Koodausagenttisi muistaa kaiken. Ei enää tarvetta selittää asioita uudelleen. Perustuu iii-moottoriin
Pysyvä muisti seuraaville: Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ja mikä tahansa MCP-asiakas.

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

Gist laajentaa Karpathyn LLM Wiki -mallia luottamuspisteytyksellä, elinkaarella, tietograafeilla ja hybridihaulla: agentmemory on tämän toteutus.

Asennus • Pika-aloitus • Benchmarkit • vs. kilpailijat • Agentit • Miten se toimii • MCP • Katseluohjelma • iii:n voimalla • Asetukset • API

` -valitsinta tai `AGENTMEMORY_DATA_DIR`-muuttujaa ylikirjoittaaksesi tämän, ja käytä samaa arvoa jokaisella uudelleenkäynnistyksellä. Taustayhteensopivuuden vuoksi olemassa oleva `./data/state_store.db` tai `./data/iii-config.yaml` ajaa instanssin 0 kohdalla alustan oletuksen edelle; nimenomainen lippu tai ympäristömuuttuja voittaa edelleen. Todista sitten, että muistin palauttaminen toimii, ja anna agentillesi sen taidot: ```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 ``` Avainsanahakujen pitäisi osua oletuksena avaimettomassa tilassa BM25:n kautta. Demon `database performance optimization` -kysely on tarkoituksella semanttinen ja voi palauttaa nolla tulosta, ennen kuin upotustarjoaja on määritetty. Haluatko antaa koodausagentin hoitaa koko homman? Anna sille yksi ohje: > Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md Kytke lisää agentteja milloin tahansa komennolla `agentmemory connect ` — 20 sovitinta listattuna kohdassa [Toimii jokaisen agentin kanssa](#works-with-every-agent). Täysi komentoviite kohdassa [Pika-aloitus](#quick-start).

Windows

Nopein reitti on WSL2. Natiivi Windows-moottorin asennus vaatii kiinnitetyn v0.22.1-ZIP-paketin latauksen ja `iii.exe`:n purkamisen käsin; CLI ei pura sitä automaattisesti. Docker Desktop on myös tuettu. Katso [Windows-huomautukset](#windows) vaihe vaiheelta.

Globaali asennus / EACCES

```bash npm install -g @agentmemory/agentmemory@latest ``` Yllä oleva npx-komento pysyy kanonisena tuoreena asennusreittinä ja välttää globaalin etuliitteen oikeusongelmat.

npx tarjoaa vanhan version

npx käyttää välimuistia versioittain. Pakota uusin versio komennolla `npx -y @agentmemory/agentmemory@latest`, tai tyhjennä välimuisti kerran komennolla `rm -rf ~/.npm/_npx` (macOS/Linux; Windowsilla poista `%LOCALAPPDATA%\npm-cache\_npx`).

Oma iii-moottori on jo käynnissä

agentmemory kiinnittää iii-engine-version v0.22.1:een ja ei liity eri versioon (worker ei osaa puhua toisen moottorin protokollaa). Pysäytä toinen moottori ja aja sitten `npx -y @agentmemory/agentmemory@latest`. Se asentaa ja ajaa kiinnitetyn v0.22.1-version polussa `~/.agentmemory/bin`, jättäen oman `iii`-asennuksesi koskemattomaksi.

---

agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST-rajapintaa. Kaikki agentit jakavat saman muistipalvelimen.

Claude Code natiivi plugin + 12 hookia + MCP	Codex CLI natiivi plugin + 6 hookia + MCP	GitHub Copilot CLI MCP + plugin-hookit/-taidot	Cursor natiivi plugin + 7 hookia + MCP	OpenCode tallennus-plugin + MCP
Devin 6 hookia + taidot + MCP	OpenClaw natiivi plugin + MCP	Hermes natiivi plugin + MCP	pi natiivi plugin + MCP	OpenHuman natiivi Memory-trait-taustaosa
Gemini CLI MCP-palvelin	Antigravity MCP + hookit	Claude Desktop MCP-palvelin	Warp connect + MCP + taidot	Zed MCP-palvelin
Cline MCP-palvelin	Continue MCP-palvelin	Droid MCP-palvelin	Kiro MCP-palvelin	Qwen Code MCP-palvelin
DeepSeek Harness MCP-palvelin	Roo Code MCP-palvelin	Kilo Code MCP-palvelin	Goose MCP-palvelin	Aider REST-rajapinta

_{Toimii minkä tahansa agentin kanssa, joka puhuu MCP:tä tai HTTP:tä. Yksi palvelin, muistot jaettuna kaikkien kesken.}

--- Selität saman arkkitehtuurin joka istunnossa. Löydät uudelleen samat bugit. Opetat uudelleen samat mieltymykset. Sisäänrakennettu muisti (CLAUDE.md, .cursorrules) tukkeutuu 200 riviin ja vanhenee. agentmemory korjaa tämän. Se tallentaa huomaamattomasti, mitä agenttisi tekee, pakkaa sen hakukelpoiseksi muistiksi ja syöttää oikean kontekstin, kun seuraava istunto alkaa. Yksi komento. Toimii agenttien välillä. **Mikä muuttuu:** Istunnossa 1 otat käyttöön JWT-autentikoinnin. Istunnossa 2 pyydät rate limitingiä. Agentti tietää jo, että autentikointisi käyttää jose-middlewarea tiedostossa `src/middleware/auth.ts`, että testisi kattavat tokenin validoinnin, ja että valitsit josen jsonwebtokenin sijaan Edge-yhteensopivuuden vuoksi — ei tarvetta selittää uudelleen eikä kopioi-liitä-työtä. ```bash npx -y @agentmemory/agentmemory@latest ``` Oletuksena agentmemory tallentaa iii-moottorin tilan sen repositorion ulkopuolelle, josta se käynnistetään: `~/Library/Application Support/agentmemory` macOS:llä, `$XDG_DATA_HOME/agentmemory` tai `~/.local/share/agentmemory` Linuxilla ja `%APPDATA%\agentmemory` Windowsilla. Olemassa oleva vanha `./data/state_store.db` tai `./data/iii-config.yaml` käytetään uudelleen instanssille 0 ennen tätä alustan oletusta. Valitaksesi sijainnin nimenomaisesti, välitä `--data-dir ` tai aseta `AGENTMEMORY_DATA_DIR`; kumpi tahansa nimenomainen asetus ajaa vanhan tunnistuksen edelle: ```bash npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest ``` Natiivi- ja Docker-käynnistykset käyttävät samaa ratkaistua isäntähakemistoa; Docker liittää sen pisteeseen `/data`. `--instance 1` liittää `instance-1`-hakemiston ratkaistuun hakemistoon ja valitsee erillisen oletusporttineljännyksen `3211/3212/3213/49234`. Uusimmat julkaisutiedot: [CHANGELOG.md](../CHANGELOG.md). ---

### Hakutarkkuus **coding-agent-life-v1** (talon sisäinen korpus, hiekkalaatikossa toistettavissa) | Sovitin | P@5 | R@5 | Top-5-osumasuhde | p50-latenssi | |---|---|---|---|---| | **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms | | grep-perustaso | 0.227 | 0.967 | 15 / 15 | 0 ms | 100 % top-5-osumasuhde **P@5-matemaattisessa kattossa** tälle korpukselle (0.240, katso scorecard). Hybrid hakee jokaisen kultaisen istunnon. grep jättää huomiotta 1/2 kultaisesta moni-istuntoisessa temporaalikyselyssä. Hyöty on **muistaminen + temporaalisuus**, ei kokonaistarkkuus. Tämä benchmark on pieni ja kultadataltaan harva; isompi LongMemEval-S alla erottelee paremmin. Täysi tyyppikohtainen erittely + korjaushuomautus: [`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 kysymystä) | Järjestelmä | R@5 | R@10 | MRR | |---|---|---|---| | **agentmemory** | **95.2%** | **98.6%** | **88.2%** | | vain BM25 -varmistusreitti | 86.2% | 94.6% | 71.5% |

### Tokenisäästöt | Lähestymistapa | Tokenia/vuosi | Kustannus/vuosi | |---|---|---| | Liitä koko konteksti | 19.5M+ | Mahdotonta (ylittää ikkunan) | | LLM-tiivistetty | ~650K | ~500 $ | | **agentmemory** | **~170K** | **~10 $** | | agentmemory + paikalliset upotukset | ~170K | **0 $** |

> Upotusmalli: `all-MiniLM-L6-v2` (paikallinen, ilmainen, ei API-avainta). Täydet raportit: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Kilpailijavertailu: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), joka kattaa agentmemoryn vs. mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo. **Toista paikallisesti:** [`eval/README.md`](../eval/README.md), sovitinpohjainen testipenkki LongMemEvalille `_s` (julkinen 500 kysymystä) + `coding-agent-life-v1` (talon sisäinen 15 istunnon korpus). Grep-, vektori- ja agentmemory-sovittimet pisteytetään rinnakkain, NDJSON-tulostus, julkaistut scorecardit löytyvät kansiosta [`docs/benchmarks/`](../docs/benchmarks/). **Toimii yhdessä [codegraphin](https://github.com/colbymchenry/codegraph), [Understand Anythingin](https://github.com/Lum1104/Understand-Anything) ja [Graphifyn](https://github.com/safishamsi/graphify) kanssa.** Koodigraafi-indeksointi, moniagenttiset build-putket ja laajemmat tietograafit dokumenttien / PDF:ien / kuvien / videoiden yli. agentmemory muistaa työn; nämä kolme projektia valaisevat kontekstikerroksen muun osan. Reseptit + kysymysten reititystaulukko: [`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	Sisäänrakennettu (CLAUDE.md)
Tyyppi	Muistimoottori + MCP-palvelin	Muistikerros-API	Täysi agentti-ajonaikainen ympäristö	Henkilökohtainen AI	Muisti-API + sovellus	Tiimimuistikeskus (LLM-proxy)	Vektorimuisti (avoin lähdekoodi)	Muistimoottori (Oracle-tietokanta)	Muistijärjestelmä	Staattinen tiedosto
Hakutarkkuus R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	Ei saatavilla	Itse ilmoitettu	PersonaMem 76% (itse ilmoitettu)	~96.6% (itse ilmoitettu)	94.4% (itse ilmoitettu)	Ei saatavilla	Ei saatavilla (grep)
Automaattinen tallennus	12 hookia (ei manuaalista työtä)	Manuaaliset add()-kutsut	Agentti muokkaa itseään	Manuaalinen	API-puolen poiminta	Proxy-sieppaus (base-URL-vaihto)	Manuaalinen	API-poiminta	Manuaalinen	Manuaalinen muokkaus
Haku	BM25 + vektori + graafi (RRF-fuusio)	Vektori + graafi	Vektori (arkisto)	Semanttinen	Vektori + RAG	4 omaisuustyyppiä (Chat / Skill / Wiki / CodeGraph)	Vain vektori	Vektori + semanttinen	Vanhenemispainotettu	Lataa kaiken kontekstiin
Moniagenttisuus	MCP + REST + leaset + signaalit	API (ei koordinaatiota)	Vain Lettan ajonaikaisessa ympäristössä	Ei	Ei	Tiimiroolit + jaetut omaisuudet	Ei	Vain rajattu	Jaettu moniagenttisuus	Agenttikohtaiset tiedostot
Kehyksestä riippuvuus	Ei lainkaan (mikä tahansa MCP-asiakas)	Ei lainkaan	Korkea (pakko käyttää Lettaa)	Itsenäinen	Ei lainkaan	Proxy edessä joka mallikutsussa	Ei lainkaan	Oracle Database	Ei lainkaan	Agenttikohtainen formaatti
Ulkoiset riippuvuudet	Ei mitään (SQLite + iii-engine)	Qdrant / pgvector	Postgres + vektoritietokanta	Useita	Hallittu pilvi	Docker-pino (Core + Hub + Proxy)	Vektorivarasto	Oracle AI Database	Ei mitään	Ei mitään
Muistin elinkaari	4-tasoinen konsolidointi + vanheneminen + automaattinen unohtaminen	Passiivinen poiminta	Agentin hallinnoima	Manuaalinen	Automaattinen unohtaminen	Manuaalinen katselmointi; automaattireititys kehitteillä	Ei mitään	Ei ilmoitettu	Vanheneminen + konsolidointi	Manuaalinen karsinta
Tokentehokkuus	~1 900 tokenia/istunto (10 $/vuosi)	Vaihtelee integraation mukaan	Ydinmuisti kontekstissa	Vaihtelee	Pilvihinnoittelu	Ei ilmoitettu	Ei tokenbudjettia	LLM-pohjainen (vaihtelee)	Vaihtelee	22K+ tokenia 240 havainnolla
Reaaliaikainen katseluohjelma	Kyllä (portti 3113)	Pilvikojelauta	Pilvikojelauta	Web-käyttöliittymä	Pilvikojelauta	Hub-web-käyttöliittymä	Ei	Ei	Ei	Ei
Itseisännöity	Kyllä (oletus)	Valinnainen	Valinnainen	Kyllä	Ei (vain pilvi)	Kyllä (Docker)	Kyllä	Kyllä (Oracle-tietokanta)	Kyllä	Kyllä

_{Benchmark-huomautus: vain agentmemoryn R@5 on omaa mitattua tulostamme (LongMemEval-S, toistettavissa tiedostosta benchmark/COMPARISON.md). mem0- ja Letta-luvut ovat niiden julkaisemia LoCoMo-lukuja (eri aineisto); MemPalace-, supermemory-, TencentDB (PersonaMem) - ja oracleagentmemory-luvut ovat valmistajien itse ilmoittamia väitteitä, joita emme ole itsenäisesti toistaneet (oracleagentmemoryn ajo käytti GPT-5.5:tä Oracle AI Databasea vastaan). Esitetty rinnakkain vain suuntaa antavana, ei pää-pää-vertailuna samalla datalla. Tähtimäärät ovat likimääräisiä ja muuttuvat ajan myötä.} **Uudemmat tulokkaat**, hyvä tietää, syvemmin vertailtuna kohdassa [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md): | Järjestelmä | ⭐ | Näkökulma | |--------|---|-------| | Zep / Graphiti | 30K | Temporaalinen tietograafi; vahvimmat julkaistut temporaalikyselytulokset (LongMemEval 63.8%), mutta graafi rakentuu asynkronisesti, jolloin tuoreet faktat voivat viivästyä | | Cognee | 30K | Dokumentista tietograafiksi -tuonti, vain Python, rakennettu rakenteelliseen entiteettipoimintaan istuntotallennuksen sijaan | Mikään näistä ei tallenna automaattisesti koodausagenttien hookeista, toimita paikallista katseluohjelmaa tai toimi avaimetta — yhdistelmä, jonka ympärille agentmemory on rakennettu. ---

Yhteensopivuus: tämä julkaisu kohdistuu `iii-sdk`-versioon 0.22.1 ja kiinnittää iii-engine-version v0.22.1. ### Kokeile 30 sekunnissa ```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` siementää 3 realistista istuntoa (JWT-autentikointi, N+1-kyselyn korjaus, rate limiting) ja ajaa hakuja niitä vastaan. Avaimettomat asennukset poistavat vektorit käytöstä, niin että `mem::search`-avainsanakyselyiden pitäisi osua BM25:n kautta, kun taas `database performance optimization` voi palauttaa nolla tulosta. `smart-search` voi lisäksi palauttaa rakenteellisia graafiosumia, kun graafidataa on olemassa. Saadaksesi semanttisen kyselyn löytämään N+1-korjauksen vektoreiden avulla, aseta `EMBEDDING_PROVIDER=local`, käynnistä uudelleen ja anna ensimmäisen mallilatauksen valmistua. Avaa `http://localhost:3113` nähdäksesi muistin rakentuvan reaaliajassa. ### Vahvista tuore asennus ja uudelleenkäynnistyksen pysyvyys Kun palvelin on käynnissä, vahvista REST, health, katseluohjelma ja iii-pohjaisen ajonaikaisen ympäristön tila: ```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 ``` Käynnistyksen valmiuspaneeli huomioi kaikki neljä porttia: REST/MCP HTTP portissa 3111, iii-streamit portissa 3112, katseluohjelma portissa 3113 ja iii-workerin WebSocket portissa 49134. `status` vahvistaa agentmemoryn terveyden ja aktiivisen tarjoaja-/upotustilan. Tallenna koetin ja vahvista, että se on hakukelpoinen: ```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}' ``` Aja sitten `npx -y @agentmemory/agentmemory@latest stop`, käynnistä kanoninen komento uudelleen Terminaalissa 1, odota `/agentmemory/livez`-vastausta ja toista haku. Koettimen on edelleen tultava takaisin. Jos valitsit mukautetun `--data-dir`-arvon, välitä sama hakemisto uudelleenkäynnistyksessä. ### Päivittäiset komennot Asennus ja käyttöönotto löytyvät yllä kohdasta [Asennus](#install) (ensimmäinen käynnistys opastaa sinut läpi sen). Päivittäin: ```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 ``` ### Istunnon toisto Jokainen agentmemoryn tallentama istunto on toistettavissa. Avaa katseluohjelma, valitse **Replay**-välilehti ja selaa aikajanaa: kehotteet, työkalukutsut, työkalujen tulokset ja vastaukset renderöityvät erillisinä tapahtumina toisto/tauko-painikkeella, nopeudensäädöllä (0.5x–4x) ja pikanäppäimillä (välilyönti vaihtaa, nuolet askeltavat). Tuodaksesi vanhempia Claude Coden JSONL-transkriptioita: ```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 ``` Tuodut istunnot näkyvät Replay-valitsimessa natiivien istuntojen rinnalla. Konepellin alla kukin merkintä kulkee funktioiden `mem::replay::load`, `mem::replay::sessions` ja `mem::replay::import-jsonl` läpi, ei sivukanavapalvelimia. Jokainen tuotu transkriptio indeksoidään hakua varten, leimataan alkuperäkanavalla `import` ja louhitaan istuntokristalliksi ja opetuksiksi. > **Huomio, jos nojaat `import-jsonl`-komentoon ensisijaisena tallennusreittinä:** Claude Coden `cleanupPeriodDays` (tiedostossa `~/.claude/settings.json`, oletus **30**) poistaa automaattisesti JSONL-transkriptiot, jotka ovat vanhempia kuin tämä ikkuna, kansiosta `~/.claude/projects/`. Jos asennat agentmemoryn tuoreena useita kuukausia vanhan Claude Code -historian päälle, kaikki 30 päivää vanhempi on jo poissa ennen ensimmäistä tuontia. Aja `import-jsonl` cron-ajastettuna, nosta `cleanupPeriodDays`-arvoa korkeammaksi, tai kytke automaattitallennushookit (oletusarvoinen plugin-asennusreitti), jotta jokainen vuoro päätyy agentmemoryyn istunnon ollessa käynnissä ja JSONL-siivous lakkaa merkitsemästä. ### Päivitys / ylläpito Käytä ylläpitokomentoa, kun haluat tarkoituksella päivittää paikallisen ajonaikaisen ympäristösi: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` Varoitus: tämä komento muuttaa nykyistä työtilaa/ajonaikaista ympäristöä. Se voi päivittää JavaScript-riippuvuuksia ja hakea kiinnitetyn `iiidev/iii:0.22.1`-Docker-imagen. Se ei koskaan asenna kiinnittämätöntä tai uudempaa iii-moottoria. Toteutuksen yksityiskohdat löytyvät tiedostosta `src/cli.ts` (katso `runUpgrade` alueen `src/cli.ts:544-595` kohdalla). ### Claude Code (yksi lohko, liitä se) ```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 ilman pluginin asennusta (itsenäinen MCP-reitti) Jos kytket agentmemoryn MCP-palvelimen tiedoston `~/.claude.json` kautta suoraan sen sijaan, että käyttäisit `/plugin install`-komentoa, Claude Code ei koskaan ratkaise muuttujaa `${CLAUDE_PLUGIN_ROOT}`, ja sinun on osoitettava hook-skriptit absoluuttisiin polkuihin tiedostossa `~/.claude/settings.json`. Nämä polut sisältävät tyypillisesti agentmemoryn versionumeron (esim. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), niin että seuraava päivitys hajottaa hiljaisesti kaikki hookit. Kiertotapa: ```bash agentmemory connect claude-code --with-hooks ``` Tämä yhdistää samat hook-komennot tiedostoon `~/.claude/settings.json` absoluuttisilla poluilla, jotka osoittavat asennetun `@agentmemory/agentmemory`-paketin mukana tulevaan `plugin/`-hakemistoon. Aja komento uudelleen agentmemoryn päivityksen jälkeen päivittääksesi polut. Käyttäjän omat merkinnät samassa tiedostossa säilyvät; vain aiemmat agentmemory-merkinnät korvataan. `/plugin install`-reitti pysyy suositeltuna lähestymistapana. Etä- tai suojattuja käyttöönottoja varten käynnistä Claude Code `AGENTMEMORY_URL`- ja `AGENTMEMORY_SECRET`-muuttujat asetettuina. Plugin välittää molemmat arvot sen mukana tulevalle MCP-palvelimelle; kun `AGENTMEMORY_URL` on tyhjä, MCP-shim käyttää osoitetta `http://localhost:3111`. ### Codex CLI (Codexin plugin-alusta) ```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-plugin toimitetaan samasta `plugin/`-hakemistosta kuin Claude Code -plugin. Se rekisteröi: - Mukana tuleva stdio MCP -silta käynnissä olevaan daemoniin, ilman npm-latausta tai fallback-varastoa. Katso [paikallinen Codex-opas](../docs/plugins/codex-local.md) testataksesi julkaisematonta buildia. - 6 elinkaarihookia: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 9 kutsuttavaa taitoa: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 viitetaitoa, jotka agentti lataa tarpeen mukaan (muistikuri, MCP-työkalut, REST-rajapinta, asetukset, agentit, hookit, arkkitehtuuri ja taitojen kirjoittamisen opas) Codexin hook-moottori injektoi `CLAUDE_PLUGIN_ROOT`-muuttujan hook-aliprosesseihin (ks. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), niin että samat hook-skriptit toimivat molemmissa isännissä päällekkäisyyttä aiheuttamatta. Subagent-/SessionEnd-/Notification-/TaskCompleted-/PostToolUseFailure-tapahtumat ovat vain Claude Codelle, eikä niitä rekisteröidä Codexille. #### Codex-hookit: luottamus ja yhteensopivuus Natiivi plugin-hookien välitys on vahvistettu Codex CLI -versiolla 0.150.1. Luota plugin-hookeihin ennen kuin odotat tallennusta. Desktop-käytös riippuu sen mukana tulevasta ajonaikaisesta ympäristöstä; tarkista `/hooks` ja vahvista tallennettu tapahtuma ennen kuin otat kiertotavan käyttöön. Jos isäntäsi vaatii globaaleja hookeja, peilaa komennot tiedostoon `~/.codex/hooks.json`. Kun MCP on jo kytketty, nykyinen sovitin tarvitsee `--force`-valitsimen päästäkseen hook-asennukseen: ```bash agentmemory connect codex --with-hooks --force ``` Tämä yhdistää globaalit hookit ja kirjoittaa agentmemory MCP -merkinnän uudelleen säilyttäen muut merkinnät. Tarkista mahdolliset mukautetut agentmemoryn päätepisteasetukset ennen `--force`-valitsimen käyttöä. Aja uudelleen päivityksen jälkeen päivittääksesi skriptien polut. Ota käyttöön natiivit plugin-hookit tai globaalit kopiot kaksinkertaisen tallennuksen välttämiseksi. ### GitHub Copilot CLI VS Coden agenttitilaa varten käytä [Copilotin MCP- ja automaattitallennusopasta](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-sovitin ei määritä VS Codea. ```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` yhdistää `mcpServers.agentmemory`-merkinnän tiedostoon `~/.copilot/mcp-config.json` (tai `$COPILOT_HOME/mcp-config.json`, kun `COPILOT_HOME` on asetettu) ja säilyttää olemassa olevat palvelimet. Natiivilla Windowsilla tämä on ainoa automatisoitu `connect`-sovitin; määritä kaikki muut natiivit Windows-agentit käsin. WSL `connect` on soveltuva vain, kun kohdeagentti on asennettu samaan WSL-ympäristöön. Copilot ottaa MCP-palvelimen käyttöön seuraavalla käynnistyksellä tai `/mcp`-komennon jälkeen. Asenna myös plugin, kun haluat täyden hook-/taito-kokemuksen.

OpenClaw (liitä tämä kehote)

```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`. ``` Täysi opas: [`integrations/openclaw/`](../integrations/openclaw/)

Hermes Agent (liitä tämä kehote)

```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. ``` Täysi opas: [`integrations/hermes/`](../integrations/hermes/)

### Muut agentit Käynnistä muistipalvelin: `npx -y @agentmemory/agentmemory@latest` #### Natiivit taidot komennolla `npx skills add` (50+ agenttia) agentmemory toimittaa 17 taitoa Claude-Code-tyylisessä `/SKILL.md`-formaatissa: 9 kutsuttavaa toimintotaitoa (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) ja 8 viitetaitoa, jotka agentti lataa tarpeen mukaan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Viitetaidot kuljettavat lähdekoodista generoituja datataulukoita, niin ne eivät koskaan ajaudu pois synkasta. vercel-labsin [`skills`](https://npmjs.com/package/skills)-CLI asentaa ne automaattisesti kutsuvan agentin natiiviin taitohakemistoon yli 50 agentin yli (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf ja monet muut): ```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 ``` Tämä on **täydentävä** komennolle `agentmemory connect `: - `agentmemory connect ` kirjoittaa MCP-palvelimen asetukset, jotta työkalut ovat käytettävissä. - `npx skills add rohitg00/agentmemory` asentaa taidot, jotta agentti tietää, milloin kutsua niitä. Niille harvoille agenteille, joita skills-CLI ei vielä kata (Zed v1.3.x ja vanhemmat), pudota 17 SKILL.md-tiedostoa agentin natiiviin taitohakemistoon itse; sama formaatti toimii kaikkialla. #### Standardi MCP-lohko agentmemory-merkintä on **sama MCP-palvelinlohko** jokaisessa isännässä, joka käyttää `mcpServers`-muotoa (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}" } } ``` **Yhdistä tämä merkintä olemassa olevaan `mcpServers`-objektiin** isännän asetustiedostossa; älä korvaa tiedostoa. Jos tiedostossa on jo muita palvelimia, lisää `agentmemory` niiden viereen toisena avaimena `mcpServers`-objektin sisällä. Jos `mcpServers` puuttuu kokonaan, liitä lohko rakenteen `{ "mcpServers": { ... } }` sisään. `${VAR}`-paikkamerkit perivät `AGENTMEMORY_URL`/`AGENTMEMORY_SECRET`-arvot shellistä MCP-palvelimen käynnistyshetkellä; asettamattomat muuttujat välittävät tyhjiä merkkijonoja, ja shim palaa osoitteeseen `http://localhost:3111`. Yksi kytketty merkintä kattaa molemmat: paikallisen ja etäisen (k8s / reverse-proxyn takana olevan) käyttöönoton. | Agentti | Asetustiedosto | Huomautuksia | |---|---|---| | **Cursor (vain MCP)** | `~/.cursor/mcp.json` | Yhdistä `mcpServers`-objektiin, tai `agentmemory connect cursor`. Yhden klikkauksen deeplink saatavilla myös sivustolla. | | **Cursor (täysi plugin)** | `.cursor-plugin/` | Cursor Marketplace -listaus (hakemus katselmoinnissa) tai Cursor Settings → Plugins → paikallinen checkout. Rekisteröi 7 automaattitallennushookia (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 taitoa + MCP-palvelimen, ja `AGENTMEMORY_URL`/`AGENTMEMORY_SECRET` hallitaan Cursorin plugin-kojelaudalla. Toimii Cursor IDE:ssä ja `cursor-agent`-CLI:ssä; CLI:n print-tilan kehotteet täydennetään jälkikäteen istunnon transkriptiosta istunnon päättyessä. | | **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Yhdistä `mcpServers`-objektiin. Käynnistä Claude Desktop uudelleen muokkauksen jälkeen. | | **Cline / Roo Code / Kilo Code** | Clinen MCP-asetukset (Settings-käyttöliittymä → MCP Servers → Edit) | Sama `mcpServers`-lohko. | | **Devin CLI (MCP + hookit)** | `~/.config/devin/config.json` | `agentmemory connect devin` yhdistää MCP-merkinnän; `--with-hooks` lisää kuusi natiivia automaattitallennushookia (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) Devinin pienaakkosisilla työkalusovittimilla. Vahvista komennolla `devin mcp list` ja `/hooks` devinin sisällä. | | **Devin CLI (täysi plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` checkoutista rekisteröi kaikki 17 taitoa `/agentmemory:`-pikakomentoina sekä MCP-palvelimen. Devinin plugin-hookit eivät voi laukaista `SessionStart`/`SessionEnd`-tapahtumia, niin yhdistä se komentoon `connect devin --with-hooks` täyden istuntotallennuksen saamiseksi. | | **Devin (pilvi)** | Settings → Connections → MCP servers | Lisää mukautettu MCP (STDIO): komento `npx`, argumentit `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` osoittamassa verkon tavoittamaan agentmemory-käyttöönottoon, plus `AGENTMEMORY_SECRET` (pilvi-istunnot eivät tavoita localhostia — katso [`deploy/`](../deploy/)). Tallenna salaisuus Devin Secretsiin, käytä sitten "Test listing tools" -toimintoa vahvistaaksesi, että kaikki 54 työkalua näkyvät. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (yhdistää automaattisesti). | | **GitHub Copilot CLI (vain MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` yhdistää `mcpServers.agentmemory`; Copilot ottaa sen käyttöön seuraavalla käynnistyksellä tai `/mcp`-komennolla. | | **GitHub Copilot CLI (täysi plugin)** | Copilot-pluginin asennus | `copilot plugin install rohitg00/agentmemory:plugin` GitHub-alikansion pluginille. | | **OpenClaw** | OpenClawin MCP-asetukset | Sama `mcpServers`-lohko. Syvemmälle: `openclaw plugins install ./integrations/openclaw` ottaa OpenClawin muistipaikan haltuun (vaihtaa automaattisesti `memory-core`:sta); aseta `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, tai tallennus estyy hiljaisesti. Katso [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (vain MCP)** | `.codex/config.toml` | TOML-muoto: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, tai lisää `[mcp_servers.agentmemory]` käsin. | | **Codex CLI (täysi plugin)** | Codexin plugin-markkinapaikka | `codex plugin marketplace add rohitg00/agentmemory`, sitten `codex plugin add agentmemory@agentmemory`. Rekisteröi MCP + 6 elinkaarihookia + 17 taitoa. Luota hookeihin ja varmista tallennus isännässäsi; katso [Codexin asennus ja validointi](../docs/plugins/codex-local.md). | | **OpenCode (vain MCP)** | `opencode.json` | Eri muoto: ylätason `mcp`-avain, komento taulukkona: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (täysi plugin)** | `plugin/opencode/` | 22 automaattitallennushookia kattaen istunnon elinkaaren, viestit, työkalut ja virheet. Projektiattribuutio on istuntokohtainen, niin yksi OpenCode-prosessi, joka kattaa useita repositorioita, tallentaa jokaisen istunnon oman projektinsa alle. Kaksi pikakomentoa (`/recall`, `/remember`). Kopioi `plugin/opencode/` OpenCode-työtilaasi ja lisää plugin-merkintä tiedostoon `opencode.json`. Katso [`plugin/opencode/README.md`](../plugin/opencode/README.md) täydelle hook-taulukolle + puuteanalyysille. | | **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` asentaa mukana tulevan laajennuksen pi:n automaattisen tunnistuksen hakemistoon (palautus agentin käynnistyessä, tallennus agentin päättyessä, `memory_search`/`memory_save`/`memory_health`-työkalut, `/agentmemory-status`). `/reload` käynnissä olevassa pi:ssä ottaa sen käyttöön. [`integrations/pi`](../integrations/pi/) on myös pi-paketti (`pi install ./integrations/pi` checkoutista). | | **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` antaa 6-hookisen muistitarjoajan (esihaku, vuoron tallennus, istunnon päättyminen, esipakkaus, MEMORY.md-peilaus, system prompt -lohko). Vahvista komennoilla `hermes plugins doctor` ja `hermes memory status`. Katso [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` kirjoittaa standardin `mcpServers`-lohkon. Hook-hyötykuorma on kenttätasolla yhteensopiva Claude Coden kanssa, niin olemassa olevat 12-hookin skriptit toimivat muokkaamatta; kytke ne `hooks`-osiossa samassa `settings.json`-tiedostossa. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` asentaa MCP:n ja tallennushookit jaettuun mukautushakemistoon. Katso [Antigravityn asennus ja rajoitukset](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` käyttää samaa MCP- ja hook-määritystä kuin nykyiset IDE-versiot. Olemassa olevat asennukset tulisi päivittää `--force`-valitsimella; katso [päivitysohjeet](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` kirjoittaa käyttäjätason asetukset. Työtilakohtaiset ylikirjoitukset menevät tiedostoon `.kiro/settings/mcp.json` koodisi vierelle. | | **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` kirjoittaa standardin `mcpServers`-lohkon. Warp myös tunnistaa automaattisesti taidot kansiosta `.claude/skills/`; kun Claude Code -plugin on asennettu, 8 agentmemory-taitoa (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) näkyvät natiivisti Warpin pikakomentopaletissa. | | **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` kirjoittaa standardin `mcpServers`-lohkon. VS Code -laajennuksen käyttäjät: liitä sama lohko Cline Settings → MCP Servers → Edit JSON -kautta. | | **Continue.dev** | `~/.continue/config.yaml` (suositeltu) tai `config.json` (vanha) | `agentmemory connect continue` luo tiedoston `config.yaml` tyhjästä, kun kumpaakaan ei ole, tai muokkaa olemassa olevaa `config.json`-tiedostoa. **Jos sinulla on jo `config.yaml`**, sovitin tulostaa tarkan lohkon liitettäväksi `mcpServers:`-kohtaan; se ei hiljaa uudelleenkirjoita yamliasi, koska kommenttien ja ankkureiden turvallinen säilyttäminen vaatisi YAML-jäsentimen, jota paketti ei toimita. Continue käyttää taulukkomuotoa (ei objektia) `mcpServers`-kentälle. | | **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` kirjoittaa avaimen `context_servers` alle (Zedin avain, EI `mcpServers`). Etä-MCP-palvelimet voidaan kytkeä myös muodolla `{"url": "..."}`. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` kirjoittaa standardin `mcpServers`-lohkon. Projektikohtaiset ylikirjoitukset menevät tiedostoon `/.factory/mcp.json`. Välitä `--with-hooks` natiivia automaattitallennusta varten. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` lisää `@deepseek-ai/dsh-mcp-client`-rivin kotihakemistotason patch-kerrokseen, jonka joka Harness-profiili lataa; työkalut rekisteröityvät muodossa `mcp__agentmemory__*`. Välitä `--with-hooks` kytkeäksesi myös automaattitallennuksen: mukana tulevat Claude Code -hook-skriptit kulkevat Harnessin ensiosapuolen `@deepseek-ai/dsh-hooks-claude-code`-sillan läpi (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) manifestin kautta, joka kirjoitetaan tiedostoon `$DSH_HOME/agentmemory.hooks.json`. Oletusarvo on `~/.dsh`, kun `DSH_HOME` on asettamatta. | | **Goose** | Goosen MCP-asetuskäyttöliittymä | Sama `mcpServers`-lohko; käytä `goose configure` → Add Extension → MCP. Suora YAML-muokkaus polussa `~/.config/goose/config.yaml` on tuettu, mutta skeema käyttää `extensions:` + `cmd` (ei `mcpServers:` + `command`). | | **Aider** | ei saatavilla | Puhu suoraan REST-rajapinnalle: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. | | **Mikä tahansa agentti (32+)** | ei saatavilla | `npx skillkit install agentmemory` tunnistaa isännän automaattisesti ja yhdistää. | **Hiekkalaatikoidut MCP-asiakkaat** (Flatpak / Snap / rajoittavat kontit), jotka eivät tavoita isännän `localhost`-osoitetta: aseta lisäksi `"AGENTMEMORY_FORCE_PROXY": "1"` `env`-lohkoon, ja osoita `AGENTMEMORY_URL` reitille, jonka hiekkalaatikko oikeasti tavoittaa (esim. LAN-IP-osoitteesi). ### Ohjelmallinen pääsy (Python / Rust / Node) agentmemory rekisteröi sen ydintoiminnot iii-funktioina (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Mikä tahansa kieli, jolla on iii-SDK, voi kutsua niitä suoraan osoitteen `ws://localhost:49134` kautta, ei erillistä REST-asiakasta per kieli. ```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"}, }) ``` Toimiva esimerkki: [`examples/python/`](../examples/python/) (pika-aloitus + havainnointi-/palautusvirta). REST portissa `:3111` pysyy saatavilla isännille, joilla ei ole iii-ajonaikaista ympäristöä. ### Lähdekoodista ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` Tämä käynnistää agentmemoryn paikallisella `iii-engine`-moottorilla, jos kiinnitetty binääri on jo asennettu, tai käyttää Docker Composea, kun se on valittu. REST, streamit ja katseluohjelma sitoutuvat oletuksena osoitteeseen `127.0.0.1`. Automaattinen macOS/Linux-binääripolku vaatii `curl`:n, POSIX-yhteensopivan `sh`:n ja `tar`:n. Asenna `iii-engine` käsin. **agentmemory kiinnittää tällä hetkellä `iii-engine`-versioon `v0.22.1`**, samaan julkaisuun kuin sen `iii-sdk`-riippuvuus; worker puhuu kyseisen moottorin lankaprotokollaa, ja 0.20.0 järjesti SDK-pinnan uudelleen, niin molemmat liikkuvat yhdessä agentmemoryn julkaisuissa. Ylikirjoita arvolla `AGENTMEMORY_III_VERSION=`, jos ajat omaa moottoriasi ja tiedät, että se täsmää. - **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:** vaihda `aarch64-apple-darwin` tilalle `x86_64-apple-darwin` - **Linux x64:** vaihda tilalle `x86_64-unknown-linux-gnu` - **Linux arm64:** vaihda tilalle `aarch64-unknown-linux-gnu` - **Windows:** lataa `iii-x86_64-pc-windows-msvc.zip` osoitteesta [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) ja pura `iii.exe` polkuun `%USERPROFILE%\.agentmemory\bin\iii.exe` Joka arkistolla on vastaava `.sha256`-tiedosto julkaisusivulla; kun vaihdat alustaa, käytä kyseisen tiedoston tiivistettä yllä olevassa tarkistuksessa (Windowsilla: `Get-FileHash`). `npx @agentmemory/agentmemory`-komennon automaattinen asentaja kiinnittää näihin tiivisteisiin ja hylkää arkiston, joka ei täsmää. Tai käytä Dockeria (mukana tuleva `docker-compose.yml` hakee imagen `iiidev/iii:0.22.1`). Täysi dokumentaatio: [iii.dev/docs](https://iii.dev/docs). ### Windows agentmemory toimii Windows 10/11:llä, mutta Node.js-paketti yksinään ei riitä; tarvitset myös kiinnitetyn iii-engine v0.22.1 -ajonaikaisen ympäristön taustaprosessina. CLI ei pura Windows-ZIP-pakettia automaattisesti, niin natiivien Windows-käyttäjien on asennettava `iii.exe` käsin, käytettävä WSL2:ta tai valittava Docker Desktop. Natiivi Windows-automaattinen MCP-kytkentä tukee vain komentoa `agentmemory connect copilot-cli`. Claude Codea, Codexia, Cursoria ja kaikkia muita natiiveja Windows-agentteja varten kopioi manuaalinen MCP-lohko kohdasta [Muut agentit](#other-agents) kyseisen agentin Windows-asetuksiin. `connect`-komennon ajaminen WSL:ssä on sopivaa vain, kun kohdeagentti on asennettu myös samaan WSL-ympäristöön; se ei muokkaa Windows-isännän agentin asetuksia. **Vaihtoehto A: valmiiksi käännetty Windows-binääri (suositeltu)** ```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 ``` **Vaihtoehto 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 ``` **Vaihtoehto C: vain itsenäinen MCP (ei moottoria).** Jos tarvitset vain MCP-työkalut agentillesi ja et tarvitse REST-rajapintaa, katseluohjelmaa tai cron-tehtäviä, ohita moottori kokonaan: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or via the shim package: npx -y @agentmemory/mcp ``` **Diagnostiikka Windowsilla:** jos `npx -y @agentmemory/agentmemory@latest` epäonnistuu, aja se uudelleen lipulla `--verbose` nähdäksesi moottorin todellisen stderr-tulosteen. Yleiset vikatilat: | Oire | Korjaus | |---|---| | `The engine process started but the REST API never responded.` | Vahvista, että kaikki neljä johdettua porttia ovat vapaat, varmista, että kiinnitetty `iii.exe` pysyi käynnissä, ja aja sitten uudelleen lipulla `--verbose` ja tarkista tallennettu moottorin stderr | | `Could not start iii-engine` | Ei `iii.exe`:tä eikä Dockeria ole asennettu. Katso Vaihtoehto A tai B yllä | | Porttiristiriita | `netstat -ano \| findstr :3111` nähdäksesi, mihin on sidottu, sammuta se tai käytä lippua `--port ` | | Docker-varajärjestelmä ohitetaan, vaikka Docker on asennettu | Varmista, että Docker Desktop on oikeasti käynnissä (järjestelmäpalkin kuvake) | > Huomio: iii-**moottori** on valmiiksi käännetty binääri, ei cargo-pakki, niin sitä ei kannata yrittää asentaa komennolla `cargo install`. (iii-**SDK:t** on julkaistu crates.io:ssa, npm:ssä ja PyPI:ssä, mutta agentmemory ei tarvitse niitä.) Tuetut moottorin asennustavat on kaikki kiinnitetty versioon v0.22.1: yllä oleva valmiiksi käännetty binääri, agentmemoryn macOS/Linux-automaattiasennusreitti (`curl`, POSIX `sh` ja `tar` vaadittu) ja Docker-image `iiidev/iii:0.22.1`. Paljas ylävirran `install.sh | sh` asentaa uusimman moottorin, jota agentmemory ei tue. Käytä komentoa `npx -y @agentmemory/agentmemory@latest`; macOS/Linuxilla se hakee kiinnitetyn moottorin polkuun `~/.agentmemory/bin`. ---

Käyttöönotto

Yhden klikkauksen mallipohjat hallinnoiduille isännille. Joka pohja toimittaa itsenäisen Dockerfile-tiedoston, joka hakee paketin `@agentmemory/agentmemory` npm:stä ja kopioi iii-moottorin binäärin viralliselta `iiidev/iii`-Docker Hub -imagelta; valmiiksi rakennettua agentmemory-imagea ei tarvita. Pysyvä tallennustila liitetään pisteeseen `/data`; ensimmäisen käynnistyksen entrypoint korvaa npm:n mukana tulevan iii-asetuksen (joka sitoutuu `127.0.0.1`-osoitteeseen) käyttöönottoa varten viritetyllä asetuksella, joka sitoutuu `0.0.0.0`-osoitteeseen ja käyttää absoluuttisia `/data`-polkuja, generoi HMAC-salaisuuden, ja luopuu sitten oikeuksista `root`-käyttäjästä `node`-käyttäjään `gosu`:n kautta ennen agentmemory-CLI:n exec-komentoa.

Renderin yhden klikkauksen käyttöönottopainike vaatii `render.yaml`-tiedoston repositorion juuressa, jonka pidämme tarkoituksella siistinä. Käytä [`deploy/render/`](.././deploy/render/README.md)-kansiossa dokumentoitua Render Blueprint -virtaa osoittaaksesi repositorion sisäiseen blueprintiin käsin. Täydet asetustiedot (HMAC-tallennus, katseluohjelman SSH-tunneli, kierto, varmuuskopiointi, kustannuslattia) löytyvät kansiosta [`deploy/`](.././deploy/README.md): - [`deploy/fly`](.././deploy/fly/README.md): yksi kone, asetuksella `auto_stop_machines = "stop"`; halvin joutokäynnillä. - [`deploy/railway`](.././deploy/railway/README.md): Hobby-tason kiinteä hinta, volyymi kojelaudassa. - [`deploy/render`](.././deploy/render/README.md): Blueprint-virta, automaattiset levykuvat maksullisilla tasoilla. - [`deploy/coolify`](.././deploy/coolify/README.md): itseisännöity omalla VPS:lläsi [Coolifyn](https://coolify.io/self-hosted) kautta; sama Docker Compose -pino, omistat itse isännän ja datan. Vain portti `3111` julkaistaan. Katseluohjelma portissa `3113` pysyy sidottuna loopbackiin kontin sisällä; joka mallipohjan README dokumentoi SSH-tunnelimallin sen saavuttamiseksi. ---

Jokainen koodausagentti unohtaa kaiken, kun istunto päättyy, ja joka uusi istunto alkaa sinun selittäessä pinoasi uudelleen. agentmemory toimii taustalla ja poistaa tämän vaiheen. ```text Session 1: "Add auth to the API" Agent writes code, runs tests, fixes bugs agentmemory silently captures every tool use Session ends -> observations compressed into structured memory Session 2: "Now add rate limiting" Agent already knows: - Auth uses JWT middleware in src/middleware/auth.ts - Tests in test/auth.test.ts cover token validation - You chose jose over jsonwebtoken for Edge compatibility Zero re-explaining. Starts working immediately. ``` ### vs. sisäänrakennettu agenttimuisti Jokainen tekoälypohjainen koodausagentti toimitetaan sisäänrakennetulla muistilla: Claude Codella on `MEMORY.md`, Cursorilla on notepadit, Clinellä on memory bank. Nämä toimivat kuin tarralaput. agentmemory on hakukelpoinen tietokanta tarralappujen takana. | | Sisäänrakennettu (CLAUDE.md) | agentmemory | |---|---|---| | Skaala | 200 rivin katto | Rajattomasti | | Haku | Lataa kaiken kontekstiin | BM25 + vektori + graafi (vain top-K) | | Tokenkustannus | 22K+ 240 havainnolla | ~1 900 tokenia (92 % vähemmän) | | Agenttien välillä | Agenttikohtaiset tiedostot | MCP + REST (mikä tahansa agentti) | | Koordinointi | Ei mitään | Leaset, signaalit, toiminnot, rutiinit | | Havainnoitavuus | Lue tiedostoja käsin | Reaaliaikainen katseluohjelma portissa :3113 | ---

### Muistiputki ```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-tasoinen muistin konsolidointi Mallinnettu sen mukaan, miten ihmisen aivot käsittelevät muistia, mukaan lukien unen aikainen konsolidointi. | Taso | Mitä | Analogia | |------|------|---------| | **Työ-** | Raa'at havainnot työkalujen käytöstä | Lyhytkestoinen muisti | | **Episodinen** | Pakatut istuntoyhteenvedot | "Mitä tapahtui" | | **Semanttinen** | Poimitut faktat ja mallit | "Mitä tiedän" | | **Proseduraalinen** | Työnkulut ja päätösmallit | "Miten se tehdään" | Muistot vanhenevat ajan myötä (Ebbinghausin käyrä). Usein käytetyt muistot vahvistuvat. Vanhentuneet muistot poistuvat automaattisesti. Ristiriidat havaitaan ja ratkaistaan. ### Mitä tallennetaan | Hook | Tallentaa | |------|----------| | `SessionStart` | Projektin polku, istunnon ID | | `UserPromptSubmit` | Käyttäjän kehotteet (yksityisyyssuodatettu) | | `PreToolUse` | Tiedostonkäyttömallit + rikastettu konteksti | | `PostToolUse` | Työkalun nimi, syöte, tuloste | | `PostToolUseFailure` | Virhekonteksti | | `PreCompact` | Syöttää muistin uudelleen ennen tiivistämistä | | `SubagentStart/Stop` | Aliagentin elinkaari | | `Stop` | Istunnon loppuyhteenveto | | `SessionEnd` | Istunnon valmistumismerkki | ### Keskeiset ominaisuudet | Ominaisuus | Kuvaus | |---|---| | **Automaattinen tallennus** | Joka työkalun käyttö tallennetaan hookien kautta, ei manuaalista työtä | | **Semanttinen haku** | BM25 + vektori + tietograafi RRF-fuusiolla | | **Muistin kehitys** | Versiointi, korvaaminen, suhdegraafit | | **Palautushygienia** | Korvatut muistiversiot poistuvat hakuindekseistä; versioketju KV:ssä säilyttää täyden historian | | **Läheisten kaksoiskappaleiden vihjeet** | Tallennukset ilmoittavat ohjeellisen `similarTo`-osuman, kun uusi sisältö muistuttaa läheisesti olemassa olevaa muistoa | | **Agenttikohtainen rajaus** | `agentId` kulkee tallennuksen ja palautuksen läpi REST:ssä, MCP:ssä ja hakuindeksissä, jaetussa tai eristetyssä tilassa | | **Kirjoitushetken alkuperä** | Joka havainto ja muisto kantaa muuttumattoman alkuperäkanavan (käyttäjä, agentti, työkalu, tuonti tai jaettu), leimattuna kaappauksen, tallennuksen ja tuonnin hetkellä | | **Automaattinen unohtaminen** | TTL-vanheneminen, ristiriitojen havaitseminen, tärkeyspohjainen poisto | | **Yksityisyys ensin** | API-avaimet, salaisuudet, ``-tagit riisutaan ennen tallennusta | | **Itseparantuminen** | Katkaisija, tarjoajan varaketju, terveyden valvonta | | **Claude-silta** | Kaksisuuntainen synkronointi MEMORY.md:n kanssa | | **Tietograafi** | Entiteettipoiminta + BFS-läpikäynti | | **Tiimimuisti** | Nimiavaruudella eroteltu jaettu + yksityinen tiimin jäsenten kesken | | **Viittausten jäljitettävyys** | Jäljitä mikä tahansa muisto takaisin lähdehavaintoihin | | **Git-tilannevedokset** | Versioi, palauta ja vertaile muistin tilaa | ---

Kolmoisvirtainen hakutoteutus, joka yhdistää kolme signaalia: | Virta | Mitä se tekee | Milloin | |---|---|---| | **BM25** | Sanavartaloitettu avainsanahaku synonyymilaajennuksella | Aina päällä | | **Vektori** | Kosinin samankaltaisuus tiheiden upotusten yli | Upotustarjoaja määritetty | | **Graafi** | Tietograafin läpikäynti entiteettivastaavuuden kautta | Kyselyssä havaittu entiteetit | Yhdistetty Reciprocal Rank Fusionilla (RRF, k=60) ja istuntokohtaisesti monipuolistettu (enintään 3 tulosta per istunto). Kun vektori-indeksi on täytetty, `mem::search` (`memory_recall`-työkalun takana) käyttää hybridiä BM25 + vektori -luokittelijaa. Ilman upotuksia se käyttää BM25:tä. `smart-search` voi lisäksi yhdistää rakenteellisia graafiosumia, kun graafidataa on olemassa, myös avaimettomassa tilassa. Opetusten palautus käyttää erillistä muistinvaraista BM25-indeksiä sen sijaan, että se skannaisi koko korpuksen jokaisella kyselyllä. Korvatut muistiversiot on suljettu pois jokaisesta palautusreitistä; versioketju säilyttää niiden historian. Vektorit selviävät kaatumisesta tai pakkosammutuksesta. Vektori-indeksi tallennetaan erissä enintään `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`-ajan välein (10 minuuttia). Joka vektori, joka lisätään tai poistetaan tällä välillä, kirjoitetaan myös heti pieneen odottavaan lokiin tilavarastossa, ja seuraava käynnistys toistaa sen kutsumatta upotustarjoajaa. Joka onnistunut tallennus tyhjentää lokin. Dokumentit, joilla ei vielä ole vektoria toiston jälkeen, upotetaan uudelleen taustalla erissä kooltaan `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), kunnes yhtäkään ei jää jäljelle, ja pysäytetty täydennys jatkuu seuraavassa käynnistyksessä. `/agentmemory/status` ja katseluohjelma näyttävät odottavan lokin koon ja täydennyksen tilan. Avaimettomat asennukset eivät kirjoita mitään. BM25 tokenisoi kreikan, kyrilliset kirjaimet, hebrean, arabian ja aksentoidun latinan oletuksena. Kiinan-, japanin- ja koreankielisiä muistoja varten asenna valinnaiset segmentoijat (`npm install @node-rs/jieba tiny-segmenter`) jakaaksesi CJK-jaksot sananlaajuisiksi tokeneiksi; ilman niitä agentmemory lankeaa pehmeästi koko jakson tokenisointiin ja tulostaa kertaluonteisen vihjeen stderriin. ### Upotustarjoajat Avaimettomat asennukset poistavat vektoriupotukset käytöstä: `mem::search` käyttää BM25:tä, kun taas `smart-search` voi myös käyttää olemassa olevaa rakenteellista graafidataa. Saadaksesi käyttöön ilmaiset, laitteella toimivat semanttiset upotukset, lisää tämä tiedostoon `~/.agentmemory/.env` ja käynnistä agentmemory uudelleen: ```env EMBEDDING_PROVIDER=local ``` Normaali npm-asennus sisältää valinnaisen `@huggingface/transformers`-ajonaikaisen ympäristön. Ensimmäinen upotuspyyntö lataa mallin `Xenova/all-MiniLM-L6-v2`, niin se vaatii verkkoyhteyden ja voi kestää pidempään; seuraava päättely toimii laitteella. Etätarjoajat tunnistetaan automaattisesti niiden avaimista, ellei `EMBEDDING_PROVIDER` ylikirjoita niitä. | Tarjoaja | Malli | Kustannus | Huomautuksia | |---|---|---|---| | **Paikallinen (suositeltu opt-in)** | `all-MiniLM-L6-v2` | Ilmainen | Laitteella ensimmäisen mallilatauksen jälkeen, +8pp palautustarkkuutta vain-BM25:een verrattuna | | Gemini | `gemini-embedding-001` | Ilmainen taso | 100+ kieltä, 768/1536/3072-ulotteinen (MRL), 2048-tokenin syöte. Korvaa `text-embedding-004`:n ([poistettu käytöstä, sammutetaan 14.1.2026](https://ai.google.dev/gemini-api/docs/deprecations)) | | OpenAI | `text-embedding-3-small` | 0,02 $/1M | Korkein laatu | | Voyage AI | `voyage-code-3` | Maksullinen | Optimoitu koodille | | Cohere | `embed-english-v3.0` | Ilmainen kokeilu | Yleiskäyttöinen | | OpenRouter | Mikä tahansa malli | Vaihtelee | Multi-model-proxy | ---

54 työkalua, 6 resurssia, 3 kehotetta ja 17 taitoa. > **MCP-shim vs. täysi palvelin:** julkaistu `@agentmemory/mcp`-paketti on ohut shim. Se paljastaa täyden 54 työkalun pinnan **vain kun se tavoittaa käynnissä olevan agentmemory-palvelimen** `AGENTMEMORY_URL`:n kautta (proxy-tila). Kun palvelinta ei tavoiteta, shim palaa 7 työkalun paikalliseen settiin (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|all`-ympäristömuuttuja on *palvelinpuolen* lippu; sen asettaminen shimin `env`-lohkossa ei vaikuta mihinkään. Jos näet vain 7 työkalua Cursorissa / OpenCodessa / Gemini CLI:ssä, käynnistä `npx -y @agentmemory/agentmemory@latest` (tai Docker-pino) ja aseta `AGENTMEMORY_URL=http://localhost:3111`. ### 54 työkalua Kolme työkalupintaa, pienimmästä suurimpaan: `AGENTMEMORY_TOOLS=core` karsii näkyvyyden 8 olennaisimpaan (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); alla oleva perussetti on rekisterin 14 perustyökalua; oletus (`AGENTMEMORY_TOOLS=all`) paljastaa kaikki 54.

Perustyökalut (14)

| Työkalu | Kuvaus | |------|-------------| | `memory_recall` | Hae menneitä havaintoja | | `memory_compress_file` | Pakkaa markdown-tiedostoja säilyttäen rakenteen | | `memory_save` | Tallenna oivallus, päätös tai malli | | `memory_file_history` | Menneet havainnot tietyistä tiedostoista | | `memory_patterns` | Havaitse toistuvia malleja | | `memory_sessions` | Listaa viimeaikaiset istunnot | | `memory_smart_search` | Hybridi semanttinen + avainsanahaku | | `memory_vision_search` | Hae kuvahavainnoista | | `memory_timeline` | Kronologiset havainnot | | `memory_profile` | Projektiprofiili (käsitteet, tiedostot, mallit) | | `memory_export` | Vie kaikki muistidata | | `memory_relations` | Kysele suhdegraafia | | `memory_commit_lookup` | Git-commitin takana olevat istunnot | | `memory_commits` | Istunnolle tallennetut commitit |

Laajennetut työkalut (yhteensä 54, oletuspinta)

| Työkalu | Kuvaus | |------|-------------| | `memory_patterns` | Havaitse toistuvia malleja | | `memory_timeline` | Kronologiset havainnot | | `memory_relations` | Kysele suhdegraafia | | `memory_graph_query` | Tietograafin läpikäynti | | `memory_consolidate` | Aja 4-tasoinen konsolidointi | | `memory_claude_bridge_sync` | Synkronoi MEMORY.md:n kanssa | | `memory_team_share` | Jaa tiimin jäsenten kanssa | | `memory_team_feed` | Viimeaikaiset jaetut kohteet | | `memory_audit` | Toimintojen auditointijälki | | `memory_governance_delete` | Poista auditointijäljellä | | `memory_snapshot_create` | Git-versioitu tilannevedos | | `memory_action_create` | Luo työkohteita riippuvuuksilla | | `memory_action_update` | Päivitä toiminnon tila | | `memory_frontier` | Esteettömät toiminnot tärkeysjärjestyksessä | | `memory_next` | Yksittäinen tärkein seuraava toiminto | | `memory_lease` | Yksinoikeudelliset toimintoleaset (moniagenttisuus) | | `memory_routine_run` | Instansioi työnkulkurutiineja | | `memory_signal_send` | Agenttien välinen viestintä | | `memory_signal_read` | Lue viestit kuittauksilla | | `memory_checkpoint` | Ulkoiset ehtoportit | | `memory_mesh_sync` | P2P-synkronointi instanssien välillä | | `memory_sentinel_create` | Tapahtumaohjatut vartijat | | `memory_sentinel_trigger` | Laukaise vartijat ulkoisesti | | `memory_sketch_create` | Lyhytikäiset toimintagraafit | | `memory_sketch_promote` | Korota pysyväksi | | `memory_crystallize` | Tiivistä toimintoketjut | | `memory_diagnose` | Terveystarkistukset | | `memory_heal` | Korjaa jumittunut tila automaattisesti | | `memory_facet_tag` | Ulottuvuus:arvo-tagit | | `memory_facet_query` | Kysely facet-tageilla | | `memory_verify` | Jäljitä alkuperä |

### 6 resurssia · 3 kehotetta · 17 taitoa | Tyyppi | Nimi | Kuvaus | |------|------|-------------| | Resurssi | `agentmemory://status` | Terveys, istuntomäärä, muistomäärä | | Resurssi | `agentmemory://project/{name}/profile` | Projektikohtainen tieto | | Resurssi | `agentmemory://project/{name}/recent` | Projektin viimeaikaiset havainnot | | Resurssi | `agentmemory://memories/latest` | 10 viimeisintä aktiivista muistoa | | Resurssi | `agentmemory://graph/stats` | Tietograafin tilastot | | Resurssi | `agentmemory://team/{id}/profile` | Jaettu tiimiprofiili | | Kehote | `recall_context` | Hae + palauta kontekstiviestit | | Kehote | `session_handoff` | Luovutustieto agenttien välillä | | Kehote | `detect_patterns` | Analysoi toistuvia malleja | | Taito | `/recall` | Hae muistista | | Taito | `/remember` | Tallenna pitkäkestoiseen muistiin | | Taito | `/session-history` | Viimeaikaiset istuntoyhteenvedot | | Taito | `/forget` | Poista havaintoja/istuntoja | Taulukko näyttää neljä ydintaitoa. Täysi setti on 9 kutsuttavaa taitoa plus 8 viitetaitoa; katso Natiivit taidot -osio yllä. ### Itsenäinen MCP Aja ilman täyttä palvelinta, mille tahansa MCP-asiakkaalle. Kumpi tahansa näistä toimii: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` Tai lisää agenttisi MCP-asetuksiin: Useimmat agentit (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` Yhdistä `agentmemory`-merkintä isäntäsi olemassa olevaan `mcpServers`-objektiin sen sijaan, että korvaisit tiedoston. Hiekkalaatikoiduille asiakkaille, jotka eivät tavoita isännän `localhost`-osoitetta, lisää `"AGENTMEMORY_FORCE_PROXY": "1"` env-lohkoon ja aseta `AGENTMEMORY_URL` reitille, jonka hiekkalaatikko tavoittaa. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` Kopioi plugin-tiedosto repositoriosta: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

Käynnistyy automaattisesti portissa `3113`. Katseluohjelma lataa yhden tilannevedoksen yhdistyessään (`GET /agentmemory/viewer/snapshot`) ja soveltaa sitten live-streamitapahtumia: uudet muistot, opetukset, havainnot, auditointimerkinnät, graafimuutokset ja terveyspäivitykset ilmestyvät ilman pollausta tai sivun uudelleenlatausta. Ainoat muut pyynnöt ovat toiminnot, joita klikkaat, "lataa lisää" -sivut ja haut. Kun stream katkeaa, katseluohjelma näyttää, kuinka vanhoja sen luvut ovat, yhdistää uudelleen takaisinvedolla ja synkronoi uudelleen yhdestä tilannevedoksesta. - **12 välilehteä neljässä ryhmässä** live-laskureilla, syvälinkeillä (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), pikanäppäimillä ja mobiilivalikolla. - **Muistot:** palvelinpuolen haku, suodattimet projektin, agentin ja tyypin mukaan, yksityiskohtapaneeli versioketjulla ja sanadiffillä, alkuperälinkit, kopiointipainikkeet id:lle, MCP-kutsulle ja curl-komennolle, muokkaus (uusi versio), unohtaminen vahvistuksella, joukkounohtaminen ja JSON-vienti. - **Istunnot:** sisäänrakennettu havaintoaikajana luettavalla työkalusyötteellä ja -tulosteella, suodattimet ja sivutus, sekä muistot ja opetukset, jotka joka istunto tuotti. - **Graafi:** haku, solmun yksityiskohdat suhteilla ja lähteillä, selite, joka ei nojaa vain väriin, ja zoom-säätimet. - **Terveys:** `GET /agentmemory/status`:n live-versio. Joka ongelman mukana tulee sen korjaus, plus tilan taustaosa, indeksin tallennustila, graafin alkuperän tiivistämisen edistyminen ja konsolidointiselitys todellisilla kynnysarvoilla. - **Auditointi, Toiminta, Profiili, Toisto, Opetukset, Toiminnot ja Kristallit** -sivut, joilla kaikilla on tyhjä tila, joka kertoo, mikä osio on, miksi se on tyhjä ja mikä komento täyttää sen, sekä `?`-sanastovihje joka termille ja luvulle. ```bash open http://localhost:3113 ``` Katseluohjelman palvelin sitoutuu oletuksena osoitteeseen `127.0.0.1` ja liittää palvelimen salaisuuden välittäessään pyyntöjä REST-rajapinnalle, niin se ei vaadi asetuksia. REST-rajapinnan tarjoama `/agentmemory/viewer`-päätepiste noudattaa normaaleja bearer-tokenisääntöjä ja ohjaa selaimet, joilla ei ole tokenia, katseluohjelman porttiin. CSP-otsikot käyttävät vastauskohtaista script-noncea ja poistavat käytöstä inline-käsittelijäattribuutit (`script-src-attr 'none'`). ---

Katseluohjelma portissa `:3113` näyttää, mitä agenttisi **muisti**. [iii-konsoli](https://iii.dev/docs/console) näyttää, mitä agenttisi **teki**: joka muistioperaatio OpenTelemetry-jäljityksenä, joka KV-merkintä muokattavana, joka funktio kutsuttavana, joka stream napautettavana. Kaksi ikkunaa samaan muistiin: yksi tuoteksikin, yksi moottoriksikin muotoiltu. Katso `memory_smart_search`-kutsun laukeavan ja näe BM25-skannaus → upotushaku → RRF-fuusio → uudelleenluokittelu vesiputousnäkymänä. Muokkaa jumittunutta konsolidointiajastinta KV-selaimessa. Toista `PostToolUse`-hook muokatulla hyötykuormalla. Pinnaa WebSocket-stream ja katso havaintojen saapuvan live. agentmemory toimittaa tämän ilmaiseksi, koska joka funktiokutsu ja triggeri laukeaa iii:n läpi; ei mitään mukautettua, ei mitään instrumentoitavaa.

Workers-sivu: joka yhdistetty worker, mukaan lukien agentmemory itse, PID:llä, funktiomäärällä, ajonaikaisella ympäristöllä ja viimeisimmällä näkymisajalla.

**Jo asennettu.** Konsoli toimitetaan kiinnitetyn `iii`-moottorin (0.22+) mukana; ei mitään erillistä asennettavaa. Ensimmäinen käynnistys lataa konsolin binäärin moottorin viereen. **Käynnistä agentmemoryn rinnalla:** ```bash agentmemory console ``` Tämä ajaa kiinnitetyn moottorin `iii console`-komennon porteja vastaan, jotka agentmemory ratkaisi (REST, streamit, silta), ja tarjoilee sen yhden portin katseluohjelman yläpuolella, oletuksena `http://localhost:3114`. `--console-port N` valitsee toisen portin; `--port` ja `--instance` valitsevat agentmemory-instanssin samalla tavalla kuin `stop`-komennolle; mikä tahansa muu lippu välitetään läpi, esimerkiksi `--enable-flow` kokeelliselle arkkitehtuurigraafi-sivulle. Sama asia käsin, hyödyllinen kun `agentmemory` ei ole PATH:ssa: ```bash ~/.agentmemory/bin/iii console --port 3114 \ --engine-port 3111 \ --ws-port 3112 \ --bridge-port 49134 ``` **Mitä voit tehdä konsolista:** | Sivu | Käytä tätä | |------|-----------| | **Workers** | Näe joka yhdistetty worker ja sen live-mittarit, mukaan lukien agentmemory-worker itse. | | **Functions** | Kutsu mitä tahansa agentmemoryn funktiota suoraan JSON-hyötykuormalla; kätevä testaamaan `memory.recall`, `memory.consolidate`, `graph.query` kytkemättä asiakasta. | | **Triggers** | Toista HTTP-, cron-, tapahtuma- ja tilatriggereitä: laukaise konsolidointi-cron käsin, yritä HTTP-reittiä uudelleen, lähetä tilamuutos. | | **States** | KV-selain täydellä CRUD:lla istuntoihin, muistipaikkoihin, elinkaariajastimiin ja upotusindeksiin; muokkaa arvoja paikan päällä. | | **Streams** | Live-WebSocket-monitori muistikirjoituksille, hook-tapahtumille ja havaintopäivityksille niiden virratessa iii-streamien läpi. | | **Queues** | Pysyvät jono-aiheet + dead-letter-hallinta. Toista tai hylkää epäonnistuneet upotus-/pakkaustehtävät. | | **Traces** | OpenTelemetry-vesiputous-/liekki-/palvelujaotellut näkymät. Suodata `trace_id`:llä nähdäksesi tarkalleen, mitkä funktiot, tietokantakutsut ja upotuspyynnöt yksi `memory.search` tuotti. | | **Logs** | Rakenteelliset OTEL-lokit suodatettuna ja korreloituna trace-/span-ID:ihin. | | **Config** | Ajonaikainen konfiguraatio: näe tarkalleen, millä workereilla, tarjoajilla ja porteilla moottorisi käy. | | **Flow** | (Valinnainen, `--enable-flow`) Interaktiivinen arkkitehtuurigraafi joka workerista, triggeristä ja streamista. |

Traces: vesiputous-/liekki-/palvelujaottelu joka muistioperaatiolle.

**Jäljitykset ovat jo päällä:** `iii-config.yaml` toimitetaan `iii-observability`-worker käytössä (`exporter: memory`, `sampling_ratio: 0.1`, metriikat + lokit). Ei mitään lisäasetuksia tarvita; sillä hetkellä, kun agentmemory käynnistyy, joka muistioperaatio lähettää rakenteellisen lokin, jonka konsoli voi lukea, ja yksi kymmenestä niistä (`sampling_ratio: 0.1`) lähettää myös trace-spanin. Jos haluat viedä datan Jaegeriin/Honeycombiin/Grafana Tempoon sen sijaan, vaihda `exporter: memory` arvoon `exporter: otlp` ja aseta kerääjän päätepiste iii:n observability-dokumentaation mukaan. > **Huomio:** konsolissa itsessään ei ole pakotettua autentikointia; pidä se sidottuna osoitteeseen `127.0.0.1` (oletus) ja älä koskaan paljasta sitä julkisesti. ---

agentmemory on **jo käynnissä oleva [iii](https://iii.dev)-instanssi**. Kolme primitiiviä (worker, funktio, triggeri) muodostavat ajonaikaisen ympäristön; KV-tila, streamit ja OTEL-jäljitykset tulevat iii-state-, iii-stream- ja iii-observability-workereilta, jotka toimitetaan iii:n mukana. Et asentanut Postgresia, Redistä, Expressiä, pm2:ta tai Prometheusta, koska iii korvaa ne. Se tarkoittaa, että yksi komento lisää laajentaa agentmemoryn kokonaan uudella kyvykkyydellä. ### Laajenna agentmemorya lisäworkereilla Sisäänrakennetut workerit, joita agentmemory tarvitsee, ovat jo tiedostossa `iii-config.yaml` ja käynnistyvät sen mukana: `iii-state` (KV), `iii-queue` (pysyvät uudelleenyritykset tapahtumatilaajille), `iii-pubsub`, `iii-cron`, `iii-stream` ja `iii-observability` (OTEL-jäljitykset, metriikat ja lokit joka funktiolle). Kaikki muu [iii-workerrekisteristä](https://workers.iii.dev) kytkeytyy samaan moottoriin: kopioi `iii-config.yaml` tiedostoon `~/.agentmemory/iii-config.yaml` (CLI suosii tätä tiedostoa mukana tulevan sijaan ja renderöi siihen edelleen portit ja datapolut), lisää merkintä, asenna workerin ajonaikainen ympäristö kerran komennolla `~/.agentmemory/bin/iii update worker`, ja käynnistä agentmemory uudelleen. ```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 | Mitä saat agentmemoryn päälle | |---|---| | [`database`](https://workers.iii.dev/workers/database) | SQL-pohjainen tila-adapteri, kun kasvat ulos muistinvaraisista KV-oletuksista | | [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`:sta tullut koodi ajetaan kertakäyttöisessä VM:ssä, ei shellissäsi | | [`mcp`](https://workers.iii.dev/workers/mcp) | Pystytä lisää MCP-palvelimia agentmemoryn rinnalle, jaa sama moottori | Moottorin 0.22.x-versiossa pidä `iii-`-etuliitteelliset nimet yllä olevilla sisäänrakennetuilla; etuliitteettömät `http`-, `state`-, `queue`-, `pubsub`- ja `cron`-merkinnät ovat itsenäisen rekisterin workerit, joihin agentmemory siirtyy 0.23-migraation mukana. Täysi rekisteri: [workers.iii.dev](https://workers.iii.dev). Joka worker sillä sivulla muodostuu samoista primitiiveistä, joita agentmemory käyttää, ja agentmemory, joka sinulla on jo, on yksi niistä. ### Moottorin asetukset ja sidontaosoite `agentmemory start` lukee moottorin asetukset ensimmäisestä tiedostosta, joka on olemassa: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` nykyisessä hakemistossa, `~/.agentmemory/iii-config.yaml`, sitten mukana tuleva `iii-config.yaml`. Joka käynnistyksellä se renderöi kyseisen tiedoston (datapolut, portit, tilan taustaosa) tiedostoon `~/.agentmemory/data/iii-config.runtime.yaml` ja käynnistää moottorin renderöidyllä kopiolla, niin muokkaa lähdetiedostoa, ei renderöityä. Lähdetiedoston `host:`-arvot säilytetään kirjoitetussa muodossa. Mukana tuleva `iii-config.yaml` sitoutuu tarkoituksella osoitteeseen `127.0.0.1`, ja tämä oletus pätee myös kontin sisällä. Kontissa käynnistetty CLI kuuntelee kontin loopbackia, niin julkaistut portit eivät tavoita mitään. Tarjoillaksesi konteriutuneen CLI:n julkaistujen porttien kautta, aseta `AGENTMEMORY_III_CONFIG` osoittamaan asetukseen, joka sitoutuu osoitteeseen `0.0.0.0`. Pakattu `iii-config.docker.yaml` on yksi tällainen: se sitoo `iii-http`:n, `iii-stream`:n ja moottorin portin osoitteeseen `0.0.0.0` ja tallentaa tilan polkuun `/data`, niin liitä kirjoitettava volyymi siihen. Pidä `AGENTMEMORY_SECRET` asetettuna, ja julkaise vain tarvitsemasi portit, osoitteessa `127.0.0.1` tai luotettavan proxyn takana. Tämän repositorion `docker-compose.yml` ei kulje CLI:n asetushaun läpi: se liittää `iii-config.docker.yaml`:n pisteeseen `/app/config.yaml`, ja `iii-engine`-kontti käynnistyy lipulla `--config /app/config.yaml`. Yhden klikkauksen [käyttöönottomallipohjat](../deploy/) kirjoittavat omat `0.0.0.0`-asetuksensa niiden entrypointeihin. ### Tallennuksen taustaosa: file (oletus) vs. redis `iii-state` ja `iii-stream` käyttävät oletuksena iii-moottorin mukana tulevaa tiedostopohjaista KV-varastoa: yksi JSON-tiedosto per scope, pidettynä moottoriprosessin muistissa ja uudelleenkirjoitettuna levylle ajastimella. Se on oikea oletus yhden käyttäjän paikalliselle asennukselle; jaettu daemon, jossa on useita samanaikaisia kirjoittajia, saa oikeat avainkohtaiset kirjoitukset Redisiltä sen sijaan, verkkokierroksen hinnalla per operaatio (joka `state::*`-kutsu sarjallistuu edelleen yhdelle Redis-yhteydelle, niin tämä vaihtaa tiedostovaraston lukituksen soklaan, ei rinnakkaisuuteen). Aseta `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) vaihtaaksesi molemmat workerit iii-moottorin sisäänrakennettuun `redis`-adapteriin, joka tallentaa joka avaimen Redis-hash-kenttänä (`HSET`) sen sijaan, että uudelleenkirjoittaisi koko scopen jokaisella kirjoituksella: ```env # ~/.agentmemory/.env AGENTMEMORY_STATE_BACKEND=redis AGENTMEMORY_REDIS_URL=redis://localhost:6379 ``` `AGENTMEMORY_STATE_BACKEND` on oletuksena `file`; sen asettamatta jättäminen pitää tämänpäiväisen käytöksen muuttumattomana, ja tunnistamaton arvo (mikä tahansa muu kuin `file` tai `redis`) on käynnistysvirhe, ei hiljainen varajärjestelmä. `/agentmemory/status` ja katseluohjelman Health-sivu (State store -rivi) ilmoittavat, mikä taustaosa on aktiivinen ja vastaako se, ei koskaan URL-osoitetta. **Vain pelkkä `redis://`.** Kiinnitetty moottori (0.22.1) rakentaa Redis-asiakkaansa ilman TLS-tukea, niin `rediss://`-URL (useimmat hallitut Redis-tarjoomat, kuten Upstash, Redis Cloud ja ElastiCache siirron aikaisella salauksella, ovat oletuksena vain-TLS) ei muodosta yhteyttä. Yhteys on salaamaton, niin Redis-salasana ja joka tallennettu muisto kulkevat langalla selkokielisenä: osoita paikalliseen Redisiin tai luotettavassa yksityisessä verkossa olevaan. Mille tahansa muulle Redisille, aja salattu tunneli (stunnel, SSH tai VPN) agentmemory-isännällä, niin pelkkä `redis://`-hyppy pysyy kyseisellä isännällä ja tunnelin ylävirran yhteys on salattu ja todennettu. Jos Redis-salasana sisältää heittomerkin, prosenttikoodaa se (`%27`); moottori laajentaa URL:n YAML-asetukseksi ennen jäsentämistä. **Yksi Redis-palvelin per `--instance`.** Moottorin Redis-avainetuliitteet (`state:`, `stream::`) on kiinnitetty, niin kaksi agentmemory-instanssia (`--instance 1`, `--instance 2`, ...) osoitettuna samaan tietokantaan ylikirjoittavat toistensa datan. Erillinen tietokantaindeksi (`redis://localhost:6379/1`) pitää tallennetun datan erillään, mutta moottori välittää live-katseluohjelman tapahtumat yhden Redis-pub/sub-kanavan (`stream::events`) yli, ja Redis-pub/sub ohittaa tietokantaindeksin, niin joka instanssin katseluohjelma näyttäisi edelleen toisen live-tapahtumat. Anna joka instanssille omansa Redis-palvelin (tai portti), kun ajat useampaa kuin yhtä. **Mikä pysyy samana, ja mikä eroaa.** Joka agentmemory-ominaisuus toimii Redisillä: istunnot, havainnot, muistot (muista, korvaa, kehitä, unohda), haku ja indeksierät, opetukset, graafi, auditointiloki ja sen kuukausittaiset scopet, vienti ja tuonti, hallintapoistot, konsolidoinnin tila, katseluohjelman tilannevedos ja sen live-stream, ja terveysmonitori. Moottori tallentaa joka scopen yhtenä Redis-hashina (`HSET`/`HGET`/`HGETALL`) ja laukaisee samat tilatriggerit kuin tiedostovarasto. Kolme moottorieroa käsitellään agentmemoryn sisällä: - Redis palauttaa scopen tietueet ei-kiinnitetyssä järjestyksessä. agentmemory lajittelee ne vanhimmasta alkaen (tietueen ID:ssä olevan luomisajan, sitten sen aikaleiman mukaan), niin listat, sivutus ja vientierät palautuvat samassa järjestyksessä kuin tiedostovarastolla. - Moottori soveltaa osittaisia päivityksiä Redisillä Lua-skriptissä, joka muuttaa tyhjät taulukot tyhjiksi objekteiksi. agentmemory soveltaa näitä päivityksiä itse (lue, muuta, kirjoita avainkohtaisen lukon alla) Redisillä, niin kentät kuten `tags: []` pysyvät taulukkoina. - Vanhentunut auditointilokitarkistus lukee vanhan scopen Redisistä sen sijaan, että etsisi tiedostovaraston tiedostoa levyltä. Yksi ero vaatii sinulta toimia: **Redis-uudelleenkäynnistyksen jälkeen moottori lakkaa välittämästä live-tapahtumia** katseluohjelmalle, kunnes agentmemory käynnistyy uudelleen. Data tallennetaan ja luetaan yhä normaalisti. Terveysmonitori lähettää testitapahtuman Redisin läpi 30 sekunnin välein; kun se ei palaa, `/agentmemory/status` ja katseluohjelman Health-sivu näyttävät "Live updates are not reaching the viewer" korjauksen kanssa: käynnistä agentmemory uudelleen. Jos Redis on alhaalla, tilaraportti näyttää "The state store is not answering" ja kuinka tarkistaa se (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Erittäin suuren scopen listaaminen lukee koko hashin yhdellä `HGETALL`:lla, samalla kustannuksella kuin tiedostovaraston pitäminen muistissa. **Suositellut Redis-asetukset.** Oletusarvoinen `save 3600 1 300 100 60 10000` -tilannevedospolitiikka voi menettää minuutteja kirjoituksia kaatumisessa, pahemmin kuin tiedostovaraston 5s flush-ikkuna. Aseta `appendonly yes` kaikelle, mistä välittäisit, jos menettäisit sen. Aseta `maxmemory-policy noeviction`; `allkeys-lru` tai vastaava pudottaa hiljaa muistoja, kun Redis osuu muistirajaansa. Natiivi (ei-Docker) käynnistys, ja joka yhden klikkauksen [käyttöönottomallipohja](../deploy/) (ne ylikirjoittavat mukana tulevan `iii-config.yaml`:n ja käynnistyvät natiivisti), lukevat `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` ja renderöivät ne käynnistettyyn `iii-config`:iin. URL itsessään ei koskaan kirjoiteta tähän renderöityyn tiedostoon, vain `${AGENTMEMORY_REDIS_URL}`-viittaus, jonka moottoriprosessi laajentaa omasta ympäristöstään käynnistyshetkellä. Vain tämän repositorion oma Docker Compose -reitti (`AGENTMEMORY_USE_DOCKER=1`, tai sillä tavalla aiemmin käynnistetyn moottorin jatkaminen) liittää `iii-config.docker.yaml`:n kirjoitussuojattuna ja ei koskaan renderöi; `agentmemory start` varoittaa, kun se havaitsee tämän yhdistelmän. Vaihda tämä tiedosto käsin, seuraten samaa `name: redis` / `config: redis_url: ...` -muotoa, joka näkyy [iii-state](https://workers.iii.dev/workers/iii-state)- ja [iii-stream](https://workers.iii.dev/workers/iii-stream)-workereiden dokumentaatiossa, ja osoita `redis_url` kontista tavoitettavaan Redisiin. `docker-compose.yml` välittää `AGENTMEMORY_REDIS_URL`:n moottorikonttiin, niin `redis_url: '${AGENTMEMORY_REDIS_URL}'` toimii siellä ja pitää URL:n pois liitetystä tiedostosta. Renderöity asetus pitää URL:n pois tiedostosta `~/.agentmemory/data/iii-config.runtime.yaml`, mutta moottorin oma konfiguraatioworker tallentaa yhä *laajennetun* arvon pysyvästi tiedostoihin `~/.agentmemory/config/iii-state.yaml` ja `iii-stream.yaml`, kun se käynnistyy (iii-moottorin `${VAR}`-laajennus tapahtuu ennen kuin tämä worker tallentaa siemenensä, ja se tallentaa ratkaistun arvon, ei viittausta). Kohtele tätä hakemistoa tunnuksena: `chmod 700 ~/.agentmemory` millä tahansa jaetulla isännällä, ja suosi Redis-ACL-käyttäjää, joka on rajattu siihen, mitä agentmemory tarvitsee, tietokannan admin-tunnusten sijaan. **Migraatio ei ole automaattinen.** `AGENTMEMORY_STATE_BACKEND`:n vaihtaminen aloittaa tyhjästä varastosta molemmilla puolilla; mikään ei kopioi olemassa olevaa dataa tiedostosta Redisiin tai takaisin. Vie data taustaosasta, jota jätät, ja tuo siihen, jota siirryt käyttämään. Tämä toimii identtisesti bashissa ja zshissä (mukaan lukien `bash -u`). Taulukko kuten `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` ei toimi: zsh pitää otsikon yhtenä virheellisenä sanana, kun bash jakaa sen kahdeksi, niin molemmat pyynnöt saavat 401-vastauksen aina kun `AGENTMEMORY_SECRET` on asetettu: ```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` hyväksyy myös `?maxSessions=`- ja `?offset=`-parametrit suuren korpuksen paloittelemiseksi useiden kutsujen yli; `strategy` tuonnissa on `merge` (oletusturvallinen), `replace` tai `skip`. ### Mitä iii korvaa | Perinteinen pino | agentmemory käyttää | |---|---| | Express.js / Fastify | iii HTTP-triggerit | | SQLite / Postgres + pgvector | iii KV-tila + muistinvarainen vektori-indeksi | | SSE / Socket.io | iii-streamit (WebSocket) | | pm2 / systemd | iii-moottorin workerien valvonta | | Prometheus / Grafana | iii OTEL + terveysmonitori | | Mukautetut plugin-järjestelmät | `iii worker add ` | **219 lähdetiedostoa · ~52,000 LOC · 2,500+ testiä · 311 funktiota · 60 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse. ---

### LLM-tarjoajat agentmemory tunnistaa tarjoajat automaattisesti ympäristöstäsi. Tarjoaja tekee LLM-pohjaiset operaatiot käytettäväksi, mutta tarjoajan asettaminen yksinään ei ota käyttöön LLM:n kirjoittamaa havaintojen pakkausta. Tämä reitti vaatii molemmat: tarjoajan ja `AGENTMEMORY_AUTO_COMPRESS=true`. | Tarjoaja | Asetus | Huomautuksia | |----------|--------|-------| | **No-op (oletus)** | Ei asetuksia tarvita | LLM-pohjainen pakkaus/yhteenveto on pois käytöstä. Synteettinen pakkaus ja BM25-palautus toimivat yhä. Katso `AGENTMEMORY_ALLOW_AGENT_SDK` alla, jos luotit aiemmin Claude-tilauksen varajärjestelmään. | | Anthropic API | `ANTHROPIC_API_KEY` | Per-token-laskutus | | MiniMax | `MINIMAX_API_KEY` | Anthropic-yhteensopiva | | Gemini | `GEMINI_API_KEY` | Ottaa myös upotukset käyttöön | | OpenRouter | `OPENROUTER_API_KEY` | Mikä tahansa malli | | OpenAI API | `OPENAI_API_KEY` | Oletus `gpt-5.6-luna`, ylikirjoita `OPENAI_MODEL`:lla | | **Paikallinen (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) tai `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Mikä tahansa OpenAI-API-yhteensopiva. Nolla kustannuksia, toimii omalla laitteistollasi. Katso [Paikalliset mallit](#local-models-ollama--lm-studio--vllm) alla. | | Claude-tilauksen varajärjestelmä | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Vain opt-in. Käynnistää `@anthropic-ai/claude-agent-sdk`-istuntoja; se aiheutti aiemmin rajoittamattoman Stop-hook-rekursion, niin se ei ole enää oletus. | ### Paikalliset mallit (Ollama / LM Studio / vLLM) agentmemory puhuu minkä tahansa OpenAI-API-yhteensopivan palvelimen kanssa, niin kaikki, mikä paljastaa `/v1/chat/completions`-päätepisteen, toimii ilman koodimuutoksia. Ei maksullisia avaimia, ei pilveä, ei nopeusrajoituksia; toimii kokonaan laitteistollasi. **Ollama** (oletusportti `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** (oletusportti `1234`): Avaa LM Studio → Local Server -välilehti → Start Server. Valitse mikä tahansa keskustelumalli valitsimesta (Qwen 3, gpt-oss, DeepSeek R1, jne.). ```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**: samanlainen muoto. Osoita `OPENAI_BASE_URL` mihin tahansa URL-osoitteeseen, jonka palvelimesi paljastaa, ja aseta `OPENAI_MODEL` nimeksi, jonka palvelimesi hyväksyy. **Mallivalinnat muistityöhön**: pakkaus ja yhteenveto ovat lyhyitä tehtäviä (<2K tokenia sisään, <500 tokenia ulos), joissa 7B-ohjeistusmalli on enemmän kuin tarpeeksi. Suositukset: | Malli | Koko | Miksi | |-------|------|-----| | `qwen3:8b` | ~5,2 GB | Tasapainoinen oletus 16 GB:n koneella; vahva poiminnassa ja työkalumuotoisessa tekstissä | | `qwen3:4b` | ~2,6 GB | Pienin järkevä vaihtoehto; sopii pakkaukseen, heikompi graafipoiminnassa | | `qwen3-coder:30b` | ~19 GB | Paras paikallinen valinta koodimuotoisille istunnoille (30B MoE, 3,3B aktiivista) 24–32 GB:n laitteistolla | | `gpt-oss:20b` | ~14 GB | Vahva yleismalli, mahtuu 16 GB RAM:iin | | `deepseek-r1:8b` | ~5,2 GB | Päättelytislattu; hitaampi mutta puhtaammat poiminnat | Qwen 3 -mallit ajattelevat oletuksena ja voivat polttaa koko tokenbudjetin päättelyyn ennen tulostetta. Aseta `AGENTMEMORY_LLM_NOTHINK=1` liittääksesi `/no_think`-lisäyksen graafipoimintakehotteisiin, ja nosta `MAX_TOKENS`-arvoa (16384 toimii), jos poiminnat palaavat tyhjinä. Päättelyluokan mallit (`o1`-tyyliset ``-lohkoilla) voivat palauttaa tyhjän `content`-kentän `reasoning`-kentällä, jota paikallinen palvelimesi ei välttämättä paljasta. Jos poiminnat palaavat tyhjinä, vaihda ensin ei-päättelevään malliin. `OPENAI_REASONING_EFFORT=none`-ympäristömuuttuja voi myös poistaa ajattelun käytöstä Ollama Cloudin ajattelevissa malleissa, jotka peilaavat OpenAI:n reasoning-skeemaa. Paikalliset upotukset toimitetaan valinnaisena riippuvuutena, mutta ne eivät ole käytössä oletuksena. Aseta `EMBEDDING_PROVIDER=local` ottaaksesi käyttöön `Xenova/all-MiniLM-L6-v2` (384-ulotteinen). Ensimmäinen upotuspyyntö lataa mallin; päättely tapahtuu sen jälkeen laitteella. Ilman tätä asetusta tai etäupotusavainta vektorit pysyvät pois käytöstä, `mem::search` käyttää BM25:tä, ja `smart-search` voi yhä lisätä olemassa olevia graafiosumia. ### Kustannustietoinen mallin valinta Kun LLM:n kirjoittama taustapakkaus on otettu käyttöön molemmilla, tarjoajalla ja `AGENTMEMORY_AUTO_COMPRESS=true`, se ajetaan joka havainnolle, niin mallinvalinta muuttaa kuukausikuluja merkittävästi. Tallennettu työkuormadata: 635 pyyntöä / 888K tokenia / 35 tuntia aktiivista käyttöä, ajettuna kolmea OpenRouter-mallia vastaan 2026-05-23-hinnoittelulla. | Taso | Malli | Syöte / 1M | Tuloste / 1M | Kustannus tallennetulle 35h:lle | Huomautuksia | |------|-------|------------|-------------|---------------------------|-------| | Suositeltu | `deepseek/deepseek-v4-flash-0731` | 0,07 $ | 0,14 $ | ~0,07 $ (arvio) | Uusin DeepSeek; halvin suositeltu valinta pakkaustyökuormille. | | Suositeltu | `deepseek/deepseek-v4-pro` | 0,435 $ | 0,87 $ | ~0,46 $ | Vahva pakkaus- ja yhteenvetolaatu ~10x alemmilla kustannuksilla kuin Sonnet. | | Suositeltu | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Vahva koodipäättely, jos istuntosi ovat voimakkaasti koodimuotoisia. | | Premium | `anthropic/claude-sonnet-5` | 3,00 $ | 15,00 $ | ~5,02 $ (arvio) | Sama listahinta kuin mitattu Sonnet 4.6 -ajo; 2 $/10 $ -esittelyhinnoittelu 31.8.2026 asti. | | Premium | `openai/gpt-5.6-sol` | 5,00 $ | 30,00 $ | ~9 $ (arvio) | Lippulaivataso; kallis jatkuvasti päällä olevalle taustatyölle. | | Vältä | `anthropic/claude-opus-5` | 5,00 $ | 25,00 $ | ~8,40 $ (arvio) | Lippulaivaluokan malli; ylikulutus pakkaukseen. | Mitatut rivit tulevat tallennetusta ajosta; (arvio)-rivit skaalaavat samaa tokensekoitusta joka mallin listahinnalla. agentmemory tulostaa ajonaikaisen varoituksen, kun `OPENROUTER_MODEL` täsmää premium-tason malliin. Aseta `AGENTMEMORY_SUPPRESS_COST_WARNING=1` hiljentääksesi sen, kun olet tehnyt tietoisen valinnan. Laadun vs. kustannuksen kompromissi muistityöhön: pakkaus on yhteenvetotehtävä, jossa on suhteellisen väljät laatuvaatimukset (agentti lukee yhteenvedon uudelleen, ei käyttäjä). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder jäävät pyöristysvirheen sisään Sonnetista tässä tehtävässä kustantaen 10–70x vähemmän. Säästä premium-tason mallit kyselyihin, jotka luet suoraan. Lähteet: [OpenRouter-hinnoittelu Claude Sonnet 5:lle](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeekin hinnoitteluhuomautukset](https://api-docs.deepseek.com/quick_start/pricing/). ### Moniagenttinen muisti (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) Moniagenttisissa asetuksissa, joissa useat roolit jakavat yhden agentmemory-palvelimen (arkkitehti / kehittäjä / arvioija / tutkija / tukiagentti), `AGENT_ID` tagittaa joka kirjoituksen roolilla, joka sen teki. `AGENTMEMORY_AGENT_SCOPE` hallitsee, suodattaako palautus tämän tagin mukaan. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` Kaksi tilaa: | Tila | Tagittaa kirjoitukset | Suodattaa palautuksen | Milloin käyttää | |------|------------|---------------|-------------| | `shared` (oletus) | kyllä | ei | Agenttien välinen konteksti auditointijäljellä. Arkkitehti voi nähdä, mitä kehittäjä merkitsi, mutta joka rivi tallentaa, kuka sanoi sen. | | `isolated` | kyllä | kyllä | Tiukka erottelu. Arkkitehti ei koskaan näe kehittäjän havaintoja / muistoja / istuntoja. | Mitä tagitetaan, kun `AGENT_ID` on asetettu: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rooli kulkee ketjua `api::session::start` → `mem::observe` → `mem::compress` → KV. Mitä suodatetaan isolated-tilassa: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Joka päätepiste hyväksyy `?agentId=` ylikirjoittaakseen per pyyntö, ja `?agentId=*` poistuakseen env-rajauksesta kokonaan. `/memories` hyväksyy myös `?includeOrphans=true` tuodakseen esiin ennen-AGENT_ID-muistot, joiden `agentId` on määrittelemätön. Per-kutsu-ylikirjoitus SDK-/REST-tasolla: joka muuttava päätepiste (`/session/start`, `/remember`) hyväksyy `agentId`-kentän pyynnön rungossa, joka voittaa env-arvon. Hyödyllinen ajonaikaisille ympäristöille, jotka reitittävät monta roolia yhden palvelinprosessin läpi. MCP:n `memory_save`-työkalu paljastaa saman `agentId`-kentän, itsenäinen stdio-palvelin välittää molemmat, `agentId`:n ja `project`:n, ja tallennetut muistot kuljettavat `agentId`:n hakuindeksiin, niin agenttirajattu haku kattaa myös muistot, ei vain havainnot. Kun `AGENT_ID` on asettamatta, muisti pysyy rajaamattomana (vanha käytös, ei tageja, ei suodattimia). ### Portit agentmemory + iii-engine sitovat neljä porttia oletuksena. Jos uudelleenkäynnistys epäonnistuu virheellä `port in use`, tämä taulukko kertoo, mitä prosessia etsiä. | Portti | Prosessi | Tarkoitus | Env-ylikirjoitus | |------|---------|---------|--------------| | `3111` | agentmemory | REST-rajapinta + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` | | `3112` | iii-engine | Sisäinen streams-worker (agentmemoryn + katseluohjelman kuluttama) | `III_STREAM_PORT` (suositeltu) tai vanha `III_STREAMS_PORT` | | `3113` | agentmemory | Reaaliaikainen katseluohjelma (`http://localhost:3113`) | `III_VIEWER_PORT` tai `AGENTMEMORY_VIEWER_URL` ilmoitetulle URL-osoitteelle | | `49134` | iii-engine | WebSocket; workerit rekisteröityvät tähän, OTel-telemetria kulkee sen yli | `III_ENGINE_PORT` tai `III_ENGINE_URL` | `--port ` muuttaa REST-ankkurin ja johtaa streamit `N+1`, katseluohjelman `N+2` ja moottorin WebSocketin `N+46023`, vain siltä osin kuin vastaava eksplisiittinen portti tai URL yllä on asettamatta. Se ei luo eristettyä elinkaarinimiavaruutta. Käytä `--instance 1` toiselle daemonille; se käyttää ankkuria 3211, oletuksena `3211/3212/3213/49234`, ja saa erillisen `instance-1`-data- ja elinkaarihakemiston. Instanssit 1–50 noudattavat samaa mallia. Kiinnitetty moottori käynnistyy lipulla `--no-update-check` (ei päivitys- tai turvallisuusneuvontahakuja GitHubista käynnistyksessä) ja iii:n anonyymi käyttötelemetria pois päältä: agentmemory asettaa `III_TELEMETRY_ENABLED=false` moottorille, jonka se käynnistää, ellet itse vie muuttujaa, ja mukana tuleva compose-tiedosto tekee samoin. Vanhentuneiden prosessien siivous, kun portit pysyvät sidottuina kaatuneen ajon jälkeen: ```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` kerää siististi sekä workerin että moottorin pidfile:n normaalissa natiivissa sammutuksessa. Docker-tilassa se huuhtelee natiivin workerin, pysäyttää tarkan validoidun moottorikontin, ja säilyttää molemmat, kontin ja sen `/data`-liitoksen, häviöttömälle uudelleenkäynnistykselle. Seuraava käynnistys validoi ja jatkaa samaa konttia. Docker-pohjainen poisto vaatii `agentmemory remove --keep-data`-komennon: se poistaa jaetut agentmemory-hallinnoimat tiedostot säilyttäen validoidun kontin, sen datan liitoksen ja elinkaaritietueen, jota tarvitaan niiden palauttamiseen. Tuhoisa Docker-datan poisto on tarkoituksella jätetty operaattorille varmuuskopion jälkeen. CLI myös kieltäytyy ottamasta haltuun tai signaalittamasta Docker- tai VM-porttien haltijoita (Docker-backend, vpnkit, colima) natiivina moottorina, ellei `--force`-lippua anneta. Yllä oleva manuaalinen siivous on vain kaatumisen jälkeiselle tapaukselle, jossa kumpaakaan pidfileä ei jäänyt. ### Asetustiedosto Laita agentmemoryn ajonaikaiset asetukset tiedostoon `~/.agentmemory/.env` sen sijaan, että vietäisit muuttujia joka shellissä. Jos katseluohjelma näyttää asetusvihjeen kuten `export ANTHROPIC_API_KEY=...`, kopioi se tähän tiedostoon muodossa `ANTHROPIC_API_KEY=...` ilman `export`-etuliitettä, ja käynnistä sitten agentmemory uudelleen. Prosessin ympäristömuuttujat toimivat yhä ja voittavat tiedoston arvot. Windowsilla sama tiedosto sijaitsee polussa `%USERPROFILE%\.agentmemory\.env`: ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` Testataksesi Claude Code Pro-/Max-tilauksella API-avaimen sijaan, liity mukaan nimenomaisesti: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` LLM:n kirjoittama havaintojen pakkaus vaatii molemmat rivit: pääsyn LLM-tarjoajaan (mukaan lukien tämä nimenomainen tilauksen varajärjestelmä) ja `AGENTMEMORY_AUTO_COMPRESS=true`. Tarjoaja yksinään jättää oletusarvoisen synteettisen pakkausreitin paikalleen. Konsolidointi (graafisolmut, opetukset, kristallit) on oletuksena päällä aina, kun LLM-tarjoaja on määritetty. Poistu siitä nimenomaisesti asetuksella `CONSOLIDATION_ENABLED=false`, jos haluat LLM-vapaan toiminnan. Graafipoiminta on erillinen lippu: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### Ympäristömuuttujat Luo `~/.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 endpointia portissa `3111`. REST-rajapinta sitoutuu oletuksena osoitteeseen `127.0.0.1`. Suojatut endpointit vaativat `Authorization: Bearer `, ja mesh-synkronointiendpointit vaativat nimenomaisesti asetetun `AGENTMEMORY_SECRET`-arvon molemmilla vertaisilla. **Autentikointi on oletuksena päällä.** Kun `AGENTMEMORY_SECRET` ei ole asetettu (shellissä tai tiedostossa `~/.agentmemory/.env`), palvelin generoi satunnaisen salaisuuden ensimmäisellä käynnistyksellä ja tallentaa sen polkuun `~/.agentmemory/secret` oikeuksilla `0600`. Joka mukana tuleva asiakas lukee sen sieltä puhuessaan paikalliselle palvelimelle: CLI, katseluohjelma, hookit kansiossa `plugin/scripts`, MCP-palvelin ja `@agentmemory/mcp`-shim, `agentmemory connect`-komennon kirjoittamat asetukset, ja mukana tulevat OpenCode-, Pi-, OpenClaw-, Hermes- ja tiedostojärjestelmän tarkkailijaintegraatiot. Tallennettu salaisuus lähetetään vain loopback-URL-osoitteisiin (`localhost`, `127.0.0.0/8`, `::1`). Nimenomainen `AGENTMEMORY_SECRET` voittaa aina, ja etäasiakkaat tarvitsevat sen yhä asetettuna. Docker ja `deploy/`-entrypointit generoivat ja vievät jo omansa. Kutsuaksesi rajapintaa käsin: ```bash curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health ``` **Kirjoitusten pyyntösäännöt.** `POST`-, `PUT`-, `PATCH`- ja `DELETE`-pyyntöjen REST-rajapinnalle ja katseluohjelmalle on lähetettävä `Content-Type: application/json` (`charset`-parametri on OK) aina, kun niillä on runko, ja `Origin`-otsikon, kun se on läsnä, on oltava loopback-alkuperä määritetylle REST- tai katseluohjelmaportille tai listattu `VIEWER_ALLOWED_ORIGINS`-muuttujassa (pilkulla eroteltu, esim. `https://memory.example.com`). Asiakkaat, jotka eivät lähetä `Origin`-otsikkoa (CLI, hookit, MCP, curl, palvelin-palvelin-liikenne), eivät kärsi tästä. Katseluohjelma hyväksyy myös oman alkuperänsä. **Tiedostopolut.** Päätepisteet, jotka lukevat tai kirjoittavat tiedostoja (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), hyväksyvät vain polkuja hakemiston `~/.agentmemory`, instanssin datahakemiston tai `AGENTMEMORY_IMPORT_ROOT`-muuttujassa listatun hakemiston alla (erota useampi `:`-merkillä, tai `;`-merkillä Windowsilla). `/replay/import-jsonl` hyväksyy myös oletuksensa `~/.claude/projects`. `/obsidian/export` pysyy hakemiston `AGENTMEMORY_EXPORT_ROOT` sisällä ja `/migrate` hakemiston `~/.agentmemory` sisällä. Symbolilinkit ratkaistaan ennen joka tarkistusta. **Salaisuuksien siistiminen.** API-avaimet, bearer-tokenit, PEM-yksityisavainlohkot ja URL-osoitteisiin upotetut tunnukset (`scheme://user:password@host`) peitetään ennen tekstin tallentamista, joka kirjoitusreitillä: havainnot, remember, evolve, slotit, opetukset, toiminnot, sketchit, signaalit, checkpointit, tuonnit, jsonl-toisto, mesh-synkronointi, tiimijaot, pakkaus- ja yhteenvetotuloste, kristallit ja graafisolmut.

Keskeiset endpointit

| Metodi | Polku | Kuvaus | |--------|------|-------------| | `GET` | `/agentmemory/health` | Terveystarkistus (aina julkinen) | | `GET` | `/agentmemory/status` | Mikä on vialla ja miten se korjataan (HTML selaimille, muuten JSON) | | `GET` | `/agentmemory/viewer/snapshot` | Kaikki, mitä katseluohjelma näyttää, yhdessä vastauksessa | | `POST` | `/agentmemory/session/start` | Aloita istunto + hae konteksti | | `POST` | `/agentmemory/session/end` | Päätä istunto | | `POST` | `/agentmemory/observe` | Tallenna havainto (katso tallennuksen toimitus alla) | | `GET` | `/agentmemory/capture` | Tallennuksen saapuvat, dead letterit ja offline-spool | | `POST` | `/agentmemory/capture/retry` | Yritä dead-letter-tallennuksia uudelleen | | `POST` | `/agentmemory/capture/drain` | Lähetä paikallinen offline-spool nyt | | `POST` | `/agentmemory/smart-search` | Hybridihaku | | `POST` | `/agentmemory/context` | Generoi konteksti | | `POST` | `/agentmemory/remember` | Tallenna pitkäkestoiseen muistiin | | `POST` | `/agentmemory/forget` | Poista havaintoja | | `POST` | `/agentmemory/enrich` | Tiedostokonteksti + muistot + bugit | | `GET` | `/agentmemory/profile` | Projektiprofiili | | `GET` | `/agentmemory/export` | Vie kaikki data | | `POST` | `/agentmemory/import` | Tuo JSON:sta | | `POST` | `/agentmemory/graph/query` | Tietograafikysely | | `POST` | `/agentmemory/graph/compact` | Tiivistä ylisuuri graafin alkuperä | | `POST` | `/agentmemory/team/share` | Jaa tiimin kanssa | | `GET` | `/agentmemory/audit` | Auditointijälki | Täysi endpoint-lista: [`src/triggers/api.ts`](../src/triggers/api.ts)

**Tallennuksen toimitus.** Hookit lähettävät joka havainnon kerran osoitteeseen `POST /agentmemory/observe` `eventId`:n kanssa. Se on isännän oma ID kutsulle, kun hyötykuormalla on sellainen (esimerkiksi Claude Coden `tool_use_id`), muuten tiiviste istunnosta, hook-tyypistä, työkalun nimestä, syötteestä, tulosteesta ja isännän aikaleimasta. Palvelin kirjoittaa tapahtuman tallennuksen saapuviin tilavarastossa, tallentaa havainnon, ja poistaa sitten saapuva-merkinnän. Tilakoodi kertoo, mitä tapahtui: | Tila | `status`-kenttä | Merkitys | |---|---|---| | `201` | `accepted` | Tallennettu. `observationId` on uusi havainto. | | `202` | `accepted` (`state: "retrying"`) | Hyväksytty, mutta tallentaminen epäonnistui. Palvelin yrittää sitä uudelleen, myös uudelleenkäynnistyksen jälkeen. | | `200` | `duplicate` | Tämä `eventId` on jo hyväksytty. `observationId` on olemassa oleva havainto; mitään uutta ei tallenneta. | | `400` / `422` | `rejected` | Virheellinen hyötykuorma, tai tallentaminen epäonnistui pysyvästi (tapahtuma säilytetään dead letterina). | | `503` | `rejected` (`retryable: true`) | Saapuvat on täynnä (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hookit spoolaavat tapahtuman ja lähettävät sen myöhemmin. | Epäonnistuneita tapahtumia yritetään uudelleen `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`-välein (10 s) kaksinkertaistuvalla takaisinvedolla, enintään `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`-kertaa (5). Tapahtumat, jotka epäonnistuvat yhä, jäävät saapuviin dead lettereina, listataan `/agentmemory/status`:ssa ja katseluohjelman Health-sivulla, ja niitä voi yrittää uudelleen komennolla `POST /agentmemory/capture/retry` (`{"eventId": "..."}` tai `{"all": true}`). Hyväksytyt tapahtuma-ID:t muistetaan `AGENTMEMORY_CAPTURE_DEDUP_HOURS`-ajan (168 tuntia, enintään `AGENTMEMORY_CAPTURE_EVENTS_MAX` ID:tä), niin aikakatkaisun tai uudelleenkäynnistyksen jälkeen toistettu hook tallennetaan kerran, kun taas kaksi erillistä työkalukutsua omilla isäntä-ID:illään tallennetaan kahdesti, vaikka niiden sisältö olisi identtinen. Kun havainto poistetaan (unohda, istunnon poisto, häädetty, automaattisesti unohdettu tai tuonti, joka korvaa varaston), sen tapahtuma merkitään poistetuksi ennen havainnon poistamista, niin kyseisen tapahtuman toisto samalla ikkunalla vastataan kaksoiskappaleena eikä mitään tallenneta. Tilavarasto kirjoittaa levylle 2 sekunnin välein, niin vastattu tapahtuma voi yhä olla vain muistissa hetken. Kattaakseen tämän, joka `2xx`-vastaus kantaa myös palvelimen `bootId`:n (uusi joka käynnistyksellä), `acceptedAt`:n ja `durableAfterMs`:n (tallennusväli plus 1,5 s tiedostovarastolla, 1,5 s redisillä, jossa pysyvyys on operaattorin asetus). Hookit pitävät tapahtuman paikallisessa spoolissa, kunnes tämä ikkuna on kulunut, ja poistavat sen myöhemmällä kutsulla ilman toista pyyntöä. Jos `bootId` on sillä välin muuttunut, palvelin käynnistyi uudelleen, niin hook lähettää tapahtuman uudelleen samalla `eventId`:llä; tapahtuma, joka todella saapui levylle, ei tallenneta kahdesti. Palvelin myös lähettää tällaisia tapahtumia itse käynnistyksessä ja joka uudelleenyrityksen välein, niin uudelleenkäynnistys ei menetä mitään, vaikka mikään hook ei ajaisi sen jälkeen. Vanhemmat hookit ohittavat ylimääräiset kentät, ja uudet hookit vanhempaa palvelinta vastaan hylkäävät tapahtuman `2xx`:llä kuten ennen. Kun palvelin on alhaalla, ei vastaa ajoissa tai palauttaa 5xx:n, hook liittää havainnon paikalliseen spool-tiedostoon, `/capture-spool/-.jsonl` (ylikirjoita kansio `AGENTMEMORY_CAPTURE_SPOOL_DIR`:llä). Tiedosto on yksityinen käyttäjällesi (oikeudet 600), salaisuudet peitetään samalla tavalla kuin palvelin peittää ne, se pitää enintään `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) ja pudottaa merkinnät, jotka ovat vanhempia kuin `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Kun se on täynnä, uudet merkinnät pudotetaan ja lasketaan, ja `/agentmemory/status` raportoi sen. Hook poistuu yhä koodilla 0 aikarajansa sisällä ja lisää ei yhtään pyyntöä, kun palvelin on terve. Spool lähetetään seuraavassa käynnistyksessä ja ensimmäisellä hookilla, joka tavoittaa palvelimen uudelleen, taustaprosessissa, niin agentti ei odota. Tapahtuma-ID:t tekevät tämän turvalliseksi: havainto, joka saapui ennen aikakatkaisua, ei tallenneta kahdesti. `npx @agentmemory/agentmemory capture` näyttää spoolin ja palvelimen saapuvat, `--drain` lähettää spoolin nyt, ja `GET /agentmemory/capture` palauttaa saman JSON:na. Aseta `AGENTMEMORY_CAPTURE_SPOOL=false` kytkeäksesi spoolin pois. **Graafin alkuperän tiivistäminen.** Joka tietograafin solmu ja reuna pitää 32 uusimman havainnon ID:t, joista se tuli. Varastot, jotka kirjoitettiin ennen tätä kattoa, voivat pitää tuhansia ID:itä per kuuma solmu, mikä tekee graafihausta ja katseluohjelmasta hitaan tai kaataa workerin. agentmemory korjaa tämän itse: ensimmäisellä käynnistyksellä päivityksen jälkeen se tiivistää joka solmun, reunan, korvatun reunan (temporaalinen graafihistoria) ja välimuistitetun tilannevedoksen kattoon taustalla, pienissä viipaleissa tauolla niiden välissä, niin haku, tallennus ja katseluohjelma pysyvät toiminnassa. Se tallentaa edistymisensä, jatkaa uudelleenkäynnistyksen jälkeen ja ei koskaan aja uudelleen, kun se on valmistunut. `/agentmemory/status` ja katseluohjelman Health-sivu näyttävät sen odottavana, käynnissä (nykyisellä scopella ja sijainnilla), valmiina tai epäonnistuneena. Aseta `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` kytkeäksesi sen pois. Ajaaksesi sen käsin, kutsu `POST /agentmemory/graph/compact`. Se kävelee nimi- ja reuna-avainindeksit sen sijaan, että listaisi joka solmun ja reunan, ja sen voi turvallisesti ajaa uudelleen. Kun se tiivistää ID:itä, se kirjoittaa `graph_compact`-auditointimerkinnän. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}' ``` Suurella varastolla, tai kun kutsu palauttaa 504:n, aja se viipaleissa. Lähetä `scope` (`nodes`, `edges` tai `history`), `offset` ja `limit`, ja kutsu sitten uudelleen palautetulla `nextOffset`:lla, kunnes se on `null`. Tee tämä `nodes`:lle, `edges`:lle ja `history`:lle, ja lopeta yhdellä `{"scope":"snapshot"}`-kutsulla, koska viipaloitu ajo ei koske välimuistitettua tilannevedosta. ```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) ``` **Edellytykset:** Node.js >= 20 npm/npx:llä; [iii-engine](https://iii.dev/docs) v0.22.1 tai Docker. macOS/Linux-automaattinen moottorin asennus vaatii myös `curl`:n, POSIX-yhteensopivan `sh`:n ja `tar`:n; natiivi Windows käyttää manuaalista kiinnitettyä `iii.exe`:tä, WSL2:ta tai Docker Desktopia.

[Apache-2.0](../LICENSE)