Initialize Hugging Face Space deployment for AgentMemory Python (clean without assets)

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "agentmemory",
+  "owner": {
+    "name": "Rohit Ghumare",
+    "github": "rohitg00"
+  },
+  "plugins": [
+    {
+      "name": "agentmemory",
+      "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions",
+      "source": "./plugin"
+    }
+  ]
+}

.codex-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "agentmemory",
+  "interface": {
+    "displayName": "agentmemory"
+  },
+  "plugins": [
+    {
+      "name": "agentmemory",
+      "source": {
+        "source": "git-subdir",
+        "url": "https://github.com/rohitg00/agentmemory.git",
+        "path": "./plugin",
+        "ref": "main"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Memory"
+    }
+  ]
+}

.env.example

@@ -0,0 +1,175 @@
+# =============================================================================
+# agentmemory configuration
+# =============================================================================
+#
+# Copy this file to `~/.agentmemory/.env` (or to your project root if you
+# prefer scoped config) and uncomment the lines you want to override.
+#
+# Every line is OFF by default — `agentmemory` runs out of the box with no
+# LLM key, no embedding key, and no API auth. Set keys here only when you
+# want to enable the corresponding feature.
+#
+# Run `npx @agentmemory/agentmemory init` to copy this file into place
+# automatically. Run `npx @agentmemory/agentmemory doctor` to verify that
+# the daemon reads the env you expect.
+#
+# Defaults shown in comments. Listed in priority order — the first key
+# present wins on the LLM detection path (see src/config.ts::detectProvider).
+
+# -----------------------------------------------------------------------------
+# 1. LLM provider — pick ONE
+# -----------------------------------------------------------------------------
+#
+# Without a provider key, agentmemory runs in noop mode: observations are
+# indexed via zero-LLM synthetic compression, hybrid search still works,
+# but LLM-backed summarisation / reflection / consolidation are disabled.
+# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
+# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
+
+# OPENAI_API_KEY=sk-...                          # Used for OpenAI-compatible embeddings today. PR #307 will extend this to chat completions (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`).
+# OPENAI_BASE_URL=https://api.openai.com         # Override for OpenAI-compatible providers
+
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_MODEL=claude-sonnet-4-20250514       # Default Anthropic model
+# ANTHROPIC_BASE_URL=https://api.anthropic.com   # Override for Anthropic-compatible proxies / Azure AI Foundry
+
+# GEMINI_API_KEY=...                             # Either env name works; GEMINI_API_KEY takes precedence
+# GOOGLE_API_KEY=...                             # Alias for GEMINI_API_KEY when set alone (emits a one-time stderr hint)
+# GEMINI_MODEL=gemini-2.5-flash                  # Default Gemini model (auto-detected GA model)
+
+# OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514
+
+# MINIMAX_API_KEY=...
+# MINIMAX_MODEL=MiniMax-M2.7
+
+# MAX_TOKENS=4096                                # Cap LLM completion tokens for compression / summarise calls
+
+# Outbound LLM / embedding timeout — shared across every raw-fetch provider
+# (Gemini, OpenRouter, MiniMax, OpenAI LLM, and OpenAI/Cohere/Voyage/OpenRouter
+# embedding). The OpenAI LLM path also honours the OpenAI-scoped
+# OPENAI_TIMEOUT_MS alias for back-compat with v0.9.17 (precedence).
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000                # Default: 60 000 ms (60 s)
+
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk
+# child sessions). Off by default — the agent-sdk fallback can trigger
+# Stop-hook recursion (#149 follow-up) when invoked from inside Claude Code.
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# FALLBACK_PROVIDERS=anthropic,gemini            # Comma-separated chain tried after the primary provider returns an error (e.g. rate limit)
+
+# -----------------------------------------------------------------------------
+# 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
+# -----------------------------------------------------------------------------
+#
+# Without an embedding key, agentmemory runs in BM25-only mode for hybrid
+# search. Detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
+# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
+# local (Xenova/all-MiniLM-L6-v2, 384-dim).
+
+# EMBEDDING_PROVIDER=local                       # local | openai | voyage | cohere | gemini | openrouter
+
+# VOYAGE_API_KEY=pa-...                          # Optimised for code embeddings
+
+# COHERE_API_KEY=...                             # General-purpose embeddings
+
+# Reuses OPENAI_API_KEY / OPENAI_BASE_URL above when EMBEDDING_PROVIDER=openai.
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # Embedding model when EMBEDDING_PROVIDER=openai
+# OPENAI_EMBEDDING_DIMENSIONS=1536               # Required when the model is not in the known-models table
+
+# OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small  # When EMBEDDING_PROVIDER=openrouter
+
+# -----------------------------------------------------------------------------
+# 3. Auth & security
+# -----------------------------------------------------------------------------
+#
+# Bearer-token auth for the REST API + viewer + all integration plugins.
+# Without a secret, REST endpoints are open on loopback. Set this when
+# you expose the daemon beyond loopback or run behind a reverse proxy.
+
+# AGENTMEMORY_SECRET=your-secret-here
+
+# -----------------------------------------------------------------------------
+# 4. Search tuning
+# -----------------------------------------------------------------------------
+
+# BM25_WEIGHT=0.4                                # Hybrid search weight for BM25 leg
+# VECTOR_WEIGHT=0.6                              # Hybrid search weight for vector leg
+# AGENTMEMORY_GRAPH_WEIGHT=0.2                   # Graph traversal bonus on smart-search ranking
+# TOKEN_BUDGET=2000                              # Max tokens injected via mem::context per session
+# MAX_OBS_PER_SESSION=500                        # Per-session observation cap before consolidation kicks in
+# SUMMARIZE_CHUNK_SIZE=400                       # When mem::summarize sees a session larger than this, it chunks observations and map-reduces (chunk-summarize → reduce-merge) to stay within the LLM's context window. Default 400 ≈ 50k tokens per chunk at ~110 tok/obs. Native sessions are capped by MAX_OBS_PER_SESSION; chunking primarily matters for bulk-imported jsonl sessions, which bypass that cap.
+# SUMMARIZE_CHUNK_CONCURRENCY=6                  # Parallel chunk LLM calls during chunked summarize. Default 6 fits ~100-chunk sessions under iii's 180s function-invocation timeout at typical ~8s/call. High-throughput providers (Novita, DeepInfra, DeepSeek) commonly allow 100+ concurrent — bump this for very large imported sessions.
+
+# -----------------------------------------------------------------------------
+# 5. Behaviour flags
+# -----------------------------------------------------------------------------
+
+# AGENTMEMORY_AUTO_COMPRESS=true                 # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
+# AGENTMEMORY_INJECT_CONTEXT=true                # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
+# CONSOLIDATION_ENABLED=true                     # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost.
+# CONSOLIDATION_DECAY_DAYS=30                    # Age (days) after which non-reinforced memories decay during consolidation
+# GRAPH_EXTRACTION_ENABLED=true                  # Extract concept-graph edges on remember; powers the graph-traversal recall path
+# GRAPH_EXTRACTION_BATCH_SIZE=8                  # Memories per graph-extraction batch
+# AGENTMEMORY_REFLECT=true                       # Periodically auto-synthesize lessons from memories
+# AGENTMEMORY_DROP_STALE_INDEX=true              # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
+# AGENTMEMORY_IMAGE_EMBEDDINGS=true              # Enable image embeddings when an image provider is present (experimental).
+
+# -----------------------------------------------------------------------------
+# 6. CLI / runtime knobs
+# -----------------------------------------------------------------------------
+
+# AGENTMEMORY_TOOLS=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
+# AGENTMEMORY_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
+# AGENTMEMORY_DEBUG=1                            # Trace MCP shim probe + standalone fallback decisions to stderr
+# AGENTMEMORY_FORCE_PROXY=1                      # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)
+# AGENTMEMORY_PROBE_TIMEOUT_MS=2000              # MCP shim livez probe timeout
+# AGENTMEMORY_URL=http://localhost:3111          # REST base URL — honored by status, doctor, MCP shim
+# AGENTMEMORY_VIEWER_URL=http://localhost:3113   # Override the viewer URL printed by `agentmemory status`
+# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup   # Default destination for `agentmemory export`
+
+# STANDALONE_MCP=1                               # MCP shim only — bypass the worker and run @agentmemory/mcp in-process
+# STANDALONE_PERSIST_PATH=~/.agentmemory/local.db  # Path used by the standalone MCP shim's local fallback store
+
+# Snapshot exporter — periodic snapshots of state_store + stream_store.
+# SNAPSHOT_ENABLED=true
+# SNAPSHOT_DIR=~/.agentmemory/snapshots
+# SNAPSHOT_INTERVAL=3600                         # Seconds between snapshots
+
+# Team sharing — when set, memories are scoped to (TEAM_ID, USER_ID) tuples.
+# TEAM_MODE=shared
+# TEAM_ID=acme
+# USER_ID=rohit
+
+# -----------------------------------------------------------------------------
+# 7. Ports
+# -----------------------------------------------------------------------------
+
+# III_REST_PORT=3111                             # REST API port (also affects viewer at +2)
+# III_STREAMS_PORT=3112                          # Streams API port
+# III_ENGINE_URL=ws://localhost:49134            # iii-engine WebSocket URL (used by the worker)
+
+# -----------------------------------------------------------------------------
+# 8. iii engine pin
+# -----------------------------------------------------------------------------
+#
+# agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
+# new sandbox-everything-via-`iii worker add` model that agentmemory
+# hasn't been refactored for yet. Override with AGENTMEMORY_III_VERSION
+# only after migrating to the sandbox model manually.
+
+# AGENTMEMORY_III_VERSION=0.11.2
+
+# -----------------------------------------------------------------------------
+# 9. Claude Code bridge (opt-in)
+# -----------------------------------------------------------------------------
+
+# CLAUDE_MEMORY_BRIDGE=true                      # Mirror compressed memories into Claude Code's CLAUDE.md
+# CLAUDE_PROJECT_PATH=/path/to/your/project      # Required when CLAUDE_MEMORY_BRIDGE=true
+# CLAUDE_MEMORY_LINE_BUDGET=200                  # Lines of memory CLAUDE.md should hold
+
+# -----------------------------------------------------------------------------
+# 10. Obsidian export (opt-in)
+# -----------------------------------------------------------------------------
+
+# OBSIDIAN_AUTO_EXPORT=true                      # Auto-export memories to an Obsidian vault on every consolidation

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [rohitg00]

.github/dependabot.yml

@@ -0,0 +1,110 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    open-pull-requests-limit: 10
+    labels:
+      - dependencies
+      - npm
+    commit-message:
+      prefix: deps
+      include: scope
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: npm
+    directory: /website
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    open-pull-requests-limit: 10
+    labels:
+      - dependencies
+      - npm
+      - website
+    commit-message:
+      prefix: deps(website)
+      include: scope
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: npm
+    directory: /integrations/openclaw
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - npm
+      - integrations
+    commit-message:
+      prefix: deps(openclaw)
+      include: scope
+
+  - package-ecosystem: npm
+    directory: /integrations/pi
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - npm
+      - integrations
+    commit-message:
+      prefix: deps(pi)
+      include: scope
+
+  - package-ecosystem: npm
+    directory: /integrations/filesystem-watcher
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - npm
+      - integrations
+    commit-message:
+      prefix: deps(fs-watcher)
+      include: scope
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Etc/UTC
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - github-actions
+    commit-message:
+      prefix: ci(deps)
+      include: scope
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch

.github/security-advisories/01-viewer-xss.md

@@ -0,0 +1,46 @@
+# GHSA Draft: Stored XSS in agentmemory real-time viewer
+
+**Severity:** Critical · **CVSS 3.1:** 9.6 (`AV:N/AC:L/PR:N/UI:R/S:C/C:H/I:H/A:L`)
+**CWE:** [CWE-79 — Improper Neutralization of Input During Web Page Generation](https://cwe.mitre.org/data/definitions/79.html)
+**Affected versions:** `< 0.8.2`
+**Patched version:** `0.8.2`
+
+## Summary
+
+agentmemory's real-time viewer (default port 3113) rendered user-controlled data — tool outputs, file paths, memory titles, observation content — into HTML using inline `onclick=` event handlers. The viewer's Content Security Policy simultaneously allowed `script-src 'unsafe-inline'`, meaning injected JavaScript would execute in the reader's browser context.
+
+## Impact
+
+Any data captured by agentmemory hooks — which includes tool output from Claude Code, Cursor, or any other agent — becomes an XSS vector when the user opens the viewer. An attacker with the ability to influence any captured observation (e.g., by sending a crafted file contents to be read by an agent, or by planting a malicious commit message in a repository) could:
+
+- Exfiltrate the entire memory store via authenticated requests from the browser
+- Read `AGENTMEMORY_SECRET` if the viewer was configured with auth
+- Make requests to arbitrary endpoints on behalf of the viewer user
+- Modify the DOM to mislead the developer
+- Pivot to other localhost services on the developer's machine
+
+The viewer runs on localhost by default but is **reachable from the browser**, so standard same-origin protections don't help.
+
+## Patches
+
+Fixed in **0.8.2**:
+
+- All inline `on*=` handlers removed from `src/viewer/index.html`
+- Replaced with delegated `data-action` event handling
+- CSP switched to a **per-response script nonce** (`script-src 'nonce-<random>'`)
+- Added `script-src-attr 'none'` to block any inline handler attributes even if injected
+- Viewer HTML now rendered through `src/viewer/document.ts` which generates a fresh nonce per request
+
+## Workarounds
+
+**None.** Users on affected versions should upgrade to 0.8.2 immediately. Do not open `http://localhost:3113` in a browser on affected versions if you suspect any of your captured observations may contain attacker-controlled content.
+
+## References
+
+- Fix PR: [#108](https://github.com/rohitg00/agentmemory/pull/108)
+- Commit: [`cbaaf4f`](https://github.com/rohitg00/agentmemory/commit/cbaaf4f)
+- Reporter: @eng-pf
+
+## Credit
+
+@eng-pf submitted PR #108 with fixes for this and 5 other vulnerabilities.

.github/security-advisories/02-curl-sh-rce.md

@@ -0,0 +1,57 @@
+# GHSA Draft: Remote shell script execution in agentmemory CLI startup
+
+**Severity:** Critical · **CVSS 3.1:** 9.8 (`AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H`)
+**CWE:** [CWE-494 — Download of Code Without Integrity Check](https://cwe.mitre.org/data/definitions/494.html), [CWE-829 — Inclusion of Functionality from Untrusted Control Sphere](https://cwe.mitre.org/data/definitions/829.html)
+**Affected versions:** `< 0.8.2`
+**Patched version:** `0.8.2`
+
+## Summary
+
+The agentmemory CLI (`npx @agentmemory/agentmemory`) auto-installed the iii-engine binary by piping a remote shell script into `sh`:
+
+```ts
+execSync("curl -fsSL https://install.iii.dev/iii/main/install.sh | sh")
+```
+
+This happened automatically on first run if `iii` was not found in `$PATH`. The script was fetched over HTTPS and executed with the permissions of the user running `npx agentmemory`. No checksum verification, no pinned version, no signature check.
+
+## Impact
+
+If `install.iii.dev` were ever compromised — via DNS hijack, domain takeover, expired certificate + MITM on an untrusted network, BGP attack, or any other supply chain attack — **every new agentmemory user would execute attacker-controlled shell code** as their own user.
+
+This is the canonical "curl | sh" supply chain anti-pattern. It affected:
+- Developers running `npx @agentmemory/agentmemory` for the first time
+- CI/CD pipelines that installed agentmemory fresh
+- Docker builds that installed agentmemory as part of an image
+
+## Patches
+
+Fixed in **0.8.2**:
+
+- Removed `execSync` call entirely from `src/cli.ts`
+- CLI now uses an existing local `iii` binary if present in `$PATH`
+- Falls back to Docker Compose (`docker compose up -d`) if Docker is available
+- Shows manual install instructions if neither iii nor Docker is found:
+  - `cargo install iii-engine`
+  - `docker pull iiidev/iii:latest`
+  - Docs link: https://iii.dev/docs
+
+## Workarounds
+
+Users on affected versions should **install iii-engine manually** and run `agentmemory --no-engine` until upgraded:
+
+```bash
+cargo install iii-engine
+npx @agentmemory/agentmemory@0.8.1 --no-engine
+```
+
+Then upgrade to 0.8.2 at the earliest opportunity.
+
+## References
+
+- Fix PR: [#108](https://github.com/rohitg00/agentmemory/pull/108)
+- Commit: [`cbaaf4f`](https://github.com/rohitg00/agentmemory/commit/cbaaf4f)
+
+## Credit
+
+@eng-pf

.github/security-advisories/03-default-bind-0000.md

@@ -0,0 +1,62 @@
+# GHSA Draft: agentmemory REST and stream services bound to 0.0.0.0 by default
+
+**Severity:** High · **CVSS 3.1:** 8.1 (`AV:A/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:L`)
+**CWE:** [CWE-668 — Exposure of Resource to Wrong Sphere](https://cwe.mitre.org/data/definitions/668.html), [CWE-306 — Missing Authentication for Critical Function](https://cwe.mitre.org/data/definitions/306.html)
+**Affected versions:** `< 0.8.2`
+**Patched version:** `0.8.2`
+
+## Summary
+
+The default `iii-config.yaml` bound both the REST API (port 3111) and the streams server (port 3112) to `0.0.0.0`, exposing them on every network interface the host could reach. Combined with the fact that `AGENTMEMORY_SECRET` is **unset by default**, this meant any device on the same local network as a running agentmemory instance could read the entire memory store without authentication.
+
+Affected endpoints included:
+- `GET /agentmemory/export` — full dump of every captured observation, memory, session, and audit entry
+- `GET /agentmemory/sessions` — session list
+- `POST /agentmemory/smart-search` — arbitrary search over all captured content
+- `POST /agentmemory/observe` — ability to **inject** fake observations
+- `POST /agentmemory/remember` — ability to plant arbitrary memories
+- All 109 other REST endpoints
+
+## Impact
+
+A developer running agentmemory on a laptop in a coffee shop, office, or conference WiFi effectively published their entire memory store — including captured API keys, file contents, prompts, decisions, and project context — to anyone on the same network.
+
+Attackers on the same network could:
+
+1. **Exfiltrate secrets.** `curl http://<victim-ip>:3111/agentmemory/export` downloads everything. Depending on the incompleteness of the secret redaction (see advisory #06), this could include API keys and tokens.
+2. **Inject memories.** An attacker could `POST /agentmemory/observe` or `/remember` with fake observations, poisoning the memory store so future sessions retrieve attacker-controlled context.
+3. **Pivot to other services.** The mesh sync endpoint (before the auth fix in advisory #04) accepted peer data from any source.
+
+## Patches
+
+Fixed in **0.8.2**:
+
+- `iii-config.yaml` now binds REST, streams to `127.0.0.1`
+- Viewer server already bound to `127.0.0.1`
+- New `iii-config.docker.yaml` for Docker deployments: containers bind to `0.0.0.0` internally (required for Docker networking) but host port mapping is restricted to `127.0.0.1:port` in `docker-compose.yml`
+- README and API section documentation updated to note 127.0.0.1 as the default
+
+## Workarounds
+
+Users on affected versions should manually edit their `iii-config.yaml` and change the REST and streams `host` values to `127.0.0.1`:
+
+```yaml
+modules:
+  - class: modules::api::RestApiModule
+    config:
+      host: 127.0.0.1   # was 0.0.0.0
+  - class: modules::stream::StreamModule
+    config:
+      host: 127.0.0.1   # was 0.0.0.0
+```
+
+And set `AGENTMEMORY_SECRET` to a strong random value to protect endpoints even if network exposure is needed.
+
+## References
+
+- Fix PR: [#108](https://github.com/rohitg00/agentmemory/pull/108)
+- Commit: [`cbaaf4f`](https://github.com/rohitg00/agentmemory/commit/cbaaf4f)
+
+## Credit
+
+@eng-pf

.github/security-advisories/04-mesh-unauth.md

@@ -0,0 +1,47 @@
+# GHSA Draft: Unauthenticated mesh sync in agentmemory
+
+**Severity:** High · **CVSS 3.1:** 7.4 (`AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:N`)
+**CWE:** [CWE-306 — Missing Authentication for Critical Function](https://cwe.mitre.org/data/definitions/306.html), [CWE-862 — Missing Authorization](https://cwe.mitre.org/data/definitions/862.html)
+**Affected versions:** `< 0.8.2`
+**Patched version:** `0.8.2`
+
+## Summary
+
+agentmemory's mesh federation feature (P2P sync between instances) accepted push/pull requests on its `/agentmemory/mesh/*` endpoints without requiring authentication. The mesh sync function also did not send any `Authorization` header when calling peer instances, meaning the federation protocol was entirely unauthenticated.
+
+## Impact
+
+Any attacker who could reach a mesh-enabled agentmemory instance could:
+
+1. **Push fake memories** via `POST /agentmemory/mesh/receive` — inject attacker-controlled observations, actions, semantic memories, and relations into the target's memory store. This poisons future retrievals and could be used to manipulate what the target's AI agent sees.
+2. **Pull the entire memory store** via `GET /agentmemory/mesh/export` — download all memories, actions, and graph data marked as mesh-shareable.
+3. **Chain with advisory #03** — combined with the default `0.0.0.0` binding, mesh endpoints were reachable from any device on the local network without any authentication.
+
+Mesh is opt-in (requires an explicit peer registration), so this affected only users who had enabled federation. But those users had no authentication at all.
+
+## Patches
+
+Fixed in **0.8.2**:
+
+- All 5 mesh REST endpoints (`mesh-register`, `mesh-list`, `mesh-sync`, `mesh-receive`, `mesh-export`) now return 503 with `"mesh requires AGENTMEMORY_SECRET"` if the secret is not configured
+- The `mem::mesh-sync` function now accepts a `meshAuthToken` parameter and **refuses to sync at all** if the token is missing
+- Outgoing push/pull requests include `Authorization: Bearer <secret>` headers
+- Server-side, all mesh endpoints check bearer auth via the existing `checkAuth` helper
+
+## Workarounds
+
+Users on affected versions who have mesh federation enabled should:
+1. Set `AGENTMEMORY_SECRET` to a strong random value on **both** peers
+2. Restart the server
+3. Upgrade to 0.8.2 at the earliest opportunity
+
+Users who have **not** enabled mesh federation are not affected by this specific issue, but should still upgrade for the other 5 fixes.
+
+## References
+
+- Fix PR: [#108](https://github.com/rohitg00/agentmemory/pull/108)
+- Commit: [`cbaaf4f`](https://github.com/rohitg00/agentmemory/commit/cbaaf4f)
+
+## Credit
+
+@eng-pf

.github/security-advisories/05-obsidian-export-traversal.md

@@ -0,0 +1,61 @@
+# GHSA Draft: Arbitrary filesystem write via Obsidian export in agentmemory
+
+**Severity:** Medium · **CVSS 3.1:** 6.5 (`AV:N/AC:L/PR:L/UI:N/S:U/C:N/I:H/A:L`)
+**CWE:** [CWE-22 — Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')](https://cwe.mitre.org/data/definitions/22.html), [CWE-73 — External Control of File Name or Path](https://cwe.mitre.org/data/definitions/73.html)
+**Affected versions:** `< 0.8.2`
+**Patched version:** `0.8.2`
+
+## Summary
+
+The `POST /agentmemory/obsidian/export` endpoint accepted a `vaultDir` parameter and passed it directly to `mkdir` and `writeFile` calls without any containment check. A caller could set `vaultDir` to any absolute path on the filesystem and agentmemory would create directories and write Markdown files there with the permissions of the process running the server.
+
+```bash
+# Example exploit payload (affected versions only)
+curl -X POST http://localhost:3111/agentmemory/obsidian/export \
+  -H "Content-Type: application/json" \
+  -d '{"vaultDir": "/etc/cron.d"}'
+```
+
+The content written would be agentmemory's exported memories in Markdown format, but an attacker could craft specific memory content beforehand to plant arbitrary files.
+
+## Impact
+
+When chained with advisory #03 (default `0.0.0.0` binding) or advisory #04 (unauthenticated mesh), an attacker on the local network could write arbitrary files to any filesystem location the agentmemory process had write access to.
+
+Possible exploitation paths:
+- Write to `~/.ssh/authorized_keys` — SSH key injection
+- Write to `/etc/cron.d/*` — cron job injection (if running as root)
+- Write to `~/.bashrc` or shell rc files — code execution on next shell
+- Overwrite any file the process could write to
+
+## Patches
+
+Fixed in **0.8.2**:
+
+- New `AGENTMEMORY_EXPORT_ROOT` environment variable (default: `~/.agentmemory`)
+- `vaultDir` now goes through `resolveVaultDir()` in `src/functions/obsidian-export.ts`:
+  - Resolves the path with `path.resolve`
+  - Checks `resolved === root || resolved.startsWith(root + path.sep)`
+  - Returns `null` if the check fails, and the endpoint returns `{ success: false, error: "vaultDir must be inside AGENTMEMORY_EXPORT_ROOT" }`
+- Default export is confined to `~/.agentmemory/vault`
+- Tests added in `test/obsidian-export.test.ts` for both the custom-but-valid case and the rejection case
+
+## Known limitations
+
+`resolveVaultDir()` performs lexical containment only — it does not call `fs.realpathSync` / `fs.lstatSync`. A pre-existing symlink under `AGENTMEMORY_EXPORT_ROOT` that points outside the root can still be written through. Users who allow untrusted processes to create files inside `AGENTMEMORY_EXPORT_ROOT` should additionally run agentmemory inside a sandbox that forbids symlink creation, or file a follow-up issue requesting symlink-aware containment.
+
+## Workarounds
+
+Users on affected versions should:
+1. **Disable the Obsidian export endpoint** by setting `OBSIDIAN_AUTO_EXPORT=false` (and avoid calling `/agentmemory/obsidian/export` manually)
+2. Set `AGENTMEMORY_SECRET` so the endpoint requires bearer auth
+3. Upgrade to 0.8.2
+
+## References
+
+- Fix PR: [#108](https://github.com/rohitg00/agentmemory/pull/108)
+- Commit: [`cbaaf4f`](https://github.com/rohitg00/agentmemory/commit/cbaaf4f)
+
+## Credit
+
+@eng-pf

.github/security-advisories/06-privacy-redaction-incomplete.md

@@ -0,0 +1,60 @@
+# GHSA Draft: Incomplete secret redaction in agentmemory privacy filter
+
+**Severity:** Medium · **CVSS 3.1:** 6.2 (`AV:L/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N`)
+**CWE:** [CWE-532 — Insertion of Sensitive Information into Log File](https://cwe.mitre.org/data/definitions/532.html), [CWE-200 — Exposure of Sensitive Information to an Unauthorized Actor](https://cwe.mitre.org/data/definitions/200.html)
+**Affected versions:** `< 0.8.2`
+**Patched version:** `0.8.2`
+
+## Summary
+
+agentmemory's privacy filter (`src/functions/privacy.ts`) is supposed to strip API keys, secrets, and bearer tokens from captured observations before they are stored. The filter used regex patterns to detect common token formats. Three modern token formats were missing from the patterns:
+
+1. **Bearer tokens** — `Authorization: Bearer <token>` headers were not matched, so any captured HTTP request or response that included an Authorization header flowed into the memory store verbatim.
+2. **OpenAI project keys** — `sk-proj-*` (the dominant OpenAI API key format since mid-2024) was not matched. The existing `sk-[A-Za-z0-9]{20,}` pattern only caught the legacy format.
+3. **GitHub fine-grained service/user tokens** — `ghs_*` and `ghu_*` were not matched. The existing `ghp_[A-Za-z0-9]{36}` pattern only caught personal access tokens.
+
+## Impact
+
+agentmemory's README explicitly claimed "Privacy first — API keys, secrets, and `<private>` tags are stripped before anything is stored." That claim was **false** for three common token formats.
+
+Users relying on the privacy filter to protect their captured observations had a false sense of security. Tokens matching these three patterns would:
+
+1. Be captured by `PostToolUse` hooks alongside the rest of the tool output
+2. Pass through `stripPrivateData()` unmodified
+3. Be LLM-compressed and stored in the memory KV
+4. Be exposed to any attacker who could reach the `/agentmemory/export` or `/agentmemory/smart-search` endpoints
+5. Be included in Obsidian exports, mesh syncs, and CLAUDE.md bridge writes
+
+When chained with advisory #03 (default `0.0.0.0` binding), this meant network-adjacent attackers could retrieve captured Bearer tokens, OpenAI keys, and GitHub service tokens from the memory store.
+
+## Patches
+
+Fixed in **0.8.2**:
+
+New regex patterns added to `SECRET_PATTERN_SOURCES` in `src/functions/privacy.ts`:
+
+```ts
+/Bearer\s+[A-Za-z0-9._\-+/=]{20,}/gi,
+/sk-proj-[A-Za-z0-9\-_]{20,}/g,
+/(?:sk|pk|rk|ak)-[A-Za-z0-9][A-Za-z0-9\-_]{19,}/g,
+/gh[pus]_[A-Za-z0-9]{36,}/g,
+```
+
+Three new unit tests in `test/privacy.test.ts` verify each format is now stripped.
+
+## Workarounds
+
+Users on affected versions should:
+1. Avoid having agents read files or API responses containing these token formats
+2. Use the `<private>` tag around any block containing secrets — that filter was not affected
+3. Set `AGENTMEMORY_SECRET` to restrict API access
+4. Upgrade to 0.8.2
+
+## References
+
+- Fix PR: [#108](https://github.com/rohitg00/agentmemory/pull/108)
+- Commit: [`cbaaf4f`](https://github.com/rohitg00/agentmemory/commit/cbaaf4f)
+
+## Credit
+
+@eng-pf

.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+# `paths-ignore` keeps doc-only / website / README / CHANGELOG churn from
+# burning runner minutes. Source / config / workflow changes always run.
+# `workflow_dispatch` gives a manual re-run button for flake debugging.
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "README.md"
+      - "CHANGELOG.md"
+      - "AGENTS.md"
+      - "ROADMAP.md"
+      - "website/**"
+      - "docs/**"
+      - "assets/**"
+      - "deploy/**/README.md"
+      - "**/*.md"
+      - "**/*.mdx"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "README.md"
+      - "CHANGELOG.md"
+      - "AGENTS.md"
+      - "ROADMAP.md"
+      - "website/**"
+      - "docs/**"
+      - "assets/**"
+      - "deploy/**/README.md"
+      - "**/*.md"
+      - "**/*.mdx"
+  workflow_dispatch:
+
+# Cancel in-flight PR runs when a force-push lands. Keep push runs to
+# protect against partial state on main.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Don't bail the whole matrix on one cell's failure — we want to
+      # see whether the same failure reproduces across OSes (e.g.
+      # whether a flake is platform-specific or universal).
+      fail-fast: false
+      matrix:
+        # Windows held back: test/obsidian-export.test.ts has hardcoded
+        # POSIX paths (`/tmp/...`) that fail on D:\ drive runners.
+        # src/functions/obsidian-export.ts needs os.tmpdir() + path.join
+        # rework before Windows can be added back. Tracked as follow-up.
+        os: [ubuntu-latest, macos-latest]
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      # Two-step install: generate a lockfile in-runner with
+      # --package-lock-only, then install from it with `npm ci`.
+      # Lockfiles are gitignored at the repo level.
+      - run: npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund
+      - run: npm ci --legacy-peer-deps --no-audit --no-fund
+      - run: npm run build
+      - run: npm run skills:check
+      - run: npm test

.github/workflows/publish.yml

@@ -0,0 +1,124 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      packages:
+        description: "Packages to publish (comma-separated: agentmemory,mcp,fs-watcher)"
+        required: false
+        default: "agentmemory,mcp,fs-watcher"
+
+# Workflow-level permissions stay minimal — only `contents: read`
+# is required to check out the repo. `id-token: write` is granted on
+# the publish job for npm's --provenance Sigstore OIDC mint.
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Don't persist the GITHUB_TOKEN to .git/config — the
+          # publish steps don't push back to the repo, so the token
+          # only needs to live in memory for this checkout.
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      # Two-step install: generate a lockfile in-runner with
+      # --package-lock-only, then install from it with `npm ci`. Gives a
+      # single deterministic dep graph across build / test / publish
+      # within one job — important because publish uses `--provenance`.
+      # Lockfiles are gitignored at the repo level.
+      - run: npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund
+      - run: npm ci --legacy-peer-deps --no-audit --no-fund
+      - run: npm run build
+      - run: npm test
+
+      - name: Publish @agentmemory/agentmemory
+        run: |
+          if npm view "@agentmemory/agentmemory@$(node -p "require('./package.json').version")" version >/dev/null 2>&1; then
+            echo "Version already published, skipping"
+          else
+            npm publish --provenance --access public
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Wait for npm registry propagation
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          for i in $(seq 1 24); do
+            if npm view "@agentmemory/agentmemory@$VERSION" version >/dev/null 2>&1; then
+              echo "Registry propagated after ${i} attempt(s)"
+              exit 0
+            fi
+            echo "Attempt $i: not yet available, sleeping 5s..."
+            sleep 5
+          done
+          echo "ERROR: registry never propagated after 2 minutes" >&2
+          exit 1
+
+      - name: Publish @agentmemory/mcp shim
+        working-directory: packages/mcp
+        run: |
+          SHIM_VERSION=$(node -p "require('./package.json').version")
+          if npm view "@agentmemory/mcp@$SHIM_VERSION" version >/dev/null 2>&1; then
+            echo "Shim version already published, skipping"
+          else
+            npm publish --provenance --access public
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Wait for @agentmemory/mcp registry propagation
+        working-directory: packages/mcp
+        run: |
+          SHIM_VERSION=$(node -p "require('./package.json').version")
+          for i in $(seq 1 24); do
+            if npm view "@agentmemory/mcp@$SHIM_VERSION" version >/dev/null 2>&1; then
+              echo "Shim propagated after ${i} attempt(s)"
+              exit 0
+            fi
+            echo "Attempt $i: not yet available, sleeping 5s..."
+            sleep 5
+          done
+          echo "ERROR: shim never propagated after 2 minutes" >&2
+          exit 1
+
+      - name: Publish @agentmemory/fs-watcher connector
+        working-directory: integrations/filesystem-watcher
+        run: |
+          FSW_VERSION=$(node -p "require('./package.json').version")
+          if npm view "@agentmemory/fs-watcher@$FSW_VERSION" version >/dev/null 2>&1; then
+            echo "fs-watcher version already published, skipping"
+          else
+            npm publish --provenance --access public
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Wait for @agentmemory/fs-watcher registry propagation
+        working-directory: integrations/filesystem-watcher
+        run: |
+          FSW_VERSION=$(node -p "require('./package.json').version")
+          for i in $(seq 1 24); do
+            if npm view "@agentmemory/fs-watcher@$FSW_VERSION" version >/dev/null 2>&1; then
+              echo "fs-watcher propagated after ${i} attempt(s)"
+              exit 0
+            fi
+            echo "Attempt $i: not yet available, sleeping 5s..."
+            sleep 5
+          done
+          echo "ERROR: fs-watcher never propagated after 2 minutes" >&2
+          exit 1

.gitignore

@@ -0,0 +1,53 @@
+node_modules/
+dist/
+*.tsbuildinfo
+
+.env
+.env.*
+!.env.example
+
+*.log
+.DS_Store
+.claude/
+
+plugin/scripts/*.map
+plugin/scripts/*.d.mts
+data/
+!eval/data/
+!eval/data/**
+data-*/
+agentmemory-debug/
+.gstack/
+
+# Lock files — never commit (see feedback_no_lockfiles memory)
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+integrations/hermes/__pycache__/
+
+# Eval reports (transient; published scorecards live in docs/benchmarks/)
+eval/reports/
+# LongMemEval download is 278MB; fetched on demand
+eval/data/longmemeval/
+
+# Python virtual environment and caches
+.venv/
+venv/
+ENV/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+
+# Large files
+assets/
+*.mp4
+*.png
+*.gif
+*.jpg
+*.jpeg
+
+
+

.playwright-mcp/page-2026-06-08T23-28-16-016Z.yml

@@ -0,0 +1,35 @@
+- generic [active] [ref=e1]:
+  - generic [ref=e2]:
+    - link "Open dashboard" [ref=e3] [cursor=pointer]:
+      - /url: "#dashboard"
+      - heading "agentmemory" [level=1] [ref=e4]
+      - generic [ref=e5]: v0.9.8
+    - generic [ref=e6]:
+      - generic [ref=e7]: Tue, Jun 9, 2026
+      - button "DARK" [ref=e8] [cursor=pointer]
+      - generic [ref=e9]: live updates off
+  - generic [ref=e10]:
+    - button "Dashboard" [ref=e11] [cursor=pointer]
+    - button "Graph" [ref=e12] [cursor=pointer]
+    - button "Memories" [ref=e13] [cursor=pointer]
+    - button "Timeline" [ref=e14] [cursor=pointer]
+    - button "Sessions" [ref=e15] [cursor=pointer]
+    - button "Lessons" [ref=e16] [cursor=pointer]
+    - button "Actions" [ref=e17] [cursor=pointer]
+    - button "Crystals" [ref=e18] [cursor=pointer]
+    - button "Audit" [ref=e19] [cursor=pointer]
+    - button "Activity" [ref=e20] [cursor=pointer]
+    - button "Profile" [ref=e21] [cursor=pointer]
+    - button "Replay" [ref=e22] [cursor=pointer]
+  - generic [ref=e24]: Loading dashboard...
+  - contentinfo [ref=e25]:
+    - generic [ref=e26]: agentmemory viewer · loading...
+    - generic [ref=e27]: ·
+    - link "github" [ref=e28] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory
+    - generic [ref=e29]: ·
+    - link "docs" [ref=e30] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory#readme
+    - generic [ref=e31]: ·
+    - link "report issue →" [ref=e32] [cursor=pointer]:
+      - /url: "#"

.playwright-mcp/page-2026-06-08T23-35-49-143Z.yml

@@ -0,0 +1,40 @@
+- generic [active] [ref=e1]:
+  - generic [ref=e2]:
+    - link "Open dashboard" [ref=e3] [cursor=pointer]:
+      - /url: "#dashboard"
+      - heading "agentmemory" [level=1] [ref=e4]
+      - generic [ref=e5]: v0.9.8
+    - generic [ref=e6]:
+      - generic [ref=e7]: Tue, Jun 9, 2026
+      - button "DARK" [ref=e8] [cursor=pointer]
+      - generic [ref=e9]: live updates off
+  - generic [ref=e10]:
+    - button "Dashboard" [ref=e11] [cursor=pointer]
+    - button "Graph" [ref=e12] [cursor=pointer]
+    - button "Memories" [ref=e13] [cursor=pointer]
+    - button "Timeline" [ref=e14] [cursor=pointer]
+    - button "Sessions" [ref=e15] [cursor=pointer]
+    - button "Lessons" [ref=e16] [cursor=pointer]
+    - button "Actions" [ref=e17] [cursor=pointer]
+    - button "Crystals" [ref=e18] [cursor=pointer]
+    - button "Audit" [ref=e19] [cursor=pointer]
+    - button "Activity" [ref=e20] [cursor=pointer]
+    - button "Profile" [ref=e21] [cursor=pointer]
+    - button "Replay" [ref=e22] [cursor=pointer]
+  - button "1 off Feature flags — click to expand" [ref=e24] [cursor=pointer]:
+    - generic [ref=e25]: 1 off
+    - generic [ref=e26]: Feature flags
+    - generic [ref=e27]: — click to expand
+    - generic [ref=e28]: ▼
+  - generic [ref=e30]: Loading dashboard...
+  - contentinfo [ref=e31]:
+    - generic [ref=e32]: agentmemory viewer · v0.9.8
+    - generic [ref=e33]: ·
+    - link "github" [ref=e34] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory
+    - generic [ref=e35]: ·
+    - link "docs" [ref=e36] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory#readme
+    - generic [ref=e37]: ·
+    - link "report issue →" [ref=e38] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory/issues/new?title=%5Bviewer%5D%20&body=**Version%3A**%200.9.8%0A**Provider%3A**%20llm%0A**Embedding%3A**%20gemini%0A**Flags%3A**%20GRAPH_EXTRACTION_ENABLED%3Don%2C%20CONSOLIDATION_ENABLED%3Don%2C%20AGENTMEMORY_AUTO_COMPRESS%3Doff%0A**User%20agent%3A**%20Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F149.0.0.0%20Safari%2F537.36%0A%0A%23%23%23%20What%20went%20wrong%0A%0A(describe%20the%20issue)%0A%0A%23%23%23%20Steps%20to%20reproduce%0A%0A1.%20%0A2.%20%0A3.%20%0A

.playwright-mcp/page-2026-06-09T00-16-38-317Z.yml

@@ -0,0 +1,40 @@
+- generic [active] [ref=e1]:
+  - generic [ref=e2]:
+    - link "Open dashboard" [ref=e3] [cursor=pointer]:
+      - /url: "#dashboard"
+      - heading "agentmemory" [level=1] [ref=e4]
+      - generic [ref=e5]: v0.9.8
+    - generic [ref=e6]:
+      - generic [ref=e7]: Tue, Jun 9, 2026
+      - button "DARK" [ref=e8] [cursor=pointer]
+      - generic [ref=e9]: live updates off
+  - generic [ref=e10]:
+    - button "Dashboard" [ref=e11] [cursor=pointer]
+    - button "Graph" [ref=e12] [cursor=pointer]
+    - button "Memories" [ref=e13] [cursor=pointer]
+    - button "Timeline" [ref=e14] [cursor=pointer]
+    - button "Sessions" [ref=e15] [cursor=pointer]
+    - button "Lessons" [ref=e16] [cursor=pointer]
+    - button "Actions" [ref=e17] [cursor=pointer]
+    - button "Crystals" [ref=e18] [cursor=pointer]
+    - button "Audit" [ref=e19] [cursor=pointer]
+    - button "Activity" [ref=e20] [cursor=pointer]
+    - button "Profile" [ref=e21] [cursor=pointer]
+    - button "Replay" [ref=e22] [cursor=pointer]
+  - button "1 off Feature flags — click to expand" [ref=e24] [cursor=pointer]:
+    - generic [ref=e25]: 1 off
+    - generic [ref=e26]: Feature flags
+    - generic [ref=e27]: — click to expand
+    - generic [ref=e28]: ▼
+  - generic [ref=e30]: Loading dashboard...
+  - contentinfo [ref=e31]:
+    - generic [ref=e32]: agentmemory viewer · v0.9.8
+    - generic [ref=e33]: ·
+    - link "github" [ref=e34] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory
+    - generic [ref=e35]: ·
+    - link "docs" [ref=e36] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory#readme
+    - generic [ref=e37]: ·
+    - link "report issue →" [ref=e38] [cursor=pointer]:
+      - /url: https://github.com/rohitg00/agentmemory/issues/new?title=%5Bviewer%5D%20&body=**Version%3A**%200.9.8%0A**Provider%3A**%20llm%0A**Embedding%3A**%20gemini%0A**Flags%3A**%20GRAPH_EXTRACTION_ENABLED%3Don%2C%20CONSOLIDATION_ENABLED%3Don%2C%20AGENTMEMORY_AUTO_COMPRESS%3Doff%0A**User%20agent%3A**%20Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F149.0.0.0%20Safari%2F537.36%0A%0A%23%23%23%20What%20went%20wrong%0A%0A(describe%20the%20issue)%0A%0A%23%23%23%20Steps%20to%20reproduce%0A%0A1.%20%0A2.%20%0A3.%20%0A

AGENTS.md

@@ -0,0 +1,124 @@
+# agentmemory — Agent Instructions
+
+## Architecture
+
+agentmemory is a persistent memory system for AI coding agents, built on iii-engine's three primitives (Worker/Function/Trigger). Everything goes through `registerFunction`/`registerTrigger`/`sdk.trigger()` — never bypass iii-engine with standalone SQLite or in-process alternatives.
+
+- **Engine**: iii-sdk (WebSocket to iii-engine on port 49134)
+- **State**: File-based SQLite via iii-engine's StateModule (`./data/state_store.db`)
+- **Build**: TypeScript → ESM via tsdown, output to `dist/`
+- **Test**: vitest (`npm test` excludes integration tests)
+
+## Consistency Rules
+
+**When adding or removing MCP tools, you MUST update ALL of the following:**
+1. `src/mcp/tools-registry.ts` — tool definition + `getAllTools()` array
+2. `src/mcp/server.ts` — handler case in the `mcp::tools::call` switch
+3. `src/triggers/api.ts` — REST endpoint registration
+4. `src/index.ts` — function registration + endpoint count in the log line
+5. `test/mcp-standalone.test.ts` — tool count assertion
+6. `README.md` — tool counts (search for "MCP tools")
+7. `plugin/.claude-plugin/plugin.json` — tool count in description
+8. `plugin/plugin.json` and `plugin/.mcp.copilot.json` (when present) — tool count or MCP exposure
+
+**When adding REST endpoints, you MUST update:**
+1. `src/triggers/api.ts` — endpoint registration
+2. `src/index.ts` — endpoint count in the log line
+3. `README.md` — endpoint count (search for "REST endpoints" and "endpoints on port")
+
+**When bumping version, you MUST update ALL of the following:**
+1. `package.json` — version field
+2. `src/version.ts` — VERSION constant and type union
+3. `src/types.ts` — ExportData version union
+4. `src/functions/export-import.ts` — supportedVersions set
+5. `test/export-import.test.ts` — version assertion
+6. `plugin/.claude-plugin/plugin.json` — version field
+7. `plugin/plugin.json` (when present) — version field
+
+**When adding new KV scopes:**
+1. `src/state/schema.ts` — add to the KV object
+2. `src/types.ts` — add the corresponding interface
+
+**When adding new audit operations:**
+1. `src/types.ts` — add to AuditEntry.operation union type
+
+## Code Patterns
+
+### Function Registration
+```typescript
+sdk.registerFunction(
+  "mem::your-function",
+  async (data: { ... }) => {
+    // validate inputs
+    // do work via kv.get/kv.set/kv.list
+    // record audit via recordAudit()
+    return { success: true, ... };
+  },
+);
+```
+
+### REST Endpoint Registration
+```typescript
+sdk.registerFunction("api::your-endpoint", async (req: ApiRequest) => {
+  const denied = checkAuth(req, secret);
+  if (denied) return denied;
+  const body = req.body as Record<string, unknown>;
+  // validate + whitelist fields (never pass raw body to sdk.trigger)
+  const result = await sdk.trigger({
+    function_id: "mem::your-function",
+    payload: { ... },
+  });
+  return { status_code: 200, body: result };
+});
+sdk.registerTrigger({
+  type: "http",
+  function_id: "api::your-endpoint",
+  config: { api_path: "/agentmemory/your-path", http_method: "POST" },
+});
+```
+
+### MCP Tool Handler
+```typescript
+case "memory_your_tool": {
+  // validate args with typeof checks
+  // parse CSV args: args.field.split(",").map(t => t.trim()).filter(Boolean)
+  const result = await sdk.trigger({
+    function_id: "mem::your-function",
+    payload: { ... },
+  });
+  return { status_code: 200, body: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } };
+}
+```
+
+### Hook Scripts
+Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). They read JSON from stdin, make HTTP calls to the REST API, and exit. There are two patterns depending on whether Claude Code consumes the script's stdout:
+
+- **Context-injecting hooks** (`pre-tool-use`, `pre-compact`, `session-start`) write recalled context to stdout for Claude Code to inject. These MUST use `try/catch` with `await fetch(..., { signal: AbortSignal.timeout(N) })` — the script has to wait for the response before exiting, and the timeout is the only bound on hang time.
+- **Telemetry-only hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `stop`, `session-end`, `subagent-start`, `subagent-stop`, `task-completed`) write nothing to stdout. These MUST use fire-and-forget `fetch(..., { signal: AbortSignal.timeout(N) }).catch(() => {})` paired with `setTimeout(() => process.exit(0), 500).unref()`. The unawaited fetch dispatches the request; the unref'd `setTimeout` force-exits the process after the request has been flushed to the local daemon's socket buffer (~500ms is enough for single-request hooks; use 1500ms for multi-request hooks like `stop` and `session-end` so all fetches have time to start, especially when `AGENTMEMORY_URL` points to a remote daemon). Without the `setTimeout` Node keeps the event loop alive waiting for any in-flight fetch to settle, which means the hook still blocks Claude Code's next-prompt boundary for up to the AbortSignal duration — exactly the bug fire-and-forget is meant to fix.
+
+## Coding Standards
+
+- TypeScript, ESM only (`"type": "module"`)
+- No code comments explaining WHAT — use clear naming instead
+- Use `fingerprintId()` for content-addressable dedup, `generateId()` for unique IDs
+- Parallel operations where possible (`Promise.all` for independent kv writes/reads)
+- Input validation at system boundaries (MCP handlers, REST endpoints)
+- REST endpoints must whitelist fields — never pass raw request body to `sdk.trigger()`
+- Use `recordAudit()` for state-changing operations
+- Timestamps: capture once with `new Date().toISOString()` and reuse
+
+## Testing
+
+- All tests must pass before PR: `npm test` (950+ tests)
+- Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list`
+- Test files go in `test/` with `.test.ts` extension
+- Follow existing patterns in `test/crystallize.test.ts` for function tests
+
+## Current Stats (v0.9.16)
+
+- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
+- 128 REST endpoints
+- 6 MCP resources, 3 MCP prompts
+- 12 hooks, 4 skills
+- 50+ iii functions
+- 950+ tests

CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Python reimplementation of the agentmemory persistent memory server. Exposes a REST API + WebSocket stream + MCP tools endpoint that AI coding agents use to store and retrieve session observations, long-term memories, lessons, and pinned memory slots. Backed by a Dolt SQL Server (MySQL-compatible).
+
+## Running
+
+**Prerequisite**: Dolt SQL Server must be running on `127.0.0.1:3306` with a database named `agentmemory`. Config is read from `~/.agentmemory/.env` at startup.
+
+```bash
+# Start the memory API server and built-in viewer (port 3111)
+python src/app.py
+```
+
+The built-in HTML dashboard is accessible at:
+- `http://localhost:3111/viewer` or `http://localhost:3111/`
+
+No build step. No test runner is configured yet.
+
+## Key Environment Variables
+
+Set in `~/.agentmemory/.env` or as system env vars:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `III_REST_PORT` / `PORT` | `3111` | API server port |
+| `DOLT_HOST/PORT/USER/PASSWORD/DATABASE` | `127.0.0.1/3306/root//"agentmemory"` | Dolt connection |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables 768-dim vector search; without it, BM25-only |
+| `AGENTMEMORY_SECRET` | — | Enables Bearer token auth on all endpoints |
+| `AGENT_ID` | — | Default agent ID for scope isolation |
+| `AGENTMEMORY_AGENT_SCOPE=isolated` | — | Filters sessions/obs to current `AGENT_ID` |
+| `DOLT_AUTO_COMMIT=false` | auto-commit | Disable Dolt versioning commits per write |
+| `MAX_OBS_PER_SESSION` | `500` | Hard cap on observations per session |
+| `TOKEN_BUDGET` | `2000` | Max tokens in compiled context response |
+| `GRAPH_EXTRACTION_ENABLED=true` | `false` | Knowledge graph extraction (requires LLM) — **disabled by default** |
+| `CONSOLIDATION_ENABLED=true` | `false` | Memory consolidation (requires LLM) — **disabled by default** |
+| `AGENTMEMORY_AUTO_COMPRESS=true` | `false` | LLM-powered observation compression |
+
+## Architecture
+
+### `src/db.py` — Storage Layer
+`StateKV` wraps a single Dolt table `kv_store(scope VARCHAR, key VARCHAR, value LONGTEXT)`. All data is JSON-serialized. Scopes are namespaced strings (e.g. `mem:sessions`, `mem:obs:{session_id}`). Dolt versioning is triggered via `CALL dolt_add('-A')` + `CALL dolt_commit(...)` stored procedures — this is what makes the store git-versioned.
+
+### `src/functions.py` — Business Logic
+All core operations live here. Important globals:
+- `_bm25_index` / `_vector_index` — in-memory search indexes (rebuilt from DB on startup if empty)
+- `_hybrid_search` — combines BM25 + vector search; only initialized when embedding provider is set
+- `_stream_broadcaster` — WebSocket broadcast callback injected by `app.py`
+
+Key scopes are defined in the `KV` class. Dynamic scopes: `KV.observations(session_id)` → `mem:obs:{session_id}`.
+
+**Observation pipeline**: raw payload → `strip_private_data()` → `build_synthetic_compression()` → stored + BM25-indexed + vector-indexed + Dolt-committed + WebSocket-broadcast.
+
+**Memory versioning**: `remember()` checks Jaccard similarity against existing memories; if > 0.7 match found, the new memory supersedes the old one (`isLatest=False` on old, `parentId` set on new).
+
+**Context compilation** (`context()`): assembles pinned slots → project profile → lessons (scored by confidence × project match) → past session summaries, capped at `TOKEN_BUDGET` tokens (estimated at `len/3`).
+
+**Lessons**: fingerprinted by SHA-256 of content. Duplicate saves strengthen confidence (`+0.1 × (1 - conf)`). Weekly decay sweep reduces confidence by `decayRate × weeks`; soft-deleted at ≤ 0.1 confidence with 0 reinforcements.
+
+### `src/search.py` — Search Indexes
+- `SearchIndex`: BM25 with custom Porter stemmer. Persisted to Dolt in sharded 2MB chunks via `IndexPersistence`.
+- `VectorIndex`: cosine similarity over Gemini 768-dim embeddings stored as base64-encoded float32 arrays.
+- `HybridSearch`: fuses BM25 + vector scores with RRF (reciprocal rank fusion).
+
+### `src/app.py` — Flask API
+Initializes DB → embedding provider → index persistence → rebuilds index if empty (background thread). All endpoints check `AGENTMEMORY_SECRET` via timing-safe Bearer token comparison. WebSocket at `/stream/mem-live/viewer` broadcasts raw + compressed observations to connected viewers.
+
+MCP tools are served at `GET /agentmemory/mcp/tools` (schema list) and `POST /agentmemory/mcp/tools` (tool call dispatch).
+
+### `src/viewer/index.html` — Built-in HTML Dashboard
+Interactive web dashboard served directly by the Flask server. Provides real-time view of active sessions, timelines, memories with search, slots editor, and DB migration panel. Connects to the Flask backend via REST and live WebSockets. Imports legacy TypeScript `.bin` files via `src/import_data.py`.
+
+## API Surface
+
+Base path: `/agentmemory/`
+
+- `GET /livez` — health/liveness (no auth)
+- `POST /observe` — ingest a hook event observation
+- `POST /agent/observe` — simplified observe for direct agent use
+- `POST /remember` / `POST /agent/remember` — save long-term memory
+- `POST /forget` — delete memory/session/observations
+- `POST /context` — compile context for a session+project
+- `POST /search` — hybrid BM25+vector search
+- `POST/GET /lessons` — lessons CRUD + `/lessons/search`, `/lessons/strengthen`
+- `GET/POST /slots`, `GET/POST/DELETE /slot` — memory slots CRUD
+- `POST /slot/reflect` — auto-populate slots from session observations
+- `POST/GET /session/start|end|commit` — session lifecycle
+- `GET /sessions`, `GET /observations` — list data
+- `GET/POST /relations` — knowledge graph edges
+- `POST /evolve` — create new memory version
+- `POST /timeline` — chronological observation window
+- `GET /profile` — project profile (top concepts/files); no `?project` → returns list of all known projects
+- `GET /actions` — list actions (`?limit`, `?status`)
+- `POST /actions` — create action
+- `PATCH /actions/<id>` — update action status/fields
+- `GET /frontier` — pending+active actions sorted by priority
+- `GET /insights` — list insights (`?limit`)
+- `GET /replay/sessions` — sessions list for replay tab
+- `GET /replay/load?sessionId=<id>` — full session + observations for replay
+- `GET/POST /mcp/tools` — MCP protocol adapter

CODE_OF_CONDUCT.md

@@ -0,0 +1,48 @@
+# Code of Conduct
+
+agentmemory follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+The short version:
+
+- Be kind. Assume good faith.
+- Disagree on the idea, not the person.
+- Harassment — in issues, PRs, discussions, or any other project space — is not tolerated.
+- Unwelcome behavior gets moderated first by reminder, then by time-out, then by removal.
+
+## Enforcement
+
+Reports go to **ghumare64@gmail.com** with subject `agentmemory CoC`. All reports are confidential.
+
+Responses follow the Covenant's enforcement ladder — correction, warning, temporary ban, permanent ban — and are decided by the project Maintainers listed in [MAINTAINERS.md](./MAINTAINERS.md). Where a Maintainer is a party to the report, that Maintainer recuses.
+
+### Escalation when no impartial Maintainer is available
+
+If every listed Maintainer recuses, or if the project is operating with a single Maintainer and the report concerns that Maintainer, the report is forwarded to an external neutral contact for independent adjudication. The current fallback chain, in order:
+
+1. **Contributor Covenant community ombudsperson** — email `ombudsperson@contributor-covenant.org` (see <https://www.contributor-covenant.org/faq/>).
+2. **Hosting foundation abuse channel** — when agentmemory is accepted into a foundation (see `GOVERNANCE.md`), reports can be routed to that foundation's conduct committee instead. The current contact will be published here at that time.
+3. **GitHub Trust & Safety** — for conduct that occurs inside GitHub spaces, the report can also be filed through <https://support.github.com/contact/report-abuse>.
+
+The external contact receives the original report verbatim (redacted only of third-party PII unrelated to the incident) and decides the enforcement step. The Maintainer body executes whatever enforcement action the external contact recommends. This ensures no report can dead-end because every internal reviewer is conflicted.
+
+## Scope
+
+This applies to every project space:
+
+- GitHub issues, PRs, discussions, and reviews on this repo.
+- Any official chat channel that gets set up (currently none).
+- Public representation of the project at conferences, meetups, and on social media.
+
+## Full text
+
+Reproduced verbatim from the Contributor Covenant 2.1 for convenience:
+
+> We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+>
+> We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+Full Covenant v2.1 text: <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+## Attribution
+
+Contributor Covenant is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to agentmemory
+
+Thanks for taking an interest. This file is the short path from "I have an idea" to "it's in main."
+
+## Ground rules
+
+- Apache-2.0 license applies to every contribution.
+- Sign-off is required on every commit (see [DCO](#developer-certificate-of-origin) below).
+- Be civil. [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) applies.
+- No attribution headers ("Generated with Claude Code", "Co-Authored-By: Claude", etc.) in commits or PR descriptions.
+
+## Before you open an issue
+
+Search existing issues first:
+
+- [open issues](https://github.com/rohitg00/agentmemory/issues?q=is%3Aissue+is%3Aopen)
+- [closed issues](https://github.com/rohitg00/agentmemory/issues?q=is%3Aissue+is%3Aclosed)
+
+If it's a bug: provide the repro steps, your Node version, OS, agentmemory version (`npm view @agentmemory/agentmemory version`), and what you expected vs. what you saw.
+
+If it's a feature: describe the user problem before the implementation. "I couldn't X because Y" beats "please add X."
+
+## Before you open a PR
+
+1. Fork the repo and create a branch off `main`:
+   - `feat/<short-name>` for features
+   - `fix/<issue-number>-<short-name>` for bug fixes
+   - `docs/<topic>`, `refactor/<topic>`, `chore/<topic>` for the rest
+2. `npm install` — you need Node >=20.
+3. `npm run build` — TypeScript must compile clean.
+4. `npm test` — the full test suite must pass. The one integration test under `test/integration.test.ts` needs a live server on `:3111` and is fine to skip locally.
+5. Commit with sign-off. Rebase over tiny fixup commits so the history stays readable.
+
+## Pull request flow
+
+- Keep PRs small and focused. One logical change per PR.
+- Write a clear description: what it does, why, and how to verify.
+- Link the issue the PR resolves (`Fixes #NNN` / `Closes #NNN`).
+- Expect CodeRabbit to review automatically. Address its comments before asking a human.
+- Address review feedback in new commits (do not force-push to the same branch). Maintainers may squash on merge.
+- A maintainer will merge when tests pass, CodeRabbit is green, and any review comments are addressed.
+
+## Developer Certificate of Origin
+
+Every commit must carry a `Signed-off-by` trailer stating you have the right to submit the contribution under Apache-2.0. The full text of the DCO is at <https://developercertificate.org>.
+
+Add it automatically:
+
+```bash
+git commit -s -m "feat: your message"
+```
+
+PRs with commits lacking sign-off will not merge.
+
+## Coding style
+
+- TypeScript strict mode. No `any` unless justified in a comment.
+- Prettier-compatible formatting (editor on save is fine; no repo-wide hook).
+- No code comments that restate what the code does. Only write a comment when the *why* is non-obvious — a hidden constraint, an invariant, a workaround for a specific bug.
+- No dead code, no commented-out imports.
+- Tests live next to the feature in `test/<feature>.test.ts`. Name the test after the behavior, not the implementation.
+
+## Subsystems at a glance
+
+| Directory | What lives here |
+|-|-|
+| `src/triggers/api.ts` | Every HTTP endpoint under `/agentmemory/*`. Adding an MCP tool? Add the REST twin here too. |
+| `src/mcp/` | Standalone MCP server (`@agentmemory/mcp`), tools registry, transport, in-memory KV. |
+| `src/functions/` | Core memory operations — observe, compress, consolidate, retention, forget, graph, smart-search, export-import, governance. |
+| `src/hooks/` | The 12 auto-hooks that capture sessions in agents. |
+| `src/health/` | Liveness + readiness + alert thresholds. |
+| `src/state/` | KV schema, keyed mutex, access log. |
+| `integrations/` | First-party plugins: `hermes/`, `openclaw/`, `filesystem-watcher/`. |
+| `plugin/` | Claude Code plugin (`agentmemory@agentmemory`). |
+| `website/` | Marketing site (Next.js 16). |
+| `test/` | Vitest test suite. |
+
+## Adding an MCP tool
+
+1. Register the function in `src/functions/<area>.ts`.
+2. Register the HTTP trigger in `src/triggers/api.ts` with a matching `api_path`.
+3. Add the tool entry in `src/mcp/tools-registry.ts`.
+4. Implement in `src/mcp/standalone.ts` if the standalone MCP package should also expose it.
+5. Write a test under `test/`.
+6. No CHANGELOG touch in the PR itself — release PRs are the only place CHANGELOG changes.
+
+## Adding an auto-hook
+
+1. Add the new `HookType` string to the union in `src/types.ts`.
+2. Wire the handler in `src/hooks/<hook-name>.ts`.
+3. Add a Vitest case that fires the hook and asserts the observation gets written.
+
+## Release process
+
+Maintainers cut releases. Every bump touches 8 files in lockstep:
+
+1. `package.json`
+2. `package-lock.json` (top + `packages[""].version`)
+3. `plugin/.claude-plugin/plugin.json`
+4. `packages/mcp/package.json` (self + `~x.y.z` pin on the main package)
+5. `src/version.ts` (extend the union, assign)
+6. `src/types.ts` (`ExportData.version` union)
+7. `src/functions/export-import.ts` (`supportedVersions` Set)
+8. `test/export-import.test.ts` (assertion)
+
+Then: CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance.
+
+## Security issues
+
+Do not open a public issue for a security report. See [SECURITY.md](./SECURITY.md).
+
+## Questions
+
+- Implementation questions: open a GitHub Discussion.
+- Governance questions: open an issue labeled `governance`. See [GOVERNANCE.md](./GOVERNANCE.md).

Caddyfile

@@ -0,0 +1,26 @@
+:7860 {
+    # Route WebSocket streams (iii-stream on 3112)
+    # Keep full path — iii-stream expects /stream/mem-live/viewer
+    handle /stream/* {
+        reverse_proxy localhost:3112 {
+            header_up Host localhost:3112
+            header_up Authorization "Bearer {env.AGENTMEMORY_SECRET}"
+        }
+    }
+
+    # Route REST API endpoints (iii-http on 3111)
+    # Caddy injects the secret so the dashboard viewer works without exposing it to the browser
+    handle /agentmemory/* {
+        reverse_proxy localhost:3111 {
+            header_up Host localhost:3111
+            header_up Authorization "Bearer {env.AGENTMEMORY_SECRET}"
+        }
+    }
+
+    # Route Viewer dashboard (on 3113)
+    handle {
+        reverse_proxy localhost:3113 {
+            header_up Host localhost:3113
+        }
+    }
+}

DESIGN.md

@@ -0,0 +1,288 @@
+# Design System Inspired by Lamborghini
+
+## 1. Visual Theme & Atmosphere
+
+Lamborghini's website is a cathedral of darkness — a digital stage where jet-black surfaces stretch infinitely and every element emerges from the void like a machine under a spotlight. The page is almost entirely black. Not dark gray, not near-black — true, uncompromising black (`#000000`) that saturates the viewport and refuses to yield. Into this abyss, white type and Lamborghini Gold (`#FFC000`) are deployed with surgical precision, creating a visual language that feels like walking through a nighttime motorsport event where every surface absorbs light except the things that matter.
+
+The hero is a full-viewport video — dark, cinematic, immersive — showing event footage or vehicle reveals with the Lamborghini bull logo floating ethereally above. The navigation is minimal: a centered bull logo, a "MENU" hamburger on the left, and search/bookmark icons on the right, all rendered in white against the black canvas. There are no borders, no visible nav containers, no background color on the header — just white marks floating in darkness. The overall mood is nocturnal luxury: exclusive, theatrical, and deliberately intimidating. Each section transition is a scroll through darkness into the next revelation.
+
+Typography is the voice of this darkness. LamboType — a custom Neo-Grotesk typeface created by Character Type and design agency Strichpunkt — is used for everything from 120px uppercase display headlines to 10px micro labels. Its distinctive 12° angled terminals are inspired by the aerodynamic lines of Lamborghini's super sports cars, and its proportions range from Normal to Ultracompressed width. Headlines SHOUT in uppercase at enormous scales with tight line-heights (0.92 at 120px), creating dense blocks of text that feel stamped from steel. The typeface carries hexagonal geometric DNA — constructed from hexagons, three-armed stars, and circles — that echoes throughout the interface in the hexagonal pause button and UI icons. Built on Bootstrap grid with 68 Element Plus/UI components, the technical infrastructure is substantial beneath the theatrical surface.
+
+**Key Characteristics:**
+- True black (`#000000`) dominant surfaces with white and gold as the only relief colors
+- LamboType custom Neo-Grotesk font with 12° angled terminals inspired by aerodynamic car lines
+- Lamborghini Gold (`#FFC000`) as the sole accent color — used exclusively for primary CTA buttons
+- All-uppercase display typography at extreme scales (120px, 80px, 54px) with tight line-heights
+- Full-viewport video heroes with cinematic event/vehicle content
+- Zero border-radius on buttons — sharp, angular, uncompromising rectangles
+- Hexagonal motifs in UI elements (pause button, icon system) echoing brand geometry
+- Bootstrap grid system + Element Plus/UI 68 components underneath
+- Transparent ghost buttons with white borders at 50% opacity as the secondary CTA pattern
+
+## 2. Color Palette & Roles
+
+### Primary
+- **Lamborghini Gold** (`#FFC000`): The signature accent color — a warm, saturated amber-gold (rgb 255, 192, 0) used exclusively for primary action buttons ("Discover More", "Tickets", "Start Configuration"). The only chromatic color in the entire interface, it ignites against the black canvas like a headlight cutting through night
+- **Pure White** (`#FFFFFF`): Primary text color on dark surfaces, logo rendering, nav elements, and light-mode button fills — the voice that speaks from the darkness
+
+### Secondary & Accent
+- **Dark Gold** (`#917300`): Hover/pressed state for gold buttons — a deep amber (rgb 145, 115, 0) that darkens the gold to signal interaction
+- **Gold Text** (`#FFCE3E`): Slightly lighter gold variant (rgb 255, 206, 62) used for inline text accents and highlighted labels
+- **Cyan Pulse** (`#29ABE2`): Electric blue-cyan (rgb 41, 171, 226) appearing as an informational accent and interactive element highlight
+- **Link Blue** (`#3860BE`): Medium blue (rgb 56, 96, 190) used universally for link hover states across all text colors
+
+### Surface & Background
+- **Absolute Black** (`#000000`): The dominant surface color — used for page background, hero sections, header, footer, and most containers
+- **Charcoal** (`#202020`): Elevated dark surface (rgb 32, 32, 32) — the primary "dark gray" for cards, panels, and text containers sitting above the black canvas
+- **Dark Iron** (`#181818`): Subtle surface variant (rgb 24, 24, 24) — barely distinguishable from black, used for footer and deep sections
+- **Overlay Black** (`rgba(0,0,0,0.7)`): Semi-transparent overlay for modals and video dimming
+- **Near White** (`#F8F8F8`): Rare light surface (rgb 248, 248, 248) for content blocks in white-mode sections
+- **Mist** (`#E6E6E6`): Light gray surface for secondary light-mode containers
+
+### Neutrals & Text
+- **Pure White** (`#FFFFFF`): Primary text on dark backgrounds — headlines, body, nav labels
+- **Smoke** (`#F5F5F5`): Secondary text on dark surfaces — slightly softer than pure white
+- **Graphite** (`#494949`): Dark gray text on light surfaces (rgb 73, 73, 73)
+- **Ash** (`#7D7D7D`): Mid-range gray for muted text, timestamps, and metadata (rgb 125, 125, 125)
+- **Steel** (`#969696`): Lighter gray for disabled text and subtle labels (rgb 150, 150, 150)
+- **Slate** (`#666666`): Alternative mid-gray for secondary content
+- **Iron** (`#555555`): Dark mid-gray for body text variants
+- **Shadow** (`#313131`): Very dark gray for text on dark surfaces where white is too strong
+
+### Semantic & Accent
+- **Cyan Pulse** (`#29ABE2`): Used for informational highlights and interactive feedback
+- **Link Blue** (`#3860BE`): Universal hover state for all hyperlinks
+- **Teal Action** (`#1EAEDB`): Button hover background for transparent/ghost variants (rgb 30, 174, 219)
+
+### Gradient System
+- No explicit gradients in the color palette — the dark-to-light progression is achieved through surface layering: `#000000` → `#181818` → `#202020` → `#494949` → `#7D7D7D`
+- Video heroes use natural atmospheric gradients from the content itself
+- Top-of-page gradient: subtle dark-to-darker fade at the edges of full-bleed imagery
+
+## 3. Typography Rules
+
+### Font Family
+- **Display & UI**: `LamboType`, Roboto, Helvetica Neue, Arial — custom Neo-Grotesk typeface by Character Type for Lamborghini's 2024 brand refresh. Available in widths from Normal to Ultracompressed and weights from Light (300) to Black. Features 12° angled terminals inspired by aerodynamic car geometry, hexagonal construction logic, and support for 200+ languages including Latin, Cyrillic, and Greek
+- **Fallback/UI**: `Open Sans` — used for some button/form contexts as system fallback
+- **No italic variants** observed on the marketing site — the brand voice is always upright
+
+### Hierarchy
+
+| Role | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|--------|-------------|----------------|-------|
+| Hero Display | 120px (7.50rem) | 400 | 0.92 | normal | LamboType, uppercase, maximum impact |
+| Display 2 | 80px (5.00rem) | 400 | 1.13 | normal | LamboType, uppercase, major section titles |
+| Section Title | 54px (3.38rem) | 400 | 1.19 | normal | LamboType, uppercase |
+| Sub-section | 40px (2.50rem) | 400 | 1.15 | normal | LamboType, uppercase |
+| Feature Heading | 27px (1.69rem) | 400 | 1.37 | normal | LamboType, uppercase |
+| Card Title | 24px (1.50rem) | 400 | — | normal | LamboType |
+| Body Large | 18px (1.13rem) | 400 | 1.56 | normal | LamboType, mixed case and uppercase variants |
+| Body / UI | 16px (1.00rem) | 400/700 | 1.50 | normal/0.16px | LamboType, primary body text |
+| Button Large | 16px (1.00rem) | 400 | 1.50 | normal | Gold CTA buttons |
+| Button Standard | 14.4px (0.90rem) | 300/700 | 1.00 | 0.14–0.2px | LamboType, uppercase, ghost buttons |
+| Button Small | 13px (0.81rem) | 300/500 | 1.20 | 0.13–0.2px | LamboType, compact button variant |
+| Caption | 14px (0.88rem) | 600/700 | 1.14–1.50 | -0.42px | LamboType, uppercase, negative tracking |
+| Label | 12px (0.75rem) | 400/500 | 1.83 | 0.96px | LamboType, uppercase badges and micro labels |
+| Micro | 10px (0.63rem) | 400 | 1.00–2.00 | 0.225px | LamboType, uppercase, smallest text |
+
+### Principles
+- **ALL-CAPS is the default voice**: Display and feature headings are universally uppercase. This creates a shouting, commanding tone that matches the brand's aggression
+- **Extreme scale range**: From 120px heroes to 10px micro labels — a 12:1 ratio that creates dramatic visual hierarchy
+- **Tight line-heights at scale**: Display sizes use 0.92-1.19 line-height, creating dense, compressed blocks of type that feel stamped rather than typeset
+- **Weight 400 dominates**: Unlike many design systems that use bold for emphasis, Lamborghini's regular weight carries the headlines — the typeface itself is so distinctive it doesn't need weight variation
+- **Negative tracking on captions**: -0.42px letter-spacing on 14px captions creates a compressed, technical aesthetic
+- **Positive tracking on micro text**: +0.225px at 10px ensures legibility at the smallest sizes
+- **Single typeface discipline**: LamboType handles everything — the 12° angled terminals and hexagonal geometry provide visual coherence across all sizes
+
+## 4. Component Stylings
+
+### Buttons
+All buttons use **zero border-radius** — sharp, angular rectangles that echo the aggressive lines of Lamborghini vehicles.
+
+**Gold Accent CTA** — The primary action:
+- Default: bg `#FFC000` (Lamborghini Gold), text `#000000`, padding 24px, fontSize 16px, fontWeight 400, borderRadius 0px, no border
+- Hover: bg `#917300` (Dark Gold), darkens significantly
+- Class: `btn-accent btn-large`
+- Used for: "Discover More", "Tickets", "Start Configuration"
+
+**Transparent Ghost** — The secondary action on dark backgrounds:
+- Default: bg transparent, text `#FFFFFF`, border 1px solid `#FFFFFF`, padding 16px, opacity 0.5
+- Hover: bg `#1EAEDB` (Teal Action), text white, opacity 0.7
+- Focus: bg `#1EAEDB`, border 1px solid `#000000`, outline 2px solid `#000000`
+- Used for: secondary CTAs on hero sections and dark panels
+
+**White Filled** — Light-mode primary:
+- Default: bg `#FFFFFF`, text `#202020`, no border
+- Used for: CTAs on dark sections where gold isn't appropriate
+
+**Black Filled** — Dark filled variant:
+- Default: bg `#000000`, text `#202020`
+- Used for: Inverted CTA on light sections
+
+**Gray Neutral** — Subtle action:
+- Default: bg `#969696`, text `#202020`
+- Used for: secondary/tertiary actions, badge-like buttons
+
+### Cards & Containers
+- Background: `#202020` (Charcoal) on black canvas, or `#000000` on lighter sections
+- Border: `0px 1px solid #202020` bottom borders for section dividers
+- Border-radius: 0px (completely sharp corners)
+- Shadow: minimal, uses overlay opacity for depth
+- Content: full-bleed photography + overlaid text in white
+
+### Inputs & Forms
+- Minimal form presence on the marketing site
+- Switch elements: border-radius 20px (the only rounded element), border 1px solid `#DDDDDD`
+- Cookie banner input style: white text on black with `#7D7D7D` borders
+
+### Navigation
+- **Desktop**: Centered bull logo, "MENU" hamburger with icon on left, search icon + bookmarks icon on right
+- **Background**: Transparent (inherits black page background)
+- **Sticky**: Fixed to top, floats above content
+- **No visible borders or shadows** — elements float in the darkness
+- **"MENU" label**: White text at 14px weight 400, uppercase, accompanies hamburger icon
+- **Hexagonal motifs**: Pause button on hero sections uses hexagonal outline shape
+
+### Image Treatment
+- **Hero**: Full-viewport video sections (100vh) with cinematic event/vehicle footage
+- **Event photography**: Full-bleed aerial shots of Lamborghini Arena events
+- **Vehicle imagery**: High-contrast studio shots on dark backgrounds, full-width
+- **Aspect ratios**: Predominantly 16:9 and wider for cinematic feel
+- **Dark gradient overlays**: Subtle darkening at top/bottom edges of video to ensure text legibility
+
+### Distinctive Components
+- **Hexagonal Pause Button**: Video control uses a hexagonal outline (matching the brand's geometric DNA from the typeface), positioned bottom-right of hero sections
+- **Progress Bar**: Thin white line at bottom of hero sections indicating video/slide progress
+- **Badge/Tag**: bg `#969696`, text white, padding 8px, fontSize 10px, borderRadius 2px — tiny metallic pills
+
+## 5. Layout Principles
+
+### Spacing System
+- **Base unit**: 8px
+- **Full scale**: 2px, 4px, 5px, 8px, 10px, 12px, 15px, 16px, 20px, 24px, 32px, 40px, 48px, 56px
+- **Button padding**: 16px (ghost), 24px (gold accent)
+- **Section padding**: 48–56px vertical, 40px horizontal
+- **Small spacing**: 2–5px for fine adjustments (badge padding, border spacing)
+
+### Grid & Container
+- **Framework**: Bootstrap grid system (container + row + col)
+- **Max width**: 1440px (largest breakpoint)
+- **Columns**: Standard 12-column Bootstrap grid
+- **Full-bleed**: Hero sections break out of grid to fill viewport edge-to-edge
+- **Content areas**: Centered within 1200px max-width containers
+
+### Whitespace Philosophy
+Lamborghini uses darkness as whitespace. The generous black expanses between content blocks serve the same function as white space in a light design — creating breathing room that elevates each element to the status of exhibit. A model name floating in the middle of a black viewport has the same visual weight as a gallery piece on a white wall. The absence of color IS the design.
+
+### Border Radius Scale
+| Value | Context |
+|-------|---------|
+| 0px | Default for everything — buttons, cards, containers, images |
+| 1px | Subtle span elements |
+| 2px | Badges, close buttons, cookie elements — barely perceptible |
+| 20px | Toggle switches only — the sole rounded element |
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Level 0 (Abyss) | `#000000` flat | Page background, deepest layer |
+| Level 1 (Surface) | `#181818` or `#202020` | Cards, content panels, elevated sections |
+| Level 2 (Overlay) | `rgba(0,0,0,0.7)` | Modal backdrops, video dimming |
+| Level 3 (Fog) | `rgba(0,0,0,0.5)` | Lighter overlays, hover states |
+| Level 4 (Mist) | `rgba(0,0,0,0.25)` | Subtle depth hints |
+
+### Shadow Philosophy
+Lamborghini achieves depth through surface color layering rather than shadows. On a black canvas, traditional drop shadows are invisible — instead, the system creates elevation by shifting from absolute black to progressively lighter dark grays: `#000000` → `#181818` → `#202020` → `#494949`. This "darkness gradient" approach means that elevated elements are literally lighter than their surroundings, inverting the traditional shadow model.
+
+### Decorative Depth
+- Full-bleed video provides atmospheric depth through cinematic lighting
+- The hexagonal pause button floats with a thin white outline stroke
+- Progress bars at hero section bottoms create a subtle horizon line
+- No gradients, glows, or blur effects on UI elements — the photography provides all visual richness
+
+## 7. Do's and Don'ts
+
+### Do
+- Use absolute black (`#000000`) as the primary background — never dark gray as a substitute
+- Apply Lamborghini Gold (`#FFC000`) exclusively for primary CTA buttons — never for decorative purposes
+- Set all display headings in uppercase with LamboType — the brand voice is always SHOUTING
+- Use zero border-radius on buttons and cards — sharp angles are non-negotiable
+- Maintain tight line-heights (0.92–1.19) on display type to create dense, architectural text blocks
+- Use the transparent ghost button (white border, 50% opacity) as the secondary CTA on dark backgrounds
+- Let full-viewport video/photography carry emotional weight — UI is infrastructure, not decoration
+- Reserve hexagonal geometry for UI icons and the video control button
+- Use weight 400 (regular) for headlines — the typeface is distinctive enough without bold emphasis
+- Keep the gray palette achromatic — all neutrals are pure gray without color tinting
+
+### Don't
+- Introduce additional accent colors beyond gold — the monochrome-plus-gold system is sacred
+- Apply border-radius to buttons or cards — curved edges contradict the angular vehicle aesthetic
+- Use LamboType in italic or decorative styles — the brand is always upright and direct
+- Add gradients to buttons or surfaces — depth comes from surface layering, not blending
+- Use light backgrounds as the primary canvas — darkness is the default state, light is the exception
+- Mix lowercase into display headings — the uppercase convention communicates authority and power
+- Add hover animations with scale or translate — interactions should be color-only (background/opacity shifts)
+- Use Open Sans for display text — LamboType must handle all visible typography
+- Create busy layouts with many small elements — Lamborghini's design is about singular, bold statements
+- Apply shadows to elements — on a black canvas, shadows are meaningless; use surface color shifts instead
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile Small | <425px | Single column, reduced type scale, stacked buttons |
+| Mobile | 425-576px | Single column, hamburger nav, hero text ~40px |
+| Tablet Small | 576-768px | 2-column grid begins, padding adjusts |
+| Tablet | 768-1024px | 2-column layout, expanded hero, vehicle cards side-by-side |
+| Desktop | 1024-1280px | Full navigation, 3+ column grids, display text at 80px |
+| Desktop Large | 1280-1440px | Full layout, hero at 120px display, max-width containers |
+| Wide | >1440px | Content centered, margins expand, hero fills viewport |
+
+### Touch Targets
+- Gold CTA buttons: 48px+ minimum height with 24px padding (exceeds WCAG 44×44px)
+- Ghost buttons: 48px+ with 16px padding
+- Hamburger menu: large touch target (~48px square)
+- Hexagonal pause button: approximately 48px diameter
+
+### Collapsing Strategy
+- **Navigation**: Always hamburger-based ("MENU" + icon) — no horizontal nav expansion on any breakpoint
+- **Hero video**: Maintains full-viewport height across all breakpoints, adjusting object-fit
+- **Display type**: Scales from 120px (desktop) → 80px (tablet) → 54px/40px (mobile)
+- **Button layout**: Side-by-side on desktop, stacks vertically on mobile
+- **Grid columns**: 3-column → 2-column → 1-column progression
+- **Section spacing**: Reduces from 56px → 40px → 24px vertical padding
+
+### Image Behavior
+- Hero videos use `object-fit: cover` to maintain cinematic framing at all sizes
+- Vehicle images scale within their containers with maintained aspect ratios
+- Event photography crops to viewport width on narrow screens
+- Background images darken at edges to maintain text contrast on all viewports
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Primary CTA: "Lamborghini Gold (#FFC000)"
+- Background: "Absolute Black (#000000)"
+- Surface: "Charcoal (#202020)"
+- Heading text: "Pure White (#FFFFFF)"
+- Body text: "Ash (#7D7D7D)"
+- Link hover: "Link Blue (#3860BE)"
+- Accent: "Cyan Pulse (#29ABE2)"
+- Border: "Pure White (#FFFFFF) at 50% opacity"
+
+### Example Component Prompts
+- "Create a hero section with a full-viewport black background, the model name 'TEMERARIO' in LamboType at 120px uppercase weight 400 white text with 0.92 line-height, centered vertically, with a Lamborghini Gold (#FFC000) 'Discover More' button below — sharp corners, 0px radius, 24px padding, black text"
+- "Design a transparent ghost button with 1px solid white border at 50% opacity, white text at 14.4px uppercase with 0.2px letter-spacing, padding 16px, on a black background — hover state changes to Teal Action (#1EAEDB) background with 70% opacity"
+- "Build a navigation bar with zero visible background on absolute black, a centered bull logo, 'MENU' text label with hamburger icon on the left, and search + bookmark icons on the right — all in white, sticky position"
+- "Create a news card grid on charcoal (#202020) background with white headlines at 27px uppercase, body text in #7D7D7D at 16px, and a white underlined 'Read More' link that turns #3860BE on hover"
+- "Design a section divider using a 1px solid bottom border in #202020 on a black canvas — the elevation difference is purely through surface color shift, not shadow"
+
+### Iteration Guide
+When refining existing screens generated with this design system:
+1. Focus on ONE component at a time — Lamborghini's system is extreme and every element must feel aggressive
+2. Reference specific color names and hex codes from this document — the palette has only about 5 active colors
+3. Use natural language descriptions, not CSS values — "sharp-cut golden rectangle" not "border-radius: 0px; background: #FFC000"
+4. Describe the desired "feel" alongside specific measurements — "floating in total darkness" communicates the black canvas better than "background: #000000"
+5. Remember that UPPERCASE IS THE DEFAULT — if text isn't uppercase at display sizes, it probably should be

Dockerfile

@@ -0,0 +1,42 @@
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    git \
+    openssl \
+    ca-certificates \
+    tini \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Dolt
+RUN curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
+
+# Set up HF Spaces user (uid 1000 required)
+RUN useradd -m -u 1000 user
+
+# Set up workdir
+WORKDIR /app
+
+# Copy python dependencies and install
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# Copy application files
+COPY --chown=user:user src /app/src
+COPY --chown=user:user start.sh /app/start.sh
+COPY --chown=user:user sync.py /app/sync.py
+
+# Give permissions
+RUN chmod +x /app/start.sh && chown -R user:user /app /home/user
+
+# Switch to the non-root user
+USER user
+
+# Set environment
+ENV HOME=/home/user
+
+# Expose the standard HF port
+EXPOSE 7860
+
+ENTRYPOINT ["/usr/bin/tini", "--", "/app/start.sh"]

GOVERNANCE.md

@@ -0,0 +1,88 @@
+# Governance
+
+This document describes how decisions are made in the agentmemory project.
+
+The model here is a near-copy of the [Linux Foundation Minimum Viable Governance (MVG)](https://github.com/todogroup/ospolog/blob/main/governance/minimum-viable-governance.md) pattern, scoped to the project's current single-maintainer reality with a concrete plan to diversify maintainership over the next two release cycles.
+
+## Mission
+
+Ship a persistent, local-first memory runtime for AI coding agents that:
+
+- Requires zero external databases.
+- Runs under any MCP-compatible client.
+- Stays compatible with the open [Model Context Protocol](https://modelcontextprotocol.io).
+- Keeps every user's data on the user's machine by default.
+
+## Roles
+
+### Users
+
+Anyone who runs agentmemory. No process obligation beyond the license. Feedback via [GitHub issues](https://github.com/rohitg00/agentmemory/issues) and [discussions](https://github.com/rohitg00/agentmemory/discussions) is the input channel.
+
+### Contributors
+
+Anyone who opens an issue, comments on an issue, opens a pull request, or otherwise helps the project. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the how-to.
+
+### Maintainers
+
+A Maintainer has commit access to the repository, responsibility for reviewing PRs, and a vote on project-level decisions. The current list is tracked in [MAINTAINERS.md](./MAINTAINERS.md).
+
+A Maintainer is expected to:
+
+- Respond to PRs they are review-owner for within a reasonable window (goal: 3 working days for first comment).
+- Uphold the [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+- Avoid merging their own non-trivial PRs without a second reviewer once the maintainer count is greater than one.
+- Disclose conflicts of interest (employer, paid relationships to users).
+
+### Maintainer acceptance process
+
+A Contributor becomes a Maintainer by:
+
+1. Sustained, high-signal contributions over the prior 6 months (multiple merged PRs across more than one subsystem, plus review comments on others' PRs).
+2. A Maintainer nominates the Contributor in a public PR editing `MAINTAINERS.md`.
+3. The PR stays open for 7 calendar days to collect objections.
+4. If no standing objection from an existing Maintainer, the PR merges and the new Maintainer is added.
+
+A Maintainer steps down by opening a PR that moves their entry to the `Emeritus` section. This is always accepted.
+
+## Decision-making
+
+### Default: lazy consensus on PRs
+
+Most decisions happen inside pull requests. A PR merges when any Maintainer approves it and no other Maintainer blocks it. Silence is assent after 72 hours of no objection.
+
+### Non-PR decisions
+
+Anything that is not a normal code change — charter changes, governance edits, maintainer additions/removals, project scope, breaking API changes, relicensing — happens in a GitHub Issue labeled `governance` with a proposal in the first comment.
+
+- Minor scope decisions: rough consensus in the issue thread, captured by a Maintainer in a summary comment.
+- Formal votes: Maintainers react `+1` / `-1` / `0` to the summary comment. Simple majority of Maintainers with a minimum of two distinct voters carries. If only one Maintainer exists, a 7-day public comment window substitutes for a vote.
+
+### Breaking changes
+
+A breaking change to the REST / MCP surface requires:
+
+1. A tracking issue labeled `breaking` opened at least one minor release cycle ahead of the change.
+2. A deprecation path in the codebase (warning log, feature flag, or adapter) for at least one minor release.
+3. The change landing in the CHANGELOG under a clearly marked `Breaking` sub-section.
+
+## Release process
+
+Releases follow [Semantic Versioning](https://semver.org). See the [release process](./CONTRIBUTING.md#release-process) in `CONTRIBUTING.md` and the automated `.github/workflows/publish.yml` pipeline for the mechanics.
+
+## Conflicts of interest
+
+Maintainers employed by a company that sells a product competing with agentmemory, or by a company whose business depends on agentmemory's roadmap, should disclose that relationship in `MAINTAINERS.md` next to their name. Nothing prohibits such maintainership; transparency is the requirement.
+
+## Amending this document
+
+This document changes by PR. Edits follow the Non-PR decisions path above: open a `governance` issue, collect feedback, then open the PR citing the issue.
+
+## Related documents
+
+- [LICENSE](./LICENSE) — Apache-2.0
+- [CONTRIBUTING.md](./CONTRIBUTING.md) — how to contribute
+- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — community behavior
+- [SECURITY.md](./SECURITY.md) — how to report a vulnerability
+- [MAINTAINERS.md](./MAINTAINERS.md) — who has commit access
+- [ROADMAP.md](./ROADMAP.md) — where the project is heading

INSTALL_FOR_AGENTS.md

@@ -0,0 +1,163 @@
+# Install agentmemory (agent runbook)
+
+You are a coding agent. Follow this runbook top to bottom to install agentmemory, wire it into yourself, and verify that persistent memory works. Run each command, check the result against the "Expect" note, then move on. If a step fails, jump to Troubleshooting, and if it still fails, stop and report the step, the exact command, and the error output.
+
+## What you are installing
+
+agentmemory is a local memory server for coding agents. It runs on your machine, exposes a REST API on port 3111 and an MCP server, and stores memories on disk under `~/.agentmemory`. It is built on the iii engine, which agentmemory downloads and manages for you as a pinned binary under `~/.agentmemory/bin`. You do not install iii separately.
+
+Default mode needs no API key and no cloud account. Out of the box it runs hybrid retrieval (BM25 keyword search plus local on-device embeddings), so a full install proves real semantic recall with zero credentials. An LLM provider key is optional and only unlocks richer summaries and auto-injection (see "Optional: richer features").
+
+## Prerequisites
+
+- Node.js >= 20 and npm. Check with `node -v`.
+- macOS or Linux for the one-command path. On Windows, use WSL2; native Windows engine setup is manual and `agentmemory connect` is not supported there.
+- Ports 3111 (REST), 3112 (streams), 3113 (viewer), and 49134 (engine) free. Override the whole block with `--port <N>` or `--instance <N>` if any are taken.
+
+## Running non-interactively
+
+Several commands prompt on a TTY (for example the first-run "install globally?" question). As an agent you usually want no prompts. Either set `CI=1` in the environment for the commands below, or rely on the fact that agentmemory skips all prompts automatically when stdin/stdout are not a TTY. Prompts are also never-nag: once answered they persist and are not asked again. Re-run onboarding any time with `agentmemory --reset`.
+
+## 1. Install globally
+
+```bash
+npm install -g @agentmemory/agentmemory
+```
+
+If you hit `EACCES` on a system Node install (macOS/Linux), retry with `sudo npm install -g @agentmemory/agentmemory`.
+
+No-install alternative: skip this step and run the server with `npx -y @agentmemory/agentmemory@latest` everywhere this runbook says `agentmemory`. The `@latest` and `-y` flags matter because npx caches per version and a bare `npx @agentmemory/agentmemory` can serve a stale release.
+
+Expect: the install completes without errors.
+
+## 2. Verify the install
+
+```bash
+agentmemory --version
+```
+
+Expect: a version string is printed. If `command not found`, the global bin is not on `PATH`; use the `npx -y @agentmemory/agentmemory@latest` form instead.
+
+## 3. Start the server
+
+The server listens on port 3111 and auto-starts its pinned iii engine on first run (this can take a few seconds the first time while the engine binary is fetched into `~/.agentmemory/bin`). Run it in the background or in a separate terminal so the rest of the runbook can talk to it.
+
+```bash
+agentmemory &
+```
+
+Or in a dedicated terminal, run `agentmemory` in the foreground. To run a second isolated instance, use `agentmemory --instance 1` (relocates the whole port block to 3211/3212/3213/49234).
+
+Wait until it is reachable, then continue:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+```
+
+Expect: a `200` response. Retry for up to ~15 seconds on first run while the engine warms up.
+
+## 4. Prove recall in one command
+
+```bash
+agentmemory demo --serve
+```
+
+`--serve` boots the server, seeds three realistic sessions (JWT auth, an N+1 query fix, rate limiting), runs semantic searches against them, prints the results, and tears everything down. No second terminal needed.
+
+Expect: the demo finds the "N+1 query fix" memory when it searches for "database performance optimization", which keyword matching alone cannot do. Open `http://localhost:3113` while it runs to watch the memory build live.
+
+## 5. Wire MCP into the calling agent
+
+Detect which agent is running this runbook, then wire its MCP config:
+
+```bash
+agentmemory connect <agent>
+```
+
+`connect` merges agentmemory into that agent's MCP config and preserves any existing servers. Supported agent names:
+
+`claude-code`, `copilot-cli`, `codex`, `cursor`, `gemini-cli`, `opencode`, `cline`, `continue`, `droid`, `hermes`, `openclaw`, `openhuman`, `pi`, `qwen`, `warp`, `zed`, `antigravity`, `kiro`.
+
+If you cannot tell which agent you are, default to `claude-code`. After wiring, restart the agent or run its MCP reload command (for example `/mcp` in Claude Code) so it picks up the server.
+
+Expect: the agent now lists agentmemory's tools. With the server running you should see the full set of 53 tools (for example `memory_save`, `memory_smart_search`, `memory_sessions`). If you see only 7 tools, the MCP shim could not reach a server, see Troubleshooting.
+
+## 6. Install native skills
+
+```bash
+npx skills add rohitg00/agentmemory -y
+```
+
+This installs the native skills so the agent knows when to call the memory tools, not just that they exist. `connect` makes the tools available; skills teach the agent when to use them.
+
+Expect: the skills are installed for the detected agent.
+
+## 7. Verify a save and recall round-trip
+
+Confirm health first:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/health
+```
+
+Expect: a JSON body with an ok status.
+
+Now write a memory and read it back. If MCP is wired, call the `memory_save` tool followed by `memory_smart_search`. Otherwise use REST directly (note: these are the REST paths, which differ from the MCP tool names):
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/remember \
+  -H "Content-Type: application/json" \
+  -d '{"content":"agentmemory install verification probe","concepts":["install-check"]}'
+
+curl -X POST http://localhost:3111/agentmemory/smart-search \
+  -H "Content-Type: application/json" \
+  -d '{"query":"install verification probe","limit":5}'
+```
+
+Expect: the first call returns `201`, the second returns `200` with results that include the probe memory you just saved.
+
+If `AGENTMEMORY_SECRET` is set in the environment, the REST API requires it. Add `-H "Authorization: Bearer $AGENTMEMORY_SECRET"` to both calls. By default no secret is set and localhost is open.
+
+## Optional: richer features
+
+These are off by default because they spend tokens. Enable them only if the user wants them. Put configuration in `~/.agentmemory/.env` (no `export` prefix), then restart the server.
+
+- `AGENTMEMORY_INJECT_CONTEXT=true` makes the SessionStart and PreToolUse hooks inject past memory into the agent's context automatically. Cost: spends session tokens proportional to tool-call frequency.
+- `AGENTMEMORY_AUTO_COMPRESS=true` sends each observation to your LLM provider for a richer summary. Cost: spends API tokens proportional to tool-use frequency. Requires a provider key.
+- Provider key: set one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, and similar, in the same file. Without a key, agentmemory stays in zero-LLM mode and still indexes and recalls via BM25 plus local embeddings.
+
+## Tool surface
+
+The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 8-tool set on hosts with tight tool limits. The 8 core tools cover save, recall, smart search, sessions, export, audit, and governance delete.
+
+## Lifecycle commands
+
+- `agentmemory status` shows server and engine state.
+- `agentmemory doctor` runs diagnostics and reports what is misconfigured.
+- `agentmemory stop` stops the engine this CLI started (`stop --force` bypasses the Docker guard).
+- `agentmemory upgrade` upgrades agentmemory and the iii runtime, best effort.
+- `agentmemory --reset` wipes onboarding preferences and re-runs the wizard.
+- `agentmemory import-jsonl <file>` imports prior Claude Code session logs as memories.
+
+## Troubleshooting
+
+- `command not found: agentmemory`: the global bin is not on `PATH`. Use `npx -y @agentmemory/agentmemory@latest`.
+- `EACCES` during global install: retry with `sudo`, or use the npx form.
+- Stale npx version: run `npx -y @agentmemory/agentmemory@latest`, or clear the cache with `rm -rf ~/.npm/_npx` (macOS/Linux).
+- Port already in use: another instance or process holds 3111. Stop it, or relocate with `agentmemory --instance 1`.
+- Server starts but `livez` never returns 200: re-run with `agentmemory --verbose` to see engine stderr.
+- Engine version warning on start: harmless. agentmemory uses its own pinned engine in `~/.agentmemory/bin` regardless of any `iii` on `PATH`. Set `AGENTMEMORY_III_VERSION` only to override deliberately.
+- Only 7 tools visible in the agent: the MCP shim is in local fallback because it could not reach a server. Start `npx @agentmemory/agentmemory` and ensure `AGENTMEMORY_URL` points at it (default `http://localhost:3111`), then reload MCP.
+- Windows: use WSL2 for the path above. Native Windows runs the server but `connect` and the automated engine install are not supported.
+
+## Report success
+
+Report back to the user:
+
+- agentmemory installed, version, and the server running on port 3111
+- which agent was wired via `agentmemory connect`, and the tool count the agent now sees
+- the save and recall round-trip returned the probe memory
+- the viewer is available at `http://localhost:3113`
+- whether any optional features were enabled
+
+If any step failed, report which step, the exact command, and the error output.

LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Rohit Ghumare
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

MAINTAINERS.md

@@ -0,0 +1,21 @@
+# Maintainers
+
+The authoritative list of people with commit access. See [GOVERNANCE.md](./GOVERNANCE.md) for what a Maintainer is, what they do, and how someone becomes one.
+
+## Active
+
+| Name | GitHub | Affiliation | Area of focus | Since |
+|-|-|-|-|-|
+| Rohit Ghumare | [@rohitg00](https://github.com/rohitg00) | Independent | Project lead, all subsystems | 2026-01 |
+
+## Emeritus
+
+_None yet._
+
+## Maintainer recruitment
+
+agentmemory is actively looking to diversify maintainership. The growth plan in [ROADMAP.md](./ROADMAP.md) commits to adding at least one additional Maintainer from a different organization by the end of the current growth cycle.
+
+If you have a sustained contribution track record and would like to be considered, open an issue tagged `governance`.
+
+The complete contributor graph, with commit counts and recent activity, lives at <https://github.com/rohitg00/agentmemory/graphs/contributors>.

README.md

@@ -0,0 +1,1532 @@
+<p align="center">
+  <img src="assets/banner.png" alt="agentmemory — Persistent memory for AI coding agents" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    Your coding agent remembers everything. No more re-explaining.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="READMEs/README.zh-CN.md">简体中文</a> |
+  <a href="READMEs/README.zh-TW.md">繁體中文</a> |
+  <a href="READMEs/README.ja-JP.md">日本語</a> |
+  <a href="READMEs/README.ko-KR.md">한국어</a> |
+  <a href="READMEs/README.es-ES.md">Español</a> |
+  <a href="READMEs/README.tr-TR.md">Türkçe</a> |
+  <a href="READMEs/README.ru-RU.md">Русский</a> |
+  <a href="READMEs/README.hi-IN.md">हिन्दी</a> |
+  <a href="READMEs/README.pt-BR.md">Português</a> |
+  <a href="READMEs/README.fr-FR.md">Français</a> |
+  <a href="READMEs/README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1.3k%20stars%20%2F%20182%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1.3k stars / 182 forks on the gist" /></a>
+</p>
+
+<p align="center">
+  <em>The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-recall.svg"><img src="assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tokens.svg"><img src="assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="1,423+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="assets/demo.gif" alt="agentmemory demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#benchmarks">Benchmarks</a> &bull;
+  <a href="#vs-competitors">vs Competitors</a> &bull;
+  <a href="#works-with-every-agent">Agents</a> &bull;
+  <a href="#how-it-works">How It Works</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">Viewer</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">Config</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Install
+
+Fastest path if you use a coding agent: hand it this one instruction and it installs, wires, and verifies agentmemory end to end.
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+On Windows the fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 minutes) and `agentmemory connect` is currently unsupported there. See the [Windows notes](#windows) below for the step-by-step.
+
+```bash
+npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # start the memory server on :3111
+agentmemory demo                                 # seed sample sessions + prove recall
+agentmemory demo --serve                         # one command: boot server, run demo, tear down (no second terminal)
+agentmemory connect claude-code                  # wire MCP into your agent (also: copilot-cli, codex, cursor, gemini-cli, ...)
+npx skills add rohitg00/agentmemory -y           # install 15 native skills (8 you can invoke, 7 reference) so your agent knows when to use the tools
+```
+
+Or via `npx` (no install):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+Heads-up — npx caches per version. If a bare `npx @agentmemory/agentmemory` serves an older release, force the latest with `npx -y @agentmemory/agentmemory@latest`, or clear the cache once with `rm -rf ~/.npm/_npx` (macOS/Linux; on Windows delete `%LOCALAPPDATA%\npm-cache\_npx`). The first npx run from v0.9.16+ prompts to install globally inline so the bare `agentmemory` command works everywhere afterwards.
+
+Full options at [Quick Start](#quick-start) below. Agent-specific wiring at [Works with every agent](#works-with-every-agent).
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-agents.svg"><img src="assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
+
+agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>native plugin + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>native plugin + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/features/copilot"><img src="https://github.githubassets.com/images/modules/site/copilot/copilot.png" alt="GitHub Copilot CLI" width="48" height="48" /></a><br/>
+<strong>GitHub Copilot CLI</strong><br/>
+<sub>MCP + plugin hooks/skills</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="integrations/pi/"><img src="assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>native Memory trait backend</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode" width="48" height="48" /></picture></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/windsurf-dark.svg"><img src="https://svgl.app/library/windsurf-light.svg" alt="Windsurf" width="48" height="48" /></picture></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://www.warp.dev"><img src="https://github.com/warpdotdev.png?size=120" alt="Warp" width="48" height="48" /></a><br/>
+<strong>Warp</strong><br/>
+<sub>connect + MCP + skills</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>Works with <strong>any</strong> agent that speaks MCP or HTTP. One server, memories shared across all of them.</sub>
+</p>
+
+---
+
+You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.
+
+**What changes:** Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in `src/middleware/auth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility. No re-explaining. No copy-pasting. The agent just *knows*.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+Latest release notes: [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-benchmarks.svg"><img src="assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Retrieval Accuracy
+
+**coding-agent-life-v1** (in-house corpus, sandbox-reproducible)
+
+| Adapter | P@5 | R@5 | Top-5 hit rate | p50 latency |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% top-5 hit rate at the **P@5 math ceiling** for this corpus (0.240, see scorecard). Hybrid retrieves every gold session; grep misses 1 of 2 gold on the multi-session temporal query. Lift is **recall + temporal**, not aggregate precision — this benchmark is small + gold-sparse, the larger LongMemEval-S below differentiates better. Full per-type breakdown + correction note: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 questions)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Token Savings
+
+| Approach | Tokens/yr | Cost/yr |
+|---|---|---|
+| Paste full context | 19.5M+ | Impossible (exceeds window) |
+| LLM-summarized | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + local embeddings | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> Embedding model: `all-MiniLM-L6-v2` (local, free, no API key). Full reports: [`benchmark/LONGMEMEVAL.md`](benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](benchmark/QUALITY.md), [`benchmark/SCALE.md`](benchmark/SCALE.md). Competitor comparison: [`benchmark/COMPARISON.md`](benchmark/COMPARISON.md) covering agentmemory vs mem0, Letta, Khoj, supermemory, MemPalace, Hippo.
+
+**Reproduce locally:** [`eval/README.md`](eval/README.md) — adapter-pluggable harness for LongMemEval `_s` (public 500-Q) + `coding-agent-life-v1` (in-house 15-session corpus). Grep / vector / agentmemory adapters score side-by-side, NDJSON output, published scorecards land in [`docs/benchmarks/`](docs/benchmarks/).
+
+**Pairs with [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), and [Graphify](https://github.com/safishamsi/graphify).** Code-graph indexing, multi-agent build pipelines, and broader knowledge graphs across docs / PDFs / images / videos. agentmemory remembers the work; those three projects light up the rest of the context layer. Recipes + question-routing table: [`docs/recipes/pairings.md`](docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-competitors.svg"><img src="assets/tags/section-competitors.svg" alt="vs Competitors" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th></th>
+<th>agentmemory</th>
+<th>mem0 (58K ⭐)</th>
+<th>Letta / MemGPT (23K ⭐)</th>
+<th>Khoj (35K ⭐)</th>
+<th>supermemory (26K ⭐)</th>
+<th>MemPalace (54K ⭐)</th>
+<th>Hippo</th>
+<th>Built-in (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>Type</strong></td>
+<td>Memory engine + MCP server</td>
+<td>Memory layer API</td>
+<td>Full agent runtime</td>
+<td>Personal AI</td>
+<td>Memory API + app</td>
+<td>Vector memory (OSS)</td>
+<td>Memory system</td>
+<td>Static file</td>
+</tr>
+<tr>
+<td><strong>Retrieval R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A</td>
+<td>Self-reported</td>
+<td>~96.6% (self-reported)</td>
+<td>N/A</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>Auto-capture</strong></td>
+<td>12 hooks (zero manual effort)</td>
+<td>Manual <code>add()</code> calls</td>
+<td>Agent self-edits</td>
+<td>Manual</td>
+<td>API-side extraction</td>
+<td>Manual</td>
+<td>Manual</td>
+<td>Manual editing</td>
+</tr>
+<tr>
+<td><strong>Search</strong></td>
+<td>BM25 + Vector + Graph (RRF fusion)</td>
+<td>Vector + Graph</td>
+<td>Vector (archival)</td>
+<td>Semantic</td>
+<td>Vector + RAG</td>
+<td>Vector-only</td>
+<td>Decay-weighted</td>
+<td>Loads everything into context</td>
+</tr>
+<tr>
+<td><strong>Multi-agent</strong></td>
+<td>MCP + REST + leases + signals</td>
+<td>API (no coordination)</td>
+<td>Within Letta runtime only</td>
+<td>No</td>
+<td>No</td>
+<td>No</td>
+<td>Multi-agent shared</td>
+<td>Per-agent files</td>
+</tr>
+<tr>
+<td><strong>Framework lock-in</strong></td>
+<td>None (any MCP client)</td>
+<td>None</td>
+<td>High (must use Letta)</td>
+<td>Standalone</td>
+<td>None</td>
+<td>None</td>
+<td>None</td>
+<td>Per-agent format</td>
+</tr>
+<tr>
+<td><strong>External deps</strong></td>
+<td>None (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + vector DB</td>
+<td>Multiple</td>
+<td>Managed cloud</td>
+<td>Vector store</td>
+<td>None</td>
+<td>None</td>
+</tr>
+<tr>
+<td><strong>Memory lifecycle</strong></td>
+<td>4-tier consolidation + decay + auto-forget</td>
+<td>Passive extraction</td>
+<td>Agent-managed</td>
+<td>Manual</td>
+<td>Auto-forget</td>
+<td>None</td>
+<td>Decay + consolidation</td>
+<td>Manual pruning</td>
+</tr>
+<tr>
+<td><strong>Token efficiency</strong></td>
+<td>~1,900 tokens/session ($10/yr)</td>
+<td>Varies by integration</td>
+<td>Core memory in context</td>
+<td>Varies</td>
+<td>Cloud pricing</td>
+<td>No token budget</td>
+<td>Varies</td>
+<td>22K+ tokens at 240 obs</td>
+</tr>
+<tr>
+<td><strong>Real-time viewer</strong></td>
+<td>Yes (built-in at :3111)</td>
+<td>Cloud dashboard</td>
+<td>Cloud dashboard</td>
+<td>Web UI</td>
+<td>Cloud dashboard</td>
+<td>No</td>
+<td>No</td>
+<td>No</td>
+</tr>
+<tr>
+<td><strong>Self-hosted</strong></td>
+<td>Yes (default)</td>
+<td>Optional</td>
+<td>Optional</td>
+<td>Yes</td>
+<td>No (cloud-only)</td>
+<td>Yes</td>
+<td>Yes</td>
+<td>Yes</td>
+</tr>
+</table>
+
+<sub>Benchmark note: only agentmemory's R@5 is our own measured result (LongMemEval-S, reproducible from <a href="benchmark/COMPARISON.md"><code>benchmark/COMPARISON.md</code></a>). The mem0 and Letta figures are their published LoCoMo numbers (a different dataset); the MemPalace and supermemory figures are vendor self-reported claims we have not independently reproduced. Shown side by side for ballpark only, not a head-to-head on identical data. Star counts are approximate and drift over time.</sub>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-quickstart.svg"><img src="assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
+
+Compatibility: this release targets stable `iii-sdk` `^0.11.0` and iii-engine v0.11.x.
+
+### Try it in 30 seconds
+
+```bash
+# Terminal 1: start the server
+npx @agentmemory/agentmemory
+
+# Terminal 2: seed sample data and see recall in action
+npx @agentmemory/agentmemory demo
+```
+
+`demo` seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs semantic searches against them. You'll see it find "N+1 query fix" when you search "database performance optimization" — keyword matching can't do that.
+
+Open `http://localhost:3111/viewer` to watch the memory build live.
+
+### Recommended: install globally
+
+`npx` caches per-version. If you ran `npx @agentmemory/agentmemory@0.9.14` last week, a bare `npx @agentmemory/agentmemory` may serve the stale 0.9.14 from `~/.npm/_npx/`, not the latest release. Install once and the bare `agentmemory` command works everywhere:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # start the server (same as the npx form)
+agentmemory stop               # tear it down
+agentmemory remove             # uninstall everything we created
+agentmemory connect claude-code   # wire one agent
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+From v0.9.16 onward, the first npx run prompts you to install globally inline — answer `Y` once and you're set. If you skip, fall back to either of these for a fresh fetch:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)
+```
+
+On Windows / PowerShell, the equivalent cache clear is `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — the `npx -y ...@latest` form above is the cross-platform option.
+
+### Session Replay
+
+Every session agentmemory records is replayable. Open the viewer, pick the **Replay** tab, and scrub through the timeline: prompts, tool calls, tool results, and responses render as discrete events with play/pause, speed control (0.5×–4×), and keyboard shortcuts (space to toggle, arrows to step).
+
+Already have older Claude Code JSONL transcripts you want to bring in?
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx @agentmemory/agentmemory import-jsonl
+
+# Or import a single file
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Imported sessions show up in the Replay picker alongside native ones. Under the hood each entry routes through the `mem::replay::load`, `mem::replay::sessions`, and `mem::replay::import-jsonl` iii functions — no side-channel servers.
+
+> **Heads-up if you rely on `import-jsonl` as your primary capture path:** Claude Code's `cleanupPeriodDays` (in `~/.claude/settings.json`, default **30**) auto-deletes JSONL transcripts older than that window from `~/.claude/projects/`. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run `import-jsonl` on a cron, raise `cleanupPeriodDays` to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering.
+
+### Upgrade / Maintenance
+
+Use the maintenance command when you intentionally want to update your local runtime:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies, may run `cargo install iii-engine --force`, and may pull Docker images.
+
+Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cli.ts:544-595` region).
+
+### Claude Code (one block, paste it)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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:3111/viewer.
+```
+
+#### Claude Code without the plugin install (MCP-standalone path)
+
+If you wire agentmemory's MCP server through `~/.claude.json` directly instead of using `/plugin install`, Claude Code never resolves `${CLAUDE_PLUGIN_ROOT}` and you have to point hook scripts at absolute paths in `~/.claude/settings.json`. Those paths typically embed the agentmemory version (e.g. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), so the next upgrade silently breaks every hook ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+Workaround:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+This merges the same hook commands into `~/.claude/settings.json` with absolute paths resolved to the bundled `plugin/` directory of the currently installed `@agentmemory/agentmemory` package. Re-run the command after upgrading agentmemory to refresh the paths. User entries in the same file are preserved; only previous agentmemory entries are replaced. Using the `/plugin install` path remains the recommended approach.
+For remote or protected deployments, launch Claude Code with `AGENTMEMORY_URL` and `AGENTMEMORY_SECRET` set. The plugin passes both values through to its bundled MCP server; when `AGENTMEMORY_URL` is empty, the MCP shim uses `http://localhost:3111`.
+
+### Codex CLI (Codex plugin platform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers:
+
+- `@agentmemory/mcp` as an MCP server (proxies all 53 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)
+- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 8 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide)
+
+Codex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.
+
+#### Codex Desktop: plugin hooks currently silent (workaround available)
+
+`CodexHooks` and `PluginHooks` are both stable + default-enabled in [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), but Codex Desktop builds currently do not dispatch plugin-local `hooks.json` ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). MCP tools still work; only the lifecycle observations are missing.
+
+Until upstream lands the fix, mirror the same hook commands into the global `~/.codex/hooks.json`:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+This adds an idempotent block to `~/.codex/hooks.json` referencing absolute paths to the bundled scripts (no `${CLAUDE_PLUGIN_ROOT}` expansion needed at user-scope). Re-run the same command after upgrading agentmemory to refresh paths. User entries in the same file are preserved; only previous agentmemory entries are replaced.
+
+### GitHub Copilot CLI
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` merges `mcpServers.agentmemory` into `~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set) and preserves existing servers. This adapter is Windows-safe even though other `connect` adapters still require manual Windows setup. Copilot picks up the MCP server on next launch or after `/mcp`. Install the plugin as well when you want the full hook/skill experience.
+
+<details>
+<summary><b>OpenClaw (paste this prompt)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 53 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:3111/viewer 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`.
+```
+
+Full guide: [`integrations/openclaw/`](integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (paste this prompt)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 53 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:3111/viewer for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Full guide: [`integrations/hermes/`](integrations/hermes/)
+
+</details>
+
+### Other agents
+
+Start the memory server: `npx @agentmemory/agentmemory`
+
+#### Native skills via `npx skills add` (50+ agents)
+
+agentmemory ships 15 skills in the Claude-Code-style `<dir>/SKILL.md` format: 8 invocable action skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) and 7 reference skills the agent loads on demand (`agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). The reference skills carry data tables generated from source, so they never drift. The [`skills`](https://npmjs.com/package/skills) CLI by vercel-labs auto-installs them into the calling agent's native skill directory across 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more):
+
+```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
+```
+
+This is **complementary** to `agentmemory connect <agent>`:
+
+- `agentmemory connect <agent>` writes the MCP server config so the tools are available.
+- `npx skills add rohitg00/agentmemory` installs the skills so the agent knows when to call them.
+
+For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 15 SKILL.md files under the agent's native skill directory yourself — same format works everywhere.
+
+#### Standard MCP block
+
+The agentmemory entry is the **same MCP server block** across every host that uses the `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**Merge this entry into the existing `mcpServers` object** in the host's config file — don't replace the file. If the file already has other servers, add `agentmemory` next to them as another key inside `mcpServers`. If `mcpServers` is missing entirely, paste the block inside `{ "mcpServers": { ... } }`. The `${VAR}` placeholders inherit `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` from the shell at MCP-server launch — unset vars pass empty strings and the shim falls back to `http://localhost:3111`. One wired entry covers both local and remote (k8s / reverse-proxied) deployments.
+
+| Agent | Config file | Notes |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | Merge into `mcpServers`. One-click deeplink also available on the website. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge into `mcpServers`. Restart Claude Desktop after editing. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Same `mcpServers` block. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Same `mcpServers` block. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges). |
+| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` merges `mcpServers.agentmemory`; Copilot picks it up on next launch or `/mcp`. |
+| **GitHub Copilot CLI (full plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` for the plugin from the GitHub subdir. |
+| **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block, or use the deeper [memory plugin](integrations/openclaw/). |
+| **Codex CLI (MCP only)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. |
+| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin add agentmemory@agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 15 skills. On Codex Desktop, also run `agentmemory connect codex --with-hooks` until [openai/codex#16430](https://github.com/openai/codex/issues/16430) lands — plugin hooks are currently silent there. |
+| **OpenCode (MCP only)** | `opencode.json` | Different shape — top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (full plugin)** | `plugin/opencode/` | 22 auto-capture hooks covering session lifecycle, messages, tools, errors. Two slash commands (`/recall`, `/remember`). Copy `plugin/opencode/` into your OpenCode workspace and add the plugin entry to `opencode.json`. See [`plugin/opencode/README.md`](plugin/opencode/README.md) for the full hook table + gap analysis. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Copy [`integrations/pi`](integrations/pi/) and restart pi. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Use the deeper [memory provider plugin](integrations/hermes/) with `memory.provider: agentmemory`. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` writes the standard `mcpServers` block. Hook payload is field-compatible with Claude Code, so the existing 12-hook scripts work without modification — wire them via the `hooks` section in the same `settings.json`. |
+| **Antigravity** (replaces Gemini CLI) | `mcp_config.json` (in Antigravity's User dir) | `agentmemory connect antigravity` writes the standard `mcpServers` block. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Use after the 2026-06-18 Gemini CLI sunset. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` writes the user-level config. Workspace overrides go in `.kiro/settings/mcp.json` next to your code. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` writes the standard `mcpServers` block. Warp also auto-discovers skills from `.claude/skills/` — once the Claude Code plugin is installed the 8 agentmemory skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) appear natively in Warp's slash-command palette. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` writes the standard `mcpServers` block. VS Code extension users: paste the same block via Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferred) or `config.json` (legacy) | `agentmemory connect continue` creates `config.yaml` from scratch when neither exists, or modifies existing `config.json`. **If you already have `config.yaml`** the adapter prints the exact block to paste under `mcpServers:` — it won't silently rewrite your yaml because preserving comments and anchors safely needs a YAML parser the package doesn't ship. Continue uses array form (not object) for `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` writes under `context_servers` (Zed's key, NOT `mcpServers`). Remote MCP servers can be wired via `{"url": "..."}` instead. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` writes the standard `mcpServers` block. Project-scoped overrides go in `<repo>/.factory/mcp.json`. The `/mcp` slash command inside droid lists configured servers. |
+| **Goose** | Goose MCP settings UI | Same `mcpServers` block — use `goose configure` → Add Extension → MCP. Direct YAML edit at `~/.config/goose/config.yaml` is supported but the schema uses `extensions:` + `cmd` (not `mcpServers:` + `command`). |
+| **Aider** | n/a | Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` auto-detects the host and merges. |
+
+**Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). See [#234](https://github.com/rohitg00/agentmemory/issues/234) for the diagnostic walkthrough.
+
+### Programmatic access (Python / Rust / Node)
+
+agentmemory registers its core operations as iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any language with an iii SDK can call them directly over `ws://localhost:49134` — no separate REST client per language.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Worked example: [`examples/python/`](examples/python/) (quickstart + observation/recall flow). REST on `:3111` remains available for hosts without an iii runtime.
+
+### From source
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+This starts agentmemory with a local `iii-engine` if `iii` is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to `127.0.0.1` by default.
+
+Install `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.11.2`** — `v0.11.6` introduces a new sandbox-everything-via-`iii worker add` model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with `AGENTMEMORY_III_VERSION=<version>` if you've migrated to the sandbox model manually.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** swap `aarch64-apple-darwin` for `x86_64-apple-darwin`
+- **Linux x64:** swap for `x86_64-unknown-linux-gnu`
+- **Linux arm64:** swap for `aarch64-unknown-linux-gnu`
+- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extract `iii.exe`, add to PATH
+
+Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:0.11.2`). Full docs: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough — you also need the `iii-engine` runtime (a separate native binary) as a background process. The official upstream installer is a `sh` script and there is no PowerShell installer or scoop/winget package today, so Windows users have two paths:
+
+**Option A — Prebuilt Windows binary (recommended):**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe somewhere on PATH, or place it at:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory checks that location automatically)
+# 4. Verify:
+iii --version
+# Should print: 0.11.2
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**Option B — Docker Desktop:**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**Option C — standalone MCP only (no engine):** if you only need the MCP tools for your agent and don't need the REST API, viewer, or cron jobs, skip the engine entirely:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostics for Windows:** if `npx @agentmemory/agentmemory` fails, re-run with `--verbose` to see the actual engine stderr. Common failure modes:
+
+| Symptom | Fix |
+|---|---|
+| `iii-engine process started` then `did not become ready within 15s` | Engine crashed on startup — re-run with `--verbose`, check stderr |
+| `Could not start iii-engine` | Neither `iii.exe` nor Docker is installed. See Option A or B above |
+| Port conflict | `netstat -ano \| findstr :3111` to see what's bound, then kill it or use `--port <N>` |
+| Docker fallback skipped even though Docker is installed | Make sure Docker Desktop is actually running (system tray icon) |
+
+> Note: there is no `cargo install iii-engine` — `iii` is not published to crates.io. The only supported install methods are the prebuilt binary above, the upstream `sh` install script (macOS/Linux only), and the Docker image.
+
+---
+
+<h2 id="deploy">Deploy</h2>
+
+One-click templates for managed hosts. Each one ships a self-contained
+Dockerfile that pulls `@agentmemory/agentmemory` from npm and copies
+the iii engine binary in from the official `iiidev/iii` Docker Hub
+image — no pre-built agentmemory image required. Persistent storage
+mounts at `/data`; the first-boot entrypoint overwrites the
+npm-bundled iii config (which binds `127.0.0.1`) with a deploy-tuned
+one that binds `0.0.0.0` and uses absolute `/data` paths, generates
+the HMAC secret, then drops privileges from `root` to `node` via
+`gosu` before exec'ing the agentmemory CLI.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render's one-click deploy button requires `render.yaml` at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in [`deploy/render/`](./deploy/render/README.md) to point at the in-repo blueprint manually.
+
+Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup,
+cost floors) live in [`deploy/`](./deploy/README.md):
+
+- [`deploy/fly`](./deploy/fly/README.md) — single machine with
+  `auto_stop_machines = "stop"`; cheapest idle.
+- [`deploy/railway`](./deploy/railway/README.md) — Hobby plan flat fee,
+  volume in the dashboard.
+- [`deploy/render`](./deploy/render/README.md) — Blueprint flow,
+  automatic disk snapshots on paid plans.
+- [`deploy/coolify`](./deploy/coolify/README.md) — self-hosted on your
+  own VPS via [Coolify](https://coolify.io/self-hosted); same Docker
+  Compose stack, you own the host and the data.
+
+Port `3111` serves both the API and the built-in HTML viewer. — every template's README documents the
+SSH-tunnel pattern for reaching it.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-why.svg"><img src="assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
+
+Every coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack. agentmemory runs in the background and eliminates that entirely.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### vs built-in agent memory
+
+Every AI coding agent ships with built-in memory — Claude Code has `MEMORY.md`, Cursor has notepads, Cline has memory bank. These work like sticky notes. agentmemory is the searchable database behind the sticky notes.
+
+| | Built-in (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Scale | 200-line cap | Unlimited |
+| Search | Loads everything into context | BM25 + vector + graph (top-K only) |
+| Token cost | 22K+ at 240 observations | ~1,900 tokens (92% less) |
+| Cross-agent | Per-agent files | MCP + REST (any agent) |
+| Coordination | None | Leases, signals, actions, routines |
+| Observability | Read files manually | Real-time viewer on :3111 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-how.svg"><img src="assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>
+
+### Memory Pipeline
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4-Tier Memory Consolidation
+
+Inspired by how human brains process memory — not unlike sleep consolidation.
+
+| Tier | What | Analogy |
+|------|------|---------|
+| **Working** | Raw observations from tool use | Short-term memory |
+| **Episodic** | Compressed session summaries | "What happened" |
+| **Semantic** | Extracted facts and patterns | "What I know" |
+| **Procedural** | Workflows and decision patterns | "How to do it" |
+
+Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved.
+
+### What Gets Captured
+
+| Hook | Captures |
+|------|----------|
+| `SessionStart` | Project path, session ID |
+| `UserPromptSubmit` | User prompts (privacy-filtered) |
+| `PreToolUse` | File access patterns + enriched context |
+| `PostToolUse` | Tool name, input, output |
+| `PostToolUseFailure` | Error context |
+| `PreCompact` | Re-injects memory before compaction |
+| `SubagentStart/Stop` | Sub-agent lifecycle |
+| `Stop` | End-of-session summary |
+| `SessionEnd` | Session complete marker |
+
+### Key Capabilities
+
+| Capability | Description |
+|---|---|
+| **Automatic capture** | Every tool use recorded via hooks — zero manual effort |
+| **Semantic search** | BM25 + vector + knowledge graph with RRF fusion |
+| **Memory evolution** | Versioning, supersession, relationship graphs |
+| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction |
+| **Privacy first** | API keys, secrets, `<private>` tags stripped before storage |
+| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring |
+| **Claude bridge** | Bi-directional sync with MEMORY.md |
+| **Knowledge graph** | Entity extraction + BFS traversal |
+| **Team memory** | Namespaced shared + private across team members |
+| **Citation provenance** | Trace any memory back to source observations |
+| **Git snapshots** | Version, rollback, and diff memory state |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-search.svg"><img src="assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
+
+Triple-stream retrieval combining three signals:
+
+| Stream | What it does | When |
+|---|---|---|
+| **BM25** | Stemmed keyword matching with synonym expansion | Always on |
+| **Vector** | Cosine similarity over dense embeddings | Embedding provider configured |
+| **Graph** | Knowledge graph traversal via entity matching | Entities detected in query |
+
+Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).
+
+BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (`npm install @node-rs/jieba tiny-segmenter`) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.
+
+### Embedding providers
+
+agentmemory auto-detects your provider. For best results, install local embeddings (free):
+
+```bash
+npm install @xenova/transformers
+```
+
+| Provider | Model | Cost | Notes |
+|---|---|---|---|
+| **Local (recommended)** | `all-MiniLM-L6-v2` | Free | Offline, +8pp recall over BM25-only |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ languages, 768/1536/3072 dims (MRL), 2048-token input. Replaces `text-embedding-004` ([deprecated, shutdown Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Highest quality |
+| Voyage AI | `voyage-code-3` | Paid | Optimized for code |
+| Cohere | `embed-english-v3.0` | Free trial | General purpose |
+| OpenRouter | Any model | Varies | Multi-model proxy |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-mcp.svg"><img src="assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>
+
+53 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent.
+
+> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 53-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 53 Tools
+
+<details>
+<summary>Core tools (always available)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `memory_recall` | Search past observations |
+| `memory_compress_file` | Compress markdown files while preserving structure |
+| `memory_save` | Save an insight, decision, or pattern |
+| `memory_patterns` | Detect recurring patterns |
+| `memory_smart_search` | Hybrid semantic + keyword search |
+| `memory_file_history` | Past observations about specific files |
+| `memory_sessions` | List recent sessions |
+| `memory_timeline` | Chronological observations |
+| `memory_profile` | Project profile (concepts, files, patterns) |
+| `memory_export` | Export all memory data |
+| `memory_relations` | Query relationship graph |
+
+</details>
+
+<details>
+<summary>Extended tools (53 total — set AGENTMEMORY_TOOLS=all)</summary>
+
+| Tool | Description |
+|------|-------------|
+| `memory_patterns` | Detect recurring patterns |
+| `memory_timeline` | Chronological observations |
+| `memory_relations` | Query relationship graph |
+| `memory_graph_query` | Knowledge graph traversal |
+| `memory_consolidate` | Run 4-tier consolidation |
+| `memory_claude_bridge_sync` | Sync with MEMORY.md |
+| `memory_team_share` | Share with team members |
+| `memory_team_feed` | Recent shared items |
+| `memory_audit` | Audit trail of operations |
+| `memory_governance_delete` | Delete with audit trail |
+| `memory_snapshot_create` | Git-versioned snapshot |
+| `memory_action_create` | Create work items with dependencies |
+| `memory_action_update` | Update action status |
+| `memory_frontier` | Unblocked actions ranked by priority |
+| `memory_next` | Single most important next action |
+| `memory_lease` | Exclusive action leases (multi-agent) |
+| `memory_routine_run` | Instantiate workflow routines |
+| `memory_signal_send` | Inter-agent messaging |
+| `memory_signal_read` | Read messages with receipts |
+| `memory_checkpoint` | External condition gates |
+| `memory_mesh_sync` | P2P sync between instances |
+| `memory_sentinel_create` | Event-driven watchers |
+| `memory_sentinel_trigger` | Fire sentinels externally |
+| `memory_sketch_create` | Ephemeral action graphs |
+| `memory_sketch_promote` | Promote to permanent |
+| `memory_crystallize` | Compact action chains |
+| `memory_diagnose` | Health checks |
+| `memory_heal` | Auto-fix stuck state |
+| `memory_facet_tag` | Dimension:value tags |
+| `memory_facet_query` | Query by facet tags |
+| `memory_verify` | Trace provenance |
+
+</details>
+
+### 6 Resources · 3 Prompts · 4 Skills
+
+| Type | Name | Description |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, session count, memory count |
+| Resource | `agentmemory://project/{name}/profile` | Per-project intelligence |
+| Resource | `agentmemory://memories/latest` | Latest 10 active memories |
+| Resource | `agentmemory://graph/stats` | Knowledge graph statistics |
+| Prompt | `recall_context` | Search + return context messages |
+| Prompt | `session_handoff` | Handoff data between agents |
+| Prompt | `detect_patterns` | Analyze recurring patterns |
+| Skill | `/recall` | Search memory |
+| Skill | `/remember` | Save to long-term memory |
+| Skill | `/session-history` | Recent session summaries |
+| Skill | `/forget` | Delete observations/sessions |
+
+### Standalone MCP
+
+Run without the full server — for any MCP client. Either of these works:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (always available)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+Or add to your agent's MCP config:
+
+Most agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+Merge the `agentmemory` entry into your host's existing `mcpServers` object rather than replacing the file. For sandboxed clients that can't reach the host's `localhost`, add `"AGENTMEMORY_FORCE_PROXY": "1"` to the env block and set `AGENTMEMORY_URL` to a route the sandbox can reach.
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copy the plugin file from the repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
+
+Built-in on port `3111`. Live observation stream, session explorer, memory browser, knowledge graph visualization, and health dashboard.
+
+```bash
+open http://localhost:3111/viewer
+```
+
+The viewer server binds to `127.0.0.1` by default. The REST-served `/agentmemory/viewer` endpoint follows the normal `AGENTMEMORY_SECRET` bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+The viewer at `:3111` shows what your agent **remembered**. The [iii console](https://iii.dev/docs/console) shows what your agent **did** — every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped.
+
+Watch a `memory_smart_search` fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a `PostToolUse` hook with a tweaked payload. Pin the WebSocket stream and watch observations land live.
+
+agentmemory ships this for free because every function call and trigger fires through iii — nothing custom, nothing to instrument.
+
+<p align="center">
+  <img src="assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
+  <br/>
+  <em>Workers page: every connected worker — including agentmemory itself — with PID, function count, runtime, and last-seen.</em>
+</p>
+
+**Already installed.** The console ships with `iii` — no separate installer.
+
+**Launch alongside agentmemory:**
+
+```bash
+# agentmemory holds port 3111, so run other services on other ports.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
+```
+
+Then open `http://localhost:3114`. Add `--enable-flow` for the experimental architecture-graph page.
+
+Override engine endpoints only if you've moved them:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**What you can do from the console:**
+
+| Page | Use it to |
+|------|-----------|
+| **Workers** | See every connected worker and its live metrics — including the agentmemory worker itself. |
+| **Functions** | Invoke any of agentmemory's functions directly with a JSON payload — handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client. |
+| **Triggers** | Replay HTTP, cron, event, and state triggers — fire the consolidation cron manually, retry an HTTP route, emit a state change. |
+| **States** | KV browser with full CRUD — sessions, memory slots, lifecycle timers, embeddings index — edit values in place. |
+| **Streams** | Live WebSocket monitor for memory writes, hook events, and observation updates as they flow through iii streams. |
+| **Queues** | Durable queue topics + dead-letter management. Replay or drop failed embedding / compression jobs. |
+| **Traces** | OpenTelemetry waterfall / flame / service-breakdown views. Filter by `trace_id` to see exactly which functions, DB calls, and embedding requests a single `memory.search` produced. |
+| **Logs** | Structured OTEL logs filtered and correlated to trace/span IDs. |
+| **Config** | Runtime configuration — see exactly which workers, providers, and ports your engine is running with. |
+| **Flow** | (Optional, `--enable-flow`) Interactive architecture graph of every worker, trigger, and stream. |
+
+<p align="center">
+  <img src="assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
+  <br/>
+  <em>Traces: waterfall / flame / service breakdown for every memory operation.</em>
+</p>
+
+**Traces are already on:**
+
+`iii-config.yaml` ships with the `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs). No extra config needed — the moment agentmemory starts, every memory operation emits a trace span and a structured log the console can read.
+
+If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change `exporter: memory` to `exporter: otlp` and set the collector endpoint per iii's observability docs.
+
+> **Heads-up:** no auth is enforced on the console itself — keep it bound to `127.0.0.1` (the default) and never expose it publicly.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-architecture.svg"><img src="assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory is **already a running [iii](https://iii.dev) instance**. Three primitives — worker, function, trigger — compose the runtime; KV state, streams, and OTEL traces come from iii-state, iii-stream, and iii-observability workers that ship with iii. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them.
+
+That means one more command extends agentmemory with an entire new capability.
+
+### Extend agentmemory with one command
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+Each `iii worker add` registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately — no reload, no new integration, no new container.
+
+| `iii worker add` | What you get on top of agentmemory |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-instance memory: every `remember` fans out, every `search` reads the union |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Scheduled lifecycle — nightly consolidation, weekly snapshots, decay on a fixed clock |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable retries: failed embedding + compression jobs survive restart, no lost observations |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL traces, metrics, logs on every function — wired in `iii-config.yaml` from day one |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code that came out of `memory_recall` runs inside a throwaway VM, not your shell |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-backed state adapter when you outgrow the in-memory KV defaults |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Stand up extra MCP servers next to agentmemory's, share the same engine |
+
+Full registry: [workers.iii.dev](https://workers.iii.dev). Every worker there composes through the same primitives agentmemory uses — and the agentmemory you already have is one of them.
+
+### What iii replaces
+
+| Traditional stack | agentmemory uses |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker supervision |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Custom plugin systems | `iii worker add <name>` |
+
+**174 source files · ~37,800 LOC · 1,423+ tests · 258 functions · 44 KV scopes** — all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-config.svg"><img src="assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### LLM Providers
+
+agentmemory auto-detects from your environment. By default, no LLM calls are made unless you configure a provider or explicitly opt in to the Claude subscription fallback.
+
+| Provider | Config | Notes |
+|----------|--------|-------|
+| **No-op (default)** | No config needed | LLM-backed compress/summarize is DISABLED. Synthetic BM25 compression + recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
+| Gemini | `GEMINI_API_KEY` | Also enables embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Any model |
+| OpenAI API | `OPENAI_API_KEY` | Default `gpt-4o-mini`, override with `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) or `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<your model>` | Anything OpenAI-API-compatible. Zero cost, runs on your hardware. See [Local models](#local-models-ollama-lm-studio-vllm) below. |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in only. Spawns `@anthropic-ai/claude-agent-sdk` sessions — used to cause unbounded Stop-hook recursion (#149 follow-up) so it is no longer the default. |
+
+### Local models (Ollama / LM Studio / vLLM)
+
+agentmemory talks to any OpenAI-API-compatible server, so anything that exposes `/v1/chat/completions` works without code changes. No paid keys, no cloud, no rate limits — runs entirely on your hardware.
+
+**Ollama** (default port `11434`):
+
+```bash
+ollama pull qwen2.5-coder:7b   # or llama3.2:3b, mistral:7b, 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=qwen2.5-coder:7b
+```
+
+**LM Studio** (default port `1234`):
+
+Open LM Studio → Local Server tab → Start Server. Pick any chat model from the picker (Qwen 2.5 Coder, Llama 3.2, DeepSeek, etc.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio                        # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen2.5-coder-7b-instruct         # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: same shape — point `OPENAI_BASE_URL` at whatever URL your server exposes, set `OPENAI_MODEL` to a name your server will accept.
+
+**Model picks for memory work**: compression and summarization are short tasks (<2K tokens in, <500 tokens out) where a 7B instruct model is plenty. Recommendations:
+
+| Model | Size | Why |
+|-------|------|-----|
+| `qwen2.5-coder:7b` | ~4.7 GB | Best at code-shaped sessions; trained on programming + tool-use traces |
+| `llama3.2:3b` | ~2 GB | Smallest sane option — fine for compression, weaker for graph extraction |
+| `mistral:7b-instruct` | ~4.4 GB | Good general-purpose baseline if you don't want code-specific |
+| `deepseek-r1:7b` | ~4.7 GB | Reasoning-tier quality at 7B; slower but cleaner extractions |
+
+Reasoning-class models (`o1`-style with `<think>` blocks) can return empty `content` with a `reasoning` field your local server may not surface. If extractions come back blank, switch to a non-reasoning model first. The `OPENAI_REASONING_EFFORT=none` env can also disable thinking on Ollama Cloud thinking models that mirror the OpenAI reasoning schema.
+
+Local embeddings ship out of the box via `@xenova/transformers` — `EMBEDDING_PROVIDER=local` (default) gives you BGE-small entirely on-device. No extra config needed.
+
+### Cost-aware model selection
+
+Background compression runs on every observation, so model choice meaningfully changes monthly spend. Captured workload data: 635 requests / 888K tokens / 35 hours of active use, run against three OpenRouter models at 2026-05-23 pricing.
+
+| Tier | Model | Input / 1M | Output / 1M | Cost for the captured 35h | Notes |
+|------|-------|------------|-------------|---------------------------|-------|
+| Recommended | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid compression + summarization quality at ~10× lower cost than Sonnet. |
+| Recommended | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | Older but still fine for compression-only workloads. |
+| Recommended | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Strong code reasoning if your sessions are heavily code-shaped. |
+| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | High quality but expensive for always-on background work. |
+| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Similar tier to Sonnet. |
+| Avoid | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | Reasoning-class model; massive overspend for compression. |
+
+agentmemory prints a runtime warning when `OPENROUTER_MODEL` matches a premium-tier pattern. Set `AGENTMEMORY_SUPPRESS_COST_WARNING=1` to silence once you've made an informed choice.
+
+Quality vs cost tradeoff for memory work: compression is a summarization task with relatively loose quality bars (the agent re-reads the summary, not the user). DeepSeek-V4-Pro / Qwen3-Coder land within rounding error of Sonnet on this task while costing ~10× less. Save the premium-tier models for queries you read directly.
+
+Sources: [OpenRouter pricing for Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+In multi-agent setups where several roles share one agentmemory server (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` tags every write with the role that made it. `AGENTMEMORY_AGENT_SCOPE` controls whether recall filters by that tag.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+Two modes:
+
+| Mode | Tag writes | Filter recall | When to use |
+|------|------------|---------------|-------------|
+| `shared` (default) | yes | no | Cross-agent context with audit trail. Architect can see what developer noted, but every row records who said it. |
+| `isolated` | yes | yes | Strict separation. Architect never sees developer's observations / memories / sessions. |
+
+What gets tagged when `AGENT_ID` is set: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. The role flows from `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+What gets filtered in isolated mode: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Each endpoint accepts `?agentId=<role>` to override per-request, and `?agentId=*` to opt out of the env scope entirely. `/memories` also accepts `?includeOrphans=true` to surface pre-AGENT_ID memories whose `agentId` is undefined.
+
+Per-call override at the SDK / REST layer: every mutating endpoint (`/session/start`, `/remember`) accepts an `agentId` field in the request body that wins over the env. Useful for runtimes routing many roles through one server process.
+
+When `AGENT_ID` is unset, memory remains unscoped (legacy behavior, no tags, no filters).
+
+### Ports
+
+agentmemory + iii-engine bind four ports by default. If a restart fails with `port in use`, this table tells you which process to look for.
+
+| Port | Process | Purpose | Env override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Internal streams worker (consumed by agentmemory + viewer) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Real-time viewer (`http://localhost:3111/viewer`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — workers register here, OTel telemetry flows over it | `III_ENGINE_URL` (full URL, default `ws://localhost:49134`) |
+
+Stale-process cleanup when ports stay bound after a crashed run:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` reaps both the worker and the engine pidfile cleanly on graceful shutdown (#640, #474). The manual cleanup above is only for the post-crash case where neither pidfile is left behind.
+
+### Config File
+
+Put agentmemory runtime configuration in `~/.agentmemory/.env` instead of exporting variables in every shell. If the viewer shows a setup hint like `export ANTHROPIC_API_KEY=...`, copy it into this file as `ANTHROPIC_API_KEY=...` without the `export` prefix, then restart agentmemory.
+
+Process environment variables still work and take precedence over values in the file.
+
+On Windows, the same file lives at `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+To test with a Claude Code Pro/Max subscription instead of an API key, opt in explicitly:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is configured. Explicitly opt out with `CONSOLIDATION_ENABLED=false` if you want LLM-free operation. Graph extraction is a separate flag:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false   # opt out of auto-consolidation
+```
+
+### Environment Variables
+
+Create `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (default: 3111 API/viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=false   # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools, lean fallback) or "all" (53 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+128 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
+
+<details>
+<summary>Key endpoints</summary>
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (always public) |
+| `POST` | `/agentmemory/session/start` | Start session + get context |
+| `POST` | `/agentmemory/session/end` | End session |
+| `POST` | `/agentmemory/observe` | Capture observation |
+| `POST` | `/agentmemory/smart-search` | Hybrid search |
+| `POST` | `/agentmemory/context` | Generate context |
+| `POST` | `/agentmemory/remember` | Save to long-term memory |
+| `POST` | `/agentmemory/forget` | Delete observations |
+| `POST` | `/agentmemory/enrich` | File context + memories + bugs |
+| `GET` | `/agentmemory/profile` | Project profile |
+| `GET` | `/agentmemory/export` | Export all data |
+| `POST` | `/agentmemory/import` | Import from JSON |
+| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
+| `POST` | `/agentmemory/team/share` | Share with team |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-development.svg"><img src="assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 1,423+ tests
+npm run test:integration  # API tests (requires running services)
+```
+
+**Prerequisites:** Node.js >= 20, [iii-engine](https://iii.dev/docs) or Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-license.svg"><img src="assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
+
+[Apache-2.0](LICENSE)

READMEs/README.de-DE.md

@@ -0,0 +1,1377 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — Persistentes Gedächtnis für KI-Coding-Agenten" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    Ihr Coding-Agent merkt sich alles. Schluss mit dem ständigen Wiederholen.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Persistentes Gedächtnis für Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode und jeden MCP-Client.
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  Deutsch
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design-Dokument: 1200 stars / 172 forks im Gist" /></a>
+</p>
+
+<p align="center">
+  <em>Das Gist erweitert Karpathys LLM-Wiki-Muster um Confidence Scoring, Lifecycle, Knowledge Graphs und hybride Suche: agentmemory ist die Implementierung.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory-Demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">Installation</a> &bull;
+  <a href="#quick-start">Schnellstart</a> &bull;
+  <a href="#benchmarks">Benchmarks</a> &bull;
+  <a href="#vs-competitors">Vergleich</a> &bull;
+  <a href="#works-with-every-agent">Agenten</a> &bull;
+  <a href="#how-it-works">Funktionsweise</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">Viewer</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">Konfiguration</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # start the memory server on :3111
+agentmemory demo                                 # seed sample sessions + prove recall
+agentmemory connect claude-code                  # wire your agent (also: codex, cursor, gemini-cli, ...)
+```
+
+Oder per `npx` (keine Installation):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+Achtung — npx cached pro Version. Wenn ein nacktes `npx @agentmemory/agentmemory` eine ältere Version liefert, erzwingen Sie die neueste mit `npx -y @agentmemory/agentmemory@latest` oder leeren Sie den Cache einmalig mit `rm -rf ~/.npm/_npx` (macOS/Linux; unter Windows löschen Sie `%LOCALAPPDATA%\npm-cache\_npx`). Der erste npx-Lauf ab v0.9.16+ fordert eine globale Installation inline an, sodass der nackte Befehl `agentmemory` anschließend überall funktioniert.
+
+Vollständige Optionen unter [Schnellstart](#quick-start). Agenten­spezifische Verdrahtung unter [Funktioniert mit jedem Agenten](#works-with-every-agent).
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funktioniert mit jedem Agenten" height="32" /></picture></h2>
+
+agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterstützt. Alle Agenten teilen sich denselben Memory-Server.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>natives Plugin + 12 Hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>natives Plugin + 6 Hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>natives Plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>natives Plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>natives Plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>natives Memory-trait-Backend</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 Hooks + MCP + Plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP-Server</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>Funktioniert mit <strong>jedem</strong> Agenten, der MCP oder HTTP spricht. Ein Server, gemeinsame Erinnerungen für alle.</sub>
+</p>
+
+---
+
+Sie erklären in jeder Session dieselbe Architektur. Sie entdecken dieselben Bugs erneut. Sie bringen dem Agenten dieselben Präferenzen wieder bei. Eingebautes Gedächtnis (CLAUDE.md, .cursorrules) ist bei 200 Zeilen am Ende und veraltet. agentmemory behebt das. Es erfasst stillschweigend, was Ihr Agent tut, komprimiert das Ganze in durchsuchbares Gedächtnis und injiziert beim Start der nächsten Session den passenden Kontext. Ein Befehl. Funktioniert über Agenten hinweg.
+
+**Was sich ändert:** Session 1 richten Sie JWT-Authentifizierung ein. Session 2 fragen Sie nach Rate Limiting. Der Agent weiß bereits, dass Ihre Auth jose-Middleware in `src/middleware/auth.ts` verwendet, dass Ihre Tests Token-Validierung abdecken und dass Sie sich aus Gründen der Edge-Kompatibilität für jose statt jsonwebtoken entschieden haben. Kein Wiederholen. Kein Copy-Paste. Der Agent *weiß es einfach*.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **Neu in v0.9.0** — Landing-Site unter [agent-memory.dev](https://agent-memory.dev), Filesystem-Connector (`@agentmemory/fs-watcher`), das standalone MCP proxyt nun zum laufenden Server, sodass Hooks und Viewer übereinstimmen, Audit-Policy auf jedem Delete-Pfad kodifiziert, der Health-Check meldet `memory_critical` nicht mehr bei kleinen Node-Prozessen. Vollständige Hinweise in [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18).
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Retrieval-Genauigkeit
+
+**coding-agent-life-v1** (interner Korpus, Sandbox-reproduzierbar)
+
+| Adapter | P@5 | R@5 | Top-5-Trefferquote | p50-Latenz |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep-Baseline | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+100 % Top-5-Trefferquote. **2,2×** bessere Präzision als die grep-Baseline bei identischer Eingabe. Volle Aufschlüsselung pro Typ: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 Fragen)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only Fallback | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Token-Einsparungen
+
+| Ansatz | Tokens/Jahr | Kosten/Jahr |
+|---|---|---|
+| Vollständigen Kontext einfügen | 19,5M+ | Unmöglich (überschreitet das Fenster) |
+| LLM-zusammengefasst | ~650K | ~500 $ |
+| **agentmemory** | **~170K** | **~10 $** |
+| agentmemory + lokale Embeddings | ~170K | **0 $** |
+
+</td>
+</tr>
+</table>
+
+> Embedding-Modell: `all-MiniLM-L6-v2` (lokal, kostenlos, kein API-Schlüssel). Vollständige Berichte: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Konkurrenzvergleich: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory vs mem0, Letta, Khoj, claude-mem, Hippo.
+
+**Lokal reproduzieren:** [`eval/README.md`](../eval/README.md) — Adapter-pluggable Harness für LongMemEval `_s` (öffentlich, 500 Fragen) + `coding-agent-life-v1` (interner 15-Session-Korpus). Adapter für grep / vector / agentmemory werden direkt verglichen, NDJSON-Ausgabe, veröffentlichte Scorecards landen in [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Funktioniert kombiniert mit [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) und [Graphify](https://github.com/safishamsi/graphify).** Code-Graph-Indizierung, mehragentige Build-Pipelines und breitere Knowledge Graphs über Docs / PDFs / Bilder / Videos. agentmemory merkt sich die Arbeit; diese drei Projekte beleuchten den Rest der Kontextschicht. Rezepte + Frage-Routing-Tabelle: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="Vergleich mit der Konkurrenz" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">Eingebaut (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>Typ</strong></td>
+<td>Memory-Engine + MCP-Server</td>
+<td>Memory-Layer-API</td>
+<td>Komplette Agenten-Runtime</td>
+<td>Statische Datei</td>
+</tr>
+<tr>
+<td><strong>Retrieval R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/V (grep)</td>
+</tr>
+<tr>
+<td><strong>Auto-Erfassung</strong></td>
+<td>12 Hooks (null manueller Aufwand)</td>
+<td>Manuelle <code>add()</code>-Aufrufe</td>
+<td>Agent bearbeitet sich selbst</td>
+<td>Manuelle Bearbeitung</td>
+</tr>
+<tr>
+<td><strong>Suche</strong></td>
+<td>BM25 + Vector + Graph (RRF-Fusion)</td>
+<td>Vector + Graph</td>
+<td>Vector (Archival)</td>
+<td>Lädt alles in den Kontext</td>
+</tr>
+<tr>
+<td><strong>Multi-Agent</strong></td>
+<td>MCP + REST + Leases + Signals</td>
+<td>API (keine Koordination)</td>
+<td>Nur innerhalb der Letta-Runtime</td>
+<td>Dateien pro Agent</td>
+</tr>
+<tr>
+<td><strong>Framework-Lock-in</strong></td>
+<td>Keiner (jeder MCP-Client)</td>
+<td>Keiner</td>
+<td>Hoch (Letta erforderlich)</td>
+<td>Format pro Agent</td>
+</tr>
+<tr>
+<td><strong>Externe Abhängigkeiten</strong></td>
+<td>Keine (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + Vector-DB</td>
+<td>Keine</td>
+</tr>
+<tr>
+<td><strong>Memory-Lifecycle</strong></td>
+<td>4-stufige Konsolidierung + Decay + Auto-Forget</td>
+<td>Passive Extraktion</td>
+<td>Vom Agenten verwaltet</td>
+<td>Manuelles Pruning</td>
+</tr>
+<tr>
+<td><strong>Token-Effizienz</strong></td>
+<td>~1.900 Tokens/Session (10 $/Jahr)</td>
+<td>Je nach Integration unterschiedlich</td>
+<td>Core Memory im Kontext</td>
+<td>22K+ Tokens bei 240 Beobachtungen</td>
+</tr>
+<tr>
+<td><strong>Echtzeit-Viewer</strong></td>
+<td>Ja (Port 3113)</td>
+<td>Cloud-Dashboard</td>
+<td>Cloud-Dashboard</td>
+<td>Nein</td>
+</tr>
+<tr>
+<td><strong>Self-hosted</strong></td>
+<td>Ja (Standard)</td>
+<td>Optional</td>
+<td>Optional</td>
+<td>Ja</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Schnellstart" height="32" /></picture></h2>
+
+Kompatibilität: Diese Version zielt auf stabiles `iii-sdk` `^0.11.0` und iii-engine v0.11.x ab.
+
+### In 30 Sekunden ausprobieren
+
+```bash
+# Terminal 1: start the server
+npx @agentmemory/agentmemory
+
+# Terminal 2: seed sample data and see recall in action
+npx @agentmemory/agentmemory demo
+```
+
+`demo` befüllt 3 realistische Sessions (JWT-Auth, N+1-Query-Fix, Rate Limiting) und führt semantische Suchen darauf aus. Sie sehen, wie „N+1 query fix" gefunden wird, wenn Sie nach „database performance optimization" suchen — Keyword-Matching kann das nicht.
+
+Öffnen Sie `http://localhost:3113`, um das Memory in Echtzeit aufgebaut zu sehen.
+
+### Empfohlen: global installieren
+
+`npx` cached pro Version. Wenn Sie letzte Woche `npx @agentmemory/agentmemory@0.9.14` ausgeführt haben, kann ein nacktes `npx @agentmemory/agentmemory` das veraltete 0.9.14 aus `~/.npm/_npx/` ausliefern und nicht die neueste Version. Einmal installieren, und der nackte Befehl `agentmemory` funktioniert überall:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # start the server (same as the npx form)
+agentmemory stop               # tear it down
+agentmemory remove             # uninstall everything we created
+agentmemory connect claude-code   # wire one agent
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+Ab v0.9.16 fordert der erste npx-Lauf inline zu einer globalen Installation auf — einmal mit `Y` antworten, fertig. Wenn Sie das überspringen, greifen Sie für einen frischen Fetch auf eine dieser Möglichkeiten zurück:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)
+```
+
+Unter Windows / PowerShell lautet das Äquivalent zum Leeren des Caches `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — die plattformübergreifende Option ist `npx -y ...@latest` oben.
+
+### Session-Replay
+
+Jede Session, die agentmemory aufzeichnet, ist abspielbar. Öffnen Sie den Viewer, wählen Sie den Reiter **Replay** und scrubben Sie durch die Timeline: Prompts, Tool-Aufrufe, Tool-Ergebnisse und Antworten werden als diskrete Events mit Play/Pause, Geschwindigkeitssteuerung (0,5×–4×) und Tastenkürzeln (Leertaste zum Umschalten, Pfeile zum Schrittweisen) gerendert.
+
+Haben Sie ältere Claude-Code-JSONL-Transkripte, die Sie übernehmen wollen?
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx @agentmemory/agentmemory import-jsonl
+
+# Or import a single file
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Importierte Sessions tauchen im Replay-Picker neben den nativen auf. Intern routet jeder Eintrag durch die iii-Funktionen `mem::replay::load`, `mem::replay::sessions` und `mem::replay::import-jsonl` — keine Seitenkanal-Server.
+
+### Upgrade / Wartung
+
+Verwenden Sie den Wartungsbefehl, wenn Sie Ihr lokales Runtime bewusst aktualisieren wollen:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+Achtung: Dieser Befehl verändert den aktuellen Workspace/Runtime. Er kann JavaScript-Abhängigkeiten aktualisieren, ggf. `cargo install iii-engine --force` ausführen und Docker-Images ziehen.
+
+Implementierungsdetails in `src/cli.ts` (siehe `runUpgrade` rund um den Bereich `src/cli.ts:544-595`).
+
+### Claude Code (ein Block, einfügen)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Claude Code ohne Plugin-Installation (MCP-Standalone-Pfad)
+
+Wenn Sie den MCP-Server von agentmemory direkt über `~/.claude.json` verdrahten anstatt über `/plugin install`, löst Claude Code `${CLAUDE_PLUGIN_ROOT}` niemals auf, und Sie müssen Hook-Skripte in `~/.claude/settings.json` auf absolute Pfade zeigen lassen. Diese Pfade enthalten typischerweise die agentmemory-Version (z. B. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), sodass das nächste Upgrade jeden Hook stillschweigend bricht ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+Workaround:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Das mischt dieselben Hook-Befehle in `~/.claude/settings.json` ein, mit absoluten Pfaden, die in das mitgelieferte `plugin/`-Verzeichnis des aktuell installierten `@agentmemory/agentmemory`-Pakets auflösen. Führen Sie den Befehl nach einem agentmemory-Upgrade erneut aus, um die Pfade zu aktualisieren. Eigene Einträge in derselben Datei bleiben erhalten; nur frühere agentmemory-Einträge werden ersetzt. Den `/plugin install`-Pfad zu nutzen, bleibt der empfohlene Ansatz.
+Für entfernte oder geschützte Deployments starten Sie Claude Code mit gesetztem `AGENTMEMORY_URL` und `AGENTMEMORY_SECRET`. Das Plugin reicht beide Werte an seinen mitgelieferten MCP-Server weiter; ist `AGENTMEMORY_URL` leer, verwendet das MCP-Shim `http://localhost:3111`.
+
+### Codex CLI (Codex-Plugin-Plattform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Das Codex-Plugin wird aus demselben `plugin/`-Verzeichnis ausgeliefert wie das Claude-Code-Plugin. Es registriert:
+
+- `@agentmemory/mcp` als MCP-Server (proxyt alle 51 Tools, wenn `AGENTMEMORY_URL` auf einen laufenden agentmemory-Server zeigt; fällt lokal auf 7 Tools zurück, wenn kein Server erreichbar ist)
+- 6 Lifecycle-Hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 Skills: `/recall`, `/remember`, `/session-history`, `/forget`
+
+Codex' Hook-Engine injiziert `CLAUDE_PLUGIN_ROOT` in Hook-Subprozesse (siehe [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), sodass dieselben Hook-Skripte ohne Duplikation auf beiden Hosts laufen. Die Events Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure gibt es nur in Claude Code und werden für Codex nicht registriert.
+
+#### Codex Desktop: Plugin-Hooks derzeit lautlos (Workaround vorhanden)
+
+`CodexHooks` und `PluginHooks` sind beide stabil und standardmäßig aktiviert in [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), aber aktuelle Codex-Desktop-Builds dispatchen die plugin-lokale `hooks.json` nicht ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). MCP-Tools funktionieren weiterhin; nur die Lifecycle-Beobachtungen fehlen.
+
+Solange der Fix upstream nicht gelandet ist, spiegeln Sie dieselben Hook-Befehle in die globale `~/.codex/hooks.json`:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+Das fügt einen idempotenten Block zu `~/.codex/hooks.json` hinzu, der absolute Pfade zu den mitgelieferten Skripten referenziert (keine `${CLAUDE_PLUGIN_ROOT}`-Expansion auf Benutzer-Scope nötig). Führen Sie denselben Befehl nach einem agentmemory-Upgrade erneut aus, um die Pfade zu aktualisieren. Eigene Einträge in derselben Datei bleiben erhalten; nur frühere agentmemory-Einträge werden ersetzt.
+
+<details>
+<summary><b>OpenClaw (diesen Prompt einfügen)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+Vollständiger Leitfaden: [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (diesen Prompt einfügen)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Vollständiger Leitfaden: [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### Andere Agenten
+
+Starten Sie den Memory-Server: `npx @agentmemory/agentmemory`
+
+Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, der das `mcpServers`-Format verwendet (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**Fügen Sie diesen Eintrag in das bestehende `mcpServers`-Objekt** in der Konfigurationsdatei des Hosts ein — ersetzen Sie nicht die Datei. Wenn die Datei bereits andere Server enthält, fügen Sie `agentmemory` als zusätzlichen Schlüssel innerhalb von `mcpServers` daneben ein. Fehlt `mcpServers` ganz, fügen Sie den Block innerhalb von `{ "mcpServers": { ... } }` ein. Die `${VAR}`-Platzhalter übernehmen `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` aus der Shell beim Start des MCP-Servers — nicht gesetzte Variablen werden als leere Strings übergeben, und das Shim fällt auf `http://localhost:3111` zurück. Ein einziger verdrahteter Eintrag deckt sowohl lokale als auch entfernte (k8s / reverse-proxied) Deployments ab.
+
+| Agent | Konfigurationsdatei | Hinweise |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | In `mcpServers` einfügen. Ein-Klick-Deeplink auch auf der Website. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | In `mcpServers` einfügen. Claude Desktop nach dem Editieren neu starten. |
+| **Cline / Roo Code / Kilo Code** | Cline-MCP-Einstellungen (Settings UI → MCP Servers → Edit) | Gleicher `mcpServers`-Block. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Gleicher `mcpServers`-Block. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (automatisches Mergen). |
+| **OpenClaw** | OpenClaw-MCP-Konfig | Gleicher `mcpServers`-Block oder das tiefer integrierte [Memory-Plugin](../integrations/openclaw/). |
+| **Codex CLI (nur MCP)** | `.codex/config.toml` | TOML-Form: `codex mcp add agentmemory -- npx -y @agentmemory/mcp` oder `[mcp_servers.agentmemory]` manuell hinzufügen. |
+| **Codex CLI (volles Plugin)** | Codex-Plugin-Marketplace | `codex plugin marketplace add rohitg00/agentmemory`, dann `codex plugin add agentmemory@agentmemory`. Registriert MCP + 6 Lifecycle-Hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 Skills. Auf Codex Desktop zusätzlich `agentmemory connect codex --with-hooks` ausführen, bis [openai/codex#16430](https://github.com/openai/codex/issues/16430) landet — Plugin-Hooks sind dort derzeit lautlos. |
+| **OpenCode (nur MCP)** | `opencode.json` | Anderes Format — `mcp`-Schlüssel auf oberster Ebene, Command als Array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (volles Plugin)** | `plugin/opencode/` | 22 Auto-Capture-Hooks für Session-Lifecycle, Messages, Tools, Fehler. Zwei Slash-Befehle (`/recall`, `/remember`). Kopieren Sie `plugin/opencode/` in Ihren OpenCode-Workspace und fügen Sie den Plugin-Eintrag zu `opencode.json` hinzu. Siehe [`plugin/opencode/README.md`](../plugin/opencode/README.md) für die vollständige Hook-Tabelle + Gap-Analyse. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | [`integrations/pi`](../integrations/pi/) kopieren und pi neu starten. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Verwenden Sie das tiefer integrierte [Memory-Provider-Plugin](../integrations/hermes/) mit `memory.provider: agentmemory`. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` schreibt den standardmäßigen `mcpServers`-Block. Die Hook-Payload ist feldkompatibel mit Claude Code, sodass die bestehenden 12 Hook-Skripte ohne Änderung funktionieren — verdrahten Sie sie über den Abschnitt `hooks` in derselben `settings.json`. |
+| **Antigravity** (ersetzt Gemini CLI) | `mcp_config.json` (im User-Verzeichnis von Antigravity) | `agentmemory connect antigravity` schreibt den standardmäßigen `mcpServers`-Block. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Nach dem Sunset von Gemini CLI am 2026-06-18 zu nutzen. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` schreibt die Konfig auf Benutzerebene. Workspace-Overrides liegen in `.kiro/settings/mcp.json` neben Ihrem Code. |
+| **Goose** | Goose-MCP-Einstellungen-UI | Gleicher `mcpServers`-Block. |
+| **Aider** | n/v | Sprechen Sie direkt mit der REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Jeder Agent (32+)** | n/v | `npx skillkit install agentmemory` erkennt den Host automatisch und merged. |
+
+**MCP-Clients in Sandboxen** (Flatpak / Snap / restriktive Container), die den `localhost` des Hosts nicht erreichen können: Setzen Sie zusätzlich `"AGENTMEMORY_FORCE_PROXY": "1"` im `env`-Block und lassen Sie `AGENTMEMORY_URL` auf eine Route zeigen, die die Sandbox tatsächlich erreichen kann (z. B. Ihre LAN-IP). Siehe [#234](https://github.com/rohitg00/agentmemory/issues/234) für den Diagnose-Walkthrough.
+
+### Programmatischer Zugriff (Python / Rust / Node)
+
+agentmemory registriert seine Kernoperationen als iii-Funktionen (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Jede Sprache mit einem iii-SDK kann sie direkt über `ws://localhost:49134` aufrufen — kein separater REST-Client pro Sprache nötig.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Vollständiges Beispiel: [`examples/python/`](../examples/python/) (Quickstart + Beobachtungs-/Recall-Fluss). REST auf `:3111` bleibt verfügbar für Hosts ohne iii-Runtime.
+
+### Aus den Quellen
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Das startet agentmemory mit einer lokalen `iii-engine`, falls `iii` bereits installiert ist, oder fällt auf Docker Compose zurück, falls Docker vorhanden ist. REST, Streams und der Viewer binden sich standardmäßig an `127.0.0.1`.
+
+`iii-engine` manuell installieren. **agentmemory pinnt `iii-engine` derzeit auf `v0.11.2`** — `v0.11.6` führt ein neues Modell ein, alles per `iii worker add` zu sandboxen, für das agentmemory noch nicht refaktoriert wurde. Der Pin wird aufgehoben, sobald die Refaktorierung erfolgt ist. Überschreiben Sie mit `AGENTMEMORY_III_VERSION=<version>`, wenn Sie manuell auf das Sandbox-Modell migriert sind.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `aarch64-apple-darwin` durch `x86_64-apple-darwin` ersetzen
+- **Linux x64:** durch `x86_64-unknown-linux-gnu` ersetzen
+- **Linux arm64:** durch `aarch64-unknown-linux-gnu` ersetzen
+- **Windows:** `iii-x86_64-pc-windows-msvc.zip` von [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2) herunterladen, `iii.exe` extrahieren, zum PATH hinzufügen
+
+Oder Docker verwenden (die mitgelieferte `docker-compose.yml` zieht `iiidev/iii:0.11.2`). Vollständige Doku: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory läuft auf Windows 10/11, aber das Node.js-Paket allein genügt nicht — Sie brauchen außerdem das `iii-engine`-Runtime (ein separates natives Binary) als Hintergrundprozess. Der offizielle Upstream-Installer ist ein `sh`-Skript, und es gibt heute weder einen PowerShell-Installer noch ein scoop/winget-Paket, daher haben Windows-Nutzer zwei Wege:
+
+**Option A — Vorgebautes Windows-Binary (empfohlen):**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe somewhere on PATH, or place it at:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory checks that location automatically)
+# 4. Verify:
+iii --version
+# Should print: 0.11.2
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**Option B — Docker Desktop:**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**Option C — Nur Standalone-MCP (ohne Engine):** Wenn Sie nur die MCP-Tools für Ihren Agenten brauchen und weder REST API, Viewer noch Cron-Jobs, überspringen Sie die Engine ganz:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnose unter Windows:** Wenn `npx @agentmemory/agentmemory` fehlschlägt, mit `--verbose` neu starten, um das tatsächliche Engine-stderr zu sehen. Häufige Fehlerbilder:
+
+| Symptom | Lösung |
+|---|---|
+| `iii-engine process started`, dann `did not become ready within 15s` | Engine ist beim Start abgestürzt — mit `--verbose` neu starten, stderr prüfen |
+| `Could not start iii-engine` | Weder `iii.exe` noch Docker installiert. Siehe Option A oder B oben |
+| Port-Konflikt | `netstat -ano \| findstr :3111`, um zu sehen, was gebunden ist, dann beenden oder `--port <N>` verwenden |
+| Docker-Fallback wird übersprungen, obwohl Docker installiert ist | Stellen Sie sicher, dass Docker Desktop tatsächlich läuft (Taskleisten-Icon) |
+
+> Hinweis: Es gibt kein `cargo install iii-engine` — `iii` ist nicht auf crates.io veröffentlicht. Die einzigen unterstützten Installationsmethoden sind das vorgebaute Binary oben, das Upstream-`sh`-Installationsskript (nur macOS/Linux) und das Docker-Image.
+
+---
+
+<h2 id="deploy">Deployment</h2>
+
+Ein-Klick-Vorlagen für gemanagte Hosts. Jede liefert ein autonomes
+Dockerfile aus, das `@agentmemory/agentmemory` aus npm bezieht und das
+iii-engine-Binary aus dem offiziellen `iiidev/iii`-Image vom Docker Hub
+kopiert — keine vorgebaute agentmemory-Image-Erforderlichkeit. Persistenter
+Speicher wird unter `/data` gemountet; der Entrypoint beim ersten Boot
+überschreibt die per npm gelieferte iii-Konfig (die `127.0.0.1` bindet)
+mit einer deploy-tauglichen Variante, die `0.0.0.0` bindet und absolute
+`/data`-Pfade verwendet, generiert das HMAC-Secret und senkt die
+Privilegien von `root` auf `node` via `gosu`, bevor er die agentmemory-CLI
+exec't.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Der Ein-Klick-Deploy-Button von Render erfordert eine `render.yaml` im Repository-Root, das wir bewusst sauber halten. Verwenden Sie den Render-Blueprint-Fluss, dokumentiert in [`deploy/render/`](./deploy/render/README.md), um manuell auf das im Repo liegende Blueprint zu zeigen.
+
+Vollständige Setup-Details (HMAC-Capture, Viewer-SSH-Tunnel, Rotation, Backup, Kostenuntergrenzen) finden Sie in [`deploy/`](./deploy/README.md):
+
+- [`deploy/fly`](./deploy/fly/README.md) — Einzelmaschine mit
+  `auto_stop_machines = "stop"`; am günstigsten im Leerlauf.
+- [`deploy/railway`](./deploy/railway/README.md) — Hobby-Plan mit Pauschalpreis,
+  Volume im Dashboard.
+- [`deploy/render`](./deploy/render/README.md) — Blueprint-Fluss,
+  automatische Disk-Snapshots auf bezahlten Plänen.
+- [`deploy/coolify`](./deploy/coolify/README.md) — self-hosted auf Ihrem
+  eigenen VPS via [Coolify](https://coolify.io/self-hosted); derselbe
+  Docker-Compose-Stack, Sie besitzen Host und Daten.
+
+Nur Port `3111` wird veröffentlicht. Der Viewer auf `3113` bleibt im
+Container an Loopback gebunden — jedes Template-README dokumentiert
+das SSH-Tunnel-Muster, um ihn zu erreichen.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Warum agentmemory" height="32" /></picture></h2>
+
+Jeder Coding-Agent vergisst alles, wenn die Session endet. Sie verschwenden die ersten 5 Minuten jeder Session damit, Ihren Stack erneut zu erklären. agentmemory läuft im Hintergrund und beseitigt das vollständig.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### vs. eingebautes Agent-Memory
+
+Jeder KI-Coding-Agent kommt mit eingebautem Memory — Claude Code hat `MEMORY.md`, Cursor hat Notepads, Cline hat Memory Bank. Das funktioniert wie Klebezettel. agentmemory ist die durchsuchbare Datenbank hinter den Klebezetteln.
+
+| | Eingebaut (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skalierung | 200-Zeilen-Limit | Unbegrenzt |
+| Suche | Lädt alles in den Kontext | BM25 + Vector + Graph (nur Top-K) |
+| Token-Kosten | 22K+ bei 240 Beobachtungen | ~1.900 Tokens (92 % weniger) |
+| Agentenübergreifend | Dateien pro Agent | MCP + REST (jeder Agent) |
+| Koordination | Keine | Leases, Signale, Actions, Routinen |
+| Observability | Dateien manuell lesen | Echtzeit-Viewer auf :3113 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="Funktionsweise" height="32" /></picture></h2>
+
+### Memory-Pipeline
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4-stufige Memory-Konsolidierung
+
+Inspiriert davon, wie menschliche Gehirne Erinnerungen verarbeiten — nicht unähnlich der Schlafkonsolidierung.
+
+| Stufe | Was | Analogie |
+|------|------|---------|
+| **Working** | Rohbeobachtungen aus Tool-Nutzung | Kurzzeitgedächtnis |
+| **Episodic** | Komprimierte Session-Zusammenfassungen | „Was passiert ist" |
+| **Semantic** | Extrahierte Fakten und Muster | „Was ich weiß" |
+| **Procedural** | Workflows und Entscheidungsmuster | „Wie es geht" |
+
+Erinnerungen klingen mit der Zeit ab (Ebbinghaus-Kurve). Häufig abgerufene Erinnerungen werden verstärkt. Veraltete Erinnerungen werden automatisch evakuiert. Widersprüche werden erkannt und aufgelöst.
+
+### Was erfasst wird
+
+| Hook | Erfasst |
+|------|----------|
+| `SessionStart` | Projektpfad, Session-ID |
+| `UserPromptSubmit` | Benutzer-Prompts (Privacy-gefiltert) |
+| `PreToolUse` | Datei-Zugriffsmuster + angereicherter Kontext |
+| `PostToolUse` | Tool-Name, Eingabe, Ausgabe |
+| `PostToolUseFailure` | Fehlerkontext |
+| `PreCompact` | Re-injiziert Memory vor der Kompaktierung |
+| `SubagentStart/Stop` | Sub-Agent-Lifecycle |
+| `Stop` | Zusammenfassung am Session-Ende |
+| `SessionEnd` | Session-Abschluss-Marker |
+
+### Kernfähigkeiten
+
+| Fähigkeit | Beschreibung |
+|---|---|
+| **Automatische Erfassung** | Jede Tool-Nutzung via Hooks aufgezeichnet — null manueller Aufwand |
+| **Semantische Suche** | BM25 + Vector + Knowledge Graph mit RRF-Fusion |
+| **Memory-Evolution** | Versionierung, Supersession, Beziehungsgraphen |
+| **Auto-Vergessen** | TTL-Ablauf, Widerspruchserkennung, Wichtigkeits-Eviction |
+| **Privacy first** | API-Keys, Secrets, `<private>`-Tags vor Speicherung entfernt |
+| **Selbstheilung** | Circuit Breaker, Provider-Fallback-Kette, Health-Monitoring |
+| **Claude-Bridge** | Bidirektionale Synchronisierung mit MEMORY.md |
+| **Knowledge Graph** | Entitäten-Extraktion + BFS-Traversal |
+| **Team-Memory** | Namensraum-getrennt geteilt + privat über Teammitglieder hinweg |
+| **Zitations-Provenienz** | Jedes Memory bis zu Ursprungsbeobachtungen zurückverfolgen |
+| **Git-Snapshots** | Memory-Stand versionieren, zurückrollen und diffen |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Suche" height="32" /></picture></h2>
+
+Triple-Stream-Retrieval, das drei Signale kombiniert:
+
+| Stream | Was es tut | Wann |
+|---|---|---|
+| **BM25** | Gestemmter Keyword-Abgleich mit Synonymerweiterung | Immer aktiv |
+| **Vector** | Cosinus-Ähnlichkeit über dichte Embeddings | Embedding-Provider konfiguriert |
+| **Graph** | Knowledge-Graph-Traversal via Entitäten-Abgleich | Entitäten in der Anfrage erkannt |
+
+Verschmolzen mit Reciprocal Rank Fusion (RRF, k=60) und session-diversifiziert (max. 3 Ergebnisse pro Session).
+
+BM25 tokenisiert Griechisch, Kyrillisch, Hebräisch, Arabisch und akzentuiertes Latein standardmäßig. Für Erinnerungen in Chinesisch / Japanisch / Koreanisch installieren Sie die optionalen Segmentierer (`npm install @node-rs/jieba tiny-segmenter`), um CJK-Folgen in Worttokens aufzuteilen; ohne sie fällt agentmemory weich auf eine Tokenisierung als gesamte Folge zurück und gibt einmalig einen Hinweis auf stderr aus.
+
+### Embedding-Provider
+
+agentmemory erkennt Ihren Provider automatisch. Für die besten Ergebnisse installieren Sie lokale Embeddings (kostenlos):
+
+```bash
+npm install @xenova/transformers
+```
+
+| Provider | Modell | Kosten | Hinweise |
+|---|---|---|---|
+| **Lokal (empfohlen)** | `all-MiniLM-L6-v2` | Kostenlos | Offline, +8 pp Recall gegenüber BM25 allein |
+| Gemini | `gemini-embedding-001` | Free Tier | 100+ Sprachen, 768/1536/3072 Dims (MRL), 2048-Token-Eingabe. Ersetzt `text-embedding-004` ([deprecated, Abschaltung 14. Jan. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | 0,02 $/1M | Höchste Qualität |
+| Voyage AI | `voyage-code-3` | Kostenpflichtig | Auf Code optimiert |
+| Cohere | `embed-english-v3.0` | Testzugang | Allzweck |
+| OpenRouter | Beliebiges Modell | Variabel | Multi-Modell-Proxy |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP-Server" height="32" /></picture></h2>
+
+53 Tools, 6 Resources, 3 Prompts und 4 Skills — das umfassendste MCP-Memory-Toolkit für jeden Agenten.
+
+> **MCP-Shim vs. voller Server:** Das veröffentlichte `@agentmemory/mcp`-Paket ist ein dünnes Shim. Es legt die volle 51-Tool-Oberfläche **nur dann** offen, wenn es per `AGENTMEMORY_URL` einen laufenden agentmemory-Server erreichen kann (Proxy-Modus). Ohne erreichbaren Server fällt das Shim auf einen lokalen 7-Tool-Satz zurück (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Die Umgebungsvariable `AGENTMEMORY_TOOLS=core|all` ist ein *serverseitiger* Schalter — sie im `env`-Block des Shims zu setzen hat keinen Effekt. Wenn Sie in Cursor / OpenCode / Gemini CLI nur 7 Tools sehen, starten Sie `npx @agentmemory/agentmemory` (oder den Docker-Stack) und setzen Sie `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 51 Tools
+
+<details>
+<summary>Core-Tools (immer verfügbar)</summary>
+
+| Tool | Beschreibung |
+|------|-------------|
+| `memory_recall` | Vergangene Beobachtungen durchsuchen |
+| `memory_compress_file` | Markdown-Dateien unter Erhalt der Struktur komprimieren |
+| `memory_save` | Erkenntnis, Entscheidung oder Muster speichern |
+| `memory_patterns` | Wiederkehrende Muster erkennen |
+| `memory_smart_search` | Hybride semantische + Keyword-Suche |
+| `memory_file_history` | Vergangene Beobachtungen zu bestimmten Dateien |
+| `memory_sessions` | Letzte Sessions auflisten |
+| `memory_timeline` | Chronologische Beobachtungen |
+| `memory_profile` | Projektprofil (Konzepte, Dateien, Muster) |
+| `memory_export` | Alle Memory-Daten exportieren |
+| `memory_relations` | Beziehungsgraph abfragen |
+
+</details>
+
+<details>
+<summary>Erweiterte Tools (insgesamt 51 — AGENTMEMORY_TOOLS=all setzen)</summary>
+
+| Tool | Beschreibung |
+|------|-------------|
+| `memory_patterns` | Wiederkehrende Muster erkennen |
+| `memory_timeline` | Chronologische Beobachtungen |
+| `memory_relations` | Beziehungsgraph abfragen |
+| `memory_graph_query` | Knowledge-Graph-Traversal |
+| `memory_consolidate` | 4-stufige Konsolidierung ausführen |
+| `memory_claude_bridge_sync` | Mit MEMORY.md synchronisieren |
+| `memory_team_share` | Mit Teammitgliedern teilen |
+| `memory_team_feed` | Kürzlich geteilte Einträge |
+| `memory_audit` | Audit-Trail der Operationen |
+| `memory_governance_delete` | Mit Audit-Trail löschen |
+| `memory_snapshot_create` | Git-versionierter Snapshot |
+| `memory_action_create` | Arbeitspakete mit Abhängigkeiten anlegen |
+| `memory_action_update` | Action-Status aktualisieren |
+| `memory_frontier` | Entblockte Actions nach Priorität sortiert |
+| `memory_next` | Einzelne wichtigste nächste Action |
+| `memory_lease` | Exklusive Action-Leases (Multi-Agent) |
+| `memory_routine_run` | Workflow-Routinen instanziieren |
+| `memory_signal_send` | Inter-Agent-Messaging |
+| `memory_signal_read` | Nachrichten mit Empfangsquittungen lesen |
+| `memory_checkpoint` | Externe Bedingungs-Gates |
+| `memory_mesh_sync` | P2P-Sync zwischen Instanzen |
+| `memory_sentinel_create` | Ereignisgesteuerte Watcher |
+| `memory_sentinel_trigger` | Sentinels extern auslösen |
+| `memory_sketch_create` | Ephemere Action-Graphen |
+| `memory_sketch_promote` | In permanent überführen |
+| `memory_crystallize` | Action-Ketten kompaktieren |
+| `memory_diagnose` | Health-Checks |
+| `memory_heal` | Festsitzenden Zustand auto-fixen |
+| `memory_facet_tag` | Dimension:Wert-Tags |
+| `memory_facet_query` | Nach Facetten-Tags abfragen |
+| `memory_verify` | Provenienz nachverfolgen |
+
+</details>
+
+### 6 Resources · 3 Prompts · 4 Skills
+
+| Typ | Name | Beschreibung |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, Session-Anzahl, Memory-Anzahl |
+| Resource | `agentmemory://project/{name}/profile` | Projektspezifische Intelligenz |
+| Resource | `agentmemory://memories/latest` | Die 10 neuesten aktiven Erinnerungen |
+| Resource | `agentmemory://graph/stats` | Knowledge-Graph-Statistiken |
+| Prompt | `recall_context` | Suche + Rückgabe von Kontext-Nachrichten |
+| Prompt | `session_handoff` | Handoff-Daten zwischen Agenten |
+| Prompt | `detect_patterns` | Wiederkehrende Muster analysieren |
+| Skill | `/recall` | Memory durchsuchen |
+| Skill | `/remember` | Im Langzeit-Memory speichern |
+| Skill | `/session-history` | Zusammenfassungen letzter Sessions |
+| Skill | `/forget` | Beobachtungen / Sessions löschen |
+
+### Standalone MCP
+
+Ohne den vollen Server laufen lassen — für jeden MCP-Client. Eines der folgenden geht:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (always available)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+Oder zur MCP-Konfig Ihres Agenten hinzufügen:
+
+Die meisten Agenten (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+Fügen Sie den `agentmemory`-Eintrag in das vorhandene `mcpServers`-Objekt Ihres Hosts ein, statt die Datei zu ersetzen. Für Sandbox-Clients, die den `localhost` des Hosts nicht erreichen können, fügen Sie `"AGENTMEMORY_FORCE_PROXY": "1"` zum env-Block hinzu und lassen `AGENTMEMORY_URL` auf eine Route zeigen, die die Sandbox erreicht.
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Plugin-Datei aus dem Repo kopieren:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Echtzeit-Viewer" height="32" /></picture></h2>
+
+Startet automatisch auf Port `3113`. Live-Beobachtungs-Stream, Session-Explorer, Memory-Browser, Knowledge-Graph-Visualisierung und Health-Dashboard.
+
+```bash
+open http://localhost:3113
+```
+
+Der Viewer-Server bindet sich standardmäßig an `127.0.0.1`. Der per REST ausgelieferte `/agentmemory/viewer`-Endpunkt folgt den üblichen `AGENTMEMORY_SECRET`-Bearer-Token-Regeln. CSP-Header verwenden eine Skript-Nonce pro Response und deaktivieren Inline-Handler-Attribute (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+Der Viewer auf `:3113` zeigt, was Ihr Agent **gespeichert hat**. Die [iii console](https://iii.dev/docs/console) zeigt, was Ihr Agent **getan hat** — jede Memory-Operation als OpenTelemetry-Trace, jeden KV-Eintrag editierbar, jede Funktion aufrufbar, jeden Stream abgreifbar. Zwei Fenster auf dasselbe Memory: eines produktnah, eines engine-nah.
+
+Sehen Sie, wie ein `memory_smart_search` feuert, und beobachten Sie BM25-Scan → Embedding-Lookup → RRF-Fusion → Reranker als Wasserfall. Editieren Sie einen festsitzenden Konsolidierungs-Timer im KV-Browser. Spielen Sie einen `PostToolUse`-Hook mit angepasster Payload erneut ab. Pinnen Sie den WebSocket-Stream an und sehen Sie Beobachtungen live eintrudeln.
+
+agentmemory liefert das umsonst, weil jede Funktion, jeder Trigger, jeder State-Scope und jeder Stream eine iii-Primitive ist — nichts Eigenes, nichts zu instrumentieren.
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers-Seite — verbundene Worker, einschließlich agentmemory-Instanzen mit Live-Funktionszahlen und Runtime-Metadaten" width="720" />
+  <br/>
+  <em>Workers-Seite: jeder verbundene Worker — einschließlich agentmemory selbst — mit PID, Funktionsanzahl, Runtime und last-seen.</em>
+</p>
+
+**Bereits installiert.** Die Console wird mit `iii` ausgeliefert — kein separater Installer.
+
+**Neben agentmemory starten:**
+
+```bash
+# agentmemory viewer holds port 3113, so run the console on 3114.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
+```
+
+Dann `http://localhost:3114` öffnen. `--enable-flow` ergänzen für die experimentelle Architektur-Graph-Seite.
+
+Engine-Endpunkte nur überschreiben, wenn Sie sie verschoben haben:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**Was Sie aus der Console heraus tun können:**
+
+| Seite | Verwenden Sie sie für |
+|------|-----------|
+| **Workers** | Jeden verbundenen Worker und seine Live-Metriken sehen — einschließlich des agentmemory-Workers selbst. |
+| **Functions** | Jede Funktion von agentmemory direkt mit einer JSON-Payload aufrufen — handlich zum Testen von `memory.recall`, `memory.consolidate`, `graph.query` ohne Client zu verdrahten. |
+| **Triggers** | HTTP-, Cron-, Event- und State-Trigger erneut abspielen — den Konsolidierungs-Cron manuell auslösen, eine HTTP-Route wiederholen, einen State-Change emittieren. |
+| **States** | KV-Browser mit vollem CRUD — Sessions, Memory-Slots, Lifecycle-Timer, Embedding-Index — Werte direkt bearbeiten. |
+| **Streams** | Live-WebSocket-Monitor für Memory-Schreibvorgänge, Hook-Events und Beobachtungsupdates, wie sie durch iii-Streams fließen. |
+| **Queues** | Durable Queue-Topics + Dead-Letter-Verwaltung. Fehlgeschlagene Embedding-/Kompressions-Jobs wiederholen oder verwerfen. |
+| **Traces** | OpenTelemetry-Wasserfall- / Flame- / Service-Breakdown-Ansichten. Nach `trace_id` filtern, um exakt zu sehen, welche Funktionen, DB-Calls und Embedding-Anfragen eine einzelne `memory.search` ausgelöst hat. |
+| **Logs** | Strukturierte OTEL-Logs, gefiltert und korreliert mit Trace-/Span-IDs. |
+| **Config** | Runtime-Konfiguration — sehen Sie genau, mit welchen Workern, Providern und Ports Ihre Engine läuft. |
+| **Flow** | (Optional, `--enable-flow`) Interaktiver Architekturgraph jedes Workers, Triggers und Streams. |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="iii console Trace-Wasserfall-Ansicht mit Span-Dauer" width="720" />
+  <br/>
+  <em>Traces: Wasserfall / Flame / Service-Breakdown für jede Memory-Operation.</em>
+</p>
+
+**Traces sind bereits aktiv:**
+
+`iii-config.yaml` wird mit aktiviertem `iii-observability`-Worker ausgeliefert (`exporter: memory`, `sampling_ratio: 1.0`, Metriken + Logs). Keine zusätzliche Konfig nötig — in dem Moment, in dem agentmemory startet, emittiert jede Memory-Operation einen Trace-Span und ein strukturiertes Log, das die Console lesen kann.
+
+Wenn Sie stattdessen zu Jaeger/Honeycomb/Grafana Tempo exportieren wollen, ändern Sie `exporter: memory` zu `exporter: otlp` und setzen den Collector-Endpunkt gemäß der iii-Observability-Doku.
+
+> **Achtung:** Auf der Console selbst wird keine Auth erzwungen — lassen Sie sie an `127.0.0.1` gebunden (Standard) und stellen Sie sie niemals öffentlich bereit.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory ist **bereits eine laufende [iii](https://iii.dev)-Instanz**. Funktionen, Trigger, KV-State, Streams, OTEL-Traces — alles sind iii-Primitiven. Sie haben weder Postgres noch Redis, Express, pm2 oder Prometheus installiert, weil iii sie ersetzt.
+
+Das bedeutet, ein weiterer Befehl erweitert agentmemory um eine komplett neue Fähigkeit.
+
+### agentmemory mit einem Befehl erweitern
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+Jedes `iii worker add` registriert neue Funktionen und Trigger im selben Engine, auf dem agentmemory bereits läuft. Viewer und Console übernehmen sie sofort — kein Reload, keine neue Integration, kein neuer Container.
+
+| `iii worker add` | Was Sie zusätzlich zu agentmemory erhalten |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-Instanz-Memory: jedes `remember` fächert auf, jedes `search` liest die Vereinigung |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Geplanter Lifecycle — nächtliche Konsolidierung, wöchentliche Snapshots, Decay nach fester Uhr |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable Retries: fehlgeschlagene Embedding-/Kompressions-Jobs überleben den Neustart, keine verlorenen Beobachtungen |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL-Traces, Metriken, Logs auf jeder Funktion — in `iii-config.yaml` ab dem ersten Tag verdrahtet |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code, der aus `memory_recall` kommt, läuft in einer wegwerf-VM, nicht in Ihrer Shell |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-gestützter State-Adapter, wenn Sie die In-Memory-KV-Voreinstellungen überwachsen |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Zusätzliche MCP-Server neben dem von agentmemory aufstellen, die sich denselben Engine teilen |
+
+Volle Registry: [workers.iii.dev](https://workers.iii.dev). Jeder Worker dort komponiert sich über dieselben Primitiven wie agentmemory — und das agentmemory, das Sie bereits haben, ist einer davon.
+
+### Was iii ersetzt
+
+| Traditioneller Stack | agentmemory verwendet |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + In-Memory-Vector-Index |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii-Engine-Worker-Supervision |
+| Prometheus / Grafana | iii OTEL + Health-Monitor |
+| Eigene Plugin-Systeme | `iii worker add <name>` |
+
+**118 Quelldateien · ~21.800 LOC · 950+ Tests · 123 Funktionen · 34 KV-Scopes** — alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfiguration" height="32" /></picture></h2>
+
+### LLM-Provider
+
+agentmemory erkennt aus Ihrer Umgebung automatisch. Standardmäßig werden keine LLM-Aufrufe ausgeführt, solange Sie nicht einen Provider konfigurieren oder dem Claude-Abonnement-Fallback ausdrücklich zustimmen.
+
+| Provider | Konfig | Hinweise |
+|----------|--------|-------|
+| **No-op (Standard)** | Keine Konfig nötig | LLM-gestütztes Compress/Summarize ist DEAKTIVIERT. Synthetische BM25-Kompression + Recall funktionieren weiter. Siehe `AGENTMEMORY_ALLOW_AGENT_SDK` unten, falls Sie früher auf den Claude-Abonnement-Fallback gesetzt haben. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Abrechnung pro Token |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
+| Gemini | `GEMINI_API_KEY` | Aktiviert zusätzlich Embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Beliebiges Modell |
+| Claude-Abonnement-Fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Nur als Opt-in. Startet `@anthropic-ai/claude-agent-sdk`-Sessions — verursachte früher unbegrenzte Stop-Hook-Rekursion (Folge von #149), daher nicht mehr Standard. |
+
+### Kostenbewusste Modellwahl
+
+Hintergrund-Kompression läuft bei jeder Beobachtung, daher beeinflusst die Modellwahl die monatlichen Kosten spürbar. Erfasste Lastdaten: 635 Requests / 888K Tokens / 35 Stunden aktive Nutzung, gegen drei OpenRouter-Modelle zu den Preisen vom 2026-05-23.
+
+| Stufe | Modell | Eingabe / 1M | Ausgabe / 1M | Kosten für die erfassten 35 h | Hinweise |
+|------|-------|------------|-------------|---------------------------|-------|
+| Empfohlen | `deepseek/deepseek-v4-pro` | 0,435 $ | 0,87 $ | ~0,46 $ | Solide Kompressions-/Summarize-Qualität zu ~10× geringeren Kosten als Sonnet. |
+| Empfohlen | `deepseek/deepseek-chat` | 0,27 $ | 1,10 $ | ~0,40 $ | Älter, aber für reine Kompressions-Workloads weiterhin in Ordnung. |
+| Empfohlen | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Starkes Code-Reasoning, wenn Ihre Sessions stark codelastig sind. |
+| Premium | `anthropic/claude-sonnet-4.6` | 3,00 $ | 15,00 $ | ~5,02 $ | Hohe Qualität, aber teuer für dauerhafte Hintergrundarbeit. |
+| Premium | `openai/gpt-4o` | 2,50 $ | 10,00 $ | ~4,20 $ | Ähnliche Stufe wie Sonnet. |
+| Vermeiden | `anthropic/claude-opus-4.6` | 15,00 $ | 75,00 $ | ~25+ $ | Reasoning-Klasse-Modell; massive Überausgabe für Kompression. |
+
+agentmemory gibt eine Runtime-Warnung aus, wenn `OPENROUTER_MODEL` auf ein Premium-Tier-Muster passt. Setzen Sie `AGENTMEMORY_SUPPRESS_COST_WARNING=1`, um sie zum Schweigen zu bringen, sobald Sie eine bewusste Wahl getroffen haben.
+
+Qualitäts-Kosten-Abwägung für Memory-Arbeit: Kompression ist eine Summarize-Aufgabe mit eher lockerer Qualitätsanforderung (der Agent liest die Zusammenfassung erneut, nicht der Benutzer). DeepSeek-V4-Pro / Qwen3-Coder landen bei dieser Aufgabe innerhalb von Rundungsfehlern an Sonnet, bei ~10× weniger Kosten. Heben Sie Premium-Modelle für Anfragen auf, die Sie direkt lesen.
+
+Quellen: [OpenRouter-Preise für Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek-Preis-Hinweise](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Multi-Agent-Memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+In Multi-Agent-Setups, in denen sich mehrere Rollen einen agentmemory-Server teilen (architect / developer / reviewer / researcher / support-agent), markiert `AGENT_ID` jede Schreibaktion mit der Rolle, die sie ausgelöst hat. `AGENTMEMORY_AGENT_SCOPE` steuert, ob der Recall nach diesem Tag filtert.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+Zwei Modi:
+
+| Modus | Schreibvorgänge markieren | Recall filtern | Wann verwenden |
+|------|------------|---------------|-------------|
+| `shared` (Standard) | ja | nein | Agentenübergreifender Kontext mit Audit-Trail. Architect sieht, was Developer notiert hat, aber jede Zeile vermerkt, wer es gesagt hat. |
+| `isolated` | ja | ja | Strikte Trennung. Architect sieht niemals Beobachtungen / Erinnerungen / Sessions von Developer. |
+
+Was getaggt wird, wenn `AGENT_ID` gesetzt ist: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Die Rolle fließt von `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Was im Isolated-Modus gefiltert wird: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Jeder Endpunkt akzeptiert `?agentId=<role>` als Per-Request-Override und `?agentId=*`, um sich komplett aus dem env-Scope auszuklinken. `/memories` akzeptiert zudem `?includeOrphans=true`, um Pre-AGENT_ID-Erinnerungen, deren `agentId` undefiniert ist, sichtbar zu machen.
+
+Per-Call-Override auf SDK-/REST-Ebene: jeder mutierende Endpunkt (`/session/start`, `/remember`) akzeptiert ein `agentId`-Feld im Request-Body, das die env-Variable überschreibt. Nützlich für Runtimes, die viele Rollen durch einen einzelnen Serverprozess routen.
+
+Wenn `AGENT_ID` nicht gesetzt ist, bleibt Memory unscoped (Legacy-Verhalten, keine Tags, keine Filter).
+
+### Ports
+
+agentmemory + iii-engine binden standardmäßig vier Ports. Wenn ein Neustart mit `port in use` fehlschlägt, sagt Ihnen diese Tabelle, nach welchem Prozess Sie suchen müssen.
+
+| Port | Prozess | Zweck | Env-Override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Interner Streams-Worker (von agentmemory + Viewer verwendet) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Echtzeit-Viewer (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — Worker registrieren sich hier, OTel-Telemetrie fließt darüber | `III_ENGINE_URL` (volle URL, Standard `ws://localhost:49134`) |
+
+Aufräumen veralteter Prozesse, wenn Ports nach einem abgestürzten Lauf gebunden bleiben:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` räumt sowohl den Worker als auch das Engine-Pidfile bei einem geordneten Shutdown sauber auf (#640, #474). Das manuelle Cleanup oben ist nur für den Post-Crash-Fall nötig, in dem kein Pidfile zurückbleibt.
+
+### Konfigurationsdatei
+
+Legen Sie die agentmemory-Runtime-Konfiguration in `~/.agentmemory/.env` ab, statt Variablen in jeder Shell zu exportieren. Wenn der Viewer einen Setup-Hinweis wie `export ANTHROPIC_API_KEY=...` zeigt, kopieren Sie ihn als `ANTHROPIC_API_KEY=...` ohne `export`-Präfix in diese Datei und starten Sie agentmemory neu.
+
+Prozess-Umgebungsvariablen funktionieren weiterhin und haben Vorrang vor Werten in der Datei.
+
+Unter Windows liegt dieselbe Datei unter `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Um mit einem Claude Code Pro/Max-Abonnement statt eines API-Schlüssels zu testen, stimmen Sie explizit zu:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Aktivieren Sie Graph- oder Konsolidierungs-Features in derselben Datei, falls gewünscht:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### Umgebungsvariablen
+
+`~/.agentmemory/.env` anlegen:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+124 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer <secret>`, wenn `AGENTMEMORY_SECRET` gesetzt ist, und Mesh-Sync-Endpunkte erfordern `AGENTMEMORY_SECRET` auf beiden Peers.
+
+<details>
+<summary>Wichtige Endpunkte</summary>
+
+| Methode | Pfad | Beschreibung |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health-Check (immer öffentlich) |
+| `POST` | `/agentmemory/session/start` | Session starten + Kontext holen |
+| `POST` | `/agentmemory/session/end` | Session beenden |
+| `POST` | `/agentmemory/observe` | Beobachtung erfassen |
+| `POST` | `/agentmemory/smart-search` | Hybride Suche |
+| `POST` | `/agentmemory/context` | Kontext erzeugen |
+| `POST` | `/agentmemory/remember` | In Langzeit-Memory speichern |
+| `POST` | `/agentmemory/forget` | Beobachtungen löschen |
+| `POST` | `/agentmemory/enrich` | Dateikontext + Erinnerungen + Bugs |
+| `GET` | `/agentmemory/profile` | Projektprofil |
+| `GET` | `/agentmemory/export` | Alle Daten exportieren |
+| `POST` | `/agentmemory/import` | Aus JSON importieren |
+| `POST` | `/agentmemory/graph/query` | Knowledge-Graph-Anfrage |
+| `POST` | `/agentmemory/team/share` | Mit Team teilen |
+| `GET` | `/agentmemory/audit` | Audit-Trail |
+
+Volle Endpunktliste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Entwicklung" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ tests
+npm run test:integration  # API tests (requires running services)
+```
+
+**Voraussetzungen:** Node.js >= 20, [iii-engine](https://iii.dev/docs) oder Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Lizenz" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.es-ES.md

@@ -0,0 +1,1370 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — Memoria persistente para agentes de codificación con IA" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    Tu agente de codificación lo recuerda todo. Se acabó volver a explicarlo.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Memoria persistente para Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode y cualquier cliente MCP.
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  Español |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Documento de diseño: 1200 stars / 172 forks en el gist" /></a>
+</p>
+
+<p align="center">
+  <em>El gist extiende el patrón LLM Wiki de Karpathy con puntuación de confianza, ciclo de vida, grafos de conocimiento y búsqueda híbrida: agentmemory es la implementación.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="Demostración de agentmemory" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">Instalación</a> &bull;
+  <a href="#quick-start">Inicio rápido</a> &bull;
+  <a href="#benchmarks">Benchmarks</a> &bull;
+  <a href="#vs-competitors">Comparativa</a> &bull;
+  <a href="#works-with-every-agent">Agentes</a> &bull;
+  <a href="#how-it-works">Cómo funciona</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">Visor</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">Configuración</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # start the memory server on :3111
+agentmemory demo                                 # seed sample sessions + prove recall
+agentmemory connect claude-code                  # wire your agent (also: codex, cursor, gemini-cli, ...)
+```
+
+O mediante `npx` (sin instalación):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+Aviso — npx cachea por versión. Si un simple `npx @agentmemory/agentmemory` sirve una versión antigua, fuerza la última con `npx -y @agentmemory/agentmemory@latest`, o limpia la caché una vez con `rm -rf ~/.npm/_npx` (macOS/Linux; en Windows borra `%LOCALAPPDATA%\npm-cache\_npx`). La primera ejecución vía npx desde la v0.9.16+ pregunta si deseas instalar globalmente, de modo que el comando `agentmemory` quede disponible en cualquier lugar.
+
+Todas las opciones en [Inicio rápido](#quick-start) más abajo. Conexión específica por agente en [Funciona con cualquier agente](#works-with-every-agent).
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funciona con cualquier agente" height="32" /></picture></h2>
+
+agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Todos los agentes comparten el mismo servidor de memoria.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>native plugin + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>native plugin + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>native Memory trait backend</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>Funciona con <strong>cualquier</strong> agente que hable MCP o HTTP. Un único servidor, memorias compartidas entre todos ellos.</sub>
+</p>
+
+---
+
+Vuelves a explicar la misma arquitectura cada sesión. Vuelves a descubrir los mismos bugs. Vuelves a enseñar las mismas preferencias. La memoria integrada (CLAUDE.md, .cursorrules) se topa con un techo de 200 líneas y se queda obsoleta. agentmemory soluciona esto. Captura silenciosamente lo que hace tu agente, lo comprime en una memoria buscable e inyecta el contexto correcto al inicio de la siguiente sesión. Un único comando. Funciona en todos los agentes.
+
+**Qué cambia:** En la sesión 1 configuras autenticación JWT. En la sesión 2 pides rate limiting. El agente ya sabe que tu autenticación usa el middleware jose en `src/middleware/auth.ts`, que tus pruebas cubren la validación de tokens y que elegiste jose en lugar de jsonwebtoken por compatibilidad con Edge. Sin volver a explicar. Sin copiar y pegar. El agente simplemente lo *sabe*.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **Novedad en v0.9.0** — Sitio de aterrizaje en [agent-memory.dev](https://agent-memory.dev), conector de sistema de ficheros (`@agentmemory/fs-watcher`), el MCP standalone ahora hace de proxy al servidor en ejecución, por lo que los hooks y el visor coinciden, política de auditoría codificada en cada ruta de borrado, y health deja de marcar `memory_critical` en procesos Node pequeños. Notas completas en [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18).
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Precisión de recuperación
+
+**coding-agent-life-v1** (corpus interno, reproducible en sandbox)
+
+| Adaptador | P@5 | R@5 | Tasa de aciertos top-5 | Latencia p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep baseline | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+Tasa de aciertos top-5 del 100%. Precisión **2,2×** mejor que la baseline grep con la misma entrada. Desglose completo por tipo: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 preguntas)
+
+| Sistema | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Ahorro de tokens
+
+| Enfoque | Tokens/año | Coste/año |
+|---|---|---|
+| Pegar todo el contexto | 19.5M+ | Imposible (excede la ventana) |
+| Resumido por LLM | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + embeddings locales | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> Modelo de embedding: `all-MiniLM-L6-v2` (local, gratuito, sin API key). Informes completos: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparativa con la competencia: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory frente a mem0, Letta, Khoj, claude-mem, Hippo.
+
+**Reproduce en local:** [`eval/README.md`](../eval/README.md) — un harness con adaptadores intercambiables para LongMemEval `_s` (500-Q públicas) y `coding-agent-life-v1` (corpus interno de 15 sesiones). Los adaptadores grep / vector / agentmemory se puntúan en paralelo, salida NDJSON, y las scorecards publicadas quedan en [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Funciona muy bien con [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) y [Graphify](https://github.com/safishamsi/graphify).** Indexado de grafos de código, pipelines de build multiagente y grafos de conocimiento más amplios sobre documentos / PDFs / imágenes / vídeos. agentmemory recuerda el trabajo; esos tres proyectos iluminan el resto de la capa de contexto. Recetas y tabla de enrutamiento por pregunta: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="Comparativa" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">Built-in (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>Tipo</strong></td>
+<td>Motor de memoria + servidor MCP</td>
+<td>API de capa de memoria</td>
+<td>Runtime de agente completo</td>
+<td>Fichero estático</td>
+</tr>
+<tr>
+<td><strong>Retrieval R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>Captura automática</strong></td>
+<td>12 hooks (esfuerzo manual cero)</td>
+<td>Llamadas manuales a <code>add()</code></td>
+<td>El agente se edita a sí mismo</td>
+<td>Edición manual</td>
+</tr>
+<tr>
+<td><strong>Búsqueda</strong></td>
+<td>BM25 + Vector + Graph (fusión RRF)</td>
+<td>Vector + Graph</td>
+<td>Vector (archival)</td>
+<td>Carga todo en contexto</td>
+</tr>
+<tr>
+<td><strong>Multiagente</strong></td>
+<td>MCP + REST + leases + signals</td>
+<td>API (sin coordinación)</td>
+<td>Solo dentro del runtime de Letta</td>
+<td>Ficheros por agente</td>
+</tr>
+<tr>
+<td><strong>Dependencia de framework</strong></td>
+<td>Ninguna (cualquier cliente MCP)</td>
+<td>Ninguna</td>
+<td>Alta (obliga a usar Letta)</td>
+<td>Formato por agente</td>
+</tr>
+<tr>
+<td><strong>Dependencias externas</strong></td>
+<td>Ninguna (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + BD vectorial</td>
+<td>Ninguna</td>
+</tr>
+<tr>
+<td><strong>Ciclo de vida de memoria</strong></td>
+<td>Consolidación de 4 niveles + decaimiento + auto-olvido</td>
+<td>Extracción pasiva</td>
+<td>Gestionado por el agente</td>
+<td>Poda manual</td>
+</tr>
+<tr>
+<td><strong>Eficiencia de tokens</strong></td>
+<td>~1.900 tokens/sesión ($10/año)</td>
+<td>Varía según la integración</td>
+<td>Memoria principal en contexto</td>
+<td>22K+ tokens con 240 obs</td>
+</tr>
+<tr>
+<td><strong>Visor en tiempo real</strong></td>
+<td>Sí (port 3113)</td>
+<td>Dashboard en la nube</td>
+<td>Dashboard en la nube</td>
+<td>No</td>
+</tr>
+<tr>
+<td><strong>Self-hosted</strong></td>
+<td>Sí (por defecto)</td>
+<td>Opcional</td>
+<td>Opcional</td>
+<td>Sí</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Inicio rápido" height="32" /></picture></h2>
+
+Compatibilidad: esta release apunta a `iii-sdk` estable `^0.11.0` e iii-engine v0.11.x.
+
+### Pruébalo en 30 segundos
+
+```bash
+# Terminal 1: start the server
+npx @agentmemory/agentmemory
+
+# Terminal 2: seed sample data and see recall in action
+npx @agentmemory/agentmemory demo
+```
+
+`demo` siembra 3 sesiones realistas (autenticación JWT, corrección de N+1 queries, rate limiting) y ejecuta búsquedas semánticas sobre ellas. Verás cómo encuentra "N+1 query fix" al buscar "database performance optimization" — algo que la coincidencia por palabra clave no puede hacer.
+
+Abre `http://localhost:3113` para ver cómo se construye la memoria en directo.
+
+### Recomendado: instala globalmente
+
+`npx` cachea por versión. Si la semana pasada ejecutaste `npx @agentmemory/agentmemory@0.9.14`, un simple `npx @agentmemory/agentmemory` puede servir la versión obsoleta 0.9.14 desde `~/.npm/_npx/`, y no la última. Instala una vez y el comando `agentmemory` funciona en cualquier sitio:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # start the server (same as the npx form)
+agentmemory stop               # tear it down
+agentmemory remove             # uninstall everything we created
+agentmemory connect claude-code   # wire one agent
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+A partir de v0.9.16, la primera ejecución vía npx pregunta si deseas instalar globalmente — responde `Y` una vez y listo. Si lo saltas, recurre a cualquiera de estos para un fetch limpio:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)
+```
+
+En Windows / PowerShell, el equivalente para limpiar caché es `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — la opción `npx -y ...@latest` de arriba es la alternativa multiplataforma.
+
+### Session Replay
+
+Toda sesión que agentmemory registra es reproducible. Abre el visor, elige la pestaña **Replay** y desplázate por la línea de tiempo: prompts, llamadas a herramientas, resultados y respuestas se renderizan como eventos discretos con play/pause, control de velocidad (0,5×–4×) y atajos de teclado (espacio para alternar, flechas para avanzar paso a paso).
+
+¿Ya tienes transcripciones JSONL antiguas de Claude Code que quieras importar?
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx @agentmemory/agentmemory import-jsonl
+
+# Or import a single file
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Las sesiones importadas aparecen en el selector de Replay junto a las nativas. Por debajo, cada entrada se enruta a través de las funciones iii `mem::replay::load`, `mem::replay::sessions` y `mem::replay::import-jsonl` — sin servidores side-channel.
+
+### Actualización / Mantenimiento
+
+Usa el comando de mantenimiento cuando intencionadamente quieras actualizar tu runtime local:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+Aviso: este comando muta el workspace/runtime actual. Puede actualizar dependencias de JavaScript, puede ejecutar `cargo install iii-engine --force`, y puede traer imágenes Docker.
+
+Los detalles de implementación están en `src/cli.ts` (ver `runUpgrade` en torno a la región `src/cli.ts:544-595`).
+
+### Claude Code (un bloque, pégalo)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Claude Code sin instalar el plugin (ruta MCP standalone)
+
+Si conectas el servidor MCP de agentmemory directamente vía `~/.claude.json` en lugar de usar `/plugin install`, Claude Code nunca resuelve `${CLAUDE_PLUGIN_ROOT}` y tienes que apuntar los scripts de hook a rutas absolutas en `~/.claude/settings.json`. Esas rutas suelen incluir la versión de agentmemory (p. ej. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), por lo que la siguiente actualización rompe silenciosamente todos los hooks ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+Solución:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Esto fusiona los mismos comandos de hook en `~/.claude/settings.json` con rutas absolutas que apuntan al directorio `plugin/` empaquetado del paquete `@agentmemory/agentmemory` actualmente instalado. Vuelve a ejecutar el comando tras actualizar agentmemory para refrescar las rutas. Las entradas de usuario en el mismo fichero se preservan; solo se reemplazan las entradas previas de agentmemory. La ruta vía `/plugin install` sigue siendo la recomendada.
+Para despliegues remotos o protegidos, lanza Claude Code con `AGENTMEMORY_URL` y `AGENTMEMORY_SECRET` definidos. El plugin pasa ambos valores a su servidor MCP empaquetado; cuando `AGENTMEMORY_URL` está vacío, el shim MCP usa `http://localhost:3111`.
+
+### Codex CLI (plataforma de plugins Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+El plugin de Codex se sirve desde el mismo directorio `plugin/` que el de Claude Code. Registra:
+
+- `@agentmemory/mcp` como servidor MCP (hace de proxy a las 51 tools cuando `AGENTMEMORY_URL` apunta a un servidor agentmemory en ejecución; cae a 7 tools en local cuando no hay servidor accesible)
+- 6 hooks de ciclo de vida: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 skills: `/recall`, `/remember`, `/session-history`, `/forget`
+
+El motor de hooks de Codex inyecta `CLAUDE_PLUGIN_ROOT` en los subprocesos de hook (según [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), por lo que los mismos scripts de hook funcionan en ambos hosts sin duplicación. Los eventos Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure son exclusivos de Claude Code y no se registran para Codex.
+
+#### Codex Desktop: los hooks del plugin están silenciados (con workaround)
+
+`CodexHooks` y `PluginHooks` son estables y están activados por defecto en [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), pero las builds actuales de Codex Desktop no despachan el `hooks.json` local del plugin ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). Las tools MCP siguen funcionando; solo faltan las observaciones del ciclo de vida.
+
+Hasta que se solucione upstream, replica los mismos comandos de hook en el `~/.codex/hooks.json` global:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+Esto añade un bloque idempotente a `~/.codex/hooks.json` que referencia rutas absolutas a los scripts empaquetados (no hace falta expandir `${CLAUDE_PLUGIN_ROOT}` en el ámbito de usuario). Vuelve a ejecutar el mismo comando tras actualizar agentmemory para refrescar las rutas. Las entradas de usuario en el mismo fichero se preservan; solo se reemplazan las entradas previas de agentmemory.
+
+<details>
+<summary><b>OpenClaw (pega este prompt)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+Guía completa: [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (pega este prompt)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Guía completa: [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### Otros agentes
+
+Arranca el servidor de memoria: `npx @agentmemory/agentmemory`
+
+La entrada de agentmemory es el **mismo bloque de servidor MCP** en cada host que use la forma `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**Fusiona esta entrada en el objeto `mcpServers` existente** en el fichero de configuración del host — no reemplaces el fichero. Si el fichero ya contiene otros servidores, añade `agentmemory` junto a ellos como otra clave dentro de `mcpServers`. Si `mcpServers` no existe, pega el bloque dentro de `{ "mcpServers": { ... } }`. Los marcadores `${VAR}` heredan `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` del shell al lanzar el servidor MCP — si no están definidas se pasan como cadena vacía y el shim cae a `http://localhost:3111`. Una sola entrada cubre tanto despliegues locales como remotos (k8s / con reverse-proxy).
+
+| Agente | Fichero de configuración | Notas |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | Fusiona en `mcpServers`. También hay deeplink de un clic en el sitio web. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Fusiona en `mcpServers`. Reinicia Claude Desktop tras editar. |
+| **Cline / Roo Code / Kilo Code** | Ajustes MCP de Cline (Settings UI → MCP Servers → Edit) | Mismo bloque `mcpServers`. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Mismo bloque `mcpServers`. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (fusión automática). |
+| **OpenClaw** | Configuración MCP de OpenClaw | Mismo bloque `mcpServers`, o usa el [memory plugin](../integrations/openclaw/) más profundo. |
+| **Codex CLI (solo MCP)** | `.codex/config.toml` | Forma TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, o añade `[mcp_servers.agentmemory]` a mano. |
+| **Codex CLI (plugin completo)** | Marketplace de plugins Codex | `codex plugin marketplace add rohitg00/agentmemory` y luego `codex plugin add agentmemory@agentmemory`. Registra MCP + 6 hooks de ciclo de vida (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills. En Codex Desktop, ejecuta también `agentmemory connect codex --with-hooks` hasta que se mergee [openai/codex#16430](https://github.com/openai/codex/issues/16430) — los hooks de plugin están silenciados allí. |
+| **OpenCode (solo MCP)** | `opencode.json` | Forma distinta — clave `mcp` en el nivel superior, comando como array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin completo)** | `plugin/opencode/` | 22 hooks de captura automática que cubren ciclo de vida de sesión, mensajes, tools y errores. Dos comandos slash (`/recall`, `/remember`). Copia `plugin/opencode/` a tu workspace de OpenCode y añade la entrada del plugin a `opencode.json`. Tabla completa de hooks + análisis de gaps en [`plugin/opencode/README.md`](../plugin/opencode/README.md). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Copia [`integrations/pi`](../integrations/pi/) y reinicia pi. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Usa el [memory provider plugin](../integrations/hermes/) más profundo con `memory.provider: agentmemory`. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` escribe el bloque `mcpServers` estándar. El payload de los hooks es compatible a nivel de campo con Claude Code, así que los scripts de los 12 hooks existentes funcionan sin modificación — conéctalos en la sección `hooks` del mismo `settings.json`. |
+| **Antigravity** (sustituye a Gemini CLI) | `mcp_config.json` (en el directorio User de Antigravity) | `agentmemory connect antigravity` escribe el bloque `mcpServers` estándar. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Úsalo tras el sunset de Gemini CLI del 2026-06-18. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` escribe la configuración de nivel usuario. Los overrides por workspace van en `.kiro/settings/mcp.json` junto a tu código. |
+| **Goose** | UI de ajustes MCP de Goose | Mismo bloque `mcpServers`. |
+| **Aider** | n/a | Habla directamente con la REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Cualquier agente (32+)** | n/a | `npx skillkit install agentmemory` auto-detecta el host y fusiona. |
+
+**Clientes MCP en sandbox** (Flatpak / Snap / contenedores restrictivos) que no pueden alcanzar el `localhost` del host: añade también `"AGENTMEMORY_FORCE_PROXY": "1"` al bloque `env`, y apunta `AGENTMEMORY_URL` a una ruta que el sandbox sí pueda alcanzar (p. ej. tu IP de LAN). Consulta [#234](https://github.com/rohitg00/agentmemory/issues/234) para el walkthrough de diagnóstico.
+
+### Acceso programático (Python / Rust / Node)
+
+agentmemory registra sus operaciones principales como funciones iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Cualquier lenguaje con un SDK iii puede llamarlas directamente sobre `ws://localhost:49134` — sin un cliente REST separado por lenguaje.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Ejemplo trabajado: [`examples/python/`](../examples/python/) (quickstart + flujo de observación/recall). La REST en `:3111` sigue disponible para hosts sin runtime iii.
+
+### Desde el código fuente
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Esto arranca agentmemory con un `iii-engine` local si `iii` ya está instalado, o cae a Docker Compose si hay Docker disponible. REST, streams y el visor se enlazan a `127.0.0.1` por defecto.
+
+Instala `iii-engine` manualmente. **agentmemory actualmente fija `iii-engine` a `v0.11.2`** — `v0.11.6` introduce un nuevo modelo que sandboxea todo vía `iii worker add`, y agentmemory aún no se ha refactorizado para él. La fijación se levantará cuando aterrice el refactor. Sobrescribe con `AGENTMEMORY_III_VERSION=<version>` si has migrado al modelo sandbox manualmente.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** cambia `aarch64-apple-darwin` por `x86_64-apple-darwin`
+- **Linux x64:** cambia por `x86_64-unknown-linux-gnu`
+- **Linux arm64:** cambia por `aarch64-unknown-linux-gnu`
+- **Windows:** descarga `iii-x86_64-pc-windows-msvc.zip` desde [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extrae `iii.exe`, añádelo al PATH
+
+O usa Docker (el `docker-compose.yml` empaquetado descarga `iiidev/iii:0.11.2`). Documentación completa: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory funciona en Windows 10/11, pero el paquete de Node.js por sí solo no es suficiente — también necesitas el runtime `iii-engine` (un binario nativo aparte) como proceso en segundo plano. El instalador oficial upstream es un script `sh` y hoy no existe un instalador PowerShell ni paquete scoop/winget, así que los usuarios de Windows tienen dos rutas:
+
+**Opción A — Binario Windows preconstruido (recomendado):**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe somewhere on PATH, or place it at:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory checks that location automatically)
+# 4. Verify:
+iii --version
+# Should print: 0.11.2
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**Opción B — Docker Desktop:**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**Opción C — Solo MCP standalone (sin engine):** si solo necesitas las tools MCP para tu agente y no necesitas la REST API, el visor ni los cron jobs, sáltate el engine por completo:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnóstico para Windows:** si `npx @agentmemory/agentmemory` falla, vuelve a ejecutar con `--verbose` para ver el stderr real del engine. Modos de fallo habituales:
+
+| Síntoma | Solución |
+|---|---|
+| `iii-engine process started` seguido de `did not become ready within 15s` | El engine ha crasheado al arrancar — reejecuta con `--verbose` y revisa stderr |
+| `Could not start iii-engine` | Ni `iii.exe` ni Docker están instalados. Ver Opción A o B |
+| Conflicto de puerto | `netstat -ano \| findstr :3111` para ver qué está vinculado, mátalo o usa `--port <N>` |
+| Se omite el fallback a Docker aunque Docker esté instalado | Asegúrate de que Docker Desktop esté efectivamente en ejecución (icono en la bandeja del sistema) |
+
+> Nota: no existe `cargo install iii-engine` — `iii` no está publicado en crates.io. Los únicos métodos de instalación soportados son el binario preconstruido de arriba, el script `sh` upstream (solo macOS/Linux) y la imagen Docker.
+
+---
+
+<h2 id="deploy">Deploy</h2>
+
+Plantillas de un clic para hosts gestionados. Cada una incluye un
+Dockerfile autocontenido que descarga `@agentmemory/agentmemory` desde npm
+y copia el binario del iii engine desde la imagen oficial `iiidev/iii` de
+Docker Hub — no se requiere una imagen preconstruida de agentmemory. El
+almacenamiento persistente se monta en `/data`; el entrypoint del primer
+arranque sobrescribe la configuración iii empaquetada por npm (que se
+enlaza a `127.0.0.1`) por una afinada para despliegue que se enlaza a
+`0.0.0.0` y usa rutas absolutas `/data`, genera el secreto HMAC y
+baja privilegios de `root` a `node` con `gosu` antes de hacer exec
+del CLI de agentmemory.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+El botón de despliegue de un clic de Render requiere un `render.yaml` en la raíz del repo, que mantenemos limpio a propósito. Usa el flujo Render Blueprint documentado en [`deploy/render/`](../deploy/render/README.md) para apuntar al blueprint del repo manualmente.
+
+Los detalles completos de configuración (captura HMAC, túnel SSH del visor, rotación, backup, mínimos de coste) están en [`deploy/`](../deploy/README.md):
+
+- [`deploy/fly`](../deploy/fly/README.md) — máquina única con `auto_stop_machines = "stop"`; más barato en idle.
+- [`deploy/railway`](../deploy/railway/README.md) — tarifa plana del plan Hobby, volumen en el dashboard.
+- [`deploy/render`](../deploy/render/README.md) — flujo Blueprint, snapshots automáticos de disco en planes de pago.
+- [`deploy/coolify`](../deploy/coolify/README.md) — self-hosted en tu propio VPS vía [Coolify](https://coolify.io/self-hosted); misma stack Docker Compose, tú eres dueño del host y los datos.
+
+Solo se publica el puerto `3111`. El visor en `3113` permanece enlazado a loopback dentro del contenedor — el README de cada plantilla documenta el patrón de túnel SSH para alcanzarlo.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Por qué agentmemory" height="32" /></picture></h2>
+
+Todo agente de codificación olvida todo al terminar la sesión. Pierdes los primeros 5 minutos de cada sesión re-explicando tu stack. agentmemory corre en segundo plano y lo elimina por completo.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### Frente a la memoria integrada del agente
+
+Todo agente de codificación con IA viene con memoria integrada — Claude Code tiene `MEMORY.md`, Cursor tiene notepads, Cline tiene memory bank. Funcionan como notas adhesivas. agentmemory es la base de datos buscable que hay detrás de esas notas adhesivas.
+
+| | Integrada (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Escala | tope de 200 líneas | Ilimitado |
+| Búsqueda | Carga todo en contexto | BM25 + vector + graph (solo top-K) |
+| Coste en tokens | 22K+ con 240 observaciones | ~1.900 tokens (92% menos) |
+| Cross-agent | Ficheros por agente | MCP + REST (cualquier agente) |
+| Coordinación | Ninguna | Leases, signals, actions, routines |
+| Observabilidad | Lectura manual de ficheros | Visor en tiempo real en :3113 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="Cómo funciona" height="32" /></picture></h2>
+
+### Pipeline de memoria
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### Consolidación de memoria en 4 niveles
+
+Inspirada en cómo el cerebro humano procesa la memoria — no muy diferente de la consolidación del sueño.
+
+| Nivel | Qué | Analogía |
+|------|------|---------|
+| **Working** | Observaciones crudas a partir del uso de tools | Memoria a corto plazo |
+| **Episodic** | Resúmenes de sesión comprimidos | "Qué pasó" |
+| **Semantic** | Hechos y patrones extraídos | "Lo que sé" |
+| **Procedural** | Workflows y patrones de decisión | "Cómo hacerlo" |
+
+Las memorias decaen con el tiempo (curva de Ebbinghaus). Las memorias accedidas con frecuencia se refuerzan. Las memorias obsoletas se evictan automáticamente. Las contradicciones se detectan y resuelven.
+
+### Qué se captura
+
+| Hook | Captura |
+|------|----------|
+| `SessionStart` | Ruta de proyecto, ID de sesión |
+| `UserPromptSubmit` | Prompts del usuario (con filtro de privacidad) |
+| `PreToolUse` | Patrones de acceso a ficheros + contexto enriquecido |
+| `PostToolUse` | Nombre de la tool, entrada, salida |
+| `PostToolUseFailure` | Contexto del error |
+| `PreCompact` | Re-inyecta memoria antes de la compactación |
+| `SubagentStart/Stop` | Ciclo de vida de sub-agentes |
+| `Stop` | Resumen de fin de sesión |
+| `SessionEnd` | Marcador de sesión completa |
+
+### Capacidades clave
+
+| Capacidad | Descripción |
+|---|---|
+| **Captura automática** | Cada uso de tool registrado vía hooks — esfuerzo manual cero |
+| **Búsqueda semántica** | BM25 + vector + grafo de conocimiento con fusión RRF |
+| **Evolución de memoria** | Versionado, supersesión, grafos de relaciones |
+| **Auto-olvido** | Expiración por TTL, detección de contradicciones, evicción por importancia |
+| **Privacy first** | API keys, secretos y etiquetas `<private>` se eliminan antes del almacenado |
+| **Self-healing** | Circuit breaker, cadena de fallback de proveedores, monitorización de salud |
+| **Puente Claude** | Sincronización bidireccional con MEMORY.md |
+| **Grafo de conocimiento** | Extracción de entidades + recorrido BFS |
+| **Memoria de equipo** | Espacios compartidos y privados con namespace por miembro |
+| **Provenance de citas** | Traza cualquier memoria de vuelta a las observaciones origen |
+| **Snapshots de Git** | Versiona, revierte y diffea el estado de memoria |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Búsqueda" height="32" /></picture></h2>
+
+Recuperación de triple stream combinando tres señales:
+
+| Stream | Qué hace | Cuándo |
+|---|---|---|
+| **BM25** | Coincidencia por palabras con stemming y expansión de sinónimos | Siempre activo |
+| **Vector** | Similitud coseno sobre embeddings densos | Proveedor de embeddings configurado |
+| **Graph** | Recorrido del grafo de conocimiento vía coincidencia de entidades | Entidades detectadas en la consulta |
+
+Fusionado con Reciprocal Rank Fusion (RRF, k=60) y diversificado por sesión (máximo 3 resultados por sesión).
+
+BM25 tokeniza griego, cirílico, hebreo, árabe y latín con tildes de serie. Para memorias en chino / japonés / coreano, instala los segmentadores opcionales (`npm install @node-rs/jieba tiny-segmenter`) para partir los runs CJK en tokens a nivel de palabra; sin ellos, agentmemory hace soft-fallback a tokenización por run completo y muestra una pista única en stderr.
+
+### Proveedores de embedding
+
+agentmemory autodetecta tu proveedor. Para mejores resultados, instala embeddings locales (gratis):
+
+```bash
+npm install @xenova/transformers
+```
+
+| Proveedor | Modelo | Coste | Notas |
+|---|---|---|---|
+| **Local (recomendado)** | `all-MiniLM-L6-v2` | Gratis | Offline, +8pp de recall sobre BM25-only |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ idiomas, 768/1536/3072 dims (MRL), entrada de 2048 tokens. Sustituye a `text-embedding-004` ([deprecado, cierre el 14 ene 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Máxima calidad |
+| Voyage AI | `voyage-code-3` | De pago | Optimizado para código |
+| Cohere | `embed-english-v3.0` | Trial gratis | Uso general |
+| OpenRouter | Cualquier modelo | Varía | Proxy multi-modelo |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="Servidor MCP" height="32" /></picture></h2>
+
+53 tools, 6 recursos, 3 prompts y 4 skills — el toolkit MCP de memoria más completo para cualquier agente.
+
+> **Shim MCP vs servidor completo:** el paquete publicado `@agentmemory/mcp` es un shim ligero. Expone la superficie completa de 51 tools **solo cuando puede alcanzar un servidor agentmemory en ejecución** vía `AGENTMEMORY_URL` (modo proxy). Sin servidor accesible, el shim cae a un set local de 7 tools (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). La variable de entorno `AGENTMEMORY_TOOLS=core|all` es un flag *del lado del servidor* — definirla en el bloque `env` del shim no tiene efecto. Si ves solo 7 tools en Cursor / OpenCode / Gemini CLI, arranca `npx @agentmemory/agentmemory` (o la stack Docker) y define `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 51 Tools
+
+<details>
+<summary>Tools principales (siempre disponibles)</summary>
+
+| Tool | Descripción |
+|------|-------------|
+| `memory_recall` | Busca observaciones pasadas |
+| `memory_compress_file` | Comprime ficheros markdown preservando la estructura |
+| `memory_save` | Guarda un insight, decisión o patrón |
+| `memory_patterns` | Detecta patrones recurrentes |
+| `memory_smart_search` | Búsqueda híbrida semántica + por palabras |
+| `memory_file_history` | Observaciones pasadas sobre ficheros concretos |
+| `memory_sessions` | Lista sesiones recientes |
+| `memory_timeline` | Observaciones cronológicas |
+| `memory_profile` | Perfil de proyecto (conceptos, ficheros, patrones) |
+| `memory_export` | Exporta todos los datos de memoria |
+| `memory_relations` | Consulta el grafo de relaciones |
+
+</details>
+
+<details>
+<summary>Tools extendidas (51 en total — define AGENTMEMORY_TOOLS=all)</summary>
+
+| Tool | Descripción |
+|------|-------------|
+| `memory_patterns` | Detecta patrones recurrentes |
+| `memory_timeline` | Observaciones cronológicas |
+| `memory_relations` | Consulta el grafo de relaciones |
+| `memory_graph_query` | Recorrido del grafo de conocimiento |
+| `memory_consolidate` | Ejecuta la consolidación de 4 niveles |
+| `memory_claude_bridge_sync` | Sincroniza con MEMORY.md |
+| `memory_team_share` | Comparte con miembros del equipo |
+| `memory_team_feed` | Elementos compartidos recientes |
+| `memory_audit` | Pista de auditoría de operaciones |
+| `memory_governance_delete` | Borrado con pista de auditoría |
+| `memory_snapshot_create` | Snapshot versionado en Git |
+| `memory_action_create` | Crea ítems de trabajo con dependencias |
+| `memory_action_update` | Actualiza estado de una action |
+| `memory_frontier` | Actions desbloqueadas, ordenadas por prioridad |
+| `memory_next` | La única acción más importante a continuación |
+| `memory_lease` | Leases exclusivos de actions (multiagente) |
+| `memory_routine_run` | Instancia rutinas de workflow |
+| `memory_signal_send` | Mensajería entre agentes |
+| `memory_signal_read` | Lee mensajes con acuse de recibo |
+| `memory_checkpoint` | Gates de condiciones externas |
+| `memory_mesh_sync` | Sincronización P2P entre instancias |
+| `memory_sentinel_create` | Watchers dirigidos por eventos |
+| `memory_sentinel_trigger` | Dispara sentinels desde fuera |
+| `memory_sketch_create` | Grafos de actions efímeros |
+| `memory_sketch_promote` | Promociona a permanente |
+| `memory_crystallize` | Compacta cadenas de actions |
+| `memory_diagnose` | Health checks |
+| `memory_heal` | Repara automáticamente estado atascado |
+| `memory_facet_tag` | Tags dimension:value |
+| `memory_facet_query` | Consulta por tags de facet |
+| `memory_verify` | Traza provenance |
+
+</details>
+
+### 6 Recursos · 3 Prompts · 4 Skills
+
+| Tipo | Nombre | Descripción |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Salud, conteo de sesiones, conteo de memorias |
+| Resource | `agentmemory://project/{name}/profile` | Inteligencia por proyecto |
+| Resource | `agentmemory://memories/latest` | Las 10 memorias activas más recientes |
+| Resource | `agentmemory://graph/stats` | Estadísticas del grafo de conocimiento |
+| Prompt | `recall_context` | Búsqueda + devuelve mensajes de contexto |
+| Prompt | `session_handoff` | Datos de traspaso entre agentes |
+| Prompt | `detect_patterns` | Analiza patrones recurrentes |
+| Skill | `/recall` | Busca en memoria |
+| Skill | `/remember` | Guarda en memoria a largo plazo |
+| Skill | `/session-history` | Resúmenes recientes de sesiones |
+| Skill | `/forget` | Borra observaciones/sesiones |
+
+### MCP standalone
+
+Ejecútalo sin el servidor completo — para cualquier cliente MCP. Cualquiera de estos funciona:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (always available)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+O añádelo a la configuración MCP de tu agente:
+
+La mayoría de los agentes (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+Fusiona la entrada `agentmemory` en el objeto `mcpServers` existente del host en lugar de reemplazar el fichero. Para clientes en sandbox que no pueden alcanzar el `localhost` del host, añade `"AGENTMEMORY_FORCE_PROXY": "1"` al bloque env y define `AGENTMEMORY_URL` a una ruta a la que el sandbox sí pueda llegar.
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copia el fichero del plugin desde el repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Visor en tiempo real" height="32" /></picture></h2>
+
+Se inicia automáticamente en el puerto `3113`. Stream de observaciones en vivo, explorador de sesiones, navegador de memoria, visualización del grafo de conocimiento y dashboard de salud.
+
+```bash
+open http://localhost:3113
+```
+
+El servidor del visor se enlaza a `127.0.0.1` por defecto. El endpoint servido por REST `/agentmemory/viewer` sigue las reglas habituales de bearer-token `AGENTMEMORY_SECRET`. Las cabeceras CSP usan un nonce de script por respuesta y desactivan los atributos handler inline (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+El visor en `:3113` muestra lo que tu agente **recordó**. La [iii console](https://iii.dev/docs/console) muestra lo que tu agente **hizo** — cada operación de memoria como una traza OpenTelemetry, cada entrada KV editable, cada función invocable, cada stream tappable. Dos ventanas sobre la misma memoria: una con forma de producto, otra con forma de motor.
+
+Mira cómo se dispara `memory_smart_search` y observa el escaneo BM25 → consulta de embedding → fusión RRF → reranker como un waterfall. Edita un temporizador de consolidación atascado en el navegador KV. Reproduce un hook `PostToolUse` con un payload ajustado. Fija el stream WebSocket y mira cómo aterrizan las observaciones en vivo.
+
+agentmemory ofrece esto gratis porque cada función, trigger, scope de estado y stream es un primitivo de iii — nada custom, nada que instrumentar.
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="Página Workers de iii console — workers conectados incluyendo instancias de agentmemory con conteo de funciones en vivo y metadatos de runtime" width="720" />
+  <br/>
+  <em>Página Workers: cada worker conectado — incluida agentmemory — con PID, conteo de funciones, runtime y last-seen.</em>
+</p>
+
+**Ya instalada.** La console se incluye con `iii` — sin instalador aparte.
+
+**Lánzala junto a agentmemory:**
+
+```bash
+# agentmemory viewer holds port 3113, so run the console on 3114.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
+```
+
+Luego abre `http://localhost:3114`. Añade `--enable-flow` para la página experimental de grafo de arquitectura.
+
+Sobrescribe endpoints del engine solo si los has movido:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**Qué puedes hacer desde la console:**
+
+| Página | Úsala para |
+|------|-----------|
+| **Workers** | Ver todos los workers conectados y sus métricas en vivo — incluyendo el propio worker de agentmemory. |
+| **Functions** | Invocar cualquier función de agentmemory directamente con un payload JSON — útil para probar `memory.recall`, `memory.consolidate`, `graph.query` sin cablear un cliente. |
+| **Triggers** | Reproducir triggers HTTP, cron, event y state — disparar manualmente el cron de consolidación, reintentar una ruta HTTP, emitir un cambio de estado. |
+| **States** | Navegador KV con CRUD completo — sesiones, slots de memoria, temporizadores del ciclo de vida, índice de embeddings — edita valores in-place. |
+| **Streams** | Monitor WebSocket en vivo para escrituras de memoria, eventos de hooks y actualizaciones de observaciones a medida que fluyen por los streams de iii. |
+| **Queues** | Topics de cola duraderas + gestión de dead-letter. Reproduce o descarta jobs fallidos de embedding / compresión. |
+| **Traces** | Vistas OpenTelemetry waterfall / flame / desglose por servicio. Filtra por `trace_id` para ver exactamente qué funciones, llamadas a BD y peticiones de embedding produjo un único `memory.search`. |
+| **Logs** | Logs OTEL estructurados, filtrados y correlados con trace/span IDs. |
+| **Config** | Configuración de runtime — ve exactamente con qué workers, proveedores y puertos está ejecutando tu engine. |
+| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitectura interactivo de cada worker, trigger y stream. |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="Vista de waterfall de trazas de iii console mostrando duración por span" width="720" />
+  <br/>
+  <em>Traces: waterfall / flame / desglose por servicio para cada operación de memoria.</em>
+</p>
+
+**Las trazas ya están activas:**
+
+`iii-config.yaml` se sirve con el worker `iii-observability` habilitado (`exporter: memory`, `sampling_ratio: 1.0`, métricas + logs). No se necesita configuración adicional — desde el momento en que agentmemory arranca, cada operación de memoria emite una traza-span y un log estructurado que la console puede leer.
+
+Si quieres exportar a Jaeger/Honeycomb/Grafana Tempo en su lugar, cambia `exporter: memory` por `exporter: otlp` y define el endpoint del collector según la documentación de observabilidad de iii.
+
+> **Aviso:** la console en sí no impone auth — mantenla enlazada a `127.0.0.1` (por defecto) y nunca la expongas públicamente.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory **ya es una instancia [iii](https://iii.dev) en ejecución**. Funciones, triggers, estado KV, streams, trazas OTEL — todo son primitivos de iii. No has instalado Postgres, Redis, Express, pm2 ni Prometheus, porque iii los reemplaza.
+
+Eso significa que un comando más extiende agentmemory con una capacidad completamente nueva.
+
+### Extiende agentmemory con un comando
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+Cada `iii worker add` registra nuevas funciones y triggers en el mismo engine en el que agentmemory ya está corriendo. El visor y la console los detectan al instante — sin recargar, sin nueva integración, sin nuevo contenedor.
+
+| `iii worker add` | Qué obtienes encima de agentmemory |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Memoria multi-instancia: cada `remember` se difunde, cada `search` lee la unión |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Ciclo de vida programado — consolidación nocturna, snapshots semanales, decaimiento en un reloj fijo |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Reintentos duraderos: los jobs de embedding + compresión fallidos sobreviven al reinicio, sin observaciones perdidas |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | Trazas OTEL, métricas y logs en cada función — cableado en `iii-config.yaml` desde el primer día |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | El código salido de `memory_recall` corre dentro de una VM desechable, no en tu shell |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | Adaptador de estado respaldado por SQL cuando te quedas pequeño con el KV in-memory por defecto |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Levanta servidores MCP adicionales junto al MCP de agentmemory, compartiendo el mismo engine |
+
+Registro completo: [workers.iii.dev](https://workers.iii.dev). Cada worker allí se compone a través de los mismos primitivos que usa agentmemory — y el agentmemory que ya tienes es uno de ellos.
+
+### Qué reemplaza iii
+
+| Stack tradicional | agentmemory usa |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + índice vectorial in-memory |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | Supervisión de workers del iii engine |
+| Prometheus / Grafana | iii OTEL + monitor de salud |
+| Sistemas de plugins propios | `iii worker add <name>` |
+
+**118 ficheros de código · ~21.800 LOC · 950+ tests · 123 funciones · 34 scopes KV** — todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuración" height="32" /></picture></h2>
+
+### Proveedores de LLM
+
+agentmemory autodetecta desde tu entorno. Por defecto no se hacen llamadas LLM a menos que configures un proveedor o aceptes explícitamente el fallback de suscripción de Claude.
+
+| Proveedor | Configuración | Notas |
+|----------|--------|-------|
+| **No-op (por defecto)** | Sin configuración | Compresión/resumen vía LLM DESACTIVADA. La compresión sintética BM25 + recall siguen funcionando. Mira `AGENTMEMORY_ALLOW_AGENT_SDK` más abajo si dependías del fallback de suscripción de Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Facturación por token |
+| MiniMax | `MINIMAX_API_KEY` | Compatible con Anthropic |
+| Gemini | `GEMINI_API_KEY` | También habilita embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Cualquier modelo |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Solo opt-in. Lanza sesiones de `@anthropic-ai/claude-agent-sdk` — solía causar recursión sin límite en el Stop-hook (seguimiento de #149), por eso ya no es el comportamiento por defecto. |
+
+### Selección de modelo con conciencia de coste
+
+La compresión en background corre en cada observación, así que la elección de modelo cambia el gasto mensual de forma significativa. Datos de carga capturados: 635 peticiones / 888K tokens / 35 horas de uso activo, sobre tres modelos de OpenRouter con precios del 2026-05-23.
+
+| Tier | Modelo | Input / 1M | Output / 1M | Coste para las 35h capturadas | Notas |
+|------|-------|------------|-------------|---------------------------|-------|
+| Recomendado | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Calidad de compresión + resumen sólida a ~10× menos coste que Sonnet. |
+| Recomendado | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | Más antiguo pero aún correcto para cargas solo de compresión. |
+| Recomendado | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Buen razonamiento de código si tus sesiones son muy code-centric. |
+| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | Alta calidad pero caro para trabajo de background siempre activo. |
+| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Tier similar a Sonnet. |
+| Evitar | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | Modelo de reasoning; sobrecoste enorme para compresión. |
+
+agentmemory imprime un aviso en runtime cuando `OPENROUTER_MODEL` coincide con un patrón de tier premium. Define `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para silenciarlo una vez que hayas tomado una decisión informada.
+
+Trade-off de calidad vs coste en trabajo de memoria: la compresión es una tarea de resumen con un listón de calidad relativamente flexible (quien re-lee el resumen es el agente, no el usuario). DeepSeek-V4-Pro / Qwen3-Coder se quedan dentro del error de redondeo respecto a Sonnet en esta tarea, costando ~10× menos. Reserva los modelos de tier premium para las consultas que leas directamente.
+
+Fuentes: [OpenRouter pricing for Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Memoria multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+En montajes multiagente donde varios roles comparten un servidor agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` etiqueta cada escritura con el rol que la hizo. `AGENTMEMORY_AGENT_SCOPE` controla si el recall filtra por esa etiqueta.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+Dos modos:
+
+| Modo | Etiqueta escrituras | Filtra recall | Cuándo usarlo |
+|------|------------|---------------|-------------|
+| `shared` (por defecto) | sí | no | Contexto cross-agent con pista de auditoría. El architect puede ver lo que el developer apuntó, pero cada fila registra quién lo dijo. |
+| `isolated` | sí | sí | Separación estricta. El architect nunca ve observaciones / memorias / sesiones del developer. |
+
+Qué se etiqueta cuando `AGENT_ID` está definido: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. El rol fluye `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Qué se filtra en modo isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Cada endpoint acepta `?agentId=<role>` para sobreescribir por petición, y `?agentId=*` para optar por salir del scope del entorno por completo. `/memories` también acepta `?includeOrphans=true` para sacar memorias previas a AGENT_ID cuyo `agentId` es undefined.
+
+Sobrescritura por llamada en la capa SDK / REST: cada endpoint que muta (`/session/start`, `/remember`) acepta un campo `agentId` en el body que gana frente al entorno. Útil para runtimes que enrutan muchos roles a un único proceso de servidor.
+
+Cuando `AGENT_ID` no está definido, la memoria permanece sin scope (comportamiento legacy, sin etiquetas, sin filtros).
+
+### Puertos
+
+agentmemory + iii-engine enlazan cuatro puertos por defecto. Si un reinicio falla con `port in use`, esta tabla te dice qué proceso buscar.
+
+| Puerto | Proceso | Propósito | Override por env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker de streams interno (consumido por agentmemory + visor) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Visor en tiempo real (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — los workers se registran aquí, la telemetría OTel fluye por encima | `III_ENGINE_URL` (URL completa, por defecto `ws://localhost:49134`) |
+
+Limpieza de procesos zombi cuando los puertos quedan ocupados tras una ejecución crasheada:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` recoge limpiamente tanto el worker como el pidfile del engine en un shutdown graceful (#640, #474). La limpieza manual de arriba solo aplica al caso post-crash en el que no queda ningún pidfile.
+
+### Fichero de configuración
+
+Coloca la configuración de runtime de agentmemory en `~/.agentmemory/.env` en lugar de exportar variables en cada shell. Si el visor muestra una pista de setup tipo `export ANTHROPIC_API_KEY=...`, cópiala a este fichero como `ANTHROPIC_API_KEY=...` sin el prefijo `export`, y reinicia agentmemory.
+
+Las variables de entorno del proceso siguen funcionando y tienen prioridad sobre los valores del fichero.
+
+En Windows, el mismo fichero vive en `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Para probar con una suscripción Claude Code Pro/Max en lugar de una API key, acepta opt-in explícito:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Activa graph o consolidation en el mismo fichero si las quieres:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### Variables de entorno
+
+Crea `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+124 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer <secret>` cuando `AGENTMEMORY_SECRET` está definido, y los endpoints de mesh sync requieren `AGENTMEMORY_SECRET` en ambos peers.
+
+<details>
+<summary>Endpoints principales</summary>
+
+| Method | Path | Descripción |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (siempre público) |
+| `POST` | `/agentmemory/session/start` | Inicia sesión + obtiene contexto |
+| `POST` | `/agentmemory/session/end` | Finaliza sesión |
+| `POST` | `/agentmemory/observe` | Captura observación |
+| `POST` | `/agentmemory/smart-search` | Búsqueda híbrida |
+| `POST` | `/agentmemory/context` | Genera contexto |
+| `POST` | `/agentmemory/remember` | Guarda en memoria a largo plazo |
+| `POST` | `/agentmemory/forget` | Borra observaciones |
+| `POST` | `/agentmemory/enrich` | Contexto de fichero + memorias + bugs |
+| `GET` | `/agentmemory/profile` | Perfil de proyecto |
+| `GET` | `/agentmemory/export` | Exporta todos los datos |
+| `POST` | `/agentmemory/import` | Importa desde JSON |
+| `POST` | `/agentmemory/graph/query` | Consulta del grafo de conocimiento |
+| `POST` | `/agentmemory/team/share` | Comparte con el equipo |
+| `GET` | `/agentmemory/audit` | Pista de auditoría |
+
+Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Desarrollo" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ tests
+npm run test:integration  # API tests (requires running services)
+```
+
+**Requisitos previos:** Node.js >= 20, [iii-engine](https://iii.dev/docs) o Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licencia" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.fr-FR.md

@@ -0,0 +1,1377 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — Mémoire persistante pour les agents de codage IA" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    Votre agent de codage se souvient de tout. Fini de tout réexpliquer.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Mémoire persistante pour Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode et tout client MCP.
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  Français |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Document de conception : 1200 stars / 172 forks sur le gist" /></a>
+</p>
+
+<p align="center">
+  <em>Le gist étend le motif LLM Wiki de Karpathy avec scoring de confiance, cycle de vie, graphes de connaissances et recherche hybride : agentmemory en est l'implémentation.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="Démo agentmemory" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">Installation</a> &bull;
+  <a href="#quick-start">Démarrage rapide</a> &bull;
+  <a href="#benchmarks">Benchmarks</a> &bull;
+  <a href="#vs-competitors">vs Concurrents</a> &bull;
+  <a href="#works-with-every-agent">Agents</a> &bull;
+  <a href="#how-it-works">Fonctionnement</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">Visualiseur</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">Configuration</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # start the memory server on :3111
+agentmemory demo                                 # seed sample sessions + prove recall
+agentmemory connect claude-code                  # wire your agent (also: codex, cursor, gemini-cli, ...)
+```
+
+Ou via `npx` (sans installation) :
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+À noter — npx met en cache par version. Si un simple `npx @agentmemory/agentmemory` sert une version plus ancienne, forcez la dernière avec `npx -y @agentmemory/agentmemory@latest`, ou videz le cache une fois avec `rm -rf ~/.npm/_npx` (macOS/Linux ; sur Windows, supprimez `%LOCALAPPDATA%\npm-cache\_npx`). Depuis v0.9.16+, la première exécution npx propose une installation globale inline pour que la commande `agentmemory` soit ensuite disponible partout.
+
+Toutes les options dans [Démarrage rapide](#quick-start) ci-dessous. Câblage spécifique par agent dans [Compatible avec tous les agents](#works-with-every-agent).
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Compatible avec tous les agents" height="32" /></picture></h2>
+
+agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'API REST. Tous les agents partagent le même serveur de mémoire.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>plugin natif + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>plugin natif + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>plugin natif + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>plugin natif + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>plugin natif + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>backend natif trait Memory</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>API REST</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>serveur MCP</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>Fonctionne avec <strong>n'importe quel</strong> agent qui parle MCP ou HTTP. Un seul serveur, des mémoires partagées entre tous.</sub>
+</p>
+
+---
+
+Vous expliquez la même architecture à chaque session. Vous redécouvrez les mêmes bugs. Vous réenseignez les mêmes préférences. La mémoire intégrée (CLAUDE.md, .cursorrules) plafonne à 200 lignes et devient obsolète. agentmemory règle ce problème. Il capture silencieusement ce que fait votre agent, le compresse dans une mémoire interrogeable, puis injecte le bon contexte au démarrage de la session suivante. Une seule commande. Compatible entre agents.
+
+**Ce qui change :** Session 1, vous mettez en place l'authentification JWT. Session 2, vous demandez une limitation de débit. L'agent sait déjà que votre authentification utilise le middleware jose dans `src/middleware/auth.ts`, que vos tests couvrent la validation des tokens, et que vous avez choisi jose plutôt que jsonwebtoken pour la compatibilité Edge. Pas de réexplication. Pas de copier-coller. L'agent *sait*, point.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **Nouveau en v0.9.0** — Site d'accueil sur [agent-memory.dev](https://agent-memory.dev), connecteur système de fichiers (`@agentmemory/fs-watcher`), le MCP standalone fait désormais proxy vers le serveur en cours d'exécution afin que les hooks et le visualiseur soient cohérents, politique d'audit codifiée sur tous les chemins de suppression, l'état de santé ne signale plus `memory_critical` sur les petits processus Node. Notes complètes dans [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18).
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Précision de récupération
+
+**coding-agent-life-v1** (corpus interne, reproductible en sandbox)
+
+| Adaptateur | P@5 | R@5 | Taux de hit top-5 | Latence p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| Référence grep | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+100 % de taux de hit top-5. **2,2×** meilleure précision que la référence grep sur entrée identique. Ventilation complète par type : [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 questions)
+
+| Système | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Repli BM25 seul | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Économies de tokens
+
+| Approche | Tokens/an | Coût/an |
+|---|---|---|
+| Coller le contexte complet | 19,5M+ | Impossible (dépasse la fenêtre) |
+| Résumé par LLM | ~650K | ~500 $ |
+| **agentmemory** | **~170K** | **~10 $** |
+| agentmemory + embeddings locaux | ~170K | **0 $** |
+
+</td>
+</tr>
+</table>
+
+> Modèle d'embedding : `all-MiniLM-L6-v2` (local, gratuit, aucune clé d'API). Rapports complets : [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparaison avec les concurrents : [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory vs mem0, Letta, Khoj, claude-mem, Hippo.
+
+**Reproduire localement :** [`eval/README.md`](../eval/README.md) — harnais à adaptateurs pluggables pour LongMemEval `_s` (public, 500 questions) + `coding-agent-life-v1` (corpus interne de 15 sessions). Les adaptateurs grep / vectoriel / agentmemory sont scorés côte à côte, sortie NDJSON, scorecards publiés dans [`docs/benchmarks/`](../docs/benchmarks/).
+
+**À associer à [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) et [Graphify](https://github.com/safishamsi/graphify).** Indexation de graphe de code, pipelines de build multi-agents et graphes de connaissances étendus sur docs / PDFs / images / vidéos. agentmemory mémorise le travail ; ces trois projets éclairent le reste de la couche de contexte. Recettes et tableau de routage des questions : [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="vs Concurrents" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">Intégré (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>Type</strong></td>
+<td>Moteur de mémoire + serveur MCP</td>
+<td>API de couche mémoire</td>
+<td>Runtime d'agent complet</td>
+<td>Fichier statique</td>
+</tr>
+<tr>
+<td><strong>R@5 de récupération</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>Capture automatique</strong></td>
+<td>12 hooks (zéro effort manuel)</td>
+<td>Appels <code>add()</code> manuels</td>
+<td>L'agent s'édite lui-même</td>
+<td>Édition manuelle</td>
+</tr>
+<tr>
+<td><strong>Recherche</strong></td>
+<td>BM25 + Vectoriel + Graphe (fusion RRF)</td>
+<td>Vectoriel + Graphe</td>
+<td>Vectoriel (archival)</td>
+<td>Charge tout en contexte</td>
+</tr>
+<tr>
+<td><strong>Multi-agents</strong></td>
+<td>MCP + REST + leases + signaux</td>
+<td>API (sans coordination)</td>
+<td>Uniquement dans le runtime Letta</td>
+<td>Fichiers par agent</td>
+</tr>
+<tr>
+<td><strong>Verrouillage framework</strong></td>
+<td>Aucun (tout client MCP)</td>
+<td>Aucun</td>
+<td>Élevé (Letta obligatoire)</td>
+<td>Format par agent</td>
+</tr>
+<tr>
+<td><strong>Dépendances externes</strong></td>
+<td>Aucune (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + base vectorielle</td>
+<td>Aucune</td>
+</tr>
+<tr>
+<td><strong>Cycle de vie mémoire</strong></td>
+<td>Consolidation à 4 niveaux + décroissance + oubli automatique</td>
+<td>Extraction passive</td>
+<td>Gérée par l'agent</td>
+<td>Élagage manuel</td>
+</tr>
+<tr>
+<td><strong>Efficacité en tokens</strong></td>
+<td>~1 900 tokens/session (10 $/an)</td>
+<td>Variable selon l'intégration</td>
+<td>Mémoire centrale dans le contexte</td>
+<td>22K+ tokens à 240 observations</td>
+</tr>
+<tr>
+<td><strong>Visualiseur temps réel</strong></td>
+<td>Oui (port 3113)</td>
+<td>Tableau de bord cloud</td>
+<td>Tableau de bord cloud</td>
+<td>Non</td>
+</tr>
+<tr>
+<td><strong>Auto-hébergé</strong></td>
+<td>Oui (par défaut)</td>
+<td>Optionnel</td>
+<td>Optionnel</td>
+<td>Oui</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Démarrage rapide" height="32" /></picture></h2>
+
+Compatibilité : cette version cible `iii-sdk` stable `^0.11.0` et iii-engine v0.11.x.
+
+### Essayez en 30 secondes
+
+```bash
+# Terminal 1: start the server
+npx @agentmemory/agentmemory
+
+# Terminal 2: seed sample data and see recall in action
+npx @agentmemory/agentmemory demo
+```
+
+`demo` amorce 3 sessions réalistes (auth JWT, correctif de requêtes N+1, limitation de débit) et lance des recherches sémantiques dessus. Vous verrez le système trouver « N+1 query fix » quand vous cherchez « database performance optimization » — la correspondance par mots-clés en est incapable.
+
+Ouvrez `http://localhost:3113` pour voir la mémoire se construire en direct.
+
+### Recommandé : installation globale
+
+`npx` met en cache par version. Si vous avez lancé `npx @agentmemory/agentmemory@0.9.14` la semaine dernière, un simple `npx @agentmemory/agentmemory` peut servir le 0.9.14 obsolète depuis `~/.npm/_npx/`, pas la dernière version. Installez une fois et la commande `agentmemory` est disponible partout :
+
+```bash
+npm install -g @agentmemory/agentmemory
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # start the server (same as the npx form)
+agentmemory stop               # tear it down
+agentmemory remove             # uninstall everything we created
+agentmemory connect claude-code   # wire one agent
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+À partir de v0.9.16, la première exécution npx propose une installation globale inline — répondez `Y` une fois et c'est réglé. Si vous passez l'étape, repliez sur l'une de ces options pour un fetch frais :
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)
+```
+
+Sur Windows / PowerShell, l'équivalent pour vider le cache est `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — le `npx -y ...@latest` ci-dessus reste l'option multiplateforme.
+
+### Replay de session
+
+Chaque session enregistrée par agentmemory est rejouable. Ouvrez le visualiseur, choisissez l'onglet **Replay**, et parcourez la chronologie : prompts, appels d'outils, résultats d'outils et réponses s'affichent comme événements discrets avec play/pause, contrôle de vitesse (0,5×–4×) et raccourcis clavier (espace pour basculer, flèches pour avancer).
+
+Vous avez déjà d'anciennes transcriptions JSONL Claude Code à importer ?
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx @agentmemory/agentmemory import-jsonl
+
+# Or import a single file
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Les sessions importées apparaissent dans le sélecteur Replay aux côtés des natives. Sous le capot, chaque entrée passe par les fonctions iii `mem::replay::load`, `mem::replay::sessions` et `mem::replay::import-jsonl` — aucun serveur secondaire.
+
+### Mise à niveau / Maintenance
+
+Utilisez la commande de maintenance lorsque vous voulez intentionnellement mettre à jour votre runtime local :
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+Avertissement : cette commande modifie l'espace de travail / runtime courant. Elle peut mettre à jour les dépendances JavaScript, exécuter `cargo install iii-engine --force` et tirer des images Docker.
+
+Détails d'implémentation dans `src/cli.ts` (voir `runUpgrade` autour de la zone `src/cli.ts:544-595`).
+
+### Claude Code (un seul bloc, à coller)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Claude Code sans installation du plugin (chemin MCP-standalone)
+
+Si vous câblez le serveur MCP d'agentmemory via `~/.claude.json` directement plutôt que via `/plugin install`, Claude Code ne résout jamais `${CLAUDE_PLUGIN_ROOT}` et vous devez pointer les scripts de hooks vers des chemins absolus dans `~/.claude/settings.json`. Ces chemins embarquent typiquement la version d'agentmemory (par ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), si bien que la mise à niveau suivante casse silencieusement tous les hooks ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+Contournement :
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Cela fusionne les mêmes commandes de hooks dans `~/.claude/settings.json` avec des chemins absolus résolus vers le répertoire `plugin/` du paquet `@agentmemory/agentmemory` actuellement installé. Relancez la commande après une mise à niveau d'agentmemory pour rafraîchir les chemins. Les entrées de l'utilisateur dans le même fichier sont préservées ; seules les entrées agentmemory précédentes sont remplacées. Utiliser le chemin `/plugin install` reste l'approche recommandée.
+Pour des déploiements distants ou protégés, lancez Claude Code avec `AGENTMEMORY_URL` et `AGENTMEMORY_SECRET` définis. Le plugin transmet les deux valeurs à son serveur MCP intégré ; quand `AGENTMEMORY_URL` est vide, le shim MCP utilise `http://localhost:3111`.
+
+### Codex CLI (plateforme de plugins Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Le plugin Codex est livré depuis le même répertoire `plugin/` que le plugin Claude Code. Il enregistre :
+
+- `@agentmemory/mcp` comme serveur MCP (proxie les 51 outils lorsque `AGENTMEMORY_URL` pointe vers un serveur agentmemory actif ; retombe sur 7 outils en local si aucun serveur n'est accessible)
+- 6 hooks de cycle de vie : `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 skills : `/recall`, `/remember`, `/session-history`, `/forget`
+
+Le moteur de hooks de Codex injecte `CLAUDE_PLUGIN_ROOT` dans les sous-processus de hooks (cf. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), donc les mêmes scripts de hooks fonctionnent sur les deux hôtes sans duplication. Les événements Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure sont propres à Claude Code et ne sont pas enregistrés pour Codex.
+
+#### Codex Desktop : hooks de plugin actuellement silencieux (contournement disponible)
+
+`CodexHooks` et `PluginHooks` sont tous deux stables + activés par défaut dans [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), mais les builds Codex Desktop actuels ne dispatchent pas les `hooks.json` locaux au plugin ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). Les outils MCP fonctionnent toujours ; seules les observations de cycle de vie manquent.
+
+En attendant le correctif amont, dupliquez les mêmes commandes de hooks dans le `~/.codex/hooks.json` global :
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+Cela ajoute un bloc idempotent à `~/.codex/hooks.json` qui référence des chemins absolus vers les scripts intégrés (pas besoin d'expansion `${CLAUDE_PLUGIN_ROOT}` au scope utilisateur). Relancez la même commande après une mise à niveau d'agentmemory pour rafraîchir les chemins. Les entrées de l'utilisateur dans le même fichier sont préservées ; seules les entrées agentmemory précédentes sont remplacées.
+
+<details>
+<summary><b>OpenClaw (collez ce prompt)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+Guide complet : [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (collez ce prompt)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Guide complet : [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### Autres agents
+
+Démarrez le serveur de mémoire : `npx @agentmemory/agentmemory`
+
+L'entrée agentmemory est le **même bloc serveur MCP** pour tous les hôtes utilisant le format `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw) :
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**Fusionnez cette entrée dans l'objet `mcpServers` existant** du fichier de config de l'hôte — ne remplacez pas le fichier. Si le fichier contient déjà d'autres serveurs, ajoutez `agentmemory` à côté d'eux comme nouvelle clé dans `mcpServers`. Si `mcpServers` est totalement absent, collez le bloc dans `{ "mcpServers": { ... } }`. Les placeholders `${VAR}` héritent de `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` depuis le shell au lancement du serveur MCP — des vars non définies passent des chaînes vides et le shim retombe sur `http://localhost:3111`. Une seule entrée câblée couvre à la fois les déploiements locaux et distants (k8s / reverse-proxy).
+
+| Agent | Fichier de config | Notes |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | Fusionner dans `mcpServers`. Deeplink en un clic également disponible sur le site web. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Fusionner dans `mcpServers`. Redémarrer Claude Desktop après modification. |
+| **Cline / Roo Code / Kilo Code** | Paramètres MCP de Cline (Settings UI → MCP Servers → Edit) | Même bloc `mcpServers`. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Même bloc `mcpServers`. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (fusion automatique). |
+| **OpenClaw** | Config MCP d'OpenClaw | Même bloc `mcpServers`, ou utilisez le [plugin mémoire plus poussé](../integrations/openclaw/). |
+| **Codex CLI (MCP seul)** | `.codex/config.toml` | Format TOML : `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, ou ajoutez `[mcp_servers.agentmemory]` à la main. |
+| **Codex CLI (plugin complet)** | Marketplace de plugins Codex | `codex plugin marketplace add rohitg00/agentmemory` puis `codex plugin add agentmemory@agentmemory`. Enregistre MCP + 6 hooks de cycle de vie (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills. Sur Codex Desktop, lancez également `agentmemory connect codex --with-hooks` en attendant que [openai/codex#16430](https://github.com/openai/codex/issues/16430) soit corrigé — les hooks de plugin y sont actuellement silencieux. |
+| **OpenCode (MCP seul)** | `opencode.json` | Format différent — clé `mcp` au niveau racine, commande sous forme de tableau : `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin complet)** | `plugin/opencode/` | 22 hooks de capture automatique couvrant cycle de vie de session, messages, outils, erreurs. Deux commandes slash (`/recall`, `/remember`). Copiez `plugin/opencode/` dans votre workspace OpenCode et ajoutez l'entrée du plugin à `opencode.json`. Voir [`plugin/opencode/README.md`](../plugin/opencode/README.md) pour le tableau complet des hooks et l'analyse des manques. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Copiez [`integrations/pi`](../integrations/pi/) et redémarrez pi. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Utilisez le [plugin de fournisseur de mémoire plus poussé](../integrations/hermes/) avec `memory.provider: agentmemory`. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` écrit le bloc `mcpServers` standard. La charge utile des hooks est compatible champ-à-champ avec Claude Code, donc les 12 scripts de hooks existants fonctionnent sans modification — câblez-les via la section `hooks` du même `settings.json`. |
+| **Antigravity** (remplace Gemini CLI) | `mcp_config.json` (dans le répertoire User d'Antigravity) | `agentmemory connect antigravity` écrit le bloc `mcpServers` standard. macOS : `~/Library/Application Support/Antigravity/User/`. Linux : `~/.config/Antigravity/User/`. À utiliser après l'arrêt de Gemini CLI au 2026-06-18. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` écrit la config au niveau utilisateur. Les overrides de workspace vont dans `.kiro/settings/mcp.json` à côté de votre code. |
+| **Goose** | UI des paramètres MCP de Goose | Même bloc `mcpServers`. |
+| **Aider** | n/a | Parlez directement à l'API REST : `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Tout agent (32+)** | n/a | `npx skillkit install agentmemory` détecte l'hôte automatiquement et fusionne. |
+
+**Clients MCP en sandbox** (Flatpak / Snap / conteneurs restrictifs) qui ne peuvent pas joindre le `localhost` de l'hôte : définissez également `"AGENTMEMORY_FORCE_PROXY": "1"` dans le bloc `env` et pointez `AGENTMEMORY_URL` vers une route que la sandbox peut effectivement atteindre (par ex. votre IP LAN). Voir [#234](https://github.com/rohitg00/agentmemory/issues/234) pour la démarche de diagnostic.
+
+### Accès programmatique (Python / Rust / Node)
+
+agentmemory enregistre ses opérations principales en tant que fonctions iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). N'importe quel langage doté d'un SDK iii peut les appeler directement sur `ws://localhost:49134` — pas besoin de client REST séparé par langage.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Exemple complet : [`examples/python/`](../examples/python/) (quickstart + flux observation/recall). REST sur `:3111` reste disponible pour les hôtes sans runtime iii.
+
+### Depuis les sources
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Cela démarre agentmemory avec un `iii-engine` local si `iii` est déjà installé, ou retombe sur Docker Compose si Docker est disponible. REST, streams et visualiseur se lient à `127.0.0.1` par défaut.
+
+Installer `iii-engine` manuellement. **agentmemory épingle actuellement `iii-engine` à `v0.11.2`** — `v0.11.6` introduit un nouveau modèle de sandboxing systématique via `iii worker add` pour lequel agentmemory n'a pas encore été refactorisé. L'épinglage sera levé une fois la refonte effectuée. Surchargez avec `AGENTMEMORY_III_VERSION=<version>` si vous avez migré au modèle sandbox manuellement.
+
+- **macOS arm64 :** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64 :** remplacez `aarch64-apple-darwin` par `x86_64-apple-darwin`
+- **Linux x64 :** remplacez par `x86_64-unknown-linux-gnu`
+- **Linux arm64 :** remplacez par `aarch64-unknown-linux-gnu`
+- **Windows :** téléchargez `iii-x86_64-pc-windows-msvc.zip` depuis [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extrayez `iii.exe`, ajoutez-le au PATH
+
+Ou utilisez Docker (le `docker-compose.yml` fourni tire `iiidev/iii:0.11.2`). Documentation complète : [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory tourne sur Windows 10/11, mais le paquet Node.js seul ne suffit pas — il vous faut aussi le runtime `iii-engine` (un binaire natif séparé) comme processus en arrière-plan. L'installeur amont officiel est un script `sh` et il n'existe à ce jour ni installeur PowerShell ni paquet scoop/winget, donc les utilisateurs Windows ont deux chemins :
+
+**Option A — Binaire Windows précompilé (recommandé) :**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe somewhere on PATH, or place it at:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory checks that location automatically)
+# 4. Verify:
+iii --version
+# Should print: 0.11.2
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**Option B — Docker Desktop :**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**Option C — MCP standalone uniquement (sans moteur) :** si vous n'avez besoin que des outils MCP pour votre agent et pas de l'API REST, du visualiseur ou des jobs cron, sautez le moteur :
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostics pour Windows :** si `npx @agentmemory/agentmemory` échoue, relancez avec `--verbose` pour voir le stderr réel du moteur. Modes de défaillance courants :
+
+| Symptôme | Correctif |
+|---|---|
+| `iii-engine process started` puis `did not become ready within 15s` | Le moteur a planté au démarrage — relancez avec `--verbose`, vérifiez stderr |
+| `Could not start iii-engine` | Ni `iii.exe` ni Docker installés. Voir les options A ou B ci-dessus |
+| Conflit de port | `netstat -ano \| findstr :3111` pour voir ce qui est lié, puis tuez-le ou utilisez `--port <N>` |
+| Fallback Docker ignoré bien que Docker soit installé | Assurez-vous que Docker Desktop tourne effectivement (icône de la barre d'état système) |
+
+> Note : il n'y a pas de `cargo install iii-engine` — `iii` n'est pas publié sur crates.io. Les seules méthodes d'installation supportées sont le binaire précompilé ci-dessus, le script d'installation amont en `sh` (macOS/Linux uniquement) et l'image Docker.
+
+---
+
+<h2 id="deploy">Déploiement</h2>
+
+Templates en un clic pour les hébergeurs managés. Chacun livre un Dockerfile
+autonome qui récupère `@agentmemory/agentmemory` depuis npm et copie le
+binaire iii engine depuis l'image officielle `iiidev/iii` du Docker
+Hub — pas d'image agentmemory précompilée requise. Le stockage
+persistant se monte sur `/data` ; le point d'entrée au premier
+démarrage réécrit la config iii livrée par npm (qui se lie à
+`127.0.0.1`) par une version réglée pour le déploiement qui se lie à
+`0.0.0.0` et utilise des chemins absolus `/data`, génère le secret HMAC,
+puis abaisse les privilèges de `root` à `node` via `gosu` avant
+d'exec'er la CLI agentmemory.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Le bouton de déploiement en un clic de Render exige un `render.yaml` à la racine du dépôt, que nous gardons délibérément propre. Utilisez le flux Render Blueprint documenté dans [`deploy/render/`](./deploy/render/README.md) pour pointer manuellement vers le blueprint dans le dépôt.
+
+Détails complets de configuration (capture HMAC, tunnel SSH du visualiseur, rotation, sauvegarde, plafonds de coût) dans [`deploy/`](./deploy/README.md) :
+
+- [`deploy/fly`](./deploy/fly/README.md) — machine unique avec
+  `auto_stop_machines = "stop"` ; le moins cher à l'arrêt.
+- [`deploy/railway`](./deploy/railway/README.md) — forfait Hobby à tarif fixe,
+  volume dans le tableau de bord.
+- [`deploy/render`](./deploy/render/README.md) — flux Blueprint,
+  snapshots disque automatiques sur les forfaits payants.
+- [`deploy/coolify`](./deploy/coolify/README.md) — auto-hébergé sur votre
+  propre VPS via [Coolify](https://coolify.io/self-hosted) ; même stack
+  Docker Compose, vous possédez l'hôte et les données.
+
+Seul le port `3111` est publié. Le visualiseur sur `3113` reste lié à la
+boucle locale dans le conteneur — chaque README de template documente
+le motif tunnel SSH pour y accéder.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Pourquoi agentmemory" height="32" /></picture></h2>
+
+Chaque agent de codage oublie tout quand la session se termine. Vous perdez les 5 premières minutes de chaque session à réexpliquer votre stack. agentmemory tourne en arrière-plan et élimine totalement cette perte.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### vs mémoire d'agent intégrée
+
+Chaque agent de codage IA est livré avec une mémoire intégrée — Claude Code a `MEMORY.md`, Cursor a des notepads, Cline a memory bank. Cela fonctionne comme des post-it. agentmemory est la base de données interrogeable derrière les post-it.
+
+| | Intégrée (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Échelle | Plafond de 200 lignes | Illimitée |
+| Recherche | Charge tout en contexte | BM25 + vecteur + graphe (top-K seul) |
+| Coût en tokens | 22K+ à 240 observations | ~1 900 tokens (92 % de moins) |
+| Inter-agents | Fichiers par agent | MCP + REST (n'importe quel agent) |
+| Coordination | Aucune | Leases, signaux, actions, routines |
+| Observabilité | Lire les fichiers à la main | Visualiseur temps réel sur :3113 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="Fonctionnement" height="32" /></picture></h2>
+
+### Pipeline mémoire
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### Consolidation mémoire à 4 niveaux
+
+Inspirée de la façon dont le cerveau humain traite la mémoire — pas si éloignée de la consolidation pendant le sommeil.
+
+| Niveau | Quoi | Analogie |
+|------|------|---------|
+| **Working** | Observations brutes issues de l'usage des outils | Mémoire à court terme |
+| **Episodic** | Résumés de session compressés | « Ce qui s'est passé » |
+| **Semantic** | Faits et motifs extraits | « Ce que je sais » |
+| **Procedural** | Workflows et motifs de décision | « Comment faire » |
+
+Les mémoires décroissent dans le temps (courbe d'Ebbinghaus). Les mémoires fréquemment consultées se renforcent. Les mémoires obsolètes sont évincées automatiquement. Les contradictions sont détectées et résolues.
+
+### Ce qui est capturé
+
+| Hook | Capture |
+|------|----------|
+| `SessionStart` | Chemin de projet, ID de session |
+| `UserPromptSubmit` | Prompts utilisateur (filtrés pour la vie privée) |
+| `PreToolUse` | Motifs d'accès fichier + contexte enrichi |
+| `PostToolUse` | Nom de l'outil, entrée, sortie |
+| `PostToolUseFailure` | Contexte d'erreur |
+| `PreCompact` | Réinjecte la mémoire avant compaction |
+| `SubagentStart/Stop` | Cycle de vie des sous-agents |
+| `Stop` | Résumé de fin de session |
+| `SessionEnd` | Marqueur de fin de session |
+
+### Capacités clés
+
+| Capacité | Description |
+|---|---|
+| **Capture automatique** | Chaque usage d'outil enregistré via hooks — zéro effort manuel |
+| **Recherche sémantique** | BM25 + vecteur + graphe de connaissances avec fusion RRF |
+| **Évolution de la mémoire** | Versioning, supersession, graphes de relations |
+| **Oubli automatique** | Expiration TTL, détection de contradictions, éviction par importance |
+| **Vie privée d'abord** | Clés d'API, secrets, balises `<private>` retirés avant stockage |
+| **Auto-réparation** | Circuit breaker, chaîne de repli de fournisseur, surveillance de santé |
+| **Pont Claude** | Synchronisation bidirectionnelle avec MEMORY.md |
+| **Graphe de connaissances** | Extraction d'entités + parcours BFS |
+| **Mémoire d'équipe** | Partagée + privée par namespace entre membres de l'équipe |
+| **Provenance des citations** | Tracer toute mémoire jusqu'aux observations sources |
+| **Snapshots git** | Version, rollback et diff de l'état mémoire |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Recherche" height="32" /></picture></h2>
+
+Récupération triple-flux combinant trois signaux :
+
+| Flux | Ce qu'il fait | Quand |
+|---|---|---|
+| **BM25** | Correspondance par mots-clés racinisés avec expansion par synonymes | Toujours actif |
+| **Vector** | Similarité cosinus sur embeddings denses | Fournisseur d'embedding configuré |
+| **Graph** | Parcours du graphe de connaissances par correspondance d'entités | Entités détectées dans la requête |
+
+Fusionnés par Reciprocal Rank Fusion (RRF, k=60) et diversifiés par session (max 3 résultats par session).
+
+BM25 tokenise nativement le grec, le cyrillique, l'hébreu, l'arabe et le latin accentué. Pour des mémoires en chinois / japonais / coréen, installez les segmenteurs optionnels (`npm install @node-rs/jieba tiny-segmenter`) afin de découper les suites CJK en tokens au niveau du mot ; sans eux, agentmemory retombe doucement sur une tokenisation par suite entière et imprime un message indicatif unique sur stderr.
+
+### Fournisseurs d'embedding
+
+agentmemory détecte automatiquement votre fournisseur. Pour de meilleurs résultats, installez les embeddings locaux (gratuits) :
+
+```bash
+npm install @xenova/transformers
+```
+
+| Fournisseur | Modèle | Coût | Notes |
+|---|---|---|---|
+| **Local (recommandé)** | `all-MiniLM-L6-v2` | Gratuit | Hors-ligne, +8 pp de rappel par rapport à BM25 seul |
+| Gemini | `gemini-embedding-001` | Niveau gratuit | 100+ langues, dimensions 768/1536/3072 (MRL), entrée 2048 tokens. Remplace `text-embedding-004` ([déprécié, arrêt le 14 jan. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | 0,02 $/1M | Meilleure qualité |
+| Voyage AI | `voyage-code-3` | Payant | Optimisé pour le code |
+| Cohere | `embed-english-v3.0` | Essai gratuit | Polyvalent |
+| OpenRouter | N'importe quel modèle | Variable | Proxy multi-modèles |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="Serveur MCP" height="32" /></picture></h2>
+
+53 outils, 6 ressources, 3 prompts et 4 skills — la boîte à outils mémoire MCP la plus complète pour tout agent.
+
+> **Shim MCP vs serveur complet :** le paquet publié `@agentmemory/mcp` est un shim léger. Il expose la surface complète de 51 outils **uniquement quand il peut joindre un serveur agentmemory actif** via `AGENTMEMORY_URL` (mode proxy). Sans serveur joignable, le shim retombe sur un jeu local de 7 outils (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). La variable d'env `AGENTMEMORY_TOOLS=core|all` est un drapeau *côté serveur* — la définir dans le bloc `env` du shim n'a aucun effet. Si vous ne voyez que 7 outils dans Cursor / OpenCode / Gemini CLI, lancez `npx @agentmemory/agentmemory` (ou la stack Docker) et définissez `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 51 outils
+
+<details>
+<summary>Outils de base (toujours disponibles)</summary>
+
+| Outil | Description |
+|------|-------------|
+| `memory_recall` | Rechercher dans les observations passées |
+| `memory_compress_file` | Compresser des fichiers markdown en préservant la structure |
+| `memory_save` | Sauvegarder un insight, une décision ou un motif |
+| `memory_patterns` | Détecter des motifs récurrents |
+| `memory_smart_search` | Recherche hybride sémantique + mots-clés |
+| `memory_file_history` | Observations passées sur des fichiers spécifiques |
+| `memory_sessions` | Lister les sessions récentes |
+| `memory_timeline` | Observations chronologiques |
+| `memory_profile` | Profil de projet (concepts, fichiers, motifs) |
+| `memory_export` | Exporter toutes les données mémoire |
+| `memory_relations` | Interroger le graphe de relations |
+
+</details>
+
+<details>
+<summary>Outils étendus (51 au total — définissez AGENTMEMORY_TOOLS=all)</summary>
+
+| Outil | Description |
+|------|-------------|
+| `memory_patterns` | Détecter des motifs récurrents |
+| `memory_timeline` | Observations chronologiques |
+| `memory_relations` | Interroger le graphe de relations |
+| `memory_graph_query` | Parcours du graphe de connaissances |
+| `memory_consolidate` | Lancer la consolidation à 4 niveaux |
+| `memory_claude_bridge_sync` | Synchroniser avec MEMORY.md |
+| `memory_team_share` | Partager avec les membres de l'équipe |
+| `memory_team_feed` | Éléments partagés récemment |
+| `memory_audit` | Piste d'audit des opérations |
+| `memory_governance_delete` | Supprimer avec piste d'audit |
+| `memory_snapshot_create` | Snapshot versionné git |
+| `memory_action_create` | Créer des éléments de travail avec dépendances |
+| `memory_action_update` | Mettre à jour le statut d'une action |
+| `memory_frontier` | Actions débloquées classées par priorité |
+| `memory_next` | Seule action suivante la plus importante |
+| `memory_lease` | Leases d'action exclusifs (multi-agents) |
+| `memory_routine_run` | Instancier des routines de workflow |
+| `memory_signal_send` | Messagerie inter-agents |
+| `memory_signal_read` | Lire des messages avec accusés |
+| `memory_checkpoint` | Portes de condition externes |
+| `memory_mesh_sync` | Sync P2P entre instances |
+| `memory_sentinel_create` | Watchers événementiels |
+| `memory_sentinel_trigger` | Déclencher des sentinelles depuis l'extérieur |
+| `memory_sketch_create` | Graphes d'action éphémères |
+| `memory_sketch_promote` | Promouvoir en permanent |
+| `memory_crystallize` | Compacter les chaînes d'actions |
+| `memory_diagnose` | Vérifications de santé |
+| `memory_heal` | Auto-correction d'état bloqué |
+| `memory_facet_tag` | Tags dimension:valeur |
+| `memory_facet_query` | Interroger par tags de facettes |
+| `memory_verify` | Tracer la provenance |
+
+</details>
+
+### 6 Ressources · 3 Prompts · 4 Skills
+
+| Type | Nom | Description |
+|------|------|-------------|
+| Ressource | `agentmemory://status` | Santé, nombre de sessions, nombre de mémoires |
+| Ressource | `agentmemory://project/{name}/profile` | Intelligence par projet |
+| Ressource | `agentmemory://memories/latest` | 10 dernières mémoires actives |
+| Ressource | `agentmemory://graph/stats` | Statistiques du graphe de connaissances |
+| Prompt | `recall_context` | Recherche + retour de messages de contexte |
+| Prompt | `session_handoff` | Données de passation entre agents |
+| Prompt | `detect_patterns` | Analyser les motifs récurrents |
+| Skill | `/recall` | Rechercher la mémoire |
+| Skill | `/remember` | Sauvegarder en mémoire long-terme |
+| Skill | `/session-history` | Résumés de sessions récentes |
+| Skill | `/forget` | Supprimer observations / sessions |
+
+### MCP autonome
+
+Tourne sans le serveur complet — pour n'importe quel client MCP. L'une ou l'autre marche :
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (always available)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+Ou ajoutez à la config MCP de votre agent :
+
+La plupart des agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI) :
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+Fusionnez l'entrée `agentmemory` dans l'objet `mcpServers` existant de votre hôte plutôt que de remplacer le fichier. Pour des clients en sandbox qui ne peuvent pas joindre le `localhost` de l'hôte, ajoutez `"AGENTMEMORY_FORCE_PROXY": "1"` au bloc env et pointez `AGENTMEMORY_URL` vers une route que la sandbox peut atteindre.
+
+OpenCode (`opencode.json`) :
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copiez le fichier plugin depuis le dépôt :
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Visualiseur temps réel" height="32" /></picture></h2>
+
+Démarre automatiquement sur le port `3113`. Flux d'observations en direct, explorateur de sessions, navigateur mémoire, visualisation du graphe de connaissances et tableau de bord de santé.
+
+```bash
+open http://localhost:3113
+```
+
+Le serveur du visualiseur se lie à `127.0.0.1` par défaut. Le point d'entrée `/agentmemory/viewer` servi par REST suit les règles normales de bearer-token `AGENTMEMORY_SECRET`. Les en-têtes CSP utilisent un nonce de script par réponse et désactivent les attributs gestionnaires inline (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+Le visualiseur sur `:3113` montre ce que votre agent **a mémorisé**. La [iii console](https://iii.dev/docs/console) montre ce que votre agent **a fait** — chaque op mémoire comme trace OpenTelemetry, chaque entrée KV éditable, chaque fonction invocable, chaque flux taps-able. Deux fenêtres sur la même mémoire : l'une orientée produit, l'autre orientée moteur.
+
+Regardez un `memory_smart_search` se déclencher et voyez le scan BM25 → recherche d'embeddings → fusion RRF → reranker comme un waterfall. Éditez un timer de consolidation bloqué dans le navigateur KV. Rejouez un hook `PostToolUse` avec une charge utile modifiée. ��pinglez le flux WebSocket et regardez les observations arriver en direct.
+
+agentmemory livre cela gratuitement parce que chaque fonction, trigger, scope d'état et flux est une primitive iii — rien de personnalisé, rien à instrumenter.
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console — page Workers montrant les workers connectés, dont les instances agentmemory avec compteurs de fonctions en direct et métadonnées de runtime" width="720" />
+  <br/>
+  <em>Page Workers : chaque worker connecté — y compris agentmemory lui-même — avec PID, nombre de fonctions, runtime et last-seen.</em>
+</p>
+
+**Déjà installé.** La console est livrée avec `iii` — pas d'installeur séparé.
+
+**Lancer aux côtés d'agentmemory :**
+
+```bash
+# agentmemory viewer holds port 3113, so run the console on 3114.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
+```
+
+Puis ouvrez `http://localhost:3114`. Ajoutez `--enable-flow` pour la page expérimentale de graphe d'architecture.
+
+Surchargez les endpoints du moteur uniquement si vous les avez déplacés :
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**Ce que vous pouvez faire depuis la console :**
+
+| Page | Pour |
+|------|-----------|
+| **Workers** | Voir chaque worker connecté et ses métriques en direct — y compris le worker agentmemory lui-même. |
+| **Functions** | Invoquer n'importe quelle fonction d'agentmemory avec une charge utile JSON — pratique pour tester `memory.recall`, `memory.consolidate`, `graph.query` sans câbler un client. |
+| **Triggers** | Rejouer les triggers HTTP, cron, event et state — déclencher manuellement le cron de consolidation, retenter une route HTTP, émettre un changement d'état. |
+| **States** | Navigateur KV avec CRUD complet — sessions, slots mémoire, timers de cycle de vie, index d'embeddings — éditer les valeurs sur place. |
+| **Streams** | Moniteur WebSocket en direct pour les écritures mémoire, événements de hooks et mises à jour d'observations à mesure qu'ils circulent dans les iii streams. |
+| **Queues** | Topics de files durables + gestion de la dead-letter. Rejouer ou abandonner les jobs d'embedding / compression échoués. |
+| **Traces** | Vues waterfall / flame / décomposition par service OpenTelemetry. Filtrez par `trace_id` pour voir exactement quelles fonctions, appels DB et requêtes d'embedding une seule `memory.search` a produits. |
+| **Logs** | Logs OTEL structurés filtrés et corrélés aux IDs de trace/span. |
+| **Config** | Configuration runtime — voir exactement quels workers, fournisseurs et ports tourne votre moteur. |
+| **Flow** | (Optionnel, `--enable-flow`) Graphe d'architecture interactif de chaque worker, trigger et flux. |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="vue waterfall de traces dans iii console montrant la durée par span" width="720" />
+  <br/>
+  <em>Traces : waterfall / flame / décomposition par service pour chaque opération mémoire.</em>
+</p>
+
+**Les traces sont déjà actives :**
+
+`iii-config.yaml` est livré avec le worker `iii-observability` activé (`exporter: memory`, `sampling_ratio: 1.0`, métriques + logs). Aucune config supplémentaire — dès qu'agentmemory démarre, chaque opération mémoire émet un span de trace et un log structuré que la console peut lire.
+
+Si vous voulez exporter vers Jaeger/Honeycomb/Grafana Tempo à la place, changez `exporter: memory` en `exporter: otlp` et définissez l'endpoint du collecteur selon la documentation d'observabilité d'iii.
+
+> **Attention :** aucune auth n'est appliquée sur la console elle-même — gardez-la liée à `127.0.0.1` (par défaut) et ne l'exposez jamais publiquement.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory est **déjà une instance [iii](https://iii.dev) en cours d'exécution**. Fonctions, triggers, état KV, flux, traces OTEL — tout est primitive iii. Vous n'avez pas installé Postgres, Redis, Express, pm2, ni Prometheus, parce qu'iii les remplace.
+
+Cela signifie qu'une commande supplémentaire étend agentmemory d'une toute nouvelle capacité.
+
+### Étendez agentmemory avec une seule commande
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+Chaque `iii worker add` enregistre de nouvelles fonctions et triggers dans le même moteur sur lequel agentmemory tourne déjà. Le visualiseur et la console les prennent en compte immédiatement — sans rechargement, sans nouvelle intégration, sans nouveau conteneur.
+
+| `iii worker add` | Ce que vous obtenez en plus d'agentmemory |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Mémoire multi-instances : chaque `remember` se diffuse, chaque `search` lit l'union |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Cycle de vie planifié — consolidation nocturne, snapshots hebdomadaires, décroissance sur horloge fixe |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Retries durables : les jobs d'embedding + compression en échec survivent au redémarrage, aucune observation perdue |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | Traces, métriques et logs OTEL sur chaque fonction — câblés dans `iii-config.yaml` dès le premier jour |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Le code issu de `memory_recall` s'exécute dans une VM jetable, pas dans votre shell |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | Adaptateur d'état adossé à SQL lorsque vous dépassez les valeurs par défaut KV en mémoire |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Déployez des serveurs MCP supplémentaires à côté de celui d'agentmemory, partageant le même moteur |
+
+Registre complet : [workers.iii.dev](https://workers.iii.dev). Chaque worker là-bas se compose via les mêmes primitives qu'utilise agentmemory — et l'agentmemory que vous avez déjà en est un.
+
+### Ce qu'iii remplace
+
+| Stack traditionnelle | agentmemory utilise |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + index vectoriel en mémoire |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | Supervision de workers du moteur iii |
+| Prometheus / Grafana | iii OTEL + moniteur de santé |
+| Systèmes de plugins personnalisés | `iii worker add <name>` |
+
+**118 fichiers sources · ~21 800 LOC · 950+ tests · 123 fonctions · 34 scopes KV** — tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### Fournisseurs LLM
+
+agentmemory détecte automatiquement depuis votre environnement. Par défaut, aucun appel LLM n'est effectué tant que vous n'avez pas configuré de fournisseur ou explicitement opté pour le fallback abonnement Claude.
+
+| Fournisseur | Config | Notes |
+|----------|--------|-------|
+| **No-op (par défaut)** | Aucune config nécessaire | Le compress/summarize adossé à un LLM est DÉSACTIVÉ. La compression et le recall BM25 synthétiques fonctionnent toujours. Voir `AGENTMEMORY_ALLOW_AGENT_SDK` ci-dessous si vous comptiez sur le fallback abonnement Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Facturation au token |
+| MiniMax | `MINIMAX_API_KEY` | Compatible Anthropic |
+| Gemini | `GEMINI_API_KEY` | Active aussi les embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | N'importe quel modèle |
+| Fallback abonnement Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in seulement. Engendre des sessions `@anthropic-ai/claude-agent-sdk` — provoquait une récursion non bornée du Stop-hook (suite de #149), il n'est plus l'option par défaut. |
+
+### Sélection de modèle attentive au coût
+
+La compression en arrière-plan tourne sur chaque observation, donc le choix du modèle influence sensiblement la dépense mensuelle. Données de charge capturées : 635 requêtes / 888K tokens / 35 heures d'usage actif, exécutées contre trois modèles OpenRouter au tarif du 2026-05-23.
+
+| Niveau | Modèle | Entrée / 1M | Sortie / 1M | Coût pour les 35h capturées | Notes |
+|------|-------|------------|-------------|---------------------------|-------|
+| Recommandé | `deepseek/deepseek-v4-pro` | 0,435 $ | 0,87 $ | ~0,46 $ | Qualité de compression + résumé solide à un coût ~10× moindre que Sonnet. |
+| Recommandé | `deepseek/deepseek-chat` | 0,27 $ | 1,10 $ | ~0,40 $ | Plus ancien mais toujours satisfaisant pour des charges de compression uniquement. |
+| Recommandé | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Solide raisonnement code si vos sessions sont fortement code-shaped. |
+| Premium | `anthropic/claude-sonnet-4.6` | 3,00 $ | 15,00 $ | ~5,02 $ | Haute qualité mais coûteux pour du travail de fond permanent. |
+| Premium | `openai/gpt-4o` | 2,50 $ | 10,00 $ | ~4,20 $ | Niveau similaire à Sonnet. |
+| À éviter | `anthropic/claude-opus-4.6` | 15,00 $ | 75,00 $ | ~25+ $ | Modèle classe raisonnement ; surcoût massif pour de la compression. |
+
+agentmemory imprime un avertissement runtime quand `OPENROUTER_MODEL` correspond à un motif de niveau premium. Définissez `AGENTMEMORY_SUPPRESS_COST_WARNING=1` pour le faire taire une fois votre choix éclairé.
+
+Compromis qualité vs coût pour le travail mémoire : la compression est une tâche de résumé avec des exigences de qualité relativement souples (c'est l'agent qui relit le résumé, pas l'utilisateur). DeepSeek-V4-Pro / Qwen3-Coder se situent à la précision d'arrondi près de Sonnet sur cette tâche tout en coûtant ~10× moins. Réservez les modèles premium aux requêtes que vous lisez directement.
+
+Sources : [tarification OpenRouter pour Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [notes de prix DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Mémoire multi-agents (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Dans des configurations multi-agents où plusieurs rôles partagent un même serveur agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` marque chaque écriture avec le rôle qui l'a produite. `AGENTMEMORY_AGENT_SCOPE` contrôle si le recall filtre par ce tag.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+Deux modes :
+
+| Mode | Marquer les écritures | Filtrer le recall | Quand l'utiliser |
+|------|------------|---------------|-------------|
+| `shared` (par défaut) | oui | non | Contexte inter-agents avec piste d'audit. L'architect voit ce que le developer a noté, mais chaque ligne enregistre qui l'a dit. |
+| `isolated` | oui | oui | Séparation stricte. L'architect ne voit jamais les observations / mémoires / sessions du developer. |
+
+Ce qui est marqué quand `AGENT_ID` est défini : `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Le rôle circule de `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Ce qui est filtré en mode isolé : `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Chaque endpoint accepte `?agentId=<role>` pour surcharger par requête, et `?agentId=*` pour se désinscrire entièrement du scope de l'env. `/memories` accepte aussi `?includeOrphans=true` pour faire remonter les mémoires antérieures à AGENT_ID dont `agentId` est indéfini.
+
+Surcharge par appel au niveau SDK / REST : chaque endpoint mutant (`/session/start`, `/remember`) accepte un champ `agentId` dans le corps de la requête qui gagne sur l'env. Utile pour des runtimes qui routent plusieurs rôles à travers un même processus serveur.
+
+Quand `AGENT_ID` n'est pas défini, la mémoire reste non scopée (comportement legacy, sans tags ni filtres).
+
+### Ports
+
+agentmemory + iii-engine se lient à quatre ports par défaut. Si un redémarrage échoue avec `port in use`, ce tableau vous indique le processus à chercher.
+
+| Port | Processus | Usage | Surcharge env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | API REST + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker streams interne (consommé par agentmemory + visualiseur) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Visualiseur temps réel (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — les workers s'y enregistrent, la télémétrie OTel y circule | `III_ENGINE_URL` (URL complète, défaut `ws://localhost:49134`) |
+
+Nettoyage de processus zombies quand des ports restent occupés après un crash :
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` réclame proprement à la fois le worker et le pidfile du moteur en arrêt gracieux (#640, #474). Le nettoyage manuel ci-dessus n'est nécessaire que pour le cas post-crash où aucun pidfile n'est laissé en place.
+
+### Fichier de configuration
+
+Mettez la configuration runtime d'agentmemory dans `~/.agentmemory/.env` au lieu d'exporter des variables dans chaque shell. Si le visualiseur affiche un indice de setup comme `export ANTHROPIC_API_KEY=...`, recopiez-le dans ce fichier sous la forme `ANTHROPIC_API_KEY=...` sans le préfixe `export`, puis redémarrez agentmemory.
+
+Les variables d'environnement du processus restent valides et prennent le pas sur les valeurs du fichier.
+
+Sur Windows, le même fichier se trouve dans `%USERPROFILE%\.agentmemory\.env` :
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Pour tester avec un abonnement Claude Code Pro/Max au lieu d'une clé d'API, optez-vous explicitement :
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Activez les fonctionnalités de graphe ou de consolidation dans le même fichier si vous les voulez :
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### Variables d'environnement
+
+Créez `~/.agentmemory/.env` :
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+124 endpoints sur le port `3111`. L'API REST se lie à `127.0.0.1` par défaut. Les endpoints protégés exigent `Authorization: Bearer <secret>` lorsque `AGENTMEMORY_SECRET` est défini, et les endpoints de mesh sync exigent `AGENTMEMORY_SECRET` sur les deux pairs.
+
+<details>
+<summary>Endpoints clés</summary>
+
+| Méthode | Chemin | Description |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Vérification de santé (toujours publique) |
+| `POST` | `/agentmemory/session/start` | Démarrer une session + obtenir le contexte |
+| `POST` | `/agentmemory/session/end` | Terminer une session |
+| `POST` | `/agentmemory/observe` | Capturer une observation |
+| `POST` | `/agentmemory/smart-search` | Recherche hybride |
+| `POST` | `/agentmemory/context` | Générer du contexte |
+| `POST` | `/agentmemory/remember` | Sauvegarder en mémoire long-terme |
+| `POST` | `/agentmemory/forget` | Supprimer des observations |
+| `POST` | `/agentmemory/enrich` | Contexte de fichier + mémoires + bugs |
+| `GET` | `/agentmemory/profile` | Profil de projet |
+| `GET` | `/agentmemory/export` | Exporter toutes les données |
+| `POST` | `/agentmemory/import` | Importer depuis JSON |
+| `POST` | `/agentmemory/graph/query` | Requête sur le graphe de connaissances |
+| `POST` | `/agentmemory/team/share` | Partager avec l'équipe |
+| `GET` | `/agentmemory/audit` | Piste d'audit |
+
+Liste complète des endpoints : [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Développement" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ tests
+npm run test:integration  # API tests (requires running services)
+```
+
+**Prérequis :** Node.js >= 20, [iii-engine](https://iii.dev/docs) ou Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licence" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.hi-IN.md

@@ -0,0 +1,1380 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — AI कोडिंग एजेंट्स के लिए स्थायी मेमोरी" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    आपका कोडिंग एजेंट सब कुछ याद रखता है। बार-बार समझाने की ज़रूरत नहीं।
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, और किसी भी MCP क्लाइंट के लिए स्थायी मेमोरी।
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  हिन्दी |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1200 stars / 172 forks on the gist" /></a>
+</p>
+
+<p align="center">
+  <em>यह gist Karpathy के LLM Wiki पैटर्न को confidence scoring, lifecycle, knowledge graphs और hybrid search के साथ बढ़ाता है: agentmemory इसका implementation है।</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">इंस्टॉल</a> &bull;
+  <a href="#quick-start">क्विक स्टार्ट</a> &bull;
+  <a href="#benchmarks">बेंचमार्क्स</a> &bull;
+  <a href="#vs-competitors">प्रतिस्पर्धियों से तुलना</a> &bull;
+  <a href="#works-with-every-agent">एजेंट्स</a> &bull;
+  <a href="#how-it-works">यह कैसे काम करता है</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">व्यूअर</a> &bull;
+  <a href="#iii-console">iii कंसोल</a> &bull;
+  <a href="#powered-by-iii">iii द्वारा संचालित</a> &bull;
+  <a href="#configuration">कॉन्फ़िग</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## इंस्टॉल
+
+```bash
+npm install -g @agentmemory/agentmemory          # एक बार — PATH पर `agentmemory` कमांड उपलब्ध
+# अगर macOS/Linux सिस्टम Node इंस्टॉल पर EACCES त्रुटि आती है, तो इसके साथ फिर से चलाएँ:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # :3111 पर मेमोरी सर्वर शुरू करें
+agentmemory demo                                 # नमूना सेशंस सीड करें + recall साबित करें
+agentmemory connect claude-code                  # अपना एजेंट जोड़ें (अन्य: codex, cursor, gemini-cli, ...)
+```
+
+या `npx` के माध्यम से (इंस्टॉल की ज़रूरत नहीं):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+ध्यान दें — npx प्रति-वर्ज़न कैश करता है। अगर बेयर `npx @agentmemory/agentmemory` कोई पुराना रिलीज़ चला रहा है, तो नवीनतम को `npx -y @agentmemory/agentmemory@latest` से ज़बरदस्ती चलाएँ, या एक बार `rm -rf ~/.npm/_npx` से कैश साफ़ करें (macOS/Linux; Windows पर `%LOCALAPPDATA%\npm-cache\_npx` हटाएँ)। v0.9.16+ के बाद पहली npx रन आपको इनलाइन ग्लोबल इंस्टॉल करने का प्रॉम्प्ट देती है ताकि बेयर `agentmemory` कमांड हर जगह काम करे।
+
+पूर्ण विकल्प नीचे [क्विक स्टार्ट](#quick-start) में हैं। एजेंट-विशिष्ट कॉन्फ़िगरेशन [हर एजेंट के साथ काम करता है](#works-with-every-agent) में।
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
+
+agentmemory किसी भी ऐसे एजेंट के साथ काम करता है जो hooks, MCP, या REST API सपोर्ट करता है। सभी एजेंट एक ही मेमोरी सर्वर साझा करते हैं।
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>native plugin + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>native plugin + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>native Memory trait बैकएंड</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP सर्वर</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>MCP या HTTP बोलने वाले <strong>किसी भी</strong> एजेंट के साथ काम करता है। एक सर्वर, सभी के बीच साझा मेमोरी।</sub>
+</p>
+
+---
+
+आप हर सेशन में वही आर्किटेक्चर समझाते हैं। आप वही bugs बार-बार खोजते हैं। आप वही प्राथमिकताएँ फिर से सिखाते हैं। बिल्ट-इन मेमोरी (CLAUDE.md, .cursorrules) 200 लाइनों पर सीमित है और पुरानी हो जाती है। agentmemory इसे ठीक करता है। यह चुपचाप आपके एजेंट की गतिविधियाँ कैप्चर करता है, उन्हें खोज योग्य मेमोरी में संकुचित करता है, और अगला सेशन शुरू होने पर सही संदर्भ इंजेक्ट करता है। एक कमांड। सभी एजेंट्स के साथ काम करता है।
+
+**क्या बदलता है:** सेशन 1 में आप JWT auth सेटअप करते हैं। सेशन 2 में आप rate limiting माँगते हैं। एजेंट को पहले से पता है कि आपकी auth `src/middleware/auth.ts` में jose middleware का उपयोग करती है, आपके tests token validation को कवर करते हैं, और आपने Edge compatibility के लिए jsonwebtoken के बजाय jose चुना है। फिर से समझाना नहीं। कॉपी-पेस्ट नहीं। एजेंट बस *जानता है*।
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **v0.9.0 में नया** — लैंडिंग साइट [agent-memory.dev](https://agent-memory.dev), फाइलसिस्टम कनेक्टर (`@agentmemory/fs-watcher`), स्टैंडअलोन MCP अब चल रहे सर्वर को प्रॉक्सी करता है ताकि hooks और व्यूअर सहमत हों, हर delete path में audit policy कोडिफाई की गई, small Node प्रक्रियाओं पर health अब `memory_critical` फ़्लैग नहीं करता। पूरे नोट्स [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18) में।
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Retrieval सटीकता
+
+**coding-agent-life-v1** (in-house corpus, sandbox-reproducible)
+
+| Adapter | P@5 | R@5 | Top-5 hit rate | p50 latency |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep baseline | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+100% top-5 hit rate। समान input पर grep baseline से **2.2×** बेहतर precision। पूरी प्रकार-वार breakdown: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md)।
+
+**LongMemEval-S** (ICLR 2025, 500 प्रश्न)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Token बचत
+
+| दृष्टिकोण | Tokens/yr | Cost/yr |
+|---|---|---|
+| पूरा context paste करें | 19.5M+ | असंभव (window से अधिक) |
+| LLM-summarized | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + local embeddings | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> Embedding मॉडल: `all-MiniLM-L6-v2` (local, free, कोई API key नहीं)। पूरी रिपोर्ट्स: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md)। प्रतिस्पर्धी तुलना: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory बनाम mem0, Letta, Khoj, claude-mem, Hippo।
+
+**स्थानीय रूप से reproduce करें:** [`eval/README.md`](../eval/README.md) — LongMemEval `_s` (public 500-Q) + `coding-agent-life-v1` (in-house 15-session corpus) के लिए adapter-pluggable harness। Grep / vector / agentmemory adapters साथ-साथ scored होते हैं, NDJSON output, प्रकाशित scorecards [`docs/benchmarks/`](../docs/benchmarks/) में जाते हैं।
+
+**[codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), और [Graphify](https://github.com/safishamsi/graphify) के साथ जोड़ता है।** Code-graph indexing, multi-agent build pipelines, और docs / PDFs / images / videos में व्यापक knowledge graphs। agentmemory काम याद रखता है; ये तीन प्रोजेक्ट्स context layer के बाकी हिस्से को रोशन करते हैं। Recipes + question-routing table: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md)।
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="vs Competitors" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">बिल्ट-इन (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>प्रकार</strong></td>
+<td>Memory engine + MCP सर्वर</td>
+<td>Memory layer API</td>
+<td>पूर्ण agent runtime</td>
+<td>Static फाइल</td>
+</tr>
+<tr>
+<td><strong>Retrieval R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>स्वचालित कैप्चर</strong></td>
+<td>12 hooks (शून्य मैनुअल प्रयास)</td>
+<td>मैनुअल <code>add()</code> कॉल</td>
+<td>एजेंट self-edits</td>
+<td>मैनुअल editing</td>
+</tr>
+<tr>
+<td><strong>खोज</strong></td>
+<td>BM25 + Vector + Graph (RRF fusion)</td>
+<td>Vector + Graph</td>
+<td>Vector (archival)</td>
+<td>सब कुछ context में लोड करता है</td>
+</tr>
+<tr>
+<td><strong>Multi-agent</strong></td>
+<td>MCP + REST + leases + signals</td>
+<td>API (कोई coordination नहीं)</td>
+<td>केवल Letta runtime में</td>
+<td>प्रति-एजेंट फाइलें</td>
+</tr>
+<tr>
+<td><strong>Framework lock-in</strong></td>
+<td>कोई नहीं (कोई भी MCP क्लाइंट)</td>
+<td>कोई नहीं</td>
+<td>उच्च (Letta का उपयोग आवश्यक)</td>
+<td>प्रति-ए��ेंट format</td>
+</tr>
+<tr>
+<td><strong>बाहरी निर्भरताएँ</strong></td>
+<td>कोई नहीं (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + vector DB</td>
+<td>कोई नहीं</td>
+</tr>
+<tr>
+<td><strong>Memory lifecycle</strong></td>
+<td>4-tier consolidation + decay + auto-forget</td>
+<td>Passive extraction</td>
+<td>Agent-managed</td>
+<td>मैनुअल pruning</td>
+</tr>
+<tr>
+<td><strong>Token दक्षता</strong></td>
+<td>~1,900 tokens/session ($10/yr)</td>
+<td>integration पर निर्भर</td>
+<td>Core memory context में</td>
+<td>240 observations पर 22K+ tokens</td>
+</tr>
+<tr>
+<td><strong>Real-time व्यूअर</strong></td>
+<td>हाँ (port 3113)</td>
+<td>Cloud dashboard</td>
+<td>Cloud dashboard</td>
+<td>नहीं</td>
+</tr>
+<tr>
+<td><strong>Self-hosted</strong></td>
+<td>हाँ (default)</td>
+<td>Optional</td>
+<td>Optional</td>
+<td>हाँ</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
+
+संगतता: यह रिलीज़ stable `iii-sdk` `^0.11.0` और iii-engine v0.11.x को टार्गेट करता है।
+
+### 30 सेकंड में आज़माएँ
+
+```bash
+# Terminal 1: सर्वर शुरू करें
+npx @agentmemory/agentmemory
+
+# Terminal 2: नमूना डेटा सीड करें और recall को कार्य में देखें
+npx @agentmemory/agentmemory demo
+```
+
+`demo` 3 यथार्थवादी सेशंस सीड करता है (JWT auth, N+1 query fix, rate limiting) और उन पर semantic searches चलाता है। जब आप "database performance optimization" खोजते हैं तो आप देखेंगे कि यह "N+1 query fix" ढूँढ़ लेता है — keyword matching ऐसा नहीं कर सकती।
+
+मेमोरी को लाइव बनते हुए देखने के लिए `http://localhost:3113` खोलें।
+
+### अनुशंसित: globally इंस्टॉल करें
+
+`npx` per-version कैश करता है। अगर आपने पिछले हफ्ते `npx @agentmemory/agentmemory@0.9.14` चलाया था, तो एक बेयर `npx @agentmemory/agentmemory` `~/.npm/_npx/` से stale 0.9.14 दे सकता है, न कि नवीनतम रिलीज़। एक बार इंस्टॉल करें और बेयर `agentmemory` कमांड हर जगह काम करता है:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# अगर macOS/Linux सिस्टम Node इंस्टॉल पर EACCES त्रुटि आती है, इसके साथ फिर से चलाएँ:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # सर्वर शुरू करें (npx form के समान)
+agentmemory stop               # बंद करें
+agentmemory remove             # हमने जो भी बनाया उसे अनइंस्टॉल करें
+agentmemory connect claude-code   # एक एजेंट जोड़ें
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+v0.9.16 के बाद से, पहली npx रन आपको inline globally इंस्टॉल करने का प्रॉम्प्ट देती है — एक बार `Y` जवाब दें और तैयार। अगर आप skip करते हैं, तो ताज़ा fetch के लिए इनमें से किसी पर भी fallback करें:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # npm से नवीनतम को force करता है (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # केवल macOS/Linux (POSIX shell)
+```
+
+Windows / PowerShell पर, समतुल्य cache clear है `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — ऊपर का `npx -y ...@latest` form cross-platform विकल्प है।
+
+### Session Replay
+
+agentmemory द्वारा रिकॉर्ड किया गया हर सेशन replayable है। व्यूअर खोलें, **Replay** टैब चुनें, और timeline scrub करें: prompts, tool calls, tool results, और responses अलग events के रूप में render होते हैं, play/pause, speed control (0.5×–4×), और keyboard shortcuts (space toggle के लिए, arrows step के लिए) के साथ।
+
+क्या आपके पास पहले से पुर���नी Claude Code JSONL transcripts हैं जिन्हें आप लाना चाहते हैं?
+
+```bash
+# डिफ़ॉल्ट ~/.claude/projects के तहत सब कुछ import करें
+npx @agentmemory/agentmemory import-jsonl
+
+# या एक अकेली फाइल import करें
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Imported सेशंस native ones के साथ Replay picker में दिखते हैं। हुड के नीचे प्रत्येक entry `mem::replay::load`, `mem::replay::sessions`, और `mem::replay::import-jsonl` iii functions के माध्यम से रूट होती है — कोई side-channel servers नहीं।
+
+### Upgrade / Maintenance
+
+जब आप जानबूझकर अपने local runtime को update करना चाहते हैं तो maintenance command का उपयोग करें:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+चेतावनी: यह कमांड वर्तमान workspace/runtime को mutate करता है। यह JavaScript निर्भरताएँ update कर सकता है, `cargo install iii-engine --force` चला सकता है, और Docker images खींच सकता है।
+
+Implementation विवरण `src/cli.ts` में हैं (`src/cli.ts:544-595` क्षेत्र के आसपास `runUpgrade` देखें)।
+
+### Claude Code (एक block, paste करें)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Plugin install के बिना Claude Code (MCP-standalone path)
+
+अगर आप `/plugin install` का उपयोग करने के बजाय `~/.claude.json` के माध्यम से सीधे agentmemory का MCP सर्वर कनेक्ट करते हैं, तो Claude Code कभी भी `${CLAUDE_PLUGIN_ROOT}` resolve नहीं करता और आपको hook scripts को `~/.claude/settings.json` में absolute paths पर point करना पड़ता है। ये paths आमतौर पर agentmemory version को embed करते हैं (जैसे `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), इसलिए अगला upgrade चुपचाप हर hook को तोड़ देता है ([#508](https://github.com/rohitg00/agentmemory/issues/508))।
+
+Workaround:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+यह वही hook commands को `~/.claude/settings.json` में merge करता है, current installed `@agentmemory/agentmemory` package की bundled `plugin/` directory पर resolve किए गए absolute paths के साथ। agentmemory upgrade करने के बाद paths refresh करने के लिए कमांड फिर से चलाएँ। उसी फाइल में user entries संरक्षित होती हैं; केवल पिछली agentmemory entries replace होती हैं। `/plugin install` path अनुशंसित approach बनी रहती है।
+Remote या protected deployments के लिए, Claude Code को `AGENTMEMORY_URL` और `AGENTMEMORY_SECRET` set के साथ launch करें। Plugin दोनों values को इसके bundled MCP सर्वर के माध्यम से pass करता है; जब `AGENTMEMORY_URL` खाली होता है, तो MCP shim `http://localhost:3111` का उपयोग करता है।
+
+### Codex CLI (Codex plugin platform)
+
+```bash
+# 1. एक अलग terminal में memory सर्वर शुरू करें
+npx @agentmemory/agentmemory
+
+# 2. agentmemory marketplace register करें और plugin install करें
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex plugin उसी `plugin/` directory से ship होता है जिससे Claude Code plugin। यह register करता है:
+
+- `@agentmemory/mcp` MCP सर्वर के रूप में (जब `AGENTMEMORY_URL` चल रहे agentmemory सर्वर पर point करता है, तो सभी 51 tools proxy करता है; कोई पहुँच योग्य सर्वर �� होने पर locally 7 tools पर fallback करता है)
+- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 skills: `/recall`, `/remember`, `/session-history`, `/forget`
+
+Codex का hook engine hook subprocesses में `CLAUDE_PLUGIN_ROOT` inject करता है ([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs) के अनुसार), इसलिए वही hook scripts duplication के बिना दोनों hosts में काम करते हैं। Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events केवल Claude-Code-only हैं और Codex के लिए register नहीं होते।
+
+#### Codex Desktop: plugin hooks वर्तमान में silent हैं (workaround उपलब्ध)
+
+`CodexHooks` और `PluginHooks` दोनों [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs) में stable + default-enabled हैं, लेकिन Codex Desktop builds वर्तमान में plugin-local `hooks.json` dispatch नहीं करते ([openai/codex#16430](https://github.com/openai/codex/issues/16430))। MCP tools अभी भी काम करते हैं; केवल lifecycle observations छूट जाते हैं।
+
+जब तक upstream fix land नहीं करता, वही hook commands को global `~/.codex/hooks.json` में mirror करें:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+यह `~/.codex/hooks.json` में एक idempotent block जोड़ता है जो bundled scripts के absolute paths को reference करता है (user-scope पर `${CLAUDE_PLUGIN_ROOT}` expansion की ज़रूरत नहीं)। agentmemory upgrade के बाद paths refresh करने के लिए वही कमांड फिर से चलाएँ। उसी फाइल में user entries संरक्षित रहती हैं; केवल पिछली agentmemory entries replace होती हैं।
+
+<details>
+<summary><b>OpenClaw (यह prompt paste करें)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+पूर्ण गाइड: [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (यह prompt paste करें)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+पूर्ण गाइड: [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### अन्य एजेंट्स
+
+मेमोरी सर्वर शुरू करें: `npx @agentmemory/agentmemory`
+
+agentmemory entry `mcpServers` shape का उपयोग करने वाले हर host में **वही MCP server block** है (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**इस entry को host की config file में मौजूदा `mcpServers` object में merge करें** — file को replace न करें। अगर फाइल में पहले से अन्य servers हैं, तो `mcpServers` के अंदर एक और key के रूप में `agentmemory` को उनके बगल में जोड़ें। अगर `mcpServers` पूरी तरह से missing है, तो block को `{ "mcpServers": { ... } }` के अंदर paste करें। `${VAR}` placeholders MCP-server launch पर shell से `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` inherit करते हैं — unset variables empty strings pass करते हैं और shim `http://localhost:3111` पर fallback होता है। एक wired entry local और remote (k8s / reverse-proxied) दोनों deployments को कवर करती है।
+
+| एजेंट | Config फाइल | नोट्स |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | `mcpServers` में merge करें। Website पर one-click deeplink भी उपलब्ध। |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers` में merge करें। Edit के बाद Claude Desktop restart करें। |
+| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | वही `mcpServers` block। |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | वही `mcpServers` block। |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges)। |
+| **OpenClaw** | OpenClaw MCP config | वही `mcpServers` block, या गहरे [memory plugin](../integrations/openclaw/) का उपयोग करें। |
+| **Codex CLI (केवल MCP)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, या manually `[mcp_servers.agentmemory]` जोड़ें। |
+| **Codex CLI (पूर्ण plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` फिर `codex plugin add agentmemory@agentmemory`। MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills register करता है। Codex Desktop पर, [openai/codex#16430](https://github.com/openai/codex/issues/16430) land होने तक `agentmemory connect codex --with-hooks` भी चलाएँ — plugin hooks वर्तमान में वहाँ silent हैं। |
+| **OpenCode (केवल MCP)** | `opencode.json` | अलग shape — top-level `mcp` key, command array के रूप में: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`। |
+| **OpenCode (पूर्ण plugin)** | `plugin/opencode/` | Session lifecycle, messages, tools, errors को कवर करने वाले 22 auto-capture hooks। दो slash commands (`/recall`, `/remember`)। `plugin/opencode/` को अपने OpenCode workspace में copy करें और plugin entry को `opencode.json` में जोड़ें। पूरी hook table + gap analysis के लिए [`plugin/opencode/README.md`](../plugin/opencode/README.md) देखें। |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | [`integrations/pi`](../integrations/pi/) copy करें और pi restart करें। |
+| **Hermes Agent** | `~/.hermes/config.yaml` | गहरे [memory provider plugin](../integrations/hermes/) का उपयोग `memory.provider: agentmemory` के साथ करें। |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` standard `mcpServers` block लिखता है। Hook payload Claude Code के साथ field-compatible है, इसलिए मौजूदा 12-hook scripts modification के बिना काम करते हैं — उन्हें उसी `settings.json` के `hooks` section के माध्यम से जोड़ें। |
+| **Antigravity** (Gemini CLI को replace करता है) | `mcp_config.json` (Antigravity की User dir में) | `agentmemory connect antigravity` standard `mcpServers` block लिखता है। macOS: `~/Library/Application Support/Antigravity/User/`। Linux: `~/.config/Antigravity/User/`। 2026-06-18 Gemini CLI sunset के बाद उपयोग करें। |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` user-level config लिखता है। Workspace overrides आपके code के बगल में `.kiro/settings/mcp.json` में जाते हैं। |
+| **Goose** | Goose MCP settings UI | वही `mcpServers` block। |
+| **Aider** | n/a | REST API से सीधे बात करें: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`। |
+| **कोई भी एजेंट (32+)** | n/a | `npx skillkit install agentmemory` host को auto-detect करता है और merge करता है। |
+
+**Sandboxed MCP क्लाइंट्स** (Flatpak / Snap / प्रतिबंधात्मक containers) जो host के `localhost` तक नहीं पहुँच सकते: `env` block में `"AGENTMEMORY_FORCE_PROXY": "1"` भी set करें, और `AGENTMEMORY_URL` को एक ऐसे route पर point करें जिस तक sandbox वास्तव में पहुँच सकता है (जैसे आपका LAN IP)। Diagnostic walkthrough के लिए [#234](https://github.com/rohitg00/agentmemory/issues/234) देखें।
+
+### Programmatic access (Python / Rust / Node)
+
+agentmemory अपने core operations को iii functions के रूप में register करता है (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`)। iii SDK वाली कोई भी भाषा उन्हें `ws://localhost:49134` पर सीधे call कर सकती है — प्रति भाषा अलग REST क्लाइंट नहीं।
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+कार्यशील उदाहरण: [`examples/python/`](../examples/python/) (quickstart + observation/recall flow)। iii runtime के बिना hosts के लिए REST `:3111` पर उपलब्ध रहता है।
+
+### Source से
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+यह agentmemory को local `iii-engine` के साथ शुरू करता है अगर `iii` पहले से installed है, या Docker उपलब्ध होने पर Docker Compose पर fallback करता है। REST, streams, और व्यूअर default रूप से `127.0.0.1` से bind करते हैं।
+
+`iii-engine` मैनुअली इंस्टॉल करें। **agentmemory वर्तमान में `iii-engine` को `v0.11.2` पर pin करता है** — `v0.11.6` एक नया sandbox-everything-via-`iii worker add` model introduce करता है जिसके लिए agentmemory को अभी refactor नहीं किया गया है। Refactor land होने के बाद pin हटा दी जाती है। अगर आपने sandbox model पर मैनुअली migrate किया है तो `AGENTMEMORY_III_VERSION=<version>` से override करें।
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `aarch64-apple-darwin` को `x86_64-apple-darwin` के साथ बदलें
+- **Linux x64:** `x86_64-unknown-linux-gnu` के साथ बदलें
+- **Linux arm64:** `aarch64-unknown-linux-gnu` के साथ बदलें
+- **Windows:** [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2) से `iii-x86_64-pc-windows-msvc.zip` download करें, `iii.exe` extract करें, PATH में जोड़ें
+
+या Docker का उपयोग करें (bundled `docker-compose.yml` `iiidev/iii:0.11.2` खींचता है)। पूर्ण docs: [iii.dev/docs](https://iii.dev/docs)।
+
+### Windows
+
+agentmemory Windows 10/11 पर चलता है, लेकिन केवल Node.js package पर्याप्त नहीं है — आपको एक background process के रूप में `iii-engine` runtime (एक अलग native binary) भी चाहिए। आधिकारिक upstream installer एक `sh` script है और आज कोई PowerShell installer या scoop/winget package नहीं है, इसलिए Windows users के पास दो रास्ते हैं:
+
+**विकल्प A — Prebuilt Windows binary (अनुशंसित):**
+
+```powershell
+# 1. अपने browser में https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 खोलें
+#    (हम v0.11.2 पर pin करते हैं जब तक agentmemory नए sandbox
+#     model के लिए refactor नहीं हो जाता जो engine v0.11.6+ की आवश्यकता है)
+# 2. iii-x86_64-pc-windows-msvc.zip download करें
+#    (या ARM machine पर हैं तो iii-aarch64-pc-windows-msvc.zip)
+# 3. PATH पर कहीं iii.exe extract करें, या यहाँ रखें:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory उस location को automatically check करता है)
+# 4. Verify करें:
+iii --version
+# Print होना चाहिए: 0.11.2
+
+# 5. फिर agentmemory को सामान्य ���ी तरह चलाएँ:
+npx -y @agentmemory/agentmemory
+```
+
+**विकल्प B — Docker Desktop:**
+
+```powershell
+# 1. Windows के लिए Docker Desktop install करें
+# 2. Docker Desktop शुरू करें और सुनिश्चित करें कि engine चल रहा है
+# 3. agentmemory चलाएँ — यह bundled compose file को auto-start करेगा:
+npx -y @agentmemory/agentmemory
+```
+
+**विकल्प C — केवल standalone MCP (कोई engine नहीं):** अगर आपको केवल अपने agent के लिए MCP tools चाहिए और REST API, व्यूअर, या cron jobs की ज़रूरत नहीं है, तो engine को पूरी तरह से skip करें:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# या shim package के माध्यम से:
+npx -y @agentmemory/mcp
+```
+
+**Windows के लिए diagnostics:** अगर `npx @agentmemory/agentmemory` fail करता है, तो वास्तविक engine stderr देखने के लिए `--verbose` के साथ फिर से चलाएँ। सामान्य failure modes:
+
+| लक्षण | समाधान |
+|---|---|
+| `iii-engine process started` फिर `did not become ready within 15s` | Engine startup पर crashed — `--verbose` के साथ फिर से चलाएँ, stderr check करें |
+| `Could not start iii-engine` | न तो `iii.exe` न ही Docker installed है। ऊपर विकल्प A या B देखें |
+| Port conflict | `netstat -ano \| findstr :3111` से देखें कि क्या bind है, फिर उसे kill करें या `--port <N>` का उपयोग करें |
+| Docker installed होने पर भी Docker fallback skip हो रहा है | सुनिश्चित करें कि Docker Desktop वास्तव में चल रहा है (system tray icon) |
+
+> नोट: कोई `cargo install iii-engine` नहीं है — `iii` crates.io पर publish नहीं है। केवल समर्थित install methods ऊपर prebuilt binary, upstream `sh` install script (केवल macOS/Linux), और Docker image हैं।
+
+---
+
+<h2 id="deploy">Deploy</h2>
+
+Managed hosts के लिए one-click templates। प्रत्येक एक self-contained
+Dockerfile ship करता है जो npm से `@agentmemory/agentmemory` खींचता है
+और आधिकारिक `iiidev/iii` Docker Hub image से iii engine binary को
+copy करता है — pre-built agentmemory image की आवश्यकता नहीं। Persistent
+storage `/data` पर mount होती है; first-boot entrypoint npm-bundled
+iii config (जो `127.0.0.1` से bind करती है) को एक deploy-tuned config
+से overwrite करता है जो `0.0.0.0` से bind करती है और absolute `/data`
+paths का उपयोग करती है, HMAC secret generate करती है, फिर agentmemory
+CLI को exec करने से पहले `gosu` के माध्यम से privileges को `root` से
+`node` पर drop करती है।
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render का one-click deploy button repository root पर `render.yaml` की आवश्यकता रखता है,
+जिसे हम जानबूझकर साफ़ रखते हैं। In-repo blueprint पर manually point करने के लिए
+[`deploy/render/`](../deploy/render/README.md) में documented Render Blueprint flow का उपयोग करें।
+
+पूर्ण setup विवरण (HMAC capture, viewer SSH tunnel,
+rotation, backup, cost floors) [`deploy/`](../deploy/README.md) में रहते हैं:
+
+- [`deploy/fly`](../deploy/fly/README.md) — `auto_stop_machines = "stop"` के साथ
+  single machine; सबसे सस्ता idle।
+- [`deploy/railway`](../deploy/railway/README.md) — Hobby plan flat fee,
+  dashboard में volume।
+- [`deploy/render`](../deploy/render/README.md) — Blueprint flow,
+  paid plans पर automatic disk snapshots।
+- [`deploy/coolify`](../deploy/coolify/README.md) — अपने स्वयं के VPS पर
+  [Coolify](https://coolify.io/self-hosted) के माध��यम से self-hosted; वही Docker
+  Compose stack, आप host और data के मालिक हैं।
+
+केवल port `3111` publish किया जाता है। `3113` पर viewer container के अंदर
+loopback से bound रहता है — हर template का README उस तक पहुँचने के लिए
+SSH-tunnel pattern को document करता है।
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
+
+हर coding agent सेशन समाप्त होने पर सब कुछ भूल जाता है। आप हर सेशन के पहले 5 मिनट अपने stack को फिर से समझाने में बर्बाद करते हैं। agentmemory पृष्ठभूमि में चलता है और इसे पूरी तरह से समाप्त कर देता है।
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### बिल्ट-इन agent memory से तुलना
+
+हर AI coding agent बिल्ट-इन memory के साथ ship होता है — Claude Code में `MEMORY.md` है, Cursor में notepads हैं, Cline में memory bank है। ये sticky notes की तरह काम करते हैं। agentmemory उन sticky notes के पीछे का searchable database है।
+
+| | बिल्ट-इन (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Scale | 200-line cap | असीमित |
+| खोज | सब कुछ context में load करता है | BM25 + vector + graph (केवल top-K) |
+| Token cost | 240 observations पर 22K+ | ~1,900 tokens (92% कम) |
+| Cross-agent | प्रति-agent फाइलें | MCP + REST (कोई भी agent) |
+| Coordination | कोई नहीं | Leases, signals, actions, routines |
+| Observability | फाइलें मैनुअल पढ़ें | :3113 पर real-time viewer |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>
+
+### Memory Pipeline
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4-Tier Memory Consolidation
+
+मानव मस्तिष्क memory को कैसे process करता है उससे प्रेरित — sleep consolidation से बहुत अलग नहीं।
+
+| Tier | क्या | Analogy |
+|------|------|---------|
+| **Working** | Tool use से raw observations | Short-term memory |
+| **Episodic** | संकुचित session summaries | "क्या हुआ" |
+| **Semantic** | निकाले गए facts और patterns | "मैं क्या जानता हूँ" |
+| **Procedural** | Workflows और decision patterns | "कैसे करें" |
+
+Memories समय के साथ decay होती हैं (Ebbinghaus curve)। बार-बार access की जाने वाली memories मज़बूत होती हैं। पुरानी memories auto-evict होती हैं। Contradictions detect और resolve होती हैं।
+
+### क्या Capture होता है
+
+| Hook | Captures |
+|------|----------|
+| `SessionStart` | Project path, session ID |
+| `UserPromptSubmit` | User prompts (privacy-filtered) |
+| `PreToolUse` | File access patterns + enriched context |
+| `PostToolUse` | Tool name, input, output |
+| `PostToolUseFailure` | Error context |
+| `PreCompact` | Compaction से पहले memory को re-inject करता है |
+| `SubagentStart/Stop` | Sub-agent lifecycle |
+| `Stop` | End-of-session summary |
+| `SessionEnd` | Session complete marker |
+
+### मुख्य क्षमताएँ
+
+| क्षमता | विवरण |
+|---|---|
+| **Automatic capture** | हर tool use hooks के माध्यम से record होता है — शून्य manual effort |
+| **Semantic search** | RRF fusion के साथ BM25 + vector + knowledge graph |
+| **Memory evolution** | Versioning, supersession, relationship graphs |
+| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction |
+| **Privacy first** | API keys, secrets, `<private>` tags storage से पहले strip होते हैं |
+| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring |
+| **Claude bridge** | MEMORY.md के साथ bi-directional sync |
+| **Knowledge graph** | Entity extraction + BFS traversal |
+| **Team memory** | Team members के बीच namespaced shared + private |
+| **Citation provenance** | किसी भी memory को source observations तक trace करें |
+| **Git snapshots** | Memory state को version, rollback, और diff करें |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
+
+तीन signals को combine करने वाला triple-stream retrieval:
+
+| Stream | यह क्या करता है | कब |
+|---|---|---|
+| **BM25** | Synonym expansion के साथ stemmed keyword matching | हमेशा on |
+| **Vector** | Dense embeddings पर cosine similarity | Embedding provider configured |
+| **Graph** | Entity matching के माध्यम से knowledge graph traversal | Query में entities detected |
+
+Reciprocal Rank Fusion (RRF, k=60) के साथ fuse होता है और session-diversified होता है (प्रति session max 3 results)।
+
+BM25 box से बाहर ही Greek, Cyrillic, Hebrew, Arabic, और accented Latin को tokenize करता है। Chinese / Japanese / Korean memories के लिए, CJK runs को word-level tokens में split करने के लिए optional segmenters install करें (`npm install @node-rs/jieba tiny-segmenter`); उनके बिना, agentmemory soft-fall back होकर whole-run tokenization पर जाता है और stderr पर एक-बार hint print करता है।
+
+### Embedding providers
+
+agentmemory आपके provider को auto-detect करता है। सर्वोत्तम परिणामों के लिए, local embeddings install करें (free):
+
+```bash
+npm install @xenova/transformers
+```
+
+| Provider | Model | Cost | नोट्स |
+|---|---|---|---|
+| **Local (अनुशंसित)** | `all-MiniLM-L6-v2` | Free | Offline, BM25-only पर +8pp recall |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ भाषाएँ, 768/1536/3072 dims (MRL), 2048-token input। `text-embedding-004` को replace करता है ([deprecated, 14 जनवरी 2026 को shutdown](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | उच्चतम quality |
+| Voyage AI | `voyage-code-3` | Paid | Code के लिए optimized |
+| Cohere | `embed-english-v3.0` | Free trial | General purpose |
+| OpenRouter | कोई भी model | भिन्न | Multi-model proxy |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>
+
+53 tools, 6 resources, 3 prompts, और 4 skills — किसी भी agent के लिए सबसे व्यापक MCP memory toolkit।
+
+> **MCP shim बनाम full server:** published `@agentmemory/mcp` package एक thin shim है। यह full 51-tool surface को **केवल तभी expose करता है जब यह `AGENTMEMORY_URL` के माध्यम से चल रहे agentmemory server तक पहुँच सके** (proxy mode)। कोई पहुँच योग्य server न होने पर, shim 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`) पर fallback करता है। `AGENTMEMORY_TOOLS=core|all` env var एक *server-side* flag है — shim के `env` block में set करने का कोई असर नहीं। अगर आप Cursor / OpenCode / Gemini CLI में केवल 7 tools देखते हैं, तो `npx @agentmemory/agentmemory` (या Docker stack) शुरू करें और `AGENTMEMORY_URL=http://localhost:3111` set करें।
+
+### 51 Tools
+
+<details>
+<summary>Core tools (हमेशा उपलब्ध)</summary>
+
+| Tool | विवरण |
+|------|-------------|
+| `memory_recall` | पिछले observations खोजें |
+| `memory_compress_file` | Structure preserve करते हुए markdown files compress करें |
+| `memory_save` | एक insight, decision, या pattern save करें |
+| `memory_patterns` | Recurring patterns detect करें |
+| `memory_smart_search` | Hybrid semantic + keyword search |
+| `memory_file_history` | विशिष्ट files के बारे में पिछले observations |
+| `memory_sessions` | Recent sessions list करें |
+| `memory_timeline` | Chronological observations |
+| `memory_profile` | Project profile (concepts, files, patterns) |
+| `memory_export` | सभी memory data export करें |
+| `memory_relations` | Relationship graph query करें |
+
+</details>
+
+<details>
+<summary>Extended tools (कुल 51 — AGENTMEMORY_TOOLS=all set करें)</summary>
+
+| Tool | विवरण |
+|------|-------------|
+| `memory_patterns` | Recurring patterns detect करें |
+| `memory_timeline` | Chronological observations |
+| `memory_relations` | Relationship graph query करें |
+| `memory_graph_query` | Knowledge graph traversal |
+| `memory_consolidate` | 4-tier consolidation चलाएँ |
+| `memory_claude_bridge_sync` | MEMORY.md के साथ sync करें |
+| `memory_team_share` | Team members के साथ share करें |
+| `memory_team_feed` | हाल ही में shared items |
+| `memory_audit` | Operations का audit trail |
+| `memory_governance_delete` | Audit trail के साथ delete करें |
+| `memory_snapshot_create` | Git-versioned snapshot |
+| `memory_action_create` | Dependencies के साथ work items create करें |
+| `memory_action_update` | Action status update करें |
+| `memory_frontier` | Priority द्वारा ranked unblocked actions |
+| `memory_next` | Single most important next action |
+| `memory_lease` | Exclusive action leases (multi-agent) |
+| `memory_routine_run` | Workflow routines instantiate करें |
+| `memory_signal_send` | Inter-agent messaging |
+| `memory_signal_read` | Receipts के साथ messages पढ़ें |
+| `memory_checkpoint` | External condition gates |
+| `memory_mesh_sync` | Instances के बीच P2P sync |
+| `memory_sentinel_create` | Event-driven watchers |
+| `memory_sentinel_trigger` | Sentinels externally fire करें |
+| `memory_sketch_create` | Ephemeral action graphs |
+| `memory_sketch_promote` | Permanent पर promote करें |
+| `memory_crystallize` | Action chains compact करें |
+| `memory_diagnose` | Health checks |
+| `memory_heal` | Stuck state को auto-fix करें |
+| `memory_facet_tag` | Dimension:value tags |
+| `memory_facet_query` | Facet tags द्वारा query करें |
+| `memory_verify` | Provenance trace करें |
+
+</details>
+
+### 6 Resources · 3 Prompts · 4 Skills
+
+| प्रकार | नाम | विवरण |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, session count, memory count |
+| Resource | `agentmemory://project/{name}/profile` | Per-project intelligence |
+| Resource | `agentmemory://memories/latest` | नवीनतम 10 active memories |
+| Resource | `agentmemory://graph/stats` | Knowledge graph statistics |
+| Prompt | `recall_context` | Search + context messages return करें |
+| Prompt | `session_handoff` | Agents के बीच handoff data |
+| Prompt | `detect_patterns` | Recurring patterns analyze करें |
+| Skill | `/recall` | Memory खोजें |
+| Skill | `/remember` | Long-term memory में save करें |
+| Skill | `/session-history` | हाल के session summaries |
+| Skill | `/forget` | Observations/sessions delete करें |
+
+### Standalone MCP
+
+Full server के बिना चलाएँ — किसी भी MCP client के लिए। इनमें से कोई भी काम करता है:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (हमेशा उपलब्ध)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+या अपने agent की MCP config में जोड़ें:
+
+अधिकांश agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+`agentmemory` entry को file को replace करने के बजाय अपने host के मौजूदा `mcpServers` object में merge करें। होस्ट के `localhost` तक नहीं पहुँच सकने वाले sandboxed clients के लिए, env block में `"AGENTMEMORY_FORCE_PROXY": "1"` जोड़ें और `AGENTMEMORY_URL` को एक ऐसे route पर set करें जिस तक sandbox पहुँच सकता है।
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Plugin file को repo से copy करें:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
+
+Port `3113` पर auto-start होता है। Live observation stream, session explorer, memory browser, knowledge graph visualization, और health dashboard।
+
+```bash
+open http://localhost:3113
+```
+
+व्यूअर server default रूप से `127.0.0.1` से bind होता है। REST-served `/agentmemory/viewer` endpoint सामान्य `AGENTMEMORY_SECRET` bearer-token नियमों का पालन करता है। CSP headers per-response script nonce का उपयोग करते हैं और inline handler attributes को disable करते हैं (`script-src-attr 'none'`)।
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+`:3113` पर viewer दिखाता है कि आपके agent ने क्या **याद रखा**। [iii console](https://iii.dev/docs/console) दिखाता है कि आपके agent ने क्या **किया** — हर memory op एक OpenTelemetry trace के रूप में, हर KV entry editable, हर function invocable, हर stream tappable। एक ही memory पर दो windows: एक product-shaped, एक engine-shaped।
+
+`memory_smart_search` को fire होते देखें और BM25 scan → embedding lookup → RRF fusion → reranker को waterfall के रूप में देखें। KV browser में stuck consolidation timer को edit करें। `PostToolUse` hook को tweaked payload के साथ replay करें। WebSocket stream को pin करें और observations को live land होते देखें।
+
+agentmemory इसे free में ship करता है क्योंकि हर function, trigger, state scope, और stream एक iii primitive है — कुछ भी custom नहीं, instrument करने के लिए कुछ नहीं।
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
+  <br/>
+  <em>Workers page: हर connected worker — agentmemory स्वयं सहित — PID, function count, runtime, और last-seen के साथ।</em>
+</p>
+
+**पहले से installed।** Console `iii` के साथ ship होता है — कोई अलग installer नहीं।
+
+**agentmemory के साथ launch करें:**
+
+```bash
+# agentmemory viewer port 3113 रखता है, तो console को 3114 पर चलाएँ।
+# Engine REST (3111), WebSocket (3112), और bridge (49134) defaults agentmemory से match करते हैं।
+iii console --port 3114
+```
+
+फिर `http://localhost:3114` खोलें। Experimental architecture-graph page के लिए `--enable-flow` जोड़ें।
+
+केवल तभी engine endpoints override करें जब आपने उन्हें move किया हो:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**Console से आप क्या कर सकते हैं:**
+
+| Page | इसके लिए उपयोग करें |
+|------|-----------|
+| **Workers** | हर connected worker और उसके live metrics देखें — agentmemory worker सहित। |
+| **Functions** | agentmemory के किसी भी function को सीधे JSON payload के साथ invoke करें — client जोड़े बिना `memory.recall`, `memory.consolidate`, `graph.query` test करने के लिए उपयोगी। |
+| **Triggers** | HTTP, cron, event, और state triggers replay करें — consolidation cron को manually fire करें, HTTP route retry करें, एक state change emit करें। |
+| **States** | Full CRUD के साथ KV browser — sessions, memory slots, lifecycle timers, embeddings index — values को in place edit करें। |
+| **Streams** | Memory writes, hook events, और observation updates के लिए live WebSocket monitor क्योंकि वे iii streams से बहते हैं। |
+| **Queues** | Durable queue topics + dead-letter management। Failed embedding / compression jobs को replay या drop करें। |
+| **Traces** | OpenTelemetry waterfall / flame / service-breakdown views। `trace_id` से filter करें ताकि देख सकें कि एक `memory.search` ने वास्तव में कौन से functions, DB calls, और embedding requests produce किए। |
+| **Logs** | Trace/span IDs से correlated और filtered structured OTEL logs। |
+| **Config** | Runtime configuration — देखें कि आपका engine किन workers, providers, और ports के साथ चल रहा है। |
+| **Flow** | (Optional, `--enable-flow`) हर worker, trigger, और stream का interactive architecture graph। |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
+  <br/>
+  <em>Traces: हर memory operation के लिए waterfall / flame / service breakdown।</em>
+</p>
+
+**Traces पहले से on हैं:**
+
+`iii-config.yaml` `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs) के साथ ship होता है। कोई extra config की ज़रूरत नहीं — जैसे ही agentmemory शुरू होता है, हर memory operation एक trace span और एक structured log emit करता है जिसे console पढ़ सकता है।
+
+अगर आप इसके बजाय Jaeger/Honeycomb/Grafana Tempo पर export करना चाहते हैं, तो `exporter: memory` को `exporter: otlp` में बदलें और iii के observability docs के अनुसार collector endpoint set करें।
+
+> **ध्यान दें:** console पर कोई auth enforce नहीं है — इसे `127.0.0.1` (default) से bound रखें और इसे कभी publicly expose न करें।
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory **पहले से एक चल रहा [iii](https://iii.dev) instance है**। Functions, triggers, KV state, streams, OTEL traces — यह सब iii primitives हैं। आपने Postgres, Redis, Express, pm2, या Prometheus install नहीं किया, क्योंकि iii उन्हें replace करता है।
+
+इसका मतलब है कि एक और कमांड agentmemory को एक पूरी नई capability के साथ extend करती है।
+
+### एक command के साथ agentmemory को extend करें
+
+```bash
+iii worker add iii-pubsub          # memory writes को हर connected instance पर fan out करें
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # embedding + compression jobs के लिए durable retries
+iii worker add iii-observability   # हर memory op पर OTEL traces (default on)
+iii worker add iii-sandbox         # recalled code को isolated microVM के अंदर चलाएँ
+iii worker add iii-database        # एक SQL-backed state adapter में swap करें
+iii worker add mcp                 # agentmemory MCP के साथ-साथ generic MCP host
+```
+
+प्रत्येक `iii worker add` उसी engine में नए functions और triggers register करता है जिस पर agentmemory पहले से चल रहा है। Viewer और console उन्हें तुरंत pick करते हैं — कोई reload नहीं, कोई नया integration नहीं, कोई नया container नहीं।
+
+| `iii worker add` | agentmemory के ऊपर आपको क्या मिलता है |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-instance memory: हर `remember` fan out होती है, हर `search` union पढ़ता है |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Scheduled lifecycle — रात की consolidation, साप्ताहिक snapshots, fixed clock पर decay |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable retries: failed embedding + compression jobs restart से बचते हैं, कोई lost observations नहीं |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | हर function पर OTEL traces, metrics, logs — दिन एक से `iii-config.yaml` में wired |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` से निकला code throwaway VM के अंदर चलता है, आपके shell में नहीं |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | जब आप in-memory KV defaults से बाहर निकलते हैं तो SQL-backed state adapter |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory के साथ-साथ extra MCP servers खड़े करें, वही engine share करें |
+
+Full registry: [workers.iii.dev](https://workers.iii.dev)। वहाँ हर worker उन्हीं primitives के माध्यम से compose करता है जिनका agentmemory उपयोग करता है — और आपके पास पहले से जो agentmemory है, वह उनमें से एक है।
+
+### iii क्या replace करता है
+
+| Traditional stack | agentmemory उपयोग करता है |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker supervision |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Custom plugin systems | `iii worker add <name>` |
+
+**118 source files · ~21,800 LOC · 950+ tests · 123 functions · 34 KV scopes** — सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### LLM Providers
+
+agentmemory आपके environment से auto-detect करता है। Default रूप से, जब तक आप एक provider configure नहीं करते या Claude subscription fallback में explicitly opt in नहीं करते, कोई LLM calls नहीं की जातीं।
+
+| Provider | Config | नोट्स |
+|----------|--------|-------|
+| **No-op (default)** | कोई config की ज़रूरत नहीं | LLM-backed compress/summarize DISABLED है। Synthetic BM25 compression + recall अभी भी काम करते हैं। अगर आप पहले Claude-subscription fallback पर निर्भर थे तो नीचे `AGENTMEMORY_ALLOW_AGENT_SDK` देखें। |
+| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
+| Gemini | `GEMINI_API_KEY` | Embeddings भी enable करता है |
+| OpenRouter | `OPENROUTER_API_KEY` | कोई भी model |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | केवल opt-in। `@anthropic-ai/claude-agent-sdk` sessions spawn करता है — पहले unbounded Stop-hook recursion का कारण था (#149 follow-up) तो यह अब default नहीं है। |
+
+### Cost-aware model selection
+
+Background compression हर observation पर चलता है, इसलिए model choice monthly spend को meaningfully बदलता है। Captured workload data: 635 requests / 888K tokens / 35 hours of active use, 2026-05-23 pricing पर तीन OpenRouter models पर चलाया गया।
+
+| Tier | Model | Input / 1M | Output / 1M | Captured 35h के लिए cost | नोट्स |
+|------|-------|------------|-------------|---------------------------|-------|
+| अनुशंसित | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet से ~10× कम cost पर solid compression + summarization quality। |
+| अनुशंसित | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | पुराना लेकिन केवल-compression workloads के लिए अभी भी ठीक। |
+| अनुशंसित | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | अगर आपके sessions भारी रूप से code-shaped हैं तो strong code reasoning। |
+| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | High quality लेकिन always-on background work के लिए महंगा। |
+| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Sonnet के समान tier। |
+| बचें | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | Reasoning-class model; compression के लिए massive overspend। |
+
+जब `OPENROUTER_MODEL` premium-tier pattern से match करता है तो agentmemory एक runtime warning print करता है। जब आप informed choice कर लें तो silence करने के लिए `AGENTMEMORY_SUPPRESS_COST_WARNING=1` set करें।
+
+Memory work के लिए quality बनाम cost tradeoff: compression एक summarization task है जिसमें अपेक्षाकृत loose quality bars हैं (agent summary को re-read करता है, user नहीं)। DeepSeek-V4-Pro / Qwen3-Coder इस task पर Sonnet से rounding error के भीतर land होते हैं जबकि ~10× कम cost में। Premium-tier models को उन queries के लिए save करें जिन्हें आप सीधे पढ़ते हैं।
+
+Sources: [Sonnet 4.6 के लिए OpenRouter pricing](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing नोट्स](https://api-docs.deepseek.com/quick_start/pricing/)।
+
+### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Multi-agent setups में जहाँ कई roles एक agentmemory server share करते हैं (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` हर write को उस role से tag करता है जिसने इसे किया। `AGENTMEMORY_AGENT_SCOPE` यह control करता है कि recall उस tag के द्वारा filter करता है या नहीं।
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+दो modes:
+
+| Mode | Writes को tag करें | Recall filter करें | कब उपयोग करें |
+|------|------------|---------------|-------------|
+| `shared` (default) | हाँ | नहीं | Audit trail के साथ cross-agent context। Architect देख सकता है कि developer ने क्या note किया, लेकिन हर row record करती है कि किसने कहा। |
+| `isolated` | हाँ | हाँ | सख्त separation। Architect कभी developer के observations / memories / sessions नहीं देखता। |
+
+जब `AGENT_ID` set होता है तो क्या tagged होता है: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`। Role `api::session::start` → `mem::observe` → `mem::compress` → KV से flow करता है।
+
+Isolated mode में क्या filter होता है: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`। प्रत्येक endpoint per-request override के लिए `?agentId=<role>` और env scope से पूरी तरह से opt out करने के लिए `?agentId=*` accept करता है। `/memories` AGENT_ID से पहले के memories को surface करने के लिए `?includeOrphans=true` भी accept करता है जिनकी `agentId` undefined है।
+
+SDK / REST layer पर per-call override: हर mutating endpoint (`/session/start`, `/remember`) request body में एक `agentId` field accept करता है जो env से जीतता है। एक server process के माध्यम से कई roles को route करने वाले runtimes के लिए उपयोगी।
+
+जब `AGENT_ID` unset होता है, तो memory unscoped रहती है (legacy behavior, कोई tags नहीं, कोई filters नहीं)।
+
+### Ports
+
+agentmemory + iii-engine default रूप से चार ports पर bind होते हैं। अगर एक restart `port in use` के साथ fail होता है, तो यह table बताती है कि किस process को देखना है।
+
+| Port | Process | उद्देश्य | Env override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Internal streams worker (agentmemory + viewer द्वारा consumed) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — workers यहाँ register होते हैं, OTel telemetry यहाँ से flow होती है | `III_ENGINE_URL` (full URL, default `ws://localhost:49134`) |
+
+Crashed run के बाद ports bound रहने पर stale-process cleanup:
+
+```bash
+# macOS / Linux — हर port पर जो भी है उसे ढूँढ़ें और kill करें
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` graceful shutdown पर worker और engine pidfile दोनों को साफ़ रूप से reap करता है (#640, #474)। ऊपर का manual cleanup केवल post-crash case के लिए है जहाँ कोई भी pidfile पीछे नहीं छोड़ी गई।
+
+### Config File
+
+हर shell में variables export करने के बजाय agentmemory runtime configuration को `~/.agentmemory/.env` में रखें। अगर viewer `export ANTHROPIC_API_KEY=...` जैसा setup hint दिखाता है, तो इसे `export` prefix के बिना इस file में `ANTHROPIC_API_KEY=...` के रूप में copy करें, फिर agentmemory restart करें।
+
+Process environment variables अभी भी काम करते हैं और file में values पर precedence लेते हैं।
+
+Windows पर, वही file `%USERPROFILE%\.agentmemory\.env` पर रहती है:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+API key के बजाय Claude Code Pro/Max subscription के साथ test करने के लिए, explicitly opt in करें:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+अगर आप graph या consolidation features चाहते हैं तो उसी file में उन्हें on करें:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### Environment Variables
+
+`~/.agentmemory/.env` बनाएँ:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+Port `3111` पर 124 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। `AGENTMEMORY_SECRET` set होने पर protected endpoints `Authorization: Bearer <secret>` की आवश्यकता रखते हैं, और mesh sync endpoints दोनों peers पर `AGENTMEMORY_SECRET` की आवश्यकता रखते हैं।
+
+<details>
+<summary>मुख्य endpoints</summary>
+
+| Method | Path | विवरण |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (हमेशा public) |
+| `POST` | `/agentmemory/session/start` | Session शुरू करें + context प्राप्त करें |
+| `POST` | `/agentmemory/session/end` | Session समाप्त करें |
+| `POST` | `/agentmemory/observe` | Observation capture करें |
+| `POST` | `/agentmemory/smart-search` | Hybrid search |
+| `POST` | `/agentmemory/context` | Context generate करें |
+| `POST` | `/agentmemory/remember` | Long-term memory में save करें |
+| `POST` | `/agentmemory/forget` | Observations delete करें |
+| `POST` | `/agentmemory/enrich` | File context + memories + bugs |
+| `GET` | `/agentmemory/profile` | Project profile |
+| `GET` | `/agentmemory/export` | सभी data export करें |
+| `POST` | `/agentmemory/import` | JSON से import करें |
+| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
+| `POST` | `/agentmemory/team/share` | Team के साथ share करें |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Full endpoint list: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ tests
+npm run test:integration  # API tests (running services की आवश्यकता है)
+```
+
+**आवश्यकताएँ:** Node.js >= 20, [iii-engine](https://iii.dev/docs) या Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.ja-JP.md

@@ -0,0 +1,1380 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — AI コーディングエージェントのための永続メモリ" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    コーディングエージェントがすべてを記憶します。もう説明し直す必要はありません。
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Claude Code、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode、そしてあらゆる MCP クライアントのための永続メモリ。
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  日本語 |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1200 stars / 172 forks on the gist" /></a>
+</p>
+
+<p align="center">
+  <em>この gist は Karpathy の LLM Wiki パターンを信頼度スコア、ライフサイクル管理、ナレッジグラフ、ハイブリッド検索で拡張します。agentmemory はその実装です。</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">インストール</a> &bull;
+  <a href="#quick-start">クイックスタート</a> &bull;
+  <a href="#benchmarks">ベンチマーク</a> &bull;
+  <a href="#vs-competitors">競合比較</a> &bull;
+  <a href="#works-with-every-agent">エージェント</a> &bull;
+  <a href="#how-it-works">仕組み</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">ビューワー</a> &bull;
+  <a href="#iii-console">iii コンソール</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">設定</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## インストール
+
+```bash
+npm install -g @agentmemory/agentmemory          # 一度のインストール — PATH 上に `agentmemory` が使えるようになる
+# macOS/Linux のシステム Node で EACCES が出る場合は次を試してください:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # :3111 でメモリサーバーを起動
+agentmemory demo                                 # サンプルセッションを投入してリコールを実証
+agentmemory connect claude-code                  # エージェントを接続 (他にも codex, cursor, gemini-cli, ...)
+```
+
+または `npx` で(インストール不要):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+注意 — npx はバージョン単位でキャッシュします。素の `npx @agentmemory/agentmemory` が古いリリースを返す場合は、`npx -y @agentmemory/agentmemory@latest` で最新を強制するか、`rm -rf ~/.npm/_npx`(macOS/Linux。Windows では `%LOCALAPPDATA%\npm-cache\_npx` を削除)で一度キャッシュをクリアしてください。v0.9.16+ では初回 npx 実行時にインラインでグローバルインストールを促されるので、それ以降は素の `agentmemory` コマンドがどこでも動きます。
+
+すべてのオプションは下の[クイックスタート](#quick-start)を参照。各エージェント固有の接続は[すべてのエージェントで動作](#works-with-every-agent)を参照。
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
+
+agentmemory は hooks、MCP、REST API をサポートするあらゆるエージェントで動作します。すべてのエージェントが同じメモリサーバーを共有します。
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>ネイティブプラグイン + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>ネイティブプラグイン + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>ネイティブプラグイン + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>ネイティブプラグイン + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>ネイティブプラグイン + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>ネイティブ Memory trait バックエンド</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + プラグイン</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP サーバー</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>MCP または HTTP を話す<strong>あらゆる</strong>エージェントで動作。サーバー 1 つで、すべてのエージェントがメモリを共有。</sub>
+</p>
+
+---
+
+あなたは毎セッション、同じアーキテクチャを説明し直している。同じバグを何度も発見する。同じ好みを繰り返し教える。組み込みのメモリ(CLAUDE.md、.cursorrules)は 200 行で打ち止め、しかも古びていく。agentmemory がこれを解決します。バックグラウンドで静かにエージェントの動きを捕捉し、検索可能なメモリに圧縮し、次のセッションが始まるときに適切なコンテキストを注入します。コマンド 1 つ。エージェント間で動作します。
+
+**何が変わるか:** セッション 1 で JWT 認証をセットアップ。セッション 2 でレート制限を依頼する。エージェントは既に、あなたの認証が `src/middleware/auth.ts` の jose ミドルウェアを使い、テストがトークン検証をカバーし、Edge 互換性のために jsonwebtoken ではなく jose を選んだことを知っています。説明のし直し不要。コピペ不要。エージェントはただ*知っている*。
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **v0.9.0 新機能** — ランディングサイト [agent-memory.dev](https://agent-memory.dev) 公開、ファイルシステムコネクタ(`@agentmemory/fs-watcher`)、スタンドアロン MCP は実行中のサーバーへプロキシすることで hooks とビューワーが整合、削除パス全体で監査ポリシーをコード化、健康チェックは小さな Node プロセスで `memory_critical` を誤検知しなくなりました。詳細は [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18) を参照。
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### 検索精度
+
+**coding-agent-life-v1**(社内コーパス、サンドボックスで再現可能)
+
+| アダプタ | P@5 | R@5 | Top-5 ヒット率 | p50 レイテンシ |
+|---|---|---|---|---|
+| **agentmemory ハイブリッド** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep ベースライン | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+100% Top-5 ヒット率。同じ入力で grep ベースラインより **2.2×** 高い精度。タイプ別の詳細は [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md)。
+
+**LongMemEval-S**(ICLR 2025、500 問)
+
+| システム | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25 のみのフォールバック | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### トークン削減
+
+| 方式 | トークン/年 | コスト/年 |
+|---|---|---|
+| フルコンテキスト貼付 | 19.5M+ | 不可能(コンテキストウィンドウ超過) |
+| LLM 要約 | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + ローカル埋め込み | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> 埋め込みモデル:`all-MiniLM-L6-v2`(ローカル、無料、API キー不要)。詳細レポート:[`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md)、[`benchmark/QUALITY.md`](../benchmark/QUALITY.md)、[`benchmark/SCALE.md`](../benchmark/SCALE.md)。競合比較:[`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory vs mem0、Letta、Khoj、claude-mem、Hippo。
+
+**ローカルで再現:** [`eval/README.md`](../eval/README.md) — LongMemEval `_s`(公開 500 問)+ `coding-agent-life-v1`(社内 15 セッションコーパス)向けのアダプタプラガブルハーネス。Grep / vector / agentmemory アダプタを並べてスコアリングし、NDJSON 出力、公開スコアカードは [`docs/benchmarks/`](../docs/benchmarks/) に掲載。
+
+**[codegraph](https://github.com/colbymchenry/codegraph)、[Understand Anything](https://github.com/Lum1104/Understand-Anything)、[Graphify](https://github.com/safishamsi/graphify) と組み合わせて使えます。** コードグラフのインデックス、マルチエージェントビルドパイプライン、ドキュメント / PDF / 画像 / 動画にまたがる広範なナレッジグラフ。agentmemory が作業を覚え、これら 3 つのプロジェクトがコンテキストレイヤーの残りを照らします。レシピと質問ルーティング表:[`docs/recipes/pairings.md`](../docs/recipes/pairings.md)。
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="vs Competitors" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">組み込み (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>種別</strong></td>
+<td>メモリエンジン + MCP サーバー</td>
+<td>メモリレイヤー API</td>
+<td>フルエージェントランタイム</td>
+<td>静的ファイル</td>
+</tr>
+<tr>
+<td><strong>検索 R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>自動キャプチャ</strong></td>
+<td>12 hooks(手動作業ゼロ)</td>
+<td>手動の <code>add()</code> 呼び出し</td>
+<td>エージェントが自分で編集</td>
+<td>手動編集</td>
+</tr>
+<tr>
+<td><strong>検索</strong></td>
+<td>BM25 + ベクトル + グラフ(RRF 融合)</td>
+<td>ベクトル + グラフ</td>
+<td>ベクトル(アーカイブ)</td>
+<td>すべてをコンテキストにロード</td>
+</tr>
+<tr>
+<td><strong>マルチエージェント</strong></td>
+<td>MCP + REST + リース + シグナル</td>
+<td>API(調整なし)</td>
+<td>Letta ランタイム内のみ</td>
+<td>エージェントごとにファイル</td>
+</tr>
+<tr>
+<td><strong>フレームワークロックイン</strong></td>
+<td>なし(任意の MCP クライアント)</td>
+<td>なし</td>
+<td>高(Letta 必須)</td>
+<td>エージェントごとのフォーマット</td>
+</tr>
+<tr>
+<td><strong>外部依存</strong></td>
+<td>なし(SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + ベクトル DB</td>
+<td>なし</td>
+</tr>
+<tr>
+<td><strong>メモリライフサイクル</strong></td>
+<td>4 層統合 + 減衰 + 自動忘却</td>
+<td>受動的抽出</td>
+<td>エージェント管理</td>
+<td>手動プルーニング</td>
+</tr>
+<tr>
+<td><strong>トークン効率</strong></td>
+<td>~1,900 tokens/セッション ($10/年)</td>
+<td>統合方法による</td>
+<td>コアメモリがコンテキスト内</td>
+<td>240 観測で 22K+ tokens</td>
+</tr>
+<tr>
+<td><strong>リアルタイムビューワー</strong></td>
+<td>あり(ポート 3113)</td>
+<td>クラウドダッシュボード</td>
+<td>クラウドダッシュボード</td>
+<td>なし</td>
+</tr>
+<tr>
+<td><strong>セルフホスト</strong></td>
+<td>あり(デフォルト)</td>
+<td>オプション</td>
+<td>オプション</td>
+<td>あり</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
+
+互換性:このリリースは安定版の `iii-sdk` `^0.11.0` と iii-engine v0.11.x を対象とします。
+
+### 30 秒で試す
+
+```bash
+# ターミナル 1: サーバーを起動
+npx @agentmemory/agentmemory
+
+# ターミナル 2: サンプルデータを投入してリコールを確認
+npx @agentmemory/agentmemory demo
+```
+
+`demo` は 3 つの現実的なセッション(JWT 認証、N+1 クエリ修正、レート制限)を投入し、セマンティック検索を実行します。「database performance optimization」で検索すると「N+1 query fix」が見つかります — キーワード一致ではできない芸当です。
+
+`http://localhost:3113` を開けばメモリがリアルタイムに構築される様子が見られます。
+
+### 推奨:グローバルインストール
+
+`npx` はバージョン単位でキャッシュ���ます。先週 `npx @agentmemory/agentmemory@0.9.14` を実行していた場合、素の `npx @agentmemory/agentmemory` は最新ではなく `~/.npm/_npx/` から古い 0.9.14 を提供することがあります。一度インストールすれば、素の `agentmemory` コマンドがどこでも動きます:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# macOS/Linux のシステム Node で EACCES が出る場合は次を試してください:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # サーバー起動(npx 形式と同じ)
+agentmemory stop               # 停止
+agentmemory remove             # 作成したものをすべてアンインストール
+agentmemory connect claude-code   # エージェントを 1 つ接続
+agentmemory doctor             # 対話型診断 + 修正プロンプト
+```
+
+v0.9.16 以降、初回 npx 実行時にインラインでグローバルインストールを促されます — 一度 `Y` と答えれば完了です。スキップした場合、以下のいずれかで最新を取得できます:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # npm から最新を強制(クロスプラットフォーム)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux のみ (POSIX shell)
+```
+
+Windows / PowerShell では、同等のキャッシュクリアは `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` です — 上記の `npx -y ...@latest` 形式がクロスプラットフォームの選択肢になります。
+
+### セッションリプレイ
+
+agentmemory が記録するすべてのセッションは再生可能です。ビューワーを開き、**Replay** タブを選択し、タイムラインをスクラブしてください: プロンプト、ツール呼び出し、ツール結果、応答が個別のイベントとして表示され、再生/一時停止、速度コントロール(0.5×–4×)、キーボードショートカット(スペースで切り替え、矢印でステップ)が使えます。
+
+古い Claude Code の JSONL トランスクリプトを取り込みたい?
+
+```bash
+# デフォルトの ~/.claude/projects 配下を一括インポート
+npx @agentmemory/agentmemory import-jsonl
+
+# あるいは単一ファイルをインポート
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+インポートしたセッションはネイティブのセッションと並んで Replay ピッカーに表示されます。内部では各エントリが `mem::replay::load`、`mem::replay::sessions`、`mem::replay::import-jsonl` の iii functions を経由します — サイドチャネルサーバーはありません。
+
+### アップグレード / メンテナンス
+
+意図的にローカルランタイムを更新したいときは、メンテナンスコマンドを使ってください:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+警告: このコマンドは現在のワークスペース/ランタイムを変更します。JavaScript 依存を更新したり、`cargo install iii-engine --force` を実行したり、Docker イメージを pull したりすることがあります。
+
+実装の詳細は `src/cli.ts` を参照(`src/cli.ts:544-595` 付近の `runUpgrade`)。
+
+### Claude Code(1 ブロックそのまま貼り付け)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### プラグインをインストールしない Claude Code(MCP スタンドアロン)
+
+`/plugin install` ではなく `~/.claude.json` から直接 agentmemory の MCP サーバーを配線する場合、Claude Code は `${CLAUDE_PLUGIN_ROOT}` を解決しないため、hook スクリプトを `~/.claude/settings.json` の絶対パスに向ける必要があります。これらのパスには通常 agentmemory のバージョン(例: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`)が埋め込まれるため、次のアップグレードで全 hook が静かに壊れます([#508](https://github.com/rohitg00/agentmemory/issues/508))。
+
+回避策:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+同じ hook コマンドを `~/.claude/settings.json` にマージし、現在インストールされている `@agentmemory/agentmemory` パッケージの `plugin/` ディレクトリに解決された絶対パスを書き込みます。agentmemory をアップグレードしたら、このコマンドを再実行してパスを更新してください。��じファイル内のユーザーエントリは保持され、以前の agentmemory エントリだけが置き換えられます。`/plugin install` の経路が推奨アプローチであることに変わりはありません。
+
+リモートや保護されたデプロイでは、`AGENTMEMORY_URL` と `AGENTMEMORY_SECRET` を設定して Claude Code を起動します。プラグインはこの両方の値を同梱の MCP サーバーに渡します。`AGENTMEMORY_URL` が空の場合、MCP shim は `http://localhost:3111` にフォールバックします。
+
+### Codex CLI(Codex プラグインプラットフォーム)
+
+```bash
+# 1. 別ターミナルでメモリサーバーを起動
+npx @agentmemory/agentmemory
+
+# 2. agentmemory マーケットプレイスを登録してプラグインをインストール
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex プラグインは Claude Code プラグインと同じ `plugin/` ディレクトリから出荷されます。以下を登録します:
+
+- `@agentmemory/mcp` を MCP サーバーとして(`AGENTMEMORY_URL` が動作中の agentmemory サーバーを指す場合は 51 ツールすべてをプロキシ、サーバーに到達できない場合はローカルで 7 ツールにフォールバック)
+- 6 つのライフサイクル hooks: `SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PreCompact`、`Stop`
+- 4 つの skills: `/recall`、`/remember`、`/session-history`、`/forget`
+
+Codex の hook エンジンは hook サブプロセスに `CLAUDE_PLUGIN_ROOT` を注入する([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs))ので、同じ hook スクリプトが両ホストで重複なく動きます。Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure イベントは Claude Code 専用で、Codex には登録されません。
+
+#### Codex Desktop: プラグイン hooks は現在無音(回避策あり)
+
+`CodexHooks` と `PluginHooks` はどちらも [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs) で安定版・デフォルト有効ですが、Codex Desktop ビルドは現在プラグインローカルの `hooks.json` をディスパッチしません([openai/codex#16430](https://github.com/openai/codex/issues/16430))。MCP ツールは引き続き動きますが、ライフサイクル観測だけが欠落します。
+
+上流が修正を出すまでは、同じ hook コマンドをグローバルな `~/.codex/hooks.json` にミラーしてください:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+これは同梱スクリプトへの絶対パスを参照する冪等なブロックを `~/.codex/hooks.json` に追加します(ユーザースコープでは `${CLAUDE_PLUGIN_ROOT}` の展開は不要)。agentmemory をアップグレードしたら同じコマンドを再実行してパスを更新してください。同じファイル内のユーザーエントリは保持され、以前の agentmemory エントリだけが置き換えられます。
+
+<details>
+<summary><b>OpenClaw(このプロンプトを貼り付け)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+詳細ガイド:[`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent(このプロンプトを貼り付け)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+詳細ガイド:[`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### その他のエージェント
+
+メ��リサーバーを起動:`npx @agentmemory/agentmemory`
+
+`mcpServers` シェイプを使うホスト(Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI、OpenClaw)では、agentmemory エントリは**同じ MCP サーバーブロック**です:
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**このエントリをホストの設定ファイルにある既存の `mcpServers` オブジェクトにマージしてください** — ファイル全体を置き換えないでください。ファイルに既に他のサーバーがある場合は、`agentmemory` をその隣にもう 1 つのキーとして追加します。`mcpServers` が完全に欠落している場合は、ブロックを `{ "mcpServers": { ... } }` の中に貼り付けてください。`${VAR}` プレースホルダーは MCP サーバー起動時にシェルから `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` を継承します — 未設定の変数は空文字列を渡し、shim は `http://localhost:3111` にフォールバックします。1 つの接続済みエントリでローカルとリモート(k8s / リバースプロキシ)両方のデプロイに対応します。
+
+| エージェント | 設定ファイル | 備考 |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | `mcpServers` にマージ。ウェブサイトでワンクリックディープリンクも利用可能。 |
+| **Claude Desktop** | `claude_desktop_config.json`(Application Support) | `mcpServers` にマージ。編集後 Claude Desktop を再起動。 |
+| **Cline / Roo Code / Kilo Code** | Cline MCP 設定(設定 UI → MCP Servers → Edit) | 同じ `mcpServers` ブロック。 |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | 同じ `mcpServers` ブロック。 |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user`(自動マージ)。 |
+| **OpenClaw** | OpenClaw MCP 設定 | 同じ `mcpServers` ブロック、または[より深いメモリプラグイン](../integrations/openclaw/)を使用。 |
+| **Codex CLI(MCP のみ)** | `.codex/config.toml` | TOML シェイプ: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`、または `[mcp_servers.agentmemory]` を手動で追加。 |
+| **Codex CLI(フルプラグイン)** | Codex プラグインマーケットプレイス | `codex plugin marketplace add rohitg00/agentmemory` のあと `codex plugin add agentmemory@agentmemory`。MCP + 6 つのライフサイクル hooks(SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop)+ 4 つの skills を登録。Codex Desktop では、[openai/codex#16430](https://github.com/openai/codex/issues/16430) が解決するまで `agentmemory connect codex --with-hooks` も実行 — そちらではプラグイン hooks が現在無音。 |
+| **OpenCode(MCP のみ)** | `opencode.json` | 異なるシェイプ — トップレベルの `mcp` キー、command は配列: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`。 |
+| **OpenCode(フルプラグイン)** | `plugin/opencode/` | 22 個の自動キャプチャ hooks がセッションライフサイクル、メッセージ、ツール、エラーをカバー。2 つのスラッシュコマンド(`/recall`、`/remember`)。`plugin/opencode/` を OpenCode ワークスペースにコピーし、プラグインエントリを `opencode.json` に追加。完全な hook 表とギャップ分析は [`plugin/opencode/README.md`](../plugin/opencode/README.md) を参照。 |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | [`integrations/pi`](../integrations/pi/) をコピーして pi を再起動。 |
+| **Hermes Agent** | `~/.hermes/config.yaml` | より深い[メモリプロバイダープラグイン](../integrations/hermes/)を使い、`memory.provider: agentmemory` を設定。 |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` が標準の `mcpServers` ブロックを書き込みます。Hook ペイロードは Claude Code とフィールド互換なので、既存の 12 hook スクリプトはそのまま動作 — 同じ `settings.json` の `hooks` セクションで配線してください。 |
+| **Antigravity**(Gemini CLI の後継) | `mcp_config.json`(Antigravity の User ディレクトリ内) | `agentmemory connect antigravity` が標準の `mcpServers` ブロックを書き込みます。macOS: `~/Library/Application Support/Antigravity/User/`。Linux: `~/.config/Antigravity/User/`。2026-06-18 の Gemini CLI 終了後に使用。 |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` がユーザーレベル設定を書き込みます。ワークスペースのオーバーライドはコードの横にある `.kiro/settings/mcp.json` に。 |
+| **Goose** | Goose MCP 設定 UI | 同じ `mcpServers` ブロック。 |
+| **Aider** | n/a | REST API に直接話しかける: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
+| **任意のエージェント(32+)** | n/a | `npx skillkit install agentmemory` がホストを自動検出してマージ。 |
+
+**サンドボックス化された MCP クライアント**(Flatpak / Snap / 制限的なコンテナ)はホストの `localhost` に到達できません: `env` ブロックに `"AGENTMEMORY_FORCE_PROXY": "1"` も設定し、`AGENTMEMORY_URL` をサンドボックスが実際に到達できる経路(例: LAN IP)に向けてください。診断手順は [#234](https://github.com/rohitg00/agentmemory/issues/234) を参照。
+
+### プログラマティックアクセス(Python / Rust / Node)
+
+agentmemory はコア操作を iii functions(`mem::remember`、`mem::observe`、`mem::context`、`mem::smart-search`、`mem::forget`)として登録します。iii SDK を持つあらゆる言語が `ws://localhost:49134` で直接呼び出せます — 言語ごとに REST クライアントを用意する必要はありません。
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+実例:[`examples/python/`](../examples/python/)(クイックスタート + 観測/リコールフロー)。iii ランタイムがないホスト向けに `:3111` の REST も引き続き利用可能。
+
+### ソースから
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+`iii` が既にインストールされていれば、これでローカルの `iii-engine` で agentmemory が起動します。Docker が使える場合は Docker Compose にフォールバックします。REST、ストリーム、ビューワーはデフォルトで `127.0.0.1` にバインドします。
+
+`iii-engine` を手動でインストールしてください。**agentmemory は現在 `iii-engine` を `v0.11.2` にピン留めしています** — `v0.11.6` では `iii worker add` で何でもサンドボックス化する新モデルが導入されましたが、agentmemory はまだそれ向けにリファクタリングされていません。リファクタが完了次第ピンは解除されます。サンドボックスモデルへ手動移行済みなら `AGENTMEMORY_III_VERSION=<version>` でオーバーライドできます。
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `aarch64-apple-darwin` を `x86_64-apple-darwin` に置換
+- **Linux x64:** `x86_64-unknown-linux-gnu` に置換
+- **Linux arm64:** `aarch64-unknown-linux-gnu` に置換
+- **Windows:** [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2) から `iii-x86_64-pc-windows-msvc.zip` をダウンロード、`iii.exe` を展開し PATH に追加
+
+または Docker を使用(同梱の `docker-compose.yml` が `iiidev/iii:0.11.2` を pull します)。詳細ドキュメント:[iii.dev/docs](https://iii.dev/docs)。
+
+### Windows
+
+agentmemory は Windows 10/11 で動作しますが、Node.js パッケージだけでは不十分で、`iii-engine` ランタイム(別のネイティブバイナリ)もバックグラウンドプロセスとして必要です。公式の上流インストーラは `sh` スクリプトで、今のところ PowerShell インストーラや scoop/winget パッケージは存在しないため、Windows ユーザーには 2 つの経路があります:
+
+**選択肢 A — ビルド済み Windows バイナリ(推奨):**
+
+```powershell
+# 1. ブラウザで https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 を開く
+#    (engine v0.11.6+ が要求する新しいサンドボックスモデルへ
+#     agentmemory がリファクタリングされるまで v0.11.2 にピン留め)
+# 2. iii-x86_64-pc-windows-msvc.zip をダウンロード
+#    (ARM マシンの場合は iii-aarch64-pc-windows-msvc.zip)
+# 3. iii.exe を PATH 上のどこかに展開、または以下に配置:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory はこの場所を自動でチェックします)
+# 4. 確認:
+iii --version
+# 出力: 0.11.2
+
+# 5. その後 agentmemory を通常通り起動:
+npx -y @agentmemory/agentmemory
+```
+
+**選択肢 B — Docker Desktop:**
+
+```powershell
+# 1. Docker Desktop for Windows をインストール
+# 2. Docker Desktop を起動し、エンジンが動作中であることを確認
+# 3. agentmemory を実行 — 同梱の compose ファイルが自動起動します:
+npx -y @agentmemory/agentmemory
+```
+
+**選択肢 C — スタンドアロン MCP のみ(エンジンなし):** ���ージェント用に MCP ツールだけが必要で、REST API、ビューワー、cron ジョブが不要なら、エンジンを完全にスキップ:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# あるいは shim パッケージ経由:
+npx -y @agentmemory/mcp
+```
+
+**Windows の診断:** `npx @agentmemory/agentmemory` が失敗する場合、`--verbose` 付きで再実行して実際のエンジン stderr を確認してください。よくある失敗パターン:
+
+| 症状 | 修正 |
+|---|---|
+| `iii-engine process started` のあとに `did not become ready within 15s` | エンジンが起動時にクラッシュ — `--verbose` で再実行し stderr を確認 |
+| `Could not start iii-engine` | `iii.exe` も Docker もインストールされていない。上記の選択肢 A または B を参照 |
+| ポート競合 | `netstat -ano \| findstr :3111` でバインドを確認、kill するか `--port <N>` を使用 |
+| Docker をインストール済みなのにフォールバックがスキップされる | Docker Desktop が実際に動作している(システムトレイアイコン)ことを確認 |
+
+> 注意: `cargo install iii-engine` は存在しません — `iii` は crates.io に公開されていません。サポートされるインストール方法は、上記のビルド済みバイナリ、上流の `sh` インストールスクリプト(macOS/Linux のみ)、Docker イメージのみです。
+
+---
+
+<h2 id="deploy">デプロイ</h2>
+
+マネージドホスト向けのワンクリックテンプレート。それぞれが
+自己完結した Dockerfile を提供し、npm から
+`@agentmemory/agentmemory` を pull して公式の `iiidev/iii`
+Docker Hub イメージから iii engine バイナリをコピーします — 事前に
+ビルドした agentmemory イメージは不要です。永続ストレージは
+`/data` にマウントされます。初回起動の entrypoint は npm 同梱の
+iii 設定(`127.0.0.1` をバインド)をデプロイ向けに調整した
+設定(`0.0.0.0` をバインドし絶対 `/data` パスを使用)で上書きし、
+HMAC シークレットを生成、そして `gosu` で `root` から `node`
+に権限を落としてから agentmemory CLI を exec します。
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render のワンクリックデプロイボタンはリポジトリルートに `render.yaml` を要求しますが、ルートをあえて綺麗に保っています。[`deploy/render/`](../deploy/render/README.md) にドキュメント化された Render Blueprint フローを使い、リポジトリ内のブループリントを手動で指してください。
+
+完全なセットアップ詳細(HMAC キャプチャ、ビューワーの SSH トンネル、
+ローテーション、バックアップ、コスト下限)は
+[`deploy/`](../deploy/README.md) を参照:
+
+- [`deploy/fly`](../deploy/fly/README.md) — 単一マシンで
+  `auto_stop_machines = "stop"`、アイドル時最安。
+- [`deploy/railway`](../deploy/railway/README.md) — Hobby プラン定額、
+  ボリュームはダッシュボードで。
+- [`deploy/render`](../deploy/render/README.md) — Blueprint フロー、
+  有料プランで自動ディスクスナップショット。
+- [`deploy/coolify`](../deploy/coolify/README.md) — [Coolify](https://coolify.io/self-hosted)
+  経由で自前 VPS にセルフホスト。同じ Docker Compose
+  スタックで、ホストとデータは自分の手元に。
+
+公開されるのはポート `3111` のみです。`3113` のビューワーは
+コンテナ内でループバックにバインドされ続けます — 各テンプレートの
+README にそこへ到達する SSH トンネルパターンが記載されています。
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
+
+すべてのコーディングエージェントはセッションが終わるとすべてを忘れます。毎セッションの最初の 5 分をスタックの再説明に浪費しています。agentmemory はバックグラウンドで動作し、それを完全になくします。
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### 組み込みエージェントメモリとの比較
+
+すべての AI コーディングエージェントには組み込みのメモリが付属します — Claude Code には `MEMORY.md`、Cursor には notepad、Cline には memory bank。これらは付箋のようなものです。agentmemory はその付箋の背後にある検索可能なデータベースです。
+
+| | 組み込み (CLAUDE.md) | agentmemory |
+|---|---|---|
+| スケール | 200 行上限 | 無制限 |
+| 検索 | すべてをコンテキストにロード | BM25 + ベクトル + グラフ(top-K のみ) |
+| トークンコスト | 240 観測で 22K+ | ~1,900 tokens(92% 削減) |
+| クロスエージェント | エージェントごとのファイル | MCP + REST(任意のエージェント) |
+| 調整 | なし | リース、シグナル、アクション、ルーチン |
+| 可観測性 | 手動でファイルを読む | ポート 3113 のリアルタイムビューワー |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>
+
+### メモリパイプライン
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4 層メモリ統合
+
+人間の脳が記憶を処理する方法に着想を得ています — 睡眠時の記憶統合と通じるものがあります。
+
+| 層 | 内容 | 例え |
+|------|------|---------|
+| **Working(作業記憶)** | ツール使用からの生観測 | 短期記憶 |
+| **Episodic(エピソード記憶)** | 圧縮されたセッション要約 | 「何が起きたか」 |
+| **Semantic(意味記憶)** | 抽出された事実とパターン | 「何を知っているか」 |
+| **Procedural(手続き記憶)** | ワークフローと意思決定パターン | 「どうやるか」 |
+
+記憶は時間とともに減衰(エビングハウス曲線)。頻繁にアクセスされる記憶は強化されます。古い記憶は自動退避。矛盾は検出され解決されます。
+
+### 何をキャプチャするか
+
+| Hook | キャプチャ内容 |
+|------|----------|
+| `SessionStart` | プロジェクトパス、セッション ID |
+| `UserPromptSubmit` | ユーザープロンプト(プライバシーフィルタ済み) |
+| `PreToolUse` | ファイルアクセスパターン + コンテキスト富化 |
+| `PostToolUse` | ツール名、入力、出力 |
+| `PostToolUseFailure` | エラーコンテキスト |
+| `PreCompact` | コンパクション前にメモリを再注入 |
+| `SubagentStart/Stop` | サブエージェントのライフサイクル |
+| `Stop` | セッション終了時の要約 |
+| `SessionEnd` | セッション完了マーカー |
+
+### 主な機能
+
+| 機能 | 説明 |
+|---|---|
+| **自動キャプチャ** | hooks で毎ツール使用を記録 — 手動作業ゼロ |
+| **セマンティック検索** | BM25 + ベクトル + ナレッジグラフ、RRF 融合 |
+| **メモリ進化** | バージョン管理、上書き、関係グラフ |
+| **自動忘却** | TTL 期限切れ、矛盾検出、重要度退避 |
+| **プライバシー優先** | API キー、シークレット、`<private>` タグは保存前に除去 |
+| **自己修復** | サーキットブレーカー、プロバイダーフォールバックチェーン、ヘルスモニタ |
+| **Claude ブリッジ** | MEMORY.md と双方向同期 |
+| **ナレッジグラフ** | エンティティ抽出 + BFS 探索 |
+| **チームメモリ** | チームメンバー間で名前空間化された共有 + プライベート |
+| **引用の出所追跡** | あらゆるメモリを元の観測まで遡れる |
+| **Git スナップショット** | メモリ状態のバージョン、ロールバック、diff |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
+
+3 つのシグナルを組み合わせるトリプルストリーム検索:
+
+| ストリーム | 役割 | 起動条件 |
+|---|---|---|
+| **BM25** | ステミング付きキーワード一���と類義語拡張 | 常時有効 |
+| **Vector(ベクトル)** | 密埋め込みのコサイン類似度 | 埋め込みプロバイダー設定時 |
+| **Graph(グラフ)** | エンティティ一致によるナレッジグラフ探索 | クエリにエンティティ検出時 |
+
+Reciprocal Rank Fusion (RRF, k=60) で融合し、セッションで多様化(セッションあたり最大 3 件)。
+
+BM25 は箱から出してすぐにギリシャ文字、キリル文字、ヘブライ文字、アラビア文字、アクセント付きラテン文字をトークン化できます。中国語 / 日本語 / 韓国語のメモリには、オプションのセグメンタ(`npm install @node-rs/jieba tiny-segmenter`)をインストールして CJK 連続を単語レベルのトークンに分割してください。インストールしない場合、agentmemory は連続全体をそのままトークン化するソフトフォールバックに切り替わり、stderr に一度だけヒントを出します。
+
+### 埋め込みプロバイダー
+
+agentmemory はプロバイダーを自動検出します。最良の結果を得るには、ローカル埋め込み(無料)をインストール:
+
+```bash
+npm install @xenova/transformers
+```
+
+| プロバイダー | モデル | コスト | 備考 |
+|---|---|---|---|
+| **ローカル(推奨)** | `all-MiniLM-L6-v2` | 無料 | オフライン、BM25 単独より召集率 +8pp |
+| Gemini | `gemini-embedding-001` | 無料枠 | 100+ 言語、768/1536/3072 次元 (MRL)、2048 トークン入力。`text-embedding-004` の後継([非推奨、2026 年 1 月 14 日に停止](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | 最高品質 |
+| Voyage AI | `voyage-code-3` | 有料 | コード向け最適化 |
+| Cohere | `embed-english-v3.0` | 無料試用 | 汎用 |
+| OpenRouter | 任意のモデル | 場合による | マルチモデルプロキシ |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>
+
+53 ツール、6 リソース、3 プロンプト、4 skills — あらゆるエージェント向けで最も充実した MCP メモリツールキット。
+
+> **MCP shim とフルサーバー:** 公開されている `@agentmemory/mcp` パッケージは薄い shim です。**`AGENTMEMORY_URL` 経由で動作中の agentmemory サーバーに到達できる場合に限り**、完全な 51 ツール群を公開します(プロキシモード)。サーバーに到達できない場合、shim は 7 ツールのローカルセット(`memory_save`、`memory_recall`、`memory_smart_search`、`memory_sessions`、`memory_export`、`memory_audit`、`memory_governance_delete`)にフォールバックします。`AGENTMEMORY_TOOLS=core|all` 環境変数は*サーバー側*のフラグです — shim の `env` ブロックで設定しても効果はありません。Cursor / OpenCode / Gemini CLI で 7 ツールしか見えない場合は、`npx @agentmemory/agentmemory`(または Docker スタック)を起動し、`AGENTMEMORY_URL=http://localhost:3111` を設定してください。
+
+### 51 ツール
+
+<details>
+<summary>コアツール(常時利用可能)</summary>
+
+| ツール | 説明 |
+|------|-------------|
+| `memory_recall` | 過去の観測を検索 |
+| `memory_compress_file` | 構造を保持したまま markdown ファイルを圧縮 |
+| `memory_save` | 洞察、決定、パターンを保存 |
+| `memory_patterns` | 繰り返し現れるパターンを検出 |
+| `memory_smart_search` | ハイブリッドなセマンティック + キーワード検索 |
+| `memory_file_history` | 特定ファイルに関する過去の観測 |
+| `memory_sessions` | 最近のセッション一覧 |
+| `memory_timeline` | 時系列の観測 |
+| `memory_profile` | プロジェクトプロファイル(概念、ファイル、パターン) |
+| `memory_export` | すべてのメモリデータをエクスポート |
+| `memory_relations` | 関係グラフを照会 |
+
+</details>
+
+<details>
+<summary>拡張ツール(全 51 — AGENTMEMORY_TOOLS=all を設定)</summary>
+
+| ツール | 説明 |
+|------|-------------|
+| `memory_patterns` | 繰り返し現れるパターンを検出 |
+| `memory_timeline` | 時系列の観測 |
+| `memory_relations` | 関係グラフを照会 |
+| `memory_graph_query` | ナレッジグラフ探索 |
+| `memory_consolidate` | 4 層統合を実行 |
+| `memory_claude_bridge_sync` | MEMORY.md と同期 |
+| `memory_team_share` | チームメンバーと共有 |
+| `memory_team_feed` | 最近の共有アイテム |
+| `memory_audit` | 操作の監査証跡 |
+| `memory_governance_delete` | 監査証跡付き削除 |
+| `memory_snapshot_create` | Git バージョンスナップショット |
+| `memory_action_create` | 依存関係付き作業項目を作成 |
+| `memory_action_update` | アクションのステータス更新 |
+| `memory_frontier` | 優先度順のブロック解除済みアクション |
+| `memory_next` | 次に最も重要なアクション 1 つ |
+| `memory_lease` | 排他的アクションリース(マルチエージェント) |
+| `memory_routine_run` | ワークフロー ルーチンをインスタンス化 |
+| `memory_signal_send` | エージェント間メッセージング |
+| `memory_signal_read` | 受領確認付きでメッセージを読む |
+| `memory_checkpoint` | 外部条件ゲート |
+| `memory_mesh_sync` | インスタンス間 P2P 同期 |
+| `memory_sentinel_create` | イベント駆動ウォッチャー |
+| `memory_sentinel_trigger` | 外部からセンチネルを発火 |
+| `memory_sketch_create` | 一時的なアクショングラフ |
+| `memory_sketch_promote` | 永続化に昇格 |
+| `memory_crystallize` | アクションチェーンをコンパクト化 |
+| `memory_diagnose` | ヘルスチェック |
+| `memory_heal` | 詰まった状態を自動修復 |
+| `memory_facet_tag` | 次元:値タグ |
+| `memory_facet_query` | facet タグで照会 |
+| `memory_verify` | 出所を追跡 |
+
+</details>
+
+### 6 リソース · 3 プロンプト · 4 Skills
+
+| 種類 | 名前 | 説明 |
+|------|------|-------------|
+| Resource | `agentmemory://status` | ヘルス、セッション数、メモリ数 |
+| Resource | `agentmemory://project/{name}/profile` | プロジェクト別インテリジェンス |
+| Resource | `agentmemory://memories/latest` | 直近 10 件のアクティブメモリ |
+| Resource | `agentmemory://graph/stats` | ナレッジグラフ統計 |
+| Prompt | `recall_context` | 検索してコンテキストメッセージを返す |
+| Prompt | `session_handoff` | エージェント間でのハンドオフデータ |
+| Prompt | `detect_patterns` | 繰り返し現れるパターンを分析 |
+| Skill | `/recall` | メモリを検索 |
+| Skill | `/remember` | 長期メモリに保存 |
+| Skill | `/session-history` | 最近のセッション要約 |
+| Skill | `/forget` | 観測/セッションを削除 |
+
+### スタンドアロン MCP
+
+フルサーバーなしで実行 — 任意の MCP クライアント向け。以下のどちらも動きます:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # 正規(常時利用可能)
+npx -y @agentmemory/mcp                # shim パッケージのエイリアス
+```
+
+またはエージェントの MCP 設定に追加:
+
+ほとんどのエージェント(Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+`agentmemory` エントリはホストの既存 `mcpServers` オブジェクトにマージし、ファイル全体を置き換えないでください。ホストの `localhost` に到達できないサンドボックスクライアントには、env ブロックに `"AGENTMEMORY_FORCE_PROXY": "1"` を追加し、`AGENTMEMORY_URL` をサンドボックスが到達できる経路に設定してください。
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+リポジトリからプラグインファイルをコピー:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
+
+ポート `3113` で自動起動。ライブ観測ストリーム、セッションエクスプローラ、メモリブラウザ、ナレッジグラフの可視化、ヘルスダッシュボード。
+
+```bash
+open http://localhost:3113
+```
+
+ビューワーサーバーはデフォルトで `127.0.0.1` にバインドします。REST 経由の `/agentmemory/viewer` エンドポイントは通常の `AGENTMEMORY_SECRET` ベアラートークン規則に従います。CSP ヘッダーはレスポンスごとのスクリプト nonce を使い、インラインハンドラ属性は無効化(`script-src-attr 'none'`)。
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+`:3113` のビューワーはエージェントが**覚えた**ことを見せます。[iii コンソール](https://iii.dev/docs/console)はエージェントが**やった**ことを見せます — 各メモリ操作は OpenTelemetry トレース、各 KV エントリは編集可能、各 function は呼び出し可能、各ストリームは tap 可能。同じメモリへの 2 つの窓: 一方はプロダクト形、もう一方はエンジン形。
+
+`memory_smart_search` の発火を眺め、BM25 スキャン → 埋め込み参照 → RRF 融合 → リランカーをウォーターフォールで見ます。KV ブラウザで詰まった統合タイマーを編集します。調整したペイロードで `PostToolUse` hook を再生します。WebSocket ストリームをピンして観測がライブで着地するのを眺めます。
+
+agentmemory はこれを無料で提供します。すべての function、トリガー、ステートスコープ、ストリームが iii プリミティブだからです — カスタム実装も計装も必要ありません。
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
+  <br/>
+  <em>Workers ページ: agentmemory 自身を含む、接続中のすべての worker と PID、function 数、ランタイム、最終応答時刻。</em>
+</p>
+
+**インストール済みです。** コンソールは `iii` に同梱 — 別途インストーラはありません。
+
+**agentmemory と並行して起動:**
+
+```bash
+# agentmemory ビューワーがポート 3113 を握っているので、コンソールは 3114 で実行します。
+# エンジン REST (3111)、WebSocket (3112)、bridge (49134) のデフォルトは agentmemory と一致します。
+iii console --port 3114
+```
+
+その後 `http://localhost:3114` を開きます。`--enable-flow` で実験的なアーキテクチャグラフページを有効化します。
+
+エンジンエンドポイントを移動した場合のみ上書き:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**コンソールでできること:**
+
+| ページ | 用途 |
+|------|-----------|
+| **Workers** | agentmemory worker 自身を含む、接続中の各 worker とライブメトリクスを表示。 |
+| **Functions** | JSON ペイロードを与えて agentmemory の任意の function を直接呼び出し — クライアントを配線せずに `memory.recall`、`memory.consolidate`、`graph.query` をテストできて便利。 |
+| **Triggers** | HTTP、cron、イベント、ステートのトリガーを再生 — 統合 cron を手動で発火、HTTP ルートを再試行、ステート変更を発行。 |
+| **States** | フル CRUD の KV ブラウザ — セッション、メモリスロット、ライフサイクルタイマー、埋め込みインデックス — その場で値を編集。 |
+| **Streams** | メモリ書き込み、hook イベント、観測更新が iii ストリームを流れる様子をライブで監視する WebSocket モニタ。 |
+| **Queues** | 永続キューのトピック + デッドレター管理。失敗した埋め込み / 圧縮ジョブを再生または破棄。 |
+| **Traces** | OpenTelemetry のウォーターフォール / フレーム / サービスブレークダウン。`trace_id` でフィルタすれば、単一の `memory.search` がどの function、DB 呼び出し、埋め込みリクエストを生んだか正確にわかります。 |
+| **Logs** | 構造化 OTEL ログをフィルタし、trace/span ID と相関付け。 |
+| **Config** | ランタイム設定 — エンジンがどの worker、プロバイダー、ポートで動いているか確認。 |
+| **Flow** | (オプション、`--enable-flow`)各 worker、トリガー、ストリームの対話型アーキテクチャグラフ。 |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
+  <br/>
+  <em>Traces: すべてのメモリ操作についてウォーターフォール / フレーム / サービスブレークダウン。</em>
+</p>
+
+**Traces は既にオン:**
+
+`iii-config.yaml` は出荷時から `iii-observability` worker を有効化(`exporter: memory`、`sampling_ratio: 1.0`、メトリクス + ログ)。追加設定不要 — agentmemory が起動した瞬間に、すべてのメモリ操作がトレーススパンとコンソールが読み取れる構造化ログを出します。
+
+代わりに Jaeger / Honeycomb / Grafana Tempo へエクスポートしたい場合は、`exporter: memory` を `exporter: otlp` に変更し、iii の可観測性ドキュメントに従ってコレクタエンドポイントを設定してください。
+
+> **注意:** コンソール自身に認証は強制されていません — デフォルトの `127.0.0.1` バインドのままにし、決して公開しないでください。
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory は**それ自体が稼働中の [iii](https://iii.dev) インスタンス**です。function、トリガー、KV ステート、ストリーム、OTEL トレース — すべてが iii プリミティブです。Postgres、Redis、Express、pm2、Prometheus をインストールしなかったのは、iii がそれらを置き換えるからです。
+
+つまり、もう 1 つのコマンドで agentmemory にまったく新しい機能を拡張できます。
+
+### 1 つのコマンドで agentmemory を拡張
+
+```bash
+iii worker add iii-pubsub          # メモリ書き込みを接続中のすべてのインスタンスに fan-out
+iii worker add iii-cron            # スケジュール統合、減衰スイープ、スナップショットローテーション
+iii worker add iii-queue           # 埋め込み + 圧縮ジョブの永続リトライ
+iii worker add iii-observability   # すべてのメモリ操作に OTEL トレース(デフォルト オン)
+iii worker add iii-sandbox         # リコールしたコードを隔離 microVM 内で実行
+iii worker add iii-database        # SQL バックエンドのステートアダプタに切り替え
+iii worker add mcp                 # agentmemory MCP の横に汎用 MCP ホストを立てる
+```
+
+各 `iii worker add` は新しい function とトリガーを、agentmemory が既に動いているのと同じエンジンに登録します。ビューワーとコンソールがすぐに拾い上げます — リロード不要、新しい統合不要、新しいコンテナ不要。
+
+| `iii worker add` | agentmemory の上に得られるもの |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | マルチインスタンスメモリ: すべての `remember` が fan-out、すべての `search` が和集合を読む |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | スケジュールされたライフサイクル — 夜間統合、週次スナップショット、固定クロックでの減衰 |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | 永続リトライ: 失敗した埋め込み + 圧縮ジョブが再起動を生き延び、観測は失われない |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | すべての function に OTEL トレース、メトリクス、ログ — 初日から `iii-config.yaml` に配線済み |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` から出てきたコードはあなたのシェルではなく使い捨て VM 内で実行 |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | デフォルトのインメモリ KV では足りないときの SQL バックエンドのステートアダプタ |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory の隣に追加の MCP サーバーを立て、同じエンジンを共有 |
+
+完全なレジストリ:[workers.iii.dev](https://workers.iii.dev)。そこにあるすべての worker は agentmemory が使っているのと同じプリミティブで組み立てられています — そして既に手元にある agentmemory もその 1 つです。
+
+### iii が置き換えるもの
+
+| 従来のスタック | agentmemory が使うもの |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + インメモリベクトルインデックス |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker 監視 |
+| Prometheus / Grafana | iii OTEL + ヘルスモニタ |
+| カスタムプラグインシステム | `iii worker add <name>` |
+
+**118 ソースファイル · ~21,800 LOC · 950+ テスト · 123 functions · 34 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### LLM プロバイダー
+
+agentmemory は環境から自動検出します。デフォルトでは、プロバイダーを設定するか Claude 購読フォールバックに明示的にオプトインしない限り、LLM 呼び出しは行いません。
+
+| プロバイダー | 設定 | 備考 |
+|----------|--------|-------|
+| **No-op(デフォルト)** | 設定不要 | LLM 駆動の compress/summarize は無効。合成 BM25 圧縮 + リコールは引き続き動作。以前 Claude 購読フォールバックに依存していた場合は、下記の `AGENTMEMORY_ALLOW_AGENT_SDK` を参照。 |
+| Anthropic API | `ANTHROPIC_API_KEY` | トークン単位課金 |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic 互換 |
+| Gemini | `GEMINI_API_KEY` | 埋め込みも有効化 |
+| OpenRouter | `OPENROUTER_API_KEY` | 任意のモデル |
+| Claude 購読フォールバック | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | オプトインのみ。`@anthropic-ai/claude-agent-sdk` セッションを生成 — 過去に無限の Stop-hook 再帰(#149 のフォローアップ)を引き起こしたため、もはやデフォルトではありません。 |
+
+### コストを意識したモデル選択
+
+バックグラウンド圧縮は観測のたびに走るため、モデル選択は月額支出に大きく効きます。記録されたワークロード: 635 リクエスト / 888K トークン / 35 時間のアクティブ使用、2026-05-23 時点の OpenRouter 価格で 3 モデルを比較。
+
+| 階層 | モデル | 入力 / 1M | 出力 / 1M | 35 時間のワークロードでのコスト | 備考 |
+|------|-------|------------|-------------|---------------------------|-------|
+| 推奨 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | 圧縮 + 要約品質が手堅く、Sonnet の約 10 分の 1 のコスト。 |
+| 推奨 | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | やや古めだが圧縮のみのワークロードには十分。 |
+| 推奨 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | セッションがコード中心ならコード推論が強い。 |
+| プレミアム | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | 品質は高いが常時稼働のバックグラウンドには高価。 |
+| プレミアム | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Sonnet と同階層。 |
+| 回避 | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | 推論クラスのモデル。圧縮には大幅な過剰支出。 |
+
+agentmemory は `OPENROUTER_MODEL` がプレミアム階層パターンと一致するときランタイム警告を表示します。納得して選んだあとは `AGENTMEMORY_SUPPRESS_COST_WARNING=1` で消音できます。
+
+メモリ作業における品質対コストのトレードオフ: 圧縮は品質のハードルが比較的緩い要約タスクです(要約を読み返すのはエージェントであってユーザーではありません)。DeepSeek-V4-Pro / Qwen3-Coder はこのタスクで Sonnet と誤差範囲に収まる一方、コストは約 10 分の 1 です。プレミアム階層のモデルは、あなたが直接読むクエリに取っておきましょう。
+
+出典:[OpenRouter の Sonnet 4.6 価格](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing)、[DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro)、[DeepSeek の価格に関する注](https://api-docs.deepseek.com/quick_start/pricing/)。
+
+### マルチエージェントメモリ(`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+複数のロール(architect / developer / reviewer / researcher / support-agent)が 1 つの agentmemory サーバーを共有するマルチエージェント構成では、`AGENT_ID` がすべての書き込みに発信したロールのタグを付けます。`AGENTMEMORY_AGENT_SCOPE` はリコールがそのタグでフィルタするかどうかを制御します。
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # 任意、デフォルトは "shared"
+```
+
+2 つのモード:
+
+| モード | 書き込みにタグ | リコールでフィルタ | 使いどころ |
+|------|------------|---------------|-------------|
+| `shared`(デフォルト) | はい | いいえ | 監査証跡付きのクロスエージェントコンテキスト。Architect は developer のメモを見られるが、各行に発言者が記録されます。 |
+| `isolated` | はい | はい | 厳格分離。Architect は developer の観測 / メモリ / セッションを決して見られません。 |
+
+`AGENT_ID` が設定されたときにタグ付けされるもの:`Session.agentId`、`RawObservation.agentId`、`CompressedObservation.agentId`、`Memory.agentId`。ロールは `api::session::start` → `mem::observe` → `mem::compress` → KV を流れます。
+
+isolated モードでフィルタされるもの:`mem::smart-search`、`/agentmemory/memories`、`/agentmemory/observations`、`/agentmemory/sessions`。各エンドポイントはリクエスト単位でオーバーライドする `?agentId=<role>` を受け付け、`?agentId=*` で環境スコープから完全にオプトアウトできます。`/memories` はさらに `?includeOrphans=true` を受け付け、`agentId` が undefined の AGENT_ID 導入前のメモリを浮上させます。
+
+SDK / REST 層での呼び出し単位オーバーライド: すべての変更系エンドポイント(`/session/start`、`/remember`)はリクエストボディに `agentId` フィールドを受け付け、環境変数より優先されます。1 つのサーバープロセス経由で多数のロールをルーティングするランタイムに便利です。
+
+`AGENT_ID` が未設定の場合、メモリはスコープなしのまま(従来の挙動、タグなし・フィルタなし)。
+
+### ポート
+
+agentmemory + iii-engine はデフォルトで 4 つのポートをバインドします。再起動が `port in use` で失敗する場合、この表でどのプロセスを探せばよいか分かります。
+
+| ポート | プロセス | 用途 | 環境変数で上書き |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | 内部ストリーム worker(agentmemory + ビューワーが消費) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | リアルタイムビューワー(`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — worker はここに登録、OTel テレメトリもここを流れる | `III_ENGINE_URL`(完全 URL、デフォルト `ws://localhost:49134`) |
+
+クラッシュ後にポートが解放されないときの古いプロセス整理:
+
+```bash
+# macOS / Linux — 各ポートで動いているものを探して kill
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` は正常終了時に worker と engine の pidfile を綺麗に回収します(#640、#474)。上の手動クリーンアップは、どちらの pidfile も残っていないクラッシュ後の状態を対象とします。
+
+### 設定ファイル
+
+agentmemory のランタイム設定は、各シェルで変数を export するのではなく `~/.agentmemory/.env` に置いてください。ビューワーが `export ANTHROPIC_API_KEY=...` のようなセットアップヒントを表示したら、これをこのファイルに `ANTHROPIC_API_KEY=...` として(`export` プレフィックスなしで)コピーしてから agentmemory を再起動してください。
+
+プロセスの環境変数も引き続き有効で、ファイルの値より優先されます。
+
+Windows では同じファイルが `%USERPROFILE%\.agentmemory\.env` にあります:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+API キーの代わりに Claude Code Pro/Max 購読でテストするには、明示的にオプトイン:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+グラフや統合の機能を使いたい場合は同じファイルでオン:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### 環境変数
+
+`~/.agentmemory/.env` を作成:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+ポート `3111` 上の 124 エンドポイント。REST API はデフォルトで `127.0.0.1` にバインドします。`AGENTMEMORY_SECRET` が設定されている場合、保護されたエンドポイントは `Authorization: Bearer <secret>` を要求し、mesh sync エンドポイントは両ピアで `AGENTMEMORY_SECRET` を要求します。
+
+<details>
+<summary>主要エンドポイント</summary>
+
+| メソッド | パス | 説明 |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | ヘルスチェック(常に公開) |
+| `POST` | `/agentmemory/session/start` | セッシ���ン開始 + コンテキスト取得 |
+| `POST` | `/agentmemory/session/end` | セッション終了 |
+| `POST` | `/agentmemory/observe` | 観測キャプチャ |
+| `POST` | `/agentmemory/smart-search` | ハイブリッド検索 |
+| `POST` | `/agentmemory/context` | コンテキスト生成 |
+| `POST` | `/agentmemory/remember` | 長期メモリに保存 |
+| `POST` | `/agentmemory/forget` | 観測の削除 |
+| `POST` | `/agentmemory/enrich` | ファイルコンテキスト + メモリ + bug |
+| `GET` | `/agentmemory/profile` | プロジェクトプロファイル |
+| `GET` | `/agentmemory/export` | 全データをエクスポート |
+| `POST` | `/agentmemory/import` | JSON からインポート |
+| `POST` | `/agentmemory/graph/query` | ナレッジグラフ照会 |
+| `POST` | `/agentmemory/team/share` | チームと共有 |
+| `GET` | `/agentmemory/audit` | 監査証跡 |
+
+完全なエンドポイント一覧:[`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
+
+```bash
+npm run dev               # ホットリロード
+npm run build             # 本番ビルド
+npm test                  # 950+ テスト
+npm run test:integration  # API テスト(サービス起動が必要)
+```
+
+**前提:** Node.js >= 20、[iii-engine](https://iii.dev/docs) または Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.ko-KR.md

@@ -0,0 +1,1361 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — AI 코딩 에이전트를 위한 영구 메모리" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    코딩 에이전트가 모든 것을 기억합니다. 더 이상 다시 설명할 필요가 없습니다.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode 및 모든 MCP 클라이언트를 위한 영구 메모리입니다.
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  한국어 |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="설계 문서: gist 기준 1200 stars / 172 forks" /></a>
+</p>
+
+<p align="center">
+  <em>이 gist는 Karpathy의 LLM Wiki 패턴을 신뢰도 점수, 라이프사이클, 지식 그래프, 하이브리드 검색으로 확장한 것입니다. agentmemory는 그 구현체입니다.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory 데모" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">설치</a> &bull;
+  <a href="#quick-start">빠른 시작</a> &bull;
+  <a href="#benchmarks">벤치마크</a> &bull;
+  <a href="#vs-competitors">경쟁 제품 비교</a> &bull;
+  <a href="#works-with-every-agent">에이전트</a> &bull;
+  <a href="#how-it-works">동작 방식</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">뷰어</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">설정</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # start the memory server on :3111
+agentmemory demo                                 # seed sample sessions + prove recall
+agentmemory connect claude-code                  # wire your agent (also: codex, cursor, gemini-cli, ...)
+```
+
+또는 `npx`로 설치 없이 실행:
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+참고 — npx는 버전별로 캐싱합니다. 단순한 `npx @agentmemory/agentmemory`가 이전 릴리스를 제공한다면, `npx -y @agentmemory/agentmemory@latest`로 최신 버전을 강제로 가져오거나 `rm -rf ~/.npm/_npx`로 캐시를 한 번 비우십시오(macOS/Linux. Windows에서는 `%LOCALAPPDATA%\npm-cache\_npx`를 삭제). v0.9.16부터의 첫 npx 실행은 전역 설치 여부를 인라인으로 묻기 때문에, 이후에는 어디서나 단순한 `agentmemory` 명령이 동작합니다.
+
+전체 옵션은 아래 [빠른 시작](#quick-start)을 참고하십시오. 에이전트별 연결 방법은 [모든 에이전트와 호환](#works-with-every-agent) 섹션에서 확인할 수 있습니다.
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="모든 에이전트와 호환" height="32" /></picture></h2>
+
+agentmemory는 hooks, MCP, REST API를 지원하는 모든 에이전트와 호환됩니다. 모든 에이전트는 동일한 메모리 서버를 공유합니다.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>native plugin + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>native plugin + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>native Memory trait backend</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>MCP 또는 HTTP를 지원하는 <strong>모든</strong> 에이전트와 호환됩니다. 서버 하나, 모든 에이전트가 메모리를 공유합니다.</sub>
+</p>
+
+---
+
+세션마다 같은 아키텍처를 설명하고, 같은 버그를 다시 찾고, 같은 선호 사항을 다시 가르치게 됩니다. 내장 메모리(CLAUDE.md, .cursorrules)는 200줄 한도에서 멈추고 금세 낡습니다. agentmemory가 이 문제를 해결합니다. 에이전트의 동작을 조용히 캡처하여 검색 가능한 메모리로 압축하고, 다음 세션이 시작될 때 적절한 컨텍스트를 주입합니다. 명령 하나면 됩니다. 모든 에이전트에서 동작합니다.
+
+**무엇이 바뀌는가:** 세션 1에서 JWT 인증을 설정합니다. 세션 2에서 rate limiting을 요청합니다. 에이전트는 이미 인증이 `src/middleware/auth.ts`의 jose 미들웨어로 처리된다는 것, 테스트가 토큰 검증을 다룬다는 것, 그리고 Edge 호환성 때문에 jsonwebtoken 대신 jose를 선택했다는 것을 알고 있습니다. 다시 설명할 필요도, 복사·붙여넣기도 필요 없습니다. 에이전트가 그냥 *알고* 있습니다.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **v0.9.0의 새로운 기능** — [agent-memory.dev](https://agent-memory.dev)의 랜딩 사이트, 파일시스템 커넥터(`@agentmemory/fs-watcher`), 독립형 MCP가 이제 실행 중인 서버로 프록시되어 hooks와 뷰어가 일치합니다. 모든 삭제 경로에 감사 정책이 코드로 명문화되었고, 작은 Node 프로세스에서 health가 `memory_critical`로 잘못 표시되지 않습니다. 전체 노트는 [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18)에서 확인할 수 있습니다.
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="벤치마크" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### 검색 정확도
+
+**coding-agent-life-v1** (자체 코퍼스, 샌드박스 재현 가능)
+
+| 어댑터 | P@5 | R@5 | Top-5 적중률 | p50 지연 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep baseline | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+Top-5 적중률 100%. 동일한 입력에서 grep 기준선 대비 정밀도가 **2.2배** 더 높습니다. 유형별 전체 분석은 다음에서 확인할 수 있습니다: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500개 질문)
+
+| 시스템 | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### 토큰 절감
+
+| 방식 | 연간 토큰 | 연간 비용 |
+|---|---|---|
+| 전체 컨텍스트를 매번 붙여넣기 | 19.5M+ | 불가능(컨텍스트 윈도우 초과) |
+| LLM 요약 | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + 로컬 임베딩 | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> 임베딩 모델: `all-MiniLM-L6-v2` (로컬, 무료, API 키 불필요). 전체 보고서: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). 경쟁 제품 비교: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory 대 mem0, Letta, Khoj, claude-mem, Hippo.
+
+**로컬 재현 방법:** [`eval/README.md`](../eval/README.md) — LongMemEval `_s`(공개 500-Q)와 `coding-agent-life-v1`(자체 15-세션 코퍼스)을 위한 어댑터 플러그형 하니스. grep / vector / agentmemory 어댑터를 나란히 평가하고, NDJSON으로 출력하며, 게시된 스코어카드는 [`docs/benchmarks/`](../docs/benchmarks/)에 보관됩니다.
+
+**다음과 함께 사용하기 좋습니다: [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), [Graphify](https://github.com/safishamsi/graphify).** 코드 그래프 인덱싱, 멀티 에이전트 빌드 파이프라인, 그리고 docs/PDF/이미지/비디오에 걸친 더 넓은 지식 그래프. agentmemory는 작업을 기억하고, 이 세 프로젝트는 나머지 컨텍스트 레이어를 밝혀줍니다. 레시피와 질문 라우팅 표: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="경쟁 제품 비교" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">내장 메모리 (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>유형</strong></td>
+<td>메모리 엔진 + MCP 서버</td>
+<td>메모리 레이어 API</td>
+<td>완전한 에이전트 런타임</td>
+<td>정적 파일</td>
+</tr>
+<tr>
+<td><strong>검색 R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>해당 없음 (grep)</td>
+</tr>
+<tr>
+<td><strong>자동 캡처</strong></td>
+<td>12 hooks (수동 작업 없음)</td>
+<td>수동 <code>add()</code> 호출</td>
+<td>에이전트 자체 편집</td>
+<td>수동 편집</td>
+</tr>
+<tr>
+<td><strong>검색</strong></td>
+<td>BM25 + Vector + Graph (RRF 융합)</td>
+<td>Vector + Graph</td>
+<td>Vector (archival)</td>
+<td>모든 것을 컨텍스트에 로드</td>
+</tr>
+<tr>
+<td><strong>멀티 에이전트</strong></td>
+<td>MCP + REST + leases + signals</td>
+<td>API (조정 없음)</td>
+<td>Letta 런타임 내에서만</td>
+<td>에이전트별 파일</td>
+</tr>
+<tr>
+<td><strong>프레임워크 종속성</strong></td>
+<td>없음 (모든 MCP 클라이언트)</td>
+<td>없음</td>
+<td>높음 (Letta 사용 필수)</td>
+<td>에이전트별 포맷</td>
+</tr>
+<tr>
+<td><strong>외부 의존성</strong></td>
+<td>없음 (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + 벡터 DB</td>
+<td>없음</td>
+</tr>
+<tr>
+<td><strong>메모리 라이프사이클</strong></td>
+<td>4-tier 통합 + 감쇠 + 자동 망각</td>
+<td>수동적 추출</td>
+<td>에이전트 관리</td>
+<td>수동 정리</td>
+</tr>
+<tr>
+<td><strong>토큰 효율</strong></td>
+<td>세션당 ~1,900 토큰 ($10/년)</td>
+<td>통합 방식에 따라 다름</td>
+<td>핵심 메모리는 컨텍스트에 상주</td>
+<td>관측 240개 기준 22K+ 토큰</td>
+</tr>
+<tr>
+<td><strong>실시간 뷰어</strong></td>
+<td>있음 (port 3113)</td>
+<td>클라우드 대시보드</td>
+<td>클라우드 대시보드</td>
+<td>없음</td>
+</tr>
+<tr>
+<td><strong>셀프 호스팅</strong></td>
+<td>예 (기본)</td>
+<td>선택 사항</td>
+<td>선택 사항</td>
+<td>예</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="빠른 시작" height="32" /></picture></h2>
+
+호환성: 이 릴리스는 안정 버전 `iii-sdk` `^0.11.0`과 iii-engine v0.11.x를 대상으로 합니다.
+
+### 30초 만에 사용해 보기
+
+```bash
+# Terminal 1: start the server
+npx @agentmemory/agentmemory
+
+# Terminal 2: seed sample data and see recall in action
+npx @agentmemory/agentmemory demo
+```
+
+`demo`는 현실적인 세션 3개(JWT 인증, N+1 쿼리 수정, rate limiting)를 시드하고, 그 위에서 시맨틱 검색을 실행합니다. "database performance optimization"으로 검색하면 "N+1 query fix"를 찾는 것을 확인할 수 있는데, 키워드 매칭으로는 불가능한 결과입니다.
+
+`http://localhost:3113`을 열어서 메모리가 실시간으로 쌓이는 것을 지켜보십시오.
+
+### 권장: 전역 설치
+
+`npx`는 버전별로 캐싱합니다. 지난주에 `npx @agentmemory/agentmemory@0.9.14`를 실행했다면, 단순한 `npx @agentmemory/agentmemory`는 최신 릴리스가 아니라 `~/.npm/_npx/`에 캐시된 0.9.14를 제공할 수 있습니다. 한 번 설치하면 단순한 `agentmemory` 명령이 어디서나 동작합니다:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # start the server (same as the npx form)
+agentmemory stop               # tear it down
+agentmemory remove             # uninstall everything we created
+agentmemory connect claude-code   # wire one agent
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+v0.9.16 이후부터 첫 npx 실행은 인라인으로 전역 설치 여부를 묻습니다 — `Y`로 한 ���만 답하면 설정이 끝납니다. 만약 건너뛰었다면, 새로 가져오기 위해 다음 중 하나를 사용하십시오:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)
+```
+
+Windows / PowerShell에서 동일한 캐시 비우기는 `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"`입니다 — 위의 `npx -y ...@latest`가 크로스 플랫폼 옵션입니다.
+
+### 세션 리플레이
+
+agentmemory가 기록한 모든 세션은 재생 가능합니다. 뷰어를 열어 **Replay** 탭을 선택하고 타임라인을 스크럽하면 프롬프트, 도구 호출, 도구 결과, 응답이 별개의 이벤트로 렌더링됩니다. 재생/일시정지, 속도 제어(0.5×–4×), 키보드 단축키(space로 토글, 화살표로 단계 이동)를 모두 지원합니다.
+
+가져오고 싶은 기존 Claude Code JSONL 트랜스크립트가 있습니까?
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx @agentmemory/agentmemory import-jsonl
+
+# Or import a single file
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+가져온 세션은 네이티브 세션과 함께 Replay 선택기에 표시됩니다. 내부적으로 각 항목은 `mem::replay::load`, `mem::replay::sessions`, `mem::replay::import-jsonl` iii 함수로 라우팅됩니다 — 별도의 사이드 채널 서버 없이.
+
+### 업그레이드 / 유지보수
+
+로컬 런타임을 의도적으로 업데이트할 때는 maintenance 명령을 사용하십시오:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, `cargo install iii-engine --force`를 실행할 수도 있고, Docker 이미지를 pull할 수도 있습니다.
+
+구현 세부 사항은 `src/cli.ts`에 있습니다 (`runUpgrade`는 `src/cli.ts:544-595` 부근 참고).
+
+### Claude Code (블록 한 번, 붙여넣기)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### 플러그인 설치 없이 Claude Code 사용 (MCP-독립형 경로)
+
+`/plugin install` 대신 `~/.claude.json`을 통해 agentmemory의 MCP 서버를 직접 연결한 경우, Claude Code는 `${CLAUDE_PLUGIN_ROOT}`를 해석하지 못하므로 `~/.claude/settings.json`의 hook 스크립트를 절대 경로로 지정해야 합니다. 이 경로들은 일반적으로 agentmemory 버전을 포함하기 때문에 (예: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), 다음 업그레이드에서 모든 hook이 조용히 깨질 수 있습니다 ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+해결책:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+이 명령은 현재 설치된 `@agentmemory/agentmemory` 패키지의 번들된 `plugin/` 디렉터리로 해석된 절대 경로로 동일한 hook 명령을 `~/.claude/settings.json`에 병합합니다. agentmemory를 업그레이드한 후 동일한 명령을 다시 실행하여 경로를 갱신하십시오. 동일한 파일의 사용자 항목은 보존되며, 이전 agentmemory 항목만 교체됩니다. `/plugin install` 경로를 사용하는 것이 여전히 권장 방식입니다.
+원격 또는 보호된 배포의 경우, `AGENTMEMORY_URL`과 `AGENTMEMORY_SECRET`을 설정한 채로 Claude Code를 실행하십시오. 플러그인은 두 값을 모두 번들된 MCP 서버로 전달합니다. `AGENTMEMORY_URL`이 비어 있을 때는 MCP shim이 `http://localhost:3111`을 사용합니다.
+
+### Codex CLI (Codex 플러그인 플랫폼)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex 플러그인은 Claude Code 플러그인과 동일한 `plugin/` 디렉터리에서 제공됩니다. 다음을 등록합니다:
+
+- `@agentmemory/mcp`를 MCP 서버로 등록 (`AGENTMEMORY_URL`이 실행 중인 agentmemory 서버를 가리킬 때 51개 도구 모두 프록시. 도달 가능한 서버가 없으면 로컬에서 7개 도구로 폴백)
+- 6개 라이프사이클 hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4개 skills: `/recall`, `/remember`, `/session-history`, `/forget`
+
+Codex��� hook 엔진은 hook 서브프로세스에 `CLAUDE_PLUGIN_ROOT`를 주입하므로 ([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs) 참고), 동일한 hook 스크립트가 중복 없이 두 호스트에서 모두 동작합니다. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 이벤트는 Claude Code 전용이며 Codex에는 등록되지 않습니다.
+
+#### Codex Desktop: 플러그인 hooks가 현재 동작하지 않음 (해결책 있음)
+
+`CodexHooks`와 `PluginHooks`는 [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs)에서 모두 안정 + 기본 활성화 상태이지만, 현재 Codex Desktop 빌드는 플러그인-로컬 `hooks.json`을 디스패치하지 않습니다 ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). MCP 도구는 여전히 동작합니다. 라이프사이클 관측만 누락됩니다.
+
+업스트림 수정이 적용될 때까지 동일한 hook 명령을 전역 `~/.codex/hooks.json`에 미러링하십시오:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+이 명령은 번들된 스크립트의 절대 경로를 참조하는 idempotent 블록을 `~/.codex/hooks.json`에 추가합니다(사용자 스코프에서 `${CLAUDE_PLUGIN_ROOT}` 확장이 필요 없음). agentmemory를 업그레이드한 후 동일한 명령을 다시 실행하여 경로를 갱신하십시오. 동일한 파일의 사용자 항목은 보존되며, 이전 agentmemory 항목만 교체됩니다.
+
+<details>
+<summary><b>OpenClaw (이 프롬프트를 붙여넣으세요)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+전체 가이드: [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (이 프롬프트를 붙여넣으세요)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+전체 가이드: [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### 다른 에이전트
+
+메모리 서버 시작: `npx @agentmemory/agentmemory`
+
+agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw)에서 **동일한 MCP 서버 블록**입니다:
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**호스트 설정 파일의 기존 `mcpServers` 객체에 이 항목을 병합하십시오** — 파일 전체를 교체하지 마십시오. 파일에 이미 다른 서버가 있다면, `agentmemory`를 `mcpServers` 안의 또 다른 키로 옆에 추가하십시오. `mcpServers` 자체가 없다면 `{ "mcpServers": { ... } }` 안에 블록을 붙여넣으십시오. `${VAR}` 자리표시자는 MCP 서버 실행 시 셸에서 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`을 상속합니다 — 설정되지 않은 변수는 빈 문자열로 전달되며 shim은 `http://localhost:3111`로 폴백합니다. 한 번 연결한 항목으로 로컬과 원격(k8s / 리버스 프록시) 배포를 모두 커버합니다.
+
+| 에이전트 | 설정 파일 | 비고 |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | `mcpServers`에 병합. 웹사이트에서 원클릭 deeplink도 사용 가능. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers`에 병합. 편집 후 Claude Desktop 재시작. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | 동일한 `mcpServers` ��록. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | 동일한 `mcpServers` 블록. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (자동 병합). |
+| **OpenClaw** | OpenClaw MCP config | 동일한 `mcpServers` 블록을 사용하거나, 더 깊은 [memory plugin](../integrations/openclaw/)을 사용. |
+| **Codex CLI (MCP only)** | `.codex/config.toml` | TOML 형식: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, 또는 `[mcp_servers.agentmemory]`를 수동으로 추가. |
+| **Codex CLI (full plugin)** | Codex 플러그인 마켓플레이스 | `codex plugin marketplace add rohitg00/agentmemory` 후 `codex plugin add agentmemory@agentmemory`. MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills 등록. Codex Desktop에서는 [openai/codex#16430](https://github.com/openai/codex/issues/16430)이 머지될 때까지 `agentmemory connect codex --with-hooks`도 실행해야 합니다 — 현재 그곳에서는 플러그인 hooks가 동작하지 않습니다. |
+| **OpenCode (MCP only)** | `opencode.json` | 다른 형식 — 최상위 `mcp` 키, 명령은 배열로: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (full plugin)** | `plugin/opencode/` | 세션 라이프사이클, 메시지, 도구, 오류를 다루는 22개의 자동 캡처 hooks. 두 개의 슬래시 명령(`/recall`, `/remember`). `plugin/opencode/`를 OpenCode workspace에 복사한 후 `opencode.json`에 플러그인 항목을 추가하십시오. 전체 hook 표 + gap 분석은 [`plugin/opencode/README.md`](../plugin/opencode/README.md) 참고. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | [`integrations/pi`](../integrations/pi/)를 복사하고 pi를 재시작. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `memory.provider: agentmemory`로 더 깊은 [memory provider plugin](../integrations/hermes/) 사용. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen`이 표준 `mcpServers` 블록을 기록. Hook 페이로드는 Claude Code와 필드 호환이므로, 기존 12-hook 스크립트가 수정 없이 동작합니다 — 동일한 `settings.json`의 `hooks` 섹션에서 연결. |
+| **Antigravity** (Gemini CLI 대체) | `mcp_config.json` (Antigravity의 User 디렉터리 내) | `agentmemory connect antigravity`가 표준 `mcpServers` 블록을 기록. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. 2026-06-18 Gemini CLI sunset 이후 사용. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro`가 사용자 레벨 설정을 기록. 워크스페이스 오버라이드는 코드 옆 `.kiro/settings/mcp.json`에. |
+| **Goose** | Goose MCP settings UI | 동일한 `mcpServers` 블록. |
+| **Aider** | n/a | REST API와 직접 통신: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **모든 에이전트 (32+)** | n/a | `npx skillkit install agentmemory`가 호스트를 자동 감지하고 병합. |
+
+**샌드박스된 MCP 클라이언트**(Flatpak / Snap / 제한적인 컨테이너 등)가 호스트의 `localhost`에 도달할 수 없는 경우: `env` 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`도 설정하고, `AGENTMEMORY_URL`을 샌드박스가 실제로 도달 가능한 경로(예: LAN IP)로 지정하십시오. 진단 가이드는 [#234](https://github.com/rohitg00/agentmemory/issues/234)를 참고하십시오.
+
+### 프로그래매틱 액세스 (Python / Rust / Node)
+
+agentmemory는 핵심 작업을 iii 함수(`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`)로 등록합니다. iii SDK가 있는 모든 언어에서 `ws://localhost:49134`로 직접 호출할 수 있습니다 — 언어별 별도의 REST 클라이언트가 필요하지 않습니다.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+작동 예제: [`examples/python/`](../examples/python/) (퀵스타트 + 관측/리콜 흐름). iii 런타임이 없는 호스트를 위해 `:3111`의 REST는 그대로 사용 가능합니다.
+
+### 소스에서 빌드
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+`iii`가 이미 설치되어 있으면 로컬 `iii-engine`으로 agentmemory를 시작하고, Docker가 사용 가능하면 Docker Compose로 폴백합니다. REST, 스트림, 뷰어는 기본적으로 `127.0.0.1`에 바인딩됩니다.
+
+`iii-engine`을 수동으로 설치하십시오. **agentmemory는 현재 `iii-engine`을 `v0.11.2`로 고정합니다** — `v0.11.6`은 모든 것을 `iii worker add`를 통해 샌드박스화하는 새 모델을 도입했는데 agentmemory는 아직 이를 위해 리팩터링되지 않았기 때문입니다. 리팩터링이 완료되면 고정이 풀립니다. 수동으로 sandbox 모델로 마이그레이션했다면 `AGENTMEMORY_III_VERSION=<version>`으로 덮어쓰십시오.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `aarch64-apple-darwin`을 `x86_64-apple-darwin`으로 교체
+- **Linux x64:** `x86_64-unknown-linux-gnu`로 교체
+- **Linux arm64:** `aarch64-unknown-linux-gnu`로 교체
+- **Windows:** [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2)에서 `iii-x86_64-pc-windows-msvc.zip`을 다운로드하고 `iii.exe`를 추출한 후 PATH에 추가
+
+또는 Docker 사용 (번들된 `docker-compose.yml`이 `iiidev/iii:0.11.2`를 pull). 전체 문서: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory는 Windows 10/11에서 실행되지만, Node.js 패키지만으로는 충분하지 않습니다 — 별도의 네이티브 바이너리인 `iii-engine` 런타임이 백그라운드 프로세스로 필요합니다. 공식 업스트림 인스톨러는 `sh` 스크립트이고 PowerShell 인스톨러나 scoop/winget 패키지는 현재 없으므로, Windows 사용자에게는 두 가지 경로가 있습니다:
+
+**옵션 A — 사전 빌드된 Windows 바이너리 (권장):**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe somewhere on PATH, or place it at:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory checks that location automatically)
+# 4. Verify:
+iii --version
+# Should print: 0.11.2
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**옵션 B — Docker Desktop:**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**옵션 C — 독립형 MCP만 사용 (엔진 없음):** 에이전트용 MCP 도구만 필요하고 REST API, 뷰어, cron 작업이 필요하지 않다면 엔진을 완전히 건너뛸 수 있습니다:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Windows 진단:** `npx @agentmemory/agentmemory`가 실패하면 `--verbose`로 다시 실행하여 실제 엔진 stderr를 확인하십시오. 일반적인 실패 모드:
+
+| 증상 | 해결 방법 |
+|---|---|
+| `iii-engine process started`가 표시된 후 `did not become ready within 15s` | 엔진이 시작 시 충돌함 — `--verbose`로 다시 실행하여 stderr 확인 |
+| `Could not start iii-engine` | `iii.exe`도 Docker도 설치되어 있지 않음. 위의 옵션 A 또는 B 참고 |
+| 포트 충돌 | `netstat -ano \| findstr :3111`로 무엇이 바인딩되어 있는지 확인하고 종료하거나 `--port <N>` 사용 |
+| Docker가 설치되어 있어도 Docker 폴백을 건너뜀 | Docker Desktop이 실제로 실행 중인지 확인 (시스템 트레이 아이콘) |
+
+> 참고: `cargo install iii-engine`는 없습니다 — `iii`는 crates.io에 게시되지 않았습니다. 지원되는 설치 방법은 위의 사전 빌드된 바이너리, 업스트림 `sh` 설치 스크립트(macOS/Linux 전용), Docker 이미지뿐입니다.
+
+---
+
+<h2 id="deploy">배포</h2>
+
+매니지드 호스트용 원클릭 템플릿입니다. 각각은 npm에서 `@agentmemory/agentmemory`를 가져오고 공식 `iiidev/iii` Docker Hub 이미지에서 iii 엔진 바이너리를 복사하는 자체 완결형 Dockerfile을 제공합니다 — 사전 빌드된 agentmemory 이미지가 필요 없습니다. 영구 스토리지는 `/data`에 마운트되며, 첫 부팅 진입점은 npm 번들 iii 설정(`127.0.0.1`에 바인딩)을 `0.0.0.0`에 바인딩하고 절대 `/data` 경로를 사용하는 배포 튜닝 설정으로 덮어쓰고, HMAC 시크릿을 생성한 후, `gosu`를 통해 `root`에서 `node`로 권한을 낮춘 다음 agentmemory CLI를 exec합니다.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render의 원클릭 배포 버튼은 저장소 루트에 `render.yaml`이 필요한데, 우리는 의도적으로 이를 깨끗하게 유지합니다. [`deploy/render/`](../deploy/render/README.md)에 문서화된 Render Blueprint 플로우를 사용하여 in-repo blueprint를 수동으로 가리키도록 하십시오.
+
+전체 설정 세부 사항(HMAC 캡처, 뷰어 SSH 터널, 로테이션, 백업, 비용 하한)은 [`deploy/`](../deploy/README.md)에 있습니다:
+
+- [`deploy/fly`](../deploy/fly/README.md) — `auto_stop_machines = "stop"`으로 단일 머신; 유휴 비용이 가장 저렴.
+- [`deploy/railway`](../deploy/railway/README.md) — Hobby 플랜 정액제, 볼륨은 대시보드에서.
+- [`deploy/render`](../deploy/render/README.md) — Blueprint 플로우, 유료 플랜에서 자동 디스크 스냅샷.
+- [`deploy/coolify`](../deploy/coolify/README.md) — [Coolify](https://coolify.io/self-hosted)를 통해 자체 VPS에 셀프 호스팅; 동일한 Docker Compose 스택, 호스트와 데이터를 직접 소유.
+
+`3111` 포트만 게시됩니다. `3113`의 뷰어는 컨테이너 내부에서 loopback에 바인딩된 채로 유지됩니다 — 각 템플릿의 README는 그곳에 도달하기 위한 SSH 터널 패턴을 문서화합니다.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="왜 agentmemory인가" height="32" /></picture></h2>
+
+모든 코딩 에이전트는 세션이 끝나면 모든 것을 잊습니다. 매 세션의 첫 5분을 스택을 다시 설명하는 데 낭비합니다. agentmemory는 백그라운드에서 실행되어 이를 완전히 제거합니다.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### 내장 에이전트 메모리와의 비교
+
+모든 AI 코딩 에이전트는 내장 메모리와 함께 제공됩니다 — Claude Code에는 `MEMORY.md`가 있고, Cursor에는 notepad가, Cline에는 memory bank가 있습니다. 이들은 포스트잇처럼 동작합니다. agentmemory는 포스트잇 뒤에 있는 검색 가능한 데이터베이스입니다.
+
+| | 내장 (CLAUDE.md) | agentmemory |
+|---|---|---|
+| 규모 | 200줄 한도 | 무제한 |
+| 검색 | 모든 것을 컨텍스트에 로드 | BM25 + vector + graph (top-K만) |
+| 토큰 비용 | 관측 240개 기준 22K+ | ~1,900 토큰 (92% 적음) |
+| 크로스 에이전트 | 에이전트별 파일 | MCP + REST (모든 에이전트) |
+| 조정 | 없음 | leases, signals, actions, routines |
+| 가시성 | 파일 수동 읽기 | :3113의 실시간 뷰어 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="동작 방식" height="32" /></picture></h2>
+
+### 메모리 파이프라인
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4-Tier 메모리 통합
+
+인간 뇌가 메모리를 처리하는 방식 — 수면 통합과 크게 다르지 않은 방식 — 에서 영감을 받았습니다.
+
+| Tier | 무엇 | 비유 |
+|------|------|---------|
+| **Working** | 도구 사용에서 나온 원시 관측 | 단기 기억 |
+| **Episodic** | 압축된 세션 요약 | "무슨 일이 있었는가" |
+| **Semantic** | 추출된 사실과 패턴 | "내가 아는 것" |
+| **Procedural** | 워크플로우와 의사 결정 패턴 | "그것을 하는 방법" |
+
+메모리는 시간이 지나면서 감쇠합니다(Ebbinghaus 곡선). 자주 액세스하는 메모리는 강화됩니다. 오래된 메모리는 자동으로 축출됩니다. 모순은 감지되고 해결됩니다.
+
+### 무엇이 캡처되는가
+
+| Hook | 캡처 내용 |
+|------|----------|
+| `SessionStart` | 프로젝트 경로, 세션 ID |
+| `UserPromptSubmit` | 사용자 프롬프트 (개인정보 필터링됨) |
+| `PreToolUse` | 파일 접근 패턴 + 풍부한 컨텍스트 |
+| `PostToolUse` | 도구 이름, 입력, 출력 |
+| `PostToolUseFailure` | 오류 컨텍스트 |
+| `PreCompact` | 컴팩션 전에 메모리 재주입 |
+| `SubagentStart/Stop` | 서브 에이전트 라이프사이클 |
+| `Stop` | 세션 종료 요약 |
+| `SessionEnd` | 세션 완료 마커 |
+
+### 핵심 기능
+
+| 기능 | 설명 |
+|---|---|
+| **자동 캡처** | 모든 도구 사용을 hooks로 기록 — 수동 작업 없음 |
+| **시맨틱 검색** | BM25 + vector + 지식 그래프, RRF 융합 |
+| **메모리 진화** | 버저닝, supersession, 관계 그래프 |
+| **자동 망각** | TTL 만료, 모순 감지, 중요도 기반 축출 |
+| **개인정보 우선** | API 키, 시크릿, `<private>` 태그를 저장 전에 제거 |
+| **자가 치유** | 서킷 브레이커, 프로바이더 폴백 체인, 헬스 모니터링 |
+| **Claude 브리지** | MEMORY.md와의 양방향 동기화 |
+| **지식 그래프** | 엔티티 추출 + BFS 순회 |
+| **팀 메모리** | 팀원 간 namespaced 공유 + 비공개 |
+| **인용 출처 추적** | 모든 메모리를 원본 관측으로 추적 |
+| **Git 스냅샷** | 메모리 상태의 버전 관리, 롤백, 차이 비교 |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="검색" height="32" /></picture></h2>
+
+세 가지 신호를 결합한 트리플 스트림 검색:
+
+| 스트림 | 무엇을 하는가 | 언제 |
+|---|---|---|
+| **BM25** | 형태소 추출 키워드 매칭 + 동의어 확장 | 항상 활성 |
+| **Vector** | 밀집 임베딩 위의 코사인 유사도 | 임베딩 프로바이더 구성 시 |
+| **Graph** | 엔티티 매칭을 통한 지식 그래프 순회 | 쿼리에서 엔티티 감지 시 |
+
+Reciprocal Rank Fusion(RRF, k=60)으로 융합하고, 세션 다양화(세션당 최대 3개 결과)합니다.
+
+BM25는 기본적으로 그리스어, 키릴 문자, 히브리어, 아랍어, 강세 부호가 있는 라틴 문자를 토크나이즈합니다. 중국어 / 일본어 / 한국어 메모리의 경우 선택적 세그멘터(`npm install @node-rs/jieba tiny-segmenter`)를 설치하여 CJK 런을 단어 수준 토큰으로 분할하십시오. 설치하지 않으면 agentmemory는 전체 런 토크나이제이션으로 soft fallback하고 stderr에 일회성 힌트를 출력합니다.
+
+### 임베딩 프로바이더
+
+agentmemory는 프로바이더를 자동 감지합니다. 최상의 결과를 위해 로컬 임베딩을 설치하십시오 (무료):
+
+```bash
+npm install @xenova/transformers
+```
+
+| 프로바이더 | 모델 | 비용 | 비고 |
+|---|---|---|---|
+| **Local (권장)** | `all-MiniLM-L6-v2` | 무료 | 오프라인, BM25-only 대비 +8pp recall |
+| Gemini | `gemini-embedding-001` | 무료 티어 | 100+ 언어, 768/1536/3072 dims (MRL), 2048-token 입력. `text-embedding-004`를 대체 ([deprecated, 2026년 1월 14일 종료](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | 최고 품질 |
+| Voyage AI | `voyage-code-3` | 유료 | 코드 최적화 |
+| Cohere | `embed-english-v3.0` | 무료 평가판 | 범용 |
+| OpenRouter | 모든 모델 | 다양 | 멀티 모델 프록시 |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP 서버" height="32" /></picture></h2>
+
+53개 도구, 6개 리소스, 3개 프롬프트, 4개 skills — 모든 에이전트를 위한 가장 포괄적인 MCP 메모리 툴킷.
+
+> **MCP shim 대 전체 서버:** 게시된 `@agentmemory/mcp` 패키지는 얇은 shim입니다. `AGENTMEMORY_URL`을 통해 실행 중인 agentmemory 서버에 도달할 수 있을 때 **만** 전체 51-도구 표면을 노출합니다(프록시 모드). 도달 가능한 서버가 없으면 shim은 7-도구 로컬 세트(`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`)로 폴백합니다. `AGENTMEMORY_TOOLS=core|all` 환경 변수는 *서버 측* 플래그입니다 — shim의 `env` 블록에 설정해도 효과가 없습니다. Cursor / OpenCode / Gemini CLI에서 도구가 7개만 보인다면 `npx @agentmemory/agentmemory`(또는 Docker 스택)를 시작하고 `AGENTMEMORY_URL=http://localhost:3111`을 설정하십시오.
+
+### 51개 도구
+
+<details>
+<summary>핵심 도구 (항상 사용 가능)</summary>
+
+| 도구 | 설명 |
+|------|-------------|
+| `memory_recall` | 과거 관측 검색 |
+| `memory_compress_file` | 구조를 유지하면서 markdown 파일 압축 |
+| `memory_save` | 통찰, 결정, 패턴 저장 |
+| `memory_patterns` | 반복 패턴 감지 |
+| `memory_smart_search` | 하이브리드 시맨틱 + 키워드 검색 |
+| `memory_file_history` | 특정 파일에 대한 과거 관측 |
+| `memory_sessions` | 최근 세션 목록 |
+| `memory_timeline` | 시간순 관측 |
+| `memory_profile` | 프로젝트 프로필 (개념, 파일, 패턴) |
+| `memory_export` | 모든 메모리 데이터 내보내기 |
+| `memory_relations` | 관계 그래프 쿼리 |
+
+</details>
+
+<details>
+<summary>확장 도구 (총 51개 — AGENTMEMORY_TOOLS=all 설정)</summary>
+
+| 도구 | 설명 |
+|------|-------------|
+| `memory_patterns` | 반복 패턴 감지 |
+| `memory_timeline` | 시간순 관측 |
+| `memory_relations` | 관계 그래프 쿼리 |
+| `memory_graph_query` | 지식 그래프 순회 |
+| `memory_consolidate` | 4-tier 통합 실행 |
+| `memory_claude_bridge_sync` | MEMORY.md와 동기화 |
+| `memory_team_share` | 팀원과 공유 |
+| `memory_team_feed` | 최근 공유 항목 |
+| `memory_audit` | 작업 감사 로그 |
+| `memory_governance_delete` | 감사 로그를 남기는 삭제 |
+| `memory_snapshot_create` | Git 버전 관리 스냅샷 |
+| `memory_action_create` | 의존성이 있는 작업 항목 생성 |
+| `memory_action_update` | 작업 상태 업데이트 |
+| `memory_frontier` | 우선순위로 정렬된 차단 해제된 작업 |
+| `memory_next` | 가장 중요한 다음 작업 하나 |
+| `memory_lease` | 독점 작업 leases (멀티 에이전트) |
+| `memory_routine_run` | 워크플로우 루틴 인스턴스화 |
+| `memory_signal_send` | 에이전트 간 메시징 |
+| `memory_signal_read` | 수신 확인이 있는 메시지 읽기 |
+| `memory_checkpoint` | 외부 조건 게이트 |
+| `memory_mesh_sync` | 인스턴스 간 P2P 동기화 |
+| `memory_sentinel_create` | 이벤트 기반 워처 |
+| `memory_sentinel_trigger` | 외부에서 sentinel 발화 |
+| `memory_sketch_create` | 일시적 작업 그래프 |
+| `memory_sketch_promote` | 영구로 승격 |
+| `memory_crystallize` | 작업 체인 압축 |
+| `memory_diagnose` | 헬스 체크 |
+| `memory_heal` | 정체된 상태 자동 수정 |
+| `memory_facet_tag` | dimension:value 태그 |
+| `memory_facet_query` | facet 태그로 쿼리 |
+| `memory_verify` | 출처 추적 |
+
+</details>
+
+### 6 리소스 · 3 프롬프트 · 4 Skills
+
+| 유형 | 이름 | 설명 |
+|------|------|-------------|
+| Resource | `agentmemory://status` | 헬스, 세션 수, 메모리 수 |
+| Resource | `agentmemory://project/{name}/profile` | 프로젝트별 인텔리전스 |
+| Resource | `agentmemory://memories/latest` | 최신 10개 활성 메모리 |
+| Resource | `agentmemory://graph/stats` | 지식 그래프 통계 |
+| Prompt | `recall_context` | 검색 + 컨텍스트 메시지 반환 |
+| Prompt | `session_handoff` | 에이전트 간 핸드오프 데이터 |
+| Prompt | `detect_patterns` | 반복 패턴 분석 |
+| Skill | `/recall` | 메모리 검색 |
+| Skill | `/remember` | 장기 메모리에 저장 |
+| Skill | `/session-history` | 최근 세션 요약 |
+| Skill | `/forget` | 관측/세션 삭제 |
+
+### 독립형 MCP
+
+전체 서버 없이 실행 — 모든 MCP 클라이언트용. 다음 둘 다 동작합니다:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (always available)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+또는 에이전트의 MCP 설정에 추가:
+
+대부분의 에이전트 (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+파일을 교체하지 말고 호스트의 기존 `mcpServers` 객체에 `agentmemory` 항목을 병합하십시오. 호스트의 `localhost`에 도달할 수 없는 샌드박스 클라이언트의 경우 env 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`을 추가하고 `AGENTMEMORY_URL`을 샌드박스가 도달할 수 있는 경로로 설정하십시오.
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+저장소에서 플러그인 파일을 복사하십시오:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="실시간 뷰어" height="32" /></picture></h2>
+
+`3113` 포트에서 자동 시작됩니다. 라이브 관측 스트림, 세션 탐색기, 메모리 브라우저, 지식 그래프 시각화, 헬스 대시보드.
+
+```bash
+open http://localhost:3113
+```
+
+뷰어 서버는 기본적으로 `127.0.0.1`에 바인딩됩니다. REST가 서빙하는 `/agentmemory/viewer` 엔드포인트는 일반 `AGENTMEMORY_SECRET` bearer-token 규칙을 따릅니다. CSP 헤더는 응답별 script nonce를 사용하며 인라인 핸들러 속성을 비활성화합니다 (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+`:3113`의 뷰어는 에이전트가 **기억한 것**을 보여줍니다. [iii console](https://iii.dev/docs/console)은 에이전트가 **무엇을 했는지**를 보여줍니다 — 모든 메모리 작업을 OpenTelemetry 추적으로, 모든 KV 항목을 편집 가능하게, 모든 함수를 호출 가능하게, 모든 스트림을 탭 가능하게. 동일한 메모리에 대한 두 창: 하나는 제품 형태, 하나는 엔진 형태.
+
+`memory_smart_search`가 발화되는 것을 보고 BM25 스캔 → 임베딩 조회 → RRF 융합 → 리랭커를 워터폴로 확인하십시오. KV 브라우저에서 정체된 통합 타이머를 편집하십시오. 조정된 페이로드로 `PostToolUse` hook을 재생하십시오. WebSocket 스트림을 고정하고 관측이 실시간으로 도착하는 것을 지켜보십시오.
+
+agentmemory는 모든 함수, 트리거, 상태 스코프, 스트림이 iii 프리미티브이기 때문에 — 사용자 정의도, 계측할 것도 없기 때문에 — 이를 무료로 제공합니다.
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers 페이지 — 연결된 워커들, 라이브 함수 수와 런타임 메타데이터가 표시된 agentmemory 인스턴스 포함" width="720" />
+  <br/>
+  <em>Workers 페이지: 연결된 모든 워커 — agentmemory 자체 포함 — PID, 함수 수, 런타임, last-seen 표시.</em>
+</p>
+
+**이미 설치됨.** 콘솔은 `iii`와 함께 제공됩니다 — 별도의 인스톨러가 없습니다.
+
+**agentmemory와 함께 실행:**
+
+```bash
+# agentmemory viewer holds port 3113, so run the console on 3114.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
+```
+
+그런 다음 `http://localhost:3114`을 여십시오. 실험적인 architecture-graph 페이지를 위해 `--enable-flow`를 추가하십시오.
+
+엔진 엔드포인트를 옮긴 경우에만 덮어쓰십시오:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**콘솔에서 할 수 있는 일:**
+
+| 페이지 | 용도 |
+|------|-----------|
+| **Workers** | 연결된 모든 워커와 그 라이브 메트릭 확인 — agentmemory 워커 자체 포함. |
+| **Functions** | JSON 페이로드로 agentmemory의 모든 함수를 직접 호출 — 클라이언트를 연결하지 않고 `memory.recall`, `memory.consolidate`, `graph.query`를 테스트하기에 편리. |
+| **Triggers** | HTTP, cron, event, state 트리거를 재생 — 통합 cron을 수동으로 발화, HTTP 라우트를 재시도, state 변경을 발생. |
+| **States** | 전체 CRUD가 가능한 KV 브라우저 — 세션, 메모리 슬롯, 라이프사이클 타이머, 임베딩 인덱스 — 값을 그 자리에서 편집. |
+| **Streams** | iii 스트림을 통해 흐르는 메모리 쓰기, hook 이벤트, 관측 업데이트를 위한 라이브 WebSocket 모니터. |
+| **Queues** | 내구성 있는 큐 토픽 + 데드 레터 관리. 실패한 임베딩 / 압축 작업을 재생하거나 폐기. |
+| **Traces** | OpenTelemetry 워터폴 / 플레임 / 서비스별 분해 뷰. `trace_id`로 필터링하여 단일 `memory.search`가 생성한 함수, DB 호출, 임베딩 요청을 정확히 확인. |
+| **Logs** | trace/span ID에 필터링·상관된 구조화된 OTEL 로그. |
+| **Config** | 런타임 설정 — 엔진이 실행 중인 워커, 프로바이더, 포트를 정확히 확인. |
+| **Flow** | (선택, `--enable-flow`) 모든 워커, 트리거, 스트림의 인터랙티브 architecture graph. |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="span별 지속 시간을 보여주는 iii console trace waterfall view" width="720" />
+  <br/>
+  <em>Traces: 모든 메모리 작업에 대한 워터폴 / 플레임 / 서비스 분해.</em>
+</p>
+
+**Traces는 이미 켜져 있습니다:**
+
+`iii-config.yaml`은 `iii-observability` 워커가 활성화된 상태로 제공됩니다(`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs). 추가 설정이 필요 없습니다 — agentmemory가 시작되는 순간 모든 메모리 작업이 콘솔이 읽을 수 있는 trace span과 구조화된 로그를 방출합니다.
+
+대신 Jaeger/Honeycomb/Grafana Tempo로 내보내고 싶다면 `exporter: memory`를 `exporter: otlp`로 변경하고 iii의 가시성 문서에 따라 collector 엔드포인트를 설정하십시오.
+
+> **참고:** 콘솔 자체에는 인증이 적용되지 않습니다 — `127.0.0.1`에 바인딩된 채로 두고(기본값) 절대 공개적으로 노출하지 마십시오.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory는 **��미 실행 중인 [iii](https://iii.dev) 인스턴스**입니다. 함수, 트리거, KV 상태, 스트림, OTEL 추적 — 모두 iii 프리미티브입니다. Postgres, Redis, Express, pm2, Prometheus를 설치하지 않은 이유는 iii가 이들을 대체하기 때문입니다.
+
+그 말은 명령어 하나로 agentmemory에 완전히 새로운 기능을 확장할 수 있다는 뜻입니다.
+
+### 명령어 하나로 agentmemory 확장
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+각 `iii worker add`는 agentmemory가 이미 실행 중인 동일한 엔진에 새 함수와 트리거를 등록합니다. 뷰어와 콘솔은 즉시 이를 인식합니다 — 재로드도, 새 통합도, 새 컨테이너도 필요 없습니다.
+
+| `iii worker add` | agentmemory 위에 무엇이 추가되는가 |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | 멀티 인스턴스 메모리: 모든 `remember`가 팬아웃, 모든 `search`가 합집합을 읽음 |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | 스케줄링된 라이프사이클 — 야간 통합, 주간 스냅샷, 고정된 시계에 따른 감쇠 |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | 내구성 있는 재시도: 실패한 임베딩 + 압축 작업은 재시작에도 살아남아 관측 손실 없음 |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | 모든 함수에 OTEL traces, metrics, logs — 첫날부터 `iii-config.yaml`에 연결됨 |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`에서 나온 코드를 셸이 아니라 일회용 VM 안에서 실행 |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | 인메모리 KV 기본값을 넘어설 때 SQL 기반 state adapter |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory의 MCP 옆에 추가 MCP 서버를 세우고 동일한 엔진을 공유 |
+
+전체 레지스트리: [workers.iii.dev](https://workers.iii.dev). 그곳의 모든 워커는 agentmemory가 사용하는 동일한 프리미티브로 구성됩니다 — 그리고 이미 갖고 있는 agentmemory도 그중 하나입니다.
+
+### iii가 무엇을 대체하는가
+
+| 전통적인 스택 | agentmemory에서의 사용 |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + 인메모리 벡터 인덱스 |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker supervision |
+| Prometheus / Grafana | iii OTEL + 헬스 모니터 |
+| 사용자 정의 플러그인 시스템 | `iii worker add <name>` |
+
+**118개 소스 파일 · ~21,800 LOC · 950+ tests · 123개 함수 · 34개 KV 스코프** — 모두 세 가지 프리미티브 위에. `agentmemory plugin install`이 없습니다. 플러그인 시스템은 iii 자체입니다.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="설정" height="32" /></picture></h2>
+
+### LLM 프로바이더
+
+agentmemory는 환경에서 자동 감지합니다. 기본적으로 프로바이더를 구성하거나 Claude subscription 폴백에 명시적으로 옵트인하지 않는 한 LLM 호출이 발생하지 않습니다.
+
+| 프로바이더 | 설정 | 비고 |
+|----------|--------|-------|
+| **No-op (기본)** | 설정 불필요 | LLM 기반 압축/요약이 비활성화됨. 합성 BM25 압축 + 리콜은 여전히 동작. 이전에 Claude-subscription 폴백에 의존했다면 아래의 `AGENTMEMORY_ALLOW_AGENT_SDK` 참고. |
+| Anthropic API | `ANTHROPIC_API_KEY` | 토큰당 청구 |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic 호환 |
+| Gemini | `GEMINI_API_KEY` | 임베딩도 활성화 |
+| OpenRouter | `OPENROUTER_API_KEY` | 모든 모델 |
+| Claude subscription 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 옵트인 전용. `@anthropic-ai/claude-agent-sdk` 세션을 스폰 — 무한 Stop-hook 재귀를 일으킨 전력이 있어서(#149 후속) 더 이상 기본값이 아닙니다. |
+
+### 비용 인식 모델 선택
+
+백그라운드 압축은 모든 관측마다 실행되므로 모델 선택이 월별 지출에 의미 있게 영향을 미칩니다. 캡처된 워크로드 데이터: 635 요청 / 888K 토큰 / 35시간의 활성 사용, 2026-05-23 가격으로 세 가지 OpenRouter 모델에 대해 실행.
+
+| 티어 | 모델 | Input / 1M | Output / 1M | 캡처된 35h 비용 | 비고 |
+|------|-------|------------|-------------|---------------------------|-------|
+| 권장 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | 견고한 압축 + 요약 품질, Sonnet 대비 ~10배 저렴. |
+| 권장 | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | 더 오래되었지만 압축 전용 워크로드에 여전히 적합. |
+| 권장 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 세션이 코드 중심이라면 강한 코드 추론. |
+| 프리미엄 | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | 고품질이지만 항시 백그라운드 작업에는 비쌈. |
+| 프리미엄 | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Sonnet과 유사한 티어. |
+| 회피 | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | 추론 클래스 모델; 압축에는 막대한 과지출. |
+
+`OPENROUTER_MODEL`이 프리미엄 티어 패턴과 일치하면 agentmemory가 런타임 경고를 출력합니다. 정보에 기반한 결정을 내렸다면 `AGENTMEMORY_SUPPRESS_COST_WARNING=1`로 한 번에 침묵시키십시오.
+
+메모리 작업에서의 품질 대 비용 트레이드오프: 압축은 비교적 느슨한 품질 기준을 가진 요약 작업입니다(사용자가 아니라 에이전트가 요약을 다시 읽습니다). DeepSeek-V4-Pro / Qwen3-Coder는 이 작업에서 Sonnet과 반올림 오차 내에 들어가면서 ~10배 적은 비용이 듭니다. 프리미엄 티어 모델은 직접 읽는 쿼리에 남겨두십시오.
+
+출처: [OpenRouter pricing for Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### 멀티 에이전트 메모리 (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+여러 역할(architect / developer / reviewer / researcher / support-agent)이 하나의 agentmemory 서버를 공유하는 멀티 에이전트 설정에서, `AGENT_ID`는 모든 쓰기에 그것을 작성한 역할을 태깅합니다. `AGENTMEMORY_AGENT_SCOPE`는 리콜이 그 태그로 필터링되는지 여부를 제어합니다.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+두 가지 모드:
+
+| 모드 | 쓰기 태그 | 리콜 필터링 | 사용 시점 |
+|------|------------|---------------|-------------|
+| `shared` (기본) | 예 | 아니오 | 감사 로그가 있는 크로스 에이전트 컨텍스트. architect는 developer가 기록한 내용을 볼 수 있지만, 모든 행은 누가 말했는지 기록합니다. |
+| `isolated` | 예 | 예 | 엄격한 분리. architect는 developer의 관측 / 메모리 / 세션을 절대 보지 않습니다. |
+
+`AGENT_ID`가 설정되었을 때 태깅되는 것: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. 역할은 `api::session::start` → `mem::observe` → `mem::compress` → KV로 흐릅니다.
+
+isolated 모드에서 필터링되는 것: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. 각 엔드포인트는 요청별로 덮어쓰기 위해 `?agentId=<role>`을 받고, env 스코프를 완전히 옵트아웃하기 위해 `?agentId=*`을 받습니다. `/memories`는 또한 `agentId`가 undefined인 pre-AGENT_ID 메모리를 노출하기 위해 `?includeOrphans=true`를 받습니다.
+
+SDK / REST 레이어에서의 호출별 덮어쓰기: 모든 변형 엔드포인트(`/session/start`, `/remember`)는 env를 이기는 `agentId` 필드를 request body에서 받습니다. 많은 역할을 하나의 서버 프로세스로 라우팅하는 런타임에 유용합니다.
+
+`AGENT_ID`가 설정되지 않았을 때, 메모리는 스코프되지 않은 상태로 유지됩니다(레거시 동작, 태그 없음, 필터 없음).
+
+### 포트
+
+agentmemory + iii-engine은 기본적으로 네 개의 포트에 바인딩합니다. 재시작이 `port in use`로 실패한다면, 이 표가 어떤 프로세스를 찾을지 알려줍니다.
+
+| 포트 | 프로세스 | 용도 | Env 덮어쓰기 |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | 내부 streams 워커 (agentmemory + 뷰어가 소비) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | 실시간 뷰어 (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — 워커가 여기에 등록, OTel 텔레메트리가 이 위로 흐름 | `III_ENGINE_URL` (전체 URL, 기본 `ws://localhost:49134`) |
+
+크래시된 실행 후 포트가 바인딩된 채로 남아 있을 때의 정리:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop`은 정상 종료 시 워커�� 엔진 pidfile을 모두 깔끔하게 회수합니다 (#640, #474). 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
+
+### 설정 파일
+
+매 셸에서 변수를 export하는 대신 agentmemory 런타임 설정을 `~/.agentmemory/.env`에 두십시오. 뷰어가 `export ANTHROPIC_API_KEY=...` 같은 setup 힌트를 보여주면, `export` 접두사 없이 `ANTHROPIC_API_KEY=...`로 이 파일에 복사한 후 agentmemory를 재시작하십시오.
+
+프로세스 환경 변수는 여전히 동작하며 파일의 값보다 우선순위가 높습니다.
+
+Windows에서 동일한 파일은 `%USERPROFILE%\.agentmemory\.env`에 있습니다:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+API 키 대신 Claude Code Pro/Max subscription으로 테스트하려면 명시적으로 옵트인하십시오:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+원한다면 동일한 파일에서 graph 또는 consolidation 기능을 활성화하십시오:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### 환경 변수
+
+`~/.agentmemory/.env` 생성:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+`3111` 포트의 124개 엔드포인트. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `AGENTMEMORY_SECRET`이 설정되었을 때 `Authorization: Bearer <secret>`를 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에서 `AGENTMEMORY_SECRET`을 요구합니다.
+
+<details>
+<summary>주요 엔드포인트</summary>
+
+| Method | Path | 설명 |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | 헬스 체크 (항상 공개) |
+| `POST` | `/agentmemory/session/start` | 세션 시작 + 컨텍스트 가져오기 |
+| `POST` | `/agentmemory/session/end` | 세션 종료 |
+| `POST` | `/agentmemory/observe` | 관측 캡처 |
+| `POST` | `/agentmemory/smart-search` | 하이브리드 검색 |
+| `POST` | `/agentmemory/context` | 컨텍스트 생성 |
+| `POST` | `/agentmemory/remember` | 장기 메모리에 저장 |
+| `POST` | `/agentmemory/forget` | 관측 삭제 |
+| `POST` | `/agentmemory/enrich` | 파일 컨텍스트 + 메모리 + 버그 |
+| `GET` | `/agentmemory/profile` | 프로젝트 프로필 |
+| `GET` | `/agentmemory/export` | 모든 데이터 내보내기 |
+| `POST` | `/agentmemory/import` | JSON에서 가져오기 |
+| `POST` | `/agentmemory/graph/query` | 지식 그래프 쿼리 |
+| `POST` | `/agentmemory/team/share` | 팀과 공유 |
+| `GET` | `/agentmemory/audit` | 감사 로그 |
+
+전체 엔드포인트 목록: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="개발" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ tests
+npm run test:integration  # API tests (requires running services)
+```
+
+**전제 조건:** Node.js >= 20, [iii-engine](https://iii.dev/docs) 또는 Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="라이선스" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.pt-BR.md

@@ -0,0 +1,1370 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — Memória persistente para agentes de codificação com IA" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    Seu agente de codificação lembra de tudo. Chega de re-explicar.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Memória persistente para Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualquer cliente MCP.
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  Português |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Documento de design: 1200 stars / 172 forks no gist" /></a>
+</p>
+
+<p align="center">
+  <em>O gist estende o padrão LLM Wiki do Karpathy com pontuação de confiança, ciclo de vida, grafos de conhecimento e busca híbrida: agentmemory é a implementação.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="Demonstração do agentmemory" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">Instalação</a> &bull;
+  <a href="#quick-start">Início rápido</a> &bull;
+  <a href="#benchmarks">Benchmarks</a> &bull;
+  <a href="#vs-competitors">Comparativo</a> &bull;
+  <a href="#works-with-every-agent">Agentes</a> &bull;
+  <a href="#how-it-works">Como funciona</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">Viewer</a> &bull;
+  <a href="#iii-console">iii Console</a> &bull;
+  <a href="#powered-by-iii">Powered by iii</a> &bull;
+  <a href="#configuration">Configuração</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install -g @agentmemory/agentmemory          # once — bare `agentmemory` on PATH
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # start the memory server on :3111
+agentmemory demo                                 # seed sample sessions + prove recall
+agentmemory connect claude-code                  # wire your agent (also: codex, cursor, gemini-cli, ...)
+```
+
+Ou via `npx` (sem instalação):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+Atenção — o npx faz cache por versão. Se um simples `npx @agentmemory/agentmemory` servir uma release antiga, force a mais recente com `npx -y @agentmemory/agentmemory@latest`, ou limpe o cache uma vez com `rm -rf ~/.npm/_npx` (macOS/Linux; no Windows apague `%LOCALAPPDATA%\npm-cache\_npx`). A primeira execução via npx a partir da v0.9.16+ pergunta inline se você quer instalar globalmente, de modo que o comando `agentmemory` simples funcione em qualquer lugar depois.
+
+Opções completas em [Início rápido](#quick-start) abaixo. Conexão específica por agente em [Funciona com qualquer agente](#works-with-every-agent).
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funciona com qualquer agente" height="32" /></picture></h2>
+
+agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Todos os agentes compartilham o mesmo servidor de memória.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>native plugin + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>native plugin + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>native Memory trait backend</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + plugin</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP server</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP server</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>Funciona com <strong>qualquer</strong> agente que fale MCP ou HTTP. Um servidor, memórias compartilhadas entre todos eles.</sub>
+</p>
+
+---
+
+Você explica a mesma arquitetura toda sessão. Você redescobre os mesmos bugs. Você reensina as mesmas preferências. A memória integrada (CLAUDE.md, .cursorrules) bate no teto das 200 linhas e fica desatualizada. agentmemory resolve isso. Ele captura silenciosamente o que seu agente faz, comprime em memória pesquisável e injeta o contexto certo quando a próxima sessão começa. Um comando. Funciona em todos os agentes.
+
+**O que muda:** Na sessão 1 você configura autenticação JWT. Na sessão 2 você pede rate limiting. O agente já sabe que sua autenticação usa o middleware jose em `src/middleware/auth.ts`, que seus testes cobrem a validação de tokens e que você escolheu jose em vez de jsonwebtoken por compatibilidade com Edge. Sem re-explicar. Sem copiar e colar. O agente simplesmente *sabe*.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **Novidade na v0.9.0** — Landing em [agent-memory.dev](https://agent-memory.dev), conector de filesystem (`@agentmemory/fs-watcher`), MCP standalone agora faz proxy para o servidor em execução, então hooks e viewer combinam, política de auditoria codificada em cada caminho de deleção, e health para de marcar `memory_critical` em processos Node pequenos. Notas completas em [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18).
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Precisão de recuperação
+
+**coding-agent-life-v1** (corpus interno, reproduzível em sandbox)
+
+| Adaptador | P@5 | R@5 | Taxa de acerto top-5 | Latência p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep baseline | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+Taxa de acerto top-5 de 100%. **2,2×** mais precisão que a baseline grep com a mesma entrada. Detalhamento completo por tipo: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 perguntas)
+
+| Sistema | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Economia de tokens
+
+| Abordagem | Tokens/ano | Custo/ano |
+|---|---|---|
+| Colar contexto completo | 19.5M+ | Impossível (excede a janela) |
+| Resumido por LLM | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + embeddings locais | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> Modelo de embedding: `all-MiniLM-L6-v2` (local, gratuito, sem API key). Relatórios completos: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparativo com concorrentes: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory vs mem0, Letta, Khoj, claude-mem, Hippo.
+
+**Reproduza localmente:** [`eval/README.md`](../eval/README.md) — harness com adaptadores plugáveis para LongMemEval `_s` (500-Q públicas) e `coding-agent-life-v1` (corpus interno de 15 sessões). Adaptadores grep / vector / agentmemory são pontuados lado a lado, saída em NDJSON, e as scorecards publicadas ficam em [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Combina com [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) e [Graphify](https://github.com/safishamsi/graphify).** Indexação de grafos de código, pipelines de build multiagente e grafos de conhecimento mais amplos sobre docs / PDFs / imagens / vídeos. agentmemory lembra do trabalho; esses três projetos iluminam o resto da camada de contexto. Recipes e tabela de roteamento por pergunta: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="Comparativo" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">Built-in (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>Tipo</strong></td>
+<td>Engine de memória + servidor MCP</td>
+<td>API de camada de memória</td>
+<td>Runtime de agente completo</td>
+<td>Arquivo estático</td>
+</tr>
+<tr>
+<td><strong>Retrieval R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>Captura automática</strong></td>
+<td>12 hooks (esforço manual zero)</td>
+<td>Chamadas manuais a <code>add()</code></td>
+<td>O agente se autoedita</td>
+<td>Edição manual</td>
+</tr>
+<tr>
+<td><strong>Busca</strong></td>
+<td>BM25 + Vector + Graph (fusão RRF)</td>
+<td>Vector + Graph</td>
+<td>Vector (archival)</td>
+<td>Carrega tudo no contexto</td>
+</tr>
+<tr>
+<td><strong>Multiagente</strong></td>
+<td>MCP + REST + leases + signals</td>
+<td>API (sem coordenação)</td>
+<td>Somente dentro do runtime do Letta</td>
+<td>Arquivos por agente</td>
+</tr>
+<tr>
+<td><strong>Dependência de framework</strong></td>
+<td>Nenhuma (qualquer cliente MCP)</td>
+<td>Nenhuma</td>
+<td>Alta (precisa usar Letta)</td>
+<td>Formato por agente</td>
+</tr>
+<tr>
+<td><strong>Dependências externas</strong></td>
+<td>Nenhuma (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + BD vetorial</td>
+<td>Nenhuma</td>
+</tr>
+<tr>
+<td><strong>Ciclo de vida da memória</strong></td>
+<td>Consolidação de 4 níveis + decaimento + auto-esquecimento</td>
+<td>Extração passiva</td>
+<td>Gerenciado pelo agente</td>
+<td>Poda manual</td>
+</tr>
+<tr>
+<td><strong>Eficiência de tokens</strong></td>
+<td>~1.900 tokens/sessão ($10/ano)</td>
+<td>Varia conforme a integração</td>
+<td>Memória principal no contexto</td>
+<td>22K+ tokens com 240 obs</td>
+</tr>
+<tr>
+<td><strong>Viewer em tempo real</strong></td>
+<td>Sim (port 3113)</td>
+<td>Dashboard na nuvem</td>
+<td>Dashboard na nuvem</td>
+<td>Não</td>
+</tr>
+<tr>
+<td><strong>Self-hosted</strong></td>
+<td>Sim (padrão)</td>
+<td>Opcional</td>
+<td>Opcional</td>
+<td>Sim</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Início rápido" height="32" /></picture></h2>
+
+Compatibilidade: este release tem como alvo o `iii-sdk` estável `^0.11.0` e o iii-engine v0.11.x.
+
+### Experimente em 30 segundos
+
+```bash
+# Terminal 1: start the server
+npx @agentmemory/agentmemory
+
+# Terminal 2: seed sample data and see recall in action
+npx @agentmemory/agentmemory demo
+```
+
+`demo` semeia 3 sessões realistas (autenticação JWT, correção de N+1 queries, rate limiting) e roda buscas semânticas sobre elas. Você verá que ele encontra "N+1 query fix" ao buscar "database performance optimization" — algo que matching por palavra-chave não consegue fazer.
+
+Abra `http://localhost:3113` para acompanhar a memória sendo construída ao vivo.
+
+### Recomendado: instale globalmente
+
+`npx` faz cache por versão. Se você rodou `npx @agentmemory/agentmemory@0.9.14` semana passada, um simples `npx @agentmemory/agentmemory` pode servir a versão velha 0.9.14 a partir de `~/.npm/_npx/`, e não a mais recente. Instale uma vez e o comando `agentmemory` funciona em qualquer lugar:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# If you hit EACCES on macOS/Linux system Node installs, retry with:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # start the server (same as the npx form)
+agentmemory stop               # tear it down
+agentmemory remove             # uninstall everything we created
+agentmemory connect claude-code   # wire one agent
+agentmemory doctor             # interactive diagnostics + fix prompts
+```
+
+A partir da v0.9.16, a primeira execução via npx pergunta inline se você quer instalar globalmente — responda `Y` uma vez e está pronto. Se pular, recorra a qualquer um destes para um fetch limpo:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # forces latest from npm (cross-platform)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # macOS/Linux only (POSIX shell)
+```
+
+No Windows / PowerShell, o equivalente para limpar cache é `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — a forma `npx -y ...@latest` acima é a opção multiplataforma.
+
+### Session Replay
+
+Toda sessão que o agentmemory grava é reproduzível. Abra o viewer, escolha a aba **Replay** e arraste pela timeline: prompts, chamadas a tools, resultados e respostas renderizam como eventos discretos com play/pause, controle de velocidade (0,5×–4×) e atalhos de teclado (espaço para alternar, setas para avançar passo a passo).
+
+Já tem transcripts antigos JSONL do Claude Code que quer trazer para cá?
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx @agentmemory/agentmemory import-jsonl
+
+# Or import a single file
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+As sessões importadas aparecem no seletor de Replay ao lado das nativas. Sob o capô, cada entrada passa pelas funções iii `mem::replay::load`, `mem::replay::sessions` e `mem::replay::import-jsonl` — sem servidores paralelos.
+
+### Atualização / Manutenção
+
+Use o comando de manutenção quando você intencionalmente quiser atualizar seu runtime local:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+Aviso: este comando muta o workspace/runtime atual. Pode atualizar dependências JavaScript, pode rodar `cargo install iii-engine --force` e pode puxar imagens Docker.
+
+Detalhes de implementação estão em `src/cli.ts` (veja `runUpgrade` na região `src/cli.ts:544-595`).
+
+### Claude Code (um bloco, cole)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Claude Code sem instalar o plugin (caminho MCP standalone)
+
+Se você cabear o servidor MCP do agentmemory via `~/.claude.json` diretamente em vez de usar `/plugin install`, o Claude Code nunca resolve `${CLAUDE_PLUGIN_ROOT}` e você tem que apontar os scripts de hook para caminhos absolutos em `~/.claude/settings.json`. Esses caminhos tipicamente embutem a versão do agentmemory (ex: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), então a próxima atualização quebra silenciosamente todos os hooks ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+Contorno:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Isso mescla os mesmos comandos de hook em `~/.claude/settings.json` com caminhos absolutos resolvidos para o diretório `plugin/` empacotado do pacote `@agentmemory/agentmemory` atualmente instalado. Rode o comando novamente após atualizar o agentmemory para atualizar os caminhos. Entradas de usuário no mesmo arquivo são preservadas; apenas entradas anteriores do agentmemory são substituídas. Usar o caminho `/plugin install` continua sendo a abordagem recomendada.
+Para deploys remotos ou protegidos, inicie o Claude Code com `AGENTMEMORY_URL` e `AGENTMEMORY_SECRET` definidos. O plugin repassa ambos os valores para seu servidor MCP empacotado; quando `AGENTMEMORY_URL` está vazio, o shim MCP usa `http://localhost:3111`.
+
+### Codex CLI (plataforma de plugins do Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+O plugin do Codex é servido a partir do mesmo diretório `plugin/` do plugin do Claude Code. Ele registra:
+
+- `@agentmemory/mcp` como servidor MCP (faz proxy de todas as 51 tools quando `AGENTMEMORY_URL` aponta para um servidor agentmemory em execução; cai para 7 tools localmente quando não há servidor acessível)
+- 6 hooks de ciclo de vida: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 skills: `/recall`, `/remember`, `/session-history`, `/forget`
+
+A engine de hooks do Codex injeta `CLAUDE_PLUGIN_ROOT` nos subprocessos de hook (conforme [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), então os mesmos scripts de hook funcionam nos dois hosts sem duplicação. Os eventos Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure são exclusivos do Claude Code e não são registrados para o Codex.
+
+#### Codex Desktop: hooks do plugin atualmente silenciosos (com contorno)
+
+`CodexHooks` e `PluginHooks` são estáveis e habilitados por padrão em [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), mas as builds atuais do Codex Desktop não despacham `hooks.json` local de plugin ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). As tools MCP continuam funcionando; só as observações de ciclo de vida estão faltando.
+
+Até que o upstream corrija, espelhe os mesmos comandos de hook no `~/.codex/hooks.json` global:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+Isso adiciona um bloco idempotente em `~/.codex/hooks.json` referenciando caminhos absolutos para os scripts empacotados (sem necessidade de expansão de `${CLAUDE_PLUGIN_ROOT}` no escopo de usuário). Rode o mesmo comando novamente após atualizar o agentmemory para atualizar os caminhos. Entradas de usuário no mesmo arquivo são preservadas; só entradas anteriores do agentmemory são substituídas.
+
+<details>
+<summary><b>OpenClaw (cole este prompt)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+Guia completo: [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (cole este prompt)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Guia completo: [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### Outros agentes
+
+Inicie o servidor de memória: `npx @agentmemory/agentmemory`
+
+A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que usa o formato `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**Mescle esta entrada no objeto `mcpServers` existente** no arquivo de configuração do host — não substitua o arquivo. Se o arquivo já tem outros servidores, adicione `agentmemory` ao lado deles como outra chave dentro de `mcpServers`. Se `mcpServers` não existe, cole o bloco dentro de `{ "mcpServers": { ... } }`. Os placeholders `${VAR}` herdam `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` do shell no momento em que o servidor MCP sobe — variáveis não definidas passam string vazia e o shim cai para `http://localhost:3111`. Uma entrada cabeada cobre deploys tanto locais quanto remotos (k8s / com reverse-proxy).
+
+| Agente | Arquivo de configuração | Notas |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | Mescle em `mcpServers`. Deeplink de um clique também disponível no site. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Mescle em `mcpServers`. Reinicie o Claude Desktop após editar. |
+| **Cline / Roo Code / Kilo Code** | Configurações MCP do Cline (Settings UI → MCP Servers → Edit) | Mesmo bloco `mcpServers`. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Mesmo bloco `mcpServers`. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (mescla automaticamente). |
+| **OpenClaw** | Configuração MCP do OpenClaw | Mesmo bloco `mcpServers`, ou use o [memory plugin](../integrations/openclaw/) mais profundo. |
+| **Codex CLI (somente MCP)** | `.codex/config.toml` | Formato TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, ou adicione `[mcp_servers.agentmemory]` manualmente. |
+| **Codex CLI (plugin completo)** | Marketplace de plugins do Codex | `codex plugin marketplace add rohitg00/agentmemory` e depois `codex plugin add agentmemory@agentmemory`. Registra MCP + 6 hooks de ciclo de vida (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills. No Codex Desktop, rode também `agentmemory connect codex --with-hooks` até que [openai/codex#16430](https://github.com/openai/codex/issues/16430) seja mergeado — os hooks de plugin estão silenciosos lá. |
+| **OpenCode (somente MCP)** | `opencode.json` | Formato diferente — chave `mcp` no topo, comando como array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin completo)** | `plugin/opencode/` | 22 hooks de captura automática cobrindo ciclo de vida de sessão, mensagens, tools e erros. Dois comandos slash (`/recall`, `/remember`). Copie `plugin/opencode/` para seu workspace do OpenCode e adicione a entrada do plugin em `opencode.json`. Tabela completa de hooks + análise de gaps em [`plugin/opencode/README.md`](../plugin/opencode/README.md). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Copie [`integrations/pi`](../integrations/pi/) e reinicie o pi. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Use o [memory provider plugin](../integrations/hermes/) mais profundo com `memory.provider: agentmemory`. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` escreve o bloco `mcpServers` padrão. O payload dos hooks é compatível em nível de campo com o Claude Code, então os scripts dos 12 hooks existentes funcionam sem modificação — cabê-los na seção `hooks` do mesmo `settings.json`. |
+| **Antigravity** (substitui o Gemini CLI) | `mcp_config.json` (no diretório User do Antigravity) | `agentmemory connect antigravity` escreve o bloco `mcpServers` padrão. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Use após o sunset do Gemini CLI em 2026-06-18. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` escreve a configuração no nível do usuário. Overrides por workspace vão em `.kiro/settings/mcp.json` ao lado do seu código. |
+| **Goose** | UI de configurações MCP do Goose | Mesmo bloco `mcpServers`. |
+| **Aider** | n/a | Fale diretamente com a REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Qualquer agente (32+)** | n/a | `npx skillkit install agentmemory` autodetecta o host e mescla. |
+
+**Clientes MCP em sandbox** (Flatpak / Snap / contêineres restritivos) que não conseguem alcançar o `localhost` do host: também defina `"AGENTMEMORY_FORCE_PROXY": "1"` no bloco `env`, e aponte `AGENTMEMORY_URL` para uma rota que o sandbox realmente alcance (ex: seu IP de LAN). Veja [#234](https://github.com/rohitg00/agentmemory/issues/234) para o passo a passo de diagnóstico.
+
+### Acesso programático (Python / Rust / Node)
+
+agentmemory registra suas operações principais como funções iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Qualquer linguagem com um SDK iii pode chamá-las diretamente via `ws://localhost:49134` — sem um cliente REST separado por linguagem.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Exemplo prático: [`examples/python/`](../examples/python/) (quickstart + fluxo de observação/recall). A REST em `:3111` continua disponível para hosts sem runtime iii.
+
+### A partir do código-fonte
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Isso inicia o agentmemory com um `iii-engine` local se `iii` já estiver instalado, ou cai para Docker Compose se o Docker estiver disponível. REST, streams e o viewer fazem bind em `127.0.0.1` por padrão.
+
+Instale o `iii-engine` manualmente. **O agentmemory atualmente fixa o `iii-engine` em `v0.11.2`** — `v0.11.6` introduz um novo modelo que faz sandbox de tudo via `iii worker add` que o agentmemory ainda não foi refatorado para usar. O pin sai assim que o refactor cair. Sobrescreva com `AGENTMEMORY_III_VERSION=<version>` se você migrou manualmente para o modelo de sandbox.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** troque `aarch64-apple-darwin` por `x86_64-apple-darwin`
+- **Linux x64:** troque por `x86_64-unknown-linux-gnu`
+- **Linux arm64:** troque por `aarch64-unknown-linux-gnu`
+- **Windows:** baixe `iii-x86_64-pc-windows-msvc.zip` de [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extraia `iii.exe`, adicione ao PATH
+
+Ou use Docker (o `docker-compose.yml` empacotado puxa `iiidev/iii:0.11.2`). Docs completas: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory roda em Windows 10/11, mas só o pacote Node.js não é suficiente — você também precisa do runtime `iii-engine` (um binário nativo separado) como processo em segundo plano. O instalador oficial upstream é um script `sh` e hoje não há instalador PowerShell nem pacote scoop/winget, então usuários de Windows têm dois caminhos:
+
+**Opção A — Binário Windows pré-compilado (recomendado):**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
+#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
+#     model that engine v0.11.6+ requires)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe somewhere on PATH, or place it at:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory checks that location automatically)
+# 4. Verify:
+iii --version
+# Should print: 0.11.2
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory
+```
+
+**Opção B — Docker Desktop:**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Run agentmemory — it will auto-start the bundled compose file:
+npx -y @agentmemory/agentmemory
+```
+
+**Opção C — apenas MCP standalone (sem engine):** se você só precisa das tools MCP para seu agente e não precisa da REST API, viewer ou cron jobs, pule o engine completamente:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnóstico para Windows:** se `npx @agentmemory/agentmemory` falhar, rode novamente com `--verbose` para ver o stderr real do engine. Modos de falha comuns:
+
+| Sintoma | Correção |
+|---|---|
+| `iii-engine process started` seguido de `did not become ready within 15s` | Engine crashou na inicialização — rode novamente com `--verbose`, verifique stderr |
+| `Could not start iii-engine` | Nem `iii.exe` nem Docker estão instalados. Veja Opção A ou B acima |
+| Conflito de porta | `netstat -ano \| findstr :3111` para ver o que está em bind, mate o processo ou use `--port <N>` |
+| Fallback do Docker é pulado mesmo com Docker instalado | Confira se o Docker Desktop está de fato rodando (ícone na bandeja do sistema) |
+
+> Nota: não existe `cargo install iii-engine` — `iii` não é publicado no crates.io. Os únicos métodos de instalação suportados são o binário pré-compilado acima, o script de instalação `sh` upstream (somente macOS/Linux) e a imagem Docker.
+
+---
+
+<h2 id="deploy">Deploy</h2>
+
+Templates de um clique para hosts gerenciados. Cada um inclui um
+Dockerfile autocontido que puxa `@agentmemory/agentmemory` do npm
+e copia o binário do iii engine da imagem oficial `iiidev/iii` no
+Docker Hub — sem necessidade de imagem pré-compilada do agentmemory.
+Armazenamento persistente monta em `/data`; o entrypoint de primeiro
+boot sobrescreve a configuração iii empacotada pelo npm (que faz
+bind em `127.0.0.1`) por uma ajustada para deploy que faz bind em
+`0.0.0.0` e usa caminhos absolutos `/data`, gera o segredo HMAC e
+depois reduz privilégios de `root` para `node` via `gosu` antes de
+fazer exec do CLI do agentmemory.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+O botão de deploy de um clique do Render exige um `render.yaml` na raiz do repositório, que mantemos limpo de propósito. Use o fluxo Render Blueprint documentado em [`deploy/render/`](../deploy/render/README.md) para apontar para o blueprint do repo manualmente.
+
+Detalhes completos de setup (captura de HMAC, túnel SSH do viewer, rotação, backup, mínimos de custo) ficam em [`deploy/`](../deploy/README.md):
+
+- [`deploy/fly`](../deploy/fly/README.md) — máquina única com `auto_stop_machines = "stop"`; mais barato em idle.
+- [`deploy/railway`](../deploy/railway/README.md) — taxa plana do plano Hobby, volume no dashboard.
+- [`deploy/render`](../deploy/render/README.md) — fluxo Blueprint, snapshots automáticos de disco nos planos pagos.
+- [`deploy/coolify`](../deploy/coolify/README.md) — self-hosted no seu próprio VPS via [Coolify](https://coolify.io/self-hosted); mesma stack Docker Compose, você possui o host e os dados.
+
+Somente a porta `3111` é publicada. O viewer em `3113` fica em bind no loopback dentro do contêiner — o README de cada template documenta o padrão de túnel SSH para alcançá-lo.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Por que agentmemory" height="32" /></picture></h2>
+
+Todo agente de codificação esquece tudo quando a sessão termina. Você desperdiça os primeiros 5 minutos de toda sessão re-explicando sua stack. agentmemory roda em segundo plano e elimina isso por completo.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### vs memória integrada do agente
+
+Todo agente de codificação com IA vem com memória integrada — Claude Code tem `MEMORY.md`, Cursor tem notepads, Cline tem memory bank. Funcionam como post-its. agentmemory é o banco de dados pesquisável por trás dos post-its.
+
+| | Integrada (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Escala | teto de 200 linhas | Ilimitado |
+| Busca | Carrega tudo no contexto | BM25 + vector + graph (só top-K) |
+| Custo em tokens | 22K+ com 240 observações | ~1.900 tokens (92% menos) |
+| Cross-agent | Arquivos por agente | MCP + REST (qualquer agente) |
+| Coordenação | Nenhuma | Leases, signals, actions, routines |
+| Observabilidade | Leitura manual de arquivos | Viewer em tempo real em :3113 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="Como funciona" height="32" /></picture></h2>
+
+### Pipeline de memória
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### Consolidação de memória em 4 níveis
+
+Inspirada em como o cérebro humano processa memória — não muito diferente da consolidação do sono.
+
+| Nível | O quê | Analogia |
+|------|------|---------|
+| **Working** | Observações brutas a partir do uso de tools | Memória de curto prazo |
+| **Episodic** | Resumos de sessão comprimidos | "O que aconteceu" |
+| **Semantic** | Fatos e padrões extraídos | "O que eu sei" |
+| **Procedural** | Workflows e padrões de decisão | "Como fazer" |
+
+As memórias decaem com o tempo (curva de Ebbinghaus). Memórias acessadas com frequência se reforçam. Memórias velhas são evictadas automaticamente. Contradições são detectadas e resolvidas.
+
+### O que é capturado
+
+| Hook | Captura |
+|------|----------|
+| `SessionStart` | Caminho do projeto, ID da sessão |
+| `UserPromptSubmit` | Prompts do usuário (filtrados por privacidade) |
+| `PreToolUse` | Padrões de acesso a arquivos + contexto enriquecido |
+| `PostToolUse` | Nome da tool, entrada, saída |
+| `PostToolUseFailure` | Contexto do erro |
+| `PreCompact` | Reinjeta memória antes da compactação |
+| `SubagentStart/Stop` | Ciclo de vida de sub-agentes |
+| `Stop` | Resumo de fim de sessão |
+| `SessionEnd` | Marcador de sessão completa |
+
+### Principais capacidades
+
+| Capacidade | Descrição |
+|---|---|
+| **Captura automática** | Todo uso de tool registrado via hooks — esforço manual zero |
+| **Busca semântica** | BM25 + vector + grafo de conhecimento com fusão RRF |
+| **Evolução de memória** | Versionamento, supersessão, grafos de relacionamento |
+| **Auto-esquecimento** | Expiração por TTL, detecção de contradição, evicção por importância |
+| **Privacy first** | API keys, segredos e tags `<private>` são removidos antes do armazenamento |
+| **Self-healing** | Circuit breaker, cadeia de fallback de providers, monitoramento de saúde |
+| **Ponte Claude** | Sincronização bidirecional com MEMORY.md |
+| **Grafo de conhecimento** | Extração de entidades + travessia BFS |
+| **Memória de time** | Compartilhado namespaced + privado entre membros do time |
+| **Provenance de citação** | Rastreia qualquer memória de volta às observações originais |
+| **Snapshots Git** | Versiona, faz rollback e diff do estado de memória |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Busca" height="32" /></picture></h2>
+
+Recuperação triple-stream combinando três sinais:
+
+| Stream | O que faz | Quando |
+|---|---|---|
+| **BM25** | Matching de palavra-chave com stemming + expansão de sinônimos | Sempre ativo |
+| **Vector** | Similaridade de cosseno sobre embeddings densos | Provider de embedding configurado |
+| **Graph** | Travessia do grafo de conhecimento via matching de entidades | Entidades detectadas na query |
+
+Fundidos com Reciprocal Rank Fusion (RRF, k=60) e diversificados por sessão (máximo de 3 resultados por sessão).
+
+BM25 tokeniza grego, cirílico, hebraico, árabe e latim acentuado de fábrica. Para memórias em chinês / japonês / coreano, instale os segmentadores opcionais (`npm install @node-rs/jieba tiny-segmenter`) para quebrar runs CJK em tokens em nível de palavra; sem eles, o agentmemory faz soft-fallback para tokenização por run inteiro e imprime uma dica única no stderr.
+
+### Providers de embedding
+
+agentmemory autodetecta seu provider. Para melhores resultados, instale embeddings locais (gratuito):
+
+```bash
+npm install @xenova/transformers
+```
+
+| Provider | Modelo | Custo | Notas |
+|---|---|---|---|
+| **Local (recomendado)** | `all-MiniLM-L6-v2` | Gratuito | Offline, +8pp de recall sobre BM25-only |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ idiomas, 768/1536/3072 dims (MRL), entrada de 2048 tokens. Substitui `text-embedding-004` ([deprecado, encerramento em 14 de janeiro de 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Maior qualidade |
+| Voyage AI | `voyage-code-3` | Pago | Otimizado para código |
+| Cohere | `embed-english-v3.0` | Trial gratuito | Uso geral |
+| OpenRouter | Qualquer modelo | Varia | Proxy multi-modelo |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="Servidor MCP" height="32" /></picture></h2>
+
+53 tools, 6 resources, 3 prompts e 4 skills — o toolkit MCP de memória mais completo para qualquer agente.
+
+> **Shim MCP vs servidor completo:** o pacote publicado `@agentmemory/mcp` é um shim fino. Expõe a superfície completa de 51 tools **apenas quando consegue alcançar um servidor agentmemory em execução** via `AGENTMEMORY_URL` (modo proxy). Sem servidor acessível, o shim cai para um set local de 7 tools (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). A variável de ambiente `AGENTMEMORY_TOOLS=core|all` é uma flag *do lado do servidor* — defini-la no bloco `env` do shim não tem efeito. Se você vê só 7 tools no Cursor / OpenCode / Gemini CLI, inicie `npx @agentmemory/agentmemory` (ou a stack Docker) e defina `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 51 Tools
+
+<details>
+<summary>Tools principais (sempre disponíveis)</summary>
+
+| Tool | Descrição |
+|------|-------------|
+| `memory_recall` | Busca observações passadas |
+| `memory_compress_file` | Comprime arquivos markdown preservando a estrutura |
+| `memory_save` | Salva um insight, decisão ou padrão |
+| `memory_patterns` | Detecta padrões recorrentes |
+| `memory_smart_search` | Busca híbrida semântica + por palavras |
+| `memory_file_history` | Observações passadas sobre arquivos específicos |
+| `memory_sessions` | Lista sessões recentes |
+| `memory_timeline` | Observações cronológicas |
+| `memory_profile` | Perfil de projeto (conceitos, arquivos, padrões) |
+| `memory_export` | Exporta todos os dados de memória |
+| `memory_relations` | Consulta o grafo de relacionamentos |
+
+</details>
+
+<details>
+<summary>Tools estendidas (51 no total — defina AGENTMEMORY_TOOLS=all)</summary>
+
+| Tool | Descrição |
+|------|-------------|
+| `memory_patterns` | Detecta padrões recorrentes |
+| `memory_timeline` | Observações cronológicas |
+| `memory_relations` | Consulta o grafo de relacionamentos |
+| `memory_graph_query` | Travessia do grafo de conhecimento |
+| `memory_consolidate` | Executa a consolidação de 4 níveis |
+| `memory_claude_bridge_sync` | Sincroniza com MEMORY.md |
+| `memory_team_share` | Compartilha com membros do time |
+| `memory_team_feed` | Itens compartilhados recentes |
+| `memory_audit` | Trilha de auditoria de operações |
+| `memory_governance_delete` | Deleção com trilha de auditoria |
+| `memory_snapshot_create` | Snapshot versionado no Git |
+| `memory_action_create` | Cria itens de trabalho com dependências |
+| `memory_action_update` | Atualiza status de action |
+| `memory_frontier` | Actions desbloqueadas ranqueadas por prioridade |
+| `memory_next` | A única action mais importante a seguir |
+| `memory_lease` | Leases exclusivos de actions (multiagente) |
+| `memory_routine_run` | Instancia rotinas de workflow |
+| `memory_signal_send` | Mensageria entre agentes |
+| `memory_signal_read` | Lê mensagens com confirmação de recebimento |
+| `memory_checkpoint` | Portões de condições externas |
+| `memory_mesh_sync` | Sincronização P2P entre instâncias |
+| `memory_sentinel_create` | Watchers dirigidos por eventos |
+| `memory_sentinel_trigger` | Dispara sentinels externamente |
+| `memory_sketch_create` | Grafos de actions efêmeros |
+| `memory_sketch_promote` | Promove para permanente |
+| `memory_crystallize` | Compacta cadeias de actions |
+| `memory_diagnose` | Health checks |
+| `memory_heal` | Corrige automaticamente estado travado |
+| `memory_facet_tag` | Tags dimension:value |
+| `memory_facet_query` | Consulta por tags de facet |
+| `memory_verify` | Rastreia provenance |
+
+</details>
+
+### 6 Resources · 3 Prompts · 4 Skills
+
+| Tipo | Nome | Descrição |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Saúde, contagem de sessões, contagem de memórias |
+| Resource | `agentmemory://project/{name}/profile` | Inteligência por projeto |
+| Resource | `agentmemory://memories/latest` | As 10 memórias ativas mais recentes |
+| Resource | `agentmemory://graph/stats` | Estatísticas do grafo de conhecimento |
+| Prompt | `recall_context` | Busca + retorna mensagens de contexto |
+| Prompt | `session_handoff` | Dados de handoff entre agentes |
+| Prompt | `detect_patterns` | Analisa padrões recorrentes |
+| Skill | `/recall` | Busca na memória |
+| Skill | `/remember` | Salva na memória de longo prazo |
+| Skill | `/session-history` | Resumos recentes de sessões |
+| Skill | `/forget` | Deleta observações/sessões |
+
+### MCP standalone
+
+Rode sem o servidor completo — para qualquer cliente MCP. Qualquer um destes funciona:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # canonical (always available)
+npx -y @agentmemory/mcp                # shim package alias
+```
+
+Ou adicione à configuração MCP do seu agente:
+
+A maioria dos agentes (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+Mescle a entrada `agentmemory` no objeto `mcpServers` existente do seu host em vez de substituir o arquivo. Para clientes em sandbox que não conseguem alcançar o `localhost` do host, adicione `"AGENTMEMORY_FORCE_PROXY": "1"` ao bloco env e defina `AGENTMEMORY_URL` para uma rota que o sandbox alcance.
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copie o arquivo do plugin do repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Viewer em tempo real" height="32" /></picture></h2>
+
+Sobe automaticamente na porta `3113`. Stream ao vivo de observações, explorador de sessões, navegador de memórias, visualização do grafo de conhecimento e dashboard de saúde.
+
+```bash
+open http://localhost:3113
+```
+
+O servidor do viewer faz bind em `127.0.0.1` por padrão. O endpoint servido por REST `/agentmemory/viewer` segue as regras normais de bearer-token `AGENTMEMORY_SECRET`. Os headers CSP usam um nonce de script por resposta e desabilitam atributos de handler inline (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+O viewer em `:3113` mostra o que seu agente **lembrou**. O [iii console](https://iii.dev/docs/console) mostra o que seu agente **fez** — cada operação de memória como uma trace do OpenTelemetry, cada entrada KV editável, cada função invocável, cada stream observável. Duas janelas sobre a mesma memória: uma em formato de produto, outra em formato de engine.
+
+Veja um `memory_smart_search` disparar e enxergue o scan BM25 → busca de embedding → fusão RRF → reranker como um waterfall. Edite um timer de consolidação travado no navegador KV. Reproduza um hook `PostToolUse` com payload ajustado. Fixe o stream WebSocket e veja as observações chegando ao vivo.
+
+agentmemory oferece isso de graça porque toda função, trigger, escopo de estado e stream é um primitivo iii — nada custom, nada para instrumentar.
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="Página Workers do iii console — workers conectados incluindo instâncias do agentmemory com contagem de funções ao vivo e metadados de runtime" width="720" />
+  <br/>
+  <em>Página Workers: todo worker conectado — incluindo o próprio agentmemory — com PID, contagem de funções, runtime e last-seen.</em>
+</p>
+
+**Já instalado.** O console vem junto com `iii` — sem instalador separado.
+
+**Suba junto com o agentmemory:**
+
+```bash
+# agentmemory viewer holds port 3113, so run the console on 3114.
+# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
+iii console --port 3114
+```
+
+Depois abra `http://localhost:3114`. Adicione `--enable-flow` para a página experimental de grafo de arquitetura.
+
+Sobrescreva endpoints do engine apenas se você os tiver movido:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**O que você pode fazer pelo console:**
+
+| Página | Use para |
+|------|-----------|
+| **Workers** | Ver todo worker conectado e suas métricas ao vivo — incluindo o próprio worker do agentmemory. |
+| **Functions** | Invocar qualquer função do agentmemory diretamente com um payload JSON — útil para testar `memory.recall`, `memory.consolidate`, `graph.query` sem cabear um cliente. |
+| **Triggers** | Reproduzir triggers HTTP, cron, event e state — disparar o cron de consolidação manualmente, reexecutar uma rota HTTP, emitir uma mudança de estado. |
+| **States** | Navegador KV com CRUD completo — sessões, slots de memória, timers de ciclo de vida, índice de embeddings — edite valores no lugar. |
+| **Streams** | Monitor WebSocket ao vivo para escritas de memória, eventos de hook e atualizações de observação à medida que fluem pelos streams iii. |
+| **Queues** | Tópicos de fila duráveis + gestão de dead-letter. Reproduza ou descarte jobs de embedding / compressão que falharam. |
+| **Traces** | Vistas waterfall / flame / breakdown por serviço do OpenTelemetry. Filtre por `trace_id` para ver exatamente quais funções, chamadas a DB e requisições de embedding um único `memory.search` produziu. |
+| **Logs** | Logs OTEL estruturados filtrados e correlacionados a trace/span IDs. |
+| **Config** | Configuração de runtime — veja exatamente com quais workers, providers e portas seu engine está rodando. |
+| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitetura interativo de todo worker, trigger e stream. |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="Visão waterfall de trace do iii console mostrando duração por span" width="720" />
+  <br/>
+  <em>Traces: waterfall / flame / breakdown por serviço para toda operação de memória.</em>
+</p>
+
+**Traces já estão ativos:**
+
+`iii-config.yaml` vem com o worker `iii-observability` habilitado (`exporter: memory`, `sampling_ratio: 1.0`, métricas + logs). Sem configuração extra — no momento em que o agentmemory inicia, toda operação de memória emite um trace span e um log estruturado que o console consegue ler.
+
+Se você quiser exportar para Jaeger/Honeycomb/Grafana Tempo, troque `exporter: memory` por `exporter: otlp` e configure o endpoint do collector conforme a documentação de observabilidade do iii.
+
+> **Aviso:** nenhum auth é aplicado no console em si — mantenha-o em bind em `127.0.0.1` (o padrão) e nunca o exponha publicamente.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory **já é uma instância [iii](https://iii.dev) em execução**. Funções, triggers, estado KV, streams, traces OTEL — tudo são primitivos iii. Você não instalou Postgres, Redis, Express, pm2 ou Prometheus, porque o iii os substitui.
+
+Isso significa que mais um comando estende o agentmemory com uma capacidade totalmente nova.
+
+### Estenda o agentmemory com um comando
+
+```bash
+iii worker add iii-pubsub          # fan memory writes out to every connected instance
+iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
+iii worker add iii-queue           # durable retries for embedding + compression jobs
+iii worker add iii-observability   # OTEL traces on every memory op (default on)
+iii worker add iii-sandbox         # run recalled code inside an isolated microVM
+iii worker add iii-database        # swap in a SQL-backed state adapter
+iii worker add mcp                 # generic MCP host alongside the agentmemory MCP
+```
+
+Cada `iii worker add` registra novas funções e triggers no mesmo engine onde o agentmemory já está rodando. O viewer e o console os reconhecem na hora — sem reload, sem nova integração, sem novo contêiner.
+
+| `iii worker add` | O que você ganha em cima do agentmemory |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Memória multi-instância: todo `remember` faz fanout, todo `search` lê a união |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Ciclo de vida agendado — consolidação noturna, snapshots semanais, decaimento em relógio fixo |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Retries duráveis: jobs falhos de embedding + compressão sobrevivem a restart, sem observações perdidas |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | Traces OTEL, métricas, logs em toda função — cabeado em `iii-config.yaml` desde o primeiro dia |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Código que veio do `memory_recall` roda dentro de uma VM descartável, não no seu shell |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | Adaptador de estado baseado em SQL quando você ultrapassa o KV in-memory padrão |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Suba servidores MCP adicionais ao lado do MCP do agentmemory, compartilhando o mesmo engine |
+
+Registry completo: [workers.iii.dev](https://workers.iii.dev). Todo worker lá se compõe pelos mesmos primitivos que o agentmemory usa — e o agentmemory que você já tem é um deles.
+
+### O que o iii substitui
+
+| Stack tradicional | agentmemory usa |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + índice vetorial in-memory |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | Supervisão de workers do iii engine |
+| Prometheus / Grafana | iii OTEL + monitor de saúde |
+| Sistemas de plugin customizados | `iii worker add <name>` |
+
+**118 arquivos de código · ~21.800 LOC · 950+ tests · 123 funções · 34 escopos KV** — tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuração" height="32" /></picture></h2>
+
+### Providers de LLM
+
+agentmemory autodetecta a partir do seu ambiente. Por padrão, nenhuma chamada LLM é feita a menos que você configure um provider ou opte explicitamente pelo fallback de assinatura do Claude.
+
+| Provider | Config | Notas |
+|----------|--------|-------|
+| **No-op (padrão)** | Sem configuração | Compress/summarize via LLM DESATIVADO. Compressão sintética BM25 + recall ainda funcionam. Veja `AGENTMEMORY_ALLOW_AGENT_SDK` abaixo se você dependia do fallback de assinatura do Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Cobrança por token |
+| MiniMax | `MINIMAX_API_KEY` | Compatível com Anthropic |
+| Gemini | `GEMINI_API_KEY` | Também habilita embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Qualquer modelo |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Apenas opt-in. Cria sessões de `@anthropic-ai/claude-agent-sdk` — costumava causar recursão sem limite no Stop-hook (seguimento do #149), por isso não é mais o padrão. |
+
+### Seleção de modelo com consciência de custo
+
+A compressão em background roda em toda observação, então a escolha de modelo muda o gasto mensal de forma significativa. Dados de workload capturados: 635 requisições / 888K tokens / 35 horas de uso ativo, executados contra três modelos OpenRouter a preços de 2026-05-23.
+
+| Tier | Modelo | Input / 1M | Output / 1M | Custo para as 35h capturadas | Notas |
+|------|-------|------------|-------------|---------------------------|-------|
+| Recomendado | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Qualidade sólida de compressão + sumarização a um custo ~10× menor que o Sonnet. |
+| Recomendado | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | Mais antigo mas ainda OK para workloads só de compressão. |
+| Recomendado | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Bom raciocínio de código se suas sessões forem muito orientadas a código. |
+| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | Alta qualidade, mas caro para trabalho de background sempre ativo. |
+| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Tier similar ao Sonnet. |
+| Evitar | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | Modelo classe reasoning; gasto desproporcional para compressão. |
+
+agentmemory imprime um aviso em runtime quando `OPENROUTER_MODEL` casa com um padrão de tier premium. Defina `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para silenciar depois que você tiver tomado uma decisão informada.
+
+Trade-off qualidade vs custo para trabalho de memória: compressão é uma tarefa de sumarização com critério de qualidade relativamente frouxo (quem relê o resumo é o agente, não o usuário). DeepSeek-V4-Pro / Qwen3-Coder ficam dentro do erro de arredondamento do Sonnet nessa tarefa, custando ~10× menos. Reserve os modelos tier premium para as queries que você lê diretamente.
+
+Fontes: [OpenRouter pricing for Sonnet 4.6](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Memória multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Em setups multiagente onde vários papéis compartilham um servidor agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` etiqueta cada escrita com o papel que a fez. `AGENTMEMORY_AGENT_SCOPE` controla se o recall filtra por essa tag.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"
+```
+
+Dois modos:
+
+| Modo | Etiqueta escritas | Filtra recall | Quando usar |
+|------|------------|---------------|-------------|
+| `shared` (padrão) | sim | não | Contexto cross-agent com trilha de auditoria. O architect pode ver o que o developer anotou, mas toda linha registra quem disse. |
+| `isolated` | sim | sim | Separação estrita. O architect nunca vê observações / memórias / sessões do developer. |
+
+O que é etiquetado quando `AGENT_ID` está definido: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. O papel flui `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+O que é filtrado no modo isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Cada endpoint aceita `?agentId=<role>` para sobrescrever por requisição, e `?agentId=*` para sair do escopo do env por completo. `/memories` também aceita `?includeOrphans=true` para mostrar memórias pré-AGENT_ID cujo `agentId` é undefined.
+
+Override por chamada na camada SDK / REST: todo endpoint mutador (`/session/start`, `/remember`) aceita um campo `agentId` no body da requisição que vence o env. Útil para runtimes que roteiam muitos papéis por um único processo de servidor.
+
+Quando `AGENT_ID` não está definido, a memória permanece sem escopo (comportamento legado, sem tags, sem filtros).
+
+### Portas
+
+agentmemory + iii-engine fazem bind em quatro portas por padrão. Se um restart falhar com `port in use`, esta tabela diz qual processo procurar.
+
+| Porta | Processo | Propósito | Override por env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker de streams interno (consumido por agentmemory + viewer) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer em tempo real (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — workers se registram aqui, telemetria OTel flui por cima | `III_ENGINE_URL` (URL completa, padrão `ws://localhost:49134`) |
+
+Limpeza de processo travado quando as portas ficam ocupadas após uma execução crashada:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` recolhe tanto o worker quanto o pidfile do engine de forma limpa no shutdown graceful (#640, #474). A limpeza manual acima só serve para o caso pós-crash em que nenhum pidfile foi deixado para trás.
+
+### Arquivo de configuração
+
+Coloque a configuração de runtime do agentmemory em `~/.agentmemory/.env` em vez de exportar variáveis em cada shell. Se o viewer mostrar uma dica de setup como `export ANTHROPIC_API_KEY=...`, copie para este arquivo como `ANTHROPIC_API_KEY=...` sem o prefixo `export`, depois reinicie o agentmemory.
+
+Variáveis de ambiente do processo continuam funcionando e têm precedência sobre os valores no arquivo.
+
+No Windows, o mesmo arquivo fica em `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Para testar com uma assinatura Claude Code Pro/Max em vez de uma API key, faça opt-in explícito:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Ligue features de graph ou consolidation no mesmo arquivo se quiser:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### Variáveis de ambiente
+
+Crie `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+124 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer <secret>` quando `AGENTMEMORY_SECRET` está definido, e endpoints de mesh sync exigem `AGENTMEMORY_SECRET` em ambos os peers.
+
+<details>
+<summary>Endpoints principais</summary>
+
+| Method | Path | Descrição |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (sempre público) |
+| `POST` | `/agentmemory/session/start` | Inicia sessão + obtém contexto |
+| `POST` | `/agentmemory/session/end` | Encerra sessão |
+| `POST` | `/agentmemory/observe` | Captura observação |
+| `POST` | `/agentmemory/smart-search` | Busca híbrida |
+| `POST` | `/agentmemory/context` | Gera contexto |
+| `POST` | `/agentmemory/remember` | Salva na memória de longo prazo |
+| `POST` | `/agentmemory/forget` | Deleta observações |
+| `POST` | `/agentmemory/enrich` | Contexto de arquivo + memórias + bugs |
+| `GET` | `/agentmemory/profile` | Perfil de projeto |
+| `GET` | `/agentmemory/export` | Exporta todos os dados |
+| `POST` | `/agentmemory/import` | Importa de JSON |
+| `POST` | `/agentmemory/graph/query` | Query do grafo de conhecimento |
+| `POST` | `/agentmemory/team/share` | Compartilha com o time |
+| `GET` | `/agentmemory/audit` | Trilha de auditoria |
+
+Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Desenvolvimento" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ tests
+npm run test:integration  # API tests (requires running services)
+```
+
+**Pré-requisitos:** Node.js >= 20, [iii-engine](https://iii.dev/docs) ou Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licença" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.tr-TR.md

@@ -0,0 +1,1381 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — AI kodlama ajanları için kalıcı bellek" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    Kodlama ajanınız her şeyi hatırlasın. Aynı şeyi bir daha açıklamayın.
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ve her MCP istemcisi için kalıcı bellek.
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  Türkçe |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1200 stars / 172 forks on the gist" /></a>
+</p>
+
+<p align="center">
+  <em>Bu gist, Karpathy'nin LLM Wiki desenini güven puanlaması, yaşam döngüsü, bilgi grafları ve hibrit aramayla genişletir: agentmemory bunun uygulamasıdır.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">Kurulum</a> &bull;
+  <a href="#quick-start">Hızlı Başlangıç</a> &bull;
+  <a href="#benchmarks">Kıyaslamalar</a> &bull;
+  <a href="#vs-competitors">Rakiplerle Karşılaştırma</a> &bull;
+  <a href="#works-with-every-agent">Ajanlar</a> &bull;
+  <a href="#how-it-works">Nasıl Çalışır</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">Görüntüleyici</a> &bull;
+  <a href="#iii-console">iii Konsolu</a> &bull;
+  <a href="#powered-by-iii">iii ile çalışır</a> &bull;
+  <a href="#configuration">Yapılandırma</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## Kurulum
+
+```bash
+npm install -g @agentmemory/agentmemory          # bir kez — `agentmemory` PATH'te kullanılabilir
+# macOS/Linux sistem Node kurulumlarında EACCES hatası alırsanız şununla deneyin:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # bellek sunucusunu :3111 üzerinde başlat
+agentmemory demo                                 # örnek oturumlar yükle + recall'u kanıtla
+agentmemory connect claude-code                  # ajanınızı bağlayın (ayrıca: codex, cursor, gemini-cli, ...)
+```
+
+Veya `npx` ile (kurulum gerekmez):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+Dikkat — npx sürüm bazında önbelleğe alır. Eğer çıplak bir `npx @agentmemory/agentmemory` eski bir sürümü servis ediyorsa, en güncelini `npx -y @agentmemory/agentmemory@latest` ile zorlayın veya önbelleği `rm -rf ~/.npm/_npx` ile bir kez temizleyin (macOS/Linux; Windows'ta `%LOCALAPPDATA%\npm-cache\_npx` dizinini silin). v0.9.16+ sonrası ilk npx çalıştırması, çıplak `agentmemory` komutunun her yerden çalışması için global kurulum yapmanızı satır içi olarak sorar.
+
+Tüm seçenekler aşağıdaki [Hızlı Başlangıç](#quick-start) bölümünde. Ajana özel bağlantılar için [Her ajanla çalışır](#works-with-every-agent) bölümüne bakın.
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
+
+agentmemory; hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalışır. Tüm ajanlar aynı bellek sunucusunu paylaşır.
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>yerel eklenti + 12 hook + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>yerel eklenti + 6 hook + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>yerel eklenti + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>yerel eklenti + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>yerel eklenti + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>yerel Memory trait arka uç</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hook + MCP + eklenti</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP sunucusu</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>MCP veya HTTP konuşan <strong>herhangi bir</strong> ajanla çalışır. Tek sunucu, tüm ajanlar arasında paylaşılan bellek.</sub>
+</p>
+
+---
+
+Her oturumda aynı mimariyi tekrar tekrar anlatıyorsunuz. Aynı bug'ları yeniden keşfediyorsunuz. Aynı tercihleri yeniden öğretiyorsunuz. Yerleşik bellek (CLAUDE.md, .cursorrules) 200 satırda tıkanır ve eskir. agentmemory bunu düzeltir. Ajanınızın yaptıklarını sessizce yakalar, aranabilir belleğe sıkıştırır ve bir sonraki oturum başladığında doğru bağlamı enjekte eder. Tek komut. Ajanlar arası çalışır.
+
+**Neler değişiyor:** Oturum 1'de JWT kimlik doğrulamasını kuruyorsunuz. Oturum 2'de hız sınırlaması istiyorsunuz. Ajan zaten biliyor: kimlik doğrulamanız `src/middleware/auth.ts` içinde jose middleware kullanıyor, testleriniz token doğrulamasını kapsıyor ve Edge uyumluluğu için jsonwebtoken yerine jose'yi seçtiniz. Yeniden anlatma yok. Kopyala-yapıştır yok. Ajan basitçe *biliyor*.
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **v0.9.0'da yeni** — [agent-memory.dev](https://agent-memory.dev) tanıtım sitesi, dosya sistemi bağlayıcısı (`@agentmemory/fs-watcher`), bağımsız MCP artık çalışan sunucuya proxy yapıyor (böylece hook'lar ve görüntüleyici hemfikir), her silme yolunda kodlanmış denetim politikası, küçük Node süreçlerinde sağlık `memory_critical` olarak işaretlenmiyor. Tüm notlar [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18) içinde.
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### Geri Getirme Doğruluğu
+
+**coding-agent-life-v1** (kurum içi corpus, sandbox-yeniden üretilebilir)
+
+| Adaptör | P@5 | R@5 | Top-5 isabet oranı | p50 gecikme |
+|---|---|---|---|---|
+| **agentmemory hibrit** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep referansı | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+%100 Top-5 isabet oranı. Aynı girdide grep referansından **2.2×** daha iyi hassasiyet. Tam tip bazında döküm: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 soru)
+
+| Sistem | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Yalnız BM25 yedeği | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Token Tasarrufu
+
+| Yaklaşım | Token/yıl | Maliyet/yıl |
+|---|---|---|
+| Tam bağlamı yapıştır | 19.5M+ | İmkansız (pencereyi aşar) |
+| LLM-özetlenmiş | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + yerel embedding | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> Embedding modeli: `all-MiniLM-L6-v2` (yerel, ücretsiz, API anahtarı gerekmez). Tam raporlar: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Rakip karşılaştırması: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory'nin mem0, Letta, Khoj, claude-mem, Hippo ile karşılaştırması.
+
+**Yerel olarak yeniden üretin:** [`eval/README.md`](../eval/README.md) — LongMemEval `_s` (genel 500 soru) + `coding-agent-life-v1` (kurum içi 15 oturum corpus) için adaptör-takılabilir harness. Grep / vektör / agentmemory adaptörleri yan yana puanlanır, NDJSON çıktısı, yayımlanan puan tabloları [`docs/benchmarks/`](../docs/benchmarks/) içine düşer.
+
+**[codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) ve [Graphify](https://github.com/safishamsi/graphify) ile birlikte çalışır.** Kod-graf indeksleme, çok-ajanlı build pipeline'ları ve doküman / PDF / görsel / video boyunca daha geniş bilgi grafları. agentmemory çalışmayı hatırlar; bu üç proje bağlam katmanının geri kalanını aydınlatır. Tarifler + soru-yönlendirme tablosu: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="vs Competitors" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">Yerleşik (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>Tür</strong></td>
+<td>Bellek motoru + MCP sunucusu</td>
+<td>Bellek katmanı API'si</td>
+<td>Tam ajan runtime'ı</td>
+<td>Statik dosya</td>
+</tr>
+<tr>
+<td><strong>Geri getirme R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>Otomatik yakalama</strong></td>
+<td>12 hook (sıfır manuel çaba)</td>
+<td>Manuel <code>add()</code> çağrıları</td>
+<td>Ajan kendi düzenler</td>
+<td>Manuel düzenleme</td>
+</tr>
+<tr>
+<td><strong>Arama</strong></td>
+<td>BM25 + Vektör + Graf (RRF füzyonu)</td>
+<td>Vektör + Graf</td>
+<td>Vektör (arşiv)</td>
+<td>Her şeyi bağlama yükler</td>
+</tr>
+<tr>
+<td><strong>Çoklu ajan</strong></td>
+<td>MCP + REST + lease'ler + sinyaller</td>
+<td>API (koordinasyon yok)</td>
+<td>Yalnızca Letta runtime'ı içinde</td>
+<td>Ajan başına dosya</td>
+</tr>
+<tr>
+<td><strong>Framework bağımlılığı</strong></td>
+<td>Yok (herhangi bir MCP istemcisi)</td>
+<td>Yok</td>
+<td>Yüksek (Letta kullanılmalı)</td>
+<td>Ajan başına format</td>
+</tr>
+<tr>
+<td><strong>Harici bağımlılıklar</strong></td>
+<td>Yok (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + vektör DB</td>
+<td>Yok</td>
+</tr>
+<tr>
+<td><strong>Bellek yaşam döngüsü</strong></td>
+<td>4 katmanlı konsolidasyon + decay + otomatik-unutma</td>
+<td>Pasif çıkarım</td>
+<td>Ajan-yönetimli</td>
+<td>Manuel ayıklama</td>
+</tr>
+<tr>
+<td><strong>Token verimliliği</strong></td>
+<td>~1,900 token/oturum ($10/yıl)</td>
+<td>Entegrasyona göre değişir</td>
+<td>Çekirdek bellek bağlamda</td>
+<td>240 gözlemde 22K+ token</td>
+</tr>
+<tr>
+<td><strong>Gerçek zamanlı görüntüleyici</strong></td>
+<td>Var (port 3113)</td>
+<td>Bulut panel</td>
+<td>Bulut panel</td>
+<td>Yok</td>
+</tr>
+<tr>
+<td><strong>Self-hosted</strong></td>
+<td>Evet (varsayılan)</td>
+<td>İsteğe bağlı</td>
+<td>İsteğe bağlı</td>
+<td>Evet</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
+
+Uyumluluk: bu sürüm kararlı `iii-sdk` `^0.11.0` ve iii-engine v0.11.x'i hedefler.
+
+### 30 saniyede deneyin
+
+```bash
+# Terminal 1: sunucuyu başlatın
+npx @agentmemory/agentmemory
+
+# Terminal 2: örnek veriyi yükleyin ve geri çağırmayı iş başında görün
+npx @agentmemory/agentmemory demo
+```
+
+`demo`, 3 gerçekçi oturum yükler (JWT auth, N+1 sorgu düzeltmesi, hız sınırlaması) ve bunlar üzerinde anlamsal aramalar çalıştırır. "veritabanı performans optimizasyonu" araması yaptığınızda "N+1 sorgu düzeltmesi"ni bulduğunu göreceksiniz — anahtar kelime eşleştirmesi bunu yapamaz.
+
+Belleğin canlı oluşumunu izlemek için `http://localhost:3113` adresini açın.
+
+### Önerilen: globally kurun
+
+`npx` sürüm bazında önbelleğe alır. Geçen hafta `npx @agentmemory/agentmemory@0.9.14`'ü çalıştırdıysanız, çıplak bir `npx @agentmemory/agentmemory` `~/.npm/_npx/`'ten en son sürümü değil, eski 0.9.14'ü servis edebilir. Bir kez kurun ve çıplak `agentmemory` komutu her yerde çalışsın:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# macOS/Linux sistem Node kurulumlarında EACCES hatası alırsanız şununla deneyin:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # sunucuyu başlatın (npx şekliyle aynı)
+agentmemory stop               # kapatın
+agentmemory remove             # oluşturduğumuz her şeyi kaldırın
+agentmemory connect claude-code   # tek bir ajanı bağlayın
+agentmemory doctor             # interaktif teşhis + düzeltme istemleri
+```
+
+v0.9.16 ve sonrası ile birlikte, ilk npx çalıştırması global kurmanızı satır içi olarak ister — bir kez `Y` yanıtlayın, hazırsınız. Atlarsanız, taze bir indirme için şunlardan birine geri dönün:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # npm'den en güncelini zorlar (platformlar arası)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # yalnız macOS/Linux (POSIX shell)
+```
+
+Windows / PowerShell'de eşdeğer cache temizleme komutu `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` şeklindedir — yukarıdaki `npx -y ...@latest` formu platformlar arası seçenektir.
+
+### Oturum Tekrar Oynatma (Session Replay)
+
+agentmemory'nin kaydettiği her oturum tekrar oynatılabilir. Görüntüleyiciyi açın, **Replay** sekmesini seçin ve zaman çizelgesini tarayın: istemler, araç çağrıları, araç sonuçları ve yanıtlar; oynat/duraklat, hız kontrolü (0.5×–4×) ve klavye kısayollarıyla (boşluk geçiş, oklar adım atlama) ayrı olaylar olarak görüntülenir.
+
+Halihazırda içeri aktarmak istediğiniz eski Claude Code JSONL kayıtlarınız mı var?
+
+```bash
+# Varsayılan ~/.claude/projects altındaki her şeyi içeri aktar
+npx @agentmemory/agentmemory import-jsonl
+
+# Veya tek bir dosya içeri aktar
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+İçeri aktarılan oturumlar yerli olanların yanında Replay seçicisinde görünür. Arka planda her giriş `mem::replay::load`, `mem::replay::sessions` ve `mem::replay::import-jsonl` iii fonksiyonları üzerinden yönlendirilir — yan kanal sunucu yok.
+
+### Yükseltme / Bakım
+
+Yerel runtime'ınızı bilinçli olarak güncellemek istediğinizde bakım komutunu kullanın:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+Uyarı: bu komut mevcut çalışma alanını/runtime'ı değiştirir. JavaScript bağımlılıklarını güncelleyebilir, `cargo install iii-engine --force` çalıştırabilir ve Docker imajlarını çekebilir.
+
+Uygulama detayları `src/cli.ts` içinde (`src/cli.ts:544-595` bölgesi civarında `runUpgrade`'a bakın).
+
+### Claude Code (tek blok, yapıştırın)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Eklenti kurulumu olmadan Claude Code (MCP-bağımsız yol)
+
+Eğer `/plugin install` kullanmak yerine agentmemory'nin MCP sunucusunu doğrudan `~/.claude.json` üzerinden bağlarsanız, Claude Code `${CLAUDE_PLUGIN_ROOT}`'u asla çözmez ve hook scriptlerini `~/.claude/settings.json` içinde mutlak yollara işaret etmek zorunda kalırsınız. Bu yollar genellikle agentmemory sürümünü gömer (örn. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), bu yüzden bir sonraki yükseltme her hook'u sessizce kırar ([#508](https://github.com/rohitg00/agentmemory/issues/508)).
+
+Geçici çözüm:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Bu, aynı hook komutlarını `~/.claude/settings.json` içine, kurulu `@agentmemory/agentmemory` paketinin paketli `plugin/` dizinine çözülmüş mutlak yollarla birleştirir. agentmemory'yi yükselttikten sonra yolları yenilemek için komutu yeniden çalıştırın. Aynı dosyadaki kullanıcı girdileri korunur; yalnızca önceki agentmemory girdileri değiştirilir. `/plugin install` yolunu kullanmak hâlâ önerilen yaklaşımdır.
+Uzak veya korumalı deployment'lar için Claude Code'u `AGENTMEMORY_URL` ve `AGENTMEMORY_SECRET` ayarlanmış olarak başlatın. Eklenti her iki değeri de paketli MCP sunucusuna geçirir; `AGENTMEMORY_URL` boş olduğunda MCP shim'i `http://localhost:3111`'i kullanır.
+
+### Codex CLI (Codex eklenti platformu)
+
+```bash
+# 1. ayrı bir terminalde bellek sunucusunu başlatın
+npx @agentmemory/agentmemory
+
+# 2. agentmemory marketplace'i kaydedin ve eklentiyi kurun
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex eklentisi, Claude Code eklentisiyle aynı `plugin/` dizininden gelir. Şunları kaydeder:
+
+- `@agentmemory/mcp` MCP sunucusu olarak (`AGENTMEMORY_URL` çalışan bir agentmemory sunucusuna işaret ettiğinde tüm 51 tool'u proxy yapar; erişilebilir sunucu yoksa yerel olarak 7 tool'a düşer)
+- 6 yaşam döngüsü hook'u: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 skill: `/recall`, `/remember`, `/session-history`, `/forget`
+
+Codex'in hook motoru, hook alt süreçlerine `CLAUDE_PLUGIN_ROOT` enjekte eder (bkz. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), bu sayede aynı hook scriptleri her iki host'ta da çoğaltma yapmadan çalışır. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure olayları yalnızca Claude Code'a özeldir ve Codex için kaydedilmez.
+
+#### Codex Desktop: eklenti hook'ları şu anda sessiz (geçici çözüm mevcut)
+
+`CodexHooks` ve `PluginHooks` her ikisi de [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs) içinde stable + varsayılan olarak etkin, ancak Codex Desktop sürümleri şu anda eklenti-yerel `hooks.json`'u dağıtmıyor ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). MCP tool'ları hâlâ çalışıyor; yalnızca yaşam döngüsü gözlemleri eksik.
+
+Düzeltme upstream'e iner inmez, aynı hook komutlarını global `~/.codex/hooks.json` içine yansıtın:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+Bu, `~/.codex/hooks.json`'a paketli scriptlere mutlak yollarla atıfta bulunan idempotent bir blok ekler (user-scope'ta `${CLAUDE_PLUGIN_ROOT}` genişlemesi gerekmez). agentmemory'yi yükselttikten sonra yolları yenilemek için aynı komutu yeniden çalıştırın. Aynı dosyadaki kullanıcı girdileri korunur; yalnızca önceki agentmemory girdileri değiştirilir.
+
+<details>
+<summary><b>OpenClaw (bu istemi yapıştırın)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+Tam kılavuz: [`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent (bu istemi yapıştırın)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Tam kılavuz: [`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### Diğer ajanlar
+
+Bellek sunucusunu başlatın: `npx @agentmemory/agentmemory`
+
+agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw) **aynı MCP sunucu bloğudur**:
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**Bu girdiyi host'un yapılandırma dosyasındaki mevcut `mcpServers` nesnesine birleştirin** — dosyayı değiştirmeyin. Dosyada zaten başka sunucular varsa, `agentmemory`'yi `mcpServers` içindeki başka bir anahtar olarak yanlarına ekleyin. `mcpServers` tamamen eksikse, bloğu `{ "mcpServers": { ... } }` içine yapıştırın. `${VAR}` yer tutucuları, MCP-sunucu lansmanında shell'den `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`'i miras alır — ayarsız değişkenler boş string geçirir ve shim `http://localhost:3111`'e geri döner. Bir tane bağlı girdi hem yerel hem uzak (k8s / reverse-proxy'li) dağıtımları kapsar.
+
+| Ajan | Yapılandırma dosyası | Notlar |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | `mcpServers` içine birleştirin. Web sitesinde tek tıklamayla deeplink de mevcut. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers` içine birleştirin. Düzenlemeden sonra Claude Desktop'ı yeniden başlatın. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP ayarları (Settings UI → MCP Servers → Edit) | Aynı `mcpServers` bloğu. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Aynı `mcpServers` bloğu. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (otomatik birleştirir). |
+| **OpenClaw** | OpenClaw MCP yapılandırması | Aynı `mcpServers` bloğu veya daha derin [bellek eklentisi](../integrations/openclaw/) kullanın. |
+| **Codex CLI (yalnız MCP)** | `.codex/config.toml` | TOML şekli: `codex mcp add agentmemory -- npx -y @agentmemory/mcp` veya manuel olarak `[mcp_servers.agentmemory]` ekleyin. |
+| **Codex CLI (tam eklenti)** | Codex eklenti marketplace | `codex plugin marketplace add rohitg00/agentmemory` ardından `codex plugin add agentmemory@agentmemory`. MCP + 6 yaşam döngüsü hook'u (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skill kaydeder. Codex Desktop'ta, [openai/codex#16430](https://github.com/openai/codex/issues/16430) inene kadar `agentmemory connect codex --with-hooks` da çalıştırın — eklenti hook'ları şu anda orada sessiz. |
+| **OpenCode (yalnız MCP)** | `opencode.json` | Farklı şekil — üst seviye `mcp` anahtarı, komut dizi olarak: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (tam eklenti)** | `plugin/opencode/` | Oturum yaşam döngüsü, mesajlar, araçlar, hataları kapsayan 22 otomatik yakalama hook'u. İki slash komut (`/recall`, `/remember`). `plugin/opencode/`'u OpenCode çalışma alanınıza kopyalayın ve eklenti girdisini `opencode.json`'a ekleyin. Tam hook tablosu + gap analizi için [`plugin/opencode/README.md`](../plugin/opencode/README.md) bakın. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | [`integrations/pi`](../integrations/pi/)'yi kopyalayın ve pi'yi yeniden başlatın. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Daha derin [bellek sağlayıcı eklentisi](../integrations/hermes/)'ni `memory.provider: agentmemory` ile kullanın. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` standart `mcpServers` bloğunu yazar. Hook yükü Claude Code ile alan-uyumludur, bu yüzden mevcut 12 hook scripti değişiklik yapmadan çalışır — aynı `settings.json`'daki `hooks` bölümü üzerinden bağlayın. |
+| **Antigravity** (Gemini CLI'nin yerini alır) | `mcp_config.json` (Antigravity'nin User dizininde) | `agentmemory connect antigravity` standart `mcpServers` bloğunu yazar. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. 2026-06-18 Gemini CLI sonlandırılması sonrasında kullanın. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` kullanıcı-seviyesi yapılandırmayı yazar. Çalışma alanı override'ları kodunuzun yanındaki `.kiro/settings/mcp.json`'a gider. |
+| **Goose** | Goose MCP ayarları UI | Aynı `mcpServers` bloğu. |
+| **Aider** | n/a | REST API ile doğrudan konuşun: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Herhangi bir ajan (32+)** | n/a | `npx skillkit install agentmemory` host'u otomatik algılar ve birleştirir. |
+
+**Sandbox'lı MCP istemcileri** (Flatpak / Snap / kısıtlayıcı container'lar) host'un `localhost`'una erişemez: ayrıca `env` bloğunda `"AGENTMEMORY_FORCE_PROXY": "1"` ayarlayın ve `AGENTMEMORY_URL`'i sandbox'ın gerçekten erişebileceği bir rotaya yönlendirin (örn. LAN IP'niz). Teşhis adım adımı için bkz. [#234](https://github.com/rohitg00/agentmemory/issues/234).
+
+### Programatik erişim (Python / Rust / Node)
+
+agentmemory çekirdek işlemlerini iii fonksiyonları olarak kaydeder (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). iii SDK'sı olan herhangi bir dil, bunları doğrudan `ws://localhost:49134` üzerinden çağırabilir — dil başına ayrı bir REST istemcisi yok.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Çalışan örnek: [`examples/python/`](../examples/python/) (quickstart + gözlem/recall akışı). iii runtime'ı olmayan host'lar için REST `:3111` üzerinde kullanılmaya devam eder.
+
+### Kaynaktan
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Bu, `iii` zaten kuruluysa yerel bir `iii-engine` ile agentmemory'yi başlatır veya Docker mevcutsa Docker Compose'a düşer. REST, stream'ler ve görüntüleyici varsayılan olarak `127.0.0.1`'e bağlanır.
+
+`iii-engine`'i manuel olarak kurun. **agentmemory şu anda `iii-engine`'i `v0.11.2`'ye sabitliyor** — `v0.11.6`, agentmemory'nin henüz refactor edilmediği yeni bir sandbox-her-şey-üzerinden-`iii worker add` modelini tanıtıyor. Refactor geldiğinde sabitleme kaldırılır. Sandbox modeline manuel olarak geçtiyseniz `AGENTMEMORY_III_VERSION=<version>` ile override edin.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `aarch64-apple-darwin`'i `x86_64-apple-darwin` ile değiştirin
+- **Linux x64:** `x86_64-unknown-linux-gnu` ile değiştirin
+- **Linux arm64:** `aarch64-unknown-linux-gnu` ile değiştirin
+- **Windows:** [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2)'den `iii-x86_64-pc-windows-msvc.zip`'i indirin, `iii.exe`'yi çıkarın, PATH'e ekleyin
+
+Veya Docker kullanın (paketli `docker-compose.yml` `iiidev/iii:0.11.2`'yi çeker). Tam dokümanlar: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory Windows 10/11'de çalışır, ancak yalnızca Node.js paketi yeterli değildir — arka planda çalışan bir süreç olarak `iii-engine` runtime'ı (ayrı yerel ikilik) da gerekir. Resmi upstream kurucu bir `sh` scripti ve bugün için PowerShell kurucusu veya scoop/winget paketi yok, bu yüzden Windows kullanıcılarının iki yolu var:
+
+**Seçenek A — Önceden derlenmiş Windows ikiliği (önerilen):**
+
+```powershell
+# 1. Tarayıcınızda https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 açın
+#    (engine v0.11.6+'nın gerektirdiği yeni sandbox modeli için
+#     agentmemory refactor edilene kadar v0.11.2'ye sabitliyoruz)
+# 2. iii-x86_64-pc-windows-msvc.zip indirin
+#    (veya ARM makinedeyseniz iii-aarch64-pc-windows-msvc.zip)
+# 3. iii.exe'yi PATH'te bir yere çıkarın veya şuraya yerleştirin:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory bu konumu otomatik kontrol eder)
+# 4. Doğrulayın:
+iii --version
+# Şunu yazmalı: 0.11.2
+
+# 5. Ardından agentmemory'yi her zamanki gibi çalıştırın:
+npx -y @agentmemory/agentmemory
+```
+
+**Seçenek B — Docker Desktop:**
+
+```powershell
+# 1. Windows için Docker Desktop kurun
+# 2. Docker Desktop'ı başlatın ve engine'in çalıştığından emin olun
+# 3. agentmemory'yi çalıştırın — paketli compose dosyasını otomatik başlatır:
+npx -y @agentmemory/agentmemory
+```
+
+**Seçenek C — yalnızca bağımsız MCP (engine yok):** yalnızca ajanınız için MCP araçlarına ihtiyacınız varsa ve REST API'sine, görüntüleyiciye veya cron işlerine gerek yoksa engine'i tamamen atlayın:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# veya shim paketi üzerinden:
+npx -y @agentmemory/mcp
+```
+
+**Windows için teşhis:** `npx @agentmemory/agentmemory` başarısız olursa, gerçek engine stderr'ini görmek için `--verbose` ile yeniden çalıştırın. Yaygın hata türleri:
+
+| Belirti | Düzeltme |
+|---|---|
+| `iii-engine process started` ardından `did not become ready within 15s` | Engine başlatma sırasında çöktü — `--verbose` ile yeniden çalıştırın, stderr'i kontrol edin |
+| `Could not start iii-engine` | Ne `iii.exe` ne de Docker kurulu. Yukarıdaki Seçenek A veya B'ye bakın |
+| Port çakışması | `netstat -ano \| findstr :3111` ile neyin bağlı olduğunu görün, ardından öldürün veya `--port <N>` kullanın |
+| Docker kurulu olsa bile Docker fallback atlanıyor | Docker Desktop'ın gerçekten çalıştığından emin olun (sistem tepsisi simgesi) |
+
+> Not: `cargo install iii-engine` yoktur — `iii` crates.io'da yayımlanmamıştır. Tek desteklenen kurulum yöntemleri yukarıdaki önceden derlenmiş ikilik, upstream `sh` kurulum scripti (yalnızca macOS/Linux) ve Docker imajıdır.
+
+---
+
+<h2 id="deploy">Deploy</h2>
+
+Yönetilen host'lar için tek tıklamayla şablonlar. Her biri,
+npm'den `@agentmemory/agentmemory`'yi çeken ve iii engine
+ikilisini resmi `iiidev/iii` Docker Hub imajından kopyalayan
+kendi kendine yeten bir Dockerfile içerir — önceden derlenmiş
+bir agentmemory imajı gerekmez. Kalıcı depolama `/data`'ya
+bağlanır; ilk açılış entrypoint'i, npm-paketli iii yapılandırmasını
+(ki `127.0.0.1`'e bağlanır) `0.0.0.0`'a bağlanan ve mutlak
+`/data` yollarını kullanan deploy-ayarlı bir tanesiyle üzerine
+yazar, HMAC secret'ını üretir, ardından agentmemory CLI'sini
+exec etmeden önce `gosu` aracılığıyla yetkileri `root`'tan
+`node`'a düşürür.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render'ın tek-tıklamayla deploy düğmesi, depo kökünde `render.yaml`
+gerektirir; biz bunu bilerek temiz tutuyoruz. Deponun içindeki blueprint'e
+manuel olarak işaret etmek için [`deploy/render/`](../deploy/render/README.md) içinde belgelenen Render Blueprint akışını kullanın.
+
+Tam kurulum detayları (HMAC yakalama, görüntüleyici SSH tüneli,
+döndürme, yedekleme, maliyet alt sınırları) [`deploy/`](../deploy/README.md) içinde:
+
+- [`deploy/fly`](../deploy/fly/README.md) — `auto_stop_machines = "stop"` ile
+  tek makine; en ucuz boşta çalışma.
+- [`deploy/railway`](../deploy/railway/README.md) — Hobby planı sabit ücret,
+  panelden volume.
+- [`deploy/render`](../deploy/render/README.md) — Blueprint akışı,
+  ücretli planlarda otomatik disk snapshot'ları.
+- [`deploy/coolify`](../deploy/coolify/README.md) — kendi VPS'inizde
+  [Coolify](https://coolify.io/self-hosted) üzerinden self-hosted; aynı
+  Docker Compose stack'i, host ve verinin sahibi sizsiniz.
+
+Yalnızca `3111` portu yayımlanır. `3113`'teki görüntüleyici container içinde
+loopback'e bağlı kalır �� her şablonun README'si ona ulaşmak için SSH-tünel
+desenini belgeler.
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
+
+Her kodlama ajanı, oturum sona erdiğinde her şeyi unutur. Her oturumun ilk 5 dakikasını yığınınızı yeniden anlatarak harcarsınız. agentmemory arka planda çalışır ve bunu tamamen ortadan kaldırır.
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### Yerleşik ajan belleğiyle karşılaştırma
+
+Her AI kodlama ajanı yerleşik bellekle gelir — Claude Code'da `MEMORY.md`, Cursor'da notepad, Cline'da memory bank var. Bunlar yapışkan notlar gibi çalışır. agentmemory, o yapışkan notların ardındaki aranabilir veritabanıdır.
+
+| | Yerleşik (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Ölçek | 200 satır sınırı | Sınırsız |
+| Arama | Her şeyi bağlama yükler | BM25 + vektör + graf (yalnız top-K) |
+| Token maliyeti | 240 gözlemde 22K+ | ~1,900 token (%92 daha az) |
+| Ajanlar arası | Ajan başına dosya | MCP + REST (herhangi bir ajan) |
+| Koordinasyon | Yok | Lease'ler, sinyaller, action'lar, routine'ler |
+| Gözlemlenebilirlik | Dosyaları manuel okuma | :3113'te gerçek zamanlı görüntüleyici |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>
+
+### Bellek Pipeline'ı
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4 Katmanlı Bellek Konsolidasyonu
+
+İnsan beyninin belleği nasıl işlediğinden ilham aldı — uyku konsolidasyonundan çok da farklı değil.
+
+| Katman | Ne | Analoji |
+|------|------|---------|
+| **Working** | Araç kullanımından ham gözlemler | Kısa süreli bellek |
+| **Episodic** | Sıkıştırılmış oturum özetleri | "Ne oldu" |
+| **Semantic** | Çıkarılmış olgular ve desenler | "Ne biliyorum" |
+| **Procedural** | İş akışları ve karar desenleri | "Nasıl yapılır" |
+
+Bellekler zamanla decay olur (Ebbinghaus eğrisi). Sık erişilen bellekler güçlenir. Bayat bellekler otomatik tahliye edilir. Çelişkiler algılanır ve çözülür.
+
+### Ne Yakalanır
+
+| Hook | Yakalar |
+|------|----------|
+| `SessionStart` | Proje yolu, oturum ID |
+| `UserPromptSubmit` | Kullanıcı istemleri (gizlilik-filtrelenmiş) |
+| `PreToolUse` | Dosya erişim desenleri + zenginleştirilmiş bağlam |
+| `PostToolUse` | Tool adı, girdi, çıktı |
+| `PostToolUseFailure` | Hata bağlamı |
+| `PreCompact` | Sıkıştırmadan önce belleği yeniden enjekte eder |
+| `SubagentStart/Stop` | Alt-ajan yaşam döngüsü |
+| `Stop` | Oturum sonu özeti |
+| `SessionEnd` | Oturum tamamlandı işareti |
+
+### Temel Yetenekler
+
+| Yetenek | Açıklama |
+|---|---|
+| **Otomatik yakalama** | Her tool kullanımı hook'lar üzerinden kaydedilir — sıfır manuel çaba |
+| **Anlamsal arama** | RRF füzyonu ile BM25 + vektör + bilgi grafı |
+| **Bellek evrimi** | Sürümleme, supersede, ilişki grafları |
+| **Otomatik unutma** | TTL süresi dolması, çelişki algılama, önem tahliyesi |
+| **Gizlilik öncelikli** | API anahtarları, secret'lar, `<private>` etiketleri depolamadan önce çıkarılır |
+| **Kendini iyileştirme** | Devre kesici, sağlayıcı yedek zinciri, sağlık izleme |
+| **Claude bridge** | MEMORY.md ile çift yönlü sync |
+| **Bilgi grafı** | Entity çıkarımı + BFS gezinti |
+| **Takım belleği** | İsimlendirilmiş paylaşımlı + özel takım üyeleri arasında |
+| **Atıf provenansı** | Herhangi bir belleği kaynak gözlemlere kadar izleyin |
+| **Git snapshot'ları** | Bellek durumunu sürümleyin, geri alın ve diff'leyin |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
+
+Üç sinyali birleştiren üçlü-akış geri getirme:
+
+| Akış | Ne yapar | Ne zaman |
+|---|---|---|
+| **BM25** | Eş anlamlı genişletmeli stem'lenmiş anahtar kelime eşleştirme | Her zaman açık |
+| **Vektör** | Yoğun embedding'ler üzerinde kosinüs benzerliği | Embedding sağlayıcı yapılandırılmış |
+| **Graf** | Entity eşleştirme yoluyla bilgi grafı gezintisi | Sorguda entity'ler tespit edildiğinde |
+
+Reciprocal Rank Fusion (RRF, k=60) ile birleştirilir ve oturum-çeşitlendirilir (oturum başına maksimum 3 sonuç).
+
+BM25, Yunanca, Kiril, İbranice, Arapça ve aksanlı Latin'i kutudan çıkar çıkmaz tokenize eder. Çince / Japonca / Korece bellekler için, CJK akışlarını kelime-seviyesinde token'lara bölmek üzere isteğe bağlı segmenter'ları kurun (`npm install @node-rs/jieba tiny-segmenter`); bunlar olmadan agentmemory yumuşak olarak tüm-akış tokenizasyonuna düşer ve stderr'e bir kerelik bir ipucu yazdırır.
+
+### Embedding sağlayıcıları
+
+agentmemory sağlayıcınızı otomatik algılar. En iyi sonuçlar için yerel embedding'leri kurun (ücretsiz):
+
+```bash
+npm install @xenova/transformers
+```
+
+| Sağlayıcı | Model | Maliyet | Notlar |
+|---|---|---|---|
+| **Yerel (önerilen)** | `all-MiniLM-L6-v2` | Ücretsiz | Çevrim dışı, BM25-only üzerinde +8pp recall |
+| Gemini | `gemini-embedding-001` | Ücretsiz katman | 100+ dil, 768/1536/3072 boyut (MRL), 2048-token girdi. `text-embedding-004`'ün yerini alır ([deprecated, 14 Ocak 2026'da kapanış](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | 1M başı $0.02 | En yüksek kalite |
+| Voyage AI | `voyage-code-3` | Ücretli | Kod için optimize edilmiş |
+| Cohere | `embed-english-v3.0` | Ücretsiz deneme | Genel amaçlı |
+| OpenRouter | Herhangi bir model | Değişken | Çok-modelli proxy |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>
+
+53 tool, 6 kaynak, 3 prompt ve 4 skill — herhangi bir ajan için en kapsamlı MCP bellek toolkit'i.
+
+> **MCP shim vs tam sunucu:** yayımlanan `@agentmemory/mcp` paketi ince bir shim'dir. Tam 51-tool yüzeyini **yalnızca `AGENTMEMORY_URL` üzerinden çalışan bir agentmemory sunucusuna erişebildiğinde** açığa çıkarır (proxy modu). Erişilebilir sunucu yoksa, shim 7-tool yerel sete (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`) düşer. `AGENTMEMORY_TOOLS=core|all` env değişkeni *sunucu tarafı* bir bayraktır — shim'in `env` bloğunda ayarlamak hiçbir etki yapmaz. Cursor / OpenCode / Gemini CLI'da yalnızca 7 tool görüyorsanız, `npx @agentmemory/agentmemory` (veya Docker stack'i) başlatın ve `AGENTMEMORY_URL=http://localhost:3111` ayarlayın.
+
+### 51 Tool
+
+<details>
+<summary>Çekirdek tool'lar (her zaman kullanılabilir)</summary>
+
+| Tool | Açıklama |
+|------|-------------|
+| `memory_recall` | Geçmiş gözlemleri ara |
+| `memory_compress_file` | Yapıyı koruyarak markdown dosyalarını sıkıştır |
+| `memory_save` | Bir içgörü, karar veya deseni kaydet |
+| `memory_patterns` | Tekrar eden desenleri algıla |
+| `memory_smart_search` | Hibrit anlamsal + anahtar kelime araması |
+| `memory_file_history` | Belirli dosyalar hakkında geçmiş gözlemler |
+| `memory_sessions` | Son oturumları listele |
+| `memory_timeline` | Kronolojik gözlemler |
+| `memory_profile` | Proje profili (kavramlar, dosyalar, desenler) |
+| `memory_export` | Tüm bellek verisini dışa aktar |
+| `memory_relations` | İlişki grafını sorgula |
+
+</details>
+
+<details>
+<summary>Genişletilmiş tool'lar (51 toplam — AGENTMEMORY_TOOLS=all ayarla)</summary>
+
+| Tool | Açıklama |
+|------|-------------|
+| `memory_patterns` | Tekrar eden desenleri algıla |
+| `memory_timeline` | Kronolojik gözlemler |
+| `memory_relations` | İlişki grafını sorgula |
+| `memory_graph_query` | Bilgi grafı gezintisi |
+| `memory_consolidate` | 4 katmanlı konsolidasyonu çalıştır |
+| `memory_claude_bridge_sync` | MEMORY.md ile sync |
+| `memory_team_share` | Takım üyeleriyle paylaş |
+| `memory_team_feed` | Son paylaşılan öğeler |
+| `memory_audit` | İşlemlerin denetim izi |
+| `memory_governance_delete` | Denetim izi ile sil |
+| `memory_snapshot_create` | Git-sürümlü snapshot |
+| `memory_action_create` | Bağımlılıklarla iş öğesi oluştur |
+| `memory_action_update` | Action durumunu güncelle |
+| `memory_frontier` | Önceliğe göre sıralanmış engellenmemiş action'lar |
+| `memory_next` | Tek en önemli sonraki action |
+| `memory_lease` | Exclusive action lease'leri (çoklu ajan) |
+| `memory_routine_run` | İş akışı routine'lerini örnekle |
+| `memory_signal_send` | Ajanlar arası mesajlaşma |
+| `memory_signal_read` | Onay alındıyla mesajları oku |
+| `memory_checkpoint` | Harici koşul kapıları |
+| `memory_mesh_sync` | Örnekler arasında P2P sync |
+| `memory_sentinel_create` | Event-driven gözcüler |
+| `memory_sentinel_trigger` | Sentinel'leri harici olarak tetikle |
+| `memory_sketch_create` | Ephemeral action grafları |
+| `memory_sketch_promote` | Kalıcıya yükselt |
+| `memory_crystallize` | Action zincirlerini kompakt et |
+| `memory_diagnose` | Sağlık kontrolleri |
+| `memory_heal` | Sıkışmış durumu otomatik düzelt |
+| `memory_facet_tag` | Boyut:değer etiketleri |
+| `memory_facet_query` | Facet etiketlerine göre sorgula |
+| `memory_verify` | Provenansı izle |
+
+</details>
+
+### 6 Kaynak · 3 Prompt · 4 Skill
+
+| Tür | İsim | Açıklama |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Sağlık, oturum sayısı, bellek sayısı |
+| Resource | `agentmemory://project/{name}/profile` | Proje başına zeka |
+| Resource | `agentmemory://memories/latest` | En son 10 aktif bellek |
+| Resource | `agentmemory://graph/stats` | Bilgi grafı istatistikleri |
+| Prompt | `recall_context` | Ara + bağlam mesajları döndür |
+| Prompt | `session_handoff` | Ajanlar arasında handoff verisi |
+| Prompt | `detect_patterns` | Tekrar eden desenleri analiz et |
+| Skill | `/recall` | Belleği ara |
+| Skill | `/remember` | Uzun süreli belleğe kaydet |
+| Skill | `/session-history` | Son oturum özetleri |
+| Skill | `/forget` | Gözlemleri/oturumları sil |
+
+### Bağımsız MCP
+
+Tam sunucu olmadan çalıştır — herhangi bir MCP istemcisi için. Şunlardan herhangi biri çalışır:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # kanonik (her zaman kullanılabilir)
+npx -y @agentmemory/mcp                # shim paketi takma adı
+```
+
+Veya ajanınızın MCP yapılandırmasına ekleyin:
+
+Çoğu ajan (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+`agentmemory` girdisini, dosyayı değiştirmek yerine host'unuzun mevcut `mcpServers` nesnesine birleştirin. Host'un `localhost`'una erişemeyen sandbox'lı istemciler için env bloğuna `"AGENTMEMORY_FORCE_PROXY": "1"` ekleyin ve `AGENTMEMORY_URL`'i sandbox'ın erişebileceği bir rotaya ayarlayın.
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Eklenti dosyasını depodan kopyalayın:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
+
+`3113` portunda otomatik başlar. Canlı gözlem akışı, oturum gezgini, bellek tarayıcısı, bilgi grafı görselleştirmesi ve sağlık paneli.
+
+```bash
+open http://localhost:3113
+```
+
+Görüntüleyici sunucusu varsayılan olarak `127.0.0.1`'e bağlanır. REST-servisli `/agentmemory/viewer` endpoint'i normal `AGENTMEMORY_SECRET` bearer-token kurallarını izler. CSP başlıkları yanıt başına bir script nonce'ı kullanır ve satır içi handler özniteliklerini devre dışı bırakır (`script-src-attr 'none'`).
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+`:3113`'teki görüntüleyici ajanınızın **hatırladıklarını** gösterir. [iii konsolu](https://iii.dev/docs/console) ajanınızın **yaptıklarını** gösterir — her bellek op'u bir OpenTelemetry trace'i olarak, her KV girdisi düzenlenebilir, her fonksiyon çağrılabilir, her stream dinlenebilir. Aynı belleğe iki pencere: biri ürün-şekilli, diğeri motor-şekilli.
+
+Bir `memory_smart_search`'ün ateşlenmesini izleyin ve BM25 taramasını → embedding aramasını → RRF füzyonunu → reranker'ı bir şelale olarak görün. Sıkışmış bir konsolidasyon zamanlayıcısını KV tarayıcıda düzenleyin. `PostToolUse` hook'unu değiştirilmiş bir payload ile tekrar oynatın. WebSocket stream'ini sabitleyin ve gözlemlerin canlı olarak indiğini izleyin.
+
+agentmemory bunu ücretsiz dağıtır çünkü her fonksiyon, trigger, durum kapsamı ve stream bir iii primitif'idir — özel hiçbir şey, enstrümante edilecek hiçbir şey yok.
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
+  <br/>
+  <em>Workers sayfası: bağlı her worker — agentmemory'nin kendisi dahil — PID, fonksiyon sayısı, runtime ve son-görülme ile birlikte.</em>
+</p>
+
+**Zaten kurulu.** Konsol `iii` ile birlikte gelir — ayrı kurucu yok.
+
+**agentmemory ile birlikte başlat:**
+
+```bash
+# agentmemory görüntüleyicisi 3113 portunu tutar, bu yüzden konsolu 3114'te çalıştırın.
+# Engine REST (3111), WebSocket (3112) ve bridge (49134) varsayılanları agentmemory ile eşleşir.
+iii console --port 3114
+```
+
+Ardından `http://localhost:3114`'ü açın. Deneysel mimari-grafı sayfası için `--enable-flow` ekleyin.
+
+Yalnızca taşıdıysanız engine endpoint'lerini override edin:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**Konsoldan neler yapabilirsiniz:**
+
+| Sayfa | Şunun için kullanın |
+|------|-----------|
+| **Workers** | Bağlı her worker'ı ve canlı metriklerini görün — agentmemory worker'ının kendisi dahil. |
+| **Functions** | agentmemory'nin herhangi bir fonksiyonunu doğrudan JSON payload ile çağırın — bir istemci bağlamadan `memory.recall`, `memory.consolidate`, `graph.query` test etmek için kullanışlı. |
+| **Triggers** | HTTP, cron, event ve state trigger'larını tekrar oynatın — konsolidasyon cron'unu manuel olarak ateşleyin, bir HTTP route'unu yeniden deneyin, bir durum değişikliği yayın. |
+| **States** | Tam CRUD ile KV tarayıcı — oturumlar, bellek slot'ları, yaşam döngüsü zamanlayıcıları, embedding'ler indeksi — değerleri yerinde düzenleyin. |
+| **Streams** | Bellek yazımları, hook olayları ve gözlem güncellemeleri için iii stream'leri üzerinden akarken canlı WebSocket monitörü. |
+| **Queues** | Dayanıklı kuyruk konuları + dead-letter yönetimi. Başarısız embedding / sıkıştırma işlerini tekrar oynatın veya bırakın. |
+| **Traces** | OpenTelemetry şelale / alev / hizmet-dağılımı görünümleri. `trace_id` ile filtreleyerek tek bir `memory.search`'ün hangi fonksiyonları, DB çağrılarını ve embedding isteklerini ürettiğini tam olarak görün. |
+| **Logs** | Trace/span ID'lerine korelasyonlu, yapılandırılmış OTEL logları. |
+| **Config** | Runtime yapılandırması — engine'inizin hangi worker'lar, sağlayıcılar ve portlarla çalıştığını tam olarak görün. |
+| **Flow** | (İsteğe bağlı, `--enable-flow`) Her worker, trigger ve stream'in interaktif mimari grafı. |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
+  <br/>
+  <em>Traces: her bellek işlemi için şelale / alev / hizmet dağılımı.</em>
+</p>
+
+**Trace'ler zaten açık:**
+
+`iii-config.yaml` `iii-observability` worker'ı etkinleştirilmiş olarak gelir (`exporter: memory`, `sampling_ratio: 1.0`, metrikler + log'lar). Ekstra yapılandırma gerekmez — agentmemory başlar başlamaz, her bellek işlemi konsolun okuyabileceği bir trace span'ı ve yapılandırılmış bir log yayar.
+
+Bunun yerine Jaeger/Honeycomb/Grafana Tempo'ya dışa aktarmak isterseniz, `exporter: memory`'yi `exporter: otlp` olarak değiştirin ve collector endpoint'ini iii'nin observability dokümanlarına göre ayarlayın.
+
+> **Dikkat:** konsolun kendisinde hiçbir auth zorlanmaz — `127.0.0.1`'e bağlı tutun (varsayılan) ve asla genel kullanıma açmayın.
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory **zaten çalışan bir [iii](https://iii.dev) örneğidir**. Fonksiyonlar, trigger'lar, KV state, stream'ler, OTEL trace'leri — hepsi iii primitifleridir. Postgres, Redis, Express, pm2 veya Prometheus kurmadınız çünkü iii bunların yerini alıyor.
+
+Bu da, tek bir komutun agentmemory'yi tamamen yeni bir yetenekle genişlettiği anlamına gelir.
+
+### agentmemory'yi tek komutla genişletin
+
+```bash
+iii worker add iii-pubsub          # bellek yazımlarını bağlı her örneğe fan-out et
+iii worker add iii-cron            # zamanlanmış konsolidasyon, decay süpürmeleri, snapshot rotasyonu
+iii worker add iii-queue           # embedding + sıkıştırma işleri için dayanıklı yeniden denemeler
+iii worker add iii-observability   # her bellek op'unda OTEL trace'leri (varsayılan açık)
+iii worker add iii-sandbox         # hatırlanan kodu izole bir microVM içinde çalıştır
+iii worker add iii-database        # SQL destekli bir state adaptörü tak
+iii worker add mcp                 # agentmemory MCP'sinin yanında genel MCP host'u
+```
+
+Her `iii worker add` agentmemory'nin zaten çalıştığı aynı engine'e yeni fonksiyonlar ve trigger'lar kaydeder. Görüntüleyici ve konsol bunları anında alır — yeniden yükleme yok, yeni entegrasyon yok, yeni container yok.
+
+| `iii worker add` | agentmemory'nin üzerine ne elde edersiniz |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Çoklu-örnek bellek: her `remember` fan-out olur, her `search` birleşimi okur |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Zamanlanmış yaşam döngüsü — geceleri konsolidasyon, haftalık snapshot'lar, sabit bir saatte decay |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Dayanıklı yeniden denemeler: başarısız embedding + sıkıştırma işleri yeniden başlatmaya dayanır, kayıp gözlem yok |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL trace'leri, metrikleri, log'ları her fonksiyonda — birinci günden itibaren `iii-config.yaml`'da bağlı |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`'dan çıkan kod, shell'inizde değil, bir kullan-at VM içinde çalışır |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | In-memory KV varsayılanlarını aştığınızda SQL destekli state adaptörü |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory'ninin yanında ekstra MCP sunucuları ayağa kaldırın, aynı engine'i paylaşın |
+
+Tam kayıt defteri: [workers.iii.dev](https://workers.iii.dev). Oradaki her worker, agentmemory'nin kullandığı aynı primitifler aracılığıyla bir araya gelir — ve elinizde olan agentmemory de onlardan biridir.
+
+### iii'nin yerini aldığı şeyler
+
+| Geleneksel stack | agentmemory kullanır |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + in-memory vektör indeksi |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker süpervizyonu |
+| Prometheus / Grafana | iii OTEL + sağlık monitörü |
+| Özel eklenti sistemleri | `iii worker add <name>` |
+
+**118 kaynak dosya · ~21,800 LOC · 950+ test · 123 fonksiyon · 34 KV scope** — hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi iii'nin kendisi.
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### LLM Sağlayıcıları
+
+agentmemory ortamınızdan otomatik algılar. Varsayılan olarak, bir sağlayıcı yapılandırmadıkça veya Claude abonelik fallback'ine açıkça opt-in yapmadıkça hiçbir LLM çağrısı yapılmaz.
+
+| Sağlayıcı | Yapılandırma | Notlar |
+|----------|--------|-------|
+| **No-op (varsayılan)** | Yapılandırma gerekmez | LLM destekli compress/summarize DEVRE DIŞI. Sentetik BM25 sıkıştırma + recall hâlâ çalışır. Eskiden Claude-abonelik fallback'ine dayanıyorsanız aşağıdaki `AGENTMEMORY_ALLOW_AGENT_SDK`'ya bakın. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Token başına faturalama |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-uyumlu |
+| Gemini | `GEMINI_API_KEY` | Embedding'leri de etkinleştirir |
+| OpenRouter | `OPENROUTER_API_KEY` | Herhangi bir model |
+| Claude abonelik fallback'i | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Yalnızca opt-in. `@anthropic-ai/claude-agent-sdk` oturumları doğurur — eskiden sınırsız Stop-hook recursion'ına neden oluyordu (#149 takip), bu yüzden artık varsayılan değil. |
+
+### Maliyet bilincine sahip model seçimi
+
+Arka plan sıkıştırması her gözlemde çalışır, bu yüzden model seçimi aylık harcamayı anlamlı ölçüde değiştirir. Yakalanan iş yükü verisi: 635 istek / 888K token / 35 saatlik aktif kullanım, 2026-05-23 fiyatlandırmasında üç OpenRouter modeline karşı çalıştırıldı.
+
+| Katman | Model | Girdi / 1M | Çıktı / 1M | Yakalanan 35 saat maliyeti | Notlar |
+|------|-------|------------|-------------|---------------------------|-------|
+| Önerilen | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet'ten ~10× daha düşük maliyetle sağlam sıkıştırma + özetleme kalitesi. |
+| Önerilen | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | Daha eski ama yalnızca-sıkıştırma iş yükleri için hâlâ iyi. |
+| Önerilen | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Oturumlarınız yoğun olarak kod-şekilli ise güçlü kod muhakemesi. |
+| Premium | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | Yüksek kalite ancak her zaman açık arka plan çalışması için pahalı. |
+| Premium | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | Sonnet ile benzer katman. |
+| Kaçının | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | Reasoning sınıfı model; sıkıştırma için büyük aşırı harcama. |
+
+`OPENROUTER_MODEL` premium-katman bir desenle eşleştiğinde agentmemory bir runtime uyarısı yazdırır. Bilinçli bir seçim yaptıktan sonra susturmak için `AGENTMEMORY_SUPPRESS_COST_WARNING=1` ayarlayın.
+
+Bellek işi için kalite vs maliyet ödünleşmesi: sıkıştırma görece gevşek kalite çıtaları olan bir özetleme görevidir (özeti tekrar okuyan kullanıcı değil, ajandır). DeepSeek-V4-Pro / Qwen3-Coder bu görevde Sonnet'in yuvarlama hatası içinde kalırken ~10× daha az maliyetlidir. Premium katman modelleri doğrudan okuduğunuz sorgular için saklayın.
+
+Kaynaklar: [Sonnet 4.6 için OpenRouter fiyatlandırması](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing), [DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro), [DeepSeek fiyatlandırma notları](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Çoklu-ajan belleği (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Birden fazla rolün tek bir agentmemory sunucusunu paylaştığı çoklu-ajan kurulumlarında (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` her yazıyı onu yapan rolle etiketler. `AGENTMEMORY_AGENT_SCOPE` recall'un bu etikete göre filtreleyip filtrelemeyeceğini kontrol eder.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # isteğe bağlı; varsayılan "shared"
+```
+
+İki mod:
+
+| Mod | Yazıları etiketle | Recall'u filtrele | Ne zaman kullanılır |
+|------|------------|---------------|-------------|
+| `shared` (varsayılan) | evet | hayır | Denetim iziyle ajanlar arası bağlam. Architect, developer'ın notlarını görebilir ancak her satır kim söylediğini kaydeder. |
+| `isolated` | evet | evet | Katı ayrım. Architect developer'ın gözlemlerini / belleklerini / oturumlarını asla görmez. |
+
+`AGENT_ID` ayarlandığında ne etiketlenir: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rol `api::session::start` → `mem::observe` → `mem::compress` → KV boyunca akar.
+
+İzole modda ne filtrelenir: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Her endpoint istek başına override için `?agentId=<role>` ve env kapsamından opt-out etmek için `?agentId=*` kabul eder. `/memories` ayrıca `agentId`'si undefined olan AGENT_ID öncesi belleklerin yüzeylenmesi için `?includeOrphans=true` kabul eder.
+
+SDK / REST katmanında çağrı başına override: her mutasyon endpoint'i (`/session/start`, `/remember`) istek gövdesinde env'i geçen bir `agentId` alanı kabul eder. Tek bir sunucu sürecinden birçok rolü yönlendiren runtime'lar için kullanışlıdır.
+
+`AGENT_ID` ayarlanmadığında bellek kapsam dışı kalır (eski davranış, etiket yok, filtre yok).
+
+### Portlar
+
+agentmemory + iii-engine varsayılan olarak dört port'a bağlanır. Bir yeniden başlatma `port in use` ile başarısız olursa, bu tablo hangi süreci aramanız gerektiğini söyler.
+
+| Port | Süreç | Amaç | Env override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Dahili stream'ler worker'ı (agentmemory + görüntüleyici tarafından tüketilir) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | Gerçek zamanlı görüntüleyici (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — worker'lar burada kaydolur, OTel telemetri buradan akar | `III_ENGINE_URL` (tam URL, varsayılan `ws://localhost:49134`) |
+
+Çöken bir çalıştırma sonrası portlar bağlı kaldığında bayat-süreç temizliği:
+
+```bash
+# macOS / Linux — her portta ne varsa bulun ve öldürün
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` graceful shutdown'da hem worker hem de engine pidfile'ını temiz olarak biçer (#640, #474). Yukarıdaki manuel temizlik yalnızca her iki pidfile'ın da geride kalmadığı çökme sonrası durum içindir.
+
+### Yapılandırma Dosyası
+
+agentmemory runtime yapılandırmasını her shell'de değişkenleri export etmek yerine `~/.agentmemory/.env`'a koyun. Görüntüleyici `export ANTHROPIC_API_KEY=...` gibi bir kurulum ipucu gösteriyorsa, `export` ön ekini koymadan bu dosyaya `ANTHROPIC_API_KEY=...` olarak kopyalayın, ardından agentmemory'yi yeniden başlatın.
+
+Süreç ortam değişkenleri hâlâ çalışır ve dosyadaki değerlere göre öncelik kazanır.
+
+Windows'ta aynı dosya `%USERPROFILE%\.agentmemory\.env` konumunda bulunur:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+API anahtarı yerine Claude Code Pro/Max aboneliğiyle test etmek için açıkça opt-in yapın:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Graph veya konsolidasyon özelliklerini istiyorsanız aynı dosyada açın:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### Ortam Değişkenleri
+
+`~/.agentmemory/.env` oluşturun:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+`3111` portunda 124 endpoint. REST API varsayılan olarak `127.0.0.1`'e bağlanır. `AGENTMEMORY_SECRET` ayarlandığında korumalı endpoint'ler `Authorization: Bearer <secret>` gerektirir ve mesh sync endpoint'leri her iki eşte de `AGENTMEMORY_SECRET` gerektirir.
+
+<details>
+<summary>Önemli endpoint'ler</summary>
+
+| Method | Path | Açıklama |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Sağlık kontrolü (her zaman public) |
+| `POST` | `/agentmemory/session/start` | Oturum başlat + bağlam al |
+| `POST` | `/agentmemory/session/end` | Oturumu bitir |
+| `POST` | `/agentmemory/observe` | Gözlem yakala |
+| `POST` | `/agentmemory/smart-search` | Hibrit arama |
+| `POST` | `/agentmemory/context` | Bağlam üret |
+| `POST` | `/agentmemory/remember` | Uzun süreli belleğe kaydet |
+| `POST` | `/agentmemory/forget` | Gözlemleri sil |
+| `POST` | `/agentmemory/enrich` | Dosya bağlamı + bellekler + bug'lar |
+| `GET` | `/agentmemory/profile` | Proje profili |
+| `GET` | `/agentmemory/export` | Tüm veriyi dışa aktar |
+| `POST` | `/agentmemory/import` | JSON'dan içeri aktar |
+| `POST` | `/agentmemory/graph/query` | Bilgi grafı sorgusu |
+| `POST` | `/agentmemory/team/share` | Takımla paylaş |
+| `GET` | `/agentmemory/audit` | Denetim izi |
+
+Tam endpoint listesi: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
+
+```bash
+npm run dev               # Hot reload
+npm run build             # Production build
+npm test                  # 950+ test
+npm run test:integration  # API testleri (çalışan servisler gerektirir)
+```
+
+**Ön koşullar:** Node.js >= 20, [iii-engine](https://iii.dev/docs) veya Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.zh-CN.md

@@ -0,0 +1,1378 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — 为 AI 编码代理提供持久化记忆" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    让你的编码代理记住一切。不再重复解释。
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  为 Claude Code、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 以及任何 MCP 客户端提供持久化记忆。
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  简体中文 |
+  <a href="README.zh-TW.md">繁體中文</a> |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1200 stars / 172 forks on the gist" /></a>
+</p>
+
+<p align="center">
+  <em>这份 gist 以置信度评分、生命周期管理、知识图谱和混合搜索扩展了 Karpathy 的 LLM Wiki 模式:agentmemory 就是其实现。</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">安装</a> &bull;
+  <a href="#quick-start">快速开始</a> &bull;
+  <a href="#benchmarks">基准测试</a> &bull;
+  <a href="#vs-competitors">对比竞品</a> &bull;
+  <a href="#works-with-every-agent">代理</a> &bull;
+  <a href="#how-it-works">工作原理</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">查看器</a> &bull;
+  <a href="#iii-console">iii 控制台</a> &bull;
+  <a href="#powered-by-iii">由 iii 驱动</a> &bull;
+  <a href="#configuration">配置</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## 安装
+
+```bash
+npm install -g @agentmemory/agentmemory          # 一次安装 — 全局可用 `agentmemory` 命令
+# 如果在 macOS/Linux 的系统 Node 上遇到 EACCES,请重试:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # 在 :3111 启动记忆服务器
+agentmemory demo                                 # 注入示例会话并验证召回
+agentmemory connect claude-code                  # 连接你的代理(也支持: codex, cursor, gemini-cli, ...)
+```
+
+或通过 `npx`(无需安装):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+提醒 — npx 会按版本缓存。如果裸 `npx @agentmemory/agentmemory` 命令运行的是旧版本,强制使用最新版 `npx -y @agentmemory/agentmemory@latest`,或一次性清除缓存 `rm -rf ~/.npm/_npx`(macOS/Linux;Windows 上删除 `%LOCALAPPDATA%\npm-cache\_npx`)。从 v0.9.16+ 起,首次 npx 运行会内联提示你全局安装,这样之后裸 `agentmemory` 命令在任何地方都能用。
+
+完整选项见下方[快速开始](#quick-start)。各代理具体接入见[支持所有代理](#works-with-every-agent)。
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
+
+agentmemory 兼容任何支持 hooks、MCP 或 REST API 的代理。所有代理共享同一个记忆服务器。
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>原生插件 + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>原生插件 + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>原生插件 + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>原生插件 + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>原生插件 + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>原生 Memory trait 后端</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + 插件</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP 服务器</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>兼容<strong>任何</strong>使用 MCP 或 HTTP 的代理。一个服务器,所有代理共享记忆。</sub>
+</p>
+
+---
+
+你每次会话都在重复解释同样的架构。你反复发现同样的 bug。你重复教同样的偏好。内建的记忆(CLAUDE.md、.cursorrules)上限是 200 行而且会过时。agentmemory 解决了这个问题。它在后台静默捕获代理的行为,将其压缩为可搜索的记忆,并在下次会话开始时注入正确的上下文。一条命令。跨代理工作。
+
+**改变了什么:** 会话 1 你设置了 JWT 鉴权。会话 2 你要求限流。代理已经知道你的鉴权使用 `src/middleware/auth.ts` 中的 jose 中间件,测试覆盖了 token 校验,你选择 jose 而非 jsonwebtoken 是为了 Edge 兼容性。无需重新解释。无需复制粘贴。代理就是*知道*。
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **v0.9.0 新功能** — 落地页 [agent-memory.dev](https://agent-memory.dev) 上线,文件系统连接器(`@agentmemory/fs-watcher`),独立 MCP 现在代理至正在运行的服务器,使 hooks 和查看器保持一致,审计策略在所有删除路径上得到统一,健康状态在小型 Node 进程上不再误报 `memory_critical`。完整变更见 [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18)。
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### 检索准确率
+
+**coding-agent-life-v1** (内部语料库,沙盒可复现)
+
+| 适配器 | P@5 | R@5 | Top-5 命中率 | p50 延迟 |
+|---|---|---|---|---|
+| **agentmemory 混合** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep 基线 | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+100% Top-5 命中率。在同一输入下,精度比 grep 基线高 **2.2×**。完整按类型分解:[`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md)。
+
+**LongMemEval-S** (ICLR 2025,500 个问题)
+
+| 系统 | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| 仅 BM25 回退 | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Token 节省
+
+| 方法 | Token/年 | 成本/年 |
+|---|---|---|
+| 粘贴全部上下文 | 19.5M+ | 不可能(超出窗口) |
+| LLM 摘要 | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + 本地嵌入 | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> 嵌入模型:`all-MiniLM-L6-v2` (本地、免费、无需 API key)。完整报告:[`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md)、[`benchmark/QUALITY.md`](../benchmark/QUALITY.md)、[`benchmark/SCALE.md`](../benchmark/SCALE.md)。竞品对比:[`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory 对比 mem0、Letta、Khoj、claude-mem、Hippo。
+
+**本地复现:** [`eval/README.md`](../eval/README.md) — 适配器可插拔的 harness,支持 LongMemEval `_s`(公开 500 问)+ `coding-agent-life-v1`(内部 15 会话语料)。Grep / 向量 / agentmemory 适配器并排打分,NDJSON 输出,公开记分卡发布于 [`docs/benchmarks/`](../docs/benchmarks/)。
+
+**搭配 [codegraph](https://github.com/colbymchenry/codegraph)、[Understand Anything](https://github.com/Lum1104/Understand-Anything) 和 [Graphify](https://github.com/safishamsi/graphify) 使用。** 代码图索引、多代理构建流水线,以及跨文档 / PDF / 图像 / 视频的更广泛知识图谱。agentmemory 记住工作内容;这三个项目点亮上下文层的其余部分。组合配方和问题路由表:[`docs/recipes/pairings.md`](../docs/recipes/pairings.md)。
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="vs Competitors" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">内建 (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>类型</strong></td>
+<td>记忆引擎 + MCP 服务器</td>
+<td>记忆层 API</td>
+<td>完整代理运行时</td>
+<td>静态文件</td>
+</tr>
+<tr>
+<td><strong>检索 R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>自动捕获</strong></td>
+<td>12 hooks (零人工)</td>
+<td>手动调用 <code>add()</code></td>
+<td>代理自编辑</td>
+<td>手动编辑</td>
+</tr>
+<tr>
+<td><strong>搜索</strong></td>
+<td>BM25 + 向量 + 图 (RRF 融合)</td>
+<td>向量 + 图</td>
+<td>向量 (归档)</td>
+<td>将所有内容加载到上下文</td>
+</tr>
+<tr>
+<td><strong>多代理</strong></td>
+<td>MCP + REST + 租约 + 信号</td>
+<td>API (无协调)</td>
+<td>仅在 Letta 运行时内部</td>
+<td>每代理一个文件</td>
+</tr>
+<tr>
+<td><strong>框架锁定</strong></td>
+<td>无 (任何 MCP 客户端)</td>
+<td>无</td>
+<td>高 (必须使用 Letta)</td>
+<td>每代理格式</td>
+</tr>
+<tr>
+<td><strong>外部依赖</strong></td>
+<td>无 (SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + 向量数据库</td>
+<td>无</td>
+</tr>
+<tr>
+<td><strong>记忆生命周期</strong></td>
+<td>4 层整合 + 衰减 + 自动遗忘</td>
+<td>被动提取</td>
+<td>代理管理</td>
+<td>手动清理</td>
+</tr>
+<tr>
+<td><strong>Token 效率</strong></td>
+<td>~1,900 tokens/会话 ($10/年)</td>
+<td>依集成方式不同</td>
+<td>核心记忆位于上下文</td>
+<td>240 条观测达 22K+ tokens</td>
+</tr>
+<tr>
+<td><strong>实时查看器</strong></td>
+<td>是 (端口 3113)</td>
+<td>云端仪表板</td>
+<td>云端仪表板</td>
+<td>无</td>
+</tr>
+<tr>
+<td><strong>自托管</strong></td>
+<td>是 (默认)</td>
+<td>可选</td>
+<td>可选</td>
+<td>是</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
+
+兼容性:此版本面向稳定的 `iii-sdk` `^0.11.0` 和 iii-engine v0.11.x。
+
+### 30 秒体验
+
+```bash
+# 终端 1:启动服务器
+npx @agentmemory/agentmemory
+
+# 终端 2:注入示例数据并查看召回
+npx @agentmemory/agentmemory demo
+```
+
+`demo` 会注入 3 个真实会话(JWT 鉴权、N+1 查询修复、限流)并对它们执行语义搜索。你将看到搜索「数据库性能优化」时找到「N+1 查询修复」 — 关键词匹配做不到这一点。
+
+打开 `http://localhost:3113` 即时观察记忆的构建过程。
+
+### 推荐:全局安装
+
+`npx` 按版本缓存。如果你上周运行过 `npx @agentmemory/agentmemory@0.9.14`,裸 `npx @agentmemory/agentmemory` 命令可能会从 `~/.npm/_npx/` 提供过期的 0.9.14 而非最新版本。安装一次后,裸 `agentmemory` 命令处处可用:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# 如果在 macOS/Linux 的系统 Node 上遇到 EACCES,请重试:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # 启动服务器(等同于 npx 形式)
+agentmemory stop               # 停止
+agentmemory remove             # 卸载所有创建的内容
+agentmemory connect claude-code   # 连接一个代理
+agentmemory doctor             # 交互式诊断 + 修复提示
+```
+
+从 v0.9.16 开始,首次 npx 运行会内联提示你全局安装 — 回答一次 `Y` 即可。如果你跳过,可使用以下任一方式获取最新版:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # 强制从 npm 拉取最新(跨平台)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # 仅 macOS/Linux (POSIX shell)
+```
+
+在 Windows / PowerShell 上,等价的缓存清除命令是 `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — 上面的 `npx -y ...@latest` 形式是跨平台选项。
+
+### 会话回放
+
+agentmemory 记录的每个会话都可回放。打开查看器,选择 **Replay** 标签,在时间线上拖动:提示词、工具调用、工具结果和响应都作为离散事件呈现,支持播放/暂停、速度控制(0.5×–4×)和键盘快捷键(空格切换,箭头单步)。
+
+已有旧的 Claude Code JSONL 记录想导入?
+
+```bash
+# 导入默认 ~/.claude/projects 下的全部内容
+npx @agentmemory/agentmemory import-jsonl
+
+# 或导入单个文件
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+导入的会话与原生会话一起出现在 Replay 选择器中。底层每个条目都通过 `mem::replay::load`、`mem::replay::sessions`、`mem::replay::import-jsonl` 这些 iii 函数路由 — 没有侧通道服务器。
+
+### 升级 / 维护
+
+当你确实想更新本地运行时时,使用维护命令:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+警告:此命令会变更当前工作空间/运行时。它可能更新 JavaScript 依赖,可能运行 `cargo install iii-engine --force`,也可能拉取 Docker 镜像。
+
+实现细节见 `src/cli.ts`(参考 `src/cli.ts:544-595` 附近的 `runUpgrade`)。
+
+### Claude Code(一段话,直接粘贴)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Claude Code 不安装插件(MCP-standalone 路径)
+
+如果你直接通过 `~/.claude.json` 连接 agentmemory 的 MCP 服务器而不使用 `/plugin install`,Claude Code 永远不会解析 `${CLAUDE_PLUGIN_ROOT}`,你必须把 hook 脚本指向 `~/.claude/settings.json` 中的绝对路径。这些路径通常会嵌入 agentmemory 版本号(例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`),因此下次升级会静默破坏所有 hooks([#508](https://github.com/rohitg00/agentmemory/issues/508))。
+
+变通方法:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+这会将同样的 hook 命令合并到 `~/.claude/settings.json`,绝对路径解析到当前安装的 `@agentmemory/agentmemory` 包的 `plugin/` 目录。升级 agentmemory 后重新运行该命令以刷新路径。同一文件中的用户条目会被保留;只替换之前的 agentmemory 条目。仍然推荐使用 `/plugin install` 路径。
+
+对于远程或受保护的部署,启动 Claude Code 时设置 `AGENTMEMORY_URL` 和 `AGENTMEMORY_SECRET`。插件会将两个值传递给其捆绑的 MCP 服务器;当 `AGENTMEMORY_URL` 为空时,MCP shim 默认使用 `http://localhost:3111`。
+
+### Codex CLI(Codex 插件平台)
+
+```bash
+# 1. 在单独终端启动记忆服务器
+npx @agentmemory/agentmemory
+
+# 2. 注册 agentmemory 市场并安装插件
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex 插件与 Claude Code 插件同源,来自相同的 `plugin/` 目录。它注册:
+
+- `@agentmemory/mcp` 作为 MCP 服务器(当 `AGENTMEMORY_URL` 指向运行中的 agentmemory 服务器时,代理全部 51 个工具;若服务器不可达,本地回退至 7 个工具)
+- 6 个生命周期 hooks:`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PreCompact`、`Stop`
+- 4 个 skills:`/recall`、`/remember`、`/session-history`、`/forget`
+
+Codex 的 hook 引擎会将 `CLAUDE_PLUGIN_ROOT` 注入 hook 子进程(参见 [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)),因此同样的 hook 脚本在两个宿主中都能工作,无需重复实现。Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 事件仅 Claude Code 支持,Codex 未注册这些。
+
+#### Codex Desktop:插件 hooks 当前无响应(有变通方法)
+
+`CodexHooks` 和 `PluginHooks` 在 [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs) 中都已稳定且默认启用,但 Codex Desktop 当前不会派发插件本地的 `hooks.json`([openai/codex#16430](https://github.com/openai/codex/issues/16430))。MCP 工具仍能工作;只是生命周期观测缺失。
+
+在上游修复落地前,将同样的 hook 命令镜像到全局 `~/.codex/hooks.json`:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+这会在 `~/.codex/hooks.json` 添加一个幂等块,引用捆绑脚本的绝对路径(用户级作用域下无需 `${CLAUDE_PLUGIN_ROOT}` 展开)。升级 agentmemory 后重新运行同一命令以刷新路径。同一文件中的用户条目会被保留;只替换之前的 agentmemory 条目。
+
+<details>
+<summary><b>OpenClaw(粘贴此提示)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+完整指南:[`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent(粘贴此提示)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+完整指南:[`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### 其他代理
+
+启动记忆服务器:`npx @agentmemory/agentmemory`
+
+在使用 `mcpServers` 结构的每个宿主(Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI、OpenClaw)中,agentmemory 条目是**相同的 MCP 服务器块**:
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**将此条目合并到宿主配置文件的现有 `mcpServers` 对象中** — 不要替换整个文件。如果文件已经有其他服务器,把 `agentmemory` 作为另一个 key 加在它们旁边。如果完全缺少 `mcpServers`,把整块粘贴到 `{ "mcpServers": { ... } }` 里。`${VAR}` 占位符会在 MCP 服务器启动时从 shell 继承 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` — 未设置的变量传空字符串,shim 回退到 `http://localhost:3111`。一个接好的条目同时覆盖本地和远程(k8s / 反代)部署。
+
+| 代理 | 配置文件 | 备注 |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | 合并到 `mcpServers`。网站上也提供一键深链。 |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | 合并到 `mcpServers`。编辑后重启 Claude Desktop。 |
+| **Cline / Roo Code / Kilo Code** | Cline MCP 设置 (设置 UI → MCP Servers → Edit) | 同样的 `mcpServers` 块。 |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | 同样的 `mcpServers` 块。 |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user`(自动合并)。 |
+| **OpenClaw** | OpenClaw MCP 配置 | 同样的 `mcpServers` 块,或使用更深的[记忆插件](../integrations/openclaw/)。 |
+| **Codex CLI (仅 MCP)** | `.codex/config.toml` | TOML 形式:`codex mcp add agentmemory -- npx -y @agentmemory/mcp`,或手动添加 `[mcp_servers.agentmemory]`。 |
+| **Codex CLI (完整插件)** | Codex 插件市场 | `codex plugin marketplace add rohitg00/agentmemory` 然后 `codex plugin add agentmemory@agentmemory`。注册 MCP + 6 个生命周期 hooks(SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop)+ 4 个 skills。在 Codex Desktop 上,直到 [openai/codex#16430](https://github.com/openai/codex/issues/16430) 落地之前,还要运行 `agentmemory connect codex --with-hooks` — 那里的插件 hooks 当前无响应。 |
+| **OpenCode (仅 MCP)** | `opencode.json` | 不同结构 — 顶层 `mcp` key,command 是数组:`{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`。 |
+| **OpenCode (完整插件)** | `plugin/opencode/` | 22 个自动捕获 hooks,覆盖会话生命周期、消息、工具、错误。两个斜杠命令(`/recall`、`/remember`)。将 `plugin/opencode/` 复制到你的 OpenCode 工作空间并把插件条目添加到 `opencode.json`。完整 hook 表和差异分析见 [`plugin/opencode/README.md`](../plugin/opencode/README.md)。 |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | 复制 [`integrations/pi`](../integrations/pi/) 并重启 pi。 |
+| **Hermes Agent** | `~/.hermes/config.yaml` | 使用更深的[记忆提供者插件](../integrations/hermes/),设置 `memory.provider: agentmemory`。 |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` 会写入标准的 `mcpServers` 块。Hook 负载与 Claude Code 字段兼容,因此现有的 12 hook 脚本无需修改即可工作 — 通过同一 `settings.json` 的 `hooks` 段连接它们。 |
+| **Antigravity** (替换 Gemini CLI) | `mcp_config.json`(在 Antigravity 的 User 目录中) | `agentmemory connect antigravity` 会写入标准的 `mcpServers` 块。macOS: `~/Library/Application Support/Antigravity/User/`。Linux: `~/.config/Antigravity/User/`。在 2026-06-18 Gemini CLI 停服后使用。 |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` 写入用户级配置。工作空间覆盖放在你的代码旁的 `.kiro/settings/mcp.json` 中。 |
+| **Goose** | Goose MCP 设置 UI | 同样的 `mcpServers` 块。 |
+| **Aider** | n/a | 直接调用 REST API:`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
+| **任何代理 (32+)** | n/a | `npx skillkit install agentmemory` 自动检测宿主并合并。 |
+
+**沙盒化的 MCP 客户端**(Flatpak / Snap / 受限容器)无法访问宿主的 `localhost`:还要在 `env` 块中设置 `"AGENTMEMORY_FORCE_PROXY": "1"`,并把 `AGENTMEMORY_URL` 指向���盒确实能到达的路由(例如你的 LAN IP)。诊断步骤见 [#234](https://github.com/rohitg00/agentmemory/issues/234)。
+
+### 程序化访问(Python / Rust / Node)
+
+agentmemory 将其核心操作注册为 iii 函数(`mem::remember`、`mem::observe`、`mem::context`、`mem::smart-search`、`mem::forget`)。任何拥有 iii SDK 的语言都可以通过 `ws://localhost:49134` 直接调用它们 — 无需为每种语言准备单独的 REST 客户端。
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+完整示例:[`examples/python/`](../examples/python/)(快速开始 + 观测/召回流程)。`:3111` 上的 REST 对没有 iii 运行时的宿主仍然可用。
+
+### 从源码构建
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+如果已经安装 `iii`,这会以本地 `iii-engine` 启动 agentmemory;如果 Docker 可用,则回退到 Docker Compose。REST、流和查看器默认绑定到 `127.0.0.1`。
+
+手动安装 `iii-engine`。**agentmemory 当前将 `iii-engine` 固定在 `v0.11.2`** — `v0.11.6` 引入了新的「通过 `iii worker add` 沙盒化一切」模型,agentmemory 尚未为此重构。重构落地后即解除固定。如果你已经手动迁移到沙盒模型,可用 `AGENTMEMORY_III_VERSION=<version>` 覆盖。
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** 把 `aarch64-apple-darwin` 换成 `x86_64-apple-darwin`
+- **Linux x64:** 换成 `x86_64-unknown-linux-gnu`
+- **Linux arm64:** 换成 `aarch64-unknown-linux-gnu`
+- **Windows:** 从 [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2) 下载 `iii-x86_64-pc-windows-msvc.zip`,提取 `iii.exe`,加入 PATH
+
+或使用 Docker(捆绑的 `docker-compose.yml` 会拉取 `iiidev/iii:0.11.2`)。完整文档:[iii.dev/docs](https://iii.dev/docs)。
+
+### Windows
+
+agentmemory 可在 Windows 10/11 运行,但仅 Node.js 包不够 — 你还需要 `iii-engine` 运行时(一个独立的原生二进制)作为后台进程。官方上游安装器是 `sh` 脚本,目前没有 PowerShell 安装器或 scoop/winget 包,因此 Windows 用户有两条路径:
+
+**选项 A — 预构建 Windows 二进制(推荐):**
+
+```powershell
+# 1. 在浏览器打开 https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2
+#    (我们固定在 v0.11.2,直到 agentmemory 为 v0.11.6+ 引擎要求的
+#     新沙盒模型完成重构)
+# 2. 下载 iii-x86_64-pc-windows-msvc.zip
+#    (如果是 ARM 机器则下载 iii-aarch64-pc-windows-msvc.zip)
+# 3. 把 iii.exe 解压到 PATH 上的某处,或放在:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory 会自动检查该位置)
+# 4. 验证:
+iii --version
+# 应输出:0.11.2
+
+# 5. 然后照常运行 agentmemory:
+npx -y @agentmemory/agentmemory
+```
+
+**选项 B — Docker Desktop:**
+
+```powershell
+# 1. 安装 Docker Desktop for Windows
+# 2. 启动 Docker Desktop 并确保引擎运行中
+# 3. 运行 agentmemory — 它会自动启动捆绑的 compose 文件:
+npx -y @agentmemory/agentmemory
+```
+
+**选项 C — 仅独立 MCP(无引擎):** 如果你只需要 MCP 工具供代理使用,不需要 REST API、查看器或定时任务,则完全跳过引擎:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# 或通过 shim 包:
+npx -y @agentmemory/mcp
+```
+
+**Windows 诊断:** 如果 `npx @agentmemory/agentmemory` 失败,加 `--verbose` 重新运行以看到实际的引擎 stderr。常见失败模式:
+
+| 症状 | 修复 |
+|---|---|
+| `iii-engine process started` 然后 `did not become ready within 15s` | 引擎启动崩溃 — 用 `--verbose` 重新运行,检查 stderr |
+| `Could not start iii-engine` | `iii.exe` 和 Docker 都未安装。见上面选项 A 或 B |
+| 端口冲突 | `netstat -ano \| findstr :3111` 查看占用,然后 kill 或用 `--port <N>` |
+| Docker 已安装但仍跳过回退 | 确保 Docker Desktop 确实在运行(系统托盘图标) |
+
+> 注意:没有 `cargo install iii-engine` — `iii` 未发布到 crates.io。唯一受支持的安装方式是上面的预构建二进制、上游 `sh` 安装脚本(仅 macOS/Linux)和 Docker 镜像。
+
+---
+
+<h2 id="deploy">部署</h2>
+
+托管主机的一键模板。每个模板都附带自包含的
+Dockerfile,从 npm 拉取 `@agentmemory/agentmemory` 并从官方
+`iiidev/iii` Docker Hub 镜像复制 iii 引擎二进制 — 无需
+预构建 agentmemory 镜像。持久存储挂载在
+`/data`;首次启动 entrypoint 用面向部署调优的配置
+覆盖 npm 捆绑的 iii 配置(原配置绑定 `127.0.0.1`),
+让其绑定 `0.0.0.0` 并使用绝对 `/data` 路径,生成
+HMAC secret,然后通过 `gosu` 从 `root` 降权到 `node`
+再 exec agentmemory CLI。
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render 的一键部署按钮要求仓库根有 `render.yaml`,我们刻意保持根目录整洁。使用 [`deploy/render/`](../deploy/render/README.md) 中文档化的 Render Blueprint 流程,手动指向仓库内的蓝图。
+
+完整设置细节(HMAC 捕获、查看器 SSH 隧道、轮换、备份、
+成本下限)见 [`deploy/`](../deploy/README.md):
+
+- [`deploy/fly`](../deploy/fly/README.md) — 单机搭配
+  `auto_stop_machines = "stop"`;空闲时最便宜。
+- [`deploy/railway`](../deploy/railway/README.md) — Hobby 套餐固定费用,
+  卷在仪表板中配置。
+- [`deploy/render`](../deploy/render/README.md) — Blueprint 流程,
+  付费套餐自动磁盘快照。
+- [`deploy/coolify`](../deploy/coolify/README.md) — 通过 [Coolify](https://coolify.io/self-hosted)
+  在你自己的 VPS 上自托管;同样的 Docker
+  Compose 栈,主机和数据都归你所有。
+
+只发布端口 `3111`。`3113` 上的查看器在容器内仍绑定到
+loopback — 每个模板的 README 都文档化了到达它的
+SSH 隧道模式。
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
+
+每个编码代理在会话结束时都会忘记一切。你每次会话的前 5 分钟都浪费在重新解释技术栈上。agentmemory 在后台运行,完全消除这一点。
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### 对比内建代理记忆
+
+每个 AI 编码代理都自带内建记忆 — Claude Code 有 `MEMORY.md`,Cursor 有 notepad,Cline 有 memory bank。这些像便利贴。agentmemory 是便利贴背后的可搜索数据库。
+
+| | 内建 (CLAUDE.md) | agentmemory |
+|---|---|---|
+| 规模 | 200 行上限 | 无限 |
+| 搜索 | 把所有内容加载到上下文 | BM25 + 向量 + 图 (仅 top-K) |
+| Token 成本 | 240 条观测达 22K+ | ~1,900 tokens(少 92%) |
+| 跨代理 | 每代理一个文件 | MCP + REST(任何代理) |
+| 协调 | 无 | 租约、信号、动作、例程 |
+| 可观测性 | 手动读文件 | 端口 3113 实时查看器 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>
+
+### 记忆流水线
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4 层记忆整合
+
+灵感来自人脑处理记忆的方式 — 与睡眠时的记忆整合并无不同。
+
+| 层级 | 内容 | 类比 |
+|------|------|---------|
+| **Working(工作记忆)** | 来自工具使用的原始观测 | 短期记忆 |
+| **Episodic(情景记忆)** | 压缩后的会话摘要 | 「发生了什么」 |
+| **Semantic(语义记忆)** | 提取的事实与模式 | 「我知道什么」 |
+| **Procedural(程序记忆)** | 工作流与决策模式 | 「怎么做」 |
+
+记忆随时间衰减(Ebbinghaus 曲线)。频繁访问的记忆会强化。陈旧记忆会自动清除。矛盾会被检测并解决。
+
+### 捕获了什么
+
+| Hook | 捕获内容 |
+|------|----------|
+| `SessionStart` | 项目路径、会话 ID |
+| `UserPromptSubmit` | 用户提示词(隐私过滤) |
+| `PreToolUse` | 文件访问模式 + 富化上下文 |
+| `PostToolUse` | 工具名、���入、输出 |
+| `PostToolUseFailure` | 错误上下文 |
+| `PreCompact` | 在压缩前重新注入记忆 |
+| `SubagentStart/Stop` | 子代理生命周期 |
+| `Stop` | 会话结束摘要 |
+| `SessionEnd` | 会话完成标记 |
+
+### 关键能力
+
+| 能力 | 描述 |
+|---|---|
+| **自动捕获** | 每次工具使用都通过 hooks 记录 — 零人工 |
+| **语义搜索** | BM25 + 向量 + 知识图谱,RRF 融合 |
+| **记忆演化** | 版本控制、覆盖关系、关系图 |
+| **自动遗忘** | TTL 过期、矛盾检测、重要性驱逐 |
+| **隐私优先** | API key、secret、`<private>` 标签存储前被剥离 |
+| **自愈** | 熔断器、提供者回退链、健康监控 |
+| **Claude 桥接** | 与 MEMORY.md 双向同步 |
+| **知识图谱** | 实体抽取 + BFS 遍历 |
+| **团队记忆** | 团队成员之间的命名空间共享 + 私有 |
+| **引用溯源** | 任意记忆追溯到源观测 |
+| **Git 快照** | 记忆状态的版本、回滚、diff |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
+
+三路检索结合三种信号:
+
+| 流 | 作用 | 何时启用 |
+|---|---|---|
+| **BM25** | 词干化关键词匹配 + 同义词扩展 | 始终启用 |
+| **Vector(向量)** | 稠密嵌入上的余弦相似度 | 配置了嵌入提供者 |
+| **Graph(图)** | 通过实体匹配进行知识图谱遍历 | 查询中检测到实体 |
+
+通过 Reciprocal Rank Fusion (RRF, k=60) 融合,并按会话多样化(每会话最多 3 个结果)。
+
+BM25 开箱即用支持希腊语、西里尔语、希伯来语、阿拉伯语和带音标的拉丁文分词。对于中文/日语/韩语记忆,安装可选分词器(`npm install @node-rs/jieba tiny-segmenter`)以把 CJK 串切分为词级 token;不安装的话,agentmemory 会软回退到整串分词并在 stderr 打印一次性提示。
+
+### 嵌入提供者
+
+agentmemory 自动检测你的提供者。为获得最佳效果,安装本地嵌入(免费):
+
+```bash
+npm install @xenova/transformers
+```
+
+| 提供者 | 模型 | 成本 | 备注 |
+|---|---|---|---|
+| **本地 (推荐)** | `all-MiniLM-L6-v2` | 免费 | 离线,比仅 BM25 召回率高 +8pp |
+| Gemini | `gemini-embedding-001` | 免费层 | 100+ 语言,768/1536/3072 维 (MRL),2048-token 输入。替换 `text-embedding-004`([已弃用,2026 年 1 月 14 日下线](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | 最高质量 |
+| Voyage AI | `voyage-code-3` | 付费 | 针对代码优化 |
+| Cohere | `embed-english-v3.0` | 免费试用 | 通用 |
+| OpenRouter | 任意模型 | 视而定 | 多模型代理 |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>
+
+53 个工具、6 个资源、3 个提示词、4 个 skills — 任何代理可用的最全面 MCP 记忆工具包。
+
+> **MCP shim 对比完整服务器:** 已发布的 `@agentmemory/mcp` 包是一个薄 shim。**只有当它能通过 `AGENTMEMORY_URL` 连通运行中的 agentmemory 服务器**(代理模式)时,才暴露完整的 51 工具表面。在没有可达服务器的情况下,shim 回退到 7 工具的本地集合(`memory_save`、`memory_recall`、`memory_smart_search`、`memory_sessions`、`memory_export`、`memory_audit`、`memory_governance_delete`)。`AGENTMEMORY_TOOLS=core|all` 环境变量是*服务器端*标志 — 在 shim 的 `env` 块中设置无效。如果在 Cursor / OpenCode / Gemini CLI 中只看到 7 个工具,启动 `npx @agentmemory/agentmemory`(或 Docker 栈)并设置 `AGENTMEMORY_URL=http://localhost:3111`。
+
+### 51 个工具
+
+<details>
+<summary>核心工具(始终可用)</summary>
+
+| 工具 | 描述 |
+|------|-------------|
+| `memory_recall` | 搜索过去的观测 |
+| `memory_compress_file` | 在保留结构的同时压缩 markdown 文件 |
+| `memory_save` | 保存洞察、决策或模式 |
+| `memory_patterns` | 检测反复出现的模式 |
+| `memory_smart_search` | 混合语义 + 关键词搜索 |
+| `memory_file_history` | 关于特定文件的过去观测 |
+| `memory_sessions` | 列出最近的会话 |
+| `memory_timeline` | 按时间排列的观测 |
+| `memory_profile` | 项目档案(概念、文件、模式) |
+| `memory_export` | 导出所有记忆数据 |
+| `memory_relations` | 查询关系图 |
+
+</details>
+
+<details>
+<summary>扩展工具(总 51 — 设置 AGENTMEMORY_TOOLS=all)</summary>
+
+| 工具 | 描述 |
+|------|-------------|
+| `memory_patterns` | 检测反复出现的模式 |
+| `memory_timeline` | 按时间排列的观测 |
+| `memory_relations` | 查询关系图 |
+| `memory_graph_query` | 知识图谱遍历 |
+| `memory_consolidate` | 运行 4 层整合 |
+| `memory_claude_bridge_sync` | 与 MEMORY.md 同步 |
+| `memory_team_share` | 与团队成员共享 |
+| `memory_team_feed` | ��近共享条目 |
+| `memory_audit` | 操作审计轨迹 |
+| `memory_governance_delete` | 带审计轨迹的删除 |
+| `memory_snapshot_create` | Git 版本快照 |
+| `memory_action_create` | 创建带依赖的工作项 |
+| `memory_action_update` | 更新动作状态 |
+| `memory_frontier` | 按优先级排序的未阻塞动作 |
+| `memory_next` | 单个最重要的下一动作 |
+| `memory_lease` | 独占动作租约(多代理) |
+| `memory_routine_run` | 实例化工作流例程 |
+| `memory_signal_send` | 代理间消息 |
+| `memory_signal_read` | 带回执读取消息 |
+| `memory_checkpoint` | 外部条件门 |
+| `memory_mesh_sync` | 实例间 P2P 同步 |
+| `memory_sentinel_create` | 事件驱动监视器 |
+| `memory_sentinel_trigger` | 外部触发哨兵 |
+| `memory_sketch_create` | 临时动作图 |
+| `memory_sketch_promote` | 提升为永久 |
+| `memory_crystallize` | 紧凑化动作链 |
+| `memory_diagnose` | 健康检查 |
+| `memory_heal` | 自动修复卡住的状态 |
+| `memory_facet_tag` | 维度:值 标签 |
+| `memory_facet_query` | 按 facet 标签查询 |
+| `memory_verify` | 追溯来源 |
+
+</details>
+
+### 6 个资源 · 3 个提示词 · 4 个 Skills
+
+| 类型 | 名称 | 描述 |
+|------|------|-------------|
+| Resource | `agentmemory://status` | 健康、会话数、记忆数 |
+| Resource | `agentmemory://project/{name}/profile` | 项目级智能 |
+| Resource | `agentmemory://memories/latest` | 最新 10 条活跃记忆 |
+| Resource | `agentmemory://graph/stats` | 知识图谱统计 |
+| Prompt | `recall_context` | 搜索并返回上下文消息 |
+| Prompt | `session_handoff` | 代理之间的交接数据 |
+| Prompt | `detect_patterns` | 分析反复出现的模式 |
+| Skill | `/recall` | 搜索记忆 |
+| Skill | `/remember` | 保存到长期记忆 |
+| Skill | `/session-history` | 最近的会话摘要 |
+| Skill | `/forget` | 删除观测/会话 |
+
+### 独立 MCP
+
+无需完整服务器即可运行 — 适用于任何 MCP 客户端。以下两种都可以:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # 规范命令(始终可用)
+npx -y @agentmemory/mcp                # shim 包别名
+```
+
+或添加到你的代理的 MCP 配置:
+
+大多数代理(Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+把 `agentmemory` 条目合并到你的宿主现有的 `mcpServers` 对象中,而非替换文件。对于无法访问宿主 `localhost` 的沙盒客户端,在 env 块中添加 `"AGENTMEMORY_FORCE_PROXY": "1"`,并将 `AGENTMEMORY_URL` 设为沙盒能到达的路由。
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+从仓库复制插件文件:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
+
+在端口 `3113` 自动启动。实时观测流、会话浏览器、记忆浏览器、知识图谱可视化和健康仪表板。
+
+```bash
+open http://localhost:3113
+```
+
+查看器服务器默认绑定 `127.0.0.1`。REST 提供的 `/agentmemory/viewer` 端点遵循正常的 `AGENTMEMORY_SECRET` bearer-token 规则。CSP 头使用每响应 script nonce 并禁用内联处理器属性(`script-src-attr 'none'`)。
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+`:3113` 上的查看器展示你的代理**记住了什么**。[iii 控制台](https://iii.dev/docs/console) 展示你的代理**做了什么** — 每个记忆操作都是 OpenTelemetry trace,每个 KV 条目都可编辑,每个函数都可调用,每个流都可挂载。同一记忆的两个窗口:一个面向产品,一个面向引擎。
+
+观察一次 `memory_smart_search` 触发,在瀑布图中看到 BM25 扫描 → 嵌入查找 → RRF 融合 → 重排器。在 KV 浏览器中编辑卡住的整合计时器。用调整后的负载重放一个 `PostToolUse` hook。固定 WebSocket 流,实时观察观测落地。
+
+agentmemory 免费提供这一切,因为每个函数、触发器、状态作用域、流都是 iii 原语 — 没有定制,没有需要插桩的地方。
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
+  <br/>
+  <em>Workers 页面:每个已连接的 worker — 包括 agentmemory 本身 — 显示 PID、函数数、运行时和最后在线时间。</em>
+</p>
+
+**已经装好了。** 控制台随 `iii` 一同发布 — 无需单独安装器。
+
+**与 agentmemory 并行启动:**
+
+```bash
+# agentmemory 查看器占用端口 3113,所以在 3114 运行控制台。
+# 引擎 REST (3111)、WebSocket (3112)、bridge (49134) 默认值与 agentmemory 匹配。
+iii console --port 3114
+```
+
+然后打开 `http://localhost:3114`。加 `--enable-flow` 开启实验性架构图页面。
+
+仅在你移动了引擎端点时才覆盖:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**控制台能做什么:**
+
+| 页面 | 用途 |
+|------|-----------|
+| **Workers** | 查看每个已连接 worker 及其实时指标 — 包括 agentmemory worker 本身。 |
+| **Functions** | 直接用 JSON 负载调用 agentmemory 的任何函数 — 测试 `memory.recall`、`memory.consolidate`、`graph.query` 无需接入客户端。 |
+| **Triggers** | 重放 HTTP、cron、事件和状态触发器 — 手动触发整合 cron、重试 HTTP 路由、发出状态变化。 |
+| **States** | 完整 CRUD 的 KV 浏览器 — 会话、记忆槽位、生命周期计时器、嵌入索引 — 就地编辑值。 |
+| **Streams** | 记忆写入、hook 事件和观测更新流经 iii 流时的实时 WebSocket 监视器。 |
+| **Queues** | 持久队列主题 + 死信管理。重放或丢弃失败的嵌入/压缩任务。 |
+| **Traces** | OpenTelemetry 瀑布/火焰/服务分解视图。按 `trace_id` 过滤,精确查看单次 `memory.search` 产生了哪些函数、DB 调用和嵌入请求。 |
+| **Logs** | 结构化 OTEL 日志,过滤并与 trace/span ID 关联。 |
+| **Config** | 运行时配置 — 看到引擎正在使用的 workers、提供者和端口。 |
+| **Flow** | (可选,`--enable-flow`) 每个 worker、触发器和流的交互式架构图。 |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
+  <br/>
+  <em>Traces:每个记忆操作的瀑布/火焰/服务分解。</em>
+</p>
+
+**Traces 已开启:**
+
+`iii-config.yaml` 出厂启用 `iii-observability` worker(`exporter: memory`、`sampling_ratio: 1.0`、指标 + 日志)。无需额外配置 — agentmemory 启动那一刻,每个记忆操作都会发出一个 trace span 和一个控制台可读的结构化日志。
+
+如果你想改为导出到 Jaeger/Honeycomb/Grafana Tempo,把 `exporter: memory` 改为 `exporter: otlp` 并按 iii 的可观测性文档设置收集器端点。
+
+> **提醒:** 控制台本身未强制鉴权 — 保持其绑定 `127.0.0.1`(默认)并永远不要对外暴露。
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory **本身就是一个运行中的 [iii](https://iii.dev) 实例**。函数、触发器、KV 状态、流、OTEL traces — 全部都是 iii 原语。你没有安装 Postgres、Redis、Express、pm2 或 Prometheus,因为 iii 替代了它们。
+
+这意味着多一条命令就能为 agentmemory 增加一整套新能力。
+
+### 一条命令扩展 agentmemory
+
+```bash
+iii worker add iii-pubsub          # 把记忆写入扇出到每个连接的实例
+iii worker add iii-cron            # 定时整合、衰减扫描、快照轮换
+iii worker add iii-queue           # 嵌入 + 压缩任务的持久重试
+iii worker add iii-observability   # 每个记忆操作的 OTEL traces(默认开启)
+iii worker add iii-sandbox         # 在隔离 microVM 内运行召回到的代码
+iii worker add iii-database        # 切换 SQL 后端的状态适配器
+iii worker add mcp                 # 在 agentmemory 的 MCP 旁开通用 MCP 宿主
+```
+
+每个 `iii worker add` 都会把新的函数和触发器注册到 agentmemory 正在运行的同一引擎中。查看器和控制台立即接收 — 无需重载、无需新集成、无需新容器。
+
+| `iii worker add` | 在 agentmemory 上获得的额外能力 |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | 多实例记忆:每次 `remember` 扇出,每次 `search` 读取并集 |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | 定时生命周期 — 夜间整合、周快照、按固定时钟衰减 |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | 持久重试:失败的嵌入 + 压缩任务在重启后存活,无观测丢失 |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | 每个函数的 OTEL traces、指标、日志 — 从第一天起就接入 `iii-config.yaml` |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` 出来的代码在一次性 VM 中运行,不在你的 shell 中 |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | 当默认的内存 KV 不够用时,SQL 后端状态适配器 |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | 在 agentmemory 的旁边架设额外 MCP 服务器,共享同一引擎 |
+
+完整注册表:[workers.iii.dev](https://workers.iii.dev)。那里的每个 worker 都通过 agentmemory 所用的同样原语组合 — 而你已经拥有的 agentmemory 本身就是其中之一。
+
+### iii 替代了什么
+
+| 传统栈 | agentmemory 使用 |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + 内存向量索引 |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker 监管 |
+| Prometheus / Grafana | iii OTEL + 健康监控 |
+| 自定义插件系统 | `iii worker add <name>` |
+
+**118 个源文件 · ~21,800 行代码 · 950+ 测试 · 123 个函数 · 34 个 KV 作用域** — 全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### LLM 提供者
+
+agentmemory 从你的环境自动检测。默认情况下,除非你配置提供者或显式启用 Claude 订阅回退,否则不会发起 LLM 调用。
+
+| 提供者 | 配置 | 备注 |
+|----------|--------|-------|
+| **No-op(默认)** | 无需配置 | LLM 驱动的 compress/summarize 被禁用。合成 BM25 压缩 + 召回仍可用。如果你以前依赖 Claude 订阅回退,请见下面的 `AGENTMEMORY_ALLOW_AGENT_SDK`。 |
+| Anthropic API | `ANTHROPIC_API_KEY` | 按 token 计费 |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic 兼容 |
+| Gemini | `GEMINI_API_KEY` | 同时启用嵌入 |
+| OpenRouter | `OPENROUTER_API_KEY` | 任意模型 |
+| Claude 订阅回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 仅按需启用。会派生 `@anthropic-ai/claude-agent-sdk` 会话 — 曾导致无限 Stop-hook 递归(#149 后续)故不再默认。 |
+
+### 成本感知的模型选择
+
+后台压缩在每次观测时运行,模型选择会显著影响月度支出。捕获的工作负载数据:635 次请求 / 888K tokens / 35 小时活跃使用,基于 2026-05-23 OpenRouter 定价对三个模型评测。
+
+| 等级 | 模型 | 输入 / 1M | 输出 / 1M | 35 小时捕获工作负载成本 | 备注 |
+|------|-------|------------|-------------|---------------------------|-------|
+| 推荐 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | 压缩 + 摘要质量稳定,比 Sonnet 便宜 ~10×。 |
+| 推荐 | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | 略旧但仍胜任仅压缩工作负载。 |
+| 推荐 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 如果你的会话多为代码,代码推理能力强。 |
+| 高级 | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | 质量高但对长期后台工作来说成本昂贵。 |
+| 高级 | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | 与 Sonnet 同档。 |
+| 避免 | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | 推理级模型;用于压缩属于巨额超支。 |
+
+当 `OPENROUTER_MODEL` 匹配高级层模式时,agentmemory 会打印运行时警告。在做出知情选择后,设置 `AGENTMEMORY_SUPPRESS_COST_WARNING=1` 来消音。
+
+记忆工作的质量-成本权衡:压缩是质量门槛相对宽松的摘要任务(代理重新阅读摘要,而非用户)。DeepSeek-V4-Pro / Qwen3-Coder 在该任务上与 Sonnet 误差极小,而成本约低 10×。把高级层模型留给你直接阅读的查询。
+
+来源:[OpenRouter Sonnet 4.6 定价](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing)、[DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro)、[DeepSeek 定价说明](https://api-docs.deepseek.com/quick_start/pricing/)。
+
+### 多代理记忆(`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+在多个角色共享一台 agentmemory 服务器的多代理设置中(architect / developer / reviewer / researcher / support-agent),`AGENT_ID` 给每次写入打上发起角色的标签。`AGENTMEMORY_AGENT_SCOPE` 控制召回是否按该标签过滤。
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # 可选;默认 "shared"
+```
+
+两种模式:
+
+| 模式 | 标记写入 | 过滤召回 | 何时使用 |
+|------|------------|---------------|-------------|
+| `shared`(默认) | 是 | 否 | 跨代理共享上下文且带审计轨迹。Architect 能看到 developer 记下了什么,但每条记录都标明发言者。 |
+| `isolated` | 是 | 是 | 严格隔离。Architect 永远不会看到 developer 的观测/记忆/会话。 |
+
+设置 `AGENT_ID` 后会被标记的内容:`Session.agentId`、`RawObservation.agentId`、`CompressedObservation.agentId`、`Memory.agentId`。角色从 `api::session::start` → `mem::observe` → `mem::compress` → KV 流转。
+
+isolated 模式下被过滤的内容:`mem::smart-search`、`/agentmemory/memories`、`/agentmemory/observations`、`/agentmemory/sessions`。每个端点都接受 `?agentId=<role>` 来按请求覆盖,以及 `?agentId=*` 来完全跳过环境作用域。`/memories` 还接受 `?includeOrphans=true` 来浮现 `agentId` 为 undefined 的预-AGENT_ID 记忆。
+
+SDK / REST 层的按调用覆盖:每个修改端点(`/session/start`、`/remember`)都接受请求体中的 `agentId` 字段,胜过环境变量。对于在一个服务器进程中路由多角色的运行时很有用。
+
+当 `AGENT_ID` 未设置时,记忆保持无作用域(遗留行为,无标签、无过滤)。
+
+### 端口
+
+agentmemory + iii-engine 默认绑定四个端口。如果重启失败并显示 `port in use`,这张表告诉你该查找什么进程。
+
+| 端口 | 进程 | 用途 | 环境覆盖 |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | 内部流 worker(由 agentmemory + 查看器消费) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | 实时查看器(`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — workers 在此注册,OTel 遥测在此流过 | `III_ENGINE_URL`(完整 URL,默认 `ws://localhost:49134`) |
+
+崩溃后端口仍被占用时的陈旧进程清理:
+
+```bash
+# macOS / Linux — 查找每个端口上的进程并杀掉
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` 在优雅关闭时干净地回收 worker 和 engine pidfile(#640、#474)。上面的手动清理仅针对崩溃后两个 pidfile 都未留下的情况。
+
+### 配置文件
+
+把 agentmemory 运行时配置放到 `~/.agentmemory/.env`,而不是在每个 shell 中 export 变量。如果查看器显示像 `export ANTHROPIC_API_KEY=...` 这样的设置提示,把它复制到该文件中作为 `ANTHROPIC_API_KEY=...`(去掉 `export` 前缀),然后重启 agentmemory。
+
+进程环境变量仍然有效,优先级高于文件中的值。
+
+在 Windows 上,同一文件位于 `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+要用 Claude Code Pro/Max 订阅而非 API key 测试,显式启用:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+如果想开启图或整合特性,在同一文件中打开:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### 环境变量
+
+创建 `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+端口 `3111` 上的 124 个端点。REST API 默认绑定 `127.0.0.1`。当 `AGENTMEMORY_SECRET` 已设置时,受保护端点需要 `Authorization: Bearer <secret>`,网状同步端点要求两端都设置 `AGENTMEMORY_SECRET`。
+
+<details>
+<summary>关键端点</summary>
+
+| 方法 | 路径 | 描述 |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | 健康检查(始终公开) |
+| `POST` | `/agentmemory/session/start` | 开始会话 + 获取上下文 |
+| `POST` | `/agentmemory/session/end` | 结束会话 |
+| `POST` | `/agentmemory/observe` | 捕获观测 |
+| `POST` | `/agentmemory/smart-search` | 混合搜索 |
+| `POST` | `/agentmemory/context` | 生成上下文 |
+| `POST` | `/agentmemory/remember` | 保存到长期记忆 |
+| `POST` | `/agentmemory/forget` | 删除观测 |
+| `POST` | `/agentmemory/enrich` | 文件上下文 + 记忆 + bugs |
+| `GET` | `/agentmemory/profile` | 项目档案 |
+| `GET` | `/agentmemory/export` | 导出所有数据 |
+| `POST` | `/agentmemory/import` | 从 JSON 导入 |
+| `POST` | `/agentmemory/graph/query` | 知识图谱查询 |
+| `POST` | `/agentmemory/team/share` | 与团队共享 |
+| `GET` | `/agentmemory/audit` | 审计轨迹 |
+
+完整端点列表:[`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
+
+```bash
+npm run dev               # 热重载
+npm run build             # 生产构建
+npm test                  # 950+ 测试
+npm run test:integration  # API 测试(需要服务运行中)
+```
+
+**先决条件:** Node.js >= 20、[iii-engine](https://iii.dev/docs) 或 Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

READMEs/README.zh-TW.md

@@ -0,0 +1,1378 @@
+<p align="center">
+  <img src="../assets/banner.png" alt="agentmemory — 為 AI 編碼代理提供持久化記憶" width="720" />
+</p>
+
+<p align="center">
+  <strong>
+    讓你的編碼代理記住一切。不再重複解釋。
+    Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+  </strong><br/>
+  為 Claude Code、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 以及任何 MCP 用戶端提供持久化記憶。
+</p>
+
+<p align="center">
+  <a href="../README.md">English</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  繁體中文 |
+  <a href="README.ja-JP.md">日本語</a> |
+  <a href="README.ko-KR.md">한국어</a> |
+  <a href="README.es-ES.md">Español</a> |
+  <a href="README.tr-TR.md">Türkçe</a> |
+  <a href="README.ru-RU.md">Русский</a> |
+  <a href="README.hi-IN.md">हिन्दी</a> |
+  <a href="README.pt-BR.md">Português</a> |
+  <a href="README.fr-FR.md">Français</a> |
+  <a href="README.de-DE.md">Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://trendshift.io/repositories/25123" target="_blank"><img src="https://trendshift.io/api/badge/repositories/25123" alt="rohitg00/agentmemory | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/?repos=rohitg00%2Fagentmemory&type=date&legend=top-left">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&theme=dark&legend=top-left" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+      <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=rohitg00/agentmemory&type=date&legend=top-left" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://gist.github.com/rohitg00/2067ab416f7bbe447c1977edaaa681e2"><img src="https://img.shields.io/badge/Viral%20GitHub%20Gist-1200%20stars%20%2F%20172%20forks-FF6B35?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a1a" alt="Design doc: 1200 stars / 172 forks on the gist" /></a>
+</p>
+
+<p align="center">
+  <em>這份 gist 以信心評分、生命週期管理、知識圖譜和混合搜尋擴展了 Karpathy 的 LLM Wiki 模式:agentmemory 就是其實作。</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/dm/@agentmemory/agentmemory?color=CB3837&label=downloads&style=for-the-badge&logo=npm" alt="npm downloads" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-recall.svg"><img src="../assets/tags/stat-recall.svg" alt="95.2% retrieval R@5" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tokens.svg"><img src="../assets/tags/stat-tokens.svg" alt="92% fewer tokens" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="53 MCP tools" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
+  <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="950+ tests passing" height="38" /></picture>
+</p>
+
+<p align="center">
+  <img src="../assets/demo.gif" alt="agentmemory demo" width="720" />
+</p>
+
+<p align="center">
+  <a href="#install">安裝</a> &bull;
+  <a href="#quick-start">快速開始</a> &bull;
+  <a href="#benchmarks">基準測試</a> &bull;
+  <a href="#vs-competitors">對比競品</a> &bull;
+  <a href="#works-with-every-agent">代理</a> &bull;
+  <a href="#how-it-works">運作原理</a> &bull;
+  <a href="#mcp-server">MCP</a> &bull;
+  <a href="#real-time-viewer">檢視器</a> &bull;
+  <a href="#iii-console">iii 主控台</a> &bull;
+  <a href="#powered-by-iii">由 iii 驅動</a> &bull;
+  <a href="#configuration">設定</a> &bull;
+  <a href="#api">API</a>
+</p>
+
+---
+
+## 安裝
+
+```bash
+npm install -g @agentmemory/agentmemory          # 一次安裝 — 全域可用 `agentmemory` 指令
+# 如果在 macOS/Linux 的系統 Node 上遇到 EACCES,請重試:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                                      # 在 :3111 啟動記憶伺服器
+agentmemory demo                                 # 注入範例會話並驗證召回
+agentmemory connect claude-code                  # 連接你的代理(也支援: codex, cursor, gemini-cli, ...)
+```
+
+或透過 `npx`(無需安裝):
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+提醒 — npx 會依版本快取。若裸 `npx @agentmemory/agentmemory` 指令執行的是舊版,強制使用最新版 `npx -y @agentmemory/agentmemory@latest`,或一次性清除快取 `rm -rf ~/.npm/_npx`(macOS/Linux;Windows 上刪除 `%LOCALAPPDATA%\npm-cache\_npx`)。從 v0.9.16+ 起,首次 npx 執行會以行內方式提示你全域安裝,之後裸 `agentmemory` 指令在任何地方都能用。
+
+完整選項見下方[快速開始](#quick-start)。各代理具體接入見[支援所有代理](#works-with-every-agent)。
+
+---
+
+<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
+
+agentmemory 相容任何支援 hooks、MCP 或 REST API 的代理。所有代理共享同一個記憶伺服器。
+
+<table>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
+<strong>Claude Code</strong><br/>
+<sub>原生外掛 + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>原生外掛 + 6 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
+<strong>OpenClaw</strong><br/>
+<sub>原生外掛 + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
+<strong>Hermes</strong><br/>
+<sub>原生外掛 + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>原生外掛 + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>原生 Memory trait 後端</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
+<strong>Cursor</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/google-gemini/gemini-cli"><img src="https://github.com/google-gemini.png?size=120" alt="Gemini CLI" width="48" height="48" /></a><br/>
+<strong>Gemini CLI</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="12.5%">
+<a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
+<strong>OpenCode</strong><br/>
+<sub>22 hooks + MCP + 外掛</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
+<strong>Cline</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
+<strong>Goose</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
+<strong>Kilo Code</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
+<strong>Aider</strong><br/>
+<sub>REST API</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
+<strong>Claude Desktop</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg?size=120" alt="Windsurf" width="48" height="48" /></a><br/>
+<strong>Windsurf</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
+<strong>Roo Code</strong><br/>
+<sub>MCP 伺服器</sub>
+</td>
+</tr>
+</table>
+
+<p align="center">
+  <sub>相容<strong>任何</strong>使用 MCP 或 HTTP 的代理。一個伺服器,所有代理共享記憶。</sub>
+</p>
+
+---
+
+你每次會話都在重複解釋同樣的架構。你反覆發現同樣的 bug。你重複教同樣的偏好。內建的記憶(CLAUDE.md、.cursorrules)上限是 200 行而且會過期。agentmemory 解決了這個問題。它在背景靜默捕捉代理的行為,將其壓縮為可搜尋的記憶,並在下次會話開始時注入正確的上下文。一條指令。跨代理工作。
+
+**改變了什麼:** 會話 1 你設定了 JWT 驗證。會話 2 你要求限流。代理已經知道你的驗證使用 `src/middleware/auth.ts` 中的 jose middleware,測試覆蓋了 token 驗證,你選擇 jose 而非 jsonwebtoken 是為了 Edge 相容性。無需重新解釋。無需複製貼上。代理就是*知道*。
+
+```bash
+npx @agentmemory/agentmemory
+```
+
+> **v0.9.0 新功能** — 著陸頁 [agent-memory.dev](https://agent-memory.dev) 上線,檔案系統連接器(`@agentmemory/fs-watcher`),獨立 MCP 現在代理至執行中的伺服器,使 hooks 和檢視器保持一致,稽核策略在所有刪除路徑上得到統一,健康狀態在小型 Node 行程上不再誤報 `memory_critical`。完整變更見 [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18)。
+
+---
+
+<h2 id="benchmarks"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-benchmarks.svg"><img src="../assets/tags/section-benchmarks.svg" alt="Benchmarks" height="32" /></picture></h2>
+
+<table>
+<tr>
+<td width="50%">
+
+### 檢索準確率
+
+**coding-agent-life-v1** (內部語料庫,沙盒可重現)
+
+| 適配器 | P@5 | R@5 | Top-5 命中率 | p50 延遲 |
+|---|---|---|---|---|
+| **agentmemory 混合** | **0.578** | **0.967** | **15 / 15** | 14 ms |
+| grep 基線 | 0.267 | 0.967 | 15 / 15 | 0 ms |
+
+100% Top-5 命中率。在相同輸入下,精確度比 grep 基線高 **2.2×**。完整依類型分解:[`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md)。
+
+**LongMemEval-S** (ICLR 2025,500 個問題)
+
+| 系統 | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| 僅 BM25 回退 | 86.2% | 94.6% | 71.5% |
+
+</td>
+<td width="50%">
+
+### Token 節省
+
+| 方法 | Token/年 | 成本/年 |
+|---|---|---|
+| 貼上完整上下文 | 19.5M+ | 不可能(超出窗口) |
+| LLM 摘要 | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + 本地嵌入 | ~170K | **$0** |
+
+</td>
+</tr>
+</table>
+
+> 嵌入模型:`all-MiniLM-L6-v2`(本地、免費、無需 API key)。完整報告:[`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md)、[`benchmark/QUALITY.md`](../benchmark/QUALITY.md)、[`benchmark/SCALE.md`](../benchmark/SCALE.md)。競品比較:[`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory 比較 mem0、Letta、Khoj、claude-mem、Hippo。
+
+**在地重現:** [`eval/README.md`](../eval/README.md) — 適配器可插拔的 harness,支援 LongMemEval `_s`(公開 500 問)+ `coding-agent-life-v1`(內部 15 會話語料)。Grep / 向量 / agentmemory 適配器並排計分,NDJSON 輸出,公開計分卡發布於 [`docs/benchmarks/`](../docs/benchmarks/)。
+
+**搭配 [codegraph](https://github.com/colbymchenry/codegraph)、[Understand Anything](https://github.com/Lum1104/Understand-Anything) 和 [Graphify](https://github.com/safishamsi/graphify) 使用。** 程式碼圖索引、多代理建置流水線,以及跨文件 / PDF / 圖片 / 影片的更廣泛知識圖譜。agentmemory 記住工作內容;這三個專案點亮上下文層其餘部分。組合配方與問題路由表:[`docs/recipes/pairings.md`](../docs/recipes/pairings.md)。
+
+---
+
+<h2 id="vs-competitors"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-competitors.svg"><img src="../assets/tags/section-competitors.svg" alt="vs Competitors" height="32" /></picture></h2>
+
+<table>
+<tr>
+<th width="20%"></th>
+<th width="20%">agentmemory</th>
+<th width="20%">mem0 (53K ⭐)</th>
+<th width="20%">Letta / MemGPT (22K ⭐)</th>
+<th width="20%">內建 (CLAUDE.md)</th>
+</tr>
+<tr>
+<td><strong>類型</strong></td>
+<td>記憶引擎 + MCP 伺服器</td>
+<td>記憶層 API</td>
+<td>完整代理執行階段</td>
+<td>靜態檔案</td>
+</tr>
+<tr>
+<td><strong>檢索 R@5</strong></td>
+<td><strong>95.2%</strong></td>
+<td>68.5% (LoCoMo)</td>
+<td>83.2% (LoCoMo)</td>
+<td>N/A (grep)</td>
+</tr>
+<tr>
+<td><strong>自動捕捉</strong></td>
+<td>12 hooks(零人工)</td>
+<td>手動呼叫 <code>add()</code></td>
+<td>代理自編輯</td>
+<td>手動編輯</td>
+</tr>
+<tr>
+<td><strong>搜尋</strong></td>
+<td>BM25 + 向量 + 圖(RRF 融合)</td>
+<td>向量 + 圖</td>
+<td>向量(歸檔)</td>
+<td>把所有內容載入上下文</td>
+</tr>
+<tr>
+<td><strong>多代理</strong></td>
+<td>MCP + REST + 租約 + 訊號</td>
+<td>API(無協調)</td>
+<td>僅在 Letta 執行階段內部</td>
+<td>每個代理一個檔案</td>
+</tr>
+<tr>
+<td><strong>框架鎖定</strong></td>
+<td>無(任何 MCP 用戶端)</td>
+<td>無</td>
+<td>高(必須使用 Letta)</td>
+<td>每個代理格式</td>
+</tr>
+<tr>
+<td><strong>外部相依</strong></td>
+<td>無(SQLite + iii-engine)</td>
+<td>Qdrant / pgvector</td>
+<td>Postgres + 向量資料庫</td>
+<td>無</td>
+</tr>
+<tr>
+<td><strong>記憶生命週期</strong></td>
+<td>4 層整合 + 衰減 + 自動遺忘</td>
+<td>被動擷取</td>
+<td>代理管理</td>
+<td>手動清理</td>
+</tr>
+<tr>
+<td><strong>Token 效率</strong></td>
+<td>~1,900 tokens/會話 ($10/年)</td>
+<td>依整合方式不同</td>
+<td>核心記憶位於上下文</td>
+<td>240 條觀測達 22K+ tokens</td>
+</tr>
+<tr>
+<td><strong>即時檢視器</strong></td>
+<td>是(連接埠 3113)</td>
+<td>雲端儀表板</td>
+<td>雲端儀表板</td>
+<td>無</td>
+</tr>
+<tr>
+<td><strong>自架</strong></td>
+<td>是(預設)</td>
+<td>選用</td>
+<td>選用</td>
+<td>是</td>
+</tr>
+</table>
+
+---
+
+<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
+
+相容性:此版本面向穩定的 `iii-sdk` `^0.11.0` 和 iii-engine v0.11.x。
+
+### 30 秒體驗
+
+```bash
+# 終端 1:啟動伺服器
+npx @agentmemory/agentmemory
+
+# 終端 2:注入範例資料並查看召回
+npx @agentmemory/agentmemory demo
+```
+
+`demo` 會注入 3 個真實會話(JWT 驗證、N+1 查詢修正、限流)並對它們執行語義搜尋。你將看到搜尋「資料庫效能最佳化」時找到「N+1 查詢修正」 — 關鍵字比對做不到這一點。
+
+打開 `http://localhost:3113` 即時觀察記憶的建構過程。
+
+### 推薦:全域安裝
+
+`npx` 依版本快取。若你上週執行過 `npx @agentmemory/agentmemory@0.9.14`,裸 `npx @agentmemory/agentmemory` 指令可能會從 `~/.npm/_npx/` 提供過期的 0.9.14 而非最新版。安裝一次後,裸 `agentmemory` 指令處處可用:
+
+```bash
+npm install -g @agentmemory/agentmemory
+# 如果在 macOS/Linux 的系統 Node 上遇到 EACCES,請重試:
+# sudo npm install -g @agentmemory/agentmemory
+agentmemory                    # 啟動伺服器(等同 npx 形式)
+agentmemory stop               # 停止
+agentmemory remove             # 解除安裝所有建立的內容
+agentmemory connect claude-code   # 連接一個代理
+agentmemory doctor             # 互動式診斷 + 修復提示
+```
+
+從 v0.9.16 開始,首次 npx 執行會以行內方式提示你全域安裝 — 回答一次 `Y` 即可。若你跳過,可使用以下任一方式取得最新版本:
+
+```bash
+npx -y @agentmemory/agentmemory@latest                 # 強制從 npm 拉取最新(跨平台)
+rm -rf ~/.npm/_npx && npx @agentmemory/agentmemory     # 僅 macOS/Linux (POSIX shell)
+```
+
+在 Windows / PowerShell 上,等價的快取清除指令是 `Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"` — 上面的 `npx -y ...@latest` 形式是跨平台選項。
+
+### 會話重播
+
+agentmemory 紀錄的每個會話都可重播。打開檢視器,選擇 **Replay** 標籤,在時間軸上拖動:提示、工具呼叫、工具結果和回應都以離散事件呈現,支援播放/暫停、速度控制(0.5×–4×)和鍵盤快捷鍵(空白鍵切換,方向鍵單步)。
+
+已有舊的 Claude Code JSONL 紀錄想匯入?
+
+```bash
+# 匯入預設 ~/.claude/projects 下的全部內容
+npx @agentmemory/agentmemory import-jsonl
+
+# 或匯入單一檔案
+npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+匯入的會話與原生會話一同出現在 Replay 選擇器中。底層每個條目都透過 `mem::replay::load`、`mem::replay::sessions`、`mem::replay::import-jsonl` 這些 iii 函式路由 — 沒有側通道伺服器。
+
+### 升級 / 維護
+
+當你確實想更新本地執行階段時,使用維護指令:
+
+```bash
+npx @agentmemory/agentmemory upgrade
+```
+
+警告:此指令會變更目前工作區/執行階段。它可能更新 JavaScript 相依、可能執行 `cargo install iii-engine --force`、也可能拉取 Docker 鏡像。
+
+實作細節見 `src/cli.ts`(參考 `src/cli.ts:544-595` 附近的 `runUpgrade`)。
+
+### Claude Code(一段話,直接貼上)
+
+```text
+Install agentmemory: run `npx @agentmemory/agentmemory` 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, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 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.
+```
+
+#### Claude Code 不安裝外掛(MCP-standalone 路徑)
+
+若你直接透過 `~/.claude.json` 連接 agentmemory 的 MCP 伺服器而非使用 `/plugin install`,Claude Code 永遠不會解析 `${CLAUDE_PLUGIN_ROOT}`,你必須把 hook 腳本指向 `~/.claude/settings.json` 中的絕對路徑。這些路徑通常會嵌入 agentmemory 版本號(例如 `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`),因此下次升級會靜默破壞所有 hooks([#508](https://github.com/rohitg00/agentmemory/issues/508))。
+
+變通方法:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+這會把同樣的 hook 指令合併到 `~/.claude/settings.json`,絕對路徑解析到目前安裝的 `@agentmemory/agentmemory` 套件的 `plugin/` 目錄。升級 agentmemory 後重新執行該指令以重新整理路徑。同一檔案中的使用者條目會被保留;只取代之前的 agentmemory 條目。仍然推薦使用 `/plugin install` 路徑。
+
+對於遠端或受保護的部署,啟動 Claude Code 時設定 `AGENTMEMORY_URL` 和 `AGENTMEMORY_SECRET`。外掛會把這兩個值傳遞給其捆綁的 MCP 伺服器;當 `AGENTMEMORY_URL` 為空時,MCP shim 預設使用 `http://localhost:3111`。
+
+### Codex CLI(Codex 外掛平台)
+
+```bash
+# 1. 在另一個終端啟動記憶伺服器
+npx @agentmemory/agentmemory
+
+# 2. 註冊 agentmemory 市集並安裝外掛
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex 外掛與 Claude Code 外掛同源,來自相同的 `plugin/` 目錄。它註冊:
+
+- `@agentmemory/mcp` 作為 MCP 伺服器(當 `AGENTMEMORY_URL` 指向執行中的 agentmemory 伺服器時,代理全部 51 個工具;若伺服器不可達,本地回退至 7 個工具)
+- 6 個生命週期 hooks:`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PreCompact`、`Stop`
+- 4 個 skills:`/recall`、`/remember`、`/session-history`、`/forget`
+
+Codex 的 hook 引擎會把 `CLAUDE_PLUGIN_ROOT` 注入 hook 子行程(參見 [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)),因此同樣的 hook 腳本在兩個宿主中都能運作,無需重複實作。Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 事件僅 Claude Code 支援,Codex 未註冊這些。
+
+#### Codex Desktop:外掛 hooks 目前沒有回應(有變通方法)
+
+`CodexHooks` 和 `PluginHooks` 在 [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs) 中都已穩定且預設啟用,但 Codex Desktop 目前不會派發外掛本地的 `hooks.json`([openai/codex#16430](https://github.com/openai/codex/issues/16430))。MCP 工具仍能運作;只是生命週期觀測缺失。
+
+在上游修正落地前,把同樣的 hook 指令鏡像到全域 `~/.codex/hooks.json`:
+
+```bash
+agentmemory connect codex --with-hooks
+```
+
+這會在 `~/.codex/hooks.json` 新增一個冪等區塊,引用捆綁腳本的絕對路徑(在使用者範圍下無需 `${CLAUDE_PLUGIN_ROOT}` 展開)。升級 agentmemory 後重新執行同一指令以重新整理路徑。同一檔案中的使用者條目會被保留;只取代之前的 agentmemory 條目。
+
+<details>
+<summary><b>OpenClaw(貼上此提示)</b></summary>
+
+```text
+Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` 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 51 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`.
+```
+
+完整指南:[`integrations/openclaw/`](../integrations/openclaw/)
+
+</details>
+
+<details>
+<summary><b>Hermes Agent(貼上此提示)</b></summary>
+
+```text
+Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` 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 51 memory tools:
+
+mcp_servers:
+  agentmemory:
+    command: npx
+    args: ["-y", "@agentmemory/mcp"]
+
+memory:
+  provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+完整指南:[`integrations/hermes/`](../integrations/hermes/)
+
+</details>
+
+### 其他代理
+
+啟動記憶伺服器:`npx @agentmemory/agentmemory`
+
+在使用 `mcpServers` 結構的每個宿主(Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI、OpenClaw)中,agentmemory 條目是**相同的 MCP 伺服器區塊**:
+
+```json
+"agentmemory": {
+  "command": "npx",
+  "args": ["-y", "@agentmemory/mcp"],
+  "env": {
+    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+  }
+}
+```
+
+**把此條目合併到宿主設定檔現有的 `mcpServers` 物件中** — 不要取代整個檔案。若檔案已有其他伺服器,把 `agentmemory` 作為另一個 key 加在它們旁邊。若完全缺少 `mcpServers`,把整個區塊貼到 `{ "mcpServers": { ... } }` 裡。`${VAR}` 佔位符會在 MCP 伺服器啟動時從 shell 繼承 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` — 未設定的變數傳空字串,shim 回退到 `http://localhost:3111`。一個接好的條目同時涵蓋本地和遠端(k8s / 反向代理)部署。
+
+| 代理 | 設定檔 | 備註 |
+|---|---|---|
+| **Cursor** | `~/.cursor/mcp.json` | 合併到 `mcpServers`。網站上也提供一鍵深層連結。 |
+| **Claude Desktop** | `claude_desktop_config.json`(Application Support) | 合併到 `mcpServers`。編輯後重新啟動 Claude Desktop。 |
+| **Cline / Roo Code / Kilo Code** | Cline MCP 設定(設定 UI → MCP Servers → Edit) | 同樣的 `mcpServers` 區塊。 |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | 同樣的 `mcpServers` 區塊。 |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user`(自動合併)。 |
+| **OpenClaw** | OpenClaw MCP 設定 | 同樣的 `mcpServers` 區塊,或使用更深的[記憶外掛](../integrations/openclaw/)。 |
+| **Codex CLI(僅 MCP)** | `.codex/config.toml` | TOML 形式:`codex mcp add agentmemory -- npx -y @agentmemory/mcp`,或手動新增 `[mcp_servers.agentmemory]`。 |
+| **Codex CLI(完整外掛)** | Codex 外掛市集 | `codex plugin marketplace add rohitg00/agentmemory` 然後 `codex plugin add agentmemory@agentmemory`。註冊 MCP + 6 個生命週期 hooks(SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop)+ 4 個 skills。在 Codex Desktop 上,直到 [openai/codex#16430](https://github.com/openai/codex/issues/16430) 落地之前,還要執行 `agentmemory connect codex --with-hooks` — 那裡的外掛 hooks 目前沒有回應。 |
+| **OpenCode(僅 MCP)** | `opencode.json` | 不同結構 — 頂層 `mcp` key,command 是陣列:`{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`。 |
+| **OpenCode(完整外掛)** | `plugin/opencode/` | 22 個自動捕捉 hooks,涵蓋會話生命週期、訊息、工具、錯誤。兩個斜線指令(`/recall`、`/remember`)。把 `plugin/opencode/` 複製到你的 OpenCode 工作區並把外掛條目新增到 `opencode.json`。完整 hook 表與差異分析見 [`plugin/opencode/README.md`](../plugin/opencode/README.md)。 |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | 複製 [`integrations/pi`](../integrations/pi/) 並重啟 pi。 |
+| **Hermes Agent** | `~/.hermes/config.yaml` | 使用更深的[記憶提供者外掛](../integrations/hermes/),設定 `memory.provider: agentmemory`。 |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` 會寫入標準的 `mcpServers` 區塊。Hook 負載與 Claude Code 欄位相容,因此既有的 12 hook 腳本無需修改即可運作 — 透過同一 `settings.json` 的 `hooks` 區段連接它們。 |
+| **Antigravity**(取代 Gemini CLI) | `mcp_config.json`(在 Antigravity 的 User 目錄中) | `agentmemory connect antigravity` 會寫入標準的 `mcpServers` 區塊。macOS: `~/Library/Application Support/Antigravity/User/`。Linux: `~/.config/Antigravity/User/`。在 2026-06-18 Gemini CLI 停止服務後使用。 |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` 寫入使用者層級設定。工作區覆寫放在你的程式碼旁的 `.kiro/settings/mcp.json` 中。 |
+| **Goose** | Goose MCP 設定 UI | 同樣的 `mcpServers` 區塊。 |
+| **Aider** | n/a | 直接呼叫 REST API:`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
+| **任何代理(32+)** | n/a | `npx skillkit install agentmemory` 自動偵測宿主並合併。 |
+
+**沙箱化的 MCP 用戶端**(Flatpak / Snap / 受限容器)無法存取宿主的 `localhost`:還要在 `env` 區塊���設定 `"AGENTMEMORY_FORCE_PROXY": "1"`,並把 `AGENTMEMORY_URL` 指向沙箱確實能到達的路由(例如你的 LAN IP)。診斷步驟見 [#234](https://github.com/rohitg00/agentmemory/issues/234)。
+
+### 程式化存取(Python / Rust / Node)
+
+agentmemory 把核心操作註冊為 iii 函式(`mem::remember`、`mem::observe`、`mem::context`、`mem::smart-search`、`mem::forget`)。任何擁有 iii SDK 的語言都可以透過 `ws://localhost:49134` 直接呼叫它們 — 無需為每種語言準備獨立的 REST 用戶端。
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+完整範例:[`examples/python/`](../examples/python/)(快速開始 + 觀測/召回流程)。`:3111` 上的 REST 對沒有 iii 執行階段的宿主仍可用。
+
+### 從原始碼建置
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+若 `iii` 已安裝,這會以本地 `iii-engine` 啟動 agentmemory;若 Docker 可用,則回退到 Docker Compose。REST、串流和檢視器預設繫結到 `127.0.0.1`。
+
+手動安裝 `iii-engine`。**agentmemory 目前把 `iii-engine` 釘在 `v0.11.2`** — `v0.11.6` 引入了新的「透過 `iii worker add` 沙盒化一切」模型,agentmemory 尚未為此重構。重構落地後即解除釘版。若你已手動遷移到沙盒模型,可用 `AGENTMEMORY_III_VERSION=<version>` 覆寫。
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** 把 `aarch64-apple-darwin` 換成 `x86_64-apple-darwin`
+- **Linux x64:** 換成 `x86_64-unknown-linux-gnu`
+- **Linux arm64:** 換成 `aarch64-unknown-linux-gnu`
+- **Windows:** 從 [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2) 下載 `iii-x86_64-pc-windows-msvc.zip`,擷取 `iii.exe`,加入 PATH
+
+或使用 Docker(捆綁的 `docker-compose.yml` 會拉取 `iiidev/iii:0.11.2`)。完整文件:[iii.dev/docs](https://iii.dev/docs)。
+
+### Windows
+
+agentmemory 可在 Windows 10/11 執行,但僅 Node.js 套件不夠 — 你還需要 `iii-engine` 執行階段(一個獨立的原生二進位)作為背景行程。官方上游安裝器是 `sh` 指令稿,目前沒有 PowerShell 安裝器或 scoop/winget 套件,因此 Windows 使用者有兩條路徑:
+
+**選項 A — 預建 Windows 二進位(推薦):**
+
+```powershell
+# 1. 在瀏覽器打開 https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2
+#    (我們釘在 v0.11.2,直到 agentmemory 為 v0.11.6+ 引擎需求的
+#     新沙盒模型完成重構)
+# 2. 下載 iii-x86_64-pc-windows-msvc.zip
+#    (若是 ARM 機器則下載 iii-aarch64-pc-windows-msvc.zip)
+# 3. 把 iii.exe 解壓到 PATH 上的某處,或放在:
+#    %USERPROFILE%\.local\bin\iii.exe
+#    (agentmemory 會自動檢查該位置)
+# 4. 驗證:
+iii --version
+# 應輸出:0.11.2
+
+# 5. 然後照常執行 agentmemory:
+npx -y @agentmemory/agentmemory
+```
+
+**選項 B — Docker Desktop:**
+
+```powershell
+# 1. 安裝 Docker Desktop for Windows
+# 2. 啟動 Docker Desktop 並確保引擎執行中
+# 3. 執行 agentmemory — 它會自動啟動捆綁的 compose 檔:
+npx -y @agentmemory/agentmemory
+```
+
+**選項 C — 僅獨立 MCP(無引擎):** 若你只需要 MCP 工具供代理使用,不需要 REST API、檢視器或定時工作,則完全跳過引擎:
+
+```powershell
+npx -y @agentmemory/agentmemory mcp
+# 或透過 shim 套件:
+npx -y @agentmemory/mcp
+```
+
+**Windows 診斷:** 若 `npx @agentmemory/agentmemory` 失敗,加 `--verbose` 重新執行以看到實際的引擎 stderr。常見失敗模式:
+
+| 症狀 | 修正 |
+|---|---|
+| `iii-engine process started` 然後 `did not become ready within 15s` | 引擎啟動當機 — 用 `--verbose` 重新執行,檢查 stderr |
+| `Could not start iii-engine` | `iii.exe` 和 Docker 都未安裝。見上面選項 A 或 B |
+| 連接埠衝突 | `netstat -ano \| findstr :3111` 查看佔用,然後 kill 或用 `--port <N>` |
+| Docker 已安裝但仍跳過回退 | 確保 Docker Desktop 確實在執行(系統匣圖示) |
+
+> 注意:沒有 `cargo install iii-engine` — `iii` 未發布到 crates.io。唯一受支援的安裝方式是上述預建二進位、上游 `sh` 安裝指令稿(僅 macOS/Linux)和 Docker 鏡像。
+
+---
+
+<h2 id="deploy">部署</h2>
+
+託管主機的一鍵範本。每個範本都附帶自含的
+Dockerfile,從 npm 拉取 `@agentmemory/agentmemory` 並從官方
+`iiidev/iii` Docker Hub 鏡像複製 iii 引擎二進位 — 無需
+預建 agentmemory 鏡像。持久儲存掛載在
+`/data`;首次啟動 entrypoint 用面向部署調校的設定
+覆寫 npm 捆綁的 iii ���定(原設定繫結 `127.0.0.1`),
+讓其繫結 `0.0.0.0` 並使用絕對 `/data` 路徑,產生
+HMAC secret,然後透過 `gosu` 從 `root` 降權到 `node`
+再 exec agentmemory CLI。
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render 的一鍵部署按鈕要求倉庫根有 `render.yaml`,我們刻意保持根目錄整潔。使用 [`deploy/render/`](../deploy/render/README.md) 中文件化的 Render Blueprint 流程,手動指向倉庫內的藍圖。
+
+完整設定細節(HMAC 擷取、檢視器 SSH 隧道、輪替、備份、
+成本下限)見 [`deploy/`](../deploy/README.md):
+
+- [`deploy/fly`](../deploy/fly/README.md) — 單機搭配
+  `auto_stop_machines = "stop"`;閒置時最便宜。
+- [`deploy/railway`](../deploy/railway/README.md) — Hobby 方案固定費,
+  磁碟區在儀表板中設定。
+- [`deploy/render`](../deploy/render/README.md) — Blueprint 流程,
+  付費方案自動磁碟快照。
+- [`deploy/coolify`](../deploy/coolify/README.md) — 透過 [Coolify](https://coolify.io/self-hosted)
+  在你自己的 VPS 上自架;同樣的 Docker
+  Compose 堆疊,主機與資料都歸你所有。
+
+僅發布連接埠 `3111`。`3113` 上的檢視器在容器內仍繫結到
+loopback — 每個範本的 README 都文件化了到達它的
+SSH 隧道模式。
+
+---
+
+<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
+
+每個編碼代理在會話結束時都會忘記一切。你每次會話的前 5 分鐘都浪費在重新解釋技術堆疊上。agentmemory 在背景執行,徹底消除這一點。
+
+```text
+Session 1: "Add auth to the API"
+  Agent writes code, runs tests, fixes bugs
+  agentmemory silently captures every tool use
+  Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+  Agent already knows:
+    - Auth uses JWT middleware in src/middleware/auth.ts
+    - Tests in test/auth.test.ts cover token validation
+    - You chose jose over jsonwebtoken for Edge compatibility
+  Zero re-explaining. Starts working immediately.
+```
+
+### 對比內建代理記憶
+
+每個 AI 編碼代理都自帶內建記憶 — Claude Code 有 `MEMORY.md`、Cursor 有 notepad、Cline 有 memory bank。這些像便利貼。agentmemory 是便利貼背後的可搜尋資料庫。
+
+| | 內建 (CLAUDE.md) | agentmemory |
+|---|---|---|
+| 規模 | 200 行上限 | 無限 |
+| 搜尋 | 把所有內容載入上下文 | BM25 + 向量 + 圖(僅 top-K) |
+| Token 成本 | 240 條觀測達 22K+ | ~1,900 tokens(少 92%) |
+| 跨代理 | 每個代理一個檔案 | MCP + REST(任何代理) |
+| 協調 | 無 | 租約、訊號、動作、例程 |
+| 可觀測性 | 手動讀檔 | 連接埠 3113 即時檢視器 |
+
+---
+
+<h2 id="how-it-works"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-how.svg"><img src="../assets/tags/section-how.svg" alt="How It Works" height="32" /></picture></h2>
+
+### 記憶流水線
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Vector embedding (6 providers + local)
+  -> Index in BM25 + vector
+
+Stop / SessionEnd hook fires
+  -> Summarize session
+  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph)
+  -> Token budget (default: 2000 tokens)
+  -> Inject into conversation
+```
+
+### 4 層記憶整合
+
+靈感來自人腦處理記憶的方式 — 與睡眠時的記憶整合並無不同。
+
+| 層級 | 內容 | 類比 |
+|------|------|---------|
+| **Working(工作記憶)** | 來自工具使用的原始觀測 | 短期記憶 |
+| **Episodic(情節記憶)** | 壓縮後的會話摘要 | 「發生了什麼」 |
+| **Semantic(語意記憶)** | 擷取的事實與模式 | 「我知道什麼」 |
+| **Procedural(程序記憶)** | 工作流與決策模式 | 「怎麼做」 |
+
+記憶隨時間衰減(Ebbinghaus 曲線)。頻繁存取的記憶會強化。陳舊記憶會自動清除。矛盾會被偵測並解決。
+
+### 捕捉了什麼
+
+| Hook | 捕捉內容 |
+|------|----------|
+| `SessionStart` | 專案路徑、會話 ID |
+| `UserPromptSubmit` | 使用者提示(隱私過濾) |
+| `PreToolUse` | 檔案��取模式 + 富化上下文 |
+| `PostToolUse` | 工具名、輸入、輸出 |
+| `PostToolUseFailure` | 錯誤上下文 |
+| `PreCompact` | 在壓縮前重新注入記憶 |
+| `SubagentStart/Stop` | 子代理生命週期 |
+| `Stop` | 會話結束摘要 |
+| `SessionEnd` | 會話完成標記 |
+
+### 關鍵能力
+
+| 能力 | 描述 |
+|---|---|
+| **自動捕捉** | 每次工具使用都透過 hooks 記錄 — 零人工 |
+| **語意搜尋** | BM25 + 向量 + 知識圖譜,RRF 融合 |
+| **記憶演化** | 版本控制、覆寫關係、關係圖 |
+| **自動遺忘** | TTL 過期、矛盾偵測、重要性驅逐 |
+| **隱私優先** | API key、secret、`<private>` 標籤儲存前被剝除 |
+| **自癒** | 熔斷器、提供者回退鏈、健康監控 |
+| **Claude 橋接** | 與 MEMORY.md 雙向同步 |
+| **知識圖譜** | 實體擷取 + BFS 走訪 |
+| **團隊記憶** | 團隊成員之間的命名空間共享 + 私有 |
+| **引用溯源** | 任意記憶追溯到來源觀測 |
+| **Git 快照** | 記憶狀態的版本、回滾、diff |
+
+---
+
+<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-search.svg"><img src="../assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
+
+三路檢索結合三種訊號:
+
+| 流 | 功用 | 何時啟用 |
+|---|---|---|
+| **BM25** | 詞幹化關鍵字比對 + 同義詞擴展 | 始終啟用 |
+| **Vector(向量)** | 稠密嵌入上的餘弦相似度 | 已設定嵌入提供者 |
+| **Graph(圖)** | 透過實體比對進行知識圖譜走訪 | 查詢中偵測到實體 |
+
+透過 Reciprocal Rank Fusion (RRF, k=60) 融合,並按會話多樣化(每個會話最多 3 個結果)。
+
+BM25 開箱即用支援希臘文、西里爾文、希伯來文、阿拉伯文和帶音標拉丁文的分詞。對於中文/日文/韓文記憶,安裝可選分詞器(`npm install @node-rs/jieba tiny-segmenter`)以把 CJK 串切分為詞級 token;若未安裝,agentmemory 會軟回退到整串分詞並在 stderr 印出一次性提示。
+
+### 嵌入提供者
+
+agentmemory 自動偵測你的提供者。為獲得最佳效果,安裝本地嵌入(免費):
+
+```bash
+npm install @xenova/transformers
+```
+
+| 提供者 | 模型 | 成本 | 備註 |
+|---|---|---|---|
+| **本地(推薦)** | `all-MiniLM-L6-v2` | 免費 | 離線,比僅 BM25 召回率高 +8pp |
+| Gemini | `gemini-embedding-001` | 免費層 | 100+ 語言,768/1536/3072 維 (MRL),2048-token 輸入。取代 `text-embedding-004`([已棄用,2026 年 1 月 14 日下線](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | 最高品質 |
+| Voyage AI | `voyage-code-3` | 付費 | 針對程式碼最佳化 |
+| Cohere | `embed-english-v3.0` | 免費試用 | 通用 |
+| OpenRouter | 任意模型 | 視情況 | 多模型代理 |
+
+---
+
+<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-mcp.svg"><img src="../assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>
+
+53 個工具、6 個資源、3 個提示、4 個 skills — 任何代理可用的最全面 MCP 記憶工具組。
+
+> **MCP shim 對比完整伺服器:** 已發布的 `@agentmemory/mcp` 套件是一個薄 shim。**只有當它能透過 `AGENTMEMORY_URL` 連通執行中的 agentmemory 伺服器**(代理模式)時,才暴露完整的 51 工具表面。在沒有可達伺服器的情況下,shim 回退到 7 工具的本地集合(`memory_save`、`memory_recall`、`memory_smart_search`、`memory_sessions`、`memory_export`、`memory_audit`、`memory_governance_delete`)。`AGENTMEMORY_TOOLS=core|all` 環境變數是*伺服器端*旗標 — 在 shim 的 `env` 區塊中設定無效。若在 Cursor / OpenCode / Gemini CLI 中只看到 7 個工具,啟動 `npx @agentmemory/agentmemory`(或 Docker 堆疊)並設定 `AGENTMEMORY_URL=http://localhost:3111`。
+
+### 51 個工具
+
+<details>
+<summary>核心工具(始終可用)</summary>
+
+| 工具 | 描述 |
+|------|-------------|
+| `memory_recall` | 搜尋過去的觀測 |
+| `memory_compress_file` | 在保留結構的同時壓縮 markdown 檔 |
+| `memory_save` | 儲存洞察、決策或模式 |
+| `memory_patterns` | 偵測反覆出現的模式 |
+| `memory_smart_search` | 混合語意 + 關鍵字搜尋 |
+| `memory_file_history` | 關於特定檔案的過去觀測 |
+| `memory_sessions` | 列出最近的會話 |
+| `memory_timeline` | 按時間排列的觀測 |
+| `memory_profile` | 專案檔案(概念、檔案、模式) |
+| `memory_export` | 匯出所有記憶資料 |
+| `memory_relations` | 查詢關係圖 |
+
+</details>
+
+<details>
+<summary>擴展工具(共 51 — 設定 AGENTMEMORY_TOOLS=all)</summary>
+
+| 工具 | 描述 |
+|------|-------------|
+| `memory_patterns` | 偵測反覆出現的模式 |
+| `memory_timeline` | 按時間排列的觀測 |
+| `memory_relations` | 查詢關係圖 |
+| `memory_graph_query` | 知識圖譜走訪 |
+| `memory_consolidate` | 執行 4 層整合 |
+| `memory_claude_bridge_sync` | 與 MEMORY.md 同步 |
+| `memory_team_share` | 與團隊成員共享 |
+| `memory_team_feed` | 最近共享條目 |
+| `memory_audit` | 操作稽核軌跡 |
+| `memory_governance_delete` | 帶稽核軌跡的刪除 |
+| `memory_snapshot_create` | Git 版本快照 |
+| `memory_action_create` | 建立帶相依性的工作項 |
+| `memory_action_update` | 更新動作狀態 |
+| `memory_frontier` | 依優先序排序的未阻塞動作 |
+| `memory_next` | 單一最重要的下一個動作 |
+| `memory_lease` | 獨佔動作租約(多代理) |
+| `memory_routine_run` | 實例化工作流例程 |
+| `memory_signal_send` | 代理之間的訊息 |
+| `memory_signal_read` | 帶回執讀取訊息 |
+| `memory_checkpoint` | 外部條件閘門 |
+| `memory_mesh_sync` | 實例之間 P2P 同步 |
+| `memory_sentinel_create` | 事件驅動監視器 |
+| `memory_sentinel_trigger` | 外部觸發哨兵 |
+| `memory_sketch_create` | 暫時動作圖 |
+| `memory_sketch_promote` | 提升為永久 |
+| `memory_crystallize` | 緊湊化動作鏈 |
+| `memory_diagnose` | 健康檢查 |
+| `memory_heal` | 自動修復卡住的狀態 |
+| `memory_facet_tag` | 維度:值 標籤 |
+| `memory_facet_query` | 依 facet 標籤查詢 |
+| `memory_verify` | 追溯來源 |
+
+</details>
+
+### 6 個資源 · 3 個提示 · 4 個 Skills
+
+| 類型 | 名稱 | 描述 |
+|------|------|-------------|
+| Resource | `agentmemory://status` | 健康、會話數、記憶數 |
+| Resource | `agentmemory://project/{name}/profile` | 專案層級智慧 |
+| Resource | `agentmemory://memories/latest` | 最新 10 條活躍記憶 |
+| Resource | `agentmemory://graph/stats` | 知識圖譜統計 |
+| Prompt | `recall_context` | 搜尋並回傳上下文訊息 |
+| Prompt | `session_handoff` | 代理之間的交接資料 |
+| Prompt | `detect_patterns` | 分析反覆出現的模式 |
+| Skill | `/recall` | 搜尋記憶 |
+| Skill | `/remember` | 儲存到長期記憶 |
+| Skill | `/session-history` | 最近的會話摘要 |
+| Skill | `/forget` | 刪除觀測/會話 |
+
+### 獨立 MCP
+
+無需完整伺服器即可執行 — 適用於任何 MCP 用戶端。以下兩種都可以:
+
+```bash
+npx -y @agentmemory/agentmemory mcp   # 標準指令(始終可用)
+npx -y @agentmemory/mcp                # shim 套件別名
+```
+
+或新增到你的代理的 MCP 設定:
+
+大多數代理(Cursor、Claude Desktop、Cline、Roo Code、Windsurf、Gemini CLI):
+```json
+{
+  "mcpServers": {
+    "agentmemory": {
+      "command": "npx",
+      "args": ["-y", "@agentmemory/mcp"],
+      "env": {
+        "AGENTMEMORY_URL": "http://localhost:3111"
+      }
+    }
+  }
+}
+```
+
+把 `agentmemory` 條目合併到你的宿主既有的 `mcpServers` 物件中,而非取代檔案。對於無法存取宿主 `localhost` 的沙箱用戶端,在 env 區塊中加入 `"AGENTMEMORY_FORCE_PROXY": "1"`,並把 `AGENTMEMORY_URL` 設為沙箱能到達的路由。
+
+OpenCode (`opencode.json`):
+```json
+{
+  "mcp": {
+    "agentmemory": {
+      "type": "local",
+      "command": ["npx", "-y", "@agentmemory/mcp"],
+      "enabled": true
+    }
+  },
+  "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+從倉庫複製外掛檔:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
+
+在連接埠 `3113` 自動啟動。即時觀測流、會話瀏覽器、記憶瀏覽器、知識圖譜視覺化和健康儀表板。
+
+```bash
+open http://localhost:3113
+```
+
+檢視器伺服器預設繫結 `127.0.0.1`。REST 提供的 `/agentmemory/viewer` 端點遵循正常的 `AGENTMEMORY_SECRET` bearer-token 規則。CSP 標頭使用每回應 script nonce 並停用行內處理常式屬性(`script-src-attr 'none'`)。
+
+---
+
+<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
+
+`:3113` 上的檢視器展示你的代理**記住了什麼**。[iii 主控台](https://iii.dev/docs/console) 展示你的代理**做了什麼** — 每個記憶操作都是 OpenTelemetry trace,每個 KV 條目都可編輯,每個函式都可呼叫,每個串流都可掛載。同一記憶的兩個視窗:一個面向產品,一個面向引擎。
+
+觀察一次 `memory_smart_search` 觸發,在瀑布圖中看到 BM25 掃描 → 嵌入查找 → RRF 融合 → 重新排序器。在 KV 瀏覽器中編輯卡住的整合計時器。用調整後的負載重播一個 `PostToolUse` hook。釘選 WebSocket 串流,即時觀察觀測落地。
+
+agentmemory 免費提供這一切,因為每個函式、觸發器、狀態範圍、串流都是 iii 原語 — 沒有自訂、沒有需要插樁的地方。
+
+<p align="center">
+  <img src="../assets/iii-console/workers.png" alt="iii console Workers page — connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
+  <br/>
+  <em>Workers 頁面:每個已連接 worker — 包括 agentmemory 本身 — 顯示 PID、函式數、執行階段和最後在線時間。</em>
+</p>
+
+**已經裝好了。** 主控台隨 `iii` 一同發布 — 無需獨立安裝器。
+
+**與 agentmemory 並行啟動:**
+
+```bash
+# agentmemory 檢視器佔用連接埠 3113,所以在 3114 執行主控台。
+# 引擎 REST (3111)、WebSocket (3112)、bridge (49134) 預設值與 agentmemory 相符。
+iii console --port 3114
+```
+
+然後打開 `http://localhost:3114`。加 `--enable-flow` 開啟實驗性架構圖頁面。
+
+僅在你已移動引擎端點時才覆寫:
+
+```bash
+iii console --port 3114 \
+  --engine-port 3111 \
+  --ws-port 3112 \
+  --bridge-port 49134
+```
+
+**主控台能做什麼:**
+
+| 頁面 | 用途 |
+|------|-----------|
+| **Workers** | 查看每個已連接 worker 及其即時指標 — 包括 agentmemory worker 本身。 |
+| **Functions** | 直接以 JSON 負載呼叫 agentmemory 的任何函式 — 測試 `memory.recall`、`memory.consolidate`、`graph.query` 無需接入用戶端。 |
+| **Triggers** | 重播 HTTP、cron、事件和狀態觸發器 — 手動觸發整合 cron、重試 HTTP 路由、發出狀態變更。 |
+| **States** | 完整 CRUD 的 KV 瀏覽器 — 會話、記憶槽位、生命週期計時器、嵌入索引 — 就地編輯值。 |
+| **Streams** | 記憶寫入、hook 事件和觀測更新流經 iii 串流時的即時 WebSocket 監視器。 |
+| **Queues** | 持久佇列主題 + 死信管理。重播或捨棄失敗的嵌入/壓縮工作。 |
+| **Traces** | OpenTelemetry 瀑布/火焰/服務分解視圖。按 `trace_id` 過濾,精確查看單次 `memory.search` 產生了哪些函式、DB 呼叫和嵌入請求。 |
+| **Logs** | 結構化 OTEL 日誌,過濾並與 trace/span ID 關聯。 |
+| **Config** | 執行階段設定 — 看到引擎正在使用的 workers、提供者和連接埠。 |
+| **Flow** | (選用,`--enable-flow`)每個 worker、觸發器和串流的互動式架構圖。 |
+
+<p align="center">
+  <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
+  <br/>
+  <em>Traces:每個記憶操作的瀑布/火焰/服務分解。</em>
+</p>
+
+**Traces 已開啟:**
+
+`iii-config.yaml` 出廠啟用 `iii-observability` worker(`exporter: memory`、`sampling_ratio: 1.0`、指標 + 日誌)。無需額外設定 — agentmemory 啟動那一刻,每個記憶操作都會發出一個 trace span 和一個主控台可讀的結構化日誌。
+
+若你想改為匯出到 Jaeger/Honeycomb/Grafana Tempo,把 `exporter: memory` 改為 `exporter: otlp` 並依 iii 的可觀測性文件設定收集器端點。
+
+> **提醒:** 主控台本身未強制驗證 — 保持其繫結 `127.0.0.1`(預設)並永遠不要對外暴露。
+
+---
+
+<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
+
+agentmemory **本身就是一個執行中的 [iii](https://iii.dev) 實例**。函式、觸發器、KV 狀態、串流、OTEL traces — 全部都是 iii 原語。你沒有安裝 Postgres、Redis、Express、pm2 或 Prometheus,因為 iii 取代了它們。
+
+這代表多一條指令就能為 agentmemory 增加一整套新能力。
+
+### 一條指令擴展 agentmemory
+
+```bash
+iii worker add iii-pubsub          # 把記憶寫入扇出到每個連接的實例
+iii worker add iii-cron            # 排程整合、衰減掃描、快照輪替
+iii worker add iii-queue           # 嵌入 + 壓縮工作的持久重試
+iii worker add iii-observability   # 每個記憶操作的 OTEL traces(預設開啟)
+iii worker add iii-sandbox         # 在隔離 microVM 內執行召回到的程式碼
+iii worker add iii-database        # 切換 SQL 後端的狀態適配器
+iii worker add mcp                 # 在 agentmemory 的 MCP 旁開設通用 MCP 宿主
+```
+
+每個 `iii worker add` 都會把新的函式和觸發器註冊到 agentmemory 正在執行的同一引擎中。檢視器和主控台立即接收 — 無需重新載入、無需新整合、無需新容器。
+
+| `iii worker add` | 在 agentmemory 上獲得的額外能力 |
+|---|---|
+| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | 多實例記憶:每次 `remember` 扇出,每次 `search` 讀取聯集 |
+| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | 排程生命週期 — 夜間整合、週快照、按固定時鐘衰減 |
+| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | 持久重試:失敗的嵌入 + 壓縮工作在重啟後存活,無觀測遺失 |
+| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | 每個函式的 OTEL traces、指標、日誌 — 從第一天起就接入 `iii-config.yaml` |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` 出來的程式碼在一次性 VM 中執行,不在你的 shell 中 |
+| [`iii-database`](https://workers.iii.dev/workers/iii-database) | 當預設的記憶體 KV 不夠用時,SQL 後端狀態適配器 |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | 在 agentmemory 的旁邊架設額外 MCP 伺服器,共享同一引擎 |
+
+完整登錄表:[workers.iii.dev](https://workers.iii.dev)。那裡的每個 worker 都透過 agentmemory 所用的同樣原語組合 — 而你已經擁有的 agentmemory 本身就是其中之一。
+
+### iii 取代了什麼
+
+| 傳統堆疊 | agentmemory 使用 |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + 記憶體向量索引 |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker 監管 |
+| Prometheus / Grafana | iii OTEL + 健康監控 |
+| 自訂外掛系統 | `iii worker add <name>` |
+
+**118 個原始檔 · ~21,800 行程式碼 · 950+ 測試 · 123 個函式 · 34 個 KV 範圍** — 全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
+
+---
+
+<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
+
+### LLM 提供者
+
+agentmemory 從你的環境自動偵測。預設情況下,除非你設定提供者或明確啟用 Claude 訂閱回退,否則不會發起 LLM 呼叫。
+
+| 提供者 | 設定 | 備註 |
+|----------|--------|-------|
+| **No-op(預設)** | 無需設定 | LLM 驅動的 compress/summarize 被停用。合成 BM25 壓縮 + 召回仍可用。若你以前依賴 Claude 訂閱回退,請見下面的 `AGENTMEMORY_ALLOW_AGENT_SDK`。 |
+| Anthropic API | `ANTHROPIC_API_KEY` | 依 token 計費 |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic 相容 |
+| Gemini | `GEMINI_API_KEY` | 同時啟用嵌入 |
+| OpenRouter | `OPENROUTER_API_KEY` | 任意模型 |
+| Claude 訂閱回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 僅按需啟用。會衍生 `@anthropic-ai/claude-agent-sdk` 會話 — 曾導致無限 Stop-hook 遞迴(#149 後續)故不再預設。 |
+
+### 成本感知的模型選擇
+
+背景壓縮在每次觀測時執行,模型選擇會顯著影響月支出。擷取的工作負載資料:635 次請求 / 888K tokens / 35 小時活躍使用,基於 2026-05-23 OpenRouter 定價對三個模型評測。
+
+| 等級 | 模型 | 輸入 / 1M | 輸出 / 1M | 35 小時擷取工作負載成本 | 備註 |
+|------|-------|------------|-------------|---------------------------|-------|
+| 推薦 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | 壓縮 + 摘要品質穩定,比 Sonnet 便宜 ~10×。 |
+| 推薦 | `deepseek/deepseek-chat` | $0.27 | $1.10 | ~$0.40 | 略舊但仍勝任僅壓縮工作負載。 |
+| 推薦 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 若你的會話多為程式碼,程式碼推理能力強。 |
+| 高階 | `anthropic/claude-sonnet-4.6` | $3.00 | $15.00 | ~$5.02 | 品質高但對長期背景工作來說成本昂貴。 |
+| 高階 | `openai/gpt-4o` | $2.50 | $10.00 | ~$4.20 | 與 Sonnet 同檔。 |
+| 避免 | `anthropic/claude-opus-4.6` | $15.00 | $75.00 | ~$25+ | 推理級模型;用於壓縮屬於巨額超支。 |
+
+當 `OPENROUTER_MODEL` 比對高階層模式時,agentmemory 會印出執行階段警告。在做出知情選擇後,設定 `AGENTMEMORY_SUPPRESS_COST_WARNING=1` 來消音。
+
+記憶工作的品質-成本權衡:壓縮是品質門檻相對寬鬆的摘要任務(代理重新閱讀摘要,而非使用者)。DeepSeek-V4-Pro / Qwen3-Coder 在該任務上與 Sonnet 誤差極小,而成本約低 10×。把高階層模型留給你直接閱讀的查詢。
+
+來源:[OpenRouter Sonnet 4.6 定價](https://openrouter.ai/anthropic/claude-sonnet-4.6/pricing)、[DeepSeek V4 Pro](https://openrouter.ai/deepseek/deepseek-v4-pro)、[DeepSeek 定價說明](https://api-docs.deepseek.com/quick_start/pricing/)。
+
+### 多代理記憶(`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+在多個角色共享一台 agentmemory 伺服器的多代理設置中(architect / developer / reviewer / researcher / support-agent),`AGENT_ID` 給每次寫入打上發起角色的標籤。`AGENTMEMORY_AGENT_SCOPE` 控制召回是否依該標籤過濾。
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated  # 選填;預設 "shared"
+```
+
+兩種模式:
+
+| 模式 | 標記寫入 | 過濾召回 | 何時使用 |
+|------|------------|---------------|-------------|
+| `shared`(預設) | 是 | 否 | 跨代理共享上下文且帶稽核軌跡。Architect 能看到 developer 記下了什麼,但每條記錄都標明發言者。 |
+| `isolated` | 是 | 是 | 嚴格隔離。Architect 永遠不會看到 developer 的觀測/記憶/會話。 |
+
+設定 `AGENT_ID` 後會被標記的內容:`Session.agentId`、`RawObservation.agentId`、`CompressedObservation.agentId`、`Memory.agentId`。角色從 `api::session::start` → `mem::observe` → `mem::compress` → KV 流轉。
+
+isolated 模式下被過濾的內容:`mem::smart-search`、`/agentmemory/memories`、`/agentmemory/observations`、`/agentmemory/sessions`。每個端點都接受 `?agentId=<role>` 來依請求覆寫,以及 `?agentId=*` 來完全跳過環境範圍。`/memories` 還接受 `?includeOrphans=true` 來浮現 `agentId` 為 undefined 的 pre-AGENT_ID 記憶。
+
+SDK / REST 層的依呼叫覆寫:每個變更端點(`/session/start`、`/remember`)都接受請求體中的 `agentId` 欄位,勝過環境變數。對於在一個伺服器行程中路由多角色的執行階段很有用。
+
+當 `AGENT_ID` 未設定時,記憶保持無範圍(舊行為,無標籤、無過濾)。
+
+### 連接埠
+
+agentmemory + iii-engine 預設繫結四個連接埠。若重啟失敗並顯示 `port in use`,這張表告訴你該查找什麼行程。
+
+| 連接埠 | 行程 | 用途 | 環境覆寫 |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | 內部串流 worker(由 agentmemory + 檢視器消費) | `III_STREAMS_PORT` |
+| `3113` | agentmemory | 即時檢視器(`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
+| `49134` | iii-engine | WebSocket — workers 在此註冊,OTel 遙測在此流過 | `III_ENGINE_URL`(完整 URL,預設 `ws://localhost:49134`) |
+
+當機後連接埠仍被佔用時的陳舊行程清理:
+
+```bash
+# macOS / Linux — 找出每個連接埠上的行程並 kill 掉
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID <pid>
+```
+
+`agentmemory stop` 在優雅關閉時乾淨地回收 worker 和 engine pidfile(#640、#474)。上述手動清理僅針對當機後兩個 pidfile 都未留下的情況。
+
+### 設定檔
+
+把 agentmemory 執行階段設定放到 `~/.agentmemory/.env`,而非在每個 shell 中 export 變數。若檢視器顯示像 `export ANTHROPIC_API_KEY=...` 這樣的設定提示,把它複製到該檔案作為 `ANTHROPIC_API_KEY=...`(去掉 `export` 前綴),然後重啟 agentmemory。
+
+行程環境變數仍然有效,優先序高於檔案中的值。
+
+在 Windows 上,同一檔案位於 `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+要用 Claude Code Pro/Max 訂閱而非 API key 測試,明確啟用:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+若想開啟圖或整合特性,在同一檔案中打開:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+CONSOLIDATION_ENABLED=true
+```
+
+### 環境變數
+
+建立 `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=...              # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=***                       # NOTE: this same key auto-activates BOTH the
+#                                          # OpenAI LLM provider (here) AND the OpenAI
+#                                          # embedding provider (further below). Set
+#                                          # OPENAI_API_KEY_FOR_LLM=false to scope it
+#                                          # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com   # Optional: override for Azure / vLLM / LM Studio / proxies
+#                                          # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
+#                                          # Auto-detected from `.openai.azure.com` hostname; uses
+#                                          # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview    # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-4o-mini                 # Optional: default model
+# OPENAI_TIMEOUT_MS=60000                  # Optional: OpenAI-scoped alias for the outbound fetch
+#                                          # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+#                                          # for back-compat with v0.9.17. New configs should
+#                                          # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none             # Optional: "low" | "medium" | "high" | "none"
+#                                          # Honored only by OpenAI's reasoning models (o1, o3,
+#                                          # gpt-*-reasoning) and providers that mirror that
+#                                          # schema (Ollama Cloud thinking models). Standard
+#                                          # chat models reject this field with 400. Set to
+#                                          # "none" for thinking models that return reasoning
+#                                          # but no content.
+# OPENAI_API_KEY_FOR_LLM=false             # Optional: set to false to skip OpenAI auto-detection
+#                                          # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk (#149 follow-up):
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (auto-detected, or override)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com   # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536        # Required when the model is not in the known-models table
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000       # Default: 60 000 ms (60 s). Applies to every
+                                          # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+                                          # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+                                          # embedding). For the OpenAI LLM path, the
+                                          # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+                                          # takes precedence when set, for back-compat
+                                          # with v0.9.17.
+                                          # Increase for slow networks or large batch calls;
+                                          # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth
+# AGENTMEMORY_SECRET=your-secret
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false  # OFF by default (#138). When on,
+                                   # every PostToolUse hook calls your
+                                   # LLM provider to compress the
+                                   # observation — expect significant
+                                   # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false          # OFF by default. Editable pinned
+                                   # memory slots — persona,
+                                   # user_preferences, tool_guidelines,
+                                   # project_context, guidance,
+                                   # pending_items, session_patterns,
+                                   # self_notes. Size-limited; agent
+                                   # edits via memory_slot_* tools.
+                                   # Pinned slots addressable for
+                                   # SessionStart injection.
+# AGENTMEMORY_REFLECT=false        # OFF by default. Requires SLOTS=on.
+                                   # Stop hook fires mem::slot-reflect:
+                                   # scans recent observations, auto-
+                                   # appends TODOs to pending_items,
+                                   # counts patterns in
+                                   # session_patterns, records touched
+                                   # files in project_context. Fire-
+                                   # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default (#143). When on:
+                                   # - SessionStart may inject ~1-2K
+                                   #   chars of project context into
+                                   #   the first turn of each session
+                                   #   (this is what actually reaches
+                                   #   the model — Claude Code treats
+                                   #   SessionStart stdout as context)
+                                   # - PreToolUse fires /agentmemory/enrich
+                                   #   on every file-touching tool call
+                                   #   (resource cleanup, not a token
+                                   #   fix — PreToolUse stdout is debug
+                                   #   log only per Claude Code docs)
+                                   # Observations are still captured via
+                                   # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# CONSOLIDATION_ENABLED=true
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "core" (8 tools) or "all" (51 tools)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
+
+連接埠 `3111` 上的 124 個端點。REST API 預設繫結 `127.0.0.1`。當 `AGENTMEMORY_SECRET` 已設定時,受保護端點需要 `Authorization: Bearer <secret>`,網狀同步端點要求兩端都設定 `AGENTMEMORY_SECRET`。
+
+<details>
+<summary>關鍵端點</summary>
+
+| 方法 | 路徑 | 描述 |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | 健康檢查(始終公開) |
+| `POST` | `/agentmemory/session/start` | 開始會話 + 取得上下文 |
+| `POST` | `/agentmemory/session/end` | 結束會話 |
+| `POST` | `/agentmemory/observe` | 擷取觀測 |
+| `POST` | `/agentmemory/smart-search` | 混合搜尋 |
+| `POST` | `/agentmemory/context` | 產生上下文 |
+| `POST` | `/agentmemory/remember` | 儲存到長期記憶 |
+| `POST` | `/agentmemory/forget` | 刪除觀測 |
+| `POST` | `/agentmemory/enrich` | 檔案上下文 + 記憶 + bugs |
+| `GET` | `/agentmemory/profile` | 專案檔案 |
+| `GET` | `/agentmemory/export` | 匯出所有資料 |
+| `POST` | `/agentmemory/import` | 從 JSON 匯入 |
+| `POST` | `/agentmemory/graph/query` | 知識圖譜查詢 |
+| `POST` | `/agentmemory/team/share` | 與團隊共享 |
+| `GET` | `/agentmemory/audit` | 稽核軌跡 |
+
+完整端點列表:[`src/triggers/api.ts`](../src/triggers/api.ts)
+
+</details>
+
+---
+
+<h2 id="development"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-development.svg"><img src="../assets/tags/section-development.svg" alt="Development" height="32" /></picture></h2>
+
+```bash
+npm run dev               # 熱重新載入
+npm run build             # 生產建置
+npm test                  # 950+ 測試
+npm run test:integration  # API 測試(需要服務執行中)
+```
+
+**先決條件:** Node.js >= 20、[iii-engine](https://iii.dev/docs) 或 Docker
+
+<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
+
+[Apache-2.0](../LICENSE)

ROADMAP.md

@@ -0,0 +1,92 @@
+# Roadmap
+
+This is agentmemory's public 12-month roadmap. It covers Q2 2026 through Q1 2027. The roadmap is the source of truth for where the project is heading; anything significant that lands in main should trace back to an item here or a ratified issue.
+
+Items shift as evidence changes. Each quarter we publish a short retrospective on what landed, what slipped, and why — attached to the release notes.
+
+## How to read this
+
+- **Shipped** — landed in main and tagged in a release.
+- **Active** — in-flight, has an open PR or issue owner.
+- **Planned** — accepted scope for the quarter, not started.
+- **Candidate** — under consideration, may defer.
+
+Anything not on this list that a contributor wants to pursue is welcome — open an issue labeled `roadmap` and it gets triaged against the quarterly theme.
+
+## Themes
+
+- **Q2 2026 — Depth.** Multimodal memory, more connectors, close out backlog from the v0.9 cycle.
+- **Q3 2026 — Breadth.** Hook parity across more agents, community expansion, OpenSSF best-practices alignment.
+- **Q4 2026 — Trust.** Enterprise features — SSO, audit export, RBAC, long-running deployment story.
+- **Q1 2027 — v1.0.** Stability, LTS branch, semver freeze on the REST + MCP surface.
+
+## Q2 2026 — Depth (April – June)
+
+### Shipped so far in this quarter
+- [x] iii console docs in README with vendored screenshots (#157)
+- [x] Health severity gated on RSS floor (#158 / PR #160)
+- [x] Standalone MCP proxies to the running server (#159 / PR #161)
+- [x] Audit coverage for `mem::forget` + audit policy doc (#125 / PR #162)
+- [x] `@agentmemory/fs-watcher` filesystem connector (#62 / PR #163)
+- [x] Next.js website on Vercel (PR #164)
+- [x] CI publishes all three npm packages on release (PR #166)
+
+### Active
+- [ ] **Multimodal memory** — content-addressed image store, vision-prompt compression, disk quota + refcount on eviction (#64, PR #111)
+- [ ] **Governance baseline** — this file, plus `GOVERNANCE.md`, `CONTRIBUTING.md`, `MAINTAINERS.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`
+
+### Planned
+- [ ] **GitHub connector** (`@agentmemory/github-watcher`) — sync issues, PRs, discussions as observations. Shares the `POST /agentmemory/observe` wire format with the filesystem connector.
+- [x] **OpenCode hook bus** (#156) — wired 22 hooks covering all 12 Claude Code hook types: session lifecycle (create/idle/status/compacted/update/diff/delete/error), messages & prompts (chat.message, message.updated user+assistant, message.removed), tool capture (before + rich ToolPart lifecycle in message.part.updated), memory injection (context + enrich via system.transform), part tracking (subtask, step-finish, reasoning, file, patch, compaction, agent, retry), file enrichment pipeline (stash via tool.execute.before + file.edited + file parts), permissions (updated + replied), task tracking (todo.updated w/ priority), commands (command.executed), config & model tracking (config + chat.params). Plus 2 slash commands (recall/remember). See `plugin/opencode/`.
+- [ ] **Session replay UI** in the real-time viewer — scrub the timeline, inspect per-observation payloads.
+- [ ] **Benchmark harness in CI** — keep the 95.2% R@5 number honest across releases by re-running LongMemEval-S on every minor tag.
+
+## Q3 2026 — Breadth (July – September)
+
+### Planned
+- [ ] **Additional maintainer onboarding** — at least one Maintainer from a different organization added via the process in `GOVERNANCE.md`. This is a prerequisite for advancing past the foundation's Growth Stage.
+- [ ] **Slack / Discord connector** — third source in the connector family.
+- [ ] **OpenSSF Scorecard** — enroll, reach a Silver-equivalent score. Badged in the README.
+- [ ] **Hermes integration hardening** — reach parity with the OpenClaw plugin surface (session lifecycle + tool-use hooks).
+- [ ] **Knowledge graph query language** — small DSL on top of `/agentmemory/graph` for multi-hop questions.
+- [ ] **First conference talk** — submit to KubeCon / LlamaCon / similar.
+
+### Candidate
+- Cross-agent shared memory namespace. Currently each agent installs its own instance. This would let a Claude Code session and a Cursor session recall each other's observations via a shared mesh node.
+
+## Q4 2026 — Trust (October – December)
+
+### Planned
+- [ ] **SSO gateway** — accept OIDC in front of the REST surface for team deployments.
+- [ ] **Audit log export** — streamable tail to S3 / Loki / stdout for compliance pipelines.
+- [ ] **RBAC on memory scope** — `project:read`, `project:write`, `governance:delete` role set.
+- [ ] **Long-running deployment guide** — first-class Docker, systemd unit, and launchd plist.
+- [ ] **Performance SLO** — publish p50/p95 recall latency targets, enforce via the benchmark harness.
+- [ ] **Security audit** — external review of the REST surface + mesh-sync path. Fund through LF if foundation acceptance lands before end of quarter.
+
+### Candidate
+- Agent-to-agent memory handoff protocol — standardize what one agent can inherit from another's memory, complementing MCP.
+
+## Q1 2027 — v1.0 (January – March)
+
+### Planned
+- [ ] **REST + MCP surface freeze.** Any break requires a major-version tag per `GOVERNANCE.md`.
+- [ ] **LTS branch `v1.x`** — 12-month security-fix commitment.
+- [ ] **v1.0 release** — full documentation pass, all roadmap items from prior quarters either shipped or formally deferred.
+- [ ] **Foundation membership** — Growth → Impact stage application if adoption + maintainer diversity metrics justify.
+
+### Candidate
+- Hosted reference instance for the community to benchmark against.
+- Reference implementation in a second language (Rust or Go) for the MCP server — would expand the set of runtimes that can host agentmemory.
+
+## Out of scope
+
+For transparency, these are deliberately *not* on the roadmap:
+
+- A cloud-hosted agentmemory SaaS.
+- Billing, subscription tiers, commercial licensing beyond Apache-2.0.
+- Agent frameworks themselves — agentmemory is a dependency, not a replacement for the agent runtime.
+
+## Feedback
+
+Anything on this list you disagree with, or think should move up / down — open an issue tagged `roadmap`. Quarterly themes are revisited with every quarterly retrospective.

SECURITY.md

@@ -0,0 +1,85 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+**Do not open a public GitHub issue for a suspected vulnerability.**
+
+Use one of:
+
+- **GitHub Security Advisories (preferred)** — private report form at <https://github.com/rohitg00/agentmemory/security/advisories/new>. GitHub routes the report to the Maintainers, assigns a GHSA identifier, and keeps you in a private thread until the fix ships. All sensitive details (stack traces, credentials, exploit payloads) stay end-to-end within GitHub's security infrastructure — use this channel whenever possible.
+- **Encrypted email (fallback)** — if GitHub is unavailable or the issue cannot be described in the GHSA form, send an encrypted message to `ghumare64@gmail.com` with subject `agentmemory security`. Encrypt with the Maintainer public keys published at <https://github.com/rohitg00.gpg> (PGP) and <https://github.com/rohitg00.keys> (SSH for verification); attach your own public key so we can reply encrypted. Plaintext email is accepted only as a last resort — prefer GHSA.
+
+Include, at minimum:
+
+- agentmemory version (`npm view @agentmemory/agentmemory version` against your install).
+- The affected surface — REST endpoint, MCP tool, hook, CLI flag, or filesystem layout.
+- A minimal reproduction — prefer one curl invocation or one MCP tool call plus the environment state required.
+- Impact, in your own words.
+
+## What we do with it
+
+1. **Acknowledge** within 72 hours (target: 24).
+2. **Triage** — confirm reproduction, assign a severity using CVSS 3.1, and give you a rough timeline.
+3. **Fix** in a private branch. Draft a GitHub Security Advisory with the patched version, CWE, CVSS vector, affected versions, and attribution to you (unless you prefer anonymity).
+4. **Coordinate disclosure** — we agree a disclosure date with you. Default window is 30 days from acknowledgment for straightforward vulnerabilities, up to 90 days for ones that need a deep refactor.
+5. **Publish** — release the patched version on npm, publish the advisory, update `CHANGELOG.md` under a `### Security` section for the release, notify downstream scanners.
+
+## Supported versions
+
+| Version | Security fixes? |
+|-|-|
+| Latest minor (currently `0.9.x`) | Yes |
+| Previous minor (currently `0.8.x`) | Critical / High severity only, for 90 days after a new minor is released |
+| Older | No |
+
+At v1.0 this policy switches to a stated LTS window per the roadmap.
+
+## Scope
+
+In scope:
+
+- The `@agentmemory/agentmemory` server (REST + MCP surface, hook handlers, state store).
+- The `@agentmemory/mcp` standalone MCP server.
+- The `@agentmemory/fs-watcher` connector.
+- First-party integrations under `integrations/` (`hermes/`, `openclaw/`, `filesystem-watcher/`).
+- The Claude Code plugin under `plugin/`.
+
+Out of scope:
+
+- Third-party MCP clients consuming agentmemory — report to those projects.
+- `iii-sdk` upstream — report to the iii project.
+- The marketing site under `website/` unless the issue affects user security (XSS against visitors, credential leak in build output).
+
+## Supply-chain stance
+
+agentmemory ships pre-built artifacts in the npm tarball — `dist/` is bundled at publish time, not built from `node_modules` at install time. The package's runtime dependency tree is intentionally small (6 production deps: `@anthropic-ai/sdk`, `@anthropic-ai/claude-agent-sdk`, `@clack/prompts`, `dotenv`, `iii-sdk`, `zod`) plus an optional set guarded behind `optionalDependencies` for embeddings.
+
+**No lockfile is committed** (#540). The reasoning:
+
+- The npm tarball ships pre-built `dist/` — fresh installs don't compile from source, so no lockfile is consulted at the user's install step.
+- The lockfile only affects contributor-local builds. Pinning it would shift the supply-chain attack surface from "what npm resolves today" to "what was resolved when the lockfile was last regenerated," which is a different tradeoff, not strictly better.
+- We use SemVer ranges (`^x.y.z`) on the published deps so security patches reach users without a re-release.
+
+If you ship agentmemory inside a hardened pipeline that requires reproducible installs, the recommended path is:
+
+1. `npm install --legacy-peer-deps` against the published tarball in a controlled environment.
+2. `npm shrinkwrap` to produce a versioned `npm-shrinkwrap.json` that travels with your deployment.
+3. Audit `node_modules/` once at that point and republish internally.
+
+CI runs `npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund` then `npm ci` against that generated lockfile, so every test job builds against a fully resolved tree. The lockfile is regenerated on each CI run rather than checked in, which keeps the published tarball aligned with whatever SemVer-compatible patch level was current at release time.
+
+Supply-chain monitoring we already do:
+
+- Dependabot opens PRs for every minor/patch bump on the production dep list (visible in the open PRs).
+- Every PR runs the full test suite on ubuntu-latest + macos-latest, Node 20 + 22, before any merge.
+- `optionalDependencies` (`@xenova/transformers`, `onnxruntime-node`, etc.) are guarded by `try { await import("...") } catch` so a missing or compromised optional dep cannot break the core runtime path.
+
+If you find a malicious package in our dep tree, file via the GHSA flow at the top of this document — that's the fastest path to a fixed release on npm.
+
+## Past advisories
+
+See the [`.github/security-advisories/`](./.github/security-advisories) directory for advisory drafts. Published advisories (with assigned GHSA IDs) live at <https://github.com/rohitg00/agentmemory/security/advisories>.
+
+## Safe harbor
+
+Good-faith research, reported privately, does not get legal heat from the project. Research targeting third-party deployments of agentmemory is not covered — that's between you and the deployer.

benchmark/COMPARISON.md

@@ -0,0 +1,158 @@
+# AI Agent Memory: Benchmark Comparison
+
+How agentmemory compares against other persistent memory solutions for AI coding agents.
+
+All numbers here come from published benchmarks or public repositories. We link to primary sources wherever possible so you can reproduce.
+
+---
+
+## Retrieval Accuracy (LongMemEval)
+
+[LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) measures long-term memory retrieval across ~48 sessions per question on the S variant (500 questions, ~115K tokens each).
+
+| System | Benchmark | R@5 | Notes |
+|---|---|---|---|
+| **agentmemory** (BM25 + Vector) | LongMemEval-S | **95.2%** | `all-MiniLM-L6-v2` embeddings, no API key |
+| agentmemory (BM25-only) | LongMemEval-S | 86.2% | Fallback when no embedding provider available |
+| MemPalace | LongMemEval-S | ~96.6% (self-reported) | Vendor-published number we have not independently reproduced. Vector-only with a larger embedding model and no agent-integration surface (no hooks, no MCP, no multi-agent) |
+| Letta / MemGPT | LoCoMo | 83.2% | Different benchmark (LoCoMo, not LongMemEval) |
+| Mem0 | LoCoMo | 68.5% | Different benchmark (LoCoMo, not LongMemEval) |
+
+**⚠️ Apples vs oranges caveat:** only agentmemory's 95.2% is our own measured result, reproducible from the methodology below. Every other number here is the vendor's published claim, on a different benchmark or harness, that we have not independently reproduced: MemPalace reports LongMemEval-S, while Letta and Mem0 publish on [LoCoMo](https://snap-stanford.github.io/LoCoMo/). Treat them as ballpark vendor claims, not a head-to-head on identical data. We'd love to run every system on the same dataset; if any maintainer wants to collaborate, open an issue.
+
+Full agentmemory methodology: [`LONGMEMEVAL.md`](LONGMEMEVAL.md)
+
+---
+
+## Feature Matrix
+
+| Feature | agentmemory | mem0 | Letta/MemGPT | Khoj | supermemory | MemPalace | Hippo |
+|---|---|---|---|---|---|---|---|
+| **GitHub stars** | Growing | 58K+ | 23K+ | 35K+ | 26K+ | 54K+ | Trending |
+| **Type** | Memory engine + MCP server | Memory layer API | Full agent runtime | Personal AI | Memory API + app | Benchmark-focused OSS | Memory system |
+| **Auto-capture via hooks** | ✅ 12 lifecycle hooks | ❌ Manual `add()` | ❌ Agent self-edits | ❌ Manual | ❌ API-side extraction | ❌ Manual | ❌ Manual |
+| **Search strategy** | BM25 + Vector + Graph | Vector + Graph | Vector (archival) | Semantic | Vector + RAG | Vector-only (large model) | Decay-weighted |
+| **Multi-agent coordination** | ✅ Leases + signals + mesh | ❌ | Runtime-internal only | ❌ | ❌ | ❌ | Multi-agent shared |
+| **Framework lock-in** | None | None | High | Standalone | None (drop-in wrappers) | None | None |
+| **External deps** | None | Qdrant/pgvector | Postgres + vector | Multiple | Managed cloud | Vector store | None |
+| **Self-hostable** | ✅ default | Optional | Optional | ✅ | ❌ Cloud-only | ✅ | ✅ |
+| **Knowledge graph** | ✅ Entity extraction + BFS | ✅ Mem0g variant | ❌ | Doc links | ❌ | ❌ | ❌ |
+| **Memory decay** | ✅ Ebbinghaus + tiered | ❌ | ❌ | ❌ | ✅ Auto-forget | ❌ | ✅ Half-lives |
+| **4-tier consolidation** | ✅ Working → episodic → semantic → procedural | ❌ | OS-inspired tiers | ❌ | ❌ | ❌ | Episodic + semantic |
+| **Version / supersession** | ✅ Jaccard-based | Passive | ❌ | ❌ | ✅ Auto-resolve | ❌ | ❌ |
+| **Real-time viewer** | ✅ Port 3113 | Cloud dashboard | Cloud dashboard | Web UI | Cloud dashboard | ❌ | ❌ |
+| **Privacy filtering** | ✅ Strips secrets pre-store | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Obsidian export** | ✅ Built-in | ❌ | ❌ | Native format | ❌ | ❌ | ❌ |
+| **Cross-agent** | ✅ MCP + REST | API calls | Within runtime | Standalone | MCP + API | Standalone | Multi-agent shared |
+| **Audit trail** | ✅ All mutations logged | ❌ | Limited | ❌ | ❌ | ❌ | ❌ |
+| **Language SDKs** | Any (REST + MCP) | Python + TS | Python only | API | Python + TS | Python | Node |
+
+---
+
+## Token Efficiency
+
+The main reason to use persistent memory at all: token cost. Here's what one year of heavy agent use looks like across approaches.
+
+| Approach | Tokens / year | Cost / year | Notes |
+|---|---|---|---|
+| Paste full history into context | 19.5M+ | Impossible | Exceeds context window after ~200 observations |
+| LLM-summarized memory (extraction-based) | ~650K | ~$500 | Lossy — summarization drops detail |
+| **agentmemory (API embeddings)** | **~170K** | **~$10** | Token-budgeted, only relevant memories injected |
+| **agentmemory (local embeddings)** | **~170K** | **$0** | `all-MiniLM-L6-v2` runs in-process |
+| supermemory | Not published | Cloud pricing | Managed API, no local token budget |
+| Mem0 | Varies by integration | Varies | Extraction-based, no token budget |
+
+**agentmemory ships with a built-in token savings calculator.** Run `npx @agentmemory/agentmemory status` after a few sessions and you'll see exactly how many tokens you've saved vs. pasting the full history.
+
+---
+
+## What Each Tool Is Best At
+
+This isn't a "agentmemory wins everything" page. Different tools solve different problems.
+
+**Choose agentmemory if you want:**
+- Automatic capture with zero manual `add()` calls
+- MCP server that works across Claude Code, Cursor, Codex, Gemini CLI, etc.
+- Hybrid BM25 + vector + graph search
+- Real-time viewer to see what your agent is learning
+- Self-hostable with zero external databases
+- Privacy filtering on API keys and secrets
+- Multi-agent coordination (leases, signals, routines)
+
+**Choose Mem0 if you want:**
+- Framework-agnostic API to bolt onto an existing agent
+- Managed cloud option with a dashboard
+- Python + TypeScript SDKs for direct integration
+- Entity/relationship extraction as the primary abstraction
+
+**Choose Letta/MemGPT if you want:**
+- A full agent runtime, not just memory
+- OS-inspired memory tiers (core/archival/recall)
+- Agents that self-edit their memory via function calls
+- Long-running conversational agents (weeks/months)
+
+**Choose Khoj if you want:**
+- A personal AI second brain, not agent infrastructure
+- Document-first search over your files and the web
+- Obsidian/Notion/Emacs integrations
+- Scheduled automations and research tasks
+
+**Choose supermemory if you want:**
+- A managed memory API with server-side auto-extraction and automatic forgetting
+- Drop-in wrappers for major AI frameworks (Vercel AI, LangChain, LangGraph)
+- A hosted dashboard with no infrastructure to run yourself
+- RAG plus memory served from a single query
+
+**Choose MemPalace if you want:**
+- A simple, free, open-source vector memory store
+- To chase its self-reported retrieval benchmark (we have not reproduced it)
+- Pure retrieval over agent workflow features
+- Note: no auto-capture, no MCP, no multi-agent coordination, so you wire all integration yourself
+
+**Choose Hippo if you want:**
+- Biologically-inspired memory model (decay, consolidation, sleep)
+- Multi-agent shared memory as a primary feature
+- "Forget by default, earn persistence through use" philosophy
+
+---
+
+## Running Your Own Benchmarks
+
+We encourage you to measure this yourself rather than trust any README. Here's how:
+
+```bash
+# Clone the repo
+git clone https://github.com/rohitg00/agentmemory.git
+cd agentmemory && npm install
+
+# Run LongMemEval-S
+npm run bench:longmemeval
+
+# Run quality benchmark (240 observations, 20 queries)
+npm run bench:quality
+
+# Run scale benchmark
+npm run bench:scale
+
+# Run real embeddings benchmark
+npm run bench:real-embeddings
+```
+
+Results land in `benchmark/results/`. All scripts, datasets, and results are committed for reproducibility.
+
+---
+
+## Corrections Welcome
+
+If you maintain one of these tools and we got a number wrong, please open an issue or PR. We'd rather have accurate numbers than convenient ones.
+
+If you want to add your tool to this comparison, open a PR with:
+1. A link to your benchmark methodology
+2. The metric and dataset you're measuring on
+3. A commit hash / version so we can reproduce
+
+**Sources:**
+- Mem0 LoCoMo benchmark: [mem0.ai blog](https://mem0.ai)
+- Letta LoCoMo benchmark: [letta.com/blog/benchmarking-ai-agent-memory](https://letta.com/blog/benchmarking-ai-agent-memory)
+- LongMemEval paper: [arxiv.org/abs/2410.10813](https://arxiv.org/abs/2410.10813)
+- LoCoMo paper: [snap-stanford.github.io/LoCoMo](https://snap-stanford.github.io/LoCoMo/)

benchmark/LONGMEMEVAL.md

@@ -0,0 +1,79 @@
+# LongMemEval-S Benchmark Results
+
+[LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) is an academic benchmark for evaluating long-term memory in chat assistants. It tests 5 core abilities: information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention.
+
+## Setup
+
+- **Dataset**: LongMemEval-S (500 questions, ~48 sessions per question, ~115K tokens)
+- **Source**: [xiaowu0162/longmemeval-cleaned](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned)
+- **Metric**: `recall_any@K` — does ANY gold session appear in top-K retrieved results?
+- **Embedding model**: `all-MiniLM-L6-v2` (384 dimensions, local, no API key)
+- **No LLM in the loop**: Pure retrieval evaluation, no answer generation or judge
+
+## Results
+
+| System | R@5 | R@10 | R@20 | NDCG@10 | MRR |
+|---|---|---|---|---|---|
+| **agentmemory BM25+Vector** | **95.2%** | **98.6%** | **99.4%** | **87.9%** | **88.2%** |
+| agentmemory BM25-only | 86.2% | 94.6% | 98.6% | 73.0% | 71.5% |
+| MemPalace raw (vector-only) | 96.6% | ~97.6% | — | — | — |
+
+### By Question Type (BM25+Vector)
+
+| Type | R@5 | R@10 | Count |
+|---|---|---|---|
+| knowledge-update | 98.7% | 100.0% | 78 |
+| multi-session | 97.7% | 100.0% | 133 |
+| single-session-assistant | 96.4% | 98.2% | 56 |
+| temporal-reasoning | 95.5% | 97.7% | 133 |
+| single-session-user | 90.0% | 97.1% | 70 |
+| single-session-preference | 83.3% | 96.7% | 30 |
+
+### By Question Type (BM25-only)
+
+| Type | R@5 | R@10 | Count |
+|---|---|---|---|
+| knowledge-update | 92.3% | 98.7% | 78 |
+| single-session-user | 91.4% | 95.7% | 70 |
+| temporal-reasoning | 88.0% | 94.7% | 133 |
+| multi-session | 86.5% | 96.2% | 133 |
+| single-session-assistant | 80.4% | 91.1% | 56 |
+| single-session-preference | 60.0% | 80.0% | 30 |
+
+## Analysis
+
+1. **BM25+Vector (95.2%) nearly matches pure vector search (96.6%)** with only a 1.4pp gap. Both use the same embedding model (all-MiniLM-L6-v2).
+
+2. **BM25 alone gets 86.2%** — keyword search with Porter stemming and synonym expansion is surprisingly effective on conversational data.
+
+3. **Adding vectors to BM25 gives +9pp** (86.2% → 95.2%), the largest improvement from any single component.
+
+4. **Preferences are the hardest category** for both BM25 (60%) and hybrid (83.3%). These require understanding implicit/indirect statements.
+
+5. **Multi-session and knowledge-update are strongest** (97.7%+ hybrid). The hybrid approach excels when facts are distributed across sessions.
+
+6. **R@10 reaches 98.6%** — nearly all gold sessions are found within the top 10 results.
+
+## Important Notes on Methodology
+
+- These are **retrieval recall** scores, not end-to-end QA accuracy. The official LongMemEval metric is QA accuracy (retrieve + generate answer + GPT-4o judge).
+- Systems on the actual LongMemEval QA leaderboard score 60-95% depending on the LLM reader (Oracle GPT-4o gets ~82.4%).
+- We do NOT claim these as "LongMemEval scores" — they are retrieval-only evaluations on the LongMemEval-S haystack.
+- Each question builds a fresh index from its ~48 sessions, searches with the question text, and checks if gold session IDs appear in results.
+
+## Reproducibility
+
+```bash
+# Download dataset (264 MB)
+pip install huggingface_hub
+python3 -c "
+from huggingface_hub import hf_hub_download
+hf_hub_download(repo_id='xiaowu0162/longmemeval-cleaned', filename='longmemeval_s_cleaned.json', repo_type='dataset', local_dir='benchmark/data')
+"
+
+# Run BM25-only
+npx tsx benchmark/longmemeval-bench.ts bm25
+
+# Run BM25+Vector hybrid (requires @xenova/transformers)
+npx tsx benchmark/longmemeval-bench.ts hybrid
+```

benchmark/QUALITY.md

@@ -0,0 +1,75 @@
+# agentmemory v0.6.0 — Search Quality Evaluation (Internal Dataset)
+
+> For results on the academic LongMemEval-S benchmark (ICLR 2025, 500 questions), see [`LONGMEMEVAL.md`](LONGMEMEVAL.md) — **95.2% R@5, 98.6% R@10**.
+
+**Date:** 2026-03-18T07:44:43.397Z
+**Dataset:** 240 synthetic observations across 30 sessions (internal coding project)
+**Queries:** 20 labeled queries with ground-truth relevance
+**Metric definitions:** Recall@K (fraction of relevant docs in top K), Precision@K (fraction of top K that are relevant), NDCG@10 (ranking quality), MRR (position of first relevant result)
+
+## Head-to-Head Comparison
+
+| System | Recall@5 | Recall@10 | Precision@5 | NDCG@10 | MRR | Latency | Tokens/query |
+|--------|----------|-----------|-------------|---------|-----|---------|--------------|
+| Built-in (CLAUDE.md / grep) | 37.0% | 55.8% | 78.0% | 80.3% | 82.5% | 0.50ms | 22,610 |
+| Built-in (200-line MEMORY.md) | 27.4% | 37.8% | 63.0% | 56.4% | 65.5% | 0.16ms | 7,938 |
+| BM25-only | 43.8% | 55.9% | 95.0% | 82.7% | 95.5% | 0.17ms | 3,142 |
+| Dual-stream (BM25+Vector) | 42.4% | 58.6% | 90.0% | 84.7% | 95.4% | 0.71ms | 3,142 |
+| Triple-stream (BM25+Vector+Graph) | 36.8% | 58.0% | 87.0% | 81.7% | 87.9% | 1.02ms | 3,142 |
+
+## Why This Matters
+
+**Recall improvement:** agentmemory triple-stream finds 58.0% of relevant memories at K=10 vs 55.8% for keyword grep (+4%)
+**Token savings:** agentmemory returns only the top 10 results (3,142 tokens) vs loading everything into context (22,610 tokens) — 86% reduction
+**200-line cap:** Claude Code's MEMORY.md is capped at 200 lines. With 240 observations, 37.8% recall at K=10 — memories from later sessions are simply invisible.
+
+## Per-Query Breakdown (Triple-Stream)
+
+| Query | Category | Recall@10 | NDCG@10 | MRR | Relevant | Latency |
+|-------|----------|-----------|---------|-----|----------|---------|
+| How did we set up authentication? | semantic | 50.0% | 100.0% | 100.0% | 20 | 1.7ms |
+| JWT token validation middleware | exact | 50.0% | 64.9% | 100.0% | 10 | 1.2ms |
+| PostgreSQL connection issues | semantic | 33.3% | 100.0% | 100.0% | 30 | 1.0ms |
+| Playwright test configuration | exact | 100.0% | 100.0% | 100.0% | 10 | 1.1ms |
+| Why did the production deployment fail? | cross-session | 33.3% | 100.0% | 100.0% | 30 | 0.8ms |
+| rate limiting implementation | exact | 80.0% | 64.1% | 33.3% | 10 | 0.7ms |
+| What security measures did we add? | semantic | 33.3% | 100.0% | 100.0% | 30 | 0.7ms |
+| database performance optimization | semantic | 0.0% | 0.0% | 7.1% | 25 | 0.8ms |
+| Kubernetes pod crash debugging | entity | 100.0% | 96.7% | 100.0% | 5 | 1.2ms |
+| Docker containerization setup | entity | 100.0% | 100.0% | 100.0% | 10 | 0.9ms |
+| How does caching work in the app? | semantic | 25.0% | 64.9% | 100.0% | 20 | 0.8ms |
+| test infrastructure and factories | exact | 50.0% | 64.9% | 100.0% | 10 | 0.7ms |
+| What happened with the OAuth callback error? | cross-session | 100.0% | 54.1% | 16.7% | 5 | 1.1ms |
+| monitoring and observability setup | semantic | 66.7% | 100.0% | 100.0% | 15 | 0.8ms |
+| Prisma ORM configuration | entity | 25.7% | 93.6% | 100.0% | 35 | 1.8ms |
+| CI/CD pipeline configuration | exact | 20.0% | 64.9% | 100.0% | 25 | 1.0ms |
+| memory leak debugging | cross-session | 100.0% | 100.0% | 100.0% | 5 | 0.7ms |
+| API design decisions | semantic | 25.0% | 64.9% | 100.0% | 20 | 1.4ms |
+| zod validation schemas | entity | 66.7% | 100.0% | 100.0% | 15 | 0.7ms |
+| infrastructure as code Terraform | entity | 100.0% | 100.0% | 100.0% | 5 | 1.5ms |
+
+## By Query Category
+
+| Category | Avg Recall@10 | Avg NDCG@10 | Avg MRR | Queries |
+|----------|---------------|-------------|---------|---------|
+| exact | 60.0% | 71.8% | 86.7% | 5 |
+| semantic | 33.3% | 75.7% | 86.7% | 7 |
+| cross-session | 77.8% | 84.7% | 72.2% | 3 |
+| entity | 78.5% | 98.1% | 100.0% | 5 |
+
+## Context Window Analysis
+
+The fundamental problem with built-in agent memory:
+
+| Observations | MEMORY.md tokens | agentmemory tokens (top 10) | Savings | MEMORY.md reachable |
+|-------------|-----------------|---------------------------|---------|-------------------|
+| 240 | 12,000 | 3,142 | 74% | 83% |
+| 500 | 25,000 | 3,142 | 87% | 40% |
+| 1,000 | 50,000 | 3,142 | 94% | 20% |
+| 5,000 | 250,000 | 3,142 | 99% | 4% |
+
+At 240 observations (our dataset), MEMORY.md already hits its 200-line cap and loses access to the most recent 40 observations. At 1,000 observations, 80% of memories are invisible. agentmemory always searches the full corpus.
+
+---
+
+*100 evaluations across 5 systems. Ground-truth labels assigned by concept matching against observation metadata.*

benchmark/README.md

@@ -0,0 +1,100 @@
+# benchmark/
+
+Two kinds of numbers live in this directory:
+
+1. **Quality / retrieval** — `longmemeval-bench.ts`, `quality-eval.ts`,
+   `real-embeddings-eval.ts`, `scale-eval.ts`. Recall, precision, token
+   savings. Documented in `LONGMEMEVAL.md`, `QUALITY.md`,
+   `REAL-EMBEDDINGS.md`, `SCALE.md`.
+
+2. **Load shape** — `load-100k.ts`. p50 / p90 / p99 latency and
+   throughput against a running daemon. This is the file you want when
+   somebody asks "what's p99 at 100k memories under concurrency 100?".
+
+## load-100k.ts
+
+Hand-rolled, dependency-free load harness. Issues real HTTP against a
+local agentmemory daemon at `http://localhost:3111`, records per-request
+latency with `performance.now()`, and writes a JSON report per run.
+
+### What it measures
+
+For each cell in the matrix `(N, concurrency, endpoint)` it records:
+
+- `p50_ms`, `p90_ms`, `p99_ms` — nearest-rank percentiles.
+- `min_ms`, `max_ms`, `ops`, `errors`.
+- `throughput_per_sec` — wall-clock ops / sec for that cell.
+
+Default matrix:
+
+- `N` ∈ {1000, 10000, 100000} — number of memories seeded before the
+  cell runs.
+- `C` ∈ {1, 10, 100} — concurrent in-flight requests during the cell.
+- Endpoints under test:
+  - `POST /agentmemory/remember`
+  - `POST /agentmemory/smart-search`
+  - `GET  /agentmemory/memories?latest=true`
+
+Each cell issues `BENCH_OPS=200` requests by default — enough samples
+for stable p99 without dragging a 100k-seed run past tens of minutes.
+
+### Why p99 is the number that matters
+
+p50 tells you the median request feels fast. p90 tells you the bulk of
+requests feel fast. **p99 tells you the request your tail user hits when
+they really need it feels fast.** Capacity planning lives here — if you
+want to size a fleet, scale your daemon, or set an SLO, p99 is the
+number to plan against. p50 will lie to you.
+
+### Running it
+
+```bash
+# 1. Start the daemon however you normally do (npx, Docker, etc.)
+npx @agentmemory/agentmemory
+
+# 2. From the repo root, in another shell:
+npm run bench:load
+```
+
+To override the matrix:
+
+```bash
+BENCH_N=1000 BENCH_C=1,10 BENCH_OPS=100 npm run bench:load
+```
+
+To have the harness spawn a daemon for the run (after `npm run build`):
+
+```bash
+AGENTMEMORY_BENCH_AUTOSTART=1 npm run bench:load
+```
+
+Other env knobs (see the file header for the canonical list):
+
+- `AGENTMEMORY_URL` — base URL of the daemon (default
+  `http://localhost:3111`).
+- `BENCH_SEED` — seed for the `mulberry32` content RNG. Same seed +
+  same daemon build = byte-identical seed corpus.
+- `BENCH_OUT_DIR` — where the JSON report lands (default
+  `benchmark/results/`).
+
+### Where results land
+
+`benchmark/results/load-100k-<short-git-sha>.json`. The harness
+`mkdir -p`s the directory. The file has a `schema_version: 1` field so
+future format changes don't silently break consumers.
+
+### Content generation is seedable
+
+Synthetic memory content is built from a small noun / verb / concept
+vocabulary fed by a `mulberry32(BENCH_SEED)` PRNG. Same seed + same
+build = same corpus. The point isn't "realistic" content (there isn't
+one realistic content); the point is **reproducibility** — re-running
+the harness against the same git sha should give the same content
+mixture going in, so latency variance comes from the daemon and not
+from JSON payload jitter.
+
+### Publishing numbers per release
+
+The release flow appends a `## Performance` section to `CHANGELOG.md`
+referencing the JSON in `benchmark/results/` for that release's git
+sha. p99 is the headline number; the JSON is the receipt.

benchmark/REAL-EMBEDDINGS.md

@@ -0,0 +1,67 @@
+# agentmemory v0.6.0 — Real Embeddings Quality Evaluation
+
+**Date:** 2026-03-18T07:38:21.450Z
+**Platform:** darwin arm64, Node v20.20.0
+**Dataset:** 240 observations, 30 sessions, 20 labeled queries
+**Embedding model:** Xenova/all-MiniLM-L6-v2 (384d, local, no API key)
+
+## Head-to-Head: Real Embeddings vs Keyword Search
+
+| System | Recall@5 | Recall@10 | Precision@5 | NDCG@10 | MRR | Avg Latency | Tokens/query |
+|--------|----------|-----------|-------------|---------|-----|-------------|--------------|
+| Built-in (grep all) | 37.0% | 55.8% | 78.0% | 80.3% | 82.5% | 0.44ms | 19,462 |
+| BM25-only (stemmed+synonyms) | 43.8% | 55.9% | 95.0% | 82.7% | 95.5% | 0.26ms | 1,571 |
+| Dual-stream (BM25+Xenova) | 43.8% | 64.1% | 98.0% | 94.9% | 100.0% | 2.39ms | 1,571 |
+| Triple-stream (BM25+Xenova+Graph) | 43.8% | 64.1% | 98.0% | 94.9% | 100.0% | 2.07ms | 1,571 |
+
+## Improvement from Real Embeddings
+
+Adding real vector embeddings to BM25 improves recall@10 by **8.2 percentage points**.
+Token savings vs loading everything: **92%** (1,571 vs 19,462 tokens).
+
+## Per-Query: Where Real Embeddings Win
+
+Queries where dual-stream (real embeddings) outperforms BM25-only:
+
+| Query | Category | BM25 Recall@10 | +Vector Recall@10 | Delta |
+|-------|----------|---------------|-------------------|-------|
+| How did we set up authentication? | semantic | 25.0% | 45.0% | +20.0pp ** |
+| Playwright test configuration | exact | 50.0% | 90.0% | +40.0pp ** |
+| database performance optimization | semantic | 0.0% | 40.0% | +40.0pp ** |
+| test infrastructure and factories | exact | 50.0% | 80.0% | +30.0pp ** |
+| Prisma ORM configuration | entity | 14.3% | 28.6% | +14.3pp ** |
+| CI/CD pipeline configuration | exact | 20.0% | 40.0% | +20.0pp ** |
+
+## By Category Comparison
+
+| Category | Built-in grep | BM25 (stemmed) | +Real Vectors | +Graph |
+|----------|--------------|----------------|--------------|--------|
+| exact | 48.0% | 54.0% | 72.0% | 72.0% |
+| semantic | 35.5% | 33.3% | 41.9% | 41.9% |
+| cross-session | 77.8% | 77.8% | 77.8% | 77.8% |
+| entity | 79.0% | 76.2% | 79.0% | 79.0% |
+
+## Embedding Performance
+
+| System | Embedding Time | Model | Dimensions |
+|--------|---------------|-------|------------|
+| Dual-stream (BM25+Xenova) | 3.1s | Xenova/all-MiniLM-L6-v2 | 384 |
+| Triple-stream (BM25+Xenova+Graph) | 2.9s | Xenova/all-MiniLM-L6-v2 | 384 |
+
+Embedding is a one-time cost at ingestion. Search is sub-millisecond after indexing.
+
+## Key Findings
+
+1. **Semantic queries improve most**: 8.6pp recall@10 gain from real embeddings
+2. **"database performance optimization"** — the hardest query — goes from BM25 0.0% to vector-augmented 40.0%
+3. **Entity/exact queries** are already well-served by BM25+stemming — vectors add marginal value
+4. **Local embeddings (Xenova)** run without API keys — zero cost, zero latency concerns
+
+## Recommendation
+
+Enable local embeddings by default (`EMBEDDING_PROVIDER=local` or install `@xenova/transformers`).
+This gives agentmemory genuine semantic search that built-in agent memories cannot match —
+understanding that "database performance optimization" relates to "N+1 query fix" and "eager loading".
+
+---
+*All measurements use Xenova/all-MiniLM-L6-v2 local embeddings (384 dimensions, no API calls).*

benchmark/SCALE.md

@@ -0,0 +1,110 @@
+# agentmemory v0.6.0 — Scale & Cross-Session Evaluation
+
+**Date:** 2026-03-18T07:45:03.529Z
+**Platform:** darwin arm64, Node v20.20.0
+
+## 1. Scale: agentmemory vs Built-in Memory
+
+Every built-in agent memory (CLAUDE.md, .cursorrules, Cline's memory-bank) loads ALL memory into context every session. agentmemory searches and returns only relevant results.
+
+| Observations | Sessions | Index Build | BM25 Search | Hybrid Search | Heap | Context Tokens (built-in) | Context Tokens (agentmemory) | Savings | Built-in Unreachable |
+|-------------|----------|------------|-------------|---------------|------|--------------------------|-----------------------------|---------|--------------------|
+| 240 | 30 | 177ms | 0.112ms | 0.63ms | 9MB | 10,504 | 1,924 | 82% | 17% |
+| 1,000 | 125 | 155ms | 0.317ms | 1.709ms | 6MB | 43,834 | 1,969 | 96% | 80% |
+| 5,000 | 625 | 810ms | 1.496ms | 8.58ms | 25MB | 220,335 | 1,972 | 99% | 96% |
+| 10,000 | 1250 | 1657ms | 3.195ms | 17.49ms | 1MB | 440,973 | 1,974 | 100% | 98% |
+| 50,000 | 6250 | 9182ms | 22.827ms | 108.722ms | 316MB | 2,216,173 | 1,981 | 100% | 100% |
+
+### What the numbers mean
+
+**Context Tokens (built-in):** How many tokens Claude Code/Cursor/Cline would consume loading ALL memory into the context window. At 5,000 observations, this is ~250K tokens — exceeding most context windows entirely.
+
+**Context Tokens (agentmemory):** How many tokens the top-10 search results consume. Stays constant regardless of corpus size.
+
+**Built-in Unreachable:** Percentage of memories that built-in systems CANNOT access because they exceed the 200-line MEMORY.md cap or context window limits. At 1,000 observations, 80% of your project history is invisible.
+
+### Storage Costs
+
+| Observations | BM25 Index | Vector Index (d=384) | Total Storage |
+|-------------|-----------|---------------------|---------------|
+| 240 | 395 KB | 494 KB | 0.9 MB |
+| 1,000 | 1,599 KB | 2,060 KB | 3.6 MB |
+| 5,000 | 8,006 KB | 10,298 KB | 17.9 MB |
+| 10,000 | 16,005 KB | 20,596 KB | 35.7 MB |
+| 50,000 | 80,126 KB | 102,979 KB | 178.8 MB |
+
+## 2. Cross-Session Retrieval
+
+Can the system find relevant information from past sessions? This is impossible for built-in memory once observations exceed the line/context cap.
+
+| Query | Target Session | Gap | BM25 Found | BM25 Rank | Hybrid Found | Hybrid Rank | Built-in Visible |
+|-------|---------------|-----|-----------|-----------|-------------|-------------|-----------------|
+| How did we set up OAuth providers? | ses_005-009 | 24 | Yes | #1 | Yes | #1 | Yes |
+| What was the N+1 query fix? | ses_010-014 | 18 | Yes | #1 | Yes | #2 | Yes |
+| PostgreSQL full-text search setup | ses_010-014 | 17 | Yes | #1 | Yes | #1 | Yes |
+| bcrypt password hashing configuration | ses_005-009 | 20 | Yes | #1 | Yes | #1 | Yes |
+| Vitest unit testing setup | ses_020-024 | 9 | Yes | #1 | Yes | #1 | Yes |
+| webhook retry exponential backoff | ses_015-019 | 14 | Yes | #1 | Yes | #1 | Yes |
+| ESLint flat config migration | ses_000-004 | 29 | Yes | #1 | Yes | #1 | Yes |
+| Kubernetes HPA autoscaling configuration | ses_025-029 | 4 | Yes | #1 | Yes | #1 | No |
+| Prisma database seed script | ses_010-014 | 16 | Yes | #1 | Yes | #1 | Yes |
+| API cursor-based pagination | ses_015-019 | 14 | Yes | #1 | Yes | #1 | Yes |
+| CSRF protection double-submit cookie | ses_005-009 | 24 | Yes | #1 | Yes | #1 | Yes |
+| blue-green deployment rollback | ses_025-029 | 4 | Yes | #1 | Yes | #1 | No |
+
+**Summary:** agentmemory BM25 found 12/12 cross-session queries. Hybrid found 12/12. Built-in memory (200-line cap) could only reach 10/12.
+
+## 3. The Context Window Problem
+
+```
+Agent context window: ~200K tokens
+System prompt + tools:  ~20K tokens
+User conversation:      ~30K tokens
+Available for memory:  ~150K tokens
+
+At 50 tokens/observation:
+  200 observations  =  10,000 tokens  (fits, but 200-line cap hits first)
+  1,000 observations =  50,000 tokens  (33% of available budget)
+  5,000 observations = 250,000 tokens  (EXCEEDS total context window)
+
+agentmemory top-10 results:
+  Any corpus size     =  ~1,924 tokens  (0.3% of budget)
+```
+
+## 4. What Built-in Memory Cannot Do
+
+| Capability | Built-in (CLAUDE.md) | agentmemory |
+|-----------|---------------------|-------------|
+| Semantic search | No (keyword grep only) | BM25 + vector + graph |
+| Scale beyond 200 lines | No (hard cap) | Unlimited |
+| Cross-session recall | Only if in 200-line window | Full corpus search |
+| Cross-agent sharing | No (per-agent files) | MCP + REST API |
+| Multi-agent coordination | No | Leases, signals, actions |
+| Temporal queries | No | Point-in-time graph |
+| Memory lifecycle | No (manual pruning) | Ebbinghaus decay + eviction |
+| Knowledge graph | No | Entity extraction + traversal |
+| Query expansion | No | LLM-generated reformulations |
+| Retention scoring | No | Time-frequency decay model |
+| Real-time dashboard | No (read files manually) | Viewer on :3113 |
+| Concurrent access | No (file lock) | Keyed mutex + KV store |
+
+## 5. When to Use What
+
+**Use built-in memory (CLAUDE.md) when:**
+- You have < 200 items to remember
+- Single agent, single project
+- Preferences and quick facts only
+- Zero setup is the priority
+
+**Use agentmemory when:**
+- Project history exceeds 200 observations
+- You need to recall specific incidents from weeks ago
+- Multiple agents work on the same codebase
+- You want semantic search ("how does auth work?") not just keyword matching
+- You need to track memory quality, decay, and lifecycle
+- You want a shared memory layer across Claude Code, Cursor, Windsurf, etc.
+
+Built-in memory is your sticky notes. agentmemory is the searchable database behind them.
+
+---
+*Scale tests: 5 corpus sizes. Cross-session tests: 12 queries targeting specific past sessions.*

benchmark/dataset.ts

@@ -0,0 +1,293 @@
+import type { CompressedObservation } from "../src/types.js";
+
+export interface LabeledQuery {
+  query: string;
+  relevantObsIds: string[];
+  description: string;
+  category: "exact" | "semantic" | "temporal" | "cross-session" | "entity";
+}
+
+const SESSION_COUNT = 30;
+const OBS_PER_SESSION = 8;
+
+function ts(daysAgo: number): string {
+  return new Date(Date.now() - daysAgo * 86400000).toISOString();
+}
+
+const RAW_SESSIONS: Array<{
+  sessionRange: [number, number];
+  daysAgoRange: [number, number];
+  project: string;
+  observations: Array<Omit<CompressedObservation, "id" | "sessionId" | "timestamp">>;
+}> = [
+  {
+    sessionRange: [0, 4],
+    daysAgoRange: [28, 25],
+    project: "webapp",
+    observations: [
+      { type: "command_run", title: "Initialize Next.js 15 project", subtitle: "create-next-app", facts: ["Created Next.js 15 app with App Router", "TypeScript template selected", "Tailwind CSS v4 configured"], narrative: "Initialized a new Next.js 15 project using create-next-app with TypeScript and Tailwind CSS. Selected the App Router layout.", concepts: ["nextjs", "typescript", "tailwind", "app-router"], files: ["package.json", "tsconfig.json", "tailwind.config.ts"], importance: 6 },
+      { type: "file_edit", title: "Configure ESLint with flat config", subtitle: "eslint.config.mjs", facts: ["Migrated to ESLint flat config format", "Added typescript-eslint plugin", "Configured import sorting rules"], narrative: "Set up ESLint using the new flat config format (eslint.config.mjs). Added typescript-eslint for type-aware linting and configured import sorting with eslint-plugin-import.", concepts: ["eslint", "linting", "code-quality", "typescript"], files: ["eslint.config.mjs", "package.json"], importance: 5 },
+      { type: "file_edit", title: "Set up Prettier with Tailwind plugin", subtitle: "Formatting", facts: ["Installed prettier and prettier-plugin-tailwindcss", "Added .prettierrc with semi: false, singleQuote: true", "Configured format-on-save in VS Code settings"], narrative: "Configured Prettier for automatic code formatting. Added the Tailwind CSS class sorting plugin. Set up VS Code to format on save.", concepts: ["prettier", "formatting", "tailwind", "developer-experience"], files: [".prettierrc", ".vscode/settings.json"], importance: 4 },
+      { type: "file_edit", title: "Create shared UI component library", subtitle: "Components", facts: ["Created Button, Input, Card, Badge components", "Used cva (class-variance-authority) for variant styling", "Added Radix UI primitives for accessibility"], narrative: "Built a shared component library with Button, Input, Card, and Badge components. Used class-variance-authority (cva) for type-safe variant styling and Radix UI primitives for keyboard navigation and screen reader support.", concepts: ["components", "ui-library", "radix-ui", "cva", "accessibility"], files: ["src/components/ui/button.tsx", "src/components/ui/input.tsx", "src/components/ui/card.tsx"], importance: 7 },
+      { type: "file_edit", title: "Add global layout with navigation", subtitle: "Layout", facts: ["Created root layout with metadata", "Added responsive navigation bar", "Implemented mobile hamburger menu"], narrative: "Created the root layout component with SEO metadata, Open Graph tags, and a responsive navigation bar that collapses into a hamburger menu on mobile devices.", concepts: ["layout", "navigation", "responsive-design", "seo"], files: ["src/app/layout.tsx", "src/components/nav.tsx"], importance: 6 },
+      { type: "file_edit", title: "Configure path aliases and absolute imports", subtitle: "tsconfig", facts: ["Added @ alias pointing to src/", "Configured baseUrl for absolute imports"], narrative: "Set up TypeScript path aliases so imports can use @/components instead of relative paths. Configured baseUrl in tsconfig.json.", concepts: ["typescript", "path-aliases", "developer-experience"], files: ["tsconfig.json"], importance: 3 },
+      { type: "command_run", title: "Add Vitest for unit testing", subtitle: "Testing setup", facts: ["Installed vitest and @testing-library/react", "Created vitest.config.ts with jsdom environment", "Added test script to package.json"], narrative: "Set up Vitest as the unit testing framework with React Testing Library for component tests. Configured jsdom environment for DOM testing.", concepts: ["vitest", "testing", "react-testing-library", "configuration"], files: ["vitest.config.ts", "package.json"], importance: 5 },
+      { type: "file_edit", title: "Set up Husky pre-commit hooks", subtitle: "Git hooks", facts: ["Installed husky and lint-staged", "Pre-commit runs ESLint and Prettier", "Added commitlint for conventional commits"], narrative: "Configured Husky git hooks with lint-staged to run ESLint and Prettier on staged files before each commit. Added commitlint to enforce conventional commit message format.", concepts: ["husky", "git-hooks", "lint-staged", "commitlint", "ci"], files: [".husky/pre-commit", ".lintstagedrc", "commitlint.config.js"], importance: 4 },
+    ],
+  },
+  {
+    sessionRange: [5, 9],
+    daysAgoRange: [24, 20],
+    project: "webapp",
+    observations: [
+      { type: "file_edit", title: "Implement NextAuth.js v5 authentication", subtitle: "Auth setup", facts: ["Configured NextAuth.js v5 with Auth.js", "Added GitHub and Google OAuth providers", "Set up JWT session strategy with 30-day expiry"], narrative: "Implemented authentication using NextAuth.js v5 (Auth.js). Configured GitHub and Google as OAuth providers. Using JWT-based sessions with 30-day expiry instead of database sessions for simplicity.", concepts: ["nextauth", "authentication", "oauth", "jwt", "github", "google"], files: ["src/auth.ts", "src/app/api/auth/[...nextauth]/route.ts", ".env.local"], importance: 9 },
+      { type: "file_edit", title: "Create login and signup pages", subtitle: "Auth UI", facts: ["Built login page with OAuth buttons", "Added email/password form with validation", "Implemented error toast notifications"], narrative: "Created the login page with GitHub and Google OAuth sign-in buttons plus an email/password form. Used react-hook-form with zod validation. Added toast notifications for login errors.", concepts: ["login", "signup", "oauth", "form-validation", "react-hook-form", "zod"], files: ["src/app/login/page.tsx", "src/app/signup/page.tsx"], importance: 7 },
+      { type: "file_edit", title: "Add middleware for route protection", subtitle: "Auth middleware", facts: ["Created middleware.ts to protect /dashboard routes", "Redirects unauthenticated users to /login", "Allows public access to /api/webhooks"], narrative: "Added Next.js middleware that checks for valid sessions on protected routes (/dashboard/*). Unauthenticated users are redirected to /login. The /api/webhooks path is excluded from auth checks for third-party integrations.", concepts: ["middleware", "route-protection", "authentication", "security"], files: ["src/middleware.ts"], importance: 8 },
+      { type: "file_edit", title: "Implement role-based access control", subtitle: "RBAC", facts: ["Added user roles: admin, editor, viewer", "Created withAuth HOC for role checking", "Stored roles in JWT custom claims"], narrative: "Implemented role-based access control with three roles: admin, editor, and viewer. Created a withAuth higher-order component that checks user roles before rendering protected components. Roles are stored as custom claims in the JWT token.", concepts: ["rbac", "authorization", "roles", "jwt-claims", "security"], files: ["src/lib/auth/rbac.ts", "src/lib/auth/with-auth.tsx"], importance: 8 },
+      { type: "file_edit", title: "Add password hashing with bcrypt", subtitle: "Security", facts: ["Using bcrypt with cost factor 12", "Added password strength validation (min 8 chars, mixed case, number)", "Implemented rate limiting on login endpoint (5 attempts per 15 min)"], narrative: "Added bcrypt password hashing with cost factor 12 for the email/password authentication flow. Implemented password strength validation requiring minimum 8 characters with mixed case and numbers. Added rate limiting on the login API endpoint: 5 attempts per 15-minute window per IP.", concepts: ["bcrypt", "password-hashing", "rate-limiting", "security", "validation"], files: ["src/lib/auth/password.ts", "src/app/api/auth/login/route.ts"], importance: 9 },
+      { type: "file_edit", title: "Create user profile settings page", subtitle: "User settings", facts: ["Profile page shows avatar, name, email", "Added avatar upload with S3 presigned URLs", "Implemented account deletion flow"], narrative: "Built the user profile settings page showing avatar, name, and email. Added avatar upload using S3 presigned URLs for direct browser-to-S3 uploads. Implemented a full account deletion flow with email confirmation.", concepts: ["user-profile", "settings", "s3", "file-upload", "account-deletion"], files: ["src/app/dashboard/settings/page.tsx", "src/app/api/upload/route.ts"], importance: 6 },
+      { type: "command_run", title: "Debug OAuth callback URL mismatch", subtitle: "Auth debugging", facts: ["GitHub OAuth callback failed with redirect_uri_mismatch", "Fixed: NEXTAUTH_URL was set to http:// but app served on https://", "Lesson: always use HTTPS in production OAuth callback URLs"], narrative: "Spent time debugging why GitHub OAuth login failed in production. The error was redirect_uri_mismatch. Root cause: NEXTAUTH_URL environment variable was set to http://localhost:3000 in production instead of the HTTPS production URL. Fixed by updating the environment variable.", concepts: ["oauth-debugging", "github", "callback-url", "environment-variables", "production"], files: [".env.production"], importance: 7 },
+      { type: "file_edit", title: "Add CSRF protection to API routes", subtitle: "Security", facts: ["Implemented double-submit cookie pattern", "Added CSRF token generation in layout", "Validated CSRF token on all POST/PUT/DELETE requests"], narrative: "Added CSRF protection using the double-submit cookie pattern. A CSRF token is generated on page load and stored in both a cookie and a hidden form field. All mutating API requests (POST, PUT, DELETE) validate the token.", concepts: ["csrf", "security", "cookies", "api-protection"], files: ["src/lib/csrf.ts", "src/middleware.ts"], importance: 8 },
+    ],
+  },
+  {
+    sessionRange: [10, 14],
+    daysAgoRange: [19, 15],
+    project: "webapp",
+    observations: [
+      { type: "file_edit", title: "Set up Prisma ORM with PostgreSQL", subtitle: "Database", facts: ["Initialized Prisma with PostgreSQL provider", "Created User, Post, Comment, Tag models", "Generated migrations with prisma migrate dev"], narrative: "Set up Prisma ORM connecting to a PostgreSQL database. Defined the initial schema with User, Post, Comment, and Tag models including many-to-many relationships between Post and Tag.", concepts: ["prisma", "postgresql", "database", "orm", "schema", "migrations"], files: ["prisma/schema.prisma", "src/lib/db.ts"], importance: 9 },
+      { type: "file_edit", title: "Create database seed script", subtitle: "Seeding", facts: ["Created seed.ts with faker-generated data", "Seeds 10 users, 50 posts, 200 comments", "Runs via prisma db seed command"], narrative: "Built a database seed script using faker.js to generate realistic test data. Creates 10 users with posts, comments, and tags. Configured to run automatically on prisma db seed.", concepts: ["database", "seeding", "faker", "test-data", "prisma"], files: ["prisma/seed.ts", "package.json"], importance: 5 },
+      { type: "file_edit", title: "Implement server actions for CRUD operations", subtitle: "Data layer", facts: ["Created server actions for post CRUD", "Used Prisma transactions for multi-step operations", "Added revalidatePath after mutations"], narrative: "Implemented Next.js server actions for post create, read, update, and delete operations. Used Prisma transactions for operations that modify multiple tables. Called revalidatePath after mutations to refresh cached data.", concepts: ["server-actions", "crud", "prisma", "transactions", "revalidation", "caching"], files: ["src/app/actions/posts.ts"], importance: 8 },
+      { type: "command_run", title: "Fix N+1 query in post listing", subtitle: "Performance", facts: ["Identified N+1 query loading post authors individually", "Fixed with Prisma include for eager loading", "Query count dropped from 52 to 3"], narrative: "Discovered an N+1 query problem on the post listing page — each post was triggering a separate query to load its author. Fixed by using Prisma's include option for eager loading. Total query count dropped from 52 to 3.", concepts: ["n+1", "performance", "prisma", "eager-loading", "query-optimization"], files: ["src/app/actions/posts.ts"], importance: 8 },
+      { type: "file_edit", title: "Add full-text search with PostgreSQL tsvector", subtitle: "Search", facts: ["Created tsvector column on posts table", "Built GIN index for fast text search", "Implemented search API with ts_rank scoring"], narrative: "Added full-text search using PostgreSQL's built-in tsvector functionality. Created a generated tsvector column combining title and body, with a GIN index. The search API uses ts_rank for relevance scoring and supports phrase matching.", concepts: ["full-text-search", "postgresql", "tsvector", "gin-index", "search"], files: ["prisma/migrations/20260301_add_search.sql", "src/app/api/search/route.ts"], importance: 7 },
+      { type: "file_edit", title: "Set up connection pooling with PgBouncer", subtitle: "Database infra", facts: ["Deployed PgBouncer in transaction pooling mode", "Configured max 25 client connections, 10 server connections", "Added DATABASE_URL_DIRECT for migrations (bypasses pooler)"], narrative: "Deployed PgBouncer as a connection pooler for PostgreSQL. Using transaction pooling mode to maximize connection reuse. Configured separate DATABASE_URL for application use (through pooler) and DATABASE_URL_DIRECT for migrations.", concepts: ["pgbouncer", "connection-pooling", "postgresql", "infrastructure"], files: ["docker-compose.yml", ".env"], importance: 7 },
+      { type: "command_run", title: "Debug Prisma migration drift", subtitle: "Database debugging", facts: ["prisma migrate deploy failed with drift detected", "Cause: manual SQL ALTER was run directly on production", "Resolution: ran prisma migrate resolve to mark migration as applied"], narrative: "Production deployment failed because Prisma detected schema drift — someone had run a manual ALTER TABLE directly on the production database. Resolved by using prisma migrate resolve to mark the conflicting migration as already applied.", concepts: ["prisma", "migration-drift", "database", "production", "debugging"], files: ["prisma/schema.prisma"], importance: 7 },
+      { type: "file_edit", title: "Add Redis caching layer for expensive queries", subtitle: "Caching", facts: ["Used ioredis with 60-second TTL for post listings", "Implemented cache-aside pattern", "Added cache invalidation on post mutations"], narrative: "Added a Redis caching layer for expensive database queries. Post listings are cached for 60 seconds using a cache-aside pattern. Cache entries are invalidated when posts are created, updated, or deleted.", concepts: ["redis", "caching", "cache-aside", "ioredis", "performance"], files: ["src/lib/cache.ts", "src/app/actions/posts.ts"], importance: 7 },
+    ],
+  },
+  {
+    sessionRange: [15, 19],
+    daysAgoRange: [14, 10],
+    project: "webapp",
+    observations: [
+      { type: "file_edit", title: "Build REST API with input validation", subtitle: "API", facts: ["Created /api/v1/posts, /api/v1/users endpoints", "Used zod for request body validation", "Added consistent error response format with error codes"], narrative: "Built a versioned REST API under /api/v1/ with endpoints for posts and users. All request bodies are validated with zod schemas. Errors follow a consistent format with error codes, messages, and field-level details.", concepts: ["rest-api", "zod", "validation", "error-handling", "api-design"], files: ["src/app/api/v1/posts/route.ts", "src/app/api/v1/users/route.ts", "src/lib/api/errors.ts"], importance: 8 },
+      { type: "file_edit", title: "Implement cursor-based pagination", subtitle: "API pagination", facts: ["Replaced offset pagination with cursor-based approach", "Uses Prisma cursor with opaque base64-encoded cursors", "Returns hasNextPage and endCursor in response"], narrative: "Switched from offset-based to cursor-based pagination for the post listing API. Cursors are base64-encoded Prisma record IDs. Response includes hasNextPage boolean and endCursor for the client to request the next page.", concepts: ["pagination", "cursor-based", "prisma", "api-design", "performance"], files: ["src/app/api/v1/posts/route.ts", "src/lib/api/pagination.ts"], importance: 7 },
+      { type: "file_edit", title: "Add API rate limiting with Upstash Redis", subtitle: "Rate limiting", facts: ["Used @upstash/ratelimit with sliding window algorithm", "10 requests per 10 seconds per API key", "Returns X-RateLimit-Remaining header"], narrative: "Implemented API rate limiting using Upstash Redis with a sliding window algorithm. Each API key is limited to 10 requests per 10-second window. Rate limit status is communicated via standard X-RateLimit-* headers.", concepts: ["rate-limiting", "upstash", "redis", "api-security", "sliding-window"], files: ["src/middleware.ts", "src/lib/rate-limit.ts"], importance: 8 },
+      { type: "file_edit", title: "Create webhook system for external integrations", subtitle: "Webhooks", facts: ["Built webhook registration and delivery system", "Events: post.created, post.updated, user.signup", "Implemented retry with exponential backoff (max 3 retries)"], narrative: "Created a webhook system allowing external services to subscribe to events. Supports post.created, post.updated, and user.signup events. Webhook deliveries use exponential backoff with up to 3 retries on failure.", concepts: ["webhooks", "events", "integrations", "retry", "exponential-backoff"], files: ["src/lib/webhooks.ts", "src/app/api/v1/webhooks/route.ts"], importance: 7 },
+      { type: "file_edit", title: "Add OpenAPI specification with Swagger UI", subtitle: "API docs", facts: ["Generated OpenAPI 3.1 spec from zod schemas", "Added Swagger UI at /api/docs", "Included request/response examples"], narrative: "Generated an OpenAPI 3.1 specification from the existing zod validation schemas. Added Swagger UI accessible at /api/docs for interactive API documentation with request/response examples.", concepts: ["openapi", "swagger", "api-documentation", "zod"], files: ["src/app/api/docs/route.ts", "src/lib/openapi.ts"], importance: 5 },
+      { type: "command_run", title: "Debug 504 gateway timeout on large queries", subtitle: "Performance debugging", facts: ["Large post queries timing out after 30 seconds on Vercel", "Root cause: missing database index on posts.authorId", "Added composite index (authorId, createdAt DESC), query dropped to 50ms"], narrative: "Investigated 504 Gateway Timeout errors on the post listing endpoint in production (Vercel). Found that large queries filtering by author were doing a full table scan. Added a composite index on (authorId, createdAt DESC) which reduced query time from 30+ seconds to 50ms.", concepts: ["performance", "timeout", "database-index", "postgresql", "vercel", "debugging"], files: ["prisma/migrations/20260310_add_author_index.sql"], importance: 9 },
+      { type: "file_edit", title: "Implement API versioning strategy", subtitle: "API design", facts: ["URL-based versioning: /api/v1/, /api/v2/", "v1 deprecated with Sunset header", "Migration guide in API docs"], narrative: "Established an API versioning strategy using URL-based versioning (/api/v1/, /api/v2/). The v1 API returns a Sunset header indicating its deprecation date. Added a migration guide to the API documentation.", concepts: ["api-versioning", "deprecation", "sunset-header", "backward-compatibility"], files: ["src/app/api/v2/posts/route.ts", "src/lib/api/versioning.ts"], importance: 6 },
+      { type: "file_edit", title: "Add request logging with structured JSON", subtitle: "Observability", facts: ["Used pino for structured JSON logging", "Logs request method, path, status, duration, user ID", "Configured log levels per environment"], narrative: "Added structured JSON request logging using pino. Each request logs method, path, response status, duration in milliseconds, and authenticated user ID. Log levels are configured per environment (debug in dev, info in production).", concepts: ["logging", "pino", "observability", "structured-logging", "monitoring"], files: ["src/lib/logger.ts", "src/middleware.ts"], importance: 6 },
+    ],
+  },
+  {
+    sessionRange: [20, 24],
+    daysAgoRange: [9, 5],
+    project: "webapp",
+    observations: [
+      { type: "file_edit", title: "Write unit tests for auth module", subtitle: "Testing", facts: ["25 test cases covering login, signup, role checking", "Mocked Prisma client with vitest", "Achieved 92% coverage on auth module"], narrative: "Wrote comprehensive unit tests for the authentication module. 25 test cases covering login flow, signup validation, role-based access checks, and password hashing. Mocked the Prisma client using vitest's vi.mock. Achieved 92% code coverage.", concepts: ["unit-testing", "vitest", "mocking", "authentication", "coverage"], files: ["tests/unit/auth.test.ts", "tests/unit/rbac.test.ts"], importance: 7 },
+      { type: "file_edit", title: "Add E2E tests with Playwright", subtitle: "E2E testing", facts: ["Configured Playwright with Chrome and Firefox", "Tests: login flow, post CRUD, search, pagination", "Set up test database with Docker for isolation"], narrative: "Set up Playwright for end-to-end testing with Chrome and Firefox browsers. Created E2E tests for the complete login flow, post CRUD operations, search functionality, and pagination. Each test run gets a fresh database via Docker containers.", concepts: ["playwright", "e2e-testing", "docker", "test-isolation", "browser-testing"], files: ["playwright.config.ts", "tests/e2e/auth.spec.ts", "tests/e2e/posts.spec.ts", "docker-compose.test.yml"], importance: 8 },
+      { type: "command_run", title: "Fix flaky Playwright test on CI", subtitle: "CI debugging", facts: ["Test passed locally but failed in GitHub Actions", "Root cause: missing waitForNavigation after form submit", "Fixed by using page.waitForURL instead of waitForNavigation"], narrative: "Debugged a flaky Playwright test that passed locally but failed intermittently in GitHub Actions CI. The issue was a race condition after form submission — the test was checking the URL before navigation completed. Fixed by replacing the deprecated waitForNavigation with page.waitForURL.", concepts: ["playwright", "flaky-test", "ci", "github-actions", "debugging", "race-condition"], files: ["tests/e2e/auth.spec.ts"], importance: 6 },
+      { type: "file_edit", title: "Add API integration tests with supertest", subtitle: "API testing", facts: ["30 test cases for REST API endpoints", "Tests validation, auth, error responses, pagination", "Uses test database with transaction rollback"], narrative: "Created API integration tests using supertest. 30 test cases covering request validation, authentication requirements, error response formats, and cursor-based pagination. Each test runs in a database transaction that rolls back after completion.", concepts: ["integration-testing", "supertest", "api-testing", "transactions", "test-isolation"], files: ["tests/integration/api.test.ts"], importance: 7 },
+      { type: "file_edit", title: "Set up test coverage reporting with codecov", subtitle: "Coverage", facts: ["Configured vitest coverage with v8 provider", "Minimum coverage thresholds: 80% branches, 85% lines", "Upload to Codecov in CI pipeline"], narrative: "Configured vitest code coverage using the v8 provider. Set minimum coverage thresholds at 80% for branches and 85% for lines. Coverage reports are uploaded to Codecov as part of the GitHub Actions CI pipeline.", concepts: ["code-coverage", "codecov", "vitest", "ci", "quality-gates"], files: ["vitest.config.ts", ".github/workflows/ci.yml"], importance: 5 },
+      { type: "file_edit", title: "Create test fixtures and factories", subtitle: "Test infrastructure", facts: ["Built factory functions for User, Post, Comment, Tag", "Uses faker for realistic data generation", "Supports partial overrides for specific test scenarios"], narrative: "Created test factory functions for all main models (User, Post, Comment, Tag). Factories use faker.js for realistic data and support partial overrides so individual tests can customize specific fields.", concepts: ["test-factories", "faker", "testing-infrastructure", "fixtures"], files: ["tests/fixtures/factories.ts"], importance: 5 },
+      { type: "command_run", title: "Debug memory leak in test suite", subtitle: "Test debugging", facts: ["Tests consuming 2GB+ RAM after 100+ test files", "Root cause: Prisma client not disconnected in afterAll", "Fixed by adding global teardown that calls prisma.$disconnect()"], narrative: "Investigated why the test suite was consuming over 2GB of RAM. The Prisma client was creating new connections in each test file but never disconnecting. Fixed by adding a global teardown hook that calls prisma.$disconnect().", concepts: ["memory-leak", "testing", "prisma", "debugging", "resource-management"], files: ["vitest.config.ts", "tests/setup.ts"], importance: 7 },
+      { type: "file_edit", title: "Add snapshot testing for API responses", subtitle: "Snapshot tests", facts: ["Added toMatchSnapshot for API response shapes", "Snapshot updates require --update flag", "Catches unintended breaking changes in API responses"], narrative: "Added snapshot testing for API response shapes to catch unintended breaking changes. Response bodies are compared against stored snapshots. Snapshots must be explicitly updated with the --update flag when intentional changes are made.", concepts: ["snapshot-testing", "api-testing", "regression-testing", "vitest"], files: ["tests/integration/api.test.ts", "tests/integration/__snapshots__/"], importance: 4 },
+    ],
+  },
+  {
+    sessionRange: [25, 29],
+    daysAgoRange: [4, 0],
+    project: "webapp",
+    observations: [
+      { type: "file_edit", title: "Create multi-stage Dockerfile", subtitle: "Docker", facts: ["Multi-stage build: deps → build → production", "Final image size 180MB (down from 1.2GB)", "Runs as non-root user with UID 1001"], narrative: "Created a multi-stage Dockerfile for the Next.js application. Stage 1 installs dependencies, stage 2 builds the app, stage 3 copies only production artifacts. Final image is 180MB (down from 1.2GB). Application runs as a non-root user for security.", concepts: ["docker", "multi-stage-build", "containerization", "security", "image-optimization"], files: ["Dockerfile", ".dockerignore"], importance: 7 },
+      { type: "file_edit", title: "Set up GitHub Actions CI/CD pipeline", subtitle: "CI/CD", facts: ["Matrix build: Node 18 and 20", "Jobs: lint, test, build, deploy", "Auto-deploy to Vercel on main branch push"], narrative: "Created a comprehensive GitHub Actions CI/CD pipeline with matrix builds for Node 18 and 20. Pipeline runs lint, test (with coverage), build, and deploy jobs. Merges to main automatically trigger Vercel deployment.", concepts: ["github-actions", "ci-cd", "deployment", "vercel", "automation"], files: [".github/workflows/ci.yml", ".github/workflows/deploy.yml"], importance: 8 },
+      { type: "file_edit", title: "Configure Kubernetes deployment manifests", subtitle: "K8s", facts: ["Created Deployment, Service, Ingress, HPA resources", "HPA: min 2, max 10 replicas, CPU target 70%", "Health checks: liveness on /healthz, readiness on /readyz"], narrative: "Created Kubernetes deployment manifests including Deployment, Service, Ingress, and HorizontalPodAutoscaler. HPA scales between 2 and 10 replicas targeting 70% CPU utilization. Added liveness and readiness probes for health monitoring.", concepts: ["kubernetes", "deployment", "hpa", "autoscaling", "health-checks", "ingress"], files: ["k8s/deployment.yaml", "k8s/service.yaml", "k8s/ingress.yaml", "k8s/hpa.yaml"], importance: 8 },
+      { type: "file_edit", title: "Add Terraform for AWS infrastructure", subtitle: "IaC", facts: ["VPC with public/private subnets across 3 AZs", "RDS PostgreSQL with Multi-AZ failover", "ElastiCache Redis cluster with 2 replicas"], narrative: "Created Terraform modules for AWS infrastructure. VPC spans 3 availability zones with public and private subnets. RDS PostgreSQL instance with Multi-AZ failover for high availability. ElastiCache Redis cluster with 2 read replicas.", concepts: ["terraform", "aws", "infrastructure-as-code", "vpc", "rds", "elasticache"], files: ["terraform/main.tf", "terraform/vpc.tf", "terraform/rds.tf", "terraform/redis.tf"], importance: 8 },
+      { type: "command_run", title: "Debug Kubernetes pod crash loop", subtitle: "K8s debugging", facts: ["Pods in CrashLoopBackOff status", "Root cause: DATABASE_URL secret not mounted correctly", "Fixed: Secret key name was 'database-url' but env var expected 'DATABASE_URL'"], narrative: "Debugged pods stuck in CrashLoopBackOff. The application was failing to start because the DATABASE_URL environment variable was empty. Root cause: the Kubernetes secret had the key 'database-url' (kebab-case) but the secretKeyRef expected 'DATABASE_URL' (uppercase).", concepts: ["kubernetes", "debugging", "crashloopbackoff", "secrets", "environment-variables"], files: ["k8s/deployment.yaml", "k8s/secrets.yaml"], importance: 8 },
+      { type: "file_edit", title: "Set up Datadog monitoring and alerting", subtitle: "Monitoring", facts: ["Deployed Datadog agent as DaemonSet", "Custom metrics: request latency, error rate, DB query time", "Alerts: p99 latency > 500ms, error rate > 1%"], narrative: "Deployed the Datadog monitoring agent as a Kubernetes DaemonSet. Created custom metrics for request latency, error rate, and database query time. Set up alerts that trigger when p99 latency exceeds 500ms or error rate exceeds 1%.", concepts: ["datadog", "monitoring", "alerting", "observability", "kubernetes"], files: ["k8s/datadog-agent.yaml", "src/lib/metrics.ts"], importance: 7 },
+      { type: "file_edit", title: "Implement blue-green deployment strategy", subtitle: "Deployment", facts: ["Two identical environments: blue and green", "Health check must pass before traffic switch", "Instant rollback by switching back to previous color"], narrative: "Implemented blue-green deployment strategy. Two identical environments run simultaneously — deploy to the inactive one, run health checks, then switch traffic via Kubernetes service selector update. Rollback is instant by pointing traffic back to the previous color.", concepts: ["blue-green", "deployment-strategy", "zero-downtime", "rollback", "kubernetes"], files: ["k8s/blue-deployment.yaml", "k8s/green-deployment.yaml", "scripts/deploy.sh"], importance: 7 },
+      { type: "file_edit", title: "Add Prometheus metrics and Grafana dashboards", subtitle: "Observability", facts: ["Exported custom metrics via /metrics endpoint", "Metrics: http_request_duration, db_query_duration, cache_hit_ratio", "Created Grafana dashboard with request rate, latency, error panels"], narrative: "Added Prometheus metrics export on a /metrics endpoint. Custom metrics include HTTP request duration histogram, database query duration, and cache hit ratio. Created a Grafana dashboard with panels for request rate, latency percentiles, error rate, and cache performance.", concepts: ["prometheus", "grafana", "metrics", "observability", "dashboards"], files: ["src/lib/metrics.ts", "grafana/dashboard.json"], importance: 6 },
+    ],
+  },
+];
+
+export function generateDataset(): {
+  observations: CompressedObservation[];
+  queries: LabeledQuery[];
+  sessions: Map<string, string[]>;
+} {
+  const observations: CompressedObservation[] = [];
+  const sessions = new Map<string, string[]>();
+
+  for (const group of RAW_SESSIONS) {
+    const [sStart, sEnd] = group.sessionRange;
+    const [dStart, dEnd] = group.daysAgoRange;
+
+    for (let s = sStart; s <= sEnd; s++) {
+      const sessionId = `ses_${s.toString().padStart(3, "0")}`;
+      const daysAgo = dStart - ((s - sStart) / Math.max(1, sEnd - sStart)) * (dStart - dEnd);
+      const obsIds: string[] = [];
+
+      const obsPerSession = Math.min(group.observations.length, OBS_PER_SESSION);
+      for (let o = 0; o < obsPerSession; o++) {
+        const idx = ((s - sStart) * obsPerSession + o) % group.observations.length;
+        const raw = group.observations[idx];
+        const obsId = `obs_${sessionId}_${o.toString().padStart(2, "0")}`;
+        const hourOffset = o * 0.5;
+
+        observations.push({
+          id: obsId,
+          sessionId,
+          timestamp: ts(daysAgo - hourOffset / 24),
+          ...raw,
+        });
+        obsIds.push(obsId);
+      }
+      sessions.set(sessionId, obsIds);
+    }
+  }
+
+  const queries: LabeledQuery[] = [
+    {
+      query: "How did we set up authentication?",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["nextauth", "authentication", "oauth", "jwt", "login", "signup"].includes(c))).map(o => o.id),
+      description: "Should find all auth-related observations across sessions 5-9",
+      category: "semantic",
+    },
+    {
+      query: "JWT token validation middleware",
+      relevantObsIds: observations.filter(o => o.concepts.includes("jwt") || (o.concepts.includes("middleware") && o.concepts.includes("authentication"))).map(o => o.id),
+      description: "Exact match on JWT middleware setup",
+      category: "exact",
+    },
+    {
+      query: "PostgreSQL connection issues",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["postgresql", "pgbouncer", "connection-pooling", "database"].includes(c))).map(o => o.id),
+      description: "Should find database connection and pooling observations",
+      category: "semantic",
+    },
+    {
+      query: "Playwright test configuration",
+      relevantObsIds: observations.filter(o => o.concepts.includes("playwright") || (o.concepts.includes("e2e-testing"))).map(o => o.id),
+      description: "E2E testing setup with Playwright",
+      category: "exact",
+    },
+    {
+      query: "Why did the production deployment fail?",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["debugging", "production", "crashloopbackoff", "timeout", "migration-drift"].includes(c))).map(o => o.id),
+      description: "Cross-session: find all production debugging incidents",
+      category: "cross-session",
+    },
+    {
+      query: "rate limiting implementation",
+      relevantObsIds: observations.filter(o => o.concepts.includes("rate-limiting")).map(o => o.id),
+      description: "Rate limiting across auth and API modules",
+      category: "exact",
+    },
+    {
+      query: "What security measures did we add?",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["security", "csrf", "bcrypt", "rate-limiting", "rbac", "password-hashing"].includes(c))).map(o => o.id),
+      description: "Broad semantic: all security-related work",
+      category: "semantic",
+    },
+    {
+      query: "database performance optimization",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["n+1", "query-optimization", "database-index", "performance", "eager-loading", "caching"].includes(c))).map(o => o.id),
+      description: "Performance optimizations across database and caching",
+      category: "semantic",
+    },
+    {
+      query: "Kubernetes pod crash debugging",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["crashloopbackoff", "kubernetes"].includes(c)) && o.concepts.includes("debugging")).map(o => o.id),
+      description: "Specific K8s debugging incident",
+      category: "entity",
+    },
+    {
+      query: "Docker containerization setup",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["docker", "multi-stage-build", "containerization", "dockerfile"].includes(c))).map(o => o.id),
+      description: "Docker-related observations",
+      category: "entity",
+    },
+    {
+      query: "How does caching work in the app?",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["redis", "caching", "cache-aside", "ioredis", "elasticache"].includes(c))).map(o => o.id),
+      description: "All caching-related observations",
+      category: "semantic",
+    },
+    {
+      query: "test infrastructure and factories",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["test-factories", "testing-infrastructure", "fixtures", "mocking"].includes(c))).map(o => o.id),
+      description: "Test setup infrastructure",
+      category: "exact",
+    },
+    {
+      query: "What happened with the OAuth callback error?",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["oauth-debugging", "callback-url"].includes(c))).map(o => o.id),
+      description: "Specific debugging incident recall",
+      category: "cross-session",
+    },
+    {
+      query: "monitoring and observability setup",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["datadog", "prometheus", "grafana", "monitoring", "observability", "alerting", "metrics", "logging", "pino"].includes(c))).map(o => o.id),
+      description: "All monitoring/observability observations",
+      category: "semantic",
+    },
+    {
+      query: "Prisma ORM configuration",
+      relevantObsIds: observations.filter(o => o.concepts.includes("prisma")).map(o => o.id),
+      description: "All Prisma-related observations",
+      category: "entity",
+    },
+    {
+      query: "CI/CD pipeline configuration",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["ci-cd", "github-actions", "deployment", "ci"].includes(c))).map(o => o.id),
+      description: "CI/CD related observations",
+      category: "exact",
+    },
+    {
+      query: "memory leak debugging",
+      relevantObsIds: observations.filter(o => o.concepts.includes("memory-leak")).map(o => o.id),
+      description: "Memory leak incidents (WebSocket handler, test suite)",
+      category: "cross-session",
+    },
+    {
+      query: "API design decisions",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["rest-api", "api-design", "api-versioning", "pagination", "openapi", "error-handling"].includes(c))).map(o => o.id),
+      description: "API design and architecture decisions",
+      category: "semantic",
+    },
+    {
+      query: "zod validation schemas",
+      relevantObsIds: observations.filter(o => o.concepts.includes("zod")).map(o => o.id),
+      description: "Where zod is used for validation",
+      category: "entity",
+    },
+    {
+      query: "infrastructure as code Terraform",
+      relevantObsIds: observations.filter(o => o.concepts.some(c => ["terraform", "infrastructure-as-code", "aws", "vpc", "rds", "elasticache"].includes(c))).map(o => o.id),
+      description: "Terraform/IaC observations",
+      category: "entity",
+    },
+  ];
+
+  return { observations, queries, sessions };
+}
+
+export function generateScaleDataset(count: number): CompressedObservation[] {
+  const base = generateDataset().observations;
+  const result: CompressedObservation[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const src = base[i % base.length];
+    result.push({
+      ...src,
+      id: `obs_scale_${i.toString().padStart(6, "0")}`,
+      sessionId: `ses_${Math.floor(i / 8).toString().padStart(4, "0")}`,
+      timestamp: ts(Math.random() * 90),
+      title: `${src.title} (iteration ${i})`,
+      narrative: `${src.narrative} [Scale test variant ${i}, session group ${Math.floor(i / 8)}]`,
+    });
+  }
+  return result;
+}