Engrim 1.3.0: Local‑First SQLite Memory Engine for Multi‑Model AI CLIs

TL;DR

Engrim 1.3.0 provides a local‑first SQLite‑backed episodic memory layer for AI coding assistants (Google Antigravity, Claude Code, Cursor, Windsurf), enabling seamless model switches and context persistence while keeping all data offline and private.

---

Core Value Proposition

Engrim replaces the growing “attention dilution” problem—where large token windows become noisy and expensive—with a 4 KB curated working memory stored in SQLite. The key benefits are:

• Vendor‑agnostic continuity – Switch from Gemini 3.8 to Claude 3.7 Sonnet to GPT‑4o mid‑project and retain decisions, constraints, and architecture without re‑explaining.
• Explicit save‑button semantics – Developers can clear an agent’s session (/clear) while Engrim automatically reloads the curated memory pack.
• Hybrid retrieval – Combines FTS5 BM25 lexical search with static model2vec embeddings in a zero‑latency reciprocal‑rank fusion engine.

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

---

Empirical Evidence (105‑Session Case Study)

A production test on a 50 k‑line algorithmic‑trading codebase showed:

• 153 000 tokens of work were compressed into < 1 000 tokens of active memory (≈ 99 % reduction).
• Zero regressions across 186 unit tests after switching between Antigravity, Claude Code, and Cursor.
• No context amnesia was observed when agents were swapped mid‑project.

The author notes that the test involved continuous sessions, but the discussion on Hacker News raised questions about benchmark comparability and handling of unclean exits.

---

Architecture Overview

Agents (Antigravity, Claude Code, Cursor/Windsurf) → Adapters & Hooks →
   Provenance Engine (origin_agent tracking) →
   Hybrid Retrieval (bm25 + vector) →
   SQLite Store (~/.engrim/memory.db)

• Memories table – Stores curated records (decisions, facts, feedback).
• FTS5 – Full‑text search with Porter stemming and triggers.
• Vector column – Static model2vec embeddings for semantic recall.
• Flight Recorder Log – Raw turn‑by‑turn transcript for audit and review.

---

Quickstart for Multi‑Agent Environments

pip install engrim
engrim setup            # auto‑detects Antigravity, Claude, Cursor, Windsurf
# or explicit per‑agent setup
engrim setup --agy      # Antigravity hooks
engrim setup --claude   # Claude Code hooks
engrim setup --cursor   # Cursor MCP registration
engrim setup --all      # configure every supported agent

Use --dry-run to preview file changes without writing.

---

Provenance Tracking

Every memory entry records an origin_agent field (antigravity, claude-code, cursor, cli, user). Example output of engrim list:

[DECISION]
- #961 (via Antigravity): Inverted stop‑loss matrix for high volatility
- #942 (via Claude Code): Switched primary DB from MongoDB to PostgreSQL
- #910 (via Cursor): Standardized on Pydantic v2 schemas

Existing databases are migrated automatically with an ALTER TABLE that adds the provenance column.

---

Model Context Protocol (MCP) Server

Run a zero‑dependency JSON‑RPC 2.0 stdio server:

engrim serve --mcp   # or simply `engrim mcp`

The server reserves stdout for JSON‑RPC messages and sends diagnostics to stderr.

Core MCP Methods

Method	Signature	Purpose
engrim_recall	(query: str, project: str = "auto", k: int = 5, type: str = None)	Hybrid keyword + semantic search.
engrim_add	(type: str, summary: str, detail: str = None, tags: list[str] = [])	Persist a memory record.
engrim_context	(project: str = "auto", budget: int = 4000)	Return a budget‑capped memory pack for session boot.
engrim_review	(project: str = "auto")	Scan logs for uncaptured decisions before clearing.

---

CLI Reference (selected commands)

Command	Example	Description
engrim add	engrim add -t decision -s "..."	Insert a memory record (types: decision, fact, feedback, state, user, reference).
engrim recall	engrim recall -q "database"	Hybrid ranked recall for the current project.
engrim context	engrim context -b 4000	Retrieve the priority‑ordered, character‑budgeted boot pack.
engrim hook	engrim hook --agent agy --event boot	Execute lifecycle hook for Antigravity or Claude Code.
engrim serve	engrim serve --mcp	Start the MCP server for agent integration.
engrim review	engrim review	Verify that all recent decisions are captured before a clear.
engrim list	engrim list -k 20	Show recent memories for the current project.

---

"Continue‑as‑Clear" Workflow

1. Capture – Use engrim add (or the MCP engrim_add) whenever a decision or rule is made.
2. Pin a resume pointer – Add a record tagged resume-pointer describing the next immediate task; the newest pointer appears as [▶ RESUME HERE] on the next boot.
3. Review – Run engrim review to ensure no important decision is missing.
4. Clear – Issue /clear in the agent; Engrim automatically injects the curated memory pack on the next prompt.

---

Security & Privacy Guarantees

• 100 % local & offline – All data lives in ~/.engrim/memory.db; no telemetry or cloud sync.
• File permissions – SQLite file created with 0600 (owner‑only) permissions.
• Git safety – *.db is git‑ignored by default, preventing accidental commits.
• Optional embeddings – Set ENGRIM_EMBED=off to run purely lexical search, eliminating the need for the model2vec package.

---

Community Feedback (Hacker News Highlights)

@thih9: “Run engrim setup without arguments… Does it come with an uninstall script?” – Users are asking for a clean‑up utility; the repo currently does not ship one.

@aidiveyt: “Stop hooks can block the turn too: exit 2 with a message and the session keeps working until the check passes.” – Indicates that hook failures are propagated correctly, preserving session stability.

@corv: “I’m using gbrain as provider‑agnostic memory but miss how lightweight SQLite is in practice, so this is interesting!” – Highlights the appeal of SQLite’s minimal footprint compared to other memory back‑ends.

@dsemakin: “What triggers a memory getting written in practice? is it on me to remember engrim add?” – Clarifies that memory creation is explicit; developers must invoke engrim add (or the MCP engrim_add) to record a fact.

@flippant: “I’ve been using another memory plugin… decision summaries look really cool – though the agent/model info probably won’t be useful for me because I never let agents commit code autonomously.” – Positive comparison to existing tools, noting that provenance metadata may be optional for some workflows.

@esafak: “Could you expand on the 105‑session case study? … No lifecycle management or conflict resolution yet, and the models do the work of deciding when to use it.” – Calls for more rigorous benchmarking and clarification of conflict handling.

@quietraster: “How do you handle conflicts when two agents write to the same SQLite store?” – The current design relies on SQLite’s transactional guarantees; concurrent writes are serialized, but higher‑level conflict resolution is not yet implemented.

---

Limitations & Open Questions

• Benchmarking – The published case study lacks a direct comparison to competing memory plugins (e.g., ctx.rs). Independent benchmarks would help quantify the 99 % token reduction claim.
• Conflict resolution – While SQLite prevents corruption, the repository does not yet provide a strategy for reconciling divergent edits from multiple agents.
• Uninstall support – No built‑in script to remove hooks or delete the memory database; users must clean up manually.
• Cross‑device sync – The tool is deliberately local‑first; synchronizing the SQLite file across machines would require external solutions (e.g., rsync, cloud‑mounted drives).

---

License

Engrim is released under the MIT License (© 2026 Tim Gordon).