This server provides persistent, project-scoped memory tools for coding agents to recall, save, and review context across sessions.
engrim_recall: Search memories with hybrid keyword/semantic ranking, optionally filtered by type, tag, project, or including stale records.
engrim_context: Retrieve a budget-capped session-boot memory pack to orient at the start of work.
engrim_add: Save durable memory records (decisions, facts, feedback, state, references, user constraints) with optional tags, detail, project scope, global layer, and origin-agent provenance.
engrim_review: Check whether recent transcript decisions are captured in memory, giving a safe_to_clear verdict when log data exists.
Provides memory integration for Windsurf (by Codeium), allowing agents to save and recall project context, decisions, and user constraints across sessions.
Allows memory persistence across GitHub Actions workflow runs via artifacts and engrim merge, enabling continuation without context loss.
The Universal Cross-Model & Cross-Agent Episodic Memory Store.
A local-first, project-scoped SQLite memory engine that allows developers to freely switch between models and environments (Google Antigravity, Claude Code, Cursor MCP, Windsurf) on the SAME project without losing architectural decisions, user constraints, or project state.
"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, 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. The connected AI agents (Antigravity, Claude Code, Cursor, Codex, Codex CLI) can automatically write to memory via MCP tools when they make architectural decisions, or you can manually save them (engrim add). Clear your agent session freely (/clear) and watch context reload intact.
Smart, Hot Context Loading: Combines SQLite FTS5 (bm25 keyword search) with static vector embeddings (model2vec) in a zero-latency hybrid reciprocal-rank fusion engine.
Related MCP server: agentmem
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.
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/>(Hooks & MCP)"]
end
subgraph CoreEngine ["engrim Core Engine (v1.4.0)"]
ADAPTERS["Adapters & Hooks<br/>(agy, claude, mcp)"]
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 <-->|"hook / MCP"| ADAPTERS
ADAPTERS --> PROVENANCE
PROVENANCE --> ROUTER
ROUTER --> MEMORIES
MEMORIES --- FTS5
MEMORIES --- VEC
ADAPTERS --> LOGpip install engrimRun engrim setup without arguments. It automatically detects installed environments on your machine and configures them all:
engrim setupIf ~/.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 hooks and MCP server.
engrim setup --agyConfigures ~/.gemini/config/hooks.json to execute engrim hook --agent agy --event boot on PreInvocation and engrim hook --agent agy --event stop on Stop.
Deploys the canonical Antigravity skill to ~/.gemini/config/skills/engrim/SKILL.md.
Registers the MCP server in ~/.gemini/antigravity-cli/mcp_config.json and ~/.gemini/config/mcp_config.json.
engrim setup --claudeWires 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.
engrim setup --cursorAdds engrim to ~/.cursor/mcp.json running engrim serve --mcp.
engrim setup --codexWires SessionStart, SessionEnd, Stop, and UserPromptSubmit hooks in ~/.codex/hooks.json.
Registers the MCP server in ~/.codex/config.toml.
Add engrim to your ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"engrim": {
"command": "engrim",
"args": ["serve", "--mcp"]
}
}
}engrim setup --allConfigures every supported environment in one command.
(Use --dry-run with any setup command to inspect changes without modifying disk).
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.
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, 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.
Launch the zero-dependency, JSON-RPC 2.0 stdio MCP server:
engrim serve --mcp
# or: engrim mcpstdout is strictly reserved for JSON-RPC messages, redirecting all diagnostic logs to stderr.
Tool | Signature | Purpose |
|
| Search project memory using hybrid ranking (optionally filter by type or tag). |
|
| Write a durable memory record persisted across sessions. |
|
| Retrieve the session-boot memory pack within a character budget. |
|
| Check uncaptured decisions from transcript logs before clearing. |
engrim_review returns safe_to_clear: null (unknown) when the project has no transcript log,
even if it has saved memories. With logged turns, the field is a boolean heuristic verdict:
false means possible uncaptured decisions were detected; true means none were detected in
the reviewed log. It does not verify that logging captured the entire session.
Command | Usage | Description |
|
| Insert memory record (types: |
|
| Ranked hybrid recall for the project ( |
|
| Priority-ordered, budget-capped session-boot pack. |
|
| Agent lifecycle hook runner for Antigravity and Claude Code. |
|
| Universal multi-agent environment configuration ( |
|
| Start stdio MCP server for agent integrations. |
|
| "Safe to clear" coverage check: scans logs for uncurated decisions ( |
|
| Purge old transcript logs and VACUUM the SQLite DB (opt-in retention; off by default). |
|
| List recent memories for the current project (supports |
|
| Records, active count and last write for one project tag (the current one by default), or every tag with |
|
| Every project's counts — the same as |
|
| Mark a record superseded without erasing history. |
|
| Mark the active |
|
| Mirror markdown memories into the store (idempotent seed-once). |
|
| Fold another store's records into this one (content-keyed, idempotent; retirements carry over). |
|
| Consistent copy of the whole store via SQLite's online backup API (safe while agents hold it open). |
Capture as you work: Whenever a major decision or architectural rule is made, it needs to be saved to memory. The AI agent will often do this automatically via the engrim_add tool, but you can also manually intervene by running engrim add yourself.
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(s) done so a finished task never leads a later pack.
Verify with engrim review: Check that all recent decisions are captured.
Clear freely (/clear): The session window is wiped clean; engrim automatically re-injects the active memory pack on the next prompt or invocation.
There are several other memory solutions and coding assistants out there (such as gbrain, OpenCode, Codex, and Pi). Here is how engrim differs:
vs gbrain: While gbrain is a great provider-agnostic memory tool, engrim sets itself apart by using a lightweight, local-first SQLite architecture. This keeps everything fast and offline without needing complex setup or cloud dependencies.
vs OpenCode & Codex: While other solutions may have built-in SQLite or memory components, engrim is specifically designed as an episodic memory engine that tracks the provenance of decisions across multiple different agents (Antigravity, Claude Code, Cursor, Codex, Codex CLI). It operates as a unified backend that all your tools can share.
vs Pi: Pi acts as a personal AI companion with a long-term memory. engrim is specifically tailored for coding projects and software architecture—capturing decisions, state, and constraints in a format that coding agents can efficiently query via hybrid search (FTS5 + vector).
100% Local & Offline: All memory records and logs reside in a local SQLite file (~/.engrim/memory.db). No telemetry, no cloud sync, no tracking.
Model Storage: Uses model2vec for local static embeddings (~30ms load time, no GPU required, runs on CPU). Can run pure-lexical (ENGRIM_EMBED=off) for zero extra dependencies.
POSIX File Permissions: Databases are created with restricted owner-only permissions (0600).
Git Protection: *.db is gitignored by default; your memories never accidentally commit to version control.
Created by Tim Gordon (@timgordontg).
LinkedIn: linkedin.com/in/timgordon1
Email: timgordontg@gmail.com
Open to collaborations and Staff / Senior engineering opportunities in Agentic AI, Developer Tooling, and Systems Engineering.
MIT © 2026 Tim Gordon.
Write a durable memory record so it persists across sessions. Use at real decision points and for durable facts/feedback/state.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| type | Yes | ||
| detail | No | Optional longer body / the why. | |
| global | No | Write to the global user-layer that loads in every project. | |
| project | No | auto | |
| summary | Yes | One-line headline for the record. | |
| origin_agent | No | Origin agent identifier for provenance tracking. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries a heavier burden. It adds the concrete behavior that records persist across sessions and are durable, which is helpful. It does not disclose side effects, overwrite semantics, permissions, or latency. Given the simple 'add' nature, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the core purpose and then provide direct usage guidance. There is no filler and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, no-output-schema, no-annotation tool, the description is short. It covers why (durability) and when (decision points, facts) but does not outline the fields, the exact semantics of type, or how the memory is structured. Enough for a rough call, but could be richer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 57% and the description adds minimal value beyond it. It hints at 'facts/feedback/state' which map to the type enum, but it does not clarify the roles of summary, tags, detail, global, project, or origin_agent. An agent would have to rely mostly on the bare schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Write') and the resource ('durable memory record') plus an explicit behavioral promise (persists across sessions). It is easily distinguished from sibling tools like engrim_recall or engrim_context, which are about reading or retrieving, not writing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance: 'Use at real decision points and for durable facts/feedback/state.' This is useful contextual selection information. It does not name the sibling alternatives or state when not to use it, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the project's session-boot memory pack — the curated, high-signal records that orient you at the start of work, within a character budget.
| Name | Required | Description | Default |
|---|---|---|---|
| budget | No | Character budget for the pack. | |
| project | No | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates a read-like operation ('Return') but does not explicitly state it is read-only, nor does it mention any side effects, truncation behavior, or limits beyond the character budget parameter. It lacks details on what happens if the budget is exceeded or how the pack is constructed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core action and resource. It avoids unnecessary fluff and is appropriately sized for the tool's simplicity, though it could arguably add more structure or bullet points if needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, and the incomplete parameter information (project is undocumented), the description is insufficient for an agent to confidently invoke the tool. It does not explain the return format, what constitutes 'high-signal records,' or how the project parameter behaves. The tool is simple, but the missing context around parameters and output leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'within a character budget,' which aligns with the budget parameter, but the project parameter is completely undocumented in the schema (0% schema description) and the description does not clarify it. With 50% schema coverage, the description fails to compensate for the missing parameter meaning, leaving agents uncertain about the 'auto' default and acceptable values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and a clearly defined resource ('the project's session-boot memory pack'), and even elaborates on its purpose ('curated, high-signal records that orient you at the start of work'). This distinguishes it from sibling tools like engrim_recall or engrim_add, which clearly serve different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is intended for session start ('orient you at the start of work') but provides no explicit guidance on when to use this tool over alternatives, nor any exclusions or prerequisites. There is no mention of when not to use it or how it differs from engrim_recall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search this project's engrim memory for records relevant to a query (hybrid keyword + semantic ranking). Use before non-trivial work to recall prior decisions, facts, feedback, and state.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | Max records to return. | |
| tag | No | Optional: filter records by tag (e.g. 'auth'). | |
| type | No | Optional: restrict to one record type. | |
| query | Yes | Free-text topic to search for. | |
| project | No | Project tag; 'auto' = current working directory. | auto |
| include_stale | No | Include superseded/archived records. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses hybrid keyword + semantic ranking behavior and implies a read-only operation by saying 'Search... and recall.' It does not mention any side effects, performance constraints, or output format, which is a gap, but the ranking behavior adds meaningful detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no fluff. The first sentence states the action and method, and the second adds contextual usage guidance. Key information is front-loaded and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex (6 parameters, mostly optional) and has no output schema. The description explains when to use it and what it recalls, but does not describe the return structure or ordering. Given the absence of an output schema, a small note on return format would enrich complete picture, though it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, so the schema already documents each parameter. The description does not add extra beyond what the schema provides (max records, filtering by tag/type, project, include_stale). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function as searching the project's engrim memory with hybrid keyword + semantic ranking, and specifies the resource ('engrim memory'). It distinguishes this retrieval action from likely sibling tools (add, review, context) by stating it recalls prior decisions, facts, feedback, and state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use before non-trivial work to recall prior decisions...', giving a clear context for when to invoke the tool. However, it does not mention alternatives or exclusion criteria, though the usage window is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check coverage before clearing context: surface recent decisions from the transcript log that don't appear to be in curated memory yet. safe_to_clear is null (unknown) when this project has no transcript log; otherwise it is a boolean heuristic verdict about the available log.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project tag; 'auto' = current working directory. | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of explaining behavior. It discloses that the result is a heuristic verdict and that null means 'unknown because no transcript log exists', giving important runtime context without pretending to be authoritative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences, front-loads the purpose, and includes the important safe_to_clear edge case without fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single optional parameter and no output schema, it explains both the main output and the null safe_to_clear edge case. It could have specified the exact output shape of the surfaced decisions, but is still complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the only parameter (project, default 'auto'), and the description does not add anything about project semantics, valid values, or edge cases. Baseline 3 is appropriate because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it checks coverage by surfacing recent transcript-log decisions that are not yet in curated memory. This is specific and clearly separate from recall/add/context behavior, though it does not explicitly name sibling tools for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives actionable timing guidance ('before clearing context') and explains the safe_to_clear result semantic, including the null case for missing transcript logs. It does not explicitly say when NOT to use it or name alternatives, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0engrim_addengrim_contextengrim_recallengrim_reviewScored across 4 tools
Each tool has a clearly distinct role: adding durable records, retrieving the curated boot pack, searching memory, and reviewing coverage before clearing context. There is no overlap or ambiguity between them.
All tools share the `engrim_` prefix and are mostly verb-oriented (add, recall, review). `engrim_context` uses a noun rather than a verb, but the pattern is still predictable and easy to follow.
Four tools cover the full memory workflow without redundancy. This is a well-scoped set for a persistent memory server — enough to be useful without overwhelming the agent.
The surface covers the core memory lifecycle: write, retrieve, search, and review coverage. There is no explicit delete/update tool, which could be a minor gap for correcting stale records, but the core functionality is solid.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Shared memory for coding agents. Stop re-explaining your codebase every session.
