|
| 1 | +[← Back to README](../README.md) |
| 2 | + |
| 3 | +# Engram Codebase Guide |
| 4 | + |
| 5 | +**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.** |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## 90-second mental model |
| 10 | + |
| 11 | +```text |
| 12 | +Coding agent |
| 13 | + Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / Cursor / Windsurf |
| 14 | + │ |
| 15 | + │ MCP stdio, plugin hooks, or local API |
| 16 | + ▼ |
| 17 | +cmd/engram |
| 18 | + CLI + local runtime + cloud runtime |
| 19 | + │ |
| 20 | + ├── internal/mcp mem_* tools for agents |
| 21 | + ├── internal/server local JSON API: engram serve |
| 22 | + ├── internal/tui Bubbletea terminal UI |
| 23 | + ├── internal/setup automated integration installation |
| 24 | + │ |
| 25 | + ▼ |
| 26 | +internal/store |
| 27 | + SQLite + FTS5 + sessions + observations + prompts + relations + sync mutations |
| 28 | + │ |
| 29 | + ├── internal/sync git-friendly chunks / transport |
| 30 | + └── internal/cloud/autosync optional background push/pull |
| 31 | + │ |
| 32 | + ▼ |
| 33 | + internal/cloud/remote ── HTTP ── engram cloud serve |
| 34 | + │ |
| 35 | + ├── internal/cloud/cloudserver |
| 36 | + ├── internal/cloud/cloudstore Postgres |
| 37 | + ├── internal/cloud/dashboard HTML/HTMX |
| 38 | + └── internal/cloud/auth bearer + dashboard session |
| 39 | +``` |
| 40 | + |
| 41 | +The sentence that organizes the whole repo: |
| 42 | + |
| 43 | +> **Local SQLite is the source of truth. Cloud is opt-in replication and shared access, not the owner of the data.** |
| 44 | +
|
| 45 | +## Recommended reading path |
| 46 | + |
| 47 | +| Step | Page | Read this when... | |
| 48 | +|---|---|---| |
| 49 | +| 1 | [Mental Model](codebase/mental-model.md) | You need the product shape before opening code. | |
| 50 | +| 2 | [Repository Map](codebase/repository-map.md) | You need to decide which package owns a change. | |
| 51 | +| 3 | [Memory Core](codebase/memory-core.md) | You are touching SQLite, FTS5, prompts, observations, sessions, relations, or sync mutations. | |
| 52 | +| 4 | [Interfaces](codebase/interfaces.md) | You are changing CLI, MCP, local API, or TUI behavior. | |
| 53 | +| 5 | [Sync and Cloud](codebase/sync-and-cloud.md) | You are changing chunks, remote sync, autosync, transport, or cloud persistence. | |
| 54 | +| 6 | [Dashboard](codebase/dashboard.md) | You are changing browser UI, HTMX partials, cloud dashboard routes, or dashboard policy controls. | |
| 55 | +| 7 | [Integrations](codebase/integrations.md) | You are changing agent setup, plugins, or MCP configuration docs. | |
| 56 | +| 8 | [Maintainer Playbook](codebase/maintainer-playbook.md) | You are reviewing a PR or planning a large change. | |
| 57 | +| 9 | [Reference Map](codebase/reference-map.md) | You need a traceable appendix from docs/source files to purpose. | |
| 58 | + |
| 59 | +## Quick map: if you need X, read Y |
| 60 | + |
| 61 | +| If you need to... | Open first | Then check | |
| 62 | +|---|---|---| |
| 63 | +| Understand the product in 5 minutes | `README.md` | [Mental Model](codebase/mental-model.md) | |
| 64 | +| See the full technical reference | `DOCS.md` | This guide for ownership and guardrails | |
| 65 | +| Change MCP tools | `internal/mcp/mcp.go` | [Interfaces](codebase/interfaces.md), `internal/mcp/*_test.go`, `docs/AGENT-SETUP.md` | |
| 66 | +| Change local persistence | `internal/store/store.go` | [Memory Core](codebase/memory-core.md), `internal/store/*_test.go`, `DOCS.md#database-schema` | |
| 67 | +| Change the local API | `internal/server/server.go` | [Interfaces](codebase/interfaces.md), `internal/server/*_test.go`, `DOCS.md#http-api-endpoints` | |
| 68 | +| Change chunk sync | `internal/sync/sync.go` | [Sync and Cloud](codebase/sync-and-cloud.md), `internal/sync/*_test.go`, `README.md#git-sync` | |
| 69 | +| Change cloud autosync | `internal/cloud/autosync/manager.go` | [Sync and Cloud](codebase/sync-and-cloud.md), `internal/cloud/remote/transport.go`, `DOCS.md#cloud-autosync` | |
| 70 | +| Change the dashboard | `internal/cloud/dashboard/dashboard.go` | [Dashboard](codebase/dashboard.md), `internal/cloud/dashboard/*_templ.go`, `internal/cloud/dashboard/static/styles.css` | |
| 71 | +| Change agent setup | `internal/setup/setup.go` | [Integrations](codebase/integrations.md), `plugin/`, `docs/AGENT-SETUP.md`, `docs/PLUGINS.md` | |
| 72 | +| Prepare or review a large feature | `openspec/changes/*` | [Maintainer Playbook](codebase/maintainer-playbook.md), `openspec/specs/*`, `CONTRIBUTING.md` | |
| 73 | + |
| 74 | +## Full technical reference stays in DOCS.md |
| 75 | + |
| 76 | +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](../DOCS.md). |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +[Next: Mental Model →](codebase/mental-model.md) |
0 commit comments