Din kodeagent husker alt. Ikke mere genforklaring.
Built on iii engine
Persistent hukommelse til Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode og enhver MCP-klient.
---
## Installation
Krav:
- Node.js 20 eller nyere med npm og npx (`node -v`, `npm -v` og `npx -v`).
- Automatisk installation af iii-engine på macOS/Linux kræver også `curl`, en POSIX `sh` og `tar`. Minimale images som `node:20-slim` indeholder dem muligvis ikke.
- Native Windows kræver, at den fastlåste iii-engine v0.22.1 `iii.exe` installeres manuelt. WSL2 eller Docker Desktop er de andre understøttede veje.
Den kanoniske kommando til en ny installation:
```bash
npx -y @agentmemory/agentmemory@latest
```
Den første kørsel er en interaktiv opsætning: du vælger de agenter, der skal forbindes (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), vælger en LLM-udbyder eller fortsætter uden nøgle, og den udfylder konfigurationen, starter hukommelsesserveren og dens fastlåste iii-engine, og tilbyder at installere globalt, så den rene `agentmemory`-kommando fungerer alle steder bagefter. `-y` accepterer npx's pakke-prompt, og `@latest` undgår en forældet, cachet udgivelse. En udbyder gør LLM-funktioner tilgængelige, men LLM-skrevet observationskomprimering starter kun, når `AGENTMEMORY_AUTO_COMPRESS=true` også er sat.
Nøgleløs tilstand deaktiverer vektor-embeddings. `memory_recall` (stien `mem::search`) bruger BM25, mens `memory_smart_search` også kan kombinere strukturelle graf-match, når der allerede findes graf-data. For gratis semantisk recall på enheden, sæt `EMBEDDING_PROVIDER=local` i `~/.agentmemory/.env` og genstart. Den første embedding-forespørgsel downloader `Xenova/all-MiniLM-L6-v2`; herefter køres inferens lokalt.
Den lokale runtime bruger fire porte: `3111` til REST/MCP HTTP, `3112` til iii-streams, `3113` til viewer, og `49134` til iii-workerens WebSocket. Persistent iii-tilstand ligger i `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, og `%APPDATA%\agentmemory` på Windows. Brug `--data-dir ` eller `AGENTMEMORY_DATA_DIR` til at ændre det, og genbrug samme værdi ved hver genstart. Af bagudkompatibilitet har en eksisterende `./data/state_store.db` eller `./data/iii-config.yaml` forrang over platformens standardplacering for instans 0; et eksplicit flag eller en miljøvariabel vinder stadig.
Bevis derefter, at recall virker, og giv din agent dens 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
```
Nøgleordssøgningerne bør give hit i standard nøgleløs tilstand via BM25. Demoens `database performance optimization`-forespørgsel er bevidst semantisk og kan give nul resultater, før en embedding-udbyder er konfigureret.
Foretrækker du, at en kodeagent gør det hele selv? Giv den en enkelt instruktion:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Forbind flere agenter når som helst med `agentmemory connect ` — 20 adaptere er listet under [Works with every agent](#works-with-every-agent). Fuld kommandoreference under [Quick Start](#quick-start).
Windows
Den hurtige vej er WSL2. Opsætning af native Windows-engine kræver, at den fastlåste v0.22.1-ZIP downloades, og at `iii.exe` udpakkes manuelt; CLI'en udpakker ikke automatisk. Docker Desktop understøttes også. Se [Windows-noterne](#windows) for trin-for-trin-vejledningen.
Global installation / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
npx-kommandoen ovenfor er stadig den kanoniske vej til en ny installation og undgår problemer med rettigheder til global-prefix.
npx leverer en gammel version
npx cacher pr. version. Tving den nyeste med `npx -y @agentmemory/agentmemory@latest`, eller ryd cachen én gang med `rm -rf ~/.npm/_npx` (macOS/Linux; på Windows slettes `%LOCALAPPDATA%\npm-cache\_npx`).
Kører allerede din egen iii-engine
agentmemory fastlåser iii-engine v0.22.1 og tilkobler sig ikke en anden version (workeren kan ikke tale en anden engines protokol). Stop den anden engine, og kør derefter `npx -y @agentmemory/agentmemory@latest`. Den installerer og kører den fastlåste v0.22.1 i `~/.agentmemory/bin` og lader din egen `iii` være uberørt.
---
agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST API. Alle agenter deler den samme hukommelsesserver.
Claude Code native plugin + 12 hooks + MCP
Codex CLI native plugin + 6 hooks + MCP
GitHub Copilot CLI MCP + plugin hooks/skills
Cursor native plugin + 7 hooks + MCP
OpenCode capture plugin + MCP
Devin 6 hooks + skills + MCP
OpenClaw native plugin + MCP
Hermes native plugin + MCP
pi native plugin + MCP
OpenHuman native Memory trait backend
Gemini CLI MCP server
Antigravity MCP + hooks
Claude Desktop MCP server
Warp connect + MCP + skills
Zed MCP server
Cline MCP server
Continue MCP server
Droid MCP server
Kiro MCP server
Qwen Code MCP server
DeepSeek Harness MCP server
Roo Code MCP server
Kilo Code MCP server
Goose MCP server
Aider REST API
Fungerer med enhver agent, der taler MCP eller HTTP. Én server — hukommelse delt mellem dem alle.
---
Du forklarer den samme arkitektur i hver session. Du genopdager de samme fejl. Du genunderviser i de samme præferencer. Indbygget hukommelse (CLAUDE.md, .cursorrules) topper ved 200 linjer og bliver forældet. agentmemory løser dette. Den indsamler stille og roligt, hvad din agent gør, komprimerer det til søgbar hukommelse og injicerer den rette kontekst, når den næste session starter. Én kommando. Fungerer tværs af agenter.
**Hvad der ændrer sig:** I session 1 sætter du JWT-autentificering op. I session 2 beder du om rate limiting. Agenten ved allerede, at din auth bruger jose-middleware i `src/middleware/auth.ts`, at dine tests dækker token-validering, og at du valgte jose frem for jsonwebtoken af hensyn til Edge-kompatibilitet — uden genforklaring og uden copy-paste.
```bash
npx -y @agentmemory/agentmemory@latest
```
Som standard lagrer agentmemory iii-engine-tilstand uden for det repository, du starter den fra: `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, og `%APPDATA%\agentmemory` på Windows. En eksisterende, forældet `./data/state_store.db` eller `./data/iii-config.yaml` genbruges til instans 0 før platformens standard. For at vælge en placering eksplicit, angiv `--data-dir ` eller sæt `AGENTMEMORY_DATA_DIR`; begge eksplicitte indstillinger har forrang over den forældede opdagelse:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
Native og Docker-opstarter bruger samme opløste hostmappe; Docker bind-mounter den på `/data`. `--instance 1` tilføjer `instance-1` til den opløste mappe og vælger den separate standard-portkvartet `3211/3212/3213/49234`.
Seneste udgivelsesnoter: [CHANGELOG.md](../CHANGELOG.md).
---
### Retrieval-nøjagtighed
**coding-agent-life-v1** (internt korpus, reproducerbart i sandbox)
| Adapter | P@5 | R@5 | Top-5-hitrate | p50-latens |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep-baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
100% top-5-hitrate ved **P@5-matematikkens loft** for dette korpus (0.240, se scorecard). Hybrid finder hver gylden session; grep misser 1 af 2 gyldne i den multi-session-temporale forespørgsel. Forbedringen er **recall + temporal**, ikke samlet precision. Dette benchmark er lille og har få gyldne eksempler; det større LongMemEval-S nedenfor differentierer bedre. Fuld opdeling pr. type + korrektionsnote: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
**LongMemEval-S** (ICLR 2025, 500 spørgsmål)
| System | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| Kun BM25-fallback | 86.2% | 94.6% | 71.5% |
> Embedding-model: `all-MiniLM-L6-v2` (lokal, gratis, ingen API-nøgle). Fulde rapporter: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Konkurrentsammenligning: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), der dækker agentmemory vs. mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
**Reproducér lokalt:** [`eval/README.md`](../eval/README.md), en adapter-plugbar harness til LongMemEval `_s` (offentligt 500-spørgsmåls-sæt) + `coding-agent-life-v1` (internt korpus med 15 sessioner). Grep-, vektor- og agentmemory-adaptere scorer side om side, NDJSON-output, publicerede scorecards lander i [`docs/benchmarks/`](../docs/benchmarks/).
**Fungerer godt sammen med [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) og [Graphify](https://github.com/safishamsi/graphify).** Code-graph-indeksering, multi-agent build-pipelines og bredere videngrafer tværs af dokumenter/PDF'er/billeder/videoer. agentmemory husker arbejdet; disse tre projekter oplyser resten af kontekstlaget. Opskrifter + spørgsmålsrouting-tabel: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
Benchmark-note: kun agentmemorys R@5 er vores eget målte resultat (LongMemEval-S, reproducerbart fra benchmark/COMPARISON.md). Tallene for mem0 og Letta er deres publicerede LoCoMo-tal (et andet datasæt); tallene for MemPalace, supermemory, TencentDB (PersonaMem) og oracleagentmemory er leverandørens selvrapporterede påstande, som vi ikke selv har reproduceret (oracleagentmemorys kørsel brugte GPT-5.5 mod en Oracle AI Database). Vist side om side kun som et groft overblik, ikke en direkte sammenligning på identiske data. Stjerneantal er cirka og ændrer sig over tid.
**Nyere aktører**, som er værd at kende, sammenlignet i detaljer i [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| System | ⭐ | Vinkel |
|--------|---|-------|
| Zep / Graphiti | 30K | Temporal videngraf; stærkeste publicerede resultater for temporale forespørgsler (LongMemEval 63.8%), men grafen bygges asynkront, så nye fakta kan halte |
| Cognee | 30K | Dokument-til-videngraf-indlæsning, kun Python, bygget til struktureret entitetsudtrækning snarere end sessionsindsamling |
Ingen af disse indsamler automatisk fra kodeagent-hooks, leverer en local-first viewer eller kan køre uden nøgle — den kombination er agentmemory bygget omkring.
---
Kompatibilitet: denne udgivelse målretter `iii-sdk` 0.22.1 og fastlåser iii-engine v0.22.1.
### Prøv det på 30 sekunder
```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` seeder 3 realistiske sessioner (JWT-auth, N+1-forespørgselsfix, rate limiting) og kører søgninger mod dem. Nøgleløse installationer deaktiverer vektorer, så nøgleordsforespørgslerne via `mem::search` bør give hit via BM25, mens `database performance optimization` kan give nul resultater. `smart-search` kan desuden returnere strukturelle graf-match, når der findes graf-data. For at få den semantiske forespørgsel til at finde N+1-fixet via vektorer, sæt `EMBEDDING_PROVIDER=local`, genstart, og lad den første modeldownload færdiggøre.
Åbn `http://localhost:3113` for at se hukommelsen bygges live.
### Validér en frisk installation og persistens ved genstart
Mens serveren kører, validér REST, health, viewer og den iii-baserede runtime-status:
```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
```
Opstartens ready-panel tager højde for alle fire porte: REST/MCP HTTP på 3111, iii-streams på 3112, viewer på 3113, og iii-workerens WebSocket på 49134. `status` bekræfter agentmemorys health og den aktive provider-/embedding-tilstand. Gem en probe, og bekræft at den er søgbar:
```bash
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-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 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Kør derefter `npx -y @agentmemory/agentmemory@latest stop`, start den kanoniske kommando igen i Terminal 1, vent på `/agentmemory/livez`, og gentag søgningen. Proben skal stadig returneres. Hvis du valgte en brugerdefineret `--data-dir`, så angiv samme mappe ved genstarten.
### Daglige kommandoer
Installation og opsætning findes under [Install](#install) ovenfor (den første kørsel guider dig igennem det). Til dagligt brug:
```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
```
### Session-genafspilning
Hver session, agentmemory optager, kan genafspilles. Åbn viewer, vælg fanen **Replay**, og spol gennem tidslinjen: prompts, tool calls, tool-resultater og svar vises som enkeltstående events med afspil/pause, hastighedskontrol (0.5x til 4x) og tastaturgenveje (space til at skifte afspil/pause, piletaster til at trinvist bevæge dig).
For at importere ældre Claude Code JSONL-transskripter:
```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
```
Importerede sessioner vises i Replay-vælgeren sammen med de native. Under motorhjelmen router hver post gennem iii-funktionerne `mem::replay::load`, `mem::replay::sessions` og `mem::replay::import-jsonl`, uden side-channel-servere. Hvert importeret transskript indekseres til søgning, stemples med oprindelseskanalen `import`, og udvindes for en session-crystal og lessons.
> **Vigtigt, hvis du afhænger af `import-jsonl` som din primære indsamlingsvej:** Claude Codes `cleanupPeriodDays` (i `~/.claude/settings.json`, standard **30**) sletter automatisk JSONL-transskripter, der er ældre end dette vindue, fra `~/.claude/projects/`. Hvis du installerer agentmemory helt nyt mod en måneder gammel Claude Code-historik, er alt ældre end 30 dage allerede væk, før den første import. Kør enten `import-jsonl` via en cron, hæv `cleanupPeriodDays` til noget højere, eller forbind auto-capture-hooks (standard-installationsvejen for pluginet), så hver tur lander i agentmemory, mens sessionen er aktiv, og JSONL-ryddet ikke længere betyder noget.
### Opgradering / vedligeholdelse
Brug vedligeholdelseskommandoen, når du bevidst vil opdatere din lokale runtime:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Advarsel: denne kommando ændrer det nuværende workspace/runtime. Den kan opdatere JavaScript-afhængigheder og hente det fastlåste `iiidev/iii:0.22.1` Docker-image. Den installerer aldrig en ikke-fastlåst eller nyere iii-engine.
Implementeringsdetaljer findes i `src/cli.ts` (se `runUpgrade` omkring regionen `src/cli.ts:544-595`).
### Claude Code (én blok, indsæt den)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. 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 uden plugin-installation (MCP-standalone-vej)
Hvis du forbinder agentmemorys MCP-server via `~/.claude.json` direkte i stedet for at bruge `/plugin install`, opløser Claude Code aldrig `${CLAUDE_PLUGIN_ROOT}`, og du skal pege hook-scripts på absolutte paths i `~/.claude/settings.json`. Disse paths indeholder typisk agentmemory-versionen (f.eks. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), så den næste opgradering stille og roligt bryder hver hook.
Løsning:
```bash
agentmemory connect claude-code --with-hooks
```
Dette sammenføjer de samme hook-kommandoer i `~/.claude/settings.json` med absolutte paths, der peger på den medfølgende `plugin/`-mappe i den aktuelt installerede `@agentmemory/agentmemory`-pakke. Kør kommandoen igen efter opgradering af agentmemory for at opdatere paths. Brugerens egne indgange i samme fil bevares; kun tidligere agentmemory-indgange udskiftes. At bruge `/plugin install`-vejen er stadig den anbefalede metode.
Til eksterne eller beskyttede deployments, start Claude Code med `AGENTMEMORY_URL` og `AGENTMEMORY_SECRET` sat. Pluginet sender begge værdier videre til sin medfølgende MCP-server; når `AGENTMEMORY_URL` er tom, bruger MCP-shimmen `http://localhost:3111`.
### Codex CLI (Codex-plugin-platform)
```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
```
Codex-pluginet leveres fra samme `plugin/`-mappe som Claude Code-pluginet. Det registrerer:
- En medfølgende stdio MCP-bridge til den kørende daemon, uden npm-download eller fallback-lager. Se [den lokale Codex-guide](../docs/plugins/codex-local.md) for at teste en build, der endnu ikke er udgivet.
- 6 livscyklus-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 kaldbare skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, samt 8 referenceskills, som agenten indlæser efter behov (hukommelsesdisciplin, MCP-værktøjer, REST API, konfiguration, agenter, hooks, arkitektur og guiden til at skrive skills)
Codex' hook-motor injicerer `CLAUDE_PLUGIN_ROOT` i hook-underprocesser (jf. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), så de samme hook-scripts virker på begge hosts uden duplikering. Subagent-/SessionEnd-/Notification-/TaskCompleted-/PostToolUseFailure-events er kun til Claude Code og registreres ikke for Codex.
#### Codex-hooks: tillid og kompatibilitet
Native plugin-hook-afsendelse er verificeret med Codex CLI 0.150.1. Stol på plugin-hooks, før du forventer capture. Desktop-opførslen afhænger af dens medfølgende runtime; kontrollér `/hooks`, og bekræft en fanget hændelse, før du aktiverer en løsning.
Hvis din host kræver globale hooks, så spejl kommandoerne ind i `~/.codex/hooks.json`. Når MCP allerede er forbundet, skal den nuværende adapter bruge `--force` for at nå hook-installationen:
```bash
agentmemory connect codex --with-hooks --force
```
Dette sammenføjer globale hooks og omskriver agentmemory MCP-indgangen, og bevarer ikke-relaterede indgange. Gennemgå eventuelle tilpassede agentmemory endpoint-indstillinger, før du bruger `--force`. Kør igen efter opgradering for at opdatere scriptpaths. Aktivér enten native plugin-hooks eller globale kopier for at undgå duplikeret capture.
### GitHub Copilot CLI
Til VS Code agent-tilstand, brug [Copilot MCP- og auto-capture-guiden](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-adapteren konfigurerer ikke VS Code.
```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` sammenføjer `mcpServers.agentmemory` ind i `~/.copilot/mcp-config.json` (eller `$COPILOT_HOME/mcp-config.json`, når `COPILOT_HOME` er sat) og bevarer eksisterende servere. På native Windows er dette den eneste automatiserede `connect`-adapter; konfigurér alle andre native Windows-agenter manuelt. WSL `connect` understøttes kun, når målagenten er installeret i samme WSL-miljø. Copilot opdager MCP-serveren ved næste opstart eller efter `/mcp`. Installér også pluginet, når du vil have den fulde hook-/skill-oplevelse.
OpenClaw (indsæt denne 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`.
```
Fuld guide: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (indsæt denne 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 the agentmemory repo to ~/.hermes/plugins/agentmemory.
```
Fuld guide: [`integrations/hermes/`](../integrations/hermes/)
### Andre agenter
Start hukommelsesserveren: `npx -y @agentmemory/agentmemory@latest`
#### Native skills via `npx skills add` (50+ agenter)
agentmemory leveres med 17 skills i Claude-Code-stilens `/SKILL.md`-format: 9 kaldbare action-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) og 8 referenceskills, som agenten indlæser efter behov (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referenceskillene indeholder datatabeller genereret fra kildekoden, så de aldrig driver ud af kurs. [`skills`](https://npmjs.com/package/skills)-CLI'en fra vercel-labs installerer dem automatisk i den kaldende agents native skill-mappe på tværs af 50+ agenter (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf og flere):
```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
```
Dette er et **supplement** til `agentmemory connect `:
- `agentmemory connect ` skriver MCP-serverkonfigurationen, så værktøjerne er tilgængelige.
- `npx skills add rohitg00/agentmemory` installerer skillene, så agenten ved, hvornår den skal kalde dem.
For de få agenter, som skills-CLI'en endnu ikke dækker (Zed v1.3.x og tidligere), skal du selv placere de 17 SKILL.md-filer i agentens native skill-mappe; det samme format fungerer alle steder.
#### Standard MCP-blok
agentmemory-indgangen er den **samme MCP-serverblok** på alle hosts, der bruger `mcpServers`-formen (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}"
}
}
```
**Sammenføj denne indgang i det eksisterende `mcpServers`-objekt** i hostens konfigurationsfil; udskift ikke filen. Hvis filen allerede har andre servere, så tilføj `agentmemory` ved siden af dem som endnu en nøgle inde i `mcpServers`. Hvis `mcpServers` helt mangler, så indsæt blokken inden i `{ "mcpServers": { ... } }`. `${VAR}`-pladsholderne overtager `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` fra shellen, når MCP-serveren starter; ikke-satte variabler giver tomme strenge, og shimmen falder tilbage til `http://localhost:3111`. Én forbundet indgang dækker både lokale og eksterne (k8s/reverse-proxy'ede) deployments.
| Agent | Konfigurationsfil | Noter |
|---|---|---|
| **Cursor (kun MCP)** | `~/.cursor/mcp.json` | Sammenføj i `mcpServers`, eller brug `agentmemory connect cursor`. Et one-click deeplink er også tilgængeligt på hjemmesiden. |
| **Cursor (fuldt plugin)** | `.cursor-plugin/` | Cursor Marketplace-listing (indsendelse under review) eller Cursor Settings → Plugins → lokal checkout. Registrerer 7 auto-capture-hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + MCP-serveren, med `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` administreret i Cursors plugin-dashboard. Fungerer i Cursor IDE og `cursor-agent`-CLI'en; CLI print-mode-prompts efterudfyldes fra sessionstransskriptet ved sessionens afslutning. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Sammenføj i `mcpServers`. Genstart Claude Desktop efter redigering. |
| **Cline / Roo Code / Kilo Code** | Cline MCP-indstillinger (Settings UI → MCP Servers → Edit) | Samme `mcpServers`-blok. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` sammenføjer MCP-indgangen; `--with-hooks` tilføjer seks native auto-capture-hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) med Devins små bogstaver-tool-matchers. Bekræft med `devin mcp list` og `/hooks` inde i devin. |
| **Devin CLI (fuldt plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` fra en checkout registrerer alle 17 skills som `/agentmemory:`-slash-kommandoer plus MCP-serveren. Devins plugin-hooks kan ikke udløse `SessionStart`/`SessionEnd`, så kombinér det med `connect devin --with-hooks` for fuld sessionsindsamling. |
| **Devin (cloud)** | Settings → Connections → MCP servers | Tilføj en custom MCP (STDIO): kommando `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL`, der peger på en netværkstilgængelig agentmemory-deployment, plus `AGENTMEMORY_SECRET` (cloud-sessioner kan ikke nå localhost — se [`deploy/`](../deploy/)). Gem secreten i Devin Secrets, og brug derefter "Test listing tools" til at bekræfte, at alle 54 værktøjer vises. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (sammenføjer automatisk). |
| **GitHub Copilot CLI (kun MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` sammenføjer `mcpServers.agentmemory`; Copilot opdager den ved næste opstart eller `/mcp`. |
| **GitHub Copilot CLI (fuldt plugin)** | Copilot plugin-installation | `copilot plugin install rohitg00/agentmemory:plugin` for pluginet fra GitHub-undermappen. |
| **OpenClaw** | OpenClaw MCP-konfiguration | Samme `mcpServers`-blok. Dybere integration: `openclaw plugins install ./integrations/openclaw` tager OpenClaws memory-slot (skifter automatisk fra `memory-core`); sæt `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, ellers blokeres tur-indsamlingen stille og roligt. Se [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (kun MCP)** | `.codex/config.toml` | TOML-form: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, eller tilføj `[mcp_servers.agentmemory]` manuelt. |
| **Codex CLI (fuldt plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory`, derefter `codex plugin add agentmemory@agentmemory`. Registrerer MCP + 6 livscyklus-hooks + 17 skills. Stol på hooks, og bekræft capture på din host; se [Codex-opsætning og validering](../docs/plugins/codex-local.md). |
| **OpenCode (kun MCP)** | `opencode.json` | Anden form: en `mcp`-nøgle på topniveau, kommando som array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (fuldt plugin)** | `plugin/opencode/` | 22 auto-capture-hooks, der dækker sessionslivscyklus, beskeder, tools og fejl. Projekttilskrivning er pr. session, så én OpenCode-proces, der spænder over flere repositories, journalfører hver session under sit eget projekt. To slash-kommandoer (`/recall`, `/remember`). Kopiér `plugin/opencode/` ind i dit OpenCode-workspace, og tilføj plugin-indgangen til `opencode.json`. Se [`plugin/opencode/README.md`](../plugin/opencode/README.md) for den fulde hook-tabel + gap-analyse. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installerer den medfølgende extension i pi's auto-discovery-mappe (recall ved agentstart, capture ved agentafslutning, tools `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` i en kørende pi opdager den. [`integrations/pi`](../integrations/pi/) er også en pi-pakke (`pi install ./integrations/pi` fra en checkout). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` giver den 6-hook hukommelsesprovider (prefetch, turindsamling, sessionsafslutning, pre-compress, MEMORY.md-spejling, system-prompt-blok). Validér med `hermes plugins doctor` og `hermes memory status`. Se [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` skriver standard-`mcpServers`-blokken. Hook-payloaden er felt-kompatibel med Claude Code, så de eksisterende 12-hook-scripts fungerer uden ændringer; forbind dem via `hooks`-sektionen i samme `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installerer MCP og capture-hooks i den delte tilpasningsmappe. Se [Antigravity-opsætning og begrænsninger](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` bruger samme MCP- og hook-konfiguration som de nuværende IDE-versioner. Eksisterende installationer bør opdateres med `--force`; se [opgraderingsnoterne](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` skriver konfigurationen på brugerniveau. Workspace-overrides placeres i `.kiro/settings/mcp.json` ved siden af din kode. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` skriver standard-`mcpServers`-blokken. Warp opdager også automatisk skills fra `.claude/skills/`; når Claude Code-pluginet er installeret, vises de 8 agentmemory-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) nativt i Warps slash-kommando-palette. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` skriver standard-`mcpServers`-blokken. Brugere af VS Code-extensionen: indsæt samme blok via Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (foretrukket) eller `config.json` (legacy) | `agentmemory connect continue` opretter `config.yaml` fra bunden, når ingen af dem findes, eller ændrer en eksisterende `config.json`. **Hvis du allerede har `config.yaml`**, printer adapteren den nøjagtige blok, du skal indsætte under `mcpServers:`; den omskriver ikke stille og roligt din yaml, fordi sikker bevarelse af kommentarer og anchors kræver en YAML-parser, som pakken ikke leverer. Continue bruger array-form (ikke objekt) til `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` skriver under `context_servers` (Zeds nøgle, IKKE `mcpServers`). Eksterne MCP-servere kan i stedet forbindes via `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` skriver standard-`mcpServers`-blokken. Projekt-scopede overrides placeres i `/.factory/mcp.json`. Angiv `--with-hooks` for native auto-capture. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` tilføjer en `@deepseek-ai/dsh-mcp-client`-række til det home-niveau patch-lag, som hver Harness-profil indlæser; tools registreres som `mcp__agentmemory__*`. Angiv `--with-hooks` for også at forbinde auto-capture: de medfølgende Claude Code-hook-scripts køres gennem Harness' egen `@deepseek-ai/dsh-hooks-claude-code`-bridge (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via et manifest skrevet til `$DSH_HOME/agentmemory.hooks.json`. Standard er `~/.dsh`, når `DSH_HOME` ikke er sat. |
| **Goose** | Goose MCP-indstillings-UI | Samme `mcpServers`-blok; brug `goose configure` → Add Extension → MCP. Direkte YAML-redigering i `~/.config/goose/config.yaml` understøttes, men skemaet bruger `extensions:` + `cmd` (ikke `mcpServers:` + `command`). |
| **Aider** | n/a | Tal direkte med REST API'et: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Enhver agent (32+)** | n/a | `npx skillkit install agentmemory` opdager automatisk hosten og sammenføjer. |
**Sandboxede MCP-klienter** (Flatpak/Snap/restriktive containere), der ikke kan nå hostens `localhost`: sæt også `"AGENTMEMORY_FORCE_PROXY": "1"` i `env`-blokken, og peg `AGENTMEMORY_URL` på en rute, sandboxen faktisk kan nå (f.eks. din LAN-IP).
### Programmatisk adgang (Python / Rust / Node)
agentmemory registrerer sine kerneoperationer som iii-funktioner (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Ethvert sprog med en iii SDK kan kalde dem direkte over `ws://localhost:49134`, uden en separat REST-klient pr. sprog.
```bash
pip install iii-sdk # Python
cargo add iii-sdk # Rust
npm install iii-sdk # Node
```
```python
from iii import register_worker
iii = register_worker("ws://localhost:49134")
iii.connect()
iii.trigger({
"function_id": "mem::smart-search",
"payload": {"project": "demo", "query": "how do tokens refresh"},
})
```
Gennemarbejdet eksempel: [`examples/python/`](../examples/python/) (quickstart + observations-/recall-flow). REST på `:3111` er stadig tilgængeligt for hosts uden en iii-runtime.
### Fra kildekode
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
Dette starter agentmemory med en lokal `iii-engine`, hvis den fastlåste binary allerede er installeret, eller bruger Docker Compose, når det er valgt. REST, streams og viewer binder til `127.0.0.1` som standard. Den automatiske binary-vej på macOS/Linux kræver `curl`, en POSIX `sh` og `tar`.
Installér `iii-engine` manuelt. **agentmemory fastlåser i øjeblikket `iii-engine` til `v0.22.1`**, samme udgivelse som dens `iii-sdk`-afhængighed; workeren taler denne engines wire-protokol, og 0.20.0 omorganiserede SDK-overfladen, så de to følges i agentmemorys udgivelser. Overskriv med `AGENTMEMORY_III_VERSION=`, hvis du kører din egen engine og ved, at den passer.
- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** erstat `aarch64-apple-darwin` med `x86_64-apple-darwin`
- **Linux x64:** erstat med `x86_64-unknown-linux-gnu`
- **Linux arm64:** erstat med `aarch64-unknown-linux-gnu`
- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` fra [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1), og udpak `iii.exe` til `%USERPROFILE%\.agentmemory\bin\iii.exe`
Hvert arkiv har en tilhørende `.sha256`-fil på udgivelsessiden; når du skifter platform, så brug den fils hash i checket ovenfor (på Windows: `Get-FileHash`). Den automatiske installer i `npx @agentmemory/agentmemory` fastlåser disse hashes og afviser et arkiv, der ikke matcher.
Eller brug Docker (den medfølgende `docker-compose.yml` henter `iiidev/iii:0.22.1`). Fuld dokumentation: [iii.dev/docs](https://iii.dev/docs).
### Windows
agentmemory kører på Windows 10/11, men Node.js-pakken alene er ikke nok; du skal også have den fastlåste iii-engine v0.22.1-runtime som en baggrundsproces. CLI'en udpakker ikke automatisk Windows-ZIP'en, så native Windows-brugere skal installere `iii.exe` manuelt, bruge WSL2 eller vælge Docker Desktop.
Automatiseret MCP-forbindelse på native Windows understøtter kun `agentmemory connect copilot-cli`. For Claude Code, Codex, Cursor og alle andre native Windows-agenter skal du kopiere den manuelle MCP-blok fra [Other agents](#other-agents) ind i den agents Windows-konfiguration. At køre `connect` i WSL er kun hensigtsmæssigt, når målagenten også er installeret i samme WSL-miljø; det redigerer ikke en Windows-host-agents konfiguration.
**Mulighed A: prækompileret Windows-binary (anbefalet)**
```powershell
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
# (agentmemory pins the engine to the same release as its iii-sdk;
# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe to agentmemory's private engine directory:
New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
& "$HOME\.agentmemory\bin\iii.exe" --version
# Should print: 0.22.1
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory@latest
```
**Mulighed B: Docker Desktop**
```powershell
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Select Docker explicitly and run agentmemory:
$env:AGENTMEMORY_USE_DOCKER = "1"
npx -y @agentmemory/agentmemory@latest
```
**Mulighed C: kun standalone MCP (ingen engine).** Hvis du kun har brug for MCP-værktøjerne til din agent og ikke behøver REST API, viewer eller cron-jobs, kan du springe engine'en helt over:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Diagnostik til Windows:** hvis `npx -y @agentmemory/agentmemory@latest` fejler, så kør den igen med `--verbose` for at se den faktiske engine-stderr. Almindelige fejltilstande:
| Symptom | Løsning |
|---|---|
| `The engine process started but the REST API never responded.` | Bekræft at alle fire afledte porte er frie, verificér at den fastlåste `iii.exe` forblev i live, og kør derefter igen med `--verbose`, og undersøg den fangede engine-stderr |
| `Could not start iii-engine` | Hverken `iii.exe` eller Docker er installeret. Se mulighed A eller B ovenfor |
| Portkonflikt | `netstat -ano \| findstr :3111` for at se, hvad der er bundet, og dræb det derefter, eller brug `--port ` |
| Docker-fallback springes over, selv om Docker er installeret | Sørg for, at Docker Desktop faktisk kører (ikon i systembakken) |
> Bemærk: iii-**engine** er en prækompileret binary, ikke en cargo crate, så prøv ikke at `cargo install` den. (iii-**SDK'erne** er publiceret på crates.io, npm og PyPI, men agentmemory har ikke brug for dem.) De understøttede installationsmetoder for engine er alle fastlåst til v0.22.1: den prækompilerede binary ovenfor, agentmemorys macOS/Linux-auto-installationsvej (`curl`, POSIX `sh` og `tar` er nødvendige), og Docker-imaget `iiidev/iii:0.22.1`. En ren upstream `install.sh | sh` installerer den nyeste engine, hvilket agentmemory ikke understøtter. Brug `npx -y @agentmemory/agentmemory@latest`; på macOS/Linux henter den den fastlåste engine ind i `~/.agentmemory/bin`.
---
Deployment
One-click-skabeloner til administrerede hosts. Hver enkelt leveres med en selvstændig Dockerfile, der henter `@agentmemory/agentmemory` fra npm og kopierer iii-engine-binaryen ind fra det officielle `iiidev/iii` Docker Hub-image; intet prækompileret agentmemory-image er nødvendigt. Persistent lagring monteres på `/data`; first-boot-entrypointet overskriver den npm-medfølgende iii-konfiguration (som binder `127.0.0.1`) med en deploy-tunet udgave, der binder `0.0.0.0` og bruger absolutte `/data`-paths, genererer HMAC-secreten, og frafalder derefter privilegier fra `root` til `node` via `gosu`, før den eksekverer agentmemory-CLI'en.
Renders one-click-deploy-knap kræver `render.yaml` i repositoryets rod, som vi med vilje holder ren. Brug Render Blueprint-flowet, dokumenteret i [`deploy/render/`](.././deploy/render/README.md), til manuelt at pege på blueprintet i repositoryet.
Fulde opsætningsdetaljer (HMAC-capture, SSH-tunnel til viewer, rotation, backup,
minimumsomkostninger) findes i [`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): én maskine med
`auto_stop_machines = "stop"`; billigst i tomgang.
- [`deploy/railway`](.././deploy/railway/README.md): fast pris på Hobby-planen,
volume i dashboardet.
- [`deploy/render`](.././deploy/render/README.md): Blueprint-flow,
automatiske disk-snapshots på betalte planer.
- [`deploy/coolify`](.././deploy/coolify/README.md): selvhostet på din
egen VPS via [Coolify](https://coolify.io/self-hosted); samme Docker
Compose-stack, du ejer hosten og dataene.
Kun port `3111` eksponeres. Viewer på `3113` forbliver bundet til
loopback inde i containeren; hver skabelons README dokumenterer
SSH-tunnel-mønsteret for at nå den.
---
Hver kodeagent glemmer alt, når sessionen slutter, og hver ny session starter med, at du genforklarer din stack. agentmemory kører i baggrunden og fjerner dette trin.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
agentmemory silently captures every tool use
Session ends -> observations compressed into structured memory
Session 2: "Now add rate limiting"
Agent already knows:
- 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
Zero re-explaining. Starts working immediately.
```
### vs. indbygget agenthukommelse
Hver AI-kodeagent leveres med indbygget hukommelse: Claude Code har `MEMORY.md`, Cursor har notepads, Cline har memory bank. Disse fungerer som gule post-it-sedler. agentmemory er den søgbare database bag post-it-sedlerne.
| | Indbygget (CLAUDE.md) | agentmemory |
|---|---|---|
| Skala | 200-linjers-loft | Ubegrænset |
| Søgning | Indlæser alt i konteksten | BM25 + vektor + graf (kun top-K) |
| Tokenomkostning | 22K+ ved 240 observationer | ~1,900 tokens (92% mindre) |
| Tværs af agenter | Filer pr. agent | MCP + REST (enhver agent) |
| Koordinering | Ingen | Leases, signaler, actions, routines |
| Observerbarhed | Læs filer manuelt | Realtids-viewer på :3113 |
---
### Hukommelsespipeline
```text
PostToolUse hook fires
-> SHA-256 dedup (5min window)
-> 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 SLOT_REFLECT_ENABLED=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject into conversation
```
### 4-lags hukommelseskonsolidering
Modelleret efter, hvordan menneskehjerner bearbejder hukommelse, inklusive søvnkonsolidering.
| Lag | Hvad | Analogi |
|------|------|---------|
| **Arbejdshukommelse** | Rå observationer fra tool-brug | Korttidshukommelse |
| **Episodisk** | Komprimerede sessionsopsummeringer | "Hvad der skete" |
| **Semantisk** | Udtrukne fakta og mønstre | "Hvad jeg ved" |
| **Procedurel** | Workflows og beslutningsmønstre | "Hvordan man gør det" |
Hukommelser forfalder over tid (Ebbinghaus-kurven). Ofte tilgåede hukommelser styrkes. Forældede hukommelser smides automatisk ud. Modsætninger opdages og løses.
### Hvad der indsamles
| Hook | Indsamler |
|------|----------|
| `SessionStart` | Projektsti, session-ID |
| `UserPromptSubmit` | Brugerprompts (privacy-filtreret) |
| `PreToolUse` | Filtilgangsmønstre + beriget kontekst |
| `PostToolUse` | Tool-navn, input, output |
| `PostToolUseFailure` | Fejlkontekst |
| `PreCompact` | Genindsætter hukommelse før compaction |
| `SubagentStart/Stop` | Subagent-livscyklus |
| `Stop` | Opsummering ved sessionsafslutning |
| `SessionEnd` | Markør for afsluttet session |
### Vigtigste funktioner
| Funktion | Beskrivelse |
|---|---|
| **Automatisk indsamling** | Hver tool-brug registreres via hooks, ingen manuel indsats |
| **Semantisk søgning** | BM25 + vektor + videngraf med RRF-fusion |
| **Hukommelsesudvikling** | Versionering, overskrivning (supersession), relationsgrafer |
| **Recall-hygiejne** | Overskrevne hukommelsesversioner forsvinder fra søgeindeksene; versionskæden i KV bevarer den fulde historik |
| **Hints om næsten-duplikater** | Gemninger rapporterer et vejledende `similarTo`-match, når nyt indhold ligner en eksisterende hukommelse |
| **Scoping pr. agent** | `agentId` følger med gennem save og recall tværs af REST, MCP og søgeindekset, i delt eller isoleret tilstand |
| **Herkomst ved skrivetidspunkt** | Hver observation og hukommelse bærer en uforanderlig oprindelseskanal (user, agent, tool, import eller shared), stemplet ved capture, save og import |
| **Auto-forglemmelse** | TTL-udløb, modstridsdetektion, vigtighedsbaseret udsmidning |
| **Privacy first** | API-nøgler, secrets, ``-tags fjernes før lagring |
| **Selvhelende** | Circuit breaker, fallback-kæde for providere, health-overvågning |
| **Claude-bridge** | Bidirektionel synkronisering med MEMORY.md |
| **Videngraf** | Entitetsudtrækning + BFS-traversering |
| **Team-hukommelse** | Namespaced delt + privat hukommelse mellem teammedlemmer |
| **Citationsherkomst** | Spor enhver hukommelse tilbage til kildeobservationerne |
| **Git-snapshots** | Versionér, rul tilbage og diff hukommelsestilstanden |
---
Trestrøms-retrieval, der kombinerer tre signaler:
| Strøm | Hvad den gør | Hvornår |
|---|---|---|
| **BM25** | Stemmet nøgleordsmatching med synonymudvidelse | Altid aktiv |
| **Vektor** | Cosine-similaritet over dense embeddings | Embedding-udbyder konfigureret |
| **Graf** | Videngraf-traversering via entitetsmatching | Entiteter opdaget i forespørgslen |
Fusioneret med Reciprocal Rank Fusion (RRF, k=60) og session-diversificeret (maks. 3 resultater pr. session).
Når et vektorindeks er udfyldt, bruger `mem::search` (bag `memory_recall`) den hybride BM25 + vektor-ranker. Uden embeddings bruger den BM25. `smart-search` kan desuden fusionere strukturelle graf-match, når der findes graf-data, også i nøgleløs tilstand. Lesson-recall køres på et dedikeret in-memory BM25-indeks i stedet for at scanne hele korpuset pr. forespørgsel. Overskrevne hukommelsesversioner udelukkes fra alle recall-veje; versionskæden bevarer deres historik.
Vektorer overlever et crash eller force-kill. Vektorindekset gemmes i buckets højst hver `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutter). Hver vektor, der tilføjes eller fjernes imellemtiden, skrives også straks til en lille ventende log i state-store'en, og den næste opstart afspiller den uden at kalde embedding-udbyderen. Hver gennemført save tømmer loggen. Dokumenter, der stadig ikke har en vektor efter afspilningen, genindlejres i baggrunden i batches af `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), indtil ingen er tilbage, og en backfill, der stoppes, fortsætter ved næste opstart. `/agentmemory/status` og viewer viser størrelsen af den ventende log og backfill-tilstanden. Nøgleløse installationer skriver ingenting.
BM25 tokeniserer græsk, kyrillisk, hebraisk, arabisk og accentueret latin ud af boksen. For kinesiske/japanske/koreanske hukommelser skal du installere de valgfrie segmenterere (`npm install @node-rs/jieba tiny-segmenter`) for at splitte CJK-forløb i ord-niveau-tokens; uden dem falder agentmemory blidt tilbage til hel-forløb-tokenisering og printer et engangshint på stderr.
### Embedding-udbydere
Nøgleløse installationer deaktiverer vektor-embeddings: `mem::search` bruger BM25, mens `smart-search` også kan bruge eksisterende strukturel graf-data. For at tilvælge gratis semantiske embeddings på enheden, tilføj dette til `~/.agentmemory/.env`, og genstart agentmemory:
```env
EMBEDDING_PROVIDER=local
```
Den normale npm-installation inkluderer den valgfrie `@huggingface/transformers`-runtime. Den første embedding-forespørgsel downloader `Xenova/all-MiniLM-L6-v2`, så den kræver netværksadgang og kan tage længere tid; efterfølgende inferens køres på enheden. Eksterne udbydere opdages automatisk fra deres nøgler, med mindre `EMBEDDING_PROVIDER` overskriver dem.
| Udbyder | Model | Pris | Noter |
|---|---|---|---|
| **Lokal (anbefalet tilvalg)** | `all-MiniLM-L6-v2` | Gratis | På enheden efter første modeldownload, +8pp recall over kun BM25 |
| Gemini | `gemini-embedding-001` | Gratis niveau | 100+ sprog, 768/1536/3072 dimensioner (MRL), 2048-token input. Afløser `text-embedding-004` ([udfaset, lukket 14. januar 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | Højeste kvalitet |
| Voyage AI | `voyage-code-3` | Betalt | Optimeret til kode |
| Cohere | `embed-english-v3.0` | Gratis prøveperiode | Generelt anvendelig |
| OpenRouter | Enhver model | Varierer | Multi-model-proxy |
---
54 værktøjer, 6 ressourcer, 3 prompts og 17 skills.
> **MCP-shim vs. fuld server:** den publicerede `@agentmemory/mcp`-pakke er en tynd shim. Den eksponerer den fulde overflade med 54 værktøjer **kun når den kan nå en kørende agentmemory-server** via `AGENTMEMORY_URL` (proxy-tilstand). Når ingen server kan nås, falder shimmen tilbage til et lokalt sæt på 7 værktøjer (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Miljøvariablen `AGENTMEMORY_TOOLS=core|all` er et flag på *serversiden*; at sætte den i shimmens `env`-blok har ingen effekt. Hvis du kun ser 7 værktøjer i Cursor / OpenCode / Gemini CLI, så start `npx -y @agentmemory/agentmemory@latest` (eller Docker-stacken), og sæt `AGENTMEMORY_URL=http://localhost:3111`.
### 54 værktøjer
Tre værktøjsoverflader, fra mindst til størst: `AGENTMEMORY_TOOLS=core` beskærer synligheden til 8 essentielle værktøjer (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); grundsættet nedenfor er registerets 14 fundamentale værktøjer; standarden (`AGENTMEMORY_TOOLS=all`) eksponerer alle 54.
Grundlæggende værktøjer (14)
| Værktøj | Beskrivelse |
|------|-------------|
| `memory_recall` | Søg i tidligere observationer |
| `memory_compress_file` | Komprimer markdown-filer, mens strukturen bevares |
| `memory_save` | Gem en indsigt, beslutning eller et mønster |
| `memory_file_history` | Tidligere observationer om specifikke filer |
| `memory_patterns` | Opdag tilbagevendende mønstre |
| `memory_sessions` | List de seneste sessioner |
| `memory_smart_search` | Hybrid semantisk + nøgleordssøgning |
| `memory_vision_search` | Søg i billedobservationer |
| `memory_timeline` | Kronologiske observationer |
| `memory_profile` | Projektprofil (koncepter, filer, mønstre) |
| `memory_export` | Eksportér alle hukommelsesdata |
| `memory_relations` | Forespørg relationsgrafen |
| `memory_commit_lookup` | Sessioner bag et git-commit |
| `memory_commits` | Commits registreret for en session |
Udvidede værktøjer (54 i alt, standardoverfladen)
| Værktøj | Beskrivelse |
|------|-------------|
| `memory_patterns` | Opdag tilbagevendende mønstre |
| `memory_timeline` | Kronologiske observationer |
| `memory_relations` | Forespørg relationsgrafen |
| `memory_graph_query` | Videngraf-traversering |
| `memory_consolidate` | Kør 4-lags konsolidering |
| `memory_claude_bridge_sync` | Synkronisér med MEMORY.md |
| `memory_team_share` | Del med teammedlemmer |
| `memory_team_feed` | Seneste delte elementer |
| `memory_audit` | Audit trail for operationer |
| `memory_governance_delete` | Slet med audit trail |
| `memory_snapshot_create` | Git-versioneret snapshot |
| `memory_action_create` | Opret arbejdselementer med afhængigheder |
| `memory_action_update` | Opdatér action-status |
| `memory_frontier` | Ublokerede actions rangeret efter prioritet |
| `memory_next` | Den enkelte vigtigste næste action |
| `memory_lease` | Eksklusive action-leases (multi-agent) |
| `memory_routine_run` | Instantiér workflow-routines |
| `memory_signal_send` | Besked mellem agenter |
| `memory_signal_read` | Læs beskeder med kvitteringer |
| `memory_checkpoint` | Eksterne betingelses-gates |
| `memory_mesh_sync` | P2P-synkronisering mellem instanser |
| `memory_sentinel_create` | Event-drevne watchers |
| `memory_sentinel_trigger` | Udløs sentinels eksternt |
| `memory_sketch_create` | Kortvarige action-grafer |
| `memory_sketch_promote` | Forfrem til permanent |
| `memory_crystallize` | Komprimér action-kæder |
| `memory_diagnose` | Health-checks |
| `memory_heal` | Auto-reparér fastlåst tilstand |
| `memory_facet_tag` | Dimension:værdi-tags |
| `memory_facet_query` | Forespørg via facet-tags |
| `memory_verify` | Spor herkomst |
### 6 ressourcer · 3 prompts · 17 skills
| Type | Navn | Beskrivelse |
|------|------|-------------|
| Ressource | `agentmemory://status` | Health, antal sessioner, antal hukommelser |
| Ressource | `agentmemory://project/{name}/profile` | Intelligens pr. projekt |
| Ressource | `agentmemory://project/{name}/recent` | Seneste observationer for et projekt |
| Ressource | `agentmemory://memories/latest` | De seneste 10 aktive hukommelser |
| Ressource | `agentmemory://graph/stats` | Videngraf-statistik |
| Ressource | `agentmemory://team/{id}/profile` | Delt teamprofil |
| Prompt | `recall_context` | Søg + returnér kontekst-beskeder |
| Prompt | `session_handoff` | Handoff-data mellem agenter |
| Prompt | `detect_patterns` | Analysér tilbagevendende mønstre |
| Skill | `/recall` | Søg i hukommelse |
| Skill | `/remember` | Gem til langtidshukommelse |
| Skill | `/session-history` | Seneste sessionsopsummeringer |
| Skill | `/forget` | Slet observationer/sessioner |
Tabellen viser de fire centrale skills. Det fulde sæt er 9 kaldbare skills plus 8 referenceskills; se afsnittet Native skills ovenfor.
### Standalone MCP
Køres uden den fulde server, til enhver MCP-klient. Begge disse fungerer:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Eller tilføj til din agents MCP-konfiguration:
De fleste agenter (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
Sammenføj `agentmemory`-indgangen i hostens eksisterende `mcpServers`-objekt, i stedet for at udskifte filen. For sandboxede klienter, der ikke kan nå hostens `localhost`, tilføj `"AGENTMEMORY_FORCE_PROXY": "1"` til env-blokken, og sæt `AGENTMEMORY_URL` til en rute, sandboxen kan nå.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Kopiér plugin-filen fra repositoryet:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
Starter automatisk på port `3113`. Viewer indlæser ét snapshot, når den forbinder (`GET /agentmemory/viewer/snapshot`), og anvender derefter live stream-events: nye hukommelser, lessons, observationer, audit-indgange, grafændringer og health-opdateringer vises uden polling eller gensidsindlæsninger. De eneste andre forespørgsler er de handlinger, du klikker på, "load more"-sider og søgninger. Når streamen falder ud, viser viewer, hvor gamle dens tal er, genforbinder med backoff, og resynkroniserer fra ét snapshot.
- **12 faner i fire grupper** med live-tal, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), tastaturgenveje og en mobilmenu.
- **Memories:** søgning på serversiden, filtre efter projekt, agent og type, et detaljepanel med versionskæden og en orddiff, herkomstlinks, kopiér-knapper til id'et, MCP-kaldet og en curl-kommando, rediger (en ny version), glem med bekræftelse, bulk-glem og JSON-eksport.
- **Sessions:** en indlejret observationstidslinje med læsbart tool-input og -output, filtre og paginering, samt de hukommelser og lessons, hver session gav.
- **Graph:** søgning, node-detaljer med relationer og kilder, en legende, der ikke udelukkende afhænger af farve, samt zoom-kontroller.
- **Health:** den levende version af `GET /agentmemory/status`. Hvert problem kommer med sin løsning, plus state-backenden, indeksets save-tilstand, fremdrift for graf-herkomst-kompaktering og en forklaring på konsolidering med de reelle tærskler.
- Siderne **Audit, Activity, Profile, Replay, Lessons, Actions og Crystals**, hver med en tom-tilstand, der siger, hvad sektionen er, hvorfor den er tom, og den kommando, der udfylder den, samt et `?`-ordliste-tooltip på hvert begreb og tal.
```bash
open http://localhost:3113
```
Viewer-serveren binder til `127.0.0.1` som standard og tilføjer server-secreten, når den videresender forespørgsler til REST API'et, så den kræver ingen opsætning. Den REST-serverede `/agentmemory/viewer`-endpoint følger de normale bearer-token-regler og omdirigerer browsere uden token til viewer-porten. CSP-headers bruger en per-response script-nonce og deaktiverer inline handler-attributter (`script-src-attr 'none'`).
---
Viewer på `:3113` viser, hvad din agent **huskede**. [iii console](https://iii.dev/docs/console) viser, hvad din agent **gjorde**: hver hukommelsesoperation som en OpenTelemetry-trace, hver KV-indgang redigerbar, hver funktion kaldbar, hver stream aftappelig. To vinduer på den samme hukommelse: ét produkt-formet, ét engine-formet.
agentmemory leverer dette gratis, fordi hvert funktionskald og trigger affyres gennem iii; intet custom, intet at instrumentere.
Workers-siden: hver forbundne worker, inklusive agentmemory selv, med PID, funktionstal, runtime og senest set.
**Allerede installeret.** Konsollen leveres med den fastlåste `iii`-engine (0.22+); intet separat at installere. Den første opstart downloader konsol-binaryen ved siden af enginen.
**Start sammen med agentmemory:**
```bash
agentmemory console
```
Dette kører den fastlåste engines `iii console` mod de porte, agentmemory har opløst (REST, streams, bridge), og serverer den én port over viewer, `http://localhost:3114` som standard. `--console-port N` vælger en anden port; `--port` og `--instance` vælger agentmemory-instansen på samme måde som for `stop`; ethvert andet flag videresendes, for eksempel `--enable-flow` til den eksperimentelle arkitektur-graf-side.
Det samme manuelt, nyttigt når `agentmemory` ikke er på PATH:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**Hvad du kan gøre fra konsollen:**
| Side | Brug den til at |
|------|-----------|
| **Workers** | Se hver forbundne worker og dens live metrics, inklusive agentmemory-workeren selv. |
| **Functions** | Kalde enhver af agentmemorys funktioner direkte med en JSON-payload; praktisk til at teste `memory.recall`, `memory.consolidate`, `graph.query` uden at forbinde en klient. |
| **Triggers** | Afspille HTTP-, cron-, event- og state-triggers igen: udløse konsoliderings-cronen manuelt, gentage en HTTP-rute, udsende en state-ændring. |
| **States** | KV-browser med fuld CRUD over sessioner, memory-slots, livscyklustimere og embeddings-indekset; redigere værdier direkte. |
| **Streams** | Live WebSocket-monitor for hukommelsesskrivninger, hook-events og observationsopdateringer, mens de flyder gennem iii-streams. |
| **Queues** | Durable queue-topics + dead-letter-håndtering. Afspille eller droppe mislykkede embedding-/kompressionsjobs. |
| **Traces** | OpenTelemetry waterfall-/flame-/service-breakdown-visninger. Filtrere efter `trace_id` for at se præcis, hvilke funktioner, DB-kald og embedding-forespørgsler en enkelt `memory.search` producerede. |
| **Logs** | Strukturerede OTEL-logs filtreret og korreleret til trace-/span-ID'er. |
| **Config** | Runtime-konfiguration: se præcis, hvilke workers, providere og porte din engine kører med. |
| **Flow** | (Valgfrit, `--enable-flow`) Interaktiv arkitekturgraf over hver worker, trigger og stream. |
Traces: waterfall-/flame-/service-breakdown for hver hukommelsesoperation.
**Traces er allerede aktiveret:**
`iii-config.yaml` leveres med `iii-observability`-workeren aktiveret (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Ingen ekstra konfiguration nødvendig; i det øjeblik agentmemory starter, udsender hver hukommelsesoperation en struktureret log, konsollen kan læse, og én ud af ti af dem (`sampling_ratio: 0.1`) udsender også et trace-span.
Hvis du i stedet vil eksportere til Jaeger/Honeycomb/Grafana Tempo, så ændr `exporter: memory` til `exporter: otlp`, og sæt collector-endpointet jf. iii's observability-dokumentation.
> **Vigtigt:** der er ingen auth gennemtvunget på konsollen selv; hold den bundet til `127.0.0.1` (standarden), og eksponér den aldrig offentligt.
---
agentmemory er **allerede en kørende [iii](https://iii.dev)-instans**. Tre primitiver (worker, function, trigger) sammensætter runtimen; KV-state, streams og OTEL-traces kommer fra iii-state-, iii-stream- og iii-observability-workers, der leveres med iii. Du installerede ikke Postgres, Redis, Express, pm2 eller Prometheus, fordi iii erstatter dem.
Det betyder, at én kommando mere udvider agentmemory med en helt ny funktion.
### Udvid agentmemory med flere workers
De builtins, agentmemory har brug for, er allerede i `iii-config.yaml` og starter op med den: `iii-state` (KV), `iii-queue` (durable retries til event-subscribers), `iii-pubsub`, `iii-cron`, `iii-stream` og `iii-observability` (OTEL-traces, metrics og logs på hver funktion). Alt andet fra [iii worker registry](https://workers.iii.dev) kobler sig til den samme engine: kopiér `iii-config.yaml` til `~/.agentmemory/iii-config.yaml` (CLI'en foretrækker denne fil frem for den medfølgende og indsætter stadig porte og data-paths i den), tilføj indgangen, installér worker-runtimen én gang med `~/.agentmemory/bin/iii update worker`, og genstart agentmemory.
```yaml
workers:
# ...the bundled entries...
- name: database # SQL-backed state adapter when you outgrow the KV defaults
- name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
- name: mcp # extra MCP servers next to agentmemory's, same engine
```
| Worker | Hvad du får i tillæg til agentmemory |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | SQL-baseret state-adapter, når du vokser fra KV-standarderne i hukommelsen |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Kode, der kom ud af `memory_recall`, køres inde i en kortlivet VM, ikke din shell |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Sæt ekstra MCP-servere op ved siden af agentmemorys, del samme engine |
På engine 0.22.x skal du bevare de `iii-`-præfikserede navne for builtins ovenfor; de upræfikserede `http`-, `state`-, `queue`-, `pubsub`- og `cron`-indgange er de selvstændige registry-workers, agentmemory flytter til med 0.23-migreringen.
Fuldt register: [workers.iii.dev](https://workers.iii.dev). Hver worker der sammensættes gennem de samme primitiver, agentmemory bruger, og den agentmemory, du allerede har, er én af dem.
### Engine-konfiguration og bind-adresse
`agentmemory start` læser engine-konfigurationen fra den første fil, der findes: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` i den aktuelle mappe, `~/.agentmemory/iii-config.yaml`, derefter den medfølgende `iii-config.yaml`. Ved hver opstart renderer den denne fil (data-paths, porte, state-backend) ind i `~/.agentmemory/data/iii-config.runtime.yaml` og starter enginen med den rendererede kopi, så redigér kildefilen, ikke den rendererede. `host:`-værdierne i kildefilen bevares som skrevet.
Den medfølgende `iii-config.yaml` binder bevidst `127.0.0.1`, og denne standard gælder også inde i en container. En CLI, der startes i en container, lytter på containerens loopback, så eksponerede porte ikke når nogen steder. For at servere en containeriseret CLI gennem eksponerede porte, sæt `AGENTMEMORY_III_CONFIG` til en konfiguration, der binder `0.0.0.0`. Den medfølgende `iii-config.docker.yaml` er en sådan: den binder `iii-http`, `iii-stream` og engine-porten til `0.0.0.0` og lagrer state under `/data`, så montér et skrivbart volume der. Hold `AGENTMEMORY_SECRET` sat, og eksponér kun de porte, du har brug for, på `127.0.0.1` eller bag en proxy, du har tillid til.
Dette repositorys `docker-compose.yml` går ikke gennem CLI'ens konfigurationsopslag: den monterer `iii-config.docker.yaml` på `/app/config.yaml`, og `iii-engine`-containeren starter med `--config /app/config.yaml`. One-click [deploy-skabelonerne](../deploy/) skriver deres egen `0.0.0.0`-konfiguration i deres entrypoints.
### Storage-backend: file (standard) vs. redis
`iii-state` og `iii-stream` falder som standard tilbage til iii-engines medfølgende filbaserede KV-lager: én JSON-fil pr. scope, holdt i engine-processens hukommelse og genskrevet til disk på en timer. Det er det rette standardvalg til en lokal single-user-installation; en delt daemon med flere samtidige skrivere får i stedet rigtige per-key-skrivninger fra Redis, til prisen af en netværksrundtur pr. operation (hvert `state::*`-kald serialiserer stadig på én Redis-forbindelse, så dette ombytter fillagrets lock til en socket, ikke til parallelisme).
Sæt `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) for at skifte begge workers til iii-engines indbyggede `redis`-adapter, som lagrer hver key som et Redis hash-felt (`HSET`) i stedet for at genskrive et helt scope ved hver skrivning:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
`AGENTMEMORY_STATE_BACKEND` er som standard `file`; at lade den stå usat bevarer dagens opførsel uændret, og en ikke-genkendt værdi (alt andet end `file` eller `redis`) er en opstartsfejl frem for en tavs fallback. `/agentmemory/status` og viewers Health-side (State store-rækken) rapporterer, hvilken backend der er aktiv, og om den svarer, aldrig URL'en.
**Kun almindelig `redis://`.** Den fastlåste engine (0.22.1) bygger sin Redis-klient uden TLS-understøttelse, så en `rediss://`-URL (de fleste administrerede Redis-tjenester, som Upstash, Redis Cloud og ElastiCache med kryptering under transport, er som standard kun TLS) kan ikke forbinde. Forbindelsen er ukrypteret, så Redis-adgangskoden og hver lagret hukommelse krydser ledningen i klartekst: peg på en lokal Redis eller én på et privat netværk, du har tillid til. For enhver anden Redis, så kør en krypteret tunnel (stunnel, SSH eller en VPN) på agentmemory-hosten, så det almindelige `redis://`-hop forbliver på den host, og tunnelens upstream-forbindelse er krypteret og autentificeret. Hvis en Redis-adgangskode indeholder et enkelt anførselstegn, så percent-encode det (`%27`); enginen udvider URL'en i sin YAML-konfiguration, før den parses.
**Én Redis-server pr. `--instance`.** Enginens Redis-key-præfikser (`state:`, `stream::`) er fikserede, så to agentmemory-instanser (`--instance 1`, `--instance 2`, ...), der peger på samme database, overskriver hinandens data. Et separat database-indeks (`redis://localhost:6379/1`) holder de lagrede data adskilt, men enginen relayerer live viewer-events over én Redis pub/sub-kanal (`stream::events`), og Redis pub/sub ignorerer database-indekset, så hver instans' viewer stadig ville vise den anden instans' live events. Giv hver instans sin egen Redis-server (eller port), når du kører mere end én.
**Hvad der er det samme, og hvad der er forskelligt.** Hver agentmemory-funktion fungerer på Redis: sessioner, observationer, hukommelser (remember, supersede, evolve, forget), søgning og indeks-buckets, lessons, grafen, audit-loggen og dens månedlige scopes, eksport og import, governance-sletninger, konsolideringsstatus, viewer-snapshottet og dens live stream, samt health-monitoren. Enginen lagrer hvert scope som ét Redis-hash (`HSET`/`HGET`/`HGETALL`) og udløser de samme state-triggers som fillagret. Tre engine-forskelle håndteres inde i agentmemory:
- Redis returnerer et scopes poster i ingen fast rækkefølge. agentmemory sorterer dem ældst først (efter oprettelsestidspunktet i post-id'et, derefter dets timestamp), så lister, paginering og eksport-chunks kommer tilbage i samme rækkefølge som på fillagret.
- Enginen anvender delvise opdateringer på Redis i et Lua-script, der gør tomme arrays til tomme objekter. agentmemory anvender selv disse opdateringer (læs, ændr, skriv under en per-key-lock) på Redis, så felter som `tags: []` forbliver arrays.
- Det gamle audit-log-check læser det gamle scope fra Redis i stedet for at kigge efter fillagrets fil på disken.
Én forskel kræver din indgriben: **efter Redis genstarter, stopper enginen med at relaye live events** til viewer, indtil agentmemory genstarter. Data gemmes og læses stadig normalt. Health-monitoren sender et testevent gennem Redis hvert 30. sekund; når det ikke kommer tilbage, viser `/agentmemory/status` og viewers Health-side "Live updates are not reaching the viewer" med løsningen: genstart agentmemory. Hvis Redis er nede, viser statusrapporten "The state store is not answering" og hvordan man tjekker det (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). At liste et meget stort scope læser hele hashet i ét `HGETALL`, samme omkostning som når fillagret holder det i hukommelsen.
**Anbefalede Redis-indstillinger.** Standard-snapshot-politikken `save 3600 1 300 100 60 10000` kan tabe minutter af skrivninger ved et crash, værre end fillagrets 5-sekunders flush-vindue. Sæt `appendonly yes` for alt, du ville være ked af at tabe. Sæt `maxmemory-policy noeviction`; `allkeys-lru` eller lignende smider stille og roligt hukommelser ud, så snart Redis når sin hukommelsesgrænse.
En native (ikke-Docker) opstart, og hver one-click [deploy-skabelon](../deploy/) (de overskriver den medfølgende `iii-config.yaml` og starter nativt), læser `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` og indsætter dem i den startede `iii-config`. Selve URL'en skrives aldrig til den rendererede fil, kun en `${AGENTMEMORY_REDIS_URL}`-reference, som engine-processen udvider fra sit eget miljø ved opstart. Kun dette repositorys egen Docker Compose-vej (`AGENTMEMORY_USE_DOCKER=1`, eller genoptagelse af en engine, der allerede er startet på den måde) monterer `iii-config.docker.yaml` skrivebeskyttet og renderer aldrig; `agentmemory start` advarer, når den registrerer denne kombination. Skift den fil manuelt, idet du følger samme `name: redis` / `config: redis_url: ...`-form, der vises i worker-dokumentationen for [iii-state](https://workers.iii.dev/workers/iii-state) og [iii-stream](https://workers.iii.dev/workers/iii-stream), og peg `redis_url` på en Redis, der kan nås fra containeren. `docker-compose.yml` sender `AGENTMEMORY_REDIS_URL` ind i engine-containeren, så `redis_url: '${AGENTMEMORY_REDIS_URL}'` fungerer der og holder URL'en ude af den monterede fil.
Den rendererede konfiguration holder URL'en ude af `~/.agentmemory/data/iii-config.runtime.yaml`, men enginens egen konfigurations-worker persisterer stadig den *udvidede* værdi til `~/.agentmemory/config/iii-state.yaml` og `iii-stream.yaml`, når den starter op (iii-engines `${VAR}`-udvidelse sker, før den worker lagrer sit seed, og den lagrer den opløste værdi, ikke referencen). Behandl den mappe som om den indeholder et credential: `chmod 700 ~/.agentmemory` på enhver delt host, og foretræk en Redis ACL-bruger, scopet til det, agentmemory har brug for, over databasens admin-credentials.
**Migrering er ikke automatisk.** At skifte `AGENTMEMORY_STATE_BACKEND` starter fra et tomt lager på begge sider; intet kopierer eksisterende data fra file til Redis eller tilbage. Eksportér fra den backend, du forlader, og importér til den, du flytter til. Dette køres identisk under bash og zsh (inklusive `bash -u`). Et array som `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gør ikke: zsh holder headeren som ét forkert-formet ord, hvor bash splitter den i to, så begge forespørgsler giver 401, når `AGENTMEMORY_SECRET` er sat:
```bash
# 0. Use the generated secret when none is exported:
AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
# 1. On the old backend, while agentmemory is still running on it:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
else
curl -fsS http://localhost:3111/agentmemory/export > backup.json
fi
# 2. Confirm backup.json is a usable export before switching backends:
jq -e '.version and .exportedAt' backup.json > /dev/null || {
echo "backup.json is not a valid export; do not switch backends" >&2
exit 1
}
# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
# restart agentmemory against the new backend, then:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
else
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
fi
```
`/agentmemory/export` accepterer også `?maxSessions=` og `?offset=` til at opdele et stort korpus over flere kald; `strategy` ved import er `merge` (standard-sikker), `replace` eller `skip`.
### Hvad iii erstatter
| Traditionel stack | agentmemory bruger |
|---|---|
| Express.js / Fastify | iii HTTP Triggers |
| SQLite / Postgres + pgvector | iii KV State + in-memory vektorindeks |
| SSE / Socket.io | iii Streams (WebSocket) |
| pm2 / systemd | iii engine worker-supervision |
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemer | `iii worker add ` |
**219 kildefiler · ~52,000 LOC · 2,500+ tests · 311 funktioner · 60 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
---
### LLM-udbydere
agentmemory opdager automatisk udbydere fra dit miljø. En udbyder gør LLM-baserede operationer tilgængelige, men udbyderkonfiguration alene aktiverer ikke LLM-skrevet observationskomprimering. Den vej kræver både en udbyder og `AGENTMEMORY_AUTO_COMPRESS=true`.
| Provider | Config | Notes |
|----------|--------|-------|
| **No-op (standard)** | Ingen konfiguration nødvendig | LLM-baseret compress/summarize er deaktiveret. Syntetisk komprimering og BM25-recall fungerer stadig. Se `AGENTMEMORY_ALLOW_AGENT_SDK` nedenfor, hvis du tidligere afhang af Claude-abonnements-fallbacken. |
| Anthropic API | `ANTHROPIC_API_KEY` | Per-token-fakturering |
| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
| Gemini | `GEMINI_API_KEY` | Aktiverer også embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Enhver model |
| OpenAI API | `OPENAI_API_KEY` | Standard `gpt-5.6-luna`, overskriv med `OPENAI_MODEL` |
| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) eller `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alt, der er OpenAI-API-kompatibelt. Ingen omkostning, kører på din egen hardware. Se [Lokale modeller](#local-models-ollama--lm-studio--vllm) nedenfor. |
| Claude-abonnements-fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Kun tilvalg. Starter `@anthropic-ai/claude-agent-sdk`-sessioner; det forårsagede tidligere ubegrænset Stop-hook-rekursion, så det er ikke længere standard. |
### Lokale modeller (Ollama / LM Studio / vLLM)
agentmemory taler med enhver OpenAI-API-kompatibel server, så alt, der eksponerer `/v1/chat/completions`, fungerer uden kodeændringer. Ingen betalte nøgler, ingen cloud, ingen rate limits; kører helt på din egen hardware.
**Ollama** (standardport `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** (standardport `1234`):
Åbn LM Studio → fanen Local Server → Start Server. Vælg en vilkårlig chat-model fra vælgeren (Qwen 3, gpt-oss, DeepSeek R1 osv.).
```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**: samme form. Peg `OPENAI_BASE_URL` på den URL, din server eksponerer, og sæt `OPENAI_MODEL` til et navn, din server vil acceptere.
**Modelvalg til hukommelsesarbejde**: komprimering og opsummering er korte opgaver (<2K tokens ind, <500 tokens ud), hvor en 7B instruct-model er mere end rigeligt. Anbefalinger:
| Model | Størrelse | Hvorfor |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | Balanceret standard på en 16 GB-maskine; stærk til udtrækning og tool-formet tekst |
| `qwen3:4b` | ~2.6 GB | Mindste fornuftige mulighed; fin til komprimering, svagere til graf-udtrækning |
| `qwen3-coder:30b` | ~19 GB | Bedste lokale valg til kode-formede sessioner (30B MoE, 3.3B aktive) på 24-32 GB hardware |
| `gpt-oss:20b` | ~14 GB | Stærk generel model, der passer til 16 GB RAM |
| `deepseek-r1:8b` | ~5.2 GB | Reasoning-distillat; langsommere, men renere udtrækninger |
Qwen 3-modeller tænker som standard og kan brænde hele token-budgettet på reasoning, før der kommer nogen output. Sæt `AGENTMEMORY_LLM_NOTHINK=1` for at tilføje `/no_think` til graf-udtræknings-prompts, og hæv `MAX_TOKENS` (16384 virker), hvis udtrækninger kommer tomme tilbage.
Reasoning-klasse-modeller (`o1`-stil med ``-blokke) kan returnere tomt `content` med et `reasoning`-felt, din lokale server muligvis ikke eksponerer. Hvis udtrækninger kommer tomme tilbage, skal du først skifte til en ikke-reasoning-model. Miljøvariablen `OPENAI_REASONING_EFFORT=none` kan også deaktivere thinking på Ollama Cloud thinking-modeller, der spejler OpenAI's reasoning-skema.
Lokale embeddings leveres som en valgfri afhængighed, men er ikke aktiveret som standard. Sæt `EMBEDDING_PROVIDER=local` for at tilvælge `Xenova/all-MiniLM-L6-v2` (384-dim). Den første embedding-forespørgsel downloader modellen; inferens er derefter på enheden. Uden denne indstilling eller en ekstern embedding-nøgle forbliver vektorer deaktiveret, `mem::search` bruger BM25, og `smart-search` kan stadig tilføje eksisterende graf-match.
### Kostbevidst modelvalg
Når LLM-skrevet baggrundskomprimering er aktiveret med både en udbyder og `AGENTMEMORY_AUTO_COMPRESS=true`, køres den på hver observation, så modelvalg ændrer de månedlige udgifter mærkbart. Indsamlet workload-data: 635 forespørgsler / 888K tokens / 35 timers aktiv brug, kørt mod tre OpenRouter-modeller med priser fra 2026-05-23.
| Tier | Model | Input / 1M | Output / 1M | Cost for the captured 35h | Notes |
|------|-------|------------|-------------|---------------------------|-------|
| Anbefalet | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Nyeste DeepSeek; billigste anbefalede valg til komprimerings-workloads. |
| Anbefalet | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid komprimerings- og opsummeringskvalitet ved ~10× lavere omkostning end Sonnet. |
| Anbefalet | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Stærk kode-reasoning, hvis dine sessioner er stærkt kode-formede. |
| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Samme listepris som den målte Sonnet 4.6-kørsel; $2/$10 introduktionspris til og med 2026-08-31. |
| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flagskibs-niveau; dyrt til always-on baggrundsarbejde. |
| Undgå | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flagskibs-klasse-model; overforbrug til komprimering. |
Målte rækker kommer fra den indsamlede kørsel; (est.)-rækker skalerer samme token-mix med hver models listepris.
agentmemory printer en runtime-advarsel, når `OPENROUTER_MODEL` matcher et premium-niveau-mønster. Sæt `AGENTMEMORY_SUPPRESS_COST_WARNING=1` for at dæmpe den, når du har taget et informeret valg.
Kvalitet vs. omkostning-afvejning til hukommelsesarbejde: komprimering er en opsummeringsopgave med relativt løse kvalitetskrav (agenten genlæser opsummeringen, ikke brugeren). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder lander inden for afrundingsfejl af Sonnet på denne opgave, mens de koster 10-70× mindre. Gem premium-niveau-modellerne til forespørgsler, du selv læser direkte.
Kilder: [OpenRouter-priser for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-prisnoter](https://api-docs.deepseek.com/quick_start/pricing/).
### Multi-agent-hukommelse (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
I multi-agent-opsætninger, hvor flere roller deler én agentmemory-server (architect / developer / reviewer / researcher / support-agent), tagger `AGENT_ID` hver skrivning med den rolle, der udførte den. `AGENTMEMORY_AGENT_SCOPE` styrer, om recall filtrerer efter dette tag.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
To tilstande:
| Tilstand | Tagger skrivninger | Filtrerer recall | Hvornår bruges den |
|------|------------|---------------|-------------|
| `shared` (standard) | ja | nej | Kontekst tværs af agenter med audit trail. Architect kan se, hvad developer noterede, men hver række registrerer, hvem der sagde det. |
| `isolated` | ja | ja | Striks adskillelse. Architect ser aldrig developers observationer/hukommelser/sessioner. |
Hvad der tagges, når `AGENT_ID` er sat: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rollen flyder fra `api::session::start` → `mem::observe` → `mem::compress` → KV.
Hvad der filtreres i isoleret tilstand: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Hver endpoint accepterer `?agentId=` til at overskrive pr. forespørgsel, og `?agentId=*` til helt at framelde env-scopet. `/memories` accepterer også `?includeOrphans=true` for at vise pre-AGENT_ID-hukommelser, hvis `agentId` er undefined.
Override pr. kald på SDK-/REST-laget: hver muterende endpoint (`/session/start`, `/remember`) accepterer et `agentId`-felt i request-body'en, som vinder over env'et. Nyttigt for runtimes, der ruter mange roller gennem én serverproces. MCP-værktøjet `memory_save` eksponerer det samme `agentId`-felt, den selvstændige stdio-server videresender både `agentId` og `project`, og gemte hukommelser bærer `agentId` ind i søgeindekset, så agent-scopet søgning dækker både hukommelser og observationer.
Når `AGENT_ID` ikke er sat, forbliver hukommelsen uscopet (legacy-opførsel, ingen tags, ingen filtre).
### Porte
agentmemory + iii-engine binder fire porte som standard. Hvis en genstart fejler med `port in use`, fortæller denne tabel dig, hvilken proces du skal kigge efter.
| Port | Proces | Formål | Env-override |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | Intern streams-worker (bruges af agentmemory + viewer) | `III_STREAM_PORT` (foretrukket) eller legacy `III_STREAMS_PORT` |
| `3113` | agentmemory | Realtids-viewer (`http://localhost:3113`) | `III_VIEWER_PORT` eller `AGENTMEMORY_VIEWER_URL` for den rapporterede URL |
| `49134` | iii-engine | WebSocket; workers registrerer sig her, OTel-telemetri flyder over den | `III_ENGINE_PORT` eller `III_ENGINE_URL` |
`--port ` ændrer REST-ankeret og afleder streams `N+1`, viewer `N+2` og engine-WebSocket `N+46023`, kun hvor den tilsvarende eksplicitte port eller URL ovenfor ikke er sat. Det opretter ikke et isoleret livscyklus-namespace. Brug `--instance 1` til en anden daemon; den bruger anker 3211, er som standard `3211/3212/3213/49234`, og får en separat `instance-1`-data- og livscyklusmappe. Instanser 1 til 50 følger samme mønster.
Den fastlåste engine starter med `--no-update-check` (ingen opslag efter opdateringer eller sikkerhedsråd mod GitHub ved boot) og med iii's anonyme brugstelemetri slået fra: agentmemory sætter `III_TELEMETRY_ENABLED=false` for den engine, den starter, med mindre du selv eksporterer variablen, og den medfølgende compose-fil gør det samme.
Rydning af forældede processer, når porte forbliver bundet efter en crashet kørsel:
```bash
# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true
# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
`agentmemory stop` rydder både worker- og engine-pidfilen pænt op ved en graciøs native nedlukning. I Docker-tilstand flusher den den native worker, stopper den nøjagtige validerede engine-container, og bevarer både containeren og dens `/data`-mount til en lossless genstart; den næste opstart validerer og genoptager samme container. Docker-baseret afinstallation kræver `agentmemory remove --keep-data`: den fjerner delte agentmemory-styrede filer, mens den bevarer den validerede container, dens data-mount og det livscyklus-record, der er nødvendigt for at gendanne dem. Destruktiv sletning af Docker-data er med vilje overlad til operatøren efter en backup. CLI'en afviser også at adoptere eller signalere Docker- eller VM-port-indehavere (Docker backend, vpnkit, colima) som den native engine, med mindre `--force` sendes med. Den manuelle rydning ovenfor er kun til post-crash-tilfældet, hvor ingen af pidfilerne er efterladt.
### Konfigurationsfil
Placér agentmemorys runtime-konfiguration i `~/.agentmemory/.env` i stedet for at eksportere variabler i hver shell. Hvis viewer viser et opsætningshint som `export ANTHROPIC_API_KEY=...`, kopiér det ind i denne fil som `ANTHROPIC_API_KEY=...` uden `export`-præfikset, og genstart derefter agentmemory.
Procesmiljøvariabler fungerer stadig og har forrang over værdier i filen.
På Windows ligger samme fil på `%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
For at teste med et Claude Code Pro/Max-abonnement i stedet for en API-nøgle, skal du tilvælge det eksplicit:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
LLM-skrevet observationskomprimering kræver begge linjer: adgang til en LLM-udbyder (inklusive denne eksplicitte abonnements-fallback) og `AGENTMEMORY_AUTO_COMPRESS=true`. En udbyder alene lader standard-stien med syntetisk komprimering forblive uændret.
Konsolidering (graf-noder, lessons, crystals) er aktiveret som standard, når en LLM-udbyder er konfigureret. Fravælg eksplicit med `CONSOLIDATION_ENABLED=false`, hvis du vil have LLM-fri drift. Graf-udtrækning er et separat flag:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Miljøvariabler
Opret `~/.agentmemory/.env`:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
# # OpenAI LLM provider (here) AND the OpenAI
# # embedding provider (further below). Set
# # OPENAI_API_KEY_FOR_LLM=false to scope it
# # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
# # Azure: https://.openai.azure.com/openai/deployments/
# # Auto-detected from `.openai.azure.com` hostname; uses
# # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
# # for back-compat with v0.9.17. New configs should
# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
# # Honored only by OpenAI's reasoning models (o1, o3,
# # gpt-*-reasoning) and providers that mirror that
# # schema (Ollama Cloud thinking models). Standard
# # chat models reject this field with 400. Set to
# # "none" for thinking models that return reasoning
# # but no content.
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
# raw-fetch provider (Gemini, OpenRouter, MiniMax,
# OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
# embedding). For the OpenAI LLM path, the
# OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
# takes precedence when set, for back-compat
# with v0.9.17.
# Increase for slow networks or large batch calls;
# decrease to fail-fast on rate-limit holds.
# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
# Features
# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
# provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
# token spend on active sessions.
# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
# memory slots — persona,
# user_preferences, tool_guidelines,
# project_context, guidance,
# pending_items, session_patterns,
# self_notes. Size-limited; agent
# edits via memory_slot_* tools.
# Pinned slots addressable for
# SessionStart injection.
# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
# Stop hook fires mem::slot-reflect:
# scans recent observations, auto-
# appends TODOs to pending_items,
# counts patterns in
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
# (this is what actually reaches
# the model — Claude Code treats
# SessionStart stdout as context)
# - PreToolUse fires /agentmemory/enrich
# on every file-touching tool call
# (resource cleanup, not a token
# fix — PreToolUse stdout is debug
# log only per Claude Code docs)
# Observations are still captured via
# PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
# Storage and durability
# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
# A hard kill loses at most this window.
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
# shutdown and deletes still save at once.
# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
# provenance; false skips it
# Sessions
# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
# the threshold as abandoned. Deletes nothing;
# new activity makes the session active again.
# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
# Capture filters (hooks)
# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
# when set, only these tools are captured
# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
# defaults: memory_*, toolsearch,
# listmcpresources, fetchmcpresource
# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
# Audit log
# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
# rows (debugging only)
# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private
# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
# AGENTMEMORY_TOOLS=core
```
---
138 endpoints på port `3111`. REST API'et binder til `127.0.0.1` som standard. Beskyttede endpoints kræver `Authorization: Bearer `, og mesh-sync-endpoints kræver en eksplicit sat `AGENTMEMORY_SECRET` på begge peers.
**Autentificering er slået til som standard.** Når `AGENTMEMORY_SECRET` ikke er sat (i shellen eller i `~/.agentmemory/.env`), genererer serveren en tilfældig secret ved første opstart og lagrer den i `~/.agentmemory/secret` med rettigheden `0600`. Hver medfølgende klient læser den fra der, når den taler med en lokal server: CLI'en, viewer, hooks under `plugin/scripts`, MCP-serveren og `@agentmemory/mcp`-shimmen, konfigurationerne skrevet af `agentmemory connect`, og de medfølgende OpenCode-, Pi-, OpenClaw-, Hermes- og filesystem-watcher-integrationer. Den lagrede secret sendes kun til loopback-URL'er (`localhost`, `127.0.0.0/8`, `::1`). En eksplicit `AGENTMEMORY_SECRET` vinder altid, og eksterne klienter skal stadig have den sat. Docker og `deploy/`-entrypoints genererer og eksporterer allerede deres egen secret. For at kalde API'et manuelt:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**Request-regler for skrivninger.** `POST`-, `PUT`-, `PATCH`- og `DELETE`-forespørgsler til REST API'et og viewer skal sende `Content-Type: application/json` (en `charset`-parameter er fint) når de bærer en body, og en `Origin`-header, når den er til stede, skal være en loopback-origin for den konfigurerede REST- eller viewer-port eller være listet i `VIEWER_ALLOWED_ORIGINS` (kommasepareret, f.eks. `https://memory.example.com`). Klienter, der ikke sender en `Origin`-header (CLI, hooks, MCP, curl, server-til-server), er ikke påvirket. Viewer accepterer også sin egen origin.
**Filstier.** Endpoints, der læser eller skriver filer (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), accepterer kun paths under `~/.agentmemory`, instansens data-mappe, eller en mappe listet i `AGENTMEMORY_IMPORT_ROOT` (separér flere med `:`, eller `;` på Windows). `/replay/import-jsonl` accepterer også sin standard `~/.claude/projects`. `/obsidian/export` forbliver inden for `AGENTMEMORY_EXPORT_ROOT`, og `/migrate` inden for `~/.agentmemory`. Symlinks opløses før hvert check.
**Secret-scrubbing.** API-nøgler, bearer-tokens, PEM private key-blokke og credentials indlejret i URL'er (`scheme://user:password@host`) redigeres (redacted), før tekst lagres, på hver skrivevej: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, komprimerings- og opsummeringsoutput, crystals og graf-noder.
Centrale endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health-check (altid offentlig) |
| `GET` | `/agentmemory/status` | Hvad der er forkert, og hvordan det fikses (HTML til browsere, JSON i øvrigt) |
| `GET` | `/agentmemory/viewer/snapshot` | Alt det, viewer viser, i ét svar |
| `POST` | `/agentmemory/session/start` | Start session + få kontekst |
| `POST` | `/agentmemory/session/end` | Afslut session |
| `POST` | `/agentmemory/observe` | Indsaml observation (se capture-levering nedenfor) |
| `GET` | `/agentmemory/capture` | Capture-inbox, dead letters og offline-spool |
| `POST` | `/agentmemory/capture/retry` | Gentag dead-letter-captures |
| `POST` | `/agentmemory/capture/drain` | Send den lokale offline-spool nu |
| `POST` | `/agentmemory/smart-search` | Hybrid søgning |
| `POST` | `/agentmemory/context` | Generér kontekst |
| `POST` | `/agentmemory/remember` | Gem til langtidshukommelse |
| `POST` | `/agentmemory/forget` | Slet observationer |
| `POST` | `/agentmemory/enrich` | Filkontekst + hukommelser + bugs |
| `GET` | `/agentmemory/profile` | Projektprofil |
| `GET` | `/agentmemory/export` | Eksportér alle data |
| `POST` | `/agentmemory/import` | Importér fra JSON |
| `POST` | `/agentmemory/graph/query` | Videngraf-forespørgsel |
| `POST` | `/agentmemory/graph/compact` | Beskær overdimensioneret graf-herkomst |
| `POST` | `/agentmemory/team/share` | Del med team |
| `GET` | `/agentmemory/audit` | Audit trail |
Fuld endpoint-liste: [`src/triggers/api.ts`](../src/triggers/api.ts)
**Capture-levering.** Hooks sender hver observation én gang til `POST /agentmemory/observe` med et `eventId`. Det er hostens eget id for kaldet, når payloaden har et (for eksempel Claude Codes `tool_use_id`), ellers en hash af sessionen, hook-typen, tool-navnet, input, output og host-timestamp. Serveren skriver eventet til en capture-inbox i state-store'en, lagrer observationen, og fjerner derefter inbox-indgangen. Statuskoden siger, hvad der skete:
| Status | `status` field | Meaning |
|---|---|---|
| `201` | `accepted` | Lagret. `observationId` er den nye observation. |
| `202` | `accepted` (`state: "retrying"`) | Accepteret, men lagring fejlede. Serveren gentager den, også efter en genstart. |
| `200` | `duplicate` | Dette `eventId` var allerede accepteret. `observationId` er den eksisterende observation; intet nyt lagres. |
| `400` / `422` | `rejected` | Ugyldig payload, eller lagring fejlede permanent (eventet bevares som en dead letter). |
| `503` | `rejected` (`retryable: true`) | Inbox'en er fuld (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks spooler eventet og sender det senere. |
Mislykkede events gentages hvert `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 sek.) med fordoblende backoff, op til `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Events, der stadig fejler, forbliver i inbox'en som dead letters, listes på `/agentmemory/status` og viewerens Health-side, og kan gentages med `POST /agentmemory/capture/retry` (`{"eventId": "..."}` eller `{"all": true}`). Accepterede event-id'er huskes i `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 timer, højst `AGENTMEMORY_CAPTURE_EVENTS_MAX` id'er), så en hook, der afspilles igen efter en timeout eller en genstart, lagres én gang, mens to separate tool-kald med deres egne host-id'er lagres to gange, selv når deres indhold er identisk. Når en observation slettes (forget, sessionssletning, eviction, auto-forget eller en import, der udskifter lageret), markeres dens event som slettet, før observationen fjernes, så en afspilning af det event inden for samme vindue besvares som en duplikat og lagrer intet. State-store'en skriver til disk hvert 2. sekund, så et besvaret event stadig kan være kun i hukommelsen et øjeblik. For at dække det bærer hvert `2xx`-svar også serverens `bootId` (ny ved hver opstart), `acceptedAt` og `durableAfterMs` (save-intervallet plus 1.5 s på fillagret, 1.5 s på redis, hvor persistens er operatørens indstilling). Hooks holder eventet i den lokale spool, indtil dette vindue er gået, og sletter det ved et senere kald uden endnu en forespørgsel. Hvis `bootId` er ændret til da, genstartede serveren, så hooken sender eventet igen med samme `eventId`; et event, der nåede disken, lagres ikke to gange. Serveren sender også selv sådanne events ved opstart og ved hvert retry-interval, så en genstart taber intet, selv når ingen hook kører bagefter. Ældre hooks ignorerer de ekstra felter, og nye hooks mod en ældre server kasserer eventet ved `2xx` som før.
Når serveren er nede, ikke svarer i tide, eller returnerer en 5xx, tilføjer hooken observationen til en lokal spool-fil, `/capture-spool/-.jsonl` (overskriv mappen med `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Filen er privat for din bruger (rettighed 600), secrets redigeres (redacted) på samme måde som serveren redigerer dem, den holder højst `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) og smider indgange ud, der er ældre end `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Når den er fuld, smides nye indgange ud og tælles, og `/agentmemory/status` rapporterer det. Hooken afslutter stadig med 0 inden for sin tidsgrænse og tilføjer ingen forespørgsel, når serveren er sund. Spool'en sendes ved næste opstart og af den første hook, der når serveren igen, i en baggrundsproces, så agenten ikke venter. Event-id'er gør dette sikkert: en observation, der nåede frem før en timeout, lagres ikke to gange. `npx @agentmemory/agentmemory capture` viser spool'en og server-inbox'en, `--drain` sender spool'en nu, og `GET /agentmemory/capture` returnerer det samme som JSON. Sæt `AGENTMEMORY_CAPTURE_SPOOL=false` for at slå spool'en fra.
**Komprimering af graf-herkomst.** Hver videngraf-node og -kant bevarer id'erne for de nyeste 32 observationer, den stammer fra. Lagre skrevet før det loft kan holde tusindvis af id'er pr. hot node, hvilket gør graf-søgning og viewer langsom eller fælder workeren. agentmemory fixer dette selv: ved den første opstart efter en opgradering beskærer den hver node, kant, overskrevet kant (den temporale graf-historik) og det cachede snapshot til loftet i baggrunden, i små skiver med en pause imellem, så søgning, capture og viewer fortsætter med at fungere. Den gemmer sin fremdrift, genoptager efter en genstart, og kører aldrig igen, når den er færdig. `/agentmemory/status` og viewerens Health-side viser den som pending, running (med det aktuelle scope og position), done eller failed. Sæt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` for at slå den fra.
For at køre den manuelt, kald `POST /agentmemory/graph/compact`. Den gennemgår navne- og edge-key-indekserne i stedet for at liste hver node og kant, og er sikker at køre igen. Når den beskærer id'er, skriver den en `graph_compact`-audit-indgang.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
```
På et stort lager, eller når kaldet returnerer 504, så kør den i skiver. Send `scope` (`nodes`, `edges` eller `history`), `offset` og `limit`, og kald derefter igen med den returnerede `nextOffset`, indtil den er `null`. Gør dette for `nodes`, `edges` og `history`, og afslut med ét `{"scope":"snapshot"}`-kald, fordi en skive-kørsel ikke rører det cachede snapshot.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 2,500+ tests
npm run test:integration # API tests (requires running services)
```
**Forudsætninger:** Node.js >= 20 med npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 eller Docker. Den automatiske engine-installation på macOS/Linux kræver også `curl`, en POSIX `sh` og `tar`; native Windows bruger den manuelt fastlåste `iii.exe`, WSL2 eller Docker Desktop.
