Epicode

Give AI an Unforgettable Memory

English · 中文 · Quick Start · Docs · OpenAPI · Releases

---

Epicode is an open-source memory service for AI agents. Retrieval is BM25 plus HNSW. Memories also have a tetrahedral placement used for clustering and visualization, a knowledge graph, validity windows, and an MCP endpoint for cross-session recall. Placement is not the retrieval index.

Quick Start

The fastest way to run Epicode locally is with Docker Compose:

git clone https://github.com/sunormesky-max/epicode.git
cd epicode/deploy
cp .env.example .env
# Edit .env and add your DEEPSEEK_API_KEY and keys
docker compose up --build -d

Then store and search a memory:

curl -X POST http://127.0.0.1:8080/api/v1/remember \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"content": "Epicode gives AI persistent spatial memory"}'

# Store a memory that expires in 7 days
curl -X POST http://127.0.0.1:8080/api/v1/remember \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"content": "Sprint deadline: ship v1.0 by Friday", "ttl_seconds": 604800}'

curl -X POST http://127.0.0.1:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"query": "AI memory"}'

💡 Live demo: epicode.cn

Key Features

• Spatial placement — memories can be placed as tetrahedrons for clustering and visualization. This is not the retrieval index.
• Semantic Search — BM25 + HNSW hybrid search for natural-language retrieval.
• Knowledge Graph — automatic relationship extraction and dynamic graph updates.
• Temporal Validity — every memory supports valid_from / valid_until windows and freshness decay scoring. This is a storage/filter feature, not a claim of parity with Zep/Graphiti on a shared benchmark.
• MCP Integration — discover the current tool catalog with MCP tools/list, including memory, identity, skills, and L0 drive tools.
• L0 Active Inference — evidence-backed drive signals with REST/MCP inbox and acknowledgement flows.
• SMRP Protocol — transport-independent structured memory responses with tier, retrieval provenance, and optional topology/placement metadata.
• Multi-tenant Cloud — user management, quotas, invite codes, and admin controls.
• Self-hosted Defense — epicode-guard watches SSH/Web/honeypot traffic and auto-bans attackers.
• Observable — call-detail stats (request/retrieval/cache/decision metrics) exposed on /v1/stats.
• Benchmark — see BENCHMARK.md for quantified latency, throughput, and cache numbers.

Architecture

AI Agent → POST /api/v1/remember
    → Nginx (strips /api prefix)
    → Security middleware (API key + rate limit + energy check)
    → GatewayCenter (embedding → LLM classification → spatial placement)
    → New tetrahedron placed in Space (auto-merge nearby vertices)
    → Knowledge graph updated
    → Scheduler runs background cycles: pulse / link / dedup / dream

Read more in docs/architecture.md.

Tech Stack

Layer	Technologies
Frontend	React 19 · TypeScript · Vite 7 · Tailwind CSS
Backend	Rust · Axum · Tokio · SQLite · ONNX Runtime
Search	HNSW · BM25 · ONNX embeddings
Cognition	DeepSeek LLM API
Defense	Rust · nftables · firewalld · TCP honeypots
Deployment	Docker · Docker Compose · Kubernetes · Nginx

Local Development

# Frontend
cd frontend
npm install
npm run dev        # http://localhost:5173

# Backend
cd backend
cargo build --release
cargo test --all-targets
./target/release/epicode --cloud   # Cloud mode on :9111

See CONTRIBUTING.md for the full development setup.

Docker Deploy

cd deploy
cp .env.example .env
# fill in DEEPSEEK_API_KEY, EPICODE_ADMIN_KEY, EPICODE_MASTER_KEY
docker compose up --build -d

Visit http://127.0.0.1:8080 for the local HTTP gateway. Public deployments must put a TLS proxy in front; see docs/deployment.md.

Documentation

• Architecture — data flow, spatial model, concurrency.
• API Reference — HTTP endpoints and MCP tools.
• MCP Protocol — SMRP envelope and agent integration.
• Configuration — environment variables and keys.
• Benchmarks — performance numbers and hardware requirements.
• Deployment — Docker, Kubernetes, and bare-metal.
• Examples — curl, Node.js, and Python snippets.
• Troubleshooting — common issues and fixes.

SDK

Python

pip install epicode-sdk

from epicode import EpicodeClient

client = EpicodeClient("your-api-key")
client.remember("Project deadline is June 15.")
results = client.search("deadline")

TypeScript / JavaScript

npm install epicode-sdk

import { EpicodeClient } from "epicode-sdk";

const client = new EpicodeClient("your-api-key");
await client.remember("Deployed v2.3 to production");
const results = await client.search("production deploy");

Note: The old package name tetramem-sdk is deprecated. Please use epicode-sdk.

Community & Contributing

We welcome contributions!

• Discussions — ask questions and share ideas.
• Issues — bug reports and feature requests.
• Contributing Guide — development setup, commit style, PR process.
• Security Policy — report vulnerabilities privately.
• Roadmap — upcoming features and long-term plans.

License

Epicode is released under the MIT License.

Note on build-time dependencies. The local embedding engine (backend/src/engine/vector.rs) depends on the ort crate, which downloads a prebuilt, MIT-licensed ONNX Runtime from the official ort-rs distribution mirror (cdn.pyke.io) the first time you build the backend. This is a third-party precompiled binary, not source. To build fully from source or use a system-provided ONNX Runtime instead, set ORT_STRATEGY=system / ORT_LIB_DIR (or ORT_STRATEGY=compile) at build time. See the ort docs for details.

---

Made with ❤️ by sunormesky-max and contributors.