Skip to content
Back to search

engram

Persistent memory for AI coding agents — agent-agnostic, single binary, zero dependencies

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 14 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Gentleman-Programming/engram with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Gentleman-Programming/engram'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gentleman-programming--engram/badge.svg)](/listings/gentleman-programming--engram)

HTML

<a href="/listings/gentleman-programming--engram"><img src="/api/listings/gentleman-programming--engram/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

brew install gentleman-programming/tap/engram

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "engram",
  4. "description": "Persistent memory for AI coding agents — agent-agnostic, single binary, zero dependencies",
  5. "owner": {
  6. "name": "Gentleman Programming",
  7. "email": "gentlemanprogramming.dev@gmail.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "engram",
  12. "description": "Persistent memory with session tracking, compaction recovery, and Memory Protocol. Gives Claude a brain that survives across sessions.",
  13. "version": "0.1.23",
  14. "author": {
  15. "name": "Gentleman Programming"
  16. },
  17. "source": "./plugin/claude-code",
  18. "category": "productivity",
  19. "homepage": "https://github.com/Gentleman-Programming/engram"
  20. }
  21. ]
  22. }
README.md · README · 435 lines
  1. <!-- markdownlint-disable-next-line MD041 -->
  2. <a id="top"></a>
  3. <div align="center">
  4. <img width="100%" alt="Engram neon elephant banner: the elephant exhales a memory stream (remember, sync, recall), the ENGRAM wordmark is written on, and the tagline One Brain. Local or Cloud. appears" src="assets/branding/engram-banner.gif" />
  5. <h1>Engram™</h1>
  6. <p><strong>Persistent memory for AI coding agents.</strong></p>
  7. <p>
  8. <a href="https://github.com/Gentleman-Programming/engram/releases"><img src="https://img.shields.io/github/v/release/Gentleman-Programming/engram?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="Release"></a>
  9. <a href="https://github.com/Gentleman-Programming/engram/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/engram?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="Stars"></a>
  10. <img src="https://img.shields.io/badge/agents-14-F095C8?style=for-the-badge&labelColor=1A1218" alt="14 agents">
  11. <img src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Platform">
  12. <a href="LICENSE"><img src="https://img.shields.io/badge/MIT-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="License: MIT"></a>
  13. </p>
  14. <p>
  15. <a href="https://trendshift.io/repositories/22750?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-22750" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/22750" alt="Gentleman-Programming%2Fengram | Trendshift" width="250" height="55"/></a>
  16. <a href="https://trendshift.io/repositories/22750?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-22750" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/22750/weekly?language=Go" alt="Gentleman-Programming%2Fengram | Trendshift" width="250" height="55"/></a>
  17. <a href="https://trendshift.io/repositories/22750?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-22750" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/22750/monthly?language=Go" alt="Gentleman-Programming%2Fengram | Trendshift" width="250" height="55"/></a>
  18. </p>
  19. <p>
  20. <a href="https://engram.gentlemanprogramming.com/"><strong>Website</strong></a> &bull;
  21. <a href="#get-started"><strong>Quickstart</strong></a> &bull;
  22. <a href="DOCS.md"><strong>Docs</strong></a> &bull;
  23. <a href="docs/RELEASE-STAGING.md"><strong>Candidate staging</strong></a> &bull;
  24. <a href="https://gentle-ai.gentlemanprogramming.com/"><strong>Gentle-AI</strong></a> &bull;
  25. <a href="https://gentle-ai-wiki.gentlemanprogramming.com/"><strong>Wiki</strong></a>
  26. </p>
  27. <br/>
  28. <p>
  29. <strong>engram</strong> <code>/ˈen.ɡræm/</code> — <em>neuroscience</em>: the physical trace of a memory in the brain.
  30. </p>
  31. <p>
  32. Your AI coding agent forgets everything when the session ends.
  33. <strong>Engram gives it a brain.</strong>
  34. </p>
  35. <p><sub>One brain. Local or cloud. Agent-agnostic, single binary, zero dependencies.</sub></p>
  36. <br/>
  37. <sub><strong>If Engram saved you from re-explaining your project, a star helps other people find it.</strong></sub>
  38. <!--
  39. sealed_token is a GitHub fine-grained token encrypted against Star History's
  40. public key, so only the encrypted value is published here. It is required
  41. because GitHub restricted the stargazers API to a repository's admins and
  42. collaborators on 2026-06-30; without it the chart renders an error placeholder.
  43. Regenerate it at https://www.star-history.com/?repos=Gentleman-Programming%2Fengram&type=date&legend=top-left
  44. -->
  45. <a href="https://www.star-history.com/?repos=Gentleman-Programming%2Fengram&type=date&legend=top-left">
  46. <picture>
  47. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fengram&type=date&theme=dark&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
  48. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fengram&type=date&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
  49. <img width="620" alt="Star History Chart" src="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fengram&type=date&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
  50. </picture>
  51. </a>
  52. <br/>
  53. <sub><strong>WORKS WITH THE AGENT YOU ALREADY HAVE</strong></sub>
  54. <strong><a href="docs/AGENT-SETUP.md#claude-code">Claude Code</a></strong> ·
  55. <strong><a href="docs/AGENT-SETUP.md#pi">Pi</a></strong> ·
  56. <strong><a href="docs/AGENT-SETUP.md#opencode">OpenCode</a></strong> ·
  57. <strong><a href="docs/AGENT-SETUP.md#gemini-cli">Gemini CLI</a></strong> ·
  58. <strong><a href="docs/AGENT-SETUP.md#codex">Codex</a></strong> ·
  59. <strong><a href="docs/AGENT-SETUP.md#antigravity">Antigravity</a></strong> ·
  60. <strong><a href="docs/AGENT-SETUP.md#windsurf">Windsurf</a></strong><br/>
  61. <strong><a href="docs/AGENT-SETUP.md#qwen-code">Qwen Code</a></strong> ·
  62. <strong><a href="docs/AGENT-SETUP.md#kiro">Kiro</a></strong> ·
  63. <strong><a href="docs/AGENT-SETUP.md#cursor">Cursor</a></strong> ·
  64. <strong><a href="docs/AGENT-SETUP.md#vs-code-copilot--claude-code-extension">VS Code (Copilot)</a></strong> ·
  65. <strong><a href="docs/AGENT-SETUP.md#kilo-code">Kilo Code</a></strong> ·
  66. <strong><a href="docs/AGENT-SETUP.md#kimi-code">Kimi Code</a></strong> ·
  67. <strong><a href="docs/AGENT-SETUP.md#commandcode">CommandCode</a></strong>
  68. <sub>14 setup targets · plus any MCP-compatible agent · <a href="docs/AGENT-SETUP.md">per-agent setup →</a></sub>
  69. </div>
  70. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  71. ## Support the project
  72. <div align="center">
  73. <a href="https://github.com/sponsors/Gentleman-Programming"><img width="100%" src="assets/branding/sponsor-banner.svg" alt="Free forever, independent by choice. No investors, no paywalls: Gentle AI, Engram and Gentle Shell are funded by the people who use them. Sponsor on GitHub, monthly or one-time."></a>
  74. <p>
  75. We deliberately don't depend on investors: no outside agenda deciding the roadmap and no features locked behind paywalls.<br/>
  76. Donations through <a href="https://github.com/sponsors/Gentleman-Programming"><strong>GitHub Sponsors</strong></a> go straight into maintenance, new features and keeping everything free and ours.
  77. </p>
  78. <p>Can't donate? A ⭐, a bug report or a pull request helps too.</p>
  79. <sub>Sponsorship never buys rankings, default selections or endorsements; see <a href="TRADEMARKS.md">TRADEMARKS.md</a>.</sub>
  80. </div>
  81. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  82. ## Features
  83. ---
  84. ### One binary — Memory without a stack
  85. ```
  86. Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
  87. ↓ MCP stdio
  88. Engram (single Go binary)
  89. ↓
  90. SQLite + FTS5 (~/.engram/engram.db)
  91. ```
  92. 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.
  93. 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.
  94. The data directory defaults to `~/.engram`; a nonblank `ENGRAM_DATA_DIR` overrides it and must be an absolute path. On Windows, local-SQLite commands (including `serve`, `mcp`, and `doctor`) create and check `<data-directory>/tmp/sqlite` before opening SQLite, then set `TEMP` and `TMP` for that process only. Startup fails with an operation-specific diagnostic if the directory cannot be used. User/system environment settings and the working directory are unchanged. The directory is shared between processes and is not cleaned by Engram; SQLite manages its own uniquely named temporary files. This preparation also covers cloud `status`, `enroll`, `unenroll`, `attest-prompt-source`, and the local-store `cloud upgrade` operations (`doctor`, `repair`, `bootstrap`, `remirror`, `status`, `rollback`). It does not run for `protocol-mode`, `setup`, `cloud serve`, `cloud config`, top-level `cloud repair` or `cloud bootstrap` (distinct from the included `cloud upgrade repair` and `cloud upgrade bootstrap`), other `cloud upgrade` subcommands, or unknown commands. Existing orphan-database migration behavior is unchanged, including for commands excluded from this preparation. Linux/macOS, config-free commands, isolated self-tests, `compatibility`, and `migrate-copy` retain their existing behavior.
  95. **[Docs →](docs/ARCHITECTURE.md)**
  96. ---
  97. ### Project-aware — The right memory for the right repo
  98. 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.
  99. **[Docs →](DOCS.md#mcp-project-resolution)**
  100. ---
  101. ### Local first — Portable when needed
  102. 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.
  103. | Need | Start here |
  104. | --- | --- |
  105. | Local memory and the runtime model | [Architecture](docs/ARCHITECTURE.md) |
  106. | Share memory with Git | [Git Sync reference](DOCS.md#git-sync-chunked) |
  107. | Use optional Cloud replication | [Engram Cloud](docs/engram-cloud/README.md) |
  108. | Diagnose or recover Cloud operations | [Cloud troubleshooting](docs/engram-cloud/troubleshooting.md) |
  109. 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.
  110. ```bash
  111. engram cloud upgrade doctor --project <project>
  112. engram cloud upgrade repair --project <project> --dry-run
  113. engram cloud upgrade repair --project <project> --apply # only when the dry run reports changes
  114. engram cloud upgrade bootstrap --project <project>
  115. engram cloud upgrade status --project <project>
  116. ```
  117. **[Docs →](DOCS.md#cloud-upgrade-flow)**
  118. ---
  119. ### Terminal UI — Browse what your agent remembers
  120. ```bash
  121. engram tui
  122. ```
  123. <p align="center">
  124. <img src="assets/tui-dashboard.png" alt="TUI Dashboard" width="400" />
  125. <img width="400" alt="TUI recent observations" src="assets/tui-recent.png" />
  126. <img src="assets/tui-detail.png" alt="TUI Observation Detail" width="400" />
  127. <img src="assets/tui-search.png" alt="TUI Search Results" width="400" />
  128. </p>
  129. 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.
  130. **[Docs →](DOCS.md#terminal-ui-tui)**
  131. ---
  132. ### Also in the box
  133. | Component | What it does |
  134. | :--- | :--- |
  135. | **[MCP tools](DOCS.md#mcp-tools-27-tools)** | Save, search, timeline, session, review, and diagnosis tools for your agent |
  136. | **[HTTP API](DOCS.md#http-api-endpoints)** | The same memory over local HTTP endpoints; [compound agent workflows](docs/HTTP-AGENT-WORKFLOWS.md) |
  137. | **[Doctor](docs/DOCTOR.md)** | `engram doctor` — read-only operational diagnostics |
  138. | **[Conflict surfacing](docs/AGENT-SETUP.md#conflict-surfacing-automatic)** | Flags related or conflicting memories so the agent can judge them |
  139. | **[Plugins](docs/PLUGINS.md)** | OpenCode and Claude Code plugin details |
  140. | **[`gentle-engram`](plugin/pi/README.md)** | The Engram package for Pi |
  141. | **[Team usage](docs/TEAM-USAGE.md)** | Shared-memory conventions |
  142. | **[Binary self-testing](docs/SELF-TESTING.md)** | Isolated reliability and performance checks for released binaries |
  143. | **[Obsidian Brain](docs/beta/obsidian-brain.md)** | Export memories as an Obsidian knowledge graph (beta) |
  144. > **Every command, environment variable, and endpoint: [Full reference →](DOCS.md)**
  145. <div align="right"><a href="#top">Back to top</a></div>
  146. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  147. ## Get started
  148. ### Install
  149. 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.
  150. Homebrew installs the latest stable release:
  151. ```bash
  152. brew install gentleman-programming/tap/engram
  153. ```
  154. For Windows, Linux, source builds, and all installation methods, see [Installation](docs/INSTALLATION.md).
  155. ### Set up your agent
  156. 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.
  157. | Agent | Setup |
  158. | --- | --- |
  159. | Claude Code | `engram setup claude-code` |
  160. | Pi | `engram setup pi` |
  161. | OpenCode | `engram setup opencode` |
  162. | Gemini CLI | `engram setup gemini-cli` |
  163. | Codex | `engram setup codex` |
  164. | Antigravity CLI | `engram setup antigravity-cli` |
  165. | Windsurf | `engram setup windsurf` |
  166. | Qwen Code | `engram setup qwen` |
  167. | Kiro | `engram setup kiro` |
  168. | Cursor | `engram setup cursor` |
  169. | VS Code (Copilot) | `engram setup vscode-copilot` |
  170. | Kilo Code | `engram setup kilocode` |
  171. | Kimi Code | `engram setup kimi` |
  172. | CommandCode | `engram setup commandcode` |
  173. | Another MCP-compatible agent | [Manual MCP setup](docs/AGENT-SETUP.md#any-other-mcp-agent) |
  174. 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.
  175. > **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).
  176. <div align="right"><a href="#top">Back to top</a></div>
  177. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  178. ## Read-only compatibility observations
  179. Before considering an existing store, run the explicit-path probe:
  180. ```sh
  181. engram compatibility --data-dir /absolute/path/to/fixture --json
  182. ```
  183. This command dispatches before updates, configuration, orphan migration or
  184. `Store.New`. It reads directory metadata, the SQLite header and `.instance-id`
  185. only; it does not load SQLite, read memories, create directories/locks or repair
  186. identity. Exactly one `--data-dir` and one `--json` are accepted; any other
  187. argument, including `--help`, prints the usage line to stderr. Invalid arguments
  188. or unsafe metadata produce exit 2, no stdout and a diagnostic on stderr.
  189. `engram help` lists the command. Successful observations produce exit 0 and one
  190. JSON object with `revision: 1`, `source: "offline"`, both authorization flags
  191. false and, for an existing store, its `instance_id`. Status is `fresh` for
  192. an empty directory, `legacy_schema`/`future_schema` for non-current headers,
  193. or `unknown_shape` for a current header. Missing directories, malformed headers,
  194. missing/invalid identity, nonregular database/identity entries, database-name
  195. ambiguity, WAL/SHM/journal sidecars and observed metadata changes are rejected.
  196. Directory aliases are resolved; no filesystem path is returned in the JSON.
  197. **Offline success never authorizes opening an existing store.** A current header
  198. cannot prove schema shape, and normal schema-1 startup still executes DDL and
  199. repairs. These observations are not atomic snapshots or leases; an undetected
  200. race cannot grant permission because offline authorization is always false.
  201. `GET /compatibility` provides the actual running store's startup facts, under
  202. the same optional bearer authentication as other protected API routes. A
  203. successful current-schema startup returns `source: "active"`, `status: "ready"`,
  204. `active_reuse_authorized: true`, its actual `instance_id`, a per-store-opening
  205. random `runtime_id`, and `capability: "startup-verified-store-v1"`. The response
  206. is not derived from `/health`, release version or externally supplied metadata.
  207. Nil, closed, generation-invalidated and future-schema-skipped handles return
  208. `status: "unknown"` and deny reuse. Reads do not open SQLite connections or
  209. resolve configuration. Startup facts do not certify arbitrary external in-place
  210. schema edits or future changes; clients must not treat this response as a lease,
  211. an authentication token or offline migration permission. Compare explicit store
  212. identity when reusing a selected runtime; never silently substitute another
  213. endpoint. Unknown evidence should leave memory disabled, with guidance to back
  214. up, update and restart the existing server, then recheck.
  215. ## For agents
  216. Treat Engram as a curated project memory, not a transcript sink. Use this operating contract throughout the session.
  217. 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.
  218. 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.
  219. 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.
  220. 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.
  221. 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.
  222. 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.
  223. 7. **Recover after compaction.** Persist the compacted handoff with `mem_session_summary` first. Then call `mem_context` to recover recent session history before continuing.
  224. ### When Git initialization changes the detected project
  225. Before creating a repository's first private Git identity, Engram checks local
  226. session history for the exact working directory. If Git suggests `remote-app`
  227. but that directory has history under `local-app`, implicit project selection
  228. stops with `project_transition_conflict` instead of silently changing scope.
  229. History is only a precaution: explicit or imported sessions can also trigger it.
  230. Choose the intended scope deliberately. For a persistent choice, run
  231. `engram init local-app` in the project directory; existing explicit project
  232. filters and valid registered-session writes remain available. Do not overwrite
  233. an existing configuration without reviewing it. This choice changes future
  234. resolution; it does **not** merge or move previously split memories.
  235. Historical directories are matched as absolute, lexically normalized paths;
  236. Engram does not access their filesystems. Relative history without a recorded
  237. base is ignored. Only the selected working directory is filesystem-canonicalized,
  238. so legacy history stored under a symlink alias may require an explicit project
  239. choice (`engram init local-app`) rather than automatic recognition.
  240. Existing Git bindings stay stable. This check cannot reconstruct history without
  241. a usable absolute directory, across relocated paths, or in another local store.
  242. ### A useful memory is structured
  243. ```markdown
  244. **What**: Added retry-safe upload handling.
  245. **Why**: Retries could create duplicate records.
  246. **Where**: internal/upload/handler.go
  247. **Learned**: Reuse the request id as the idempotency key.
  248. ```
  249. 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.
  250. ### Choose MCP tools by intent
  251. 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.
  252. | Intent | Start with |
  253. | --- | --- |
  254. | Confirm the project and recover recent work | `mem_current_project`, `mem_context` |
  255. | Find prior knowledge without repeating work | `mem_search` |
  256. | Inspect a result in enough detail | `mem_timeline`, `mem_get_observation` |
  257. | Save or refine durable knowledge | `mem_save`, `mem_update`, `mem_suggest_topic_key` |
  258. | Consolidate observations after preview and explicit confirmation | `mem_consolidate` (Go MCP server; [contract](docs/codebase/OBSERVATION-CONSOLIDATION.md#mcp-contract)) |
  259. | Preserve the user's request | `mem_save_prompt` |
  260. | Hand off or close a session | `mem_session_summary`, `mem_session_start`, `mem_session_end`; MCP atomic close: `mem_session_finalize` |
  261. | Review stale knowledge or memory relationships | `mem_review`, `mem_judge`, `mem_compare`; MCP batch: `mem_judge_many` |
  262. | Diagnose project or store state | `mem_doctor` |
  263. For parameters and the complete, current tool reference, see [the full documentation](DOCS.md).
  264. <div align="right"><a href="#top">Back to top</a></div>
  265. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  266. ## Documentation
  267. | Where to go | What you'll find |
  268. | :--- | :--- |
  269. | **[Intended Usage](docs/intended-usage.md)** | The human mental model for using Engram |
  270. | **[Installation](docs/INSTALLATION.md)** · **[Release Policy](docs/RELEASE-POLICY.md)** | Platform support, all installation methods, and stable, RC, security-support, upgrade, and rollback guidance |
  271. | **[Agent Setup](docs/AGENT-SETUP.md)** · **[Plugins](docs/PLUGINS.md)** | Per-agent configuration, compaction resilience, and OpenCode and Claude Code plugin details |
  272. | **[Architecture](docs/ARCHITECTURE.md)** · **[Codebase Guide](docs/CODEBASE-GUIDE.md)** | Memory model, tool behavior, project structure, flows, and implementation landmarks |
  273. | **[Engram Cloud](docs/engram-cloud/README.md)** · **[Team Usage](docs/TEAM-USAGE.md)** | Cloud quickstart, deployment, technical links, and shared-memory conventions |
  274. | **[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 |
  275. | **[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) |
  276. | **[Comparison](docs/COMPARISON.md)** | Engram compared with claude-mem |
  277. | **[Full Docs](DOCS.md)** · **[Contributing](CONTRIBUTING.md)** | Complete CLI, environment, API, and operational reference, and the contributor workflow |
  278. > **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).
  279. <div align="right"><a href="#top">Back to top</a></div>
  280. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  281. ## Community
  282. Every change starts with an approved issue. See [Contributing](CONTRIBUTING.md) for the issue-first workflow, labels, review requirements, and contributor standards.
  283. <div align="center">
  284. <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/Contributing%20Guide-F095C8?style=for-the-badge&labelColor=1A1218&logo=git&logoColor=F095C8" alt="Contributing Guide"></a>
  285. <a href="https://github.com/Gentleman-Programming/engram/graphs/contributors"><img src="https://img.shields.io/badge/Contributors-D7A0B8?style=for-the-badge&labelColor=1A1218&logo=github&logoColor=D7A0B8" alt="Contributors"></a>
  286. <a href="https://discord.com/invite/gentleman-programming-769863833996754944"><img src="https://img.shields.io/badge/Discord-Gentleman%20Programming-F095C8?style=for-the-badge&labelColor=1A1218" alt="Gentleman Programming Discord"></a>
  287. <br/><br/>
  288. <a href="https://github.com/Gentleman-Programming/engram/graphs/contributors">
  289. <img width="100%" src="https://contrib.rocks/image?repo=Gentleman-Programming/engram&max=100" alt="Engram contributors" />
  290. </a>
  291. <p><sub>This project exists because of these people.</sub></p>
  292. </div>
  293. <div align="right"><a href="#top">Back to top</a></div>
  294. <div align="center"><img src="assets/branding/engram-logo-only.png" width="28" alt="" /></div>
  295. ## About the author
  296. 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.
  297. <div align="center">
  298. <a href="https://gentlemanprogramming.com/"><img src="https://img.shields.io/badge/Website-F095C8?style=for-the-badge&labelColor=1A1218&logo=googlechrome&logoColor=F095C8" alt="Website"></a>
  299. <a href="https://www.youtube.com/@GentlemanProgramming"><img src="https://img.shields.io/badge/YouTube-F095C8?style=for-the-badge&labelColor=1A1218&logo=youtube&logoColor=F095C8" alt="YouTube"></a>
  300. <a href="https://github.com/Gentleman-Programming"><img src="https://img.shields.io/badge/GitHub-D7A0B8?style=for-the-badge&labelColor=1A1218&logo=github&logoColor=D7A0B8" alt="GitHub"></a>
  301. </div>
  302. ---
  303. <div align="center">
  304. <img src="assets/branding/engram-logo-only.png" width="56" alt="" />
  305. <br/>
  306. <p><strong>Inspired by <a href="https://github.com/thedotmack/claude-mem">claude-mem</a></strong> — but agent-agnostic, simpler, and built different.</p>
  307. <br/>
  308. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-F095C8?style=for-the-badge&labelColor=1A1218" alt="License: MIT"></a>
  309. </div>
  310. > **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).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.