agentmemory: persistent geheugen voor AI coding agents

Blijvend geheugen tussen programmeersessies en agents.
Persistent geheugen voor Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, en elke MCP-client.

🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog

rohitg00/agentmemory | Trendshift

Design-document: 1.7k stars / 240 forks op de gist

De gist breidt Karpathy's LLM Wiki-patroon uit met confidence scoring, lifecycle, knowledge graphs en hybride zoeken: agentmemory is de implementatie.

npm version CI License Stars skills.sh installs

54 MCP tools 12 auto hooks 0 external DBs 5,000+ tests passing

agentmemory-demo

Installeren • Snelstart • Benchmarks • vs Concurrenten • Agenten • Hoe het werkt • MCP • Viewer • Config • API

--- AgentMemory legt programmeersessies vast en maakt beslissingen, oplossingen en lessen doorzoekbaar. Deel één geheugenopslag tussen agents, bekijk wat is opgeslagen en bepaal hoeveel context het model ontvangt. ## Install Vereisten: - Node.js 20 of nieuwer met npm en npx (`node -v`, `npm -v` en `npx -v`). - Op macOS/Linux vereist automatische installatie ook `curl`, een POSIX-`sh` en `tar`. - Gebruik op Windows WSL2 of volg de [native Windows-installatie](#windows). Canonieke opdracht voor een nieuwe installatie: ```bash npx -y @agentmemory/agentmemory@latest ``` Kies je agents en een provider, of werk zonder API-sleutel. De setup schrijft de configuratie, start de geheugenserver en biedt een globale installatie voor de opdracht `agentmemory`. `-y` bevestigt de npm-vraag; `@latest` kiest de huidige versie. LLM-compressie is optioneel en vereist een provider en `AGENTMEMORY_AUTO_COMPRESS=true`. Keyless-modus schakelt vector-embeddings uit. `memory_recall` (het `mem::search`-pad) gebruikt BM25, terwijl `memory_smart_search` ook structurele graph-matches kan combineren wanneer er al graph-data bestaat. Voor gratis semantisch ophalen op het eigen apparaat stel je `EMBEDDING_PROVIDER=local` in in `~/.agentmemory/.env` en herstart je. De eerste embedding-aanvraag downloadt `Xenova/all-MiniLM-L6-v2`; inference draait daarna lokaal, na die eerste modeldownload. De API staat op `http://localhost:3111` en de viewer op `http://localhost:3113`. Beide luisteren standaard op loopback. De configuratie staat in `~/.agentmemory/.env`; zie [gegevensopslag](#data-storage) voor locaties en afzonderlijke instanties. Bewijs vervolgens dat recall werkt en geef je agent zijn skills: ```bash npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory ``` De keyword-zoekopdrachten zouden in de standaard keyless-modus via BM25 moeten raken. De `database performance optimization`-query van de demo is doelbewust semantisch en kan nul resultaten opleveren totdat er een embedding-provider is geconfigureerd. Wil je liever dat een coding agent dit allemaal voor je doet? Geef hem één instructie: > Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md Verbind een andere agent met `agentmemory connect `. Zie de [integraties](#works-with-every-agent) en [dagelijkse opdrachten](#everyday-commands).
Globale installatie / EACCES ```bash npm install -g @agentmemory/agentmemory@latest ``` Het npx-commando hierboven blijft het canonieke pad voor een nieuwe installatie en voorkomt problemen met globale-prefix-rechten.
npx serveert een oude versie npx cachet per versie. Forceer de laatste versie met `npx -y @agentmemory/agentmemory@latest`, of wis de cache eenmalig met `rm -rf ~/.npm/_npx` (macOS/Linux; verwijder op Windows `%LOCALAPPDATA%\npm-cache\_npx`).
---

Werkt met elke agent

agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. Alle agents delen dezelfde memory server.
Claude Code
Claude Code
native plugin + 12 hooks + MCP
Codex CLI
Codex CLI
native plugin + 6 hooks + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + plugin hooks/skills
Cursor
Cursor
native plugin + lifecycle-hooks + MCP
OpenCode
OpenCode
capture plugin + MCP
Devin
Devin
6 hooks + skills + MCP
OpenClaw
OpenClaw
native plugin + MCP
Hermes
Hermes
native plugin + MCP
pi
pi
native zoeken + vastlegging + skills
OpenHuman
OpenHuman
native Memory-trait-backend
Gemini CLI
Gemini CLI
MCP-server
Antigravity
Antigravity
MCP + hooks
Claude Desktop
Claude Desktop
MCP-server
Warp
Warp
connect + MCP + skills
Zed
Zed
MCP-server
Cline
Cline
MCP-server
Continue
Continue
MCP-server
Droid
Droid
MCP-server
Kiro
Kiro
MCP-server
Qwen Code
Qwen Code
MCP-server
DeepSeek Harness
DeepSeek Harness
native vastlegging + MCP
Roo Code
Roo Code
MCP-server
Kilo Code
Kilo Code
MCP-server
Goose
Goose
MCP-server
Aider
Aider
REST API
Oh My Pi
native zoeken + vastlegging + skills + Optioneel MCP

Werkt met elke agent die MCP of HTTP spreekt. Eén server, memories gedeeld over al deze agents.

--- ### Gegevensopslag Herinneringen worden standaard buiten je repository opgeslagen: | Platform | Gegevensmap | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | Instantie 0 hergebruikt een bestaande `./data/state_store.db`. Kies een andere locatie met `--data-dir ` of `AGENTMEMORY_DATA_DIR` en behoud die bij herstarts en upgrades. `--instance 1` gebruikt de submap `instance-1`, API-poort `3211` en viewerpoort `3213`. Zie de [handleiding voor opslag en back-ups](../docs/reliability/state-storage.md) voor Redis en migraties. ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` Laatste release notes: [CHANGELOG.md](../CHANGELOG.md). ---

Benchmarks

Actuele zoekresultaten, definities van meetwaarden en stappen om de test te herhalen: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

vs Concurrenten

Bijgewerkte vergelijking van producten en implementatieopties, met bronnen: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

Snelstart

### Probeer het in 30 seconden ```bash # Terminal 1: start the server npx -y @agentmemory/agentmemory@latest # Terminal 2: seed sample data and see recall in action npx -y @agentmemory/agentmemory@latest demo ``` `demo` zet 3 realistische sessies klaar (JWT-auth, N+1-queryfix, rate limiting) en voert zoekopdrachten erop uit. Keyless-installaties schakelen vectoren uit, dus de keyword-queries via `mem::search` zouden via BM25 moeten raken, terwijl `database performance optimization` nul resultaten kan opleveren. `smart-search` kan daarnaast structurele graph-matches teruggeven wanneer er graph-data bestaat. Om de semantische query de N+1-fix via vectoren te laten vinden, stel je `EMBEDDING_PROVIDER=local` in, herstart je, en laat je de eerste modeldownload afronden. Open `http://localhost:3113` om het geheugen live te zien opbouwen. ### Een nieuwe installatie en persistentie na herstart valideren Controleer de gezondheid, viewer en status terwijl de server draait: ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` `status` toont de serverstatus en de actieve providers en embeddings. Sla een testherinnering op en controleer de zoekfunctie: ```bash # Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead. read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret" curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}' curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -H 'Content-Type: application/json' \ -d '{"query":"restart persistence probe","limit":5}' ``` Voer vervolgens `npx -y @agentmemory/agentmemory@latest stop` uit, start het canonieke commando opnieuw in Terminal 1, wacht op `/agentmemory/livez`, en herhaal de zoekopdracht. De probe moet nog steeds worden teruggegeven. Als je een aangepaste `--data-dir` koos, geef dan bij de herstart dezelfde map door. ### Dagelijkse commando's Installatie en setup staan hierboven bij [Install](#install) (de eerste run begeleidt je erdoorheen). Dagelijks gebruik: ```bash agentmemory # start the server agentmemory stop # stop it cleanly agentmemory connect # wire another agent agentmemory doctor # interactive diagnostics + fix prompts agentmemory remove # uninstall everything we created ``` ### Sessie-replay Elke sessie die agentmemory vastlegt, is afspeelbaar. Open de viewer, kies het tabblad **Replay**, en schuif door de tijdlijn: prompts, tool calls, tool-resultaten en antwoorden worden weergegeven als afzonderlijke events met play/pause, snelheidsregeling (0.5x tot 4x) en toetsenbordsneltoetsen (spatie om te schakelen, pijltjes om stap voor stap te gaan). Om oudere Claude Code JSONL-transcripten te importeren: ```bash # Import everything under the default ~/.claude/projects npx -y @agentmemory/agentmemory@latest import-jsonl # Or import a single file npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl ``` Geïmporteerde sessies verschijnen in de Replay-kiezer naast de native sessies. Elk geïmporteerd transcript wordt geïndexeerd voor zoeken, gestempeld met oorsprongkanaal `import`, en doorzocht op een sessie-crystal en lessen. > **Let op als je `import-jsonl` als je primaire capture-pad gebruikt:** de `cleanupPeriodDays` van Claude Code (in `~/.claude/settings.json`, standaard **30**) verwijdert automatisch JSONL-transcripten die ouder zijn dan dat venster uit `~/.claude/projects/`. Als je agentmemory vers installeert op een Claude Code-geschiedenis van maanden oud, is alles ouder dan 30 dagen al verdwenen vóór de eerste import. Draai `import-jsonl` op een cron, verhoog `cleanupPeriodDays` naar een hogere waarde, of koppel de auto-capture-hooks (het standaard installatiepad via de plugin) zodat elke turn in agentmemory terechtkomt terwijl de sessie live is en de JSONL-cleanup er niet meer toe doet. ### Upgraden / onderhoud Gebruik het onderhoudscommando wanneer je bewust je lokale runtime wilt bijwerken: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` Deze opdracht werkt de lokale runtime bij en kan JavaScript-afhankelijkheden in de huidige workspace bijwerken. Maak een back-up en lees de [upgradehandleiding](../docs/upgrades/iii-0.25.md) voordat je verdergaat. ### Claude Code (één blok, plak dit) ```text Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall. ``` #### Claude Code zonder de plugin-installatie (MCP-standalone pad) Als je de MCP-server van agentmemory rechtstreeks via `~/.claude.json` (standaardpad) koppelt in plaats van `/plugin install` te gebruiken, lost Claude Code `${CLAUDE_PLUGIN_ROOT}` nooit op en moet je hook-scripts naar absolute paden in `~/.claude/settings.json` (standaardpad) laten verwijzen. Die paden bevatten doorgaans de agentmemory-versie (bijv. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), waardoor de volgende upgrade stilletjes elke hook stuk maakt. Workaround: ```bash agentmemory connect claude-code --with-hooks ``` Dit commando configureert de MCP-server en voegt de meegeleverde hooks samen met de gebruikersconfiguratie van Claude Code. Als `CLAUDE_CONFIG_DIR` niet is ingesteld, leeg is of alleen witruimte bevat, gebruikt het `~/.claude.json` voor MCP en `~/.claude/settings.json` voor hooks. Andere mapwaarden worden precies gebruikt zoals opgegeven, inclusief witruimte aan het begin en einde. Voor een aangepaste map stel je `CLAUDE_CONFIG_DIR` voor zowel dit commando als Claude Code in op dezelfde niet-lege waarde; de bestanden zijn dan respectievelijk `$CLAUDE_CONFIG_DIR/.claude.json` en `$CLAUDE_CONFIG_DIR/settings.json`. Claude Code moet deze waarde ontvangen in zijn opstartomgeving, ook als de connector die uit het `.env`-bestand van AgentMemory leest. Maak de aangepaste map aan voordat je dit commando uitvoert; anders slaat de connector Claude Code over omdat het niet wordt gedetecteerd. Als de waarde in de shell alleen witruimte bevat, verwijder dan `CLAUDE_CONFIG_DIR` uit de omgeving voordat je Claude Code start, zodat het ook het standaardprofiel gebruikt. Gebruik een absoluut pad. Relatieve paden worden vanuit de werkmap bepaald, dus beide opdrachten moeten vanuit dezelfde map worden uitgevoerd. Hook-commando’s gebruiken absolute paden naar de meegeleverde map `plugin/` van het geïnstalleerde pakket. Voer het commando na het upgraden van agentmemory opnieuw uit om deze paden te vernieuwen. Gebruikersinvoer in de configuratiebestanden blijft behouden; alleen eerdere agentmemory-invoer wordt vervangen. Het gebruik van `/plugin install` blijft de aanbevolen aanpak. Voor remote of beveiligde deployments start je Claude Code met `AGENTMEMORY_URL` en `AGENTMEMORY_SECRET` ingesteld. De plugin geeft beide waarden door aan zijn gebundelde MCP-server; wanneer `AGENTMEMORY_URL` leeg is, gebruikt de MCP-shim `http://localhost:3111`. ### Codex CLI (Codex-pluginplatform) ```bash # 1. start the memory server in a separate terminal npx -y @agentmemory/agentmemory@latest # 2. register the agentmemory marketplace and install the plugin codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` De Codex-plugin komt uit dezelfde `plugin/`-map als de Claude Code-plugin. Hij registreert: - Een gebundelde stdio MCP-bridge naar de draaiende daemon, zonder npm-download of fallback-store. Zie de [lokale Codex-guide](../docs/plugins/codex-local.md) om een niet-uitgebrachte build te testen. - 6 lifecycle-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 9 aanroepbare skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 referentieskills die de agent op aanvraag laadt (memory discipline, MCP-tools, REST API, config, agents, hooks, architecture, en de skill-authoring guide) De hook-engine van Codex injecteert `CLAUDE_PLUGIN_ROOT` in hook-subprocessen (zie [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), zodat dezelfde hook-scripts op beide hosts werken zonder duplicatie. Subagent-, SessionEnd-, Notification-, TaskCompleted- en PostToolUseFailure-events zijn alleen voor Claude Code en worden niet geregistreerd voor Codex. #### Codex-hooks: vertrouwen en compatibiliteit Native plugin-hook-dispatch is geverifieerd met Codex CLI 0.150.1. Vertrouw de plugin-hooks voordat je capture verwacht. Het gedrag van Codex Desktop hangt af van de gebundelde runtime; controleer `/hooks` en bevestig een vastgelegd event voordat je een workaround inschakelt. Als je host globale hooks nodig heeft, spiegel je de commando's naar de globale `~/.codex/hooks.json`. Wanneer MCP al gekoppeld is, heeft de huidige `connect`-adapter `--force` nodig om bij de hook-installatie te komen: ```bash agentmemory connect codex --with-hooks --force ``` Dit voegt globale hooks samen en herschrijft de agentmemory MCP-entry, met behoud van niet-gerelateerde entries. Controleer aangepaste agentmemory-endpoint-instellingen voordat je `--force` gebruikt. Voer opnieuw uit na het upgraden om de scriptpaden te verversen. Schakel ofwel native plugin-hooks ofwel globale kopieën in om dubbele capture te vermijden. ### GitHub Copilot CLI Voor de VS Code-agentmodus gebruik je de [Copilot MCP- en auto-capture-guide](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). De CLI-connector configureert VS Code niet. ```bash # MCP-only wiring agentmemory connect copilot-cli # Alternatively, full hooks/skills plugin from the GitHub subdir copilot plugin install rohitg00/agentmemory:plugin ``` `agentmemory connect copilot-cli` voegt `mcpServers.agentmemory` samen in `~/.copilot/mcp-config.json` (of `$COPILOT_HOME/mcp-config.json` wanneer `COPILOT_HOME` is ingesteld) en behoudt bestaande servers. Op native Windows is dit de enige geautomatiseerde `connect`-adapter; configureer elke andere native Windows-agent handmatig. `connect` via WSL wordt alleen ondersteund wanneer de doelagent in diezelfde WSL-omgeving is geïnstalleerd. Copilot pikt de MCP-server op bij de volgende start of na `/mcp`. Installeer ook de plugin wanneer je de volledige hook/skill-ervaring wilt. ### Cursor ```bash agentmemory connect cursor ``` Voeg daarna de native plugin vanuit een AgentMemory-checkout toe via **Settings → Plugins → Add marketplace** en herlaad het venster. De plugin biedt lifecycle-capture, projecttoewijzing, skills en MCP. Activeer de pluginhooks of de handmatige hooks in `~/.cursor/hooks.json` om dubbele vastlegging te voorkomen. [Cursor-handleiding](../integrations/cursor/). ### Pi, Oh My Pi, DeepSeek Harness ```bash agentmemory connect pi --with-mcp agentmemory connect omp --with-mcp agentmemory connect dsh --with-hooks ``` Kies de opdracht voor je host. Pi en OMP installeren zoeken, vastlegging, offline opnieuw verzenden en 17 skills; `--with-mcp` voegt alle tools toe. Voer `/reload` uit in Pi of herstart OMP en controleer `/agentmemory-status`. DSH installeert MCP en de meegeleverde capture-plugin; herstart DSH daarna. Pi ondersteunt ook het installeerbare pakket `@agentmemory/pi`. De [Pi-handleiding](../integrations/pi/) beschrijft lokale installatie en npm-beschikbaarheid. Gebruik één installatiemethode per host. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (plak deze prompt) ```text Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`. ``` Volledige handleiding: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (plak deze prompt) ```text Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: command: npx args: ["-y", "@agentmemory/mcp"] memory: provider: agentmemory Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from https://github.com/rohitg00/agentmemory to ~/.hermes/plugins/agentmemory. ``` Volledige handleiding: [`integrations/hermes/`](../integrations/hermes/)
### Other agents Start de memory server: `npx -y @agentmemory/agentmemory@latest` #### Native skills via `npx skills add` agentmemory levert 17 skills in het Claude-Code-achtige `/SKILL.md`-formaat: 9 aanroepbare actie-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) en 8 referentieskills die de agent op aanvraag laadt (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). De referentieskills bevatten datatabellen die uit de bron gegenereerd zijn, dus ze lopen nooit uit de pas. De [`skills`](https://npmjs.com/package/skills)-CLI van vercel-labs installeert ze automatisch in de native skills-map van de aanroepende agent, verspreid over 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, en meer): ```bash npx skills add rohitg00/agentmemory -y # auto-detects the calling agent npx skills add rohitg00/agentmemory -y -a warp # explicit agent npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent ``` Dit is **complementair** aan `agentmemory connect `: - `agentmemory connect ` schrijft normaal de MCP-configuratie. Hermes, OpenClaw, Pi en Oh My Pi installeren standaard hun native integratie en meegeleverde skills; MCP is optioneel met `--with-mcp`. - `npx skills add rohitg00/agentmemory` installeert skills voor agents zonder meegeleverde native skills. Sla deze stap over voor Hermes, OpenClaw, Pi en Oh My Pi: hun connectors installeren de skills al. Voor de paar agents die de skills-CLI nog niet dekt (Zed v1.3.x en lager), plaats je de 17 SKILL.md-bestanden zelf in de native skills-map van de agent; hetzelfde formaat werkt overal. #### Standaard MCP-blok De agentmemory-entry is hetzelfde **MCP-serverblok** op elke host die de `mcpServers`-vorm gebruikt (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw): ```json "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}" } } ``` **Voeg deze entry samen met het bestaande `mcpServers`-object** in het configuratiebestand van de host; vervang het bestand niet. Als het bestand al andere servers heeft, voeg je `agentmemory` ernaast toe als een extra key binnen `mcpServers`. Als `mcpServers` volledig ontbreekt, plak je het blok binnen `{ "mcpServers": { ... } }`. De `${VAR}`-placeholders erven `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` van de shell bij het starten van de MCP-server; niet-ingestelde variabelen geven lege strings door en de shim valt terug op `http://localhost:3111`. Eén gekoppelde entry dekt zowel lokale als remote (k8s / reverse-proxied) deployments. | Agent | Configuratiebestand | Opmerkingen | |---|---|---| | **Cursor (alleen MCP)** | `~/.cursor/mcp.json` | Voeg samen in `mcpServers`, of `agentmemory connect cursor`. Eén-klik-deeplink ook beschikbaar op de website. | | **Cursor (volledige plugin)** | `.cursor-plugin/` | Voeg daarna de native plugin vanuit een AgentMemory-checkout toe via **Settings → Plugins → Add marketplace** en herlaad het venster. De plugin biedt lifecycle-capture, projecttoewijzing, skills en MCP. Activeer de pluginhooks of de handmatige hooks in `~/.cursor/hooks.json` om dubbele vastlegging te voorkomen. [Cursor-handleiding](../integrations/cursor/). | | **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Voeg samen in `mcpServers`. Herstart Claude Desktop na het bewerken. | | **Cline / Roo Code / Kilo Code** | Cline MCP-instellingen (Settings UI → MCP Servers → Edit) | Hetzelfde `mcpServers`-blok. | | **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` voegt de MCP-entry samen; `--with-hooks` voegt zes native auto-capture-hooks toe (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) met de kleine-letter-toolmatchers van Devin. Controleer met `devin mcp list` en `/hooks` binnen devin. | | **Devin CLI (volledige plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` vanuit een checkout registreert alle 17 skills als `/agentmemory:`-slashcommando's plus de MCP-server. Devin-plugin-hooks kunnen `SessionStart`/`SessionEnd` niet afvuren, combineer dit dus met `connect devin --with-hooks` voor volledige sessie-capture. | | **Devin (cloud)** | Settings → Connections → MCP servers | Voeg een aangepaste MCP toe (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` die wijst naar een netwerkbereikbare agentmemory-deployment, plus `AGENTMEMORY_SECRET` (cloudsessies kunnen localhost niet bereiken — zie [`deploy/`](../deploy/)). Bewaar het secret in Devin Secrets, en gebruik vervolgens "Test listing tools" om te controleren of alle 54 tools verschijnen. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (voegt automatisch samen). | | **GitHub Copilot CLI (alleen MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` voegt `mcpServers.agentmemory` samen; Copilot pikt dit op bij de volgende start of `/mcp`. | | **GitHub Copilot CLI (volledige plugin)** | Copilot plugin-installatie | `copilot plugin install rohitg00/agentmemory:plugin` voor de plugin vanuit de GitHub-submap. | | **OpenClaw** | OpenClaw MCP-config | Hetzelfde `mcpServers`-blok. Dieper: `openclaw plugins install ./integrations/openclaw` claimt de memory-slot van OpenClaw (schakelt automatisch over vanaf `memory-core`); stel `plugins.entries.agentmemory.hooks.allowConversationAccess=true` in, anders wordt turn-capture stilletjes geblokkeerd. Zie [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (alleen MCP)** | `.codex/config.toml` | TOML-vorm: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, of voeg handmatig `[mcp_servers.agentmemory]` toe. | | **Codex CLI (volledige plugin)** | Codex plugin-marketplace | `codex plugin marketplace add rohitg00/agentmemory`, daarna `codex plugin add agentmemory@agentmemory`. Registreert MCP + 6 lifecycle-hooks + 17 skills. Vertrouw de hooks en verifieer de capture in je host; zie [Codex-setup en -validatie](../docs/plugins/codex-local.md). | | **OpenCode (alleen MCP)** | `opencode.json` | Andere vorm: top-level `mcp`-key, command als array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (volledige plugin)** | `plugin/opencode/` | 22 auto-capture-hooks voor sessie-lifecycle, berichten, tools en errors. Projecttoewijzing is per sessie, dus één OpenCode-proces dat meerdere repositories omspant, bestandt elke sessie onder zijn eigen project. Twee slashcommando's (`/recall`, `/remember`). Kopieer `plugin/opencode/` naar je OpenCode-workspace en voeg de plugin-entry toe aan `opencode.json`. Zie [`plugin/opencode/README.md`](../plugin/opencode/README.md) voor de volledige hooktabel + gap-analyse. | | **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | native zoeken + vastlegging + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). | | **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` geeft de 6-hook memory-provider (prefetch, turn-capture, session-end, pre-compress, MEMORY.md-mirroring, system-prompt-blok). Valideer met `hermes plugins doctor` en `hermes memory status`. Zie [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` schrijft het standaard `mcpServers`-blok. De hook-payload is veldcompatibel met Claude Code, dus de bestaande 12-hook-scripts werken zonder aanpassing; koppel ze via de `hooks`-sectie in hetzelfde `settings.json`. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installeert MCP en capture-hooks in de gedeelde customization-map. Zie [Antigravity-setup en -beperkingen](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` gebruikt dezelfde MCP- en hookconfiguratie als de huidige IDE-versies. Bestaande installaties moeten verversen met `--force`; zie de [upgrade-notities](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` schrijft de config op gebruikersniveau. Workspace-overrides komen in `.kiro/settings/mcp.json` naast je code. | | **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` schrijft het standaard `mcpServers`-blok. Warp ontdekt ook automatisch skills vanuit `.claude/skills/`; zodra de Claude Code-plugin is geïnstalleerd, verschijnen de 9 agentmemory-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) native in het slashcommando-palet van Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | `agentmemory connect cline` schrijft het standaard `mcpServers`-blok. Gebruikers van de VS Code-extensie: plak hetzelfde blok via Cline Settings → MCP Servers → Edit JSON. | | **Continue.dev** | `~/.continue/config.yaml` (voorkeur) of `config.json` (legacy) | `agentmemory connect continue` maakt een ontbrekende `config.yaml` of wijzigt een bestaande `config.json`. Bij bestaande YAML toont de adapter het blok voor `mcpServers:` zodat comments en anchors behouden blijven. Continue gebruikt een array, geen object. | | **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` schrijft onder `context_servers` (de key van Zed, NIET `mcpServers`). Remote MCP-servers kunnen in plaats daarvan gekoppeld worden via `{"url": "..."}`. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` schrijft het standaard `mcpServers`-blok. Project-scoped overrides komen in `/.factory/mcp.json`. Geef `--with-hooks` door voor native auto-capture. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` activeert MCP-tools. Voeg `--with-hooks` toe voor de native registratieplugin die bij AgentMemory wordt geleverd. Er is geen apart pluginpakket nodig. [DSH](../docs/dsh.md). | | **Goose** | Goose MCP-instellingen-UI | Hetzelfde `mcpServers`-blok; gebruik `goose configure` → Add Extension → MCP. Direct bewerken van de YAML op `~/.config/goose/config.yaml` wordt ondersteund, maar het schema gebruikt `extensions:` + `cmd` (niet `mcpServers:` + `command`). | | **Aider** | n/a | Gebruik de [geauthenticeerde REST-voorbeelden](#validate-a-fresh-install-and-restart-persistence) om geheugen vanuit scripts op te slaan en te doorzoeken. | | **Ondersteunde agents** | Alleen skills | `npx skills add rohitg00/agentmemory`; kies de skills en de agents waarvoor je ze wilt installeren. | **Gesandboxte MCP-clients** (Flatpak / Snap / restrictieve containers) die de `localhost` van de host niet kunnen bereiken: stel ook `"AGENTMEMORY_FORCE_PROXY": "1"` in het `env`-blok in, en richt `AGENTMEMORY_URL` op een route die de sandbox daadwerkelijk kan bereiken (bijv. je LAN-IP). ### Programmatische toegang (Python / Rust / Node) Gebruik de [REST API](#api) vanuit elke taal of de [MCP-tools](#mcp-server) vanuit een agent. REST gebruikt JSON en bearer-authenticatie; zie het [voorbeeld voor opslaan en zoeken](#validate-a-fresh-install-and-restart-persistence). De [Python-voorbeelden](../examples/python/) behandelen directe runtime-integratie. ### Vanuit de bron ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` `npm start` start dezelfde lokale server als de geïnstalleerde CLI. Vereisten staan onder [Install](#install); API en viewer luisteren op `127.0.0.1`. ### Windows agentmemory draait op Windows 10/11. WSL2 volgt het Linux-pad en kan de vastgezette engine automatisch installeren. Native Windows vereist handmatige installatie van de vastgezette iii-engine v0.25.1-binary; download het passende archief van de [iii v0.25.1-releasepagina](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), controleer de checksum en plaats `iii.exe` op `PATH` (bijvoorbeeld `%USERPROFILE%\.local\bin\iii.exe`). De CLI pakt de Windows ZIP niet automatisch uit. Geautomatiseerde MCP-koppeling op native Windows ondersteunt alleen `agentmemory connect copilot-cli`. Gebruik voor andere native Windows-agents het handmatige MCP-blok uit [Other agents](#other-agents). Voer `connect` binnen WSL alleen uit wanneer de doelagent in dezelfde WSL-omgeving is geïnstalleerd. **Alleen standalone MCP (geen engine).** Als je alleen MCP-tools nodig hebt en de REST API, viewer of runtimeservices niet nodig hebt: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` Voer `agentmemory doctor` uit of herstart met `--verbose`. Gebruik `--port ` of `--instance ` als de poorten bezet zijn. Zie de [upgradehandleiding](../docs/upgrades/iii-0.25.md) voor compatibiliteit en herstel. ---

Deployment

Host de dienst zelf met Docker Compose of de onderstaande templates. Geheugen en inloggegevens staan op het `/data`-volume. Maak een back-up en hergebruik dit volume bij upgrades. De [deploymenthandleiding](../deploy/README.md) behandelt authenticatie, netwerktoegang, back-ups en migratie.

Deploy to fly.io Deploy to Railway

De één-klik-deployknop van Render vereist een `render.yaml` in de root van de repository, die we bewust leeg houden. Gebruik de Render Blueprint-flow die gedocumenteerd is in [`deploy/render/`](.././deploy/render/README.md) om handmatig naar de blueprint in de repo te wijzen. Volledige setupdetails (HMAC-capture, SSH-tunnel voor de viewer, rotatie, backup, minimale kosten) staan in [`deploy/`](.././deploy/README.md): - [`deploy/fly`](.././deploy/fly/README.md): één machine met `auto_stop_machines = "stop"`; goedkoopst in rust. - [`deploy/railway`](.././deploy/railway/README.md): vast tarief op het Hobby-plan, volume in het dashboard. - [`deploy/render`](.././deploy/render/README.md): Blueprint-flow, automatische disk-snapshots op betaalde plannen. - [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted op je eigen VPS via [Coolify](https://coolify.io/self-hosted); dezelfde Docker Compose-stack, jij bent eigenaar van de host en de data. REST gebruikt poort `3111`; de viewer gebruikt `3113`. Houd ze privé of bescherm ze met authenticatie en TLS. De deploymenthandleiding beschrijft netwerktoegang en [migratie van oudere Docker-installaties](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode). ---

Waarom agentmemory

Projectkennis raakt verspreid over chats en instructiebestanden. Met AgentMemory kun je eerdere beslissingen, oplossingen en lessen doorzoeken vanuit de agent die je nu gebruikt. ```text Session 1: "Add auth to the API" Agent writes code, runs tests, fixes bugs Connected hooks capture supported tool events Observations become searchable project history Session 2: "Now add rate limiting" Agent recalls: - Auth uses JWT middleware in src/middleware/auth.ts - Tests in test/auth.test.ts cover token validation - You chose jose over jsonwebtoken for Edge compatibility Continues with the earlier decisions in context. ``` ### vs ingebouwd agentgeheugen Elke AI coding agent levert ingebouwd geheugen: Claude Code heeft `MEMORY.md`, Cursor heeft notepads, Cline heeft een memory bank. Deze werken als geheugensteuntjes. agentmemory is de doorzoekbare database achter die geheugensteuntjes. | | Ingebouwd (CLAUDE.md) | agentmemory | |---|---|---| | Onderhoud | Handmatig bijgehouden instructies | Geïndexeerde sessiegeschiedenis en herinneringen | | Zoeken | Laadt alles in de context | BM25 + vector + graph (alleen top-K) | | Cross-agent | Bestanden per agent | MCP + REST (elke agent) | | Coördinatie | Geen | Leases, signals, actions, routines | | Observability | Bestanden handmatig lezen | Realtime viewer op :3113 | ---

Hoe het werkt

### Memory-pipeline ```text PostToolUse hook fires -> Stable event ID / durable capture inbox / offline spool -> Privacy filter (strip secrets, API keys) -> Store raw observation -> Synthetic compression by default (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled Stop / SessionEnd hook fires -> Summarize session -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true) -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject context when enabled by the integration ``` ### 4-laagse memory-consolidatie Gemodelleerd naar hoe menselijke breinen geheugen verwerken, inclusief consolidatie tijdens slaap. | Laag | Wat | Analogie | |------|------|---------| | **Working** | Ruwe observaties uit toolgebruik | Kortetermijngeheugen | | **Episodic** | Gecomprimeerde sessiesamenvattingen | "Wat er gebeurd is" | | **Semantic** | Geëxtraheerde feiten en patronen | "Wat ik weet" | | **Procedural** | Workflows en beslispatronen | "Hoe je het doet" | Memories vervagen in de tijd (Ebbinghaus-curve). Vaak opgevraagde memories worden sterker. Verouderde memories worden automatisch verwijderd. Tegenstrijdigheden worden gedetecteerd en opgelost. ### Wat er wordt vastgelegd Deze tabel beschrijft de Claude Code-hooks. Andere integraties leggen de gebeurtenissen vast die hun host aanbiedt; zie de afzonderlijke handleidingen. Automatische contextinjectie via de gedeelde hooks is optioneel met `AGENTMEMORY_INJECT_CONTEXT=true`. | Hook | Legt vast | |------|----------| | `SessionStart` | Projectpad, session ID | | `UserPromptSubmit` | Gebruikersprompts (privacy-gefilterd) | | `PreToolUse` | Bestandstoegangspatronen + verrijkte context | | `PostToolUse` | Toolnaam, input, output | | `PostToolUseFailure` | Errorcontext | | `PreCompact` | Injecteert geheugen opnieuw vóór compactie | | `SubagentStart/Stop` | Lifecycle van sub-agents | | `Stop` | Samenvatting aan het einde van de sessie | | `SessionEnd` | Markering dat de sessie voltooid is | ### Belangrijkste functies | Functie | Beschrijving | |---|---| | **Automatische capture** | Native integraties leggen ondersteunde sessie- en toolgebeurtenissen vast | | **Semantisch zoeken** | BM25 + vector + knowledge graph met RRF-fusie | | **Memory-evolutie** | Versiebeheer, supersession, relatiegraphs | | **Recall-hygiëne** | Vervangen memory-versies verlaten de zoekindexen; de versieketen in KV behoudt de volledige geschiedenis | | **Near-duplicate-hints** | Bij opslaan wordt een adviserende `similarTo`-match gerapporteerd wanneer nieuwe content sterk op een bestaande memory lijkt | | **Scoping per agent** | `agentId` loopt door save en recall heen, over REST, MCP en de zoekindex, in shared of isolated modus | | **Provenance op schrijfmoment** | Elke observatie en memory draagt een onveranderlijk oorsprongkanaal (user, agent, tool, import of shared), gestempeld bij capture, save en import | | **Auto-forgetting** | TTL-verval, detectie van tegenstrijdigheden, eviction op basis van belang | | **Privacy eerst** | API-keys, secrets en ``-tags verwijderd vóór opslag | | **Zelfherstellend** | Circuit breaker, fallback-keten van providers, health monitoring | | **Claude-bridge** | Bidirectionele sync met MEMORY.md | | **Knowledge graph** | Entiteitsextractie + BFS-traversal | | **Team memory** | Namespaced shared + private tussen teamleden | | **Citation-provenance** | Traceer elke memory terug naar de bron-observaties | | **Git-snapshots** | Versioneer, rollback en diff van memory-state | --- Triple-stream retrieval combineert drie signalen: | Stream | Wat het doet | Wanneer | |---|---|---| | **BM25** | Keyword-matching met stemming en synonym-expansion | Altijd actief | | **Vector** | Cosine similarity over dense embeddings | Embedding-provider geconfigureerd | | **Graph** | Knowledge-graph-traversal via entity-matching | Entiteiten gedetecteerd in de query | Samengevoegd met Reciprocal Rank Fusion (RRF, k=60) en gediversifieerd per sessie (max. 3 resultaten per sessie). Wanneer een vector-index gevuld is, gebruikt `mem::search` (achter `memory_recall`) de hybride BM25 + vector-ranker. Zonder embeddings gebruikt het BM25. `smart-search` kan daarnaast structurele graph-matches samenvoegen wanneer er graph-data bestaat, ook in keyless-modus. Lesson-recall draait op een eigen in-memory BM25-index in plaats van het hele corpus per query te doorzoeken. Vervangen memory-versies worden uitgesloten van elk recall-pad; de versieketen behoudt hun geschiedenis. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). BM25 tokeniseert standaard Grieks, Cyrillisch, Hebreeuws, Arabisch en Latijn met accenten. Voor Chinese / Japanse / Koreaanse memories installeer je de optionele segmenters (`npm install @node-rs/jieba tiny-segmenter`) om CJK-reeksen op te splitsen in tokens op woordniveau; zonder deze valt agentmemory soft terug op tokenisatie van de hele reeks en print het eenmalig een hint naar stderr. ### Embedding-providers Keyless-installaties schakelen vector-embeddings uit: `mem::search` gebruikt BM25, terwijl `smart-search` ook bestaande structurele graph-data kan gebruiken. Om in te stappen op gratis semantische embeddings op het eigen apparaat, voeg je dit toe aan `~/.agentmemory/.env` en herstart je agentmemory: ```env EMBEDDING_PROVIDER=local ``` De normale npm-installatie bevat de optionele `@huggingface/transformers`-runtime. De eerste embedding-aanvraag downloadt `Xenova/all-MiniLM-L6-v2`, waarvoor netwerktoegang nodig is en wat langer kan duren; latere inference draait op het eigen apparaat. Remote providers worden automatisch gedetecteerd aan hun keys, tenzij `EMBEDDING_PROVIDER` ze overschrijft. | Provider | Model | Kosten | Opmerkingen | |---|---|---|---| | **Lokaal (aanbevolen opt-in)** | `all-MiniLM-L6-v2` | Gratis | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | Gemini | `gemini-embedding-001` | Gratis tier | 100+ talen, 768/1536/3072 dims (MRL), input tot 2048 tokens. Vervangt `text-embedding-004` ([deprecated, uitgefaseerd op 14 jan. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) | | OpenAI | `text-embedding-3-small` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) | | Voyage AI | `voyage-code-3` | Betaald | Geoptimaliseerd voor code | | Cohere | `embed-english-v3.0` | Gratis trial | Algemeen inzetbaar | | OpenRouter | Elk model | Varieert | Multi-model-proxy | ---

MCP-server

54 tools, 6 resources, 3 prompts en 17 skills. > **MCP-shim versus volledige server:** het gepubliceerde `@agentmemory/mcp`-package is een dunne shim. Het toont het volledige oppervlak van 54 tools **alleen wanneer het een draaiende agentmemory server kan bereiken** via `AGENTMEMORY_URL` (proxy-modus). Als er geen server bereikbaar is, valt de shim terug op een lokale set van 7 tools (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). De env-variabele `AGENTMEMORY_TOOLS=core|all` is een vlag aan de *serverzijde*; deze instellen in het `env`-blok van de shim heeft geen effect. Zie je maar 7 tools in Cursor / OpenCode / Gemini CLI, start dan `npx -y @agentmemory/agentmemory@latest` (of de Docker-stack) en stel `AGENTMEMORY_URL=http://localhost:3111` in. ### 54 tools Drie tool-oppervlakken, van klein naar groot: `AGENTMEMORY_TOOLS=core` beperkt de zichtbaarheid tot 8 essentiële tools (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); de basisset hieronder bestaat uit de 14 fundamentele tools van het registry; de standaard (`AGENTMEMORY_TOOLS=all`) toont alle 54.
Basistools (14) | Tool | Beschrijving | |------|-------------| | `memory_recall` | Doorzoek eerdere observaties | | `memory_compress_file` | Comprimeer markdown-bestanden met behoud van structuur | | `memory_save` | Sla een inzicht, beslissing of patroon op | | `memory_file_history` | Eerdere observaties over specifieke bestanden | | `memory_patterns` | Detecteer terugkerende patronen | | `memory_sessions` | Lijst recente sessies | | `memory_smart_search` | Hybride semantisch + keyword-zoeken | | `memory_vision_search` | Doorzoek afbeeldingsobservaties | | `memory_timeline` | Chronologische observaties | | `memory_profile` | Projectprofiel (concepten, bestanden, patronen) | | `memory_export` | Exporteer alle memory-data | | `memory_relations` | Query de relatiegraph | | `memory_commit_lookup` | Sessies achter een git-commit | | `memory_commits` | Commits vastgelegd voor een sessie |
Uitgebreide tools (54 in totaal, het standaardoppervlak) | Tool | Beschrijving | |------|-------------| | `memory_patterns` | Detecteer terugkerende patronen | | `memory_timeline` | Chronologische observaties | | `memory_relations` | Query de relatiegraph | | `memory_graph_query` | Knowledge-graph-traversal | | `memory_consolidate` | Voer 4-laagse consolidatie uit | | `memory_claude_bridge_sync` | Sync met MEMORY.md | | `memory_team_share` | Deel met teamleden | | `memory_team_feed` | Recent gedeelde items | | `memory_audit` | Audit trail van operaties | | `memory_governance_delete` | Verwijderen met audit trail | | `memory_snapshot_create` | Git-versiebeheerde snapshot | | `memory_action_create` | Maak werkitems met dependencies | | `memory_action_update` | Werk actiestatus bij | | `memory_frontier` | Niet-geblokkeerde acties gerangschikt op prioriteit | | `memory_next` | De ene belangrijkste volgende actie | | `memory_lease` | Exclusieve action leases (multi-agent) | | `memory_routine_run` | Instantieer workflow-routines | | `memory_signal_send` | Berichten tussen agents | | `memory_signal_read` | Lees berichten met ontvangstbevestigingen | | `memory_checkpoint` | Externe conditiepoorten | | `memory_mesh_sync` | P2P-sync tussen instanties | | `memory_sentinel_create` | Event-gestuurde watchers | | `memory_sentinel_trigger` | Vuur sentinels extern af | | `memory_sketch_create` | Tijdelijke action graphs | | `memory_sketch_promote` | Promoveer naar permanent | | `memory_crystallize` | Comprimeer actieketens | | `memory_diagnose` | Health-checks | | `memory_heal` | Herstel vastgelopen state automatisch | | `memory_facet_tag` | Dimensie:waarde-tags | | `memory_facet_query` | Query op facet-tags | | `memory_verify` | Traceer provenance |
### 6 resources · 3 prompts · 17 skills | Type | Naam | Beschrijving | |------|------|-------------| | Resource | `agentmemory://status` | Health, aantal sessies, aantal memories | | Resource | `agentmemory://project/{name}/profile` | Intelligence per project | | Resource | `agentmemory://project/{name}/recent` | Recente observaties voor een project | | Resource | `agentmemory://memories/latest` | Laatste 10 actieve memories | | Resource | `agentmemory://graph/stats` | Knowledge-graph-statistieken | | Resource | `agentmemory://team/{id}/profile` | Gedeeld teamprofiel | | Prompt | `recall_context` | Zoek + geef contextberichten terug | | Prompt | `session_handoff` | Handoff-data tussen agents | | Prompt | `detect_patterns` | Analyseer terugkerende patronen | | Skill | `/recall` | Doorzoek geheugen | | Skill | `/remember` | Sla op in langetermijngeheugen | | Skill | `/session-history` | Recente sessiesamenvattingen | | Skill | `/forget` | Verwijder observaties/sessies | De tabel toont de vier kernskills. De volledige set is 9 aanroepbare skills plus 8 referentieskills; zie de sectie Native skills hierboven. ### Standalone MCP Draai zonder de volledige server, voor elke MCP-client. Beide werken: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` Of voeg toe aan de MCP-config van je agent: De meeste agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` Voeg de `agentmemory`-entry samen met het bestaande `mcpServers`-object van je host, in plaats van het bestand te vervangen. Voor gesandboxte clients die de `localhost` van de host niet kunnen bereiken, voeg je `"AGENTMEMORY_FORCE_PROXY": "1"` toe aan het env-blok en stel je `AGENTMEMORY_URL` in op een route die de sandbox kan bereiken. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` Kopieer het plugin-bestand uit de repo: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

Realtime viewer

Start automatisch op poort `3113`. De viewer laadt één snapshot bij het verbinden (`GET /agentmemory/viewer/snapshot`) en verwerkt daarna live-events via SSE op `/agentmemory/viewer/events` van de REST-worker: nieuwe memories, lessen, observaties, audit-entries, graph-wijzigingen en health-updates verschijnen zonder polling of het herladen van de pagina. De enige andere verzoeken zijn de acties die je aanklikt, "load more"-pagina's en zoekopdrachten. Wanneer de stream wegvalt, toont de viewer hoe oud zijn cijfers zijn, maakt opnieuw verbinding met backoff en synchroniseert opnieuw vanaf één snapshot. - **12 tabbladen in vier groepen** met live aantallen, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), toetsenbordsneltoetsen en een mobiel menu. - **Memories:** server-side zoeken, filters op project, agent en type, een detailpaneel met de versieketen en een word-diff, provenance-links, kopieerknoppen voor de id, de MCP-aanroep en een curl-commando, bewerken (een nieuwe versie), forget met bevestiging, bulk-forget en JSON-export. - **Sessions:** een inline observatietijdlijn met leesbare tool-input en -output, filters en paginering, en de memories en lessen die elke sessie heeft opgeleverd. - **Graph:** zoeken, node-detail met relaties en bronnen, een legenda die niet alleen op kleur vertrouwt, en zoomregeling. - **Health:** de live versie van `GET /agentmemory/status`. Elk probleem komt met zijn oplossing, plus de state-backend, de save-status van de index, de voortgang van graph-provenance-compactie en een consolidatie-uitleg met de echte drempelwaarden. - **Audit-, Activity-, Profile-, Replay-, Lessons-, Actions- en Crystals**-pagina's, elk met een lege staat die vertelt wat de sectie is, waarom hij leeg is en welk commando hem vult, en een `?`-woordenlijsttooltip bij elke term en elk getal. ```bash open http://localhost:3113 ``` De viewer-server bindt standaard aan `127.0.0.1` en voegt het server-secret toe wanneer hij verzoeken doorstuurt naar de REST API. Bij een niet-loopback-bind is de HTML-shell openbaar, maar vereist elk proxyverzoek de bearer-token; de viewer vraagt erom en bewaart deze in session storage. Configureer expliciete host-/origin-allowlists en TLS voordat je de viewer blootstelt. Het via REST geserveerde `/agentmemory/viewer`-endpoint volgt de normale bearer-token-regels en stuurt browsers zonder token door naar de viewer-poort. CSP-headers gebruiken een nonce per response en schakelen inline handler-attributen uit (`script-src-attr 'none'`). ---

Configuration

### LLM-providers agentmemory detecteert providers automatisch vanuit je environment. Een provider maakt LLM-ondersteunde operaties beschikbaar, maar het configureren van een provider alleen schakelt LLM-geschreven compressie van observaties niet in. Dat pad vereist zowel een provider als `AGENTMEMORY_AUTO_COMPRESS=true`. | Provider | Config | Opmerkingen | |----------|--------|-------| | **No-op (standaard)** | Geen config nodig | LLM-ondersteund compress/summarize is uitgeschakeld. Synthetic compressie en BM25-recall werken nog steeds. Zie `AGENTMEMORY_ALLOW_AGENT_SDK` hieronder als je vroeger vertrouwde op de Claude-abonnement-fallback. | | Anthropic API | `ANTHROPIC_API_KEY` | Facturering per token | | MiniMax | `MINIMAX_API_KEY` | Anthropic-compatibel | | Gemini | `GEMINI_API_KEY` | Schakelt ook embeddings in | | OpenRouter | `OPENROUTER_API_KEY` | Elk model | | OpenAI API | `OPENAI_API_KEY` | Standaard `gpt-5.6-luna`, overschrijf met `OPENAI_MODEL` | | **Lokaal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) of `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alles wat OpenAI-API-compatibel is. Geen kosten, draait op je eigen hardware. Zie [Local models](#local-models-ollama--lm-studio--vllm) hieronder. | | Claude-abonnement-fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Alleen opt-in. Spawnt `@anthropic-ai/claude-agent-sdk`-sessies; dit veroorzaakte vroeger onbegrensde Stop-hook-recursie, dus het is niet langer de standaard. | ### Local models (Ollama / LM Studio / vLLM) agentmemory praat met elke OpenAI-API-compatibele server, dus alles dat `/v1/chat/completions` blootstelt werkt zonder codewijzigingen. Geen betaalde keys, geen cloud, geen rate limits; draait volledig op je eigen hardware. **Ollama** (standaardpoort `11434`): ```bash ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc. ollama serve ``` ```env # ~/.agentmemory/.env OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=qwen3:8b ``` **LM Studio** (standaardpoort `1234`): Open LM Studio → tabblad Local Server → Start Server. Kies een willekeurig chatmodel uit de kiezer (Qwen 3, gpt-oss, DeepSeek R1, enz.). ```env # ~/.agentmemory/.env OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it OPENAI_BASE_URL=http://localhost:1234/v1 OPENAI_MODEL=qwen3-8b # match the model name from LM Studio ``` **vLLM / llama.cpp / Text Generation Inference**: zelfde vorm. Richt `OPENAI_BASE_URL` op welke URL je server ook blootstelt en stel `OPENAI_MODEL` in op een naam die je server accepteert. **Modelkeuzes voor memory-werk**: compressie en samenvatting zijn korte taken (<2K tokens in, <500 tokens uit) waarbij een 7B instruct-model ruim voldoende is. Aanbevelingen: | Model | Grootte | Waarom | |-------|------|-----| | `qwen3:8b` | ~5.2 GB | Gebalanceerde standaard op een 16 GB-machine; sterk in extractie en tool-vormige tekst | | `qwen3:4b` | ~2.6 GB | Kleinste zinnige optie; prima voor compressie, zwakker bij graph-extractie | | `qwen3-coder:30b` | ~19 GB | Beste lokale keuze voor code-vormige sessies (30B MoE, 3.3B actief) op 24-32 GB hardware | | `gpt-oss:20b` | ~14 GB | Sterk algemeen model dat past binnen 16 GB RAM | | `deepseek-r1:8b` | ~5.2 GB | Reasoning-distillatie; trager maar schonere extracties | Qwen 3-modellen denken standaard en kunnen het hele tokenbudget opbranden aan reasoning voordat er output is. Stel `AGENTMEMORY_LLM_NOTHINK=1` in om `/no_think` toe te voegen aan graph-extractie-prompts, en verhoog `MAX_TOKENS` (16384 werkt) als extracties leeg terugkomen. Reasoning-modellen (`o1`-achtig met ``-blokken) kunnen een lege `content` teruggeven met een `reasoning`-veld dat je lokale server mogelijk niet toont. Als extracties leeg terugkomen, schakel dan eerst over naar een niet-reasoning-model. De env `OPENAI_REASONING_EFFORT=none` kan ook thinking uitschakelen bij Ollama Cloud thinking-modellen die het OpenAI-reasoning-schema spiegelen. Lokale embeddings worden als optionele dependency meegeleverd, maar zijn niet standaard ingeschakeld. Stel `EMBEDDING_PROVIDER=local` in om in te stappen op `Xenova/all-MiniLM-L6-v2` (384-dim). De eerste embedding-aanvraag downloadt het model; inference gebeurt daarna op het eigen apparaat. Zonder die instelling of een remote embedding-key blijven vectoren uitgeschakeld, gebruikt `mem::search` BM25, en kan `smart-search` nog steeds bestaande graph-matches toevoegen. ### Kostenbewuste modelkeuze Begin zonder sleutel voor vastlegging en zoeken op trefwoorden. `EMBEDDING_PROVIDER=local` activeert lokaal semantisch zoeken na de eerste modeldownload. LLM-compressie vereist een provider en `AGENTMEMORY_AUTO_COMPRESS=true`; dit kan per observatie een verzoek opleveren. Controleer eerst de actuele tarieven. De viewer en `agentmemory status` tonen de actieve providers. ### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) In multi-agent-opzetten waarbij meerdere rollen één agentmemory server delen (architect / developer / reviewer / researcher / support-agent), tagt `AGENT_ID` elke write met de rol die deze maakte. `AGENTMEMORY_AGENT_SCOPE` bepaalt of recall op die tag filtert. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` Twee modi: | Modus | Tagt writes | Filtert recall | Wanneer te gebruiken | |------|------------|---------------|-------------| | `shared` (standaard) | ja | nee | Cross-agent context met audit trail. De architect kan zien wat de developer noteerde, maar elke rij legt vast wie het zei. | | `isolated` | ja | ja | Strikte scheiding. De architect ziet nooit de observaties / memories / sessies van de developer. | Wat getagd wordt wanneer `AGENT_ID` is ingesteld: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. De rol stroomt van `api::session::start` → `mem::observe` → `mem::compress` → KV. Wat gefilterd wordt in isolated-modus: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Elk endpoint accepteert `?agentId=` om per request te overschrijven, en `?agentId=*` om volledig uit de env-scope te stappen. `/memories` accepteert ook `?includeOrphans=true` om memories van vóór AGENT_ID te tonen waarvan `agentId` undefined is. Override per aanroep op de SDK-/REST-laag: elk muterend endpoint (`/session/start`, `/remember`) accepteert een `agentId`-veld in de request body dat voorrang heeft op de env. Handig voor runtimes die veel rollen door één serverproces routeren. De MCP-tool `memory_save` biedt hetzelfde `agentId`-veld, de standalone stdio-server geeft zowel `agentId` als `project` door, en opgeslagen memories dragen `agentId` mee de zoekindex in, zodat agent-scoped zoeken zowel memories als observaties dekt. Wanneer `AGENT_ID` niet is ingesteld, blijft memory unscoped (legacy-gedrag, geen tags, geen filters). ### Poorten | Poort | Doel | Configuratie | |---|---|---| | `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` | | `3113` | Viewer UI | `III_VIEWER_PORT` | `--port ` stelt de API-poort in en standaard de viewer op `N+2`. Gebruik `--instance N` voor een afzonderlijke instantie. Houd interne poorten privé; lees de [deploymenthandleiding](../deploy/README.md) voordat je externe toegang toestaat. ### Storage-backend: file (standaard) versus Redis De standaard bestandsopslag vereist geen afzonderlijke databaseservice. Redis is optioneel met `AGENTMEMORY_STATE_BACKEND=redis` en `AGENTMEMORY_REDIS_URL`. Een backendwissel kopieert geen herinneringen. De [handleiding voor opslag en back-ups](../docs/reliability/state-storage.md) behandelt persistentie, Redis-beperkingen en geauthenticeerde export/import. ### Configuratiebestand Zet de runtime-configuratie van agentmemory in `~/.agentmemory/.env` in plaats van variabelen in elke shell te exporteren. Als de viewer een setup-hint toont zoals `export ANTHROPIC_API_KEY=...`, kopieer je deze naar dit bestand als `ANTHROPIC_API_KEY=...` zonder het `export`-voorvoegsel, en herstart je dan agentmemory. Stel `AGENTMEMORY_ENV_FILE` in om een ander env-bestand te gebruiken. Procesomgevingsvariabelen hebben voorrang op het bestand. Herstart de server na configuratiewijzigingen. Op Windows leeft hetzelfde bestand op `%USERPROFILE%\.agentmemory\.env`: ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` Om te testen met een Claude Code Pro/Max-abonnement in plaats van een API-key, stap je er expliciet in: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` LLM-geschreven compressie van observaties vereist beide regels: toegang tot een LLM-provider (inclusief deze expliciete abonnement-fallback) en `AGENTMEMORY_AUTO_COMPRESS=true`. Een provider alleen laat het standaard synthetic-compressiepad ongewijzigd. Consolidatie (graph-nodes, lessen, crystals) staat standaard aan zodra een LLM-provider geconfigureerd is. Stap er expliciet uit met `CONSOLIDATION_ENABLED=false` als je LLM-vrije werking wilt. Graph-extractie is een aparte flag: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### Environment-variabelen Veelgebruikte opties voor `~/.agentmemory/.env`: ```env EMBEDDING_PROVIDER=local # AGENTMEMORY_INJECT_CONTEXT=true # AGENTMEMORY_AUTO_COMPRESS=true # AGENTMEMORY_TOOLS=core # AUTO_FORGET_ENABLED=false # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` De volledige referentie staat in [`.env.example`](../.env.example), met providergegevens, capture-filters, bewaartermijnen, opslag, teamscope en opties. `AGENTMEMORY_ENV_FILE` selecteert een ander bestand. Commit nooit een ingevulde `.env` of bearer-secret. ---

API

147 endpoints op poort `3111`. De REST API bindt standaard aan `127.0.0.1`. Beschermde endpoints vereisen `Authorization: Bearer `, en mesh-sync-endpoints vereisen een expliciet ingestelde `AGENTMEMORY_SECRET` op beide peers. **Authenticatie staat standaard aan.** Als `AGENTMEMORY_SECRET` niet in de shell of in `~/.agentmemory/.env` staat, maakt de CLI bij de eerste start een willekeurig secret in `~/.agentmemory/secret` en een kopie met de naam `secret` in de geselecteerde gegevensmap, met bestandsmodus `0600`. Elke gebundelde client leest het daar wanneer die met een lokale server communiceert: de CLI, viewer, hooks onder `plugin/scripts`, MCP-server en `@agentmemory/mcp`-shim, configs geschreven door `agentmemory connect`, en de gebundelde OpenCode-, Pi-, OpenClaw-, Hermes- en filesystem-watcher-integraties. Het opgeslagen secret wordt alleen verstuurd naar loopback-URL's (`localhost`, `127.0.0.0/8`, `::1`). Een expliciete `AGENTMEMORY_SECRET` wint altijd, en externe clients hebben het secret in hun omgeving nodig. Docker self-host deployments vanuit de repository en de `deploy/`-entrypoints genereren en exporteren hun eigen secret. Zo roep je de API handmatig aan: ```bash curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health ``` **Verzoekregels voor writes.** `POST`-, `PUT`-, `PATCH`- en `DELETE`-verzoeken naar de REST API en de viewer moeten `Content-Type: application/json` versturen (een `charset`-parameter is prima) wanneer ze een body dragen, en een `Origin`-header, indien aanwezig, moet een loopback-origin zijn voor de geconfigureerde REST- of viewer-poort, of vermeld staan in `VIEWER_ALLOWED_ORIGINS` (komma-gescheiden, bijv. `https://memory.example.com`). Clients die geen `Origin`-header versturen (CLI, hooks, MCP, curl, server-naar-server) zijn hier niet door geraakt. De viewer accepteert ook zijn eigen origin. **Bestandspaden.** Endpoints die bestanden lezen of schrijven (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) accepteren alleen paden onder `~/.agentmemory`, de instance-datamap, of een map vermeld in `AGENTMEMORY_IMPORT_ROOT` (meerdere scheiden met `:`, of `;` op Windows). `/replay/import-jsonl` accepteert ook zijn standaard `~/.claude/projects`. `/obsidian/export` blijft binnen `AGENTMEMORY_EXPORT_ROOT` en `/migrate` binnen `~/.agentmemory`. Symlinks worden opgelost vóór elke check. **Secret-scrubbing.** API-keys, bearer tokens, PEM-private-key-blokken en credentials die in URL's zitten (`scheme://user:password@host`) worden geredigeerd voordat tekst wordt opgeslagen, op elk schrijfpad: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl-replay, mesh-sync, team-shares, compressie- en summary-output, crystals en graph-nodes.
Belangrijkste endpoints | Methode | Pad | Beschrijving | |--------|------|-------------| | `GET` | `/agentmemory/health` | Health-check (altijd publiek) | | `GET` | `/agentmemory/status` | Wat er mis is en hoe je het oplost (HTML voor browsers, anders JSON) | | `GET` | `/agentmemory/viewer/snapshot` | Alles wat de viewer toont, in één response | | `POST` | `/agentmemory/session/start` | Start sessie + haal context op | | `POST` | `/agentmemory/session/end` | Beëindig sessie | | `POST` | `/agentmemory/observe` | Leg observatie vast (zie capture-levering hieronder) | | `GET` | `/agentmemory/capture` | Capture-inbox, dead letters en offline spool | | `POST` | `/agentmemory/capture/retry` | Probeer dead-letter-captures opnieuw | | `POST` | `/agentmemory/capture/drain` | Stuur de lokale offline spool nu | | `POST` | `/agentmemory/smart-search` | Hybride zoeken | | `POST` | `/agentmemory/context` | Genereer context | | `POST` | `/agentmemory/remember` | Sla op in langetermijngeheugen | | `POST` | `/agentmemory/forget` | Verwijder observaties | | `POST` | `/agentmemory/enrich` | Bestandscontext + memories + bugs | | `GET` | `/agentmemory/profile` | Projectprofiel | | `GET` | `/agentmemory/export` | Exporteer alle data | | `POST` | `/agentmemory/import` | Importeer vanuit JSON | | `POST` | `/agentmemory/graph/query` | Knowledge-graph-query | | `POST` | `/agentmemory/graph/compact` | Trim overmatige graph-provenance | | `POST` | `/agentmemory/team/share` | Deel met team | | `GET` | `/agentmemory/audit` | Audit trail | Volledige endpointlijst: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Capture-levering.** Hooks sturen elke observatie één keer naar `POST /agentmemory/observe` met een `eventId`. Dit is de eigen id van de host voor de aanroep wanneer de payload er één heeft (bijvoorbeeld de `tool_use_id` van Claude Code), anders een hash van de sessie, hooktype, toolnaam, input, output en host-timestamp. De server schrijft het event naar een capture-inbox in de state store, slaat de observatie op, en verwijdert dan de inbox-entry. De statuscode zegt wat er gebeurd is: | Status | `status`-veld | Betekenis | |---|---|---| | `201` | `accepted` | Opgeslagen. `observationId` is de nieuwe observatie. | | `202` | `accepted` (`state: "retrying"`) | Geaccepteerd, maar opslaan mislukte. De server probeert het opnieuw, ook na een herstart. | | `200` | `duplicate` | Deze `eventId` was al geaccepteerd. `observationId` is de bestaande observatie; er wordt niets nieuws opgeslagen. | | `400` / `422` | `rejected` | Ongeldige payload, of opslaan mislukte definitief (het event wordt bewaard als dead letter). | | `503` | `rejected` (`retryable: true`) | De inbox is vol (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks spoolen het event en versturen het later. | Mislukte events worden elke `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) opnieuw geprobeerd met verdubbelende backoff, tot `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Events die nog steeds mislukken blijven als dead letters in de inbox staan, worden vermeld op `/agentmemory/status` en de Health-pagina van de viewer, en kunnen opnieuw geprobeerd worden met `POST /agentmemory/capture/retry` (`{"eventId": "..."}` of `{"all": true}`). Geaccepteerde event-id's worden onthouden voor `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 uur, maximaal `AGENTMEMORY_CAPTURE_EVENTS_MAX` id's), zodat een hook die na een timeout of herstart opnieuw afgespeeld wordt, één keer wordt opgeslagen, terwijl twee afzonderlijke tool calls met hun eigen host-id's twee keer worden opgeslagen, ook als hun inhoud identiek is. Wanneer een observatie wordt verwijderd (forget, sessie-delete, eviction, auto-forget of een import die de store vervangt), wordt het event als verwijderd gemarkeerd voordat de observatie verdwijnt, zodat het opnieuw afspelen van dat event binnen hetzelfde venster beantwoord wordt als duplicate en niets opslaat. De state store schrijft elke 2 seconden naar disk, dus een beantwoord event kan nog even alleen in het geheugen staan. Om dat te dekken draagt elk `2xx`-antwoord ook de `bootId` van de server (nieuw bij elke start), `acceptedAt` en `durableAfterMs` (het save-interval plus 1.5 s op de file store, 1.5 s op redis, waar persistentie de instelling van de operator is). Hooks houden het event in de lokale spool totdat dat venster verstreken is en verwijderen het bij een latere aanroep zonder een extra request. Als de `bootId` inmiddels veranderd is, is de server herstart, dus stuurt de hook het event opnieuw met dezelfde `eventId`; een event dat de disk al bereikt had, wordt niet twee keer opgeslagen. De server stuurt zulke events ook zelf bij het opstarten en bij elk retry-interval, zodat een herstart niets verliest, zelfs als er daarna geen hook meer draait. Oudere hooks negeren de extra velden, en nieuwe hooks tegen een oudere server verwerpen het event bij `2xx` zoals voorheen. Wanneer de server down is, niet op tijd antwoordt, of een 5xx teruggeeft, voegt de hook de observatie toe aan een lokaal spool-bestand, `/capture-spool/-.jsonl` (overschrijf de map met `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Het bestand is privé voor je gebruiker (modus 600), secrets worden op dezelfde manier geredigeerd als de server ze redigeert, het bevat maximaal `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) en laat entries vallen die ouder zijn dan `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Wanneer het vol is, worden nieuwe entries verwijderd en geteld, en rapporteert `/agentmemory/status` dit. De hook sluit nog steeds af met 0 binnen zijn tijdslimiet en voegt geen request toe wanneer de server gezond is. De spool wordt verstuurd bij de volgende start en door de eerste hook die de server weer bereikt, in een achtergrondproces zodat de agent niet wacht. Event-id's maken dit veilig: een observatie die al aankwam vóór een timeout wordt niet twee keer opgeslagen. `npx @agentmemory/agentmemory capture` toont de spool en de server-inbox, `--drain` stuurt de spool nu, en `GET /agentmemory/capture` geeft hetzelfde terug als JSON. Stel `AGENTMEMORY_CAPTURE_SPOOL=false` in om de spool uit te zetten. **Graph-provenance compacten.** Het compacten van oude provenance wordt bij het opstarten uitgesteld omdat het volledige oude scopes leest. `/agentmemory/status` meldt `deferred`, of `off` bij `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Voer het onderstaande handmatige compacten uit tijdens onderhoud. De migratie van de zoekindex staat hier los van: gebruik `agentmemory graph-index migrate --allow-legacy-scan` volgens de [onderhoudsgids](../docs/reliability/graph-index-migration.md). Om het handmatig te draaien, roep je `POST /agentmemory/graph/compact` aan. Het loopt door de name- en edge-key-indexen in plaats van elke node en edge op te lijsten, en is veilig om opnieuw te draaien. Wanneer het id's trimt, schrijft het een `graph_compact`-audit-entry. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}' ``` Draai het op een grote store, of wanneer de aanroep 504 teruggeeft, in stukken. Stuur `scope` (`nodes`, `edges` of `history`), `offset` en `limit`, en roep het dan opnieuw aan met de teruggegeven `nextOffset` totdat deze `null` is. Doe dit voor `nodes`, `edges` en `history`, en sluit af met één `{"scope":"snapshot"}`-aanroep, omdat een gestukte run de gecachte snapshot niet aanraakt. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

Ontwikkeling

```bash npm run dev # Hot reload npm run build # Production build npm test # 5,000+ tests npm run test:integration # API tests (requires running services) ``` [Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)

Licentie

[Apache-2.0](../LICENSE)