Engram keeps AI coding agent memory in one SQLite file, and guards writes when the server and CLI drift apart

One Go binary in front of one SQLite file

Engram's architecture is short enough to draw in four lines:

Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
    ↓ MCP stdio
Engram (single Go binary)
    ↓
SQLite + FTS5 (~/.engram/engram.db)

The agent talks to Engram over MCP on stdio, and Engram stores everything in a SQLite database with FTS5 full-text search. The same binary also exposes an HTTP API, a CLI and an interactive TUI, built with the Charm bubbletea, bubbles and lipgloss libraries. SQLite access comes from modernc.org/sqlite, and MCP from mark3labs/mcp-go. No Node.js, Python or Docker is required to run it.

The data directory defaults to ~/.engram. A nonblank ENGRAM_DATA_DIR overrides it, and it must be an absolute path; a relative value is not accepted. That single-file design is the point: backing up, moving or wiping an agent's memory means handling one database. It also means every agent and every project on the machine shares that one file unless you set ENGRAM_DATA_DIR differently per environment, which is why the project selection rules below carry so much weight.

Which project a memory belongs to is resolved, not assumed

Because all projects share one store, Engram has to decide which project a read refers to. When no selector is given, project-aware reads use the canonical current project, chosen in this order: an explicit project argument, then the ENGRAM_PROJECT environment variable, then detection from the current working directory.

To read across every project on purpose, pass --all on the CLI or all_projects=true over HTTP. Neither can be combined with an explicit project; the two are mutually exclusive. engram context keeps its positional project argument as an alias for --project. GET /sync/status works on one resolved project only and rejects all_projects=true, because its provider cannot aggregate status across projects.

The consequence is that the working directory quietly decides what an agent remembers. Launch an agent from a parent folder, a scratch directory or a different checkout of the same repository, and cwd detection can resolve to a different project from the one you expect, so recalled context looks empty or wrong. If you work across monorepo subfolders or multiple worktrees, set ENGRAM_PROJECT explicitly rather than relying on detection, and use --all only when you actually want everything.

Codex writes stay blocked until the running server proves it is new enough

Engram runs as a long-lived server that agents connect to, and the CLI that installs hooks can be newer than the server already running. For Codex, Engram refuses to guess. Mutating Engram tools require the running core's /health response to advertise capabilities.runtime_session_resolution: true before Engram resolves the host session. Advertising root_session_resume alone is not enough.

If the core is incompatible, the fix is manual and has three steps: upgrade the core to match the CLI, restart the running Engram server yourself, and start a new Codex session. Hooks never restart the server automatically. Until then, unregistered sessions and connection or invalid-response failures stay blocked, each with its own diagnostic. Read-only calls and non-Engram tool calls are unaffected.

The design protects memory from being written against the wrong session. The cost is that an upgrade can leave Codex unable to save memories until you notice and restart. Engram is shipping fast, with v3.5.4 on 2026-10-23, v3.6.0 the next day and v3.6.1 on 2026-11-03, so treat a server restart as part of every upgrade if you use Codex, and read the diagnostic before assuming the agent simply chose not to save.

Windows gets a private SQLite temp directory that Engram never cleans

On Windows, local-SQLite commands, including serve, mcp and doctor, first create and check a directory at <data-directory>/tmp/sqlite, then set TEMP and TMP to it for that process only. Your user and system environment settings and the working directory are left unchanged. If the directory cannot be used, startup fails with a diagnostic naming the operation.

The same preparation covers the cloud status, enroll, unenroll and attest-prompt-source commands, and the local-store cloud upgrade operations doctor, repair, bootstrap, remirror, status and rollback. It does not run for protocol-mode, setup, cloud serve, cloud config, the top-level cloud repair and cloud bootstrap, other cloud upgrade subcommands, or unknown commands. Linux and macOS keep their existing behaviour.

Two consequences follow. First, a Windows data directory on a location that blocks writes, or that a security tool locks down, stops Engram at startup rather than failing later inside SQLite, which is easier to diagnose. Second, the directory is shared between processes and Engram does not clean it. SQLite manages its own uniquely named temporary files there, but if something leaves files behind, removing them is your job, not Engram's.

Local by default, with cloud as a separate command tree

Engram keeps memory local by default. Moving it beyond one machine goes through a distinct set of cloud commands: enroll and unenroll, status, attest-prompt-source, cloud serve, cloud config, and a cloud upgrade group with doctor, repair, bootstrap, remirror, status and rollback.

The repository carries the pieces for a server side as well. go.mod includes pgx/v5, a PostgreSQL driver, and templ, which the Makefile uses to generate templates for internal/cloud/dashboard. There are docker-compose.cloud.yml and docker-compose.beta.yml files at the top level, and a docs/RELEASE-STAGING.md page for candidate staging.

For the reader, the split matters in both directions. The local path really is one binary and one file, with no service to run. The cloud path is not: it has its own enrollment, its own upgrade and rollback commands, and its own deployment files. The zero dependencies claim describes the local binary, so if you want memory to follow you across machines or a team, plan for running and maintaining that second piece and read DOCS.md before committing to it.

Fourteen agent targets, each wired its own way

Engram lists 14 setup targets: Claude Code, Pi, OpenCode, Gemini CLI, Codex, Antigravity, Windsurf, Qwen Code, Kiro, Cursor, VS Code with Copilot, Kilo Code, Kimi Code and CommandCode, plus any other MCP-compatible agent. Each has its own section in docs/AGENT-SETUP.md.

The repository also carries agent-specific packaging: a .claude-plugin/ directory, a plugin/ directory, a skills/ directory and a setup.sh script at the top level. The shared protocol is MCP over stdio, so the core behaviour is the same, but how the server gets registered, and whether hooks are involved, differs per agent. Codex is the clearest example, with its session-resolution gate.

The consequence is that agent-agnostic describes the storage, not the setup. Switching agents does not require migrating memory, which is the real advantage of one SQLite file. It does require following a different setup section each time, and an agent that is MCP-compatible but not in the list of 14 is on the generic path without a dedicated guide. If you use two agents side by side, set both up against the same data directory, or you end up with two separate memories.

Strict contributor gates and a trademarked name on MIT code

The code is MIT licensed, but the name is marked Engram™ and the repository has a TRADEMARKS.md beside LICENSE. If you plan to ship a fork or a hosted service, read the trademark file before reusing the name; the code licence does not settle that question by itself.

The Go module path is github.com/Gentleman-Programming/engram/v3 and targets Go 1.26.10. Contributing comes with tight checks. make lint requires golangci-lint at exactly version 2.13.2 and fails with a message if a different version is on PATH, then lints only changes since HEAD~. Performance and dead code are ratcheted against committed baselines, .perf-baseline.txt and .deadcode-baseline.txt, through scripts/perf-ratchet.sh and scripts/deadcode-ratchet.sh. Templates are regenerated with this target:

go tool templ generate -path ./internal/cloud/dashboard

For contributors this means a precise toolchain before the first pull request, and a change that slows a measured path or adds unused code is caught by the ratchet. For users, it is a sign that regressions are checked mechanically, though it says nothing about how stable the storage format is across the rapid v3.x releases; read CHANGELOG.md before upgrading.

Editorial conclusion

Engram fits developers who move between coding agents and want one local, searchable memory store without running Node.js, Python or Docker. It is a poorer fit if you need memory shared across machines with no extra setup, or if you run Codex and cannot restart the Engram server when the CLI updates. Before relying on it, check how your agent is wired in docs/AGENT-SETUP.md and which project your working directory resolves to.

Frequently asked questions

Official sources

1. Gentleman-Programming/engram on GitHub
2. License: MIT
3. Project website
4. README
5. Releases