Bitemporal, graph-backed memory system for AI coding agents. Captures reasoning traces from Claude Code, Codex CLI, and others into a knowledge graph with full temporal history.
engram_preview.webm
# Prerequisites: Bun v1.3.5+, Docker, Python 3.12+ with uv
git clone https://github.com/ccheney/engram.git
cd engram
bun install
bun run infra:up # Start FalkorDB, Qdrant, NATS, PostgreSQL
bun run dev # Start all servicesVerify: Observatory http://localhost:6178 | API http://localhost:6174/v1/health
CLI Agents → Ingestion (6175) → NATS → Memory → FalkorDB
↓
Search (6176) → Qdrant
↓
Neural Observatory (6178)
Storage: FalkorDB (graph), Qdrant (vectors), NATS+JetStream (events), PostgreSQL (API keys/usage)
Bitemporal: All graph nodes track vt_start/vt_end (valid time) and tt_start/tt_end (transaction time) for time-travel queries.
| App | Port | Purpose |
|---|---|---|
| api | 6174 | REST API - memory ops, OAuth, rate limiting, OpenTofu state backend |
| ingestion | 6175 | Event parsing from 8+ providers, PII redaction |
| mcp | stdio | MCP server - remember/recall/query/context tools |
| memory | - | Graph persistence, turn aggregation, NATS consumer |
| observatory | 6178 | Next.js 16 real-time session visualization |
| console | 6185 | Next.js 16 infrastructure management console |
| search | 6176 | Python/FastAPI hybrid search, multi-tier reranking |
| tuner | 6177 | Python/FastAPI Optuna hyperparameter optimization |
| Package | Purpose |
|---|---|
| benchmark | LongMemEval/MTEB/BEIR evaluation suite (Python) |
| common | Utilities, errors, constants, test fixtures |
| engram-plugin | Claude Code plugin for memory commands |
| events | Zod schemas for RawStreamEvent/ParsedStreamEvent |
| graph | Bitemporal models, repositories, QueryBuilder |
| infra | OpenTofu IaC for Hetzner Cloud deployment |
| logger | Pino structured logging with PII redaction |
| parser | Provider parsers, extractors, redaction |
| storage | FalkorDB, NATS, PostgreSQL, Redis, blob clients |
| temporal | Rehydrator, TimeTravelService, ReplayEngine |
| tsconfig | Shared TypeScript 7 configuration |
| tuner | TypeScript client/CLI for tuner service |
| vfs | VirtualFileSystem, NodeFileSystem, PatchManager |
# Development
bun run dev # Start all services
bun run infra:up # Start infrastructure (Docker)
bun run infra:down # Stop infrastructure# Build & Test
bun run build # Build all packages
bun run test# Run Vitest tests
bun run typecheck # TypeScript validation
bun run lint # Biome linting
bun run format # Biome formatting# Python servicescd apps/search && uv sync && uv run search
cd apps/tuner && uv sync && uv run tuner| Tool | Purpose |
|---|---|
remember | Store memory with type (decision/insight/preference/fact) and tags |
recall | Retrieve memories via hybrid semantic/keyword search |
query | Execute read-only Cypher queries (local mode) |
context | Comprehensive context assembly for tasks (local mode) |
summarize | Condense text using client LLM (requires sampling) |
extract_facts | Parse text into atomic facts (requires sampling) |
enrich_memory | Auto-generate summary/keywords/category (requires sampling) |
| Endpoint | Method | Scope | Purpose |
|---|---|---|---|
/v1/health | GET | Public | Health check |
/v1/memory/remember | POST | memory:write | Store memory with deduplication |
/v1/memory/recall | POST | memory:read | Hybrid search with reranking |
/v1/memory/query | POST | query:read | Read-only Cypher queries |
/v1/memory/context | POST | memory:read | Context assembly |
/v1/tofu | GET/POST | state:write | OpenTofu remote state |
Ingestion supports 8+ LLM providers:
| Provider | Key | Aliases |
|---|---|---|
| Anthropic | anthropic | claude |
| OpenAI | openai | gpt, gpt-4 |
| Google Gemini | gemini | - |
| XAI (Grok) | xai | grok |
| Claude Code | claude_code | claude-code |
| Cline | cline | - |
| Codex | codex | - |
| OpenCode | opencode | - |
All services use Kaprekar's constant (6174) as the base port.
| Service | Port | Category |
|---|---|---|
| API | 6174 | Service |
| Ingestion | 6175 | Service |
| Search | 6176 | Service |
| Tuner | 6177 | Service |
| Observatory | 6178 | Service |
| FalkorDB | 6179 | Database |
| Qdrant | 6180 | Database |
| NATS | 6181 | Database |
| NATS Monitor | 6182 | Dev Tool |
| PostgreSQL | 6183 | Database |
| Optuna Dashboard | 6184 | Dev Tool |
| Console | 6185 | Service |
- TypeScript: Bun runtime, TypeScript 7 (tsgo), Biome
- Python: uv, Ruff, FastAPI, Optuna, sentence-transformers
- Graph: FalkorDB (Redis-based graph DB)
- Vectors: Qdrant with BGE/SPLADE embeddings
- Messaging: NATS JetStream
- Frontend: Next.js 16, React 19, React Flow
- Auth: OAuth 2.1 with RFC 7662 token introspection
All services require OAuth authentication in local development for production parity. See Local OAuth Setup Guide for detailed configuration.
Quick start:
# Configure environment (copy template)
cp .env.local.example .env
# Start all services with OAuth
bun run infra:up
# Verify OAuth server
curl http://localhost:6178/api/healthObservatory (port 6178) acts as the OAuth authorization server. All services (search, tuner, api, memory, ingestion) authenticate via token introspection.
AGPL-3.0