agentmemory: permanenteng memory para sa mga AI coding agent

Persistent na memory sa iba't ibang coding session at agent.
Permanenteng memory para sa Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, at anumang MCP client.

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

rohitg00/agentmemory | Trendshift

Design doc: 1.7k stars / 240 forks sa gist

Pinalalawak ng gist ang LLM Wiki pattern ni Karpathy gamit ang confidence scoring, lifecycle, knowledge graph, at hybrid search: ang agentmemory ang implementasyon nito.

npm version CI License Stars skills.sh installs

54 MCP tool 12 awtomatikong hook 0 panlabas na DB 5,000+ pumapasang test

Demo ng agentmemory

I-install • Mabilisang Simula • Benchmarks • VS Kompetisyon • Mga Agent • Paano Gumagana • MCP • Viewer • Config • API

--- Nirerekord ng AgentMemory ang coding session para mahanap muli ang mga desisyon at pag-aayos. Gumamit ng iisang memory store sa iba't ibang tool, suriin ang naka-save, at piliin kung gaano karaming context ang matatanggap ng model. ## I-install Mga Kinakailangan: - Node.js 20 o mas bago, kasama ang npm at npx (`node -v`, `npm -v`, at `npx -v`). - Kailangan ng `curl`, POSIX `sh`, at `tar` para sa awtomatikong setup sa macOS/Linux. - Windows / WSL2: [Windows](#windows). Standard na command para sa sariwang pag-install: ```bash npx -y @agentmemory/agentmemory@latest ``` Piliin ang mga agent at provider o keyless mode. Sine-save ng setup ang configuration, pinapatakbo ang memory server, at nag-aalok ng global install. Tinatanggap ng `-y` ang npm prompt; pinipili ng `@latest` ang pinakabagong release. Kailangan ng provider at `AGENTMEMORY_AUTO_COMPRESS=true` para sa LLM compression. Pinapatay ng keyless mode ang vector embeddings. Ginagamit ng `memory_recall` (ang `mem::search` path) ang BM25, habang ang `memory_smart_search` ay maaari ring pagsamahin ang structural graph matches kapag umiiral na ang graph data. Para sa libreng on-device semantic recall, i-set ang `EMBEDDING_PROVIDER=local` sa `~/.agentmemory/.env` at i-restart. Ang unang embedding request ay nag-download ng `Xenova/all-MiniLM-L6-v2`; tumatakbo na lokal ang inference pagkatapos ng unang pag-download na ito ng model. Nasa `http://localhost:3111` ang API at `http://localhost:3113` ang live viewer. Pareho silang naka-bind sa loopback bilang default. Nasa `~/.agentmemory/.env` ang configuration. [Pag-iimbak ng data](#data-storage). Pagkatapos, patunayan na gumagana ang recall at bigyan ang iyong agent ng mga skill nito: ```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 ``` Dapat tumama ang mga keyword search sa default na keyless mode gamit ang BM25. Ang query ng demo na `database performance optimization` ay sadyang semantic at puwedeng magbalik ng zero hanggang hindi pa naka-configure ang isang embedding provider. Mas gusto mo bang ipagawa lahat sa isang coding agent? Bigyan ito ng isang instruction: > Kunin at sundin ang mga instruction sa: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md Magdagdag ng agent gamit ang `agentmemory connect `. Tingnan ang [mga integration](#works-with-every-agent) at [pang-araw-araw na command](#everyday-commands).
Global na Pag-install / EACCES ```bash npm install -g @agentmemory/agentmemory@latest ``` Ang npx command sa itaas ay nananatiling standard na landas para sa bagong pag-install at iniiwasan nito ang mga isyu sa global-prefix permission.
Lumang bersyon ang ibinibigay ng npx Nag-cache ang npx ayon sa bersyon. Pilitin ang paggamit ng pinakabago gamit ang `npx -y @agentmemory/agentmemory@latest`, o burahin ang cache nang isang pagkakataon gamit ang `rm -rf ~/.npm/_npx` (macOS/Linux; sa Windows, burahin ang `%LOCALAPPDATA%\npm-cache\_npx`).
---

Gumagana sa Bawat Agent

Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST API. Ibinabahagi ng lahat ng agent ang parehong memory server.
Claude Code
Claude Code
native plugin + 12 hook + MCP
Codex CLI
Codex CLI
native plugin + 6 hook + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + plugin hook/skill
Cursor
Cursor
native plugin + lifecycle hooks + MCP
OpenCode
OpenCode
capture plugin + MCP
Devin
Devin
6 hook + skill + MCP
OpenClaw
OpenClaw
native plugin + MCP
Hermes
Hermes
native plugin + MCP
pi
pi
native recall + capture + skills
OpenHuman
OpenHuman
native na Memory trait backend
Gemini CLI
Gemini CLI
MCP server
Antigravity
Antigravity
MCP + hook
Claude Desktop
Claude Desktop
MCP server
Warp
Warp
connect + MCP + skill
Zed
Zed
MCP server
Cline
Cline
MCP server
Continue
Continue
MCP server
Droid
Droid
MCP server
Kiro
Kiro
MCP server
Qwen Code
Qwen Code
MCP server
DeepSeek Harness
DeepSeek Harness
native capture + MCP
Roo Code
Roo Code
MCP server
Kilo Code
Kilo Code
MCP server
Goose
Goose
MCP server
Aider
Aider
REST API
Oh My Pi
native recall + capture + skills + Opsyonal na MCP

Gumagana sa anumang agent na nakikipag-usap gamit ang MCP o HTTP. Isang server, ibinabahagi ang mga memory sa lahat ng ito.

--- ### Pag-iimbak ng data Nasa labas ng repository ang memory bilang default. Ginagamit muli ng instance 0 ang kasalukuyang `./data/state_store.db`. Pumili ng lokasyon gamit ang `--data-dir ` o `AGENTMEMORY_DATA_DIR` at panatilihin ang parehong directory sa restart at upgrade. | Platform | Directory ng data | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` Gumagamit ang `--instance 1` ng `instance-1` subdirectory, API port `3211`, at viewer port `3213`. Tingnan ang [storage at backup](../docs/reliability/state-storage.md) para sa Redis at paglipat ng backend. Pinakabagong release notes: [CHANGELOG.md](../CHANGELOG.md). ---

Benchmarks

Kasalukuyang resulta ng paghahanap, kahulugan ng mga sukatan, at mga hakbang sa pag-ulit ng pagsubok: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

VS Kompetisyon

Na-update na paghahambing ng mga produkto at paraan ng deployment, kasama ang mga sanggunian: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

Mabilisang Simula

### Subukan sa 30 Segundo ```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 ``` Nag-seed ang `demo` ng 3 makatotohanang session (JWT auth, N+1 query fix, rate limiting) at pinapatakbo ang mga search laban dito. Pinapatay ng keyless install ang vectors, kaya dapat tumama ang mga `mem::search` keyword query gamit ang BM25 habang puwedeng magbalik ng zero ang `database performance optimization`. Maaari pang ibalik ng `smart-search` ang structural graph matches kapag umiiral ang graph data. Para mahanap ng semantic query ang N+1 fix gamit ang vectors, i-set ang `EMBEDDING_PROVIDER=local`, i-restart, at hintaying matapos ang unang pag-download ng model. Buksan ang `http://localhost:3113` para panoorin ang live na pagbuo ng memory. ### I-validate ang Bagong Install at ang Persistence ng Restart Habang tumatakbo ang server, suriin ang health, viewer, at status. ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` Ipinapakita ng `status` ang server health, provider, embedding mode, capture delivery, at recovery. Kailangan ng server secret ang protected REST requests. Gamitin ang naka-configure na `AGENTMEMORY_SECRET` o basahin ang generated local secret kung wala nito. ```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}' ``` Pagkatapos, patakbuhin ang `npx -y @agentmemory/agentmemory@latest stop`, simulan ulit ang standard na command sa Terminal 1, hintayin ang `/agentmemory/livez`, at ulitin ang search. Dapat pa ring ibalik ang probe. Kung pumili ka ng custom na `--data-dir`, ipasa ang parehong directory sa restart. ### Mga Pang-araw-araw na Command Ang install at setup ay nasa [I-install](#install) sa itaas (gagabayan ka ng unang pagpapatakbo). Sa pang-araw-araw: ```bash agentmemory # start the server agentmemory stop # stop it cleanly agentmemory status # health, providers and recovery state agentmemory capture # inspect capture inbox and offline spool agentmemory capture --drain # replay queued observations agentmemory connect # connect another agent agentmemory doctor # interactive diagnostics + fix prompts agentmemory remove # uninstall everything we created ``` ### Replay ng Session Replayable ang bawat session na itinatala ng agentmemory. Buksan ang viewer, piliin ang tab na **Replay**, at mag-scrub sa timeline: ang mga prompt, tool call, tool result, at response ay nag-render bilang hiwalay na event na may play/pause, speed control (0.5x hanggang 4x), at keyboard shortcut (space para i-toggle, arrow para mag-step). Para dalhin ang mga mas lumang Claude Code JSONL transcript: ```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 ``` Lumalabas ang imported sessions kasama ng native sessions sa Replay, naka-index para sa search, at may origin channel na `import`. Maaari ring gumawa ng crystals at lessons ang session processing. > **Paalala kung aasa ka sa `import-jsonl` bilang pangunahing capture path:** Awtomatikong binubura ng `cleanupPeriodDays` ng Claude Code (sa `~/.claude/settings.json`, default na **30**) ang mga JSONL transcript na mas matanda sa window na iyon mula sa `~/.claude/projects/`. Kung mag-install ka ng bagong agentmemory sa isang Claude Code history na may edad na ilang buwan, wala na ang anumang mas matanda sa 30 araw bago pa man ang unang import. Patakbuhin ang `import-jsonl` sa isang cron, itaas ang `cleanupPeriodDays` sa mas mataas, o i-wire ang auto-capture hooks (ang default na plugin install path) para makarating sa agentmemory ang bawat turn habang live ang session at hindi na mahalaga ang JSONL cleanup. ### Upgrade / Maintenance Gamitin ang maintenance command kapag sinasadya mong i-update ang iyong local runtime: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` Ina-update nito ang local runtime at maaaring baguhin ang JavaScript dependencies sa kasalukuyang working directory. I-backup ang data at basahin ang [upgrade guide](../docs/upgrades/iii-0.25.md) bago mag-update ng umiiral na installation. ### Claude Code (isang block, i-paste ito) ```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 nang walang plugin install (MCP-standalone path) Kung i-wire mo ang MCP server ng agentmemory gamit ang `~/.claude.json` (default na path) nang direkta sa halip na gamitin ang `/plugin install`, hindi kailanman nireresolba ng Claude Code ang `${CLAUDE_PLUGIN_ROOT}` at kailangan mong ituro ang hook scripts sa absolute paths sa `~/.claude/settings.json` (default na path). Karaniwang naka-embed sa mga path na ito ang bersyon ng agentmemory (hal. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), kaya tahimik na masisira ng susunod na upgrade ang bawat hook. Workaround: ```bash agentmemory connect claude-code --with-hooks ``` Kino-configure ng command na ito ang MCP server at pinagsasama ang mga bundled hook sa user configuration ng Claude Code. Kung hindi naka-set ang `CLAUDE_CONFIG_DIR`, blangko ito, o puro whitespace ang laman, ginagamit nito ang `~/.claude.json` para sa MCP at `~/.claude/settings.json` para sa mga hook. Ginagamit ang iba pang directory value nang eksakto sa ibinigay, kasama ang whitespace sa simula at dulo. Para sa custom na directory, itakda ang `CLAUDE_CONFIG_DIR` sa parehong hindi blangkong value para sa command na ito at sa Claude Code; ang mga file ay magiging `$CLAUDE_CONFIG_DIR/.claude.json` at `$CLAUDE_CONFIG_DIR/settings.json`, ayon sa pagkakasunod. Kailangang matanggap ng Claude Code ang value na ito sa environment na ginagamit sa paglulunsad nito, kahit binabasa ito ng connector mula sa `.env` ng AgentMemory. Gawin ang custom na directory bago patakbuhin ang command na ito; kung wala ito, lalaktawan ng connector ang Claude Code dahil hindi ito ma-detect. Kung puro whitespace ang value sa shell, alisin ang `CLAUDE_CONFIG_DIR` sa environment bago ilunsad ang Claude Code para gamitin din nito ang default na profile. Gumamit ng absolute path. Ang mga relative path ay nakabatay sa working directory, kaya dapat patakbuhin ang parehong command mula sa iisang directory. Gumagamit ang mga hook command ng absolute paths patungo sa bundled na `plugin/` directory ng naka-install na package. Patakbuhin muli ang command pagkatapos i-upgrade ang agentmemory upang i-refresh ang mga path. Pinananatili ang mga entry ng user sa mga configuration file; ang mga dating entry ng agentmemory lamang ang pinapalitan. Ang paggamit ng `/plugin install` pa rin ang inirerekomendang paraan. Para sa remote o protected deployment, patakbuhin ang Claude Code na naka-set ang `AGENTMEMORY_URL` at `AGENTMEMORY_SECRET`. Ipinapasa ng plugin ang dalawang value papunta sa bundled MCP server nito; kapag walang laman ang `AGENTMEMORY_URL`, gumagamit ang MCP shim ng `http://localhost:3111`. ### Codex CLI (Codex plugin platform) ```bash # 1. start the memory server in a separate terminal npx -y @agentmemory/agentmemory@latest # 2. register the agentmemory marketplace and install the plugin codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` Ang Codex plugin ay nag-ship mula sa parehong `plugin/` directory ng Claude Code plugin. Irehistro nito ang: - Isang bundled stdio MCP bridge sa tumatakbong daemon, walang npm download o fallback store. Tingnan ang [local Codex guide](../docs/plugins/codex-local.md) para subukan ang isang unreleased build. - 6 lifecycle hook: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop` - 9 invocable na skill: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, kasama ang 8 reference skill na nilo-load ng agent kapag kailangan (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, at ang skill-authoring guide) Itinuturok ng hook engine ng Codex ang `CLAUDE_PLUGIN_ROOT` sa mga hook subprocess (ayon sa [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), kaya gumagana ang parehong hook script sa dalawang host nang walang duplication. Ang mga event na Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure ay Claude-Code-only lamang at hindi nirerehistro para sa Codex. #### Trust at compatibility ng Codex hook Na-verify ang native plugin hook dispatch gamit ang Codex CLI 0.150.1. I-trust ang plugin hooks bago asahan ang capture. Ang behavior ng Desktop ay depende sa bundled runtime nito; i-check ang `/hooks` at kumpirmahin ang isang na-capture na event bago paganahin ang isang workaround. Kapag kailangan ng host mo ang global hooks, i-mirror ang mga command sa `~/.codex/hooks.json`. Kapag naka-wire na ang MCP, kailangan ng kasalukuyang connector ang `--force` para maabot ang hook installation: ```bash agentmemory connect codex --with-hooks --force ``` Pinagsasama nito ang global hooks at isinusulat ulit ang agentmemory MCP entry, habang napapanatili ang mga entry na walang kaugnayan. Suriin ang anumang custom na agentmemory endpoint settings mo bago gamitin ang `--force`. Patakbuhin ulit pagkatapos i-upgrade para i-refresh ang mga script path. Paganahin ang isa sa dalawa: native plugin hooks o global copies, para iwasan ang duplicate capture. ### GitHub Copilot CLI Para sa VS Code agent mode, gamitin ang [Copilot MCP at automatic-capture guide](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Hindi i-configure ng CLI connector na ito ang VS Code. ```bash # MCP-only wiring agentmemory connect copilot-cli # Alternatively, full hooks/skills plugin from the GitHub subdir copilot plugin install rohitg00/agentmemory:plugin ``` Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory` sa `~/.copilot/mcp-config.json` (o `$COPILOT_HOME/mcp-config.json` kapag naka-set ang `COPILOT_HOME`) at pinapanatili ang mga umiiral na server. Sa native Windows, ito lamang ang awtomatikong `connect` adapter; i-configure nang manu-mano ang lahat ng iba pang native Windows agent. Suportado lamang ang WSL `connect` kapag naka-install din ang target agent sa parehong WSL environment. Kukunin ng Copilot ang MCP server sa susunod na launch o pagkatapos ng `/mcp`. I-install din ang plugin kapag gusto mo ang buong hook/skill na karanasan. ### Cursor I-configure ang MCP gamit ang `agentmemory connect cursor`. Sa **Settings → Plugins → Add marketplace**, piliin ang checkout na may `.cursor-plugin/plugin.json`, paganahin ang agentmemory, at i-reload. May lifecycle capture, workspace attribution, skills, at MCP ang plugin. Paganahin lang ang plugin hooks o manual hooks sa `~/.cursor/hooks.json` para maiwasan ang dobleng capture. [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 ``` Piliin ang command para sa host mo. Nag-i-install ang Pi at OMP ng native recall/capture, offline replay, at 17 skills; idinadagdag ng `--with-mcp` ang buong toolset. Patakbuhin ang `/reload` sa Pi o i-restart ang OMP, saka tingnan ang `/agentmemory-status`. Ini-install ng DSH ang MCP at bundled capture plugin; i-restart pagkatapos kumonekta. May installable na `@agentmemory/pi` package din ang Pi. Tingnan ang [Pi guide](../integrations/pi/) para sa local install at availability sa npm. Gumamit ng isang paraan ng install sa bawat host. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
OpenClaw (i-paste ang prompt na ito) ```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`. ``` Kumpletong gabay: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (i-paste ang prompt na ito) ```text Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: command: npx args: ["-y", "@agentmemory/mcp"] memory: provider: agentmemory Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from https://github.com/rohitg00/agentmemory to ~/.hermes/plugins/agentmemory. ``` Kumpletong gabay: [`integrations/hermes/`](../integrations/hermes/)
### Iba Pang Agent Simulan ang memory server: `npx -y @agentmemory/agentmemory@latest` #### Native na skill gamit ang `npx skills add` Nag-ship ang agentmemory ng 17 skill sa Claude-Code-style na `/SKILL.md` format: 9 invocable na action skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) at 8 reference skill na nilo-load ng agent kapag kailangan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). May dala ang mga reference skill na data table na nabuo mula sa source, kaya hindi ito kailanman nadrift. Ang [`skills`](https://npmjs.com/package/skills) CLI ng vercel-labs ay awtomatikong nag-install nito sa native skill directory ng tumatawag na agent sa 50+ agent (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, at iba pa): ```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 ``` Ito ay **komplementaryo** sa `agentmemory connect `: Ini-install ng Hermes, OpenClaw, Pi, at Oh My Pi connectors ang native integration at skills bilang default; idagdag ang MCP gamit ang `--with-mcp`. Sa ibang host, mag-install ng skills gamit ang `npx skills add rohitg00/agentmemory`. Para sa ilang agent na hindi pa saklaw ng skills CLI (Zed v1.3.x pababa), ilagay mo mismo ang 17 SKILL.md file sa ilalim ng native skill directory ng agent; gumagana ang parehong format kahit saan. #### Standard na MCP Block Ang entry ng agentmemory ay ang **parehong MCP server block** sa bawat host na gumagamit ng `mcpServers` shape (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}" } } ``` **I-merge ang entry na ito sa umiiral na `mcpServers` object** sa config file ng host; huwag palitan ang file. Kung may iba na ang file na mga server, idagdag ang `agentmemory` sa tabi nila bilang isa pang key sa loob ng `mcpServers`. Kung wala talaga ang `mcpServers`, i-paste ang block sa loob ng `{ "mcpServers": { ... } }`. Minana ng mga `${VAR}` placeholder ang `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` mula sa shell sa oras ng paglunsad ng MCP server; nagpapasa ng walang-lamang string ang mga unset var at babalik ang shim sa `http://localhost:3111`. Sapat ang isang wired na entry para sa local at remote (k8s / reverse-proxied) deployment. | Agent | Config file | Mga Tala | |---|---|---| | **Cursor (MCP lamang)** | `~/.cursor/mcp.json` | I-merge sa `mcpServers`, o `agentmemory connect cursor`. May one-click deeplink din sa website. | | **Cursor (buong plugin)** | `.cursor-plugin/` | I-install sa Cursor Marketplace o Settings → Plugins → local checkout. Nirerehistro ang lifecycle hooks sa pamamagitan ng maliit na adapter na tumatawag sa shared `plugin/scripts/*.mjs`, kasama ang skills at MCP. Tinutukoy ng adapter ang workspace na hindi palaging tama ang ulat ng Cursor. Tingnan ang [Cursor](#cursor). Gumagana sa Cursor IDE at `cursor-agent` CLI. | | **Claude Desktop** | `claude_desktop_config.json` (Application Support) | I-merge sa `mcpServers`. I-restart ang Claude Desktop pagkatapos i-edit. | | **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Parehong `mcpServers` block. | | **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | Pinagsasama ng `agentmemory connect devin` ang MCP entry; idinadagdag ng `--with-hooks` ang anim na native na auto-capture hook (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) gamit ang lowercase na tool matcher ng Devin. Patunayan gamit ang `devin mcp list` at `/hooks` sa loob ng devin. | | **Devin CLI (buong plugin)** | `plugin/.devin-plugin/` | Nirerehistro ng `devin plugins install ./plugin` mula sa isang checkout ang lahat ng 17 skill bilang `/agentmemory:` slash command kasama ang MCP server. Hindi kayang paandarin ng Devin plugin hooks ang `SessionStart`/`SessionEnd`, kaya ipares ito sa `connect devin --with-hooks` para sa buong session capture. | | **Devin (cloud)** | Settings → Connections → MCP servers | Magdagdag ng custom na MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` na itinuturo sa isang network-reachable na agentmemory deployment kasama ang `AGENTMEMORY_SECRET` (hindi maaabot ng cloud session ang localhost — tingnan ang [`../deploy/`](../deploy/)). Itago ang secret sa Devin Secrets, pagkatapos gamitin ang "Test listing tools" para patunayan na lumalabas ang lahat ng 54 tool. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (awtomatikong nag-merge). | | **GitHub Copilot CLI (MCP lamang)** | `~/.copilot/mcp-config.json` | Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory`; kukunin ito ng Copilot sa susunod na launch o `/mcp`. | | **GitHub Copilot CLI (buong plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` para sa plugin mula sa GitHub subdir. | | **OpenClaw** | OpenClaw MCP config | Parehong `mcpServers` block. Mas malalim: angkin ng `openclaw plugins install ./integrations/openclaw` ang memory slot ng OpenClaw (awtomatikong lilipat mula sa `memory-core`); i-set ang `plugins.entries.agentmemory.hooks.allowConversationAccess=true` o tahimik na haharangin ang turn capture. Tingnan ang [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (MCP lamang)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, o idagdag ang `[mcp_servers.agentmemory]` nang manu-mano. | | **Codex CLI (buong plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` pagkatapos `codex plugin add agentmemory@agentmemory`. Nirerehistro ang MCP + 6 lifecycle hook + 17 skill. I-trust ang hooks at i-verify ang capture sa host mo; tingnan ang [Codex setup at validation](../docs/plugins/codex-local.md). | | **OpenCode (MCP lamang)** | `opencode.json` | Ibang shape: top-level na `mcp` key, command bilang array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (buong plugin)** | `plugin/opencode/` | 22 auto-capture hook na sumasaklaw sa session lifecycle, messages, tools, errors. Per-session ang project attribution, kaya ang isang OpenCode process na saklaw ang ilang repository ay nagtatala ng bawat session sa ilalim ng sarili nitong project. Dalawang slash command (`/recall`, `/remember`). Kopyahin ang `plugin/opencode/` sa iyong OpenCode workspace at idagdag ang plugin entry sa `opencode.json`. Tingnan ang [`plugin/opencode/README.md`](../plugin/opencode/README.md) para sa buong hook table + gap analysis. | | **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · native recall + capture + skills. [Pi](../integrations/pi/) | | **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · native recall + capture + skills. [Oh My Pi](../integrations/omp/) | | **Hermes Agent** | `~/.hermes/config.yaml` | Ang `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ay magbibigay ng 6-hook na memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block). Patunayan gamit ang `hermes plugins doctor` at `hermes memory status`. Tingnan ang [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | Isinusulat ng `agentmemory connect qwen` ang standard na `mcpServers` block. Field-compatible ang hook payload sa Claude Code, kaya gumagana ang umiiral na 12-hook scripts nang walang pagbabago; i-wire ito gamit ang `hooks` section sa parehong `settings.json`. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | Ini-install ng `agentmemory connect antigravity --with-hooks` ang MCP at capture hooks sa shared customization directory. Tingnan ang [setup at limitasyon ng Antigravity](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | Ginagamit ng `agentmemory connect antigravity-cli --with-hooks` ang parehong MCP at hook configuration ng kasalukuyang mga bersyon ng IDE. Dapat i-refresh ng mga umiiral na installation gamit ang `--force`; tingnan ang [upgrade notes](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | Isinusulat ng `agentmemory connect kiro` ang user-level config. Ang workspace override ay sa `.kiro/settings/mcp.json`, katabi ng iyong code. | | **Warp** | `~/.warp/.mcp.json` | Isinusulat ng `agentmemory connect warp` ang standard na `mcpServers` block. Awtomatikong nadidiskubre din ng Warp ang mga skill mula sa `.claude/skills/`; kapag naka-install na ang Claude Code plugin, lumalabas nang native ang 9 agentmemory skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) sa slash-command palette ng Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.json` | Isinusulat ng `agentmemory connect cline` ang standard na `mcpServers` block. Para sa VS Code extension user: i-paste ang parehong block sa Cline Settings → MCP Servers → Edit JSON. | | **Continue.dev** | `~/.continue/config.yaml` (preferred) o `config.json` (legacy) | Gumagawa ang `agentmemory connect continue` ng `config.yaml` kung wala pang configuration o ina-update ang kasalukuyang `config.json`. Hindi nito binabago ang umiiral na YAML upang mapanatili ang comments at anchors; ipinapakita ang block na ilalagay sa ilalim ng `mcpServers:`. Array ang gamit ng Continue para sa `mcpServers`. | | **Zed** | `~/.config/zed/settings.json` | Isinusulat ng `agentmemory connect zed` sa ilalim ng `context_servers` (ang key ng Zed, HINDI `mcpServers`). Maaaring i-wire ang remote MCP server gamit ang `{"url": "..."}` sa halip. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | Isinusulat ng `agentmemory connect droid` ang standard na `mcpServers` block. Ang project-scoped override ay sa `/.factory/mcp.json`. Ipasa ang `--with-hooks` para sa native auto-capture. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Ina-activate ng `agentmemory connect dsh` ang mga MCP tool. Idagdag ang `--with-hooks` para i-load ang native capture plugin na kasama sa AgentMemory. Hindi kailangan ng hiwalay na plugin package. [DSH](../docs/dsh.md). | | **Goose** | Goose MCP settings UI | Parehong `mcpServers` block; gamitin ang `goose configure` → Add Extension → MCP. Suportado ang direktang YAML edit sa `~/.config/goose/config.yaml` pero ang schema ay gumagamit ng `extensions:` + `cmd` (hindi `mcpServers:` + `command`). | | **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) | | **Mga suportadong agent** | Skills lamang | `npx skills add rohitg00/agentmemory`; piliin ang skills na ii-install at ang mga target na agent. | **Mga sandboxed MCP client** (Flatpak / Snap / restrictive container) na hindi maabot ang `localhost` ng host: i-set din ang `"AGENTMEMORY_FORCE_PROXY": "1"` sa `env` block, at ituro ang `AGENTMEMORY_URL` sa isang route na talagang maabot ng sandbox (hal. ang LAN IP mo). ### Programmatic access Gamitin ang [REST API](#api) mula sa anumang wika o [MCP tools](#mcp-server) mula sa agent. JSON at Bearer authentication ang gamit ng REST; tingnan ang [halimbawa ng save at search](#validate-a-fresh-install-and-restart-persistence). Nasa [Python examples](../examples/python/) ang direktang runtime integration. ### Mula sa Source ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` Pinapatakbo ng `npm start` ang kaparehong local server ng naka-install na CLI. Nasa [Install](#install) ang mga kailangan; naka-bind ang API at viewer sa `127.0.0.1`. ### Windows Tumatakbo ang agentmemory sa Windows 10/11. Awtomatikong nag-i-install ng engine ang WSL2 gamit ang Linux path. Sa native Windows, manu-manong i-install ang pinned na iii-engine v0.25.1: i-download ang archive mula sa [iii v0.25.1 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1), tiyakin ang checksum, at ilagay ang `iii.exe` sa `PATH`. Hindi awtomatikong nag-e-extract ng ZIP ang CLI Native Windows MCP automation ay para lamang sa `agentmemory connect copilot-cli`; gamitin ang manual MCP block sa [Other agents](#other-agents) para sa iba. Sa WSL, patakbuhin ang `connect` lamang kung naroon din ang target agent **Standalone MCP lang (walang engine).** Kung MCP tools lamang ang kailangan, at hindi ang REST API, viewer o runtime services: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` Patakbuhin ang `agentmemory doctor` o i-restart gamit ang `--verbose`. Kung ginagamit na ang default ports, gumamit ng `--port ` o `--instance `. Tingnan ang [upgrade guide](../docs/upgrades/iii-0.25.md) para sa compatibility at recovery. ---

Pag-deploy

Mag-self-host gamit ang Docker Compose o mga platform template sa ibaba. Nasa `/data` volume ang memory at credentials. I-backup at gamitin muli ang volume sa upgrade. Tingnan ang [deployment guide](../deploy/README.md) para sa authentication, network, at migration.

I-deploy sa fly.io I-deploy sa Railway

Kinakailangan ng one-click deploy button ng Render ang `render.yaml` sa repository root, na sinadya naming panatilihing malinis. Gamitin ang Render Blueprint flow na nakadokumento sa [`../deploy/render/`](.././deploy/render/README.md) para ituro nang manu-mano ang in-repo blueprint. Nasa [`../deploy/`](.././deploy/README.md) ang kumpletong detalye ng setup (HMAC capture, viewer SSH tunnel, rotation, backup, cost floor): - [`../deploy/fly`](.././deploy/fly/README.md): isang machine na may `auto_stop_machines = "stop"`; pinakamura kapag idle. - [`../deploy/railway`](.././deploy/railway/README.md): Hobby plan na flat fee, volume sa dashboard. - [`../deploy/render`](.././deploy/render/README.md): Blueprint flow, awtomatikong disk snapshot sa mga paid plan. - [`../deploy/coolify`](.././deploy/coolify/README.md): self-hosted sa sariling VPS mo gamit ang [Coolify](https://coolify.io/self-hosted); parehong Docker Compose stack, ikaw ang may-ari ng host at ng data. Port `3111` ang gamit ng REST at `3113` ng viewer. Panatilihing pribado ang access o protektahan gamit ang authentication at TLS. Nasa deployment guide ang platform access settings at [paglipat mula sa lumang Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode). ---

Bakit agentmemory

Nagkakahiwa-hiwalay ang kaalaman sa proyekto sa mga chat at instruction file. Sa AgentMemory, mahahanap ng kasalukuyan mong agent ang mga dating desisyon, pag-aayos, at aral. ```text Session 1: "Add auth to the API" Agent writes code, runs tests, fixes bugs Connected hooks capture supported tool events Observations become searchable project history Session 2: "Now add rate limiting" Agent recalls: - Auth uses JWT middleware in src/middleware/auth.ts - Tests in test/auth.test.ts cover token validation - You chose jose over jsonwebtoken for Edge compatibility Continues with the earlier decisions in context. ``` ### Kumpara sa Built-in na Memory ng Agent Nag-ship ang bawat AI coding agent na may built-in memory: may `MEMORY.md` ang Claude Code, may notepad ang Cursor, may memory bank ang Cline. Gumagana ang mga ito gaya ng sticky note. Ang agentmemory ang searchable database sa likod ng mga sticky note. | | Built-in (CLAUDE.md) | agentmemory | |---|---|---| | Pagpapanatili | Manu-manong inayos na instructions | Naka-index na session history at memory | | Paghahanap | Nilo-load ang lahat sa context | BM25 + vector + graph (top-K lamang) | | Cross-agent | Per-agent na file | MCP + REST (kahit anong agent) | | Koordinasyon | Wala | Lease, signal, action, routine | | Observability | Basahin ang mga file nang manu-mano | Real-time viewer sa :3113 | ---

Paano Gumagana

### Memory Pipeline ```text PostToolUse hook fires -> Stable event ID / durable capture inbox / offline spool -> Privacy filter (strip secrets, API keys) -> Store raw observation -> Synthetic compression by default (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled Stop / SessionEnd hook fires -> Summarize session -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true) -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject context when enabled by the integration ``` ### 4-Tier Memory Consolidation Hinubog batay sa paano pinoproseso ng utak ng tao ang memory, kasama ang sleep consolidation. | Tier | Ano | Analohiya | |------|------|---------| | **Working** | Raw na obserbasyon mula sa paggamit ng tool | Panandaliang memory | | **Episodic** | Pinaikling buod ng session | "Ano ang Nangyari" | | **Semantic** | Mga nakuhang fact at pattern | "Ano ang Alam Ko" | | **Procedural** | Mga workflow at decision pattern | "Paano Ito Gawin" | Nauupos ang mga memory sa paglipas ng panahon (Ebbinghaus curve). Lumalakas ang mga madalas i-access na memory. Awtomatikong naaalis ang mga stale na memory. Nadidiskubre at naresolba ang mga kontradiksyon. ### Ano ang Nakukuha Inilalarawan ng talahanayan ang hooks ng Claude Code. Nirerekord ng ibang integration ang events na ibinibigay ng kanilang host. Opt-in ang awtomatikong context injection sa shared hooks gamit ang `AGENTMEMORY_INJECT_CONTEXT=true`. | Hook | Nakukuha | |------|----------| | `SessionStart` | Project path, session ID | | `UserPromptSubmit` | User prompt (privacy-filtered) | | `PreToolUse` | File access pattern + enriched context | | `PostToolUse` | Tool name, input, output | | `PostToolUseFailure` | Error context | | `PreCompact` | Itinuturok ulit ang memory bago ang compaction | | `SubagentStart/Stop` | Sub-agent lifecycle | | `Stop` | Buod sa katapusan ng session | | `SessionEnd` | Marker ng kumpletong session | ### Mga Pangunahing Kakayahan | Kakayahan | Paglalarawan | |---|---| | **Awtomatikong capture** | Nirerekord ng native integrations ang suportadong session at tool events | | **Semantic search** | BM25 + vector + knowledge graph na may RRF fusion | | **Ebolusyon ng memory** | Versioning, supersession, relationship graph | | **Recall hygiene** | Umaalis sa search index ang mga superseded na bersyon ng memory; pinapanatili ng version chain sa KV ang buong history | | **Near-duplicate hint** | Nag-uulat ang mga save ng advisory na `similarTo` match kapag malapit na kahawig ng umiiral na memory ang bagong content | | **Per-agent scoping** | Dumadaan ang `agentId` sa save at recall sa REST, MCP, at ang search index, sa shared o isolated mode | | **Write-time provenance** | May dalang hindi-nababagong origin channel (user, agent, tool, import, o shared) ang bawat obserbasyon at memory, na tinatakan sa capture, save, at import | | **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction | | **Privacy muna** | Tinatanggal ang mga API key, secret, `` tag bago ang storage | | **Self-healing** | Circuit breaker, provider fallback chain, health monitoring | | **Claude bridge** | Bi-directional sync sa MEMORY.md | | **Knowledge graph** | Entity extraction + BFS traversal | | **Team memory** | Namespaced shared + private sa mga miyembro ng team | | **Citation provenance** | Subaybayan ang anumang memory pabalik sa source observation | | **Git snapshot** | I-version, i-rollback, at i-diff ang memory state | --- Triple-stream retrieval na pinagsasama ang tatlong signal: | Stream | Ano ang Ginagawa Nito | Kailan | |---|---|---| | **BM25** | Stemmed keyword matching na may synonym expansion | Palaging naka-on | | **Vector** | Cosine similarity sa dense embeddings | Naka-configure ang embedding provider | | **Graph** | Knowledge graph traversal gamit ang entity matching | May nadetektang entity sa query | Pinagsasama gamit ang Reciprocal Rank Fusion (RRF, k=60) at session-diversified (max 3 resulta kada session). Kapag napupuno ang isang vector index, ginagamit ng `mem::search` (sa likod ng `memory_recall`) ang hybrid na BM25 + vector ranker. Kapag walang embeddings, ginagamit nito ang BM25. Maaari pang pagsamahin ng `smart-search` ang structural graph matches kapag umiiral ang graph data, kasama na sa keyless mode. Tumatakbo ang lesson recall sa isang dedikadong in-memory BM25 index sa halip na i-scan ang buong corpus kada query. Hindi kasama sa bawat recall path ang mga superseded na bersyon ng memory; pinapanatili ng version chain ang kanilang history. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). Tinotokenize ng BM25 ang Griyego, Cyrillic, Hebreo, Arabic, at accented Latin nang out of the box. Para sa mga memory sa Chinese / Japanese / Korean, i-install ang opsyonal na segmenter (`npm install @node-rs/jieba tiny-segmenter`) para hatiin ang mga CJK run sa word-level token; kung wala ito, soft-falls ang agentmemory sa whole-run tokenization at nagprint ng one-time hint sa stderr. ### Mga Embedding Provider Pinapatay ng keyless install ang vector embeddings: ginagamit ng `mem::search` ang BM25, habang maaari pang gamitin ng `smart-search` ang umiiral na structural graph data. Para opt in sa libreng on-device semantic embeddings, idagdag ito sa `~/.agentmemory/.env` at i-restart ang agentmemory: ```env EMBEDDING_PROVIDER=local ``` Kasama sa normal na npm install ang opsyonal na `@huggingface/transformers` runtime. Nag-download ang unang embedding request ng `Xenova/all-MiniLM-L6-v2`, kaya kailangan nito ng network access at maaaring tumagal; tumatakbo na on-device ang susunod na inference. Awtomatikong nadidiskubre ang mga remote provider mula sa kanilang keys maliban kung na-override ito ng `EMBEDDING_PROVIDER`. | Provider | Model | Gastos | Mga Tala | |---|---|---|---| | **Local (inirerekomendang opt-in)** | `all-MiniLM-L6-v2` | Libre | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | Gemini | `gemini-embedding-001` | Free tier | 100+ wika, 768/1536/3072 dims (MRL), 2048-token input. Pumalit sa `text-embedding-004` ([deprecated, magsasara noong Jan 14, 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` | Bayad | Na-optimize para sa code | | Cohere | `embed-english-v3.0` | Free trial | Pangkalahatang gamit | | OpenRouter | Kahit anong model | Depende | Multi-model proxy | ---

MCP Server

54 na tool, 6 na resource, 3 na prompt, at 17 na skill. > **MCP shim laban sa buong server:** ang pinublish na `@agentmemory/mcp` package ay isang manipis na shim. Ilalantad nito ang buong 54-tool surface **lamang kapag kaya nitong maabot ang isang tumatakbong agentmemory server** gamit ang `AGENTMEMORY_URL` (proxy mode). Kung walang maabot na server, babalik ang shim sa isang 7-tool na lokal na set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Ang `AGENTMEMORY_TOOLS=core|all` env var ay isang *server-side* na flag; walang epekto ang pag-set nito sa `env` block ng shim. Kung 7 tool lamang ang nakikita mo sa Cursor / OpenCode / Gemini CLI, simulan ang `npx -y @agentmemory/agentmemory@latest` (o ang Docker stack) at i-set ang `AGENTMEMORY_URL=http://localhost:3111`. ### 54 na Tool Tatlong tool surface, mula sa pinakamaliit hanggang pinakamalaki: binabawasan ng `AGENTMEMORY_TOOLS=core` ang visibility sa 8 mahahalagang tool (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); ang base set sa ibaba ay ang 14 foundational tool ng registry; ang default (`AGENTMEMORY_TOOLS=all`) ay ilalantad ang lahat ng 54.
Base tool (14) | Tool | Paglalarawan | |------|-------------| | `memory_recall` | Hanapin ang nakaraang obserbasyon | | `memory_compress_file` | I-compress ang mga markdown file habang pinapanatili ang structure | | `memory_save` | I-save ang isang insight, desisyon, o pattern | | `memory_file_history` | Mga nakaraang obserbasyon tungkol sa partikular na file | | `memory_patterns` | Tuklasin ang mga umuulit na pattern | | `memory_sessions` | Ilista ang mga kamakailang session | | `memory_smart_search` | Hybrid semantic + keyword search | | `memory_vision_search` | Hanapin ang mga obserbasyon ng imahe | | `memory_timeline` | Obserbasyon ayon sa pagkakasunod-sunod ng oras | | `memory_profile` | Profile ng project (concept, file, pattern) | | `memory_export` | I-export ang lahat ng memory data | | `memory_relations` | Query ang relationship graph | | `memory_commit_lookup` | Mga session sa likod ng isang git commit | | `memory_commits` | Mga commit na naitala para sa isang session |
Extended tool (54 lahat, ang default surface) | Tool | Paglalarawan | |------|-------------| | `memory_patterns` | Tuklasin ang mga umuulit na pattern | | `memory_timeline` | Obserbasyon ayon sa pagkakasunod-sunod ng oras | | `memory_relations` | Query ang relationship graph | | `memory_graph_query` | Knowledge graph traversal | | `memory_consolidate` | Patakbuhin ang 4-tier consolidation | | `memory_claude_bridge_sync` | I-sync sa MEMORY.md | | `memory_team_share` | Ibahagi sa mga miyembro ng team | | `memory_team_feed` | Mga kamakailang ibinahaging item | | `memory_audit` | Audit trail ng mga operation | | `memory_governance_delete` | Burahin na may audit trail | | `memory_snapshot_create` | Git-versioned na snapshot | | `memory_action_create` | Gumawa ng work item na may dependency | | `memory_action_update` | I-update ang status ng action | | `memory_frontier` | Mga unblocked na action na naayos ayon sa priority | | `memory_next` | Ang pinakamahalagang susunod na action | | `memory_lease` | Exclusive na action lease (multi-agent) | | `memory_routine_run` | I-instantiate ang mga workflow routine | | `memory_signal_send` | Pagmemensahe sa pagitan ng agent | | `memory_signal_read` | Basahin ang mga mensahe na may receipt | | `memory_checkpoint` | Panlabas na condition gate | | `memory_mesh_sync` | P2P sync sa pagitan ng instance | | `memory_sentinel_create` | Event-driven na watcher | | `memory_sentinel_trigger` | Patakbuhin ang mga sentinel mula sa labas | | `memory_sketch_create` | Ephemeral na action graph | | `memory_sketch_promote` | I-promote sa permanente | | `memory_crystallize` | I-compact ang mga action chain | | `memory_diagnose` | Health check | | `memory_heal` | Awtomatikong ayusin ang stuck na state | | `memory_facet_tag` | Dimension:value tag | | `memory_facet_query` | Query ayon sa facet tag | | `memory_verify` | Subaybayan ang provenance |
### 6 Resource · 3 Prompt · 17 Skill | Type | Pangalan | Paglalarawan | |------|------|-------------| | Resource | `agentmemory://status` | Health, bilang ng session, bilang ng memory | | Resource | `agentmemory://project/{name}/profile` | Per-project intelligence | | Resource | `agentmemory://project/{name}/recent` | Mga kamakailang obserbasyon para sa isang project | | Resource | `agentmemory://memories/latest` | Pinakabagong 10 aktibong memory | | Resource | `agentmemory://graph/stats` | Statistics ng knowledge graph | | Resource | `agentmemory://team/{id}/profile` | Shared na profile ng team | | Prompt | `recall_context` | Maghanap + ibalik ang mga context message | | Prompt | `session_handoff` | Handoff data sa pagitan ng agent | | Prompt | `detect_patterns` | Suriin ang mga umuulit na pattern | | Skill | `/recall` | Hanapin ang memory | | Skill | `/remember` | I-save sa long-term memory | | Skill | `/session-history` | Mga buod ng kamakailang session | | Skill | `/forget` | Burahin ang mga obserbasyon/session | Ipinapakita ng table ang apat na core skill. Ang buong set ay 9 invocable na skill kasama ang 8 reference skill; tingnan ang Native skills section sa itaas. ### Standalone MCP Patakbuhin nang walang buong server, para sa kahit anong MCP client. Gumagana ang alinman sa mga ito: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` O idagdag sa MCP config ng iyong agent: Karamihan sa mga agent (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` I-merge ang entry ng `agentmemory` sa umiiral na `mcpServers` object ng host sa halip na palitan ang file. Para sa mga sandboxed client na hindi maabot ang `localhost` ng host, idagdag ang `"AGENTMEMORY_FORCE_PROXY": "1"` sa env block at i-set ang `AGENTMEMORY_URL` sa isang route na maaabot ng sandbox. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` Kopyahin ang plugin file mula sa repo: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

Real-Time na Viewer

Awtomatikong nagsisimula sa port `3113`. Nag-load ang viewer ng isang snapshot kapag kumonekta ito (`GET /agentmemory/viewer/snapshot`) at pagkatapos ay ilalapat ang mga live stream event: lumalabas ang mga bagong memory, lesson, obserbasyon, audit entry, pagbabago sa graph, at health update nang walang polling o page reload. Ang iba lamang na request ay ang mga action na iyong kinliklik, ang mga "load more" page at search. Kapag nawala ang stream, ipinapakita ng viewer kung gaano na katanda ang mga numero nito, kumokonekta ulit nang may backoff at nireresync mula sa isang snapshot. - **12 tab sa apat na grupo** na may live count, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), keyboard shortcut at isang mobile menu. - **Memories:** server-side search, filter ayon sa project, agent, at type, isang detail panel na may version chain at word diff, provenance link, copy button para sa id, ang MCP call at isang curl command, edit (bagong bersyon), forget na may confirmation, bulk forget at JSON export. - **Sessions:** inline na observation timeline na may nababasang tool input at output, filter at paging, at ang mga memory at lesson na nabuo ng bawat session. - **Graph:** search, detalye ng node na may relation at source, isang legend na hindi umaasa sa kulay lamang, at zoom control. - **Health:** ang live na bersyon ng `GET /agentmemory/status`. May kasamang fix ang bawat problema, kasama ang state backend, index save state, progress ng graph provenance compaction, at isang consolidation explainer na may tunay na threshold. - Mga pahina ng **Audit, Activity, Profile, Replay, Lessons, Actions, at Crystals**, na bawat isa ay may empty state na nagsasabi kung ano ang section, bakit ito walang laman, at ang command na magpupuno nito, at isang `?` glossary tooltip sa bawat termino at numero. ```bash open http://localhost:3113 ``` Nagbibind ang viewer server sa `127.0.0.1` bilang default at idinadagdag nito ang server secret kapag ipinapasa ang mga request sa REST API, kaya walang kailangang i-setup. Sumusunod ang `/agentmemory/viewer` endpoint na naka-serve sa REST sa normal na bearer-token rules at nireredirect ang mga browser na walang token papunta sa viewer port. Gumagamit ang CSP headers ng per-response script nonce at pinapatay ang inline handler attributes (`script-src-attr 'none'`). ---

Konfigurasyon

### Mga LLM Provider Awtomatikong tinutuklas ng agentmemory ang mga provider mula sa iyong environment. Pinagagana ng isang provider ang mga LLM-backed operation, pero ang configuration ng provider lamang ay hindi nagpapagana ng LLM-written na observation compression. Kailangan ng path na iyon ang parehong provider at `AGENTMEMORY_AUTO_COMPRESS=true`. | Provider | Config | Mga Tala | |----------|--------|-------| | **No-op (default)** | Walang kailangang config | Naka-disable ang LLM-backed compress/summarize. Gumagana pa rin ang synthetic compression at BM25 recall. Tingnan ang `AGENTMEMORY_ALLOW_AGENT_SDK` sa ibaba kung dati kang umaasa sa Claude-subscription fallback. | | Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing | | MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible | | Gemini | `GEMINI_API_KEY` | Pinagagana din ang embeddings | | OpenRouter | `OPENROUTER_API_KEY` | Kahit anong model | | OpenAI API | `OPENAI_API_KEY` | Default `gpt-5.6-luna`, i-override gamit ang `OPENAI_MODEL` | | **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) o `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Anumang OpenAI-API-compatible. Zero cost, tumatakbo sa iyong hardware. Tingnan ang [Mga Local Model](#local-models-ollama--lm-studio--vllm) sa ibaba. | | Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in lamang. Nag-spawn ng mga `@anthropic-ai/claude-agent-sdk` session; dati itong nagdudulot ng unbounded Stop-hook recursion, kaya hindi na ito ang default. | ### Mga Local Model (Ollama / LM Studio / vLLM) Kinakausap ng agentmemory ang anumang OpenAI-API-compatible na server, kaya gumagana nang walang pagbabago sa code ang anumang naglalantad ng `/v1/chat/completions`. Walang bayad na key, walang cloud, walang rate limit; tumatakbo nang buo sa iyong hardware. **Ollama** (default port `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** (default port `1234`): Buksan ang LM Studio → Local Server tab → Start Server. Piliin ang kahit anong chat model mula sa picker (Qwen 3, gpt-oss, DeepSeek R1, atbp.). ```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**: parehong shape. Ituro ang `OPENAI_BASE_URL` sa kung anumang URL na inilalantad ng iyong server at i-set ang `OPENAI_MODEL` sa isang pangalang tatanggapin ng iyong server. **Pagpili ng model para sa memory work**: ang compression at summarization ay mga maikling task (<2K token papasok, <500 token palabas) kung saan sapat na ang isang 7B instruct model. Mga rekomendasyon: | Model | Laki | Bakit | |-------|------|-----| | `qwen3:8b` | ~5.2 GB | Balanced na default sa 16 GB machine; malakas sa extraction at tool-shaped na text | | `qwen3:4b` | ~2.6 GB | Pinakamaliit na makatwirang opsyon; sapat para sa compression, mahina para sa graph extraction | | `qwen3-coder:30b` | ~19 GB | Pinakamagandang local pick para sa code-shaped na session (30B MoE, 3.3B active) sa 24-32 GB hardware | | `gpt-oss:20b` | ~14 GB | Malakas na general model na kasya sa 16 GB RAM | | `deepseek-r1:8b` | ~5.2 GB | Reasoning distill; mas mabagal pero mas malinis ang extraction | Nag-iisip ang mga Qwen 3 model bilang default at maaaring maubos ang buong token budget sa reasoning bago ang anumang output. I-set ang `AGENTMEMORY_LLM_NOTHINK=1` para idagdag ang `/no_think` sa mga graph-extraction prompt, at itaas ang `MAX_TOKENS` (gumagana ang 16384) kung nagbabalik na walang-lamang ang mga extraction. Maaaring magbalik ang mga reasoning-class model (`o1`-style na may `` block) ng walang-lamang `content` na may `reasoning` field na posibleng hindi ilantad ng iyong local server. Kung nagbabalik na blangko ang mga extraction, lumipat muna sa isang non-reasoning na model. Maaari din i-disable ng env na `OPENAI_REASONING_EFFORT=none` ang thinking sa mga Ollama Cloud thinking model na sumasalamin sa OpenAI reasoning schema. Nag-ship ang local embeddings bilang opsyonal na dependency pero hindi ito naka-enable bilang default. I-set ang `EMBEDDING_PROVIDER=local` para opt in sa `Xenova/all-MiniLM-L6-v2` (384-dim). Nag-download ng model ang unang embedding request; on-device na ang inference pagkatapos. Kung walang setting na iyon o remote embedding key, mananatiling naka-disable ang vectors, gagamit ang `mem::search` ng BM25, at maaari pa ring idagdag ng `smart-search` ang umiiral na graph matches. ### Cost-aware na Pagpili ng Model Magsimula nang walang key para sa capture at keyword search. Nagbibigay ang `EMBEDDING_PROVIDER=local` ng semantic search sa device matapos ang unang model download. Kailangan ng provider at `AGENTMEMORY_AUTO_COMPRESS=true` ang LLM compression, at maaaring may request kada observation; suriin ang kasalukuyang presyo. `agentmemory status` / http://localhost:3113 ### Multi-agent na Memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) Sa multi-agent setup kung saan nagbabahagi ng isang agentmemory server ang ilang role (architect / developer / reviewer / researcher / support-agent), tinatakan ng `AGENT_ID` ang bawat sulat gamit ang role na gumawa nito. Kinokontrol ng `AGENTMEMORY_AGENT_SCOPE` kung mag-filter ang recall ayon sa tag na iyon. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` Dalawang mode: | Mode | Tinatakan ang Sulat | Nag-filter ang Recall | Kailan Gagamitin | |------|------------|---------------|-------------| | `shared` (default) | oo | hindi | Cross-agent na context na may audit trail. Makikita ng architect ang naitala ng developer, pero itinatala ng bawat row kung sino ang nagsabi nito. | | `isolated` | oo | oo | Mahigpit na paghihiwalay. Hindi kailanman makikita ng architect ang mga obserbasyon / memory / session ng developer. | Ang natatakan kapag naka-set ang `AGENT_ID`: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Dumadaloy ang role mula sa `api::session::start` → `mem::observe` → `mem::compress` → KV. Ang na-filter sa isolated mode: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Tinatanggap ng bawat endpoint ang `?agentId=` para i-override kada-request, at `?agentId=*` para lumabas nang buo sa env scope. Tinatanggap din ng `/memories` ang `?includeOrphans=true` para ilantad ang mga pre-AGENT_ID na memory na hindi defined ang `agentId`. Per-call override sa SDK / REST layer: tinatanggap ng bawat mutating endpoint (`/session/start`, `/remember`) ang isang `agentId` field sa request body na nananaig kaysa sa env. Kapaki-pakinabang para sa mga runtime na nagruruta ng maraming role sa isang server process. Inilalantad ng MCP tool na `memory_save` ang parehong `agentId` field, ipinapasa ng standalone stdio server ang parehong `agentId` at `project`, at dala ng mga na-save na memory ang `agentId` papunta sa search index, kaya saklaw ng agent-scoped search ang mga memory gayundin ang mga obserbasyon. Kapag hindi naka-set ang `AGENT_ID`, nananatiling unscoped ang memory (legacy behavior, walang tag, walang filter). ### Mga Port Naka-bind sa loopback ang API at viewer bilang default. | Port | API / Viewer | Env | |---|---|---| | `3111` | REST / MCP / SSE | `III_REST_PORT` | | `3113` | Viewer | `III_VIEWER_PORT` | Itinatakda ng `--port ` ang API port; `N+2` ang default ng viewer. Gumamit ng `--instance N` para sa hiwalay na instance. Panatilihing pribado ang internal listeners. Sundin ang deployment guide para sa remote access at [paglipat mula sa lumang Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode). ### Storage Backend: file (default) laban sa redis Hindi kailangan ng hiwalay na database service. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. Hindi awtomatikong kinokopya ang umiiral na memory kapag nagpalit ng backend. [Pag-iimbak ng data](../docs/reliability/state-storage.md). ### Config File Ilagay ang runtime config sa `~/.agentmemory/.env` sa halip na mag-export ng variables sa bawat shell. Gamitin ang `AGENTMEMORY_ENV_FILE` upang pumili ng ibang env-file path. Mas mataas ang priority ng process environment variables kaysa sa file. Ipinapasa ng CLI-generated Worker Compose project ang Redis settings sa `state` worker. ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` Para magsubok gamit ang isang Claude Code Pro/Max subscription sa halip ng isang API key, opt in nang tahasan: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` Kailangan ng LLM-written na observation compression ang parehong linya: access sa isang LLM provider (kasama ang tahasang subscription fallback na ito) at `AGENTMEMORY_AUTO_COMPRESS=true`. Iiwanan ng provider mismo ang default na synthetic compression path. Naka-on bilang default ang consolidation (graph node, lesson, crystal) sa tuwing naka-configure ang isang LLM provider. Tahasang opt out gamit ang `CONSOLIDATION_ENABLED=false` kung nais mo ng LLM-free operation. Hiwalay na flag ang graph extraction: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### Mga Environment Variable `~/.agentmemory/.env`: ```env EMBEDDING_PROVIDER=local # AGENTMEMORY_INJECT_CONTEXT=true # AGENTMEMORY_AUTO_COMPRESS=true # AGENTMEMORY_TOOLS=core # AUTO_FORGET_ENABLED=false # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` Nasa [`.env.example`](../.env.example) ang buong reference, kasama ang provider, capture filter, retention, storage, at team scope. Pumili ng ibang file gamit ang `AGENTMEMORY_ENV_FILE`. I-restart pagkatapos magbago ng configuration. Huwag i-commit ang `.env` na may aktuwal na halaga o Bearer secret. ---

API

147 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer `, at kinakailangan ng mga mesh sync endpoint ang tahasang naka-set na `AGENTMEMORY_SECRET` sa dalawang peer. Naka-on ang authentication bilang default. Kapag walang `AGENTMEMORY_SECRET`, gumagawa ang CLI ng random secret sa unang start sa `~/.agentmemory/secret` at kinokopya sa `secret` ng napiling data directory, na may mode `0600`. Inuuna ng bundled clients ang canonical file sa local connection at ipinapadala lang ang naka-save na secret sa loopback URL. Mas mataas ang prayoridad ng explicit na `AGENTMEMORY_SECRET`; dapat itong itakda ng remote clients sa environment. Gumagawa ang Docker deployment ng sarili nitong secret. ```bash curl -H "Authorization: Bearer " http://localhost:3111/agentmemory/health ``` **Mga Tuntunin ng Request para sa Sulat.** Dapat magpadala ng `Content-Type: application/json` (okay ang isang `charset` parameter) ang mga request na `POST`, `PUT`, `PATCH` at `DELETE` papunta sa REST API at sa viewer sa tuwing may dala itong body, at ang isang `Origin` header, kapag naroroon, ay dapat isang loopback origin para sa naka-configure na REST o viewer port o nakalista sa `VIEWER_ALLOWED_ORIGINS` (comma-separated, hal. `https://memory.example.com`). Hindi apektado ang mga client na walang ipinapadalang `Origin` header (CLI, hooks, MCP, curl, server-to-server). Tinatanggap din ng viewer ang sariling origin nito. **Mga File Path.** Ang mga endpoint na nagbabasa o nagsusulat ng file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) ay tumatanggap lamang ng mga path sa ilalim ng `~/.agentmemory`, ang instance data directory, o isang directory na nakalista sa `AGENTMEMORY_IMPORT_ROOT` (paghiwalayin ang ilan gamit ang `:`, o `;` sa Windows). Tinatanggap din ng `/replay/import-jsonl` ang default nitong `~/.claude/projects`. Nananatili ang `/obsidian/export` sa loob ng `AGENTMEMORY_EXPORT_ROOT` at ang `/migrate` sa loob ng `~/.agentmemory`. Nireresolba ang mga symlink bago ang bawat check. **Secret Scrubbing.** Ang mga API key, bearer token, PEM private key block, at credential na naka-embed sa mga URL (`scheme://user:password@host`) ay nire-redact bago maitago ang text, sa bawat write path: obserbasyon, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, compression at summary output, crystal, at graph node.
Mga Pangunahing Endpoint | Method | Path | Paglalarawan | |--------|------|-------------| | `GET` | `/agentmemory/health` | Health check (laging public) | | `GET` | `/agentmemory/status` | Ano ang mali at paano ito aayusin (HTML para sa browser, JSON kung hindi) | | `GET` | `/agentmemory/viewer/snapshot` | Lahat ng ipinapakita ng viewer, sa isang response | | `POST` | `/agentmemory/session/start` | Simulan ang session + kunin ang context | | `POST` | `/agentmemory/session/end` | Tapusin ang session | | `POST` | `/agentmemory/observe` | Kunin ang obserbasyon (tingnan ang capture delivery sa ibaba) | | `GET` | `/agentmemory/capture` | Capture inbox, dead letter, at offline spool | | `POST` | `/agentmemory/capture/retry` | Ulitin ang mga dead-letter capture | | `POST` | `/agentmemory/capture/drain` | Ipadala na ang local offline spool | | `POST` | `/agentmemory/smart-search` | Hybrid search | | `POST` | `/agentmemory/context` | Buuin ang context | | `POST` | `/agentmemory/remember` | I-save sa long-term memory | | `POST` | `/agentmemory/forget` | Burahin ang mga obserbasyon | | `POST` | `/agentmemory/enrich` | File context + memory + bug | | `GET` | `/agentmemory/profile` | Profile ng project | | `GET` | `/agentmemory/export` | I-export ang lahat ng data | | `POST` | `/agentmemory/import` | I-import mula sa JSON | | `POST` | `/agentmemory/graph/query` | Knowledge graph query | | `POST` | `/agentmemory/graph/compact` | Putulin ang oversized na graph provenance | | `POST` | `/agentmemory/team/share` | Ibahagi sa team | | `GET` | `/agentmemory/audit` | Audit trail | Kumpletong listahan ng endpoint: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**Capture Delivery.** Ipinapadala ng hooks ang bawat obserbasyon isang beses sa `POST /agentmemory/observe` na may `eventId`. Ito ang sariling id ng host para sa call kapag may isa ang payload (halimbawa ang `tool_use_id` ng Claude Code), kung hindi ay isang hash ng session, hook type, tool name, input, output, at host timestamp. Isusulat ng server ang event sa isang capture inbox sa state store, itinatago ang obserbasyon, pagkatapos tanggalin ang inbox entry. Sinasabi ng status code kung ano ang nangyari: | Status | `status` field | Kahulugan | |---|---|---| | `201` | `accepted` | Naitago. Ang `observationId` ay ang bagong obserbasyon. | | `202` | `accepted` (`state: "retrying"`) | Tinanggap, pero nabigo ang pag-store. Uulitin ito ng server, maging pagkatapos ng isang restart. | | `200` | `duplicate` | Natanggap na dati ang `eventId` na ito. Ang `observationId` ay ang umiiral na obserbasyon; walang bagong naitago. | | `400` / `422` | `rejected` | Hindi valid ang payload, o permanenteng nabigo ang pag-store (itinatago ang event bilang dead letter). | | `503` | `rejected` (`retryable: true`) | Puno ang inbox (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Isinusulat ng hooks ang event sa spool at ipapadala ito mamaya. | Uulitin ang mga nabigong event kada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) na may doubling backoff, hanggang `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Ang mga event na nananatiling nabigo ay nananatili sa inbox bilang dead letter, nililista sa `/agentmemory/status` at sa Health page ng viewer, at maaaring ulitin gamit ang `POST /agentmemory/capture/retry` (`{"eventId": "..."}` o `{"all": true}`). Naaalala ang mga tinanggap na event id sa loob ng `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 oras, pinakamarami na `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), kaya ang isang hook na nireplay pagkatapos ng isang timeout o isang restart ay naitatago isang beses lamang, habang dalawang hiwalay na tool call na may sariling host id ay naitatago nang dalawang beses kahit magkapareho ang nilalaman. Kapag nabura ang isang obserbasyon (forget, session delete, eviction, auto-forget, o isang import na pumapalit sa store), minamarkahan ang event nito bilang nabura bago matanggal ang obserbasyon, kaya ang isang replay ng event na iyon sa loob ng parehong window ay sinasagot bilang duplicate at walang itinatago. Isinusulat ng state store sa disk kada 2 segundo, kaya ang isang sinagot na event ay maaaring nasa memory lamang sandali. Para masaklaw ito, dala rin ng bawat `2xx` na sagot ang `bootId` ng server (bago sa bawat start), `acceptedAt`, at `durableAfterMs` (ang save interval kasama ang 1.5 s sa file store, 1.5 s sa redis, kung saan ang persistence ay setting ng operator). Itinatago ng hooks ang event sa local spool hanggang lumipas ang window na iyon at tinatanggal ito sa isang susunod na call nang walang karagdagang request. Kung nagbago na ang `bootId` sa oras na iyon, nag-restart ang server, kaya ipinapadala ulit ng hook ang event gamit ang parehong `eventId`; ang isang event na nakarating na sa disk ay hindi naitatago nang dalawang beses. Ipinapadala rin ng server mismo ang mga event na ito sa start at sa bawat retry interval, kaya walang mawawala sa isang restart kahit walang tumakbong hook pagkatapos. Hindi pinapansin ng mas lumang hooks ang mga extra field, at itinatapon ng mga bagong hooks laban sa isang mas lumang server ang event sa `2xx` gaya ng dati. Kapag down ang server, hindi sumagot sa oras, o nagbalik ng 5xx, idinadagdag ng hook ang obserbasyon sa isang local spool file, `/capture-spool/-.jsonl` (i-override ang folder gamit ang `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Private sa iyong user ang file (mode 600), nire-redact ang mga secret sa parehong paraan na nire-redact ito ng server, hawak nito ang pinakamarami na `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) at itinatapon ang mga entry na mas matanda sa `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Kapag puno na, itinatapon at binibilang ang mga bagong entry, at iniulat ito ng `/agentmemory/status`. Nag-exit pa rin ng 0 ang hook sa loob ng time limit nito at hindi nagdadagdag ng request kapag healthy ang server. Ipinapadala ang spool sa susunod na start at ng unang hook na maabot ulit ang server, sa isang background process para hindi maghintay ang agent. Ginagawang ligtas ito ng event id: ang isang obserbasyon na nakarating na bago ang isang timeout ay hindi naitatago nang dalawang beses. Ipinapakita ng `npx @agentmemory/agentmemory capture` ang spool at ang inbox ng server, ipinapadala ng `--drain` ang spool ngayon, at ibinabalik ng `GET /agentmemory/capture` ang pareho bilang JSON. I-set ang `AGENTMEMORY_CAPTURE_SPOOL=false` para patayin ang spool. **Compacting Graph Provenance.** Ipinagpapaliban sa startup ang compaction ng lumang provenance dahil binabasa nito ang buong lumang scopes. Ipinapakita ng `/agentmemory/status` ang `deferred`, o `off` kapag `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Patakbuhin ang manual compaction sa ibaba habang nagme-maintenance. Hiwalay ang migration ng retrieval index: gamitin ang `agentmemory graph-index migrate --allow-legacy-scan` ayon sa [gabay sa maintenance](../docs/reliability/graph-index-migration.md). Para patakbuhin ito nang manu-mano, tawagin ang `POST /agentmemory/graph/compact`. Dumadaan ito sa name at edge-key indexes sa halip na ilista ang bawat node at edge, at ligtas itong patakbuhin ulit. Kapag pinuputol nito ang mga id, isinusulat nito ang isang `graph_compact` audit entry. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{}' ``` Sa isang malaking store, o kapag nagbalik ng 504 ang call, patakbuhin ito sa mga slice. Ipadala ang `scope` (`nodes`, `edges` o `history`), `offset` at `limit`, pagkatapos tawagin ulit gamit ang ibinalik na `nextOffset` hanggang `null` ito. Gawin ito para sa `nodes`, `edges`, at `history`, at tapusin gamit ang isang `{"scope":"snapshot"}` call, dahil hindi ginagalaw ng isang sliced run ang cached snapshot. ```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"}' ``` ---

Pagpapaunlad

```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) ``` Tingnan ang [Install](#install) para sa requirements at [CONTRIBUTING.md](../CONTRIBUTING.md) para sa contribution rules at release checks.

Lisensya

[Apache-2.0](../LICENSE)