engrim: De Universele Episodische Geheugenstandaard voor Cross-Model en Cross-Agent systemen

1. De Kernwaarde

"Waarom betalen voor 200.000 tokens aan vergeten ruis bij elke beurt? Modellen zijn vervangbare hulpmiddelen; de beslissingen van uw project zijn dat niet."

Naarmate contextvensters groeien naar 1 miljoen+ tokens, krijgen ontwikkelaars te maken met 'aandachtsverdunning': de redeneerkracht neemt af, de kosten vermenigvuldigen zich bij elke conversationele beurt, en het wissen van de context leidt tot totale amnesie.

engrim vervangt deze aandachtsverdunning door 4.000 tekens aan gecureerd episodisch werkgeheugen:

• Het Zwitserland van AI-geheugen: Ontkoppelt projectintelligentie van een specifieke AI-leverancier of een proprietary cloud-silo. Schakel halverwege een project over van Gemini 3.8 in Antigravity naar Claude 3.7 Sonnet in Claude Code of GPT-4o in Cursor — uw agents vallen precies in het spoor waar de vorige stopte.
• De 'Opslagknop' voor autonoom coderen: Externaliseer beslissingen, beperkingen en status terwijl u werkt. Wis uw agentsessie gerust (/clear) en zie hoe de context intact wordt herladen.
• Slimme, snelle context-laadfuncties: Combineert SQLite FTS5 (bm25 trefwoordzoekopdracht) met statische vector-embeddings (model2vec) in een zero-latency hybride reciprocal-rank fusion engine.

2. Empirisch Bewijs (Case Study van 105 sessies)

Getest over 105 continue sessies op een algoritmisch handelssysteem van 50.000 regels code. Dit resulteerde in nul regressies over 186 unit-tests en geen context-amnesie bij het wisselen van modellen.

Bij productietesten op een actieve codebase voor algoritmische handel met echt kapitaal:

• Meer dan 153.000 tokens aan werk over meerdere dagen (architectuur, parameter-tuning en debugging) werden geconsolideerd in een actief geheugenpakket van minder dan 1.000 tokens (<1% van het contextvenster).
• Dit betekent een verlaging van meer dan 99% in de kosten voor het herladen van de context bij elke herstart van de sessie.
• Naadloos gewisseld tussen Google Antigravity CLI, Claude Code en Cursor MCP op identieke repositories zonder modeldrift of architecturale regressie.

3. Architectuur

Agent-omgevingen (Supported Agent Environments)

• Google Antigravity (PreInvocation & Stop Hooks)
• Claude Code (SessionStart & Stop Hooks)
• Cursor / Windsurf (Model Context Protocol stdio)

engrim Core Engine (v1.3.0)

• Adapters & Hooks (agy, claude, mcp)
• Agent Provenance Engine (tracking van origin_agent)
• Hybrid Retrieval & Minder (bm25 lexicaal + vector cosinus)

Local-First SQLite Store (~/.engrim/memory.db)

• Gecureerde herinneringen (beslissingen, feiten, feedback)
• FTS5 Full-Text Search (porter stemmer, triggers)
• Vector Embeddings (model2vec statische embeddings)
• Flight Recorder Log (beurten + actieregels)

Interactie: De Agent-omgevingen communiceren via hooks, CLI of JSON-RPC (stdio) met de Adapters, die vervolgens via de Provenance Engine en de Router communiceren met de SQLite Store.

4. Snelstart voor Multi-Agent

Installatie

pip install engrim

Automatische Detectie (Aanbevolen)

Voer engrim setup uit zonder argumenten. Het detecteert automatisch de geïnstalleerde omgevingen op uw machine en configureert deze:

• Als ~/.gemini bestaat → koppelt Antigravity lifecycle hooks, skill en MCP-server.
• Als ~/.claude bestaat → koppelt Claude Code SessionStart, Stop, statusregel en CLAUDE.md.
• Als ~/.cursor bestaat → genereert en voegt de Cursor MCP-configuratie samen.

Expliciete Platform-setup

Google Antigravity

engrim setup --agy

• Configureert ~/.gemini/config/hooks.json om engrim hook --agent agy --event boot uit te voeren bij PreInvocation en engrim hook --agent agy --event stop bij Stop.
• Implementeert de canonieke Antigravity skill in ~/.gemini/config/skills/engrim/SKILL.md.
• Registreert de MCP-server in ~/.gemini/antigravity-cli/mcpconfig.json en ~/.gemini/config/mcpconfig.json.

Claude Code

engrim setup --claude

• Koppelt SessionStart, SessionEnd, Stop en UserPromptSubmit hooks in ~/.claude/settings.json.
• Configureert een live ambient statusregel in de statusbalk van Claude Code.
• Voegt aantekeningen over geheugengebruik toe aan ~/.claude/CLAUDE.md.

Cursor

engrim setup --cursor

• Voegt engrim toe aan ~/.cursor/mcp.json met het commando engrim serve --mcp.

Windsurf

Voeg engrim toe aan uw ~/.codeium/windsurf/mcp_config.json:

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

Alle Platforms

engrim setup --all Configureert elke ondersteunde omgeving in één commando. (Gebruik --dry-run bij elk setup-commando om wijzigingen te inspecteren zonder de schijf aan te passen).

5. Tracking van Agent-Herkomst (Agent Provenance)

Wanneer meerdere agents samenwerken aan één codebase, is de herkomst van informatie essentieel. engrim registreert de oorsprong van elke geheugenentry met het veld origin_agent.

• Toegestane waarden: antigravity, claude-code, cursor, cli, of user.
• Vulling: Wordt automatisch ingevuld op basis van de actieve hook, MCP-client of CLI-sessie.
• Zichtbaarheid: Wordt subtiel getoond in de engrim-context en engrim list:

🧠 engrim · geheugen hersteld voor dit project — u hoeft niets opnieuw uit te leggen · /workspace

18 van de 54 gecureerde records zijn geladen (~3850 tekens) · de rest is bereikbaar via recall

[DECISION]

- #961 [DECISION] (via Antigravity): Inverted stop loss matrix voor hoge volatiliteit (risk, execution)

- #942 [DECISION] (via Claude Code): Primaire database gewisseld van MongoDB naar PostgreSQL (db, schema)

- #910 [DECISION] (via Cursor): Gestandaardiseerd op Pydantic v2 schema's over API-grenzen (api, types)

Bestaande databases worden niet-destructief gemigreerd bij de eerste toegang via ALTER TABLE memories ADD COLUMN origin_agent TEXT.

6. Robuuste Model Context Protocol (MCP) Server

Start de zero-dependency, JSON-RPC 2.0 stdio MCP-server:

engrim serve --mcp
# of:
engrim mcp

stdout is strikt gereserveerd voor JSON-RPC berichten; alle diagnostische logs worden naar stderr omgeleid.

Beschikbare MCP-tools

Tool	Signatuur	Doel
engrim_recall	(query: str, project: str = "auto", k: int = 5, type: str = None)	Hybride (trefwoord + semantisch) zoeken in projectgeheugen.
engrim_add	(type: str, summary: str, detail: str = None, tags: list[str] = [])	Een duurzaam geheugenrecord schrijven dat over sessies behouden blijft.
engrim_context	(project: str = "auto", budget: int = 4000)	Het session-boot geheugenpakket ophalen binnen een bepaald tekenbudget.
engrim_review	(project: str = "auto")	Niet-vastgelegde beslissingen uit transcript-logs controleren voordat deze worden gewist.

7. CLI-Referentie

Commando	Gebruik	Beschrijving
engrim add	engrim add -t decision -s "..." [--origin-agent agy]	Voegt geheugenrecord toe (typen: decision, fact, feedback, state, user, reference).
engrim recall	engrim recall -q "database"	Gerangschikte hybride recall voor het project (--log zoekt in ruwe beurten).
engrim context	engrim context [-b 4000]	Prioriteitsvolgeordend, budget-beperkt session-boot pakket.
engrim hook	engrim hook --agent agy --event boot	Lifecycle hook runner voor Antigravity en Claude Code.
engrim setup	`engrim setup [--agy\	--claude\	--cursor\	--all]`	Universele configuratie voor multi-agent omgevingen.
engrim serve	engrim serve --mcp	Start stdio MCP-server voor agent-integraties.
engrim review	engrim review	"Safe to clear" controle: scant logs op niet-gecureerde beslissingen.
engrim list	engrim list [-k 20]	Lijst recente herinneringen voor het huidige project.
engrim supersede	engrim supersede --id 12 --status superseded	Markeert een record als vervangen zonder de historie te wissen.
engrim sync	engrim sync [DIR]	Spiegel Markdown-herinneringen naar de store (idempotent, eenmalige seed).

8. "Continue-As-Clear" Workflow

1. Vastleggen tijdens het werk: Telkens wanneer er een belangrijke beslissing of architecturale regel wordt genomen, voert u engrim add uit of roept u engrim_add aan via uw agent.
2. Gebruik de resume-pointer: Voeg vóór het beëindigen van een sessie of het wissen van de context een record toe met de tag resume-pointer, waarin de onmiddellijke volgende taak wordt beschreven. De nieuwste pointer wordt bovenaan het volgende session-boot pakket geplaatst onder [▶ RESUME HERE].
3. Verifiëren met engrim review: Controleer of alle recente beslissingen zijn vastgelegd.
4. Vrij wissen (/clear): Het sessievenster wordt leeggemaakt; engrim injecteert automatisch het actieve geheugenpakket bij de volgende prompt of aanroep.

9. Beveiliging & Privacy

• 100% Lokaal & Offline: Alle geheugenrecords en logs bevinden zich in een lokaal SQLite-bestand (~/.engrim/memory.db). Geen telemetrie, geen cloud-sync, geen tracking.
• Modelopslag: Maakt gebruik van model2vec voor lokale statische embeddings (~30ms laadtijd, geen GPU vereist, draait op CPU). Kan puur lexicaal draaien (ENGRIM_EMBED=off) voor nul extra afhankelijkheden.
• POSIX-bestandsrechten: Databases worden aangemaakt met beperkte rechten voor alleen de eigenaar (0600).
• Git-bescherming: *.db is standaard gitignored; uw herinneringen worden nooit per ongeluk toegevoegd aan versiebeheer.

10. Licentie

MIT © 2026 Tim Gordon.