Epicode

Give AI an Unforgettable Memory

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

Epicode 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.

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://localhost: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://localhost: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://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"query": "AI memory"}'

💡 Live demo: epicode.cn · Dashboard screenshot will be added in a follow-up PR.

Key Features

• Spatial Memory — memories stored as tetrahedrons in 3D space for natural clustering.
• 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, enabling time-aware recall (on par with Zep/Graphiti's core capability).
• MCP Integration — 35 standardized tools for any MCP-compatible AI agent.
• SMRP Protocol — structured memory responses with topology and 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

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://localhost:8080. For production details, 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.