Intial Files

AGENTS.md

@@ -1,289 +0,0 @@
-# agentcache-python — Agent Instructions
-
-## What this project is
-
-A Python REST + WebSocket + MCP memory server backed by SQLite. No Node.js, no iii-engine, no Dolt. Agents use it to store observations scoped to `(folder_path, agent_id)` pairs and global long-term memories. The viewer, MCP tools, and REST API are built around the **folder-based memory model** — sessions, lessons, slots, and actions are removed.
-
-## Project layout
-
-```
-src/
-├── app.py              Thin Flask factory — create_app(), WebSocket, CORS hook
-├── cli.py              CLI entrypoint (agentcache serve/migrate/export)
-├── connect.py          Client connection helper
-├── db.py               StateKV — SQLite WAL, per-thread connections, stats()
-├── functions.py        All canonical business logic (large; memory/ shims delegate here)
-├── search.py           BM25 + VectorIndex + HybridSearch + 3 embedding providers
-├── viewer_helpers.py   Viewer HTML injection helper
-├── workers.py          Background threads — index rebuild, auto-forget, SIGTERM handler
-│
-├── routes/             Flask blueprints
-│   ├── observations.py   /observe, /agent/observe, /folders, /folder/observations
-│   ├── memories.py       /remember, /agent/remember, /memories, /forget
-│   ├── search.py         /search, /timeline
-│   ├── graph.py          /graph, /graph/stats, /graph/query, /graph/build
-│   ├── health.py         /livez, /health, /audit, /config/flags
-│   ├── mcp.py            /mcp/tools GET+POST (12 active tools)
-│   └── migration.py      /migrate
-│
-├── memory/             Thin shim package — delegates to functions.py
-│   ├── observe.py        folder_observe, observe, build_synthetic_compression, strip_private_data
-│   ├── remember.py       remember, forget, jaccard_similarity
-│   ├── context.py        context, export_data, rebuild_index
-│   ├── graph.py          folder_graph_build
-│   ├── timeline.py       folder_timeline, folder_search
-│   └── health.py         health_check, auto_forget
-│
-├── storage/            KV scope registry + path/ID utilities
-│   ├── scopes.py         KV class (mirrored from functions.py)
-│   ├── paths.py          normalize_folder_path, validate_agent_id, generate_id, fingerprint_id
-│   └── images.py         save_image_to_disk, delete_image, touch_image
-│
-└── viewer/
-    └── index.html      Single-file HTML dashboard (4 tabs: Folders / Memories / Graph / Timeline)
-
-sync.py             HuggingFace dataset backup/restore
-Dockerfile          HF Space container definition
-start.sh            Boot: restore DB → start server → start sync loop
-requirements.txt    flask, flask-sock, requests, websockets, python-dateutil, huggingface_hub
-pyproject.toml      pip-installable package (agentcache==0.9.8, Python ≥3.10)
-tests/              pytest suite — unit, integration, and Hypothesis property tests
-```
-
-## Running
-
-```bash
-pip install -r requirements.txt
-python src/app.py
-# Server on http://localhost:3111
-# Viewer at http://localhost:3111/viewer
-```
-
-No build step. No external database. SQLite file lives at `~/.agentcache/agentcache.db`.
-
-## Architecture
-
-### Data Model — Folder-Based Memory
-
-The primary unit of storage is `(folder_path, agent_id)`. Each agent accumulates observations scoped to the folder it is working in. Global long-term memories remain unchanged.
-
-### Storage — `src/db.py`
-
-`StateKV` wraps a single SQLite file with:
-- `kv_store(scope TEXT, key TEXT, value TEXT, PRIMARY KEY(scope, key))` — all data as JSON
-- `audit_log(id, ts, agent_id, message)` — write audit trail
-- `sync_state_metadata(key, value)` — HuggingFace sync watermark
-
-Per-thread persistent connections via `threading.local()`. WAL checkpoint registered via `atexit` and on `SIGTERM`/`SIGINT`.
-
-Key scopes (defined in `functions.py` `KV` class and mirrored in `src/storage/scopes.py`):
-
-| Scope | Content |
-|-------|---------|
-| `mem:folders` | Index of all `(folder_path, agent_id)` pairs — key = `"{path}:{agent}"` |
-| `mem:folder:{path}:{agent}` | Observations for a pair — key = obs_id |
-| `mem:foldermeta:{path}:{agent}` | Metadata for a pair (obsCount, lastUpdated, summary) |
-| `mem:obs_lookup` | O(1) reverse-lookup: obs_id → `{folderPath, agentId}` |
-| `mem:memories` | Global long-term memories |
-| `mem:index:bm25:*` | Sharded BM25 index (2MB chunks) |
-| `mem:audit` | Audit log entries |
-| `mem:relations` | Knowledge graph edges |
-| `mem:sessions` | Legacy session store (read-only, migration only) |
-| `mem:obs:{session_id}` | Legacy per-session observations (read-only, migration only) |
-
-### Business logic — `src/functions.py`
-
-All canonical implementations live here. `src/memory/*` are thin shims that re-export from this module (for future decoupling).
-
-**Observation pipeline:**
-```
-raw payload → normalize_folder_path() → validate_agent_id() → strip_private_data()
-→ build obs dict → kv.set(folder_obs scope) → upsert folder_meta + folders index
-→ kv.set(obs_lookup) → BM25-indexed → vector-indexed (if key set)
-→ schedule_save() (debounced 5s) → audit log → WebSocket broadcast
-```
-
-**Memory versioning:** `remember()` checks Jaccard similarity against existing memories. If > 0.7 match found, new memory supersedes old (`isLatest=False` on old, `parentId` set on new).
-
-**Search:** `folder_search()` uses `HybridSearch` (BM25 + vector, RRF k=60). Falls back to BM25-only when no embedding provider is configured. Results include both folder observations and global memories.
-
-**`health_check()`** returns: `folderCount`, `agentCount`, `pairCount`, `observationCount`, `memoryCount`, `bm25IndexSize`, `vectorIndexSize`, `dbPath`, plus `db.stats()` fields.
-
-### Search — `src/search.py`
-
-- `SearchIndex`: BM25 with Porter stemmer and synonym expansion. Dirty-flag (`_dirty`) prevents unnecessary saves. Persisted in sharded 2MB KV chunks.
-- `VectorIndex`: cosine similarity over embeddings stored as base64-encoded float32 arrays. Also has `_dirty` flag.
-- `HybridSearch`: fuses BM25 + vector scores with RRF (k=60).
-
-**Embedding providers** (auto-selected by priority in `create_app()`):
-
-| Priority | Provider | Env var | Dimensions |
-|----------|----------|---------|------------|
-| 1 | `GeminiEmbeddingProvider` | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | 768 |
-| 2 | `OpenAIEmbeddingProvider` | `OPENAI_API_KEY` | 1536 |
-| 3 | `SentenceTransformerProvider` | `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | variable |
-| 4 | BM25-only | — | — |
-
-### Server — `src/app.py`
-
-Boot order:
-1. Load `~/.agentcache/.env` if present
-2. Initialize `StateKV` (SQLite)
-3. Auto-select embedding provider (Gemini → OpenAI → SentenceTransformer → BM25-only)
-4. Initialize `IndexPersistence` (load or rebuild)
-5. Backfill `obs_lookup` index if missing
-6. Create Flask app, register blueprints
-7. Set up WebSocket `/stream/mem-live/viewer`
-8. Register CORS `after_request` hook
-9. Start background workers (index rebuild if empty/stale, auto-forget loop)
-
-Auth: all endpoints check `AGENTCACHE_SECRET` via `hmac.compare_digest`. `/livez` is always open.
-
-## MCP Tools
-
-The server exposes **12 MCP tools** via `GET /agentcache/mcp/tools` and `POST /agentcache/mcp/tools`.
-
-| Tool | Description | Status |
-|------|-------------|--------|
-| `agent_observe` | Log observation to a `(folderPath, agentId)` pair | Working |
-| `agent_remember` | Save to global long-term memory | Working |
-| `memory_recall` | Search folder obs + global memories (BM25+vector) | Working |
-| `memory_smart_search` | Hybrid semantic+keyword search (alias for recall) | Working |
-| `memory_save` | Explicitly save insight to long-term memory | Working |
-| `memory_export` | Export all data as JSON (v2 format) | Working |
-| `memory_forget` | Delete memory or folder pair observations | Working |
-| `memory_diagnose` | Health check (folder/agent/obs/memory counts) | Working |
-| `memory_folders` | List all `(folder, agent)` pairs | Working |
-| `memory_folder_observations` | Get observations for a specific pair | Working |
-| `memory_timeline` | Folder activity feed (sorted by time, filterable) | Working |
-
-**MCP stdio wrapper:** `src/mcp_stdio.py` reads `AGENTCACHE_URL` and `AGENTCACHE_SECRET` from environment variables dynamically.
-
-## Consistency rules
-
-**When adding a REST endpoint:**
-1. Add the route in the appropriate `src/routes/*.py` blueprint
-2. Update the `API Reference` section in `README.md`
-3. Add the MCP tool in `src/routes/mcp.py` if it should be agent-callable
-
-**When adding an MCP tool:**
-1. Add the schema to the `GET /mcp/tools` response in `src/routes/mcp.py`
-2. Add the handler case to the `POST /mcp/tools` dispatch in `src/routes/mcp.py`
-3. Update the tool table in `README.md`
-4. Update `AGENTS.md` tool list
-
-**When changing data scopes:**
-1. Update the `KV` class in `src/functions.py` (canonical)
-2. Mirror the change in `src/storage/scopes.py`
-3. Update the scope table in this file
-
-## Code patterns
-
-### Adding a new KV scope
-
-```python
-# In src/functions.py KV class (canonical):
-class KV:
-    your_scope = "mem:your-scope"
-
-    @staticmethod
-    def your_dynamic_scope(id: str) -> str:
-        return f"mem:your-scope:{id}"
-```
-
-### Adding a REST endpoint
-
-```python
-# In the appropriate src/routes/*.py blueprint:
-@your_bp.route('/agentcache/your-path', methods=['POST'])
-def your_endpoint():
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-    body = request.get_json(force=True) or {}
-    # validate fields explicitly — never pass raw body to functions
-    result = functions.your_function(_get_kv(), body.get('field'))
-    return jsonify(result), 200
-```
-
-### Adding an MCP tool schema
-
-In `src/routes/mcp.py`, `GET /agentcache/mcp/tools` handler:
-```python
-{
-    "name": "memory_your_tool",
-    "description": "What it does",
-    "inputSchema": {
-        "type": "object",
-        "properties": {
-            "query": {"type": "string", "description": "..."}
-        },
-        "required": ["query"]
-    }
-}
-```
-
-In `src/routes/mcp.py`, `POST /agentcache/mcp/tools` handler:
-```python
-elif tool_name == 'memory_your_tool':
-    query = args.get('query', '')
-    result = functions.your_function(kv, query)
-    return jsonify({'content': [{'type': 'text', 'text': json.dumps(result)}]})
-```
-
-## Environment variables
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `III_REST_PORT` / `PORT` | `3111` | Server port |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables Gemini vector search (priority 1) |
-| `OPENAI_API_KEY` | — | Enables OpenAI vector search (priority 2) |
-| `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | — | SentenceTransformer model name (priority 3) |
-| `AGENTCACHE_SECRET` | — | Bearer token auth |
-| `AGENT_ID` | — | Default agent ID |
-| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filter data to current agent |
-| `AGENTCACHE_CWD` | — | Fallback folder path for legacy clients |
-| `MAX_OBS_PER_FOLDER` | `2000` | Observations hard cap per (folder, agent) pair |
-| `TOKEN_BUDGET` | `2000` | Context compilation cap |
-| `GRAPH_EXTRACTION_ENABLED` | `false` | Graph extraction (needs LLM) |
-| `CONSOLIDATION_ENABLED` | `false` | Consolidation (needs LLM) |
-| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM compression |
-| `AUTO_FORGET_ENABLED` | — | Auto-forget sweep (set to "false" to disable) |
-| `AGENTCACHE_CORS_ORIGINS` | see app.py | Comma-separated allowed origins |
-| `AGENTCACHE_IMAGE_STORE_MAX_BYTES` | 500MB | Image store byte limit |
-| `HF_TOKEN` | — | HuggingFace sync |
-| `AGENTCACHE_DATASET_REPO` | — | HF dataset repo for backup |
-
-## Testing
-
-```bash
-pip install -e ".[dev]"
-pytest tests/ -v
-```
-
-Tests live in `tests/` — 17 test files covering unit tests, integration tests (Flask test client), and Hypothesis property tests.
-
-Key test files:
-- `tests/test_properties.py` — 8 correctness properties (pair isolation, obs count consistency, index coverage, privacy, timeline ordering, forget completeness, memory version uniqueness, path normalization idempotency)
-- `tests/test_api.py` — Flask test client integration tests
-- `tests/test_route_regressions.py` — regression suite after blueprint split
-
-## HuggingFace Space deployment
-
-Data flow: `agentcache.db` (SQLite) ↔ `sync.py` ↔ HF dataset repo.
-
-`start.sh` sequence:
-1. Restore `agentcache.db` from dataset repo
-2. Start `python src/app.py` in background
-3. Run `sync.py` in a loop (backup every ~60s if changed)
-
-## Viewer — `src/viewer/index.html`
-
-Single-file HTML dashboard, served directly by Flask at `/viewer`. No build step, no bundler.
-
-Tabs: **Folders**, **Memories**, **Graph**, **Timeline**.
-
-- **Folders tab**: lists all `(folder, agent)` pairs; click a row to drill into observations
-- **Memories tab**: global long-term memories with search
-- **Graph tab**: force-directed graph — nodes = folder paths, edges = same-parent / cross-ref / agent-shared
-- **Timeline tab**: all observations sorted by timestamp desc, filterable by folder path and agent ID

ARCHITECTURE.md

@@ -1,144 +0,0 @@
-# agentcache-python — Architecture
-
-## Overview
-
-A Python REST + WebSocket + MCP memory server backed by SQLite.
-Agents store observations scoped by `(folderPath, agentId)` pairs and retrieve
-context at session start. No Node.js, no external database, no build step.
-
----
-
-## Module Responsibilities
-
-```
-src/
-├── app.py              Flask application factory (create_app).
-│                       Initialises DB, embeddings, blueprints, WebSocket,
-│                       CORS hook, and background workers.
-│
-├── routes/             Flask blueprints — one per domain area.
-│   ├── __init__.py     register_blueprints(app) helper.
-│   ├── observations.py /observe, /agent/observe, /folders, /folder/observations
-│   ├── memories.py     /remember, /agent/remember, /memories, /forget
-│   ├── search.py       /search, /timeline
-│   ├── graph.py        /graph, /graph/stats, /graph/query, /graph/build
-│   ├── health.py       /livez, /health, /audit, /config/flags
-│   ├── mcp.py          GET+POST /mcp/tools
-│   └── migration.py    /migrate
-│
-├── functions.py        Core business logic.
-│                       observe(), folder_observe(), remember(), forget(),
-│                       folder_search(), folder_timeline(), health_check(),
-│                       export_data(), rebuild_index(), auto_forget(),
-│                       folder_graph_build(), KV scope registry.
-│
-├── db.py               StateKV — SQLite wrapper (WAL mode, kv_store + audit_log).
-│
-├── search.py           SearchIndex (BM25 + Porter stemmer + synonyms),
-│                       VectorIndex (cosine similarity, base64 float32),
-│                       GeminiEmbeddingProvider, HybridSearch (RRF).
-│
-├── workers.py          Daemon threads: index rebuild, auto-forget sweep,
-│                       graceful shutdown (SIGTERM/SIGINT).
-│
-├── viewer_helpers.py   make_viewer_response() — reads viewer/index.html,
-│                       injects nonce + version, sets CSP headers.
-│
-├── mcp_stdio.py        stdio MCP bridge: reads AGENTCACHE_URL and
-│                       AGENTCACHE_SECRET, proxies tool calls to the HTTP API.
-│
-└── viewer/
-    └── index.html      Single-file HTML dashboard (no bundler).
-```
-
----
-
-## KV Scope Layout
-
-All data lives in a single SQLite file (`~/.agentcache/agentcache.db`) in two tables:
-
-- `kv_store(scope TEXT, key TEXT, value TEXT, PRIMARY KEY(scope, key))` — JSON values
-- `audit_log(id, ts, agent_id, message)` — write audit trail
-
-| Scope | Content |
-|-------|---------|
-| `mem:folders` | Global index of all `(folderPath, agentId)` pairs |
-| `mem:folder:{path}:{agent}` | Observations for one `(folder, agent)` pair |
-| `mem:foldermeta:{path}:{agent}` | Metadata for one pair (obsCount, lastUpdated, summary) |
-| `mem:memories` | Long-term global memories |
-| `mem:index:bm25` | BM25 index shards (manifest + data chunks) |
-| `mem:audit` | Audit log entries (via `record_audit()`) |
-| `mem:relations` | Knowledge graph edges |
-| `mem:sessions` | Legacy session objects (read-only for migration) |
-| `mem:obs:{session_id}` | Legacy session observations (read-only for migration) |
-
----
-
-## Data Flow
-
-### Observation Ingestion
-
-```
-POST /agent/observe
-  └─► folder_observe(kv, payload)
-        1. Validate folderPath, agentId, text, timestamp
-        2. normalize_folder_path() + validate_agent_id()
-        3. strip_private_data()
-        4. Cap text at 4000 chars
-        5. Enforce MAX_OBS_PER_FOLDER cap
-        6. Generate obs_id (fobs_...)
-        7. Write FolderObservation to KV.folder_obs(fp, aid)
-        8. Upsert folder metadata (KV.folder_meta)
-        9. Upsert global folders index (KV.folders)
-       10. Add to BM25 index (_bm25_index.add)
-       11. Add to vector index if embedding provider is set
-       12. Debounce persistence save (IndexPersistence.schedule_save)
-       13. Write audit log entry (kv.commit_version)
-       14. Broadcast via WebSocket (/stream/mem-live/viewer)
-        └─► return {"observationId": obs_id}
-```
-
-### Search
-
-```
-POST /search  or  POST /mcp/tools {name:"memory_recall"}
-  └─► folder_search(kv, query, limit, folderPath?, agentId?)
-        1. HybridSearch.search() → BM25 + vector RRF fusion
-        2. Load all (folder, agent) pairs from KV.folders
-        3. Hydrate obs_ids from KV.folder_obs scopes
-        4. Apply folderPath/agentId post-filters
-        5. Also include matching global memories
-        6. Sort by score descending, cap at limit
-```
-
-### Memory Versioning
-
-`remember()` scans existing memories for Jaccard similarity > 0.7.
-If found, old memory is marked `isLatest=False` and new memory sets `parentId`.
-
----
-
-## Authentication
-
-All endpoints except `/livez` check `AGENTCACHE_SECRET` via timing-safe
-`hmac.compare_digest` Bearer token comparison. No secret → no auth check.
-
----
-
-## WebSocket
-
-`/stream/mem-live/viewer` broadcasts raw JSON payloads to connected viewers.
-The viewer's "Replay" tab subscribes to this stream for live observation updates.
-
----
-
-## Embedding Providers
-
-Priority order (auto-selected at startup):
-
-1. `GeminiEmbeddingProvider` — if `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set (768 dims)
-2. `OpenAIEmbeddingProvider` — if `OPENAI_API_KEY` is set (1536 dims)
-3. `SentenceTransformerProvider` — if `AGENTCACHE_LOCAL_EMBEDDING_MODEL` is set
-4. BM25-only fallback
-
-Without an embedding provider, `HybridSearch` falls back to pure BM25.

CHANGELOG.md

@@ -1,69 +0,0 @@
-# Changelog
-
-All notable changes to agentmemory-python are documented here.
-
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions track the Python reimplementation, not the upstream Node.js agentmemory releases.
-
----
-
-## [Unreleased]
-
----
-
-## [1.0.0] — 2026-06-09
-
-Initial public release of the Python reimplementation.
-
-### Added
-
-- **Flask REST server** (`src/app.py`) — full API surface matching the agentmemory wire format: sessions, observations, memories, lessons, slots, relations, actions, replay, context, search, MCP
-- **SQLite storage** (`src/db.py`) — `StateKV` backed by a single WAL-mode SQLite file at `~/.agentmemory/agentmemory.db`; replaces Dolt SQL Server
-- **Audit log** — `audit_log(id, ts, agent_id, message)` table replaces Dolt git versioning; every write is tracked
-- **BM25 search** (`src/search.py`) — custom Porter stemmer, in-memory index, persisted to DB in 2MB shards
-- **Vector search** (`src/search.py`) — Gemini `text-embedding-004` 768-dim cosine similarity; enabled by `GEMINI_API_KEY`
-- **Hybrid search** — RRF fusion of BM25 + vector (k=60), session-diversified (max 3 per session)
-- **MCP tools endpoint** — 16 tools via `GET/POST /agentmemory/mcp/tools`
-- **WebSocket live stream** — `/stream/mem-live/viewer` broadcasts all observations in real time
-- **Built-in viewer** (`src/viewer/index.html`) — single-file HTML dashboard: Dashboard, Sessions, Memories, Graph, Timeline, Lessons, Slots, Replay tabs
-- **Knowledge graph visualization** — Graph tab shows project folders as nodes with unique hash-based HSL colors; edges represent shared concepts or common parent paths
-- **4-tier memory consolidation** — Working → Episodic → Semantic → Procedural; enabled by `CONSOLIDATION_ENABLED=true` + LLM key
-- **Lessons system** — confidence-scored, fingerprinted by SHA-256, duplicate saves strengthen confidence, weekly decay, auto-evict below 0.1
-- **Memory versioning** — Jaccard similarity check; memories with > 0.7 overlap supersede each other with `parentId` linkage
-- **Session lifecycle** — start, end, commit with summary; auto-close dangling active sessions on new session start
-- **HuggingFace Space support** — `Dockerfile`, `start.sh`, `sync.py` for deploy-and-forget on HF Spaces
-- **Sync with fingerprinting** (`sync.py`) — mtime+size hash prevents redundant uploads; only backs up when DB actually changed
-- **Privacy filtering** — API keys, secrets, `<private>` tags stripped before storage
-- **Bearer token auth** — timing-safe `hmac.compare_digest` check on all endpoints when `AGENTMEMORY_SECRET` is set
-- **Agent scope isolation** — `AGENTMEMORY_AGENT_SCOPE=isolated` filters all reads to the current `AGENT_ID`
-
-### Migrated
-
-- `migrate_dolt_to_sqlite.py` — one-time migration script that reads all rows from a local Dolt SQL server and writes them to SQLite; migrated 7502 rows (19.6MB) from the original deployment
-
-### Removed
-
-- Dolt SQL server dependency — no more `dolt sql-server`, no more `pymysql`, no more Dolt install in Dockerfile
-- Node.js / iii-engine dependency — the entire iii-engine binary and worker model is gone
-- `start.sh` Dolt startup block — `sleep 5`, `DOLT_*` env vars, migration step all removed
-
-### Dependencies (6 total)
-
-```
-flask>=3.0.0
-flask-sock>=0.7.0
-requests>=2.31.0
-websockets>=12.0
-python-dateutil>=2.8.2
-huggingface_hub>=0.20.0
-```
-
----
-
-## Format
-
-- **Added** — new features
-- **Changed** — changes to existing behavior
-- **Fixed** — bug fixes
-- **Removed** — removed features
-- **Security** — security fixes
-- **Migrated** — data or infrastructure migrations

CLAUDE.md

@@ -1,109 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What This Is
-
-A Python REST + WebSocket + MCP memory server backed by SQLite. No Node.js, no Dolt. Agents use it to store observations scoped to `(folder_path, agent_id)` pairs and global long-term memories. The architecture is **folder-based** — sessions, lessons, slots, and actions are removed.
-
-## Running
-
-```bash
-pip install -r requirements.txt
-python src/app.py
-# Server on http://localhost:3111
-# Viewer at http://localhost:3111/viewer
-```
-
-No build step. SQLite file lives at `~/.agentcache/agentcache.db`. Config optionally loaded from `~/.agentcache/.env`.
-
-## Running Tests
-
-```bash
-pip install -e ".[dev]"
-pytest tests/ -v
-```
-
-## Key Environment Variables
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `III_REST_PORT` / `PORT` | `3111` | API server port |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Gemini vector search (priority 1) |
-| `OPENAI_API_KEY` | — | OpenAI vector search (priority 2) |
-| `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | — | SentenceTransformer model (priority 3) |
-| `AGENTCACHE_SECRET` | — | Bearer token auth on all endpoints |
-| `AGENT_ID` | — | Default agent ID |
-| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filter data to current `AGENT_ID` |
-| `AGENTCACHE_CWD` | — | Fallback folder path for legacy clients |
-| `MAX_OBS_PER_FOLDER` | `2000` | Hard cap on observations per (folder, agent) pair |
-| `TOKEN_BUDGET` | `2000` | Context compilation cap |
-| `GRAPH_EXTRACTION_ENABLED` | `false` | Knowledge graph extraction (needs LLM) |
-| `CONSOLIDATION_ENABLED` | `false` | Memory consolidation (needs LLM) |
-| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM-powered observation compression |
-| `AGENTCACHE_CORS_ORIGINS` | see app.py | Comma-separated allowed CORS origins |
-
-## Architecture
-
-### `src/db.py` — Storage Layer
-
-`StateKV` wraps SQLite with two tables:
-- `kv_store(scope, key, value)` — all data as JSON, namespaced by scope
-- `audit_log(id, ts, agent_id, message)` — write audit trail
-
-Per-thread persistent connections via `threading.local()`. WAL checkpoint on shutdown.
-
-Key scopes: `mem:folders` (index), `mem:folder:{path}:{agent}` (observations), `mem:foldermeta:{path}:{agent}` (metadata), `mem:obs_lookup` (O(1) reverse lookup), `mem:memories` (global), `mem:index:bm25:*` (search).
-
-### `src/functions.py` — Business Logic
-
-All core implementations. Key functions:
-- `folder_observe(kv, payload)` — ingest a folder-scoped observation
-- `folder_search(kv, query, limit, folder_path, agent_id)` — BM25+vector hybrid search
-- `folder_timeline(kv, limit, folder_path, agent_id, before, after)` — activity feed
-- `folder_graph_build(kv)` — build graph nodes + edges
-- `remember(kv, data)` / `forget(kv, data)` — global memory management
-- `health_check(kv)` — system stats
-- `export_data(kv, data)` — v2 JSON export
-- `migrate_sessions_to_folders(kv, dry_run)` — legacy migration
-
-`src/memory/*` contains thin shim modules that re-export from here.
-
-### `src/search.py` — Search Indexes
-
-- `SearchIndex`: BM25 with Porter stemmer + synonym expansion. `_dirty` flag prevents unnecessary saves.
-- `VectorIndex`: cosine similarity over embeddings as base64 float32. `_dirty` flag.
-- `HybridSearch`: RRF fusion (k=60) of BM25 + vector.
-- `GeminiEmbeddingProvider`, `OpenAIEmbeddingProvider`, `SentenceTransformerProvider`.
-
-### `src/app.py` — Flask Factory
-
-`create_app()`: init DB → auto-select embedding provider → init IndexPersistence → backfill obs_lookup → register blueprints → setup WebSocket → register CORS → start background workers.
-
-### `src/routes/` — Flask Blueprints
-
-| Blueprint | Endpoints |
-|-----------|-----------|
-| `observations.py` | `/observe`, `/agent/observe`, `/folders`, `/folder/observations`, legacy session shims |
-| `memories.py` | `/remember`, `/agent/remember`, `/memories`, `/forget` |
-| `search.py` | `/search`, `/timeline` |
-| `graph.py` | `/graph`, `/graph/stats`, `/graph/query`, `/graph/build` |
-| `health.py` | `/livez`, `/health`, `/audit`, `/config/flags` |
-| `mcp.py` | `/mcp/tools` GET+POST (12 tools) |
-| `migration.py` | `/migrate` |
-
-### `src/workers.py` — Background Threads
-
-- Index rebuild thread (if BM25 index is empty or out of sync on boot)
-- Auto-forget sweep loop (hourly)
-- SIGTERM/SIGINT handlers: flush `IndexPersistence`, WAL checkpoint, exit 0
-
-### `src/viewer/index.html` — Dashboard
-
-Single-file HTML, served at `/viewer`. Tabs: **Folders**, **Memories**, **Graph**, **Timeline**. No build step.
-
-## MCP Tools (12 active)
-
-`agent_observe`, `agent_remember`, `memory_recall`, `memory_smart_search`, `memory_save`, `memory_export`, `memory_forget`, `memory_diagnose`, `memory_folders`, `memory_folder_observations`, `memory_timeline`
-
-Full schema at `GET /agentcache/mcp/tools`.

CODE_OF_CONDUCT.md

@@ -1,48 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# Contributing to agentmemory-python
-
-Thanks for your interest. This covers the path from "I have an idea" to "it's merged."
-
-## License
-
-Apache-2.0. Every contribution is covered by it.
-
-## Before opening an issue
-
-Search [open issues](https://github.com/Yashwant00CR7/agentcache/issues?q=is%3Aopen) and [closed issues](https://github.com/Yashwant00CR7/agentcache/issues?q=is%3Aclosed) first.
-
-**Bug reports** — include:
-- Python version (`python --version`)
-- OS
-- Exact steps to reproduce
-- What you expected vs. what happened
-- Any relevant log lines from the server
-
-**Feature requests** — describe the user problem before the implementation. "I couldn't X because Y" is more useful than "please add Z."
-
-## Before opening a PR
-
-1. Fork the repo and create a branch off `main`:
-   - `feat/<short-name>` for new features
-   - `fix/<issue-number>-<short-name>` for bug fixes
-   - `docs/<topic>` for documentation
-   - `refactor/<topic>`, `chore/<topic>` for everything else
-
-2. Install dependencies:
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-3. Make your change. Keep it focused — one logical change per PR.
-
-4. Run the server and test manually:
-   ```bash
-   python src/app.py
-   curl http://localhost:3111/agentmemory/livez
-   ```
-
-5. No test runner is configured yet. If you're adding tests, use `pytest`:
-   ```bash
-   pip install pytest
-   pytest
-   ```
-
-6. Run linting before submitting:
-   ```bash
-   pip install ruff
-   ruff check src/
-   ruff format src/
-   ```
-
-## Pull request guidelines
-
-- Write a clear description: what it does, why, and how to verify.
-- Link the issue the PR resolves (`Fixes #NNN` or `Closes #NNN`).
-- Keep PRs small — large PRs are harder to review and slower to merge.
-- Address review feedback in new commits, not force-pushes.
-
-## Code style
-
-- Python 3.10+. No walrus operator or match/case unless there's a real reason.
-- No comments that restate what the code does. Only comment the *why* — a hidden constraint, a workaround for a specific bug, a non-obvious invariant.
-- No dead code or commented-out blocks.
-- Validate inputs at system boundaries (REST endpoints, MCP handlers). Never pass raw request bodies to internal functions.
-- Use `hmac.compare_digest` for secret comparisons — never `==`.
-
-## Architecture rules
-
-When adding a REST endpoint, also update:
-- `README.md` API Reference table
-- `AGENTS.md` if it's agent-callable
-
-When adding an MCP tool, also update:
-- The schema list in `GET /agentmemory/mcp/tools` in `src/app.py`
-- The dispatch handler in `POST /agentmemory/mcp/tools` in `src/app.py`
-- The tool table in `README.md`
-- The tool list in `AGENTS.md`
-
-When adding a new KV scope, also update:
-- The `KV` class in `src/functions.py`
-- The scope table in `AGENTS.md`
-
-## Good first contributions
-
-- Add pytest test coverage for `src/functions.py`
-- Add a hook script for a new agent (see `INSTALL_FOR_AGENTS.md`)
-- Add support for an additional embedding provider (OpenAI, Cohere, local)
-- Improve error messages in the viewer
-- Add a language-specific README to `READMEs/`
-
-## Questions?
-
-Open an issue or start a discussion. The project is small enough that a quick question is usually faster than reading all the code.

EPIC.md

@@ -1,134 +0,0 @@
-# Epic: Enterprise-Grade Memory, Context Ingestion, & Database Scaling for `agentcache`
-
-This document outlines the product epic for transforming `agentcache` into an industry-leading, production-grade memory server for AI coding agents. It covers database scaling, zero-config onboarding, cognitive pruning, observability, and team-based memory synchronization.
-
----
-
-```mermaid
-graph TD
-    A[Epic: Enterprise Memory Server] --> B[Pillar 1: Storage & Vector Hardening]
-    A --> C[Pillar 2: Zero-Config Bootstrapper & SDKs]
-    A --> D[Pillar 3: Memory Decay & Cognitive Pruning]
-    A --> E[Pillar 4: Time-Travel Debugger & Replay]
-    A --> F[Pillar 5: Graph-Augmented Retrieval & Docs]
-    A --> G[Pillar 6: Enterprise Observability & RBAC]
-    A --> H[Pillar 7: Git-Backed Team Memory Sync]
-
-    style A fill:#0F172A,stroke:#334155,color:#fff
-    style B fill:#0369A1,stroke:#1E293B,color:#fff
-    style C fill:#0369A1,stroke:#1E293B,color:#fff
-    style D fill:#0369A1,stroke:#1E293B,color:#fff
-    style E fill:#0F766E,stroke:#1E293B,color:#fff
-    style F fill:#0F766E,stroke:#1E293B,color:#fff
-    style G fill:#B91C1C,stroke:#1E293B,color:#fff
-    style H fill:#6B21A8,stroke:#1E293B,color:#fff
-```
-
----
-
-## Pillar 1: Core Datastore & Vector Hardening (Pluggable Storage)
-To run in production with millions of logs and observations, the core storage and vector indices must scale beyond a single SQLite file and in-memory list arrays.
-
-### 1. Storage Layer Interface (`BaseStorage`)
-Abstract all database key-value operations behind a unified repository interface:
-* **Interface Definition:** Abstract operations `get`, `set`, `delete`, `list`, and `commit`.
-* **Swappable Backends:**
-  - `SQLiteStorage`: Optimized default backend featuring tuned WAL and memory-mapped pragmas.
-  - `PostgreSQLStorage`: Scalable production backend storing scope data inside `JSONB` columns with GIN indexing.
-  - `RedisStorage`: High-speed memory storage for volatile and ephemeral caching environments.
-
-### 2. Out-of-Process Vector Indexing (`BaseVectorIndex`)
-Move beyond holding float32 list arrays in Python process memory, which bloats and slows search queries over time.
-* **Interface Definition:** Abstract vector insertion, eviction, and cosine similarity query runs.
-* **Swappable Backends:**
-  - `InMemoryVectorIndex`: Flat-list memory storage (default).
-  - `QdrantVectorIndex` / `ChromaVectorIndex`: Offloads embedding storage and spatial indexing to external, specialized vector database services, enabling sub-10ms hybrid search queries.
-
----
-
-## Pillar 2: Zero-Config Context Ingestion & Client SDKs
-Minimize developer friction by automating prompt context bootstrap and exposing clean programming clients.
-
-### 1. Auto-Context Bootstrapper (`agentcache bootstrap`)
-* **The Problem:** Coding agents have to waste token limits and execution time calling MCP tools like `memory_recall` at startup just to figure out "what was I doing here?".
-* **The Solution:** A background directory watcher writes the latest active tasks, recent lessons, and pinned slots to a local `.agentcache_context.md` file in the project.
-* **Execution:** Since agents (Cursor, Cline, Windsurf) automatically read local files on boot, context is injected into their initial system prompt automatically, saving token overhead.
-
-### 2. Client SDK Packages
-* **Python SDK (`agentcache-client`):** Programmatic async client wrappers:
-  ```python
-  from agentcache import AgentCacheClient
-  client = AgentCacheClient(url="http://localhost:3111", token="...")
-  client.observe(folder="./src", agent="coder", text="Refactored modules")
-  ```
-* **TypeScript SDK (`@agentcache/client`):** Native Node.js package to simplify integrations inside VS Code extensions and JavaScript agent scripts.
-
----
-
-## Pillar 3: Memory Decay & Cognitive Pruning (Noise Erasure)
-AI agents generate vast volumes of raw tool execution logs. Without pruning, search results become polluted with transient noise, inflating context sizes and costs.
-
-### 1. Time-To-Live (TTL) on Transient Data
-* Tag incoming logs with TTLs. EPhemeral warnings, intermediate compiler failures, and temporary shell outputs are deleted automatically after a short duration (e.g. 2 hours).
-* If a "build passed" or "test successful" observation is logged, previous compiler errors in that folder are immediately deleted.
-
-### 2. Semantic Compression (Episode Crystallization)
-* Once a folder pair reaches a threshold of observations, run a background LLM consolidation sweep.
-* Compress those observations into high-level semantic facts (e.g., "Resolved circular imports in auth.py by using lazy imports").
-* Store the consolidated summaries as permanent memories and evict the underlying raw log observations.
-
----
-
-## Pillar 4: Time-Travel Debugger & Interactive Trace Replay
-Provide developer visibility and trace debugging controls for agent loops and mental states.
-
-### 1. Interactive Trace Replay
-* A debugger screen in the HTML dashboard allowing developers to step forward or backward through each event in an agent's history.
-* **Cognitive Diffs:** Side-by-side visualization showing file changes, prompt context, tool outcomes, and memory states at each execution step.
-* **Mental Model Correction:** Allow developers to edit or inject memories mid-run, correcting the agent's assumptions before resuming execution.
-
----
-
-## Pillar 5: Graph-Augmented Retrieval (GRAG) & Auto-Documentation
-Combine vector similarity with topological relations to improve query relevance and developer documentation.
-
-### 1. Topological Search Expansion
-* Vector similarity only matches text similarity. Codebases are topological (e.g., `UserAuth` calls `db.py`, which is loaded by `routes/auth.py`).
-* Traverse Knowledge Graph relations to pull adjacent files, parent folders, and concept associations into search results, giving the agent a structural map of the codebase.
-
-### 2. Auto-Documentation Generator (`memory_crystalize_docs`)
-* An MCP tool and API endpoint that reads the consolidated semantic and procedural memories of all agent runs.
-* Automatically compiles them into structured developer documentation (e.g., `ARCHITECTURE.md` or `DEVELOPER_GUIDE.md`), explaining workarounds and design decisions.
-
----
-
-## Pillar 6: Enterprise Observability & Multi-Token RBAC Security
-Prepare `agentcache` for enterprise networks and cloud environments through secure and monitored interfaces.
-
-### 1. Multi-Token Role-Based Access Control (RBAC)
-* Implement timing-safe HMAC verification against multiple client tokens.
-* Enforce access privileges:
-  - `Viewer Token`: Read-only access to HTML dashboard.
-  - `Agent Token`: Scoped read-write access to specific folder namespaces.
-  - `Admin Token`: Full control over migrations, settings, and database purges.
-
-### 2. Operations Telemetry
-* **Structured JSON Logging:** Replace raw standard prints with standard python `logging` outputting JSON, allowing simple ingestion by log aggregators (Splunk, ELK, Datadog).
-* **Prometheus Metrics:** Expose `/metrics` containing:
-  - Active WebSocket client counts.
-  - SQLite WAL size and connection pool details.
-  - Execution latencies for BM25, Vector, and Hybrid search runs.
-
----
-
-## Pillar 7: Git-Backed Team Memory Synchronization
-Enable developer teams to share agent learnings using existing Git repository workflows.
-
-### 1. Repository-Level Snapshots
-* A CLI command `agentcache export --format=db --type=semantic` that compiles and outputs a highly compressed SQLite snapshot containing only semantic/procedural memories.
-* Store this snapshot under `.agentcache/project_memories.db` in the repository.
-
-### 2. Git Hook Automation
-* **Pre-commit hook:** Automatically triggers memory consolidation and commits the updated lightweight snapshot.
-* **Post-pull hook:** Merges the incoming memory snapshot into the developer's local `agentcache` SQLite database.
-* **Result:** Every developer on the team benefits from the collective intelligence of all agents running in the repository.

GOVERNANCE.md

@@ -1,88 +0,0 @@
-# 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

@@ -1,237 +0,0 @@
-# Install agentcache-python (agent runbook)
-
-You are a coding agent. Follow this runbook top to bottom to install agentcache-python, wire it into yourself, and verify that persistent memory works. Run each command, check the result against the "Expect" note, then move on.
-
-## What you are installing
-
-agentcache-python is a local memory server for coding agents. It runs on your machine, exposes a REST API on port 3111 and an MCP endpoint, and stores all memories in a single SQLite file at `~/.agentcache/agentcache.db`. It is built with Python and Flask — no Node.js, no external database, no daemon to manage separately.
-
-Default mode works with no API key. It runs BM25 keyword search out of the box. Set `GEMINI_API_KEY` to also enable vector semantic search.
-
-## Prerequisites
-
-- Python 3.10 or newer. Check with `python --version` or `python3 --version`.
-- pip. Check with `pip --version`.
-- Port 3111 free. If taken, set `III_REST_PORT=<other>` in `~/.agentcache/.env`.
-
-## 1. Clone the repo
-
-```bash
-git clone https://github.com/Yashwant00CR7/agentcache.git
-cd agentcache
-```
-
-Expect: the directory exists with `src/app.py` inside.
-
-## 2. Install dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-This installs: flask, flask-sock, requests, websockets, python-dateutil, huggingface_hub.
-
-Expect: install completes without errors.
-
-## 3. Start the server
-
-```bash
-python src/app.py &
-```
-
-Or run in a separate terminal: `python src/app.py`
-
-Wait until it is reachable:
-
-```bash
-curl -fsS http://localhost:3111/agentcache/livez
-```
-
-Expect: `{"status": "ok"}`. On first run the BM25 index initializes in the background; this takes under a second.
-
-## 4. Prove save and recall works
-
-```bash
-# Save a memory
-curl -X POST http://localhost:3111/agentcache/remember \
-  -H "Content-Type: application/json" \
-  -d '{"content":"agentcache-python install verification probe","concepts":["install-check"]}'
-
-# Recall it
-curl -X POST http://localhost:3111/agentcache/search \
-  -H "Content-Type: application/json" \
-  -d '{"query":"install verification probe","limit":5}'
-```
-
-Expect: first call returns `{"id": "...", "success": true}`, second returns results containing the probe memory.
-
-## 5. Wire MCP into the calling agent
-
-Detect which agent is running this runbook, then add agentcache-python to its MCP config.
-
-### Standard MCP block (Cursor, Claude Desktop, Cline, Windsurf, Gemini CLI)
-
-Merge this into the agent's `mcpServers` object:
-
-```json
-"agentcache": {
-  "command": "npx",
-  "args": ["-y", "@agentcache/mcp"],
-  "env": {
-    "AGENTCACHE_URL": "http://localhost:3111"
-  }
-}
-```
-
-### Claude Code
-
-Add to `~/.claude.json` under `mcpServers`:
-
-```json
-"agentcache": {
-  "command": "npx",
-  "args": ["-y", "@agentcache/mcp"],
-  "env": {
-    "AGENTCACHE_URL": "http://localhost:3111"
-  }
-}
-```
-
-Then reload MCP: run `/mcp` in Claude Code.
-
-### Any agent — verify tool count
-
-After wiring, the agent should list agentcache's tools. With the server running you should see 16 tools (e.g. `memory_save`, `memory_smart_search`, `memory_sessions`).
-
-If you see 0 tools or an error, check that `python src/app.py` is running and `AGENTCACHE_URL` points at it.
-
-## 6. Setting up agent hooks
-
-Agent hooks post observations to agentcache automatically on every tool use, command, or edit — no manual calls required. Hook scripts live in the [`hooks/`](hooks/) directory.
-
-### Claude Code (`hooks/claude-code-hook.sh`)
-
-Add a `PostToolUse` hook to `.claude/settings.json`. The hook script reads `AGENTCACHE_URL` and `AGENTCACHE_SECRET` from your shell environment, so no secrets are embedded in the config file.
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash /path/to/hooks/claude-code-hook.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Set the required environment variables before starting Claude Code:
-
-```bash
-export AGENTCACHE_URL=http://127.0.0.1:3111
-export AGENTCACHE_SECRET=your-secret-here   # omit if no auth set
-```
-
-The script picks up `$PWD` as `folderPath` and `$CLAUDE_AGENT_ID` (falling back to `"claude-code"`) as `agentId`.
-
-### Cursor (`hooks/cursor-hook.js`)
-
-Require the hook from your `.cursorrules` file (or any JS entry point Cursor runs) and call `logObservation()` with the tool name and input:
-
-```js
-const { logObservation } = require('/path/to/hooks/cursor-hook.js');
-
-// Call inside your Cursor hook handler, e.g. after every tool invocation:
-logObservation(`Tool: ${toolName}\nInput: ${JSON.stringify(toolInput)}`);
-```
-
-The module reads `AGENTCACHE_URL`, `AGENTCACHE_SECRET`, and `AGENTCACHE_AGENT_ID` from `process.env`. Set them in your shell profile or in Cursor's environment settings.
-
-### `.env` file format
-
-All hooks and the server itself read credentials from `~/.agentcache/.env`. Create this file if it doesn't exist:
-
-```
-III_REST_PORT=3111
-AGENTCACHE_SECRET=your-secret-here
-GEMINI_API_KEY=your-gemini-key-here
-```
-
-The server loads this file on startup. Hook scripts read the same variables from your shell environment (export them from your profile after sourcing `~/.agentcache/.env`, or use `direnv` / `dotenv` tooling).
-
-## 7. Open the viewer (optional)
-
-```bash
-open http://localhost:3111/viewer
-# or on Linux:
-xdg-open http://localhost:3111/viewer
-# or on Windows:
-start http://localhost:3111/viewer
-```
-
-The viewer shows live sessions, memories, and the knowledge graph.
-
-## Optional: enable vector search
-
-Vector search finds memories semantically, not just by keyword. Enable it with a free Gemini API key:
-
-```bash
-mkdir -p ~/.agentcache
-echo "GEMINI_API_KEY=your-key-here" >> ~/.agentcache/.env
-```
-
-Restart the server after adding the key. The viewer's search bar will now use hybrid BM25 + vector retrieval.
-
-## Optional: enable LLM compression
-
-LLM compression makes each observation richer and more searchable. Requires an LLM API key:
-
-```bash
-# Add to ~/.agentcache/.env
-ANTHROPIC_API_KEY=your-key   # or OPENAI_API_KEY or GEMINI_API_KEY
-AGENTCACHE_AUTO_COMPRESS=true
-```
-
-## Lifecycle
-
-```bash
-# Stop the server (find and kill the process)
-pkill -f "python src/app.py"
-
-# Check what's stored
-curl http://localhost:3111/agentcache/sessions
-curl http://localhost:3111/agentcache/memories
-
-# Health check
-curl http://localhost:3111/agentcache/livez
-```
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---------|-----|
-| `ModuleNotFoundError: No module named 'flask'` | Run `pip install -r requirements.txt` |
-| `Address already in use` on port 3111 | Set `III_REST_PORT=3112` in `~/.agentcache/.env` and restart |
-| `/livez` never returns | Check `python src/app.py` stderr for import errors |
-| 0 tools in agent | Confirm `AGENTCACHE_URL=http://localhost:3111` and the server is running |
-| `401 Unauthorized` | Set `AGENTCACHE_SECRET` env var in the MCP config to match `~/.agentcache/.env` |
-| Vector search not working | Add `GEMINI_API_KEY` to `~/.agentcache/.env` and restart |
-| Windows Python path issue | Use `python3` instead of `python`, or use WSL2 |
-
-## Report success
-
-Report back:
-
-- agentcache-python server running on port 3111
-- MCP wired into the agent, tool count visible
-- Save and recall round-trip returned the probe memory
-- Viewer available at http://localhost:3111/viewer
-- Any optional features enabled (vector search, LLM compression)
-
-If any step failed, report the step, exact command, and error output.

MAINTAINERS.md

@@ -1,21 +0,0 @@
-# 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

@@ -1,482 +0,0 @@
----
-title: AgentCache Python
-emoji: 🧠
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-pinned: false
----
-
-<h1 align="center">agentcache-python</h1>
-
-<p align="center">
-  <strong>Persistent memory for AI coding agents — pure Python, zero external databases.</strong><br/>
-  Works with Claude Code, Cursor, Cline, Windsurf, Gemini CLI, and any MCP client.
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
-  <img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite WAL" />
-  <img src="https://img.shields.io/badge/Flask-3.0-000000?style=for-the-badge&logo=flask&logoColor=white" alt="Flask 3.0" />
-  <img src="https://img.shields.io/badge/MCP-Compatible-6B21A8?style=for-the-badge" alt="MCP Compatible" />
-  <img src="https://img.shields.io/badge/HuggingFace-Space-FF9D00?style=for-the-badge&logo=huggingface&logoColor=white" alt="HuggingFace Space" />
-</p>
-
-<p align="center">
-  <a href="#quick-start">Quick Start</a> &bull;
-  <a href="#features">Features</a> &bull;
-  <a href="#mcp-integration">MCP</a> &bull;
-  <a href="#api-reference">API</a> &bull;
-  <a href="#configuration">Config</a> &bull;
-  <a href="#deploy-to-huggingface">Deploy</a> &bull;
-  <a href="#viewer">Viewer</a> &bull;
-  <a href="#architecture">Architecture</a>
-</p>
-
----
-
-## What Is This?
-
-**agentcache-python** is a Python reimplementation of the [agentcache](https://github.com/rohitg00/agentcache) persistent memory server. It exposes a REST API, WebSocket stream, and MCP tools endpoint that AI coding agents use to store and retrieve session observations, long-term memories, lessons, and pinned memory slots.
-
-Key differences from the Node.js original:
-
-- **No Node.js or iii-engine** — runs with plain `python src/app.py`
-- **SQLite instead of Dolt** — single file, WAL mode, instant startup
-- **HuggingFace Space ready** — deploys in one click, data synced to an HF dataset repo
-- **Same REST + MCP wire format** — drop-in for any agent already wired to agentcache
-
-Your agent captures every tool call, stores them as observations, compresses them into searchable memory, and injects the right context at the start of every new session — automatically.
-
----
-
-## Quick Start
-
-### Run locally
-
-```bash
-# Clone
-git clone https://github.com/Yashwant00CR7/agentcache.git
-cd agentcache
-
-# Install dependencies (no build step)
-pip install -r requirements.txt
-
-# Start the server
-python src/app.py
-```
-
-Server starts on **http://localhost:3111**. Open the viewer at http://localhost:3111/viewer.
-
-### Verify it works
-
-```bash
-# Health check
-curl http://localhost:3111/agentcache/livez
-# {"status": "ok"}
-
-# Save a memory
-curl -X POST http://localhost:3111/agentcache/remember \
-  -H "Content-Type: application/json" \
-  -d '{"content": "JWT auth uses jose middleware in src/middleware/auth.ts", "concepts": ["auth", "jwt"]}'
-
-# Recall it
-curl -X POST http://localhost:3111/agentcache/search \
-  -H "Content-Type: application/json" \
-  -d '{"query": "authentication middleware", "limit": 5}'
-```
-
----
-
-## Features
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| REST API — sessions, memories, observations | ✅ | Full surface |
-| WebSocket live stream | ✅ | `/stream/mem-live/viewer` |
-| MCP tools endpoint | ✅ | 31 tools |
-| Built-in HTML viewer | ✅ | Real-time dashboard at `/viewer` |
-| BM25 keyword search | ✅ | Always on, no API key needed |
-| Hybrid BM25 + vector search | ✅ | Requires `GEMINI_API_KEY` |
-| 4-tier memory consolidation | ⚙️ | `CONSOLIDATION_ENABLED=true` + LLM key |
-| Knowledge graph extraction | ⚙️ | `GRAPH_EXTRACTION_ENABLED=true` + LLM key |
-| LLM observation compression | ⚙️ | `AGENTCACHE_AUTO_COMPRESS=true` + LLM key |
-| Lessons with confidence decay | ✅ | Fingerprinted, auto-strengthen on repeat |
-| Memory slots (pinned context) | ✅ | CRUD + auto-reflect |
-| Session replay | ✅ | Full timeline in viewer |
-| Audit log | ✅ | Tracks every write with agent_id + timestamp |
-| HuggingFace Space deploy | ✅ | One-click, data synced to dataset repo |
-| Privacy filtering | ✅ | Strips API keys, tokens before storage |
-
-### 4-Tier Memory Model
-
-Inspired by how human memory works — raw experience → compressed episodes → extracted facts → learned patterns.
-
-| Tier | What | When |
-|------|------|------|
-| **Working** | Raw observations from tool use | Every tool call |
-| **Episodic** | Compressed session summaries | Session end |
-| **Semantic** | Extracted facts and patterns | Consolidation |
-| **Procedural** | Workflows and decision patterns | Consolidation |
-
----
-
-## MCP Integration
-
-Wire agentcache-python into your agent's MCP config. It speaks the same MCP protocol as the Node.js original.
-
-### Most agents (Cursor, Claude Desktop, Cline, Windsurf)
-
-```json
-{
-  "mcpServers": {
-    "agentcache": {
-      "command": "npx",
-      "args": ["-y", "@agentcache/mcp"],
-      "env": {
-        "AGENTCACHE_URL": "http://localhost:3111"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
-
-Paste this prompt and your agent will wire everything:
-
-```
-Start agentcache-python: run `python src/app.py` from the agentcache-python directory.
-Then add this MCP server to ~/.claude.json under mcpServers:
-{
-  "agentcache": {
-    "command": "npx",
-    "args": ["-y", "@agentcache/mcp"],
-    "env": { "AGENTCACHE_URL": "http://localhost:3111" }
-  }
-}
-Verify with: curl http://localhost:3111/agentcache/livez
-Open the viewer at: http://localhost:3111/viewer
-```
-
-### Available MCP Tools (31)
-
-| Tool | Description |
-|------|-------------|
-| `memory_save` | Save a long-term insight, decision, or pattern |
-| `memory_recall` | Search past observations by keyword |
-| `memory_smart_search` | Hybrid BM25 + vector semantic search |
-| `memory_sessions` | List recent sessions |
-| `memory_sessions_list` | Retrieve all memory sessions |
-| `memory_timeline` | Chronological observations for a session |
-| `memory_observations` | Observations for a session |
-| `memory_profile` | Per-project concept + file profile |
-| `memory_lessons` | List active lessons with confidence scores |
-| `memory_lesson_save` | Save a lesson (duplicate saves strengthen it) |
-| `memory_lesson_recall` | Search lessons by query |
-| `memory_lesson_search` | Search lessons by keywords |
-| `memory_consolidate` | Run 4-tier memory consolidation |
-| `memory_reflect` | Reflect on session, update context |
-| `memory_diagnose` | Health check across all subsystems |
-| `memory_forget` | Delete memory, session, or observations |
-| `memory_export` | Export all memory data as JSON |
-| `agent_observe` | Log agent execution observation |
-| `agent_remember` | Save agent cache to long-term storage |
-| `memory_antigravity_sync` | Sync Antigravity transcripts to memory |
-| `memory_antigravity_sync_all` | Master sync: transcript + crystallize + reflect |
-| `memory_slot_list` | List all pinned memory slots |
-| `memory_slot_get` | Retrieve a specific pinned memory slot |
-| `memory_slot_create` | Create/overwrite a pinned memory slot |
-| `memory_slot_append` | Append text content to a pinned memory slot |
-| `memory_slot_replace` | Replace pinned memory slot content |
-| `memory_slot_delete` | Delete a pinned memory slot |
-| `memory_action_create` | Create a new work item / action |
-| `memory_action_update` | Update fields of an existing action |
-| `memory_frontier` | Get active and pending actions sorted by priority |
-| `memory_crystallize` | Crystallize/summarize observations in a session |
-
----
-
-## API Reference
-
-Base URL: `http://localhost:3111/agentcache`
-
-### Health
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/livez` | Liveness probe — no auth required |
-
-### Sessions
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/session/start` | Start a new session |
-| `POST` | `/session/end` | End a session |
-| `POST` | `/session/commit` | Commit session with summary |
-| `GET` | `/sessions` | List all sessions |
-
-### Observations
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/observe` | Ingest a hook event observation |
-| `POST` | `/agent/observe` | Simplified observe for direct agent use |
-| `GET` | `/observations` | List observations (`?session_id=`) |
-| `POST` | `/timeline` | Chronological observation window |
-
-### Memories
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/remember` | Save long-term memory |
-| `POST` | `/agent/remember` | Simplified remember |
-| `POST` | `/forget` | Delete memory / session / observations |
-| `POST` | `/search` | BM25 + vector search |
-| `POST` | `/context` | Compile context for a session + project |
-| `GET` | `/memories` | List memories (`?latest=true&limit=N`) |
-| `POST` | `/evolve` | Create a new memory version |
-
-### Lessons
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/lessons` | List lessons |
-| `POST` | `/lessons` | Create lesson |
-| `POST` | `/lessons/search` | Search lessons |
-| `POST` | `/lessons/strengthen` | Reinforce an existing lesson |
-
-### Slots
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/slots` | List all pinned slots |
-| `POST` | `/slot` | Create or update a slot |
-| `GET` | `/slot` | Get slot by name |
-| `DELETE` | `/slot` | Delete a slot |
-| `POST` | `/slot/reflect` | Auto-populate from session observations |
-
-### Graph + Profile
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/relations` | Knowledge graph edges |
-| `POST` | `/relations` | Add a relation |
-| `GET` | `/profile` | Project profile (top concepts, files) |
-
-### Actions
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/actions` | List actions |
-| `POST` | `/actions` | Create an action |
-| `PATCH` | `/actions/<id>` | Update action status / fields |
-| `GET` | `/frontier` | Pending actions sorted by priority |
-| `GET` | `/insights` | List insights |
-
-### Replay
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/replay/sessions` | Sessions list for replay tab |
-| `GET` | `/replay/load` | Full session + observations (`?sessionId=`) |
-
-### MCP
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/mcp/tools` | MCP tool schema list |
-| `POST` | `/mcp/tools` | MCP tool call dispatch |
-
----
-
-## Configuration
-
-Create `~/.agentcache/.env` (no `export` prefix needed):
-
-```env
-# Server port
-III_REST_PORT=3111
-
-# Vector search — enables Gemini 768-dim embeddings
-GEMINI_API_KEY=your-gemini-key
-
-# LLM for compression / consolidation / graph extraction
-# Any one of these enables LLM features:
-ANTHROPIC_API_KEY=your-anthropic-key
-# OPENAI_API_KEY=your-openai-key
-# GEMINI_API_KEY=your-key   (same key as above works for both)
-
-# LLM-powered features (disabled by default — spend tokens)
-CONSOLIDATION_ENABLED=true
-GRAPH_EXTRACTION_ENABLED=true
-AGENTCACHE_AUTO_COMPRESS=true
-
-# Context injection limits
-TOKEN_BUDGET=2000
-MAX_OBS_PER_SESSION=500
-
-# Auth — set to require Bearer token on all endpoints
-AGENTCACHE_SECRET=your-secret
-
-# Agent scope isolation
-AGENT_ID=my-agent
-AGENTCACHE_AGENT_SCOPE=isolated   # only see this agent's data
-
-# HuggingFace sync
-HF_TOKEN=your-hf-token
-AGENTCACHE_DATASET_REPO=username/agentcache-data
-```
-
-### Full Variable Reference
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `III_REST_PORT` / `PORT` | `3111` | API server port |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables 768-dim vector search |
-| `AGENTCACHE_SECRET` | — | Bearer token auth on all endpoints |
-| `AGENT_ID` | — | Default agent ID for scope isolation |
-| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filters data to current `AGENT_ID` |
-| `MAX_OBS_PER_SESSION` | `500` | Hard cap on observations per session |
-| `TOKEN_BUDGET` | `2000` | Max tokens in compiled context |
-| `GRAPH_EXTRACTION_ENABLED` | `false` | Knowledge graph (needs LLM) |
-| `CONSOLIDATION_ENABLED` | `false` | Memory consolidation (needs LLM) |
-| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM observation compression |
-
----
-
-## Viewer
-
-Built-in dashboard at **http://localhost:3111/viewer**.
-
-| Tab | What You See |
-|-----|-------------|
-| **Dashboard** | Session stats, memory counts, recent activity |
-| **Sessions** | Browse sessions, inspect observations |
-| **Memories** | Search, filter, and read long-term memories |
-| **Graph** | Project folder visualization — nodes = folders, edges = shared concepts or parent path |
-| **Timeline** | Per-session chronological observation view |
-| **Lessons** | Confidence-scored lessons with decay tracking |
-| **Slots** | Pinned memory slots editor |
-| **Replay** | Scrub through past sessions frame by frame |
-
----
-
-## Deploy to HuggingFace
-
-This project is designed to run as a HuggingFace Space. Data is stored in an HF dataset repo and restored on every boot — so no persistent disk is needed.
-
-### Setup
-
-1. Fork this repo as a HuggingFace Space (SDK: Docker)
-2. Create a dataset repo (e.g. `your-username/agentcache-data`)
-3. Add Space secrets in the HF dashboard:
-
-   | Secret | Value |
-   |--------|-------|
-   | `HF_TOKEN` | Your HF write token |
-   | `AGENTCACHE_DATASET_REPO` | `your-username/agentcache-data` |
-   | `AGENTCACHE_SECRET` | A random secret (optional but recommended) |
-   | `GEMINI_API_KEY` | Gemini key (optional, enables vector search) |
-
-4. The Space boots, restores `agentcache.db` from the dataset repo, and starts the server
-
-### How sync works
-
-`sync.py` uses mtime fingerprinting — it only uploads when the database actually changed, so there are no unnecessary uploads during idle periods.
-
-```bash
-# Manual backup
-python sync.py
-
-# Environment for sync
-HF_TOKEN=...
-AGENTCACHE_DATASET_REPO=username/agentcache-data
-```
-
----
-
-## Architecture
-
-```
-agentcache-python/
-├── src/
-│   ├── app.py          Flask server — all endpoints, WebSocket broadcaster
-│   ├── db.py           SQLite StateKV — WAL mode, audit_log table
-│   ├── functions.py    Core logic — observe, remember, search, context
-│   ├── search.py       BM25 + Gemini vector index + HybridSearch (RRF)
-│   └── viewer/
-│       └── index.html  Single-file HTML dashboard (no build step)
-├── sync.py             HuggingFace dataset backup/restore
-├── Dockerfile          HF Space container
-├── start.sh            Boot script (restore → start server → start sync)
-└── requirements.txt    6 Python dependencies, no external DB required
-```
-
-### Database layout
-
-Two SQLite tables in `~/.agentcache/agentcache.db`:
-
-```sql
--- All data lives here, namespaced by scope
-kv_store (
-  scope TEXT NOT NULL,    -- e.g. "mem:sessions", "mem:obs:{session_id}"
-  key   TEXT NOT NULL,
-  value TEXT NOT NULL,    -- JSON-serialized
-  PRIMARY KEY (scope, key)
-)
-
--- Audit trail replaces Dolt git versioning
-audit_log (
-  id       INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts       INTEGER NOT NULL,   -- unix millis
-  agent_id TEXT NOT NULL,
-  message  TEXT NOT NULL
-)
-```
-
-### Search pipeline
-
-```
-Query
-  → BM25 (always)         — Porter-stemmed keyword matching
-  → Vector (if Gemini key) — 768-dim cosine similarity
-  → RRF fusion            — Reciprocal Rank Fusion (k=60)
-  → Session diversify     — max 3 results per session
-  → Return top-K
-```
-
----
-
-## vs Original agentcache
-
-| | agentcache (Node.js) | agentcache-python |
-|---|---|---|
-| Runtime | Node.js 20+ | Python 3.10+ |
-| Storage | Dolt SQL (git-versioned MySQL) | SQLite WAL (single file) |
-| Engine dependency | iii-engine (separate binary) | None — just Flask |
-| Embeddings | 6 providers + local `@xenova/transformers` | Gemini 768-dim |
-| MCP tools | 53 | 31 |
-| REST endpoints | 128 | ~50 |
-| Deploy | npm, Docker, fly.io, Railway, Render | Docker, HuggingFace Spaces |
-| Cold boot | ~7s (iii engine warm-up) | <2s |
-| Database size | ~232MB (417 Dolt chunk files) | ~20MB (single `.db` file) |
-| Setup | `npm install -g @agentcache/agentcache` | `pip install -r requirements.txt` |
-
-Choose the Python version for: simpler setup, HF Space deployment, single-file database, no Node.js, or Python ecosystem integration.
-
-Choose the Node.js version for: the full 53-tool MCP surface, iii-engine observability, production multi-agent deployments, or the full auto-hook suite.
-
----
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
-
-Priority areas: test coverage, additional embedding providers, more agent hook scripts.
-
----
-
-## License
-
-Apache-2.0 — see [LICENSE](LICENSE).

READMEs/README.de-DE.md

@@ -1,1377 +0,0 @@
-<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

@@ -1,1370 +0,0 @@
-<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

@@ -1,1377 +0,0 @@
-<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

@@ -1,1380 +0,0 @@
-<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

@@ -1,1380 +0,0 @@
-<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

@@ -1,1361 +0,0 @@
-<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

@@ -1,1370 +0,0 @@
-<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

@@ -1,1381 +0,0 @@
-<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

@@ -1,1378 +0,0 @@
-<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

@@ -1,1378 +0,0 @@
-<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

@@ -1,66 +0,0 @@
-# Roadmap
-
-This is agentmemory-python's public roadmap. Items shift as priorities change.
-
-- **Shipped** — in main
-- **Active** — has an open PR
-- **Planned** — accepted, not started
-- **Candidate** — under consideration
-
----
-
-## Phase 1 — Foundation (done)
-
-- [x] Python + Flask server replacing Node.js / iii-engine
-- [x] SQLite WAL backend replacing Dolt SQL
-- [x] Audit log replacing Dolt git versioning
-- [x] BM25 search with Porter stemmer
-- [x] Gemini 768-dim vector search + hybrid RRF fusion
-- [x] 16-tool MCP endpoint
-- [x] WebSocket live stream
-- [x] Built-in HTML viewer (Dashboard, Sessions, Memories, Graph, Timeline, Lessons, Slots, Replay)
-- [x] Knowledge graph visualization — folder nodes with unique colors, force-directed layout
-- [x] 4-tier memory consolidation (Working → Episodic → Semantic → Procedural)
-- [x] Lessons system with confidence decay
-- [x] HuggingFace Space deployment with sync fingerprinting
-- [x] Dolt → SQLite one-time migration (7502 rows, 19.6MB)
-
----
-
-## Phase 2 — Reliability
-
-### Active
-
-- [ ] **Pytest test coverage** for `src/functions.py` core operations (observe, remember, search, context)
-- [ ] **Graph edge label bug** — labels overlap at default zoom on dense graphs
-
-### Planned
-
-- [ ] **Additional embedding providers** — OpenAI `text-embedding-3-small`, local `sentence-transformers`
-- [ ] **Hook scripts** — prebuilt bash/PowerShell hook scripts for Claude Code, Cursor, Codex CLI pointing at `http://localhost:3111`
-- [ ] **Memory export/import** — JSON round-trip so users can migrate between instances
-- [ ] **Health endpoint** (`/agentmemory/health`) — richer than `/livez`, includes index sizes, sync status, last backup time
-- [ ] **Graceful shutdown** — flush BM25/vector index to DB before exit on SIGTERM
-
----
-
-## Phase 3 — Breadth
-
-### Candidate
-
-- **Additional LLM providers** — OpenRouter, Ollama (local), Cohere for compression and consolidation
-- **MCP tool parity** — expand from 16 to 30+ tools to match the most-used subset of the Node.js 53-tool surface
-- **GitHub Actions hook** — observe CI runs as memory events
-- **Slack / Discord connector** — ingest messages as observations
-- **Multi-agent shared memory** — namespace isolation for team use; agents share a pool with per-agent write attribution
-- **RBAC** — role-based access control for shared deployments
-- **Benchmark harness** — reproduce the LongMemEval-S R@5 metric on the Python stack
-- **pip package** — `pip install agentmemory` with a `agentmemory` CLI entrypoint
-
----
-
-## Non-goals
-
-- Full parity with the 128-endpoint / 53-tool Node.js surface — the Python version targets simplicity and HF deployment, not feature count
-- iii-engine worker model — the Python version intentionally avoids the iii runtime
-- Dolt git-versioned history — the audit log satisfies the write-tracking requirement without the complexity

SECURITY.md

@@ -1,85 +0,0 @@
-# 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.

SPIKE.md

@@ -1,578 +0,0 @@
-# Feature Spike: Small Improvements for Agent Cache User Experience
-
-**Date:** 2026-07-16  
-**Priority:** Low risk, high value additions to current architecture  
-**Tech Stack Impact:** None — all fit within Flask/SQLite model
-
----
-
-## Table of Contents
-1. [Current State Analysis](#current-state-analysis)
-2. [Feature Opportunities](#feature-opportunities)
-3. [Recommendation Priority](#recommendation-priority)
-
----
-
-## Current State Analysis
-
-### What agentcache-python Already Has
-
-**Core Features Implemented:**
-- REST API (Flask framework on port 3111)
-- WebSocket streaming (`/stream/mem-live/viewer`)
-- Hybrid search: BM25 keyword + vector embeddings (Gemini/OpenAI/SentenceTransformer)
-- Folder-based memory model: `(folder_path, agent_id)` scoping
-- Knowledge graph construction via `folder_graph_build()`
-- MCP tools for agent integration (13+ tools)
-- Security redactions in observations (`strip_private_data()`)
-- Token budget limits during context compilation
-- Background workers for index maintenance
-
-**Key Functions:**
-| Function | Purpose | File |
-|----------|---------|------|
-| `folder_observe()` | Ingest observations with scoping | `functions.py` |
-| `folder_search()` | BM25 + vector hybrid search | `search.py` |
-| `folder_timeline()` | Chronological activity feed | `functions.py` |
-| `folder_graph_build()` | Build knowledge graph nodes/edges | `functions.py` |
-| `remember()/forget()` | Global memory management | `functions.py` |
-| `context()` | Compile contextual blocks with token limits | `functions.py` |
-| `export_data()` | v2 JSON export format | `functions.py` |
-
-**Key Tests:**
-- `test_observe_core.py` — Observation validation and redaction
-- `test_folder_observe.py` — Folder-scoped ingestion
-- `test_search.py` — BM25/vector search logic
-- `test_context.py` — Context compilation with token budgets
-- `test_graph.py` — Knowledge graph construction
-
----
-
-## Feature Opportunities
-
-### 🎯 Feature 1: Observation Prioritization / Weighting
-
-**Why Add This?**
-Users naturally write observations with different levels of importance. Currently all observations are weighted equally in search results. The search uses RRF (Reciprocal Rank Fusion) which already applies weights, but there's no user-controlled way to emphasize important observations.
-
-**What to Implement:**
-```python
-def folder_observe(kv, payload, priority=0):  # 0-100 scale
-    
-    # Store in metadata:
-    obs["priority"] = priority
-    
-    return {
-        "observationId": fobs_{hash}_{rand},
-        "priority": priority,  # Added field
-        ...
-    }
-```
-
-**Changes Required:**
-- Add `priority` field to observation payload validation (new required/optional check)
-- Modify search weighting in `HybridSearch._rank()` to include observation priority:
-  ```python
-  # Current RRF: rank_weight = 1 / len(relevant_docs)
-  # New RRF: combined_weight = (bm25_score + vector_score) * obs_priority / 100
-  ```
-
-**User Experience:**
-When a user writes an observation, they can optionally mark it as high-priority:
-```python
-# Tag this as critical issue - show prominently in search results
-folder_observe(
-    kv, {
-        "folderPath": "/home/user/project/src/auth",
-        "agentId": "my-ai-agent",
-        "text": "JWT rotation breaks production auth endpoints",
-        "timestamp": now(),
-        "priority": 90  # Highest importance
-    }
-)
-```
-
-Search results for "jwt auth break" automatically rank this observation higher than lower-priority memories.
-
-**Implementation Complexity:** **15 minutes**  
-- Add one field to observation validation schema  
-- Modify RRF weighting formula (single math operation change)  
-- Update tests to verify priority affects ranking
-
----
-
-### 🎯 Feature 2: Observation Source Tracking
-
-**Why Add This?**
-Users write observations from different contexts (code files, documentation, terminal logs). Knowing which file context an observation came from helps detect when user re-wrote same code after learning a lesson, and aids in identifying relevant follow-up actions.
-
-**What to Implement:**
-```python
-def folder_observe(kv, payload, source_file=None):  # e.g., "src/auth.py"
-    
-    obs["sourceFile"] = source_file or None
-    
-    return {
-        "observationId": fobs_{hash}_{rand},
-        "sourceFile": source_file,  # New field
-        "text": "...",
-        ...
-    }
-```
-
-**Changes Required:**
-- Add `source_file` to observation payload validation (optional string)
-- Store as additional JSON field in KV value column
-- Update timeline query to optionally show source files
-- Update search results to surface source file info
-
-**User Experience:**
-Search: "What did I learn about JWT?"  
-Results:
-```json
-{
-  "id": "fobs_abc123",
-  "text": "JWT needs refresh tokens for rotation",
-  "sourceFile": "src/auth.py",
-  "timestamp": "2026-07-15T10:30:00Z"
-}
-```
-
-The source file field tracks which files were being developed when lessons were learned. Helps detect when user re-implements same pattern after reading a tutorial, or helps identify which modules need updates based on recent observations.
-
-**Implementation Complexity:** **15 minutes**  
-- Add one optional field to observation schema  
-- Store in existing KV structure (no new table/column needed)  
-- Update `folder_timeline()` to surface source file info when requested  
-
----
-
-### 🎯 Feature 3: Folder-Level Statistics Endpoint
-
-**Why Add This?**
-Users need quick stats on individual folders without going to the dashboard UI. The current `/health` endpoint only returns global aggregate across all folders. Users often want: "How many observations do I have in my frontend folder?" answered via simple API call.
-
-**What to Implement:**
-```python
-# src/agentcache/routes/folder_stats.py or append to existing routes
-
-@app.route('/folder/stats/<path:folder_path>')
-def folder_stats(folder_path):
-    kv = StateKV()  # Get current DB instance
-    
-    # Count observations for this folder
-    obs_count = 0
-    try:
-        from agentcache.functions import KV
-        scope = KV.folder_obs(folder_path, os.getenv("AGENT_ID", "default"))
-        rows = kv.db.execute(
-            "SELECT COUNT(*) FROM kv_store WHERE scope = ?",
-            [scope]
-        ).fetchone()
-        obs_count = rows[0] if rows else 0
-    except:
-        pass
-    
-    # Get last observation timestamp
-    last_obs_ts = None
-    try:
-        rows = kv.db.execute(
-            "SELECT MAX(ts) FROM kv_store WHERE scope = ?",
-            [scope]
-        ).fetchone()
-        last_obs_ts = rows[0] if rows else None
-    except:
-        pass
-    
-    return {
-        "folderPath": folder_path,
-        "observationCount": obs_count,
-        "memoryCount": 123,  # Get from memories scope separately
-        "lastObsTimestamp": last_obs_ts.isoformat() if last_obs_ts else None,
-        "foldersKnownToThisAgent": ["home/user/projectX", ...]  # Also include this context
-    }
-```
-
-**User Experience:**
-REST API call returns folder stats instantly:
-```bash
-curl http://localhost:3111/folder/stats/home/user/my-project
-# Returns:
-{
-  "folderPath": "home/user/my-project",
-  "observationCount": 42,
-  "memoryCount": 5,
-  "lastObsTimestamp": "2026-07-15T14:23:00Z",
-  "foldersKnownToThisAgent": ["home/user/my-project"]
-}
-```
-
-**Implementation Complexity:** **10 minutes**  
-- Create new endpoint following existing Flask pattern (like `/health`)  
-- Query existing KV methods for observation and memory counts  
-- Return simple JSON response  
-
-**Note:** This requires importing `StateKV` instance in new route file, which means either creating a module-scoped singleton per folder or passing the current `kv` from `app.py` via Flask's application context.
-
----
-
-### 🎯 Feature 4: Observation Expiration / TTL (Time-To-Live)
-
-**Why Add This?**
-Temporal observations become outdated over time. Example: "Error on port 3000" observation becomes irrelevant after user changes their app to use port 8080. Currently all observations persist indefinitely. With TTL, expired observations can auto-remove from search results or be marked as "expired".
-
-**What to Implement:**
-```python
-def folder_observe(kv, payload, ttl_seconds=None):
-    
-    # Store observation with expiration timestamp
-    obs["expiryTs"] = ts + ttl_seconds if ttl_seconds else None
-    
-    return {
-        "observationId": fobs_{hash}_{rand},
-        "ttl": ttl_seconds or null,  # New field
-        ...
-    }
-```
-
-**Changes Required:**
-- Add `ttl_seconds` to observation payload validation (optional)
-- Store as additional timestamp field in KV value column
-- Modify `folder_timeline()` to filter out expired observations by default
-- Optional: Add background worker that sweeps/expunges expired observations
-
-**User Experience:**
-```python
-# Observation expires after 24 hours
-folder_observe(
-    kv, {
-        "folderPath": "/home/user/app/src/server",
-        "agentId": "my-agent",
-        "text": "Default port is 3000 for development",
-        "timestamp": now(),
-        "ttl": 86400  # 24 hours
-    }
-)
-
-# Timeline query automatically excludes expired observations
-timeline(kv, folder_path="/home/user/app/src/server")
-```
-
-Returns timeline without "port 3000" observation after 24 hours. Users can also check for specific expiry status on an observation with additional endpoint `/folder/observation/status/<id>`.
-
-**Implementation Complexity:** **25 minutes**  
-- Add TTL field to observation payload validation  
-- Store as extra JSON field in KV (existing table schema)  
-- Modify `folder_timeline()` query to include optional TTL filter:
-  ```python
-  ts > now() - ttl_seconds if ttl_seconds else None AND expiryTs > ts
-  ```  
-- Update search results to exclude expired observations  
-- Optional: Background worker sweeps for cleanup (simpler version doesn't need this)  
-
-**Risk:** Medium — requires changes to timeline query logic which users expect returns chronological activity. Must ensure backward compatibility with existing payloads that don't include TTL field (use `None` default).
-
----
-
-### 🎯 Feature 5: Memory Version History
-
-**Why Add This?**
-Long-term memories evolve. Currently `remember()` just overwrites the old memory. Users might accidentally overwrite important information or can't undo an incorrect memory. With versioning, each remember creates a new version tracked sequentially.
-
-**What to Implement:**
-```python
-def remember(kv, data, skip_versioning=False):
-    
-    # Check existing memories for this content
-    existing_memories = kv.get(KV.memories, "mem_abc123")
-    
-    if not skip_versioning and existing_memories:
-        # Append version suffix to old content (preserve as text)
-        current_content = json.loads(existing_memories["value"])
-        current_content["_version"] = len(current_content.get("_versions", [])) + 1
-        current_content["_createdTs"] = existing_memories["ts"]
-        
-        # Store in new version field
-        versions = current_content.get("_versions", [])
-        current_content["_versions"].append({
-            "content": current_content["content"],
-            "version": len(versions),
-            "ts": now(),
-            ...
-        })
-    
-    return {
-        "memoryId": new_id,
-        "versions": [...],  # New field: list of version history
-        ...
-    }
-```
-
-**Changes Required:**
-- Modify `remember()` to check for existing content match in KV memories
-- Append new version as JSON object to version history array  
-- Store version number and timestamp for each version change
-- Optionally expose version history endpoint for viewing past versions
-
-**User Experience:**
-When a user calls:
-```python
-remember(
-    kv, {
-        "content": "JWT authentication uses bearer token in Authorization header",
-        "concepts": ["jwt", "auth"],
-        ...
-    }
-)
-```
-
-The response includes version history showing how this memory has evolved over time. Later, if the user discovers more context:
-```python
-remember(
-    kv, {
-        "content": "JWT authentication uses Bearer token and JWT_SECRET key in Authorization header",
-        ...
-    }
-)
-```
-
-They can review past versions to see the evolution or optionally revert to earlier version by storing it again.
-
-**Implementation Complexity:** **20 minutes**  
-- Modify `remember()` to detect duplicate content (hash match on content field)  
-- Store version history as JSON array in KV value column (existing table schema, just more data)  
-- Optionally create endpoint `/memory/version/<id>` for viewing history  
-- Update tests to verify version history is stored correctly  
-
-**Risk:** Low — simple append operation to existing data structure. No schema migration needed since we're adding fields to existing JSON values. Backward compatible since previous versions without `_versions` field just get overwritten (which may be surprising behavior, but acceptable for safety).
-
----
-
-### 🎯 Feature 6: Search Result Citation with Source Links
-
-**Why Add This?**
-When a memory is returned from search, users can see where the original observation came from and what code context had it observed. This helps understand which files are most relevant to certain topics and provides better "view in context" capability for follow-up actions.
-
-**What to Implement:**
-```python
-def folder_observe(kv, payload):
-    # Store source file info
-    if payload.get("sourceFile"):
-        obs["sourceFile"] = payload["sourceFile"]
-        obs["lineNumber"] = payload.get("lineNumber") or None
-    
-    return {
-        "observationId": fobs_{hash}_{rand},
-        "sourceFile": "src/auth.py",  # New field: where this came from
-        ...
-    }
-```
-
-**Search Result Enhancement:**
-Modify search result response format:
-```python
-def folder_search(kv, query, limit, folder_path, agent_id):
-    
-    results = [
-        {
-            "id": obs_id,
-            "text": "...",
-            "folderPath": "/home/user/project",
-            "score": 0.85,  # Original BM25 score or vector similarity
-            "sourceFile": "src/auth.py",   # NEW: where this came from
-            "timestamp": ts.isoformat(),
-            ...
-        }
-    ]
-```
-
-**User Experience:**
-Search query: "JWT authentication"  
-Results now show source file links:
-```json
-[
-  {
-    "id": "fobs_abc123",
-    "text": "JWT needs refresh tokens for token rotation",
-    "sourceFile": "src/auth.py",  // Click link to see code context!
-    "score": 0.92,
-    ...
-  },
-  {
-    "id": "fobs_def456",  
-    "text": "Using 'jwt' import from auth package",
-    "sourceFile": "src/main.py",  // Another file
-    "score": 0.78,
-    ...
-  }
-]
-```
-
-**Implementation Complexity:** **20 minutes**  
-- Add `source_file` field to observation schema (same as Feature 2)  
-- Update search result formatting in `folder_search()` to include source file info from observations  
-- Optionally: Show which files are most-relevant based on sources of highest-scoring memories  
-
-**Risk:** Low — just need to read the new field from observations and format it in search results. No complex data structure change needed.
-
----
-
-### 🎯 Feature 7: Memory Impact / Related Memories Endpoint
-
-**Why Add This?**
-When a user remembers something important, they might want to know which other memories relate semantically or contextually. Currently all memories exist independently with no explicit linking mechanism. Adding semantic similarity scores helps users understand how new memories connect to existing knowledge and spot conflicts.
-
-**What to Implement:**
-```python
-def memory_related(kv, memory_id):
-    
-    # Get original memory content from KV
-    original_memory = kv.get(KV.memories, memory_id)
-    original_content = json.loads(original_memory["value"])
-    
-    # Search for semantically similar memories
-    search_results = hybrid_search.search(
-        query=original_content["content"],
-        limit=5,  # Return top 5 related memories
-        filter_scope=[KV.memories],  # Only search within memories scope
-    )
-    
-    # Score by similarity + rank in results list
-    return {
-        "memoryId": memory_id,
-        "relatedMemories": [
-            {
-                "id": "mem_abc123",
-                "score": 0.92,  # Semantic similarity score (0-1)
-                "reason": "Same concepts: JWT, authentication",
-                ...
-            },
-            ...
-        ]
-    }
-```
-
-**User Experience:**
-Request: `/agentcache/memories/related/mem_xyz123`  
-Response shows how this memory connects to existing knowledge:
-```json
-{
-  "memoryId": "mem_xyz123",
-  "relatedMemories": [
-    {
-      "id": "mem_abc456",
-      "score": 0.94,
-      "reason": "Same concepts (JWT) and file context (src/auth.py)",
-      "content": "JWT uses Bearer token format in Authorization header"
-    },
-    {
-      "id": "mem_def789",
-      "score": 0.78,
-      "reason": "Related to auth module but different concepts",
-      "content": "Using Express.js for REST API development"
-    }
-  ],
-  ...
-}
-```
-
-**Implementation Complexity:** **30 minutes**  
-- Use existing `HybridSearch.search()` method with original memory content as query  
-- Score by rank in results (1st highest = most related) + cosine similarity score  
-- Format response as JSON with reason descriptions generated from concept extraction  
-- Create new endpoint that takes memory ID and returns related items  
-
-**Risk:** Medium — requires leveraging existing search infrastructure. Must ensure the semantic search is fast enough (< 50ms response time). Also need to handle empty or non-existent memories gracefully (return helpful error).
-
----
-
-## Recommendation Priority
-
-As a user who relies on this tool daily for code context and observation management, here's my prioritization based on "bang for buck" — quick implementation with high utility:
-
-### **Priority 1 (Implement First): Observation Weighting**
-
-**Why #1:** Fastest to implement (~10 min), highest immediate value
-- Let me tag observations as priority 90-100 and have them surface prominently in search results  
-- No new data structures needed; just add one number to the existing weighting formula
-- Users already write some observations as "important issues" but they're weighted same as trivial notes
-
-**Implementation:**
-```python
-# New payload validation
-def folder_observe(kv, payload, priority=0):
-    # Validate priority is 0-100 range
-    if not (0 <= priority <= 100):
-        raise ValueError("priority must be between 0 and 100")
-```
-
-**Time:** ~10 min  
-**Risk:** None — modifies existing RRF function slightly  
-
----
-
-### **Priority 2: Folder Statistics Endpoint**
-
-**Why #2:** Simplest implementation with high utility for daily users
-- Users constantly need this info but it's not easily available via API calls
-- Just needs a few more lines of code following Flask pattern  
-- Query existing data without any schema changes
-
-**Implementation:**
-```python
-@app.route('/folder/stats/<path:folder_path>')
-def folder_stats():
-    # ~5 min implementation
-```
-
-**Time:** ~5 min  
-**Risk:** None — new endpoint, minimal queries  
-
----
-
-### **Priority 3: Observation Source Tracking**
-
-**Why #3:** Low risk, very useful for detecting patterns
-- Track which files user has observed about certain topics helps detect learning cycles  
-- One extra field in KV value dict — no schema changes  
-- Helps spot when user re-implements same code after reading tutorial
-
-**Implementation:**
-```python
-def folder_observe(kv, payload, source_file=None):
-    # ~10 min implementation
-```
-
-**Time:** ~15 min  
-**Risk:** Low — one optional field addition  
-
----
-
-### **Priority 4: Memory Version History**
-
-**Why #4:** Good safety feature, relatively simple to implement
-- Prevents accidental data loss  
-- Version history array in JSON value column is trivial to add  
-- Users love being able to see evolution of memories they've written
-
-**Implementation:**
-```python
-def remember(kv, data):
-    # ~15 min implementation
-```
-
-**Time:** ~20 min  
-**Risk:** Low — append operation, no schema changes  
-
----
-
-## Summary
-
-| Feature | Est. Time | Risk Level | User Impact |
-|---------|-----------|------------|-------------|
-| Observation Weighting | 10 min | None | High (control over search ranking) |
-| Folder Stats Endpoint | 5 min | None | High (quick stats access) |
-| Source Tracking | 15 min | Low | Medium (detect patterns) |
-| Memory Versioning | 20 min | Low | Medium (safety feature) |
-
-All four fit seamlessly into existing Flask/SQLite architecture without requiring any architectural changes or new dependencies. They leverage current infrastructure and enhance the user experience incrementally.

UBIQUITOUS_LANGUAGE.md

@@ -1,166 +0,0 @@
-# Ubiquitous Language — agentcache
-
-> This glossary defines the canonical terms used in agentcache's domain model.
-> Use these exact names in code, docs, PR descriptions, ticket titles, and conversations.
-> "Aliases to avoid" lists terms found in the codebase or tickets that should be replaced.
-> Last updated: July 2026 — incorporates architecture review, ubiquitous language session, and ticket breakdown.
->
-> **Architecture improvement tickets:** `.scratch/arch-improvements/issues/`
-
----
-
-## Core Memory Model
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Observation** | A single captured event from an agent's execution — one tool call, one prompt, one file edit — scoped to a Folder Pair. The atomic unit of Working Memory. | `log`, `event`, `entry`, `raw_observation`, `hook event` |
-| **Memory** | A manually saved, long-term insight, decision, or pattern — not derived from a single tool call but from deliberate agent reflection. | `long-term memory`, `global memory`, `insight`, `fact` (when used alone) |
-| **Lesson** | A reusable learning with a confidence score that decays over time; strengthened when the same pattern recurs. | `learning`, `tip`, `rule` |
-| **Slot** | A named, pinned piece of context — manually set or auto-populated — injected into every session start. | `pinned slot`, `memory slot`, `context slot` |
-| **Folder Pair** | The primary scope key: the combination of a `folderPath` and an `agentId` that uniquely identifies one agent's memory for one project directory. | `(folder, agent)`, `folder-agent pair`, `scope key`, `session` (when used to mean this) |
-| **Folder Metadata** | Aggregate statistics for a Folder Pair: observation count, last updated timestamp, and optional summary. | `folder meta`, `FolderMeta` |
-
----
-
-## Memory Tiers (Consolidation Pipeline)
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Working Memory** | The live, unprocessed stream of Observations for a Folder Pair — raw and ephemeral. | `raw observations`, `session logs` |
-| **Episodic Memory** | A compressed summary of a group of Observations for a Folder Pair, produced by the Consolidation pipeline. | `session summary`, `compressed episode`, `narrative` |
-| **Semantic Memory** | Stable factual knowledge extracted from multiple Episodic Memories by the Consolidation pipeline. | `fact`, `knowledge`, `semantic fact` |
-| **Procedural Memory** | A reusable workflow or decision pattern extracted from repeated cross-session patterns. | `procedure`, `workflow memory`, `pattern` (when used alone) |
-| **Consolidation** | The LLM-driven pipeline that compresses Working Memory → Episodic → Semantic → Procedural. Triggered manually or by the auto-forget sweep. | `crystallize`, `compress`, `summarize` |
-
----
-
-## Agents & Identity
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Agent** | An AI coding assistant (Claude, Kiro, Cursor, Cline, etc.) that writes Observations and reads Memory. | `client`, `AI`, `bot` |
-| **Agent ID** | A string identity for one agent instance, used as the second key in a Folder Pair. | `agentId`, `agent_id`, `agent name` |
-| **Agent Scope** | The isolation boundary for an Agent's data — either `shared` (sees all agents' data) or `isolated` (sees only its own). | `scope isolation`, `agent namespace` |
-| **MCP Client** | Any tool (Cursor, Claude Desktop, Kiro) that communicates with agentcache using the Model Context Protocol. | `plugin`, `integration`, `agent client` |
-
----
-
-## Search & Retrieval
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Recall** | A keyword-based search over Observations and Memories using the BM25 index. | `search`, `lookup`, `query` (when BM25 is implied) |
-| **Smart Search** | A hybrid search combining BM25 keyword matching and vector cosine similarity, fused by Reciprocal Rank Fusion (RRF). | `semantic search`, `hybrid search`, `vector search` |
-| **Folder Search** | A Recall or Smart Search scoped to one or more Folder Pairs. | `scoped search`, `project search` |
-| **Timeline** | A chronological, filterable feed of Observations for a Folder Pair. | `activity feed`, `history`, `replay feed` |
-| **Context Compilation** | The process of assembling Slots, Lessons, recent Episodic Memories, and a Profile into a single text block for agent injection at session start. | `context injection`, `context window prep`, `compile_context` |
-
----
-
-## Lifecycle & Maintenance
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Auto-Forget** | A background sweep that evicts Observations past their TTL or above the per-Folder-Pair cap, optionally running Consolidation before eviction. | `auto_forget`, `TTL sweep`, `pruning`, `cleanup` |
-| **Deduplication** | Removal of Observations whose text fingerprint (SHA-256) matches an existing Observation in the same Folder Pair. | `dedup`, `duplicate removal` |
-| **Privacy Scrub** | The process of stripping secrets, tokens, and API keys from Observation text before storage, using a regex-based policy. | `redaction`, `sanitization`, `strip_private_data` |
-| **Index Rebuild** | A background process that reprocesses all stored Observations and Memories into a fresh BM25 and vector index. | `reindex`, `rebuild_index`, `warm-up` |
-| **Audit Entry** | An append-only record of every write operation, stored in the audit log with agent ID and timestamp. | `audit log`, `commit`, `version` (legacy Dolt term — avoid) |
-
----
-
-## Knowledge Graph
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Relation** | A directed edge in the Knowledge Graph between two concepts, files, or Folder Pairs. | `graph edge`, `link`, `connection` |
-| **Knowledge Graph** | The set of Relations extracted from Observations, used to augment search retrieval with structural codebase topology. | `graph`, `concept graph`, `project graph` |
-| **Graph Extraction** | The LLM-driven process that reads Observations and produces Relations for the Knowledge Graph. | `graph build`, `relation extraction` |
-
----
-
-## Architecture & Module Structure
-
-These terms describe the codebase's structural concepts, used in tickets, PRs, and architecture discussions.
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **AppContext** | A single injectable dataclass that packages all runtime state (`kv`, `bm25`, `vector`, `embedder`, `broadcast`) — the replacement for module-level globals. Constructed once in `create_app()` and passed explicitly to every function that needs it. | `globals`, `module state`, `app state` |
-| **Deep Module** | A module with a narrow public interface that hides substantial implementation — the opposite of a shallow wrapper. The goal of every split in the god-module refactor. | `service`, `component`, `helper` |
-| **Adapter Seam** | The interface point where one concrete implementation can be swapped for another (e.g. `BaseVectorIndex` allows `InMemoryVectorIndex` to be replaced by an HNSW adapter). A seam becomes real once two concrete adapters exist. | `interface`, `abstraction layer`, `plugin point` |
-| **Expand–Contract** | The two-phase refactor pattern used for wide changes: first *expand* (add the new form alongside the old so CI stays green), then *contract* (delete the old form once all callers are migrated). | `big bang refactor`, `flag day`, `rewrite` |
-| **God Module** | An anti-pattern: a single module (`functions.py` at 4 583 lines) containing all domain logic, making it impossible to test any concern in isolation. Being eliminated via tickets 01–08. | `utils.py`, `helpers.py`, `core.py` (when used as a catch-all) |
-| **Auth Middleware** | A single `require_auth` decorator in `auth.py` that performs the timing-safe Bearer token check — the replacement for copy-pasted `_check_auth()` functions in every blueprint. | `_check_auth`, `auth function`, `bearer check` |
-| **MCP Tool Registry** | A `dict[str, Callable]` populated by `@register("tool_name")` decorators, replacing the 300-line `if/elif` dispatch chain in `routes/mcp.py`. | `tool dispatcher`, `elif chain`, `tool handler map` |
-| **Privacy Policy** | The documented, extensible set of regex patterns that defines what text is scrubbed before an Observation is stored. Lives in `privacy.py` as `DEFAULT_PATTERNS`. | `regex list`, `scrub rules`, `redaction rules` |
-| **Tracer Bullet** | A narrow, complete vertical slice of work that cuts through every layer (storage, logic, API, tests) and is demoable on its own. The unit of work in the ticket breakdown. | `task`, `story`, `sub-task` |
-
----
-
-## Infrastructure & Sync
-
-| Term | Definition | Aliases to avoid |
-|------|------------|-----------------|
-| **Folder Path** | The absolute filesystem path of the working directory that scopes a Folder Pair. | `cwd`, `directory`, `project path` |
-| **KV Store** | The SQLite-backed key-value store that persists all domain data as JSON values keyed by `(scope, key)`. | `database`, `store`, `StateKV` |
-| **HF Sync** | The process of backing up the KV Store to a private HuggingFace dataset repo and restoring it on startup. | `sync`, `backup`, `dataset sync` |
-| **Audit High-Water Mark** | The `MAX(id)` of the audit log, used by HF Sync to detect whether any writes have occurred since the last backup. | `HWM`, `sync cursor`, `change marker` |
-| **Index Shard** | A chunk of the serialized BM25 or vector index stored in the KV Store for persistence across restarts. | `index chunk`, `bm25 shard`, `vector shard` |
-
----
-
-## Relationships
-
-- An **Observation** belongs to exactly one **Folder Pair**.
-- A **Folder Pair** has exactly one **Folder Path** and exactly one **Agent ID**.
-- A **Folder Pair** accumulates many **Observations** and zero or one **Folder Metadata**.
-- **Consolidation** consumes **Observations** from a **Folder Pair** and produces **Episodic Memories**, which in turn feed **Semantic Memory** and **Procedural Memory**.
-- A **Lesson** exists globally — not scoped to a **Folder Pair**.
-- A **Slot** is scoped to either a project (matched by **Folder Path**) or global (all agents).
-- A **Memory** is global — not scoped to a **Folder Pair** — and may link to source **Observations** via `sourceObservationIds`.
-- **Recall** and **Smart Search** operate across all **Folder Pairs** (optionally filtered) and also include **Memories**.
-- **Context Compilation** assembles **Slots** + **Lessons** + **Episodic Memories** + **Profile** for one **Folder Pair** at session start.
-- An **AppContext** is constructed once per process and holds one **KV Store**, one BM25 index, one **Adapter Seam** for the vector index, one embedder, and one broadcast callable.
-- The **Auth Middleware** guards every route — the **MCP Tool Registry** handles dispatch after auth passes.
-- The **Privacy Policy** is applied to every **Observation** before it is written to the **KV Store** or the typed observations table.
-
----
-
-## Flagged Ambiguities
-
-- **"session"** is used in two conflicting ways:
-  1. *Legacy* — a `Session` object with a `sessionId`, from the pre-folder model (now read-only, used only for migration).
-  2. *Informal* — an agent's working period within a Folder Pair.
-  → Use **Folder Pair** for the scope concept and avoid "session" entirely in new code.
-
-- **"memory"** is used both as the general concept ("agent memory system") and as the specific entity (`Memory` — a saved insight). 
-  → In domain conversations, always qualify: **Working Memory**, **Episodic Memory**, **Semantic Memory**, **Procedural Memory**, or the entity **Memory** (capitalised).
-
-- **"crystallize" vs "consolidate"** — the codebase uses both for the same pipeline (LLM compression of Observations into higher-tier memories).
-  → Canonical term: **Consolidation**. `crystallize` is an alias to retire.
-
-- **"recall" vs "search" vs "smart search"** — three terms for overlapping operations.
-  → **Recall** = BM25 keyword search. **Smart Search** = hybrid BM25 + vector. **Folder Search** = either, scoped to a Folder Pair.
-
-- **"forget" vs "auto-forget" vs "evict"** — used interchangeably in code and docs.
-  → **Forget** = deliberate deletion triggered by an agent. **Auto-Forget** = background TTL sweep. **Eviction** = the act of removing one Observation during Auto-Forget.
-
----
-
-## Example Dialogue
-
-> **Dev:** "When an agent finishes a task, should it call `remember` or does the system handle that automatically?"
-
-> **Domain expert:** "Those are two different things. `remember` is for **Memories** — things the agent explicitly wants to preserve, like an architecture decision. The system automatically stores every tool call as an **Observation** in the **Folder Pair** via `folder_observe`. **Memories** are always deliberate."
-
-> **Dev:** "So if the agent never calls `remember`, does it lose everything?"
-
-> **Domain expert:** "No — the **Observations** are still there in **Working Memory** for that **Folder Pair**. But they're raw and noisy. **Consolidation** is what turns them into clean **Episodic Memories** that survive **Auto-Forget** eviction."
-
-> **Dev:** "What's the difference between a **Lesson** and a **Semantic Memory**?"
-
-> **Domain expert:** "A **Lesson** is something the agent explicitly learned and wants to reuse — it has a confidence score that decays. **Semantic Memory** is extracted automatically by the **Consolidation** pipeline from patterns across **Episodic Memories**. You save a **Lesson**; the system extracts **Semantic Memory**."
-
-> **Dev:** "And a **Slot** is different from both?"
-
-> **Domain expert:** "Yes. A **Slot** is pinned context — the agent or developer sets it manually and it gets injected at every session start via **Context Compilation**. Think of it as a sticky note, not a memory."

agentcache.md

@@ -1,33 +0,0 @@
-# AgentCache Automation & Client Hook Roundabout
-
-This file documents the technical details and configurations for automating memory sessions, observations, and prompt-context syncing in environments that lack native client-side hook runners.
-
----
-
-## 1. PowerShell-Level Console Hook Automation
-For standard command shells that do not have custom plugins (such as PowerShell), we have implemented a native console hook system directly in the user profile:
-* **Profile File**: `D:\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
-* **Automation Mechanism**:
-  1. **Prompt Redefinition**: Overrides the default PowerShell `prompt` function to retrieve the last executed command from the session history (`Get-History`).
-  2. **Asynchronous Dispatch**: Uses PowerShell's `Start-Job` to send the command, execution status, and duration to the Hugging Face Space database (`https://yash030-agentcache-python.hf.space/agentcache/observe`) in the background, keeping terminal prompts lag-free.
-  3. **Interactive Shield**: Wraps the prompts and startup session creation in `if (-not [Console]::IsInputRedirected)` so background script executions or tool runners do not pollute the database.
-  4. **Active Session Reuse**: On console startup, checks for a cached session ID in `current_session.txt` and reuses it to prevent session clutter.
-
----
-
-## 2. Antigravity Chat Sync Loop
-Because the Gemini Antigravity agent runs inside a transient prompt-response loop sandbox, we automate chat log syncing through a shell-level daemon job:
-* **Sync Script**: `C:\Users\yashw\.gemini\antigravity\sync_antigravity.py`
-* **Daemon Job**: Appended to the PowerShell profile as a background `Start-Job` loop named `AntigravitySync`.
-* **Execution Heuristic**:
-  - The job runs a continuous loop that executes the sync script every 30 seconds.
-  - Uses a lock file (`sync_antigravity.lock`) to ensure only a single terminal window runs the sync globally.
-  - The script parses `transcript.jsonl` from the local `brain/` directory and uploads new user prompts and response turns to the Hugging Face Space under the session `antigravity_<conversation_id>`.
-
----
-
-## 3. Configuration & Controls
-To control this automation inside PowerShell, use the following commands:
-* **`Start-MemorySession -project "name"`**: Starts a new memory session. Use the `-Force` switch to override any active session.
-* **`End-MemorySession`**: Ends the active session, marking it completed and cleaning up the local cache file.
-* **`Get-Job -Name "AntigravitySync"`**: Checks the status of the background chat sync thread.

issues.md

@@ -1,273 +0,0 @@
-# Technical Issues, Bugs, & Architecture Audit: agentmemory-python
-
-This document details all technical anomalies, display bugs, synchronization issues, and functional mismatches discovered during the code audit of the `agentmemory-python` project.
-
----
-
-## Category A: Syntax & Technical Code Correctness
-
-### 1. SQLite Parameterization Syntax Error (`%s` vs `?`)
-* **File & Lines:** [src/functions.py:L411-429](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L411-L429) (within `IndexPersistence.save_sharded_index`)
-* **The Code:**
-  ```python
-  cursor.execute(
-      "SELECT DISTINCT scope FROM kv_store WHERE scope LIKE %s",
-      (scope_prefix + "%",)
-  )
-  ...
-  format_strings = ','.join(['%s'] * len(chunk_delete))
-  cursor.execute(
-      f"DELETE FROM kv_store WHERE scope IN ({format_strings})",
-      tuple(chunk_delete)
-  )
-  ```
-* **Root Cause:** The database backend uses standard Python `sqlite3`, which expects `?` placeholders for parameter injection. `%s` is specific to MySQL or PostgreSQL clients.
-* **Consequence:** Executing `save_sharded_index` throws a `sqlite3.OperationalError` every time it attempts to clean up old sharded indexes. This error is captured in a silent `try-except` block, meaning old shards are **never** deleted, leading to database bloat.
-* **Remediation:** Replace `%s` with `?` in both queries:
-  ```python
-  cursor.execute(
-      "SELECT DISTINCT scope FROM kv_store WHERE scope LIKE ?",
-      (scope_prefix + "%",)
-  )
-  ...
-  format_strings = ','.join(['?'] * len(chunk_delete))
-  ```
-
-### 2. Thread Safety Write Locks Omitted
-* **File & Lines:** [src/db.py:L75-105](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/db.py#L75-L105) (within `StateKV.set` and `StateKV.delete`)
-* **The Code:** The `set()`, `delete()`, and `commit_version()` write methods execute queries and transactions directly on SQLite connections without acquiring `self._lock`. Only `update()` acquires the lock:
-  ```python
-  def update(self, scope: str, key: str, ops: List[Dict[str, Any]]) -> Optional[Any]:
-      with self._lock:
-          ...
-  ```
-* **Root Cause:** SQLite operates database-level write serialization. In a multi-threaded Flask environment, two threads making concurrent database modifications (one inside `update` and another executing a basic `set` or `delete`) can cause a database race condition.
-* **Consequence:** Occasional `sqlite3.OperationalError: database is locked` exceptions, transaction rollbacks, or lost writes.
-* **Remediation:** Wrap the database write operations in `set()`, `delete()`, and `commit_version()` with `with self._lock:`.
-
-### 3. Nonexistent Delete Memory API Endpoint Called
-* **File & Lines:** [src/viewer/index.html:L2813](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L2813) (within `confirmDeleteMemory`)
-* **The Code:**
-  ```javascript
-  await apiDelete('governance/memories', { memoryIds: [id], reason: 'Deleted via viewer' });
-  ```
-* **Root Cause:** The backend [src/app.py](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/app.py) contains no `/agentmemory/governance/memories` endpoint. It processes deletions via a `POST` route at `/agentmemory/forget`, which expects a payload of `{"memoryId": "<id>"}`.
-* **Consequence:** The delete memory request fails with an HTTP 404 / 405 error, leaving memories undeletable from the UI.
-* **Remediation:** Update `confirmDeleteMemory` to call `apiPost` on the correct path and query structure:
-  ```javascript
-  await apiPost('forget', { memoryId: id });
-  ```
-
-### 4. Nonexistent Graph Modification Endpoints Called
-* **File & Lines:** [src/viewer/index.html:L2292](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L2292) and [L2404](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L2404)
-* **The Code:**
-  ```javascript
-  // L2292 (expanding neighbors)
-  var result = await apiPost('graph/query', { startNodeId: nodeId, maxDepth: 1 });
-  ...
-  // L2404 (rebuilding graph)
-  await apiPost('graph/build', {});
-  ```
-* **Root Cause:** The backend lacks routes for `/graph/query` and `/graph/build`. It only implements a read-only endpoint `/agentmemory/graph/stats`.
-* **Consequence:** Interactive graph expansion and manual rebuilding fail with HTTP 404 errors in the console.
-* **Remediation:** Register endpoints `/agentmemory/graph/query` and `/agentmemory/graph/build` in `app.py` or remove these interactive buttons from the dashboard sidebar if they are not supported by the Python backend.
-
----
-
-## Category B: Functional Alignment & Purpose Verification
-
-### 1. Project-Scoped Memory Slots Collapsing into Global Scope
-* **File & Lines:** [src/functions.py:L1277](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L1277) (within `slot_create`) and [L1216](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L1216) (within `list_pinned_slots`)
-* **The Code:**
-  ```python
-  # L1277
-  target_kv = KV.globalSlots if scope == "global" else KV.slots
-  ...
-  # L1216
-  p_slots = kv.list(KV.slots)
-  ```
-* **Root Cause:** The KV namespace for project-scoped slots is hardcoded as `KV.slots = "mem:slots"`. This is a single, shared global namespace for all projects.
-* **Consequence:** Project scoping is broken. Any project-scoped slot (e.g. `current_task` or `project_context`) is saved under the global `mem:slots` namespace. If Project A writes to `current_task`, it overwrites Project B's `current_task`. Furthermore, Project B inherits Project A's slots, violating intended project isolation boundaries.
-* **Remediation:** Derive the project slots database scope dynamically by incorporating the project ID or path name. For example:
-  ```python
-  # In functions.py, scope project slots by project name
-  def project_slots_scope(project: str) -> str:
-      return f"mem:slots:{project}"
-  ```
-  And update `slot_create`, `slot_append`, `slot_replace`, `slot_delete`, and `context` retrieval to pass the project name and use this dynamic scope prefix.
-
-### 2. Aggressive Auto-Completion of Parallel Sessions
-* **File & Lines:** [src/functions.py:L117-131](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L117-L131) (within `auto_complete_old_active_sessions`)
-* **The Code:**
-  ```python
-  def auto_complete_old_active_sessions(kv: StateKV, current_session_id: str) -> int:
-      sessions = kv.list(KV.sessions)
-      count = 0
-      for s in sessions:
-          if s.get("id") != current_session_id and s.get("status") == "active":
-              s["status"] = "completed"
-              ...
-              kv.set(KV.sessions, s["id"], s)
-  ```
-* **Root Cause:** The system operates under the assumption that only one agent session can be active globally. Starting a session or recording an observation automatically marks all other active sessions as completed.
-* **Consequence:** If multiple workspaces, parallel subagents, or agents operate concurrently using the same backend, they force-close each other's sessions. Observations are then recorded against closed sessions, or new sessions are spawned, constantly closing others.
-* **Remediation:** Scour out the global session force-completion. Sessions should only be closed:
-  - Explicitly via the `/session/end` endpoint
-  - When matching the exact project or agent scope (e.g., only auto-complete active sessions belonging to the same project or the same `agentId`).
-
-### 3. Agent Scoping Bypassed in MCP Tools
-* **File & Lines:** [src/app.py:L2200-2226](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/app.py#L2200-L2226) (within `memory_sessions` and `memory_observations` MCP handlers)
-* **The Code:** The REST routes respect `AGENTMEMORY_AGENT_SCOPE=isolated` to restrict session/observation lookups to the configured `agentId` (via `functions.is_agent_scope_isolated()`). However, the MCP tool handlers fetch data globally:
-  ```python
-  # L2206 - MCP memory_sessions handler
-  sessions = functions.list_sessions(kv)  # Fetches all sessions globally
-  ```
-* **Root Cause:** The MCP dispatch logic calls the database list functions directly without checking or applying the agent isolation filters.
-* **Consequence:** An agent running in an isolated environment (`AGENTMEMORY_AGENT_SCOPE=isolated`) can query other agents' sessions and observations via the MCP tools, violating the promised security isolation boundary.
-* **Remediation:** Apply `is_agent_scope_isolated()` and `get_agent_id()` filters inside the MCP dispatcher cases for `memory_sessions` and `memory_observations`.
-
-### 4. Telemetry Events and Gauges Legacy Debt
-* **File & Lines:** [src/viewer/index.html:L1596-1637](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L1596-L1637) (within `renderDashboard`)
-* **Root Cause:** The dashboard UI has gauge components for CPU, Heap memory, RSS memory, Event loop lag, and Circuit Breaker states, which are legacy features from the Node.js implementation. The Python Flask server returns a minimal hardcoded health structure:
-  ```python
-  # functions.py L2177
-  return {
-      "status": "healthy" if db_status == "connected" else "degraded",
-      "service": "agentmemory",
-      "version": "0.9.8",
-      "database": "dolt", # Legacy name, database is actually sqlite
-      "databaseStatus": db_status
-  }
-  ```
-* **Consequence:** The gauges show empty, fallback, or zero values in the dashboard. Additionally, the database type displays as `"dolt"`, which is legacy debt (the project is now SQLite).
-* **Remediation:** 
-  - Update `health_check` in [src/functions.py](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L2170) to return `"database": "sqlite"`.
-  - To support the UI gauges, implement basic process metric collection in Python (e.g. using `os` or `resource` packages) to return CPU and Memory stats, or simplify the dashboard UI to omit Node-specific gauges.
-
----
-
-## Category C: Real-Time Data Synchronization
-
-### 1. Consolidated Memories Bypassing Search Indexes
-* **File & Lines:** [src/functions.py:L2512](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L2512) and [L2532](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L2532) (within `consolidate` memory saving loops)
-* **The Code:**
-  ```python
-  kv.set(KV.memories, evolved["id"], evolved)
-  ...
-  kv.set(KV.memories, memory["id"], memory)
-  ```
-* **Root Cause:** When memories are merged or consolidated, they are saved directly to the SQLite database via `kv.set()`, but they are **never** added to the BM25 index (`_bm25_index.add()`) or the Vector index (`vector_index_add_guarded()`).
-* **Consequence:** Consolidated memories remain search-invisible. They are omitted from search results (`memory_recall`, `memory_smart_search`) and context compilation until the server is rebooted (rebooting forces index rebuild from the DB).
-* **Remediation:** Add indexing commands directly after saving the memory in `consolidate`:
-  ```python
-  # Index evolved memory
-  try:
-      _bm25_index.add(memory_to_observation(evolved))
-  except Exception:
-      pass
-  comb_text = evolved["title"] + " " + evolved["content"]
-  vector_index_add_guarded(evolved["id"], "memory", comb_text, {"kind": "memory", "logId": evolved["id"]})
-  ```
-  Repeat this for the newly created `memory` object on line 2532.
-
-### 2. Raw Observations Overwritten by Compressed Observations
-* **File & Lines:** [src/functions.py:L719](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L719) and [L770](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/functions.py#L770) (within `observe`)
-* **The Code:**
-  ```python
-  # L719 - Save raw observation
-  kv.set(KV.observations(session_id), obs_id, raw)
-  ...
-  # L770 - Overwrite with synthetic/compressed observation
-  kv.set(KV.observations(session_id), obs_id, synthetic)
-  ```
-* **Root Cause:** Both calls write to the exact same scope (`KV.observations(session_id)`) and key (`obs_id`).
-* **Consequence:** The raw observation is completely overwritten. The backend endpoints and APIs designed to fetch "raw" vs. "compressed" observations are redundant, as only the compressed version is stored (with raw inputs nested inside the `raw` field).
-* **Remediation:** Store raw observations under a separate database key or suffix (e.g. `f"{obs_id}:raw"`), or store them in a distinct scope (e.g. `KV.rawObservations(session_id)`).
-
----
-
-## Category D: Frontend Page Connection & Tab Synchronization
-
-### 1. Silent WebSocket Message Discard (Payload Shape Mismatch)
-* **File & Lines:** [src/viewer/index.html:L4130](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L4130) (within `ws.onmessage` event listener)
-* **The Code:**
-  ```javascript
-  ws.onmessage = function(e) {
-    if (state.ws !== ws) return;
-    try {
-      var msg = JSON.parse(e.data);
-      if (msg.type === 'stream' && msg.event) {
-        handleStreamEvent(msg);
-      } else if (msg.event_type && msg.data) {
-        handleStreamEvent({ event: { type: 'create', data: msg.data, event_type: msg.event_type } });
-      }
-    } catch {}
-  };
-  ```
-* **Root Cause:** The Python backend broadcasts observations in the following structure:
-  - `{"type": "raw_observation", "sessionId": ..., "data": {"type": "raw", "observation": {...}}}`
-  - `{"type": "compressed_observation", "sessionId": ..., "data": {"type": "compressed", "observation": {...}}}`
-  Neither has `msg.type === 'stream'` or `msg.event_type`.
-* **Consequence:** The WebSocket parser silently ignores all server-sent broadcasts. Real-time logging of new observations or commands is broken.
-* **Remediation:** Add handlers for Python's `raw_observation` and `compressed_observation` messages:
-  ```javascript
-  if (msg.type === 'raw_observation' || msg.type === 'compressed_observation') {
-    if (msg.data && msg.data.observation) {
-      routeWsMessage({ observation: msg.data.observation });
-    }
-  } else if (msg.type === 'stream' && msg.event) {
-     ...
-  ```
-
-### 2. WebSocket Connection Disabling Fallback Polling
-* **File & Lines:** [src/viewer/index.html:L4125](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L4125) (within `ws.onopen`)
-* **Root Cause:** When the WebSocket connection succeeds, the frontend calls `stopPolling()`.
-* **Consequence:** Because WebSocket events are silently discarded due to the payload mismatch, and polling is stopped, the dashboard ceases to update at all once the WebSocket is connected. The UI remains completely frozen.
-* **Remediation:** Fixing the WebSocket event parsing (Issue D1) will restore live updates. Additionally, if the WebSocket disconnects, the polling mechanism must be correctly re-triggered.
-
-### 3. Cached Pages/Tabs Preventing Sync on Navigation
-* **File & Lines:** [src/viewer/index.html:L1502-1518](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L1502-1518) (within `loadTab`)
-* **The Code:**
-  ```javascript
-  async function loadTab(tab) {
-    switch(tab) {
-      case 'dashboard': if (!state.dashboard.loaded) await loadDashboard(); break;
-      case 'graph': if (!state.graph.loaded) await loadGraph(); break;
-      case 'memories': if (!state.memories.loaded) await loadMemories(); break;
-      ...
-    }
-  }
-  ```
-* **Root Cause:** A tab's data is only fetched the first time it is visited (when `.loaded` is `false`).
-* **Consequence:** Switching between tabs (e.g. from Dashboard to Sessions or Memories) displays stale cached data. The user has to hit the browser refresh button to see updates.
-* **Remediation:** Force data reload when a tab is clicked, or provide a visual indicator and auto-refresh trigger when switching tabs:
-  ```javascript
-  // Always load fresh data on switch, or reset the loaded flag
-  async function loadTab(tab) {
-    switch(tab) {
-      case 'dashboard': await loadDashboard(); break;
-      case 'graph': await loadGraph(); break;
-      case 'memories': await loadMemories(); break;
-      ...
-    }
-  }
-  ```
-
-### 4. Flat Project Name Skipping in Graph Construction
-* **File & Lines:** [src/viewer/index.html:L1871](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L1871) and [L1893](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/viewer/index.html#L1893) (within `loadGraph`)
-* **The Code:**
-  ```javascript
-  if (!path.includes('/') && !path.includes('\\')) return;
-  ```
-* **Root Cause:** The graph builder ignores any session/memory whose project path does not contain a slash or backslash.
-* **Consequence:** If project names are stored as simple strings (e.g. `agentmemory-python` or `demo_project` rather than absolute directories), they are omitted from the graph, rendering the Graph tab entirely empty (0 nodes, 0 edges).
-* **Remediation:** Remove the slash-enforcement condition so any non-empty project name is rendered:
-  ```javascript
-  // Remove: if (!path.includes('/') && !path.includes('\\')) return;
-  ```
-
-### 5. Empty Graph Nodes Card on Dashboard
-* **File & Lines:** [src/app.py:L990-996](file:///d:/Downloads/Projects/Other%20Projects/agentmemory-python/src/app.py#L990-L996) (within `api_graph_stats`)
-* **Root Cause:** The Dashboard tab's "Graph Nodes" card displays stats queried from the backend `/graph/stats` endpoint. The backend queries `kv.list(KV.graphNodes)` and `kv.list(KV.graphEdges)`. However, the Python backend never writes to these scopes.
-* **Consequence:** The "Graph Nodes" card always displays `0` even when the Graph tab successfully visualizes active sessions and folders.
-* **Remediation:** Calculate these stats dynamically in `api_graph_stats` based on the counts of active unique project paths in the sessions and memories lists, matching the client-side folder map logic.

product_roadmap.md

@@ -1,39 +0,0 @@
-# Project Roadmap: Prototype to Production
-
-This document outlines the phased roadmap for scaling our Memory Server project from a prototype to a robust, production-ready product. Each phase builds upon the last, focusing sequentially on Security, Features, Deployment, and Monitoring.
-
-## Phase 1: Stabilization & Hardening (Security First)
-**Goal:** Eliminate critical vulnerabilities, patch security gaps, and ensure core functionality is robust against common exploits.
-
-### Tasks
-1.  **Security Audit**: Review all authentication logic (`AGENTCACHE_SECRET` usage) across API endpoints to enforce strict access control checks.
-2.  **Input Sanitization**: Implement rigorous input sanitization for all data ingress points (API calls, WebSocket messages) to mitigate SQL injection and XSS risks.
-3.  **Dependency Hardening**: Audit `requirements.txt` and update all dependencies to their latest secure versions, flagging any version downgrade/upgrade that could introduce a vulnerability.
-4.  **Test Baseline**: Run full test suite (`pytest`) and fix every failing test before moving to Phase 2.
-
-## Phase 2: Feature Parity & Depth
-**Goal:** Implement all planned features that were marked as incomplete or missing, bringing the system closer to its intended scope.
-
-### Tasks
-1.  **Memory Deep Dive**: Fully implement complex memory routines like `folder_graph_build` and ensure atomic behavior for `remember`/`forget` operations.
-2.  **Search Optimization**: Optimize the hybrid search component (RRF parameters) and profile database queries to improve retrieval performance.
-3.  **MCP Tool Completion**: Complete functionality for all remaining tools listed in `/mcp/tools`.
-4.  **UX Polish**: Enhance the dashboard viewer (`/viewer`) to provide clear, actionable feedback on system status (e.g., current embedding model, load metrics).
-
-## Phase 3: Productionization & Deployment
-**Goal:** Prepare the application for a stable, scalable production environment.
-
-### Tasks
-1.  **Containerization**: Write optimized Dockerfiles for the Flask application and dependencies to ensure environment parity across environments.
-2.  **Configuration Decoupling**: Refactor configuration loading to strictly adhere to container-native practices (using ENV variables exclusively) rather than relying on local `.env` file structures for production use.
-3.  **Performance Tuning**: Conduct load testing to identify I/O bottlenecks (DB access, network latency). Tune database indices and optimize WebSocket message throughput.
-4.  **Scalability Design**: Analyze the statelessness of components to determine optimal strategies for horizontal scaling (e.g., separate API workers vs. WebSocket workers).
-
-## Phase 4: Monitoring & Iteration (Live Operations)
-**Goal:** Establish continuous monitoring and a feedback loop for post-launch maintenance.
-
-### Tasks
-1.  **Observability Stack**: Implement structured logging across all modules to facilitate easy debugging in production.
-2.  **Metrics Collection**: Integrate Prometheus metrics collection for tracking latency, resource utilization, and error rates.
-3.  **Anomaly Detection**: Configure alerts for performance degradation or excessive error rates in the data access layer.
-4.  **Feedback Mechanism**: Design and implement a simple feedback mechanism for collecting post-launch bug reports and feature requests.

questions.md

@@ -1,176 +0,0 @@
-# Architectural Questions for agentcache
-
-These are design and architecture questions raised by the current codebase.
-They are not criticisms — they are things worth understanding and deciding on
-before the system grows. Each one points to a real trade-off or risk.
-
----
-
-## 1. Flat KV Schema
-
-The entire data model lives in one SQLite table: `kv_store(scope, key, value TEXT)`.
-Observations, memories, index shards, sessions, lessons, slots, graph edges, and
-image refs all share this single namespace.
-
-- What happens to read performance when this table grows to 100k+ rows?
-- Every "query" loads an entire scope into Python and filters in memory — no
-  SQL-level filtering by timestamp, type, or importance. Is that intentional?
-- Why not give each data type its own table with typed columns, which would
-  enable proper indexes and range queries at the DB level?
-
----
-
-## 2. In-Memory Index with a Cold-Start Window
-
-The BM25 and vector indexes live entirely in Python process memory. On restart,
-the server either deserializes them from SQLite or rebuilds them from scratch in
-a background thread.
-
-- During the rebuild window, searches return results from an empty or stale
-  index. Users get silently degraded results with no indication.
-- Is there a "index warming" status exposed anywhere? The `/health` endpoint
-  could surface this, but does it?
-- For large datasets, how long does the rebuild take? Is there a bound on that?
-
----
-
-## 3. Vector Index is a Flat Python List
-
-`VectorIndex.search()` iterates over every stored vector and computes cosine
-similarity one by one. This is O(n) per query.
-
-- At 10k observations this is already slow. At 100k it is unusable.
-- There is no ANN (approximate nearest neighbor) index — no HNSW, no IVF, no
-  external vector DB.
-- The EPIC mentions Qdrant/Chroma as future backends. What is the plan and
-  threshold for switching?
-
----
-
-## 4. Single Auth Token (No RBAC)
-
-Authentication is one shared secret compared with `hmac.compare_digest`. Every
-client — viewer, agent, admin — uses the same token.
-
-- If the token leaks from one agent config, everything is exposed.
-- The viewer dashboard, the `/forget` endpoint (which can delete all data), and
-  the `/migrate` endpoint all share the same credential level.
-- The EPIC mentions RBAC (viewer/agent/admin tokens). Is there a plan to
-  implement this before exposing the server to a network?
-
----
-
-## 5. Global Module-Level State
-
-`functions.py` declares `_bm25_index`, `_vector_index`, `_embedding_provider`,
-`_hybrid_search`, and `_stream_broadcaster` as module-level globals. They are
-set once at startup and mutated by every request.
-
-- This makes the application impossible to unit test in isolation (you cannot
-  inject a fresh index per test).
-- It also makes it impossible to run two instances in the same process (e.g.
-  for testing).
-- Was this a deliberate simplicity trade-off, or just how it grew?
-
----
-
-## 6. No Rate Limiting or Input Size Caps on Most Endpoints
-
-Observations are capped at 4000 characters. But memories, lessons, slots, and
-graph edges have no enforced size limits. The `/agent/observe` endpoint accepts
-arbitrary JSON payloads.
-
-- A misbehaving or compromised agent could flood the server with gigabytes of
-  data and exhaust disk space.
-- There is no per-agent write rate limit, no total storage quota, and no
-  backpressure mechanism.
-- Is this acceptable for the current single-user local use case? What changes
-  if this is exposed as a shared service?
-
----
-
-## 7. HuggingFace Sync Backs Up the Entire SQLite File
-
-`sync.py` uploads the whole `agentcache.db` file to a HuggingFace dataset repo,
-including the BM25/vector index shards stored inside it.
-
-- The index shards can be large and are fully reproducible from raw observations.
-  Syncing them wastes bandwidth and storage.
-- The backup is not incremental — it uploads the whole file every time the
-  audit high-water mark changes.
-- If the HF token is compromised, all user memory data (observations, memories,
-  lessons) is exposed. Is that risk documented anywhere for users?
-
----
-
-## 8. `functions.py` is ~2000 Lines — a God Module
-
-All business logic lives in one file: observation ingestion, memory CRUD,
-search orchestration, consolidation, auto-forget, graph building, slot
-management, lessons, image store, index persistence, and privacy scrubbing.
-
-- This makes it hard to test any single concern in isolation.
-- It creates implicit coupling — a change to how observations are stored can
-  accidentally affect how the index is rebuilt or how memories are versioned.
-- What would it look like to split this into focused modules
-  (e.g. `observations.py`, `memories.py`, `indexing.py`, `consolidation.py`)?
-
----
-
-## 9. Jaccard Similarity for Memory Deduplication
-
-`remember()` checks for duplicate memories by computing Jaccard similarity
-(word overlap) between the new content and all existing memories, with a
-threshold of 0.7.
-
-- This loads all memories into Python memory on every `remember()` call.
-- Jaccard on raw word sets is a weak signal for semantic similarity — two
-  memories about the same concept but phrased differently score low and
-  both get stored.
-- With a vector embedding provider active, why not use cosine similarity
-  against the vector index for deduplication instead?
-
----
-
-## 10. The MCP Endpoint Duplicates Auth and Dispatch Logic
-
-`routes/mcp.py` has its own `_check_auth()` function, its own `_get_kv()` helper,
-and a large `if/elif` chain dispatching 30+ tool names. The same auth logic
-exists in other route blueprints too.
-
-- Auth is copy-pasted across at least 3 places. A future change (e.g. adding
-  RBAC) would require updating each copy.
-- The tool dispatch chain has no registry — adding a new tool requires editing
-  a long elif block rather than registering a handler.
-- Was there a reason not to use a decorator-based dispatch registry or a shared
-  auth middleware?
-
----
-
-## 11. Privacy Scrubbing is a Regex List — Not a Policy
-
-`strip_private_data()` removes secrets by matching a hardcoded list of regex
-patterns (API keys, tokens, passwords). It runs on raw observation text before
-storage.
-
-- If an agent logs a secret with an unusual key name (e.g. `my_service_cred`),
-  it passes through unredacted.
-- The scrubbing happens *after* the data is already in the Python process —
-  if the process crashes mid-scrub, the raw data may already be partially
-  visible in a WAL frame.
-- Is the current regex set documented so users can audit and extend it?
-
----
-
-## 12. No Tests
-
-The `tests/` directory appears to be empty or minimal. For a system that
-persists agent memory and is used as a source of truth for AI context:
-
-- How do you verify that `folder_search` returns the right results after an
-  observation is added and the index is updated?
-- How do you catch regressions in privacy scrubbing when you add a new pattern?
-- How do you verify that the HF sync does not upload stale data after a
-  failed WAL checkpoint?
-- What is the plan for adding test coverage before the system is used in
-  production or shared with other developers?