Din kodningsagent minns allt. Inget mer återförklarande.
Byggt på iii engine
Beständigt minne för Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode och alla MCP-klienter.
---
## Installation
Krav:
- Node.js 20 eller nyare med npm och npx (`node -v`, `npm -v` och `npx -v`).
- Automatisk installation av iii-engine på macOS/Linux kräver också `curl`, ett POSIX-`sh` och `tar`. Minimala avbildningar som `node:20-slim` kan sakna dem.
- Native Windows kräver att den fastlåsta iii-engine v0.22.1 `iii.exe` installeras manuellt. WSL2 eller Docker Desktop är de andra vägarna som stöds.
Det kanoniska kommandot för en ny installation:
```bash
npx -y @agentmemory/agentmemory@latest
```
Den första körningen är en interaktiv konfiguration: du väljer vilka agenter som ska kopplas in (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), väljer en LLM-leverantör eller kör nyckelfritt, och den sår konfigurationen, startar minnesservern och dess fastlåsta iii-engine, samt erbjuder sig att installera globalt så att det bara kommandot `agentmemory` fungerar överallt därefter. `-y` accepterar npx:s paketfråga och `@latest` undviker en inaktuell cachad version. En leverantör gör LLM-funktioner tillgängliga, men LLM-skriven observationskomprimering startar bara när `AGENTMEMORY_AUTO_COMPRESS=true` också är satt.
Nyckelfritt läge inaktiverar vektor-embeddings. `memory_recall` (vägen `mem::search`) använder BM25, medan `memory_smart_search` också kan sammanfoga strukturella grafmatchningar när grafdata redan finns. För kostnadsfri semantisk återkallning på enheten, sätt `EMBEDDING_PROVIDER=local` i `~/.agentmemory/.env` och starta om. Den första embedding-förfrågan laddar ner `Xenova/all-MiniLM-L6-v2`; efter den initiala modellnedladdningen körs inferensen lokalt.
Den lokala körtiden använder fyra portar: `3111` för REST/MCP HTTP, `3112` för iii-strömmar, `3113` för viewern och `49134` för iii-workerns WebSocket. Beständigt iii-state ligger i `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, och `%APPDATA%\agentmemory` på Windows. Använd `--data-dir ` eller `AGENTMEMORY_DATA_DIR` för att åsidosätta detta, och återanvänd samma värde vid varje omstart. Av bakåtkompatibilitetsskäl prioriteras en befintlig `./data/state_store.db` eller `./data/iii-config.yaml` framför plattformens standard för instans 0; en explicit flagga eller miljövariabel vinner fortfarande.
Bevisa sedan att återkallning fungerar och ge din agent dess 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
```
Nyckelordssökningarna bör träffa i standardläget utan nyckel via BM25. Demots fråga `database performance optimization` är avsiktligt semantisk och kan ge noll resultat förrän en embedding-leverantör har konfigurerats.
Föredrar du att låta en kodningsagent sköta hela installationen? Ge den en enda instruktion:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
Koppla in fler agenter när du vill med `agentmemory connect ` — 20 adaptrar listade under [Fungerar med alla agenter](#works-with-every-agent). Fullständig kommandoreferens finns under [Snabbstart](#quick-start).
Windows
Den snabbaste vägen är WSL2. Native Windows-motorinstallation kräver att den fastlåsta v0.22.1-ZIP-filen laddas ner och att `iii.exe` extraheras manuellt; CLI:n extraherar inte automatiskt. Docker Desktop stöds också. Se [Windows-anteckningarna](#windows) för steg-för-steg-instruktioner.
Global installation / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
npx-kommandot ovan är fortfarande den kanoniska vägen för en ny installation och undviker behörighetsproblem med den globala prefix-katalogen.
npx levererar en gammal version
npx cachar per version. Tvinga fram den senaste med `npx -y @agentmemory/agentmemory@latest`, eller rensa cachen en gång med `rm -rf ~/.npm/_npx` (macOS/Linux; på Windows, radera `%LOCALAPPDATA%\npm-cache\_npx`).
Kör redan din egen iii-engine
agentmemory fastlåser iii-engine v0.22.1 och kopplar inte in sig på en annan version (workern kan inte tala en annan engines protokoll). Stoppa den andra enginen och köra sedan `npx -y @agentmemory/agentmemory@latest`. Den installerar och kör den fastlåsta v0.22.1 i `~/.agentmemory/bin`, utan att röra din egen `iii`.
---
agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. Alla agenter delar samma minnesserver.
Claude Code inbyggd plugin + 12 hooks + MCP
Codex CLI inbyggd plugin + 6 hooks + MCP
GitHub Copilot CLI MCP + plugin-hooks/skills
Cursor inbyggd plugin + 7 hooks + MCP
OpenCode insamlingsplugin + MCP
Devin 6 hooks + skills + MCP
OpenClaw inbyggd plugin + MCP
Hermes inbyggd plugin + MCP
pi inbyggd plugin + MCP
OpenHuman inbyggd 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
Fungerar med alla agenter som talar MCP eller HTTP. En server, minnen delade mellan dem alla.
---
Du förklarar samma arkitektur varje session. Du upptäcker samma buggar på nytt. Du lär agenten samma preferenser på nytt. Inbyggt minne (CLAUDE.md, .cursorrules) toppar ut vid 200 rader och blir inaktuellt. agentmemory löser detta. Det fångar tyst vad din agent gör, komprimerar det till sökbart minne och injicerar rätt kontext när nästa session startar. Ett kommando. Fungerar mellan agenter.
**Vad som förändras:** I session 1 sätter du upp JWT-autentisering. I session 2 ber du om rate limiting. Agenten vet redan att din autentisering använder jose-middleware i `src/middleware/auth.ts`, att dina tester täcker tokenvalidering, och att du valde jose framför jsonwebtoken för Edge-kompatibilitet — utan återförklaring och utan att klistra in kod på nytt.
```bash
npx -y @agentmemory/agentmemory@latest
```
Som standard lagrar agentmemory iii-engine-state utanför det repo du startar den från: `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, och `%APPDATA%\agentmemory` på Windows. En befintlig äldre `./data/state_store.db` eller `./data/iii-config.yaml` återanvänds för instans 0 före den plattformsstandarden. För att välja en plats explicit, ange `--data-dir ` eller sätt `AGENTMEMORY_DATA_DIR`; båda explicita inställningarna har företräde framför den äldre upptäckten:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
Native och Docker-baserade starter använder samma upplösta värdkatalog; Docker bind-monterar den på `/data`. `--instance 1` lägger till `instance-1` i den upplösta katalogen och väljer den separata standardportkvartetten `3211/3212/3213/49234`.
Senaste versionsanteckningarna: [CHANGELOG.md](../CHANGELOG.md).
---
### Hämtningsnoggrannhet
**coding-agent-life-v1** (internt korpus, reproducerbart i sandbox)
| Adapter | P@5 | R@5 | Topp-5-träffrate | p50-latens |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep-baslinje | 0.227 | 0.967 | 15 / 15 | 0 ms |
100% topp-5-träffrate vid **P@5-mattaket** för detta korpus (0.240, se scorecard). Hybrid hämtar varje gold-session; grep missar 1 av 2 gold på den flersessions-temporala frågan. Lyftet ligger i **recall + temporal**, inte i aggregerad precision. Detta benchmark är litet och gold-glest; det större LongMemEval-S nedan differentierar bättre. Fullständig uppdelning per typ + rättelsenotis: [`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 frågor)
| System | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| Endast BM25-fallback | 86.2% | 94.6% | 71.5% |
> Embedding-modell: `all-MiniLM-L6-v2` (lokal, kostnadsfri, inget API-nyckel krävs). Fullständiga rapporter: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Konkurrentjämförelse: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) som täcker agentmemory mot mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
**Reproducera lokalt:** [`eval/README.md`](../eval/README.md), en adapter-pluggbar testrigg för LongMemEval `_s` (publikt 500-frågors) + `coding-agent-life-v1` (internt 15-sessionskorpus). Grep-, vektor- och agentmemory-adaptrar poängsätts sida vid sida, NDJSON-utdata, publicerade scorecards hamnar i [`docs/benchmarks/`](../docs/benchmarks/).
**Fungerar bra ihop med [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) och [Graphify](https://github.com/safishamsi/graphify).** Kodgraf-indexering, multiagent-byggpipelines och bredare kunskapsgrafer över dokument/PDF-filer/bilder/videor. agentmemory minns arbetet; dessa tre projekt lyser upp resten av kontextlagret. Recept + frågerouting-tabell: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
agentmemory
mem0 (63K ⭐)
Letta / MemGPT (24K ⭐)
Khoj (36K ⭐)
supermemory (29K ⭐)
TencentDB Agent Memory (22K ⭐)
MemPalace (54K ⭐)
oracleagentmemory
Hippo
Inbyggt (CLAUDE.md)
Typ
Minnesmotor + MCP-server
Minneslager-API
Fullständig agent-körtid
Personlig AI
Minnes-API + app
Teamminnesnav (LLM-proxy)
Vektorminne (OSS)
Minnesmotor (Oracle DB)
Minnessystem
Statisk fil
Hämtning R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
N/A
Självrapporterat
PersonaMem 76% (självrapporterat)
~96.6% (självrapporterat)
94.4% (självrapporterat)
N/A
N/A (grep)
Automatisk infångning
12 hooks (noll manuellt arbete)
Manuella add()-anrop
Agenten redigerar sig själv
Manuellt
Extraktion på API-sidan
Proxy-avlyssning (byte av bas-URL)
Manuellt
API-extraktion
Manuellt
Manuell redigering
Sökning
BM25 + vektor + graf (RRF-fusion)
Vektor + graf
Vektor (arkiverat)
Semantisk
Vektor + RAG
4 typer av tillgångar (Chat / Skill / Wiki / CodeGraph)
Benchmark-notis: det är bara agentmemorys R@5 som är vårt eget uppmätta resultat (LongMemEval-S, reproducerbart från benchmark/COMPARISON.md). Siffrorna för mem0 och Letta är deras publicerade LoCoMo-siffror (ett annat dataset); siffrorna för MemPalace, supermemory, TencentDB (PersonaMem) och oracleagentmemory är leverantörens egna rapporterade påståenden som vi inte har reproducerat oberoende (oracleagentmemorys körning använde GPT-5.5 mot en Oracle AI Database). Visas sida vid sida enbart som fingervisning, inte en head-to-head på identisk data. Stjärnantal är ungefärliga och förändras över tid.
**Nyare aktörer** värda att känna till, jämförda på djupet i [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| System | ⭐ | Inriktning |
|--------|---|-------|
| Zep / Graphiti | 30K | Temporal kunskapsgraf; starkast publicerade resultat för temporala frågor (LongMemEval 63.8%), men grafen byggs asynkront så färska fakta kan ligga efter |
| Cognee | 30K | Dokument-till-kunskapsgraf-inmatning, endast Python, byggt för strukturerad entitetsextraktion snarare än sessionsinfångning |
Ingen av dessa fångar automatiskt in data från kodningsagent-hooks, levererar en local-first viewer eller körs nyckelfritt — kombinationen agentmemory är byggt kring.
---
Kompatibilitet: den här utgåvan riktar sig mot `iii-sdk` 0.22.1 och fastlåser iii-engine v0.22.1.
### Prova 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` sår 3 realistiska sessioner (JWT-autentisering, fix av N+1-fråga, rate limiting) och kör sökningar mot dem. Nyckelfria installationer inaktiverar vektorer, så nyckelordsfrågorna via `mem::search` bör träffa via BM25 medan `database performance optimization` kan ge noll resultat. `smart-search` kan dessutom returnera strukturella grafmatchningar när grafdata finns. För att få den semantiska frågan att hitta N+1-fixen via vektorer, sätt `EMBEDDING_PROVIDER=local`, starta om, och låt den första modellnedladdningen slutföras.
Öppna `http://localhost:3113` för att se minnet byggas upp i realtid.
### Validera en ny installation och omstarts-persistens
Med servern igång, validera REST, hälsostatus, viewern och den iii-baserade körtidsstatusen:
```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
```
Startpanelen för redo-status tar hänsyn till alla fyra portar: REST/MCP HTTP på 3111, iii-strömmar på 3112, viewern på 3113 och iii-workerns WebSocket på 49134. `status` bekräftar agentmemorys hälsa och det aktiva leverantörs-/embedding-läget. Spara en testpunkt och bekräfta att den är sökbar:
```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 sedan `npx -y @agentmemory/agentmemory@latest stop`, starta det kanoniska kommandot igen i Terminal 1, vänta på `/agentmemory/livez`, och upprepa sökningen. Testpunkten måste fortfarande returneras. Om du valde en anpassad `--data-dir`, ange samma katalog vid omstarten.
### Vardagskommandon
Installation och konfiguration finns under [Installation](#install) ovan (den första körningen guidar dig genom det). Till vardags:
```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
```
### Sessionsuppspelning
Varje session som agentmemory registrerar kan spelas upp igen. Öppna viewern, välj fliken **Replay**, och skrubba genom tidslinjen: prompter, verktygsanrop, verktygsresultat och svar renderas som diskreta händelser med play/pause, hastighetskontroll (0.5x till 4x) och kortkommandon (mellanslag för att växla, piltangenterna för att stega).
För att importera äldre Claude Code JSONL-transkript:
```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
```
Importerade sessioner dyker upp i Replay-väljaren tillsammans med de ursprungliga. Under huven dirigeras varje post genom iii-funktionerna `mem::replay::load`, `mem::replay::sessions` och `mem::replay::import-jsonl`, utan några sidokanalsservrar. Varje importerat transkript indexeras för sökning, märks med ursprungskanalen `import`, och analyseras för en sessionskristall och lärdomar.
> **Observera om du förlitar dig på `import-jsonl` som din primära infångningsväg:** Claude Codes `cleanupPeriodDays` (i `~/.claude/settings.json`, standard **30**) tar automatiskt bort JSONL-transkript äldre än det fönstret från `~/.claude/projects/`. Om du installerar agentmemory på en månader-gammal Claude Code-historik är allt äldre än 30 dagar redan borta innan den första importen. Antingen kör du `import-jsonl` på en cron, höjer `cleanupPeriodDays` till något högre, eller kopplar in auto-infångnings-hookarna (standardvägen vid plugin-installation) så att varje tur hamnar i agentmemory medan sessionen är live och JSONL-rensningen slutar spela någon roll.
### Uppgradering / underhåll
Använd underhållskommandot när du avsiktligt vill uppdatera din lokala körtid:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
Varning: det här kommandot ändrar den aktuella arbetsytan/körtiden. Det kan uppdatera JavaScript-beroenden och hämta den fastlåsta Docker-avbildningen `iiidev/iii:0.22.1`. Det installerar aldrig en ofastlåst eller nyare iii-engine.
Implementationsdetaljer finns i `src/cli.ts` (se `runUpgrade` runt området `src/cli.ts:544-595`).
### Claude Code (ett block, klistra in det)
```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 utan plugin-installationen (fristående MCP-väg)
Om du kopplar in agentmemorys MCP-server via `~/.claude.json` direkt istället för att använda `/plugin install`, löser Claude Code aldrig upp `${CLAUDE_PLUGIN_ROOT}`, och du måste peka hook-skripten mot absoluta sökvägar i `~/.claude/settings.json`. Dessa sökvägar innehåller vanligtvis agentmemory-versionen (t.ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), så nästa uppgradering bryter varje hook i det tysta.
Lösning:
```bash
agentmemory connect claude-code --with-hooks
```
Detta slår samman samma hook-kommandon i `~/.claude/settings.json` med absoluta sökvägar som löses upp till den medföljande `plugin/`-katalogen i det för tillfället installerade paketet `@agentmemory/agentmemory`. Kör kommandot igen efter att du har uppgraderat agentmemory för att uppdatera sökvägarna. Användarens egna poster i samma fil bevaras; endast tidigare agentmemory-poster ersätts. Att använda vägen `/plugin install` är fortfarande den rekommenderade metoden.
För fjärr- eller skyddade driftsättningar, starta Claude Code med `AGENTMEMORY_URL` och `AGENTMEMORY_SECRET` satta. Plugin-programmet skickar båda värdena vidare till sin medföljande MCP-server; när `AGENTMEMORY_URL` är tomt använder MCP-shimmen `http://localhost:3111`.
### Codex CLI (Codex-plugin-plattformen)
```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 levereras från samma `plugin/`-katalog som Claude Code-pluginet. Det registrerar:
- En medföljande stdio MCP-brygga till den körande daemonen, utan npm-nedladdning eller fallback-lager. Se [lokala Codex-guiden](../docs/plugins/codex-local.md) för att testa en build som ännu inte är publicerad.
- 6 livscykel-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 anropsbara skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 referens-skills som agenten laddar vid behov (minnesdisciplin, MCP-verktyg, REST API, konfiguration, agenter, hooks, arkitektur och guiden för att skriva skills)
Codex hook-motor injicerar `CLAUDE_PLUGIN_ROOT` i hook-underprocesser (enligt [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), så samma hook-skript fungerar på båda värdarna utan duplicering. Händelserna Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure är specifika för Claude Code och registreras inte för Codex.
#### Codex hooks: tillit och kompatibilitet
Native plugin-hook-utlösning är verifierad med Codex CLI 0.150.1. Lita på plugin-hooksen innan du förväntar dig infångning. Desktop-beteendet beror på dess medföljande körtid; kontrollera `/hooks` och bekräfta en infångad händelse innan du aktiverar en lösning.
Om din värd kräver globala hooks, spegla kommandona till `~/.codex/hooks.json`. När MCP redan är inkopplat behöver den nuvarande adaptern `--force` för att nå hook-installationen:
```bash
agentmemory connect codex --with-hooks --force
```
Detta slår samman globala hooks och skriver om agentmemory-MCP-posten, och bevarar orelaterade poster. Granska eventuella anpassade agentmemory-endpoint-inställningar innan du använder `--force`. Kör om efter uppgradering för att uppdatera skriptsökvägarna. Aktivera antingen native plugin-hooks eller globala kopior för att undvika dubblerad infångning.
### GitHub Copilot CLI
För VS Code agent-läge, använd [Copilot MCP- och automatisk-infångningsguiden](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-adaptern konfigurerar inte 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` slår samman `mcpServers.agentmemory` i `~/.copilot/mcp-config.json` (eller `$COPILOT_HOME/mcp-config.json` när `COPILOT_HOME` är satt) och bevarar befintliga servrar. På native Windows är detta den enda automatiserade `connect`-adaptern; konfigurera varje annan native Windows-agent manuellt. WSL-`connect` stöds bara när målagenten är installerad i samma WSL-miljö. Copilot plockar upp MCP-servern vid nästa start eller efter `/mcp`. Installera även pluginet när du vill ha den fullständiga hook-/skill-upplevelsen.
OpenClaw (klistra in denna 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`.
```
Fullständig guide: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (klistra in denna 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.
```
Fullständig guide: [`integrations/hermes/`](../integrations/hermes/)
### Andra agenter
Starta minnesservern: `npx -y @agentmemory/agentmemory@latest`
#### Inbyggda skills via `npx skills add` (50+ agenter)
agentmemory levereras med 17 skills i Claude-Code-stilens `/SKILL.md`-format: 9 anropsbara handlings-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) och 8 referens-skills som agenten laddar vid behov (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referens-skillsen innehåller datatabeller genererade från källkoden, så de avviker aldrig. CLI-verktyget [`skills`](https://npmjs.com/package/skills) från vercel-labs installerar dem automatiskt i den anropande agentens inbyggda skill-katalog över 50+ agenter (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf och fler):
```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
```
Detta är ett **komplement** till `agentmemory connect `:
- `agentmemory connect ` skriver MCP-serverkonfigurationen så att verktygen blir tillgängliga.
- `npx skills add rohitg00/agentmemory` installerar skillsen så att agenten vet när den ska anropa dem.
För de få agenter som skills-CLI:n ännu inte täcker (Zed v1.3.x och lägre), lägg själv de 17 SKILL.md-filerna i agentens inbyggda skill-katalog; samma format fungerar överallt.
#### Standard-MCP-block
agentmemory-posten är **samma MCP-serverblock** på alla värdar som använder `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}"
}
}
```
**Slå samman denna post med det befintliga `mcpServers`-objektet** i värdens konfigurationsfil; ersätt inte filen. Om filen redan har andra servrar, lägg till `agentmemory` bredvid dem som en ytterligare nyckel inuti `mcpServers`. Om `mcpServers` helt saknas, klistra in blocket inuti `{ "mcpServers": { ... } }`. `${VAR}`-platshållarna ärver `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` från skalet vid MCP-serverns start; ej satta variabler skickar tomma strängar och shimmen faller tillbaka till `http://localhost:3111`. En inkopplad post täcker både lokala och fjärran (k8s / reverse-proxyade) driftsättningar.
| Agent | Konfigurationsfil | Anteckningar |
|---|---|---|
| **Cursor (endast MCP)** | `~/.cursor/mcp.json` | Slå samman i `mcpServers`, eller `agentmemory connect cursor`. En deeplink med ett klick finns också på webbplatsen. |
| **Cursor (fullständigt plugin)** | `.cursor-plugin/` | Cursor Marketplace-listning (inlämning under granskning) eller Cursor Settings → Plugins → lokal checkout. Registrerar 7 auto-infångnings-hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + MCP-servern, med `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` hanterade i Cursors plugin-panel. Fungerar i Cursor IDE och `cursor-agent`-CLI:n; CLI-utskriftslägets prompter fylls i efterhand från sessionstranskriptet vid sessionens slut. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Slå samman i `mcpServers`. Starta om Claude Desktop efter redigering. |
| **Cline / Roo Code / Kilo Code** | Clines MCP-inställningar (Settings UI → MCP Servers → Edit) | Samma `mcpServers`-block. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` slår samman MCP-posten; `--with-hooks` lägger till sex inbyggda auto-infångnings-hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) med Devins gemener i verktygsmatcharna. Verifiera med `devin mcp list` och `/hooks` inuti devin. |
| **Devin CLI (fullständigt plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` från en checkout registrerar alla 17 skills som `/agentmemory:`-snabbkommandon plus MCP-servern. Devins plugin-hooks kan inte utlösa `SessionStart`/`SessionEnd`, så kombinera med `connect devin --with-hooks` för fullständig sessionsinfångning. |
| **Devin (moln)** | Settings → Connections → MCP servers | Lägg till en anpassad MCP (STDIO): kommando `npx`, argument `-y @agentmemory/mcp@latest`, miljövariabeln `AGENTMEMORY_URL` som pekar på en nätverksåtkomlig agentmemory-driftsättning plus `AGENTMEMORY_SECRET` (molnsessioner kan inte nå localhost — se [`deploy/`](../deploy/)). Spara hemligheten i Devin Secrets, och använd sedan "Test listing tools" för att bekräfta att alla 54 verktyg visas. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (slås samman automatiskt). |
| **GitHub Copilot CLI (endast MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` slår samman `mcpServers.agentmemory`; Copilot plockar upp det vid nästa start eller via `/mcp`. |
| **GitHub Copilot CLI (fullständigt plugin)** | Copilot plugin-installation | `copilot plugin install rohitg00/agentmemory:plugin` för pluginet från GitHub-underkatalogen. |
| **OpenClaw** | OpenClaw MCP-konfiguration | Samma `mcpServers`-block. Djupare integration: `openclaw plugins install ./integrations/openclaw` tar över OpenClaws minnesplats (byter automatiskt från `memory-core`); sätt `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, annars blockeras tur-infångningen i det tysta. Se [`integrations/openclaw`](../integrations/openclaw/). |
| **Codex CLI (endast MCP)** | `.codex/config.toml` | TOML-form: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, eller lägg till `[mcp_servers.agentmemory]` manuellt. |
| **Codex CLI (fullständigt plugin)** | Codex plugin-marketplace | `codex plugin marketplace add rohitg00/agentmemory` och sedan `codex plugin add agentmemory@agentmemory`. Registrerar MCP + 6 livscykel-hooks + 17 skills. Lita på hooksen och verifiera infångningen i din värd; se [Codex-konfiguration och validering](../docs/plugins/codex-local.md). |
| **OpenCode (endast MCP)** | `opencode.json` | Annan form: en toppnivånyckel `mcp`, kommando som array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (fullständigt plugin)** | `plugin/opencode/` | 22 auto-infångnings-hooks som täcker sessionslivscykel, meddelanden, verktyg, fel. Projekttillhörighet är per session, så en OpenCode-process som spänner över flera repon registrerar varje session under sitt eget projekt. Två snabbkommandon (`/recall`, `/remember`). Kopiera `plugin/opencode/` till din OpenCode-arbetsyta och lägg till plugin-posten i `opencode.json`. Se [`plugin/opencode/README.md`](../plugin/opencode/README.md) för den fullständiga hook-tabellen + luckanalysen. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installerar det medföljande tillägget i pi:s katalog för automatisk upptäckt (recall vid agentstart, infångning vid agentslut, verktygen `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` i en körande pi plockar upp det. [`integrations/pi`](../integrations/pi/) är även ett pi-paket (`pi install ./integrations/pi` från en checkout). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ger minnesleverantören med 6 hooks (förhämtning, turinfångning, sessionsslut, förkomprimering, MEMORY.md-spegling, systemprompt-block). Validera med `hermes plugins doctor` och `hermes memory status`. Se [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` skriver det vanliga `mcpServers`-blocket. Hook-nyttolasten är fältkompatibel med Claude Code, så de befintliga 12-hooks-skripten fungerar utan ändring; koppla in dem via `hooks`-avsnittet i samma `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installerar MCP och infångnings-hooks i den delade anpassningskatalogen. Se [Antigravity-konfiguration och begränsningar](../docs/plugins/antigravity.md). |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` använder samma MCP- och hook-konfiguration som nuvarande IDE-versioner. Befintliga installationer bör uppdateras med `--force`; se [uppgraderingsanteckningarna](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` skriver konfigurationen på användarnivå. Arbetsyteöverskrivningar läggs i `.kiro/settings/mcp.json` bredvid din kod. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` skriver det vanliga `mcpServers`-blocket. Warp upptäcker också automatiskt skills från `.claude/skills/`; när Claude Code-pluginet är installerat visas agentmemorys 8 skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) naturligt i Warps snabbkommando-palett. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` skriver det vanliga `mcpServers`-blocket. VS Code-tilläggsanvändare: klistra in samma block via Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (att föredra) eller `config.json` (äldre) | `agentmemory connect continue` skapar `config.yaml` från grunden när ingen av dem finns, eller ändrar befintlig `config.json`. **Om du redan har `config.yaml`** skriver adaptern ut exakt det block som ska klistras in under `mcpServers:`; den skriver inte om din yaml i det tysta, eftersom att bevara kommentarer och ankare på ett säkert sätt kräver en YAML-parser som paketet inte levererar. Continue använder array-form (inte objekt) för `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` skriver under `context_servers` (Zeds nyckel, INTE `mcpServers`). Fjärranslutna MCP-servrar kan istället kopplas in via `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` skriver det vanliga `mcpServers`-blocket. Projektbegränsade överskrivningar läggs i `/.factory/mcp.json`. Ange `--with-hooks` för inbyggd auto-infångning. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` lägger till en rad `@deepseek-ai/dsh-mcp-client` i patch-lagret på hemkatalognivå som varje Harness-profil laddar; verktyg registreras som `mcp__agentmemory__*`. Ange `--with-hooks` för att även koppla in auto-infångning: de medföljande Claude Code-hook-skripten körs genom Harness förstapartsbrygga `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via ett manifest skrivet till `$DSH_HOME/agentmemory.hooks.json`. Standardvärdet är `~/.dsh` när `DSH_HOME` inte är satt. |
| **Goose** | Goose MCP-inställningsgränssnitt | Samma `mcpServers`-block; använd `goose configure` → Add Extension → MCP. Direkt YAML-redigering i `~/.config/goose/config.yaml` stöds, men schemat använder `extensions:` + `cmd` (inte `mcpServers:` + `command`). |
| **Aider** | n/a | Kommunicera direkt med REST API:et: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **Alla agenter (32+)** | n/a | `npx skillkit install agentmemory` upptäcker värden automatiskt och slår samman. |
**Sandboxade MCP-klienter** (Flatpak / Snap / restriktiva containrar) som inte kan nå värdens `localhost`: sätt även `"AGENTMEMORY_FORCE_PROXY": "1"` i `env`-blocket, och peka `AGENTMEMORY_URL` mot en väg som sandboxen faktiskt kan nå (t.ex. din LAN-IP).
### Programmatisk åtkomst (Python / Rust / Node)
agentmemory registrerar sina kärnoperationer som iii-funktioner (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Alla språk med en iii SDK kan anropa dem direkt över `ws://localhost:49134`, utan behov av en separat REST-klient per språk.
```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"},
})
```
Genomarbetat exempel: [`examples/python/`](../examples/python/) (snabbstart + flöde för observation/recall). REST på `:3111` finns fortfarande tillgängligt för värdar utan en iii-körtid.
### Från källkod
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
Detta startar agentmemory med en lokal `iii-engine` om den fastlåsta binären redan är installerad, eller använder Docker Compose när det valts. REST, strömmar och viewern binder till `127.0.0.1` som standard. Den automatiska binärvägen för macOS/Linux kräver `curl`, ett POSIX-`sh` och `tar`.
Installera `iii-engine` manuellt. **agentmemory fastlåser för närvarande `iii-engine` till `v0.22.1`**, samma utgåva som dess `iii-sdk`-beroende; workern talar den enginens trådprotokoll, och 0.20.0 omorganiserade SDK-ytan, så de två rör sig tillsammans i agentmemorys utgåvor. Åsidosätt med `AGENTMEMORY_III_VERSION=` om du kör din egen engine och vet att den matchar.
- **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:** byt ut `aarch64-apple-darwin` mot `x86_64-apple-darwin`
- **Linux x64:** byt ut mot `x86_64-unknown-linux-gnu`
- **Linux arm64:** byt ut mot `aarch64-unknown-linux-gnu`
- **Windows:** ladda ner `iii-x86_64-pc-windows-msvc.zip` från [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) och extrahera `iii.exe` till `%USERPROFILE%\.agentmemory\bin\iii.exe`
Varje arkiv har en matchande `.sha256`-fil på utgåvesidan; när du byter plattform, använd den filens hash i kontrollen ovan (på Windows: `Get-FileHash`). Den automatiska installeraren i `npx @agentmemory/agentmemory` fastlåser dessa hashar och vägrar ett arkiv som inte matchar.
Eller använd Docker (den medföljande `docker-compose.yml` hämtar `iiidev/iii:0.22.1`). Fullständig dokumentation: [iii.dev/docs](https://iii.dev/docs).
### Windows
agentmemory körs på Windows 10/11, men Node.js-paketet ensamt räcker inte; du behöver också den fastlåsta iii-engine v0.22.1-körtiden som en bakgrundsprocess. CLI:n extraherar inte Windows-ZIP-filen automatiskt, så native Windows-användare måste installera `iii.exe` manuellt, använda WSL2, eller välja Docker Desktop.
Automatiserad MCP-inkoppling på native Windows stöder bara `agentmemory connect copilot-cli`. För Claude Code, Codex, Cursor och varje annan native Windows-agent, kopiera det manuella MCP-blocket från [Andra agenter](#other-agents) till den agentens Windows-konfiguration. Att köra `connect` i WSL är lämpligt bara när målagenten också är installerad i samma WSL-miljö; det redigerar inte konfigurationen för en agent som körs på Windows-värden.
**Alternativ A: förbyggd Windows-binär (rekommenderas)**
```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
```
**Alternativ 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
```
**Alternativ C: endast fristående MCP (ingen engine).** Om du bara behöver MCP-verktygen för din agent och inte behöver REST API, viewern eller cron-jobb, hoppa över enginen helt:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Diagnostik för Windows:** om `npx -y @agentmemory/agentmemory@latest` misslyckas, kör det igen med `--verbose` för att se enginens faktiska stderr. Vanliga felorsaker:
| Symptom | Åtgärd |
|---|---|
| `The engine process started but the REST API never responded.` | Bekräfta att alla fyra härledda portar är fria, verifiera att den fastlåsta `iii.exe` förblev igång, och kör sedan igen med `--verbose` och inspektera den infångade enginens stderr |
| `Could not start iii-engine` | Varken `iii.exe` eller Docker är installerat. Se alternativ A eller B ovan |
| Portkonflikt | `netstat -ano \| findstr :3111` för att se vad som är bundet, avsluta det sedan eller använd `--port ` |
| Docker-reservläge hoppas över trots att Docker är installerat | Se till att Docker Desktop faktiskt körs (ikonen i systemfältet) |
> Observera: iii-**enginen** är en förbyggd binär, inte en cargo crate, så försök inte `cargo install` den. (iii-**SDK:erna** publiceras på crates.io, npm och PyPI, men agentmemory behöver inte dem.) Alla engine-installationsmetoder som stöds är fastlåsta till v0.22.1: den förbyggda binären ovan, agentmemorys auto-installationsväg för macOS/Linux (`curl`, POSIX `sh` och `tar` krävs), och Docker-avbildningen `iiidev/iii:0.22.1`. Ett rått uppströms `install.sh | sh` installerar den senaste enginen, vilket agentmemory inte stöder. Använd `npx -y @agentmemory/agentmemory@latest`; på macOS/Linux hämtar det den fastlåsta enginen till `~/.agentmemory/bin`.
---
Driftsättning
Mallar med ett klick för hanterade värdar. Var och en levererar en självständig Dockerfile som hämtar `@agentmemory/agentmemory` från npm och kopierar in iii-engine-binären från den officiella Docker Hub-avbildningen `iiidev/iii`; ingen förbyggd agentmemory-avbildning krävs. Beständig lagring monteras på `/data`; vid första start skriver startpunkten över den npm-medföljande iii-konfigurationen (som binder till `127.0.0.1`) med en driftsättningsanpassad version som binder till `0.0.0.0` och använder absoluta `/data`-sökvägar, genererar HMAC-hemligheten, och sänker sedan rättigheterna från `root` till `node` via `gosu` innan agentmemory-CLI:n körs.
Renders driftsättningsknapp med ett klick kräver `render.yaml` i repots rot, vilket vi avsiktligt håller rent. Använd Render Blueprint-flödet som dokumenteras i [`deploy/render/`](.././deploy/render/README.md) för att manuellt peka på den repo-interna blueprinten.
Fullständiga installationsdetaljer (HMAC-infångning, SSH-tunnel för viewern, rotation, backup, kostnadsgolv) finns i [`deploy/`](.././deploy/README.md):
- [`deploy/fly`](.././deploy/fly/README.md): en enda maskin med
`auto_stop_machines = "stop"`; billigast vid inaktivitet.
- [`deploy/railway`](.././deploy/railway/README.md): fast avgift på
Hobby-planen, volym i dashboarden.
- [`deploy/render`](.././deploy/render/README.md): Blueprint-flöde,
automatiska disk-snapshots på betalplaner.
- [`deploy/coolify`](.././deploy/coolify/README.md): självhostat på din
egen VPS via [Coolify](https://coolify.io/self-hosted); samma Docker
Compose-stack, du äger värden och datan.
Endast port `3111` publiceras. Viewern på `3113` förblir bunden till
loopback inuti containern; varje malls README dokumenterar
SSH-tunnel-mönstret för att nå den.
---
Varje kodningsagent glömmer allt när sessionen tar slut, och varje ny session börjar med att du förklarar din tech-stack på nytt. agentmemory körs i bakgrunden och tar bort det steget.
```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.
```
### Jämfört med inbyggt agentminne
Varje AI-kodningsagent levereras med inbyggt minne: Claude Code har `MEMORY.md`, Cursor har notepads, Cline har memory bank. Dessa fungerar som post-it-lappar. agentmemory är den sökbara databasen bakom post-it-lapparna.
| | Inbyggt (CLAUDE.md) | agentmemory |
|---|---|---|
| Skala | Tak på 200 rader | Obegränsat |
| Sökning | Laddar allt in i kontexten | BM25 + vektor + graf (endast topp-K) |
| Tokenkostnad | 22K+ vid 240 observationer | ~1,900 tokens (92% mindre) |
| Mellan agenter | Filer per agent | MCP + REST (vilken agent som helst) |
| Koordinering | Ingen | Leaser, signaler, åtgärder, rutiner |
| Observerbarhet | Läs filer manuellt | Viewer i realtid på :3113 |
---
### Minnespipeline
```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-nivås minneskonsolidering
Modellerat efter hur mänskliga hjärnor bearbetar minne, inklusive sömnkonsolidering.
| Nivå | Vad | Analogi |
|------|------|---------|
| **Arbetsminne** | Råa observationer från verktygsanvändning | Korttidsminne |
| **Episodiskt** | Komprimerade sessionssammanfattningar | "Vad som hände" |
| **Semantiskt** | Extraherade fakta och mönster | "Vad jag vet" |
| **Procedurellt** | Arbetsflöden och beslutsmönster | "Hur man gör det" |
Minnen klingar av över tid (Ebbinghaus-kurvan). Ofta använda minnen förstärks. Inaktuella minnen rensas ut automatiskt. Motsägelser upptäcks och löses.
### Vad som fångas in
| Hook | Fångar in |
|------|----------|
| `SessionStart` | Projektsökväg, sessions-ID |
| `UserPromptSubmit` | Användarprompter (integritetsfiltrerade) |
| `PreToolUse` | Filåtkomstmönster + berikad kontext |
| `PostToolUse` | Verktygsnamn, indata, utdata |
| `PostToolUseFailure` | Felkontext |
| `PreCompact` | Återinjicerar minne före komprimering |
| `SubagentStart/Stop` | Underagentens livscykel |
| `Stop` | Sammanfattning vid sessionens slut |
| `SessionEnd` | Markering för avslutad session |
### Nyckelfunktioner
| Funktion | Beskrivning |
|---|---|
| **Automatisk infångning** | Varje verktygsanvändning registreras via hooks, inget manuellt arbete |
| **Semantisk sökning** | BM25 + vektor + kunskapsgraf med RRF-fusion |
| **Minnesutveckling** | Versionering, ersättning, relationsgrafer |
| **Återkallningshygien** | Ersatta minnesversioner lämnar sökindexen; versionskedjan i KV behåller fullständig historik |
| **Nästan-dubblett-tips** | Sparningar rapporterar en rådgivande `similarTo`-matchning när nytt innehåll nära liknar ett befintligt minne |
| **Scoping per agent** | `agentId` löper genom spara och återkalla över REST, MCP och sökindexet, i delat eller isolerat läge |
| **Ursprung vid skrivtillfället** | Varje observation och minne bär en oföränderlig ursprungskanal (user, agent, tool, import eller shared) stämplad vid infångning, sparning och import |
| **Automatisk glömning** | TTL-utgång, upptäckt av motsägelser, viktbaserad utrensning |
| **Integritet först** | API-nycklar, hemligheter, ``-taggar tas bort före lagring |
| **Självläkande** | Circuit breaker, reservkedja för leverantörer, hälsoövervakning |
| **Claude-brygga** | Dubbelriktad synkning med MEMORY.md |
| **Kunskapsgraf** | Entitetsextraktion + BFS-genomsökning |
| **Teamminne** | Namnrymdsindelat delat + privat mellan teammedlemmar |
| **Citeringsursprung** | Spåra vilket minne som helst tillbaka till källobservationerna |
| **Git-snapshots** | Versionera, återställa och diffa minnestillståndet |
---
Trippelströms-hämtning som kombinerar tre signaler:
| Ström | Vad den gör | När |
|---|---|---|
| **BM25** | Stam-baserad nyckelordsmatchning med synonymexpansion | Alltid aktiv |
| **Vektor** | Cosinuslikhet över täta embeddings | Embedding-leverantör konfigurerad |
| **Graf** | Genomsökning av kunskapsgrafen via entitetsmatchning | Entiteter upptäckta i frågan |
Sammanfogad med Reciprocal Rank Fusion (RRF, k=60) och sessionsdiversifierad (max 3 resultat per session).
När ett vektorindex är ifyllt använder `mem::search` (bakom `memory_recall`) den hybrida BM25 + vektor-rankaren. Utan embeddings används BM25. `smart-search` kan dessutom sammanfoga strukturella grafmatchningar när grafdata finns, även i nyckelfritt läge. Återkallning av lärdomar körs på ett dedikerat BM25-index i minnet istället för att skanna hela korpuset per fråga. Ersatta minnesversioner exkluderas från varje återkallningsväg; versionskedjan behåller deras historik.
Vektorer överlever en krasch eller en tvingad avstängning. Vektorindexet sparas i buckets högst var `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minuter). Varje vektor som läggs till eller tas bort däremellan skrivs också direkt till en liten väntande logg i state-lagret, och nästa start spelar upp den igen utan att anropa embedding-leverantören. Varje lyckad sparning tömmer loggen. Dokument som fortfarande saknar en vektor efter uppspelningen bäddas in igen i bakgrunden i omgångar om `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) tills inga återstår, och en backfill som stoppas fortsätter vid nästa start. `/agentmemory/status` och viewern visar storleken på den väntande loggen och backfill-tillståndet. Nyckelfria installationer skriver ingenting.
BM25 tokeniserar grekiska, kyrilliska, hebreiska, arabiska och accentuerad latin direkt ur lådan. För kinesiska/japanska/koreanska minnen, installera de valfria segmenterarna (`npm install @node-rs/jieba tiny-segmenter`) för att dela upp CJK-sekvenser i ordnivå-tokens; utan dem faller agentmemory mjukt tillbaka till tokenisering av hela sekvenser och skriver ut en engångstips på stderr.
### Embedding-leverantörer
Nyckelfria installationer inaktiverar vektor-embeddings: `mem::search` använder BM25, medan `smart-search` också kan använda befintlig strukturell grafdata. För att aktivera kostnadsfria semantiska embeddings på enheten, lägg till detta i `~/.agentmemory/.env` och starta om agentmemory:
```env
EMBEDDING_PROVIDER=local
```
Den vanliga npm-installationen inkluderar den valfria körtiden `@huggingface/transformers`. Den första embedding-förfrågan laddar ner `Xenova/all-MiniLM-L6-v2`, så den behöver nätverksåtkomst och kan ta längre tid; efterföljande inferens körs på enheten. Fjärrleverantörer upptäcks automatiskt utifrån sina nycklar om inte `EMBEDDING_PROVIDER` åsidosätter dem.
| Leverantör | Modell | Kostnad | Anteckningar |
|---|---|---|---|
| **Lokal (rekommenderat att aktivera)** | `all-MiniLM-L6-v2` | Kostnadsfri | På enheten efter den första modellnedladdningen, +8 procentenheter recall jämfört med endast BM25 |
| Gemini | `gemini-embedding-001` | Kostnadsfri nivå | 100+ språk, 768/1536/3072 dimensioner (MRL), 2048-token indata. Ersätter `text-embedding-004` ([utfasad, stängs ner 14 jan 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | Högst kvalitet |
| Voyage AI | `voyage-code-3` | Betald | Optimerad för kod |
| Cohere | `embed-english-v3.0` | Kostnadsfri provperiod | Generell användning |
| OpenRouter | Vilken modell som helst | Varierar | Multimodell-proxy |
---
54 verktyg, 6 resurser, 3 prompter och 17 skills.
> **MCP-shim kontra fullständig server:** det publicerade paketet `@agentmemory/mcp` är en tunn shim. Det exponerar hela ytan med 54 verktyg **bara när det kan nå en körande agentmemory-server** via `AGENTMEMORY_URL` (proxy-läge). Utan någon nåbar server faller shimmen tillbaka till en lokal uppsättning på 7 verktyg (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Miljövariabeln `AGENTMEMORY_TOOLS=core|all` är en flagga på *serversidan*; att sätta den i shimmens `env`-block har ingen effekt. Om du bara ser 7 verktyg i Cursor / OpenCode / Gemini CLI, starta `npx -y @agentmemory/agentmemory@latest` (eller Docker-stacken) och sätt `AGENTMEMORY_URL=http://localhost:3111`.
### 54 verktyg
Tre verktygsytor, från minst till störst: `AGENTMEMORY_TOOLS=core` begränsar synligheten till 8 väsentliga verktyg (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); grundmängden nedan är registrets 14 grundläggande verktyg; standarden (`AGENTMEMORY_TOOLS=all`) exponerar alla 54.
Grundverktyg (14)
| Verktyg | Beskrivning |
|------|-------------|
| `memory_recall` | Sök i tidigare observationer |
| `memory_compress_file` | Komprimera markdown-filer samtidigt som strukturen bevaras |
| `memory_save` | Spara en insikt, ett beslut eller ett mönster |
| `memory_file_history` | Tidigare observationer om specifika filer |
| `memory_patterns` | Upptäck återkommande mönster |
| `memory_sessions` | Lista senaste sessionerna |
| `memory_smart_search` | Hybrid semantisk + nyckelordssökning |
| `memory_vision_search` | Sök bland bildobservationer |
| `memory_timeline` | Kronologiska observationer |
| `memory_profile` | Projektprofil (koncept, filer, mönster) |
| `memory_export` | Exportera all minnesdata |
| `memory_relations` | Fråga relationsgrafen |
| `memory_commit_lookup` | Sessioner bakom en git-commit |
| `memory_commits` | Commits registrerade för en session |
Utökade verktyg (54 totalt, standardytan)
| Verktyg | Beskrivning |
|------|-------------|
| `memory_patterns` | Upptäck återkommande mönster |
| `memory_timeline` | Kronologiska observationer |
| `memory_relations` | Fråga relationsgrafen |
| `memory_graph_query` | Genomsökning av kunskapsgrafen |
| `memory_consolidate` | Kör 4-nivås konsolidering |
| `memory_claude_bridge_sync` | Synka med MEMORY.md |
| `memory_team_share` | Dela med teammedlemmar |
| `memory_team_feed` | Senaste delade objekt |
| `memory_audit` | Granskningsspår för operationer |
| `memory_governance_delete` | Radera med granskningsspår |
| `memory_snapshot_create` | Git-versionerad snapshot |
| `memory_action_create` | Skapa arbetsobjekt med beroenden |
| `memory_action_update` | Uppdatera åtgärdsstatus |
| `memory_frontier` | Oblockerade åtgärder rankade efter prioritet |
| `memory_next` | Den enskilt viktigaste nästa åtgärden |
| `memory_lease` | Exklusiva åtgärdsleaser (multiagent) |
| `memory_routine_run` | Instansiera arbetsflödesrutiner |
| `memory_signal_send` | Meddelanden mellan agenter |
| `memory_signal_read` | Läs meddelanden med kvitton |
| `memory_checkpoint` | Externa villkorsgrindar |
| `memory_mesh_sync` | P2P-synk mellan instanser |
| `memory_sentinel_create` | Händelsedrivna bevakare |
| `memory_sentinel_trigger` | Utlös bevakare externt |
| `memory_sketch_create` | Kortlivade åtgärdsgrafer |
| `memory_sketch_promote` | Befordra till permanent |
| `memory_crystallize` | Komprimera åtgärdskedjor |
| `memory_diagnose` | Hälsokontroller |
| `memory_heal` | Fixa fastnat tillstånd automatiskt |
| `memory_facet_tag` | Dimension:värde-taggar |
| `memory_facet_query` | Fråga via facett-taggar |
| `memory_verify` | Spåra ursprung |
### 6 resurser · 3 prompter · 17 skills
| Typ | Namn | Beskrivning |
|------|------|-------------|
| Resurs | `agentmemory://status` | Hälsa, sessionsantal, minnesantal |
| Resurs | `agentmemory://project/{name}/profile` | Intelligens per projekt |
| Resurs | `agentmemory://project/{name}/recent` | Senaste observationer för ett projekt |
| Resurs | `agentmemory://memories/latest` | De 10 senaste aktiva minnena |
| Resurs | `agentmemory://graph/stats` | Statistik för kunskapsgrafen |
| Resurs | `agentmemory://team/{id}/profile` | Delad teamprofil |
| Prompt | `recall_context` | Sök + returnera kontextmeddelanden |
| Prompt | `session_handoff` | Överlämningsdata mellan agenter |
| Prompt | `detect_patterns` | Analysera återkommande mönster |
| Skill | `/recall` | Sök i minnet |
| Skill | `/remember` | Spara till långtidsminnet |
| Skill | `/session-history` | Senaste sessionssammanfattningarna |
| Skill | `/forget` | Radera observationer/sessioner |
Tabellen visar de fyra kärnskillsen. Den fullständiga mängden är 9 anropsbara skills plus 8 referens-skills; se avsnittet om inbyggda skills ovan.
### Fristående MCP
Körs utan den fullständiga servern, för vilken MCP-klient som helst. Något av dessa fungerar:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Eller lägg till i din agents MCP-konfiguration:
De flesta agenter (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
Slå samman `agentmemory`-posten med värdens befintliga `mcpServers`-objekt istället för att ersätta filen. För sandboxade klienter som inte kan nå värdens `localhost`, lägg till `"AGENTMEMORY_FORCE_PROXY": "1"` i env-blocket och sätt `AGENTMEMORY_URL` till en väg som sandboxen kan nå.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
Kopiera plugin-filen från repot:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
Startar automatiskt på port `3113`. Viewern laddar en snapshot när den ansluter (`GET /agentmemory/viewer/snapshot`) och tillämpar därefter live-strömhändelser: nya minnen, lärdomar, observationer, granskningsposter, grafändringar och hälsouppdateringar visas utan polling eller sidomladdningar. De enda andra förfrågningarna är de åtgärder du klickar på, sidor för "ladda mer" och sökningar. När strömmen bryts visar viewern hur gamla dess siffror är, återansluter med backoff och synkar om från en snapshot.
- **12 flikar i fyra grupper** med livevärden, djuplänkar (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), kortkommandon och en mobilmeny.
- **Memories:** serversidig sökning, filter efter projekt, agent och typ, en detaljpanel med versionskedjan och en orddiff, ursprungslänkar, kopieringsknappar för id:t, MCP-anropet och ett curl-kommando, redigering (en ny version), glöm med bekräftelse, massglöm och JSON-export.
- **Sessions:** en inbäddad observationstidslinje med läsbar verktygsindata och -utdata, filter och sidbläddring, samt de minnen och lärdomar varje session gav upphov till.
- **Graph:** sökning, noddetaljer med relationer och källor, en legend som inte enbart förlitar sig på färg, samt zoomkontroller.
- **Health:** liveversionen av `GET /agentmemory/status`. Varje problem kommer med sin åtgärd, plus state-backend, indexsparningsstatus, förloppet för kompaktering av grafursprung och en konsolideringsförklaring med de verkliga tröskelvärdena.
- **Audit, Activity, Profile, Replay, Lessons, Actions och Crystals**-sidorna, var och en med ett tomt tillstånd som säger vad avsnittet är, varför det är tomt och vilket kommando som fyller det, samt en `?`-ordlisteverktygstips på varje term och siffra.
```bash
open http://localhost:3113
```
Viewer-servern binder till `127.0.0.1` som standard och bifogar serverhemligheten när den vidarebefordrar förfrågningar till REST API:et, så den behöver ingen konfiguration. Endpointen `/agentmemory/viewer`, som serveras via REST, följer de vanliga bearer-token-reglerna och omdirigerar webbläsare utan token till viewer-porten. CSP-headrarna använder en script-nonce per svar och inaktiverar inline-hanterarattribut (`script-src-attr 'none'`).
---
Viewern på `:3113` visar vad din agent **minns**. [iii-konsolen](https://iii.dev/docs/console) visar vad din agent **gjorde**: varje minnesoperation som ett OpenTelemetry-spår, varje KV-post redigerbar, varje funktion anropsbar, varje ström avlyssningsbar. Två fönster mot samma minne: ett produktformat, ett motorformat.
Se en `memory_smart_search` utlösas och följ BM25-skanningen → embedding-uppslaget → RRF-fusionen → rerankern som ett vattenfall. Redigera en fastnad konsolideringstimer i KV-webbläsaren. Spela upp en `PostToolUse`-hook igen med en justerad nyttolast. Fäst WebSocket-strömmen och se observationer landa i realtid.
agentmemory levererar detta gratis eftersom varje funktionsanrop och trigger går genom iii; inget anpassat, inget att instrumentera.
Workers-sidan: varje ansluten worker, inklusive agentmemory självt, med PID, funktionsantal, körtid och senast sedd.
**Redan installerad.** Konsolen levereras med den fastlåsta `iii`-enginen (0.22+); inget separat att installera. Den första starten laddar ner konsolbinären bredvid enginen.
**Starta tillsammans med agentmemory:**
```bash
agentmemory console
```
Detta kör den fastlåsta enginens `iii console` mot de portar agentmemory har löst (REST, strömmar, bridge) och serverar den en port ovanför viewern, `http://localhost:3114` som standard. `--console-port N` väljer en annan port; `--port` och `--instance` väljer agentmemory-instansen på samma sätt som för `stop`; varje annan flagga skickas vidare, till exempel `--enable-flow` för den experimentella arkitektur-grafsidan.
Samma sak för hand, användbart när `agentmemory` inte finns i PATH:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**Vad du kan göra från konsolen:**
| Sida | Använd den för att |
|------|-----------|
| **Workers** | Se varje ansluten worker och dess livemetrik, inklusive agentmemory-workern själv. |
| **Functions** | Anropa vilken av agentmemorys funktioner som helst direkt med en JSON-nyttolast; praktiskt för att testa `memory.recall`, `memory.consolidate`, `graph.query` utan att koppla in en klient. |
| **Triggers** | Spela upp HTTP-, cron-, event- och state-triggers igen: utlös konsolideringscronen manuellt, försök igen med en HTTP-rutt, sänd en tillståndsändring. |
| **States** | KV-webbläsare med fullständig CRUD över sessioner, minnesplatser, livscykeltimrar och embedding-indexet; redigera värden direkt. |
| **Streams** | Live-WebSocket-övervakning för minnesskrivningar, hook-händelser och observationsuppdateringar när de flödar genom iii-strömmarna. |
| **Queues** | Beständiga köämnen + hantering av dödbrevslådor. Spela upp igen eller släpp misslyckade embedding-/komprimeringsjobb. |
| **Traces** | OpenTelemetry-vyer för vattenfall/flame/tjänsteuppdelning. Filtrera på `trace_id` för att se exakt vilka funktioner, DB-anrop och embedding-förfrågningar en enskild `memory.search` gav upphov till. |
| **Logs** | Strukturerade OTEL-loggar filtrerade och korrelerade till trace-/span-ID:n. |
| **Config** | Körtidskonfiguration: se exakt vilka workers, leverantörer och portar din engine körs med. |
| **Flow** | (Valfritt, `--enable-flow`) Interaktiv arkitekturgraf över varje worker, trigger och ström. |
Traces: vattenfall/flame/tjänsteuppdelning för varje minnesoperation.
**Spårning är redan aktiverad:**
`iii-config.yaml` levereras med workern `iii-observability` aktiverad (`exporter: memory`, `sampling_ratio: 0.1`, metrics + loggar). Ingen extra konfiguration behövs; i samma stund agentmemory startar sänder varje minnesoperation ut en strukturerad logg som konsolen kan läsa, och en av tio av dem (`sampling_ratio: 0.1`) sänder också ut ett spår-span.
Om du istället vill exportera till Jaeger/Honeycomb/Grafana Tempo, ändra `exporter: memory` till `exporter: otlp` och sätt collector-endpointen enligt iii:s dokumentation för observability.
> **Observera:** ingen autentisering upprätthålls på konsolen själv; håll den bunden till `127.0.0.1` (standard) och exponera den aldrig publikt.
---
agentmemory är **redan en körande [iii](https://iii.dev)-instans**. Tre primitiv (worker, function, trigger) utgör körtiden; KV-state, strömmar och OTEL-spår kommer från workers som iii-state, iii-stream och iii-observability som levereras med iii. Du installerade inte Postgres, Redis, Express, pm2 eller Prometheus, eftersom iii ersätter dem.
Det betyder att ett enda extra kommando utökar agentmemory med en helt ny funktion.
### Utöka agentmemory med fler workers
De inbyggda workers agentmemory behöver finns redan i `iii-config.yaml` och startar med den: `iii-state` (KV), `iii-queue` (beständiga återförsök för händelseprenumeranterna), `iii-pubsub`, `iii-cron`, `iii-stream` och `iii-observability` (OTEL-spår, metrics och loggar för varje funktion). Allt annat från [iii-workerregistret](https://workers.iii.dev) kopplas in i samma engine: kopiera `iii-config.yaml` till `~/.agentmemory/iii-config.yaml` (CLI:n föredrar den filen framför den medföljande, och renderar fortfarande portar och datasökvägar in i den), lägg till posten, installera worker-körtiden en gång med `~/.agentmemory/bin/iii update worker`, och starta om 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 | Vad du får utöver agentmemory |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | SQL-baserad state-adapter när du växer ur standardinställningarna för KV i minnet |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Kod som kommer från `memory_recall` körs inuti en slit-och-släng-VM, inte ditt skal |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Sätt upp extra MCP-servrar bredvid agentmemorys egen, dela samma engine |
På engine 0.22.x, behåll de `iii-`-prefixade namnen för de inbyggda ovan; posterna utan prefix `http`, `state`, `queue`, `pubsub` och `cron` är de fristående registerworkers som agentmemory flyttar till med 0.23-migreringen.
Fullständigt register: [workers.iii.dev](https://workers.iii.dev). Varje worker där sätts samman via samma primitiv som agentmemory använder, och den agentmemory du redan har är en av dem.
### Motorkonfiguration och bindningsadress
`agentmemory start` läser motorkonfigurationen från den första fil som finns: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` i den aktuella katalogen, `~/.agentmemory/iii-config.yaml`, och därefter den medföljande `iii-config.yaml`. Vid varje start renderar den den filen (datasökvägar, portar, state-backend) till `~/.agentmemory/data/iii-config.runtime.yaml` och startar enginen med den renderade kopian, så redigera källfilen, inte den renderade. Värdena för `host:` i källfilen bevaras som skrivna.
Den medföljande `iii-config.yaml` binder till `127.0.0.1` med avsikt, och den standarden gäller även inuti en container. En CLI som startas i en container lyssnar på containerns loopback, så publicerade portar når ingenting. För att serva en containeriserad CLI genom publicerade portar, sätt `AGENTMEMORY_III_CONFIG` till en konfiguration som binder till `0.0.0.0`. Den paketerade `iii-config.docker.yaml` är en sådan: den binder `iii-http`, `iii-stream` och engine-porten till `0.0.0.0` och lagrar state under `/data`, så montera en skrivbar volym där. Håll `AGENTMEMORY_SECRET` satt, och publicera bara de portar du behöver, på `127.0.0.1` eller bakom en proxy du litar på.
Detta repos `docker-compose.yml` går inte genom CLI:ns konfigurationssökning: den monterar `iii-config.docker.yaml` på `/app/config.yaml`, och containern `iii-engine` startar med `--config /app/config.yaml`. Mallarna för [driftsättning med ett klick](../deploy/) skriver sin egen `0.0.0.0`-konfiguration i sina startpunkter.
### Lagringsbackend: fil (standard) kontra redis
`iii-state` och `iii-stream` använder som standard iii-enginens medföljande fil-baserade KV-lager: en JSON-fil per scope, hållen i motor-processens minne och omskriven till disk på en timer. Det är rätt standard för en lokal installation med en användare; en delad daemon med flera samtidiga skrivare får istället riktiga skrivningar per nyckel från Redis, till priset av en nätverkstur-och-retur per operation (varje `state::*`-anrop serialiseras fortfarande på en Redis-anslutning, så detta byter ut fil-lagrets lås mot en socket, inte mot parallellitet).
Sätt `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) för att växla båda workers till iii-enginens inbyggda `redis`-adapter, som lagrar varje nyckel som ett Redis-hashfält (`HSET`) istället för att skriva om ett helt scope vid varje skrivning:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
`AGENTMEMORY_STATE_BACKEND` har `file` som standard; att lämna den osatt behåller dagens beteende oförändrat, och ett okänt värde (något annat än `file` eller `redis`) ger ett startfel istället för en tyst reserv. `/agentmemory/status` och viewerns Health-sida (raden State store) rapporterar vilken backend som är aktiv och om den svarar, aldrig URL:en.
**Endast rent `redis://`.** Den fastlåsta enginen (0.22.1) bygger sin Redis-klient utan TLS-stöd, så en `rediss://`-URL (de flesta hanterade Redis-erbjudanden, som Upstash, Redis Cloud och ElastiCache med kryptering under överföring, är som standard enbart TLS) misslyckas med att ansluta. Anslutningen är okrypterad, så Redis-lösenordet och varje lagrat minne passerar tråden i klartext: peka mot en lokal Redis eller en på ett privat nätverk du litar på. För någon annan Redis, kör en krypterad tunnel (stunnel, SSH eller en VPN) på agentmemory-värden, så att det rena `redis://`-hoppet stannar på den värden och tunnelns uppströmsanslutning är krypterad och autentiserad. Om ett Redis-lösenord innehåller ett enkelt citattecken, procent-koda det (`%27`); enginen expanderar URL:en i sin YAML-konfiguration innan den tolkas.
**En Redis-server per `--instance`.** Enginens Redis-nyckelprefix (`state:`, `stream::`) är fasta, så två agentmemory-instanser (`--instance 1`, `--instance 2`, ...) som pekar mot samma databas skriver över varandras data. Ett separat databasindex (`redis://localhost:6379/1`) håller den lagrade datan åtskild, men enginen vidarebefordrar live-viewerhändelser över en Redis pub/sub-kanal (`stream::events`), och Redis pub/sub ignorerar databasindexet, så varje instans viewer skulle fortfarande visa den andras livehändelser. Ge varje instans sin egen Redis-server (eller port) när du kör mer än en.
**Vad som förblir samma, och vad som skiljer sig.** Varje funktion i agentmemory fungerar på Redis: sessioner, observationer, minnen (remember, supersede, evolve, forget), sökning och indexbuckets, lärdomar, grafen, granskningsloggen och dess månadsscopes, export och import, governance-raderingar, konsolideringsstatus, viewer-snapshoten och dess liveström, samt hälsoövervakaren. Enginen lagrar varje scope som en Redis-hash (`HSET`/`HGET`/`HGETALL`) och utlöser samma state-triggers som fil-lagret. Tre skillnader i enginen hanteras inuti agentmemory:
- Redis returnerar ett scopes poster i ingen bestämd ordning. agentmemory sorterar dem äldst först (efter skapelsetiden i post-id:t, sedan dess tidsstämpel) så att listor, sidbläddring och exportdelar kommer tillbaka i samma ordning som på fil-lagret.
- Enginen tillämpar partiella uppdateringar på Redis i ett Lua-skript som omvandlar tomma arrayer till tomma objekt. agentmemory tillämpar de uppdateringarna själv (läsa, ändra, skriva under ett lås per nyckel) på Redis, så att fält som `tags: []` förblir arrayer.
- Den äldre granskningslogg-kontrollen läser det gamla scopet från Redis istället för att leta efter fil-lagrets fil på disk.
En skillnad kräver din uppmärksamhet: **efter att Redis har startat om slutar enginen vidarebefordra livehändelser** till viewern tills agentmemory startas om. Data sparas och läses fortfarande normalt. Hälsoövervakaren skickar en testhändelse genom Redis var 30 sekunder; när den inte kommer tillbaka visar `/agentmemory/status` och viewerns Health-sida "Live updates are not reaching the viewer" med åtgärden: starta om agentmemory. Om Redis är nere visar statusrapporten "The state store is not answering" och hur man kontrollerar det (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Att lista ett mycket stort scope läser hela hashen i ett `HGETALL`, samma kostnad som fil-lagret att hålla det i minnet.
**Rekommenderade Redis-inställningar.** Standardpolicyn för snapshot, `save 3600 1 300 100 60 10000`, kan förlora minuter av skrivningar vid en krasch, värre än fil-lagrets 5-sekunders flush-fönster. Sätt `appendonly yes` för allt du skulle bry dig om att förlora. Sätt `maxmemory-policy noeviction`; `allkeys-lru` eller liknande tappar minnen i det tysta när Redis når sin minnesgräns.
En native (icke-Docker) start, och varje driftsättningsmall [med ett klick](../deploy/) (de skriver över den medföljande `iii-config.yaml` och startar native), läser `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` och renderar dem in i den startade `iii-config`. URL:en själv skrivs aldrig till den renderade filen, bara en referens `${AGENTMEMORY_REDIS_URL}` som motor-processen expanderar från sin egen miljö vid start. Bara detta repos egen Docker Compose-väg (`AGENTMEMORY_USE_DOCKER=1`, eller att återuppta en engine som redan startats på det sättet) monterar `iii-config.docker.yaml` skrivskyddat och renderar aldrig; `agentmemory start` varnar när den upptäcker den kombinationen. Byt den filen för hand, enligt samma form `name: redis` / `config: redis_url: ...` som visas i dokumentationen för workers [iii-state](https://workers.iii.dev/workers/iii-state) och [iii-stream](https://workers.iii.dev/workers/iii-stream), och peka `redis_url` mot en Redis som går att nå från containern. `docker-compose.yml` skickar `AGENTMEMORY_REDIS_URL` in i engine-containern, så `redis_url: '${AGENTMEMORY_REDIS_URL}'` fungerar där och håller URL:en utanför den monterade filen.
Den renderade konfigurationen håller URL:en utanför `~/.agentmemory/data/iii-config.runtime.yaml`, men enginens egen konfigurationsworker sparar fortfarande det *expanderade* värdet till `~/.agentmemory/config/iii-state.yaml` och `iii-stream.yaml` när den startar (iii-enginens `${VAR}`-expansion sker innan den workern lagrar sitt frö, och den lagrar det upplösta värdet, inte referensen). Behandla den katalogen som om den innehåller en autentiseringsuppgift: `chmod 700 ~/.agentmemory` på varje delad värd, och föredra en Redis ACL-användare begränsad till det agentmemory behöver framför databasens admin-uppgifter.
**Migrering sker inte automatiskt.** Att växla `AGENTMEMORY_STATE_BACKEND` börjar med ett tomt lager på båda sidor; ingenting kopierar befintlig data från fil till Redis eller tillbaka. Exportera från den backend du lämnar och importera till den du flyttar till. Detta körs identiskt under bash och zsh (inklusive `bash -u`). En array som `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gör det inte: zsh behåller headern som ett enda felformat ord där bash delar upp den i två, så båda förfrågningarna ger 401 närhelst `AGENTMEMORY_SECRET` är satt:
```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` accepterar också `?maxSessions=` och `?offset=` för att dela upp ett stort korpus över flera anrop; `strategy` vid import är `merge` (säker standard), `replace` eller `skip`.
### Vad iii ersätter
| Traditionell stack | agentmemory använder |
|---|---|
| Express.js / Fastify | iii HTTP-triggers |
| SQLite / Postgres + pgvector | iii KV-state + vektorindex i minnet |
| SSE / Socket.io | iii-strömmar (WebSocket) |
| pm2 / systemd | iii-enginens worker-övervakning |
| Prometheus / Grafana | iii OTEL + hälsoövervakare |
| Anpassade pluginsystem | `iii worker add ` |
**219 källkodsfiler · ~52,000 LOC · 2,500+ tester · 311 funktioner · 60 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
---
### LLM-leverantörer
agentmemory upptäcker leverantörer automatiskt från din miljö. En leverantör gör LLM-baserade operationer tillgängliga, men leverantörskonfiguration ensam aktiverar inte LLM-skriven observationskomprimering. Den vägen kräver både en leverantör och `AGENTMEMORY_AUTO_COMPRESS=true`.
| Leverantör | Konfiguration | Anteckningar |
|----------|--------|-------|
| **No-op (standard)** | Ingen konfiguration behövs | LLM-baserad komprimering/sammanfattning är inaktiverad. Syntetisk komprimering och BM25-återkallning fungerar fortfarande. Se `AGENTMEMORY_ALLOW_AGENT_SDK` nedan om du tidigare förlitade dig på Claude-prenumerationsreserven. |
| Anthropic API | `ANTHROPIC_API_KEY` | Fakturering per token |
| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
| Gemini | `GEMINI_API_KEY` | Aktiverar även embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Vilken modell som helst |
| OpenAI API | `OPENAI_API_KEY` | Standard `gpt-5.6-luna`, åsidosätt 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=` | Allt som är OpenAI-API-kompatibelt. Noll kostnad, körs på din hårdvara. Se [Lokala modeller](#local-models-ollama--lm-studio--vllm) nedan. |
| Claude-prenumerationsreserv | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Endast opt-in. Startar `@anthropic-ai/claude-agent-sdk`-sessioner; den orsakade tidigare obegränsad Stop-hook-rekursion, så den är inte längre standard. |
### Lokala modeller (Ollama / LM Studio / vLLM)
agentmemory talar med vilken OpenAI-API-kompatibel server som helst, så allt som exponerar `/v1/chat/completions` fungerar utan kodändringar. Inga betalda nycklar, inget moln, inga rate limits; körs helt på din hårdvara.
**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`):
Öppna LM Studio → fliken Local Server → Start Server. Välj vilken chattmodell som helst från väljaren (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**: samma form. Peka `OPENAI_BASE_URL` mot vilken URL din server än exponerar och sätt `OPENAI_MODEL` till ett namn din server accepterar.
**Modellval för minnesarbete**: komprimering och sammanfattning är korta uppgifter (<2K tokens in, <500 tokens ut) där en 7B instruct-modell räcker gott och väl. Rekommendationer:
| Modell | Storlek | Varför |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | Balanserad standard på en 16 GB-maskin; stark på extraktion och verktygsformad text |
| `qwen3:4b` | ~2.6 GB | Minsta rimliga alternativet; funkar för komprimering, svagare för grafextraktion |
| `qwen3-coder:30b` | ~19 GB | Bästa lokala valet för kodformade sessioner (30B MoE, 3.3B aktiva) på 24-32 GB hårdvara |
| `gpt-oss:20b` | ~14 GB | Stark generell modell som ryms i 16 GB RAM |
| `deepseek-r1:8b` | ~5.2 GB | Reasoning-destillat; långsammare men renare extraktioner |
Qwen 3-modeller tänker som standard och kan bränna hela tokenbudgeten på reasoning innan någon utdata alls. Sätt `AGENTMEMORY_LLM_NOTHINK=1` för att lägga till `/no_think` i prompter för grafextraktion, och höj `MAX_TOKENS` (16384 funkar) om extraktioner kommer tillbaka tomma.
Reasoning-modeller (`o1`-stil med ``-block) kan returnera tomt `content` med ett `reasoning`-fält som din lokala server kanske inte exponerar. Om extraktioner kommer tillbaka tomma, byt först till en modell utan reasoning. Miljövariabeln `OPENAI_REASONING_EFFORT=none` kan också inaktivera tänkande på Ollama Cloud-tänkande-modeller som speglar OpenAIs reasoning-schema.
Lokala embeddings levereras som ett valfritt beroende men är inte aktiverade som standard. Sätt `EMBEDDING_PROVIDER=local` för att aktivera `Xenova/all-MiniLM-L6-v2` (384 dimensioner). Den första embedding-förfrågan laddar ner modellen; inferensen sker därefter på enheten. Utan den inställningen eller en fjärr-embedding-nyckel förblir vektorer inaktiverade, `mem::search` använder BM25, och `smart-search` kan fortfarande lägga till befintliga grafmatchningar.
### Kostnadsmedvetet modellval
När LLM-skriven bakgrundskomprimering är aktiverad med både en leverantör och `AGENTMEMORY_AUTO_COMPRESS=true`, körs den vid varje observation, så modellvalet förändrar den månatliga kostnaden på ett betydande sätt. Infångad arbetsbelastningsdata: 635 förfrågningar / 888K tokens / 35 timmars aktiv användning, körd mot tre OpenRouter-modeller enligt prissättningen 2026-05-23.
| Nivå | Modell | Indata / 1M | Utdata / 1M | Kostnad för de infångade 35 timmarna | Anteckningar |
|------|-------|------------|-------------|---------------------------|-------|
| Rekommenderad | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (uppskattat) | Senaste DeepSeek; billigaste rekommenderade valet för komprimeringsarbetsbelastningar. |
| Rekommenderad | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid kvalitet på komprimering + sammanfattning till ~10 gånger lägre kostnad än Sonnet. |
| Rekommenderad | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Stark kodresonering om dina sessioner är starkt kodformade. |
| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (uppskattat) | Samma listpris som den uppmätta Sonnet 4.6-körningen; introduktionspris $2/$10 till och med 2026-08-31. |
| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (uppskattat) | Flaggskeppsnivå; dyrt för alltid-på-bakgrundsarbete. |
| Undvik | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (uppskattat) | Flaggskeppsklass-modell; överspenderat för komprimering. |
Uppmätta rader kommer från den infångade körningen; rader märkta (uppskattat) skalar samma tokenmix efter varje modells listpris.
agentmemory skriver ut en körtidsvarning när `OPENROUTER_MODEL` matchar ett premiumnivåmönster. Sätt `AGENTMEMORY_SUPPRESS_COST_WARNING=1` för att tysta den när du har gjort ett informerat val.
Avvägning mellan kvalitet och kostnad för minnesarbete: komprimering är en sammanfattningsuppgift med relativt lösa kvalitetskrav (agenten läser om sammanfattningen, inte användaren). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder hamnar inom felmarginalen av Sonnet på denna uppgift samtidigt som de kostar 10-70 gånger mindre. Spara premiumnivå-modellerna för frågor du läser direkt.
Källor: [OpenRouter-prissättning för Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-prissättningsanteckningar](https://api-docs.deepseek.com/quick_start/pricing/).
### Multiagent-minne (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
I multiagent-uppsättningar där flera roller delar en agentmemory-server (architect / developer / reviewer / researcher / support-agent), taggar `AGENT_ID` varje skrivning med rollen som gjorde den. `AGENTMEMORY_AGENT_SCOPE` styr om återkallning filtrerar på den taggen.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
Två lägen:
| Läge | Taggar skrivningar | Filtrerar återkallning | När man använder det |
|------|------------|---------------|-------------|
| `shared` (standard) | ja | nej | Kontext mellan agenter med granskningsspår. Architect kan se vad developer noterade, men varje rad registrerar vem som sa det. |
| `isolated` | ja | ja | Strikt separation. Architect ser aldrig developers observationer / minnen / sessioner. |
Vad som taggas när `AGENT_ID` är satt: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rollen flödar från `api::session::start` → `mem::observe` → `mem::compress` → KV.
Vad som filtreras i isolerat läge: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Varje endpoint accepterar `?agentId=` för att åsidosätta per förfrågan, och `?agentId=*` för att helt välja bort miljö-scopet. `/memories` accepterar också `?includeOrphans=true` för att visa minnen från före AGENT_ID vars `agentId` är odefinierad.
Åsidosättning per anrop på SDK-/REST-lagret: varje muterande endpoint (`/session/start`, `/remember`) accepterar ett `agentId`-fält i förfrågans body som vinner över miljövariabeln. Användbart för körtider som dirigerar många roller genom en serverprocess. MCP-verktyget `memory_save` exponerar samma `agentId`-fält, den fristående stdio-servern vidarebefordrar både `agentId` och `project`, och sparade minnen bär `agentId` in i sökindexet, så agent-scopead sökning täcker minnen lika väl som observationer.
När `AGENT_ID` inte är satt förblir minnet oscopat (äldre beteende, inga taggar, inga filter).
### Portar
agentmemory + iii-engine binder fyra portar som standard. Om en omstart misslyckas med `port in use`, säger den här tabellen vilken process du ska leta efter.
| Port | Process | Syfte | Åsidosättning via miljövariabel |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | Intern strömmar-worker (används av agentmemory + viewer) | `III_STREAM_PORT` (att föredra) eller äldre `III_STREAMS_PORT` |
| `3113` | agentmemory | Viewer i realtid (`http://localhost:3113`) | `III_VIEWER_PORT` eller `AGENTMEMORY_VIEWER_URL` för den rapporterade URL:en |
| `49134` | iii-engine | WebSocket; workers registrerar sig här, OTel-telemetri flödar över den | `III_ENGINE_PORT` eller `III_ENGINE_URL` |
`--port ` ändrar REST-ankaret och härleder strömmar `N+1`, viewer `N+2`, och engine-WebSocket `N+46023` bara där motsvarande explicita port eller URL ovan är osatt. Det skapar inte en isolerad livscykel-namnrymd. Använd `--instance 1` för en andra daemon; den använder ankare 3211, defaultar till `3211/3212/3213/49234`, och får en separat data- och livscykelkatalog `instance-1`. Instanser 1 till 50 följer samma mönster.
Den fastlåsta enginen startar med `--no-update-check` (inga uppslag mot GitHub för uppdateringar eller säkerhetsrådgivningar vid start) och med iii:s anonyma användningstelemetri avstängd: agentmemory sätter `III_TELEMETRY_ENABLED=false` för enginen den startar om du inte exporterar variabeln själv, och den medföljande compose-filen gör samma sak.
Rensning av gamla processer när portar förblir bundna efter en kraschad körning:
```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` städar bort både workerns och enginens pidfil rent vid en skonsam native-avstängning. I Docker-läge flushar den native-workern, stoppar exakt den validerade engine-containern, och bevarar både containern och dess `/data`-montering för en förlustfri omstart; nästa start validerar och återupptar samma container. Avinstallation med Docker som backend kräver `agentmemory remove --keep-data`: den tar bort delade agentmemory-hanterade filer samtidigt som den bevarar den validerade containern, dess datamontering och den livscykelpost som behövs för att återställa dem. Destruktiv radering av Docker-data lämnas avsiktligt till operatören efter en backup. CLI:n vägrar också att adoptera eller signalera Docker- eller VM-portinnehavare (Docker backend, vpnkit, colima) som den native enginen om inte `--force` anges. Den manuella rensningen ovan är bara till för fallet efter en krasch där ingen pidfil lämnats kvar.
### Konfigurationsfil
Lägg agentmemorys körtidskonfiguration i `~/.agentmemory/.env` istället för att exportera variabler i varje skal. Om viewern visar ett konfigurationstips som `export ANTHROPIC_API_KEY=...`, kopiera det in i den här filen som `ANTHROPIC_API_KEY=...` utan `export`-prefixet, och starta sedan om agentmemory.
Processens miljövariabler fungerar fortfarande och har företräde framför värden i filen.
På Windows finns samma fil på `%USERPROFILE%\.agentmemory\.env`:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
För att testa med en Claude Code Pro/Max-prenumeration istället för en API-nyckel, aktivera det explicit:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
LLM-skriven observationskomprimering kräver båda raderna: åtkomst till en LLM-leverantör (inklusive denna explicita prenumerationsreserv) och `AGENTMEMORY_AUTO_COMPRESS=true`. En leverantör ensam lämnar standardvägen för syntetisk komprimering intakt.
Konsolidering (grafnoder, lärdomar, crystals) är aktiverad som standard närhelst en LLM-leverantör är konfigurerad. Välj bort den explicit med `CONSOLIDATION_ENABLED=false` om du vill ha LLM-fri drift. Grafextraktion är en separat flagga:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Miljövariabler
Skapa `~/.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 till `127.0.0.1` som standard. Skyddade endpoints kräver `Authorization: Bearer `, och mesh-synk-endpoints kräver en explicit satt `AGENTMEMORY_SECRET` på båda parterna.
**Autentisering är aktiverad som standard.** När `AGENTMEMORY_SECRET` inte är satt (i skalet eller i `~/.agentmemory/.env`), genererar servern en slumpmässig hemlighet vid första start och lagrar den i `~/.agentmemory/secret` med rättigheterna `0600`. Varje medföljande klient läser den därifrån när den talar med en lokal server: CLI:n, viewern, hookarna under `plugin/scripts`, MCP-servern och `@agentmemory/mcp`-shimmen, konfigurationerna skrivna av `agentmemory connect`, och de medföljande integrationerna för OpenCode, Pi, OpenClaw, Hermes och filsystemsbevakaren. Den lagrade hemligheten skickas bara till loopback-URL:er (`localhost`, `127.0.0.0/8`, `::1`). En explicit `AGENTMEMORY_SECRET` vinner alltid, och fjärrklienter måste fortfarande ha den satt. Docker och startpunkterna i `deploy/` genererar och exporterar redan sin egen hemlighet. För att anropa API:et för hand:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**Regler för skrivförfrågningar.** `POST`-, `PUT`-, `PATCH`- och `DELETE`-förfrågningar till REST API:et och viewern måste skicka `Content-Type: application/json` (en `charset`-parameter är okej) närhelst de bär en body, och en `Origin`-header, när den finns, måste vara en loopback-origin för den konfigurerade REST- eller viewer-porten eller finnas listad i `VIEWER_ALLOWED_ORIGINS` (kommaseparerat, t.ex. `https://memory.example.com`). Klienter som inte skickar någon `Origin`-header (CLI, hooks, MCP, curl, server-till-server) påverkas inte. Viewern accepterar också sitt eget origin.
**Filsökvägar.** Endpoints som läser eller skriver filer (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) accepterar bara sökvägar under `~/.agentmemory`, instansens datakatalog, eller en katalog listad i `AGENTMEMORY_IMPORT_ROOT` (separera flera med `:`, eller `;` på Windows). `/replay/import-jsonl` accepterar också sin standard `~/.claude/projects`. `/obsidian/export` håller sig inom `AGENTMEMORY_EXPORT_ROOT` och `/migrate` inom `~/.agentmemory`. Symlinkar löses upp innan varje kontroll.
**Rensning av hemligheter.** API-nycklar, bearer-tokens, PEM-privatnyckelblock och autentiseringsuppgifter inbäddade i URL:er (`scheme://user:password@host`) redigeras bort innan text lagras, på varje skrivväg: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, komprimerings- och sammanfattningsutdata, crystals och grafnoder.
Viktiga endpoints
| Metod | Sökväg | Beskrivning |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Hälsokontroll (alltid publik) |
| `GET` | `/agentmemory/status` | Vad som är fel och hur man fixar det (HTML för webbläsare, annars JSON) |
| `GET` | `/agentmemory/viewer/snapshot` | Allt viewern visar, i ett svar |
| `POST` | `/agentmemory/session/start` | Starta session + hämta kontext |
| `POST` | `/agentmemory/session/end` | Avsluta session |
| `POST` | `/agentmemory/observe` | Fånga in observation (se infångningsleverans nedan) |
| `GET` | `/agentmemory/capture` | Infångningsinkorg, dödbrev och offline-spool |
| `POST` | `/agentmemory/capture/retry` | Försök igen med dödbrevsinfångningar |
| `POST` | `/agentmemory/capture/drain` | Skicka den lokala offline-spoolen nu |
| `POST` | `/agentmemory/smart-search` | Hybridsökning |
| `POST` | `/agentmemory/context` | Generera kontext |
| `POST` | `/agentmemory/remember` | Spara till långtidsminnet |
| `POST` | `/agentmemory/forget` | Radera observationer |
| `POST` | `/agentmemory/enrich` | Filkontext + minnen + buggar |
| `GET` | `/agentmemory/profile` | Projektprofil |
| `GET` | `/agentmemory/export` | Exportera all data |
| `POST` | `/agentmemory/import` | Importera från JSON |
| `POST` | `/agentmemory/graph/query` | Fråga kunskapsgrafen |
| `POST` | `/agentmemory/graph/compact` | Trimma överdimensionerat grafursprung |
| `POST` | `/agentmemory/team/share` | Dela med team |
| `GET` | `/agentmemory/audit` | Granskningsspår |
Fullständig endpoint-lista: [`src/triggers/api.ts`](../src/triggers/api.ts)
**Infångningsleverans.** Hooks skickar varje observation en gång till `POST /agentmemory/observe` med ett `eventId`. Det är värdens eget id för anropet när nyttolasten har ett (till exempel Claude Codes `tool_use_id`), annars en hash av sessionen, hook-typen, verktygsnamnet, indata, utdata och värdens tidsstämpel. Servern skriver händelsen till en infångningsinkorg i state-lagret, lagrar observationen, och tar sedan bort inkorgsposten. Statuskoden säger vad som hände:
| Status | `status`-fält | Betydelse |
|---|---|---|
| `201` | `accepted` | Lagrad. `observationId` är den nya observationen. |
| `202` | `accepted` (`state: "retrying"`) | Accepterad, men lagringen misslyckades. Servern försöker igen, även efter en omstart. |
| `200` | `duplicate` | Det här `eventId` hade redan accepterats. `observationId` är den befintliga observationen; ingenting nytt lagras. |
| `400` / `422` | `rejected` | Ogiltig nyttolast, eller lagringen misslyckades permanent (händelsen behålls som ett dödbrev). |
| `503` | `rejected` (`retryable: true`) | Inkorgen är full (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks lägger händelsen i kö och skickar den senare. |
Misslyckade händelser får nya försök var `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) med dubblerande backoff, upp till `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Händelser som fortfarande misslyckas stannar i inkorgen som dödbrev, listas på `/agentmemory/status` och viewerns Health-sida, och kan försökas igen med `POST /agentmemory/capture/retry` (`{"eventId": "..."}` eller `{"all": true}`). Accepterade händelse-id:n minns i `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 timmar, högst `AGENTMEMORY_CAPTURE_EVENTS_MAX` id:n), så en hook som spelas upp igen efter en timeout eller en omstart lagras en gång, medan två separata verktygsanrop med sina egna värd-id:n lagras två gånger även om deras innehåll är identiskt. När en observation raderas (forget, sessionsradering, utrensning, auto-glömning eller en import som ersätter lagret), markeras dess händelse som raderad innan observationen tas bort, så en uppspelning av den händelsen inom samma fönster besvaras som en dubblett och lagrar ingenting. State-lagret skriver till disk var 2 sekunder, så en besvarad händelse kan fortfarande bara finnas i minnet för ett ögonblick. För att täcka det bär varje `2xx`-svar också serverns `bootId` (ny vid varje start), `acceptedAt` och `durableAfterMs` (sparintervallet plus 1.5 s på fil-lagret, 1.5 s på redis, där varaktighet är operatörens inställning). Hooks behåller händelsen i den lokala spoolen tills det fönstret har passerat och raderar den vid ett senare anrop utan ytterligare en förfrågan. Om `bootId` har ändrats vid det laget startade servern om, så hooken skickar händelsen igen med samma `eventId`; en händelse som faktiskt nådde disken lagras inte två gånger. Servern skickar också sådana händelser själv vid start och vid varje återförsöksintervall, så en omstart förlorar ingenting även om ingen hook körs efteråt. Äldre hooks ignorerar de extra fälten, och nya hooks mot en äldre server kastar händelsen vid `2xx` som tidigare.
När servern är nere, inte svarar i tid eller returnerar en 5xx, lägger hooken till observationen i en lokal spool-fil, `/capture-spool/-.jsonl` (åsidosätt mappen med `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Filen är privat för din användare (rättigheterna 600), hemligheter redigeras bort på samma sätt som servern gör det, den rymmer högst `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) och tappar poster äldre än `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). När den är full tappas nya poster och räknas, och `/agentmemory/status` rapporterar det. Hooken avslutas fortfarande med 0 inom sin tidsgräns och lägger inte till någon förfrågan när servern är frisk. Spoolen skickas vid nästa start och av den första hooken som når servern igen, i en bakgrundsprocess så att agenten inte väntar. Händelse-id:n gör detta säkert: en observation som faktiskt anlände innan en timeout lagras inte två gånger. `npx @agentmemory/agentmemory capture` visar spoolen och serverns inkorg, `--drain` skickar spoolen nu, och `GET /agentmemory/capture` returnerar samma sak som JSON. Sätt `AGENTMEMORY_CAPTURE_SPOOL=false` för att stänga av spoolen.
**Kompaktering av grafursprung.** Varje kunskapsgraf-nod och -kant behåller id:n för de senaste 32 observationerna den kom från. Lager skrivna innan den gränsen kan hålla tusentals id:n per het nod, vilket gör grafsökning och viewern långsamma eller slår ut workern. agentmemory fixar detta själv: vid den första starten efter en uppgradering trimmar den varje nod, kant, ersatt kant (den temporala grafhistoriken) och den cachade snapshoten till gränsen i bakgrunden, i små skivor med en paus mellan dem, så att sökning, infångning och viewern fortsätter fungera. Den sparar sitt förlopp, återupptas efter en omstart och körs aldrig igen när den väl är klar. `/agentmemory/status` och viewerns Health-sida visar den som väntande, körande (med aktuellt scope och position), klar eller misslyckad. Sätt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` för att stänga av den.
För att köra den för hand, anropa `POST /agentmemory/graph/compact`. Den går igenom namn- och kant-nyckel-indexen istället för att lista varje nod och kant, och är säker att köra igen. När den trimmar id:n skriver den en `graph_compact`-granskningspost.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
```
På ett stort lager, eller när anropet returnerar 504, kör den i skivor. Skicka `scope` (`nodes`, `edges` eller `history`), `offset` och `limit`, och anropa sedan igen med det returnerade `nextOffset` tills det är `null`. Gör detta för `nodes`, `edges` och `history`, och avsluta med ett `{"scope":"snapshot"}`-anrop, eftersom en skivad körning inte rör den cachade snapshoten.
```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)
```
**Förutsättningar:** Node.js >= 20 med npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 eller Docker. Den automatiska motorinstallationen för macOS/Linux kräver också `curl`, ett POSIX-`sh` och `tar`; native Windows använder den manuellt fastlåsta `iii.exe`, WSL2, eller Docker Desktop.
