Status: pre-alpha. The event core works (M1) and so does the query engine (M2):
engram init / add / list / show / search / status / rebuildstore and query real, typed, replayable memories — including time travel (show --at). The markdown/git export, proposals, the AI pipeline, and the surfaces land milestone by milestone (roadmap).
engram is a local-first, user-owned memory engine for AI assistants. It lets ChatGPT, Claude, Gemini, Cursor, Copilot, Ollama, and anything else that speaks MCP or REST share a single persistent memory that you own — as an event log you can replay, a SQLite database you can query, and a git repository of markdown files you can read, grep, and take anywhere.
Two principles govern everything here:
- AI proposes; events decide. No model is ever authoritative — automation can only open proposals; only approved events change memory (ADR-0011/0012).
- Boringly trustworthy. Not flashy, not magical: every action is explainable, reproducible, versioned, and reversible. If you ever wonder "why did it do that?", the system can answer (ADR-0015).
Three storage concerns, three canonical layers (ADR-0001):
Conversations / Assistants / CLI / Web
│ commands
▼
Memory Engine (application services)
│ appends
▼
EVENT LOG — append-only, system of record (SQLite)
│ projected into
┌──────────┼──────────────────┐
▼ ▼ ▼
SQLite Search index Markdown export
state (FTS / vectors, (.md + frontmatter)
tables later) │
(canonical runtime state) ▼
Git repository
(canonical history, portable, user-owned)
- SQLite is the canonical runtime state. Search, graph traversal, decay, dedup, and analytics are database problems, so state lives in a database.
- Markdown is the canonical portable representation. Every memory is exported as a human-readable file with YAML frontmatter.
- Git is the canonical history. Exports are committed; the event log is also exported as
NDJSON, so
git clone+engram rebuildlosslessly reconstitutes the database anywhere. - Event-sourced from day 1 (ADR-0002): state changes
are immutable events (
MemoryCreated,MemoryEdited, …). Undo, audit, timelines, and replay come from the architecture, not from features.
| Path | What it is |
|---|---|
libs/engram-events |
Kernel: event envelope, registry, bus/store/projection contracts. Zero dependencies. |
libs/engram-core |
Domain aggregates, value objects, ports; application command/query services. |
libs/engram-storage-sqlite |
Canonical store: SQLModel event store + state projections + Alembic migrations. |
libs/engram-export-git |
Markdown/NDJSON export projector, git committer, inbound reconciler. |
libs/engram-intelligence |
AI layer: ingestion pipeline contracts, LLM provider port (SDKs confined to providers/), versioned prompts, eval harness. |
libs/engram-observatory |
Explainability: the audit graph answering "why did it do that?" (decision traces, not logs). |
evaluations/ |
Golden cases + synthetic corpus spec + the committed quality baseline. |
apps/api |
FastAPI REST server (thin shell over application services). |
apps/cli |
engram command-line interface (Typer). |
apps/mcp |
MCP server (stub — milestone M6). |
apps/web |
Next.js 15 dashboard. |
packages/api-client |
TypeScript client generated from the OpenAPI contract. |
docs/ |
Architecture, ADRs, conventions, roadmap. Start with docs/architecture.md. |
Prerequisites: Node 22+, pnpm 9+, uv (uv installs Python 3.13 for you).
pnpm install # JS workspace
uv sync --all-packages # Python workspace (fetches Python 3.13 if needed)
uv run engram init # create your memory space (~/.engram)
uv run engram add fact "I prefer dark mode" -t ui
uv run engram add project myapp --attr name=myapp --attr status=active
uv run engram list
uv run engram search "kind:project status:active dark mode" # the query language
uv run engram show <id> # full state + event timeline
uv run engram show <id> --version 1 # time travel: the memory as it first existed
uv run engram status # event log totals + projection drift detection
uv run engram rebuild # drop projections, replay the log — same state
pnpm dev # API on :8000, web on :3000 (route stubs until M7)Everything runs locally. No Docker required (compose files exist for convenience), no cloud, no accounts, no telemetry.
- Architecture — the full picture, including a self-critique
- The Memory Model — twelve typed kinds + the justification spine
- Intelligence — ingestion pipeline, provider port, prompts, evals
- Domain model · Events · Data flow
- REST API · Conventions · Operations
- Security · Roadmap · ADRs
See CONTRIBUTING.md. The one rule you cannot break: imports point
inward (apps → adapters → core → events) — CI enforces it with import-linter.