Pysyvä muisti koodausistuntojen ja agenttien välillä.
Pysyvä muisti seuraaville: Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode ja mikä tahansa MCP-asiakas.
---
AgentMemory tallentaa tuetut istuntotapahtumat ja tekee päätöksistä, korjauksista ja opeista haettavia eri agenteille. Viewerissa voit tarkastella, muokata, viedä ja poistaa muistoja. Avainsanahaku toimii ilman API-avainta; upotukset lisäävät semanttisen haun.
## Asennus
Vaatimukset:
- Node.js 20 tai uudempi, mukana npm ja npx (`node -v`, `npm -v` ja `npx -v`).
- macOS/Linux tarvitsevat myös `curl`-, POSIX `sh`- ja `tar`-työkalut ympäristön automaattiseen asennukseen.
- Käytä Windowsissa WSL2:ta tai [natiivin Windowsin ohjetta](#windows).
Kanoninen tuore asennuskomento:
```bash
npx -y @agentmemory/agentmemory@latest
```
Valitse agentit ja palveluntarjoaja tai avaimeton tila. Ohjattu asennus tallentaa asetukset, käynnistää muistipalvelimen ja tarjoaa `agentmemory`-komennon globaalin asennuksen. `-y` hyväksyy npm-kehotteen; `@latest` valitsee nykyisen julkaisun. LLM-pakkaus edellyttää palveluntarjoajaa ja asetusta `AGENTMEMORY_AUTO_COMPRESS=true`.
Avaimeton tila poistaa vektoriupotukset käytöstä. `memory_recall` (`mem::search`-reitti) käyttää BM25:tä, kun taas `memory_smart_search` voi myös yhdistää rakenteellisia graafiosumia, kun graafidataa on jo olemassa. Saadaksesi ilmaisen, laitteella toimivan semanttisen muistinhaun, aseta `EMBEDDING_PROVIDER=local` tiedostoon `~/.agentmemory/.env` ja käynnistä uudelleen. Ensimmäinen upotuspyyntö lataa mallin `Xenova/all-MiniLM-L6-v2`; päättely toimii sen jälkeen paikallisesti.
API toimii osoitteessa `http://localhost:3111` ja viewer osoitteessa `http://localhost:3113`. Molemmat kuuntelevat oletuksena vain paikallisesti. Asetukset ovat tiedostossa `~/.agentmemory/.env`; [tietojen tallennus](#data-storage) kuvaa hakemistot ja erilliset instanssit.
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
Yhdistä toinen agentti komennolla `agentmemory connect `. Katso [integraatiot](#works-with-every-agent) ja [päivittäiset komennot](#everyday-commands).
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`).
---
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 + elinkaarihookit + MCP
OpenCode tallennus-plugin + MCP
Devin 6 hookia + taidot + MCP
OpenClaw natiivi plugin + MCP
Hermes natiivi plugin + MCP
pi natiivi muistihaku + tallennus + taidot
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 natiivi tallennus + MCP
Roo Code MCP-palvelin
Kilo Code MCP-palvelin
Goose MCP-palvelin
Aider REST-rajapinta
Oh My Pi natiivi muistihaku + tallennus + taidot + valinnainen MCP
Toimii minkä tahansa agentin kanssa, joka puhuu MCP:tä tai HTTP:tä. Yksi palvelin, muistot jaettuna kaikkien kesken.
---
### Tietojen tallennus
Muistot tallennetaan oletuksena repositorion ulkopuolelle:
| Alusta | Datahakemisto |
|---|---|
| macOS | `~/Library/Application Support/agentmemory` |
| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
| Windows | `%APPDATA%\agentmemory` |
Instanssi 0 käyttää olemassa olevaa `./data/state_store.db`-tallennusta. Valitse toinen hakemisto valinnalla `--data-dir ` tai muuttujalla `AGENTMEMORY_DATA_DIR`. Säilytä sama hakemisto uudelleenkäynnistyksissä ja päivityksissä.
```bash
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
```
`--instance 1` käyttää alihakemistoa `instance-1`, API-porttia `3211` ja viewer-porttia `3213`. Redis ja siirrot kuvataan [tallennus- ja varmuuskopiointioppaassa](../docs/reliability/state-storage.md).
Uusimmat julkaisutiedot: [CHANGELOG.md](../CHANGELOG.md).
---
### 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
Tarkista käynnissä olevan palvelimen terveys, viewer ja 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
```
`status` näyttää palvelimen tilan, palveluntarjoajat, upotustilan, havaintojen toimituksen ja palautumisen. Suojatut REST-pyynnöt tarvitsevat palvelimen salaisuuden. Käytä omaa `AGENTMEMORY_SECRET`-arvoa, jos se on asetettu; muutoin lue luotu paikallinen salaisuus:
```bash
# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
-H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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 status
agentmemory capture
agentmemory capture --drain
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-näkymässä natiivien rinnalla. Litteroinnit indeksoidaan ja merkitään alkuperäkanavalla `import`; käsittely voi tuottaa myös istuntokiteitä ja oppeja.
> **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
```
Komento päivittää paikallisen ympäristön ja voi muuttaa työtilan JavaScript-riippuvuuksia. Varmuuskopioi tiedot ja lue [päivitysopas](../docs/upgrades/iii-0.25.md).
### Claude Code (yksi lohko, liitä se)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code ilman pluginin asennusta (itsenäinen MCP-reitti)
Jos kytket agentmemoryn MCP-palvelimen tiedoston `~/.claude.json` (oletuspolku) 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` (oletuspolku). 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ä komento määrittää MCP-palvelimen ja yhdistää mukana tulevat hookit Claude Coden käyttäjäkohtaisiin asetuksiin. Jos `CLAUDE_CONFIG_DIR` on asettamatta, tyhjä tai sisältää vain tyhjiä merkkejä, se käyttää MCP:lle tiedostoa `~/.claude.json` ja hookeille tiedostoa `~/.claude/settings.json`. Muut hakemistopolut säilytetään täsmälleen annettuina, myös alun ja lopun tyhjät merkit mukaan lukien. Jos haluat käyttää omaa hakemistoa, aseta `CLAUDE_CONFIG_DIR` samaksi ei-tyhjäksi arvoksi sekä tälle komennolle että Claude Codelle; tiedostot ovat tällöin `$CLAUDE_CONFIG_DIR/.claude.json` MCP:lle ja `$CLAUDE_CONFIG_DIR/settings.json` hookeille. Claude Coden on saatava tämä arvo käynnistysympäristöstään, vaikka yhdistin lukisi sen AgentMemoryn `.env`-tiedostosta. Luo oma hakemisto ennen tämän komennon suorittamista; muuten yhdistin ohittaa Claude Coden, koska sitä ei tunnisteta. Jos shellin arvo sisältää vain tyhjiä merkkejä, poista `CLAUDE_CONFIG_DIR` ympäristöstä ennen Claude Coden käynnistämistä, jotta myös se käyttää oletusprofiilia. Käytä absoluuttista polkua. Suhteelliset polut tulkitaan työhakemiston perusteella, joten molemmat komennot on suoritettava samasta hakemistosta.
Hook-komennot käyttävät absoluuttisia polkuja asennetun paketin mukana tulevaan `plugin/`-hakemistoon. Suorita komento uudelleen agentmemoryn päivityksen jälkeen, jotta polut päivittyvät. Käyttäjän omat merkinnät asetustiedostoissa säilytetään; vain aiemmat agentmemory-merkinnät korvataan. `/plugin install` on edelleen suositeltu tapa.
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.
### Cursor
```bash
agentmemory connect cursor
```
Valitse sitten **Settings → Plugins → Add marketplace** -kohdassa agentmemory-hakemisto, joka sisältää `.cursor-plugin/plugin.json`-tiedoston. Ota **agentmemory**-plugin käyttöön ja lataa ikkuna uudelleen. Plugin tarjoaa elinkaaren tallennuksen, työtilaan perustuvan projektin tunnistuksen, taidot ja MCP:n. Käytä joko pluginin hookeja tai manuaalisia hookeja tiedostossa `~/.cursor/hooks.json`, jotta tapahtumat eivät tallennu kahdesti.
[Cursor](../integrations/cursor/)
### Pi, Oh My Pi, DeepSeek Harness
```bash
agentmemory connect pi --with-mcp
agentmemory connect omp --with-mcp
agentmemory connect dsh --with-hooks
```
Valitse oman ohjelmasi komento. Pi ja OMP asentavat natiivin muistihaun, tallennuksen, offline-uudelleenlähetyksen ja taidot; `--with-mcp` lisää kaikki työkalut. Suorita Pi:ssä `/reload` tai käynnistä OMP uudelleen ja tarkista `/agentmemory-status`. DSH asentaa MCP:n ja mukana toimitetun tallennuspluginin; käynnistä DSH uudelleen yhdistämisen jälkeen.
Pi tukee myös asennettavaa `@agentmemory/pi`-pakettia. Paikallinen asennus ja npm-saatavuus kuvataan [Pi-oppaassa](../integrations/pi/). Käytä ohjelmaa kohti vain yhtä asennustapaa.
[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (liitä tämä kehote)
```text
Asenna agentmemory OpenClawille. Käynnistä muistipalvelin portissa localhost:3111 suorittamalla komento `npx -y @agentmemory/agentmemory@latest` erillisessä terminaalissa. Lisää sitten tämä OpenClawin MCP-asetuksiin, jotta kaikki agentmemoryn 54 muistityökalua ovat käytettävissä:
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
Käynnistä OpenClaw uudelleen. Vahvista toiminta komennolla `curl http://localhost:3111/agentmemory/health`. Avaa reaaliaikainen katseluohjelma osoitteessa http://localhost:3113. Syvempää muistipaikkaintegraatiota varten kopioi `integrations/openclaw` polkuun `~/.openclaw/extensions/agentmemory` ja ota käyttöön `plugins.slots.memory = "agentmemory"` tiedostossa `~/.openclaw/openclaw.json`.
```
Täysi opas: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (liitä tämä kehote)
```text
Asenna agentmemory Hermesille. Käynnistä muistipalvelin portissa localhost:3111 suorittamalla komento `npx -y @agentmemory/agentmemory@latest` erillisessä terminaalissa. Lisää sitten tämä tiedostoon ~/.hermes/config.yaml, jotta Hermes voi käyttää agentmemorya MCP-palvelimena ja sen 54 muistityökalua:
mcp_servers:
agentmemory:
command: npx
args: ["-y", "@agentmemory/mcp"]
memory:
provider: agentmemory
Vahvista toiminta komennolla `curl http://localhost:3111/agentmemory/health`. Avaa reaaliaikainen katseluohjelma osoitteessa http://localhost:3113. Syvempää kuuden hookin muistitarjoajaintegraatiota varten (kontekstin lisäys ennen LLM:ää, vuoron tallennus, MEMORY.md-peilaus ja järjestelmäkehotteen lohko) kopioi integrations/hermes repositoriosta https://github.com/rohitg00/agentmemory polkuun ~/.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`
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ä täydentää komentoa `agentmemory connect `:
- `agentmemory connect ` kirjoittaa tavallisesti MCP-asetukset. Hermes, OpenClaw, Pi ja Oh My Pi asentavat oletuksena natiivin integraation ja taidot; MCP otetaan käyttöön valinnalla `--with-mcp`.
- `npx skills add rohitg00/agentmemory` asentaa taidot agenteille, joilla ei ole mukana tulevia natiiveja taitoja. Ohita tämä vaihe Hermesin, OpenClaw’n, Pi:n ja Oh My Pi:n kohdalla; niiden liittimet asentavat taidot jo.
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/` | Plugin tarjoaa elinkaarihookit, työtilan tunnistuksen, taidot ja MCP:n Cursor IDE:ssä ja `cursor-agent`-ohjelmassa. Katso [Cursorin asennus](#cursor). |
| **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 --with-mcp`. natiivi muistihaku + tallennus + taidot. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. natiivi muistihaku + tallennus + taidot. [Oh My Pi](../integrations/omp/). |
| **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, 9 agentmemory-taitoa (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) näkyvät natiivisti Warpin pikakomentopaletissa. |
| **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.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 `config.yaml`-tiedoston, jos asetuksia ei ole, tai muokkaa olemassa olevaa `config.json`-tiedostoa. Olemassa olevan YAML:n tapauksessa se tulostaa lisättävän `mcpServers:`-lohkon säilyttääkseen kommentit ja ankkurit. Continue käyttää taulukkoa, ei objektia. |
| **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` ottaa MCP-työkalut käyttöön. Lisää `--with-hooks` ladataksesi AgentMemoryn mukana tulevan natiivin tallennuslisäosan. Erillistä lisäosapakettia ei tarvita. [DSH](../docs/dsh.md). |
| **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 | Käytä [autentikoituja REST-esimerkkejä](#validate-a-fresh-install-and-restart-persistence) tallentamiseen ja hakemiseen skripteistä. |
| **Tuetut agentit** | Vain taidot | `npx skills add rohitg00/agentmemory`; valitse asennettavat taidot ja kohdeagentit. |
**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)
Käytä [REST API:a](#api) mistä tahansa kielestä tai [MCP-työkaluja](#mcp-server) agentista. REST käyttää JSONia ja bearer-autentikointia; katso [tallennus- ja hakuesimerkki](#validate-a-fresh-install-and-restart-persistence). Suora ympäristöintegraatio kuvataan [Python-esimerkeissä](../examples/python/).
### Lähdekoodista
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
`npm start` käynnistää saman paikallisen palvelimen kuin asennettu CLI. Vaatimukset ovat [asennusohjeessa](#install); API ja viewer kuuntelevat osoitetta `127.0.0.1`.
### Windows
agentmemory toimii Windows 10/11:ssä. WSL2 noudattaa Linuxin polkua ja voi asentaa kiinnitetyn moottorin automaattisesti. Natiivi Windows vaatii iii-engine v0.25.1:n kiinnitetyn binäärin asentamisen käsin; lataa sopiva paketti [iii v0.25.1 -julkaisusivulta](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), tarkista sen tarkistussumma ja sijoita `iii.exe` `PATH`-polkuun (esimerkiksi `%USERPROFILE%\.local\bin\iii.exe`). CLI ei pura Windows-ZIP-pakettia automaattisesti.
Natiivin Windowsin automaattinen MCP-kytkentä tukee vain komentoa `agentmemory connect copilot-cli`. Muiden natiivien Windows-agenttien kanssa käytä manuaalista MCP-lohkoa kohdasta [Muut agentit](#other-agents). Suorita `connect` WSL:ssä vain, kun kohdeagentti on asennettu samaan WSL-ympäristöön.
**Vain itsenäinen MCP (ei moottoria).** Jos tarvitset vain MCP-työkaluja etkä REST-rajapintaa, katseluohjelmaa tai ajonaikaisia palveluita:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# tai
npx -y @agentmemory/mcp
```
Suorita `agentmemory doctor` tai käynnistä uudelleen valinnalla `--verbose`. Jos portit ovat varattuja, käytä `--port ` tai `--instance `. Yhteensopivuus ja palautuminen kuvataan [päivitysoppaassa](../docs/upgrades/iii-0.25.md).
---
Käyttöönotto
Käytä itse ylläpidettyyn palveluun Docker Composea tai alla olevia malleja. Muisti ja tunnistetiedot ovat `/data`-volyymissa; varmuuskopioi ja käytä sitä uudelleen päivityksissä. Autentikointi, verkko, varmuuskopiot ja siirrot kuvataan [käyttöönotto-oppaassa](../deploy/README.md).
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.
REST käyttää porttia `3111` ja viewer porttia `3113`. Pidä ne yksityisinä tai suojaa autentikoinnilla ja TLS:llä. Alustakohtaiset asetukset ja [vanhan Docker-asennuksen siirto](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ovat käyttöönotto-oppaassa.
---
Projektitieto hajautuu keskusteluihin ja ohjetiedostoihin. AgentMemory tuo aiemmat päätökset, korjaukset ja opit haettaviksi nykyisestä agentista.
### 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 |
|---|---|---|
| Ylläpito | Käsin ylläpidetyt ohjeet | Indeksoitu istuntohistoria ja muistot |
| Haku | Lataa kaiken kontekstiin | BM25 + vektori + graafi (vain top-K) |
| 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
-> Stable event ID / durable capture inbox / offline spool
-> Privacy filter (strip secrets, API keys)
-> Store raw observation
-> Synthetic compression by default
(LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
-> Vector embedding when an embedding provider is active
-> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
-> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject context when enabled by the integration
```
### 4-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
Taulukko kuvaa Claude Coden hookit. Muut integraatiot tallentavat ohjelmansa tarjoamat tapahtumat. Automaattinen kontekstin lisäys yhteisten hookien kautta otetaan erikseen käyttöön: `AGENTMEMORY_INJECT_CONTEXT=true`.
| 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** | Natiivien integraatioiden tallentamat tuetut istunto- ja työkalutapahtumat |
| **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.
[0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md).
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 | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) |
| 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` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) |
| Voyage AI | `voyage-code-3` | 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 muodosta yhteys itse ylläpitämääsi palvelimeen) 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 yhdistyessään yhden tilannevedoksen (`GET /agentmemory/viewer/snapshot`) ja käsittelee sen jälkeen reaaliaikaisia tapahtumia SSE:n kautta REST-workerissä osoitteessa `/agentmemory/viewer/events`: uudet muistot, opetukset, havainnot, auditointimerkinnät, graafimuutokset ja terveystiedot näkyvät ilman kyselyitä tai sivun uudelleenlatausta. Muut pyynnöt liittyvät vain napsauttamiisi toimintoihin, "lataa lisää" -sivuihin ja hakuihin. Jos virta katkeaa, katseluohjelma kertoo tietojen iän, yhdistää uudelleen takaisinviiveellä ja synkronoi tiedot 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. Muuhun kuin loopback-osoitteeseen sidottaessa HTML-runko pysyy julkisena, mutta jokainen proxypyyntö vaatii bearer-tunnuksen; katseluohjelma pyytää sitä ja tallentaa sen istuntokohtaiseen tallennustilaan. Määritä eksplisiittiset host/origin-sallittujen listat ja TLS ennen katseluohjelman avaamista. REST-rajapinnan `/agentmemory/viewer`-päätepiste noudattaa normaaleja bearer-token-sääntöjä ja ohjaa selaimet ilman tokenia katseluohjelman porttiin. CSP-otsakkeet käyttävät vastauskohtaista script-noncea ja poistavat käytöstä inline-käsittelijäattribuutit (`script-src-attr 'none'`).
---
### 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
Aloita ilman avainta tallennusta ja avainsanahakua varten. `EMBEDDING_PROVIDER=local` lisää paikallisen semanttisen haun mallin lataamisen jälkeen. LLM-pakkaus vaatii palveluntarjoajan ja asetuksen `AGENTMEMORY_AUTO_COMPRESS=true`; jokainen havainto voi aiheuttaa pyynnön, joten tarkista nykyiset hinnat. Viewer ja `agentmemory status` näyttävät aktiiviset palveluntarjoajat.
### 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
| Port | Tarkoitus | Ympäristömuuttuja |
|---|---|---|
| `3111` | REST API, MCP HTTP ja viewerin reaaliaikaiset tapahtumat | `III_REST_PORT` |
| `3113` | Viewerin käyttöliittymä | `III_VIEWER_PORT` |
`--port ` asettaa REST-portin ja viewerin oletusportiksi `N+2`. `--instance N` luo erillisen ympäristön. Sisäisten porttien on pysyttävä yksityisinä; lue [käyttöönotto-opas](../deploy/README.md) ennen etäkäyttöä.
### Tallennus: tiedosto tai Redis
Oletusarvoinen tiedostotallennus ei tarvitse erillistä tietokantaa. Redis on valinnainen asetuksilla `AGENTMEMORY_STATE_BACKEND=redis` ja `AGENTMEMORY_REDIS_URL`. Taustajärjestelmän vaihto ei kopioi muistia. Pysyvyys, Redisin rajoitukset ja autentikoitu vienti/tuonti kuvataan [tallennusoppaassa](../docs/reliability/state-storage.md).
### Asetustiedosto
Laita agentmemoryn ajonaikaiset asetukset tiedostoon `~/.agentmemory/.env` sen sijaan, että veisit 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ä agentmemory uudelleen. Aseta `AGENTMEMORY_ENV_FILE`, jos haluat käyttää muuta ympäristötiedoston polkua.
Prosessin ympäristömuuttujat ohittavat tiedoston arvot. Käynnistä palvelin uudelleen asetusten muuttamisen jälkeen.
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
Tavalliset asetukset tiedostoon `~/.agentmemory/.env`. Kontekstin lisäys ja pakkaus ovat valinnaisia; pakkaus tarvitsee myös palveluntarjoajan. `core` rajaa näkyviä MCP-työkaluja:
```env
EMBEDDING_PROVIDER=local
# AGENTMEMORY_INJECT_CONTEXT=true
# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
# AUTO_FORGET_ENABLED=false
# LESSON_DECAY_ENABLED=false
# INSIGHT_DECAY_ENABLED=false
```
Täydellinen [`.env.example`](../.env.example) kattaa palveluntarjoajat, tallennussuodattimet, säilytyksen, tallennusratkaisut, tiimit ja valinnaiset ominaisuudet. `AGENTMEMORY_ENV_FILE` valitsee toisen tiedoston. Älä koskaan commitoi täytettyä `.env`-tiedostoa tai bearer-salaisuutta.
---
147 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ä.** Jos `AGENTMEMORY_SECRET` puuttuu, CLI luo ensimmäisellä käynnistyksellä satunnaisen salaisuuden tiedostoon `~/.agentmemory/secret` oikeuksilla `0600` ja kopioi sen myös valittuun datahakemistoon. Kaikki mukana toimitetut asiakkaat lukevat salaisuuden sieltä käyttäessään paikallista palvelinta: CLI, katseluohjelma, `plugin/scripts`-hakemiston hookit, MCP-palvelin ja `@agentmemory/mcp`-shim, `agentmemory connect` -komennon luomat asetukset sekä mukana toimitetut OpenCode-, Pi-, OpenClaw-, Hermes- ja filesystem-watcher-integraatiot. Tallennettu salaisuus lähetetään vain loopback-osoitteisiin (`localhost`, `127.0.0.0/8`, `::1`). Nimenomainen `AGENTMEMORY_SECRET` voittaa aina, ja etäasiakkaiden on asetettava salaisuus ympäristöönsä. Repositorion Docker-itseylläpitokäyttöönotot ja `deploy/`-entrypointit luovat ja vievät oman salaisuutensa. Rajapinnan manuaalinen kutsu:
```bash
curl -H "Authorization: Bearer " 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: [Generoitu REST-viite](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**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.** Vanhojen alkuperätietojen tiivistäminen lykätään käynnistyksessä, koska se lukee vanhat scopet kokonaan. `/agentmemory/status` näyttää tilan `deferred`, tai `off`, kun `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Suorita alla kuvattu manuaalinen tiivistäminen huollon aikana. Hakuindeksin migraatio on erillinen: käytä komentoa `agentmemory graph-index migrate --allow-legacy-scan` [huolto-ohjeen](../docs/reliability/graph-index-migration.md) mukaisesti.
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 "Authorization: Bearer " -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 "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 5,000+ tests
npm run test:integration # API tests (requires running services)
```
Vaatimukset ovat [asennusohjeessa](#install). Osallistumisohjeet ja julkaisutarkistukset ovat [CONTRIBUTING.md](../CONTRIBUTING.md)-tiedostossa.