← Back to README

Engram Codebase Guide

This guide is for maintainers and contributors who need to understand where Engram responsibilities live, which invariants are non-negotiable, and which file to open when something needs to change.

Engram is a local-first persistent memory system for coding agents. The center of the product is a Go binary that writes to SQLite + FTS5; the CLI, MCP, HTTP API, TUI, plugins, sync, cloud, and dashboard are interfaces around that core.

90-second mental model

Coding agent
  Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / Cursor / Windsurf
        │
        │ MCP stdio, plugin hooks, or local API
        ▼
cmd/engram
  CLI + local runtime + cloud runtime
        │
        ├── internal/mcp        mem_* tools for agents
        ├── internal/server     local JSON API: engram serve
        ├── internal/tui        Bubbletea terminal UI
        ├── internal/setup      automated integration installation
        │
        ▼
internal/store
  SQLite + FTS5 + sessions + observations + prompts + relations + sync mutations
        │
        ├── internal/sync                   git-friendly chunks / transport
        └── internal/cloud/autosync         optional background push/pull
                │
                ▼
        internal/cloud/remote ── HTTP ── engram cloud serve
                                      │
                                      ├── internal/cloud/cloudserver
                                      ├── internal/cloud/cloudstore  Postgres
                                      ├── internal/cloud/dashboard   HTML/HTMX
                                      └── internal/cloud/auth        bearer + dashboard session

The sentence that organizes the whole repo:

Local SQLite is the source of truth. Cloud is opt-in replication and shared access, not the owner of the data.

Recommended reading path

Step	Page	Read this when...
1	Mental Model	You need the product shape before opening code.
2	Repository Map	You need to decide which package owns a change.
3	Memory Core	You are touching SQLite, FTS5, prompts, observations, sessions, relations, or sync mutations.
4	Interfaces	You are changing CLI, MCP, local API, or TUI behavior.
5	Sync and Cloud	You are changing chunks, remote sync, autosync, transport, or cloud persistence.
6	Dashboard	You are changing browser UI, HTMX partials, cloud dashboard routes, or dashboard policy controls.
7	Integrations	You are changing agent setup, plugins, or MCP configuration docs.
8	Maintainer Playbook	You are reviewing a PR or planning a large change.
9	Reference Map	You need a traceable appendix from docs/source files to purpose.

Quick map: if you need X, read Y

If you need to...	Open first	Then check
Understand the product in 5 minutes	README.md	Mental Model
See the full technical reference	DOCS.md	This guide for ownership and guardrails
Change MCP tools	internal/mcp/mcp.go	Interfaces, internal/mcp/*_test.go, docs/AGENT-SETUP.md
Change local persistence	internal/store/store.go	Memory Core, internal/store/*_test.go, DOCS.md#database-schema
Change the local API	internal/server/server.go	Interfaces, internal/server/*_test.go, DOCS.md#http-api-endpoints
Change chunk sync	internal/sync/sync.go	Sync and Cloud, internal/sync/*_test.go, README.md#git-sync
Change cloud autosync	internal/cloud/autosync/manager.go	Sync and Cloud, internal/cloud/remote/transport.go, DOCS.md#cloud-autosync
Change the dashboard	internal/cloud/dashboard/dashboard.go	Dashboard, internal/cloud/dashboard/*_templ.go, internal/cloud/dashboard/static/styles.css
Change agent setup	internal/setup/setup.go	Integrations, plugin/, docs/AGENT-SETUP.md, docs/PLUGINS.md
Prepare or review a large feature	openspec/changes/*	Maintainer Playbook, openspec/specs/*, CONTRIBUTING.md

Full technical reference stays in DOCS.md

This guide explains ownership, flows, and guardrails. It intentionally does not duplicate the complete API reference. For endpoints, schemas, MCP parameters, and CLI flags, use DOCS.md.

---

Next: Mental Model →