Engram Agent Memory: Local Recall and Readable Truth

Engram agent memory is a local-first memory system for coding agents. The Gentleman Programming project runs as one Go binary, stores observations in SQLite, searches them with FTS5, and exposes them through MCP, HTTP, a CLI, and a terminal UI. It is a practical answer to a recurring problem: Claude Code, Codex, Cursor, and other coding agents should not rediscover the same bug, convention, or decision every session.

Engram is strongest as a fast observation and handoff layer. For durable team knowledge, pair it with files people can read, edit, review, and self-host. That creates a useful boundary: Engram recalls what happened; a readable wiki defines what remains authoritative.

First, identify the Engram you mean

The name is currently ambiguous. This guide covers Gentleman Programming's Engram, the coding-agent tool built around a local SQLite database. A separate product at engram.so describes typed memories, salience scoring, a Python SDK, REST API, and hosted OAuth MCP. They are unrelated products. Check the repository and package owner before following setup instructions or comparing features.

What the leading pages cover

The top result is Engram's repository. It documents the single-binary architecture, 14 named agent setup targets, project detection, 27 MCP tools, optional cloud replication, Git sync, conflict surfacing, session summaries, and recovery after context compaction. Its operational documentation is unusually detailed.

The second leading page, OSS Insight's “Agent Memory Race of 2026,” compares five repositories and places Engram at the low-infrastructure end: one Go binary and one SQLite file, in contrast with systems requiring vector databases, graph stores, or several runtimes. The third result is the unrelated engram.so product, which focuses on typed facts and cross-model hosted memory.

Those pages explain installation or market architecture. They do not provide the two-store authority drill below: a repeatable test for deciding which facts belong in local episodic recall, which deserve promotion into readable project truth, and whether corrections and exports still work when one memory runtime disappears.

How Engram memory works

By default, Engram stores data under ~/.engram; its SQLite database is authoritative. FTS5 provides lexical full-text search, so local operation does not require an embedding model or vector database. The MCP process usually runs over stdio. Project-aware reads resolve an explicit project first, then ENGRAM_PROJECT, then the current working directory.

Engram's operating contract is selective rather than transcript-based. Agents save decisions, fixes, discoveries, patterns, and durable constraints with mem_save; retrieve candidates with mem_search; inspect surrounding events with mem_timeline; and close work with mem_session_summary. Reusing a stable topic_key helps evolving knowledge update coherently instead of becoming a pile of near-duplicates.

On each save, Engram can surface related FTS5 candidates for judgment. An agent can mark relationships such as supersedes, conflicts_with, compatible, or scoped. That is better than silently returning two incompatible observations. It still depends on an agent or person making the right judgment.

Working Claude Code setup

Install the current stable Engram binary from its GitHub Releases page and put it on PATH. Then run:

engram setup claude-code
engram doctor

The supported setup registers a user-scoped stdio MCP server and installs or refreshes Engram's Claude Code plugin. Restart Claude Code, open a new session in the target repository, and ask it to call mem_current_project. Do not write until the returned project is correct. For deterministic repository scope, create .engram/config.json:

{
  "project_name": "payments-api"
}

Then perform a two-session check. In session one, save a harmless test decision with a stable topic key, end with mem_session_summary, and close the client. In a fresh session, search for the decision and retrieve its full observation. Delete the test afterward with the expected project assertion. This verifies project resolution, writes, persistence, retrieval, and mutation—not merely that MCP says “connected.”

Add readable project truth through MCP

SQLite observations are inspectable through Engram's tools and TUI, but they are not ordinary project documents. Decisions that teammates must review, link, edit, publish, or carry between agent products benefit from a markdown authority layer. Meshnote exposes linked Markdown wikis over MCP while keeping the underlying knowledge human-readable.

Claude Code can use both servers. Keep the real API key out of source control and add the hosted Meshnote connection to your user configuration:

{
  "mcpServers": {
    "meshnote": {
      "type": "url",
      "url": "https://meshnote.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_MESHNOTE_API_KEY>"
      }
    }
  }
}

After restarting, call list_projects, select the intended project, and use get_schema before writing. Engram remains the low-friction session memory; Meshnote becomes the reviewed home for architectural decisions, runbooks, source-backed research, and cross-agent handoffs. The broader coding-agent memory architecture explains why conversation recall and project knowledge should not be forced into one store.

Use an explicit promotion contract

Knowledge	Engram	Readable wiki
Recent debugging observation	Primary	Only if it becomes a runbook lesson
Session handoff and next step	Primary	Promote if several agents need it
Approved architecture decision	Pointer or summary	Primary, with rationale and status
Deployment procedure	Recall hint	Primary, reviewed and versioned
User preference	Useful when scoped correctly	Usually no
Research with sources	Discovery note	Primary, linked to sources

Use a simple rule: observe locally, promote deliberately, correct at the authority. Once a fact is promoted, the Engram observation should point to the wiki page rather than compete with it as an equal source. This avoids a common failure mode where retrieval returns an old local observation beside a corrected team decision.

The six-case authority-and-exit drill

Persistence: save an Engram observation, restart the client, and retrieve it in a new session.
Scope: create two repositories and prove that an unqualified search in repository B does not treat repository A's decision as current context.
Promotion: turn one accepted decision into a linked wiki page with owner, rationale, date, and source.
Correction: reverse the decision in the wiki, mark the old Engram observation as superseded, and verify a fresh agent reports only the current rule as authoritative.
Handoff: connect a second MCP-capable client and confirm it can read the promoted decision without importing the first client's transcript.
Exit: back up the SQLite file and export the wiki. Disable Engram, then prove a person can still reconstruct the approved project rules from readable files alone.

This drill measures operational trust, not benchmark trivia. Long-context recall benchmarks can reveal retrieval quality, but they do not prove tenant isolation, correction semantics, human auditability, or reconstruction after a vendor or runtime change. For more acceptance criteria, see the MCP memory server guide.

How Engram compares with other memory choices

Mem0 offers an extraction-and-retrieval memory layer with managed and self-hosted paths; it fits applications that want API-level memory across frameworks. Zep/Graphiti models temporally changing facts and relationships in a knowledge graph, which is useful when history and entity connections drive retrieval. Letta makes memory part of a stateful agent runtime and now uses git-backed memory files and shared repositories. Native ChatGPT or Claude memory is convenient for personal continuity, but it is tied to the host's product boundary and policy.

Engram is compelling when you want local coding-agent memory with modest infrastructure and strong agent integrations. A readable wiki is better when shared project truth must be directly editable, linkable, and portable. Many teams need both, not a winner-takes-all choice. The self-hosted agent memory comparison covers the broader deployment trade-offs.

Choose based on the correction path

Ask where a wrong fact is corrected, who can review that correction, and what survives if the memory service is removed. If the answer is “only through another model call,” the system is convenient but not yet a dependable knowledge authority.

Use Engram for rapid local recall and session continuity. Promote durable team knowledge into files your agents and people can inspect. Meshnote provides that agent-agnostic MCP layer as readable Markdown. Start syncing — $8/mo, or choose Self-hosted for teams from $10/seat/month.