engrim

The Universal Cross-Model & Cross-Agent Episodic Memory Standard.

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, OpenCode, and Windsurf) on the same codebase without losing architectural decisions, user constraints, or project state.

1. The Core Value Proposition

"Why pay for 200,000 tokens of forgotten noise on every turn? The models are disposable utilities; your project's decisions are not."

As context windows scale to 1M+ tokens, developers face attention dilution: reasoning degrades, token cost multiplies with every conversational turn, and clearing context causes total amnesia.

engrim replaces attention dilution with 4,000 characters of curated episodic working memory:

• Switzerland of AI Memory: Decouples project intelligence from any single AI vendor or proprietary cloud silo. Switch from Gemini 3.8 in Antigravity to Claude 3.7 Sonnet in Claude Code to Codex CLI mid-project — your agents pick up right where the others left off.
• Save Button for Autonomous Coding: Externalize decisions, constraints, and state as you work. Connected agents write to memory via MCP tools (engrim_add) or lifecycle hooks when they make architectural decisions. Clear your agent session freely (/clear) and watch context reload intact.
• Precision, Hot Context Loading: Combines SQLite FTS5 (bm25 keyword search) with static vector embeddings (model2vec) in a zero-latency hybrid reciprocal-rank fusion engine. 100% local, runs on CPU in ~30ms, with zero cloud dependency.

The Problem vs. The Engrim Standard

2. Empirical Proof (The 105-Session Case Study)

Tested across 105 continuous sessions on a 50,000-line algorithmic trading system. Zero regressions across 186 unit tests, zero context amnesia across model switches.

In production testing on an active algorithmic trading codebase running real capital:

• 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).
• That is a 99%+ cut in reloaded context cost on every session restart.
• Seamlessly switched between Google Antigravity CLI, Claude Code, and Cursor MCP on identical repos with zero model drift or architectural regression.

3. How It Works (The 10-Second Mental Model)

graph TD
    subgraph Agents ["Supported Agent Environments"]
        AGY["Google Antigravity<br/>(PreInvocation & Stop Hooks)"]
        CLAUDE["Claude Code<br/>(SessionStart & Stop Hooks)"]
        CURSOR["Cursor / Windsurf<br/>(Model Context Protocol stdio)"]
        CODEX["Codex CLI<br/>(Native command hooks)"]
        OPENCODE["OpenCode<br/>(Plugin & MCP)"]
    end

    subgraph CoreEngine ["engrim Core Engine (v1.4.5)"]
        ADAPTERS["Adapters & Lifecycle Hooks<br/>(agy, claude, opencode, mcp)"]
        DOCTOR["Health & Diagnostic Engine<br/>(engrim doctor --fix)"]
        PROVENANCE["Agent Provenance Engine<br/>(origin_agent tracking)"]
        ROUTER["Hybrid Retrieval & Minder<br/>(bm25 lexical + vector cosine)"]
    end

    subgraph Storage ["Local-First SQLite Store (~/.engrim/memory.db)"]
        MEMORIES[("Curated Memories<br/>(decisions, facts, feedback)")]
        FTS5["FTS5 Full-Text Search<br/>(porter stemmer, triggers)"]
        VEC["Vector Embeddings<br/>(model2vec static embeddings)"]
        LOG["Flight Recorder Log<br/>(turns + action lines)"]
    end

    AGY <-->|"hook / CLI"| ADAPTERS
    CLAUDE <-->|"hook / CLI"| ADAPTERS
    CURSOR <-->|"JSON-RPC (stdio)"| ADAPTERS
    CODEX <-->|"command hook"| ADAPTERS
    OPENCODE <-->|"plugin / MCP"| ADAPTERS
    ADAPTERS --> PROVENANCE
    PROVENANCE --> ROUTER
    ROUTER --> MEMORIES
    MEMORIES --- FTS5
    MEMORIES --- VEC
    ADAPTERS --> LOG

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].
2. Capture: As the agent works, it records architectural decisions via MCP (engrim_add) or lifecycle hooks automatically, tracking the origin_agent provenance.
3. Recall & Minder: Hybrid lexical (bm25) + vector (model2vec) search retrieves relevant records on demand in ~30ms without slowing down the agent.
4. Continue-As-Clear: When context bloats or the model drifts, type /clear. The next session boots from memory.db with zero memory loss.

4. Multi-Agent Quickstart

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.
• If ~/.config/opencode exists $\rightarrow$ writes OpenCode plugin, registers MCP server, and adds AGENTS.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

================================================================================
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 amnesia 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.
• Registers MCP server in ~/.gemini/antigravity-cli/mcp_config.json and ~/.gemini/config/mcp_config.json.

🟣 Claude Code

engrim setup --claude

• Wires SessionStart, SessionEnd, Stop, and UserPromptSubmit hooks in ~/.claude/settings.json.
• Configures live ambient status line in Claude Code's status bar.
• Appends memory usage notes to ~/.claude/CLAUDE.md.

⚡ Cursor & Windsurf

engrim setup --cursor

• Adds engrim to ~/.cursor/mcp.json running engrim serve --mcp.

For Windsurf, add engrim to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "engrim": {
      "command": "engrim",
      "args": ["serve", "--mcp"]
    }
  }
}

💻 Codex CLI

engrim setup --codex

• Wires SessionStart, SessionEnd, Stop, and UserPromptSubmit command hooks in ~/.codex/hooks.json.
• Calls local engrim CLI directly (MCP not required). Hooks must be reviewed and trusted with Codex's /hooks command before they run.

🟩 OpenCode

engrim setup --opencode

OpenCode has no shell hooks, so engrim ships as a plugin plus an MCP server:

• Writes ~/.config/opencode/plugins/engrim.js (respects $XDG_CONFIG_HOME). The plugin calls engrim hook --agent opencode at each lifecycle moment:
  • session boot → memory pack is injected into system prompt (once per session, and again after compaction);
  • every prompt → minder pulls the few records relevant to that message;
  • session idle → session's new user/assistant turns land in flight-recorder log (idempotent, keyed on OpenCode message ids);
  • compaction → compaction prompt is told that durable memory lives in engrim and to list uncaptured decisions so they get engrim_add-ed.
• Registers mcp.engrim (engrim serve --mcp) in ~/.config/opencode/opencode.json, exposing engrim_* tools to the agent.
• Appends usage note to ~/.config/opencode/AGENTS.md.

"OpenCode already has a SQLite database — why add engrim?"

It does, and it is good at what it is for. opencode.db holds sessions, messages, and parts: it is the transcript store for one tool. It has no memory table, no cross-session retrieval the model can call, and nothing outside OpenCode can read it. engrim solves a different problem:

• Switch harnesses on the same task. Start in OpenCode, finish in Claude Code, Codex CLI, Cursor, or Antigravity. Every one of them boots from the same ~/.engrim/memory.db.
• Curated memory, not replayed history. OpenCode's compaction summaries are lossy, regenerated each time, and gone with the session. engrim stores typed records (decision, fact, state, feedback, user, reference) that can be superseded, tagged, and retired.
• Survives /new, compaction, and deleted sessions. With engrim the boot pack is injected again on every session and after compaction, and the resume pointer says exactly where to pick up.
• Model-driven retrieval. Hybrid FTS5 + vector recall (engrim_recall), a per-prompt minder, and explicit write access (engrim_add).
• Cross-agent provenance. Every record carries origin_agent, so you know if a constraint came from Codex or OpenCode.
• Portable and yours. One SQLite file you can engrim backup, engrim merge, and share with ENGRIM_PROJECT.

🐙 GitHub Agentic Workflows (gh-aw)

See examples/gh-aw/ for engrim inside GitHub Agentic Workflows: memory across runs through artifacts and engrim merge, and a continue-as-clear restart instead of auto-compaction.

All Platforms

engrim setup --all

(Use --dry-run with any setup command to preview changes without writing to disk).

5. Agent Provenance Tracking

When multiple agents collaborate on a single codebase, provenance matters. engrim records the origin of every memory entry with the origin_agent field:

• Allowed values: antigravity, claude-code, cursor, opencode, cli, or user.
• Automatically populated based on the active hook, MCP client, or CLI session.
• Subtly surfaced in engrim context and engrim list:

🧠 engrim · memory restored for this project — you don't have to re-explain · /workspace
  18 of 54 curated records loaded (~3850 chars) · the rest one `recall` away

[DECISION]
- #961 [DECISION] (via Antigravity): Inverted stop loss matrix for high volatility  (risk, execution)
- #942 [DECISION] (via Claude Code): Switched primary database from MongoDB to PostgreSQL  (db, schema)
- #910 [DECISION] (via Cursor): Standardized on Pydantic v2 schemas across API boundaries  (api, types)

Existing databases are non-destructively migrated on first access via ALTER TABLE memories ADD COLUMN origin_agent TEXT.

6. Hardened Model Context Protocol (MCP) Server

Launch the zero-dependency, JSON-RPC 2.0 stdio MCP server:

engrim serve --mcp
# or: engrim mcp

stdout is strictly reserved for JSON-RPC messages, redirecting all diagnostic logs to stderr.

Core MCP Tools Exposed:

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.

7. CLI Reference

8. Continue-As-Clear Workflow

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.
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.
3. Verify with engrim review: Check that all recent decisions are captured before clearing.
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.

9. Open Core Architecture: Local vs. Enterprise

Engrim maintains a strict, transparent architectural boundary between open-source single-developer productivity and enterprise infrastructure:

10. How Does Engrim Compare?

• 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.
• 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.
• 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.

11. Security & Privacy

• 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.
• 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.
• POSIX Owner Permissions: Databases are created with restricted owner-only permissions (0600).
• Git Safe: *.db is gitignored by default; memories are never accidentally committed to public version control.

12. Author & Community

Created by Tim Gordon (@timgordontg).

• LinkedIn: linkedin.com/in/timgordon1
• Email: [email protected]
• GitHub: github.com/timgordontg/engrim

Founder & Creator @ Engrim. Raising a $2.0M Seed round for In-VPC Autonomous CI infrastructure. For enterprise licensing, pilot deployments, or investment inquiries: [email protected].

13. License

MIT © 2026 Tim Gordon.