Skip to content
Back to search

engrim

The Universal Cross-Model Episodic Memory Standard. Local-first, project-scoped SQLite engine for Google Antigravity, Claude Code, Cursor, Codex CLI, GitHub Copilot CLI, and OpenCode. Zero cloud lock-in.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/timgordontg--engrim/badge.svg)](/listings/timgordontg--engrim)

HTML

<a href="/listings/timgordontg--engrim"><img src="/api/listings/timgordontg--engrim/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.

Installation

pip install engrim

Auto-Detection (Recommended)

Run `engrim setup` without arguments. It automatically detects installed environments on your machine and configures them all:

engrim setup

- If `~/.gemini` exists $\rightarrow$ wires Antigravity lifecycle hooks, skill, and MCP server. - If `~/.claude` exists $\rightarrow$ wires Claude Code SessionStart, Stop, status line, and CLAUDE.md. - If `~/.cursor` exists $\rightarrow$ generates and merges Cursor MCP configuration. - If `~/.codex` exists $\rightarrow$ wires Codex CLI native command hooks and managed global `AGENTS.md` guidance. MCP stays opt-in. - If `~/.config/opencode` exists $\rightarrow$ writes OpenCode plugin, registers MCP server, and adds `AGENTS.md` notes. - If `~/.copilot` exists $\rightarrow$ wires Copilot CLI hooks and the Engrim status line, registers the MCP server, and adds `copilot-instructions.md` notes.

---

Diagnostic Health Check & Self-Healing (`engrim doctor`)

Verify database integrity, semantic recall coverage, and all configured agent hooks across your system:

# Run comprehensive health diagnostic across all agent environments
engrim doctor

# Automatically repair broken hook paths or cross-OS migrations with self-healing PATH fallback
engrim doctor --fix

# Output diagnostic report as JSON (for CI pipelines or health monitoring)
engrim doctor --json

**Real output:**

================================================================================
                 🩺 ENGRIM DOCTOR: DIAGNOSTIC HEALTH CHECK                    
================================================================================
Platform   : linux (x86_64) Β· Python 3.12.3
Engrim CLI : /home/user/.local/bin/engrim
Project    : /workspace/my-project

[1] Database & Storage Engine
  βœ“ Store Location   : /home/user/.engrim/memory.db
  βœ“ Integrity Check  : ok
  βœ“ Journal Mode     : wal (WAL)
  βœ“ Curated Memories : 956 active / 1057 total
    (decision=413, fact=178, feedback=47, reference=20, state=283, user=15)
  βœ“ Flight Log Turns : 48501 logged

[2] Semantic Recall Engine
  βœ“ Model Available  : model2vec:minishlab/potion-base-8M
  βœ“ Embedded Records : 1032 / 956

[3] Agent Environments & Hooks
  Google Antigravity (~/.gemini):
    βœ“ PreInvocation hook: valid
    βœ“ Stop hook: valid
    βœ“ MCP server: /home/user/.local/bin/engrim (valid)
    βœ“ Skill deployed: yes
  Claude Code (~/.claude):
    βœ“ SessionStart hook: valid
    βœ“ SessionEnd hook: valid
    βœ“ Stop hook: valid
    βœ“ UserPromptSubmit hook: valid
  Codex CLI (~/.codex):
    βœ“ SessionStart hook: valid
    βœ“ SessionEnd hook: valid
    βœ“ Stop hook: valid
    βœ“ UserPromptSubmit hook: valid
    βœ“ Managed AGENTS.md guidance: present
    β€’ MCP registration: optional, not configured
  GitHub Copilot CLI (~/.copilot):
    βœ“ sessionStart hook: valid
    βœ“ userPromptSubmitted hook: valid
    βœ“ agentStop hook: valid
    βœ“ MCP server: /home/user/.local/bin/engrim (valid)
    βœ“ Status line: configured

================================================================================
Result: All systems healthy. Zero issues detected across all agent hosts.
================================================================================

- **Self-Healing Path Fallback**: Hook commands feature portable PATH fallback (`<bin> || engrim ... || true`) ensuring sessions never experience silent hook failures when directories move or dotfiles sync across machines. - **Deep Integrity Audit**: Validates SQLite WAL mode, database consistency (`PRAGMA integrity_check`), active records, and semantic model readiness (`model2vec`).

---

Explicit Platform Setup

πŸͺ Google Antigravity

engrim setup --agy

- Configures `~/.gemini/config/hooks.json` to execute `engrim hook --agent agy --event boot` on `PreInvocation` and `engrim hook --agent agy --event stop` on `Stop`. - Deploys canonical Antigravity skill to `~/.gemini/config/skills/engrim/SKILL.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 Β· 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "engrim",
  4. "owner": {
  5. "name": "Tim Gordon",
  6. "url": "https://github.com/timgordontg"
  7. },
  8. "metadata": {
  9. "description": "Local-first memory for Claude Code: no API key, nothing leaves your machine.",
  10. "version": "1.4.11"
  11. },
  12. "plugins": [
  13. {
  14. "name": "engrim",
  15. "source": "./plugin",
  16. "description": "Local-first memory for Claude Code: no API key, nothing leaves your machine. Remembers your decisions and the WHY behind them, then hands back just the relevant slice at session start and on every prompt, so you can /clear aggressively without losing context. You curate what matters; bundled semantic + keyword retrieval over a local SQLite store. Self-installs on first run.",
  17. "version": "1.4.11",
  18. "keywords": ["memory", "context", "local-first", "no-api-key", "privacy", "decisions", "clear", "continuity"]
  19. }
  20. ]
  21. }
README.md Β· README Β· 424 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # engrim
  2. [![CI](https://github.com/timgordontg/engrim/actions/workflows/ci.yml/badge.svg)](https://github.com/timgordontg/engrim/actions/workflows/ci.yml)
  3. [![PyPI](https://img.shields.io/pypi/v/engrim?color=blue)](https://pypi.org/project/engrim/)
  4. [![Website](https://img.shields.io/badge/website-engrim.dev-blue)](https://engrim.dev)
  5. [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
  6. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  7. [![Local & Private](https://img.shields.io/badge/local-%26%20private-brightgreen)](#security-privacy)
  8. [![Glama MCP](https://glama.ai/mcp/servers/timgordontg/engrim/badges/score.svg)](https://glama.ai/mcp/servers/timgordontg/engrim)
  9. **The Universal Cross-Model & Cross-Agent Episodic Memory Standard.**
  10. A local-first, project-scoped SQLite memory engine that allows developers to freely switch between models and environments (**Google Antigravity**, **Claude Code**, **Cursor**, **Codex CLI**, **GitHub Copilot CLI**, **OpenCode**, and **Windsurf**) on the **same codebase** without losing architectural decisions, user constraints, or project state.
  11. ---
  12. ## 1. Overview & Core Value Proposition
  13. > **"Why pay for 200,000 tokens of forgotten noise on every turn? The models are disposable utilities; your project's decisions are not."**
  14. **Engrim** is the universal, cross-model episodic memory standard engineered specifically for autonomous AI coding agents and heavy software development.
  15. It solves the **"200,000-token context window trap"** (where coding models suffer from severe attention dilution, compounding per-turn token costs, and the loss of prior architectural decisions whenever a chat session is cleared) by replacing raw transcript replay with **4,000 characters of high-precision, curated episodic working memory** stored in a single, local-first SQLite file (`~/.engrim/memory.db`).
  16. ### The Problem vs. The Engrim Standard
  17. | Challenge | Without Engrim (Token Bloat & Context Resets) | With Engrim (Episodic Continuity) |
  18. |:---|:---|:---|
  19. | **Context Window** | **Attention Dilution**: 150k+ tokens re-sent on every turn; models lose reasoning sharpness and hallucinate past constraints. | **Precision Working Memory**: ~4,000 chars (<1,000 tokens, <1% of context) injected at boot. Zero attention dilution. |
  20. | **Session Clearing** | **Context Reset on `/clear`**: Clearing chat wipes agent context to zero; you spend minutes re-explaining rules and architecture. | **Continue-As-Clear**: Clear anytime (`/clear`). Decisions, active state, and `[β–Ά RESUME HERE]` reload instantly. |
  21. | **Agent Ecosystem** | **Vendor Silos**: Decisions made in Claude Code are invisible in Antigravity, Cursor, Codex, Copilot CLI, or OpenCode. | **Universal Substrate**: One local SQLite store (`~/.engrim/memory.db`) shared across all 6 major harnesses. |
  22. | **Hook Reliability** | **Silent Failures**: Moving across machines or OSes silently breaks hardcoded binary paths with no error message. | **Self-Healing Diagnostics**: `engrim doctor --fix` checks the supported hook and MCP configurations and repairs stale binary paths. |
  23. | **Data Privacy** | **SaaS Cloud Leakage**: Proprietary code and architectural constraints sent to third-party memory APIs. | **100% Local & Private**: Stored locally in SQLite WAL mode (POSIX `0600`). No telemetry, no cloud sync, no tracking. |
  24. ---
  25. ## 2. Architecture & How It Works (The 10-Second Mental Model)
  26. ```mermaid
  27. graph TD
  28. subgraph Agents ["Supported Agent Environments"]
  29. AGY["Google Antigravity<br/>(PreInvocation & Stop Hooks)"]
  30. CLAUDE["Claude Code<br/>(SessionStart & Stop Hooks)"]
  31. CURSOR["Cursor / Windsurf<br/>(Model Context Protocol stdio)"]
  32. CODEX["Codex CLI<br/>(Hooks, guidance & optional MCP)"]
  33. OPENCODE["OpenCode<br/>(Plugin & MCP)"]
  34. COPILOT["GitHub Copilot CLI<br/>(Command hooks & MCP)"]
  35. end
  36. subgraph CoreEngine ["engrim Core Engine (v1.4.11)"]
  37. ADAPTERS["Adapters & Lifecycle Hooks<br/>(agy, claude, opencode, copilot, mcp)"]
  38. DOCTOR["Health & Diagnostic Engine<br/>(engrim doctor --fix)"]
  39. PROVENANCE["Agent Provenance Engine<br/>(origin_agent tracking)"]
  40. ROUTER["Hybrid Retrieval & Minder<br/>(bm25 lexical + vector cosine)"]
  41. end
  42. subgraph Storage ["Local-First SQLite Store (~/.engrim/memory.db)"]
  43. MEMORIES[("Curated Memories<br/>(decisions, facts, feedback)")]
  44. FTS5["FTS5 Full-Text Search<br/>(porter stemmer, triggers)"]
  45. VEC["Vector Embeddings<br/>(model2vec static embeddings)"]
  46. LOG["Flight Recorder Log<br/>(turns + action lines)"]
  47. end
  48. AGY <-->|"hook / CLI"| ADAPTERS
  49. CLAUDE <-->|"hook / CLI"| ADAPTERS
  50. CURSOR <-->|"JSON-RPC (stdio)"| ADAPTERS
  51. CODEX <-->|"command hook / MCP"| ADAPTERS
  52. OPENCODE <-->|"plugin / MCP"| ADAPTERS
  53. COPILOT <-->|"command hook / MCP"| ADAPTERS
  54. ADAPTERS --> PROVENANCE
  55. PROVENANCE --> ROUTER
  56. ROUTER --> MEMORIES
  57. MEMORIES --- FTS5
  58. MEMORIES --- VEC
  59. ADAPTERS --> LOG
  60. ```
  61. 1. **Boot**: When your agent starts or a prompt is submitted, `engrim` injects the top-priority memory pack (~4k chars) into the agent's context, leading with `[β–Ά RESUME HERE]`.
  62. 2. **Capture**: As the agent works, it records architectural decisions via MCP (`engrim_add`) or lifecycle hooks automatically, tracking the `origin_agent` provenance.
  63. 3. **Recall & Minder**: Hybrid lexical (`bm25`) + vector (`model2vec`) search retrieves relevant records on demand in ~30ms without slowing down the agent.
  64. 4. **Continue-As-Clear**: When context bloats or the model drifts, type `/clear`. The next session boots from `memory.db` with zero memory loss.
  65. ---
  66. ## 3. Multi-Agent Quickstart
  67. ### Installation
  68. ```bash
  69. pip install engrim
  70. ```
  71. ### Auto-Detection (Recommended)
  72. Run `engrim setup` without arguments. It automatically detects installed environments on your machine and configures them all:
  73. ```bash
  74. engrim setup
  75. ```
  76. - If `~/.gemini` exists $\rightarrow$ wires Antigravity lifecycle hooks, skill, and MCP server.
  77. - If `~/.claude` exists $\rightarrow$ wires Claude Code SessionStart, Stop, status line, and CLAUDE.md.
  78. - If `~/.cursor` exists $\rightarrow$ generates and merges Cursor MCP configuration.
  79. - If `~/.codex` exists $\rightarrow$ wires Codex CLI native command hooks and managed global `AGENTS.md` guidance. MCP stays opt-in.
  80. - If `~/.config/opencode` exists $\rightarrow$ writes OpenCode plugin, registers MCP server, and adds `AGENTS.md` notes.
  81. - If `~/.copilot` exists $\rightarrow$ wires Copilot CLI hooks and the Engrim status line, registers the MCP server, and adds `copilot-instructions.md` notes.
  82. ---
  83. ### Diagnostic Health Check & Self-Healing (`engrim doctor`)
  84. Verify database integrity, semantic recall coverage, and all configured agent hooks across your system:
  85. ```bash
  86. # Run comprehensive health diagnostic across all agent environments
  87. engrim doctor
  88. # Automatically repair broken hook paths or cross-OS migrations with self-healing PATH fallback
  89. engrim doctor --fix
  90. # Output diagnostic report as JSON (for CI pipelines or health monitoring)
  91. engrim doctor --json
  92. ```
  93. **Real output:**
  94. ```text
  95. ================================================================================
  96. 🩺 ENGRIM DOCTOR: DIAGNOSTIC HEALTH CHECK
  97. ================================================================================
  98. Platform : linux (x86_64) Β· Python 3.12.3
  99. Engrim CLI : /home/user/.local/bin/engrim
  100. Project : /workspace/my-project
  101. [1] Database & Storage Engine
  102. βœ“ Store Location : /home/user/.engrim/memory.db
  103. βœ“ Integrity Check : ok
  104. βœ“ Journal Mode : wal (WAL)
  105. βœ“ Curated Memories : 956 active / 1057 total
  106. (decision=413, fact=178, feedback=47, reference=20, state=283, user=15)
  107. βœ“ Flight Log Turns : 48501 logged
  108. [2] Semantic Recall Engine
  109. βœ“ Model Available : model2vec:minishlab/potion-base-8M
  110. βœ“ Embedded Records : 1032 / 956
  111. [3] Agent Environments & Hooks
  112. Google Antigravity (~/.gemini):
  113. βœ“ PreInvocation hook: valid
  114. βœ“ Stop hook: valid
  115. βœ“ MCP server: /home/user/.local/bin/engrim (valid)
  116. βœ“ Skill deployed: yes
  117. Claude Code (~/.claude):
  118. βœ“ SessionStart hook: valid
  119. βœ“ SessionEnd hook: valid
  120. βœ“ Stop hook: valid
  121. βœ“ UserPromptSubmit hook: valid
  122. Codex CLI (~/.codex):
  123. βœ“ SessionStart hook: valid
  124. βœ“ SessionEnd hook: valid
  125. βœ“ Stop hook: valid
  126. βœ“ UserPromptSubmit hook: valid
  127. βœ“ Managed AGENTS.md guidance: present
  128. β€’ MCP registration: optional, not configured
  129. GitHub Copilot CLI (~/.copilot):
  130. βœ“ sessionStart hook: valid
  131. βœ“ userPromptSubmitted hook: valid
  132. βœ“ agentStop hook: valid
  133. βœ“ MCP server: /home/user/.local/bin/engrim (valid)
  134. βœ“ Status line: configured
  135. ================================================================================
  136. Result: All systems healthy. Zero issues detected across all agent hosts.
  137. ================================================================================
  138. ```
  139. - **Self-Healing Path Fallback**: Hook commands feature portable PATH fallback (`<bin> || engrim ... || true`) ensuring sessions never experience silent hook failures when directories move or dotfiles sync across machines.
  140. - **Deep Integrity Audit**: Validates SQLite WAL mode, database consistency (`PRAGMA integrity_check`), active records, and semantic model readiness (`model2vec`).
  141. ---
  142. ### Explicit Platform Setup
  143. #### πŸͺ Google Antigravity
  144. ```bash
  145. engrim setup --agy
  146. ```
  147. - Configures `~/.gemini/config/hooks.json` to execute `engrim hook --agent agy --event boot` on `PreInvocation` and `engrim hook --agent agy --event stop` on `Stop`.
  148. - Deploys canonical Antigravity skill to `~/.gemini/config/skills/engrim/SKILL.md`.
  149. - Registers MCP server in `~/.gemini/antigravity-cli/mcp_config.json` and `~/.gemini/config/mcp_config.json`.
  150. #### 🟣 Claude Code
  151. ```bash
  152. engrim setup --claude
  153. ```
  154. - Wires `SessionStart`, `SessionEnd`, `Stop`, and `UserPromptSubmit` hooks in `~/.claude/settings.json`.
  155. - Configures live ambient status line in Claude Code's status bar.
  156. - Appends memory usage notes to `~/.claude/CLAUDE.md`.
  157. #### ⚑ Cursor & Windsurf
  158. ```bash
  159. engrim setup --cursor
  160. ```
  161. - Adds `engrim` to `~/.cursor/mcp.json` running `engrim serve --mcp`.
  162. For Windsurf, add `engrim` to `~/.codeium/windsurf/mcp_config.json`:
  163. ```json
  164. {
  165. "mcpServers": {
  166. "engrim": {
  167. "command": "engrim",
  168. "args": ["serve", "--mcp"]
  169. }
  170. }
  171. }
  172. ```
  173. #### πŸ’» Codex CLI
  174. ```bash
  175. engrim setup --codex
  176. ```
  177. - Wires `SessionStart`, `SessionEnd`, `Stop`, and `UserPromptSubmit` command hooks in `$CODEX_HOME/hooks.json` (`~/.codex` by default).
  178. - Adds or updates an Engrim-owned block in `$CODEX_HOME/AGENTS.md`. Existing instructions and symbolic links remain unchanged. If the file already has an unmarked `## Project Memory (engrim)` section, setup treats it as user-owned and does not add a duplicate. A non-empty `AGENTS.override.md` is not modified, but setup warns that it shadows the guidance.
  179. - Calls the local `engrim` CLI directly, so MCP is not required. Hooks must be reviewed and trusted with Codex's `/hooks` command before they run.
  180. To expose the `engrim_*` tools to Codex, enable the optional MCP server:
  181. ```bash
  182. engrim setup --codex-mcp
  183. # Equivalent: engrim setup --codex --codex-mcp
  184. ```
  185. This uses Codex's supported `codex mcp add` command and preserves unrelated `config.toml` settings. Use `/mcp` to verify the server, then open a new Codex session so the hooks and guidance load.
  186. `engrim uninstall --codex` removes only Engrim hooks, the managed guidance block, and the `mcp_servers.engrim` entry. It preserves all other Codex settings and instructions.
  187. #### πŸ€– GitHub Copilot CLI
  188. ```bash
  189. engrim setup --copilot
  190. ```
  191. - Writes `~/.copilot/hooks/engrim.json` (respects `$COPILOT_HOME`), a file engrim owns outright, so your other hook files are never rewritten.
  192. - **`sessionStart`** β†’ the memory pack is returned as `additionalContext` and injected into the new session before your first prompt.
  193. - **`userPromptSubmitted`** β†’ the prompt lands in the flight-recorder log. Copilot CLI discards the output of command hooks on this event, so this hook injects nothing.
  194. - **`agentStop`** β†’ assistant messages are read from the supplied `events.jsonl` transcript path and added to the flight-recorder log.
  195. - Registers `mcpServers.engrim` (`engrim serve --mcp`) in `~/.copilot/mcp-config.json`, exposing the `engrim_*` tools. Records the agent writes are attributed to `copilot` automatically.
  196. - Configures `engrim statusline` in `~/.copilot/settings.json`, providing live curated, logged, in-play, and clear-safety counts. An existing custom status line is preserved.
  197. - Appends a usage note to `~/.copilot/copilot-instructions.md`.
  198. Hook entries use Copilot's `exec` + `args` form, which runs the binary directly with no shell in between, so a path containing spaces or backslashes needs no quoting. Hook configuration is read at startup: open a **new** session after setup.
  199. Copilot can flush the final assistant event shortly after `agentStop` begins, so Engrim polls briefly and recovers any later tail during the next session start. The event-file schema is not a public Copilot compatibility contract. Engrim detects incompatible known records without putting transcript content in diagnostics, warns once through the hook, and reports the persistent issue through `engrim doctor` until a compatible pass succeeds.
  200. #### 🟩 OpenCode
  201. ```bash
  202. engrim setup --opencode
  203. ```
  204. OpenCode has no shell hooks, so engrim ships as a plugin plus an MCP server:
  205. - Writes `~/.config/opencode/plugins/engrim.js` (respects `$XDG_CONFIG_HOME`). The plugin calls `engrim hook --agent opencode` at each lifecycle moment:
  206. - **session boot** β†’ memory pack is injected into system prompt (once per session, and again after compaction);
  207. - **every prompt** β†’ minder pulls the few records relevant to that message and attaches them to that user message, never to the system prompt, so the provider's prompt cache (vLLM prefix cache, Anthropic prompt caching) stays warm across turns;
  208. - **session idle** β†’ session's new user/assistant turns land in flight-recorder log (idempotent, keyed on OpenCode message ids);
  209. - **compaction** β†’ compaction prompt is told that durable memory lives in engrim and to list uncaptured decisions so they get `engrim_add`-ed.
  210. - Registers `mcp.engrim` (`engrim serve --mcp`) in `~/.config/opencode/opencode.json`, exposing `engrim_*` tools to the agent.
  211. - Appends usage note to `~/.config/opencode/AGENTS.md`.
  212. ###### OpenCode Transcript Store vs. Engrim
  213. `opencode.db` stores raw transcripts (sessions, messages, parts) for OpenCode alone. Engrim provides the universal cross-session memory layer:
  214. - **Cross-Harness Continuity**: Switch between OpenCode, Claude Code, Codex CLI, Cursor, or Antigravity on the same codebase from one `~/.engrim/memory.db`.
  215. - **Curated Episodic State**: Preserves typed records (`decision`, `fact`, `state`) that survive `/new`, session deletion, and compaction.
  216. - **Model-Driven Retrieval**: Hybrid FTS5 + vector recall (`engrim_recall`) and per-prompt minding with cross-agent provenance (`origin_agent`).
  217. #### πŸ™ GitHub Agentic Workflows (`gh-aw`)
  218. See [`examples/gh-aw/`](examples/gh-aw/) for engrim inside [GitHub Agentic Workflows](https://github.github.com/gh-aw/): memory across runs through artifacts and `engrim merge`, and a continue-as-clear restart instead of auto-compaction.
  219. #### All Platforms
  220. ```bash
  221. engrim setup --all
  222. ```
  223. `--all` configures Codex hooks and guidance but does not opt in to the Codex MCP server. Add `--codex-mcp` explicitly when you want that tool interface.
  224. *(Use `--dry-run` with any setup command to preview changes without writing to disk).*
  225. ---
  226. ## 4. Empirical Proof (The 105-Session Case Study)
  227. > **Tested across 105 continuous sessions on a 50,000-line algorithmic trading system. Zero regressions across 186 unit tests, zero context loss across model switches.**
  228. In production testing on an active algorithmic trading codebase running real capital:
  229. - Over **153,000 tokens of work** across days of architecture, parameter tuning, and debugging was consolidated into an active memory pack under **1,000 tokens** (<1% of the context window).
  230. - That is a **99%+ cut in reloaded context cost** on every session restart.
  231. - Seamlessly switched between Google Antigravity CLI, Claude Code, and Cursor MCP on identical repos with zero model drift or architectural regression.
  232. ---
  233. ## 5. Agent Provenance Tracking
  234. When multiple agents collaborate on a single codebase, provenance matters. `engrim` records the origin of every memory entry with the `origin_agent` field:
  235. - Allowed values: `antigravity`, `claude-code`, `cursor`, `codex`, `opencode`, `copilot`, `cli`, or `user`.
  236. - Automatically populated based on the active hook, MCP client, or CLI session.
  237. - Subtly surfaced in `engrim context` and `engrim list`:
  238. ```text
  239. 🧠 engrim · memory restored for this project: you don't have to re-explain · /workspace
  240. 18 of 54 curated records loaded (~3850 chars) Β· the rest one `recall` away
  241. [DECISION]
  242. - #961 [DECISION] (via Antigravity): Inverted stop loss matrix for high volatility (risk, execution)
  243. - #942 [DECISION] (via Claude Code): Switched primary database from MongoDB to PostgreSQL (db, schema)
  244. - #910 [DECISION] (via Cursor): Standardized on Pydantic v2 schemas across API boundaries (api, types)
  245. ```
  246. Existing databases are non-destructively migrated on first access via `ALTER TABLE memories ADD COLUMN origin_agent TEXT`.
  247. ---
  248. ## 6. Hardened Model Context Protocol (MCP) Server
  249. Launch the zero-dependency, JSON-RPC 2.0 stdio MCP server:
  250. ```bash
  251. engrim serve --mcp
  252. # or: engrim mcp
  253. ```
  254. `stdout` is strictly reserved for JSON-RPC messages, redirecting all diagnostic logs to `stderr`.
  255. ### Core MCP Tools Exposed:
  256. | Tool | Signature | Purpose |
  257. |---|---|---|
  258. | `engrim_recall` | `(query: str, project: str = "auto", k: int = 5, type: str = None, tag: str = None)` | Search project memory using hybrid ranking (optionally filter by type or tag). |
  259. | `engrim_add` | `(type: str, summary: str, detail: str = None, tags: list[str] = [])` | Write a durable memory record persisted across sessions. |
  260. | `engrim_context` | `(project: str = "auto", budget: int = 4000)` | Retrieve the session-boot memory pack within a character budget. |
  261. | `engrim_review` | `(project: str = "auto")` | Check uncaptured decisions from transcript logs before clearing. |
  262. `engrim_review` returns `safe_to_clear: null` (unknown) when the project has no transcript log. With logged turns, it evaluates whether uncaptured architectural decisions exist before a developer runs `/clear`.
  263. ---
  264. ## 7. CLI Reference
  265. | Command | Usage | Description |
  266. |---|---|---|
  267. | `engrim add` | `engrim add -t decision -s "..." [--origin-agent agy]` | Insert memory record (types: `decision`, `fact`, `feedback`, `state`, `user`, `reference`). |
  268. | `engrim recall` | `engrim recall -q "database" [--tag auth]` | Ranked hybrid recall for the project (`--tag` filters by tag; `--log` searches raw turns). |
  269. | `engrim context` | `engrim context [-b 4000]` | Priority-ordered, budget-capped session-boot pack. |
  270. | `engrim doctor` | `engrim doctor [--fix] [--json]` | Comprehensive health & environment diagnostic across SQLite, semantic engine, and hooks (`--fix` auto-repairs paths). |
  271. | `engrim hook` | `engrim hook --agent agy --event boot` | Agent lifecycle hook runner for Claude Code, Antigravity, Codex, Copilot CLI, and OpenCode (`--agent opencode --event boot\|prompt\|stop`). |
  272. | `engrim setup` | `engrim setup [--agy\|--claude\|--cursor\|--codex\|--codex-mcp\|--opencode\|--copilot\|--all] [--strict]` | Universal multi-agent environment configuration. `--codex-mcp` implies `--codex`; `--strict` wires gate mode. |
  273. | `engrim serve` | `engrim serve --mcp` | Start stdio MCP server for agent integrations. |
  274. | `engrim review` | `engrim review [--strict]` | "Safe to clear" coverage check: scans logs for uncurated decisions (`--strict` exits 2 if uncaptured). |
  275. | `engrim prune` | `engrim prune [--keep-days <N> \| --all \| --vacuum]` | Purge old transcript logs and VACUUM the SQLite DB (opt-in retention; off by default). |
  276. | `engrim list` | `engrim list [-k 20] [--tag auth]` | List recent memories for the current project (supports `--tag`). |
  277. | `engrim project` | `engrim project [-p PROJECT \| --global \| --all] [--json]` | Records, active count and last write for one project tag (the current one by default), or every tag with `--all`. |
  278. | `engrim projects` | `engrim projects [--json]` | Every project's counts: the same as `engrim project --all`. |
  279. | `engrim supersede`| `engrim supersede --id 12 --status superseded` | Mark a record superseded without erasing history. |
  280. | `engrim retire` | `engrim retire [--all] [--dry-run] [--json]` | Mark active `resume-pointer` record(s) done once their work is finished (never erases). |
  281. | `engrim sync` | `engrim sync [DIR]` | Mirror markdown memories into the store (idempotent seed-once). |
  282. | `engrim merge` | `engrim merge OTHER.db [--dry-run]` | Fold another store's records into this one (content-keyed, idempotent; retirements carry over). |
  283. | `engrim backup` | `engrim backup COPY.db [--force] [--json]` | Consistent copy of the store via SQLite's online backup API (safe while agents hold it open). |
  284. ---
  285. ## 8. Continue-As-Clear Workflow
  286. 1. **Capture as you work**: Whenever a major decision or architectural constraint is established, save it to memory. Connected agents do this automatically via `engrim_add`, or you can run `engrim add`.
  287. 2. **Use `resume-pointer`**: Before ending a session or clearing, add a record tagged `resume-pointer` describing the immediate next task. The newest pointer is pinned under `[β–Ά RESUME HERE]` at the top of the next session's boot pack. When that work is done, `engrim retire` marks the pointer `done` so finished tasks never lead later packs.
  288. 3. **Verify with `engrim review`**: Check that all recent decisions are captured before clearing.
  289. 4. **Clear freely (`/clear`)**: The session window is wiped clean. `engrim` automatically re-injects the active memory pack on the next prompt or invocation with zero context loss.
  290. ---
  291. ## 9. Open Core Architecture: Local vs. Enterprise
  292. Engrim maintains a strict, transparent architectural boundary between open-source single-developer productivity and enterprise infrastructure:
  293. | Capability | Engrim Open Source (Free, MIT) | Engrim Enterprise (Commercial In-VPC) |
  294. |:---|:---|:---|
  295. | **Target User** | Individual developers & local coding agents | Engineering teams & autonomous CI/CD pipelines |
  296. | **Storage Substrate** | 100% local SQLite WAL (`~/.engrim/memory.db`) | In-VPC high-throughput state collector & team repository |
  297. | **Retrieval Engine** | Hybrid FTS5 bm25 + `model2vec` (CPU, ~30ms) | Organization-wide semantic search & multi-tenant indexing |
  298. | **Agent Support** | Antigravity, Claude Code, Cursor, Codex, Copilot CLI, OpenCode | Distributed container fleets & autonomous CI state-machines |
  299. | **Integrity & Health** | `engrim doctor` diagnostic & self-healing hooks | Pre-commit AST invariant arbiter & deterministic validation |
  300. | **Security & Compliance** | POSIX `0600` owner permissions, offline | Secret & PII scrubber, cryptographic Merkle compliance ledger |
  301. | **Collaboration** | Local merge & backup (`engrim merge/backup`) | Multi-developer team memory federation & Linear-grade web UI |
  302. ---
  303. ## 10. How Does Engrim Compare?
  304. - **vs gbrain**: While gbrain is a provider-agnostic memory tool, `engrim` sets itself apart with a lightweight, local-first SQLite architecture. It requires zero cloud infrastructure, no complex daemon setup, and operates entirely on CPU.
  305. - **vs OpenCode & Codex Internal Stores**: Their built-in SQLite databases store *transcripts* (sessions, raw message parts, lossy compaction summaries) locked to one tool. `engrim` is a cross-tool *episodic* memory engine that tracks provenance across all your tools. With the OpenCode plugin, engrim serves as the durable memory layer rather than competing with it.
  306. - **vs Pi / Personal Companions**: Companion tools focus on social conversation history. `engrim` is engineered specifically for **software engineering projects**, preserving architectural decisions, invariant constraints, and technical state.
  307. ---
  308. <a id="security-privacy"></a>
  309. ## 11. Security & Privacy
  310. - **100% Local & Offline**: All memory records and flight-recorder logs reside in your local SQLite file (`~/.engrim/memory.db`). No telemetry, no cloud sync, no tracking.
  311. - **CPU-Only Vector Inference**: Uses `model2vec` for static embeddings (~30ms load time, no GPU required, runs on CPU). Can run pure-lexical (`ENGRIM_EMBED=off`) for zero extra dependencies.
  312. - **POSIX Owner Permissions**: Databases are created with restricted owner-only permissions (`0600`).
  313. - **Git Safe**: `*.db` is gitignored by default; memories are never accidentally committed to public version control.
  314. ---
  315. ## 12. About the Project & Author
  316. **Engrim** was created by **Tim Gordon** ([@timgordontg](https://github.com/timgordontg)).
  317. - **Website:** [engrim.dev](https://engrim.dev)
  318. - **GitHub:** [github.com/timgordontg/engrim](https://github.com/timgordontg/engrim)
  319. - **LinkedIn:** [linkedin.com/in/timgordon1](https://www.linkedin.com/in/timgordon1)
  320. - **Email:** [timgordontg@gmail.com](mailto:timgordontg@gmail.com)
  321. Tim built Engrim to establish the definitive open-source standard for agent episodic memory, giving developers complete freedom from vendor lock-in.
  322. For enterprise licensing, advisory, pilot deployments, or custom agent integrations, reach out at [timgordontg@gmail.com](mailto:timgordontg@gmail.com).
  323. ---
  324. ## 13. License
  325. MIT Β© 2026 Tim Gordon.

Ratings and comments

Sign in to rate this skill.

Sign in

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