{"id":51284802,"url":"https://github.com/sunormesky-max/epicode","last_synced_at":"2026-06-30T04:30:40.899Z","repository":{"id":363782863,"uuid":"1264892380","full_name":"sunormesky-max/epicode","owner":"sunormesky-max","description":"Epicode - AI Memory Operating System. Spatial AI memory with knowledge graph, MCP integration, and auto-defense.","archived":false,"fork":false,"pushed_at":"2026-06-27T02:15:51.000Z","size":2048,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T03:18:14.800Z","etag":null,"topics":["ai","axum","knowledge-graph","mcp","memory","react","rust","spatial","sqlite","vector-database"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sunormesky-max.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":".github/GOVERNANCE.md","roadmap":"ROADMAP.md","authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["sunormesky-max"]}},"created_at":"2026-06-10T09:17:20.000Z","updated_at":"2026-06-27T02:15:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sunormesky-max/epicode","commit_stats":null,"previous_names":["sunormesky-max/epicode"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sunormesky-max/epicode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunormesky-max%2Fepicode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunormesky-max%2Fepicode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunormesky-max%2Fepicode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunormesky-max%2Fepicode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sunormesky-max","download_url":"https://codeload.github.com/sunormesky-max/epicode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunormesky-max%2Fepicode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34952850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","axum","knowledge-graph","mcp","memory","react","rust","spatial","sqlite","vector-database"],"created_at":"2026-06-30T04:30:39.910Z","updated_at":"2026-06-30T04:30:40.872Z","avatar_url":"https://github.com/sunormesky-max.png","language":"Rust","funding_links":["https://github.com/sponsors/sunormesky-max"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Epicode\n\n## Give AI an Unforgettable Memory\n\n[![CI](https://github.com/sunormesky-max/epicode/actions/workflows/ci.yml/badge.svg)](https://github.com/sunormesky-max/epicode/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Version](https://img.shields.io/github/v/release/sunormesky-max/epicode)](https://github.com/sunormesky-max/epicode/releases)\n[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker)](deploy/docker-compose.yml)\n[![Rust](https://img.shields.io/badge/Rust-1.88+-orange?logo=rust)](https://www.rust-lang.org/)\n[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://react.dev/)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/v2/github.com/sunormesky-max/epicode/badge)](https://securityscorecards.dev/viewer/?uri=github.com/sunormesky-max/epicode)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-blue)](SECURITY.md)\n[![Contributions Welcome](https://img.shields.io/badge/Contributions-Welcome-brightgreen)](CONTRIBUTING.md)\n\n[![GitHub stars](https://img.shields.io/github/stars/sunormesky-max/epicode?style=social)](https://github.com/sunormesky-max/epicode/stargazers)\n[![GitHub Discussions](https://img.shields.io/github/discussions/sunormesky-max/epicode)](https://github.com/sunormesky-max/epicode/discussions)\n[![Docs](https://img.shields.io/badge/Docs-epicode.cn-success)](https://epicode.cn/#/docs)\n[![Live Demo](https://img.shields.io/badge/Live-epicode.cn-2ea44f)](https://epicode.cn)\n\n[English](README.md) · [中文](README.zh.md) · [Quick Start](#quick-start) · [Docs](docs/) · [OpenAPI](backend/docs/openapi.yaml) · [Releases](https://github.com/sunormesky-max/epicode/releases)\n\n\u003c/div\u003e\n\n---\n\nEpicode is an **open-source spatial AI memory system**. It stores AI memories as tetrahedrons in continuous 3D space, automatically extracts relationships into a knowledge graph, and gives AI agents persistent, cross-session memory.\n\n## Quick Start\n\nThe fastest way to run Epicode locally is with Docker Compose:\n\n```bash\ngit clone https://github.com/sunormesky-max/epicode.git\ncd epicode/deploy\ncp .env.example .env\n# Edit .env and add your DEEPSEEK_API_KEY and keys\ndocker compose up --build -d\n```\n\nThen store and search a memory:\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/remember \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-api-key\" \\\n  -d '{\"content\": \"Epicode gives AI persistent spatial memory\", \"labels\": [\"ai\", \"memory\"]}'\n\ncurl -X POST http://localhost:8080/api/v1/search \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-api-key\" \\\n  -d '{\"query\": \"AI memory\"}'\n```\n\n\u003e 💡 **Live demo:** [epicode.cn](https://epicode.cn) · Dashboard screenshot will be added in a follow-up PR.\n\n## Key Features\n\n- **Spatial Memory** — memories stored as tetrahedrons in 3D space for natural clustering.\n- **Semantic Search** — BM25 + HNSW hybrid search for natural-language retrieval.\n- **Knowledge Graph** — automatic relationship extraction and dynamic graph updates.\n- **MCP Integration** — 35 standardized tools for any MCP-compatible AI agent.\n- **SMRP Protocol** — structured memory responses with topology and placement metadata.\n- **Multi-tenant Cloud** — user management, quotas, invite codes, and admin controls.\n- **Self-hosted Defense** — `epicode-guard` watches SSH/Web/honeypot traffic and auto-bans attackers.\n\n## Architecture\n\n```text\nAI Agent → POST /api/v1/remember\n    → Nginx (strips /api prefix)\n    → Security middleware (API key + rate limit + energy check)\n    → GatewayCenter (embedding → LLM classification → spatial placement)\n    → New tetrahedron placed in Space (auto-merge nearby vertices)\n    → Knowledge graph updated\n    → Scheduler runs background cycles: pulse / link / dedup / dream\n```\n\nRead more in [docs/architecture.md](docs/architecture.md).\n\n## Tech Stack\n\n| Layer | Technologies |\n|-------|--------------|\n| Frontend | React 19 · TypeScript · Vite 7 · Tailwind CSS |\n| Backend | Rust · Axum · Tokio · SQLite · ONNX Runtime |\n| Search | HNSW · BM25 · ONNX embeddings |\n| Cognition | DeepSeek LLM API |\n| Defense | Rust · nftables · firewalld · TCP honeypots |\n| Deployment | Docker · Docker Compose · Kubernetes · Nginx |\n\n## Local Development\n\n```bash\n# Frontend\ncd frontend\nnpm install\nnpm run dev        # http://localhost:5173\n\n# Backend\ncd backend\ncargo build --release\ncargo test --all-targets\n./target/release/epicode --cloud   # Cloud mode on :9111\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development setup.\n\n## Docker Deploy\n\n```bash\ncd deploy\ncp .env.example .env\n# fill in DEEPSEEK_API_KEY, EPICODE_ADMIN_KEY, EPICODE_MASTER_KEY\ndocker compose up --build -d\n```\n\nVisit `http://localhost:8080`. For production details, see [docs/deployment.md](docs/deployment.md).\n\n## Documentation\n\n- [Architecture](docs/architecture.md) — data flow, spatial model, concurrency.\n- [API Reference](docs/api-reference.md) — HTTP endpoints and MCP tools.\n- [MCP Protocol](docs/mcp-protocol.md) — SMRP envelope and agent integration.\n- [Configuration](docs/configuration.md) — environment variables and keys.\n- [Benchmarks](docs/benchmarks.md) — performance numbers and hardware requirements.\n- [Deployment](docs/deployment.md) — Docker, Kubernetes, and bare-metal.\n- [Examples](docs/examples.md) — curl, Node.js, and Python snippets.\n- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes.\n\n## SDK\n\n### Python\n\n```bash\npip install epicode-sdk\n```\n\n```python\nfrom epicode import EpicodeClient\n\nclient = EpicodeClient(\"your-api-key\")\nclient.remember(\"Project deadline is June 15.\")\nresults = client.search(\"deadline\")\n```\n\n### TypeScript / JavaScript\n\n```bash\nnpm install epicode-sdk\n```\n\n```typescript\nimport { EpicodeClient } from \"epicode-sdk\";\n\nconst client = new EpicodeClient(\"your-api-key\");\nawait client.remember(\"Deployed v2.3 to production\");\nconst results = await client.search(\"production deploy\");\n```\n\n\u003e **Note:** The old package name `tetramem-sdk` is deprecated. Please use `epicode-sdk`.\n\n## Community \u0026 Contributing\n\nWe welcome contributions!\n\n- [Discussions](https://github.com/sunormesky-max/epicode/discussions) — ask questions and share ideas.\n- [Issues](https://github.com/sunormesky-max/epicode/issues) — bug reports and feature requests.\n- [Contributing Guide](CONTRIBUTING.md) — development setup, commit style, PR process.\n- [Security Policy](SECURITY.md) — report vulnerabilities privately.\n- [Roadmap](ROADMAP.md) — upcoming features and long-term plans.\n\n## License\n\nEpicode is released under the [MIT License](LICENSE).\n\n\u003e **Note on build-time dependencies.** The local embedding engine\n\u003e (`backend/src/engine/vector.rs`) depends on the [`ort`](https://crates.io/crates/ort)\n\u003e crate, which downloads a prebuilt, **MIT-licensed** [ONNX Runtime](https://github.com/microsoft/onnxruntime)\n\u003e from the official `ort-rs` distribution mirror (`cdn.pyke.io`) the first time\n\u003e you build the backend. This is a third-party precompiled binary, not source.\n\u003e To build fully from source or use a system-provided ONNX Runtime instead,\n\u003e set `ORT_STRATEGY=system` / `ORT_LIB_DIR` (or `ORT_STRATEGY=compile`) at build\n\u003e time. See the [`ort` docs](https://docs.rs/ort) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n[![Star History Chart](https://api.star-history.com/svg?repos=sunormesky-max/epicode\u0026type=Date)](https://star-history.com/#sunormesky-max/epicode\u0026Date)\n\n**Made with ❤️ by [sunormesky-max](https://github.com/sunormesky-max) and contributors.**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunormesky-max%2Fepicode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsunormesky-max%2Fepicode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunormesky-max%2Fepicode/lists"}