Gentleman-Programming · Trending

Gentleman-Programming/engram

Persistent memory system for AI coding agents. Agent-agnostic Go binary with SQLite + FTS5, MCP server, HTTP API, CLI, and TUI.

View on GitHub Website / Demo Back to listing

7.2kstars 743forks 56contributors Go

README.md

View on GitHub

<a id="top"></a>

<h1>Engram™</h1>

<p><strong>Persistent memory for AI coding agents.</strong></p>

<p>
<a href="https://engram.gentlemanprogramming.com/"><strong>Website</strong></a> &bull;
<a href="#get-started"><strong>Quickstart</strong></a> &bull;
<a href="DOCS.md"><strong>Docs</strong></a> &bull;
<a href="https://gentle-ai.gentlemanprogramming.com/"><strong>Gentle-AI</strong></a> &bull;
<a href="https://gentle-ai-wiki.gentlemanprogramming.com/"><strong>Wiki</strong></a>
</p>

<br/>

<p>
<strong>engram</strong> <code>/ˈen.ɡræm/</code> — <em>neuroscience</em>: the physical trace of a memory in the brain.
</p>

<p>
Your AI coding agent forgets everything when the session ends.
<strong>Engram gives it a brain.</strong>
</p>

<p><sub>One brain. Local or cloud. Agent-agnostic, single binary, zero dependencies.</sub></p>

<br/>

<sub><strong>If Engram saved you from re-explaining your project, a star helps other people find it.</strong></sub>

<br/>

<sub><strong>WORKS WITH THE AGENT YOU ALREADY HAVE</strong></sub>

<strong><a href="docs/AGENT-SETUP.md#claude-code">Claude Code</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#pi">Pi</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#opencode">OpenCode</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#gemini-cli">Gemini CLI</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#codex">Codex</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#antigravity">Antigravity</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#windsurf">Windsurf</a></strong><br/>
<strong><a href="docs/AGENT-SETUP.md#qwen-code">Qwen Code</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#kiro">Kiro</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#cursor">Cursor</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#vs-code-copilot--claude-code-extension">VS Code (Copilot)</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#kilo-code">Kilo Code</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#kimi-code">Kimi Code</a></strong> ·
<strong><a href="docs/AGENT-SETUP.md#commandcode">CommandCode</a></strong>

<sub>14 setup targets · plus any MCP-compatible agent · <a href="docs/AGENT-SETUP.md">per-agent setup →</a></sub>

</div>

## Features

---

### One binary — Memory without a stack

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

Codex mutating Engram tools require the running core's `/health` response to advertise `capabilities.runtime_session_resolution: true` before resolving the host session. `root_session_resume` alone is not sufficient. If the core is incompatible, upgrade it to match the CLI, manually restart the running Engram server, and start a new Codex session. Hooks never restart the server automatically. Unregistered sessions and connection or invalid-response failures remain safely blocked with distinct diagnostics; read-only and non-Engram calls are unaffected.

A **Go binary** with SQLite + FTS5 full-text search, exposed through CLI, HTTP API, MCP, and an interactive TUI. It works with any MCP-compatible agent, including Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, and Windsurf. No Node.js, Python, or Docker is required: one binary, one SQLite file.

**[Docs →](docs/ARCHITECTURE.md)**

---

### Project-aware — The right memory for the right repo

Project-aware reads use the canonical current project when no selector is supplied: an explicit project, then `ENGRAM_PROJECT`, then cwd detection. Use `--all` in the CLI or `all_projects=true` in HTTP for an intentional global read; do not combine either with an explicit project. `engram context` retains its positional project as an alias for `--project`. `GET /sync/status` supports one resolved project and rejects `all_projects=true` because its provider cannot aggregate status.

**[Docs →](DOCS.md#mcp-project-resolution)**

---

### Local first — Portable when needed

Engram keeps memory local by default. The local SQLite database is authoritative; Git Sync exports portable compressed chunks for sharing across machines, and Engram Cloud is optional, project-scoped replication/shared access with browser visibility.

| Need | Start here |
| --- | --- |
| Local memory and the runtime model | [Architecture](docs/ARCHITECTURE.md) |
| Share memory with Git | [Git Sync reference](DOCS.md#git-sync-chunked) |
| Use optional Cloud replication | [Engram Cloud](docs/engram-cloud/README.md) |
| Diagnose or recover Cloud operations | [Cloud troubleshooting](docs/engram-cloud/troubleshooting.md) |

For an existing local database, use the guided upgrade sequence. If the dry run reports changes, apply them before bootstrap; otherwise continue directly to bootstrap.

```bash
engram cloud upgrade doctor --project <project>
engram cloud upgrade repair --project <project> --dry-run
engram cloud upgrade repair --project <project> --apply # only when the dry run reports changes
engram cloud upgrade bootstrap --project <project>
engram cloud upgrade status --project <project>
```

**[Docs →](DOCS.md#cloud-upgrade-flow)**

---

### Terminal UI — Browse what your agent remembers

```bash
engram tui
```

Navigate with `j`/`k`, use `Enter` to drill in, `c` to copy content to the clipboard, `/` to search, and `Esc` to go back. The TUI uses the Catppuccin Mocha theme.

**[Docs →](DOCS.md#terminal-ui-tui)**

---

### Also in the box

> **Every command, environment variable, and endpoint: [Full reference →](DOCS.md)**

## Get started

### Install

For production use and security support, install the latest stable release from [GitHub Releases](https://github.com/Gentleman-Programming/engram/releases). Release candidates are prerelease validation and feedback builds; choose one only when you accept prerelease risk. See the [Release Policy](docs/RELEASE-POLICY.md) before upgrading.

Homebrew installs the latest stable release:

```bash
brew install gentleman-programming/tap/engram
```

For Windows, Linux, source builds, and all installation methods, see [Installation](docs/INSTALLATION.md).

### Set up your agent

Run the setup command for the agent you use, then restart that agent. `engram setup` writes the applicable MCP and integration configuration; it does not require you to start a server for the usual stdio-only setup.

| Agent | Setup |
| --- | --- |
| Claude Code | `engram setup claude-code` |
| Pi | `engram setup pi` |
| OpenCode | `engram setup opencode` |
| Gemini CLI | `engram setup gemini-cli` |
| Codex | `engram setup codex` |
| Antigravity CLI | `engram setup antigravity-cli` |
| Windsurf | `engram setup windsurf` |
| Qwen Code | `engram setup qwen` |
| Kiro | `engram setup kiro` |
| Cursor | `engram setup cursor` |
| VS Code (Copilot) | `engram setup vscode-copilot` |
| Kilo Code | `engram setup kilocode` |
| Kimi Code | `engram setup kimi` |
| CommandCode | `engram setup commandcode` |
| Another MCP-compatible agent | [Manual MCP setup](docs/AGENT-SETUP.md#any-other-mcp-agent) |

For Claude Code, rerunning setup updates the marketplace and the user-scope `engram@engram` plugin when it is already installed; existing project- or local-scope copies are not updated. An update failure fails setup; restart Claude Code after a successful update to load the new hooks.

> **Per-agent configuration, plugin behavior, manual MCP setup, compaction resilience, and troubleshooting: [Agent Setup →](docs/AGENT-SETUP.md)** · Pi users can also find the package at [`gentle-engram`](plugin/pi/README.md).

## Read-only compatibility observations

Before considering an existing store, run the explicit-path probe:

```sh
engram compatibility --data-dir /absolute/path/to/fixture --json
```

This command dispatches before updates, configuration, orphan migration or
`Store.New`. It reads directory metadata, the SQLite header and `.instance-id`
only; it does not load SQLite, read memories, create directories/locks or repair
identity. Exactly one `--data-dir` and one `--json` are accepted; any other
argument, including `--help`, prints the usage line to stderr. Invalid arguments
or unsafe metadata produce exit 2, no stdout and a diagnostic on stderr.
`engram help` lists the command. Successful observations produce exit 0 and one
JSON object with `revision: 1`, `source: "offline"`, both authorization flags
false and, for an existing store, its `instance_id`. Status is `fresh` for
an empty directory, `legacy_schema`/`future_schema` for non-current headers,
or `unknown_shape` for a current header. Missing directories, malformed headers,
missing/invalid identity, nonregular database/identity entries, database-name
ambiguity, WAL/SHM/journal sidecars and observed metadata changes are rejected.
Directory aliases are resolved; no filesystem path is returned in the JSON.

**Offline success never authorizes opening an existing store.** A current header
cannot prove schema shape, and normal schema-1 startup still executes DDL and
repairs. These observations are not atomic snapshots or leases; an undetected
race cannot grant permission because offline authorization is always false.

`GET /compatibility` provides the actual running store's startup facts, under
the same optional bearer authentication as other protected API routes. A
successful current-schema startup returns `source: "active"`, `status: "ready"`,
`active_reuse_authorized: true`, its actual `instance_id`, a per-store-opening
random `runtime_id`, and `capability: "startup-verified-store-v1"`. The response
is not derived from `/health`, release version or externally supplied metadata.
Nil, closed, generation-invalidated and future-schema-skipped handles return
`status: "unknown"` and deny reuse. Reads do not open SQLite connections or
resolve configuration. Startup facts do not certify arbitrary external in-place
schema edits or future changes; clients must not treat this response as a lease,
an authentication token or offline migration permission. Compare explicit store
identity when reusing a selected runtime; never silently substitute another
endpoint. Unknown evidence should leave memory disabled, with guidance to back
up, update and restart the existing server, then recheck.

## For agents

Treat Engram as a curated project memory, not a transcript sink. Use this operating contract throughout the session.

1. **Orient before writing.** Start with `mem_current_project` to confirm the resolved project and its source. At the start of related work, use `mem_context` and `mem_search` to recover the relevant history.
2. **Search before repeating.** Before revisiting a decision, bug, convention, or request that may already be known, search with focused terms. Search results are previews, not the complete record.
3. **Retrieve progressively.** Use `mem_search` for candidates, `mem_timeline` when surrounding session context matters, and `mem_get_observation` before relying on a full observation.
4. **Save significant knowledge deliberately.** Save completed bug fixes, decisions, discoveries, configuration changes, patterns, and durable user constraints with `mem_save`. Do not capture raw tool output or every conversational turn.
5. **Keep evolving knowledge stable.** Give an evolving topic a stable `topic_key` such as `architecture/auth-model`; reuse it to update that topic rather than creating competing memories. Use `mem_suggest_topic_key` when the key is unclear.
6. **Leave a handoff.** Before ending a session, save a `mem_session_summary` with the goal, instructions, discoveries, accomplished work, next steps, and relevant files.
7. **Recover after compaction.** Persist the compacted handoff with `mem_session_summary` first. Then call `mem_context` to recover recent session history before continuing.

### When Git initialization changes the detected project

Before creating a repository's first private Git identity, Engram checks local
session history for the exact working directory. If Git suggests `remote-app`
but that directory has history under `local-app`, implicit project selection
stops with `project_transition_conflict` instead of silently changing scope.
History is only a precaution: explicit or imported sessions can also trigger it.

Choose the intended scope deliberately. For a persistent choice, run
`engram init local-app` in the project directory; existing explicit project
filters and valid registered-session writes remain available. Do not overwrite
an existing configuration without reviewing it. This choice changes future
resolution; it does **not** merge or move previously split memories.

Historical directories are matched as absolute, lexically normalized paths;
Engram does not access their filesystems. Relative history without a recorded
base is ignored. Only the selected working directory is filesystem-canonicalized,
so legacy history stored under a symlink alias may require an explicit project
choice (`engram init local-app`) rather than automatic recognition.

Existing Git bindings stay stable. This check cannot reconstruct history without
a usable absolute directory, across relocated paths, or in another local store.

### A useful memory is structured

```markdown
**What**: Added retry-safe upload handling.
**Why**: Retries could create duplicate records.
**Where**: internal/upload/handler.go
**Learned**: Reuse the request id as the idempotency key.
```

Use a short, searchable title and a fitting type with that content. The full [Memory Protocol](DOCS.md#memory-protocol) defines the durable-save rules and session-summary shape.

### Choose MCP tools by intent

Tool availability can vary by MCP profile. Start with the intent, then use your client's tool discovery mechanism (such as `ToolSearch`) only when a deferred tool is needed.

| Intent | Start with |
| --- | --- |
| Confirm the project and recover recent work | `mem_current_project`, `mem_context` |
| Find prior knowledge without repeating work | `mem_search` |
| Inspect a result in enough detail | `mem_timeline`, `mem_get_observation` |
| Save or refine durable knowledge | `mem_save`, `mem_update`, `mem_suggest_topic_key` |
| Consolidate observations after preview and explicit confirmation | `mem_consolidate` (Go MCP server; [contract](docs/codebase/OBSERVATION-CONSOLIDATION.md#mcp-contract)) |
| Preserve the user's request | `mem_save_prompt` |
| Hand off or close a session | `mem_session_summary`, `mem_session_start`, `mem_session_end`; MCP atomic close: `mem_session_finalize` |
| Review stale knowledge or memory relationships | `mem_review`, `mem_judge`, `mem_compare`; MCP batch: `mem_judge_many` |
| Diagnose project or store state | `mem_doctor` |

For parameters and the complete, current tool reference, see [the full documentation](DOCS.md).

## Documentation

| Where to go | What you'll find |
| :--- | :--- |
| **[Intended Usage](docs/intended-usage.md)** | The human mental model for using Engram |
| **[Installation](docs/INSTALLATION.md)** · **[Release Policy](docs/RELEASE-POLICY.md)** | Platform support, all installation methods, and stable, RC, security-support, upgrade, and rollback guidance |
| **[Agent Setup](docs/AGENT-SETUP.md)** · **[Plugins](docs/PLUGINS.md)** | Per-agent configuration, compaction resilience, and OpenCode and Claude Code plugin details |
| **[Architecture](docs/ARCHITECTURE.md)** · **[Codebase Guide](docs/CODEBASE-GUIDE.md)** | Memory model, tool behavior, project structure, flows, and implementation landmarks |
| **[Engram Cloud](docs/engram-cloud/README.md)** · **[Team Usage](docs/TEAM-USAGE.md)** | Cloud quickstart, deployment, technical links, and shared-memory conventions |
| **[Doctor](docs/DOCTOR.md)** · **[Binary self-testing](docs/SELF-TESTING.md)** | Operational diagnosis and repair workflows, and isolated reliability and performance checks for released binaries |
| **[Beta Testing](docs/BETA_TESTING.md)** · **[Obsidian Brain](docs/beta/obsidian-brain.md)** | Isolated beta testing flows and cleanup guidance, and exporting memories as an Obsidian knowledge graph (beta) |
| **[Comparison](docs/COMPARISON.md)** | Engram compared with claude-mem |
| **[Full Docs](DOCS.md)** · **[Contributing](CONTRIBUTING.md)** | Complete CLI, environment, API, and operational reference, and the contributor workflow |

> **Dashboard contributors:** if you modify `.templ` files in `internal/cloud/dashboard/`, run `make templ` to regenerate before committing. See [Dashboard templ regeneration](DOCS.md#dashboard-templ-regeneration).

## Community

Every change starts with an approved issue. See [Contributing](CONTRIBUTING.md) for the issue-first workflow, labels, review requirements, and contributor standards.

<p><sub>This project exists because of these people.</sub></p>

</div>

## About the author

Built by [Alan Buscaglia](https://github.com/Gentleman-Programming) (Gentleman Programming). Engram is also the memory layer of [Gentle-AI](https://github.com/Gentleman-Programming/gentle-ai), and it stays a standalone tool you can use with any MCP-compatible agent.

</div>

---

<br/>

<p><strong>Inspired by <a href="https://github.com/thedotmack/claude-mem">claude-mem</a></strong> — but agent-agnostic, simpler, and built different.</p>

<br/>

</div>

> **Trademark notice:** The Engram™ names and logos are trademarks of Alan Buscaglia. The symbol appears on the first prominent mention, and this notice covers the rest. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See [TRADEMARKS.md](TRADEMARKS.md).

Repository info

Default branch: main
Latest version: v3.4.0
Created: 2026-02-16
Last activity: 2026-10-14
License: MIT
Open issues: 86
Watchers: 37

Contributors

Alan-TheGentleman

491 contributions

dnlrsls

480 contributions

danielgap

34 contributions

egdev6

12 contributions

Reaan06

10 contributions