diff --git a/.codex-plugin/marketplace.json b/.codex-plugin/marketplace.json
index 2065fc357e..99aee3092c 100644
--- a/.codex-plugin/marketplace.json
+++ b/.codex-plugin/marketplace.json
@@ -10,13 +10,13 @@
"source": "git-subdir",
"url": "https://github.com/davidrobertson/agentmemory.git",
"path": "./plugin",
- "ref": "v0.9.28-codex.2"
+ "ref": "v0.9.30-codex.1"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
- "category": "Memory"
+ "category": "Developer Tools"
}
]
}
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 89ba547eda..59cad81a3b 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "agentmemory",
- "version": "0.9.29-codex.1",
+ "version": "0.9.30-codex.1",
"description": "Persistent memory for Cursor: auto-captures sessions, prompts, and tool use via hooks, recalls with hybrid BM25 + vector + graph search, and exposes 54 memory tools over MCP. Keyless by default, runs entirely on your machine.",
"author": {
"name": "Rohit Ghumare",
diff --git a/.env.example b/.env.example
index 9d346ea191..6f112252d5 100644
--- a/.env.example
+++ b/.env.example
@@ -9,9 +9,9 @@
# LLM key, no embedding key, and no API auth. Set keys here only when you
# want to enable the corresponding feature.
#
-# Run `npx @agentmemory/agentmemory init` to copy this file into place
-# automatically. Run `npx @agentmemory/agentmemory doctor` to verify that
-# the daemon reads the env you expect.
+# Run `npx -y @agentmemory/agentmemory@latest init` to copy this file into
+# place automatically. Run `npx -y @agentmemory/agentmemory@latest doctor`
+# to verify that the daemon reads the env you expect.
#
# Defaults shown in comments. Listed in priority order — the first key
# present wins on the LLM detection path (see src/config.ts::detectProvider).
@@ -21,8 +21,24 @@
# -----------------------------------------------------------------------------
#
# Without a provider key, agentmemory runs in noop mode: observations are
-# indexed via zero-LLM synthetic compression, hybrid search still works,
+# indexed via zero-LLM synthetic compression and BM25 recall still works,
# but LLM-backed summarisation / reflection / consolidation are disabled.
+# A provider key alone does not enable LLM-written observation compression;
+# that path also requires AGENTMEMORY_AUTO_COMPRESS=true.
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma/space list of tool names or globs to capture; when set, only these are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra tool names or globs to skip, added to the defaults (memory_*, toolsearch, listmcpresources, fetchmcpresource)
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output stored per captured observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for context injected by the PreCompact hook; 0 disables it
+# AGENTMEMORY_CAPTURE_MAX_ATTEMPTS=5 # Attempts before a capture becomes a dead letter
+# AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS=10000 # Retry sweep interval and backoff base
+# AGENTMEMORY_CAPTURE_DEDUP_HOURS=168 # How long stored event ids block replays
+# AGENTMEMORY_CAPTURE_EVENTS_MAX=100000 # Max stored event ids
+# AGENTMEMORY_CAPTURE_INBOX_MAX=10000 # Max unprocessed events before 503
+# AGENTMEMORY_CAPTURE_DEAD_MAX=1000 # Max dead letters kept
+# AGENTMEMORY_CAPTURE_SPOOL=false # Turn off the hook offline spool
+# AGENTMEMORY_CAPTURE_SPOOL_DIR= # Spool folder (default /capture-spool)
+# AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES=5242880 # Spool size limit
+# AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS=168 # Spooled records older than this are dropped
# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
@@ -55,7 +71,7 @@
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk
# child sessions). Off by default — the agent-sdk fallback can trigger
-# Stop-hook recursion (#149 follow-up) when invoked from inside Claude Code.
+# Stop-hook recursion when invoked from inside Claude Code.
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# FALLBACK_PROVIDERS=anthropic,gemini # Comma-separated chain tried after the primary provider returns an error (e.g. rate limit)
@@ -64,10 +80,14 @@
# 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
# -----------------------------------------------------------------------------
#
-# Without an embedding key, agentmemory runs in BM25-only mode for hybrid
-# search. Detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
+# Without an embedding provider, vector embeddings are disabled. `mem::search`
+# uses BM25; `mem::smart-search` can also fuse structural graph matches when
+# graph data exists. Remote
+# provider detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
-# local (Xenova/all-MiniLM-L6-v2, 384-dim).
+# BM25-only. Local embeddings are an explicit opt-in, not the keyless default.
+# `EMBEDDING_PROVIDER=local` uses Xenova/all-MiniLM-L6-v2 (384-dim) on-device;
+# the first embedding request downloads the model and needs network access.
# EMBEDDING_PROVIDER=local # local | openai | voyage | cohere | gemini | openrouter
@@ -76,6 +96,8 @@
# COHERE_API_KEY=... # General-purpose embeddings
# Reuses OPENAI_API_KEY / OPENAI_BASE_URL above when EMBEDDING_PROVIDER=openai.
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small # Embedding model when EMBEDDING_PROVIDER=openai
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
@@ -89,7 +111,9 @@
# Without a secret, REST endpoints are open on loopback. Set this when
# you expose the daemon beyond loopback or run behind a reverse proxy.
-# AGENTMEMORY_SECRET=your-secret-here
+# AGENTMEMORY_SECRET=your-secret # generated into ~/.agentmemory/secret on first start when unset
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# -----------------------------------------------------------------------------
# 4. Search tuning
@@ -98,6 +122,7 @@
# BM25_WEIGHT=0.4 # Hybrid search weight for BM25 leg
# VECTOR_WEIGHT=0.6 # Hybrid search weight for vector leg
# AGENTMEMORY_GRAPH_WEIGHT=0.2 # Graph traversal bonus on smart-search ranking
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false # Skip the one-time background trim of oversized graph provenance at startup
# TOKEN_BUDGET=2000 # Max tokens injected via mem::context per session
# MAX_OBS_PER_SESSION=500 # Per-session observation cap before consolidation kicks in
# SUMMARIZE_CHUNK_SIZE=400 # When mem::summarize sees a session larger than this, it chunks observations and map-reduces (chunk-summarize → reduce-merge) to stay within the LLM's context window. Default 400 ≈ 50k tokens per chunk at ~110 tok/obs. Native sessions are capped by MAX_OBS_PER_SESSION; chunking primarily matters for bulk-imported jsonl sessions, which bypass that cap.
@@ -107,8 +132,8 @@
# 5. Behaviour flags
# -----------------------------------------------------------------------------
-# AGENTMEMORY_AUTO_COMPRESS=true # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
-# AGENTMEMORY_INJECT_CONTEXT=true # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
+# AGENTMEMORY_AUTO_COMPRESS=true # Run LLM-written compression on every observation batch. Requires BOTH this flag and a configured provider; a provider alone leaves synthetic compression active.
+# AGENTMEMORY_INJECT_CONTEXT=true # Inject recalled memories back into agent prompts. Default off — hooks capture observations but do not modify conversation.
# CONSOLIDATION_ENABLED=true # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost.
# CONSOLIDATION_DECAY_DAYS=30 # Age (days) after which non-reinforced memories decay during consolidation
# GRAPH_EXTRACTION_ENABLED=true # Extract concept-graph edges on remember; powers the graph-traversal recall path
@@ -121,8 +146,16 @@
# AGENTMEMORY_LLM_NOTHINK=1
# AGENTMEMORY_REFLECT=true # Periodically auto-synthesize lessons from memories
-# AGENTMEMORY_DROP_STALE_INDEX=true # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
+# AGENTMEMORY_DROP_STALE_INDEX=true # Drop on-disk BM25 / vector index on startup if dim guard fires. Recovery toggle for stuck-state debugging.
# AGENTMEMORY_IMAGE_EMBEDDINGS=true # Enable image embeddings when an image provider is present (experimental).
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=6 # Drop whole audit-log month scopes older than N months on a daily sweep. Default 0 = keep audit history forever.
+# AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES=33554432 # Largest legacy mem:audit scope file the one-time migration will read locally. Default 32 MiB; bigger or unreadable stores are left frozen.
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # Set to 1 or true to audit index migration and cleanup writes (debugging only)
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves; shutdown and deletes still save immediately.
+# AGENTMEMORY_VECTOR_BUCKET_SIZE=500 # Vectors held per storage bucket before a new bucket opens; a save only rewrites buckets it changed.
+# AGENTMEMORY_VECTOR_BACKFILL_MAX=500 # Batch size for re-embedding vectors missing since the last save (continues across restarts); also caps the whole-store opt-in per boot.
+# AGENTMEMORY_VECTOR_BACKFILL=all # Required to backfill an entire store's vectors at once (no prior vector save, or a stale legacy manifest); unset means that case waits for an explicit opt-in.
+# AGENTMEMORY_VIEWER_STREAM_MAX=500 # Max items kept in the persisted "viewer" live-stream group; older entries are pruned in batches. Floored at 200 (the viewer's reload window); negative values fall back to the default
# -----------------------------------------------------------------------------
# 6. CLI / runtime knobs
@@ -135,8 +168,20 @@
# AGENTMEMORY_PROBE_TIMEOUT_MS=2000 # MCP shim livez probe timeout
# AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim
# AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status`
+# Persistent iii state; same override as `--data-dir`, used by native and
+# Docker starts. Explicit flag/env wins. Otherwise instance 0 reuses an
+# existing ./data/state_store.db or ./data/iii-config.yaml before defaults: macOS
+# ~/Library/Application Support/agentmemory; Linux $XDG_DATA_HOME/agentmemory
+# or ~/.local/share/agentmemory; Windows %APPDATA%\agentmemory.
+# AGENTMEMORY_DATA_DIR=/absolute/path
+# AGENTMEMORY_III_CONFIG=/path/to/iii-config.yaml # Engine config the CLI starts from; the bundled default binds 127.0.0.1
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes state to disk; a crash loses at most this much
+# AGENTMEMORY_USE_DOCKER=1 # Prefer bundled Docker even when a compatible native iii binary exists
# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Default destination for `agentmemory export`
+# AGENTMEMORY_STATE_BACKEND=redis # file (default) | redis — storage adapter for iii-state and iii-stream, see README "Storage backend"
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required when AGENTMEMORY_STATE_BACKEND=redis
+
# STANDALONE_MCP=1 # MCP shim only — bypass the worker and run @agentmemory/mcp in-process
# STANDALONE_PERSIST_PATH=~/.agentmemory/local.db # Path used by the standalone MCP shim's local fallback store
@@ -154,23 +199,39 @@
# 7. Ports
# -----------------------------------------------------------------------------
-# III_REST_PORT=3111 # REST API port (also affects viewer at +2)
-# III_STREAMS_PORT=3112 # Streams API port
-# III_ENGINE_URL=ws://localhost:49134 # iii-engine WebSocket URL (used by the worker)
+# III_REST_PORT=3111 # REST API + MCP HTTP anchor
+# III_STREAM_PORT=3112 # Preferred streams override; defaults to REST + 1
+# III_STREAMS_PORT=3112 # Legacy alias for III_STREAM_PORT
+# III_VIEWER_PORT=3113 # Viewer bind port; defaults to REST + 2
+# III_ENGINE_PORT=49134 # Engine bind port; defaults to REST + 46023
+# III_ENGINE_URL=ws://localhost:49134 # Explicit/remote worker WebSocket URL; takes precedence over derived engine port
+# Derivation applies only while the corresponding explicit port/URL is unset.
+# `--instance 1` selects 3211/3212/3213/49234 and an instance-1 data subdir.
# -----------------------------------------------------------------------------
# 8. iii engine pin
# -----------------------------------------------------------------------------
#
-# agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
-# new sandbox-everything-via-`iii worker add` model that agentmemory
-# hasn't been refactored for yet. Override with AGENTMEMORY_III_VERSION
-# only after migrating to the sandbox model manually.
+# agentmemory pins iii-engine to the same release as its iii-sdk dependency
+# (v0.22.1). The worker speaks the wire protocol of that engine, so the two move
+# together in agentmemory releases. Override with AGENTMEMORY_III_VERSION only
+# if you run your own engine and know it matches.
+
+# AGENTMEMORY_III_VERSION=0.22.1
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# -----------------------------------------------------------------------------
+# 9. Session sweep
+# -----------------------------------------------------------------------------
-# AGENTMEMORY_III_VERSION=0.11.2
+# Hourly backstop that marks stale active sessions as abandoned.
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=false # Disable the hourly sweep
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24 # Inactivity hours before a session is abandoned
# -----------------------------------------------------------------------------
-# 9. Claude Code bridge (opt-in)
+# 10. Claude Code bridge (opt-in)
# -----------------------------------------------------------------------------
# CLAUDE_MEMORY_BRIDGE=true # Mirror compressed memories into Claude Code's CLAUDE.md
@@ -178,7 +239,7 @@
# CLAUDE_MEMORY_LINE_BUDGET=200 # Lines of memory CLAUDE.md should hold
# -----------------------------------------------------------------------------
-# 10. Obsidian export (opt-in)
+# 11. Obsidian export (opt-in)
# -----------------------------------------------------------------------------
# OBSIDIAN_AUTO_EXPORT=true # Auto-export memories to an Obsidian vault on every consolidation
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index e0a74e99e9..067c45313d 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -14,6 +14,8 @@ updates:
commit-message:
prefix: deps
include: scope
+ ignore:
+ - dependency-name: iii-sdk
groups:
minor-and-patch:
update-types:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cbedfaa6df..219caac397 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -38,6 +38,9 @@ concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+permissions:
+ contents: read
+
jobs:
test:
runs-on: ${{ matrix.os }}
diff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.yml
new file mode 100644
index 0000000000..d7b150883e
--- /dev/null
+++ b/.github/workflows/release-gate.yml
@@ -0,0 +1,53 @@
+name: Release gate
+
+on:
+ push:
+ branches: [main]
+ paths-ignore:
+ - "website/**"
+ - "docs/**"
+ - "assets/**"
+ - "**/*.md"
+ - "**/*.mdx"
+ pull_request:
+ branches: [main]
+ paths-ignore:
+ - "website/**"
+ - "docs/**"
+ - "assets/**"
+ - "**/*.md"
+ - "**/*.mdx"
+ workflow_dispatch:
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+ contents: read
+
+jobs:
+ packed-artifact:
+ name: packed artifact (${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 30
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, macos-latest]
+ steps:
+ - uses: actions/checkout@v6
+ with:
+ persist-credentials: false
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 22
+ - run: npm install --legacy-peer-deps --no-audit --no-fund
+ - run: npm run release:gate -- --out "${{ runner.temp }}/release-gate"
+ - if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: release-gate-${{ matrix.os }}
+ path: ${{ runner.temp }}/release-gate
+ if-no-files-found: ignore
+ retention-days: 14
diff --git a/.gitignore b/.gitignore
index 0a58383b8d..26efdec757 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,3 +31,5 @@ integrations/hermes/__pycache__/
eval/reports/
# LongMemEval download is 278MB; fetched on demand
eval/data/longmemeval/
+
+benchmark/results/capture-costs-*
diff --git a/AGENTS.md b/AGENTS.md
index dc08f431ca..f223e644f3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,36 +4,26 @@
agentmemory is a persistent memory system for AI coding agents, built on iii-engine's three primitives (Worker/Function/Trigger). Everything goes through `registerFunction`/`registerTrigger`/`sdk.trigger()` — never bypass iii-engine with standalone SQLite or in-process alternatives.
-- **Engine**: iii-sdk (WebSocket to iii-engine on port 49134)
+- **Engine**: iii-sdk 0.22.1 with @iii-dev/helpers 0.22.1 (WebSocket to iii-engine 0.22.1 on port 49134; the client type is `IIIClient`, HTTP requests are `HttpRequest` from `@iii-dev/helpers/http`)
- **State**: File-based SQLite via iii-engine's StateModule (`./data/state_store.db`)
- **Build**: TypeScript → ESM via tsdown, output to `dist/`
- **Test**: vitest (`npm test` excludes integration tests)
## Consistency Rules
-**When adding or removing MCP tools, you MUST update ALL of the following:**
+**Before every commit, run `npm run docs:sync` and commit what it changes.** It computes MCP tool counts (all, core, local fallback), REST endpoints, skills, hooks, tests, iii functions, source files, lines of code and KV scopes from the source, and rewrites them in README.md, the translated READMEs, AGENTS.md, INSTALL_FOR_AGENTS.md, plugin manifests, integration READMEs, the stat badges and the `src/index.ts` banner. The last synced values live in `scripts/docs-sync.state.json`; commit that file with the rest. `npm run docs:check` exits non-zero when anything is out of date. When the sync prints `check left in `, open that line: either fix it by hand or add its noun to the fact in `scripts/docs-sync.ts` so the next sync catches it. Never hand-edit these numbers or versions in the docs; change the source and sync.
+
+**When adding or removing MCP tools, update:**
1. `src/mcp/tools-registry.ts` — tool definition + `getAllTools()` array
2. `src/mcp/server.ts` — handler case in the `mcp::tools::call` switch
3. `src/triggers/api.ts` — REST endpoint registration
-4. `src/index.ts` — function registration + endpoint count in the log line
+4. `src/index.ts` — function registration
5. `test/mcp-standalone.test.ts` — tool count assertion
-6. `README.md` — tool counts (search for "MCP tools")
-7. `plugin/.claude-plugin/plugin.json` — tool count in description
-8. `plugin/plugin.json` and `plugin/.mcp.copilot.json` (when present) — tool count or MCP exposure
-**When adding REST endpoints, you MUST update:**
+**When adding REST endpoints, update:**
1. `src/triggers/api.ts` — endpoint registration
-2. `src/index.ts` — endpoint count in the log line
-3. `README.md` — endpoint count (search for "REST endpoints" and "endpoints on port")
-
-**When bumping version, you MUST update ALL of the following:**
-1. `package.json` — version field
-2. `src/version.ts` — VERSION constant and type union
-3. `src/types.ts` — ExportData version union
-4. `src/functions/export-import.ts` — supportedVersions set
-5. `test/export-import.test.ts` — version assertion
-6. `plugin/.claude-plugin/plugin.json` — version field
-7. `plugin/plugin.json` (when present) — version field
+
+**When bumping version, change only `package.json`.** `npm run docs:sync` carries the new version into `src/version.ts`, the `src/types.ts` ExportData union, the `supportedVersions` set in `src/functions/export-import.ts`, every plugin and package manifest that shared the old version, the deploy templates, the AGENTS.md stats heading, and CHANGELOG.md (the Unreleased section becomes the new version with today's date, plus its compare link).
**When adding new KV scopes:**
1. `src/state/schema.ts` — add to the KV object
@@ -59,7 +49,9 @@ sdk.registerFunction(
### REST Endpoint Registration
```typescript
-sdk.registerFunction("api::your-endpoint", async (req: ApiRequest) => {
+import type { HttpRequest } from "@iii-dev/helpers/http";
+
+sdk.registerFunction("api::your-endpoint", async (req: HttpRequest) => {
const denied = checkAuth(req, secret);
if (denied) return denied;
const body = req.body as Record;
@@ -94,7 +86,7 @@ case "memory_your_tool": {
Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). They read JSON from stdin, make HTTP calls to the REST API, and exit. There are two patterns depending on whether Claude Code consumes the script's stdout:
- **Context-injecting hooks** (`pre-tool-use`, `pre-compact`, `session-start`) write recalled context to stdout for Claude Code to inject. These MUST use `try/catch` with `await fetch(..., { signal: AbortSignal.timeout(N) })` — the script has to wait for the response before exiting, and the timeout is the only bound on hang time.
-- **Telemetry-only hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `stop`, `session-end`, `subagent-start`, `subagent-stop`, `task-completed`) write nothing to stdout. These MUST use fire-and-forget `fetch(..., { signal: AbortSignal.timeout(N) }).catch(() => {})` paired with `setTimeout(() => process.exit(0), 500).unref()`. The unawaited fetch dispatches the request; the unref'd `setTimeout` force-exits the process after the request has been flushed to the local daemon's socket buffer (~500ms is enough for single-request hooks; use 1500ms for multi-request hooks like `stop` and `session-end` so all fetches have time to start, especially when `AGENTMEMORY_URL` points to a remote daemon). Without the `setTimeout` Node keeps the event loop alive waiting for any in-flight fetch to settle, which means the hook still blocks Claude Code's next-prompt boundary for up to the AbortSignal duration — exactly the bug fire-and-forget is meant to fix.
+- **Capture hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `subagent-start`, `subagent-stop`, `task-completed`) write nothing to stdout. Use the shared `captureObservation()` path with a 3000ms request timeout and a 3500ms exit cap so failed deliveries reach the local spool before exit. The drain child has its own bounded retry deadline. `session-end` awaits transcript prompt capture before dispatching session-end and optional bridge requests, then exits within 1500ms of dispatch. `stop` only dispatches session-end and retains its 500ms exit cap. Keep these lifecycle-only requests bounded with `AbortSignal.timeout()` and an unref'd exit timer.
## Coding Standards
@@ -109,16 +101,17 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
## Testing
-- All tests must pass before PR: `npm test` (1,596+ tests)
+- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (2,600+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.
+- Before any npm publish: `npm run release:gate` must pass. It installs the packed tarballs into a clean home and runs capture, recovery, restart, export/import, MCP and status checks against the installed CLI (see CONTRIBUTING.md, Release process)
- Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list`
- Test files go in `test/` with `.test.ts` extension
- Follow existing patterns in `test/crystallize.test.ts` for function tests
-## Current Stats (v0.9.29)
+## Current Stats (v0.9.30-codex.1)
- 54 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
-- 130 REST endpoints
+- 138 REST endpoints
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 17 skills
-- 260+ iii functions
-- 1,596+ tests
+- 312+ iii functions
+- 2,600+ tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85df068d7a..db1f0ab5fd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,132 @@ All notable changes to agentmemory will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+
+## [0.9.30-codex.1] — 2026-10-10
+## [0.9.30] - 2026-10-06
+
+Scale, durability and safety release. The iii engine moves from 0.11.2 to 0.22.1. The stores that grew without bound on shared daemons (graph provenance, the audit log, the vector index, the viewer stream backlog) are bounded and heal themselves at boot. Capture is durable end to end: the server accepts each observation into a persistent inbox with a restart-safe event id, and hooks keep an offline spool while the server is down. Vectors survive a force-kill through a pending log. The REST API requires auth by default. Redis becomes an opt-in state backend, and the viewer is rebuilt around one snapshot plus live stream events with a Health page backed by `GET /agentmemory/status`. Every publish now goes through a release gate that installs the packed tarballs and runs capture and recovery against them. Contributions from david-waltermire, a652, cbsincool, dmazhukov and Tyxiel, with earlier work by DaveCole, Srinath279, joyjit and cristianbdev carried into merged PRs.
+
+### Breaking changes
+
+- **Auth is on by default** (#1462). When `AGENTMEMORY_SECRET` is not set, the server generates a secret into `~/.agentmemory/secret` (mode 0600) on first start. The CLI, viewer, hooks, MCP server and shim, `agentmemory connect` configs and the bundled integrations read it for loopback URLs, so they keep working with no change. Hand-written requests to `:3111` now need `Authorization: Bearer $(cat ~/.agentmemory/secret)`. An explicit `AGENTMEMORY_SECRET` still wins, and mesh sync still requires an explicit one.
+- **File import and export paths are confined** (#1462). `/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`, the Obsidian export and `/migrate` resolve symlinks and only accept paths inside the data dir, `~/.agentmemory` or a directory listed in `AGENTMEMORY_IMPORT_ROOT`. `/replay/import-jsonl` also keeps its default `~/.claude/projects`.
+- **Browser writes need JSON and an allowed origin** (#1462). `POST`, `PUT`, `PATCH` and `DELETE` requests with a body must send `Content-Type: application/json`, and a present `Origin` header must be a loopback origin for the configured ports, the viewer's own origin, or listed in `VIEWER_ALLOWED_ORIGINS`. Clients that send no `Origin` (CLI, hooks, MCP, curl) are unaffected.
+- **`AGENTMEMORY_VECTOR_BACKFILL_MAX` is now a batch size** (#1467). Recovery re-embeds missing vectors in batches of this size until the backlog is empty, across restarts, instead of stopping at the cap once per boot.
+- **iii engine 0.22.1** (#1396, #1397). Keep the `iii-` prefixed builtin worker names (`iii-http`, `iii-state`, `iii-queue`, `iii-pubsub`, `iii-cron`) in any custom config: on 0.22.1 the bare names resolve to standalone registry workers.
+- **Hooks skip agentmemory's own tools** (#1452). PostToolUse no longer captures `memory_*` MCP calls or `toolsearch`, `listmcpresources` and `fetchmcpresource`.
+- **Changed response shapes.**
+ - `mem::forget`, `mem::governance-delete` and `mem::governance-bulk` count only records that were really deleted. Absent ids come back in `notFound` and failed deletes in `failed` and `failures`, with `success: false` when anything failed. `governance-bulk` refuses an empty filter and unsupported keys on both the dry run and the live call (#1449).
+ - `GET /agentmemory/audit` and the `memory_audit` MCP tool return `{ entries, legacyFrozen, legacyFrozenBytes }`; the MCP tool used to return a bare list (#1419).
+ - `GET /agentmemory/memories` returns newest first and adds `nextCursor` (plus `search` and `facets` when requested) (#1433).
+ - `GET /agentmemory/export` returns 413 with the refusal body (`oversized`, `bytes`, `limitBytes`, `stoppedAt`) instead of 200 when the export is too large (#1422, #1449).
+ - `POST /agentmemory/session/end` for an unknown, malformed or already completed session returns 200 with `ended: false` and writes nothing (#1252).
+ - `memory_patterns` / `mem::patterns` reads the 50 most recent sessions by default (`limit`, max 500) and stops after 5,000 observations (#1424).
+ - Consolidation decay applies at most once per decay period, and `results.decay` reports `{ scanned, written }` per tier (#1417).
+
+### Upgrade notes
+
+- Scripts or tools that call the REST API by hand on `:3111`: add `Authorization: Bearer $(cat ~/.agentmemory/secret)`, or set your own `AGENTMEMORY_SECRET` and send that.
+- Imports or exports from folders outside `~/.agentmemory` and the data dir: list those folders in `AGENTMEMORY_IMPORT_ROOT` (separate several with `:`, or `;` on Windows).
+- A web page on another origin that writes through the viewer: add its origin to `VIEWER_ALLOWED_ORIGINS`.
+- Nothing else is required. Stores load unchanged, and the one-time migrations below run by themselves.
+
+### What happens on the first start
+
+- **Graph provenance is compacted once in the background.** Every node, edge, superseded edge and the cached snapshot is trimmed to 32 observation ids in slices, without blocking boot, search or the viewer. Progress is saved and resumes after a restart. `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` skips it; `POST /agentmemory/graph/compact` runs it by hand (#1455).
+- **The audit log moves to monthly scopes** (`mem:audit:YYYY-MM`) with a one-time background migration. A legacy scope larger than `AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES` (default 32 MiB) or unreadable is left frozen and reported as `legacyFrozen` (#1419).
+- **The vector index migrates to buckets** (`AGENTMEMORY_VECTOR_BUCKET_SIZE`, default 500) by copying vectors, with no embedding calls. BM25 is no longer persisted and is rebuilt at every boot (#1416).
+- **State is saved every 2 s** instead of 5 s, and `agentmemory stop` waits for the engine flush, so it takes a few seconds longer (#1457, #1449).
+- **Stale sessions are marked abandoned** after `AGENTMEMORY_SESSION_SWEEP_STALE_HOURS` (default 24) by an hourly sweep that deletes nothing (#1453).
+- **Viewer stream groups.** Observations stop writing to per-session `mem-live` groups and the shared `viewer` group is capped at `AGENTMEMORY_VIEWER_STREAM_MAX` (default 500). Existing per-session groups are left in place (#1420).
+
+### Added
+
+- **Durable capture** (#1460). Hooks send a stable event id with every observation (the host tool use id when present, otherwise a hash of the event). The server writes each event to a capture inbox before storing it, keeps completed ids for `AGENTMEMORY_CAPTURE_DEDUP_HOURS`, and answers a replay with the existing observation. Failed writes retry with backoff, also after a restart, and end as dead letters shown on `/status`, the viewer Health page and `GET /agentmemory/capture`, with `POST /agentmemory/capture/retry` to retry them.
+- **Offline hook spool** (#1460, #1468). When the server is down, times out or returns a 5xx, hooks keep a copy of the observation in a bounded private spool under the data dir until the engine has saved it. The spool drains at boot and from the next hook that reaches the server. New: `agentmemory capture [--drain]` and `POST /agentmemory/capture/drain`.
+- **Vector pending log** (#1467). Every vector added to or removed from the live index is also written to a small pending log. Boot replays it after the snapshot with 0 embedding calls, and whatever is still missing is re-embedded as a durable backlog that resumes after a restart instead of stopping at a 500 cap. `/status` and the viewer show the log size and a paused backfill.
+- **Release gate** (#1463). `npm run release:gate` packs `@agentmemory/agentmemory` and `@agentmemory/mcp`, installs both tarballs into a clean home and runs named scenarios against the installed CLI: capture through the bundled hooks, offline capture recovered from the spool, replay dedup after a force kill, dead letters that survive a restart, vectors surviving a crash, stop and start, export and import, the MCP shim, the viewer and `/status`. A Release gate workflow runs it on Ubuntu and macOS.
+- **Capture cost bench** (#1464). `npm run bench:capture-costs` measures disk bytes per state scope, engine and worker memory and CPU, hook latency, provider requests, agent-visible context bytes and force-kill recovery, with separate capture and recovery budgets in `benchmark/capture-costs-budgets.json` and a figure in `docs/benchmarks/capture-costs.svg`. Optional Ollama, Redis and crash-offline variants.
+- **Codex plugin package** (#1459). The Codex plugin bundles a small stdio bridge that forwards tools, resources and prompts to the configured agentmemory daemon and reports connection errors instead of falling back to a separate store. Authenticated non-loopback connections require HTTPS. `npm run plugin:pack:codex` builds a local package with the six Codex hooks and a review package without lifecycle hooks, and `npm run plugin:verify:published` refuses a release whose runtime, MCP shim and iii versions do not match.
+- **Rebuilt viewer that streams every page** (#1433, #1407). One snapshot on connect (`GET /agentmemory/viewer/snapshot`, `GET /agentmemory/counts`), then live `.created/updated/deleted` events with no polling. 12 tabs in four groups with live counts, deep links, keyboard shortcuts and a mobile menu, a memories detail panel with version chain, diff and provenance, sessions with an inline timeline, and a searchable graph. Cursor pagination and facets on memories, sessions and observations, `GET /graph/node` and `GET /observations/locate` back it.
+- **`GET /agentmemory/status` and a Health tab in the viewer** (#1408). One report of what is wrong and how to fix it: providers and circuit breaker, failing functions, observations missing from the search index, index save state per leg (#1415), the state backend, graph compaction progress, capture inbox and spool, ports, the pinned engine version and every feature flag. HTML for browsers, JSON otherwise.
+- **`GET /agentmemory/consolidation/status`** and a "Memory layers" panel (#1407).
+- **Opt-in Redis backend for state and streams**: `AGENTMEMORY_STATE_BACKEND=file|redis` and `AGENTMEMORY_REDIS_URL` (#1425). Use one Redis server per instance, and move data with `agentmemory export` and `import` when switching.
+- **`POST /agentmemory/graph/compact`** trims oversized node, edge, edge history and snapshot provenance in slices (#1454, carries #1445 by david-waltermire), and **`AGENTMEMORY_GRAPH_COMPACT_ON_BOOT`** runs it once after upgrade (#1455).
+- **Stale session sweep**: `AGENTMEMORY_SESSION_SWEEP_ENABLED` and `AGENTMEMORY_SESSION_SWEEP_STALE_HOURS` (#1453, carries #1411 by cristianbdev).
+- **Capture filters for hooks**: `AGENTMEMORY_CAPTURE_ALLOW`, `AGENTMEMORY_CAPTURE_DENY`, `AGENTMEMORY_CAPTURE_OUTPUT_MAX` (default 8000) and `AGENTMEMORY_PRE_COMPACT_BUDGET` (default 1500, 0 disables) (#1452, carries #994 by joyjit).
+- **`AGENTMEMORY_AUDIT_INDEX_PERSIST`** (off by default) re-enables index persistence audit rows for debugging (#1182 by dmazhukov).
+- **`AGENTMEMORY_AUDIT_RETENTION_MONTHS`** and **`AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES`** for the monthly audit log (#1419).
+- **`AGENTMEMORY_STATE_SAVE_INTERVAL_MS`**, **`AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`**, **`AGENTMEMORY_VECTOR_BUCKET_SIZE`**, **`AGENTMEMORY_VECTOR_BACKFILL`** and **`AGENTMEMORY_VIEWER_STREAM_MAX`** (#1457, #1415, #1416, #1420).
+- **`agentmemory console`** launches the iii web console through the pinned engine; the "install iii console?" prompt and the `skipConsoleInstall` preference are gone (#1397).
+- **Multi-instance installs**: `--instance N` gets its own port quartet, data directory and lifecycle state, and `--port` derives the other ports (#892).
+- Procedures are extracted from finished sessions when consolidation is on and an LLM provider is configured (#1407).
+- `memory_patterns` takes an optional `limit` (#1424). `POST /lessons` accepts `sourceIds`, and `mem::evolve` returns 409, 400 and 404 errors (#1433).
+- **OpenCode 2 support in the OpenCode plugin** (#1476, building on #1451 by Tyxiel). One `agentmemory-capture.ts` serves both plugin APIs: OpenCode 2 loads its `setup()` entry and OpenCode 1.x keeps the existing hooks. On OpenCode 2 it captures prompts, tool calls with their output, the assistant's answer, step and compaction events, injects memory on every model call, and requests a summary when a run finishes. Checked in live sessions on OpenCode 2.0.24, 1.18.34 and 1.17.10.
+
+### Fixed
+
+- **Repeated identical prompts are kept** (#1468). Hooks whose host sends no event id or time now include the hook timestamp in the id, so typing the same prompt twice stores it twice; retries still reuse the stored id.
+- **Cursor prompts are stored once** (#1470). A per-session prompt ledger matches the session-end transcript back-fill against live captures, so a back-filled prompt is answered as a duplicate instead of stored a second time. Live prompts are never deduped by content.
+- **Concurrent spool writers cannot overwrite each other** (#1468), and printed recovery commands (dead letter retry, spool drain, graph compact, the status page example) send the bearer token.
+- **Graph provenance is bounded.** Each node and edge records only its own observation ids, capped at 32, which stops huge graph rows from crash-looping the worker during search (#1454, carries #1445 by david-waltermire).
+- **Search skips graph retrieval when `AGENTMEMORY_GRAPH_WEIGHT=0`** (#1446 by david-waltermire).
+- **A failed graph snapshot read no longer zeroes the snapshot**; the delta is aborted instead (#1384 by cbsincool).
+- **The graph snapshot total can no longer be lower than the nodes it returns** (#1385 by cbsincool).
+- **Ending an unknown session no longer creates a partial row** that hung the sessions listing (#1252 by a652).
+- **Memories and vectors written just before `agentmemory stop` survive the restart** (#1449).
+- **Forget and governance deletes count and audit only real deletions** (#1449).
+- **Export refuses an oversized payload before assembling it** and the REST endpoint returns 413; the MCP shim surfaces the refusal (#1449, #1422).
+- **Session and graph read-modify-write paths take locks**, closing lost updates when several agents share one daemon (#1421).
+- **Hooks no longer exit before their observe request is sent** on a slow start (#1456).
+- **A fresh vector index is checkpointed within 5 s** and observations keep a bounded, sanitized copy of their source for replay and export (#1448).
+- **Runtime config is re-seeded on every start**, so `--port`, `--instance` and data-dir changes take effect after the first run (#1396, #1397).
+- **The "Memory elevated" alert no longer fires on a healthy process** (#1409).
+- **The viewer stops blinking and keeps data on a failed refresh**, and dashboard numbers match the API (#1407).
+- Consolidation and provider detection use the same check, and functions that need an LLM show as off instead of failed (#1433).
+- Worker shutdown no longer hangs when the engine is already gone (#1396).
+- Fresh installs are portable and persistent, and native and Docker removal stops the worker before the engine (#892).
+- **`OPENAI_EMBEDDING_API_KEY` is honored** when the embedding provider is auto-detected or chosen, and wins over `OPENAI_API_KEY`; blank keys count as unset (#1472).
+- **SessionStart context reaches hosts that expect structured hook output.** When the hook input names the `SessionStart` event, context is returned as `hookSpecificOutput.additionalContext`; hosts that send no event name still get plain text (#1472).
+
+### Security
+
+- **Request hardening** (#1462, supersedes #878 by DaveCole and #922 by Srinath279). Auth on by default, origin and content type checks on writes, and confined file paths, as described under Breaking changes. Confined files are replaced only after the new content is fully written, and a destination that is a symlink is refused.
+- **Scrubbing on every write** (#1462). Write functions run the secret scrubber on their input, and compression, summary, crystal, graph, replay, team share, session title, commit message and image description text is scrubbed before storage. New patterns cover PEM private key blocks and credentials in URLs. Stored text is escaped before it goes into the injected context block.
+- **Clients resolve the API secret the same way as the server** (#1462): environment first, then `~/.agentmemory/.env`, then the generated secret file, and the stored secret is only sent to loopback URLs.
+- **Supply chain** (#1461). The automatic engine installer verifies the downloaded archive against a SHA-256 pinned in the CLI for each platform before extracting it, and refuses an unpinned version or platform. `npm run engine:hashes` refreshes the pins. Installer paths reach the shell as arguments, so a home directory containing shell syntax is never evaluated. The CI workflow runs with read-only permissions, and the deploy Dockerfiles check that the copied iii binary matches `III_VERSION`.
+- `GET /agentmemory/status` serves HTML with no scripts under a strict CSP and the same bearer auth as the rest of the API (#1408).
+- The Redis URL stays out of files and output (#1425).
+- `mem::governance-bulk` cannot widen a dry run to the whole store (#1449).
+- The pinned engine starts with `--no-update-check` and iii's anonymous usage telemetry off (#1396).
+- A profile read no longer writes a `share` audit entry (#1433).
+
+### Performance
+
+- **Vectors are stored per key in fill-and-roll buckets**, so a save rewrites a few buckets instead of the whole index and the store no longer hits V8's string limit at about 49,000 vectors (#1416).
+- **Index saves are throttled and each leg reports its own state**, so one failing leg no longer skips the others (#1415).
+- **The audit log lives in monthly scopes** read newest first (#1419).
+- **Session start context and observation lookups use small secondary indexes** instead of listing every session (#1418).
+- **`mem::remember` calls the embedding provider outside the global save lock** (#1423).
+- **`mem::patterns` is bounded** to recent sessions and an observation budget (#1424).
+- **Consolidation decay writes only rows that changed** (#1417).
+- **The viewer stream backlog is bounded** (#1420).
+- **Faster state saves**, `MALLOC_ARENA_MAX=2` for the engine on Linux, and a higher open-file limit in Docker and deploy entrypoints (#1457).
+
+### Docs and internal
+
+- **agent-memory.dev is rebuilt** around use cases and sourced proof: agent sessions showing what memory changes, a view of the 1,571 tokens the next session gets out of a month of history, live GitHub and all-time npm numbers, and new /benchmarks, /security, /privacy, /changelog and /vs comparison pages. It ships robots.txt, a sitemap, llms.txt and llms-full.txt, and link previews now point at agent-memory.dev instead of a parked domain.
+- `npm run docs:sync` and `npm run docs:check` keep the documented counts and versions in README, the translated READMEs and AGENTS.md in step with the code.
+- The README documents auth by default, request rules, file path roots, the capture inbox and spool, and the pending vector log (#1460, #1462, #1467).
+- The README, the config skill reference and `agentmemory --help` document `AGENTMEMORY_III_CONFIG` and the engine bind address, including the Docker engine config (#1472).
+- Code and tests no longer cite issue or PR numbers (#1469).
+- The `index_persist` audit gating suite is restored against bucketed persistence and monthly audit scopes (#1477), originally written by dmazhukov in #1182.
+- Unit tests grew from about 1,700 to more than 2,400.
+- Dependabot no longer proposes `iii-sdk` bumps; the engine pin and the SDK move together by hand (#1396). `dotenv` 18.0.3 (#1430) and `@types/node` 26.6.2 (#1401, #1400).
+- The deploy Dockerfiles refuse to build when `III_VERSION` and `III_SDK_VERSION` differ (#1396).
+- Thanks to MarvinFS (discussion #1358), inix-x, sbynode-ux, ErikBPF and cmondragon023, whose measurements and earlier PRs shaped the scaling work.
+
## [0.9.29] — 2026-08-16
Release wave in two parts. Recall quality: hybrid ranking reaches the primary recall path, lessons get a real index, every record learns where it came from, the knowledge graph populates keyless, and agent scoping threads through all save paths — plus connector parity for pi and Codex, a new DeepSeek Harness connector, current provider model defaults, and a viewer clarity pass. Foundation: the `.env` file now applies everywhere, imports become searchable, consolidation runs on session stop, twelve MCP-only agents get activated on connect, and every capture surface agrees on what "project" means. No breaking changes; read the upgrade notes for behavior changes you will notice.
@@ -136,6 +262,8 @@ Wave release closing several breaking regressions reported against v0.9.26, plus
- `/agentmemory:forget` skill still calls `memory_governance_delete` which only touches `KV.memories` and never observations ([#833](https://github.com/rohitg00/agentmemory/issues/833)). Skill rewrite + new `memory_forget` MCP tool tracked separately.
- `crypto.randomUUID()` global-only on Node <19 ([#715](https://github.com/rohitg00/agentmemory/issues/715)). Drop-in import fix tracked.
+[0.9.30-codex.1]: https://github.com/davidrobertson/agentmemory/compare/v0.9.30...v0.9.30-codex.1
+[0.9.30]: https://github.com/rohitg00/agentmemory/compare/v0.9.29...v0.9.30
[0.9.29]: https://github.com/rohitg00/agentmemory/compare/v0.9.28...v0.9.29
[0.9.28]: https://github.com/rohitg00/agentmemory/compare/v0.9.27...v0.9.28
[0.9.27]: https://github.com/rohitg00/agentmemory/compare/v0.9.26...v0.9.27
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d865ecb9e2..6e58c49d0c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -93,19 +93,18 @@ PRs with commits lacking sign-off will not merge.
## Release process
-Maintainers cut releases. Every bump touches these files in lockstep (the consistency tests fail if the trio of doc counts or any version drifts):
-
-1. `package.json`
-2. `src/version.ts`
-3. `plugin/.claude-plugin/plugin.json`
-4. `plugin/plugin.json`
-5. `plugin/.codex-plugin/plugin.json`
-6. `packages/mcp/package.json`
-7. `src/types.ts` (`ExportData.version` union)
-8. `src/functions/export-import.ts` (`supportedVersions` Set)
+Maintainers cut releases. To bump the version, change only `package.json`, then run `npm run docs:sync`. It carries the new version into `src/version.ts`, the `ExportData.version` union in `src/types.ts`, the `supportedVersions` set in `src/functions/export-import.ts`, every plugin and package manifest that shared the old version, the deploy templates, the AGENTS.md stats heading, and CHANGELOG.md (the Unreleased section becomes the new version with today's date and its compare link). Commit everything it changes, and check with `npm run docs:check`.
No lockfiles are committed. `test/export-import.test.ts` asserts against the `VERSION` constant, so it needs no per-release edit. Run `npm run skills:gen` if the endpoint or env surface changed.
+Before publishing, run the release gate on the release commit:
+
+```bash
+npm run release:gate
+```
+
+It builds, packs `@agentmemory/agentmemory` and `@agentmemory/mcp`, installs both tarballs into a fresh prefix with a clean `HOME`, starts the installed CLI on random free ports with a deterministic local embedding server (no API keys), and checks capture through the bundled hooks, offline capture and spool recovery, replay dedup after a force kill, dead letters across a restart, vector survival before the first checkpoint, `agentmemory stop` then start, export and import into a fresh home, the MCP entrypoints, and the viewer plus `/agentmemory/status`. It prints a pass or fail line per scenario and a JSON summary, writes logs and `summary.json` to the output directory it prints, and stops only the processes it started. To gate the exact file you will publish, pass it in: `npm pack` then `npm run release:gate -- --tarball agentmemory-agentmemory-.tgz`, and publish that tarball. Do not publish when a scenario fails. The `Release gate` workflow runs the same script on Ubuntu and macOS for pull requests and pushes to main.
+
Then: CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance (`@agentmemory/fs-watcher` versions independently from `integrations/filesystem-watcher/package.json`).
## Security issues
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index 18c78d3bf8..6bb1d1119b 100644
--- a/INSTALL_FOR_AGENTS.md
+++ b/INSTALL_FOR_AGENTS.md
@@ -4,83 +4,116 @@ You are a coding agent. Follow this runbook top to bottom to install agentmemory
## What you are installing
-agentmemory is a local memory server for coding agents. It runs on your machine, exposes a REST API on port 3111 and an MCP server, and stores memories on disk under `~/.agentmemory`. It is built on the iii engine, which agentmemory downloads and manages for you as a pinned binary under `~/.agentmemory/bin`. You do not install iii separately.
+agentmemory is a local memory server for coding agents. It exposes a REST API and MCP HTTP routes on port 3111, streams on 3112, a viewer on 3113, and connects its worker to iii-engine on 49134. It is built on the iii engine, which agentmemory manages as a pinned v0.22.1 binary under `~/.agentmemory/bin` on macOS/Linux or `%USERPROFILE%\.agentmemory\bin` on Windows.
-Default mode needs no API key and no cloud account. Out of the box it runs hybrid retrieval (BM25 keyword search plus local on-device embeddings), so a full install proves real semantic recall with zero credentials. An LLM provider key is optional and only unlocks richer summaries and auto-injection (see "Optional: richer features").
+Configuration and the managed iii binary live under `~/.agentmemory`. Persistent iii state uses the platform data directory: `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. Override it with `--data-dir ` or `AGENTMEMORY_DATA_DIR`; use the same override on every restart. For instance 0, an existing `./data/state_store.db` or `./data/iii-config.yaml` takes precedence over the platform default, while an explicit flag or environment override still wins. Native and Docker starts use the same resolved host data directory.
+
+Default keyless mode needs no API key or cloud account and disables vector embeddings. `memory_recall` (`mem::search`) uses BM25, while `memory_smart_search` can also fuse structural graph matches when graph data exists. Semantic vector recall is an explicit opt-in: set `EMBEDDING_PROVIDER=local` for on-device `Xenova/all-MiniLM-L6-v2`, or configure a supported remote embedding provider. Local inference is free, but the first embedding request downloads the model and therefore needs network access and extra startup time. An LLM provider is separate; LLM-written observation compression requires both a provider and `AGENTMEMORY_AUTO_COMPRESS=true`.
## Prerequisites
-- Node.js >= 20 and npm. Check with `node -v`.
-- macOS or Linux for the one-command path. On Windows, use WSL2; native Windows engine setup is manual and `agentmemory connect` is not supported there.
+- Node.js >= 20 with npm and npx. Check with `node -v`, `npm -v`, and `npx -v`.
+- macOS/Linux automatic iii installation also requires `curl`, a POSIX `sh`, and `tar`. Check with `command -v curl sh tar`. Minimal images such as `node:20-slim` may not include them.
+- Windows: WSL2 follows the Linux path above. Native Windows requires a manually downloaded, pinned iii-engine v0.22.1 `iii.exe`, or Docker Desktop; the CLI does not auto-extract the Windows ZIP. Native automated `connect` supports only `copilot-cli`. Other Windows agents need manual MCP configuration; WSL `connect` applies only to agents installed in that same WSL environment.
- Ports 3111 (REST), 3112 (streams), 3113 (viewer), and 49134 (engine) free. If any are taken, stop whatever is using them before starting (see Troubleshooting).
## Running non-interactively
-Several commands prompt on a TTY (for example the first-run "install globally?" question). As an agent you usually want no prompts. Either set `CI=1` in the environment for the commands below, or rely on the fact that agentmemory skips all prompts automatically when stdin/stdout are not a TTY. Prompts are also never-nag: once answered they persist and are not asked again. Re-run onboarding any time with `agentmemory --reset`.
+Use `npx -y @agentmemory/agentmemory@latest` as the canonical command. `-y` accepts npx's package prompt and `@latest` avoids running a stale cached release. Several agentmemory onboarding choices can still prompt on a TTY; set `CI=1` for unattended runs or use non-TTY stdin. Re-run onboarding any time with `npx -y @agentmemory/agentmemory@latest --reset`.
-## 1. Install globally
+## 1. Verify the runtime prerequisites
```bash
-npm install -g @agentmemory/agentmemory
+node -v
+npm -v
+npx -v
+
+# macOS/Linux only
+command -v curl sh tar
```
-`npm install -g` already fetches the latest published release. If you hit `EACCES` on a system Node install (macOS/Linux), retry with `sudo npm install -g @agentmemory/agentmemory`.
+Expect: Node prints v20 or newer, npm succeeds, and macOS/Linux prints a path for each automatic-installer dependency.
-No-install alternative: skip this step and run the server with `npx -y @agentmemory/agentmemory@latest` everywhere this runbook says `agentmemory`. The `@latest` and `-y` flags matter because npx caches per version and a bare `npx @agentmemory/agentmemory` can serve a stale release.
+For native Windows, install the engine before continuing:
-Expect: the install completes without errors.
+```powershell
+# Download the archive that matches your CPU from the pinned release:
+# https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1
+# Extract iii.exe to $HOME\.agentmemory\bin\iii.exe, then verify the pin:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+```
-## 2. Verify the install
+Expect: exactly `0.22.1`. Do not install the latest unpinned iii release. Alternatively, use WSL2 or start Docker Desktop and choose the Docker path when agentmemory starts.
-```bash
-agentmemory --version
-```
+## 2. Start the server
-Expect: a version string is printed. If `command not found`, the global bin is not on `PATH`; use the `npx -y @agentmemory/agentmemory@latest` form instead.
+The canonical command downloads the npm package and, on macOS/Linux, auto-installs its pinned iii-engine into the private agentmemory bin directory. Run it in a dedicated terminal:
-## 3. Start the server
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
-The server listens on port 3111 and auto-starts its pinned iii engine on first run (this can take a few seconds the first time while the engine binary is fetched into `~/.agentmemory/bin`). Run it in the background or in a separate terminal so the rest of the runbook can talk to it.
+To prefer Docker even when a compatible native binary is present, set `AGENTMEMORY_USE_DOCKER=1` for the same command. To choose persistent storage, pass an absolute path and reuse it on every start:
```bash
-agentmemory &
+npx -y @agentmemory/agentmemory@latest --data-dir /absolute/path/to/agentmemory-data
```
-Or run `agentmemory` in the foreground in a dedicated terminal.
+Docker bind-mounts that same resolved host directory at `/data`. For a second isolated daemon, add `--instance 1`; it stores data and lifecycle metadata under `instance-1` and defaults to ports 3211, 3212, 3213, and 49234. Do not use `--port` alone for concurrent daemons: it changes the ports but keeps instance 0's canonical lifecycle ownership. Use `--instance` for isolation.
+
+Expect: iii-engine v0.22.1 starts, the agentmemory worker registers with iii, and the ready panel lists REST, viewer, streams, and engine addresses. First boot can take longer while the engine binary is downloaded.
+
+## 3. Validate the server and all four ports
+
+| Port | Owner | Validation |
+|---|---|---|
+| 3111 | agentmemory REST/MCP | `/agentmemory/livez` and `/agentmemory/health` return 200 |
+| 3112 | iii streams | listed in the ready panel; must be free at startup |
+| 3113 | agentmemory viewer | opening the URL returns the viewer |
+| 49134 | iii engine WebSocket | listed in the ready panel and worker registration succeeds |
-Wait until it is reachable, then continue:
+From a second terminal, run:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
```
-Expect: a `200` response. Retry for up to ~15 seconds on first run while the engine warms up.
+Expect: both REST checks return JSON, the viewer request succeeds, the startup ready panel has listed all four addresses, and `status` reports healthy agentmemory state. In keyless mode, status should report vectors disabled or `bm25-only`; `mem::search` uses BM25, while smart search may also include existing graph matches. Native PowerShell users can use `Invoke-RestMethod` instead of `curl`.
-## 4. Prove recall in one command
+## 4. Exercise default recall and optional local semantics
```bash
-agentmemory demo --serve
+npx -y @agentmemory/agentmemory@latest demo
```
-`--serve` boots the server, seeds three realistic sessions (JWT auth, an N+1 query fix, rate limiting), runs semantic searches against them, prints the results, and tears everything down. No second terminal needed.
+The demo seeds three realistic sessions and searches them. In default keyless mode, vectors are disabled and the `mem::search` keyword queries such as `jwt auth middleware` and `rate limiting` should return BM25 hits. The deliberately semantic query `database performance optimization` can return zero because no embedding provider is active. Smart search can still add structural graph matches if graph data already exists.
+
+To opt into on-device semantic recall, add this line to `~/.agentmemory/.env`, restart the server, and rerun the demo:
-Expect: the demo finds the "N+1 query fix" memory when it searches for "database performance optimization", which keyword matching alone cannot do. Open `http://localhost:3113` while it runs to watch the memory build live.
+```env
+EMBEDDING_PROVIDER=local
+```
+
+The first embedding request downloads `Xenova/all-MiniLM-L6-v2`; wait for that download to finish. Afterward, inference runs locally and the semantic query should find the N+1 memory. Open `http://localhost:3113` to watch the memory build live.
## 5. Wire MCP into the calling agent
-Detect which agent is running this runbook, then wire its MCP config:
+Detect which agent is running this runbook, then wire its MCP config. On native Windows, run this automated step only for `copilot-cli`:
```bash
-agentmemory connect
+npx -y @agentmemory/agentmemory@latest connect
```
`connect` merges agentmemory into that agent's MCP config and preserves any existing servers. Supported agent names:
`claude-code`, `copilot-cli`, `codex`, `cursor`, `gemini-cli`, `opencode`, `cline`, `continue`, `droid`, `hermes`, `openclaw`, `openhuman`, `pi`, `qwen`, `warp`, `zed`, `antigravity`, `kiro`.
-If you cannot tell which agent you are, default to `claude-code`. After wiring, restart the agent or run its MCP reload command (for example `/mcp` in Claude Code) so it picks up the server.
+If you cannot tell which agent you are, default to `claude-code` on macOS/Linux. On native Windows, `copilot-cli` is the only automated adapter; configure all other agents with the manual MCP block in the README. Run `connect` inside WSL only when the target agent is installed inside the same WSL environment. After wiring, restart the agent or run its MCP reload command (for example `/mcp` in Claude Code) so it picks up the server.
-Expect: the agent now lists agentmemory's tools. With the server running you should see the full set of 54 tools (for example `memory_save`, `memory_smart_search`, `memory_sessions`). If you see only 7 tools, the MCP shim could not reach a server, see Troubleshooting.
+Expect: the agent now lists agentmemory's tools. With the server running you should see the full set of 54 tools (for example `memory_save`, `memory_smart_search`, `memory_sessions`). If you see only 7 tools, the MCP shim could not reach the server; see Troubleshooting.
## 6. Install native skills
@@ -92,7 +125,7 @@ This installs the native skills so the agent knows when to call the memory tools
Expect: the skills are installed for the detected agent.
-## 7. Verify a save and recall round-trip
+## 7. Verify save, recall, and restart persistence
Confirm health first:
@@ -118,13 +151,33 @@ Expect: the first call returns `201`, the second returns `200` with results that
If `AGENTMEMORY_SECRET` is set in the environment, the REST API requires it. Add `-H "Authorization: Bearer $AGENTMEMORY_SECRET"` to both calls. By default no secret is set and localhost is open.
+Now stop and restart the processes, using the same `--data-dir` value if you set one:
+
+```bash
+npx -y @agentmemory/agentmemory@latest stop
+npx -y @agentmemory/agentmemory@latest
+```
+
+After `/agentmemory/livez` returns 200 again, repeat the `smart-search` request above. Expect: the saved probe is still returned. This restart check proves the selected platform data directory is persistent rather than only proving the in-memory index.
+
+## Optional: install a global command
+
+The npx form above is the canonical fresh-install path. If you want the shorter `agentmemory` command afterward:
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+agentmemory --version
+```
+
+If a system Node install returns `EACCES` on macOS/Linux, use a user-owned npm prefix rather than changing repository permissions. The npx form remains available without a global install.
+
## Optional: richer features
These are off by default because they spend tokens. Enable them only if the user wants them. Put configuration in `~/.agentmemory/.env` (no `export` prefix), then restart the server.
- `AGENTMEMORY_INJECT_CONTEXT=true` makes the SessionStart and PreToolUse hooks inject past memory into the agent's context automatically. Cost: spends session tokens proportional to tool-call frequency.
-- `AGENTMEMORY_AUTO_COMPRESS=true` sends each observation to your LLM provider for a richer summary. Cost: spends API tokens proportional to tool-use frequency. Requires a provider key.
-- Provider key: set one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, and similar, in the same file. Without a key, agentmemory stays in zero-LLM mode and still indexes and recalls via BM25 plus local embeddings.
+- LLM-written observation compression requires both `AGENTMEMORY_AUTO_COMPRESS=true` and a configured provider. A provider alone leaves synthetic compression active. When both are set, each observation is sent to the provider for a richer summary, spending API tokens proportional to tool-use frequency.
+- Provider key: set one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, and similar, in the same file. Without a key, agentmemory stays in zero-LLM mode and recalls via BM25. Local embeddings remain available as the separate `EMBEDDING_PROVIDER=local` opt-in above.
## Tool surface
@@ -132,33 +185,37 @@ The MCP server exposes 54 tools by default (`--tools all`). Use `--tools core` (
## Lifecycle commands
-- `agentmemory status` shows server and engine state.
-- `agentmemory doctor` runs diagnostics and reports what is misconfigured.
-- `agentmemory stop` stops the engine this CLI started (`stop --force` bypasses the Docker guard).
-- `agentmemory upgrade` upgrades agentmemory and the iii runtime, best effort.
-- `agentmemory --reset` wipes onboarding preferences and re-runs the wizard.
-- `agentmemory import-jsonl ` imports prior Claude Code session logs as memories.
+- `npx -y @agentmemory/agentmemory@latest status` shows server health, viewer, provider, and embedding state.
+- `npx -y @agentmemory/agentmemory@latest doctor` runs diagnostics and reports what is misconfigured.
+- `npx -y @agentmemory/agentmemory@latest stop` stops the engine this CLI started. Docker mode validates and preserves the exact container and `/data` mount for the next restart; `stop --force` applies only to native ownership checks.
+- `npx -y @agentmemory/agentmemory@latest upgrade` upgrades agentmemory and the iii runtime, best effort.
+- `npx -y @agentmemory/agentmemory@latest --reset` wipes onboarding preferences and re-runs the wizard.
+- `npx -y @agentmemory/agentmemory@latest import-jsonl ` imports prior Claude Code session logs as memories.
## Troubleshooting
-- `command not found: agentmemory`: the global bin is not on `PATH`. Use `npx -y @agentmemory/agentmemory@latest`.
-- `EACCES` during global install: retry with `sudo`, or use the npx form.
-- Stale npx version: run `npx -y @agentmemory/agentmemory@latest`, or clear the cache with `rm -rf ~/.npm/_npx` (macOS/Linux).
+- `command not found: agentmemory`: the optional global bin is not on `PATH`. Use `npx -y @agentmemory/agentmemory@latest`.
+- Automatic iii install fails on macOS/Linux: verify `command -v curl sh tar`; install the missing prerequisite or use Docker.
+- Stale npx version: include both `-y` and `@latest` as shown throughout this runbook.
- Port already in use: another process holds 3111, 3112, 3113, or 49134. Stop that process, then re-run.
-- Server starts but `livez` never returns 200: re-run with `agentmemory --verbose` to see engine stderr.
+- Custom REST port: `--port ` derives streams as `N+1`, viewer as `N+2`, and the iii worker WebSocket as `N+46023` only when their explicit port/URL variables are unset (`III_STREAM_PORT` or legacy `III_STREAMS_PORT`, `III_VIEWER_PORT` or `AGENTMEMORY_VIEWER_URL`, and `III_ENGINE_PORT` or `III_ENGINE_URL`).
+- Server starts but `livez` never returns 200: re-run with `npx -y @agentmemory/agentmemory@latest --verbose` to see engine stderr.
+- `The engine process started but the REST API never responded.`: inspect all four derived ports, confirm the pinned iii process stayed alive, and use `--verbose` for captured engine stderr.
- Engine version warning on start: harmless. agentmemory uses its own pinned engine in `~/.agentmemory/bin` regardless of any `iii` on `PATH`. Set `AGENTMEMORY_III_VERSION` only to override deliberately.
-- "engine conflict" / another iii engine already running: if a different iii version is already serving the port (common if you run your own iii), agentmemory will not adopt it and stops with an "engine conflict" note. Stop that engine (`agentmemory stop --force`, or however you started it), then re-run `agentmemory` — it installs and runs the pinned engine in `~/.agentmemory/bin`, leaving your own iii untouched.
-- Only 7 tools visible in the agent: the MCP shim is in local fallback because it could not reach a server. Start `npx @agentmemory/agentmemory` and ensure `AGENTMEMORY_URL` points at it (default `http://localhost:3111`), then reload MCP.
-- Windows: use WSL2 for the path above. Native Windows runs the server but `connect` and the automated engine install are not supported.
+- "engine conflict" / another iii engine already running: if a different iii version is already serving the port, agentmemory will not adopt it. Stop that engine (`npx -y @agentmemory/agentmemory@latest stop --force`, or however you started it), then rerun the canonical command. Its private v0.22.1 binary does not replace a user-managed `iii` on `PATH`.
+- Only 7 tools visible in the agent: the MCP shim is in local fallback because it could not reach a server. Start `npx -y @agentmemory/agentmemory@latest`, ensure `AGENTMEMORY_URL` points at it (default `http://localhost:3111`), then reload MCP.
+- Native Windows: the CLI does not auto-extract the ZIP. Install the pinned v0.22.1 `iii.exe` manually, use WSL2, or run with Docker Desktop and `AGENTMEMORY_USE_DOCKER=1`. Automated `connect` supports only `copilot-cli`; configure other native agents manually.
+- Semantic demo query returns zero hits: this is expected with vectors disabled in default keyless mode. Set `EMBEDDING_PROVIDER=local`, restart, allow the first model download to complete, and rerun the demo.
## Report success
Report back to the user:
- agentmemory installed, version, and the server running on port 3111
+- iii-engine v0.22.1 running, the selected platform data directory, and all four ports accounted for
- which agent was wired via `agentmemory connect`, and the tool count the agent now sees
-- the save and recall round-trip returned the probe memory
+- the save and recall round-trip returned the probe memory after a full stop/start
- the viewer is available at `http://localhost:3113`
-- whether any optional features were enabled
+- whether vectors were disabled (`mem::search` BM25, with optional graph matches in smart search) or an embedding provider was enabled
If any step failed, report which step, the exact command, and the error output.
diff --git a/README.md b/README.md
index 6a6462d566..72e285ae2c 100644
--- a/README.md
+++ b/README.md
@@ -11,18 +11,39 @@
@@ -75,21 +96,33 @@
## Install
-One command:
+Requirements:
+
+- Node.js 20 or newer with npm and npx (`node -v`, `npm -v`, and `npx -v`).
+- macOS/Linux automatic iii-engine installation also needs `curl`, a POSIX `sh`, and `tar`. Minimal images such as `node:20-slim` may not include them.
+- Native Windows requires the pinned iii-engine v0.22.1 `iii.exe` to be installed manually. WSL2 or Docker Desktop are the other supported paths.
+
+Canonical fresh-install command:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-The first run is an interactive setup: pick the agents to wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pick an LLM provider or stay keyless, and it seeds the config, starts the memory server on `:3111`, and offers to install globally so the bare `agentmemory` command works everywhere afterwards.
+The first run is an interactive setup: pick the agents to wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pick an LLM provider or stay keyless, and it seeds the config, starts the memory server and its pinned iii engine, and offers to install globally so the bare `agentmemory` command works everywhere afterward. `-y` accepts npx's package prompt and `@latest` avoids a stale cached release. A provider makes LLM features available, but LLM-written observation compression starts only when `AGENTMEMORY_AUTO_COMPRESS=true` is also set.
+
+Keyless mode disables vector embeddings. `memory_recall` (the `mem::search` path) uses BM25, while `memory_smart_search` can also fuse structural graph matches when graph data already exists. For free on-device semantic recall, set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart. The first embedding request downloads `Xenova/all-MiniLM-L6-v2`; inference runs locally after that initial model download.
+
+The local runtime uses four ports: `3111` for REST/MCP HTTP, `3112` for iii streams, `3113` for the viewer, and `49134` for the iii worker WebSocket. Persistent iii state lives in `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. Use `--data-dir ` or `AGENTMEMORY_DATA_DIR` to override it, and reuse the same value on every restart. For backward compatibility, an existing `./data/state_store.db` or `./data/iii-config.yaml` takes precedence over the platform default for instance 0; an explicit flag or environment override still wins.
Then prove recall works and give your agent its skills:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
+The keyword searches should hit in default keyless mode through BM25. The demo's `database performance optimization` query is intentionally semantic and can return zero until an embedding provider is configured.
+
Prefer to let a coding agent do the whole thing? Hand it one instruction:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
@@ -99,7 +132,7 @@ Wire more agents any time with `agentmemory connect ` — 20 adapters lis
Windows
-The fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 minutes) and `agentmemory connect` is currently unsupported there. See the [Windows notes](#windows) for the step-by-step.
+The fast path is WSL2. Native Windows engine setup requires the pinned v0.22.1 ZIP to be downloaded and `iii.exe` extracted manually; the CLI does not auto-extract it. Docker Desktop is also supported. See the [Windows notes](#windows) for the step-by-step.
@@ -107,11 +140,11 @@ The fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 min
Global install / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+The npx command above remains the canonical fresh-install path and avoids global-prefix permission issues.
+
@@ -124,7 +157,7 @@ npx caches per version. Force the latest with `npx -y @agentmemory/agentmemory@l
Already running your own iii engine
-agentmemory pins iii-engine v0.11.2 and won't attach to a different version (the worker can't speak another engine's protocol). Stop the other engine, then run `npx -y @agentmemory/agentmemory@latest`. It installs and runs the pinned v0.11.2 in `~/.agentmemory/bin`, leaving your own `iii` untouched.
+agentmemory pins iii-engine v0.22.1 and won't attach to a different version (the worker can't speak another engine's protocol). Stop the other engine, then run `npx -y @agentmemory/agentmemory@latest`. It installs and runs the pinned v0.22.1 in `~/.agentmemory/bin`, leaving your own `iii` untouched.
@@ -136,99 +169,138 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
-
+
Claude Code native plugin + 12 hooks + MCP
-
+
Codex CLI native plugin + 6 hooks + MCP
-
-
+
+ GitHub Copilot CLI MCP + plugin hooks/skills
-
+
+
+Cursor
+native plugin + 7 hooks + MCP
+
+
+
+OpenCode
+capture plugin + MCP
+
+
+
+
+
+Devin
+6 hooks + skills + MCP
+
+
OpenClaw native plugin + MCP
-
+
Hermes native plugin + MCP
-
+
pi native plugin + MCP
-
-
+
+ OpenHuman native Memory trait backend
-
-
-Cursor
-native plugin + MCP
-
-
+
+
+
Gemini CLI MCP server
+
+
+Antigravity
+MCP + hooks
+
+
+
+Claude Desktop
+MCP server
+
+
+
+Warp
+connect + MCP + skills
+
+
+
+Zed
+MCP server
+
-
-
-OpenCode
-22 hooks + MCP + plugin
-
-
+
Cline MCP server
-
-
-Goose
+
+
+Continue MCP server
-
-
-Kilo Code
+
+
+Droid MCP server
-
-
-Aider
-REST API
+
+
+Kiro
+MCP server
-
-
-Claude Desktop
+
+
+Qwen Code MCP server
-
-
-Devin
-6 hooks + MCP
+
+
+
+
+DeepSeek Harness
+MCP server
-
+
Roo Code MCP server
-
-
-
-
-Warp
-connect + MCP + skills
+
+
+Kilo Code
+MCP server
+
+
+
+Goose
+MCP server
+
+
+
+Aider
+REST API
@@ -244,16 +316,18 @@ You explain the same architecture every session. You re-discover the same bugs.
**What changes:** Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in `src/middleware/auth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility, with no re-explaining and no copy-pasting.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-By default, agentmemory stores iii-engine state outside the repository you start it from: `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. To choose a location, pass `--data-dir ` or set `AGENTMEMORY_DATA_DIR`:
+By default, agentmemory stores iii-engine state outside the repository you start it from: `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. An existing legacy `./data/state_store.db` or `./data/iii-config.yaml` is reused for instance 0 before that platform default. To choose a location explicitly, pass `--data-dir ` or set `AGENTMEMORY_DATA_DIR`; either explicit setting takes precedence over legacy discovery:
```bash
-npx @agentmemory/agentmemory --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
+Native and Docker launches use this same resolved host directory; Docker bind-mounts it at `/data`. `--instance 1` appends `instance-1` to the resolved directory and selects the separate default port quartet `3211/3212/3213/49234`.
+
Latest release notes: [CHANGELOG.md](CHANGELOG.md).
---
@@ -482,29 +556,54 @@ None of these auto-capture from coding-agent hooks, ship a local-first viewer, o
-Compatibility: this release targets stable `iii-sdk` `^0.11.0` and iii-engine v0.11.x.
+Compatibility: this release targets `iii-sdk` 0.22.1 and pins iii-engine v0.22.1.
### Try it in 30 seconds
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest demo
```
-`demo` seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs semantic searches against them. You'll see it find "N+1 query fix" when you search "database performance optimization", which keyword matching cannot do.
+`demo` seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs searches against them. Keyless installs disable vectors, so the `mem::search` keyword queries should hit through BM25 while `database performance optimization` can return zero. `smart-search` may additionally return structural graph matches when graph data exists. To make the semantic query find the N+1 fix through vectors, set `EMBEDDING_PROVIDER=local`, restart, and allow the first model download to finish.
Open `http://localhost:3113` to watch the memory build live.
+### Validate a fresh install and restart persistence
+
+With the server running, validate REST, health, the viewer, and the iii-backed runtime status:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+The startup ready panel accounts for all four ports: REST/MCP HTTP on 3111, iii streams on 3112, the viewer on 3113, and the iii worker WebSocket on 49134. `status` confirms agentmemory health and the active provider/embedding mode. Save a probe and confirm it is searchable:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Then run `npx -y @agentmemory/agentmemory@latest stop`, start the canonical command again in Terminal 1, wait for `/agentmemory/livez`, and repeat the search. The probe must still be returned. If you selected a custom `--data-dir`, pass the same directory on the restart.
+
### Everyday commands
Install and setup live in [Install](#install) above (the first run walks you through it). Day to day:
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -518,10 +617,10 @@ To bring in older Claude Code JSONL transcripts:
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
Imported sessions show up in the Replay picker alongside native ones. Under the hood each entry routes through the `mem::replay::load`, `mem::replay::sessions`, and `mem::replay::import-jsonl` iii functions, with no side-channel servers. Each imported transcript is indexed for search, stamped with origin channel `import`, and mined for a session crystal and lessons.
@@ -533,17 +632,17 @@ Imported sessions show up in the Replay picker alongside native ones. Under the
Use the maintenance command when you intentionally want to update your local runtime:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies and pull the pinned `iiidev/iii:0.11.2` Docker image. It never installs an unpinned or newer iii engine.
+Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies and pull the pinned `iiidev/iii:0.22.1` Docker image. It never installs an unpinned or newer iii engine.
Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cli.ts:544-595` region).
### Claude Code (one block, paste it)
```text
-Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code without the plugin install (MCP-standalone path)
@@ -563,7 +662,7 @@ For remote or protected deployments, launch Claude Code with `AGENTMEMORY_URL` a
```bash
# 1. start the memory server in a separate terminal
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
@@ -572,41 +671,43 @@ codex plugin add agentmemory@agentmemory
The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers:
-- `@agentmemory/mcp` as an MCP server (proxies all 54 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)
+- A bundled stdio MCP bridge to the running daemon, with no npm download or fallback store. See the [local Codex guide](docs/plugins/codex-local.md) to test an unreleased build.
- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 reference skills the agent loads on demand (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide)
Codex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.
-#### Codex Desktop: plugin hooks currently silent (workaround available)
+#### Codex hook trust and compatibility
-`CodexHooks` and `PluginHooks` are both stable + default-enabled in [`codex-rs/features/src/lib.rs`](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs), but Codex Desktop builds currently do not dispatch plugin-local `hooks.json` ([openai/codex#16430](https://github.com/openai/codex/issues/16430)). MCP tools still work; only the lifecycle observations are missing.
+Native plugin hook dispatch is verified with Codex CLI 0.150.1. Trust the plugin hooks before expecting capture. Desktop behavior depends on its bundled runtime; check `/hooks` and confirm a captured event before enabling a workaround.
-Until upstream lands the fix, mirror the same hook commands into the global `~/.codex/hooks.json`:
+If your host requires global hooks, mirror the commands into `~/.codex/hooks.json`. When MCP is already wired, the current connector needs `--force` to reach hook installation:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-This adds an idempotent block to `~/.codex/hooks.json` referencing absolute paths to the bundled scripts (no `${CLAUDE_PLUGIN_ROOT}` expansion needed at user-scope). Re-run the same command after upgrading agentmemory to refresh paths. User entries in the same file are preserved; only previous agentmemory entries are replaced.
+This merges global hooks and rewrites the agentmemory MCP entry, preserving unrelated entries. Review any custom agentmemory endpoint settings before using `--force`. Re-run after upgrading to refresh script paths. Enable either native plugin hooks or global copies to avoid duplicate capture.
### GitHub Copilot CLI
+For VS Code agent mode, use the [Copilot MCP and automatic-capture guide](docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). The CLI connector does not configure VS Code.
+
```bash
# MCP-only wiring
agentmemory connect copilot-cli
-# Full hooks/skills plugin from the GitHub subdir
+# Alternatively, full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin
```
-`agentmemory connect copilot-cli` merges `mcpServers.agentmemory` into `~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set) and preserves existing servers. This adapter is Windows-safe even though other `connect` adapters still require manual Windows setup. Copilot picks up the MCP server on next launch or after `/mcp`. Install the plugin as well when you want the full hook/skill experience.
+`agentmemory connect copilot-cli` merges `mcpServers.agentmemory` into `~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set) and preserves existing servers. On native Windows this is the only automated `connect` adapter; configure every other native Windows agent manually. WSL `connect` is supported only when the target agent is installed in that same WSL environment. Copilot picks up the MCP server on next launch or after `/mcp`. Install the plugin as well when you want the full hook/skill experience.
OpenClaw (paste this prompt)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -631,7 +732,7 @@ Full guide: [`integrations/openclaw/`](integrations/openclaw/)
Hermes Agent (paste this prompt)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -650,7 +751,7 @@ Full guide: [`integrations/hermes/`](integrations/hermes/)
### Other agents
-Start the memory server: `npx @agentmemory/agentmemory`
+Start the memory server: `npx -y @agentmemory/agentmemory@latest`
#### Native skills via `npx skills add` (50+ agents)
@@ -700,14 +801,14 @@ The agentmemory entry is the **same MCP server block** across every host that us
| **GitHub Copilot CLI (full plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` for the plugin from the GitHub subdir. |
| **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block. Deeper: `openclaw plugins install ./integrations/openclaw` claims OpenClaw's memory slot (auto-switches from `memory-core`); set `plugins.entries.agentmemory.hooks.allowConversationAccess=true` or turn capture is silently blocked. See [`integrations/openclaw`](integrations/openclaw/). |
| **Codex CLI (MCP only)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. |
-| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin add agentmemory@agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 17 skills. On Codex Desktop, also run `agentmemory connect codex --with-hooks` until [openai/codex#16430](https://github.com/openai/codex/issues/16430) lands; plugin hooks are currently silent there. |
+| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin add agentmemory@agentmemory`. Registers MCP + 6 lifecycle hooks + 17 skills. Trust hooks and verify capture in your host; see [Codex setup and validation](docs/plugins/codex-local.md). |
| **OpenCode (MCP only)** | `opencode.json` | Different shape: top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (full plugin)** | `plugin/opencode/` | 22 auto-capture hooks covering session lifecycle, messages, tools, errors. Project attribution is per-session, so one OpenCode process spanning several repositories files each session under its own project. Two slash commands (`/recall`, `/remember`). Copy `plugin/opencode/` into your OpenCode workspace and add the plugin entry to `opencode.json`. See [`plugin/opencode/README.md`](plugin/opencode/README.md) for the full hook table + gap analysis. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installs the bundled extension into pi's auto-discovery directory (recall on agent start, capture on agent end, `memory_search` / `memory_save` / `memory_health` tools, `/agentmemory-status`). `/reload` in a running pi picks it up. [`integrations/pi`](integrations/pi/) is also a pi package (`pi install ./integrations/pi` from a checkout). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` gives the 6-hook memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block). Validate with `hermes plugins doctor` and `hermes memory status`. See [`integrations/hermes`](integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` writes the standard `mcpServers` block. Hook payload is field-compatible with Claude Code, so the existing 12-hook scripts work without modification; wire them via the `hooks` section in the same `settings.json`. |
-| **Antigravity** (replaces Gemini CLI) | `mcp_config.json` (in Antigravity's User dir) | `agentmemory connect antigravity` writes the standard `mcpServers` block. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Use after the 2026-06-18 Gemini CLI sunset. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. The `agy` CLI keeps its own config under `~/.gemini/`, separate from the Antigravity IDE above. Pass `--with-hooks` for native auto-capture via `~/.gemini/config/hooks.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installs MCP and capture hooks in the shared customization directory. See [Antigravity setup and limits](docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` uses the same MCP and hook configuration as current IDE versions. Existing installations should refresh with `--force`; see the [upgrade notes](docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` writes the user-level config. Workspace overrides go in `.kiro/settings/mcp.json` next to your code. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` writes the standard `mcpServers` block. Warp also auto-discovers skills from `.claude/skills/`; once the Claude Code plugin is installed the 8 agentmemory skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) appear natively in Warp's slash-command palette. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` writes the standard `mcpServers` block. VS Code extension users: paste the same block via Cline Settings → MCP Servers → Edit JSON. |
@@ -752,39 +853,43 @@ git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
-This starts agentmemory with a local `iii-engine` if `iii` is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to `127.0.0.1` by default.
+This starts agentmemory with a local `iii-engine` if the pinned binary is already installed, or uses Docker Compose when selected. REST, streams, and the viewer bind to `127.0.0.1` by default. The automatic macOS/Linux binary path requires `curl`, a POSIX `sh`, and `tar`.
-Install `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.11.2`**. `v0.11.6` introduces a new sandbox-everything-via-`iii worker add` model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with `AGENTMEMORY_III_VERSION=` if you've migrated to the sandbox model manually.
+Install `iii-engine` manually. **agentmemory currently pins `iii-engine` to `v0.22.1`**, the same release as its `iii-sdk` dependency; the worker speaks that engine's wire protocol, and 0.20.0 reorganized the SDK surface, so the two move together in agentmemory releases. Override with `AGENTMEMORY_III_VERSION=` if you run your own engine and know it matches.
-- **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 arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** swap `aarch64-apple-darwin` for `x86_64-apple-darwin`
- **Linux x64:** swap for `x86_64-unknown-linux-gnu`
- **Linux arm64:** swap for `aarch64-unknown-linux-gnu`
-- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), extract `iii.exe`, add to PATH
+- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` from [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) and extract `iii.exe` to `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Every archive has a matching `.sha256` file on the release page; when you swap the platform, use that file's hash in the check above (on Windows: `Get-FileHash`). The automatic installer in `npx @agentmemory/agentmemory` pins these hashes and refuses an archive that does not match.
-Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:0.11.2`). Full docs: [iii.dev/docs](https://iii.dev/docs).
+Or use Docker (the bundled `docker-compose.yml` pulls `iiidev/iii:0.22.1`). Full docs: [iii.dev/docs](https://iii.dev/docs).
### Windows
-agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough; you also need the `iii-engine` runtime (a separate native binary) as a background process. The official upstream installer is a `sh` script and there is no PowerShell installer or scoop/winget package today, so Windows users have two paths:
+agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough; you also need the pinned iii-engine v0.22.1 runtime as a background process. The CLI does not auto-extract the Windows ZIP, so native Windows users must install `iii.exe` manually, use WSL2, or choose Docker Desktop.
+
+Native Windows automated MCP wiring supports only `agentmemory connect copilot-cli`. For Claude Code, Codex, Cursor, and every other native Windows agent, copy the manual MCP block from [Other agents](#other-agents) into that agent's Windows config. Running `connect` in WSL is appropriate only when the target agent is also installed in the same WSL environment; it does not edit a Windows-host agent's configuration.
**Option A: prebuilt Windows binary (recommended)**
```powershell
-# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
-# (we pin to v0.11.2 until agentmemory refactors for the new sandbox
-# model that engine v0.11.6+ requires)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**Option B: Docker Desktop**
@@ -792,28 +897,29 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
**Option C: standalone MCP only (no engine).** If you only need the MCP tools for your agent and don't need the REST API, viewer, or cron jobs, skip the engine entirely:
```powershell
-npx -y @agentmemory/agentmemory mcp
+npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
-**Diagnostics for Windows:** if `npx @agentmemory/agentmemory` fails, re-run with `--verbose` to see the actual engine stderr. Common failure modes:
+**Diagnostics for Windows:** if `npx -y @agentmemory/agentmemory@latest` fails, re-run it with `--verbose` to see the actual engine stderr. Common failure modes:
| Symptom | Fix |
|---|---|
-| `iii-engine process started` then `did not become ready within 15s` | Engine crashed on startup; re-run with `--verbose`, check stderr |
+| `The engine process started but the REST API never responded.` | Confirm all four derived ports are free, verify the pinned `iii.exe` stayed alive, then re-run with `--verbose` and inspect the captured engine stderr |
| `Could not start iii-engine` | Neither `iii.exe` nor Docker is installed. See Option A or B above |
| Port conflict | `netstat -ano \| findstr :3111` to see what's bound, then kill it or use `--port ` |
| Docker fallback skipped even though Docker is installed | Make sure Docker Desktop is actually running (system tray icon) |
-> Note: the iii **engine** is a prebuilt binary, not a cargo crate, so don't try to `cargo install` it. (The iii **SDKs** are published on crates.io, npm, and PyPI, but agentmemory doesn't need them.) Supported engine install methods, all pinned to v0.11.2: the prebuilt v0.11.2 binary above, the upstream sh install script **with the version pin** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), and the Docker image `iiidev/iii:0.11.2`. A bare `install.sh | sh` installs the **latest** engine, which agentmemory does not support; always pass `VERSION=0.11.2`. Easiest of all: just run `npx @agentmemory/agentmemory`, which fetches the pinned engine into `~/.agentmemory/bin` for you.
+> Note: the iii **engine** is a prebuilt binary, not a cargo crate, so don't try to `cargo install` it. (The iii **SDKs** are published on crates.io, npm, and PyPI, but agentmemory doesn't need them.) Supported engine install methods are all pinned to v0.22.1: the prebuilt binary above, agentmemory's macOS/Linux auto-install path (`curl`, POSIX `sh`, and `tar` required), and the Docker image `iiidev/iii:0.22.1`. A bare upstream `install.sh | sh` installs the latest engine, which agentmemory does not support. Use `npx -y @agentmemory/agentmemory@latest`; on macOS/Linux it fetches the pinned engine into `~/.agentmemory/bin`.
---
@@ -897,9 +1003,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -974,21 +1081,25 @@ Triple-stream retrieval combining three signals:
Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).
-Hybrid ranking applies to the primary recall path, not just `smart-search`: `mem::search` (behind `memory_recall`) ranks through the same BM25 + vector + graph fusion once the vector index is populated. Lesson recall runs on a dedicated in-memory BM25 index instead of scanning the whole corpus per query. Superseded memory versions are excluded from every recall path; the version chain keeps their history.
+When a vector index is populated, `mem::search` (behind `memory_recall`) uses the hybrid BM25 + vector ranker. Without embeddings it uses BM25. `smart-search` can additionally fuse structural graph matches when graph data exists, including in keyless mode. Lesson recall runs on a dedicated in-memory BM25 index instead of scanning the whole corpus per query. Superseded memory versions are excluded from every recall path; the version chain keeps their history.
+
+Vectors survive a crash or force-kill. The vector index is saved in buckets at most every `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutes). Every vector added or removed in between is also written right away to a small pending log in the state store, and the next start replays it without calling the embedding provider. Each successful save empties the log. Documents that still have no vector after the replay are re-embedded in the background in batches of `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) until none are left, and a backfill that is stopped continues at the next start. `/agentmemory/status` and the viewer show the pending log size and the backfill state. Keyless installs write nothing.
BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (`npm install @node-rs/jieba tiny-segmenter`) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.
### Embedding providers
-agentmemory auto-detects your provider. For best results, install local embeddings (free):
+Keyless installs disable vector embeddings: `mem::search` uses BM25, while `smart-search` can also use existing structural graph data. To opt into free on-device semantic embeddings, add this to `~/.agentmemory/.env` and restart agentmemory:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+The normal npm install includes the optional `@huggingface/transformers` runtime. The first embedding request downloads `Xenova/all-MiniLM-L6-v2`, so it needs network access and can take longer; subsequent inference runs on-device. Remote providers are auto-detected from their keys unless `EMBEDDING_PROVIDER` overrides them.
+
| Provider | Model | Cost | Notes |
|---|---|---|---|
-| **Local (recommended)** | `all-MiniLM-L6-v2` | Free | Offline, +8pp recall over BM25-only |
+| **Local (recommended opt-in)** | `all-MiniLM-L6-v2` | Free | On-device after the first model download, +8pp recall over BM25-only |
| Gemini | `gemini-embedding-001` | Free tier | 100+ languages, 768/1536/3072 dims (MRL), 2048-token input. Replaces `text-embedding-004` ([deprecated, shutdown Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | Highest quality |
| Voyage AI | `voyage-code-3` | Paid | Optimized for code |
@@ -1001,7 +1112,7 @@ npm install @huggingface/transformers
54 tools, 6 resources, 3 prompts, and 17 skills.
-> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 54-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag; setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`.
+> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 54-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag; setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx -y @agentmemory/agentmemory@latest` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
@@ -1093,7 +1204,7 @@ The table shows the four core skills. The full set is 9 invocable skills plus 8
Run without the full server, for any MCP client. Either of these works:
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (always available)
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
@@ -1141,13 +1252,20 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Auto-starts on port `3113`. Live observation stream with a stream status indicator, a two-pane session explorer (list beside a sticky detail panel on wide screens), memory and lesson rows that expand to the full stored record including raw JSON and origin provenance, a knowledge graph that clusters nodes by type while relations are sparse, session replay, and a health dashboard.
+Auto-starts on port `3113`. The viewer loads one snapshot when it connects (`GET /agentmemory/viewer/snapshot`) and then applies live stream events: new memories, lessons, observations, audit entries, graph changes and health updates appear without polling or page reloads. The only other requests are the actions you click, "load more" pages and searches. When the stream drops, the viewer shows how old its numbers are, reconnects with backoff and resyncs from one snapshot.
+
+- **12 tabs in four groups** with live counts, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), keyboard shortcuts and a mobile menu.
+- **Memories:** server-side search, filters by project, agent and type, a detail panel with the version chain and a word diff, provenance links, copy buttons for the id, the MCP call and a curl command, edit (a new version), forget with confirmation, bulk forget and JSON export.
+- **Sessions:** an inline observation timeline with readable tool input and output, filters and paging, and the memories and lessons each session produced.
+- **Graph:** search, node detail with relations and sources, a legend that does not rely on colour alone, and zoom controls.
+- **Health:** the live version of `GET /agentmemory/status`. Every problem comes with its fix, plus the state backend, index save state, graph provenance compaction progress and a consolidation explainer with the real thresholds.
+- **Audit, Activity, Profile, Replay, Lessons, Actions and Crystals** pages, each with an empty state that says what the section is, why it is empty and the command that fills it, and a `?` glossary tooltip on every term and number.
```bash
open http://localhost:3113
```
-The viewer server binds to `127.0.0.1` by default. The REST-served `/agentmemory/viewer` endpoint follows the normal `AGENTMEMORY_SECRET` bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`).
+The viewer server binds to `127.0.0.1` by default and attaches the server secret when it forwards requests to the REST API, so it needs no setup. The REST-served `/agentmemory/viewer` endpoint follows the normal bearer-token rules and redirects browsers without a token to the viewer port. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`).
---
@@ -1165,22 +1283,20 @@ agentmemory ships this for free because every function call and trigger fires th
Workers page: every connected worker, including agentmemory itself, with PID, function count, runtime, and last-seen.
-**Already installed.** The console ships with `iii`; no separate installer.
+**Already installed.** The console ships with the pinned `iii` engine (0.22+); nothing separate to install. The first launch downloads the console binary next to the engine.
**Launch alongside 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
+agentmemory console
```
-Then open `http://localhost:3114`. Add `--enable-flow` for the experimental architecture-graph page.
+This runs the pinned engine's `iii console` against the ports agentmemory resolved (REST, streams, bridge) and serves it one port above the viewer, `http://localhost:3114` by default. `--console-port N` picks another port; `--port` and `--instance` select the agentmemory instance the same way they do for `stop`; any other flag is passed through, for example `--enable-flow` for the experimental architecture-graph page.
-Override engine endpoints only if you've moved them:
+The same thing by hand, useful when `agentmemory` is not on PATH:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1209,7 +1325,7 @@ iii console --port 3114 \
**Traces are already on:**
-`iii-config.yaml` ships with the `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs). No extra config needed; the moment agentmemory starts, every memory operation emits a trace span and a structured log the console can read.
+`iii-config.yaml` ships with the `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). No extra config needed; the moment agentmemory starts, every memory operation emits a structured log the console can read, and one in ten of them (`sampling_ratio: 0.1`) also emits a trace span.
If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change `exporter: memory` to `exporter: otlp` and set the collector endpoint per iii's observability docs.
@@ -1223,32 +1339,102 @@ agentmemory is **already a running [iii](https://iii.dev) instance**. Three prim
That means one more command extends agentmemory with an entire new capability.
-### Extend agentmemory with one command
+### Extend agentmemory with more workers
-```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
-```
+The builtins agentmemory needs are already in `iii-config.yaml` and boot with it: `iii-state` (KV), `iii-queue` (durable retries for the event subscribers), `iii-pubsub`, `iii-cron`, `iii-stream`, and `iii-observability` (OTEL traces, metrics and logs on every function). Anything else from the [iii worker registry](https://workers.iii.dev) plugs into the same engine: copy `iii-config.yaml` to `~/.agentmemory/iii-config.yaml` (the CLI prefers that file over the bundled one and still renders ports and data paths into it), add the entry, install the worker runtime once with `~/.agentmemory/bin/iii update worker`, and restart agentmemory.
-Each `iii worker add` registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately: no reload, no new integration, no new container.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | What you get on top of agentmemory |
+| Worker | What you get on top of agentmemory |
|---|---|
-| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Multi-instance memory: every `remember` fans out, every `search` reads the union |
-| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Scheduled lifecycle: nightly consolidation, weekly snapshots, decay on a fixed clock |
-| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Durable retries: failed embedding + compression jobs survive restart, no lost observations |
-| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL traces, metrics, logs on every function, wired in `iii-config.yaml` from day one |
+| [`database`](https://workers.iii.dev/workers/database) | SQL-backed state adapter when you outgrow the in-memory KV defaults |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code that came out of `memory_recall` runs inside a throwaway VM, not your shell |
-| [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-backed state adapter when you outgrow the in-memory KV defaults |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Stand up extra MCP servers next to agentmemory's, share the same engine |
+On engine 0.22.x keep the `iii-` prefixed names for the builtins above; the unprefixed `http`, `state`, `queue`, `pubsub` and `cron` entries are the standalone registry workers agentmemory moves to with the 0.23 migration.
+
Full registry: [workers.iii.dev](https://workers.iii.dev). Every worker there composes through the same primitives agentmemory uses, and the agentmemory you already have is one of them.
+### Engine config and bind address
+
+`agentmemory start` reads the engine config from the first file that exists: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` in the current directory, `~/.agentmemory/iii-config.yaml`, then the bundled `iii-config.yaml`. On every start it renders that file (data paths, ports, state backend) into `~/.agentmemory/data/iii-config.runtime.yaml` and launches the engine with the rendered copy, so edit the source file, not the rendered one. The `host:` values of the source file are kept as written.
+
+The bundled `iii-config.yaml` binds `127.0.0.1` on purpose, and that default also applies inside a container. A CLI started in a container listens on the container's loopback, so published ports reach nothing. To serve a containerized CLI through published ports, set `AGENTMEMORY_III_CONFIG` to a config that binds `0.0.0.0`. The packaged `iii-config.docker.yaml` is one: it binds `iii-http`, `iii-stream` and the engine port to `0.0.0.0` and stores state under `/data`, so mount a writable volume there. Keep `AGENTMEMORY_SECRET` set, and publish only the ports you need, on `127.0.0.1` or behind a proxy you trust.
+
+This repo's `docker-compose.yml` does not go through the CLI's config lookup: it mounts `iii-config.docker.yaml` at `/app/config.yaml`, and the `iii-engine` container starts with `--config /app/config.yaml`. The one-click [deploy templates](deploy/) write their own `0.0.0.0` config in their entrypoints.
+
+### Storage backend: file (default) vs redis
+
+`iii-state` and `iii-stream` default to iii-engine's bundled file-based KV store: one JSON file per scope, held in the engine process's memory and rewritten to disk on a timer. That's the right default for a single-user local install; a shared daemon with several concurrent writers gets real per-key writes from Redis instead, at the cost of a network round trip per operation (every `state::*` call still serializes on one Redis connection, so this trades the file store's lock for a socket, not for parallelism).
+
+Set `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) to switch both workers to iii-engine's built-in `redis` adapter, which stores each key as a Redis hash field (`HSET`) instead of rewriting a whole scope on every write:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` defaults to `file`; leaving it unset keeps today's behavior unchanged, and an unrecognized value (anything other than `file` or `redis`) is a startup error rather than a silent fallback. `/agentmemory/status` and the viewer's Health page (the State store row) report which backend is active and whether it answers, never the URL.
+
+**Plain `redis://` only.** The pinned engine (0.22.1) builds its Redis client without TLS support, so a `rediss://` URL (most managed Redis offerings, such as Upstash, Redis Cloud, and ElastiCache with in-transit encryption, default to TLS-only) fails to connect. The connection is unencrypted, so the Redis password and every stored memory cross the wire in clear text: point at a local Redis or one on a private network you trust. For any other Redis, run an encrypted tunnel (stunnel, SSH, or a VPN) on the agentmemory host, so the plain `redis://` hop stays on that host and the tunnel's upstream connection is encrypted and authenticated. If a Redis password contains a single quote, percent-encode it (`%27`); the engine expands the URL into its YAML config before parsing it.
+
+**One Redis server per `--instance`.** The engine's Redis key prefixes (`state:`, `stream::`) are fixed, so two agentmemory instances (`--instance 1`, `--instance 2`, ...) pointed at the same database overwrite each other's data. A separate database index (`redis://localhost:6379/1`) keeps the stored data apart, but the engine relays live viewer events over one Redis pub/sub channel (`stream::events`), and Redis pub/sub ignores the database index, so each instance's viewer would still show the other's live events. Give each instance its own Redis server (or port) when you run more than one.
+
+**What stays the same, and what differs.** Every agentmemory feature works on Redis: sessions, observations, memories (remember, supersede, evolve, forget), search and the index buckets, lessons, the graph, the audit log and its monthly scopes, export and import, governance deletes, consolidation status, the viewer snapshot and its live stream, and the health monitor. The engine stores each scope as one Redis hash (`HSET`/`HGET`/`HGETALL`) and fires the same state triggers as the file store. Three engine differences are handled inside agentmemory:
+
+- Redis returns a scope's records in no fixed order. agentmemory sorts them oldest first (by the creation time in the record id, then its timestamp) so lists, paging and export chunks come back in the same order as on the file store.
+- The engine applies partial updates on Redis in a Lua script that turns empty arrays into empty objects. agentmemory applies those updates itself (read, change, write under a per-key lock) on Redis, so fields like `tags: []` stay arrays.
+- The legacy audit log check reads the old scope from Redis instead of looking for the file store's file on disk.
+
+One difference needs you: **after Redis restarts, the engine stops relaying live events** to the viewer until agentmemory restarts. Data is still saved and read normally. The health monitor sends a test event through Redis every 30 seconds; when it does not come back, `/agentmemory/status` and the viewer's Health page show "Live updates are not reaching the viewer" with the fix: restart agentmemory. If Redis is down, the status report shows "The state store is not answering" and how to check it (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listing a very large scope reads the whole hash in one `HGETALL`, the same cost as the file store holding it in memory.
+
+**Recommended Redis settings.** The default `save 3600 1 300 100 60 10000` snapshot policy can lose minutes of writes on a crash, worse than the file store's 5s flush window. Set `appendonly yes` for anything you'd mind losing. Set `maxmemory-policy noeviction`; `allkeys-lru` or similar silently drops memories once Redis hits its memory limit.
+
+A native (non-Docker) start, and every one-click [deploy template](deploy/) (they overwrite the bundled `iii-config.yaml` and start natively), read `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` and render them into the launched `iii-config`. The URL itself is never written to that rendered file, only a `${AGENTMEMORY_REDIS_URL}` reference that the engine process expands from its own environment at boot. Only this repo's own Docker Compose path (`AGENTMEMORY_USE_DOCKER=1`, or resuming an engine already started that way) mounts `iii-config.docker.yaml` read-only and never renders; `agentmemory start` warns when it detects that combination. Switch that file by hand, following the same `name: redis` / `config: redis_url: ...` shape shown in the [iii-state](https://workers.iii.dev/workers/iii-state) and [iii-stream](https://workers.iii.dev/workers/iii-stream) worker docs, and point `redis_url` at a Redis reachable from the container. `docker-compose.yml` passes `AGENTMEMORY_REDIS_URL` into the engine container, so `redis_url: '${AGENTMEMORY_REDIS_URL}'` works there and keeps the URL out of the mounted file.
+
+The rendered config keeps the URL out of `~/.agentmemory/data/iii-config.runtime.yaml`, but the engine's own configuration worker still persists the *expanded* value to `~/.agentmemory/config/iii-state.yaml` and `iii-stream.yaml` once it boots (iii-engine's `${VAR}` expansion happens before that worker stores its seed, and it stores the resolved value, not the reference). Treat that directory as holding a credential: `chmod 700 ~/.agentmemory` on any shared host, and prefer a Redis ACL user scoped to what agentmemory needs over the database's admin credentials.
+
+**Migration is not automatic.** Switching `AGENTMEMORY_STATE_BACKEND` starts from an empty store on either side; nothing copies existing data from file to Redis or back. Export from the backend you're leaving and import into the one you're moving to. This runs identically under bash and zsh (including `bash -u`). An array like `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` does not: zsh keeps the header as one malformed word where bash splits it into two, so both requests 401 whenever `AGENTMEMORY_SECRET` is set:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` also accepts `?maxSessions=` and `?offset=` for chunking a large corpus across several calls; `strategy` on import is `merge` (default-safe), `replace`, or `skip`.
+
### What iii replaces
| Traditional stack | agentmemory uses |
@@ -1260,7 +1446,7 @@ Full registry: [workers.iii.dev](https://workers.iii.dev). Every worker there co
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add ` |
-**184 source files · ~42,200 LOC · 1,674 tests · 264 functions · 50 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+**225 source files · ~54,000 LOC · 2,600+ tests · 312 functions · 66 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
---
@@ -1268,11 +1454,11 @@ Full registry: [workers.iii.dev](https://workers.iii.dev). Every worker there co
### LLM Providers
-agentmemory auto-detects from your environment. By default, no LLM calls are made unless you configure a provider or explicitly opt in to the Claude subscription fallback.
+agentmemory auto-detects providers from your environment. A provider makes LLM-backed operations available, but provider configuration alone does not enable LLM-written observation compression. That path requires both a provider and `AGENTMEMORY_AUTO_COMPRESS=true`.
| Provider | Config | Notes |
|----------|--------|-------|
-| **No-op (default)** | No config needed | LLM-backed compress/summarize is DISABLED. Synthetic BM25 compression + recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback. |
+| **No-op (default)** | No config needed | LLM-backed compress/summarize is disabled. Synthetic compression and BM25 recall still work. See `AGENTMEMORY_ALLOW_AGENT_SDK` below if you used to rely on the Claude-subscription fallback. |
| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |
| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
| Gemini | `GEMINI_API_KEY` | Also enables embeddings |
@@ -1326,11 +1512,11 @@ Qwen 3 models think by default and can burn the whole token budget on reasoning
Reasoning-class models (`o1`-style with `` blocks) can return empty `content` with a `reasoning` field your local server may not surface. If extractions come back blank, switch to a non-reasoning model first. The `OPENAI_REASONING_EFFORT=none` env can also disable thinking on Ollama Cloud thinking models that mirror the OpenAI reasoning schema.
-Local embeddings ship out of the box via `@huggingface/transformers`: `EMBEDDING_PROVIDER=local` (default) gives you `Xenova/all-MiniLM-L6-v2` (384-dim) entirely on-device. No extra config needed.
+Local embeddings ship as an optional dependency but are not enabled by default. Set `EMBEDDING_PROVIDER=local` to opt into `Xenova/all-MiniLM-L6-v2` (384-dim). The first embedding request downloads the model; inference is on-device afterward. Without that setting or a remote embedding key, vectors stay disabled, `mem::search` uses BM25, and `smart-search` can still add existing graph matches.
### Cost-aware model selection
-Background compression runs on every observation, so model choice meaningfully changes monthly spend. Captured workload data: 635 requests / 888K tokens / 35 hours of active use, run against three OpenRouter models at 2026-05-23 pricing.
+When LLM-written background compression is enabled with both a provider and `AGENTMEMORY_AUTO_COMPRESS=true`, it runs on every observation, so model choice meaningfully changes monthly spend. Captured workload data: 635 requests / 888K tokens / 35 hours of active use, run against three OpenRouter models at 2026-05-23 pricing.
| Tier | Model | Input / 1M | Output / 1M | Cost for the captured 35h | Notes |
|------|-------|------------|-------------|---------------------------|-------|
@@ -1382,9 +1568,13 @@ agentmemory + iii-engine bind four ports by default. If a restart fails with `po
| Port | Process | Purpose | Env override |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | Internal streams worker (consumed by agentmemory + viewer) | `III_STREAMS_PORT` |
-| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | `AGENTMEMORY_VIEWER_PORT` |
-| `49134` | iii-engine | WebSocket; workers register here, OTel telemetry flows over it | `III_ENGINE_URL` (full URL, default `ws://localhost:49134`) |
+| `3112` | iii-engine | Internal streams worker (consumed by agentmemory + viewer) | `III_STREAM_PORT` (preferred) or legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | `III_VIEWER_PORT` or `AGENTMEMORY_VIEWER_URL` for the reported URL |
+| `49134` | iii-engine | WebSocket; workers register here, OTel telemetry flows over it | `III_ENGINE_PORT` or `III_ENGINE_URL` |
+
+`--port ` changes the REST anchor and derives streams `N+1`, viewer `N+2`, and engine WebSocket `N+46023` only where the corresponding explicit port or URL above is unset. It does not create an isolated lifecycle namespace. Use `--instance 1` for a second daemon; it uses anchor 3211, defaults to `3211/3212/3213/49234`, and receives a separate `instance-1` data and lifecycle directory. Instances 1 through 50 follow the same pattern.
+
+The pinned engine starts with `--no-update-check` (no update or security-advisory lookups against GitHub at boot) and with iii's anonymous usage telemetry off: agentmemory sets `III_TELEMETRY_ENABLED=false` for the engine it spawns unless you export the variable yourself, and the bundled compose file does the same.
Stale-process cleanup when ports stay bound after a crashed run:
@@ -1399,7 +1589,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` reaps both the worker and the engine pidfile cleanly on graceful shutdown. In Docker mode it tears down only agentmemory's own compose services and reaps the native worker before the Docker teardown; the CLI also refuses to adopt or signal Docker or VM port holders (Docker backend, vpnkit, colima) as the native engine unless `--force` is passed. The manual cleanup above is only for the post-crash case where neither pidfile is left behind.
+`agentmemory stop` reaps both the worker and the engine pidfile cleanly on graceful native shutdown. In Docker mode it flushes the native worker, stops the exact validated engine container, and preserves both the container and its `/data` mount for a lossless restart; the next start validates and resumes that same container. Docker-backed uninstall requires `agentmemory remove --keep-data`: it removes shared agentmemory-managed files while preserving the validated container, its data mount, and the lifecycle record needed to recover them. Destructive Docker data deletion is intentionally left to the operator after a backup. The CLI also refuses to adopt or signal Docker or VM port holders (Docker backend, vpnkit, colima) as the native engine unless `--force` is passed. The manual cleanup above is only for the post-crash case where neither pidfile is left behind.
### Config File
@@ -1421,6 +1611,8 @@ AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
+LLM-written observation compression requires both lines: access to an LLM provider (including this explicit subscription fallback) and `AGENTMEMORY_AUTO_COMPRESS=true`. A provider by itself leaves the default synthetic compression path in place.
+
Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is configured. Explicitly opt out with `CONSOLIDATION_ENABLED=false` if you want LLM-free operation. Graph extraction is a separate flag:
```env
@@ -1467,13 +1659,15 @@ Create `~/.agentmemory/.env`:
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1491,14 +1685,20 @@ Create `~/.agentmemory/.env`:
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1546,6 +1746,36 @@ Create `~/.agentmemory/.env`:
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1559,7 +1789,19 @@ Create `~/.agentmemory/.env`:
-130 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer ` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
+138 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer `, and mesh sync endpoints require an explicitly set `AGENTMEMORY_SECRET` on both peers.
+
+**Authentication is on by default.** When `AGENTMEMORY_SECRET` is not set (in the shell or in `~/.agentmemory/.env`), the server generates a random secret on first start and stores it in `~/.agentmemory/secret` with mode `0600`. Every bundled client reads it from there when it talks to a local server: the CLI, the viewer, the hooks under `plugin/scripts`, the MCP server and the `@agentmemory/mcp` shim, the configs written by `agentmemory connect`, and the bundled OpenCode, Pi, OpenClaw, Hermes and filesystem-watcher integrations. The stored secret is only sent to loopback URLs (`localhost`, `127.0.0.0/8`, `::1`). An explicit `AGENTMEMORY_SECRET` always wins, and remote clients still need it set. Docker and the `deploy/` entrypoints already generate and export their own secret. To call the API by hand:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Request rules for writes.** `POST`, `PUT`, `PATCH` and `DELETE` requests to the REST API and the viewer must send `Content-Type: application/json` (a `charset` parameter is fine) whenever they carry a body, and an `Origin` header, when present, must be a loopback origin for the configured REST or viewer port or be listed in `VIEWER_ALLOWED_ORIGINS` (comma-separated, e.g. `https://memory.example.com`). Clients that send no `Origin` header (CLI, hooks, MCP, curl, server-to-server) are unaffected. The viewer also accepts its own origin.
+
+**File paths.** Endpoints that read or write files (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) only accept paths under `~/.agentmemory`, the instance data directory, or a directory listed in `AGENTMEMORY_IMPORT_ROOT` (separate several with `:`, or `;` on Windows). `/replay/import-jsonl` also accepts its default `~/.claude/projects`. `/obsidian/export` stays inside `AGENTMEMORY_EXPORT_ROOT` and `/migrate` inside `~/.agentmemory`. Symlinks are resolved before every check.
+
+**Secret scrubbing.** API keys, bearer tokens, PEM private key blocks and credentials embedded in URLs (`scheme://user:password@host`) are redacted before text is stored, on every write path: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, compression and summary output, crystals and graph nodes.
Key endpoints
@@ -1567,9 +1809,14 @@ Create `~/.agentmemory/.env`:
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check (always public) |
+| `GET` | `/agentmemory/status` | What is wrong and how to fix it (HTML for browsers, JSON otherwise) |
+| `GET` | `/agentmemory/viewer/snapshot` | Everything the viewer shows, in one response |
| `POST` | `/agentmemory/session/start` | Start session + get context |
| `POST` | `/agentmemory/session/end` | End session |
-| `POST` | `/agentmemory/observe` | Capture observation |
+| `POST` | `/agentmemory/observe` | Capture observation (see capture delivery below) |
+| `GET` | `/agentmemory/capture` | Capture inbox, dead letters and offline spool |
+| `POST` | `/agentmemory/capture/retry` | Retry dead-letter captures |
+| `POST` | `/agentmemory/capture/drain` | Send the local offline spool now |
| `POST` | `/agentmemory/smart-search` | Hybrid search |
| `POST` | `/agentmemory/context` | Generate context |
| `POST` | `/agentmemory/remember` | Save to long-term memory |
@@ -1579,6 +1826,7 @@ Create `~/.agentmemory/.env`:
| `GET` | `/agentmemory/export` | Export all data |
| `POST` | `/agentmemory/import` | Import from JSON |
| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
+| `POST` | `/agentmemory/graph/compact` | Trim oversized graph provenance |
| `POST` | `/agentmemory/team/share` | Share with team |
| `GET` | `/agentmemory/audit` | Audit trail |
@@ -1586,6 +1834,35 @@ Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts)
+**Capture delivery.** Hooks send each observation once to `POST /agentmemory/observe` with an `eventId`. It is the host's own id for the call when the payload has one (for example Claude Code's `tool_use_id`), otherwise a hash of the session, hook type, tool name, input, output and host timestamp. The server writes the event to a capture inbox in the state store, stores the observation, then removes the inbox entry. The status code says what happened:
+
+| Status | `status` field | Meaning |
+|---|---|---|
+| `201` | `accepted` | Stored. `observationId` is the new observation. |
+| `202` | `accepted` (`state: "retrying"`) | Accepted, but storing failed. The server retries it, also after a restart. |
+| `200` | `duplicate` | This `eventId` was already accepted. `observationId` is the existing observation; nothing new is stored. |
+| `400` / `422` | `rejected` | Invalid payload, or storing failed for good (the event is kept as a dead letter). |
+| `503` | `rejected` (`retryable: true`) | The inbox is full (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks spool the event and send it later. |
+
+Failed events are retried every `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) with doubling backoff, up to `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Events that still fail stay in the inbox as dead letters, are listed on `/agentmemory/status` and the viewer Health page, and can be retried with `POST /agentmemory/capture/retry` (`{"eventId": "..."}` or `{"all": true}`). Accepted event ids are remembered for `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 hours, at most `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), so a hook replayed after a timeout or a restart is stored once, while two separate tool calls with their own host ids are stored twice even when their content is identical. When an observation is deleted (forget, session delete, eviction, auto-forget or an import that replaces the store), its event is marked as deleted before the observation is removed, so a replay of that event inside the same window is answered as a duplicate and stores nothing. The state store writes to disk every 2 seconds, so an answered event can still be only in memory for a moment. To cover that, every `2xx` answer also carries the server's `bootId` (new at every start), `acceptedAt` and `durableAfterMs` (the save interval plus 1.5 s on the file store, 1.5 s on redis, where persistence is the operator's setting). Hooks keep the event in the local spool until that window has passed and delete it on a later call without another request. If the `bootId` has changed by then, the server restarted, so the hook sends the event again with the same `eventId`; an event that did reach the disk is not stored twice. The server also sends such events itself at start and every retry interval, so a restart loses nothing even when no hook runs afterwards. Older hooks ignore the extra fields, and new hooks against an older server discard the event on `2xx` as before.
+
+When the server is down, does not answer in time or returns a 5xx, the hook appends the observation to a local spool file, `/capture-spool/-.jsonl` (override the folder with `AGENTMEMORY_CAPTURE_SPOOL_DIR`). The file is private to your user (mode 600), secrets are redacted the same way the server redacts them, it holds at most `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) and drops entries older than `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). When it is full, new entries are dropped and counted, and `/agentmemory/status` reports it. The hook still exits 0 within its time limit and adds no request when the server is healthy. The spool is sent at the next start and by the first hook that reaches the server again, in a background process so the agent does not wait. Event ids make this safe: an observation that did arrive before a timeout is not stored twice. `npx @agentmemory/agentmemory capture` shows the spool and the server inbox, `--drain` sends the spool now, and `GET /agentmemory/capture` returns the same as JSON. Set `AGENTMEMORY_CAPTURE_SPOOL=false` to turn the spool off.
+
+**Compacting graph provenance.** Each knowledge graph node and edge keeps the ids of the newest 32 observations it came from. Stores written before that cap can hold thousands of ids per hot node, which makes graph search and the viewer slow or drops the worker. agentmemory fixes this by itself: on the first start after upgrading it trims every node, edge, superseded edge (the temporal graph history) and the cached snapshot to the cap in the background, in small slices with a pause between them, so search, capture and the viewer keep working. It saves its progress, resumes after a restart and never runs again once it has finished. `/agentmemory/status` and the viewer Health page show it as pending, running (with the current scope and position), done or failed. Set `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` to turn it off.
+
+To run it by hand, call `POST /agentmemory/graph/compact`. It walks the name and edge-key indexes instead of listing every node and edge, and is safe to re-run. When it trims ids it writes a `graph_compact` audit entry.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+On a large store, or when the call returns 504, run it in slices. Send `scope` (`nodes`, `edges` or `history`), `offset` and `limit`, then call again with the returned `nextOffset` until it is `null`. Do this for `nodes`, `edges` and `history`, and finish with one `{"scope":"snapshot"}` call, because a sliced run does not touch the cached snapshot.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1593,11 +1870,11 @@ Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**Prerequisites:** Node.js >= 20, [iii-engine](https://iii.dev/docs) or Docker
+**Prerequisites:** Node.js >= 20 with npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 or Docker. The macOS/Linux automatic engine install also requires `curl`, a POSIX `sh`, and `tar`; native Windows uses the manual pinned `iii.exe`, WSL2, or Docker Desktop.
diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.md
new file mode 100644
index 0000000000..ae107e1b53
--- /dev/null
+++ b/READMEs/README.ar-SA.md
@@ -0,0 +1,1876 @@
+
+
+
+
+
+
+ وكيل الترميز الخاص بك يتذكر كل شيء. لا حاجة لإعادة الشرح من جديد.
+ مبنيّ على iii engine
+
+ ذاكرة دائمة لـ Claude Code وGitHub Copilot CLI وCursor وGemini CLI وCodex CLI وHermes وOpenClaw وpi وOpenCode، ولأي عميل MCP.
+
+ يوسّع هذا الـ gist نمط LLM Wiki الذي صاغه Karpathy بإضافة تقييم الثقة، ودورة الحياة، والرسوم البيانية المعرفية، والبحث الهجين: و agentmemory هو تطبيق ذلك النمط.
+
+
+---
+
+## التثبيت
+
+المتطلبات:
+
+- يتطلب الأمر Node.js الإصدار 20 أو أحدث مع npm وnpx (تحقّق بـ `node -v` و`npm -v` و`npx -v`).
+- يحتاج التثبيت الآلي لـ iii-engine على macOS/Linux أيضًا إلى `curl` وصدفة POSIX من نوع `sh` وأداة `tar`. قد لا تتضمنها الصور الدنيا مثل `node:20-slim`.
+- يتطلب نظام Windows الأصلي تثبيت ملف `iii.exe` الخاص بالإصدار المثبَّت v0.22.1 من iii-engine يدويًا. أما WSL2 أو Docker Desktop فهما المساران المدعومان الآخران.
+
+أمر التثبيت الجديد المعياري:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+التشغيل الأول هو إعداد تفاعلي: تختار الوكلاء المراد ربطهم (Claude Code وCursor وCodex وGemini CLI وOpenCode، ...)، وتختار مزوّد LLM أو تبقى بلا مفتاح، فيقوم الإعداد بتوليد ملف التكوين، وتشغيل خادم الذاكرة ومحرك iii المثبَّت الخاص به، ويعرض عليك تثبيته عالميًا بحيث يعمل أمر `agentmemory` المجرد في كل مكان بعد ذلك. تقبل `-y` مطالبة npx بتثبيت الحزمة، وتتجنّب `@latest` إصدارًا قديمًا مخزَّنًا مؤقتًا. يُتيح المزوّد ميزات LLM، لكن ضغط الملاحظات المكتوب بواسطة LLM لا يبدأ إلا عند ضبط `AGENTMEMORY_AUTO_COMPRESS=true` أيضًا.
+
+يُعطّل وضع عدم استخدام المفاتيح تضمينات المتجهات. تستخدم `memory_recall` (مسار `mem::search`) خوارزمية BM25، في حين يمكن لـ `memory_smart_search` أيضًا دمج تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني مسبقًا. للحصول على استرجاع دلالي مجاني على الجهاز نفسه، اضبط `EMBEDDING_PROVIDER=local` في `~/.agentmemory/.env` وأعد التشغيل. يُنزِّل أول طلب تضمين النموذج `Xenova/all-MiniLM-L6-v2`؛ ويعمل الاستدلال محليًا بعد ذلك التنزيل الأولي للنموذج.
+
+تستخدم بيئة التشغيل المحلية أربعة منافذ: `3111` لـ REST/MCP HTTP، و`3112` لتيارات iii، و`3113` للعارض، و`49134` لمقبس WebSocket الخاص بعامل iii. تعيش حالة iii الدائمة في `~/Library/Application Support/agentmemory` على macOS، وفي `$XDG_DATA_HOME/agentmemory` أو `~/.local/share/agentmemory` على Linux، وفي `%APPDATA%\agentmemory` على Windows. استخدم `--data-dir ` أو `AGENTMEMORY_DATA_DIR` لتجاوز ذلك المسار، وأعد استخدام القيمة نفسها في كل إعادة تشغيل. للحفاظ على التوافق مع الإصدارات السابقة، يُعطى `./data/state_store.db` أو `./data/iii-config.yaml` الموجودان مسبقًا الأسبقية على المسار الافتراضي للنظام في النسخة 0؛ وتظل الراية الصريحة أو تجاوز متغيرات البيئة هي الأعلى أسبقية.
+
+بعد ذلك، تحقَّق من أن الاسترجاع يعمل، وأعطِ وكيلك مهاراته:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+ينبغي أن تُصيب عمليات البحث بالكلمات المفتاحية هدفها في وضع عدم استخدام المفاتيح الافتراضي عبر BM25. أما استعلام العرض التوضيحي `database performance optimization` فهو دلالي بالتصميم، ويمكن أن يعيد صفر نتائج إلى أن يُضبط مزوّد تضمين.
+
+تفضّل أن يقوم وكيل ترميز بتنفيذ العملية كاملة؟ أعطه تعليمة واحدة:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+اربط وكلاء إضافيين في أي وقت باستخدام `agentmemory connect ` — توجد 20 حزمة توصيل مُدرَجة في [يعمل مع كل وكيل](#works-with-every-agent). المرجع الكامل للأوامر في [البدء السريع](#quick-start).
+
+
+Windows
+
+المسار الأسرع هو WSL2. يتطلب إعداد المحرك على Windows الأصلي تنزيل أرشيف ZIP الخاص بالإصدار المثبَّت v0.22.1 واستخراج `iii.exe` يدويًا؛ فالواجهة الطرفية CLI لا تستخرجه تلقائيًا. كما يُدعم Docker Desktop أيضًا. راجع [ملاحظات Windows](#windows) للاطلاع على الخطوات التفصيلية.
+
+
+
+
+Global install / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+يظل أمر npx أعلاه هو المسار المعياري للتثبيت الجديد، وهو يتجنّب مشكلات أذونات بادئة التثبيت العالمية.
+
+
+
+
+npx يقدّم إصدارًا قديمًا
+
+يخزّن npx كل إصدار على حدة مؤقتًا. فرض استخدام الأحدث عبر `npx -y @agentmemory/agentmemory@latest`، أو مسح الذاكرة المؤقتة مرة واحدة بتشغيل `rm -rf ~/.npm/_npx` (على macOS/Linux؛ وعلى Windows احذف `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+لديك محرك iii خاص بك يعمل مسبقًا
+
+يُثبّت agentmemory الإصدار v0.22.1 من iii-engine تحديدًا، ولن يرتبط بإصدار مختلف (لأن العامل لا يستطيع التحدث ببروتوكول محرك آخر). أوقف المحرك الآخر، ثم شغّل `npx -y @agentmemory/agentmemory@latest`. سيثبّت ويشغّل الإصدار المثبَّت v0.22.1 في `~/.agentmemory/bin`، تاركًا نسخة `iii` الخاصة بك دون أي تغيير.
+
+
+
+---
+
+
+
+يعمل agentmemory مع أي وكيل يدعم الخطافات أو MCP أو REST API. يتشارك جميع الوكلاء خادم الذاكرة نفسه.
+
+
+ يعمل مع أي وكيل يتحدث MCP أو HTTP. خادم واحد، والذكريات مشتركة بين جميعها.
+
+
+---
+
+أنت تشرح نفس البنية المعمارية في كل جلسة. وتعيد اكتشاف نفس الأخطاء مرارًا. وتُعلِّم نفس التفضيلات من جديد. تتوقف الذاكرة المدمجة (CLAUDE.md، .cursorrules) عند حد 200 سطر وتصبح قديمة بمرور الوقت. يحل agentmemory هذه المشكلة. فهو يلتقط بصمت ما يفعله وكيلك، ويضغطه في ذاكرة قابلة للبحث، ويحقن السياق المناسب عند بدء الجلسة التالية. أمر واحد فقط. ويعمل عبر الوكلاء كافة.
+
+**ما الذي يتغيّر:** في الجلسة 1 تُعِدّ مصادقة JWT. وفي الجلسة 2 تطلب تحديد معدل الطلبات (rate limiting). يعرف الوكيل مسبقًا أن مصادقتك تستخدم وسيط jose في `src/middleware/auth.ts`، وأن اختباراتك تغطي التحقق من الرمز (token)، وأنك اخترت jose بدلًا من jsonwebtoken لتوافقه مع Edge، دون أي إعادة شرح أو نسخ ولصق.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+افتراضيًا، يخزّن agentmemory حالة iii-engine خارج المستودع الذي تشغّله منه: في `~/Library/Application Support/agentmemory` على macOS، وفي `$XDG_DATA_HOME/agentmemory` أو `~/.local/share/agentmemory` على Linux، وفي `%APPDATA%\agentmemory` على Windows. ويُعاد استخدام `./data/state_store.db` أو `./data/iii-config.yaml` القديمين إن وُجدا للنسخة 0 قبل الاعتماد على ذلك المسار الافتراضي للنظام. لاختيار موقع محدد صريحًا، مرّر `--data-dir ` أو اضبط `AGENTMEMORY_DATA_DIR`؛ وأيٌّ من هذين الضبطين الصريحين يسبق آلية الاكتشاف القديمة في الأولوية:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+تستخدم عمليات التشغيل الأصلية (native) وعبر Docker نفس دليل المضيف المُحلَّل؛ ويربطه Docker (bind-mount) عند `/data`. يُضيف الخيار `--instance 1` اللاحقة `instance-1` إلى الدليل المُحلَّل، ويختار رباعية المنافذ الافتراضية المستقلة `3211/3212/3213/49234`.
+
+ملاحظات آخر إصدار: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### دقة الاسترجاع
+
+**coding-agent-life-v1** (مجموعة بيانات داخلية، قابلة لإعادة الإنتاج في بيئة معزولة)
+
+| المحوّل | P@5 | R@5 | معدل الإصابة ضمن أفضل 5 | زمن الاستجابة p50 |
+|---|---|---|---|---|
+| **agentmemory الهجين** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| خط أساس grep | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+معدل إصابة 100% ضمن أفضل 5 عند **سقف P@5 الرياضي** لهذه المجموعة (0.240، راجع بطاقة النتائج). يسترجع النظام الهجين كل جلسة مرجعية (gold)؛ بينما يفوّت grep جلسة واحدة من جلستين مرجعيتين في الاستعلام الزمني متعدد الجلسات. التحسّن هنا في **الاسترجاع + البعد الزمني**، لا في الدقة الكلية. هذا المقياس صغير وقليل الجلسات المرجعية؛ ويميّز المقياس الأكبر LongMemEval-S أدناه بشكل أفضل. التفصيل الكامل حسب النوع وملاحظة التصحيح: [`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% |
+
+
+
+> نموذج التضمين: `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 وsupermemory وTencentDB Agent Memory وMemPalace وZep/Graphiti وCognee و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).** فهرسة الرسم البياني للشفرة (code-graph)، وخطوط بناء متعددة الوكلاء، ورسوم بيانية معرفية أوسع تمتد عبر المستندات/ملفات PDF/الصور/الفيديوهات. يتذكّر agentmemory العمل؛ وتُضيء هذه المشاريع الثلاثة بقية طبقة السياق. الوصفات وجدول توجيه الأسئلة: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
مدمج (CLAUDE.md)
+
+
+
النوع
+
محرك ذاكرة + خادم MCP
+
واجهة برمجية لطبقة الذاكرة
+
بيئة تشغيل كاملة للوكيل
+
ذكاء اصطناعي شخصي
+
واجهة برمجية للذاكرة + تطبيق
+
محور ذاكرة جماعي (وكيل LLM وسيط)
+
ذاكرة متجهية (مفتوحة المصدر)
+
محرك ذاكرة (قاعدة بيانات Oracle)
+
نظام ذاكرة
+
ملف ثابت
+
+
+
دقة الاسترجاع R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
غير متوفر
+
مُعلَن من الشركة نفسها
+
PersonaMem 76% (مُعلَن من الشركة نفسها)
+
~96.6% (مُعلَن من الشركة نفسها)
+
94.4% (مُعلَن من الشركة نفسها)
+
غير متوفر
+
غير متوفر (grep)
+
+
+
الالتقاط التلقائي
+
12 خطافًا (بلا أي جهد يدوي)
+
استدعاءات add() يدوية
+
تعديلات ذاتية من الوكيل
+
يدوي
+
استخراج من جانب الواجهة البرمجية
+
اعتراض عبر وكيل وسيط (باستبدال base-URL)
+
يدوي
+
استخراج عبر API
+
يدوي
+
تعديل يدوي
+
+
+
البحث
+
BM25 + المتجهات + الرسم البياني (دمج RRF)
+
المتجهات + الرسم البياني
+
متجهات (أرشيفية)
+
دلالي
+
متجهات + RAG
+
4 أنواع من الأصول (محادثة / مهارة / Wiki / CodeGraph)
+
متجهات فقط
+
متجهات + دلالي
+
مرجَّح بالتلاشي
+
يحمّل كل شيء إلى السياق
+
+
+
تعدد الوكلاء
+
MCP + REST + حجوزات (leases) + إشارات
+
API (بلا تنسيق)
+
داخل بيئة تشغيل Letta فقط
+
لا
+
لا
+
أدوار جماعية + أصول مشتركة
+
لا
+
محدود النطاق فقط
+
مشترك بين وكلاء متعددين
+
ملفات لكل وكيل على حدة
+
+
+
الارتهان لإطار عمل محدد
+
لا يوجد (أي عميل MCP)
+
لا يوجد
+
مرتفع (يجب استخدام Letta)
+
مستقل
+
لا يوجد
+
وكيل وسيط يتقدّم كل استدعاء للنموذج
+
لا يوجد
+
Oracle Database
+
لا يوجد
+
تنسيق خاص بكل وكيل
+
+
+
الاعتماديات الخارجية
+
لا يوجد (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + قاعدة بيانات متجهية
+
متعددة
+
سحابة مُدارة
+
حزمة Docker (Core + Hub + Proxy)
+
مخزن متجهات
+
Oracle AI Database
+
لا يوجد
+
لا يوجد
+
+
+
دورة حياة الذاكرة
+
توحيد رباعي المستويات + تلاشي + نسيان تلقائي
+
استخراج سلبي (passive)
+
يديرها الوكيل
+
يدوي
+
نسيان تلقائي
+
مراجعة يدوية؛ والتوجيه التلقائي قيد التطوير
+
لا يوجد
+
غير مُحدَّد
+
تلاشي + توحيد
+
تقليم يدوي
+
+
+
كفاءة استخدام الرموز
+
~1,900 رمز/جلسة (10$/سنويًا)
+
يتفاوت حسب التكامل
+
الذاكرة الأساسية داخل السياق
+
متفاوت
+
تسعير سحابي
+
غير مُحدَّد
+
بلا حد لعدد الرموز
+
معتمد على LLM (متفاوت)
+
متفاوت
+
أكثر من 22K رمز عند 240 ملاحظة
+
+
+
العارض اللحظي
+
نعم (المنفذ 3113)
+
لوحة تحكم سحابية
+
لوحة تحكم سحابية
+
واجهة ويب
+
لوحة تحكم سحابية
+
واجهة ويب للمحور (Hub)
+
لا
+
لا
+
لا
+
لا
+
+
+
استضافة ذاتية
+
نعم (افتراضيًا)
+
اختياري
+
اختياري
+
نعم
+
لا (سحابي فقط)
+
نعم (Docker)
+
نعم
+
نعم (Oracle DB)
+
نعم
+
نعم
+
+
+
+ملاحظة على المقياس: نتيجة R@5 الخاصة بـ agentmemory فقط هي قياسنا الفعلي (LongMemEval-S، قابلة لإعادة الإنتاج من benchmark/COMPARISON.md). أما أرقام mem0 وLetta فهي أرقامهما المنشورة على LoCoMo (مجموعة بيانات مختلفة)؛ وأرقام MemPalace وsupermemory وTencentDB (PersonaMem) وoracleagentmemory هي ادعاءات مُعلَنة من الشركات نفسها لم نُعِد إنتاجها بشكل مستقل (استخدمت عملية تشغيل oracleagentmemory نموذج GPT-5.5 مقابل قاعدة بيانات Oracle AI Database). عُرضت جنبًا إلى جنب للمقارنة التقريبية فقط، لا كمواجهة مباشرة على بيانات متطابقة. أعداد النجوم تقريبية وتتغير مع الوقت.
+
+**داخلون جدد** تستحق المعرفة، مع مقارنة تفصيلية في [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| النظام | ⭐ | الزاوية |
+|--------|---|-------|
+| Zep / Graphiti | 30K | رسم بياني معرفي زمني؛ يملك أقوى نتائج منشورة للاستعلامات الزمنية (LongMemEval 63.8%)، لكن بناء الرسم البياني يتم بشكل غير متزامن، فقد تتأخر الحقائق الجديدة |
+| Cognee | 30K | استيعاب يحوّل المستندات إلى رسم بياني معرفي، مخصص لـ Python فقط، ومبني لاستخراج الكيانات البنيوية لا لالتقاط الجلسات |
+
+لا يلتقط أي منها تلقائيًا من خطافات وكيل الترميز، ولا يقدّم عارضًا يُبنى أولاً للتشغيل المحلي، ولا يعمل بلا مفتاح — وهذا المزيج هو ما بُني agentmemory حوله.
+
+---
+
+
+
+التوافق: يستهدف هذا الإصدار `iii-sdk` بالإصدار 0.22.1، ويثبّت iii-engine على الإصدار v0.22.1.
+
+### جرّبه في 30 ثانية
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+يُنشئ أمر `demo` ثلاث جلسات واقعية (مصادقة JWT، إصلاح استعلام N+1، تحديد معدل الطلبات) ويُجري عمليات بحث عليها. تُعطّل عمليات التثبيت بلا مفاتيح المتجهات، لذا ينبغي أن تُصيب استعلامات `mem::search` بالكلمات المفتاحية هدفها عبر BM25، في حين يمكن أن يعيد `database performance optimization` صفر نتائج. وقد يُعيد `smart-search` أيضًا تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني. لجعل الاستعلام الدلالي يعثر على إصلاح N+1 عبر المتجهات، اضبط `EMBEDDING_PROVIDER=local`، وأعد التشغيل، واسمح لأول تنزيل للنموذج بأن يكتمل.
+
+افتح `http://localhost:3113` لمشاهدة بناء الذاكرة مباشرةً.
+
+### التحقق من تثبيت جديد واستمرارية البيانات بعد إعادة التشغيل
+
+مع تشغيل الخادم، تحقّق من REST، والحالة الصحية (health)، والعارض، وحالة بيئة التشغيل المعتمدة على iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+تغطي لوحة الجاهزية عند بدء التشغيل جميع المنافذ الأربعة: REST/MCP HTTP على 3111، وتيارات iii على 3112، والعارض على 3113، ومقبس WebSocket الخاص بعامل iii على 49134. يؤكد أمر `status` سلامة agentmemory ووضع المزوّد/التضمين النشط. احفظ عيّنة اختبار (probe) وتأكّد من إمكانية البحث عنها:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+ثم شغّل `npx -y @agentmemory/agentmemory@latest stop`، وأعد تشغيل الأمر المعياري من جديد في الطرفية 1، وانتظر استجابة `/agentmemory/livez`، وكرِّر عملية البحث. يجب أن تظل عيّنة الاختبار مُستردَّة. إذا اخترت مسار `--data-dir` مخصصًا، مرّر الدليل نفسه عند إعادة التشغيل.
+
+### أوامر الاستخدام اليومي
+
+تعليمات التثبيت والإعداد موجودة في [التثبيت](#install) أعلاه (يرشدك التشغيل الأول خلالها). في الاستخدام اليومي:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### إعادة تشغيل الجلسة (Session Replay)
+
+كل جلسة يسجّلها agentmemory قابلة لإعادة التشغيل. افتح العارض، واختر تبويب **Replay**، وتجوّل عبر خط الزمن: تُعرض المطالبات، واستدعاءات الأدوات، ونتائجها، والردود كأحداث منفصلة مع إمكانية تشغيل/إيقاف مؤقت، والتحكم بالسرعة (من 0.5x إلى 4x)، واختصارات لوحة المفاتيح (مسافة للتبديل، والأسهم للتنقل خطوة بخطوة).
+
+لاستيراد محاضر JSONL أقدم من Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+تظهر الجلسات المستوردة في قائمة اختيار Replay جنبًا إلى جنب مع الجلسات الأصلية. تحت الغطاء، يمر كل إدخال عبر دوال iii: `mem::replay::load` و`mem::replay::sessions` و`mem::replay::import-jsonl`، دون أي خوادم جانبية. تُفهرس كل محضر مستورد للبحث، ويُختم بقناة المصدر `import`، ويُستخرج منه بلورة جلسة (crystal) ودروس مستفادة (lessons).
+
+> **تنبيه إذا كنت تعتمد على `import-jsonl` كمسارك الأساسي للالتقاط:** يحذف إعداد `cleanupPeriodDays` الخاص بـ Claude Code (في `~/.claude/settings.json`، والافتراضي **30**) تلقائيًا محاضر JSONL الأقدم من تلك النافذة الزمنية من `~/.claude/projects/`. إذا ثبّت agentmemory حديثًا على سجل Claude Code يمتد لعدة أشهر، فإن كل ما هو أقدم من 30 يومًا يكون قد اختفى مسبقًا قبل أول استيراد. إما أن تشغّل `import-jsonl` عبر مهمة cron، أو ترفع قيمة `cleanupPeriodDays` إلى رقم أعلى، أو تربط خطافات الالتقاط التلقائي (مسار تثبيت الإضافة الافتراضي) حتى تصل كل مداولة إلى agentmemory والجلسة لا تزال نشطة، فلا يعود تنظيف JSONL ذا أهمية.
+
+### الترقية / الصيانة
+
+استخدم أمر الصيانة عندما تريد عمدًا تحديث بيئة التشغيل المحلية لديك:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+تحذير: يُغيّر هذا الأمر مساحة العمل/بيئة التشغيل الحالية. فقد يُحدِّث اعتماديات JavaScript ويسحب صورة Docker المثبَّتة `iiidev/iii:0.22.1`. ولن يُثبّت مطلقًا محرك iii غير مثبَّت الإصدار أو أحدث منه.
+
+تفاصيل التنفيذ موجودة في `src/cli.ts` (راجع `runUpgrade` حول نطاق `src/cli.ts:544-595`).
+
+### Claude Code (كتلة واحدة، الصقها)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code بدون تثبيت الإضافة (مسار MCP القائم بذاته)
+
+إذا ربطت خادم MCP الخاص بـ agentmemory عبر `~/.claude.json` مباشرة بدلًا من استخدام `/plugin install`، فإن Claude Code لن يحلّ `${CLAUDE_PLUGIN_ROOT}` مطلقًا، وستحتاج إلى توجيه نصوص الخطافات إلى مسارات مطلقة في `~/.claude/settings.json`. وتُضمِّن تلك المسارات عادة إصدار agentmemory (مثل `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`)، فتنكسر جميع الخطافات بصمت عند الترقية التالية.
+
+الحل البديل:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+يُدمج هذا الأمر نفس أوامر الخطافات في `~/.claude/settings.json` بمسارات مطلقة تُحلَّل إلى دليل `plugin/` المُضمَّن في حزمة `@agentmemory/agentmemory` المثبَّتة حاليًا. أعد تشغيل الأمر بعد ترقية agentmemory لتحديث المسارات. تُحفظ إدخالات المستخدم في نفس الملف؛ ويُستبدل إدخالات agentmemory السابقة فقط. يظل استخدام مسار `/plugin install` هو الأسلوب المُوصى به.
+بالنسبة للنشر عن بُعد أو المحمي، شغّل Claude Code مع ضبط `AGENTMEMORY_URL` و`AGENTMEMORY_SECRET`. تُمرّر الإضافة كلتا القيمتين إلى خادم MCP المُضمَّن بها؛ وعندما يكون `AGENTMEMORY_URL` فارغًا، يستخدم وسيط MCP (shim) عنوان `http://localhost:3111`.
+
+### Codex CLI (منصة إضافات Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+تُشحن إضافة Codex من نفس دليل `plugin/` الذي تُشحن منه إضافة Claude Code. وهي تُسجِّل:
+
+- جسر MCP مُضمَّن من نوع stdio إلى العفريت (daemon) العامل، دون تنزيل npm أو مخزن احتياطي (fallback). راجع [دليل Codex المحلي](../docs/plugins/codex-local.md) لاختبار إصدار (build) غير منشور.
+- 6 خطافات لدورة الحياة: `SessionStart` و`UserPromptSubmit` و`PreToolUse` و`PostToolUse` و`PreCompact` و`Stop`
+- 9 مهارات قابلة للاستدعاء: `/recall` و`/remember` و`/session-history` و`/forget` و`/recap` و`/handoff` و`/lesson` و`/commit-context` و`/commit-history`، بالإضافة إلى 8 مهارات مرجعية يُحمّلها الوكيل عند الطلب (انضباط الذاكرة، وأدوات MCP، وواجهة REST API، والإعدادات، والوكلاء، والخطافات، والبنية المعمارية، ودليل تأليف المهارات)
+
+يحقن محرك خطافات Codex متغيّر `CLAUDE_PLUGIN_ROOT` في العمليات الفرعية للخطافات (حسب [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs))، لذا تعمل نصوص الخطافات نفسها على كلتا البيئتين دون تكرار. أما أحداث Subagent وSessionEnd وNotification وTaskCompleted وPostToolUseFailure فهي خاصة بـ Claude Code فقط، ولا تُسجَّل في Codex.
+
+#### ثقة خطافات Codex والتوافق
+
+تم التحقق من إرسال خطافات الإضافة الأصلية (native) مع Codex CLI 0.150.1. ثِق بخطافات الإضافة قبل أن تتوقع الالتقاط (capture). يعتمد سلوك Desktop على وقت التشغيل (runtime) المُضمَّن فيه؛ تحقّق من `/hooks` وتأكّد من التقاط حدث قبل تفعيل حل بديل.
+
+إذا كان المضيف (host) الخاص بك يتطلب خطافات عامة (global)، فاعكس الأوامر إلى `~/.codex/hooks.json`. وعندما يكون MCP موصولًا بالفعل، يحتاج المحوّل الحالي إلى `--force` للوصول إلى تثبيت الخطافات:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+يدمج هذا الخطافات العامة (global) ويعيد كتابة إدخال agentmemory MCP، مع الحفاظ على الإدخالات غير المرتبطة. راجع أي إعدادات نقطة نهاية (endpoint) مخصصة لـ agentmemory قبل استخدام `--force`. أعد التشغيل بعد الترقية لتحديث مسارات النصوص. فعِّل خطافات الإضافة الأصلية أو النُّسخ العامة لتجنّب الالتقاط المكرر.
+
+### GitHub Copilot CLI
+
+لوضع الوكيل (agent mode) في VS Code، استخدم [دليل Copilot MCP والالتقاط التلقائي](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). لا يضبط محوّل CLI إعدادات VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+يُدمج أمر `agentmemory connect copilot-cli` مفتاح `mcpServers.agentmemory` في `~/.copilot/mcp-config.json` (أو في `$COPILOT_HOME/mcp-config.json` عند ضبط `COPILOT_HOME`)، ويحافظ على الخوادم الموجودة مسبقًا. على Windows الأصلي، هذا هو محوّل `connect` الآلي الوحيد؛ أما بقية وكلاء Windows الأصليين فيجب ضبطهم يدويًا. ولا يُدعم `connect` عبر WSL إلا عندما يكون الوكيل المستهدف مثبَّتًا في بيئة WSL نفسها. يلتقط Copilot خادم MCP عند التشغيل التالي أو بعد تنفيذ `/mcp`. ثبّت الإضافة أيضًا إذا رغبت في تجربة الخطافات/المهارات الكاملة.
+
+
+OpenClaw (الصق هذا الموجّه)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+الدليل الكامل: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+وكيل Hermes (الصق هذا الموجّه)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+الدليل الكامل: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### وكلاء آخرون
+
+شغّل خادم الذاكرة: `npx -y @agentmemory/agentmemory@latest`
+
+#### المهارات الأصلية عبر `npx skills add` (أكثر من 50 وكيلًا)
+
+يشحن agentmemory 17 مهارة بتنسيق `/SKILL.md` على طراز Claude Code: 9 مهارات فعل قابلة للاستدعاء (`remember` و`recall` و`recap` و`handoff` و`forget` و`lesson` و`commit-context` و`commit-history` و`session-history`) و8 مهارات مرجعية يُحمّلها الوكيل عند الطلب (`memory-discipline` و`agentmemory-mcp-tools` و`agentmemory-rest-api` و`agentmemory-config` و`agentmemory-agents` و`agentmemory-hooks` و`agentmemory-architecture` و`write-agentmemory-skill`). تحمل المهارات المرجعية جداول بيانات مُولَّدة من المصدر، فلا تنحرف عنه أبدًا. تقوم واجهة سطر الأوامر [`skills`](https://npmjs.com/package/skills) من vercel-labs بتثبيتها آليًا في دليل المهارات الأصلي للوكيل المستدعي عبر أكثر من 50 وكيلًا (Claude Code وCursor وCline وContinue وDroid وWarp وCodex وAntigravity وKiro وOpenCode وGoose وRoo وTrae وWindsurf، وغيرها):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+هذا **مُكمِّل** لأمر `agentmemory connect `:
+
+- يكتب `agentmemory connect ` إعدادات خادم MCP بحيث تصبح الأدوات متاحة.
+- يُثبّت `npx skills add rohitg00/agentmemory` المهارات بحيث يعرف الوكيل متى يستدعيها.
+
+بالنسبة للوكلاء القليلين الذين لا تغطيهم واجهة سطر الأوامر skills بعد (Zed بالإصدار v1.3.x وما قبله)، ضع ملفات SKILL.md الـ17 بنفسك تحت دليل المهارات الأصلي للوكيل؛ فالتنسيق نفسه يعمل في كل مكان.
+
+#### كتلة MCP القياسية
+
+إدخال agentmemory هو **كتلة خادم MCP نفسها** في كل مضيف يستخدم شكل `mcpServers` (Cursor وClaude Desktop وCline وRoo Code وGemini CLI وOpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**ادمج هذا الإدخال في كائن `mcpServers` الموجود مسبقًا** في ملف إعدادات المضيف؛ لا تستبدل الملف بالكامل. إذا كان الملف يحتوي على خوادم أخرى مسبقًا، أضف `agentmemory` بجانبها كمفتاح آخر داخل `mcpServers`. وإذا كان `mcpServers` غير موجود بالمرة، الصق الكتلة داخل `{ "mcpServers": { ... } }`. تستمد العناصر النائبة `${VAR}` قيم `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` من الصدفة (shell) عند تشغيل خادم MCP؛ وتُمرِّر المتغيرات غير المضبوطة نصًا فارغًا، فيعود الوسيط (shim) إلى `http://localhost:3111`. يغطي إدخال واحد مُهيَّأ كلًا من النشر المحلي والبعيد (k8s / عبر وكيل عكسي).
+
+| الوكيل | ملف الإعدادات | ملاحظات |
+|---|---|---|
+| **Cursor (MCP فقط)** | `~/.cursor/mcp.json` | ادمج داخل `mcpServers`، أو استخدم `agentmemory connect cursor`. يتوفر أيضًا رابط تفعيل بنقرة واحدة (deeplink) على الموقع. |
+| **Cursor (الإضافة الكاملة)** | `.cursor-plugin/` | قائمة في Cursor Marketplace (الطلب قيد المراجعة) أو عبر Cursor Settings ← Plugins ← نسخة محلية. تُسجِّل 7 خطافات التقاط تلقائي (sessionStart و beforeSubmitPrompt و preToolUse و postToolUse و postToolUseFailure و stop و sessionEnd) + 17 مهارة + خادم MCP، مع إدارة `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` من لوحة إضافات Cursor. يعمل في بيئة Cursor IDE وفي واجهة `cursor-agent` CLI؛ وتُستكمل مطالبات وضع الطباعة في CLI من محضر الجلسة عند انتهائها. |
+| **Claude Desktop** | `claude_desktop_config.json` (في Application Support) | ادمج داخل `mcpServers`. أعد تشغيل Claude Desktop بعد التعديل. |
+| **Cline / Roo Code / Kilo Code** | إعدادات MCP في Cline (واجهة Settings ← MCP Servers ← Edit) | نفس كتلة `mcpServers`. |
+| **Devin CLI (MCP + خطافات)** | `~/.config/devin/config.json` | يدمج `agentmemory connect devin` إدخال MCP؛ ويضيف `--with-hooks` ستة خطافات التقاط تلقائي أصلية (SessionStart و UserPromptSubmit و PreToolUse و PostToolUse و Stop و SessionEnd) مع مطابقات أدوات Devin بالحروف الصغيرة. تحقّق باستخدام `devin mcp list` وأمر `/hooks` داخل devin. |
+| **Devin CLI (الإضافة الكاملة)** | `plugin/.devin-plugin/` | يُسجِّل أمر `devin plugins install ./plugin` من نسخة محلية جميع المهارات الـ17 كأوامر شرطة `/agentmemory:` إضافة إلى خادم MCP. لا يمكن لخطافات إضافة Devin إطلاق `SessionStart`/`SessionEnd`، فاجمعها مع `connect devin --with-hooks` للحصول على التقاط كامل للجلسة. |
+| **Devin (السحابة)** | Settings ← Connections ← MCP servers | أضف MCP مخصصًا (STDIO): الأمر `npx`، والوسائط `-y @agentmemory/mcp@latest`، ومتغير البيئة `AGENTMEMORY_URL` يشير إلى نشر agentmemory يمكن الوصول إليه عبر الشبكة، إضافة إلى `AGENTMEMORY_SECRET` (لا يمكن لجلسات السحابة الوصول إلى localhost — راجع [`deploy/`](../deploy/)). خزّن السر في Devin Secrets، ثم استخدم "Test listing tools" للتحقق من ظهور جميع الأدوات الـ54. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (يدمج تلقائيًا). |
+| **GitHub Copilot CLI (MCP فقط)** | `~/.copilot/mcp-config.json` | يدمج `agentmemory connect copilot-cli` مفتاح `mcpServers.agentmemory`؛ ويلتقطه Copilot عند التشغيل التالي أو عبر `/mcp`. |
+| **GitHub Copilot CLI (الإضافة الكاملة)** | تثبيت إضافة Copilot | `copilot plugin install rohitg00/agentmemory:plugin` لتثبيت الإضافة من الدليل الفرعي على GitHub. |
+| **OpenClaw** | إعدادات MCP في OpenClaw | نفس كتلة `mcpServers`. للتكامل الأعمق: يستحوذ `openclaw plugins install ./integrations/openclaw` على فُتحة الذاكرة (memory slot) في OpenClaw (ينتقل تلقائيًا من `memory-core`)؛ اضبط `plugins.entries.agentmemory.hooks.allowConversationAccess=true` وإلا يُحجب التقاط المداولة بصمت. راجع [`integrations/openclaw`](../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 خطافات دورة حياة + 17 مهارة. ثِق بالخطافات وتحقّق من الالتقاط في مضيفك (host)؛ راجع [إعداد Codex والتحقق منه](../docs/plugins/codex-local.md). |
+| **OpenCode (MCP فقط)** | `opencode.json` | بصيغة مختلفة: مفتاح `mcp` على المستوى الأعلى، والأمر كمصفوفة: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (الإضافة الكاملة)** | `plugin/opencode/` | 22 خطاف التقاط تلقائي تغطي دورة حياة الجلسة والرسائل والأدوات والأخطاء. ويُحدَّد المشروع لكل جلسة على حدة، فعملية OpenCode واحدة تمتد عبر عدة مستودعات تُسجِّل كل جلسة تحت مشروعها الخاص بها. أمرا شرطة اثنان (`/recall` و`/remember`). انسخ `plugin/opencode/` إلى مساحة عمل OpenCode الخاصة بك وأضف إدخال الإضافة إلى `opencode.json`. راجع [`plugin/opencode/README.md`](../plugin/opencode/README.md) للحصول على جدول الخطافات الكامل وتحليل الثغرات. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | يُثبّت `agentmemory connect pi` الإضافة المُضمَّنة في دليل الاكتشاف التلقائي لـ pi (استرجاع عند بدء الوكيل، والتقاط عند انتهائه، وأدوات `memory_search` / `memory_save` / `memory_health`، و`/agentmemory-status`). يلتقطها أمر `/reload` في pi قيد التشغيل. كما أن [`integrations/pi`](../integrations/pi/) حزمة pi أيضًا (`pi install ./integrations/pi` من نسخة محلية). |
+| **وكيل Hermes** | `~/.hermes/config.yaml` | يمنحك `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` مزوّد ذاكرة بستة خطافات (جلب مسبق، والتقاط المداولة، وانتهاء الجلسة، وما قبل الضغط، ومرآة لـ MEMORY.md، وكتلة موجّه النظام). تحقّق باستخدام `hermes plugins doctor` و`hermes memory status`. راجع [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | يكتب `agentmemory connect qwen` كتلة `mcpServers` القياسية. حمولة الخطاف متوافقة الحقول مع Claude Code، فتعمل نصوص الخطافات الـ12 الموجودة دون أي تعديل؛ اربطها عبر قسم `hooks` في نفس ملف `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | يُثبِّت `agentmemory connect antigravity --with-hooks` خطافات MCP والالتقاط في دليل التخصيص (customization) المشترك. راجع [إعداد Antigravity وحدوده](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | يستخدم `agentmemory connect antigravity-cli --with-hooks` نفس إعدادات MCP والخطافات المستخدمة في إصدارات IDE الحالية. ينبغي للتثبيتات الحالية التحديث باستخدام `--force`؛ راجع [ملاحظات الترقية](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | يكتب `agentmemory connect kiro` الإعدادات على مستوى المستخدم. وتوضع تجاوزات مساحة العمل في `.kiro/settings/mcp.json` بجانب شفرتك. |
+| **Warp** | `~/.warp/.mcp.json` | يكتب `agentmemory connect warp` كتلة `mcpServers` القياسية. يكتشف Warp أيضًا المهارات تلقائيًا من `.claude/skills/`؛ وبمجرد تثبيت إضافة Claude Code، تظهر مهارات agentmemory الثماني (`remember` و`recall` و`recap` و`handoff` و`forget` و`commit-context` و`commit-history` و`session-history`) أصليًا في لوحة أوامر الشرطة في Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | يكتب `agentmemory connect cline` كتلة `mcpServers` القياسية. لمستخدمي إضافة VS Code: الصق الكتلة نفسها عبر Cline Settings ← MCP Servers ← Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (مفضّل) أو `config.json` (قديم) | يُنشئ `agentmemory connect continue` ملف `config.yaml` من الصفر إن لم يوجد أي منهما، أو يُعدِّل `config.json` الموجود مسبقًا. **إذا كان لديك `config.yaml` مسبقًا**، يطبع المحوّل الكتلة الدقيقة لتلصقها تحت `mcpServers:`؛ ولن يُعيد كتابة ملف yaml بصمت لأن الحفاظ الآمن على التعليقات والمراسي يتطلب مُحلِّل YAML لا تشحنه الحزمة. يستخدم Continue الصيغة المصفوفية (لا الكائنية) لـ `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | يكتب `agentmemory connect zed` تحت `context_servers` (مفتاح Zed الخاص، وليس `mcpServers`). يمكن ربط خوادم MCP البعيدة بدلًا من ذلك عبر `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | يكتب `agentmemory connect droid` كتلة `mcpServers` القياسية. وتوضع تجاوزات نطاق المشروع في `/.factory/mcp.json`. مرّر `--with-hooks` لالتقاط تلقائي أصلي. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | يُضيف `agentmemory connect dsh` صفًا من نوع `@deepseek-ai/dsh-mcp-client` إلى طبقة الترقيع على مستوى الدليل الرئيسي التي يحمّلها كل ملف تعريف في Harness؛ وتُسجَّل الأدوات بصيغة `mcp__agentmemory__*`. مرّر `--with-hooks` لربط الالتقاط التلقائي أيضًا: تعمل نصوص خطافات Claude Code المُضمَّنة عبر جسر `@deepseek-ai/dsh-hooks-claude-code` الأصلي الخاص بـ Harness (SessionStart و UserPromptSubmit و PreToolUse و PostToolUse و Stop) من خلال بيان يُكتب في `$DSH_HOME/agentmemory.hooks.json`. يُستخدم `~/.dsh` افتراضيًا عندما لا يكون `DSH_HOME` مضبوطًا. |
+| **Goose** | واجهة إعدادات MCP في Goose | نفس كتلة `mcpServers`؛ استخدم `goose configure` ← Add Extension ← MCP. يُدعم التعديل المباشر لملف YAML في `~/.config/goose/config.yaml`، لكن المخطط يستخدم `extensions:` + `cmd` (وليس `mcpServers:` + `command`). |
+| **Aider** | لا ينطبق | تحدَّث مباشرة مع REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **أي وكيل (أكثر من 32)** | لا ينطبق | يكتشف `npx skillkit install agentmemory` المضيف تلقائيًا ويدمج الإعدادات. |
+
+**عملاء MCP المحتجزون في بيئة معزولة (sandbox)** (Flatpak / Snap / الحاويات المقيَّدة) الذين لا يمكنهم الوصول إلى `localhost` الخاص بالمضيف: اضبط أيضًا `"AGENTMEMORY_FORCE_PROXY": "1"` في كتلة `env`، ووجِّه `AGENTMEMORY_URL` إلى مسار يمكن للبيئة المعزولة الوصول إليه فعليًا (مثل عنوان IP على شبكتك المحلية).
+
+### الوصول البرمجي (Python / Rust / Node)
+
+يُسجِّل agentmemory عملياته الأساسية كدوال iii (`mem::remember` و`mem::observe` و`mem::context` و`mem::smart-search` و`mem::forget`). يمكن لأي لغة تملك SDK لـ iii استدعاءها مباشرة عبر `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/) (بدء سريع + مسار الملاحظة/الاسترجاع). تظل REST على `:3111` متاحة للمضيفين الذين لا تتوفر لديهم بيئة تشغيل iii.
+
+### من المصدر
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+يُشغِّل هذا agentmemory مع `iii-engine` محلي إذا كان الملف التنفيذي المثبَّت مُثبَّتًا مسبقًا، أو يستخدم Docker Compose عند اختياره. ترتبط REST والتيارات والعارض بـ `127.0.0.1` افتراضيًا. ويتطلب مسار الملف التنفيذي الآلي على macOS/Linux وجود `curl` وصدفة POSIX من نوع `sh` وأداة `tar`.
+
+ثبّت `iii-engine` يدويًا. **يُثبّت agentmemory حاليًا `iii-engine` على الإصدار `v0.22.1`**، وهو نفس إصدار اعتمادية `iii-sdk` الخاصة به؛ فالعامل يتحدث بروتوكول الاتصال الخاص بذلك المحرك، وقد أعاد الإصدار 0.20.0 تنظيم سطح SDK، فيتحرك الاثنان معًا في إصدارات agentmemory. تجاوز ذلك باستخدام `AGENTMEMORY_III_VERSION=` إذا كنت تُشغِّل محركك الخاص وتعرف أنه متوافق.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** استبدل `aarch64-apple-darwin` بـ `x86_64-apple-darwin`
+- **Linux x64:** استبدل بـ `x86_64-unknown-linux-gnu`
+- **Linux arm64:** استبدل بـ `aarch64-unknown-linux-gnu`
+- **Windows:** نزِّل `iii-x86_64-pc-windows-msvc.zip` من [إصدارات iii-hq/iii v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) واستخرج `iii.exe` إلى `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+يملك كل أرشيف ملف `.sha256` مطابقًا على صفحة الإصدار؛ وعند تبديل النظام الأساسي، استخدم بصمة ذلك الملف (hash) في عملية التحقق أعلاه (على Windows: `Get-FileHash`). يُثبِّت المُثبِّت الآلي في `npx @agentmemory/agentmemory` هذه البصمات ويرفض أي أرشيف لا يطابقها.
+
+أو استخدم Docker (يسحب ملف `docker-compose.yml` المُضمَّن الصورة `iiidev/iii:0.22.1`). المستندات الكاملة: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+يعمل agentmemory على Windows 10/11، لكن حزمة Node.js وحدها لا تكفي؛ فأنت تحتاج أيضًا إلى بيئة تشغيل iii-engine المثبَّتة v0.22.1 كعملية خلفية. لا تستخرج الواجهة الطرفية CLI أرشيف ZIP الخاص بـ Windows تلقائيًا، فيجب على مستخدمي Windows الأصليين تثبيت `iii.exe` يدويًا، أو استخدام WSL2، أو اختيار Docker Desktop.
+
+لا يدعم الربط الآلي لـ MCP على Windows الأصلي إلا `agentmemory connect copilot-cli`. أما بالنسبة لـ Claude Code وCodex وCursor وكل وكيل Windows أصلي آخر، فانسخ كتلة MCP اليدوية من [وكلاء آخرون](#other-agents) إلى إعدادات Windows لذلك الوكيل. وتشغيل `connect` في WSL مناسب فقط عندما يكون الوكيل المستهدف مثبَّتًا أيضًا في بيئة WSL نفسها؛ فهو لا يُعدِّل إعدادات وكيل يستضيفه Windows.
+
+**الخيار أ: ملف تنفيذي جاهز لـ Windows (مُوصى به)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**الخيار ب: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**الخيار ج: MCP قائم بذاته فقط (بلا محرك).** إذا كنت تحتاج فقط إلى أدوات MCP لوكيلك ولا تحتاج إلى REST API أو العارض أو مهام cron، تجاوز المحرك كليًا:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**تشخيص الأعطال على Windows:** إذا فشل `npx -y @agentmemory/agentmemory@latest`، أعد تشغيله مع `--verbose` لرؤية مخرجات stderr الفعلية للمحرك. أنماط الفشل الشائعة:
+
+| العارض | الإصلاح |
+|---|---|
+| `The engine process started but the REST API never responded.` | تأكّد من أن المنافذ الأربعة المُستمَدَّة كلها خالية، وتحقَّق من بقاء `iii.exe` المثبَّت على قيد العمل، ثم أعد التشغيل مع `--verbose` وافحص stderr المُسجَّل للمحرك |
+| `Could not start iii-engine` | لا `iii.exe` ولا Docker مثبَّتان. راجع الخيار أ أو ب أعلاه |
+| تعارض في المنفذ | استخدم `netstat -ano \| findstr :3111` لمعرفة ما هو مرتبط بالمنفذ، ثم أنهِ تلك العملية أو استخدم `--port ` |
+| تجاوز الرجوع إلى Docker رغم تثبيت Docker | تأكّد من أن Docker Desktop يعمل فعليًا (أيقونة في علبة النظام) |
+
+> ملاحظة: **محرك** iii هو ملف تنفيذي جاهز مسبقًا، وليس صندوق (crate) من cargo، فلا تحاول تثبيته بأمر `cargo install`. (تُنشر **حِزم SDK** الخاصة بـ iii على crates.io وnpm وPyPI، لكن agentmemory لا يحتاج إليها.) جميع طرق تثبيت المحرك المدعومة مثبَّتة على الإصدار v0.22.1: الملف التنفيذي الجاهز أعلاه، ومسار التثبيت الآلي لـ agentmemory على macOS/Linux (يتطلب `curl` وصدفة POSIX من نوع `sh` وأداة `tar`)، وصورة Docker `iiidev/iii:0.22.1`. أما تشغيل سكربت المصدر الأساسي العاري `install.sh | sh` فيُثبّت أحدث المحرك، وهو ما لا يدعمه agentmemory. استخدم `npx -y @agentmemory/agentmemory@latest`؛ فهو يجلب المحرك المثبَّت على macOS/Linux إلى `~/.agentmemory/bin`.
+
+---
+
+
النشر
+
+قوالب نشر بنقرة واحدة للمضيفين المُدارين. يشحن كل قالب ملف Dockerfile قائمًا بذاته يسحب `@agentmemory/agentmemory` من npm، وينسخ الملف التنفيذي لمحرك iii من صورة `iiidev/iii` الرسمية على Docker Hub؛ فلا حاجة إلى صورة agentmemory مبنية مسبقًا. يُركَّب التخزين الدائم عند `/data`؛ ويستبدل سكربت الدخول (entrypoint) في أول تشغيل إعدادات iii المُضمَّنة في npm (التي ترتبط بـ `127.0.0.1`) بإعدادات مضبوطة للنشر ترتبط بـ `0.0.0.0` وتستخدم مسارات `/data` المطلقة، وتُولِّد سر HMAC، ثم تتنازل عن الصلاحيات من `root` إلى `node` عبر `gosu` قبل تنفيذ واجهة agentmemory CLI.
+
+
+
+
+
+
+يتطلب زر نشر Render بنقرة واحدة وجود `render.yaml` في جذر المستودع، وهو ما نتركه نظيفًا عمدًا. استخدم مسار Render Blueprint المُوثَّق في [`deploy/render/`](.././deploy/render/README.md) للإشارة يدويًا إلى المخطط الموجود في المستودع.
+
+تفاصيل الإعداد الكاملة (التقاط 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)؛ نفس حزمة Docker
+ Compose، وأنت من يملك المضيف والبيانات.
+
+لا يُنشر إلا المنفذ `3111`. ويبقى العارض على `3113`
+مرتبطًا بعنوان loopback داخل الحاوية؛ ويوثِّق ملف README لكل قالب نمط
+نفق SSH للوصول إليه.
+
+---
+
+
+
+ينسى كل وكيل ترميز كل شيء عند انتهاء الجلسة، وتبدأ كل جلسة جديدة بإعادتك شرح مكدّسك التقني من جديد. يعمل 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.
+```
+
+### مقابل ذاكرة الوكيل المدمجة
+
+يشحن كل وكيل ترميز بذكاء اصطناعي بذاكرة مدمجة: فـ Claude Code يملك `MEMORY.md`، وCursor يملك notepads، وCline يملك memory bank. تعمل هذه كملاحظات لاصقة (sticky notes). أما agentmemory فهو قاعدة البيانات القابلة للبحث التي تقف خلف تلك الملاحظات اللاصقة.
+
+| | مدمج (CLAUDE.md) | agentmemory |
+|---|---|---|
+| الحجم | حد 200 سطر | غير محدود |
+| البحث | يحمّل كل شيء إلى السياق | BM25 + متجهات + رسم بياني (أفضل K فقط) |
+| تكلفة الرموز | أكثر من 22K عند 240 ملاحظة | ~1,900 رمز (أقل بنسبة 92%) |
+| بين الوكلاء | ملفات لكل وكيل | MCP + REST (أي وكيل) |
+| التنسيق | لا يوجد | حجوزات، وإشارات، وإجراءات، ومسارات عمل (routines) |
+| قابلية الرصد | قراءة الملفات يدويًا | عارض لحظي على :3113 |
+
+---
+
+
+
+### مسار الذاكرة
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### توحيد الذاكرة الرباعي المستويات
+
+مصمَّم على غرار كيفية معالجة العقل البشري للذاكرة، بما في ذلك التوحيد أثناء النوم.
+
+| المستوى | المحتوى | المثيل البشري |
+|------|------|---------|
+| **العاملة (Working)** | ملاحظات خام من استخدام الأدوات | الذاكرة قصيرة المدى |
+| **الحدثية (Episodic)** | ملخصات مضغوطة للجلسات | "ما الذي حدث" |
+| **الدلالية (Semantic)** | حقائق وأنماط مستخرجة | "ما الذي أعرفه" |
+| **الإجرائية (Procedural)** | مسارات عمل وأنماط قرارات | "كيف يتم ذلك" |
+
+تتلاشى الذكريات بمرور الوقت (منحنى إبنغهاوس). وتتقوّى الذكريات التي يُرجَع إليها كثيرًا. ويُطرَد تلقائيًا الذكريات القديمة البائتة. ويُكتشف التضارب ويُحل.
+
+### ما الذي يُلتَقط
+
+| الخطاف | يلتقط |
+|------|----------|
+| `SessionStart` | مسار المشروع، ومعرّف الجلسة |
+| `UserPromptSubmit` | مطالبات المستخدم (مُرشَّحة للخصوصية) |
+| `PreToolUse` | أنماط الوصول إلى الملفات + سياق مُغنًى |
+| `PostToolUse` | اسم الأداة، والمدخل، والمخرج |
+| `PostToolUseFailure` | سياق الخطأ |
+| `PreCompact` | يُعيد حقن الذاكرة قبل الضغط (compaction) |
+| `SubagentStart/Stop` | دورة حياة الوكيل الفرعي |
+| `Stop` | ملخص نهاية الجلسة |
+| `SessionEnd` | علامة اكتمال الجلسة |
+
+### القدرات الأساسية
+
+| القدرة | الوصف |
+|---|---|
+| **الالتقاط التلقائي** | يُسجَّل كل استخدام للأدوات عبر الخطافات، دون أي جهد يدوي |
+| **البحث الدلالي** | BM25 + متجهات + رسم بياني معرفي بدمج RRF |
+| **تطوّر الذاكرة** | إصدارات، وإحلال (supersession)، ورسوم بيانية للعلاقات |
+| **نظافة الاسترجاع** | تخرج نسخ الذاكرة المُستبدَلة من فهارس البحث؛ وتحتفظ سلسلة الإصدارات في KV بالتاريخ الكامل |
+| **تلميحات شبه التكرار** | يُسجِّل الحفظ تطابق `similarTo` استشاريًا عندما يشبه المحتوى الجديد ذكرى موجودة مسبقًا بشكل وثيق |
+| **تحديد النطاق لكل وكيل** | يمر `agentId` عبر الحفظ والاسترجاع في REST وMCP وفهرس البحث، في الوضع المشترك أو المعزول |
+| **المصدرية عند الكتابة** | تحمل كل ملاحظة وذكرى قناة أصل ثابتة (مستخدم، وكيل، أداة، استيراد، أو مشترك) تُختم عند الالتقاط والحفظ والاستيراد |
+| **النسيان التلقائي** | انتهاء صلاحية TTL، وكشف التضارب، وطرد حسب الأهمية |
+| **الخصوصية أولًا** | تُحذف مفاتيح API والأسرار ووسوم `` قبل التخزين |
+| **الإصلاح الذاتي** | قاطع دائرة (circuit breaker)، وسلسلة احتياطية للمزوّدين، ورصد صحي |
+| **جسر Claude** | مزامنة ثنائية الاتجاه مع MEMORY.md |
+| **الرسم البياني المعرفي** | استخراج الكيانات + تجوال BFS |
+| **ذاكرة الفريق** | مشترك وخاص مُقسَّم بمساحات أسماء بين أعضاء الفريق |
+| **مصدرية الاستشهاد** | تتبّع أي ذكرى رجوعًا إلى الملاحظات المصدرية |
+| **لقطات Git** | إصدار، وتراجع، ومقارنة فروقات لحالة الذاكرة |
+
+---
+
+
+
+استرجاع ثلاثي التيار يجمع بين ثلاث إشارات:
+
+| التيار | ما يفعله | متى يعمل |
+|---|---|---|
+| **BM25** | مطابقة كلمات مفتاحية بعد التجذيع (stemming) مع توسيع بالمرادفات | يعمل دائمًا |
+| **المتجهات** | تشابه جيب التمام (cosine) عبر تضمينات كثيفة | عند ضبط مزوّد تضمين |
+| **الرسم البياني** | تجوال في الرسم البياني المعرفي عبر مطابقة الكيانات | عند اكتشاف كيانات في الاستعلام |
+
+تُدمج بخوارزمية Reciprocal Rank Fusion (RRF، k=60) وتُنوَّع حسب الجلسة (3 نتائج كحد أقصى لكل جلسة).
+
+عندما يكون فهرس المتجهات مُعبَّأً، يستخدم `mem::search` (الذي يقف خلف `memory_recall`) المُصنِّف الهجين BM25 + المتجهات. وبدون تضمينات يستخدم BM25. ويمكن لـ `smart-search` أيضًا دمج تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني، حتى في وضع عدم استخدام المفاتيح. ويعمل استرجاع الدروس المستفادة على فهرس BM25 مخصص في الذاكرة بدلًا من مسح المجموعة الكاملة في كل استعلام. وتُستبعد نسخ الذاكرة المُستبدَلة من كل مسار استرجاع؛ وتحتفظ سلسلة الإصدارات بتاريخها.
+
+تنجو المتجهات من الانهيار أو الإيقاف القسري. ويُحفظ فهرس المتجهات في حُزَم مرة واحدة على الأكثر كل `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 دقائق). ويُكتب أيضًا كل متجه يُضاف أو يُحذف بين ذلك فورًا في سجل انتظار صغير في مخزن الحالة، ويُعاد تشغيله عند البدء التالي دون استدعاء مزوّد التضمين. ويُفرَّغ السجل عند كل حفظ ناجح. وتُعاد تضمين المستندات التي لا تزال بلا متجه بعد إعادة التشغيل في الخلفية على دفعات بحجم `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) إلى أن لا يبقى منها شيء، ويستكمل أي ملء رجعي (backfill) متوقف في البدء التالي. يُظهر `/agentmemory/status` والعارض حجم سجل الانتظار وحالة الملء الرجعي. ولا تكتب التثبيتات بلا مفاتيح أي شيء.
+
+يُجزِّئ BM25 إلى رموز (tokens) اليونانية والسيريلية والعبرية والعربية واللاتينية المُشكَّلة جاهزًا دون أي إعداد. وبالنسبة لذكريات الصينية/اليابانية/الكورية، ثبّت المُجزِّئات (segmenters) الاختيارية (`npm install @node-rs/jieba tiny-segmenter`) لتقسيم سلاسل CJK إلى رموز على مستوى الكلمة؛ وبدونها، يتراجع agentmemory بسلاسة إلى تجزيء السلسلة كاملةً ويطبع تلميحًا لمرة واحدة على stderr.
+
+### مزوّدو التضمين
+
+تُعطّل التثبيتات بلا مفاتيح تضمينات المتجهات: يستخدم `mem::search` خوارزمية BM25، في حين يمكن لـ `smart-search` أيضًا استخدام بيانات الرسم البياني البنيوية الموجودة مسبقًا. للانضمام الاختياري إلى تضمينات دلالية مجانية على الجهاز نفسه، أضف هذا إلى `~/.agentmemory/.env` وأعد تشغيل agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+يتضمن تثبيت npm العادي بيئة تشغيل `@huggingface/transformers` الاختيارية. يُنزِّل أول طلب تضمين النموذج `Xenova/all-MiniLM-L6-v2`، لذا يحتاج إلى الوصول إلى الشبكة وقد يستغرق وقتًا أطول؛ ويعمل الاستدلال اللاحق على الجهاز نفسه. ويُكتشف المزوّدون البعيدون تلقائيًا من مفاتيحهم إلا إذا تجاوزهم `EMBEDDING_PROVIDER`.
+
+| المزوّد | النموذج | التكلفة | ملاحظات |
+|---|---|---|---|
+| **محلي (مُوصى بتفعيله)** | `all-MiniLM-L6-v2` | مجاني | على الجهاز نفسه بعد أول تنزيل للنموذج، وبزيادة 8 نقاط نسبة مئوية في الاسترجاع عن BM25 فقط |
+| Gemini | `gemini-embedding-001` | مستوى مجاني | أكثر من 100 لغة، أبعاد 768/1536/3072 (MRL)، ومدخل حتى 2048 رمزًا. يحل محل `text-embedding-004` ([مُستبعَد، يُغلق في 14 يناير 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | 0.02$/مليون | أعلى جودة |
+| Voyage AI | `voyage-code-3` | مدفوع | مُحسَّن للشفرة |
+| Cohere | `embed-english-v3.0` | نسخة تجريبية مجانية | للاستخدام العام |
+| OpenRouter | أي نموذج | متفاوت | وكيل متعدد النماذج |
+
+---
+
+
+
+54 أداة، و6 موارد، و3 مطالبات، و17 مهارة.
+
+> **وسيط MCP (shim) في مقابل الخادم الكامل:** حزمة `@agentmemory/mcp` المنشورة هي وسيط خفيف (shim). ولا يُظهر سطح الأدوات الكامل البالغ 54 أداة **إلا عندما يستطيع الوصول إلى خادم agentmemory يعمل** عبر `AGENTMEMORY_URL` (وضع الوكيل الوسيط proxy). وإذا تعذّر الوصول إلى أي خادم، يرجع الوسيط إلى مجموعة محلية من 7 أدوات (`memory_save` و`memory_recall` و`memory_smart_search` و`memory_sessions` و`memory_export` و`memory_audit` و`memory_governance_delete`). متغير البيئة `AGENTMEMORY_TOOLS=core|all` هو راية *من جانب الخادم*؛ وضبطه في كتلة `env` الخاصة بالوسيط لا يُحدث أي أثر. إذا رأيت 7 أدوات فقط في Cursor / OpenCode / Gemini CLI، شغّل `npx -y @agentmemory/agentmemory@latest` (أو حزمة Docker) واضبط `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 أداة
+
+ثلاث واجهات للأدوات، من الأصغر إلى الأكبر: يُقلِّص `AGENTMEMORY_TOOLS=core` مجموعة الأدوات الظاهرة إلى 8 أدوات أساسية (`memory_save` و`memory_recall` و`memory_consolidate` و`memory_smart_search` و`memory_sessions` و`memory_diagnose` و`memory_lesson_save` و`memory_reflect`)؛ وتمثل المجموعة الأساسية أدناه الأدوات التأسيسية الـ14 في السجل؛ أما الوضع الافتراضي (`AGENTMEMORY_TOOLS=all`) فيعرض جميع الأدوات الـ54.
+
+
+الأدوات الأساسية (14)
+
+| الأداة | الوصف |
+|------|-------------|
+| `memory_recall` | البحث في الملاحظات السابقة |
+| `memory_compress_file` | ضغط ملفات Markdown مع الحفاظ على البنية |
+| `memory_save` | حفظ استبصار، أو قرار، أو نمط |
+| `memory_file_history` | الملاحظات السابقة المتعلقة بملفات محددة |
+| `memory_patterns` | اكتشاف الأنماط المتكررة |
+| `memory_sessions` | سرد الجلسات الأخيرة |
+| `memory_smart_search` | بحث هجين دلالي + بكلمات مفتاحية |
+| `memory_vision_search` | البحث في ملاحظات الصور |
+| `memory_timeline` | الملاحظات مرتبة زمنيًا |
+| `memory_profile` | ملف تعريف المشروع (مفاهيم، ملفات، أنماط) |
+| `memory_export` | تصدير جميع بيانات الذاكرة |
+| `memory_relations` | الاستعلام عن رسم بياني العلاقات |
+| `memory_commit_lookup` | الجلسات التي تقف خلف commit في git |
+| `memory_commits` | عمليات الـ commit المسجَّلة لجلسة ما |
+
+
+
+
+الأدوات الموسَّعة (54 أداة إجمالًا، السطح الافتراضي)
+
+| الأداة | الوصف |
+|------|-------------|
+| `memory_patterns` | اكتشاف الأنماط المتكررة |
+| `memory_timeline` | الملاحظات مرتبة زمنيًا |
+| `memory_relations` | الاستعلام عن رسم بياني العلاقات |
+| `memory_graph_query` | تجوال الرسم البياني المعرفي |
+| `memory_consolidate` | تشغيل التوحيد الرباعي المستويات |
+| `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` | إنشاء نُسخ من مسارات العمل (routines) |
+| `memory_signal_send` | التراسل بين الوكلاء |
+| `memory_signal_read` | قراءة الرسائل مع إيصالات استلام |
+| `memory_checkpoint` | بوابات شروط خارجية |
+| `memory_mesh_sync` | مزامنة نظير إلى نظير (P2P) بين النُّسخ |
+| `memory_sentinel_create` | رُصَد (watchers) مُفعَّلة بالأحداث |
+| `memory_sentinel_trigger` | تفعيل الرُّصَد خارجيًا |
+| `memory_sketch_create` | رسوم تخطيطية مؤقتة للإجراءات |
+| `memory_sketch_promote` | ترقية إلى دائم |
+| `memory_crystallize` | ضغط سلاسل الإجراءات |
+| `memory_diagnose` | فحوصات الحالة الصحية |
+| `memory_heal` | إصلاح تلقائي للحالة المتوقفة |
+| `memory_facet_tag` | وسوم بُعد:قيمة |
+| `memory_facet_query` | الاستعلام عبر وسوم الأبعاد |
+| `memory_verify` | تتبّع المصدرية |
+
+
+
+### 6 موارد · 3 مطالبات · 17 مهارة
+
+| النوع | الاسم | الوصف |
+|------|------|-------------|
+| مورد | `agentmemory://status` | الحالة الصحية، وعدد الجلسات، وعدد الذكريات |
+| مورد | `agentmemory://project/{name}/profile` | معلومات ذكية خاصة بكل مشروع |
+| مورد | `agentmemory://project/{name}/recent` | الملاحظات الأخيرة لمشروع ما |
+| مورد | `agentmemory://memories/latest` | أحدث 10 ذكريات نشطة |
+| مورد | `agentmemory://graph/stats` | إحصاءات الرسم البياني المعرفي |
+| مورد | `agentmemory://team/{id}/profile` | ملف تعريف مشترك للفريق |
+| مطالبة | `recall_context` | البحث + إعادة رسائل السياق |
+| مطالبة | `session_handoff` | تسليم البيانات بين الوكلاء |
+| مطالبة | `detect_patterns` | تحليل الأنماط المتكررة |
+| مهارة | `/recall` | البحث في الذاكرة |
+| مهارة | `/remember` | الحفظ في الذاكرة طويلة المدى |
+| مهارة | `/session-history` | ملخصات الجلسات الأخيرة |
+| مهارة | `/forget` | حذف الملاحظات/الجلسات |
+
+يُظهر الجدول المهارات الأساسية الأربع. والمجموعة الكاملة هي 9 مهارات قابلة للاستدعاء إضافة إلى 8 مهارات مرجعية؛ راجع قسم المهارات الأصلية أعلاه.
+
+### MCP القائم بذاته
+
+يُشغَّل دون الخادم الكامل، لأي عميل MCP. يعمل كلاهما:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+أو أضف إلى إعدادات MCP الخاصة بوكيلك:
+
+معظم الوكلاء (Cursor وClaude Desktop وCline وRoo Code وGemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+ادمج إدخال `agentmemory` في كائن `mcpServers` الموجود مسبقًا في مضيفك بدلًا من استبدال الملف. وبالنسبة للعملاء المحتجزين في بيئة معزولة والذين لا يمكنهم الوصول إلى `localhost` الخاص بالمضيف، أضف `"AGENTMEMORY_FORCE_PROXY": "1"` إلى كتلة env واضبط `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/
+```
+
+---
+
+
+
+يبدأ تلقائيًا على المنفذ `3113`. يحمّل العارض لقطة واحدة (snapshot) عند الاتصال (`GET /agentmemory/viewer/snapshot`)، ثم يطبّق أحداث التيار المباشر: تظهر الذكريات الجديدة، والدروس المستفادة، والملاحظات، وإدخالات التدقيق، وتغييرات الرسم البياني، وتحديثات الحالة الصحية دون أي استقصاء دوري أو إعادة تحميل للصفحة. والطلبات الأخرى الوحيدة هي الإجراءات التي تنقر عليها، وصفحات "تحميل المزيد"، وعمليات البحث. وعند انقطاع التيار، يُظهر العارض مدى قِدَم أرقامه، ويعيد الاتصال بتراجع تدريجي (backoff)، ويعيد المزامنة من لقطة واحدة.
+
+- **12 تبويبًا في أربع مجموعات** مع عدادات حية، وروابط عميقة (`#memories/`، و`#sessions/?obs=`، و`#graph/`، و`#health/consolidation`)، واختصارات لوحة المفاتيح، وقائمة للهاتف المحمول.
+- **الذكريات:** بحث من جانب الخادم، ومرشِّحات حسب المشروع والوكيل والنوع، ولوحة تفاصيل تضم سلسلة الإصدارات ومقارنة فروق الكلمات (word diff)، وروابط المصدرية، وأزرار نسخ للمعرّف، واستدعاء MCP، وأمر curl، وتعديل (ينشئ إصدارًا جديدًا)، ونسيان مع تأكيد، ونسيان جماعي، وتصدير JSON.
+- **الجلسات:** خط زمني مضمَّن للملاحظات بمدخلات ومخرجات أدوات قابلة للقراءة، ومرشِّحات وتصفّح بالصفحات، والذكريات والدروس المستفادة التي أنتجتها كل جلسة.
+- **الرسم البياني:** بحث، وتفاصيل العُقَد مع العلاقات والمصادر، ومفتاح توضيحي (legend) لا يعتمد على اللون وحده، وأدوات تحكم بالتقريب (zoom).
+- **الحالة الصحية:** النسخة المباشرة من `GET /agentmemory/status`. تأتي كل مشكلة مع إصلاحها، إضافة إلى خلفية الحالة، وحالة حفظ الفهرس، وتقدّم ضغط مصدرية الرسم البياني، وشرح للتوحيد يضم العتبات الفعلية.
+- صفحات **التدقيق، والنشاط، وملف التعريف، وإعادة التشغيل، والدروس المستفادة، والإجراءات، والبلورات (Crystals)**، وكل صفحة منها لها حالة فراغ تشرح ما هو هذا القسم، ولماذا هو فارغ، والأمر الذي يملؤه، إضافة إلى تلميح مسرد (glossary) بعلامة `?` عند كل مصطلح وعدد.
+
+```bash
+open http://localhost:3113
+```
+
+يرتبط خادم العارض بـ `127.0.0.1` افتراضيًا، ويُرفق سر الخادم عند تمرير الطلبات إلى REST API، فلا يحتاج إلى أي إعداد. وتتبع نقطة النهاية `/agentmemory/viewer` المُقدَّمة عبر REST القواعد العادية لرمز الحامل (bearer token)، وتُعيد توجيه المتصفحات التي لا تحمل رمزًا إلى منفذ العارض. وتستخدم ترويسات CSP قيمة nonce خاصة بالنص البرمجي لكل استجابة، وتُعطِّل سمات المعالج المضمَّنة inline (`script-src-attr 'none'`).
+
+---
+
+
+
+يُظهر العارض على `:3113` ما **تذكّره** وكيلك. أما [لوحة تحكم iii](https://iii.dev/docs/console) فتُظهر ما **فعله** وكيلك: كل عملية ذاكرة كتتبع OpenTelemetry، وكل إدخال KV قابل للتعديل، وكل دالة قابلة للاستدعاء، وكل تيار قابل للاستماع إليه. نافذتان على الذاكرة نفسها: واحدة بشكل المنتج، وأخرى بشكل المحرك.
+
+شاهد `memory_smart_search` وهو يُطلَق وتابع مسح BM25 ← البحث في التضمينات ← دمج RRF ← إعادة الترتيب (reranker) كشكل شلالي (waterfall). عدِّل مؤقِّت توحيد عالقًا في مستعرض KV. أعد تشغيل خطاف `PostToolUse` بحمولة مُعدَّلة. ثبِّت تيار WebSocket وشاهد الملاحظات وهي تصل لحظيًا.
+
+يقدّم agentmemory هذا مجانًا لأن كل استدعاء دالة ومحفِّز يمر عبر iii؛ فلا شيء مخصص، ولا شيء يحتاج إلى تثبيت أدوات قياس (instrumentation).
+
+
+
+
+ صفحة العمّال: كل عامل متصل، بما في ذلك agentmemory نفسه، مع PID، وعدد الدوال، وبيئة التشغيل، وآخر ظهور.
+
+
+**مثبَّت مسبقًا.** تُشحن لوحة التحكم مع محرك `iii` المثبَّت (0.22 وما بعده)؛ فلا حاجة إلى تثبيت أي شيء منفصل. يُنزِّل أول تشغيل الملف التنفيذي للوحة التحكم بجانب المحرك.
+
+**التشغيل جنبًا إلى جنب مع agentmemory:**
+
+```bash
+agentmemory console
+```
+
+يُشغِّل هذا أمر `iii console` الخاص بالمحرك المثبَّت على المنافذ التي حلّلها agentmemory (REST، والتيارات، والجسر)، ويقدّمه على منفذ واحد أعلى من العارض، أي `http://localhost:3114` افتراضيًا. يختار `--console-port N` منفذًا آخر؛ ويختار `--port` و`--instance` نسخة agentmemory بنفس الطريقة التي يفعلانها مع `stop`؛ وتُمرَّر أي راية أخرى كما هي، مثل `--enable-flow` لصفحة الرسم البياني المعماري التجريبية.
+
+نفس الأمر يدويًا، وهو مفيد عندما لا يكون `agentmemory` موجودًا في PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**ما يمكنك فعله من لوحة التحكم:**
+
+| الصفحة | استخدمها لـ |
+|------|-----------|
+| **العمّال (Workers)** | رؤية كل عامل متصل ومقاييسه الحية، بما في ذلك عامل agentmemory نفسه. |
+| **الدوال (Functions)** | استدعاء أي من دوال agentmemory مباشرة بحمولة JSON؛ مفيد لاختبار `memory.recall` و`memory.consolidate` و`graph.query` دون ربط عميل. |
+| **المحفِّزات (Triggers)** | إعادة تشغيل محفِّزات HTTP وcron والأحداث والحالة: تفعيل مهمة cron للتوحيد يدويًا، وإعادة محاولة مسار HTTP، وبث تغيّر حالة. |
+| **الحالات (States)** | مستعرض KV بعمليات CRUD كاملة على الجلسات، وفُتحات الذاكرة، ومؤقِّتات دورة الحياة، وفهرس التضمينات؛ وتعديل القيم في مكانها. |
+| **التيارات (Streams)** | مراقب WebSocket مباشر لكتابات الذاكرة، وأحداث الخطافات، وتحديثات الملاحظات أثناء تدفّقها عبر تيارات iii. |
+| **قوائم الانتظار (Queues)** | مواضيع قوائم انتظار دائمة + إدارة الرسائل المتعطّلة (dead-letter). إعادة تشغيل أو إسقاط مهام التضمين/الضغط الفاشلة. |
+| **التتبّعات (Traces)** | عروض شلالية (waterfall) / لهبية (flame) / تفصيلية بالخدمة لـ OpenTelemetry. رشِّح حسب `trace_id` لمعرفة بالضبط أي الدوال، واستدعاءات قاعدة البيانات، وطلبات التضمين التي أنتجها استدعاء واحد لـ `memory.search`. |
+| **السجلات (Logs)** | سجلات OTEL البنيوية مُرشَّحة ومرتبطة بمعرِّفات trace/span. |
+| **الإعدادات (Config)** | إعدادات بيئة التشغيل: رؤية بالضبط أي عمّال ومزوّدين ومنافذ يعمل محركك بها. |
+| **التدفّق (Flow)** | (اختياري، `--enable-flow`) رسم بياني معماري تفاعلي لكل عامل، ومحفِّز، وتيار. |
+
+
+
+
+ التتبّعات: عرض شلالي / لهبي / تفصيلي بالخدمة لكل عملية ذاكرة.
+
+
+**التتبّعات مُفعَّلة مسبقًا:**
+
+يُشحن `iii-config.yaml` مع تفعيل عامل `iii-observability` (`exporter: memory`، و`sampling_ratio: 0.1`، ومقاييس + سجلات). ولا حاجة إلى أي إعداد إضافي؛ فمنذ لحظة تشغيل agentmemory، تُصدِر كل عملية ذاكرة سجلًا بنيويًا يمكن لوحة التحكم قراءته، وتُصدِر واحدة من كل عشر عمليات (`sampling_ratio: 0.1`) مدى تتبّع (trace span) أيضًا.
+
+إذا رغبت في التصدير إلى Jaeger/Honeycomb/Grafana Tempo بدلًا من ذلك، غيّر `exporter: memory` إلى `exporter: otlp` واضبط نقطة نهاية المُجمِّع (collector) وفقًا لمستندات المراقبة في iii.
+
+> **تنبيه:** لا تُفرَض أي مصادقة على لوحة التحكم نفسها؛ احتفظ بارتباطها بـ `127.0.0.1` (الافتراضي) ولا تُعرِّضها علنًا مطلقًا.
+
+---
+
+
+
+agentmemory هو **فعليًا نسخة تشغيل من [iii](https://iii.dev)**. تُؤلِّف ثلاث بنى أساسية (العامل، والدالة، والمحفِّز) بيئة التشغيل؛ وتأتي حالة KV، والتيارات، وتتبّعات OTEL من عمّال iii-state وiii-stream وiii-observability المُشحونة مع iii. أنت لم تُثبِّت Postgres أو Redis أو Express أو pm2 أو Prometheus، لأن iii يحل محلها.
+
+وهذا يعني أن أمرًا واحدًا إضافيًا يمنح agentmemory قدرة جديدة كاملة.
+
+### توسيع agentmemory بمزيد من العمّال
+
+العمّال المُضمَّنون (builtins) اللازمون لـ agentmemory موجودون مسبقًا في `iii-config.yaml` ويُقلعون معه: `iii-state` (KV)، و`iii-queue` (إعادة محاولات دائمة لمشتركي الأحداث)، و`iii-pubsub`، و`iii-cron`، و`iii-stream`، و`iii-observability` (تتبّعات OTEL، ومقاييس، وسجلات على كل دالة). وأي شيء آخر من [سجل عمّال iii](https://workers.iii.dev) يتوصّل بالمحرك نفسه: انسخ `iii-config.yaml` إلى `~/.agentmemory/iii-config.yaml` (تُفضِّل الواجهة الطرفية CLI هذا الملف على الملف المُضمَّن، وتظل تُصيِّر المنافذ ومسارات البيانات فيه)، وأضف الإدخال، وثبِّت بيئة تشغيل العامل مرة واحدة بأمر `~/.agentmemory/bin/iii update worker`، وأعد تشغيل agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| العامل | ما تحصل عليه إضافة إلى agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | محوِّل حالة مدعوم بـ SQL عندما تتجاوز احتياجاتك إعدادات KV الافتراضية في الذاكرة |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | تشغيل الشفرة التي تخرج من `memory_recall` داخل جهاز افتراضي مؤقت، لا في صدفتك الخاصة |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | إقامة خوادم MCP إضافية بجانب خادم agentmemory، بمشاركة المحرك نفسه |
+
+على المحرك 0.22.x، احتفظ بالأسماء المُضافة لها بادئة `iii-` للعمّال المُضمَّنين أعلاه؛ أما الإدخالات غير المُسبَّقة بادئةً `http` و`state` و`queue` و`pubsub` و`cron` فهي عمّال السجل المستقلون التي ينتقل إليها agentmemory مع ترحيل 0.23.
+
+السجل الكامل: [workers.iii.dev](https://workers.iii.dev). ويُؤلَّف كل عامل هناك من خلال البنى الأساسية نفسها التي يستخدمها agentmemory، وagentmemory الذي تملكه مسبقًا هو واحد منها.
+
+### إعدادات المحرك وعنوان الارتباط
+
+يقرأ `agentmemory start` إعدادات المحرك من أول ملف موجود: `AGENTMEMORY_III_CONFIG`، ثم `./iii-config.yaml` في الدليل الحالي، ثم `~/.agentmemory/iii-config.yaml`، ثم ملف `iii-config.yaml` المُضمَّن. وفي كل تشغيل، يُصيِّر ذلك الملف (مسارات البيانات، والمنافذ، وخلفية الحالة) إلى `~/.agentmemory/data/iii-config.runtime.yaml` ويُشغِّل المحرك بالنسخة المُصيَّرة، فعدِّل ملف المصدر، لا الملف المُصيَّر. وتُحفظ قيم `host:` في ملف المصدر كما كُتبت.
+
+يرتبط `iii-config.yaml` المُضمَّن بـ `127.0.0.1` عمدًا، وينطبق ذلك الافتراضي أيضًا داخل الحاوية. وتستمع الواجهة الطرفية CLI المُشغَّلة داخل حاوية إلى عنوان loopback الخاص بالحاوية، فلا تصل المنافذ المنشورة إلى أي شيء. ولتقديم واجهة طرفية مُحوسَبة في حاويات عبر منافذ منشورة، اضبط `AGENTMEMORY_III_CONFIG` على إعدادات ترتبط بـ `0.0.0.0`. ويُعدّ `iii-config.docker.yaml` المُعبَّأ أحد هذه الإعدادات: فهو يربط `iii-http` و`iii-stream` ومنفذ المحرك بـ `0.0.0.0` ويخزِّن الحالة تحت `/data`، فاربط (mount) حجمًا (volume) قابلًا للكتابة هناك. حافظ على ضبط `AGENTMEMORY_SECRET`، ولا تنشر إلا المنافذ التي تحتاجها، على `127.0.0.1` أو خلف وكيل عكسي تثق به.
+
+لا يمر ملف `docker-compose.yml` الخاص بهذا المستودع عبر آلية بحث الواجهة الطرفية CLI عن الإعدادات: فهو يربط `iii-config.docker.yaml` عند `/app/config.yaml`، وتُشغَّل حاوية `iii-engine` بأمر `--config /app/config.yaml`. أما [قوالب النشر](../deploy/) بنقرة واحدة فتكتب إعداداتها الخاصة بـ `0.0.0.0` في سكربتات دخولها.
+
+### خلفية التخزين: ملف (افتراضي) في مقابل redis
+
+يفترض `iii-state` و`iii-stream` مخزن KV المستنِد إلى الملفات المُضمَّن في iii-engine: ملف JSON واحد لكل نطاق، محفوظ في ذاكرة عملية المحرك ويُعاد كتابته على القرص بمؤقِّت. وهذا هو الافتراضي الصحيح لتثبيت محلي بمستخدم واحد؛ أما خادم عفريتي (daemon) مشترك بعدة كُتّاب متزامنين فيحصل بدلًا من ذلك على كتابات فعلية لكل مفتاح من Redis، بتكلفة رحلة شبكة ذهابًا وعودة لكل عملية (لا يزال كل استدعاء `state::*` يتسلسل على اتصال Redis واحد، فهذا يستبدل قفل مخزن الملفات بمقبس (socket)، لا بتوازٍ حقيقي).
+
+اضبط `AGENTMEMORY_STATE_BACKEND=redis` (مع `AGENTMEMORY_REDIS_URL`) لتبديل كلا العاملين إلى محوِّل `redis` المدمج في iii-engine، والذي يخزِّن كل مفتاح كحقل تجزئة (hash) في Redis (`HSET`) بدلًا من إعادة كتابة نطاق كامل عند كل كتابة:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+يكون `AGENTMEMORY_STATE_BACKEND` بقيمة `file` افتراضيًا؛ وتركه بلا ضبط يحافظ على السلوك الحالي دون تغيير، وأي قيمة غير معروفة (أي شيء غير `file` أو `redis`) تُسبِّب خطأ عند البدء بدلًا من رجوع صامت. يُعلِن `/agentmemory/status` وصفحة الحالة الصحية في العارض (صف مخزن الحالة) عن الخلفية النشطة وهل تستجيب أم لا، ولا يُعلِنان العنوان مطلقًا.
+
+**`redis://` العادي فقط.** يبني المحرك المثبَّت (0.22.1) عميل Redis الخاص به دون دعم TLS، فيفشل الاتصال بعنوان `rediss://` (تفترض معظم خدمات Redis المُدارة، مثل Upstash وRedis Cloud وElastiCache بتشفير أثناء النقل، استخدام TLS فقط). الاتصال غير مُشفَّر، فتعبر كلمة مرور Redis وكل ذكرى مخزَّنة السلك نصًا صريحًا: وجِّهه إلى Redis محلي أو إلى واحد على شبكة خاصة تثق بها. وبالنسبة لأي Redis آخر، شغِّل نفقًا مُشفَّرًا (stunnel أو SSH أو VPN) على مضيف agentmemory، بحيث تبقى قفزة `redis://` العادية على ذلك المضيف ويكون اتصال النفق الصاعد (upstream) مُشفَّرًا ومُصادَقًا عليه. وإذا كانت كلمة مرور Redis تحتوي على علامة اقتباس مفردة، شفِّرها بترميز النسبة المئوية (`%27`)؛ فالمحرك يُوسِّع العنوان في إعدادات YAML الخاصة به قبل تحليله.
+
+**خادم Redis واحد لكل `--instance`.** بادئات مفاتيح Redis الخاصة بالمحرك (`state:`، و`stream::`) ثابتة، فإذا أشارت نسختان من agentmemory (`--instance 1`، و`--instance 2`، ...) إلى قاعدة البيانات نفسها، تتداخل بيانات كل منهما مع الأخرى وتُستبدَل. يُبقي فهرس قاعدة بيانات منفصل (`redis://localhost:6379/1`) البيانات المخزَّنة متفرقة، لكن المحرك يُرحِّل أحداث العارض الحية عبر قناة واحدة من نوع Redis pub/sub (`stream::events`)، ويتجاهل Redis pub/sub فهرس قاعدة البيانات، فسيظل عارض كل نسخة يُظهر الأحداث الحية للنسخة الأخرى. أعطِ كل نسخة خادم Redis خاصًا بها (أو منفذًا خاصًا) عندما تُشغِّل أكثر من نسخة واحدة.
+
+**ما يبقى كما هو، وما يختلف.** تعمل كل ميزة في agentmemory على Redis: الجلسات، والملاحظات، والذكريات (الحفظ، والإحلال، والتطور، والنسيان)، والبحث وحُزَم الفهرس، والدروس المستفادة، والرسم البياني، وسجل التدقيق ونطاقاته الشهرية، والتصدير والاستيراد، وعمليات الحذف الإدارية (governance)، وحالة التوحيد، ولقطة العارض وتيارها المباشر، ومراقب الحالة الصحية. ويخزِّن المحرك كل نطاق كتجزئة Redis واحدة (`HSET`/`HGET`/`HGETALL`) ويُطلِق محفِّزات الحالة نفسها التي يُطلقها مخزن الملفات. وتُعالَج ثلاثة اختلافات في المحرك داخل agentmemory:
+
+- يُعيد Redis سجلات النطاق دون ترتيب ثابت. يُرتِّبها agentmemory من الأقدم إلى الأحدث (بحسب وقت الإنشاء في معرّف السجل، ثم طابعه الزمني) بحيث تعود القوائم، والصفحات، وكُتل التصدير بالترتيب نفسه الموجود على مخزن الملفات.
+- يطبِّق المحرك التحديثات الجزئية على Redis بسكربت Lua يُحوِّل المصفوفات الفارغة إلى كائنات فارغة. يطبِّق agentmemory تلك التحديثات بنفسه على Redis (قراءة، وتغيير، وكتابة تحت قفل لكل مفتاح)، فتبقى حقول مثل `tags: []` مصفوفات.
+- يقرأ فحص سجل التدقيق القديم النطاق القديم من Redis بدلًا من البحث عن ملف مخزن الملفات على القرص.
+
+هناك اختلاف واحد يحتاج تدخّلك: **بعد إعادة تشغيل Redis، يتوقف المحرك عن ترحيل الأحداث الحية** إلى العارض إلى أن يُعاد تشغيل agentmemory. ولا تزال البيانات تُحفظ وتُقرأ بشكل طبيعي. يرسل مراقب الحالة الصحية حدثًا اختباريًا عبر Redis كل 30 ثانية؛ وعندما لا يعود، يُظهر `/agentmemory/status` وصفحة الحالة الصحية في العارض "التحديثات الحية لا تصل إلى العارض" مع الإصلاح: أعِد تشغيل agentmemory. وإذا كان Redis متوقفًا، يُظهر تقرير الحالة "مخزن الحالة لا يستجيب" وكيفية التحقق من ذلك (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). ويقرأ سرد نطاق كبير جدًا التجزئة كاملةً في `HGETALL` واحد، بنفس تكلفة احتفاظ مخزن الملفات به في الذاكرة.
+
+**إعدادات Redis المُوصى بها.** قد تُفقد سياسة اللقطات الافتراضية `save 3600 1 300 100 60 10000` دقائق من الكتابات عند الانهيار، وهذا أسوأ من نافذة التفريغ البالغة 5 ثوانٍ في مخزن الملفات. اضبط `appendonly yes` لأي شيء يهمك ألا تفقده. واضبط `maxmemory-policy noeviction`؛ فسياسة `allkeys-lru` أو ما شابهها تُسقِط الذكريات بصمت بمجرد أن يصل Redis إلى حد ذاكرته.
+
+يقرأ التشغيل الأصلي (غير Docker)، وكل [قالب نشر](../deploy/) بنقرة واحدة (فهي تستبدل `iii-config.yaml` المُضمَّن وتُشغَّل أصليًا)، `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` ويُصيِّرانها في `iii-config` المُشغَّل. ولا يُكتب العنوان نفسه في ذلك الملف المُصيَّر مطلقًا، بل فقط مرجع `${AGENTMEMORY_REDIS_URL}` تُوسِّعه عملية المحرك من بيئتها الخاصة عند الإقلاع. ولا يربط `iii-config.docker.yaml` للقراءة فقط دون تصيير إلا مسار Docker Compose الخاص بهذا المستودع (`AGENTMEMORY_USE_DOCKER=1`، أو استئناف محرك بدأ بتلك الطريقة مسبقًا)؛ ويُحذِّر `agentmemory start` عندما يكتشف هذا المزيج. بدِّل ذلك الملف يدويًا، باتباع نفس شكل `name: redis` / `config: redis_url: ...` الموضَّح في مستندات عمّال [iii-state](https://workers.iii.dev/workers/iii-state) و[iii-stream](https://workers.iii.dev/workers/iii-stream)، ووجِّه `redis_url` إلى Redis يمكن الوصول إليه من الحاوية. ويُمرِّر `docker-compose.yml` متغير `AGENTMEMORY_REDIS_URL` إلى حاوية المحرك، فتعمل `redis_url: '${AGENTMEMORY_REDIS_URL}'` هناك وتُبقي العنوان خارج الملف المربوط.
+
+تُبقي الإعدادات المُصيَّرة العنوان خارج `~/.agentmemory/data/iii-config.runtime.yaml`، لكن عامل الإعدادات الخاص بالمحرك نفسه لا يزال يُثبِّت القيمة *المُوسَّعة* في `~/.agentmemory/config/iii-state.yaml` و`iii-stream.yaml` بمجرد إقلاعه (يحدث توسيع `${VAR}` الخاص بـ iii-engine قبل أن يخزِّن ذلك العامل بذرته، ويخزِّن القيمة المحلولة، لا المرجع). تعامل مع ذلك الدليل بصفته يحمل بيانات اعتماد: استخدم `chmod 700 ~/.agentmemory` على أي مضيف مشترك، وفضِّل مستخدم ACL لـ Redis مُحدَّد النطاق بما يحتاجه agentmemory فقط على بيانات اعتماد مسؤول قاعدة البيانات.
+
+**الترحيل ليس آليًا.** يبدأ تبديل `AGENTMEMORY_STATE_BACKEND` من مخزن فارغ على أي من الجانبين؛ ولا شيء يُنسِّخ البيانات الموجودة من الملف إلى Redis أو بالعكس. صدِّر من الخلفية التي تتركها واستورد إلى التي تنتقل إليها. يعمل هذا بشكل متطابق تحت bash وzsh (بما في ذلك `bash -u`). أما مصفوفة مثل `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` فلا تعمل بالمثل: يحتفظ zsh بالترويسة كَكلمة واحدة مُشوَّهة حيث يقسِّمها bash إلى كلمتين، فيعيد كل من الطلبين الرمز 401 في كل مرة يكون `AGENTMEMORY_SECRET` مضبوطًا فيها:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+يقبل `/agentmemory/export` أيضًا `?maxSessions=` و`?offset=` لتقسيم مجموعة كبيرة عبر عدة استدعاءات؛ وتكون `strategy` عند الاستيراد إما `merge` (الآمن افتراضيًا)، أو `replace`، أو `skip`.
+
+### ما الذي يحل iii محله
+
+| المكدّس التقليدي | ما يستخدمه agentmemory |
+|---|---|
+| Express.js / Fastify | محفِّزات HTTP في iii |
+| SQLite / Postgres + pgvector | حالة KV في iii + فهرس متجهات في الذاكرة |
+| SSE / Socket.io | تيارات iii (WebSocket) |
+| pm2 / systemd | إشراف المحرك على العمّال في iii |
+| Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية |
+| أنظمة إضافات مخصصة | `iii worker add ` |
+
+**225 ملف مصدري · ~54,000 سطر برمجي · 2,600+ اختبار · 312 دالة · 66 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
+
+---
+
+
+
+### مزوّدو LLM
+
+يكتشف agentmemory المزوّدين تلقائيًا من بيئتك. يُتيح المزوّد العمليات المعتمدة على LLM، لكن ضبط المزوّد وحده لا يُفعِّل ضغط الملاحظات المكتوب بواسطة LLM. فذلك المسار يتطلب مزوّدًا و`AGENTMEMORY_AUTO_COMPRESS=true` معًا.
+
+| المزوّد | الإعداد | ملاحظات |
+|----------|--------|-------|
+| **بلا عملية (No-op، الافتراضي)** | لا حاجة إلى إعداد | الضغط/التلخيص المعتمد على LLM مُعطَّل. ولا يزال الضغط التركيبي واسترجاع BM25 يعملان. راجع `AGENTMEMORY_ALLOW_AGENT_SDK` أدناه إذا كنت تعتمد سابقًا على الرجوع لاشتراك Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | فوترة لكل رمز (token) |
+| MiniMax | `MINIMAX_API_KEY` | متوافق مع Anthropic |
+| Gemini | `GEMINI_API_KEY` | يُفعِّل التضمينات أيضًا |
+| OpenRouter | `OPENROUTER_API_KEY` | أي نموذج |
+| OpenAI API | `OPENAI_API_KEY` | الافتراضي `gpt-5.6-luna`، تجاوزه بـ `OPENAI_MODEL` |
+| **محلي (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) أو `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | أي شيء متوافق مع OpenAI API. بلا تكلفة، ويعمل على جهازك. راجع [النماذج المحلية](#local-models-ollama--lm-studio--vllm) أدناه. |
+| الرجوع لاشتراك Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | اختياري الانضمام فقط. يُولِّد جلسات `@anthropic-ai/claude-agent-sdk`؛ وكان يتسبب سابقًا في تكرار (recursion) غير محدود لخطاف Stop، فلم يعد الافتراضي. |
+
+### النماذج المحلية (Ollama / LM Studio / vLLM)
+
+يتحدّث agentmemory مع أي خادم متوافق مع OpenAI API، فأي خادم يُعرِّض `/v1/chat/completions` يعمل دون أي تعديل في الشفرة. لا مفاتيح مدفوعة، ولا سحابة، ولا حدود لمعدل الطلبات؛ ويعمل بالكامل على جهازك.
+
+**Ollama** (المنفذ الافتراضي `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (المنفذ الافتراضي `1234`):
+
+افتح LM Studio ← تبويب Local Server ← Start Server. اختر أي نموذج محادثة من القائمة (Qwen 3، وgpt-oss، وDeepSeek R1، وغيرها).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: نفس الصيغة. وجِّه `OPENAI_BASE_URL` إلى أي عنوان يُعرِّضه خادمك، واضبط `OPENAI_MODEL` على اسم يقبله خادمك.
+
+**اختيارات النماذج لعمل الذاكرة**: الضغط والتلخيص مهمتان قصيرتان (أقل من 2K رمز مدخل، وأقل من 500 رمز مخرج) يكفيهما نموذج instruct بحجم 7B. التوصيات:
+
+| النموذج | الحجم | السبب |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 جيجابايت | افتراضي متوازن على جهاز بـ16 جيجابايت؛ قوي في الاستخراج والنصوص الشبيهة باستدعاءات الأدوات |
+| `qwen3:4b` | ~2.6 جيجابايت | أصغر خيار منطقي؛ مناسب للضغط، وأضعف في استخراج الرسم البياني |
+| `qwen3-coder:30b` | ~19 جيجابايت | أفضل خيار محلي للجلسات الشبيهة بالشفرة (30B MoE، بـ3.3B نشطة) على أجهزة بـ24-32 جيجابايت |
+| `gpt-oss:20b` | ~14 جيجابايت | نموذج عام قوي يُناسب ذاكرة 16 جيجابايت |
+| `deepseek-r1:8b` | ~5.2 جيجابايت | تقطير استدلالي (reasoning distill)؛ أبطأ لكن استخراجاته أنظف |
+
+تُفكِّر نماذج Qwen 3 افتراضيًا، وقد تستهلك موازنة الرموز كاملةً في الاستدلال قبل أي مخرج. اضبط `AGENTMEMORY_LLM_NOTHINK=1` لإلحاق `/no_think` بمطالبات استخراج الرسم البياني، وارفع `MAX_TOKENS` (تعمل قيمة 16384) إذا عادت الاستخراجات فارغة.
+
+يمكن لنماذج فئة الاستدلال (على طراز `o1` بكتل ``) أن تُعيد `content` فارغًا مع حقل `reasoning` قد لا يُظهره خادمك المحلي. إذا عادت الاستخراجات فارغة، جرِّب نموذجًا غير استدلالي أولًا. ويمكن لمتغير البيئة `OPENAI_REASONING_EFFORT=none` أيضًا تعطيل التفكير على نماذج Ollama Cloud المُفكِّرة التي تُحاكي مخطط استدلال OpenAI.
+
+تُشحن التضمينات المحلية كاعتمادية اختيارية لكنها غير مُفعَّلة افتراضيًا. اضبط `EMBEDDING_PROVIDER=local` للانضمام إلى `Xenova/all-MiniLM-L6-v2` (384 بُعدًا). يُنزِّل أول طلب تضمين النموذج؛ ويكون الاستدلال على الجهاز نفسه بعد ذلك. وبدون ذلك الضبط أو مفتاح تضمين بعيد، تبقى المتجهات مُعطَّلة، ويستخدم `mem::search` خوارزمية BM25، ويمكن لـ `smart-search` أن يُضيف تطابقات الرسم البياني الموجودة مسبقًا.
+
+### اختيار النموذج الواعي بالتكلفة
+
+عندما يُفعَّل الضغط الخلفي المكتوب بواسطة LLM بوجود مزوّد و`AGENTMEMORY_AUTO_COMPRESS=true` معًا، فإنه يعمل على كل ملاحظة، فيُغيِّر اختيار النموذج الإنفاق الشهري بشكل ملموس. بيانات حِمل عمل مُسجَّلة: 635 طلبًا / 888 ألف رمز / 35 ساعة استخدام نشط، شُغِّلت مقابل ثلاثة نماذج من OpenRouter بتسعير 2026-05-23.
+
+| المستوى | النموذج | المدخل / مليون | المخرج / مليون | التكلفة لـ35 ساعة المُسجَّلة | ملاحظات |
+|------|-------|------------|-------------|---------------------------|-------|
+| مُوصى به | `deepseek/deepseek-v4-flash-0731` | 0.07$ | 0.14$ | ~0.07$ (تقديري) | أحدث DeepSeek؛ الخيار الأرخص المُوصى به لأعمال الضغط. |
+| مُوصى به | `deepseek/deepseek-v4-pro` | 0.435$ | 0.87$ | ~0.46$ | جودة ضغط وتلخيص جيدة بتكلفة أقل بنحو 10× من Sonnet. |
+| مُوصى به | `qwen/qwen3-coder` | 0.45$ | 1.80$ | ~0.55$ | استدلال برمجي قوي إذا كانت جلساتك شبيهة بالشفرة بكثافة. |
+| مميّز | `anthropic/claude-sonnet-5` | 3.00$ | 15.00$ | ~5.02$ (تقديري) | نفس سعر القائمة لتشغيل Sonnet 4.6 المُقاس؛ وتسعير تمهيدي 2$/10$ حتى 2026-08-31. |
+| مميّز | `openai/gpt-5.6-sol` | 5.00$ | 30.00$ | ~9$ (تقديري) | مستوى رائد؛ مكلف للعمل الخلفي الدائم التشغيل. |
+| تجنّبه | `anthropic/claude-opus-5` | 5.00$ | 25.00$ | ~8.40$ (تقديري) | نموذج من فئة رائدة؛ إنفاق زائد لعمليات الضغط. |
+
+تأتي الصفوف المقيسة من التشغيل المُسجَّل؛ وتُحجِّم صفوف (تقديري) نفس مزيج الرموز بسعر قائمة كل نموذج.
+
+يطبع agentmemory تحذيرًا وقت التشغيل عندما يطابق `OPENROUTER_MODEL` نمط المستوى المميّز. اضبط `AGENTMEMORY_SUPPRESS_COST_WARNING=1` لإسكاته بعد أن تتخذ قرارًا مدروسًا.
+
+مقايضة الجودة في مقابل التكلفة لعمل الذاكرة: الضغط مهمة تلخيص بمعايير جودة فضفاضة نسبيًا (فالوكيل هو من يُعيد قراءة الملخص، لا المستخدم). يحطّ DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ضمن هامش خطأ التقريب لـ Sonnet في هذه المهمة بتكلفة أقل بـ10-70×. احتفظ بالنماذج من المستوى المميّز للاستعلامات التي تقرأها مباشرة.
+
+المصادر: [تسعير OpenRouter لـ Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5)، و[DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731)، و[ملاحظات تسعير DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### ذاكرة متعددة الوكلاء (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+في إعدادات تعدد الوكلاء حيث تتشارك عدة أدوار خادم 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` (الافتراضي) | نعم | لا | سياق بين الوكلاء مع مسار تدقيق. يمكن للمهندس المعماري رؤية ما لاحظه المطوِّر، لكن كل صف يُسجِّل من قاله. |
+| `isolated` | نعم | نعم | انفصال صارم. لا يرى المهندس المعماري أبدًا ملاحظات/ذكريات/جلسات المطوِّر. |
+
+ما الذي يُوسَم عند ضبط `AGENT_ID`: `Session.agentId`، و`RawObservation.agentId`، و`CompressedObservation.agentId`، و`Memory.agentId`. ويتدفّق الدور من `api::session::start` ← `mem::observe` ← `mem::compress` ← KV.
+
+ما الذي يُرشَّح في الوضع المعزول: `mem::smart-search`، و`/agentmemory/memories`، و`/agentmemory/observations`، و`/agentmemory/sessions`. تقبل كل نقطة نهاية `?agentId=` للتجاوز في كل طلب على حدة، و`?agentId=*` للخروج من نطاق متغير البيئة بالكامل. ويقبل `/memories` أيضًا `?includeOrphans=true` لإظهار الذكريات السابقة لـ AGENT_ID التي يكون `agentId` فيها غير مُحدَّد.
+
+التجاوز لكل استدعاء على مستوى SDK / REST: تقبل كل نقطة نهاية مُغيِّرة (`/session/start`، و`/remember`) حقل `agentId` في جسم الطلب يتغلّب على متغير البيئة. مفيد لبيئات تشغيل تُوجِّه أدوارًا عديدة عبر عملية خادم واحدة. وتُظهر أداة MCP `memory_save` حقل `agentId` نفسه، ويُمرِّر خادم stdio القائم بذاته كلًا من `agentId` و`project`، وتحمل الذكريات المحفوظة `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 | عامل التيارات الداخلي (يستهلكه agentmemory + العارض) | `III_STREAM_PORT` (مُفضَّل) أو `III_STREAMS_PORT` القديم |
+| `3113` | agentmemory | العارض اللحظي (`http://localhost:3113`) | `III_VIEWER_PORT` أو `AGENTMEMORY_VIEWER_URL` للعنوان المُعلَن |
+| `49134` | iii-engine | WebSocket؛ يُسجِّل العمّال هنا، ويتدفّق قياس OTel عبره | `III_ENGINE_PORT` أو `III_ENGINE_URL` |
+
+يُغيِّر `--port ` مرساة REST ويستمد منفذ التيارات `N+1`، والعارض `N+2`، وWebSocket المحرك `N+46023`، فقط حيث يكون المنفذ أو العنوان الصريح المقابل أعلاه غير مضبوط. ولا يُنشئ مساحة أسماء دورة حياة معزولة. استخدم `--instance 1` لعفريت (daemon) ثانٍ؛ فهو يستخدم المرساة 3211، وافتراضيًا `3211/3212/3213/49234`، ويحصل على دليل بيانات ودورة حياة منفصل باسم `instance-1`. وتتبع النُّسخ من 1 إلى 50 النمط نفسه.
+
+يبدأ المحرك المثبَّت بخيار `--no-update-check` (بلا أي بحث عن تحديثات أو تنبيهات أمنية مقابل GitHub عند الإقلاع) ومع تعطيل قياس الاستخدام المجهول لـ iii: يضبط agentmemory `III_TELEMETRY_ENABLED=false` للمحرك الذي يُولِّده إلا إذا صدَّرت المتغير بنفسك، ويفعل ملف compose المُضمَّن الشيء نفسه.
+
+تنظيف العمليات العالقة عندما تظل المنافذ مربوطة بعد تشغيل منهار:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+يحصد `agentmemory stop` كلًا من ملف pid الخاص بالعامل والمحرك بنظافة عند الإيقاف الأصلي السَّلِس (graceful). وفي وضع Docker، يُفرِّغ العامل الأصلي، ويُوقِف حاوية المحرك المُصادَق عليها تحديدًا، ويحافظ على كلٍّ من الحاوية وربطها بـ `/data` لإعادة تشغيل بلا فقد بيانات؛ ويتحقق التشغيل التالي من تلك الحاوية نفسها ويستأنفها. ويتطلب إلغاء التثبيت المعتمد على Docker أمر `agentmemory remove --keep-data`: فهو يحذف ملفات agentmemory المُشتركة والمُدارة بينما يحافظ على الحاوية المُصادَق عليها، وربط بياناتها، وسجل دورة الحياة اللازم لاستعادتها. ويُترَك حذف بيانات Docker المدمِّر عمدًا للمُشغِّل بعد نسخة احتياطية. وترفض الواجهة الطرفية CLI أيضًا تبنّي أو إرسال إشارة إلى حائزي منافذ Docker أو الأجهزة الافتراضية (خلفية Docker، أو vpnkit، أو colima) باعتبارهم المحرك الأصلي إلا إذا مُرِّرت `--force`. والتنظيف اليدوي أعلاه مخصص فقط لحالة ما بعد الانهيار التي لا يُترَك فيها أي ملف pid.
+
+### ملف الإعدادات
+
+ضع إعدادات بيئة تشغيل agentmemory في `~/.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
+```
+
+لتجربته باستخدام اشتراك Claude Code Pro/Max بدلًا من مفتاح API، انضم اختياريًا وبشكل صريح:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+يتطلب ضغط الملاحظات المكتوب بواسطة LLM السطرين معًا: الوصول إلى مزوّد LLM (بما في ذلك هذا الرجوع الصريح للاشتراك) و`AGENTMEMORY_AUTO_COMPRESS=true`. ويترك المزوّد وحده مسار الضغط التركيبي الافتراضي كما هو.
+
+يكون التوحيد (عُقَد الرسم البياني، والدروس المستفادة، والبلورات) مُفعَّلًا افتراضيًا كلما ضُبط مزوّد LLM. استثنِ نفسك صريحًا بـ `CONSOLIDATION_ENABLED=false` إذا أردت تشغيلًا بلا LLM. واستخراج الرسم البياني راية مستقلة:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### متغيرات البيئة
+
+أنشئ `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer `، وتتطلب نقاط نهاية مزامنة mesh ضبط `AGENTMEMORY_SECRET` صريحًا على كلا الطرفين.
+
+**المصادقة مُفعَّلة افتراضيًا.** عندما لا يكون `AGENTMEMORY_SECRET` مضبوطًا (في الصدفة أو في `~/.agentmemory/.env`)، يُولِّد الخادم سرًا عشوائيًا عند أول تشغيل ويخزِّنه في `~/.agentmemory/secret` بوضع صلاحيات `0600`. ويقرؤه كل عميل مُضمَّن من هناك عند التحدث إلى خادم محلي: الواجهة الطرفية CLI، والعارض، والخطافات تحت `plugin/scripts`، وخادم MCP والوسيط `@agentmemory/mcp`، والإعدادات التي يكتبها `agentmemory connect`، وتكاملات OpenCode وPi وOpenClaw وHermes ومراقب نظام الملفات (filesystem-watcher) المُضمَّنة. ولا يُرسَل السر المخزَّن إلا إلى عناوين loopback (`localhost`، و`127.0.0.0/8`، و`::1`). ويتغلّب `AGENTMEMORY_SECRET` الصريح دائمًا، ولا يزال العملاء البعيدون بحاجة إلى ضبطه. وتُولِّد Docker وقوالب [`deploy/`](../deploy/) سرها الخاص وتُصدِّره مسبقًا. ولاستدعاء الواجهة البرمجية يدويًا:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**قواعد الطلبات للكتابة.** يجب أن تُرسِل طلبات `POST` و`PUT` و`PATCH` و`DELETE` إلى REST API والعارض ترويسة `Content-Type: application/json` (مُعامل `charset` مقبول) كلما حملت جسمًا، وترويسة `Origin`، عند وجودها، يجب أن تكون أصلًا من نوع loopback لمنفذ REST أو العارض المضبوط، أو مُدرَجة في `VIEWER_ALLOWED_ORIGINS` (مفصولة بفواصل، مثل `https://memory.example.com`). أما العملاء الذين لا يُرسلون ترويسة `Origin` (CLI، والخطافات، وMCP، وcurl، ومن خادم إلى خادم) فلا يتأثرون. ويقبل العارض أيضًا أصله الخاص.
+
+**مسارات الملفات.** لا تقبل نقاط النهاية التي تقرأ أو تكتب ملفات (`/compress-file`، و`/replay/import-jsonl`، و`/graph/import-graphify`) إلا مسارات تحت `~/.agentmemory`، أو دليل بيانات النسخة، أو دليل مُدرَج في `AGENTMEMORY_IMPORT_ROOT` (فصل عدة مسارات بـ `:`، أو بـ `;` على Windows). ويقبل `/replay/import-jsonl` أيضًا مساره الافتراضي `~/.claude/projects`. ويبقى `/obsidian/export` داخل `AGENTMEMORY_EXPORT_ROOT` و`/migrate` داخل `~/.agentmemory`. وتُحلّ الروابط الرمزية (symlinks) قبل كل فحص.
+
+**تنقية الأسرار.** تُحذف مفاتيح API، ورموز الحامل (bearer tokens)، وكتل مفاتيح PEM الخاصة، وبيانات الاعتماد المُضمَّنة في العناوين (`scheme://user:password@host`) قبل تخزين النص، في كل مسار كتابة: الملاحظات، والحفظ، والتطور، والفُتحات (slots)، والدروس المستفادة، والإجراءات، والرسوم التخطيطية، والإشارات، ونقاط التحقق، والاستيرادات، وإعادة تشغيل jsonl، ومزامنة mesh، ومشاركات الفريق، ومخرجات الضغط والتلخيص، والبلورات، وعُقَد الرسم البياني.
+
+
+نقاط النهاية الأساسية
+
+| الطريقة | المسار | الوصف |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | فحص الحالة الصحية (عام دائمًا) |
+| `GET` | `/agentmemory/status` | ما الخطأ وكيفية إصلاحه (HTML للمتصفحات، JSON في الحالات الأخرى) |
+| `GET` | `/agentmemory/viewer/snapshot` | كل ما يُظهره العارض، في استجابة واحدة |
+| `POST` | `/agentmemory/session/start` | بدء الجلسة + الحصول على السياق |
+| `POST` | `/agentmemory/session/end` | إنهاء الجلسة |
+| `POST` | `/agentmemory/observe` | التقاط ملاحظة (راجع تسليم الالتقاط أدناه) |
+| `GET` | `/agentmemory/capture` | صندوق وارد الالتقاط، والرسائل المتعطّلة، والتخزين المؤقت دون اتصال |
+| `POST` | `/agentmemory/capture/retry` | إعادة محاولة الالتقاطات المتعطّلة |
+| `POST` | `/agentmemory/capture/drain` | إرسال التخزين المؤقت المحلي دون اتصال الآن |
+| `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/graph/compact` | تقليص مصدرية الرسم البياني المتضخمة |
+| `POST` | `/agentmemory/team/share` | المشاركة مع الفريق |
+| `GET` | `/agentmemory/audit` | مسار التدقيق |
+
+قائمة نقاط النهاية الكاملة: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**تسليم الالتقاط.** تُرسل الخطافات كل ملاحظة مرة واحدة إلى `POST /agentmemory/observe` مع `eventId`. وهو معرّف المضيف الخاص بالاستدعاء عندما تحمله الحمولة (مثل `tool_use_id` في Claude Code)، وإلا فهو بصمة (hash) للجلسة، ونوع الخطاف، واسم الأداة، والمدخل، والمخرج، والطابع الزمني للمضيف. يكتب الخادم الحدث إلى صندوق وارد الالتقاط في مخزن الحالة، ويخزِّن الملاحظة، ثم يحذف إدخال صندوق الوارد. ويُخبرك رمز الحالة بما حدث:
+
+| رمز الحالة | حقل `status` | المعنى |
+|---|---|---|
+| `201` | `accepted` | تم التخزين. `observationId` هو الملاحظة الجديدة. |
+| `202` | `accepted` (`state: "retrying"`) | تم القبول، لكن التخزين فشل. يعيد الخادم محاولته، أيضًا بعد إعادة التشغيل. |
+| `200` | `duplicate` | تم قبول `eventId` هذا مسبقًا. `observationId` هو الملاحظة الموجودة؛ ولا يُخزَّن أي شيء جديد. |
+| `400` / `422` | `rejected` | حمولة غير صالحة، أو فشل التخزين نهائيًا (يُحفظ الحدث كرسالة متعطّلة). |
+| `503` | `rejected` (`retryable: true`) | صندوق الوارد ممتلئ (`AGENTMEMORY_CAPTURE_INBOX_MAX`). تُخزِّن الخطافات الحدث مؤقتًا وترسله لاحقًا. |
+
+تُعاد محاولة الأحداث الفاشلة كل `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 ثوان) بتراجع تدريجي مُضاعِف، حتى `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). وتبقى الأحداث التي لا تزال تفشل في صندوق الوارد كرسائل متعطّلة، وتُسرَد في `/agentmemory/status` وصفحة الحالة الصحية في العارض، ويمكن إعادة محاولتها بـ `POST /agentmemory/capture/retry` (`{"eventId": "..."}` أو `{"all": true}`). وتُتذكَّر معرّفات الأحداث المقبولة لمدة `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 ساعة، وبحد أقصى `AGENTMEMORY_CAPTURE_EVENTS_MAX` معرّفًا)، فيُخزَّن خطاف أُعيد تشغيله بعد انتهاء مهلة أو إعادة تشغيل مرة واحدة فقط، بينما يُخزَّن استدعاءا أداة منفصلان بمعرّفي مضيف خاصين بهما مرتين حتى لو كان محتواهما متطابقًا. وعندما تُحذف ملاحظة (نسيان، أو حذف جلسة، أو طرد، أو نسيان تلقائي، أو استيراد يستبدل المخزن)، يُوسَم حدثها بأنه محذوف قبل إزالة الملاحظة، فتُجاب إعادة تشغيل ذلك الحدث داخل النافذة الزمنية نفسها باعتبارها تكرارًا ولا تُخزِّن شيئًا. يكتب مخزن الحالة إلى القرص كل ثانيتين، فقد تبقى إجابة حدث مُجاب في الذاكرة فقط للحظة. ولتغطية ذلك، تحمل كل إجابة من فئة `2xx` أيضًا `bootId` الخادم (جديد في كل بدء تشغيل)، و`acceptedAt`، و`durableAfterMs` (مدة الحفظ زائد 1.5 ثانية على مخزن الملفات، و1.5 ثانية على redis، حيث يكون الاستمرار من ضبط المُشغِّل). تحتفظ الخطافات بالحدث في التخزين المؤقت المحلي إلى أن تنقضي تلك النافذة الزمنية، وتحذفه في استدعاء لاحق دون طلب آخر. وإذا تغيَّر `bootId` بحلول ذلك الوقت، فهذا يعني أن الخادم أعاد التشغيل، فيُرسِل الخطاف الحدث مرة أخرى بنفس `eventId`؛ ولا يُخزَّن حدث وصل فعلًا إلى القرص مرتين. ويُرسِل الخادم نفسه أيضًا تلك الأحداث عند البدء وفي كل فاصل إعادة محاولة، فلا تفقد إعادة التشغيل أي شيء حتى لو لم يعمل أي خطاف بعد ذلك. وتتجاهل الخطافات القديمة الحقول الإضافية، وتتخلى الخطافات الجديدة عن الحدث عند `2xx` مقابل خادم أقدم كما كان الحال سابقًا.
+
+وعندما يكون الخادم متوقفًا، أو لا يُجيب في الوقت المناسب، أو يُعيد 5xx، يُلحق الخطاف الملاحظة بملف تخزين مؤقت محلي، `/capture-spool/-.jsonl` (تجاوز المجلد بـ `AGENTMEMORY_CAPTURE_SPOOL_DIR`). الملف خاص بمستخدمك (وضع صلاحيات 600)، وتُحذف الأسرار منه بنفس الطريقة التي يحذفها الخادم بها، ويحمل بحد أقصى `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 ميبيبايت)، ويُسقِط الإدخالات الأقدم من `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). وعندما يكون ممتلئًا، تُسقَط الإدخالات الجديدة وتُعَدّ، ويُسجِّل `/agentmemory/status` ذلك. ولا يزال الخطاف يخرج بالرمز 0 ضمن حده الزمني ولا يُضيف أي طلب عندما يكون الخادم سليمًا. ويُرسَل التخزين المؤقت عند البدء التالي وبواسطة أول خطاف يصل إلى الخادم مرة أخرى، في عملية خلفية حتى لا ينتظر الوكيل. ومعرّفات الأحداث تجعل ذلك آمنًا: فالملاحظة التي وصلت فعلًا قبل انتهاء المهلة لا تُخزَّن مرتين. يُظهر أمر `npx @agentmemory/agentmemory capture` التخزين المؤقت وصندوق وارد الخادم، ويرسل `--drain` التخزين المؤقت الآن، ويُعيد `GET /agentmemory/capture` الشيء نفسه كـ JSON. اضبط `AGENTMEMORY_CAPTURE_SPOOL=false` لتعطيل التخزين المؤقت.
+
+**ضغط مصدرية الرسم البياني.** تحتفظ كل عقدة وحافة في الرسم البياني المعرفي بمعرّفات أحدث 32 ملاحظة أتت منها. وقد تحمل المخازن المكتوبة قبل ذلك الحد آلاف المعرّفات لكل عقدة نشطة، وهذا يُبطئ بحث الرسم البياني والعارض أو يُسقِط العامل. ويُصلح agentmemory ذلك بنفسه: في أول تشغيل بعد الترقية، يُقلِّص كل عقدة، وحافة، وحافة مُستبدَلة (تاريخ الرسم البياني الزمني)، واللقطة المخبَّأة إلى الحد في الخلفية، في شرائح صغيرة مع توقّف بينها، بحيث يستمر البحث والالتقاط والعارض في العمل. ويحفظ تقدّمه، ويستأنف بعد إعادة التشغيل، ولا يعمل مرة أخرى أبدًا بعد أن ينتهي. ويُظهره `/agentmemory/status` وصفحة الحالة الصحية في العارض بصفته معلَّقًا، أو قيد التشغيل (مع النطاق والموضع الحاليين)، أو مكتملًا، أو فاشلًا. اضبط `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` لتعطيله.
+
+لتشغيله يدويًا، استدعِ `POST /agentmemory/graph/compact`. فهو يتجوّل عبر فهارس الأسماء ومفاتيح الحواف بدلًا من سرد كل عقدة وحافة، وهو آمن لإعادة التشغيل. وعندما يُقلِّص المعرّفات، يكتب إدخال تدقيق `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+في مخزن كبير، أو عندما يُعيد الاستدعاء 504، شغِّله على شرائح. أرسل `scope` (`nodes` أو `edges` أو `history`)، و`offset`، و`limit`، ثم استدعِ مجددًا بالقيمة المُعادة `nextOffset` إلى أن تصبح `null`. فعل ذلك لـ `nodes` و`edges` و`history`، وأنهِ باستدعاء واحد لـ `{"scope":"snapshot"}`، لأن تشغيلًا على شرائح لا يلمس اللقطة المخبَّأة.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**المتطلبات الأساسية:** Node.js بإصدار 20 أو أحدث مع npm/npx؛ و[iii-engine](https://iii.dev/docs) بالإصدار v0.22.1 أو Docker. ويتطلب تثبيت المحرك الآلي على macOS/Linux أيضًا `curl` وصدفة POSIX من نوع `sh` وأداة `tar`؛ ويستخدم Windows الأصلي ملف `iii.exe` المثبَّت اليدوي، أو WSL2، أو Docker Desktop.
+
+
+
+[Apache-2.0](../LICENSE)
+
+
diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.md
new file mode 100644
index 0000000000..decacdc164
--- /dev/null
+++ b/READMEs/README.bn-BD.md
@@ -0,0 +1,1872 @@
+
+
+
+
+
+
+ আপনার কোডিং এজেন্ট সবকিছু মনে রাখে। আর বারবার ব্যাখ্যা করতে হয় না।
+ iii engine-এর উপর তৈরি
+
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode এবং যে কোনো MCP ক্লায়েন্টের জন্য স্থায়ী মেমরি।
+
+ এই গিস্টটি Karpathy-র LLM Wiki প্যাটার্নকে কনফিডেন্স স্কোরিং, লাইফসাইকেল, নলেজ গ্রাফ এবং হাইব্রিড সার্চ দিয়ে সম্প্রসারিত করে: agentmemory হলো তার বাস্তবায়ন।
+
+
+---
+
+## ইনস্টল
+
+প্রয়োজনীয়তা:
+
+- Node.js 20 বা তার নতুন সংস্করণ, npm এবং npx সহ (`node -v`, `npm -v`, এবং `npx -v`)।
+- macOS/Linux-এ iii-engine-এর স্বয়ংক্রিয় ইনস্টলেশনের জন্য `curl`, একটি POSIX `sh`, এবং `tar`-ও প্রয়োজন। `node:20-slim`-এর মতো মিনিমাল ইমেজে এগুলো থাকতে পারে না।
+- নেটিভ Windows-এ পিন করা iii-engine v0.22.1 `iii.exe` ম্যানুয়ালি ইনস্টল করতে হয়। WSL2 বা Docker Desktop অন্য সাপোর্টেড পথ।
+
+ক্যানোনিকাল ফ্রেশ-ইনস্টল কমান্ড:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+প্রথম রান একটি ইন্টারঅ্যাক্টিভ সেটআপ: কোন এজেন্টগুলো ওয়্যার করবেন তা বেছে নিন (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), একটি LLM প্রোভাইডার বাছুন বা কিলেস থাকুন, আর এটি কনফিগ সিড করে, মেমরি সার্ভার ও তার পিন করা iii engine চালু করে, এবং গ্লোবালি ইনস্টল করার প্রস্তাব দেয় যাতে পরে যেকোনো জায়গায় খালি `agentmemory` কমান্ড কাজ করে। `-y` npx-এর প্যাকেজ প্রম্পট মেনে নেয় এবং `@latest` কোনো পুরোনো ক্যাশড রিলিজ এড়িয়ে যায়। একটি প্রোভাইডার LLM ফিচারগুলো উপলব্ধ করে, কিন্তু LLM-লিখিত অবজারভেশন কম্প্রেশন শুরু হয় তখনই যখন `AGENTMEMORY_AUTO_COMPRESS=true`-ও সেট করা থাকে।
+
+কিলেস মোডে ভেক্টর এমবেডিং বন্ধ থাকে। `memory_recall` (`mem::search` পাথ) BM25 ব্যবহার করে, আর `memory_smart_search` গ্রাফ ডেটা থাকলে স্ট্রাকচারাল গ্রাফ ম্যাচও মিশিয়ে দিতে পারে। ফ্রি অন-ডিভাইস সিম্যান্টিক রিকল পেতে, `~/.agentmemory/.env`-এ `EMBEDDING_PROVIDER=local` সেট করে রিস্টার্ট করুন। প্রথম এমবেডিং রিকোয়েস্ট `Xenova/all-MiniLM-L6-v2` ডাউনলোড করে; সেই প্রাথমিক মডেল ডাউনলোডের পর ইনফারেন্স লোকালি চলে।
+
+লোকাল রানটাইম চারটি পোর্ট ব্যবহার করে: REST/MCP HTTP-র জন্য `3111`, iii স্ট্রিমের জন্য `3112`, ভিউয়ারের জন্য `3113`, এবং iii ওয়ার্কার WebSocket-এর জন্য `49134`। স্থায়ী iii স্টেট থাকে macOS-এ `~/Library/Application Support/agentmemory`-তে, Linux-এ `$XDG_DATA_HOME/agentmemory` বা `~/.local/share/agentmemory`-তে, এবং Windows-এ `%APPDATA%\agentmemory`-তে। এটি ওভাররাইড করতে `--data-dir ` বা `AGENTMEMORY_DATA_DIR` ব্যবহার করুন, এবং প্রতি রিস্টার্টে একই ভ্যালু পুনরায় ব্যবহার করুন। ব্যাকওয়ার্ড কম্প্যাটিবিলিটির জন্য, ইনস্ট্যান্স 0-এর জন্য প্ল্যাটফর্মের ডিফল্টের চেয়ে আগে থেকে থাকা `./data/state_store.db` বা `./data/iii-config.yaml`-কে প্রাধান্য দেওয়া হয়; একটি এক্সপ্লিসিট ফ্ল্যাগ বা এনভায়রনমেন্ট ওভাররাইড তখনও জেতে।
+
+তারপর প্রমাণ করুন রিকল কাজ করছে এবং আপনার এজেন্টকে তার স্কিল দিন:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+ডিফল্ট কিলেস মোডে কিওয়ার্ড সার্চগুলো BM25-র মাধ্যমে হিট করার কথা। ডেমোর `database performance optimization` কোয়েরি উদ্দেশ্যমূলকভাবে সিম্যান্টিক, আর একটি এমবেডিং প্রোভাইডার কনফিগার না করা পর্যন্ত এটি শূন্য রিটার্ন করতে পারে।
+
+একটি কোডিং এজেন্টকে পুরো কাজটা করতে দিতে চান? তাকে একটা মাত্র ইন্সট্রাকশন দিন:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+`agentmemory connect `-এর মাধ্যমে যেকোনো সময় আরও এজেন্ট ওয়্যার করুন — [Works with every agent](#works-with-every-agent)-এ ২০টি অ্যাডাপ্টার তালিকাভুক্ত আছে। সম্পূর্ণ কমান্ড রেফারেন্স [Quick Start](#quick-start)-এ।
+
+
+Windows
+
+সবচেয়ে সহজ পথ WSL2। নেটিভ Windows ইঞ্জিন সেটআপের জন্য পিন করা v0.22.1 ZIP ডাউনলোড করে `iii.exe` ম্যানুয়ালি এক্সট্র্যাক্ট করতে হয়; CLI এটি অটো-এক্সট্র্যাক্ট করে না। Docker Desktop-ও সাপোর্টেড। স্টেপ-বাই-স্টেপের জন্য [Windows notes](#windows) দেখুন।
+
+
+
+
+Global install / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+উপরের npx কমান্ডটিই ক্যানোনিকাল ফ্রেশ-ইনস্টল পথ থেকে যায় এবং গ্লোবাল-প্রিফিক্স পারমিশন সমস্যা এড়ায়।
+
+
+
+
+npx পুরোনো ভার্সন সার্ভ করছে
+
+npx প্রতি ভার্সন অনুযায়ী ক্যাশ করে। `npx -y @agentmemory/agentmemory@latest` দিয়ে লেটেস্ট ফোর্স করুন, বা একবার ক্যাশ পরিষ্কার করুন `rm -rf ~/.npm/_npx` দিয়ে (macOS/Linux; Windows-এ `%LOCALAPPDATA%\npm-cache\_npx` ডিলিট করুন)।
+
+
+
+
+নিজের iii engine ইতিমধ্যে চলছে
+
+agentmemory iii-engine v0.22.1 পিন করে এবং অন্য ভার্সনের সাথে অ্যাটাচ করবে না (ওয়ার্কার অন্য ইঞ্জিনের প্রোটোকল বলতে পারে না)। অন্য ইঞ্জিনটি থামান, তারপর `npx -y @agentmemory/agentmemory@latest` চালান। এটি পিন করা v0.22.1 `~/.agentmemory/bin`-এ ইনস্টল ও রান করে, আপনার নিজের `iii` অক্ষতই রাখে।
+
+
+
+---
+
+
+
+agentmemory এমন যেকোনো এজেন্টের সাথে কাজ করে যা হুক, MCP, বা REST API সাপোর্ট করে। সব এজেন্ট একই মেমরি সার্ভার শেয়ার করে।
+
+
+
+
+
+Claude Code
+নেটিভ প্লাগইন + 12 হুক + MCP
+
+
+
+Codex CLI
+নেটিভ প্লাগইন + 6 হুক + MCP
+
+
+
+GitHub Copilot CLI
+MCP + প্লাগইন হুক/স্কিল
+
+
+
+Cursor
+নেটিভ প্লাগইন + 7 হুক + MCP
+
+
+
+OpenCode
+ক্যাপচার প্লাগইন + MCP
+
+
+
+
+
+Devin
+6 হুক + স্কিল + MCP
+
+
+
+OpenClaw
+নেটিভ প্লাগইন + MCP
+
+
+
+Hermes
+নেটিভ প্লাগইন + MCP
+
+
+
+pi
+নেটিভ প্লাগইন + MCP
+
+
+
+OpenHuman
+নেটিভ Memory trait ব্যাকএন্ড
+
+
+
+
+
+Gemini CLI
+MCP সার্ভার
+
+
+
+Antigravity
+MCP + হুক
+
+
+
+Claude Desktop
+MCP সার্ভার
+
+
+
+Warp
+connect + MCP + স্কিল
+
+
+
+Zed
+MCP সার্ভার
+
+
+
+
+
+Cline
+MCP সার্ভার
+
+
+
+Continue
+MCP সার্ভার
+
+
+
+Droid
+MCP সার্ভার
+
+
+
+Kiro
+MCP সার্ভার
+
+
+
+Qwen Code
+MCP সার্ভার
+
+
+
+
+
+DeepSeek Harness
+MCP সার্ভার
+
+
+
+Roo Code
+MCP সার্ভার
+
+
+
+Kilo Code
+MCP সার্ভার
+
+
+
+Goose
+MCP সার্ভার
+
+
+
+Aider
+REST API
+
+
+
+
+
+ MCP বা HTTP বলতে পারা যে কোনো এজেন্টের সাথে কাজ করে। একটি সার্ভার, এবং সবার মধ্যে শেয়ার করা মেমরি।
+
+
+---
+
+আপনি প্রতি সেশনে একই আর্কিটেকচার ব্যাখ্যা করেন। আপনি একই বাগ আবার খুঁজে পান। আপনি একই পছন্দগুলো পুনরায় শেখান। বিল্ট-ইন মেমরি (CLAUDE.md, .cursorrules) ২০০ লাইনে আটকে যায় এবং বাসি হয়ে যায়। agentmemory এটা ঠিক করে। এটি নিঃশব্দে আপনার এজেন্ট যা করে তা ক্যাপচার করে, সার্চযোগ্য মেমরিতে কম্প্রেস করে, এবং পরের সেশন শুরু হলে সঠিক কনটেক্সট ইনজেক্ট করে। একটি কমান্ড। সব এজেন্টে কাজ করে।
+
+**কী বদলে যায়:** সেশন ১-এ আপনি JWT auth সেটআপ করলেন। সেশন ২-এ আপনি রেট লিমিটিং চাইলেন। এজেন্ট আগে থেকেই জানে আপনার auth `src/middleware/auth.ts`-এ jose middleware ব্যবহার করে, আপনার টেস্ট টোকেন ভ্যালিডেশন কভার করে, এবং আপনি Edge কম্প্যাটিবিলিটির জন্য jsonwebtoken-এর বদলে jose বেছে নিয়েছিলেন — আর কোনো পুনরায় ব্যাখ্যা বা কপি-পেস্ট ছাড়াই।
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+ডিফল্টভাবে, agentmemory আপনি যে রেপো থেকে এটি চালু করেছেন তার বাইরে iii-engine স্টেট জমা রাখে: macOS-এ `~/Library/Application Support/agentmemory`, Linux-এ `$XDG_DATA_HOME/agentmemory` বা `~/.local/share/agentmemory`, এবং Windows-এ `%APPDATA%\agentmemory`। একটি পুরোনো `./data/state_store.db` বা `./data/iii-config.yaml` থাকলে, প্ল্যাটফর্ম ডিফল্টের আগে ইনস্ট্যান্স 0-এর জন্য সেটিই পুনরায় ব্যবহার করা হয়। স্পষ্টভাবে একটি লোকেশন বেছে নিতে, `--data-dir ` পাস করুন বা `AGENTMEMORY_DATA_DIR` সেট করুন; এই দুটি এক্সপ্লিসিট সেটিংই লিগ্যাসি ডিসকভারির উপর প্রাধান্য পায়:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+নেটিভ এবং Docker লঞ্চ একই রিজলভড হোস্ট ডিরেক্টরি ব্যবহার করে; Docker এটি `/data`-এ বাইন্ড-মাউন্ট করে। `--instance 1` রিজলভড ডিরেক্টরিতে `instance-1` যুক্ত করে এবং আলাদা ডিফল্ট পোর্ট চতুষ্টয় `3211/3212/3213/49234` বেছে নেয়।
+
+সর্বশেষ রিলিজ নোট: [CHANGELOG.md](../CHANGELOG.md)।
+
+---
+
+
+
+
+
+
+
+### রিট্রিভাল অ্যাকুরেসি
+
+**coding-agent-life-v1** (ইন-হাউস করপাস, স্যান্ডবক্সে রিপ্রোডিউসযোগ্য)
+
+| অ্যাডাপ্টার | P@5 | R@5 | টপ-5 হিট রেট | p50 লেটেন্সি |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep বেসলাইন | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+এই করপাসের জন্য **P@5-এর গাণিতিক সর্বোচ্চ সীমায় (0.240, স্কোরকার্ড দেখুন)** 100% টপ-5 হিট রেট। Hybrid প্রতিটি গোল্ড সেশন রিট্রিভ করে; multi-session temporal কোয়েরিতে grep 2টির মধ্যে 1টি গোল্ড মিস করে। উন্নতিটা **রিকল + টেম্পোরাল**-এর, অ্যাগ্রিগেট প্রিসিশনের নয়। এই বেঞ্চমার্কটি ছোট এবং গোল্ড-স্পার্স; নিচের বড় LongMemEval-S আরও ভালোভাবে পার্থক্য দেখায়। প্রতি-টাইপ সম্পূর্ণ ব্রেকডাউন + সংশোধন নোট: [`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% |
+
+
+
+> এমবেডিং মডেল: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, 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)-এর সাথে ভালোভাবে জুটি বাঁধে।** কোড-গ্রাফ ইনডেক্সিং, মাল্টি-এজেন্ট বিল্ড পাইপলাইন, এবং docs / PDF / ছবি / ভিডিও জুড়ে বিস্তৃত নলেজ গ্রাফ। agentmemory কাজটা মনে রাখে; এই তিনটি প্রজেক্ট কনটেক্সট লেয়ারের বাকি অংশ আলোকিত করে। রেসিপি + প্রশ্ন-রাউটিং টেবিল: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md)।
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
বিল্ট-ইন (CLAUDE.md)
+
+
+
ধরন
+
মেমরি ইঞ্জিন + MCP সার্ভার
+
মেমরি লেয়ার API
+
সম্পূর্ণ এজেন্ট রানটাইম
+
পার্সোনাল AI
+
মেমরি API + অ্যাপ
+
টিম মেমরি হাব (LLM প্রক্সি)
+
ভেক্টর মেমরি (OSS)
+
মেমরি ইঞ্জিন (Oracle DB)
+
মেমরি সিস্টেম
+
স্ট্যাটিক ফাইল
+
+
+
রিট্রিভাল R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
স্ব-ঘোষিত
+
PersonaMem 76% (স্ব-ঘোষিত)
+
~96.6% (স্ব-ঘোষিত)
+
94.4% (স্ব-ঘোষিত)
+
N/A
+
N/A (grep)
+
+
+
অটো-ক্যাপচার
+
12 হুক (ম্যানুয়াল পরিশ্রম শূন্য)
+
ম্যানুয়াল add() কল
+
এজেন্ট সেলফ-এডিট
+
ম্যানুয়াল
+
API-সাইড এক্সট্রাকশন
+
প্রক্সি ইন্টারসেপশন (base-URL সোয়াপ)
+
ম্যানুয়াল
+
API এক্সট্রাকশন
+
ম্যানুয়াল
+
ম্যানুয়াল এডিটিং
+
+
+
সার্চ
+
BM25 + Vector + Graph (RRF ফিউশন)
+
Vector + Graph
+
Vector (আর্কাইভাল)
+
সিম্যান্টিক
+
Vector + RAG
+
4 ধরনের অ্যাসেট (Chat / Skill / Wiki / CodeGraph)
+
কেবল Vector
+
Vector + সিম্যান্টিক
+
ডিকে-ওয়েটেড
+
সব কনটেক্সটে লোড করে
+
+
+
মাল্টি-এজেন্ট
+
MCP + REST + lease + signal
+
API (কোনো কো-অর্ডিনেশন নেই)
+
কেবল Letta রানটাইমের মধ্যে
+
না
+
না
+
টিম রোল + শেয়ার্ড অ্যাসেট
+
না
+
কেবল স্কোপড
+
মাল্টি-এজেন্ট শেয়ার্ড
+
প্রতি-এজেন্ট ফাইল
+
+
+
ফ্রেমওয়ার্ক লক-ইন
+
নেই (যেকোনো MCP ক্লায়েন্ট)
+
নেই
+
বেশি (Letta-ই ব্যবহার করতে হবে)
+
স্ট্যান্ডঅ্যালোন
+
নেই
+
প্রক্সি প্রতিটি মডেল কলের সামনে থাকে
+
নেই
+
Oracle Database
+
নেই
+
প্রতি-এজেন্ট ফরম্যাট
+
+
+
এক্সটার্নাল ডিপেন্ডেন্সি
+
নেই (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + ভেক্টর DB
+
একাধিক
+
ম্যানেজড ক্লাউড
+
Docker স্ট্যাক (Core + Hub + Proxy)
+
ভেক্টর স্টোর
+
Oracle AI Database
+
নেই
+
নেই
+
+
+
মেমরি লাইফসাইকেল
+
4-টায়ার কনসোলিডেশন + ডিকে + অটো-ফরগেট
+
প্যাসিভ এক্সট্রাকশন
+
এজেন্ট-ম্যানেজড
+
ম্যানুয়াল
+
অটো-ফরগেট
+
ম্যানুয়াল রিভিউ; অটো-রাউটিং চলছে
+
নেই
+
বলা নেই
+
ডিকে + কনসোলিডেশন
+
ম্যানুয়াল প্রুনিং
+
+
+
টোকেন এফিশিয়েন্সি
+
~1,900 টোকেন/সেশন ($10/বছর)
+
ইন্টিগ্রেশন অনুযায়ী ভিন্ন
+
কোর মেমরি কনটেক্সটে থাকে
+
ভিন্ন হয়
+
ক্লাউড প্রাইসিং
+
বলা নেই
+
কোনো টোকেন বাজেট নেই
+
LLM-ব্যাকড (ভিন্ন হয়)
+
ভিন্ন হয়
+
240 অবজারভেশনে 22K+ টোকেন
+
+
+
রিয়েল-টাইম ভিউয়ার
+
হ্যাঁ (পোর্ট 3113)
+
ক্লাউড ড্যাশবোর্ড
+
ক্লাউড ড্যাশবোর্ড
+
ওয়েব UI
+
ক্লাউড ড্যাশবোর্ড
+
হাব ওয়েব UI
+
না
+
না
+
না
+
না
+
+
+
সেলফ-হোস্টেড
+
হ্যাঁ (ডিফল্ট)
+
অপশনাল
+
অপশনাল
+
হ্যাঁ
+
না (কেবল ক্লাউড)
+
হ্যাঁ (Docker)
+
হ্যাঁ
+
হ্যাঁ (Oracle DB)
+
হ্যাঁ
+
হ্যাঁ
+
+
+
+বেঞ্চমার্ক নোট: শুধু agentmemory-র R@5 আমাদের নিজের মাপা ফল (LongMemEval-S, benchmark/COMPARISON.md থেকে রিপ্রোডিউসযোগ্য)। mem0 এবং Letta-র সংখ্যাগুলো তাদের প্রকাশিত LoCoMo নম্বর (একটি ভিন্ন ডেটাসেট); MemPalace, supermemory, TencentDB (PersonaMem), এবং oracleagentmemory-র সংখ্যাগুলো ভেন্ডরের স্ব-ঘোষিত দাবি যা আমরা স্বতন্ত্রভাবে রিপ্রোডিউস করিনি (oracleagentmemory-র রানটি একটি Oracle AI Database-এর বিরুদ্ধে GPT-5.5 ব্যবহার করেছিল)। পাশাপাশি দেখানো হয়েছে কেবল মোটামুটি ধারণা দেওয়ার জন্য, অভিন্ন ডেটার উপর মুখোমুখি তুলনা নয়। স্টার সংখ্যা আনুমানিক এবং সময়ের সাথে বদলায়।
+
+**নতুন প্রতিযোগী** যাদের জানা দরকার, [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md)-এ গভীরভাবে তুলনা করা হয়েছে:
+
+| সিস্টেম | ⭐ | অ্যাঙ্গেল |
+|--------|---|-------|
+| Zep / Graphiti | 30K | টেম্পোরাল নলেজ গ্রাফ; সবচেয়ে শক্তিশালী প্রকাশিত টেম্পোরাল-কোয়েরি ফল (LongMemEval 63.8%), কিন্তু গ্রাফ অ্যাসিনক্রোনাসভাবে তৈরি হয় তাই নতুন তথ্য দেরিতে আসতে পারে |
+| Cognee | 30K | ডকুমেন্ট-থেকে-নলেজ-গ্রাফ ইনজেশন, কেবল Python, সেশন ক্যাপচারের বদলে স্ট্রাকচারড এনটিটি এক্সট্র্যাকশনের জন্য তৈরি |
+
+এদের কেউই কোডিং-এজেন্ট হুক থেকে অটো-ক্যাপচার করে না, লোকাল-ফার্স্ট ভিউয়ার দেয় না, বা কিলেস চলে না — যে কম্বিনেশনের উপর agentmemory তৈরি।
+
+---
+
+
+
+কম্প্যাটিবিলিটি: এই রিলিজ `iii-sdk` 0.22.1 টার্গেট করে এবং iii-engine v0.22.1 পিন করে।
+
+### 30 সেকেন্ডে ট্রাই করুন
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` 3টি রিয়েলিস্টিক সেশন সিড করে (JWT auth, N+1 কোয়েরি ফিক্স, রেট লিমিটিং) এবং সেগুলোর বিরুদ্ধে সার্চ চালায়। কিলেস ইনস্টলে ভেক্টর বন্ধ থাকে, তাই `mem::search` কিওয়ার্ড কোয়েরিগুলো BM25-এর মাধ্যমে হিট করার কথা, যেখানে `database performance optimization` শূন্য রিটার্ন করতে পারে। গ্রাফ ডেটা থাকলে `smart-search` এর উপরও স্ট্রাকচারাল গ্রাফ ম্যাচ রিটার্ন করতে পারে। সিম্যান্টিক কোয়েরিটিকে ভেক্টরের মাধ্যমে N+1 ফিক্স খুঁজে পাওয়াতে, `EMBEDDING_PROVIDER=local` সেট করুন, রিস্টার্ট করুন, এবং প্রথম মডেল ডাউনলোড শেষ হতে দিন।
+
+মেমরি লাইভ তৈরি হওয়া দেখতে `http://localhost:3113` খুলুন।
+
+### ফ্রেশ ইনস্টল এবং রিস্টার্ট পারসিস্টেন্স যাচাই করুন
+
+সার্ভার চলা অবস্থায়, REST, health, ভিউয়ার, এবং iii-ব্যাকড রানটাইম স্ট্যাটাস যাচাই করুন:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+স্টার্টআপ রেডি প্যানেল চারটি পোর্টের হিসাব রাখে: 3111-এ REST/MCP HTTP, 3112-এ iii স্ট্রিম, 3113-এ ভিউয়ার, এবং 49134-এ iii ওয়ার্কার WebSocket। `status` agentmemory-র স্বাস্থ্য এবং অ্যাক্টিভ প্রোভাইডার/এমবেডিং মোড নিশ্চিত করে। একটি প্রোব সেভ করুন এবং নিশ্চিত করুন এটি সার্চযোগ্য:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+তারপর `npx -y @agentmemory/agentmemory@latest stop` চালান, Terminal 1-এ ক্যানোনিকাল কমান্ড আবার শুরু করুন, `/agentmemory/livez`-এর জন্য অপেক্ষা করুন, এবং সার্চটি আবার করুন। প্রোবটি তখনও রিটার্ন হতে হবে। কাস্টম `--data-dir` বেছে নিয়ে থাকলে, রিস্টার্টেও একই ডিরেক্টরি পাস করুন।
+
+### দৈনন্দিন কমান্ড
+
+ইনস্টল ও সেটআপ উপরে [Install](#install)-এ আছে (প্রথম রান আপনাকে গাইড করে)। দৈনন্দিন ব্যবহারের জন্য:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### সেশন রিপ্লে
+
+agentmemory যে সেশনই রেকর্ড করুক, তা রিপ্লেযোগ্য। ভিউয়ার খুলুন, **Replay** ট্যাবটি বেছে নিন, এবং টাইমলাইন স্ক্রাব করুন: প্রম্পট, টুল কল, টুল রেজাল্ট, এবং রেসপন্স আলাদা ইভেন্ট হিসেবে রেন্ডার হয়, play/pause, স্পিড কন্ট্রোল (0.5x থেকে 4x), এবং কিবোর্ড শর্টকাট (টগল করতে স্পেস, স্টেপ করতে অ্যারো) সহ।
+
+পুরোনো Claude Code JSONL ট্রান্সক্রিপ্ট নিয়ে আসতে:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+ইমপোর্ট করা সেশনগুলো নেটিভগুলোর পাশে Replay পিকারে দেখা যায়। হুডের নিচে প্রতিটি এন্ট্রি `mem::replay::load`, `mem::replay::sessions`, এবং `mem::replay::import-jsonl` iii ফাংশনের মধ্য দিয়ে যায়, কোনো সাইড-চ্যানেল সার্ভার ছাড়াই। প্রতিটি ইমপোর্ট করা ট্রান্সক্রিপ্ট সার্চের জন্য ইনডেক্সড হয়, `import` অরিজিন চ্যানেলে স্ট্যাম্পড হয়, এবং একটি সেশন ক্রিস্টাল ও লেসনের জন্য মাইনড হয়।
+
+> **`import-jsonl`-কে আপনার মূল ক্যাপচার পাথ হিসেবে ব্যবহার করলে এটা জেনে রাখুন:** Claude Code-এর `cleanupPeriodDays` (`~/.claude/settings.json`-এ, ডিফল্ট **30**) সেই উইন্ডোর চেয়ে পুরোনো JSONL ট্রান্সক্রিপ্ট `~/.claude/projects/` থেকে অটো-ডিলিট করে দেয়। মাস-কয়েক পুরোনো Claude Code হিস্ট্রির উপর যদি আপনি agentmemory ফ্রেশ ইনস্টল করেন, তাহলে 30 দিনের চেয়ে পুরোনো যা কিছু প্রথম ইমপোর্টের আগেই হারিয়ে গেছে। এক্ষেত্রে cron-এ `import-jsonl` চালান, `cleanupPeriodDays` বাড়িয়ে দিন, বা অটো-ক্যাপচার হুক ওয়্যার করুন (ডিফল্ট প্লাগইন ইনস্টল পাথ) যাতে সেশন লাইভ থাকা অবস্থায় প্রতিটি টার্ন agentmemory-তে পৌঁছে যায় এবং JSONL ক্লিনআপ আর গুরুত্বপূর্ণ না থাকে।
+
+### আপগ্রেড / মেইনটেন্যান্স
+
+আপনি ইচ্ছাকৃতভাবে আপনার লোকাল রানটাইম আপডেট করতে চাইলে মেইনটেন্যান্স কমান্ড ব্যবহার করুন:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+সতর্কতা: এই কমান্ড বর্তমান workspace/runtime বদলে দেয়। এটি JavaScript ডিপেন্ডেন্সি আপডেট করতে পারে এবং পিন করা `iiidev/iii:0.22.1` Docker ইমেজ টানতে পারে। এটি কখনো আনপিনড বা নতুন iii engine ইনস্টল করে না।
+
+ইমপ্লিমেন্টেশনের ডিটেইল থাকে `src/cli.ts`-এ (দেখুন `src/cli.ts:544-595` অঞ্চলের কাছে `runUpgrade`)।
+
+### Claude Code (এক ব্লক, পেস্ট করুন)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### প্লাগইন ইনস্টল ছাড়া Claude Code (MCP-স্ট্যান্ডঅ্যালোন পাথ)
+
+আপনি `/plugin install` ব্যবহার না করে সরাসরি `~/.claude.json`-এর মাধ্যমে agentmemory-র MCP সার্ভার ওয়্যার করলে, Claude Code কখনো `${CLAUDE_PLUGIN_ROOT}` রিজলভ করে না এবং আপনাকে `~/.claude/settings.json`-এ হুক স্ক্রিপ্টগুলো অ্যাবসোলিউট পাথে পয়েন্ট করতে হয়। সেই পাথগুলোতে সাধারণত agentmemory-র ভার্সন এমবেড থাকে (যেমন `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), তাই পরের আপগ্রেড নিঃশব্দে প্রতিটি হুক ভেঙে দেয়।
+
+ওয়ার্কঅ্যারাউন্ড:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+এটি একই হুক কমান্ডগুলো `~/.claude/settings.json`-এ মার্জ করে, বর্তমানে ইনস্টল করা `@agentmemory/agentmemory` প্যাকেজের বান্ডলড `plugin/` ডিরেক্টরির অ্যাবসোলিউট পাথ দিয়ে। পাথ রিফ্রেশ করতে agentmemory আপগ্রেড করার পর কমান্ডটি আবার চালান। একই ফাইলের ইউজার এন্ট্রিগুলো রক্ষিত থাকে; শুধু আগের agentmemory এন্ট্রিগুলো রিপ্লেস হয়। `/plugin install` পাথটি এখনও সুপারিশকৃত পদ্ধতি।
+রিমোট বা প্রোটেক্টেড ডিপ্লয়মেন্টের জন্য, `AGENTMEMORY_URL` এবং `AGENTMEMORY_SECRET` সেট করে Claude Code লঞ্চ করুন। প্লাগইন দুটি ভ্যালুই তার বান্ডলড MCP সার্ভারে পাস করে; `AGENTMEMORY_URL` খালি থাকলে, MCP শিম `http://localhost:3111` ব্যবহার করে।
+
+### Codex CLI (Codex প্লাগইন প্ল্যাটফর্ম)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex প্লাগইনটি Claude Code প্লাগইনের মতো একই `plugin/` ডিরেক্টরি থেকে আসে। এটি রেজিস্টার করে:
+
+- চলমান daemon-এর একটি bundled stdio MCP bridge, কোনো npm download বা fallback store ছাড়াই। একটি unreleased build টেস্ট করতে [লোকাল Codex গাইড](../docs/plugins/codex-local.md) দেখুন।
+- 6টি লাইফসাইকেল হুক: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9টি ইনভোকেবল স্কিল: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, এবং আরও 8টি রেফারেন্স স্কিল যা এজেন্ট প্রয়োজনমতো লোড করে (memory discipline, MCP টুল, REST API, কনফিগ, এজেন্ট, হুক, আর্কিটেকচার, এবং স্কিল-লেখার গাইড)
+
+Codex-এর হুক ইঞ্জিন হুক সাবপ্রসেসে `CLAUDE_PLUGIN_ROOT` ইনজেক্ট করে (দেখুন [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), তাই একই হুক স্ক্রিপ্ট দুই হোস্টেই কোনো ডুপ্লিকেশন ছাড়া কাজ করে। Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure ইভেন্টগুলো কেবল Claude-Code-এর, এবং Codex-এর জন্য রেজিস্টার করা হয় না।
+
+#### Codex হুকের বিশ্বাস ও কম্প্যাটিবিলিটি
+
+Codex CLI 0.150.1-এর সাথে নেটিভ প্লাগইন হুক ডিসপ্যাচ ভেরিফাই করা হয়েছে। ক্যাপচার আশা করার আগে প্লাগইন হুকগুলোকে বিশ্বাস করুন। Desktop-এর আচরণ তার বান্ডলড রানটাইমের উপর নির্ভর করে; একটি workaround চালু করার আগে `/hooks` চেক করুন এবং একটি captured event নিশ্চিত করুন।
+
+যদি আপনার হোস্টের গ্লোবাল হুক প্রয়োজন হয়, তাহলে কমান্ডগুলো `~/.codex/hooks.json`-এ মিরর করুন। MCP যখন আগে থেকেই ওয়্যারড থাকে, তখন বর্তমান কনেক্টরের হুক ইনস্টলেশন পর্যন্ত পৌঁছাতে `--force` প্রয়োজন হয়:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+এটি গ্লোবাল হুক মার্জ করে এবং agentmemory MCP এন্ট্রি রিরাইট করে, অসম্পর্কিত এন্ট্রিগুলো সংরক্ষণ করে। `--force` ব্যবহারের আগে কাস্টম agentmemory এন্ডপয়েন্ট সেটিংস রিভিউ করুন। স্ক্রিপ্ট পাথ রিফ্রেশ করতে আপগ্রেড করার পর আবার চালান। ডুপ্লিকেট ক্যাপচার এড়াতে নেটিভ প্লাগইন হুক বা গ্লোবাল কপির মধ্যে একটি সক্রিয় করুন।
+
+### GitHub Copilot CLI
+
+VS Code এজেন্ট মোডের জন্য, [Copilot MCP এবং অটোমেটিক-ক্যাপচার গাইড](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions) ব্যবহার করুন। CLI কনেক্টর VS Code কনফিগার করে না।
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` `mcpServers.agentmemory`-কে `~/.copilot/mcp-config.json`-এ (বা `COPILOT_HOME` সেট থাকলে `$COPILOT_HOME/mcp-config.json`-এ) মার্জ করে এবং বিদ্যমান সার্ভারগুলো রক্ষা করে। নেটিভ Windows-এ এটিই একমাত্র অটোমেটেড `connect` অ্যাডাপ্টার; অন্য প্রতিটি নেটিভ Windows এজেন্ট ম্যানুয়ালি কনফিগার করতে হবে। WSL `connect` কেবল তখনই সাপোর্টেড যখন টার্গেট এজেন্টটিও সেই একই WSL এনভায়রনমেন্টে ইনস্টল করা থাকে। Copilot পরের লঞ্চে বা `/mcp`-এর পর MCP সার্ভারটি নিয়ে নেয়। পূর্ণ হুক/স্কিল অভিজ্ঞতা চাইলে প্লাগইনটিও ইনস্টল করুন।
+
+
+OpenClaw (এই প্রম্পট পেস্ট করুন)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+সম্পূর্ণ গাইড: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (এই প্রম্পট পেস্ট করুন)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+সম্পূর্ণ গাইড: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### অন্য এজেন্ট
+
+মেমরি সার্ভার শুরু করুন: `npx -y @agentmemory/agentmemory@latest`
+
+#### `npx skills add`-এর মাধ্যমে নেটিভ স্কিল (50+ এজেন্ট)
+
+agentmemory Claude-Code-স্টাইলের `/SKILL.md` ফরম্যাটে 17টি স্কিল নিয়ে আসে: 9টি ইনভোকেবল অ্যাকশন স্কিল (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) এবং 8টি রেফারেন্স স্কিল যা এজেন্ট প্রয়োজনমতো লোড করে (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`)। রেফারেন্স স্কিলগুলো সোর্স থেকে জেনারেট করা ডেটা টেবিল বহন করে, তাই এগুলো কখনো ডিফ্ট করে না। vercel-labs-এর [`skills`](https://npmjs.com/package/skills) CLI 50+ এজেন্টে (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, এবং আরও) কলিং এজেন্টের নেটিভ স্কিল ডিরেক্টরিতে এগুলো অটো-ইনস্টল করে:
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+এটি `agentmemory connect `-এর সাথে **পরিপূরক**:
+
+- `agentmemory connect ` MCP সার্ভার কনফিগ লেখে যাতে টুলগুলো উপলব্ধ হয়।
+- `npx skills add rohitg00/agentmemory` স্কিলগুলো ইনস্টল করে যাতে এজেন্ট জানে কখন এগুলো কল করতে হবে।
+
+স্কিল CLI এখনও যে কয়েকটা এজেন্ট কভার করে না (Zed v1.3.x এবং তার নিচে), সেগুলোতে 17টি SKILL.md ফাইল নিজেই এজেন্টের নেটিভ স্কিল ডিরেক্টরিতে রাখুন; একই ফরম্যাট সবখানে কাজ করে।
+
+#### স্ট্যান্ডার্ড MCP ব্লক
+
+`mcpServers` শেপ ব্যবহার করে এমন প্রতিটি হোস্টে (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw) agentmemory এন্ট্রিটি **একই MCP সার্ভার ব্লক**:
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**এই এন্ট্রিটি হোস্টের বিদ্যমান `mcpServers` অবজেক্টে মার্জ করুন**; ফাইলটি রিপ্লেস করবেন না। ফাইলে আগে থেকে অন্য সার্ভার থাকলে, `mcpServers`-এর ভেতর আরেকটি কি হিসেবে সেগুলোর পাশে `agentmemory` যুক্ত করুন। `mcpServers` সম্পূর্ণ অনুপস্থিত থাকলে, ব্লকটি `{ "mcpServers": { ... } }`-এর ভেতরে পেস্ট করুন। `${VAR}` প্লেসহোল্ডারগুলো MCP-সার্ভার লঞ্চের সময় শেল থেকে `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` ইনহেরিট করে; আনসেট ভ্যারিয়েবল খালি স্ট্রিং পাস করে এবং শিম `http://localhost:3111`-এ ফলব্যাক করে। একটি ওয়্যারড এন্ট্রি লোকাল ও রিমোট (k8s / রিভার্স-প্রক্সিড) দুই ডিপ্লয়মেন্টই কভার করে।
+
+| এজেন্ট | কনফিগ ফাইল | নোট |
+|---|---|---|
+| **Cursor (কেবল MCP)** | `~/.cursor/mcp.json` | `mcpServers`-এ মার্জ করুন, বা `agentmemory connect cursor`। ওয়েবসাইটেও এক-ক্লিক ডিপলিংক আছে। |
+| **Cursor (পূর্ণ প্লাগইন)** | `.cursor-plugin/` | Cursor Marketplace লিস্টিং (রিভিউতে আছে সাবমিশন) বা Cursor Settings → Plugins → লোকাল চেকআউট। 7টি অটো-ক্যাপচার হুক (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17টি স্কিল + MCP সার্ভার রেজিস্টার করে, `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` Cursor-এর প্লাগইন ড্যাশবোর্ডে ম্যানেজড। Cursor IDE এবং `cursor-agent` CLI-তে কাজ করে; CLI প্রিন্ট-মোড প্রম্পটগুলো সেশন শেষে সেশন ট্রান্সক্রিপ্ট থেকে ব্যাকফিল করা হয়। |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers`-এ মার্জ করুন। এডিট করার পর Claude Desktop রিস্টার্ট করুন। |
+| **Cline / Roo Code / Kilo Code** | Cline MCP সেটিংস (Settings UI → MCP Servers → Edit) | একই `mcpServers` ব্লক। |
+| **Devin CLI (MCP + হুক)** | `~/.config/devin/config.json` | `agentmemory connect devin` MCP এন্ট্রি মার্জ করে; `--with-hooks` Devin-এর লোয়ারকেস টুল ম্যাচার সহ ছয়টি নেটিভ অটো-ক্যাপচার হুক (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) যুক্ত করে। `devin mcp list` এবং devin-এর ভেতরে `/hooks` দিয়ে যাচাই করুন। |
+| **Devin CLI (পূর্ণ প্লাগইন)** | `plugin/.devin-plugin/` | একটি চেকআউট থেকে `devin plugins install ./plugin` 17টি স্কিলকে `/agentmemory:` স্ল্যাশ কমান্ড হিসেবে প্লাস MCP সার্ভার রেজিস্টার করে। Devin প্লাগইন হুক `SessionStart`/`SessionEnd` ফায়ার করতে পারে না, তাই পূর্ণ সেশন ক্যাপচারের জন্য এটি `connect devin --with-hooks`-এর সাথে পেয়ার করুন। |
+| **Devin (ক্লাউড)** | Settings → Connections → MCP servers | একটি কাস্টম MCP (STDIO) যুক্ত করুন: কমান্ড `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` একটি নেটওয়ার্ক-রিচেবল agentmemory ডিপ্লয়মেন্টের দিকে প্লাস `AGENTMEMORY_SECRET` (ক্লাউড সেশন localhost-এ পৌঁছাতে পারে না — দেখুন [`deploy/`](../deploy/))। Devin Secrets-এ সিক্রেট জমা রাখুন, তারপর সব 54টি টুল দেখা যায় কিনা যাচাই করতে "Test listing tools" ব্যবহার করুন। |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (অটো-মার্জ করে)। |
+| **GitHub Copilot CLI (কেবল MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` `mcpServers.agentmemory` মার্জ করে; Copilot পরের লঞ্চে বা `/mcp`-এ এটি নিয়ে নেয়। |
+| **GitHub Copilot CLI (পূর্ণ প্লাগইন)** | Copilot প্লাগইন ইনস্টল | GitHub সাবডির থেকে প্লাগইনের জন্য `copilot plugin install rohitg00/agentmemory:plugin`। |
+| **OpenClaw** | OpenClaw MCP কনফিগ | একই `mcpServers` ব্লক। আরও গভীরে: `openclaw plugins install ./integrations/openclaw` OpenClaw-র মেমরি স্লট দাবি করে (`memory-core` থেকে অটো-সুইচ করে); `plugins.entries.agentmemory.hooks.allowConversationAccess=true` সেট করুন, না হলে টার্ন ক্যাপচার নিঃশব্দে ব্লক হয়ে যায়। দেখুন [`integrations/openclaw`](../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টি লাইফসাইকেল হুক + 17টি স্কিল রেজিস্টার করে। আপনার হোস্টে হুক বিশ্বাস করুন এবং ক্যাপচার যাচাই করুন; দেখুন [Codex সেটআপ ও যাচাইকরণ](../docs/plugins/codex-local.md)। |
+| **OpenCode (কেবল MCP)** | `opencode.json` | ভিন্ন শেপ: টপ-লেভেল `mcp` কি, কমান্ড অ্যারে হিসেবে: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`। |
+| **OpenCode (পূর্ণ প্লাগইন)** | `plugin/opencode/` | সেশন লাইফসাইকেল, মেসেজ, টুল, এরর কভার করা 22টি অটো-ক্যাপচার হুক। প্রজেক্ট অ্যাট্রিবিউশন প্রতি-সেশন, তাই একাধিক রিপোজিটরি জুড়ে চলা একটি OpenCode প্রসেস প্রতিটি সেশনকে তার নিজের প্রজেক্টের অধীনে ফাইল করে। দুটি স্ল্যাশ কমান্ড (`/recall`, `/remember`)। আপনার OpenCode ওয়ার্কস্পেসে `plugin/opencode/` কপি করুন এবং `opencode.json`-এ প্লাগইন এন্ট্রি যুক্ত করুন। পূর্ণ হুক টেবিল + গ্যাপ অ্যানালিসিসের জন্য দেখুন [`plugin/opencode/README.md`](../plugin/opencode/README.md)। |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` pi-র অটো-ডিসকভারি ডিরেক্টরিতে বান্ডলড এক্সটেনশন ইনস্টল করে (এজেন্ট শুরুতে রিকল, এজেন্ট শেষে ক্যাপচার, `memory_search` / `memory_save` / `memory_health` টুল, `/agentmemory-status`)। চলমান pi-তে `/reload` এটি নিয়ে নেয়। [`integrations/pi`](../integrations/pi/) নিজেও একটি pi প্যাকেজ (একটি চেকআউট থেকে `pi install ./integrations/pi`)। |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` 6-হুক মেমরি প্রোভাইডার দেয় (প্রিফেচ, টার্ন ক্যাপচার, সেশন শেষ, প্রি-কম্প্রেস, MEMORY.md মিররিং, সিস্টেম প্রম্পট ব্লক)। `hermes plugins doctor` এবং `hermes memory status` দিয়ে যাচাই করুন। দেখুন [`integrations/hermes`](../integrations/hermes/)। |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` স্ট্যান্ডার্ড `mcpServers` ব্লক লেখে। হুক পেলোড Claude Code-এর সাথে ফিল্ড-কম্প্যাটিবল, তাই বিদ্যমান 12-হুক স্ক্রিপ্টগুলো কোনো পরিবর্তন ছাড়াই কাজ করে; একই `settings.json`-এর `hooks` সেকশনে এগুলো ওয়্যার করুন। |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` শেয়ার্ড কাস্টমাইজেশন ডিরেক্টরিতে MCP এবং ক্যাপচার হুক ইনস্টল করে। দেখুন [Antigravity সেটআপ ও সীমাবদ্ধতা](../docs/plugins/antigravity.md)। |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` বর্তমান IDE ভার্সনের মতো একই MCP এবং হুক কনফিগারেশন ব্যবহার করে। বিদ্যমান ইনস্টলেশনগুলো `--force` দিয়ে রিফ্রেশ করা উচিত; দেখুন [আপগ্রেড নোটস](../docs/plugins/antigravity.md)। |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` ইউজার-লেভেল কনফিগ লেখে। ওয়ার্কস্পেস ওভাররাইড আপনার কোডের পাশে `.kiro/settings/mcp.json`-এ যায়। |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` স্ট্যান্ডার্ড `mcpServers` ব্লক লেখে। Warp `.claude/skills/` থেকেও স্কিল অটো-ডিসকভার করে; Claude Code প্লাগইন ইনস্টল হলে agentmemory-র 8টি স্কিল (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) Warp-এর স্ল্যাশ-কমান্ড প্যালেটে নেটিভভাবে দেখা যায়। |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` স্ট্যান্ডার্ড `mcpServers` ব্লক লেখে। VS Code এক্সটেনশন ইউজাররা: Cline Settings → MCP Servers → Edit JSON-এর মাধ্যমে একই ব্লক পেস্ট করুন। |
+| **Continue.dev** | `~/.continue/config.yaml` (পছন্দনীয়) বা `config.json` (লেগ্যাসি) | দুটোরই অস্তিত্ব না থাকলে `agentmemory connect continue` শূন্য থেকে `config.yaml` তৈরি করে, বা বিদ্যমান `config.json` পরিবর্তন করে। **আপনার আগে থেকে `config.yaml` থাকলে** অ্যাডাপ্টারটি `mcpServers:`-এর নিচে পেস্ট করার জন্য ঠিক ব্লকটি প্রিন্ট করে; এটি নিঃশব্দে আপনার yaml পুনরায় লেখে না কারণ কমেন্ট ও অ্যাঙ্কর নিরাপদে রক্ষা করতে একটি YAML পার্সার লাগে যা প্যাকেজটি বহন করে না। Continue `mcpServers`-এর জন্য (অবজেক্ট না) অ্যারে ফর্ম ব্যবহার করে। |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` `context_servers`-এর নিচে লেখে (Zed-র কি, `mcpServers` নয়)। রিমোট MCP সার্ভার এর বদলে `{"url": "..."}` দিয়েও ওয়্যার করা যায়। |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` স্ট্যান্ডার্ড `mcpServers` ব্লক লেখে। প্রজেক্ট-স্কোপড ওভাররাইড যায় `/.factory/mcp.json`-এ। নেটিভ অটো-ক্যাপচারের জন্য `--with-hooks` পাস করুন। |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` প্রতিটি Harness প্রোফাইল লোড করা হোম-লেভেল প্যাচ লেয়ারে একটি `@deepseek-ai/dsh-mcp-client` সারি যুক্ত করে; টুলগুলো `mcp__agentmemory__*` হিসেবে রেজিস্টার হয়। অটো-ক্যাপচারও ওয়্যার করতে `--with-hooks` পাস করুন: বান্ডলড Claude Code হুক স্ক্রিপ্টগুলো Harness-র ফার্স্ট-পার্টি `@deepseek-ai/dsh-hooks-claude-code` ব্রিজের (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) মাধ্যমে চলে, `$DSH_HOME/agentmemory.hooks.json`-এ লেখা একটি ম্যানিফেস্টের মাধ্যমে। `DSH_HOME` আনসেট থাকলে ডিফল্ট `~/.dsh`। |
+| **Goose** | Goose MCP সেটিংস UI | একই `mcpServers` ব্লক; `goose configure` → Add Extension → MCP ব্যবহার করুন। `~/.config/goose/config.yaml`-এ সরাসরি YAML এডিট সাপোর্টেড, কিন্তু স্কিমা `extensions:` + `cmd` ব্যবহার করে (`mcpServers:` + `command` নয়)। |
+| **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)।
+
+### প্রোগ্রামেটিক অ্যাক্সেস (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-engine` দিয়ে agentmemory চালু করে, বা বেছে নিলে Docker Compose ব্যবহার করে। REST, স্ট্রিম, এবং ভিউয়ার ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড হয়। macOS/Linux-এ স্বয়ংক্রিয় বাইনারি পাথের জন্য `curl`, একটি POSIX `sh`, এবং `tar` প্রয়োজন।
+
+`iii-engine` ম্যানুয়ালি ইনস্টল করুন। **agentmemory বর্তমানে `iii-engine`-কে `v0.22.1`-এ পিন করে**, তার `iii-sdk` ডিপেন্ডেন্সির মতো একই রিলিজ; ওয়ার্কারটি সেই ইঞ্জিনের ওয়্যার প্রোটোকল বলে, এবং 0.20.0 SDK সারফেস পুনর্গঠিত করেছিল, তাই agentmemory-র রিলিজগুলোতে এই দুটো একসাথে চলে। আপনি নিজের ইঞ্জিন চালান এবং জানেন এটা মেলে এমন অবস্থায় `AGENTMEMORY_III_VERSION=` দিয়ে ওভাররাইড করুন।
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `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.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) থেকে `iii-x86_64-pc-windows-msvc.zip` ডাউনলোড করুন এবং `iii.exe` এক্সট্র্যাক্ট করুন `%USERPROFILE%\.agentmemory\bin\iii.exe`-এ
+
+প্রতিটি আর্কাইভের রিলিজ পেজে একটি ম্যাচিং `.sha256` ফাইল আছে; প্ল্যাটফর্ম বদলালে, উপরের চেকে সেই ফাইলের হ্যাশ ব্যবহার করুন (Windows-এ: `Get-FileHash`)। `npx @agentmemory/agentmemory`-র স্বয়ংক্রিয় ইনস্টলার এই হ্যাশগুলো পিন করে এবং না-মেলা আর্কাইভ রিজেক্ট করে।
+
+বা Docker ব্যবহার করুন (বান্ডলড `docker-compose.yml` `iiidev/iii:0.22.1` টানে)। সম্পূর্ণ ডকুমেন্টেশন: [iii.dev/docs](https://iii.dev/docs)।
+
+### Windows
+
+agentmemory Windows 10/11-এ চলে, কিন্তু কেবল Node.js প্যাকেজটাই পর্যাপ্ত নয়; ব্যাকগ্রাউন্ড প্রসেস হিসেবে পিন করা iii-engine v0.22.1 রানটাইমও প্রয়োজন। CLI Windows ZIP অটো-এক্সট্র্যাক্ট করে না, তাই নেটিভ Windows ইউজারদের `iii.exe` ম্যানুয়ালি ইনস্টল করতে হবে, WSL2 ব্যবহার করতে হবে, বা Docker Desktop বেছে নিতে হবে।
+
+নেটিভ Windows অটোমেটেড MCP ওয়্যারিং কেবল `agentmemory connect copilot-cli` সাপোর্ট করে। Claude Code, Codex, Cursor, এবং অন্য প্রতিটি নেটিভ Windows এজেন্টের জন্য, [Other agents](#other-agents)-এর ম্যানুয়াল MCP ব্লকটি সেই এজেন্টের Windows কনফিগে কপি করুন। WSL-এ `connect` চালানো তখনই যথাযথ যখন টার্গেট এজেন্টও সেই একই WSL এনভায়রনমেন্টে ইনস্টল করা আছে; এটি Windows-হোস্টেড কোনো এজেন্টের কনফিগ এডিট করে না।
+
+**অপশন A: প্রিবিল্ট Windows বাইনারি (সুপারিশকৃত)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**অপশন B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**অপশন C: কেবল স্ট্যান্ডঅ্যালোন MCP (কোনো ইঞ্জিন ছাড়াই)।** আপনার এজেন্টের জন্য কেবল MCP টুল প্রয়োজন হলে এবং REST API, ভিউয়ার, বা cron job প্রয়োজন না হলে, ইঞ্জিনটি সম্পূর্ণ স্কিপ করুন:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Windows-এর জন্য ডায়াগনস্টিক:** `npx -y @agentmemory/agentmemory@latest` ফেইল করলে, আসল ইঞ্জিন stderr দেখতে `--verbose` দিয়ে আবার চালান। সাধারণ ফেইলিউর মোড:
+
+| লক্ষণ | সমাধান |
+|---|---|
+| `The engine process started but the REST API never responded.` | চারটি ডিরাইভড পোর্ট ফ্রি আছে কিনা নিশ্চিত করুন, পিন করা `iii.exe` সচল ছিল কিনা যাচাই করুন, তারপর `--verbose` দিয়ে আবার চালান এবং ক্যাপচার করা ইঞ্জিন stderr দেখুন |
+| `Could not start iii-engine` | `iii.exe` বা Docker কোনোটাই ইনস্টল করা নেই। উপরের অপশন A বা B দেখুন |
+| পোর্ট কনফ্লিক্ট | কী বাইন্ড করা আছে দেখতে `netstat -ano \| findstr :3111`, তারপর সেটা কিল করুন বা `--port ` ব্যবহার করুন |
+| Docker ইনস্টল থাকলেও Docker ফলব্যাক স্কিপ হচ্ছে | Docker Desktop সত্যিই চলছে কিনা নিশ্চিত করুন (সিস্টেম ট্রে আইকন) |
+
+> নোট: iii **ইঞ্জিন** একটি প্রিবিল্ট বাইনারি, cargo crate নয়, তাই এটি `cargo install` করার চেষ্টা করবেন না। (iii **SDK**গুলো crates.io, npm, এবং PyPI-এ প্রকাশিত, কিন্তু agentmemory-র এগুলো লাগে না।) সাপোর্টেড ইঞ্জিন ইনস্টল পদ্ধতিগুলো সবই v0.22.1-এ পিন করা: উপরের প্রিবিল্ট বাইনারি, agentmemory-র macOS/Linux অটো-ইনস্টল পাথ (`curl`, POSIX `sh`, এবং `tar` প্রয়োজন), এবং Docker ইমেজ `iiidev/iii:0.22.1`। একটি খালি আপস্ট্রিম `install.sh | sh` লেটেস্ট ইঞ্জিন ইনস্টল করে, যা agentmemory সাপোর্ট করে না। `npx -y @agentmemory/agentmemory@latest` ব্যবহার করুন; macOS/Linux-এ এটি পিন করা ইঞ্জিন `~/.agentmemory/bin`-এ নিয়ে আসে।
+
+---
+
+
Deploy
+
+ম্যানেজড হোস্টের জন্য ওয়ান-ক্লিক টেমপ্লেট। প্রতিটিতে একটি সেলফ-কনটেইনড Dockerfile থাকে যা npm থেকে `@agentmemory/agentmemory` টানে এবং অফিশিয়াল `iiidev/iii` Docker Hub ইমেজ থেকে iii engine বাইনারিটি কপি করে; কোনো প্রি-বিল্ট agentmemory ইমেজ লাগে না। স্থায়ী স্টোরেজ `/data`-এ মাউন্ট হয়; ফার্স্ট-বুট এন্ট্রিপয়েন্ট npm-বান্ডলড iii কনফিগ (যা `127.0.0.1`-এ বাইন্ড করে) একটি ডিপ্লয়-টিউনড কনফিগ দিয়ে ওভাররাইট করে যা `0.0.0.0`-এ বাইন্ড করে এবং অ্যাবসোলিউট `/data` পাথ ব্যবহার করে, HMAC সিক্রেট জেনারেট করে, তারপর agentmemory CLI exec করার আগে `gosu`-র মাধ্যমে `root` থেকে `node`-এ প্রিভিলেজ নামিয়ে আনে।
+
+
+
+
+
+
+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-টানেল প্যাটার্ন ডকুমেন্ট করে।
+
+---
+
+
+
+সেশন শেষ হলে প্রতিটি কোডিং এজেন্ট সবকিছু ভুলে যায়, এবং প্রতিটি নতুন সেশন শুরু হয় আপনার স্ট্যাক আবার ব্যাখ্যা করা দিয়ে। 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-এর আছে নোটপ্যাড, Cline-এর আছে memory bank। এগুলো স্টিকি নোটের মতো কাজ করে। agentmemory হলো সেই স্টিকি নোটগুলোর পেছনের সার্চযোগ্য ডেটাবেস।
+
+| | বিল্ট-ইন (CLAUDE.md) | agentmemory |
+|---|---|---|
+| স্কেল | 200-লাইন ক্যাপ | আনলিমিটেড |
+| সার্চ | সবকিছু কনটেক্সটে লোড করে | BM25 + vector + graph (কেবল top-K) |
+| টোকেন খরচ | 240 অবজারভেশনে 22K+ | ~1,900 টোকেন (92% কম) |
+| ক্রস-এজেন্ট | প্রতি-এজেন্ট ফাইল | MCP + REST (যেকোনো এজেন্ট) |
+| কো-অর্ডিনেশন | নেই | lease, signal, action, routine |
+| অবজারভেবিলিটি | ম্যানুয়ালি ফাইল পড়া | :3113-এ রিয়েল-টাইম ভিউয়ার |
+
+---
+
+
+
+### মেমরি পাইপলাইন
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-স্তর মেমরি কনসোলিডেশন
+
+মানুষের ব্রেইন কীভাবে মেমরি প্রসেস করে তার উপর মডেল করা, ঘুমের কনসোলিডেশন সহ।
+
+| টায়ার | কী | উপমা |
+|------|------|---------|
+| **Working** | টুল ব্যবহারের কাঁচা অবজারভেশন | শর্ট-টার্ম মেমরি |
+| **Episodic** | কম্প্রেসড সেশন সামারি | "কী ঘটেছিল" |
+| **Semantic** | এক্সট্র্যাক্ট করা ফ্যাক্ট ও প্যাটার্ন | "আমি কী জানি" |
+| **Procedural** | ওয়ার্কফ্লো ও সিদ্ধান্ত-প্যাটার্ন | "কীভাবে করতে হয়" |
+
+মেমরি সময়ের সাথে ক্ষয় হয় (Ebbinghaus কার্ভ)। প্রায়ই অ্যাক্সেস করা মেমরি জোরদার হয়। বাসি মেমরি অটো-ইভিক্ট হয়। বিরোধ (contradiction) ডিটেক্ট ও সমাধান করা হয়।
+
+### কী ক্যাপচার হয়
+
+| হুক | যা ক্যাপচার করে |
+|------|----------|
+| `SessionStart` | প্রজেক্ট পাথ, সেশন ID |
+| `UserPromptSubmit` | ইউজার প্রম্পট (প্রাইভেসি-ফিল্টারড) |
+| `PreToolUse` | ফাইল অ্যাক্সেস প্যাটার্ন + এনরিচড কনটেক্সট |
+| `PostToolUse` | টুলের নাম, ইনপুট, আউটপুট |
+| `PostToolUseFailure` | এরর কনটেক্সট |
+| `PreCompact` | কম্প্যাকশনের আগে মেমরি পুনরায় ইনজেক্ট করে |
+| `SubagentStart/Stop` | সাব-এজেন্ট লাইফসাইকেল |
+| `Stop` | সেশন-শেষের সামারি |
+| `SessionEnd` | সেশন সম্পূর্ণ হওয়ার মার্কার |
+
+### মূল সক্ষমতা
+
+| সক্ষমতা | বর্ণনা |
+|---|---|
+| **অটোমেটিক ক্যাপচার** | হুকের মাধ্যমে প্রতিটি টুল ব্যবহার রেকর্ড হয়, কোনো ম্যানুয়াল পরিশ্রম ছাড়াই |
+| **সিম্যান্টিক সার্চ** | RRF ফিউশন সহ BM25 + vector + নলেজ গ্রাফ |
+| **মেমরি ইভোলিউশন** | ভার্সনিং, সুপারসেশন, রিলেশনশিপ গ্রাফ |
+| **রিকল হাইজিন** | রিপ্লেসড মেমরি ভার্সন সার্চ ইনডেক্স থেকে বাদ পড়ে; KV-এর ভার্সন চেইন সম্পূর্ণ ইতিহাস রাখে |
+| **নিয়ার-ডুপ্লিকেট হিন্ট** | নতুন কনটেন্ট বিদ্যমান কোনো মেমরির সাথে খুব মিলে গেলে সেভগুলো একটি উপদেষ্টামূলক `similarTo` ম্যাচ রিপোর্ট করে |
+| **প্রতি-এজেন্ট স্কোপিং** | `agentId` REST, MCP, এবং সার্চ ইনডেক্স জুড়ে সেভ ও রিকলের মধ্য দিয়ে যায়, শেয়ারড বা আইসোলেটেড মোডে |
+| **রাইট-টাইম প্রোভেন্যান্স** | প্রতিটি অবজারভেশন ও মেমরি ক্যাপচার, সেভ, এবং ইমপোর্টের সময় স্ট্যাম্প করা একটি অপরিবর্তনীয় অরিজিন চ্যানেল (user, agent, tool, import, বা shared) বহন করে |
+| **অটো-ফরগেটিং** | TTL এক্সপায়ারি, কনট্রাডিকশন ডিটেকশন, ইমপোর্টেন্স ইভিকশন |
+| **প্রাইভেসি ফার্স্ট** | স্টোরেজের আগে API কী, সিক্রেট, `` ট্যাগ স্ট্রিপ করা হয় |
+| **সেলফ-হিলিং** | সার্কিট ব্রেকার, প্রোভাইডার ফলব্যাক চেইন, হেলথ মনিটরিং |
+| **Claude ব্রিজ** | MEMORY.md-এর সাথে বাই-ডিরেকশনাল সিঙ্ক |
+| **নলেজ গ্রাফ** | এনটিটি এক্সট্র্যাকশন + BFS ট্রাভার্সাল |
+| **টিম মেমরি** | টিম মেম্বারদের মধ্যে নেমস্পেসড শেয়ার্ড + প্রাইভেট |
+| **সাইটেশন প্রোভেন্যান্স** | কোনো মেমরিকে তার সোর্স অবজারভেশন পর্যন্ত ট্রেস করা |
+| **Git স্ন্যাপশট** | মেমরি স্টেট ভার্সন, রোলব্যাক, এবং ডিফ করা |
+
+---
+
+
+
+তিনটি সিগন্যাল একসাথে মিশিয়ে ট্রিপল-স্ট্রিম রিট্রিভাল:
+
+| স্ট্রিম | যা করে | কখন |
+|---|---|---|
+| **BM25** | সিনোনিম এক্সপানশন সহ স্টেমড কিওয়ার্ড ম্যাচিং | সবসময় চালু |
+| **Vector** | ডেন্স এমবেডিংয়ের উপর cosine similarity | এমবেডিং প্রোভাইডার কনফিগার করা থাকলে |
+| **Graph** | এনটিটি ম্যাচিংয়ের মাধ্যমে নলেজ গ্রাফ ট্রাভার্সাল | কোয়েরিতে এনটিটি ডিটেক্ট হলে |
+
+Reciprocal Rank Fusion (RRF, k=60) দিয়ে ফিউজড এবং সেশন-ডাইভার্সিফায়েড (প্রতি সেশনে সর্বোচ্চ 3টি রেজাল্ট)।
+
+ভেক্টর ইনডেক্স পপুলেটেড থাকলে, `mem::search` (`memory_recall`-এর পেছনে) হাইব্রিড BM25 + vector র্যাংকার ব্যবহার করে। এমবেডিং ছাড়া এটি BM25 ব্যবহার করে। `smart-search` গ্রাফ ডেটা থাকলে অতিরিক্তভাবে স্ট্রাকচারাল গ্রাফ ম্যাচ ফিউজ করতে পারে, কিলেস মোডেও। লেসন রিকল প্রতি কোয়েরিতে সম্পূর্ণ করপাস স্ক্যান করার বদলে একটি ডেডিকেটেড ইন-মেমরি BM25 ইনডেক্সে চলে। রিপ্লেসড মেমরি ভার্সন প্রতিটি রিকল পাথ থেকে বাদ পড়ে; ভার্সন চেইন তাদের ইতিহাস রাখে।
+
+ভেক্টর ক্র্যাশ বা ফোর্স-কিল সহ্য করতে পারে। ভেক্টর ইনডেক্স সর্বোচ্চ প্রতি `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 মিনিট) অন্তর বাকেটে সেভ হয়। মাঝখানে যুক্ত বা বাদ দেওয়া প্রতিটি ভেক্টরও state store-এ একটি ছোট পেন্ডিং লগে তাৎক্ষণিকভাবে লেখা হয়, এবং পরের স্টার্ট এমবেডিং প্রোভাইডারকে কল না করেই সেটা রিপ্লে করে। প্রতিটি সফল সেভ লগটি খালি করে দেয়। রিপ্লের পরেও যে ডকুমেন্টগুলোর ভেক্টর নেই সেগুলো ব্যাকগ্রাউন্ডে `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500)-এর ব্যাচে পুনরায়-এমবেড করা হয় যতক্ষণ না কোনোটা বাকি থাকে, এবং থেমে যাওয়া ব্যাকফিল পরের স্টার্টে চালু থাকে। `/agentmemory/status` এবং ভিউয়ার পেন্ডিং লগের সাইজ ও ব্যাকফিল স্টেট দেখায়। কিলেস ইনস্টল কিছুই লেখে না।
+
+BM25 আউট অফ দ্য বক্সে গ্রিক, সিরিলিক, হিব্রু, আরবি, এবং অ্যাকসেন্টেড ল্যাটিন টোকেনাইজ করে। চাইনিজ / জাপানিজ / কোরিয়ান মেমরির জন্য, CJK রানগুলো ওয়ার্ড-লেভেল টোকেনে ভাগ করতে অপশনাল সেগমেন্টার ইনস্টল করুন (`npm install @node-rs/jieba tiny-segmenter`); এগুলো ছাড়া, agentmemory সফট-ফল করে সম্পূর্ণ-রান টোকেনাইজেশনে এবং stderr-এ একবার একটি হিন্ট প্রিন্ট করে।
+
+### এমবেডিং প্রোভাইডার
+
+কিলেস ইনস্টলে ভেক্টর এমবেডিং বন্ধ থাকে: `mem::search` BM25 ব্যবহার করে, যেখানে `smart-search` বিদ্যমান স্ট্রাকচারাল গ্রাফ ডেটাও ব্যবহার করতে পারে। ফ্রি অন-ডিভাইস সিম্যান্টিক এমবেডিং চালু করতে, এটি `~/.agentmemory/.env`-এ যুক্ত করুন এবং agentmemory রিস্টার্ট করুন:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+নরমাল npm ইনস্টলে অপশনাল `@huggingface/transformers` রানটাইম অন্তর্ভুক্ত থাকে। প্রথম এমবেডিং রিকোয়েস্ট `Xenova/all-MiniLM-L6-v2` ডাউনলোড করে, তাই এর নেটওয়ার্ক অ্যাক্সেস লাগে এবং বেশি সময় নিতে পারে; পরবর্তী ইনফারেন্স অন-ডিভাইসে চলে। `EMBEDDING_PROVIDER` ওভাররাইড না করলে রিমোট প্রোভাইডারগুলো তাদের কী থেকে অটো-ডিটেক্টেড হয়।
+
+| প্রোভাইডার | মডেল | খরচ | নোট |
+|---|---|---|---|
+| **Local (সুপারিশকৃত অপ্ট-ইন)** | `all-MiniLM-L6-v2` | ফ্রি | প্রথম মডেল ডাউনলোডের পর অন-ডিভাইস, শুধু-BM25-র তুলনায় +8pp রিকল |
+| Gemini | `gemini-embedding-001` | ফ্রি টায়ার | 100+ ভাষা, 768/1536/3072 dims (MRL), 2048-টোকেন ইনপুট। `text-embedding-004`-কে প্রতিস্থাপন করে ([deprecated, শাটডাউন Jan 14, 2026](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 | কোনো মডেল | ভিন্ন হয় | মাল্টি-মডেল প্রক্সি |
+
+---
+
+
+
+54 টুল, 6 রিসোর্স, 3 প্রম্পট, এবং 17 স্কিল।
+
+> **MCP শিম বনাম পূর্ণ সার্ভার:** প্রকাশিত `@agentmemory/mcp` প্যাকেজটি একটি থিন শিম। এটি পূর্ণ 54-টুল সারফেস তখনই দেখায় **যখন এটি `AGENTMEMORY_URL`-এর (প্রক্সি মোড) মাধ্যমে একটি চলমান agentmemory সার্ভারে পৌঁছাতে পারে**। কোনো সার্ভার অ্যাক্সেসযোগ্য না থাকলে, শিমটি 7-টুলের লোকাল সেটে (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`) ফলব্যাক করে। `AGENTMEMORY_TOOLS=core|all` এনভ ভ্যারিয়েবলটি একটি *সার্ভার-সাইড* ফ্ল্যাগ; শিমের `env` ব্লকে এটি সেট করলে কোনো প্রভাব পড়ে না। Cursor / OpenCode / Gemini CLI-এ কেবল 7টি টুল দেখলে, `npx -y @agentmemory/agentmemory@latest` (বা Docker স্ট্যাক) চালু করুন এবং `AGENTMEMORY_URL=http://localhost:3111` সেট করুন।
+
+### 54 টুল
+
+ছোট থেকে বড়, তিনটি টুল সারফেস: `AGENTMEMORY_TOOLS=core` ভিজিবিলিটি 8টি জরুরি টুলে (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`) নামিয়ে আনে; নিচের বেস সেটটি রেজিস্ট্রির 14টি ফাউন্ডেশনাল টুল; ডিফল্ট (`AGENTMEMORY_TOOLS=all`) সবগুলো 54টি দেখায়।
+
+
+বেস টুল (14)
+
+| টুল | বর্ণনা |
+|------|-------------|
+| `memory_recall` | অতীত অবজারভেশন সার্চ করে |
+| `memory_compress_file` | স্ট্রাকচার রক্ষা করে markdown ফাইল কম্প্রেস করে |
+| `memory_save` | একটি ইনসাইট, সিদ্ধান্ত, বা প্যাটার্ন সেভ করে |
+| `memory_file_history` | নির্দিষ্ট ফাইল সম্পর্কে অতীত অবজারভেশন |
+| `memory_patterns` | পুনরাবৃত্ত প্যাটার্ন ডিটেক্ট করে |
+| `memory_sessions` | সাম্প্রতিক সেশনের তালিকা দেয় |
+| `memory_smart_search` | হাইব্রিড সিম্যান্টিক + কিওয়ার্ড সার্চ |
+| `memory_vision_search` | ছবির অবজারভেশন সার্চ করে |
+| `memory_timeline` | ক্রনোলজিক্যাল অবজারভেশন |
+| `memory_profile` | প্রজেক্ট প্রোফাইল (concept, file, pattern) |
+| `memory_export` | সব মেমরি ডেটা এক্সপোর্ট করে |
+| `memory_relations` | রিলেশনশিপ গ্রাফ কোয়েরি করে |
+| `memory_commit_lookup` | একটি git কমিটের পেছনের সেশন |
+| `memory_commits` | একটি সেশনের জন্য রেকর্ড করা কমিট |
+
+
+
+
+এক্সটেন্ডেড টুল (মোট 54টি, ডিফল্ট সারফেস)
+
+| টুল | বর্ণনা |
+|------|-------------|
+| `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` | Dimension:value ট্যাগ |
+| `memory_facet_query` | ফ্যাসেট ট্যাগ দিয়ে কোয়েরি করে |
+| `memory_verify` | প্রোভেন্যান্স ট্রেস করে |
+
+
+
+### 6 রিসোর্স · 3 প্রম্পট · 17 স্কিল
+
+| ধরন | নাম | বর্ণনা |
+|------|------|-------------|
+| Resource | `agentmemory://status` | স্বাস্থ্য, সেশন সংখ্যা, মেমরি সংখ্যা |
+| Resource | `agentmemory://project/{name}/profile` | প্রতি-প্রজেক্ট ইন্টেলিজেন্স |
+| Resource | `agentmemory://project/{name}/recent` | একটি প্রজেক্টের সাম্প্রতিক অবজারভেশন |
+| Resource | `agentmemory://memories/latest` | সাম্প্রতিক 10টি অ্যাকটিভ মেমরি |
+| Resource | `agentmemory://graph/stats` | নলেজ গ্রাফ স্ট্যাটিস্টিক্স |
+| Resource | `agentmemory://team/{id}/profile` | শেয়ার্ড টিম প্রোফাইল |
+| Prompt | `recall_context` | সার্চ + কনটেক্সট মেসেজ রিটার্ন করে |
+| Prompt | `session_handoff` | এজেন্টদের মধ্যে হ্যান্ডঅফ ডেটা |
+| Prompt | `detect_patterns` | পুনরাবৃত্ত প্যাটার্ন অ্যানালাইজ করে |
+| Skill | `/recall` | মেমরি সার্চ করে |
+| Skill | `/remember` | লং-টার্ম মেমরিতে সেভ করে |
+| Skill | `/session-history` | সাম্প্রতিক সেশনের সামারি |
+| Skill | `/forget` | অবজারভেশন/সেশন ডিলিট করে |
+
+টেবিলটি মূল চারটি স্কিল দেখায়। পূর্ণ সেট হলো 9টি ইনভোকেবল স্কিল প্লাস 8টি রেফারেন্স স্কিল; উপরের Native skills সেকশন দেখুন।
+
+### স্ট্যান্ডঅ্যালোন MCP
+
+পূর্ণ সার্ভার ছাড়াই চালান, যেকোনো MCP ক্লায়েন্টের জন্য। এর যেকোনো একটি কাজ করবে:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+বা আপনার এজেন্টের MCP কনফিগে যুক্ত করুন:
+
+অধিকাংশ এজেন্ট (Cursor, Claude Desktop, Cline, Roo Code, 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/
+```
+
+---
+
+
+
+`3113` পোর্টে অটো-স্টার্ট হয়। ভিউয়ার কানেক্ট হওয়ার সময় একটি স্ন্যাপশট লোড করে (`GET /agentmemory/viewer/snapshot`) এবং তারপর লাইভ স্ট্রিম ইভেন্ট অ্যাপ্লাই করে: নতুন মেমরি, লেসন, অবজারভেশন, অডিট এন্ট্রি, গ্রাফ পরিবর্তন, এবং হেলথ আপডেট পোলিং বা পেজ রিলোড ছাড়াই দেখা যায়। অন্য একমাত্র রিকোয়েস্টগুলো হলো আপনি যে অ্যাকশনে ক্লিক করেন, "load more" পেজ, এবং সার্চ। স্ট্রিম বিচ্ছিন্ন হলে, ভিউয়ার দেখায় তার সংখ্যাগুলো কত পুরোনো, ব্যাকঅফ দিয়ে রিকানেক্ট করে এবং একটি স্ন্যাপশট থেকে রিসিঙ্ক করে।
+
+- **চারটি গ্রুপে 12টি ট্যাব**, লাইভ কাউন্ট, ডিপ লিংক (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), কিবোর্ড শর্টকাট এবং মোবাইল মেনু সহ।
+- **Memories:** সার্ভার-সাইড সার্চ, প্রজেক্ট, এজেন্ট ও টাইপ অনুযায়ী ফিল্টার, ভার্সন চেইন ও একটি word diff সহ একটি ডিটেল প্যানেল, প্রোভেন্যান্স লিংক, id-র জন্য কপি বাটন, MCP কল এবং একটি curl কমান্ড, এডিট (একটি নতুন ভার্সন), কনফার্মেশন সহ forget, বাল্ক forget, এবং JSON এক্সপোর্ট।
+- **Sessions:** রিডেবল টুল ইনপুট ও আউটপুট সহ একটি ইনলাইন অবজারভেশন টাইমলাইন, ফিল্টার ও পেজিং, এবং প্রতিটি সেশন যে মেমরি ও লেসন তৈরি করেছে।
+- **Graph:** সার্চ, রিলেশন ও সোর্স সহ নোড ডিটেল, কেবল কালারের উপর নির্ভর না করা একটি লিজেন্ড, এবং জুম কন্ট্রোল।
+- **Health:** `GET /agentmemory/status`-এর লাইভ ভার্সন। প্রতিটি সমস্যার সাথে তার সমাধান থাকে, প্লাস state ব্যাকএন্ড, ইনডেক্স সেভ স্টেট, গ্রাফ প্রোভেন্যান্স কমপ্যাকশনের অগ্রগতি, এবং আসল থ্রেশহোল্ড সহ একটি কনসোলিডেশন এক্সপ্লেইনার।
+- **Audit, Activity, Profile, Replay, Lessons, Actions, এবং Crystals** পেজ, প্রতিটিতে একটি এম্পটি স্টেট আছে যা বলে সেকশনটি কী, কেন এটি খালি, এবং সেটা ভরাট করার কমান্ড কী, আর প্রতিটি টার্ম ও নম্বরের উপর একটি `?` গ্লসারি টুলটিপ।
+
+```bash
+open http://localhost:3113
+```
+
+ভিউয়ার সার্ভার ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে এবং REST API-তে রিকোয়েস্ট ফরওয়ার্ড করার সময় সার্ভার সিক্রেট যুক্ত করে, তাই এর কোনো সেটআপ লাগে না। REST-সার্ভড `/agentmemory/viewer` এন্ডপয়েন্ট নরমাল bearer-token নিয়ম মেনে চলে এবং টোকেন ছাড়া ব্রাউজারগুলোকে ভিউয়ার পোর্টে রিডাইরেক্ট করে। CSP হেডার প্রতি-রেসপন্স script nonce ব্যবহার করে এবং ইনলাইন হ্যান্ডলার অ্যাট্রিবিউট বন্ধ রাখে (`script-src-attr 'none'`)।
+
+---
+
+
+
+`:3113`-এর ভিউয়ার দেখায় আপনার এজেন্ট কী **মনে রেখেছে**। [iii console](https://iii.dev/docs/console) দেখায় আপনার এজেন্ট কী **করেছে**: প্রতিটি মেমরি অপারেশন একটি OpenTelemetry ট্রেস হিসেবে, প্রতিটি KV এন্ট্রি এডিটযোগ্য, প্রতিটি ফাংশন ইনভোকেবল, প্রতিটি স্ট্রিম ট্যাপযোগ্য। একই মেমরির উপর দুটি জানালা: একটি প্রোডাক্ট-শেপড, একটি ইঞ্জিন-শেপড।
+
+একটি `memory_smart_search` ফায়ার হতে দেখুন এবং BM25 স্ক্যান → embedding lookup → RRF ফিউশন → reranker-কে একটি waterfall হিসেবে দেখুন। KV ব্রাউজারে একটি আটকে থাকা কনসোলিডেশন টাইমার এডিট করুন। একটি টুইকড পেলোড দিয়ে `PostToolUse` হুক রিপ্লে করুন। WebSocket স্ট্রিম পিন করুন এবং অবজারভেশনগুলো লাইভ ল্যান্ড করতে দেখুন।
+
+agentmemory এটা ফ্রিতে দেয় কারণ প্রতিটি ফাংশন কল ও ট্রিগার iii-এর মধ্য দিয়ে ফায়ার হয়; কিছুই কাস্টম নয়, ইন্সট্রুমেন্ট করার কিছু নেই।
+
+
+
+
+ Workers পেজ: প্রতিটি কানেক্টেড ওয়ার্কার, agentmemory নিজেও সহ, PID, ফাংশন কাউন্ট, রানটাইম, এবং last-seen সহ।
+
+
+**আগে থেকেই ইনস্টলড।** কনসোলটি পিন করা `iii` engine (0.22+)-এর সাথে আসে; আলাদা করে ইনস্টল করার কিছু নেই। প্রথম লঞ্চ ইঞ্জিনের পাশে কনসোল বাইনারি ডাউনলোড করে।
+
+**agentmemory-র সাথে লঞ্চ করুন:**
+
+```bash
+agentmemory console
+```
+
+এটি পিন করা ইঞ্জিনের `iii console`-কে agentmemory রিজলভ করা পোর্টগুলোর (REST, streams, bridge) বিরুদ্ধে চালায় এবং ভিউয়ারের একটা পোর্ট উপরে, ডিফল্টভাবে `http://localhost:3114`-এ সার্ভ করে। `--console-port N` অন্য একটা পোর্ট বেছে নেয়; `--port` এবং `--instance` `stop`-এর জন্য যেভাবে করে ঠিক সেভাবেই agentmemory ইনস্ট্যান্স বেছে নেয়; অন্য যেকোনো ফ্ল্যাগ পাস-থ্রু হয়, যেমন এক্সপেরিমেন্টাল আর্কিটেকচার-গ্রাফ পেজের জন্য `--enable-flow`।
+
+একই কাজ হাতে করে, `agentmemory` PATH-এ না থাকলে কাজে লাগে:
+
+```bash
+~/.agentmemory/bin/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 পরিবর্তন emit করুন। |
+| **States** | সেশন, মেমরি স্লট, লাইফসাইকেল টাইমার, এবং এমবেডিং ইনডেক্সের উপর পূর্ণ CRUD সহ KV ব্রাউজার; ভ্যালু ইন-প্লেস এডিট করুন। |
+| **Streams** | মেমরি রাইট, হুক ইভেন্ট, এবং অবজারভেশন আপডেটের জন্য লাইভ WebSocket মনিটর, এগুলো iii স্ট্রিমের মধ্য দিয়ে প্রবাহিত হওয়ার সাথে সাথে। |
+| **Queues** | ডিউরেবল কিউ টপিক + ডেড-লেটার ম্যানেজমেন্ট। ফেইলড এমবেডিং / কম্প্রেশন জব রিপ্লে বা ড্রপ করুন। |
+| **Traces** | OpenTelemetry waterfall / flame / service-breakdown ভিউ। একটি একক `memory.search` ঠিক কোন ফাংশন, DB কল, এবং এমবেডিং রিকোয়েস্ট তৈরি করেছে তা দেখতে `trace_id` দিয়ে ফিল্টার করুন। |
+| **Logs** | trace/span ID-র সাথে ফিল্টার ও কো-রিলেটেড স্ট্রাকচারড OTEL লগ। |
+| **Config** | রানটাইম কনফিগারেশন: আপনার ইঞ্জিন ঠিক কোন ওয়ার্কার, প্রোভাইডার, এবং পোর্ট নিয়ে চলছে তা দেখুন। |
+| **Flow** | (অপশনাল, `--enable-flow`) প্রতিটি ওয়ার্কার, ট্রিগার, এবং স্ট্রিমের ইন্টারঅ্যাক্টিভ আর্কিটেকচার গ্রাফ। |
+
+
+
+
+ Traces: প্রতিটি মেমরি অপারেশনের জন্য waterfall / flame / service breakdown।
+
+
+**Trace আগে থেকেই চালু:**
+
+`iii-config.yaml` `iii-observability` ওয়ার্কার চালু অবস্থায় আসে (`exporter: memory`, `sampling_ratio: 0.1`, মেট্রিক্স + লগ)। কোনো অতিরিক্ত কনফিগ লাগে না; agentmemory শুরু হওয়ার সাথে সাথে, প্রতিটি মেমরি অপারেশন একটি স্ট্রাকচারড লগ emit করে যা কনসোল পড়তে পারে, এবং তার মধ্যে দশটায় একটা (`sampling_ratio: 0.1`) একটি trace span-ও emit করে।
+
+এর বদলে Jaeger/Honeycomb/Grafana Tempo-তে এক্সপোর্ট করতে চাইলে, `exporter: memory`-কে `exporter: otlp`-এ বদলান এবং iii-র observability ডক্স অনুযায়ী কালেক্টর এন্ডপয়েন্ট সেট করুন।
+
+> **খেয়াল রাখুন:** কনসোলের উপর নিজেই কোনো auth এনফোর্সড নেই; এটিকে `127.0.0.1`-এই (ডিফল্ট) বাঁধা রাখুন এবং কখনো পাবলিকলি এক্সপোজ করবেন না।
+
+---
+
+
+
+agentmemory **ইতিমধ্যেই একটি চলমান [iii](https://iii.dev) ইনস্ট্যান্স**। তিনটি প্রিমিটিভ (worker, function, trigger) রানটাইম কম্পোজ করে; KV state, স্ট্রিম, এবং OTEL ট্রেস আসে iii-র সাথে আসা iii-state, iii-stream, এবং iii-observability ওয়ার্কার থেকে। আপনি Postgres, Redis, Express, pm2, বা Prometheus ইনস্টল করেননি, কারণ iii এগুলো প্রতিস্থাপন করে।
+
+তার মানে একটা মাত্র কমান্ড agentmemory-কে একটা সম্পূর্ণ নতুন সক্ষমতা দিয়ে বাড়িয়ে দেয়।
+
+### আরও ওয়ার্কার দিয়ে agentmemory বাড়ান
+
+agentmemory-র প্রয়োজনীয় বিল্টিনগুলো আগে থেকেই `iii-config.yaml`-এ আছে এবং তার সাথেই বুট হয়: `iii-state` (KV), `iii-queue` (ইভেন্ট সাবস্ক্রাইবারদের জন্য ডিউরেবল রিট্রাই), `iii-pubsub`, `iii-cron`, `iii-stream`, এবং `iii-observability` (প্রতিটি ফাংশনে OTEL ট্রেস, মেট্রিক্স, এবং লগ)। [iii worker registry](https://workers.iii.dev)-র বাকি যেকোনো কিছু একই ইঞ্জিনে প্লাগ ইন করে: `iii-config.yaml` কে `~/.agentmemory/iii-config.yaml`-এ কপি করুন (CLI বান্ডলড ফাইলের চেয়ে এই ফাইলটিকে প্রাধান্য দেয় এবং তারপরেও পোর্ট ও ডেটা পাথ এতে রেন্ডার করে), এন্ট্রিটি যুক্ত করুন, `~/.agentmemory/bin/iii update worker` দিয়ে একবার ওয়ার্কার রানটাইম ইনস্টল করুন, এবং agentmemory রিস্টার্ট করুন।
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| ওয়ার্কার | agentmemory-র উপরে যা পাবেন |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | KV ডিফল্ট ছাড়িয়ে গেলে SQL-ব্যাকড state অ্যাডাপ্টার |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` থেকে আসা কোড আপনার শেলে না চলে একটি থ্রোঅ্যাওয়ে VM-এর ভেতরে চলে |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory-র পাশে অতিরিক্ত MCP সার্ভার দাঁড় করান, একই ইঞ্জিন শেয়ার করে |
+
+0.22.x ইঞ্জিনে উপরের বিল্টিনগুলোর জন্য `iii-` প্রিফিক্সড নামগুলো রাখুন; প্রিফিক্স ছাড়া `http`, `state`, `queue`, `pubsub`, এবং `cron` এন্ট্রিগুলো সেই স্ট্যান্ডঅ্যালোন রেজিস্ট্রি ওয়ার্কার যেগুলোতে agentmemory 0.23 মাইগ্রেশনের সাথে চলে যাবে।
+
+সম্পূর্ণ রেজিস্ট্রি: [workers.iii.dev](https://workers.iii.dev)। সেখানে প্রতিটি ওয়ার্কার agentmemory যে প্রিমিটিভ ব্যবহার করে তার মধ্য দিয়েই কম্পোজ হয়, এবং আপনার কাছে থাকা agentmemory নিজেই তাদের একটি।
+
+### ইঞ্জিন কনফিগ এবং বাইন্ড অ্যাড্রেস
+
+`agentmemory start` প্রথম যে ফাইলটি পায় সেখান থেকে ইঞ্জিন কনফিগ পড়ে: `AGENTMEMORY_III_CONFIG`, বর্তমান ডিরেক্টরির `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, তারপর বান্ডলড `iii-config.yaml`। প্রতিবার স্টার্টে এটি সেই ফাইলটি (ডেটা পাথ, পোর্ট, state ব্যাকএন্ড) `~/.agentmemory/data/iii-config.runtime.yaml`-এ রেন্ডার করে এবং রেন্ডার করা কপি দিয়ে ইঞ্জিন লঞ্চ করে, তাই সোর্স ফাইলটি এডিট করুন, রেন্ডার করা ফাইলটি না। সোর্স ফাইলের `host:` ভ্যালুগুলো যেমন লেখা তেমনই রাখা হয়।
+
+বান্ডলড `iii-config.yaml` ইচ্ছাকৃতভাবে `127.0.0.1`-এ বাইন্ড করে, এবং এই ডিফল্ট কনটেইনারের ভেতরেও প্রযোজ্য। কনটেইনারে শুরু হওয়া একটি CLI কনটেইনারের লুপব্যাকে শোনে, তাই পাবলিশড পোর্ট কিছুতেই পৌঁছায় না। পাবলিশড পোর্টের মাধ্যমে একটি কনটেইনারাইজড CLI সার্ভ করতে, `AGENTMEMORY_III_CONFIG`-কে এমন একটি কনফিগে সেট করুন যা `0.0.0.0`-এ বাইন্ড করে। প্যাকেজড `iii-config.docker.yaml` তেমন একটি: এটি `iii-http`, `iii-stream`, এবং ইঞ্জিন পোর্টকে `0.0.0.0`-এ বাইন্ড করে এবং state `/data`-এর নিচে জমা রাখে, তাই সেখানে একটি রাইটেবল ভলিউম মাউন্ট করুন। `AGENTMEMORY_SECRET` সেট রাখুন, এবং কেবল প্রয়োজনীয় পোর্টগুলোই পাবলিশ করুন, `127.0.0.1`-এ বা আপনার বিশ্বস্ত কোনো প্রক্সির পেছনে।
+
+এই রেপোর `docker-compose.yml` CLI-র কনফিগ লুকআপ দিয়ে যায় না: এটি `iii-config.docker.yaml`-কে `/app/config.yaml`-এ মাউন্ট করে, এবং `iii-engine` কন্টেইনার `--config /app/config.yaml` দিয়ে শুরু হয়। ওয়ান-ক্লিক [deploy templates](../deploy/) তাদের এন্ট্রিপয়েন্টে নিজেদের `0.0.0.0` কনফিগ লেখে।
+
+### স্টোরেজ ব্যাকএন্ড: file (ডিফল্ট) বনাম redis
+
+`iii-state` এবং `iii-stream` ডিফল্টভাবে iii-engine-র বান্ডলড ফাইল-বেসড KV স্টোর ব্যবহার করে: প্রতি স্কোপে একটি JSON ফাইল, ইঞ্জিন প্রসেসের মেমরিতে রাখা এবং একটা টাইমারে ডিস্কে পুনরায় লেখা হয়। একক-ইউজার লোকাল ইনস্টলের জন্য এটাই সঠিক ডিফল্ট; একাধিক কনকারেন্ট রাইটার সহ একটি শেয়ার্ড ডেমন এর পরিবর্তে Redis থেকে আসল প্রতি-কী রাইট পায়, প্রতি অপারেশনে একটি নেটওয়ার্ক রাউন্ড ট্রিপের খরচে (প্রতিটি `state::*` কল তখনও একটি Redis কানেকশনে সিরিয়ালাইজ হয়, তাই এটি ফাইল স্টোরের লক-কে একটি সকেটের বিনিময়ে বদলায়, প্যারালালিজমের বিনিময়ে নয়)।
+
+দুটো ওয়ার্কারকেই iii-engine-র বিল্ট-ইন `redis` অ্যাডাপ্টারে বদলাতে `AGENTMEMORY_STATE_BACKEND=redis` (প্লাস `AGENTMEMORY_REDIS_URL`) সেট করুন, যা প্রতিটি রাইটে পুরো স্কোপ পুনরায় লেখার বদলে প্রতিটি কী-কে একটি Redis হ্যাশ ফিল্ড (`HSET`) হিসেবে জমা রাখে:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND`-র ডিফল্ট `file`; এটি আনসেট রাখলে আজকের আচরণ অপরিবর্তিত থাকে, এবং একটি অচেনা ভ্যালু (`file` বা `redis` ছাড়া অন্য কিছু) নিঃশব্দ ফলব্যাকের বদলে একটি স্টার্টআপ এরর। `/agentmemory/status` এবং ভিউয়ারের Health পেজ (State store সারি) রিপোর্ট করে কোন ব্যাকএন্ড অ্যাকটিভ এবং এটি উত্তর দেয় কিনা, কখনো URL দেখায় না।
+
+**শুধু প্লেইন `redis://`।** পিন করা ইঞ্জিন (0.22.1) তার Redis ক্লায়েন্ট TLS সাপোর্ট ছাড়াই বিল্ড করে, তাই একটি `rediss://` URL (বেশিরভাগ ম্যানেজড Redis অফারিং, যেমন Upstash, Redis Cloud, এবং in-transit এনক্রিপশন সহ ElastiCache, ডিফল্টভাবে TLS-only) কানেক্ট করতে ফেইল করে। কানেকশনটি আনএনক্রিপ্টেড, তাই Redis পাসওয়ার্ড এবং প্রতিটি স্টোর করা মেমরি তারের উপর প্লেইন টেক্সটে যায়: একটি লোকাল Redis বা আপনার বিশ্বস্ত কোনো প্রাইভেট নেটওয়ার্কের Redis-এ পয়েন্ট করুন। অন্য কোনো Redis-এর জন্য, agentmemory হোস্টে একটি এনক্রিপ্টেড টানেল (stunnel, SSH, বা VPN) চালান, যাতে প্লেইন `redis://` হপটি সেই হোস্টেই থাকে এবং টানেলের আপস্ট্রিম কানেকশন এনক্রিপ্টেড ও অথেন্টিকেটেড থাকে। একটি Redis পাসওয়ার্ডে সিঙ্গল কোট থাকলে, এটা percent-encode করুন (`%27`); ইঞ্জিন পার্স করার আগে URL-কে তার YAML কনফিগে এক্সপ্যান্ড করে।
+
+**প্রতি `--instance`-এ একটি Redis সার্ভার।** ইঞ্জিনের Redis কী প্রিফিক্স (`state:`, `stream::`) ফিক্সড, তাই একই ডেটাবেসের দিকে পয়েন্ট করা দুটি agentmemory ইনস্ট্যান্স (`--instance 1`, `--instance 2`, ...) একে অপরের ডেটা ওভাররাইট করে ফেলে। একটি আলাদা ডেটাবেস ইনডেক্স (`redis://localhost:6379/1`) স্টোর করা ডেটা আলাদা রাখে, কিন্তু ইঞ্জিন লাইভ ভিউয়ার ইভেন্ট একটি Redis pub/sub চ্যানেলের (`stream::events`) উপর রিলে করে, এবং Redis pub/sub ডেটাবেস ইনডেক্স উপেক্ষা করে, তাই প্রতিটি ইনস্ট্যান্সের ভিউয়ার তখনও অন্যটির লাইভ ইভেন্ট দেখাবে। একাধিক ইনস্ট্যান্স চালালে প্রতিটিকে তার নিজের Redis সার্ভার (বা পোর্ট) দিন।
+
+**কী একই থাকে, এবং কী বদলায়।** agentmemory-র প্রতিটি ফিচার Redis-এ কাজ করে: সেশন, অবজারভেশন, মেমরি (remember, supersede, evolve, forget), সার্চ ও ইনডেক্স বাকেট, লেসন, গ্রাফ, অডিট লগ ও তার মাসিক স্কোপ, এক্সপোর্ট ও ইমপোর্ট, গভর্নেন্স ডিলিট, কনসোলিডেশন স্ট্যাটাস, ভিউয়ার স্ন্যাপশট ও তার লাইভ স্ট্রিম, এবং হেলথ মনিটর। ইঞ্জিন প্রতিটি স্কোপকে একটি Redis হ্যাশ (`HSET`/`HGET`/`HGETALL`) হিসেবে জমা রাখে এবং ফাইল স্টোরের মতোই একই state ট্রিগার ফায়ার করে। ইঞ্জিনের তিনটি পার্থক্য agentmemory-র ভেতরে হ্যান্ডল করা হয়:
+
+- Redis কোনো স্কোপের রেকর্ড কোনো ফিক্সড অর্ডারে রিটার্ন করে না। agentmemory সেগুলোকে পুরোনো থেকে সাজায় (রেকর্ড id-তে থাকা তৈরির সময় দিয়ে, তারপর তার টাইমস্ট্যাম্প দিয়ে) যাতে লিস্ট, পেজিং, এবং এক্সপোর্ট চাঙ্ক ফাইল স্টোরের মতো একই অর্ডারে ফিরে আসে।
+- ইঞ্জিন Redis-এ একটি Lua স্ক্রিপ্টে পার্শিয়াল আপডেট প্রয়োগ করে যা খালি অ্যারেকে খালি অবজেক্টে বদলে দেয়। agentmemory নিজেই Redis-এ সেই আপডেটগুলো প্রয়োগ করে (read, change, write, একটি প্রতি-কী লকের অধীনে), তাই `tags: []`-এর মতো ফিল্ড অ্যারে-ই থাকে।
+- লেগ্যাসি অডিট লগ চেক ডিস্কে ফাইল স্টোরের ফাইল খোঁজার বদলে Redis থেকে পুরোনো স্কোপ পড়ে।
+
+একটা পার্থক্যে আপনার হাত লাগাতে হবে: **Redis রিস্টার্ট হওয়ার পর, agentmemory রিস্টার্ট না হওয়া পর্যন্ত ইঞ্জিন ভিউয়ারে লাইভ ইভেন্ট রিলে করা বন্ধ করে দেয়**। ডেটা তখনও স্বাভাবিকভাবে সেভ ও পড়া হয়। হেলথ মনিটর প্রতি 30 সেকেন্ডে Redis-এর মাধ্যমে একটি টেস্ট ইভেন্ট পাঠায়; সেটা ফিরে না এলে, `/agentmemory/status` এবং ভিউয়ারের Health পেজ "Live updates are not reaching the viewer" দেখায় সমাধান সহ: agentmemory রিস্টার্ট করুন। Redis ডাউন থাকলে, স্ট্যাটাস রিপোর্ট দেখায় "The state store is not answering" এবং এটা যাচাই করার উপায় (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)। একটা খুব বড় স্কোপ লিস্ট করা একটি `HGETALL`-এ পুরো হ্যাশ পড়ে, ফাইল স্টোর এটাকে মেমরিতে রাখার মতোই একই খরচ।
+
+**সুপারিশকৃত Redis সেটিংস।** ডিফল্ট `save 3600 1 300 100 60 10000` স্ন্যাপশট পলিসি একটা ক্র্যাশে মিনিটের রাইট হারাতে পারে, ফাইল স্টোরের 5s ফ্লাশ উইন্ডোর চেয়েও খারাপ। যেটা হারালে আপনার খারাপ লাগবে তার জন্য `appendonly yes` সেট করুন। `maxmemory-policy noeviction` সেট করুন; `allkeys-lru` বা অনুরূপ কিছু Redis তার মেমরি লিমিটে পৌঁছালে নিঃশব্দে মেমরি ড্রপ করে দেয়।
+
+একটি নেটিভ (নন-Docker) স্টার্ট, এবং প্রতিটি ওয়ান-ক্লিক [deploy template](../deploy/) (এগুলো বান্ডলড `iii-config.yaml` ওভাররাইট করে এবং নেটিভভাবে শুরু হয়), `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` পড়ে এবং লঞ্চ করা `iii-config`-এ রেন্ডার করে। URL নিজেই সেই রেন্ডার করা ফাইলে কখনো লেখা হয় না, কেবল একটি `${AGENTMEMORY_REDIS_URL}` রেফারেন্স যা ইঞ্জিন প্রসেস বুটের সময় তার নিজের এনভায়রনমেন্ট থেকে এক্সপ্যান্ড করে। কেবল এই রেপোর নিজের Docker Compose পাথ (`AGENTMEMORY_USE_DOCKER=1`, বা সেভাবে শুরু করা একটি ইঞ্জিন রিজিউম করা) `iii-config.docker.yaml`-কে read-only মাউন্ট করে এবং কখনো রেন্ডার করে না; `agentmemory start` এই কম্বিনেশন ডিটেক্ট করলে সতর্ক করে। [iii-state](https://workers.iii.dev/workers/iii-state) এবং [iii-stream](https://workers.iii.dev/workers/iii-stream) ওয়ার্কার ডক্সে দেখানো একই `name: redis` / `config: redis_url: ...` শেপ অনুসরণ করে ফাইলটি হাতে বদলান, এবং কনটেইনার থেকে পৌঁছানো যায় এমন একটি Redis-এ `redis_url` পয়েন্ট করুন। `docker-compose.yml` ইঞ্জিন কন্টেইনারে `AGENTMEMORY_REDIS_URL` পাস করে, তাই `redis_url: '${AGENTMEMORY_REDIS_URL}'` সেখানে কাজ করে এবং মাউন্ট করা ফাইলের বাইরে URL রাখে।
+
+রেন্ডার করা কনফিগ `~/.agentmemory/data/iii-config.runtime.yaml`-এর বাইরে URL রাখে, কিন্তু ইঞ্জিনের নিজের কনফিগারেশন ওয়ার্কার বুট হওয়ার পর তখনও *এক্সপ্যান্ডেড* ভ্যালুটা `~/.agentmemory/config/iii-state.yaml` এবং `iii-stream.yaml`-এ পার্সিস্ট করে (সেই ওয়ার্কার তার সিড জমা রাখার আগেই iii-engine-র `${VAR}` এক্সপানশন ঘটে, এবং এটি রিজলভড ভ্যালু জমা রাখে, রেফারেন্স নয়)। সেই ডিরেক্টরিটাকে একটি ক্রেডেনশিয়াল ধরে নিয়ে চলুন: কোনো শেয়ার্ড হোস্টে `chmod 700 ~/.agentmemory` করুন, এবং ডেটাবেসের অ্যাডমিন ক্রেডেনশিয়ালের চেয়ে agentmemory-র প্রয়োজন অনুযায়ী স্কোপড একটি Redis ACL ইউজার বেছে নিন।
+
+**মাইগ্রেশন স্বয়ংক্রিয় নয়।** `AGENTMEMORY_STATE_BACKEND` বদলালে দুই পাশেই একটি খালি স্টোর থেকে শুরু হয়; কিছুই বিদ্যমান ডেটা file থেকে Redis-এ বা উল্টোদিকে কপি করে না। আপনি যে ব্যাকএন্ড ছেড়ে যাচ্ছেন সেখান থেকে এক্সপোর্ট করুন এবং যেখানে যাচ্ছেন সেখানে ইমপোর্ট করুন। এটা bash এবং zsh-এ (`bash -u` সহ) অভিন্নভাবে চলে। `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})`-এর মতো একটি অ্যারে তা করে না: zsh হেডারটাকে একটা বিকৃত শব্দ হিসেবে রাখে যেখানে bash এটাকে দুই ভাগে ভাগ করে, তাই `AGENTMEMORY_SECRET` সেট থাকলেই দুটো রিকোয়েস্টই 401 দেয়:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` একাধিক কলে একটি বড় করপাস চাঙ্ক করার জন্য `?maxSessions=` এবং `?offset=`-ও গ্রহণ করে; import-এ `strategy` হলো `merge` (ডিফল্ট-সেফ), `replace`, বা `skip`।
+
+### iii যা প্রতিস্থাপন করে
+
+| ট্র্যাডিশনাল স্ট্যাক | agentmemory যা ব্যবহার করে |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + ইন-মেমরি ভেক্টর ইনডেক্স |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine ওয়ার্কার সুপারভিশন |
+| Prometheus / Grafana | iii OTEL + হেলথ মনিটর |
+| কাস্টম প্লাগইন সিস্টেম | `iii worker add ` |
+
+**225 সোর্স ফাইল · ~54,000 LOC · 2,600+ টেস্ট · 312 ফাংশন · 66 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
+
+---
+
+
+
+### LLM প্রোভাইডার
+
+agentmemory আপনার এনভায়রনমেন্ট থেকে প্রোভাইডার অটো-ডিটেক্ট করে। একটি প্রোভাইডার LLM-ব্যাকড অপারেশন উপলব্ধ করে, কিন্তু কেবল প্রোভাইডার কনফিগারেশন LLM-লিখিত অবজারভেশন কম্প্রেশন চালু করে না। সেই পাথের জন্য একটি প্রোভাইডার এবং `AGENTMEMORY_AUTO_COMPRESS=true` দুটোই লাগে।
+
+| প্রোভাইডার | কনফিগ | নোট |
+|----------|--------|-------|
+| **No-op (ডিফল্ট)** | কোনো কনফিগ লাগে না | LLM-ব্যাকড কম্প্রেস/সামারাইজ বন্ধ থাকে। সিন্থেটিক কম্প্রেশন এবং BM25 রিকল তখনও কাজ করে। আগে Claude-সাবস্ক্রিপশন ফলব্যাকের উপর নির্ভর করতেন তাহলে নিচের `AGENTMEMORY_ALLOW_AGENT_SDK` দেখুন। |
+| Anthropic API | `ANTHROPIC_API_KEY` | প্রতি-টোকেন বিলিং |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-কম্প্যাটিবল |
+| Gemini | `GEMINI_API_KEY` | এমবেডিংও চালু করে |
+| OpenRouter | `OPENROUTER_API_KEY` | কোনো মডেল |
+| OpenAI API | `OPENAI_API_KEY` | ডিফল্ট `gpt-5.6-luna`, `OPENAI_MODEL` দিয়ে ওভাররাইড করুন |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) বা `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=<আপনার মডেল>` | OpenAI-API-কম্প্যাটিবল যা কিছু। জিরো কস্ট, আপনার হার্ডওয়্যারে চলে। নিচে [Local models](#local-models-ollama--lm-studio--vllm) দেখুন। |
+| Claude সাবস্ক্রিপশন ফলব্যাক | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | কেবল অপ্ট-ইন। `@anthropic-ai/claude-agent-sdk` সেশন স্পন করে; এটা আগে আনবাউন্ডেড Stop-হুক রিকার্শন তৈরি করত, তাই এটা আর ডিফল্ট নয়। |
+
+### লোকাল মডেল (Ollama / LM Studio / vLLM)
+
+agentmemory যেকোনো OpenAI-API-কম্প্যাটিবল সার্ভারের সাথে কথা বলে, তাই `/v1/chat/completions` এক্সপোজ করা যা কিছুই কোনো কোড পরিবর্তন ছাড়া কাজ করে। কোনো পেইড কী নেই, কোনো ক্লাউড নেই, কোনো রেট লিমিট নেই; সম্পূর্ণভাবে আপনার হার্ডওয়্যারে চলে।
+
+**Ollama** (ডিফল্ট পোর্ট `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (ডিফল্ট পোর্ট `1234`):
+
+LM Studio খুলুন → Local Server ট্যাব → Start Server। পিকার থেকে যেকোনো চ্যাট মডেল বেছে নিন (Qwen 3, gpt-oss, DeepSeek R1, ইত্যাদি)।
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: একই শেপ। আপনার সার্ভার যে URL এক্সপোজ করে সেদিকে `OPENAI_BASE_URL` পয়েন্ট করুন এবং আপনার সার্ভার গ্রহণ করবে এমন একটি নামে `OPENAI_MODEL` সেট করুন।
+
+**মেমরি কাজের জন্য মডেল বাছাই**: কম্প্রেশন ও সামারাইজেশন ছোট কাজ (<2K টোকেন ইন, <500 টোকেন আউট) যেখানে একটা 7B instruct মডেলই যথেষ্ট। সুপারিশ:
+
+| মডেল | সাইজ | কেন |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | 16 GB মেশিনে ব্যালান্সড ডিফল্ট; এক্সট্র্যাকশন ও টুল-শেপড টেক্সটে শক্তিশালী |
+| `qwen3:4b` | ~2.6 GB | সবচেয়ে ছোট সেন্সিবল অপশন; কম্প্রেশনের জন্য ঠিক আছে, গ্রাফ এক্সট্র্যাকশনে দুর্বল |
+| `qwen3-coder:30b` | ~19 GB | 24-32 GB হার্ডওয়্যারে কোড-শেপড সেশনের জন্য সেরা লোকাল পিক (30B MoE, 3.3B অ্যাকটিভ) |
+| `gpt-oss:20b` | ~14 GB | 16 GB RAM-এ ফিট হয় এমন একটি শক্তিশালী জেনারেল মডেল |
+| `deepseek-r1:8b` | ~5.2 GB | রিজনিং ডিস্টিল; স্লোয়ার কিন্তু ক্লিনার এক্সট্র্যাকশন |
+
+Qwen 3 মডেল ডিফল্টভাবে থিংক করে এবং কোনো আউটপুটের আগেই পুরো টোকেন বাজেট রিজনিংয়ে পুড়িয়ে দিতে পারে। গ্রাফ-এক্সট্র্যাকশন প্রম্পটে `/no_think` যুক্ত করতে `AGENTMEMORY_LLM_NOTHINK=1` সেট করুন, এবং এক্সট্র্যাকশন খালি ফিরলে `MAX_TOKENS` বাড়ান (16384 কাজ করে)।
+
+রিজনিং-ক্লাস মডেল (`` ব্লক সহ `o1`-স্টাইল) খালি `content` রিটার্ন করতে পারে, একটি `reasoning` ফিল্ডের সাথে যা আপনার লোকাল সার্ভার সামনে আনতে পারে না। এক্সট্র্যাকশন খালি ফিরলে, প্রথমে একটি নন-রিজনিং মডেলে বদলান। `OPENAI_REASONING_EFFORT=none` এনভ OpenAI রিজনিং স্কিমা মিরর করা Ollama Cloud থিংকিং মডেলেও থিংকিং বন্ধ করে দিতে পারে।
+
+লোকাল এমবেডিং একটি অপশনাল ডিপেন্ডেন্সি হিসেবে আসে কিন্তু ডিফল্টভাবে চালু নয়। `Xenova/all-MiniLM-L6-v2` (384-dim)-এ অপ্ট-ইন করতে `EMBEDDING_PROVIDER=local` সেট করুন। প্রথম এমবেডিং রিকোয়েস্ট মডেলটি ডাউনলোড করে; তারপর ইনফারেন্স অন-ডিভাইসে চলে। সেই সেটিং বা একটি রিমোট এমবেডিং কী ছাড়া, ভেক্টর বন্ধ থাকে, `mem::search` BM25 ব্যবহার করে, এবং `smart-search` তখনও বিদ্যমান গ্রাফ ম্যাচ যুক্ত করতে পারে।
+
+### কস্ট-অ্যাওয়্যার মডেল বাছাই
+
+LLM-লিখিত ব্যাকগ্রাউন্ড কম্প্রেশন একটি প্রোভাইডার এবং `AGENTMEMORY_AUTO_COMPRESS=true` দুটো দিয়েই চালু থাকলে, এটা প্রতিটি অবজারভেশনে চলে, তাই মডেল বাছাই মাসিক খরচকে অর্থপূর্ণভাবে বদলে দেয়। ক্যাপচার করা ওয়ার্কলোড ডেটা: 635 রিকোয়েস্ট / 888K টোকেন / 35 ঘন্টার অ্যাকটিভ ব্যবহার, 2026-05-23-র প্রাইসিংয়ে তিনটি OpenRouter মডেলের বিরুদ্ধে চালানো।
+
+| টায়ার | মডেল | Input / 1M | Output / 1M | ক্যাপচার করা 35h-র খরচ | নোট |
+|------|-------|------------|-------------|---------------------------|-------|
+| সুপারিশকৃত | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | লেটেস্ট DeepSeek; কম্প্রেশন ওয়ার্কলোডের জন্য সবচেয়ে সস্তা সুপারিশকৃত পিক। |
+| সুপারিশকৃত | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet-র চেয়ে ~10× কম খরচে সলিড কম্প্রেশন + সামারাইজেশন কোয়ালিটি। |
+| সুপারিশকৃত | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | আপনার সেশন ভারীভাবে কোড-শেপড হলে শক্তিশালী কোড রিজনিং। |
+| প্রিমিয়াম | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | মাপা Sonnet 4.6 রানের মতোই একই লিস্ট প্রাইস; 2026-08-31 পর্যন্ত $2/$10 ইন্ট্রো প্রাইসিং। |
+| প্রিমিয়াম | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | ফ্ল্যাগশিপ টায়ার; অলওয়েজ-অন ব্যাকগ্রাউন্ড কাজের জন্য খরচসাপেক্ষ। |
+| এড়িয়ে যান | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | ফ্ল্যাগশিপ-ক্লাস মডেল; কম্প্রেশনের জন্য ওভারস্পেন্ড। |
+
+মাপা সারিগুলো ক্যাপচার করা রান থেকে আসে; (est.) সারিগুলো একই টোকেন মিক্সকে প্রতিটি মডেলের লিস্ট প্রাইস দিয়ে স্কেল করে।
+
+`OPENROUTER_MODEL` একটি প্রিমিয়াম-টায়ার প্যাটার্নের সাথে মিললে agentmemory একটি রানটাইম ওয়ার্নিং প্রিন্ট করে। একটি তথ্যভিত্তিক সিদ্ধান্ত নেওয়ার পর এটা নিশ্চুপ করতে `AGENTMEMORY_SUPPRESS_COST_WARNING=1` সেট করুন।
+
+মেমরি কাজের জন্য কোয়ালিটি বনাম কস্ট ট্রেডঅফ: কম্প্রেশন একটি সামারাইজেশন টাস্ক যার কোয়ালিটি বার তুলনামূলকভাবে ঢিলা (সামারি আবার এজেন্ট পড়ে, ইউজার নয়)। DeepSeek V4 Flash / V4 Pro / Qwen3-Coder এই টাস্কে Sonnet-র রাউন্ডিং এরর-এর মধ্যেই থাকে, আর খরচ হয় 10-70× কম। প্রিমিয়াম-টায়ার মডেলগুলো সেই কোয়েরির জন্য রেখে দিন যা আপনি সরাসরি পড়বেন।
+
+সোর্স: [OpenRouter pricing for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing notes](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 # 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=` গ্রহণ করে, এবং সম্পূর্ণভাবে env স্কোপ থেকে অপ্ট-আউট করতে `?agentId=*`। `/memories`-ও `?includeOrphans=true` গ্রহণ করে pre-AGENT_ID মেমরি সামনে আনতে যাদের `agentId` undefined।
+
+SDK / REST লেয়ারে প্রতি-কল ওভাররাইড: প্রতিটি মিউটেটিং এন্ডপয়েন্ট (`/session/start`, `/remember`) রিকোয়েস্ট বডিতে একটি `agentId` ফিল্ড গ্রহণ করে যা env-এর উপর জেতে। অনেক রোল একটি সার্ভার প্রসেসের মধ্য দিয়ে রাউট করা রানটাইমের জন্য কাজে লাগে। MCP `memory_save` টুল একই `agentId` ফিল্ড দেখায়, স্ট্যান্ডঅ্যালোন stdio সার্ভার `agentId` এবং `project` দুটোই ফরওয়ার্ড করে, এবং সেভ করা মেমরি সার্চ ইনডেক্সে `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 | ইন্টারনাল স্ট্রিম ওয়ার্কার (agentmemory + ভিউয়ার দিয়ে কনজিউমড) | `III_STREAM_PORT` (পছন্দনীয়) বা লেগ্যাসি `III_STREAMS_PORT` |
+| `3113` | agentmemory | রিয়েল-টাইম ভিউয়ার (`http://localhost:3113`) | রিপোর্টেড URL-এর জন্য `III_VIEWER_PORT` বা `AGENTMEMORY_VIEWER_URL` |
+| `49134` | iii-engine | WebSocket; ওয়ার্কাররা এখানে রেজিস্টার করে, OTel টেলিমেট্রি এর উপর দিয়ে প্রবাহিত হয় | `III_ENGINE_PORT` বা `III_ENGINE_URL` |
+
+`--port ` REST অ্যাঙ্কর বদলে দেয় এবং স্ট্রিম `N+1`, ভিউয়ার `N+2`, এবং ইঞ্জিন WebSocket `N+46023` ডিরাইভ করে, কেবল যেখানে উপরের সংশ্লিষ্ট এক্সপ্লিসিট পোর্ট বা URL আনসেট আছে। এটা কোনো আইসোলেটেড লাইফসাইকেল নেমস্পেস তৈরি করে না। দ্বিতীয় ডেমনের জন্য `--instance 1` ব্যবহার করুন; এটা অ্যাঙ্কর 3211 ব্যবহার করে, ডিফল্টভাবে `3211/3212/3213/49234`, এবং একটি আলাদা `instance-1` ডেটা ও লাইফসাইকেল ডিরেক্টরি পায়। ইনস্ট্যান্স 1 থেকে 50 একই প্যাটার্ন অনুসরণ করে।
+
+পিন করা ইঞ্জিন `--no-update-check` দিয়ে শুরু হয় (বুটে GitHub-এর বিরুদ্ধে কোনো আপডেট বা সিকিউরিটি-অ্যাডভাইজরি লুকআপ নেই) এবং iii-র অ্যানোনিমাস ইউসেজ টেলিমেট্রি বন্ধ রেখে: agentmemory যে ইঞ্জিন স্পন করে তার জন্য `III_TELEMETRY_ENABLED=false` সেট করে যদি না আপনি নিজে ভ্যারিয়েবলটি এক্সপোর্ট করেন, এবং বান্ডলড compose ফাইলও একই কাজ করে।
+
+একটি ক্র্যাশড রান শেষে পোর্টগুলো বাঁধা থেকে গেলে, বাসি প্রসেস ক্লিনআপ:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+গ্রেসফুল নেটিভ শাটডাউনে `agentmemory stop` ওয়ার্কার এবং ইঞ্জিন পিডফাইল দুটোই পরিষ্কারভাবে রিপ করে। Docker মোডে এটা নেটিভ ওয়ার্কার ফ্লাশ করে, ঠিক ভ্যালিডেটেড ইঞ্জিন কন্টেইনারটি থামায়, এবং লসলেস রিস্টার্টের জন্য কন্টেইনার ও তার `/data` মাউন্ট দুটোই রক্ষা করে; পরের স্টার্ট সেই একই কন্টেইনার যাচাই করে পুনরায় শুরু করে। Docker-ব্যাকড আনইনস্টলের জন্য `agentmemory remove --keep-data` লাগে: এটা শেয়ার্ড agentmemory-ম্যানেজড ফাইল সরিয়ে দেয়, ভ্যালিডেটেড কন্টেইনার, তার ডেটা মাউন্ট, এবং সেগুলো রিকভার করতে প্রয়োজনীয় লাইফসাইকেল রেকর্ড রক্ষা করে। ডেস্ট্রাক্টিভ Docker ডেটা ডিলিশন ইচ্ছাকৃতভাবে ব্যাকআপের পর অপারেটরের হাতে ছেড়ে দেওয়া। `--force` পাস না করলে CLI Docker বা VM পোর্ট হোল্ডারদের (Docker backend, vpnkit, colima) নেটিভ ইঞ্জিন হিসেবে গ্রহণ বা সিগন্যাল করতেও অস্বীকার করে। উপরের ম্যানুয়াল ক্লিনআপ শুধু পোস্ট-ক্র্যাশ কেসের জন্য যেখানে কোনো পিডফাইলই বাকি নেই।
+
+### কনফিগ ফাইল
+
+প্রতিটি শেলে ভ্যারিয়েবল এক্সপোর্ট করার বদলে agentmemory-র রানটাইম কনফিগারেশন `~/.agentmemory/.env`-এ রাখুন। ভিউয়ার `export ANTHROPIC_API_KEY=...`-র মতো একটি সেটআপ হিন্ট দেখালে, `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 সাবস্ক্রিপশন দিয়ে টেস্ট করতে, স্পষ্টভাবে অপ্ট-ইন করুন:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM-লিখিত অবজারভেশন কম্প্রেশনের জন্য দুই লাইনই লাগে: একটি LLM প্রোভাইডারে অ্যাক্সেস (এই এক্সপ্লিসিট সাবস্ক্রিপশন ফলব্যাক সহ) এবং `AGENTMEMORY_AUTO_COMPRESS=true`। একটি প্রোভাইডার একা ডিফল্ট সিন্থেটিক কম্প্রেশন পাথ রেখে দেয়।
+
+কনসোলিডেশন (গ্রাফ নোড, লেসন, ক্রিস্টাল) একটি LLM প্রোভাইডার কনফিগার করা থাকলেই ডিফল্টভাবে চালু থাকে। LLM-ফ্রি অপারেশন চাইলে স্পষ্টভাবে `CONSOLIDATION_ENABLED=false` দিয়ে অপ্ট-আউট করুন। গ্রাফ এক্সট্র্যাকশন একটা আলাদা ফ্ল্যাগ:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### এনভায়রনমেন্ট ভ্যারিয়েবল
+
+`~/.agentmemory/.env` তৈরি করুন:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+`3111` পোর্টে 138 এন্ডপয়েন্ট। REST API ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে। প্রোটেক্টেড এন্ডপয়েন্টে `Authorization: Bearer ` লাগে, এবং mesh sync এন্ডপয়েন্টে দুই পিয়ারেই স্পষ্টভাবে সেট করা `AGENTMEMORY_SECRET` লাগে।
+
+**অথেন্টিকেশন ডিফল্টভাবে চালু।** `AGENTMEMORY_SECRET` সেট না থাকলে (শেলে বা `~/.agentmemory/.env`-এ), সার্ভার প্রথম স্টার্টে একটি র্যান্ডম সিক্রেট জেনারেট করে এবং `0600` মোডে `~/.agentmemory/secret`-এ জমা রাখে। লোকাল সার্ভারের সাথে কথা বলার সময় প্রতিটি বান্ডলড ক্লায়েন্ট সেখান থেকেই এটা পড়ে: CLI, ভিউয়ার, `plugin/scripts`-এর নিচের হুক, MCP সার্ভার এবং `@agentmemory/mcp` শিম, `agentmemory connect`-এ লেখা কনফিগ, এবং বান্ডলড OpenCode, Pi, OpenClaw, Hermes, এবং filesystem-watcher ইন্টিগ্রেশন। জমা রাখা সিক্রেটটি কেবল লুপব্যাক URL-এ (`localhost`, `127.0.0.0/8`, `::1`) পাঠানো হয়। একটি এক্সপ্লিসিট `AGENTMEMORY_SECRET` সবসময় জেতে, এবং রিমোট ক্লায়েন্টদেরও এটা সেট করা লাগে। Docker এবং `deploy/` এন্ট্রিপয়েন্ট নিজেরাই নিজেদের সিক্রেট জেনারেট ও এক্সপোর্ট করে। হাতে API কল করতে:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**রাইটের জন্য রিকোয়েস্ট নিয়ম।** REST API এবং ভিউয়ারে `POST`, `PUT`, `PATCH`, এবং `DELETE` রিকোয়েস্টে body থাকলে `Content-Type: application/json` পাঠাতে হবে (একটা `charset` প্যারামিটার ঠিক আছে), এবং একটি `Origin` হেডার থাকলে, এটা কনফিগার করা REST বা ভিউয়ার পোর্টের জন্য একটি লুপব্যাক origin হতে হবে বা `VIEWER_ALLOWED_ORIGINS`-এ (কমা-সেপারেটেড, যেমন `https://memory.example.com`) তালিকাভুক্ত থাকতে হবে। যে ক্লায়েন্টগুলো কোনো `Origin` হেডার পাঠায় না (CLI, হুক, MCP, curl, সার্ভার-টু-সার্ভার) তারা প্রভাবিত হয় না। ভিউয়ার তার নিজের origin-ও গ্রহণ করে।
+
+**ফাইল পাথ।** যে এন্ডপয়েন্টগুলো ফাইল পড়ে বা লেখে (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) তারা কেবল `~/.agentmemory`, ইনস্ট্যান্স ডেটা ডিরেক্টরি, বা `AGENTMEMORY_IMPORT_ROOT`-এ তালিকাভুক্ত একটি ডিরেক্টরির নিচের পাথ গ্রহণ করে (একাধিক ডিরেক্টরি `:` দিয়ে আলাদা করুন, Windows-এ `;`)। `/replay/import-jsonl` তার ডিফল্ট `~/.claude/projects`-ও গ্রহণ করে। `/obsidian/export` `AGENTMEMORY_EXPORT_ROOT`-এর ভেতরেই থাকে এবং `/migrate` `~/.agentmemory`-র ভেতরে। সিমলিংক প্রতিটি চেকের আগে রিজলভ করা হয়।
+
+**সিক্রেট স্ক্রাবিং।** API কী, bearer টোকেন, PEM প্রাইভেট কী ব্লক, এবং URL-এ এমবেডেড ক্রেডেনশিয়াল (`scheme://user:password@host`) টেক্সট জমা রাখার আগে রিড্যাক্ট করা হয়, প্রতিটি রাইট পাথে: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, কম্প্রেশন ও সামারি আউটপুট, crystals, এবং গ্রাফ নোড।
+
+
+মূল এন্ডপয়েন্ট
+
+| Method | Path | বর্ণনা |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | হেলথ চেক (সবসময় পাবলিক) |
+| `GET` | `/agentmemory/status` | কী ভুল আর তা কীভাবে ঠিক করবেন (ব্রাউজারের জন্য HTML, নইলে JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | ভিউয়ার যা দেখায় সবকিছু, একটি রেসপন্সে |
+| `POST` | `/agentmemory/session/start` | সেশন শুরু + কনটেক্সট পান |
+| `POST` | `/agentmemory/session/end` | সেশন শেষ করুন |
+| `POST` | `/agentmemory/observe` | অবজারভেশন ক্যাপচার করুন (নিচে capture delivery দেখুন) |
+| `GET` | `/agentmemory/capture` | ক্যাপচার ইনবক্স, ডেড লেটার, এবং অফলাইন স্পুল |
+| `POST` | `/agentmemory/capture/retry` | ডেড-লেটার ক্যাপচার রিট্রাই করুন |
+| `POST` | `/agentmemory/capture/drain` | লোকাল অফলাইন স্পুল এখনই পাঠান |
+| `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/graph/compact` | অতিরিক্ত বড় গ্রাফ প্রোভেন্যান্স ট্রিম করুন |
+| `POST` | `/agentmemory/team/share` | টিমের সাথে শেয়ার করুন |
+| `GET` | `/agentmemory/audit` | অডিট ট্রেইল |
+
+সম্পূর্ণ এন্ডপয়েন্ট তালিকা: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**ক্যাপচার ডেলিভারি।** হুকগুলো প্রতিটি অবজারভেশন একবার `eventId` সহ `POST /agentmemory/observe`-এ পাঠায়। পেলোডের নিজের একটা id থাকলে (যেমন Claude Code-র `tool_use_id`) এটা সেই কলের হোস্টের নিজের id, না থাকলে সেশন, হুক টাইপ, টুলের নাম, ইনপুট, আউটপুট, এবং হোস্ট টাইমস্ট্যাম্পের একটা হ্যাশ। সার্ভার ইভেন্টটিকে state store-এ একটি ক্যাপচার ইনবক্সে লেখে, অবজারভেশনটি জমা রাখে, তারপর ইনবক্স এন্ট্রি সরিয়ে দেয়। স্ট্যাটাস কোড বলে দেয় কী ঘটেছে:
+
+| Status | `status` ফিল্ড | অর্থ |
+|---|---|---|
+| `201` | `accepted` | জমা হয়েছে। `observationId` নতুন অবজারভেশন। |
+| `202` | `accepted` (`state: "retrying"`) | গ্রহণ করা হয়েছে, কিন্তু জমা রাখা ফেইল করেছে। সার্ভার এটা রিট্রাই করে, রিস্টার্টের পরেও। |
+| `200` | `duplicate` | এই `eventId` আগেই গ্রহণ করা হয়েছিল। `observationId` বিদ্যমান অবজারভেশন; নতুন কিছু জমা হয় না। |
+| `400` / `422` | `rejected` | অবৈধ পেলোড, বা জমা রাখা স্থায়ীভাবে ফেইল করেছে (ইভেন্টটি ডেড লেটার হিসেবে রাখা হয়)। |
+| `503` | `rejected` (`retryable: true`) | ইনবক্স ভরা (`AGENTMEMORY_CAPTURE_INBOX_MAX`)। হুকগুলো ইভেন্টটি স্পুল করে এবং পরে পাঠায়। |
+
+ফেইলড ইভেন্টগুলো প্রতি `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) দ্বিগুণ হওয়া ব্যাকঅফ দিয়ে রিট্রাই হয়, `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5) পর্যন্ত। যে ইভেন্টগুলো তখনও ফেইল হয় সেগুলো ইনবক্সে ডেড লেটার হিসেবে থাকে, `/agentmemory/status` এবং ভিউয়ার Health পেজে তালিকাভুক্ত হয়, এবং `POST /agentmemory/capture/retry` (`{"eventId": "..."}` বা `{"all": true}`) দিয়ে রিট্রাই করা যায়। গ্রহণ করা ইভেন্ট id-গুলো `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 ঘন্টা, সর্বোচ্চ `AGENTMEMORY_CAPTURE_EVENTS_MAX` id) ধরে মনে রাখা হয়, তাই টাইমআউট বা রিস্টার্টের পর রিপ্লে করা একটি হুক একবার জমা হয়, যেখানে তাদের নিজ নিজ হোস্ট id-সহ দুটি আলাদা টুল কল দুইবার জমা হয় যদিও তাদের কনটেন্ট অভিন্ন। একটি অবজারভেশন ডিলিট হলে (forget, সেশন ডিলিট, eviction, auto-forget, বা store রিপ্লেস করা একটি import), তার ইভেন্ট অবজারভেশনটি সরানোর আগে ডিলিটেড হিসেবে মার্ক করা হয়, তাই একই উইন্ডোর মধ্যে সেই ইভেন্টের রিপ্লে একটি ডুপ্লিকেট হিসেবে উত্তর পায় এবং কিছু জমা হয় না। state store প্রতি 2 সেকেন্ডে ডিস্কে লেখে, তাই একটি উত্তর পাওয়া ইভেন্ট তখনও একটা মুহূর্তের জন্য কেবল মেমরিতে থাকতে পারে। এটা কভার করতে, প্রতিটি `2xx` উত্তরও সার্ভারের `bootId` (প্রতি স্টার্টে নতুন), `acceptedAt`, এবং `durableAfterMs` (file store-এ সেভ ইন্টারভাল প্লাস 1.5 s, redis-এ 1.5 s, যেখানে পার্সিস্টেন্স অপারেটরের সেটিং) বহন করে। হুকগুলো সেই উইন্ডো পার হওয়া পর্যন্ত ইভেন্টটিকে লোকাল স্পুলে রাখে এবং অন্য কোনো রিকোয়েস্ট ছাড়াই একটি পরের কলে এটা ডিলিট করে। তার মধ্যে `bootId` বদলে গেলে, সার্ভার রিস্টার্ট হয়েছিল, তাই হুক একই `eventId` দিয়ে ইভেন্টটা আবার পাঠায়; ডিস্কে পৌঁছানো একটি ইভেন্ট দুইবার জমা হয় না। সার্ভারও স্টার্টে এবং প্রতিটি রিট্রাই ইন্টারভালে নিজে এই ইভেন্টগুলো পাঠায়, তাই পরে কোনো হুক না চললেও একটা রিস্টার্ট কিছু হারায় না। পুরোনো হুকগুলো অতিরিক্ত ফিল্ডগুলো উপেক্ষা করে, এবং একটি পুরোনো সার্ভারের বিরুদ্ধে নতুন হুকগুলো আগের মতোই `2xx`-এ ইভেন্ট বাতিল করে।
+
+সার্ভার ডাউন থাকলে, সময়মতো উত্তর না দিলে, বা একটা 5xx রিটার্ন করলে, হুক অবজারভেশনটিকে একটি লোকাল স্পুল ফাইলে যুক্ত করে, `/capture-spool/-.jsonl` (`AGENTMEMORY_CAPTURE_SPOOL_DIR` দিয়ে ফোল্ডারটি ওভাররাইড করুন)। ফাইলটি আপনার ইউজারের জন্য প্রাইভেট (মোড 600), সিক্রেটগুলো সার্ভার যেভাবে রিড্যাক্ট করে ঠিক সেভাবেই রিড্যাক্ট করা হয়, এটা সর্বোচ্চ `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) ধরে রাখে এবং `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168)-এর চেয়ে পুরোনো এন্ট্রি ড্রপ করে। এটা ভরে গেলে, নতুন এন্ট্রি ড্রপ হয় এবং গণনা করা হয়, এবং `/agentmemory/status` তা রিপোর্ট করে। সার্ভার স্বাস্থ্যবান থাকলে হুক তখনও তার টাইম লিমিটের মধ্যে 0 দিয়ে exit হয় এবং কোনো রিকোয়েস্ট যুক্ত করে না। পরের স্টার্টে এবং সার্ভারে আবার পৌঁছানো প্রথম হুক দিয়ে স্পুলটি পাঠানো হয়, একটা ব্যাকগ্রাউন্ড প্রসেসে যাতে এজেন্ট অপেক্ষা না করে। ইভেন্ট id এটা নিরাপদ করে: একটা টাইমআউটের আগে পৌঁছানো অবজারভেশন দুইবার জমা হয় না। `npx @agentmemory/agentmemory capture` স্পুল এবং সার্ভার ইনবক্স দেখায়, `--drain` স্পুলটি এখনই পাঠায়, এবং `GET /agentmemory/capture` JSON হিসেবে একই জিনিস রিটার্ন করে। স্পুল বন্ধ করতে `AGENTMEMORY_CAPTURE_SPOOL=false` সেট করুন।
+
+**গ্রাফ প্রোভেন্যান্স কমপ্যাক্ট করা।** প্রতিটি নলেজ গ্রাফ নোড ও এজ সবচেয়ে নতুন 32টি অবজারভেশনের id রাখে যেখান থেকে এটা এসেছে। সেই ক্যাপের আগে লেখা store হট নোড প্রতি হাজার হাজার id ধরে রাখতে পারে, যা গ্রাফ সার্চ ও ভিউয়ারকে স্লো করে দেয় বা ওয়ার্কারকে ক্র্যাশ করায়। agentmemory নিজেই এটা ঠিক করে: আপগ্রেডের পর প্রথম স্টার্টে এটা ব্যাকগ্রাউন্ডে ছোট ছোট স্লাইসে, মাঝে একটা বিরতি দিয়ে, প্রতিটি নোড, এজ, সুপারসিডেড এজ (টেম্পোরাল গ্রাফ ইতিহাস), এবং ক্যাশড স্ন্যাপশটকে ক্যাপে ট্রিম করে, যাতে সার্চ, ক্যাপচার, এবং ভিউয়ার চলতে থাকে। এটা তার অগ্রগতি সেভ করে, রিস্টার্টের পর আবার শুরু করে এবং শেষ হওয়ার পর আর কখনো চলে না। `/agentmemory/status` এবং ভিউয়ার Health পেজ এটাকে pending, running (বর্তমান scope ও position সহ), done, বা failed হিসেবে দেখায়। এটা বন্ধ করতে `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` সেট করুন।
+
+হাতে চালাতে, `POST /agentmemory/graph/compact` কল করুন। এটা প্রতিটি নোড ও এজ লিস্ট করার বদলে নাম ও edge-key ইনডেক্সের মধ্য দিয়ে হাঁটে, এবং আবার চালানো নিরাপদ। id ট্রিম করলে এটা একটি `graph_compact` অডিট এন্ট্রি লেখে।
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+একটা বড় store-এ, বা কলটি 504 রিটার্ন করলে, এটা স্লাইসে চালান। `scope` (`nodes`, `edges`, বা `history`), `offset`, এবং `limit` পাঠান, তারপর রিটার্ন করা `nextOffset` দিয়ে আবার কল করুন যতক্ষণ না এটা `null` হয়। `nodes`, `edges`, এবং `history`-র জন্য এটা করুন, এবং একটা `{"scope":"snapshot"}` কল দিয়ে শেষ করুন, কারণ একটা স্লাইসড রান ক্যাশড স্ন্যাপশট ছোঁয় না।
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**প্রয়োজনীয়তা:** npm/npx সহ Node.js >= 20; [iii-engine](https://iii.dev/docs) v0.22.1 বা Docker। macOS/Linux অটোমেটিক ইঞ্জিন ইনস্টলের জন্য `curl`, একটি POSIX `sh`, এবং `tar`-ও লাগে; নেটিভ Windows ম্যানুয়াল পিন করা `iii.exe`, WSL2, বা Docker Desktop ব্যবহার করে।
+
+
+
+ Váš kódovací agent si pamatuje všechno. Žádné další opakované vysvětlování.
+ Založeno na iii engine
+
+ Trvalá paměť pro Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode a jakéhokoli klienta MCP.
+
+ Tento gist rozšiřuje Karpathyho vzor LLM Wiki o hodnocení spolehlivosti, životní cyklus, znalostní grafy a hybridní vyhledávání: agentmemory je jeho implementací.
+
+
+---
+
+## Instalace
+
+Požadavky:
+
+- Node.js 20 nebo novější s npm a npx (`node -v`, `npm -v` a `npx -v`).
+- Automatická instalace iii-engine na macOS/Linuxu vyžaduje také `curl`, POSIX `sh` a `tar`. Minimální image, jako je `node:20-slim`, je nemusí obsahovat.
+- Nativní Windows vyžaduje manuální instalaci pinned verze iii-engine v0.22.1 `iii.exe`. Dalšími podporovanými cestami jsou WSL2 nebo Docker Desktop.
+
+Kanonický příkaz pro čistou instalaci:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+První spuštění je interaktivní nastavení: vyberete agenty, které chcete propojit (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), vyberete poskytovatele LLM nebo zůstanete bez klíče, nastavení vytvoří konfiguraci, spustí server paměti i jeho pinned iii engine a nabídne globální instalaci, aby pak všude fungoval holý příkaz `agentmemory`. `-y` potvrzuje dotaz npx na balíček a `@latest` zabraňuje použití zastaralého cachovaného vydání. Poskytovatel zpřístupní funkce LLM, ale komprese pozorování psaná pomocí LLM se spustí až po nastavení `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Režim bez klíče (keyless) vypíná vektorová embeddingy. `memory_recall` (cesta `mem::search`) používá BM25, zatímco `memory_smart_search` může navíc kombinovat strukturální shody ze znalostního grafu, pokud už grafová data existují. Pro bezplatné sémantické vyhledávání přímo na zařízení nastavte `EMBEDDING_PROVIDER=local` v `~/.agentmemory/.env` a restartujte. První požadavek na embedding stáhne `Xenova/all-MiniLM-L6-v2`; po tomto prvním stažení modelu běží inference lokálně.
+
+Lokální runtime používá čtyři porty: `3111` pro REST/MCP HTTP, `3112` pro iii streamy, `3113` pro viewer a `49134` pro WebSocket iii workeru. Trvalý stav iii žije v `~/Library/Application Support/agentmemory` na macOS, v `$XDG_DATA_HOME/agentmemory` nebo `~/.local/share/agentmemory` na Linuxu a v `%APPDATA%\agentmemory` na Windows. Pro jeho přepsání použijte `--data-dir ` nebo `AGENTMEMORY_DATA_DIR` a při každém restartu použijte stejnou hodnotu. Z důvodu zpětné kompatibility má existující `./data/state_store.db` nebo `./data/iii-config.yaml` pro instanci 0 přednost před výchozí hodnotou dané platformy; explicitní přepínač nebo proměnná prostředí má přednost i nad tím.
+
+Pak ověřte, že vyhledávání funguje, a dejte svému agentovi jeho skills:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # naseje ukázkové sessions + vyzkouší vyhledávání
+npx skills add rohitg00/agentmemory -y # 17 nativních skills, aby agent věděl, kdy sáhnout po paměti
+```
+
+Hledání klíčových slov by mělo fungovat ve výchozím režimu bez klíče přes BM25. Dotaz dema `database performance optimization` je záměrně sémantický a dokud není nakonfigurován poskytovatel embeddingů, může vracet nulu výsledků.
+
+Chcete, aby celou věc provedl kódovací agent? Dejte mu jedinou instrukci:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Další agenty můžete kdykoli propojit pomocí `agentmemory connect ` — 20 adaptérů je uvedeno v sekci [Funguje s každým agentem](#works-with-every-agent). Úplný přehled příkazů najdete v sekci [Rychlý start](#quick-start).
+
+
+Windows
+
+Nejrychlejší cestou je WSL2. Nativní nastavení enginu na Windows vyžaduje manuální stažení pinned ZIP v0.22.1 a manuální extrakci `iii.exe`; CLI ho automaticky nerozbaluje. Podporován je i Docker Desktop. Postup krok za krokem najdete v [poznámkách k Windows](#windows).
+
+
+
+
+Globální instalace / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Výše uvedený příkaz npx zůstává kanonickou cestou pro čistou instalaci a vyhne se problémům s oprávněními globálního prefixu.
+
+
+
+
+npx vrací starou verzi
+
+npx cachuje podle verze. Vynuťte nejnovější verzi pomocí `npx -y @agentmemory/agentmemory@latest`, nebo jednou vymažte cache pomocí `rm -rf ~/.npm/_npx` (macOS/Linux; na Windows smažte `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Už mám běžící vlastní iii engine
+
+agentmemory je pinned na iii-engine v0.22.1 a nepřipojí se k jiné verzi (worker neumí mluvit protokolem jiného enginu). Zastavte jiný engine a pak spusťte `npx -y @agentmemory/agentmemory@latest`. Nainstaluje a spustí pinned v0.22.1 v `~/.agentmemory/bin`, aniž by se dotkl vašeho vlastního `iii`.
+
+
+
+---
+
+
+
+agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST API. Všichni agenti sdílejí stejný server paměti.
+
+
+ Funguje s jakýmkoli agentem, který mluví MCP nebo HTTP. Jeden server, paměti sdílené mezi všemi z nich.
+
+
+---
+
+Stejnou architekturu vysvětlujete při každé session. Znovu objevujete stejné chyby. Znovu vysvětlujete stejné preference. Vestavěná paměť (CLAUDE.md, .cursorrules) má strop 200 řádků a postupně zastará. agentmemory to řeší. Tiše zachycuje, co váš agent dělá, komprimuje to do prohledávatelné paměti a při startu další session vloží ten správný kontext. Jeden příkaz. Funguje napříč agenty.
+
+**Co se změní:** V session 1 nastavíte JWT autentizaci. V session 2 požádáte o rate limiting. Agent už ví, že vaše autentizace používá middleware jose v `src/middleware/auth.ts`, že vaše testy pokrývají validaci tokenů a že jste zvolili jose před jsonwebtoken pro kompatibilitu s Edge, bez opakovaného vysvětlování a bez copy-pastování.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Ve výchozím nastavení agentmemory ukládá stav iii-engine mimo repozitář, ze kterého jej spouštíte: `~/Library/Application Support/agentmemory` na macOS, `$XDG_DATA_HOME/agentmemory` nebo `~/.local/share/agentmemory` na Linuxu a `%APPDATA%\agentmemory` na Windows. Existující starší `./data/state_store.db` nebo `./data/iii-config.yaml` se pro instanci 0 použije ještě před touto výchozí hodnotou platformy. Pro explicitní volbu umístění použijte `--data-dir ` nebo nastavte `AGENTMEMORY_DATA_DIR`; kterékoli z explicitních nastavení má přednost před starším vyhledáváním:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Nativní i Docker spouštění používají stejný vyřešený hostitelský adresář; Docker ho připojí (bind-mount) jako `/data`. `--instance 1` připojí k vyřešenému adresáři `instance-1` a zvolí samostatnou výchozí čtveřici portů `3211/3212/3213/49234`.
+
+Nejnovější poznámky k vydání: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Přesnost vyhledávání
+
+**coding-agent-life-v1** (vlastní korpus, reprodukovatelný v sandboxu)
+
+| Adaptér | P@5 | R@5 | Úspěšnost top-5 | latence p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% úspěšnost top-5 na **matematickém stropu P@5** pro tento korpus (0.240, viz scorecard). Hybrid najde každou zlatou session; grep mine 1 ze 2 zlatých u vícesessionového temporálního dotazu. Zisk je v **recall + temporalitě**, ne v agregátní přesnosti. Tento benchmark je malý a s málo zlatými případy; větší LongMemEval-S níže rozlišuje lépe. Úplný rozpad podle typu + oprava: [`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 otázek)
+
+| Systém | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| záložní režim pouze BM25 | 86.2% | 94.6% | 71.5% |
+
+
Manuální revize; automatické směrování se připravuje
+
Žádný
+
Neuvedeno
+
Rozpad + konsolidace
+
Manuální prořezávání
+
+
+
Efektivita tokenů
+
~1,900 tokenů/session ($10/rok)
+
Liší se podle integrace
+
Klíčová paměť v kontextu
+
Liší se
+
Cloudové ceny
+
Neuvedeno
+
Žádný rozpočet tokenů
+
Založeno na LLM (liší se)
+
Liší se
+
22K+ tokenů při 240 obs.
+
+
+
Viewer v reálném čase
+
Ano (port 3113)
+
Cloudový dashboard
+
Cloudový dashboard
+
Webové UI
+
Cloudový dashboard
+
Webové UI hubu
+
Ne
+
Ne
+
Ne
+
Ne
+
+
+
Self-hosted
+
Ano (výchozí)
+
Volitelné
+
Volitelné
+
Ano
+
Ne (pouze cloud)
+
Ano (Docker)
+
Ano
+
Ano (Oracle DB)
+
Ano
+
Ano
+
+
+
+Poznámka k benchmarku: pouze R@5 pro agentmemory je náš vlastní naměřený výsledek (LongMemEval-S, reprodukovatelný z benchmark/COMPARISON.md). Čísla pro mem0 a Letta jsou jejich publikované hodnoty LoCoMo (jiný dataset); čísla pro MemPalace, supermemory, TencentDB (PersonaMem) a oracleagentmemory jsou tvrzení výrobců, která jsme nezávisle nereprodukovali (běh oracleagentmemory použil GPT-5.5 proti Oracle AI Database). Uvedeno vedle sebe jen pro orientační srovnání, nejde o přímé porovnání na identických datech. Počty hvězd jsou orientační a v čase se mění.
+
+**Novější konkurenti**, o kterých má smysl vědět, podrobně srovnáni v [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Systém | ⭐ | Přístup |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporální znalostní graf; nejsilnější publikované výsledky pro temporální dotazy (LongMemEval 63.8%), ale graf se buduje asynchronně, takže čerstvá fakta mohou zpožďovat |
+| Cognee | 30K | Načítání dokumentů do znalostního grafu, pouze Python, navrženo pro strukturovanou extrakci entit, nikoli pro zachytávání sessions |
+
+Nic z toho automaticky nezachytává data z hooks kódovacího agenta, nedodává lokální viewer jako primární prvek ani neumí běžet bez klíče — to je kombinace, kolem které je agentmemory postaveno.
+
+---
+
+
+
+Kompatibilita: toto vydání cílí na `iii-sdk` 0.22.1 a je pinned na iii-engine v0.22.1.
+
+### Vyzkoušejte to za 30 sekund
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` naseje 3 realistické sessions (JWT autentizace, oprava N+1 dotazu, rate limiting) a spustí proti nim vyhledávání. Instalace bez klíče vypínají vektory, takže klíčové dotazy `mem::search` by měly fungovat přes BM25, zatímco `database performance optimization` může vrátit nulu. `smart-search` může navíc vrátit strukturální shody z grafu, pokud grafová data existují. Aby sémantický dotaz našel opravu N+1 přes vektory, nastavte `EMBEDDING_PROVIDER=local`, restartujte a počkejte, až se dokončí první stažení modelu.
+
+Otevřete `http://localhost:3113` a sledujte, jak se paměť živě staví.
+
+### Ověření čisté instalace a persistence po restartu
+
+Se spuštěným serverem ověřte REST, health, viewer a stav runtime podporovaného iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Startovní panel připravenosti pokrývá všechny čtyři porty: REST/MCP HTTP na 3111, iii streamy na 3112, viewer na 3113 a WebSocket iii workeru na 49134. `status` potvrzuje zdraví agentmemory a aktivní režim poskytovatele/embeddingů. Uložte sondu a ověřte, že je vyhledatelná:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Pak spusťte `npx -y @agentmemory/agentmemory@latest stop`, znovu spusťte kanonický příkaz v terminálu 1, počkejte na `/agentmemory/livez` a vyhledávání zopakujte. Sonda musí být stále vrácena. Pokud jste zvolili vlastní `--data-dir`, použijte při restartu stejný adresář.
+
+### Běžné příkazy
+
+Instalace a nastavení jsou popsány výše v sekci [Instalace](#install) (první spuštění vás jimi provede). Den za dnem:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Replay session
+
+Každou session, kterou agentmemory zaznamená, lze přehrát. Otevřete viewer, zvolte záložku **Replay** a projděte se časovou osou: prompty, volání nástrojů, výsledky nástrojů a odpovědi se vykreslují jako samostatné události s play/pause, řízením rychlosti (0.5x až 4x) a klávesovými zkratkami (mezerník pro přepnutí, šipky pro krokování).
+
+Pro import starších JSONL transkriptů z Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Importované sessions se objeví ve výběru Replay vedle nativních. Pod kapotou každá položka jde přes iii funkce `mem::replay::load`, `mem::replay::sessions` a `mem::replay::import-jsonl`, bez vedlejších serverů. Každý importovaný transkript je indexován pro vyhledávání, oražen původním kanálem `import` a prohledán na session crystal a lessons.
+
+> **Upozornění, pokud se spoléháte na `import-jsonl` jako hlavní cestu zachycení:** `cleanupPeriodDays` v Claude Code (v `~/.claude/settings.json`, výchozí **30**) automaticky maže JSONL transkripty starší než toto okno z `~/.claude/projects/`. Pokud instalujete agentmemory nově na měsíce starou historii Claude Code, vše starší než 30 dní je už pryč před prvním importem. Buď spouštějte `import-jsonl` na cronu, zvyšte `cleanupPeriodDays` na vyšší hodnotu, nebo zapojte hooks pro automatické zachycení (výchozí cesta instalace pluginu), aby se každý tah ukládal do agentmemory už za běhu session a čištění JSONL přestalo hrát roli.
+
+### Upgrade / údržba
+
+Příkaz pro údržbu použijte, když chcete úmyslně aktualizovat svůj lokální runtime:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Varování: tento příkaz mění aktuální workspace/runtime. Může aktualizovat JavaScript závislosti a stáhnout pinned Docker image `iiidev/iii:0.22.1`. Nikdy nenainstaluje nepinned nebo novější iii engine.
+
+Detaily implementace jsou v `src/cli.ts` (viz `runUpgrade` kolem oblasti `src/cli.ts:544-595`).
+
+### Claude Code (jeden blok, vložte ho)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code bez instalace pluginu (cesta MCP-standalone)
+
+Pokud zapojíte server MCP agentmemory přímo přes `~/.claude.json` místo použití `/plugin install`, Claude Code nikdy nevyřeší `${CLAUDE_PLUGIN_ROOT}` a musíte nasměrovat skripty hooks na absolutní cesty v `~/.claude/settings.json`. Tyto cesty typicky obsahují verzi agentmemory (např. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), takže další upgrade tiše rozbije všechny hooks.
+
+Řešení:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Toto sloučí stejné příkazy hooks do `~/.claude/settings.json` s absolutními cestami vyřešenými na balíčený adresář `plugin/` aktuálně nainstalovaného balíčku `@agentmemory/agentmemory`. Po upgradu agentmemory příkaz spusťte znovu, aby se cesty obnovily. Uživatelské položky ve stejném souboru zůstanou zachovány; nahrazeny jsou pouze předchozí položky agentmemory. Doporučovaným přístupem zůstává cesta přes `/plugin install`.
+Pro vzdálená nebo chráněná nasazení spusťte Claude Code s nastaveným `AGENTMEMORY_URL` a `AGENTMEMORY_SECRET`. Plugin obě hodnoty předá svému zabalenému serveru MCP; když je `AGENTMEMORY_URL` prázdné, shim MCP použije `http://localhost:3111`.
+
+### Codex CLI (platforma pluginů Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Plugin pro Codex se dodává ze stejného adresáře `plugin/` jako plugin pro Claude Code. Registruje:
+
+- Zabalený stdio MCP most k běžícímu daemonu, bez stažení přes npm nebo fallback úložiště. Viz [lokální průvodce Codexem](../docs/plugins/codex-local.md) pro testování nevydaného buildu.
+- 6 hooks životního cyklu: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 vyvolatelných skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 referenčních skills, které agent načítá podle potřeby (disciplína paměti, nástroje MCP, REST API, konfigurace, agenti, hooks, architektura a průvodce psaním skills)
+
+Enginový hook Codexu vkládá `CLAUDE_PLUGIN_ROOT` do subprocesů hooks (podle [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), takže stejné skripty hooks fungují na obou hostitelích bez duplikace. Události Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure jsou pouze pro Claude Code a pro Codex se neregistrují.
+
+#### Důvěra a kompatibilita hooků Codexu
+
+Nativní vyvolávání hooků pluginu je ověřeno s Codex CLI 0.150.1. Před očekáváním zachycení udělte hookům pluginu důvěru (trust). Chování Codex Desktop závisí na jeho zabaleném runtime; zkontrolujte `/hooks` a potvrďte zachycenou událost, než povolíte náhradní řešení.
+
+Pokud váš hostitel vyžaduje globální hooky, zrcadlete příkazy do `~/.codex/hooks.json`. Když je MCP již zapojené, současný konektor potřebuje `--force`, aby se dostal k instalaci hooků:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Tohle sloučí globální hooky a přepíše záznam MCP agentmemory, při zachování nesouvisejících položek. Před použitím `--force` zkontrolujte veškerá vlastní nastavení endpointu agentmemory. Po upgradu spusťte znovu, abyste obnovili cesty ke skriptům. Povolte buď nativní hooky pluginu, nebo globální kopie, abyste se vyhnuli duplicitnímu zachycení.
+
+### GitHub Copilot CLI
+
+Pro agentní režim VS Code použijte [průvodce MCP a automatickým zachycením pro Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Konektor CLI nekonfiguruje VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` sloučí `mcpServers.agentmemory` do `~/.copilot/mcp-config.json` (nebo `$COPILOT_HOME/mcp-config.json`, pokud je nastaveno `COPILOT_HOME`) a zachová existující servery. Na nativním Windows je to jediný automatizovaný adaptér `connect`; každého dalšího nativního agenta na Windows nakonfigurujte manuálně. `connect` ve WSL je podporován pouze tehdy, když je cílový agent nainstalován ve stejném prostředí WSL. Copilot si server MCP vyzvedne při dalším spuštění nebo po `/mcp`. Pro plný zážitek s hooks/skills nainstalujte i plugin.
+
+
+OpenClaw (vložte tento prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Úplný návod: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (vložte tento prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Úplný návod: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Další agenti
+
+Spusťte server paměti: `npx -y @agentmemory/agentmemory@latest`
+
+#### Nativní skills přes `npx skills add` (50+ agentů)
+
+agentmemory dodává 17 skills ve formátu `/SKILL.md` ve stylu Claude Code: 9 vyvolatelných akčních skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) a 8 referenčních skills, které agent načítá podle potřeby (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referenční skills obsahují datové tabulky generované ze zdroje, takže se nikdy neliší. CLI [`skills`](https://npmjs.com/package/skills) od vercel-labs je automaticky instaluje do nativního adresáře skills volajícího agenta napříč 50+ agenty (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf a dalšími):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Toto je **doplňkové** k `agentmemory connect `:
+
+- `agentmemory connect ` zapíše konfiguraci serveru MCP, aby byly nástroje k dispozici.
+- `npx skills add rohitg00/agentmemory` nainstaluje skills, aby agent věděl, kdy je má volat.
+
+Pro těch několik agentů, které CLI skills ještě nepokrývá (Zed v1.3.x a nižší), vložte 17 souborů SKILL.md do nativního adresáře skills agenta sami; stejný formát funguje všude.
+
+#### Standardní blok MCP
+
+Položka agentmemory je **stejný blok serveru MCP** na všech hostitelích, kteří používají tvar `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Sloučte tuto položku do existujícího objektu `mcpServers`** v konfiguračním souboru hostitele; soubor nenahrazujte. Pokud soubor už má jiné servery, přidejte `agentmemory` vedle nich jako další klíč uvnitř `mcpServers`. Pokud `mcpServers` zcela chybí, vložte blok do `{ "mcpServers": { ... } }`. Zástupné symboly `${VAR}` zdědí `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` ze shellu při spuštění serveru MCP; nenastavené proměnné předají prázdné řetězce a shim se vrátí na `http://localhost:3111`. Jeden zapojený záznam pokrývá lokální i vzdálená (k8s / za reverzní proxy) nasazení.
+
+| Agent | Konfigurační soubor | Poznámky |
+|---|---|---|
+| **Cursor (pouze MCP)** | `~/.cursor/mcp.json` | Sloučte do `mcpServers`, nebo použijte `agentmemory connect cursor`. Na webu je k dispozici i deeplink na jedno kliknutí. |
+| **Cursor (plný plugin)** | `.cursor-plugin/` | Záznam v Cursor Marketplace (podání čeká na schválení) nebo Cursor Settings → Plugins → lokální checkout. Registruje 7 hooks pro automatické zachycení (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + server MCP, přičemž `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` se správují v dashboardu pluginu Cursor. Funguje v IDE Cursor i v CLI `cursor-agent`; prompty v print-mode CLI se na konci session doplní zpětně z transkriptu session. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Sloučte do `mcpServers`. Po úpravě Claude Desktop restartujte. |
+| **Cline / Roo Code / Kilo Code** | nastavení MCP v Cline (Settings UI → MCP Servers → Edit) | Stejný blok `mcpServers`. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` sloučí položku MCP; `--with-hooks` přidá šest nativních hooks pro automatické zachycení (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) s malými písmeny v maticích nástrojů Devin. Ověřte pomocí `devin mcp list` a `/hooks` uvnitř devin. |
+| **Devin CLI (plný plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` z checkoutu zaregistruje všech 17 skills jako slash příkazy `/agentmemory:` plus server MCP. Hooks pluginu Devin neumí vyvolat `SessionStart`/`SessionEnd`, takže ho pro plné zachycení session kombinujte s `connect devin --with-hooks`. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Přidejte vlastní MCP (STDIO): příkaz `npx`, argumenty `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` ukazující na síťově dostupné nasazení agentmemory plus `AGENTMEMORY_SECRET` (cloudové sessions se nedostanou na localhost — viz [`deploy/`](../deploy/)). Uložte secret do Devin Secrets a pomocí „Test listing tools“ ověřte, že se objeví všech 54 nástrojů. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (sloučí se automaticky). |
+| **GitHub Copilot CLI (pouze MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` sloučí `mcpServers.agentmemory`; Copilot si ji vyzvedne při dalším spuštění nebo po `/mcp`. |
+| **GitHub Copilot CLI (plný plugin)** | instalace pluginu Copilot | `copilot plugin install rohitg00/agentmemory:plugin` pro plugin z podadresáře GitHub. |
+| **OpenClaw** | konfigurace MCP OpenClaw | Stejný blok `mcpServers`. Hlouběji: `openclaw plugins install ./integrations/openclaw` obsadí paměťový slot OpenClaw (automaticky přepne z `memory-core`); nastavte `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, jinak je zachycení tahů tiše blokováno. Viz [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (pouze MCP)** | `.codex/config.toml` | Tvar TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, nebo manuálně přidejte `[mcp_servers.agentmemory]`. |
+| **Codex CLI (plný plugin)** | marketplace pluginů Codex | `codex plugin marketplace add rohitg00/agentmemory`, pak `codex plugin add agentmemory@agentmemory`. Registruje MCP + 6 hooks životního cyklu + 17 skills. Důvěřujte hookům a ověřte zachycení ve svém hostiteli; viz [nastavení a validace Codexu](../docs/plugins/codex-local.md). |
+| **OpenCode (pouze MCP)** | `opencode.json` | Jiný tvar: klíč `mcp` na nejvyšší úrovni, příkaz jako pole: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plný plugin)** | `plugin/opencode/` | 22 hooks pro automatické zachycení pokrývajících životní cyklus session, zprávy, nástroje a chyby. Přiřazení k projektu je po jednotlivých sessions, takže jeden proces OpenCode pokrývající více repozitářů zařadí každou session pod její vlastní projekt. Dva slash příkazy (`/recall`, `/remember`). Zkopírujte `plugin/opencode/` do svého workspace OpenCode a doplňte položku pluginu do `opencode.json`. Úplnou tabulku hooks + analýzu mezer najdete v [`plugin/opencode/README.md`](../plugin/opencode/README.md). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` nainstaluje zabalené rozšíření do adresáře automatického vyhledávání pi (recall při startu agenta, zachycení při konci agenta, nástroje `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` v běžícím pi ho načte. [`integrations/pi`](../integrations/pi/) je také balíček pi (`pi install ./integrations/pi` z checkoutu). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` dá poskytovatele paměti se 6 hooks (prefetch, zachycení tahu, konec session, pre-compress, zrcadlení MEMORY.md, blok systémového promptu). Ověřte pomocí `hermes plugins doctor` a `hermes memory status`. Viz [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` zapíše standardní blok `mcpServers`. Payload hooks je polově kompatibilní s Claude Code, takže existující skripty pro 12 hooks fungují bez úprav; zapojte je přes sekci `hooks` ve stejném `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` nainstaluje MCP a hooky pro zachycení do sdíleného adresáře přizpůsobení. Viz [nastavení a limity Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` používá stejnou konfiguraci MCP a hooků jako aktuální verze IDE. Stávající instalace by měly provést refresh pomocí `--force`; viz [poznámky k upgradu](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` zapíše konfiguraci na úrovni uživatele. Přepisy na úrovni workspace patří do `.kiro/settings/mcp.json` vedle vašeho kódu. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` zapíše standardní blok `mcpServers`. Warp také automaticky vyhledává skills z `.claude/skills/`; po instalaci pluginu Claude Code se 8 skills agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) objeví nativně v paletě slash příkazů Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` zapíše standardní blok `mcpServers`. Uživatelé rozšíření VS Code: vložte stejný blok přes Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferované) nebo `config.json` (starší) | `agentmemory connect continue` vytvoří `config.yaml` od nuly, pokud žádný z nich neexistuje, nebo upraví existující `config.json`. **Pokud už máte `config.yaml`**, adaptér vypíše přesný blok k vložení pod `mcpServers:`; váš yaml tiše nepřepíše, protože bezpečné zachování komentářů a kotev vyžaduje parser YAML, který balíček nedodává. Continue používá pro `mcpServers` formu pole (ne objektu). |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` zapíše pod `context_servers` (klíč Zed, NE `mcpServers`). Vzdálené servery MCP lze zapojit místo toho přes `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` zapíše standardní blok `mcpServers`. Přepisy na úrovni projektu patří do `/.factory/mcp.json`. Pro nativní automatické zachycení přidejte `--with-hooks`. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` připojí řádek `@deepseek-ai/dsh-mcp-client` do vrstvy patchů na úrovni home, kterou načítá každý profil Harness; nástroje se registrují jako `mcp__agentmemory__*`. Pro zapojení i automatického zachycení přidejte `--with-hooks`: zabalené skripty hooks pro Claude Code běží přes vlastní most Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) pomocí manifestu zapsaného do `$DSH_HOME/agentmemory.hooks.json`. Pokud `DSH_HOME` není nastaveno, výchozí je `~/.dsh`. |
+| **Goose** | UI nastavení MCP v Goose | Stejný blok `mcpServers`; použijte `goose configure` → Add Extension → MCP. Přímá úprava YAML v `~/.config/goose/config.yaml` je podporována, ale schéma používá `extensions:` + `cmd` (ne `mcpServers:` + `command`). |
+| **Aider** | n/a | Mluvte přímo s REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Jakýkoli agent (32+)** | n/a | `npx skillkit install agentmemory` automaticky detekuje hostitele a sloučí konfiguraci. |
+
+**Sandboxovaní klienti MCP** (Flatpak / Snap / omezující kontejnery), kteří se nedostanou na `localhost` hostitele: navíc nastavte `"AGENTMEMORY_FORCE_PROXY": "1"` v bloku `env` a nasměrujte `AGENTMEMORY_URL` na cestu, na kterou se sandbox skutečně dostane (např. vaši LAN IP adresu).
+
+### Programový přístup (Python / Rust / Node)
+
+agentmemory registruje své klíčové operace jako iii funkce (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Jakýkoli jazyk s iii SDK je může volat přímo přes `ws://localhost:49134`, bez samostatného klienta REST pro každý jazyk.
+
+```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"},
+})
+```
+
+Hotový příklad: [`examples/python/`](../examples/python/) (quickstart + průběh observation/recall). REST na `:3111` zůstává dostupné pro hostitele bez runtime iii.
+
+### Ze zdroje
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Tím se spustí agentmemory s lokálním `iii-engine`, pokud je pinned binárka už nainstalována, nebo se použije Docker Compose, pokud je zvolen. REST, streamy a viewer se ve výchozím stavu váží na `127.0.0.1`. Automatická cesta binárky pro macOS/Linux vyžaduje `curl`, POSIX `sh` a `tar`.
+
+Nainstalujte `iii-engine` manuálně. **agentmemory je momentálně pinned na `iii-engine` ve verzi `v0.22.1`**, stejné vydání jako jeho závislost `iii-sdk`; worker mluví protokolem tohoto enginu a 0.20.0 přeorganizovalo povrch SDK, takže se obě verze ve vydáních agentmemory pohybují společně. Přepište pomocí `AGENTMEMORY_III_VERSION=`, pokud provozujete vlastní engine a víte, že sedí.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** nahraďte `aarch64-apple-darwin` za `x86_64-apple-darwin`
+- **Linux x64:** nahraďte za `x86_64-unknown-linux-gnu`
+- **Linux arm64:** nahraďte za `aarch64-unknown-linux-gnu`
+- **Windows:** stáhněte `iii-x86_64-pc-windows-msvc.zip` z [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) a rozbalte `iii.exe` do `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Každý archiv má na stránce vydání odpovídající soubor `.sha256`; při výměně platformy použijte hash z tohoto souboru ve výše uvedené kontrole (na Windows: `Get-FileHash`). Automatický instalátor v `npx @agentmemory/agentmemory` má tyto hashe pevně dané a odmítne archiv, který nesedí.
+
+Nebo použijte Docker (zabalený `docker-compose.yml` stahuje `iiidev/iii:0.22.1`). Úplná dokumentace: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory běží na Windows 10/11, ale samotný balíček Node.js nestačí; potřebujete také pinned runtime iii-engine v0.22.1 jako proces na pozadí. CLI nerozbaluje Windows ZIP automaticky, takže uživatelé nativního Windows musí `iii.exe` nainstalovat manuálně, použít WSL2, nebo zvolit Docker Desktop.
+
+Automatizované zapojení MCP na nativním Windows podporuje pouze `agentmemory connect copilot-cli`. Pro Claude Code, Codex, Cursor a každého dalšího nativního agenta na Windows zkopírujte manuální blok MCP ze sekce [Další agenti](#other-agents) do konfigurace daného agenta na Windows. Spouštění `connect` ve WSL je vhodné pouze tehdy, když je cílový agent nainstalován ve stejném prostředí WSL; nijak neupravuje konfiguraci agenta na hostiteli Windows.
+
+**Varianta A: předpřipravená binárka pro Windows (doporučeno)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Varianta B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Varianta C: pouze samostatné MCP (bez enginu).** Pokud pro svého agenta potřebujete jen nástroje MCP a nepotřebujete REST API, viewer ani cron úlohy, engine úplně vynechte:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostika pro Windows:** pokud `npx -y @agentmemory/agentmemory@latest` selže, spusťte ho znovu s `--verbose`, abyste viděli skutečný stderr enginu. Běžné způsoby selhání:
+
+| Příznak | Oprava |
+|---|---|
+| `The engine process started but the REST API never responded.` | Ověřte, že všechny čtyři odvozené porty jsou volné, zkontrolujte, že pinned `iii.exe` zůstal naživu, pak spusťte znovu s `--verbose` a prozkoumejte zachycený stderr enginu |
+| `Could not start iii-engine` | Není nainstalován ani `iii.exe`, ani Docker. Viz varianta A nebo B výše |
+| Konflikt portů | `netstat -ano \| findstr :3111` ukáže, co je obsazeno, pak to ukončete nebo použijte `--port ` |
+| Záložní řešení přes Docker se vynechá, i když je Docker nainstalován | Ujistěte se, že Docker Desktop skutečně běží (ikona v system tray) |
+
+> Poznámka: iii **engine** je předpřipravená binárka, ne cargo crate, takže se ji nesnažte instalovat pomocí `cargo install`. (iii **SDK** jsou publikována na crates.io, npm a PyPI, ale agentmemory je nepotřebuje.) Všechny podporované metody instalace enginu jsou pinned na v0.22.1: výše uvedená předpřipravená binárka, automatická instalační cesta agentmemory pro macOS/Linux (vyžaduje `curl`, POSIX `sh` a `tar`) a Docker image `iiidev/iii:0.22.1`. Holé `install.sh | sh` z upstreamu nainstaluje nejnovější engine, který agentmemory nepodporuje. Použijte `npx -y @agentmemory/agentmemory@latest`; na macOS/Linuxu si stáhne pinned engine do `~/.agentmemory/bin`.
+
+---
+
+
Nasazení
+
+Šablony pro nasazení na jedno kliknutí u správovaných hostitelů. Každá z nich dodává samostatný
+Dockerfile, který stáhne `@agentmemory/agentmemory` z npm a zkopíruje
+binárku iii enginu z oficiálního Docker Hub image
+`iiidev/iii`; žádný předpřipravený image agentmemory není potřeba. Trvalé úložiště
+se připojuje na `/data`; entrypoint při prvním startu přepíše
+konfiguraci iii zabalenou v npm (která se váže na `127.0.0.1`) tou
+upravenou pro nasazení, která se váže na `0.0.0.0` a používá absolutní cesty `/data`, vygeneruje
+HMAC secret a pak sníží oprávnění z `root` na `node` pomocí
+`gosu` před spuštěním CLI agentmemory.
+
+
+
+
+
+
+Tlačítko pro nasazení na jedno kliknutí od Renderu vyžaduje `render.yaml` v kořeni repozitáře, který záměrně udržujeme čistý. Pro manuální nasměrování na blueprint v repozitáři použijte postup Render Blueprint popsaný v [`deploy/render/`](.././deploy/render/README.md).
+
+Úplné detaily nastavení (zachycení HMAC, SSH tunel pro viewer, rotace, zálohy,
+spodní hranice nákladů) jsou v [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): jeden stroj s
+ `auto_stop_machines = "stop"`; nejlevnější v nečinnosti.
+- [`deploy/railway`](.././deploy/railway/README.md): pevný poplatek plánu Hobby,
+ volume v dashboardu.
+- [`deploy/render`](.././deploy/render/README.md): postup Blueprint,
+ automatické snímky disku na placených plánech.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted na vlastním
+ VPS přes [Coolify](https://coolify.io/self-hosted); stejný Docker
+ Compose stack, host i data vlastníte vy.
+
+Publikován je pouze port `3111`. Viewer na `3113` zůstává uvnitř kontejneru
+vázán na loopback; postup SSH tunelu pro jeho dosažení je zdokumentován
+v README každé šablony.
+
+---
+
+
+
+Každý kódovací agent po skončení session zapomene všechno a každá nová session začíná tím, že znovu vysvětlujete svůj stack. agentmemory běží na pozadí a tento krok odstraňuje.
+
+```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 vestavěná paměť agenta
+
+Každý AI kódovací agent se dodává s vestavěnou pamětí: Claude Code má `MEMORY.md`, Cursor má poznámkové bloky, Cline má memory bank. Ty funguji jako lístečky na ledničku. agentmemory je prohledávatelná databáze za těmi lístečky.
+
+| | Vestavěné (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Rozsah | strop 200 řádků | neomezený |
+| Vyhledávání | načte vše do kontextu | BM25 + vektor + graf (pouze top-K) |
+| Náklady na tokeny | 22K+ při 240 pozorováních | ~1,900 tokenů (o 92% méně) |
+| Napříč agenty | soubory po agentech | MCP + REST (jakýkoli agent) |
+| Koordinace | žádná | leases, signály, akce, routiny |
+| Observabilita | manuální čtení souborů | viewer v reálném čase na :3113 |
+
+---
+
+
+
+### Pipeline paměti
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4úrovňová konsolidace paměti
+
+Vzor podle toho, jak lidský mozek zpracovává paměť, včetně konsolidace během spánku.
+
+| Úroveň | Co | Analogie |
+|------|------|---------|
+| **Pracovní** | Syrová pozorování z použití nástrojů | Krátkodobá paměť |
+| **Epizodická** | Komprimovaná shrnutí sessions | „Co se stalo" |
+| **Sémantická** | Extrahovaná fakta a vzory | „Co vím" |
+| **Procedurální** | Workflows a rozhodovací vzory | „Jak to udělat" |
+
+Paměti v čase slábnou (Ebbinghausova křivka). Často navštěvované paměti se zesilují. Zastaralé paměti se automaticky odstraňují. Rozpory se detekují a řeší.
+
+### Co se zachycuje
+
+| Hook | Zachycuje |
+|------|----------|
+| `SessionStart` | cestu k projektu, ID session |
+| `UserPromptSubmit` | uživatelské prompty (filtrované na soukromí) |
+| `PreToolUse` | vzory přístupu k souborům + obohacený kontext |
+| `PostToolUse` | název nástroje, vstup, výstup |
+| `PostToolUseFailure` | kontext chyby |
+| `PreCompact` | znovu vloží paměť před kompakcí |
+| `SubagentStart/Stop` | životní cyklus sub-agenta |
+| `Stop` | shrnutí na konci session |
+| `SessionEnd` | značka dokončení session |
+
+### Klíčové schopnosti
+
+| Schopnost | Popis |
+|---|---|
+| **Automatické zachycení** | každé použití nástroje se zaznamená přes hooks, bez manuálního úsilí |
+| **Sémantické vyhledávání** | BM25 + vektor + znalostní graf s fúzí RRF |
+| **Evoluce paměti** | verzování, nahrazování (supersession), grafy vztahů |
+| **Hygiena vyhledávání** | nahrazené verze paměti opustí vyhledávací indexy; řetězec verzí v KV si uchovává úplnou historii |
+| **Náznaky téměř-duplikátů** | ukládání nahlásí orientační shodu `similarTo`, když se nový obsah silně podobá existující paměti |
+| **Rozsah po agentech** | `agentId` prochází ukládáním a vyhledáváním přes REST, MCP i vyhledávací index, v režimu sdíleném nebo izolovaném |
+| **Původ v okamžiku zápisu** | každé pozorování a paměť nese neměnný kanál původu (user, agent, tool, import nebo shared) otištěný při zachycení, uložení a importu |
+| **Automatické zapomínání** | expirace TTL, detekce rozporů, odstranění podle důležitosti |
+| **Soukromí na prvním místě** | API klíče, secrets a značky `` se před uložením odstraní |
+| **Samoopravné chování** | circuit breaker, záložní řetězec poskytovatelů, monitorování zdraví |
+| **Most do Claude** | obousměrná synchronizace s MEMORY.md |
+| **Znalostní graf** | extrakce entit + BFS průchod |
+| **Týmová paměť** | sdílená i privátní, s namespacy mezi členy týmu |
+| **Původ citací** | dohledání jakékoli paměti zpět k výchozím pozorováním |
+| **Git snapshoty** | verzování, rollback a diff stavu paměti |
+
+---
+
+
+
+Trojproudové vyhledávání kombinující tři signály:
+
+| Proud | Co dělá | Kdy |
+|---|---|---|
+| **BM25** | shoda klíčových slov se stemmingem a rozšířením synonym | vždy zapnuto |
+| **Vector** | kosinová podobnost nad hustými embeddingy | nakonfigurován poskytovatel embeddingů |
+| **Graph** | průchod znalostním grafem přes shodu entit | v dotazu byly detekovány entity |
+
+Sloučeno pomocí Reciprocal Rank Fusion (RRF, k=60) a diverzifikováno po sessions (max 3 výsledky na session).
+
+Když je vektorový index naplněný, `mem::search` (za `memory_recall`) používá hybridní řadič BM25 + vektor. Bez embeddingů používá BM25. `smart-search` může navíc sloučit strukturální shody z grafu, pokud grafová data existují, včetně režimu bez klíče. Vyhledávání lessons běží na vyhrazeném in-memory indexu BM25 místo skenování celého korpusu při každém dotazu. Nahrazené verze paměti jsou vyloučeny z každé cesty vyhledávání; řetězec verzí uchovává jejich historii.
+
+Vektory přežijí pád nebo násilné vypnutí. Vektorový index se ukládá v dávkách nejvýše jednou za `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minut). Každý vektor přidaný nebo odstraněný mezitím se navíc okamžitě zapíše do malého čekajícího logu ve state store a při dalším startu se přehraje bez volání poskytovatele embeddingů. Každé úspěšné uložení log vyprázdní. Dokumenty, které po přehrání stále nemají vektor, se na pozadí znovu embedují v dávkách po `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), dokud žádné nezbydou, a zastavený backfill pokračuje při dalším startu. `/agentmemory/status` a viewer zobrazují velikost čekajícího logu a stav backfillu. Instalace bez klíče nic nezapisují.
+
+BM25 standardně tokenizuje řečtinu, cyrilici, hebrejštinu, arabštinu a akcentovanou latinku. Pro paměti v čínštině / japonštině / korejštině nainstalujte volitelné segmentery (`npm install @node-rs/jieba tiny-segmenter`), aby se běhy CJK rozdělily na tokeny na úrovni slov; bez nich agentmemory měkce spadne na tokenizaci celého běhu a jednou vypíše nápovědu na stderr.
+
+### Poskytovatelé embeddingů
+
+Instalace bez klíče vypínají vektorové embeddingy: `mem::search` používá BM25, zatímco `smart-search` může navíc použít existující strukturální grafová data. Pro bezplatné sémantické embeddingy přímo na zařízení přidejte toto do `~/.agentmemory/.env` a restartujte agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Běžná instalace npm obsahuje volitelný runtime `@huggingface/transformers`. První požadavek na embedding stáhne `Xenova/all-MiniLM-L6-v2`, takže potřebuje síťový přístup a může trvat déle; následná inference běží na zařízení. Vzdálení poskytovatelé jsou automaticky detekováni podle svých klíčů, pokud je nepřepíše `EMBEDDING_PROVIDER`.
+
+| Poskytovatel | Model | Náklady | Poznámky |
+|---|---|---|---|
+| **Lokální (doporučeno jako opt-in)** | `all-MiniLM-L6-v2` | zdarma | na zařízení po prvním stažení modelu, +8pp recall oproti samotnému BM25 |
+| Gemini | `gemini-embedding-001` | bezplatný tier | 100+ jazyků, rozměry 768/1536/3072 (MRL), vstup 2048 tokenů. Nahrazuje `text-embedding-004` ([deprecated, ukončení 14. 1. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | nejvyšší kvalita |
+| Voyage AI | `voyage-code-3` | placené | optimalizováno pro kód |
+| Cohere | `embed-english-v3.0` | bezplatná zkouška | univerzální použití |
+| OpenRouter | jakýkoli model | liší se | proxy pro více modelů |
+
+---
+
+
+
+54 nástrojů, 6 resources, 3 prompty a 17 skills.
+
+> **Shim MCP vs plný server:** publikovaný balíček `@agentmemory/mcp` je tenký shim. Celý povrch 54 nástrojů zpřístupní **pouze když se dostane k běžícímu serveru agentmemory** přes `AGENTMEMORY_URL` (proxy režim). Když žádný server není dostupný, shim se vrátí na lokální sadu 7 nástrojů (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Proměnná prostředí `AGENTMEMORY_TOOLS=core|all` je příznak *na straně serveru*; nastavení v bloku `env` shimu nemá žádný efekt. Pokud v Cursor / OpenCode / Gemini CLI vidíte jen 7 nástrojů, spusťte `npx -y @agentmemory/agentmemory@latest` (nebo Docker stack) a nastavte `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 nástrojů
+
+Tři povrchy nástrojů, od nejmenšího k největšímu: `AGENTMEMORY_TOOLS=core` omezí viditelnost na 8 nezbytných (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); základní sada níže je 14 základních nástrojů registru; výchozí nastavení (`AGENTMEMORY_TOOLS=all`) zpřístupní všech 54.
+
+
+Základní nástroje (14)
+
+| Nástroj | Popis |
+|------|-------------|
+| `memory_recall` | vyhledá minulá pozorování |
+| `memory_compress_file` | komprimuje soubory markdown při zachování struktury |
+| `memory_save` | uloží poznatek, rozhodnutí nebo vzor |
+| `memory_file_history` | minulá pozorování o konkrétních souborech |
+| `memory_patterns` | detekuje opakující se vzory |
+| `memory_sessions` | vypíše nedávné sessions |
+| `memory_smart_search` | hybridní sémantické + klíčové vyhledávání |
+| `memory_vision_search` | vyhledává pozorování z obrázků |
+| `memory_timeline` | chronologická pozorování |
+| `memory_profile` | profil projektu (koncepty, soubory, vzory) |
+| `memory_export` | exportuje všechna data paměti |
+| `memory_relations` | dotaz na graf vztahů |
+| `memory_commit_lookup` | sessions za konkrétním git commitem |
+| `memory_commits` | commity zaznamenané pro session |
+
+
+
+
+Rozšířené nástroje (celkem 54, výchozí povrch)
+
+| Nástroj | Popis |
+|------|-------------|
+| `memory_patterns` | detekuje opakující se vzory |
+| `memory_timeline` | chronologická pozorování |
+| `memory_relations` | dotaz na graf vztahů |
+| `memory_graph_query` | průchod znalostním grafem |
+| `memory_consolidate` | spustí 4úrovňovou konsolidaci |
+| `memory_claude_bridge_sync` | synchronizace s MEMORY.md |
+| `memory_team_share` | sdílení s členy týmu |
+| `memory_team_feed` | nedávné sdílené položky |
+| `memory_audit` | audit trail operací |
+| `memory_governance_delete` | smazání s audit trail |
+| `memory_snapshot_create` | snapshot verzovaný v gitu |
+| `memory_action_create` | vytvoří pracovní položky se závislostmi |
+| `memory_action_update` | aktualizuje stav akce |
+| `memory_frontier` | nezablokované akce seřazené podle priority |
+| `memory_next` | jediná nejdůležitější další akce |
+| `memory_lease` | exkluzivní leases akcí (multi-agent) |
+| `memory_routine_run` | instanciuje workflow routiny |
+| `memory_signal_send` | zprávy mezi agenty |
+| `memory_signal_read` | čte zprávy s potvrzením o přijetí |
+| `memory_checkpoint` | brány na externí podmínky |
+| `memory_mesh_sync` | P2P synchronizace mezi instancemi |
+| `memory_sentinel_create` | hlídače řízené událostmi |
+| `memory_sentinel_trigger` | vyvolá sentinely externě |
+| `memory_sketch_create` | efemérní grafy akcí |
+| `memory_sketch_promote` | povýší na trvalé |
+| `memory_crystallize` | zhuští řetězce akcí |
+| `memory_diagnose` | kontroly zdraví |
+| `memory_heal` | automatická oprava zaseknutého stavu |
+| `memory_facet_tag` | značky dimenze:hodnota |
+| `memory_facet_query` | dotaz podle facetových značek |
+| `memory_verify` | dohledá původ |
+
+
+
+### 6 resources · 3 prompty · 17 skills
+
+| Typ | Název | Popis |
+|------|------|-------------|
+| Resource | `agentmemory://status` | zdraví, počet sessions, počet pamětí |
+| Resource | `agentmemory://project/{name}/profile` | inteligence pro konkrétní projekt |
+| Resource | `agentmemory://project/{name}/recent` | nedávná pozorování pro projekt |
+| Resource | `agentmemory://memories/latest` | posledních 10 aktivních pamětí |
+| Resource | `agentmemory://graph/stats` | statistiky znalostního grafu |
+| Resource | `agentmemory://team/{id}/profile` | sdílený profil týmu |
+| Prompt | `recall_context` | vyhledá + vrátí kontextové zprávy |
+| Prompt | `session_handoff` | data pro předání mezi agenty |
+| Prompt | `detect_patterns` | analyzuje opakující se vzory |
+| Skill | `/recall` | vyhledá v paměti |
+| Skill | `/remember` | uloží do dlouhodobé paměti |
+| Skill | `/session-history` | nedávná shrnutí sessions |
+| Skill | `/forget` | smaže pozorování/sessions |
+
+Tabulka zobrazuje čtyři klíčové skills. Celá sada je 9 vyvolatelných skills plus 8 referenčních skills; viz sekce Nativní skills výše.
+
+### Samostatné MCP
+
+Spuštění bez plného serveru, pro jakéhokoli klienta MCP. Funguje kterékoli z tohoto:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Nebo přidejte do konfigurace MCP svého agenta:
+
+Většina agentů (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Sloučte položku `agentmemory` do existujícího objektu `mcpServers` vašeho hostitele, místo nahrazení celého souboru. Pro sandboxované klienty, kteří se nedostanou na `localhost` hostitele, přidejte do bloku env `"AGENTMEMORY_FORCE_PROXY": "1"` a nastavte `AGENTMEMORY_URL` na cestu, na kterou se sandbox dostane.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Zkopírujte soubor pluginu z repozitáře:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Automaticky se spouští na portu `3113`. Viewer při připojení načte jeden snapshot (`GET /agentmemory/viewer/snapshot`) a pak aplikuje živé streamové události: nové paměti, lessons, pozorování, audit záznamy, změny grafu a aktualizace zdraví se objevují bez pollingu nebo obnovení stránky. Jediné další požadavky jsou akce, na které kliknete, stránky „load more" a vyhledávání. Když stream vypadne, viewer ukáže, jak staré jsou jeho čísla, znovu se připojí s odstupňovaným zpomalením a znovu se sesynchronizuje z jednoho snapshotu.
+
+- **12 záložek ve čtyřech skupinách** s živými počty, deep linky (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), klávesovými zkratkami a mobilním menu.
+- **Memories:** vyhledávání na straně serveru, filtry podle projektu, agenta a typu, detailní panel s řetězcem verzí a diffem slov, odkazy na původ, tlačítka pro kopírování id, volání MCP a příkazu curl, úprava (nová verze), forget s potvrzením, hromadný forget a export JSON.
+- **Sessions:** vložená časová osa pozorování s čitelným vstupem a výstupem nástrojů, filtry a stránkování, a paměti i lessons, které každá session vyprodukovala.
+- **Graph:** vyhledávání, detail uzlu se vztahy a zdroji, legenda, která se nespoléhá jen na barvu, a ovládání zoomu.
+- **Health:** živá verze `GET /agentmemory/status`. Každý problém má svou opravu, plus backend state, stav uložení indexu, průběh komprese provenience grafu a vysvětlení konsolidace se skutečnými prahovými hodnotami.
+- **Stránky Audit, Activity, Profile, Replay, Lessons, Actions a Crystals**, každá s prázdným stavem, který říká, co daná sekce je, proč je prázdná a jaký příkaz ji naplní, a tooltip se slovníčkem `?` u každého termínu a čísla.
+
+```bash
+open http://localhost:3113
+```
+
+Server vieweru se ve výchozím stavu váže na `127.0.0.1` a při předávání požadavků na REST API přikládá server secret, takže nevyžaduje žádné nastavení. Endpoint `/agentmemory/viewer` zpřístupněný přes REST se řídí běžnými pravidly bearer tokenu a prohlížeče bez tokenu přesměruje na port vieweru. Hlavičky CSP používají nonce skriptu pro každou odpověď a vypínají inline handler atributy (`script-src-attr 'none'`).
+
+---
+
+
+
+Viewer na `:3113` ukazuje, co si váš agent **zapamatoval**. [iii console](https://iii.dev/docs/console) ukazuje, co váš agent **udělal**: každá operace s pamětí jako trace OpenTelemetry, každá položka KV editovatelná, každá funkce vyvolatelná, každý stream napojitelný. Dvě okna na stejnou paměť: jedno ve tvaru produktu, druhé ve tvaru enginu.
+
+Sledujte, jak se vyvolá `memory_smart_search`, a uvidíte skenování BM25 → vyhledání embeddingu → fúzi RRF → reranker jako waterfall. Upravte zaseknutý časovač konsolidace v prohlížeči KV. Přehrajte hook `PostToolUse` s upraveným payloadem. Připněte si WebSocket stream a sledujte, jak pozorování přicházejí živě.
+
+agentmemory tohle dodává zadarmo, protože každé volání funkce a trigger se vyvolává přes iii; nic na míru, nic k instrumentaci.
+
+
+
+
+ Stránka Workers: každý připojený worker, včetně samotného agentmemory, s PID, počtem funkcí, runtime a časem posledního výskytu.
+
+
+**Už je nainstalováno.** Console se dodává s pinned enginem `iii` (0.22+); není třeba nic instalovat zvlášť. Při prvním spuštění se binárka console stáhne vedle enginu.
+
+**Spuštění společně s agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Tím se spustí `iii console` pinned enginu proti portům, které agentmemory vyřešil (REST, streamy, bridge), a obslouží se o jeden port nad viewerem, výchozí `http://localhost:3114`. `--console-port N` zvolí jiný port; `--port` a `--instance` volí instanci agentmemory stejně jako u `stop`; jakýkoli jiný přepínač se předá dál, například `--enable-flow` pro experimentální stránku architekturního grafu.
+
+Totéž manuálně, užitečné, když `agentmemory` není v PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Co lze z console dělat:**
+
+| Stránka | K čemu slouží |
+|------|-----------|
+| **Workers** | zobrazí každého připojeného workera a jeho živé metriky, včetně samotného workeru agentmemory. |
+| **Functions** | vyvolá přímo jakoukoli funkci agentmemory s payloadem JSON; vhodné pro testování `memory.recall`, `memory.consolidate`, `graph.query` bez zapojování klienta. |
+| **Triggers** | přehraje triggery HTTP, cron, event a state: manuálně vyvolá cron konsolidace, zopakuje HTTP route, vyšle změnu stavu. |
+| **States** | prohlížeč KV s plným CRUD nad sessions, sloty paměti, časovači životního cyklu a indexem embeddingů; hodnoty lze upravovat na místě. |
+| **Streams** | živý monitor WebSocket pro zápisy paměti, události hooks a aktualizace pozorování, jak proudí přes iii streamy. |
+| **Queues** | trvalá témata queue + správa dead-letter. Přehrání nebo zahození neúspěšných úloh embeddingu / komprese. |
+| **Traces** | pohledy waterfall / flame / rozpad podle služby v OpenTelemetry. Filtrování podle `trace_id` ukáže přesně, které funkce, volání DB a požadavky na embedding jedno `memory.search` vyprodukovalo. |
+| **Logs** | strukturované logy OTEL filtrované a korelované na ID trace/span. |
+| **Config** | runtime konfigurace: přesně vidíte, s jakými workery, poskytovateli a porty váš engine běží. |
+| **Flow** | (volitelné, `--enable-flow`) interaktivní architekturní graf každého workeru, triggeru a streamu. |
+
+
+
+
+ Traces: waterfall / flame / rozpad podle služby pro každou operaci s pamětí.
+
+
+**Traces jsou už zapnuté:**
+
+`iii-config.yaml` se dodává se zapnutým workerem `iii-observability` (`exporter: memory`, `sampling_ratio: 0.1`, metriky + logy). Žádná další konfigurace není potřeba; ve chvíli, kdy agentmemory nastartuje, každá operace s pamětí vyšle strukturovaný log, který console umí číst, a jedna z deseti operací (`sampling_ratio: 0.1`) vyšle i trace span.
+
+Pokud chcete exportovat místo toho do Jaeger/Honeycomb/Grafana Tempo, změňte `exporter: memory` na `exporter: otlp` a nastavte endpoint kolektoru podle dokumentace observability iii.
+
+> **Upozornění:** na samotné console není vynucena žádná autentizace; udržujte ji vázanou na `127.0.0.1` (výchozí stav) a nikdy ji nevystavujte veřejně.
+
+---
+
+
+
+agentmemory je **už běžící instance [iii](https://iii.dev)**. Runtime skládají tři primitiva (worker, function, trigger); stav KV, streamy a trace OTEL pochází z workerů iii-state, iii-stream a iii-observability, které se dodávají s iii. Neinstalovali jste Postgres, Redis, Express, pm2 ani Prometheus, protože iii je nahrazuje.
+
+To znamená, že jeden další příkaz rozšíří agentmemory o celou novou schopnost.
+
+### Rozšiřte agentmemory dalšími workery
+
+Vestavěné (builtin) workery, které agentmemory potřebuje, jsou už v `iii-config.yaml` a startují s ním: `iii-state` (KV), `iii-queue` (trvalé opakování pro odběratele událostí), `iii-pubsub`, `iii-cron`, `iii-stream` a `iii-observability` (OTEL trace, metriky a logy u každé funkce). Cokoli dalšího z [registru workerů iii](https://workers.iii.dev) se zapojí do stejného enginu: zkopírujte `iii-config.yaml` do `~/.agentmemory/iii-config.yaml` (CLI tento soubor preferuje před zabaleným a pořád do něj vykresluje porty a cesty k datům), přidejte položku, jednou nainstalujte runtime workeru pomocí `~/.agentmemory/bin/iii update worker` a agentmemory restartujte.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Co navíc získáte oproti agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | adaptér stavu nad SQL, když vám výchozí KV nestačí |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | kód, který vyšel z `memory_recall`, běží uvnitř jednorázového VM, ne ve vašem shellu |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | postavte další servery MCP vedle toho od agentmemory, se stejným enginem |
+
+Na enginu 0.22.x zachovejte pro výše uvedené builtin workery názvy s prefixem `iii-`; nepreixované položky `http`, `state`, `queue`, `pubsub` a `cron` jsou samostatné workery z registru, na které se agentmemory přesune s migrací na 0.23.
+
+Úplný registr: [workers.iii.dev](https://workers.iii.dev). Každý worker tam skládá přes stejná primitiva, která používá agentmemory, a agentmemory, které už máte, je jedním z nich.
+
+### Konfigurace enginu a bind adresa
+
+`agentmemory start` čte konfiguraci enginu z prvního souboru, který existuje: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` v aktuálním adresáři, `~/.agentmemory/iii-config.yaml`, pak zabalený `iii-config.yaml`. Při každém startu tento soubor vykreslí (cesty k datům, porty, backend stavu) do `~/.agentmemory/data/iii-config.runtime.yaml` a engine spustí s vykresleným souborem, takže upravujte zdrojový soubor, ne ten vykreslený. Hodnoty `host:` ze zdrojového souboru se zachovávají tak, jak jsou napsané.
+
+Zabalený `iii-config.yaml` se váže na `127.0.0.1` zcela úmyslně, a tato výchozí hodnota platí i uvnitř kontejneru. CLI spuštěné v kontejneru poslouchá na loopbacku kontejneru, takže publikované porty se nikam nedostanou. Aby bylo kontejnerizované CLI dosažitelné přes publikované porty, nastavte `AGENTMEMORY_III_CONFIG` na konfiguraci, která se váže na `0.0.0.0`. Zabalený `iii-config.docker.yaml` je taková konfigurace: váže `iii-http`, `iii-stream` a port enginu na `0.0.0.0` a ukládá stav pod `/data`, takže tam připojte zapisovatelný volume. Mějte nastavené `AGENTMEMORY_SECRET` a publikujte jen porty, které potřebujete, na `127.0.0.1` nebo za proxy, které důvěřujete.
+
+`docker-compose.yml` z tohoto repozitáře nejde přes vyhledávání konfigurace v CLI: připojí `iii-config.docker.yaml` jako `/app/config.yaml` a kontejner `iii-engine` se spustí s `--config /app/config.yaml`. Šablony pro [nasazení na jedno kliknutí](../deploy/) si zapisují svou vlastní konfiguraci `0.0.0.0` ve svých entrypointech.
+
+### Úložný backend: file (výchozí) vs redis
+
+`iii-state` a `iii-stream` ve výchozím stavu používají zabalené souborové úložiště KV iii-engine: jeden JSON soubor na scope, držený v paměti procesu enginu a periodicky přepisovaný na disk. To je správná výchozí hodnota pro lokální instalaci jednoho uživatele; sdílený daemon s více souběžnými writery dostane místo toho skutečné zápisy po jednotlivých klíčích z Redis, za cenu síťového round-tripu na každou operaci (každé volání `state::*` se stejně serializuje na jednom spojení Redis, takže se tím vyměňuje zámek souborového úložiště za socket, ne za paralelismus).
+
+Nastavte `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`), abyste přepnuli oba workery na vestavěný adaptér `redis` iii-engine, který ukládá každý klíč jako pole hash Redis (`HSET`) místo přepisování celého scope při každém zápisu:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` má výchozí hodnotu `file`; když ho nenastavíte, dnešní chování se nezmění, a nerozpoznaná hodnota (cokoli jiného než `file` nebo `redis`) je chyba při startu, ne tichý fallback. `/agentmemory/status` a stránka Health ve viewer (řádek State store) hlásí, který backend je aktivní a zda odpovídá, nikdy ne URL.
+
+**Pouze čisté `redis://`.** Pinned engine (0.22.1) sestavuje svého klienta Redis bez podpory TLS, takže URL `rediss://` (většina správovaných nabídek Redis, jako Upstash, Redis Cloud a ElastiCache se šifrováním při přenosu, má ve výchozím stavu jen TLS) se nepřipojí. Spojení je nešifrované, takže heslo Redis i každá uložená paměť cestují po síti v čistém textu: nasměrujte na lokální Redis nebo na Redis v privátní síti, které důvěřujete. Pro jakýkoli jiný Redis spusťte šifrovaný tunel (stunnel, SSH nebo VPN) na hostiteli agentmemory, aby čistý skok `redis://` zůstal na tomto hostiteli a upstream spojení tunelu bylo šifrované a autentizované. Pokud heslo Redis obsahuje jednoduchou uvozovku, percent-encode ji (`%27`); engine URL rozvine do své konfigurace YAML ještě před parsováním.
+
+**Jeden server Redis na jeden `--instance`.** Prefixy klíčů Redis v enginu (`state:`, `stream::`) jsou pevné, takže dvě instance agentmemory (`--instance 1`, `--instance 2`, ...) nasměrované na stejnou databázi si přepíší data navzájem. Samostatný index databáze (`redis://localhost:6379/1`) udrží uložená data odděleně, ale engine přenáší živé události vieweru přes jeden pub/sub kanál Redis (`stream::events`), a pub/sub Redis ignoruje index databáze, takže viewer každé instance by i tak zobrazoval živé události té druhé. Pokud provozujete více než jednu instanci, dejte každé vlastní server (nebo port) Redis.
+
+**Co zůstává stejné a co se liší.** Na Redis funguje každá funkce agentmemory: sessions, pozorování, paměti (remember, supersede, evolve, forget), vyhledávání a indexové dávky, lessons, graf, audit log a jeho měsíční scopy, export a import, governance delete, stav konsolidace, snapshot vieweru a jeho živý stream, i health monitor. Engine ukládá každý scope jako jeden hash Redis (`HSET`/`HGET`/`HGETALL`) a vyvolává stejné state triggery jako souborové úložiště. Uvnitř agentmemory se ošetřují tři rozdíly enginu:
+
+- Redis vrací záznamy scope v žádném pevném pořadí. agentmemory je seřadí od nejstarších (podle času vytvoření v id záznamu, pak podle jeho timestampu), takže seznamy, stránkování a dávky exportu se vrátí ve stejném pořadí jako na souborovém úložišti.
+- Engine aplikuje částečné aktualizace na Redis ve skriptu Lua, který prázdná pole mění na prázdné objekty. agentmemory aplikuje tyto aktualizace sám (čti, změň, zapiš pod zámkem na klíč) na Redis, takže pole jako `tags: []` zůstanou poli.
+- Starší kontrola audit logu čte starý scope z Redis, místo hledání souboru souborového úložiště na disku.
+
+Jeden rozdíl vyžaduje vaši pozornost: **po restartu Redis engine přestane předávat živé události** vieweru, dokud se agentmemory nerestartuje. Data se stále normálně ukládají a čtou. Health monitor posílá testovací událost přes Redis každých 30 sekund; když se nevrátí, `/agentmemory/status` a stránka Health ve viewer zobrazí „Live updates are not reaching the viewer" s opravou: restartujte agentmemory. Pokud Redis neběží, status report zobrazí „The state store is not answering" a jak to ověřit (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Výpis velmi velkého scope čte celý hash v jednom `HGETALL`, se stejnými náklady, jako kdyby ho v paměti drželo souborové úložiště.
+
+**Doporučená nastavení Redis.** Výchozí snapshotová politika `save 3600 1 300 100 60 10000` může při pádu ztratit minuty zápisů, hůř než 5sekundové okno flush souborového úložiště. Nastavte `appendonly yes` pro cokoli, o co byste nerádi přišli. Nastavte `maxmemory-policy noeviction`; `allkeys-lru` nebo podobné tiše odhazují paměti, jakmile Redis narazí na svůj limit paměti.
+
+Nativní (nekontejnerový) start a každá šablona pro [nasazení na jedno kliknutí](../deploy/) (přepisují zabalený `iii-config.yaml` a startují nativně) čtou `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` a vykreslují je do spuštěné `iii-config`. Samotná URL se do tohoto vykresleného souboru nikdy nezapisuje, pouze odkaz `${AGENTMEMORY_REDIS_URL}`, který proces enginu rozvine ze svého vlastního prostředí při startu. Jen vlastní cesta Docker Compose tohoto repozitáře (`AGENTMEMORY_USE_DOCKER=1`, nebo navázání na engine už takto spuštěný) připojuje `iii-config.docker.yaml` jako read-only a nikdy nevykresluje; `agentmemory start` na tuto kombinaci varuje. Tento soubor přepněte manuálně, podle stejného tvaru `name: redis` / `config: redis_url: ...` uvedeného v dokumentaci workerů [iii-state](https://workers.iii.dev/workers/iii-state) a [iii-stream](https://workers.iii.dev/workers/iii-stream), a nasměrujte `redis_url` na Redis dostupný z kontejneru. `docker-compose.yml` předává `AGENTMEMORY_REDIS_URL` do kontejneru enginu, takže tam funguje `redis_url: '${AGENTMEMORY_REDIS_URL}'` a URL se tím nedostane do připojeného souboru.
+
+Vykreslená konfigurace udržuje URL mimo `~/.agentmemory/data/iii-config.runtime.yaml`, ale vlastní konfigurační worker enginu stejně po startu uloží *rozvinutou* hodnotu do `~/.agentmemory/config/iii-state.yaml` a `iii-stream.yaml` (expanze `${VAR}` v iii-engine proběhne dřív, než tento worker uloží svůj seed, a uloží se vyřešená hodnota, ne odkaz). Zacházejte s tímto adresářem, jako by obsahoval přihlašovací údaj: na jakémkoli sdíleném hostiteli udělejte `chmod 700 ~/.agentmemory` a dejte přednost uživateli ACL Redis omezenému na to, co agentmemory potřebuje, před administrátorskými údaji databáze.
+
+**Migrace není automatická.** Přepnutí `AGENTMEMORY_STATE_BACKEND` začíná na obou stranách od prázdného úložiště; nic nekopíruje existující data z file do Redis nebo zpět. Exportujte z backendu, který opouštíte, a importujte do toho, na který přecházíte. Toto běží identicky v bash i zsh (včetně `bash -u`). Pole jako `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` tak nefunguje: zsh zachová hlavičku jako jedno poškozené slovo, kde bash ji rozdělí na dvě, takže oba požadavky vrátí 401 pokaždé, když je `AGENTMEMORY_SECRET` nastaveno:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` také přijímá `?maxSessions=` a `?offset=` pro rozdělení velkého korpusu do více volání; `strategy` při importu je `merge` (bezpečná výchozí hodnota), `replace` nebo `skip`.
+
+### Co iii nahrazuje
+
+| Tradiční stack | agentmemory používá |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + in-memory vektorový index |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | dohled nad workery iii engine |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Vlastní systémy pluginů | `iii worker add ` |
+
+**225 zdrojových souborů · ~54,000 řádků kódu · 2,600+ testů · 312 funkcí · 66 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
+
+---
+
+
+
+### Poskytovatelé LLM
+
+agentmemory automaticky detekuje poskytovatele z vašeho prostředí. Poskytovatel zpřístupní operace založené na LLM, ale samotná konfigurace poskytovatele nezapíná kompresi pozorování psanou LLM. Tato cesta vyžaduje jak poskytovatele, tak `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Poskytovatel | Konfigurace | Poznámky |
+|----------|--------|-------|
+| **No-op (výchozí)** | konfigurace není potřeba | komprese/shrnutí přes LLM je vypnuto. Syntetická komprese a vyhledávání přes BM25 fungují i tak. Pokud jste se dříve spoléhali na záložní řešení přes předplatné Claude, viz `AGENTMEMORY_ALLOW_AGENT_SDK` níže. |
+| Anthropic API | `ANTHROPIC_API_KEY` | fakturace za token |
+| MiniMax | `MINIMAX_API_KEY` | kompatibilní s Anthropic |
+| Gemini | `GEMINI_API_KEY` | zapíná i embeddingy |
+| OpenRouter | `OPENROUTER_API_KEY` | jakýkoli model |
+| OpenAI API | `OPENAI_API_KEY` | výchozí `gpt-5.6-luna`, přepište pomocí `OPENAI_MODEL` |
+| **Lokální (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) nebo `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | cokoli kompatibilní s OpenAI API. Nulové náklady, běží na vašem hardwaru. Viz [Lokální modely](#local-models-ollama--lm-studio--vllm) níže. |
+| Záložní řešení přes předplatné Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | pouze opt-in. Spouští sessions `@anthropic-ai/claude-agent-sdk`; dříve to způsobovalo neomezenou rekurzi Stop-hook, takže už to není výchozí nastavení. |
+
+### Lokální modely (Ollama / LM Studio / vLLM)
+
+agentmemory komunikuje s jakýmkoli serverem kompatibilním s OpenAI API, takže cokoli, co zpřístupňuje `/v1/chat/completions`, funguje beze změn kódu. Žádné placené klíče, žádný cloud, žádné rate limity; běží čistě na vašem hardwaru.
+
+**Ollama** (výchozí port `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (výchozí port `1234`):
+
+Otevřete LM Studio → záložku Local Server → Start Server. V nabídce vyberte libovolný chat model (Qwen 3, gpt-oss, DeepSeek R1 atd.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: stejný tvar. Nasměrujte `OPENAI_BASE_URL` na URL, kterou zpřístupňuje váš server, a nastavte `OPENAI_MODEL` na název, který váš server přijme.
+
+**Výběr modelu pro práci s pamětí**: komprese a shrnutí jsou krátké úlohy (<2K tokenů na vstupu, <500 tokenů na výstupu), kde plně postačí 7B instruct model. Doporučení:
+
+| Model | Velikost | Proč |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | vyvážená výchozí volba na stroji s 16 GB; silný v extrakci a textu ve tvaru nástrojů |
+| `qwen3:4b` | ~2.6 GB | nejmenší rozumná volba; v pořádku pro kompresi, slabší pro extrakci grafu |
+| `qwen3-coder:30b` | ~19 GB | nejlepší lokální volba pro sessions ve tvaru kódu (30B MoE, 3.3B aktivních) na hardwaru 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | silný obecný model, který se vejde do 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | reasoning distill; pomalejší, ale čistší extrakce |
+
+Modely Qwen 3 ve výchozím stavu „myslí" a mohou spálit celý rozpočet tokenů na uvažování ještě před jakýmkoli výstupem. Nastavte `AGENTMEMORY_LLM_NOTHINK=1`, aby se k promptům pro extrakci grafu přidalo `/no_think`, a zvyšte `MAX_TOKENS` (16384 funguje), pokud se extrakce vrací prázdné.
+
+Modely třídy reasoning (ve stylu `o1` s bloky ``) mohou vracet prázdný `content` s polem `reasoning`, které váš lokální server nemusí zpřístupnit. Pokud se extrakce vrací prázdné, nejprve přepněte na model bez reasoning. Proměnná prostředí `OPENAI_REASONING_EFFORT=none` může také vypnout myšlení u thinking modelů Ollama Cloud, které zrcadlí schéma reasoning od OpenAI.
+
+Lokální embeddingy se dodávají jako volitelná závislost, ale ve výchozím stavu nejsou zapnuté. Nastavte `EMBEDDING_PROVIDER=local`, abyste zapnuli `Xenova/all-MiniLM-L6-v2` (384 dimenzí). První požadavek na embedding stáhne model; inference pak běží na zařízení. Bez tohoto nastavení nebo vzdáleného klíče pro embeddingy zůstávají vektory vypnuté, `mem::search` používá BM25 a `smart-search` může i tak přidat existující shody z grafu.
+
+### Výběr modelu s ohledem na náklady
+
+Když je komprese na pozadí psaná LLM zapnutá (poskytovatel i `AGENTMEMORY_AUTO_COMPRESS=true`), běží u každého pozorování, takže volba modelu výrazně ovlivní měsíční výdaje. Zachycená data o zátěži: 635 requestů / 888K tokenů / 35 hodin aktivního používání, spuštěno proti třem modelům OpenRouter podle ceníku z 2026-05-23.
+
+| Úroveň | Model | Vstup / 1M | Výstup / 1M | Náklady za zachycených 35h | Poznámky |
+|------|-------|------------|-------------|---------------------------|-------|
+| Doporučeno | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (odhad) | nejnovější DeepSeek; nejlevnější doporučená volba pro zátěž typu komprese. |
+| Doporučeno | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | solidní kvalita komprese + shrnutí za ~10× nižší náklady než Sonnet. |
+| Doporučeno | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | silné uvažování nad kódem, pokud jsou vaše sessions silně orientované na kód. |
+| Prémiová | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (odhad) | stejná ceníková cena jako naměřený běh Sonnet 4.6; úvodní cena $2/$10 do 2026-08-31. |
+| Prémiová | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (odhad) | vlajková úroveň; nákladná pro neustále běžící práci na pozadí. |
+| Vyhněte se | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (odhad) | model vlajkové třídy; přeplatíte za kompresi. |
+
+Naměřené řádky pocházejí ze zachyceného běhu; řádky (odhad) škálují stejnou směs tokenů podle ceníkové ceny každého modelu.
+
+agentmemory vypíše při startu varování, když `OPENROUTER_MODEL` odpovídá vzoru prémiové úrovně. Nastavte `AGENTMEMORY_SUPPRESS_COST_WARNING=1`, abyste ho umlčeli, jakmile učiníte informovanou volbu.
+
+Poměr kvality a nákladů pro práci s pamětí: komprese je úloha typu shrnutí s poměrně volnými nároky na kvalitu (shrnutí si znovu čte agent, ne uživatel). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder se v této úloze blíží Sonnet na úroveň zaokrouhlovací chyby, za 10-70× nižší náklady. Prémiové modely šetřete na dotazy, které čtete přímo vy.
+
+Zdroje: [ceník OpenRouter pro Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [poznámky k cenám DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Paměť pro víc agentů (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+V multi-agentních nastaveních, kde si několik rolí sdílí jeden server agentmemory (architekt / vývojář / reviewer / researcher / support agent), `AGENT_ID` oznamuje každý zápis rolí, která ho vytvořila. `AGENTMEMORY_AGENT_SCOPE` řídí, zda vyhledávání podle této značky filtruje.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Dva režimy:
+
+| Režim | Značí zápisy | Filtruje vyhledávání | Kdy použít |
+|------|------------|---------------|-------------|
+| `shared` (výchozí) | ano | ne | kontext napříč agenty s audit trail. Architekt vidí, co zaznamenal vývojář, ale každý řádek zaznamená, kdo to řekl. |
+| `isolated` | ano | ano | striktní oddělení. Architekt nikdy nevidí pozorování / paměti / sessions vývojáře. |
+
+Co se značí, když je `AGENT_ID` nastaveno: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Role prochází od `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Co se filtruje v izolovaném režimu: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Každý endpoint přijímá `?agentId=` pro přepsání na úrovni jednotlivého požadavku a `?agentId=*` pro úplné odhlášení z rozsahu dle env. `/memories` také přijímá `?includeOrphans=true`, aby se zobrazily paměti z doby před AGENT_ID, jejichž `agentId` je nedefinované.
+
+Přepsání na úrovni jednotlivého volání ve vrstvě SDK / REST: každý měnící endpoint (`/session/start`, `/remember`) přijímá pole `agentId` v těle požadavku, které má přednost před env. Užitečné pro runtime, které směrují mnoho rolí přes jeden proces serveru. Nástroj MCP `memory_save` zpřístupňuje stejné pole `agentId`, samostatný stdio server předává jak `agentId`, tak `project`, a uložené paměti nesou `agentId` do vyhledávacího indexu, takže vyhledávání v rozsahu agenta pokrývá jak paměti, tak pozorování.
+
+Když `AGENT_ID` není nastaveno, paměť zůstává bez rozsahu (starší chování, žádné značky, žádné filtry).
+
+### Porty
+
+agentmemory + iii-engine se ve výchozím stavu váží na čtyři porty. Pokud restart selže s `port in use`, tato tabulka vám řekne, jaký proces hledat.
+
+| Port | Proces | Účel | Přepis přes env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | interní worker streamů (využívá ho agentmemory + viewer) | `III_STREAM_PORT` (preferováno) nebo starší `III_STREAMS_PORT` |
+| `3113` | agentmemory | viewer v reálném čase (`http://localhost:3113`) | `III_VIEWER_PORT` nebo `AGENTMEMORY_VIEWER_URL` pro hlášenou URL |
+| `49134` | iii-engine | WebSocket; zde se registrují workery, protéká tím telemetrie OTel | `III_ENGINE_PORT` nebo `III_ENGINE_URL` |
+
+`--port ` změní kotvu REST a odvodí streamy `N+1`, viewer `N+2` a WebSocket enginu `N+46023`, jen pokud odpovídající explicitní port nebo URL výše není nastaven. Nevytváří izolovaný namespace životního cyklu. Pro druhý daemon použijte `--instance 1`; používá kotvu 3211, výchozí `3211/3212/3213/49234`, a dostane samostatný adresář dat a životního cyklu `instance-1`. Instance 1 až 50 se řídí stejným vzorem.
+
+Pinned engine startuje s `--no-update-check` (žádné vyhledávání aktualizací nebo bezpečnostních upozornění proti GitHubu při startu) a s vypnutou anonymní telemetrií používání iii: agentmemory nastaví `III_TELEMETRY_ENABLED=false` pro engine, který spouští, pokud si tuto proměnnou nevyexportujete sami, a zabalený soubor compose dělá totéž.
+
+Vyčištění zaseknutých procesů, když porty zůstanou obsazené po zhavarovaném běhu:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` čistě sklidí pidfile workeru i enginu při korektním nativním vypnutí. V režimu Docker vypláchne nativní worker, zastaví přesně validovaný kontejner enginu a zachová jak kontejner, tak jeho mount `/data` pro bezeztrátový restart; další start validuje a obnoví tentýž kontejner. Odinstalace postavená na Dockeru vyžaduje `agentmemory remove --keep-data`: odstraní sdílené soubory správované agentmemory, přičemž zachová validovaný kontejner, jeho datový mount a záznam životního cyklu potřebný k jejich obnovení. Destruktivní smazání dat Dockeru je záměrně ponecháno na operátorovi po zálohování. CLI také odmítá přijmout nebo signalizovat držitele portů Docker nebo VM (Docker backend, vpnkit, colima) jako nativní engine, pokud není předán `--force`. Výše uvedené manuální čištění je jen pro případ po havárii, kdy nezůstal žádný pidfile.
+
+### Konfigurační soubor
+
+Dejte runtime konfiguraci agentmemory do `~/.agentmemory/.env`, místo exportování proměnných v každém shellu. Pokud viewer zobrazí instalační nápovědu jako `export ANTHROPIC_API_KEY=...`, zkopírujte ji do tohoto souboru jako `ANTHROPIC_API_KEY=...` bez prefixu `export`, pak agentmemory restartujte.
+
+Proměnné prostředí procesu stále fungují a mají přednost před hodnotami v souboru.
+
+Na Windows žije stejný soubor na `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Pro test s předplatným Claude Code Pro/Max místo API klíče se přihlaste explicitně:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Komprese pozorování psaná LLM vyžaduje obě řádky: přístup k poskytovateli LLM (včetně tohoto explicitního záložního řešení přes předplatné) a `AGENTMEMORY_AUTO_COMPRESS=true`. Samotný poskytovatel nechá na místě výchozí syntetickou cestu komprese.
+
+Konsolidace (uzly grafu, lessons, crystals) je ve výchozím stavu zapnutá, kdykoli je nakonfigurován poskytovatel LLM. Explicitně se z ní odhlaste pomocí `CONSOLIDATION_ENABLED=false`, pokud chcete provoz bez LLM. Extrakce grafu je samostatný příznak:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Proměnné prostředí
+
+Vytvořte `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpointů na portu `3111`. REST API se ve výchozím stavu váže na `127.0.0.1`. Chráněné endpointy vyžadují `Authorization: Bearer `, a endpointy pro mesh sync vyžadují explicitně nastavené `AGENTMEMORY_SECRET` na obou stranách.
+
+**Autentizace je ve výchozím stavu zapnutá.** Když `AGENTMEMORY_SECRET` není nastaveno (v shellu ani v `~/.agentmemory/.env`), server při prvním startu vygeneruje náhodný secret a uloží ho do `~/.agentmemory/secret` s režimem `0600`. Každý zabalený klient ho odtud čte, když mluví s lokálním serverem: CLI, viewer, hooks pod `plugin/scripts`, server MCP a shim `@agentmemory/mcp`, konfigurace zapsané příkazem `agentmemory connect` a zabalené integrace OpenCode, Pi, OpenClaw, Hermes a filesystem-watcher. Uložený secret se posílá jen na loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Explicitní `AGENTMEMORY_SECRET` má vždy přednost, a vzdálení klienti ho stejně potřebují nastavený. Docker a entrypointy v `deploy/` už svůj vlastní secret generují a exportují. Pro manuální volání API:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Pravidla požadavků pro zápisy.** Požadavky `POST`, `PUT`, `PATCH` a `DELETE` na REST API a viewer musí poslat `Content-Type: application/json` (parametr `charset` je v pořádku), kdykoli nesou tělo, a hlavička `Origin`, pokud je přítomná, musí být loopback origin pro nakonfigurovaný port REST nebo vieweru, nebo musí být uvedena v `VIEWER_ALLOWED_ORIGINS` (odděleno čárkami, např. `https://memory.example.com`). Klienty, které žádnou hlavičku `Origin` neposílají (CLI, hooks, MCP, curl, server-server), se to nijak nedotýká. Viewer navíc akceptuje svůj vlastní origin.
+
+**Cesty k souborům.** Endpointy, které čtou nebo zapisují soubory (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), přijímají jen cesty pod `~/.agentmemory`, adresářem dat instance, nebo adresářem uvedeným v `AGENTMEMORY_IMPORT_ROOT` (víc jich oddělte pomocí `:`, na Windows pomocí `;`). `/replay/import-jsonl` navíc přijímá svou výchozí `~/.claude/projects`. `/obsidian/export` zůstává uvnitř `AGENTMEMORY_EXPORT_ROOT` a `/migrate` uvnitř `~/.agentmemory`. Symlinky se vyřeší před každou kontrolou.
+
+**Odstraňování secrets.** API klíče, bearer tokeny, bloky privátních klíčů PEM a přihlašovací údaje vložené v URL (`scheme://user:password@host`) se před uložením textu odstraní, na každé cestě zápisu: pozorování, remember, evolve, slots, lessons, actions, sketches, signály, checkpoints, importy, jsonl replay, mesh sync, sdílení s týmem, výstup komprese a shrnutí, crystals a uzly grafu.
+
+
+Klíčové endpointy
+
+| Metoda | Cesta | Popis |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | kontrola zdraví (vždy veřejná) |
+| `GET` | `/agentmemory/status` | co je špatně a jak to opravit (HTML pro prohlížeče, jinak JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | vše, co viewer zobrazuje, v jedné odpovědi |
+| `POST` | `/agentmemory/session/start` | spustí session + vrátí kontext |
+| `POST` | `/agentmemory/session/end` | ukončí session |
+| `POST` | `/agentmemory/observe` | zachytí pozorování (viz doručení zachycení níže) |
+| `GET` | `/agentmemory/capture` | inbox zachycení, dead letters a offline spool |
+| `POST` | `/agentmemory/capture/retry` | zopakuje zachycení v dead letters |
+| `POST` | `/agentmemory/capture/drain` | hned odešle lokální offline spool |
+| `POST` | `/agentmemory/smart-search` | hybridní vyhledávání |
+| `POST` | `/agentmemory/context` | vygeneruje kontext |
+| `POST` | `/agentmemory/remember` | uloží do dlouhodobé paměti |
+| `POST` | `/agentmemory/forget` | smaže pozorování |
+| `POST` | `/agentmemory/enrich` | kontext souboru + paměti + bugy |
+| `GET` | `/agentmemory/profile` | profil projektu |
+| `GET` | `/agentmemory/export` | exportuje všechna data |
+| `POST` | `/agentmemory/import` | import z JSON |
+| `POST` | `/agentmemory/graph/query` | dotaz na znalostní graf |
+| `POST` | `/agentmemory/graph/compact` | zmenší nadměrnou provenienci grafu |
+| `POST` | `/agentmemory/team/share` | sdílí s týmem |
+| `GET` | `/agentmemory/audit` | audit trail |
+
+Úplný seznam endpointů: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Doručení zachycení.** Hooks poslají každé pozorování jednou na `POST /agentmemory/observe` s `eventId`. Je to vlastní id hostitele pro to volání, pokud ho payload má (například `tool_use_id` z Claude Code), jinak hash session, typu hooku, názvu nástroje, vstupu, výstupu a timestampu hostitele. Server zapíše událost do inboxu zachycení ve state store, uloží pozorování, pak odstraní položku z inboxu. Status kód říká, co se stalo:
+
+| Status | pole `status` | Význam |
+|---|---|---|
+| `201` | `accepted` | uloženo. `observationId` je nové pozorování. |
+| `202` | `accepted` (`state: "retrying"`) | přijato, ale uložení selhalo. Server to zopakuje, i po restartu. |
+| `200` | `duplicate` | toto `eventId` už bylo přijato. `observationId` je existující pozorování; nic nového se neuloží. |
+| `400` / `422` | `rejected` | neplatný payload, nebo uložení definitivně selhalo (událost se uchová jako dead letter). |
+| `503` | `rejected` (`retryable: true`) | inbox je plný (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks událost uloží do spoolu a pošlou později. |
+
+Neúspěšné události se opakují každých `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) se zdvojnásobujícím se zpomalením, až do `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Události, které stále selhávají, zůstávají v inboxu jako dead letters, jsou uvedeny na `/agentmemory/status` a na stránce Health vieweru, a lze je zopakovat pomocí `POST /agentmemory/capture/retry` (`{"eventId": "..."}` nebo `{"all": true}`). Přijatá id událostí se pamatují po `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 hodin, nejvýš `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), takže hook přehraný po timeoutu nebo restartu se uloží jednou, zatímco dvě samostatná volání nástroje s vlastními id hostitele se uloží dvakrát, i když je jejich obsah identický. Když je pozorování smazáno (forget, smazání session, eviction, auto-forget nebo import, který nahrazuje úložiště), jeho událost se označí jako smazaná ještě před odstraněním pozorování, takže přehrání této události ve stejném okně se zodpoví jako duplikát a nic se neuloží. State store zapisuje na disk každé 2 sekundy, takže zodpovězená událost může ještě chvíli existovat jen v paměti. Aby to bylo ošetřeno, každá odpověď `2xx` nese i `bootId` serveru (nové při každém startu), `acceptedAt` a `durableAfterMs` (interval ukládání plus 1,5 s na souborovém úložišti, 1,5 s na redis, kde je trvalost na nastavení operátora). Hooks uchovávají událost v lokálním spoolu, dokud toto okno neuplyne, a smažou ji při pozdějším volání bez dalšího požadavku. Pokud se `bootId` do té doby změnil, server se restartoval, takže hook pošle událost znovu se stejným `eventId`; událost, která se na disk dostala, se neuloží dvakrát. Server takové události posílá i sám při startu a při každém intervalu opakování, takže restart nic neztratí, i když potom žádný hook neběží. Starší hooks ignorují extra pole a nové hooks proti staršímu serveru zahodí událost na `2xx` jako dřív.
+
+Když je server mimo provoz, neodpoví včas nebo vrátí 5xx, hook připojí pozorování do lokálního souboru spoolu, `/capture-spool/-.jsonl` (adresář přepište pomocí `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Soubor je privátní pro vašeho uživatele (režim 600), secrets jsou odstraněny stejně jako je odstraňuje server, pojme nejvýš `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) a zahazuje záznamy starší než `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Když je plný, nové záznamy se zahodí a započítají, a `/agentmemory/status` to nahlásí. Hook stále skončí s kódem 0 ve svém časovém limitu a nepřidá žádný požadavek, když je server zdravý. Spool se odešle při dalším startu a prvním hookem, který se znovu dostane k serveru, v procesu na pozadí, aby agent nečekal. Id událostí to dělají bezpečným: pozorování, které dorazilo před timeoutem, se neuloží dvakrát. `npx @agentmemory/agentmemory capture` zobrazí spool i inbox serveru, `--drain` hned odešle spool a `GET /agentmemory/capture` vrátí totéž jako JSON. Nastavte `AGENTMEMORY_CAPTURE_SPOOL=false`, abyste spool vypnuli.
+
+**Komprimace provenience grafu.** Každý uzel a hrana znalostního grafu si drží id posledních 32 pozorování, ze kterých vznikly. Úložiště zapsaná před tímto limitem mohou mít u „horkého" uzlu tisíce id, což zpomaluje vyhledávání v grafu a viewer, nebo to shazuje worker. agentmemory to opravuje samo: při prvním startu po upgradu na pozadí zmenší každý uzel, hranu, nahrazenou hranu (temporální historii grafu) a cachovaný snapshot na tento limit, v malých dávkách s pauzou mezi nimi, aby vyhledávání, zachycení i viewer fungovaly dál. Ukládá si svůj postup, pokračuje po restartu a po dokončení už nikdy znovu neběží. `/agentmemory/status` a stránka Health vieweru ji zobrazují jako čekající, běžící (s aktuálním scope a pozicí), hotovou nebo neúspěšnou. Nastavte `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`, abyste ji vypnuli.
+
+Pro manuální spuštění zavolejte `POST /agentmemory/graph/compact`. Prochází indexy názvů a klíčů hran místo výpisu každého uzlu a hrany, a je bezpečné ho spustit znovu. Když zmenší id, zapíše audit záznam `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Na velkém úložišti, nebo když volání vrátí 504, spusťte ho po dávkách. Pošlete `scope` (`nodes`, `edges` nebo `history`), `offset` a `limit`, pak volejte znovu s vráceným `nextOffset`, dokud není `null`. Udělejte to pro `nodes`, `edges` a `history`, a zakončete jedním voláním `{"scope":"snapshot"}`, protože dávkový běh se cachovaného snapshotu nedotýká.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Požadavky:** Node.js >= 20 s npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 nebo Docker. Automatická instalace enginu na macOS/Linuxu navíc vyžaduje `curl`, POSIX `sh` a `tar`; nativní Windows používá manuálně pinned `iii.exe`, WSL2 nebo Docker Desktop.
+
+
+
+ Din kodeagent husker alt. Ikke mere genforklaring.
+ Built on iii engine
+
+ Persistent hukommelse til Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode og enhver MCP-klient.
+
+
+---
+
+## Installation
+
+Krav:
+
+- Node.js 20 eller nyere med npm og npx (`node -v`, `npm -v` og `npx -v`).
+- Automatisk installation af iii-engine på macOS/Linux kræver også `curl`, en POSIX `sh` og `tar`. Minimale images som `node:20-slim` indeholder dem muligvis ikke.
+- Native Windows kræver, at den fastlåste iii-engine v0.22.1 `iii.exe` installeres manuelt. WSL2 eller Docker Desktop er de andre understøttede veje.
+
+Den kanoniske kommando til en ny installation:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Den første kørsel er en interaktiv opsætning: du vælger de agenter, der skal forbindes (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), vælger en LLM-udbyder eller fortsætter uden nøgle, og den udfylder konfigurationen, starter hukommelsesserveren og dens fastlåste iii-engine, og tilbyder at installere globalt, så den rene `agentmemory`-kommando fungerer alle steder bagefter. `-y` accepterer npx's pakke-prompt, og `@latest` undgår en forældet, cachet udgivelse. En udbyder gør LLM-funktioner tilgængelige, men LLM-skrevet observationskomprimering starter kun, når `AGENTMEMORY_AUTO_COMPRESS=true` også er sat.
+
+Nøgleløs tilstand deaktiverer vektor-embeddings. `memory_recall` (stien `mem::search`) bruger BM25, mens `memory_smart_search` også kan kombinere strukturelle graf-match, når der allerede findes graf-data. For gratis semantisk recall på enheden, sæt `EMBEDDING_PROVIDER=local` i `~/.agentmemory/.env` og genstart. Den første embedding-forespørgsel downloader `Xenova/all-MiniLM-L6-v2`; herefter køres inferens lokalt.
+
+Den lokale runtime bruger fire porte: `3111` til REST/MCP HTTP, `3112` til iii-streams, `3113` til viewer, og `49134` til iii-workerens WebSocket. Persistent iii-tilstand ligger i `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, og `%APPDATA%\agentmemory` på Windows. Brug `--data-dir ` eller `AGENTMEMORY_DATA_DIR` til at ændre det, og genbrug samme værdi ved hver genstart. Af bagudkompatibilitet har en eksisterende `./data/state_store.db` eller `./data/iii-config.yaml` forrang over platformens standardplacering for instans 0; et eksplicit flag eller en miljøvariabel vinder stadig.
+
+Bevis derefter, at recall virker, og giv din agent dens skills:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Nøgleordssøgningerne bør give hit i standard nøgleløs tilstand via BM25. Demoens `database performance optimization`-forespørgsel er bevidst semantisk og kan give nul resultater, før en embedding-udbyder er konfigureret.
+
+Foretrækker du, at en kodeagent gør det hele selv? Giv den en enkelt instruktion:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Forbind flere agenter når som helst med `agentmemory connect ` — 20 adaptere er listet under [Works with every agent](#works-with-every-agent). Fuld kommandoreference under [Quick Start](#quick-start).
+
+
+Windows
+
+Den hurtige vej er WSL2. Opsætning af native Windows-engine kræver, at den fastlåste v0.22.1-ZIP downloades, og at `iii.exe` udpakkes manuelt; CLI'en udpakker ikke automatisk. Docker Desktop understøttes også. Se [Windows-noterne](#windows) for trin-for-trin-vejledningen.
+
+
+
+
+Global installation / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+npx-kommandoen ovenfor er stadig den kanoniske vej til en ny installation og undgår problemer med rettigheder til global-prefix.
+
+
+
+
+npx leverer en gammel version
+
+npx cacher pr. version. Tving den nyeste med `npx -y @agentmemory/agentmemory@latest`, eller ryd cachen én gang med `rm -rf ~/.npm/_npx` (macOS/Linux; på Windows slettes `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Kører allerede din egen iii-engine
+
+agentmemory fastlåser iii-engine v0.22.1 og tilkobler sig ikke en anden version (workeren kan ikke tale en anden engines protokol). Stop den anden engine, og kør derefter `npx -y @agentmemory/agentmemory@latest`. Den installerer og kører den fastlåste v0.22.1 i `~/.agentmemory/bin` og lader din egen `iii` være uberørt.
+
+
+
+---
+
+
+
+agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST API. Alle agenter deler den samme hukommelsesserver.
+
+
+ Fungerer med enhver agent, der taler MCP eller HTTP. Én server — hukommelse delt mellem dem alle.
+
+
+---
+
+Du forklarer den samme arkitektur i hver session. Du genopdager de samme fejl. Du genunderviser i de samme præferencer. Indbygget hukommelse (CLAUDE.md, .cursorrules) topper ved 200 linjer og bliver forældet. agentmemory løser dette. Den indsamler stille og roligt, hvad din agent gør, komprimerer det til søgbar hukommelse og injicerer den rette kontekst, når den næste session starter. Én kommando. Fungerer tværs af agenter.
+
+**Hvad der ændrer sig:** I session 1 sætter du JWT-autentificering op. I session 2 beder du om rate limiting. Agenten ved allerede, at din auth bruger jose-middleware i `src/middleware/auth.ts`, at dine tests dækker token-validering, og at du valgte jose frem for jsonwebtoken af hensyn til Edge-kompatibilitet — uden genforklaring og uden copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Som standard lagrer agentmemory iii-engine-tilstand uden for det repository, du starter den fra: `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, og `%APPDATA%\agentmemory` på Windows. En eksisterende, forældet `./data/state_store.db` eller `./data/iii-config.yaml` genbruges til instans 0 før platformens standard. For at vælge en placering eksplicit, angiv `--data-dir ` eller sæt `AGENTMEMORY_DATA_DIR`; begge eksplicitte indstillinger har forrang over den forældede opdagelse:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native og Docker-opstarter bruger samme opløste hostmappe; Docker bind-mounter den på `/data`. `--instance 1` tilføjer `instance-1` til den opløste mappe og vælger den separate standard-portkvartet `3211/3212/3213/49234`.
+
+Seneste udgivelsesnoter: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Retrieval-nøjagtighed
+
+**coding-agent-life-v1** (internt korpus, reproducerbart i sandbox)
+
+| Adapter | P@5 | R@5 | Top-5-hitrate | p50-latens |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep-baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% top-5-hitrate ved **P@5-matematikkens loft** for dette korpus (0.240, se scorecard). Hybrid finder hver gylden session; grep misser 1 af 2 gyldne i den multi-session-temporale forespørgsel. Forbedringen er **recall + temporal**, ikke samlet precision. Dette benchmark er lille og har få gyldne eksempler; det større LongMemEval-S nedenfor differentierer bedre. Fuld opdeling pr. type + korrektionsnote: [`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 spørgsmål)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Kun BM25-fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+> Embedding-model: `all-MiniLM-L6-v2` (lokal, gratis, ingen API-nøgle). Fulde rapporter: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Konkurrentsammenligning: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), der dækker agentmemory vs. mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Reproducér lokalt:** [`eval/README.md`](../eval/README.md), en adapter-plugbar harness til LongMemEval `_s` (offentligt 500-spørgsmåls-sæt) + `coding-agent-life-v1` (internt korpus med 15 sessioner). Grep-, vektor- og agentmemory-adaptere scorer side om side, NDJSON-output, publicerede scorecards lander i [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Fungerer godt sammen med [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) og [Graphify](https://github.com/safishamsi/graphify).** Code-graph-indeksering, multi-agent build-pipelines og bredere videngrafer tværs af dokumenter/PDF'er/billeder/videoer. agentmemory husker arbejdet; disse tre projekter oplyser resten af kontekstlaget. Opskrifter + spørgsmålsrouting-tabel: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+Benchmark-note: kun agentmemorys R@5 er vores eget målte resultat (LongMemEval-S, reproducerbart fra benchmark/COMPARISON.md). Tallene for mem0 og Letta er deres publicerede LoCoMo-tal (et andet datasæt); tallene for MemPalace, supermemory, TencentDB (PersonaMem) og oracleagentmemory er leverandørens selvrapporterede påstande, som vi ikke selv har reproduceret (oracleagentmemorys kørsel brugte GPT-5.5 mod en Oracle AI Database). Vist side om side kun som et groft overblik, ikke en direkte sammenligning på identiske data. Stjerneantal er cirka og ændrer sig over tid.
+
+**Nyere aktører**, som er værd at kende, sammenlignet i detaljer i [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| System | ⭐ | Vinkel |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporal videngraf; stærkeste publicerede resultater for temporale forespørgsler (LongMemEval 63.8%), men grafen bygges asynkront, så nye fakta kan halte |
+| Cognee | 30K | Dokument-til-videngraf-indlæsning, kun Python, bygget til struktureret entitetsudtrækning snarere end sessionsindsamling |
+
+Ingen af disse indsamler automatisk fra kodeagent-hooks, leverer en local-first viewer eller kan køre uden nøgle — den kombination er agentmemory bygget omkring.
+
+---
+
+
+
+Kompatibilitet: denne udgivelse målretter `iii-sdk` 0.22.1 og fastlåser iii-engine v0.22.1.
+
+### Prøv det på 30 sekunder
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` seeder 3 realistiske sessioner (JWT-auth, N+1-forespørgselsfix, rate limiting) og kører søgninger mod dem. Nøgleløse installationer deaktiverer vektorer, så nøgleordsforespørgslerne via `mem::search` bør give hit via BM25, mens `database performance optimization` kan give nul resultater. `smart-search` kan desuden returnere strukturelle graf-match, når der findes graf-data. For at få den semantiske forespørgsel til at finde N+1-fixet via vektorer, sæt `EMBEDDING_PROVIDER=local`, genstart, og lad den første modeldownload færdiggøre.
+
+Åbn `http://localhost:3113` for at se hukommelsen bygges live.
+
+### Validér en frisk installation og persistens ved genstart
+
+Mens serveren kører, validér REST, health, viewer og den iii-baserede runtime-status:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Opstartens ready-panel tager højde for alle fire porte: REST/MCP HTTP på 3111, iii-streams på 3112, viewer på 3113, og iii-workerens WebSocket på 49134. `status` bekræfter agentmemorys health og den aktive provider-/embedding-tilstand. Gem en probe, og bekræft at den er søgbar:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Kør derefter `npx -y @agentmemory/agentmemory@latest stop`, start den kanoniske kommando igen i Terminal 1, vent på `/agentmemory/livez`, og gentag søgningen. Proben skal stadig returneres. Hvis du valgte en brugerdefineret `--data-dir`, så angiv samme mappe ved genstarten.
+
+### Daglige kommandoer
+
+Installation og opsætning findes under [Install](#install) ovenfor (den første kørsel guider dig igennem det). Til dagligt brug:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Session-genafspilning
+
+Hver session, agentmemory optager, kan genafspilles. Åbn viewer, vælg fanen **Replay**, og spol gennem tidslinjen: prompts, tool calls, tool-resultater og svar vises som enkeltstående events med afspil/pause, hastighedskontrol (0.5x til 4x) og tastaturgenveje (space til at skifte afspil/pause, piletaster til at trinvist bevæge dig).
+
+For at importere ældre Claude Code JSONL-transskripter:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Importerede sessioner vises i Replay-vælgeren sammen med de native. Under motorhjelmen router hver post gennem iii-funktionerne `mem::replay::load`, `mem::replay::sessions` og `mem::replay::import-jsonl`, uden side-channel-servere. Hvert importeret transskript indekseres til søgning, stemples med oprindelseskanalen `import`, og udvindes for en session-crystal og lessons.
+
+> **Vigtigt, hvis du afhænger af `import-jsonl` som din primære indsamlingsvej:** Claude Codes `cleanupPeriodDays` (i `~/.claude/settings.json`, standard **30**) sletter automatisk JSONL-transskripter, der er ældre end dette vindue, fra `~/.claude/projects/`. Hvis du installerer agentmemory helt nyt mod en måneder gammel Claude Code-historik, er alt ældre end 30 dage allerede væk, før den første import. Kør enten `import-jsonl` via en cron, hæv `cleanupPeriodDays` til noget højere, eller forbind auto-capture-hooks (standard-installationsvejen for pluginet), så hver tur lander i agentmemory, mens sessionen er aktiv, og JSONL-ryddet ikke længere betyder noget.
+
+### Opgradering / vedligeholdelse
+
+Brug vedligeholdelseskommandoen, når du bevidst vil opdatere din lokale runtime:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Advarsel: denne kommando ændrer det nuværende workspace/runtime. Den kan opdatere JavaScript-afhængigheder og hente det fastlåste `iiidev/iii:0.22.1` Docker-image. Den installerer aldrig en ikke-fastlåst eller nyere iii-engine.
+
+Implementeringsdetaljer findes i `src/cli.ts` (se `runUpgrade` omkring regionen `src/cli.ts:544-595`).
+
+### Claude Code (én blok, indsæt den)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code uden plugin-installation (MCP-standalone-vej)
+
+Hvis du forbinder agentmemorys MCP-server via `~/.claude.json` direkte i stedet for at bruge `/plugin install`, opløser Claude Code aldrig `${CLAUDE_PLUGIN_ROOT}`, og du skal pege hook-scripts på absolutte paths i `~/.claude/settings.json`. Disse paths indeholder typisk agentmemory-versionen (f.eks. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), så den næste opgradering stille og roligt bryder hver hook.
+
+Løsning:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Dette sammenføjer de samme hook-kommandoer i `~/.claude/settings.json` med absolutte paths, der peger på den medfølgende `plugin/`-mappe i den aktuelt installerede `@agentmemory/agentmemory`-pakke. Kør kommandoen igen efter opgradering af agentmemory for at opdatere paths. Brugerens egne indgange i samme fil bevares; kun tidligere agentmemory-indgange udskiftes. At bruge `/plugin install`-vejen er stadig den anbefalede metode.
+Til eksterne eller beskyttede deployments, start Claude Code med `AGENTMEMORY_URL` og `AGENTMEMORY_SECRET` sat. Pluginet sender begge værdier videre til sin medfølgende MCP-server; når `AGENTMEMORY_URL` er tom, bruger MCP-shimmen `http://localhost:3111`.
+
+### Codex CLI (Codex-plugin-platform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex-pluginet leveres fra samme `plugin/`-mappe som Claude Code-pluginet. Det registrerer:
+
+- En medfølgende stdio MCP-bridge til den kørende daemon, uden npm-download eller fallback-lager. Se [den lokale Codex-guide](../docs/plugins/codex-local.md) for at teste en build, der endnu ikke er udgivet.
+- 6 livscyklus-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 kaldbare skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, samt 8 referenceskills, som agenten indlæser efter behov (hukommelsesdisciplin, MCP-værktøjer, REST API, konfiguration, agenter, hooks, arkitektur og guiden til at skrive skills)
+
+Codex' hook-motor injicerer `CLAUDE_PLUGIN_ROOT` i hook-underprocesser (jf. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), så de samme hook-scripts virker på begge hosts uden duplikering. Subagent-/SessionEnd-/Notification-/TaskCompleted-/PostToolUseFailure-events er kun til Claude Code og registreres ikke for Codex.
+
+#### Codex-hooks: tillid og kompatibilitet
+
+Native plugin-hook-afsendelse er verificeret med Codex CLI 0.150.1. Stol på plugin-hooks, før du forventer capture. Desktop-opførslen afhænger af dens medfølgende runtime; kontrollér `/hooks`, og bekræft en fanget hændelse, før du aktiverer en løsning.
+
+Hvis din host kræver globale hooks, så spejl kommandoerne ind i `~/.codex/hooks.json`. Når MCP allerede er forbundet, skal den nuværende adapter bruge `--force` for at nå hook-installationen:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Dette sammenføjer globale hooks og omskriver agentmemory MCP-indgangen, og bevarer ikke-relaterede indgange. Gennemgå eventuelle tilpassede agentmemory endpoint-indstillinger, før du bruger `--force`. Kør igen efter opgradering for at opdatere scriptpaths. Aktivér enten native plugin-hooks eller globale kopier for at undgå duplikeret capture.
+
+### GitHub Copilot CLI
+
+Til VS Code agent-tilstand, brug [Copilot MCP- og auto-capture-guiden](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-adapteren konfigurerer ikke VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` sammenføjer `mcpServers.agentmemory` ind i `~/.copilot/mcp-config.json` (eller `$COPILOT_HOME/mcp-config.json`, når `COPILOT_HOME` er sat) og bevarer eksisterende servere. På native Windows er dette den eneste automatiserede `connect`-adapter; konfigurér alle andre native Windows-agenter manuelt. WSL `connect` understøttes kun, når målagenten er installeret i samme WSL-miljø. Copilot opdager MCP-serveren ved næste opstart eller efter `/mcp`. Installér også pluginet, når du vil have den fulde hook-/skill-oplevelse.
+
+
+OpenClaw (indsæt denne prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Fuld guide: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (indsæt denne prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Fuld guide: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Andre agenter
+
+Start hukommelsesserveren: `npx -y @agentmemory/agentmemory@latest`
+
+#### Native skills via `npx skills add` (50+ agenter)
+
+agentmemory leveres med 17 skills i Claude-Code-stilens `/SKILL.md`-format: 9 kaldbare action-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) og 8 referenceskills, som agenten indlæser efter behov (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referenceskillene indeholder datatabeller genereret fra kildekoden, så de aldrig driver ud af kurs. [`skills`](https://npmjs.com/package/skills)-CLI'en fra vercel-labs installerer dem automatisk i den kaldende agents native skill-mappe på tværs af 50+ agenter (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf og flere):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Dette er et **supplement** til `agentmemory connect `:
+
+- `agentmemory connect ` skriver MCP-serverkonfigurationen, så værktøjerne er tilgængelige.
+- `npx skills add rohitg00/agentmemory` installerer skillene, så agenten ved, hvornår den skal kalde dem.
+
+For de få agenter, som skills-CLI'en endnu ikke dækker (Zed v1.3.x og tidligere), skal du selv placere de 17 SKILL.md-filer i agentens native skill-mappe; det samme format fungerer alle steder.
+
+#### Standard MCP-blok
+
+agentmemory-indgangen er den **samme MCP-serverblok** på alle hosts, der bruger `mcpServers`-formen (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Sammenføj denne indgang i det eksisterende `mcpServers`-objekt** i hostens konfigurationsfil; udskift ikke filen. Hvis filen allerede har andre servere, så tilføj `agentmemory` ved siden af dem som endnu en nøgle inde i `mcpServers`. Hvis `mcpServers` helt mangler, så indsæt blokken inden i `{ "mcpServers": { ... } }`. `${VAR}`-pladsholderne overtager `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` fra shellen, når MCP-serveren starter; ikke-satte variabler giver tomme strenge, og shimmen falder tilbage til `http://localhost:3111`. Én forbundet indgang dækker både lokale og eksterne (k8s/reverse-proxy'ede) deployments.
+
+| Agent | Konfigurationsfil | Noter |
+|---|---|---|
+| **Cursor (kun MCP)** | `~/.cursor/mcp.json` | Sammenføj i `mcpServers`, eller brug `agentmemory connect cursor`. Et one-click deeplink er også tilgængeligt på hjemmesiden. |
+| **Cursor (fuldt plugin)** | `.cursor-plugin/` | Cursor Marketplace-listing (indsendelse under review) eller Cursor Settings → Plugins → lokal checkout. Registrerer 7 auto-capture-hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + MCP-serveren, med `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` administreret i Cursors plugin-dashboard. Fungerer i Cursor IDE og `cursor-agent`-CLI'en; CLI print-mode-prompts efterudfyldes fra sessionstransskriptet ved sessionens afslutning. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Sammenføj i `mcpServers`. Genstart Claude Desktop efter redigering. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP-indstillinger (Settings UI → MCP Servers → Edit) | Samme `mcpServers`-blok. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` sammenføjer MCP-indgangen; `--with-hooks` tilføjer seks native auto-capture-hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) med Devins små bogstaver-tool-matchers. Bekræft med `devin mcp list` og `/hooks` inde i devin. |
+| **Devin CLI (fuldt plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` fra en checkout registrerer alle 17 skills som `/agentmemory:`-slash-kommandoer plus MCP-serveren. Devins plugin-hooks kan ikke udløse `SessionStart`/`SessionEnd`, så kombinér det med `connect devin --with-hooks` for fuld sessionsindsamling. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Tilføj en custom MCP (STDIO): kommando `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL`, der peger på en netværkstilgængelig agentmemory-deployment, plus `AGENTMEMORY_SECRET` (cloud-sessioner kan ikke nå localhost — se [`deploy/`](../deploy/)). Gem secreten i Devin Secrets, og brug derefter "Test listing tools" til at bekræfte, at alle 54 værktøjer vises. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (sammenføjer automatisk). |
+| **GitHub Copilot CLI (kun MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` sammenføjer `mcpServers.agentmemory`; Copilot opdager den ved næste opstart eller `/mcp`. |
+| **GitHub Copilot CLI (fuldt plugin)** | Copilot plugin-installation | `copilot plugin install rohitg00/agentmemory:plugin` for pluginet fra GitHub-undermappen. |
+| **OpenClaw** | OpenClaw MCP-konfiguration | Samme `mcpServers`-blok. Dybere integration: `openclaw plugins install ./integrations/openclaw` tager OpenClaws memory-slot (skifter automatisk fra `memory-core`); sæt `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, ellers blokeres tur-indsamlingen stille og roligt. Se [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (kun MCP)** | `.codex/config.toml` | TOML-form: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, eller tilføj `[mcp_servers.agentmemory]` manuelt. |
+| **Codex CLI (fuldt plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory`, derefter `codex plugin add agentmemory@agentmemory`. Registrerer MCP + 6 livscyklus-hooks + 17 skills. Stol på hooks, og bekræft capture på din host; se [Codex-opsætning og validering](../docs/plugins/codex-local.md). |
+| **OpenCode (kun MCP)** | `opencode.json` | Anden form: en `mcp`-nøgle på topniveau, kommando som array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (fuldt plugin)** | `plugin/opencode/` | 22 auto-capture-hooks, der dækker sessionslivscyklus, beskeder, tools og fejl. Projekttilskrivning er pr. session, så én OpenCode-proces, der spænder over flere repositories, journalfører hver session under sit eget projekt. To slash-kommandoer (`/recall`, `/remember`). Kopiér `plugin/opencode/` ind i dit OpenCode-workspace, og tilføj plugin-indgangen til `opencode.json`. Se [`plugin/opencode/README.md`](../plugin/opencode/README.md) for den fulde hook-tabel + gap-analyse. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installerer den medfølgende extension i pi's auto-discovery-mappe (recall ved agentstart, capture ved agentafslutning, tools `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` i en kørende pi opdager den. [`integrations/pi`](../integrations/pi/) er også en pi-pakke (`pi install ./integrations/pi` fra en checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` giver den 6-hook hukommelsesprovider (prefetch, turindsamling, sessionsafslutning, pre-compress, MEMORY.md-spejling, system-prompt-blok). Validér med `hermes plugins doctor` og `hermes memory status`. Se [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` skriver standard-`mcpServers`-blokken. Hook-payloaden er felt-kompatibel med Claude Code, så de eksisterende 12-hook-scripts fungerer uden ændringer; forbind dem via `hooks`-sektionen i samme `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installerer MCP og capture-hooks i den delte tilpasningsmappe. Se [Antigravity-opsætning og begrænsninger](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` bruger samme MCP- og hook-konfiguration som de nuværende IDE-versioner. Eksisterende installationer bør opdateres med `--force`; se [opgraderingsnoterne](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` skriver konfigurationen på brugerniveau. Workspace-overrides placeres i `.kiro/settings/mcp.json` ved siden af din kode. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` skriver standard-`mcpServers`-blokken. Warp opdager også automatisk skills fra `.claude/skills/`; når Claude Code-pluginet er installeret, vises de 8 agentmemory-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) nativt i Warps slash-kommando-palette. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` skriver standard-`mcpServers`-blokken. Brugere af VS Code-extensionen: indsæt samme blok via Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (foretrukket) eller `config.json` (legacy) | `agentmemory connect continue` opretter `config.yaml` fra bunden, når ingen af dem findes, eller ændrer en eksisterende `config.json`. **Hvis du allerede har `config.yaml`**, printer adapteren den nøjagtige blok, du skal indsætte under `mcpServers:`; den omskriver ikke stille og roligt din yaml, fordi sikker bevarelse af kommentarer og anchors kræver en YAML-parser, som pakken ikke leverer. Continue bruger array-form (ikke objekt) til `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` skriver under `context_servers` (Zeds nøgle, IKKE `mcpServers`). Eksterne MCP-servere kan i stedet forbindes via `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` skriver standard-`mcpServers`-blokken. Projekt-scopede overrides placeres i `/.factory/mcp.json`. Angiv `--with-hooks` for native auto-capture. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` tilføjer en `@deepseek-ai/dsh-mcp-client`-række til det home-niveau patch-lag, som hver Harness-profil indlæser; tools registreres som `mcp__agentmemory__*`. Angiv `--with-hooks` for også at forbinde auto-capture: de medfølgende Claude Code-hook-scripts køres gennem Harness' egen `@deepseek-ai/dsh-hooks-claude-code`-bridge (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via et manifest skrevet til `$DSH_HOME/agentmemory.hooks.json`. Standard er `~/.dsh`, når `DSH_HOME` ikke er sat. |
+| **Goose** | Goose MCP-indstillings-UI | Samme `mcpServers`-blok; brug `goose configure` → Add Extension → MCP. Direkte YAML-redigering i `~/.config/goose/config.yaml` understøttes, men skemaet bruger `extensions:` + `cmd` (ikke `mcpServers:` + `command`). |
+| **Aider** | n/a | Tal direkte med REST API'et: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Enhver agent (32+)** | n/a | `npx skillkit install agentmemory` opdager automatisk hosten og sammenføjer. |
+
+**Sandboxede MCP-klienter** (Flatpak/Snap/restriktive containere), der ikke kan nå hostens `localhost`: sæt også `"AGENTMEMORY_FORCE_PROXY": "1"` i `env`-blokken, og peg `AGENTMEMORY_URL` på en rute, sandboxen faktisk kan nå (f.eks. din LAN-IP).
+
+### Programmatisk adgang (Python / Rust / Node)
+
+agentmemory registrerer sine kerneoperationer som iii-funktioner (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Ethvert sprog med en iii SDK kan kalde dem direkte over `ws://localhost:49134`, uden en separat REST-klient pr. sprog.
+
+```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"},
+})
+```
+
+Gennemarbejdet eksempel: [`examples/python/`](../examples/python/) (quickstart + observations-/recall-flow). REST på `:3111` er stadig tilgængeligt for hosts uden en iii-runtime.
+
+### Fra kildekode
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Dette starter agentmemory med en lokal `iii-engine`, hvis den fastlåste binary allerede er installeret, eller bruger Docker Compose, når det er valgt. REST, streams og viewer binder til `127.0.0.1` som standard. Den automatiske binary-vej på macOS/Linux kræver `curl`, en POSIX `sh` og `tar`.
+
+Installér `iii-engine` manuelt. **agentmemory fastlåser i øjeblikket `iii-engine` til `v0.22.1`**, samme udgivelse som dens `iii-sdk`-afhængighed; workeren taler denne engines wire-protokol, og 0.20.0 omorganiserede SDK-overfladen, så de to følges i agentmemorys udgivelser. Overskriv med `AGENTMEMORY_III_VERSION=`, hvis du kører din egen engine og ved, at den passer.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** erstat `aarch64-apple-darwin` med `x86_64-apple-darwin`
+- **Linux x64:** erstat med `x86_64-unknown-linux-gnu`
+- **Linux arm64:** erstat med `aarch64-unknown-linux-gnu`
+- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` fra [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1), og udpak `iii.exe` til `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Hvert arkiv har en tilhørende `.sha256`-fil på udgivelsessiden; når du skifter platform, så brug den fils hash i checket ovenfor (på Windows: `Get-FileHash`). Den automatiske installer i `npx @agentmemory/agentmemory` fastlåser disse hashes og afviser et arkiv, der ikke matcher.
+
+Eller brug Docker (den medfølgende `docker-compose.yml` henter `iiidev/iii:0.22.1`). Fuld dokumentation: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory kører på Windows 10/11, men Node.js-pakken alene er ikke nok; du skal også have den fastlåste iii-engine v0.22.1-runtime som en baggrundsproces. CLI'en udpakker ikke automatisk Windows-ZIP'en, så native Windows-brugere skal installere `iii.exe` manuelt, bruge WSL2 eller vælge Docker Desktop.
+
+Automatiseret MCP-forbindelse på native Windows understøtter kun `agentmemory connect copilot-cli`. For Claude Code, Codex, Cursor og alle andre native Windows-agenter skal du kopiere den manuelle MCP-blok fra [Other agents](#other-agents) ind i den agents Windows-konfiguration. At køre `connect` i WSL er kun hensigtsmæssigt, når målagenten også er installeret i samme WSL-miljø; det redigerer ikke en Windows-host-agents konfiguration.
+
+**Mulighed A: prækompileret Windows-binary (anbefalet)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Mulighed B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Mulighed C: kun standalone MCP (ingen engine).** Hvis du kun har brug for MCP-værktøjerne til din agent og ikke behøver REST API, viewer eller cron-jobs, kan du springe engine'en helt over:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostik til Windows:** hvis `npx -y @agentmemory/agentmemory@latest` fejler, så kør den igen med `--verbose` for at se den faktiske engine-stderr. Almindelige fejltilstande:
+
+| Symptom | Løsning |
+|---|---|
+| `The engine process started but the REST API never responded.` | Bekræft at alle fire afledte porte er frie, verificér at den fastlåste `iii.exe` forblev i live, og kør derefter igen med `--verbose`, og undersøg den fangede engine-stderr |
+| `Could not start iii-engine` | Hverken `iii.exe` eller Docker er installeret. Se mulighed A eller B ovenfor |
+| Portkonflikt | `netstat -ano \| findstr :3111` for at se, hvad der er bundet, og dræb det derefter, eller brug `--port ` |
+| Docker-fallback springes over, selv om Docker er installeret | Sørg for, at Docker Desktop faktisk kører (ikon i systembakken) |
+
+> Bemærk: iii-**engine** er en prækompileret binary, ikke en cargo crate, så prøv ikke at `cargo install` den. (iii-**SDK'erne** er publiceret på crates.io, npm og PyPI, men agentmemory har ikke brug for dem.) De understøttede installationsmetoder for engine er alle fastlåst til v0.22.1: den prækompilerede binary ovenfor, agentmemorys macOS/Linux-auto-installationsvej (`curl`, POSIX `sh` og `tar` er nødvendige), og Docker-imaget `iiidev/iii:0.22.1`. En ren upstream `install.sh | sh` installerer den nyeste engine, hvilket agentmemory ikke understøtter. Brug `npx -y @agentmemory/agentmemory@latest`; på macOS/Linux henter den den fastlåste engine ind i `~/.agentmemory/bin`.
+
+---
+
+
Deployment
+
+One-click-skabeloner til administrerede hosts. Hver enkelt leveres med en selvstændig Dockerfile, der henter `@agentmemory/agentmemory` fra npm og kopierer iii-engine-binaryen ind fra det officielle `iiidev/iii` Docker Hub-image; intet prækompileret agentmemory-image er nødvendigt. Persistent lagring monteres på `/data`; first-boot-entrypointet overskriver den npm-medfølgende iii-konfiguration (som binder `127.0.0.1`) med en deploy-tunet udgave, der binder `0.0.0.0` og bruger absolutte `/data`-paths, genererer HMAC-secreten, og frafalder derefter privilegier fra `root` til `node` via `gosu`, før den eksekverer agentmemory-CLI'en.
+
+
+
+
+
+
+Renders one-click-deploy-knap kræver `render.yaml` i repositoryets rod, som vi med vilje holder ren. Brug Render Blueprint-flowet, dokumenteret i [`deploy/render/`](.././deploy/render/README.md), til manuelt at pege på blueprintet i repositoryet.
+
+Fulde opsætningsdetaljer (HMAC-capture, SSH-tunnel til viewer, rotation, backup,
+minimumsomkostninger) findes i [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): én maskine med
+ `auto_stop_machines = "stop"`; billigst i tomgang.
+- [`deploy/railway`](.././deploy/railway/README.md): fast pris på Hobby-planen,
+ volume i dashboardet.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint-flow,
+ automatiske disk-snapshots på betalte planer.
+- [`deploy/coolify`](.././deploy/coolify/README.md): selvhostet på din
+ egen VPS via [Coolify](https://coolify.io/self-hosted); samme Docker
+ Compose-stack, du ejer hosten og dataene.
+
+Kun port `3111` eksponeres. Viewer på `3113` forbliver bundet til
+loopback inde i containeren; hver skabelons README dokumenterer
+SSH-tunnel-mønsteret for at nå den.
+
+---
+
+
+
+Hver kodeagent glemmer alt, når sessionen slutter, og hver ny session starter med, at du genforklarer din stack. agentmemory kører i baggrunden og fjerner dette trin.
+
+```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. indbygget agenthukommelse
+
+Hver AI-kodeagent leveres med indbygget hukommelse: Claude Code har `MEMORY.md`, Cursor har notepads, Cline har memory bank. Disse fungerer som gule post-it-sedler. agentmemory er den søgbare database bag post-it-sedlerne.
+
+| | Indbygget (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skala | 200-linjers-loft | Ubegrænset |
+| Søgning | Indlæser alt i konteksten | BM25 + vektor + graf (kun top-K) |
+| Tokenomkostning | 22K+ ved 240 observationer | ~1,900 tokens (92% mindre) |
+| Tværs af agenter | Filer pr. agent | MCP + REST (enhver agent) |
+| Koordinering | Ingen | Leases, signaler, actions, routines |
+| Observerbarhed | Læs filer manuelt | Realtids-viewer på :3113 |
+
+---
+
+
+
+### Hukommelsespipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-lags hukommelseskonsolidering
+
+Modelleret efter, hvordan menneskehjerner bearbejder hukommelse, inklusive søvnkonsolidering.
+
+| Lag | Hvad | Analogi |
+|------|------|---------|
+| **Arbejdshukommelse** | Rå observationer fra tool-brug | Korttidshukommelse |
+| **Episodisk** | Komprimerede sessionsopsummeringer | "Hvad der skete" |
+| **Semantisk** | Udtrukne fakta og mønstre | "Hvad jeg ved" |
+| **Procedurel** | Workflows og beslutningsmønstre | "Hvordan man gør det" |
+
+Hukommelser forfalder over tid (Ebbinghaus-kurven). Ofte tilgåede hukommelser styrkes. Forældede hukommelser smides automatisk ud. Modsætninger opdages og løses.
+
+### Hvad der indsamles
+
+| Hook | Indsamler |
+|------|----------|
+| `SessionStart` | Projektsti, session-ID |
+| `UserPromptSubmit` | Brugerprompts (privacy-filtreret) |
+| `PreToolUse` | Filtilgangsmønstre + beriget kontekst |
+| `PostToolUse` | Tool-navn, input, output |
+| `PostToolUseFailure` | Fejlkontekst |
+| `PreCompact` | Genindsætter hukommelse før compaction |
+| `SubagentStart/Stop` | Subagent-livscyklus |
+| `Stop` | Opsummering ved sessionsafslutning |
+| `SessionEnd` | Markør for afsluttet session |
+
+### Vigtigste funktioner
+
+| Funktion | Beskrivelse |
+|---|---|
+| **Automatisk indsamling** | Hver tool-brug registreres via hooks, ingen manuel indsats |
+| **Semantisk søgning** | BM25 + vektor + videngraf med RRF-fusion |
+| **Hukommelsesudvikling** | Versionering, overskrivning (supersession), relationsgrafer |
+| **Recall-hygiejne** | Overskrevne hukommelsesversioner forsvinder fra søgeindeksene; versionskæden i KV bevarer den fulde historik |
+| **Hints om næsten-duplikater** | Gemninger rapporterer et vejledende `similarTo`-match, når nyt indhold ligner en eksisterende hukommelse |
+| **Scoping pr. agent** | `agentId` følger med gennem save og recall tværs af REST, MCP og søgeindekset, i delt eller isoleret tilstand |
+| **Herkomst ved skrivetidspunkt** | Hver observation og hukommelse bærer en uforanderlig oprindelseskanal (user, agent, tool, import eller shared), stemplet ved capture, save og import |
+| **Auto-forglemmelse** | TTL-udløb, modstridsdetektion, vigtighedsbaseret udsmidning |
+| **Privacy first** | API-nøgler, secrets, ``-tags fjernes før lagring |
+| **Selvhelende** | Circuit breaker, fallback-kæde for providere, health-overvågning |
+| **Claude-bridge** | Bidirektionel synkronisering med MEMORY.md |
+| **Videngraf** | Entitetsudtrækning + BFS-traversering |
+| **Team-hukommelse** | Namespaced delt + privat hukommelse mellem teammedlemmer |
+| **Citationsherkomst** | Spor enhver hukommelse tilbage til kildeobservationerne |
+| **Git-snapshots** | Versionér, rul tilbage og diff hukommelsestilstanden |
+
+---
+
+
+
+Trestrøms-retrieval, der kombinerer tre signaler:
+
+| Strøm | Hvad den gør | Hvornår |
+|---|---|---|
+| **BM25** | Stemmet nøgleordsmatching med synonymudvidelse | Altid aktiv |
+| **Vektor** | Cosine-similaritet over dense embeddings | Embedding-udbyder konfigureret |
+| **Graf** | Videngraf-traversering via entitetsmatching | Entiteter opdaget i forespørgslen |
+
+Fusioneret med Reciprocal Rank Fusion (RRF, k=60) og session-diversificeret (maks. 3 resultater pr. session).
+
+Når et vektorindeks er udfyldt, bruger `mem::search` (bag `memory_recall`) den hybride BM25 + vektor-ranker. Uden embeddings bruger den BM25. `smart-search` kan desuden fusionere strukturelle graf-match, når der findes graf-data, også i nøgleløs tilstand. Lesson-recall køres på et dedikeret in-memory BM25-indeks i stedet for at scanne hele korpuset pr. forespørgsel. Overskrevne hukommelsesversioner udelukkes fra alle recall-veje; versionskæden bevarer deres historik.
+
+Vektorer overlever et crash eller force-kill. Vektorindekset gemmes i buckets højst hver `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutter). Hver vektor, der tilføjes eller fjernes imellemtiden, skrives også straks til en lille ventende log i state-store'en, og den næste opstart afspiller den uden at kalde embedding-udbyderen. Hver gennemført save tømmer loggen. Dokumenter, der stadig ikke har en vektor efter afspilningen, genindlejres i baggrunden i batches af `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), indtil ingen er tilbage, og en backfill, der stoppes, fortsætter ved næste opstart. `/agentmemory/status` og viewer viser størrelsen af den ventende log og backfill-tilstanden. Nøgleløse installationer skriver ingenting.
+
+BM25 tokeniserer græsk, kyrillisk, hebraisk, arabisk og accentueret latin ud af boksen. For kinesiske/japanske/koreanske hukommelser skal du installere de valgfrie segmenterere (`npm install @node-rs/jieba tiny-segmenter`) for at splitte CJK-forløb i ord-niveau-tokens; uden dem falder agentmemory blidt tilbage til hel-forløb-tokenisering og printer et engangshint på stderr.
+
+### Embedding-udbydere
+
+Nøgleløse installationer deaktiverer vektor-embeddings: `mem::search` bruger BM25, mens `smart-search` også kan bruge eksisterende strukturel graf-data. For at tilvælge gratis semantiske embeddings på enheden, tilføj dette til `~/.agentmemory/.env`, og genstart agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Den normale npm-installation inkluderer den valgfrie `@huggingface/transformers`-runtime. Den første embedding-forespørgsel downloader `Xenova/all-MiniLM-L6-v2`, så den kræver netværksadgang og kan tage længere tid; efterfølgende inferens køres på enheden. Eksterne udbydere opdages automatisk fra deres nøgler, med mindre `EMBEDDING_PROVIDER` overskriver dem.
+
+| Udbyder | Model | Pris | Noter |
+|---|---|---|---|
+| **Lokal (anbefalet tilvalg)** | `all-MiniLM-L6-v2` | Gratis | På enheden efter første modeldownload, +8pp recall over kun BM25 |
+| Gemini | `gemini-embedding-001` | Gratis niveau | 100+ sprog, 768/1536/3072 dimensioner (MRL), 2048-token input. Afløser `text-embedding-004` ([udfaset, lukket 14. januar 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Højeste kvalitet |
+| Voyage AI | `voyage-code-3` | Betalt | Optimeret til kode |
+| Cohere | `embed-english-v3.0` | Gratis prøveperiode | Generelt anvendelig |
+| OpenRouter | Enhver model | Varierer | Multi-model-proxy |
+
+---
+
+
+
+54 værktøjer, 6 ressourcer, 3 prompts og 17 skills.
+
+> **MCP-shim vs. fuld server:** den publicerede `@agentmemory/mcp`-pakke er en tynd shim. Den eksponerer den fulde overflade med 54 værktøjer **kun når den kan nå en kørende agentmemory-server** via `AGENTMEMORY_URL` (proxy-tilstand). Når ingen server kan nås, falder shimmen tilbage til et lokalt sæt på 7 værktøjer (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Miljøvariablen `AGENTMEMORY_TOOLS=core|all` er et flag på *serversiden*; at sætte den i shimmens `env`-blok har ingen effekt. Hvis du kun ser 7 værktøjer i Cursor / OpenCode / Gemini CLI, så start `npx -y @agentmemory/agentmemory@latest` (eller Docker-stacken), og sæt `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 værktøjer
+
+Tre værktøjsoverflader, fra mindst til størst: `AGENTMEMORY_TOOLS=core` beskærer synligheden til 8 essentielle værktøjer (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); grundsættet nedenfor er registerets 14 fundamentale værktøjer; standarden (`AGENTMEMORY_TOOLS=all`) eksponerer alle 54.
+
+
+Grundlæggende værktøjer (14)
+
+| Værktøj | Beskrivelse |
+|------|-------------|
+| `memory_recall` | Søg i tidligere observationer |
+| `memory_compress_file` | Komprimer markdown-filer, mens strukturen bevares |
+| `memory_save` | Gem en indsigt, beslutning eller et mønster |
+| `memory_file_history` | Tidligere observationer om specifikke filer |
+| `memory_patterns` | Opdag tilbagevendende mønstre |
+| `memory_sessions` | List de seneste sessioner |
+| `memory_smart_search` | Hybrid semantisk + nøgleordssøgning |
+| `memory_vision_search` | Søg i billedobservationer |
+| `memory_timeline` | Kronologiske observationer |
+| `memory_profile` | Projektprofil (koncepter, filer, mønstre) |
+| `memory_export` | Eksportér alle hukommelsesdata |
+| `memory_relations` | Forespørg relationsgrafen |
+| `memory_commit_lookup` | Sessioner bag et git-commit |
+| `memory_commits` | Commits registreret for en session |
+
+
+
+
+Udvidede værktøjer (54 i alt, standardoverfladen)
+
+| Værktøj | Beskrivelse |
+|------|-------------|
+| `memory_patterns` | Opdag tilbagevendende mønstre |
+| `memory_timeline` | Kronologiske observationer |
+| `memory_relations` | Forespørg relationsgrafen |
+| `memory_graph_query` | Videngraf-traversering |
+| `memory_consolidate` | Kør 4-lags konsolidering |
+| `memory_claude_bridge_sync` | Synkronisér med MEMORY.md |
+| `memory_team_share` | Del med teammedlemmer |
+| `memory_team_feed` | Seneste delte elementer |
+| `memory_audit` | Audit trail for operationer |
+| `memory_governance_delete` | Slet med audit trail |
+| `memory_snapshot_create` | Git-versioneret snapshot |
+| `memory_action_create` | Opret arbejdselementer med afhængigheder |
+| `memory_action_update` | Opdatér action-status |
+| `memory_frontier` | Ublokerede actions rangeret efter prioritet |
+| `memory_next` | Den enkelte vigtigste næste action |
+| `memory_lease` | Eksklusive action-leases (multi-agent) |
+| `memory_routine_run` | Instantiér workflow-routines |
+| `memory_signal_send` | Besked mellem agenter |
+| `memory_signal_read` | Læs beskeder med kvitteringer |
+| `memory_checkpoint` | Eksterne betingelses-gates |
+| `memory_mesh_sync` | P2P-synkronisering mellem instanser |
+| `memory_sentinel_create` | Event-drevne watchers |
+| `memory_sentinel_trigger` | Udløs sentinels eksternt |
+| `memory_sketch_create` | Kortvarige action-grafer |
+| `memory_sketch_promote` | Forfrem til permanent |
+| `memory_crystallize` | Komprimér action-kæder |
+| `memory_diagnose` | Health-checks |
+| `memory_heal` | Auto-reparér fastlåst tilstand |
+| `memory_facet_tag` | Dimension:værdi-tags |
+| `memory_facet_query` | Forespørg via facet-tags |
+| `memory_verify` | Spor herkomst |
+
+
+
+### 6 ressourcer · 3 prompts · 17 skills
+
+| Type | Navn | Beskrivelse |
+|------|------|-------------|
+| Ressource | `agentmemory://status` | Health, antal sessioner, antal hukommelser |
+| Ressource | `agentmemory://project/{name}/profile` | Intelligens pr. projekt |
+| Ressource | `agentmemory://project/{name}/recent` | Seneste observationer for et projekt |
+| Ressource | `agentmemory://memories/latest` | De seneste 10 aktive hukommelser |
+| Ressource | `agentmemory://graph/stats` | Videngraf-statistik |
+| Ressource | `agentmemory://team/{id}/profile` | Delt teamprofil |
+| Prompt | `recall_context` | Søg + returnér kontekst-beskeder |
+| Prompt | `session_handoff` | Handoff-data mellem agenter |
+| Prompt | `detect_patterns` | Analysér tilbagevendende mønstre |
+| Skill | `/recall` | Søg i hukommelse |
+| Skill | `/remember` | Gem til langtidshukommelse |
+| Skill | `/session-history` | Seneste sessionsopsummeringer |
+| Skill | `/forget` | Slet observationer/sessioner |
+
+Tabellen viser de fire centrale skills. Det fulde sæt er 9 kaldbare skills plus 8 referenceskills; se afsnittet Native skills ovenfor.
+
+### Standalone MCP
+
+Køres uden den fulde server, til enhver MCP-klient. Begge disse fungerer:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Eller tilføj til din agents MCP-konfiguration:
+
+De fleste agenter (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Sammenføj `agentmemory`-indgangen i hostens eksisterende `mcpServers`-objekt, i stedet for at udskifte filen. For sandboxede klienter, der ikke kan nå hostens `localhost`, tilføj `"AGENTMEMORY_FORCE_PROXY": "1"` til env-blokken, og sæt `AGENTMEMORY_URL` til en rute, sandboxen kan nå.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Kopiér plugin-filen fra repositoryet:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Starter automatisk på port `3113`. Viewer indlæser ét snapshot, når den forbinder (`GET /agentmemory/viewer/snapshot`), og anvender derefter live stream-events: nye hukommelser, lessons, observationer, audit-indgange, grafændringer og health-opdateringer vises uden polling eller gensidsindlæsninger. De eneste andre forespørgsler er de handlinger, du klikker på, "load more"-sider og søgninger. Når streamen falder ud, viser viewer, hvor gamle dens tal er, genforbinder med backoff, og resynkroniserer fra ét snapshot.
+
+- **12 faner i fire grupper** med live-tal, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), tastaturgenveje og en mobilmenu.
+- **Memories:** søgning på serversiden, filtre efter projekt, agent og type, et detaljepanel med versionskæden og en orddiff, herkomstlinks, kopiér-knapper til id'et, MCP-kaldet og en curl-kommando, rediger (en ny version), glem med bekræftelse, bulk-glem og JSON-eksport.
+- **Sessions:** en indlejret observationstidslinje med læsbart tool-input og -output, filtre og paginering, samt de hukommelser og lessons, hver session gav.
+- **Graph:** søgning, node-detaljer med relationer og kilder, en legende, der ikke udelukkende afhænger af farve, samt zoom-kontroller.
+- **Health:** den levende version af `GET /agentmemory/status`. Hvert problem kommer med sin løsning, plus state-backenden, indeksets save-tilstand, fremdrift for graf-herkomst-kompaktering og en forklaring på konsolidering med de reelle tærskler.
+- Siderne **Audit, Activity, Profile, Replay, Lessons, Actions og Crystals**, hver med en tom-tilstand, der siger, hvad sektionen er, hvorfor den er tom, og den kommando, der udfylder den, samt et `?`-ordliste-tooltip på hvert begreb og tal.
+
+```bash
+open http://localhost:3113
+```
+
+Viewer-serveren binder til `127.0.0.1` som standard og tilføjer server-secreten, når den videresender forespørgsler til REST API'et, så den kræver ingen opsætning. Den REST-serverede `/agentmemory/viewer`-endpoint følger de normale bearer-token-regler og omdirigerer browsere uden token til viewer-porten. CSP-headers bruger en per-response script-nonce og deaktiverer inline handler-attributter (`script-src-attr 'none'`).
+
+---
+
+
+
+Viewer på `:3113` viser, hvad din agent **huskede**. [iii console](https://iii.dev/docs/console) viser, hvad din agent **gjorde**: hver hukommelsesoperation som en OpenTelemetry-trace, hver KV-indgang redigerbar, hver funktion kaldbar, hver stream aftappelig. To vinduer på den samme hukommelse: ét produkt-formet, ét engine-formet.
+
+agentmemory leverer dette gratis, fordi hvert funktionskald og trigger affyres gennem iii; intet custom, intet at instrumentere.
+
+
+
+
+ Workers-siden: hver forbundne worker, inklusive agentmemory selv, med PID, funktionstal, runtime og senest set.
+
+
+**Allerede installeret.** Konsollen leveres med den fastlåste `iii`-engine (0.22+); intet separat at installere. Den første opstart downloader konsol-binaryen ved siden af enginen.
+
+**Start sammen med agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Dette kører den fastlåste engines `iii console` mod de porte, agentmemory har opløst (REST, streams, bridge), og serverer den én port over viewer, `http://localhost:3114` som standard. `--console-port N` vælger en anden port; `--port` og `--instance` vælger agentmemory-instansen på samme måde som for `stop`; ethvert andet flag videresendes, for eksempel `--enable-flow` til den eksperimentelle arkitektur-graf-side.
+
+Det samme manuelt, nyttigt når `agentmemory` ikke er på PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Hvad du kan gøre fra konsollen:**
+
+| Side | Brug den til at |
+|------|-----------|
+| **Workers** | Se hver forbundne worker og dens live metrics, inklusive agentmemory-workeren selv. |
+| **Functions** | Kalde enhver af agentmemorys funktioner direkte med en JSON-payload; praktisk til at teste `memory.recall`, `memory.consolidate`, `graph.query` uden at forbinde en klient. |
+| **Triggers** | Afspille HTTP-, cron-, event- og state-triggers igen: udløse konsoliderings-cronen manuelt, gentage en HTTP-rute, udsende en state-ændring. |
+| **States** | KV-browser med fuld CRUD over sessioner, memory-slots, livscyklustimere og embeddings-indekset; redigere værdier direkte. |
+| **Streams** | Live WebSocket-monitor for hukommelsesskrivninger, hook-events og observationsopdateringer, mens de flyder gennem iii-streams. |
+| **Queues** | Durable queue-topics + dead-letter-håndtering. Afspille eller droppe mislykkede embedding-/kompressionsjobs. |
+| **Traces** | OpenTelemetry waterfall-/flame-/service-breakdown-visninger. Filtrere efter `trace_id` for at se præcis, hvilke funktioner, DB-kald og embedding-forespørgsler en enkelt `memory.search` producerede. |
+| **Logs** | Strukturerede OTEL-logs filtreret og korreleret til trace-/span-ID'er. |
+| **Config** | Runtime-konfiguration: se præcis, hvilke workers, providere og porte din engine kører med. |
+| **Flow** | (Valgfrit, `--enable-flow`) Interaktiv arkitekturgraf over hver worker, trigger og stream. |
+
+
+
+
+ Traces: waterfall-/flame-/service-breakdown for hver hukommelsesoperation.
+
+
+**Traces er allerede aktiveret:**
+
+`iii-config.yaml` leveres med `iii-observability`-workeren aktiveret (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Ingen ekstra konfiguration nødvendig; i det øjeblik agentmemory starter, udsender hver hukommelsesoperation en struktureret log, konsollen kan læse, og én ud af ti af dem (`sampling_ratio: 0.1`) udsender også et trace-span.
+
+Hvis du i stedet vil eksportere til Jaeger/Honeycomb/Grafana Tempo, så ændr `exporter: memory` til `exporter: otlp`, og sæt collector-endpointet jf. iii's observability-dokumentation.
+
+> **Vigtigt:** der er ingen auth gennemtvunget på konsollen selv; hold den bundet til `127.0.0.1` (standarden), og eksponér den aldrig offentligt.
+
+---
+
+
+
+agentmemory er **allerede en kørende [iii](https://iii.dev)-instans**. Tre primitiver (worker, function, trigger) sammensætter runtimen; KV-state, streams og OTEL-traces kommer fra iii-state-, iii-stream- og iii-observability-workers, der leveres med iii. Du installerede ikke Postgres, Redis, Express, pm2 eller Prometheus, fordi iii erstatter dem.
+
+Det betyder, at én kommando mere udvider agentmemory med en helt ny funktion.
+
+### Udvid agentmemory med flere workers
+
+De builtins, agentmemory har brug for, er allerede i `iii-config.yaml` og starter op med den: `iii-state` (KV), `iii-queue` (durable retries til event-subscribers), `iii-pubsub`, `iii-cron`, `iii-stream` og `iii-observability` (OTEL-traces, metrics og logs på hver funktion). Alt andet fra [iii worker registry](https://workers.iii.dev) kobler sig til den samme engine: kopiér `iii-config.yaml` til `~/.agentmemory/iii-config.yaml` (CLI'en foretrækker denne fil frem for den medfølgende og indsætter stadig porte og data-paths i den), tilføj indgangen, installér worker-runtimen én gang med `~/.agentmemory/bin/iii update worker`, og genstart agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Hvad du får i tillæg til agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-baseret state-adapter, når du vokser fra KV-standarderne i hukommelsen |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Kode, der kom ud af `memory_recall`, køres inde i en kortlivet VM, ikke din shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Sæt ekstra MCP-servere op ved siden af agentmemorys, del samme engine |
+
+På engine 0.22.x skal du bevare de `iii-`-præfikserede navne for builtins ovenfor; de upræfikserede `http`-, `state`-, `queue`-, `pubsub`- og `cron`-indgange er de selvstændige registry-workers, agentmemory flytter til med 0.23-migreringen.
+
+Fuldt register: [workers.iii.dev](https://workers.iii.dev). Hver worker der sammensættes gennem de samme primitiver, agentmemory bruger, og den agentmemory, du allerede har, er én af dem.
+
+### Engine-konfiguration og bind-adresse
+
+`agentmemory start` læser engine-konfigurationen fra den første fil, der findes: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` i den aktuelle mappe, `~/.agentmemory/iii-config.yaml`, derefter den medfølgende `iii-config.yaml`. Ved hver opstart renderer den denne fil (data-paths, porte, state-backend) ind i `~/.agentmemory/data/iii-config.runtime.yaml` og starter enginen med den rendererede kopi, så redigér kildefilen, ikke den rendererede. `host:`-værdierne i kildefilen bevares som skrevet.
+
+Den medfølgende `iii-config.yaml` binder bevidst `127.0.0.1`, og denne standard gælder også inde i en container. En CLI, der startes i en container, lytter på containerens loopback, så eksponerede porte ikke når nogen steder. For at servere en containeriseret CLI gennem eksponerede porte, sæt `AGENTMEMORY_III_CONFIG` til en konfiguration, der binder `0.0.0.0`. Den medfølgende `iii-config.docker.yaml` er en sådan: den binder `iii-http`, `iii-stream` og engine-porten til `0.0.0.0` og lagrer state under `/data`, så montér et skrivbart volume der. Hold `AGENTMEMORY_SECRET` sat, og eksponér kun de porte, du har brug for, på `127.0.0.1` eller bag en proxy, du har tillid til.
+
+Dette repositorys `docker-compose.yml` går ikke gennem CLI'ens konfigurationsopslag: den monterer `iii-config.docker.yaml` på `/app/config.yaml`, og `iii-engine`-containeren starter med `--config /app/config.yaml`. One-click [deploy-skabelonerne](../deploy/) skriver deres egen `0.0.0.0`-konfiguration i deres entrypoints.
+
+### Storage-backend: file (standard) vs. redis
+
+`iii-state` og `iii-stream` falder som standard tilbage til iii-engines medfølgende filbaserede KV-lager: én JSON-fil pr. scope, holdt i engine-processens hukommelse og genskrevet til disk på en timer. Det er det rette standardvalg til en lokal single-user-installation; en delt daemon med flere samtidige skrivere får i stedet rigtige per-key-skrivninger fra Redis, til prisen af en netværksrundtur pr. operation (hvert `state::*`-kald serialiserer stadig på én Redis-forbindelse, så dette ombytter fillagrets lock til en socket, ikke til parallelisme).
+
+Sæt `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) for at skifte begge workers til iii-engines indbyggede `redis`-adapter, som lagrer hver key som et Redis hash-felt (`HSET`) i stedet for at genskrive et helt scope ved hver skrivning:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` er som standard `file`; at lade den stå usat bevarer dagens opførsel uændret, og en ikke-genkendt værdi (alt andet end `file` eller `redis`) er en opstartsfejl frem for en tavs fallback. `/agentmemory/status` og viewers Health-side (State store-rækken) rapporterer, hvilken backend der er aktiv, og om den svarer, aldrig URL'en.
+
+**Kun almindelig `redis://`.** Den fastlåste engine (0.22.1) bygger sin Redis-klient uden TLS-understøttelse, så en `rediss://`-URL (de fleste administrerede Redis-tjenester, som Upstash, Redis Cloud og ElastiCache med kryptering under transport, er som standard kun TLS) kan ikke forbinde. Forbindelsen er ukrypteret, så Redis-adgangskoden og hver lagret hukommelse krydser ledningen i klartekst: peg på en lokal Redis eller én på et privat netværk, du har tillid til. For enhver anden Redis, så kør en krypteret tunnel (stunnel, SSH eller en VPN) på agentmemory-hosten, så det almindelige `redis://`-hop forbliver på den host, og tunnelens upstream-forbindelse er krypteret og autentificeret. Hvis en Redis-adgangskode indeholder et enkelt anførselstegn, så percent-encode det (`%27`); enginen udvider URL'en i sin YAML-konfiguration, før den parses.
+
+**Én Redis-server pr. `--instance`.** Enginens Redis-key-præfikser (`state:`, `stream::`) er fikserede, så to agentmemory-instanser (`--instance 1`, `--instance 2`, ...), der peger på samme database, overskriver hinandens data. Et separat database-indeks (`redis://localhost:6379/1`) holder de lagrede data adskilt, men enginen relayerer live viewer-events over én Redis pub/sub-kanal (`stream::events`), og Redis pub/sub ignorerer database-indekset, så hver instans' viewer stadig ville vise den anden instans' live events. Giv hver instans sin egen Redis-server (eller port), når du kører mere end én.
+
+**Hvad der er det samme, og hvad der er forskelligt.** Hver agentmemory-funktion fungerer på Redis: sessioner, observationer, hukommelser (remember, supersede, evolve, forget), søgning og indeks-buckets, lessons, grafen, audit-loggen og dens månedlige scopes, eksport og import, governance-sletninger, konsolideringsstatus, viewer-snapshottet og dens live stream, samt health-monitoren. Enginen lagrer hvert scope som ét Redis-hash (`HSET`/`HGET`/`HGETALL`) og udløser de samme state-triggers som fillagret. Tre engine-forskelle håndteres inde i agentmemory:
+
+- Redis returnerer et scopes poster i ingen fast rækkefølge. agentmemory sorterer dem ældst først (efter oprettelsestidspunktet i post-id'et, derefter dets timestamp), så lister, paginering og eksport-chunks kommer tilbage i samme rækkefølge som på fillagret.
+- Enginen anvender delvise opdateringer på Redis i et Lua-script, der gør tomme arrays til tomme objekter. agentmemory anvender selv disse opdateringer (læs, ændr, skriv under en per-key-lock) på Redis, så felter som `tags: []` forbliver arrays.
+- Det gamle audit-log-check læser det gamle scope fra Redis i stedet for at kigge efter fillagrets fil på disken.
+
+Én forskel kræver din indgriben: **efter Redis genstarter, stopper enginen med at relaye live events** til viewer, indtil agentmemory genstarter. Data gemmes og læses stadig normalt. Health-monitoren sender et testevent gennem Redis hvert 30. sekund; når det ikke kommer tilbage, viser `/agentmemory/status` og viewers Health-side "Live updates are not reaching the viewer" med løsningen: genstart agentmemory. Hvis Redis er nede, viser statusrapporten "The state store is not answering" og hvordan man tjekker det (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). At liste et meget stort scope læser hele hashet i ét `HGETALL`, samme omkostning som når fillagret holder det i hukommelsen.
+
+**Anbefalede Redis-indstillinger.** Standard-snapshot-politikken `save 3600 1 300 100 60 10000` kan tabe minutter af skrivninger ved et crash, værre end fillagrets 5-sekunders flush-vindue. Sæt `appendonly yes` for alt, du ville være ked af at tabe. Sæt `maxmemory-policy noeviction`; `allkeys-lru` eller lignende smider stille og roligt hukommelser ud, så snart Redis når sin hukommelsesgrænse.
+
+En native (ikke-Docker) opstart, og hver one-click [deploy-skabelon](../deploy/) (de overskriver den medfølgende `iii-config.yaml` og starter nativt), læser `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` og indsætter dem i den startede `iii-config`. Selve URL'en skrives aldrig til den rendererede fil, kun en `${AGENTMEMORY_REDIS_URL}`-reference, som engine-processen udvider fra sit eget miljø ved opstart. Kun dette repositorys egen Docker Compose-vej (`AGENTMEMORY_USE_DOCKER=1`, eller genoptagelse af en engine, der allerede er startet på den måde) monterer `iii-config.docker.yaml` skrivebeskyttet og renderer aldrig; `agentmemory start` advarer, når den registrerer denne kombination. Skift den fil manuelt, idet du følger samme `name: redis` / `config: redis_url: ...`-form, der vises i worker-dokumentationen for [iii-state](https://workers.iii.dev/workers/iii-state) og [iii-stream](https://workers.iii.dev/workers/iii-stream), og peg `redis_url` på en Redis, der kan nås fra containeren. `docker-compose.yml` sender `AGENTMEMORY_REDIS_URL` ind i engine-containeren, så `redis_url: '${AGENTMEMORY_REDIS_URL}'` fungerer der og holder URL'en ude af den monterede fil.
+
+Den rendererede konfiguration holder URL'en ude af `~/.agentmemory/data/iii-config.runtime.yaml`, men enginens egen konfigurations-worker persisterer stadig den *udvidede* værdi til `~/.agentmemory/config/iii-state.yaml` og `iii-stream.yaml`, når den starter op (iii-engines `${VAR}`-udvidelse sker, før den worker lagrer sit seed, og den lagrer den opløste værdi, ikke referencen). Behandl den mappe som om den indeholder et credential: `chmod 700 ~/.agentmemory` på enhver delt host, og foretræk en Redis ACL-bruger, scopet til det, agentmemory har brug for, over databasens admin-credentials.
+
+**Migrering er ikke automatisk.** At skifte `AGENTMEMORY_STATE_BACKEND` starter fra et tomt lager på begge sider; intet kopierer eksisterende data fra file til Redis eller tilbage. Eksportér fra den backend, du forlader, og importér til den, du flytter til. Dette køres identisk under bash og zsh (inklusive `bash -u`). Et array som `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gør ikke: zsh holder headeren som ét forkert-formet ord, hvor bash splitter den i to, så begge forespørgsler giver 401, når `AGENTMEMORY_SECRET` er sat:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` accepterer også `?maxSessions=` og `?offset=` til at opdele et stort korpus over flere kald; `strategy` ved import er `merge` (standard-sikker), `replace` eller `skip`.
+
+### Hvad iii erstatter
+
+| Traditionel stack | agentmemory bruger |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + in-memory vektorindeks |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker-supervision |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Custom plugin-systemer | `iii worker add ` |
+
+**225 kildefiler · ~54,000 LOC · 2,600+ tests · 312 funktioner · 66 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
+
+---
+
+
+
+### LLM-udbydere
+
+agentmemory opdager automatisk udbydere fra dit miljø. En udbyder gør LLM-baserede operationer tilgængelige, men udbyderkonfiguration alene aktiverer ikke LLM-skrevet observationskomprimering. Den vej kræver både en udbyder og `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Provider | Config | Notes |
+|----------|--------|-------|
+| **No-op (standard)** | Ingen konfiguration nødvendig | LLM-baseret compress/summarize er deaktiveret. Syntetisk komprimering og BM25-recall fungerer stadig. Se `AGENTMEMORY_ALLOW_AGENT_SDK` nedenfor, hvis du tidligere afhang af Claude-abonnements-fallbacken. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Per-token-fakturering |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
+| Gemini | `GEMINI_API_KEY` | Aktiverer også embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Enhver model |
+| OpenAI API | `OPENAI_API_KEY` | Standard `gpt-5.6-luna`, overskriv med `OPENAI_MODEL` |
+| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) eller `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alt, der er OpenAI-API-kompatibelt. Ingen omkostning, kører på din egen hardware. Se [Lokale modeller](#local-models-ollama--lm-studio--vllm) nedenfor. |
+| Claude-abonnements-fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Kun tilvalg. Starter `@anthropic-ai/claude-agent-sdk`-sessioner; det forårsagede tidligere ubegrænset Stop-hook-rekursion, så det er ikke længere standard. |
+
+### Lokale modeller (Ollama / LM Studio / vLLM)
+
+agentmemory taler med enhver OpenAI-API-kompatibel server, så alt, der eksponerer `/v1/chat/completions`, fungerer uden kodeændringer. Ingen betalte nøgler, ingen cloud, ingen rate limits; kører helt på din egen hardware.
+
+**Ollama** (standardport `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (standardport `1234`):
+
+Åbn LM Studio → fanen Local Server → Start Server. Vælg en vilkårlig chat-model fra vælgeren (Qwen 3, gpt-oss, DeepSeek R1 osv.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: samme form. Peg `OPENAI_BASE_URL` på den URL, din server eksponerer, og sæt `OPENAI_MODEL` til et navn, din server vil acceptere.
+
+**Modelvalg til hukommelsesarbejde**: komprimering og opsummering er korte opgaver (<2K tokens ind, <500 tokens ud), hvor en 7B instruct-model er mere end rigeligt. Anbefalinger:
+
+| Model | Størrelse | Hvorfor |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Balanceret standard på en 16 GB-maskine; stærk til udtrækning og tool-formet tekst |
+| `qwen3:4b` | ~2.6 GB | Mindste fornuftige mulighed; fin til komprimering, svagere til graf-udtrækning |
+| `qwen3-coder:30b` | ~19 GB | Bedste lokale valg til kode-formede sessioner (30B MoE, 3.3B aktive) på 24-32 GB hardware |
+| `gpt-oss:20b` | ~14 GB | Stærk generel model, der passer til 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning-distillat; langsommere, men renere udtrækninger |
+
+Qwen 3-modeller tænker som standard og kan brænde hele token-budgettet på reasoning, før der kommer nogen output. Sæt `AGENTMEMORY_LLM_NOTHINK=1` for at tilføje `/no_think` til graf-udtræknings-prompts, og hæv `MAX_TOKENS` (16384 virker), hvis udtrækninger kommer tomme tilbage.
+
+Reasoning-klasse-modeller (`o1`-stil med ``-blokke) kan returnere tomt `content` med et `reasoning`-felt, din lokale server muligvis ikke eksponerer. Hvis udtrækninger kommer tomme tilbage, skal du først skifte til en ikke-reasoning-model. Miljøvariablen `OPENAI_REASONING_EFFORT=none` kan også deaktivere thinking på Ollama Cloud thinking-modeller, der spejler OpenAI's reasoning-skema.
+
+Lokale embeddings leveres som en valgfri afhængighed, men er ikke aktiveret som standard. Sæt `EMBEDDING_PROVIDER=local` for at tilvælge `Xenova/all-MiniLM-L6-v2` (384-dim). Den første embedding-forespørgsel downloader modellen; inferens er derefter på enheden. Uden denne indstilling eller en ekstern embedding-nøgle forbliver vektorer deaktiveret, `mem::search` bruger BM25, og `smart-search` kan stadig tilføje eksisterende graf-match.
+
+### Kostbevidst modelvalg
+
+Når LLM-skrevet baggrundskomprimering er aktiveret med både en udbyder og `AGENTMEMORY_AUTO_COMPRESS=true`, køres den på hver observation, så modelvalg ændrer de månedlige udgifter mærkbart. Indsamlet workload-data: 635 forespørgsler / 888K tokens / 35 timers aktiv brug, kørt mod tre OpenRouter-modeller med priser fra 2026-05-23.
+
+| Tier | Model | Input / 1M | Output / 1M | Cost for the captured 35h | Notes |
+|------|-------|------------|-------------|---------------------------|-------|
+| Anbefalet | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Nyeste DeepSeek; billigste anbefalede valg til komprimerings-workloads. |
+| Anbefalet | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid komprimerings- og opsummeringskvalitet ved ~10× lavere omkostning end Sonnet. |
+| Anbefalet | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Stærk kode-reasoning, hvis dine sessioner er stærkt kode-formede. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Samme listepris som den målte Sonnet 4.6-kørsel; $2/$10 introduktionspris til og med 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flagskibs-niveau; dyrt til always-on baggrundsarbejde. |
+| Undgå | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flagskibs-klasse-model; overforbrug til komprimering. |
+
+Målte rækker kommer fra den indsamlede kørsel; (est.)-rækker skalerer samme token-mix med hver models listepris.
+
+agentmemory printer en runtime-advarsel, når `OPENROUTER_MODEL` matcher et premium-niveau-mønster. Sæt `AGENTMEMORY_SUPPRESS_COST_WARNING=1` for at dæmpe den, når du har taget et informeret valg.
+
+Kvalitet vs. omkostning-afvejning til hukommelsesarbejde: komprimering er en opsummeringsopgave med relativt løse kvalitetskrav (agenten genlæser opsummeringen, ikke brugeren). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder lander inden for afrundingsfejl af Sonnet på denne opgave, mens de koster 10-70× mindre. Gem premium-niveau-modellerne til forespørgsler, du selv læser direkte.
+
+Kilder: [OpenRouter-priser for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-prisnoter](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Multi-agent-hukommelse (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+I multi-agent-opsætninger, hvor flere roller deler én agentmemory-server (architect / developer / reviewer / researcher / support-agent), tagger `AGENT_ID` hver skrivning med den rolle, der udførte den. `AGENTMEMORY_AGENT_SCOPE` styrer, om recall filtrerer efter dette tag.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+To tilstande:
+
+| Tilstand | Tagger skrivninger | Filtrerer recall | Hvornår bruges den |
+|------|------------|---------------|-------------|
+| `shared` (standard) | ja | nej | Kontekst tværs af agenter med audit trail. Architect kan se, hvad developer noterede, men hver række registrerer, hvem der sagde det. |
+| `isolated` | ja | ja | Striks adskillelse. Architect ser aldrig developers observationer/hukommelser/sessioner. |
+
+Hvad der tagges, når `AGENT_ID` er sat: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rollen flyder fra `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Hvad der filtreres i isoleret tilstand: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Hver endpoint accepterer `?agentId=` til at overskrive pr. forespørgsel, og `?agentId=*` til helt at framelde env-scopet. `/memories` accepterer også `?includeOrphans=true` for at vise pre-AGENT_ID-hukommelser, hvis `agentId` er undefined.
+
+Override pr. kald på SDK-/REST-laget: hver muterende endpoint (`/session/start`, `/remember`) accepterer et `agentId`-felt i request-body'en, som vinder over env'et. Nyttigt for runtimes, der ruter mange roller gennem én serverproces. MCP-værktøjet `memory_save` eksponerer det samme `agentId`-felt, den selvstændige stdio-server videresender både `agentId` og `project`, og gemte hukommelser bærer `agentId` ind i søgeindekset, så agent-scopet søgning dækker både hukommelser og observationer.
+
+Når `AGENT_ID` ikke er sat, forbliver hukommelsen uscopet (legacy-opførsel, ingen tags, ingen filtre).
+
+### Porte
+
+agentmemory + iii-engine binder fire porte som standard. Hvis en genstart fejler med `port in use`, fortæller denne tabel dig, hvilken proces du skal kigge efter.
+
+| Port | Proces | Formål | Env-override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Intern streams-worker (bruges af agentmemory + viewer) | `III_STREAM_PORT` (foretrukket) eller legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Realtids-viewer (`http://localhost:3113`) | `III_VIEWER_PORT` eller `AGENTMEMORY_VIEWER_URL` for den rapporterede URL |
+| `49134` | iii-engine | WebSocket; workers registrerer sig her, OTel-telemetri flyder over den | `III_ENGINE_PORT` eller `III_ENGINE_URL` |
+
+`--port ` ændrer REST-ankeret og afleder streams `N+1`, viewer `N+2` og engine-WebSocket `N+46023`, kun hvor den tilsvarende eksplicitte port eller URL ovenfor ikke er sat. Det opretter ikke et isoleret livscyklus-namespace. Brug `--instance 1` til en anden daemon; den bruger anker 3211, er som standard `3211/3212/3213/49234`, og får en separat `instance-1`-data- og livscyklusmappe. Instanser 1 til 50 følger samme mønster.
+
+Den fastlåste engine starter med `--no-update-check` (ingen opslag efter opdateringer eller sikkerhedsråd mod GitHub ved boot) og med iii's anonyme brugstelemetri slået fra: agentmemory sætter `III_TELEMETRY_ENABLED=false` for den engine, den starter, med mindre du selv eksporterer variablen, og den medfølgende compose-fil gør det samme.
+
+Rydning af forældede processer, når porte forbliver bundet efter en crashet kørsel:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` rydder både worker- og engine-pidfilen pænt op ved en graciøs native nedlukning. I Docker-tilstand flusher den den native worker, stopper den nøjagtige validerede engine-container, og bevarer både containeren og dens `/data`-mount til en lossless genstart; den næste opstart validerer og genoptager samme container. Docker-baseret afinstallation kræver `agentmemory remove --keep-data`: den fjerner delte agentmemory-styrede filer, mens den bevarer den validerede container, dens data-mount og det livscyklus-record, der er nødvendigt for at gendanne dem. Destruktiv sletning af Docker-data er med vilje overlad til operatøren efter en backup. CLI'en afviser også at adoptere eller signalere Docker- eller VM-port-indehavere (Docker backend, vpnkit, colima) som den native engine, med mindre `--force` sendes med. Den manuelle rydning ovenfor er kun til post-crash-tilfældet, hvor ingen af pidfilerne er efterladt.
+
+### Konfigurationsfil
+
+Placér agentmemorys runtime-konfiguration i `~/.agentmemory/.env` i stedet for at eksportere variabler i hver shell. Hvis viewer viser et opsætningshint som `export ANTHROPIC_API_KEY=...`, kopiér det ind i denne fil som `ANTHROPIC_API_KEY=...` uden `export`-præfikset, og genstart derefter agentmemory.
+
+Procesmiljøvariabler fungerer stadig og har forrang over værdier i filen.
+
+På Windows ligger samme fil på `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+For at teste med et Claude Code Pro/Max-abonnement i stedet for en API-nøgle, skal du tilvælge det eksplicit:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM-skrevet observationskomprimering kræver begge linjer: adgang til en LLM-udbyder (inklusive denne eksplicitte abonnements-fallback) og `AGENTMEMORY_AUTO_COMPRESS=true`. En udbyder alene lader standard-stien med syntetisk komprimering forblive uændret.
+
+Konsolidering (graf-noder, lessons, crystals) er aktiveret som standard, når en LLM-udbyder er konfigureret. Fravælg eksplicit med `CONSOLIDATION_ENABLED=false`, hvis du vil have LLM-fri drift. Graf-udtrækning er et separat flag:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Miljøvariabler
+
+Opret `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoints på port `3111`. REST API'et binder til `127.0.0.1` som standard. Beskyttede endpoints kræver `Authorization: Bearer `, og mesh-sync-endpoints kræver en eksplicit sat `AGENTMEMORY_SECRET` på begge peers.
+
+**Autentificering er slået til som standard.** Når `AGENTMEMORY_SECRET` ikke er sat (i shellen eller i `~/.agentmemory/.env`), genererer serveren en tilfældig secret ved første opstart og lagrer den i `~/.agentmemory/secret` med rettigheden `0600`. Hver medfølgende klient læser den fra der, når den taler med en lokal server: CLI'en, viewer, hooks under `plugin/scripts`, MCP-serveren og `@agentmemory/mcp`-shimmen, konfigurationerne skrevet af `agentmemory connect`, og de medfølgende OpenCode-, Pi-, OpenClaw-, Hermes- og filesystem-watcher-integrationer. Den lagrede secret sendes kun til loopback-URL'er (`localhost`, `127.0.0.0/8`, `::1`). En eksplicit `AGENTMEMORY_SECRET` vinder altid, og eksterne klienter skal stadig have den sat. Docker og `deploy/`-entrypoints genererer og eksporterer allerede deres egen secret. For at kalde API'et manuelt:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Request-regler for skrivninger.** `POST`-, `PUT`-, `PATCH`- og `DELETE`-forespørgsler til REST API'et og viewer skal sende `Content-Type: application/json` (en `charset`-parameter er fint) når de bærer en body, og en `Origin`-header, når den er til stede, skal være en loopback-origin for den konfigurerede REST- eller viewer-port eller være listet i `VIEWER_ALLOWED_ORIGINS` (kommasepareret, f.eks. `https://memory.example.com`). Klienter, der ikke sender en `Origin`-header (CLI, hooks, MCP, curl, server-til-server), er ikke påvirket. Viewer accepterer også sin egen origin.
+
+**Filstier.** Endpoints, der læser eller skriver filer (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), accepterer kun paths under `~/.agentmemory`, instansens data-mappe, eller en mappe listet i `AGENTMEMORY_IMPORT_ROOT` (separér flere med `:`, eller `;` på Windows). `/replay/import-jsonl` accepterer også sin standard `~/.claude/projects`. `/obsidian/export` forbliver inden for `AGENTMEMORY_EXPORT_ROOT`, og `/migrate` inden for `~/.agentmemory`. Symlinks opløses før hvert check.
+
+**Secret-scrubbing.** API-nøgler, bearer-tokens, PEM private key-blokke og credentials indlejret i URL'er (`scheme://user:password@host`) redigeres (redacted), før tekst lagres, på hver skrivevej: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, komprimerings- og opsummeringsoutput, crystals og graf-noder.
+
+
+Centrale endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health-check (altid offentlig) |
+| `GET` | `/agentmemory/status` | Hvad der er forkert, og hvordan det fikses (HTML til browsere, JSON i øvrigt) |
+| `GET` | `/agentmemory/viewer/snapshot` | Alt det, viewer viser, i ét svar |
+| `POST` | `/agentmemory/session/start` | Start session + få kontekst |
+| `POST` | `/agentmemory/session/end` | Afslut session |
+| `POST` | `/agentmemory/observe` | Indsaml observation (se capture-levering nedenfor) |
+| `GET` | `/agentmemory/capture` | Capture-inbox, dead letters og offline-spool |
+| `POST` | `/agentmemory/capture/retry` | Gentag dead-letter-captures |
+| `POST` | `/agentmemory/capture/drain` | Send den lokale offline-spool nu |
+| `POST` | `/agentmemory/smart-search` | Hybrid søgning |
+| `POST` | `/agentmemory/context` | Generér kontekst |
+| `POST` | `/agentmemory/remember` | Gem til langtidshukommelse |
+| `POST` | `/agentmemory/forget` | Slet observationer |
+| `POST` | `/agentmemory/enrich` | Filkontekst + hukommelser + bugs |
+| `GET` | `/agentmemory/profile` | Projektprofil |
+| `GET` | `/agentmemory/export` | Eksportér alle data |
+| `POST` | `/agentmemory/import` | Importér fra JSON |
+| `POST` | `/agentmemory/graph/query` | Videngraf-forespørgsel |
+| `POST` | `/agentmemory/graph/compact` | Beskær overdimensioneret graf-herkomst |
+| `POST` | `/agentmemory/team/share` | Del med team |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Fuld endpoint-liste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Capture-levering.** Hooks sender hver observation én gang til `POST /agentmemory/observe` med et `eventId`. Det er hostens eget id for kaldet, når payloaden har et (for eksempel Claude Codes `tool_use_id`), ellers en hash af sessionen, hook-typen, tool-navnet, input, output og host-timestamp. Serveren skriver eventet til en capture-inbox i state-store'en, lagrer observationen, og fjerner derefter inbox-indgangen. Statuskoden siger, hvad der skete:
+
+| Status | `status` field | Meaning |
+|---|---|---|
+| `201` | `accepted` | Lagret. `observationId` er den nye observation. |
+| `202` | `accepted` (`state: "retrying"`) | Accepteret, men lagring fejlede. Serveren gentager den, også efter en genstart. |
+| `200` | `duplicate` | Dette `eventId` var allerede accepteret. `observationId` er den eksisterende observation; intet nyt lagres. |
+| `400` / `422` | `rejected` | Ugyldig payload, eller lagring fejlede permanent (eventet bevares som en dead letter). |
+| `503` | `rejected` (`retryable: true`) | Inbox'en er fuld (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks spooler eventet og sender det senere. |
+
+Mislykkede events gentages hvert `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 sek.) med fordoblende backoff, op til `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Events, der stadig fejler, forbliver i inbox'en som dead letters, listes på `/agentmemory/status` og viewerens Health-side, og kan gentages med `POST /agentmemory/capture/retry` (`{"eventId": "..."}` eller `{"all": true}`). Accepterede event-id'er huskes i `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 timer, højst `AGENTMEMORY_CAPTURE_EVENTS_MAX` id'er), så en hook, der afspilles igen efter en timeout eller en genstart, lagres én gang, mens to separate tool-kald med deres egne host-id'er lagres to gange, selv når deres indhold er identisk. Når en observation slettes (forget, sessionssletning, eviction, auto-forget eller en import, der udskifter lageret), markeres dens event som slettet, før observationen fjernes, så en afspilning af det event inden for samme vindue besvares som en duplikat og lagrer intet. State-store'en skriver til disk hvert 2. sekund, så et besvaret event stadig kan være kun i hukommelsen et øjeblik. For at dække det bærer hvert `2xx`-svar også serverens `bootId` (ny ved hver opstart), `acceptedAt` og `durableAfterMs` (save-intervallet plus 1.5 s på fillagret, 1.5 s på redis, hvor persistens er operatørens indstilling). Hooks holder eventet i den lokale spool, indtil dette vindue er gået, og sletter det ved et senere kald uden endnu en forespørgsel. Hvis `bootId` er ændret til da, genstartede serveren, så hooken sender eventet igen med samme `eventId`; et event, der nåede disken, lagres ikke to gange. Serveren sender også selv sådanne events ved opstart og ved hvert retry-interval, så en genstart taber intet, selv når ingen hook kører bagefter. Ældre hooks ignorerer de ekstra felter, og nye hooks mod en ældre server kasserer eventet ved `2xx` som før.
+
+Når serveren er nede, ikke svarer i tide, eller returnerer en 5xx, tilføjer hooken observationen til en lokal spool-fil, `/capture-spool/-.jsonl` (overskriv mappen med `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Filen er privat for din bruger (rettighed 600), secrets redigeres (redacted) på samme måde som serveren redigerer dem, den holder højst `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) og smider indgange ud, der er ældre end `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Når den er fuld, smides nye indgange ud og tælles, og `/agentmemory/status` rapporterer det. Hooken afslutter stadig med 0 inden for sin tidsgrænse og tilføjer ingen forespørgsel, når serveren er sund. Spool'en sendes ved næste opstart og af den første hook, der når serveren igen, i en baggrundsproces, så agenten ikke venter. Event-id'er gør dette sikkert: en observation, der nåede frem før en timeout, lagres ikke to gange. `npx @agentmemory/agentmemory capture` viser spool'en og server-inbox'en, `--drain` sender spool'en nu, og `GET /agentmemory/capture` returnerer det samme som JSON. Sæt `AGENTMEMORY_CAPTURE_SPOOL=false` for at slå spool'en fra.
+
+**Komprimering af graf-herkomst.** Hver videngraf-node og -kant bevarer id'erne for de nyeste 32 observationer, den stammer fra. Lagre skrevet før det loft kan holde tusindvis af id'er pr. hot node, hvilket gør graf-søgning og viewer langsom eller fælder workeren. agentmemory fixer dette selv: ved den første opstart efter en opgradering beskærer den hver node, kant, overskrevet kant (den temporale graf-historik) og det cachede snapshot til loftet i baggrunden, i små skiver med en pause imellem, så søgning, capture og viewer fortsætter med at fungere. Den gemmer sin fremdrift, genoptager efter en genstart, og kører aldrig igen, når den er færdig. `/agentmemory/status` og viewerens Health-side viser den som pending, running (med det aktuelle scope og position), done eller failed. Sæt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` for at slå den fra.
+
+For at køre den manuelt, kald `POST /agentmemory/graph/compact`. Den gennemgår navne- og edge-key-indekserne i stedet for at liste hver node og kant, og er sikker at køre igen. Når den beskærer id'er, skriver den en `graph_compact`-audit-indgang.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+På et stort lager, eller når kaldet returnerer 504, så kør den i skiver. Send `scope` (`nodes`, `edges` eller `history`), `offset` og `limit`, og kald derefter igen med den returnerede `nextOffset`, indtil den er `null`. Gør dette for `nodes`, `edges` og `history`, og afslut med ét `{"scope":"snapshot"}`-kald, fordi en skive-kørsel ikke rører det cachede snapshot.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Forudsætninger:** Node.js >= 20 med npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 eller Docker. Den automatiske engine-installation på macOS/Linux kræver også `curl`, en POSIX `sh` og `tar`; native Windows bruger den manuelt fastlåste `iii.exe`, WSL2 eller Docker Desktop.
+
+
+
+[Apache-2.0](../LICENSE)
diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md
index 2f95ce63f7..34793535bd 100644
--- a/READMEs/README.de-DE.md
+++ b/READMEs/README.de-DE.md
@@ -7,22 +7,43 @@
Ihr Coding-Agent merkt sich alles. Schluss mit dem ständigen Wiederholen.
Built on iii engine
- Persistentes Gedächtnis für Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode und jeden MCP-Client.
+ Persistentes Gedächtnis für Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode und jeden MCP-Client.
@@ -75,22 +96,34 @@
## Install
-Ein Befehl:
+Voraussetzungen:
+
+- Node.js 20 oder neuer mit npm und npx (`node -v`, `npm -v` und `npx -v`).
+- Die automatische iii-engine-Installation unter macOS/Linux benötigt außerdem `curl`, eine POSIX-`sh` und `tar`. Minimale Images wie `node:20-slim` enthalten diese unter Umständen nicht.
+- Natives Windows erfordert, dass die gepinnte iii-engine v0.22.1 `iii.exe` manuell installiert wird. WSL2 oder Docker Desktop sind die anderen unterstützten Wege.
+
+Kanonischer Befehl für die Frischinstallation:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-Der erste Lauf ist ein interaktives Setup: Wählen Sie die zu verdrahtenden Agenten (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), wählen Sie einen LLM-Provider oder bleiben Sie ohne Schlüssel, und es legt die Konfiguration an, startet den Memory-Server auf `:3111` und bietet eine globale Installation an, sodass der nackte Befehl `agentmemory` anschließend überall funktioniert.
+Der erste Lauf ist ein interaktives Setup: Wählen Sie die zu verdrahtenden Agenten (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), wählen Sie einen LLM-Provider oder bleiben Sie ohne Schlüssel, und es legt die Konfiguration an, startet den Memory-Server und seine gepinnte iii-Engine und bietet an, global zu installieren, sodass der nackte Befehl `agentmemory` anschließend überall funktioniert. `-y` akzeptiert npx' Paket-Prompt, und `@latest` vermeidet eine veraltete gecachte Version. Ein Provider macht LLM-Funktionen verfügbar, aber die LLM-geschriebene Beobachtungs-Kompression startet erst, wenn zusätzlich `AGENTMEMORY_AUTO_COMPRESS=true` gesetzt ist.
+
+Der schlüssellose Modus deaktiviert Vector-Embeddings. `memory_recall` (der Pfad `mem::search`) verwendet BM25, während `memory_smart_search` zusätzlich strukturelle Graph-Treffer einbeziehen kann, wenn bereits Graph-Daten existieren. Für kostenloses semantisches Recall auf dem eigenen Gerät setzen Sie `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` und starten neu. Die erste Embedding-Anfrage lädt `Xenova/all-MiniLM-L6-v2` herunter; danach läuft die Inferenz lokal.
+
+Die lokale Runtime verwendet vier Ports: `3111` für REST/MCP HTTP, `3112` für iii-Streams, `3113` für den Viewer und `49134` für den WebSocket des iii-Workers. Persistenter iii-State liegt unter `~/Library/Application Support/agentmemory` auf macOS, `$XDG_DATA_HOME/agentmemory` bzw. `~/.local/share/agentmemory` auf Linux und `%APPDATA%\agentmemory` auf Windows. Verwenden Sie `--data-dir ` oder `AGENTMEMORY_DATA_DIR`, um das zu überschreiben, und nutzen Sie bei jedem Neustart denselben Wert. Aus Gründen der Abwärtskompatibilität hat eine bereits vorhandene `./data/state_store.db` oder `./data/iii-config.yaml` für Instanz 0 Vorrang vor dem Plattform-Standard; ein expliziter Flag- oder Umgebungs-Override gewinnt trotzdem.
Beweisen Sie dann, dass Recall funktioniert, und geben Sie Ihrem Agenten seine Skills:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
-Sie möchten das Ganze lieber von einem Coding-Agenten erledigen lassen? Geben Sie ihm eine einzige Anweisung:
+Die Keyword-Suchen sollten im Standard-Modus ohne Schlüssel über BM25 treffen. Die `database performance optimization`-Abfrage der Demo ist bewusst semantisch und kann null Treffer liefern, bis ein Embedding-Provider konfiguriert ist.
+
+Möchten Sie das Ganze lieber von einem Coding-Agenten erledigen lassen? Geben Sie ihm eine einzige Anweisung:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
@@ -99,7 +132,7 @@ Verdrahten Sie jederzeit weitere Agenten mit `agentmemory connect ` — 2
Windows
-Der schnelle Weg ist WSL2. Das native Windows-Engine-Setup ist manuell (etwa 10 bis 20 Minuten), und `agentmemory connect` wird dort derzeit nicht unterstützt. Siehe die [Windows-Hinweise](#windows) für die Schritt-für-Schritt-Anleitung.
+Der schnelle Weg ist WSL2. Das native Windows-Engine-Setup erfordert, dass die gepinnte v0.22.1-ZIP herunterladen und `iii.exe` manuell extrahiert wird; die CLI extrahiert sie nicht automatisch. Docker Desktop wird ebenfalls unterstützt. Siehe die [Windows-Hinweise](#windows) für die Schritt-für-Schritt-Anleitung.
@@ -107,24 +140,24 @@ Der schnelle Weg ist WSL2. Das native Windows-Engine-Setup ist manuell (etwa 10
Globale Installation / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+Der obige npx-Befehl bleibt der kanonische Weg für die Frischinstallation und vermeidet Berechtigungsprobleme mit dem globalen Präfix.
+
npx liefert eine alte Version
-npx cached pro Version. 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`).
+npx cached pro Version. 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`).
Sie betreiben bereits eine eigene iii-Engine
-agentmemory pinnt iii-engine v0.11.2 und verbindet sich nicht mit einer anderen Version (der Worker kann das Protokoll einer anderen Engine nicht sprechen). Stoppen Sie die andere Engine und führen Sie dann `npx -y @agentmemory/agentmemory@latest` aus. Es installiert und startet das gepinnte v0.11.2 in `~/.agentmemory/bin` und lässt Ihre eigene `iii` unangetastet.
+agentmemory pinnt iii-engine v0.22.1 und verbindet sich nicht mit einer anderen Version (der Worker kann das Protokoll einer anderen Engine nicht sprechen). Stoppen Sie die andere Engine und führen Sie dann `npx -y @agentmemory/agentmemory@latest` aus. Es installiert und startet das gepinnte v0.22.1 in `~/.agentmemory/bin` und lässt Ihre eigene `iii` unangetastet.
@@ -136,88 +169,139 @@ agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterst
@@ -232,10 +316,19 @@ Sie erklären in jeder Session dieselbe Architektur. Sie entdecken dieselben Bug
**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, ohne erneutes Erklären und ohne Copy-Paste.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **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).
+Standardmäßig speichert agentmemory den iii-engine-State außerhalb des Repositorys, aus dem Sie es starten: `~/Library/Application Support/agentmemory` auf macOS, `$XDG_DATA_HOME/agentmemory` bzw. `~/.local/share/agentmemory` auf Linux und `%APPDATA%\agentmemory` auf Windows. Eine bereits vorhandene Legacy-`./data/state_store.db` oder `./data/iii-config.yaml` wird für Instanz 0 vor diesem Plattform-Standard wiederverwendet. Um einen Ort explizit zu wählen, übergeben Sie `--data-dir ` oder setzen Sie `AGENTMEMORY_DATA_DIR`; beide expliziten Einstellungen haben Vorrang vor der Legacy-Erkennung:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native Starts und Docker-Starts verwenden dasselbe aufgelöste Host-Verzeichnis; Docker bindet es per Bind-Mount an `/data`. `--instance 1` hängt `instance-1` an das aufgelöste Verzeichnis an und wählt das separate Standard-Port-Quartett `3211/3212/3213/49234`.
+
+Neueste Release-Hinweise: [CHANGELOG.md](../CHANGELOG.md).
---
@@ -254,14 +347,14 @@ npx @agentmemory/agentmemory
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep-Baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
-100 % Top-5-Trefferquote an der **mathematischen P@5-Obergrenze** für diesen Korpus (0.240, siehe Scorecard). Hybrid findet jede Gold-Session; grep verfehlt 1 von 2 Gold-Sessions bei der Multi-Session-Temporalanfrage. Der Gewinn ist **Recall + Temporal**, nicht aggregierte Präzision. Dieser Benchmark ist klein und Gold-arm; das größere LongMemEval-S unten differenziert besser. Volle Aufschlüsselung pro Typ + Korrekturhinweis: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+100 % Top-5-Trefferquote an der **mathematischen P@5-Obergrenze** für diesen Korpus (0.240, siehe Scorecard). Hybrid findet jede Gold-Session; grep verfehlt 1 von 2 Gold-Sessions bei der Multi-Session-Temporalanfrage. Der Gewinn ist **Recall + Temporal**, nicht aggregierte Präzision. Dieser Benchmark ist klein und Gold-arm; das größere LongMemEval-S unten differenziert besser. Vollständige Aufschlüsselung pro Typ + Korrekturhinweis: [`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% |
+| Nur-BM25-Fallback | 86.2% | 94.6% | 71.5% |
@@ -281,7 +374,7 @@ npx @agentmemory/agentmemory
> 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), der agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo abdeckt.
-**Lokal reproduzieren:** [`eval/README.md`](../eval/README.md), ein 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/).
+**Lokal reproduzieren:** [`eval/README.md`](../eval/README.md), ein 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).
@@ -409,7 +502,7 @@ npx @agentmemory/agentmemory
Token-Effizienz
-
~1.900 Tokens/Session (10 $/Jahr)
+
~1,900 Tokens/Session ($10/Jahr)
Je nach Integration unterschiedlich
Core Memory im Kontext
Variiert
@@ -463,29 +556,54 @@ Keines davon erfasst automatisch aus Coding-Agent-Hooks, liefert einen local-fir
-Kompatibilität: Diese Version zielt auf stabiles `iii-sdk` `^0.11.0` und iii-engine v0.11.x ab.
+Kompatibilität: Diese Version zielt auf `iii-sdk` 0.22.1 und pinnt iii-engine v0.22.1.
### In 30 Sekunden ausprobieren
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest 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, was Keyword-Matching nicht kann.
+`demo` befüllt 3 realistische Sessions (JWT-Auth, N+1-Query-Fix, Rate Limiting) und führt Suchen darauf aus. Installationen ohne Schlüssel deaktivieren Vectors, daher sollten die Keyword-Abfragen von `mem::search` über BM25 treffen, während `database performance optimization` null Treffer liefern kann. `smart-search` kann zusätzlich strukturelle Graph-Treffer liefern, wenn Graph-Daten existieren. Damit die semantische Abfrage den N+1-Fix über Vectors findet, setzen Sie `EMBEDDING_PROVIDER=local`, starten neu und lassen den ersten Modell-Download abschließen.
Öffnen Sie `http://localhost:3113`, um das Memory in Echtzeit aufgebaut zu sehen.
+### Eine Frischinstallation und die Persistenz nach einem Neustart validieren
+
+Validieren Sie bei laufendem Server REST, Health, den Viewer und den iii-gestützten Runtime-Status:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Das Startup-Ready-Panel berücksichtigt alle vier Ports: REST/MCP HTTP auf 3111, iii-Streams auf 3112, den Viewer auf 3113 und den WebSocket des iii-Workers auf 49134. `status` bestätigt die agentmemory-Health und den aktiven Provider-/Embedding-Modus. Speichern Sie eine Probe und prüfen Sie, dass sie durchsuchbar ist:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Führen Sie dann `npx -y @agentmemory/agentmemory@latest stop` aus, starten Sie den kanonischen Befehl in Terminal 1 erneut, warten Sie auf `/agentmemory/livez` und wiederholen Sie die Suche. Die Probe muss weiterhin zurückgegeben werden. Wenn Sie ein eigenes `--data-dir` gewählt haben, übergeben Sie beim Neustart dasselbe Verzeichnis.
+
### Alltagsbefehle
Installation und Setup stehen oben unter [Install](#install) (der erste Lauf führt Sie hindurch). Im Alltag:
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -499,37 +617,37 @@ So übernehmen Sie ältere Claude-Code-JSONL-Transkripte:
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest 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`, ohne Seitenkanal-Server. Jedes importierte Transkript wird für die Suche indiziert, mit dem Ursprungskanal `import` gestempelt, und daraus werden ein Session-Crystal und Lessons gewonnen.
-> **Achtung, wenn Sie sich auf `import-jsonl` als primären Erfassungspfad verlassen:** Claude Codes `cleanupPeriodDays` (in `~/.claude/settings.json`, Standard **30**) löscht JSONL-Transkripte, die älter als dieses Fenster sind, automatisch aus `~/.claude/projects/`. Wenn Sie agentmemory frisch auf einer monatealten Claude-Code-Historie installieren, ist alles, was älter als 30 Tage ist, schon vor dem ersten Import weg. Führen Sie `import-jsonl` entweder per Cron aus, erhöhen Sie `cleanupPeriodDays` auf einen höheren Wert oder verdrahten Sie die Auto-Capture-Hooks (den Standard-Plugin-Installationspfad), sodass jeder Turn in agentmemory landet, während die Session live ist, und das JSONL-Cleanup keine Rolle mehr spielt.
+> **Achtung, wenn Sie sich auf `import-jsonl` als primären Erfassungspfad verlassen:** Claude Codes `cleanupPeriodDays` (in `~/.claude/settings.json`, Standard **30**) löscht JSONL-Transkripte, die älter als dieses Fenster sind, automatisch aus `~/.claude/projects/`. Wenn Sie agentmemory frisch auf einer monatealten Claude-Code-Historie installieren, ist alles, was älter als 30 Tage ist, schon vor dem ersten Import weg. Führen Sie `import-jsonl` entweder per Cron aus, erhöhen Sie `cleanupPeriodDays` auf einen höheren Wert, oder verdrahten Sie die Auto-Capture-Hooks (den Standard-Plugin-Installationspfad), sodass jeder Turn in agentmemory landet, während die Session live ist, und das JSONL-Cleanup keine Rolle mehr spielt.
### Upgrade / Wartung
Verwenden Sie den Wartungsbefehl, wenn Sie Ihr lokales Runtime bewusst aktualisieren wollen:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Achtung: Dieser Befehl verändert den aktuellen Workspace/Runtime. Er kann JavaScript-Abhängigkeiten aktualisieren und das gepinnte Docker-Image `iiidev/iii:0.11.2` ziehen. Er installiert niemals eine ungepinnte oder neuere iii-Engine.
+Achtung: Dieser Befehl verändert den aktuellen Workspace/Runtime. Er kann JavaScript-Abhängigkeiten aktualisieren und das gepinnte Docker-Image `iiidev/iii:0.22.1` ziehen. Er installiert niemals eine ungepinnte oder neuere iii-Engine.
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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code 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.
+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.22/scripts/…`), sodass das nächste Upgrade jeden Hook stillschweigend bricht.
Workaround:
@@ -544,7 +662,7 @@ Für entfernte oder geschützte Deployments starten Sie Claude Code mit gesetzte
```bash
# 1. start the memory server in a separate terminal
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
@@ -553,29 +671,43 @@ 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 54 Tools, wenn `AGENTMEMORY_URL` auf einen laufenden agentmemory-Server zeigt; fällt lokal auf 7 Tools zurück, wenn kein Server erreichbar ist)
+- Eine mitgelieferte stdio-MCP-Bridge zum laufenden Daemon, ohne npm-Download oder Fallback-Store. Siehe den [lokalen Codex-Leitfaden](../docs/plugins/codex-local.md), um einen unveröffentlichten Build zu testen.
- 6 Lifecycle-Hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 aufrufbare Skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 Referenz-Skills, die der Agent bei Bedarf lädt (memory discipline, MCP-Tools, REST-API, Konfiguration, Agents, Hooks, Architektur und der Skill-Autorenleitfaden)
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)
+#### Codex-Hooks: Vertrauen und Kompatibilität
-`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.
+Der native Plugin-Hook-Dispatch ist mit Codex CLI 0.150.1 verifiziert. Vertrauen Sie den Plugin-Hooks, bevor Sie Erfassung erwarten. Das Verhalten von Codex Desktop hängt von seiner mitgelieferten Runtime ab; prüfen Sie `/hooks` und bestätigen Sie ein erfasstes Event, bevor Sie einen Workaround aktivieren.
-Solange der Fix upstream nicht gelandet ist, spiegeln Sie dieselben Hook-Befehle in die globale `~/.codex/hooks.json`:
+Wenn Ihr Host globale Hooks benötigt, spiegeln Sie die Befehle in die globale `~/.codex/hooks.json`. Wenn MCP bereits verdrahtet ist, braucht der aktuelle `connect`-Adapter `--force`, um die Hook-Installation zu erreichen:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-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.
+Das mischt globale Hooks und schreibt den agentmemory-MCP-Eintrag um, wobei unabhängige Einträge erhalten bleiben. Prüfen Sie alle benutzerdefinierten agentmemory-Endpunkt-Einstellungen, bevor Sie `--force` verwenden. Führen Sie es nach einem Upgrade erneut aus, um die Skript-Pfade zu aktualisieren. Aktivieren Sie entweder native Plugin-Hooks oder globale Kopien, um doppelte Erfassung zu vermeiden.
+
+### GitHub Copilot CLI
+
+Für den VS-Code-Agentenmodus nutzen Sie den [Copilot-MCP- und Auto-Capture-Leitfaden](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Der CLI-Connector konfiguriert VS Code nicht.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` führt `mcpServers.agentmemory` in `~/.copilot/mcp-config.json` zusammen (oder `$COPILOT_HOME/mcp-config.json`, wenn `COPILOT_HOME` gesetzt ist) und bewahrt bestehende Server. Auf nativem Windows ist dies der einzige automatisierte `connect`-Adapter; konfigurieren Sie jeden anderen nativen Windows-Agenten manuell. `connect` unter WSL ist nur dann sinnvoll, wenn der Ziel-Agent auch in derselben WSL-Umgebung installiert ist. Copilot übernimmt den MCP-Server beim nächsten Start oder nach `/mcp`. Installieren Sie zusätzlich das Plugin, wenn Sie die volle Hook-/Skill-Erfahrung wollen.
OpenClaw (diesen Prompt einfügen)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -600,7 +732,7 @@ Vollständiger Leitfaden: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (diesen Prompt einfügen)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -619,11 +751,11 @@ Vollständiger Leitfaden: [`integrations/hermes/`](../integrations/hermes/)
### Andere Agenten
-Starten Sie den Memory-Server: `npx @agentmemory/agentmemory`
+Starten Sie den Memory-Server: `npx -y @agentmemory/agentmemory@latest`
#### Native Skills via `npx skills add` (50+ Agenten)
-agentmemory liefert 17 Skills im Claude-Code-artigen `/SKILL.md`-Format mit: 9 aufrufbare Action-Skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) und 8 Referenz-Skills, die der Agent bei Bedarf lädt (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Die Referenz-Skills tragen aus dem Quellcode generierte Datentabellen, sodass sie nie driften. Die [`skills`](https://npmjs.com/package/skills)-CLI von vercel-labs installiert sie automatisch in das native Skill-Verzeichnis des aufrufenden Agenten, über 50+ Agenten hinweg (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf und mehr):
+agentmemory liefert 17 Skills im Claude-Code-artigen `/SKILL.md`-Format: 9 aufrufbare Action-Skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) und 8 Referenz-Skills, die der Agent bei Bedarf lädt (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Die Referenz-Skills tragen aus dem Quellcode generierte Datentabellen, sodass sie nie driften. Die [`skills`](https://npmjs.com/package/skills)-CLI von vercel-labs installiert sie automatisch in das native Skill-Verzeichnis des aufrufenden Agenten, über 50+ Agenten hinweg (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf und mehr):
```bash
npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
@@ -640,7 +772,7 @@ Für die wenigen Agenten, die die skills-CLI noch nicht abdeckt (Zed v1.3.x und
#### Standard-MCP-Block
-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):
+Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, der das `mcpServers`-Format verwendet (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
```json
"agentmemory": {
@@ -657,24 +789,26 @@ Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, de
| Agent | Konfigurationsdatei | Hinweise |
|---|---|---|
-| **Cursor** | `~/.cursor/mcp.json` | In `mcpServers` einfügen. Ein-Klick-Deeplink auch auf der Website. |
+| **Cursor (nur MCP)** | `~/.cursor/mcp.json` | In `mcpServers` einfügen, oder `agentmemory connect cursor`. Ein-Klick-Deeplink auch auf der Website. |
+| **Cursor (volles Plugin)** | `.cursor-plugin/` | Cursor-Marketplace-Eintrag (Einreichung in Prüfung) oder Cursor Settings → Plugins → lokaler Checkout. Registriert 7 Auto-Capture-Hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 Skills + den MCP-Server, wobei `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` im Cursor-Plugin-Dashboard verwaltet werden. Funktioniert in der Cursor-IDE und der `cursor-agent`-CLI; Print-Mode-Prompts der CLI werden am Session-Ende aus dem Session-Transkript nachgefüllt. |
| **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. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` fügt den MCP-Eintrag ein; `--with-hooks` ergänzt sechs native Auto-Capture-Hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) mit Devins kleingeschriebenen Tool-Matchern. Prüfen mit `devin mcp list` und `/hooks` in devin. |
-| **Devin (Cloud)** | Settings → Connections → MCP servers | Custom MCP (STDIO) hinzufügen: Command `npx`, Args `-y @agentmemory/mcp@latest`, Env `AGENTMEMORY_URL` auf ein netzwerkerreichbares agentmemory-Deployment plus `AGENTMEMORY_SECRET` (Cloud-Sitzungen erreichen kein localhost — siehe [`deploy/`](../deploy/)). |
+| **Devin CLI (MCP + Hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` fügt den MCP-Eintrag ein; `--with-hooks` ergänzt sechs native Auto-Capture-Hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) mit Devins kleingeschriebenen Tool-Matchern. Prüfen mit `devin mcp list` und `/hooks` in devin. |
+| **Devin CLI (volles Plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` aus einem Checkout registriert alle 17 Skills als `/agentmemory:`-Slash-Befehle plus den MCP-Server. Devin-Plugin-Hooks können `SessionStart`/`SessionEnd` nicht auslösen, daher kombinieren Sie es mit `connect devin --with-hooks` für vollständige Session-Erfassung. |
+| **Devin (Cloud)** | Settings → Connections → MCP servers | Einen benutzerdefinierten MCP (STDIO) hinzufügen: Command `npx`, Args `-y @agentmemory/mcp@latest`, Env `AGENTMEMORY_URL`, das auf ein netzwerkerreichbares agentmemory-Deployment zeigt, plus `AGENTMEMORY_SECRET` (Cloud-Sitzungen erreichen kein localhost — siehe [`deploy/`](../deploy/)). Speichern Sie das Secret in Devin Secrets und nutzen Sie dann „Test listing tools", um zu prüfen, dass alle 54 Tools erscheinen. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (automatisches Mergen). |
| **GitHub Copilot CLI (nur MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` merged `mcpServers.agentmemory`; Copilot übernimmt es beim nächsten Start oder per `/mcp`. |
| **GitHub Copilot CLI (volles Plugin)** | Copilot-Plugin-Installation | `copilot plugin install rohitg00/agentmemory:plugin` für das Plugin aus dem GitHub-Unterverzeichnis. |
-| **OpenClaw** | OpenClaw-MCP-Konfig | Gleicher `mcpServers`-Block. Tiefer: `openclaw plugins install ./integrations/openclaw` beansprucht OpenClaws Memory-Slot (wechselt automatisch von `memory-core`); setzen Sie `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, sonst wird die Turn-Erfassung stillschweigend blockiert. Siehe [`integrations/openclaw`](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) + 17 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. |
+| **OpenClaw** | OpenClaw-MCP-Konfig | Gleicher `mcpServers`-Block. Tiefer: `openclaw plugins install ./integrations/openclaw` beansprucht OpenClaws Memory-Slot (wechselt automatisch von `memory-core`); setzen Sie `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, sonst wird die Turn-Erfassung stillschweigend blockiert. Siehe [`integrations/openclaw`](../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 + 17 Skills. Vertrauen Sie den Hooks und verifizieren Sie die Erfassung in Ihrem Host; siehe [Codex-Setup und -Validierung](../docs/plugins/codex-local.md). |
| **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. Die Projekt-Zuordnung erfolgt pro Session, sodass ein OpenCode-Prozess, der mehrere Repositories umspannt, jede Session unter ihrem eigenen Projekt ablegt. 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` | `agentmemory connect pi` installiert die mitgelieferte Extension in pis Auto-Discovery-Verzeichnis (Recall beim Agent-Start, Capture beim Agent-Ende, `memory_search` / `memory_save` / `memory_health` Tools, `/agentmemory-status`). `/reload` in einem laufenden pi übernimmt sie. [`integrations/pi`](../integrations/pi/) ist außerdem ein pi-Paket (`pi install ./integrations/pi` aus einem Checkout). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` liefert den 6-Hook-Memory-Provider (Prefetch, Turn-Erfassung, Session-Ende, Vorkomprimierung, MEMORY.md-Spiegelung, System-Prompt-Block). Validieren Sie mit `hermes plugins doctor` und `hermes memory status`. Siehe [`integrations/hermes`](integrations/hermes/). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` liefert den 6-Hook-Memory-Provider (Prefetch, Turn-Erfassung, Session-Ende, Vorkomprimierung, MEMORY.md-Spiegelung, System-Prompt-Block). Validieren Sie mit `hermes plugins doctor` und `hermes memory status`. Siehe [`integrations/hermes`](../integrations/hermes/). |
| **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. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. Die `agy`-CLI hält ihre eigene Konfig unter `~/.gemini/`, getrennt von der Antigravity-IDE oben. Übergeben Sie `--with-hooks` für native Auto-Erfassung via `~/.gemini/config/hooks.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installiert MCP und Capture-Hooks im gemeinsam genutzten Customization-Verzeichnis. Siehe [Antigravity-Setup und -Grenzen](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` verwendet dieselbe MCP- und Hook-Konfiguration wie aktuelle IDE-Versionen. Bestehende Installationen sollten mit `--force` aktualisieren; siehe die [Upgrade-Hinweise](../docs/plugins/antigravity.md). |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` schreibt die Konfig auf Benutzerebene. Workspace-Overrides liegen in `.kiro/settings/mcp.json` neben Ihrem Code. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` schreibt den standardmäßigen `mcpServers`-Block. Warp entdeckt außerdem Skills aus `.claude/skills/` automatisch; sobald das Claude-Code-Plugin installiert ist, erscheinen die 8 agentmemory-Skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) nativ in Warps Slash-Command-Palette. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` schreibt den standardmäßigen `mcpServers`-Block. Nutzer der VS-Code-Extension: Fügen Sie denselben Block über Cline Settings → MCP Servers → Edit JSON ein. |
@@ -710,7 +844,7 @@ iii.trigger({
})
```
-Vollständiges Beispiel: [`examples/python/`](../examples/python/) (Quickstart + Beobachtungs-/Recall-Fluss). REST auf `:3111` bleibt verfügbar für Hosts ohne iii-Runtime.
+Durchgearbeitetes Beispiel: [`examples/python/`](../examples/python/) (Quickstart + Beobachtungs-/Recall-Fluss). REST auf `:3111` bleibt verfügbar für Hosts ohne iii-Runtime.
### Aus den Quellen
@@ -719,39 +853,43 @@ 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`.
+Das startet agentmemory mit einer lokalen `iii-engine`, falls das gepinnte Binary bereits installiert ist, oder verwendet Docker Compose, wenn das ausgewählt ist. REST, Streams und der Viewer binden sich standardmäßig an `127.0.0.1`. Der automatische Binary-Pfad für macOS/Linux erfordert `curl`, eine POSIX-`sh` und `tar`.
-`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=`, wenn Sie manuell auf das Sandbox-Modell migriert sind.
+`iii-engine` manuell installieren. **agentmemory pinnt `iii-engine` derzeit auf `v0.22.1`**, dieselbe Version wie seine `iii-sdk`-Abhängigkeit; der Worker spricht das Wire-Protokoll genau dieser Engine, und 0.20.0 hat die SDK-Oberfläche neu organisiert, daher werden beide in agentmemory-Releases gemeinsam angehoben. Mit `AGENTMEMORY_III_VERSION=` überschreiben, wenn Sie eine eigene Engine betreiben und wissen, dass sie passt.
-- **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 arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** `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
+- **Windows:** `iii-x86_64-pc-windows-msvc.zip` von [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) herunterladen und `iii.exe` nach `%USERPROFILE%\.agentmemory\bin\iii.exe` extrahieren
+
+Jedes Archiv hat eine passende `.sha256`-Datei auf der Release-Seite; wenn Sie die Plattform wechseln, verwenden Sie den Hash dieser Datei in der obigen Prüfung (unter Windows: `Get-FileHash`). Der automatische Installer in `npx @agentmemory/agentmemory` pinnt diese Hashes und lehnt ein Archiv ab, das nicht übereinstimmt.
-Oder Docker verwenden (die mitgelieferte `docker-compose.yml` zieht `iiidev/iii:0.11.2`). Vollständige Doku: [iii.dev/docs](https://iii.dev/docs).
+Oder Docker verwenden (die mitgelieferte `docker-compose.yml` zieht `iiidev/iii:0.22.1`). 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:
+agentmemory läuft auf Windows 10/11, aber das Node.js-Paket allein genügt nicht; Sie brauchen außerdem die gepinnte iii-engine-v0.22.1-Runtime als Hintergrundprozess. Die CLI extrahiert die Windows-ZIP nicht automatisch, daher müssen native Windows-Nutzer `iii.exe` manuell installieren, WSL2 verwenden oder Docker Desktop wählen.
+
+Die automatisierte native Windows-MCP-Verdrahtung unterstützt nur `agentmemory connect copilot-cli`. Für Claude Code, Codex, Cursor und jeden anderen nativen Windows-Agenten kopieren Sie den manuellen MCP-Block aus [Andere Agenten](#other-agents) in die Windows-Konfig dieses Agenten. `connect` in WSL auszuführen ist nur dann sinnvoll, wenn der Ziel-Agent auch in derselben WSL-Umgebung installiert ist; es editiert nicht die Konfiguration eines Windows-Host-Agenten.
**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)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**Option B: Docker Desktop**
@@ -759,32 +897,33 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
**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
+npx -y @agentmemory/agentmemory@latest 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:
+**Diagnose unter Windows:** Wenn `npx -y @agentmemory/agentmemory@latest` 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 |
+| `The engine process started but the REST API never responded.` | Prüfen Sie, dass alle vier abgeleiteten Ports frei sind, verifizieren Sie, dass die gepinnte `iii.exe` am Leben blieb, starten Sie dann mit `--verbose` neu und prüfen Sie das erfasste Engine-stderr |
+| `Could not start iii-engine` | Weder `iii.exe` noch Docker ist installiert. Siehe Option A oder B oben |
| Port-Konflikt | `netstat -ano \| findstr :3111`, um zu sehen, was gebunden ist, dann beenden oder `--port ` verwenden |
| Docker-Fallback wird übersprungen, obwohl Docker installiert ist | Stellen Sie sicher, dass Docker Desktop tatsächlich läuft (Taskleisten-Icon) |
-> Hinweis: Die iii-**Engine** ist ein vorgebautes Binary, kein Cargo-Crate, versuche also nicht, sie per `cargo install` zu installieren. (Die iii-**SDKs** sind auf crates.io, npm und PyPI veröffentlicht, aber agentmemory benötigt sie nicht.) Unterstützte Engine-Installationsmethoden, alle auf v0.11.2 gepinnt: das vorgebaute v0.11.2-Binary oben, das Upstream-`sh`-Installationsskript **mit dem Versions-Pin** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) und das Docker-Image `iiidev/iii:0.11.2`. Ein bloßes `install.sh | sh` installiert die **neueste** Engine, die agentmemory nicht unterstützt; übergib immer `VERSION=0.11.2`. Am einfachsten von allen: Führe einfach `npx @agentmemory/agentmemory` aus, das die gepinnte Engine für dich nach `~/.agentmemory/bin` holt.
+> Hinweis: Die iii-**Engine** ist ein vorgebautes Binary, kein Cargo-Crate, versuchen Sie also nicht, sie per `cargo install` zu installieren. (Die iii-**SDKs** sind auf crates.io, npm und PyPI veröffentlicht, aber agentmemory benötigt sie nicht.) Unterstützte Engine-Installationsmethoden, alle auf v0.22.1 gepinnt: das vorgebaute Binary oben, agentmemorys automatischer Installationspfad für macOS/Linux (erfordert `curl`, POSIX-`sh` und `tar`) und das Docker-Image `iiidev/iii:0.22.1`. Ein bloßes Upstream-`install.sh | sh` installiert die neueste Engine, die agentmemory nicht unterstützt. Verwenden Sie `npx -y @agentmemory/agentmemory@latest`; unter macOS/Linux holt es die gepinnte Engine nach `~/.agentmemory/bin`.
---
-
Deployment
+
Deploy
Ein-Klick-Vorlagen für gemanagte Hosts. Jede liefert ein autonomes
Dockerfile aus, das `@agentmemory/agentmemory` aus npm bezieht und das
@@ -793,26 +932,26 @@ kopiert; kein vorgebautes agentmemory-Image erforderlich. 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.
+`/data`-Pfade verwendet, generiert das HMAC-Secret und senkt dann die
+Privilegien von `root` auf `node` via `gosu`, bevor er die agentmemory-CLI exec't.
-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.
+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):
+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
+- [`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,
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby-Plan mit Pauschalpreis,
Volume im Dashboard.
-- [`deploy/render`](./deploy/render/README.md): Blueprint-Fluss,
+- [`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
+- [`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.
@@ -848,7 +987,7 @@ Jeder KI-Coding-Agent kommt mit eingebautem Memory: Claude Code hat `MEMORY.md`,
|---|---|---|
| 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) |
+| 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 |
@@ -864,9 +1003,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -941,23 +1081,27 @@ Triple-Stream-Retrieval, das drei Signale kombiniert:
Verschmolzen mit Reciprocal Rank Fusion (RRF, k=60) und session-diversifiziert (max. 3 Ergebnisse pro Session).
-Hybrides Ranking gilt für den primären Recall-Pfad, nicht nur für `smart-search`: `mem::search` (hinter `memory_recall`) rankt durch dieselbe BM25 + Vector + Graph-Fusion, sobald der Vector-Index befüllt ist. Lesson-Recall läuft auf einem dedizierten In-Memory-BM25-Index, statt bei jeder Anfrage den ganzen Korpus zu scannen. Überholte Memory-Versionen sind von jedem Recall-Pfad ausgeschlossen; die Versionskette bewahrt ihre Historie.
+Wenn ein Vector-Index befüllt ist, verwendet `mem::search` (hinter `memory_recall`) den hybriden BM25-+-Vector-Ranker. Ohne Embeddings verwendet es BM25. `smart-search` kann zusätzlich strukturelle Graph-Treffer einbeziehen, wenn Graph-Daten existieren, auch im schlüssellosen Modus. Lesson-Recall läuft auf einem dedizierten In-Memory-BM25-Index, statt bei jeder Anfrage den ganzen Korpus zu scannen. Überholte Memory-Versionen sind von jedem Recall-Pfad ausgeschlossen; die Versionskette bewahrt ihre Historie.
+
+Vectors überleben einen Absturz oder Force-Kill. Der Vector-Index wird in Buckets gespeichert, höchstens alle `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 Minuten). Jeder dazwischen hinzugefügte oder entfernte Vector wird außerdem sofort in ein kleines Pending-Log im State-Store geschrieben, und der nächste Start spielt es ab, ohne den Embedding-Provider aufzurufen. Jedes erfolgreiche Speichern leert das Log. Dokumente, die nach dem Replay noch keinen Vector haben, werden im Hintergrund in Batches von `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) neu eingebettet, bis keine mehr übrig sind, und ein gestopptes Backfill wird beim nächsten Start fortgesetzt. `/agentmemory/status` und der Viewer zeigen die Größe des Pending-Logs und den Backfill-Status. Schlüssellose Installationen schreiben nichts.
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):
+Schlüssellose Installationen deaktivieren Vector-Embeddings: `mem::search` verwendet BM25, während `smart-search` zusätzlich bestehende strukturelle Graph-Daten verwenden kann. Um kostenlose semantische Embeddings auf dem eigenen Gerät zu aktivieren, fügen Sie dies zu `~/.agentmemory/.env` hinzu und starten Sie agentmemory neu:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+Die normale npm-Installation enthält die optionale `@huggingface/transformers`-Runtime. Die erste Embedding-Anfrage lädt `Xenova/all-MiniLM-L6-v2` herunter, braucht also Netzwerkzugang und kann länger dauern; nachfolgende Inferenz läuft on-device. Remote-Provider werden anhand ihrer Schlüssel automatisch erkannt, sofern `EMBEDDING_PROVIDER` sie nicht überschreibt.
+
| Provider | Modell | Kosten | Hinweise |
|---|---|---|---|
-| **Lokal (empfohlen)** | `all-MiniLM-L6-v2` | Kostenlos | Offline, +8 pp Recall gegenüber BM25 allein |
+| **Lokal (empfohlenes Opt-in)** | `all-MiniLM-L6-v2` | Kostenlos | On-device nach dem ersten Modell-Download, +8pp Recall gegenüber Nur-BM25 |
| 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 |
+| 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 |
@@ -968,11 +1112,11 @@ npm install @huggingface/transformers
54 Tools, 6 Resources, 3 Prompts und 17 Skills.
-> **MCP-Shim vs. voller Server:** Das veröffentlichte `@agentmemory/mcp`-Paket ist ein dünnes Shim. Es legt die volle 54-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`.
+> **MCP-Shim vs. voller Server:** Das veröffentlichte `@agentmemory/mcp`-Paket ist ein dünnes Shim. Es legt die volle 54-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 -y @agentmemory/agentmemory@latest` (oder den Docker-Stack) und setzen Sie `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
-Drei Tool-Oberflächen, von der kleinsten zur größten: `AGENTMEMORY_TOOLS=core` reduziert die Sichtbarkeit auf 8 Essentials (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); der Basis-Satz unten sind die 14 grundlegenden Tools der Registry; der Standard (`AGENTMEMORY_TOOLS=all`) legt alle 54 offen.
+Drei Tool-Oberflächen, von der kleinsten zur größten: `AGENTMEMORY_TOOLS=core` reduziert die Sichtbarkeit auf 8 essenzielle Tools (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); der Basis-Satz unten sind die 14 grundlegenden Tools der Registry; der Standard (`AGENTMEMORY_TOOLS=all`) legt alle 54 offen.
Basis-Tools (14)
@@ -1051,22 +1195,22 @@ Drei Tool-Oberflächen, von der kleinsten zur größten: `AGENTMEMORY_TOOLS=core
| Skill | `/recall` | Memory durchsuchen |
| Skill | `/remember` | Im Langzeit-Memory speichern |
| Skill | `/session-history` | Zusammenfassungen letzter Sessions |
-| Skill | `/forget` | Beobachtungen / Sessions löschen |
+| Skill | `/forget` | Beobachtungen/Sessions löschen |
-Die Tabelle zeigt die vier Kern-Skills. Der volle Satz umfasst 8 aufrufbare Skills plus 7 Referenz-Skills; siehe den Abschnitt Native Skills oben.
+Die Tabelle zeigt die vier Kern-Skills. Der volle Satz umfasst 9 aufrufbare Skills plus 8 Referenz-Skills; siehe den Abschnitt Native Skills oben.
### 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/agentmemory@latest 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):
+Die meisten Agenten (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1108,13 +1252,20 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Startet automatisch auf Port `3113`. Live-Beobachtungs-Stream mit Stream-Status-Indikator, ein zweispaltiger Session-Explorer (Liste neben einem fixierten Detail-Panel auf breiten Bildschirmen), Memory- und Lesson-Zeilen, die sich zum vollständigen gespeicherten Datensatz inklusive Roh-JSON und Ursprungs-Provenienz aufklappen, ein Knowledge Graph, der Knoten nach Typ clustert, solange Relationen spärlich sind, Session-Replay und ein Health-Dashboard.
+Startet automatisch auf Port `3113`. Der Viewer lädt beim Verbinden einen Snapshot (`GET /agentmemory/viewer/snapshot`) und wendet danach Live-Stream-Events an: neue Erinnerungen, Lessons, Beobachtungen, Audit-Einträge, Graph-Änderungen und Health-Updates erscheinen ohne Polling oder Seiten-Reloads. Die einzigen weiteren Requests sind die Aktionen, die Sie anklicken, „load more"-Seiten und Suchen. Wenn der Stream abreißt, zeigt der Viewer, wie alt seine Zahlen sind, verbindet sich mit Backoff neu und synchronisiert sich wieder aus einem Snapshot.
+
+- **12 Tabs in vier Gruppen** mit Live-Zählern, Deep-Links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), Tastenkürzeln und einem Mobile-Menü.
+- **Memories:** serverseitige Suche, Filter nach Projekt, Agent und Typ, ein Detail-Panel mit der Versionskette und einem Wort-Diff, Provenienz-Links, Kopierknöpfe für die ID, den MCP-Aufruf und einen curl-Befehl, Editieren (eine neue Version), Forget mit Bestätigung, Bulk-Forget und JSON-Export.
+- **Sessions:** eine inline eingebettete Beobachtungs-Timeline mit lesbarer Tool-Eingabe und -Ausgabe, Filtern und Paging sowie den Memories und Lessons, die jede Session erzeugt hat.
+- **Graph:** Suche, Knoten-Detail mit Relationen und Quellen, eine Legende, die sich nicht allein auf Farbe verlässt, und Zoom-Steuerung.
+- **Health:** die Live-Version von `GET /agentmemory/status`. Jedes Problem kommt mit seinem Fix, plus dem State-Backend, dem Index-Speicherstatus, dem Fortschritt der Graph-Provenienz-Kompaktierung und einem Konsolidierungs-Erklärer mit den echten Schwellenwerten.
+- **Audit-, Activity-, Profile-, Replay-, Lessons-, Actions- und Crystals**-Seiten, jede mit einem Leerzustand, der erklärt, was der Abschnitt ist, warum er leer ist und welcher Befehl ihn befüllt, sowie einem `?`-Glossar-Tooltip an jedem Begriff und jeder Zahl.
```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'`).
+Der Viewer-Server bindet sich standardmäßig an `127.0.0.1` und hängt das Server-Secret an, wenn er Requests an die REST API weiterleitet, braucht also kein eigenes Setup. Der per REST ausgelieferte `/agentmemory/viewer`-Endpunkt folgt den üblichen Bearer-Token-Regeln und leitet Browser ohne Token auf den Viewer-Port um. CSP-Header verwenden eine Skript-Nonce pro Response und deaktivieren Inline-Handler-Attribute (`script-src-attr 'none'`).
---
@@ -1132,22 +1283,20 @@ agentmemory liefert das umsonst, weil jeder Funktionsaufruf und jeder Trigger du
Workers-Seite: jeder verbundene Worker, einschließlich agentmemory selbst, mit PID, Funktionsanzahl, Runtime und last-seen.
-**Bereits installiert.** Die Console wird mit `iii` ausgeliefert; kein separater Installer.
+**Bereits installiert.** Die Console wird mit der gepinnten `iii`-Engine ausgeliefert (0.22+); nichts Separates zu installieren. Der erste Start lädt das Console-Binary neben die Engine herunter.
**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
+agentmemory console
```
-Dann `http://localhost:3114` öffnen. `--enable-flow` ergänzen für die experimentelle Architektur-Graph-Seite.
+Das führt die `iii console` der gepinnten Engine gegen die von agentmemory aufgelösten Ports aus (REST, Streams, Bridge) und liefert sie einen Port über dem Viewer aus, standardmäßig `http://localhost:3114`. `--console-port N` wählt einen anderen Port; `--port` und `--instance` wählen die agentmemory-Instanz auf dieselbe Weise wie bei `stop`; jedes andere Flag wird durchgereicht, zum Beispiel `--enable-flow` für die experimentelle Architektur-Graph-Seite.
-Engine-Endpunkte nur überschreiben, wenn Sie sie verschoben haben:
+Dasselbe von Hand, nützlich, wenn `agentmemory` nicht im PATH liegt:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1160,7 +1309,7 @@ iii console --port 3114 \
| **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 über Sessions, Memory-Slots, Lifecycle-Timer und den Embedding-Index; Werte direkt bearbeiten. |
+| **States** | KV-Browser mit vollem CRUD über Sessions, Memory-Slots, Lifecycle-Timer und den Embeddings-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. |
@@ -1176,7 +1325,7 @@ iii console --port 3114 \
**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.
+`iii-config.yaml` wird mit aktiviertem `iii-observability`-Worker ausgeliefert (`exporter: memory`, `sampling_ratio: 0.1`, Metriken + Logs). Keine zusätzliche Konfig nötig; in dem Moment, in dem agentmemory startet, emittiert jede Memory-Operation ein strukturiertes Log, das die Console lesen kann, und jede zehnte (`sampling_ratio: 0.1`) zusätzlich einen Trace-Span.
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.
@@ -1190,32 +1339,102 @@ agentmemory ist **bereits eine laufende [iii](https://iii.dev)-Instanz**. Drei P
Das bedeutet, ein weiterer Befehl erweitert agentmemory um eine komplett neue Fähigkeit.
-### agentmemory mit einem Befehl erweitern
+### agentmemory mit weiteren Workern 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
-```
+Die Builtins, die agentmemory braucht, sind bereits in `iii-config.yaml` und starten mit ihr: `iii-state` (KV), `iii-queue` (durable Retries für die Event-Subscriber), `iii-pubsub`, `iii-cron`, `iii-stream` und `iii-observability` (OTEL-Traces, Metriken und Logs bei jeder Funktion). Alles andere aus der [iii-Worker-Registry](https://workers.iii.dev) steckt in denselben Engine: Kopieren Sie `iii-config.yaml` nach `~/.agentmemory/iii-config.yaml` (die CLI bevorzugt diese Datei vor der mitgelieferten und rendert Ports und Datenpfade weiterhin in sie hinein), fügen Sie den Eintrag hinzu, installieren Sie die Worker-Runtime einmalig mit `~/.agentmemory/bin/iii update worker`, und starten Sie agentmemory neu.
-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.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | Was Sie zusätzlich zu agentmemory erhalten |
+| Worker | 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 |
+| [`database`](https://workers.iii.dev/workers/database) | SQL-gestützter State-Adapter, wenn Sie die In-Memory-KV-Voreinstellungen überwachsen |
+| [`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 |
| [`mcp`](https://workers.iii.dev/workers/mcp) | Zusätzliche MCP-Server neben dem von agentmemory aufstellen, die sich denselben Engine teilen |
+Auf Engine 0.22.x halten Sie für die obigen Builtins die `iii-`-präfixierten Namen; die unpräfixierten Einträge `http`, `state`, `queue`, `pubsub` und `cron` sind die eigenständigen Registry-Worker, zu denen agentmemory mit der 0.23-Migration wechselt.
+
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.
+### Engine-Konfiguration und Bind-Adresse
+
+`agentmemory start` liest die Engine-Konfig aus der ersten vorhandenen Datei: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` im aktuellen Verzeichnis, `~/.agentmemory/iii-config.yaml`, dann die mitgelieferte `iii-config.yaml`. Bei jedem Start rendert es diese Datei (Datenpfade, Ports, State-Backend) nach `~/.agentmemory/data/iii-config.runtime.yaml` und startet die Engine mit der gerenderten Kopie, editieren Sie also die Quelldatei, nicht die gerenderte. Die `host:`-Werte der Quelldatei werden so übernommen, wie sie geschrieben sind.
+
+Die mitgelieferte `iii-config.yaml` bindet absichtlich `127.0.0.1`, und dieser Standard gilt auch innerhalb eines Containers. Eine in einem Container gestartete CLI lauscht auf dem Loopback des Containers, sodass veröffentlichte Ports nichts erreichen. Um eine containerisierte CLI über veröffentlichte Ports zu bedienen, setzen Sie `AGENTMEMORY_III_CONFIG` auf eine Konfig, die `0.0.0.0` bindet. Die mitgelieferte `iii-config.docker.yaml` ist eine solche: Sie bindet `iii-http`, `iii-stream` und den Engine-Port an `0.0.0.0` und speichert den State unter `/data`, mounten Sie dort also ein schreibbares Volume. Halten Sie `AGENTMEMORY_SECRET` gesetzt und veröffentlichen Sie nur die Ports, die Sie brauchen, auf `127.0.0.1` oder hinter einem Proxy, dem Sie vertrauen.
+
+Die `docker-compose.yml` dieses Repos geht nicht über die Konfig-Suche der CLI: Sie mountet `iii-config.docker.yaml` nach `/app/config.yaml`, und der `iii-engine`-Container startet mit `--config /app/config.yaml`. Die Ein-Klick-[Deploy-Vorlagen](../deploy/) schreiben in ihren Entrypoints ihre eigene `0.0.0.0`-Konfig.
+
+### Storage-Backend: file (Standard) vs. redis
+
+`iii-state` und `iii-stream` greifen standardmäßig auf den mitgelieferten dateibasierten KV-Store der iii-engine zurück: eine JSON-Datei pro Scope, im Speicher des Engine-Prozesses gehalten und nach einem Timer auf die Festplatte zurückgeschrieben. Das ist der richtige Standard für eine lokale Einzelbenutzer-Installation; ein gemeinsam genutzter Daemon mit mehreren gleichzeitigen Schreibern erhält von Redis echte Per-Key-Writes, auf Kosten eines Netzwerk-Roundtrips pro Operation (jeder `state::*`-Aufruf serialisiert weiterhin auf einer Redis-Verbindung, das tauscht also das Lock des File-Stores gegen eine Socket-Verbindung, nicht gegen Parallelität).
+
+Setzen Sie `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`), um beide Worker auf den eingebauten `redis`-Adapter der iii-engine umzustellen, der jeden Schlüssel als Redis-Hash-Feld speichert (`HSET`) statt bei jedem Write einen ganzen Scope umzuschreiben:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` ist standardmäßig `file`; lassen Sie es ungesetzt, bleibt das heutige Verhalten unverändert, und ein nicht erkannter Wert (alles außer `file` oder `redis`) ist ein Startfehler statt eines stillen Fallbacks. `/agentmemory/status` und die Health-Seite des Viewers (die Zeile State Store) melden, welches Backend aktiv ist und ob es antwortet, niemals die URL.
+
+**Nur reines `redis://`.** Die gepinnte Engine (0.22.1) baut ihren Redis-Client ohne TLS-Unterstützung, daher schlägt eine `rediss://`-URL fehl (die meisten gemanagten Redis-Angebote, etwa Upstash, Redis Cloud und ElastiCache mit Transit-Verschlüsselung, sind standardmäßig TLS-only). Die Verbindung ist unverschlüsselt, daher laufen das Redis-Passwort und jedes gespeicherte Memory im Klartext über die Leitung: Zeigen Sie auf ein lokales Redis oder eines in einem privaten Netzwerk, dem Sie vertrauen. Für jedes andere Redis betreiben Sie einen verschlüsselten Tunnel (stunnel, SSH oder ein VPN) auf dem agentmemory-Host, sodass die reine `redis://`-Strecke auf diesem Host bleibt und die Upstream-Verbindung des Tunnels verschlüsselt und authentifiziert ist. Enthält ein Redis-Passwort ein einfaches Anführungszeichen, kodieren Sie es per Prozent (`%27`); die Engine expandiert die URL in ihre YAML-Konfig, bevor sie geparst wird.
+
+**Ein Redis-Server pro `--instance`.** Die Redis-Schlüsselpräfixe der Engine (`state:`, `stream::`) sind fest, daher überschreiben zwei auf dieselbe Datenbank gerichtete agentmemory-Instanzen (`--instance 1`, `--instance 2`, ...) gegenseitig ihre Daten. Ein separater Datenbankindex (`redis://localhost:6379/1`) hält die gespeicherten Daten getrennt, aber die Engine leitet Live-Viewer-Events über einen einzigen Redis-Pub/Sub-Kanal (`stream::events`) weiter, und Redis-Pub/Sub ignoriert den Datenbankindex, sodass der Viewer jeder Instanz trotzdem die Live-Events der anderen zeigen würde. Geben Sie jeder Instanz ihren eigenen Redis-Server (oder Port), wenn Sie mehr als eine betreiben.
+
+**Was gleich bleibt, und was sich unterscheidet.** Jede agentmemory-Funktion funktioniert auf Redis: Sessions, Beobachtungen, Memories (remember, supersede, evolve, forget), Suche und die Index-Buckets, Lessons, der Graph, das Audit-Log mit seinen Monats-Scopes, Export und Import, Governance-Deletes, Konsolidierungsstatus, der Viewer-Snapshot mit seinem Live-Stream und der Health-Monitor. Die Engine speichert jeden Scope als einen Redis-Hash (`HSET`/`HGET`/`HGETALL`) und feuert dieselben State-Trigger wie der File-Store. Drei Engine-Unterschiede werden innerhalb von agentmemory behandelt:
+
+- Redis gibt die Datensätze eines Scopes in keiner festen Reihenfolge zurück. agentmemory sortiert sie älteste zuerst (nach dem Erstellungszeitpunkt in der Datensatz-ID, dann nach ihrem Zeitstempel), sodass Listen, Paging und Export-Chunks in derselben Reihenfolge zurückkommen wie beim File-Store.
+- Die Engine wendet partielle Updates auf Redis in einem Lua-Skript an, das leere Arrays in leere Objekte verwandelt. agentmemory wendet diese Updates selbst an (lesen, ändern, unter einem Per-Key-Lock schreiben) auf Redis, sodass Felder wie `tags: []` Arrays bleiben.
+- Die Legacy-Audit-Log-Prüfung liest den alten Scope aus Redis, statt auf der Festplatte nach der Datei des File-Stores zu suchen.
+
+Ein Unterschied braucht Ihr Eingreifen: **nach einem Redis-Neustart stellt die Engine das Weiterleiten von Live-Events** an den Viewer ein, bis agentmemory neu startet. Daten werden weiterhin normal gespeichert und gelesen. Der Health-Monitor sendet alle 30 Sekunden ein Testereignis über Redis; kommt es nicht zurück, zeigen `/agentmemory/status` und die Health-Seite des Viewers „Live-Updates erreichen den Viewer nicht" mit dem Fix: agentmemory neu starten. Ist Redis down, zeigt der Statusbericht „Der State Store antwortet nicht" und wie man das prüft (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Das Auflisten eines sehr großen Scopes liest den gesamten Hash in einem `HGETALL`, denselben Aufwand, den der File-Store hätte, ihn im Speicher zu halten.
+
+**Empfohlene Redis-Einstellungen.** Die Standard-Snapshot-Policy `save 3600 1 300 100 60 10000` kann bei einem Absturz Minuten an Writes verlieren, schlechter als das 5-Sekunden-Flush-Fenster des File-Stores. Setzen Sie `appendonly yes` für alles, dessen Verlust Sie stören würde. Setzen Sie `maxmemory-policy noeviction`; `allkeys-lru` oder Ähnliches verwirft stillschweigend Erinnerungen, sobald Redis sein Speicherlimit erreicht.
+
+Ein nativer (Nicht-Docker-)Start und jede Ein-Klick-[Deploy-Vorlage](../deploy/) (sie überschreiben die mitgelieferte `iii-config.yaml` und starten nativ) lesen `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` und rendern sie in die gestartete `iii-config`. Die URL selbst wird nie in diese gerenderte Datei geschrieben, nur eine `${AGENTMEMORY_REDIS_URL}`-Referenz, die der Engine-Prozess beim Booten aus seiner eigenen Umgebung expandiert. Nur der eigene Docker-Compose-Pfad dieses Repos (`AGENTMEMORY_USE_DOCKER=1`, oder das Fortsetzen einer bereits so gestarteten Engine) mountet `iii-config.docker.yaml` read-only und rendert nie; `agentmemory start` warnt, wenn es diese Kombination erkennt. Ändern Sie diese Datei von Hand, nach derselben `name: redis` / `config: redis_url: ...`-Form, die in den Worker-Docs von [iii-state](https://workers.iii.dev/workers/iii-state) und [iii-stream](https://workers.iii.dev/workers/iii-stream) gezeigt wird, und lassen Sie `redis_url` auf ein vom Container erreichbares Redis zeigen. `docker-compose.yml` gibt `AGENTMEMORY_REDIS_URL` in den Engine-Container weiter, sodass `redis_url: '${AGENTMEMORY_REDIS_URL}'` dort funktioniert und die URL aus der gemounteten Datei heraushält.
+
+Die gerenderte Konfig hält die URL aus `~/.agentmemory/data/iii-config.runtime.yaml` heraus, aber der eigene Konfigurations-Worker der Engine persistiert den *expandierten* Wert trotzdem nach `~/.agentmemory/config/iii-state.yaml` und `iii-stream.yaml`, sobald sie bootet (die `${VAR}`-Expansion der iii-engine passiert, bevor dieser Worker seinen Seed speichert, und er speichert den aufgelösten Wert, nicht die Referenz). Behandeln Sie dieses Verzeichnis so, als enthielte es ein Credential: `chmod 700 ~/.agentmemory` auf jedem gemeinsam genutzten Host, und bevorzugen Sie einen auf das von agentmemory Benötigte beschränkten Redis-ACL-Benutzer vor den Admin-Credentials der Datenbank.
+
+**Migration ist nicht automatisch.** Das Umschalten von `AGENTMEMORY_STATE_BACKEND` startet auf beiden Seiten mit einem leeren Store; nichts kopiert bestehende Daten von File nach Redis oder zurück. Exportieren Sie aus dem Backend, das Sie verlassen, und importieren Sie in das, zu dem Sie wechseln. Das läuft identisch unter bash und zsh (auch `bash -u`). Ein Array wie `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` tut das nicht: zsh behält den Header als ein fehlgeformtes Wort, während bash ihn in zwei aufteilt, sodass beide Requests 401 liefern, sobald `AGENTMEMORY_SECRET` gesetzt ist:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` akzeptiert außerdem `?maxSessions=` und `?offset=`, um einen großen Korpus über mehrere Aufrufe zu zerlegen; `strategy` beim Import ist `merge` (standardmäßig sicher), `replace` oder `skip`.
+
### Was iii ersetzt
| Traditioneller Stack | agentmemory verwendet |
@@ -1227,7 +1446,7 @@ Volle Registry: [workers.iii.dev](https://workers.iii.dev). Jeder Worker dort ko
| Prometheus / Grafana | iii OTEL + Health-Monitor |
| Eigene Plugin-Systeme | `iii worker add ` |
-**182 Quelldateien · ~41.600 LOC · 1.674 Tests · 264 Funktionen · 50 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+**225 Quelldateien · ~54,000 LOC · 2,600+ Tests · 312 Funktionen · 66 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
---
@@ -1235,17 +1454,17 @@ Volle Registry: [workers.iii.dev](https://workers.iii.dev). Jeder Worker dort ko
### 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.
+agentmemory erkennt Provider automatisch aus Ihrer Umgebung. Ein Provider macht LLM-gestützte Operationen verfügbar, aber die Provider-Konfiguration allein aktiviert noch nicht die LLM-geschriebene Beobachtungs-Kompression. Dieser Pfad erfordert sowohl einen Provider als auch `AGENTMEMORY_AUTO_COMPRESS=true`.
| 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. |
+| **No-op (Standard)** | Keine Konfig nötig | LLM-gestütztes Compress/Summarize ist deaktiviert. Synthetische Kompression und BM25-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 |
| OpenAI API | `OPENAI_API_KEY` | Standard `gpt-5.6-luna`, Override per `OPENAI_MODEL` |
-| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) oder `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alles, was OpenAI-API-kompatibel ist. Null Kosten, läuft auf Ihrer Hardware. Siehe [Lokale Modelle](#lokale-modelle-ollama--lm-studio--vllm) unten. |
+| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) oder `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alles, was OpenAI-API-kompatibel ist. Null Kosten, läuft auf Ihrer Hardware. Siehe [Lokale Modelle](#local-models-ollama--lm-studio--vllm) unten. |
| 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, daher nicht mehr Standard. |
### Lokale Modelle (Ollama / LM Studio / vLLM)
@@ -1283,30 +1502,30 @@ OPENAI_MODEL=qwen3-8b # match the model name from LM St
| Modell | Größe | Warum |
|-------|------|-----|
-| `qwen3:8b` | ~5,2 GB | Ausgewogener Standard auf einer 16-GB-Maschine; stark bei Extraktion und tool-förmigem Text |
-| `qwen3:4b` | ~2,6 GB | Kleinste vernünftige Option; gut für Kompression, schwächer bei Graph-Extraktion |
-| `qwen3-coder:30b` | ~19 GB | Beste lokale Wahl für codelastige Sessions (30B MoE, 3,3B aktiv) auf 24-32-GB-Hardware |
+| `qwen3:8b` | ~5.2 GB | Ausgewogener Standard auf einer 16-GB-Maschine; stark bei Extraktion und tool-förmigem Text |
+| `qwen3:4b` | ~2.6 GB | Kleinste vernünftige Option; gut für Kompression, schwächer bei Graph-Extraktion |
+| `qwen3-coder:30b` | ~19 GB | Beste lokale Wahl für codelastige Sessions (30B MoE, 3.3B aktiv) auf 24-32-GB-Hardware |
| `gpt-oss:20b` | ~14 GB | Starkes Allzweckmodell, das in 16 GB RAM passt |
-| `deepseek-r1:8b` | ~5,2 GB | Reasoning-Distill; langsamer, aber sauberere Extraktionen |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning-Distill; langsamer, aber sauberere Extraktionen |
Qwen-3-Modelle denken standardmäßig und können das ganze Token-Budget für Reasoning verbrennen, bevor irgendeine Ausgabe kommt. Setzen Sie `AGENTMEMORY_LLM_NOTHINK=1`, um `/no_think` an Graph-Extraktions-Prompts anzuhängen, und erhöhen Sie `MAX_TOKENS` (16384 funktioniert), falls Extraktionen leer zurückkommen.
Modelle der Reasoning-Klasse (`o1`-artig mit ``-Blöcken) können leeren `content` mit einem `reasoning`-Feld zurückgeben, das Ihr lokaler Server womöglich nicht durchreicht. Wenn Extraktionen leer zurückkommen, wechseln Sie zuerst zu einem Nicht-Reasoning-Modell. Die Env-Variable `OPENAI_REASONING_EFFORT=none` kann das Denken auch auf Ollama-Cloud-Thinking-Modellen deaktivieren, die das OpenAI-Reasoning-Schema spiegeln.
-Lokale Embeddings sind über `@huggingface/transformers` von Haus aus dabei: `EMBEDDING_PROVIDER=local` (Standard) liefert `Xenova/all-MiniLM-L6-v2` (384-dim) vollständig on-device. Keine zusätzliche Konfig nötig.
+Lokale Embeddings werden als optionale Abhängigkeit ausgeliefert, sind aber standardmäßig nicht aktiviert. Setzen Sie `EMBEDDING_PROVIDER=local`, um `Xenova/all-MiniLM-L6-v2` (384-dim) zu aktivieren. Die erste Embedding-Anfrage lädt das Modell herunter; die Inferenz läuft danach on-device. Ohne diese Einstellung oder einen Remote-Embedding-Schlüssel bleiben Vectors deaktiviert, `mem::search` verwendet BM25, und `smart-search` kann weiterhin bestehende Graph-Treffer hinzufügen.
### 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.
+Wenn LLM-geschriebene Hintergrund-Kompression sowohl mit einem Provider als auch mit `AGENTMEMORY_AUTO_COMPRESS=true` aktiviert ist, läuft sie 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-flash-0731` | 0,07 $ | 0,14 $ | ~0,07 $ (est.) | Neuestes DeepSeek; günstigste empfohlene Wahl für Kompressions-Workloads. |
-| Empfohlen | `deepseek/deepseek-v4-pro` | 0,435 $ | 0,87 $ | ~0,46 $ | Solide Kompressions-/Summarize-Qualität zu ~10× geringeren Kosten als Sonnet. |
-| Empfohlen | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Starkes Code-Reasoning, wenn Ihre Sessions stark codelastig sind. |
-| Premium | `anthropic/claude-sonnet-5` | 3,00 $ | 15,00 $ | ~5,02 $ (est.) | Gleicher Listenpreis wie der gemessene Sonnet-4.6-Lauf; Einführungspreis 2 $/10 $ bis 2026-08-31. |
-| Premium | `openai/gpt-5.6-sol` | 5,00 $ | 30,00 $ | ~9 $ (est.) | Flaggschiff-Stufe; teuer für dauerhafte Hintergrundarbeit. |
-| Vermeiden | `anthropic/claude-opus-5` | 5,00 $ | 25,00 $ | ~8,40 $ (est.) | Modell der Flaggschiff-Klasse; Überausgabe für Kompression. |
+| Empfohlen | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Neuestes DeepSeek; günstigste empfohlene Wahl für Kompressions-Workloads. |
+| Empfohlen | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solide Kompressions-/Summarize-Qualität zu ~10× geringeren Kosten als Sonnet. |
+| Empfohlen | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Starkes Code-Reasoning, wenn Ihre Sessions stark codelastig sind. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Gleicher Listenpreis wie der gemessene Sonnet-4.6-Lauf; Einführungspreis $2/$10 bis 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flaggschiff-Stufe; teuer für dauerhafte Hintergrundarbeit. |
+| Vermeiden | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modell der Flaggschiff-Klasse; Überausgabe für Kompression. |
Gemessene Zeilen stammen aus dem erfassten Lauf; (est.)-Zeilen skalieren denselben Token-Mix mit dem Listenpreis des jeweiligen Modells.
@@ -1338,7 +1557,7 @@ Was getaggt wird, wenn `AGENT_ID` gesetzt ist: `Session.agentId`, `RawObservatio
Was im Isolated-Modus gefiltert wird: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Jeder Endpunkt akzeptiert `?agentId=` 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. Das MCP-Tool `memory_save` legt dasselbe `agentId`-Feld offen, der Standalone-stdio-Server reicht sowohl `agentId` als auch `project` weiter, und gespeicherte Memories tragen `agentId` in den Suchindex, sodass agent-gescopte Suche Memories ebenso abdeckt wie Beobachtungen.
+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 einzigen Serverprozess routen. Das MCP-Tool `memory_save` legt dasselbe `agentId`-Feld offen, der Standalone-stdio-Server reicht sowohl `agentId` als auch `project` weiter, und gespeicherte Memories tragen `agentId` in den Suchindex, sodass agent-gescopte Suche Memories ebenso abdeckt wie Beobachtungen.
Wenn `AGENT_ID` nicht gesetzt ist, bleibt Memory unscoped (Legacy-Verhalten, keine Tags, keine Filter).
@@ -1349,9 +1568,13 @@ agentmemory + iii-engine binden standardmäßig vier Ports. Wenn ein Neustart mi
| 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`) |
+| `3112` | iii-engine | Interner Streams-Worker (von agentmemory + Viewer verwendet) | `III_STREAM_PORT` (bevorzugt) oder legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Echtzeit-Viewer (`http://localhost:3113`) | `III_VIEWER_PORT` oder `AGENTMEMORY_VIEWER_URL` für die gemeldete URL |
+| `49134` | iii-engine | WebSocket; Worker registrieren sich hier, OTel-Telemetrie fließt darüber | `III_ENGINE_PORT` oder `III_ENGINE_URL` |
+
+`--port ` ändert den REST-Anker und leitet Streams `N+1`, Viewer `N+2` und den Engine-WebSocket `N+46023` nur dort ab, wo der entsprechende explizite Port oder die URL oben ungesetzt ist. Es erzeugt keinen isolierten Lifecycle-Namespace. Verwenden Sie `--instance 1` für einen zweiten Daemon; er nutzt den Anker 3211, standardmäßig `3211/3212/3213/49234`, und erhält ein separates `instance-1`-Daten- und Lifecycle-Verzeichnis. Instanzen 1 bis 50 folgen demselben Muster.
+
+Die gepinnte Engine startet mit `--no-update-check` (keine Update- oder Security-Advisory-Abfragen gegen GitHub beim Booten) und mit deaktivierter anonymer Nutzungstelemetrie von iii: agentmemory setzt `III_TELEMETRY_ENABLED=false` für die Engine, die es spawnt, sofern Sie die Variable nicht selbst exportieren, und die mitgelieferte Compose-Datei macht dasselbe.
Aufräumen veralteter Prozesse, wenn Ports nach einem abgestürzten Lauf gebunden bleiben:
@@ -1366,7 +1589,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` räumt sowohl den Worker als auch das Engine-Pidfile bei einem geordneten Shutdown sauber auf. Im Docker-Modus baut es nur agentmemorys eigene Compose-Services ab und räumt den nativen Worker vor dem Docker-Teardown auf; die CLI weigert sich außerdem, Docker- oder VM-Port-Inhaber (Docker-Backend, vpnkit, colima) als native Engine zu adoptieren oder zu signalisieren, sofern nicht `--force` übergeben wird. Das manuelle Cleanup oben ist nur für den Post-Crash-Fall nötig, in dem kein Pidfile zurückbleibt.
+`agentmemory stop` räumt sowohl den Worker als auch das Engine-Pidfile bei einem geordneten nativen Shutdown sauber auf. Im Docker-Modus leert es den nativen Worker, stoppt genau den validierten Engine-Container und bewahrt sowohl den Container als auch sein `/data`-Mount für einen verlustfreien Neustart; der nächste Start validiert und setzt denselben Container fort. Docker-gestütztes Deinstallieren erfordert `agentmemory remove --keep-data`: Es entfernt gemeinsam genutzte, von agentmemory verwaltete Dateien und bewahrt dabei den validierten Container, sein Daten-Mount und den Lifecycle-Eintrag, der zu ihrer Wiederherstellung nötig ist. Destruktives Löschen von Docker-Daten wird bewusst dem Betreiber nach einem Backup überlassen. Die CLI weigert sich außerdem, Docker- oder VM-Port-Inhaber (Docker-Backend, vpnkit, colima) als native Engine zu adoptieren oder zu signalisieren, sofern nicht `--force` übergeben wird. Das manuelle Cleanup oben ist nur für den Post-Crash-Fall nötig, in dem kein Pidfile zurückbleibt.
### Konfigurationsdatei
@@ -1388,11 +1611,13 @@ AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-Aktivieren Sie Graph- oder Konsolidierungs-Features in derselben Datei, falls gewünscht:
+LLM-geschriebene Beobachtungs-Kompression erfordert beide Zeilen: Zugang zu einem LLM-Provider (einschließlich dieses expliziten Abonnement-Fallbacks) und `AGENTMEMORY_AUTO_COMPRESS=true`. Ein Provider allein lässt den standardmäßigen synthetischen Kompressionspfad unangetastet.
+
+Konsolidierung (Graph-Knoten, Lessons, Crystals) ist standardmäßig aktiv, sobald ein LLM-Provider konfiguriert ist. Deaktivieren Sie das explizit mit `CONSOLIDATION_ENABLED=false`, wenn Sie LLM-freien Betrieb wollen. Graph-Extraktion ist ein separates Flag:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Umgebungsvariablen
@@ -1434,13 +1659,15 @@ CONSOLIDATION_ENABLED=true
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1458,14 +1685,20 @@ CONSOLIDATION_ENABLED=true
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1513,6 +1746,36 @@ CONSOLIDATION_ENABLED=true
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1526,7 +1789,19 @@ CONSOLIDATION_ENABLED=true
-124 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer `, wenn `AGENTMEMORY_SECRET` gesetzt ist, und Mesh-Sync-Endpunkte erfordern `AGENTMEMORY_SECRET` auf beiden Peers.
+138 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer `, und Mesh-Sync-Endpunkte erfordern ein explizit gesetztes `AGENTMEMORY_SECRET` auf beiden Peers.
+
+**Authentifizierung ist standardmäßig aktiv.** Wenn `AGENTMEMORY_SECRET` nicht gesetzt ist (weder in der Shell noch in `~/.agentmemory/.env`), erzeugt der Server beim ersten Start ein zufälliges Secret und speichert es in `~/.agentmemory/secret` mit dem Modus `0600`. Jeder mitgelieferte Client liest es von dort, wenn er mit einem lokalen Server spricht: die CLI, der Viewer, die Hooks unter `plugin/scripts`, der MCP-Server und das `@agentmemory/mcp`-Shim, die von `agentmemory connect` geschriebenen Konfigs sowie die mitgelieferten Integrationen für OpenCode, Pi, OpenClaw, Hermes und den Filesystem-Watcher. Das gespeicherte Secret wird nur an Loopback-URLs gesendet (`localhost`, `127.0.0.0/8`, `::1`). Ein explizites `AGENTMEMORY_SECRET` gewinnt immer, und Remote-Clients benötigen es trotzdem gesetzt. Docker und die `deploy/`-Entrypoints erzeugen und exportieren bereits ihr eigenes Secret. Um die API von Hand aufzurufen:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Request-Regeln für Writes.** `POST`-, `PUT`-, `PATCH`- und `DELETE`-Requests an die REST API und den Viewer müssen `Content-Type: application/json` senden (ein `charset`-Parameter ist in Ordnung), wann immer sie einen Body tragen, und ein `Origin`-Header muss, wenn vorhanden, ein Loopback-Origin für den konfigurierten REST- oder Viewer-Port sein oder in `VIEWER_ALLOWED_ORIGINS` aufgeführt sein (kommasepariert, z. B. `https://memory.example.com`). Clients, die keinen `Origin`-Header senden (CLI, Hooks, MCP, curl, Server-zu-Server), sind nicht betroffen. Der Viewer akzeptiert außerdem seinen eigenen Origin.
+
+**Dateipfade.** Endpunkte, die Dateien lesen oder schreiben (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), akzeptieren nur Pfade unter `~/.agentmemory`, dem Instanz-Datenverzeichnis oder einem in `AGENTMEMORY_IMPORT_ROOT` aufgeführten Verzeichnis (mehrere getrennt mit `:`, unter Windows mit `;`). `/replay/import-jsonl` akzeptiert außerdem seinen Standard `~/.claude/projects`. `/obsidian/export` bleibt innerhalb von `AGENTMEMORY_EXPORT_ROOT` und `/migrate` innerhalb von `~/.agentmemory`. Symlinks werden vor jeder Prüfung aufgelöst.
+
+**Secret-Bereinigung.** API-Schlüssel, Bearer-Tokens, PEM-Private-Key-Blöcke und in URLs eingebettete Credentials (`scheme://user:password@host`) werden vor dem Speichern von Text auf jedem Write-Pfad geschwärzt: Beobachtungen, Remember, Evolve, Slots, Lessons, Actions, Sketches, Signals, Checkpoints, Imports, JSONL-Replay, Mesh-Sync, Team-Shares, Kompressions- und Summary-Ausgabe, Crystals und Graph-Knoten.
Wichtige Endpunkte
@@ -1534,9 +1809,14 @@ CONSOLIDATION_ENABLED=true
| Methode | Pfad | Beschreibung |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health-Check (immer öffentlich) |
+| `GET` | `/agentmemory/status` | Was nicht stimmt und wie man es behebt (HTML für Browser, sonst JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Alles, was der Viewer zeigt, in einer Antwort |
| `POST` | `/agentmemory/session/start` | Session starten + Kontext holen |
| `POST` | `/agentmemory/session/end` | Session beenden |
-| `POST` | `/agentmemory/observe` | Beobachtung erfassen |
+| `POST` | `/agentmemory/observe` | Beobachtung erfassen (siehe Capture-Delivery unten) |
+| `GET` | `/agentmemory/capture` | Capture-Inbox, Dead Letters und Offline-Spool |
+| `POST` | `/agentmemory/capture/retry` | Dead-Letter-Captures erneut versuchen |
+| `POST` | `/agentmemory/capture/drain` | Den lokalen Offline-Spool jetzt senden |
| `POST` | `/agentmemory/smart-search` | Hybride Suche |
| `POST` | `/agentmemory/context` | Kontext erzeugen |
| `POST` | `/agentmemory/remember` | In Langzeit-Memory speichern |
@@ -1546,6 +1826,7 @@ CONSOLIDATION_ENABLED=true
| `GET` | `/agentmemory/export` | Alle Daten exportieren |
| `POST` | `/agentmemory/import` | Aus JSON importieren |
| `POST` | `/agentmemory/graph/query` | Knowledge-Graph-Anfrage |
+| `POST` | `/agentmemory/graph/compact` | Übergroße Graph-Provenienz trimmen |
| `POST` | `/agentmemory/team/share` | Mit Team teilen |
| `GET` | `/agentmemory/audit` | Audit-Trail |
@@ -1553,6 +1834,35 @@ Volle Endpunktliste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+**Capture-Delivery.** Hooks senden jede Beobachtung einmal an `POST /agentmemory/observe` mit einer `eventId`. Das ist die eigene ID des Hosts für den Aufruf, wenn die Payload eine hat (zum Beispiel Claude Codes `tool_use_id`), sonst ein Hash aus Session, Hook-Typ, Tool-Name, Eingabe, Ausgabe und Host-Zeitstempel. Der Server schreibt das Event in eine Capture-Inbox im State-Store, speichert die Beobachtung und entfernt dann den Inbox-Eintrag. Der Statuscode sagt, was passiert ist:
+
+| Status | `status`-Feld | Bedeutung |
+|---|---|---|
+| `201` | `accepted` | Gespeichert. `observationId` ist die neue Beobachtung. |
+| `202` | `accepted` (`state: "retrying"`) | Akzeptiert, aber das Speichern schlug fehl. Der Server versucht es erneut, auch nach einem Neustart. |
+| `200` | `duplicate` | Diese `eventId` wurde bereits akzeptiert. `observationId` ist die bestehende Beobachtung; nichts Neues wird gespeichert. |
+| `400` / `422` | `rejected` | Ungültige Payload, oder das Speichern ist endgültig fehlgeschlagen (das Event wird als Dead Letter behalten). |
+| `503` | `rejected` (`retryable: true`) | Die Inbox ist voll (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks spoolen das Event und senden es später. |
+
+Fehlgeschlagene Events werden alle `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) mit verdoppelndem Backoff wiederholt, bis zu `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Events, die weiterhin fehlschlagen, bleiben als Dead Letters in der Inbox, werden auf `/agentmemory/status` und der Health-Seite des Viewers aufgeführt und können mit `POST /agentmemory/capture/retry` erneut versucht werden (`{"eventId": "..."}` oder `{"all": true}`). Akzeptierte Event-IDs werden für `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 Stunden, höchstens `AGENTMEMORY_CAPTURE_EVENTS_MAX` IDs) gemerkt, sodass ein nach einem Timeout oder Neustart wiederholter Hook einmal gespeichert wird, während zwei separate Tool-Aufrufe mit ihren eigenen Host-IDs zweimal gespeichert werden, auch wenn ihr Inhalt identisch ist. Wenn eine Beobachtung gelöscht wird (Forget, Session-Delete, Eviction, Auto-Forget oder ein Import, der den Store ersetzt), wird ihr Event als gelöscht markiert, bevor die Beobachtung entfernt wird, sodass ein Replay dieses Events innerhalb desselben Fensters als Duplikat beantwortet wird und nichts speichert. Der State-Store schreibt alle 2 Sekunden auf die Festplatte, daher kann eine beantwortete Event noch einen Moment lang nur im Speicher stehen. Um das abzudecken, trägt jede `2xx`-Antwort zusätzlich die `bootId` des Servers (neu bei jedem Start), `acceptedAt` und `durableAfterMs` (das Speicherintervall plus 1,5 s beim File-Store, 1,5 s bei Redis, wo Persistenz die Einstellung des Betreibers ist). Hooks behalten das Event im lokalen Spool, bis dieses Fenster vergangen ist, und löschen es bei einem späteren Aufruf ohne einen weiteren Request. Hat sich die `bootId` bis dahin geändert, ist der Server neu gestartet, daher sendet der Hook das Event erneut mit derselben `eventId`; ein Event, das die Festplatte tatsächlich erreicht hat, wird nicht doppelt gespeichert. Der Server sendet solche Events auch selbst beim Start und bei jedem Retry-Intervall, sodass ein Neustart nichts verliert, selbst wenn danach kein Hook läuft. Ältere Hooks ignorieren die zusätzlichen Felder, und neue Hooks gegen einen älteren Server verwerfen das Event bei `2xx` wie zuvor.
+
+Wenn der Server down ist, nicht rechtzeitig antwortet oder einen 5xx zurückgibt, hängt der Hook die Beobachtung an eine lokale Spool-Datei an, `/capture-spool/-.jsonl` (den Ordner mit `AGENTMEMORY_CAPTURE_SPOOL_DIR` überschreiben). Die Datei ist privat für Ihren Benutzer (Modus 600), Secrets werden auf dieselbe Weise geschwärzt wie beim Server, sie fasst höchstens `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) und verwirft Einträge, die älter als `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168) sind. Ist sie voll, werden neue Einträge verworfen und gezählt, und `/agentmemory/status` meldet das. Der Hook beendet sich innerhalb seines Zeitlimits weiterhin mit 0 und fügt keinen Request hinzu, wenn der Server gesund ist. Der Spool wird beim nächsten Start gesendet und vom ersten Hook, der den Server wieder erreicht, in einem Hintergrundprozess, sodass der Agent nicht wartet. Event-IDs machen das sicher: Eine Beobachtung, die vor einem Timeout tatsächlich angekommen ist, wird nicht doppelt gespeichert. `npx @agentmemory/agentmemory capture` zeigt den Spool und die Server-Inbox, `--drain` sendet den Spool jetzt, und `GET /agentmemory/capture` liefert dasselbe als JSON. Setzen Sie `AGENTMEMORY_CAPTURE_SPOOL=false`, um den Spool abzuschalten.
+
+**Graph-Provenienz kompaktieren.** Jeder Knowledge-Graph-Knoten und jede Kante behält die IDs der neuesten 32 Beobachtungen, aus denen sie stammt. Vor diesem Cap geschriebene Stores können Tausende von IDs pro heißem Knoten enthalten, was die Graph-Suche und den Viewer langsam macht oder den Worker zum Absturz bringt. agentmemory behebt das selbst: Beim ersten Start nach einem Upgrade trimmt es jeden Knoten, jede Kante, jede überholte Kante (die temporale Graph-Historie) und den gecachten Snapshot im Hintergrund auf das Cap, in kleinen Scheiben mit einer Pause dazwischen, sodass Suche, Capture und der Viewer weiter funktionieren. Es speichert seinen Fortschritt, setzt nach einem Neustart fort und läuft nie wieder, sobald es fertig ist. `/agentmemory/status` und die Health-Seite des Viewers zeigen es als ausstehend, laufend (mit dem aktuellen Scope und der Position), fertig oder fehlgeschlagen. Setzen Sie `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`, um es abzuschalten.
+
+Um es von Hand auszuführen, rufen Sie `POST /agentmemory/graph/compact` auf. Es durchläuft die Name- und Edge-Key-Indizes, statt jeden Knoten und jede Kante aufzulisten, und kann sicher erneut ausgeführt werden. Wenn es IDs trimmt, schreibt es einen `graph_compact`-Audit-Eintrag.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Bei einem großen Store, oder wenn der Aufruf 504 zurückgibt, führen Sie es in Scheiben aus. Senden Sie `scope` (`nodes`, `edges` oder `history`), `offset` und `limit`, und rufen Sie es dann mit dem zurückgegebenen `nextOffset` erneut auf, bis er `null` ist. Tun Sie das für `nodes`, `edges` und `history`, und schließen Sie mit einem einzigen `{"scope":"snapshot"}`-Aufruf ab, da ein in Scheiben ausgeführter Lauf den gecachten Snapshot nicht berührt.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1560,11 +1870,11 @@ Volle Endpunktliste: [`src/triggers/api.ts`](../src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**Voraussetzungen:** Node.js >= 20, [iii-engine](https://iii.dev/docs) oder Docker
+**Voraussetzungen:** Node.js >= 20 mit npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 oder Docker. Die automatische Engine-Installation unter macOS/Linux benötigt außerdem `curl`, eine POSIX-`sh` und `tar`; natives Windows verwendet die manuell gepinnte `iii.exe`, WSL2 oder Docker Desktop.
diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.md
new file mode 100644
index 0000000000..b6b169e323
--- /dev/null
+++ b/READMEs/README.el-GR.md
@@ -0,0 +1,1873 @@
+
+
+
+
+
+
+ Ο agent κώδικα σας θυμάται τα πάντα. Τέλος οι επαναλαμβανόμενες εξηγήσεις.
+ Βασισμένο στο iii engine
+
+ Μόνιμη μνήμη για τα Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, και κάθε client MCP.
+
+ Το gist επεκτείνει το πρότυπο LLM Wiki του Karpathy με βαθμολόγηση εμπιστοσύνης, κύκλο ζωής, γράφους γνώσης και υβριδική αναζήτηση: το agentmemory είναι η υλοποίηση.
+
+
+---
+
+## Εγκατάσταση
+
+Απαιτήσεις:
+
+- Node.js 20 ή νεότερη έκδοση με npm και npx (`node -v`, `npm -v`, και `npx -v`).
+- Η αυτόματη εγκατάσταση του iii-engine σε macOS/Linux απαιτεί επίσης `curl`, ένα POSIX `sh`, και `tar`. Ελάχιστες εικόνες όπως το `node:20-slim` μπορεί να μην τα περιλαμβάνουν.
+- Το native Windows απαιτεί την καθορισμένη έκδοση iii-engine v0.22.1 `iii.exe` να εγκατασταθεί χειροκίνητα. Τα WSL2 ή το Docker Desktop είναι οι άλλες υποστηριζόμενες διαδρομές.
+
+Η κανονική εντολή εγκατάστασης από την αρχή:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Η πρώτη εκτέλεση είναι μια διαδραστική ρύθμιση: επιλέγετε τους agents που θα συνδέσετε (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), επιλέγετε έναν πάροχο LLM ή παραμένετε χωρίς κλειδί, και εκείνη δημιουργεί τις ρυθμίσεις, ξεκινά τον διακομιστή μνήμης και τον καθορισμένο iii engine του, και προσφέρεται να εγκατασταθεί καθολικά ώστε η απλή εντολή `agentmemory` να λειτουργεί παντού στη συνέχεια. Το `-y` αποδέχεται την προτροπή πακέτου του npx και το `@latest` αποφεύγει μια παλιωμένη έκδοση από την cache. Ένας πάροχος κάνει διαθέσιμες τις λειτουργίες LLM, αλλά η συμπίεση παρατηρήσεων γραμμένη από LLM ξεκινά μόνο όταν έχει ρυθμιστεί επίσης το `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Η λειτουργία χωρίς κλειδί απενεργοποιεί τα vector embeddings. Το `memory_recall` (η διαδρομή `mem::search`) χρησιμοποιεί BM25, ενώ το `memory_smart_search` μπορεί επίσης να συγχωνεύσει δομικές αντιστοιχίσεις γράφου όταν υπάρχουν ήδη δεδομένα γράφου. Για δωρεάν σημασιολογική ανάκληση στη συσκευή, ρυθμίστε το `EMBEDDING_PROVIDER=local` στο `~/.agentmemory/.env` και κάντε επανεκκίνηση. Το πρώτο αίτημα embedding κατεβάζει το `Xenova/all-MiniLM-L6-v2`· η εξαγωγή συμπερασμάτων εκτελείται τοπικά μετά από αυτήν την αρχική λήψη μοντέλου.
+
+Το τοπικό runtime χρησιμοποιεί τέσσερις θύρες: `3111` για REST/MCP HTTP, `3112` για τα iii streams, `3113` για το viewer, και `49134` για το WebSocket του iii worker. Η μόνιμη κατάσταση iii βρίσκεται στο `~/Library/Application Support/agentmemory` σε macOS, στο `$XDG_DATA_HOME/agentmemory` ή `~/.local/share/agentmemory` σε Linux, και στο `%APPDATA%\agentmemory` σε Windows. Χρησιμοποιήστε `--data-dir ` ή `AGENTMEMORY_DATA_DIR` για να το παρακάμψετε, και επαναχρησιμοποιήστε την ίδια τιμή σε κάθε επανεκκίνηση. Για λόγους συμβατότητας προς τα πίσω, ένα υπάρχον `./data/state_store.db` ή `./data/iii-config.yaml` υπερισχύει της προεπιλογής της πλατφόρμας για το instance 0· μια ρητή σημαία ή παράκαμψη περιβάλλοντος εξακολουθεί να υπερισχύει.
+
+Στη συνέχεια, επιβεβαιώστε ότι η ανάκληση λειτουργεί και δώστε στον agent σας τα skills του:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Οι αναζητήσεις με λέξεις-κλειδιά θα πρέπει να βρίσκουν αποτελέσματα στην προεπιλεγμένη λειτουργία χωρίς κλειδί μέσω BM25. Το ερώτημα `database performance optimization` του demo είναι σκόπιμα σημασιολογικό και μπορεί να επιστρέψει μηδέν αποτελέσματα μέχρι να ρυθμιστεί ένας πάροχος embedding.
+
+Προτιμάτε να αφήσετε έναν agent κώδικα να κάνει όλη τη δουλειά; Δώστε του μία οδηγία:
+
+> Ανακτήστε και ακολουθήστε τις οδηγίες στο: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Συνδέστε περισσότερους agents όποτε θέλετε με `agentmemory connect ` — 20 adapters αναφέρονται στο [Λειτουργεί με κάθε agent](#works-with-every-agent). Πλήρης αναφορά εντολών στο [Γρήγορη Εκκίνηση](#quick-start).
+
+
+Windows
+
+Η πιο γρήγορη διαδρομή είναι το WSL2. Η native ρύθμιση του engine σε Windows απαιτεί τη λήψη του καθορισμένου ZIP v0.22.1 και την χειροκίνητη εξαγωγή του `iii.exe`· το CLI δεν το εξάγει αυτόματα. Υποστηρίζεται επίσης το Docker Desktop. Δείτε τις [σημειώσεις Windows](#windows) για τα βήματα.
+
+
+
+
+Καθολική εγκατάσταση / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Η παραπάνω εντολή npx παραμένει η κανονική διαδρομή εγκατάστασης από την αρχή και αποφεύγει προβλήματα δικαιωμάτων global-prefix.
+
+
+
+
+Το npx εξυπηρετεί μια παλιά έκδοση
+
+Το npx αποθηκεύει στην cache ανά έκδοση. Επιβάλετε τη τελευταία με `npx -y @agentmemory/agentmemory@latest`, ή καθαρίστε την cache μία φορά με `rm -rf ~/.npm/_npx` (macOS/Linux· σε Windows διαγράψτε το `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Έχετε ήδη τον δικό σας iii engine σε εκτέλεση
+
+Το agentmemory καθορίζει τον iii-engine στην v0.22.1 και δεν θα συνδεθεί σε διαφορετική έκδοση (ο worker δεν μπορεί να μιλήσει το πρωτόκολλο ενός άλλου engine). Σταματήστε τον άλλο engine, και μετά εκτελέστε `npx -y @agentmemory/agentmemory@latest`. Εγκαθιστά και εκτελεί την καθορισμένη v0.22.1 στο `~/.agentmemory/bin`, αφήνοντας τον δικό σας `iii` ανεπηρέαστο.
+
+
+
+---
+
+
+
+Το agentmemory λειτουργεί με κάθε agent που υποστηρίζει hooks, MCP, ή REST API. Όλοι οι agents μοιράζονται τον ίδιο διακομιστή μνήμης.
+
+
+
+
+
+Claude Code
+εγγενές plugin + 12 hooks + MCP
+
+
+
+Codex CLI
+εγγενές plugin + 6 hooks + MCP
+
+
+
+GitHub Copilot CLI
+MCP + hooks/skills του plugin
+
+
+
+Cursor
+εγγενές plugin + 7 hooks + MCP
+
+
+
+OpenCode
+plugin καταγραφής + MCP
+
+
+
+
+
+Devin
+6 hooks + skills + MCP
+
+
+
+OpenClaw
+εγγενές plugin + MCP
+
+
+
+Hermes
+εγγενές plugin + MCP
+
+
+
+pi
+εγγενές plugin + MCP
+
+
+
+OpenHuman
+εγγενές backend Memory trait
+
+
+
+
+
+Gemini CLI
+διακομιστής MCP
+
+
+
+Antigravity
+MCP + hooks
+
+
+
+Claude Desktop
+διακομιστής MCP
+
+
+
+Warp
+connect + MCP + skills
+
+
+
+Zed
+διακομιστής MCP
+
+
+
+
+
+Cline
+διακομιστής MCP
+
+
+
+Continue
+διακομιστής MCP
+
+
+
+Droid
+διακομιστής MCP
+
+
+
+Kiro
+διακομιστής MCP
+
+
+
+Qwen Code
+διακομιστής MCP
+
+
+
+
+
+DeepSeek Harness
+διακομιστής MCP
+
+
+
+Roo Code
+διακομιστής MCP
+
+
+
+Kilo Code
+διακομιστής MCP
+
+
+
+Goose
+διακομιστής MCP
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Λειτουργεί με κάθε agent που μιλά MCP ή HTTP. Ένας διακομιστής, μνήμες κοινές σε όλους.
+
+
+---
+
+Εξηγείτε την ίδια αρχιτεκτονική σε κάθε συνεδρία. Ανακαλύπτετε ξανά τα ίδια bugs. Ξαναδιδάσκετε τις ίδιες προτιμήσεις. Η ενσωματωμένη μνήμη (CLAUDE.md, .cursorrules) φτάνει στο όριο των 200 γραμμών και μπαγιατεύει. Το agentmemory το διορθώνει αυτό. Καταγράφει σιωπηλά τι κάνει ο agent σας, το συμπιέζει σε αναζητήσιμη μνήμη, και εισάγει το σωστό πλαίσιο όταν ξεκινά η επόμενη συνεδρία. Μία εντολή. Λειτουργεί σε όλους τους agents.
+
+**Τι αλλάζει:** Στη συνεδρία 1 ρυθμίζετε JWT auth. Στη συνεδρία 2 ζητάτε rate limiting. Ο agent ήδη γνωρίζει ότι το auth σας χρησιμοποιεί jose middleware στο `src/middleware/auth.ts`, ότι τα tests σας καλύπτουν την επικύρωση token, και ότι επιλέξατε jose αντί για jsonwebtoken για συμβατότητα με Edge, χωρίς καμία επανάληψη εξηγήσεων και χωρίς copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Από προεπιλογή, το agentmemory αποθηκεύει την κατάσταση του iii-engine έξω από το αποθετήριο από το οποίο το ξεκινάτε: `~/Library/Application Support/agentmemory` σε macOS, `$XDG_DATA_HOME/agentmemory` ή `~/.local/share/agentmemory` σε Linux, και `%APPDATA%\agentmemory` σε Windows. Ένα υπάρχον παλιό `./data/state_store.db` ή `./data/iii-config.yaml` επαναχρησιμοποιείται για το instance 0 πριν από αυτή την προεπιλογή πλατφόρμας. Για να επιλέξετε μια τοποθεσία ρητά, περάστε `--data-dir ` ή ρυθμίστε `AGENTMEMORY_DATA_DIR`· κάθε ρητή ρύθμιση υπερισχύει της παλιάς ανακάλυψης:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Οι native και Docker εκκινήσεις χρησιμοποιούν τον ίδιο επιλυμένο κατάλογο host· το Docker τον κάνει bind-mount στο `/data`. Το `--instance 1` προσθέτει `instance-1` στον επιλυμένο κατάλογο και επιλέγει το ξεχωριστό προεπιλεγμένο quartet θυρών `3211/3212/3213/49234`.
+
+Τελευταίες σημειώσεις έκδοσης: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Ακρίβεια Ανάκλησης
+
+**coding-agent-life-v1** (εσωτερικό corpus, αναπαραγώγιμο σε sandbox)
+
+| Προσαρμογέας | P@5 | R@5 | Ποσοστό επιτυχίας Top-5 | Καθυστέρηση p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep βασικής αναφοράς | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+Ποσοστό επιτυχίας Top-5 100% στο **ανώτατο μαθηματικό όριο P@5** για αυτό το corpus (0.240, δείτε το scorecard). Το hybrid ανακτά κάθε gold συνεδρία· το grep χάνει 1 από τα 2 gold στο ερώτημα πολλαπλών συνεδριών με χρονική διάσταση. Η βελτίωση είναι σε **ανάκληση + χρονικότητα**, όχι σε συνολική ακρίβεια. Αυτό το benchmark είναι μικρό και με λίγα gold δεδομένα· το μεγαλύτερο LongMemEval-S παρακάτω διαφοροποιεί καλύτερα. Πλήρης ανάλυση ανά τύπο + σημείωση διόρθωσης: [`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 (fallback) | 86.2% | 94.6% | 71.5% |
+
+
+
+> Μοντέλο embedding: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Αναπαραγωγή τοπικά:** [`eval/README.md`](../eval/README.md), ένα harness με συνδέσιμους adapters για το LongMemEval `_s` (δημόσιο, 500 ερωτήσεις) + `coding-agent-life-v1` (εσωτερικό corpus 15 συνεδριών). Οι adapters grep / vector / agentmemory βαθμολογούνται παράλληλα, με έξοδο NDJSON, και τα δημοσιευμένα 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, pipelines κατασκευής πολλών agents, και ευρύτεροι γράφοι γνώσης σε docs / PDF / εικόνες / βίντεο. Το agentmemory θυμάται τη δουλειά· αυτά τα τρία projects αναδεικνύουν την υπόλοιπη context layer. Συνταγές + πίνακας δρομολόγησης ερωτημάτων: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Ενσωματωμένο (CLAUDE.md)
+
+
+
Τύπος
+
Μηχανή μνήμης + διακομιστής MCP
+
API επιπέδου μνήμης
+
Πλήρες runtime agent
+
Προσωπικό AI
+
API μνήμης + εφαρμογή
+
Κόμβος μνήμης ομάδας (proxy LLM)
+
Vector μνήμη (OSS)
+
Μηχανή μνήμης (Oracle DB)
+
Σύστημα μνήμης
+
Στατικό αρχείο
+
+
+
Ανάκληση R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Αυτοαναφερόμενο
+
PersonaMem 76% (αυτοαναφερόμενο)
+
~96.6% (αυτοαναφερόμενο)
+
94.4% (αυτοαναφερόμενο)
+
N/A
+
N/A (grep)
+
+
+
Αυτόματη καταγραφή
+
12 hooks (καμία χειροκίνητη προσπάθεια)
+
Χειροκίνητες κλήσεις add()
+
Αυτο-επεξεργασίες από τον agent
+
Χειροκίνητο
+
Εξαγωγή από την πλευρά του API
+
Παρεμβολή proxy (αλλαγή base-URL)
+
Χειροκίνητο
+
Εξαγωγή API
+
Χειροκίνητο
+
Χειροκίνητη επεξεργασία
+
+
+
Αναζήτηση
+
BM25 + Vector + Graph (συγχώνευση RRF)
+
Vector + Graph
+
Vector (αρχειοθέτηση)
+
Σημασιολογική
+
Vector + RAG
+
4 τύποι assets (Chat / Skill / Wiki / CodeGraph)
+
Μόνο Vector
+
Vector + σημασιολογική
+
Σταθμισμένη βάσει decay
+
Φορτώνει τα πάντα στο context
+
+
+
Πολλαπλών agents
+
MCP + REST + leases + σήματα
+
API (χωρίς συντονισμό)
+
Μόνο εντός του runtime Letta
+
Όχι
+
Όχι
+
Ρόλοι ομάδας + κοινά assets
+
Όχι
+
Μόνο εντός scope
+
Κοινό μεταξύ πολλών agents
+
Αρχεία ανά agent
+
+
+
Εξάρτηση από framework
+
Καμία (οποιοδήποτε MCP client)
+
Καμία
+
Υψηλή (απαιτεί χρήση Letta)
+
Αυτόνομο
+
Καμία
+
Το proxy μεσολαβεί σε κάθε κλήση μοντέλου
+
Καμία
+
Oracle Database
+
Καμία
+
Μορφή ανά agent
+
+
+
Εξωτερικές εξαρτήσεις
+
Καμία (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + vector DB
+
Πολλαπλές
+
Διαχειριζόμενο cloud
+
Docker stack (Core + Hub + Proxy)
+
Αποθήκη vector
+
Oracle AI Database
+
Καμία
+
Καμία
+
+
+
Κύκλος ζωής μνήμης
+
Ενοποίηση 4 επιπέδων + decay + αυτόματη διαγραφή
+
Παθητική εξαγωγή
+
Διαχειρίζεται από τον agent
+
Χειροκίνητο
+
Αυτόματη διαγραφή
+
Χειροκίνητη επισκόπηση· αυτόματη δρομολόγηση σε εξέλιξη
+
Καμία
+
Δεν αναφέρεται
+
Decay + ενοποίηση
+
Χειροκίνητο κλάδεμα
+
+
+
Απόδοση tokens
+
~1,900 tokens/συνεδρία ($10/έτος)
+
Διαφέρει ανά ολοκλήρωση
+
Βασική μνήμη εντός context
+
Διαφέρει
+
Τιμολόγηση cloud
+
Δεν αναφέρεται
+
Χωρίς προϋπολογισμό tokens
+
Βασισμένο σε LLM (διαφέρει)
+
Διαφέρει
+
22K+ tokens σε 240 παρατηρήσεις
+
+
+
Viewer σε πραγματικό χρόνο
+
Ναι (θύρα 3113)
+
Dashboard cloud
+
Dashboard cloud
+
Web UI
+
Dashboard cloud
+
Hub web UI
+
Όχι
+
Όχι
+
Όχι
+
Όχι
+
+
+
Αυτοφιλοξενούμενο (self-hosted)
+
Ναι (προεπιλογή)
+
Προαιρετικό
+
Προαιρετικό
+
Ναι
+
Όχι (μόνο cloud)
+
Ναι (Docker)
+
Ναι
+
Ναι (Oracle DB)
+
Ναι
+
Ναι
+
+
+
+Σημείωση benchmark: μόνο το R@5 του agentmemory είναι δικό μας μετρημένο αποτέλεσμα (LongMemEval-S, αναπαραγώγιμο από το benchmark/COMPARISON.md). Τα στοιχεία των mem0 και Letta είναι οι δημοσιευμένες τιμές τους στο LoCoMo (διαφορετικό dataset)· τα στοιχεία των MemPalace, supermemory, TencentDB (PersonaMem), και oracleagentmemory είναι αυτοαναφερόμενοι ισχυρισμοί προμηθευτών που δεν έχουμε αναπαράγει ανεξάρτητα (η εκτέλεση του oracleagentmemory χρησιμοποίησε GPT-5.5 έναντι μιας Oracle AI Database). Παρουσιάζονται δίπλα-δίπλα μόνο για κατά προσέγγιση σύγκριση, όχι ως απευθείας αντιπαράθεση σε ταυτόσημα δεδομένα. Οι μετρήσεις αστεριών είναι κατά προσέγγιση και μεταβάλλονται με τον χρόνο.
+
+**Νεότεροι παίκτες** που αξίζει να γνωρίζετε, συγκρίνονται αναλυτικά στο [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Σύστημα | ⭐ | Προσέγγιση |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Χρονικός γράφος γνώσης· τα ισχυρότερα δημοσιευμένα αποτελέσματα σε χρονικά ερωτήματα (LongMemEval 63.8%), αλλά ο γράφος χτίζεται ασύγχρονα, οπότε τα νέα δεδομένα μπορεί να καθυστερούν |
+| Cognee | 30K | Εισαγωγή εγγράφων σε γράφο γνώσης, μόνο σε Python, σχεδιασμένο για δομημένη εξαγωγή οντοτήτων παρά για καταγραφή συνεδριών |
+
+Κανένα από αυτά δεν κάνει αυτόματη καταγραφή από hooks agent κώδικα, δεν διαθέτει local-first viewer, και δεν λειτουργεί χωρίς κλειδί — τον συνδυασμό γύρω από τον οποίο είναι χτισμένο το agentmemory.
+
+---
+
+
+
+Συμβατότητα: αυτή η έκδοση στοχεύει το `iii-sdk` 0.22.1 και καθορίζει τον iii-engine στην v0.22.1.
+
+### Δοκιμάστε το σε 30 δευτερόλεπτα
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+Το `demo` δημιουργεί 3 ρεαλιστικές συνεδρίες (JWT auth, διόρθωση ερωτήματος N+1, rate limiting) και εκτελεί αναζητήσεις σε αυτές. Οι εγκαταστάσεις χωρίς κλειδί απενεργοποιούν τα vectors, οπότε τα ερωτήματα λέξεων-κλειδιών `mem::search` θα πρέπει να βρίσκουν αποτελέσματα μέσω BM25, ενώ το `database performance optimization` μπορεί να επιστρέψει μηδέν. Το `smart-search` μπορεί επίσης να επιστρέψει δομικές αντιστοιχίσεις γράφου όταν υπάρχουν δεδομένα γράφου. Για να κάνετε το σημασιολογικό ερώτημα να βρει τη διόρθωση N+1 μέσω vectors, ρυθμίστε το `EMBEDDING_PROVIDER=local`, κάντε επανεκκίνηση, και αφήστε την πρώτη λήψη μοντέλου να ολοκληρωθεί.
+
+Ανοίξτε το `http://localhost:3113` για να παρακολουθήσετε τη μνήμη να χτίζεται ζωντανά.
+
+### Επιβεβαιώστε μια νέα εγκατάσταση και τη μονιμότητα μετά από επανεκκίνηση
+
+Με τον διακομιστή σε λειτουργία, επιβεβαιώστε το REST, το health, το viewer, και την κατάσταση του runtime που βασίζεται στο iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Το πάνελ ετοιμότητας εκκίνησης λαμβάνει υπόψη όλες τις τέσσερις θύρες: REST/MCP HTTP στη 3111, τα iii streams στη 3112, το viewer στη 3113, και το WebSocket του iii worker στη 49134. Το `status` επιβεβαιώνει την υγεία του agentmemory και την ενεργή λειτουργία provider/embedding. Αποθηκεύστε μια δοκιμαστική εγγραφή (probe) και επιβεβαιώστε ότι είναι αναζητήσιμη:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Στη συνέχεια εκτελέστε `npx -y @agentmemory/agentmemory@latest stop`, ξεκινήστε ξανά την κανονική εντολή στο Terminal 1, περιμένετε το `/agentmemory/livez`, και επαναλάβετε την αναζήτηση. Το probe πρέπει να επιστρέφεται ακόμα. Αν επιλέξατε προσαρμοσμένο `--data-dir`, περάστε τον ίδιο κατάλογο στην επανεκκίνηση.
+
+### Καθημερινές εντολές
+
+Η εγκατάσταση και η ρύθμιση βρίσκονται στο [Εγκατάσταση](#install) παραπάνω (η πρώτη εκτέλεση σας καθοδηγεί). Καθημερινά:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Αναπαραγωγή Συνεδρίας
+
+Κάθε συνεδρία που καταγράφει το agentmemory μπορεί να αναπαραχθεί. Ανοίξτε το viewer, επιλέξτε την καρτέλα **Replay**, και μετακινηθείτε στο timeline: τα prompts, οι κλήσεις εργαλείων, τα αποτελέσματα εργαλείων, και οι απαντήσεις αποδίδονται ως διακριτά events με play/pause, έλεγχο ταχύτητας (0.5x έως 4x), και συντομεύσεις πληκτρολογίου (space για εναλλαγή, βέλη για βήμα-βήμα).
+
+Για να εισάγετε παλαιότερα JSONL transcripts του Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Οι εισαγμένες συνεδρίες εμφανίζονται στον επιλογέα Replay μαζί με τις εγγενείς. Στο παρασκήνιο, κάθε καταχώρηση διέρχεται από τα iii functions `mem::replay::load`, `mem::replay::sessions`, και `mem::replay::import-jsonl`, χωρίς πλευρικούς (side-channel) διακομιστές. Κάθε εισαγμένο transcript ευρετηριάζεται για αναζήτηση, σημαίνεται με κανάλι προέλευσης `import`, και εξορύσσεται για ένα session crystal και μαθήματα.
+
+> **Σημαντική σημείωση αν βασίζεστε στο `import-jsonl` ως κύρια διαδρομή καταγραφής:** Το `cleanupPeriodDays` του Claude Code (στο `~/.claude/settings.json`, προεπιλογή **30**) διαγράφει αυτόματα τα JSONL transcripts παλαιότερα από αυτό το παράθυρο από το `~/.claude/projects/`. Αν εγκαταστήσετε το agentmemory από την αρχή σε ένα ιστορικό Claude Code μηνών, οτιδήποτε παλαιότερο από 30 ημέρες έχει ήδη χαθεί πριν από την πρώτη εισαγωγή. Είτε εκτελέστε το `import-jsonl` μέσω cron, αυξήστε το `cleanupPeriodDays` σε μεγαλύτερη τιμή, είτε συνδέστε τα hooks αυτόματης καταγραφής (η προεπιλεγμένη διαδρομή εγκατάστασης plugin) ώστε κάθε γύρος να καταλήγει στο agentmemory ενώ η συνεδρία είναι ενεργή, και ο καθαρισμός JSONL να σταματήσει να έχει σημασία.
+
+### Αναβάθμιση / Συντήρηση
+
+Χρησιμοποιήστε την εντολή συντήρησης όταν θέλετε σκόπιμα να ενημερώσετε το τοπικό runtime σας:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Προειδοποίηση: αυτή η εντολή τροποποιεί τον τρέχοντα workspace/runtime. Μπορεί να ενημερώσει τις εξαρτήσεις JavaScript και να κατεβάσει την καθορισμένη εικόνα Docker `iiidev/iii:0.22.1`. Ποτέ δεν εγκαθιστά μη καθορισμένη ή νεότερη έκδοση του iii engine.
+
+Οι λεπτομέρειες υλοποίησης βρίσκονται στο `src/cli.ts` (δείτε το `runUpgrade` γύρω από την περιοχή `src/cli.ts:544-595`).
+
+### Claude Code (ένα block, επικολλήστε το)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code χωρίς εγκατάσταση plugin (αυτόνομη διαδρομή MCP)
+
+Αν συνδέσετε τον διακομιστή MCP του agentmemory μέσω του `~/.claude.json` απευθείας αντί να χρησιμοποιήσετε το `/plugin install`, το Claude Code δεν επιλύει ποτέ το `${CLAUDE_PLUGIN_ROOT}` και πρέπει να δείξετε τα scripts των hooks σε απόλυτες διαδρομές στο `~/.claude/settings.json`. Αυτές οι διαδρομές συνήθως ενσωματώνουν την έκδοση του agentmemory (π.χ. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), οπότε η επόμενη αναβάθμιση χαλάει σιωπηλά κάθε hook.
+
+Λύση παράκαμψης:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Αυτό συγχωνεύει τις ίδιες εντολές hook στο `~/.claude/settings.json` με απόλυτες διαδρομές που αναλύονται στον ενσωματωμένο κατάλογο `plugin/` του πακέτου `@agentmemory/agentmemory` που είναι τρέχουσα εγκατεστημένο. Εκτελέστε ξανά την εντολή μετά την αναβάθμιση του agentmemory για να ανανεωθούν οι διαδρομές. Οι καταχωρήσεις του χρήστη στο ίδιο αρχείο διατηρούνται· αντικαθίστανται μόνο οι προηγούμενες καταχωρήσεις του agentmemory. Η χρήση της διαδρομής `/plugin install` παραμένει η συνιστώμενη προσέγγιση.
+Για απομακρυσμένες ή προστατευμένες αναπτύξεις, εκκινήστε το Claude Code με ρυθμισμένα τα `AGENTMEMORY_URL` και `AGENTMEMORY_SECRET`. Το plugin περνάει και τις δύο τιμές στον ενσωματωμένο διακομιστή MCP του· όταν το `AGENTMEMORY_URL` είναι άδειο, το MCP shim χρησιμοποιεί το `http://localhost:3111`.
+
+### Codex CLI (πλατφόρμα plugin του Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Το plugin του Codex διανέμεται από τον ίδιο κατάλογο `plugin/` όπως το plugin του Claude Code. Καταχωρεί:
+
+- Μια ενσωματωμένη γέφυρα MCP stdio προς τον ενεργό daemon, χωρίς λήψη μέσω npm ή αποθήκη fallback. Δείτε τον [τοπικό οδηγό Codex](../docs/plugins/codex-local.md) για να δοκιμάσετε ένα μη κυκλοφορημένο build.
+- 6 hooks κύκλου ζωής: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 επικλητά skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, συν 8 skills αναφοράς που ο agent φορτώνει όταν τα χρειάζεται (πειθαρχία μνήμης, εργαλεία MCP, REST API, ρυθμίσεις, agents, hooks, αρχιτεκτονική, και τον οδηγό συγγραφής skills)
+
+Η μηχανή hooks του Codex εισάγει το `CLAUDE_PLUGIN_ROOT` στις υποδιαδικασίες των hooks (σύμφωνα με το [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), οπότε τα ίδια scripts hooks λειτουργούν σε αμφότερους τους hosts χωρίς διπλασιασμό. Τα events Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure είναι αποκλειστικά του Claude Code και δεν καταχωρούνται για το Codex.
+
+#### Εμπιστοσύνη και συμβατότητα των hooks του Codex
+
+Η εγγενής αποστολή (dispatch) των hooks του plugin είναι επιβεβαιωμένη με το Codex CLI 0.150.1. Εμπιστευτείτε (trust) τα hooks του plugin πριν περιμένετε καταγραφή. Η συμπεριφορά του Codex Desktop εξαρτάται από το ενσωματωμένο runtime του· ελέγξτε το `/hooks` και επιβεβαιώστε ένα καταγεγραμμένο event πριν ενεργοποιήσετε μια λύση παράκαμψης.
+
+Αν το host σας απαιτεί καθολικά hooks, αντιγράψτε τις εντολές στο `~/.codex/hooks.json`. Όταν το MCP είναι ήδη συνδεδεμένο, ο τρέχων connector χρειάζεται το `--force` για να φτάσει στην εγκατάσταση των hooks:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Αυτό συγχωνεύει τα καθολικά hooks και ξαναγράφει την καταχώρηση MCP του agentmemory, διατηρώντας τις άσχετες καταχωρήσεις. Ελέγξτε τυχόν προσαρμοσμένες ρυθμίσεις endpoint του agentmemory πριν χρησιμοποιήσετε το `--force`. Εκτελέστε ξανά μετά την αναβάθμιση για να ανανεωθούν οι διαδρομές των scripts. Ενεργοποιήστε είτε τα εγγενή hooks του plugin, είτε τα καθολικά αντίγραφα, για να αποφύγετε τη διπλή καταγραφή.
+
+### GitHub Copilot CLI
+
+Για τη λειτουργία agent του VS Code, χρησιμοποιήστε τον [οδηγό MCP και αυτόματης καταγραφής του Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Ο connector CLI δεν ρυθμίζει το VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+Το `agentmemory connect copilot-cli` συγχωνεύει το `mcpServers.agentmemory` στο `~/.copilot/mcp-config.json` (ή στο `$COPILOT_HOME/mcp-config.json` όταν έχει ρυθμιστεί το `COPILOT_HOME`) και διατηρεί τους υπάρχοντες διακομιστές. Σε native Windows αυτός είναι ο μόνος αυτοματοποιημένος adapter `connect`· ρυθμίστε κάθε άλλο native Windows agent χειροκίνητα. Το `connect` σε WSL υποστηρίζεται μόνο όταν ο στόχος-agent είναι εγκατεστημένος στο ίδιο περιβάλλον WSL. Το Copilot παραλαμβάνει τον διακομιστή MCP στην επόμενη εκκίνηση ή μετά το `/mcp`. Εγκαταστήστε επίσης το plugin όταν θέλετε την πλήρη εμπειρία hooks/skills.
+
+
+OpenClaw (επικολλήστε αυτό το prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Πλήρης οδηγός: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (επικολλήστε αυτό το prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Πλήρης οδηγός: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Άλλοι agents
+
+Ξεκινήστε τον διακομιστή μνήμης: `npx -y @agentmemory/agentmemory@latest`
+
+#### Εγγενή skills μέσω `npx skills add` (50+ agents)
+
+Το agentmemory διανέμει 17 skills στη μορφή `/SKILL.md` τύπου Claude Code: 9 επικλητά skills ενέργειας (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) και 8 skills αναφοράς που ο agent φορτώνει όταν τα χρειάζεται (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Τα skills αναφοράς περιέχουν πίνακες δεδομένων που δημιουργούνται από την πηγή, οπότε δεν αποκλίνουν ποτέ. Το CLI [`skills`](https://npmjs.com/package/skills) από την vercel-labs τα εγκαθιστά αυτόματα στον εγγενή κατάλογο skills του agent που το καλεί, σε 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, και άλλα):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Αυτό είναι **συμπληρωματικό** του `agentmemory connect `:
+
+- Το `agentmemory connect ` γράφει τις ρυθμίσεις του διακομιστή MCP ώστε να είναι διαθέσιμα τα εργαλεία.
+- Το `npx skills add rohitg00/agentmemory` εγκαθιστά τα skills ώστε ο agent να ξέρει πότε να τα καλέσει.
+
+Για τους λίγους agents που το CLI skills δεν καλύπτει ακόμα (Zed v1.3.x και παλαιότερα), τοποθετήστε τα 17 αρχεία SKILL.md μόνοι σας στον εγγενή κατάλογο skills του agent· η ίδια μορφή λειτουργεί παντού.
+
+#### Τυπικό block MCP
+
+Η καταχώρηση agentmemory είναι το **ίδιο block διακομιστή MCP** σε κάθε host που χρησιμοποιεί τη μορφή `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Συγχωνεύστε αυτή την καταχώρηση στο υπάρχον αντικείμενο `mcpServers`** στο αρχείο ρυθμίσεων του host· μην αντικαταστήσετε το αρχείο. Αν το αρχείο έχει ήδη άλλους διακομιστές, προσθέστε το `agentmemory` δίπλα τους ως ακόμα ένα κλειδί μέσα στο `mcpServers`. Αν το `mcpServers` λείπει εντελώς, επικολλήστε το block μέσα στο `{ "mcpServers": { ... } }`. Τα placeholders `${VAR}` κληρονομούν τα `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` από το shell κατά την εκκίνηση του διακομιστή MCP· οι μη ρυθμισμένες μεταβλητές περνούν κενά strings και το shim επιστρέφει στο `http://localhost:3111`. Μία συνδεδεμένη καταχώρηση καλύπτει τόσο τοπικές όσο και απομακρυσμένες (k8s / πίσω από reverse-proxy) αναπτύξεις.
+
+| Agent | Αρχείο ρυθμίσεων | Σημειώσεις |
+|---|---|---|
+| **Cursor (MCP only)** | `~/.cursor/mcp.json` | Συγχωνεύστε στο `mcpServers`, ή `agentmemory connect cursor`. Διατίθεται επίσης one-click deeplink στον ιστότοπο. |
+| **Cursor (full plugin)** | `.cursor-plugin/` | Καταχώρηση στο Cursor Marketplace (η υποβολή βρίσκεται υπό έλεγχο) ή Cursor Settings → Plugins → τοπικό checkout. Καταχωρεί 7 hooks αυτόματης καταγραφής (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + τον διακομιστή MCP, με τα `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` να διαχειρίζονται στο dashboard του plugin του Cursor. Λειτουργεί στο Cursor IDE και στο CLI `cursor-agent`· τα prompts του CLI σε print-mode συμπληρώνονται αναδρομικά από το transcript της συνεδρίας στο τέλος της συνεδρίας. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Συγχωνεύστε στο `mcpServers`. Κάντε επανεκκίνηση του Claude Desktop μετά την επεξεργασία. |
+| **Cline / Roo Code / Kilo Code** | Ρυθμίσεις MCP του Cline (Settings UI → MCP Servers → Edit) | Το ίδιο block `mcpServers`. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | Το `agentmemory connect devin` συγχωνεύει την καταχώρηση MCP· το `--with-hooks` προσθέτει έξι εγγενή hooks αυτόματης καταγραφής (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) με τους πεζούς (lowercase) tool matchers του Devin. Επιβεβαιώστε με `devin mcp list` και `/hooks` μέσα στο devin. |
+| **Devin CLI (full plugin)** | `plugin/.devin-plugin/` | Το `devin plugins install ./plugin` από ένα checkout καταχωρεί όλα τα 17 skills ως εντολές `/agentmemory:` καθώς και τον διακομιστή MCP. Τα hooks του plugin στο Devin δεν μπορούν να ενεργοποιήσουν τα `SessionStart`/`SessionEnd`, οπότε συνδυάστε το με `connect devin --with-hooks` για πλήρη καταγραφή συνεδρίας. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Προσθέστε ένα προσαρμοσμένο MCP (STDIO): εντολή `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` που δείχνει σε μια ανάπτυξη agentmemory προσβάσιμη από το δίκτυο, καθώς και `AGENTMEMORY_SECRET` (οι συνεδρίες cloud δεν μπορούν να φτάσουν το localhost — δείτε [`deploy/`](../deploy/)). Αποθηκεύστε το secret στο Devin Secrets, και χρησιμοποιήστε το "Test listing tools" για να επιβεβαιώσετε ότι εμφανίζονται όλα τα 54 εργαλεία. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (συγχωνεύεται αυτόματα). |
+| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | Το `agentmemory connect copilot-cli` συγχωνεύει το `mcpServers.agentmemory`· το Copilot το παραλαμβάνει στην επόμενη εκκίνηση ή με `/mcp`. |
+| **GitHub Copilot CLI (full plugin)** | Εγκατάσταση plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` για το plugin από τον υποκατάλογο GitHub. |
+| **OpenClaw** | Ρυθμίσεις MCP του OpenClaw | Το ίδιο block `mcpServers`. Για βαθύτερη ενσωμάτωση: το `openclaw plugins install ./integrations/openclaw` διεκδικεί το memory slot του OpenClaw (αλλάζει αυτόματα από το `memory-core`)· ρυθμίστε `plugins.entries.agentmemory.hooks.allowConversationAccess=true` αλλιώς η καταγραφή γύρων μπλοκάρεται σιωπηλά. Δείτε [`integrations/openclaw`](../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 plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` και μετά `codex plugin add agentmemory@agentmemory`. Καταχωρεί MCP + 6 hooks κύκλου ζωής + 17 skills. Εμπιστευτείτε τα hooks και επιβεβαιώστε την καταγραφή στο host σας· δείτε [ρύθμιση και επικύρωση του Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (MCP only)** | `opencode.json` | Διαφορετική μορφή: κλειδί `mcp` στο ανώτατο επίπεδο, η εντολή ως array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (full plugin)** | `plugin/opencode/` | 22 hooks αυτόματης καταγραφής που καλύπτουν τον κύκλο ζωής συνεδρίας, τα μηνύματα, τα εργαλεία, τα σφάλματα. Η απόδοση σε project γίνεται ανά συνεδρία, οπότε μία διαδικασία OpenCode που εκτείνεται σε πολλά αποθετήρια καταχωρεί κάθε συνεδρία στο δικό της project. Δύο εντολές με slash (`/recall`, `/remember`). Αντιγράψτε το `plugin/opencode/` στον χώρο εργασίας σας OpenCode και προσθέστε την καταχώρηση του plugin στο `opencode.json`. Δείτε το [`plugin/opencode/README.md`](../plugin/opencode/README.md) για τον πλήρη πίνακα hooks + ανάλυση κενών. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Το `agentmemory connect pi` εγκαθιστά την ενσωματωμένη extension στον κατάλογο αυτόματης ανίχνευσης του pi (ανάκληση στην εκκίνηση του agent, καταγραφή στο τέλος του agent, εργαλεία `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). Το `/reload` σε ένα ενεργό pi το παραλαμβάνει. Το [`integrations/pi`](../integrations/pi/) είναι επίσης πακέτο pi (`pi install ./integrations/pi` από ένα checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` δίνει τον πάροχο μνήμης με 6 hooks (prefetch, καταγραφή γύρου, τέλος συνεδρίας, pre-compress, αντικατοπτρισμό MEMORY.md, block system prompt). Επιβεβαιώστε με `hermes plugins doctor` και `hermes memory status`. Δείτε [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | Το `agentmemory connect qwen` γράφει το τυπικό block `mcpServers`. Το payload των hooks είναι συμβατό ως προς τα πεδία με το Claude Code, οπότε τα υπάρχοντα 12 scripts hooks λειτουργούν χωρίς τροποποίηση· συνδέστε τα μέσω της ενότητας `hooks` στο ίδιο `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | Το `agentmemory connect antigravity --with-hooks` εγκαθιστά το MCP και τα hooks καταγραφής στον κοινόχρηστο κατάλογο προσαρμογής. Δείτε [ρύθμιση και περιορισμοί Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | Το `agentmemory connect antigravity-cli --with-hooks` χρησιμοποιεί την ίδια ρύθμιση MCP και hooks με τις τρέχουσες εκδόσεις IDE. Οι υπάρχουσες εγκαταστάσεις πρέπει να ανανεωθούν με `--force`· δείτε τις [σημειώσεις αναβάθμισης](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | Το `agentmemory connect kiro` γράφει τις ρυθμίσεις σε επίπεδο χρήστη. Οι παρακάμψεις workspace μπαίνουν στο `.kiro/settings/mcp.json` δίπλα στον κώδικά σας. |
+| **Warp** | `~/.warp/.mcp.json` | Το `agentmemory connect warp` γράφει το τυπικό block `mcpServers`. Το Warp επίσης ανακαλύπτει αυτόματα skills από το `.claude/skills/`· μόλις εγκατασταθεί το plugin του Claude Code, τα 8 skills του agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) εμφανίζονται εγγενώς στην παλέτα εντολών slash του Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | Το `agentmemory connect cline` γράφει το τυπικό block `mcpServers`. Χρήστες της extension VS Code: επικολλήστε το ίδιο block μέσω Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (προτιμώμενο) ή `config.json` (παλαιό) | Το `agentmemory connect continue` δημιουργεί το `config.yaml` από την αρχή όταν δεν υπάρχει κανένα από τα δύο, ή τροποποιεί το υπάρχον `config.json`. **Αν έχετε ήδη `config.yaml`**, ο adapter εκτυπώνει το ακριβές block για επικόλληση κάτω από το `mcpServers:`· δεν ξαναγράφει σιωπηλά το yaml σας, επειδή η ασφαλής διατήρηση σχολίων και anchors απαιτεί έναν YAML parser που το πακέτο δεν διαθέτει. Το Continue χρησιμοποιεί μορφή array (όχι object) για το `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | Το `agentmemory connect zed` γράφει κάτω από το `context_servers` (το κλειδί του Zed, ΟΧΙ `mcpServers`). Απομακρυσμένοι διακομιστές MCP μπορούν να συνδεθούν εναλλακτικά μέσω `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | Το `agentmemory connect droid` γράφει το τυπικό block `mcpServers`. Οι παρακάμψεις σε επίπεδο project μπαίνουν στο `/.factory/mcp.json`. Περάστε `--with-hooks` για εγγενή αυτόματη καταγραφή. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Το `agentmemory connect dsh` προσθέτει μια γραμμή `@deepseek-ai/dsh-mcp-client` στο επίπεδο patch home που φορτώνει κάθε προφίλ Harness· τα εργαλεία καταχωρούνται ως `mcp__agentmemory__*`. Περάστε `--with-hooks` για να συνδέσετε επίσης την αυτόματη καταγραφή: τα ενσωματωμένα scripts hooks του Claude Code εκτελούνται μέσω της πρωτογενούς γέφυρας `@deepseek-ai/dsh-hooks-claude-code` του Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) μέσω ενός manifest που γράφεται στο `$DSH_HOME/agentmemory.hooks.json`. Προεπιλέγει στο `~/.dsh` όταν το `DSH_HOME` δεν έχει ρυθμιστεί. |
+| **Goose** | Settings UI MCP του Goose | Το ίδιο block `mcpServers`· χρησιμοποιήστε `goose configure` → Add Extension → MCP. Υποστηρίζεται άμεση επεξεργασία YAML στο `~/.config/goose/config.yaml`, αλλά το σχήμα χρησιμοποιεί `extensions:` + `cmd` (όχι `mcpServers:` + `command`). |
+| **Aider** | n/a | Επικοινωνήστε απευθείας με το REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Οποιοσδήποτε agent (32+)** | n/a | Το `npx skillkit install agentmemory` ανιχνεύει αυτόματα τον host και συγχωνεύει. |
+
+**Sandboxed MCP clients** (Flatpak / Snap / περιορισμένα containers) που δεν μπορούν να φτάσουν το `localhost` του host: ρυθμίστε επίσης `"AGENTMEMORY_FORCE_PROXY": "1"` στο block `env`, και δείξτε το `AGENTMEMORY_URL` σε μια διαδρομή που το sandbox μπορεί πράγματι να φτάσει (π.χ. η IP του LAN σας).
+
+### Προγραμματιστική πρόσβαση (Python / Rust / Node)
+
+Το agentmemory καταχωρεί τις βασικές λειτουργίες του ως iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Κάθε γλώσσα με ένα iii SDK μπορεί να τα καλέσει απευθείας μέσω `ws://localhost:49134`, χωρίς ξεχωριστό REST client ανά γλώσσα.
+
+```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). Το REST στη θύρα `:3111` παραμένει διαθέσιμο για hosts χωρίς iii runtime.
+
+### Από τον πηγαίο κώδικα
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Αυτό ξεκινά το agentmemory με τοπικό `iii-engine` αν το καθορισμένο binary είναι ήδη εγκατεστημένο, ή χρησιμοποιεί Docker Compose όταν επιλεγεί. Το REST, τα streams, και το viewer συνδέονται στο `127.0.0.1` από προεπιλογή. Η αυτόματη διαδρομή binary για macOS/Linux απαιτεί `curl`, ένα POSIX `sh`, και `tar`.
+
+Εγκαταστήστε τον `iii-engine` χειροκίνητα. **Το agentmemory προς το παρόν καθορίζει τον `iii-engine` στην `v0.22.1`**, την ίδια έκδοση με την εξάρτηση `iii-sdk` του· ο worker μιλά το wire protocol αυτού του engine, και η έκδοση 0.20.0 αναδιοργάνωσε την επιφάνεια του SDK, οπότε οι δύο κινούνται μαζί στις εκδόσεις του agentmemory. Παρακάμψτε με `AGENTMEMORY_III_VERSION=` αν τρέχετε τον δικό σας engine και γνωρίζετε ότι ταιριάζει.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** αντικαταστήστε το `aarch64-apple-darwin` με `x86_64-apple-darwin`
+- **Linux x64:** αντικαταστήστε με `x86_64-unknown-linux-gnu`
+- **Linux arm64:** αντικαταστήστε με `aarch64-unknown-linux-gnu`
+- **Windows:** κατεβάστε το `iii-x86_64-pc-windows-msvc.zip` από το [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) και εξάγετε το `iii.exe` στο `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Κάθε αρχείο archive έχει ένα αντίστοιχο αρχείο `.sha256` στη σελίδα έκδοσης· όταν αλλάζετε πλατφόρμα, χρησιμοποιήστε το hash αυτού του αρχείου στον παραπάνω έλεγχο (σε Windows: `Get-FileHash`). Ο αυτόματος installer στο `npx @agentmemory/agentmemory` καθορίζει αυτά τα hashes και αρνείται ένα archive που δεν ταιριάζει.
+
+Ή χρησιμοποιήστε Docker (το ενσωματωμένο `docker-compose.yml` κατεβάζει το `iiidev/iii:0.22.1`). Πλήρη docs: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+Το agentmemory τρέχει σε Windows 10/11, αλλά το πακέτο Node.js από μόνο του δεν αρκεί· χρειάζεστε επίσης το καθορισμένο runtime iii-engine v0.22.1 ως διαδικασία παρασκηνίου. Το CLI δεν εξάγει αυτόματα το Windows ZIP, οπότε οι χρήστες native Windows πρέπει να εγκαταστήσουν το `iii.exe` χειροκίνητα, να χρησιμοποιήσουν WSL2, ή να επιλέξουν Docker Desktop.
+
+Η αυτοματοποιημένη σύνδεση MCP σε native Windows υποστηρίζει μόνο το `agentmemory connect copilot-cli`. Για το Claude Code, το Codex, το Cursor, και κάθε άλλο native Windows agent, αντιγράψτε το χειροκίνητο block MCP από το [Άλλοι agents](#other-agents) στις ρυθμίσεις Windows αυτού του agent. Η εκτέλεση του `connect` σε WSL είναι κατάλληλη μόνο όταν ο στόχος-agent είναι εγκατεστημένος επίσης στο ίδιο περιβάλλον WSL· δεν επεξεργάζεται τις ρυθμίσεις ενός agent που τρέχει σε Windows host.
+
+**Επιλογή A: προκατασκευασμένο binary για Windows (προτείνεται)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Επιλογή B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Επιλογή C: μόνο αυτόνομο MCP (χωρίς engine).** Αν χρειάζεστε μόνο τα εργαλεία MCP για τον agent σας και δεν χρειάζεστε το REST API, το viewer, ή τις εργασίες cron, παραλείψτε εντελώς τον engine:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Διαγνωστικά για Windows:** αν το `npx -y @agentmemory/agentmemory@latest` αποτύχει, εκτελέστε το ξανά με `--verbose` για να δείτε το πραγματικό stderr του engine. Συχνοί τρόποι αποτυχίας:
+
+| Σύμπτωμα | Διόρθωση |
+|---|---|
+| `The engine process started but the REST API never responded.` | Επιβεβαιώστε ότι είναι ελεύθερες όλες οι τέσσερις παραγόμενες θύρες, επιβεβαιώστε ότι το καθορισμένο `iii.exe` παρέμεινε ενεργό, και μετά εκτελέστε ξανά με `--verbose` και εξετάστε το καταγεγραμμένο stderr του engine |
+| `Could not start iii-engine` | Δεν είναι εγκατεστημένο ούτε το `iii.exe` ούτε το Docker. Δείτε την Επιλογή A ή B παραπάνω |
+| Σύγκρουση θύρας | `netstat -ano \| findstr :3111` για να δείτε τι είναι δεσμευμένο, και μετά σκοτώστε τη διαδικασία ή χρησιμοποιήστε `--port ` |
+| Η εναλλακτική λύση Docker παραλείπεται παρόλο που το Docker είναι εγκατεστημένο | Σιγουρευτείτε ότι το Docker Desktop τρέχει πράγματι (εικονίδιο system tray) |
+
+> Σημείωση: ο **engine** του iii είναι ένα προκατασκευασμένο binary, όχι ένα cargo crate, οπότε μην προσπαθήσετε να το κάνετε `cargo install`. (Τα **SDKs** του iii δημοσιεύονται στα crates.io, npm, και PyPI, αλλά το agentmemory δεν τα χρειάζεται.) Οι υποστηριζόμενες μέθοδοι εγκατάστασης του engine είναι όλες καθορισμένες στην v0.22.1: το προκατασκευασμένο binary παραπάνω, η αυτόματη διαδρομή εγκατάστασης macOS/Linux του agentmemory (απαιτούνται `curl`, POSIX `sh`, και `tar`), και η εικόνα Docker `iiidev/iii:0.22.1`. Ένα απλό upstream `install.sh | sh` εγκαθιστά τον τελευταίο engine, που το agentmemory δεν υποστηρίζει. Χρησιμοποιήστε `npx -y @agentmemory/agentmemory@latest`· σε macOS/Linux κατεβάζει τον καθορισμένο engine στο `~/.agentmemory/bin`.
+
+---
+
+
Ανάπτυξη
+
+Πρότυπα ανάπτυξης με ένα κλικ για διαχειριζόμενους hosts. Καθένα διανέμει ένα αυτόνομο Dockerfile που κατεβάζει το `@agentmemory/agentmemory` από το npm και αντιγράφει το binary του iii engine από την επίσημη εικόνα `iiidev/iii` του Docker Hub· δεν απαιτείται προκατασκευασμένη εικόνα agentmemory. Η μόνιμη αποθήκευση γίνεται mount στο `/data`· το entrypoint της πρώτης εκκίνησης αντικαθιστά τις ρυθμίσεις iii που διανέμονται με το npm (οι οποίες συνδέονται στο `127.0.0.1`) με μια προσαρμοσμένη για ανάπτυξη έκδοση που συνδέεται στο `0.0.0.0` και χρησιμοποιεί απόλυτες διαδρομές `/data`, δημιουργεί το HMAC secret, και μετά μειώνει τα δικαιώματα από `root` σε `node` μέσω του `gosu` πριν εκτελέσει (exec) το CLI του agentmemory.
+
+
+
+
+
+
+Το κουμπί ανάπτυξης με ένα κλικ του Render απαιτεί `render.yaml` στη ρίζα του αποθετηρίου, το οποίο σκόπιμα το κρατάμε καθαρό. Χρησιμοποιήστε τη ροή Render Blueprint που τεκμηριώνεται στο [`deploy/render/`](.././deploy/render/README.md) για να δείξετε χειροκίνητα στο blueprint εντός του αποθετηρίου.
+
+Πλήρεις λεπτομέρειες ρύθμισης (καταγραφή HMAC, SSH tunnel για το viewer, περιστροφή, αντίγραφα ασφαλείας,
+ελάχιστο κόστος) βρίσκονται στο [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): μία μηχανή με
+ `auto_stop_machines = "stop"`· το πιο οικονομικό σε αδράνεια.
+- [`deploy/railway`](.././deploy/railway/README.md): σταθερή χρέωση στο πλάνο Hobby,
+ volume μέσα από το dashboard.
+- [`deploy/render`](.././deploy/render/README.md): ροή Blueprint,
+ αυτόματα snapshots δίσκου στα επί πληρωμή πλάνα.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted στο δικό σας
+ VPS μέσω του [Coolify](https://coolify.io/self-hosted)· το ίδιο Docker
+ Compose stack, εσείς κατέχετε τον host και τα δεδομένα.
+
+Δημοσιεύεται μόνο η θύρα `3111`. Το viewer στη `3113` παραμένει συνδεδεμένο στο
+loopback εντός του container· το README κάθε προτύπου τεκμηριώνει το μοτίβο
+SSH-tunnel για να το προσεγγίσετε.
+
+---
+
+
+
+Κάθε agent κώδικα ξεχνά τα πάντα όταν τελειώνει η συνεδρία, και κάθε νέα συνεδρία ξεκινά με εσάς να εξηγείτε ξανά το 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
+
+Κάθε AI agent κώδικα διαθέτει ενσωματωμένη μνήμη: το Claude Code έχει `MEMORY.md`, το Cursor έχει notepads, το Cline έχει memory bank. Αυτά λειτουργούν σαν αυτοκόλλητα σημειωματάρια (sticky notes). Το agentmemory είναι η αναζητήσιμη βάση δεδομένων πίσω από τα sticky notes.
+
+| | Ενσωματωμένο (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Κλίμακα | Όριο 200 γραμμών | Απεριόριστο |
+| Αναζήτηση | Φορτώνει τα πάντα στο context | BM25 + vector + graph (μόνο top-K) |
+| Κόστος tokens | 22K+ σε 240 παρατηρήσεις | ~1,900 tokens (92% λιγότερο) |
+| Μεταξύ agents | Αρχεία ανά agent | MCP + REST (οποιοσδήποτε agent) |
+| Συντονισμός | Κανένας | Leases, signals, actions, routines |
+| Παρατηρησιμότητα | Χειροκίνητη ανάγνωση αρχείων | Viewer σε πραγματικό χρόνο στη :3113 |
+
+---
+
+
+
+### Αγωγός Μνήμης
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### Ενοποίηση Μνήμης 4 Επιπέδων
+
+Βασίζεται στον τρόπο που ο ανθρώπινος εγκέφαλος επεξεργάζεται τη μνήμη, συμπεριλαμβανομένης της ενοποίησης κατά τον ύπνο.
+
+| Επίπεδο | Τι | Αναλογία |
+|------|------|---------|
+| **Εργαζόμενη** | Ανεπεξέργαστες παρατηρήσεις από τη χρήση εργαλείων | Βραχυπρόθεσμη μνήμη |
+| **Επεισοδιακή** | Συμπιεσμένες περιλήψεις συνεδριών | "Τι συνέβη" |
+| **Σημασιολογική** | Εξαγόμενα γεγονότα και μοτίβα | "Τι γνωρίζω" |
+| **Διαδικαστική** | Ροές εργασίας και μοτίβα αποφάσεων | "Πώς να το κάνω" |
+
+Οι μνήμες φθίνουν με τον χρόνο (καμπύλη Ebbinghaus). Οι μνήμες που προσπελαύνονται συχνά ενισχύονται. Οι μπαγιάτικες μνήμες εκδιώκονται αυτόματα. Οι αντιφάσεις εντοπίζονται και επιλύονται.
+
+### Τι Καταγράφεται
+
+| Hook | Καταγράφει |
+|------|----------|
+| `SessionStart` | Διαδρομή project, ID συνεδρίας |
+| `UserPromptSubmit` | Prompts χρήστη (φιλτραρισμένα για ιδιωτικότητα) |
+| `PreToolUse` | Μοτίβα πρόσβασης αρχείων + ενριχυμένο context |
+| `PostToolUse` | Όνομα εργαλείου, είσοδος, έξοδος |
+| `PostToolUseFailure` | Context σφάλματος |
+| `PreCompact` | Επανεισάγει τη μνήμη πριν από τη συμπίεση (compaction) |
+| `SubagentStart/Stop` | Κύκλος ζωής sub-agent |
+| `Stop` | Περίληψη τέλους συνεδρίας |
+| `SessionEnd` | Δείκτης ολοκλήρωσης συνεδρίας |
+
+### Βασικές Δυνατότητες
+
+| Δυνατότητα | Περιγραφή |
+|---|---|
+| **Αυτόματη καταγραφή** | Κάθε χρήση εργαλείου καταγράφεται μέσω hooks, χωρίς χειροκίνητη προσπάθεια |
+| **Σημασιολογική αναζήτηση** | BM25 + vector + γράφος γνώσης με συγχώνευση RRF |
+| **Εξέλιξη μνήμης** | Versioning, αντικατάσταση (supersession), γράφοι σχέσεων |
+| **Υγιεινή ανάκλησης** | Οι αντικατεστημένες εκδόσεις μνήμης αφαιρούνται από τα ευρετήρια αναζήτησης· η αλυσίδα εκδόσεων στο KV διατηρεί το πλήρες ιστορικό |
+| **Υποδείξεις σχεδόν-διπλότυπων** | Οι αποθηκεύσεις αναφέρουν μια συμβουλευτική αντιστοίχιση `similarTo` όταν νέο περιεχόμενο μοιάζει πολύ με μια υπάρχουσα μνήμη |
+| **Εμβέλεια ανά agent** | Το `agentId` διαπερνά την αποθήκευση και την ανάκληση σε REST, MCP, και το ευρετήριο αναζήτησης, σε λειτουργία shared ή isolated |
+| **Προέλευση κατά τη συγγραφή** | Κάθε παρατήρηση και μνήμη φέρει ένα αμετάβλητο κανάλι προέλευσης (user, agent, tool, import, ή shared) που σημαίνεται κατά την καταγραφή, την αποθήκευση, και την εισαγωγή |
+| **Αυτόματη διαγραφή** | Λήξη TTL, εντοπισμός αντιφάσεων, εκδίωξη βάσει σημασίας |
+| **Ιδιωτικότητα πρώτα** | Τα κλειδιά API, τα μυστικά, και οι ετικέτες `` αφαιρούνται πριν από την αποθήκευση |
+| **Αυτοθεραπεία** | Circuit breaker, αλυσίδα εναλλακτικών providers, παρακολούθηση υγείας |
+| **Γέφυρα Claude** | Αμφίδρομος συγχρονισμός με το MEMORY.md |
+| **Γράφος γνώσης** | Εξαγωγή οντοτήτων + διάσχιση BFS |
+| **Μνήμη ομάδας** | Κοινή + ιδιωτική μνήμη με namespace μεταξύ μελών της ομάδας |
+| **Προέλευση παραπομπών** | Ανίχνευση κάθε μνήμης πίσω στις αρχικές παρατηρήσεις |
+| **Στιγμιότυπα Git** | Version, rollback, και diff της κατάστασης μνήμης |
+
+---
+
+
+
+Ανάκτηση τριπλής ροής που συνδυάζει τρία σήματα:
+
+| Ροή | Τι κάνει | Πότε |
+|---|---|---|
+| **BM25** | Αντιστοίχιση λέξεων-κλειδιών με stemming και επέκταση συνωνύμων | Πάντα ενεργό |
+| **Vector** | Ομοιότητα συνημιτόνου πάνω σε πυκνά embeddings | Έχει ρυθμιστεί πάροχος embedding |
+| **Graph** | Διάσχιση γράφου γνώσης μέσω αντιστοίχισης οντοτήτων | Εντοπίζονται οντότητες στο ερώτημα |
+
+Συγχωνεύονται με Reciprocal Rank Fusion (RRF, k=60) και διαφοροποιούνται ανά συνεδρία (έως 3 αποτελέσματα ανά συνεδρία).
+
+Όταν ένα ευρετήριο vector είναι γεμάτο, το `mem::search` (πίσω από το `memory_recall`) χρησιμοποιεί τον υβριδικό ranker BM25 + vector. Χωρίς embeddings χρησιμοποιεί BM25. Το `smart-search` μπορεί επιπλέον να συγχωνεύσει δομικές αντιστοιχίσεις γράφου όταν υπάρχουν δεδομένα γράφου, ακόμα και σε λειτουργία χωρίς κλειδί. Η ανάκληση μαθημάτων (lesson recall) τρέχει σε ένα αποκλειστικό in-memory ευρετήριο BM25 αντί να σκανάρει όλο το corpus σε κάθε ερώτημα. Οι αντικατεστημένες εκδόσεις μνήμης αποκλείονται από κάθε διαδρομή ανάκλησης· η αλυσίδα εκδόσεων διατηρεί το ιστορικό τους.
+
+Τα vectors επιβιώνουν από ένα crash ή force-kill. Το ευρετήριο vector αποθηκεύεται σε buckets το πολύ κάθε `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 λεπτά). Κάθε vector που προστίθεται ή αφαιρείται στο ενδιάμεσο γράφεται επίσης αμέσως σε ένα μικρό εκκρεμές log στο state store, και η επόμενη εκκίνηση το αναπαράγει χωρίς να καλέσει τον πάροχο embedding. Κάθε επιτυχημένη αποθήκευση αδειάζει το log. Τα έγγραφα που εξακολουθούν να μην έχουν vector μετά την αναπαραγωγή επανα-embeddάρονται στο παρασκήνιο σε batches των `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) μέχρι να μην απομείνει κανένα, και ένα backfill που διακόπτεται συνεχίζει στην επόμενη εκκίνηση. Το `/agentmemory/status` και το viewer δείχνουν το μέγεθος του εκκρεμούς log και την κατάσταση του backfill. Οι εγκαταστάσεις χωρίς κλειδί δεν γράφουν τίποτα.
+
+Το BM25 κάνει tokenize Ελληνικά, Κυριλλικά, Εβραϊκά, Αραβικά, και τονισμένα Λατινικά απευθείας. Για μνήμες στα Κινεζικά / Ιαπωνικά / Κορεατικά, εγκαταστήστε τους προαιρετικούς segmenters (`npm install @node-rs/jieba tiny-segmenter`) για να χωρίσετε τις ακολουθίες CJK σε tokens επιπέδου λέξης· χωρίς αυτούς, το agentmemory υποχωρεί ομαλά σε tokenization ολόκληρης της ακολουθίας και εκτυπώνει μία υπόδειξη, μία φορά, στο stderr.
+
+### Πάροχοι Embedding
+
+Οι εγκαταστάσεις χωρίς κλειδί απενεργοποιούν τα vector embeddings: το `mem::search` χρησιμοποιεί BM25, ενώ το `smart-search` μπορεί επίσης να χρησιμοποιήσει υπάρχοντα δομικά δεδομένα γράφου. Για να ενεργοποιήσετε δωρεάν σημασιολογικά embeddings στη συσκευή, προσθέστε αυτό στο `~/.agentmemory/.env` και κάντε επανεκκίνηση του agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Η κανονική εγκατάσταση npm περιλαμβάνει το προαιρετικό runtime `@huggingface/transformers`. Το πρώτο αίτημα embedding κατεβάζει το `Xenova/all-MiniLM-L6-v2`, οπότε χρειάζεται πρόσβαση στο δίκτυο και μπορεί να διαρκέσει περισσότερο· η επόμενη εξαγωγή συμπερασμάτων τρέχει στη συσκευή. Οι απομακρυσμένοι πάροχοι ανιχνεύονται αυτόματα από τα κλειδιά τους, εκτός αν το `EMBEDDING_PROVIDER` τους παρακάμψει.
+
+| Πάροχος | Μοντέλο | Κόστος | Σημειώσεις |
+|---|---|---|---|
+| **Τοπικό (προτεινόμενη ενεργοποίηση)** | `all-MiniLM-L6-v2` | Δωρεάν | Στη συσκευή μετά την πρώτη λήψη μοντέλου, +8pp ανάκληση σε σχέση με μόνο BM25 |
+| Gemini | `gemini-embedding-001` | Δωρεάν βαθμίδα | 100+ γλώσσες, διαστάσεις 768/1536/3072 (MRL), είσοδος 2048 tokens. Αντικαθιστά το `text-embedding-004` ([καταργήθηκε, διακοπή στις 14 Ιαν 2026](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 | Οποιοδήποτε μοντέλο | Διαφέρει | Proxy πολλών μοντέλων |
+
+---
+
+
+
+54 εργαλεία, 6 πόροι, 3 προτροπές, και 17 skills.
+
+> **MCP shim έναντι πλήρους διακομιστή:** το δημοσιευμένο πακέτο `@agentmemory/mcp` είναι ένα λεπτό shim. Εκθέτει την πλήρη επιφάνεια των 54 εργαλείων **μόνο όταν μπορεί να φτάσει έναν ενεργό διακομιστή agentmemory** μέσω του `AGENTMEMORY_URL` (λειτουργία proxy). Χωρίς προσβάσιμο διακομιστή, το shim επιστρέφει σε ένα τοπικό σύνολο 7 εργαλείων (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Η μεταβλητή περιβάλλοντος `AGENTMEMORY_TOOLS=core|all` είναι μια σημαία *από την πλευρά του διακομιστή*· η ρύθμισή της στο block `env` του shim δεν έχει καμία επίδραση. Αν βλέπετε μόνο 7 εργαλεία στο Cursor / OpenCode / Gemini CLI, ξεκινήστε το `npx -y @agentmemory/agentmemory@latest` (ή το Docker stack) και ρυθμίστε `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 Εργαλεία
+
+Τρεις επιφάνειες εργαλείων, από τη μικρότερη στη μεγαλύτερη: το `AGENTMEMORY_TOOLS=core` περιορίζει την ορατότητα σε 8 βασικά εργαλεία (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`)· το βασικό σύνολο παρακάτω είναι τα 14 θεμελιώδη εργαλεία του registry· η προεπιλογή (`AGENTMEMORY_TOOLS=all`) εκθέτει όλα τα 54.
+
+
+Βασικά εργαλεία (14)
+
+| Εργαλείο | Περιγραφή |
+|------|-------------|
+| `memory_recall` | Αναζήτηση παλαιότερων παρατηρήσεων |
+| `memory_compress_file` | Συμπίεση αρχείων markdown με διατήρηση της δομής |
+| `memory_save` | Αποθήκευση μιας διαπίστωσης, απόφασης, ή μοτίβου |
+| `memory_file_history` | Παλαιότερες παρατηρήσεις για συγκεκριμένα αρχεία |
+| `memory_patterns` | Εντοπισμός επαναλαμβανόμενων μοτίβων |
+| `memory_sessions` | Λίστα πρόσφατων συνεδριών |
+| `memory_smart_search` | Υβριδική σημασιολογική + αναζήτηση λέξεων-κλειδιών |
+| `memory_vision_search` | Αναζήτηση παρατηρήσεων εικόνων |
+| `memory_timeline` | Χρονολογικές παρατηρήσεις |
+| `memory_profile` | Προφίλ project (concepts, αρχεία, μοτίβα) |
+| `memory_export` | Εξαγωγή όλων των δεδομένων μνήμης |
+| `memory_relations` | Ερώτημα γράφου σχέσεων |
+| `memory_commit_lookup` | Συνεδρίες πίσω από ένα git commit |
+| `memory_commits` | Commits καταγεγραμμένα για μια συνεδρία |
+
+
+
+
+Εκτεταμένα εργαλεία (54 σύνολο, η προεπιλεγμένη επιφάνεια)
+
+| Εργαλείο | Περιγραφή |
+|------|-------------|
+| `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` | Ιστορικό ελέγχου (audit trail) λειτουργιών |
+| `memory_governance_delete` | Διαγραφή με ιστορικό ελέγχου |
+| `memory_snapshot_create` | Στιγμιότυπο με έκδοση Git |
+| `memory_action_create` | Δημιουργία στοιχείων εργασίας με εξαρτήσεις |
+| `memory_action_update` | Ενημέρωση κατάστασης ενέργειας |
+| `memory_frontier` | Ξεμπλοκαρισμένες ενέργειες κατά σειρά προτεραιότητας |
+| `memory_next` | Η μία πιο σημαντική επόμενη ενέργεια |
+| `memory_lease` | Αποκλειστικά leases ενεργειών (πολλών agents) |
+| `memory_routine_run` | Δημιουργία στιγμιότυπων ρουτινών ροής εργασίας |
+| `memory_signal_send` | Ανταλλαγή μηνυμάτων μεταξύ agents |
+| `memory_signal_read` | Ανάγνωση μηνυμάτων με αποδείξεις παραλαβής |
+| `memory_checkpoint` | Πύλες εξωτερικών συνθηκών |
+| `memory_mesh_sync` | Συγχρονισμός P2P μεταξύ instances |
+| `memory_sentinel_create` | Παρατηρητές βάσει events |
+| `memory_sentinel_trigger` | Ενεργοποίηση sentinels εξωτερικά |
+| `memory_sketch_create` | Προσωρινοί γράφοι ενεργειών |
+| `memory_sketch_promote` | Προβιβασμός σε μόνιμο |
+| `memory_crystallize` | Συμπύκνωση αλυσίδων ενεργειών |
+| `memory_diagnose` | Έλεγχοι υγείας |
+| `memory_heal` | Αυτόματη διόρθωση κολλημένης κατάστασης |
+| `memory_facet_tag` | Ετικέτες dimension:value |
+| `memory_facet_query` | Ερώτημα βάσει ετικετών facet |
+| `memory_verify` | Ανίχνευση προέλευσης |
+
+
+
+### 6 Πόροι · 3 Προτροπές · 17 Skills
+
+| Τύπος | Όνομα | Περιγραφή |
+|------|------|-------------|
+| Πόρος | `agentmemory://status` | Υγεία, αριθμός συνεδριών, αριθμός μνημών |
+| Πόρος | `agentmemory://project/{name}/profile` | Ευφυΐα ανά project |
+| Πόρος | `agentmemory://project/{name}/recent` | Πρόσφατες παρατηρήσεις για ένα project |
+| Πόρος | `agentmemory://memories/latest` | Τελευταίες 10 ενεργές μνήμες |
+| Πόρος | `agentmemory://graph/stats` | Στατιστικά γράφου γνώσης |
+| Πόρος | `agentmemory://team/{id}/profile` | Κοινό προφίλ ομάδας |
+| Προτροπή | `recall_context` | Αναζήτηση + επιστροφή μηνυμάτων context |
+| Προτροπή | `session_handoff` | Δεδομένα handoff μεταξύ agents |
+| Προτροπή | `detect_patterns` | Ανάλυση επαναλαμβανόμενων μοτίβων |
+| Skill | `/recall` | Αναζήτηση μνήμης |
+| Skill | `/remember` | Αποθήκευση σε μακροπρόθεσμη μνήμη |
+| Skill | `/session-history` | Πρόσφατες περιλήψεις συνεδριών |
+| Skill | `/forget` | Διαγραφή παρατηρήσεων/συνεδριών |
+
+Ο πίνακας δείχνει τα τέσσερα βασικά skills. Το πλήρες σύνολο είναι 9 επικλητά skills συν 8 skills αναφοράς· δείτε την ενότητα Εγγενή skills παραπάνω.
+
+### Αυτόνομο MCP
+
+Εκτελέστε χωρίς τον πλήρη διακομιστή, για οποιονδήποτε MCP client. Οποιοδήποτε από τα δύο λειτουργεί:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Ή προσθέστε στις ρυθμίσεις MCP του agent σας:
+
+Οι περισσότεροι agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Συγχωνεύστε την καταχώρηση `agentmemory` στο υπάρχον αντικείμενο `mcpServers` του host σας αντί να αντικαταστήσετε το αρχείο. Για sandboxed clients που δεν μπορούν να φτάσουν το `localhost` του host, προσθέστε `"AGENTMEMORY_FORCE_PROXY": "1"` στο block env και ρυθμίστε το `AGENTMEMORY_URL` σε μια διαδρομή που το sandbox μπορεί να φτάσει.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Αντιγράψτε το αρχείο plugin από το αποθετήριο:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Ξεκινά αυτόματα στη θύρα `3113`. Το viewer φορτώνει ένα snapshot όταν συνδέεται (`GET /agentmemory/viewer/snapshot`) και μετά εφαρμόζει live stream events: νέες μνήμες, μαθήματα, παρατηρήσεις, καταχωρήσεις audit, αλλαγές γράφου, και ενημερώσεις υγείας εμφανίζονται χωρίς polling ή επαναφόρτωση σελίδας. Τα μόνα άλλα αιτήματα είναι οι ενέργειες που κάνετε κλικ, οι σελίδες "load more" και οι αναζητήσεις. Όταν το stream διακόπτεται, το viewer δείχνει πόσο παλιά είναι οι αριθμοί του, επανασυνδέεται με backoff και επανασυγχρονίζεται από ένα snapshot.
+
+- **12 καρτέλες σε τέσσερις ομάδες** με ζωντανές μετρήσεις, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), συντομεύσεις πληκτρολογίου, και ένα μενού για κινητά.
+- **Memories:** αναζήτηση από την πλευρά του server, φίλτρα ανά project, agent, και τύπο, ένα πάνελ λεπτομερειών με την αλυσίδα εκδόσεων και ένα word diff, συνδέσμους προέλευσης, κουμπιά αντιγραφής για το id, την κλήση MCP, και μια εντολή curl, επεξεργασία (νέα έκδοση), forget με επιβεβαίωση, μαζικό forget, και εξαγωγή JSON.
+- **Sessions:** ένα ενσωματωμένο timeline παρατηρήσεων με ευανάγνωστη είσοδο και έξοδο εργαλείων, φίλτρα και paging, και τις μνήμες και τα μαθήματα που παρήγαγε κάθε συνεδρία.
+- **Graph:** αναζήτηση, λεπτομέρειες κόμβου με σχέσεις και πηγές, ένα υπόμνημα που δεν βασίζεται μόνο στο χρώμα, και χειριστήρια zoom.
+- **Health:** η ζωντανή έκδοση του `GET /agentmemory/status`. Κάθε πρόβλημα συνοδεύεται από τη διόρθωσή του, καθώς και το state backend, την κατάσταση αποθήκευσης ευρετηρίου, την πρόοδο συμπύκνωσης προέλευσης γράφου, και έναν επεξηγητή ενοποίησης με τα πραγματικά thresholds.
+- Σελίδες **Audit, Activity, Profile, Replay, Lessons, Actions, και Crystals**, καθεμία με μια κενή κατάσταση που εξηγεί τι είναι η ενότητα, γιατί είναι κενή, και την εντολή που τη γεμίζει, καθώς και ένα tooltip γλωσσαρίου `?` σε κάθε όρο και αριθμό.
+
+```bash
+open http://localhost:3113
+```
+
+Ο διακομιστής του viewer συνδέεται στο `127.0.0.1` από προεπιλογή και επισυνάπτει το secret του διακομιστή όταν προωθεί αιτήματα στο REST API, οπότε δεν χρειάζεται καμία ρύθμιση. Το endpoint `/agentmemory/viewer` που εξυπηρετείται από το REST ακολουθεί τους κανονικούς κανόνες bearer-token και ανακατευθύνει τους browsers χωρίς token στη θύρα του viewer. Οι κεφαλίδες CSP χρησιμοποιούν ένα script nonce ανά απάντηση και απενεργοποιούν τα inline handler attributes (`script-src-attr 'none'`).
+
+---
+
+
+
+Το viewer στη `:3113` δείχνει τι **θυμήθηκε** ο agent σας. Η [iii console](https://iii.dev/docs/console) δείχνει τι **έκανε** ο agent σας: κάθε λειτουργία μνήμης ως trace OpenTelemetry, κάθε καταχώρηση KV επεξεργάσιμη, κάθε function επικλητή, κάθε stream προσβάσιμο. Δύο παράθυρα στην ίδια μνήμη: ένα σε σχήμα προϊόντος, ένα σε σχήμα engine.
+
+Παρακολουθήστε ένα `memory_smart_search` να ενεργοποιείται και δείτε το BM25 scan → αναζήτηση embedding → συγχώνευση RRF → reranker ως ένα waterfall. Επεξεργαστείτε ένα κολλημένο timer ενοποίησης στον KV browser. Αναπαράγετε ένα hook `PostToolUse` με ένα τροποποιημένο payload. Καρφιτσώστε (pin) το WebSocket stream και παρακολουθήστε τις παρατηρήσεις να καταφθάνουν ζωντανά.
+
+Το agentmemory το προσφέρει αυτό δωρεάν επειδή κάθε κλήση function και trigger ενεργοποιείται μέσω του iii· τίποτα προσαρμοσμένο, τίποτα να γίνει instrument.
+
+
+
+
+ Σελίδα Workers: κάθε συνδεδεμένος worker, συμπεριλαμβανομένου του ίδιου του agentmemory, με PID, αριθμό functions, runtime, και last-seen.
+
+
+**Είναι ήδη εγκατεστημένη.** Η console διανέμεται με τον καθορισμένο `iii` engine (0.22+)· δεν χρειάζεται ξεχωριστή εγκατάσταση. Η πρώτη εκκίνηση κατεβάζει το binary της console δίπλα στον engine.
+
+**Εκκίνηση παράλληλα με το agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Αυτό εκτελεί το `iii console` του καθορισμένου engine πάνω στις θύρες που επέλυσε το agentmemory (REST, streams, bridge) και το εξυπηρετεί μία θύρα πάνω από το viewer, `http://localhost:3114` από προεπιλογή. Το `--console-port N` επιλέγει άλλη θύρα· τα `--port` και `--instance` επιλέγουν το instance του agentmemory με τον ίδιο τρόπο όπως για το `stop`· κάθε άλλη σημαία περνάει αυτούσια, για παράδειγμα το `--enable-flow` για την πειραματική σελίδα γράφου αρχιτεκτονικής.
+
+Το ίδιο πράγμα χειροκίνητα, χρήσιμο όταν το `agentmemory` δεν είναι στο PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Τι μπορείτε να κάνετε από την console:**
+
+| Σελίδα | Χρησιμοποιήστε την για |
+|------|-----------|
+| **Workers** | Να δείτε κάθε συνδεδεμένο worker και τις ζωντανές μετρήσεις του, συμπεριλαμβανομένου του ίδιου του worker agentmemory. |
+| **Functions** | Να καλέσετε απευθείας οποιαδήποτε από τις functions του agentmemory με ένα JSON payload· χρήσιμο για τη δοκιμή των `memory.recall`, `memory.consolidate`, `graph.query` χωρίς να συνδέσετε έναν client. |
+| **Triggers** | Να αναπαράγετε triggers HTTP, cron, event, και state: να ενεργοποιήσετε το cron ενοποίησης χειροκίνητα, να ξαναδοκιμάσετε μια διαδρομή HTTP, να εκπέμψετε μια αλλαγή κατάστασης. |
+| **States** | Έναν KV browser με πλήρες CRUD πάνω σε sessions, memory slots, χρονόμετρα κύκλου ζωής, και το ευρετήριο embeddings· να επεξεργαστείτε τιμές επί τόπου. |
+| **Streams** | Ζωντανή παρακολούθηση WebSocket για εγγραφές μνήμης, events hooks, και ενημερώσεις παρατηρήσεων καθώς διαρρέουν μέσα από τα iii streams. |
+| **Queues** | Durable θέματα ουράς + διαχείριση dead-letter. Να αναπαράγετε ή να απορρίψετε αποτυχημένες εργασίες embedding / συμπίεσης. |
+| **Traces** | Προβολές waterfall / flame / service-breakdown του OpenTelemetry. Φιλτράρετε κατά `trace_id` για να δείτε ακριβώς ποιες functions, κλήσεις DB, και αιτήματα embedding παρήγαγε ένα μόνο `memory.search`. |
+| **Logs** | Δομημένα logs OTEL φιλτραρισμένα και συσχετισμένα με IDs trace/span. |
+| **Config** | Ρυθμίσεις runtime: δείτε ακριβώς με ποιους workers, providers, και θύρες τρέχει ο engine σας. |
+| **Flow** | (Προαιρετικό, `--enable-flow`) Διαδραστικός γράφος αρχιτεκτονικής κάθε worker, trigger, και stream. |
+
+
+
+
+ Traces: waterfall / flame / service breakdown για κάθε λειτουργία μνήμης.
+
+
+**Τα traces είναι ήδη ενεργά:**
+
+Το `iii-config.yaml` διανέμεται με ενεργοποιημένο τον worker `iii-observability` (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Δεν χρειάζεται επιπλέον ρύθμιση· τη στιγμή που ξεκινά το agentmemory, κάθε λειτουργία μνήμης εκπέμπει ένα δομημένο log που μπορεί να διαβάσει η console, και μία στις δέκα (`sampling_ratio: 0.1`) εκπέμπει επίσης ένα trace span.
+
+Αν θέλετε να εξάγετε στο Jaeger/Honeycomb/Grafana Tempo αντ' αυτού, αλλάξτε το `exporter: memory` σε `exporter: otlp` και ρυθμίστε το endpoint του collector σύμφωνα με τα docs παρατηρησιμότητας του iii.
+
+> **Σημαντική σημείωση:** δεν επιβάλλεται auth στην ίδια την console· κρατήστε τη συνδεδεμένη στο `127.0.0.1` (η προεπιλογή) και ποτέ μην την εκθέσετε δημόσια.
+
+---
+
+
+
+Το agentmemory είναι **ήδη ένα ενεργό instance του [iii](https://iii.dev)**. Τρία primitives (worker, function, trigger) συνθέτουν το runtime· η κατάσταση KV, τα streams, και τα traces OTEL προέρχονται από τους workers iii-state, iii-stream, και iii-observability που διανέμονται με το iii. Δεν εγκαταστήσατε Postgres, Redis, Express, pm2, ή Prometheus, επειδή το iii τα αντικαθιστά.
+
+Αυτό σημαίνει ότι μία ακόμα εντολή επεκτείνει το agentmemory με μια ολόκληρη νέα δυνατότητα.
+
+### Επέκταση του agentmemory με περισσότερους workers
+
+Τα builtins που χρειάζεται το agentmemory βρίσκονται ήδη στο `iii-config.yaml` και εκκινούν μαζί του: `iii-state` (KV), `iii-queue` (durable retries για τους συνδρομητές events), `iii-pubsub`, `iii-cron`, `iii-stream`, και `iii-observability` (traces OTEL, metrics, και logs σε κάθε function). Οτιδήποτε άλλο από το [iii worker registry](https://workers.iii.dev) συνδέεται στον ίδιο engine: αντιγράψτε το `iii-config.yaml` στο `~/.agentmemory/iii-config.yaml` (το CLI προτιμά αυτό το αρχείο έναντι του ενσωματωμένου, και συνεχίζει να αποδίδει θύρες και διαδρομές δεδομένων μέσα του), προσθέστε την καταχώρηση, εγκαταστήστε το runtime του worker μία φορά με `~/.agentmemory/bin/iii update worker`, και κάντε επανεκκίνηση του agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Τι αποκτάτε πάνω από το agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Προσαρμογέας κατάστασης βασισμένος σε SQL, όταν ξεπεράσετε τις προεπιλογές in-memory KV |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Κώδικας που προέκυψε από το `memory_recall` τρέχει μέσα σε ένα αναλώσιμο VM, όχι στο shell σας |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Στήστε επιπλέον διακομιστές MCP δίπλα σε αυτόν του agentmemory, μοιραζόμενοι τον ίδιο engine |
+
+Στον engine 0.22.x κρατήστε τα ονόματα με πρόθεμα `iii-` για τα builtins παραπάνω· οι καταχωρήσεις χωρίς πρόθεμα `http`, `state`, `queue`, `pubsub`, και `cron` είναι οι αυτόνομοι workers του registry στους οποίους μεταβαίνει το agentmemory με τη μετάβαση στο 0.23.
+
+Πλήρες registry: [workers.iii.dev](https://workers.iii.dev). Κάθε worker εκεί συνθέτεται μέσω των ίδιων primitives που χρησιμοποιεί το agentmemory, και το agentmemory που έχετε ήδη είναι ένα από αυτά.
+
+### Ρυθμίσεις Engine και Διεύθυνση Σύνδεσης
+
+Το `agentmemory start` διαβάζει τις ρυθμίσεις του engine από το πρώτο αρχείο που υπάρχει: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` στον τρέχοντα κατάλογο, `~/.agentmemory/iii-config.yaml`, και μετά το ενσωματωμένο `iii-config.yaml`. Σε κάθε εκκίνηση αποδίδει αυτό το αρχείο (διαδρομές δεδομένων, θύρες, state backend) στο `~/.agentmemory/data/iii-config.runtime.yaml` και ξεκινά τον engine με το αποδοθέν αντίγραφο, οπότε επεξεργαστείτε το αρχείο-πηγή, όχι το αποδοθέν. Οι τιμές `host:` του αρχείου-πηγή διατηρούνται όπως είναι γραμμένες.
+
+Το ενσωματωμένο `iii-config.yaml` συνδέεται σκόπιμα στο `127.0.0.1`, και αυτή η προεπιλογή ισχύει και μέσα σε ένα container. Ένα CLI που ξεκινά σε ένα container ακούει στο loopback του container, οπότε οι δημοσιευμένες θύρες δεν φτάνουν πουθενά. Για να εξυπηρετήσετε ένα containerized CLI μέσω δημοσιευμένων θυρών, ρυθμίστε το `AGENTMEMORY_III_CONFIG` σε ρυθμίσεις που συνδέονται στο `0.0.0.0`. Το συνοδευτικό `iii-config.docker.yaml` είναι ένα τέτοιο: συνδέει τα `iii-http`, `iii-stream`, και τη θύρα του engine στο `0.0.0.0` και αποθηκεύει την κατάσταση κάτω από το `/data`, οπότε κάντε mount έναν εγγράψιμο volume εκεί. Κρατήστε ρυθμισμένο το `AGENTMEMORY_SECRET`, και δημοσιεύστε μόνο τις θύρες που χρειάζεστε, στο `127.0.0.1` ή πίσω από ένα proxy που εμπιστεύεστε.
+
+Το `docker-compose.yml` αυτού του αποθετηρίου δεν περνάει από την αναζήτηση ρυθμίσεων του CLI: κάνει mount το `iii-config.docker.yaml` στο `/app/config.yaml`, και το container `iii-engine` ξεκινά με `--config /app/config.yaml`. Τα πρότυπα [ανάπτυξης με ένα κλικ](../deploy/) γράφουν τις δικές τους ρυθμίσεις `0.0.0.0` στα entrypoints τους.
+
+### Backend Αποθήκευσης: file (προεπιλογή) έναντι redis
+
+Τα `iii-state` και `iii-stream` χρησιμοποιούν από προεπιλογή το ενσωματωμένο file-based KV store του iii-engine: ένα αρχείο JSON ανά scope, που κρατείται στη μνήμη της διαδικασίας του engine και ξαναγράφεται στον δίσκο σε χρονομέτρημα. Αυτή είναι η σωστή προεπιλογή για μια τοπική εγκατάσταση ενός χρήστη· ένας κοινός daemon με πολλούς ταυτόχρονους writers παίρνει αντί αυτού πραγματικές εγγραφές ανά κλειδί από το Redis, με το κόστος ενός network round trip ανά λειτουργία (κάθε κλήση `state::*` εξακολουθεί να σειριοποιείται σε μία σύνδεση Redis, οπότε αυτό ανταλλάζει το lock του file store για ένα socket, όχι για παραλληλία).
+
+Ρυθμίστε `AGENTMEMORY_STATE_BACKEND=redis` (μαζί με `AGENTMEMORY_REDIS_URL`) για να αλλάξετε και τους δύο workers στον ενσωματωμένο `redis` adapter του iii-engine, που αποθηκεύει κάθε κλειδί ως πεδίο hash του Redis (`HSET`) αντί να ξαναγράφει ολόκληρο το scope σε κάθε εγγραφή:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+Το `AGENTMEMORY_STATE_BACKEND` έχει προεπιλογή το `file`· αφήνοντάς το χωρίς ρύθμιση διατηρεί τη σημερινή συμπεριφορά αμετάβλητη, και μια μη αναγνωρισμένη τιμή (οτιδήποτε άλλο εκτός από `file` ή `redis`) είναι σφάλμα εκκίνησης αντί για σιωπηλή επιστροφή σε προεπιλογή. Το `/agentmemory/status` και η σελίδα Health του viewer (η γραμμή State store) αναφέρουν ποιο backend είναι ενεργό και αν αποκρίνεται, ποτέ το URL.
+
+**Μόνο απλό `redis://`.** Ο καθορισμένος engine (0.22.1) χτίζει τον Redis client του χωρίς υποστήριξη TLS, οπότε ένα URL `rediss://` (οι περισσότερες διαχειριζόμενες προσφορές Redis, όπως οι Upstash, Redis Cloud, και ElastiCache με κρυπτογράφηση in-transit, έχουν προεπιλογή μόνο TLS) αποτυγχάνει να συνδεθεί. Η σύνδεση είναι χωρίς κρυπτογράφηση, οπότε ο κωδικός του Redis και κάθε αποθηκευμένη μνήμη διασχίζουν το δίκτυο σε καθαρό κείμενο: δείξτε σε έναν τοπικό Redis ή σε έναν σε ιδιωτικό δίκτυο που εμπιστεύεστε. Για οποιοδήποτε άλλο Redis, τρέξτε ένα κρυπτογραφημένο tunnel (stunnel, SSH, ή VPN) στον host του agentmemory, ώστε το απλό hop `redis://` να παραμένει σε αυτόν τον host και η upstream σύνδεση του tunnel να είναι κρυπτογραφημένη και αυθεντικοποιημένη. Αν ο κωδικός του Redis περιέχει μονό εισαγωγικό, κάντε percent-encode (`%27`)· ο engine επεκτείνει το URL μέσα στις ρυθμίσεις YAML του πριν το αναλύσει.
+
+**Ένας διακομιστής Redis ανά `--instance`.** Τα προθέματα κλειδιών Redis του engine (`state:`, `stream::`) είναι σταθερά, οπότε δύο instances agentmemory (`--instance 1`, `--instance 2`, ...) που δείχνουν στην ίδια βάση δεδομένων αντικαθιστούν τα δεδομένα το ένα του άλλου. Ένα ξεχωριστό database index (`redis://localhost:6379/1`) κρατά τα αποθηκευμένα δεδομένα ξεχωριστά, αλλά ο engine αναμεταδίδει τα live events του viewer μέσω ενός καναλιού pub/sub του Redis (`stream::events`), και το pub/sub του Redis αγνοεί το database index, οπότε ο viewer κάθε instance θα εξακολουθούσε να δείχνει τα live events του άλλου. Δώστε σε κάθε instance τον δικό του διακομιστή Redis (ή θύρα) όταν τρέχετε περισσότερα από ένα.
+
+**Τι παραμένει το ίδιο, και τι διαφέρει.** Κάθε δυνατότητα του agentmemory λειτουργεί στο Redis: sessions, παρατηρήσεις, μνήμες (remember, supersede, evolve, forget), αναζήτηση και τα buckets ευρετηρίου, μαθήματα, ο γράφος, το audit log και τα μηνιαία scopes του, εξαγωγή και εισαγωγή, διαγραφές governance, κατάσταση ενοποίησης, το snapshot του viewer και το live stream του, και ο health monitor. Ο engine αποθηκεύει κάθε scope ως ένα hash Redis (`HSET`/`HGET`/`HGETALL`) και ενεργοποιεί τα ίδια state triggers με το file store. Τρεις διαφορές του engine διαχειρίζονται εντός του agentmemory:
+
+- Το Redis επιστρέφει τις εγγραφές ενός scope χωρίς σταθερή σειρά. Το agentmemory τις ταξινομεί από την παλαιότερη (κατά τον χρόνο δημιουργίας στο id της εγγραφής, και μετά το timestamp της) ώστε οι λίστες, το paging, και τα κομμάτια εξαγωγής να επιστρέφουν με την ίδια σειρά όπως στο file store.
+- Ο engine εφαρμόζει μερικές ενημερώσεις στο Redis μέσα σε ένα script Lua που μετατρέπει τα κενά arrays σε κενά objects. Το agentmemory εφαρμόζει αυτές τις ενημερώσεις μόνο του (ανάγνωση, αλλαγή, εγγραφή υπό ένα lock ανά κλειδί) στο Redis, ώστε πεδία όπως το `tags: []` να παραμένουν arrays.
+- Ο παλαιός έλεγχος audit log διαβάζει το παλιό scope από το Redis αντί να ψάχνει για το αρχείο του file store στον δίσκο.
+
+Μία διαφορά απαιτεί τη δική σας ενέργεια: **μετά από επανεκκίνηση του Redis, ο engine σταματά να αναμεταδίδει live events** στον viewer μέχρι να γίνει επανεκκίνηση του agentmemory. Τα δεδομένα συνεχίζουν να αποθηκεύονται και να διαβάζονται κανονικά. Ο health monitor στέλνει ένα δοκιμαστικό event μέσω Redis κάθε 30 δευτερόλεπτα· όταν δεν επιστρέφει, το `/agentmemory/status` και η σελίδα Health του viewer δείχνουν "Live updates are not reaching the viewer" με τη διόρθωση: επανεκκίνηση του agentmemory. Αν το Redis είναι εκτός λειτουργίας, η αναφορά κατάστασης δείχνει "The state store is not answering" και πώς να το ελέγξετε (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Η λίστα ενός πολύ μεγάλου scope διαβάζει ολόκληρο το hash σε ένα `HGETALL`, το ίδιο κόστος με το να το κρατά το file store στη μνήμη.
+
+**Προτεινόμενες ρυθμίσεις Redis.** Η προεπιλεγμένη πολιτική snapshot `save 3600 1 300 100 60 10000` μπορεί να χάσει λεπτά εγγραφών σε ένα crash, χειρότερο από το παράθυρο flush των 5 δευτερολέπτων του file store. Ρυθμίστε `appendonly yes` για οτιδήποτε θα σας ενοχλούσε να χάσετε. Ρυθμίστε `maxmemory-policy noeviction`· το `allkeys-lru` ή κάτι αντίστοιχο απορρίπτει σιωπηλά μνήμες μόλις το Redis φτάσει το όριο μνήμης του.
+
+Μια native (μη-Docker) εκκίνηση, και κάθε πρότυπο [ανάπτυξης](../deploy/) με ένα κλικ (αντικαθιστούν το ενσωματωμένο `iii-config.yaml` και ξεκινούν native), διαβάζουν τα `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` και τα αποδίδουν στο `iii-config` που εκκινείται. Το ίδιο το URL δεν γράφεται ποτέ σε αυτό το αποδοθέν αρχείο, μόνο μια αναφορά `${AGENTMEMORY_REDIS_URL}` που η διαδικασία του engine επεκτείνει από το δικό της περιβάλλον κατά την εκκίνηση. Μόνο η δική του διαδρομή Docker Compose αυτού του αποθετηρίου (`AGENTMEMORY_USE_DOCKER=1`, ή η συνέχιση ενός engine που ξεκίνησε ήδη με αυτόν τον τρόπο) κάνει mount το `iii-config.docker.yaml` ως read-only και ποτέ δεν το αποδίδει· το `agentmemory start` προειδοποιεί όταν εντοπίζει αυτόν τον συνδυασμό. Αλλάξτε αυτό το αρχείο χειροκίνητα, ακολουθώντας την ίδια μορφή `name: redis` / `config: redis_url: ...` που φαίνεται στα docs των workers [iii-state](https://workers.iii.dev/workers/iii-state) και [iii-stream](https://workers.iii.dev/workers/iii-stream), και δείξτε το `redis_url` σε ένα Redis προσβάσιμο από το container. Το `docker-compose.yml` περνάει το `AGENTMEMORY_REDIS_URL` μέσα στο container του engine, οπότε το `redis_url: '${AGENTMEMORY_REDIS_URL}'` λειτουργεί εκεί και κρατά το URL έξω από το αρχείο που είναι mounted.
+
+Η αποδοθείσα ρύθμιση κρατά το URL έξω από το `~/.agentmemory/data/iii-config.runtime.yaml`, αλλά ο ίδιος ο worker ρυθμίσεων του engine εξακολουθεί να αποθηκεύει μόνιμα την *επεκταμένη* τιμή στα `~/.agentmemory/config/iii-state.yaml` και `iii-stream.yaml` μόλις εκκινήσει (η επέκταση `${VAR}` του iii-engine συμβαίνει πριν αυτός ο worker αποθηκεύσει το seed του, και αποθηκεύει την επιλυμένη τιμή, όχι την αναφορά). Αντιμετωπίστε αυτόν τον κατάλογο ως κάτι που κρατά διαπιστευτήρια: `chmod 700 ~/.agentmemory` σε κάθε κοινό host, και προτιμήστε έναν χρήστη Redis ACL με εμβέλεια σε ό,τι χρειάζεται το agentmemory αντί για τα admin διαπιστευτήρια της βάσης δεδομένων.
+
+**Η μετάβαση δεν είναι αυτόματη.** Η αλλαγή του `AGENTMEMORY_STATE_BACKEND` ξεκινά από ένα άδειο store και στις δύο πλευρές· τίποτα δεν αντιγράφει υπάρχοντα δεδομένα από το file στο Redis ή αντίστροφα. Κάντε export από το backend που αφήνετε και import σε αυτό στο οποίο μεταβαίνετε. Αυτό τρέχει ταυτόσημα σε bash και zsh (συμπεριλαμβανομένου του `bash -u`). Ένα array όπως το `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` δεν τρέχει το ίδιο: το zsh κρατά την κεφαλίδα ως μία κακοσχηματισμένη λέξη ενώ το bash τη χωρίζει σε δύο, οπότε και τα δύο αιτήματα επιστρέφουν 401 όποτε έχει ρυθμιστεί το `AGENTMEMORY_SECRET`:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+Το `/agentmemory/export` δέχεται επίσης `?maxSessions=` και `?offset=` για τον διαμερισμό ενός μεγάλου corpus σε πολλές κλήσεις· το `strategy` κατά το import είναι `merge` (ασφαλής προεπιλογή), `replace`, ή `skip`.
+
+### Τι Αντικαθιστά το iii
+
+| Παραδοσιακό stack | Το agentmemory χρησιμοποιεί |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + ευρετήριο vector in-memory |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | επιτήρηση workers του iii engine |
+| Prometheus / Grafana | iii OTEL + monitor υγείας |
+| Προσαρμοσμένα συστήματα plugin | `iii worker add ` |
+
+**225 αρχεία πηγαίου κώδικα · ~54,000 LOC · 2,600+ δοκιμές · 312 functions · 66 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
+
+---
+
+
+
+### Πάροχοι LLM
+
+Το agentmemory ανιχνεύει αυτόματα τους providers από το περιβάλλον σας. Ένας provider κάνει διαθέσιμες τις λειτουργίες που βασίζονται σε LLM, αλλά μόνο η ρύθμιση του provider δεν ενεργοποιεί τη συμπίεση παρατηρήσεων γραμμένη από LLM. Αυτή η διαδρομή απαιτεί τόσο έναν provider όσο και το `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Πάροχος | Ρύθμιση | Σημειώσεις |
+|----------|--------|-------|
+| **No-op (προεπιλογή)** | Δεν χρειάζεται ρύθμιση | Η συμπίεση/σύνοψη βασισμένη σε LLM είναι απενεργοποιημένη. Η συνθετική συμπίεση και η ανάκληση BM25 συνεχίζουν να λειτουργούν. Δείτε το `AGENTMEMORY_ALLOW_AGENT_SDK` παρακάτω αν βασιζόσασταν στην εναλλακτική λύση συνδρομής Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Χρέωση ανά token |
+| MiniMax | `MINIMAX_API_KEY` | Συμβατό με Anthropic |
+| Gemini | `GEMINI_API_KEY` | Ενεργοποιεί επίσης τα embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Οποιοδήποτε μοντέλο |
+| OpenAI API | `OPENAI_API_KEY` | Προεπιλογή `gpt-5.6-luna`, παρακάμψτε με `OPENAI_MODEL` |
+| **Τοπικό (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ή `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Οτιδήποτε συμβατό με το OpenAI API. Μηδενικό κόστος, τρέχει στο δικό σας hardware. Δείτε [Τοπικά μοντέλα](#local-models-ollama--lm-studio--vllm) παρακάτω. |
+| Εναλλακτική λύση συνδρομής Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Μόνο με ρητή ενεργοποίηση. Δημιουργεί συνεδρίες `@anthropic-ai/claude-agent-sdk`· παλαιότερα προκαλούσε απεριόριστη αναδρομή στο Stop-hook, οπότε δεν είναι πλέον η προεπιλογή. |
+
+### Τοπικά Μοντέλα (Ollama / LM Studio / vLLM)
+
+Το agentmemory επικοινωνεί με οποιονδήποτε διακομιστή συμβατό με το OpenAI API, οπότε οτιδήποτε εκθέτει το `/v1/chat/completions` λειτουργεί χωρίς αλλαγές κώδικα. Χωρίς επί πληρωμή κλειδιά, χωρίς cloud, χωρίς rate limits· τρέχει εξολοκλήρου στο δικό σας hardware.
+
+**Ollama** (προεπιλεγμένη θύρα `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (προεπιλεγμένη θύρα `1234`):
+
+Ανοίξτε το LM Studio → καρτέλα Local Server → Start Server. Επιλέξτε οποιοδήποτε μοντέλο chat από τον επιλογέα (Qwen 3, gpt-oss, DeepSeek R1, κλπ.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: ίδια μορφή. Δείξτε το `OPENAI_BASE_URL` στο URL που εκθέτει ο διακομιστής σας και ρυθμίστε το `OPENAI_MODEL` σε ένα όνομα που θα δέχεται ο διακομιστής σας.
+
+**Επιλογές μοντέλων για εργασίες μνήμης**: η συμπίεση και η σύνοψη είναι σύντομες εργασίες (<2K tokens είσοδος, <500 tokens έξοδος) όπου ένα μοντέλο instruct 7B είναι υπεραρκετό. Προτάσεις:
+
+| Μοντέλο | Μέγεθος | Γιατί |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Ισορροπημένη προεπιλογή σε μηχάνημα 16 GB· ισχυρό σε εξαγωγή και κείμενο σε μορφή εργαλείου |
+| `qwen3:4b` | ~2.6 GB | Η μικρότερη λογική επιλογή· καλό για συμπίεση, πιο αδύναμο για εξαγωγή γράφου |
+| `qwen3-coder:30b` | ~19 GB | Η καλύτερη τοπική επιλογή για συνεδρίες σε μορφή κώδικα (30B MoE, 3.3B ενεργά) σε hardware 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Ισχυρό γενικό μοντέλο που χωράει σε 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Distill συλλογιστικής· πιο αργό αλλά καθαρότερες εξαγωγές |
+
+Τα μοντέλα Qwen 3 σκέφτονται από προεπιλογή και μπορούν να καταναλώσουν όλο τον προϋπολογισμό tokens σε συλλογιστική πριν βγάλουν καθόλου έξοδο. Ρυθμίστε `AGENTMEMORY_LLM_NOTHINK=1` για να προσθέσετε `/no_think` στα prompts εξαγωγής γράφου, και ανεβάστε το `MAX_TOKENS` (16384 λειτουργεί) αν οι εξαγωγές επιστρέφουν άδειες.
+
+Τα μοντέλα κλάσης reasoning (στυλ `o1` με blocks ``) μπορούν να επιστρέψουν άδειο `content` με ένα πεδίο `reasoning` που ο τοπικός διακομιστής σας μπορεί να μην εμφανίζει. Αν οι εξαγωγές επιστρέφουν κενές, αλλάξτε πρώτα σε ένα μοντέλο χωρίς reasoning. Η μεταβλητή περιβάλλοντος `OPENAI_REASONING_EFFORT=none` μπορεί επίσης να απενεργοποιήσει τη σκέψη σε μοντέλα thinking του Ollama Cloud που αντικατοπτρίζουν το σχήμα reasoning του OpenAI.
+
+Τα τοπικά embeddings διανέμονται ως προαιρετική εξάρτηση αλλά δεν είναι ενεργοποιημένα από προεπιλογή. Ρυθμίστε `EMBEDDING_PROVIDER=local` για να ενεργοποιήσετε το `Xenova/all-MiniLM-L6-v2` (384 διαστάσεων). Το πρώτο αίτημα embedding κατεβάζει το μοντέλο· η εξαγωγή συμπερασμάτων γίνεται στη συσκευή στη συνέχεια. Χωρίς αυτή τη ρύθμιση ή ένα απομακρυσμένο κλειδί embedding, τα vectors παραμένουν απενεργοποιημένα, το `mem::search` χρησιμοποιεί BM25, και το `smart-search` μπορεί ακόμα να προσθέσει υπάρχουσες αντιστοιχίσεις γράφου.
+
+### Επιλογή Μοντέλου με Επίγνωση Κόστους
+
+Όταν η συμπίεση παρασκηνίου γραμμένη από LLM είναι ενεργοποιημένη με έναν provider και `AGENTMEMORY_AUTO_COMPRESS=true`, τρέχει σε κάθε παρατήρηση, οπότε η επιλογή μοντέλου αλλάζει ουσιαστικά το μηνιαίο κόστος. Δεδομένα καταγεγραμμένου φόρτου: 635 requests / 888K tokens / 35 ώρες ενεργής χρήσης, εκτελέστηκαν σε τρία μοντέλα OpenRouter με τιμολόγηση της 2026-05-23.
+
+| Βαθμίδα | Μοντέλο | Είσοδος / 1M | Έξοδος / 1M | Κόστος για τις καταγεγραμμένες 35 ώρες | Σημειώσεις |
+|------|-------|------------|-------------|---------------------------|-------|
+| Προτεινόμενο | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (εκτίμηση) | Το πιο πρόσφατο DeepSeek· η πιο οικονομική προτεινόμενη επιλογή για φόρτους συμπίεσης. |
+| Προτεινόμενο | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Στέρεη ποιότητα συμπίεσης + σύνοψης σε ~10× χαμηλότερο κόστος από το Sonnet. |
+| Προτεινόμενο | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Ισχυρή συλλογιστική κώδικα αν οι συνεδρίες σας είναι έντονα σε μορφή κώδικα. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (εκτίμηση) | Ίδια λιανική τιμή με τη μετρημένη εκτέλεση Sonnet 4.6· εισαγωγική τιμολόγηση $2/$10 έως 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (εκτίμηση) | Κορυφαία βαθμίδα· ακριβό για πάντα-ενεργή εργασία παρασκηνίου. |
+| Αποφύγετε | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (εκτίμηση) | Μοντέλο κλάσης flagship· υπερβολική δαπάνη για συμπίεση. |
+
+Οι μετρημένες γραμμές προέρχονται από την καταγεγραμμένη εκτέλεση· οι γραμμές (εκτίμηση) κλιμακώνουν το ίδιο μείγμα tokens με τη λιανική τιμή κάθε μοντέλου.
+
+Το agentmemory εκτυπώνει μια προειδοποίηση runtime όταν το `OPENROUTER_MODEL` ταιριάζει με ένα μοτίβο βαθμίδας premium. Ρυθμίστε `AGENTMEMORY_SUPPRESS_COST_WARNING=1` για να τη σιγάσετε μόλις κάνετε μια ενημερωμένη επιλογή.
+
+Ισορροπία ποιότητας/κόστους για εργασίες μνήμης: η συμπίεση είναι μια εργασία σύνοψης με σχετικά χαλαρά όρια ποιότητας (ο agent ξαναδιαβάζει τη σύνοψη, όχι ο χρήστης). Τα DeepSeek V4 Flash / V4 Pro / Qwen3-Coder προσεγγίζουν το Sonnet σε αυτήν την εργασία μέσα σε περιθώριο στρογγυλοποίησης, ενώ κοστίζουν 10-70× λιγότερο. Κρατήστε τα μοντέλα premium για ερωτήματα που διαβάζετε απευθείας.
+
+Πηγές: [Τιμολόγηση OpenRouter για το Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [Σημειώσεις τιμολόγησης DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Μνήμη Πολλών Agents (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Σε setups πολλών agents όπου αρκετοί ρόλοι μοιράζονται έναν διακομιστή 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 # optional; default "shared"
+```
+
+Δύο λειτουργίες:
+
+| Λειτουργία | Σημαίνει εγγραφές | Φιλτράρει ανάκληση | Πότε να τη χρησιμοποιήσετε |
+|------|------------|---------------|-------------|
+| `shared` (προεπιλογή) | ναι | όχι | Context μεταξύ agents με ιστορικό ελέγχου. Ο 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`. Κάθε endpoint δέχεται `?agentId=` για παράκαμψη ανά αίτημα, και `?agentId=*` για πλήρη εξαίρεση από το scope περιβάλλοντος. Το `/memories` δέχεται επίσης `?includeOrphans=true` για να εμφανίσει μνήμες πριν το AGENT_ID, των οποίων το `agentId` είναι undefined.
+
+Παράκαμψη ανά κλήση στο επίπεδο SDK / REST: κάθε endpoint που τροποποιεί δεδομένα (`/session/start`, `/remember`) δέχεται ένα πεδίο `agentId` στο σώμα του αιτήματος που υπερισχύει του περιβάλλοντος. Χρήσιμο για runtimes που δρομολογούν πολλούς ρόλους μέσα από μία διαδικασία διακομιστή. Το εργαλείο MCP `memory_save` εκθέτει το ίδιο πεδίο `agentId`, ο αυτόνομος διακομιστής stdio προωθεί τόσο το `agentId` όσο και το `project`, και οι αποθηκευμένες μνήμες μεταφέρουν το `agentId` στο ευρετήριο αναζήτησης, οπότε η αναζήτηση με εμβέλεια agent καλύπτει τόσο τις μνήμες όσο και τις παρατηρήσεις.
+
+Όταν το `AGENT_ID` δεν έχει ρυθμιστεί, η μνήμη παραμένει χωρίς scope (παλαιή συμπεριφορά, χωρίς ετικέτες, χωρίς φίλτρα).
+
+### Θύρες
+
+Το agentmemory + iii-engine συνδέονται σε τέσσερις θύρες από προεπιλογή. Αν μια επανεκκίνηση αποτύχει με `port in use`, αυτός ο πίνακας σας λέει ποια διαδικασία να αναζητήσετε.
+
+| Θύρα | Διαδικασία | Σκοπός | Παράκαμψη περιβάλλοντος |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Εσωτερικός worker streams (καταναλώνεται από το agentmemory + viewer) | `III_STREAM_PORT` (προτεινόμενο) ή το παλαιό `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer σε πραγματικό χρόνο (`http://localhost:3113`) | `III_VIEWER_PORT` ή `AGENTMEMORY_VIEWER_URL` για το αναφερόμενο URL |
+| `49134` | iii-engine | WebSocket· οι workers καταχωρούνται εδώ, η τηλεμετρία OTel ρέει μέσω αυτού | `III_ENGINE_PORT` ή `III_ENGINE_URL` |
+
+Το `--port ` αλλάζει την άγκυρα REST και παράγει τα streams στο `N+1`, το viewer στο `N+2`, και το WebSocket του engine στο `N+46023` μόνο όπου η αντίστοιχη ρητή θύρα ή URL παραπάνω δεν έχει ρυθμιστεί. Δεν δημιουργεί ένα απομονωμένο namespace κύκλου ζωής. Χρησιμοποιήστε `--instance 1` για έναν δεύτερο daemon· χρησιμοποιεί άγκυρα 3211, με προεπιλογή `3211/3212/3213/49234`, και λαμβάνει έναν ξεχωριστό κατάλογο δεδομένων και κύκλου ζωής `instance-1`. Τα instances 1 έως 50 ακολουθούν το ίδιο μοτίβο.
+
+Ο καθορισμένος engine ξεκινά με `--no-update-check` (χωρίς αναζητήσεις ενημέρωσης ή security-advisory προς το GitHub κατά την εκκίνηση) και με την ανώνυμη τηλεμετρία χρήσης του iii απενεργοποιημένη: το agentmemory ρυθμίζει το `III_TELEMETRY_ENABLED=false` για τον engine που δημιουργεί, εκτός αν εξάγετε εσείς τη μεταβλητή, και το ενσωματωμένο αρχείο compose κάνει το ίδιο.
+
+Καθαρισμός παλιωμένων διαδικασιών όταν οι θύρες παραμένουν δεσμευμένες μετά από μια εκτέλεση που κατέρρευσε:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+Το `agentmemory stop` τερματίζει καθαρά τόσο τον worker όσο και το pidfile του engine σε ομαλή native τερματισμό. Σε λειτουργία Docker, αδειάζει τον native worker, σταματά το ακριβές επικυρωμένο container του engine, και διατηρεί τόσο το container όσο και το mount `/data` του για μια επανεκκίνηση χωρίς απώλειες· η επόμενη εκκίνηση επικυρώνει και συνεχίζει το ίδιο container. Η απεγκατάσταση με Docker απαιτεί `agentmemory remove --keep-data`: αφαιρεί τα κοινά αρχεία που διαχειρίζεται το agentmemory, διατηρώντας το επικυρωμένο container, το data mount του, και την εγγραφή κύκλου ζωής που χρειάζεται για την ανάκτησή τους. Η καταστροφική διαγραφή δεδομένων Docker αφήνεται σκόπιμα στον χειριστή μετά από ένα backup. Το CLI αρνείται επίσης να υιοθετήσει ή να στείλει σήμα σε κατόχους θυρών Docker ή VM (Docker backend, vpnkit, colima) ως τον native engine εκτός αν περαστεί το `--force`. Ο χειροκίνητος καθαρισμός παραπάνω είναι μόνο για την περίπτωση μετά από crash όπου δεν έχει απομείνει κανένα pidfile.
+
+### Αρχείο Ρυθμίσεων
+
+Βάλτε τις ρυθμίσεις runtime του agentmemory στο `~/.agentmemory/.env` αντί να εξάγετε μεταβλητές σε κάθε shell. Αν το viewer δείξει μια υπόδειξη ρύθμισης όπως `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, ενεργοποιήστε το ρητά:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Η συμπίεση παρατηρήσεων γραμμένη από LLM απαιτεί και τις δύο γραμμές: πρόσβαση σε έναν πάροχο LLM (συμπεριλαμβανομένης αυτής της ρητής εναλλακτικής λύσης συνδρομής) και `AGENTMEMORY_AUTO_COMPRESS=true`. Ένας πάροχος από μόνος του αφήνει στη θέση της την προεπιλεγμένη διαδρομή συνθετικής συμπίεσης.
+
+Η ενοποίηση (κόμβοι γράφου, μαθήματα, crystals) είναι ενεργή από προεπιλογή όποτε έχει ρυθμιστεί ένας πάροχος LLM. Απενεργοποιήστε ρητά με `CONSOLIDATION_ENABLED=false` αν θέλετε λειτουργία χωρίς LLM. Η εξαγωγή γράφου είναι ξεχωριστή σημαία:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Μεταβλητές Περιβάλλοντος
+
+Δημιουργήστε το `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoints στη θύρα `3111`. Το REST API συνδέεται στο `127.0.0.1` από προεπιλογή. Τα προστατευμένα endpoints απαιτούν `Authorization: Bearer `, και τα endpoints mesh sync απαιτούν ένα ρητά ρυθμισμένο `AGENTMEMORY_SECRET` και στους δύο peers.
+
+**Η πιστοποίηση είναι ενεργή από προεπιλογή.** Όταν το `AGENTMEMORY_SECRET` δεν έχει ρυθμιστεί (στο shell ή στο `~/.agentmemory/.env`), ο διακομιστής δημιουργεί ένα τυχαίο secret στην πρώτη εκκίνηση και το αποθηκεύει στο `~/.agentmemory/secret` με mode `0600`. Κάθε ενσωματωμένος client το διαβάζει από εκεί όταν μιλά με έναν τοπικό διακομιστή: το CLI, το viewer, τα hooks κάτω από το `plugin/scripts`, ο διακομιστής MCP και το shim `@agentmemory/mcp`, οι ρυθμίσεις που γράφει το `agentmemory connect`, και οι ενσωματωμένες ενσωματώσεις OpenCode, Pi, OpenClaw, Hermes, και filesystem-watcher. Το αποθηκευμένο secret αποστέλλεται μόνο σε loopback URLs (`localhost`, `127.0.0.0/8`, `::1`). Ένα ρητό `AGENTMEMORY_SECRET` υπερισχύει πάντα, και οι απομακρυσμένοι clients εξακολουθούν να το χρειάζονται ρυθμισμένο. Το Docker και τα entrypoints του `deploy/` δημιουργούν και εξάγουν ήδη το δικό τους secret. Για να καλέσετε το API χειροκίνητα:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Κανόνες αιτημάτων για εγγραφές.** Τα αιτήματα `POST`, `PUT`, `PATCH`, και `DELETE` προς το REST API και το viewer πρέπει να στέλνουν `Content-Type: application/json` (μια παράμετρος `charset` είναι εντάξει) όποτε φέρουν ένα σώμα, και μια κεφαλίδα `Origin`, όταν υπάρχει, πρέπει να είναι μια προέλευση loopback για τη ρυθμισμένη θύρα REST ή viewer ή να αναφέρεται στο `VIEWER_ALLOWED_ORIGINS` (διαχωρισμένο με κόμματα, π.χ. `https://memory.example.com`). Οι clients που δεν στέλνουν κεφαλίδα `Origin` (CLI, hooks, MCP, curl, server-to-server) δεν επηρεάζονται. Το viewer δέχεται επίσης τη δική του προέλευση.
+
+**Διαδρομές αρχείων.** Τα endpoints που διαβάζουν ή γράφουν αρχεία (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) δέχονται μόνο διαδρομές κάτω από το `~/.agentmemory`, τον κατάλογο δεδομένων του instance, ή έναν κατάλογο που αναφέρεται στο `AGENTMEMORY_IMPORT_ROOT` (διαχωρίστε πολλούς με `:`, ή `;` σε Windows). Το `/replay/import-jsonl` δέχεται επίσης το προεπιλεγμένο του `~/.claude/projects`. Το `/obsidian/export` παραμένει εντός του `AGENTMEMORY_EXPORT_ROOT` και το `/migrate` εντός του `~/.agentmemory`. Τα symlinks επιλύονται πριν από κάθε έλεγχο.
+
+**Απόκρυψη μυστικών.** Κλειδιά API, bearer tokens, blocks ιδιωτικών κλειδιών PEM, και διαπιστευτήρια ενσωματωμένα σε URLs (`scheme://user:password@host`) αποκρύπτονται πριν αποθηκευτεί το κείμενο, σε κάθε διαδρομή εγγραφής: παρατηρήσεις, remember, evolve, slots, μαθήματα, ενέργειες, sketches, signals, σημεία ελέγχου, imports, jsonl replay, mesh sync, κοινοποιήσεις ομάδας, έξοδο συμπίεσης και σύνοψης, crystals, και κόμβοι γράφου.
+
+
+Βασικά endpoints
+
+| Μέθοδος | Διαδρομή | Περιγραφή |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Έλεγχος υγείας (πάντα δημόσιο) |
+| `GET` | `/agentmemory/status` | Τι πάει στραβά και πώς να το διορθώσετε (HTML για browsers, JSON διαφορετικά) |
+| `GET` | `/agentmemory/viewer/snapshot` | Όλα όσα δείχνει το viewer, σε μία απάντηση |
+| `POST` | `/agentmemory/session/start` | Εκκίνηση συνεδρίας + λήψη context |
+| `POST` | `/agentmemory/session/end` | Τέλος συνεδρίας |
+| `POST` | `/agentmemory/observe` | Καταγραφή παρατήρησης (δείτε την παράδοση καταγραφής παρακάτω) |
+| `GET` | `/agentmemory/capture` | Inbox καταγραφής, dead letters, και offline spool |
+| `POST` | `/agentmemory/capture/retry` | Επανάληψη καταγραφών dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Αποστολή του τοπικού offline spool τώρα |
+| `POST` | `/agentmemory/smart-search` | Υβριδική αναζήτηση |
+| `POST` | `/agentmemory/context` | Δημιουργία context |
+| `POST` | `/agentmemory/remember` | Αποθήκευση σε μακροπρόθεσμη μνήμη |
+| `POST` | `/agentmemory/forget` | Διαγραφή παρατηρήσεων |
+| `POST` | `/agentmemory/enrich` | Context αρχείου + μνήμες + bugs |
+| `GET` | `/agentmemory/profile` | Προφίλ project |
+| `GET` | `/agentmemory/export` | Εξαγωγή όλων των δεδομένων |
+| `POST` | `/agentmemory/import` | Εισαγωγή από JSON |
+| `POST` | `/agentmemory/graph/query` | Ερώτημα γράφου γνώσης |
+| `POST` | `/agentmemory/graph/compact` | Περιορισμός υπερμεγέθους προέλευσης γράφου |
+| `POST` | `/agentmemory/team/share` | Κοινοποίηση σε ομάδα |
+| `GET` | `/agentmemory/audit` | Ιστορικό ελέγχου |
+
+Πλήρης λίστα endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Παράδοση καταγραφής.** Τα hooks στέλνουν κάθε παρατήρηση μία φορά στο `POST /agentmemory/observe` με ένα `eventId`. Αυτό είναι το δικό του id του host για την κλήση όταν το payload έχει ένα (για παράδειγμα το `tool_use_id` του Claude Code), διαφορετικά ένα hash της συνεδρίας, του τύπου hook, του ονόματος εργαλείου, της εισόδου, της εξόδου, και του timestamp του host. Ο διακομιστής γράφει το event σε ένα inbox καταγραφής στο state store, αποθηκεύει την παρατήρηση, και μετά αφαιρεί την καταχώρηση του inbox. Ο κωδικός κατάστασης λέει τι συνέβη:
+
+| Κατάσταση | πεδίο `status` | Σημασία |
+|---|---|---|
+| `201` | `accepted` | Αποθηκεύτηκε. Το `observationId` είναι η νέα παρατήρηση. |
+| `202` | `accepted` (`state: "retrying"`) | Έγινε δεκτό, αλλά η αποθήκευση απέτυχε. Ο διακομιστής το ξαναδοκιμάζει, και μετά από επανεκκίνηση. |
+| `200` | `duplicate` | Αυτό το `eventId` έγινε ήδη δεκτό. Το `observationId` είναι η υπάρχουσα παρατήρηση· δεν αποθηκεύεται τίποτα νέο. |
+| `400` / `422` | `rejected` | Μη έγκυρο payload, ή η αποθήκευση απέτυχε οριστικά (το event κρατιέται ως dead letter). |
+| `503` | `rejected` (`retryable: true`) | Το inbox είναι γεμάτο (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Τα hooks κάνουν spool το event και το στέλνουν αργότερα. |
+
+Τα αποτυχημένα events ξαναδοκιμάζονται κάθε `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 δευτ.) με διπλασιαζόμενο backoff, έως `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Τα events που συνεχίζουν να αποτυγχάνουν παραμένουν στο inbox ως dead letters, αναφέρονται στο `/agentmemory/status` και στη σελίδα Health του viewer, και μπορούν να ξαναδοκιμαστούν με `POST /agentmemory/capture/retry` (`{"eventId": "..."}` ή `{"all": true}`). Τα αποδεκτά event ids θυμούνται για `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 ώρες, το πολύ `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), οπότε ένα hook που αναπαράγεται μετά από timeout ή επανεκκίνηση αποθηκεύεται μία φορά, ενώ δύο ξεχωριστές κλήσεις εργαλείων με τα δικά τους host ids αποθηκεύονται δύο φορές ακόμα κι αν το περιεχόμενό τους είναι ταυτόσημο. Όταν μια παρατήρηση διαγράφεται (forget, διαγραφή συνεδρίας, εκδίωξη, αυτόματη διαγραφή, ή ένα import που αντικαθιστά το store), το event της σημαίνεται ως διαγραμμένο πριν αφαιρεθεί η παρατήρηση, οπότε μια αναπαραγωγή αυτού του event εντός του ίδιου παραθύρου απαντιέται ως duplicate και δεν αποθηκεύει τίποτα. Το state store γράφει στον δίσκο κάθε 2 δευτερόλεπτα, οπότε ένα event που έχει απαντηθεί μπορεί ακόμα να βρίσκεται μόνο στη μνήμη για μια στιγμή. Για να το καλύψει αυτό, κάθε απάντηση `2xx` φέρει επίσης το `bootId` του διακομιστή (νέο σε κάθε εκκίνηση), το `acceptedAt`, και το `durableAfterMs` (το διάστημα αποθήκευσης συν 1.5 δευτ. στο file store, 1.5 δευτ. στο redis, όπου η μονιμότητα είναι ρύθμιση του χειριστή). Τα hooks κρατούν το event στο τοπικό spool μέχρι να περάσει αυτό το παράθυρο και το διαγράφουν σε μια επόμενη κλήση χωρίς άλλο αίτημα. Αν το `bootId` έχει αλλάξει μέχρι τότε, ο διακομιστής επανεκκινήθηκε, οπότε το hook στέλνει ξανά το event με το ίδιο `eventId`· ένα event που είχε φτάσει στον δίσκο δεν αποθηκεύεται δύο φορές. Ο διακομιστής στέλνει επίσης τέτοια events ο ίδιος κατά την εκκίνηση και σε κάθε διάστημα retry, οπότε μια επανεκκίνηση δεν χάνει τίποτα ακόμα και όταν δεν τρέξει κανένα hook μετά. Τα παλαιότερα hooks αγνοούν τα επιπλέον πεδία, και τα νέα hooks έναντι ενός παλαιότερου διακομιστή απορρίπτουν το event στο `2xx` όπως πριν.
+
+Όταν ο διακομιστής είναι εκτός λειτουργίας, δεν απαντά εγκαίρως, ή επιστρέφει 5xx, το hook προσθέτει την παρατήρηση σε ένα τοπικό αρχείο spool, `/capture-spool/-.jsonl` (παρακάμψτε τον φάκελο με `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Το αρχείο είναι ιδιωτικό για τον χρήστη σας (mode 600), τα μυστικά αποκρύπτονται με τον ίδιο τρόπο που τα αποκρύπτει ο διακομιστής, κρατά το πολύ `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) και αφαιρεί καταχωρήσεις παλαιότερες από `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Όταν είναι γεμάτο, οι νέες καταχωρήσεις αφαιρούνται και μετρούνται, και το `/agentmemory/status` το αναφέρει. Το hook συνεχίζει να κάνει exit 0 εντός του χρονικού ορίου του και δεν προσθέτει κανένα αίτημα όταν ο διακομιστής είναι υγιής. Το spool αποστέλλεται στην επόμενη εκκίνηση και από το πρώτο hook που φτάνει ξανά στον διακομιστή, σε μια διαδικασία παρασκηνίου ώστε ο agent να μην περιμένει. Τα event ids το κάνουν ασφαλές: μια παρατήρηση που είχε φτάσει πριν από ένα timeout δεν αποθηκεύεται δύο φορές. Το `npx @agentmemory/agentmemory capture` δείχνει το spool και το inbox του διακομιστή, το `--drain` στέλνει το spool τώρα, και το `GET /agentmemory/capture` επιστρέφει το ίδιο ως JSON. Ρυθμίστε `AGENTMEMORY_CAPTURE_SPOOL=false` για να απενεργοποιήσετε το spool.
+
+**Συμπύκνωση προέλευσης γράφου.** Κάθε κόμβος και ακμή γράφου γνώσης κρατά τα ids των 32 πιο πρόσφατων παρατηρήσεων από τις οποίες προήλθε. Stores γραμμένα πριν από αυτό το όριο μπορούν να κρατούν χιλιάδες ids ανά hot κόμβο, κάτι που κάνει την αναζήτηση γράφου και το viewer αργά ή ρίχνει τον worker. Το agentmemory το διορθώνει μόνο του: στην πρώτη εκκίνηση μετά από αναβάθμιση περιορίζει κάθε κόμβο, ακμή, αντικατεστημένη ακμή (το χρονικό ιστορικό γράφου), και το cached snapshot στο όριο, στο παρασκήνιο, σε μικρές φέτες με μια παύση μεταξύ τους, ώστε η αναζήτηση, η καταγραφή, και το viewer να συνεχίζουν να λειτουργούν. Αποθηκεύει την πρόοδό του, συνεχίζει μετά από επανεκκίνηση, και δεν ξανατρέχει μόλις τελειώσει. Το `/agentmemory/status` και η σελίδα Health του viewer το δείχνουν ως εκκρεμές, σε εξέλιξη (με το τρέχον scope και θέση), ολοκληρωμένο, ή αποτυχημένο. Ρυθμίστε `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` για να το απενεργοποιήσετε.
+
+Για να το εκτελέσετε χειροκίνητα, καλέστε `POST /agentmemory/graph/compact`. Διασχίζει τα ευρετήρια ονόματος και edge-key αντί να απαριθμεί κάθε κόμβο και ακμή, και είναι ασφαλές να ξανατρέξει. Όταν περιορίζει ids, γράφει μια καταχώρηση audit `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Σε ένα μεγάλο store, ή όταν η κλήση επιστρέφει 504, εκτελέστε το σε φέτες. Στείλτε `scope` (`nodes`, `edges`, ή `history`), `offset`, και `limit`, και μετά καλέστε ξανά με το επιστρεφόμενο `nextOffset` μέχρι να γίνει `null`. Κάντε το αυτό για τα `nodes`, `edges`, και `history`, και τελειώστε με μία κλήση `{"scope":"snapshot"}`, επειδή μια κλήση σε φέτες δεν αγγίζει το cached snapshot.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Προαπαιτούμενα:** Node.js >= 20 με npm/npx· [iii-engine](https://iii.dev/docs) v0.22.1 ή Docker. Η αυτόματη εγκατάσταση του engine σε macOS/Linux απαιτεί επίσης `curl`, ένα POSIX `sh`, και `tar`· το native Windows χρησιμοποιεί το χειροκίνητο καθορισμένο `iii.exe`, WSL2, ή Docker Desktop.
+
+
Tu agente de codificación lo recuerda todo. Se acabó volver a explicarlo.
- Built on iii engine
+ Basado en el iii engine
- Memoria persistente para Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode y cualquier cliente MCP.
+ Memoria persistente para Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode y cualquier cliente MCP.
---
-## Install
+## Instalación
-Un solo comando:
+Requisitos:
+
+- Node.js 20 o superior con npm y npx (`node -v`, `npm -v` y `npx -v`).
+- La instalación automática de iii-engine en macOS/Linux también necesita `curl`, un `sh` POSIX y `tar`. Las imágenes mínimas como `node:20-slim` pueden no incluirlos.
+- Windows nativo requiere instalar manualmente el `iii.exe` de iii-engine v0.22.1 fijado. WSL2 o Docker Desktop son las otras rutas soportadas.
+
+Comando canónico de instalación limpia:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-La primera ejecución es un setup interactivo: elige los agentes a conectar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), elige un proveedor LLM o quédate sin claves, y siembra la configuración, arranca el servidor de memoria en `:3111` y ofrece instalar globalmente para que el comando `agentmemory` a secas funcione en cualquier lugar a partir de entonces.
+La primera ejecución es un setup interactivo: elige los agentes a conectar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), elige un proveedor LLM o quédate sin claves, y siembra la configuración, arranca el servidor de memoria y su iii engine fijado, y ofrece instalar globalmente para que el comando `agentmemory` a secas funcione en cualquier lugar a partir de entonces. `-y` acepta el prompt de paquete de npx y `@latest` evita una release cacheada obsoleta. Un proveedor habilita las funciones de LLM, pero la compresión de observaciones escrita por LLM solo arranca cuando también se establece `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+El modo sin claves desactiva los embeddings vectoriales. `memory_recall` (la ruta `mem::search`) usa BM25, mientras que `memory_smart_search` también puede fusionar coincidencias estructurales del grafo cuando ya existen datos de grafo. Para recall semántico local y gratuito, define `EMBEDDING_PROVIDER=local` en `~/.agentmemory/.env` y reinicia. La primera petición de embedding descarga `Xenova/all-MiniLM-L6-v2`; la inferencia corre en local después de esa descarga inicial del modelo.
+
+El runtime local usa cuatro puertos: `3111` para REST/MCP HTTP, `3112` para los streams de iii, `3113` para el visor y `49134` para el WebSocket del worker de iii. El estado persistente de iii vive en `~/Library/Application Support/agentmemory` en macOS, `$XDG_DATA_HOME/agentmemory` o `~/.local/share/agentmemory` en Linux, y `%APPDATA%\agentmemory` en Windows. Usa `--data-dir ` o `AGENTMEMORY_DATA_DIR` para sobrescribirlo, y reutiliza el mismo valor en cada reinicio. Por compatibilidad retroactiva, un `./data/state_store.db` o `./data/iii-config.yaml` ya existentes tienen prioridad sobre el valor por defecto de la plataforma para la instancia 0; un flag explícito o una variable de entorno siguen ganando.
Después demuestra que el recall funciona y dale a tu agente sus skills:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
-¿Prefieres que un agente de codificación lo haga todo? Entrégale una única instrucción:
+Las búsquedas por palabra clave deberían acertar en el modo sin claves por defecto a través de BM25. La consulta `database performance optimization` de la demo es intencionadamente semántica y puede devolver cero resultados hasta que se configure un proveedor de embeddings.
+
+¿Prefieres que un agente de codificación lo haga todo? Dale una sola instrucción:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
@@ -99,7 +132,7 @@ Conecta más agentes en cualquier momento con `agentmemory connect ` —
Windows
-La ruta rápida es WSL2. La configuración nativa del engine en Windows es manual (entre 10 y 20 minutos) y `agentmemory connect` no está soportado allí por ahora. Consulta las [notas de Windows](#windows) para el paso a paso.
+La ruta rápida es WSL2. La configuración nativa del engine en Windows requiere descargar el ZIP v0.22.1 fijado y extraer `iii.exe` manualmente; la CLI no lo extrae automáticamente. Docker Desktop también está soportado. Consulta las [notas de Windows](#windows) para el paso a paso.
@@ -107,11 +140,11 @@ La ruta rápida es WSL2. La configuración nativa del engine en Windows es manua
Instalación global / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+El comando npx de arriba sigue siendo la ruta canónica de instalación limpia y evita problemas de permisos del prefijo global.
+
@@ -122,9 +155,9 @@ npx cachea por versión. Fuerza la última con `npx -y @agentmemory/agentmemory@
-Ya ejecutas tu propio engine iii
+Ya ejecutas tu propio iii engine
-agentmemory fija iii-engine a v0.11.2 y no se conectará a una versión distinta (el worker no puede hablar el protocolo de otro engine). Detén el otro engine y ejecuta `npx -y @agentmemory/agentmemory@latest`. Instala y ejecuta la v0.11.2 fijada en `~/.agentmemory/bin`, dejando tu propio `iii` intacto.
+agentmemory fija iii-engine a v0.22.1 y no se conectará a una versión distinta (el worker no puede hablar el protocolo de otro motor). Detén el otro motor y ejecuta `npx -y @agentmemory/agentmemory@latest`. Instala y ejecuta la v0.22.1 fijada en `~/.agentmemory/bin`, dejando tu propio `iii` intacto.
@@ -136,106 +169,166 @@ agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Tod
-
-Cursor
-MCP server
+backend nativo del trait Memory
-
+
+
+
Gemini CLI
-MCP server
+servidor MCP
+
+
+
+Antigravity
+MCP + hooks
+
+
+
+Claude Desktop
+servidor MCP
+
+
+
+Warp
+connect + MCP + skills
+
+
+
+Zed
+servidor MCP
-
-
-OpenCode
-22 hooks + MCP + plugin
-
-
+
Cline
-MCP server
+servidor MCP
-
-
-Goose
-MCP server
+
+
+Continue
+servidor MCP
-
-
-Kilo Code
-MCP server
+
+
+Droid
+servidor MCP
-
-
-Aider
-REST API
+
+
+Kiro
+servidor MCP
-
-
-Claude Desktop
-MCP server
+
+
+Qwen Code
+servidor MCP
-
-
-Devin
-6 hooks + MCP
+
+
+
+
+DeepSeek Harness
+servidor MCP
-
+
Roo Code
-MCP server
+servidor MCP
+
+
+
+Kilo Code
+servidor MCP
+
+
+
+Goose
+servidor MCP
+
+
+
+Aider
+REST API
- Funciona con cualquier agente que hable MCP o HTTP. Un único servidor, memorias compartidas entre todos ellos.
+ Funciona con cualquier agente que hable MCP o HTTP. Un servidor, memorias compartidas entre todos ellos.
---
-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.
+Explicas la misma arquitectura en cada sesión. Vuelves a descubrir los mismos bugs. Vuelves a enseñar las mismas preferencias. La memoria integrada (CLAUDE.md, .cursorrules) tiene un tope de 200 líneas y se queda obsoleta. agentmemory soluciona esto. Captura en silencio lo que hace tu agente, lo comprime en memoria buscable e inyecta el contexto correcto cuando empieza la siguiente sesión. Un solo comando. Funciona entre agentes.
+
+**Qué cambia:** en la sesión 1 configuras JWT auth. En la sesión 2 pides rate limiting. El agente ya sabe que tu auth usa middleware jose en `src/middleware/auth.ts`, que tus tests cubren la validación de tokens, y que elegiste jose sobre jsonwebtoken por compatibilidad con Edge, sin volver a explicar nada y sin copiar y pegar.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
-**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 nada y sin copiar y pegar.
+Por defecto, agentmemory almacena el estado de iii-engine fuera del repositorio desde el que lo arrancas: `~/Library/Application Support/agentmemory` en macOS, `$XDG_DATA_HOME/agentmemory` o `~/.local/share/agentmemory` en Linux, y `%APPDATA%\agentmemory` en Windows. Un `./data/state_store.db` o `./data/iii-config.yaml` legacy ya existentes se reutilizan para la instancia 0 antes de ese valor por defecto de la plataforma. Para elegir una ubicación explícitamente, pasa `--data-dir ` o define `AGENTMEMORY_DATA_DIR`; cualquiera de los dos ajustes explícitos tiene prioridad sobre el descubrimiento legacy:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
-> **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).
+Los arranques nativos y en Docker usan este mismo directorio de host resuelto; Docker lo monta con bind en `/data`. `--instance 1` añade `instance-1` al directorio resuelto y selecciona el cuarteto de puertos por defecto separado `3211/3212/3213/49234`.
+
+Notas de la última release: [CHANGELOG.md](../CHANGELOG.md).
---
@@ -247,12 +340,12 @@ npx @agentmemory/agentmemory
### Precisión de recuperación
-**coding-agent-life-v1** (corpus interno, reproducible en sandbox)
+**coding-agent-life-v1** (corpus propio, reproducible en sandbox)
| Adaptador | P@5 | R@5 | Tasa de aciertos top-5 | Latencia p50 |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
-| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+| baseline grep | 0.227 | 0.967 | 15 / 15 | 0 ms |
Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este corpus (0.240, ver scorecard). Hybrid recupera todas las sesiones gold; grep falla 1 de 2 gold en la consulta temporal multi-sesión. La mejora es **recall + temporal**, no precisión agregada. Este benchmark es pequeño y escaso en gold; el LongMemEval-S más grande de abajo diferencia mejor. Desglose completo por tipo + nota de corrección: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
@@ -261,7 +354,7 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
| Sistema | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
-| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+| Fallback solo BM25 | 86.2% | 94.6% | 71.5% |
@@ -270,7 +363,7 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
| Enfoque | Tokens/año | Coste/año |
|---|---|---|
-| Pegar todo el contexto | 19.5M+ | Imposible (excede la ventana) |
+| Pegar el contexto completo | 19.5M+ | Imposible (excede la ventana) |
| Resumido por LLM | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
| agentmemory + embeddings locales | ~170K | **$0** |
@@ -279,9 +372,9 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
-> 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), que cubre agentmemory frente a mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+> Modelo de embedding: `all-MiniLM-L6-v2` (local, gratis, 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 competidores: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), que cubre agentmemory frente a mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, 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/).
+**Reprodúcelo en local:** [`eval/README.md`](../eval/README.md), un harness con adaptadores intercambiables para LongMemEval `_s` (500 preguntas públicas) + `coding-agent-life-v1` (corpus propio de 15 sesiones). Los adaptadores grep / vector / agentmemory puntúan uno junto al otro, salida NDJSON, los scorecards publicados aterrizan 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).
@@ -301,7 +394,7 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
MemPalace (54K ⭐)
oracleagentmemory
Hippo
-
Built-in (CLAUDE.md)
+
Integrada (CLAUDE.md)
Tipo
@@ -317,15 +410,15 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
Fichero estático
-
Retrieval R@5
+
R@5 de recuperación
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
N/A
-
Autodeclarado
-
PersonaMem 76% (autodeclarado)
-
~96.6% (autodeclarado)
-
94.4% (autodeclarado)
+
Autoinformado
+
PersonaMem 76% (autoinformado)
+
~96.6% (autoinformado)
+
94.4% (autoinformado)
N/A
N/A (grep)
@@ -333,12 +426,12 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
Captura automática
12 hooks (esfuerzo manual cero)
Llamadas manuales a add()
-
El agente se edita a sí mismo
+
Autoedición por el agente
Manual
Extracción del lado de la API
Intercepción por proxy (cambio de base-URL)
Manual
-
Extracción vía API
+
Extracción por API
Manual
Edición manual
@@ -353,7 +446,7 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
Solo vector
Vector + semántica
Ponderada por decaimiento
-
Carga todo en contexto
+
Carga todo en el contexto
Multiagente
@@ -364,21 +457,21 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
No
Roles de equipo + assets compartidos
No
-
Solo con scopes
-
Multiagente compartido
+
Solo con scope
+
Compartido multiagente
Ficheros por agente
-
Dependencia de framework
-
Ninguna (cualquier cliente MCP)
-
Ninguna
-
Alta (obliga a usar Letta)
+
Lock-in de framework
+
Ninguno (cualquier cliente MCP)
+
Ninguno
+
Alto (debes usar Letta)
Standalone
-
Ninguna
-
El proxy antecede cada llamada al modelo
-
Ninguna
+
Ninguno
+
Un proxy antepone cada llamada al modelo
+
Ninguno
Oracle Database
-
Ninguna
+
Ninguno
Formato por agente
@@ -386,7 +479,7 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
Ninguna (SQLite + iii-engine)
Qdrant / pgvector
Postgres + BD vectorial
-
Múltiples
+
Varias
Nube gestionada
Stack Docker (Core + Hub + Proxy)
Vector store
@@ -395,26 +488,26 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
Ninguna
-
Ciclo de vida de memoria
+
Ciclo de vida de la memoria
Consolidación de 4 niveles + decaimiento + auto-olvido
Extracción pasiva
Gestionado por el agente
Manual
Auto-olvido
-
Revisión manual; auto-enrutado en desarrollo
+
Revisión manual; auto-enrutado en progreso
Ninguno
-
No declarado
+
No especificado
Decaimiento + consolidación
Poda manual
Eficiencia de tokens
-
~1.900 tokens/sesión ($10/año)
+
~1,900 tokens/sesión ($10/año)
Varía según la integración
-
Memoria principal en contexto
+
Memoria core en el contexto
Varía
Precios de nube
-
No declarado
+
No especificado
Sin presupuesto de tokens
Respaldado por LLM (varía)
Varía
@@ -422,12 +515,12 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
Visor en tiempo real
-
Sí (port 3113)
+
Sí (puerto 3113)
Dashboard en la nube
Dashboard en la nube
-
Web UI
+
UI web
Dashboard en la nube
-
Web UI del Hub
+
UI web del hub
No
No
No
@@ -448,14 +541,14 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
-Nota sobre benchmarks: solo el R@5 de agentmemory es un resultado medido por nosotros (LongMemEval-S, reproducible desde benchmark/COMPARISON.md). Las cifras de mem0 y Letta son sus números publicados de LoCoMo (un dataset distinto); las cifras de MemPalace, supermemory, TencentDB (PersonaMem) y oracleagentmemory son afirmaciones autodeclaradas por los proveedores que no hemos reproducido de forma independiente (la ejecución de oracleagentmemory usó GPT-5.5 contra una Oracle AI Database). Se muestran lado a lado solo como referencia aproximada, no como una comparación directa sobre datos idénticos. Los conteos de estrellas son aproximados y varían con el tiempo.
+Nota de benchmark: solo el R@5 de agentmemory es un resultado medido por nosotros (LongMemEval-S, reproducible desde benchmark/COMPARISON.md). Las cifras de mem0 y Letta son sus números publicados de LoCoMo (un dataset distinto); las cifras de MemPalace, supermemory, TencentDB (PersonaMem) y oracleagentmemory son afirmaciones autoinformadas por el proveedor que no hemos reproducido de forma independiente (la ejecución de oracleagentmemory usó GPT-5.5 contra una Oracle AI Database). Se muestran una junto a otra solo a modo orientativo, no como un cara a cara sobre datos idénticos. Los conteos de estrellas son aproximados y varían con el tiempo.
-**Entrantes más recientes** que conviene conocer, comparados en profundidad en [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+**Nuevos entrantes** que vale la pena conocer, comparados en profundidad en [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| Sistema | ⭐ | Enfoque |
|--------|---|-------|
-| Zep / Graphiti | 30K | Grafo de conocimiento temporal; los mejores resultados publicados en consultas temporales (LongMemEval 63.8%), pero el grafo se construye de forma asíncrona, así que los hechos frescos pueden retrasarse |
-| Cognee | 30K | Ingesta de documento a grafo de conocimiento, solo Python, construido para extracción estructurada de entidades más que para captura de sesiones |
+| Zep / Graphiti | 30K | Grafo de conocimiento temporal; los resultados publicados más fuertes en consultas temporales (LongMemEval 63.8%), pero el grafo se construye de forma asíncrona, así que los hechos recientes pueden tardar en aparecer |
+| Cognee | 30K | Ingesta de documento a grafo de conocimiento, solo Python, construido para extracción estructurada de entidades en lugar de captura de sesiones |
Ninguno de estos captura automáticamente desde hooks de agentes de codificación, incluye un visor local-first ni funciona sin claves — la combinación en torno a la que está construido agentmemory.
@@ -463,75 +556,100 @@ Ninguno de estos captura automáticamente desde hooks de agentes de codificació
-Compatibilidad: esta release apunta a `iii-sdk` estable `^0.11.0` e iii-engine v0.11.x.
+Compatibilidad: esta release apunta a `iii-sdk` 0.22.1 y fija iii-engine v0.22.1.
### Pruébalo en 30 segundos
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest 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.
+`demo` siembra 3 sesiones realistas (JWT auth, fix de query N+1, rate limiting) y ejecuta búsquedas contra ellas. Las instalaciones sin claves desactivan los vectores, así que las consultas por palabra clave de `mem::search` deberían acertar a través de BM25 mientras que `database performance optimization` puede devolver cero. `smart-search` además puede devolver coincidencias estructurales del grafo cuando existen datos de grafo. Para que la consulta semántica encuentre el fix de N+1 a través de vectores, define `EMBEDDING_PROVIDER=local`, reinicia y deja que termine la primera descarga del modelo.
Abre `http://localhost:3113` para ver cómo se construye la memoria en directo.
+### Valida una instalación limpia y la persistencia tras reiniciar
+
+Con el servidor en marcha, valida REST, health, el visor y el estado del runtime respaldado por iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+El panel de arranque listo contempla los cuatro puertos: REST/MCP HTTP en 3111, streams de iii en 3112, el visor en 3113 y el WebSocket del worker de iii en 49134. `status` confirma la salud de agentmemory y el modo de proveedor/embedding activo. Guarda una sonda y confirma que es buscable:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Luego ejecuta `npx -y @agentmemory/agentmemory@latest stop`, arranca de nuevo el comando canónico en la Terminal 1, espera a `/agentmemory/livez`, y repite la búsqueda. La sonda debe seguir devolviéndose. Si elegiste un `--data-dir` personalizado, pasa el mismo directorio en el reinicio.
+
### Comandos del día a día
-La instalación y el setup viven en [Install](#install) más arriba (la primera ejecución te guía por todo). En el día a día:
+La instalación y el setup están en [Instalación](#install) arriba (la primera ejecución te guía paso a paso). Para el día a día:
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
-### Session Replay
+### Repetición de sesión
-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.5x a 4x) y atajos de teclado (espacio para alternar, flechas para avanzar paso a paso).
+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 tools, resultados de tools y respuestas se renderizan como eventos discretos con play/pause, control de velocidad (0.5x a 4x) y atajos de teclado (espacio para alternar, flechas para avanzar paso a paso).
-Para importar transcripciones JSONL antiguas de Claude Code:
+Para traer transcripciones JSONL antiguas de Claude Code:
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest 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. Cada transcripción importada se indexa para búsqueda, se sella con el canal de origen `import` y se mina para obtener un crystal de sesión y lecciones.
-> **Aviso si dependes de `import-jsonl` como tu ruta de captura principal:** el `cleanupPeriodDays` de Claude Code (en `~/.claude/settings.json`, por defecto **30**) borra automáticamente de `~/.claude/projects/` las transcripciones JSONL más antiguas que esa ventana. Si instalas agentmemory de cero sobre un historial de Claude Code de varios meses, todo lo anterior a 30 días ya ha desaparecido antes de la primera importación. O ejecuta `import-jsonl` en un cron, o sube `cleanupPeriodDays` a un valor mayor, o conecta los hooks de captura automática (la ruta de instalación por defecto del plugin) para que cada turno aterrice en agentmemory mientras la sesión está viva y la limpieza de JSONL deje de importar.
+> **Aviso si dependes de `import-jsonl` como tu ruta de captura principal:** el `cleanupPeriodDays` de Claude Code (en `~/.claude/settings.json`, por defecto **30**) borra automáticamente de `~/.claude/projects/` las transcripciones JSONL más antiguas que esa ventana. Si instalas agentmemory de cero sobre un historial de Claude Code de varios meses, todo lo anterior a 30 días ya ha desaparecido antes de la primera importación. O ejecutas `import-jsonl` en un cron, o subes `cleanupPeriodDays` a un valor mayor, o conectas los hooks de captura automática (la ruta de instalación por defecto del plugin) para que cada turno aterrice en agentmemory mientras la sesión está viva y la limpieza de JSONL deje de importar.
### Actualización / Mantenimiento
-Usa el comando de mantenimiento cuando intencionadamente quieras actualizar tu runtime local:
+Usa el comando de mantenimiento cuando quieras actualizar intencionadamente tu runtime local:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Aviso: este comando muta el workspace/runtime actual. Puede actualizar dependencias de JavaScript y traer la imagen Docker fijada `iiidev/iii:0.11.2`. Nunca instala un motor iii sin fijar ni más nuevo.
+Aviso: este comando muta el workspace/runtime actual. Puede actualizar dependencias de JavaScript y traer la imagen Docker fijada `iiidev/iii:0.22.1`. Nunca instala un iii engine sin fijar ni más nuevo.
-Los detalles de implementación están en `src/cli.ts` (ver `runUpgrade` en torno a la región `src/cli.ts:544-595`).
+Los detalles de implementación viven en `src/cli.ts` (ver `runUpgrade` alrededor de 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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code 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.
+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.22/scripts/…`), por lo que la siguiente actualización rompe silenciosamente todos los hooks.
-Solución:
+Workaround:
```bash
agentmemory connect claude-code --with-hooks
@@ -544,7 +662,7 @@ Para despliegues remotos o protegidos, lanza Claude Code con `AGENTMEMORY_URL` y
```bash
# 1. start the memory server in a separate terminal
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
@@ -553,29 +671,43 @@ 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 54 tools cuando `AGENTMEMORY_URL` apunta a un servidor agentmemory en ejecución; cae a 7 tools en local cuando no hay servidor accesible)
+- Un bridge MCP vía stdio empaquetado al daemon en ejecución, sin descarga npm ni almacén de fallback. Consulta la [guía local de Codex](../docs/plugins/codex-local.md) para probar una build aún no publicada.
- 6 hooks de ciclo de vida: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 skills invocables: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, más 8 skills de referencia que el agente carga bajo demanda (memory discipline, tools MCP, REST API, config, agentes, hooks, arquitectura y la guía de autoría de skills)
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)
+#### Confianza y compatibilidad de los hooks de Codex
+
+El despacho nativo de hooks de plugin está verificado con Codex CLI 0.150.1. Confía en los hooks del plugin antes de esperar captura. El comportamiento en Desktop depende de su runtime empaquetado; comprueba `/hooks` y confirma un evento capturado antes de habilitar un workaround.
+
+Si tu host requiere hooks globales, replica los comandos en `~/.codex/hooks.json`. Cuando el MCP ya está configurado, el conector actual necesita `--force` para llegar a la instalación de hooks:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Esto fusiona los hooks globales y reescribe la entrada MCP de agentmemory, preservando las entradas no relacionadas. Revisa cualquier configuración personalizada del endpoint de agentmemory antes de usar `--force`. Vuelve a ejecutar tras actualizar para refrescar las rutas de los scripts. Habilita los hooks nativos del plugin o las copias globales para evitar captura duplicada.
-`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.
+### GitHub Copilot CLI
-Hasta que se solucione upstream, replica los mismos comandos de hook en el `~/.codex/hooks.json` global:
+Para el modo agente de VS Code, usa la [guía de MCP y captura automática de Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). El conector de la CLI no configura VS Code.
```bash
-agentmemory connect codex --with-hooks
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
```
-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.
+`agentmemory connect copilot-cli` fusiona `mcpServers.agentmemory` en `~/.copilot/mcp-config.json` (o `$COPILOT_HOME/mcp-config.json` cuando `COPILOT_HOME` está definido) y preserva los servidores existentes. En Windows nativo este es el único adaptador `connect` automatizado; configura manualmente cualquier otro agente nativo de Windows. `connect` en WSL solo está soportado cuando el agente destino está instalado en ese mismo entorno WSL. Copilot detecta el servidor MCP en el siguiente arranque o tras `/mcp`. Instala también el plugin cuando quieras la experiencia completa de hooks/skills.
OpenClaw (pega este prompt)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -600,7 +732,7 @@ Guía completa: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (pega este prompt)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -619,7 +751,7 @@ Guía completa: [`integrations/hermes/`](../integrations/hermes/)
### Otros agentes
-Arranca el servidor de memoria: `npx @agentmemory/agentmemory`
+Arranca el servidor de memoria: `npx -y @agentmemory/agentmemory@latest`
#### Skills nativas vía `npx skills add` (50+ agentes)
@@ -633,14 +765,14 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Esto es **complementario** a `agentmemory connect `:
-- `agentmemory connect ` escribe la configuración del servidor MCP para que las tools estén disponibles.
+- `agentmemory connect ` escribe la config del servidor MCP para que las tools estén disponibles.
- `npx skills add rohitg00/agentmemory` instala las skills para que el agente sepa cuándo llamarlas.
Para los pocos agentes que la CLI de skills aún no cubre (Zed v1.3.x e inferiores), coloca tú mismo los 17 ficheros SKILL.md bajo el directorio de skills nativo del agente; el mismo formato funciona en todas partes.
#### Bloque MCP estándar
-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):
+La entrada de agentmemory es el **mismo bloque de servidor MCP** en todos los hosts que usan la forma `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
```json
"agentmemory": {
@@ -653,44 +785,46 @@ La entrada de agentmemory es el **mismo bloque de servidor MCP** en cada host qu
}
```
-**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).
+**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 conectada 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`. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` fusiona la entrada MCP; `--with-hooks` añade seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) con los matchers de herramientas en minúscula de Devin. Verifica con `devin mcp list` y `/hooks` dentro de devin. |
-| **Devin (nube)** | Settings → Connections → MCP servers | Añade un MCP personalizado (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` apuntando a un despliegue de agentmemory accesible por red más `AGENTMEMORY_SECRET` (las sesiones en la nube no alcanzan localhost — ver [`deploy/`](../deploy/)). |
+| **Cursor (solo MCP)** | `~/.cursor/mcp.json` | Fusiona en `mcpServers`, o `agentmemory connect cursor`. También hay un deeplink de un clic disponible en el sitio web. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Listado en el Cursor Marketplace (envío en revisión) o Cursor Settings → Plugins → checkout local. Registra 7 hooks de captura automática (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + el servidor MCP, con `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` gestionados en el dashboard de plugins de Cursor. Funciona en el IDE de Cursor y en la CLI `cursor-agent`; los prompts del modo print de la CLI se rellenan a posteriori desde la transcripción de la sesión al terminar. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Fusiona en `mcpServers`. Reinicia Claude Desktop después de editar. |
+| **Cline / Roo Code / Kilo Code** | Ajustes MCP de Cline (Settings UI → MCP Servers → Edit) | El mismo bloque `mcpServers`. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` fusiona la entrada MCP; `--with-hooks` añade seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) con los matchers de tools en minúscula de Devin. Verifica con `devin mcp list` y `/hooks` dentro de devin. |
+| **Devin CLI (plugin completo)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` desde un checkout registra las 17 skills como slash commands `/agentmemory:` más el servidor MCP. Los hooks de plugin de Devin no pueden disparar `SessionStart`/`SessionEnd`, así que combínalo con `connect devin --with-hooks` para captura de sesión completa. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Añade un MCP personalizado (STDIO): comando `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` apuntando a un despliegue de agentmemory alcanzable por red, más `AGENTMEMORY_SECRET` (las sesiones en la nube no pueden alcanzar localhost — ver [`deploy/`](../deploy/)). Guarda el secreto en Devin Secrets, y luego usa "Test listing tools" para verificar que aparecen las 54 tools. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (fusión automática). |
| **GitHub Copilot CLI (solo MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` fusiona `mcpServers.agentmemory`; Copilot lo detecta en el siguiente arranque o con `/mcp`. |
| **GitHub Copilot CLI (plugin completo)** | Instalación de plugin de Copilot | `copilot plugin install rohitg00/agentmemory:plugin` para el plugin desde el subdirectorio de GitHub. |
-| **OpenClaw** | Configuración MCP de OpenClaw | Mismo bloque `mcpServers`. Más profundo: `openclaw plugins install ./integrations/openclaw` reclama el slot de memoria de OpenClaw (cambia automáticamente desde `memory-core`); configura `plugins.entries.agentmemory.hooks.allowConversationAccess=true` o la captura de turnos queda bloqueada silenciosamente. Ver [`integrations/openclaw`](integrations/openclaw/). |
-| **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) + 17 skills. En Codex Desktop, ejecuta también `agentmemory connect codex --with-hooks` hasta que aterrice [openai/codex#16430](https://github.com/openai/codex/issues/16430); los hooks de plugin están silenciados allí por ahora. |
-| **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. La atribución de proyecto es por sesión, así que un único proceso de OpenCode que abarque varios repositorios archiva cada sesión bajo su propio proyecto. 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). |
+| **OpenClaw** | Configuración MCP de OpenClaw | El mismo bloque `mcpServers`. Más a fondo: `openclaw plugins install ./integrations/openclaw` reclama el slot de memoria de OpenClaw (cambia automáticamente desde `memory-core`); define `plugins.entries.agentmemory.hooks.allowConversationAccess=true` o la captura de turnos queda bloqueada silenciosamente. Ver [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (solo MCP)** | `.codex/config.toml` | Forma TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, o añade `[mcp_servers.agentmemory]` manualmente. |
+| **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 + 17 skills. Confía en los hooks y verifica la captura en tu host; consulta [configuración y validación de Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (solo MCP)** | `opencode.json` | Forma distinta: clave `mcp` de 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. La atribución de proyecto es por sesión, así que un único proceso de OpenCode que abarque varios repositorios archiva cada sesión bajo su propio proyecto. Dos slash commands (`/recall`, `/remember`). Copia `plugin/opencode/` a tu workspace de OpenCode y añade la entrada del plugin a `opencode.json`. Ver [`plugin/opencode/README.md`](../plugin/opencode/README.md) para la tabla completa de hooks + análisis de gaps. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instala la extensión empaquetada en el directorio de auto-descubrimiento de pi (recall al arrancar el agente, captura al terminar, tools `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). Un `/reload` en un pi en ejecución la detecta. [`integrations/pi`](../integrations/pi/) también es un paquete pi (`pi install ./integrations/pi` desde un checkout). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` activa el memory provider de 6 hooks (precarga, captura de turnos, fin de sesión, pre-compresión, espejado de MEMORY.md, bloque de system prompt). Valida con `hermes plugins doctor` y `hermes memory status`. Ver [`integrations/hermes`](integrations/hermes/). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` activa el memory provider de 6 hooks (prefetch, captura de turnos, fin de sesión, pre-compresión, espejado de MEMORY.md, bloque de system prompt). Valida con `hermes plugins doctor` y `hermes memory status`. Ver [`integrations/hermes`](../integrations/hermes/). |
| **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. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. La CLI `agy` mantiene su propia configuración bajo `~/.gemini/`, separada del IDE Antigravity de arriba. Pasa `--with-hooks` para captura automática nativa vía `~/.gemini/config/hooks.json`. |
-| **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. |
-| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` escribe el bloque `mcpServers` estándar. Warp también auto-descubre skills desde `.claude/skills/`; una vez instalado el plugin de Claude Code, las 8 skills de agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecen de forma nativa en la paleta de comandos slash de Warp. |
-| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` escribe el bloque `mcpServers` estándar. Usuarios de la extensión de VS Code: pegad el mismo bloque vía Cline Settings → MCP Servers → Edit JSON. |
-| **Continue.dev** | `~/.continue/config.yaml` (preferido) o `config.json` (legacy) | `agentmemory connect continue` crea `config.yaml` desde cero cuando no existe ninguno, o modifica el `config.json` existente. **Si ya tienes `config.yaml`** el adaptador imprime el bloque exacto a pegar bajo `mcpServers:`; no reescribirá tu yaml en silencio porque preservar comentarios y anchors con seguridad necesita un parser YAML que el paquete no incluye. Continue usa forma de array (no objeto) para `mcpServers`. |
-| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` escribe bajo `context_servers` (la clave de Zed, NO `mcpServers`). Los servidores MCP remotos pueden conectarse vía `{"url": "..."}` en su lugar. |
-| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` escribe el bloque `mcpServers` estándar. Los overrides por proyecto van en `/.factory/mcp.json`. Pasa `--with-hooks` para captura automática nativa. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instala el MCP y los hooks de captura en el directorio de personalización compartido. Consulta [configuración y límites de Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` usa la misma configuración de MCP y hooks que las versiones actuales del IDE. Las instalaciones existentes deben actualizar con `--force`; consulta las [notas de actualización](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` escribe la configuración a nivel de usuario. Los overrides de workspace van en `.kiro/settings/mcp.json` junto a tu código. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` escribe el bloque `mcpServers` estándar. Warp también auto-descubre skills desde `.claude/skills/`; una vez instalado el plugin de Claude Code, las 8 skills de agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecen de forma nativa en la paleta de slash commands de Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` escribe el bloque `mcpServers` estándar. Usuarios de la extensión de VS Code: pega el mismo bloque vía Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferido) o `config.json` (legacy) | `agentmemory connect continue` crea `config.yaml` desde cero cuando no existe ninguno, o modifica el `config.json` existente. **Si ya tienes `config.yaml`** el adaptador imprime el bloque exacto para pegar bajo `mcpServers:`; no reescribe tu yaml silenciosamente porque preservar comentarios y anchors de forma segura necesita un parser YAML que el paquete no incluye. Continue usa forma de array (no de objeto) para `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` escribe bajo `context_servers` (la clave de Zed, NO `mcpServers`). Los servidores MCP remotos se pueden conectar en su lugar vía `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` escribe el bloque `mcpServers` estándar. Los overrides con scope de proyecto van en `/.factory/mcp.json`. Pasa `--with-hooks` para captura automática nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` añade una fila `@deepseek-ai/dsh-mcp-client` a la capa de patch de nivel home que carga cada perfil de Harness; las tools se registran como `mcp__agentmemory__*`. Pasa `--with-hooks` para conectar también la captura automática: los scripts de hook de Claude Code empaquetados corren a través del bridge first-party de Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) vía un manifest escrito en `$DSH_HOME/agentmemory.hooks.json`. Por defecto `~/.dsh` cuando `DSH_HOME` no está definido. |
-| **Goose** | UI de ajustes MCP de Goose | Mismo bloque `mcpServers`; usa `goose configure` → Add Extension → MCP. La edición directa del YAML en `~/.config/goose/config.yaml` está soportada, pero el esquema usa `extensions:` + `cmd` (no `mcpServers:` + `command`). |
+| **Goose** | UI de ajustes MCP de Goose | El mismo bloque `mcpServers`; usa `goose configure` → Add Extension → MCP. La edición directa del YAML en `~/.config/goose/config.yaml` está soportada, pero el schema usa `extensions:` + `cmd` (no `mcpServers:` + `command`). |
| **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. |
+| **Cualquier agente (32+)** | n/a | `npx skillkit install agentmemory` autodetecta 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).
+**Clientes MCP en sandbox** (Flatpak / Snap / contenedores restrictivos) que no pueden alcanzar el `localhost` del host: añade también `"AGENTMEMORY_FORCE_PROXY": "1"` en el bloque `env`, y apunta `AGENTMEMORY_URL` a una ruta a la que el sandbox sí pueda llegar (p. ej. tu IP de LAN).
### 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.
+agentmemory registra sus operaciones principales como funciones iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Cualquier lenguaje con un SDK de iii puede llamarlas directamente sobre `ws://localhost:49134`, sin necesidad de un cliente REST separado por lenguaje.
```bash
pip install iii-sdk # Python
@@ -710,7 +844,7 @@ iii.trigger({
})
```
-Ejemplo trabajado: [`examples/python/`](../examples/python/) (quickstart + flujo de observación/recall). La REST en `:3111` sigue disponible para hosts sin runtime iii.
+Ejemplo trabajado: [`examples/python/`](../examples/python/) (quickstart + flujo de observación/recall). La REST en `:3111` sigue disponible para hosts sin runtime de iii.
### Desde el código fuente
@@ -719,39 +853,43 @@ 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.
+Esto arranca agentmemory con un `iii-engine` local si el binario fijado ya está instalado, o usa Docker Compose cuando se selecciona. REST, streams y el visor se enlazan a `127.0.0.1` por defecto. La ruta automática del binario en macOS/Linux requiere `curl`, un `sh` POSIX y `tar`.
+
+Instala `iii-engine` manualmente. **agentmemory actualmente fija `iii-engine` a `v0.22.1`**, la misma release que su dependencia `iii-sdk`; el worker habla el protocolo de ese motor, y 0.20.0 reorganizó la superficie del SDK, así que ambos avanzan juntos en cada release de agentmemory. Sobrescribe con `AGENTMEMORY_III_VERSION=` si ejecutas tu propio motor y sabes que coincide.
-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=` si has migrado al modelo sandbox manualmente.
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** sustituye `aarch64-apple-darwin` por `x86_64-apple-darwin`
+- **Linux x64:** sustituye por `x86_64-unknown-linux-gnu`
+- **Linux arm64:** sustituye por `aarch64-unknown-linux-gnu`
+- **Windows:** descarga `iii-x86_64-pc-windows-msvc.zip` desde [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) y extrae `iii.exe` a `%USERPROFILE%\.agentmemory\bin\iii.exe`
-- **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
+Cada archivo tiene un fichero `.sha256` correspondiente en la página de la release; cuando cambies de plataforma, usa el hash de ese fichero en la comprobación de arriba (en Windows: `Get-FileHash`). El instalador automático en `npx @agentmemory/agentmemory` fija estos hashes y rechaza un archivo que no coincida.
-O usa Docker (el `docker-compose.yml` empaquetado descarga `iiidev/iii:0.11.2`). Documentación completa: [iii.dev/docs](https://iii.dev/docs).
+O usa Docker (el `docker-compose.yml` empaquetado trae `iiidev/iii:0.22.1`). 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:
+agentmemory funciona en Windows 10/11, pero el paquete de Node.js por sí solo no es suficiente; también necesitas el runtime de iii-engine v0.22.1 fijado como proceso en segundo plano. La CLI no extrae automáticamente el ZIP de Windows, así que los usuarios de Windows nativo deben instalar `iii.exe` manualmente, usar WSL2 o elegir Docker Desktop.
-**Opción A: binario Windows preconstruido (recomendado)**
+La conexión MCP automatizada en Windows nativo solo soporta `agentmemory connect copilot-cli`. Para Claude Code, Codex, Cursor y cualquier otro agente nativo de Windows, copia el bloque MCP manual de [Otros agentes](#other-agents) en la configuración de Windows de ese agente. Ejecutar `connect` en WSL solo es apropiado cuando el agente destino también está instalado en ese mismo entorno WSL; no edita la configuración de un agente que vive en el host Windows.
+
+**Opción A: binario de 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)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**Opción B: Docker Desktop**
@@ -759,28 +897,29 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
-**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:
+**Opción C: solo MCP standalone (sin motor).** Si solo necesitas las tools MCP para tu agente y no necesitas la REST API, el visor o los cron jobs, omite el motor por completo:
```powershell
-npx -y @agentmemory/agentmemory mcp
+npx -y @agentmemory/agentmemory@latest 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:
+**Diagnóstico para Windows:** si `npx -y @agentmemory/agentmemory@latest` falla, vuelve a ejecutarlo con `--verbose` para ver el stderr real del motor. 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 ` |
-| 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) |
+| `The engine process started but the REST API never responded.` | Confirma que los cuatro puertos derivados están libres, verifica que el `iii.exe` fijado se mantuvo vivo, y luego vuelve a ejecutar con `--verbose` e inspecciona el stderr del motor capturado |
+| `Could not start iii-engine` | Ni `iii.exe` ni Docker están instalados. Ver la Opción A o B arriba |
+| Conflicto de puerto | `netstat -ano \| findstr :3111` para ver qué está ocupando el puerto, luego mátalo o usa `--port ` |
+| Se omite el fallback a Docker aunque Docker esté instalado | Asegúrate de que Docker Desktop esté realmente en ejecución (icono de la bandeja del sistema) |
-> Nota: el **motor** iii es un binario preconstruido, no un crate de cargo, así que no intentes instalarlo con `cargo install`. (Los **SDK** de iii sí están publicados en crates.io, npm y PyPI, pero agentmemory no los necesita.) Métodos de instalación del motor soportados, todos fijados a v0.11.2: el binario preconstruido v0.11.2 de arriba, el script de instalación `sh` upstream **con el pin de versión** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) y la imagen Docker `iiidev/iii:0.11.2`. Un simple `install.sh | sh` instala el motor **más reciente**, que agentmemory no soporta; pasa siempre `VERSION=0.11.2`. Lo más fácil de todo: simplemente ejecuta `npx @agentmemory/agentmemory`, que obtiene el motor fijado en `~/.agentmemory/bin` por ti.
+> Nota: el **motor** de iii es un binario preconstruido, no un crate de cargo, así que no intentes instalarlo con `cargo install`. (Los **SDKs** de iii sí están publicados en crates.io, npm y PyPI, pero agentmemory no los necesita.) Los métodos de instalación del motor soportados están todos fijados a v0.22.1: el binario preconstruido de arriba, la ruta de auto-instalación de agentmemory en macOS/Linux (requiere `curl`, `sh` POSIX y `tar`), y la imagen Docker `iiidev/iii:0.22.1`. Un `install.sh | sh` upstream simple instala el motor más reciente, que agentmemory no soporta. Usa `npx -y @agentmemory/agentmemory@latest`; en macOS/Linux obtiene el motor fijado en `~/.agentmemory/bin`.
---
@@ -791,10 +930,10 @@ 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
+arranque sobrescribe la configuración de 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
+`0.0.0.0` y usa rutas absolutas `/data`, genera el secreto HMAC, y
+luego baja privilegios de `root` a `node` con `gosu` antes de hacer exec
del CLI de agentmemory.
@@ -802,16 +941,23 @@ del CLI de agentmemory.
-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.
+El botón de despliegue de un clic de Render requiere un `render.yaml` en la raíz del repositorio, 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):
+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.
+- [`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.
+Solo se publica el puerto `3111`. El visor en `3113` permanece enlazado a
+loopback dentro del contenedor; el README de cada plantilla documenta la
+pauta de túnel SSH para alcanzarlo.
---
@@ -841,7 +987,7 @@ Todo agente de codificación con IA viene con memoria integrada: Claude Code tie
|---|---|---|
| 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) |
+| 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 |
@@ -857,9 +1003,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -877,7 +1024,7 @@ SessionStart hook fires
Modelada en cómo el cerebro humano procesa la memoria, incluida la consolidación del sueño.
-| Nivel | Qué | Analogía |
+| Tier | 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ó" |
@@ -934,21 +1081,25 @@ Recuperación de triple stream combinando tres señales:
Fusionado con Reciprocal Rank Fusion (RRF, k=60) y diversificado por sesión (máximo 3 resultados por sesión).
-El ranking híbrido aplica a la ruta principal de recall, no solo a `smart-search`: `mem::search` (detrás de `memory_recall`) rankea a través de la misma fusión BM25 + vector + grafo una vez que el índice vectorial está poblado. El recall de lecciones corre sobre un índice BM25 in-memory dedicado en lugar de escanear todo el corpus en cada consulta. Las versiones de memoria reemplazadas quedan excluidas de todas las rutas de recall; la cadena de versiones conserva su historial.
+Cuando el índice vectorial está poblado, `mem::search` (detrás de `memory_recall`) usa el ranker híbrido BM25 + vector. Sin embeddings usa BM25. `smart-search` además puede fusionar coincidencias estructurales del grafo cuando existen datos de grafo, incluso en modo sin claves. El recall de lecciones corre sobre un índice BM25 in-memory dedicado en lugar de escanear todo el corpus en cada consulta. Las versiones de memoria reemplazadas quedan excluidas de todas las rutas de recall; la cadena de versiones conserva su historial.
+
+Los vectores sobreviven a un crash o un force-kill. El índice vectorial se guarda en buckets como máximo cada `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutos). Cada vector añadido o eliminado entretanto también se escribe de inmediato en un pequeño log pendiente en el state store, y el siguiente arranque lo reproduce sin llamar al proveedor de embeddings. Cada guardado exitoso vacía el log. Los documentos que siguen sin vector tras la reproducción se re-embeben en segundo plano en lotes de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) hasta que no quede ninguno, y un backfill que se detiene continúa en el siguiente arranque. `/agentmemory/status` y el visor muestran el tamaño del log pendiente y el estado del backfill. Las instalaciones sin claves no escriben nada.
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):
+Las instalaciones sin claves desactivan los embeddings vectoriales: `mem::search` usa BM25, mientras que `smart-search` también puede usar datos estructurales de grafo existentes. Para optar por embeddings semánticos locales y gratuitos, añade esto a `~/.agentmemory/.env` y reinicia agentmemory:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+La instalación npm normal incluye el runtime opcional `@huggingface/transformers`. La primera petición de embedding descarga `Xenova/all-MiniLM-L6-v2`, así que necesita acceso a red y puede tardar más; la inferencia posterior corre en local. Los proveedores remotos se autodetectan a partir de sus claves a menos que `EMBEDDING_PROVIDER` los sobrescriba.
+
| Proveedor | Modelo | Coste | Notas |
|---|---|---|---|
-| **Local (recomendado)** | `all-MiniLM-L6-v2` | Gratis | Offline, +8pp de recall sobre BM25-only |
+| **Local (opt-in recomendado)** | `all-MiniLM-L6-v2` | Gratis | En local tras la primera descarga del modelo, +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 |
@@ -961,7 +1112,7 @@ npm install @huggingface/transformers
54 tools, 6 recursos, 3 prompts y 17 skills.
-> **Shim MCP vs servidor completo:** el paquete publicado `@agentmemory/mcp` es un shim ligero. Expone la superficie completa de 54 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`.
+> **Shim MCP vs servidor completo:** el paquete publicado `@agentmemory/mcp` es un shim ligero. Expone la superficie completa de 54 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 -y @agentmemory/agentmemory@latest` (o la stack Docker) y define `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
@@ -1046,20 +1197,20 @@ Tres superficies de tools, de menor a mayor: `AGENTMEMORY_TOOLS=core` recorta la
| Skill | `/session-history` | Resúmenes recientes de sesiones |
| Skill | `/forget` | Borra observaciones/sesiones |
-La tabla muestra las cuatro skills principales. El set completo son 8 skills invocables más 7 skills de referencia; consulta la sección de skills nativas más arriba.
+La tabla muestra las cuatro skills principales. El set completo son 9 skills invocables más 8 skills de referencia; consulta la sección de skills nativas más arriba.
### MCP standalone
-Ejecútalo sin el servidor completo, para cualquier cliente MCP. Cualquiera de estos funciona:
+Ejecuta sin el servidor completo, para cualquier cliente MCP. Cualquiera de estos funciona:
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (always available)
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
-O añádelo a la configuración MCP de tu agente:
+O añádelo a la config MCP de tu agente:
-La mayoría de los agentes (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+La mayoría de agentes (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1101,13 +1252,20 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Se inicia automáticamente en el puerto `3113`. Stream de observaciones en vivo con indicador de estado del stream, un explorador de sesiones de dos paneles (lista junto a un panel de detalle fijo en pantallas anchas), filas de memorias y lecciones que se expanden al registro completo almacenado incluyendo el JSON crudo y la provenance de origen, un grafo de conocimiento que agrupa nodos por tipo mientras las relaciones son escasas, replay de sesiones y un dashboard de salud.
+Arranca automáticamente en el puerto `3113`. El visor carga un snapshot al conectar (`GET /agentmemory/viewer/snapshot`) y luego aplica eventos de stream en vivo: memorias nuevas, lecciones, observaciones, entradas de auditoría, cambios de grafo y actualizaciones de salud aparecen sin polling ni recargas de página. Las únicas otras peticiones son las acciones que haces clic, las páginas de "cargar más" y las búsquedas. Cuando el stream se cae, el visor muestra cuán viejos son sus números, reconecta con backoff y resincroniza desde un snapshot.
+
+- **12 pestañas en cuatro grupos** con conteos en vivo, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), atajos de teclado y un menú móvil.
+- **Memories:** búsqueda del lado del servidor, filtros por proyecto, agente y tipo, un panel de detalle con la cadena de versiones y un word diff, enlaces de provenance, botones de copia para el id, la llamada MCP y un comando curl, edición (una nueva versión), forget con confirmación, forget masivo y exportación JSON.
+- **Sessions:** una línea de tiempo de observaciones inline con entrada y salida de tool legibles, filtros y paginación, y las memorias y lecciones que produjo cada sesión.
+- **Graph:** búsqueda, detalle de nodo con relaciones y fuentes, una leyenda que no depende solo del color, y controles de zoom.
+- **Health:** la versión en vivo de `GET /agentmemory/status`. Cada problema viene con su solución, además del backend de estado, el estado de guardado del índice, el progreso de compactación de provenance del grafo y una explicación de la consolidación con los umbrales reales.
+- Páginas **Audit, Activity, Profile, Replay, Lessons, Actions y Crystals**, cada una con un estado vacío que dice qué es la sección, por qué está vacía y el comando que la rellena, y un tooltip de glosario `?` en cada término y número.
```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'`).
+El servidor del visor se enlaza a `127.0.0.1` por defecto y adjunta el secreto del servidor cuando reenvía peticiones a la REST API, así que no necesita configuración. El endpoint `/agentmemory/viewer` servido por REST sigue las reglas habituales de bearer-token y redirige los navegadores sin token al puerto del visor. Las cabeceras CSP usan un nonce de script por respuesta y desactivan los atributos handler inline (`script-src-attr 'none'`).
---
@@ -1115,9 +1273,9 @@ El servidor del visor se enlaza a `127.0.0.1` por defecto. El endpoint servido p
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.
+Observa cómo se dispara un `memory_smart_search` y ve el BM25 scan → embedding lookup → fusión RRF → reranker como un waterfall. Edita un timer de consolidación atascado en el navegador de KV. Repite un hook `PostToolUse` con un payload modificado. Fija el stream de WebSocket y observa cómo aterrizan las observaciones en vivo.
-agentmemory ofrece esto gratis porque cada llamada a función y cada trigger se disparan a través de iii; nada custom, nada que instrumentar.
+agentmemory incluye esto gratis porque cada llamada a función y cada trigger se disparan a través de iii; nada personalizado, nada que instrumentar.
@@ -1125,22 +1283,20 @@ agentmemory ofrece esto gratis porque cada llamada a función y cada trigger se
Página Workers: cada worker conectado, incluida agentmemory, con PID, conteo de funciones, runtime y last-seen.
-**Ya instalada.** La console se incluye con `iii`; sin instalador aparte.
+**Ya está instalado.** La console se incluye con el `iii` engine fijado (0.22+); no hay nada separado que instalar. El primer lanzamiento descarga el binario de la console junto al motor.
**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
+agentmemory console
```
-Luego abre `http://localhost:3114`. Añade `--enable-flow` para la página experimental de grafo de arquitectura.
+Esto ejecuta el `iii console` del motor fijado contra los puertos que agentmemory resolvió (REST, streams, bridge) y lo sirve un puerto por encima del visor, `http://localhost:3114` por defecto. `--console-port N` elige otro puerto; `--port` y `--instance` seleccionan la instancia de agentmemory del mismo modo que lo hacen para `stop`; cualquier otro flag se pasa tal cual, por ejemplo `--enable-flow` para la página experimental de grafo de arquitectura.
-Sobrescribe endpoints del engine solo si los has movido:
+Lo mismo a mano, útil cuando `agentmemory` no está en el PATH:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1151,29 +1307,29 @@ iii console --port 3114 \
| 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 sobre sesiones, slots de memoria, temporizadores del ciclo de vida y el í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. |
+| **Functions** | Invoca cualquiera de las funciones de agentmemory directamente con un payload JSON; útil para probar `memory.recall`, `memory.consolidate`, `graph.query` sin conectar un cliente. |
+| **Triggers** | Repite triggers de HTTP, cron, eventos y estado: dispara el cron de consolidación manualmente, reintenta una ruta HTTP, emite un cambio de estado. |
+| **States** | Navegador de KV con CRUD completo sobre sesiones, slots de memoria, timers de ciclo de vida y el índice de embeddings; edita valores in situ. |
+| **Streams** | Monitor de WebSocket en vivo para escrituras de memoria, eventos de hook y actualizaciones de observaciones mientras fluyen por los streams de iii. |
+| **Queues** | Topics de queue durables + gestión de dead-letter. Repite o descarta jobs fallidos de embedding / compresión. |
+| **Traces** | Vistas waterfall / flame / service-breakdown de OpenTelemetry. 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 correlacionados con IDs de trace/span. |
+| **Config** | Configuración de runtime: ve exactamente con qué workers, proveedores y puertos está corriendo tu motor. |
| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitectura interactivo de cada worker, trigger y stream. |
- Traces: waterfall / flame / desglose por servicio para cada operación de memoria.
+ Traces: waterfall / flame / service breakdown para cada operación de memoria.
-**Las trazas ya están activas:**
+**Las traces 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.
+`iii-config.yaml` se sirve con el worker `iii-observability` habilitado (`exporter: memory`, `sampling_ratio: 0.1`, métricas + logs). No se necesita configuración adicional; en el momento en que agentmemory arranca, cada operación de memoria emite un log estructurado que la console puede leer, y una de cada diez (`sampling_ratio: 0.1`) emite además un trace span.
-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.
+Si en su lugar quieres exportar a Jaeger/Honeycomb/Grafana Tempo, 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.
+> **Aviso:** la console en sí no exige auth; manténla enlazada a `127.0.0.1` (el valor por defecto) y nunca la expongas públicamente.
---
@@ -1183,32 +1339,102 @@ agentmemory **ya es una instancia [iii](https://iii.dev) en ejecución**. Tres p
Eso significa que un comando más extiende agentmemory con una capacidad completamente nueva.
-### Extiende agentmemory con un comando
+### Extiende agentmemory con más workers
-```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
-```
+Los builtins que agentmemory necesita ya están en `iii-config.yaml` y arrancan con él: `iii-state` (KV), `iii-queue` (reintentos durables para los suscriptores de eventos), `iii-pubsub`, `iii-cron`, `iii-stream` e `iii-observability` (trazas OTEL, métricas y logs en cada función). Cualquier otra cosa del [registro de workers de iii](https://workers.iii.dev) se conecta al mismo motor: copia `iii-config.yaml` a `~/.agentmemory/iii-config.yaml` (la CLI prefiere ese fichero sobre el empaquetado y aun así renderiza en él los puertos y las rutas de datos), añade la entrada, instala el runtime del worker una vez con `~/.agentmemory/bin/iii update worker`, y reinicia agentmemory.
-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.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | Qué obtienes encima de agentmemory |
+| Worker | 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 |
+| [`database`](https://workers.iii.dev/workers/database) | Adaptador de estado respaldado por SQL para cuando superes los valores por defecto de KV en memoria |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | El código que sale de `memory_recall` corre dentro de una VM descartable, no en tu shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Levanta servidores MCP extra junto al de agentmemory, compartiendo el mismo motor |
+
+En el motor 0.22.x mantén los nombres con prefijo `iii-` para los builtins de arriba; las entradas sin prefijo `http`, `state`, `queue`, `pubsub` y `cron` son los workers standalone del registro a los que agentmemory se moverá con la migración a 0.23.
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.
+### Configuración del motor y dirección de bind
+
+`agentmemory start` lee la configuración del motor desde el primer fichero que exista: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` en el directorio actual, `~/.agentmemory/iii-config.yaml`, y luego el `iii-config.yaml` empaquetado. En cada arranque renderiza ese fichero (rutas de datos, puertos, backend de estado) en `~/.agentmemory/data/iii-config.runtime.yaml` y lanza el motor con la copia renderizada, así que edita el fichero fuente, no el renderizado. Los valores `host:` del fichero fuente se mantienen tal como están escritos.
+
+El `iii-config.yaml` empaquetado se enlaza a `127.0.0.1` a propósito, y ese valor por defecto también aplica dentro de un contenedor. Una CLI arrancada en un contenedor escucha en el loopback del contenedor, así que los puertos publicados no alcanzan nada. Para servir una CLI en contenedor a través de puertos publicados, define `AGENTMEMORY_III_CONFIG` a una config que se enlace a `0.0.0.0`. El `iii-config.docker.yaml` empaquetado es una de ellas: enlaza `iii-http`, `iii-stream` y el puerto del motor a `0.0.0.0` y almacena el estado bajo `/data`, así que monta ahí un volumen con permiso de escritura. Mantén `AGENTMEMORY_SECRET` definido, y publica solo los puertos que necesites, en `127.0.0.1` o detrás de un proxy de confianza.
+
+El `docker-compose.yml` de este repo no pasa por la búsqueda de config de la CLI: monta `iii-config.docker.yaml` en `/app/config.yaml`, y el contenedor `iii-engine` arranca con `--config /app/config.yaml`. Las [plantillas de despliegue](../deploy/) de un clic escriben su propia config `0.0.0.0` en sus entrypoints.
+
+### Backend de almacenamiento: file (por defecto) vs redis
+
+`iii-state` e `iii-stream` usan por defecto el almacén KV basado en ficheros que trae iii-engine: un fichero JSON por scope, mantenido en la memoria del proceso del motor y reescrito a disco con un timer. Ese es el valor por defecto correcto para una instalación local de un solo usuario; un daemon compartido con varios escritores concurrentes obtiene en cambio escrituras reales por clave desde Redis, al coste de un round trip de red por operación (cada llamada `state::*` sigue serializándose en una única conexión Redis, así que esto cambia el lock del file store por un socket, no por paralelismo).
+
+Define `AGENTMEMORY_STATE_BACKEND=redis` (más `AGENTMEMORY_REDIS_URL`) para cambiar ambos workers al adaptador `redis` integrado en iii-engine, que almacena cada clave como un campo de hash de Redis (`HSET`) en lugar de reescribir todo un scope en cada escritura:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` tiene por defecto `file`; dejarla sin definir mantiene el comportamiento actual sin cambios, y un valor no reconocido (cualquier cosa distinta de `file` o `redis`) es un error de arranque en lugar de un fallback silencioso. `/agentmemory/status` y la página Health del visor (la fila State store) informan de qué backend está activo y si responde, nunca la URL.
+
+**Solo `redis://` sin cifrar.** El motor fijado (0.22.1) construye su cliente Redis sin soporte TLS, así que una URL `rediss://` (la mayoría de ofertas de Redis gestionado, como Upstash, Redis Cloud y ElastiCache con cifrado en tránsito, usan TLS-only por defecto) falla al conectar. La conexión no está cifrada, así que la contraseña de Redis y cada memoria almacenada cruzan el cable en texto claro: apunta a un Redis local o a uno en una red privada de confianza. Para cualquier otro Redis, ejecuta un túnel cifrado (stunnel, SSH o una VPN) en el host de agentmemory, de modo que el salto `redis://` sin cifrar se quede en ese host y la conexión upstream del túnel esté cifrada y autenticada. Si una contraseña de Redis contiene una comilla simple, codifícala en percent-encoding (`%27`); el motor expande la URL dentro de su config YAML antes de parsearla.
+
+**Un servidor Redis por `--instance`.** Los prefijos de clave Redis del motor (`state:`, `stream::`) son fijos, así que dos instancias de agentmemory (`--instance 1`, `--instance 2`, ...) que apunten a la misma base de datos se sobrescriben los datos mutuamente. Un índice de base de datos separado (`redis://localhost:6379/1`) mantiene separados los datos almacenados, pero el motor retransmite los eventos del visor en vivo sobre un único canal pub/sub de Redis (`stream::events`), y el pub/sub de Redis ignora el índice de base de datos, así que el visor de cada instancia seguiría mostrando los eventos en vivo del otro. Dale a cada instancia su propio servidor Redis (o puerto) cuando ejecutes más de una.
+
+**Qué se mantiene igual, y qué difiere.** Todas las funciones de agentmemory funcionan sobre Redis: sesiones, observaciones, memorias (remember, supersede, evolve, forget), búsqueda y los buckets del índice, lecciones, el grafo, el log de auditoría y sus scopes mensuales, export e import, borrados de gobernanza, estado de consolidación, el snapshot del visor y su stream en vivo, y el monitor de salud. El motor almacena cada scope como un hash de Redis (`HSET`/`HGET`/`HGETALL`) y dispara los mismos triggers de estado que el file store. Tres diferencias del motor se gestionan dentro de agentmemory:
+
+- Redis devuelve los registros de un scope sin orden fijo. agentmemory los ordena del más antiguo al más reciente (por el tiempo de creación en el id del registro, luego por su timestamp) para que las listas, la paginación y los chunks de export vuelvan en el mismo orden que en el file store.
+- El motor aplica actualizaciones parciales en Redis mediante un script Lua que convierte los arrays vacíos en objetos vacíos. agentmemory aplica esas actualizaciones por sí mismo (leer, cambiar, escribir bajo un lock por clave) sobre Redis, así que campos como `tags: []` se mantienen como arrays.
+- La comprobación del log de auditoría legacy lee el scope antiguo desde Redis en lugar de buscar el fichero del file store en disco.
+
+Una diferencia requiere tu intervención: **tras un reinicio de Redis, el motor deja de retransmitir eventos en vivo** al visor hasta que agentmemory se reinicia. Los datos se siguen guardando y leyendo normalmente. El monitor de salud envía un evento de prueba a través de Redis cada 30 segundos; cuando no vuelve, `/agentmemory/status` y la página Health del visor muestran "Live updates are not reaching the viewer" con la solución: reiniciar agentmemory. Si Redis está caído, el informe de estado muestra "The state store is not answering" y cómo comprobarlo (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listar un scope muy grande lee todo el hash en un único `HGETALL`, el mismo coste que tiene el file store al mantenerlo en memoria.
+
+**Ajustes de Redis recomendados.** La política de snapshot por defecto `save 3600 1 300 100 60 10000` puede perder minutos de escrituras en un crash, peor que la ventana de flush de 5s del file store. Define `appendonly yes` para cualquier cosa cuya pérdida te importaría. Define `maxmemory-policy noeviction`; `allkeys-lru` o similar descarta memorias silenciosamente en cuanto Redis alcanza su límite de memoria.
+
+Un arranque nativo (sin Docker), y cada [plantilla de despliegue](../deploy/) de un clic (sobrescriben el `iii-config.yaml` empaquetado y arrancan de forma nativa), leen `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` y los renderizan en el `iii-config` lanzado. La URL en sí nunca se escribe en ese fichero renderizado, solo una referencia `${AGENTMEMORY_REDIS_URL}` que el proceso del motor expande desde su propio entorno al arrancar. Solo la ruta de Docker Compose propia de este repo (`AGENTMEMORY_USE_DOCKER=1`, o reanudar un motor ya arrancado de esa forma) monta `iii-config.docker.yaml` como solo lectura y nunca renderiza; `agentmemory start` avisa cuando detecta esa combinación. Cambia ese fichero a mano, siguiendo la misma forma `name: redis` / `config: redis_url: ...` que muestran los docs de los workers [iii-state](https://workers.iii.dev/workers/iii-state) e [iii-stream](https://workers.iii.dev/workers/iii-stream), y apunta `redis_url` a un Redis alcanzable desde el contenedor. `docker-compose.yml` pasa `AGENTMEMORY_REDIS_URL` al contenedor del motor, así que `redis_url: '${AGENTMEMORY_REDIS_URL}'` funciona ahí y mantiene la URL fuera del fichero montado.
+
+La config renderizada mantiene la URL fuera de `~/.agentmemory/data/iii-config.runtime.yaml`, pero el propio worker de configuración del motor sigue persistiendo el valor *expandido* en `~/.agentmemory/config/iii-state.yaml` y `iii-stream.yaml` una vez que arranca (la expansión de `${VAR}` de iii-engine ocurre antes de que ese worker guarde su seed, y guarda el valor resuelto, no la referencia). Trata ese directorio como si contuviera una credencial: `chmod 700 ~/.agentmemory` en cualquier host compartido, y prefiere un usuario de Redis ACL con scope a lo que agentmemory necesita en lugar de las credenciales de administrador de la base de datos.
+
+**La migración no es automática.** Cambiar `AGENTMEMORY_STATE_BACKEND` arranca desde un store vacío en ambos lados; nada copia los datos existentes de file a Redis o viceversa. Exporta desde el backend que dejas e importa en el que te mudas. Esto corre de forma idéntica en bash y zsh (incluido `bash -u`). Un array como `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` no: zsh mantiene la cabecera como una sola palabra malformada mientras que bash la divide en dos, así que ambas peticiones devuelven 401 siempre que `AGENTMEMORY_SECRET` esté definido:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` también acepta `?maxSessions=` y `?offset=` para dividir en chunks un corpus grande entre varias llamadas; `strategy` en import es `merge` (seguro por defecto), `replace` o `skip`.
+
### Qué reemplaza iii
| Stack tradicional | agentmemory usa |
@@ -1220,7 +1446,7 @@ Registro completo: [workers.iii.dev](https://workers.iii.dev). Cada worker allí
| Prometheus / Grafana | iii OTEL + monitor de salud |
| Sistemas de plugins propios | `iii worker add ` |
-**182 ficheros de código · ~41.600 LOC · 1.674 tests · 264 funciones · 50 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+**225 ficheros de código · ~54,000 LOC · 2,600+ tests · 312 funciones · 66 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
---
@@ -1228,22 +1454,22 @@ Registro completo: [workers.iii.dev](https://workers.iii.dev). Cada worker allí
### 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.
+agentmemory autodetecta proveedores desde tu entorno. Un proveedor habilita las operaciones respaldadas por LLM, pero configurar solo el proveedor no activa la compresión de observaciones escrita por LLM. Esa ruta requiere tanto un proveedor como `AGENTMEMORY_AUTO_COMPRESS=true`.
-| Proveedor | Configuración | Notas |
+| Proveedor | Config | 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. |
+| **No-op (por defecto)** | No necesita config | La compresión/resumen respaldados por LLM están desactivados. La compresión sintética y el recall por BM25 siguen funcionando. Ver `AGENTMEMORY_ALLOW_AGENT_SDK` más abajo si antes dependías del fallback por 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 |
| OpenAI API | `OPENAI_API_KEY` | Por defecto `gpt-5.6-luna`, sobrescribe con `OPENAI_MODEL` |
-| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) o `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Cualquier cosa compatible con la API de OpenAI. Coste cero, corre en tu hardware. Ver [Modelos locales](#modelos-locales-ollama--lm-studio--vllm) más abajo. |
-| 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, por eso ya no es el comportamiento por defecto. |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) o `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Cualquier cosa compatible con la API de OpenAI. Coste cero, corre en tu propio hardware. Ver [Modelos locales](#local-models-ollama--lm-studio--vllm) más abajo. |
+| Fallback por suscripción de Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Solo opt-in. Lanza sesiones de `@anthropic-ai/claude-agent-sdk`; antes causaba recursión sin límite en el hook Stop, así que ya no es el valor por defecto. |
### Modelos locales (Ollama / LM Studio / vLLM)
-agentmemory habla con cualquier servidor compatible con la API de OpenAI, así que cualquier cosa que exponga `/v1/chat/completions` funciona sin cambios de código. Sin claves de pago, sin nube, sin rate limits; corre por completo en tu hardware.
+agentmemory habla con cualquier servidor compatible con la API de OpenAI, así que cualquier cosa que expone `/v1/chat/completions` funciona sin cambios de código. Sin claves de pago, sin nube, sin rate limits; corre enteramente en tu hardware.
**Ollama** (puerto por defecto `11434`):
@@ -1270,44 +1496,44 @@ OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
-**vLLM / llama.cpp / Text Generation Inference**: la misma forma. Apunta `OPENAI_BASE_URL` a la URL que exponga tu servidor y define `OPENAI_MODEL` con un nombre que tu servidor acepte.
+**vLLM / llama.cpp / Text Generation Inference**: misma forma. Apunta `OPENAI_BASE_URL` a la URL que expone tu servidor y define `OPENAI_MODEL` con un nombre que tu servidor acepte.
-**Elección de modelo para trabajo de memoria**: la compresión y el resumen son tareas cortas (<2K tokens de entrada, <500 tokens de salida) donde un modelo instruct de 7B es más que suficiente. Recomendaciones:
+**Elecciones de modelo para trabajo de memoria**: la compresión y el resumen son tareas cortas (<2K tokens de entrada, <500 tokens de salida) para las que un modelo instruct de 7B es más que suficiente. Recomendaciones:
| Modelo | Tamaño | Por qué |
|-------|------|-----|
-| `qwen3:8b` | ~5.2 GB | Opción por defecto equilibrada en una máquina de 16 GB; fuerte en extracción y texto con forma de tools |
-| `qwen3:4b` | ~2.6 GB | La opción sensata más pequeña; correcta para compresión, más débil para extracción de grafos |
-| `qwen3-coder:30b` | ~19 GB | La mejor elección local para sesiones code-céntricas (30B MoE, 3.3B activos) en hardware de 24-32 GB |
+| `qwen3:8b` | ~5.2 GB | Valor por defecto equilibrado en una máquina de 16 GB; fuerte en extracción y texto con forma de tool |
+| `qwen3:4b` | ~2.6 GB | La opción razonable más pequeña; bien para compresión, más débil para extracción de grafo |
+| `qwen3-coder:30b` | ~19 GB | La mejor elección local para sesiones con forma de código (30B MoE, 3.3B activos) en hardware de 24-32 GB |
| `gpt-oss:20b` | ~14 GB | Modelo general fuerte que cabe en 16 GB de RAM |
-| `deepseek-r1:8b` | ~5.2 GB | Distill de reasoning; más lento pero con extracciones más limpias |
+| `deepseek-r1:8b` | ~5.2 GB | Distill de razonamiento; más lento pero con extracciones más limpias |
-Los modelos Qwen 3 piensan por defecto y pueden quemar todo el presupuesto de tokens razonando antes de emitir salida. Define `AGENTMEMORY_LLM_NOTHINK=1` para añadir `/no_think` a los prompts de extracción de grafos, y sube `MAX_TOKENS` (16384 funciona) si las extracciones vuelven vacías.
+Los modelos Qwen 3 piensan por defecto y pueden quemar todo el presupuesto de tokens en razonamiento antes de cualquier salida. Define `AGENTMEMORY_LLM_NOTHINK=1` para añadir `/no_think` a los prompts de extracción de grafo, y sube `MAX_TOKENS` (16384 funciona) si las extracciones vuelven vacías.
-Los modelos de clase reasoning (estilo `o1` con bloques ``) pueden devolver `content` vacío con un campo `reasoning` que tu servidor local quizá no exponga. Si las extracciones vuelven en blanco, cambia primero a un modelo sin reasoning. La variable `OPENAI_REASONING_EFFORT=none` también puede desactivar el thinking en los modelos thinking de Ollama Cloud que replican el esquema de reasoning de OpenAI.
+Los modelos de clase reasoning (estilo `o1` con bloques ``) pueden devolver `content` vacío con un campo `reasoning` que tu servidor local puede no exponer. Si las extracciones vuelven en blanco, cambia primero a un modelo que no sea reasoning. La variable de entorno `OPENAI_REASONING_EFFORT=none` también puede desactivar el thinking en los modelos thinking de Ollama Cloud que replican el schema de reasoning de OpenAI.
-Los embeddings locales vienen de serie vía `@huggingface/transformers`: `EMBEDDING_PROVIDER=local` (por defecto) te da `Xenova/all-MiniLM-L6-v2` (384 dims) por completo en el dispositivo. Sin configuración extra.
+Los embeddings locales se incluyen como dependencia opcional pero no están activados por defecto. Define `EMBEDDING_PROVIDER=local` para optar por `Xenova/all-MiniLM-L6-v2` (384-dim). La primera petición de embedding descarga el modelo; la inferencia corre en local después. Sin ese ajuste o una clave de embedding remota, los vectores se quedan desactivados, `mem::search` usa BM25, y `smart-search` todavía puede añadir coincidencias de grafo existentes.
### 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.
+Cuando la compresión en segundo plano escrita por LLM está activada con un proveedor y `AGENTMEMORY_AUTO_COMPRESS=true`, corre en cada observación, así que la elección de modelo cambia de forma significativa el gasto mensual. Datos de carga de trabajo capturados: 635 peticiones / 888K tokens / 35 horas de uso activo, ejecutados contra tres modelos de OpenRouter a los precios del 2026-05-23.
-| Tier | Modelo | Input / 1M | Output / 1M | Coste para las 35h capturadas | Notas |
+| Nivel | Modelo | Input / 1M | Output / 1M | Coste para las 35h capturadas | Notas |
|------|-------|------------|-------------|---------------------------|-------|
-| Recomendado | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | El DeepSeek más reciente; la elección recomendada más barata para cargas de compresión. |
-| 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 | `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-5` | $3.00 | $15.00 | ~$5.02 (est.) | Mismo precio de lista que la ejecución medida con Sonnet 4.6; precio de lanzamiento $2/$10 hasta el 2026-08-31. |
-| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Tier flagship; caro para trabajo de background siempre activo. |
-| Evitar | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modelo de clase flagship; sobrecoste para compresión. |
+| Recomendado | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | El DeepSeek más reciente; la elección recomendada más barata para cargas de trabajo de compresión. |
+| Recomendado | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Calidad sólida de compresión + resumen a ~10× menos coste que Sonnet. |
+| Recomendado | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Razonamiento de código fuerte si tus sesiones tienen una forma muy orientada a código. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Mismo precio de lista que la ejecución medida de Sonnet 4.6; precio de lanzamiento $2/$10 hasta el 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Nivel flagship; caro para trabajo en segundo plano siempre activo. |
+| Evitar | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modelo de clase flagship; sobregasto para compresión. |
-Las filas medidas provienen de la ejecución capturada; las filas (est.) escalan la misma mezcla de tokens según el precio de lista de cada modelo.
+Las filas medidas vienen de la ejecución capturada; las filas (est.) escalan la misma mezcla de tokens por el precio de lista de cada modelo.
-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.
+agentmemory imprime un aviso en runtime cuando `OPENROUTER_MODEL` coincide con un patrón de nivel 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 Flash / V4 Pro / Qwen3-Coder se quedan dentro del error de redondeo respecto a Sonnet en esta tarea, costando 10-70× menos. Reserva los modelos de tier premium para las consultas que leas directamente.
+Equilibrio entre calidad y coste para el trabajo de memoria: la compresión es una tarea de resumen con barras de calidad relativamente laxas (el agente vuelve a leer el resumen, no el usuario). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder quedan dentro del margen de error de Sonnet en esta tarea mientras cuestan 10-70× menos. Reserva los modelos de nivel premium para las consultas que lees directamente.
-Fuentes: [OpenRouter pricing for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+Fuentes: [precios de OpenRouter para Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [notas de precios de DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
### Memoria multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1324,12 +1550,12 @@ 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. |
+| `shared` (por defecto) | sí | no | Contexto cross-agent con pista de auditoría. El architect puede ver lo que anotó el developer, pero cada fila registra quién lo dijo. |
+| `isolated` | sí | sí | Separación estricta. El architect nunca ve las 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 etiqueta cuando `AGENT_ID` está definido: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. El rol fluye desde `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=` 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.
+Qué se filtra en modo isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Cada endpoint acepta `?agentId=` para sobrescribir 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. La tool MCP `memory_save` expone el mismo campo `agentId`, el servidor stdio standalone reenvía tanto `agentId` como `project`, y las memorias guardadas llevan `agentId` al índice de búsqueda, de modo que la búsqueda con scope de agente cubre tanto memorias como observaciones.
@@ -1339,14 +1565,18 @@ Cuando `AGENT_ID` no está definido, la memoria permanece sin scope (comportamie
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 |
+| Puerto | Proceso | Propósito | Override de entorno |
|------|---------|---------|--------------|
| `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`) |
+| `3112` | iii-engine | Worker de streams interno (consumido por agentmemory + visor) | `III_STREAM_PORT` (preferido) o el legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Visor en tiempo real (`http://localhost:3113`) | `III_VIEWER_PORT` o `AGENTMEMORY_VIEWER_URL` para la URL reportada |
+| `49134` | iii-engine | WebSocket; los workers se registran aquí, la telemetría OTel fluye por encima | `III_ENGINE_PORT` o `III_ENGINE_URL` |
+
+`--port ` cambia el ancla REST y deriva streams `N+1`, visor `N+2` y WebSocket del motor `N+46023` solo donde el puerto o URL explícito correspondiente de arriba no está definido. No crea un namespace de ciclo de vida aislado. Usa `--instance 1` para un segundo daemon; usa el ancla 3211, por defecto `3211/3212/3213/49234`, y recibe un directorio de datos y ciclo de vida `instance-1` separado. Las instancias 1 a 50 siguen el mismo patrón.
+
+El motor fijado arranca con `--no-update-check` (sin búsquedas de actualización o avisos de seguridad contra GitHub al arrancar) y con la telemetría anónima de uso de iii desactivada: agentmemory define `III_TELEMETRY_ENABLED=false` para el motor que lanza a menos que tú mismo exportes la variable, y el fichero compose empaquetado hace lo mismo.
-Limpieza de procesos zombi cuando los puertos quedan ocupados tras una ejecución crasheada:
+Limpieza de procesos obsoletos cuando los puertos se quedan ocupados tras una ejecución que crasheó:
```bash
# macOS / Linux — find whatever is on each port and kill it
@@ -1359,11 +1589,11 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` recoge limpiamente tanto el worker como el pidfile del engine en un shutdown graceful. En modo Docker desmonta solo los servicios compose propios de agentmemory y recoge el worker nativo antes del teardown de Docker; la CLI además se niega a adoptar o señalizar como engine nativo a procesos Docker o de VM que retengan los puertos (Docker backend, vpnkit, colima) a menos que se pase `--force`. La limpieza manual de arriba solo aplica al caso post-crash en el que no queda ningún pidfile.
+`agentmemory stop` recoge limpiamente tanto el worker como el pidfile del motor en un shutdown nativo graceful. En modo Docker vacía el worker nativo, detiene el contenedor del motor validado exacto, y preserva tanto el contenedor como su montaje `/data` para un reinicio sin pérdida; el siguiente arranque valida y reanuda ese mismo contenedor. La desinstalación respaldada por Docker requiere `agentmemory remove --keep-data`: elimina los ficheros compartidos gestionados por agentmemory mientras preserva el contenedor validado, su montaje de datos y el registro de ciclo de vida necesario para recuperarlos. El borrado destructivo de datos de Docker se deja intencionadamente al operador tras un backup. La CLI también se niega a adoptar o señalizar como motor nativo a los tenedores de puertos de Docker o VM (backend de Docker, vpnkit, colima) a menos que se pase `--force`. 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.
+Pon 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.
@@ -1374,18 +1604,20 @@ 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:
+Para probar con una suscripción Claude Code Pro/Max en lugar de una API key, haz opt-in explícitamente:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-Activa graph o consolidation en el mismo fichero si las quieres:
+La compresión de observaciones escrita por LLM requiere ambas líneas: acceso a un proveedor de LLM (incluyendo este fallback explícito de suscripción) y `AGENTMEMORY_AUTO_COMPRESS=true`. Un proveedor por sí solo deja en su lugar la ruta de compresión sintética por defecto.
+
+La consolidación (nodos de grafo, lecciones, crystals) está activada por defecto siempre que haya un proveedor de LLM configurado. Opta por salir explícitamente con `CONSOLIDATION_ENABLED=false` si quieres una operación sin LLM. La extracción de grafo es un flag separado:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Variables de entorno
@@ -1427,13 +1659,15 @@ Crea `~/.agentmemory/.env`:
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1451,14 +1685,20 @@ Crea `~/.agentmemory/.env`:
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1499,13 +1739,43 @@ Crea `~/.agentmemory/.env`:
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
-# CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1519,17 +1789,34 @@ Crea `~/.agentmemory/.env`:
-124 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer ` cuando `AGENTMEMORY_SECRET` está definido, y los endpoints de mesh sync requieren `AGENTMEMORY_SECRET` en ambos peers.
+138 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer `, y los endpoints de mesh sync requieren un `AGENTMEMORY_SECRET` definido explícitamente en ambos peers.
+
+**La autenticación está activada por defecto.** Cuando `AGENTMEMORY_SECRET` no está definida (ni en el shell ni en `~/.agentmemory/.env`), el servidor genera un secreto aleatorio en el primer arranque y lo guarda en `~/.agentmemory/secret` con modo `0600`. Todos los clientes empaquetados lo leen desde ahí cuando hablan con un servidor local: la CLI, el visor, los hooks bajo `plugin/scripts`, el servidor MCP y el shim `@agentmemory/mcp`, las configs escritas por `agentmemory connect`, y las integraciones empaquetadas de OpenCode, Pi, OpenClaw, Hermes y filesystem-watcher. El secreto guardado solo se envía a URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explícito siempre gana, y los clientes remotos igualmente necesitan tenerlo definido. Docker y los entrypoints de `deploy/` ya generan y exportan su propio secreto. Para llamar a la API a mano:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Reglas de petición para escrituras.** Las peticiones `POST`, `PUT`, `PATCH` y `DELETE` a la REST API y al visor deben enviar `Content-Type: application/json` (un parámetro `charset` está bien) siempre que lleven body, y una cabecera `Origin`, cuando está presente, debe ser un origen de loopback para el puerto REST o del visor configurado, o estar listada en `VIEWER_ALLOWED_ORIGINS` (separados por comas, p. ej. `https://memory.example.com`). Los clientes que no envían cabecera `Origin` (CLI, hooks, MCP, curl, server-to-server) no se ven afectados. El visor también acepta su propio origen.
+
+**Rutas de fichero.** Los endpoints que leen o escriben ficheros (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) solo aceptan rutas bajo `~/.agentmemory`, el directorio de datos de la instancia, o un directorio listado en `AGENTMEMORY_IMPORT_ROOT` (separa varios con `:`, o `;` en Windows). `/replay/import-jsonl` también acepta su valor por defecto `~/.claude/projects`. `/obsidian/export` se mantiene dentro de `AGENTMEMORY_EXPORT_ROOT` y `/migrate` dentro de `~/.agentmemory`. Los symlinks se resuelven antes de cada comprobación.
+
+**Eliminación de secretos.** Las API keys, bearer tokens, bloques de clave privada PEM y credenciales embebidas en URLs (`scheme://user:password@host`) se redactan antes de almacenar el texto, en cada ruta de escritura: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, salida de compresión y resumen, crystals y nodos de grafo.
Endpoints principales
| 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 |
+| `GET` | `/agentmemory/health` | Comprobación de salud (siempre pública) |
+| `GET` | `/agentmemory/status` | Qué va mal y cómo arreglarlo (HTML para navegadores, JSON en el resto de casos) |
+| `GET` | `/agentmemory/viewer/snapshot` | Todo lo que muestra el visor, en una sola respuesta |
+| `POST` | `/agentmemory/session/start` | Arranca sesión + obtiene contexto |
+| `POST` | `/agentmemory/session/end` | Termina sesión |
+| `POST` | `/agentmemory/observe` | Captura observación (ver entrega de captura más abajo) |
+| `GET` | `/agentmemory/capture` | Inbox de captura, dead letters y spool offline |
+| `POST` | `/agentmemory/capture/retry` | Reintenta capturas dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Envía ahora el spool offline local |
| `POST` | `/agentmemory/smart-search` | Búsqueda híbrida |
| `POST` | `/agentmemory/context` | Genera contexto |
| `POST` | `/agentmemory/remember` | Guarda en memoria a largo plazo |
@@ -1539,6 +1826,7 @@ Crea `~/.agentmemory/.env`:
| `GET` | `/agentmemory/export` | Exporta todos los datos |
| `POST` | `/agentmemory/import` | Importa desde JSON |
| `POST` | `/agentmemory/graph/query` | Consulta del grafo de conocimiento |
+| `POST` | `/agentmemory/graph/compact` | Recorta provenance de grafo sobredimensionado |
| `POST` | `/agentmemory/team/share` | Comparte con el equipo |
| `GET` | `/agentmemory/audit` | Pista de auditoría |
@@ -1546,6 +1834,35 @@ Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+**Entrega de captura.** Los hooks envían cada observación una vez a `POST /agentmemory/observe` con un `eventId`. Es el id propio del host para la llamada cuando el payload tiene uno (por ejemplo el `tool_use_id` de Claude Code), o si no, un hash de la sesión, el tipo de hook, el nombre de la tool, la entrada, la salida y el timestamp del host. El servidor escribe el evento en un inbox de captura en el state store, almacena la observación, y luego elimina la entrada del inbox. El código de estado indica qué pasó:
+
+| Status | campo `status` | Significado |
+|---|---|---|
+| `201` | `accepted` | Almacenado. `observationId` es la nueva observación. |
+| `202` | `accepted` (`state: "retrying"`) | Aceptado, pero el almacenado falló. El servidor lo reintenta, también tras un reinicio. |
+| `200` | `duplicate` | Este `eventId` ya fue aceptado. `observationId` es la observación existente; no se almacena nada nuevo. |
+| `400` / `422` | `rejected` | Payload inválido, o el almacenado falló definitivamente (el evento se guarda como dead letter). |
+| `503` | `rejected` (`retryable: true`) | El inbox está lleno (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Los hooks almacenan el evento en el spool y lo envían después. |
+
+Los eventos fallidos se reintentan cada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) con backoff que se duplica, hasta `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Los eventos que siguen fallando se quedan en el inbox como dead letters, aparecen listados en `/agentmemory/status` y en la página Health del visor, y se pueden reintentar con `POST /agentmemory/capture/retry` (`{"eventId": "..."}` o `{"all": true}`). Los ids de evento aceptados se recuerdan durante `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 horas, como máximo `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), así que un hook repetido tras un timeout o un reinicio se almacena una vez, mientras que dos llamadas a tool separadas con sus propios ids de host se almacenan dos veces aunque su contenido sea idéntico. Cuando una observación se borra (forget, borrado de sesión, eviction, auto-forget o un import que reemplaza el store), su evento se marca como borrado antes de eliminar la observación, así que repetir ese evento dentro de la misma ventana se responde como duplicado y no almacena nada. El state store escribe a disco cada 2 segundos, así que un evento respondido todavía puede estar solo en memoria por un instante. Para cubrir eso, cada respuesta `2xx` también lleva el `bootId` del servidor (nuevo en cada arranque), `acceptedAt` y `durableAfterMs` (el intervalo de guardado más 1.5 s en el file store, 1.5 s en redis, donde la persistencia es un ajuste del operador). Los hooks mantienen el evento en el spool local hasta que pasa esa ventana y lo borran en una llamada posterior sin otra petición. Si el `bootId` ha cambiado para entonces, el servidor se reinició, así que el hook envía el evento de nuevo con el mismo `eventId`; un evento que sí llegó a disco no se almacena dos veces. El servidor también envía esos eventos por sí mismo al arrancar y en cada intervalo de reintento, así que un reinicio no pierde nada aunque ningún hook corra después. Los hooks antiguos ignoran los campos extra, y los hooks nuevos contra un servidor más antiguo descartan el evento en `2xx` como antes.
+
+Cuando el servidor está caído, no responde a tiempo o devuelve un 5xx, el hook añade la observación a un fichero de spool local, `/capture-spool/-.jsonl` (sobrescribe la carpeta con `AGENTMEMORY_CAPTURE_SPOOL_DIR`). El fichero es privado para tu usuario (modo 600), los secretos se redactan de la misma forma que los redacta el servidor, contiene como máximo `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) y descarta entradas más viejas que `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Cuando está lleno, las entradas nuevas se descartan y se cuentan, y `/agentmemory/status` lo reporta. El hook sigue saliendo con código 0 dentro de su límite de tiempo y no añade ninguna petición cuando el servidor está sano. El spool se envía en el siguiente arranque y por el primer hook que vuelve a alcanzar el servidor, en un proceso en segundo plano para que el agente no espere. Los ids de evento hacen esto seguro: una observación que sí llegó antes de un timeout no se almacena dos veces. `npx @agentmemory/agentmemory capture` muestra el spool y el inbox del servidor, `--drain` envía el spool ahora, y `GET /agentmemory/capture` devuelve lo mismo como JSON. Define `AGENTMEMORY_CAPTURE_SPOOL=false` para desactivar el spool.
+
+**Compactación de provenance del grafo.** Cada nodo y edge del grafo de conocimiento guarda los ids de las 32 observaciones más recientes de las que proviene. Los stores escritos antes de ese tope pueden contener miles de ids por nodo caliente, lo que ralentiza la búsqueda de grafo y el visor, o tira el worker. agentmemory soluciona esto por sí mismo: en el primer arranque tras actualizar, recorta cada nodo, edge, edge reemplazado (el historial temporal del grafo) y el snapshot cacheado hasta el tope en segundo plano, en pequeños slices con una pausa entre ellos, para que la búsqueda, la captura y el visor sigan funcionando. Guarda su progreso, se reanuda tras un reinicio y nunca vuelve a correr una vez que ha terminado. `/agentmemory/status` y la página Health del visor lo muestran como pending, running (con el scope y la posición actuales), done o failed. Define `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` para desactivarlo.
+
+Para ejecutarlo a mano, llama a `POST /agentmemory/graph/compact`. Recorre los índices de nombre y de clave de edge en lugar de listar cada nodo y edge, y es seguro volver a ejecutarlo. Cuando recorta ids escribe una entrada de auditoría `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+En un store grande, o cuando la llamada devuelve 504, ejecútalo en slices. Envía `scope` (`nodes`, `edges` o `history`), `offset` y `limit`, y luego vuelve a llamar con el `nextOffset` devuelto hasta que sea `null`. Haz esto para `nodes`, `edges` y `history`, y termina con una llamada `{"scope":"snapshot"}`, porque una ejecución en slices no toca el snapshot cacheado.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1553,11 +1870,11 @@ Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**Requisitos previos:** Node.js >= 20, [iii-engine](https://iii.dev/docs) o Docker
+**Requisitos previos:** Node.js >= 20 con npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 o Docker. La instalación automática del motor en macOS/Linux también requiere `curl`, un `sh` POSIX y `tar`; Windows nativo usa el `iii.exe` fijado manual, WSL2 o Docker Desktop.
diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.md
new file mode 100644
index 0000000000..45f9227a39
--- /dev/null
+++ b/READMEs/README.fi-FI.md
@@ -0,0 +1,1881 @@
+
+
+
+
+
+
+ Koodausagenttisi muistaa kaiken. Ei enää tarvetta selittää asioita uudelleen.
+ Perustuu iii-moottoriin
+
+ Pysyvä muisti seuraaville: Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ja mikä tahansa MCP-asiakas.
+
+
+---
+
+## Asennus
+
+Vaatimukset:
+
+- Node.js 20 tai uudempi, mukana npm ja npx (`node -v`, `npm -v` ja `npx -v`).
+- macOS/Linux-automaattiasennus iii-moottorille vaatii lisäksi `curl`:n, POSIX-yhteensopivan `sh`:n ja `tar`:n. Minimaaliset levykuvat kuten `node:20-slim` eivät välttämättä sisällä niitä.
+- Natiivi Windows vaatii kiinnitetyn iii-engine v0.22.1 -version `iii.exe`-tiedoston asentamista käsin. WSL2 tai Docker Desktop ovat muut tuetut reitit.
+
+Kanoninen tuore asennuskomento:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Ensimmäinen käynnistys on vuorovaikutteinen asetusvaihe: valitse kytkettävät agentit (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), valitse LLM-tarjoaja tai pysy avaimettomana, ja se alustaa asetukset, käynnistää muistipalvelimen ja sen kiinnitetyn iii-moottorin, ja tarjoutuu asentamaan itsensä globaalisti, jotta paljas `agentmemory`-komento toimii myöhemmin kaikkialla. `-y` hyväksyy npx:n pakettikehotteen ja `@latest` välttää vanhentuneen välimuistiin jääneen julkaisun. Tarjoaja tekee LLM-ominaisuudet käytettäväksi, mutta LLM:n kirjoittama havaintojen pakkaus käynnistyy vain, kun myös `AGENTMEMORY_AUTO_COMPRESS=true` on asetettu.
+
+Avaimeton tila poistaa vektoriupotukset käytöstä. `memory_recall` (`mem::search`-reitti) käyttää BM25:tä, kun taas `memory_smart_search` voi myös yhdistää rakenteellisia graafiosumia, kun graafidataa on jo olemassa. Saadaksesi ilmaisen, laitteella toimivan semanttisen muistinhaun, aseta `EMBEDDING_PROVIDER=local` tiedostoon `~/.agentmemory/.env` ja käynnistä uudelleen. Ensimmäinen upotuspyyntö lataa mallin `Xenova/all-MiniLM-L6-v2`; päättely toimii sen jälkeen paikallisesti.
+
+Paikallinen ajonaikainen ympäristö käyttää neljää porttia: `3111` REST/MCP HTTP:lle, `3112` iii-streameille, `3113` katseluohjelmalle ja `49134` iii-workerin WebSocketille. Pysyvä iii-tila sijaitsee polussa `~/Library/Application Support/agentmemory` macOS:llä, `$XDG_DATA_HOME/agentmemory` tai `~/.local/share/agentmemory` Linuxilla ja `%APPDATA%\agentmemory` Windowsilla. Käytä `--data-dir ` -valitsinta tai `AGENTMEMORY_DATA_DIR`-muuttujaa ylikirjoittaaksesi tämän, ja käytä samaa arvoa jokaisella uudelleenkäynnistyksellä. Taustayhteensopivuuden vuoksi olemassa oleva `./data/state_store.db` tai `./data/iii-config.yaml` ajaa instanssin 0 kohdalla alustan oletuksen edelle; nimenomainen lippu tai ympäristömuuttuja voittaa edelleen.
+
+Todista sitten, että muistin palauttaminen toimii, ja anna agentillesi sen taidot:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Avainsanahakujen pitäisi osua oletuksena avaimettomassa tilassa BM25:n kautta. Demon `database performance optimization` -kysely on tarkoituksella semanttinen ja voi palauttaa nolla tulosta, ennen kuin upotustarjoaja on määritetty.
+
+Haluatko antaa koodausagentin hoitaa koko homman? Anna sille yksi ohje:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Kytke lisää agentteja milloin tahansa komennolla `agentmemory connect ` — 20 sovitinta listattuna kohdassa [Toimii jokaisen agentin kanssa](#works-with-every-agent). Täysi komentoviite kohdassa [Pika-aloitus](#quick-start).
+
+
+Windows
+
+Nopein reitti on WSL2. Natiivi Windows-moottorin asennus vaatii kiinnitetyn v0.22.1-ZIP-paketin latauksen ja `iii.exe`:n purkamisen käsin; CLI ei pura sitä automaattisesti. Docker Desktop on myös tuettu. Katso [Windows-huomautukset](#windows) vaihe vaiheelta.
+
+
+
+
+Globaali asennus / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Yllä oleva npx-komento pysyy kanonisena tuoreena asennusreittinä ja välttää globaalin etuliitteen oikeusongelmat.
+
+
+
+
+npx tarjoaa vanhan version
+
+npx käyttää välimuistia versioittain. Pakota uusin versio komennolla `npx -y @agentmemory/agentmemory@latest`, tai tyhjennä välimuisti kerran komennolla `rm -rf ~/.npm/_npx` (macOS/Linux; Windowsilla poista `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Oma iii-moottori on jo käynnissä
+
+agentmemory kiinnittää iii-engine-version v0.22.1:een ja ei liity eri versioon (worker ei osaa puhua toisen moottorin protokollaa). Pysäytä toinen moottori ja aja sitten `npx -y @agentmemory/agentmemory@latest`. Se asentaa ja ajaa kiinnitetyn v0.22.1-version polussa `~/.agentmemory/bin`, jättäen oman `iii`-asennuksesi koskemattomaksi.
+
+
+
+---
+
+
+
+agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST-rajapintaa. Kaikki agentit jakavat saman muistipalvelimen.
+
+
+ Toimii minkä tahansa agentin kanssa, joka puhuu MCP:tä tai HTTP:tä. Yksi palvelin, muistot jaettuna kaikkien kesken.
+
+
+---
+
+Selität saman arkkitehtuurin joka istunnossa. Löydät uudelleen samat bugit. Opetat uudelleen samat mieltymykset. Sisäänrakennettu muisti (CLAUDE.md, .cursorrules) tukkeutuu 200 riviin ja vanhenee. agentmemory korjaa tämän. Se tallentaa huomaamattomasti, mitä agenttisi tekee, pakkaa sen hakukelpoiseksi muistiksi ja syöttää oikean kontekstin, kun seuraava istunto alkaa. Yksi komento. Toimii agenttien välillä.
+
+**Mikä muuttuu:** Istunnossa 1 otat käyttöön JWT-autentikoinnin. Istunnossa 2 pyydät rate limitingiä. Agentti tietää jo, että autentikointisi käyttää jose-middlewarea tiedostossa `src/middleware/auth.ts`, että testisi kattavat tokenin validoinnin, ja että valitsit josen jsonwebtokenin sijaan Edge-yhteensopivuuden vuoksi — ei tarvetta selittää uudelleen eikä kopioi-liitä-työtä.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Oletuksena agentmemory tallentaa iii-moottorin tilan sen repositorion ulkopuolelle, josta se käynnistetään: `~/Library/Application Support/agentmemory` macOS:llä, `$XDG_DATA_HOME/agentmemory` tai `~/.local/share/agentmemory` Linuxilla ja `%APPDATA%\agentmemory` Windowsilla. Olemassa oleva vanha `./data/state_store.db` tai `./data/iii-config.yaml` käytetään uudelleen instanssille 0 ennen tätä alustan oletusta. Valitaksesi sijainnin nimenomaisesti, välitä `--data-dir ` tai aseta `AGENTMEMORY_DATA_DIR`; kumpi tahansa nimenomainen asetus ajaa vanhan tunnistuksen edelle:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Natiivi- ja Docker-käynnistykset käyttävät samaa ratkaistua isäntähakemistoa; Docker liittää sen pisteeseen `/data`. `--instance 1` liittää `instance-1`-hakemiston ratkaistuun hakemistoon ja valitsee erillisen oletusporttineljännyksen `3211/3212/3213/49234`.
+
+Uusimmat julkaisutiedot: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Hakutarkkuus
+
+**coding-agent-life-v1** (talon sisäinen korpus, hiekkalaatikossa toistettavissa)
+
+| Sovitin | P@5 | R@5 | Top-5-osumasuhde | p50-latenssi |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep-perustaso | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100 % top-5-osumasuhde **P@5-matemaattisessa kattossa** tälle korpukselle (0.240, katso scorecard). Hybrid hakee jokaisen kultaisen istunnon. grep jättää huomiotta 1/2 kultaisesta moni-istuntoisessa temporaalikyselyssä. Hyöty on **muistaminen + temporaalisuus**, ei kokonaistarkkuus. Tämä benchmark on pieni ja kultadataltaan harva; isompi LongMemEval-S alla erottelee paremmin. Täysi tyyppikohtainen erittely + korjaushuomautus: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 kysymystä)
+
+| Järjestelmä | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| vain BM25 -varmistusreitti | 86.2% | 94.6% | 71.5% |
+
+
+
+Benchmark-huomautus: vain agentmemoryn R@5 on omaa mitattua tulostamme (LongMemEval-S, toistettavissa tiedostosta benchmark/COMPARISON.md). mem0- ja Letta-luvut ovat niiden julkaisemia LoCoMo-lukuja (eri aineisto); MemPalace-, supermemory-, TencentDB (PersonaMem) - ja oracleagentmemory-luvut ovat valmistajien itse ilmoittamia väitteitä, joita emme ole itsenäisesti toistaneet (oracleagentmemoryn ajo käytti GPT-5.5:tä Oracle AI Databasea vastaan). Esitetty rinnakkain vain suuntaa antavana, ei pää-pää-vertailuna samalla datalla. Tähtimäärät ovat likimääräisiä ja muuttuvat ajan myötä.
+
+**Uudemmat tulokkaat**, hyvä tietää, syvemmin vertailtuna kohdassa [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Järjestelmä | ⭐ | Näkökulma |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporaalinen tietograafi; vahvimmat julkaistut temporaalikyselytulokset (LongMemEval 63.8%), mutta graafi rakentuu asynkronisesti, jolloin tuoreet faktat voivat viivästyä |
+| Cognee | 30K | Dokumentista tietograafiksi -tuonti, vain Python, rakennettu rakenteelliseen entiteettipoimintaan istuntotallennuksen sijaan |
+
+Mikään näistä ei tallenna automaattisesti koodausagenttien hookeista, toimita paikallista katseluohjelmaa tai toimi avaimetta — yhdistelmä, jonka ympärille agentmemory on rakennettu.
+
+---
+
+
+
+Yhteensopivuus: tämä julkaisu kohdistuu `iii-sdk`-versioon 0.22.1 ja kiinnittää iii-engine-version v0.22.1.
+
+### Kokeile 30 sekunnissa
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` siementää 3 realistista istuntoa (JWT-autentikointi, N+1-kyselyn korjaus, rate limiting) ja ajaa hakuja niitä vastaan. Avaimettomat asennukset poistavat vektorit käytöstä, niin että `mem::search`-avainsanakyselyiden pitäisi osua BM25:n kautta, kun taas `database performance optimization` voi palauttaa nolla tulosta. `smart-search` voi lisäksi palauttaa rakenteellisia graafiosumia, kun graafidataa on olemassa. Saadaksesi semanttisen kyselyn löytämään N+1-korjauksen vektoreiden avulla, aseta `EMBEDDING_PROVIDER=local`, käynnistä uudelleen ja anna ensimmäisen mallilatauksen valmistua.
+
+Avaa `http://localhost:3113` nähdäksesi muistin rakentuvan reaaliajassa.
+
+### Vahvista tuore asennus ja uudelleenkäynnistyksen pysyvyys
+
+Kun palvelin on käynnissä, vahvista REST, health, katseluohjelma ja iii-pohjaisen ajonaikaisen ympäristön tila:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Käynnistyksen valmiuspaneeli huomioi kaikki neljä porttia: REST/MCP HTTP portissa 3111, iii-streamit portissa 3112, katseluohjelma portissa 3113 ja iii-workerin WebSocket portissa 49134. `status` vahvistaa agentmemoryn terveyden ja aktiivisen tarjoaja-/upotustilan. Tallenna koetin ja vahvista, että se on hakukelpoinen:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Aja sitten `npx -y @agentmemory/agentmemory@latest stop`, käynnistä kanoninen komento uudelleen Terminaalissa 1, odota `/agentmemory/livez`-vastausta ja toista haku. Koettimen on edelleen tultava takaisin. Jos valitsit mukautetun `--data-dir`-arvon, välitä sama hakemisto uudelleenkäynnistyksessä.
+
+### Päivittäiset komennot
+
+Asennus ja käyttöönotto löytyvät yllä kohdasta [Asennus](#install) (ensimmäinen käynnistys opastaa sinut läpi sen). Päivittäin:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Istunnon toisto
+
+Jokainen agentmemoryn tallentama istunto on toistettavissa. Avaa katseluohjelma, valitse **Replay**-välilehti ja selaa aikajanaa: kehotteet, työkalukutsut, työkalujen tulokset ja vastaukset renderöityvät erillisinä tapahtumina toisto/tauko-painikkeella, nopeudensäädöllä (0.5x–4x) ja pikanäppäimillä (välilyönti vaihtaa, nuolet askeltavat).
+
+Tuodaksesi vanhempia Claude Coden JSONL-transkriptioita:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Tuodut istunnot näkyvät Replay-valitsimessa natiivien istuntojen rinnalla. Konepellin alla kukin merkintä kulkee funktioiden `mem::replay::load`, `mem::replay::sessions` ja `mem::replay::import-jsonl` läpi, ei sivukanavapalvelimia. Jokainen tuotu transkriptio indeksoidään hakua varten, leimataan alkuperäkanavalla `import` ja louhitaan istuntokristalliksi ja opetuksiksi.
+
+> **Huomio, jos nojaat `import-jsonl`-komentoon ensisijaisena tallennusreittinä:** Claude Coden `cleanupPeriodDays` (tiedostossa `~/.claude/settings.json`, oletus **30**) poistaa automaattisesti JSONL-transkriptiot, jotka ovat vanhempia kuin tämä ikkuna, kansiosta `~/.claude/projects/`. Jos asennat agentmemoryn tuoreena useita kuukausia vanhan Claude Code -historian päälle, kaikki 30 päivää vanhempi on jo poissa ennen ensimmäistä tuontia. Aja `import-jsonl` cron-ajastettuna, nosta `cleanupPeriodDays`-arvoa korkeammaksi, tai kytke automaattitallennushookit (oletusarvoinen plugin-asennusreitti), jotta jokainen vuoro päätyy agentmemoryyn istunnon ollessa käynnissä ja JSONL-siivous lakkaa merkitsemästä.
+
+### Päivitys / ylläpito
+
+Käytä ylläpitokomentoa, kun haluat tarkoituksella päivittää paikallisen ajonaikaisen ympäristösi:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Varoitus: tämä komento muuttaa nykyistä työtilaa/ajonaikaista ympäristöä. Se voi päivittää JavaScript-riippuvuuksia ja hakea kiinnitetyn `iiidev/iii:0.22.1`-Docker-imagen. Se ei koskaan asenna kiinnittämätöntä tai uudempaa iii-moottoria.
+
+Toteutuksen yksityiskohdat löytyvät tiedostosta `src/cli.ts` (katso `runUpgrade` alueen `src/cli.ts:544-595` kohdalla).
+
+### Claude Code (yksi lohko, liitä se)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code ilman pluginin asennusta (itsenäinen MCP-reitti)
+
+Jos kytket agentmemoryn MCP-palvelimen tiedoston `~/.claude.json` kautta suoraan sen sijaan, että käyttäisit `/plugin install`-komentoa, Claude Code ei koskaan ratkaise muuttujaa `${CLAUDE_PLUGIN_ROOT}`, ja sinun on osoitettava hook-skriptit absoluuttisiin polkuihin tiedostossa `~/.claude/settings.json`. Nämä polut sisältävät tyypillisesti agentmemoryn versionumeron (esim. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), niin että seuraava päivitys hajottaa hiljaisesti kaikki hookit.
+
+Kiertotapa:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Tämä yhdistää samat hook-komennot tiedostoon `~/.claude/settings.json` absoluuttisilla poluilla, jotka osoittavat asennetun `@agentmemory/agentmemory`-paketin mukana tulevaan `plugin/`-hakemistoon. Aja komento uudelleen agentmemoryn päivityksen jälkeen päivittääksesi polut. Käyttäjän omat merkinnät samassa tiedostossa säilyvät; vain aiemmat agentmemory-merkinnät korvataan. `/plugin install`-reitti pysyy suositeltuna lähestymistapana.
+Etä- tai suojattuja käyttöönottoja varten käynnistä Claude Code `AGENTMEMORY_URL`- ja `AGENTMEMORY_SECRET`-muuttujat asetettuina. Plugin välittää molemmat arvot sen mukana tulevalle MCP-palvelimelle; kun `AGENTMEMORY_URL` on tyhjä, MCP-shim käyttää osoitetta `http://localhost:3111`.
+
+### Codex CLI (Codexin plugin-alusta)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex-plugin toimitetaan samasta `plugin/`-hakemistosta kuin Claude Code -plugin. Se rekisteröi:
+
+- Mukana tuleva stdio MCP -silta käynnissä olevaan daemoniin, ilman npm-latausta tai fallback-varastoa. Katso [paikallinen Codex-opas](../docs/plugins/codex-local.md) testataksesi julkaisematonta buildia.
+- 6 elinkaarihookia: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 kutsuttavaa taitoa: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 viitetaitoa, jotka agentti lataa tarpeen mukaan (muistikuri, MCP-työkalut, REST-rajapinta, asetukset, agentit, hookit, arkkitehtuuri ja taitojen kirjoittamisen opas)
+
+Codexin hook-moottori injektoi `CLAUDE_PLUGIN_ROOT`-muuttujan hook-aliprosesseihin (ks. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), niin että samat hook-skriptit toimivat molemmissa isännissä päällekkäisyyttä aiheuttamatta. Subagent-/SessionEnd-/Notification-/TaskCompleted-/PostToolUseFailure-tapahtumat ovat vain Claude Codelle, eikä niitä rekisteröidä Codexille.
+
+#### Codex-hookit: luottamus ja yhteensopivuus
+
+Natiivi plugin-hookien välitys on vahvistettu Codex CLI -versiolla 0.150.1. Luota plugin-hookeihin ennen kuin odotat tallennusta. Desktop-käytös riippuu sen mukana tulevasta ajonaikaisesta ympäristöstä; tarkista `/hooks` ja vahvista tallennettu tapahtuma ennen kuin otat kiertotavan käyttöön.
+
+Jos isäntäsi vaatii globaaleja hookeja, peilaa komennot tiedostoon `~/.codex/hooks.json`. Kun MCP on jo kytketty, nykyinen sovitin tarvitsee `--force`-valitsimen päästäkseen hook-asennukseen:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Tämä yhdistää globaalit hookit ja kirjoittaa agentmemory MCP -merkinnän uudelleen säilyttäen muut merkinnät. Tarkista mahdolliset mukautetut agentmemoryn päätepisteasetukset ennen `--force`-valitsimen käyttöä. Aja uudelleen päivityksen jälkeen päivittääksesi skriptien polut. Ota käyttöön natiivit plugin-hookit tai globaalit kopiot kaksinkertaisen tallennuksen välttämiseksi.
+
+### GitHub Copilot CLI
+
+VS Coden agenttitilaa varten käytä [Copilotin MCP- ja automaattitallennusopasta](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-sovitin ei määritä VS Codea.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` yhdistää `mcpServers.agentmemory`-merkinnän tiedostoon `~/.copilot/mcp-config.json` (tai `$COPILOT_HOME/mcp-config.json`, kun `COPILOT_HOME` on asetettu) ja säilyttää olemassa olevat palvelimet. Natiivilla Windowsilla tämä on ainoa automatisoitu `connect`-sovitin; määritä kaikki muut natiivit Windows-agentit käsin. WSL `connect` on soveltuva vain, kun kohdeagentti on asennettu samaan WSL-ympäristöön. Copilot ottaa MCP-palvelimen käyttöön seuraavalla käynnistyksellä tai `/mcp`-komennon jälkeen. Asenna myös plugin, kun haluat täyden hook-/taito-kokemuksen.
+
+
+OpenClaw (liitä tämä kehote)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Täysi opas: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (liitä tämä kehote)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Täysi opas: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Muut agentit
+
+Käynnistä muistipalvelin: `npx -y @agentmemory/agentmemory@latest`
+
+#### Natiivit taidot komennolla `npx skills add` (50+ agenttia)
+
+agentmemory toimittaa 17 taitoa Claude-Code-tyylisessä `/SKILL.md`-formaatissa: 9 kutsuttavaa toimintotaitoa (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) ja 8 viitetaitoa, jotka agentti lataa tarpeen mukaan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Viitetaidot kuljettavat lähdekoodista generoituja datataulukoita, niin ne eivät koskaan ajaudu pois synkasta. vercel-labsin [`skills`](https://npmjs.com/package/skills)-CLI asentaa ne automaattisesti kutsuvan agentin natiiviin taitohakemistoon yli 50 agentin yli (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf ja monet muut):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Tämä on **täydentävä** komennolle `agentmemory connect `:
+
+- `agentmemory connect ` kirjoittaa MCP-palvelimen asetukset, jotta työkalut ovat käytettävissä.
+- `npx skills add rohitg00/agentmemory` asentaa taidot, jotta agentti tietää, milloin kutsua niitä.
+
+Niille harvoille agenteille, joita skills-CLI ei vielä kata (Zed v1.3.x ja vanhemmat), pudota 17 SKILL.md-tiedostoa agentin natiiviin taitohakemistoon itse; sama formaatti toimii kaikkialla.
+
+#### Standardi MCP-lohko
+
+agentmemory-merkintä on **sama MCP-palvelinlohko** jokaisessa isännässä, joka käyttää `mcpServers`-muotoa (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Yhdistä tämä merkintä olemassa olevaan `mcpServers`-objektiin** isännän asetustiedostossa; älä korvaa tiedostoa. Jos tiedostossa on jo muita palvelimia, lisää `agentmemory` niiden viereen toisena avaimena `mcpServers`-objektin sisällä. Jos `mcpServers` puuttuu kokonaan, liitä lohko rakenteen `{ "mcpServers": { ... } }` sisään. `${VAR}`-paikkamerkit perivät `AGENTMEMORY_URL`/`AGENTMEMORY_SECRET`-arvot shellistä MCP-palvelimen käynnistyshetkellä; asettamattomat muuttujat välittävät tyhjiä merkkijonoja, ja shim palaa osoitteeseen `http://localhost:3111`. Yksi kytketty merkintä kattaa molemmat: paikallisen ja etäisen (k8s / reverse-proxyn takana olevan) käyttöönoton.
+
+| Agentti | Asetustiedosto | Huomautuksia |
+|---|---|---|
+| **Cursor (vain MCP)** | `~/.cursor/mcp.json` | Yhdistä `mcpServers`-objektiin, tai `agentmemory connect cursor`. Yhden klikkauksen deeplink saatavilla myös sivustolla. |
+| **Cursor (täysi plugin)** | `.cursor-plugin/` | Cursor Marketplace -listaus (hakemus katselmoinnissa) tai Cursor Settings → Plugins → paikallinen checkout. Rekisteröi 7 automaattitallennushookia (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 taitoa + MCP-palvelimen, ja `AGENTMEMORY_URL`/`AGENTMEMORY_SECRET` hallitaan Cursorin plugin-kojelaudalla. Toimii Cursor IDE:ssä ja `cursor-agent`-CLI:ssä; CLI:n print-tilan kehotteet täydennetään jälkikäteen istunnon transkriptiosta istunnon päättyessä. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Yhdistä `mcpServers`-objektiin. Käynnistä Claude Desktop uudelleen muokkauksen jälkeen. |
+| **Cline / Roo Code / Kilo Code** | Clinen MCP-asetukset (Settings-käyttöliittymä → MCP Servers → Edit) | Sama `mcpServers`-lohko. |
+| **Devin CLI (MCP + hookit)** | `~/.config/devin/config.json` | `agentmemory connect devin` yhdistää MCP-merkinnän; `--with-hooks` lisää kuusi natiivia automaattitallennushookia (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) Devinin pienaakkosisilla työkalusovittimilla. Vahvista komennolla `devin mcp list` ja `/hooks` devinin sisällä. |
+| **Devin CLI (täysi plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` checkoutista rekisteröi kaikki 17 taitoa `/agentmemory:`-pikakomentoina sekä MCP-palvelimen. Devinin plugin-hookit eivät voi laukaista `SessionStart`/`SessionEnd`-tapahtumia, niin yhdistä se komentoon `connect devin --with-hooks` täyden istuntotallennuksen saamiseksi. |
+| **Devin (pilvi)** | Settings → Connections → MCP servers | Lisää mukautettu MCP (STDIO): komento `npx`, argumentit `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` osoittamassa verkon tavoittamaan agentmemory-käyttöönottoon, plus `AGENTMEMORY_SECRET` (pilvi-istunnot eivät tavoita localhostia — katso [`deploy/`](../deploy/)). Tallenna salaisuus Devin Secretsiin, käytä sitten "Test listing tools" -toimintoa vahvistaaksesi, että kaikki 54 työkalua näkyvät. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (yhdistää automaattisesti). |
+| **GitHub Copilot CLI (vain MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` yhdistää `mcpServers.agentmemory`; Copilot ottaa sen käyttöön seuraavalla käynnistyksellä tai `/mcp`-komennolla. |
+| **GitHub Copilot CLI (täysi plugin)** | Copilot-pluginin asennus | `copilot plugin install rohitg00/agentmemory:plugin` GitHub-alikansion pluginille. |
+| **OpenClaw** | OpenClawin MCP-asetukset | Sama `mcpServers`-lohko. Syvemmälle: `openclaw plugins install ./integrations/openclaw` ottaa OpenClawin muistipaikan haltuun (vaihtaa automaattisesti `memory-core`:sta); aseta `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, tai tallennus estyy hiljaisesti. Katso [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (vain MCP)** | `.codex/config.toml` | TOML-muoto: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, tai lisää `[mcp_servers.agentmemory]` käsin. |
+| **Codex CLI (täysi plugin)** | Codexin plugin-markkinapaikka | `codex plugin marketplace add rohitg00/agentmemory`, sitten `codex plugin add agentmemory@agentmemory`. Rekisteröi MCP + 6 elinkaarihookia + 17 taitoa. Luota hookeihin ja varmista tallennus isännässäsi; katso [Codexin asennus ja validointi](../docs/plugins/codex-local.md). |
+| **OpenCode (vain MCP)** | `opencode.json` | Eri muoto: ylätason `mcp`-avain, komento taulukkona: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (täysi plugin)** | `plugin/opencode/` | 22 automaattitallennushookia kattaen istunnon elinkaaren, viestit, työkalut ja virheet. Projektiattribuutio on istuntokohtainen, niin yksi OpenCode-prosessi, joka kattaa useita repositorioita, tallentaa jokaisen istunnon oman projektinsa alle. Kaksi pikakomentoa (`/recall`, `/remember`). Kopioi `plugin/opencode/` OpenCode-työtilaasi ja lisää plugin-merkintä tiedostoon `opencode.json`. Katso [`plugin/opencode/README.md`](../plugin/opencode/README.md) täydelle hook-taulukolle + puuteanalyysille. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` asentaa mukana tulevan laajennuksen pi:n automaattisen tunnistuksen hakemistoon (palautus agentin käynnistyessä, tallennus agentin päättyessä, `memory_search`/`memory_save`/`memory_health`-työkalut, `/agentmemory-status`). `/reload` käynnissä olevassa pi:ssä ottaa sen käyttöön. [`integrations/pi`](../integrations/pi/) on myös pi-paketti (`pi install ./integrations/pi` checkoutista). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` antaa 6-hookisen muistitarjoajan (esihaku, vuoron tallennus, istunnon päättyminen, esipakkaus, MEMORY.md-peilaus, system prompt -lohko). Vahvista komennoilla `hermes plugins doctor` ja `hermes memory status`. Katso [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` kirjoittaa standardin `mcpServers`-lohkon. Hook-hyötykuorma on kenttätasolla yhteensopiva Claude Coden kanssa, niin olemassa olevat 12-hookin skriptit toimivat muokkaamatta; kytke ne `hooks`-osiossa samassa `settings.json`-tiedostossa. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` asentaa MCP:n ja tallennushookit jaettuun mukautushakemistoon. Katso [Antigravityn asennus ja rajoitukset](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` käyttää samaa MCP- ja hook-määritystä kuin nykyiset IDE-versiot. Olemassa olevat asennukset tulisi päivittää `--force`-valitsimella; katso [päivitysohjeet](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` kirjoittaa käyttäjätason asetukset. Työtilakohtaiset ylikirjoitukset menevät tiedostoon `.kiro/settings/mcp.json` koodisi vierelle. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` kirjoittaa standardin `mcpServers`-lohkon. Warp myös tunnistaa automaattisesti taidot kansiosta `.claude/skills/`; kun Claude Code -plugin on asennettu, 8 agentmemory-taitoa (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) näkyvät natiivisti Warpin pikakomentopaletissa. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` kirjoittaa standardin `mcpServers`-lohkon. VS Code -laajennuksen käyttäjät: liitä sama lohko Cline Settings → MCP Servers → Edit JSON -kautta. |
+| **Continue.dev** | `~/.continue/config.yaml` (suositeltu) tai `config.json` (vanha) | `agentmemory connect continue` luo tiedoston `config.yaml` tyhjästä, kun kumpaakaan ei ole, tai muokkaa olemassa olevaa `config.json`-tiedostoa. **Jos sinulla on jo `config.yaml`**, sovitin tulostaa tarkan lohkon liitettäväksi `mcpServers:`-kohtaan; se ei hiljaa uudelleenkirjoita yamliasi, koska kommenttien ja ankkureiden turvallinen säilyttäminen vaatisi YAML-jäsentimen, jota paketti ei toimita. Continue käyttää taulukkomuotoa (ei objektia) `mcpServers`-kentälle. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` kirjoittaa avaimen `context_servers` alle (Zedin avain, EI `mcpServers`). Etä-MCP-palvelimet voidaan kytkeä myös muodolla `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` kirjoittaa standardin `mcpServers`-lohkon. Projektikohtaiset ylikirjoitukset menevät tiedostoon `/.factory/mcp.json`. Välitä `--with-hooks` natiivia automaattitallennusta varten. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` lisää `@deepseek-ai/dsh-mcp-client`-rivin kotihakemistotason patch-kerrokseen, jonka joka Harness-profiili lataa; työkalut rekisteröityvät muodossa `mcp__agentmemory__*`. Välitä `--with-hooks` kytkeäksesi myös automaattitallennuksen: mukana tulevat Claude Code -hook-skriptit kulkevat Harnessin ensiosapuolen `@deepseek-ai/dsh-hooks-claude-code`-sillan läpi (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) manifestin kautta, joka kirjoitetaan tiedostoon `$DSH_HOME/agentmemory.hooks.json`. Oletusarvo on `~/.dsh`, kun `DSH_HOME` on asettamatta. |
+| **Goose** | Goosen MCP-asetuskäyttöliittymä | Sama `mcpServers`-lohko; käytä `goose configure` → Add Extension → MCP. Suora YAML-muokkaus polussa `~/.config/goose/config.yaml` on tuettu, mutta skeema käyttää `extensions:` + `cmd` (ei `mcpServers:` + `command`). |
+| **Aider** | ei saatavilla | Puhu suoraan REST-rajapinnalle: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Mikä tahansa agentti (32+)** | ei saatavilla | `npx skillkit install agentmemory` tunnistaa isännän automaattisesti ja yhdistää. |
+
+**Hiekkalaatikoidut MCP-asiakkaat** (Flatpak / Snap / rajoittavat kontit), jotka eivät tavoita isännän `localhost`-osoitetta: aseta lisäksi `"AGENTMEMORY_FORCE_PROXY": "1"` `env`-lohkoon, ja osoita `AGENTMEMORY_URL` reitille, jonka hiekkalaatikko oikeasti tavoittaa (esim. LAN-IP-osoitteesi).
+
+### Ohjelmallinen pääsy (Python / Rust / Node)
+
+agentmemory rekisteröi sen ydintoiminnot iii-funktioina (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Mikä tahansa kieli, jolla on iii-SDK, voi kutsua niitä suoraan osoitteen `ws://localhost:49134` kautta, ei erillistä REST-asiakasta per kieli.
+
+```bash
+pip install iii-sdk # Python
+cargo add iii-sdk # Rust
+npm install iii-sdk # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+ "function_id": "mem::smart-search",
+ "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Toimiva esimerkki: [`examples/python/`](../examples/python/) (pika-aloitus + havainnointi-/palautusvirta). REST portissa `:3111` pysyy saatavilla isännille, joilla ei ole iii-ajonaikaista ympäristöä.
+
+### Lähdekoodista
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Tämä käynnistää agentmemoryn paikallisella `iii-engine`-moottorilla, jos kiinnitetty binääri on jo asennettu, tai käyttää Docker Composea, kun se on valittu. REST, streamit ja katseluohjelma sitoutuvat oletuksena osoitteeseen `127.0.0.1`. Automaattinen macOS/Linux-binääripolku vaatii `curl`:n, POSIX-yhteensopivan `sh`:n ja `tar`:n.
+
+Asenna `iii-engine` käsin. **agentmemory kiinnittää tällä hetkellä `iii-engine`-versioon `v0.22.1`**, samaan julkaisuun kuin sen `iii-sdk`-riippuvuus; worker puhuu kyseisen moottorin lankaprotokollaa, ja 0.20.0 järjesti SDK-pinnan uudelleen, niin molemmat liikkuvat yhdessä agentmemoryn julkaisuissa. Ylikirjoita arvolla `AGENTMEMORY_III_VERSION=`, jos ajat omaa moottoriasi ja tiedät, että se täsmää.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** vaihda `aarch64-apple-darwin` tilalle `x86_64-apple-darwin`
+- **Linux x64:** vaihda tilalle `x86_64-unknown-linux-gnu`
+- **Linux arm64:** vaihda tilalle `aarch64-unknown-linux-gnu`
+- **Windows:** lataa `iii-x86_64-pc-windows-msvc.zip` osoitteesta [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) ja pura `iii.exe` polkuun `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Joka arkistolla on vastaava `.sha256`-tiedosto julkaisusivulla; kun vaihdat alustaa, käytä kyseisen tiedoston tiivistettä yllä olevassa tarkistuksessa (Windowsilla: `Get-FileHash`). `npx @agentmemory/agentmemory`-komennon automaattinen asentaja kiinnittää näihin tiivisteisiin ja hylkää arkiston, joka ei täsmää.
+
+Tai käytä Dockeria (mukana tuleva `docker-compose.yml` hakee imagen `iiidev/iii:0.22.1`). Täysi dokumentaatio: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory toimii Windows 10/11:llä, mutta Node.js-paketti yksinään ei riitä; tarvitset myös kiinnitetyn iii-engine v0.22.1 -ajonaikaisen ympäristön taustaprosessina. CLI ei pura Windows-ZIP-pakettia automaattisesti, niin natiivien Windows-käyttäjien on asennettava `iii.exe` käsin, käytettävä WSL2:ta tai valittava Docker Desktop.
+
+Natiivi Windows-automaattinen MCP-kytkentä tukee vain komentoa `agentmemory connect copilot-cli`. Claude Codea, Codexia, Cursoria ja kaikkia muita natiiveja Windows-agentteja varten kopioi manuaalinen MCP-lohko kohdasta [Muut agentit](#other-agents) kyseisen agentin Windows-asetuksiin. `connect`-komennon ajaminen WSL:ssä on sopivaa vain, kun kohdeagentti on asennettu myös samaan WSL-ympäristöön; se ei muokkaa Windows-isännän agentin asetuksia.
+
+**Vaihtoehto A: valmiiksi käännetty Windows-binääri (suositeltu)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Vaihtoehto B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Vaihtoehto C: vain itsenäinen MCP (ei moottoria).** Jos tarvitset vain MCP-työkalut agentillesi ja et tarvitse REST-rajapintaa, katseluohjelmaa tai cron-tehtäviä, ohita moottori kokonaan:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostiikka Windowsilla:** jos `npx -y @agentmemory/agentmemory@latest` epäonnistuu, aja se uudelleen lipulla `--verbose` nähdäksesi moottorin todellisen stderr-tulosteen. Yleiset vikatilat:
+
+| Oire | Korjaus |
+|---|---|
+| `The engine process started but the REST API never responded.` | Vahvista, että kaikki neljä johdettua porttia ovat vapaat, varmista, että kiinnitetty `iii.exe` pysyi käynnissä, ja aja sitten uudelleen lipulla `--verbose` ja tarkista tallennettu moottorin stderr |
+| `Could not start iii-engine` | Ei `iii.exe`:tä eikä Dockeria ole asennettu. Katso Vaihtoehto A tai B yllä |
+| Porttiristiriita | `netstat -ano \| findstr :3111` nähdäksesi, mihin on sidottu, sammuta se tai käytä lippua `--port ` |
+| Docker-varajärjestelmä ohitetaan, vaikka Docker on asennettu | Varmista, että Docker Desktop on oikeasti käynnissä (järjestelmäpalkin kuvake) |
+
+> Huomio: iii-**moottori** on valmiiksi käännetty binääri, ei cargo-pakki, niin sitä ei kannata yrittää asentaa komennolla `cargo install`. (iii-**SDK:t** on julkaistu crates.io:ssa, npm:ssä ja PyPI:ssä, mutta agentmemory ei tarvitse niitä.) Tuetut moottorin asennustavat on kaikki kiinnitetty versioon v0.22.1: yllä oleva valmiiksi käännetty binääri, agentmemoryn macOS/Linux-automaattiasennusreitti (`curl`, POSIX `sh` ja `tar` vaadittu) ja Docker-image `iiidev/iii:0.22.1`. Paljas ylävirran `install.sh | sh` asentaa uusimman moottorin, jota agentmemory ei tue. Käytä komentoa `npx -y @agentmemory/agentmemory@latest`; macOS/Linuxilla se hakee kiinnitetyn moottorin polkuun `~/.agentmemory/bin`.
+
+---
+
+
Käyttöönotto
+
+Yhden klikkauksen mallipohjat hallinnoiduille isännille. Joka pohja toimittaa
+itsenäisen Dockerfile-tiedoston, joka hakee paketin `@agentmemory/agentmemory`
+npm:stä ja kopioi iii-moottorin binäärin viralliselta `iiidev/iii`-Docker Hub
+-imagelta; valmiiksi rakennettua agentmemory-imagea ei tarvita. Pysyvä tallennustila
+liitetään pisteeseen `/data`; ensimmäisen käynnistyksen entrypoint korvaa
+npm:n mukana tulevan iii-asetuksen (joka sitoutuu `127.0.0.1`-osoitteeseen) käyttöönottoa
+varten viritetyllä asetuksella, joka sitoutuu `0.0.0.0`-osoitteeseen ja käyttää absoluuttisia
+`/data`-polkuja, generoi HMAC-salaisuuden, ja luopuu sitten oikeuksista
+`root`-käyttäjästä `node`-käyttäjään `gosu`:n kautta ennen agentmemory-CLI:n exec-komentoa.
+
+
+
+
+
+
+Renderin yhden klikkauksen käyttöönottopainike vaatii `render.yaml`-tiedoston repositorion juuressa, jonka pidämme tarkoituksella siistinä. Käytä [`deploy/render/`](.././deploy/render/README.md)-kansiossa dokumentoitua Render Blueprint -virtaa osoittaaksesi repositorion sisäiseen blueprintiin käsin.
+
+Täydet asetustiedot (HMAC-tallennus, katseluohjelman SSH-tunneli, kierto, varmuuskopiointi,
+kustannuslattia) löytyvät kansiosta [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): yksi kone, asetuksella
+ `auto_stop_machines = "stop"`; halvin joutokäynnillä.
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby-tason kiinteä hinta,
+ volyymi kojelaudassa.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint-virta,
+ automaattiset levykuvat maksullisilla tasoilla.
+- [`deploy/coolify`](.././deploy/coolify/README.md): itseisännöity omalla
+ VPS:lläsi [Coolifyn](https://coolify.io/self-hosted) kautta; sama Docker
+ Compose -pino, omistat itse isännän ja datan.
+
+Vain portti `3111` julkaistaan. Katseluohjelma portissa `3113` pysyy sidottuna
+loopbackiin kontin sisällä; joka mallipohjan README dokumentoi
+SSH-tunnelimallin sen saavuttamiseksi.
+
+---
+
+
+
+Jokainen koodausagentti unohtaa kaiken, kun istunto päättyy, ja joka uusi istunto alkaa sinun selittäessä pinoasi uudelleen. agentmemory toimii taustalla ja poistaa tämän vaiheen.
+
+```text
+Session 1: "Add auth to the API"
+ Agent writes code, runs tests, fixes bugs
+ agentmemory silently captures every tool use
+ Session ends -> observations compressed into structured memory
+
+Session 2: "Now add rate limiting"
+ Agent already knows:
+ - Auth uses JWT middleware in src/middleware/auth.ts
+ - Tests in test/auth.test.ts cover token validation
+ - You chose jose over jsonwebtoken for Edge compatibility
+ Zero re-explaining. Starts working immediately.
+```
+
+### vs. sisäänrakennettu agenttimuisti
+
+Jokainen tekoälypohjainen koodausagentti toimitetaan sisäänrakennetulla muistilla: Claude Codella on `MEMORY.md`, Cursorilla on notepadit, Clinellä on memory bank. Nämä toimivat kuin tarralaput. agentmemory on hakukelpoinen tietokanta tarralappujen takana.
+
+| | Sisäänrakennettu (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skaala | 200 rivin katto | Rajattomasti |
+| Haku | Lataa kaiken kontekstiin | BM25 + vektori + graafi (vain top-K) |
+| Tokenkustannus | 22K+ 240 havainnolla | ~1 900 tokenia (92 % vähemmän) |
+| Agenttien välillä | Agenttikohtaiset tiedostot | MCP + REST (mikä tahansa agentti) |
+| Koordinointi | Ei mitään | Leaset, signaalit, toiminnot, rutiinit |
+| Havainnoitavuus | Lue tiedostoja käsin | Reaaliaikainen katseluohjelma portissa :3113 |
+
+---
+
+
+
+### Muistiputki
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-tasoinen muistin konsolidointi
+
+Mallinnettu sen mukaan, miten ihmisen aivot käsittelevät muistia, mukaan lukien unen aikainen konsolidointi.
+
+| Taso | Mitä | Analogia |
+|------|------|---------|
+| **Työ-** | Raa'at havainnot työkalujen käytöstä | Lyhytkestoinen muisti |
+| **Episodinen** | Pakatut istuntoyhteenvedot | "Mitä tapahtui" |
+| **Semanttinen** | Poimitut faktat ja mallit | "Mitä tiedän" |
+| **Proseduraalinen** | Työnkulut ja päätösmallit | "Miten se tehdään" |
+
+Muistot vanhenevat ajan myötä (Ebbinghausin käyrä). Usein käytetyt muistot vahvistuvat. Vanhentuneet muistot poistuvat automaattisesti. Ristiriidat havaitaan ja ratkaistaan.
+
+### Mitä tallennetaan
+
+| Hook | Tallentaa |
+|------|----------|
+| `SessionStart` | Projektin polku, istunnon ID |
+| `UserPromptSubmit` | Käyttäjän kehotteet (yksityisyyssuodatettu) |
+| `PreToolUse` | Tiedostonkäyttömallit + rikastettu konteksti |
+| `PostToolUse` | Työkalun nimi, syöte, tuloste |
+| `PostToolUseFailure` | Virhekonteksti |
+| `PreCompact` | Syöttää muistin uudelleen ennen tiivistämistä |
+| `SubagentStart/Stop` | Aliagentin elinkaari |
+| `Stop` | Istunnon loppuyhteenveto |
+| `SessionEnd` | Istunnon valmistumismerkki |
+
+### Keskeiset ominaisuudet
+
+| Ominaisuus | Kuvaus |
+|---|---|
+| **Automaattinen tallennus** | Joka työkalun käyttö tallennetaan hookien kautta, ei manuaalista työtä |
+| **Semanttinen haku** | BM25 + vektori + tietograafi RRF-fuusiolla |
+| **Muistin kehitys** | Versiointi, korvaaminen, suhdegraafit |
+| **Palautushygienia** | Korvatut muistiversiot poistuvat hakuindekseistä; versioketju KV:ssä säilyttää täyden historian |
+| **Läheisten kaksoiskappaleiden vihjeet** | Tallennukset ilmoittavat ohjeellisen `similarTo`-osuman, kun uusi sisältö muistuttaa läheisesti olemassa olevaa muistoa |
+| **Agenttikohtainen rajaus** | `agentId` kulkee tallennuksen ja palautuksen läpi REST:ssä, MCP:ssä ja hakuindeksissä, jaetussa tai eristetyssä tilassa |
+| **Kirjoitushetken alkuperä** | Joka havainto ja muisto kantaa muuttumattoman alkuperäkanavan (käyttäjä, agentti, työkalu, tuonti tai jaettu), leimattuna kaappauksen, tallennuksen ja tuonnin hetkellä |
+| **Automaattinen unohtaminen** | TTL-vanheneminen, ristiriitojen havaitseminen, tärkeyspohjainen poisto |
+| **Yksityisyys ensin** | API-avaimet, salaisuudet, ``-tagit riisutaan ennen tallennusta |
+| **Itseparantuminen** | Katkaisija, tarjoajan varaketju, terveyden valvonta |
+| **Claude-silta** | Kaksisuuntainen synkronointi MEMORY.md:n kanssa |
+| **Tietograafi** | Entiteettipoiminta + BFS-läpikäynti |
+| **Tiimimuisti** | Nimiavaruudella eroteltu jaettu + yksityinen tiimin jäsenten kesken |
+| **Viittausten jäljitettävyys** | Jäljitä mikä tahansa muisto takaisin lähdehavaintoihin |
+| **Git-tilannevedokset** | Versioi, palauta ja vertaile muistin tilaa |
+
+---
+
+
+
+Kolmoisvirtainen hakutoteutus, joka yhdistää kolme signaalia:
+
+| Virta | Mitä se tekee | Milloin |
+|---|---|---|
+| **BM25** | Sanavartaloitettu avainsanahaku synonyymilaajennuksella | Aina päällä |
+| **Vektori** | Kosinin samankaltaisuus tiheiden upotusten yli | Upotustarjoaja määritetty |
+| **Graafi** | Tietograafin läpikäynti entiteettivastaavuuden kautta | Kyselyssä havaittu entiteetit |
+
+Yhdistetty Reciprocal Rank Fusionilla (RRF, k=60) ja istuntokohtaisesti monipuolistettu (enintään 3 tulosta per istunto).
+
+Kun vektori-indeksi on täytetty, `mem::search` (`memory_recall`-työkalun takana) käyttää hybridiä BM25 + vektori -luokittelijaa. Ilman upotuksia se käyttää BM25:tä. `smart-search` voi lisäksi yhdistää rakenteellisia graafiosumia, kun graafidataa on olemassa, myös avaimettomassa tilassa. Opetusten palautus käyttää erillistä muistinvaraista BM25-indeksiä sen sijaan, että se skannaisi koko korpuksen jokaisella kyselyllä. Korvatut muistiversiot on suljettu pois jokaisesta palautusreitistä; versioketju säilyttää niiden historian.
+
+Vektorit selviävät kaatumisesta tai pakkosammutuksesta. Vektori-indeksi tallennetaan erissä enintään `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`-ajan välein (10 minuuttia). Joka vektori, joka lisätään tai poistetaan tällä välillä, kirjoitetaan myös heti pieneen odottavaan lokiin tilavarastossa, ja seuraava käynnistys toistaa sen kutsumatta upotustarjoajaa. Joka onnistunut tallennus tyhjentää lokin. Dokumentit, joilla ei vielä ole vektoria toiston jälkeen, upotetaan uudelleen taustalla erissä kooltaan `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), kunnes yhtäkään ei jää jäljelle, ja pysäytetty täydennys jatkuu seuraavassa käynnistyksessä. `/agentmemory/status` ja katseluohjelma näyttävät odottavan lokin koon ja täydennyksen tilan. Avaimettomat asennukset eivät kirjoita mitään.
+
+BM25 tokenisoi kreikan, kyrilliset kirjaimet, hebrean, arabian ja aksentoidun latinan oletuksena. Kiinan-, japanin- ja koreankielisiä muistoja varten asenna valinnaiset segmentoijat (`npm install @node-rs/jieba tiny-segmenter`) jakaaksesi CJK-jaksot sananlaajuisiksi tokeneiksi; ilman niitä agentmemory lankeaa pehmeästi koko jakson tokenisointiin ja tulostaa kertaluonteisen vihjeen stderriin.
+
+### Upotustarjoajat
+
+Avaimettomat asennukset poistavat vektoriupotukset käytöstä: `mem::search` käyttää BM25:tä, kun taas `smart-search` voi myös käyttää olemassa olevaa rakenteellista graafidataa. Saadaksesi käyttöön ilmaiset, laitteella toimivat semanttiset upotukset, lisää tämä tiedostoon `~/.agentmemory/.env` ja käynnistä agentmemory uudelleen:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Normaali npm-asennus sisältää valinnaisen `@huggingface/transformers`-ajonaikaisen ympäristön. Ensimmäinen upotuspyyntö lataa mallin `Xenova/all-MiniLM-L6-v2`, niin se vaatii verkkoyhteyden ja voi kestää pidempään; seuraava päättely toimii laitteella. Etätarjoajat tunnistetaan automaattisesti niiden avaimista, ellei `EMBEDDING_PROVIDER` ylikirjoita niitä.
+
+| Tarjoaja | Malli | Kustannus | Huomautuksia |
+|---|---|---|---|
+| **Paikallinen (suositeltu opt-in)** | `all-MiniLM-L6-v2` | Ilmainen | Laitteella ensimmäisen mallilatauksen jälkeen, +8pp palautustarkkuutta vain-BM25:een verrattuna |
+| Gemini | `gemini-embedding-001` | Ilmainen taso | 100+ kieltä, 768/1536/3072-ulotteinen (MRL), 2048-tokenin syöte. Korvaa `text-embedding-004`:n ([poistettu käytöstä, sammutetaan 14.1.2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | 0,02 $/1M | Korkein laatu |
+| Voyage AI | `voyage-code-3` | Maksullinen | Optimoitu koodille |
+| Cohere | `embed-english-v3.0` | Ilmainen kokeilu | Yleiskäyttöinen |
+| OpenRouter | Mikä tahansa malli | Vaihtelee | Multi-model-proxy |
+
+---
+
+
+
+54 työkalua, 6 resurssia, 3 kehotetta ja 17 taitoa.
+
+> **MCP-shim vs. täysi palvelin:** julkaistu `@agentmemory/mcp`-paketti on ohut shim. Se paljastaa täyden 54 työkalun pinnan **vain kun se tavoittaa käynnissä olevan agentmemory-palvelimen** `AGENTMEMORY_URL`:n kautta (proxy-tila). Kun palvelinta ei tavoiteta, shim palaa 7 työkalun paikalliseen settiin (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|all`-ympäristömuuttuja on *palvelinpuolen* lippu; sen asettaminen shimin `env`-lohkossa ei vaikuta mihinkään. Jos näet vain 7 työkalua Cursorissa / OpenCodessa / Gemini CLI:ssä, käynnistä `npx -y @agentmemory/agentmemory@latest` (tai Docker-pino) ja aseta `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 työkalua
+
+Kolme työkalupintaa, pienimmästä suurimpaan: `AGENTMEMORY_TOOLS=core` karsii näkyvyyden 8 olennaisimpaan (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); alla oleva perussetti on rekisterin 14 perustyökalua; oletus (`AGENTMEMORY_TOOLS=all`) paljastaa kaikki 54.
+
+
+Perustyökalut (14)
+
+| Työkalu | Kuvaus |
+|------|-------------|
+| `memory_recall` | Hae menneitä havaintoja |
+| `memory_compress_file` | Pakkaa markdown-tiedostoja säilyttäen rakenteen |
+| `memory_save` | Tallenna oivallus, päätös tai malli |
+| `memory_file_history` | Menneet havainnot tietyistä tiedostoista |
+| `memory_patterns` | Havaitse toistuvia malleja |
+| `memory_sessions` | Listaa viimeaikaiset istunnot |
+| `memory_smart_search` | Hybridi semanttinen + avainsanahaku |
+| `memory_vision_search` | Hae kuvahavainnoista |
+| `memory_timeline` | Kronologiset havainnot |
+| `memory_profile` | Projektiprofiili (käsitteet, tiedostot, mallit) |
+| `memory_export` | Vie kaikki muistidata |
+| `memory_relations` | Kysele suhdegraafia |
+| `memory_commit_lookup` | Git-commitin takana olevat istunnot |
+| `memory_commits` | Istunnolle tallennetut commitit |
+
+
+
+
+Laajennetut työkalut (yhteensä 54, oletuspinta)
+
+| Työkalu | Kuvaus |
+|------|-------------|
+| `memory_patterns` | Havaitse toistuvia malleja |
+| `memory_timeline` | Kronologiset havainnot |
+| `memory_relations` | Kysele suhdegraafia |
+| `memory_graph_query` | Tietograafin läpikäynti |
+| `memory_consolidate` | Aja 4-tasoinen konsolidointi |
+| `memory_claude_bridge_sync` | Synkronoi MEMORY.md:n kanssa |
+| `memory_team_share` | Jaa tiimin jäsenten kanssa |
+| `memory_team_feed` | Viimeaikaiset jaetut kohteet |
+| `memory_audit` | Toimintojen auditointijälki |
+| `memory_governance_delete` | Poista auditointijäljellä |
+| `memory_snapshot_create` | Git-versioitu tilannevedos |
+| `memory_action_create` | Luo työkohteita riippuvuuksilla |
+| `memory_action_update` | Päivitä toiminnon tila |
+| `memory_frontier` | Esteettömät toiminnot tärkeysjärjestyksessä |
+| `memory_next` | Yksittäinen tärkein seuraava toiminto |
+| `memory_lease` | Yksinoikeudelliset toimintoleaset (moniagenttisuus) |
+| `memory_routine_run` | Instansioi työnkulkurutiineja |
+| `memory_signal_send` | Agenttien välinen viestintä |
+| `memory_signal_read` | Lue viestit kuittauksilla |
+| `memory_checkpoint` | Ulkoiset ehtoportit |
+| `memory_mesh_sync` | P2P-synkronointi instanssien välillä |
+| `memory_sentinel_create` | Tapahtumaohjatut vartijat |
+| `memory_sentinel_trigger` | Laukaise vartijat ulkoisesti |
+| `memory_sketch_create` | Lyhytikäiset toimintagraafit |
+| `memory_sketch_promote` | Korota pysyväksi |
+| `memory_crystallize` | Tiivistä toimintoketjut |
+| `memory_diagnose` | Terveystarkistukset |
+| `memory_heal` | Korjaa jumittunut tila automaattisesti |
+| `memory_facet_tag` | Ulottuvuus:arvo-tagit |
+| `memory_facet_query` | Kysely facet-tageilla |
+| `memory_verify` | Jäljitä alkuperä |
+
+
+
+### 6 resurssia · 3 kehotetta · 17 taitoa
+
+| Tyyppi | Nimi | Kuvaus |
+|------|------|-------------|
+| Resurssi | `agentmemory://status` | Terveys, istuntomäärä, muistomäärä |
+| Resurssi | `agentmemory://project/{name}/profile` | Projektikohtainen tieto |
+| Resurssi | `agentmemory://project/{name}/recent` | Projektin viimeaikaiset havainnot |
+| Resurssi | `agentmemory://memories/latest` | 10 viimeisintä aktiivista muistoa |
+| Resurssi | `agentmemory://graph/stats` | Tietograafin tilastot |
+| Resurssi | `agentmemory://team/{id}/profile` | Jaettu tiimiprofiili |
+| Kehote | `recall_context` | Hae + palauta kontekstiviestit |
+| Kehote | `session_handoff` | Luovutustieto agenttien välillä |
+| Kehote | `detect_patterns` | Analysoi toistuvia malleja |
+| Taito | `/recall` | Hae muistista |
+| Taito | `/remember` | Tallenna pitkäkestoiseen muistiin |
+| Taito | `/session-history` | Viimeaikaiset istuntoyhteenvedot |
+| Taito | `/forget` | Poista havaintoja/istuntoja |
+
+Taulukko näyttää neljä ydintaitoa. Täysi setti on 9 kutsuttavaa taitoa plus 8 viitetaitoa; katso Natiivit taidot -osio yllä.
+
+### Itsenäinen MCP
+
+Aja ilman täyttä palvelinta, mille tahansa MCP-asiakkaalle. Kumpi tahansa näistä toimii:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Tai lisää agenttisi MCP-asetuksiin:
+
+Useimmat agentit (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Yhdistä `agentmemory`-merkintä isäntäsi olemassa olevaan `mcpServers`-objektiin sen sijaan, että korvaisit tiedoston. Hiekkalaatikoiduille asiakkaille, jotka eivät tavoita isännän `localhost`-osoitetta, lisää `"AGENTMEMORY_FORCE_PROXY": "1"` env-lohkoon ja aseta `AGENTMEMORY_URL` reitille, jonka hiekkalaatikko tavoittaa.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Kopioi plugin-tiedosto repositoriosta:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Käynnistyy automaattisesti portissa `3113`. Katseluohjelma lataa yhden tilannevedoksen yhdistyessään (`GET /agentmemory/viewer/snapshot`) ja soveltaa sitten live-streamitapahtumia: uudet muistot, opetukset, havainnot, auditointimerkinnät, graafimuutokset ja terveyspäivitykset ilmestyvät ilman pollausta tai sivun uudelleenlatausta. Ainoat muut pyynnöt ovat toiminnot, joita klikkaat, "lataa lisää" -sivut ja haut. Kun stream katkeaa, katseluohjelma näyttää, kuinka vanhoja sen luvut ovat, yhdistää uudelleen takaisinvedolla ja synkronoi uudelleen yhdestä tilannevedoksesta.
+
+- **12 välilehteä neljässä ryhmässä** live-laskureilla, syvälinkeillä (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), pikanäppäimillä ja mobiilivalikolla.
+- **Muistot:** palvelinpuolen haku, suodattimet projektin, agentin ja tyypin mukaan, yksityiskohtapaneeli versioketjulla ja sanadiffillä, alkuperälinkit, kopiointipainikkeet id:lle, MCP-kutsulle ja curl-komennolle, muokkaus (uusi versio), unohtaminen vahvistuksella, joukkounohtaminen ja JSON-vienti.
+- **Istunnot:** sisäänrakennettu havaintoaikajana luettavalla työkalusyötteellä ja -tulosteella, suodattimet ja sivutus, sekä muistot ja opetukset, jotka joka istunto tuotti.
+- **Graafi:** haku, solmun yksityiskohdat suhteilla ja lähteillä, selite, joka ei nojaa vain väriin, ja zoom-säätimet.
+- **Terveys:** `GET /agentmemory/status`:n live-versio. Joka ongelman mukana tulee sen korjaus, plus tilan taustaosa, indeksin tallennustila, graafin alkuperän tiivistämisen edistyminen ja konsolidointiselitys todellisilla kynnysarvoilla.
+- **Auditointi, Toiminta, Profiili, Toisto, Opetukset, Toiminnot ja Kristallit** -sivut, joilla kaikilla on tyhjä tila, joka kertoo, mikä osio on, miksi se on tyhjä ja mikä komento täyttää sen, sekä `?`-sanastovihje joka termille ja luvulle.
+
+```bash
+open http://localhost:3113
+```
+
+Katseluohjelman palvelin sitoutuu oletuksena osoitteeseen `127.0.0.1` ja liittää palvelimen salaisuuden välittäessään pyyntöjä REST-rajapinnalle, niin se ei vaadi asetuksia. REST-rajapinnan tarjoama `/agentmemory/viewer`-päätepiste noudattaa normaaleja bearer-tokenisääntöjä ja ohjaa selaimet, joilla ei ole tokenia, katseluohjelman porttiin. CSP-otsikot käyttävät vastauskohtaista script-noncea ja poistavat käytöstä inline-käsittelijäattribuutit (`script-src-attr 'none'`).
+
+---
+
+
+
+Katseluohjelma portissa `:3113` näyttää, mitä agenttisi **muisti**. [iii-konsoli](https://iii.dev/docs/console) näyttää, mitä agenttisi **teki**: joka muistioperaatio OpenTelemetry-jäljityksenä, joka KV-merkintä muokattavana, joka funktio kutsuttavana, joka stream napautettavana. Kaksi ikkunaa samaan muistiin: yksi tuoteksikin, yksi moottoriksikin muotoiltu.
+
+Katso `memory_smart_search`-kutsun laukeavan ja näe BM25-skannaus → upotushaku → RRF-fuusio → uudelleenluokittelu vesiputousnäkymänä. Muokkaa jumittunutta konsolidointiajastinta KV-selaimessa. Toista `PostToolUse`-hook muokatulla hyötykuormalla. Pinnaa WebSocket-stream ja katso havaintojen saapuvan live.
+
+agentmemory toimittaa tämän ilmaiseksi, koska joka funktiokutsu ja triggeri laukeaa iii:n läpi; ei mitään mukautettua, ei mitään instrumentoitavaa.
+
+
+
+
+ Workers-sivu: joka yhdistetty worker, mukaan lukien agentmemory itse, PID:llä, funktiomäärällä, ajonaikaisella ympäristöllä ja viimeisimmällä näkymisajalla.
+
+
+**Jo asennettu.** Konsoli toimitetaan kiinnitetyn `iii`-moottorin (0.22+) mukana; ei mitään erillistä asennettavaa. Ensimmäinen käynnistys lataa konsolin binäärin moottorin viereen.
+
+**Käynnistä agentmemoryn rinnalla:**
+
+```bash
+agentmemory console
+```
+
+Tämä ajaa kiinnitetyn moottorin `iii console`-komennon porteja vastaan, jotka agentmemory ratkaisi (REST, streamit, silta), ja tarjoilee sen yhden portin katseluohjelman yläpuolella, oletuksena `http://localhost:3114`. `--console-port N` valitsee toisen portin; `--port` ja `--instance` valitsevat agentmemory-instanssin samalla tavalla kuin `stop`-komennolle; mikä tahansa muu lippu välitetään läpi, esimerkiksi `--enable-flow` kokeelliselle arkkitehtuurigraafi-sivulle.
+
+Sama asia käsin, hyödyllinen kun `agentmemory` ei ole PATH:ssa:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Mitä voit tehdä konsolista:**
+
+| Sivu | Käytä tätä |
+|------|-----------|
+| **Workers** | Näe joka yhdistetty worker ja sen live-mittarit, mukaan lukien agentmemory-worker itse. |
+| **Functions** | Kutsu mitä tahansa agentmemoryn funktiota suoraan JSON-hyötykuormalla; kätevä testaamaan `memory.recall`, `memory.consolidate`, `graph.query` kytkemättä asiakasta. |
+| **Triggers** | Toista HTTP-, cron-, tapahtuma- ja tilatriggereitä: laukaise konsolidointi-cron käsin, yritä HTTP-reittiä uudelleen, lähetä tilamuutos. |
+| **States** | KV-selain täydellä CRUD:lla istuntoihin, muistipaikkoihin, elinkaariajastimiin ja upotusindeksiin; muokkaa arvoja paikan päällä. |
+| **Streams** | Live-WebSocket-monitori muistikirjoituksille, hook-tapahtumille ja havaintopäivityksille niiden virratessa iii-streamien läpi. |
+| **Queues** | Pysyvät jono-aiheet + dead-letter-hallinta. Toista tai hylkää epäonnistuneet upotus-/pakkaustehtävät. |
+| **Traces** | OpenTelemetry-vesiputous-/liekki-/palvelujaotellut näkymät. Suodata `trace_id`:llä nähdäksesi tarkalleen, mitkä funktiot, tietokantakutsut ja upotuspyynnöt yksi `memory.search` tuotti. |
+| **Logs** | Rakenteelliset OTEL-lokit suodatettuna ja korreloituna trace-/span-ID:ihin. |
+| **Config** | Ajonaikainen konfiguraatio: näe tarkalleen, millä workereilla, tarjoajilla ja porteilla moottorisi käy. |
+| **Flow** | (Valinnainen, `--enable-flow`) Interaktiivinen arkkitehtuurigraafi joka workerista, triggeristä ja streamista. |
+
+
+
+
+ Traces: vesiputous-/liekki-/palvelujaottelu joka muistioperaatiolle.
+
+
+**Jäljitykset ovat jo päällä:**
+
+`iii-config.yaml` toimitetaan `iii-observability`-worker käytössä (`exporter: memory`, `sampling_ratio: 0.1`, metriikat + lokit). Ei mitään lisäasetuksia tarvita; sillä hetkellä, kun agentmemory käynnistyy, joka muistioperaatio lähettää rakenteellisen lokin, jonka konsoli voi lukea, ja yksi kymmenestä niistä (`sampling_ratio: 0.1`) lähettää myös trace-spanin.
+
+Jos haluat viedä datan Jaegeriin/Honeycombiin/Grafana Tempoon sen sijaan, vaihda `exporter: memory` arvoon `exporter: otlp` ja aseta kerääjän päätepiste iii:n observability-dokumentaation mukaan.
+
+> **Huomio:** konsolissa itsessään ei ole pakotettua autentikointia; pidä se sidottuna osoitteeseen `127.0.0.1` (oletus) ja älä koskaan paljasta sitä julkisesti.
+
+---
+
+
+
+agentmemory on **jo käynnissä oleva [iii](https://iii.dev)-instanssi**. Kolme primitiiviä (worker, funktio, triggeri) muodostavat ajonaikaisen ympäristön; KV-tila, streamit ja OTEL-jäljitykset tulevat iii-state-, iii-stream- ja iii-observability-workereilta, jotka toimitetaan iii:n mukana. Et asentanut Postgresia, Redistä, Expressiä, pm2:ta tai Prometheusta, koska iii korvaa ne.
+
+Se tarkoittaa, että yksi komento lisää laajentaa agentmemoryn kokonaan uudella kyvykkyydellä.
+
+### Laajenna agentmemorya lisäworkereilla
+
+Sisäänrakennetut workerit, joita agentmemory tarvitsee, ovat jo tiedostossa `iii-config.yaml` ja käynnistyvät sen mukana: `iii-state` (KV), `iii-queue` (pysyvät uudelleenyritykset tapahtumatilaajille), `iii-pubsub`, `iii-cron`, `iii-stream` ja `iii-observability` (OTEL-jäljitykset, metriikat ja lokit joka funktiolle). Kaikki muu [iii-workerrekisteristä](https://workers.iii.dev) kytkeytyy samaan moottoriin: kopioi `iii-config.yaml` tiedostoon `~/.agentmemory/iii-config.yaml` (CLI suosii tätä tiedostoa mukana tulevan sijaan ja renderöi siihen edelleen portit ja datapolut), lisää merkintä, asenna workerin ajonaikainen ympäristö kerran komennolla `~/.agentmemory/bin/iii update worker`, ja käynnistä agentmemory uudelleen.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Mitä saat agentmemoryn päälle |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-pohjainen tila-adapteri, kun kasvat ulos muistinvaraisista KV-oletuksista |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`:sta tullut koodi ajetaan kertakäyttöisessä VM:ssä, ei shellissäsi |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Pystytä lisää MCP-palvelimia agentmemoryn rinnalle, jaa sama moottori |
+
+Moottorin 0.22.x-versiossa pidä `iii-`-etuliitteelliset nimet yllä olevilla sisäänrakennetuilla; etuliitteettömät `http`-, `state`-, `queue`-, `pubsub`- ja `cron`-merkinnät ovat itsenäisen rekisterin workerit, joihin agentmemory siirtyy 0.23-migraation mukana.
+
+Täysi rekisteri: [workers.iii.dev](https://workers.iii.dev). Joka worker sillä sivulla muodostuu samoista primitiiveistä, joita agentmemory käyttää, ja agentmemory, joka sinulla on jo, on yksi niistä.
+
+### Moottorin asetukset ja sidontaosoite
+
+`agentmemory start` lukee moottorin asetukset ensimmäisestä tiedostosta, joka on olemassa: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` nykyisessä hakemistossa, `~/.agentmemory/iii-config.yaml`, sitten mukana tuleva `iii-config.yaml`. Joka käynnistyksellä se renderöi kyseisen tiedoston (datapolut, portit, tilan taustaosa) tiedostoon `~/.agentmemory/data/iii-config.runtime.yaml` ja käynnistää moottorin renderöidyllä kopiolla, niin muokkaa lähdetiedostoa, ei renderöityä. Lähdetiedoston `host:`-arvot säilytetään kirjoitetussa muodossa.
+
+Mukana tuleva `iii-config.yaml` sitoutuu tarkoituksella osoitteeseen `127.0.0.1`, ja tämä oletus pätee myös kontin sisällä. Kontissa käynnistetty CLI kuuntelee kontin loopbackia, niin julkaistut portit eivät tavoita mitään. Tarjoillaksesi konteriutuneen CLI:n julkaistujen porttien kautta, aseta `AGENTMEMORY_III_CONFIG` osoittamaan asetukseen, joka sitoutuu osoitteeseen `0.0.0.0`. Pakattu `iii-config.docker.yaml` on yksi tällainen: se sitoo `iii-http`:n, `iii-stream`:n ja moottorin portin osoitteeseen `0.0.0.0` ja tallentaa tilan polkuun `/data`, niin liitä kirjoitettava volyymi siihen. Pidä `AGENTMEMORY_SECRET` asetettuna, ja julkaise vain tarvitsemasi portit, osoitteessa `127.0.0.1` tai luotettavan proxyn takana.
+
+Tämän repositorion `docker-compose.yml` ei kulje CLI:n asetushaun läpi: se liittää `iii-config.docker.yaml`:n pisteeseen `/app/config.yaml`, ja `iii-engine`-kontti käynnistyy lipulla `--config /app/config.yaml`. Yhden klikkauksen [käyttöönottomallipohjat](../deploy/) kirjoittavat omat `0.0.0.0`-asetuksensa niiden entrypointeihin.
+
+### Tallennuksen taustaosa: file (oletus) vs. redis
+
+`iii-state` ja `iii-stream` käyttävät oletuksena iii-moottorin mukana tulevaa tiedostopohjaista KV-varastoa: yksi JSON-tiedosto per scope, pidettynä moottoriprosessin muistissa ja uudelleenkirjoitettuna levylle ajastimella. Se on oikea oletus yhden käyttäjän paikalliselle asennukselle; jaettu daemon, jossa on useita samanaikaisia kirjoittajia, saa oikeat avainkohtaiset kirjoitukset Redisiltä sen sijaan, verkkokierroksen hinnalla per operaatio (joka `state::*`-kutsu sarjallistuu edelleen yhdelle Redis-yhteydelle, niin tämä vaihtaa tiedostovaraston lukituksen soklaan, ei rinnakkaisuuteen).
+
+Aseta `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) vaihtaaksesi molemmat workerit iii-moottorin sisäänrakennettuun `redis`-adapteriin, joka tallentaa joka avaimen Redis-hash-kenttänä (`HSET`) sen sijaan, että uudelleenkirjoittaisi koko scopen jokaisella kirjoituksella:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` on oletuksena `file`; sen asettamatta jättäminen pitää tämänpäiväisen käytöksen muuttumattomana, ja tunnistamaton arvo (mikä tahansa muu kuin `file` tai `redis`) on käynnistysvirhe, ei hiljainen varajärjestelmä. `/agentmemory/status` ja katseluohjelman Health-sivu (State store -rivi) ilmoittavat, mikä taustaosa on aktiivinen ja vastaako se, ei koskaan URL-osoitetta.
+
+**Vain pelkkä `redis://`.** Kiinnitetty moottori (0.22.1) rakentaa Redis-asiakkaansa ilman TLS-tukea, niin `rediss://`-URL (useimmat hallitut Redis-tarjoomat, kuten Upstash, Redis Cloud ja ElastiCache siirron aikaisella salauksella, ovat oletuksena vain-TLS) ei muodosta yhteyttä. Yhteys on salaamaton, niin Redis-salasana ja joka tallennettu muisto kulkevat langalla selkokielisenä: osoita paikalliseen Redisiin tai luotettavassa yksityisessä verkossa olevaan. Mille tahansa muulle Redisille, aja salattu tunneli (stunnel, SSH tai VPN) agentmemory-isännällä, niin pelkkä `redis://`-hyppy pysyy kyseisellä isännällä ja tunnelin ylävirran yhteys on salattu ja todennettu. Jos Redis-salasana sisältää heittomerkin, prosenttikoodaa se (`%27`); moottori laajentaa URL:n YAML-asetukseksi ennen jäsentämistä.
+
+**Yksi Redis-palvelin per `--instance`.** Moottorin Redis-avainetuliitteet (`state:`, `stream::`) on kiinnitetty, niin kaksi agentmemory-instanssia (`--instance 1`, `--instance 2`, ...) osoitettuna samaan tietokantaan ylikirjoittavat toistensa datan. Erillinen tietokantaindeksi (`redis://localhost:6379/1`) pitää tallennetun datan erillään, mutta moottori välittää live-katseluohjelman tapahtumat yhden Redis-pub/sub-kanavan (`stream::events`) yli, ja Redis-pub/sub ohittaa tietokantaindeksin, niin joka instanssin katseluohjelma näyttäisi edelleen toisen live-tapahtumat. Anna joka instanssille omansa Redis-palvelin (tai portti), kun ajat useampaa kuin yhtä.
+
+**Mikä pysyy samana, ja mikä eroaa.** Joka agentmemory-ominaisuus toimii Redisillä: istunnot, havainnot, muistot (muista, korvaa, kehitä, unohda), haku ja indeksierät, opetukset, graafi, auditointiloki ja sen kuukausittaiset scopet, vienti ja tuonti, hallintapoistot, konsolidoinnin tila, katseluohjelman tilannevedos ja sen live-stream, ja terveysmonitori. Moottori tallentaa joka scopen yhtenä Redis-hashina (`HSET`/`HGET`/`HGETALL`) ja laukaisee samat tilatriggerit kuin tiedostovarasto. Kolme moottorieroa käsitellään agentmemoryn sisällä:
+
+- Redis palauttaa scopen tietueet ei-kiinnitetyssä järjestyksessä. agentmemory lajittelee ne vanhimmasta alkaen (tietueen ID:ssä olevan luomisajan, sitten sen aikaleiman mukaan), niin listat, sivutus ja vientierät palautuvat samassa järjestyksessä kuin tiedostovarastolla.
+- Moottori soveltaa osittaisia päivityksiä Redisillä Lua-skriptissä, joka muuttaa tyhjät taulukot tyhjiksi objekteiksi. agentmemory soveltaa näitä päivityksiä itse (lue, muuta, kirjoita avainkohtaisen lukon alla) Redisillä, niin kentät kuten `tags: []` pysyvät taulukkoina.
+- Vanhentunut auditointilokitarkistus lukee vanhan scopen Redisistä sen sijaan, että etsisi tiedostovaraston tiedostoa levyltä.
+
+Yksi ero vaatii sinulta toimia: **Redis-uudelleenkäynnistyksen jälkeen moottori lakkaa välittämästä live-tapahtumia** katseluohjelmalle, kunnes agentmemory käynnistyy uudelleen. Data tallennetaan ja luetaan yhä normaalisti. Terveysmonitori lähettää testitapahtuman Redisin läpi 30 sekunnin välein; kun se ei palaa, `/agentmemory/status` ja katseluohjelman Health-sivu näyttävät "Live updates are not reaching the viewer" korjauksen kanssa: käynnistä agentmemory uudelleen. Jos Redis on alhaalla, tilaraportti näyttää "The state store is not answering" ja kuinka tarkistaa se (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Erittäin suuren scopen listaaminen lukee koko hashin yhdellä `HGETALL`:lla, samalla kustannuksella kuin tiedostovaraston pitäminen muistissa.
+
+**Suositellut Redis-asetukset.** Oletusarvoinen `save 3600 1 300 100 60 10000` -tilannevedospolitiikka voi menettää minuutteja kirjoituksia kaatumisessa, pahemmin kuin tiedostovaraston 5s flush-ikkuna. Aseta `appendonly yes` kaikelle, mistä välittäisit, jos menettäisit sen. Aseta `maxmemory-policy noeviction`; `allkeys-lru` tai vastaava pudottaa hiljaa muistoja, kun Redis osuu muistirajaansa.
+
+Natiivi (ei-Docker) käynnistys, ja joka yhden klikkauksen [käyttöönottomallipohja](../deploy/) (ne ylikirjoittavat mukana tulevan `iii-config.yaml`:n ja käynnistyvät natiivisti), lukevat `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` ja renderöivät ne käynnistettyyn `iii-config`:iin. URL itsessään ei koskaan kirjoiteta tähän renderöityyn tiedostoon, vain `${AGENTMEMORY_REDIS_URL}`-viittaus, jonka moottoriprosessi laajentaa omasta ympäristöstään käynnistyshetkellä. Vain tämän repositorion oma Docker Compose -reitti (`AGENTMEMORY_USE_DOCKER=1`, tai sillä tavalla aiemmin käynnistetyn moottorin jatkaminen) liittää `iii-config.docker.yaml`:n kirjoitussuojattuna ja ei koskaan renderöi; `agentmemory start` varoittaa, kun se havaitsee tämän yhdistelmän. Vaihda tämä tiedosto käsin, seuraten samaa `name: redis` / `config: redis_url: ...` -muotoa, joka näkyy [iii-state](https://workers.iii.dev/workers/iii-state)- ja [iii-stream](https://workers.iii.dev/workers/iii-stream)-workereiden dokumentaatiossa, ja osoita `redis_url` kontista tavoitettavaan Redisiin. `docker-compose.yml` välittää `AGENTMEMORY_REDIS_URL`:n moottorikonttiin, niin `redis_url: '${AGENTMEMORY_REDIS_URL}'` toimii siellä ja pitää URL:n pois liitetystä tiedostosta.
+
+Renderöity asetus pitää URL:n pois tiedostosta `~/.agentmemory/data/iii-config.runtime.yaml`, mutta moottorin oma konfiguraatioworker tallentaa yhä *laajennetun* arvon pysyvästi tiedostoihin `~/.agentmemory/config/iii-state.yaml` ja `iii-stream.yaml`, kun se käynnistyy (iii-moottorin `${VAR}`-laajennus tapahtuu ennen kuin tämä worker tallentaa siemenensä, ja se tallentaa ratkaistun arvon, ei viittausta). Kohtele tätä hakemistoa tunnuksena: `chmod 700 ~/.agentmemory` millä tahansa jaetulla isännällä, ja suosi Redis-ACL-käyttäjää, joka on rajattu siihen, mitä agentmemory tarvitsee, tietokannan admin-tunnusten sijaan.
+
+**Migraatio ei ole automaattinen.** `AGENTMEMORY_STATE_BACKEND`:n vaihtaminen aloittaa tyhjästä varastosta molemmilla puolilla; mikään ei kopioi olemassa olevaa dataa tiedostosta Redisiin tai takaisin. Vie data taustaosasta, jota jätät, ja tuo siihen, jota siirryt käyttämään. Tämä toimii identtisesti bashissa ja zshissä (mukaan lukien `bash -u`). Taulukko kuten `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` ei toimi: zsh pitää otsikon yhtenä virheellisenä sanana, kun bash jakaa sen kahdeksi, niin molemmat pyynnöt saavat 401-vastauksen aina kun `AGENTMEMORY_SECRET` on asetettu:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` hyväksyy myös `?maxSessions=`- ja `?offset=`-parametrit suuren korpuksen paloittelemiseksi useiden kutsujen yli; `strategy` tuonnissa on `merge` (oletusturvallinen), `replace` tai `skip`.
+
+### Mitä iii korvaa
+
+| Perinteinen pino | agentmemory käyttää |
+|---|---|
+| Express.js / Fastify | iii HTTP-triggerit |
+| SQLite / Postgres + pgvector | iii KV-tila + muistinvarainen vektori-indeksi |
+| SSE / Socket.io | iii-streamit (WebSocket) |
+| pm2 / systemd | iii-moottorin workerien valvonta |
+| Prometheus / Grafana | iii OTEL + terveysmonitori |
+| Mukautetut plugin-järjestelmät | `iii worker add ` |
+
+**225 lähdetiedostoa · ~54,000 LOC · 2,600+ testiä · 312 funktiota · 66 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
+
+---
+
+
+
+### LLM-tarjoajat
+
+agentmemory tunnistaa tarjoajat automaattisesti ympäristöstäsi. Tarjoaja tekee LLM-pohjaiset operaatiot käytettäväksi, mutta tarjoajan asettaminen yksinään ei ota käyttöön LLM:n kirjoittamaa havaintojen pakkausta. Tämä reitti vaatii molemmat: tarjoajan ja `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Tarjoaja | Asetus | Huomautuksia |
+|----------|--------|-------|
+| **No-op (oletus)** | Ei asetuksia tarvita | LLM-pohjainen pakkaus/yhteenveto on pois käytöstä. Synteettinen pakkaus ja BM25-palautus toimivat yhä. Katso `AGENTMEMORY_ALLOW_AGENT_SDK` alla, jos luotit aiemmin Claude-tilauksen varajärjestelmään. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Per-token-laskutus |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-yhteensopiva |
+| Gemini | `GEMINI_API_KEY` | Ottaa myös upotukset käyttöön |
+| OpenRouter | `OPENROUTER_API_KEY` | Mikä tahansa malli |
+| OpenAI API | `OPENAI_API_KEY` | Oletus `gpt-5.6-luna`, ylikirjoita `OPENAI_MODEL`:lla |
+| **Paikallinen (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) tai `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Mikä tahansa OpenAI-API-yhteensopiva. Nolla kustannuksia, toimii omalla laitteistollasi. Katso [Paikalliset mallit](#local-models-ollama--lm-studio--vllm) alla. |
+| Claude-tilauksen varajärjestelmä | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Vain opt-in. Käynnistää `@anthropic-ai/claude-agent-sdk`-istuntoja; se aiheutti aiemmin rajoittamattoman Stop-hook-rekursion, niin se ei ole enää oletus. |
+
+### Paikalliset mallit (Ollama / LM Studio / vLLM)
+
+agentmemory puhuu minkä tahansa OpenAI-API-yhteensopivan palvelimen kanssa, niin kaikki, mikä paljastaa `/v1/chat/completions`-päätepisteen, toimii ilman koodimuutoksia. Ei maksullisia avaimia, ei pilveä, ei nopeusrajoituksia; toimii kokonaan laitteistollasi.
+
+**Ollama** (oletusportti `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (oletusportti `1234`):
+
+Avaa LM Studio → Local Server -välilehti → Start Server. Valitse mikä tahansa keskustelumalli valitsimesta (Qwen 3, gpt-oss, DeepSeek R1, jne.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: samanlainen muoto. Osoita `OPENAI_BASE_URL` mihin tahansa URL-osoitteeseen, jonka palvelimesi paljastaa, ja aseta `OPENAI_MODEL` nimeksi, jonka palvelimesi hyväksyy.
+
+**Mallivalinnat muistityöhön**: pakkaus ja yhteenveto ovat lyhyitä tehtäviä (<2K tokenia sisään, <500 tokenia ulos), joissa 7B-ohjeistusmalli on enemmän kuin tarpeeksi. Suositukset:
+
+| Malli | Koko | Miksi |
+|-------|------|-----|
+| `qwen3:8b` | ~5,2 GB | Tasapainoinen oletus 16 GB:n koneella; vahva poiminnassa ja työkalumuotoisessa tekstissä |
+| `qwen3:4b` | ~2,6 GB | Pienin järkevä vaihtoehto; sopii pakkaukseen, heikompi graafipoiminnassa |
+| `qwen3-coder:30b` | ~19 GB | Paras paikallinen valinta koodimuotoisille istunnoille (30B MoE, 3,3B aktiivista) 24–32 GB:n laitteistolla |
+| `gpt-oss:20b` | ~14 GB | Vahva yleismalli, mahtuu 16 GB RAM:iin |
+| `deepseek-r1:8b` | ~5,2 GB | Päättelytislattu; hitaampi mutta puhtaammat poiminnat |
+
+Qwen 3 -mallit ajattelevat oletuksena ja voivat polttaa koko tokenbudjetin päättelyyn ennen tulostetta. Aseta `AGENTMEMORY_LLM_NOTHINK=1` liittääksesi `/no_think`-lisäyksen graafipoimintakehotteisiin, ja nosta `MAX_TOKENS`-arvoa (16384 toimii), jos poiminnat palaavat tyhjinä.
+
+Päättelyluokan mallit (`o1`-tyyliset ``-lohkoilla) voivat palauttaa tyhjän `content`-kentän `reasoning`-kentällä, jota paikallinen palvelimesi ei välttämättä paljasta. Jos poiminnat palaavat tyhjinä, vaihda ensin ei-päättelevään malliin. `OPENAI_REASONING_EFFORT=none`-ympäristömuuttuja voi myös poistaa ajattelun käytöstä Ollama Cloudin ajattelevissa malleissa, jotka peilaavat OpenAI:n reasoning-skeemaa.
+
+Paikalliset upotukset toimitetaan valinnaisena riippuvuutena, mutta ne eivät ole käytössä oletuksena. Aseta `EMBEDDING_PROVIDER=local` ottaaksesi käyttöön `Xenova/all-MiniLM-L6-v2` (384-ulotteinen). Ensimmäinen upotuspyyntö lataa mallin; päättely tapahtuu sen jälkeen laitteella. Ilman tätä asetusta tai etäupotusavainta vektorit pysyvät pois käytöstä, `mem::search` käyttää BM25:tä, ja `smart-search` voi yhä lisätä olemassa olevia graafiosumia.
+
+### Kustannustietoinen mallin valinta
+
+Kun LLM:n kirjoittama taustapakkaus on otettu käyttöön molemmilla, tarjoajalla ja `AGENTMEMORY_AUTO_COMPRESS=true`, se ajetaan joka havainnolle, niin mallinvalinta muuttaa kuukausikuluja merkittävästi. Tallennettu työkuormadata: 635 pyyntöä / 888K tokenia / 35 tuntia aktiivista käyttöä, ajettuna kolmea OpenRouter-mallia vastaan 2026-05-23-hinnoittelulla.
+
+| Taso | Malli | Syöte / 1M | Tuloste / 1M | Kustannus tallennetulle 35h:lle | Huomautuksia |
+|------|-------|------------|-------------|---------------------------|-------|
+| Suositeltu | `deepseek/deepseek-v4-flash-0731` | 0,07 $ | 0,14 $ | ~0,07 $ (arvio) | Uusin DeepSeek; halvin suositeltu valinta pakkaustyökuormille. |
+| Suositeltu | `deepseek/deepseek-v4-pro` | 0,435 $ | 0,87 $ | ~0,46 $ | Vahva pakkaus- ja yhteenvetolaatu ~10x alemmilla kustannuksilla kuin Sonnet. |
+| Suositeltu | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Vahva koodipäättely, jos istuntosi ovat voimakkaasti koodimuotoisia. |
+| Premium | `anthropic/claude-sonnet-5` | 3,00 $ | 15,00 $ | ~5,02 $ (arvio) | Sama listahinta kuin mitattu Sonnet 4.6 -ajo; 2 $/10 $ -esittelyhinnoittelu 31.8.2026 asti. |
+| Premium | `openai/gpt-5.6-sol` | 5,00 $ | 30,00 $ | ~9 $ (arvio) | Lippulaivataso; kallis jatkuvasti päällä olevalle taustatyölle. |
+| Vältä | `anthropic/claude-opus-5` | 5,00 $ | 25,00 $ | ~8,40 $ (arvio) | Lippulaivaluokan malli; ylikulutus pakkaukseen. |
+
+Mitatut rivit tulevat tallennetusta ajosta; (arvio)-rivit skaalaavat samaa tokensekoitusta joka mallin listahinnalla.
+
+agentmemory tulostaa ajonaikaisen varoituksen, kun `OPENROUTER_MODEL` täsmää premium-tason malliin. Aseta `AGENTMEMORY_SUPPRESS_COST_WARNING=1` hiljentääksesi sen, kun olet tehnyt tietoisen valinnan.
+
+Laadun vs. kustannuksen kompromissi muistityöhön: pakkaus on yhteenvetotehtävä, jossa on suhteellisen väljät laatuvaatimukset (agentti lukee yhteenvedon uudelleen, ei käyttäjä). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder jäävät pyöristysvirheen sisään Sonnetista tässä tehtävässä kustantaen 10–70x vähemmän. Säästä premium-tason mallit kyselyihin, jotka luet suoraan.
+
+Lähteet: [OpenRouter-hinnoittelu Claude Sonnet 5:lle](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeekin hinnoitteluhuomautukset](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Moniagenttinen muisti (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Moniagenttisissa asetuksissa, joissa useat roolit jakavat yhden agentmemory-palvelimen (arkkitehti / kehittäjä / arvioija / tutkija / tukiagentti), `AGENT_ID` tagittaa joka kirjoituksen roolilla, joka sen teki. `AGENTMEMORY_AGENT_SCOPE` hallitsee, suodattaako palautus tämän tagin mukaan.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Kaksi tilaa:
+
+| Tila | Tagittaa kirjoitukset | Suodattaa palautuksen | Milloin käyttää |
+|------|------------|---------------|-------------|
+| `shared` (oletus) | kyllä | ei | Agenttien välinen konteksti auditointijäljellä. Arkkitehti voi nähdä, mitä kehittäjä merkitsi, mutta joka rivi tallentaa, kuka sanoi sen. |
+| `isolated` | kyllä | kyllä | Tiukka erottelu. Arkkitehti ei koskaan näe kehittäjän havaintoja / muistoja / istuntoja. |
+
+Mitä tagitetaan, kun `AGENT_ID` on asetettu: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rooli kulkee ketjua `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Mitä suodatetaan isolated-tilassa: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Joka päätepiste hyväksyy `?agentId=` ylikirjoittaakseen per pyyntö, ja `?agentId=*` poistuakseen env-rajauksesta kokonaan. `/memories` hyväksyy myös `?includeOrphans=true` tuodakseen esiin ennen-AGENT_ID-muistot, joiden `agentId` on määrittelemätön.
+
+Per-kutsu-ylikirjoitus SDK-/REST-tasolla: joka muuttava päätepiste (`/session/start`, `/remember`) hyväksyy `agentId`-kentän pyynnön rungossa, joka voittaa env-arvon. Hyödyllinen ajonaikaisille ympäristöille, jotka reitittävät monta roolia yhden palvelinprosessin läpi. MCP:n `memory_save`-työkalu paljastaa saman `agentId`-kentän, itsenäinen stdio-palvelin välittää molemmat, `agentId`:n ja `project`:n, ja tallennetut muistot kuljettavat `agentId`:n hakuindeksiin, niin agenttirajattu haku kattaa myös muistot, ei vain havainnot.
+
+Kun `AGENT_ID` on asettamatta, muisti pysyy rajaamattomana (vanha käytös, ei tageja, ei suodattimia).
+
+### Portit
+
+agentmemory + iii-engine sitovat neljä porttia oletuksena. Jos uudelleenkäynnistys epäonnistuu virheellä `port in use`, tämä taulukko kertoo, mitä prosessia etsiä.
+
+| Portti | Prosessi | Tarkoitus | Env-ylikirjoitus |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST-rajapinta + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Sisäinen streams-worker (agentmemoryn + katseluohjelman kuluttama) | `III_STREAM_PORT` (suositeltu) tai vanha `III_STREAMS_PORT` |
+| `3113` | agentmemory | Reaaliaikainen katseluohjelma (`http://localhost:3113`) | `III_VIEWER_PORT` tai `AGENTMEMORY_VIEWER_URL` ilmoitetulle URL-osoitteelle |
+| `49134` | iii-engine | WebSocket; workerit rekisteröityvät tähän, OTel-telemetria kulkee sen yli | `III_ENGINE_PORT` tai `III_ENGINE_URL` |
+
+`--port ` muuttaa REST-ankkurin ja johtaa streamit `N+1`, katseluohjelman `N+2` ja moottorin WebSocketin `N+46023`, vain siltä osin kuin vastaava eksplisiittinen portti tai URL yllä on asettamatta. Se ei luo eristettyä elinkaarinimiavaruutta. Käytä `--instance 1` toiselle daemonille; se käyttää ankkuria 3211, oletuksena `3211/3212/3213/49234`, ja saa erillisen `instance-1`-data- ja elinkaarihakemiston. Instanssit 1–50 noudattavat samaa mallia.
+
+Kiinnitetty moottori käynnistyy lipulla `--no-update-check` (ei päivitys- tai turvallisuusneuvontahakuja GitHubista käynnistyksessä) ja iii:n anonyymi käyttötelemetria pois päältä: agentmemory asettaa `III_TELEMETRY_ENABLED=false` moottorille, jonka se käynnistää, ellet itse vie muuttujaa, ja mukana tuleva compose-tiedosto tekee samoin.
+
+Vanhentuneiden prosessien siivous, kun portit pysyvät sidottuina kaatuneen ajon jälkeen:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` kerää siististi sekä workerin että moottorin pidfile:n normaalissa natiivissa sammutuksessa. Docker-tilassa se huuhtelee natiivin workerin, pysäyttää tarkan validoidun moottorikontin, ja säilyttää molemmat, kontin ja sen `/data`-liitoksen, häviöttömälle uudelleenkäynnistykselle. Seuraava käynnistys validoi ja jatkaa samaa konttia. Docker-pohjainen poisto vaatii `agentmemory remove --keep-data`-komennon: se poistaa jaetut agentmemory-hallinnoimat tiedostot säilyttäen validoidun kontin, sen datan liitoksen ja elinkaaritietueen, jota tarvitaan niiden palauttamiseen. Tuhoisa Docker-datan poisto on tarkoituksella jätetty operaattorille varmuuskopion jälkeen. CLI myös kieltäytyy ottamasta haltuun tai signaalittamasta Docker- tai VM-porttien haltijoita (Docker-backend, vpnkit, colima) natiivina moottorina, ellei `--force`-lippua anneta. Yllä oleva manuaalinen siivous on vain kaatumisen jälkeiselle tapaukselle, jossa kumpaakaan pidfileä ei jäänyt.
+
+### Asetustiedosto
+
+Laita agentmemoryn ajonaikaiset asetukset tiedostoon `~/.agentmemory/.env` sen sijaan, että vietäisit muuttujia joka shellissä. Jos katseluohjelma näyttää asetusvihjeen kuten `export ANTHROPIC_API_KEY=...`, kopioi se tähän tiedostoon muodossa `ANTHROPIC_API_KEY=...` ilman `export`-etuliitettä, ja käynnistä sitten agentmemory uudelleen.
+
+Prosessin ympäristömuuttujat toimivat yhä ja voittavat tiedoston arvot.
+
+Windowsilla sama tiedosto sijaitsee polussa `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Testataksesi Claude Code Pro-/Max-tilauksella API-avaimen sijaan, liity mukaan nimenomaisesti:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM:n kirjoittama havaintojen pakkaus vaatii molemmat rivit: pääsyn LLM-tarjoajaan (mukaan lukien tämä nimenomainen tilauksen varajärjestelmä) ja `AGENTMEMORY_AUTO_COMPRESS=true`. Tarjoaja yksinään jättää oletusarvoisen synteettisen pakkausreitin paikalleen.
+
+Konsolidointi (graafisolmut, opetukset, kristallit) on oletuksena päällä aina, kun LLM-tarjoaja on määritetty. Poistu siitä nimenomaisesti asetuksella `CONSOLIDATION_ENABLED=false`, jos haluat LLM-vapaan toiminnan. Graafipoiminta on erillinen lippu:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Ympäristömuuttujat
+
+Luo `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpointia portissa `3111`. REST-rajapinta sitoutuu oletuksena osoitteeseen `127.0.0.1`. Suojatut endpointit vaativat `Authorization: Bearer `, ja mesh-synkronointiendpointit vaativat nimenomaisesti asetetun `AGENTMEMORY_SECRET`-arvon molemmilla vertaisilla.
+
+**Autentikointi on oletuksena päällä.** Kun `AGENTMEMORY_SECRET` ei ole asetettu (shellissä tai tiedostossa `~/.agentmemory/.env`), palvelin generoi satunnaisen salaisuuden ensimmäisellä käynnistyksellä ja tallentaa sen polkuun `~/.agentmemory/secret` oikeuksilla `0600`. Joka mukana tuleva asiakas lukee sen sieltä puhuessaan paikalliselle palvelimelle: CLI, katseluohjelma, hookit kansiossa `plugin/scripts`, MCP-palvelin ja `@agentmemory/mcp`-shim, `agentmemory connect`-komennon kirjoittamat asetukset, ja mukana tulevat OpenCode-, Pi-, OpenClaw-, Hermes- ja tiedostojärjestelmän tarkkailijaintegraatiot. Tallennettu salaisuus lähetetään vain loopback-URL-osoitteisiin (`localhost`, `127.0.0.0/8`, `::1`). Nimenomainen `AGENTMEMORY_SECRET` voittaa aina, ja etäasiakkaat tarvitsevat sen yhä asetettuna. Docker ja `deploy/`-entrypointit generoivat ja vievät jo omansa. Kutsuaksesi rajapintaa käsin:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Kirjoitusten pyyntösäännöt.** `POST`-, `PUT`-, `PATCH`- ja `DELETE`-pyyntöjen REST-rajapinnalle ja katseluohjelmalle on lähetettävä `Content-Type: application/json` (`charset`-parametri on OK) aina, kun niillä on runko, ja `Origin`-otsikon, kun se on läsnä, on oltava loopback-alkuperä määritetylle REST- tai katseluohjelmaportille tai listattu `VIEWER_ALLOWED_ORIGINS`-muuttujassa (pilkulla eroteltu, esim. `https://memory.example.com`). Asiakkaat, jotka eivät lähetä `Origin`-otsikkoa (CLI, hookit, MCP, curl, palvelin-palvelin-liikenne), eivät kärsi tästä. Katseluohjelma hyväksyy myös oman alkuperänsä.
+
+**Tiedostopolut.** Päätepisteet, jotka lukevat tai kirjoittavat tiedostoja (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), hyväksyvät vain polkuja hakemiston `~/.agentmemory`, instanssin datahakemiston tai `AGENTMEMORY_IMPORT_ROOT`-muuttujassa listatun hakemiston alla (erota useampi `:`-merkillä, tai `;`-merkillä Windowsilla). `/replay/import-jsonl` hyväksyy myös oletuksensa `~/.claude/projects`. `/obsidian/export` pysyy hakemiston `AGENTMEMORY_EXPORT_ROOT` sisällä ja `/migrate` hakemiston `~/.agentmemory` sisällä. Symbolilinkit ratkaistaan ennen joka tarkistusta.
+
+**Salaisuuksien siistiminen.** API-avaimet, bearer-tokenit, PEM-yksityisavainlohkot ja URL-osoitteisiin upotetut tunnukset (`scheme://user:password@host`) peitetään ennen tekstin tallentamista, joka kirjoitusreitillä: havainnot, remember, evolve, slotit, opetukset, toiminnot, sketchit, signaalit, checkpointit, tuonnit, jsonl-toisto, mesh-synkronointi, tiimijaot, pakkaus- ja yhteenvetotuloste, kristallit ja graafisolmut.
+
+
+Keskeiset endpointit
+
+| Metodi | Polku | Kuvaus |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Terveystarkistus (aina julkinen) |
+| `GET` | `/agentmemory/status` | Mikä on vialla ja miten se korjataan (HTML selaimille, muuten JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Kaikki, mitä katseluohjelma näyttää, yhdessä vastauksessa |
+| `POST` | `/agentmemory/session/start` | Aloita istunto + hae konteksti |
+| `POST` | `/agentmemory/session/end` | Päätä istunto |
+| `POST` | `/agentmemory/observe` | Tallenna havainto (katso tallennuksen toimitus alla) |
+| `GET` | `/agentmemory/capture` | Tallennuksen saapuvat, dead letterit ja offline-spool |
+| `POST` | `/agentmemory/capture/retry` | Yritä dead-letter-tallennuksia uudelleen |
+| `POST` | `/agentmemory/capture/drain` | Lähetä paikallinen offline-spool nyt |
+| `POST` | `/agentmemory/smart-search` | Hybridihaku |
+| `POST` | `/agentmemory/context` | Generoi konteksti |
+| `POST` | `/agentmemory/remember` | Tallenna pitkäkestoiseen muistiin |
+| `POST` | `/agentmemory/forget` | Poista havaintoja |
+| `POST` | `/agentmemory/enrich` | Tiedostokonteksti + muistot + bugit |
+| `GET` | `/agentmemory/profile` | Projektiprofiili |
+| `GET` | `/agentmemory/export` | Vie kaikki data |
+| `POST` | `/agentmemory/import` | Tuo JSON:sta |
+| `POST` | `/agentmemory/graph/query` | Tietograafikysely |
+| `POST` | `/agentmemory/graph/compact` | Tiivistä ylisuuri graafin alkuperä |
+| `POST` | `/agentmemory/team/share` | Jaa tiimin kanssa |
+| `GET` | `/agentmemory/audit` | Auditointijälki |
+
+Täysi endpoint-lista: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Tallennuksen toimitus.** Hookit lähettävät joka havainnon kerran osoitteeseen `POST /agentmemory/observe` `eventId`:n kanssa. Se on isännän oma ID kutsulle, kun hyötykuormalla on sellainen (esimerkiksi Claude Coden `tool_use_id`), muuten tiiviste istunnosta, hook-tyypistä, työkalun nimestä, syötteestä, tulosteesta ja isännän aikaleimasta. Palvelin kirjoittaa tapahtuman tallennuksen saapuviin tilavarastossa, tallentaa havainnon, ja poistaa sitten saapuva-merkinnän. Tilakoodi kertoo, mitä tapahtui:
+
+| Tila | `status`-kenttä | Merkitys |
+|---|---|---|
+| `201` | `accepted` | Tallennettu. `observationId` on uusi havainto. |
+| `202` | `accepted` (`state: "retrying"`) | Hyväksytty, mutta tallentaminen epäonnistui. Palvelin yrittää sitä uudelleen, myös uudelleenkäynnistyksen jälkeen. |
+| `200` | `duplicate` | Tämä `eventId` on jo hyväksytty. `observationId` on olemassa oleva havainto; mitään uutta ei tallenneta. |
+| `400` / `422` | `rejected` | Virheellinen hyötykuorma, tai tallentaminen epäonnistui pysyvästi (tapahtuma säilytetään dead letterina). |
+| `503` | `rejected` (`retryable: true`) | Saapuvat on täynnä (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hookit spoolaavat tapahtuman ja lähettävät sen myöhemmin. |
+
+Epäonnistuneita tapahtumia yritetään uudelleen `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`-välein (10 s) kaksinkertaistuvalla takaisinvedolla, enintään `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`-kertaa (5). Tapahtumat, jotka epäonnistuvat yhä, jäävät saapuviin dead lettereina, listataan `/agentmemory/status`:ssa ja katseluohjelman Health-sivulla, ja niitä voi yrittää uudelleen komennolla `POST /agentmemory/capture/retry` (`{"eventId": "..."}` tai `{"all": true}`). Hyväksytyt tapahtuma-ID:t muistetaan `AGENTMEMORY_CAPTURE_DEDUP_HOURS`-ajan (168 tuntia, enintään `AGENTMEMORY_CAPTURE_EVENTS_MAX` ID:tä), niin aikakatkaisun tai uudelleenkäynnistyksen jälkeen toistettu hook tallennetaan kerran, kun taas kaksi erillistä työkalukutsua omilla isäntä-ID:illään tallennetaan kahdesti, vaikka niiden sisältö olisi identtinen. Kun havainto poistetaan (unohda, istunnon poisto, häädetty, automaattisesti unohdettu tai tuonti, joka korvaa varaston), sen tapahtuma merkitään poistetuksi ennen havainnon poistamista, niin kyseisen tapahtuman toisto samalla ikkunalla vastataan kaksoiskappaleena eikä mitään tallenneta. Tilavarasto kirjoittaa levylle 2 sekunnin välein, niin vastattu tapahtuma voi yhä olla vain muistissa hetken. Kattaakseen tämän, joka `2xx`-vastaus kantaa myös palvelimen `bootId`:n (uusi joka käynnistyksellä), `acceptedAt`:n ja `durableAfterMs`:n (tallennusväli plus 1,5 s tiedostovarastolla, 1,5 s redisillä, jossa pysyvyys on operaattorin asetus). Hookit pitävät tapahtuman paikallisessa spoolissa, kunnes tämä ikkuna on kulunut, ja poistavat sen myöhemmällä kutsulla ilman toista pyyntöä. Jos `bootId` on sillä välin muuttunut, palvelin käynnistyi uudelleen, niin hook lähettää tapahtuman uudelleen samalla `eventId`:llä; tapahtuma, joka todella saapui levylle, ei tallenneta kahdesti. Palvelin myös lähettää tällaisia tapahtumia itse käynnistyksessä ja joka uudelleenyrityksen välein, niin uudelleenkäynnistys ei menetä mitään, vaikka mikään hook ei ajaisi sen jälkeen. Vanhemmat hookit ohittavat ylimääräiset kentät, ja uudet hookit vanhempaa palvelinta vastaan hylkäävät tapahtuman `2xx`:llä kuten ennen.
+
+Kun palvelin on alhaalla, ei vastaa ajoissa tai palauttaa 5xx:n, hook liittää havainnon paikalliseen spool-tiedostoon, `/capture-spool/-.jsonl` (ylikirjoita kansio `AGENTMEMORY_CAPTURE_SPOOL_DIR`:llä). Tiedosto on yksityinen käyttäjällesi (oikeudet 600), salaisuudet peitetään samalla tavalla kuin palvelin peittää ne, se pitää enintään `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) ja pudottaa merkinnät, jotka ovat vanhempia kuin `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Kun se on täynnä, uudet merkinnät pudotetaan ja lasketaan, ja `/agentmemory/status` raportoi sen. Hook poistuu yhä koodilla 0 aikarajansa sisällä ja lisää ei yhtään pyyntöä, kun palvelin on terve. Spool lähetetään seuraavassa käynnistyksessä ja ensimmäisellä hookilla, joka tavoittaa palvelimen uudelleen, taustaprosessissa, niin agentti ei odota. Tapahtuma-ID:t tekevät tämän turvalliseksi: havainto, joka saapui ennen aikakatkaisua, ei tallenneta kahdesti. `npx @agentmemory/agentmemory capture` näyttää spoolin ja palvelimen saapuvat, `--drain` lähettää spoolin nyt, ja `GET /agentmemory/capture` palauttaa saman JSON:na. Aseta `AGENTMEMORY_CAPTURE_SPOOL=false` kytkeäksesi spoolin pois.
+
+**Graafin alkuperän tiivistäminen.** Joka tietograafin solmu ja reuna pitää 32 uusimman havainnon ID:t, joista se tuli. Varastot, jotka kirjoitettiin ennen tätä kattoa, voivat pitää tuhansia ID:itä per kuuma solmu, mikä tekee graafihausta ja katseluohjelmasta hitaan tai kaataa workerin. agentmemory korjaa tämän itse: ensimmäisellä käynnistyksellä päivityksen jälkeen se tiivistää joka solmun, reunan, korvatun reunan (temporaalinen graafihistoria) ja välimuistitetun tilannevedoksen kattoon taustalla, pienissä viipaleissa tauolla niiden välissä, niin haku, tallennus ja katseluohjelma pysyvät toiminnassa. Se tallentaa edistymisensä, jatkaa uudelleenkäynnistyksen jälkeen ja ei koskaan aja uudelleen, kun se on valmistunut. `/agentmemory/status` ja katseluohjelman Health-sivu näyttävät sen odottavana, käynnissä (nykyisellä scopella ja sijainnilla), valmiina tai epäonnistuneena. Aseta `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` kytkeäksesi sen pois.
+
+Ajaaksesi sen käsin, kutsu `POST /agentmemory/graph/compact`. Se kävelee nimi- ja reuna-avainindeksit sen sijaan, että listaisi joka solmun ja reunan, ja sen voi turvallisesti ajaa uudelleen. Kun se tiivistää ID:itä, se kirjoittaa `graph_compact`-auditointimerkinnän.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Suurella varastolla, tai kun kutsu palauttaa 504:n, aja se viipaleissa. Lähetä `scope` (`nodes`, `edges` tai `history`), `offset` ja `limit`, ja kutsu sitten uudelleen palautetulla `nextOffset`:lla, kunnes se on `null`. Tee tämä `nodes`:lle, `edges`:lle ja `history`:lle, ja lopeta yhdellä `{"scope":"snapshot"}`-kutsulla, koska viipaloitu ajo ei koske välimuistitettua tilannevedosta.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Edellytykset:** Node.js >= 20 npm/npx:llä; [iii-engine](https://iii.dev/docs) v0.22.1 tai Docker. macOS/Linux-automaattinen moottorin asennus vaatii myös `curl`:n, POSIX-yhteensopivan `sh`:n ja `tar`:n; natiivi Windows käyttää manuaalista kiinnitettyä `iii.exe`:tä, WSL2:ta tai Docker Desktopia.
+
+
Votre agent de codage se souvient de tout. Fini de tout réexpliquer.
- Built on iii engine
+ Construit sur iii engine
- Mémoire persistante pour Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode et tout client MCP.
+ Mémoire persistante pour Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode et tout client MCP.
@@ -73,23 +94,35 @@
---
-## Install
+## Installation
-Une seule commande :
+Prérequis :
+
+- Node.js 20 ou plus récent avec npm et npx (`node -v`, `npm -v` et `npx -v`).
+- L'installation automatique de iii-engine sur macOS/Linux nécessite aussi `curl`, un `sh` POSIX et `tar`. Les images minimales comme `node:20-slim` peuvent ne pas les inclure.
+- Windows natif requiert l'installation manuelle de l'`iii.exe` épinglé à la version iii-engine v0.22.1. WSL2 ou Docker Desktop sont les autres chemins pris en charge.
+
+Commande canonique d'installation initiale :
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-La première exécution est un setup interactif : choisissez les agents à câbler (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), choisissez un fournisseur LLM ou restez sans clé, et il amorce la config, démarre le serveur de mémoire sur `:3111` et propose une installation globale pour que la simple commande `agentmemory` fonctionne ensuite partout.
+La première exécution est un setup interactif : choisissez les agents à câbler (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), choisissez un fournisseur LLM ou restez sans clé, et il amorce la config, démarre le serveur de mémoire ainsi que son moteur iii épinglé, et propose une installation globale pour que la simple commande `agentmemory` fonctionne ensuite partout. `-y` accepte l'invite de paquet de npx et `@latest` évite une version mise en cache obsolète. Un fournisseur rend les fonctionnalités LLM disponibles, mais la compression d'observation rédigée par LLM ne démarre que lorsque `AGENTMEMORY_AUTO_COMPRESS=true` est aussi défini.
+
+Le mode sans clé désactive les embeddings vectoriels. `memory_recall` (le chemin `mem::search`) utilise BM25, tandis que `memory_smart_search` peut aussi fusionner des correspondances de graphe structurel quand des données de graphe existent déjà. Pour un recall sémantique gratuit sur l'appareil, définissez `EMBEDDING_PROVIDER=local` dans `~/.agentmemory/.env` et redémarrez. La première requête d'embedding télécharge `Xenova/all-MiniLM-L6-v2` ; l'inférence tourne ensuite localement après ce téléchargement initial du modèle.
-Puis prouvez que le recall fonctionne et donnez ses skills à votre agent :
+Le runtime local utilise quatre ports : `3111` pour REST/MCP HTTP, `3112` pour les streams iii, `3113` pour le visualiseur et `49134` pour le WebSocket du worker iii. L'état persistant iii vit dans `~/Library/Application Support/agentmemory` sur macOS, `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` sur Linux, et `%APPDATA%\agentmemory` sur Windows. Utilisez `--data-dir ` ou `AGENTMEMORY_DATA_DIR` pour le remplacer, et réutilisez la même valeur à chaque redémarrage. Pour la compatibilité ascendante, un `./data/state_store.db` ou `./data/iii-config.yaml` existant prime sur le défaut de la plateforme pour l'instance 0 ; un flag ou une variable d'environnement explicite l'emporte toujours.
+
+Prouvez ensuite que le recall fonctionne et donnez ses skills à votre agent :
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
+Les recherches par mot-clé devraient trouver des résultats en mode sans clé par défaut via BM25. La requête `database performance optimization` de la démo est volontairement sémantique et peut renvoyer zéro résultat jusqu'à ce qu'un fournisseur d'embedding soit configuré.
+
Vous préférez laisser un agent de codage tout faire ? Confiez-lui une seule instruction :
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
@@ -99,7 +132,7 @@ Câblez d'autres agents à tout moment avec `agentmemory connect ` — 20
Windows
-Le chemin rapide est WSL2. La configuration native du moteur sous Windows est manuelle (environ 10 à 20 minutes) et `agentmemory connect` n'y est pas pris en charge pour l'instant. Voir les [notes Windows](#windows) pour le pas-à-pas.
+Le chemin le plus rapide est WSL2. La configuration native du moteur sous Windows nécessite de télécharger le ZIP v0.22.1 épinglé et d'extraire `iii.exe` manuellement ; la CLI ne l'extrait pas automatiquement. Docker Desktop est aussi pris en charge. Voir les [notes Windows](#windows) pour le pas-à-pas.
@@ -107,11 +140,11 @@ Le chemin rapide est WSL2. La configuration native du moteur sous Windows est ma
Installation globale / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+La commande npx ci-dessus reste le chemin canonique d'installation initiale et évite les problèmes de permission liés au préfixe global.
+
@@ -124,7 +157,7 @@ npx met en cache par version. Forcez la dernière avec `npx -y @agentmemory/agen
Vous faites déjà tourner votre propre moteur iii
-agentmemory épingle iii-engine v0.11.2 et ne s'attachera pas à une autre version (le worker ne peut pas parler le protocole d'un autre moteur). Arrêtez l'autre moteur, puis lancez `npx -y @agentmemory/agentmemory@latest`. Il installe et exécute le v0.11.2 épinglé dans `~/.agentmemory/bin`, sans toucher à votre propre `iii`.
+agentmemory épingle iii-engine v0.22.1 et ne s'attachera pas à une autre version (le worker ne peut pas parler le protocole d'un autre moteur). Arrêtez l'autre moteur, puis lancez `npx -y @agentmemory/agentmemory@latest`. Il installe et exécute le v0.22.1 épinglé dans `~/.agentmemory/bin`, sans toucher à votre propre `iii`.
@@ -136,88 +169,139 @@ agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'A
-
-
+
+ Claude Code plugin natif + 12 hooks + MCP
-
+
Codex CLI plugin natif + 6 hooks + MCP
-
+
+
+GitHub Copilot CLI
+MCP + hooks/skills du plugin
+
+
+
+Cursor
+plugin natif + 7 hooks + MCP
+
+
+
+OpenCode
+plugin de capture + MCP
+
+
+
+
+
+Devin
+6 hooks + skills + MCP
+
+
OpenClaw plugin natif + MCP
-
+
Hermes plugin natif + MCP
-
+
pi plugin natif + MCP
-
-
+
+ OpenHuman
-backend natif trait Memory
-
-
-
-Cursor
-serveur MCP
+backend natif via le trait Memory
-
+
+
+
Gemini CLI serveur MCP
+
+
+Antigravity
+MCP + hooks
+
+
+
+Claude Desktop
+serveur MCP
+
+
+
+Warp
+connect + MCP + skills
+
+
+
+Zed
+serveur MCP
+
-
-
-OpenCode
-22 hooks + MCP + plugin
-
-
+
Cline serveur MCP
-
-
-Goose
+
+
+Continue serveur MCP
-
-
-Kilo Code
+
+
+Droid serveur MCP
-
-
-Aider
-API REST
+
+
+Kiro
+serveur MCP
-
-
-Claude Desktop
+
+
+Qwen Code serveur MCP
-
-
-Devin
-6 hooks + MCP
+
+
+
+
+DeepSeek Harness
+serveur MCP
-
+
Roo Code serveur MCP
+
+
+Kilo Code
+serveur MCP
+
+
+
+Goose
+serveur MCP
+
+
+
+Aider
+API REST
+
@@ -227,15 +311,24 @@ agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'A
---
-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.
+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. Fonctionne 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, sans réexplication ni copier-coller.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **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).
+Par défaut, agentmemory stocke l'état iii-engine hors du dépôt depuis lequel vous le lancez : `~/Library/Application Support/agentmemory` sur macOS, `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` sur Linux, et `%APPDATA%\agentmemory` sur Windows. Un `./data/state_store.db` ou `./data/iii-config.yaml` legacy existant est réutilisé pour l'instance 0 avant ce défaut de plateforme. Pour choisir un emplacement explicitement, passez `--data-dir ` ou définissez `AGENTMEMORY_DATA_DIR` ; l'un ou l'autre réglage explicite prime sur la découverte legacy :
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Les lancements natifs et Docker utilisent ce même répertoire hôte résolu ; Docker le bind-mount sur `/data`. `--instance 1` ajoute `instance-1` au répertoire résolu et sélectionne le quartet de ports par défaut séparé `3211/3212/3213/49234`.
+
+Notes de la dernière version : [CHANGELOG.md](../CHANGELOG.md).
---
@@ -254,7 +347,7 @@ npx @agentmemory/agentmemory
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| Référence grep | 0.227 | 0.967 | 15 / 15 | 0 ms |
-100 % de taux de hit top-5 au **plafond mathématique du P@5** pour ce corpus (0.240, voir le scorecard). L'hybride récupère chaque session gold ; grep manque 1 des 2 gold sur la requête temporelle multi-session. Le gain porte sur **recall + temporel**, pas sur la précision agrégée. Ce benchmark est petit et pauvre en gold ; le LongMemEval-S plus grand ci-dessous différencie mieux. Ventilation complète par type + note de correction : [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+100% de taux de hit top-5 au **plafond mathématique du P@5** pour ce corpus (0.240, voir le scorecard). L'hybride récupère chaque session gold ; grep manque 1 des 2 gold sur la requête temporelle multi-session. Le gain porte sur **recall + temporel**, pas sur la précision agrégée. Ce benchmark est petit et pauvre en gold ; le LongMemEval-S plus grand ci-dessous différencie mieux. Ventilation complète par type + note de correction : [`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)
@@ -279,11 +372,11 @@ npx @agentmemory/agentmemory
-> 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) couvrant agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+> Modèle d'embedding : `all-MiniLM-L6-v2` (local, gratuit, sans 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) couvrant agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
-**Reproduire localement :** [`eval/README.md`](../eval/README.md), un 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/).
+**Reproduire localement :** [`eval/README.md`](../eval/README.md), un harnais à adaptateurs pluggables pour LongMemEval `_s` (public, 500 questions) + `coding-agent-life-v1` (corpus interne de 15 sessions). Les adaptateurs grep / vectoriel / agentmemory sont noté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).
+**À 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 plus larges sur docs / PDF / images / vidéos. agentmemory mémorise le travail ; ces trois projets éclairent le reste de la couche de contexte. Recettes + tableau de routage des questions : [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
@@ -333,7 +426,7 @@ npx @agentmemory/agentmemory
-Note benchmark : seul le R@5 d'agentmemory est notre propre résultat mesuré (LongMemEval-S, reproductible depuis benchmark/COMPARISON.md). Les chiffres mem0 et Letta sont leurs résultats LoCoMo publiés (un dataset différent) ; les chiffres MemPalace, supermemory, TencentDB (PersonaMem) et oracleagentmemory sont des affirmations auto-déclarées des éditeurs que nous n'avons pas reproduites indépendamment (le run d'oracleagentmemory utilisait GPT-5.5 contre une Oracle AI Database). Présentés côte à côte à titre indicatif seulement, pas comme un face-à-face sur données identiques. Les nombres d'étoiles sont approximatifs et dérivent avec le temps.
+Note sur le benchmark : seul le R@5 d'agentmemory est notre propre résultat mesuré (LongMemEval-S, reproductible depuis benchmark/COMPARISON.md). Les chiffres de mem0 et Letta sont leurs résultats LoCoMo publiés (un jeu de données différent) ; les chiffres de MemPalace, supermemory, TencentDB (PersonaMem) et oracleagentmemory sont des annonces auto-déclarées par ces éditeurs, que nous n'avons pas reproduites indépendamment (le run d'oracleagentmemory utilisait GPT-5.5 contre une Oracle AI Database). Présentés côte à côte à titre indicatif seulement, pas comme un comparatif direct sur des données identiques. Les comptages d'étoiles sont approximatifs et évoluent avec le temps.
-**Nouveaux entrants** à connaître, comparés en profondeur dans [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) :
+**Nouveaux arrivants** à connaître, comparés en détail dans [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) :
| Système | ⭐ | Angle |
|--------|---|-------|
-| Zep / Graphiti | 30K | Graphe de connaissances temporel ; meilleurs résultats publiés sur les requêtes temporelles (LongMemEval 63.8%), mais le graphe se construit de façon asynchrone donc les faits frais peuvent traîner |
+| Zep / Graphiti | 30K | Graphe de connaissances temporel ; meilleurs résultats publiés sur les requêtes temporelles (LongMemEval 63.8%), mais le graphe se construit de façon asynchrone donc les faits récents peuvent accuser un retard |
| Cognee | 30K | Ingestion document-vers-graphe-de-connaissances, Python uniquement, conçu pour l'extraction d'entités structurées plutôt que pour la capture de sessions |
-Aucun d'eux ne capture automatiquement depuis les hooks d'agents de codage, ne livre un visualiseur local-first, ni ne tourne sans clé — la combinaison autour de laquelle agentmemory est construit.
+Aucun d'entre eux ne capture automatiquement depuis des hooks d'agent de codage, ne fournit de visualiseur local-first, ni ne fonctionne sans clé — la combinaison autour de laquelle agentmemory est construit.
---
-Compatibilité : cette version cible `iii-sdk` stable `^0.11.0` et iii-engine v0.11.x.
+Compatibilité : cette version cible `iii-sdk` 0.22.1 et épingle iii-engine v0.22.1.
-### Essayez en 30 secondes
+### Essayez-le en 30 secondes
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` amorce 3 sessions réalistes (authentification JWT, correction de requête N+1, limitation de débit) et exécute des recherches contre elles. Les installations sans clé désactivent les vecteurs, donc les requêtes par mot-clé `mem::search` devraient trouver des résultats via BM25 tandis que `database performance optimization` peut renvoyer zéro résultat. `smart-search` peut en plus renvoyer des correspondances de graphe structurel quand des données de graphe existent. Pour que la requête sémantique trouve la correction N+1 via les vecteurs, définissez `EMBEDDING_PROVIDER=local`, redémarrez, et laissez le premier téléchargement de modèle se terminer.
+
+Ouvrez `http://localhost:3113` pour regarder la mémoire se construire en direct.
+
+### Valider une installation fraîche et la persistance au redémarrage
+
+Avec le serveur en cours d'exécution, validez REST, la santé, le visualiseur et le statut du runtime adossé à iii :
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
```
-`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 », ce dont la correspondance par mots-clés est incapable.
+Le panneau de disponibilité au démarrage couvre les quatre ports : REST/MCP HTTP sur 3111, streams iii sur 3112, le visualiseur sur 3113, et le WebSocket du worker iii sur 49134. `status` confirme la santé d'agentmemory et le mode fournisseur/embedding actif. Sauvegardez une sonde et confirmez qu'elle est trouvable :
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
-Ouvrez `http://localhost:3113` pour voir la mémoire se construire en direct.
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Lancez ensuite `npx -y @agentmemory/agentmemory@latest stop`, redémarrez la commande canonique dans le Terminal 1, attendez `/agentmemory/livez`, et répétez la recherche. La sonde doit toujours être retournée. Si vous avez sélectionné un `--data-dir` personnalisé, passez le même répertoire au redémarrage.
### Commandes du quotidien
-L'installation et le setup sont dans [Install](#install) ci-dessus (la première exécution vous guide). Au quotidien :
+L'installation et le setup se trouvent dans [Installation](#install) ci-dessus (la première exécution vous guide). Au quotidien :
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -493,58 +611,58 @@ agentmemory remove # uninstall everything we created
### 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,5x à 4x) et raccourcis clavier (espace pour basculer, flèches pour avancer).
+Chaque session enregistrée par agentmemory peut être rejouée. Ouvrez le visualiseur, choisissez l'onglet **Replay**, et parcourez la timeline : prompts, appels d'outils, résultats d'outils et réponses s'affichent comme des événements distincts avec lecture/pause, contrôle de vitesse (0.5x à 4x) et raccourcis clavier (espace pour basculer, flèches pour avancer pas à pas).
-Pour importer d'anciennes transcriptions JSONL Claude Code :
+Pour importer d'anciens transcripts JSONL de Claude Code :
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest 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`, sans serveur secondaire. Chaque transcription importée est indexée pour la recherche, estampillée avec le canal d'origine `import`, et exploitée pour en tirer un cristal de session et des leçons.
+Les sessions importées apparaissent dans le sélecteur Replay aux côtés des sessions natives. Sous le capot, chaque entrée passe par les fonctions iii `mem::replay::load`, `mem::replay::sessions` et `mem::replay::import-jsonl`, sans serveur annexe. Chaque transcript importé est indexé pour la recherche, tamponné avec le canal d'origine `import`, et exploité pour produire un cristal de session et des lessons.
-> **Attention si vous comptez sur `import-jsonl` comme chemin de capture principal :** le `cleanupPeriodDays` de Claude Code (dans `~/.claude/settings.json`, **30** par défaut) supprime automatiquement de `~/.claude/projects/` les transcriptions JSONL plus anciennes que cette fenêtre. Si vous installez agentmemory à neuf sur un historique Claude Code vieux de plusieurs mois, tout ce qui a plus de 30 jours a déjà disparu avant le premier import. Lancez `import-jsonl` via un cron, augmentez `cleanupPeriodDays`, ou câblez les hooks de capture automatique (le chemin d'installation par défaut du plugin) pour que chaque tour atterrisse dans agentmemory pendant que la session est en cours et que le nettoyage JSONL cesse d'avoir de l'importance.
+> **Important si vous comptez sur `import-jsonl` comme chemin de capture principal :** le `cleanupPeriodDays` de Claude Code (dans `~/.claude/settings.json`, défaut **30**) supprime automatiquement les transcripts JSONL plus anciens que cette fenêtre depuis `~/.claude/projects/`. Si vous installez agentmemory fraîchement sur un historique Claude Code de plusieurs mois, tout ce qui a plus de 30 jours a déjà disparu avant le premier import. Soit vous lancez `import-jsonl` via un cron, soit vous augmentez `cleanupPeriodDays`, soit vous câblez les hooks de capture automatique (le chemin d'installation par défaut du plugin) pour que chaque tour atterrisse dans agentmemory tant que la session est active, et le nettoyage JSONL cesse d'avoir de l'importance.
### Mise à niveau / Maintenance
-Utilisez la commande de maintenance lorsque vous voulez intentionnellement mettre à jour votre runtime local :
+Utilisez la commande de maintenance quand vous souhaitez intentionnellement mettre à jour votre runtime local :
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Avertissement : cette commande modifie l'espace de travail / runtime courant. Elle peut mettre à jour les dépendances JavaScript et tirer l'image Docker épinglée `iiidev/iii:0.11.2`. Elle n'installe jamais un moteur iii non épinglé ou plus récent.
+Avertissement : cette commande modifie l'espace de travail/runtime actuel. Elle peut mettre à jour les dépendances JavaScript et récupérer l'image Docker épinglée `iiidev/iii:0.22.1`. Elle n'installe jamais un moteur iii non épinglé ou plus récent.
-Détails d'implémentation dans `src/cli.ts` (voir `runUpgrade` autour de la zone `src/cli.ts:544-595`).
+Les détails d'implémentation se trouvent dans `src/cli.ts` (voir `runUpgrade` autour de la zone `src/cli.ts:544-595`).
-### Claude Code (un seul bloc, à coller)
+### Claude Code (un 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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
-#### Claude Code sans installation du plugin (chemin MCP-standalone)
+#### Claude Code sans l'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.
+Si vous câblez le serveur MCP d'agentmemory via `~/.claude.json` directement plutôt qu'en utilisant `/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.22/scripts/…`), donc la prochaine mise à niveau casse silencieusement chaque hook.
-Contournement :
+Solution de 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`.
+Cela fusionne les mêmes commandes de hooks dans `~/.claude/settings.json` avec des chemins absolus résolus vers le répertoire `plugin/` embarqué dans le paquet `@agentmemory/agentmemory` actuellement installé. Relancez la commande après chaque mise à niveau d'agentmemory pour rafraîchir les chemins. Les entrées utilisateur dans le même fichier sont préservées ; seules les entrées agentmemory précédentes sont remplacées. 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 embarqué ; 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
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
@@ -553,29 +671,43 @@ 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 54 outils lorsque `AGENTMEMORY_URL` pointe vers un serveur agentmemory actif ; retombe sur 7 outils en local si aucun serveur n'est accessible)
+- Un pont MCP stdio embarqué vers le daemon en cours d'exécution, sans téléchargement npm ni store de fallback. Voir le [guide Codex local](../docs/plugins/codex-local.md) pour tester un build non publié.
- 6 hooks de cycle de vie : `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
-- 9 skills invocables : `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 skills de référence que l'agent charge à la demande (memory discipline, outils MCP, API REST, config, agents, hooks, architecture et le guide d'écriture de skills)
+- 9 skills invocables : `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 skills de référence que l'agent charge à la demande (discipline de mémoire, outils MCP, API REST, config, agents, hooks, architecture, et le guide d'écriture de skills)
-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.
+Le moteur de hooks de Codex injecte `CLAUDE_PLUGIN_ROOT` dans les sous-processus de hooks (selon [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), si bien que les mêmes scripts de hooks fonctionnent sur les deux hôtes sans duplication. Les événements Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure sont spécifiques à Claude Code et ne sont pas enregistrés pour Codex.
-#### Codex Desktop : hooks de plugin actuellement silencieux (contournement disponible)
+#### Hooks Codex : confiance et compatibilité
-`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.
+Le déclenchement natif des hooks de plugin est vérifié avec Codex CLI 0.150.1. Faites confiance aux hooks du plugin avant de vous attendre à une capture. Le comportement de Codex Desktop dépend de son runtime embarqué ; vérifiez `/hooks` et confirmez un événement capturé avant d'activer une solution de contournement.
-En attendant le correctif amont, dupliquez les mêmes commandes de hooks dans le `~/.codex/hooks.json` global :
+Si votre hôte nécessite des hooks globaux, répliquez les commandes dans le `~/.codex/hooks.json` global. Quand MCP est déjà câblé, l'adaptateur `connect` actuel a besoin de `--force` pour atteindre l'installation des hooks :
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-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.
+Cela fusionne les hooks globaux et réécrit l'entrée MCP d'agentmemory, en préservant les entrées non liées. Vérifiez vos paramètres d'endpoint agentmemory personnalisés avant d'utiliser `--force`. Relancez après une mise à niveau pour rafraîchir les chemins des scripts. Activez soit les hooks natifs du plugin, soit les copies globales, pour éviter une capture en double.
+
+### GitHub Copilot CLI
+
+Pour le mode agent de VS Code, utilisez le [guide MCP et capture automatique de Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Le connecteur CLI ne configure pas VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` fusionne `mcpServers.agentmemory` dans `~/.copilot/mcp-config.json` (ou `$COPILOT_HOME/mcp-config.json` quand `COPILOT_HOME` est défini) et préserve les serveurs existants. Sur Windows natif, c'est le seul adaptateur `connect` automatisé ; configurez tout autre agent Windows natif manuellement. Le `connect` sous WSL n'est pris en charge que lorsque l'agent cible est aussi installé dans ce même environnement WSL. Copilot prend en compte le serveur MCP au lancement suivant ou après `/mcp`. Installez aussi le plugin quand vous voulez l'expérience complète hooks/skills.
OpenClaw (collez ce prompt)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -600,7 +732,7 @@ Guide complet : [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (collez ce prompt)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -619,7 +751,7 @@ Guide complet : [`integrations/hermes/`](../integrations/hermes/)
### Autres agents
-Démarrez le serveur de mémoire : `npx @agentmemory/agentmemory`
+Démarrez le serveur de mémoire : `npx -y @agentmemory/agentmemory@latest`
#### Skills natifs via `npx skills add` (50+ agents)
@@ -631,16 +763,16 @@ npx skills add rohitg00/agentmemory -y -a warp # explicit agent
npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
```
-C'est **complémentaire** à `agentmemory connect ` :
+Ceci est **complémentaire** à `agentmemory connect ` :
- `agentmemory connect ` écrit la config du serveur MCP pour que les outils soient disponibles.
- `npx skills add rohitg00/agentmemory` installe les skills pour que l'agent sache quand les appeler.
-Pour les rares agents que la CLI skills ne couvre pas encore (Zed v1.3.x et antérieurs), déposez vous-même les 17 fichiers SKILL.md dans le répertoire de skills natif de l'agent ; le même format fonctionne partout.
+Pour les rares agents que la CLI skills ne couvre pas encore (Zed v1.3.x et antérieures), déposez vous-même les 17 fichiers SKILL.md dans le répertoire de skills natif de l'agent ; le même format fonctionne partout.
#### Bloc MCP standard
-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) :
+L'entrée agentmemory est le **même bloc de serveur MCP** sur tous les hôtes qui utilisent la forme `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw) :
```json
"agentmemory": {
@@ -653,44 +785,46 @@ L'entrée agentmemory est le **même bloc serveur MCP** pour tous les hôtes uti
}
```
-**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).
+**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 a déjà d'autres serveurs, ajoutez `agentmemory` à côté d'eux comme une autre clé à l'intérieur de `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 ; les variables non définies transmettent 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 / derrière un 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. |
+| **Cursor (MCP uniquement)** | `~/.cursor/mcp.json` | Fusionnez dans `mcpServers`, ou `agentmemory connect cursor`. Un deeplink en un clic est aussi disponible sur le site. |
+| **Cursor (plugin complet)** | `.cursor-plugin/` | Listing sur le Cursor Marketplace (soumission en cours de revue) ou Cursor Settings → Plugins → checkout local. Enregistre 7 hooks de capture automatique (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + le serveur MCP, avec `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` gérés dans le dashboard de plugin de Cursor. Fonctionne dans l'IDE Cursor et la CLI `cursor-agent` ; les prompts du mode print de la CLI sont réalimentés depuis le transcript de session en fin de session. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Fusionnez dans `mcpServers`. Redémarrez Claude Desktop après édition. |
| **Cline / Roo Code / Kilo Code** | Paramètres MCP de Cline (Settings UI → MCP Servers → Edit) | Même bloc `mcpServers`. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` fusionne l'entrée MCP ; `--with-hooks` ajoute six hooks natifs de capture automatique (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) avec les matchers d'outils en minuscules de Devin. Vérifiez avec `devin mcp list` et `/hooks` dans devin. |
-| **Devin (cloud)** | Settings → Connections → MCP servers | Ajoutez un MCP personnalisé (STDIO) : command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` pointant vers un déploiement agentmemory accessible par le réseau plus `AGENTMEMORY_SECRET` (les sessions cloud n'atteignent pas localhost — voir [`deploy/`](../deploy/)). |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` fusionne l'entrée MCP ; `--with-hooks` ajoute six hooks natifs de capture automatique (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) avec les matchers d'outils en minuscules de Devin. Vérifiez avec `devin mcp list` et `/hooks` dans devin. |
+| **Devin CLI (plugin complet)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` depuis un checkout enregistre les 17 skills comme commandes slash `/agentmemory:` plus le serveur MCP. Les hooks du plugin Devin ne peuvent pas déclencher `SessionStart`/`SessionEnd`, donc associez-le à `connect devin --with-hooks` pour une capture de session complète. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Ajoutez un MCP personnalisé (STDIO) : commande `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` pointant vers un déploiement agentmemory accessible sur le réseau plus `AGENTMEMORY_SECRET` (les sessions cloud ne peuvent pas atteindre localhost — voir [`deploy/`](../deploy/)). Stockez le secret dans Devin Secrets, puis utilisez « Test listing tools » pour vérifier que les 54 outils apparaissent. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (fusion automatique). |
-| **GitHub Copilot CLI (MCP seul)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` fusionne `mcpServers.agentmemory` ; Copilot le prend en compte au prochain lancement ou via `/mcp`. |
+| **GitHub Copilot CLI (MCP uniquement)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` fusionne `mcpServers.agentmemory` ; Copilot le prend en compte au lancement suivant ou via `/mcp`. |
| **GitHub Copilot CLI (plugin complet)** | Installation de plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` pour le plugin depuis le sous-répertoire GitHub. |
-| **OpenClaw** | Config MCP d'OpenClaw | Même bloc `mcpServers`. Plus poussé : `openclaw plugins install ./integrations/openclaw` s'approprie le slot mémoire d'OpenClaw (bascule automatiquement depuis `memory-core`) ; définissez `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, sinon la capture de tour est silencieusement bloquée. Voir [`integrations/openclaw`](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) + 17 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. L'attribution de projet est par session, donc un même processus OpenCode couvrant plusieurs dépôts classe chaque session sous son propre projet. 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. |
+| **OpenClaw** | Config MCP d'OpenClaw | Même bloc `mcpServers`. Plus poussé : `openclaw plugins install ./integrations/openclaw` revendique le slot de mémoire d'OpenClaw (bascule automatique depuis `memory-core`) ; définissez `plugins.entries.agentmemory.hooks.allowConversationAccess=true` sinon la capture de tour est silencieusement bloquée. Voir [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (MCP uniquement)** | `.codex/config.toml` | Forme TOML : `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, ou ajoutez `[mcp_servers.agentmemory]` manuellement. |
+| **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 + 17 skills. Faites confiance aux hooks et vérifiez la capture dans votre hôte ; voir [Configuration et validation Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (MCP uniquement)** | `opencode.json` | Forme différente : clé `mcp` de premier niveau, commande en tableau : `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin complet)** | `plugin/opencode/` | 22 hooks de capture automatique couvrant le cycle de vie des sessions, les messages, les outils, les erreurs. L'attribution de projet est par session, donc un processus OpenCode unique couvrant plusieurs dépôts classe chaque session sous son propre projet. Deux commandes slash (`/recall`, `/remember`). Copiez `plugin/opencode/` dans votre espace de travail 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 + l'analyse des écarts. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installe l'extension embarquée dans le répertoire d'auto-découverte de pi (recall au démarrage de l'agent, capture à la fin de l'agent, outils `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` dans un pi en cours d'exécution la prend en compte. [`integrations/pi`](../integrations/pi/) est aussi un paquet pi (`pi install ./integrations/pi` depuis un checkout). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` active le fournisseur de mémoire à 6 hooks (préchargement, capture de tour, fin de session, pré-compression, mise en miroir de MEMORY.md, bloc de prompt système). Validez avec `hermes plugins doctor` et `hermes memory status`. Voir [`integrations/hermes`](integrations/hermes/). |
-| **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. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. La CLI `agy` garde sa propre config sous `~/.gemini/`, distincte de l'IDE Antigravity ci-dessus. Passez `--with-hooks` pour la capture automatique native via `~/.gemini/config/hooks.json`. |
-| **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. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` donne le fournisseur de mémoire à 6 hooks (préchargement, capture de tour, fin de session, pré-compression, mise en miroir de MEMORY.md, bloc de prompt système). Validez avec `hermes plugins doctor` et `hermes memory status`. Voir [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` écrit le bloc `mcpServers` standard. Le payload des hooks est compatible champ par 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 IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installe MCP et les hooks de capture dans le répertoire de personnalisation partagé. Voir [Configuration et limites d'Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` utilise la même configuration MCP et hooks que les versions actuelles de l'IDE. Les installations existantes doivent se rafraîchir avec `--force` ; voir les [notes de mise à jour](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` écrit la config au niveau utilisateur. Les surcharges au niveau du workspace vont dans `.kiro/settings/mcp.json` à côté de votre code. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` écrit le bloc `mcpServers` standard. Warp découvre aussi automatiquement les skills depuis `.claude/skills/` ; une fois le plugin Claude Code installé, les 8 skills agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) apparaissent nativement dans la palette de commandes slash de Warp. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` écrit le bloc `mcpServers` standard. Utilisateurs de l'extension VS Code : collez le même bloc via Cline Settings → MCP Servers → Edit JSON. |
-| **Continue.dev** | `~/.continue/config.yaml` (préféré) ou `config.json` (legacy) | `agentmemory connect continue` crée `config.yaml` de zéro quand aucun des deux n'existe, ou modifie un `config.json` existant. **Si vous avez déjà `config.yaml`**, l'adaptateur imprime le bloc exact à coller sous `mcpServers:` ; il ne réécrira pas silencieusement votre yaml parce que préserver commentaires et ancres en toute sécurité exige un parseur YAML que le paquet n'embarque pas. Continue utilise la forme tableau (pas objet) pour `mcpServers`. |
+| **Continue.dev** | `~/.continue/config.yaml` (préféré) ou `config.json` (legacy) | `agentmemory connect continue` crée `config.yaml` à partir de rien quand aucun des deux n'existe, ou modifie le `config.json` existant. **Si vous avez déjà un `config.yaml`**, l'adaptateur affiche le bloc exact à coller sous `mcpServers:` ; il ne réécrira pas silencieusement votre yaml car préserver les commentaires et les ancres en toute sécurité nécessite un parseur YAML que le paquet n'embarque pas. Continue utilise la forme tableau (pas objet) pour `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` écrit sous `context_servers` (la clé de Zed, PAS `mcpServers`). Les serveurs MCP distants peuvent être câblés via `{"url": "..."}` à la place. |
-| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` écrit le bloc `mcpServers` standard. Les overrides par projet vont dans `/.factory/mcp.json`. Passez `--with-hooks` pour la capture automatique native. |
-| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` ajoute une ligne `@deepseek-ai/dsh-mcp-client` à la couche de patch au niveau home que chaque profil Harness charge ; les outils s'enregistrent comme `mcp__agentmemory__*`. Passez `--with-hooks` pour câbler aussi la capture automatique : les scripts de hooks Claude Code embarqués passent par le pont first-party `@deepseek-ai/dsh-hooks-claude-code` de Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via un manifeste écrit dans `$DSH_HOME/agentmemory.hooks.json`. Défaut `~/.dsh` quand `DSH_HOME` n'est pas défini. |
-| **Goose** | UI des paramètres MCP de Goose | Même bloc `mcpServers` ; utilisez `goose configure` → Add Extension → MCP. L'édition YAML directe dans `~/.config/goose/config.yaml` est supportée mais le schéma utilise `extensions:` + `cmd` (pas `mcpServers:` + `command`). |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` écrit le bloc `mcpServers` standard. Les surcharges au niveau du projet vont dans `/.factory/mcp.json`. Passez `--with-hooks` pour la capture automatique native. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` ajoute une ligne `@deepseek-ai/dsh-mcp-client` à la couche de patch de niveau home que chaque profil Harness charge ; les outils s'enregistrent comme `mcp__agentmemory__*`. Passez `--with-hooks` pour câbler aussi la capture automatique : les scripts de hooks Claude Code embarqués tournent via le pont natif `@deepseek-ai/dsh-hooks-claude-code` de Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via un manifeste écrit dans `$DSH_HOME/agentmemory.hooks.json`. Par défaut `~/.dsh` quand `DSH_HOME` n'est pas défini. |
+| **Goose** | UI des paramètres MCP de Goose | Même bloc `mcpServers` ; utilisez `goose configure` → Add Extension → MCP. L'édition YAML directe sur `~/.config/goose/config.yaml` est prise en charge mais le schéma utilise `extensions:` + `cmd` (pas `mcpServers:` + `command`). |
| **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. |
+| **Tout agent (32+)** | n/a | `npx skillkit install agentmemory` détecte automatiquement l'hôte 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).
+**Clients MCP sandboxés** (Flatpak / Snap / conteneurs restrictifs) qui ne peuvent pas atteindre le `localhost` de l'hôte : définissez aussi `"AGENTMEMORY_FORCE_PROXY": "1"` dans le bloc `env`, et pointez `AGENTMEMORY_URL` vers une route que le sandbox peut réellement atteindre (par ex. votre IP LAN).
### 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`, sans client REST séparé par langage.
+agentmemory enregistre ses opérations centrales comme fonctions iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Tout langage disposant d'un SDK iii peut les appeler directement via `ws://localhost:49134`, sans client REST séparé par langage.
```bash
pip install iii-sdk # Python
@@ -710,7 +844,7 @@ iii.trigger({
})
```
-Exemple complet : [`examples/python/`](../examples/python/) (quickstart + flux observation/recall). REST sur `:3111` reste disponible pour les hôtes sans runtime iii.
+Exemple travaillé : [`examples/python/`](../examples/python/) (démarrage rapide + flux observation/recall). REST sur `:3111` reste disponible pour les hôtes sans runtime iii.
### Depuis les sources
@@ -719,39 +853,43 @@ 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.
+Cela démarre agentmemory avec un `iii-engine` local si le binaire épinglé est déjà installé, ou utilise Docker Compose si sélectionné. REST, streams et le visualiseur se lient à `127.0.0.1` par défaut. Le chemin automatique de binaire macOS/Linux nécessite `curl`, un `sh` POSIX, et `tar`.
-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=` si vous avez migré au modèle sandbox manuellement.
+Installez `iii-engine` manuellement. **agentmemory épingle actuellement `iii-engine` à `v0.22.1`**, la même version que sa dépendance `iii-sdk` ; le worker parle le protocole réseau de ce moteur, et 0.20.0 a réorganisé la surface du SDK, donc les deux évoluent ensemble dans les versions d'agentmemory. Remplacez avec `AGENTMEMORY_III_VERSION=` si vous faites tourner votre propre moteur et savez qu'il correspond.
-- **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 arm64 :** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64 :** 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
+- **Windows :** téléchargez `iii-x86_64-pc-windows-msvc.zip` depuis [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) et extrayez `iii.exe` vers `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Chaque archive a un fichier `.sha256` correspondant sur la page de release ; quand vous changez de plateforme, utilisez le hash de ce fichier dans la vérification ci-dessus (sur Windows : `Get-FileHash`). L'installateur automatique dans `npx @agentmemory/agentmemory` épingle ces hashs et refuse une archive qui ne correspond pas.
-Ou utilisez Docker (le `docker-compose.yml` fourni tire `iiidev/iii:0.11.2`). Documentation complète : [iii.dev/docs](https://iii.dev/docs).
+Ou utilisez Docker (le `docker-compose.yml` embarqué récupère `iiidev/iii:0.22.1`). 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 :
+agentmemory fonctionne sur Windows 10/11, mais le paquet Node.js seul ne suffit pas ; vous avez aussi besoin du runtime iii-engine v0.22.1 épinglé comme processus en arrière-plan. La CLI n'extrait pas automatiquement le ZIP Windows, donc les utilisateurs Windows natifs doivent installer `iii.exe` manuellement, utiliser WSL2, ou choisir Docker Desktop.
+
+Le câblage MCP automatisé natif sous Windows ne prend en charge que `agentmemory connect copilot-cli`. Pour Claude Code, Codex, Cursor et tout autre agent Windows natif, copiez le bloc MCP manuel depuis [Autres agents](#other-agents) dans la config Windows de cet agent. Exécuter `connect` sous WSL n'est approprié que lorsque l'agent cible est aussi installé dans ce même environnement WSL ; cela ne modifie pas la config d'un agent hébergé sous Windows.
**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)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**Option B : Docker Desktop**
@@ -759,72 +897,75 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
-**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 :
+**Option C : MCP standalone uniquement (sans moteur).** Si vous avez seulement besoin des outils MCP pour votre agent et n'avez pas besoin de l'API REST, du visualiseur ou des tâches cron, ignorez complètement le moteur :
```powershell
-npx -y @agentmemory/agentmemory mcp
+npx -y @agentmemory/agentmemory@latest 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 :
+**Diagnostics pour Windows :** si `npx -y @agentmemory/agentmemory@latest` échoue, relancez-la avec `--verbose` pour voir le stderr réel du moteur. Modes d'échec 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 |
+| `The engine process started but the REST API never responded.` | Confirmez que les quatre ports dérivés sont libres, vérifiez que l'`iii.exe` épinglé est resté actif, puis relancez avec `--verbose` et examinez le stderr du moteur capturé |
+| `Could not start iii-engine` | Ni `iii.exe` ni Docker ne sont installés. Voir l'Option A ou B ci-dessus |
| Conflit de port | `netstat -ano \| findstr :3111` pour voir ce qui est lié, puis tuez-le ou utilisez `--port ` |
-| Fallback Docker ignoré bien que Docker soit installé | Assurez-vous que Docker Desktop tourne effectivement (icône de la barre d'état système) |
+| Repli sur Docker ignoré même si Docker est installé | Assurez-vous que Docker Desktop est réellement en cours d'exécution (icône dans la barre système) |
-> Note : le **moteur** iii est un binaire précompilé, pas un crate cargo, donc n'essayez pas de l'installer avec `cargo install`. (Les **SDK** iii sont bien publiés sur crates.io, npm et PyPI, mais agentmemory n'en a pas besoin.) Méthodes d'installation du moteur supportées, toutes épinglées à v0.11.2 : le binaire précompilé v0.11.2 ci-dessus, le script d'installation `sh` amont **avec l'épingle de version** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) et l'image Docker `iiidev/iii:0.11.2`. Un simple `install.sh | sh` installe le moteur **le plus récent**, que agentmemory ne supporte pas ; passez toujours `VERSION=0.11.2`. Le plus simple de tout : exécutez simplement `npx @agentmemory/agentmemory`, qui récupère le moteur épinglé dans `~/.agentmemory/bin` pour vous.
+> Remarque : le **moteur** iii est un binaire précompilé, pas une crate cargo, donc n'essayez pas de faire `cargo install` dessus. (Les **SDK** iii sont publiés sur crates.io, npm et PyPI, mais agentmemory n'en a pas besoin.) Les méthodes d'installation du moteur prises en charge sont toutes épinglées à v0.22.1 : le binaire précompilé ci-dessus, le chemin d'auto-installation macOS/Linux d'agentmemory (`curl`, `sh` POSIX, et `tar` requis), et l'image Docker `iiidev/iii:0.22.1`. Un `install.sh | sh` amont nu installe le dernier moteur, que agentmemory ne prend pas en charge. Utilisez `npx -y @agentmemory/agentmemory@latest` ; sur macOS/Linux il récupère le moteur épinglé dans `~/.agentmemory/bin`.
---
Déploiement
-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.
+Des 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 du moteur iii depuis l'image Docker Hub officielle
+`iiidev/iii` ; aucune image agentmemory pré-construite n'est requise. Le
+stockage persistant se monte sur `/data` ; le point d'entrée du premier
+démarrage remplace la config iii embarquée dans npm (qui se lie à
+`127.0.0.1`) par une config adaptée au déploiement qui se lie à
+`0.0.0.0` et utilise des chemins `/data` absolus, génère le secret
+HMAC, puis abandonne les privilèges de `root` vers `node` via
+`gosu` avant d'exécuter la CLI agentmemory.
-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.
+Le bouton de déploiement en un clic de Render nécessite un `render.yaml` à la racine du dépôt, que nous gardons volontairement propre. Utilisez le flux Render Blueprint documenté dans [`deploy/render/`](.././deploy/render/README.md) pour pointer manuellement vers le blueprint du 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) :
+Les détails complets de configuration (capture HMAC, tunnel SSH du
+visualiseur, rotation, sauvegarde, planchers de coût) se trouvent 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.
+- [`deploy/fly`](.././deploy/fly/README.md) : machine unique avec
+ `auto_stop_machines = "stop"` ; le plus économique en veille.
+- [`deploy/railway`](.././deploy/railway/README.md) : forfait Hobby,
+ volume dans le dashboard.
+- [`deploy/render`](.././deploy/render/README.md) : flux Blueprint,
+ snapshots automatiques du disque sur les plans 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.
+Seul le port `3111` est publié. Le visualiseur sur `3113` reste lié à
+loopback à l'intérieur du conteneur ; le README de chaque template
+documente le motif de tunnel SSH pour l'atteindre.
---
-Chaque agent de codage oublie tout quand la session se termine, et chaque nouvelle session commence par la réexplication de votre stack. agentmemory tourne en arrière-plan et supprime cette étape.
+Chaque agent de codage oublie tout quand la session se termine, et chaque nouvelle session commence avec vous qui réexpliquez votre stack. agentmemory tourne en arrière-plan et supprime cette étape.
```text
Session 1: "Add auth to the API"
@@ -840,33 +981,34 @@ Session 2: "Now add rate limiting"
Zero re-explaining. Starts working immediately.
```
-### vs mémoire d'agent intégrée
+### vs la mémoire intégrée de l'agent
-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.
+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 une memory bank. Elles fonctionnent comme des post-it. agentmemory est la base de données interrogeable derrière les post-it.
-| | Intégrée (CLAUDE.md) | agentmemory |
+| | Intégré (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) |
+| Échelle | Plafond de 200 lignes | Illimité |
+| Recherche | Charge tout en contexte | BM25 + vectoriel + graphe (top-K seulement) |
+| Coût en tokens | 22K+ à 240 observations | ~1 900 tokens (92% de moins) |
+| Entre agents | Fichiers par agent | MCP + REST (tout agent) |
| Coordination | Aucune | Leases, signaux, actions, routines |
-| Observabilité | Lire les fichiers à la main | Visualiseur temps réel sur :3113 |
+| Observabilité | Lire les fichiers manuellement | Visualiseur temps réel sur :3113 |
---
-### Pipeline mémoire
+### Pipeline de 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -880,87 +1022,91 @@ SessionStart hook fires
-> Inject into conversation
```
-### Consolidation mémoire à 4 niveaux
+### Consolidation de mémoire à 4 niveaux
-Modelée sur la façon dont le cerveau humain traite la mémoire, y compris la consolidation pendant le sommeil.
+Modélisé sur la façon dont les cerveaux humains traitent la mémoire, y compris 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 » |
+| **Semantic** | Faits et patterns extraits | « Ce que je sais » |
+| **Procedural** | Workflows et patterns 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.
+Les mémoires se dégradent avec 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 |
+| `SessionStart` | Chemin du projet, ID de session |
+| `UserPromptSubmit` | Prompts utilisateur (filtrés pour la confidentialité) |
+| `PreToolUse` | Patterns d'accès aux fichiers + contexte enrichi |
| `PostToolUse` | Nom de l'outil, entrée, sortie |
| `PostToolUseFailure` | Contexte d'erreur |
-| `PreCompact` | Réinjecte la mémoire avant compaction |
+| `PreCompact` | Réinjecte la mémoire avant la compaction |
| `SubagentStart/Stop` | Cycle de vie des sous-agents |
| `Stop` | Résumé de fin de session |
-| `SessionEnd` | Marqueur de fin de session |
+| `SessionEnd` | Marqueur de session terminée |
### Capacités clés
| Capacité | Description |
|---|---|
-| **Capture automatique** | Chaque usage d'outil enregistré via hooks, sans effort manuel |
-| **Recherche sémantique** | BM25 + vecteur + graphe de connaissances avec fusion RRF |
+| **Capture automatique** | Chaque usage d'outil enregistré via des hooks, aucun effort manuel |
+| **Recherche sémantique** | BM25 + vectoriel + graphe de connaissances avec fusion RRF |
| **Évolution de la mémoire** | Versioning, supersession, graphes de relations |
| **Hygiène de recall** | Les versions de mémoire supersédées quittent les index de recherche ; la chaîne de versions en KV conserve l'historique complet |
-| **Indices de quasi-doublons** | Les sauvegardes signalent une correspondance consultative `similarTo` quand un nouveau contenu ressemble fortement à une mémoire existante |
-| **Scoping par agent** | `agentId` traverse la sauvegarde et le recall via REST, MCP et l'index de recherche, en mode partagé ou isolé |
-| **Provenance à l'écriture** | Chaque observation et mémoire porte un canal d'origine immuable (user, agent, tool, import ou shared) estampillé à la capture, à la sauvegarde et à l'import |
-| **Oubli automatique** | Expiration TTL, détection de contradictions, éviction par importance |
-| **Vie privée d'abord** | Clés d'API, secrets, balises `` retirés avant stockage |
+| **Indices de quasi-doublon** | Les sauvegardes signalent une correspondance consultative `similarTo` quand un nouveau contenu ressemble fortement à une mémoire existante |
+| **Scoping par agent** | `agentId` traverse la sauvegarde et le recall à travers REST, MCP, et l'index de recherche, en mode partagé ou isolé |
+| **Provenance à l'écriture** | Chaque observation et chaque mémoire porte un canal d'origine immuable (user, agent, tool, import, ou shared) tamponné à la capture, la sauvegarde et l'import |
+| **Oubli automatique** | Expiration TTL, détection de contradiction, éviction par importance |
+| **Confidentialité d'abord** | Clés API, secrets, tags `` retirés avant le 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 |
+| **Mémoire d'équipe** | Partagée + privée, namespacée entre les membres de l'équipe |
+| **Provenance des citations** | Retracer toute mémoire jusqu'à ses observations source |
+| **Snapshots Git** | Versionner, revenir en arrière et diffuser l'état de la mémoire |
---
-Récupération triple-flux combinant trois signaux :
+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 |
+| **BM25** | Correspondance de mots-clés avec stemming et expansion de synonymes | Toujours actif |
+| **Vectoriel** | Similarité cosinus sur des embeddings denses | Fournisseur d'embedding configuré |
+| **Graphe** | Parcours du graphe de connaissances via correspondance d'entités | Entités détectées dans la requête |
+
+Fusionné avec la Reciprocal Rank Fusion (RRF, k=60) et diversifié par session (max 3 résultats par session).
-Fusionnés par Reciprocal Rank Fusion (RRF, k=60) et diversifiés par session (max 3 résultats par session).
+Quand un index vectoriel est peuplé, `mem::search` (derrière `memory_recall`) utilise le ranker hybride BM25 + vectoriel. Sans embeddings, il utilise BM25. `smart-search` peut en plus fusionner des correspondances de graphe structurel quand des données de graphe existent, y compris en mode sans clé. Le recall de lessons tourne sur un index BM25 en mémoire dédié plutôt que de scanner tout le corpus à chaque requête. Les versions de mémoire supersédées sont exclues de tout chemin de recall ; la chaîne de versions conserve leur historique.
-Le classement hybride s'applique au chemin de recall principal, pas seulement à `smart-search` : `mem::search` (derrière `memory_recall`) classe via la même fusion BM25 + vectoriel + graphe une fois l'index vectoriel peuplé. Le recall des leçons tourne sur un index BM25 en mémoire dédié au lieu de balayer tout le corpus à chaque requête. Les versions de mémoire supersédées sont exclues de chaque chemin de recall ; la chaîne de versions conserve leur historique.
+Les vecteurs survivent à un crash ou à un force-kill. L'index vectoriel est sauvegardé par lots au plus toutes les `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutes). Chaque vecteur ajouté ou retiré entre-temps est aussi écrit immédiatement dans un petit journal en attente dans le state store, et le prochain démarrage le rejoue sans appeler le fournisseur d'embedding. Chaque sauvegarde réussie vide le journal. Les documents qui n'ont toujours pas de vecteur après le replay sont réembarqués en arrière-plan par lots de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) jusqu'à épuisement, et un backfill arrêté reprend au démarrage suivant. `/agentmemory/status` et le visualiseur affichent la taille du journal en attente et l'état du backfill. Les installations sans clé n'écrivent rien.
-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.
+BM25 tokenise le grec, le cyrillique, l'hébreu, l'arabe et le latin accentué nativement. Pour les mémoires en chinois / japonais / coréen, installez les segmenteurs optionnels (`npm install @node-rs/jieba tiny-segmenter`) pour découper les suites CJK en tokens au niveau mot ; sans eux, agentmemory retombe en douceur sur une tokenisation en bloc complet et affiche un indice ponctuel sur stderr.
### Fournisseurs d'embedding
-agentmemory détecte automatiquement votre fournisseur. Pour de meilleurs résultats, installez les embeddings locaux (gratuits) :
+Les installations sans clé désactivent les embeddings vectoriels : `mem::search` utilise BM25, tandis que `smart-search` peut aussi utiliser des données de graphe structurel existantes. Pour opter pour des embeddings sémantiques gratuits sur l'appareil, ajoutez ceci à `~/.agentmemory/.env` et redémarrez agentmemory :
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+L'installation npm normale inclut le runtime optionnel `@huggingface/transformers`. La première requête d'embedding télécharge `Xenova/all-MiniLM-L6-v2`, donc elle nécessite un accès réseau et peut prendre plus de temps ; l'inférence suivante tourne sur l'appareil. Les fournisseurs distants sont auto-détectés depuis leurs clés sauf si `EMBEDDING_PROVIDER` les remplace.
+
| 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é |
+| **Local (opt-in recommandé)** | `all-MiniLM-L6-v2` | Gratuit | Sur l'appareil après le premier téléchargement de modèle, +8pp de recall par rapport à BM25 seul |
+| Gemini | `gemini-embedding-001` | Palier gratuit | 100+ langues, 768/1536/3072 dims (MRL), entrée de 2048 tokens. Remplace `text-embedding-004` ([obsolète, arrêt le 14 janvier 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 |
+| Cohere | `embed-english-v3.0` | Essai gratuit | Usage général |
+| OpenRouter | N'importe quel modèle | Variable | Proxy multi-modèle |
---
@@ -968,11 +1114,11 @@ npm install @huggingface/transformers
54 outils, 6 ressources, 3 prompts et 17 skills.
-> **Shim MCP vs serveur complet :** le paquet publié `@agentmemory/mcp` est un shim léger. Il expose la surface complète de 54 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`.
+> **Shim MCP vs serveur complet :** le paquet publié `@agentmemory/mcp` est un shim léger. Il expose la surface complète de 54 outils **uniquement quand il peut joindre un serveur agentmemory en cours d'exécution** 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, démarrez `npx -y @agentmemory/agentmemory@latest` (ou la stack Docker) et définissez `AGENTMEMORY_URL=http://localhost:3111`.
### 54 outils
-Trois surfaces d'outils, de la plus petite à la plus grande : `AGENTMEMORY_TOOLS=core` réduit la visibilité à 8 essentiels (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`) ; le jeu de base ci-dessous correspond aux 14 outils fondamentaux du registre ; le défaut (`AGENTMEMORY_TOOLS=all`) expose les 54.
+Trois surfaces d'outils, de la plus petite à la plus grande : `AGENTMEMORY_TOOLS=core` réduit la visibilité à 8 essentiels (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`) ; le jeu de base ci-dessous est constitué des 14 outils fondamentaux du registre ; le défaut (`AGENTMEMORY_TOOLS=all`) expose les 54.
Outils de base (14)
@@ -981,15 +1127,15 @@ Trois surfaces d'outils, de la plus petite à la plus grande : `AGENTMEMORY_TOOL
|------|-------------|
| `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_save` | Sauvegarder un insight, une décision ou un pattern |
| `memory_file_history` | Observations passées sur des fichiers spécifiques |
-| `memory_patterns` | Détecter des motifs récurrents |
+| `memory_patterns` | Détecter les patterns récurrents |
| `memory_sessions` | Lister les sessions récentes |
-| `memory_smart_search` | Recherche hybride sémantique + mots-clés |
-| `memory_vision_search` | Rechercher les observations d'images |
+| `memory_smart_search` | Recherche hybride sémantique + mot-clé |
+| `memory_vision_search` | Rechercher dans les observations d'images |
| `memory_timeline` | Observations chronologiques |
-| `memory_profile` | Profil de projet (concepts, fichiers, motifs) |
-| `memory_export` | Exporter toutes les données mémoire |
+| `memory_profile` | Profil de projet (concepts, fichiers, patterns) |
+| `memory_export` | Exporter toutes les données de mémoire |
| `memory_relations` | Interroger le graphe de relations |
| `memory_commit_lookup` | Sessions derrière un commit git |
| `memory_commits` | Commits enregistrés pour une session |
@@ -1001,72 +1147,72 @@ Trois surfaces d'outils, de la plus petite à la plus grande : `AGENTMEMORY_TOOL
| Outil | Description |
|------|-------------|
-| `memory_patterns` | Détecter des motifs récurrents |
+| `memory_patterns` | Détecter les patterns 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_team_feed` | Éléments partagés récents |
| `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_snapshot_create` | Snapshot versionné par Git |
+| `memory_action_create` | Créer des tâches avec dépendances |
+| `memory_action_update` | Mettre à jour le statut d'une tâche |
+| `memory_frontier` | Tâches non bloquées classées par priorité |
+| `memory_next` | La prochaine tâche la plus importante |
+| `memory_lease` | Leases exclusifs sur les tâches (multi-agent) |
| `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_signal_send` | Messagerie inter-agent |
+| `memory_signal_read` | Lire les messages avec accusés de réception |
+| `memory_checkpoint` | Barrières de condition externe |
+| `memory_mesh_sync` | Synchronisation P2P entre instances |
+| `memory_sentinel_create` | Observateurs pilotés par événements |
+| `memory_sentinel_trigger` | Déclencher des sentinels en externe |
+| `memory_sketch_create` | Graphes de tâches éphémères |
| `memory_sketch_promote` | Promouvoir en permanent |
-| `memory_crystallize` | Compacter les chaînes d'actions |
+| `memory_crystallize` | Compacter des chaînes de tâches |
| `memory_diagnose` | Vérifications de santé |
-| `memory_heal` | Auto-correction d'état bloqué |
+| `memory_heal` | Corriger automatiquement un état bloqué |
| `memory_facet_tag` | Tags dimension:valeur |
-| `memory_facet_query` | Interroger par tags de facettes |
-| `memory_verify` | Tracer la provenance |
+| `memory_facet_query` | Interroger par tags de facette |
+| `memory_verify` | Retracer la provenance |
-### 6 Ressources · 3 Prompts · 17 Skills
+### 6 ressources · 3 prompts · 17 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://project/{name}/recent` | Observations récentes d'un projet |
-| Ressource | `agentmemory://memories/latest` | 10 dernières mémoires actives |
+| Ressource | `agentmemory://project/{name}/recent` | Observations récentes pour un projet |
+| Ressource | `agentmemory://memories/latest` | Les 10 dernières mémoires actives |
| Ressource | `agentmemory://graph/stats` | Statistiques du graphe de connaissances |
| Ressource | `agentmemory://team/{id}/profile` | Profil d'équipe partagé |
-| 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 |
+| Prompt | `recall_context` | Rechercher + retourner des messages de contexte |
+| Prompt | `session_handoff` | Données de transfert entre agents |
+| Prompt | `detect_patterns` | Analyser les patterns récurrents |
+| Skill | `/recall` | Rechercher dans 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 |
+| Skill | `/forget` | Supprimer des observations/sessions |
-Le tableau montre les quatre skills de base. Le jeu complet compte 8 skills invocables plus 7 skills de référence ; voir la section Skills natifs ci-dessus.
+Le tableau montre les quatre skills de base. Le jeu complet compte 9 skills invocables plus 8 skills de référence ; voir la section Skills natifs ci-dessus.
-### MCP autonome
+### MCP standalone
-Tourne sans le serveur complet, pour n'importe quel client MCP. L'une ou l'autre marche :
+Fonctionne sans le serveur complet, pour tout client MCP. L'une ou l'autre de ces commandes fonctionne :
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (always available)
+npx -y @agentmemory/agentmemory@latest 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) :
+La plupart des agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI) :
```json
{
"mcpServers": {
@@ -1081,7 +1227,7 @@ La plupart des agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini
}
```
-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.
+Fusionnez l'entrée `agentmemory` dans l'objet `mcpServers` existant de votre hôte plutôt que de remplacer le fichier. Pour les clients sandboxés qui ne peuvent pas atteindre le `localhost` de l'hôte, ajoutez `"AGENTMEMORY_FORCE_PROXY": "1"` au bloc env et définissez `AGENTMEMORY_URL` sur une route que le sandbox peut atteindre.
OpenCode (`opencode.json`) :
```json
@@ -1097,7 +1243,7 @@ OpenCode (`opencode.json`) :
}
```
-Copiez le fichier plugin depuis le dépôt :
+Copiez le fichier du plugin depuis le dépôt :
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
@@ -1108,46 +1254,51 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Démarre automatiquement sur le port `3113`. Flux d'observations en direct avec indicateur d'état du flux, un explorateur de sessions à deux volets (liste à côté d'un panneau de détail sticky sur écrans larges), des lignes de mémoires et de leçons qui se déploient jusqu'à l'enregistrement stocké complet, y compris le JSON brut et la provenance d'origine, un graphe de connaissances qui regroupe les nœuds par type tant que les relations sont clairsemées, le replay de session et un tableau de bord de santé.
+Démarre automatiquement sur le port `3113`. Le visualiseur charge un snapshot à la connexion (`GET /agentmemory/viewer/snapshot`) puis applique les événements de stream en direct : nouvelles mémoires, lessons, observations, entrées d'audit, changements de graphe et mises à jour de santé apparaissent sans polling ni rechargement de page. Les seules autres requêtes sont les actions que vous cliquez, les pages « load more » et les recherches. Quand le stream se coupe, le visualiseur affiche l'ancienneté de ses chiffres, se reconnecte avec un backoff et se resynchronise depuis un snapshot.
+
+- **12 onglets en quatre groupes** avec compteurs en direct, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), raccourcis clavier et un menu mobile.
+- **Memories :** recherche côté serveur, filtres par projet, agent et type, un panneau de détail avec la chaîne de versions et un diff mot à mot, liens de provenance, boutons de copie pour l'id, l'appel MCP et une commande curl, édition (une nouvelle version), forget avec confirmation, forget en masse et export JSON.
+- **Sessions :** une timeline d'observations en ligne avec entrée/sortie d'outil lisibles, filtres et pagination, et les mémoires et lessons produites par chaque session.
+- **Graph :** recherche, détail de nœud avec relations et sources, une légende qui ne repose pas uniquement sur la couleur, et des contrôles de zoom.
+- **Health :** la version en direct de `GET /agentmemory/status`. Chaque problème vient avec son correctif, plus le backend d'état, l'état de sauvegarde de l'index, la progression de la compaction de provenance du graphe et un explicatif de consolidation avec les vrais seuils.
+- Pages **Audit, Activity, Profile, Replay, Lessons, Actions et Crystals**, chacune avec un état vide qui indique ce qu'est la section, pourquoi elle est vide et la commande qui la remplit, et une infobulle `?` de glossaire sur chaque terme et chaque chiffre.
```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'`).
+Le serveur du visualiseur se lie à `127.0.0.1` par défaut et attache le secret serveur quand il relaie des requêtes vers l'API REST, donc il ne nécessite aucune configuration. L'endpoint `/agentmemory/viewer` servi par REST suit les règles normales de bearer-token et redirige les navigateurs sans token vers le port du visualiseur. Les en-têtes CSP utilisent un nonce de script par réponse et désactivent les attributs de handler inline (`script-src-attr 'none'`).
---
-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.
+Le visualiseur sur `:3113` montre ce que votre agent **a retenu**. La [console iii](https://iii.dev/docs/console) montre ce que votre agent **a fait** : chaque opération de mémoire comme une trace OpenTelemetry, chaque entrée KV éditable, chaque fonction invocable, chaque stream observable. Deux fenêtres sur la même mémoire : 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.
+Observez un `memory_smart_search` se déclencher et voyez le scan BM25 → la recherche d'embedding → la fusion RRF → le reranker sous forme de waterfall. Modifiez un timer de consolidation bloqué dans le navigateur KV. Rejouez un hook `PostToolUse` avec un payload modifié. Épinglez le stream WebSocket et regardez les observations arriver en direct.
-agentmemory livre cela gratuitement parce que chaque appel de fonction et chaque trigger passent par iii ; rien de personnalisé, rien à instrumenter.
+agentmemory fournit tout cela gratuitement car chaque appel de fonction et chaque trigger passe par iii ; rien de custom, rien à instrumenter.
-
+
- Page Workers : chaque worker connecté, y compris agentmemory lui-même, avec PID, nombre de fonctions, runtime et last-seen.
+ Page Workers : chaque worker connecté, y compris agentmemory lui-même, avec PID, nombre de fonctions, runtime et dernière activité.
-**Déjà installé.** La console est livrée avec `iii` ; pas d'installeur séparé.
+**Déjà installée.** La console est livrée avec le moteur `iii` épinglé (0.22+) ; rien de séparé à installer. Le premier lancement télécharge le binaire de la console à côté du moteur.
-**Lancer aux côtés d'agentmemory :**
+**Lancer en même temps qu'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
+agentmemory console
```
-Puis ouvrez `http://localhost:3114`. Ajoutez `--enable-flow` pour la page expérimentale de graphe d'architecture.
+Cela exécute la `iii console` du moteur épinglé contre les ports résolus par agentmemory (REST, streams, bridge) et la sert un port au-dessus du visualiseur, `http://localhost:3114` par défaut. `--console-port N` choisit un autre port ; `--port` et `--instance` sélectionnent l'instance agentmemory de la même façon que pour `stop` ; tout autre flag est transmis, par exemple `--enable-flow` pour la page expérimentale de graphe d'architecture.
-Surchargez les endpoints du moteur uniquement si vous les avez déplacés :
+La même chose à la main, utile quand `agentmemory` n'est pas dans le PATH :
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1155,79 +1306,149 @@ iii console --port 3114 \
**Ce que vous pouvez faire depuis la console :**
-| Page | Pour |
+| Page | Utilisez-la 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 sur les sessions, slots mémoire, timers de cycle de vie et index d'embeddings ; éditez 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 : voyez exactement avec quels workers, fournisseurs et ports tourne votre moteur. |
-| **Flow** | (Optionnel, `--enable-flow`) Graphe d'architecture interactif de chaque worker, trigger et flux. |
+| **Functions** | Invoquer directement n'importe quelle fonction d'agentmemory avec un payload JSON ; pratique pour tester `memory.recall`, `memory.consolidate`, `graph.query` sans câbler un client. |
+| **Triggers** | Rejouer des triggers HTTP, cron, événement et état : déclencher manuellement le cron de consolidation, réessayer une route HTTP, émettre un changement d'état. |
+| **States** | Navigateur KV avec CRUD complet sur les sessions, les slots de mémoire, les timers de cycle de vie et l'index d'embeddings ; éditez les valeurs sur place. |
+| **Streams** | Moniteur WebSocket en direct pour les écritures de mémoire, les événements de hooks et les mises à jour d'observation au fil de leur passage dans les streams iii. |
+| **Queues** | Topics de queue durables + gestion des dead-letter. Rejouer ou abandonner les jobs d'embedding / compression échoués. |
+| **Traces** | Vues waterfall / flame / répartition par service OpenTelemetry. Filtrez par `trace_id` pour voir exactement quelles fonctions, appels DB et requêtes d'embedding un seul `memory.search` a produit. |
+| **Logs** | Logs OTEL structurés, filtrés et corrélés aux IDs de trace/span. |
+| **Config** | Configuration runtime : voir exactement avec quels workers, fournisseurs et ports votre moteur fonctionne. |
+| **Flow** | (Optionnel, `--enable-flow`) Graphe d'architecture interactif de chaque worker, trigger et stream. |
-
+
- Traces : waterfall / flame / décomposition par service pour chaque opération mémoire.
+ Traces : waterfall / flame / répartition par service pour chaque opération de mémoire.
-**Les traces sont déjà actives :**
+**Les traces sont déjà activées :**
-`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.
+`iii-config.yaml` est livré avec le worker `iii-observability` activé (`exporter: memory`, `sampling_ratio: 0.1`, métriques + logs). Aucune configuration supplémentaire nécessaire ; dès qu'agentmemory démarre, chaque opération de mémoire émet un log structuré que la console peut lire, et une sur dix (`sampling_ratio: 0.1`) émet aussi un span de trace.
-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.
+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 observability 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.
+> **Important :** aucune authentification n'est appliquée sur la console elle-même ; gardez-la liée à `127.0.0.1` (le défaut) et ne l'exposez jamais publiquement.
---
-agentmemory est **déjà une instance [iii](https://iii.dev) en cours d'exécution**. Trois primitives (worker, function, trigger) composent le runtime ; l'état KV, les flux et les traces OTEL viennent des workers iii-state, iii-stream et iii-observability livrés avec iii. Vous n'avez pas installé Postgres, Redis, Express, pm2, ni Prometheus, parce qu'iii les remplace.
+agentmemory est **déjà une instance [iii](https://iii.dev) en cours d'exécution**. Trois primitives (worker, fonction, trigger) composent le runtime ; l'état KV, les streams et les traces OTEL viennent des workers iii-state, iii-stream et iii-observability livrés avec iii. Vous n'avez pas installé Postgres, Redis, Express, pm2 ou Prometheus, parce que iii les remplace.
-Cela signifie qu'une commande supplémentaire étend agentmemory d'une toute nouvelle capacité.
+Cela signifie qu'une seule commande supplémentaire étend agentmemory avec une toute nouvelle capacité.
-### Étendez agentmemory avec une seule commande
+### Étendre agentmemory avec plus de workers
-```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
-```
+Les builtins dont agentmemory a besoin sont déjà dans `iii-config.yaml` et démarrent avec lui : `iii-state` (KV), `iii-queue` (retries durables pour les abonnés aux événements), `iii-pubsub`, `iii-cron`, `iii-stream`, et `iii-observability` (traces, métriques et logs OTEL sur chaque fonction). Tout le reste depuis le [registre de workers iii](https://workers.iii.dev) se branche sur le même moteur : copiez `iii-config.yaml` vers `~/.agentmemory/iii-config.yaml` (la CLI préfère ce fichier au fichier embarqué et y rend quand même les ports et les chemins de données), ajoutez l'entrée, installez le runtime du worker une fois avec `~/.agentmemory/bin/iii update worker`, et redémarrez agentmemory.
-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.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | Ce que vous obtenez en plus d'agentmemory |
+| Worker | 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 |
+| [`database`](https://workers.iii.dev/workers/database) | Adaptateur d'état adossé à SQL quand vous dépassez les défauts KV en mémoire |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Le code issu de `memory_recall` tourne dans une VM jetable, pas dans votre shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Monter des serveurs MCP supplémentaires à côté de celui d'agentmemory, partageant le même moteur |
+
+Sur le moteur 0.22.x, gardez les noms préfixés `iii-` pour les builtins ci-dessus ; les entrées sans préfixe `http`, `state`, `queue`, `pubsub` et `cron` sont les workers du registre standalone vers lesquels agentmemory migre avec la 0.23.
+
+Registre complet : [workers.iii.dev](https://workers.iii.dev). Chaque worker qui y figure se compose via les mêmes primitives qu'utilise agentmemory, et l'agentmemory que vous avez déjà en est un.
+
+### Configuration du moteur et adresse de liaison
+
+`agentmemory start` lit la config du moteur depuis le premier fichier existant : `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` dans le répertoire courant, `~/.agentmemory/iii-config.yaml`, puis le `iii-config.yaml` embarqué. À chaque démarrage, il rend ce fichier (chemins de données, ports, backend d'état) dans `~/.agentmemory/data/iii-config.runtime.yaml` et lance le moteur avec la copie rendue, donc éditez le fichier source, pas le fichier rendu. Les valeurs `host:` du fichier source sont conservées telles qu'écrites.
+
+Le `iii-config.yaml` embarqué se lie à `127.0.0.1` intentionnellement, et ce défaut s'applique aussi à l'intérieur d'un conteneur. Une CLI démarrée dans un conteneur écoute sur le loopback du conteneur, donc les ports publiés n'atteignent rien. Pour servir une CLI conteneurisée via des ports publiés, définissez `AGENTMEMORY_III_CONFIG` vers une config qui se lie à `0.0.0.0`. Le `iii-config.docker.yaml` packagé en est une : il lie `iii-http`, `iii-stream` et le port du moteur à `0.0.0.0` et stocke l'état sous `/data`, donc montez un volume accessible en écriture là. Gardez `AGENTMEMORY_SECRET` défini, et ne publiez que les ports dont vous avez besoin, sur `127.0.0.1` ou derrière un proxy de confiance.
+
+Le `docker-compose.yml` de ce dépôt ne passe pas par la recherche de config de la CLI : il monte `iii-config.docker.yaml` sur `/app/config.yaml`, et le conteneur `iii-engine` démarre avec `--config /app/config.yaml`. Les [templates de déploiement](../deploy/) en un clic écrivent leur propre config `0.0.0.0` dans leurs points d'entrée.
+
+### Backend de stockage : fichier (défaut) vs redis
+
+`iii-state` et `iii-stream` utilisent par défaut le store KV embarqué d'iii-engine basé sur fichiers : un fichier JSON par scope, maintenu en mémoire dans le processus du moteur et réécrit sur disque à intervalle régulier. C'est le bon défaut pour une installation locale mono-utilisateur ; un daemon partagé avec plusieurs écrivains concurrents obtient de vraies écritures par clé depuis Redis à la place, au prix d'un aller-retour réseau par opération (chaque appel `state::*` se sérialise toujours sur une connexion Redis, donc cela échange le verrou du store fichier contre un socket, pas contre du parallélisme).
+
+Définissez `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) pour faire passer les deux workers à l'adaptateur `redis` intégré d'iii-engine, qui stocke chaque clé comme un champ de hash Redis (`HSET`) plutôt que de réécrire tout un scope à chaque écriture :
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` a pour défaut `file` ; le laisser non défini garde le comportement actuel inchangé, et une valeur non reconnue (autre que `file` ou `redis`) est une erreur de démarrage plutôt qu'un repli silencieux. `/agentmemory/status` et la page Health du visualiseur (la ligne State store) indiquent quel backend est actif et s'il répond, jamais l'URL.
+
+**Uniquement `redis://` en clair.** Le moteur épinglé (0.22.1) construit son client Redis sans support TLS, donc une URL `rediss://` (la plupart des offres Redis managées, comme Upstash, Redis Cloud, et ElastiCache avec chiffrement en transit, sont TLS uniquement par défaut) échoue à se connecter. La connexion n'est pas chiffrée, donc le mot de passe Redis et chaque mémoire stockée traversent le réseau en clair : pointez vers un Redis local ou sur un réseau privé de confiance. Pour tout autre Redis, exécutez un tunnel chiffré (stunnel, SSH, ou un VPN) sur l'hôte agentmemory, pour que le hop `redis://` en clair reste sur cet hôte et que la connexion amont du tunnel soit chiffrée et authentifiée. Si un mot de passe Redis contient une apostrophe, encodez-la en pourcentage (`%27`) ; le moteur développe l'URL dans sa config YAML avant de la parser.
+
+**Un serveur Redis par `--instance`.** Les préfixes de clé Redis du moteur (`state:`, `stream::`) sont fixes, donc deux instances agentmemory (`--instance 1`, `--instance 2`, ...) pointant vers la même base de données écrasent mutuellement leurs données. Un index de base de données séparé (`redis://localhost:6379/1`) garde les données stockées séparées, mais le moteur relaie les événements du visualiseur en direct sur un seul canal pub/sub Redis (`stream::events`), et le pub/sub Redis ignore l'index de base de données, donc le visualiseur de chaque instance afficherait toujours les événements en direct de l'autre. Donnez à chaque instance son propre serveur Redis (ou port) quand vous en faites tourner plus d'une.
+
+**Ce qui reste identique, et ce qui diffère.** Chaque fonctionnalité d'agentmemory fonctionne sur Redis : sessions, observations, mémoires (remember, supersede, evolve, forget), recherche et les buckets d'index, lessons, le graphe, le journal d'audit et ses scopes mensuels, export et import, suppressions de gouvernance, statut de consolidation, le snapshot du visualiseur et son stream en direct, et le moniteur de santé. Le moteur stocke chaque scope comme un seul hash Redis (`HSET`/`HGET`/`HGETALL`) et déclenche les mêmes triggers d'état que le store fichier. Trois différences du moteur sont gérées à l'intérieur d'agentmemory :
+
+- Redis retourne les enregistrements d'un scope sans ordre fixe. agentmemory les trie du plus ancien au plus récent (par l'heure de création dans l'id de l'enregistrement, puis son timestamp) pour que les listes, la pagination et les chunks d'export reviennent dans le même ordre que sur le store fichier.
+- Le moteur applique les mises à jour partielles sur Redis dans un script Lua qui transforme les tableaux vides en objets vides. agentmemory applique lui-même ces mises à jour (lire, modifier, écrire sous un verrou par clé) sur Redis, pour que des champs comme `tags: []` restent des tableaux.
+- La vérification du journal d'audit legacy lit l'ancien scope depuis Redis au lieu de chercher le fichier du store fichier sur disque.
-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.
+Une différence demande votre attention : **après un redémarrage de Redis, le moteur arrête de relayer les événements en direct** vers le visualiseur jusqu'à ce qu'agentmemory redémarre. Les données sont toujours sauvegardées et lues normalement. Le moniteur de santé envoie un événement de test via Redis toutes les 30 secondes ; quand il ne revient pas, `/agentmemory/status` et la page Health du visualiseur affichent « Les mises à jour en direct n'atteignent pas le visualiseur » avec le correctif : redémarrer agentmemory. Si Redis est en panne, le rapport de statut affiche « Le state store ne répond pas » et comment le vérifier (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Lister un très grand scope lit tout le hash en un seul `HGETALL`, le même coût que le store fichier le gardant en mémoire.
-### Ce qu'iii remplace
+**Réglages Redis recommandés.** La politique de snapshot par défaut `save 3600 1 300 100 60 10000` peut perdre des minutes d'écritures en cas de crash, pire que la fenêtre de flush de 5s du store fichier. Définissez `appendonly yes` pour tout ce que vous regretteriez de perdre. Définissez `maxmemory-policy noeviction` ; `allkeys-lru` ou similaire abandonne silencieusement des mémoires une fois que Redis atteint sa limite mémoire.
+
+Un démarrage natif (non-Docker), et chaque [template de déploiement](../deploy/) en un clic (ils remplacent le `iii-config.yaml` embarqué et démarrent nativement), lisent `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` et les rendent dans la `iii-config` lancée. L'URL elle-même n'est jamais écrite dans ce fichier rendu, seulement une référence `${AGENTMEMORY_REDIS_URL}` que le processus moteur développe depuis son propre environnement au démarrage. Seul le chemin Docker Compose de ce dépôt (`AGENTMEMORY_USE_DOCKER=1`, ou la reprise d'un moteur déjà démarré ainsi) monte `iii-config.docker.yaml` en lecture seule et ne rend jamais ; `agentmemory start` avertit quand il détecte cette combinaison. Changez ce fichier à la main, en suivant la même forme `name: redis` / `config: redis_url: ...` montrée dans la documentation des workers [iii-state](https://workers.iii.dev/workers/iii-state) et [iii-stream](https://workers.iii.dev/workers/iii-stream), et pointez `redis_url` vers un Redis accessible depuis le conteneur. `docker-compose.yml` transmet `AGENTMEMORY_REDIS_URL` au conteneur du moteur, donc `redis_url: '${AGENTMEMORY_REDIS_URL}'` y fonctionne et garde l'URL hors du fichier monté.
+
+La config rendue garde l'URL hors de `~/.agentmemory/data/iii-config.runtime.yaml`, mais le worker de configuration du moteur lui-même persiste quand même la valeur *développée* dans `~/.agentmemory/config/iii-state.yaml` et `iii-stream.yaml` une fois démarré (l'expansion `${VAR}` d'iii-engine se produit avant que ce worker ne stocke sa graine, et il stocke la valeur résolue, pas la référence). Traitez ce répertoire comme contenant une credential : `chmod 700 ~/.agentmemory` sur tout hôte partagé, et préférez un utilisateur ACL Redis scopé à ce dont agentmemory a besoin plutôt que les credentials admin de la base de données.
+
+**La migration n'est pas automatique.** Changer `AGENTMEMORY_STATE_BACKEND` démarre d'un store vide des deux côtés ; rien ne copie les données existantes du fichier vers Redis ou inversement. Exportez depuis le backend que vous quittez et importez dans celui vers lequel vous allez. Ceci fonctionne identiquement sous bash et zsh (y compris `bash -u`). Un tableau comme `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` ne fonctionne pas : zsh garde l'en-tête comme un seul mot malformé là où bash le scinde en deux, donc les deux requêtes reçoivent 401 chaque fois que `AGENTMEMORY_SECRET` est défini :
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` accepte aussi `?maxSessions=` et `?offset=` pour fragmenter un gros corpus sur plusieurs appels ; `strategy` à l'import vaut `merge` (sûr par défaut), `replace`, ou `skip`.
+
+### Ce que 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 |
+| pm2 / systemd | Supervision des workers du moteur iii |
| Prometheus / Grafana | iii OTEL + moniteur de santé |
-| Systèmes de plugins personnalisés | `iii worker add ` |
+| Systèmes de plugins custom | `iii worker add ` |
-**182 fichiers sources · ~41 600 LOC · 1 619 tests · 264 fonctions · 50 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
+**225 fichiers sources · ~54,000 LOC · 2,600+ tests · 312 fonctions · 66 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
---
@@ -1235,22 +1456,22 @@ Registre complet : [workers.iii.dev](https://workers.iii.dev). Chaque worker là
### 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.
+agentmemory auto-détecte les fournisseurs depuis votre environnement. Un fournisseur rend disponibles les opérations adossées à un LLM, mais la seule configuration d'un fournisseur n'active pas la compression d'observation rédigée par LLM. Ce chemin requiert à la fois un fournisseur et `AGENTMEMORY_AUTO_COMPRESS=true`.
| 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 |
+| **No-op (défaut)** | Aucune config nécessaire | La compression/synthèse adossée à un LLM est désactivée. La compression synthétique et le recall BM25 fonctionnent toujours. Voir `AGENTMEMORY_ALLOW_AGENT_SDK` ci-dessous si vous comptiez sur le repli par abonnement Claude. |
+| API Anthropic | `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 |
-| OpenAI API | `OPENAI_API_KEY` | Défaut `gpt-5.6-luna`, surcharge avec `OPENAI_MODEL` |
-| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ou `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Tout ce qui est compatible avec l'API OpenAI. Coût nul, tourne sur votre matériel. Voir [Modèles locaux](#modèles-locaux-ollama--lm-studio--vllm) ci-dessous. |
-| Fallback abonnement Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in seulement. Engendre des sessions `@anthropic-ai/claude-agent-sdk` ; il provoquait une récursion non bornée du Stop-hook, il n'est donc plus l'option par défaut. |
+| API OpenAI | `OPENAI_API_KEY` | Défaut `gpt-5.6-luna`, remplacer avec `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ou `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Tout ce qui est compatible avec l'API OpenAI. Coût nul, tourne sur votre matériel. Voir [Modèles locaux](#local-models-ollama--lm-studio--vllm) ci-dessous. |
+| Repli par abonnement Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in uniquement. Lance des sessions `@anthropic-ai/claude-agent-sdk` ; cela provoquait auparavant une récursion illimitée du hook Stop, donc ce n'est plus le défaut. |
### Modèles locaux (Ollama / LM Studio / vLLM)
-agentmemory parle à tout serveur compatible avec l'API OpenAI, donc tout ce qui expose `/v1/chat/completions` fonctionne sans changement de code. Pas de clés payantes, pas de cloud, pas de limites de débit ; tourne entièrement sur votre matériel.
+agentmemory parle à n'importe quel serveur compatible API OpenAI, donc tout ce qui expose `/v1/chat/completions` fonctionne sans changement de code. Pas de clés payantes, pas de cloud, pas de limites de débit ; tourne entièrement sur votre matériel.
**Ollama** (port par défaut `11434`) :
@@ -1277,48 +1498,48 @@ OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
-**vLLM / llama.cpp / Text Generation Inference** : même forme. Pointez `OPENAI_BASE_URL` vers l'URL que votre serveur expose et définissez `OPENAI_MODEL` sur un nom que votre serveur acceptera.
+**vLLM / llama.cpp / Text Generation Inference** : même forme. Pointez `OPENAI_BASE_URL` vers l'URL exposée par votre serveur et définissez `OPENAI_MODEL` avec un nom que votre serveur acceptera.
-**Choix de modèles pour le travail mémoire** : la compression et le résumé sont des tâches courtes (<2K tokens en entrée, <500 tokens en sortie) où un modèle instruct 7B suffit largement. Recommandations :
+**Choix de modèle pour le travail de mémoire** : la compression et la synthèse sont des tâches courtes (<2K tokens en entrée, <500 tokens en sortie) où un modèle instruct de 7B suffit largement. Recommandations :
| Modèle | Taille | Pourquoi |
|-------|------|-----|
-| `qwen3:8b` | ~5.2 GB | Défaut équilibré sur une machine 16 GB ; solide en extraction et sur le texte façonné par les outils |
-| `qwen3:4b` | ~2.6 GB | Plus petite option raisonnable ; correcte pour la compression, plus faible pour l'extraction de graphe |
-| `qwen3-coder:30b` | ~19 GB | Meilleur choix local pour les sessions code-shaped (MoE 30B, 3.3B actifs) sur du matériel 24-32 GB |
-| `gpt-oss:20b` | ~14 GB | Modèle généraliste solide qui tient dans 16 GB de RAM |
-| `deepseek-r1:8b` | ~5.2 GB | Distillation raisonnement ; plus lent mais extractions plus propres |
+| `qwen3:8b` | ~5.2 Go | Défaut équilibré sur une machine à 16 Go ; solide en extraction et en texte orienté outils |
+| `qwen3:4b` | ~2.6 Go | Plus petite option raisonnable ; bien pour la compression, plus faible pour l'extraction de graphe |
+| `qwen3-coder:30b` | ~19 Go | Meilleur choix local pour les sessions orientées code (30B MoE, 3.3B actifs) sur du matériel 24-32 Go |
+| `gpt-oss:20b` | ~14 Go | Modèle général solide qui tient dans 16 Go de RAM |
+| `deepseek-r1:8b` | ~5.2 Go | Distillation de raisonnement ; plus lent mais extractions plus propres |
-Les modèles Qwen 3 réfléchissent par défaut et peuvent brûler tout le budget de tokens en raisonnement avant la moindre sortie. Définissez `AGENTMEMORY_LLM_NOTHINK=1` pour ajouter `/no_think` aux prompts d'extraction de graphe, et augmentez `MAX_TOKENS` (16384 fonctionne) si les extractions reviennent vides.
+Les modèles Qwen 3 réfléchissent par défaut et peuvent consommer tout le budget de tokens en raisonnement avant toute sortie. Définissez `AGENTMEMORY_LLM_NOTHINK=1` pour ajouter `/no_think` aux prompts d'extraction de graphe, et augmentez `MAX_TOKENS` (16384 fonctionne) si les extractions reviennent vides.
-Les modèles de classe raisonnement (style `o1` avec blocs ``) peuvent renvoyer un `content` vide avec un champ `reasoning` que votre serveur local peut ne pas faire remonter. Si les extractions reviennent vierges, passez d'abord à un modèle sans raisonnement. La variable d'env `OPENAI_REASONING_EFFORT=none` peut aussi désactiver la réflexion sur les modèles pensants d'Ollama Cloud qui reproduisent le schéma de raisonnement OpenAI.
+Les modèles de la classe raisonnement (style `o1` avec blocs ``) peuvent retourner un `content` vide avec un champ `reasoning` que votre serveur local peut ne pas exposer. Si les extractions reviennent vides, basculez d'abord vers un modèle non-raisonnement. La variable d'env `OPENAI_REASONING_EFFORT=none` peut aussi désactiver le thinking sur les modèles de réflexion d'Ollama Cloud qui reflètent le schéma de raisonnement OpenAI.
-Les embeddings locaux sont livrés d'origine via `@huggingface/transformers` : `EMBEDDING_PROVIDER=local` (par défaut) vous donne `Xenova/all-MiniLM-L6-v2` (384 dimensions) entièrement sur l'appareil. Aucune config supplémentaire nécessaire.
+Les embeddings locaux sont livrés comme dépendance optionnelle mais ne sont pas activés par défaut. Définissez `EMBEDDING_PROVIDER=local` pour opter pour `Xenova/all-MiniLM-L6-v2` (384 dims). La première requête d'embedding télécharge le modèle ; l'inférence se fait ensuite sur l'appareil. Sans ce réglage ni une clé d'embedding distante, les vecteurs restent désactivés, `mem::search` utilise BM25, et `smart-search` peut toujours ajouter des correspondances de graphe existantes.
-### Sélection de modèle attentive au coût
+### Sélection de modèle sensible 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.
+Quand la compression en arrière-plan rédigée par LLM est activée avec à la fois un fournisseur et `AGENTMEMORY_AUTO_COMPRESS=true`, elle tourne sur chaque observation, donc le choix du modèle change significativement 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 |
+| Palier | Modèle | Entrée / 1M | Sortie / 1M | Coût pour les 35h capturées | Notes |
|------|-------|------------|-------------|---------------------------|-------|
-| Recommandé | `deepseek/deepseek-v4-flash-0731` | 0,07 $ | 0,14 $ | ~0,07 $ (est.) | Dernier DeepSeek ; choix recommandé le moins cher pour les charges de compression. |
-| 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é | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Solide raisonnement code si vos sessions sont fortement code-shaped. |
-| Premium | `anthropic/claude-sonnet-5` | 3,00 $ | 15,00 $ | ~5,02 $ (est.) | Même prix catalogue que le run Sonnet 4.6 mesuré ; tarif de lancement 2 $/10 $ jusqu'au 2026-08-31. |
-| Premium | `openai/gpt-5.6-sol` | 5,00 $ | 30,00 $ | ~9 $ (est.) | Niveau flagship ; coûteux pour du travail de fond permanent. |
-| À éviter | `anthropic/claude-opus-5` | 5,00 $ | 25,00 $ | ~8,40 $ (est.) | Modèle classe flagship ; surcoût pour de la compression. |
+| Recommandé | `deepseek/deepseek-v4-flash-0731` | 0.07 $ | 0.14 $ | ~0.07 $ (est.) | DeepSeek le plus récent ; choix recommandé le moins cher pour les workloads de compression. |
+| Recommandé | `deepseek/deepseek-v4-pro` | 0.435 $ | 0.87 $ | ~0.46 $ | Qualité solide de compression + synthèse à ~10× moins cher que Sonnet. |
+| Recommandé | `qwen/qwen3-coder` | 0.45 $ | 1.80 $ | ~0.55 $ | Raisonnement code solide si vos sessions sont fortement orientées code. |
+| Premium | `anthropic/claude-sonnet-5` | 3.00 $ | 15.00 $ | ~5.02 $ (est.) | Même tarif catalogue que le run Sonnet 4.6 mesuré ; tarif de lancement 2 $/10 $ jusqu'au 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | 5.00 $ | 30.00 $ | ~9 $ (est.) | Palier flagship ; coûteux pour du travail en arrière-plan permanent. |
+| À éviter | `anthropic/claude-opus-5` | 5.00 $ | 25.00 $ | ~8.40 $ (est.) | Modèle de classe flagship ; surdimensionné pour la compression. |
-Les lignes mesurées viennent du run capturé ; les lignes (est.) appliquent le même mix de tokens au prix catalogue de chaque modèle.
+Les lignes mesurées viennent du run capturé ; les lignes (est.) extrapolent le même mix de tokens selon le tarif catalogue de chaque modèle.
-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é.
+agentmemory affiche un avertissement runtime quand `OPENROUTER_MODEL` correspond à un pattern de palier premium. Définissez `AGENTMEMORY_SUPPRESS_COST_WARNING=1` pour le faire taire une fois votre choix fait en connaissance de cause.
-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 Flash / V4 Pro / Qwen3-Coder se situent à l'erreur d'arrondi près de Sonnet sur cette tâche tout en coûtant 10-70× moins. Réservez les modèles premium aux requêtes que vous lisez directement.
+Compromis qualité/coût pour le travail de mémoire : la compression est une tâche de synthèse avec des barres de qualité relativement souples (l'agent relit le résumé, pas l'utilisateur). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder atterrissent à la marge d'erreur de Sonnet sur cette tâche en coûtant 10-70× moins. Gardez les modèles de palier premium pour les requêtes que vous lisez directement.
-Sources : [tarification OpenRouter pour Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [notes de prix DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+Sources : [tarif OpenRouter pour Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [notes de tarification DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
-### Mémoire multi-agents (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+### Mémoire multi-agent (`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.
+Dans les configurations multi-agents où plusieurs rôles partagent un seul serveur agentmemory (architecte / développeur / reviewer / chercheur / agent-support), `AGENT_ID` marque chaque écriture avec le rôle qui l'a faite. `AGENTMEMORY_AGENT_SCOPE` contrôle si le recall filtre par ce tag.
```env
TEAM_ID=company
@@ -1329,31 +1550,35 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
Deux modes :
-| Mode | Marquer les écritures | Filtrer le recall | Quand l'utiliser |
+| Mode | Marque les écritures | Filtre 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. |
+| `shared` (défaut) | oui | non | Contexte inter-agent avec piste d'audit. L'architecte peut voir ce que le développeur a noté, mais chaque ligne enregistre qui l'a dit. |
+| `isolated` | oui | oui | Séparation stricte. L'architecte ne voit jamais les observations / mémoires / sessions du développeur. |
-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 marqué quand `AGENT_ID` est défini : `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Le rôle circule depuis `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=` 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.
+Ce qui est filtré en mode isolé : `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Chaque endpoint accepte `?agentId=` pour surcharger par requête, et `?agentId=*` pour sortir complètement du scope de l'env. `/memories` accepte aussi `?includeOrphans=true` pour faire apparaître les mémoires pré-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. L'outil MCP `memory_save` expose le même champ `agentId`, le serveur stdio autonome transmet à la fois `agentId` et `project`, et les mémoires sauvegardées portent `agentId` dans l'index de recherche, si bien que la recherche scopée par agent couvre les mémoires autant que les observations.
+Surcharge par appel au niveau SDK / REST : chaque endpoint de mutation (`/session/start`, `/remember`) accepte un champ `agentId` dans le corps de requête qui prime sur l'env. Utile pour les runtimes qui font passer plusieurs rôles par un seul processus serveur. L'outil MCP `memory_save` expose le même champ `agentId`, le serveur stdio standalone transmet à la fois `agentId` et `project`, et les mémoires sauvegardées portent `agentId` dans l'index de recherche, donc la recherche scopée par agent couvre les mémoires aussi bien que les observations.
-Quand `AGENT_ID` n'est pas défini, la mémoire reste non scopée (comportement legacy, sans tags ni filtres).
+Quand `AGENT_ID` n'est pas défini, la mémoire reste non scopée (comportement legacy, pas de tags, pas de 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.
+agentmemory + iii-engine lient quatre ports par défaut. Si un redémarrage échoue avec `port in use`, ce tableau vous indique quel processus chercher.
-| Port | Processus | Usage | Surcharge env |
+| Port | Processus | Usage | Surcharge via 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`) |
+| `3112` | iii-engine | Worker interne de streams (consommé par agentmemory + le visualiseur) | `III_STREAM_PORT` (préféré) ou `III_STREAMS_PORT` (legacy) |
+| `3113` | agentmemory | Visualiseur temps réel (`http://localhost:3113`) | `III_VIEWER_PORT` ou `AGENTMEMORY_VIEWER_URL` pour l'URL rapportée |
+| `49134` | iii-engine | WebSocket ; les workers s'y enregistrent, la télémétrie OTel y circule | `III_ENGINE_PORT` ou `III_ENGINE_URL` |
+
+`--port ` change l'ancre REST et dérive streams `N+1`, visualiseur `N+2`, et WebSocket du moteur `N+46023` uniquement là où le port ou l'URL explicite correspondant ci-dessus n'est pas défini. Cela ne crée pas un namespace de cycle de vie isolé. Utilisez `--instance 1` pour un second daemon ; il utilise l'ancre 3211, par défaut `3211/3212/3213/49234`, et reçoit un répertoire de données et de cycle de vie `instance-1` séparé. Les instances 1 à 50 suivent le même modèle.
+
+Le moteur épinglé démarre avec `--no-update-check` (aucune recherche de mise à jour ou d'avis de sécurité contre GitHub au démarrage) et avec la télémétrie d'usage anonyme d'iii désactivée : agentmemory définit `III_TELEMETRY_ENABLED=false` pour le moteur qu'il lance sauf si vous exportez la variable vous-même, et le fichier compose embarqué fait de même.
-Nettoyage de processus zombies quand des ports restent occupés après un crash :
+Nettoyage des processus périmés quand les ports restent liés après une exécution plantée :
```bash
# macOS / Linux — find whatever is on each port and kill it
@@ -1366,33 +1591,35 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` réclame proprement à la fois le worker et le pidfile du moteur en arrêt gracieux. En mode Docker, il ne démonte que les services compose propres à agentmemory et réclame le worker natif avant le démontage Docker ; la CLI refuse aussi d'adopter ou de signaler comme moteur natif les détenteurs de ports Docker ou VM (backend Docker, vpnkit, colima) sauf si `--force` est passé. Le nettoyage manuel ci-dessus n'est nécessaire que pour le cas post-crash où aucun pidfile n'est laissé en place.
+`agentmemory stop` récupère proprement à la fois le worker et le pidfile du moteur lors d'un arrêt natif propre. En mode Docker, il vide le worker natif, arrête exactement le conteneur du moteur validé, et préserve à la fois le conteneur et son montage `/data` pour un redémarrage sans perte ; le prochain démarrage valide et reprend ce même conteneur. La désinstallation adossée à Docker requiert `agentmemory remove --keep-data` : elle supprime les fichiers partagés gérés par agentmemory tout en préservant le conteneur validé, son montage de données, et l'enregistrement de cycle de vie nécessaire pour les récupérer. La suppression destructive des données Docker est intentionnellement laissée à l'opérateur après une sauvegarde. La CLI refuse aussi d'adopter ou de signaler les détenteurs de port Docker ou VM (backend Docker, vpnkit, colima) comme le moteur natif sauf si `--force` est passé. Le nettoyage manuel ci-dessus ne concerne que le cas post-crash où aucun des deux pidfiles n'a été laissé.
-### Fichier de configuration
+### Fichier de config
-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.
+Placez la configuration runtime d'agentmemory dans `~/.agentmemory/.env` plutôt que d'exporter des variables dans chaque shell. Si le visualiseur affiche un indice de setup comme `export ANTHROPIC_API_KEY=...`, copiez-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.
+Les variables d'environnement du processus fonctionnent toujours et priment sur les valeurs du fichier.
-Sur Windows, le même fichier se trouve dans `%USERPROFILE%\.agentmemory\.env` :
+Sur Windows, le même fichier se trouve à `%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 :
+Pour tester avec un abonnement Claude Code Pro/Max plutôt qu'une clé API, optez-y 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 :
+La compression d'observation rédigée par LLM requiert les deux lignes : l'accès à un fournisseur LLM (y compris ce repli d'abonnement explicite) et `AGENTMEMORY_AUTO_COMPRESS=true`. Un fournisseur seul laisse en place le chemin de compression synthétique par défaut.
+
+La consolidation (nœuds de graphe, lessons, crystals) est activée par défaut dès qu'un fournisseur LLM est configuré. Désactivez-la explicitement avec `CONSOLIDATION_ENABLED=false` si vous voulez un fonctionnement sans LLM. L'extraction de graphe est un flag séparé :
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Variables d'environnement
@@ -1434,13 +1661,15 @@ Créez `~/.agentmemory/.env` :
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1458,14 +1687,20 @@ Créez `~/.agentmemory/.env` :
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1513,6 +1748,36 @@ Créez `~/.agentmemory/.env` :
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1526,7 +1791,19 @@ Créez `~/.agentmemory/.env` :
-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 ` lorsque `AGENTMEMORY_SECRET` est défini, et les endpoints de mesh sync exigent `AGENTMEMORY_SECRET` sur les deux pairs.
+138 endpoints sur le port `3111`. L'API REST se lie à `127.0.0.1` par défaut. Les endpoints protégés requièrent `Authorization: Bearer `, et les endpoints de mesh sync requièrent un `AGENTMEMORY_SECRET` explicitement défini sur les deux pairs.
+
+**L'authentification est activée par défaut.** Quand `AGENTMEMORY_SECRET` n'est pas défini (dans le shell ou dans `~/.agentmemory/.env`), le serveur génère un secret aléatoire au premier démarrage et le stocke dans `~/.agentmemory/secret` avec le mode `0600`. Chaque client embarqué le lit depuis là quand il parle à un serveur local : la CLI, le visualiseur, les hooks sous `plugin/scripts`, le serveur MCP et le shim `@agentmemory/mcp`, les configs écrites par `agentmemory connect`, et les intégrations embarquées OpenCode, Pi, OpenClaw, Hermes et filesystem-watcher. Le secret stocké n'est envoyé qu'à des URLs loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explicite prime toujours, et les clients distants en ont toujours besoin. Docker et les points d'entrée `deploy/` génèrent et exportent déjà leur propre secret. Pour appeler l'API à la main :
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Règles de requête pour les écritures.** Les requêtes `POST`, `PUT`, `PATCH` et `DELETE` vers l'API REST et le visualiseur doivent envoyer `Content-Type: application/json` (un paramètre `charset` est acceptable) chaque fois qu'elles portent un corps, et un en-tête `Origin`, quand présent, doit être une origine loopback pour le port REST ou visualiseur configuré, ou être listé dans `VIEWER_ALLOWED_ORIGINS` (séparé par des virgules, par ex. `https://memory.example.com`). Les clients qui n'envoient aucun en-tête `Origin` (CLI, hooks, MCP, curl, serveur-à-serveur) ne sont pas affectés. Le visualiseur accepte aussi sa propre origine.
+
+**Chemins de fichiers.** Les endpoints qui lisent ou écrivent des fichiers (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) n'acceptent que des chemins sous `~/.agentmemory`, le répertoire de données de l'instance, ou un répertoire listé dans `AGENTMEMORY_IMPORT_ROOT` (séparez-en plusieurs avec `:`, ou `;` sous Windows). `/replay/import-jsonl` accepte aussi son défaut `~/.claude/projects`. `/obsidian/export` reste à l'intérieur de `AGENTMEMORY_EXPORT_ROOT` et `/migrate` à l'intérieur de `~/.agentmemory`. Les symlinks sont résolus avant chaque vérification.
+
+**Épuration des secrets.** Les clés API, tokens bearer, blocs de clés privées PEM et credentials embarqués dans des URLs (`scheme://user:password@host`) sont expurgés avant que le texte ne soit stocké, sur chaque chemin d'écriture : observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, replay jsonl, mesh sync, partages d'équipe, sortie de compression et de résumé, crystals et nœuds de graphe.
Endpoints clés
@@ -1534,18 +1811,24 @@ Créez `~/.agentmemory/.env` :
| Méthode | Chemin | Description |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Vérification de santé (toujours publique) |
+| `GET` | `/agentmemory/status` | Ce qui ne va pas et comment le corriger (HTML pour les navigateurs, JSON sinon) |
+| `GET` | `/agentmemory/viewer/snapshot` | Tout ce que le visualiseur affiche, en une seule réponse |
| `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/observe` | Capturer une observation (voir la livraison de capture ci-dessous) |
+| `GET` | `/agentmemory/capture` | Boîte de réception de capture, dead letters et spool hors ligne |
+| `POST` | `/agentmemory/capture/retry` | Réessayer les captures en dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Envoyer le spool hors ligne local maintenant |
| `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/context` | Générer le 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/graph/query` | Requête de graphe de connaissances |
+| `POST` | `/agentmemory/graph/compact` | Réduire la provenance de graphe surdimensionnée |
| `POST` | `/agentmemory/team/share` | Partager avec l'équipe |
| `GET` | `/agentmemory/audit` | Piste d'audit |
@@ -1553,6 +1836,35 @@ Liste complète des endpoints : [`src/triggers/api.ts`](../src/triggers/api.ts)
+**Livraison de capture.** Les hooks envoient chaque observation une fois à `POST /agentmemory/observe` avec un `eventId`. C'est l'id propre de l'hôte pour l'appel quand le payload en a un (par exemple le `tool_use_id` de Claude Code), sinon un hash de la session, du type de hook, du nom d'outil, de l'entrée, de la sortie et du timestamp de l'hôte. Le serveur écrit l'événement dans une boîte de réception de capture du state store, stocke l'observation, puis retire l'entrée de la boîte de réception. Le code de statut indique ce qui s'est passé :
+
+| Statut | Champ `status` | Signification |
+|---|---|---|
+| `201` | `accepted` | Stocké. `observationId` est la nouvelle observation. |
+| `202` | `accepted` (`state: "retrying"`) | Accepté, mais le stockage a échoué. Le serveur le réessaie, aussi après un redémarrage. |
+| `200` | `duplicate` | Cet `eventId` a déjà été accepté. `observationId` est l'observation existante ; rien de nouveau n'est stocké. |
+| `400` / `422` | `rejected` | Payload invalide, ou le stockage a échoué définitivement (l'événement est conservé comme dead letter). |
+| `503` | `rejected` (`retryable: true`) | La boîte de réception est pleine (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Les hooks mettent l'événement en spool et l'envoient plus tard. |
+
+Les événements échoués sont réessayés toutes les `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) avec un backoff qui double, jusqu'à `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Les événements qui échouent encore restent dans la boîte de réception comme dead letters, sont listés sur `/agentmemory/status` et la page Health du visualiseur, et peuvent être réessayés avec `POST /agentmemory/capture/retry` (`{"eventId": "..."}` ou `{"all": true}`). Les ids d'événements acceptés sont mémorisés pendant `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 heures, au plus `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), donc un hook rejoué après un timeout ou un redémarrage est stocké une fois, tandis que deux appels d'outil séparés avec leurs propres ids d'hôte sont stockés deux fois même quand leur contenu est identique. Quand une observation est supprimée (forget, suppression de session, éviction, oubli automatique ou un import qui remplace le store), son événement est marqué comme supprimé avant que l'observation ne soit retirée, donc un replay de cet événement dans la même fenêtre reçoit une réponse de doublon et ne stocke rien. Le state store écrit sur disque toutes les 2 secondes, donc un événement ayant reçu une réponse peut encore n'exister qu'en mémoire pendant un instant. Pour couvrir cela, chaque réponse `2xx` porte aussi le `bootId` du serveur (nouveau à chaque démarrage), `acceptedAt` et `durableAfterMs` (l'intervalle de sauvegarde plus 1.5 s sur le store fichier, 1.5 s sur redis, où la persistance est le réglage de l'opérateur). Les hooks gardent l'événement dans le spool local jusqu'à ce que cette fenêtre soit passée et le suppriment lors d'un appel ultérieur sans nouvelle requête. Si le `bootId` a changé entre-temps, le serveur a redémarré, donc le hook renvoie l'événement avec le même `eventId` ; un événement qui a bien atteint le disque n'est pas stocké deux fois. Le serveur envoie aussi lui-même de tels événements au démarrage et à chaque intervalle de réessai, donc un redémarrage ne perd rien même si aucun hook ne tourne ensuite. Les anciens hooks ignorent les champs supplémentaires, et les nouveaux hooks contre un ancien serveur abandonnent l'événement sur `2xx` comme avant.
+
+Quand le serveur est en panne, ne répond pas à temps ou retourne un 5xx, le hook ajoute l'observation à un fichier de spool local, `/capture-spool/-.jsonl` (surchargez le dossier avec `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Le fichier est privé à votre utilisateur (mode 600), les secrets sont expurgés de la même façon que le serveur les expurge, il contient au plus `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 Mio) et abandonne les entrées plus anciennes que `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Quand il est plein, les nouvelles entrées sont abandonnées et comptées, et `/agentmemory/status` le rapporte. Le hook sort toujours avec 0 dans sa limite de temps et n'ajoute aucune requête quand le serveur est sain. Le spool est envoyé au démarrage suivant et par le premier hook qui atteint à nouveau le serveur, dans un processus en arrière-plan pour que l'agent n'attende pas. Les ids d'événements rendent cela sûr : une observation qui est bien arrivée avant un timeout n'est pas stockée deux fois. `npx @agentmemory/agentmemory capture` affiche le spool et la boîte de réception du serveur, `--drain` envoie le spool maintenant, et `GET /agentmemory/capture` retourne la même chose en JSON. Définissez `AGENTMEMORY_CAPTURE_SPOOL=false` pour désactiver le spool.
+
+**Compaction de la provenance de graphe.** Chaque nœud et arête du graphe de connaissances garde les ids des 32 observations les plus récentes dont il provient. Les stores écrits avant ce plafond peuvent contenir des milliers d'ids par nœud chaud, ce qui ralentit la recherche de graphe et le visualiseur ou fait planter le worker. agentmemory corrige cela de lui-même : au premier démarrage après une mise à niveau, il réduit chaque nœud, arête, arête supersédée (l'historique temporel du graphe) et le snapshot mis en cache au plafond en arrière-plan, en petites tranches avec une pause entre elles, pour que la recherche, la capture et le visualiseur continuent de fonctionner. Il sauvegarde sa progression, reprend après un redémarrage et ne se relance jamais une fois terminé. `/agentmemory/status` et la page Health du visualiseur l'affichent comme en attente, en cours (avec le scope et la position actuels), terminé ou échoué. Définissez `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` pour le désactiver.
+
+Pour le lancer à la main, appelez `POST /agentmemory/graph/compact`. Il parcourt les index de nom et de clé d'arête plutôt que de lister chaque nœud et arête, et peut être relancé en toute sécurité. Quand il réduit des ids, il écrit une entrée d'audit `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Sur un gros store, ou quand l'appel retourne 504, lancez-le en tranches. Envoyez `scope` (`nodes`, `edges` ou `history`), `offset` et `limit`, puis rappelez avec le `nextOffset` retourné jusqu'à ce qu'il soit `null`. Faites cela pour `nodes`, `edges` et `history`, et terminez par un seul appel `{"scope":"snapshot"}`, car une exécution en tranches ne touche pas le snapshot mis en cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1560,11 +1872,11 @@ Liste complète des endpoints : [`src/triggers/api.ts`](../src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**Prérequis :** Node.js >= 20, [iii-engine](https://iii.dev/docs) ou Docker
+**Prérequis :** Node.js >= 20 avec npm/npx ; [iii-engine](https://iii.dev/docs) v0.22.1 ou Docker. L'installation automatique du moteur sur macOS/Linux nécessite aussi `curl`, un `sh` POSIX, et `tar` ; Windows natif utilise l'`iii.exe` épinglé manuel, WSL2, ou Docker Desktop.
diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.md
new file mode 100644
index 0000000000..cbfcc48b0d
--- /dev/null
+++ b/READMEs/README.he-IL.md
@@ -0,0 +1,1876 @@
+
+
+
+
+
+
+ סוכן הקוד שלך זוכר הכול. אין יותר הסברים חזרתיים.
+ בנוי על מנוע iii
+
+ זיכרון מתמשך עבור Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, וכל לקוח MCP.
+
+
+---
+
+## התקנה
+
+דרישות:
+
+- Node.js 20 ואילך עם npm ו-npx (`node -v`, `npm -v`, ו-`npx -v`).
+- התקנה אוטומטית של iii-engine ב-macOS/Linux דורשת גם `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`. תמונות מינימליות כמו `node:20-slim` לא בהכרח כוללות אותן.
+- Windows מקורי מחייב התקנה ידנית של `iii.exe` בגרסה הנעוצה v0.22.1 של iii-engine. WSL2 או Docker Desktop הם המסלולים הנתמכים האחרים.
+
+פקודת ההתקנה הראשונית הקנונית:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+ההרצה הראשונה היא הגדרה אינטראקטיבית: בוחרים את הסוכנים לחיווט (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), בוחרים ספק LLM או נשארים ללא מפתח, והיא מזרעת את התצורה, מפעילה את שרת הזיכרון ואת iii-engine הנעוץ שלו, ומציעה להתקין גלובלית כך שהפקודה החשופה `agentmemory` תעבוד בכל מקום לאחר מכן. הדגל `-y` מאשר את הבקשה של npx להתקין את החבילה, ו-`@latest` מונע שימוש בגרסה ישנה שמורה במטמון. ספק מאפשר יכולות LLM, אך דחיסת תצפיות בכתיבת LLM מתחילה רק כש-`AGENTMEMORY_AUTO_COMPRESS=true` מוגדר גם כן.
+
+מצב ללא מפתח (keyless) משבית embeddings וקטוריים. `memory_recall` (נתיב `mem::search`) משתמש ב-BM25, בעוד ש-`memory_smart_search` יכול גם לשלב התאמות מבניות מגרף כשנתוני גרף קיימים כבר. לשליפה סמנטית חינמית במכשיר עצמו, יש להגדיר `EMBEDDING_PROVIDER=local` בקובץ `~/.agentmemory/.env` ולהפעיל מחדש. בקשת ה-embedding הראשונה מורידה את `Xenova/all-MiniLM-L6-v2`; לאחר ההורדה הראשונית, ההסקה רצה מקומית.
+
+סביבת ההרצה המקומית משתמשת בארבעה פורטים: `3111` עבור REST/MCP HTTP, `3112` עבור זרמי iii, `3113` עבור המציג, ו-`49134` עבור ה-WebSocket של worker ה-iii. מצב ה-iii המתמשך חי ב-`~/Library/Application Support/agentmemory` ב-macOS, ב-`$XDG_DATA_HOME/agentmemory` או `~/.local/share/agentmemory` ב-Linux, וב-`%APPDATA%\agentmemory` ב-Windows. יש להשתמש ב-`--data-dir ` או ב-`AGENTMEMORY_DATA_DIR` כדי לשנות זאת, ולהשתמש באותו ערך בכל הפעלה מחדש. לשם תאימות לאחור, `./data/state_store.db` או `./data/iii-config.yaml` קיימים מקבלים עדיפות על פני ברירת המחדל של הפלטפורמה עבור instance 0; דגל מפורש או override של משתנה סביבה עדיין גובר.
+
+לאחר מכן, הדגימו ששליפה עובדת ותנו לסוכן שלכם את ה-skills שלו:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+חיפושי מילות המפתח צריכים לפגוע ביעד במצב keyless שברירת המחדל שלו באמצעות BM25. השאילתה `database performance optimization` בדוגמה היא סמנטית במכוון ועלולה להחזיר אפס עד שיוגדר ספק embedding.
+
+מעדיפים לתת לסוכן קוד לעשות את כל העבודה? תנו לו הוראה אחת:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+ניתן לחווט עוד סוכנים בכל עת עם `agentmemory connect ` — 20 מתאמים מופיעים ברשימה ב[עובד עם כל סוכן](#works-with-every-agent). מדריך הפקודות המלא נמצא ב[התחלה מהירה](#quick-start).
+
+
+Windows
+
+המסלול המהיר הוא WSL2. הגדרת מנוע ב-Windows מקורי דורשת הורדה של קובץ ה-ZIP הנעוץ v0.22.1 וחילוץ `iii.exe` באופן ידני; ה-CLI לא מחלץ אותו אוטומטית. Docker Desktop נתמך גם הוא. ראו את [הערות Windows](#windows) לפירוט שלב-אחר-שלב.
+
+
+
+
+התקנה גלובלית / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+פקודת ה-npx שלמעלה נשארת מסלול ההתקנה הראשונית הקנוני ומונעת בעיות הרשאה של global-prefix.
+
+
+
+
+npx מגיש גרסה ישנה
+
+npx שומר במטמון לפי גרסה. אפשר לכפות את הגרסה העדכנית עם `npx -y @agentmemory/agentmemory@latest`, או לנקות את המטמון פעם אחת עם `rm -rf ~/.npm/_npx` (macOS/Linux; ב-Windows מוחקים את `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+כבר מריצים iii engine משלכם
+
+agentmemory נעוץ לגרסה v0.22.1 של iii-engine ולא יתחבר לגרסה אחרת (ה-worker לא יודע לדבר בפרוטוקול של מנוע אחר). עצרו את המנוע האחר, ואז הריצו `npx -y @agentmemory/agentmemory@latest`. זה מתקין ומריץ את הגרסה הנעוצה v0.22.1 בתוך `~/.agentmemory/bin`, מבלי לגעת ב-`iii` שלכם.
+
+
+
+---
+
+
+
+agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-REST API. כל הסוכנים חולקים את אותו שרת זיכרון.
+
+
+
+
+
+Claude Code
+plugin מובנה + 12 hooks + MCP
+
+
+
+Codex CLI
+plugin מובנה + 6 hooks + MCP
+
+
+
+GitHub Copilot CLI
+MCP + hooks/skills של plugin
+
+
+
+Cursor
+plugin מובנה + 7 hooks + MCP
+
+
+
+OpenCode
+plugin ללכידה + MCP
+
+
+
+
+
+Devin
+6 hooks + skills + MCP
+
+
+
+OpenClaw
+plugin מובנה + MCP
+
+
+
+Hermes
+plugin מובנה + MCP
+
+
+
+pi
+plugin מובנה + MCP
+
+
+
+OpenHuman
+backend מובנה מבוסס Memory trait
+
+
+
+
+
+Gemini CLI
+שרת MCP
+
+
+
+Antigravity
+MCP + hooks
+
+
+
+Claude Desktop
+שרת MCP
+
+
+
+Warp
+חיבור + MCP + skills
+
+
+
+Zed
+שרת MCP
+
+
+
+
+
+Cline
+שרת MCP
+
+
+
+Continue
+שרת MCP
+
+
+
+Droid
+שרת MCP
+
+
+
+Kiro
+שרת MCP
+
+
+
+Qwen Code
+שרת MCP
+
+
+
+
+
+DeepSeek Harness
+שרת MCP
+
+
+
+Roo Code
+שרת MCP
+
+
+
+Kilo Code
+שרת MCP
+
+
+
+Goose
+שרת MCP
+
+
+
+Aider
+REST API
+
+
+
+
+
+ עובד עם כל סוכן שמדבר MCP או HTTP. שרת אחד, זיכרונות משותפים בין כולם.
+
+
+---
+
+אתם מסבירים את אותה הארכיטקטורה בכל session מחדש. אתם מגלים מחדש את אותן תקלות. אתם מלמדים מחדש את אותן ההעדפות. הזיכרון המובנה (CLAUDE.md, .cursorrules) מוגבל ל-200 שורות והולך ומתיישן. agentmemory פותר את זה. הוא לוכד בשקט את מה שהסוכן שלכם עושה, דוחס את זה לזיכרון שניתן לחפש בו, ומזריק את ההקשר הנכון כשה-session הבא מתחיל. פקודה אחת. עובד בין סוכנים שונים.
+
+**מה משתנה:** ב-session הראשון הגדרתם JWT auth. ב-session השני אתם מבקשים rate limiting. הסוכן כבר יודע שה-auth שלכם משתמש ב-jose middleware בקובץ `src/middleware/auth.ts`, שהבדיקות שלכם מכסות אימות token, ושבחרתם ב-jose על פני jsonwebtoken בשביל תאימות ל-Edge, בלי להסביר מחדש ובלי copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+כברירת מחדל, agentmemory שומר את מצב ה-iii-engine מחוץ ל-repository שממנו הפעלתם אותו: `~/Library/Application Support/agentmemory` ב-macOS, `$XDG_DATA_HOME/agentmemory` או `~/.local/share/agentmemory` ב-Linux, ו-`%APPDATA%\agentmemory` ב-Windows. `./data/state_store.db` או `./data/iii-config.yaml` legacy קיימים מקבלים שימוש חוזר עבור instance 0 לפני ברירת המחדל של הפלטפורמה. כדי לבחור מיקום באופן מפורש, יש להעביר `--data-dir ` או להגדיר `AGENTMEMORY_DATA_DIR`; כל הגדרה מפורשת גוברת על הגילוי ה-legacy:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+הפעלות native ו-Docker משתמשות באותה תיקיית host שנפתרה; Docker עושה לה bind-mount בתוך `/data`. `--instance 1` מוסיף `instance-1` לתיקייה שנפתרה ובוחר ברביעיית הפורטים הנפרדת שבברירת המחדל `3211/3212/3213/49234`.
+
+הערות השחרור העדכניות: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### דיוק שליפה
+
+**coding-agent-life-v1** (קורפוס פנימי, שניתן לשכפול ב-sandbox)
+
+| מתאם | P@5 | R@5 | שיעור פגיעה ב-Top-5 | latency p50 |
+|---|---|---|---|---|
+| **agentmemory היברידי** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep (קו בסיס) | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+שיעור פגיעה של 100% ב-top-5 בתקרה המתמטית של **P@5** עבור הקורפוס הזה (0.240, ראו scorecard). המצב ההיברידי שולף כל session זהב (gold); ל-grep חסר 1 מתוך 2 פריטי gold בשאילתה הטמפורלית המשתרעת על כמה sessions. השיפור הוא ב-**recall + טמפורליות**, לא בדיוק מצרפי. ה-benchmark הזה קטן ומעוט gold; LongMemEval-S הגדול יותר שלהלן מבדיל טוב יותר. פירוט מלא לפי טיפוס + הערת תיקון: [`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% |
+
+
+
+
+### חיסכון בטוקנים
+
+| גישה | טוקנים/שנה | עלות/שנה |
+|---|---|---|
+| הדבקת הקשר מלא | 19.5M+ | בלתי אפשרי (חורג מהחלון) |
+| סיכום על ידי LLM | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + embeddings מקומיים | ~170K | **$0** |
+
+
+
+
+
+> מודל embedding: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**שכפול מקומי:** [`eval/README.md`](../eval/README.md), harness עם adapters נתיקים עבור LongMemEval `_s` (500 שאלות ציבוריות) + `coding-agent-life-v1` (קורפוס פנימי של 15 sessions). מתאמי Grep / וקטור / agentmemory מקבלים ניקוד אחד לצד השני, פלט NDJSON, וה-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, pipelines לבנייה מרובת-סוכנים, וגרפי ידע רחבים יותר על פני docs / PDF / תמונות / וידאו. agentmemory זוכר את העבודה; שלושת הפרויקטים האלה מדליקים את שאר שכבת ההקשר. מתכונים + טבלת ניתוב שאלות: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Built-in (CLAUDE.md)
+
+
+
סוג
+
מנוע זיכרון + שרת MCP
+
API של שכבת זיכרון
+
runtime מלא לסוכן
+
AI אישי
+
API זיכרון + אפליקציה
+
hub זיכרון לצוות (proxy ל-LLM)
+
זיכרון וקטורי (קוד פתוח)
+
מנוע זיכרון (Oracle DB)
+
מערכת זיכרון
+
קובץ סטטי
+
+
+
שליפה R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
דיווח עצמי
+
PersonaMem 76% (דיווח עצמי)
+
~96.6% (דיווח עצמי)
+
94.4% (דיווח עצמי)
+
N/A
+
N/A (grep)
+
+
+
לכידה אוטומטית
+
12 hooks (ללא מאמץ ידני)
+
קריאות add() ידניות
+
עריכות עצמיות של הסוכן
+
ידני
+
חילוץ בצד ה-API
+
יירוט proxy (החלפת base-URL)
+
ידני
+
חילוץ API
+
ידני
+
עריכה ידנית
+
+
+
חיפוש
+
BM25 + וקטור + גרף (fusion מסוג RRF)
+
וקטור + גרף
+
וקטור (ארכיוני)
+
סמנטי
+
וקטור + RAG
+
4 סוגי נכסים (Chat / Skill / Wiki / CodeGraph)
+
וקטור בלבד
+
וקטור + סמנטי
+
משוקלל decay
+
טוען הכול להקשר
+
+
+
ריבוי-סוכנים
+
MCP + REST + leases + signals
+
API (בלי תיאום)
+
רק בתוך runtime של Letta
+
לא
+
לא
+
תפקידי צוות + נכסים משותפים
+
לא
+
מוגבל לתחום בלבד
+
משותף בין סוכנים מרובים
+
קבצים לפי סוכן
+
+
+
נעילה ל-framework
+
אין (כל לקוח MCP)
+
אין
+
גבוהה (חייבים להשתמש ב-Letta)
+
עצמאי (standalone)
+
אין
+
Proxy חוצץ בפני כל קריאת מודל
+
אין
+
Oracle Database
+
אין
+
פורמט לפי סוכן
+
+
+
תלויות חיצוניות
+
אין (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + מסד נתונים וקטורי
+
מרובות
+
cloud מנוהל
+
ערימת Docker (Core + Hub + Proxy)
+
מאגר וקטורי
+
Oracle AI Database
+
אין
+
אין
+
+
+
מחזור חיים של הזיכרון
+
קונסולידציה ב-4 שכבות + decay + שכחה אוטומטית
+
חילוץ פסיבי
+
מנוהל על ידי הסוכן
+
ידני
+
שכחה אוטומטית
+
בדיקה ידנית; ניתוב אוטומטי בפיתוח
+
אין
+
לא מצוין
+
decay + קונסולידציה
+
גיזום ידני
+
+
+
יעילות טוקנים
+
~1,900 טוקנים/session ($10/שנה)
+
משתנה לפי אינטגרציה
+
זיכרון core בתוך ההקשר
+
משתנה
+
תמחור cloud
+
לא מצוין
+
אין תקציב טוקנים
+
מגובה LLM (משתנה)
+
משתנה
+
22K+ טוקנים ב-240 תצפיות
+
+
+
מציג בזמן אמת
+
כן (פורט 3113)
+
dashboard ב-cloud
+
dashboard ב-cloud
+
UI מבוסס web
+
dashboard ב-cloud
+
UI web של ה-hub
+
לא
+
לא
+
לא
+
לא
+
+
+
אירוח עצמי
+
כן (ברירת מחדל)
+
אופציונלי
+
אופציונלי
+
כן
+
לא (cloud בלבד)
+
כן (Docker)
+
כן
+
כן (Oracle DB)
+
כן
+
כן
+
+
+
+הערת benchmark: רק ה-R@5 של agentmemory הוא תוצאת מדידה שלנו (LongMemEval-S, ניתנת לשכפול מ-benchmark/COMPARISON.md). המספרים של mem0 ו-Letta הם המספרים המתפרסמים שלהם מ-LoCoMo (dataset שונה); המספרים של MemPalace, supermemory, TencentDB (PersonaMem), ו-oracleagentmemory הם טענות שדווחו על ידי היצרן ולא שכפלנו אותן באופן עצמאי (ההרצה של oracleagentmemory השתמשה ב-GPT-5.5 מול Oracle AI Database). מוצגים זה לצד זה להערכה כללית בלבד, לא כהשוואת ראש-בראש על אותם נתונים. ספירות הכוכבים הן משוערות ומשתנות עם הזמן.
+
+**שחקנים חדשים יותר** שכדאי להכיר, מושווים בהרחבה ב-[`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| מערכת | ⭐ | זווית |
+|--------|---|-------|
+| Zep / Graphiti | 30K | גרף ידע טמפורלי; תוצאות השאילתה הטמפורלית הפרסומיות החזקות ביותר (LongMemEval 63.8%), אבל הגרף נבנה באופן אסינכרוני כך שעובדות חדשות יכולות להתעכב |
+| Cognee | 30K | בליעת מסמכים לגרף ידע (document-to-knowledge-graph), Python בלבד, נבנה לחילוץ ישויות מבני ולא ללכידת sessions |
+
+אף אחד מהם לא לוכד אוטומטית מ-hooks של סוכן קוד, לא מגיע עם מציג local-first, ולא רץ במצב keyless — השילוב הזה הוא מה ש-agentmemory בנוי עליו.
+
+---
+
+
+
+תאימות: הגרסה הזו מיועדת ל-`iii-sdk` 0.22.1 ונעוצה לגרסה v0.22.1 של iii-engine.
+
+### נסו את זה ב-30 שניות
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` מזריע 3 sessions ריאליסטיים (JWT auth, תיקון שאילתת N+1, rate limiting) ומריץ עליהם חיפושים. התקנות keyless משביתות וקטורים, כך ששאילתות מילות המפתח של `mem::search` צריכות לפגוע ביעד באמצעות BM25 בעוד ש-`database performance optimization` יכולה להחזיר אפס. `smart-search` יכול גם להחזיר התאמות מבניות מהגרף כשנתוני גרף קיימים. כדי לגרום לשאילתה הסמנטית למצוא את תיקון ה-N+1 באמצעות וקטורים, יש להגדיר `EMBEDDING_PROVIDER=local`, להפעיל מחדש, ולאפשר להורדת המודל הראשונה להסתיים.
+
+פתחו את `http://localhost:3113` כדי לראות את הזיכרון נבנה בזמן אמת.
+
+### אימות התקנה חדשה והתמדה (persistence) אחרי הפעלה מחדש
+
+כשהשרת רץ, יש לאמת את ה-REST, את ה-health, את המציג, ואת מצב ה-runtime המבוסס iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+פאנל המוכנות (ready) שעולה בהפעלה מתייחס לכל ארבעת הפורטים: REST/MCP HTTP בפורט 3111, זרמי iii בפורט 3112, המציג בפורט 3113, וה-WebSocket של worker ה-iii בפורט 49134. `status` מאשר את ה-health של agentmemory ואת מצב הספק/embedding הפעיל. שמרו probe ואמתו שהוא ניתן לחיפוש:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+לאחר מכן הריצו `npx -y @agentmemory/agentmemory@latest stop`, הפעילו שוב את הפקודה הקנונית ב-Terminal 1, המתינו ל-`/agentmemory/livez`, וחזרו על החיפוש. ה-probe חייב עדיין להיות מוחזר. אם בחרתם `--data-dir` מותאם אישית, העבירו את אותה תיקייה בהפעלה מחדש.
+
+### פקודות יומיומיות
+
+התקנה והגדרה נמצאות ב[התקנה](#install) מעלה (ההרצה הראשונה מדריכה אתכם צעד אחר צעד). ביום-יום:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### שידור חזרה (Replay) של session
+
+כל session ש-agentmemory מקליט ניתן ל-replay. פתחו את המציג, בחרו בלשונית **Replay**, וגללו על פני ציר הזמן: prompts, קריאות tool, תוצאות tool, ותגובות מוצגים כאירועים נפרדים עם play/pause, שליטה במהירות (0.5x עד 4x), וקיצורי מקלדת (space להחלפה, חצים לדילוג שלב).
+
+כדי להכניס תמלילי JSONL ישנים יותר של Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+sessions מיובאים מופיעים בבורר ה-Replay לצד אלה המקוריים. מתחת למכסה המנוע, כל רשומה עוברת בפונקציות ה-iii `mem::replay::load`, `mem::replay::sessions`, ו-`mem::replay::import-jsonl`, בלי שרתי side-channel. כל תמליל מיובא מאונדקס לחיפוש, מתויג בערוץ מקור `import`, ונכרה לקבלת crystal של session ולקחים (lessons).
+
+> **שימו לב אם אתם נשענים על `import-jsonl` כנתיב הלכידה העיקרי שלכם:** ה-`cleanupPeriodDays` של Claude Code (בקובץ `~/.claude/settings.json`, ברירת מחדל **30**) מוחק אוטומטית תמלילי JSONL ישנים מהחלון הזה מ-`~/.claude/projects/`. אם אתם מתקינים agentmemory בפעם הראשונה על היסטוריית Claude Code בת כמה חודשים, כל דבר שישן מ-30 יום כבר נעלם לפני היבוא הראשון. אפשר להריץ את `import-jsonl` ב-cron, להעלות את `cleanupPeriodDays` לערך גבוה יותר, או לחווט את ה-hooks של הלכידה האוטומטית (נתיב התקנת ה-plugin כברירת מחדל) כך שכל turn נוחת ב-agentmemory כל עוד ה-session חי והניקוי של JSONL מפסיק להיות רלוונטי.
+
+### שדרוג / תחזוקה
+
+השתמשו בפקודת התחזוקה כשאתם רוצים במכוון לעדכן את ה-runtime המקומי שלכם:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+אזהרה: הפקודה הזו משנה את ה-workspace/runtime הנוכחי. היא יכולה לעדכן תלויות JavaScript ולמשוך את תמונת ה-Docker הנעוצה `iiidev/iii:0.22.1`. היא לעולם לא מתקינה iii engine לא-נעוץ או חדש יותר.
+
+פרטי המימוש נמצאים בקובץ `src/cli.ts` (ראו `runUpgrade` באזור `src/cli.ts:544-595`).
+
+### Claude Code (בלוק אחד, הדביקו אותו)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code בלי התקנת ה-plugin (נתיב MCP בלבד)
+
+אם אתם מחווטים את שרת ה-MCP של agentmemory ישירות דרך `~/.claude.json` במקום להשתמש ב-`/plugin install`, Claude Code לעולם לא פותר את `${CLAUDE_PLUGIN_ROOT}` ואתם חייבים להפנות את סקריפטי ה-hook ל-paths מוחלטים בתוך `~/.claude/settings.json`. ה-paths האלה בדרך כלל מטמיעים בתוכם את גרסת agentmemory (למשל `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), כך שהשדרוג הבא שובר בשקט כל hook.
+
+פתרון עוקף:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+זה ממזג את אותן פקודות hook לתוך `~/.claude/settings.json` עם paths מוחלטים שנפתרים לתיקיית `plugin/` המצורפת של חבילת `@agentmemory/agentmemory` המותקנת כעת. יש להריץ את הפקודה מחדש אחרי שדרוג agentmemory כדי לרפרש את ה-paths. רשומות משתמש בקובץ עצמו נשמרות; רק רשומות agentmemory קודמות מוחלפות. השימוש בנתיב `/plugin install` נשאר הגישה המומלצת.
+ל-deployments מרוחקים או מוגנים, הפעילו את Claude Code עם `AGENTMEMORY_URL` ו-`AGENTMEMORY_SECRET` מוגדרים. ה-plugin מעביר את שני הערכים לשרת ה-MCP המצורף שלו; כש-`AGENTMEMORY_URL` ריק, ה-shim של MCP משתמש ב-`http://localhost:3111`.
+
+### Codex CLI (פלטפורמת plugin של Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+ה-plugin של Codex נשלח מתוך אותה תיקיית `plugin/` כמו ה-plugin של Claude Code. הוא רושם:
+
+- גשר MCP מצורף מסוג stdio ל-daemon הרץ, בלי הורדת npm ובלי מאגר fallback. ראו את [מדריך ה-Codex המקומי](../docs/plugins/codex-local.md) כדי לבדוק build שלא פורסם.
+- 6 hooks של מחזור חיים: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skills שניתן להפעיל: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, בתוספת 8 skills של עיון (reference) שהסוכן טוען לפי הצורך (משמעת זיכרון, כלי MCP, REST API, תצורה, סוכנים, hooks, ארכיטקטורה, ומדריך כתיבת skills)
+
+מנוע ה-hooks של Codex מזריק את `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 עובדים בשני ה-hosts בלי שכפול. אירועי Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure הם ייחודיים ל-Claude Code ולא רשומים עבור Codex.
+
+#### אמון ב-hooks של Codex ותאימות
+
+שילוח ה-hooks הנטיביים של ה-plugin מאומת עם Codex CLI 0.150.1. בטחו ב-hooks של ה-plugin לפני שאתם מצפים ללכידה. ההתנהגות ב-Desktop תלויה ב-runtime המצורף שלו; בדקו את `/hooks` ואשרו אירוע שנלכד לפני הפעלת פתרון עוקף.
+
+אם ה-host שלכם דורש hooks גלובליים, שכפלו את הפקודות לתוך `~/.codex/hooks.json`. כש-MCP כבר מחווט, המתאם הנוכחי צריך `--force` כדי להגיע להתקנת ה-hooks:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+זה ממזג hooks גלובליים וכותב מחדש את הרשומה של agentmemory MCP, בעוד שהרשומות הלא-קשורות נשמרות. בדקו הגדרות endpoint מותאמות אישית של agentmemory לפני השימוש ב-`--force`. הריצו מחדש אחרי שדרוג כדי לרפרש paths של סקריפטים. הפעילו או hooks נטיביים של ה-plugin או עותקים גלובליים כדי להימנע מלכידה כפולה.
+
+### GitHub Copilot CLI
+
+למצב ה-agent של VS Code, השתמשו ב-[מדריך Copilot MCP ולכידה אוטומטית](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). מתאם ה-CLI לא מגדיר את VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` ממזג את `mcpServers.agentmemory` לתוך `~/.copilot/mcp-config.json` (או `$COPILOT_HOME/mcp-config.json` כש-`COPILOT_HOME` מוגדר) ומשמר שרתים קיימים. ב-Windows מקורי זה המתאם ה-`connect` האוטומטי היחיד; יש להגדיר כל סוכן Windows מקורי אחר באופן ידני. `connect` תחת WSL נתמך רק כשהסוכן המיועד מותקן באותה סביבת WSL. Copilot קולט את שרת ה-MCP בהפעלה הבאה או אחרי `/mcp`. התקינו גם את ה-plugin כשאתם רוצים את חוויית ה-hook/skill המלאה.
+
+
+OpenClaw (הדביקו את ה-prompt הזה)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+מדריך מלא: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (הדביקו את ה-prompt הזה)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+מדריך מלא: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### סוכנים אחרים
+
+הפעילו את שרת הזיכרון: `npx -y @agentmemory/agentmemory@latest`
+
+#### Skills מובנים דרך `npx skills add` (50+ סוכנים)
+
+agentmemory שולח 17 skills בפורמט `/SKILL.md` בסטייל Claude Code: 9 skills של פעולה שניתן להפעיל (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) ו-8 skills של עיון שהסוכן טוען לפי הצורך (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). ה-skills של העיון נושאים טבלאות נתונים שנוצרות מהמקור, כך שהן לעולם לא נסחפות (drift). ה-CLI [`skills`](https://npmjs.com/package/skills) של vercel-labs מתקין אותם אוטומטית לתוך תיקיית ה-skills המובנית של הסוכן הקורא על פני 50+ סוכנים (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, ועוד):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+זה **משלים** את `agentmemory connect `:
+
+- `agentmemory connect ` כותב את תצורת שרת ה-MCP כך שהכלים זמינים.
+- `npx skills add rohitg00/agentmemory` מתקין את ה-skills כך שהסוכן יודע מתי לקרוא להם.
+
+לכמה מהסוכנים שה-CLI של skills עדיין לא מכסה (Zed v1.3.x ומטה), שימו את 17 קבצי ה-SKILL.md בעצמכם תחת תיקיית ה-skills המובנית של הסוכן; אותו פורמט עובד בכל מקום.
+
+#### בלוק MCP סטנדרטי
+
+הרשומה של agentmemory היא **אותו בלוק שרת MCP** בכל host שמשתמש במבנה `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**מזגו את הרשומה הזו לתוך האובייקט `mcpServers` הקיים** בקובץ התצורה של ה-host; אל תחליפו את הקובץ. אם לקובץ יש כבר שרתים אחרים, הוסיפו את `agentmemory` לידם כמפתח נוסף בתוך `mcpServers`. אם `mcpServers` חסר כליל, הדביקו את הבלוק בתוך `{ "mcpServers": { ... } }`. ה-placeholders מסוג `${VAR}` יורשים את `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` מה-shell בהפעלת שרת ה-MCP; משתנים לא מוגדרים מעבירים מחרוזות ריקות וה-shim חוזר ל-`http://localhost:3111`. רשומה אחת מחווטת מכסה גם deployments מקומיים וגם מרוחקים (k8s / מאחורי reverse-proxy).
+
+| סוכן | קובץ תצורה | הערות |
+|---|---|---|
+| **Cursor (MCP בלבד)** | `~/.cursor/mcp.json` | מזגו לתוך `mcpServers`, או `agentmemory connect cursor`. deeplink בלחיצה אחת זמין גם באתר. |
+| **Cursor (plugin מלא)** | `.cursor-plugin/` | רישום ב-Cursor Marketplace (ה-submission בבדיקה) או Cursor Settings → Plugins → local checkout. רושם 7 hooks של לכידה אוטומטית (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + שרת ה-MCP, כש-`AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` מנוהלים ב-dashboard של ה-plugin של Cursor. עובד ב-Cursor IDE וב-CLI `cursor-agent`; prompts של מצב print ב-CLI מתמלאים בדיעבד מתמליל ה-session בסוף ה-session. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | מזגו לתוך `mcpServers`. הפעילו מחדש את Claude Desktop אחרי העריכה. |
+| **Cline / Roo Code / Kilo Code** | הגדרות MCP של Cline (Settings UI → MCP Servers → Edit) | אותו בלוק `mcpServers`. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` ממזג את רשומת ה-MCP; `--with-hooks` מוסיף שישה hooks מובנים של לכידה אוטומטית (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) עם matchers של tool באותיות קטנות של Devin. אמתו עם `devin mcp list` ו-`/hooks` בתוך devin. |
+| **Devin CLI (plugin מלא)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` מתוך checkout רושם את כל 17 ה-skills כפקודות slash מסוג `/agentmemory:` בתוספת שרת ה-MCP. ה-hooks של plugin ב-Devin לא יכולים להפעיל `SessionStart`/`SessionEnd`, אז משלבים אותו עם `connect devin --with-hooks` ללכידה מלאה של session. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | הוסיפו MCP מותאם אישית (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` שמצביע על deployment של agentmemory נגיש ברשת בתוספת `AGENTMEMORY_SECRET` (sessions בענן לא יכולים להגיע ל-localhost — ראו [`deploy/`](../deploy/)). שמרו את ה-secret ב-Devin Secrets, ואז השתמשו ב-"Test listing tools" כדי לאמת ש-54 הכלים מופיעים. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (ממזג אוטומטית). |
+| **GitHub Copilot CLI (MCP בלבד)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` ממזג את `mcpServers.agentmemory`; Copilot קולט את זה בהפעלה הבאה או ב-`/mcp`. |
+| **GitHub Copilot CLI (plugin מלא)** | התקנת plugin של Copilot | `copilot plugin install rohitg00/agentmemory:plugin` עבור ה-plugin מתוך ה-subdir ב-GitHub. |
+| **OpenClaw** | תצורת MCP של OpenClaw | אותו בלוק `mcpServers`. לעומק: `openclaw plugins install ./integrations/openclaw` תופס את slot הזיכרון של OpenClaw (עובר אוטומטית מ-`memory-core`); הגדירו `plugins.entries.agentmemory.hooks.allowConversationAccess=true` אחרת לכידת ה-turn נחסמת בשקט. ראו [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (MCP בלבד)** | `.codex/config.toml` | מבנה TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, או הוסיפו `[mcp_servers.agentmemory]` ידנית. |
+| **Codex CLI (plugin מלא)** | marketplace של plugin-ים ב-Codex | `codex plugin marketplace add rohitg00/agentmemory` ואז `codex plugin add agentmemory@agentmemory`. רושם MCP + 6 hooks של מחזור חיים + 17 skills. בטחו ב-hooks ואמתו לכידה ב-host שלכם; ראו [הגדרה ואימות של Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (MCP בלבד)** | `opencode.json` | מבנה שונה: מפתח `mcp` ב-top-level, command כמערך: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin מלא)** | `plugin/opencode/` | 22 hooks של לכידה אוטומטית שמכסים מחזור חיים של session, הודעות, tools, שגיאות. ייחוס הפרויקט הוא per-session, כך שתהליך OpenCode אחד שמשתרע על כמה repositories מתעד כל session תחת הפרויקט שלו. שתי פקודות slash (`/recall`, `/remember`). העתיקו את `plugin/opencode/` ל-workspace של OpenCode שלכם והוסיפו את רשומת ה-plugin ל-`opencode.json`. ראו [`plugin/opencode/README.md`](../plugin/opencode/README.md) לטבלת ה-hooks המלאה + ניתוח הפערים. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` מתקין את ה-extension המצורף לתוך תיקיית הגילוי האוטומטי של pi (recall בהתחלת הסוכן, capture בסיום הסוכן, כלי `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` ב-pi רץ קולט את זה. [`integrations/pi`](../integrations/pi/) הוא גם חבילת pi (`pi install ./integrations/pi` מתוך checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` נותן את ספק הזיכרון בן 6 ה-hooks (prefetch, לכידת turn, סיום session, pre-compress, שיקוף MEMORY.md, בלוק system prompt). אמתו עם `hermes plugins doctor` ו-`hermes memory status`. ראו [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` כותב את בלוק ה-`mcpServers` הסטנדרטי. ה-payload של ה-hook תואם-שדות ל-Claude Code, כך שסקריפטי ה-12 hooks הקיימים עובדים בלי שינוי; חווטו אותם דרך סקשן ה-`hooks` באותו `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` מתקין MCP ו-hooks של לכידה בתיקיית ההתאמה האישית המשותפת. ראו [הגדרה ומגבלות של Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` משתמש באותה תצורת MCP ו-hooks כמו גרסאות ה-IDE הנוכחיות. התקנות קיימות צריכות לרפרש עם `--force`; ראו את [הערות השדרוג](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` כותב את התצורה בשכבת המשתמש. override-ים בשכבת ה-workspace נכנסים ב-`.kiro/settings/mcp.json` לצד הקוד שלכם. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` כותב את בלוק ה-`mcpServers` הסטנדרטי. Warp גם מגלה אוטומטית skills מ-`.claude/skills/`; כשה-plugin של Claude Code מותקן, 8 ה-skills של agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) מופיעים באופן מובנה בפלטת פקודות ה-slash של Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` כותב את בלוק ה-`mcpServers` הסטנדרטי. למשתמשי ה-extension של VS Code: הדביקו את אותו בלוק דרך Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (מועדף) או `config.json` (legacy) | `agentmemory connect continue` יוצר `config.yaml` מאפס כששניהם לא קיימים, או משנה `config.json` קיים. **אם יש לכם כבר `config.yaml`** המתאם מדפיס את הבלוק המדויק להדבקה תחת `mcpServers:`; הוא לא כותב מחדש בשקט את ה-yaml שלכם כי שמירה בטוחה על comments ועוגנים (anchors) מחייבת YAML parser שהחבילה לא מגיעה איתו. Continue משתמש בצורת מערך (לא object) עבור `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` כותב תחת `context_servers` (המפתח של Zed, לא `mcpServers`). שרתי MCP מרוחקים אפשר לחווט במקום זאת דרך `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` כותב את בלוק ה-`mcpServers` הסטנדרטי. override-ים בתחום פרויקט נכנסים ב-`/.factory/mcp.json`. העבירו `--with-hooks` ללכידה אוטומטית מובנית. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` מוסיף שורת `@deepseek-ai/dsh-mcp-client` לשכבת ה-patch בשכבת ה-home שכל פרופיל Harness טוען; הכלים נרשמים כ-`mcp__agentmemory__*`. העבירו `--with-hooks` כדי לחווט גם לכידה אוטומטית: סקריפטי ה-hook המצורפים של Claude Code רצים דרך הגשר ה-first-party של Harness, `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), באמצעות manifest שנכתב ל-`$DSH_HOME/agentmemory.hooks.json`. ברירת המחדל היא `~/.dsh` כש-`DSH_HOME` לא מוגדר. |
+| **Goose** | ממשק הגדרות MCP של Goose | אותו בלוק `mcpServers`; השתמשו ב-`goose configure` → Add Extension → MCP. עריכה ישירה של YAML ב-`~/.config/goose/config.yaml` נתמכת אבל ה-schema משתמש ב-`extensions:` + `cmd` (לא `mcpServers:` + `command`). |
+| **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 וממזג. |
+
+**לקוחות MCP ב-sandbox** (Flatpak / Snap / containers מגבילים) שלא יכולים להגיע ל-`localhost` של ה-host: הגדירו גם `"AGENTMEMORY_FORCE_PROXY": "1"` בבלוק ה-`env`, והפנו את `AGENTMEMORY_URL` למסלול שה-sandbox יכול בפועל להגיע אליו (למשל כתובת ה-LAN שלכם).
+
+### גישה פרוגרמטית (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/) (quickstart + זרימת observation/recall). ה-REST בפורט `:3111` נשאר זמין ל-hosts בלי runtime של iii.
+
+### מהמקור (From source)
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+זה מפעיל את agentmemory עם `iii-engine` מקומי אם הבינארי הנעוץ כבר מותקן, או משתמש ב-Docker Compose כשנבחר. REST, streams, והמציג נקשרים (bind) ל-`127.0.0.1` כברירת מחדל. הנתיב האוטומטי של הבינארי ב-macOS/Linux דורש `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`.
+
+התקינו את `iii-engine` ידנית. **agentmemory נעוץ כרגע ל-`iii-engine` בגרסה `v0.22.1`**, אותה גרסה כמו התלות ב-`iii-sdk`; ה-worker מדבר בפרוטוקול ה-wire של אותו מנוע, וגרסה 0.20.0 ארגנה מחדש את שטח ה-SDK, כך שהשניים זזים יחד בגרסאות agentmemory. override עם `AGENTMEMORY_III_VERSION=` אם אתם מריצים מנוע משלכם ויודעים שהוא מתאים.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** החליפו את `aarch64-apple-darwin` ב-`x86_64-apple-darwin`
+- **Linux x64:** החליפו ל-`x86_64-unknown-linux-gnu`
+- **Linux arm64:** החליפו ל-`aarch64-unknown-linux-gnu`
+- **Windows:** הורידו את `iii-x86_64-pc-windows-msvc.zip` מ-[iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) וחלצו את `iii.exe` ל-`%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+לכל archive יש קובץ `.sha256` תואם בעמוד ה-release; כשמחליפים פלטפורמה, משתמשים ב-hash של אותו קובץ בבדיקה שלמעלה (ב-Windows: `Get-FileHash`). המתקין האוטומטי ב-`npx @agentmemory/agentmemory` נעוץ ל-hashes האלה ומסרב ל-archive שלא תואם.
+
+או השתמשו ב-Docker (ה-`docker-compose.yml` המצורף מוריד את `iiidev/iii:0.22.1`). תיעוד מלא: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory רץ על Windows 10/11, אבל חבילת ה-Node.js בלבד לא מספיקה; צריך גם את ה-runtime הנעוץ v0.22.1 של iii-engine כתהליך רץ ברקע. ה-CLI לא מחלץ אוטומטית את ה-ZIP של Windows, כך שמשתמשי Windows מקורי חייבים להתקין את `iii.exe` ידנית, להשתמש ב-WSL2, או לבחור ב-Docker Desktop.
+
+חיווט MCP אוטומטי ב-Windows מקורי תומך רק ב-`agentmemory connect copilot-cli`. עבור Claude Code, Codex, Cursor, וכל סוכן Windows מקורי אחר, העתיקו את בלוק ה-MCP הידני מ[סוכנים אחרים](#other-agents) לתוך תצורת ה-Windows של אותו סוכן. הרצת `connect` ב-WSL מתאימה רק כשהסוכן המיועד מותקן גם הוא באותה סביבת WSL; הוא לא עורך את התצורה של סוכן שרץ על Windows host.
+
+**אפשרות A: בינארי Windows מוכן מראש (מומלץ)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**אפשרות B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**אפשרות C: MCP standalone בלבד (בלי מנוע).** אם אתם צריכים רק את כלי ה-MCP לסוכן שלכם ולא צריכים את ה-REST API, המציג, או עבודות cron, דלגו על המנוע כליל:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**דיאגנוסטיקה ל-Windows:** אם `npx -y @agentmemory/agentmemory@latest` נכשל, הריצו אותו מחדש עם `--verbose` כדי לראות את ה-stderr האמיתי של המנוע. תבניות כשל נפוצות:
+
+| תסמין | תיקון |
+|---|---|
+| `The engine process started but the REST API never responded.` | אשרו שכל ארבעת הפורטים הנגזרים פנויים, אמתו שה-`iii.exe` הנעוץ נשאר חי, ואז הריצו מחדש עם `--verbose` ובדקו את ה-stderr שנלכד של המנוע |
+| `Could not start iii-engine` | לא `iii.exe` ולא Docker מותקנים. ראו אפשרות A או B מעלה |
+| קונפליקט פורטים | `netstat -ano \| findstr :3111` כדי לראות מה קשור (bound), ואז הרגו את התהליך או השתמשו ב-`--port ` |
+| ה-fallback ל-Docker דולג למרות ש-Docker מותקן | הקפידו ש-Docker Desktop רץ בפועל (אייקון ב-system tray) |
+
+> הערה: ה**מנוע** של iii הוא בינארי מוכן מראש, לא cargo crate, אז אל תנסו `cargo install` אותו. (ה**SDK-ים** של iii מתפרסמים ב-crates.io, npm, ו-PyPI, אבל agentmemory לא צריך אותם.) כל שיטות ההתקנה הנתמכות של המנוע נעוצות ל-v0.22.1: הבינארי המוכן מראש שלמעלה, נתיב ההתקנה האוטומטי של agentmemory ב-macOS/Linux (נדרשים `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`), ותמונת ה-Docker `iiidev/iii:0.22.1`. `install.sh | sh` גולמי מה-upstream מתקין את המנוע העדכני ביותר, שב-agentmemory לא נתמך. השתמשו ב-`npx -y @agentmemory/agentmemory@latest`; ב-macOS/Linux הוא מביא את המנוע הנעוץ לתוך `~/.agentmemory/bin`.
+
+---
+
+
פריסה
+
+תבניות בלחיצה אחת ל-hosts מנוהלים. כל אחת שולחת Dockerfile עצמאי שמוריד את `@agentmemory/agentmemory` מ-npm ומעתיק את הבינארי של מנוע ה-iii מתוך תמונת ה-Docker Hub הרשמית `iiidev/iii`; לא נדרשת תמונת agentmemory בנויה מראש. אחסון מתמשך נקשר (mount) ב-`/data`; ה-entrypoint של האתחול הראשון מחליף את תצורת ה-iii המצורפת ב-npm (שנקשרת ל-`127.0.0.1`) בתצורה מותאמת-deploy שנקשרת ל-`0.0.0.0` ומשתמשת ב-paths מוחלטים של `/data`, מייצרת את ה-secret של HMAC, ואז מוריד הרשאות מ-`root` ל-`node` באמצעות `gosu` לפני הרצת (exec) ה-CLI של agentmemory.
+
+
+
+
+
+
+כפתור הפריסה בלחיצה אחת של Render דורש `render.yaml` בשורש ה-repository, שאנחנו משאירים נקי בכוונה. השתמשו בזרימת ה-Render Blueprint המתועדת ב-[`deploy/render/`](.././deploy/render/README.md) כדי להפנות ל-blueprint שבתוך ה-repo באופן ידני.
+
+פרטי הקמה מלאים (לכידת HMAC, SSH tunnel למציג, רוטציה, backup, רצפות עלות) נמצאים ב-[`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): מכונה בודדת עם
+ `auto_stop_machines = "stop"`; הכי זול במנוחה (idle).
+- [`deploy/railway`](.././deploy/railway/README.md): תשלום קבוע ב-Hobby plan,
+ volume ב-dashboard.
+- [`deploy/render`](.././deploy/render/README.md): זרימת Blueprint,
+ snapshots אוטומטיים לדיסק בתוכניות בתשלום.
+- [`deploy/coolify`](.././deploy/coolify/README.md): אירוח עצמי על ה-VPS
+ שלכם באמצעות [Coolify](https://coolify.io/self-hosted); אותה ערימת Docker
+ Compose, אתם הבעלים של ה-host ושל הנתונים.
+
+רק פורט `3111` חשוף (published). המציג בפורט `3113` נשאר קשור
+ל-loopback בתוך ה-container; ה-README של כל תבנית מתעד את תבנית
+ה-SSH-tunnel להגיע אליו.
+
+---
+
+
+
+כל סוכן קוד שוכח הכול כש-session מסתיים, וכל session חדש מתחיל בכך שאתם מסבירים מחדש את ה-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.
+```
+
+### לעומת זיכרון מובנה בסוכן
+
+כל סוכן קוד מבוסס AI נשלח עם זיכרון מובנה: ל-Claude Code יש `MEMORY.md`, ל-Cursor יש notepads, ל-Cline יש memory bank. אלה עובדים כמו פתקיות דביקות. agentmemory הוא מסד הנתונים הניתן לחיפוש שמאחורי הפתקיות הדביקות.
+
+| | מובנה (CLAUDE.md) | agentmemory |
+|---|---|---|
+| קנה מידה | מוגבל ל-200 שורות | בלתי מוגבל |
+| חיפוש | טוען הכול להקשר | BM25 + וקטור + גרף (top-K בלבד) |
+| עלות טוקנים | 22K+ ב-240 תצפיות | ~1,900 טוקנים (92% פחות) |
+| בין-סוכנים | קבצים לפי סוכן | MCP + REST (כל סוכן) |
+| תיאום | אין | leases, signals, actions, routines |
+| Observability | קריאת קבצים ידנית | מציג בזמן אמת בפורט :3113 |
+
+---
+
+
+
+### צינור הזיכרון
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### קונסולידציית זיכרון ב-4 שכבות
+
+מבוסס על האופן שבו מוח האדם מעבד זיכרון, כולל קונסולידציה בשינה.
+
+| שכבה | מה | אנלוגיה |
+|------|------|---------|
+| **עבודה (Working)** | תצפיות גולמיות משימוש בכלים | זיכרון קצר-טווח |
+| **אפיזודי (Episodic)** | סיכומי session דחוסים | "מה קרה" |
+| **סמנטי (Semantic)** | עובדות ודפוסים שחולצו | "מה שאני יודע" |
+| **פרוצדורלי (Procedural)** | workflows ודפוסי החלטה | "איך לעשות את זה" |
+
+זיכרונות דועכים (decay) עם הזמן (עקומת Ebbinghaus). זיכרונות שנגישים אליהם לעיתים קרובות מתחזקים. זיכרונות שהתיישנו מתפנים (evict) אוטומטית. סתירות מתגלות ונפתרות.
+
+### מה נלכד
+
+| Hook | מה נלכד |
+|------|----------|
+| `SessionStart` | נתיב הפרויקט, מזהה ה-session |
+| `UserPromptSubmit` | prompts של המשתמש (מסוננים לפרטיות) |
+| `PreToolUse` | דפוסי גישה לקבצים + הקשר מועשר |
+| `PostToolUse` | שם ה-tool, קלט, פלט |
+| `PostToolUseFailure` | הקשר שגיאה |
+| `PreCompact` | מזריק מחדש זיכרון לפני compaction |
+| `SubagentStart/Stop` | מחזור חיים של תת-סוכן |
+| `Stop` | סיכום סוף-session |
+| `SessionEnd` | סימון השלמת session |
+
+### יכולות מפתח
+
+| יכולת | תיאור |
+|---|---|
+| **לכידה אוטומטית** | כל שימוש ב-tool נרשם דרך hooks, בלי מאמץ ידני |
+| **חיפוש סמנטי** | BM25 + וקטור + גרף ידע עם fusion מסוג RRF |
+| **אבולוציית זיכרון** | ניהול גרסאות, supersession, גרפי יחסים |
+| **היגיינת שליפה (recall)** | גרסאות זיכרון שהוחלפו (superseded) עוזבות את אינדקסי החיפוש; שרשרת הגרסאות ב-KV שומרת היסטוריה מלאה |
+| **אמצעי זהירות לכפילויות-כמעט** | שמירות מדווחות על התאמת `similarTo` מייעצת כשתוכן חדש מזכיר מאוד זיכרון קיים |
+| **תחום לפי סוכן** | `agentId` עובר דרך שמירה ושליפה על פני REST, MCP, ואינדקס החיפוש, במצב shared או isolated |
+| **מקור בזמן כתיבה (provenance)** | כל תצפית וזיכרון נושאים ערוץ מקור בלתי-ניתן-לשינוי (user, agent, tool, import, או shared) שמוחתם בזמן לכידה, שמירה, וייבוא |
+| **שכחה אוטומטית** | תפוגת TTL, גילוי סתירות, פינוי לפי חשיבות |
+| **פרטיות ראשית** | מפתחות API, secrets, תגי `` מוסרים לפני האחסון |
+| **החלמה עצמית (self-healing)** | circuit breaker, שרשרת fallback לספקים, מעקב health |
+| **גשר Claude** | sync דו-כיווני עם MEMORY.md |
+| **גרף ידע** | חילוץ ישויות + מעבר (traversal) מסוג BFS |
+| **זיכרון צוותי** | שיתוף + פרטיות עם namespace בין חברי הצוות |
+| **מקור ציטוט** | עקבו אחורה מכל זיכרון לתצפיות המקור |
+| **snapshots של Git** | גרסה, rollback, ו-diff על מצב הזיכרון |
+
+---
+
+
+
+שליפה בשלושה זרמים שמשלבת שלושה סיגנלים:
+
+| זרם | מה הוא עושה | מתי |
+|---|---|---|
+| **BM25** | התאמת מילות מפתח עם stemming והרחבת מילים נרדפות | פעיל תמיד |
+| **וקטור** | דמיון קוסינוס מעל embeddings צפופים | כשספק embedding מוגדר |
+| **גרף** | מעבר בגרף ידע באמצעות התאמת ישויות | כשישויות מתגלות בשאילתה |
+
+ממוזגים (fused) עם Reciprocal Rank Fusion (RRF, k=60) ומגוונים לפי session (עד 3 תוצאות ל-session).
+
+כשאינדקס וקטורי מאוכלס, `mem::search` (מאחורי `memory_recall`) משתמש ב-ranker ההיברידי של BM25 + וקטור. בלי embeddings הוא משתמש ב-BM25. `smart-search` יכול גם למזג התאמות מבניות מהגרף כשנתוני גרף קיימים, גם במצב keyless. שליפת lessons רצה על אינדקס BM25 ייעודי בזיכרון במקום לסקור את כל הקורפוס בכל שאילתה. גרסאות זיכרון שהוחלפו (superseded) מוחרגות מכל נתיב שליפה; שרשרת הגרסאות שומרת את ההיסטוריה שלהן.
+
+וקטורים שורדים קריסה או force-kill. אינדקס הווקטורים נשמר ב-buckets לכל היותר כל `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 דקות). כל וקטור שנוסף או הוסר בינתיים גם נכתב מיידית ל-log קטן של pending ב-state store, וההפעלה הבאה משדרת אותו (replay) מחדש בלי לקרוא לספק ה-embedding. כל שמירה מוצלחת מרוקנת את ה-log. מסמכים שעדיין אין להם וקטור אחרי ה-replay מוטבעים (re-embedded) מחדש ברקע ב-batches של `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) עד שלא נשאר אף אחד, ו-backfill שנעצר ממשיך בהפעלה הבאה. `/agentmemory/status` והמציג מציגים את גודל ה-log הממתין ואת מצב ה-backfill. התקנות keyless לא כותבות שום דבר.
+
+BM25 מבצע tokenization ליוונית, קירילית, עברית, ערבית, ולטינית עם סימני הטעמה ישר מהקופסה. לזיכרונות בסינית / יפנית / קוריאנית, התקינו את ה-segmenters האופציונליים (`npm install @node-rs/jieba tiny-segmenter`) כדי לפצל רצפי CJK ל-tokens בגובה-מילה; בלעדיהם, agentmemory נופל בעדינות ל-tokenization של הרצף השלם ומדפיס רמז חד-פעמי ל-stderr.
+
+### ספקי Embedding
+
+התקנות keyless משביתות embeddings וקטוריים: `mem::search` משתמש ב-BM25, בעוד ש-`smart-search` יכול גם להשתמש בנתוני גרף מבניים קיימים. כדי להפעיל embeddings סמנטיים חינמיים במכשיר עצמו, הוסיפו את זה ל-`~/.agentmemory/.env` והפעילו מחדש את agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+ה-npm install הרגיל כולל את ה-runtime האופציונלי `@huggingface/transformers`. בקשת ה-embedding הראשונה מורידה את `Xenova/all-MiniLM-L6-v2`, כך שהיא צריכה גישת רשת ויכולה לקחת יותר זמן; ההסקה הבאה רצה במכשיר עצמו. ספקים מרוחקים מתגלים אוטומטית מהמפתחות שלהם אלא אם `EMBEDDING_PROVIDER` גובר עליהם.
+
+| ספק | מודל | עלות | הערות |
+|---|---|---|---|
+| **מקומי (opt-in מומלץ)** | `all-MiniLM-L6-v2` | חינמי | במכשיר עצמו אחרי הורדת המודל הראשונה, +8pp ל-recall לעומת BM25 בלבד |
+| Gemini | `gemini-embedding-001` | שכבה חינמית | 100+ שפות, 768/1536/3072 מימדים (MRL), קלט של 2048 טוקנים. מחליף את `text-embedding-004` ([הוצא משימוש, כיבוי ב-14 בינואר 2026](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 | כל מודל | משתנה | proxy מרובה-מודלים |
+
+---
+
+
+
+54 כלים, 6 משאבים, 3 פרומפטים, ו-17 skills.
+
+> **shim MCP לעומת שרת מלא:** חבילת `@agentmemory/mcp` המתפרסמת היא shim דק. היא חושפת את שטח ה-54-הכלים המלא **רק כשהיא מצליחה להגיע לשרת agentmemory רץ** דרך `AGENTMEMORY_URL` (מצב proxy). בלי שרת נגיש, ה-shim חוזר לסט מקומי של 7 כלים (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). משתנה הסביבה `AGENTMEMORY_TOOLS=core|all` הוא דגל *בצד השרת*; הגדרתו בבלוק ה-`env` של ה-shim אין לה שום אפקט. אם אתם רואים רק 7 כלים ב-Cursor / OpenCode / Gemini CLI, הפעילו את `npx -y @agentmemory/agentmemory@latest` (או את ערימת ה-Docker) והגדירו `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 כלים
+
+שלושה שטחי כלים, מהקטן לגדול: `AGENTMEMORY_TOOLS=core` מגביל את הנראות ל-8 כלים חיוניים (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); הסט הבסיסי שלהלן הוא 14 הכלים הבסיסיים של הרשימה (registry); ברירת המחדל (`AGENTMEMORY_TOOLS=all`) חושפת את כל 54.
+
+
+כלי בסיס (14)
+
+| כלי | תיאור |
+|------|-------------|
+| `memory_recall` | חיפוש תצפיות עבר |
+| `memory_compress_file` | דחיסת קבצי markdown בשמירה על המבנה |
+| `memory_save` | שמירת תובנה, החלטה, או דפוס |
+| `memory_file_history` | תצפיות עבר על קבצים ספציפיים |
+| `memory_patterns` | גילוי דפוסים חזרתיים |
+| `memory_sessions` | רשימת sessions אחרונים |
+| `memory_smart_search` | חיפוש היברידי סמנטי + מילות מפתח |
+| `memory_vision_search` | חיפוש תצפיות תמונה |
+| `memory_timeline` | תצפיות כרונולוגיות |
+| `memory_profile` | פרופיל פרויקט (קונספטים, קבצים, דפוסים) |
+| `memory_export` | ייצוא כל נתוני הזיכרון |
+| `memory_relations` | שאילתה על גרף היחסים |
+| `memory_commit_lookup` | sessions שמאחורי git commit |
+| `memory_commits` | commits שנרשמו ל-session |
+
+
+
+
+כלים מורחבים (54 בסך הכול, שטח ברירת המחדל)
+
+| כלי | תיאור |
+|------|-------------|
+| `memory_patterns` | גילוי דפוסים חזרתיים |
+| `memory_timeline` | תצפיות כרונולוגיות |
+| `memory_relations` | שאילתה על גרף היחסים |
+| `memory_graph_query` | מעבר בגרף ידע |
+| `memory_consolidate` | הרצת קונסולידציה ב-4 שכבות |
+| `memory_claude_bridge_sync` | sync עם MEMORY.md |
+| `memory_team_share` | שיתוף עם חברי הצוות |
+| `memory_team_feed` | פריטים משותפים אחרונים |
+| `memory_audit` | audit trail של פעולות |
+| `memory_governance_delete` | מחיקה עם audit trail |
+| `memory_snapshot_create` | snapshot עם ניהול גרסאות ב-Git |
+| `memory_action_create` | יצירת פריטי עבודה עם תלויות |
+| `memory_action_update` | עדכון סטטוס action |
+| `memory_frontier` | actions לא חסומים ממוינים לפי עדיפות |
+| `memory_next` | ה-action הבא החשוב ביותר |
+| `memory_lease` | leases בלעדיים ל-action (ריבוי-סוכנים) |
+| `memory_routine_run` | הפעלת routines של workflow |
+| `memory_signal_send` | הודעות בין-סוכנים |
+| `memory_signal_read` | קריאת הודעות עם אישורי קבלה |
+| `memory_checkpoint` | שערי תנאי חיצוניים |
+| `memory_mesh_sync` | sync מסוג P2P בין instances |
+| `memory_sentinel_create` | watchers מבוססי-אירועים |
+| `memory_sentinel_trigger` | הפעלת sentinels מבחוץ |
+| `memory_sketch_create` | גרפי action זמניים |
+| `memory_sketch_promote` | קידום לקבוע |
+| `memory_crystallize` | דחיסת שרשראות action |
+| `memory_diagnose` | בדיקות health |
+| `memory_heal` | תיקון אוטומטי של מצב תקוע |
+| `memory_facet_tag` | תגים מסוג dimension:value |
+| `memory_facet_query` | שאילתה לפי תגי facet |
+| `memory_verify` | עקיבה אחר מקור (provenance) |
+
+
+
+### 6 משאבים · 3 פרומפטים · 17 Skills
+
+| סוג | שם | תיאור |
+|------|------|-------------|
+| משאב | `agentmemory://status` | Health, ספירת sessions, ספירת זיכרונות |
+| משאב | `agentmemory://project/{name}/profile` | אינטליגנציה לפי פרויקט |
+| משאב | `agentmemory://project/{name}/recent` | תצפיות אחרונות לפרויקט |
+| משאב | `agentmemory://memories/latest` | 10 הזיכרונות הפעילים האחרונים |
+| משאב | `agentmemory://graph/stats` | סטטיסטיקות גרף ידע |
+| משאב | `agentmemory://team/{id}/profile` | פרופיל צוות משותף |
+| פרומפט | `recall_context` | חיפוש + החזרת הודעות הקשר |
+| פרומפט | `session_handoff` | נתוני handoff בין סוכנים |
+| פרומפט | `detect_patterns` | ניתוח דפוסים חזרתיים |
+| Skill | `/recall` | חיפוש בזיכרון |
+| Skill | `/remember` | שמירה לזיכרון ארוך-טווח |
+| Skill | `/session-history` | סיכומי sessions אחרונים |
+| Skill | `/forget` | מחיקת תצפיות/sessions |
+
+הטבלה מציגה את ארבעת ה-skills הבסיסיים. הסט המלא הוא 9 skills שניתן להפעיל בתוספת 8 skills של עיון; ראו את סקשן ה-skills המובנים מעלה.
+
+### MCP עצמאי (Standalone)
+
+הריצו בלי השרת המלא, לכל לקוח MCP. כל אחת מהאפשרויות האלה עובדת:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+או הוסיפו לתצורת ה-MCP של הסוכן שלכם:
+
+רוב הסוכנים (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+מזגו את הרשומה `agentmemory` לתוך האובייקט `mcpServers` הקיים של ה-host שלכם במקום להחליף את הקובץ. ללקוחות ב-sandbox שלא יכולים להגיע ל-`localhost` של ה-host, הוסיפו `"AGENTMEMORY_FORCE_PROXY": "1"` לבלוק ה-env והגדירו את `AGENTMEMORY_URL` למסלול שה-sandbox יכול להגיע אליו.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+העתיקו את קובץ ה-plugin מה-repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+מופעל אוטומטית בפורט `3113`. המציג טוען snapshot אחד כשהוא מתחבר (`GET /agentmemory/viewer/snapshot`) ואז מחיל אירועי stream חיים: זיכרונות חדשים, lessons, תצפיות, רשומות audit, שינויי גרף ועדכוני health מופיעים בלי polling או רילוד של הדף. הבקשות האחרות היחידות הן הפעולות שאתם מקליקים, עמודי "טען עוד" וחיפושים. כשה-stream נופל, המציג מציג כמה זמן המספרים שלו ישנים, מתחבר מחדש עם backoff ומסתנכרן מחדש מ-snapshot אחד.
+
+- **12 לשוניות בארבע קבוצות** עם ספירות חיות, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), קיצורי מקלדת, ותפריט מובייל.
+- **זיכרונות:** חיפוש בצד השרת, filters לפי פרויקט, סוכן וסוג, פאנל פרטים עם שרשרת הגרסאות ו-word diff, קישורי provenance, כפתורי copy למזהה, לקריאת ה-MCP ולפקודת curl, עריכה (גרסה חדשה), forget עם אישור, forget בכמות (bulk) וייצוא JSON.
+- **Sessions:** ציר זמן תצפיות inline עם קלט ופלט tool קריאים, filters ו-paging, והזיכרונות וה-lessons שכל session הפיק.
+- **גרף:** חיפוש, פרטי node עם יחסים ומקורות, legend שלא מתבסס על צבע בלבד, ובקרות zoom.
+- **Health:** הגרסה החיה של `GET /agentmemory/status`. לכל בעיה מגיע התיקון שלה, בתוספת ה-state backend, מצב שמירת האינדקס, התקדמות הדחיסה (compaction) של provenance בגרף, ומסביר קונסולידציה עם הסֲפים האמיתיים.
+- עמודי **Audit, Activity, Profile, Replay, Lessons, Actions ו-Crystals**, כל אחד עם מצב ריק שאומר מה הסקשן הזה, למה הוא ריק, ואיזו פקודה מאכלסת אותו, ותיאור tooltip של `?` בכל מונח ומספר.
+
+```bash
+open http://localhost:3113
+```
+
+שרת המציג נקשר (bind) ל-`127.0.0.1` כברירת מחדל ומצרף את ה-secret של השרת כשהוא מעביר בקשות ל-REST API, כך שהוא לא דורש הגדרה. ה-endpoint `/agentmemory/viewer` המוגש דרך REST עוקב אחרי כללי bearer-token הרגילים ומפנה דפדפנים בלי token לפורט המציג. כותרות CSP משתמשות ב-nonce של script לכל תגובה ומשביתות attributes של handler inline (`script-src-attr 'none'`).
+
+---
+
+
+
+המציג בפורט `:3113` מציג מה הסוכן שלכם **זכר**. [קונסולת iii](https://iii.dev/docs/console) מציגה מה הסוכן שלכם **עשה**: כל פעולת זיכרון כ-trace של OpenTelemetry, כל רשומת KV ניתנת לעריכה, כל פונקציה ניתנת להפעלה, כל stream ניתן להאזנה (tap). שני חלונות על אותו זיכרון: אחד בצורת מוצר, אחד בצורת מנוע.
+
+צפו ב-`memory_smart_search` מופעל וראו את סריקת ה-BM25 → חיפוש ה-embedding → fusion של RRF → reranker כ-waterfall. ערכו טיימר קונסולידציה תקוע ב-KV browser. בצעו replay ל-hook `PostToolUse` עם payload משופר. הצמידו (pin) את ה-stream של ה-WebSocket וצפו בתצפיות נוחתות בשידור חי.
+
+agentmemory מקבל את זה בחינם כי כל קריאת פונקציה וכל trigger עוברים דרך iii; שום דבר מותאם אישית, שום דבר להתקין לו instrumentation.
+
+
+
+
+ עמוד ה-Workers: כל worker מחובר, כולל agentmemory עצמו, עם PID, ספירת פונקציות, runtime, ו-last-seen.
+
+
+**מותקן כבר.** הקונסולה נשלחת עם מנוע ה-`iii` הנעוץ (0.22+); אין צורך להתקין שום דבר בנפרד. ההפעלה הראשונה מורידה את הבינארי של הקונסולה לצד המנוע.
+
+**הפעלה לצד agentmemory:**
+
+```bash
+agentmemory console
+```
+
+זה מריץ את `iii console` של המנוע הנעוץ מול הפורטים ש-agentmemory פתר (REST, streams, bridge) ומגיש אותה פורט אחד מעל המציג, `http://localhost:3114` כברירת מחדל. `--console-port N` בוחר פורט אחר; `--port` ו-`--instance` בוחרים את instance ה-agentmemory באותו אופן שהם עושים ל-`stop`; כל דגל אחר מועבר הלאה, למשל `--enable-flow` לעמוד גרף הארכיטקטורה הניסיוני.
+
+אותו דבר ביד, שימושי כש-`agentmemory` לא נמצא ב-PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**מה אפשר לעשות מהקונסולה:**
+
+| עמוד | לשם מה להשתמש בו |
+|------|-----------|
+| **Workers** | לראות כל worker מחובר ואת המטריקות החיות שלו, כולל ה-worker של agentmemory עצמו. |
+| **Functions** | להפעיל כל פונקציה של agentmemory ישירות עם payload של JSON; שימושי לבדיקת `memory.recall`, `memory.consolidate`, `graph.query` בלי לחווט לקוח. |
+| **Triggers** | לבצע replay ל-triggers מסוג HTTP, cron, event, ו-state: להפעיל את ה-cron של הקונסולידציה ידנית, לנסות שוב route של HTTP, לפלוט שינוי state. |
+| **States** | KV browser עם CRUD מלא על sessions, memory slots, טיימרי מחזור חיים, ואינדקס ה-embeddings; עריכת ערכים במקום. |
+| **Streams** | מוניטור WebSocket חי לכתיבות זיכרון, אירועי hook, ועדכוני תצפית כשהם זורמים דרך streams של iii. |
+| **Queues** | נושאי queue מתמשכים + ניהול dead-letter. replay או drop לעבודות embedding / דחיסה שנכשלו. |
+| **Traces** | תצוגות waterfall / flame / פירוק-לפי-שירות של OpenTelemetry. סננו לפי `trace_id` כדי לראות בדיוק אילו functions, קריאות DB, ובקשות embedding יצר `memory.search` בודד. |
+| **Logs** | logs מבניים של OTEL מסוננים ומקושרים (correlated) למזהי trace/span. |
+| **Config** | תצורת runtime: לראות בדיוק עם אילו workers, ספקים, ופורטים המנוע שלכם רץ. |
+| **Flow** | (אופציונלי, `--enable-flow`) גרף ארכיטקטורה אינטראקטיבי של כל worker, trigger, ו-stream. |
+
+
+
+
+ Traces: waterfall / flame / פירוק-שירות לכל פעולת זיכרון.
+
+
+**Traces כבר פעילים:**
+
+`iii-config.yaml` נשלח עם ה-worker `iii-observability` מופעל (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). אין צורך בתצורה נוספת; ברגע ש-agentmemory מתחיל, כל פעולת זיכרון פולטת log מבני שהקונסולה יכולה לקרוא, ואחת מכל עשר מהן (`sampling_ratio: 0.1`) פולטת גם span של trace.
+
+אם אתם רוצים לייצא ל-Jaeger/Honeycomb/Grafana Tempo במקום, שנו את `exporter: memory` ל-`exporter: otlp` והגדירו את ה-endpoint של ה-collector לפי תיעוד ה-observability של iii.
+
+> **שימו לב:** אין auth מאולץ על הקונסולה עצמה; השאירו אותה קשורה ל-`127.0.0.1` (ברירת המחדל) ואל תחשפו אותה לעולם באופן ציבורי.
+
+---
+
+
+
+agentmemory הוא **כבר instance רץ של [iii](https://iii.dev)**. שלושה primitives (worker, function, trigger) מרכיבים את ה-runtime; מצב KV, streams, ו-OTEL traces מגיעים מ-workers בשם iii-state, iii-stream, ו-iii-observability שמגיעים עם iii. לא התקנתם Postgres, Redis, Express, pm2, או Prometheus, כי iii מחליף אותם.
+
+זה אומר שפקודה אחת נוספת מרחיבה את agentmemory עם יכולת חדשה שלמה.
+
+### הרחבת agentmemory עם עוד workers
+
+ה-builtins ש-agentmemory צריך נמצאים כבר ב-`iii-config.yaml` ועולים (boot) איתו: `iii-state` (KV), `iii-queue` (retries מתמשכים למנויי האירועים), `iii-pubsub`, `iii-cron`, `iii-stream`, ו-`iii-observability` (OTEL traces, metrics ו-logs על כל פונקציה). כל דבר אחר מ-[רשימת ה-workers של iii](https://workers.iii.dev) מתחבר לאותו מנוע: העתיקו את `iii-config.yaml` ל-`~/.agentmemory/iii-config.yaml` (ה-CLI מעדיף את הקובץ הזה על פני המצורף ועדיין מרנדר אליו ports ו-paths של נתונים), הוסיפו את הרשומה, התקינו את ה-runtime של ה-worker פעם אחת עם `~/.agentmemory/bin/iii update worker`, והפעילו מחדש את agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | מה אתם מקבלים בנוסף ל-agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | מתאם state מבוסס-SQL כשאתם גדלים מעבר לברירות המחדל של KV בזיכרון |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | קוד שיצא מ-`memory_recall` רץ בתוך VM חד-שימושי, לא ב-shell שלכם |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | הקימו שרתי MCP נוספים לצד זה של agentmemory, שתפו את אותו מנוע |
+
+במנוע 0.22.x השאירו את השמות עם ה-prefix `iii-` עבור ה-builtins שלמעלה; הרשומות בלי prefix `http`, `state`, `queue`, `pubsub` ו-`cron` הן ה-workers העצמאיים מהרשימה (registry) ש-agentmemory עובר אליהם עם מעבר הגרסה ל-0.23.
+
+רשימה (registry) מלאה: [workers.iii.dev](https://workers.iii.dev). כל worker שם מורכב (composes) דרך אותם primitives ש-agentmemory משתמש בהם, וה-agentmemory שכבר יש לכם הוא אחד מהם.
+
+### תצורת מנוע וכתובת bind
+
+`agentmemory start` קורא את תצורת המנוע מהקובץ הראשון שקיים: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` בתיקייה הנוכחית, `~/.agentmemory/iii-config.yaml`, ואז `iii-config.yaml` המצורף. בכל הפעלה הוא מרנדר את הקובץ הזה (paths של נתונים, ports, state backend) לתוך `~/.agentmemory/data/iii-config.runtime.yaml` ומפעיל את המנוע עם העותק המרונדר, אז יש לערוך את קובץ המקור, לא את המרונדר. ערכי `host:` של קובץ המקור נשמרים כמו שהם נכתבו.
+
+ה-`iii-config.yaml` המצורף נקשר ל-`127.0.0.1` בכוונה, וברירת המחדל הזו חלה גם בתוך container. CLI שמופעל בתוך container מקשיב ל-loopback של ה-container, כך שה-ports המפורסמים לא מגיעים לשום מקום. כדי להגיש CLI בתוך container דרך ports מפורסמים, הגדירו את `AGENTMEMORY_III_CONFIG` לתצורה שנקשרת ל-`0.0.0.0`. ה-`iii-config.docker.yaml` הארוז הוא אחת כזו: היא קושרת את `iii-http`, `iii-stream` ואת port המנוע ל-`0.0.0.0` ושומרת את ה-state תחת `/data`, אז יש לקשר volume לכתיבה שם. השאירו את `AGENTMEMORY_SECRET` מוגדר, ופרסמו רק את ה-ports שאתם צריכים, על `127.0.0.1` או מאחורי proxy שאתם סומכים עליו.
+
+ה-`docker-compose.yml` של ה-repo הזה לא עובר דרך חיפוש התצורה של ה-CLI: הוא מקשר את `iii-config.docker.yaml` ב-`/app/config.yaml`, וה-container `iii-engine` מתחיל עם `--config /app/config.yaml`. [תבניות הפריסה](../deploy/) בלחיצה אחת כותבות תצורת `0.0.0.0` משלהן ב-entrypoints שלהן.
+
+### Storage backend: file (ברירת מחדל) לעומת redis
+
+`iii-state` ו-`iii-stream` כברירת מחדל משתמשים במאגר KV מבוסס-קבצים המצורף של iii-engine: קובץ JSON אחד לכל scope, מוחזק בזיכרון של תהליך המנוע ונכתב מחדש לדיסק בטיימר. זו ברירת המחדל הנכונה להתקנה מקומית למשתמש בודד; daemon משותף עם כמה כותבים (writers) מקבילים מקבל במקום זאת כתיבות אמיתיות per-key מ-Redis, במחיר של round trip רשת בכל פעולה (כל קריאת `state::*` עדיין מסתדרת (serializes) על חיבור Redis אחד, אז זה מחליף את ה-lock של מאגר הקבצים ב-socket, לא בפרלליות).
+
+הגדירו `AGENTMEMORY_STATE_BACKEND=redis` (בתוספת `AGENTMEMORY_REDIS_URL`) כדי להחליף את שני ה-workers למתאם ה-`redis` המובנה של iii-engine, שמאחסן כל מפתח כשדה hash של Redis (`HSET`) במקום לכתוב מחדש scope שלם בכל כתיבה:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` כברירת מחדל הוא `file`; השארתו לא מוגדרת משאירה את ההתנהגות הנוכחית ללא שינוי, וערך לא מוכר (כל דבר חוץ מ-`file` או `redis`) הוא שגיאת startup ולא fallback שקט. `/agentmemory/status` ועמוד ה-Health של המציג (שורת State store) מדווחים איזה backend פעיל ואם הוא עונה, לעולם לא את ה-URL.
+
+**`redis://` רגיל בלבד.** המנוע הנעוץ (0.22.1) בונה את לקוח ה-Redis שלו בלי תמיכת TLS, כך ש-URL מסוג `rediss://` (רוב שירותי ה-Redis המנוהלים, כמו Upstash, Redis Cloud, ו-ElastiCache עם הצפנה in-transit, שברירת המחדל שלהם היא TLS-only) נכשל להתחבר. החיבור לא מוצפן, כך שהסיסמה של Redis וכל זיכרון שמאוחסן עוברים ב-wire בטקסט גלוי: הפנו ל-Redis מקומי או כזה ברשת פרטית שאתם סומכים עליה. לכל Redis אחר, הריצו tunnel מוצפן (stunnel, SSH, או VPN) על ה-host של agentmemory, כך שה-hop של `redis://` הרגיל נשאר על ה-host הזה והחיבור upstream של ה-tunnel מוצפן ומאומת. אם סיסמת Redis מכילה גרש בודד, בצעו לה percent-encode (`%27`); המנוע מרחיב את ה-URL לתוך תצורת ה-YAML שלו לפני ה-parsing.
+
+**שרת Redis אחד לכל `--instance`.** ה-prefixes של מפתחות Redis של המנוע (`state:`, `stream::`) קבועים, כך ששני instances של agentmemory (`--instance 1`, `--instance 2`, ...) שמצביעים על אותו database כותבים זה על גבי הנתונים של זה. אינדקס database נפרד (`redis://localhost:6379/1`) מפריד בין הנתונים המאוחסנים, אבל המנוע מעביר אירועי מציג חיים מעל ערוץ pub/sub אחד של Redis (`stream::events`), ו-pub/sub של Redis מתעלם מאינדקס ה-database, כך שהמציג של כל instance עדיין יראה את האירועים החיים של האחר. תנו לכל instance שרת Redis משלו (או port) כשאתם מריצים יותר מאחד.
+
+**מה נשאר אותו דבר, ומה שונה.** כל יכולת של agentmemory עובדת על Redis: sessions, תצפיות, זיכרונות (remember, supersede, evolve, forget), חיפוש ו-buckets של האינדקס, lessons, הגרף, audit log וה-scopes החודשיים שלו, ייצוא וייבוא, מחיקות governance, סטטוס קונסולידציה, ה-snapshot של המציג וה-stream החי שלו, ומוניטור ה-health. המנוע מאחסן כל scope כ-hash אחד של Redis (`HSET`/`HGET`/`HGETALL`) ומפעיל את אותם state triggers כמו מאגר הקבצים. שלושה הבדלי מנוע מטופלים בתוך agentmemory:
+
+- Redis מחזיר את הרשומות של scope בלי סדר קבוע. agentmemory ממיין אותן מהישן ביותר ראשון (לפי זמן היצירה שבתוך מזהה הרשומה, ואז ה-timestamp שלה) כך ש-lists, paging, ו-chunks של ייצוא חוזרים באותו סדר כמו במאגר הקבצים.
+- המנוע מחיל עדכונים חלקיים על Redis בסקריפט Lua שמהפך מערכים ריקים לאובייקטים ריקים. agentmemory מחיל את העדכונים האלה בעצמו (read, change, write תחת lock per-key) על Redis, כך ששדות כמו `tags: []` נשארים מערכים.
+- בדיקת ה-audit log הישנה (legacy) קוראת את ה-scope הישן מ-Redis במקום לחפש את הקובץ של מאגר הקבצים על הדיסק.
+
+הבדל אחד דורש מכם פעולה: **אחרי ש-Redis מופעל מחדש, המנוע מפסיק להעביר אירועים חיים** למציג עד ש-agentmemory מופעל מחדש. הנתונים עדיין נשמרים ונקראים כרגיל. מוניטור ה-health שולח אירוע בדיקה דרך Redis כל 30 שניות; כשהוא לא חוזר, `/agentmemory/status` ועמוד ה-Health של המציג מציגים "Live updates are not reaching the viewer" עם התיקון: הפעילו מחדש את agentmemory. אם Redis למטה, דוח הסטטוס מציג "The state store is not answering" ואיך לבדוק את זה (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). רישום (listing) של scope גדול מאוד קורא את כל ה-hash ב-`HGETALL` אחד, אותו עלות כמו מאגר הקבצים שמחזיק אותו בזיכרון.
+
+**הגדרות Redis מומלצות.** מדיניות ה-snapshot של ברירת המחדל `save 3600 1 300 100 60 10000` יכולה להפסיד דקות של כתיבות בקריסה, גרוע יותר מחלון ה-flush של 5 שניות של מאגר הקבצים. הגדירו `appendonly yes` לכל דבר שיהיה לכם חשוב לא להפסיד. הגדירו `maxmemory-policy noeviction`; `allkeys-lru` או דומה מפילים זיכרונות בשקט כש-Redis מגיע למגבלת הזיכרון שלו.
+
+הפעלה native (לא-Docker), וכל [תבנית פריסה](../deploy/) בלחיצה אחת (הן כותבות מחדש את `iii-config.yaml` המצורף ומתחילות native), קוראות את `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` ומרנדרות אותן לתוך ה-`iii-config` שמופעל. ה-URL עצמו לעולם לא נכתב לקובץ המרונדר הזה, רק reference מסוג `${AGENTMEMORY_REDIS_URL}` שתהליך המנוע מרחיב מהסביבה שלו עצמו באתחול. רק נתיב ה-Docker Compose של ה-repo הזה עצמו (`AGENTMEMORY_USE_DOCKER=1`, או חידוש מנוע שהופעל כך) מקשר את `iii-config.docker.yaml` לקריאה-בלבד ולא מרנדר לעולם; `agentmemory start` מזהיר כשהוא מגלה את הצירוף הזה. החליפו את הקובץ הזה ביד, בעקבות אותו מבנה `name: redis` / `config: redis_url: ...` שמוצג בתיעוד ה-workers של [iii-state](https://workers.iii.dev/workers/iii-state) ו-[iii-stream](https://workers.iii.dev/workers/iii-stream), והפנו את `redis_url` ל-Redis נגיש מה-container. `docker-compose.yml` מעביר את `AGENTMEMORY_REDIS_URL` לתוך container המנוע, כך ש-`redis_url: '${AGENTMEMORY_REDIS_URL}'` עובד שם ושומר את ה-URL מחוץ לקובץ המקושר.
+
+התצורה המרונדרת שומרת את ה-URL מחוץ ל-`~/.agentmemory/data/iii-config.runtime.yaml`, אבל ה-worker של התצורה של המנוע עצמו עדיין שומר באופן קבוע את הערך *המורחב* ל-`~/.agentmemory/config/iii-state.yaml` ול-`iii-stream.yaml` ברגע שהוא עולה (ה-הרחבה של `${VAR}` ב-iii-engine קורית לפני שה-worker הזה שומר את ה-seed שלו, והוא שומר את הערך שנפתר, לא את ה-reference). התייחסו לתיקייה הזו כמחזיקה credential: `chmod 700 ~/.agentmemory` בכל host משותף, והעדיפו משתמש ACL של Redis שמוגבל-תחום למה ש-agentmemory צריך על פני ה-credentials המנהליים של ה-database.
+
+**מיגרציה היא לא אוטומטית.** החלפת `AGENTMEMORY_STATE_BACKEND` מתחילה ממאגר ריק בשני הצדדים; שום דבר לא מעתיק נתונים קיימים מ-file ל-Redis או חזרה. ייצאו מה-backend שאתם עוזבים וייבאו לזה שאתם עוברים אליו. זה רץ זהה תחת bash ו-zsh (כולל `bash -u`). מערך כמו `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` לא: zsh משאיר את ה-header כמילה מעוותת אחת במקום ש-bash מפצל אותה לשתיים, כך ששתי הבקשות מקבלות 401 תמיד כש-`AGENTMEMORY_SECRET` מוגדר:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` גם מקבל `?maxSessions=` ו-`?offset=` לחלוקה (chunking) של קורפוס גדול על פני כמה קריאות; `strategy` בייבוא הוא `merge` (בטוח כברירת מחדל), `replace`, או `skip`.
+
+### מה iii מחליף
+
+| ערימה מסורתית | agentmemory משתמש ב |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + אינדקס וקטורי בזיכרון |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | פיקוח (supervision) workers של מנוע iii |
+| Prometheus / Grafana | iii OTEL + מוניטור health |
+| מערכות plugin מותאמות אישית | `iii worker add ` |
+
+**225 קבצי מקור · ~54,000 LOC · 2,600+ בדיקות · 312 פונקציות · 66 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
+
+---
+
+
+
+### ספקי LLM
+
+agentmemory מגלה ספקים אוטומטית מהסביבה שלכם. ספק מאפשר פעולות מגובות-LLM, אבל תצורת ספק בלבד לא מפעילה דחיסת תצפיות בכתיבת LLM. הנתיב הזה דורש גם ספק וגם `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| ספק | תצורה | הערות |
+|----------|--------|-------|
+| **No-op (ברירת מחדל)** | לא נדרשת תצורה | דחיסה/סיכום מגובי-LLM מושבתים. דחיסה סינתטית ושליפת BM25 עדיין עובדים. ראו `AGENTMEMORY_ALLOW_AGENT_SDK` מתחת אם הייתם רגילים להסתמך על ה-fallback של מנוי Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | חיוב לפי טוקן |
+| MiniMax | `MINIMAX_API_KEY` | תואם-Anthropic |
+| Gemini | `GEMINI_API_KEY` | מפעיל גם embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | כל מודל |
+| OpenAI API | `OPENAI_API_KEY` | ברירת מחדל `gpt-5.6-luna`, override עם `OPENAI_MODEL` |
+| **מקומי (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) או `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | כל דבר תואם-OpenAI-API. עלות אפס, רץ על החומרה שלכם. ראו [מודלים מקומיים](#local-models-ollama--lm-studio--vllm) מתחת. |
+| fallback למנוי Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | opt-in בלבד. יוצר sessions של `@anthropic-ai/claude-agent-sdk`; זה היה גורם לרקורסיה לא חסומה של Stop-hook, אז זה כבר לא ברירת המחדל. |
+
+### מודלים מקומיים (Ollama / LM Studio / vLLM)
+
+agentmemory מדבר עם כל שרת תואם-OpenAI-API, כך שכל דבר שחושף `/v1/chat/completions` עובד בלי שינויי קוד. בלי מפתחות בתשלום, בלי cloud, בלי rate limits; רץ כולו על החומרה שלכם.
+
+**Ollama** (port ברירת מחדל `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (port ברירת מחדל `1234`):
+
+פתחו את LM Studio → לשונית Local Server → Start Server. בחרו כל chat model מהבורר (Qwen 3, gpt-oss, DeepSeek R1, וכו').
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: אותו מבנה. הפנו את `OPENAI_BASE_URL` לכל URL שהשרת שלכם חושף והגדירו את `OPENAI_MODEL` לשם שהשרת שלכם יקבל.
+
+**בחירת מודל לעבודת זיכרון**: דחיסה וסיכום הן משימות קצרות (<2K טוקנים בכניסה, <500 טוקנים בפלט) שבהן מודל instruct בגודל 7B מספיק בהחלט. המלצות:
+
+| מודל | גודל | למה |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | ברירת מחדל מאוזנת במכונה בת 16 GB; חזק בחילוץ ובטקסט בצורת tool |
+| `qwen3:4b` | ~2.6 GB | האפשרות הקטנה הסבירה ביותר; בסדר לדחיסה, חלש יותר לחילוץ גרף |
+| `qwen3-coder:30b` | ~19 GB | הבחירה המקומית הטובה ביותר ל-sessions בצורת קוד (30B MoE, 3.3B פעיל) על חומרה בת 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | מודל כללי חזק שמתאים ל-16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | distill הסקתי (reasoning); יותר איטי אבל חילוצים נקיים יותר |
+
+מודלים של Qwen 3 חושבים כברירת מחדל ויכולים לשרוף את כל תקציב הטוקנים על reasoning לפני כל פלט. הגדירו `AGENTMEMORY_LLM_NOTHINK=1` כדי להוסיף `/no_think` ל-prompts של חילוץ גרף, והעלו את `MAX_TOKENS` (16384 עובד) אם חילוצים חוזרים ריקים.
+
+מודלים ממחלקת reasoning (בסטייל `o1` עם בלוקי ``) יכולים להחזיר `content` ריק עם שדה `reasoning` שהשרת המקומי שלכם אולי לא חושף. אם חילוצים חוזרים ריקים, עברו קודם למודל שאינו reasoning. משתנה הסביבה `OPENAI_REASONING_EFFORT=none` יכול גם להשבית thinking במודלי thinking של Ollama Cloud שמשקפים את schema ה-reasoning של OpenAI.
+
+embeddings מקומיים נשלחים כתלות אופציונלית אבל לא מופעלים כברירת מחדל. הגדירו `EMBEDDING_PROVIDER=local` כדי להפעיל את `Xenova/all-MiniLM-L6-v2` (384 מימדים). בקשת ה-embedding הראשונה מורידה את המודל; ההסקה רצה במכשיר עצמו לאחר מכן. בלי ההגדרה הזו או מפתח embedding מרוחק, הווקטורים נשארים מושבתים, `mem::search` משתמש ב-BM25, ו-`smart-search` יכול עדיין להוסיף התאמות גרף קיימות.
+
+### בחירת מודל מודעת-עלות
+
+כשדחיסת רקע בכתיבת LLM מופעלת עם גם ספק וגם `AGENTMEMORY_AUTO_COMPRESS=true`, היא רצה על כל תצפית, כך שבחירת המודל משנה באופן משמעותי את ההוצאה החודשית. נתוני עומס-עבודה שנלכדו: 635 בקשות / 888K טוקנים / 35 שעות של שימוש פעיל, רצו מול שלושה מודלים של OpenRouter בתמחור מתאריך 2026-05-23.
+
+| שכבה | מודל | קלט / 1M | פלט / 1M | עלות ל-35 השעות שנלכדו | הערות |
+|------|-------|------------|-------------|---------------------------|-------|
+| מומלץ | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (מוערך) | DeepSeek העדכני ביותר; הבחירה המומלצת הזולה ביותר לעומסי דחיסה. |
+| מומלץ | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | איכות דחיסה + סיכום סולידית במחיר נמוך בכ-10× מ-Sonnet. |
+| מומלץ | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | reasoning קוד חזק אם ה-sessions שלכם בעיקר בצורת קוד. |
+| פרימיום | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (מוערך) | אותו מחיר מחירון כמו ההרצה הנמדדת של Sonnet 4.6; תמחור היכרות $2/$10 עד 2026-08-31. |
+| פרימיום | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (מוערך) | שכבת flagship; יקר לעבודת רקע תמידית. |
+| הימנעו | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (מוערך) | מודל ממחלקת flagship; overspend לדחיסה. |
+
+שורות נמדדות מגיעות מההרצה שנלכדה; שורות (מוערך) מקנות קנה מידה (scale) לאותו mix טוקנים לפי מחיר המחירון של כל מודל.
+
+agentmemory מדפיס אזהרת runtime כש-`OPENROUTER_MODEL` מתאים לתבנית שכבת-פרימיום. הגדירו `AGENTMEMORY_SUPPRESS_COST_WARNING=1` להשתיק אחרי שעשיתם בחירה מיודעת.
+
+trade-off איכות לעומת עלות לעבודת זיכרון: דחיסה היא משימת סיכום עם סף איכות יחסית רפוי (הסוכן קורא מחדש את הסיכום, לא המשתמש). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder נוחתים בטווח שגיאת עיגול מ-Sonnet במשימה הזו בעוד שהם עולים 10-70× פחות. שמרו את המודלים משכבת-הפרימיום לשאילתות שאתם קוראים ישירות.
+
+מקורות: [תמחור OpenRouter ל-Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [הערות תמחור DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### זיכרון multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+בהקמות multi-agent שבהן כמה תפקידים חולקים שרת 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 # optional; default "shared"
+```
+
+שני מצבים:
+
+| מצב | מתייג כתיבות | מסנן שליפה | מתי להשתמש |
+|------|------------|---------------|-------------|
+| `shared` (ברירת מחדל) | כן | לא | הקשר בין-סוכנים עם audit trail. ה-architect יכול לראות מה ה-developer ציין, אבל כל שורה רושמת מי אמר את זה. |
+| `isolated` | כן | כן | הפרדה מחמירה. ה-architect לעולם לא רואה את התצפיות / הזיכרונות / ה-sessions של ה-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`. כל endpoint מקבל `?agentId=` לבצע override לפי-בקשה, ו-`?agentId=*` לפרוש כליל מתחום הסביבה. `/memories` מקבל גם `?includeOrphans=true` כדי להציג זיכרונות מלפני-AGENT_ID שה-`agentId` שלהם לא מוגדר.
+
+override לפי-קריאה בשכבת SDK / REST: כל endpoint משנה (`/session/start`, `/remember`) מקבל שדה `agentId` בגוף הבקשה שגובר על הסביבה. שימושי ל-runtimes שמנתבים הרבה תפקידים דרך תהליך שרת אחד. הכלי `memory_save` של MCP חושף את אותו שדה `agentId`, שרת ה-stdio העצמאי מעביר גם `agentId` וגם `project`, וזיכרונות שנשמרו נושאים `agentId` לתוך אינדקס החיפוש, כך שחיפוש בתחום-סוכן מכסה גם זיכרונות וגם תצפיות.
+
+כש-`AGENT_ID` לא מוגדר, הזיכרון נשאר בלי-תחום (unscoped) (התנהגות legacy, בלי תגים, בלי סינונים).
+
+### פורטים
+
+agentmemory + iii-engine נקשרים לארבעה ports כברירת מחדל. אם הפעלה מחדש נכשלת עם `port in use`, הטבלה הזו אומרת לכם לאיזה תהליך לחפש.
+
+| Port | תהליך | מטרה | override של משתנה סביבה |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | worker סטרימינג פנימי (נצרך על ידי agentmemory + המציג) | `III_STREAM_PORT` (מועדף) או ה-legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | מציג בזמן אמת (`http://localhost:3113`) | `III_VIEWER_PORT` או `AGENTMEMORY_VIEWER_URL` ל-URL המדווח |
+| `49134` | iii-engine | WebSocket; workers נרשמים כאן, טלמטריית OTel זורמת מעליו | `III_ENGINE_PORT` או `III_ENGINE_URL` |
+
+`--port ` משנה את העוגן (anchor) של REST ומגזיר ממנו streams ב-`N+1`, מציג ב-`N+2`, ו-WebSocket של המנוע ב-`N+46023`, רק במקום שבו ה-port או ה-URL המפורש המתאים שלמעלה לא מוגדר. זה לא יוצר namespace מבודד למחזור חיים. השתמשו ב-`--instance 1` ל-daemon שני; הוא משתמש בעוגן 3211, ברירת מחדל `3211/3212/3213/49234`, ומקבל תיקיית data ומחזור-חיים נפרדת `instance-1`. Instances 1 עד 50 הולכים לפי אותה תבנית.
+
+המנוע הנעוץ מתחיל עם `--no-update-check` (בלי בדיקות עדכון או security-advisory מול GitHub באתחול) ועם הטלמטריית השימוש האנונימית של iii כבויה: agentmemory מגדיר `III_TELEMETRY_ENABLED=false` למנוע שהוא יוצר אלא אם אתם מייצאים (export) את המשתנה בעצמכם, וקובץ ה-compose המצורף עושה את אותו דבר.
+
+ניקוי תהליכים תקועים (stale) כש-ports נשארים קשורים אחרי הרצה שקרסה:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` אוסף (reaps) בצורה נקייה גם את ה-worker וגם את pidfile המנוע ב-shutdown מקורי (native) מסודר. במצב Docker הוא מרוקן את ה-worker המקורי, עוצר את ה-container המדויק של המנוע שאומת, ושומר גם את ה-container וגם את ה-mount שלו ב-`/data` להפעלה מחדש בלי אובדן; ההפעלה הבאה מאמתת ומחדשת את אותו container. הסרת התקנה מבוססת-Docker דורשת `agentmemory remove --keep-data`: היא מסירה קבצים משותפים שמנוהלים על ידי agentmemory בזמן שהיא משמרת את ה-container שאומת, את ה-mount של הנתונים שלו, ואת רשומת מחזור-החיים הנחוצה כדי לשחזר אותם. מחיקת נתוני Docker הרסנית מושארת בכוונה למפעיל אחרי backup. ה-CLI גם מסרב לאמץ או לאותת ל-port holders של Docker או VM (Docker backend, vpnkit, colima) כמנוע native אלא אם `--force` מועבר. הניקוי הידני שלמעלה הוא רק למקרה של אחרי-קריסה שבו לא נשאר שום pidfile.
+
+### קובץ תצורה
+
+שימו את תצורת ה-runtime של agentmemory ב-`~/.agentmemory/.env` במקום לייצא (export) משתנים בכל shell. אם המציג מציג רמז הקמה כמו `export ANTHROPIC_API_KEY=...`, העתיקו אותו לקובץ הזה כ-`ANTHROPIC_API_KEY=...` בלי ה-prefix `export`, ואז הפעילו מחדש את agentmemory.
+
+משתני סביבת התהליך עדיין עובדים וגוברים על ערכים בקובץ.
+
+ב-Windows, אותו קובץ נמצא ב-`%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+כדי לבדוק עם מנוי Claude Code Pro/Max במקום מפתח API, בצעו opt-in באופן מפורש:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+דחיסת תצפיות בכתיבת LLM דורשת את שתי השורות: גישה לספק LLM (כולל ה-fallback המפורש הזה של מנוי) וגם `AGENTMEMORY_AUTO_COMPRESS=true`. ספק בלבד משאיר את נתיב הדחיסה הסינתטית של ברירת המחדל במקום.
+
+קונסולידציה (nodes של גרף, lessons, crystals) פעילה כברירת מחדל בכל פעם שספק LLM מוגדר. עשו opt-out מפורש עם `CONSOLIDATION_ENABLED=false` אם אתם רוצים פעולה בלי LLM. חילוץ גרף הוא דגל נפרד:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### משתני סביבה
+
+צרו `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer `, ו-endpoints של mesh sync דורשים `AGENTMEMORY_SECRET` מוגדר באופן מפורש בשני ה-peers.
+
+**אימות (Authentication) פעיל כברירת מחדל.** כש-`AGENTMEMORY_SECRET` לא מוגדר (ב-shell או ב-`~/.agentmemory/.env`), השרת מייצר secret אקראי בהפעלה הראשונה ושומר אותו ב-`~/.agentmemory/secret` במוד `0600`. כל לקוח מצורף קורא אותו משם כשהוא מדבר עם שרת מקומי: ה-CLI, המציג, ה-hooks תחת `plugin/scripts`, שרת ה-MCP וה-shim `@agentmemory/mcp`, התצורות שנכתבות על ידי `agentmemory connect`, והאינטגרציות המצורפות של OpenCode, Pi, OpenClaw, Hermes וה-filesystem-watcher. ה-secret המאוחסן נשלח רק ל-URLs של loopback (`localhost`, `127.0.0.0/8`, `::1`). `AGENTMEMORY_SECRET` מפורש גובר תמיד, ולקוחות מרוחקים עדיין צריכים אותו מוגדר. Docker וה-entrypoints של `deploy/` כבר מייצרים ומייצאים את ה-secret שלהם. כדי לקרוא ל-API ביד:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**כללי בקשה לכתיבות.** בקשות `POST`, `PUT`, `PATCH` ו-`DELETE` ל-REST API ולמציג חייבות לשלוח `Content-Type: application/json` (פרמטר `charset` זה בסדר) בכל פעם שהן נושאות גוף, וכותרת `Origin`, כשהיא קיימת, חייבת להיות origin מסוג loopback לפורט ה-REST או המציג המוגדר, או להיות רשומה ב-`VIEWER_ALLOWED_ORIGINS` (מופרד בפסיקים, למשל `https://memory.example.com`). לקוחות שלא שולחים כותרת `Origin` (CLI, hooks, MCP, curl, server-to-server) לא מושפעים. המציג גם מקבל את ה-origin שלו עצמו.
+
+**Paths של קבצים.** endpoints שקוראים או כותבים קבצים (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) מקבלים רק paths תחת `~/.agentmemory`, תיקיית הנתונים של ה-instance, או תיקייה רשומה ב-`AGENTMEMORY_IMPORT_ROOT` (הפרידו כמה עם `:`, או `;` ב-Windows). `/replay/import-jsonl` מקבל גם את ברירת המחדל שלו `~/.claude/projects`. `/obsidian/export` נשאר בתוך `AGENTMEMORY_EXPORT_ROOT` ו-`/migrate` בתוך `~/.agentmemory`. symlinks נפתרים לפני כל בדיקה.
+
+**ניקוי secrets (scrubbing).** מפתחות API, bearer tokens, בלוקי מפתח פרטי PEM, ו-credentials מוטבעים ב-URLs (`scheme://user:password@host`) מנוקים (redacted) לפני שהטקסט נשמר, בכל נתיב כתיבה: תצפיות, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, replay של jsonl, mesh sync, שיתופי צוות, פלט דחיסה וסיכום, crystals ו-nodes של גרף.
+
+
+endpoints מרכזיים
+
+| שיטה (Method) | נתיב | תיאור |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | בדיקת health (ציבורי תמיד) |
+| `GET` | `/agentmemory/status` | מה לא תקין ואיך לתקן את זה (HTML לדפדפנים, JSON אחרת) |
+| `GET` | `/agentmemory/viewer/snapshot` | כל מה שהמציג מציג, בתגובה אחת |
+| `POST` | `/agentmemory/session/start` | התחלת session + קבלת הקשר |
+| `POST` | `/agentmemory/session/end` | סיום session |
+| `POST` | `/agentmemory/observe` | לכידת תצפית (ראו capture delivery מתחת) |
+| `GET` | `/agentmemory/capture` | inbox לכידה, dead letters, ו-spool offline |
+| `POST` | `/agentmemory/capture/retry` | ניסיון חוזר ללכידות dead-letter |
+| `POST` | `/agentmemory/capture/drain` | שליחת ה-spool המקומי offline עכשיו |
+| `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/graph/compact` | גיזום provenance גרף שגדל יותר מהמידה |
+| `POST` | `/agentmemory/team/share` | שיתוף עם הצוות |
+| `GET` | `/agentmemory/audit` | audit trail |
+
+רשימת endpoints מלאה: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**מסירת לכידה (capture delivery).** hooks שולחים כל תצפית פעם אחת ל-`POST /agentmemory/observe` עם `eventId`. זה המזהה של ה-host עצמו לקריאה כשה-payload כולל אחד (למשל `tool_use_id` של Claude Code), אחרת hash של ה-session, סוג ה-hook, שם ה-tool, קלט, פלט, וחותמת הזמן של ה-host. השרת כותב את האירוע ל-inbox לכידה ב-state store, שומר את התצפית, ואז מסיר את רשומת ה-inbox. קוד הסטטוס אומר מה קרה:
+
+| Status | שדה `status` | משמעות |
+|---|---|---|
+| `201` | `accepted` | נשמר. `observationId` הוא התצפית החדשה. |
+| `202` | `accepted` (`state: "retrying"`) | התקבל, אבל השמירה נכשלה. השרת מנסה שוב, גם אחרי הפעלה מחדש. |
+| `200` | `duplicate` | ה-`eventId` הזה התקבל כבר. `observationId` הוא התצפית הקיימת; שום דבר חדש לא נשמר. |
+| `400` / `422` | `rejected` | payload לא תקין, או שהשמירה נכשלה לחלוטין (האירוע נשמר כ-dead letter). |
+| `503` | `rejected` (`retryable: true`) | ה-inbox מלא (`AGENTMEMORY_CAPTURE_INBOX_MAX`). hooks שומרים את האירוע ב-spool ושולחים אותו אחר כך. |
+
+אירועים שנכשלים מקבלים ניסיון חזרה כל `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 שניות) עם backoff מכפיל, עד `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). אירועים שעדיין נכשלים נשארים ב-inbox כ-dead letters, רשומים ב-`/agentmemory/status` ובעמוד ה-Health של המציג, וניתן לנסות אותם שוב עם `POST /agentmemory/capture/retry` (`{"eventId": "..."}` או `{"all": true}`). מזהי אירועים שהתקבלו נזכרים למשך `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 שעות, לכל היותר `AGENTMEMORY_CAPTURE_EVENTS_MAX` מזהים), כך ש-hook שעובר replay אחרי timeout או הפעלה מחדש נשמר פעם אחת, בעוד ששתי קריאות tool נפרדות עם מזהי host משלהן נשמרות פעמיים גם אם התוכן שלהן זהה. כשתצפית נמחקת (forget, מחיקת session, eviction, שכחה אוטומטית, או ייבוא שמחליף את המאגר), האירוע שלה מסומן כנמחק לפני שהתצפית מוסרת, כך ש-replay של אותו אירוע באותו חלון נענה כ-duplicate ולא שומר שום דבר. ה-state store כותב לדיסק כל 2 שניות, כך שאירוע שנענה יכול עדיין להיות רק בזיכרון לרגע. כדי לכסות את זה, כל תשובת `2xx` נושאת גם את `bootId` של השרת (חדש בכל הפעלה), `acceptedAt`, ו-`durableAfterMs` (מרווח השמירה בתוספת 1.5 שניות במאגר הקבצים, 1.5 שניות ב-redis, שם ה-persistence היא הגדרת המפעיל). hooks שומרים את האירוע ב-spool המקומי עד שהחלון הזה עובר ומוחקים אותו בקריאה מאוחרת יותר בלי בקשה נוספת. אם `bootId` השתנה עד אז, השרת הופעל מחדש, אז ה-hook שולח את האירוע שוב עם אותו `eventId`; אירוע שהגיע לדיסק לא נשמר פעמיים. השרת גם שולח אירועים כאלה בעצמו בהפעלה ובכל מרווח ניסיון חזרה, כך שהפעלה מחדש לא מפסידה כלום גם כשאף hook לא רץ אחרי כן. hooks ישנים מתעלמים מהשדות הנוספים, ו-hooks חדשים מול שרת ישן מוחקים את האירוע ב-`2xx` כמו קודם.
+
+כשהשרת נפול, לא עונה בזמן, או מחזיר 5xx, ה-hook מוסיף את התצפית לקובץ spool מקומי, `/capture-spool/-.jsonl` (override לתיקייה עם `AGENTMEMORY_CAPTURE_SPOOL_DIR`). הקובץ פרטי למשתמש שלכם (מוד 600), secrets מנוקים באותו אופן שבו השרת מנקה אותם, הוא מחזיק לכל היותר `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) ומפיל רשומות ישנות מ-`AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). כשהוא מלא, רשומות חדשות נופלות ונספרות, ו-`/agentmemory/status` מדווח על זה. ה-hook עדיין יוצא עם 0 בתוך מגבלת הזמן שלו ולא מוסיף בקשה כשהשרת תקין. ה-spool נשלח בהפעלה הבאה ועל ידי ה-hook הראשון שמגיע לשרת שוב, בתהליך רקע כך שהסוכן לא מחכה. מזהי אירועים מבטיחים שזה בטוח: תצפית שהגיעה לפני timeout לא נשמרת פעמיים. `npx @agentmemory/agentmemory capture` מציג את ה-spool ואת ה-inbox של השרת, `--drain` שולח את ה-spool עכשיו, ו-`GET /agentmemory/capture` מחזיר את אותו הדבר כ-JSON. הגדירו `AGENTMEMORY_CAPTURE_SPOOL=false` כדי לכבות את ה-spool.
+
+**דחיסת provenance של הגרף.** כל node ו-edge בגרף הידע שומר את המזהים של 32 התצפיות החדשות ביותר שהוא בא מהן. מאגרים שנכתבו לפני המכסה הזו יכולים להחזיק אלפי מזהים לכל node חם, מה שמאטה את חיפוש הגרף ואת המציג או מפיל את ה-worker. agentmemory מתקן את זה בעצמו: בהפעלה הראשונה אחרי שדרוג הוא גוזם כל node, edge, edge שהוחלף (היסטוריית הגרף הטמפורלית), וה-snapshot שבמטמון למכסה ברקע, בפרוסות קטנות עם הפסקה ביניהן, כך שחיפוש, לכידה, והמציג ממשיכים לעבוד. הוא שומר את ההתקדמות שלו, ממשיך אחרי הפעלה מחדש, ולעולם לא רץ שוב ברגע שהוא סיים. `/agentmemory/status` ועמוד ה-Health של המציג מציגים את זה כ-pending, running (עם ה-scope והמיקום הנוכחיים), done, או failed. הגדירו `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` כדי לכבות את זה.
+
+כדי להריץ את זה ביד, קראו ל-`POST /agentmemory/graph/compact`. זה הולך על אינדקסי ה-name וה-edge-key במקום לרשום כל node ו-edge, ובטוח להריץ מחדש. כשזה גוזם מזהים זה כותב רשומת audit מסוג `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+על מאגר גדול, או כשהקריאה מחזירה 504, הריצו את זה בפרוסות. שלחו `scope` (`nodes`, `edges`, או `history`), `offset`, ו-`limit`, ואז קראו שוב עם `nextOffset` שהוחזר עד שהוא `null`. עשו את זה ל-`nodes`, `edges`, ו-`history`, וסיימו עם קריאה אחת של `{"scope":"snapshot"}`, כי הרצה בפרוסות לא נוגעת ב-snapshot שבמטמון.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**דרישות מקדימות:** Node.js >= 20 עם npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 או Docker. ההתקנה האוטומטית של המנוע ב-macOS/Linux דורשת גם `curl`, מעטפת `sh` תואמת POSIX, ו-`tar`; Windows מקורי משתמש ב-`iii.exe` הנעוץ הידני, WSL2, או Docker Desktop.
+
+
- आपका कोडिंग एजेंट सब कुछ याद रखता है। बार-बार समझाने की ज़रूरत नहीं।
- Built on iii engine
+ आपका कोडिंग एजेंट सब कुछ याद रखता है। अब दोबारा समझाने की ज़रूरत नहीं।
+ iii engine पर बना।
- Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, और किसी भी MCP क्लाइंट के लिए स्थायी मेमोरी।
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, और किसी भी MCP क्लाइंट के लिए स्थायी मेमोरी।
- यह gist Karpathy के LLM Wiki पैटर्न को confidence scoring, lifecycle, knowledge graphs और hybrid search के साथ बढ़ाता है: agentmemory इसका implementation है।
+ यह gist Karpathy के LLM Wiki पैटर्न को confidence scoring, lifecycle, knowledge graphs, और hybrid search के साथ विस्तार देता है: agentmemory इसका implementation है।
@@ -50,7 +71,7 @@
-
+
@@ -75,31 +96,43 @@
## इंस्टॉल
-एक कमांड:
+आवश्यकताएं:
+
+- npm और npx के साथ Node.js 20 या नया (`node -v`, `npm -v`, और `npx -v`)।
+- macOS/Linux पर automatic iii-engine installation के लिए `curl`, एक POSIX `sh`, और `tar` भी ज़रूरी हैं। `node:20-slim` जैसी minimal images में ये शामिल नहीं हो सकते।
+- Native Windows पर pinned iii-engine v0.22.1 का `iii.exe` manually install करना ज़रूरी है। WSL2 या Docker Desktop अन्य समर्थित रास्ते हैं।
+
+मानक fresh-install कमांड:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-पहली रन एक interactive setup है: जोड़ने के लिए एजेंट चुनें (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), एक LLM provider चुनें या keyless रहें, और यह config seed करता है, `:3111` पर मेमोरी सर्वर शुरू करता है, और globally इंस्टॉल करने का प्रस्ताव देता है ताकि बेयर `agentmemory` कमांड बाद में हर जगह काम करे।
+पहली रन एक interactive setup है: जोड़ने के लिए एजेंट चुनें (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), एक LLM provider चुनें या keyless रहें, और यह config seed करता है, memory server और उसका pinned iii engine शुरू करता है, और globally install करने का प्रस्ताव देता है ताकि बेयर `agentmemory` कमांड बाद में हर जगह काम करे। `-y`, npx के package prompt को accept करता है और `@latest` किसी पुराने cached release से बचाता है। एक provider LLM features उपलब्ध कराता है, लेकिन LLM-written observation compression केवल तब शुरू होता है जब `AGENTMEMORY_AUTO_COMPRESS=true` भी set हो।
+
+Keyless mode vector embeddings को disable करता है। `memory_recall` (`mem::search` path) BM25 का उपयोग करता है, जबकि `memory_smart_search` graph data पहले से मौजूद होने पर structural graph matches को भी fuse कर सकता है। free on-device semantic recall के लिए, `~/.agentmemory/.env` में `EMBEDDING_PROVIDER=local` set करें और restart करें। पहला embedding request `Xenova/all-MiniLM-L6-v2` डाउनलोड करता है; उस शुरुआती model download के बाद inference locally चलता है।
+
+Local runtime चार ports का उपयोग करता है: REST/MCP HTTP के लिए `3111`, iii streams के लिए `3112`, viewer के लिए `3113`, और iii worker WebSocket के लिए `49134`। Persistent iii state macOS पर `~/Library/Application Support/agentmemory` में, Linux पर `$XDG_DATA_HOME/agentmemory` या `~/.local/share/agentmemory` में, और Windows पर `%APPDATA%\agentmemory` में रहता है। इसे override करने के लिए `--data-dir ` या `AGENTMEMORY_DATA_DIR` का उपयोग करें, और हर restart पर वही value फिर से उपयोग करें। backward compatibility के लिए, instance 0 के लिए मौजूदा `./data/state_store.db` या `./data/iii-config.yaml`, platform default से आगे आता है; एक explicit flag या environment override फिर भी जीतता है।
फिर साबित करें कि recall काम करता है और अपने एजेंट को उसकी skills दें:
```bash
-agentmemory demo --serve # नमूना सेशंस सीड करें + recall को उन्हें ढूँढ़ते देखें
-npx skills add rohitg00/agentmemory -y # 17 native skills ताकि आपका एजेंट जाने कि memory का उपयोग कब करना है
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
-चाहते हैं कि एक coding agent पूरा काम खुद कर दे? उसे यह एक instruction दें:
+default keyless mode में keyword searches को BM25 के माध्यम से hit करना चाहिए। demo की `database performance optimization` query जानबूझकर semantic है और embedding provider configure होने तक zero return कर सकती है।
+
+चाहते हैं कि एक coding एजेंट पूरा काम खुद कर दे? उसे यह एक instruction दें:
-> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+> https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md पर मौजूद instructions प्राप्त करें और उनका पालन करें।
-किसी भी समय `agentmemory connect ` से और एजेंट जोड़ें — 20 adapters [हर एजेंट के साथ काम करता है](#works-with-every-agent) में सूचीबद्ध हैं। पूर्ण कमांड reference [क्विक स्टार्ट](#quick-start) में।
+किसी भी समय `agentmemory connect ` से और एजेंट जोड़ें — 20 adapters [हर एजेंट के साथ काम करता है](#works-with-every-agent) में सूचीबद्ध हैं। पूरा command reference [क्विक स्टार्ट](#quick-start) में है।
Windows
-तेज़ रास्ता WSL2 है। Native Windows engine setup मैनुअल है (लगभग 10 से 20 मिनट) और `agentmemory connect` वहाँ वर्तमान में unsupported है। Step-by-step के लिए [Windows नोट्स](#windows) देखें।
+सबसे तेज़ रास्ता WSL2 है। Native Windows engine setup के लिए pinned v0.22.1 ZIP को डाउनलोड करना और `iii.exe` को manually extract करना ज़रूरी है; CLI इसे auto-extract नहीं करता। Docker Desktop भी समर्थित है। Step-by-step के लिए [Windows नोट्स](#windows) देखें।
@@ -107,24 +140,24 @@ npx skills add rohitg00/agentmemory -y # 17 native skills ताकि आप
Global install / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# अगर macOS/Linux सिस्टम Node इंस्टॉल पर EACCES त्रुटि आती है:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+ऊपर दिया गया npx कमांड मानक fresh-install रास्ता बना रहता है और global-prefix permission issues से बचाता है।
+
-npx कोई पुराना version चला रहा है
+npx कोई पुराना version serve कर रहा है
-npx प्रति-वर्ज़न कैश करता है। नवीनतम को `npx -y @agentmemory/agentmemory@latest` से force करें, या एक बार `rm -rf ~/.npm/_npx` से कैश साफ़ करें (macOS/Linux; Windows पर `%LOCALAPPDATA%\npm-cache\_npx` हटाएँ)।
+npx प्रति-version cache करता है। `npx -y @agentmemory/agentmemory@latest` से latest को force करें, या एक बार `rm -rf ~/.npm/_npx` से cache साफ़ करें (macOS/Linux; Windows पर `%LOCALAPPDATA%\npm-cache\_npx` हटाएँ)।
पहले से अपना iii engine चला रहे हैं
-agentmemory iii-engine v0.11.2 को pin करता है और किसी भिन्न version से attach नहीं होगा (worker किसी दूसरे engine का protocol नहीं बोल सकता)। दूसरे engine को रोकें, फिर `npx -y @agentmemory/agentmemory@latest` चलाएँ। यह pinned v0.11.2 को `~/.agentmemory/bin` में install और run करता है, आपके अपने `iii` को अछूता छोड़ते हुए।
+agentmemory iii-engine v0.22.1 को pin करता है और किसी अलग version से attach नहीं होगा (worker किसी दूसरे engine का protocol नहीं बोल सकता)। दूसरे engine को रोकें, फिर `npx -y @agentmemory/agentmemory@latest` चलाएँ। यह pinned v0.22.1 को `~/.agentmemory/bin` में install और run करता है, आपके अपने `iii` को बिना छुए छोड़ते हुए।
@@ -132,110 +165,170 @@ agentmemory iii-engine v0.11.2 को pin करता है और किस
-agentmemory किसी भी ऐसे एजेंट के साथ काम करता है जो hooks, MCP, या REST API सपोर्ट करता है। सभी एजेंट एक ही मेमोरी सर्वर साझा करते हैं।
+agentmemory किसी भी ऐसे एजेंट के साथ काम करता है जो hooks, MCP, या REST API support करता है। सभी एजेंट एक ही memory server साझा करते हैं।
- MCP या HTTP बोलने वाले किसी भी एजेंट के साथ काम करता है। एक सर्वर, सभी के बीच साझा मेमोरी।
+ MCP या HTTP बोलने वाले किसी भी एजेंट के साथ काम करता है। एक सर्वर, सभी के बीच साझा मेमोरीज़।
---
-आप हर सेशन में वही आर्किटेक्चर समझाते हैं। आप वही bugs बार-बार खोजते हैं। आप वही प्राथमिकताएँ फिर से सिखाते हैं। बिल्ट-इन मेमोरी (CLAUDE.md, .cursorrules) 200 लाइनों पर सीमित है और पुरानी हो जाती है। agentmemory इसे ठीक करता है। यह चुपचाप आपके एजेंट की गतिविधियाँ कैप्चर करता है, उन्हें खोज योग्य मेमोरी में संकुचित करता है, और अगला सेशन शुरू होने पर सही संदर्भ इंजेक्ट करता है। एक कमांड। सभी एजेंट्स के साथ काम करता है।
+आप हर session में वही architecture समझाते हैं। आप वही bugs फिर से खोजते हैं। आप वही preferences फिर से सिखाते हैं। Built-in memory (CLAUDE.md, .cursorrules) 200 लाइनों पर सीमित है और पुरानी हो जाती है। agentmemory इसे ठीक करता है। यह चुपचाप आपके एजेंट की गतिविधियाँ capture करता है, उन्हें searchable memory में compress करता है, और अगला session शुरू होने पर सही context inject करता है। एक कमांड। सभी एजेंट्स के साथ काम करता है।
-**क्या बदलता है:** सेशन 1 में आप JWT auth सेटअप करते हैं। सेशन 2 में आप rate limiting माँगते हैं। एजेंट को पहले से पता है कि आपकी auth `src/middleware/auth.ts` में jose middleware का उपयोग करती है, आपके tests token validation को कवर करते हैं, और आपने Edge compatibility के लिए jsonwebtoken के बजाय jose चुना है, बिना फिर से समझाए और बिना कॉपी-पेस्ट किए।
+**क्या बदलता है:** Session 1 में आप JWT auth setup करते हैं। Session 2 में आप rate limiting माँगते हैं। एजेंट को पहले से पता है कि आपका auth `src/middleware/auth.ts` में jose middleware का उपयोग करता है, आपके tests token validation को cover करते हैं, और आपने Edge compatibility के लिए jsonwebtoken के बजाय jose चुना, बिना फिर से समझाए और बिना copy-paste किए।
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **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) में।
+By default, agentmemory इस repository के बाहर iii-engine state स्टोर करता है जहाँ से आप इसे शुरू करते हैं: macOS पर `~/Library/Application Support/agentmemory`, Linux पर `$XDG_DATA_HOME/agentmemory` या `~/.local/share/agentmemory`, और Windows पर `%APPDATA%\agentmemory`। एक मौजूदा legacy `./data/state_store.db` या `./data/iii-config.yaml` उस platform default से पहले instance 0 के लिए reuse होता है। किसी location को explicitly चुनने के लिए, `--data-dir ` पास करें या `AGENTMEMORY_DATA_DIR` set करें; दोनों में से कोई भी explicit setting legacy discovery से पहले आती है:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native और Docker launches इस्तेमाल वही resolved host directory करते हैं; Docker इसे `/data` पर bind-mount करता है। `--instance 1`, resolved directory में `instance-1` जोड़ता है और अलग default port quartet `3211/3212/3213/49234` चुनता है।
+
+नवीनतम release notes: [CHANGELOG.md](../CHANGELOG.md)।
---
@@ -254,9 +347,9 @@ npx @agentmemory/agentmemory
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
-इस corpus के लिए **P@5 math ceiling** (0.240, scorecard देखें) पर 100% top-5 hit rate। Hybrid हर gold session retrieve करता है; grep multi-session temporal query पर 2 में से 1 gold miss करता है। Lift **recall + temporal** है, aggregate precision नहीं। यह benchmark छोटा और gold-sparse है; नीचे का बड़ा LongMemEval-S बेहतर differentiate करता है। पूरी प्रकार-वार breakdown + correction नोट: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md)।
+इस corpus के लिए **P@5 math ceiling** (0.240, scorecard देखें) पर 100% top-5 hit rate। Hybrid हर gold session retrieve करता है; grep multi-session temporal query पर 2 में से 1 gold miss करता है। Lift **recall + temporal** है, aggregate precision नहीं। यह benchmark छोटा और gold-sparse है; नीचे का बड़ा LongMemEval-S बेहतर differentiate करता है। पूरी per-type breakdown + correction नोट: [`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 प्रश्न)
+**LongMemEval-S** (ICLR 2025, 500 questions)
| System | R@5 | R@10 | MRR |
|---|---|---|---|
@@ -279,11 +372,11 @@ npx @agentmemory/agentmemory
-> 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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo को कवर करती है।
+> Embedding model: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo को cover करती है।
-**स्थानीय रूप से 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/) में जाते हैं।
+**स्थानीय रूप से 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 साथ-साथ score होते हैं, NDJSON output, published 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)।
+**[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 काम याद रखता है; ये तीन projects context layer के बाकी हिस्से को रोशन करते हैं। Recipes + question-routing table: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md)।
---
@@ -330,7 +423,7 @@ npx @agentmemory/agentmemory
-संगतता: यह रिलीज़ stable `iii-sdk` `^0.11.0` और iii-engine v0.11.x को टार्गेट करता है।
+संगतता: यह release `iii-sdk` 0.22.1 को target करता है और iii-engine को v0.22.1 पर pin करता है।
### 30 सेकंड में आज़माएँ
```bash
-# Terminal 1: सर्वर शुरू करें
-npx @agentmemory/agentmemory
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
-# Terminal 2: नमूना डेटा सीड करें और recall को कार्य में देखें
-npx @agentmemory/agentmemory demo
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
```
-`demo` 3 यथार्थवादी सेशंस सीड करता है (JWT auth, N+1 query fix, rate limiting) और उन पर semantic searches चलाता है। जब आप "database performance optimization" खोजते हैं तो आप देखेंगे कि यह "N+1 query fix" ढूँढ़ लेता है, जो keyword matching नहीं कर सकती।
+`demo` 3 realistic sessions सीड करता है (JWT auth, N+1 query fix, rate limiting) और उन पर searches चलाता है। Keyless installs vectors को disable करते हैं, इसलिए `mem::search` keyword queries को BM25 के माध्यम से hit करना चाहिए जबकि `database performance optimization` zero return कर सकती है। `smart-search` graph data मौजूद होने पर अतिरिक्त रूप से structural graph matches भी return कर सकता है। semantic query से vectors के माध्यम से N+1 fix ढूँढ़ने के लिए, `EMBEDDING_PROVIDER=local` set करें, restart करें, और पहले model download को पूरा होने दें।
+
+memory को लाइव बनते हुए देखने के लिए `http://localhost:3113` खोलें।
+
+### एक fresh install और restart persistence को validate करें
+
+server चलते हुए, REST, health, viewer, और iii-backed runtime status को validate करें:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
-मेमोरी को लाइव बनते हुए देखने के लिए `http://localhost:3113` खोलें।
+startup ready panel सभी चार ports के लिए हिसाब रखता है: 3111 पर REST/MCP HTTP, 3112 पर iii streams, 3113 पर viewer, और 49134 पर iii worker WebSocket। `status`, agentmemory health और active provider/embedding mode की पुष्टि करता है। एक probe save करें और पुष्टि करें कि वह searchable है:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+फिर `npx -y @agentmemory/agentmemory@latest stop` चलाएँ, Terminal 1 में मानक कमांड फिर से शुरू करें, `/agentmemory/livez` के लिए wait करें, और search दोहराएँ। probe अभी भी return होना चाहिए। अगर आपने कोई custom `--data-dir` चुना था, तो restart पर वही directory पास करें।
### रोज़मर्रा की कमांड्स
Install और setup ऊपर [इंस्टॉल](#install) में हैं (पहली रन आपको इसके माध्यम से ले जाती है)। दिन-प्रतिदिन:
```bash
-agentmemory # सर्वर शुरू करें
-agentmemory stop # बंद करें
-agentmemory connect # एक और एजेंट जोड़ें
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
-agentmemory remove # हमने जो भी बनाया उसे अनइंस्टॉल करें
+agentmemory remove # uninstall everything we created
```
### Session Replay
-agentmemory द्वारा रिकॉर्ड किया गया हर सेशन replayable है। व्यूअर खोलें, **Replay** टैब चुनें, और timeline scrub करें: prompts, tool calls, tool results, और responses अलग events के रूप में render होते हैं, play/pause, speed control (0.5x से 4x), और keyboard shortcuts (space toggle के लिए, arrows step के लिए) के साथ।
+agentmemory द्वारा record किया गया हर session replayable है। viewer खोलें, **Replay** tab चुनें, और timeline scrub करें: prompts, tool calls, tool results, और responses अलग events के रूप में render होते हैं, play/pause, speed control (0.5x से 4x), और keyboard shortcuts (space toggle के लिए, arrows step के लिए) के साथ।
पुरानी Claude Code JSONL transcripts लाने के लिए:
```bash
-# डिफ़ॉल्ट ~/.claude/projects के तहत सब कुछ import करें
-npx @agentmemory/agentmemory import-jsonl
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
-# या एक अकेली फाइल import करें
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest 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 के। हर imported transcript search के लिए indexed होती है, origin channel `import` से stamped होती है, और एक session crystal और lessons के लिए mined होती है।
+Imported sessions native ones के साथ Replay picker में दिखते हैं। हुड के नीचे हर entry `mem::replay::load`, `mem::replay::sessions`, और `mem::replay::import-jsonl` iii functions के माध्यम से route होती है, बिना किसी side-channel servers के। हर imported transcript search के लिए indexed होती है, origin channel `import` से stamped होती है, और एक session crystal और lessons के लिए mined होती है।
+
+> **ध्यान दें अगर आप `import-jsonl` को अपने प्राथमिक capture path के रूप में उपयोग करते हैं:** Claude Code का `cleanupPeriodDays` (`~/.claude/settings.json` में, default **30**) उस window से पुराने JSONL transcripts को `~/.claude/projects/` से auto-delete कर देता है। अगर आप agentmemory को महीनों पुरानी Claude Code history पर fresh install करते हैं, तो 30 दिनों से पुराना सब कुछ पहले import से पहले ही चला जाता है। या तो `import-jsonl` को cron पर चलाएँ, `cleanupPeriodDays` को ज़्यादा बढ़ाएँ, या auto-capture hooks wire करें (default plugin install path) ताकि session के live रहते हुए हर turn agentmemory में पहुँचे और JSONL cleanup मायने रखना बंद कर दे।
### Upgrade / Maintenance
जब आप जानबूझकर अपने local runtime को update करना चाहते हैं तो maintenance command का उपयोग करें:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-चेतावनी: यह कमांड वर्तमान workspace/runtime को mutate करता है। यह JavaScript निर्भरताएँ update कर सकता है और pinned Docker image `iiidev/iii:0.11.2` खींच सकता है। यह कभी भी unpinned या नया iii engine install नहीं करता।
+चेतावनी: यह कमांड current workspace/runtime को mutate करता है। यह JavaScript dependencies update कर सकता है और pinned `iiidev/iii:0.22.1` Docker image को pull कर सकता है। यह कभी भी unpinned या नया iii engine install नहीं करता।
-Implementation विवरण `src/cli.ts` में हैं (`src/cli.ts:544-595` क्षेत्र के आसपास `runUpgrade` देखें)।
+Implementation विवरण `src/cli.ts` में हैं (`src/cli.ts:544-595` region के आसपास `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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### 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 को तोड़ देता है।
+अगर आप `/plugin install` का उपयोग करने के बजाय `~/.claude.json` के माध्यम से सीधे agentmemory का MCP server connect करते हैं, तो 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.22/scripts/…`), इसलिए अगला upgrade चुपचाप हर hook को तोड़ देता है।
Workaround:
@@ -535,45 +655,59 @@ Workaround:
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` का उपयोग करता है।
+यह वही hook commands को `~/.claude/settings.json` में merge करता है, current installed `@agentmemory/agentmemory` package की bundled `plugin/` directory पर resolve किए गए absolute paths के साथ। agentmemory upgrade करने के बाद paths refresh करने के लिए command फिर से चलाएँ। उसी file में user entries preserved रहती हैं; केवल पिछली agentmemory entries replace होती हैं। `/plugin install` path अनुशंसित approach बनी रहती है।
+Remote या protected deployments के लिए, Claude Code को `AGENTMEMORY_URL` और `AGENTMEMORY_SECRET` set के साथ launch करें। Plugin दोनों values को अपने bundled MCP server के माध्यम से pass करता है; जब `AGENTMEMORY_URL` खाली होता है, तो MCP shim `http://localhost:3111` का उपयोग करता है।
### Codex CLI (Codex plugin platform)
```bash
-# 1. एक अलग terminal में memory सर्वर शुरू करें
-npx @agentmemory/agentmemory
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
-# 2. agentmemory marketplace register करें और plugin install करें
+# 2. register the agentmemory marketplace and install the plugin
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 करता है, तो सभी 54 tools proxy करता है; कोई पहुँच योग्य सर्वर न होने पर locally 7 tools पर fallback करता है)
+- चल रहे daemon के लिए एक bundled stdio MCP bridge, बिना किसी npm download या fallback store के। किसी unreleased build को test करने के लिए [local Codex guide](../docs/plugins/codex-local.md) देखें।
- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, साथ ही 8 reference skills जिन्हें agent on demand load करता है (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, और skill-authoring guide)
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 उपलब्ध)
+#### Codex hook trust और compatibility
-`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 छूट जाते हैं।
+Native plugin hook dispatch Codex CLI 0.150.1 के साथ verified है। capture की उम्मीद करने से पहले plugin hooks को trust करें। Desktop behavior उसके bundled runtime पर depend करता है; कोई workaround enable करने से पहले `/hooks` check करें और एक captured event confirm करें।
-जब तक upstream fix land नहीं करता, वही hook commands को global `~/.codex/hooks.json` में mirror करें:
+अगर आपके host को global hooks चाहिए, तो commands को `~/.codex/hooks.json` में mirror करें। जब MCP पहले से wired है, तो current connector को hook installation तक पहुँचने के लिए `--force` चाहिए:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-यह `~/.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 होती हैं।
+यह global hooks को merge करता है और agentmemory MCP entry को rewrite करता है, unrelated entries को preserve करते हुए। `--force` उपयोग करने से पहले अपनी custom agentmemory endpoint settings review करें। upgrade के बाद script paths refresh करने के लिए फिर से run करें। duplicate capture से बचने के लिए native plugin hooks या global copies में से कोई एक enable करें।
+
+### GitHub Copilot CLI
+
+VS Code agent mode के लिए, [Copilot MCP और automatic-capture guide](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions) का उपयोग करें। CLI connector VS Code को configure नहीं करता।
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# वैकल्पिक रूप से, GitHub subdir से full hooks/skills plugin
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli`, `~/.copilot/mcp-config.json` (या `COPILOT_HOME` set होने पर `$COPILOT_HOME/mcp-config.json`) में `mcpServers.agentmemory` merge करता है और existing servers को preserve करता है। Native Windows पर यह एकमात्र automated `connect` adapter है; हर दूसरे native Windows agent को manually configure करें। WSL `connect` तभी समर्थित है जब target agent उसी WSL environment में installed हो। Copilot अगली launch पर या `/mcp` के बाद MCP server को pick कर लेता है। पूरे hook/skill experience के लिए plugin भी install करें।
OpenClaw (यह prompt paste करें)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -598,7 +732,7 @@ Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. O
Hermes Agent (यह prompt paste करें)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -617,9 +751,28 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
### अन्य एजेंट्स
-मेमोरी सर्वर शुरू करें: `npx @agentmemory/agentmemory`
+memory server शुरू करें: `npx -y @agentmemory/agentmemory@latest`
+
+#### `npx skills add` के माध्यम से Native skills (50+ agents)
+
+agentmemory Claude-Code-style `/SKILL.md` format में 17 skills ship करता है: 9 invocable action skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) और 8 reference skills जिन्हें agent on demand load करता है (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`)। Reference skills में source से generated data tables होती हैं, इसलिए वे कभी drift नहीं करती। vercel-labs की [`skills`](https://npmjs.com/package/skills) CLI इन्हें calling agent की native skill directory में 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, और अधिक) में auto-install करती है:
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+यह `agentmemory connect ` के लिए **complementary** है:
-agentmemory entry `mcpServers` shape का उपयोग करने वाले हर host में **वही MCP server block** है (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+- `agentmemory connect ` MCP server config लिखता है ताकि tools उपलब्ध हों।
+- `npx skills add rohitg00/agentmemory` skills install करता है ताकि agent को पता चले कि उन्हें कब call करना है।
+
+जिन कुछ agents को skills CLI अभी cover नहीं करती (Zed v1.3.x और उससे नीचे), उनके लिए 17 SKILL.md files को agent की native skill directory में खुद drop करें; वही format हर जगह काम करता है।
+
+#### Standard MCP block
+
+agentmemory entry, `mcpServers` shape का उपयोग करने वाले हर host में (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw) **वही MCP server block** है:
```json
"agentmemory": {
@@ -632,35 +785,37 @@ agentmemory entry `mcpServers` shape का उपयोग करने वा
}
```
-**इस 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 को कवर करती है।
+**इस entry को host की मौजूदा `mcpServers` object में merge करें**; file को replace न करें। अगर file में पहले से अन्य 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 को cover करती है।
| एजेंट | Config फाइल | नोट्स |
|---|---|---|
-| **Cursor** | `~/.cursor/mcp.json` | `mcpServers` में merge करें। Website पर one-click deeplink भी उपलब्ध। |
+| **Cursor (केवल MCP)** | `~/.cursor/mcp.json` | `mcpServers` में merge करें, या `agentmemory connect cursor`। Website पर one-click deeplink भी उपलब्ध है। |
+| **Cursor (पूर्ण plugin)** | `.cursor-plugin/` | Cursor Marketplace listing (submission review में है) या Cursor Settings → Plugins → local checkout। 7 auto-capture hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + MCP server register करता है, `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` Cursor के plugin dashboard में managed होते हैं। Cursor IDE और `cursor-agent` CLI में काम करता है; CLI print-mode prompts session transcript से session end पर backfilled होते हैं। |
| **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। |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` MCP entry merge करता है; `--with-hooks` छह native auto-capture hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) जोड़ता है, Devin के lowercase tool matchers के साथ। `devin mcp list` और devin के अंदर `/hooks` से verify करें। |
-| **Devin (cloud)** | Settings → Connections → MCP servers | Custom MCP (STDIO) जोड़ें: command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` एक network-reachable agentmemory deployment पर plus `AGENTMEMORY_SECRET` (cloud sessions localhost तक नहीं पहुँचते — देखें [`deploy/`](../deploy/))। |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` MCP entry merge करता है; `--with-hooks` छह native auto-capture hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) जोड़ता है, Devin के lowercase tool matchers के साथ। `devin mcp list` और devin के अंदर `/hooks` से verify करें। |
+| **Devin CLI (पूर्ण plugin)** | `plugin/.devin-plugin/` | किसी checkout से `devin plugins install ./plugin`, सभी 17 skills को `/agentmemory:` slash commands के रूप में plus MCP server register करता है। Devin plugin hooks `SessionStart`/`SessionEnd` fire नहीं कर सकते, इसलिए पूरे session capture के लिए इसे `connect devin --with-hooks` के साथ pair करें। |
+| **Devin (cloud)** | Settings → Connections → MCP servers | एक custom MCP (STDIO) जोड़ें: command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` किसी network-reachable agentmemory deployment पर plus `AGENTMEMORY_SECRET` (cloud sessions localhost तक नहीं पहुँच सकते — देखें [`deploy/`](../deploy/))। secret को Devin Secrets में store करें, फिर यह verify करने के लिए कि सभी 54 tools दिखते हैं "Test listing tools" का उपयोग करें। |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges)। |
| **GitHub Copilot CLI (केवल MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` `mcpServers.agentmemory` merge करता है; Copilot इसे अगली launch या `/mcp` पर pick कर लेता है। |
| **GitHub Copilot CLI (पूर्ण plugin)** | Copilot plugin install | GitHub subdir से plugin के लिए `copilot plugin install rohitg00/agentmemory:plugin`। |
-| **OpenClaw** | OpenClaw MCP config | वही `mcpServers` block। गहराई से: `openclaw plugins install ./integrations/openclaw` OpenClaw का memory slot claim कर लेता है (`memory-core` से auto-switch करता है); `plugins.entries.agentmemory.hooks.allowConversationAccess=true` सेट करें, वरना turn capture चुपचाप block हो जाता है। [`integrations/openclaw`](integrations/openclaw/) देखें। |
+| **OpenClaw** | OpenClaw MCP config | वही `mcpServers` block। गहराई से: `openclaw plugins install ./integrations/openclaw` OpenClaw का memory slot claim कर लेता है (`memory-core` से auto-switch करता है); `plugins.entries.agentmemory.hooks.allowConversationAccess=true` set करें, वरना turn capture चुपचाप block हो जाता है। [`integrations/openclaw`](../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) + 17 skills register करता है। Codex Desktop पर, [openai/codex#16430](https://github.com/openai/codex/issues/16430) land होने तक `agentmemory connect codex --with-hooks` भी चलाएँ; plugin hooks वर्तमान में वहाँ silent हैं। |
+| **Codex CLI (पूर्ण plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` फिर `codex plugin add agentmemory@agentmemory`। MCP + 6 lifecycle hooks + 17 skills register करता है। अपने host में hooks को trust करें और capture verify करें; देखें [Codex setup और validation](../docs/plugins/codex-local.md)। |
| **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। Project attribution प्रति-session है, इसलिए कई repositories में फैली एक OpenCode process हर session को उसके अपने project के अंतर्गत file करती है। दो 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) देखें। |
+| **OpenCode (पूर्ण plugin)** | `plugin/opencode/` | Session lifecycle, messages, tools, errors को cover करने वाले 22 auto-capture hooks। Project attribution प्रति-session है, इसलिए कई repositories में फैली एक OpenCode process हर session को उसके अपने project के अंतर्गत file करती है। दो 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` | `agentmemory connect pi` bundled extension को pi की auto-discovery directory में install करता है (agent start पर recall, agent end पर capture, `memory_search` / `memory_save` / `memory_health` tools, `/agentmemory-status`)। चल रहे pi में `/reload` इसे pick कर लेता है। [`integrations/pi`](../integrations/pi/) एक pi package भी है (checkout से `pi install ./integrations/pi`)। |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` 6-hook memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block) को enable कर देता है। `hermes plugins doctor` और `hermes memory status` से validate करें। [`integrations/hermes`](integrations/hermes/) देखें। |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` 6-hook memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block) को enable कर देता है। `hermes plugins doctor` और `hermes memory status` से validate करें। [`integrations/hermes`](../integrations/hermes/) देखें। |
| **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 के बाद उपयोग करें। |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`। `agy` CLI अपनी config `~/.gemini/` के अंतर्गत रखता है, ऊपर वाले Antigravity IDE से अलग। `~/.gemini/config/hooks.json` के माध्यम से native auto-capture के लिए `--with-hooks` pass करें। |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` shared customization directory में MCP और capture hooks install करता है। देखें [Antigravity setup और limits](../docs/plugins/antigravity.md)। |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` current IDE versions जैसा ही MCP और hook configuration उपयोग करता है। मौजूदा installations को `--force` से refresh करना चाहिए; देखें [upgrade notes](../docs/plugins/antigravity.md)। |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` user-level config लिखता है। Workspace overrides आपके code के बगल में `.kiro/settings/mcp.json` में जाते हैं। |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` standard `mcpServers` block लिखता है। Warp `.claude/skills/` से skills भी auto-discover करता है; Claude Code plugin install होने के बाद 8 agentmemory skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) Warp की slash-command palette में natively दिखती हैं। |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` standard `mcpServers` block लिखता है। VS Code extension users: वही block Cline Settings → MCP Servers → Edit JSON के माध्यम से paste करें। |
| **Continue.dev** | `~/.continue/config.yaml` (preferred) या `config.json` (legacy) | जब दोनों में से कोई मौजूद नहीं होती तो `agentmemory connect continue` `config.yaml` शुरू से बनाता है, या मौजूदा `config.json` को modify करता है। **अगर आपके पास पहले से `config.yaml` है** तो adapter `mcpServers:` के अंतर्गत paste करने के लिए exact block print करता है; यह आपकी yaml को चुपचाप rewrite नहीं करेगा क्योंकि comments और anchors को safely preserve करने के लिए एक YAML parser चाहिए जो package ship नहीं करता। Continue `mcpServers` के लिए array form (object नहीं) का उपयोग करता है। |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` `context_servers` (Zed की key, `mcpServers` नहीं) के अंतर्गत लिखता है। Remote MCP servers इसके बजाय `{"url": "..."}` के माध्यम से wired हो सकते हैं। |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` standard `mcpServers` block लिखता है। Project-scoped overrides `/.factory/mcp.json` में जाते हैं। Native auto-capture के लिए `--with-hooks` pass करें। |
-| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` उस home-level patch layer में एक `@deepseek-ai/dsh-mcp-client` row append करता है जिसे हर Harness profile load करती है; tools `mcp__agentmemory__*` के रूप में register होते हैं। Auto-capture भी wire करने के लिए `--with-hooks` pass करें: bundled Claude Code hook scripts Harness के first-party `@deepseek-ai/dsh-hooks-claude-code` bridge (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) के माध्यम से चलते हैं, `$DSH_HOME/agentmemory.hooks.json` में लिखे गए एक manifest के जरिए। `DSH_HOME` unset होने पर default `~/.dsh` है। |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` उस home-level patch layer में एक `@deepseek-ai/dsh-mcp-client` row append करता है जिसे हर Harness profile load करती है; tools `mcp__agentmemory__*` के रूप में register होते हैं। Auto-capture भी wire करने के लिए `--with-hooks` pass करें: bundled Claude Code hook scripts Harness के first-party `@deepseek-ai/dsh-hooks-claude-code` bridge (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) के माध्यम से चलते हैं, `$DSH_HOME/agentmemory.hooks.json` में लिखे गए एक manifest के ज़रिए। `DSH_HOME` unset होने पर default `~/.dsh` है। |
| **Goose** | Goose MCP settings UI | वही `mcpServers` block; `goose configure` → Add Extension → MCP का उपयोग करें। `~/.config/goose/config.yaml` पर direct YAML edit supported है लेकिन schema `extensions:` + `cmd` का उपयोग करता है (`mcpServers:` + `command` नहीं)। |
| **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 करता है। |
@@ -669,7 +824,7 @@ agentmemory entry `mcpServers` shape का उपयोग करने वा
### 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 क्लाइंट के बिना।
+agentmemory अपने core operations को iii functions के रूप में register करता है (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`)। iii SDK वाली कोई भी भाषा उन्हें `ws://localhost:49134` पर सीधे call कर सकती है, प्रति भाषा अलग REST client के बिना।
```bash
pip install iii-sdk # Python
@@ -698,77 +853,82 @@ 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 करते हैं।
+यह agentmemory को local `iii-engine` के साथ शुरू करता है अगर pinned binary पहले से installed है, या चुने जाने पर Docker Compose का उपयोग करता है। REST, streams, और viewer default रूप से `127.0.0.1` से bind करते हैं। Automatic macOS/Linux binary path के लिए `curl`, एक POSIX `sh`, और `tar` ज़रूरी हैं।
-`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=` से override करें।
+`iii-engine` मैनुअली install करें। **agentmemory वर्तमान में `iii-engine` को `v0.22.1` पर pin करता है**, जो इसकी `iii-sdk` dependency वाला ही release है; worker उसी engine का wire protocol बोलता है, और 0.20.0 ने SDK surface को reorganize किया, इसलिए दोनों agentmemory releases में साथ बढ़ते हैं। यदि आप अपना engine चलाते हैं और जानते हैं कि वह मेल खाता है तो `AGENTMEMORY_III_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 arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** `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 में जोड़ें
+- **Windows:** [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) से `iii-x86_64-pc-windows-msvc.zip` download करें और `iii.exe` को `%USERPROFILE%\.agentmemory\bin\iii.exe` में extract करें
-या Docker का उपयोग करें (bundled `docker-compose.yml` `iiidev/iii:0.11.2` खींचता है)। पूर्ण docs: [iii.dev/docs](https://iii.dev/docs)।
+हर archive के release page पर एक matching `.sha256` file होती है; जब आप platform बदलते हैं, तो ऊपर दिए check में उस file के hash का उपयोग करें (Windows पर: `Get-FileHash`)। `npx @agentmemory/agentmemory` में automatic installer इन hashes को pin करता है और ऐसे किसी archive को reject करता है जो मेल नहीं खाता।
+
+या Docker का उपयोग करें (bundled `docker-compose.yml` `iiidev/iii:0.22.1` खींचता है)। पूर्ण 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 के पास दो रास्ते हैं:
+agentmemory Windows 10/11 पर चलता है, लेकिन केवल Node.js package पर्याप्त नहीं है; आपको एक background process के रूप में pinned iii-engine v0.22.1 runtime भी चाहिए। CLI Windows ZIP को auto-extract नहीं करता, इसलिए native Windows users को `iii.exe` manually install करना होगा, या WSL2, या Docker Desktop चुनना होगा।
+
+Native Windows automated MCP wiring केवल `agentmemory connect copilot-cli` को support करता है। Claude Code, Codex, Cursor, और हर दूसरे native Windows agent के लिए, [अन्य एजेंट्स](#other-agents) से manual MCP block को उस agent की Windows config में copy करें। WSL में `connect` चलाना तभी उचित है जब target agent भी उसी WSL environment में installed हो; यह किसी Windows-host agent की configuration edit नहीं करता।
**विकल्प 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
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
```
**विकल्प B: Docker Desktop**
```powershell
-# 1. Windows के लिए Docker Desktop install करें
-# 2. Docker Desktop शुरू करें और सुनिश्चित करें कि engine चल रहा है
-# 3. agentmemory चलाएँ — यह bundled compose file को auto-start करेगा:
-npx -y @agentmemory/agentmemory
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
-**विकल्प C: केवल standalone MCP (कोई engine नहीं)।** अगर आपको केवल अपने agent के लिए MCP tools चाहिए और REST API, व्यूअर, या cron jobs की ज़रूरत नहीं है, तो engine को पूरी तरह से skip करें:
+**विकल्प C: केवल standalone MCP (कोई engine नहीं)।** अगर आपको केवल अपने agent के लिए MCP tools चाहिए और REST API, viewer, या cron jobs की ज़रूरत नहीं है, तो engine को पूरी तरह से skip करें:
```powershell
-npx -y @agentmemory/agentmemory mcp
-# या shim package के माध्यम से:
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
npx -y @agentmemory/mcp
```
-**Windows के लिए diagnostics:** अगर `npx @agentmemory/agentmemory` fail करता है, तो वास्तविक engine stderr देखने के लिए `--verbose` के साथ फिर से चलाएँ। सामान्य failure modes:
+**Windows के लिए diagnostics:** अगर `npx -y @agentmemory/agentmemory@latest` fail करता है, तो वास्तविक engine stderr देखने के लिए `--verbose` के साथ फिर से चलाएँ। सामान्य failure modes:
| लक्षण | समाधान |
|---|---|
-| `iii-engine process started` फिर `did not become ready within 15s` | Engine startup पर crashed; `--verbose` के साथ फिर से चलाएँ, stderr check करें |
+| `The engine process started but the REST API never responded.` | पुष्टि करें कि सभी चार derived ports free हैं, verify करें कि pinned `iii.exe` alive रहा, फिर `--verbose` के साथ फिर से चलाएँ और captured engine stderr देखें |
| `Could not start iii-engine` | न तो `iii.exe` न ही Docker installed है। ऊपर विकल्प A या B देखें |
| Port conflict | `netstat -ano \| findstr :3111` से देखें कि क्या bind है, फिर उसे kill करें या `--port ` का उपयोग करें |
| Docker installed होने पर भी Docker fallback skip हो रहा है | सुनिश्चित करें कि Docker Desktop वास्तव में चल रहा है (system tray icon) |
-> नोट: iii **engine** एक prebuilt binary है, cargo crate नहीं, इसलिए इसे `cargo install` से install करने की कोशिश न करें। (iii **SDKs** crates.io, npm, और PyPI पर publish हैं, लेकिन agentmemory को उनकी ज़रूरत नहीं है।) समर्थित engine install methods, सभी v0.11.2 पर pinned: ऊपर वाला prebuilt v0.11.2 binary, version pin **के साथ** upstream `sh` install script `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), और Docker image `iiidev/iii:0.11.2`। केवल `install.sh | sh` **latest** engine install करता है, जिसे agentmemory support नहीं करता; हमेशा `VERSION=0.11.2` पास करें। सबसे आसान: बस `npx @agentmemory/agentmemory` चलाएँ, जो pinned engine को आपके लिए `~/.agentmemory/bin` में ले आता है।
+> नोट: iii **engine** एक prebuilt binary है, cargo crate नहीं, इसलिए इसे `cargo install` से install करने की कोशिश न करें। (iii **SDKs** crates.io, npm, और PyPI पर publish हैं, लेकिन agentmemory को उनकी ज़रूरत नहीं है।) समर्थित engine install methods, सभी v0.22.1 पर pinned: ऊपर वाला prebuilt binary, agentmemory का macOS/Linux auto-install path (`curl`, POSIX `sh`, और `tar` ज़रूरी), और Docker image `iiidev/iii:0.22.1`। एक bare upstream `install.sh | sh` latest engine install करता है, जिसे agentmemory support नहीं करता। `npx -y @agentmemory/agentmemory@latest` का उपयोग करें; macOS/Linux पर यह pinned engine को `~/.agentmemory/bin` में ला देता है।
---
-
Deploy
+
डिप्लॉय
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
+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`
@@ -783,18 +943,18 @@ CLI को exec करने से पहले `gosu` के माध्य
Render का one-click deploy button repository root पर `render.yaml` की आवश्यकता रखता है,
जिसे हम जानबूझकर साफ़ रखते हैं। In-repo blueprint पर manually point करने के लिए
-[`deploy/render/`](../deploy/render/README.md) में documented Render Blueprint flow का उपयोग करें।
+[`deploy/render/`](.././deploy/render/README.md) में documented Render Blueprint flow का उपयोग करें।
पूर्ण setup विवरण (HMAC capture, viewer SSH tunnel,
-rotation, backup, cost floors) [`deploy/`](../deploy/README.md) में रहते हैं:
+rotation, backup, cost floors) [`deploy/`](.././deploy/README.md) में रहते हैं:
-- [`deploy/fly`](../deploy/fly/README.md): `auto_stop_machines = "stop"` के साथ
+- [`deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"` के साथ
single machine; सबसे सस्ता idle।
-- [`deploy/railway`](../deploy/railway/README.md): Hobby plan flat fee,
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby plan flat fee,
dashboard में volume।
-- [`deploy/render`](../deploy/render/README.md): Blueprint flow,
+- [`deploy/render`](.././deploy/render/README.md): Blueprint flow,
paid plans पर automatic disk snapshots।
-- [`deploy/coolify`](../deploy/coolify/README.md): अपने स्वयं के VPS पर
+- [`deploy/coolify`](.././deploy/coolify/README.md): अपने स्वयं के VPS पर
[Coolify](https://coolify.io/self-hosted) के माध्यम से self-hosted; वही Docker
Compose stack, आप host और data के मालिक हैं।
@@ -806,7 +966,7 @@ SSH-tunnel pattern को document करता है।
-हर coding agent सेशन समाप्त होने पर सब कुछ भूल जाता है, और हर नया सेशन आपके अपने stack को फिर से समझाने से शुरू होता है। agentmemory पृष्ठभूमि में चलता है और उस step को हटा देता है।
+हर coding agent session समाप्त होने पर सब कुछ भूल जाता है, और हर नया session आपके अपने stack को फिर से समझाने से शुरू होता है। agentmemory पृष्ठभूमि में चलता है और उस step को हटा देता है।
```text
Session 1: "Add auth to the API"
@@ -846,9 +1006,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -923,21 +1084,25 @@ Memories समय के साथ decay होती हैं (Ebbinghaus cur
Reciprocal Rank Fusion (RRF, k=60) के साथ fuse होता है और session-diversified होता है (प्रति session max 3 results)।
-Hybrid ranking केवल `smart-search` पर नहीं बल्कि primary recall path पर लागू होती है: `mem::search` (`memory_recall` के पीछे) vector index populate होने के बाद उसी BM25 + vector + graph fusion के माध्यम से rank करता है। Lesson recall हर query पर पूरे corpus को scan करने के बजाय एक dedicated in-memory BM25 index पर चलती है। Superseded memory versions हर recall path से excluded हैं; version chain उनका history रखती है।
+जब vector index populated होता है, तो `mem::search` (`memory_recall` के पीछे) hybrid BM25 + vector ranker का उपयोग करता है। Embeddings के बिना यह BM25 का उपयोग करता है। Graph data मौजूद होने पर `smart-search` अतिरिक्त रूप से structural graph matches को भी fuse कर सकता है, keyless mode में भी। Lesson recall हर query पर पूरे corpus को scan करने के बजाय एक dedicated in-memory BM25 index पर चलती है। Superseded memory versions हर recall path से excluded हैं; version chain उनका history रखती है।
+
+Vectors किसी crash या force-kill से बच जाते हैं। Vector index को कम से कम हर `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 मिनट) पर buckets में save किया जाता है। इसके बीच जोड़ा या हटाया गया हर vector भी state store में एक छोटे pending log में तुरंत लिखा जाता है, और अगला start embedding provider को call किए बिना उसे replay करता है। हर successful save उस log को खाली कर देता है। जिन documents के पास replay के बाद भी कोई vector नहीं है उन्हें background में `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) के batches में तब तक re-embed किया जाता है जब तक कोई बाकी न रहे, और रुका हुआ backfill अगले start पर जारी रहता है। `/agentmemory/status` और viewer pending log का size और backfill state दिखाते हैं। Keyless installs कुछ नहीं लिखते।
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):
+Keyless installs vector embeddings को disable करते हैं: `mem::search` BM25 का उपयोग करता है, जबकि `smart-search` मौजूदा structural graph data का भी उपयोग कर सकता है। free on-device semantic embeddings opt in करने के लिए, इसे `~/.agentmemory/.env` में जोड़ें और agentmemory restart करें:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+Normal npm install में optional `@huggingface/transformers` runtime शामिल है। पहला embedding request `Xenova/all-MiniLM-L6-v2` डाउनलोड करता है, इसलिए इसे network access चाहिए और इसमें अधिक समय लग सकता है; उसके बाद inference on-device चलता है। Remote providers उनकी keys से auto-detect होते हैं जब तक `EMBEDDING_PROVIDER` उन्हें override न करे।
+
| Provider | Model | Cost | नोट्स |
|---|---|---|---|
-| **Local (अनुशंसित)** | `all-MiniLM-L6-v2` | Free | Offline, BM25-only पर +8pp recall |
+| **Local (अनुशंसित opt-in)** | `all-MiniLM-L6-v2` | Free | पहले model download के बाद on-device, 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 |
@@ -950,7 +1115,7 @@ npm install @huggingface/transformers
54 tools, 6 resources, 3 prompts, और 17 skills।
-> **MCP shim बनाम full server:** published `@agentmemory/mcp` package एक thin shim है। यह full 54-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 करें।
+> **MCP shim बनाम full server:** published `@agentmemory/mcp` package एक thin shim है। यह full 54-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 -y @agentmemory/agentmemory@latest` (या Docker stack) शुरू करें और `AGENTMEMORY_URL=http://localhost:3111` set करें।
### 54 Tools
@@ -1035,20 +1200,20 @@ npm install @huggingface/transformers
| Skill | `/session-history` | हाल के session summaries |
| Skill | `/forget` | Observations/sessions delete करें |
-यह table चार core skills दिखाती है। पूरा set 8 invocable skills और 7 reference skills है; ऊपर Native skills section देखें।
+यह table चार core skills दिखाती है। पूरा set 9 invocable skills और 8 reference skills है; ऊपर Native skills section देखें।
### Standalone MCP
Full server के बिना चलाएँ, किसी भी MCP client के लिए। इनमें से कोई भी काम करता है:
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (हमेशा उपलब्ध)
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
या अपने agent की MCP config में जोड़ें:
-अधिकांश agents (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+अधिकांश agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1063,7 +1228,7 @@ npx -y @agentmemory/mcp # shim package alias
}
```
-`agentmemory` entry को file को replace करने के बजाय अपने host के मौजूदा `mcpServers` object में merge करें। होस्ट के `localhost` तक नहीं पहुँच सकने वाले sandboxed clients के लिए, env block में `"AGENTMEMORY_FORCE_PROXY": "1"` जोड़ें और `AGENTMEMORY_URL` को एक ऐसे route पर set करें जिस तक sandbox पहुँच सकता है।
+`agentmemory` entry को file को replace करने के बजाय अपने host के मौजूदा `mcpServers` object में merge करें। host के `localhost` तक नहीं पहुँच सकने वाले sandboxed clients के लिए, env block में `"AGENTMEMORY_FORCE_PROXY": "1"` जोड़ें और `AGENTMEMORY_URL` को एक ऐसे route पर set करें जिस तक sandbox पहुँच सकता है।
OpenCode (`opencode.json`):
```json
@@ -1090,13 +1255,20 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Port `3113` पर auto-start होता है। Stream status indicator के साथ live observation stream, एक two-pane session explorer (wide screens पर list एक sticky detail panel के बगल में), memory और lesson rows जो raw JSON और origin provenance सहित पूरे stored record तक expand होती हैं, एक knowledge graph जो relations sparse रहते हुए nodes को type के अनुसार cluster करता है, session replay, और एक health dashboard।
+Port `3113` पर auto-start होता है। Viewer connect होने पर एक snapshot load करता है (`GET /agentmemory/viewer/snapshot`) और फिर live stream events apply करता है: नई memories, lessons, observations, audit entries, graph changes और health updates बिना polling या page reloads के दिखाई देती हैं। अन्य केवल वे requests हैं जो आप click करते हैं — actions, "load more" pages, और searches। जब stream drop होता है, viewer दिखाता है कि उसके numbers कितने पुराने हैं, backoff के साथ reconnect करता है, और एक snapshot से resync करता है।
+
+- **चार groups में 12 tabs**, live counts, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), keyboard shortcuts, और एक mobile menu के साथ।
+- **Memories:** server-side search, project, agent, और type के अनुसार filters, version chain और word diff वाला एक detail panel, provenance links, id/MCP call/curl command के लिए copy buttons, edit (एक नई version), confirmation के साथ forget, bulk forget, और JSON export।
+- **Sessions:** readable tool input और output वाली एक inline observation timeline, filters और paging, और हर session से produced memories और lessons।
+- **Graph:** search, relations और sources वाला node detail, एक legend जो केवल colour पर निर्भर नहीं करता, और zoom controls।
+- **Health:** `GET /agentmemory/status` का live version। हर problem अपने fix के साथ आती है, साथ ही state backend, index save state, graph provenance compaction progress, और असली thresholds वाला एक consolidation explainer।
+- **Audit, Activity, Profile, Replay, Lessons, Actions, और Crystals** pages, हर एक में एक empty state जो बताता है कि section क्या है, वह खाली क्यों है, और कौन सा command उसे भरता है, साथ ही हर term और number पर एक `?` glossary tooltip।
```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'`)।
+Viewer server default रूप से `127.0.0.1` से bind होता है और REST API को requests forward करते समय server secret attach करता है, इसलिए इसे किसी setup की ज़रूरत नहीं। REST-served `/agentmemory/viewer` endpoint सामान्य bearer-token नियमों का पालन करता है और token के बिना browsers को viewer port पर redirect करता है। CSP headers per-response script nonce का उपयोग करते हैं और inline handler attributes को disable करते हैं (`script-src-attr 'none'`)।
---
@@ -1114,22 +1286,20 @@ agentmemory इसे free में ship करता है क्योंक
Workers page: हर connected worker, agentmemory स्वयं सहित, PID, function count, runtime, और last-seen के साथ।
-**पहले से installed।** Console `iii` के साथ ship होता है; कोई अलग installer नहीं।
+**पहले से installed।** Console pinned `iii` engine (0.22+) के साथ ship होता है; कोई अलग installer नहीं। पहली launch console binary को engine के बगल में download करती है।
**agentmemory के साथ launch करें:**
```bash
-# agentmemory viewer port 3113 रखता है, तो console को 3114 पर चलाएँ।
-# Engine REST (3111), WebSocket (3112), और bridge (49134) defaults agentmemory से match करते हैं।
-iii console --port 3114
+agentmemory console
```
-फिर `http://localhost:3114` खोलें। Experimental architecture-graph page के लिए `--enable-flow` जोड़ें।
+यह pinned engine का `iii console` उन ports के विरुद्ध चलाता है जो agentmemory ने resolve किए (REST, streams, bridge) और इसे viewer से एक port ऊपर serve करता है, default रूप से `http://localhost:3114`। `--console-port N` कोई और port चुनता है; `--port` और `--instance` उसी तरह agentmemory instance चुनते हैं जैसे वे `stop` के लिए करते हैं; कोई भी अन्य flag pass through होती है, जैसे experimental architecture-graph page के लिए `--enable-flow`।
-केवल तभी engine endpoints override करें जब आपने उन्हें move किया हो:
+वही चीज़ हाथ से, तब उपयोगी जब `agentmemory` PATH पर न हो:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1158,7 +1328,7 @@ iii console --port 3114 \
**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 पढ़ सकता है।
+`iii-config.yaml` `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs) के साथ ship होता है। कोई extra config की ज़रूरत नहीं; जैसे ही agentmemory शुरू होता है, हर memory operation एक structured log emit करता है जिसे console पढ़ सकता है, और उनमें से हर दसवाँ (`sampling_ratio: 0.1`) एक trace span भी emit करता है।
अगर आप इसके बजाय Jaeger/Honeycomb/Grafana Tempo पर export करना चाहते हैं, तो `exporter: memory` को `exporter: otlp` में बदलें और iii के observability docs के अनुसार collector endpoint set करें।
@@ -1170,34 +1340,104 @@ iii console --port 3114 \
agentmemory **पहले से एक चल रहा [iii](https://iii.dev) instance है**। तीन primitives (worker, function, trigger) runtime compose करते हैं; KV state, streams, और OTEL traces iii के साथ ship होने वाले iii-state, iii-stream, और iii-observability workers से आते हैं। आपने Postgres, Redis, Express, pm2, या Prometheus install नहीं किया, क्योंकि iii उन्हें replace करता है।
-इसका मतलब है कि एक और कमांड agentmemory को एक पूरी नई capability के साथ extend करती है।
+इसका मतलब है कि एक और command agentmemory को एक पूरी नई capability के साथ extend करता है।
-### एक command के साथ agentmemory को extend करें
+### agentmemory को और workers के साथ 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
-```
+जो builtins agentmemory को चाहिए वे पहले से `iii-config.yaml` में हैं और उसके साथ boot होते हैं: `iii-state` (KV), `iii-queue` (event subscribers के लिए durable retries), `iii-pubsub`, `iii-cron`, `iii-stream`, और `iii-observability` (हर function पर OTEL traces, metrics और logs)। [iii worker registry](https://workers.iii.dev) से कुछ भी और उसी engine में plug हो जाता है: `iii-config.yaml` को `~/.agentmemory/iii-config.yaml` में copy करें (CLI bundled file की जगह उस file को prefer करता है और फिर भी उसमें ports और data paths render करता है), entry जोड़ें, `~/.agentmemory/bin/iii update worker` से worker runtime को एक बार install करें, और agentmemory restart करें।
-प्रत्येक `iii worker add` उसी engine में नए functions और triggers register करता है जिस पर agentmemory पहले से चल रहा है। Viewer और console उन्हें तुरंत pick करते हैं: कोई reload नहीं, कोई नया integration नहीं, कोई नया container नहीं।
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | agentmemory के ऊपर आपको क्या मिलता है |
+| Worker | 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 |
+| [`database`](https://workers.iii.dev/workers/database) | जब आप in-memory KV defaults से बाहर निकलते हैं तो एक SQL-backed state adapter |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` से निकला code आपके shell में नहीं, एक throwaway VM के अंदर चलता है |
| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory के साथ-साथ extra MCP servers खड़े करें, वही engine share करें |
+Engine 0.22.x पर ऊपर दिए builtins के लिए `iii-` prefixed names रखें; unprefixed `http`, `state`, `queue`, `pubsub`, और `cron` entries standalone registry workers हैं जिन पर agentmemory 0.23 migration के साथ move होगा।
+
Full registry: [workers.iii.dev](https://workers.iii.dev)। वहाँ हर worker उन्हीं primitives के माध्यम से compose करता है जिनका agentmemory उपयोग करता है, और आपके पास पहले से जो agentmemory है, वह उनमें से एक है।
+### Engine config और bind address
+
+`agentmemory start` पहली मौजूद file से engine config पढ़ता है: `AGENTMEMORY_III_CONFIG`, current directory में `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, फिर bundled `iii-config.yaml`। हर start पर यह उस file (data paths, ports, state backend) को `~/.agentmemory/data/iii-config.runtime.yaml` में render करता है और engine को rendered copy के साथ launch करता है, इसलिए source file को edit करें, rendered वाली को नहीं। Source file की `host:` values वैसी ही रखी जाती हैं जैसी लिखी गई थीं।
+
+Bundled `iii-config.yaml` जानबूझकर `127.0.0.1` से bind करता है, और यह default container के अंदर भी लागू होता है। Container में शुरू हुआ CLI container के loopback को सुनता है, इसलिए published ports कहीं नहीं पहुँचते। Published ports के माध्यम से एक containerized CLI serve करने के लिए, `AGENTMEMORY_III_CONFIG` को ऐसी config पर set करें जो `0.0.0.0` से bind करती है। Packaged `iii-config.docker.yaml` ऐसी ही एक config है: यह `iii-http`, `iii-stream`, और engine port को `0.0.0.0` से bind करती है और state को `/data` के अंतर्गत store करती है, इसलिए वहाँ एक writable volume mount करें। `AGENTMEMORY_SECRET` set रखें, और केवल वे ports publish करें जिनकी ज़रूरत है, `127.0.0.1` पर या किसी trusted proxy के पीछे।
+
+इस repo की `docker-compose.yml` CLI के config lookup से नहीं गुज़रती: यह `iii-config.docker.yaml` को `/app/config.yaml` पर mount करती है, और `iii-engine` container `--config /app/config.yaml` के साथ शुरू होता है। One-click [deploy templates](../deploy/) अपने entrypoints में अपनी स्वयं की `0.0.0.0` config लिखते हैं।
+
+### Storage backend: file (default) बनाम redis
+
+`iii-state` और `iii-stream` डिफ़ॉल्ट रूप से iii-engine के bundled file-based KV store का उपयोग करते हैं: प्रति scope एक JSON file, जो engine process की memory में रहती है और एक timer पर disk पर rewrite होती है। Single-user local install के लिए यही सही default है; कई concurrent writers वाला एक shared daemon इसके बजाय Redis से real per-key writes पाता है, प्रति operation एक network round trip की कीमत पर (हर `state::*` call अभी भी एक Redis connection पर serialize होती है, इसलिए यह file store के lock को एक socket से बदलता है, parallelism से नहीं)।
+
+दोनों workers को iii-engine के built-in `redis` adapter पर switch करने के लिए `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) set करें, जो हर write पर पूरे scope को rewrite करने के बजाय हर key को एक Redis hash field (`HSET`) के रूप में store करता है:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` डिफ़ॉल्ट रूप से `file` है; इसे unset छोड़ने पर आज का behavior अपरिवर्तित रहता है, और कोई unrecognized value (`file` या `redis` के अलावा कुछ भी) एक silent fallback के बजाय एक startup error है। `/agentmemory/status` और viewer का Health page (State store row) report करते हैं कि कौन-सा backend active है और क्या वह answer कर रहा है, URL कभी नहीं।
+
+**केवल plain `redis://`।** Pinned engine (0.22.1) अपने Redis client को TLS support के बिना build करता है, इसलिए एक `rediss://` URL (ज़्यादातर managed Redis offerings, जैसे Upstash, Redis Cloud, और in-transit encryption वाला ElastiCache, डिफ़ॉल्ट रूप से TLS-only हैं) connect करने में fail होता है। Connection unencrypted है, इसलिए Redis password और हर stored memory wire पर clear text में जाती है: किसी local Redis या किसी trusted private network पर वाले Redis को point करें। किसी भी अन्य Redis के लिए, agentmemory host पर एक encrypted tunnel (stunnel, SSH, या एक VPN) चलाएँ, ताकि plain `redis://` hop उस host पर ही रहे और tunnel का upstream connection encrypted और authenticated हो। अगर किसी Redis password में single quote है, तो उसे percent-encode करें (`%27`); engine URL को parse करने से पहले उसे अपनी YAML config में expand करता है।
+
+**प्रति `--instance` एक Redis server।** Engine के Redis key prefixes (`state:`, `stream::`) fixed हैं, इसलिए एक ही database पर point की गई दो agentmemory instances (`--instance 1`, `--instance 2`, ...) एक-दूसरे का data overwrite कर देती हैं। एक अलग database index (`redis://localhost:6379/1`) stored data को अलग रखता है, लेकिन engine live viewer events को एक Redis pub/sub channel (`stream::events`) पर relay करता है, और Redis pub/sub database index को ignore करता है, इसलिए हर instance का viewer फिर भी दूसरी instance के live events दिखाएगा। एक से ज़्यादा instance चलाते समय हर instance को उसका अपना Redis server (या port) दें।
+
+**क्या वैसा ही रहता है, और क्या अलग होता है।** Redis पर agentmemory का हर feature काम करता है: sessions, observations, memories (remember, supersede, evolve, forget), search और index buckets, lessons, graph, audit log और उसके monthly scopes, export और import, governance deletes, consolidation status, viewer snapshot और उसकी live stream, और health monitor। Engine हर scope को एक Redis hash (`HSET`/`HGET`/`HGETALL`) के रूप में store करता है और file store जैसे ही state triggers fire करता है। तीन engine differences agentmemory के अंदर handle होते हैं:
+
+- Redis किसी scope के records बिना किसी fixed order के return करता है। agentmemory उन्हें सबसे पुराने पहले sort करता है (record id में creation time से, फिर उसके timestamp से) ताकि lists, paging, और export chunks उसी order में आएँ जैसे file store पर।
+- Engine Redis पर partial updates को एक Lua script में apply करता है जो empty arrays को empty objects में बदल देता है। agentmemory Redis पर वे updates खुद apply करता है (per-key lock के अंतर्गत read, change, write), इसलिए `tags: []` जैसे fields arrays बने रहते हैं।
+- Legacy audit log check, disk पर file store की file ढूँढ़ने के बजाय, old scope को Redis से पढ़ता है।
+
+एक difference को आपकी ज़रूरत है: **Redis restart होने के बाद, engine viewer को live events relay करना बंद कर देता है** जब तक agentmemory restart न हो। Data अभी भी normally save और read होता है। Health monitor हर 30 seconds में Redis के माध्यम से एक test event भेजता है; जब वह वापस नहीं आता, तो `/agentmemory/status` और viewer का Health page fix के साथ "Live updates are not reaching the viewer" दिखाते हैं: agentmemory restart करें। अगर Redis down है, तो status report "The state store is not answering" दिखाती है और उसे check करने का तरीका (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)। एक बहुत बड़े scope को list करना पूरी hash को एक `HGETALL` में पढ़ता है, वही cost जो file store के memory में रखने पर है।
+
+**अनुशंसित Redis settings।** Default `save 3600 1 300 100 60 10000` snapshot policy किसी crash पर मिनटों के writes खो सकती है, जो file store की 5s flush window से भी बुरा है। जो भी खोना आपको बुरा लगे उसके लिए `appendonly yes` set करें। `maxmemory-policy noeviction` set करें; `allkeys-lru` या इसी तरह की कोई चीज़ Redis के memory limit तक पहुँचने पर memories को silently drop कर देती है।
+
+एक native (non-Docker) start, और हर one-click [deploy template](../deploy/) (वे bundled `iii-config.yaml` को overwrite करते हैं और natively start होते हैं), `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` पढ़ते हैं और उन्हें launched `iii-config` में render करते हैं। URL खुद उस rendered file में कभी नहीं लिखा जाता, केवल एक `${AGENTMEMORY_REDIS_URL}` reference जिसे engine process boot पर अपने environment से expand करती है। केवल इस repo का अपना Docker Compose path (`AGENTMEMORY_USE_DOCKER=1`, या उस तरह शुरू किए गए engine को resume करना) `iii-config.docker.yaml` को read-only mount करता है और कभी render नहीं करता; `agentmemory start` उस combination को detect करने पर warn करता है। उस file को हाथ से बदलें, [iii-state](https://workers.iii.dev/workers/iii-state) और [iii-stream](https://workers.iii.dev/workers/iii-stream) worker docs में दिखाए गए वही `name: redis` / `config: redis_url: ...` shape का पालन करते हुए, और `redis_url` को container से पहुँच योग्य किसी Redis पर point करें। `docker-compose.yml` `AGENTMEMORY_REDIS_URL` को engine container में pass करता है, इसलिए `redis_url: '${AGENTMEMORY_REDIS_URL}'` वहाँ काम करता है और URL को mounted file से बाहर रखता है।
+
+Rendered config URL को `~/.agentmemory/data/iii-config.runtime.yaml` से बाहर रखती है, लेकिन engine का अपना configuration worker boot होने पर भी *expanded* value को `~/.agentmemory/config/iii-state.yaml` और `iii-stream.yaml` में persist करता है (iii-engine का `${VAR}` expansion उस worker के अपना seed store करने से पहले होता है, और यह resolved value store करता है, reference नहीं)। उस directory को एक credential रखने वाली मानें: किसी shared host पर `chmod 700 ~/.agentmemory` करें, और database की admin credentials के बजाय agentmemory की ज़रूरत तक scoped किसी Redis ACL user को prefer करें।
+
+**Migration automatic नहीं है।** `AGENTMEMORY_STATE_BACKEND` बदलना दोनों तरफ़ एक empty store से शुरू होता है; कुछ भी मौजूदा data को file से Redis में या वापस copy नहीं करता। जिस backend को आप छोड़ रहे हैं उससे export करें और जिस पर जा रहे हैं उसमें import करें। यह bash और zsh दोनों के अंतर्गत समान रूप से चलता है (`bash -u` सहित)। `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` जैसा एक array नहीं चलता: zsh header को एक malformed word के रूप में रखता है जहाँ bash इसे दो में split करता है, इसलिए जब भी `AGENTMEMORY_SECRET` set है दोनों requests 401 होती हैं:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` एक बड़े corpus को कई calls में chunk करने के लिए `?maxSessions=` और `?offset=` भी accept करता है; import पर `strategy` `merge` (default-safe), `replace`, या `skip` होती है।
+
### iii क्या replace करता है
| Traditional stack | agentmemory उपयोग करता है |
@@ -1209,7 +1449,7 @@ Full registry: [workers.iii.dev](https://workers.iii.dev)। वहाँ हर
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add ` |
-**184 source files · ~42,200 LOC · 1,674 tests · 264 functions · 50 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
+**225 source files · ~54,000 LOC · 2,600+ tests · 312 functions · 66 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
---
@@ -1217,11 +1457,11 @@ Full registry: [workers.iii.dev](https://workers.iii.dev)। वहाँ हर
### LLM Providers
-agentmemory आपके environment से auto-detect करता है। Default रूप से, जब तक आप एक provider configure नहीं करते या Claude subscription fallback में explicitly opt in नहीं करते, कोई LLM calls नहीं की जातीं।
+agentmemory आपके environment से providers को auto-detect करता है। एक provider LLM-backed operations को उपलब्ध कराता है, लेकिन केवल provider configuration LLM-written observation compression को enable नहीं करता। उस path के लिए provider और `AGENTMEMORY_AUTO_COMPRESS=true` दोनों चाहिए।
| Provider | Config | नोट्स |
|----------|--------|-------|
-| **No-op (default)** | कोई config की ज़रूरत नहीं | LLM-backed compress/summarize DISABLED है। Synthetic BM25 compression + recall अभी भी काम करते हैं। अगर आप पहले Claude-subscription fallback पर निर्भर थे तो नीचे `AGENTMEMORY_ALLOW_AGENT_SDK` देखें। |
+| **No-op (default)** | कोई config की ज़रूरत नहीं | LLM-backed compress/summarize disabled है। Synthetic compression और BM25 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 करता है |
@@ -1237,7 +1477,7 @@ agentmemory किसी भी OpenAI-API-compatible server से बात
**Ollama** (default port `11434`):
```bash
-ollama pull qwen3:8b # या qwen3:4b, gpt-oss:20b, qwen3-coder:30b, आदि
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
```
@@ -1275,11 +1515,11 @@ Qwen 3 models default रूप से think करते हैं और क
Reasoning-class models (`` blocks वाले `o1`-style) खाली `content` के साथ एक `reasoning` field return कर सकते हैं जिसे आपका local server शायद surface न करे। अगर extractions blank आती हैं, तो पहले एक non-reasoning model पर switch करें। `OPENAI_REASONING_EFFORT=none` env उन Ollama Cloud thinking models पर भी thinking disable कर सकता है जो OpenAI reasoning schema को mirror करते हैं।
-Local embeddings `@huggingface/transformers` के माध्यम से out of the box ship होती हैं: `EMBEDDING_PROVIDER=local` (default) आपको पूरी तरह on-device `Xenova/all-MiniLM-L6-v2` (384-dim) देता है। किसी extra config की ज़रूरत नहीं।
+Local embeddings एक optional dependency के रूप में ship होती हैं लेकिन default रूप से enabled नहीं हैं। `Xenova/all-MiniLM-L6-v2` (384-dim) में opt in करने के लिए `EMBEDDING_PROVIDER=local` set करें। पहला embedding request model को download करता है; उसके बाद inference on-device चलता है। उस setting या किसी remote embedding key के बिना, vectors disabled रहते हैं, `mem::search` BM25 का उपयोग करता है, और `smart-search` फिर भी मौजूदा graph matches जोड़ सकता है।
### 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 पर चलाया गया।
+जब LLM-written background compression एक provider और `AGENTMEMORY_AUTO_COMPRESS=true` दोनों के साथ enabled होता है, तो यह हर 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 | नोट्स |
|------|-------|------------|-------------|---------------------------|-------|
@@ -1320,7 +1560,7 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
Isolated mode में क्या filter होता है: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`। प्रत्येक endpoint per-request override के लिए `?agentId=` और 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 के लिए उपयोगी। MCP `memory_save` tool वही `agentId` field expose करता है, standalone stdio server `agentId` और `project` दोनों forward करता है, और saved memories `agentId` को search index में carry करती हैं, इसलिए agent-scoped search observations के साथ-साथ memories को भी कवर करती है।
+SDK / REST layer पर per-call override: हर mutating endpoint (`/session/start`, `/remember`) request body में एक `agentId` field accept करता है जो env से जीतता है। एक server process के माध्यम से कई roles को route करने वाले runtimes के लिए उपयोगी। MCP `memory_save` tool वही `agentId` field expose करता है, standalone stdio server `agentId` और `project` दोनों forward करता है, और saved memories `agentId` को search index में carry करती हैं, इसलिए agent-scoped search observations के साथ-साथ memories को भी cover करती है।
जब `AGENT_ID` unset होता है, तो memory unscoped रहती है (legacy behavior, कोई tags नहीं, कोई filters नहीं)।
@@ -1331,14 +1571,18 @@ agentmemory + iii-engine default रूप से चार ports पर bind
| 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`) |
+| `3112` | iii-engine | Internal streams worker (agentmemory + viewer द्वारा consumed) | `III_STREAM_PORT` (preferred) या legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | reported URL के लिए `III_VIEWER_PORT` या `AGENTMEMORY_VIEWER_URL` |
+| `49134` | iii-engine | WebSocket; workers यहाँ register होते हैं, OTel telemetry इसी पर flow होती है | `III_ENGINE_PORT` या `III_ENGINE_URL` |
+
+`--port ` REST anchor बदलता है और streams `N+1`, viewer `N+2`, और engine WebSocket `N+46023` derive करता है, लेकिन केवल तब जब ऊपर दिया matching explicit port या URL unset हो। यह कोई isolated lifecycle namespace नहीं बनाता। दूसरे daemon के लिए `--instance 1` का उपयोग करें; यह anchor 3211 उपयोग करता है, डिफ़ॉल्ट रूप से `3211/3212/3213/49234`, और एक अलग `instance-1` data और lifecycle directory पाता है। Instances 1 से 50 तक वही pattern follow करते हैं।
+
+Pinned engine `--no-update-check` के साथ शुरू होता है (boot पर GitHub के विरुद्ध कोई update या security-advisory lookup नहीं) और iii के anonymous usage telemetry को off के साथ: agentmemory अपने spawn किए engine के लिए `III_TELEMETRY_ENABLED=false` set करता है जब तक आप स्वयं वह variable export न करें, और bundled compose file भी वही करती है।
Crashed run के बाद ports bound रहने पर stale-process cleanup:
```bash
-# macOS / Linux — हर port पर जो भी है उसे ढूँढ़ें और kill करें
+# 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
@@ -1348,7 +1592,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` graceful shutdown पर worker और engine pidfile दोनों को साफ़ रूप से reap करता है। Docker mode में यह केवल agentmemory की अपनी compose services को tear down करता है और Docker teardown से पहले native worker को reap करता है; CLI Docker या VM port holders (Docker backend, vpnkit, colima) को native engine के रूप में adopt या signal करने से भी मना करता है जब तक `--force` pass न किया जाए। ऊपर का manual cleanup केवल post-crash case के लिए है जहाँ कोई भी pidfile पीछे नहीं छोड़ी गई।
+`agentmemory stop` graceful native shutdown पर worker और engine pidfile दोनों को साफ़ रूप से reap करता है। Docker mode में यह native worker को flush करता है, exact validated engine container को stop करता है, और एक lossless restart के लिए container और उसके `/data` mount दोनों को preserve करता है; अगला start उसी container को validate और resume करता है। Docker-backed uninstall के लिए `agentmemory remove --keep-data` चाहिए: यह shared agentmemory-managed files को हटाता है जबकि validated container, उसका data mount, और उन्हें recover करने के लिए ज़रूरी lifecycle record preserve करता है। Destructive Docker data deletion जानबूझकर backup के बाद operator पर छोड़ा गया है। CLI Docker या VM port holders (Docker backend, vpnkit, colima) को native engine के रूप में adopt या signal करने से भी मना करता है जब तक `--force` pass न किया जाए। ऊपर का manual cleanup केवल post-crash case के लिए है जहाँ कोई भी pidfile पीछे नहीं छोड़ी गई।
### Config File
@@ -1370,11 +1614,13 @@ AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-अगर आप graph या consolidation features चाहते हैं तो उसी file में उन्हें on करें:
+LLM-written observation compression के लिए दोनों lines चाहिए: एक LLM provider तक access (इस explicit subscription fallback सहित) और `AGENTMEMORY_AUTO_COMPRESS=true`। सिर्फ़ एक provider default synthetic compression path को ही जगह पर छोड़ देता है।
+
+Consolidation (graph nodes, lessons, crystals) जब भी कोई LLM provider configured होता है तो default रूप से on रहता है। अगर आप LLM-free operation चाहते हैं तो `CONSOLIDATION_ENABLED=false` के साथ explicitly opt out करें। Graph extraction एक अलग flag है:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Environment Variables
@@ -1416,13 +1662,15 @@ CONSOLIDATION_ENABLED=true
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1440,14 +1688,20 @@ CONSOLIDATION_ENABLED=true
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1488,13 +1742,43 @@ CONSOLIDATION_ENABLED=true
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
-# CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1508,7 +1792,19 @@ CONSOLIDATION_ENABLED=true
-Port `3111` पर 124 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। `AGENTMEMORY_SECRET` set होने पर protected endpoints `Authorization: Bearer ` की आवश्यकता रखते हैं, और mesh sync endpoints दोनों peers पर `AGENTMEMORY_SECRET` की आवश्यकता रखते हैं।
+Port `3111` पर 138 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। Protected endpoints `Authorization: Bearer ` की आवश्यकता रखते हैं, और mesh sync endpoints दोनों peers पर एक explicitly set `AGENTMEMORY_SECRET` की आवश्यकता रखते हैं।
+
+**Authentication डिफ़ॉल्ट रूप से on है।** जब `AGENTMEMORY_SECRET` set नहीं है (shell में या `~/.agentmemory/.env` में), server पहले start पर एक random secret generate करता है और इसे mode `0600` के साथ `~/.agentmemory/secret` में store करता है। हर bundled client किसी local server से बात करते समय इसे वहाँ से पढ़ता है: CLI, viewer, `plugin/scripts` के अंतर्गत hooks, MCP server और `@agentmemory/mcp` shim, `agentmemory connect` द्वारा लिखी गई configs, और bundled OpenCode, Pi, OpenClaw, Hermes, और filesystem-watcher integrations। Stored secret केवल loopback URLs (`localhost`, `127.0.0.0/8`, `::1`) पर भेजा जाता है। एक explicit `AGENTMEMORY_SECRET` हमेशा जीतता है, और remote clients को फिर भी इसे set करना होता है। Docker और `deploy/` entrypoints पहले से अपना स्वयं का secret generate और export करते हैं। API को हाथ से call करने के लिए:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Writes के लिए request rules।** REST API और viewer को `POST`, `PUT`, `PATCH`, और `DELETE` requests, जब भी उनके पास एक body हो, `Content-Type: application/json` भेजनी चाहिए (एक `charset` parameter ठीक है), और एक `Origin` header, जब मौजूद हो, configured REST या viewer port के लिए एक loopback origin होना चाहिए या `VIEWER_ALLOWED_ORIGINS` (comma-separated, जैसे `https://memory.example.com`) में सूचीबद्ध होना चाहिए। बिना `Origin` header भेजने वाले clients (CLI, hooks, MCP, curl, server-to-server) प्रभावित नहीं होते। Viewer अपना स्वयं का origin भी accept करता है।
+
+**File paths।** Files पढ़ने या लिखने वाले endpoints (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) केवल `~/.agentmemory`, instance data directory, या `AGENTMEMORY_IMPORT_ROOT` में सूचीबद्ध किसी directory के अंतर्गत paths accept करते हैं (कई को `:` से अलग करें, Windows पर `;` से)। `/replay/import-jsonl` अपने default `~/.claude/projects` को भी accept करता है। `/obsidian/export` `AGENTMEMORY_EXPORT_ROOT` के अंदर और `/migrate` `~/.agentmemory` के अंदर रहता है। Symlinks हर check से पहले resolve किए जाते हैं।
+
+**Secret scrubbing।** API keys, bearer tokens, PEM private key blocks, और URLs में embedded credentials (`scheme://user:password@host`) को text store होने से पहले हर write path पर redact किया जाता है: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, compression और summary output, crystals, और graph nodes।
मुख्य endpoints
@@ -1516,9 +1812,14 @@ Port `3111` पर 124 endpoints। REST API default रूप से `127.0.0.1
| Method | Path | विवरण |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check (हमेशा public) |
+| `GET` | `/agentmemory/status` | क्या गलत है और उसे कैसे ठीक करें (browsers के लिए HTML, अन्यथा JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | viewer जो कुछ भी दिखाता है, एक response में |
| `POST` | `/agentmemory/session/start` | Session शुरू करें + context प्राप्त करें |
| `POST` | `/agentmemory/session/end` | Session समाप्त करें |
-| `POST` | `/agentmemory/observe` | Observation capture करें |
+| `POST` | `/agentmemory/observe` | Observation capture करें (नीचे capture delivery देखें) |
+| `GET` | `/agentmemory/capture` | Capture inbox, dead letters, और offline spool |
+| `POST` | `/agentmemory/capture/retry` | Dead-letter captures को retry करें |
+| `POST` | `/agentmemory/capture/drain` | Local offline spool अभी भेजें |
| `POST` | `/agentmemory/smart-search` | Hybrid search |
| `POST` | `/agentmemory/context` | Context generate करें |
| `POST` | `/agentmemory/remember` | Long-term memory में save करें |
@@ -1528,6 +1829,7 @@ Port `3111` पर 124 endpoints। REST API default रूप से `127.0.0.1
| `GET` | `/agentmemory/export` | सभी data export करें |
| `POST` | `/agentmemory/import` | JSON से import करें |
| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
+| `POST` | `/agentmemory/graph/compact` | Oversized graph provenance को trim करें |
| `POST` | `/agentmemory/team/share` | Team के साथ share करें |
| `GET` | `/agentmemory/audit` | Audit trail |
@@ -1535,6 +1837,35 @@ Full endpoint list: [`src/triggers/api.ts`](../src/triggers/api.ts)
+**Capture delivery।** Hooks हर observation को एक `eventId` के साथ `POST /agentmemory/observe` पर एक बार भेजते हैं। जब payload के पास अपना एक id होता है (उदाहरण के लिए Claude Code का `tool_use_id`) तो यह call के लिए host की अपनी id होती है, अन्यथा session, hook type, tool name, input, output, और host timestamp का एक hash। Server event को state store में एक capture inbox में लिखता है, observation को store करता है, फिर inbox entry को हटा देता है। Status code बताता है कि क्या हुआ:
+
+| Status | `status` field | अर्थ |
+|---|---|---|
+| `201` | `accepted` | Stored। `observationId` नई observation है। |
+| `202` | `accepted` (`state: "retrying"`) | Accepted, लेकिन storing fail हो गया। Server इसे retry करता है, एक restart के बाद भी। |
+| `200` | `duplicate` | यह `eventId` पहले ही accepted था। `observationId` मौजूदा observation है; कुछ भी नया store नहीं होता। |
+| `400` / `422` | `rejected` | Invalid payload, या storing हमेशा के लिए fail हो गया (event को एक dead letter के रूप में रखा जाता है)। |
+| `503` | `rejected` (`retryable: true`) | Inbox full है (`AGENTMEMORY_CAPTURE_INBOX_MAX`)। Hooks event को spool करते हैं और बाद में भेजते हैं। |
+
+Failed events को हर `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) पर doubling backoff के साथ retry किया जाता है, `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5) तक। जो events फिर भी fail होते रहते हैं वे dead letters के रूप में inbox में रहते हैं, `/agentmemory/status` और viewer के Health page पर list होते हैं, और `POST /agentmemory/capture/retry` (`{"eventId": "..."}` या `{"all": true}`) से retry किए जा सकते हैं। Accepted event ids को `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 hours, अधिकतम `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids) तक याद रखा जाता है, इसलिए किसी timeout या restart के बाद replayed हुआ एक hook एक बार store होता है, जबकि अपनी-अपनी host ids वाली दो अलग tool calls दो बार store होती हैं भले ही उनका content identical हो। जब एक observation delete होती है (forget, session delete, eviction, auto-forget, या store को replace करने वाला कोई import), उसका event observation हटने से पहले deleted mark होता है, इसलिए उसी window के अंदर उस event का replay एक duplicate के रूप में answer होता है और कुछ भी store नहीं करता। State store हर 2 seconds में disk पर लिखता है, इसलिए एक answered event अभी भी एक पल के लिए केवल memory में हो सकता है। इसे cover करने के लिए, हर `2xx` answer server का `bootId` (हर start पर नया), `acceptedAt`, और `durableAfterMs` (file store पर save interval plus 1.5 s, redis पर 1.5 s, जहाँ persistence operator की setting है) भी carry करता है। Hooks event को local spool में तब तक रखते हैं जब तक वह window गुज़र न जाए और बिना किसी और request के किसी बाद वाली call पर इसे delete कर देते हैं। अगर तब तक `bootId` बदल गया है, तो server restart हो गया था, इसलिए hook उसी `eventId` के साथ event फिर भेजता है; जो event disk तक पहुँच गया था वह दो बार store नहीं होता। Server खुद भी ऐसे events को start पर और हर retry interval पर भेजता है, इसलिए एक restart कुछ नहीं खोता भले ही बाद में कोई hook न चले। पुराने hooks extra fields को ignore करते हैं, और एक पुराने server के विरुद्ध नए hooks event को `2xx` पर पहले की तरह discard कर देते हैं।
+
+जब server down हो, समय पर answer न दे, या एक 5xx return करे, तो hook observation को एक local spool file में append करता है, `/capture-spool/-.jsonl` (folder को `AGENTMEMORY_CAPTURE_SPOOL_DIR` से override करें)। File आपके user के लिए private है (mode 600), secrets उसी तरह redact होते हैं जैसे server उन्हें redact करता है, यह अधिकतम `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) रखती है और `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168) से पुरानी entries drop कर देती है। जब यह full होती है, नई entries drop होकर count होती हैं, और `/agentmemory/status` इसे report करता है। जब server healthy है तब hook अभी भी अपनी time limit के अंदर 0 exit करता है और कोई request नहीं जोड़ता। Spool अगले start पर और server तक फिर से पहुँचने वाले पहले hook द्वारा, एक background process में भेजा जाता है ताकि agent को wait न करना पड़े। Event ids इसे safe बनाती हैं: एक timeout से पहले पहुँची observation दो बार store नहीं होती। `npx @agentmemory/agentmemory capture` spool और server inbox दिखाता है, `--drain` अभी spool भेजता है, और `GET /agentmemory/capture` वही JSON के रूप में return करता है। Spool को बंद करने के लिए `AGENTMEMORY_CAPTURE_SPOOL=false` set करें।
+
+**Graph provenance को compact करना।** हर knowledge graph node और edge उन नवीनतम 32 observations की ids रखता है जिनसे वह आया। उस cap से पहले लिखे गए stores प्रति hot node हज़ारों ids रख सकते हैं, जो graph search और viewer को धीमा कर देता है या worker को drop कर देता है। agentmemory इसे खुद ठीक करता है: upgrade के बाद पहली start पर यह हर node, edge, superseded edge (temporal graph history), और cached snapshot को background में cap तक trim करता है, छोटे slices में उनके बीच एक pause के साथ, ताकि search, capture, और viewer काम करते रहें। यह अपनी progress save करता है, एक restart के बाद resume होता है, और finish होने के बाद फिर कभी नहीं चलता। `/agentmemory/status` और viewer का Health page इसे pending, running (current scope और position के साथ), done, या failed के रूप में दिखाते हैं। इसे बंद करने के लिए `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` set करें।
+
+इसे हाथ से चलाने के लिए, `POST /agentmemory/graph/compact` call करें। यह हर node और edge list करने के बजाय name और edge-key indexes को walk करता है, और इसे फिर से चलाना safe है। जब यह ids trim करता है तो यह एक `graph_compact` audit entry लिखता है।
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+एक बड़े store पर, या जब call 504 return करे, तो इसे slices में चलाएँ। `scope` (`nodes`, `edges`, या `history`), `offset`, और `limit` भेजें, फिर returned `nextOffset` के साथ फिर से call करें जब तक वह `null` न हो जाए। यह `nodes`, `edges`, और `history` के लिए करें, और एक `{"scope":"snapshot"}` call के साथ ख़त्म करें, क्योंकि एक sliced run cached snapshot को नहीं छूता।
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1542,11 +1873,11 @@ Full endpoint list: [`src/triggers/api.ts`](../src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
-npm run test:integration # API tests (running services की आवश्यकता है)
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
```
-**आवश्यकताएँ:** Node.js >= 20, [iii-engine](https://iii.dev/docs) या Docker
+**आवश्यकताएँ:** npm/npx के साथ Node.js >= 20; [iii-engine](https://iii.dev/docs) v0.22.1 या Docker। macOS/Linux automatic engine install के लिए `curl`, एक POSIX `sh`, और `tar` भी ज़रूरी हैं; native Windows manual pinned `iii.exe`, WSL2, या Docker Desktop का उपयोग करता है।
diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.md
new file mode 100644
index 0000000000..40bb3780f8
--- /dev/null
+++ b/READMEs/README.hu-HU.md
@@ -0,0 +1,1881 @@
+
+
+
+
+
+
+ A kódolóágensed mindenre emlékszik. Nem kell többé újra elmagyaráznod.
+ A iii engine-re épül
+
+ Állandó memória a Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode és bármely MCP kliens számára.
+
+ A gist Karpathy LLM Wiki mintáját bővíti ki megbízhatósági pontszámmal, életciklus-kezeléssel, tudásgráfokkal és hibrid kereséssel: az agentmemory ennek az implementációja.
+
+
+---
+
+## Install
+
+Követelmények:
+
+- Node.js 20 vagy újabb, npm-mel és npx-szel (`node -v`, `npm -v`, és `npx -v`).
+- A macOS/Linux alatti automatikus iii-engine telepítéshez `curl`, egy POSIX `sh`, és `tar` is szükséges. A minimális image-ek, mint a `node:20-slim`, esetleg nem tartalmazzák ezeket.
+- A natív Windows a pinnelt iii-engine v0.22.1 `iii.exe` manuális telepítését igényli. A WSL2 vagy a Docker Desktop a másik két támogatott út.
+
+A kanonikus friss telepítési parancs:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Az első futás egy interaktív beállítás: válaszd ki a bekötendő ágenseket (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), válassz egy LLM-szolgáltatót vagy maradj kulcs nélkül, majd létrehozza a konfigurációt, elindítja a memóriaszervert és a hozzá pinnelt iii engine-t, végül felajánlja a globális telepítést, hogy ezután mindenhol működjön a sima `agentmemory` parancs. A `-y` elfogadja az npx csomag-promptját, a `@latest` pedig elkerüli az elavult gyorsítótárazott kiadást. Egy szolgáltató elérhetővé teszi az LLM-funkciókat, de az LLM által írt megfigyelés-tömörítés csak akkor indul el, ha az `AGENTMEMORY_AUTO_COMPRESS=true` is be van állítva.
+
+A kulcs nélküli mód letiltja a vektor-embeddingeket. A `memory_recall` (a `mem::search` útvonal) BM25-öt használ, míg a `memory_smart_search` strukturális gráfegyezéseket is összevonhat, ha már létezik gráfadat. Az ingyenes, eszközön futó szemantikus felidézéshez állítsd be az `EMBEDDING_PROVIDER=local` értéket a `~/.agentmemory/.env` fájlban, majd indítsd újra. Az első embedding-kérés letölti a `Xenova/all-MiniLM-L6-v2` modellt; az azt követő következtetés már lokálisan fut.
+
+A lokális futtatási környezet négy portot használ: `3111`-et a REST/MCP HTTP-hez, `3112`-t az iii stream-ekhez, `3113`-at a megjelenítőhöz, és `49134`-et az iii worker WebSockethez. A tartós iii állapot macOS-en a `~/Library/Application Support/agentmemory` mappában, Linuxon a `$XDG_DATA_HOME/agentmemory` vagy `~/.local/share/agentmemory` mappában, Windowson pedig a `%APPDATA%\agentmemory` mappában él. A `--data-dir ` kapcsolóval vagy az `AGENTMEMORY_DATA_DIR` változóval írhatod felül; minden újraindításnál ugyanazt az értéket használd. A visszafelé kompatibilitás miatt egy már létező `./data/state_store.db` vagy `./data/iii-config.yaml` elsőbbséget kap a platform alapértelmezésével szemben a 0. instance esetén; egy explicit kapcsoló vagy környezeti felülírás továbbra is elsőbbséget kap.
+
+Ezután bizonyítsd be, hogy a felidézés működik, és add meg az ágensednek a saját skilljeit:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+A kulcsszavas kereséseknek alapértelmezett kulcs nélküli módban is találniuk kell a BM25 révén. A demó `database performance optimization` lekérdezése szándékosan szemantikus, és nulla eredményt adhat, amíg nincs beállítva embedding-szolgáltató.
+
+Inkább hagynád, hogy egy kódolóágens végezze el az egészet? Add neki egyetlen utasítást:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Bármikor bekötsz további ágenseket az `agentmemory connect ` paranccsal — 20 adapter van felsorolva a [Működik minden ágenssel](#works-with-every-agent) részben. A teljes parancsreferencia a [Gyors indítás](#quick-start) alatt található.
+
+
+Windows
+
+A gyors útvonal a WSL2. A natív Windows engine beállításhoz a pinnelt v0.22.1 ZIP letöltése és az `iii.exe` manuális kibontása szükséges; a CLI nem bontja ki automatikusan. A Docker Desktop is támogatott. Lásd a [Windows megjegyzéseket](#windows) a lépésről lépésre útmutatóért.
+
+
+
+
+Globális telepítés / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+A fenti npx parancs marad a kanonikus friss telepítési útvonal, és elkerüli a globális prefix jogosultsági problémáit.
+
+
+
+
+Az npx egy régi verziót szolgál ki
+
+Az npx verziónként gyorsítótáraz. Kényszerítsd a legújabbat az `npx -y @agentmemory/agentmemory@latest` paranccsal, vagy töröld egyszer a gyorsítótárat a `rm -rf ~/.npm/_npx` paranccsal (macOS/Linux; Windows alatt töröld a `%LOCALAPPDATA%\npm-cache\_npx` mappát).
+
+
+
+
+Már fut egy saját iii engine
+
+Az agentmemory a iii-engine v0.22.1-et pinneli, és nem kapcsolódik más verzióhoz (a worker nem tud egy másik engine protokolljával beszélni). Állítsd le a másik engine-t, majd futtasd az `npx -y @agentmemory/agentmemory@latest` parancsot. Ez telepíti és futtatja a pinnelt v0.22.1-et a `~/.agentmemory/bin` mappában, érintetlenül hagyva a saját `iii`-edet.
+
+
+
+---
+
+
+
+Az agentmemory bármelyik olyan ágenssel működik, amely támogatja a hookokat, az MCP-t vagy a REST API-t. Minden ágens ugyanazt a memóriaszervert osztja meg.
+
+
+ Bármely MCP-t vagy HTTP-t beszélő ágenssel működik. Egyetlen szerver, közöttük megosztott memóriákkal.
+
+
+---
+
+Minden alkalommal elmagyarázod ugyanazt az architektúrát. Mindig ugyanazokat a hibákat fedezed fel újra. Mindig ugyanazokat a preferenciákat tanítod be újra. A beépített memória (CLAUDE.md, .cursorrules) 200 sornál korlátozódik, és elavulttá válik. Az agentmemory ezt megoldja. Némán rögzíti, mit csinál az ágensed, kereshető memóriává tömöríti, és a megfelelő kontextust befecskendezi, amikor elindul a következő session. Egyetlen parancs. Ágensek között is működik.
+
+**Mi változik:** Az 1. sessionben beállítod a JWT hitelesítést. A 2. sessionben rate limitinget kérsz. Az ágens már tudja, hogy a hitelesítésed a jose middleware-t használja a `src/middleware/auth.ts` fájlban, a tesztjeid lefedik a token-validálást, és a jose-t választottad a jsonwebtoken helyett az Edge-kompatibilitás miatt — nincs újramagyarázás, nincs copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Alapértelmezés szerint az agentmemory a repón kívül tárolja az iii-engine állapotát, amelyből elindítottad: macOS-en a `~/Library/Application Support/agentmemory`, Linuxon a `$XDG_DATA_HOME/agentmemory` vagy `~/.local/share/agentmemory`, Windowson pedig a `%APPDATA%\agentmemory` mappában. Egy már létező, örökölt `./data/state_store.db` vagy `./data/iii-config.yaml` fájlt a rendszer a 0. instance esetén a platform alapértelmezése előtt újrahasznosít. Egy explicit hely megadásához add meg a `--data-dir ` kapcsolót, vagy állítsd be az `AGENTMEMORY_DATA_DIR` változót; mindkét explicit beállítás elsőbbséget kap az örökölt felismeréssel szemben:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+A natív és a Docker-alapú indítás ugyanazt a feloldott host-mappát használja; a Docker a `/data` alá bind-mounteli. A `--instance 1` hozzáfűzi az `instance-1` nevet a feloldott mappához, és a különálló alapértelmezett port-négyest választja: `3211/3212/3213/49234`.
+
+A legfrissebb kiadási megjegyzések: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Visszakeresési pontosság
+
+**coding-agent-life-v1** (házon belüli korpusz, sandboxban reprodukálható)
+
+| Adapter | P@5 | R@5 | Top-5 találati arány | p50 késleltetés |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep alapvonal | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100%-os top-5 találati arány a **P@5 matematikai felső határán** ennél a korpusznál (0.240, lásd a scorecardot). A hibrid minden gold sessiont visszakeres; a grep 2-ből 1 gold eredményt elveszít a több sessiont átfogó, időbeli lekérdezésnél. A nyereség **felidézésben és időbeliségben** mutatkozik, nem az összesített pontosságban. Ez a benchmark kicsi és gold-szegény; a lejjebb található, nagyobb LongMemEval-S jobban differenciál. Teljes, típus szerinti bontás + korrekciós megjegyzés: [`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 kérdés)
+
+| Rendszer | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Csak BM25 fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+> Embedding modell: `all-MiniLM-L6-v2` (lokális, ingyenes, nincs szükség API-kulcsra). Teljes jelentések: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Versenytárs-összehasonlítás: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), amely az agentmemoryt a mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo rendszerekkel veti össze.
+
+**Lokális reprodukálás:** [`eval/README.md`](../eval/README.md), egy adapter-bővíthető harness a LongMemEval `_s` (nyilvános, 500 kérdéses) + `coding-agent-life-v1` (házon belüli, 15 sessiont tartalmazó korpusz) számára. A grep / vektor / agentmemory adapterek egymás mellett kapnak pontszámot, NDJSON kimenettel, a publikált scorecardok a [`docs/benchmarks/`](../docs/benchmarks/) mappában landolnak.
+
+**Jól illik a [codegraph](https://github.com/colbymchenry/codegraph), az [Understand Anything](https://github.com/Lum1104/Understand-Anything) és a [Graphify](https://github.com/safishamsi/graphify) mellé.** Kódgráf-indexelés, több ágenses build-pipeline-ok, és szélesebb tudásgráfok dokumentumok / PDF-ek / képek / videók fölött. Az agentmemory a munkára emlékszik; ez a három projekt a kontextusréteg többi részét kelti életre. Receptek + kérdés-útválasztási táblázat: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Beépített (CLAUDE.md)
+
+
+
Típus
+
Memóriamotor + MCP szerver
+
Memóriaréteg API
+
Teljes ágens-futtatókörnyezet
+
Személyes AI
+
Memória API + app
+
Csapatmemória-hub (LLM proxy)
+
Vektormemória (OSS)
+
Memóriamotor (Oracle DB)
+
Memóriarendszer
+
Statikus fájl
+
+
+
Visszakeresési R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Önbevallás alapján
+
PersonaMem 76% (önbevallás alapján)
+
~96.6% (önbevallás alapján)
+
94.4% (önbevallás alapján)
+
N/A
+
N/A (grep)
+
+
+
Automatikus rögzítés
+
12 hook (nulla manuális munka)
+
Manuális add() hívások
+
Az ágens saját szerkesztései
+
Manuális
+
API-oldali kinyerés
+
Proxy-elfogás (base-URL csere)
+
Manuális
+
API kinyerés
+
Manuális
+
Manuális szerkesztés
+
+
+
Keresés
+
BM25 + Vektor + Gráf (RRF fúzió)
+
Vektor + Gráf
+
Vektor (archivális)
+
Szemantikus
+
Vektor + RAG
+
4 eszköztípus (Chat / Skill / Wiki / CodeGraph)
+
Csak vektor
+
Vektor + szemantikus
+
Lecsengés-súlyozott
+
Mindent betölt a kontextusba
+
+
+
Több ágens
+
MCP + REST + lease-ek + szignálok
+
API (nincs koordináció)
+
Csak a Letta futtatókörnyezeten belül
+
Nem
+
Nem
+
Csapatszerepek + megosztott eszközök
+
Nem
+
Csak hatókörön belül
+
Több ágens közt megosztva
+
Ágensenkénti fájlok
+
+
+
Keretrendszer-függés
+
Nincs (bármely MCP kliens)
+
Nincs
+
Magas (a Lettát kell használni)
+
Önálló
+
Nincs
+
A proxy minden modellhívás elé kerül
+
Nincs
+
Oracle Database
+
Nincs
+
Ágensenkénti formátum
+
+
+
Külső függőségek
+
Nincs (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + vektor DB
+
Több
+
Felügyelt felhő
+
Docker-stack (Core + Hub + Proxy)
+
Vektortár
+
Oracle AI Database
+
Nincs
+
Nincs
+
+
+
Memória életciklus
+
4 szintű konszolidáció + lecsengés + automatikus elfelejtés
+
Passzív kinyerés
+
Az ágens kezeli
+
Manuális
+
Automatikus elfelejtés
+
Manuális átnézés; az automatikus útválasztás folyamatban
+
Nincs
+
Nincs megadva
+
Lecsengés + konszolidáció
+
Manuális ritkítás
+
+
+
Token-hatékonyság
+
~1,900 token/session ($10/év)
+
Az integrációtól függ
+
A core memória a kontextusban van
+
Változó
+
Felhő alapú díjszabás
+
Nincs megadva
+
Nincs token-budget
+
LLM-alapú (változó)
+
Változó
+
22K+ token 240 megfigyelésnél
+
+
+
Valós idejű megjelenítő
+
Igen (3113-as port)
+
Felhő alapú dashboard
+
Felhő alapú dashboard
+
Webes felhasználói felület
+
Felhő alapú dashboard
+
Hub webes felhasználói felület
+
Nincs
+
Nincs
+
Nincs
+
Nincs
+
+
+
Önállóan üzemeltethető
+
Igen (alapértelmezett)
+
Opcionális
+
Opcionális
+
Igen
+
Nem (csak felhő)
+
Igen (Docker)
+
Igen
+
Igen (Oracle DB)
+
Igen
+
Igen
+
+
+
+Megjegyzés a benchmarkhoz: csak az agentmemory R@5 értéke a saját, mért eredményünk (LongMemEval-S, reprodukálható a benchmark/COMPARISON.md alapján). A mem0 és a Letta számai a saját publikált LoCoMo-adataik (egy másik adathalmaz); a MemPalace, a supermemory, a TencentDB (PersonaMem) és az oracleagentmemory számai a gyártók önbevallás alapú állításai, amelyeket nem reprodukáltunk függetlenül (az oracleagentmemory futása GPT-5.5-öt használt egy Oracle AI Database ellen). Csak tájékoztató jellegű egymás mellett közlésre szánva, nem azonos adatokon futó közvetlen összehasonlításra. A csillagszámok közelítők, és idővel változnak.
+
+**Újabb belépők**, amelyeket érdemes ismerni, részletesen összehasonlítva a [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) fájlban:
+
+| Rendszer | ⭐ | Megközelítés |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporális tudásgráf; a legerősebb publikált időbeli lekérdezési eredmények (LongMemEval 63.8%), de a gráf aszinkron módon épül, így a friss tények lemaradhatnak |
+| Cognee | 30K | Dokumentum-tudásgráf feldolgozás, csak Python, strukturált entitáskinyerésre épül, nem session-rögzítésre |
+
+Ezek közül semelyik nem rögzít automatikusan kódolóágens-hookokból, nem szállít local-first megjelenítőt, és nem futtatható kulcs nélkül — ez a kombináció az, amire az agentmemory épül.
+
+---
+
+
+
+Kompatibilitás: ez a kiadás az `iii-sdk` 0.22.1-et célozza, és a iii-engine v0.22.1-et pinneli.
+
+### Próbáld ki 30 másodperc alatt
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+A `demo` 3 reális sessiont hoz létre (JWT hitelesítés, N+1 lekérdezés javítása, rate limiting), és kereséseket futtat ellenük. A kulcs nélküli telepítések letiltják a vektorokat, így a `mem::search` kulcsszavas lekérdezéseinek a BM25 révén kell találnia, míg a `database performance optimization` lekérdezés nulla eredményt adhat. A `smart-search` emellett strukturális gráfegyezéseket is visszaadhat, ha létezik gráfadat. Ahhoz, hogy a szemantikus lekérdezés vektorok révén megtalálja az N+1 javítást, állítsd be az `EMBEDDING_PROVIDER=local` értéket, indítsd újra, és hagyd, hogy az első modell-letöltés befejeződjön.
+
+Nyisd meg a `http://localhost:3113` címet, hogy élőben lásd a memória épülését.
+
+### Egy friss telepítés és az újraindítás utáni perzisztencia ellenőrzése
+
+A szerver futása közben ellenőrizd a REST-et, az egészségjelzést, a megjelenítőt és az iii-alapú futtatókörnyezet státuszát:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Az indulási állapotpanel mind a négy portot számba veszi: a REST/MCP HTTP-t a 3111-en, az iii stream-eket a 3112-n, a megjelenítőt a 3113-on, és az iii worker WebSocketet a 49134-en. A `status` megerősíti az agentmemory egészségi állapotát és az aktív szolgáltatót/embedding-módot. Mentsd el egy próbamemóriát, és erősítsd meg, hogy kereshető:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Ezután futtasd az `npx -y @agentmemory/agentmemory@latest stop` parancsot, indítsd el újra a kanonikus parancsot az 1. terminálban, várd meg a `/agentmemory/livez`-t, és ismételd meg a keresést. A próbamemóriát továbbra is vissza kell adnia. Ha egyéni `--data-dir`-t választottál, add meg ugyanazt a mappát az újraindításnál is.
+
+### Napi parancsok
+
+A telepítés és a beállítás a fenti [Telepítés](#install) részben él (az első futás végigvezet rajta). Napi szinten:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Session Replay
+
+Minden session, amelyet az agentmemory rögzít, visszajátszható. Nyisd meg a megjelenítőt, válaszd a **Replay** fület, és pörgesd végig az idővonalat: a promptok, a toolhívások, a toolok eredményei és a válaszok különálló eseményekként jelennek meg, lejátszás/szünet gombbal, sebességvezérléssel (0.5x-tól 4x-ig) és billentyűparancsokkal (szóköz a váltáshoz, nyilak a léptetéshez).
+
+Régebbi Claude Code JSONL-transcriptek behozásához:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Az importált sessionök a natívok mellett jelennek meg a Replay választóban. A háttérben minden bejegyzés a `mem::replay::load`, a `mem::replay::sessions` és a `mem::replay::import-jsonl` iii funkciókon megy keresztül, mellékszerverek nélkül. Minden importált transcript indexelve van kereséshez, `import` eredetcsatornával van megjelölve, és session-kristály és tanulságok kinyeréséhez van feldolgozva.
+
+> **Figyelem, ha az `import-jsonl`-re támaszkodsz elsődleges rögzítési útvonalként:** a Claude Code `cleanupPeriodDays` beállítása (a `~/.claude/settings.json`-ban, alapértelmezetten **30**) automatikusan törli az ennél régebbi JSONL-transcripteket a `~/.claude/projects/`-ból. Ha az agentmemoryt egy több hónapos Claude Code előzményre telepíted frissen, minden, ami 30 napnál régebbi, már eltűnt az első import előtt. Vagy futtasd az `import-jsonl`-t cronon, vagy emeld fel a `cleanupPeriodDays`-t valami magasabbra, vagy kösd be az automatikus rögzítő hookokat (az alapértelmezett plugin-telepítési útvonal), hogy minden kör az agentmemorybe kerüljön, amíg a session él, és a JSONL-takarítás ne számítson többé.
+
+### Frissítés / karbantartás
+
+Használd a karbantartási parancsot, amikor szándékosan frissíteni akarod a lokális futtatókörnyezetet:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Figyelmeztetés: ez a parancs megváltoztatja a jelenlegi workspace-t/futtatókörnyezetet. Frissíthet JavaScript-függőségeket, és lehúzhatja a pinnelt `iiidev/iii:0.22.1` Docker image-et. Soha nem telepít pinnelés nélküli vagy újabb iii engine-t.
+
+Az implementációs részletek a `src/cli.ts`-ben élnek (lásd a `runUpgrade`-et a `src/cli.ts:544-595` környékén).
+
+### Claude Code (egyetlen blokk, illeszd be)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code a plugin telepítése nélkül (önálló MCP útvonal)
+
+Ha az agentmemory MCP szerverét közvetlenül a `~/.claude.json`-ban kötöd be, a `/plugin install` használata helyett, a Claude Code soha nem oldja fel a `${CLAUDE_PLUGIN_ROOT}`-ot, és a hook-szkripteket abszolút elérési utakra kell mutatnod a `~/.claude/settings.json`-ban. Ezek az útvonalak jellemzően beágyazzák az agentmemory verziószámát (pl. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), így a következő frissítés némán elront minden hookot.
+
+Megoldás:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Ez ugyanazokat a hook-parancsokat olvasztja be a `~/.claude/settings.json`-ba, abszolút elérési utakkal, amelyek a jelenleg telepített `@agentmemory/agentmemory` csomag becsomagolt `plugin/` mappájára mutatnak. Futtasd újra a parancsot az agentmemory frissítése után, hogy felfrissítsd az útvonalakat. A felhasználó saját bejegyzései ugyanabban a fájlban megmaradnak; csak a korábbi agentmemory-bejegyzések kerülnek lecserélésre. A `/plugin install` útvonal marad az ajánlott megközelítés.
+Távoli vagy védett telepítésekhez indítsd el a Claude Code-ot az `AGENTMEMORY_URL` és az `AGENTMEMORY_SECRET` beállításával. A plugin mindkét értéket továbbadja a becsomagolt MCP szerverének; amikor az `AGENTMEMORY_URL` üres, az MCP shim a `http://localhost:3111`-et használja.
+
+### Codex CLI (Codex plugin platform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+A Codex plugin ugyanabból a `plugin/` mappából kerül kiadásra, mint a Claude Code plugin. Ez regisztrálja:
+
+- Egy becsomagolt stdio MCP híd a futó daemonhoz, npm-letöltés vagy fallback-tár nélkül. Lásd a [helyi Codex-útmutatót](../docs/plugins/codex-local.md) egy ki nem adott build teszteléséhez.
+- 6 életciklus-hookot: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 meghívható skillt: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plusz 8 referencia-skillt, amelyeket az ágens igény szerint tölt be (memóriadiszciplína, MCP eszközök, REST API, konfiguráció, ágensek, hookok, architektúra, és a skill-írási útmutató)
+
+A Codex hook-motorja befecskendezi a `CLAUDE_PLUGIN_ROOT`-ot a hook-alfolyamatokba (lásd [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), így ugyanazok a hook-szkriptek mindkét hoszton működnek, duplikálás nélkül. A Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure események csak Claude Code-specifikusak, és nincsenek regisztrálva a Codexhez.
+
+#### A Codex-hookok bizalma és kompatibilitása
+
+A natív plugin-hook kiváltás a Codex CLI 0.150.1-gyel ellenőrzött. A rögzítés elvárása előtt bízz meg (trust) a plugin-hookokban. A Codex Desktop viselkedése a becsomagolt runtime-jától függ; ellenőrizd a `/hooks`-ot, és erősíts meg egy rögzített eseményt, mielőtt engedélyeznél egy megoldást.
+
+Ha a hosztod globális hookokat igényel, tükrözd a parancsokat a `~/.codex/hooks.json`-ba. Amikor az MCP már bekötve van, a jelenlegi connector `--force`-ot igényel a hook-telepítés eléréséhez:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Ez beolvasztja a globális hookokat, és felülírja az agentmemory MCP-bejegyzést, megtartva a nem kapcsolódó bejegyzéseket. A `--force` használata előtt nézd át az agentmemory egyedi endpoint-beállításait. Frissítés után futtasd újra, hogy felfrissítsd a szkriptek elérési útjait. Engedélyezd vagy a natív plugin-hookokat, vagy a globális másolatokat, hogy elkerüld a duplikált rögzítést.
+
+### GitHub Copilot CLI
+
+VS Code agent módhoz használd a [Copilot MCP és automatikus rögzítés útmutatót](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). A CLI connector nem konfigurálja a VS Code-ot.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+Az `agentmemory connect copilot-cli` beolvasztja a `mcpServers.agentmemory`-t a `~/.copilot/mcp-config.json`-ba (vagy a `$COPILOT_HOME/mcp-config.json`-ba, ha a `COPILOT_HOME` be van állítva), és megtartja a meglévő szervereket. Natív Windowson ez az egyetlen automatizált `connect` adapter; minden más natív Windows-ágenst manuálisan kell konfigurálni. A WSL `connect` csak akkor támogatott, ha a célágens ugyanabban a WSL-környezetben van telepítve. A Copilot a következő indításkor vagy a `/mcp` után veszi fel az MCP szervert. Telepítsd a plugint is, ha a teljes hook/skill élményt szeretnéd.
+
+
+OpenClaw (illeszd be ezt a promptot)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Teljes útmutató: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (illeszd be ezt a promptot)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Teljes útmutató: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Egyéb ágensek
+
+Indítsd el a memóriaszervert: `npx -y @agentmemory/agentmemory@latest`
+
+#### Natív skillek az `npx skills add` révén (50+ ágens)
+
+Az agentmemory 17 skillt szállít a Claude-Code-stílusú `/SKILL.md` formátumban: 9 meghívható akció-skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) és 8 referencia-skill, amelyeket az ágens igény szerint tölt be (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). A referencia-skillek forrásból generált adattáblákat hordoznak, így soha nem térnek el. A [`skills`](https://npmjs.com/package/skills) CLI, a vercel-labs eszköze, automatikusan telepíti ezeket a hívó ágens natív skill-mappájába, 50+ ágens között (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, és még több):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Ez **kiegészíti** az `agentmemory connect `-et:
+
+- az `agentmemory connect ` beírja az MCP szerver konfigurációt, hogy az eszközök elérhetők legyenek.
+- az `npx skills add rohitg00/agentmemory` telepíti a skilleket, hogy az ágens tudja, mikor hívja őket.
+
+Azoknál a kevés ágensnél, amelyeket a skills CLI még nem fed le (Zed v1.3.x és régebbi), másold be saját kezűleg a 17 SKILL.md fájlt az ágens natív skill-mappájába; ugyanaz a formátum mindenhol működik.
+
+#### Standard MCP blokk
+
+Az agentmemory bejegyzés **ugyanaz az MCP szerver blokk** minden olyan hoszton, amely a `mcpServers` formátumot használja (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Olvasszd be ezt a bejegyzést a meglévő `mcpServers` objektumba** a hoszt konfigurációs fájljában; ne cseréld le a fájlt. Ha a fájlban már vannak más szerverek, add hozzá az `agentmemory`-t melléjük, egy újabb kulcsként a `mcpServers`-en belül. Ha a `mcpServers` teljesen hiányzik, illeszd be a blokkot a `{ "mcpServers": { ... } }` belsejébe. A `${VAR}` helyőrzők az `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` értékeket az MCP szerver indításakor a shellből öröklik; a be nem állított változók üres stringet adnak át, és a shim visszaesik a `http://localhost:3111`-re. Egy bekötött bejegyzés mind a lokális, mind a távoli (k8s / reverse-proxy mögötti) telepítéseket lefedi.
+
+| Ágens | Konfigurációs fájl | Megjegyzések |
+|---|---|---|
+| **Cursor (csak MCP)** | `~/.cursor/mcp.json` | Olvasztd be a `mcpServers`-be, vagy `agentmemory connect cursor`. Egykattintásos deeplink is elérhető a weboldalon. |
+| **Cursor (teljes plugin)** | `.cursor-plugin/` | Cursor Marketplace listázás (a beküldés felülvizsgálat alatt) vagy Cursor Settings → Plugins → lokális checkout. Regisztrál 7 automatikus rögzítő hookot (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skillt + az MCP szervert, az `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` kezelésével a Cursor plugin-dashboardján. Működik a Cursor IDE-ben és a `cursor-agent` CLI-ben; a CLI print-módú promptjai a session-transcriptből kerülnek visszapótlásra a session végén. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Olvasszd be a `mcpServers`-be. Indítsd újra a Claude Desktopot a szerkesztés után. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP beállítások (Settings UI → MCP Servers → Edit) | Ugyanaz a `mcpServers` blokk. |
+| **Devin CLI (MCP + hookok)** | `~/.config/devin/config.json` | Az `agentmemory connect devin` beolvasztja az MCP bejegyzést; a `--with-hooks` hozzáad hat natív automatikus rögzítő hookot (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) a Devin kisbetűs tool-matchereivel. Ellenőrizd a `devin mcp list` és a `/hooks` paranccsal a devinen belül. |
+| **Devin CLI (teljes plugin)** | `plugin/.devin-plugin/` | A `devin plugins install ./plugin` egy checkoutból regisztrálja mind a 17 skillt `/agentmemory:` slash parancsokként, plusz az MCP szervert. A Devin plugin-hookok nem tudják elsütni a `SessionStart`/`SessionEnd`-et, ezért párosítsd a `connect devin --with-hooks`-szal a teljes session-rögzítéshez. |
+| **Devin (felhő)** | Settings → Connections → MCP servers | Adj hozzá egy egyéni MCP-t (STDIO): parancs `npx`, argumentumok `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL`, amely egy hálózatilag elérhető agentmemory-telepítésre mutat, plusz `AGENTMEMORY_SECRET` (a felhős sessionök nem érik el a localhostot — lásd [`deploy/`](../deploy/)). Tárold a secretet a Devin Secretsben, majd a "Test listing tools" segítségével ellenőrizd, hogy mind az 54 eszköz megjelenik. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (automatikusan beolvaszt). |
+| **GitHub Copilot CLI (csak MCP)** | `~/.copilot/mcp-config.json` | Az `agentmemory connect copilot-cli` beolvasztja a `mcpServers.agentmemory`-t; a Copilot a következő indításkor vagy a `/mcp`-vel veszi fel. |
+| **GitHub Copilot CLI (teljes plugin)** | Copilot plugin telepítés | `copilot plugin install rohitg00/agentmemory:plugin` a GitHub-aldirektóriumban lévő pluginhoz. |
+| **OpenClaw** | OpenClaw MCP konfiguráció | Ugyanaz a `mcpServers` blokk. Mélyebben: az `openclaw plugins install ./integrations/openclaw` igényt tart az OpenClaw memória-slotjára (automatikusan átvált a `memory-core`-ról); állítsd be a `plugins.entries.agentmemory.hooks.allowConversationAccess=true`-t, különben a rögzítés némán blokkolva lesz. Lásd [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (csak MCP)** | `.codex/config.toml` | TOML formátum: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, vagy add hozzá manuálisan a `[mcp_servers.agentmemory]`-t. |
+| **Codex CLI (teljes plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory`, majd `codex plugin add agentmemory@agentmemory`. Regisztrálja az MCP-t + 6 életciklus-hookot + 17 skillt. Bízz meg a hookokban, és ellenőrizd a rögzítést a hosztodon; lásd a [Codex beállítása és ellenőrzése](../docs/plugins/codex-local.md) útmutatót. |
+| **OpenCode (csak MCP)** | `opencode.json` | Más formátum: felső szintű `mcp` kulcs, a parancs tömbként: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (teljes plugin)** | `plugin/opencode/` | 22 automatikus rögzítő hook, amely lefedi a session-életciklust, az üzeneteket, a toolokat és a hibákat. A projekt-attribúció sessiononkénti, így egyetlen, több repón átnyúló OpenCode-folyamat minden sessiont a saját projektje alá fájloz. Két slash parancs (`/recall`, `/remember`). Másold a `plugin/opencode/`-ot az OpenCode workspace-edbe, és add hozzá a plugin-bejegyzést az `opencode.json`-hoz. Lásd a [`plugin/opencode/README.md`](../plugin/opencode/README.md) fájlt a teljes hook-táblázatért + hiányanalízisért. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Az `agentmemory connect pi` telepíti a becsomagolt extension-t a pi automatikus felismerő mappájába (felidézés az ágens indulásakor, rögzítés az ágens végén, `memory_search` / `memory_save` / `memory_health` eszközök, `/agentmemory-status`). A `/reload` egy futó piben felveszi. [`integrations/pi`](../integrations/pi/) egyben egy pi-csomag is (`pi install ./integrations/pi` egy checkoutból). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | A `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` adja a 6-hookos memóriaszolgáltatót (prefetch, kör-rögzítés, session-vég, pre-compress, MEMORY.md-tükrözés, system prompt blokk). Validáld a `hermes plugins doctor` és a `hermes memory status` paranccsal. Lásd [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | Az `agentmemory connect qwen` beírja a standard `mcpServers` blokkot. A hook-payload mezőkompatibilis a Claude Code-dal, így a meglévő 12-hookos szkriptek módosítás nélkül működnek; kösd be őket a `hooks` szekcióban, ugyanabban a `settings.json`-ban. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | Az `agentmemory connect antigravity --with-hooks` telepíti az MCP-t és a rögzítő hookokat a megosztott testreszabási mappába. Lásd az [Antigravity beállítása és korlátai](../docs/plugins/antigravity.md) útmutatót. |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | Az `agentmemory connect antigravity-cli --with-hooks` ugyanazt az MCP- és hook-konfigurációt használja, mint a jelenlegi IDE-verziók. A meglévő telepítéseknek frissülniük kell a `--force`-szal; lásd a [frissítési megjegyzéseket](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | Az `agentmemory connect kiro` beírja a felhasználói szintű konfigurációt. A workspace-szintű felülírások a `.kiro/settings/mcp.json`-ba kerülnek, a kódod mellé. |
+| **Warp** | `~/.warp/.mcp.json` | Az `agentmemory connect warp` beírja a standard `mcpServers` blokkot. A Warp a skilleket is automatikusan felismeri a `.claude/skills/`-ből; a Claude Code plugin telepítése után a 8 agentmemory skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) natívan megjelenik a Warp slash-parancs palettáján. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | Az `agentmemory connect cline` beírja a standard `mcpServers` blokkot. VS Code extension felhasználóknak: illeszd be ugyanazt a blokkot a Cline Settings → MCP Servers → Edit JSON útján. |
+| **Continue.dev** | `~/.continue/config.yaml` (előnyben részesített) vagy `config.json` (örökölt) | Az `agentmemory connect continue` létrehoz egy `config.yaml`-t a semmiből, ha egyik sem létezik, vagy módosítja a meglévő `config.json`-t. **Ha már van `config.yaml`-od**, az adapter kiírja a pontos, a `mcpServers:` alá illesztendő blokkot; nem írja át némán a yaml-odat, mert a kommentek és a horgok biztonságos megtartásához egy YAML-parserre lenne szükség, amit a csomag nem szállít. A Continue tömb formátumot (nem objektumot) használ a `mcpServers`-hez. |
+| **Zed** | `~/.config/zed/settings.json` | Az `agentmemory connect zed` a `context_servers` alá ír (a Zed saját kulcsa, NEM a `mcpServers`). A távoli MCP szerverek egy `{"url": "..."}`-vel is bekötődhetnek. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | Az `agentmemory connect droid` beírja a standard `mcpServers` blokkot. A projekt-szintű felülírások a `/.factory/mcp.json`-ba kerülnek. Add meg a `--with-hooks`-ot a natív automatikus rögzítéshez. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Az `agentmemory connect dsh` hozzáfűz egy `@deepseek-ai/dsh-mcp-client` sort a home-szintű patch-réteghez, amelyet minden Harness-profil betölt; az eszközök `mcp__agentmemory__*`-ként regisztrálódnak. Add meg a `--with-hooks`-ot az automatikus rögzítés bekötéséhez is: a becsomagolt Claude Code hook-szkriptek a Harness első féltől származó `@deepseek-ai/dsh-hooks-claude-code` hídján keresztül futnak (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), egy a `$DSH_HOME/agentmemory.hooks.json`-ba írt manifeszt révén. Alapértelmezés szerint `~/.dsh`-ra áll, ha a `DSH_HOME` nincs beállítva. |
+| **Goose** | Goose MCP beállítások felhasználói felülete | Ugyanaz a `mcpServers` blokk; használd a `goose configure` → Add Extension → MCP menüt. A közvetlen YAML-szerkesztés a `~/.config/goose/config.yaml`-ban is támogatott, de a séma `extensions:` + `cmd`-t használ (nem `mcpServers:` + `command`-ot). |
+| **Aider** | n/a | Beszélj közvetlenül a REST API-val: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Bármely ágens (32+)** | n/a | Az `npx skillkit install agentmemory` automatikusan felismeri a hosztot, és beolvaszt. |
+
+**Sandboxolt MCP kliensek** (Flatpak / Snap / korlátozó konténerek), amelyek nem érik el a hoszt `localhost`-ját: állítsd be a `"AGENTMEMORY_FORCE_PROXY": "1"`-et is az `env` blokkban, és az `AGENTMEMORY_URL`-t irányítsd egy olyan útvonalra, amit a sandbox valóban elér (pl. a LAN-IP-d).
+
+### Programozott hozzáférés (Python / Rust / Node)
+
+Az agentmemory iii funkciókként regisztrálja a fő műveleteit (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Bármely nyelv, amelyhez van iii SDK, közvetlenül hívhatja ezeket a `ws://localhost:49134` felett, nyelvenkénti külön REST kliens nélkül.
+
+```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"},
+})
+```
+
+Kidolgozott példa: [`examples/python/`](../examples/python/) (gyors indítás + megfigyelés/felidézés folyamat). A REST a `:3111`-en elérhető marad azokhoz a hosztokhoz, amelyeknek nincs iii futtatókörnyezetük.
+
+### Forrásból
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Ez elindítja az agentmemoryt egy lokális `iii-engine`-nel, ha a pinnelt binárist már telepítetted, vagy Docker Compose-t használ, ha azt választod. A REST, a stream-ek és a megjelenítő alapértelmezetten a `127.0.0.1`-hez kötődnek. Az automatikus macOS/Linux binárisútvonal `curl`-t, egy POSIX `sh`-t és `tar`-t igényel.
+
+Telepítsd az `iii-engine`-t manuálisan. **Az agentmemory jelenleg a `v0.22.1`-re pinneli az `iii-engine`-t**, ugyanarra a kiadásra, mint az `iii-sdk` függősége; a worker ennek az engine-nek a wire-protokollját beszéli, és a 0.20.0 átszervezte az SDK felületét, így a kettő az agentmemory kiadásaiban együtt mozog. Írd felül az `AGENTMEMORY_III_VERSION=` segítségével, ha saját engine-t futtatsz, és tudod, hogy megegyezik.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** cseréld ki az `aarch64-apple-darwin`-t `x86_64-apple-darwin`-ra
+- **Linux x64:** cseréld ki `x86_64-unknown-linux-gnu`-ra
+- **Linux arm64:** cseréld ki `aarch64-unknown-linux-gnu`-ra
+- **Windows:** töltsd le az `iii-x86_64-pc-windows-msvc.zip`-et az [iii-hq/iii kiadások v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) oldalról, és bontsd ki az `iii.exe`-t a `%USERPROFILE%\.agentmemory\bin\iii.exe` helyre
+
+Minden archívumhoz tartozik egy illő `.sha256` fájl a kiadási oldalon; ha platformot cserélsz, használd azt a fájl hash-ét a fenti ellenőrzésben (Windowson: `Get-FileHash`). Az `npx @agentmemory/agentmemory`-ban lévő automatikus telepítő pinneli ezeket a hash-eket, és visszautasít minden archívumot, amely nem egyezik.
+
+Vagy használj Dockert (a becsomagolt `docker-compose.yml` lehúzza az `iiidev/iii:0.22.1`-et). Teljes dokumentáció: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+Az agentmemory Windows 10/11-en fut, de maga a Node.js-csomag nem elég; a pinnelt iii-engine v0.22.1 futtatókörnyezetre is szükség van háttérfolyamatként. A CLI nem bontja ki automatikusan a Windows ZIP-et, így a natív Windows-felhasználóknak manuálisan kell telepíteniük az `iii.exe`-t, vagy a WSL2-t, vagy a Docker Desktopot kell választaniuk.
+
+A natív Windows automatizált MCP-bekötés csak az `agentmemory connect copilot-cli`-t támogatja. A Claude Code, a Codex, a Cursor és minden más natív Windows-ágens esetén másold be a manuális MCP blokkot az [Egyéb ágensek](#other-agents) részből az adott ágens Windows-konfigurációjába. A `connect` futtatása WSL-ben csak akkor megfelelő, ha a célágens is ugyanabban a WSL-környezetben van telepítve; nem szerkeszti egy Windows-hoszton futó ágens konfigurációját.
+
+**A opció: előre lefordított Windows binárist (ajánlott)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**B opció: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**C opció: csak önálló MCP (engine nélkül).** Ha csak az MCP eszközökre van szükséged az ágensedhez, és nincs szükséged a REST API-ra, a megjelenítőre vagy a cron-feladatokra, hagyd ki teljesen az engine-t:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnosztika Windowshoz:** ha az `npx -y @agentmemory/agentmemory@latest` elbukik, futtasd újra `--verbose`-szal, hogy lásd a valódi engine stderr-t. Gyakori hibamódok:
+
+| Jelenség | Megoldás |
+|---|---|
+| `The engine process started but the REST API never responded.` | Erősítsd meg, hogy mind a négy levezetett port szabad, ellenőrizd, hogy a pinnelt `iii.exe` életben maradt, majd futtasd újra `--verbose`-szal, és vizsgáld meg a rögzített engine stderr-t |
+| `Could not start iii-engine` | Sem az `iii.exe`, sem a Docker nincs telepítve. Lásd a fenti A vagy B opciót |
+| Port-konfliktus | `netstat -ano \| findstr :3111`, hogy lásd, mi van hozzákötve, majd öld ki, vagy használj `--port `-t |
+| A Docker-fallback kimarad, bár a Docker telepítve van | Győződj meg róla, hogy a Docker Desktop valóban fut (a tálca ikonja) |
+
+> Megjegyzés: az iii **engine** egy előre lefordított bináris, nem egy cargo crate, ezért ne próbáld `cargo install`-lal telepíteni. (Az iii **SDK-k** publikálva vannak a crates.io-n, az npm-en és a PyPI-n, de az agentmemorynak nincs szüksége rájuk.) A támogatott engine-telepítési módok mind a v0.22.1-re vannak pinnelve: a fenti előre lefordított bináris, az agentmemory macOS/Linux automatikus telepítési útvonala (`curl`, POSIX `sh`, és `tar` szükséges), és az `iiidev/iii:0.22.1` Docker image. A sima, upstream `install.sh | sh` a legújabb engine-t telepíti, amit az agentmemory nem támogat. Használd az `npx -y @agentmemory/agentmemory@latest`-et; macOS/Linuxon ez lehúzza a pinnelt engine-t a `~/.agentmemory/bin`-be.
+
+---
+
+
Telepítés (Deploy)
+
+Egykattintásos sablonok felügyelt hosztokhoz. Mindegyik egy önálló
+Dockerfile-t szállít, amely lehúzza az `@agentmemory/agentmemory`-t az npm-ről, és
+bemásolja az iii engine binárist a hivatalos `iiidev/iii` Docker Hub
+image-ből; nincs szükség előre épített agentmemory image-re. A tartós tár
+a `/data`-ra csatlakozik; az első indításkor az entrypoint felülírja
+az npm-be csomagolt iii konfigurációt (amely a `127.0.0.1`-hez kötődik) egy
+telepítésre hangolttal, amely a `0.0.0.0`-hoz kötődik, és abszolút `/data` útvonalakat használ,
+legenerálja a HMAC secretet, majd leadja a jogosultságokat `root`-ról `node`-ra a
+`gosu`-n keresztül, mielőtt exec-elné az agentmemory CLI-t.
+
+
+
+
+
+
+A Render egykattintásos telepítés gombja a repó gyökerében lévő `render.yaml`-t igényli, amit szándékosan tisztán tartunk. Használd a [`deploy/render/`](.././deploy/render/README.md)-ben dokumentált Render Blueprint folyamatot, hogy manuálisan a repón belüli blueprintre mutass.
+
+A teljes beállítási részletek (HMAC-rögzítés, megjelenítő SSH-tunnel, forgatás, mentés,
+költségküszöbök) a [`deploy/`](.././deploy/README.md)-ben élnek:
+
+- [`deploy/fly`](.././deploy/fly/README.md): egyetlen gép,
+ `auto_stop_machines = "stop"`-pal; a legolcsóbb üresjárat.
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby-csomag, fix díj,
+ volume a dashboardon.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint-folyamat,
+ automatikus diszk-pillanatképek a fizetős csomagokon.
+- [`deploy/coolify`](.././deploy/coolify/README.md): önálló üzemeltetés a saját
+ VPS-eden, a [Coolify](https://coolify.io/self-hosted) révén; ugyanaz a Docker
+ Compose stack, te birtoklod a hosztot és az adatot.
+
+Csak a `3111`-es port van publikálva. A `3113`-as megjelenítő
+a konténeren belül a loopbackhez marad kötve; minden sablon README-je dokumentálja
+az SSH-tunnel mintát az eléréséhez.
+
+---
+
+
+
+Minden kódolóágens elfelejt mindent, amikor a session véget ér, és minden új session azzal kezdődik, hogy újra elmagyarázod a stacket. Az agentmemory a háttérben fut, és megszünteti ezt a lépést.
+
+```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.
+```
+
+### A beépített ágensmemóriával szemben
+
+Minden AI kódolóágens beépített memóriával érkezik: a Claude Code-nak `MEMORY.md`-je van, a Cursornak notepadjei, a Cline-nak memory bankja. Ezek úgy működnek, mint a ragasztós jegyzetek. Az agentmemory a kereshető adatbázis a ragasztós jegyzetek mögött.
+
+| | Beépített (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Méretezés | 200 soros korlát | Korlátlan |
+| Keresés | Mindent betölt a kontextusba | BM25 + vektor + gráf (csak top-K) |
+| Token-költség | 22K+ 240 megfigyelésnél | ~1,900 token (92%-kal kevesebb) |
+| Ágensek közötti | Ágensenkénti fájlok | MCP + REST (bármely ágens) |
+| Koordináció | Nincs | Lease-ek, szignálok, akciók, rutinok |
+| Megfigyelhetőség | Fájlok manuális olvasása | Valós idejű megjelenítő a :3113-on |
+
+---
+
+
+
+### Memória-pipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4 szintű memória-konszolidáció
+
+Az emberi agy memóriafeldolgozásának a mintájára épül, beleértve az alvás alatti konszolidációt is.
+
+| Szint | Mi | Analógia |
+|------|------|---------|
+| **Working (munka-)** | Nyers megfigyelések a toolhasználatból | Rövidtávú memória |
+| **Episodic (episodikus)** | Tömörített session-összefoglalók | "Mi történt" |
+| **Semantic (szemantikus)** | Kinyert tények és minták | "Mit tudok" |
+| **Procedural (procedurális)** | Munkafolyamatok és döntési minták | "Hogyan kell csinálni" |
+
+A memóriák idővel lecsengenek (Ebbinghaus-görbe). A gyakran elért memóriák megerősödnek. Az elavult memóriák automatikusan kiürülnek. Az ellentmondásokat a rendszer felismeri és feloldja.
+
+### Mi kerül rögzítésre
+
+| Hook | Rögzíti |
+|------|----------|
+| `SessionStart` | Projekt-útvonal, session-ID |
+| `UserPromptSubmit` | Felhasználói promptok (privacy-szűrve) |
+| `PreToolUse` | Fájlhozzáférési minták + bővített kontextus |
+| `PostToolUse` | Tool neve, bemenet, kimenet |
+| `PostToolUseFailure` | Hibakontextus |
+| `PreCompact` | Visszainjektálja a memóriát a compaction előtt |
+| `SubagentStart/Stop` | Sub-agent életciklus |
+| `Stop` | Session-vég összefoglaló |
+| `SessionEnd` | Session-lezárási jelző |
+
+### Kulcsképességek
+
+| Képesség | Leírás |
+|---|---|
+| **Automatikus rögzítés** | Minden toolhasználat hookokon keresztül rögzítve, manuális munka nélkül |
+| **Szemantikus keresés** | BM25 + vektor + tudásgráf RRF-fúzióval |
+| **Memória-evolúció** | Verziózás, felülírás, kapcsolati gráfok |
+| **Felidézési higiénia** | A felülírt memória-verziók elhagyják a keresési indexeket; a KV-ben lévő verziólánc megtartja a teljes előzményt |
+| **Közel-duplikátum jelzések** | A mentések egy tájékoztató `similarTo` egyezést adnak vissza, ha az új tartalom erősen hasonlít egy meglévő memóriára |
+| **Ágensenkénti hatókör** | Az `agentId` végigfut a mentésen és a felidézésen a REST, az MCP és a keresési index között, megosztott vagy izolált módban |
+| **Írási időbeli eredet** | Minden megfigyelés és memória egy megváltoztathatatlan eredetcsatornát hordoz (user, agent, tool, import, vagy shared), amely a rögzítéskor, mentéskor és importáláskor kerül rá |
+| **Automatikus elfelejtés** | TTL-lejárat, ellentmondás-felismerés, fontosság alapú kiürítés |
+| **Elsőbbséget kap az adatvédelem** | API-kulcsok, secretek, `` tagek eltávolítva a tárolás előtt |
+| **Önjavítás** | Circuit breaker, szolgáltató-fallback lánc, egészségfigyelés |
+| **Claude híd** | Kétirányú szinkron a MEMORY.md-vel |
+| **Tudásgráf** | Entitáskinyerés + BFS-bejárás |
+| **Csapatmemória** | Névtér szerint megosztott + privát a csapattagok között |
+| **Hivatkozási eredet** | Bármely memória visszakövethető a forrás-megfigyelésekhez |
+| **Git-pillanatképek** | A memóriaállapot verziózása, visszaállítása és diff-elése |
+
+---
+
+
+
+Hármas folyam-visszakeresés, amely három szignált kombinál:
+
+| Folyam | Mit csinál | Mikor |
+|---|---|---|
+| **BM25** | Tő szerinti kulcsszó-egyezés szinonima-bővítéssel | Mindig aktív |
+| **Vektor** | Koszinusz-hasonlóság sűrű embeddingek felett | Ha van beállítva embedding-szolgáltató |
+| **Gráf** | Tudásgráf-bejárás entitásegyezés révén | Ha a lekérdezésben entitásokat észlel |
+
+Reciprocal Rank Fusionnal (RRF, k=60) fuzionálva, és sessionönkénti diverzifikálva (legfeljebb 3 eredmény sessiononként).
+
+Ha egy vektorindex fel van töltve, a `mem::search` (a `memory_recall` mögött) a hibrid BM25 + vektor rangsorolót használja. Embeddingek nélkül BM25-öt használ. A `smart-search` emellett strukturális gráfegyezéseket is fuzionálhat, ha létezik gráfadat, kulcs nélküli módban is. A tanulság-felidézés egy dedikált, memóriában tartott BM25-indexen fut, nem a teljes korpusz lekérdezésenkénti átnézésével. A felülírt memória-verziók minden felidézési útvonalból ki vannak zárva; a verziólánc megtartja az előzményüket.
+
+A vektorok túlélnek egy összeomlást vagy egy force-killt. A vektorindex legfeljebb minden `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`-ben (10 perc) kerül mentésre, csomagokban. Minden közben hozzáadott vagy eltávolított vektor azonnal felíródik egy kis, függőben lévő naplóba is az állapottárban, és a következő indítás lejátssza ezt az embedding-szolgáltató hívása nélkül. Minden sikeres mentés kiüríti a naplót. Azok a dokumentumok, amelyeknek a lejátszás után sincs vektoruk, a háttérben, `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) méretű batch-ekben kapnak újra embeddinget, amíg nem marad ilyen, és egy leállított backfill a következő indításkor folytatódik. A `/agentmemory/status` és a megjelenítő megmutatja a függőben lévő napló méretét és a backfill állapotát. A kulcs nélküli telepítések semmit nem írnak.
+
+A BM25 alapból tokenizálja a görögöt, a cirillt, a hébert, az arabot és az ékezetes latint. Kínai / japán / koreai memóriákhoz telepítsd az opcionális szegmentálókat (`npm install @node-rs/jieba tiny-segmenter`), hogy szóméretű tokenekre bontsa a CJK-futásokat; nélkülük az agentmemory finoman visszaesik a teljes futás tokenizálására, és egyszeri jelzést ír a stderr-re.
+
+### Embedding-szolgáltatók
+
+A kulcs nélküli telepítések letiltják a vektor-embeddingeket: a `mem::search` BM25-öt használ, míg a `smart-search` emellett a meglévő strukturális gráfadatot is használhatja. Ahhoz, hogy beállj az ingyenes, eszközön futó szemantikus embeddingekre, add hozzá ezt a `~/.agentmemory/.env`-hez, és indítsd újra az agentmemoryt:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+A normál npm-telepítés tartalmazza az opcionális `@huggingface/transformers` futtatókörnyezetet. Az első embedding-kérés letölti a `Xenova/all-MiniLM-L6-v2`-t, így hálózati hozzáférésre van szükség, és tovább tarthat; az azt követő következtetés eszközön fut. A távoli szolgáltatókat a rendszer automatikusan felismeri a kulcsaikból, hacsak az `EMBEDDING_PROVIDER` nem írja felül őket.
+
+| Szolgáltató | Modell | Költség | Megjegyzések |
+|---|---|---|---|
+| **Lokális (ajánlott opt-in)** | `all-MiniLM-L6-v2` | Ingyenes | Eszközön fut az első modell-letöltés után, +8pp felidézés a csak-BM25-höz képest |
+| Gemini | `gemini-embedding-001` | Ingyenes szint | 100+ nyelv, 768/1536/3072 dimenzió (MRL), 2048 tokenes bemenet. Felváltja a `text-embedding-004`-et ([elavult, leállítva 2026. jan. 14-én](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Legjobb minőség |
+| Voyage AI | `voyage-code-3` | Fizetős | Kódra optimalizálva |
+| Cohere | `embed-english-v3.0` | Ingyenes próba | Általános célú |
+| OpenRouter | Bármely modell | Változó | Több modellt lefedő proxy |
+
+---
+
+
+
+54 eszköz, 6 resource, 3 prompt és 17 skill.
+
+> **MCP shim a teljes szerverrel szemben:** a publikált `@agentmemory/mcp` csomag egy vékony shim. A teljes, 54 eszközből álló felületet **csak akkor** adja meg, **ha el tud érni egy futó agentmemory szervert** az `AGENTMEMORY_URL` révén (proxy mód). Ha nincs elérhető szerver, a shim visszaesik egy 7 eszközből álló lokális készletre (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Az `AGENTMEMORY_TOOLS=core|all` env-változó egy *szerveroldali* kapcsoló; a shim `env` blokkjában beállítva nincs hatása. Ha csak 7 eszközt látsz a Cursorban / OpenCode-ban / Gemini CLI-ben, indítsd el az `npx -y @agentmemory/agentmemory@latest`-et (vagy a Docker-stacket), és állítsd be az `AGENTMEMORY_URL=http://localhost:3111`-et.
+
+### 54 eszköz
+
+Három eszközfelület, a legkisebbtől a legnagyobbig: az `AGENTMEMORY_TOOLS=core` 8 alapeszközre szűkíti a láthatóságot (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); az alábbi alapkészlet a regisztri 14 alapozó eszköze; az alapértelmezett (`AGENTMEMORY_TOOLS=all`) mind az 54-et megjeleníti.
+
+
+Alapeszközök (14)
+
+| Eszköz | Leírás |
+|------|-------------|
+| `memory_recall` | Keresés a korábbi megfigyelések között |
+| `memory_compress_file` | Markdown fájlok tömörítése a struktúra megtartásával |
+| `memory_save` | Egy belátás, döntés vagy minta mentése |
+| `memory_file_history` | Korábbi megfigyelések adott fájlokról |
+| `memory_patterns` | Visszatérő minták felismerése |
+| `memory_sessions` | A legutóbbi sessionök listázása |
+| `memory_smart_search` | Hibrid szemantikus + kulcsszavas keresés |
+| `memory_vision_search` | Keresés kép-megfigyelések között |
+| `memory_timeline` | Időrendi megfigyelések |
+| `memory_profile` | Projektprofil (fogalmak, fájlok, minták) |
+| `memory_export` | Az összes memóriaadat exportálása |
+| `memory_relations` | Kapcsolati gráf lekérdezése |
+| `memory_commit_lookup` | Egy git commit mögötti sessionök |
+| `memory_commits` | Egy sessionhöz rögzített commitok |
+
+
+
+
+Kiterjesztett eszközök (összesen 54, az alapértelmezett felület)
+
+| Eszköz | Leírás |
+|------|-------------|
+| `memory_patterns` | Visszatérő minták felismerése |
+| `memory_timeline` | Időrendi megfigyelések |
+| `memory_relations` | Kapcsolati gráf lekérdezése |
+| `memory_graph_query` | Tudásgráf-bejárás |
+| `memory_consolidate` | 4 szintű konszolidáció futtatása |
+| `memory_claude_bridge_sync` | Szinkron a MEMORY.md-vel |
+| `memory_team_share` | Megosztás csapattagokkal |
+| `memory_team_feed` | Legutóbbi megosztott elemek |
+| `memory_audit` | A műveletek audit-nyomvonala |
+| `memory_governance_delete` | Törlés audit-nyomvonallal |
+| `memory_snapshot_create` | Git-verziózott pillanatkép |
+| `memory_action_create` | Munkaelemek létrehozása függőségekkel |
+| `memory_action_update` | Akció-állapot frissítése |
+| `memory_frontier` | Blokkolatlan akciók, prioritás szerint rangsorolva |
+| `memory_next` | A legfontosabb egyetlen következő akció |
+| `memory_lease` | Exkluzív akció-lease-ek (több ágens) |
+| `memory_routine_run` | Munkafolyamat-rutinok instanciálása |
+| `memory_signal_send` | Ágensek közötti üzenetküldés |
+| `memory_signal_read` | Üzenetek olvasása nyugtával |
+| `memory_checkpoint` | Külső feltétel-kapuk |
+| `memory_mesh_sync` | P2P szinkron az instance-ok között |
+| `memory_sentinel_create` | Esemény-vezérelt megfigyelők |
+| `memory_sentinel_trigger` | Sentinel-ek elsütése kívülről |
+| `memory_sketch_create` | Múlékony akció-gráfok |
+| `memory_sketch_promote` | Véglegesítés |
+| `memory_crystallize` | Akcióláncok sűrítése |
+| `memory_diagnose` | Egészségvizsgálatok |
+| `memory_heal` | Elakadt állapot automatikus javítása |
+| `memory_facet_tag` | Dimenzió:érték tagek |
+| `memory_facet_query` | Lekérdezés facet-tagek szerint |
+| `memory_verify` | Eredet visszakövetése |
+
+
+
+### 6 Resource · 3 Prompt · 17 Skill
+
+| Típus | Név | Leírás |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Egészségi állapot, session-szám, memória-szám |
+| Resource | `agentmemory://project/{name}/profile` | Projektenkénti intelligencia |
+| Resource | `agentmemory://project/{name}/recent` | Egy projekt legutóbbi megfigyelései |
+| Resource | `agentmemory://memories/latest` | A legutóbbi 10 aktív memória |
+| Resource | `agentmemory://graph/stats` | Tudásgráf-statisztikák |
+| Resource | `agentmemory://team/{id}/profile` | Megosztott csapatprofil |
+| Prompt | `recall_context` | Keresés + kontextus-üzenetek visszaadása |
+| Prompt | `session_handoff` | Átadási adat ágensek között |
+| Prompt | `detect_patterns` | Visszatérő minták elemzése |
+| Skill | `/recall` | Keresés a memóriában |
+| Skill | `/remember` | Mentés a hosszútávú memóriába |
+| Skill | `/session-history` | Legutóbbi session-összefoglalók |
+| Skill | `/forget` | Megfigyelések/sessionök törlése |
+
+A táblázat a négy alap-skillt mutatja. A teljes készlet 9 meghívható skillből és 8 referencia-skillből áll; lásd a Natív skillek részt fentebb.
+
+### Önálló MCP
+
+Futtasd a teljes szerver nélkül, bármely MCP klienshez. Mindkettő működik:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Vagy add hozzá az ágensed MCP konfigurációjához:
+
+A legtöbb ágens esetén (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Olvasszd be az `agentmemory` bejegyzést a hoszt meglévő `mcpServers` objektumába, ne cseréld le a fájlt. Olyan sandboxolt klienseknél, amelyek nem érik el a hoszt `localhost`-ját, add hozzá a `"AGENTMEMORY_FORCE_PROXY": "1"`-et az env blokkhoz, és állítsd az `AGENTMEMORY_URL`-t egy olyan útvonalra, amit a sandbox el tud érni.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Másold be a plugin-fájlt a repóból:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Automatikusan elindul a `3113`-as porton. A megjelenítő egy pillanatképet tölt be, amikor csatlakozik (`GET /agentmemory/viewer/snapshot`), majd élő stream-eseményeket alkalmaz: új memóriák, tanulságok, megfigyelések, audit-bejegyzések, gráfváltozások és egészségfrissítések jelennek meg polling vagy oldal-újratöltés nélkül. Az egyetlen más kérés az, amire kattintasz: "load more" lapok és keresések. Ha a stream megszakad, a megjelenítő megmutatja, mennyire elavultak a számai, backoff-fal újracsatlakozik, és egy pillanatképből újraszinkronizál.
+
+- **12 fül, négy csoportban**, élő számlálókkal, deep linkekkel (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), billentyűparancsokkal és egy mobilmenüvel.
+- **Memories:** szerveroldali keresés, szűrők projekt, ágens és típus szerint, egy részletpanel a verziólánccal és egy szó-szintű diff-fel, eredetre mutató linkek, másolás gombok az id-hez, az MCP-híváshoz és egy curl parancshoz, szerkesztés (új verzió), elfelejtés megerősítéssel, tömeges elfelejtés és JSON-export.
+- **Sessions:** egy beágyazott megfigyelés-idővonal olvasható tool-bemenettel és -kimenettel, szűrőkkel és lapozással, valamint az adott session által létrehozott memóriák és tanulságok.
+- **Graph:** keresés, csomópont-részletek kapcsolatokkal és forrásokkal, egy jelmagyarázat, amely nem csak színre támaszkodik, és nagyítási vezérlők.
+- **Health:** a `GET /agentmemory/status` élő verziója. Minden probléma a megoldásával érkezik, plusz az állapot-backend, az index-mentési állapot, a gráf-eredet tömörítésének haladása és egy konszolidáció-magyarázó a valódi küszöbértékekkel.
+- **Audit, Activity, Profile, Replay, Lessons, Actions és Crystals** oldalak, mindegyik egy üres állapottal, amely elmondja, mi az adott szekció, miért üres, és melyik parancs tölti fel, valamint egy `?` szójegyzék-tooltippel minden terminuson és számon.
+
+```bash
+open http://localhost:3113
+```
+
+A megjelenítő szervere alapértelmezetten a `127.0.0.1`-hez kötődik, és csatolja a szerver secretjét, amikor továbbküldi a kéréseket a REST API-nak, így nincs szükség beállításra. A REST-en kiszolgált `/agentmemory/viewer` végpont a normál bearer-token szabályokat követi, és a token nélküli böngészőket a megjelenítő portjára irányítja át. A CSP-fejlécek válaszonkénti script-nonce-t használnak, és letiltják az inline handler-attribútumokat (`script-src-attr 'none'`).
+
+---
+
+
+
+A megjelenítő a `:3113`-on azt mutatja, mire **emlékezett** az ágensed. A [iii console](https://iii.dev/docs/console) azt mutatja, mit **csinált** az ágensed: minden memória-műveletet OpenTelemetry trace-ként, minden KV-bejegyzést szerkeszthetően, minden funkciót meghívhatóan, minden stream-et csatlakoztathatóan. Két ablak ugyanarra a memóriára: egy termékalakú, egy engine-alakú.
+
+Figyeld meg, ahogy egy `memory_smart_search` elsül, és nézd meg a BM25-pásztázást → embedding-keresést → RRF-fúziót → rerankert egy vízeséses nézetben. Szerkessz egy elakadt konszolidáció-timert a KV-böngészőben. Játssz vissza egy `PostToolUse` hookot egy módosított payloaddal. Pinneld ki a WebSocket-stream-et, és nézd, ahogy a megfigyelések élőben landolnak.
+
+Az agentmemory ezt ingyen szállítja, mert minden funkcióhívás és trigger az iii-n keresztül sül el; semmi egyéni, semmit nem kell instrumentálni.
+
+
+
+
+ Workers oldal: minden csatlakoztatott worker, az agentmemory-t magát is beleértve, PID-del, funkciószámmal, futtatókörnyezettel és a legutóbbi láthatósággal.
+
+
+**Már telepítve van.** A konzol a pinnelt `iii` engine-nel (0.22+) érkezik; nincs külön mit telepíteni. Az első indítás letölti a konzol binárist az engine mellé.
+
+**Indítsd el az agentmemory mellett:**
+
+```bash
+agentmemory console
+```
+
+Ez a pinnelt engine `iii console`-ját futtatja az agentmemory által feloldott portok ellen (REST, stream-ek, híd), és egy porttal a megjelenítő fölött szolgálja ki, alapértelmezetten a `http://localhost:3114`-en. A `--console-port N` egy másik portot választ; a `--port` és az `--instance` ugyanúgy választja ki az agentmemory-instance-t, mint a `stop`-nál; minden más kapcsoló átadásra kerül, például a `--enable-flow` a kísérleti architektúra-gráf oldalhoz.
+
+Ugyanaz kézzel, hasznos, ha az `agentmemory` nincs a PATH-on:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Mit tehetsz a konzolból:**
+
+| Oldal | Mire használd |
+|------|-----------|
+| **Workers** | Lásd minden csatlakoztatott workert és élő metrikáit, az agentmemory workert is beleértve. |
+| **Functions** | Hívj meg közvetlenül bármelyik agentmemory-funkciót egy JSON-payloaddal; hasznos a `memory.recall`, `memory.consolidate`, `graph.query` teszteléséhez, kliens bekötése nélkül. |
+| **Triggers** | Játssz vissza HTTP-, cron-, event- és state-triggereket: süsd el manuálisan a konszolidáció-cront, próbálj újra egy HTTP-route-ot, bocsáss ki egy állapotváltozást. |
+| **States** | KV-böngésző teljes CRUD-dal a sessionök, memória-slotok, életciklus-timerek és az embedding-index felett; szerkeszd az értékeket a helyükön. |
+| **Streams** | Élő WebSocket-monitor a memória-írásokhoz, hook-eseményekhez és megfigyelés-frissítésekhez, ahogy áthaladnak az iii stream-eken. |
+| **Queues** | Tartós queue-topicok + dead-letter kezelés. Játssz vissza vagy dobj el elbukott embedding- / tömörítési feladatokat. |
+| **Traces** | OpenTelemetry vízesés / flame / szolgáltatás-bontás nézetek. Szűrj `trace_id` szerint, hogy pontosan lásd, mely funkciók, DB-hívások és embedding-kérések adtak ki egy adott `memory.search`-t. |
+| **Logs** | Strukturált OTEL-logok, trace/span ID-khez szűrve és korrelálva. |
+| **Config** | Futásidejű konfiguráció: lásd pontosan, mely workerekkel, szolgáltatókkal és portokkal fut az engine-ed. |
+| **Flow** | (Opcionális, `--enable-flow`) Interaktív architektúra-gráf minden workerről, triggerről és stream-ről. |
+
+
+
+**A trace-ek már be vannak kapcsolva:**
+
+Az `iii-config.yaml` az `iii-observability` workerrel engedélyezve érkezik (`exporter: memory`, `sampling_ratio: 0.1`, metrikák + logok). Nincs szükség extra konfigurációra; abban a pillanatban, hogy az agentmemory elindul, minden memória-művelet egy strukturált logot bocsát ki, amit a konzol tud olvasni, és minden tizedik (`sampling_ratio: 0.1`) emellett egy trace-span-t is kibocsát.
+
+Ha Jaeger/Honeycomb/Grafana Tempo-ba akarsz exportálni helyette, változtasd meg az `exporter: memory`-t `exporter: otlp`-re, és állítsd be a collector-végpontot az iii observability-dokumentációja szerint.
+
+> **Figyelem:** a konzolon magán nincs kikényszerítve hitelesítés; tartsd a `127.0.0.1`-hez kötve (ez az alapértelmezett), és soha ne tedd nyilvánosan elérhetővé.
+
+---
+
+
+
+Az agentmemory **már egy futó [iii](https://iii.dev) instance**. Három primitívből (worker, function, trigger) épül fel a futtatókörnyezet; a KV-állapot, a stream-ek és az OTEL-trace-ek az iii-vel érkező iii-state, iii-stream és iii-observability workerekből jönnek. Nem telepítettél Postgrest, Redist, Expresst, pm2-t vagy Prometheust, mert az iii lecseréli őket.
+
+Ez azt jelenti, hogy egyetlen további paranccsal egy teljesen új képességgel bővítheted az agentmemoryt.
+
+### Bővítsd az agentmemoryt több workerrel
+
+Az agentmemoryhoz szükséges beépített workerek már ott vannak az `iii-config.yaml`-ban, és vele együtt indulnak: `iii-state` (KV), `iii-queue` (tartós újrapróbálkozás az event-feliratkozóknak), `iii-pubsub`, `iii-cron`, `iii-stream`, és `iii-observability` (OTEL-trace-ek, metrikák és logok minden funkcióhoz). Bármi más a [iii worker regiszterből](https://workers.iii.dev) beilleszthető ugyanabba az engine-be: másold az `iii-config.yaml`-t a `~/.agentmemory/iii-config.yaml`-ba (a CLI előnyben részesíti ezt a fájlt a becsomagolttal szemben, és a portokat és adat-útvonalakat is belerendereli), add hozzá a bejegyzést, telepítsd a worker futtatókörnyezetet egyszer a `~/.agentmemory/bin/iii update worker` paranccsal, és indítsd újra az agentmemoryt.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Mit kapsz hozzá az agentmemoryhoz |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-alapú állapot-adapter, ha kinövöd a memóriabeli KV-alapértelmezéseket |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | A `memory_recall`-ból kikerült kód egy eldobható VM-ben fut, nem a shelledben |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Állíts fel extra MCP szervereket az agentmemoryé mellett, osszátok meg ugyanazt az engine-t |
+
+A 0.22.x engine-en tartsd meg az `iii-` prefixes neveket a fenti beépített workerekhez; a prefix nélküli `http`, `state`, `queue`, `pubsub` és `cron` bejegyzések azok az önálló regiszter-workerek, amelyekre az agentmemory a 0.23-as migrációval áttér.
+
+Teljes regiszter: [workers.iii.dev](https://workers.iii.dev). Minden ottani worker ugyanazokon a primitíveken épül fel, amelyeket az agentmemory is használ, és a már meglévő agentmemoryod is egy közülük.
+
+### Engine-konfiguráció és bind-cím
+
+Az `agentmemory start` az engine-konfigurációt az első létező fájlból olvassa: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` a jelenlegi mappában, `~/.agentmemory/iii-config.yaml`, majd a becsomagolt `iii-config.yaml`. Minden indításkor ezt a fájlt (adat-útvonalak, portok, állapot-backend) a `~/.agentmemory/data/iii-config.runtime.yaml`-ba rendereli, és a renderelt másolattal indítja el az engine-t, így a forrásfájlt szerkeszd, ne a renderelt másolatot. A forrásfájl `host:` értékei úgy maradnak, ahogyan írva vannak.
+
+A becsomagolt `iii-config.yaml` szándékosan a `127.0.0.1`-hez kötődik, és ez az alapértelmezés egy konténeren belül is érvényes. Egy konténerben indított CLI a konténer saját loopbackjén figyel, így a publikált portok semmit nem érnek el. Ahhoz, hogy egy konténerizált CLI-t a publikált portokon keresztül szolgálj ki, állítsd az `AGENTMEMORY_III_CONFIG`-ot egy olyan konfigurációra, amely a `0.0.0.0`-hoz kötődik. A csomagolt `iii-config.docker.yaml` egy ilyen: a `iii-http`-t, az `iii-stream`-et és az engine-portot a `0.0.0.0`-hoz köti, és az állapotot a `/data` alatt tárolja, így csatolj ott egy írható volume-ot. Tartsd beállítva az `AGENTMEMORY_SECRET`-et, és csak azokat a portokat publikáld, amelyekre szükséged van, a `127.0.0.1`-en vagy egy megbízható proxy mögött.
+
+Ennek a repónak a `docker-compose.yml`-je nem megy át a CLI konfiguráció-keresésén: a `/app/config.yaml`-ra csatolja az `iii-config.docker.yaml`-t, és az `iii-engine` konténer a `--config /app/config.yaml`-lal indul. Az egykattintásos [telepítési sablonok](../deploy/) a saját `0.0.0.0` konfigurációjukat írják meg az entrypointjaikban.
+
+### Tárolási backend: fájl (alapértelmezett) vs. redis
+
+Az `iii-state` és az `iii-stream` alapértelmezetten az iii-engine beépített, fájl-alapú KV-tárát használja: egy JSON-fájl hatókörönként, az engine-folyamat memóriájában tartva, és egy időzítő szerint visszaírva a diszkre. Ez a helyes alapértelmezés egy egyfelhasználós lokális telepítéshez; egy több egyidejű íróval rendelkező megosztott daemon valódi, kulcsonkénti írásokat kap Redis révén helyette, a művelet-onkénti hálózati fordulat árán (minden `state::*` hívás továbbra is egyetlen Redis-kapcsolaton szerializál, így ez a fájl-tár zárolását egy socketre cseréli, nem párhuzamosságra).
+
+Állítsd be az `AGENTMEMORY_STATE_BACKEND=redis`-t (plusz az `AGENTMEMORY_REDIS_URL`-t), hogy mindkét workert az iii-engine beépített `redis` adapterére váltsd, amely minden kulcsot egy Redis hash-mezőként tárol (`HSET`) egy teljes hatókör minden íráskori felülírása helyett:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+Az `AGENTMEMORY_STATE_BACKEND` alapértelmezetten `file`; ha nem állítod be, a mai viselkedés nem változik, és egy nem felismert érték (bármi, ami nem `file` vagy `redis`) indítási hiba, nem néma visszaesés. A `/agentmemory/status` és a megjelenítő Health oldala (a State store sor) jelzi, melyik backend aktív, és hogy válaszol-e, az URL-t soha.
+
+**Csak sima `redis://`.** A pinnelt engine (0.22.1) TLS-támogatás nélkül építi fel a Redis-kliensét, így egy `rediss://` URL (a legtöbb felügyelt Redis-ajánlat, mint az Upstash, a Redis Cloud és az átvitel közbeni titkosítással rendelkező ElastiCache alapértelmezetten csak TLS-t enged) nem tud csatlakozni. A kapcsolat titkosítás nélküli, így a Redis-jelszó és minden tárolt memória nyílt szövegben megy át a vonalon: egy lokális Redisre, vagy egy olyan privát hálózaton lévő Redisre célozz, amelyben bízol. Bármely más Redishez futtass egy titkosított tunnelt (stunnel, SSH, vagy VPN) az agentmemory-hoszton, így a sima `redis://` szakasz azon a hoszton marad, és a tunnel upstream-kapcsolata titkosított és hitelesített. Ha egy Redis-jelszó egyetlen aposztrófot tartalmaz, percent-encode-old (`%27`); az engine kibontja az URL-t a saját YAML-konfigurációjába, mielőtt feldolgozná.
+
+**Egy Redis-szerver minden `--instance`-hez.** Az engine Redis-kulcs-prefixei (`state:`, `stream::`) fixek, így két, ugyanarra az adatbázisra mutató agentmemory-instance (`--instance 1`, `--instance 2`, ...) felülírja egymás adatait. Egy külön adatbázis-index (`redis://localhost:6379/1`) külön tartja a tárolt adatot, de az engine egyetlen Redis pub/sub csatornán (`stream::events`) továbbítja az élő megjelenítő-eseményeket, és a Redis pub/sub nem veszi figyelembe az adatbázis-indexet, így minden instance megjelenítője továbbra is a másik élő eseményeit mutatná. Adj minden instance-nek saját Redis-szervert (vagy portot), ha egynél többet futtatsz.
+
+**Mi marad ugyanaz, és mi különbözik.** Minden agentmemory-funkció működik Redisen: sessionök, megfigyelések, memóriák (remember, supersede, evolve, forget), keresés és az index-csomagok, tanulságok, a gráf, az audit-log és annak havi hatókörei, export és import, governance-törlések, konszolidáció-státusz, a megjelenítő pillanatképe és élő stream-je, és az egészségfigyelő. Az engine minden hatókört egyetlen Redis hash-ként tárol (`HSET`/`HGET`/`HGETALL`), és ugyanazokat az állapot-triggereket süti el, mint a fájl-tár. Három engine-különbséget az agentmemory oldja meg belsőleg:
+
+- A Redis fix sorrend nélkül adja vissza egy hatókör rekordjait. Az agentmemory a legrégebbitől rendezi őket (a rekord id-jében lévő létrehozási idő, majd az időbélyeg szerint), hogy a listák, a lapozás és az export-chunk-ok ugyanabban a sorrendben jöjjenek, mint a fájl-táron.
+- Az engine egy Lua-szkriptben alkalmazza a részleges frissítéseket Redisen, amely az üres tömböket üres objektumokká alakítja. Az agentmemory saját maga alkalmazza ezeket a frissítéseket (olvasás, módosítás, írás egy kulcsonkénti zár alatt) Redisen, hogy a `tags: []`-hez hasonló mezők tömbök maradjanak.
+- Az örökölt audit-log-ellenőrzés a régi hatókört Redisből olvassa, nem a fájl-tár fájlját keresi a diszken.
+
+Egy különbség rád vár: **a Redis újraindítása után az engine leállítja az élő események továbbítását** a megjelenítőhöz, amíg az agentmemory nem indul újra. Az adat normálisan mentve és olvasva marad. Az egészségfigyelő 30 másodpercenként küld egy teszt-eseményt a Rediszen keresztül; ha nem jön vissza, a `/agentmemory/status` és a megjelenítő Health oldala azt mutatja: "Az élő frissítések nem érik el a megjelenítőt", a megoldással: indítsd újra az agentmemoryt. Ha a Redis nem fut, az állapotjelentés azt mutatja: "Az állapottár nem válaszol", és hogyan ellenőrizd (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Egy nagyon nagy hatókör listázása egyetlen `HGETALL`-ban olvassa az egész hash-t, ugyanolyan költséggel, mint amikor a fájl-tár memóriában tartja.
+
+**Ajánlott Redis-beállítások.** Az alapértelmezett `save 3600 1 300 100 60 10000` pillanatkép-politika percekig tartó írásveszteséget szenvedhet egy összeomláskor, rosszabbul, mint a fájl-tár 5 másodperces flush-ablaka. Állítsd be az `appendonly yes`-t mindenhez, amit nem szeretnél elveszíteni. Állítsd be a `maxmemory-policy noeviction`-t; az `allkeys-lru` vagy hasonló némán elkezd memóriákat elejteni, amint a Redis eléri a memóriakorlátját.
+
+Egy natív (nem Docker) indítás, és minden egykattintásos [telepítési sablon](../deploy/) (ezek felülírják a becsomagolt `iii-config.yaml`-t, és natívan indulnak) olvassa az `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL`-t, és belerendereli az elindított `iii-config`-ba. Az URL maga soha nem íródik bele abba a renderelt fájlba, csak egy `${AGENTMEMORY_REDIS_URL}` hivatkozás, amelyet az engine-folyamat a saját környezetéből bont ki indításkor. Csak ennek a repónak a saját Docker Compose útvonala (`AGENTMEMORY_USE_DOCKER=1`, vagy egy már így elindított engine folytatása) csatolja az `iii-config.docker.yaml`-t írásvédetten, és soha nem renderel; az `agentmemory start` figyelmeztet, amikor ezt a kombinációt észleli. Cseréld ki azt a fájlt kézzel, követve ugyanazt a `name: redis` / `config: redis_url: ...` formátumot, amelyet az [iii-state](https://workers.iii.dev/workers/iii-state) és az [iii-stream](https://workers.iii.dev/workers/iii-stream) worker-dokumentáció mutat, és irányítsd a `redis_url`-t egy a konténerből elérhető Redisre. A `docker-compose.yml` átadja az `AGENTMEMORY_REDIS_URL`-t az engine-konténernek, így a `redis_url: '${AGENTMEMORY_REDIS_URL}'` ott működik, és kint tartja az URL-t a csatolt fájlból.
+
+A renderelt konfiguráció kint tartja az URL-t a `~/.agentmemory/data/iii-config.runtime.yaml`-ból, de az engine saját konfiguráció-workere a *kibontott* értéket mégis elmenti a `~/.agentmemory/config/iii-state.yaml`-ba és az `iii-stream.yaml`-ba, amint elindul (az iii-engine `${VAR}`-kibontása azelőtt történik, hogy ez a worker elmentené a saját seedjét, és a feloldott értéket tárolja, nem a hivatkozást). Kezeld azt a mappát úgy, mintha egy hitelesítő adatot tartalmazna: `chmod 700 ~/.agentmemory` bármely megosztott hoszton, és részesítsd előnyben egy, az agentmemory szükségleteire korlátozott Redis ACL-felhasználót az adatbázis admin hitelesítő adataival szemben.
+
+**A migráció nem automatikus.** Az `AGENTMEMORY_STATE_BACKEND` váltása mindkét oldalon üres tárból indul; semmi nem másolja át a meglévő adatot fájlból Redisbe vagy vissza. Exportálj abból a backendből, amelyet elhagysz, és importálj abba, amelybe átmész. Ez azonosan fut bash és zsh alatt (a `bash -u`-t is beleértve). Egy olyan tömb, mint az `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})`, nem: a zsh egy rosszul formázott szóként tartja a headert, ahol a bash kettőre bontja, így mindkét kérés 401-et kap, amikor az `AGENTMEMORY_SECRET` beállított:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+A `/agentmemory/export` emellett elfogadja a `?maxSessions=`-t és a `?offset=`-et egy nagy korpusz több hívásra bontásához; a `strategy` importnál `merge` (alapértelmezett, biztonságos), `replace`, vagy `skip`.
+
+### Mit helyettesít az iii
+
+| Hagyományos stack | Az agentmemory ezt használja |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggerek |
+| SQLite / Postgres + pgvector | iii KV State + memóriabeli vektorindex |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker-felügyelet |
+| Prometheus / Grafana | iii OTEL + egészségfigyelő |
+| Egyéni plugin-rendszerek | `iii worker add ` |
+
+**225 forrásfájl · ~54,000 LOC · 2,600+ teszt · 312 funkció · 66 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
+
+---
+
+
+
+### LLM-szolgáltatók
+
+Az agentmemory automatikusan felismeri a szolgáltatókat a környezetedből. Egy szolgáltató elérhetővé teszi az LLM-alapú műveleteket, de a szolgáltató-konfiguráció önmagában nem engedélyezi az LLM által írt megfigyelés-tömörítést. Ahhoz mindkettő szükséges: egy szolgáltató és az `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Szolgáltató | Konfiguráció | Megjegyzések |
+|----------|--------|-------|
+| **No-op (alapértelmezett)** | Nincs szükség konfigurációra | Az LLM-alapú tömörítés/összefoglalás letiltva. A szintetikus tömörítés és a BM25-felidézés továbbra is működik. Lásd az `AGENTMEMORY_ALLOW_AGENT_SDK`-t alább, ha korábban a Claude-előfizetéses fallbackre támaszkodtál. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Token-alapú díjszabás |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibilis |
+| Gemini | `GEMINI_API_KEY` | Az embeddingeket is engedélyezi |
+| OpenRouter | `OPENROUTER_API_KEY` | Bármely modell |
+| OpenAI API | `OPENAI_API_KEY` | Alapértelmezett `gpt-5.6-luna`, felülírható az `OPENAI_MODEL`-lel |
+| **Lokális (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) vagy `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Bármi, ami OpenAI-API-kompatibilis. Nulla költség, a saját hardvereden fut. Lásd a [Lokális modellek](#local-models-ollama--lm-studio--vllm) részt alább. |
+| Claude-előfizetéses fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Csak opt-in. A `@anthropic-ai/claude-agent-sdk` sessionöket indít; korábban korlátlan Stop-hook-rekurziót okozott, így nem alapértelmezett többé. |
+
+### Lokális modellek (Ollama / LM Studio / vLLM)
+
+Az agentmemory bármely OpenAI-API-kompatibilis szerverrel beszél, így bármi, ami kiteszi a `/v1/chat/completions`-t, kódmódosítás nélkül működik. Nincs fizetős kulcs, nincs felhő, nincs rate limit; teljesen a saját hardveredben fut.
+
+**Ollama** (alapértelmezett port `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (alapértelmezett port `1234`):
+
+Nyisd meg az LM Studio-t → Local Server fül → Start Server. Válassz bármilyen chat-modellt a választóból (Qwen 3, gpt-oss, DeepSeek R1, stb.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: ugyanaz a forma. Irányítsd az `OPENAI_BASE_URL`-t arra az URL-re, amit a szervered kitesz, és állítsd be az `OPENAI_MODEL`-t egy olyan névre, amit a szervered elfogad.
+
+**Modellajánlások memóriamunkára**: a tömörítés és az összefoglalás rövid feladatok (<2K token be, <500 token ki), ahol egy 7B instruct-modell is bőven elég. Ajánlások:
+
+| Modell | Méret | Miért |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Kiegyensúlyozott alapértelmezés egy 16 GB-os gépen; erős a kinyerésben és a tool-alakú szövegben |
+| `qwen3:4b` | ~2.6 GB | A legkisebb épkézláb opció; megfelelő tömörítéshez, gyengébb gráfkinyeréshez |
+| `qwen3-coder:30b` | ~19 GB | A legjobb lokális választás kód-alakú sessionökhöz (30B MoE, 3.3B aktív) 24-32 GB hardveren |
+| `gpt-oss:20b` | ~14 GB | Erős általános modell, amely elfér 16 GB RAM-ban |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning-disztill; lassabb, de tisztább kinyerések |
+
+A Qwen 3 modellek alapértelmezetten gondolkodnak, és képesek az egész token-budgetet elégetni a reasoning-en, mielőtt bármi kimenet lenne. Állítsd be az `AGENTMEMORY_LLM_NOTHINK=1`-et, hogy `/no_think`-et fűzzön a gráfkinyerési promptokhoz, és emeld fel a `MAX_TOKENS`-t (16384 működik), ha a kinyerések üresen jönnek vissza.
+
+A reasoning-osztályú modellek (`o1`-stílusú, `` blokkokkal) üres `content`-et adhatnak vissza egy `reasoning` mezővel, amit a lokális szervered esetleg nem tesz ki. Ha a kinyerések üresen jönnek vissza, váltsd előbb egy nem-reasoning modellre. Az `OPENAI_REASONING_EFFORT=none` env is kikapcsolhatja a gondolkodást az Ollama Cloud olyan thinking-modelljein, amelyek az OpenAI reasoning-sémáját tükrözik.
+
+A lokális embeddingek opcionális függőségként érkeznek, de nem alapértelmezetten engedélyezettek. Állítsd be az `EMBEDDING_PROVIDER=local`-t, hogy beállj a `Xenova/all-MiniLM-L6-v2`-re (384 dimenzió). Az első embedding-kérés letölti a modellt; a következtetés azután eszközön fut. Ennek a beállításnak vagy egy távoli embedding-kulcsnak a híján a vektorok letiltva maradnak, a `mem::search` BM25-öt használ, és a `smart-search` még hozzáadhat meglévő gráf-egyezéseket.
+
+### Költségtudatos modellválasztás
+
+Amikor az LLM által írt háttér-tömörítés engedélyezve van, mind egy szolgáltatóval, mind az `AGENTMEMORY_AUTO_COMPRESS=true`-val, akkor minden megfigyelésnél lefut, így a modellválasztás érdemben megváltoztatja a havi kiadást. Rögzített terhelési adat: 635 kérés / 888K token / 35 óra aktív használat, három OpenRouter-modellen futtatva, 2026-05-23-i árazással.
+
+| Szint | Modell | Input / 1M | Output / 1M | Költség a rögzített 35 órára | Megjegyzések |
+|------|-------|------------|-------------|---------------------------|-------|
+| Ajánlott | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (becs.) | A legújabb DeepSeek; a legolcsóbb ajánlott választás tömörítési terhelésekhez. |
+| Ajánlott | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Szilárd tömörítési + összefoglalási minőség, ~10×-szer alacsonyabb költséggel, mint a Sonnet. |
+| Ajánlott | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Erős kódreasoning, ha a sessionjeid erősen kód-alakúak. |
+| Prémium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (becs.) | Ugyanaz a listaár, mint a mért Sonnet 4.6 futás; $2/$10 bevezető árazás 2026-08-31-ig. |
+| Prémium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (becs.) | Zászlóshajó szint; költséges az állandóan futó háttérmunkára. |
+| Kerülendő | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (becs.) | Zászlóshajó-osztályú modell; túlköltekezés tömörítésre. |
+
+A mért sorok a rögzített futásból származnak; a (becs.) sorok ugyanazt a token-mixet skálázzák az adott modell listaára szerint.
+
+Az agentmemory futásidejű figyelmeztetést ír ki, amikor az `OPENROUTER_MODEL` egy prémium-szintű mintára illik. Állítsd be az `AGENTMEMORY_SUPPRESS_COST_WARNING=1`-et, hogy elnémítsd, ha már megtetted a tájékozott választást.
+
+Minőség vs. költség kompromisszum memóriamunkához: a tömörítés egy összefoglalási feladat, viszonylag laza minőségi küszöbökkel (az ágens olvassa vissza az összefoglalót, nem a felhasználó). A DeepSeek V4 Flash / V4 Pro / Qwen3-Coder a Sonnethez mérten kerekítési hibahatáron belül landol ennél a feladatnál, miközben 10-70×-szer kevesebbet kerül. Tartsd meg a prémium-szintű modelleket azokra a lekérdezésekre, amiket közvetlenül olvasol.
+
+Források: [OpenRouter árazás a Claude Sonnet 5-höz](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek árazási megjegyzések](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Több ágenses memória (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Több ágenses beállításokban, ahol több szerep osztja meg egy agentmemory szervert (architect / developer / reviewer / researcher / support-agent), az `AGENT_ID` minden írást megjelöl azzal a szereppel, amelyik végezte. Az `AGENTMEMORY_AGENT_SCOPE` szabályozza, hogy a felidézés szűr-e ez a tag szerint.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Két mód:
+
+| Mód | Írások megjelölése | Felidézés szűrése | Mikor használd |
+|------|------------|---------------|-------------|
+| `shared` (alapértelmezett) | igen | nem | Ágensek közötti kontextus audit-nyomvonallal. Az architect láthatja, mit jegyzett fel a developer, de minden sor rögzíti, ki mondta. |
+| `isolated` | igen | igen | Szigorú szétválasztás. Az architect soha nem látja a developer megfigyeléseit / memóriáit / sessionjeit. |
+
+Mi kerül megjelölésre, ha az `AGENT_ID` beállított: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. A szerep az `api::session::start` → `mem::observe` → `mem::compress` → KV útvonalon áramlik.
+
+Mi kerül kiszűrésre isolated módban: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Minden végpont elfogadja a `?agentId=`-t kérésenkénti felülírásra, és a `?agentId=*`-ot, hogy teljesen kilépj az env-hatókörből. A `/memories` emellett elfogadja a `?includeOrphans=true`-t is, hogy felszínre hozza azokat az AGENT_ID előtti memóriákat, amelyeknek az `agentId`-ja nincs definiálva.
+
+Hívásonkénti felülírás az SDK / REST rétegben: minden mutáló végpont (`/session/start`, `/remember`) elfogad egy `agentId` mezőt a kéréstörzsben, amely felülírja az env-et. Hasznos azoknál a futtatókörnyezeteknél, amelyek sok szerepet egyetlen szerverfolyamaton keresztül vezetnek. Az MCP `memory_save` eszköze ugyanazt az `agentId` mezőt teszi ki, az önálló stdio-szerver mind az `agentId`-t, mind a `project`-et továbbítja, és a mentett memóriák az `agentId`-t is bevezetik a keresési indexbe, így az ágens-hatókörű keresés a megfigyelések mellett a memóriákra is kiterjed.
+
+Amikor az `AGENT_ID` nincs beállítva, a memória hatókör nélkül marad (örökölt viselkedés, nincs tag, nincs szűrés).
+
+### Portok
+
+Az agentmemory + iii-engine alapértelmezetten négy portot köt le. Ha egy újraindítás `port in use`-szal bukik el, ez a táblázat megmondja, melyik folyamatot keresd.
+
+| Port | Folyamat | Cél | Env felülírás |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Belső stream-worker (az agentmemory + a megjelenítő fogyasztja) | `III_STREAM_PORT` (előnyben részesítve) vagy az örökölt `III_STREAMS_PORT` |
+| `3113` | agentmemory | Valós idejű megjelenítő (`http://localhost:3113`) | `III_VIEWER_PORT` vagy `AGENTMEMORY_VIEWER_URL` a jelentett URL-hez |
+| `49134` | iii-engine | WebSocket; itt regisztrálnak a workerek, és itt áramlik az OTel-telemetria | `III_ENGINE_PORT` vagy `III_ENGINE_URL` |
+
+A `--port ` megváltoztatja a REST-horgonyt, és levezeti a stream-eket (`N+1`), a megjelenítőt (`N+2`) és az engine WebSocketet (`N+46023`), de csak ott, ahol a fenti megfelelő explicit port vagy URL nincs beállítva. Nem hoz létre izolált életciklus-névteret. Használd a `--instance 1`-et egy második daemonhoz; ez a 3211 horgonyt használja, alapértelmezetten `3211/3212/3213/49234`, és egy külön `instance-1` adat- és életciklus-mappát kap. Az 1-től 50-ig terjedő instance-ok ugyanezt a mintát követik.
+
+A pinnelt engine `--no-update-check`-kel indul (nincs frissítés- vagy biztonsági-tanács-lekérdezés a GitHub ellen indításkor), és az iii anonim használati telemetriája kikapcsolva: az agentmemory beállítja az `III_TELEMETRY_ENABLED=false`-t az általa indított engine-hez, hacsak nem exportálod magad a változót, és a becsomagolt compose-fájl ugyanezt teszi.
+
+Elavult folyamatok takarítása, ha a portok lekötve maradnak egy összeomlott futás után:
+
+```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
+```
+
+Az `agentmemory stop` tisztán learatja a workert és az engine pidfile-t egy sikeres natív leállításnál. Docker-módban kiírja a natív workert, leállítja a pontosan validált engine-konténert, és megőrzi mind a konténert, mind a `/data` csatolását egy veszteség nélküli újraindításhoz; a következő indítás validálja és folytatja ugyanazt a konténert. A Docker-alapú eltávolítás az `agentmemory remove --keep-data`-t igényli: eltávolítja a megosztott, agentmemory-kezelt fájlokat, de megőrzi a validált konténert, az adat-csatolását és a visszaállításukhoz szükséges életciklus-rekordot. A destruktív Docker-adattörlés szándékosan az üzemeltetőre van hagyva, egy mentés után. A CLI emellett visszautasítja, hogy natív engine-ként örökbe fogadjon vagy jelezzen Docker- vagy VM-port-tulajdonosokat (Docker backend, vpnkit, colima), hacsak nincs átadva a `--force`. A fenti manuális takarítás csak az összeomlás utáni esetre vonatkozik, amikor semelyik pidfile sem maradt meg.
+
+### Konfigurációs fájl
+
+Az agentmemory futásidejű konfigurációját tedd a `~/.agentmemory/.env`-be, ne exportálj változókat minden shellben. Ha a megjelenítő egy olyan beállítási tippet mutat, mint az `export ANTHROPIC_API_KEY=...`, másold be ebbe a fájlba `ANTHROPIC_API_KEY=...`-ként, az `export` prefix nélkül, majd indítsd újra az agentmemoryt.
+
+A folyamat-szintű környezeti változók továbbra is működnek, és elsőbbséget kapnak a fájlban lévő értékekkel szemben.
+
+Windowson ugyanez a fájl a `%USERPROFILE%\.agentmemory\.env`-ben él:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Ahhoz, hogy egy Claude Code Pro/Max előfizetéssel tesztelj API-kulcs helyett, iratkozz fel rá explicit módon:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Az LLM által írt megfigyelés-tömörítéshez mindkét sor szükséges: hozzáférés egy LLM-szolgáltatóhoz (ezt az explicit előfizetéses fallbacket is beleértve) és az `AGENTMEMORY_AUTO_COMPRESS=true`. Egy szolgáltató önmagában az alapértelmezett szintetikus tömörítési útvonalat hagyja érvényben.
+
+A konszolidáció (gráf-csomópontok, tanulságok, kristályok) alapértelmezetten be van kapcsolva, amikor egy LLM-szolgáltató konfigurálva van. Explicit módon kapcsold ki a `CONSOLIDATION_ENABLED=false`-szal, ha LLM-mentes működést akarsz. A gráfkinyerés egy külön kapcsoló:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Környezeti változók
+
+Hozd létre a `~/.agentmemory/.env`-et:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoint a `3111`-es porton. A REST API alapértelmezetten a `127.0.0.1`-hez kötődik. A védett végpontok `Authorization: Bearer `-et igényelnek, és a mesh-sync végpontok mindkét oldalon explicit módon beállított `AGENTMEMORY_SECRET`-et igényelnek.
+
+**A hitelesítés alapértelmezetten be van kapcsolva.** Amikor az `AGENTMEMORY_SECRET` nincs beállítva (sem a shellben, sem a `~/.agentmemory/.env`-ben), a szerver az első indításkor egy véletlen secretet generál, és `0600` móddal tárolja a `~/.agentmemory/secret`-ben. Minden becsomagolt kliens onnan olvassa, amikor egy lokális szerverrel beszél: a CLI, a megjelenítő, a `plugin/scripts` alatti hookok, az MCP szerver és a `@agentmemory/mcp` shim, az `agentmemory connect` által írt konfigurációk, és a becsomagolt OpenCode, Pi, OpenClaw, Hermes és fájlrendszer-figyelő integrációk. A tárolt secret csak loopback URL-eknek kerül elküldésre (`localhost`, `127.0.0.0/8`, `::1`). Egy explicit `AGENTMEMORY_SECRET` mindig elsőbbséget kap, és a távoli klienseknek továbbra is be kell állítaniuk. A Docker és a `deploy/` entrypointok már generálnak és exportálnak egy saját secretet. Az API kézi hívásához:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Szabályok az írási kérésekhez.** A `POST`, `PUT`, `PATCH` és `DELETE` kéréseknek a REST API-hoz és a megjelenítőhöz `Content-Type: application/json`-t kell küldeniük (egy `charset` paraméter rendben van), amikor törzset hordoznak, és egy `Origin` fejlécnek, ha jelen van, egy loopback origin-nek kell lennie a konfigurált REST- vagy megjelenítő-porthoz, vagy felsorolva kell lennie a `VIEWER_ALLOWED_ORIGINS`-ban (vesszővel elválasztva, pl. `https://memory.example.com`). Azok a kliensek, amelyek nem küldenek `Origin` fejlécet (CLI, hookok, MCP, curl, szerver-szerver), nem érintettek. A megjelenítő a saját origin-ját is elfogadja.
+
+**Fájlútvonalak.** Azok a végpontok, amelyek fájlokat olvasnak vagy írnak (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), csak a `~/.agentmemory` alatti, az instance adatmappájában lévő, vagy az `AGENTMEMORY_IMPORT_ROOT`-ban felsorolt mappa alatti útvonalakat fogadják el (több mappát `:`-tal válassz el, Windowson `;`-vel). A `/replay/import-jsonl` elfogadja az alapértelmezett `~/.claude/projects`-et is. Az `/obsidian/export` az `AGENTMEMORY_EXPORT_ROOT`-on belül marad, a `/migrate` a `~/.agentmemory`-n belül. A symlinkek minden ellenőrzés előtt feloldásra kerülnek.
+
+**Secret-tisztítás.** API-kulcsok, bearer-tokenek, PEM privát kulcs-blokkok és URL-ekbe ágyazott hitelesítő adatok (`scheme://user:password@host`) minden írási útvonalon elfedésre kerülnek, mielőtt a szöveg tárolásra kerülne: megfigyelések, remember, evolve, slotok, tanulságok, akciók, sketchek, szignálok, checkpointok, importok, jsonl-replay, mesh-sync, csapat-megosztások, tömörítési és összefoglaló kimenet, kristályok és gráf-csomópontok.
+
+
+Kulcs végpontok
+
+| Metódus | Útvonal | Leírás |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Egészségjelzés (mindig nyilvános) |
+| `GET` | `/agentmemory/status` | Mi a hiba, és hogyan javítsd (HTML böngészőkhöz, egyébként JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Minden, amit a megjelenítő mutat, egyetlen válaszban |
+| `POST` | `/agentmemory/session/start` | Session indítása + kontextus lekérése |
+| `POST` | `/agentmemory/session/end` | Session lezárása |
+| `POST` | `/agentmemory/observe` | Megfigyelés rögzítése (lásd a rögzítés-kiszolgálást alább) |
+| `GET` | `/agentmemory/capture` | A rögzítési inbox, a dead letterek és az offline spool |
+| `POST` | `/agentmemory/capture/retry` | Dead-letter rögzítések újrapróbálása |
+| `POST` | `/agentmemory/capture/drain` | A lokális offline spool elküldése most |
+| `POST` | `/agentmemory/smart-search` | Hibrid keresés |
+| `POST` | `/agentmemory/context` | Kontextus generálása |
+| `POST` | `/agentmemory/remember` | Mentés a hosszútávú memóriába |
+| `POST` | `/agentmemory/forget` | Megfigyelések törlése |
+| `POST` | `/agentmemory/enrich` | Fájlkontextus + memóriák + hibák |
+| `GET` | `/agentmemory/profile` | Projektprofil |
+| `GET` | `/agentmemory/export` | Minden adat exportálása |
+| `POST` | `/agentmemory/import` | Import JSON-ból |
+| `POST` | `/agentmemory/graph/query` | Tudásgráf-lekérdezés |
+| `POST` | `/agentmemory/graph/compact` | Túlméretezett gráf-eredet ritkítása |
+| `POST` | `/agentmemory/team/share` | Megosztás csapattal |
+| `GET` | `/agentmemory/audit` | Audit-nyomvonal |
+
+Teljes végpontlista: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Rögzítés-kiszolgálás.** A hookok minden megfigyelést egyszer küldenek el a `POST /agentmemory/observe`-nak, egy `eventId`-vel. Ez a hoszt saját id-je a híváshoz, ha a payloadnak van ilyene (például a Claude Code `tool_use_id`-je), egyébként a session, a hook-típus, a tool neve, a bemenet, a kimenet és a hoszt időbélyegének hash-e. A szerver beírja az eseményt egy rögzítési inboxba az állapottárban, elmenti a megfigyelést, majd eltávolítja az inbox-bejegyzést. A státuszkód megmondja, mi történt:
+
+| Státusz | `status` mező | Jelentés |
+|---|---|---|
+| `201` | `accepted` | Elmentve. Az `observationId` az új megfigyelés. |
+| `202` | `accepted` (`state: "retrying"`) | Elfogadva, de a mentés elbukott. A szerver újrapróbálja, akár egy újraindítás után is. |
+| `200` | `duplicate` | Ezt az `eventId`-t már elfogadta a rendszer. Az `observationId` a meglévő megfigyelés; semmi új nem kerül tárolásra. |
+| `400` / `422` | `rejected` | Érvénytelen payload, vagy a mentés véglegesen elbukott (az esemény dead letterként marad meg). |
+| `503` | `rejected` (`retryable: true`) | Az inbox betelt (`AGENTMEMORY_CAPTURE_INBOX_MAX`). A hookok spoolozzák az eseményt, és később küldik el. |
+
+Az elbukott eseményeket a rendszer minden `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`-ben (10 s) újrapróbálja, duplázódó backoff-fal, legfeljebb `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`-ig (5). Azok az események, amelyek továbbra sem sikerülnek, dead letterként maradnak az inboxban, felsorolva a `/agentmemory/status`-on és a megjelenítő Health oldalán, és újrapróbálhatók a `POST /agentmemory/capture/retry`-vel (`{"eventId": "..."}` vagy `{"all": true}`). Az elfogadott esemény-id-ket a rendszer `AGENTMEMORY_CAPTURE_DEDUP_HOURS`-ig (168 óra, legfeljebb `AGENTMEMORY_CAPTURE_EVENTS_MAX` id) megjegyzi, így egy, egy timeout vagy újraindítás után visszajátszott hookot egyszer tárol, míg két külön toolhívás a saját hoszt-id-jével kétszer kerül tárolásra, akkor is, ha a tartalmuk azonos. Amikor egy megfigyelés törlésre kerül (forget, session-törlés, kiürítés, automatikus elfelejtés, vagy egy import, amely lecseréli a tárat), az eseménye töröltként kerül megjelölésre, mielőtt a megfigyelés eltávolításra kerül, így az adott esemény egy ugyanazon ablakon belüli visszajátszása duplikátumként kerül megválaszolásra, és semmit nem tárol. Az állapottár 2 másodpercenként ír a diszkre, így egy megválaszolt esemény egy pillanatra még csak a memóriában lehet. Hogy ezt lefedje, minden `2xx` válasz hordozza a szerver `bootId`-ját is (minden indításnál új), az `acceptedAt`-ot és a `durableAfterMs`-t (a mentési intervallum plusz 1.5 s a fájl-tárnál, 1.5 s redisen, ahol a perzisztencia az üzemeltető beállítása). A hookok a helyi spoolban tartják az eseményt, amíg ez az ablak nem telik le, és egy későbbi híváskor törlik, egy újabb kérés nélkül. Ha a `bootId` addigra megváltozott, a szerver újraindult, így a hook ismét elküldi az eseményt ugyanazzal az `eventId`-vel; egy olyan esemény, amely valóban elérte a diszket, nem kerül kétszer tárolásra. A szerver maga is elküldi az ilyen eseményeket indításkor és minden újrapróbálkozási intervallumnál, így egy újraindítás sem veszít el semmit, akkor sem, ha utána nem fut hook. A régebbi hookok ignorálják az extra mezőket, és az új hookok egy régebbi szerver ellen ugyanúgy elvetik az eseményt `2xx`-nél, mint korábban.
+
+Amikor a szerver nem fut, nem válaszol időben, vagy 5xx-et ad vissza, a hook hozzáfűzi a megfigyelést egy lokális spool-fájlhoz, `/capture-spool/-.jsonl` (a mappa felülírható az `AGENTMEMORY_CAPTURE_SPOOL_DIR`-ral). A fájl csak a saját felhasználód számára elérhető (mód 600), a secreteket a rendszer ugyanúgy elfedi, ahogy a szerver teszi, legfeljebb `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`-ot (5 MiB) tárol, és eldobja az `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`-nál (168) régebbi bejegyzéseket. Amikor betelik, az új bejegyzések elvetésre és megszámlálásra kerülnek, és a `/agentmemory/status` jelenti. A hook továbbra is 0-val lép ki az időkorlátján belül, és nem ad hozzá kérést, amikor a szerver egészséges. A spool a következő indításkor, és az első olyan hooknál kerül elküldésre, amely ismét eléri a szervert, egy háttérfolyamatban, hogy az ágens ne várjon. Az esemény-id-k ezt biztonságossá teszik: egy megfigyelés, amely már megérkezett egy timeout előtt, nem kerül kétszer tárolásra. Az `npx @agentmemory/agentmemory capture` megmutatja a spoolt és a szerver inboxát, a `--drain` elküldi a spoolt most, és a `GET /agentmemory/capture` ugyanezt adja vissza JSON-ként. Állítsd be az `AGENTMEMORY_CAPTURE_SPOOL=false`-t, hogy kikapcsold a spoolt.
+
+**A gráf-eredet tömörítése.** Minden tudásgráf-csomópont és -él megtartja a legújabb 32 megfigyelés id-jét, amelyekből származott. Az ennél a korlátnál korábban írt tárak csomópontonként akár több ezer id-t is tarthatnak egy forró csomóponton, ami lelassítja a gráfkeresést és a megjelenítőt, vagy elakasztja a workert. Az agentmemory ezt saját maga javítja: a frissítés utáni első indításkor a háttérben ritkít minden csomópontot, élt, felülírt élt (a temporális gráf-előzmény) és a gyorsítótárazott pillanatképet a korlátra, kis szeletekben, köztük szünettel, hogy a keresés, a rögzítés és a megjelenítő tovább működjön. Elmenti a haladását, folytatja egy újraindítás után, és soha nem fut újra, ha egyszer végzett. A `/agentmemory/status` és a megjelenítő Health oldala függőben lévőként, futóként (az aktuális hatókörrel és pozícióval), befejezettként vagy sikertelenként mutatja. Állítsd az `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`-ra, hogy kikapcsold.
+
+Hogy kézzel futtasd, hívd meg a `POST /agentmemory/graph/compact`-ot. A név- és él-kulcs-indexeken sétál végig, nem listáz minden csomópontot és élt, és biztonságosan újrafuttatható. Amikor id-ket ritkít, egy `graph_compact` audit-bejegyzést ír.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Egy nagy táron, vagy amikor a hívás 504-et ad vissza, futtasd szeletekben. Küldd el a `scope`-ot (`nodes`, `edges` vagy `history`), az `offset`-et és a `limit`-et, majd hívd újra a visszaadott `nextOffset`-tel, amíg az `null` nem lesz. Tedd ezt a `nodes`, az `edges` és a `history` esetén, és fejezd be egy `{"scope":"snapshot"}` hívással, mert egy szeletelt futás nem érinti a gyorsítótárazott pillanatképet.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Előfeltételek:** Node.js >= 20 npm/npx-szel; [iii-engine](https://iii.dev/docs) v0.22.1 vagy Docker. A macOS/Linux automatikus engine-telepítés `curl`-t, egy POSIX `sh`-t és `tar`-t is igényel; a natív Windows a manuális, pinnelt `iii.exe`-t, a WSL2-t vagy a Docker Desktopot használja.
+
+
+
+ Agen coding Anda mengingat segalanya. Tidak perlu menjelaskan ulang.
+ Dibangun di atas iii engine
+
+ Memori persisten untuk Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, dan klien MCP apa pun.
+
+ Gist ini memperluas pola LLM Wiki milik Karpathy dengan confidence scoring, lifecycle, knowledge graph, dan hybrid search: agentmemory adalah implementasinya.
+
+
+---
+
+## Instalasi
+
+Persyaratan:
+
+- Node.js 20 atau lebih baru dengan npm dan npx (`node -v`, `npm -v`, dan `npx -v`).
+- Instalasi otomatis iii-engine di macOS/Linux juga membutuhkan `curl`, `sh` POSIX, dan `tar`. Image minimal seperti `node:20-slim` mungkin tidak menyertakannya.
+- Windows native membutuhkan `iii.exe` iii-engine v0.22.1 yang dipin untuk dipasang secara manual. WSL2 atau Docker Desktop adalah jalur lain yang didukung.
+
+Perintah instalasi awal yang baku:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Jalankan pertama adalah setup interaktif: pilih agen yang ingin disambungkan (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pilih penyedia LLM atau tetap tanpa kunci (keyless), lalu agentmemory menyiapkan konfigurasi, menjalankan server memori beserta iii engine yang dipin, dan menawarkan instalasi global agar perintah polos `agentmemory` berfungsi di mana saja setelahnya. `-y` menerima prompt paket dari npx dan `@latest` menghindari rilis cache yang basi. Penyedia LLM membuat fitur LLM tersedia, tetapi kompresi observasi yang ditulis LLM baru dimulai saat `AGENTMEMORY_AUTO_COMPRESS=true` juga diset.
+
+Mode tanpa kunci (keyless) menonaktifkan vector embedding. `memory_recall` (jalur `mem::search`) memakai BM25, sementara `memory_smart_search` juga bisa menggabungkan kecocokan graph struktural saat data graph sudah ada. Untuk recall semantik gratis di perangkat sendiri, set `EMBEDDING_PROVIDER=local` di `~/.agentmemory/.env` lalu restart. Permintaan embedding pertama mengunduh `Xenova/all-MiniLM-L6-v2`; inferensi berjalan lokal setelah unduhan model awal itu.
+
+Runtime lokal memakai empat port: `3111` untuk REST/MCP HTTP, `3112` untuk stream iii, `3113` untuk viewer, dan `49134` untuk WebSocket worker iii. State iii yang persisten disimpan di `~/Library/Application Support/agentmemory` di macOS, `$XDG_DATA_HOME/agentmemory` atau `~/.local/share/agentmemory` di Linux, dan `%APPDATA%\agentmemory` di Windows. Gunakan `--data-dir ` atau `AGENTMEMORY_DATA_DIR` untuk menggantinya, dan pakai nilai yang sama setiap kali restart. Untuk kompatibilitas mundur, `./data/state_store.db` atau `./data/iii-config.yaml` yang sudah ada akan diprioritaskan di atas default platform untuk instance 0; flag eksplisit atau override environment tetap menang.
+
+Lalu buktikan bahwa recall berfungsi dan beri agen Anda skill-nya:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Pencarian kata kunci seharusnya berhasil di mode keyless default lewat BM25. Query `database performance optimization` pada demo sengaja dibuat semantik dan bisa menghasilkan nol sampai penyedia embedding dikonfigurasi.
+
+Lebih suka membiarkan agen coding mengerjakan semuanya? Berikan satu instruksi ini:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Sambungkan lebih banyak agen kapan saja dengan `agentmemory connect ` — 20 adapter terdaftar di [Bekerja dengan setiap agen](#works-with-every-agent). Referensi perintah lengkap ada di [Mulai Cepat](#quick-start).
+
+
+Windows
+
+Jalur tercepat adalah WSL2. Setup engine Windows native membutuhkan ZIP v0.22.1 yang dipin untuk diunduh dan `iii.exe` diekstrak secara manual; CLI tidak mengekstraknya secara otomatis. Docker Desktop juga didukung. Lihat [catatan Windows](#windows) untuk langkah demi langkahnya.
+
+
+
+
+Instalasi global / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Perintah npx di atas tetap menjadi jalur instalasi awal yang baku dan menghindari masalah izin global-prefix.
+
+
+
+
+npx menyajikan versi lama
+
+npx melakukan cache per versi. Paksakan versi terbaru dengan `npx -y @agentmemory/agentmemory@latest`, atau bersihkan cache sekali dengan `rm -rf ~/.npm/_npx` (macOS/Linux; di Windows hapus `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Sudah menjalankan iii engine sendiri
+
+agentmemory mem-pin iii-engine v0.22.1 dan tidak akan menyambung ke versi lain (worker tidak bisa berbicara dengan protokol engine lain). Hentikan engine lain itu, lalu jalankan `npx -y @agentmemory/agentmemory@latest`. Ini akan memasang dan menjalankan v0.22.1 yang dipin di `~/.agentmemory/bin`, tanpa mengganggu `iii` milik Anda sendiri.
+
+
+
+---
+
+
+
+agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API. Semua agen berbagi server memori yang sama.
+
+
+
+
+
+Claude Code
+plugin native + 12 hook + MCP
+
+
+
+Codex CLI
+plugin native + 6 hook + MCP
+
+
+
+GitHub Copilot CLI
+MCP + hook/skill plugin
+
+
+
+Cursor
+plugin native + 7 hook + MCP
+
+
+
+OpenCode
+plugin capture + MCP
+
+
+
+
+
+Devin
+6 hook + skill + MCP
+
+
+
+OpenClaw
+plugin native + MCP
+
+
+
+Hermes
+plugin native + MCP
+
+
+
+pi
+plugin native + MCP
+
+
+
+OpenHuman
+backend native Memory trait
+
+
+
+
+
+Gemini CLI
+server MCP
+
+
+
+Antigravity
+MCP + hook
+
+
+
+Claude Desktop
+server MCP
+
+
+
+Warp
+connect + MCP + skill
+
+
+
+Zed
+server MCP
+
+
+
+
+
+Cline
+server MCP
+
+
+
+Continue
+server MCP
+
+
+
+Droid
+server MCP
+
+
+
+Kiro
+server MCP
+
+
+
+Qwen Code
+server MCP
+
+
+
+
+
+DeepSeek Harness
+server MCP
+
+
+
+Roo Code
+server MCP
+
+
+
+Kilo Code
+server MCP
+
+
+
+Goose
+server MCP
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Bekerja dengan agen apa pun yang memakai MCP atau HTTP. Satu server, memori dibagikan di antara semuanya.
+
+
+---
+
+Anda menjelaskan arsitektur yang sama setiap sesi. Anda menemukan ulang bug yang sama. Anda mengajarkan ulang preferensi yang sama. Memori bawaan (CLAUDE.md, .cursorrules) terbatas pada 200 baris dan jadi basi. agentmemory memperbaiki ini. Secara diam-diam, agentmemory menangkap apa yang dilakukan agen Anda, mengompresnya menjadi memori yang bisa dicari, dan menyuntikkan konteks yang tepat saat sesi berikutnya dimulai. Satu perintah. Bekerja lintas agen.
+
+**Yang berubah:** Sesi 1 Anda menyiapkan autentikasi JWT. Sesi 2 Anda minta rate limiting. Agen sudah tahu bahwa autentikasi Anda memakai middleware jose di `src/middleware/auth.ts`, test Anda mencakup validasi token, dan Anda memilih jose dibanding jsonwebtoken untuk kompatibilitas Edge, tanpa harus menjelaskan ulang dan tanpa copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Secara default, agentmemory menyimpan state iii-engine di luar repository tempat Anda menjalankannya: `~/Library/Application Support/agentmemory` di macOS, `$XDG_DATA_HOME/agentmemory` atau `~/.local/share/agentmemory` di Linux, dan `%APPDATA%\agentmemory` di Windows. `./data/state_store.db` atau `./data/iii-config.yaml` versi lama yang sudah ada akan dipakai ulang untuk instance 0 sebelum default platform tersebut. Untuk memilih lokasi secara eksplisit, gunakan `--data-dir ` atau set `AGENTMEMORY_DATA_DIR`; kedua setelan eksplisit ini diprioritaskan di atas penemuan lokasi lama:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Peluncuran native dan Docker memakai direktori host hasil resolusi yang sama; Docker bind-mount direktori itu di `/data`. `--instance 1` menambahkan `instance-1` ke direktori hasil resolusi dan memilih kuartet port default yang terpisah `3211/3212/3213/49234`.
+
+Catatan rilis terbaru: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Akurasi Retrieval
+
+**coding-agent-life-v1** (korpus in-house, bisa direproduksi di sandbox)
+
+| Adapter | P@5 | R@5 | Top-5 hit rate | Latensi p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+Top-5 hit rate 100% pada **batas matematis P@5** untuk korpus ini (0.240, lihat scorecard). Hybrid me-retrieve setiap sesi gold; grep melewatkan 1 dari 2 gold pada query temporal multi-sesi. Peningkatannya ada pada **recall + temporal**, bukan presisi agregat. Benchmark ini kecil dan gold-nya jarang; LongMemEval-S yang lebih besar di bawah memberi pembeda yang lebih baik. Rincian lengkap per tipe + catatan koreksi: [`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 pertanyaan)
+
+| Sistem | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Fallback BM25-only | 86.2% | 94.6% | 71.5% |
+
+
+
+> Model embedding: `all-MiniLM-L6-v2` (lokal, gratis, tanpa API key). Laporan lengkap: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Perbandingan kompetitor: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) mencakup agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Reproduksi secara lokal:** [`eval/README.md`](../eval/README.md), harness yang adapternya bisa dipasang-cabut untuk LongMemEval `_s` (500-Q publik) + `coding-agent-life-v1` (korpus in-house 15 sesi). Adapter grep / vector / agentmemory dinilai berdampingan, output NDJSON, scorecard yang dipublikasikan mendarat di [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Berpasangan dengan [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), dan [Graphify](https://github.com/safishamsi/graphify).** Code-graph indexing, pipeline build multi-agen, dan knowledge graph yang lebih luas lintas dokumen / PDF / gambar / video. agentmemory mengingat pekerjaannya; ketiga proyek itu menghidupkan sisa layer konteksnya. Resep + tabel perutean pertanyaan: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Bawaan (CLAUDE.md)
+
+
+
Tipe
+
Memory engine + server MCP
+
API memory layer
+
Runtime agen lengkap
+
AI pribadi
+
API memori + app
+
Hub memori tim (proxy LLM)
+
Vector memory (OSS)
+
Memory engine (Oracle DB)
+
Sistem memori
+
File statis
+
+
+
Retrieval R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Self-reported
+
PersonaMem 76% (self-reported)
+
~96.6% (self-reported)
+
94.4% (self-reported)
+
N/A
+
N/A (grep)
+
+
+
Auto-capture
+
12 hook (tanpa effort manual)
+
Panggilan add() manual
+
Self-edit oleh agen
+
Manual
+
Ekstraksi di sisi API
+
Intersepsi proxy (swap base-URL)
+
Manual
+
Ekstraksi API
+
Manual
+
Edit manual
+
+
+
Search
+
BM25 + Vector + Graph (fusi RRF)
+
Vector + Graph
+
Vector (archival)
+
Semantik
+
Vector + RAG
+
4 tipe aset (Chat / Skill / Wiki / CodeGraph)
+
Vector-only
+
Vector + semantik
+
Decay-weighted
+
Memuat semuanya ke konteks
+
+
+
Multi-agen
+
MCP + REST + lease + signal
+
API (tanpa koordinasi)
+
Hanya dalam runtime Letta
+
Tidak
+
Tidak
+
Role tim + aset bersama
+
Tidak
+
Hanya terbatas (scoped)
+
Multi-agen bersama
+
File per agen
+
+
+
Framework lock-in
+
Tidak ada (klien MCP apa pun)
+
Tidak ada
+
Tinggi (harus pakai Letta)
+
Standalone
+
Tidak ada
+
Proxy mengarahkan setiap panggilan model
+
Tidak ada
+
Oracle Database
+
Tidak ada
+
Format per agen
+
+
+
Dependensi eksternal
+
Tidak ada (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + vector DB
+
Multipel
+
Cloud terkelola
+
Stack Docker (Core + Hub + Proxy)
+
Vector store
+
Oracle AI Database
+
Tidak ada
+
Tidak ada
+
+
+
Siklus hidup memori
+
Konsolidasi 4-tier + decay + auto-forget
+
Ekstraksi pasif
+
Dikelola agen
+
Manual
+
Auto-forget
+
Review manual; auto-routing sedang dikerjakan
+
Tidak ada
+
Tidak disebutkan
+
Decay + konsolidasi
+
Pruning manual
+
+
+
Efisiensi token
+
~1.900 token/sesi ($10/thn)
+
Bervariasi menurut integrasi
+
Core memory di konteks
+
Bervariasi
+
Harga cloud
+
Tidak disebutkan
+
Tanpa budget token
+
Didukung LLM (bervariasi)
+
Bervariasi
+
22K+ token pada 240 observasi
+
+
+
Viewer real-time
+
Ya (port 3113)
+
Dashboard cloud
+
Dashboard cloud
+
Web UI
+
Dashboard cloud
+
Web UI Hub
+
Tidak
+
Tidak
+
Tidak
+
Tidak
+
+
+
Self-hosted
+
Ya (default)
+
Opsional
+
Opsional
+
Ya
+
Tidak (cloud-only)
+
Ya (Docker)
+
Ya
+
Ya (Oracle DB)
+
Ya
+
Ya
+
+
+
+Catatan benchmark: hanya R@5 agentmemory yang merupakan hasil pengukuran kami sendiri (LongMemEval-S, bisa direproduksi dari benchmark/COMPARISON.md). Angka mem0 dan Letta adalah angka LoCoMo yang mereka publikasikan sendiri (dataset yang berbeda); angka MemPalace, supermemory, TencentDB (PersonaMem), dan oracleagentmemory adalah klaim self-reported vendor yang belum kami reproduksi secara independen (run oracleagentmemory memakai GPT-5.5 terhadap Oracle AI Database). Ditampilkan berdampingan hanya sebagai perkiraan kasar, bukan head-to-head pada data yang identik. Jumlah star bersifat perkiraan dan bisa berubah seiring waktu.
+
+**Pemain baru** yang layak diketahui, dibahas lebih dalam di [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Sistem | ⭐ | Sudut pandang |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Knowledge graph temporal; hasil query temporal terpublikasi terkuat (LongMemEval 63.8%), tapi graph dibangun secara asinkron sehingga fakta baru bisa tertinggal |
+| Cognee | 30K | Ingestion dokumen-ke-knowledge-graph, Python-only, dibangun untuk ekstraksi entitas terstruktur bukan capture sesi |
+
+Tidak satu pun dari ini yang auto-capture dari hook agen coding, menyediakan viewer local-first, atau berjalan tanpa kunci (keyless) — kombinasi yang menjadi fondasi agentmemory.
+
+---
+
+
+
+Kompatibilitas: rilis ini menyasar `iii-sdk` 0.22.1 dan mem-pin iii-engine v0.22.1.
+
+### Coba dalam 30 detik
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` menyemai (seed) 3 sesi realistis (autentikasi JWT, perbaikan query N+1, rate limiting) dan menjalankan pencarian terhadapnya. Instalasi tanpa kunci menonaktifkan vector, sehingga query kata kunci `mem::search` seharusnya berhasil lewat BM25 sementara `database performance optimization` bisa menghasilkan nol. `smart-search` bisa juga mengembalikan kecocokan graph struktural saat data graph ada. Agar query semantik menemukan perbaikan N+1 lewat vector, set `EMBEDDING_PROVIDER=local`, restart, dan biarkan unduhan model pertama selesai.
+
+Buka `http://localhost:3113` untuk menyaksikan memori terbangun secara live.
+
+### Validasi instalasi baru dan persistensi setelah restart
+
+Dengan server berjalan, validasi REST, health, viewer, dan status runtime yang didukung iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Panel ready saat startup memperhitungkan keempat port: REST/MCP HTTP di 3111, stream iii di 3112, viewer di 3113, dan WebSocket worker iii di 49134. `status` mengonfirmasi kesehatan agentmemory dan mode provider/embedding yang aktif. Simpan sebuah probe dan konfirmasi bisa dicari:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Lalu jalankan `npx -y @agentmemory/agentmemory@latest stop`, jalankan lagi perintah baku di Terminal 1, tunggu `/agentmemory/livez`, dan ulangi pencariannya. Probe itu harus masih dikembalikan. Jika Anda memilih `--data-dir` custom, gunakan direktori yang sama saat restart.
+
+### Perintah sehari-hari
+
+Instalasi dan setup ada di [Instalasi](#install) di atas (jalankan pertama akan menuntun Anda melaluinya). Sehari-hari:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Replay Sesi
+
+Setiap sesi yang direkam agentmemory bisa direplay. Buka viewer, pilih tab **Replay**, lalu scrub sepanjang timeline: prompt, tool call, hasil tool, dan respons dirender sebagai event diskret dengan play/pause, kontrol kecepatan (0.5x hingga 4x), dan shortcut keyboard (spasi untuk toggle, arrow untuk melangkah).
+
+Untuk membawa masuk transkrip JSONL Claude Code yang lama:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Sesi yang diimpor muncul di picker Replay bersama sesi native. Di balik layar setiap entri melewati fungsi iii `mem::replay::load`, `mem::replay::sessions`, dan `mem::replay::import-jsonl`, tanpa server side-channel. Setiap transkrip yang diimpor diindeks untuk pencarian, dicap dengan channel asal `import`, dan ditambang untuk crystal sesi dan lesson.
+
+> **Perhatian jika Anda mengandalkan `import-jsonl` sebagai jalur capture utama:** `cleanupPeriodDays` milik Claude Code (di `~/.claude/settings.json`, default **30**) menghapus otomatis transkrip JSONL yang lebih tua dari window itu dari `~/.claude/projects/`. Jika Anda memasang agentmemory baru pada histori Claude Code yang sudah berbulan-bulan, apa pun yang lebih tua dari 30 hari sudah hilang sebelum impor pertama. Entah jalankan `import-jsonl` lewat cron, naikkan `cleanupPeriodDays` jadi lebih tinggi, atau sambungkan hook auto-capture (jalur instalasi plugin default) sehingga setiap giliran langsung masuk ke agentmemory selagi sesi berjalan dan pembersihan JSONL tidak lagi jadi masalah.
+
+### Upgrade / Pemeliharaan
+
+Gunakan perintah pemeliharaan saat Anda sengaja ingin memperbarui runtime lokal Anda:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Peringatan: perintah ini mengubah workspace/runtime saat ini. Ia bisa memperbarui dependensi JavaScript dan menarik image Docker `iiidev/iii:0.22.1` yang dipin. Ia tidak akan pernah memasang iii engine yang tidak dipin atau lebih baru.
+
+Detail implementasi ada di `src/cli.ts` (lihat `runUpgrade` di sekitar region `src/cli.ts:544-595`).
+
+### Claude Code (satu blok, tempel saja)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code tanpa instalasi plugin (jalur MCP-standalone)
+
+Jika Anda menyambungkan server MCP agentmemory lewat `~/.claude.json` secara langsung tanpa memakai `/plugin install`, Claude Code tidak pernah meresolusi `${CLAUDE_PLUGIN_ROOT}` dan Anda harus mengarahkan script hook ke path absolut di `~/.claude/settings.json`. Path tersebut biasanya menyertakan versi agentmemory (misalnya `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), sehingga upgrade berikutnya diam-diam merusak setiap hook.
+
+Solusinya:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Ini menggabungkan perintah hook yang sama ke `~/.claude/settings.json` dengan path absolut yang diresolusi ke direktori `plugin/` bundel dari paket `@agentmemory/agentmemory` yang sedang terpasang. Jalankan ulang perintah ini setelah upgrade agentmemory untuk menyegarkan path-nya. Entri pengguna di file yang sama tetap dipertahankan; hanya entri agentmemory sebelumnya yang diganti. Jalur `/plugin install` tetap menjadi pendekatan yang direkomendasikan.
+Untuk deployment remote atau terlindungi, jalankan Claude Code dengan `AGENTMEMORY_URL` dan `AGENTMEMORY_SECRET` yang sudah diset. Plugin ini meneruskan kedua nilai itu ke server MCP bundelnya; ketika `AGENTMEMORY_URL` kosong, shim MCP memakai `http://localhost:3111`.
+
+### Codex CLI (platform plugin Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Plugin Codex dikirim dari direktori `plugin/` yang sama dengan plugin Claude Code. Ia mendaftarkan:
+
+- Bridge MCP stdio bundel ke daemon yang berjalan, tanpa unduhan npm atau fallback store. Lihat [panduan Codex lokal](../docs/plugins/codex-local.md) untuk menguji build yang belum dirilis.
+- 6 hook lifecycle: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skill yang bisa dipanggil: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, ditambah 8 skill referensi yang dimuat agen sesuai kebutuhan (disiplin memori, tool MCP, REST API, konfigurasi, agen, hook, arsitektur, dan panduan penulisan skill)
+
+Engine hook Codex menyuntikkan `CLAUDE_PLUGIN_ROOT` ke subproses hook (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), sehingga script hook yang sama bekerja di kedua host tanpa duplikasi. Event Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure hanya berlaku untuk Claude Code dan tidak didaftarkan untuk Codex.
+
+#### Trust dan kompatibilitas hook Codex
+
+Dispatch hook plugin native sudah terverifikasi dengan Codex CLI 0.150.1. Percayai (trust) hook plugin sebelum mengharapkan capture. Perilaku Desktop bergantung pada runtime bundelnya; periksa `/hooks` dan pastikan ada event yang ter-capture sebelum mengaktifkan workaround.
+
+Jika host Anda memerlukan hook global, cerminkan perintahnya ke `~/.codex/hooks.json`. Jika MCP sudah tersambung, connector saat ini memerlukan `--force` untuk mencapai instalasi hook:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Ini menggabungkan hook global dan menulis ulang entri MCP agentmemory, sambil mempertahankan entri lain yang tidak terkait. Tinjau kembali setelan endpoint agentmemory custom Anda sebelum memakai `--force`. Jalankan ulang setelah upgrade untuk menyegarkan path script. Aktifkan salah satu: hook plugin native atau salinan global, untuk menghindari capture ganda.
+
+### GitHub Copilot CLI
+
+Untuk mode agen VS Code, gunakan [panduan MCP dan automatic-capture Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Connector CLI ini tidak mengonfigurasi VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` menggabungkan `mcpServers.agentmemory` ke `~/.copilot/mcp-config.json` (atau `$COPILOT_HOME/mcp-config.json` saat `COPILOT_HOME` diset) dan mempertahankan server yang sudah ada. Di Windows native ini adalah satu-satunya adapter `connect` otomatis; konfigurasikan setiap agen Windows native lain secara manual. `connect` di WSL hanya tepat dipakai saat agen target juga terpasang di environment WSL yang sama. Copilot mengambil server MCP pada peluncuran berikutnya atau setelah `/mcp`. Pasang plugin-nya juga jika Anda menginginkan pengalaman hook/skill yang lengkap.
+
+
+OpenClaw (tempel prompt ini)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Panduan lengkap: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (tempel prompt ini)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Panduan lengkap: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Agen lainnya
+
+Jalankan server memori: `npx -y @agentmemory/agentmemory@latest`
+
+#### Native skill lewat `npx skills add` (50+ agen)
+
+agentmemory menyediakan 17 skill dalam format `/SKILL.md` ala Claude Code: 9 skill aksi yang bisa dipanggil (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) dan 8 skill referensi yang dimuat agen sesuai kebutuhan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Skill referensi membawa tabel data yang dihasilkan dari source, sehingga tidak pernah drift. CLI [`skills`](https://npmjs.com/package/skills) oleh vercel-labs memasangnya secara otomatis ke direktori skill native agen yang memanggilnya, di 50+ agen (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, dan lainnya):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Ini **melengkapi** `agentmemory connect `:
+
+- `agentmemory connect ` menulis konfigurasi server MCP sehingga tool-nya tersedia.
+- `npx skills add rohitg00/agentmemory` memasang skill-nya sehingga agen tahu kapan harus memanggilnya.
+
+Untuk sedikit agen yang belum dicakup CLI skills (Zed v1.3.x ke bawah), letakkan sendiri 17 file SKILL.md di bawah direktori skill native agen tersebut; format yang sama bekerja di mana saja.
+
+#### Blok MCP standar
+
+Entri agentmemory adalah **blok server MCP yang sama** di setiap host yang memakai bentuk `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Gabungkan entri ini ke dalam objek `mcpServers` yang sudah ada** di file konfigurasi host, jangan menggantikan seluruh file. Jika file itu sudah punya server lain, tambahkan `agentmemory` di sebelahnya sebagai key lain di dalam `mcpServers`. Jika `mcpServers` sama sekali belum ada, tempel bloknya di dalam `{ "mcpServers": { ... } }`. Placeholder `${VAR}` mewarisi `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` dari shell saat server MCP diluncurkan; variabel yang tidak diset meneruskan string kosong dan shim-nya fallback ke `http://localhost:3111`. Satu entri yang tersambung mencakup deployment lokal maupun remote (k8s / reverse-proxied).
+
+| Agen | File konfigurasi | Catatan |
+|---|---|---|
+| **Cursor (MCP saja)** | `~/.cursor/mcp.json` | Gabungkan ke `mcpServers`, atau `agentmemory connect cursor`. Deeplink satu klik juga tersedia di website. |
+| **Cursor (plugin lengkap)** | `.cursor-plugin/` | Listing Cursor Marketplace (submission sedang direview) atau Cursor Settings → Plugins → checkout lokal. Mendaftarkan 7 hook auto-capture (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + server MCP, dengan `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` dikelola di dashboard plugin Cursor. Bekerja di Cursor IDE dan CLI `cursor-agent`; prompt mode-print CLI di-backfill dari transkrip sesi saat sesi berakhir. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Gabungkan ke `mcpServers`. Restart Claude Desktop setelah mengedit. |
+| **Cline / Roo Code / Kilo Code** | Setelan MCP Cline (Settings UI → MCP Servers → Edit) | Blok `mcpServers` yang sama. |
+| **Devin CLI (MCP + hook)** | `~/.config/devin/config.json` | `agentmemory connect devin` menggabungkan entri MCP; `--with-hooks` menambahkan enam hook auto-capture native (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) dengan matcher tool huruf-kecil milik Devin. Verifikasi dengan `devin mcp list` dan `/hooks` di dalam devin. |
+| **Devin CLI (plugin lengkap)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` dari sebuah checkout mendaftarkan semua 17 skill sebagai slash command `/agentmemory:` ditambah server MCP. Hook plugin Devin tidak bisa memicu `SessionStart`/`SessionEnd`, jadi pasangkan dengan `connect devin --with-hooks` untuk capture sesi yang lengkap. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Tambahkan MCP custom (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` mengarah ke deployment agentmemory yang terjangkau lewat network ditambah `AGENTMEMORY_SECRET` (sesi cloud tidak bisa menjangkau localhost — lihat [`deploy/`](../deploy/)). Simpan secret di Devin Secrets, lalu pakai "Test listing tools" untuk memverifikasi semua 54 tool muncul. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merge). |
+| **GitHub Copilot CLI (MCP saja)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` menggabungkan `mcpServers.agentmemory`; Copilot mengambilnya pada peluncuran berikutnya atau `/mcp`. |
+| **GitHub Copilot CLI (plugin lengkap)** | Instalasi plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` untuk plugin dari subdir GitHub. |
+| **OpenClaw** | Konfigurasi MCP OpenClaw | Blok `mcpServers` yang sama. Lebih dalam: `openclaw plugins install ./integrations/openclaw` mengklaim slot memori OpenClaw (auto-switch dari `memory-core`); set `plugins.entries.agentmemory.hooks.allowConversationAccess=true` atau capture-nya akan diam-diam diblokir. Lihat [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (MCP saja)** | `.codex/config.toml` | Bentuk TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, atau tambahkan `[mcp_servers.agentmemory]` secara manual. |
+| **Codex CLI (plugin lengkap)** | Marketplace plugin Codex | `codex plugin marketplace add rohitg00/agentmemory` lalu `codex plugin add agentmemory@agentmemory`. Mendaftarkan MCP + 6 hook lifecycle + 17 skill. Percayai (trust) hook dan verifikasi capture di host Anda; lihat [setup dan validasi Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (MCP saja)** | `opencode.json` | Bentuk berbeda: key top-level `mcp`, command sebagai array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin lengkap)** | `plugin/opencode/` | 22 hook auto-capture mencakup lifecycle sesi, message, tool, error. Atribusi proyek bersifat per-sesi, sehingga satu proses OpenCode yang membentang beberapa repository mencatat setiap sesi di bawah proyeknya sendiri. Dua slash command (`/recall`, `/remember`). Salin `plugin/opencode/` ke workspace OpenCode Anda dan tambahkan entri plugin ke `opencode.json`. Lihat [`plugin/opencode/README.md`](../plugin/opencode/README.md) untuk tabel hook lengkap + analisis gap. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` memasang extension bundel ke direktori auto-discovery milik pi (recall saat agen start, capture saat agen end, tool `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` pada pi yang berjalan akan mengambilnya. [`integrations/pi`](../integrations/pi/) juga adalah paket pi (`pi install ./integrations/pi` dari sebuah checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` memberikan memory provider 6-hook (prefetch, turn capture, session end, pre-compress, mirroring MEMORY.md, blok system prompt). Validasi dengan `hermes plugins doctor` dan `hermes memory status`. Lihat [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` menulis blok `mcpServers` standar. Payload hook kompatibel secara field dengan Claude Code, sehingga 12 script hook yang sudah ada bekerja tanpa modifikasi; sambungkan lewat bagian `hooks` di `settings.json` yang sama. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` memasang MCP dan hook capture di direktori kustomisasi bersama. Lihat [pengaturan dan batasan Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` memakai konfigurasi MCP dan hook yang sama dengan versi IDE saat ini. Instalasi yang sudah ada sebaiknya di-refresh dengan `--force`; lihat [catatan upgrade](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` menulis konfigurasi tingkat pengguna. Override workspace masuk di `.kiro/settings/mcp.json` di sebelah kode Anda. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` menulis blok `mcpServers` standar. Warp juga auto-discover skill dari `.claude/skills/`; setelah plugin Claude Code terpasang, 8 skill agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) muncul secara native di palet slash-command Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` menulis blok `mcpServers` standar. Pengguna ekstensi VS Code: tempel blok yang sama lewat Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (disarankan) atau `config.json` (legacy) | `agentmemory connect continue` membuat `config.yaml` dari awal saat keduanya belum ada, atau memodifikasi `config.json` yang sudah ada. **Jika Anda sudah punya `config.yaml`**, adapter ini mencetak blok persis untuk ditempel di bawah `mcpServers:`; ia tidak akan diam-diam menulis ulang yaml Anda karena mempertahankan komentar dan anchor dengan aman membutuhkan parser YAML yang tidak disertakan paket ini. Continue memakai bentuk array (bukan objek) untuk `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` menulis di bawah `context_servers` (key milik Zed, BUKAN `mcpServers`). Server MCP remote bisa disambungkan lewat `{"url": "..."}` sebagai gantinya. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` menulis blok `mcpServers` standar. Override berbasis proyek masuk di `/.factory/mcp.json`. Tambahkan `--with-hooks` untuk auto-capture native. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` menambahkan baris `@deepseek-ai/dsh-mcp-client` ke layer patch tingkat home yang dimuat setiap profil Harness; tool terdaftar sebagai `mcp__agentmemory__*`. Tambahkan `--with-hooks` untuk juga menyambungkan auto-capture: script hook Claude Code bundel berjalan lewat bridge first-party Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) lewat manifest yang ditulis ke `$DSH_HOME/agentmemory.hooks.json`. Default ke `~/.dsh` saat `DSH_HOME` tidak diset. |
+| **Goose** | Settings UI MCP Goose | Blok `mcpServers` yang sama; gunakan `goose configure` → Add Extension → MCP. Edit YAML langsung di `~/.config/goose/config.yaml` juga didukung tapi skemanya memakai `extensions:` + `cmd` (bukan `mcpServers:` + `command`). |
+| **Aider** | n/a | Bicara langsung dengan REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Agen apa pun (32+)** | n/a | `npx skillkit install agentmemory` auto-detect host dan menggabungkannya. |
+
+**Klien MCP yang di-sandbox** (Flatpak / Snap / kontainer restriktif) yang tidak bisa menjangkau `localhost` milik host: set juga `"AGENTMEMORY_FORCE_PROXY": "1"` di blok `env`, dan arahkan `AGENTMEMORY_URL` ke rute yang benar-benar bisa dijangkau sandbox (misalnya IP LAN Anda).
+
+### Akses programatik (Python / Rust / Node)
+
+agentmemory mendaftarkan operasi intinya sebagai fungsi iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Bahasa apa pun yang punya SDK iii bisa memanggilnya langsung lewat `ws://localhost:49134`, tanpa klien REST terpisah per bahasa.
+
+```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"},
+})
+```
+
+Contoh kerja: [`examples/python/`](../examples/python/) (quickstart + flow observasi/recall). REST di `:3111` tetap tersedia untuk host tanpa runtime iii.
+
+### Dari source
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Ini menjalankan agentmemory dengan `iii-engine` lokal jika binary yang dipin sudah terpasang, atau memakai Docker Compose saat dipilih. REST, stream, dan viewer terbind ke `127.0.0.1` secara default. Jalur binary otomatis macOS/Linux membutuhkan `curl`, `sh` POSIX, dan `tar`.
+
+Pasang `iii-engine` secara manual. **agentmemory saat ini mem-pin `iii-engine` ke `v0.22.1`**, rilis yang sama dengan dependensi `iii-sdk`-nya; worker berbicara dengan wire protocol engine itu, dan 0.20.0 menata ulang permukaan SDK, sehingga keduanya bergerak bersama di rilis agentmemory. Override dengan `AGENTMEMORY_III_VERSION=` jika Anda menjalankan engine sendiri dan tahu itu cocok.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** ganti `aarch64-apple-darwin` dengan `x86_64-apple-darwin`
+- **Linux x64:** ganti dengan `x86_64-unknown-linux-gnu`
+- **Linux arm64:** ganti dengan `aarch64-unknown-linux-gnu`
+- **Windows:** unduh `iii-x86_64-pc-windows-msvc.zip` dari [rilis iii-hq/iii v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) dan ekstrak `iii.exe` ke `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Setiap arsip punya file `.sha256` yang cocok di halaman rilis; saat Anda mengganti platform, pakai hash dari file itu pada pengecekan di atas (di Windows: `Get-FileHash`). Installer otomatis di `npx @agentmemory/agentmemory` mem-pin hash-hash ini dan menolak arsip yang tidak cocok.
+
+Atau pakai Docker (`docker-compose.yml` bundel menarik `iiidev/iii:0.22.1`). Dokumentasi lengkap: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory berjalan di Windows 10/11, tapi paket Node.js saja tidak cukup; Anda juga membutuhkan runtime iii-engine v0.22.1 yang dipin sebagai proses background. CLI tidak mengekstrak ZIP Windows secara otomatis, sehingga pengguna Windows native harus memasang `iii.exe` secara manual, memakai WSL2, atau memilih Docker Desktop.
+
+Penyambungan MCP otomatis di Windows native hanya mendukung `agentmemory connect copilot-cli`. Untuk Claude Code, Codex, Cursor, dan setiap agen Windows native lainnya, salin blok MCP manual dari [Agen lainnya](#other-agents) ke konfigurasi Windows agen tersebut. Menjalankan `connect` di WSL hanya tepat saat agen target juga terpasang di environment WSL yang sama; itu tidak mengedit konfigurasi agen pada host Windows.
+
+**Opsi A: binary Windows prebuilt (disarankan)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opsi B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opsi C: hanya MCP standalone (tanpa engine).** Jika Anda hanya butuh tool MCP untuk agen Anda dan tidak membutuhkan REST API, viewer, atau cron job, lewati engine-nya sama sekali:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostik untuk Windows:** jika `npx -y @agentmemory/agentmemory@latest` gagal, jalankan ulang dengan `--verbose` untuk melihat stderr engine yang sebenarnya. Mode kegagalan umum:
+
+| Simptom | Perbaikan |
+|---|---|
+| `The engine process started but the REST API never responded.` | Pastikan keempat port hasil derivasi bebas, verifikasi `iii.exe` yang dipin tetap hidup, lalu jalankan ulang dengan `--verbose` dan periksa stderr engine yang tertangkap |
+| `Could not start iii-engine` | Baik `iii.exe` maupun Docker tidak terpasang. Lihat Opsi A atau B di atas |
+| Konflik port | `netstat -ano \| findstr :3111` untuk melihat apa yang terbind, lalu matikan atau pakai `--port ` |
+| Fallback Docker dilewati walau Docker terpasang | Pastikan Docker Desktop benar-benar berjalan (ikon system tray) |
+
+> Catatan: **engine** iii adalah binary prebuilt, bukan crate cargo, jadi jangan coba `cargo install`. (**SDK** iii dipublikasikan di crates.io, npm, dan PyPI, tapi agentmemory tidak membutuhkannya.) Metode instalasi engine yang didukung semuanya dipin ke v0.22.1: binary prebuilt di atas, jalur auto-install macOS/Linux milik agentmemory (`curl`, `sh` POSIX, dan `tar` dibutuhkan), dan image Docker `iiidev/iii:0.22.1`. `install.sh | sh` upstream yang polos memasang engine terbaru, yang tidak didukung agentmemory. Gunakan `npx -y @agentmemory/agentmemory@latest`; di macOS/Linux ia mengambil engine yang dipin ke `~/.agentmemory/bin`.
+
+---
+
+
Deploy
+
+Template satu klik untuk host terkelola. Masing-masing menyediakan
+Dockerfile mandiri yang menarik `@agentmemory/agentmemory` dari npm dan
+menyalin binary engine iii dari image Docker Hub resmi `iiidev/iii`;
+tidak perlu image agentmemory prebuilt. Storage persisten
+termount di `/data`; entrypoint first-boot menimpa
+konfigurasi iii bawaan npm (yang terbind ke `127.0.0.1`) dengan
+konfigurasi yang disetel untuk deployment, yang terbind ke `0.0.0.0` dan
+memakai path `/data` absolut, membuat secret HMAC, lalu
+melepas privilese dari `root` ke `node` lewat
+`gosu` sebelum exec ke CLI agentmemory.
+
+
+
+
+
+
+Tombol deploy satu klik milik Render membutuhkan `render.yaml` di root repository, yang dengan sengaja kami biarkan bersih. Gunakan flow Render Blueprint yang didokumentasikan di [`deploy/render/`](.././deploy/render/README.md) untuk mengarah ke blueprint in-repo secara manual.
+
+Detail setup lengkap (capture HMAC, SSH tunnel viewer, rotasi, backup,
+batas bawah biaya) ada di [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): satu machine dengan
+ `auto_stop_machines = "stop"`; paling murah saat idle.
+- [`deploy/railway`](.././deploy/railway/README.md): biaya flat plan Hobby,
+ volume di dashboard.
+- [`deploy/render`](.././deploy/render/README.md): flow Blueprint,
+ snapshot disk otomatis di plan berbayar.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted di
+ VPS Anda sendiri lewat [Coolify](https://coolify.io/self-hosted); stack Docker
+ Compose yang sama, Anda memiliki host dan datanya.
+
+Hanya port `3111` yang dipublikasikan. Viewer di `3113` tetap
+terbind ke loopback di dalam kontainer; README setiap template
+mendokumentasikan pola SSH-tunnel untuk menjangkaunya.
+
+---
+
+
+
+Setiap agen coding melupakan segalanya saat sesi berakhir, dan setiap sesi baru dimulai dengan Anda menjelaskan ulang stack Anda. agentmemory berjalan di background dan menghilangkan langkah itu.
+
+```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 memori bawaan agen
+
+Setiap agen coding AI dilengkapi memori bawaan: Claude Code punya `MEMORY.md`, Cursor punya notepad, Cline punya memory bank. Ini bekerja seperti sticky note. agentmemory adalah database yang bisa dicari di balik sticky note itu.
+
+| | Bawaan (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skala | Batas 200 baris | Tak terbatas |
+| Search | Memuat semuanya ke konteks | BM25 + vector + graph (hanya top-K) |
+| Biaya token | 22K+ pada 240 observasi | ~1.900 token (92% lebih sedikit) |
+| Lintas agen | File per agen | MCP + REST (agen apa pun) |
+| Koordinasi | Tidak ada | Lease, signal, action, routine |
+| Observability | Baca file secara manual | Viewer real-time di :3113 |
+
+---
+
+
+
+### Pipeline Memori
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### Konsolidasi Memori 4-Tier
+
+Dimodelkan dari cara otak manusia memproses memori, termasuk konsolidasi saat tidur.
+
+| Tier | Apa | Analogi |
+|------|------|---------|
+| **Working** | Observasi mentah dari pemakaian tool | Memori jangka pendek |
+| **Episodic** | Ringkasan sesi yang dikompres | "Apa yang terjadi" |
+| **Semantic** | Fakta dan pola yang diekstraksi | "Apa yang saya tahu" |
+| **Procedural** | Workflow dan pola keputusan | "Bagaimana melakukannya" |
+
+Memori meluruh (decay) dari waktu ke waktu (kurva Ebbinghaus). Memori yang sering diakses menguat. Memori yang basi otomatis dievict. Kontradiksi dideteksi dan diselesaikan.
+
+### Apa yang Ditangkap
+
+| Hook | Menangkap |
+|------|----------|
+| `SessionStart` | Path proyek, ID sesi |
+| `UserPromptSubmit` | Prompt pengguna (disaring privasinya) |
+| `PreToolUse` | Pola akses file + konteks yang diperkaya |
+| `PostToolUse` | Nama tool, input, output |
+| `PostToolUseFailure` | Konteks error |
+| `PreCompact` | Menyuntikkan ulang memori sebelum compaction |
+| `SubagentStart/Stop` | Lifecycle sub-agen |
+| `Stop` | Ringkasan akhir sesi |
+| `SessionEnd` | Marker sesi selesai |
+
+### Kemampuan Utama
+
+| Kemampuan | Deskripsi |
+|---|---|
+| **Capture otomatis** | Setiap pemakaian tool direkam lewat hook, tanpa effort manual |
+| **Semantic search** | BM25 + vector + knowledge graph dengan fusi RRF |
+| **Evolusi memori** | Versioning, supersession, graph relasi |
+| **Kebersihan recall** | Versi memori yang disupersede keluar dari index pencarian; rantai versi di KV menyimpan histori lengkap |
+| **Petunjuk near-duplicate** | Saat menyimpan, muncul kecocokan advisory `similarTo` ketika konten baru sangat menyerupai memori yang sudah ada |
+| **Scoping per agen** | `agentId` mengalir lewat save dan recall di REST, MCP, dan index pencarian, dalam mode shared atau isolated |
+| **Provenance saat penulisan** | Setiap observasi dan memori membawa channel asal yang tak berubah (user, agent, tool, import, atau shared) yang dicap saat capture, save, dan import |
+| **Auto-forgetting** | Kedaluwarsa TTL, deteksi kontradiksi, eviction berdasarkan importance |
+| **Privacy first** | API key, secret, tag `` dihapus sebelum disimpan |
+| **Self-healing** | Circuit breaker, rantai fallback provider, health monitoring |
+| **Claude bridge** | Sinkronisasi dua arah dengan MEMORY.md |
+| **Knowledge graph** | Ekstraksi entitas + traversal BFS |
+| **Memori tim** | Namespace shared + private di antar anggota tim |
+| **Citation provenance** | Lacak memori apa pun kembali ke observasi sumbernya |
+| **Snapshot Git** | Versi, rollback, dan diff state memori |
+
+---
+
+
+
+Retrieval triple-stream yang mengombinasikan tiga sinyal:
+
+| Stream | Yang dilakukan | Kapan |
+|---|---|---|
+| **BM25** | Pencocokan kata kunci yang di-stem dengan ekspansi sinonim | Selalu aktif |
+| **Vector** | Cosine similarity pada dense embedding | Penyedia embedding dikonfigurasi |
+| **Graph** | Traversal knowledge graph lewat pencocokan entitas | Entitas terdeteksi di query |
+
+Difusikan dengan Reciprocal Rank Fusion (RRF, k=60) dan didiversifikasi per sesi (maksimum 3 hasil per sesi).
+
+Saat index vector terisi, `mem::search` (di belakang `memory_recall`) memakai ranker hybrid BM25 + vector. Tanpa embedding ia memakai BM25. `smart-search` juga bisa menggabungkan kecocokan graph struktural saat data graph ada, termasuk di mode keyless. Recall lesson berjalan di index BM25 in-memory khusus bukan memindai seluruh korpus per query. Versi memori yang disupersede dikecualikan dari setiap jalur recall; rantai versi menyimpan histori mereka.
+
+Vector tetap bertahan dari crash atau force-kill. Index vector disimpan dalam bucket paling lambat setiap `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 menit). Setiap vector yang ditambahkan atau dihapus di antaranya juga langsung ditulis ke log pending kecil di state store, dan start berikutnya me-replay-nya tanpa memanggil penyedia embedding. Setiap save yang berhasil mengosongkan log itu. Dokumen yang masih belum punya vector setelah replay di-embed ulang di background dalam batch `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) sampai tidak ada yang tersisa, dan backfill yang terhenti dilanjutkan pada start berikutnya. `/agentmemory/status` dan viewer menunjukkan ukuran log pending dan state backfill. Instalasi keyless tidak menulis apa pun.
+
+BM25 men-tokenisasi Yunani, Sirilik, Ibrani, Arab, dan Latin beraksen secara bawaan. Untuk memori Tionghoa / Jepang / Korea, pasang segmenter opsional (`npm install @node-rs/jieba tiny-segmenter`) untuk membelah runtun CJK menjadi token level-kata; tanpa itu, agentmemory soft-fallback ke tokenisasi seluruh runtun dan mencetak hint satu-kali di stderr.
+
+### Penyedia embedding
+
+Instalasi keyless menonaktifkan vector embedding: `mem::search` memakai BM25, sementara `smart-search` juga bisa memakai data graph struktural yang sudah ada. Untuk opt-in ke embedding semantik gratis di perangkat sendiri, tambahkan ini ke `~/.agentmemory/.env` dan restart agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Instalasi npm normal menyertakan runtime opsional `@huggingface/transformers`. Permintaan embedding pertama mengunduh `Xenova/all-MiniLM-L6-v2`, sehingga membutuhkan akses network dan bisa lebih lama; inferensi berikutnya berjalan di perangkat sendiri. Penyedia remote terdeteksi otomatis dari key-nya kecuali `EMBEDDING_PROVIDER` meng-override-nya.
+
+| Penyedia | Model | Biaya | Catatan |
+|---|---|---|---|
+| **Lokal (opt-in yang disarankan)** | `all-MiniLM-L6-v2` | Gratis | Di perangkat sendiri setelah unduhan model pertama, +8pp recall dibanding BM25-only |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ bahasa, 768/1536/3072 dimensi (MRL), input 2048-token. Menggantikan `text-embedding-004` ([deprecated, shutdown 14 Jan 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Kualitas tertinggi |
+| Voyage AI | `voyage-code-3` | Berbayar | Dioptimalkan untuk code |
+| Cohere | `embed-english-v3.0` | Free trial | Tujuan umum |
+| OpenRouter | Model apa pun | Bervariasi | Proxy multi-model |
+
+---
+
+
+
+54 tool, 6 resource, 3 prompt, dan 17 skill.
+
+> **Shim MCP vs server lengkap:** paket `@agentmemory/mcp` yang dipublikasikan adalah shim tipis. Ia menampilkan permukaan 54-tool lengkap **hanya saat bisa menjangkau server agentmemory yang berjalan** lewat `AGENTMEMORY_URL` (mode proxy). Tanpa server yang terjangkau, shim ini fallback ke set 7-tool lokal (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Env var `AGENTMEMORY_TOOLS=core|all` adalah flag *sisi server*; mengesetnya di blok `env` shim tidak berefek. Jika Anda hanya melihat 7 tool di Cursor / OpenCode / Gemini CLI, jalankan `npx -y @agentmemory/agentmemory@latest` (atau stack Docker) dan set `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 Tool
+
+Tiga permukaan tool, dari terkecil ke terbesar: `AGENTMEMORY_TOOLS=core` memangkas visibilitas menjadi 8 tool esensial (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); set dasar di bawah adalah 14 tool fundamental milik registry; default (`AGENTMEMORY_TOOLS=all`) menampilkan semua 54.
+
+
+Tool dasar (14)
+
+| Tool | Deskripsi |
+|------|-------------|
+| `memory_recall` | Mencari observasi lampau |
+| `memory_compress_file` | Mengompres file markdown sambil mempertahankan struktur |
+| `memory_save` | Menyimpan insight, keputusan, atau pola |
+| `memory_file_history` | Observasi lampau tentang file tertentu |
+| `memory_patterns` | Mendeteksi pola berulang |
+| `memory_sessions` | Mendaftar sesi terbaru |
+| `memory_smart_search` | Search hybrid semantik + kata kunci |
+| `memory_vision_search` | Mencari observasi gambar |
+| `memory_timeline` | Observasi kronologis |
+| `memory_profile` | Profil proyek (konsep, file, pola) |
+| `memory_export` | Mengekspor semua data memori |
+| `memory_relations` | Query graph relasi |
+| `memory_commit_lookup` | Sesi di balik sebuah commit git |
+| `memory_commits` | Commit yang tercatat untuk sebuah sesi |
+
+
+
+
+Tool extended (54 total, permukaan default)
+
+| Tool | Deskripsi |
+|------|-------------|
+| `memory_patterns` | Mendeteksi pola berulang |
+| `memory_timeline` | Observasi kronologis |
+| `memory_relations` | Query graph relasi |
+| `memory_graph_query` | Traversal knowledge graph |
+| `memory_consolidate` | Menjalankan konsolidasi 4-tier |
+| `memory_claude_bridge_sync` | Sinkronisasi dengan MEMORY.md |
+| `memory_team_share` | Berbagi dengan anggota tim |
+| `memory_team_feed` | Item terbaru yang dibagikan |
+| `memory_audit` | Audit trail operasi |
+| `memory_governance_delete` | Menghapus dengan audit trail |
+| `memory_snapshot_create` | Snapshot bervesi-Git |
+| `memory_action_create` | Membuat work item dengan dependensi |
+| `memory_action_update` | Memperbarui status action |
+| `memory_frontier` | Action yang tidak terblokir, diurutkan berdasar prioritas |
+| `memory_next` | Satu action berikutnya yang paling penting |
+| `memory_lease` | Lease action eksklusif (multi-agen) |
+| `memory_routine_run` | Menjalankan routine workflow |
+| `memory_signal_send` | Pesan antar-agen |
+| `memory_signal_read` | Membaca pesan dengan receipt |
+| `memory_checkpoint` | Gate kondisi eksternal |
+| `memory_mesh_sync` | Sinkronisasi P2P antar instance |
+| `memory_sentinel_create` | Watcher berbasis event |
+| `memory_sentinel_trigger` | Memicu sentinel dari luar |
+| `memory_sketch_create` | Graph action yang efemeral |
+| `memory_sketch_promote` | Mempromosikan jadi permanen |
+| `memory_crystallize` | Memadatkan rantai action |
+| `memory_diagnose` | Health check |
+| `memory_heal` | Auto-fix state yang stuck |
+| `memory_facet_tag` | Tag dimension:value |
+| `memory_facet_query` | Query berdasarkan facet tag |
+| `memory_verify` | Melacak provenance |
+
+
+
+### 6 Resource · 3 Prompt · 17 Skill
+
+| Tipe | Nama | Deskripsi |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, jumlah sesi, jumlah memori |
+| Resource | `agentmemory://project/{name}/profile` | Intelijen per proyek |
+| Resource | `agentmemory://project/{name}/recent` | Observasi terbaru untuk sebuah proyek |
+| Resource | `agentmemory://memories/latest` | 10 memori aktif terbaru |
+| Resource | `agentmemory://graph/stats` | Statistik knowledge graph |
+| Resource | `agentmemory://team/{id}/profile` | Profil tim yang dibagikan |
+| Prompt | `recall_context` | Mencari + mengembalikan message konteks |
+| Prompt | `session_handoff` | Data handoff antar agen |
+| Prompt | `detect_patterns` | Menganalisis pola berulang |
+| Skill | `/recall` | Mencari memori |
+| Skill | `/remember` | Menyimpan ke memori jangka panjang |
+| Skill | `/session-history` | Ringkasan sesi terbaru |
+| Skill | `/forget` | Menghapus observasi/sesi |
+
+Tabel ini menampilkan empat skill inti. Set lengkapnya adalah 9 skill yang bisa dipanggil ditambah 8 skill referensi; lihat bagian Native skills di atas.
+
+### MCP Standalone
+
+Jalankan tanpa server lengkap, untuk klien MCP apa pun. Salah satu dari ini berfungsi:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Atau tambahkan ke konfigurasi MCP agen Anda:
+
+Kebanyakan agen (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Gabungkan entri `agentmemory` ke objek `mcpServers` yang sudah ada di host Anda, bukan menggantikan filenya. Untuk klien yang di-sandbox dan tidak bisa menjangkau `localhost` milik host, tambahkan `"AGENTMEMORY_FORCE_PROXY": "1"` ke blok env dan set `AGENTMEMORY_URL` ke rute yang bisa dijangkau sandbox.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Salin file plugin dari repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Auto-start di port `3113`. Viewer memuat satu snapshot saat terhubung (`GET /agentmemory/viewer/snapshot`) lalu menerapkan event stream live: memori baru, lesson, observasi, entri audit, perubahan graph, dan update health muncul tanpa polling atau reload halaman. Satu-satunya permintaan lain adalah aksi yang Anda klik, halaman "load more", dan pencarian. Saat stream putus, viewer menunjukkan seberapa basi angkanya, menyambung ulang dengan backoff, dan resync dari satu snapshot.
+
+- **12 tab dalam empat grup** dengan hitungan live, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), shortcut keyboard, dan menu mobile.
+- **Memories:** search sisi server, filter berdasarkan proyek, agen, dan tipe, panel detail dengan rantai versi dan word diff, link provenance, tombol copy untuk id, panggilan MCP, dan perintah curl, edit (versi baru), forget dengan konfirmasi, bulk forget, dan ekspor JSON.
+- **Sessions:** timeline observasi inline dengan input dan output tool yang mudah dibaca, filter dan paging, serta memori dan lesson yang dihasilkan setiap sesi.
+- **Graph:** search, detail node dengan relasi dan sumber, legenda yang tidak hanya mengandalkan warna, dan kontrol zoom.
+- **Health:** versi live dari `GET /agentmemory/status`. Setiap masalah disertai perbaikannya, plus backend state, status penyimpanan index, progres kompaksi graph provenance, dan penjelas konsolidasi dengan threshold yang sesungguhnya.
+- Halaman **Audit, Activity, Profile, Replay, Lessons, Actions, dan Crystals**, masing-masing dengan empty state yang menjelaskan apa bagian itu, mengapa kosong, dan perintah yang mengisinya, serta tooltip glosarium `?` di setiap istilah dan angka.
+
+```bash
+open http://localhost:3113
+```
+
+Server viewer terbind ke `127.0.0.1` secara default dan melampirkan secret server saat meneruskan permintaan ke REST API, sehingga tidak butuh setup. Endpoint `/agentmemory/viewer` yang disajikan REST mengikuti aturan bearer-token normal dan mengarahkan browser tanpa token ke port viewer. Header CSP memakai script nonce per-respons dan menonaktifkan atribut inline handler (`script-src-attr 'none'`).
+
+---
+
+
+
+Viewer di `:3113` menunjukkan apa yang **diingat** oleh agen Anda. [iii console](https://iii.dev/docs/console) menunjukkan apa yang **dilakukan** agen Anda: setiap operasi memori sebagai trace OpenTelemetry, setiap entri KV bisa diedit, setiap fungsi bisa dipanggil, setiap stream bisa disadap. Dua jendela pada memori yang sama: satu berbentuk produk, satu berbentuk engine.
+
+Lihat `memory_smart_search` dipicu dan saksikan scan BM25 → lookup embedding → fusi RRF → reranker sebagai waterfall. Edit timer konsolidasi yang stuck di KV browser. Replay hook `PostToolUse` dengan payload yang diubah. Pin stream WebSocket dan saksikan observasi mendarat secara live.
+
+agentmemory menyediakan ini secara gratis karena setiap panggilan fungsi dan trigger dipicu lewat iii; tidak ada yang custom, tidak ada yang perlu diinstrumentasi.
+
+
+
+
+ Halaman Workers: setiap worker yang terhubung, termasuk agentmemory sendiri, dengan PID, jumlah fungsi, runtime, dan last-seen.
+
+
+**Sudah terpasang.** Console dikirim bersama engine `iii` yang dipin (0.22+); tidak ada yang perlu dipasang terpisah. Peluncuran pertama mengunduh binary console di sebelah engine.
+
+**Jalankan bersama agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Ini menjalankan `iii console` dari engine yang dipin terhadap port hasil resolusi agentmemory (REST, stream, bridge) dan menyajikannya satu port di atas viewer, `http://localhost:3114` secara default. `--console-port N` memilih port lain; `--port` dan `--instance` memilih instance agentmemory dengan cara yang sama seperti untuk `stop`; flag lain apa pun diteruskan, misalnya `--enable-flow` untuk halaman architecture-graph eksperimental.
+
+Hal yang sama secara manual, berguna saat `agentmemory` tidak ada di PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Apa yang bisa Anda lakukan dari console:**
+
+| Halaman | Gunakan untuk |
+|------|-----------|
+| **Workers** | Melihat setiap worker yang terhubung dan metrik live-nya, termasuk worker agentmemory sendiri. |
+| **Functions** | Memanggil langsung fungsi apa pun milik agentmemory dengan payload JSON; berguna untuk menguji `memory.recall`, `memory.consolidate`, `graph.query` tanpa menyambungkan klien. |
+| **Triggers** | Me-replay trigger HTTP, cron, event, dan state: memicu cron konsolidasi secara manual, retry rute HTTP, memancarkan perubahan state. |
+| **States** | Browser KV dengan CRUD penuh atas sesi, slot memori, timer lifecycle, dan index embedding; edit nilai di tempat. |
+| **Streams** | Monitor WebSocket live untuk penulisan memori, event hook, dan update observasi saat mengalir lewat stream iii. |
+| **Queues** | Topik queue durable + manajemen dead-letter. Replay atau drop job embedding / kompresi yang gagal. |
+| **Traces** | Tampilan waterfall / flame / service-breakdown OpenTelemetry. Filter berdasarkan `trace_id` untuk melihat persis fungsi, panggilan DB, dan permintaan embedding apa yang dihasilkan satu `memory.search`. |
+| **Logs** | Log OTEL terstruktur yang difilter dan dikorelasikan ke trace/span ID. |
+| **Config** | Konfigurasi runtime: lihat persis worker, provider, dan port apa yang dipakai engine Anda. |
+| **Flow** | (Opsional, `--enable-flow`) Graph arsitektur interaktif untuk setiap worker, trigger, dan stream. |
+
+
+
+
+ Traces: breakdown waterfall / flame / service untuk setiap operasi memori.
+
+
+**Trace sudah aktif:**
+
+`iii-config.yaml` dikirim dengan worker `iii-observability` sudah aktif (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Tidak perlu konfigurasi tambahan; begitu agentmemory start, setiap operasi memori memancarkan log terstruktur yang bisa dibaca console, dan satu dari sepuluh operasi (`sampling_ratio: 0.1`) juga memancarkan span trace.
+
+Jika Anda ingin mengekspor ke Jaeger/Honeycomb/Grafana Tempo sebagai gantinya, ubah `exporter: memory` jadi `exporter: otlp` dan set endpoint collector sesuai dokumentasi observability iii.
+
+> **Perhatian:** tidak ada autentikasi yang diberlakukan pada console itu sendiri; tetap terbind ke `127.0.0.1` (default) dan jangan pernah mengeksposnya secara publik.
+
+---
+
+
+
+agentmemory **sudah menjadi instance [iii](https://iii.dev) yang berjalan**. Tiga primitif (worker, function, trigger) menyusun runtime-nya; state KV, stream, dan trace OTEL datang dari worker iii-state, iii-stream, dan iii-observability yang dikirim bersama iii. Anda tidak memasang Postgres, Redis, Express, pm2, atau Prometheus, karena iii menggantikan semuanya.
+
+Artinya satu perintah lagi memperluas agentmemory dengan kemampuan baru yang sepenuhnya baru.
+
+### Perluas agentmemory dengan worker lain
+
+Builtin yang dibutuhkan agentmemory sudah ada di `iii-config.yaml` dan boot bersamanya: `iii-state` (KV), `iii-queue` (retry durable untuk event subscriber), `iii-pubsub`, `iii-cron`, `iii-stream`, dan `iii-observability` (trace, metrics, dan logs OTEL pada setiap fungsi). Apa pun yang lain dari [registry worker iii](https://workers.iii.dev) terpasang ke engine yang sama: salin `iii-config.yaml` ke `~/.agentmemory/iii-config.yaml` (CLI memprioritaskan file itu di atas yang bundel dan tetap merender port serta path data ke dalamnya), tambahkan entrinya, pasang runtime worker sekali dengan `~/.agentmemory/bin/iii update worker`, lalu restart agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Yang Anda dapat di atas agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Adapter state berbasis SQL saat Anda melampaui default KV in-memory |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code yang keluar dari `memory_recall` berjalan di dalam VM sekali pakai, bukan di shell Anda |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Mendirikan server MCP tambahan di sebelah milik agentmemory, berbagi engine yang sama |
+
+Di engine 0.22.x, pertahankan nama berprefiks `iii-` untuk builtin di atas; entri tanpa prefiks `http`, `state`, `queue`, `pubsub`, dan `cron` adalah worker registry standalone yang agentmemory pindah ke sana dengan migrasi 0.23.
+
+Registry lengkap: [workers.iii.dev](https://workers.iii.dev). Setiap worker di sana menyusun lewat primitif yang sama yang dipakai agentmemory, dan agentmemory yang Anda sudah punya adalah salah satunya.
+
+### Konfigurasi engine dan bind address
+
+`agentmemory start` membaca konfigurasi engine dari file pertama yang ada: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` di direktori saat ini, `~/.agentmemory/iii-config.yaml`, lalu `iii-config.yaml` bundel. Pada setiap start, ia merender file itu (path data, port, backend state) ke `~/.agentmemory/data/iii-config.runtime.yaml` dan meluncurkan engine dengan salinan hasil render itu, jadi edit file source-nya, bukan yang hasil render. Nilai `host:` pada file source dipertahankan sebagaimana tertulis.
+
+`iii-config.yaml` bundel sengaja terbind ke `127.0.0.1`, dan default itu juga berlaku di dalam kontainer. CLI yang dijalankan di dalam kontainer listen di loopback milik kontainer itu, sehingga port yang dipublikasikan tidak menjangkau apa pun. Untuk menyajikan CLI yang di-kontainerisasi lewat port yang dipublikasikan, set `AGENTMEMORY_III_CONFIG` ke konfigurasi yang terbind ke `0.0.0.0`. `iii-config.docker.yaml` yang dipaketkan adalah salah satunya: ia membind `iii-http`, `iii-stream`, dan port engine ke `0.0.0.0` dan menyimpan state di bawah `/data`, jadi mount volume yang bisa ditulis di sana. Tetap set `AGENTMEMORY_SECRET`, dan publikasikan hanya port yang Anda butuhkan, di `127.0.0.1` atau di belakang proxy yang Anda percaya.
+
+`docker-compose.yml` repo ini tidak melewati pencarian konfigurasi CLI: ia mount `iii-config.docker.yaml` di `/app/config.yaml`, dan kontainer `iii-engine` start dengan `--config /app/config.yaml`. Template [deploy](../deploy/) satu-klik menulis konfigurasi `0.0.0.0` mereka sendiri di entrypoint-nya.
+
+### Storage backend: file (default) vs redis
+
+`iii-state` dan `iii-stream` secara default memakai KV store berbasis file bundel iii-engine: satu file JSON per scope, dipegang di memori proses engine dan ditulis ulang ke disk secara berkala. Itu adalah default yang tepat untuk instalasi lokal satu pengguna; daemon bersama dengan beberapa penulis konkuren mendapat penulisan per-key yang sesungguhnya dari Redis sebagai gantinya, dengan biaya satu network round trip per operasi (setiap panggilan `state::*` tetap diserialisasi pada satu koneksi Redis, sehingga ini menukar lock file store dengan socket, bukan untuk paralelisme).
+
+Set `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) untuk mengalihkan kedua worker ke adapter `redis` bawaan iii-engine, yang menyimpan setiap key sebagai field hash Redis (`HSET`) bukan menulis ulang seluruh scope pada setiap penulisan:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` defaultnya `file`; membiarkannya tidak diset menjaga perilaku hari ini tidak berubah, dan nilai yang tidak dikenal (apa pun selain `file` atau `redis`) adalah error saat startup bukan fallback senyap. `/agentmemory/status` dan halaman Health viewer (baris State store) melaporkan backend mana yang aktif dan apakah ia merespons, tidak pernah URL-nya.
+
+**Hanya `redis://` polos.** Engine yang dipin (0.22.1) membangun klien Redis-nya tanpa dukungan TLS, sehingga URL `rediss://` (kebanyakan layanan Redis terkelola, seperti Upstash, Redis Cloud, dan ElastiCache dengan enkripsi in-transit, defaultnya TLS-only) gagal terhubung. Koneksinya tidak terenkripsi, sehingga password Redis dan setiap memori yang tersimpan melintasi kabel dalam teks jelas: arahkan ke Redis lokal atau yang berada di network privat yang Anda percaya. Untuk Redis lainnya, jalankan tunnel terenkripsi (stunnel, SSH, atau VPN) di host agentmemory, sehingga hop `redis://` polos itu tetap di host tersebut dan koneksi upstream tunnel-nya terenkripsi dan terautentikasi. Jika password Redis memuat tanda kutip tunggal, percent-encode-lah (`%27`); engine mengekspansi URL ke konfigurasi YAML-nya sebelum mem-parse-nya.
+
+**Satu server Redis per `--instance`.** Prefiks key Redis milik engine (`state:`, `stream::`) sudah tetap, sehingga dua instance agentmemory (`--instance 1`, `--instance 2`, ...) yang mengarah ke database yang sama akan saling menimpa datanya. Index database yang terpisah (`redis://localhost:6379/1`) menjaga data tersimpan terpisah, tapi engine meneruskan event viewer live lewat satu channel pub/sub Redis (`stream::events`), dan pub/sub Redis mengabaikan index database, sehingga viewer setiap instance tetap akan menunjukkan event live milik instance lain. Beri setiap instance server Redis-nya sendiri (atau port-nya sendiri) saat Anda menjalankan lebih dari satu.
+
+**Apa yang tetap sama, dan apa yang berbeda.** Setiap fitur agentmemory bekerja di Redis: session, observation, memory (remember, supersede, evolve, forget), search dan bucket index-nya, lesson, graph, audit log dan scope bulanannya, export dan import, governance delete, status konsolidasi, snapshot viewer dan stream live-nya, dan health monitor. Engine menyimpan setiap scope sebagai satu hash Redis (`HSET`/`HGET`/`HGETALL`) dan memicu state trigger yang sama seperti file store. Tiga perbedaan engine ditangani di dalam agentmemory:
+
+- Redis mengembalikan record sebuah scope tanpa urutan yang tetap. agentmemory mengurutkannya dari yang paling lama (berdasarkan waktu pembuatan di id record, lalu timestamp-nya) sehingga list, paging, dan chunk export kembali dalam urutan yang sama seperti di file store.
+- Engine menerapkan update parsial di Redis lewat skrip Lua yang mengubah array kosong jadi objek kosong. agentmemory menerapkan update itu sendiri (baca, ubah, tulis di bawah lock per-key) di Redis, sehingga field seperti `tags: []` tetap array.
+- Pengecekan audit log legacy membaca scope lama dari Redis bukan mencari file file store di disk.
+
+Satu perbedaan membutuhkan tindakan Anda: **setelah Redis restart, engine berhenti meneruskan event live** ke viewer sampai agentmemory restart. Data tetap tersimpan dan terbaca normal. Health monitor mengirim event tes lewat Redis setiap 30 detik; saat tidak kembali, `/agentmemory/status` dan halaman Health viewer menunjukkan "Live updates are not reaching the viewer" dengan perbaikannya: restart agentmemory. Jika Redis mati, laporan status menunjukkan "The state store is not answering" dan cara mengeceknya (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Mendaftar scope yang sangat besar membaca seluruh hash dalam satu `HGETALL`, biaya yang sama seperti file store yang menyimpannya di memori.
+
+**Setelan Redis yang direkomendasikan.** Policy snapshot default `save 3600 1 300 100 60 10000` bisa kehilangan beberapa menit penulisan saat crash, lebih buruk dari window flush 5 detik milik file store. Set `appendonly yes` untuk apa pun yang Anda sayang kehilangan. Set `maxmemory-policy noeviction`; `allkeys-lru` atau sejenisnya diam-diam membuang memori begitu Redis mencapai batas memorinya.
+
+Start native (non-Docker), dan setiap template [deploy](../deploy/) satu-klik (mereka menimpa `iii-config.yaml` bundel dan start secara native), membaca `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` dan merendernya ke `iii-config` yang diluncurkan. URL itu sendiri tidak pernah ditulis ke file hasil render itu, hanya referensi `${AGENTMEMORY_REDIS_URL}` yang diekspansi proses engine dari environment-nya sendiri saat boot. Hanya jalur Docker Compose milik repo ini sendiri (`AGENTMEMORY_USE_DOCKER=1`, atau melanjutkan engine yang sudah distart begitu) yang mount `iii-config.docker.yaml` secara read-only dan tidak pernah merender; `agentmemory start` memperingatkan saat mendeteksi kombinasi itu. Ubah file itu secara manual, mengikuti bentuk `name: redis` / `config: redis_url: ...` yang sama yang ditunjukkan di dokumentasi worker [iii-state](https://workers.iii.dev/workers/iii-state) dan [iii-stream](https://workers.iii.dev/workers/iii-stream), dan arahkan `redis_url` ke Redis yang terjangkau dari kontainer. `docker-compose.yml` meneruskan `AGENTMEMORY_REDIS_URL` ke kontainer engine, sehingga `redis_url: '${AGENTMEMORY_REDIS_URL}'` bekerja di sana dan menjaga URL-nya di luar file yang di-mount.
+
+Konfigurasi hasil render menjaga URL-nya di luar `~/.agentmemory/data/iii-config.runtime.yaml`, tapi worker konfigurasi milik engine sendiri tetap mempersistenkan nilai yang *terekspansi* ke `~/.agentmemory/config/iii-state.yaml` dan `iii-stream.yaml` begitu ia boot (ekspansi `${VAR}` milik iii-engine terjadi sebelum worker itu menyimpan seed-nya, dan ia menyimpan nilai yang sudah diresolusi, bukan referensinya). Perlakukan direktori itu sebagai penyimpan credential: `chmod 700 ~/.agentmemory` di host bersama mana pun, dan pilih user ACL Redis yang di-scope untuk kebutuhan agentmemory dibanding credential admin database.
+
+**Migrasi tidak otomatis.** Beralih `AGENTMEMORY_STATE_BACKEND` mulai dari store kosong di kedua sisi; tidak ada yang menyalin data yang sudah ada dari file ke Redis atau sebaliknya. Export dari backend yang Anda tinggalkan dan import ke yang Anda tuju. Ini berjalan identik di bash dan zsh (termasuk `bash -u`). Array seperti `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` tidak: zsh menjaga header sebagai satu word yang malformed sementara bash membelahnya jadi dua, sehingga kedua permintaan 401 setiap kali `AGENTMEMORY_SECRET` diset:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` juga menerima `?maxSessions=` dan `?offset=` untuk memecah korpus besar lewat beberapa panggilan; `strategy` pada import adalah `merge` (default-safe), `replace`, atau `skip`.
+
+### Apa yang digantikan iii
+
+| Stack tradisional | agentmemory memakai |
+|---|---|
+| Express.js / Fastify | iii HTTP Trigger |
+| SQLite / Postgres + pgvector | iii KV State + index vector in-memory |
+| SSE / Socket.io | iii Stream (WebSocket) |
+| pm2 / systemd | Supervisi worker engine iii |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Sistem plugin custom | `iii worker add ` |
+
+**225 file sumber · ~54,000 LOC · 2,600+ pengujian · 312 fungsi · 66 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
+
+---
+
+
+
+### Penyedia LLM
+
+agentmemory mendeteksi otomatis penyedia dari environment Anda. Penyedia membuat operasi berbasis LLM tersedia, tapi konfigurasi penyedia saja tidak mengaktifkan kompresi observasi yang ditulis LLM. Jalur itu membutuhkan baik penyedia maupun `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Penyedia | Konfigurasi | Catatan |
+|----------|--------|-------|
+| **No-op (default)** | Tidak perlu konfigurasi | Compress/summarize berbasis LLM dinonaktifkan. Kompresi sintetis dan recall BM25 tetap bekerja. Lihat `AGENTMEMORY_ALLOW_AGENT_SDK` di bawah jika Anda dulu mengandalkan fallback subscription Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Billing per-token |
+| MiniMax | `MINIMAX_API_KEY` | Kompatibel Anthropic |
+| Gemini | `GEMINI_API_KEY` | Juga mengaktifkan embedding |
+| OpenRouter | `OPENROUTER_API_KEY` | Model apa pun |
+| OpenAI API | `OPENAI_API_KEY` | Default `gpt-5.6-luna`, override dengan `OPENAI_MODEL` |
+| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) atau `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Apa pun yang kompatibel OpenAI-API. Biaya nol, berjalan di hardware Anda. Lihat [Model lokal](#local-models-ollama--lm-studio--vllm) di bawah. |
+| Fallback subscription Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Hanya opt-in. Memunculkan sesi `@anthropic-ai/claude-agent-sdk`; dulu bisa menyebabkan rekursi Stop-hook tanpa batas, sehingga tidak lagi jadi default. |
+
+### Model lokal (Ollama / LM Studio / vLLM)
+
+agentmemory berbicara dengan server yang kompatibel OpenAI-API apa pun, sehingga apa pun yang mengekspos `/v1/chat/completions` bekerja tanpa perubahan kode. Tanpa key berbayar, tanpa cloud, tanpa rate limit; berjalan sepenuhnya di hardware Anda.
+
+**Ollama** (port default `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (port default `1234`):
+
+Buka LM Studio → tab Local Server → Start Server. Pilih model chat apa pun dari picker-nya (Qwen 3, gpt-oss, DeepSeek R1, dll).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: bentuk yang sama. Arahkan `OPENAI_BASE_URL` ke URL apa pun yang diekspos server Anda dan set `OPENAI_MODEL` ke nama yang akan diterima server Anda.
+
+**Pilihan model untuk kerja memori**: kompresi dan summarization adalah task singkat (<2K token masuk, <500 token keluar) di mana model instruct 7B sudah lebih dari cukup. Rekomendasi:
+
+| Model | Ukuran | Alasan |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Default seimbang di mesin 16 GB; kuat untuk ekstraksi dan teks berbentuk tool |
+| `qwen3:4b` | ~2.6 GB | Opsi paling kecil yang masih wajar; cocok untuk kompresi, lebih lemah untuk ekstraksi graph |
+| `qwen3-coder:30b` | ~19 GB | Pilihan lokal terbaik untuk sesi berbentuk code (30B MoE, 3.3B active) di hardware 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Model umum yang kuat dan cukup untuk RAM 16 GB |
+| `deepseek-r1:8b` | ~5.2 GB | Distilasi reasoning; lebih lambat tapi ekstraksinya lebih bersih |
+
+Model Qwen 3 berpikir secara default dan bisa menghabiskan seluruh budget token untuk reasoning sebelum ada output. Set `AGENTMEMORY_LLM_NOTHINK=1` untuk menambahkan `/no_think` ke prompt ekstraksi graph, dan naikkan `MAX_TOKENS` (16384 cukup) jika ekstraksi kembali kosong.
+
+Model reasoning-class (bergaya `o1` dengan blok ``) bisa mengembalikan `content` kosong dengan field `reasoning` yang server lokal Anda mungkin tidak munculkan. Jika ekstraksi kembali kosong, ganti ke model non-reasoning dulu. Env `OPENAI_REASONING_EFFORT=none` juga bisa menonaktifkan thinking pada model thinking Ollama Cloud yang mencerminkan skema reasoning OpenAI.
+
+Embedding lokal dikirim sebagai dependensi opsional tapi tidak aktif secara default. Set `EMBEDDING_PROVIDER=local` untuk opt-in ke `Xenova/all-MiniLM-L6-v2` (384-dim). Permintaan embedding pertama mengunduh modelnya; inferensi berikutnya di perangkat sendiri. Tanpa setelan itu atau key embedding remote, vector tetap nonaktif, `mem::search` memakai BM25, dan `smart-search` tetap bisa menambahkan kecocokan graph yang sudah ada.
+
+### Pemilihan model yang sadar biaya
+
+Saat kompresi background yang ditulis LLM diaktifkan dengan baik penyedia maupun `AGENTMEMORY_AUTO_COMPRESS=true`, ia berjalan pada setiap observasi, sehingga pilihan model secara berarti mengubah pengeluaran bulanan. Data workload yang tertangkap: 635 permintaan / 888K token / 35 jam pemakaian aktif, dijalankan terhadap tiga model OpenRouter dengan harga per 2026-05-23.
+
+| Tier | Model | Input / 1M | Output / 1M | Biaya untuk 35j yang tertangkap | Catatan |
+|------|-------|------------|-------------|---------------------------|-------|
+| Direkomendasikan | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | DeepSeek terbaru; pilihan termurah yang direkomendasikan untuk workload kompresi. |
+| Direkomendasikan | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Kualitas kompresi + summarization yang solid dengan biaya ~10× lebih rendah dari Sonnet. |
+| Direkomendasikan | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Reasoning code yang kuat jika sesi Anda sangat berbentuk code. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Harga list sama dengan run Sonnet 4.6 yang terukur; harga intro $2/$10 hingga 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Tier flagship; mahal untuk kerja background yang always-on. |
+| Hindari | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Model kelas flagship; overspend untuk kompresi. |
+
+Baris yang terukur berasal dari run yang tertangkap; baris (est.) menskalakan campuran token yang sama dengan harga list setiap model.
+
+agentmemory mencetak peringatan runtime saat `OPENROUTER_MODEL` cocok dengan pola tier premium. Set `AGENTMEMORY_SUPPRESS_COST_WARNING=1` untuk membisukannya setelah Anda membuat pilihan yang terinformasi.
+
+Tradeoff kualitas vs biaya untuk kerja memori: kompresi adalah task summarization dengan bar kualitas yang relatif longgar (agen membaca ulang ringkasannya, bukan penggunanya). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder mendarat dalam margin kesalahan yang sama dengan Sonnet pada task ini sambil berbiaya 10-70× lebih murah. Simpan model tier premium untuk query yang Anda baca langsung.
+
+Sumber: [harga OpenRouter untuk Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [catatan harga DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Memori multi-agen (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Pada setup multi-agen di mana beberapa role berbagi satu server agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` menandai setiap penulisan dengan role yang membuatnya. `AGENTMEMORY_AGENT_SCOPE` mengontrol apakah recall memfilter berdasarkan tag itu.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Dua mode:
+
+| Mode | Tag penulisan | Filter recall | Kapan dipakai |
+|------|------------|---------------|-------------|
+| `shared` (default) | ya | tidak | Konteks lintas-agen dengan audit trail. Architect bisa melihat apa yang dicatat developer, tapi setiap baris mencatat siapa yang mengatakannya. |
+| `isolated` | ya | ya | Pemisahan ketat. Architect tidak pernah melihat observasi / memori / sesi milik developer. |
+
+Apa yang ditandai saat `AGENT_ID` diset: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Role-nya mengalir dari `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Apa yang difilter di mode isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Setiap endpoint menerima `?agentId=` untuk override per-permintaan, dan `?agentId=*` untuk keluar dari scope env sepenuhnya. `/memories` juga menerima `?includeOrphans=true` untuk menampilkan memori pra-AGENT_ID yang `agentId`-nya tidak terdefinisi.
+
+Override per-panggilan di layer SDK / REST: setiap endpoint yang mengubah data (`/session/start`, `/remember`) menerima field `agentId` di body permintaan yang menang di atas env. Berguna untuk runtime yang merutekan banyak role lewat satu proses server. Tool MCP `memory_save` mengekspos field `agentId` yang sama, server stdio standalone meneruskan baik `agentId` maupun `project`, dan memori yang disimpan membawa `agentId` ke index pencarian, sehingga pencarian yang di-scope agen mencakup memori selain observasi.
+
+Saat `AGENT_ID` tidak diset, memori tetap unscoped (perilaku legacy, tanpa tag, tanpa filter).
+
+### Port
+
+agentmemory + iii-engine membind empat port secara default. Jika restart gagal dengan `port in use`, tabel ini memberitahu proses mana yang harus dicari.
+
+| Port | Proses | Tujuan | Override env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker stream internal (dikonsumsi agentmemory + viewer) | `III_STREAM_PORT` (disarankan) atau legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer real-time (`http://localhost:3113`) | `III_VIEWER_PORT` atau `AGENTMEMORY_VIEWER_URL` untuk URL yang dilaporkan |
+| `49134` | iii-engine | WebSocket; worker mendaftar di sini, telemetri OTel mengalir lewatnya | `III_ENGINE_PORT` atau `III_ENGINE_URL` |
+
+`--port ` mengubah anchor REST dan menurunkan stream `N+1`, viewer `N+2`, dan WebSocket engine `N+46023` hanya saat port eksplisit atau URL terkait di atas belum diset. Ini tidak membuat namespace lifecycle yang terisolasi. Gunakan `--instance 1` untuk daemon kedua; ia memakai anchor 3211, default ke `3211/3212/3213/49234`, dan menerima direktori data dan lifecycle `instance-1` yang terpisah. Instance 1 hingga 50 mengikuti pola yang sama.
+
+Engine yang dipin start dengan `--no-update-check` (tanpa pengecekan update atau security-advisory ke GitHub saat boot) dan dengan telemetri pemakaian anonim iii nonaktif: agentmemory set `III_TELEMETRY_ENABLED=false` untuk engine yang dimunculkannya kecuali Anda mengekspor variabel itu sendiri, dan file compose bundel melakukan hal yang sama.
+
+Pembersihan proses basi saat port tetap terbind setelah run yang 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
+```
+
+`agentmemory stop` membersihkan baik pidfile worker maupun engine secara bersih saat shutdown native yang graceful. Di mode Docker, ia menguras worker native, menghentikan tepat kontainer engine yang tervalidasi, dan mempertahankan baik kontainer maupun mount `/data`-nya untuk restart tanpa kehilangan data; start berikutnya memvalidasi dan melanjutkan kontainer yang sama itu. Uninstall yang didukung Docker membutuhkan `agentmemory remove --keep-data`: ia menghapus file bersama yang dikelola agentmemory sambil mempertahankan kontainer yang tervalidasi, mount datanya, dan record lifecycle yang dibutuhkan untuk memulihkannya. Penghapusan data Docker yang destruktif dengan sengaja dibiarkan ke operator setelah backup. CLI juga menolak mengadopsi atau mengirim sinyal ke pemegang port Docker atau VM (backend Docker, vpnkit, colima) sebagai engine native kecuali `--force` diberikan. Pembersihan manual di atas hanya untuk kasus pasca-crash saat tidak ada pidfile yang tersisa.
+
+### File Konfigurasi
+
+Letakkan konfigurasi runtime agentmemory di `~/.agentmemory/.env` daripada mengekspor variabel di setiap shell. Jika viewer menunjukkan hint setup seperti `export ANTHROPIC_API_KEY=...`, salin itu ke file ini sebagai `ANTHROPIC_API_KEY=...` tanpa prefiks `export`, lalu restart agentmemory.
+
+Variabel environment proses tetap berfungsi dan diprioritaskan di atas nilai di file itu.
+
+Di Windows, file yang sama ada di `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Untuk mencoba dengan subscription Claude Code Pro/Max dibanding API key, opt-in secara eksplisit:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Kompresi observasi yang ditulis LLM membutuhkan kedua baris itu: akses ke penyedia LLM (termasuk fallback subscription eksplisit ini) dan `AGENTMEMORY_AUTO_COMPRESS=true`. Penyedia saja membiarkan jalur kompresi sintetis default tetap berlaku.
+
+Konsolidasi (node graph, lesson, crystal) aktif secara default kapan pun penyedia LLM dikonfigurasi. Opt-out secara eksplisit dengan `CONSOLIDATION_ENABLED=false` jika Anda ingin operasi tanpa LLM. Ekstraksi graph adalah flag terpisah:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Variabel Environment
+
+Buat `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoint di port `3111`. REST API terbind ke `127.0.0.1` secara default. Endpoint yang terlindungi membutuhkan `Authorization: Bearer `, dan endpoint mesh sync membutuhkan `AGENTMEMORY_SECRET` yang diset secara eksplisit di kedua peer.
+
+**Autentikasi aktif secara default.** Saat `AGENTMEMORY_SECRET` tidak diset (di shell atau di `~/.agentmemory/.env`), server menghasilkan secret acak pada start pertama dan menyimpannya di `~/.agentmemory/secret` dengan mode `0600`. Setiap klien bundel membacanya dari sana saat berbicara dengan server lokal: CLI, viewer, hook di bawah `plugin/scripts`, server MCP dan shim `@agentmemory/mcp`, konfigurasi yang ditulis `agentmemory connect`, serta integrasi OpenCode, Pi, OpenClaw, Hermes, dan filesystem-watcher bundel. Secret yang tersimpan hanya dikirim ke URL loopback (`localhost`, `127.0.0.0/8`, `::1`). `AGENTMEMORY_SECRET` eksplisit selalu menang, dan klien remote tetap membutuhkannya diset. Docker dan entrypoint `deploy/` sudah menghasilkan dan mengekspor secret-nya sendiri. Untuk memanggil API secara manual:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Aturan permintaan untuk penulisan.** Permintaan `POST`, `PUT`, `PATCH`, dan `DELETE` ke REST API dan viewer harus mengirim `Content-Type: application/json` (parameter `charset` boleh) kapan pun mereka membawa body, dan header `Origin`, jika ada, harus berupa origin loopback untuk port REST atau viewer yang dikonfigurasi, atau terdaftar di `VIEWER_ALLOWED_ORIGINS` (dipisah koma, misalnya `https://memory.example.com`). Klien yang tidak mengirim header `Origin` (CLI, hook, MCP, curl, server-ke-server) tidak terpengaruh. Viewer juga menerima origin-nya sendiri.
+
+**Path file.** Endpoint yang membaca atau menulis file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) hanya menerima path di bawah `~/.agentmemory`, direktori data instance, atau direktori yang terdaftar di `AGENTMEMORY_IMPORT_ROOT` (pisahkan beberapa dengan `:`, atau `;` di Windows). `/replay/import-jsonl` juga menerima default-nya `~/.claude/projects`. `/obsidian/export` tetap di dalam `AGENTMEMORY_EXPORT_ROOT` dan `/migrate` di dalam `~/.agentmemory`. Symlink diresolusi sebelum setiap pengecekan.
+
+**Scrubbing secret.** API key, bearer token, blok PEM private key, dan credential yang tertanam di URL (`scheme://user:password@host`) disamarkan sebelum teks disimpan, pada setiap jalur penulisan: observation, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, replay jsonl, mesh sync, team share, output kompresi dan summary, crystal, dan node graph.
+
+
+Endpoint utama
+
+| Method | Path | Deskripsi |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (selalu publik) |
+| `GET` | `/agentmemory/status` | Apa yang salah dan cara memperbaikinya (HTML untuk browser, JSON lainnya) |
+| `GET` | `/agentmemory/viewer/snapshot` | Semua yang ditampilkan viewer, dalam satu respons |
+| `POST` | `/agentmemory/session/start` | Mulai sesi + dapatkan konteks |
+| `POST` | `/agentmemory/session/end` | Akhiri sesi |
+| `POST` | `/agentmemory/observe` | Menangkap observasi (lihat capture delivery di bawah) |
+| `GET` | `/agentmemory/capture` | Inbox capture, dead letter, dan spool offline |
+| `POST` | `/agentmemory/capture/retry` | Retry capture dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Kirim spool offline lokal sekarang |
+| `POST` | `/agentmemory/smart-search` | Search hybrid |
+| `POST` | `/agentmemory/context` | Membuat konteks |
+| `POST` | `/agentmemory/remember` | Simpan ke memori jangka panjang |
+| `POST` | `/agentmemory/forget` | Hapus observasi |
+| `POST` | `/agentmemory/enrich` | Konteks file + memori + bug |
+| `GET` | `/agentmemory/profile` | Profil proyek |
+| `GET` | `/agentmemory/export` | Ekspor semua data |
+| `POST` | `/agentmemory/import` | Import dari JSON |
+| `POST` | `/agentmemory/graph/query` | Query knowledge graph |
+| `POST` | `/agentmemory/graph/compact` | Memangkas provenance graph yang berlebihan ukuran |
+| `POST` | `/agentmemory/team/share` | Bagikan ke tim |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Daftar endpoint lengkap: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Pengiriman capture.** Hook mengirim setiap observasi sekali ke `POST /agentmemory/observe` dengan sebuah `eventId`. Ini adalah id milik host sendiri untuk panggilan itu saat payload-nya punya satu (misalnya `tool_use_id` milik Claude Code), atau hash dari sesi, tipe hook, nama tool, input, output, dan timestamp host jika tidak. Server menulis event itu ke inbox capture di state store, menyimpan observasinya, lalu menghapus entri inbox-nya. Status code-nya memberitahu apa yang terjadi:
+
+| Status | Field `status` | Makna |
+|---|---|---|
+| `201` | `accepted` | Tersimpan. `observationId` adalah observasi baru itu. |
+| `202` | `accepted` (`state: "retrying"`) | Diterima, tapi penyimpanannya gagal. Server me-retry-nya, juga setelah restart. |
+| `200` | `duplicate` | `eventId` ini sudah diterima sebelumnya. `observationId` adalah observasi yang sudah ada; tidak ada yang baru disimpan. |
+| `400` / `422` | `rejected` | Payload tidak valid, atau penyimpanannya gagal permanen (event disimpan sebagai dead letter). |
+| `503` | `rejected` (`retryable: true`) | Inbox penuh (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook men-spool event itu dan mengirimnya nanti. |
+
+Event yang gagal di-retry setiap `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 d) dengan backoff yang berlipat ganda, hingga `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Event yang masih gagal tetap di inbox sebagai dead letter, terdaftar di `/agentmemory/status` dan halaman Health viewer, dan bisa di-retry dengan `POST /agentmemory/capture/retry` (`{"eventId": "..."}` atau `{"all": true}`). Id event yang diterima diingat selama `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 jam, paling banyak `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), sehingga hook yang di-replay setelah timeout atau restart disimpan sekali, sementara dua tool call terpisah dengan id host masing-masing disimpan dua kali meski kontennya identik. Saat sebuah observasi dihapus (forget, delete sesi, eviction, auto-forget, atau import yang mengganti store), event-nya ditandai terhapus sebelum observasinya dihapus, sehingga replay event itu dalam window yang sama dijawab sebagai duplicate dan tidak menyimpan apa pun. State store menulis ke disk setiap 2 detik, sehingga event yang sudah dijawab bisa saja masih hanya ada di memori untuk sesaat. Untuk mengatasi itu, setiap jawaban `2xx` juga membawa `bootId` server (baru di setiap start), `acceptedAt`, dan `durableAfterMs` (interval save ditambah 1.5 d di file store, 1.5 d di redis, di mana persistensi adalah setelan operator). Hook menyimpan event itu di spool lokal sampai window itu berlalu dan menghapusnya pada panggilan berikutnya tanpa permintaan lain. Jika `bootId` sudah berubah pada saat itu, server telah restart, sehingga hook mengirim event itu lagi dengan `eventId` yang sama; event yang memang sudah mencapai disk tidak disimpan dua kali. Server juga mengirim event semacam itu sendiri saat start dan setiap interval retry, sehingga restart tidak kehilangan apa pun bahkan saat tidak ada hook yang berjalan setelahnya. Hook lama mengabaikan field tambahan itu, dan hook baru terhadap server lama membuang event itu pada `2xx` seperti sebelumnya.
+
+Saat server mati, tidak menjawab tepat waktu, atau mengembalikan 5xx, hook menambahkan observasi itu ke file spool lokal, `/capture-spool/-.jsonl` (ganti foldernya dengan `AGENTMEMORY_CAPTURE_SPOOL_DIR`). File itu privat untuk user Anda (mode 600), secret disamarkan dengan cara yang sama seperti server menyamarkannya, ia menampung paling banyak `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) dan membuang entri yang lebih tua dari `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Saat penuh, entri baru dibuang dan dihitung, dan `/agentmemory/status` melaporkannya. Hook tetap exit 0 dalam batas waktunya dan tidak menambah permintaan saat server sehat. Spool-nya dikirim pada start berikutnya dan oleh hook pertama yang menjangkau server lagi, dalam proses background sehingga agen tidak menunggu. Id event membuat ini aman: observasi yang memang tiba sebelum timeout tidak disimpan dua kali. `npx @agentmemory/agentmemory capture` menunjukkan spool dan inbox server, `--drain` mengirim spool itu sekarang, dan `GET /agentmemory/capture` mengembalikan hal yang sama sebagai JSON. Set `AGENTMEMORY_CAPTURE_SPOOL=false` untuk mematikan spool-nya.
+
+**Memadatkan provenance graph.** Setiap node dan edge knowledge graph menyimpan id dari 32 observasi terbaru asal-usulnya. Store yang ditulis sebelum batas itu bisa menyimpan ribuan id per node yang panas, yang membuat search graph dan viewer jadi lambat atau menjatuhkan worker-nya. agentmemory memperbaiki ini sendiri: pada start pertama setelah upgrade, ia memangkas setiap node, edge, edge yang disupersede (histori temporal graph), dan snapshot yang di-cache ke batas itu di background, dalam potongan kecil dengan jeda di antaranya, sehingga search, capture, dan viewer tetap bekerja. Ia menyimpan progresnya, melanjutkan setelah restart, dan tidak pernah berjalan lagi setelah selesai. `/agentmemory/status` dan halaman Health viewer menunjukkannya sebagai pending, running (dengan scope dan posisi saat ini), done, atau failed. Set `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` untuk mematikannya.
+
+Untuk menjalankannya secara manual, panggil `POST /agentmemory/graph/compact`. Ia menjelajahi index nama dan edge-key bukan mendaftar setiap node dan edge, dan aman untuk dijalankan ulang. Saat memangkas id, ia menulis entri audit `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Pada store yang besar, atau saat panggilannya mengembalikan 504, jalankan dalam potongan. Kirim `scope` (`nodes`, `edges`, atau `history`), `offset`, dan `limit`, lalu panggil lagi dengan `nextOffset` yang dikembalikan sampai nilainya `null`. Lakukan ini untuk `nodes`, `edges`, dan `history`, dan selesaikan dengan satu panggilan `{"scope":"snapshot"}`, karena run yang terpotong tidak menyentuh snapshot yang di-cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Prasyarat:** Node.js >= 20 dengan npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 atau Docker. Instalasi engine otomatis macOS/Linux juga membutuhkan `curl`, `sh` POSIX, dan `tar`; Windows native memakai `iii.exe` manual yang dipin, WSL2, atau Docker Desktop.
+
+
+
+ Il tuo agente di coding si ricorda tutto. Basta ri-spiegare tutto da capo.
+ Costruito su iii engine
+
+ Memoria persistente per Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualsiasi client MCP.
+
+ Il gist estende il pattern LLM Wiki di Karpathy con punteggio di confidenza, ciclo di vita, grafi di conoscenza e ricerca ibrida: agentmemory è l'implementazione.
+
+
+---
+
+## Installazione
+
+Requisiti:
+
+- Node.js 20 o più recente con npm e npx (`node -v`, `npm -v` e `npx -v`).
+- L'installazione automatica di iii-engine su macOS/Linux richiede anche `curl`, una `sh` POSIX e `tar`. Immagini minimali come `node:20-slim` potrebbero non includerli.
+- Windows nativo richiede l'installazione manuale della versione fissata di iii-engine v0.22.1 `iii.exe`. WSL2 o Docker Desktop sono le altre strade supportate.
+
+Comando canonico per l'installazione da zero:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+La prima esecuzione è una configurazione interattiva: scegli gli agenti da collegare (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), scegli un provider LLM oppure resta senza chiave (keyless), e il tool popola la configurazione, avvia il server di memoria e il suo iii engine fissato, e offre di installarlo globalmente così il comando nudo `agentmemory` funziona ovunque in seguito. `-y` accetta il prompt del pacchetto di npx e `@latest` evita una release obsoleta in cache. Un provider rende disponibili le funzionalità LLM, ma la compressione delle osservazioni scritta da un LLM si attiva solo quando è impostato anche `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+La modalità keyless disabilita gli embedding vettoriali. `memory_recall` (il percorso `mem::search`) usa BM25, mentre `memory_smart_search` può anche fondere corrispondenze strutturali del grafo quando i dati del grafo esistono già. Per il recall semantico gratuito on-device, imposta `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` e riavvia. La prima richiesta di embedding scarica `Xenova/all-MiniLM-L6-v2`; l'inferenza dopo quel primo download del modello viene eseguita localmente.
+
+Il runtime locale usa quattro porte: `3111` per REST/MCP HTTP, `3112` per gli stream iii, `3113` per il viewer e `49134` per il WebSocket del worker iii. Lo stato persistente di iii risiede in `~/Library/Application Support/agentmemory` su macOS, `$XDG_DATA_HOME/agentmemory` oppure `~/.local/share/agentmemory` su Linux, e `%APPDATA%\agentmemory` su Windows. Usa `--data-dir ` o `AGENTMEMORY_DATA_DIR` per sovrascriverlo, e riusa lo stesso valore a ogni riavvio. Per compatibilità con le versioni precedenti, un `./data/state_store.db` o `./data/iii-config.yaml` esistente ha precedenza sul percorso predefinito della piattaforma per l'istanza 0; un flag esplicito o una variabile d'ambiente prevalgono comunque.
+
+Poi verifica che il recall funzioni e dai al tuo agente le sue skill:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Le ricerche per parole chiave dovrebbero funzionare in modalità keyless predefinita tramite BM25. La query `database performance optimization` della demo è intenzionalmente semantica e può restituire zero risultati finché non è configurato un provider di embedding.
+
+Preferisci far fare tutto a un agente di coding? Dagli un'unica istruzione:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Collega altri agenti in qualsiasi momento con `agentmemory connect ` — 20 adapter elencati in [Funziona con qualsiasi agente](#works-with-every-agent). Riferimento completo dei comandi in [Avvio rapido](#quick-start).
+
+
+Windows
+
+La via più rapida è WSL2. La configurazione nativa del motore su Windows richiede che lo ZIP fissato v0.22.1 venga scaricato e `iii.exe` estratto manualmente; la CLI non lo estrae automaticamente. È supportato anche Docker Desktop. Vedi le [note su Windows](#windows) per la procedura passo-passo.
+
+
+
+
+Installazione globale / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Il comando npx sopra resta il percorso canonico per l'installazione da zero ed evita i problemi di permessi del prefisso globale.
+
+
+
+
+npx serve una versione vecchia
+
+npx mette in cache per versione. Forza l'ultima versione con `npx -y @agentmemory/agentmemory@latest`, oppure svuota la cache una volta con `rm -rf ~/.npm/_npx` (macOS/Linux; su Windows elimina `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Hai già un tuo iii engine in esecuzione
+
+agentmemory fissa iii-engine alla v0.22.1 e non si collegherà a una versione diversa (il worker non può parlare il protocollo di un altro engine). Arresta l'altro engine, poi esegui `npx -y @agentmemory/agentmemory@latest`. Installa ed esegue la versione fissata v0.22.1 in `~/.agentmemory/bin`, lasciando intatto il tuo `iii`.
+
+
+
+---
+
+
+
+agentmemory funziona con qualsiasi agente che supporti hook, MCP o API REST. Tutti gli agenti condividono lo stesso server di memoria.
+
+
+
+
+
+Claude Code
+plugin nativo + 12 hook + MCP
+
+
+
+Codex CLI
+plugin nativo + 6 hook + MCP
+
+
+
+GitHub Copilot CLI
+MCP + hook/skill del plugin
+
+
+
+Cursor
+plugin nativo + 7 hook + MCP
+
+
+
+OpenCode
+plugin di capture + MCP
+
+
+
+
+
+Devin
+6 hook + skill + MCP
+
+
+
+OpenClaw
+plugin nativo + MCP
+
+
+
+Hermes
+plugin nativo + MCP
+
+
+
+pi
+plugin nativo + MCP
+
+
+
+OpenHuman
+backend nativo del trait Memory
+
+
+
+
+
+Gemini CLI
+server MCP
+
+
+
+Antigravity
+MCP + hook
+
+
+
+Claude Desktop
+server MCP
+
+
+
+Warp
+connect + MCP + skill
+
+
+
+Zed
+server MCP
+
+
+
+
+
+Cline
+server MCP
+
+
+
+Continue
+server MCP
+
+
+
+Droid
+server MCP
+
+
+
+Kiro
+server MCP
+
+
+
+Qwen Code
+server MCP
+
+
+
+
+
+DeepSeek Harness
+server MCP
+
+
+
+Roo Code
+server MCP
+
+
+
+Kilo Code
+server MCP
+
+
+
+Goose
+server MCP
+
+
+
+Aider
+API REST
+
+
+
+
+
+ Funziona con qualsiasi agente che parli MCP o HTTP. Un solo server, memorie condivise tra tutti.
+
+
+---
+
+Spieghi la stessa architettura ogni sessione. Riscopri gli stessi bug. Ri-insegni le stesse preferenze. La memoria integrata (CLAUDE.md, .cursorrules) ha un limite di 200 righe e diventa obsoleta. agentmemory risolve questo problema. Catturi silenziosamente ciò che fa il tuo agente, lo comprimi in una memoria ricercabile e inietti il contesto giusto quando inizia la sessione successiva. Un solo comando. Funziona tra agenti diversi.
+
+**Cosa cambia:** Nella sessione 1 configuri l'autenticazione JWT. Nella sessione 2 chiedi il rate limiting. L'agente sa già che la tua autenticazione usa il middleware jose in `src/middleware/auth.ts`, che i tuoi test coprono la validazione dei token, e che hai scelto jose rispetto a jsonwebtoken per la compatibilità con Edge, senza bisogno di ri-spiegare nulla né di copiare e incollare.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Per impostazione predefinita, agentmemory salva lo stato di iii-engine fuori dal repository da cui lo avvii: `~/Library/Application Support/agentmemory` su macOS, `$XDG_DATA_HOME/agentmemory` oppure `~/.local/share/agentmemory` su Linux, e `%APPDATA%\agentmemory` su Windows. Un `./data/state_store.db` o `./data/iii-config.yaml` legacy esistente viene riutilizzato per l'istanza 0 prima di quel percorso predefinito della piattaforma. Per scegliere esplicitamente una posizione, passa `--data-dir ` oppure imposta `AGENTMEMORY_DATA_DIR`; entrambe le impostazioni esplicite hanno la precedenza sulla ricerca legacy:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Gli avvii nativi e Docker usano questa stessa directory host risolta; Docker la monta con bind in `/data`. `--instance 1` aggiunge `instance-1` alla directory risolta e seleziona il quartetto di porte predefinito separato `3211/3212/3213/49234`.
+
+Note sull'ultima release: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Precisione del retrieval
+
+**coding-agent-life-v1** (corpus interno, riproducibile in sandbox)
+
+| Adapter | P@5 | R@5 | Tasso di successo top-5 | latenza p50 |
+|---|---|---|---|---|
+| **agentmemory ibrido** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep di base | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+Tasso di successo top-5 del 100% al **limite matematico di P@5** per questo corpus (0.240, vedi scorecard). L'ibrido recupera ogni sessione gold; grep ne manca 1 su 2 nella query temporale multi-sessione. Il guadagno è su **recall + temporale**, non sulla precisione aggregata. Questo benchmark è piccolo e povero di dati gold; il più ampio LongMemEval-S sotto differenzia meglio. Analisi completa per tipo + nota di correzione: [`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 domande)
+
+| Sistema | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Fallback solo BM25 | 86.2% | 94.6% | 71.5% |
+
+
+
+> Modello di embedding: `all-MiniLM-L6-v2` (locale, gratuito, senza chiave API). Report completi: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Confronto con i concorrenti: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) che copre agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Riproducibile in locale:** [`eval/README.md`](../eval/README.md), un harness con adapter collegabili per LongMemEval `_s` (500 domande pubbliche) + `coding-agent-life-v1` (corpus interno di 15 sessioni). Gli adapter grep / vettoriale / agentmemory ottengono un punteggio fianco a fianco, output NDJSON, le scorecard pubblicate finiscono in [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Si combina con [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) e [Graphify](https://github.com/safishamsi/graphify).** Indicizzazione code-graph, pipeline di build multi-agente e grafi di conoscenza più ampi su documenti / PDF / immagini / video. agentmemory ricorda il lavoro; questi tre progetti illuminano il resto dello strato di contesto. Ricette + tabella di instradamento delle domande: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Integrata (CLAUDE.md)
+
+
+
Tipo
+
Motore di memoria + server MCP
+
API livello memoria
+
Runtime agente completo
+
IA personale
+
API memoria + app
+
Hub memoria di team (proxy LLM)
+
Memoria vettoriale (OSS)
+
Motore di memoria (Oracle DB)
+
Sistema di memoria
+
File statico
+
+
+
Retrieval R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/D
+
Auto-dichiarato
+
PersonaMem 76% (auto-dichiarato)
+
~96.6% (auto-dichiarato)
+
94.4% (auto-dichiarato)
+
N/D
+
N/D (grep)
+
+
+
Acquisizione automatica
+
12 hook (zero sforzo manuale)
+
Chiamate manuali add()
+
Auto-modifiche dell'agente
+
Manuale
+
Estrazione lato API
+
Intercettazione proxy (sostituzione base-URL)
+
Manuale
+
Estrazione API
+
Manuale
+
Modifica manuale
+
+
+
Ricerca
+
BM25 + vettoriale + grafo (fusione RRF)
+
Vettoriale + grafo
+
Vettoriale (archivio)
+
Semantica
+
Vettoriale + RAG
+
4 tipi di asset (Chat / Skill / Wiki / CodeGraph)
+
Solo vettoriale
+
Vettoriale + semantica
+
Pesata per decadimento
+
Carica tutto nel contesto
+
+
+
Multi-agente
+
MCP + REST + lease + segnali
+
API (nessun coordinamento)
+
Solo all'interno del runtime Letta
+
No
+
No
+
Ruoli di team + asset condivisi
+
No
+
Solo con ambito limitato
+
Condiviso multi-agente
+
File per agente
+
+
+
Vincolo al framework
+
Nessuno (qualsiasi client MCP)
+
Nessuno
+
Alto (deve usare Letta)
+
Autonomo
+
Nessuno
+
Il proxy intercetta ogni chiamata al modello
+
Nessuno
+
Oracle Database
+
Nessuno
+
Formato per agente
+
+
+
Dipendenze esterne
+
Nessuna (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + DB vettoriale
+
Multiple
+
Cloud gestito
+
Stack Docker (Core + Hub + Proxy)
+
Vector store
+
Oracle AI Database
+
Nessuna
+
Nessuna
+
+
+
Ciclo di vita della memoria
+
Consolidamento a 4 livelli + decadimento + auto-oblio
+
Estrazione passiva
+
Gestito dall'agente
+
Manuale
+
Auto-oblio
+
Revisione manuale; instradamento automatico in corso
+
Nessuno
+
Non dichiarato
+
Decadimento + consolidamento
+
Pulizia manuale
+
+
+
Efficienza dei token
+
~1,900 token/sessione ($10/anno)
+
Varia per integrazione
+
Memoria core nel contesto
+
Varia
+
Prezzo cloud
+
Non dichiarato
+
Nessun budget di token
+
Basato su LLM (varia)
+
Varia
+
22K+ token a 240 osservazioni
+
+
+
Viewer in tempo reale
+
Sì (porta 3113)
+
Dashboard cloud
+
Dashboard cloud
+
UI web
+
Dashboard cloud
+
UI web Hub
+
No
+
No
+
No
+
No
+
+
+
Self-hosted
+
Sì (predefinito)
+
Opzionale
+
Opzionale
+
Sì
+
No (solo cloud)
+
Sì (Docker)
+
Sì
+
Sì (Oracle DB)
+
Sì
+
Sì
+
+
+
+Nota sul benchmark: solo l'R@5 di agentmemory è un risultato misurato da noi (LongMemEval-S, riproducibile da benchmark/COMPARISON.md). I valori di mem0 e Letta sono i loro numeri pubblicati su LoCoMo (un dataset diverso); i valori di MemPalace, supermemory, TencentDB (PersonaMem) e oracleagentmemory sono dichiarazioni auto-riportate dai rispettivi fornitori che non abbiamo riprodotto in modo indipendente (l'esecuzione di oracleagentmemory ha usato GPT-5.5 contro un Oracle AI Database). Mostrati fianco a fianco solo per un confronto approssimativo, non un testa a testa su dati identici. I conteggi delle stelle sono approssimativi e cambiano nel tempo.
+
+**Nuovi arrivati** da conoscere, confrontati in profondità in [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Sistema | ⭐ | Approccio |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Grafo di conoscenza temporale; i risultati pubblicati più solidi sulle query temporali (LongMemEval 63.8%), ma il grafo si costruisce in modo asincrono quindi i fatti recenti possono essere in ritardo |
+| Cognee | 30K | Ingestione da documento a grafo di conoscenza, solo Python, costruito per l'estrazione strutturata di entità più che per l'acquisizione di sessioni |
+
+Nessuno di questi acquisisce automaticamente dagli hook degli agenti di coding, offre un viewer local-first, o funziona senza chiave — la combinazione su cui è costruito agentmemory.
+
+---
+
+
+
+Compatibilità: questa release ha come target `iii-sdk` 0.22.1 e fissa iii-engine alla v0.22.1.
+
+### Provalo in 30 secondi
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` crea 3 sessioni realistiche (autenticazione JWT, fix di una query N+1, rate limiting) ed esegue ricerche su di esse. Le installazioni keyless disabilitano i vettori, quindi le query per parole chiave `mem::search` dovrebbero funzionare tramite BM25 mentre `database performance optimization` può restituire zero risultati. `smart-search` può inoltre restituire corrispondenze strutturali del grafo quando i dati del grafo esistono. Per far trovare alla query semantica il fix dell'N+1 tramite i vettori, imposta `EMBEDDING_PROVIDER=local`, riavvia e lascia completare il primo download del modello.
+
+Apri `http://localhost:3113` per osservare la memoria costruirsi in tempo reale.
+
+### Valida un'installazione nuova e la persistenza al riavvio
+
+Con il server in esecuzione, valida REST, health, il viewer e lo stato del runtime basato su iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Il pannello di avvio pronto considera tutte e quattro le porte: REST/MCP HTTP sulla 3111, stream iii sulla 3112, il viewer sulla 3113 e il WebSocket del worker iii sulla 49134. `status` confirma lo stato di salute di agentmemory e il provider/modalità di embedding attivo. Salva una sonda e verifica che sia ricercabile:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Poi esegui `npx -y @agentmemory/agentmemory@latest stop`, riavvia il comando canonico nel Terminal 1, attendi `/agentmemory/livez` e ripeti la ricerca. La sonda deve essere ancora restituita. Se hai scelto un `--data-dir` personalizzato, passa la stessa directory al riavvio.
+
+### Comandi quotidiani
+
+Installazione e configurazione sono descritte in [Installazione](#install) sopra (la prima esecuzione ti guida passo passo). Quotidianamente:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Replay delle sessioni
+
+Ogni sessione registrata da agentmemory è riproducibile (replay). Apri il viewer, scegli la tab **Replay** e scorri la timeline: prompt, chiamate agli strumenti, risultati degli strumenti e risposte vengono renderizzati come eventi discreti con play/pause, controllo della velocità (da 0.5x a 4x) e scorciatoie da tastiera (spazio per attivare/disattivare, le freccie per avanzare passo passo).
+
+Per importare transcript JSONL più vecchi di Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Le sessioni importate appaiono nel selettore Replay insieme a quelle native. Dietro le quinte ogni voce passa attraverso le funzioni iii `mem::replay::load`, `mem::replay::sessions` e `mem::replay::import-jsonl`, senza server a canale laterale. Ogni transcript importato viene indicizzato per la ricerca, marcato con il canale di origine `import` ed elaborato per produrre un cristallo di sessione e delle lezioni.
+
+> **Attenzione se usi `import-jsonl` come percorso di acquisizione principale:** `cleanupPeriodDays` di Claude Code (in `~/.claude/settings.json`, predefinito **30**) elimina automaticamente i transcript JSONL più vecchi di quella finestra da `~/.claude/projects/`. Se installi agentmemory su una cronologia di Claude Code vecchia di mesi, tutto ciò che ha più di 30 giorni è già sparito prima della prima importazione. Puoi eseguire `import-jsonl` tramite cron, aumentare `cleanupPeriodDays` a un valore più alto, oppure collegare gli hook di acquisizione automatica (il percorso di installazione predefinito del plugin) così che ogni turno finisca in agentmemory mentre la sessione è ancora attiva e la pulizia dei JSONL non sia più un problema.
+
+### Aggiornamento / Manutenzione
+
+Usa il comando di manutenzione quando vuoi intenzionalmente aggiornare il tuo runtime locale:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Attenzione: questo comando modifica il workspace/runtime corrente. Può aggiornare le dipendenze JavaScript e scaricare l'immagine Docker fissata `iiidev/iii:0.22.1`. Non installa mai un iii engine non fissato o più recente.
+
+I dettagli implementativi si trovano in `src/cli.ts` (vedi `runUpgrade` nella regione `src/cli.ts:544-595`).
+
+### Claude Code (un blocco, incollalo)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code senza l'installazione del plugin (percorso MCP standalone)
+
+Se collegi il server MCP di agentmemory tramite `~/.claude.json` direttamente invece di usare `/plugin install`, Claude Code non risolve mai `${CLAUDE_PLUGIN_ROOT}` e devi puntare gli script degli hook a percorsi assoluti in `~/.claude/settings.json`. Questi percorsi di solito incorporano la versione di agentmemory (ad es. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), quindi il prossimo aggiornamento rompe silenziosamente ogni hook.
+
+Soluzione alternativa:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Questo unisce gli stessi comandi degli hook in `~/.claude/settings.json` con percorsi assoluti risolti verso la directory `plugin/` incorporata nel pacchetto `@agentmemory/agentmemory` attualmente installato. Riesegui il comando dopo aver aggiornato agentmemory per aggiornare i percorsi. Le voci dell'utente nello stesso file vengono preservate; vengono sostituite solo le voci precedenti di agentmemory. Usare il percorso `/plugin install` resta l'approccio consigliato.
+Per deployment remoti o protetti, avvia Claude Code con `AGENTMEMORY_URL` e `AGENTMEMORY_SECRET` impostati. Il plugin passa entrambi i valori al suo server MCP incorporato; quando `AGENTMEMORY_URL` è vuoto, lo shim MCP usa `http://localhost:3111`.
+
+### Codex CLI (piattaforma plugin di Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Il plugin Codex viene distribuito dalla stessa directory `plugin/` del plugin Claude Code. Registra:
+
+- Un bridge MCP via stdio incorporato per il daemon in esecuzione, senza download npm né archivio di fallback. Consulta la [guida locale di Codex](../docs/plugins/codex-local.md) per testare una build non ancora rilasciata.
+- 6 hook del ciclo di vita: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skill invocabili: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, più 8 skill di riferimento che l'agente carica su richiesta (disciplina della memoria, strumenti MCP, API REST, configurazione, agenti, hook, architettura, e la guida alla scrittura delle skill)
+
+Il motore degli hook di Codex inietta `CLAUDE_PLUGIN_ROOT` nei sottoprocessi degli hook (vedi [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), quindi gli stessi script degli hook funzionano su entrambi gli host senza duplicazione. Gli eventi Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure sono esclusivi di Claude Code e non vengono registrati per Codex.
+
+#### Fiducia e compatibilità degli hook di Codex
+
+L'invio nativo degli hook del plugin è verificato con Codex CLI 0.150.1. Fidati degli hook del plugin prima di aspettarti l'acquisizione. Il comportamento su Desktop dipende dal suo runtime incorporato; controlla `/hooks` e conferma un evento acquisito prima di abilitare una soluzione alternativa.
+
+Se il tuo host richiede hook globali, rispecchia i comandi in `~/.codex/hooks.json`. Quando l'MCP è già configurato, il connettore attuale richiede `--force` per raggiungere l'installazione degli hook:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Questo unisce gli hook globali e riscrive la voce MCP di agentmemory, preservando le voci non correlate. Rivedi eventuali impostazioni personalizzate dell'endpoint di agentmemory prima di usare `--force`. Riesegui dopo l'aggiornamento per aggiornare i percorsi degli script. Abilita gli hook nativi del plugin oppure le copie globali per evitare l'acquisizione duplicata.
+
+### GitHub Copilot CLI
+
+Per la modalità agente di VS Code, usa la [guida MCP e acquisizione automatica di Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Il connettore CLI non configura VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` unisce `mcpServers.agentmemory` in `~/.copilot/mcp-config.json` (o `$COPILOT_HOME/mcp-config.json` quando `COPILOT_HOME` è impostato) e preserva i server esistenti. Su Windows nativo questo è l'unico adapter `connect` automatizzato; configura manualmente ogni altro agente Windows nativo. `connect` in WSL è adatto solo quando l'agente target è installato nel medesimo ambiente WSL. Copilot recepisce il server MCP al prossimo avvio o dopo `/mcp`. Installa anche il plugin quando vuoi l'esperienza completa di hook/skill.
+
+
+OpenClaw (incolla questo prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Guida completa: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (incolla questo prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Guida completa: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Altri agenti
+
+Avvia il server di memoria: `npx -y @agentmemory/agentmemory@latest`
+
+#### Skill native tramite `npx skills add` (50+ agenti)
+
+agentmemory distribuisce 17 skill nel formato `/SKILL.md` in stile Claude Code: 9 skill d'azione invocabili (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) e 8 skill di riferimento che l'agente carica su richiesta (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Le skill di riferimento portano tabelle di dati generate dalla fonte, quindi non diventano mai obsolete. La CLI [`skills`](https://npmjs.com/package/skills) di vercel-labs le installa automaticamente nella directory delle skill native dell'agente chiamante su 50+ agenti (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, e altri):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Questo è **complementare** a `agentmemory connect `:
+
+- `agentmemory connect ` scrive la configurazione del server MCP così gli strumenti diventano disponibili.
+- `npx skills add rohitg00/agentmemory` installa le skill così l'agente sa quando chiamarle.
+
+Per i pochi agenti che la CLI skills non copre ancora (Zed v1.3.x e versioni precedenti), copia tu stesso i 17 file SKILL.md nella directory delle skill native dell'agente; lo stesso formato funziona ovunque.
+
+#### Blocco MCP standard
+
+La voce agentmemory è lo **stesso blocco server MCP** su ogni host che usa la forma `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Unisci questa voce nell'oggetto `mcpServers` esistente** nel file di configurazione dell'host; non sostituire il file. Se il file ha già altri server, aggiungi `agentmemory` accanto a loro come un'altra chiave dentro `mcpServers`. Se `mcpServers` manca del tutto, incolla il blocco dentro `{ "mcpServers": { ... } }`. I placeholder `${VAR}` ereditano `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` dalla shell all'avvio del server MCP; le variabili non impostate passano stringhe vuote e lo shim ricade su `http://localhost:3111`. Una singola voce collegata copre sia i deployment locali che quelli remoti (k8s / dietro reverse-proxy).
+
+| Agente | File di configurazione | Note |
+|---|---|---|
+| **Cursor (solo MCP)** | `~/.cursor/mcp.json` | Unisci in `mcpServers`, oppure `agentmemory connect cursor`. Disponibile anche un deeplink one-click sul sito web. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Elenco nel Cursor Marketplace (candidatura in revisione) oppure Cursor Settings → Plugins → checkout locale. Registra 7 hook di acquisizione automatica (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + il server MCP, con `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` gestiti nella dashboard del plugin di Cursor. Funziona nell'IDE Cursor e nella CLI `cursor-agent`; i prompt in modalità print della CLI vengono ricostruiti a posteriori dal transcript della sessione alla fine della sessione. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Unisci in `mcpServers`. Riavvia Claude Desktop dopo la modifica. |
+| **Cline / Roo Code / Kilo Code** | Impostazioni MCP di Cline (Settings UI → MCP Servers → Edit) | Stesso blocco `mcpServers`. |
+| **Devin CLI (MCP + hook)** | `~/.config/devin/config.json` | `agentmemory connect devin` unisce la voce MCP; `--with-hooks` aggiunge sei hook nativi di acquisizione automatica (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) con i matcher di strumenti in minuscolo di Devin. Verifica con `devin mcp list` e `/hooks` dentro devin. |
+| **Devin CLI (plugin completo)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` da un checkout registra tutte le 17 skill come slash command `/agentmemory:` più il server MCP. Gli hook del plugin di Devin non possono far scattare `SessionStart`/`SessionEnd`, quindi abbinalo a `connect devin --with-hooks` per una cattura completa della sessione. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Aggiungi un MCP personalizzato (STDIO): comando `npx`, argomenti `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` che punta a un deployment agentmemory raggiungibile in rete più `AGENTMEMORY_SECRET` (le sessioni cloud non possono raggiungere localhost — vedi [`deploy/`](../deploy/)). Salva il secret in Devin Secrets, poi usa "Test listing tools" per verificare che tutti i 54 strumenti appaiano. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (unisce automaticamente). |
+| **GitHub Copilot CLI (solo MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` unisce `mcpServers.agentmemory`; Copilot lo recepisce al prossimo avvio o con `/mcp`. |
+| **GitHub Copilot CLI (plugin completo)** | Installazione plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` per il plugin dalla sottodirectory GitHub. |
+| **OpenClaw** | Configurazione MCP di OpenClaw | Stesso blocco `mcpServers`. Più in profondità: `openclaw plugins install ./integrations/openclaw` rivendica lo slot di memoria di OpenClaw (passa automaticamente da `memory-core`); imposta `plugins.entries.agentmemory.hooks.allowConversationAccess=true` altrimenti la cattura del turno viene bloccata silenziosamente. Vedi [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (solo MCP)** | `.codex/config.toml` | Forma TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, oppure aggiungi `[mcp_servers.agentmemory]` manualmente. |
+| **Codex CLI (plugin completo)** | Marketplace plugin di Codex | `codex plugin marketplace add rohitg00/agentmemory` poi `codex plugin add agentmemory@agentmemory`. Registra MCP + 6 hook del ciclo di vita + 17 skill. Fidati degli hook e verifica l'acquisizione nel tuo host; consulta [configurazione e validazione di Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (solo MCP)** | `opencode.json` | Forma diversa: chiave di primo livello `mcp`, comando come array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin completo)** | `plugin/opencode/` | 22 hook di acquisizione automatica che coprono il ciclo di vita della sessione, i messaggi, gli strumenti, gli errori. L'attribuzione del progetto è per sessione, quindi un singolo processo OpenCode che abbraccia più repository registra ogni sessione sotto il proprio progetto. Due slash command (`/recall`, `/remember`). Copia `plugin/opencode/` nel tuo workspace OpenCode e aggiungi la voce del plugin a `opencode.json`. Vedi [`plugin/opencode/README.md`](../plugin/opencode/README.md) per la tabella completa degli hook + l'analisi delle lacune. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installa l'estensione incorporata nella directory di auto-discovery di pi (recall all'avvio dell'agente, cattura alla fine dell'agente, strumenti `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` in un pi in esecuzione lo recepisce. [`integrations/pi`](../integrations/pi/) è anche un pacchetto pi (`pi install ./integrations/pi` da un checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` fornisce il provider di memoria a 6 hook (prefetch, cattura del turno, fine sessione, pre-compressione, mirroring di MEMORY.md, blocco del system prompt). Valida con `hermes plugins doctor` e `hermes memory status`. Vedi [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` scrive il blocco standard `mcpServers`. Il payload degli hook è compatibile a livello di campi con Claude Code, quindi gli script esistenti dei 12 hook funzionano senza modifiche; collegali tramite la sezione `hooks` nello stesso `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installa l'MCP e gli hook di acquisizione nella directory di personalizzazione condivisa. Consulta [configurazione e limiti di Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` usa la stessa configurazione MCP e hook delle versioni IDE attuali. Le installazioni esistenti dovrebbero aggiornare con `--force`; consulta le [note di aggiornamento](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` scrive la configurazione a livello utente. Gli override per workspace vanno in `.kiro/settings/mcp.json` accanto al tuo codice. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` scrive il blocco standard `mcpServers`. Warp rileva automaticamente anche le skill da `.claude/skills/`; una volta installato il plugin Claude Code, le 8 skill di agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) appaiono nativamente nella palette slash-command di Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` scrive il blocco standard `mcpServers`. Utenti dell'estensione VS Code: incolla lo stesso blocco tramite Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferito) o `config.json` (legacy) | `agentmemory connect continue` crea `config.yaml` da zero quando nessuno dei due esiste, oppure modifica il `config.json` esistente. **Se hai già `config.yaml`** l'adapter stampa il blocco esatto da incollare sotto `mcpServers:`; non riscrive silenziosamente il tuo yaml perché preservare commenti e anchor in modo sicuro richiede un parser YAML che il pacchetto non include. Continue usa la forma array (non oggetto) per `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` scrive sotto `context_servers` (la chiave di Zed, NON `mcpServers`). I server MCP remoti possono essere collegati tramite `{"url": "..."}` invece. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` scrive il blocco standard `mcpServers`. Gli override a livello di progetto vanno in `/.factory/mcp.json`. Passa `--with-hooks` per l'acquisizione automatica nativa. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` aggiunge una riga `@deepseek-ai/dsh-mcp-client` al livello di patch a livello home che ogni profilo Harness carica; gli strumenti si registrano come `mcp__agentmemory__*`. Passa `--with-hooks` per collegare anche l'acquisizione automatica: gli script degli hook incorporati di Claude Code funzionano tramite il bridge nativo `@deepseek-ai/dsh-hooks-claude-code` di Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) tramite un manifesto scritto in `$DSH_HOME/agentmemory.hooks.json`. Il default è `~/.dsh` quando `DSH_HOME` non è impostato. |
+| **Goose** | UI delle impostazioni MCP di Goose | Stesso blocco `mcpServers`; usa `goose configure` → Add Extension → MCP. La modifica diretta del YAML in `~/.config/goose/config.yaml` è supportata ma lo schema usa `extensions:` + `cmd` (non `mcpServers:` + `command`). |
+| **Aider** | n/d | Parla direttamente con l'API REST: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Qualsiasi agente (32+)** | n/d | `npx skillkit install agentmemory` rileva automaticamente l'host e unisce la configurazione. |
+
+**Client MCP in sandbox** (Flatpak / Snap / container restrittivi) che non possono raggiungere il `localhost` dell'host: imposta anche `"AGENTMEMORY_FORCE_PROXY": "1"` nel blocco `env`, e punta `AGENTMEMORY_URL` verso una rotta che la sandbox possa effettivamente raggiungere (ad es. il tuo IP LAN).
+
+### Accesso programmatico (Python / Rust / Node)
+
+agentmemory registra le sue operazioni core come funzioni iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Qualsiasi linguaggio con un SDK iii può chiamarle direttamente su `ws://localhost:49134`, senza bisogno di un client REST separato per ogni linguaggio.
+
+```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"},
+})
+```
+
+Esempio completo: [`examples/python/`](../examples/python/) (avvio rapido + flusso di osservazione/recall). REST sulla `:3111` resta disponibile per host senza un runtime iii.
+
+### Dal codice sorgente
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Questo avvia agentmemory con un `iii-engine` locale se il binario fissato è già installato, oppure usa Docker Compose quando selezionato. REST, stream e il viewer si collegano a `127.0.0.1` per impostazione predefinita. Il percorso automatico del binario per macOS/Linux richiede `curl`, una `sh` POSIX e `tar`.
+
+Installa `iii-engine` manualmente. **agentmemory al momento fissa `iii-engine` alla `v0.22.1`**, la stessa release della sua dipendenza `iii-sdk`; il worker parla il protocollo wire di quell'engine, e la 0.20.0 ha riorganizzato la superficie dell'SDK, quindi le due si muovono insieme nelle release di agentmemory. Sovrascrivi con `AGENTMEMORY_III_VERSION=` se esegui il tuo engine e sai che corrisponde.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** sostituisci `aarch64-apple-darwin` con `x86_64-apple-darwin`
+- **Linux x64:** sostituisci con `x86_64-unknown-linux-gnu`
+- **Linux arm64:** sostituisci con `aarch64-unknown-linux-gnu`
+- **Windows:** scarica `iii-x86_64-pc-windows-msvc.zip` da [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) ed estrai `iii.exe` in `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Ogni archivio ha un file `.sha256` corrispondente sulla pagina della release; quando cambi piattaforma, usa l'hash di quel file nella verifica sopra (su Windows: `Get-FileHash`). L'installer automatico in `npx @agentmemory/agentmemory` fissa questi hash e rifiuta un archivio che non corrisponde.
+
+Oppure usa Docker (il `docker-compose.yml` incluso scarica `iiidev/iii:0.22.1`). Documentazione completa: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory funziona su Windows 10/11, ma il pacchetto Node.js da solo non basta; serve anche il runtime fissato di iii-engine v0.22.1 come processo in background. La CLI non estrae automaticamente lo ZIP Windows, quindi gli utenti Windows nativi devono installare `iii.exe` manualmente, usare WSL2 oppure scegliere Docker Desktop.
+
+Il collegamento MCP automatizzato su Windows nativo supporta solo `agentmemory connect copilot-cli`. Per Claude Code, Codex, Cursor e ogni altro agente Windows nativo, copia il blocco MCP manuale da [Altri agenti](#other-agents) nella configurazione Windows di quell'agente. Eseguire `connect` in WSL è appropriato solo quando l'agente target è installato anche in quello stesso ambiente WSL; non modifica la configurazione di un agente ospitato su Windows.
+
+**Opzione A: binario Windows precompilato (consigliata)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opzione B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opzione C: solo MCP standalone (nessun engine).** Se ti serve solo gli strumenti MCP per il tuo agente e non hai bisogno dell'API REST, del viewer o dei cron job, salta del tutto l'engine:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostica per Windows:** se `npx -y @agentmemory/agentmemory@latest` fallisce, riesegui con `--verbose` per vedere lo stderr effettivo dell'engine. Modalità di errore comuni:
+
+| Sintomo | Soluzione |
+|---|---|
+| `The engine process started but the REST API never responded.` | Verifica che tutte le quattro porte derivate siano libere, controlla che il `iii.exe` fissato sia rimasto attivo, poi riesegui con `--verbose` e ispeziona lo stderr catturato dell'engine |
+| `Could not start iii-engine` | Né `iii.exe` né Docker sono installati. Vedi l'Opzione A o B sopra |
+| Conflitto di porta | `netstat -ano \| findstr :3111` per vedere cosa è collegato, poi terminalo o usa `--port ` |
+| Fallback a Docker saltato anche se Docker è installato | Assicurati che Docker Desktop sia effettivamente in esecuzione (icona nella system tray) |
+
+> Nota: l'**engine** iii è un binario precompilato, non un crate cargo, quindi non provare a farci `cargo install`. (Gli **SDK** iii sono pubblicati su crates.io, npm e PyPI, ma agentmemory non ne ha bisogno.) I metodi di installazione dell'engine supportati sono tutti fissati alla v0.22.1: il binario precompilato sopra, il percorso di installazione automatica di agentmemory per macOS/Linux (richiede `curl`, `sh` POSIX e `tar`), e l'immagine Docker `iiidev/iii:0.22.1`. Un `install.sh | sh` upstream nudo installa l'ultimo engine, che agentmemory non supporta. Usa `npx -y @agentmemory/agentmemory@latest`; su macOS/Linux scarica l'engine fissato in `~/.agentmemory/bin`.
+
+---
+
+
Deploy
+
+Template one-click per host gestiti. Ognuno distribuisce un
+Dockerfile autosufficiente che scarica `@agentmemory/agentmemory` da npm e copia
+il binario dell'engine iii dall'immagine Docker Hub ufficiale `iiidev/iii`;
+non è richiesta nessuna immagine agentmemory precostruita. Lo storage persistente
+viene montato su `/data`; l'entrypoint del primo avvio sovrascrive
+la configurazione iii inclusa in npm (che si collega a `127.0.0.1`) con una
+ottimizzata per il deploy che si collega a `0.0.0.0` e usa percorsi `/data`
+assoluti, genera il secret HMAC, poi abbandona i privilegi da
+`root` a `node` tramite `gosu` prima di eseguire la CLI di agentmemory.
+
+
+
+
+
+
+Il pulsante di deploy one-click di Render richiede `render.yaml` nella radice del repository, che manteniamo deliberatamente puro. Usa il flusso Render Blueprint documentato in [`deploy/render/`](.././deploy/render/README.md) per puntare manualmente al blueprint nel repository.
+
+I dettagli completi di configurazione (acquisizione HMAC, tunnel SSH per il viewer, rotazione, backup,
+costi minimi) si trovano in [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): macchina singola con
+ `auto_stop_machines = "stop"`; il minimo costo a riposo.
+- [`deploy/railway`](.././deploy/railway/README.md): tariffa fissa del piano Hobby,
+ volume nella dashboard.
+- [`deploy/render`](.././deploy/render/README.md): flusso Blueprint,
+ snapshot automatici del disco sui piani a pagamento.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted sul tuo
+ VPS tramite [Coolify](https://coolify.io/self-hosted); stesso stack Docker
+ Compose, tu possiedi l'host e i dati.
+
+È pubblicata solo la porta `3111`. Il viewer sulla `3113` resta collegato a
+loopback dentro il container; il README di ogni template documenta il
+pattern del tunnel SSH per raggiungerlo.
+
+---
+
+
+
+Ogni agente di coding scorda tutto quando la sessione finisce, e ogni nuova sessione inizia con te che ri-spieghi il tuo stack. agentmemory funziona in background e elimina questo passaggio.
+
+```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 la memoria integrata degli agenti
+
+Ogni agente di coding AI ha una memoria integrata: Claude Code ha `MEMORY.md`, Cursor ha i notepad, Cline ha la memory bank. Funzionano come post-it. agentmemory è il database ricercabile dietro i post-it.
+
+| | Integrata (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Scala | Limite di 200 righe | Illimitata |
+| Ricerca | Carica tutto nel contesto | BM25 + vettoriale + grafo (solo top-K) |
+| Costo in token | 22K+ a 240 osservazioni | ~1,900 token (92% in meno) |
+| Cross-agente | File per agente | MCP + REST (qualsiasi agente) |
+| Coordinamento | Nessuno | Lease, segnali, azioni, routine |
+| Osservabilità | Lettura manuale dei file | Viewer in tempo reale su :3113 |
+
+---
+
+
+
+### Pipeline della memoria
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### Consolidamento della memoria a 4 livelli
+
+Modellato su come i cervelli umani elaborano la memoria, incluso il consolidamento durante il sonno.
+
+| Livello | Cosa | Analogia |
+|------|------|---------|
+| **Working** | Osservazioni grezze dall'uso degli strumenti | Memoria a breve termine |
+| **Episodic** | Riassunti compressi delle sessioni | "Cosa è successo" |
+| **Semantic** | Fatti e pattern estratti | "Cosa so" |
+| **Procedural** | Flussi di lavoro e pattern decisionali | "Come farlo" |
+
+Le memorie decadono nel tempo (curva di Ebbinghaus). Le memorie accedute frequentemente si rafforzano. Le memorie obsolete vengono eliminate automaticamente. Le contraddizioni vengono rilevate e risolte.
+
+### Cosa viene catturato
+
+| Hook | Catture |
+|------|----------|
+| `SessionStart` | Percorso del progetto, ID sessione |
+| `UserPromptSubmit` | Prompt dell'utente (filtrati per privacy) |
+| `PreToolUse` | Pattern di accesso ai file + contesto arricchito |
+| `PostToolUse` | Nome dello strumento, input, output |
+| `PostToolUseFailure` | Contesto dell'errore |
+| `PreCompact` | Reinietta la memoria prima della compattazione |
+| `SubagentStart/Stop` | Ciclo di vita dei sub-agenti |
+| `Stop` | Riassunto di fine sessione |
+| `SessionEnd` | Marcatore di sessione completata |
+
+### Capacità principali
+
+| Capacità | Descrizione |
+|---|---|
+| **Acquisizione automatica** | Ogni uso di strumento registrato tramite hook, nessuno sforzo manuale |
+| **Ricerca semantica** | BM25 + vettoriale + grafo di conoscenza con fusione RRF |
+| **Evoluzione della memoria** | Versionamento, supersessione, grafi di relazioni |
+| **Igiene del recall** | Le versioni superate della memoria escono dagli indici di ricerca; la catena delle versioni nel KV conserva la storia completa |
+| **Suggerimenti di quasi-duplicati** | I salvataggi segnalano un match consultivo `similarTo` quando un nuovo contenuto assomiglia molto a una memoria esistente |
+| **Scoping per agente** | `agentId` attraversa salvataggio e recall su REST, MCP e l'indice di ricerca, in modalità condivisa o isolata |
+| **Provenienza al momento della scrittura** | Ogni osservazione e memoria porta un canale di origine immutabile (user, agent, tool, import o shared) impresso al momento della cattura, del salvataggio e dell'importazione |
+| **Auto-oblio** | Scadenza TTL, rilevamento di contraddizioni, eliminazione per importanza |
+| **Privacy prima di tutto** | Chiavi API, segreti, tag `` rimossi prima della memorizzazione |
+| **Auto-guarigione** | Circuit breaker, catena di fallback dei provider, monitoraggio della salute |
+| **Bridge Claude** | Sincronizzazione bidirezionale con MEMORY.md |
+| **Grafo di conoscenza** | Estrazione di entità + attraversamento BFS |
+| **Memoria di team** | Condivisa e privata con namespace tra i membri del team |
+| **Provenienza delle citazioni** | Risali da qualsiasi memoria alle osservazioni di origine |
+| **Snapshot Git** | Versiona, ripristina e confronta lo stato della memoria |
+
+---
+
+
+
+Recupero a triplo flusso che combina tre segnali:
+
+| Flusso | Cosa fa | Quando |
+|---|---|---|
+| **BM25** | Corrispondenza di parole chiave con stemming ed espansione di sinonimi | Sempre attivo |
+| **Vettoriale** | Similarità coseno su embedding densi | Provider di embedding configurato |
+| **Grafo** | Attraversamento del grafo di conoscenza tramite corrispondenza di entità | Entità rilevate nella query |
+
+Fuso con Reciprocal Rank Fusion (RRF, k=60) e diversificato per sessione (massimo 3 risultati per sessione).
+
+Quando un indice vettoriale è popolato, `mem::search` (dietro `memory_recall`) usa il ranker ibrido BM25 + vettoriale. Senza embedding usa BM25. `smart-search` può inoltre fondere corrispondenze strutturali del grafo quando i dati del grafo esistono, anche in modalità keyless. Il recall delle lezioni funziona su un indice BM25 dedicato in memoria invece di scansionare l'intero corpus per ogni query. Le versioni superate della memoria sono escluse da ogni percorso di recall; la catena delle versioni conserva la loro storia.
+
+I vettori sopravvivono a un crash o a un force-kill. L'indice vettoriale viene salvato a blocchi almeno ogni `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minuti). Ogni vettore aggiunto o rimosso nel frattempo viene anche scritto immediatamente in un piccolo log in sospeso nello state store, e il prossimo avvio lo riapplica senza chiamare il provider di embedding. Ogni salvataggio riuscito svuota il log. I documenti che restano senza vettore dopo la riapplicazione vengono ri-embeddati in background a lotti di `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) finché non ne resta nessuno, e un backfill interrotto riprende al prossimo avvio. `/agentmemory/status` e il viewer mostrano la dimensione del log in sospeso e lo stato del backfill. Le installazioni keyless non scrivono nulla.
+
+BM25 tokenizza nativamente greco, cirillico, ebraico, arabo e latino accentato. Per le memorie in cinese / giapponese / coreano, installa i segmentatori opzionali (`npm install @node-rs/jieba tiny-segmenter`) per dividere le sequenze CJK in token a livello di parola; senza di essi, agentmemory ricade in modo graduale sulla tokenizzazione dell'intera sequenza e stampa un suggerimento una tantum su stderr.
+
+### Provider di embedding
+
+Le installazioni keyless disabilitano gli embedding vettoriali: `mem::search` usa BM25, mentre `smart-search` può anche usare i dati strutturali esistenti del grafo. Per attivare gli embedding semantici gratuiti on-device, aggiungi questo a `~/.agentmemory/.env` e riavvia agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+L'installazione npm normale include il runtime opzionale `@huggingface/transformers`. La prima richiesta di embedding scarica `Xenova/all-MiniLM-L6-v2`, quindi serve l'accesso alla rete e può richiedere più tempo; l'inferenza successiva viene eseguita on-device. I provider remoti vengono rilevati automaticamente dalle loro chiavi a meno che `EMBEDDING_PROVIDER` non le sovrascriva.
+
+| Provider | Modello | Costo | Note |
+|---|---|---|---|
+| **Locale (consigliato come opt-in)** | `all-MiniLM-L6-v2` | Gratuito | On-device dopo il primo download del modello, +8pp di recall rispetto a solo BM25 |
+| Gemini | `gemini-embedding-001` | Livello gratuito | 100+ lingue, 768/1536/3072 dimensioni (MRL), input di 2048 token. Sostituisce `text-embedding-004` ([deprecato, spegnimento il 14 gennaio 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Qualità più alta |
+| Voyage AI | `voyage-code-3` | A pagamento | Ottimizzato per il codice |
+| Cohere | `embed-english-v3.0` | Prova gratuita | Uso generale |
+| OpenRouter | Qualsiasi modello | Variabile | Proxy multi-modello |
+
+---
+
+
+
+54 strumenti, 6 risorse, 3 prompt e 17 skill.
+
+> **Shim MCP vs server completo:** il pacchetto pubblicato `@agentmemory/mcp` è uno shim leggero. Espone la superficie completa di 54 strumenti **solo quando può raggiungere un server agentmemory in esecuzione** tramite `AGENTMEMORY_URL` (modalità proxy). Senza un server raggiungibile, lo shim ricade su un set locale di 7 strumenti (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). La variabile d'ambiente `AGENTMEMORY_TOOLS=core|all` è un flag *lato server*; impostarla nel blocco `env` dello shim non ha alcun effetto. Se vedi solo 7 strumenti in Cursor / OpenCode / Gemini CLI, avvia `npx -y @agentmemory/agentmemory@latest` (o lo stack Docker) e imposta `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 strumenti
+
+Tre superfici di strumenti, dalla più piccola alla più grande: `AGENTMEMORY_TOOLS=core` riduce la visibilità a 8 strumenti essenziali (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); il set base sotto è composto dai 14 strumenti fondamentali del registro; il predefinito (`AGENTMEMORY_TOOLS=all`) espone tutti i 54.
+
+
+Strumenti base (14)
+
+| Strumento | Descrizione |
+|------|-------------|
+| `memory_recall` | Cerca osservazioni passate |
+| `memory_compress_file` | Comprime file markdown preservando la struttura |
+| `memory_save` | Salva un'intuizione, una decisione o un pattern |
+| `memory_file_history` | Osservazioni passate su file specifici |
+| `memory_patterns` | Rileva pattern ricorrenti |
+| `memory_sessions` | Elenca le sessioni recenti |
+| `memory_smart_search` | Ricerca ibrida semantica + per parole chiave |
+| `memory_vision_search` | Cerca osservazioni di immagini |
+| `memory_timeline` | Osservazioni in ordine cronologico |
+| `memory_profile` | Profilo del progetto (concetti, file, pattern) |
+| `memory_export` | Esporta tutti i dati di memoria |
+| `memory_relations` | Interroga il grafo delle relazioni |
+| `memory_commit_lookup` | Sessioni dietro un commit git |
+| `memory_commits` | Commit registrati per una sessione |
+
+
+
+
+Strumenti estesi (54 totali, la superficie predefinita)
+
+| Strumento | Descrizione |
+|------|-------------|
+| `memory_patterns` | Rileva pattern ricorrenti |
+| `memory_timeline` | Osservazioni in ordine cronologico |
+| `memory_relations` | Interroga il grafo delle relazioni |
+| `memory_graph_query` | Attraversamento del grafo di conoscenza |
+| `memory_consolidate` | Esegue il consolidamento a 4 livelli |
+| `memory_claude_bridge_sync` | Sincronizza con MEMORY.md |
+| `memory_team_share` | Condivide con i membri del team |
+| `memory_team_feed` | Elementi condivisi recenti |
+| `memory_audit` | Traccia di controllo delle operazioni |
+| `memory_governance_delete` | Elimina con traccia di controllo |
+| `memory_snapshot_create` | Snapshot versionato con Git |
+| `memory_action_create` | Crea elementi di lavoro con dipendenze |
+| `memory_action_update` | Aggiorna lo stato di un'azione |
+| `memory_frontier` | Azioni non bloccate classificate per priorità |
+| `memory_next` | La singola azione successiva più importante |
+| `memory_lease` | Lease esclusivi per azioni (multi-agente) |
+| `memory_routine_run` | Istanzia routine di workflow |
+| `memory_signal_send` | Messaggistica tra agenti |
+| `memory_signal_read` | Legge i messaggi con ricevute |
+| `memory_checkpoint` | Gate su condizioni esterne |
+| `memory_mesh_sync` | Sincronizzazione P2P tra istanze |
+| `memory_sentinel_create` | Osservatori basati su eventi |
+| `memory_sentinel_trigger` | Attiva i sentinel dall'esterno |
+| `memory_sketch_create` | Grafi di azione effimeri |
+| `memory_sketch_promote` | Promuove a permanente |
+| `memory_crystallize` | Compatta catene di azioni |
+| `memory_diagnose` | Controlli di salute |
+| `memory_heal` | Auto-correzione di stati bloccati |
+| `memory_facet_tag` | Tag dimensione:valore |
+| `memory_facet_query` | Interroga per tag di facet |
+| `memory_verify` | Traccia la provenienza |
+
+
+
+### 6 risorse · 3 prompt · 17 skill
+
+| Tipo | Nome | Descrizione |
+|------|------|-------------|
+| Risorsa | `agentmemory://status` | Salute, conteggio sessioni, conteggio memorie |
+| Risorsa | `agentmemory://project/{name}/profile` | Intelligence per progetto |
+| Risorsa | `agentmemory://project/{name}/recent` | Osservazioni recenti per un progetto |
+| Risorsa | `agentmemory://memories/latest` | Ultime 10 memorie attive |
+| Risorsa | `agentmemory://graph/stats` | Statistiche del grafo di conoscenza |
+| Risorsa | `agentmemory://team/{id}/profile` | Profilo di team condiviso |
+| Prompt | `recall_context` | Cerca e restituisce messaggi di contesto |
+| Prompt | `session_handoff` | Dati di passaggio tra agenti |
+| Prompt | `detect_patterns` | Analizza pattern ricorrenti |
+| Skill | `/recall` | Cerca nella memoria |
+| Skill | `/remember` | Salva nella memoria a lungo termine |
+| Skill | `/session-history` | Riassunti delle sessioni recenti |
+| Skill | `/forget` | Elimina osservazioni/sessioni |
+
+La tabella mostra le quattro skill core. Il set completo è di 9 skill invocabili più 8 skill di riferimento; vedi la sezione Skill native sopra.
+
+### MCP standalone
+
+Eseguilo senza il server completo, per qualsiasi client MCP. Funziona uno dei due:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Oppure aggiungi alla configurazione MCP del tuo agente:
+
+La maggior parte degli agenti (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Unisci la voce `agentmemory` nell'oggetto `mcpServers` esistente del tuo host invece di sostituire il file. Per i client in sandbox che non possono raggiungere il `localhost` dell'host, aggiungi `"AGENTMEMORY_FORCE_PROXY": "1"` al blocco env e imposta `AGENTMEMORY_URL` su una rotta che la sandbox possa raggiungere.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copia il file del plugin dal repository:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Si avvia automaticamente sulla porta `3113`. Il viewer carica uno snapshot quando si connette (`GET /agentmemory/viewer/snapshot`) e poi applica eventi di stream dal vivo: nuove memorie, lezioni, osservazioni, voci di audit, cambiamenti del grafo e aggiornamenti di salute appaiono senza polling o ricaricamenti di pagina. Le uniche altre richieste sono le azioni che clicchi, le pagine "carica altro" e le ricerche. Quando lo stream si interrompe, il viewer mostra quanto sono vecchi i suoi numeri, si riconnette con backoff e si risincronizza da uno snapshot.
+
+- **12 tab in quattro gruppi** con conteggi dal vivo, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), scorciatoie da tastiera e un menu mobile.
+- **Memorie:** ricerca lato server, filtri per progetto, agente e tipo, un pannello di dettaglio con la catena delle versioni e un diff per parola, link di provenienza, pulsanti copia per l'id, la chiamata MCP e un comando curl, modifica (una nuova versione), dimentica con conferma, dimentica in blocco ed esportazione JSON.
+- **Sessioni:** una timeline di osservazioni inline con input e output degli strumenti leggibili, filtri e paginazione, e le memorie e le lezioni prodotte da ogni sessione.
+- **Grafo:** ricerca, dettaglio del nodo con relazioni e fonti, una legenda che non si basa solo sul colore, e controlli di zoom.
+- **Salute:** la versione dal vivo di `GET /agentmemory/status`. Ogni problema arriva con la sua soluzione, oltre al backend di stato, lo stato di salvataggio dell'indice, l'avanzamento della compattazione della provenienza del grafo e una spiegazione del consolidamento con le soglie reali.
+- Pagine **Audit, Attività, Profilo, Replay, Lezioni, Azioni e Cristalli**, ognuna con uno stato vuoto che spiega cosa è la sezione, perché è vuota e il comando che la popola, e un tooltip glossario `?` su ogni termine e numero.
+
+```bash
+open http://localhost:3113
+```
+
+Il server del viewer si collega a `127.0.0.1` per impostazione predefinita e aggiunge il secret del server quando inoltra le richieste all'API REST, quindi non richiede configurazione. L'endpoint `/agentmemory/viewer` servito via REST segue le normali regole del bearer-token e reindirizza i browser senza token alla porta del viewer. Gli header CSP usano un nonce dello script per risposta e disabilitano gli attributi di gestore inline (`script-src-attr 'none'`).
+
+---
+
+
+
+Il viewer su `:3113` mostra ciò che il tuo agente **ha ricordato**. La [iii console](https://iii.dev/docs/console) mostra ciò che il tuo agente **ha fatto**: ogni operazione di memoria come traccia OpenTelemetry, ogni voce KV modificabile, ogni funzione invocabile, ogni stream intercettabile. Due finestre sulla stessa memoria: una a forma di prodotto, una a forma di engine.
+
+Osserva l'attivazione di una `memory_smart_search` e guarda la scansione BM25 → ricerca embedding → fusione RRF → reranker come un waterfall. Modifica un timer di consolidamento bloccato nel browser KV. Riproduci un hook `PostToolUse` con un payload modificato. Fissa lo stream WebSocket e guarda le osservazioni arrivare dal vivo.
+
+agentmemory offre tutto questo gratis perché ogni chiamata di funzione e trigger passa attraverso iii; niente di personalizzato, niente da strumentare.
+
+
+
+
+ Pagina Workers: ogni worker connesso, incluso agentmemory stesso, con PID, conteggio delle funzioni, runtime e ultimo avvistamento.
+
+
+**Già installata.** La console viene distribuita con l'engine `iii` fissato (0.22+); nulla da installare separatamente. Il primo avvio scarica il binario della console accanto all'engine.
+
+**Avviala insieme ad agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Questo esegue `iii console` dell'engine fissato contro le porte risolte da agentmemory (REST, stream, bridge) e la serve una porta sopra il viewer, `http://localhost:3114` per impostazione predefinita. `--console-port N` ne scelgie un'altra; `--port` e `--instance` selezionano l'istanza agentmemory nello stesso modo in cui lo fanno per `stop`; qualsiasi altro flag viene passato direttamente, ad esempio `--enable-flow` per la pagina sperimentale del grafo di architettura.
+
+La stessa cosa a mano, utile quando `agentmemory` non è nel PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Cosa puoi fare dalla console:**
+
+| Pagina | Usala per |
+|------|-----------|
+| **Workers** | Vedere ogni worker connesso e le sue metriche dal vivo, incluso il worker agentmemory stesso. |
+| **Functions** | Invocare direttamente qualsiasi funzione di agentmemory con un payload JSON; utile per testare `memory.recall`, `memory.consolidate`, `graph.query` senza collegare un client. |
+| **Triggers** | Riprodurre trigger HTTP, cron, evento e stato: far scattare manualmente il cron di consolidamento, ritentare una rotta HTTP, emettere un cambiamento di stato. |
+| **States** | Browser KV con CRUD completo su sessioni, slot di memoria, timer del ciclo di vita e indice degli embedding; modifica i valori sul posto. |
+| **Streams** | Monitor WebSocket dal vivo per scritture di memoria, eventi degli hook e aggiornamenti delle osservazioni mentre fluiscono attraverso gli stream iii. |
+| **Queues** | Topic di coda durevoli + gestione delle dead-letter. Riproduci o scarta i job di embedding/compressione falliti. |
+| **Traces** | Vista waterfall / flame / scomposizione per servizio di OpenTelemetry. Filtra per `trace_id` per vedere esattamente quali funzioni, chiamate DB e richieste di embedding ha prodotto una singola `memory.search`. |
+| **Logs** | Log OTEL strutturati filtrati e correlati agli ID di trace/span. |
+| **Config** | Configurazione runtime: vedi esattamente con quali worker, provider e porte sta funzionando il tuo engine. |
+| **Flow** | (Opzionale, `--enable-flow`) Grafo di architettura interattivo di ogni worker, trigger e stream. |
+
+
+
+
+ Traces: vista waterfall / flame / scomposizione per servizio per ogni operazione di memoria.
+
+
+**Le tracce sono già attive:**
+
+`iii-config.yaml` viene distribuito con il worker `iii-observability` abilitato (`exporter: memory`, `sampling_ratio: 0.1`, metriche + log). Nessuna configurazione extra necessaria; nel momento in cui agentmemory si avvia, ogni operazione di memoria emette un log strutturato che la console può leggere, e una su dieci di esse (`sampling_ratio: 0.1`) emette anche uno span di traccia.
+
+Se vuoi esportare verso Jaeger/Honeycomb/Grafana Tempo invece, cambia `exporter: memory` in `exporter: otlp` e imposta l'endpoint del collector secondo la documentazione di osservabilità di iii.
+
+> **Attenzione:** nessuna autenticazione è applicata sulla console stessa; mantienila collegata a `127.0.0.1` (il default) e non esporla mai pubblicamente.
+
+---
+
+
+
+agentmemory è **già un'istanza [iii](https://iii.dev) in esecuzione**. Tre primitive (worker, function, trigger) compongono il runtime; lo stato KV, gli stream e le tracce OTEL provengono dai worker iii-state, iii-stream e iii-observability distribuiti con iii. Non hai installato Postgres, Redis, Express, pm2 o Prometheus, perché iii li sostituisce.
+
+Questo significa che un comando in più estende agentmemory con un'intera nuova capacità.
+
+### Estendi agentmemory con altri worker
+
+I builtin di cui agentmemory ha bisogno sono già in `iii-config.yaml` e si avviano con esso: `iii-state` (KV), `iii-queue` (retry durevoli per i subscriber di eventi), `iii-pubsub`, `iii-cron`, `iii-stream` e `iii-observability` (tracce, metriche e log OTEL su ogni funzione). Qualsiasi altra cosa dal [registro dei worker iii](https://workers.iii.dev) si collega allo stesso engine: copia `iii-config.yaml` in `~/.agentmemory/iii-config.yaml` (la CLI preferisce quel file rispetto a quello incluso e vi rende ancora porte e percorsi dei dati), aggiungi la voce, installa il runtime del worker una volta con `~/.agentmemory/bin/iii update worker`, e riavvia agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Cosa ottieni in più rispetto ad agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Adapter di stato basato su SQL quando superi i default KV in memoria |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Il codice uscito da `memory_recall` viene eseguito dentro una VM usa e getta, non nella tua shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Avvia altri server MCP accanto a quello di agentmemory, condividendo lo stesso engine |
+
+Sull'engine 0.22.x mantieni i nomi con prefisso `iii-` per i builtin sopra; le voci senza prefisso `http`, `state`, `queue`, `pubsub` e `cron` sono i worker standalone del registro verso cui agentmemory si sposta con la migrazione alla 0.23.
+
+Registro completo: [workers.iii.dev](https://workers.iii.dev). Ogni worker lì compone attraverso le stesse primitive che usa agentmemory, e l'agentmemory che hai già è uno di loro.
+
+### Configurazione dell'engine e indirizzo di bind
+
+`agentmemory start` legge la configurazione dell'engine dal primo file che esiste: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` nella directory corrente, `~/.agentmemory/iii-config.yaml`, poi il `iii-config.yaml` incluso. A ogni avvio rende quel file (percorsi dei dati, porte, backend di stato) in `~/.agentmemory/data/iii-config.runtime.yaml` e avvia l'engine con la copia resa, quindi modifica il file sorgente, non quello reso. I valori `host:` del file sorgente vengono mantenuti come scritti.
+
+Il `iii-config.yaml` incluso si collega a `127.0.0.1` di proposito, e quel default si applica anche dentro un container. Una CLI avviata in un container si collega al loopback del container, quindi le porte pubblicate non raggiungono nulla. Per servire una CLI containerizzata tramite le porte pubblicate, imposta `AGENTMEMORY_III_CONFIG` su una configurazione che si collega a `0.0.0.0`. Il `iii-config.docker.yaml` incluso è una di queste: collega `iii-http`, `iii-stream` e la porta dell'engine a `0.0.0.0` e memorizza lo stato sotto `/data`, quindi monta lì un volume scrivibile. Mantieni `AGENTMEMORY_SECRET` impostato, e pubblica solo le porte di cui hai bisogno, su `127.0.0.1` o dietro un proxy di cui ti fidi.
+
+Il `docker-compose.yml` di questo repository non passa attraverso la ricerca di configurazione della CLI: monta `iii-config.docker.yaml` su `/app/config.yaml`, e il container `iii-engine` si avvia con `--config /app/config.yaml`. I template di [deploy](../deploy/) one-click scrivono la propria configurazione `0.0.0.0` nei loro entrypoint.
+
+### Backend di storage: file (predefinito) vs redis
+
+`iii-state` e `iii-stream` usano per default lo store KV basato su file incluso in iii-engine: un file JSON per scope, mantenuto nella memoria del processo dell'engine e riscritto su disco a intervalli. È il default giusto per un'installazione locale a utente singolo; un daemon condiviso con diversi scrittori simultanei ottiene scritture per-chiave reali da Redis invece, al costo di un round trip di rete per operazione (ogni chiamata `state::*` si serializza ancora su una connessione Redis, quindi questo scambia il lock dello store a file per un socket, non per il parallelismo).
+
+Imposta `AGENTMEMORY_STATE_BACKEND=redis` (più `AGENTMEMORY_REDIS_URL`) per far passare entrambi i worker all'adapter `redis` integrato di iii-engine, che memorizza ogni chiave come campo di un hash Redis (`HSET`) invece di riscrivere un intero scope a ogni scrittura:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` ha come default `file`; lasciarlo non impostato mantiene inalterato il comportamento attuale, e un valore non riconosciuto (qualsiasi cosa diversa da `file` o `redis`) è un errore di avvio piuttosto che un fallback silenzioso. `/agentmemory/status` e la pagina Health del viewer (la riga dello state store) riportano quale backend è attivo e se risponde, mai l'URL.
+
+**Solo `redis://` semplice.** L'engine fissato (0.22.1) costruisce il suo client Redis senza supporto TLS, quindi un URL `rediss://` (la maggior parte delle offerte Redis gestite, come Upstash, Redis Cloud ed ElastiCache con crittografia in transito, è predefinita a solo-TLS) non riesce a connettersi. La connessione è non crittografata, quindi la password Redis e ogni memoria salvata attraversano la rete in chiaro: puntala a un Redis locale o su una rete privata di cui ti fidi. Per qualsiasi altro Redis, esegui un tunnel crittografato (stunnel, SSH o una VPN) sull'host di agentmemory, così il salto `redis://` semplice resta su quell'host e la connessione a monte del tunnel è crittografata e autenticata. Se una password Redis contiene un apostrofo, codificalo in percent-encoding (`%27`); l'engine espande l'URL nella sua configurazione YAML prima di analizzarlo.
+
+**Un server Redis per ogni `--instance`.** I prefissi delle chiavi Redis dell'engine (`state:`, `stream::`) sono fissi, quindi due istanze di agentmemory (`--instance 1`, `--instance 2`, ...) puntate allo stesso database si sovrascrivono i dati a vicenda. Un indice di database separato (`redis://localhost:6379/1`) mantiene separati i dati memorizzati, ma l'engine fa da relay per gli eventi del viewer dal vivo su un unico canale pub/sub Redis (`stream::events`), e il pub/sub di Redis ignora l'indice del database, quindi il viewer di ogni istanza mostrerebbe comunque gli eventi dal vivo dell'altra. Dai a ogni istanza il proprio server Redis (o la propria porta) quando ne esegui più di una.
+
+**Cosa resta uguale, e cosa cambia.** Ogni funzionalità di agentmemory funziona su Redis: sessioni, osservazioni, memorie (remember, supersede, evolve, forget), ricerca e i bucket dell'indice, lezioni, il grafo, il log di audit e i suoi scope mensili, export e import, eliminazioni di governance, stato del consolidamento, lo snapshot del viewer e il suo stream dal vivo, e il monitor di salute. L'engine memorizza ogni scope come un hash Redis (`HSET`/`HGET`/`HGETALL`) e fa scattare gli stessi trigger di stato dello store a file. Tre differenze dell'engine sono gestite dentro agentmemory:
+
+- Redis restituisce i record di uno scope in nessun ordine fisso. agentmemory li ordina prima i più vecchi (per il momento di creazione nell'id del record, poi il suo timestamp) così liste, paginazione e blocchi di export tornano nello stesso ordine dello store a file.
+- L'engine applica gli aggiornamenti parziali su Redis in uno script Lua che trasforma gli array vuoti in oggetti vuoti. agentmemory applica quegli aggiornamenti da sé (legge, modifica, scrive sotto un lock per chiave) su Redis, così campi come `tags: []` restano array.
+- Il controllo legacy del log di audit legge il vecchio scope da Redis invece di cercare il file dello store su disco.
+
+Una differenza richiede il tuo intervento: **dopo il riavvio di Redis, l'engine smette di fare il relay degli eventi dal vivo** verso il viewer finché agentmemory non viene riavviato. I dati continuano a essere salvati e letti normalmente. Il monitor di salute invia un evento di test attraverso Redis ogni 30 secondi; quando non torna, `/agentmemory/status` e la pagina Health del viewer mostrano "Gli aggiornamenti dal vivo non raggiungono il viewer" con la soluzione: riavvia agentmemory. Se Redis è down, il report di stato mostra "Lo state store non risponde" e come verificarlo (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Elencare uno scope molto grande legge l'intero hash in un unico `HGETALL`, lo stesso costo dello store a file che lo mantiene in memoria.
+
+**Impostazioni Redis consigliate.** La policy di snapshot predefinita `save 3600 1 300 100 60 10000` può perdere minuti di scritture in caso di crash, peggio della finestra di flush di 5s dello store a file. Imposta `appendonly yes` per qualsiasi cosa di cui ti importerebbe la perdita. Imposta `maxmemory-policy noeviction`; `allkeys-lru` o simili eliminano silenziosamente le memorie una volta che Redis raggiunge il suo limite di memoria.
+
+Un avvio nativo (non-Docker), e ogni [template di deploy](../deploy/) one-click (sovrascrivono il `iii-config.yaml` incluso e si avviano nativamente), leggono `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` e li rendono nel `iii-config` avviato. L'URL stesso non viene mai scritto in quel file reso, solo un riferimento `${AGENTMEMORY_REDIS_URL}` che il processo dell'engine espande dal proprio ambiente all'avvio. Solo il percorso Docker Compose di questo stesso repository (`AGENTMEMORY_USE_DOCKER=1`, o la ripresa di un engine già avviato in quel modo) monta `iii-config.docker.yaml` in sola lettura e non lo rende mai; `agentmemory start` avvisa quando rileva questa combinazione. Cambia quel file a mano, seguendo la stessa forma `name: redis` / `config: redis_url: ...` mostrata nella documentazione dei worker [iii-state](https://workers.iii.dev/workers/iii-state) e [iii-stream](https://workers.iii.dev/workers/iii-stream), e punta `redis_url` a un Redis raggiungibile dal container. `docker-compose.yml` passa `AGENTMEMORY_REDIS_URL` nel container dell'engine, quindi `redis_url: '${AGENTMEMORY_REDIS_URL}'` funziona lì e mantiene l'URL fuori dal file montato.
+
+La configurazione resa mantiene l'URL fuori da `~/.agentmemory/data/iii-config.runtime.yaml`, ma il worker di configurazione dell'engine stesso persiste comunque il valore *espanso* in `~/.agentmemory/config/iii-state.yaml` e `iii-stream.yaml` una volta avviato (l'espansione `${VAR}` di iii-engine avviene prima che quel worker memorizzi il suo seed, e memorizza il valore risolto, non il riferimento). Tratta quella directory come se contenesse una credenziale: `chmod 700 ~/.agentmemory` su qualsiasi host condiviso, e preferisci un utente ACL Redis con ambito limitato a ciò di cui agentmemory ha bisogno piuttosto che le credenziali admin del database.
+
+**La migrazione non è automatica.** Passare `AGENTMEMORY_STATE_BACKEND` parte da uno store vuoto su entrambi i lati; nulla copia i dati esistenti da file a Redis o viceversa. Esporta dal backend che stai lasciando e importa in quello verso cui ti stai spostando. Questo funziona identicamente sotto bash e zsh (incluso `bash -u`). Un array come `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` non funziona: zsh mantiene l'header come una singola parola malformata dove bash lo divide in due, quindi entrambe le richieste restituiscono 401 ogni volta che `AGENTMEMORY_SECRET` è impostato:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` accetta anche `?maxSessions=` e `?offset=` per suddividere un corpus grande su più chiamate; `strategy` nell'import è `merge` (predefinito, sicuro), `replace`, o `skip`.
+
+### Cosa sostituisce iii
+
+| Stack tradizionale | agentmemory usa |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + indice vettoriale in memoria |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | Supervisione dei worker dell'engine iii |
+| Prometheus / Grafana | iii OTEL + monitor di salute |
+| Sistemi di plugin personalizzati | `iii worker add ` |
+
+**225 file sorgente · ~54,000 righe di codice · 2,600+ test · 312 funzioni · 66 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
+
+---
+
+
+
+### Provider LLM
+
+agentmemory rileva automaticamente i provider dal tuo ambiente. Un provider rende disponibili le operazioni basate su LLM, ma la sola configurazione del provider non attiva la compressione delle osservazioni scritta da un LLM. Quel percorso richiede sia un provider sia `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Provider | Configurazione | Note |
+|----------|--------|-------|
+| **No-op (predefinito)** | Nessuna configurazione necessaria | Compress/summarize basati su LLM disabilitati. La compressione sintetica e il recall BM25 funzionano comunque. Vedi `AGENTMEMORY_ALLOW_AGENT_SDK` sotto se facevi affidamento sul fallback dell'abbonamento Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Fatturazione per token |
+| MiniMax | `MINIMAX_API_KEY` | Compatibile con Anthropic |
+| Gemini | `GEMINI_API_KEY` | Abilita anche gli embedding |
+| OpenRouter | `OPENROUTER_API_KEY` | Qualsiasi modello |
+| OpenAI API | `OPENAI_API_KEY` | Predefinito `gpt-5.6-luna`, sovrascrivi con `OPENAI_MODEL` |
+| **Locale (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) oppure `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Qualsiasi cosa compatibile con l'API OpenAI. Costo zero, funziona sul tuo hardware. Vedi [Modelli locali](#local-models-ollama--lm-studio--vllm) sotto. |
+| Fallback abbonamento Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Solo opt-in. Avvia sessioni `@anthropic-ai/claude-agent-sdk`; in passato causava una ricorsione illimitata dell'hook Stop, quindi non è più il predefinito. |
+
+### Modelli locali (Ollama / LM Studio / vLLM)
+
+agentmemory parla con qualsiasi server compatibile con l'API OpenAI, quindi qualsiasi cosa esponga `/v1/chat/completions` funziona senza modifiche al codice. Nessuna chiave a pagamento, nessun cloud, nessun limite di rate; funziona interamente sul tuo hardware.
+
+**Ollama** (porta predefinita `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (porta predefinita `1234`):
+
+Apri LM Studio → tab Local Server → Start Server. Scegli qualsiasi modello di chat dal selettore (Qwen 3, gpt-oss, DeepSeek R1, ecc.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: stessa forma. Punta `OPENAI_BASE_URL` all'URL esposto dal tuo server e imposta `OPENAI_MODEL` su un nome che il tuo server accetterà.
+
+**Scelte di modello per il lavoro di memoria**: compressione e riassunto sono compiti brevi (<2K token in ingresso, <500 token in uscita) dove un modello instruct da 7B è più che sufficiente. Raccomandazioni:
+
+| Modello | Dimensione | Perché |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Default equilibrato su una macchina da 16 GB; forte nell'estrazione e nel testo a forma di strumento |
+| `qwen3:4b` | ~2.6 GB | Opzione più piccola ragionevole; va bene per la compressione, più debole per l'estrazione del grafo |
+| `qwen3-coder:30b` | ~19 GB | Migliore scelta locale per sessioni a forma di codice (30B MoE, 3.3B attivi) su hardware da 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Modello generale forte che entra in 16 GB di RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Distillazione di reasoning; più lento ma estrazioni più pulite |
+
+I modelli Qwen 3 "pensano" per default e possono bruciare tutto il budget di token nel reasoning prima di qualsiasi output. Imposta `AGENTMEMORY_LLM_NOTHINK=1` per aggiungere `/no_think` ai prompt di estrazione del grafo, e aumenta `MAX_TOKENS` (16384 funziona) se le estrazioni tornano vuote.
+
+I modelli di classe reasoning (stile `o1` con blocchi ``) possono restituire un `content` vuoto con un campo `reasoning` che il tuo server locale potrebbe non esporre. Se le estrazioni tornano vuote, passa prima a un modello non-reasoning. La variabile d'ambiente `OPENAI_REASONING_EFFORT=none` può anche disabilitare il pensiero sui modelli di pensiero di Ollama Cloud che rispecchiano lo schema di reasoning di OpenAI.
+
+Gli embedding locali sono distribuiti come dipendenza opzionale ma non sono abilitati per default. Imposta `EMBEDDING_PROVIDER=local` per attivare `Xenova/all-MiniLM-L6-v2` (384 dimensioni). La prima richiesta di embedding scarica il modello; l'inferenza è on-device in seguito. Senza quell'impostazione o una chiave di embedding remota, i vettori restano disabilitati, `mem::search` usa BM25, e `smart-search` può comunque aggiungere corrispondenze del grafo esistenti.
+
+### Selezione del modello consapevole dei costi
+
+Quando la compressione in background scritta da un LLM è abilitata con sia un provider sia `AGENTMEMORY_AUTO_COMPRESS=true`, viene eseguita su ogni osservazione, quindi la scelta del modello cambia in modo significativo la spesa mensile. Dati del carico di lavoro catturato: 635 richieste / 888K token / 35 ore di uso attivo, eseguite contro tre modelli OpenRouter con i prezzi del 2026-05-23.
+
+| Livello | Modello | Input / 1M | Output / 1M | Costo per le 35h catturate | Note |
+|------|-------|------------|-------------|---------------------------|-------|
+| Consigliato | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (stimato) | DeepSeek più recente; la scelta consigliata più economica per i carichi di lavoro di compressione. |
+| Consigliato | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solida qualità di compressione + riassunto a un costo ~10× inferiore rispetto a Sonnet. |
+| Consigliato | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Forte reasoning sul codice se le tue sessioni sono fortemente orientate al codice. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (stimato) | Stesso prezzo di listino dell'esecuzione misurata su Sonnet 4.6; prezzo introduttivo $2/$10 fino al 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (stimato) | Livello flagship; costoso per lavoro in background always-on. |
+| Da evitare | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (stimato) | Modello di classe flagship; spesa eccessiva per la compressione. |
+
+Le righe misurate provengono dall'esecuzione catturata; le righe (stimato) scalano lo stesso mix di token secondo il prezzo di listino di ciascun modello.
+
+agentmemory stampa un avviso a runtime quando `OPENROUTER_MODEL` corrisponde a un pattern di livello premium. Imposta `AGENTMEMORY_SUPPRESS_COST_WARNING=1` per silenziarlo una volta fatta una scelta informata.
+
+Compromesso qualità vs costo per il lavoro di memoria: la compressione è un compito di riassunto con soglie di qualità relativamente permissive (l'agente rilegge il riassunto, non l'utente). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder restano nel margine d'errore rispetto a Sonnet su questo compito costando 10-70× meno. Riserva i modelli di livello premium alle query che leggi direttamente.
+
+Fonti: [prezzi OpenRouter per Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [note sui prezzi DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Memoria multi-agente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Nelle configurazioni multi-agente dove diversi ruoli condividono un server agentmemory (architetto / sviluppatore / revisore / ricercatore / agente di supporto), `AGENT_ID` etichetta ogni scrittura con il ruolo che l'ha fatta. `AGENTMEMORY_AGENT_SCOPE` controlla se il recall filtra per quella etichetta.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Due modalità:
+
+| Modalità | Etichetta le scritture | Filtra il recall | Quando usarla |
+|------|------------|---------------|-------------|
+| `shared` (predefinita) | sì | no | Contesto cross-agente con traccia di controllo. L'architetto può vedere ciò che lo sviluppatore ha annotato, ma ogni riga registra chi lo ha detto. |
+| `isolated` | sì | sì | Separazione stretta. L'architetto non vede mai le osservazioni/memorie/sessioni dello sviluppatore. |
+
+Cosa viene etichettato quando `AGENT_ID` è impostato: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Il ruolo fluisce da `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Cosa viene filtrato in modalità isolata: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Ogni endpoint accetta `?agentId=` per sovrascrivere per-richiesta, e `?agentId=*` per disattivare completamente lo scope dell'ambiente. `/memories` accetta anche `?includeOrphans=true` per far emergere le memorie precedenti ad `AGENT_ID` il cui `agentId` è indefinito.
+
+Override per-chiamata a livello di SDK / REST: ogni endpoint che muta (`/session/start`, `/remember`) accetta un campo `agentId` nel corpo della richiesta che vince sull'ambiente. Utile per i runtime che instradano molti ruoli attraverso un singolo processo server. Lo strumento MCP `memory_save` espone lo stesso campo `agentId`, il server stdio standalone trasmette sia `agentId` sia `project`, e le memorie salvate portano `agentId` nell'indice di ricerca, così la ricerca con ambito agente copre anche le memorie oltre alle osservazioni.
+
+Quando `AGENT_ID` non è impostato, la memoria resta senza ambito (comportamento legacy, nessuna etichetta, nessun filtro).
+
+### Porte
+
+agentmemory + iii-engine collegano quattro porte per default. Se un riavvio fallisce con `port in use`, questa tabella ti dice quale processo cercare.
+
+| Porta | Processo | Scopo | Override ambiente |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | API REST + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker interno degli stream (consumato da agentmemory + viewer) | `III_STREAM_PORT` (preferito) o il legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer in tempo reale (`http://localhost:3113`) | `III_VIEWER_PORT` oppure `AGENTMEMORY_VIEWER_URL` per l'URL riportato |
+| `49134` | iii-engine | WebSocket; i worker si registrano qui, la telemetria OTel fluisce su di esso | `III_ENGINE_PORT` oppure `III_ENGINE_URL` |
+
+`--port ` cambia l'ancora REST e deriva gli stream `N+1`, il viewer `N+2` e il WebSocket dell'engine `N+46023` solo dove la porta o l'URL espliciti corrispondenti sopra non sono impostati. Non crea uno spazio dei nomi del ciclo di vita isolato. Usa `--instance 1` per un secondo daemon; usa l'ancora 3211, ha come default `3211/3212/3213/49234`, e riceve una directory separata `instance-1` per dati e ciclo di vita. Le istanze da 1 a 50 seguono lo stesso pattern.
+
+L'engine fissato si avvia con `--no-update-check` (nessuna ricerca di aggiornamenti o avvisi di sicurezza contro GitHub all'avvio) e con la telemetria di utilizzo anonima di iii disattivata: agentmemory imposta `III_TELEMETRY_ENABLED=false` per l'engine che avvia a meno che tu non esporti la variabile da solo, e il file compose incluso fa lo stesso.
+
+Pulizia dei processi bloccati quando le porte restano occupate dopo un'esecuzione andata in 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
+```
+
+`agentmemory stop` recupera in modo pulito sia il worker sia il pidfile dell'engine su uno spegnimento nativo elegante. In modalità Docker, svuota il worker nativo, arresta esattamente il container dell'engine validato, e preserva sia il container sia il suo mount `/data` per un riavvio senza perdita di dati; il prossimo avvio valida e riprende quello stesso container. La disinstallazione con backend Docker richiede `agentmemory remove --keep-data`: rimuove i file gestiti condivisi di agentmemory preservando il container validato, il suo mount dei dati e il record del ciclo di vita necessario per recuperarli. L'eliminazione distruttiva dei dati Docker è intenzionalmente lasciata all'operatore dopo un backup. La CLI rifiuta anche di adottare o segnalare i detentori di porta Docker o VM (backend Docker, vpnkit, colima) come l'engine nativo a meno che non venga passato `--force`. La pulizia manuale sopra serve solo per il caso post-crash in cui non resta nessun pidfile.
+
+### File di configurazione
+
+Metti la configurazione runtime di agentmemory in `~/.agentmemory/.env` invece di esportare variabili in ogni shell. Se il viewer mostra un suggerimento di configurazione come `export ANTHROPIC_API_KEY=...`, copialo in questo file come `ANTHROPIC_API_KEY=...` senza il prefisso `export`, poi riavvia agentmemory.
+
+Le variabili d'ambiente del processo funzionano comunque e hanno la precedenza sui valori nel file.
+
+Su Windows, lo stesso file risiede in `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Per testare con un abbonamento Claude Code Pro/Max invece di una chiave API, attiva l'opzione esplicitamente:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+La compressione delle osservazioni scritta da un LLM richiede entrambe le righe: accesso a un provider LLM (incluso questo fallback esplicito dell'abbonamento) e `AGENTMEMORY_AUTO_COMPRESS=true`. Un provider da solo lascia in vigore il percorso predefinito di compressione sintetica.
+
+Il consolidamento (nodi del grafo, lezioni, cristalli) è attivo per default ogni volta che è configurato un provider LLM. Disattivalo esplicitamente con `CONSOLIDATION_ENABLED=false` se vuoi un funzionamento senza LLM. L'estrazione del grafo è un flag separato:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Variabili d'ambiente
+
+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://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoint sulla porta `3111`. L'API REST si collega a `127.0.0.1` per impostazione predefinita. Gli endpoint protetti richiedono `Authorization: Bearer `, e gli endpoint di sincronizzazione mesh richiedono un `AGENTMEMORY_SECRET` impostato esplicitamente su entrambi i peer.
+
+**L'autenticazione è attiva per default.** Quando `AGENTMEMORY_SECRET` non è impostato (nella shell o in `~/.agentmemory/.env`), il server genera un secret casuale al primo avvio e lo memorizza in `~/.agentmemory/secret` con modalità `0600`. Ogni client incluso lo legge da lì quando parla con un server locale: la CLI, il viewer, gli hook sotto `plugin/scripts`, il server MCP e lo shim `@agentmemory/mcp`, le configurazioni scritte da `agentmemory connect`, e le integrazioni incluse OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. Il secret memorizzato viene inviato solo a URL loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` esplicito vince sempre, e i client remoti devono comunque averlo impostato. Docker e gli entrypoint di `deploy/` generano ed esportano già il proprio secret. Per chiamare l'API a mano:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Regole di richiesta per le scritture.** Le richieste `POST`, `PUT`, `PATCH` e `DELETE` all'API REST e al viewer devono inviare `Content-Type: application/json` (un parametro `charset` va bene) ogni volta che portano un corpo, e un header `Origin`, quando presente, deve essere un'origine loopback per la porta REST o viewer configurata oppure essere elencato in `VIEWER_ALLOWED_ORIGINS` (separato da virgole, ad es. `https://memory.example.com`). I client che non inviano nessun header `Origin` (CLI, hook, MCP, curl, server-to-server) non sono affetti. Il viewer accetta anche la propria origine.
+
+**Percorsi dei file.** Gli endpoint che leggono o scrivono file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) accettano solo percorsi sotto `~/.agentmemory`, la directory dei dati dell'istanza, o una directory elencata in `AGENTMEMORY_IMPORT_ROOT` (separane diverse con `:`, o `;` su Windows). `/replay/import-jsonl` accetta anche il suo default `~/.claude/projects`. `/obsidian/export` resta dentro `AGENTMEMORY_EXPORT_ROOT` e `/migrate` dentro `~/.agentmemory`. I symlink vengono risolti prima di ogni controllo.
+
+**Rimozione dei segreti.** Chiavi API, bearer token, blocchi di chiavi private PEM e credenziali incorporate negli URL (`scheme://user:password@host`) vengono oscurati prima che il testo venga memorizzato, su ogni percorso di scrittura: osservazioni, remember, evolve, slot, lezioni, azioni, sketch, segnali, checkpoint, import, replay jsonl, sincronizzazione mesh, condivisioni di team, output di compressione e riassunto, cristalli e nodi del grafo.
+
+
+Endpoint principali
+
+| Metodo | Percorso | Descrizione |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Controllo di salute (sempre pubblico) |
+| `GET` | `/agentmemory/status` | Cosa non va e come risolverlo (HTML per i browser, JSON altrimenti) |
+| `GET` | `/agentmemory/viewer/snapshot` | Tutto ciò che il viewer mostra, in un'unica risposta |
+| `POST` | `/agentmemory/session/start` | Avvia sessione + ottieni contesto |
+| `POST` | `/agentmemory/session/end` | Termina sessione |
+| `POST` | `/agentmemory/observe` | Cattura osservazione (vedi la consegna della cattura sotto) |
+| `GET` | `/agentmemory/capture` | Inbox di cattura, dead letter e spool offline |
+| `POST` | `/agentmemory/capture/retry` | Riprova le catture dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Invia ora lo spool offline locale |
+| `POST` | `/agentmemory/smart-search` | Ricerca ibrida |
+| `POST` | `/agentmemory/context` | Genera contesto |
+| `POST` | `/agentmemory/remember` | Salva nella memoria a lungo termine |
+| `POST` | `/agentmemory/forget` | Elimina osservazioni |
+| `POST` | `/agentmemory/enrich` | Contesto del file + memorie + bug |
+| `GET` | `/agentmemory/profile` | Profilo del progetto |
+| `GET` | `/agentmemory/export` | Esporta tutti i dati |
+| `POST` | `/agentmemory/import` | Importa da JSON |
+| `POST` | `/agentmemory/graph/query` | Query sul grafo di conoscenza |
+| `POST` | `/agentmemory/graph/compact` | Riduce la provenienza del grafo sovradimensionata |
+| `POST` | `/agentmemory/team/share` | Condividi con il team |
+| `GET` | `/agentmemory/audit` | Traccia di audit |
+
+Elenco completo degli endpoint: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Consegna della cattura.** Gli hook inviano ogni osservazione una volta a `POST /agentmemory/observe` con un `eventId`. È l'id proprio dell'host per la chiamata quando il payload ne ha uno (per esempio il `tool_use_id` di Claude Code), altrimenti un hash della sessione, del tipo di hook, del nome dello strumento, dell'input, dell'output e del timestamp dell'host. Il server scrive l'evento in un inbox di cattura nello state store, memorizza l'osservazione, poi rimuove la voce dall'inbox. Il codice di stato dice cosa è successo:
+
+| Stato | Campo `status` | Significato |
+|---|---|---|
+| `201` | `accepted` | Memorizzato. `observationId` è la nuova osservazione. |
+| `202` | `accepted` (`state: "retrying"`) | Accettato, ma la memorizzazione è fallita. Il server lo riprova, anche dopo un riavvio. |
+| `200` | `duplicate` | Questo `eventId` era già stato accettato. `observationId` è l'osservazione esistente; non viene memorizzato nulla di nuovo. |
+| `400` / `422` | `rejected` | Payload non valido, oppure la memorizzazione è fallita definitivamente (l'evento viene conservato come dead letter). |
+| `503` | `rejected` (`retryable: true`) | L'inbox è piena (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Gli hook mettono l'evento in spool e lo inviano più tardi. |
+
+Gli eventi falliti vengono ritentati ogni `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) con backoff che raddoppia, fino a `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Gli eventi che continuano a fallire restano nell'inbox come dead letter, sono elencati su `/agentmemory/status` e nella pagina Health del viewer, e possono essere ritentati con `POST /agentmemory/capture/retry` (`{"eventId": "..."}` oppure `{"all": true}`). Gli id degli eventi accettati vengono ricordati per `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 ore, al massimo `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), quindi un hook rieseguito dopo un timeout o un riavvio viene memorizzato una volta, mentre due chiamate di strumento separate con i propri id host vengono memorizzate due volte anche quando il loro contenuto è identico. Quando un'osservazione viene eliminata (forget, eliminazione della sessione, eviction, auto-forget o un import che sostituisce lo store), il suo evento viene marcato come eliminato prima che l'osservazione venga rimossa, così una riesecuzione di quell'evento nella stessa finestra viene risposta come duplicato e non memorizza nulla. Lo state store scrive su disco ogni 2 secondi, quindi una risposta accettata può essere ancora solo in memoria per un istante. Per coprire questo, ogni risposta `2xx` porta anche il `bootId` del server (nuovo a ogni avvio), `acceptedAt` e `durableAfterMs` (l'intervallo di salvataggio più 1.5 s sullo store a file, 1.5 s su redis, dove la persistenza è un'impostazione dell'operatore). Gli hook mantengono l'evento nello spool locale finché quella finestra non è passata e lo eliminano a una chiamata successiva senza un'altra richiesta. Se il `bootId` è cambiato da allora, il server è stato riavviato, quindi l'hook invia di nuovo l'evento con lo stesso `eventId`; un evento che è arrivato sul disco non viene memorizzato due volte. Il server invia anche da sé tali eventi all'avvio e a ogni intervallo di retry, così un riavvio non perde nulla anche quando nessun hook viene eseguito in seguito. Gli hook più vecchi ignorano i campi extra, e i nuovi hook contro un server più vecchio scartano l'evento su `2xx` come prima.
+
+Quando il server è spento, non risponde in tempo o restituisce un 5xx, l'hook aggiunge l'osservazione a un file di spool locale, `/capture-spool/-.jsonl` (sovrascrivi la cartella con `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Il file è privato per il tuo utente (modalità 600), i segreti vengono oscurati allo stesso modo in cui li oscura il server, contiene al massimo `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) ed elimina le voci più vecchie di `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Quando è pieno, le nuove voci vengono scartate e contate, e `/agentmemory/status` lo segnala. L'hook esce comunque con 0 entro il suo limite di tempo e non aggiunge nessuna richiesta quando il server è sano. Lo spool viene inviato al prossimo avvio e dal primo hook che raggiunge di nuovo il server, in un processo in background così l'agente non aspetta. Gli id degli eventi rendono questo sicuro: un'osservazione che è arrivata prima di un timeout non viene memorizzata due volte. `npx @agentmemory/agentmemory capture` mostra lo spool e l'inbox del server, `--drain` invia subito lo spool, e `GET /agentmemory/capture` restituisce lo stesso come JSON. Imposta `AGENTMEMORY_CAPTURE_SPOOL=false` per disattivare lo spool.
+
+**Compattazione della provenienza del grafo.** Ogni nodo e arco del grafo di conoscenza mantiene gli id delle 32 osservazioni più recenti da cui è derivato. Gli store scritti prima di quel limite possono contenere migliaia di id per nodo caldo, il che rende lenta la ricerca nel grafo e il viewer o fa cadere il worker. agentmemory risolve questo da solo: al primo avvio dopo l'aggiornamento riduce ogni nodo, arco, arco superato (la storia temporale del grafo) e lo snapshot in cache al limite in background, in piccole porzioni con una pausa tra di esse, così ricerca, cattura e viewer continuano a funzionare. Salva il suo progresso, riprende dopo un riavvio e non viene più eseguito una volta terminato. `/agentmemory/status` e la pagina Health del viewer lo mostrano come in attesa, in esecuzione (con lo scope e la posizione correnti), completato o fallito. Imposta `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` per disattivarlo.
+
+Per eseguirlo a mano, chiama `POST /agentmemory/graph/compact`. Percorre gli indici dei nomi e delle chiavi degli archi invece di elencare ogni nodo e arco, ed è sicuro da rieseguire. Quando riduce gli id scrive una voce di audit `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Su uno store grande, o quando la chiamata restituisce 504, eseguilo a porzioni. Invia `scope` (`nodes`, `edges` o `history`), `offset` e `limit`, poi richiama con il `nextOffset` restituito finché non è `null`. Fallo per `nodes`, `edges` e `history`, e termina con un'unica chiamata `{"scope":"snapshot"}`, perché un'esecuzione a porzioni non toglie lo snapshot in cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Prerequisiti:** Node.js >= 20 con npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 o Docker. L'installazione automatica dell'engine su macOS/Linux richiede anche `curl`, una `sh` POSIX e `tar`; Windows nativo usa il `iii.exe` fissato manuale, WSL2, o Docker Desktop.
+
+
コーディングエージェントがすべてを記憶します。もう説明し直す必要はありません。
- Built on iii engine
+ iii engine を基盤に構築
- Claude Code、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode、そしてあらゆる MCP クライアントのための永続メモリ。
+ Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode、そしてあらゆる MCP クライアントのための永続メモリ。
코딩 에이전트가 모든 것을 기억합니다. 더 이상 다시 설명할 필요가 없습니다.
- Built on iii engine
+ iii engine 기반
- Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode 및 모든 MCP 클라이언트를 위한 영구 메모리입니다.
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, 그리고 모든 MCP 클라이언트를 위한 영구 메모리입니다.
- 이 gist는 Karpathy의 LLM Wiki 패턴을 신뢰도 점수, 라이프사이클, 지식 그래프, 하이브리드 검색으로 확장한 것입니다. agentmemory는 그 구현체입니다.
+ 이 gist는 Karpathy의 LLM Wiki 패턴을 신뢰도 점수, 라이프사이클, 지식 그래프, 하이브리드 검색으로 확장합니다. agentmemory가 그 구현체입니다.
@@ -50,7 +71,7 @@
-
+
@@ -75,31 +96,43 @@
## Install
-명령 하나면 됩니다:
+요구 사항:
+
+- Node.js 20 이상, npm과 npx 포함(`node -v`, `npm -v`, `npx -v`로 확인).
+- macOS/Linux에서 iii-engine을 자동으로 설치하려면 `curl`, POSIX `sh`, `tar`도 필요합니다. `node:20-slim` 같은 최소 이미지에는 이들이 포함되어 있지 않을 수 있습니다.
+- 네이티브 Windows에서는 고정 버전인 iii-engine v0.22.1의 `iii.exe`를 수동으로 설치해야 합니다. WSL2나 Docker Desktop을 사용하는 것도 지원되는 경로입니다.
+
+표준 신규 설치 명령:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-첫 실행은 인터랙티브 설정입니다: 연결할 에이전트(Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...)를 고르고, LLM 프로바이더를 선택하거나 키 없이 유지하십시오. 그러면 설정을 시드하고 `:3111`에서 메모리 서버를 시작하며, 이후 어디서나 단순한 `agentmemory` 명령이 동작하도록 전역 설치를 제안합니다.
+첫 실행은 인터랙티브 설정입니다: 연결할 에이전트(Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...)를 고르고, LLM 프로바이더를 선택하거나 키 없이 유지할 수 있으며, 그 뒤 설정을 시드하고 메모리 서버와 고정된 iii 엔진을 시작한 다음, 이후 어디서나 단순한 `agentmemory` 명령이 동작하도록 전역 설치를 제안합니다. `-y`는 npx의 패키지 설치 확인 프롬프트를 수락하고, `@latest`는 캐시된 오래된 릴리스를 피합니다. 프로바이더를 설정하면 LLM 기능을 사용할 수 있게 되지만, LLM이 작성하는 관측 압축은 `AGENTMEMORY_AUTO_COMPRESS=true`도 함께 설정해야 비로소 시작됩니다.
+
+키 없는 모드는 벡터 임베딩을 비활성화합니다. `memory_recall`(`mem::search` 경로)은 BM25를 사용하며, `memory_smart_search`는 그래프 데이터가 이미 존재하는 경우 구조적 그래프 매치도 결합할 수 있습니다. 무료 온디바이스 시맨틱 리콜을 원한다면 `~/.agentmemory/.env`에 `EMBEDDING_PROVIDER=local`을 설정하고 재시작하십시오. 첫 임베딩 요청이 `Xenova/all-MiniLM-L6-v2`를 다운로드하며, 이 최초 모델 다운로드 이후에는 추론이 로컬에서 실행됩니다.
+
+로컬 런타임은 네 개의 포트를 사용합니다: REST/MCP HTTP용 `3111`, iii 스트림용 `3112`, 뷰어용 `3113`, iii 워커 WebSocket용 `49134`입니다. 영구 iii 상태는 macOS에서는 `~/Library/Application Support/agentmemory`, Linux에서는 `$XDG_DATA_HOME/agentmemory` 또는 `~/.local/share/agentmemory`, Windows에서는 `%APPDATA%\agentmemory`에 저장됩니다. 이를 재정의하려면 `--data-dir ` 또는 `AGENTMEMORY_DATA_DIR`을 사용하고, 재시작할 때마다 동일한 값을 재사용하십시오. 하위 호환성을 위해, 기존의 `./data/state_store.db` 또는 `./data/iii-config.yaml`이 존재하면 인스턴스 0에서 플랫폼 기본값보다 우선합니다. 명시적인 플래그나 환경 변수 재정의는 그보다도 우선합니다.
그다음 리콜이 동작하는지 확인하고 에이전트에게 skills를 부여하십시오:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
-코딩 에이전트에게 전체 과정을 맡기고 싶다면 지침 하나만 건네십시오:
+키워드 검색은 기본 키 없는 모드에서 BM25를 통해 적중해야 합니다. 데모의 `database performance optimization` 쿼리는 의도적으로 시맨틱 쿼리이며, 임베딩 프로바이더가 설정되지 않으면 결과가 0개일 수 있습니다.
+
+코딩 에이전트에게 전체 과정을 맡기고 싶다면 지침 하나만 건네주십시오:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-`agentmemory connect `로 언제든지 더 많은 에이전트를 연결할 수 있습니다 — 20개 어댑터는 [모든 에이전트와 호환](#works-with-every-agent)에 나열되어 있습니다. 전체 명령 레퍼런스는 [빠른 시작](#quick-start)에 있습니다.
+`agentmemory connect `로 언제든지 더 많은 에이전트를 연결할 수 있습니다 — 20개의 어댑터가 [모든 에이전트와 호환](#works-with-every-agent)에 나열되어 있습니다. 전체 명령 레퍼런스는 [빠른 시작](#quick-start)에 있습니다.
Windows
-가장 빠른 경로는 WSL2입니다. 네이티브 Windows 엔진 설정은 수동이며(약 10~20분), `agentmemory connect`는 현재 그곳에서 지원되지 않습니다. 단계별 방법은 [Windows 노트](#windows)를 참고하십시오.
+가장 빠른 경로는 WSL2입니다. 네이티브 Windows 엔진 설정은 고정 버전인 v0.22.1 ZIP 파일을 다운로드하고 `iii.exe`를 수동으로 압축 해제해야 합니다. CLI는 이를 자동으로 압축 해제하지 않습니다. Docker Desktop도 지원됩니다. 단계별 방법은 [Windows 노트](#windows)를 참고하십시오.
@@ -107,15 +140,15 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
전역 설치 / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+위의 npx 명령이 여전히 표준적인 신규 설치 경로이며, 전역 prefix 권한 문제를 피할 수 있습니다.
+
-npx가 이전 버전을 제공하는 경우
+npx가 오래된 버전을 제공하는 경우
npx는 버전별로 캐싱합니다. `npx -y @agentmemory/agentmemory@latest`로 최신 버전을 강제하거나, `rm -rf ~/.npm/_npx`로 캐시를 한 번 비우십시오(macOS/Linux; Windows에서는 `%LOCALAPPDATA%\npm-cache\_npx`를 삭제).
@@ -124,7 +157,7 @@ npx는 버전별로 캐싱합니다. `npx -y @agentmemory/agentmemory@latest`로
이미 자체 iii 엔진을 실행 중인 경우
-agentmemory는 iii-engine v0.11.2를 고정하며 다른 버전에는 연결되지 않습니다(워커가 다른 엔진의 프로토콜을 말할 수 없습니다). 다른 엔진을 중지한 후 `npx -y @agentmemory/agentmemory@latest`를 실행하십시오. 고정된 v0.11.2를 `~/.agentmemory/bin`에 설치·실행하며, 기존 `iii`는 건드리지 않습니다.
+agentmemory는 iii-engine v0.22.1을 고정하며 다른 버전에는 연결하지 않습니다(워커가 다른 엔진의 프로토콜을 말할 수 없기 때문입니다). 다른 엔진을 중지한 다음 `npx -y @agentmemory/agentmemory@latest`를 실행하십시오. 이 명령은 고정된 v0.22.1을 `~/.agentmemory/bin`에 설치하고 실행하며, 사용자의 기존 `iii`는 그대로 둡니다.
@@ -132,110 +165,170 @@ agentmemory는 iii-engine v0.11.2를 고정하며 다른 버전에는 연결되
-agentmemory는 hooks, MCP, REST API를 지원하는 모든 에이전트와 호환됩니다. 모든 에이전트는 동일한 메모리 서버를 공유합니다.
+agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환됩니다. 모든 에이전트가 동일한 메모리 서버를 공유합니다.
-
-
+
+ Claude Code
-native plugin + 12 hooks + MCP
+네이티브 플러그인 + hook 12개 + MCP
- MCP 또는 HTTP를 지원하는 모든 에이전트와 호환됩니다. 서버 하나, 모든 에이전트가 메모리를 공유합니다.
+ MCP 또는 HTTP를 지원하는 모든 에이전트와 호환됩니다. 서버 하나로 모든 에이전트가 메모리를 공유합니다.
---
-세션마다 같은 아키텍처를 설명하고, 같은 버그를 다시 찾고, 같은 선호 사항을 다시 가르치게 됩니다. 내장 메모리(CLAUDE.md, .cursorrules)는 200줄 한도에서 멈추고 금세 낡습니다. agentmemory가 이 문제를 해결합니다. 에이전트의 동작을 조용히 캡처하여 검색 가능한 메모리로 압축하고, 다음 세션이 시작될 때 적절한 컨텍스트를 주입합니다. 명령 하나면 됩니다. 모든 에이전트에서 동작합니다.
+세션마다 같은 아키텍처를 설명하고, 같은 버그를 다시 찾아내고, 같은 선호 사항을 다시 가르쳐야 합니다. 내장 메모리(CLAUDE.md, .cursorrules)는 200줄 한도에 막히고 금방 낡아버립니다. agentmemory가 이 문제를 해결합니다. 에이전트가 하는 일을 조용히 캡처하고, 검색 가능한 메모리로 압축한 다음, 다음 세션이 시작될 때 올바른 컨텍스트를 주입합니다. 명령 하나면 충분하며, 여러 에이전트에서 동일하게 동작합니다.
-**무엇이 바뀌는가:** 세션 1에서 JWT 인증을 설정합니다. 세션 2에서 rate limiting을 요청합니다. 에이전트는 이미 인증이 `src/middleware/auth.ts`의 jose 미들웨어로 처리된다는 것, 테스트가 토큰 검증을 다룬다는 것, 그리고 Edge 호환성 때문에 jsonwebtoken 대신 jose를 선택했다는 것을 알고 있으며, 다시 설명할 필요도 복사·붙여넣기도 없습니다.
+**무엇이 바뀌는가:** 세션 1에서 JWT 인증을 설정합니다. 세션 2에서 rate limiting을 요청합니다. 에이전트는 이미 인증이 `src/middleware/auth.ts`의 jose 미들웨어를 사용한다는 것, 테스트가 토큰 검증을 다룬다는 것, 그리고 Edge 호환성 때문에 jsonwebtoken 대신 jose를 선택했다는 것을 알고 있으므로, 다시 설명할 필요도 복사·붙여넣기도 없습니다.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **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)에서 확인할 수 있습니다.
+기본적으로 agentmemory는 iii-engine 상태를 시작한 저장소 외부에 저장합니다: macOS에서는 `~/Library/Application Support/agentmemory`, Linux에서는 `$XDG_DATA_HOME/agentmemory` 또는 `~/.local/share/agentmemory`, Windows에서는 `%APPDATA%\agentmemory`입니다. 기존의 레거시 `./data/state_store.db` 또는 `./data/iii-config.yaml`이 있으면 이 플랫폼 기본값보다 먼저 인스턴스 0에 대해 재사용됩니다. 위치를 명시적으로 지정하려면 `--data-dir `를 전달하거나 `AGENTMEMORY_DATA_DIR`을 설정하십시오. 둘 중 어느 쪽을 명시해도 레거시 탐색보다 우선합니다:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+네이티브 실행과 Docker 실행은 동일하게 해석된 호스트 디렉터리를 사용합니다. Docker는 이를 `/data`에 바인드 마운트합니다. `--instance 1`은 해석된 디렉터리에 `instance-1`을 덧붙이고, 별도의 기본 포트 4종 세트인 `3211/3212/3213/49234`를 선택합니다.
+
+최신 릴리스 노트: [CHANGELOG.md](../CHANGELOG.md).
---
@@ -281,7 +374,7 @@ npx @agentmemory/agentmemory
> 임베딩 모델: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
-**로컬 재현 방법:** [`eval/README.md`](../eval/README.md), LongMemEval `_s`(공개 500-Q)와 `coding-agent-life-v1`(자체 15-세션 코퍼스)을 위한 어댑터 플러그형 하니스. grep / vector / agentmemory 어댑터를 나란히 평가하고, NDJSON으로 출력하며, 게시된 스코어카드는 [`docs/benchmarks/`](../docs/benchmarks/)에 보관됩니다.
+**로컬 재현 방법:** [`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).
@@ -331,7 +424,7 @@ npx @agentmemory/agentmemory
자동 캡처
-
12 hooks (수동 작업 없음)
+
hook 12개 (수동 작업 없음)
수동 add() 호출
에이전트 자체 편집
수동
@@ -357,7 +450,7 @@ npx @agentmemory/agentmemory
멀티 에이전트
-
MCP + REST + leases + signals
+
MCP + REST + lease + signal
API (조정 없음)
Letta 런타임 내에서만
없음
@@ -422,7 +515,7 @@ npx @agentmemory/agentmemory
실시간 뷰어
-
있음 (port 3113)
+
있음 (포트 3113)
클라우드 대시보드
클라우드 대시보드
웹 UI
@@ -435,7 +528,7 @@ npx @agentmemory/agentmemory
셀프 호스팅
-
예 (기본)
+
예 (기본값)
선택 사항
선택 사항
예
@@ -454,38 +547,63 @@ npx @agentmemory/agentmemory
| 시스템 | ⭐ | 접근 방식 |
|--------|---|-------|
-| Zep / Graphiti | 30K | 시간적 지식 그래프; 게시된 시간 쿼리 결과 중 가장 강력(LongMemEval 63.8%). 다만 그래프가 비동기로 빌드되어 최신 사실이 지연될 수 있음 |
+| Zep / Graphiti | 30K | 시간적 지식 그래프. 게시된 시간 쿼리 결과 중 가장 강력(LongMemEval 63.8%)하지만, 그래프가 비동기로 빌드되어 최신 사실이 지연될 수 있음 |
| Cognee | 30K | 문서-지식 그래프 수집, Python 전용, 세션 캡처보다는 구조화된 엔티티 추출을 위해 설계됨 |
-이들 중 어느 것도 코딩 에이전트 hooks에서 자동 캡처하거나, 로컬 우선 뷰어를 제공하거나, 키 없이 실행되지 않습니다 — agentmemory가 중심에 두고 만들어진 조합입니다.
+이들 중 어느 것도 코딩 에이전트 hook에서 자동 캡처하거나, 로컬 우선 뷰어를 제공하거나, 키 없이 실행되지 않습니다 — agentmemory가 중심에 두고 만들어진 조합입니다.
---
-호환성: 이 릴리스는 안정 버전 `iii-sdk` `^0.11.0`과 iii-engine v0.11.x를 대상으로 합니다.
+호환성: 이 릴리스는 `iii-sdk` 0.22.1을 대상으로 하며 iii-engine을 v0.22.1로 고정합니다.
### 30초 만에 사용해 보기
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest demo
```
-`demo`는 현실적인 세션 3개(JWT 인증, N+1 쿼리 수정, rate limiting)를 시드하고, 그 위에서 시맨틱 검색을 실행합니다. "database performance optimization"으로 검색하면 "N+1 query fix"를 찾는 것을 확인할 수 있는데, 키워드 매칭으로는 불가능한 결과입니다.
+`demo`는 현실적인 세션 3개(JWT 인증, N+1 쿼리 수정, rate limiting)를 시드하고 그 위에서 검색을 실행합니다. 키 없는 설치는 벡터를 비활성화하므로, `mem::search` 키워드 쿼리는 BM25를 통해 적중해야 하는 반면 `database performance optimization`은 결과가 0개로 돌아올 수 있습니다. `smart-search`는 그래프 데이터가 존재하면 구조적 그래프 매치도 추가로 반환할 수 있습니다. 시맨틱 쿼리가 벡터를 통해 N+1 수정 사례를 찾게 하려면 `EMBEDDING_PROVIDER=local`을 설정하고 재시작한 다음, 첫 모델 다운로드가 끝나기를 기다리십시오.
`http://localhost:3113`을 열어서 메모리가 실시간으로 쌓이는 것을 지켜보십시오.
+### 신규 설치 검증 및 재시작 지속성 확인
+
+서버가 실행 중인 상태에서 REST, health, 뷰어, iii 기반 런타임 상태를 검증하십시오:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+시작 시 준비 상태 패널은 네 개의 포트를 모두 확인합니다: 3111의 REST/MCP HTTP, 3112의 iii 스트림, 3113의 뷰어, 49134의 iii 워커 WebSocket입니다. `status`는 agentmemory의 상태와 활성 프로바이더/임베딩 모드를 확인합니다. probe를 저장하고 검색되는지 확인하십시오:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+그런 다음 `npx -y @agentmemory/agentmemory@latest stop`을 실행하고, Terminal 1에서 표준 명령을 다시 시작한 뒤 `/agentmemory/livez`를 기다렸다가 검색을 반복하십시오. probe는 여전히 반환되어야 합니다. 커스텀 `--data-dir`을 선택했다면 재시작 시에도 동일한 디렉터리를 전달하십시오.
+
### 매일 쓰는 명령어
설치와 설정은 위의 [Install](#install)에 있습니다(첫 실행이 안내해 줍니다). 일상적으로는:
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -493,41 +611,43 @@ agentmemory remove # uninstall everything we created
### 세션 리플레이
-agentmemory가 기록한 모든 세션은 재생 가능합니다. 뷰어를 열어 **Replay** 탭을 선택하고 타임라인을 스크럽하면 프롬프트, 도구 호출, 도구 결과, 응답이 별개의 이벤트로 렌더링됩니다. 재생/일시정지, 속도 제어(0.5x ~ 4x), 키보드 단축키(space로 토글, 화살표로 단계 이동)를 모두 지원합니다.
+agentmemory가 기록하는 모든 세션은 재생 가능합니다. 뷰어를 열어 **Replay** 탭을 선택하고 타임라인을 스크럽하면, 프롬프트, 도구 호출, 도구 결과, 응답이 개별 이벤트로 렌더링됩니다. 재생/일시정지, 속도 조절(0.5x ~ 4x), 키보드 단축키(space로 토글, 화살표로 단계 이동)를 모두 지원합니다.
-기존 Claude Code JSONL 트랜스크립트를 가져오려면:
+기존의 Claude Code JSONL 트랜스크립트를 가져오려면:
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
-가져온 세션은 네이티브 세션과 함께 Replay 선택기에 표시됩니다. 내부적으로 각 항목은 별도의 사이드 채널 서버 없이 `mem::replay::load`, `mem::replay::sessions`, `mem::replay::import-jsonl` iii 함수로 라우팅됩니다. 가져온 각 트랜스크립트는 검색을 위해 인덱싱되고, origin 채널 `import`로 스탬프되며, 세션 crystal과 lessons로 마이닝됩니다.
+가져온 세션은 네이티브 세션과 함께 Replay 선택기에 표시됩니다. 내부적으로 각 항목은 별도의 사이드 채널 서버 없이 `mem::replay::load`, `mem::replay::sessions`, `mem::replay::import-jsonl` iii 함수를 통해 라우팅됩니다. 가져온 각 트랜스크립트는 검색을 위해 인덱싱되고, origin 채널 `import`로 스탬프되며, 세션 crystal과 lesson으로 마이닝됩니다.
+
+> **`import-jsonl`을 주요 캡처 경로로 삼는 경우 주의하십시오:** Claude Code의 `cleanupPeriodDays`(`~/.claude/settings.json`, 기본값 **30**)는 그 기간보다 오래된 JSONL 트랜스크립트를 `~/.claude/projects/`에서 자동으로 삭제합니다. 몇 달 된 Claude Code 기록 위에 agentmemory를 새로 설치하면, 30일보다 오래된 것은 첫 가져오기 전에 이미 사라진 상태입니다. `import-jsonl`을 cron으로 실행하거나, `cleanupPeriodDays`를 더 높게 올리거나, 자동 캡처 hook(기본 플러그인 설치 경로)을 연결해서 세션이 살아 있는 동안 매 턴이 agentmemory에 바로 기록되도록 하여 JSONL 정리가 더 이상 문제되지 않게 하십시오.
### 업그레이드 / 유지보수
-로컬 런타임을 의도적으로 업데이트할 때는 maintenance 명령을 사용하십시오:
+로컬 런타임을 의도적으로 업데이트하고자 할 때는 maintenance 명령을 사용하십시오:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, 고정된 Docker 이미지 `iiidev/iii:0.11.2`를 pull할 수 있습니다. 고정되지 않았거나 더 새로운 iii 엔진을 설치하는 일은 절대 없습니다.
+경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, 고정된 Docker 이미지 `iiidev/iii:0.22.1`을 pull할 수 있습니다. 고정되지 않았거나 더 새로운 iii 엔진을 설치하는 일은 절대 없습니다.
-구현 세부 사항은 `src/cli.ts`에 있습니다 (`runUpgrade`는 `src/cli.ts:544-595` 부근 참고).
+구현 세부 사항은 `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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
-#### 플러그인 설치 없이 Claude Code 사용 (MCP-독립형 경로)
+#### 플러그인 설치 없이 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이 조용히 깨질 수 있습니다.
+`/plugin install`을 사용하는 대신 `~/.claude.json`을 통해 agentmemory의 MCP 서버를 직접 연결하면, Claude Code는 `${CLAUDE_PLUGIN_ROOT}`를 해석하지 못하므로 `~/.claude/settings.json`의 hook 스크립트를 절대 경로로 지정해야 합니다. 이런 경로는 보통 agentmemory 버전을 포함하기 때문에(예: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), 다음 업그레이드에서 모든 hook이 조용히 깨질 수 있습니다.
해결책:
@@ -535,14 +655,14 @@ Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal t
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`을 사용합니다.
+이 명령은 현재 설치된 `@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
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
@@ -551,29 +671,43 @@ codex plugin add agentmemory@agentmemory
Codex 플러그인은 Claude Code 플러그인과 동일한 `plugin/` 디렉터리에서 제공됩니다. 다음을 등록합니다:
-- `@agentmemory/mcp`를 MCP 서버로 등록 (`AGENTMEMORY_URL`이 실행 중인 agentmemory 서버를 가리킬 때 54개 도구 모두 프록시. 도달 가능한 서버가 없으면 로컬에서 7개 도구로 폴백)
-- 6개 라이프사이클 hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
-- 호출 가능한 skills 9개: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, 그리고 에이전트가 필요할 때 로드하는 참조 skills 8개(memory discipline, MCP 도구, REST API, 설정, 에이전트, 훅, 아키텍처, skill 작성 가이드)
+- 실행 중인 데몬에 연결되는 번들된 stdio MCP 브리지로, npm 다운로드도 폴백 저장소도 없습니다. 미출시 빌드를 테스트하려면 [로컬 Codex 가이드](../docs/plugins/codex-local.md)를 참고하십시오.
+- 6개의 라이프사이클 hook: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 호출 가능한 skill 9개: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, 그리고 에이전트가 필요할 때 로드하는 참조 skill 8개(memory discipline, MCP 도구, REST API, 설정, 에이전트, hook, 아키텍처, skill 작성 가이드)
-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의 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가 현재 동작하지 않음 (해결책 있음)
+#### Codex hook 신뢰와 호환성
-`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 CLI 0.150.1에서 검증되었습니다. 캡처를 기대하기 전에 플러그인 hooks를 신뢰하십시오. Desktop의 동작은 번들된 런타임에 따라 달라집니다. 해결책을 활성화하기 전에 `/hooks`를 확인하고 캡처된 이벤트가 있는지 확인하십시오.
-업스트림 수정이 적용될 때까지 동일한 hook 명령을 전역 `~/.codex/hooks.json`에 미러링하십시오:
+호스트에 전역 hooks가 필요하다면, 명령을 `~/.codex/hooks.json`에 미러링하십시오. MCP가 이미 연결되어 있다면, 현재 커넥터가 hook 설치에 도달하려면 `--force`가 필요합니다:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-이 명령은 번들된 스크립트의 절대 경로를 참조하는 idempotent 블록을 `~/.codex/hooks.json`에 추가합니다(사용자 스코프에서 `${CLAUDE_PLUGIN_ROOT}` 확장이 필요 없음). agentmemory를 업그레이드한 후 동일한 명령을 다시 실행하여 경로를 갱신하십시오. 동일한 파일의 사용자 항목은 보존되며, 이전 agentmemory 항목만 교체됩니다.
+이 명령은 전역 hooks를 병합하고 agentmemory MCP 항목을 다시 작성하며, 관련 없는 항목은 보존합니다. `--force`를 사용하기 전에 커스텀 agentmemory 엔드포인트 설정을 검토하십시오. 업그레이드한 뒤에는 다시 실행해서 스크립트 경로를 갱신하십시오. 중복 캡처를 피하려면 네이티브 플러그인 hooks나 전역 사본 중 하나만 활성화하십시오.
+
+### GitHub Copilot CLI
+
+VS Code 에이전트 모드에서는 [Copilot MCP 및 자동 캡처 가이드](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions)를 사용하십시오. CLI 커넥터는 VS Code를 구성하지 않습니다.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli`는 `mcpServers.agentmemory`를 `~/.copilot/mcp-config.json`(또는 `COPILOT_HOME`이 설정된 경우 `$COPILOT_HOME/mcp-config.json`)에 병합하고 기존 서버는 그대로 둡니다. 네이티브 Windows에서는 이것이 유일하게 자동화된 `connect` 어댑터입니다. 다른 모든 네이티브 Windows 에이전트는 수동으로 설정해야 합니다. WSL에서의 `connect`는 대상 에이전트가 동일한 WSL 환경에 설치되어 있을 때만 지원됩니다. Copilot은 다음 실행 시 또는 `/mcp` 실행 후에 MCP 서버를 인식합니다. 전체 hook/skill 경험을 원한다면 플러그인도 함께 설치하십시오.
OpenClaw (이 프롬프트를 붙여넣으세요)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -598,7 +732,7 @@ Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. O
Hermes Agent (이 프롬프트를 붙여넣으세요)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -617,11 +751,11 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
### 다른 에이전트
-메모리 서버 시작: `npx @agentmemory/agentmemory`
+메모리 서버 시작: `npx -y @agentmemory/agentmemory@latest`
-#### `npx skills add`를 통한 네이티브 skills (50+ 에이전트)
+#### `npx skills add`를 통한 네이티브 skill (50+ 에이전트)
-agentmemory는 Claude Code 스타일의 `/SKILL.md` 형식으로 17개의 skills를 제공합니다: 9개의 호출 가능한 액션 skills(`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`)와 에이전트가 필요할 때 로드하는 8개의 레퍼런스 skills(`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`)입니다. 레퍼런스 skills는 소스에서 생성된 데이터 표를 담고 있어 절대 드리프트하지 않습니다. vercel-labs의 [`skills`](https://npmjs.com/package/skills) CLI가 50개 이상의 에이전트(Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf 등)에서 호출한 에이전트의 네이티브 skill 디렉터리에 이를 자동 설치합니다:
+agentmemory는 Claude-Code 스타일의 `/SKILL.md` 형식으로 17개의 skill을 제공합니다: 호출 가능한 action skill 9개(`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`)와 에이전트가 필요할 때 로드하는 참조 skill 8개(`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`)입니다. 참조 skill은 소스에서 생성된 데이터 표를 담고 있어 절대 어긋나지 않습니다. vercel-labs의 [`skills`](https://npmjs.com/package/skills) CLI는 호출한 에이전트의 네이티브 skill 디렉터리에, 50+개의 에이전트(Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf 등)에 걸쳐 자동으로 설치합니다:
```bash
npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
@@ -631,14 +765,14 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
이는 `agentmemory connect `와 **상호 보완적**입니다:
-- `agentmemory connect `는 도구를 사용할 수 있도록 MCP 서버 설정을 기록합니다.
-- `npx skills add rohitg00/agentmemory`는 에이전트가 언제 도구를 호출해야 하는지 알도록 skills를 설치합니다.
+- `agentmemory connect `는 MCP 서버 설정을 작성해서 도구를 사용할 수 있게 만듭니다.
+- `npx skills add rohitg00/agentmemory`는 skill을 설치해서 에이전트가 언제 호출해야 하는지 알게 합니다.
-skills CLI가 아직 지원하지 않는 일부 에이전트(Zed v1.3.x 이하)의 경우, 15개의 SKILL.md 파일을 에이전트의 네이티브 skill 디렉터리에 직접 넣으십시오. 동일한 형식이 어디서나 동작합니다.
+skill CLI가 아직 다루지 않는 일부 에이전트(Zed v1.3.x 이하)의 경우, 17개의 SKILL.md 파일을 에이전트의 네이티브 skill 디렉터리에 직접 넣으십시오. 동일한 형식이 어디서나 동작합니다.
#### 표준 MCP 블록
-agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw)에서 **동일한 MCP 서버 블록**입니다:
+agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw)에서 **동일한 MCP 서버 블록**입니다:
```json
"agentmemory": {
@@ -651,44 +785,46 @@ agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Curso
}
```
-**호스트 설정 파일의 기존 `mcpServers` 객체에 이 항목을 병합하십시오.** 파일 전체를 교체하지 마십시오. 파일에 이미 다른 서버가 있다면, `agentmemory`를 `mcpServers` 안의 또 다른 키로 옆에 추가하십시오. `mcpServers` 자체가 없다면 `{ "mcpServers": { ... } }` 안에 블록을 붙여넣으십시오. `${VAR}` 자리표시자는 MCP 서버 실행 시 셸에서 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`을 상속하며, 설정되지 않은 변수는 빈 문자열로 전달되고 shim은 `http://localhost:3111`로 폴백합니다. 한 번 연결한 항목으로 로컬과 원격(k8s / 리버스 프록시) 배포를 모두 커버합니다.
+**이 항목을 호스트 설정 파일의 기존 `mcpServers` 객체에 병합하십시오**. 파일을 통째로 교체하지 마십시오. 파일에 이미 다른 서버가 있다면, `mcpServers` 안에 또 다른 키로 `agentmemory`를 추가하십시오. `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` 블록. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin`이 MCP 항목을 병합하고, `--with-hooks`는 Devin의 소문자 tool matcher를 사용하는 6개의 네이티브 자동 캡처 hooks(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd)를 추가합니다. `devin mcp list`와 devin 내부의 `/hooks`로 확인하세요. |
-| **Devin (클라우드)** | Settings → Connections → MCP servers | 커스텀 MCP(STDIO) 추가: command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL`을 네트워크로 접근 가능한 agentmemory 배포로 지정하고 `AGENTMEMORY_SECRET` 설정(클라우드 세션은 localhost에 접근할 수 없음 — [`deploy/`](../deploy/) 참고). |
+| **Cursor (MCP만)** | `~/.cursor/mcp.json` | `mcpServers`에 병합하거나 `agentmemory connect cursor`를 사용하십시오. 웹사이트에서 원클릭 딥링크도 제공합니다. |
+| **Cursor (전체 플러그인)** | `.cursor-plugin/` | Cursor Marketplace 등록(심사 진행 중) 또는 Cursor Settings → Plugins → 로컬 체크아웃. 자동 캡처 hook 7개(sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + skill 17개 + MCP 서버를 등록하며, `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`은 Cursor 플러그인 대시보드에서 관리됩니다. Cursor IDE와 `cursor-agent` CLI 모두에서 동작합니다. CLI print 모드 프롬프트는 세션 종료 시 세션 트랜스크립트로부터 소급 채워집니다. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers`에 병합하십시오. 수정 후 Claude Desktop을 재시작하십시오. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP 설정 (Settings UI → MCP Servers → Edit) | 동일한 `mcpServers` 블록. |
+| **Devin CLI (MCP + hook)** | `~/.config/devin/config.json` | `agentmemory connect devin`이 MCP 항목을 병합하고, `--with-hooks`는 Devin의 소문자 tool matcher를 사용하는 6개의 네이티브 자동 캡처 hook(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd)을 추가합니다. `devin mcp list`와 devin 안에서 `/hooks`로 확인하십시오. |
+| **Devin CLI (전체 플러그인)** | `plugin/.devin-plugin/` | 체크아웃에서 `devin plugins install ./plugin`을 실행하면 17개의 skill 전부가 `/agentmemory:` 슬래시 명령으로, 그리고 MCP 서버가 함께 등록됩니다. Devin 플러그인 hook은 `SessionStart`/`SessionEnd`를 발생시킬 수 없으므로, 전체 세션 캡처를 위해 `connect devin --with-hooks`와 함께 사용하십시오. |
+| **Devin (클라우드)** | Settings → Connections → MCP servers | 커스텀 MCP(STDIO)를 추가하십시오: command `npx`, args `-y @agentmemory/mcp@latest`, env로 네트워크에서 도달 가능한 agentmemory 배포를 가리키는 `AGENTMEMORY_URL`과 `AGENTMEMORY_SECRET`(클라우드 세션은 localhost에 도달할 수 없습니다 — [`deploy/`](../deploy/) 참고). 시크릿은 Devin Secrets에 저장한 다음, "Test listing tools"로 54개 도구가 모두 나타나는지 확인하십시오. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (자동 병합). |
-| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli`가 `mcpServers.agentmemory`를 병합. Copilot은 다음 실행 또는 `/mcp`에서 인식. |
-| **GitHub Copilot CLI (full plugin)** | Copilot 플러그인 설치 | GitHub 하위 디렉터리의 플러그인은 `copilot plugin install rohitg00/agentmemory:plugin`. |
-| **OpenClaw** | OpenClaw MCP config | 동일한 `mcpServers` 블록. 더 깊게: `openclaw plugins install ./integrations/openclaw`는 OpenClaw의 메모리 슬롯을 차지합니다(`memory-core`에서 자동 전환). `plugins.entries.agentmemory.hooks.allowConversationAccess=true`를 설정하지 않으면 턴 캡처가 조용히 차단됩니다. [`integrations/openclaw`](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) + 17 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. 프로젝트 어트리뷰션은 세션 단위이므로, 하나의 OpenCode 프로세스가 여러 저장소에 걸쳐 있어도 각 세션은 자기 프로젝트 아래에 기록됩니다. 두 개의 슬래시 명령(`/recall`, `/remember`). `plugin/opencode/`를 OpenCode workspace에 복사한 후 `opencode.json`에 플러그인 항목을 추가하십시오. 전체 hook 표 + gap 분석은 [`plugin/opencode/README.md`](../plugin/opencode/README.md) 참고. |
-| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi`가 번들된 확장을 pi의 자동 발견 디렉터리에 설치합니다(에이전트 시작 시 리콜, 에이전트 종료 시 캡처, `memory_search` / `memory_save` / `memory_health` 도구, `/agentmemory-status`). 실행 중인 pi에서 `/reload`를 하면 인식됩니다. [`integrations/pi`](../integrations/pi/)는 pi 패키지이기도 합니다(체크아웃에서 `pi install ./integrations/pi`). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory`가 6개 hook로 구성된 메모리 프로바이더(프리페치, 턴 캡처, 세션 종료, 사전 압축, MEMORY.md 미러링, 시스템 프롬프트 블록)를 활성화합니다. `hermes plugins doctor`와 `hermes memory status`로 검증하세요. [`integrations/hermes`](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 이후 사용. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. `agy` CLI는 위의 Antigravity IDE와 별도로 `~/.gemini/` 아래에 자체 설정을 유지합니다. `~/.gemini/config/hooks.json`을 통한 네이티브 자동 캡처는 `--with-hooks`를 전달하십시오. |
-| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro`가 사용자 레벨 설정을 기록. 워크스페이스 오버라이드는 코드 옆 `.kiro/settings/mcp.json`에. |
-| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp`가 표준 `mcpServers` 블록을 기록. Warp는 `.claude/skills/`에서 skills도 자동 발견합니다. Claude Code 플러그인이 설치되면 8개의 agentmemory skills(`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`)가 Warp의 슬래시 명령 팔레트에 네이티브로 나타납니다. |
-| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline`이 표준 `mcpServers` 블록을 기록. VS Code 확장 사용자는 Cline Settings → MCP Servers → Edit JSON에서 동일한 블록을 붙여넣으십시오. |
-| **Continue.dev** | `~/.continue/config.yaml` (선호) 또는 `config.json` (레거시) | `agentmemory connect continue`는 둘 다 없으면 `config.yaml`을 새로 생성하고, 기존 `config.json`이 있으면 수정합니다. **이미 `config.yaml`이 있다면** 어댑터는 `mcpServers:` 아래에 붙여넣을 정확한 블록을 출력합니다. 주석과 앵커를 안전하게 보존하려면 패키지가 포함하지 않는 YAML 파서가 필요하기 때문에 yaml을 조용히 다시 쓰지 않습니다. Continue는 `mcpServers`에 (객체가 아닌) 배열 형식을 사용합니다. |
-| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed`는 `context_servers`(Zed의 키, `mcpServers` 아님) 아래에 기록. 원격 MCP 서버는 대신 `{"url": "..."}`로 연결할 수 있습니다. |
-| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid`가 표준 `mcpServers` 블록을 기록. 프로젝트 스코프 오버라이드는 `/.factory/mcp.json`에. 네이티브 자동 캡처는 `--with-hooks`를 전달하십시오. |
-| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh`는 모든 Harness 프로필이 로드하는 홈 레벨 패치 레이어에 `@deepseek-ai/dsh-mcp-client` 행을 추가합니다. 도구는 `mcp__agentmemory__*`로 등록됩니다. 자동 캡처도 연결하려면 `--with-hooks`를 전달하십시오: 번들된 Claude Code hook 스크립트가 `$DSH_HOME/agentmemory.hooks.json`에 기록된 manifest를 통해 Harness의 퍼스트파티 `@deepseek-ai/dsh-hooks-claude-code` 브리지(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop)로 실행됩니다. `DSH_HOME`이 설정되지 않으면 기본값은 `~/.dsh`입니다. |
-| **Goose** | Goose MCP settings UI | 동일한 `mcpServers` 블록. `goose configure` → Add Extension → MCP를 사용하십시오. `~/.config/goose/config.yaml`의 직접 YAML 편집도 지원되지만 스키마는 `extensions:` + `cmd`를 사용합니다(`mcpServers:` + `command` 아님). |
-| **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)로 지정하십시오.
+| **GitHub Copilot CLI (MCP만)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli`가 `mcpServers.agentmemory`를 병합합니다. Copilot은 다음 실행 시 또는 `/mcp`에서 이를 인식합니다. |
+| **GitHub Copilot CLI (전체 플러그인)** | Copilot 플러그인 설치 | GitHub 서브디렉터리의 플러그인을 위해 `copilot plugin install rohitg00/agentmemory:plugin`. |
+| **OpenClaw** | OpenClaw MCP 설정 | 동일한 `mcpServers` 블록. 더 깊은 통합: `openclaw plugins install ./integrations/openclaw`는 OpenClaw의 memory 슬롯을 차지합니다(`memory-core`에서 자동 전환). `plugins.entries.agentmemory.hooks.allowConversationAccess=true`를 설정하지 않으면 턴 캡처가 조용히 차단됩니다. [`integrations/openclaw`](../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 + 라이프사이클 hook 6개 + skill 17개를 등록합니다. 호스트에서 hooks를 신뢰하고 캡처를 확인하십시오. [Codex 설정 및 검증](../docs/plugins/codex-local.md) 참고. |
+| **OpenCode (MCP만)** | `opencode.json` | 다른 형태: 최상위 `mcp` 키, command는 배열: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (전체 플러그인)** | `plugin/opencode/` | 세션 라이프사이클, 메시지, 도구, 오류를 다루는 자동 캡처 hook 22개. 프로젝트 귀속은 세션 단위이므로, 여러 저장소를 넘나드는 OpenCode 프로세스 하나도 각 세션을 자신의 프로젝트 아래에 기록합니다. 슬래시 명령 2개(`/recall`, `/remember`). `plugin/opencode/`를 OpenCode workspace에 복사하고 플러그인 항목을 `opencode.json`에 추가하십시오. 전체 hook 표와 gap 분석은 [`plugin/opencode/README.md`](../plugin/opencode/README.md)를 참고하십시오. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi`는 번들된 확장을 pi의 자동 탐색 디렉터리에 설치합니다(에이전트 시작 시 recall, 에이전트 종료 시 capture, `memory_search` / `memory_save` / `memory_health` 도구, `/agentmemory-status`). 실행 중인 pi에서 `/reload`하면 적용됩니다. [`integrations/pi`](../integrations/pi/)는 pi 패키지이기도 합니다(체크아웃에서 `pi install ./integrations/pi`). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory`로 6-hook 메모리 프로바이더(prefetch, 턴 캡처, 세션 종료, 압축 전 처리, MEMORY.md 미러링, 시스템 프롬프트 블록)를 얻습니다. `hermes plugins doctor`와 `hermes memory status`로 검증하십시오. [`integrations/hermes`](../integrations/hermes/) 참고. |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen`은 표준 `mcpServers` 블록을 작성합니다. hook payload는 Claude Code와 필드 호환되므로, 기존 12-hook 스크립트가 수정 없이 동작합니다. 동일한 `settings.json`의 `hooks` 섹션을 통해 연결하십시오. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks`는 공유 커스터마이징 디렉터리에 MCP와 캡처 hooks를 설치합니다. [Antigravity 설정 및 제한사항](../docs/plugins/antigravity.md) 참고. |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks`는 현재 IDE 버전과 동일한 MCP 및 hook 설정을 사용합니다. 기존 설치는 `--force`로 갱신해야 합니다. [업그레이드 노트](../docs/plugins/antigravity.md) 참고. |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro`는 사용자 수준 설정을 작성합니다. workspace 재정의는 코드 옆의 `.kiro/settings/mcp.json`에 둡니다. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp`는 표준 `mcpServers` 블록을 작성합니다. Warp는 `.claude/skills/`에서 skill도 자동으로 탐색합니다. Claude Code 플러그인을 설치하면 8개의 agentmemory skill(`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`)이 Warp의 슬래시 명령 팔레트에 네이티브로 나타납니다. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline`은 표준 `mcpServers` 블록을 작성합니다. VS Code 확장 사용자는 Cline Settings → MCP Servers → Edit JSON을 통해 동일한 블록을 붙여넣으십시오. |
+| **Continue.dev** | `~/.continue/config.yaml` (권장) 또는 `config.json` (레거시) | `agentmemory connect continue`는 둘 다 없으면 `config.yaml`을 새로 생성하고, 기존 `config.json`이 있으면 이를 수정합니다. **이미 `config.yaml`이 있다면** 어댑터는 `mcpServers:` 아래에 붙여넣을 정확한 블록을 출력합니다. 주석과 anchor를 안전하게 보존하려면 패키지가 포함하지 않은 YAML 파서가 필요하므로, yaml을 조용히 재작성하지는 않습니다. Continue는 `mcpServers`에 객체가 아닌 배열 형태를 사용합니다. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed`는 `context_servers`(Zed의 키이며 `mcpServers`가 아닙니다) 아래에 작성합니다. 원격 MCP 서버는 대신 `{"url": "..."}`로 연결할 수 있습니다. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid`는 표준 `mcpServers` 블록을 작성합니다. 프로젝트 범위 재정의는 `/.factory/mcp.json`에 둡니다. 네이티브 자동 캡처를 위해서는 `--with-hooks`를 전달하십시오. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh`는 모든 Harness 프로필이 로드하는 홈 수준 patch 레이어에 `@deepseek-ai/dsh-mcp-client` 행을 추가합니다. 도구는 `mcp__agentmemory__*`로 등록됩니다. 자동 캡처까지 연결하려면 `--with-hooks`를 전달하십시오: 번들된 Claude Code hook 스크립트는 Harness의 퍼스트파티 `@deepseek-ai/dsh-hooks-claude-code` 브리지(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop)를 통해, `$DSH_HOME/agentmemory.hooks.json`에 작성된 매니페스트를 거쳐 실행됩니다. `DSH_HOME`이 설정되지 않으면 기본값은 `~/.dsh`입니다. |
+| **Goose** | Goose MCP 설정 UI | 동일한 `mcpServers` 블록. `goose configure` → Add Extension → MCP를 사용하십시오. `~/.config/goose/config.yaml`에서 직접 YAML을 편집할 수도 있지만, 스키마는 `mcpServers:` + `command`가 아니라 `extensions:` + `cmd`를 사용합니다. |
+| **Aider** | 해당 없음 | REST API에 직접 요청하십시오: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **모든 에이전트 (32+)** | 해당 없음 | `npx skillkit install agentmemory`가 호스트를 자동으로 감지해 병합합니다. |
+
+**샌드박스 MCP 클라이언트**(Flatpak / Snap / 제한적인 컨테이너)가 호스트의 `localhost`에 도달할 수 없는 경우: `env` 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`도 설정하고, `AGENTMEMORY_URL`을 샌드박스가 실제로 도달할 수 있는 경로(예: LAN IP)로 지정하십시오.
### 프로그래매틱 액세스 (Python / Rust / Node)
-agentmemory는 핵심 작업을 iii 함수(`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`)로 등록합니다. iii SDK가 있는 모든 언어에서 언어별 별도의 REST 클라이언트 없이 `ws://localhost:49134`로 직접 호출할 수 있습니다.
+agentmemory는 핵심 작업을 iii 함수(`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`)로 등록합니다. iii SDK가 있는 모든 언어는 언어별로 별도의 REST 클라이언트 없이 `ws://localhost:49134`를 통해 이를 직접 호출할 수 있습니다.
```bash
pip install iii-sdk # Python
@@ -708,7 +844,7 @@ iii.trigger({
})
```
-작동 예제: [`examples/python/`](../examples/python/) (퀵스타트 + 관측/리콜 흐름). iii 런타임이 없는 호스트를 위해 `:3111`의 REST는 그대로 사용 가능합니다.
+실제 예제: [`examples/python/`](../examples/python/) (퀵스타트 + 관측/리콜 흐름). iii 런타임이 없는 호스트에서도 `:3111`의 REST는 계속 사용할 수 있습니다.
### 소스에서 빌드
@@ -717,39 +853,43 @@ 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를 시작하고, 선택한 경우에는 Docker Compose를 사용합니다. REST, 스트림, 뷰어는 기본적으로 `127.0.0.1`에 바인딩됩니다. macOS/Linux 자동 바이너리 설치 경로에는 `curl`, POSIX `sh`, `tar`가 필요합니다.
-`iii-engine`을 수동으로 설치하십시오. **agentmemory는 현재 `iii-engine`을 `v0.11.2`로 고정합니다**. `v0.11.6`은 모든 것을 `iii worker add`를 통해 샌드박스화하는 새 모델을 도입했는데 agentmemory는 아직 이를 위해 리팩터링되지 않았기 때문입니다. 리팩터링이 완료되면 고정이 풀립니다. 수동으로 sandbox 모델로 마이그레이션했다면 `AGENTMEMORY_III_VERSION=`으로 덮어쓰십시오.
+`iii-engine`을 수동으로 설치하십시오. **agentmemory는 현재 `iii-engine`을 `v0.22.1`로 고정합니다**. 이는 `iii-sdk` 의존성과 동일한 릴리스입니다. 워커는 해당 엔진의 wire 프로토콜을 사용하고, 0.20.0에서 SDK 표면이 재구성되었기 때문에 둘은 agentmemory 릴리스에서 함께 올라갑니다. 직접 운영하는 엔진이 일치한다고 확신한다면 `AGENTMEMORY_III_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에 추가
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `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.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1)에서 `iii-x86_64-pc-windows-msvc.zip`을 다운로드하고 `iii.exe`를 `%USERPROFILE%\.agentmemory\bin\iii.exe`에 압축 해제하십시오
-또는 Docker 사용 (번들된 `docker-compose.yml`이 `iiidev/iii:0.11.2`를 pull). 전체 문서: [iii.dev/docs](https://iii.dev/docs).
+모든 아카이브는 릴리스 페이지에 대응하는 `.sha256` 파일을 가지고 있습니다. 플랫폼을 바꿀 때는 위 검증에서 그 파일의 해시를 사용하십시오(Windows에서는 `Get-FileHash`). `npx @agentmemory/agentmemory`의 자동 설치기는 이 해시들을 고정해 두고, 일치하지 않는 아카이브는 거부합니다.
+
+또는 Docker를 사용하십시오(번들된 `docker-compose.yml`은 `iiidev/iii:0.22.1`을 pull합니다). 전체 문서: [iii.dev/docs](https://iii.dev/docs).
### Windows
-agentmemory는 Windows 10/11에서 실행되지만, Node.js 패키지만으로는 충분하지 않습니다. 별도의 네이티브 바이너리인 `iii-engine` 런타임이 백그라운드 프로세스로 필요합니다. 공식 업스트림 인스톨러는 `sh` 스크립트이고 PowerShell 인스톨러나 scoop/winget 패키지는 현재 없으므로, Windows 사용자에게는 두 가지 경로가 있습니다:
+agentmemory는 Windows 10/11에서 동작하지만, Node.js 패키지만으로는 충분하지 않습니다. 고정된 iii-engine v0.22.1 런타임도 백그라운드 프로세스로 필요합니다. CLI는 Windows ZIP을 자동으로 압축 해제하지 않으므로, 네이티브 Windows 사용자는 `iii.exe`를 수동으로 설치하거나, WSL2를 사용하거나, Docker Desktop을 선택해야 합니다.
+
+네이티브 Windows에서 자동화된 MCP 연결은 `agentmemory connect copilot-cli`만 지원합니다. Claude Code, Codex, Cursor, 그리고 그 외 모든 네이티브 Windows 에이전트의 경우, [다른 에이전트](#other-agents)에서 수동 MCP 블록을 복사해 해당 에이전트의 Windows 설정에 넣으십시오. WSL에서 `connect`를 실행하는 것은 대상 에이전트도 동일한 WSL 환경에 설치되어 있을 때만 적절합니다. 이는 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)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**옵션 B: Docker Desktop**
@@ -757,56 +897,73 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
-**옵션 C: 독립형 MCP만 사용 (엔진 없음).** 에이전트용 MCP 도구만 필요하고 REST API, 뷰어, cron 작업이 필요하지 않다면 엔진을 완전히 건너뛸 수 있습니다:
+**옵션 C: 독립형 MCP만 사용 (엔진 없음).** 에이전트에 MCP 도구만 필요하고 REST API, 뷰어, cron 작업이 필요 없다면, 엔진을 완전히 건너뛰십시오:
```powershell
-npx -y @agentmemory/agentmemory mcp
+npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
-**Windows 진단:** `npx @agentmemory/agentmemory`가 실패하면 `--verbose`로 다시 실행하여 실제 엔진 stderr를 확인하십시오. 일반적인 실패 모드:
+**Windows 진단:** `npx -y @agentmemory/agentmemory@latest`가 실패하면 `--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 ` 사용 |
-| Docker가 설치되어 있어도 Docker 폴백을 건너뜀 | Docker Desktop이 실제로 실행 중인지 확인 (시스템 트레이 아이콘) |
+| `The engine process started but the REST API never responded.` | 파생된 네 개의 포트가 모두 비어 있는지 확인하고, 고정된 `iii.exe`가 계속 살아 있는지 확인한 다음, `--verbose`로 다시 실행해서 캡처된 엔진 stderr를 살펴보십시오 |
+| `Could not start iii-engine` | `iii.exe`도 Docker도 설치되어 있지 않습니다. 위의 옵션 A 또는 B를 참고하십시오 |
+| 포트 충돌 | `netstat -ano \| findstr :3111`로 무엇이 바인딩되어 있는지 확인한 다음 종료하거나 `--port `을 사용하십시오 |
+| Docker가 설치되어 있는데도 Docker 폴백이 건너뛰어짐 | Docker Desktop이 실제로 실행 중인지 확인하십시오(시스템 트레이 아이콘) |
-> 참고: iii **엔진**은 사전 빌드된 바이너리이며 cargo 크레이트가 아니므로, `cargo install`로 설치하려 하지 마세요. (iii **SDK**는 crates.io, npm, PyPI에 게시되어 있지만 agentmemory에는 필요하지 않습니다.) 지원되는 엔진 설치 방법은 모두 v0.11.2에 고정되어 있습니다: 위의 사전 빌드된 v0.11.2 바이너리, 버전 핀**을 포함한** 업스트림 `sh` 설치 스크립트 `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux), 그리고 Docker 이미지 `iiidev/iii:0.11.2`. 그냥 `install.sh | sh`를 실행하면 **최신** 엔진이 설치되는데, agentmemory는 이를 지원하지 않습니다; 항상 `VERSION=0.11.2`를 전달하세요. 가장 쉬운 방법은 그냥 `npx @agentmemory/agentmemory`를 실행하는 것입니다. 이 명령이 고정된 엔진을 `~/.agentmemory/bin`에 가져다 줍니다.
+> 참고: iii **엔진**은 cargo crate가 아니라 사전 빌드된 바이너리이므로, `cargo install`을 시도하지 마십시오. (iii **SDK**는 crates.io, npm, PyPI에 게시되어 있지만, agentmemory에는 필요하지 않습니다.) 지원되는 엔진 설치 방법은 모두 v0.22.1에 고정되어 있습니다: 위의 사전 빌드 바이너리, agentmemory의 macOS/Linux 자동 설치 경로(`curl`, POSIX `sh`, `tar` 필요), 그리고 Docker 이미지 `iiidev/iii:0.22.1`입니다. 업스트림의 순수한 `install.sh | sh`는 최신 엔진을 설치하는데, agentmemory는 이를 지원하지 않습니다. `npx -y @agentmemory/agentmemory@latest`를 사용하십시오. macOS/Linux에서는 고정된 엔진을 `~/.agentmemory/bin`으로 가져옵니다.
---
배포
-매니지드 호스트용 원클릭 템플릿입니다. 각각은 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합니다.
+매니지드 호스트를 위한 원클릭 템플릿입니다. 각 템플릿은 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합니다.
-Render의 원클릭 배포 버튼은 저장소 루트에 `render.yaml`이 필요한데, 우리는 의도적으로 이를 깨끗하게 유지합니다. [`deploy/render/`](../deploy/render/README.md)에 문서화된 Render Blueprint 플로우를 사용하여 in-repo blueprint를 수동으로 가리키도록 하십시오.
+Render의 원클릭 배포 버튼은 저장소 루트에 `render.yaml`이 있어야 하는데, 이는 의도적으로 깨끗하게 비워 두었습니다. [`deploy/render/`](.././deploy/render/README.md)에 문서화된 Render Blueprint 흐름을 사용해 저장소 내 blueprint를 수동으로 지정하십시오.
-전체 설정 세부 사항(HMAC 캡처, 뷰어 SSH 터널, 로테이션, 백업, 비용 하한)은 [`deploy/`](../deploy/README.md)에 있습니다:
+전체 설정 세부 사항(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 스택, 호스트와 데이터를 직접 소유.
+- [`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 터널 패턴을 문서화합니다.
+`3111` 포트만 게시됩니다. `3113`의 뷰어는 컨테이너 내부에서
+loopback에 바인딩된 채로 유지됩니다. 각 템플릿의 README는 그곳에
+도달하기 위한 SSH 터널 패턴을 문서화합니다.
---
-모든 코딩 에이전트는 세션이 끝나면 모든 것을 잊고, 새 세션마다 스택을 다시 설명하는 것으로 시작하게 됩니다. agentmemory는 백그라운드에서 실행되어 그 단계를 없앱니다.
+모든 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버리고, 새 세션이 시작될 때마다 사용자가 스택을 다시 설명해야 합니다. agentmemory는 백그라운드에서 실행되며 이 과정을 없애줍니다.
```text
Session 1: "Add auth to the API"
@@ -824,16 +981,16 @@ Session 2: "Now add rate limiting"
### 내장 에이전트 메모리와의 비교
-모든 AI 코딩 에이전트는 내장 메모리와 함께 제공됩니다: Claude Code에는 `MEMORY.md`가 있고, Cursor에는 notepad가, Cline에는 memory bank가 있습니다. 이들은 포스트잇처럼 동작합니다. agentmemory는 포스트잇 뒤에 있는 검색 가능한 데이터베이스입니다.
+모든 AI 코딩 에이전트는 내장 메모리를 함께 제공합니다: Claude Code에는 `MEMORY.md`가, Cursor에는 notepad가, Cline에는 memory bank가 있습니다. 이들은 포스트잇처럼 동작합니다. agentmemory는 그 포스트잇 뒤에 있는 검색 가능한 데이터베이스입니다.
-| | 내장 (CLAUDE.md) | agentmemory |
+| | 내장 메모리 (CLAUDE.md) | agentmemory |
|---|---|---|
| 규모 | 200줄 한도 | 무제한 |
| 검색 | 모든 것을 컨텍스트에 로드 | BM25 + vector + graph (top-K만) |
-| 토큰 비용 | 관측 240개 기준 22K+ | ~1,900 토큰 (92% 적음) |
-| 크로스 에이전트 | 에이전트별 파일 | MCP + REST (모든 에이전트) |
-| 조정 | 없음 | leases, signals, actions, routines |
-| 가시성 | 파일 수동 읽기 | :3113의 실시간 뷰어 |
+| 토큰 비용 | 관측 240개 기준 22K+ | ~1,900 토큰 (92% 감소) |
+| 에이전트 간 | 에이전트별 파일 | MCP + REST (모든 에이전트) |
+| 조정 | 없음 | lease, signal, action, routine |
+| 관측 가능성 | 파일을 수동으로 읽기 | :3113의 실시간 뷰어 |
---
@@ -846,9 +1003,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -864,7 +1022,7 @@ SessionStart hook fires
### 4-Tier 메모리 통합
-수면 통합을 포함해, 인간 뇌가 메모리를 처리하는 방식을 모델로 했습니다.
+수면 통합을 포함해 인간 뇌가 메모리를 처리하는 방식을 모델로 했습니다.
| Tier | 무엇 | 비유 |
|------|------|---------|
@@ -893,71 +1051,75 @@ SessionStart hook fires
| 기능 | 설명 |
|---|---|
-| **자동 캡처** | 모든 도구 사용을 hooks로 기록, 수동 작업 없음 |
-| **시맨틱 검색** | BM25 + vector + 지식 그래프, RRF 융합 |
-| **메모리 진화** | 버저닝, supersession, 관계 그래프 |
-| **리콜 위생** | 대체(superseded)된 메모리 버전은 검색 인덱스에서 제거됨; KV의 버전 체인이 전체 이력을 유지 |
-| **유사 중복 힌트** | 새 콘텐츠가 기존 메모리와 매우 유사하면 저장 시 참고용 `similarTo` 매치를 보고 |
-| **에이전트별 스코핑** | `agentId`가 REST, MCP, 검색 인덱스 전반의 저장과 리콜을 관통 (shared 또는 isolated 모드) |
-| **쓰기 시점 출처** | 모든 관측과 메모리는 캡처, 저장, 가져오기 시점에 스탬프된 불변의 origin 채널(user, agent, tool, import, shared)을 보유 |
+| **자동 캡처** | 모든 도구 사용이 hook을 통해 기록되며 수동 작업이 필요 없음 |
+| **시맨틱 검색** | RRF 융합을 사용하는 BM25 + vector + 지식 그래프 |
+| **메모리 진화** | 버전 관리, 대체(supersession), 관계 그래프 |
+| **리콜 위생** | 대체된 메모리 버전은 검색 인덱스에서 제외되며, KV의 버전 체인이 전체 기록을 보존함 |
+| **유사 중복 힌트** | 새 콘텐츠가 기존 메모리와 매우 유사하면 저장 시 참고용 `similarTo` 매치를 보고함 |
+| **에이전트별 스코프** | `agentId`가 shared 또는 isolated 모드에서 REST, MCP, 검색 인덱스 전반의 저장과 리콜을 관통함 |
+| **쓰기 시점 출처** | 모든 관측과 메모리는 캡처, 저장, 가져오기 시점에 스탬프된 불변의 origin 채널(user, agent, tool, import, shared)을 지님 |
| **자동 망각** | TTL 만료, 모순 감지, 중요도 기반 축출 |
-| **개인정보 우선** | API 키, 시크릿, `` 태그를 저장 전에 제거 |
-| **자가 치유** | 서킷 브레이커, 프로바이더 폴백 체인, 헬스 모니터링 |
-| **Claude 브리지** | MEMORY.md와의 양방향 동기화 |
+| **개인정보 우선** | API 키, 시크릿, `` 태그를 저장 전에 제거함 |
+| **자가 복구** | circuit breaker, 프로바이더 폴백 체인, health 모니터링 |
+| **Claude bridge** | MEMORY.md와의 양방향 동기화 |
| **지식 그래프** | 엔티티 추출 + BFS 순회 |
-| **팀 메모리** | 팀원 간 namespaced 공유 + 비공개 |
-| **인용 출처 추적** | 모든 메모리를 원본 관측으로 추적 |
-| **Git 스냅샷** | 메모리 상태의 버전 관리, 롤백, 차이 비교 |
+| **팀 메모리** | 팀원 간 네임스페이스로 구분된 공유 + 비공개 메모리 |
+| **인용 출처** | 모든 메모리를 원본 관측까지 추적함 |
+| **Git 스냅샷** | 메모리 상태를 버전 관리, 롤백, diff함 |
---
-세 가지 신호를 결합한 트리플 스트림 검색:
+세 가지 신호를 결합하는 트리플 스트림 검색:
-| 스트림 | 무엇을 하는가 | 언제 |
+| Stream | 동작 | 시점 |
|---|---|---|
-| **BM25** | 형태소 추출 키워드 매칭 + 동의어 확장 | 항상 활성 |
-| **Vector** | 밀집 임베딩 위의 코사인 유사도 | 임베딩 프로바이더 구성 시 |
-| **Graph** | 엔티티 매칭을 통한 지식 그래프 순회 | 쿼리에서 엔티티 감지 시 |
+| **BM25** | 동의어 확장을 포함한 어간 기반 키워드 매칭 | 항상 켜짐 |
+| **Vector** | dense 임베딩에 대한 코사인 유사도 | 임베딩 프로바이더가 설정된 경우 |
+| **Graph** | 엔티티 매칭을 통한 지식 그래프 순회 | 쿼리에서 엔티티가 감지된 경우 |
-Reciprocal Rank Fusion(RRF, k=60)으로 융합하고, 세션 다양화(세션당 최대 3개 결과)합니다.
+Reciprocal Rank Fusion(RRF, k=60)으로 융합되고, 세션별로 다변화됩니다(세션당 최대 3개 결과).
-하이브리드 랭킹은 `smart-search`뿐 아니라 기본 리콜 경로에도 적용됩니다: (`memory_recall` 뒤의) `mem::search`는 벡터 인덱스가 채워지면 동일한 BM25 + vector + graph 융합으로 랭킹합니다. Lesson 리콜은 쿼리마다 전체 코퍼스를 스캔하는 대신 전용 인메모리 BM25 인덱스에서 실행됩니다. 대체된 메모리 버전은 모든 리콜 경로에서 제외되며, 버전 체인이 그 이력을 유지합니다.
+벡터 인덱스가 채워져 있으면, (`memory_recall` 뒤에 있는) `mem::search`는 하이브리드 BM25 + vector 랭커를 사용합니다. 임베딩이 없으면 BM25를 사용합니다. `smart-search`는 그래프 데이터가 존재하면 키 없는 모드에서도 구조적 그래프 매치를 추가로 융합할 수 있습니다. Lesson 리콜은 쿼리마다 전체 코퍼스를 스캔하는 대신 전용 인메모리 BM25 인덱스에서 동작합니다. 대체된 메모리 버전은 모든 리콜 경로에서 제외되며, 버전 체인이 그 기록을 보존합니다.
-BM25는 기본적으로 그리스어, 키릴 문자, 히브리어, 아랍어, 강세 부호가 있는 라틴 문자를 토크나이즈합니다. 중국어 / 일본어 / 한국어 메모리의 경우 선택적 세그멘터(`npm install @node-rs/jieba tiny-segmenter`)를 설치하여 CJK 런을 단어 수준 토큰으로 분할하십시오. 설치하지 않으면 agentmemory는 전체 런 토크나이제이션으로 soft fallback하고 stderr에 일회성 힌트를 출력합니다.
+벡터는 크래시나 강제 종료에도 유지됩니다. 벡터 인덱스는 최소 `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`(10분) 간격으로 버킷 단위로 저장됩니다. 그 사이에 추가되거나 제거된 모든 벡터는 상태 저장소의 작은 pending 로그에도 즉시 기록되며, 다음 시작 시 임베딩 프로바이더를 호출하지 않고 이를 재생합니다. 저장이 성공할 때마다 로그가 비워집니다. 재생 후에도 벡터가 없는 문서는 `AGENTMEMORY_VECTOR_BACKFILL_MAX`(500)개 단위 배치로 백그라운드에서 다시 임베딩되며, 더 이상 남지 않을 때까지 계속됩니다. 중단된 백필은 다음 시작 시 이어서 진행됩니다. `/agentmemory/status`와 뷰어는 pending 로그 크기와 백필 상태를 보여줍니다. 키 없는 설치는 아무것도 기록하지 않습니다.
+
+BM25는 기본적으로 그리스어, 키릴 문자, 히브리어, 아랍어, 강세 부호가 있는 라틴 문자를 토크나이즈합니다. 중국어 / 일본어 / 한국어 메모리의 경우, 선택적 세그멘터(`npm install @node-rs/jieba tiny-segmenter`)를 설치해 CJK 런을 단어 수준 토큰으로 분할하십시오. 설치하지 않으면 agentmemory는 전체 런 토크나이제이션으로 soft fallback하고 stderr에 일회성 힌트를 출력합니다.
### 임베딩 프로바이더
-agentmemory는 프로바이더를 자동 감지합니다. 최상의 결과를 위해 로컬 임베딩을 설치하십시오 (무료):
+키 없는 설치는 벡터 임베딩을 비활성화합니다: `mem::search`는 BM25를 사용하며, `smart-search`는 기존의 구조적 그래프 데이터도 사용할 수 있습니다. 무료 온디바이스 시맨틱 임베딩을 사용하려면 `~/.agentmemory/.env`에 다음을 추가하고 agentmemory를 재시작하십시오:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
-| 프로바이더 | 모델 | 비용 | 비고 |
+일반적인 npm 설치에는 선택적 `@huggingface/transformers` 런타임이 포함됩니다. 첫 임베딩 요청이 `Xenova/all-MiniLM-L6-v2`를 다운로드하므로 네트워크 액세스가 필요하고 시간이 더 걸릴 수 있습니다. 이후의 추론은 온디바이스에서 실행됩니다. 원격 프로바이더는 `EMBEDDING_PROVIDER`가 재정의하지 않는 한 각자의 키로부터 자동 감지됩니다.
+
+| 프로바이더 | 모델 | 비용 | 참고 |
|---|---|---|---|
-| **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)) |
+| **Local (권장 opt-in)** | `all-MiniLM-L6-v2` | 무료 | 첫 모델 다운로드 이후 온디바이스 실행, BM25 단독 대비 recall +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 | 모든 모델 | 다양 | 멀티 모델 프록시 |
+| Voyage AI | `voyage-code-3` | 유료 | 코드에 최적화됨 |
+| Cohere | `embed-english-v3.0` | 무료 체험 | 범용 |
+| OpenRouter | 모든 모델 | 다양함 | 멀티 모델 프록시 |
---
-54개 도구, 6개 리소스, 3개 프롬프트, 17개 skills.
+도구 54개, 리소스 6개, 프롬프트 3개, skill 17개.
-> **MCP shim 대 전체 서버:** 게시된 `@agentmemory/mcp` 패키지는 얇은 shim입니다. `AGENTMEMORY_URL`을 통해 실행 중인 agentmemory 서버에 도달할 수 있을 때 **만** 전체 54-도구 표면을 노출합니다(프록시 모드). 도달 가능한 서버가 없으면 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`을 설정하십시오.
+> **MCP shim 대 전체 서버:** 게시된 `@agentmemory/mcp` 패키지는 얇은 shim입니다. `AGENTMEMORY_URL`을 통해 **실행 중인 agentmemory 서버에 도달할 수 있을 때만**(프록시 모드) 54개 도구 전체 표면을 노출합니다. 도달 가능한 서버가 없으면, 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 -y @agentmemory/agentmemory@latest`(또는 Docker 스택)를 시작하고 `AGENTMEMORY_URL=http://localhost:3111`을 설정하십시오.
### 54개 도구
-가장 작은 것부터 가장 큰 것까지 세 가지 도구 표면: `AGENTMEMORY_TOOLS=core`는 가시성을 8개의 핵심 도구(`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`)로 줄이고, 아래의 기본 세트는 레지스트리의 14개 기초 도구이며, 기본값(`AGENTMEMORY_TOOLS=all`)은 54개 전부를 노출합니다.
+가장 작은 것부터 가장 큰 것까지 세 가지 도구 표면이 있습니다: `AGENTMEMORY_TOOLS=core`는 가시성을 8개의 핵심 도구(`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`)로 줄이고, 아래의 기본 세트는 레지스트리의 14개 기초 도구이며, 기본값(`AGENTMEMORY_TOOLS=all`)은 54개 전부를 노출합니다.
-기본 도구 (14)
+기본 도구 (14개)
| 도구 | 설명 |
|------|-------------|
@@ -998,7 +1160,7 @@ npm install @huggingface/transformers
| `memory_action_update` | 작업 상태 업데이트 |
| `memory_frontier` | 우선순위로 정렬된 차단 해제된 작업 |
| `memory_next` | 가장 중요한 다음 작업 하나 |
-| `memory_lease` | 독점 작업 leases (멀티 에이전트) |
+| `memory_lease` | 독점 액션 lease (멀티 에이전트) |
| `memory_routine_run` | 워크플로우 루틴 인스턴스화 |
| `memory_signal_send` | 에이전트 간 메시징 |
| `memory_signal_read` | 수신 확인이 있는 메시지 읽기 |
@@ -1017,7 +1179,7 @@ npm install @huggingface/transformers
-### 6 리소스 · 3 프롬프트 · 17 Skills
+### 리소스 6개 · 프롬프트 3개 · skill 17개
| 유형 | 이름 | 설명 |
|------|------|-------------|
@@ -1035,20 +1197,20 @@ npm install @huggingface/transformers
| Skill | `/session-history` | 최근 세션 요약 |
| Skill | `/forget` | 관측/세션 삭제 |
-이 표는 4개의 핵심 skills만 보여줍니다. 전체 세트는 8개의 호출 가능한 skills와 7개의 레퍼런스 skills입니다. 위의 네이티브 skills 섹션을 참고하십시오.
+이 표는 핵심 skill 4개만 보여줍니다. 전체 세트는 호출 가능한 skill 9개와 참조 skill 8개입니다. 위의 네이티브 skill 섹션을 참고하십시오.
### 독립형 MCP
-전체 서버 없이, 모든 MCP 클라이언트에서 실행합니다. 다음 둘 다 동작합니다:
+전체 서버 없이, 모든 MCP 클라이언트를 위해 실행합니다. 둘 중 하나면 됩니다:
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (always available)
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
-또는 에이전트의 MCP 설정에 추가:
+또는 에이전트의 MCP 설정에 추가하십시오:
-대부분의 에이전트 (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+대부분의 에이전트(Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1063,7 +1225,7 @@ npx -y @agentmemory/mcp # shim package alias
}
```
-파일을 교체하지 말고 호스트의 기존 `mcpServers` 객체에 `agentmemory` 항목을 병합하십시오. 호스트의 `localhost`에 도달할 수 없는 샌드박스 클라이언트의 경우 env 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`을 추가하고 `AGENTMEMORY_URL`을 샌드박스가 도달할 수 있는 경로로 설정하십시오.
+`agentmemory` 항목을 파일 전체 교체 대신 호스트의 기존 `mcpServers` 객체에 병합하십시오. 호스트의 `localhost`에 도달할 수 없는 샌드박스 클라이언트의 경우, env 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`을 추가하고 `AGENTMEMORY_URL`을 샌드박스가 도달할 수 있는 경로로 설정하십시오.
OpenCode (`opencode.json`):
```json
@@ -1090,46 +1252,51 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-`3113` 포트에서 자동 시작됩니다. 스트림 상태 표시기가 있는 라이브 관측 스트림, 2-패널 세션 탐색기(넓은 화면에서는 목록 옆에 고정 상세 패널), 원시 JSON과 origin 출처를 포함한 전체 저장 레코드로 확장되는 메모리·lesson 행, 관계가 희소한 동안 노드를 유형별로 클러스터링하는 지식 그래프, 세션 리플레이, 헬스 대시보드.
+포트 `3113`에서 자동으로 시작됩니다. 뷰어는 연결 시 스냅샷 하나를 로드하고(`GET /agentmemory/viewer/snapshot`) 이후에는 실시간 스트림 이벤트를 적용합니다: 새 메모리, lesson, 관측, 감사 항목, 그래프 변경, health 업데이트가 폴링이나 페이지 새로고침 없이 나타납니다. 그 외의 요청은 클릭한 액션, "더 보기" 페이지, 검색뿐입니다. 스트림이 끊기면 뷰어는 자신의 숫자가 얼마나 오래되었는지 보여주고, 백오프로 재연결한 다음 스냅샷 하나로부터 다시 동기화합니다.
+
+- **4개 그룹에 걸친 탭 12개**, 실시간 카운트, 딥링크(`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), 키보드 단축키, 모바일 메뉴를 제공합니다.
+- **Memories:** 서버 측 검색, 프로젝트·에이전트·유형별 필터, 버전 체인과 단어 diff가 있는 상세 패널, 출처 링크, id·MCP 호출·curl 명령 복사 버튼, 수정(새 버전), 확인 후 forget, 일괄 forget, JSON 내보내기.
+- **Sessions:** 읽기 쉬운 도구 입력·출력을 담은 인라인 관측 타임라인, 필터와 페이징, 각 세션이 만들어 낸 메모리와 lesson.
+- **Graph:** 검색, 관계와 출처가 포함된 노드 상세, 색상에만 의존하지 않는 범례, 줌 컨트롤.
+- **Health:** `GET /agentmemory/status`의 실시간 버전입니다. 모든 문제에는 해결 방법이 함께 제공되며, state 백엔드, 인덱스 저장 상태, 그래프 출처 compaction 진행 상황, 실제 임계값을 담은 통합(consolidation) 설명도 포함됩니다.
+- **Audit, Activity, Profile, Replay, Lessons, Actions, Crystals** 페이지가 있으며, 각각 해당 섹션이 무엇인지, 왜 비어 있는지, 무엇을 실행하면 채워지는지를 알려주는 빈 상태 화면과, 모든 용어와 숫자에 대한 `?` 용어집 툴팁을 제공합니다.
```bash
open http://localhost:3113
```
-뷰어 서버는 기본적으로 `127.0.0.1`에 바인딩됩니다. REST가 서빙하는 `/agentmemory/viewer` 엔드포인트는 일반 `AGENTMEMORY_SECRET` bearer-token 규칙을 따릅니다. CSP 헤더는 응답별 script nonce를 사용하며 인라인 핸들러 속성을 비활성화합니다 (`script-src-attr 'none'`).
+뷰어 서버는 기본적으로 `127.0.0.1`에 바인딩되며, REST API로 요청을 전달할 때 서버 시크릿을 함께 붙이므로 별도 설정이 필요 없습니다. REST가 서빙하는 `/agentmemory/viewer` 엔드포인트는 일반적인 bearer 토큰 규칙을 따르며, 토큰이 없는 브라우저는 뷰어 포트로 리디렉션합니다. CSP 헤더는 응답별 script nonce를 사용하고 인라인 핸들러 속성을 비활성화합니다(`script-src-attr 'none'`).
---
-`:3113`의 뷰어는 에이전트가 **기억한 것**을 보여줍니다. [iii console](https://iii.dev/docs/console)은 에이전트가 **무엇을 했는지**를 보여줍니다: 모든 메모리 작업을 OpenTelemetry 추적으로, 모든 KV 항목을 편집 가능하게, 모든 함수를 호출 가능하게, 모든 스트림을 탭 가능하게. 동일한 메모리에 대한 두 창: 하나는 제품 형태, 하나는 엔진 형태.
+`:3113`의 뷰어는 에이전트가 **기억한** 것을 보여줍니다. [iii console](https://iii.dev/docs/console)은 에이전트가 **한** 일을 보여줍니다: 모든 메모리 작업이 OpenTelemetry 트레이스로, 모든 KV 항목이 편집 가능하게, 모든 함수가 호출 가능하게, 모든 스트림이 탭 가능하게 나타납니다. 같은 메모리를 바라보는 두 개의 창입니다. 하나는 제품 형태이고, 하나는 엔진 형태입니다.
-`memory_smart_search`가 발화되는 것을 보고 BM25 스캔 → 임베딩 조회 → RRF 융합 → 리랭커를 워터폴로 확인하십시오. KV 브라우저에서 정체된 통합 타이머를 편집하십시오. 조정된 페이로드로 `PostToolUse` hook을 재생하십시오. WebSocket 스트림을 고정하고 관측이 실시간으로 도착하는 것을 지켜보십시오.
+`memory_smart_search`가 발화하는 모습을 지켜보고, BM25 스캔 → 임베딩 조회 → RRF 융합 → reranker를 waterfall로 확인하십시오. KV 브라우저에서 멈춰 있는 통합(consolidation) 타이머를 수정하십시오. 수정된 payload로 `PostToolUse` hook을 재생하십시오. WebSocket 스트림을 고정해 놓고 관측이 실시간으로 쌓이는 것을 지켜보십시오.
-agentmemory는 모든 함수 호출과 트리거가 iii를 통해 발화되기 때문에 이를 무료로 제공합니다. 사용자 정의도, 계측할 것도 없습니다.
+agentmemory는 이것을 무료로 제공합니다. 모든 함수 호출과 트리거가 iii를 통해 발화하기 때문이며, 커스텀으로 만든 것도 계측해야 할 것도 없습니다.
-
+
- Workers 페이지: agentmemory 자체를 포함한 연결된 모든 워커를 PID, 함수 수, 런타임, last-seen과 함께 표시.
+ Workers 페이지: agentmemory 자신을 포함해 연결된 모든 워커를, PID, 함수 개수, 런타임, 마지막 접속 시각과 함께 보여줍니다.
-**이미 설치됨.** 콘솔은 `iii`와 함께 제공됩니다. 별도의 인스톨러가 없습니다.
+**이미 설치되어 있습니다.** 콘솔은 고정된 `iii` 엔진(0.22+)과 함께 제공되며, 별도로 설치할 것이 없습니다. 첫 실행 시 엔진 옆에 콘솔 바이너리를 다운로드합니다.
-**agentmemory와 함께 실행:**
+**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
+agentmemory console
```
-그런 다음 `http://localhost:3114`을 여십시오. 실험적인 architecture-graph 페이지를 위해 `--enable-flow`를 추가하십시오.
+이 명령은 고정된 엔진의 `iii console`을 agentmemory가 해석한 포트(REST, 스트림, bridge)에 대해 실행하고, 뷰어보다 한 포트 위, 기본적으로 `http://localhost:3114`에서 서비스합니다. `--console-port N`으로 다른 포트를 선택할 수 있습니다. `--port`와 `--instance`는 `stop`에서와 동일한 방식으로 agentmemory 인스턴스를 선택합니다. 그 외의 플래그는 그대로 전달됩니다. 예를 들어 실험적인 아키텍처 그래프 페이지를 위한 `--enable-flow`가 있습니다.
-엔진 엔드포인트를 옮긴 경우에만 덮어쓰십시오:
+`agentmemory`가 PATH에 없을 때 유용한, 동일한 작업을 수동으로 수행하는 방법:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1139,77 +1306,147 @@ iii console --port 3114 \
| 페이지 | 용도 |
|------|-----------|
-| **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. |
+| **Workers** | agentmemory 워커 자신을 포함해 연결된 모든 워커와 그 실시간 지표를 확인합니다. |
+| **Functions** | agentmemory의 함수를 JSON payload로 직접 호출합니다. 클라이언트를 연결하지 않고 `memory.recall`, `memory.consolidate`, `graph.query`를 테스트할 때 편리합니다. |
+| **Triggers** | HTTP, cron, 이벤트, state 트리거를 재생합니다: 통합(consolidation) cron을 수동으로 발화하거나, HTTP 라우트를 재시도하거나, state 변경을 발생시킵니다. |
+| **States** | 세션, 메모리 slot, 라이프사이클 타이머, 임베딩 인덱스에 대한 완전한 CRUD를 제공하는 KV 브라우저입니다. 값을 그 자리에서 편집할 수 있습니다. |
+| **Streams** | 메모리 쓰기, hook 이벤트, 관측 업데이트가 iii 스트림을 흐르는 모습을 실시간 WebSocket 모니터로 보여줍니다. |
+| **Queues** | 내구성 있는 큐 토픽 + dead-letter 관리. 실패한 임베딩/압축 작업을 재생하거나 폐기합니다. |
+| **Traces** | OpenTelemetry waterfall / flame / 서비스별 분석 뷰입니다. `trace_id`로 필터링하면 하나의 `memory.search`가 정확히 어떤 함수, DB 호출, 임베딩 요청을 발생시켰는지 볼 수 있습니다. |
+| **Logs** | trace/span ID와 연관되어 필터링된 구조화된 OTEL 로그입니다. |
+| **Config** | 런타임 설정: 엔진이 어떤 워커, 프로바이더, 포트로 실행 중인지 정확히 보여줍니다. |
+| **Flow** | (선택 사항, `--enable-flow`) 모든 워커, 트리거, 스트림에 대한 인터랙티브 아키텍처 그래프입니다. |
-
+
- Traces: 모든 메모리 작업에 대한 워터폴 / 플레임 / 서비스 분해.
+ Traces: 모든 메모리 작업에 대한 waterfall / flame / 서비스별 분석.
-**Traces는 이미 켜져 있습니다:**
+**트레이스는 이미 켜져 있습니다:**
-`iii-config.yaml`은 `iii-observability` 워커가 활성화된 상태로 제공됩니다(`exporter: memory`, `sampling_ratio: 1.0`, metrics + logs). 추가 설정이 필요 없습니다. agentmemory가 시작되는 순간 모든 메모리 작업이 콘솔이 읽을 수 있는 trace span과 구조화된 로그를 방출합니다.
+`iii-config.yaml`은 `iii-observability` 워커가 활성화된 채로 제공됩니다(`exporter: memory`, `sampling_ratio: 0.1`, 메트릭 + 로그). 추가 설정이 필요 없습니다. agentmemory가 시작되는 순간, 모든 메모리 작업은 콘솔이 읽을 수 있는 구조화된 로그를 발생시키고, 그중 10개 중 1개(`sampling_ratio: 0.1`)는 트레이스 span도 발생시킵니다.
-대신 Jaeger/Honeycomb/Grafana Tempo로 내보내고 싶다면 `exporter: memory`를 `exporter: otlp`로 변경하고 iii의 가시성 문서에 따라 collector 엔드포인트를 설정하십시오.
+대신 Jaeger/Honeycomb/Grafana Tempo로 내보내고 싶다면, `exporter: memory`를 `exporter: otlp`로 변경하고 iii의 observability 문서에 따라 collector 엔드포인트를 설정하십시오.
-> **참고:** 콘솔 자체에는 인증이 적용되지 않습니다. `127.0.0.1`에 바인딩된 채로 두고(기본값) 절대 공개적으로 노출하지 마십시오.
+> **주의:** 콘솔 자체에는 인증이 적용되지 않습니다. `127.0.0.1`(기본값)에 바인딩된 상태를 유지하고, 절대로 공개적으로 노출하지 마십시오.
---
-agentmemory는 **이미 실행 중인 [iii](https://iii.dev) 인스턴스**입니다. 세 가지 프리미티브(worker, function, trigger)가 런타임을 구성하며, KV 상태, 스트림, OTEL 추적은 iii와 함께 제공되는 iii-state, iii-stream, iii-observability 워커에서 나옵니다. Postgres, Redis, Express, pm2, Prometheus를 설치하지 않은 이유는 iii가 이들을 대체하기 때문입니다.
+agentmemory는 **이미 실행 중인 [iii](https://iii.dev) 인스턴스**입니다. 세 가지 프리미티브(worker, function, trigger)가 런타임을 구성합니다. KV 상태, 스트림, OTEL 트레이스는 iii와 함께 제공되는 iii-state, iii-stream, iii-observability 워커에서 나옵니다. Postgres, Redis, Express, pm2, Prometheus를 설치하지 않은 이유는 iii가 이들을 대체하기 때문입니다.
-그 말은 명령어 하나로 agentmemory에 완전히 새로운 기능을 확장할 수 있다는 뜻입니다.
+즉, 명령 하나만 더 실행하면 agentmemory에 완전히 새로운 기능을 추가할 수 있습니다.
-### 명령어 하나로 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
-```
+agentmemory에 필요한 빌트인은 이미 `iii-config.yaml`에 있으며 함께 부팅됩니다: `iii-state`(KV), `iii-queue`(이벤트 구독자를 위한 내구성 있는 재시도), `iii-pubsub`, `iii-cron`, `iii-stream`, 그리고 `iii-observability`(모든 함수에 대한 OTEL 트레이스, 메트릭, 로그)입니다. [iii 워커 레지스트리](https://workers.iii.dev)의 그 외 모든 것은 동일한 엔진에 꽂을 수 있습니다: `iii-config.yaml`을 `~/.agentmemory/iii-config.yaml`로 복사하고(CLI는 번들된 파일보다 이 파일을 우선시하며, 여기에도 포트와 데이터 경로를 그대로 렌더링합니다), 항목을 추가하고, `~/.agentmemory/bin/iii update worker`로 워커 런타임을 한 번 설치한 다음, agentmemory를 재시작하십시오.
-각 `iii worker add`는 agentmemory가 이미 실행 중인 동일한 엔진에 새 함수와 트리거를 등록합니다. 뷰어와 콘솔은 즉시 이를 인식합니다: 재로드도, 새 통합도, 새 컨테이너도 필요 없습니다.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | agentmemory 위에 무엇이 추가되는가 |
+| Worker | 추가되는 것 |
|---|---|
-| [`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 서버를 세우고 동일한 엔진을 공유 |
+| [`database`](https://workers.iii.dev/workers/database) | 인메모리 KV 기본값으로 부족해졌을 때 쓰는 SQL 기반 state 어댑터 |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`에서 나온 코드가 셸이 아니라 임시 VM 안에서 실행됨 |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory 옆에 추가 MCP 서버를 세우고, 동일한 엔진을 공유함 |
+
+엔진 0.22.x에서는 위 빌트인에 대해 `iii-` 접두사가 붙은 이름을 유지하십시오. 접두사가 없는 `http`, `state`, `queue`, `pubsub`, `cron` 항목은 agentmemory가 0.23 마이그레이션과 함께 옮겨갈 독립형 레지스트리 워커입니다.
+
+전체 레지스트리: [workers.iii.dev](https://workers.iii.dev). 그곳의 모든 워커는 agentmemory가 사용하는 동일한 프리미티브로 구성되며, 이미 가지고 있는 agentmemory도 그중 하나입니다.
+
+### 엔진 설정과 바인드 주소
+
+`agentmemory start`는 존재하는 첫 번째 파일에서 엔진 설정을 읽습니다: `AGENTMEMORY_III_CONFIG`, 현재 디렉터리의 `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, 그다음 번들된 `iii-config.yaml` 순입니다. 시작할 때마다 이 파일(데이터 경로, 포트, state 백엔드)을 `~/.agentmemory/data/iii-config.runtime.yaml`로 렌더링하고, 렌더링된 사본으로 엔진을 실행합니다. 따라서 렌더링된 파일이 아니라 원본 파일을 편집하십시오. 원본 파일의 `host:` 값은 작성된 그대로 유지됩니다.
+
+번들된 `iii-config.yaml`은 의도적으로 `127.0.0.1`에 바인딩되며, 이 기본값은 컨테이너 내부에서도 동일하게 적용됩니다. 컨테이너 안에서 시작된 CLI는 컨테이너의 loopback에서 수신하므로, 게시된 포트로는 아무것도 도달하지 않습니다. 컨테이너화된 CLI를 게시된 포트로 서빙하려면 `AGENTMEMORY_III_CONFIG`를 `0.0.0.0`에 바인딩하는 설정으로 지정하십시오. 패키지에 포함된 `iii-config.docker.yaml`이 바로 그것입니다: `iii-http`, `iii-stream`, 엔진 포트를 `0.0.0.0`에 바인딩하고 state를 `/data` 아래에 저장하므로, 그곳에 쓰기 가능한 볼륨을 마운트하십시오. `AGENTMEMORY_SECRET`은 계속 설정해 두고, 필요한 포트만 `127.0.0.1`에 또는 신뢰하는 프록시 뒤에 게시하십시오.
+
+이 저장소의 `docker-compose.yml`은 CLI의 설정 탐색을 거치지 않습니다: `iii-config.docker.yaml`을 `/app/config.yaml`에 마운트하고, `iii-engine` 컨테이너는 `--config /app/config.yaml`로 시작됩니다. 원클릭 [배포 템플릿](../deploy/)은 자신의 진입점에서 자체적인 `0.0.0.0` 설정을 작성합니다.
+
+### 스토리지 백엔드: file (기본값) 대 redis
+
+`iii-state`와 `iii-stream`은 기본적으로 iii-engine에 번들된 파일 기반 KV 스토어를 사용합니다: 스코프마다 하나의 JSON 파일이 있고, 이는 엔진 프로세스의 메모리에 유지되며 타이머에 따라 디스크로 재작성됩니다. 단일 사용자의 로컬 설치에는 이것이 올바른 기본값입니다. 여러 동시 writer가 있는 공유 데몬은 대신 Redis로부터 진짜 키 단위 쓰기를 얻지만, 작업마다 네트워크 왕복이라는 비용이 따릅니다(모든 `state::*` 호출은 여전히 하나의 Redis 연결에서 직렬화되므로, 이는 병렬성이 아니라 파일 스토어의 lock을 소켓으로 바꾸는 것일 뿐입니다).
+
+`AGENTMEMORY_STATE_BACKEND=redis`(와 `AGENTMEMORY_REDIS_URL`)를 설정하면 두 워커 모두 iii-engine의 내장 `redis` 어댑터로 전환됩니다. 이 어댑터는 매 쓰기마다 스코프 전체를 재작성하는 대신 각 키를 Redis 해시 필드(`HSET`)로 저장합니다:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND`의 기본값은 `file`입니다. 설정하지 않고 두면 지금의 동작이 그대로 유지되며, 인식되지 않는 값(`file`이나 `redis`가 아닌 모든 값)은 조용히 폴백하지 않고 시작 오류가 됩니다. `/agentmemory/status`와 뷰어의 Health 페이지(State store 행)는 어떤 백엔드가 활성화되어 있는지, 응답하는지를 보고하지만 URL은 절대 보여주지 않습니다.
+
+**순수 `redis://`만 지원합니다.** 고정된 엔진(0.22.1)은 TLS 지원 없이 Redis 클라이언트를 빌드하므로, `rediss://` URL(Upstash, Redis Cloud, 전송 중 암호화를 사용하는 ElastiCache 등 대부분의 매니지드 Redis 서비스가 기본적으로 TLS 전용으로 제공)은 연결에 실패합니다. 연결이 암호화되지 않으므로 Redis 비밀번호와 저장된 모든 메모리가 평문으로 네트워크를 통과합니다: 로컬 Redis나 신뢰하는 사설망 안의 Redis를 가리키십시오. 그 외의 Redis를 사용한다면 agentmemory 호스트에서 암호화된 터널(stunnel, SSH, VPN)을 실행해서, 순수 `redis://` 구간은 그 호스트 안에만 머물게 하고 터널의 업스트림 연결은 암호화·인증되도록 하십시오. Redis 비밀번호에 단일 인용부호가 포함되어 있다면 percent-encode하십시오(`%27`). 엔진은 URL을 파싱하기 전에 YAML 설정 안에서 이를 확장합니다.
+
+**`--instance`당 하나의 Redis 서버.** 엔진의 Redis 키 접두사(`state:`, `stream::`)는 고정되어 있으므로, 동일한 데이터베이스를 가리키는 두 개의 agentmemory 인스턴스(`--instance 1`, `--instance 2`, ...)는 서로의 데이터를 덮어씁니다. 별도의 데이터베이스 인덱스(`redis://localhost:6379/1`)를 사용하면 저장된 데이터는 분리되지만, 엔진은 실시간 뷰어 이벤트를 하나의 Redis pub/sub 채널(`stream::events`)로 중계하고 Redis pub/sub는 데이터베이스 인덱스를 무시하므로, 각 인스턴스의 뷰어는 여전히 다른 인스턴스의 실시간 이벤트를 보게 됩니다. 두 개 이상을 실행할 때는 각 인스턴스에 자체 Redis 서버(또는 포트)를 부여하십시오.
+
+**같은 점과 다른 점.** agentmemory의 모든 기능은 Redis에서도 동작합니다: 세션, 관측, 메모리(remember, supersede, evolve, forget), 검색과 인덱스 버킷, lesson, 그래프, 감사 로그와 그 월별 스코프, 내보내기와 가져오기, 거버넌스 삭제, 통합(consolidation) 상태, 뷰어 스냅샷과 그 실시간 스트림, health 모니터까지 모두 동작합니다. 엔진은 각 스코프를 하나의 Redis 해시(`HSET`/`HGET`/`HGETALL`)로 저장하고, 파일 스토어와 동일한 state 트리거를 발화합니다. 엔진의 세 가지 차이점은 agentmemory 내부에서 처리됩니다:
+
+- Redis는 스코프의 레코드를 고정된 순서 없이 반환합니다. agentmemory는 이를 (레코드 id의 생성 시각, 그다음 타임스탬프 기준으로) 오래된 순으로 정렬하므로, 목록, 페이징, 내보내기 청크가 파일 스토어와 동일한 순서로 반환됩니다.
+- 엔진은 Redis에서 부분 업데이트를 Lua 스크립트로 적용하는데, 이 스크립트는 빈 배열을 빈 객체로 바꿔버립니다. agentmemory는 Redis에서 이러한 업데이트를 직접 적용합니다(키 단위 lock 아래에서 읽기, 변경, 쓰기). 그 결과 `tags: []` 같은 필드는 배열로 유지됩니다.
+- 레거시 감사 로그 확인은 디스크의 파일 스토어 파일을 찾는 대신 Redis에서 예전 스코프를 읽습니다.
+
+사용자가 직접 챙겨야 할 차이 하나가 있습니다: **Redis가 재시작되면, agentmemory가 재시작되기 전까지 엔진은 뷰어로의 실시간 이벤트 중계를 멈춥니다.** 데이터는 여전히 정상적으로 저장되고 읽힙니다. health 모니터는 30초마다 Redis를 통해 테스트 이벤트를 보냅니다. 돌아오지 않으면 `/agentmemory/status`와 뷰어의 Health 페이지는 "실시간 업데이트가 뷰어에 도달하지 못하고 있습니다"를 해결 방법(agentmemory 재시작)과 함께 보여줍니다. Redis가 다운되었다면 상태 보고서는 "state 저장소가 응답하지 않습니다"와 확인 방법(`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)을 보여줍니다. 매우 큰 스코프를 나열하면 하나의 `HGETALL`로 전체 해시를 읽는데, 이는 파일 스토어가 이를 메모리에 유지하는 것과 동일한 비용입니다.
+
+**권장 Redis 설정.** 기본 `save 3600 1 300 100 60 10000` 스냅샷 정책은 크래시 시 몇 분 치의 쓰기를 잃을 수 있는데, 이는 파일 스토어의 5초 flush 윈도우보다 더 나쁩니다. 잃어버리면 곤란한 것이 있다면 `appendonly yes`를 설정하십시오. `maxmemory-policy noeviction`을 설정하십시오. `allkeys-lru` 등은 Redis가 메모리 한도에 도달하면 조용히 메모리를 버립니다.
-전체 레지스트리: [workers.iii.dev](https://workers.iii.dev). 그곳의 모든 워커는 agentmemory가 사용하는 동일한 프리미티브로 구성되며, 이미 갖고 있는 agentmemory도 그중 하나입니다.
+네이티브(비 Docker) 시작과, 모든 원클릭 [배포 템플릿](../deploy/)(번들된 `iii-config.yaml`을 덮어쓰고 네이티브로 시작하는 것들)은 `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL`을 읽어 실행되는 `iii-config`에 렌더링합니다. URL 자체는 그 렌더링된 파일에 결코 기록되지 않으며, 엔진 프로세스가 부팅 시 자신의 환경에서 확장하는 `${AGENTMEMORY_REDIS_URL}` 참조만 기록됩니다. 이 저장소 자체의 Docker Compose 경로(`AGENTMEMORY_USE_DOCKER=1`, 또는 그렇게 시작된 엔진을 다시 사용하는 경우)만 `iii-config.docker.yaml`을 읽기 전용으로 마운트하고 절대 렌더링하지 않습니다. `agentmemory start`는 이 조합을 감지하면 경고합니다. 그 파일은 [iii-state](https://workers.iii.dev/workers/iii-state)와 [iii-stream](https://workers.iii.dev/workers/iii-stream) 워커 문서에 나온 동일한 `name: redis` / `config: redis_url: ...` 형태를 따라 직접 바꾸고, `redis_url`을 컨테이너에서 도달 가능한 Redis로 지정하십시오. `docker-compose.yml`은 `AGENTMEMORY_REDIS_URL`을 엔진 컨테이너로 전달하므로, 그곳에서는 `redis_url: '${AGENTMEMORY_REDIS_URL}'`이 동작하며 URL을 마운트된 파일 밖에 유지합니다.
-### iii가 무엇을 대체하는가
+렌더링된 설정은 URL을 `~/.agentmemory/data/iii-config.runtime.yaml` 밖에 유지하지만, 엔진 자체의 설정 워커는 부팅하면 *확장된* 값을 `~/.agentmemory/config/iii-state.yaml`과 `iii-stream.yaml`에 그대로 영속화합니다(iii-engine의 `${VAR}` 확장은 그 워커가 시드를 저장하기 전에 일어나며, 참조가 아니라 해석된 값을 저장합니다). 이 디렉터리는 자격 증명을 담고 있는 것으로 취급하십시오: 공유 호스트에서는 `chmod 700 ~/.agentmemory`를 적용하고, 데이터베이스의 관리자 자격 증명보다는 agentmemory에 필요한 범위로 한정된 Redis ACL 사용자를 사용하십시오.
-| 전통적인 스택 | agentmemory에서의 사용 |
+**마이그레이션은 자동이 아닙니다.** `AGENTMEMORY_STATE_BACKEND`를 전환하면 양쪽 모두 빈 스토어에서 시작합니다. 기존 데이터를 file에서 Redis로, 혹은 그 반대로 복사해 주는 것은 없습니다. 떠나는 백엔드에서 내보내고, 옮겨갈 백엔드로 가져오십시오. 아래 스크립트는 bash와 zsh에서(`bash -u` 포함) 동일하게 동작합니다. 반면 `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` 같은 배열은 그렇지 않습니다: zsh는 이 헤더를 하나의 손상된 단어로 유지하는 반면 bash는 이를 둘로 분리하므로, `AGENTMEMORY_SECRET`이 설정되어 있으면 두 요청 모두 401이 됩니다:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export`는 큰 코퍼스를 여러 호출로 나누어 처리할 수 있도록 `?maxSessions=`와 `?offset=`도 지원합니다. import의 `strategy`는 `merge`(기본값, 안전함), `replace`, `skip` 중 하나입니다.
+
+### iii가 대체하는 것
+
+| 전통적인 스택 | agentmemory가 사용하는 것 |
|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
+| Express.js / Fastify | iii HTTP Trigger |
| 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 ` |
+| SSE / Socket.io | iii Stream (WebSocket) |
+| pm2 / systemd | iii 엔진의 워커 감독 |
+| Prometheus / Grafana | iii OTEL + health 모니터 |
+| 커스텀 플러그인 시스템 | `iii worker add ` |
-**182개 소스 파일 · ~41,600 LOC · 1,674 tests · 264개 함수 · 50개 KV 스코프**, 모두 세 가지 프리미티브 위에. `agentmemory plugin install`이 없습니다. 플러그인 시스템은 iii 자체입니다.
+**소스 파일 225개 · LOC ~54,000줄 · 테스트 2,600+개 · 함수 312개 · KV 스코프 66개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
---
@@ -1217,22 +1454,22 @@ iii worker add mcp # generic MCP host alongside the agentmemory
### LLM 프로바이더
-agentmemory는 환경에서 자동 감지합니다. 기본적으로 프로바이더를 구성하거나 Claude subscription 폴백에 명시적으로 옵트인하지 않는 한 LLM 호출이 발생하지 않습니다.
+agentmemory는 환경에서 프로바이더를 자동으로 감지합니다. 프로바이더를 설정하면 LLM 기반 작업을 사용할 수 있게 되지만, 프로바이더 설정만으로는 LLM이 작성하는 관측 압축이 활성화되지 않습니다. 그 경로에는 프로바이더와 `AGENTMEMORY_AUTO_COMPRESS=true`가 모두 필요합니다.
-| 프로바이더 | 설정 | 비고 |
+| 프로바이더 | 설정 | 참고 |
|----------|--------|-------|
-| **No-op (기본)** | 설정 불필요 | LLM 기반 압축/요약이 비활성화됨. 합성 BM25 압축 + 리콜은 여전히 동작. 이전에 Claude-subscription 폴백에 의존했다면 아래의 `AGENTMEMORY_ALLOW_AGENT_SDK` 참고. |
-| Anthropic API | `ANTHROPIC_API_KEY` | 토큰당 청구 |
+| **No-op (기본값)** | 설정 필요 없음 | LLM 기반 압축/요약은 비활성화됩니다. synthetic 압축과 BM25 리콜은 계속 동작합니다. 이전에 Claude 구독 폴백에 의존했다면 아래의 `AGENTMEMORY_ALLOW_AGENT_SDK`를 참고하십시오. |
+| Anthropic API | `ANTHROPIC_API_KEY` | 토큰 단위 과금 |
| MiniMax | `MINIMAX_API_KEY` | Anthropic 호환 |
-| Gemini | `GEMINI_API_KEY` | 임베딩도 활성화 |
+| Gemini | `GEMINI_API_KEY` | 임베딩도 함께 활성화 |
| OpenRouter | `OPENROUTER_API_KEY` | 모든 모델 |
-| OpenAI API | `OPENAI_API_KEY` | 기본 `gpt-5.6-luna`, `OPENAI_MODEL`로 덮어쓰기 |
-| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) 또는 `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | OpenAI-API 호환이면 무엇이든. 비용 제로, 자체 하드웨어에서 실행. 아래 [로컬 모델](#로컬-모델-ollama--lm-studio--vllm) 참고. |
-| Claude subscription 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 옵트인 전용. `@anthropic-ai/claude-agent-sdk` 세션을 스폰합니다. 무한 Stop-hook 재귀를 일으킨 전력이 있어 더 이상 기본값이 아닙니다. |
+| OpenAI API | `OPENAI_API_KEY` | 기본값 `gpt-5.6-luna`, `OPENAI_MODEL`로 재정의 |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) 또는 `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | OpenAI API와 호환되는 모든 것. 비용 없이 자신의 하드웨어에서 실행됩니다. 아래의 [로컬 모델](#local-models-ollama--lm-studio--vllm)을 참고하십시오. |
+| Claude 구독 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in 전용입니다. `@anthropic-ai/claude-agent-sdk` 세션을 생성하는데, 과거 무한한 Stop-hook 재귀를 일으킨 적이 있어 더 이상 기본값이 아닙니다. |
### 로컬 모델 (Ollama / LM Studio / vLLM)
-agentmemory는 모든 OpenAI-API 호환 서버와 통신하므로, `/v1/chat/completions`를 노출하는 것이라면 코드 변경 없이 동작합니다. 유료 키도, 클라우드도, rate limit도 없습니다. 전적으로 자체 하드웨어에서 실행됩니다.
+agentmemory는 OpenAI API와 호환되는 모든 서버와 통신하므로, `/v1/chat/completions`를 노출하는 것이라면 코드 변경 없이 동작합니다. 유료 키도, 클라우드도, rate limit도 없습니다. 모든 것이 사용자의 하드웨어에서 실행됩니다.
**Ollama** (기본 포트 `11434`):
@@ -1250,7 +1487,7 @@ OPENAI_MODEL=qwen3:8b
**LM Studio** (기본 포트 `1234`):
-LM Studio 열기 → Local Server 탭 → Start Server. 선택기에서 아무 채팅 모델(Qwen 3, gpt-oss, DeepSeek R1 등)을 고르십시오.
+LM Studio를 열고 → Local Server 탭 → Start Server를 누르십시오. 선택기에서 원하는 채팅 모델(Qwen 3, gpt-oss, DeepSeek R1 등)을 고르십시오.
```env
# ~/.agentmemory/.env
@@ -1259,48 +1496,48 @@ OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
-**vLLM / llama.cpp / Text Generation Inference**: 형태는 동일합니다. `OPENAI_BASE_URL`을 서버가 노출하는 URL로 지정하고, `OPENAI_MODEL`을 서버가 받아들일 이름으로 설정하십시오.
+**vLLM / llama.cpp / Text Generation Inference**: 동일한 형태입니다. `OPENAI_BASE_URL`을 서버가 노출하는 URL로 지정하고, `OPENAI_MODEL`을 서버가 받아들이는 이름으로 설정하십시오.
-**메모리 작업을 위한 모델 추천**: 압축과 요약은 짧은 작업(<2K 토큰 입력, <500 토큰 출력)이라 7B instruct 모델이면 충분합니다. 추천:
+**메모리 작업을 위한 모델 선택**: 압축과 요약은 짧은 작업(입력 2K 토큰 미만, 출력 500 토큰 미만)이므로 7B instruct 모델로도 충분합니다. 추천:
| 모델 | 크기 | 이유 |
|-------|------|-----|
-| `qwen3:8b` | ~5.2 GB | 16 GB 머신에서 균형 잡힌 기본값; 추출과 도구 형태 텍스트에 강함 |
-| `qwen3:4b` | ~2.6 GB | 가장 작은 합리적 옵션; 압축에는 적합하지만 그래프 추출에는 약함 |
-| `qwen3-coder:30b` | ~19 GB | 24-32 GB 하드웨어에서 코드 중심 세션에 최고의 로컬 선택 (30B MoE, 3.3B 활성) |
-| `gpt-oss:20b` | ~14 GB | 16 GB RAM에 들어가는 강력한 범용 모델 |
-| `deepseek-r1:8b` | ~5.2 GB | 추론 distill; 느리지만 더 깨끗한 추출 |
+| `qwen3:8b` | ~5.2 GB | 16GB 머신에서 균형 잡힌 기본값. 추출과 도구 형태의 텍스트에 강함 |
+| `qwen3:4b` | ~2.6 GB | 가장 작은 합리적 옵션. 압축에는 괜찮지만 그래프 추출에는 약함 |
+| `qwen3-coder:30b` | ~19 GB | 24-32GB 하드웨어에서 코드 형태 세션을 위한 최고의 로컬 선택(30B MoE, 활성 3.3B) |
+| `gpt-oss:20b` | ~14 GB | 16GB RAM에 맞는 강력한 범용 모델 |
+| `deepseek-r1:8b` | ~5.2 GB | reasoning distill. 더 느리지만 더 깔끔한 추출 |
-Qwen 3 모델은 기본적으로 thinking을 수행하며 출력 전에 추론에 토큰 예산 전체를 소진할 수 있습니다. `AGENTMEMORY_LLM_NOTHINK=1`을 설정하여 그래프 추출 프롬프트에 `/no_think`를 덧붙이고, 추출이 비어서 돌아온다면 `MAX_TOKENS`를 높이십시오(16384가 잘 동작합니다).
+Qwen 3 모델은 기본적으로 thinking을 수행하므로, 출력이 나오기 전에 reasoning에 토큰 예산을 전부 써버릴 수 있습니다. `AGENTMEMORY_LLM_NOTHINK=1`을 설정하면 그래프 추출 프롬프트에 `/no_think`가 덧붙으며, 추출 결과가 비어 있다면 `MAX_TOKENS`를 올리십시오(16384면 충분합니다).
-추론 클래스 모델(`` 블록이 있는 `o1` 스타일)은 로컬 서버가 노출하지 않을 수 있는 `reasoning` 필드와 함께 빈 `content`를 반환할 수 있습니다. 추출이 비어 있다면 먼저 비추론 모델로 전환하십시오. `OPENAI_REASONING_EFFORT=none` env는 OpenAI reasoning 스키마를 미러링하는 Ollama Cloud thinking 모델의 thinking도 비활성화할 수 있습니다.
+reasoning 계열 모델(`` 블록을 사용하는 `o1` 스타일)은 `content`를 빈 값으로 반환하면서, 로컬 서버가 노출하지 않을 수 있는 `reasoning` 필드만 채울 수 있습니다. 추출 결과가 비어 있다면 먼저 non-reasoning 모델로 바꿔 보십시오. `OPENAI_REASONING_EFFORT=none` 환경 변수는 OpenAI의 reasoning 스키마를 그대로 따르는 Ollama Cloud thinking 모델의 thinking도 비활성화할 수 있습니다.
-로컬 임베딩은 `@huggingface/transformers`를 통해 기본 제공됩니다: `EMBEDDING_PROVIDER=local`(기본값)이면 `Xenova/all-MiniLM-L6-v2`(384-dim)를 완전히 온디바이스로 사용합니다. 추가 설정이 필요 없습니다.
+로컬 임베딩은 선택적 의존성으로 제공되지만 기본적으로 활성화되어 있지 않습니다. `EMBEDDING_PROVIDER=local`을 설정하면 `Xenova/all-MiniLM-L6-v2`(384차원)를 사용하게 됩니다. 첫 임베딩 요청이 모델을 다운로드하고, 이후의 추론은 온디바이스에서 이루어집니다. 이 설정이나 원격 임베딩 키가 없으면 벡터는 비활성화된 채로 남고, `mem::search`는 BM25를 사용하며, `smart-search`는 여전히 기존 그래프 매치를 추가할 수 있습니다.
-### 비용 인식 모델 선택
+### 비용을 고려한 모델 선택
-백그라운드 압축은 모든 관측마다 실행되므로 모델 선택이 월별 지출에 의미 있게 영향을 미칩니다. 캡처된 워크로드 데이터: 635 요청 / 888K 토큰 / 35시간의 활성 사용, 2026-05-23 가격으로 세 가지 OpenRouter 모델에 대해 실행.
+프로바이더와 `AGENTMEMORY_AUTO_COMPRESS=true`가 모두 설정되어 LLM이 작성하는 백그라운드 압축이 활성화되면, 이는 모든 관측에 대해 실행되므로 모델 선택이 월간 비용을 상당히 바꿉니다. 캡처된 워크로드 데이터: 요청 635개 / 토큰 888K / 활성 사용 35시간을 2026-05-23 가격 기준 세 가지 OpenRouter 모델에 대해 실행한 결과입니다.
-| 티어 | 모델 | Input / 1M | Output / 1M | 캡처된 35h 비용 | 비고 |
+| Tier | 모델 | 입력 / 1M | 출력 / 1M | 캡처된 35시간 기준 비용 | 참고 |
|------|-------|------------|-------------|---------------------------|-------|
-| 권장 | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | 최신 DeepSeek; 압축 워크로드에 가장 저렴한 권장 선택. |
-| 권장 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | 견고한 압축 + 요약 품질, Sonnet 대비 ~10배 저렴. |
-| 권장 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 세션이 코드 중심이라면 강한 코드 추론. |
-| 프리미엄 | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | 측정된 Sonnet 4.6 실행과 동일한 정가; 2026-08-31까지 $2/$10 introductory 가격. |
-| 프리미엄 | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | 플래그십 티어; 항시 백그라운드 작업에는 비쌈. |
-| 회피 | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | 플래그십 클래스 모델; 압축에는 과지출. |
+| 추천 | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (추정) | 최신 DeepSeek. 압축 워크로드에 가장 저렴하게 추천되는 선택. |
+| 추천 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet보다 약 10배 낮은 비용으로 견실한 압축 + 요약 품질. |
+| 추천 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 세션이 코드 중심이라면 강력한 코드 reasoning. |
+| 프리미엄 | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (추정) | 측정된 Sonnet 4.6 실행과 동일한 정가. 2026-08-31까지는 $2/$10 도입 가격. |
+| 프리미엄 | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (추정) | 플래그십 등급. 항상 켜져 있는 백그라운드 작업에는 비쌈. |
+| 비추천 | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (추정) | 플래그십급 모델. 압축 작업에는 과도한 지출. |
-측정된 행은 캡처된 실행에서 나온 값이며, (est.) 행은 동일한 토큰 구성을 각 모델의 정가로 환산한 것입니다.
+측정된 행은 캡처된 실행에서 나온 것이며, (추정) 행은 동일한 토큰 조합을 각 모델의 정가에 맞춰 환산한 것입니다.
-`OPENROUTER_MODEL`이 프리미엄 티어 패턴과 일치하면 agentmemory가 런타임 경고를 출력합니다. 정보에 기반한 결정을 내렸다면 `AGENTMEMORY_SUPPRESS_COST_WARNING=1`로 한 번에 침묵시키십시오.
+`OPENROUTER_MODEL`이 premium 등급 패턴과 일치하면 agentmemory는 런타임 경고를 출력합니다. 충분히 알고 선택했다면 `AGENTMEMORY_SUPPRESS_COST_WARNING=1`을 설정해 끌 수 있습니다.
-메모리 작업에서의 품질 대 비용 트레이드오프: 압축은 비교적 느슨한 품질 기준을 가진 요약 작업입니다(사용자가 아니라 에이전트가 요약을 다시 읽습니다). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder는 이 작업에서 Sonnet과 반올림 오차 내에 들어가면서 10-70배 적은 비용이 듭니다. 프리미엄 티어 모델은 직접 읽는 쿼리에 남겨두십시오.
+메모리 작업에서의 품질 대 비용 트레이드오프: 압축은 품질 기준이 비교적 느슨한 요약 작업입니다(사용자가 아니라 에이전트가 요약을 다시 읽습니다). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder는 이 작업에서 Sonnet과 오차 범위 안에 있으면서 비용은 10~70배 적게 듭니다. premium 등급 모델은 직접 읽는 쿼리를 위해 아껴 두십시오.
출처: [OpenRouter pricing for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [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`는 리콜이 그 태그로 필터링되는지 여부를 제어합니다.
+여러 역할(architect / developer / reviewer / researcher / support-agent)이 하나의 agentmemory 서버를 공유하는 멀티 에이전트 구성에서, `AGENT_ID`는 모든 쓰기에 그것을 수행한 역할을 태그합니다. `AGENTMEMORY_AGENT_SCOPE`는 리콜이 그 태그로 필터링되는지를 제어합니다.
```env
TEAM_ID=company
@@ -1311,31 +1548,35 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
두 가지 모드:
-| 모드 | 쓰기 태그 | 리콜 필터링 | 사용 시점 |
+| 모드 | 쓰기 태깅 | 리콜 필터링 | 사용 시점 |
|------|------------|---------------|-------------|
-| `shared` (기본) | 예 | 아니오 | 감사 로그가 있는 크로스 에이전트 컨텍스트. architect는 developer가 기록한 내용을 볼 수 있지만, 모든 행은 누가 말했는지 기록합니다. |
-| `isolated` | 예 | 예 | 엄격한 분리. architect는 developer의 관측 / 메모리 / 세션을 절대 보지 않습니다. |
+| `shared` (기본값) | yes | no | 감사 기록이 남는 에이전트 간 컨텍스트. architect는 developer가 남긴 내용을 볼 수 있지만, 모든 행에는 누가 남겼는지가 기록됩니다. |
+| `isolated` | yes | yes | 엄격한 분리. 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=`을 받고, env 스코프를 완전히 옵트아웃하기 위해 `?agentId=*`을 받습니다. `/memories`는 또한 `agentId`가 undefined인 pre-AGENT_ID 메모리를 노출하기 위해 `?includeOrphans=true`를 받습니다.
+isolated 모드에서 필터링되는 것: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. 각 엔드포인트는 요청별로 재정의하기 위한 `?agentId=`과, env 스코프를 완전히 벗어나기 위한 `?agentId=*`를 받습니다. `/memories`는 또한 `agentId`가 정의되지 않은 pre-AGENT_ID 메모리를 드러내기 위해 `?includeOrphans=true`도 받습니다.
-SDK / REST 레이어에서의 호출별 덮어쓰기: 모든 변형 엔드포인트(`/session/start`, `/remember`)는 env를 이기는 `agentId` 필드를 request body에서 받습니다. 많은 역할을 하나의 서버 프로세스로 라우팅하는 런타임에 유용합니다. MCP `memory_save` 도구도 동일한 `agentId` 필드를 노출하고, 독립형 stdio 서버는 `agentId`와 `project`를 모두 전달하며, 저장된 메모리는 `agentId`를 검색 인덱스로 가져가므로 에이전트 스코프 검색이 관측뿐 아니라 메모리까지 커버합니다.
+SDK / REST 계층에서의 호출별 재정의: 모든 변형 엔드포인트(`/session/start`, `/remember`)는 요청 본문에 env보다 우선하는 `agentId` 필드를 받습니다. 하나의 서버 프로세스로 여러 역할을 라우팅하는 런타임에 유용합니다. MCP `memory_save` 도구도 동일한 `agentId` 필드를 노출하며, 독립형 stdio 서버는 `agentId`와 `project`를 모두 전달하고, 저장된 메모리는 `agentId`를 검색 인덱스까지 가지고 가므로, 에이전트 범위 검색은 관측뿐 아니라 메모리도 포함합니다.
-`AGENT_ID`가 설정되지 않았을 때, 메모리는 스코프되지 않은 상태로 유지됩니다(레거시 동작, 태그 없음, 필터 없음).
+`AGENT_ID`가 설정되지 않으면 메모리는 스코프 없이 유지됩니다(레거시 동작, 태그 없음, 필터 없음).
### 포트
-agentmemory + iii-engine은 기본적으로 네 개의 포트에 바인딩합니다. 재시작이 `port in use`로 실패한다면, 이 표가 어떤 프로세스를 찾을지 알려줍니다.
+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`) |
+| `3112` | iii-engine | 내부 스트림 워커 (agentmemory + 뷰어가 사용) | `III_STREAM_PORT` (권장) 또는 레거시 `III_STREAMS_PORT` |
+| `3113` | agentmemory | 실시간 뷰어 (`http://localhost:3113`) | `III_VIEWER_PORT`, 또는 보고되는 URL을 위한 `AGENTMEMORY_VIEWER_URL` |
+| `49134` | iii-engine | WebSocket. 워커가 이곳에 등록되고 OTel 텔레메트리가 이를 통해 흐름 | `III_ENGINE_PORT` 또는 `III_ENGINE_URL` |
+
+`--port `은 REST 앵커를 변경하고, 위의 대응하는 명시적 포트나 URL이 설정되지 않은 경우에만 스트림을 `N+1`, 뷰어를 `N+2`, 엔진 WebSocket을 `N+46023`으로 파생시킵니다. 이는 독립된 라이프사이클 네임스페이스를 만들지 않습니다. 두 번째 데몬에는 `--instance 1`을 사용하십시오. 앵커 3211을 사용하며 기본값은 `3211/3212/3213/49234`이고, 별도의 `instance-1` 데이터 및 라이프사이클 디렉터리를 받습니다. 인스턴스 1부터 50까지 동일한 패턴을 따릅니다.
-크래시된 실행 후 포트가 바인딩된 채로 남아 있을 때의 정리:
+고정된 엔진은 `--no-update-check`로 시작됩니다(부팅 시 GitHub에 대한 업데이트나 보안 권고 조회 없음) 그리고 iii의 익명 사용 텔레메트리가 꺼진 상태로 시작됩니다: agentmemory는 변수를 직접 export하지 않는 한 자신이 생성하는 엔진에 대해 `III_TELEMETRY_ENABLED=false`를 설정하며, 번들된 compose 파일도 동일하게 동작합니다.
+
+크래시 이후에도 포트가 바인딩된 채로 남아 있을 때 오래된 프로세스를 정리하는 방법:
```bash
# macOS / Linux — find whatever is on each port and kill it
@@ -1348,38 +1589,40 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop`은 정상 종료 시 워커와 엔진 pidfile을 모두 깔끔하게 회수합니다. Docker 모드에서는 agentmemory 자체의 compose 서비스만 내리고 Docker 정리 전에 네이티브 워커를 회수합니다. 또한 CLI는 `--force`가 전달되지 않는 한 Docker 또는 VM 포트 점유자(Docker backend, vpnkit, colima)를 네이티브 엔진으로 인식하거나 시그널을 보내는 것을 거부합니다. 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
+`agentmemory stop`은 정상적인 네이티브 종료 시 워커와 엔진 pidfile을 모두 깔끔하게 회수합니다. Docker 모드에서는 네이티브 워커를 flush하고, 정확히 검증된 엔진 컨테이너를 중지하며, 무손실 재시작을 위해 컨테이너와 그 `/data` 마운트를 모두 보존합니다. 다음 시작은 동일한 컨테이너를 검증하고 재사용합니다. Docker 기반 제거에는 `agentmemory remove --keep-data`가 필요합니다: 검증된 컨테이너, 그 데이터 마운트, 이를 복구하는 데 필요한 라이프사이클 기록은 보존하면서 agentmemory가 공유로 관리하는 파일만 제거합니다. 파괴적인 Docker 데이터 삭제는 백업 이후 운영자에게 의도적으로 맡겨져 있습니다. CLI는 또한 `--force`가 전달되지 않는 한 Docker나 VM 포트 점유자(Docker backend, vpnkit, colima)를 네이티브 엔진으로 채택하거나 시그널을 보내는 것을 거부합니다. 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
### 설정 파일
-매 셸에서 변수를 export하는 대신 agentmemory 런타임 설정을 `~/.agentmemory/.env`에 두십시오. 뷰어가 `export ANTHROPIC_API_KEY=...` 같은 setup 힌트를 보여주면, `export` 접두사 없이 `ANTHROPIC_API_KEY=...`로 이 파일에 복사한 후 agentmemory를 재시작하십시오.
+agentmemory 런타임 설정은 매 셸에서 변수를 export하는 대신 `~/.agentmemory/.env`에 두십시오. 뷰어가 `export ANTHROPIC_API_KEY=...`와 같은 설정 힌트를 보여주면, `export` 접두사 없이 `ANTHROPIC_API_KEY=...`로 이 파일에 복사한 다음 agentmemory를 재시작하십시오.
-프로세스 환경 변수는 여전히 동작하며 파일의 값보다 우선순위가 높습니다.
+프로세스 환경 변수는 여전히 동작하며 파일 안의 값보다 우선합니다.
-Windows에서 동일한 파일은 `%USERPROFILE%\.agentmemory\.env`에 있습니다:
+Windows에서는 동일한 파일이 `%USERPROFILE%\.agentmemory\.env`에 있습니다:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
-API 키 대신 Claude Code Pro/Max subscription으로 테스트하려면 명시적으로 옵트인하십시오:
+API 키 대신 Claude Code Pro/Max 구독으로 테스트하려면, 명시적으로 opt-in하십시오:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-원한다면 동일한 파일에서 graph 또는 consolidation 기능을 활성화하십시오:
+LLM이 작성하는 관측 압축에는 두 줄이 모두 필요합니다: LLM 프로바이더에 대한 접근(이 명시적 구독 폴백 포함)과 `AGENTMEMORY_AUTO_COMPRESS=true`입니다. 프로바이더만 있으면 기본 synthetic 압축 경로가 그대로 유지됩니다.
+
+통합(consolidation, 그래프 노드, lesson, crystal)은 LLM 프로바이더가 설정되어 있으면 기본적으로 켜집니다. LLM 없이 동작하고 싶다면 `CONSOLIDATION_ENABLED=false`로 명시적으로 opt-out하십시오. 그래프 추출은 별도의 플래그입니다:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### 환경 변수
-`~/.agentmemory/.env` 생성:
+`~/.agentmemory/.env`를 생성하십시오:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
@@ -1416,13 +1659,15 @@ CONSOLIDATION_ENABLED=true
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1440,14 +1685,20 @@ CONSOLIDATION_ENABLED=true
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1488,13 +1739,43 @@ CONSOLIDATION_ENABLED=true
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
-# CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1508,17 +1789,34 @@ CONSOLIDATION_ENABLED=true
-`3111` 포트의 124개 엔드포인트. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `AGENTMEMORY_SECRET`이 설정되었을 때 `Authorization: Bearer `를 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에서 `AGENTMEMORY_SECRET`을 요구합니다.
+포트 `3111`의 엔드포인트 138개. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `Authorization: Bearer `을 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에 `AGENTMEMORY_SECRET`이 명시적으로 설정되어 있어야 합니다.
+
+**인증은 기본적으로 켜져 있습니다.** `AGENTMEMORY_SECRET`이(셸이나 `~/.agentmemory/.env`에) 설정되어 있지 않으면, 서버는 첫 시작 시 무작위 시크릿을 생성해 `~/.agentmemory/secret`에 `0600` 권한으로 저장합니다. 번들된 모든 클라이언트는 로컬 서버와 통신할 때 그곳에서 이를 읽습니다: CLI, 뷰어, `plugin/scripts` 아래의 hook, MCP 서버와 `@agentmemory/mcp` shim, `agentmemory connect`가 작성하는 설정, 그리고 번들된 OpenCode, Pi, OpenClaw, Hermes, filesystem-watcher 통합까지입니다. 저장된 시크릿은 loopback URL(`localhost`, `127.0.0.0/8`, `::1`)에만 전송됩니다. 명시적인 `AGENTMEMORY_SECRET`은 항상 우선하며, 원격 클라이언트는 여전히 이를 설정해야 합니다. Docker와 `deploy/` 진입점은 이미 자체 시크릿을 생성하고 export합니다. API를 직접 호출하려면:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**쓰기 요청 규칙.** REST API와 뷰어에 대한 `POST`, `PUT`, `PATCH`, `DELETE` 요청은 본문이 있을 때마다 `Content-Type: application/json`을 보내야 하며(`charset` 파라미터는 괜찮습니다), `Origin` 헤더가 있다면 설정된 REST 또는 뷰어 포트의 loopback origin이거나 `VIEWER_ALLOWED_ORIGINS`(쉼표로 구분, 예: `https://memory.example.com`)에 나열되어 있어야 합니다. `Origin` 헤더를 보내지 않는 클라이언트(CLI, hook, MCP, curl, 서버 간 호출)는 영향을 받지 않습니다. 뷰어는 자신의 origin도 허용합니다.
+
+**파일 경로.** 파일을 읽거나 쓰는 엔드포인트(`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`)는 `~/.agentmemory`, 인스턴스 데이터 디렉터리, 또는 `AGENTMEMORY_IMPORT_ROOT`에 나열된 디렉터리(여러 개는 `:`로, Windows에서는 `;`로 구분) 아래의 경로만 받습니다. `/replay/import-jsonl`은 기본값인 `~/.claude/projects`도 받습니다. `/obsidian/export`는 `AGENTMEMORY_EXPORT_ROOT` 안에, `/migrate`는 `~/.agentmemory` 안에 머뭅니다. 심볼릭 링크는 매 검사 전에 해석됩니다.
+
+**시크릿 제거.** API 키, bearer 토큰, PEM 개인 키 블록, URL에 내포된 자격 증명(`scheme://user:password@host`)은 텍스트가 저장되기 전에 모든 쓰기 경로에서 삭제됩니다: 관측, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, 압축과 요약 출력, crystal, 그래프 노드까지입니다.
주요 엔드포인트
-| Method | Path | 설명 |
+| 메서드 | Path | 설명 |
|--------|------|-------------|
-| `GET` | `/agentmemory/health` | 헬스 체크 (항상 공개) |
-| `POST` | `/agentmemory/session/start` | 세션 시작 + 컨텍스트 가져오기 |
+| `GET` | `/agentmemory/health` | Health 체크 (항상 공개) |
+| `GET` | `/agentmemory/status` | 무엇이 문제인지와 해결 방법 (브라우저에는 HTML, 그 외에는 JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | 뷰어가 보여주는 모든 것을 하나의 응답으로 |
+| `POST` | `/agentmemory/session/start` | 세션 시작 + 컨텍스트 받기 |
| `POST` | `/agentmemory/session/end` | 세션 종료 |
-| `POST` | `/agentmemory/observe` | 관측 캡처 |
+| `POST` | `/agentmemory/observe` | 관측 캡처 (아래의 캡처 전달 참고) |
+| `GET` | `/agentmemory/capture` | 캡처 인박스, dead letter, 오프라인 spool |
+| `POST` | `/agentmemory/capture/retry` | dead-letter 캡처 재시도 |
+| `POST` | `/agentmemory/capture/drain` | 로컬 오프라인 spool을 지금 전송 |
| `POST` | `/agentmemory/smart-search` | 하이브리드 검색 |
| `POST` | `/agentmemory/context` | 컨텍스트 생성 |
| `POST` | `/agentmemory/remember` | 장기 메모리에 저장 |
@@ -1528,13 +1826,43 @@ CONSOLIDATION_ENABLED=true
| `GET` | `/agentmemory/export` | 모든 데이터 내보내기 |
| `POST` | `/agentmemory/import` | JSON에서 가져오기 |
| `POST` | `/agentmemory/graph/query` | 지식 그래프 쿼리 |
+| `POST` | `/agentmemory/graph/compact` | 과도하게 커진 그래프 출처 정리 |
| `POST` | `/agentmemory/team/share` | 팀과 공유 |
-| `GET` | `/agentmemory/audit` | 감사 로그 |
+| `GET` | `/agentmemory/audit` | 감사 기록 |
전체 엔드포인트 목록: [`src/triggers/api.ts`](../src/triggers/api.ts)
+**캡처 전달.** hook은 각 관측을 `eventId`와 함께 `POST /agentmemory/observe`로 한 번 전송합니다. payload에 자체 id가 있으면(예: Claude Code의 `tool_use_id`) 그 호출의 호스트 고유 id를 사용하고, 없으면 세션, hook 유형, 도구 이름, 입력, 출력, 호스트 타임스탬프의 해시를 사용합니다. 서버는 이벤트를 state 저장소의 캡처 인박스에 기록하고, 관측을 저장한 다음, 인박스 항목을 제거합니다. 상태 코드는 무슨 일이 있었는지를 알려줍니다:
+
+| 상태 코드 | `status` 필드 | 의미 |
+|---|---|---|
+| `201` | `accepted` | 저장됨. `observationId`는 새로운 관측입니다. |
+| `202` | `accepted` (`state: "retrying"`) | 수락되었지만 저장에 실패했습니다. 서버는 재시작 후에도 이를 재시도합니다. |
+| `200` | `duplicate` | 이 `eventId`는 이미 수락되었습니다. `observationId`는 기존 관측이며, 새로 저장되는 것은 없습니다. |
+| `400` / `422` | `rejected` | payload가 잘못되었거나 저장이 영구적으로 실패했습니다 (이벤트는 dead letter로 보관됩니다). |
+| `503` | `rejected` (`retryable: true`) | 인박스가 가득 찼습니다(`AGENTMEMORY_CAPTURE_INBOX_MAX`). hook은 이벤트를 spool에 저장해 두고 나중에 전송합니다. |
+
+실패한 이벤트는 `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`(10초)마다 백오프를 두 배씩 늘려가며 `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`(5회)까지 재시도됩니다. 여전히 실패하는 이벤트는 dead letter로 인박스에 남아 `/agentmemory/status`와 뷰어의 Health 페이지에 나열되며, `POST /agentmemory/capture/retry`(`{"eventId": "..."}` 또는 `{"all": true}`)로 재시도할 수 있습니다. 수락된 이벤트 id는 `AGENTMEMORY_CAPTURE_DEDUP_HOURS`(168시간, 최대 `AGENTMEMORY_CAPTURE_EVENTS_MAX`개) 동안 기억되므로, 타임아웃이나 재시작 후 재생된 hook은 한 번만 저장되지만, 각자 호스트 id를 가진 두 개의 별도 도구 호출은 내용이 동일해도 두 번 저장됩니다. 관측이 삭제되면(forget, 세션 삭제, eviction, 자동 망각, 또는 스토어를 교체하는 import) 그 이벤트는 관측이 제거되기 전에 삭제됨으로 표시되므로, 같은 시간 범위 안에서 그 이벤트를 재생하면 duplicate로 응답되고 아무것도 저장하지 않습니다. state 저장소는 2초마다 디스크에 기록하므로, 응답된 이벤트가 잠깐 동안은 메모리에만 있을 수 있습니다. 이를 보완하기 위해 모든 `2xx` 응답은 서버의 `bootId`(매 시작마다 새로 생성), `acceptedAt`, `durableAfterMs`(파일 스토어에서는 저장 간격 + 1.5초, redis에서는 1.5초이며, 영속성은 운영자의 설정에 따름)도 함께 전달합니다. hook은 그 시간 범위가 지날 때까지 이벤트를 로컬 spool에 보관하고, 추가 요청 없이 이후 호출에서 이를 삭제합니다. 그 사이에 `bootId`가 바뀌었다면 서버가 재시작된 것이므로, hook은 동일한 `eventId`로 이벤트를 다시 보냅니다. 디스크에 실제로 도달한 이벤트는 두 번 저장되지 않습니다. 서버 또한 시작 시와 매 재시도 간격마다 그런 이벤트를 스스로 전송하므로, 이후 어떤 hook도 실행되지 않더라도 재시작으로 데이터가 손실되지 않습니다. 오래된 hook은 추가 필드를 무시하고, 더 오래된 서버를 상대하는 새 hook은 예전처럼 `2xx`에서 이벤트를 버립니다.
+
+서버가 다운되었거나, 제때 응답하지 않거나, 5xx를 반환하면, hook은 관측을 로컬 spool 파일 `/capture-spool/-.jsonl`에 추가합니다(폴더는 `AGENTMEMORY_CAPTURE_SPOOL_DIR`로 재정의할 수 있습니다). 이 파일은 사용자 전용(모드 600)이며, 시크릿은 서버가 제거하는 방식과 동일하게 제거되고, 최대 `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`(5MiB)까지 보관하며 `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`(168)보다 오래된 항목은 버립니다. 가득 차면 새 항목은 버려지고 집계되며, `/agentmemory/status`가 이를 보고합니다. 서버가 정상일 때는 hook이 여전히 시간 제한 안에 0으로 종료하고 추가 요청을 보내지 않습니다. spool은 다음 시작 시점과, 서버에 다시 도달하는 첫 hook에 의해 백그라운드 프로세스로 전송되므로 에이전트가 기다리지 않습니다. 이벤트 id가 이를 안전하게 만듭니다: 타임아웃 전에 실제로 도착한 관측은 두 번 저장되지 않습니다. `npx @agentmemory/agentmemory capture`는 spool과 서버 인박스를 보여주고, `--drain`은 지금 spool을 전송하며, `GET /agentmemory/capture`는 동일한 내용을 JSON으로 반환합니다. spool을 끄려면 `AGENTMEMORY_CAPTURE_SPOOL=false`를 설정하십시오.
+
+**그래프 출처 압축.** 각 지식 그래프 노드와 엣지는 자신이 비롯된 가장 최근 관측 32개의 id를 보관합니다. 이 한도가 적용되기 전에 작성된 스토어는 활발한 노드마다 수천 개의 id를 가지고 있을 수 있는데, 이는 그래프 검색과 뷰어를 느리게 만들거나 워커를 다운시킵니다. agentmemory는 스스로 이를 고칩니다: 업그레이드 후 첫 시작 시, 모든 노드, 엣지, 대체된 엣지(시간적 그래프 기록), 캐시된 스냅샷을 백그라운드에서 그 한도까지 작은 조각 단위로, 사이에 일시 정지를 두고 정리하므로 검색, 캡처, 뷰어는 계속 동작합니다. 진행 상황을 저장하고, 재시작 후 이어서 진행하며, 완료되면 다시는 실행되지 않습니다. `/agentmemory/status`와 뷰어의 Health 페이지는 이를 pending, running(현재 스코프와 위치와 함께), done, failed로 보여줍니다. 끄려면 `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`를 설정하십시오.
+
+수동으로 실행하려면 `POST /agentmemory/graph/compact`를 호출하십시오. 모든 노드와 엣지를 나열하는 대신 name과 edge-key 인덱스를 순회하며, 다시 실행해도 안전합니다. id를 정리할 때는 `graph_compact` 감사 항목을 기록합니다.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+큰 스토어에서, 또는 호출이 504를 반환할 때는 조각 단위로 실행하십시오. `scope`(`nodes`, `edges`, `history`), `offset`, `limit`을 보낸 다음, 반환된 `nextOffset`이 `null`이 될 때까지 다시 호출하십시오. `nodes`, `edges`, `history` 각각에 대해 이를 수행하고, 조각 단위 실행은 캐시된 스냅샷을 건드리지 않으므로 마지막에 `{"scope":"snapshot"}` 호출 하나로 마무리하십시오.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1542,11 +1870,11 @@ CONSOLIDATION_ENABLED=true
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**전제 조건:** Node.js >= 20, [iii-engine](https://iii.dev/docs) 또는 Docker
+**사전 요구 사항:** npm/npx가 포함된 Node.js >= 20; [iii-engine](https://iii.dev/docs) v0.22.1 또는 Docker. macOS/Linux 자동 엔진 설치에는 `curl`, POSIX `sh`, `tar`도 필요합니다. 네이티브 Windows는 수동으로 고정한 `iii.exe`, WSL2, 또는 Docker Desktop을 사용합니다.
diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.md
new file mode 100644
index 0000000000..334ba7c453
--- /dev/null
+++ b/READMEs/README.nb-NO.md
@@ -0,0 +1,1882 @@
+
+
+
+
+
+
+ Kodeagenten din husker alt. Ikke forklar alt på nytt.
+ Bygget på iii-motoren
+
+ Persistent hukommelse for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, og enhver MCP-klient.
+
+
+---
+
+## Install
+
+Krav:
+
+- Node.js 20 eller nyere med npm og npx (`node -v`, `npm -v`, og `npx -v`).
+- Automatisk installasjon av iii-engine på macOS/Linux krever også `curl`, en POSIX-`sh`, og `tar`. Minimale images som `node:20-slim` har ikke nødvendigvis disse.
+- Native Windows krever at den fastlåste iii-engine v0.22.1 `iii.exe` installeres manuelt. WSL2 eller Docker Desktop er de andre støttede veiene.
+
+Den kanoniske kommandoen for en fersk installasjon:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Den første kjøringen er et interaktivt oppsett: velg hvilke agenter som skal kobles til (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), velg en LLM-leverandør eller fortsett nøkkelfritt, og den fyller ut konfigurasjonen, starter minneserveren og dens fastlåste iii-engine, og tilbyr å installere globalt slik at den rene `agentmemory`-kommandoen fungerer overalt etterpå. `-y` godtar npx' pakkespørsmål og `@latest` unngår en utdatert, cachet utgivelse. En leverandør gjør LLM-funksjoner tilgjengelige, men LLM-skrevet observasjonskomprimering starter først når `AGENTMEMORY_AUTO_COMPRESS=true` også er satt.
+
+Nøkkelfri modus deaktiverer vektor-embeddings. `memory_recall` (stien `mem::search`) bruker BM25, mens `memory_smart_search` også kan slå sammen strukturelle grafmatcher når grafdata allerede finnes. For gratis semantisk gjenkalling på enheten, sett `EMBEDDING_PROVIDER=local` i `~/.agentmemory/.env` og start på nytt. Den første embedding-forespørselen laster ned `Xenova/all-MiniLM-L6-v2`; etter den innledende modellnedlastingen kjører inferensen lokalt.
+
+Den lokale kjøretiden bruker fire porter: `3111` for REST/MCP HTTP, `3112` for iii-strømmer, `3113` for viewer, og `49134` for iii-worker-WebSocket. Persistent iii-tilstand lever i `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, og `%APPDATA%\agentmemory` på Windows. Bruk `--data-dir ` eller `AGENTMEMORY_DATA_DIR` for å overstyre dette, og bruk samme verdi ved hver omstart. For bakoverkompatibilitet går en eksisterende `./data/state_store.db` eller `./data/iii-config.yaml` foran plattformstandarden for instans 0; et uttrykkelig flagg eller miljøvariabel vinner likevel.
+
+Deretter kan du bevise at gjenkalling fungerer og gi agenten din dens skills:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed eksempelsesjoner + utløs gjenkalling
+npx skills add rohitg00/agentmemory -y # 17 native skills slik at agenten din vet når den skal bruke hukommelsen
+```
+
+Nøkkelordsøkene bør gi treff i standard nøkkelfri modus via BM25. Demoens `database performance optimization`-søk er med vilje semantisk og kan returnere null treff før en embedding-leverandør er konfigurert.
+
+Foretrekker du å la en kodeagent gjøre hele jobben? Gi den én instruksjon:
+
+> Hent og følg instruksjonene på: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Koble til flere agenter når du vil med `agentmemory connect ` — 20 adaptere er listet under [Works with every agent](#works-with-every-agent). Full kommandoreferanse under [Quick Start](#quick-start).
+
+
+Windows
+
+Den raskeste veien er WSL2. Oppsett av native Windows-engine krever at den fastlåste v0.22.1-ZIP-filen lastes ned og `iii.exe` pakkes ut manuelt; CLI-en pakker den ikke ut automatisk. Docker Desktop er også støttet. Se [Windows-notatene](#windows) for trinn-for-trinn-veiledning.
+
+
+
+
+Global installasjon / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+npx-kommandoen over er fortsatt den kanoniske veien for en fersk installasjon og unngår tillatelsesproblemer med den globale prefiksen.
+
+
+
+
+npx serverer en gammel versjon
+
+npx cacher per versjon. Tvinge den nyeste med `npx -y @agentmemory/agentmemory@latest`, eller tøm cachen én gang med `rm -rf ~/.npm/_npx` (macOS/Linux; på Windows, slett `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Kjører allerede din egen iii-engine
+
+agentmemory fastlåser iii-engine v0.22.1 og kobler seg ikke til en annen versjon (workeren kan ikke snakke en annen engines protokoll). Stopp den andre engine-instansen, og kjør deretter `npx -y @agentmemory/agentmemory@latest`. Den installerer og kjører den fastlåste v0.22.1 i `~/.agentmemory/bin`, uten å røre din egen `iii`.
+
+
+
+---
+
+
+
+agentmemory fungerer med enhver agent som støtter hooks, MCP eller REST API. Alle agenter deler samme minneserver.
+
+
+ Fungerer med enhver agent som snakker MCP eller HTTP. Én server, minner delt mellom alle.
+
+
+---
+
+Du forklarer samme arkitektur hver sesjon. Du gjenoppdager de samme feilene. Du gjenlærer agenten de samme preferansene. Innebygd hukommelse (CLAUDE.md, .cursorrules) stopper ved 200 linjer og blir utdatert. agentmemory løser dette. Den fanger stille opp det agenten din gjør, komprimerer det til søkbar hukommelse, og injiserer riktig kontekst når neste sesjon starter. Én kommando. Fungerer over flere agenter.
+
+**Hva som endrer seg:** I sesjon 1 setter du opp JWT-autentisering. I sesjon 2 ber du om rate limiting. Agenten vet allerede at autentiseringen din bruker jose-middleware i `src/middleware/auth.ts`, at testene dine dekker token-validering, og at du valgte jose over jsonwebtoken for Edge-kompatibilitet — uten at du må forklare det på nytt eller kopiere inn kode.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Som standard lagrer agentmemory iii-engine-tilstanden utenfor repoet du starter den fra: `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, og `%APPDATA%\agentmemory` på Windows. En eksisterende eldre `./data/state_store.db` eller `./data/iii-config.yaml` gjenbrukes for instans 0 før denne plattformstandarden. For å velge en plassering uttrykkelig, send `--data-dir ` eller sett `AGENTMEMORY_DATA_DIR`; begge uttrykkelige innstillinger går foran den eldre oppdagelsen:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native og Docker-oppstarter bruker samme oppløste host-katalog; Docker monterer den på `/data`. `--instance 1` legger `instance-1` til den oppløste katalogen og velger den separate standard portkvartetten `3211/3212/3213/49234`.
+
+Nyeste versjonsnotater: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Nøyaktighet ved gjenfinning
+
+**coding-agent-life-v1** (eget korpus, reproduserbart i sandbox)
+
+| Adapter | P@5 | R@5 | Topp-5-treffrate | p50-latens |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep-baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100 % topp-5-treffrate ved **P@5-matematikktaket** for dette korpuset (0.240, se scorekortet). Hybrid finner hver gullsesjon; grep mister 1 av 2 gull på det flersesjons-temporale søket. Gevinsten er **recall + temporal**, ikke samlet presisjon. Denne ytelsestesten er liten og gull-sparsom; den større LongMemEval-S nedenfor skiller bedre. Full oppdeling per type + korrigeringsnotat: [`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 spørsmål)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Kun BM25-fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+> Embedding-modell: `all-MiniLM-L6-v2` (lokal, gratis, ingen API-nøkkel). Fullstendige rapporter: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Konkurrentsammenligning: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) dekker agentmemory mot mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Reprodusér lokalt:** [`eval/README.md`](../eval/README.md), en adapter-plugbar harness for LongMemEval `_s` (offentlig 500 spørsmål) + `coding-agent-life-v1` (eget korpus på 15 sesjoner). Grep-, vektor- og agentmemory-adaptere scores side ved side, NDJSON-utdata, publiserte scorekort havner i [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Fungerer godt sammen med [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), og [Graphify](https://github.com/safishamsi/graphify).** Kodegrafindeksering, flerstegs byggepipeliner, og bredere kunnskapsgrafer over dokumenter/PDF-er/bilder/videoer. agentmemory husker arbeidet; disse tre prosjektene lyser opp resten av kontekstlaget. Oppskrifter + spørsmål-rutingstabell: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+Merk om ytelsestester: kun agentmemorys R@5 er vårt eget målte resultat (LongMemEval-S, reproduserbart fra benchmark/COMPARISON.md). Tallene for mem0 og Letta er deres publiserte LoCoMo-tall (et annet datasett); tallene for MemPalace, supermemory, TencentDB (PersonaMem) og oracleagentmemory er leverandørers selvrapporterte påstander vi ikke har reprodusert selv (oracleagentmemorys kjøring brukte GPT-5.5 mot en Oracle AI Database). Vist side ved side kun som et grovt sammenligningsgrunnlag, ikke en direkte sammenligning på identiske data. Stjernetall er tilnærmede og endrer seg over tid.
+
+**Nyere aktører** verdt å kjenne til, sammenlignet i detalj i [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| System | ⭐ | Vinkling |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporal kunnskapsgraf; de sterkeste publiserte resultatene på temporale søk (LongMemEval 63.8%), men grafen bygges asynkront så ferske fakta kan ligge etter |
+| Cognee | 30K | Dokument-til-kunnskapsgraf-innlasting, kun Python, bygget for strukturert entitetsuttrekk snarere enn sesjonsfangst |
+
+Ingen av disse fanger automatisk fra kodeagent-hooks, leverer en lokal-først viewer, eller kjører nøkkelfritt — kombinasjonen agentmemory er bygget rundt.
+
+---
+
+
+
+Kompatibilitet: denne utgivelsen bruker `iii-sdk` 0.22.1 og fastlåser iii-engine v0.22.1.
+
+### Prøv det på 30 sekunder
+
+```bash
+# Terminal 1: start serveren
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed eksempeldata og se gjenkalling i praksis
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` seeder 3 realistiske sesjoner (JWT-autentisering, N+1-spørringsfiks, rate limiting) og kjører søk mot dem. Nøkkelfrie installasjoner deaktiverer vektorer, så nøkkelordsøkene i `mem::search` bør gi treff via BM25, mens `database performance optimization` kan returnere null treff. `smart-search` kan i tillegg returnere strukturelle grafmatcher når grafdata finnes. For å få det semantiske søket til å finne N+1-fiksen via vektorer, sett `EMBEDDING_PROVIDER=local`, start på nytt, og vent til den første modellnedlastingen er fullført.
+
+Åpne `http://localhost:3113` for å se hukommelsen bygges opp live.
+
+### Validere en fersk installasjon og persistens ved omstart
+
+Med serveren i gang, valider REST, health, viewer, og den iii-baserte kjøretidsstatusen:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Oppstartspanelet for "ready" dekker alle fire portene: REST/MCP HTTP på 3111, iii-strømmer på 3112, viewer på 3113, og iii-worker-WebSocket på 49134. `status` bekrefter agentmemorys helse og den aktive leverandør-/embedding-modusen. Lagre en probe og bekreft at den er søkbar:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Kjør deretter `npx -y @agentmemory/agentmemory@latest stop`, start den kanoniske kommandoen på nytt i Terminal 1, vent på `/agentmemory/livez`, og gjenta søket. Proben må fortsatt returneres. Hvis du valgte en egendefinert `--data-dir`, bruk samme katalog ved omstarten.
+
+### Daglige kommandoer
+
+Installasjon og oppsett er beskrevet i [Install](#install) over (den første kjøringen leder deg gjennom det). Til daglig bruk:
+
+```bash
+agentmemory # start serveren
+agentmemory stop # stopp den rent
+agentmemory connect # koble til en annen agent
+agentmemory doctor # interaktiv diagnostikk + forslag til fiks
+agentmemory remove # avinstaller alt vi opprettet
+```
+
+### Sesjonsavspilling
+
+Hver sesjon agentmemory registrerer kan spilles av på nytt. Åpne viewer, velg fanen **Replay**, og spol gjennom tidslinjen: prompter, verktøykall, verktøyresultater og svar vises som separate hendelser med spill/pause, hastighetskontroll (0.5x til 4x), og tastatursnarveier (mellomrom for å veksle, piltaster for å gå trinn for trinn).
+
+For å hente inn eldre Claude Code JSONL-transkripsjoner:
+
+```bash
+# Importer alt under standard ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Eller importer én enkelt fil
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Importerte sesjoner vises i Replay-velgeren side om side med native sesjoner. Under overflaten rutes hver oppføring gjennom iii-funksjonene `mem::replay::load`, `mem::replay::sessions`, og `mem::replay::import-jsonl`, uten noen sidekanal-servere. Hver importerte transkripsjon indekseres for søk, stemples med opprinnelseskanalen `import`, og bearbeides til en sesjonskrystall og læringspunkter.
+
+> **Viktig hvis du bruker `import-jsonl` som din primære fangstvei:** Claude Codes `cleanupPeriodDays` (i `~/.claude/settings.json`, standard **30**) sletter automatisk JSONL-transkripsjoner eldre enn dette vinduet fra `~/.claude/projects/`. Hvis du installerer agentmemory ferskt på en Claude Code-historikk som er flere måneder gammel, er alt eldre enn 30 dager allerede borte før den første importen. Kjør enten `import-jsonl` via cron, sett `cleanupPeriodDays` høyere, eller koble til auto-fangst-hookene (standard installasjonsvei for plugin) slik at hver tur lander i agentmemory mens sesjonen er aktiv, og JSONL-ryddingen ikke lenger har betydning.
+
+### Oppgradering / vedlikehold
+
+Bruk vedlikeholdskommandoen når du med vilje vil oppdatere den lokale kjøretiden:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Advarsel: denne kommandoen endrer den nåværende arbeidsflaten/kjøretiden. Den kan oppdatere JavaScript-avhengigheter og hente det fastlåste `iiidev/iii:0.22.1`-Docker-imaget. Den installerer aldri en ufastlåst eller nyere iii-engine.
+
+Implementasjonsdetaljer finnes i `src/cli.ts` (se `runUpgrade` rundt `src/cli.ts:544-595`).
+
+### Claude Code (én blokk, lim den inn)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code uten plugin-installasjon (MCP-frittstående vei)
+
+Hvis du kobler agentmemorys MCP-server direkte gjennom `~/.claude.json` i stedet for å bruke `/plugin install`, løser Claude Code aldri opp `${CLAUDE_PLUGIN_ROOT}`, og du må peke hook-skriptene til absolutte stier i `~/.claude/settings.json`. Disse stiene bygger typisk inn agentmemory-versjonen (f.eks. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), så neste oppgradering knekker stille hver hook.
+
+Løsning:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Dette slår sammen de samme hook-kommandoene inn i `~/.claude/settings.json` med absolutte stier løst opp mot den medfølgende `plugin/`-katalogen til den installerte `@agentmemory/agentmemory`-pakken. Kjør kommandoen på nytt etter at du har oppgradert agentmemory for å oppdatere stiene. Brukeroppføringer i samme fil bevares; kun tidligere agentmemory-oppføringer byttes ut. Å bruke `/plugin install`-veien er fortsatt den anbefalte metoden.
+For eksterne eller beskyttede distribusjoner, start Claude Code med `AGENTMEMORY_URL` og `AGENTMEMORY_SECRET` satt. Pluginen sender begge verdiene videre til sin medfølgende MCP-server; når `AGENTMEMORY_URL` er tom, bruker MCP-shimmen `http://localhost:3111`.
+
+### Codex CLI (Codex-plugin-plattformen)
+
+```bash
+# 1. start minneserveren i en separat terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. registrer agentmemory-markedsplassen og installer pluginen
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex-pluginen leveres fra samme `plugin/`-katalog som Claude Code-pluginen. Den registrerer:
+
+- En medfølgende stdio MCP-bro til den kjørende daemonen, uten npm-nedlasting eller fallback-lager. Se [den lokale Codex-veiledningen](../docs/plugins/codex-local.md) for å teste en build som ennå ikke er utgitt.
+- 6 livssyklus-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skills som kan kalles: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, pluss 8 referanseskills agenten laster ved behov (minnedisiplin, MCP-verktøy, REST API, konfigurasjon, agenter, hooks, arkitektur, og skill-forfatterveiledningen)
+
+Codex' hook-motor injiserer `CLAUDE_PLUGIN_ROOT` inn i hook-underprosesser (ifølge [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), så de samme hook-skriptene fungerer på begge verter uten duplisering. Subagent-/SessionEnd-/Notification-/TaskCompleted-/PostToolUseFailure-hendelser er kun for Claude Code og registreres ikke for Codex.
+
+#### Codex-hooks: tillit og kompatibilitet
+
+Native plugin-hook-utsendelse er verifisert med Codex CLI 0.150.1. Stol på plugin-hooksene før du forventer fangst. Desktop-oppførselen avhenger av dens medfølgende kjøretid; kontroller `/hooks` og bekreft en fanget hendelse før du aktiverer en løsning.
+
+Hvis verten din krever globale hooks, speil kommandoene inn i `~/.codex/hooks.json`. Når MCP allerede er tilkoblet, trenger den nåværende adapteren `--force` for å nå hook-installasjonen:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Dette slår sammen globale hooks og skriver om agentmemory MCP-oppføringen, og bevarer urelaterte oppføringer. Gå gjennom eventuelle egendefinerte agentmemory-endepunktinnstillinger før du bruker `--force`. Kjør på nytt etter oppgradering for å oppdatere skriptstiene. Aktiver enten native plugin-hooks eller globale kopier for å unngå duplisert fangst.
+
+### GitHub Copilot CLI
+
+For VS Code agent-modus, bruk [Copilot MCP- og auto-fangst-veiledningen](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-adapteren konfigurerer ikke VS Code.
+
+```bash
+# Kun MCP-tilkobling
+agentmemory connect copilot-cli
+
+# Alternativt, full hooks/skills-plugin fra GitHub-undermappen
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` slår sammen `mcpServers.agentmemory` inn i `~/.copilot/mcp-config.json` (eller `$COPILOT_HOME/mcp-config.json` når `COPILOT_HOME` er satt) og bevarer eksisterende servere. På native Windows er dette den eneste automatiserte `connect`-adapteren; konfigurer alle andre native Windows-agenter manuelt. WSL-`connect` er kun støttet når målagenten også er installert i samme WSL-miljø. Installer også pluginen når du vil ha hele hook-/skill-opplevelsen.
+
+
+OpenClaw (lim inn denne prompten)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Full veiledning: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (lim inn denne prompten)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Full veiledning: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Andre agenter
+
+Start minneserveren: `npx -y @agentmemory/agentmemory@latest`
+
+#### Native skills via `npx skills add` (50+ agenter)
+
+agentmemory leveres med 17 skills i Claude-Code-stilens `/SKILL.md`-format: 9 skills som kan kalles (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) og 8 referanseskills agenten laster ved behov (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referanseskillene har datatabeller generert fra kildekoden, så de aldri går ut av synk. CLI-en [`skills`](https://npmjs.com/package/skills) fra vercel-labs installerer dem automatisk inn i den kallende agentens native skill-katalog over 50+ agenter (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, med flere):
+
+```bash
+npx skills add rohitg00/agentmemory -y # oppdager den kallende agenten automatisk
+npx skills add rohitg00/agentmemory -y -a warp # uttrykkelig agent
+npx skills add rohitg00/agentmemory -y -a '*' # installer til hver installerte agent
+```
+
+Dette er **utfyllende** til `agentmemory connect `:
+
+- `agentmemory connect ` skriver MCP-serverkonfigurasjonen slik at verktøyene er tilgjengelige.
+- `npx skills add rohitg00/agentmemory` installerer skillene slik at agenten vet når den skal kalle dem.
+
+For de få agentene skills-CLI-en ikke dekker ennå (Zed v1.3.x og eldre), legg de 17 SKILL.md-filene manuelt under agentens native skill-katalog; samme format fungerer overalt.
+
+#### Standard MCP-blokk
+
+agentmemory-oppføringen er **samme MCP-server-blokk** på tvers av alle verter som bruker `mcpServers`-formen (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Slå denne oppføringen sammen med det eksisterende `mcpServers`-objektet** i vertens konfigurasjonsfil; ikke erstatt filen. Hvis filen allerede har andre servere, legg til `agentmemory` ved siden av dem som en ny nøkkel inne i `mcpServers`. Hvis `mcpServers` mangler helt, lim inn blokken inne i `{ "mcpServers": { ... } }`. `${VAR}`-plassholderne arver `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` fra skallet når MCP-serveren starter; usatte variabler gir tomme strenger og shimmen faller tilbake til `http://localhost:3111`. Én tilkoblet oppføring dekker både lokale og eksterne (k8s / reverse-proxy) distribusjoner.
+
+| Agent | Konfigurasjonsfil | Merknader |
+|---|---|---|
+| **Cursor (kun MCP)** | `~/.cursor/mcp.json` | Slå sammen inn i `mcpServers`, eller `agentmemory connect cursor`. Et direktelink med ett klikk er også tilgjengelig på nettsiden. |
+| **Cursor (full plugin)** | `.cursor-plugin/` | Oppføring på Cursor Marketplace (innsending under vurdering) eller Cursor Settings → Plugins → lokalt sjekket ut. Registrerer 7 auto-fangst-hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + MCP-serveren, med `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` administrert i Cursors plugin-dashbord. Fungerer i Cursor-IDE-en og `cursor-agent`-CLI-en; CLI-ens print-modus-prompter fylles etterpå inn fra sesjonstranskripsjonen når sesjonen avsluttes. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Slå sammen inn i `mcpServers`. Start Claude Desktop på nytt etter redigering. |
+| **Cline / Roo Code / Kilo Code** | Clines MCP-innstillinger (Settings-UI → MCP Servers → Edit) | Samme `mcpServers`-blokk. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` slår sammen MCP-oppføringen; `--with-hooks` legger til seks native auto-fangst-hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) med Devins små bokstaver i verktøymatcherne. Verifiser med `devin mcp list` og `/hooks` inne i devin. |
+| **Devin CLI (full plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` fra et checkout registrerer alle 17 skills som `/agentmemory:`-slash-kommandoer pluss MCP-serveren. Devins plugin-hooks kan ikke utløse `SessionStart`/`SessionEnd`, så kombiner den med `connect devin --with-hooks` for full sesjonsfangst. |
+| **Devin (sky)** | Settings → Connections → MCP servers | Legg til en egendefinert MCP (STDIO): kommando `npx`, argumenter `-y @agentmemory/mcp@latest`, miljøvariabel `AGENTMEMORY_URL` pekende på en nettverksnåbar agentmemory-distribusjon pluss `AGENTMEMORY_SECRET` (sky-sesjoner kan ikke nå localhost — se [`deploy/`](../deploy/)). Lagre hemmeligheten i Devin Secrets, og bruk deretter "Test listing tools" for å verifisere at alle 54 verktøyene vises. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (slås sammen automatisk). |
+| **GitHub Copilot CLI (kun MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` slår sammen `mcpServers.agentmemory`; Copilot plukker det opp ved neste oppstart eller `/mcp`. |
+| **GitHub Copilot CLI (full plugin)** | Copilot plugin-installasjon | `copilot plugin install rohitg00/agentmemory:plugin` for pluginen fra GitHub-undermappen. |
+| **OpenClaw** | OpenClaw MCP-konfigurasjon | Samme `mcpServers`-blokk. Dypere: `openclaw plugins install ./integrations/openclaw` tar over OpenClaws minneplass (bytter automatisk fra `memory-core`); sett `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, ellers blokkeres turfangsten stille. Se [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (kun MCP)** | `.codex/config.toml` | TOML-form: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, eller legg til `[mcp_servers.agentmemory]` manuelt. |
+| **Codex CLI (full plugin)** | Codex plugin-markedsplass | `codex plugin marketplace add rohitg00/agentmemory` deretter `codex plugin add agentmemory@agentmemory`. Registrerer MCP + 6 livssyklus-hooks + 17 skills. Stol på hooks og bekreft fangst på verten din; se [Codex-oppsett og validering](../docs/plugins/codex-local.md). |
+| **OpenCode (kun MCP)** | `opencode.json` | Annen form: toppnivå-nøkkelen `mcp`, kommando som array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (full plugin)** | `plugin/opencode/` | 22 auto-fangst-hooks som dekker sesjonslivssyklus, meldinger, verktøy, feil. Prosjekttilskrivning er per sesjon, så én OpenCode-prosess som spenner over flere repoer registrerer hver sesjon under sitt eget prosjekt. To slash-kommandoer (`/recall`, `/remember`). Kopier `plugin/opencode/` inn i OpenCode-arbeidsområdet ditt og legg plugin-oppføringen til `opencode.json`. Se [`plugin/opencode/README.md`](../plugin/opencode/README.md) for hele hook-tabellen + gap-analysen. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installerer den medfølgende utvidelsen inn i pi-ens auto-oppdagelseskatalog (gjenkalling ved agentstart, fangst ved agentslutt, verktøyene `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` i en kjørende pi plukker den opp. [`integrations/pi`](../integrations/pi/) er også en pi-pakke (`pi install ./integrations/pi` fra et checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` gir 6-hook-minneleverandøren (prefetch, turfangst, sesjonsslutt, pre-compress, MEMORY.md-speiling, systemprompt-blokk). Valider med `hermes plugins doctor` og `hermes memory status`. Se [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` skriver standard `mcpServers`-blokk. Hook-nyttelasten er feltkompatibel med Claude Code, så de eksisterende 12-hook-skriptene fungerer uten endring; koble dem til via `hooks`-delen i samme `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installerer MCP og fangst-hooks i den delte tilpasningskatalogen. Se [Antigravity-oppsett og begrensninger](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` bruker samme MCP- og hook-konfigurasjon som nåværende IDE-versjoner. Eksisterende installasjoner bør oppdateres med `--force`; se [oppgraderingsnotatene](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` skriver brukernivå-konfigurasjonen. Arbeidsområde-overstyringer går i `.kiro/settings/mcp.json` ved siden av koden din. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` skriver standard `mcpServers`-blokk. Warp oppdager også automatisk skills fra `.claude/skills/`; når Claude Code-pluginen er installert vises de 8 agentmemory-skillene (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) naturlig i Warps slash-kommando-palett. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` skriver standard `mcpServers`-blokk. VS Code-utvidelsesbrukere: lim inn samme blokk via Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (foretrukket) eller `config.json` (eldre) | `agentmemory connect continue` oppretter `config.yaml` fra grunnen når ingen av dem finnes, eller endrer en eksisterende `config.json`. **Hvis du allerede har `config.yaml`** skriver adapteren ut den eksakte blokken som skal limes inn under `mcpServers:`; den overskriver ikke yaml-filen din stille, fordi det å bevare kommentarer og ankre trygt krever en YAML-parser pakken ikke leverer. Continue bruker array-form (ikke objekt) for `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` skriver under `context_servers` (Zeds nøkkel, IKKE `mcpServers`). Eksterne MCP-servere kan kobles til via `{"url": "..."}` i stedet. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` skriver standard `mcpServers`-blokk. Prosjektavgrensede overstyringer går i `/.factory/mcp.json`. Send `--with-hooks` for native auto-fangst. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` legger til en `@deepseek-ai/dsh-mcp-client`-rad i patch-laget på hjemmenivå som hver Harness-profil laster; verktøy registreres som `mcp__agentmemory__*`. Send `--with-hooks` for også å koble til auto-fangst: de medfølgende Claude Code-hook-skriptene kjører gjennom Harnessens egen `@deepseek-ai/dsh-hooks-claude-code`-bro (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via et manifest skrevet til `$DSH_HOME/agentmemory.hooks.json`. Standard er `~/.dsh` når `DSH_HOME` ikke er satt. |
+| **Goose** | Gooses MCP-innstillings-UI | Samme `mcpServers`-blokk; bruk `goose configure` → Add Extension → MCP. Direkte YAML-redigering ved `~/.config/goose/config.yaml` er støttet, men skjemaet bruker `extensions:` + `cmd` (ikke `mcpServers:` + `command`). |
+| **Aider** | n/a | Snakk direkte med REST-API-en: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Enhver agent (32+)** | n/a | `npx skillkit install agentmemory` oppdager verten automatisk og slår sammen. |
+
+**Sandkasse-MCP-klienter** (Flatpak / Snap / restriktive containere) som ikke kan nå vertens `localhost`: sett også `"AGENTMEMORY_FORCE_PROXY": "1"` i `env`-blokken, og pek `AGENTMEMORY_URL` mot en rute sandkassen faktisk kan nå (f.eks. din LAN-IP).
+
+### Programmatisk tilgang (Python / Rust / Node)
+
+agentmemory registrerer sine kjerneoperasjoner som iii-funksjoner (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Ethvert språk med en iii-SDK kan kalle dem direkte over `ws://localhost:49134`, uten en separat REST-klient per språk.
+
+```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"},
+})
+```
+
+Gjennomarbeidet eksempel: [`examples/python/`](../examples/python/) (hurtigstart + observasjon/gjenkalling-flyt). REST på `:3111` er fortsatt tilgjengelig for verter uten en iii-kjøretid.
+
+### Fra kildekode
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Dette starter agentmemory med en lokal `iii-engine` hvis den fastlåste binærfilen allerede er installert, eller bruker Docker Compose når det er valgt. REST, strømmer og viewer bindes til `127.0.0.1` som standard. Den automatiske binærfil-stien for macOS/Linux krever `curl`, en POSIX-`sh`, og `tar`.
+
+Installer `iii-engine` manuelt. **agentmemory fastlåser for øyeblikket `iii-engine` til `v0.22.1`**, samme utgivelse som dens `iii-sdk`-avhengighet; workeren snakker den enginens kablingsprotokoll, og 0.20.0 omorganiserte SDK-overflaten, så de to beveger seg sammen i agentmemory-utgivelser. Overstyr med `AGENTMEMORY_III_VERSION=` hvis du kjører din egen engine og vet at den matcher.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** bytt `aarch64-apple-darwin` med `x86_64-apple-darwin`
+- **Linux x64:** bytt til `x86_64-unknown-linux-gnu`
+- **Linux arm64:** bytt til `aarch64-unknown-linux-gnu`
+- **Windows:** last ned `iii-x86_64-pc-windows-msvc.zip` fra [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) og pakk ut `iii.exe` til `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Hvert arkiv har en matchende `.sha256`-fil på utgivelsessiden; når du bytter plattform, bruk den filens hash i kontrollen over (på Windows: `Get-FileHash`). Den automatiske installatøren i `npx @agentmemory/agentmemory` fastlåser disse hashene og avviser et arkiv som ikke stemmer.
+
+Eller bruk Docker (den medfølgende `docker-compose.yml` henter `iiidev/iii:0.22.1`). Full dokumentasjon: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory kjører på Windows 10/11, men Node.js-pakken alene er ikke nok; du trenger også den fastlåste iii-engine v0.22.1-kjøretiden som en bakgrunnsprosess. CLI-en pakker ikke automatisk ut Windows-ZIP-filen, så native Windows-brukere må installere `iii.exe` manuelt, bruke WSL2, eller velge Docker Desktop.
+
+Automatisert native Windows-MCP-tilkobling støtter bare `agentmemory connect copilot-cli`. For Claude Code, Codex, Cursor, og alle andre native Windows-agenter, kopier den manuelle MCP-blokken fra [Other agents](#other-agents) inn i agentens Windows-konfigurasjon. Å kjøre `connect` i WSL er bare riktig når målagenten også er installert i samme WSL-miljø; det endrer ikke konfigurasjonen til en agent som kjører på Windows-verten.
+
+**Alternativ A: ferdigbygget Windows-binærfil (anbefalt)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Alternativ B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Alternativ C: kun frittstående MCP (ingen engine).** Hvis du bare trenger MCP-verktøyene for agenten din og ikke trenger REST-API-en, viewer, eller cron-jobber, hopp over engine-en helt:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostikk for Windows:** hvis `npx -y @agentmemory/agentmemory@latest` mislykkes, kjør den på nytt med `--verbose` for å se den faktiske engine-stderr. Vanlige feilmodi:
+
+| Symptom | Fiks |
+|---|---|
+| `The engine process started but the REST API never responded.` | Bekreft at alle fire avledede porter er ledige, verifiser at den fastlåste `iii.exe` holdt seg i live, og kjør deretter på nytt med `--verbose` og undersøk den fangede engine-stderr |
+| `Could not start iii-engine` | Verken `iii.exe` eller Docker er installert. Se Alternativ A eller B over |
+| Portkonflikt | `netstat -ano \| findstr :3111` for å se hva som er bundet, og drep det eller bruk `--port ` |
+| Docker-fallback hoppet over selv om Docker er installert | Sørg for at Docker Desktop faktisk kjører (systemstatusfelt-ikon) |
+
+> Merk: iii-**engine** er en ferdigbygget binærfil, ikke en cargo-kiste, så ikke prøv å `cargo install` den. (iii-**SDK-ene** er publisert på crates.io, npm, og PyPI, men agentmemory trenger dem ikke.) Støttede installasjonsmetoder for engine er alle fastlåst til v0.22.1: den ferdigbygde binærfilen over, agentmemorys macOS/Linux-autoinstallasjonsvei (`curl`, POSIX-`sh`, og `tar` kreves), og Docker-imaget `iiidev/iii:0.22.1`. En ren oppstrøms `install.sh | sh` installerer den nyeste engine-en, som agentmemory ikke støtter. Bruk `npx -y @agentmemory/agentmemory@latest`; på macOS/Linux henter den den fastlåste engine-en inn i `~/.agentmemory/bin`.
+
+---
+
+
Deploy
+
+Maler med ett klikk for administrerte verter. Hver av dem leverer en
+selvstendig Dockerfile som henter `@agentmemory/agentmemory` fra npm og
+kopierer inn iii-engine-binærfilen fra det offisielle
+`iiidev/iii`-Docker Hub-imaget; ingen forhåndsbygget agentmemory-image
+er nødvendig. Persistent lagring monteres på `/data`;
+entrypointen ved første oppstart overskriver den npm-medfølgende
+iii-konfigurasjonen (som binder `127.0.0.1`) med en distribusjons-
+tilpasset versjon som binder `0.0.0.0` og bruker absolutte `/data`-
+stier, genererer HMAC-hemmeligheten, og senker deretter rettighetene
+fra `root` til `node` via `gosu` før den kjører agentmemory-CLI-en.
+
+
+
+
+
+
+Renders knapp for ett-klikks-distribusjon krever `render.yaml` i repoets rot, som vi med vilje holder ren. Bruk Render Blueprint-flyten dokumentert i [`deploy/render/`](.././deploy/render/README.md) for å peke på den interne blueprinten manuelt.
+
+Fullstendige oppsettsdetaljer (HMAC-fangst, SSH-tunnel for viewer, rotasjon, sikkerhetskopiering,
+kostnadsgulv) finnes i [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): én enkelt maskin med
+ `auto_stop_machines = "stop"`; billigst når inaktiv.
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby-planen, fast
+ pris, volum i dashbordet.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint-flyt,
+ automatiske disk-snapshot på betalte planer.
+- [`deploy/coolify`](.././deploy/coolify/README.md): selvhostet på din
+ egen VPS via [Coolify](https://coolify.io/self-hosted); samme Docker
+ Compose-stack, du eier verten og dataene.
+
+Kun port `3111` publiseres. Viewer på `3113` holdes bundet til
+loopback inne i containeren; hver mals README dokumenterer
+SSH-tunnel-mønsteret for å nå den.
+
+---
+
+
+
+Hver kodeagent glemmer alt når sesjonen avsluttes, og hver ny sesjon starter med at du forklarer stacken din på nytt. agentmemory kjører i bakgrunnen og fjerner dette steget.
+
+```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 innebygd agenthukommelse
+
+Hver AI-kodeagent leveres med innebygd hukommelse: Claude Code har `MEMORY.md`, Cursor har notisblokker, Cline har en minnebank. Disse fungerer som gule lapper. agentmemory er den søkbare databasen bak de gule lappene.
+
+| | Innebygd (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skala | Tak på 200 linjer | Ubegrenset |
+| Søk | Laster alt inn i konteksten | BM25 + vektor + graf (kun topp-K) |
+| Tokenkostnad | 22K+ ved 240 observasjoner | ~1 900 tokens (92 % mindre) |
+| Tvers av agenter | Filer per agent | MCP + REST (hvilken som helst agent) |
+| Koordinering | Ingen | Leaser, signaler, handlinger, rutiner |
+| Observerbarhet | Les filer manuelt | Viewer i realtid på :3113 |
+
+---
+
+
+
+### Hukommelsespipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-nivås hukommelseskonsolidering
+
+Modellert etter hvordan menneskehjernen behandler hukommelse, inkludert konsolidering under søvn.
+
+| Nivå | Hva | Analogi |
+|------|------|---------|
+| **Working (arbeid)** | Rå observasjoner fra verktøybruk | Korttidshukommelse |
+| **Episodic (episodisk)** | Komprimerte sesjonsoppsummeringer | "Hva som skjedde" |
+| **Semantic (semantisk)** | Uttrukne fakta og mønstre | "Hva jeg vet" |
+| **Procedural (prosedyral)** | Arbeidsflyter og beslutningsmønstre | "Hvordan gjøre det" |
+
+Minner forfaller over tid (Ebbinghaus-kurven). Ofte brukte minner styrkes. Utdaterte minner kastes automatisk. Motsetninger oppdages og løses.
+
+### Hva som fanges opp
+
+| Hook | Fanger |
+|------|----------|
+| `SessionStart` | Prosjektsti, sesjons-ID |
+| `UserPromptSubmit` | Brukerprompter (personvernfiltrert) |
+| `PreToolUse` | Filtilgangsmønstre + utvidet kontekst |
+| `PostToolUse` | Verktøynavn, inndata, utdata |
+| `PostToolUseFailure` | Feilkontekst |
+| `PreCompact` | Injiserer hukommelse på nytt før komprimering |
+| `SubagentStart/Stop` | Livssyklus for underagenter |
+| `Stop` | Oppsummering ved sesjonsslutt |
+| `SessionEnd` | Markør for fullført sesjon |
+
+### Viktige egenskaper
+
+| Egenskap | Beskrivelse |
+|---|---|
+| **Automatisk fangst** | Hver verktøybruk registreres via hooks, uten manuell innsats |
+| **Semantisk søk** | BM25 + vektor + kunnskapsgraf med RRF-fusjon |
+| **Hukommelsesevolusjon** | Versjonering, erstatning, relasjonsgrafer |
+| **Hygiene ved gjenkalling** | Erstattede minneversjoner forlater søkeindeksene; versjonskjeden i KV beholder full historikk |
+| **Hint om nær-duplikater** | Lagringer rapporterer et rådgivende `similarTo`-treff når nytt innhold ligner mye på et eksisterende minne |
+| **Avgrensning per agent** | `agentId` flyter gjennom lagring og gjenkalling over REST, MCP, og søkeindeksen, i delt eller isolert modus |
+| **Opprinnelse ved skrivetidspunkt** | Hver observasjon og hvert minne har en uforanderlig opprinnelseskanal (user, agent, tool, import, eller shared) stemplet ved fangst, lagring, og import |
+| **Automatisk glemming** | TTL-utløp, oppdagelse av motsetninger, beskjæring etter viktighet |
+| **Personvern først** | API-nøkler, hemmeligheter, ``-tagger fjernes før lagring |
+| **Selvhelende** | Strømbryterkrets (circuit breaker), fallback-kjede for leverandører, helseovervåking |
+| **Claude-bro** | Toveis synkronisering med MEMORY.md |
+| **Kunnskapsgraf** | Entitetsuttrekk + BFS-traversering |
+| **Teamhukommelse** | Navneromdelt delt + privat mellom teammedlemmer |
+| **Siteringsopprinnelse** | Spor ethvert minne tilbake til kildeobservasjonene |
+| **Git-snapshots** | Versjoner, tilbakerulling, og diff av minnetilstand |
+
+---
+
+
+
+Trippel-strøm-gjenfinning som kombinerer tre signaler:
+
+| Strøm | Hva den gjør | Når |
+|---|---|---|
+| **BM25** | Stemmet nøkkelordmatching med synonymutvidelse | Alltid på |
+| **Vektor** | Kosinus-likhet over tette embeddings | Embedding-leverandør konfigurert |
+| **Graf** | Kunnskapsgraf-traversering via entitetsmatching | Entiteter oppdaget i søket |
+
+Fusjonert med Reciprocal Rank Fusion (RRF, k=60) og sesjonsdiversifisert (maks 3 resultater per sesjon).
+
+Når en vektorindeks er fylt, bruker `mem::search` (bak `memory_recall`) den hybride BM25 + vektor-rangereren. Uten embeddings bruker den BM25. `smart-search` kan i tillegg slå sammen strukturelle grafmatcher når grafdata finnes, også i nøkkelfri modus. Gjenkalling av læringspunkter kjører på en dedikert BM25-indeks i minnet i stedet for å skanne hele korpuset per søk. Erstattede minneversjoner er utelatt fra hver gjenkallingsvei; versjonskjeden beholder historikken deres.
+
+Vektorer overlever en krasj eller tvungen avslutning. Vektorindeksen lagres i bøtter minst hvert `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutter). Hver vektor som legges til eller fjernes i mellomtiden skrives også umiddelbart til en liten ventende logg i state-lageret, og neste oppstart spiller den av igjen uten å kalle embedding-leverandøren. Hver vellykkede lagring tømmer loggen. Dokumenter som fortsatt ikke har en vektor etter avspillingen, re-embeddes i bakgrunnen i batcher av `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) til ingen er igjen, og en etterfylling som stoppes fortsetter ved neste oppstart. `/agentmemory/status` og viewer viser størrelsen på den ventende loggen og etterfyllingsstatusen. Nøkkelfrie installasjoner skriver ingenting.
+
+BM25 tokeniserer gresk, kyrillisk, hebraisk, arabisk, og aksentuert latin ut av boksen. For kinesiske/japanske/koreanske minner, installer de valgfrie segmenterne (`npm install @node-rs/jieba tiny-segmenter`) for å dele opp CJK-sekvenser i ord-nivå-tokens; uten dem faller agentmemory mykt tilbake til hele-sekvens-tokenisering og skriver et engangs-hint til stderr.
+
+### Embedding-leverandører
+
+Nøkkelfrie installasjoner deaktiverer vektor-embeddings: `mem::search` bruker BM25, mens `smart-search` også kan bruke eksisterende strukturelle grafdata. For å velge gratis semantiske embeddings på enheten, legg dette til i `~/.agentmemory/.env` og start agentmemory på nytt:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Den vanlige npm-installasjonen inkluderer den valgfrie `@huggingface/transformers`-kjøretiden. Den første embedding-forespørselen laster ned `Xenova/all-MiniLM-L6-v2`, så den trenger nettverkstilgang og kan ta lengre tid; senere inferens kjører på enheten. Eksterne leverandører oppdages automatisk fra sine nøkler med mindre `EMBEDDING_PROVIDER` overstyrer dem.
+
+| Leverandør | Modell | Kostnad | Merknader |
+|---|---|---|---|
+| **Lokal (anbefalt opt-in)** | `all-MiniLM-L6-v2` | Gratis | På enheten etter den første modellnedlastingen, +8 prosentpoeng gjenkalling over kun-BM25 |
+| Gemini | `gemini-embedding-001` | Gratis nivå | 100+ språk, 768/1536/3072 dimensjoner (MRL), 2048-tokens inndata. Erstatter `text-embedding-004` ([avviklet, stengt 14. januar 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Høyest kvalitet |
+| Voyage AI | `voyage-code-3` | Betalt | Optimalisert for kode |
+| Cohere | `embed-english-v3.0` | Gratis prøveperiode | Generell bruk |
+| OpenRouter | Hvilken som helst modell | Varierer | Flermodell-proxy |
+
+---
+
+
+
+54 MCP-verktøy, 6 ressurser, 3 prompter, og 17 skills.
+
+> **MCP-shim vs full server:** den publiserte `@agentmemory/mcp`-pakken er en tynn shim. Den eksponerer hele 54-verktøys-overflaten **kun når den kan nå en kjørende agentmemory-server** via `AGENTMEMORY_URL` (proxy-modus). Uten en nåbar server faller shimmen tilbake til et lokalt sett på 7 verktøy (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Miljøvariabelen `AGENTMEMORY_TOOLS=core|all` er et flagg på *serversiden*; å sette den i shimmens `env`-blokk har ingen effekt. Hvis du bare ser 7 verktøy i Cursor / OpenCode / Gemini CLI, start `npx -y @agentmemory/agentmemory@latest` (eller Docker-stacken) og sett `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 verktøy
+
+Tre verktøyoverflater, fra minst til størst: `AGENTMEMORY_TOOLS=core` begrenser synligheten til 8 essensielle (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); grunnsettet nedenfor er registerets 14 grunnleggende verktøy; standarden (`AGENTMEMORY_TOOLS=all`) eksponerer alle 54.
+
+
+Grunnverktøy (14)
+
+| Verktøy | Beskrivelse |
+|------|-------------|
+| `memory_recall` | Søk i tidligere observasjoner |
+| `memory_compress_file` | Komprimer markdown-filer og bevar strukturen |
+| `memory_save` | Lagre en innsikt, beslutning, eller et mønster |
+| `memory_file_history` | Tidligere observasjoner om spesifikke filer |
+| `memory_patterns` | Oppdag gjentakende mønstre |
+| `memory_sessions` | List opp nylige sesjoner |
+| `memory_smart_search` | Hybrid semantisk + nøkkelordsøk |
+| `memory_vision_search` | Søk i bildeobservasjoner |
+| `memory_timeline` | Kronologiske observasjoner |
+| `memory_profile` | Prosjektprofil (konsepter, filer, mønstre) |
+| `memory_export` | Eksporter all minnedata |
+| `memory_relations` | Spør relasjonsgrafen |
+| `memory_commit_lookup` | Sesjoner bak en git-commit |
+| `memory_commits` | Commits registrert for en sesjon |
+
+
+
+
+Utvidede verktøy (54 totalt, standardoverflaten)
+
+| Verktøy | Beskrivelse |
+|------|-------------|
+| `memory_patterns` | Oppdag gjentakende mønstre |
+| `memory_timeline` | Kronologiske observasjoner |
+| `memory_relations` | Spør relasjonsgrafen |
+| `memory_graph_query` | Kunnskapsgraf-traversering |
+| `memory_consolidate` | Kjør 4-nivås konsolidering |
+| `memory_claude_bridge_sync` | Synkroniser med MEMORY.md |
+| `memory_team_share` | Del med teammedlemmer |
+| `memory_team_feed` | Nylig delte elementer |
+| `memory_audit` | Revisjonsspor for operasjoner |
+| `memory_governance_delete` | Slett med revisjonsspor |
+| `memory_snapshot_create` | Git-versjonert snapshot |
+| `memory_action_create` | Opprett arbeidselementer med avhengigheter |
+| `memory_action_update` | Oppdater handlingsstatus |
+| `memory_frontier` | Ublokkerte handlinger rangert etter prioritet |
+| `memory_next` | Den enkelt viktigste neste handlingen |
+| `memory_lease` | Eksklusive handlingsleaser (flere agenter) |
+| `memory_routine_run` | Instansier arbeidsflyt-rutiner |
+| `memory_signal_send` | Meldinger mellom agenter |
+| `memory_signal_read` | Les meldinger med kvitteringer |
+| `memory_checkpoint` | Eksterne tilstandsporter |
+| `memory_mesh_sync` | P2P-synkronisering mellom instanser |
+| `memory_sentinel_create` | Hendelsesdrevne overvåkere |
+| `memory_sentinel_trigger` | Utløs sentinels eksternt |
+| `memory_sketch_create` | Forbigående handlingsgrafer |
+| `memory_sketch_promote` | Forfrem til permanent |
+| `memory_crystallize` | Komprimer handlingskjeder |
+| `memory_diagnose` | Helsekontroller |
+| `memory_heal` | Fiks fastlåst tilstand automatisk |
+| `memory_facet_tag` | Dimensjon:verdi-tagger |
+| `memory_facet_query` | Spør etter fasett-tagger |
+| `memory_verify` | Spor opprinnelse |
+
+
+
+### 6 ressurser · 3 prompter · 17 skills
+
+| Type | Navn | Beskrivelse |
+|------|------|-------------|
+| Ressurs | `agentmemory://status` | Helse, sesjonsantall, minneantall |
+| Ressurs | `agentmemory://project/{name}/profile` | Prosjektspesifikk intelligens |
+| Ressurs | `agentmemory://project/{name}/recent` | Nylige observasjoner for et prosjekt |
+| Ressurs | `agentmemory://memories/latest` | De siste 10 aktive minnene |
+| Ressurs | `agentmemory://graph/stats` | Kunnskapsgraf-statistikk |
+| Ressurs | `agentmemory://team/{id}/profile` | Delt teamprofil |
+| Prompt | `recall_context` | Søk + returner kontekstmeldinger |
+| Prompt | `session_handoff` | Overleveringsdata mellom agenter |
+| Prompt | `detect_patterns` | Analyser gjentakende mønstre |
+| Skill | `/recall` | Søk i hukommelsen |
+| Skill | `/remember` | Lagre til langtidshukommelse |
+| Skill | `/session-history` | Nylige sesjonsoppsummeringer |
+| Skill | `/forget` | Slett observasjoner/sesjoner |
+
+Tabellen viser de fire kjerne-skillene. Hele settet er 9 skills som kan kalles, pluss 8 referanseskills; se avsnittet om native skills over.
+
+### Frittstående MCP
+
+Kjør uten hele serveren, for en hvilken som helst MCP-klient. Begge disse fungerer:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Eller legg til i agentens MCP-konfigurasjon:
+
+De fleste agenter (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Slå sammen `agentmemory`-oppføringen inn i vertens eksisterende `mcpServers`-objekt i stedet for å erstatte filen. For sandkasse-klienter som ikke kan nå vertens `localhost`, legg til `"AGENTMEMORY_FORCE_PROXY": "1"` i `env`-blokken og sett `AGENTMEMORY_URL` til en rute sandkassen kan nå.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Kopier plugin-filen fra repoet:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Starter automatisk på port `3113`. Viewer laster ett snapshot når den kobler til (`GET /agentmemory/viewer/snapshot`) og bruker deretter live strømhendelser: nye minner, læringspunkter, observasjoner, revisjonsoppføringer, grafendringer, og helseoppdateringer vises uten polling eller sideoppdateringer. De eneste andre forespørslene er handlingene du klikker på, "load more"-sider, og søk. Når strømmen faller ut, viser viewer hvor gamle tallene er, kobler til igjen med backoff, og synkroniserer på nytt fra ett snapshot.
+
+- **12 faner i fire grupper** med live antall, dype lenker (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), tastatursnarveier, og en mobilmeny.
+- **Memories:** server-side søk, filtre etter prosjekt, agent, og type, et detaljpanel med versjonskjeden og en orddiff, opprinnelseslenker, kopieringsknapper for id-en, MCP-kallet, og en curl-kommando, rediger (en ny versjon), glem med bekreftelse, bulk-glemming, og JSON-eksport.
+- **Sessions:** en innebygd observasjonstidslinje med lesbar verktøyinndata og -utdata, filtre og paginering, og minnene og læringspunktene hver sesjon produserte.
+- **Graph:** søk, nodedetaljer med relasjoner og kilder, en legende som ikke er avhengig av farge alene, og zoomkontroller.
+- **Health:** liveversjonen av `GET /agentmemory/status`. Hvert problem kommer med sin fiks, pluss state-backend, indekslagringsstatus, fremdrift for komprimering av grafopprinnelse, og en konsolideringsforklaring med de reelle tersklene.
+- **Audit, Activity, Profile, Replay, Lessons, Actions og Crystals**-sider, hver med en tom tilstand som sier hva avsnittet er, hvorfor det er tomt, og kommandoen som fyller det, og et `?`-ordlistetips på hvert begrep og tall.
+
+```bash
+open http://localhost:3113
+```
+
+Viewer-serveren bindes til `127.0.0.1` som standard og legger på serverhemmeligheten når den videresender forespørsler til REST-API-en, så den krever ikke noe oppsett. REST-serverte `/agentmemory/viewer`-endepunktet følger de normale bearer-token-reglene og omdirigerer nettlesere uten en token til viewer-porten. CSP-headere bruker en per-respons-script-nonce og deaktiverer inline-håndteringsattributter (`script-src-attr 'none'`).
+
+---
+
+
+
+Viewer på `:3113` viser hva agenten din **husket**. [iii-konsollen](https://iii.dev/docs/console) viser hva agenten din **gjorde**: hver minneoperasjon som en OpenTelemetry-trace, hver KV-oppføring redigerbar, hver funksjon kallbar, hver strøm avlyttbar. To vinduer på samme hukommelse: ett produkt-formet, ett motor-formet.
+
+Se en `memory_smart_search` utløses og se BM25-skanningen → embedding-oppslaget → RRF-fusjonen → rerankeren som en fossefall-visning. Rediger en fastlåst konsolideringstimer i KV-browseren. Spill av en `PostToolUse`-hook på nytt med en justert nyttelast. Fest WebSocket-strømmen og se observasjoner lande live.
+
+agentmemory leverer dette gratis fordi hvert funksjonskall og hver trigger utløses gjennom iii; ingenting egendefinert, ingenting å instrumentere.
+
+
+
+
+ Workers-siden: hver tilkoblede worker, inkludert agentmemory selv, med PID, funksjonsantall, runtime, og sist sett.
+
+
+**Allerede installert.** Konsollen leveres med den fastlåste `iii`-engine-en (0.22+); ingenting separat å installere. Den første oppstarten laster ned konsoll-binærfilen ved siden av engine-en.
+
+**Start sammen med agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Dette kjører den fastlåste engine-ens `iii console` mot portene agentmemory løste opp (REST, strømmer, bro) og serverer den én port over viewer, `http://localhost:3114` som standard. `--console-port N` velger en annen port; `--port` og `--instance` velger agentmemory-instansen på samme måte som de gjør for `stop`; ethvert annet flagg sendes videre, for eksempel `--enable-flow` for den eksperimentelle arkitektur-graf-siden.
+
+Det samme for hånd, nyttig når `agentmemory` ikke er på PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Hva du kan gjøre fra konsollen:**
+
+| Side | Brukes til |
+|------|-----------|
+| **Workers** | Se hver tilkoblede worker og dens live metrikker, inkludert agentmemory-workeren selv. |
+| **Functions** | Kall direkte hvilken som helst av agentmemorys funksjoner med en JSON-nyttelast; nyttig for å teste `memory.recall`, `memory.consolidate`, `graph.query` uten å koble til en klient. |
+| **Triggers** | Spill av HTTP-, cron-, event-, og state-triggere på nytt: utløs konsolideringscronen manuelt, prøv en HTTP-rute på nytt, send en tilstandsendring. |
+| **States** | KV-browser med full CRUD over sesjoner, minneplasser, livssyklustimere, og embeddings-indeksen; rediger verdier direkte. |
+| **Streams** | Live WebSocket-overvåker for minneskriving, hook-hendelser, og observasjonsoppdateringer mens de flyter gjennom iii-strømmer. |
+| **Queues** | Varige køtopics + dead-letter-administrasjon. Spill av eller forkast mislykkede embedding-/komprimeringsjobber. |
+| **Traces** | OpenTelemetry fossefall-/flamme-/tjenesteoppdelingsvisninger. Filtrer etter `trace_id` for å se nøyaktig hvilke funksjoner, DB-kall, og embedding-forespørsler et enkelt `memory.search`-kall produserte. |
+| **Logs** | Strukturerte OTEL-logger filtrert og korrelert til trace-/span-ID-er. |
+| **Config** | Kjøretidskonfigurasjon: se nøyaktig hvilke workere, leverandører, og porter engine-en din kjører med. |
+| **Flow** | (Valgfritt, `--enable-flow`) Interaktiv arkitekturgraf av hver worker, trigger, og strøm. |
+
+
+
+
+ Traces: fossefall-/flamme-/tjenesteoppdeling for hver minneoperasjon.
+
+
+**Traces er allerede på:**
+
+`iii-config.yaml` leveres med `iii-observability`-workeren aktivert (`exporter: memory`, `sampling_ratio: 0.1`, metrikker + logger). Ingen ekstra konfigurasjon nødvendig; i det øyeblikket agentmemory starter, sender hver minneoperasjon ut en strukturert logg konsollen kan lese, og én av ti av dem (`sampling_ratio: 0.1`) sender også ut en trace-span.
+
+Hvis du vil eksportere til Jaeger/Honeycomb/Grafana Tempo i stedet, endre `exporter: memory` til `exporter: otlp` og sett collector-endepunktet ifølge iiis observability-dokumentasjon.
+
+> **Viktig:** ingen autentisering er tvunget på konsollen selv; hold den bundet til `127.0.0.1` (standard) og eksponer den aldri offentlig.
+
+---
+
+
+
+agentmemory er **allerede en kjørende [iii](https://iii.dev)-instans**. Tre primitiver (worker, funksjon, trigger) utgjør kjøretiden; KV-tilstand, strømmer, og OTEL-traces kommer fra workerne iii-state, iii-stream, og iii-observability som leveres med iii. Du installerte ikke Postgres, Redis, Express, pm2, eller Prometheus, fordi iii erstatter dem.
+
+Det betyr at én kommando til utvider agentmemory med en helt ny egenskap.
+
+### Utvid agentmemory med flere workere
+
+Byggesteinene agentmemory trenger er allerede i `iii-config.yaml` og starter med den: `iii-state` (KV), `iii-queue` (varige gjentatte forsøk for event-abonnentene), `iii-pubsub`, `iii-cron`, `iii-stream`, og `iii-observability` (OTEL-traces, metrikker, og logger på hver funksjon). Alt annet fra [iii-worker-registeret](https://workers.iii.dev) kobles til samme engine: kopier `iii-config.yaml` til `~/.agentmemory/iii-config.yaml` (CLI-en foretrekker denne filen over den medfølgende, og rendrer fortsatt porter og datastier inn i den), legg til oppføringen, installer worker-kjøretiden én gang med `~/.agentmemory/bin/iii update worker`, og start agentmemory på nytt.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Hva du får i tillegg til agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-basert state-adapter når du vokser ut av KV-standardene i minnet |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Kode som kommer ut av `memory_recall` kjører inne i en engangs-VM, ikke i skallet ditt |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Sett opp ekstra MCP-servere ved siden av agentmemorys, del samme engine |
+
+På engine 0.22.x, behold navnene med `iii-`-prefiks for byggesteinene over; de uprefikserte oppføringene `http`, `state`, `queue`, `pubsub`, og `cron` er de frittstående registerworkerne agentmemory flytter til med 0.23-migreringen.
+
+Fullt register: [workers.iii.dev](https://workers.iii.dev). Hver worker der settes sammen gjennom de samme primitivene agentmemory bruker, og agentmemory du allerede har er en av dem.
+
+### Engine-konfigurasjon og bindeadresse
+
+`agentmemory start` leser engine-konfigurasjonen fra den første filen som finnes: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` i den nåværende katalogen, `~/.agentmemory/iii-config.yaml`, deretter den medfølgende `iii-config.yaml`. Ved hver oppstart rendrer den denne filen (datastier, porter, state-backend) inn i `~/.agentmemory/data/iii-config.runtime.yaml` og starter engine-en med den rendrede kopien, så rediger kildefilen, ikke den rendrede. `host:`-verdiene i kildefilen beholdes som skrevet.
+
+Den medfølgende `iii-config.yaml` binder `127.0.0.1` med vilje, og denne standarden gjelder også inne i en container. En CLI startet i en container lytter på containerens loopback, så publiserte porter når ingenting. For å servere en konteinerisert CLI gjennom publiserte porter, sett `AGENTMEMORY_III_CONFIG` til en konfigurasjon som binder `0.0.0.0`. Den medfølgende `iii-config.docker.yaml` er en slik: den binder `iii-http`, `iii-stream`, og engine-porten til `0.0.0.0` og lagrer tilstand under `/data`, så monter et skrivbart volum der. Hold `AGENTMEMORY_SECRET` satt, og publiser bare de portene du trenger, på `127.0.0.1` eller bak en proxy du stoler på.
+
+Dette repoets `docker-compose.yml` går ikke gjennom CLI-ens konfigurasjonssøk: det monterer `iii-config.docker.yaml` på `/app/config.yaml`, og `iii-engine`-containeren starter med `--config /app/config.yaml`. Maler for [ett-klikks-distribusjon](../deploy/) skriver sin egen `0.0.0.0`-konfigurasjon i sine entrypoints.
+
+### Lagringsbackend: filbasert (standard) vs redis
+
+`iii-state` og `iii-stream` bruker som standard iii-engines medfølgende filbaserte KV-lager: én JSON-fil per scope, holdt i engine-prosessens minne og skrevet til disk på en timer. Dette er det riktige standardvalget for en lokal installasjon med én bruker; en delt daemon med flere samtidige skrivere får ekte skriving per nøkkel fra Redis i stedet, til kostnaden av en nettverks-rundtur per operasjon (hvert `state::*`-kall serialiseres fortsatt på én Redis-tilkobling, så dette bytter filens lagerlås mot en socket, ikke mot parallellitet).
+
+Sett `AGENTMEMORY_STATE_BACKEND=redis` (pluss `AGENTMEMORY_REDIS_URL`) for å bytte begge workerne til iii-engines innebygde `redis`-adapter, som lagrer hver nøkkel som et Redis hash-felt (`HSET`) i stedet for å skrive om hele scopet ved hver skriving:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` er `file` som standard; å la den være usatt beholder dagens oppførsel uendret, og en ukjent verdi (noe annet enn `file` eller `redis`) gir en oppstartsfeil i stedet for en stille fallback. `/agentmemory/status` og viewerens Health-side (State store-raden) rapporterer hvilken backend som er aktiv og om den svarer, aldri URL-en.
+
+**Kun ren `redis://`.** Den fastlåste engine-en (0.22.1) bygger sin Redis-klient uten TLS-støtte, så en `rediss://`-URL (de fleste administrerte Redis-tilbud, som Upstash, Redis Cloud, og ElastiCache med kryptering under overføring, er TLS-only som standard) kobler ikke til. Tilkoblingen er ukryptert, så Redis-passordet og hvert lagrede minne går over tråden i klartekst: pek på en lokal Redis eller en på et privat nettverk du stoler på. For enhver annen Redis, kjør en kryptert tunnel (stunnel, SSH, eller en VPN) på agentmemory-verten, slik at det rene `redis://`-hoppet holder seg på den verten og tunnelens oppstrøms-tilkobling er kryptert og autentisert. Hvis et Redis-passord inneholder et enkelt sitattegn, prosent-koder det (`%27`); engine-en utvider URL-en til sin YAML-konfigurasjon før parsing.
+
+**Én Redis-server per `--instance`.** Engine-ens Redis-nøkkelprefikser (`state:`, `stream::`) er fastsatte, så to agentmemory-instanser (`--instance 1`, `--instance 2`, ...) pekt mot samme database overskriver hverandres data. En egen databaseindeks (`redis://localhost:6379/1`) holder lagret data separat, men engine-en relayer live viewer-hendelser over én Redis pub/sub-kanal (`stream::events`), og Redis pub/sub ignorerer databaseindeksen, så hver instans' viewer vil fortsatt vise den andres live-hendelser. Gi hver instans sin egen Redis-server (eller port) når du kjører mer enn én.
+
+**Hva som forblir det samme, og hva som er forskjellig.** Hver agentmemory-egenskap fungerer på Redis: sesjoner, observasjoner, minner (remember, erstatt, evolve, forget), søk og indeksbøttene, læringspunkter, grafen, revisjonsloggen og dens månedlige scopes, eksport og import, governance-sletting, konsolideringsstatus, viewer-snapshotet og dens live-strøm, og helseovervåkeren. Engine-en lagrer hvert scope som én Redis-hash (`HSET`/`HGET`/`HGETALL`) og utløser de samme state-triggerne som filbaseret lager. Tre engine-forskjeller håndteres inne i agentmemory:
+
+- Redis returnerer en scopes oppføringer i ingen fast rekkefølge. agentmemory sorterer dem eldste først (etter opprettelsestiden i oppføringens id, deretter tidsstempelet), slik at lister, paginering, og eksportbiter kommer tilbake i samme rekkefølge som i filbaseret lager.
+- Engine-en bruker partielle oppdateringer på Redis i et Lua-skript som gjør tomme arrayer til tomme objekter. agentmemory utfører disse oppdateringene selv (les, endre, skriv under en lås per nøkkel) på Redis, slik at felt som `tags: []` forblir arrayer.
+- Den eldre revisjonsloggkontrollen leser det gamle scopet fra Redis i stedet for å se etter filbasertets fil på disk.
+
+Én forskjell krever din oppmerksomhet: **etter at Redis starter på nytt, stopper engine-en å relaye live-hendelser** til viewer til agentmemory starter på nytt. Data lagres og leses fortsatt normalt. Helseovervåkeren sender en testhendelse gjennom Redis hvert 30. sekund; når den ikke kommer tilbake, viser `/agentmemory/status` og viewerens Health-side "Live updates are not reaching the viewer" med fiksen: start agentmemory på nytt. Hvis Redis er nede, viser statusrapporten "The state store is not answering" og hvordan du sjekker det (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Å liste et veldig stort scope leser hele hashen i én `HGETALL`, samme kostnad som filbasertet som holder det i minnet.
+
+**Anbefalte Redis-innstillinger.** Standard snapshot-policy `save 3600 1 300 100 60 10000` kan tape minutter med skriving ved en krasj, verre enn filbasertets 5-sekunders flush-vindu. Sett `appendonly yes` for alt du ville savnet å tape. Sett `maxmemory-policy noeviction`; `allkeys-lru` eller lignende dropper minner stille når Redis når minnegrensen sin.
+
+En native (ikke-Docker) oppstart, og hver mal for [ett-klikks-distribusjon](../deploy/) (de overskriver den medfølgende `iii-config.yaml` og starter native), leser `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` og rendrer dem inn i den startede `iii-config`-en. URL-en selv skrives aldri til den rendrede filen, bare en `${AGENTMEMORY_REDIS_URL}`-referanse som engine-prosessen utvider fra sitt eget miljø ved oppstart. Bare dette repoets egen Docker Compose-vei (`AGENTMEMORY_USE_DOCKER=1`, eller gjenoppta en engine allerede startet på den måten) monterer `iii-config.docker.yaml` skrivebeskyttet og rendrer aldri; `agentmemory start` advarer når den oppdager den kombinasjonen. Bytt den filen manuelt, ved å følge samme `name: redis` / `config: redis_url: ...`-form vist i [iii-state](https://workers.iii.dev/workers/iii-state)- og [iii-stream](https://workers.iii.dev/workers/iii-stream)-worker-dokumentasjonen, og pek `redis_url` mot en Redis nåbar fra containeren. `docker-compose.yml` sender `AGENTMEMORY_REDIS_URL` inn i engine-containeren, så `redis_url: '${AGENTMEMORY_REDIS_URL}'` fungerer der og holder URL-en utenfor den monterte filen.
+
+Den rendrede konfigurasjonen holder URL-en utenfor `~/.agentmemory/data/iii-config.runtime.yaml`, men engine-ens egen konfigurasjonsworker lagrer fortsatt den *utvidede* verdien til `~/.agentmemory/config/iii-state.yaml` og `iii-stream.yaml` når den starter (iii-engines `${VAR}`-utvidelse skjer før denne workeren lagrer sitt seed, og den lagrer den oppløste verdien, ikke referansen). Behandle den katalogen som om den inneholder et credential: `chmod 700 ~/.agentmemory` på en delt vert, og foretrekk en Redis ACL-bruker avgrenset til hva agentmemory trenger over databasens admin-credentials.
+
+**Migrering er ikke automatisk.** Å bytte `AGENTMEMORY_STATE_BACKEND` starter fra et tomt lager på begge sider; ingenting kopierer eksisterende data fra fil til Redis eller tilbake. Eksporter fra backenden du forlater og importer inn i den du flytter til. Dette kjører identisk under bash og zsh (inkludert `bash -u`). En array som `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gjør det ikke: zsh holder headeren som ett feilformet ord der bash deler den i to, så begge forespørslene gir 401 når `AGENTMEMORY_SECRET` er satt:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` godtar også `?maxSessions=` og `?offset=` for å dele opp et stort korpus over flere kall; `strategy` ved import er `merge` (sikker standard), `replace`, eller `skip`.
+
+### Hva iii erstatter
+
+| Tradisjonell stack | agentmemory bruker |
+|---|---|
+| Express.js / Fastify | iii HTTP-triggere |
+| SQLite / Postgres + pgvector | iii KV-tilstand + vektorindeks i minnet |
+| SSE / Socket.io | iii-strømmer (WebSocket) |
+| pm2 / systemd | iii engine worker-overvåking |
+| Prometheus / Grafana | iii OTEL + helseovervåker |
+| Egendefinerte plugin-systemer | `iii worker add ` |
+
+**225 kildefiler · ~54,000 LOC · 2,600+ tester · 312 funksjoner · 66 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
+
+---
+
+
+
+### LLM-leverandører
+
+agentmemory oppdager leverandører automatisk fra miljøet ditt. En leverandør gjør LLM-baserte operasjoner tilgjengelige, men leverandørkonfigurasjon alene aktiverer ikke LLM-skrevet observasjonskomprimering. Denne stien krever både en leverandør og `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Leverandør | Konfigurasjon | Merknader |
+|----------|--------|-------|
+| **No-op (standard)** | Ingen konfigurasjon nødvendig | LLM-basert komprimering/oppsummering er deaktivert. Syntetisk komprimering og BM25-gjenkalling fungerer fortsatt. Se `AGENTMEMORY_ALLOW_AGENT_SDK` under hvis du tidligere brukte Claude-abonnement-fallbacken. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Fakturering per token |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
+| Gemini | `GEMINI_API_KEY` | Aktiverer også embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Hvilken som helst modell |
+| OpenAI API | `OPENAI_API_KEY` | Standard `gpt-5.6-luna`, overstyr med `OPENAI_MODEL` |
+| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) eller `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alt som er OpenAI-API-kompatibelt. Null kostnad, kjører på egen maskinvare. Se [Lokale modeller](#local-models-ollama--lm-studio--vllm) under. |
+| Claude-abonnement-fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Kun opt-in. Starter `@anthropic-ai/claude-agent-sdk`-sesjoner; dette brukte å forårsake ubegrenset Stop-hook-rekursjon, så det er ikke lenger standard. |
+
+### Lokale modeller (Ollama / LM Studio / vLLM)
+
+agentmemory snakker med enhver OpenAI-API-kompatibel server, så alt som eksponerer `/v1/chat/completions` fungerer uten kodeendringer. Ingen betalte nøkler, ingen sky, ingen rate-grenser; kjører helt på din egen maskinvare.
+
+**Ollama** (standardport `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (standardport `1234`):
+
+Åpne LM Studio → Local Server-fanen → Start Server. Velg en hvilken som helst chat-modell fra velgeren (Qwen 3, gpt-oss, DeepSeek R1, osv.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: samme form. Pek `OPENAI_BASE_URL` mot hvilken URL serveren din eksponerer og sett `OPENAI_MODEL` til et navn serveren din vil godta.
+
+**Modellvalg for hukommelsesarbeid**: komprimering og oppsummering er korte oppgaver (<2K tokens inn, <500 tokens ut) der en 7B instruct-modell er mer enn nok. Anbefalinger:
+
+| Modell | Størrelse | Hvorfor |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Balansert standard på en 16 GB-maskin; sterk på uttrekk og verktøy-formet tekst |
+| `qwen3:4b` | ~2.6 GB | Minste fornuftige alternativ; fint for komprimering, svakere for grafuttrekk |
+| `qwen3-coder:30b` | ~19 GB | Beste lokale valg for kode-formede sesjoner (30B MoE, 3.3B aktive) på 24-32 GB maskinvare |
+| `gpt-oss:20b` | ~14 GB | Sterk generell modell som får plass i 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Resonnerings-distill; tregere men renere uttrekk |
+
+Qwen 3-modeller tenker som standard og kan brenne hele tokenbudsjettet på resonnering før noe utdata. Sett `AGENTMEMORY_LLM_NOTHINK=1` for å legge til `/no_think` i grafuttrekk-promptene, og øk `MAX_TOKENS` (16384 fungerer) hvis uttrekkene kommer tomme tilbake.
+
+Resonneringsmodeller (`o1`-stil med ``-blokker) kan returnere tomt `content` med et `reasoning`-felt din lokale server ikke nødvendigvis eksponerer. Hvis uttrekkene kommer tomme tilbake, bytt til en ikke-resonnerende modell først. Miljøvariabelen `OPENAI_REASONING_EFFORT=none` kan også deaktivere tenking på Ollama Cloud-tenkemodeller som speiler OpenAIs resonnerings-skjema.
+
+Lokale embeddings leveres som en valgfri avhengighet, men er ikke aktivert som standard. Sett `EMBEDDING_PROVIDER=local` for å velge `Xenova/all-MiniLM-L6-v2` (384 dimensjoner). Den første embedding-forespørselen laster ned modellen; inferens kjører på enheten etterpå. Uten denne innstillingen eller en ekstern embedding-nøkkel forblir vektorer deaktivert, `mem::search` bruker BM25, og `smart-search` kan fortsatt legge til eksisterende grafmatcher.
+
+### Kostnadsbevisst modellvalg
+
+Når LLM-skrevet bakgrunnskomprimering er aktivert med både en leverandør og `AGENTMEMORY_AUTO_COMPRESS=true`, kjører den på hver observasjon, så modellvalget endrer det månedlige forbruket betydelig. Fanget arbeidsbelastningsdata: 635 forespørsler / 888K tokens / 35 timer aktiv bruk, kjørt mot tre OpenRouter-modeller ved prisene fra 2026-05-23.
+
+| Nivå | Modell | Input / 1M | Output / 1M | Kostnad for de fangede 35 timene | Merknader |
+|------|-------|------------|-------------|---------------------------|-------|
+| Anbefalt | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Nyeste DeepSeek; billigste anbefalte valg for komprimeringsarbeid. |
+| Anbefalt | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid komprimerings- og oppsummeringskvalitet til ~10x lavere kostnad enn Sonnet. |
+| Anbefalt | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Sterk koderesonnering hvis sesjonene dine er tungt kode-formede. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Samme listepris som den målte Sonnet 4.6-kjøringen; $2/$10 introduksjonspris ut 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flaggskip-nivå; dyrt for alltid-på bakgrunnsarbeid. |
+| Unngå | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flaggskip-klasse modell; overforbruk for komprimering. |
+
+Målte rader kommer fra den fangede kjøringen; (est.)-rader skalerer samme token-miks med hver modells listepris.
+
+agentmemory skriver ut en kjøretidsadvarsel når `OPENROUTER_MODEL` matcher et premium-nivå-mønster. Sett `AGENTMEMORY_SUPPRESS_COST_WARNING=1` for å dempe den når du har gjort et informert valg.
+
+Kvalitet vs kostnad for hukommelsesarbeid: komprimering er en oppsummeringsoppgave med relativt løse kvalitetskrav (agenten leser oppsummeringen på nytt, ikke brukeren). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ligger innenfor avrundingsfeilen av Sonnet på denne oppgaven, samtidig som de kostet 10-70x mindre. Spar premium-modellene til søk du leser direkte.
+
+Kilder: [OpenRouter-prising for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-prisnotater](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Hukommelse for flere agenter (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+I oppsett med flere agenter der flere roller deler én agentmemory-server (arkitekt / utvikler / reviewer / forsker / support-agent), tagger `AGENT_ID` hver skriving med rollen som utførte den. `AGENTMEMORY_AGENT_SCOPE` styrer om gjenkalling filtrerer etter denne taggen.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+To moduser:
+
+| Modus | Tagger skriving | Filtrerer gjenkalling | Når brukes den |
+|------|------------|---------------|-------------|
+| `shared` (standard) | ja | nei | Kryss-agent-kontekst med revisjonsspor. Arkitekten kan se hva utvikleren noterte, men hver rad registrerer hvem som sa det. |
+| `isolated` | ja | ja | Strikt separasjon. Arkitekten ser aldri utviklerens observasjoner/minner/sesjoner. |
+
+Hva som tagges når `AGENT_ID` er satt: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rollen flyter fra `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Hva som filtreres i isolert modus: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Hvert endepunkt godtar `?agentId=` for å overstyre per forespørsel, og `?agentId=*` for å gå ut av miljø-scopet helt. `/memories` godtar også `?includeOrphans=true` for å vise minner fra før AGENT_ID der `agentId` er udefinert.
+
+Overstyring per kall på SDK-/REST-laget: hvert muterende endepunkt (`/session/start`, `/remember`) godtar et `agentId`-felt i forespørselskroppen som vinner over miljøvariabelen. Nyttig for kjøretider som ruter mange roller gjennom én serverprosess. MCP-verktøyet `memory_save` eksponerer samme `agentId`-felt, den frittstående stdio-serveren videresender både `agentId` og `project`, og lagrede minner bærer `agentId` inn i søkeindeksen, slik at agent-avgrenset søk dekker minner så vel som observasjoner.
+
+Når `AGENT_ID` ikke er satt, forblir hukommelsen uten avgrensning (eldre oppførsel, ingen tagger, ingen filtre).
+
+### Porter
+
+agentmemory + iii-engine binder fire porter som standard. Hvis en omstart mislykkes med `port in use`, viser denne tabellen hvilken prosess du skal se etter.
+
+| Port | Prosess | Formål | Miljøoverstyring |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Intern strømme-worker (brukt av agentmemory + viewer) | `III_STREAM_PORT` (foretrukket) eller eldre `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer i realtid (`http://localhost:3113`) | `III_VIEWER_PORT` eller `AGENTMEMORY_VIEWER_URL` for den rapporterte URL-en |
+| `49134` | iii-engine | WebSocket; workere registrerer seg her, OTel-telemetri flyter over den | `III_ENGINE_PORT` eller `III_ENGINE_URL` |
+
+`--port ` endrer REST-ankeret og avleder strømmer `N+1`, viewer `N+2`, og engine-WebSocket `N+46023` bare der den tilsvarende uttrykkelige porten eller URL-en over ikke er satt. Det skaper ikke et isolert livssyklus-navnerom. Bruk `--instance 1` for en andre daemon; den bruker anker 3211, standard `3211/3212/3213/49234`, og får en separat `instance-1` data- og livssykluskatalog. Instanser 1 til 50 følger samme mønster.
+
+Den fastlåste engine-en starter med `--no-update-check` (ingen oppdaterings- eller sikkerhetsvarsel-oppslag mot GitHub ved oppstart) og med iiis anonyme brukstelemetri av: agentmemory setter `III_TELEMETRY_ENABLED=false` for engine-en den starter med mindre du eksporterer variabelen selv, og den medfølgende compose-filen gjør det samme.
+
+Opprydding av gjenværende prosesser når porter forblir bundet etter en krasjet kjøring:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` henter inn både worker- og engine-pidfilen rent ved en graceful native avslutning. I Docker-modus flusher den den native workeren, stopper den eksakte validerte engine-containeren, og bevarer både containeren og dens `/data`-montering for en tapsfri omstart; neste oppstart validerer og gjenopptar den samme containeren. Docker-basert avinstallasjon krever `agentmemory remove --keep-data`: den fjerner delte agentmemory-administrerte filer samtidig som den bevarer den validerte containeren, dens datamontering, og livssyklus-posten som trengs for å gjenopprette dem. Destruktiv Docker-datasletting er med vilje overlatt til operatøren etter en sikkerhetskopi. CLI-en avviser også å adoptere eller signalere Docker- eller VM-portholdere (Docker-backend, vpnkit, colima) som den native engine-en med mindre `--force` sendes. Den manuelle opprydningen over er bare for post-krasj-tilfellet der ingen pidfil er igjen.
+
+### Konfigurasjonsfil
+
+Legg agentmemorys kjøretidskonfigurasjon i `~/.agentmemory/.env` i stedet for å eksportere variabler i hvert skall. Hvis viewer viser et oppsettshint som `export ANTHROPIC_API_KEY=...`, kopier det inn i denne filen som `ANTHROPIC_API_KEY=...` uten `export`-prefikset, og start deretter agentmemory på nytt.
+
+Miljøvariabler i prosessen fungerer fortsatt og går foran verdier i filen.
+
+På Windows ligger samme fil på `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+For å teste med et Claude Code Pro/Max-abonnement i stedet for en API-nøkkel, velg det inn uttrykkelig:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM-skrevet observasjonskomprimering krever begge linjene: tilgang til en LLM-leverandør (inkludert denne uttrykkelige abonnement-fallbacken) og `AGENTMEMORY_AUTO_COMPRESS=true`. En leverandør alene lar standard syntetisk komprimeringsvei stå på plass.
+
+Konsolidering (grafnoder, læringspunkter, krystaller) er på som standard når en LLM-leverandør er konfigurert. Velg deg uttrykkelig ut med `CONSOLIDATION_ENABLED=false` hvis du vil ha LLM-fri drift. Grafuttrekk er et eget flagg:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Miljøvariabler
+
+Opprett `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endepunkter på port `3111`. REST-API-en bindes til `127.0.0.1` som standard. Beskyttede endepunkter krever `Authorization: Bearer `, og mesh-synkroniseringsendepunkter krever en uttrykkelig satt `AGENTMEMORY_SECRET` på begge sider.
+
+**Autentisering er på som standard.** Når `AGENTMEMORY_SECRET` ikke er satt (i skallet eller i `~/.agentmemory/.env`), genererer serveren en tilfeldig hemmelighet ved første oppstart og lagrer den i `~/.agentmemory/secret` med modus `0600`. Hver medfølgende klient leser den fra der når den snakker med en lokal server: CLI-en, viewer, hookene under `plugin/scripts`, MCP-serveren og `@agentmemory/mcp`-shimmen, konfigurasjonene skrevet av `agentmemory connect`, og de medfølgende OpenCode-, Pi-, OpenClaw-, Hermes-, og filsystem-overvåker-integrasjonene. Den lagrede hemmeligheten sendes bare til loopback-URL-er (`localhost`, `127.0.0.0/8`, `::1`). En uttrykkelig `AGENTMEMORY_SECRET` vinner alltid, og eksterne klienter trenger den fortsatt satt. Docker og `deploy/`-entrypointene genererer og eksporterer allerede sin egen hemmelighet. For å kalle API-en manuelt:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Forespørselsregler for skriving.** `POST`-, `PUT`-, `PATCH`-, og `DELETE`-forespørsler til REST-API-en og viewer må sende `Content-Type: application/json` (en `charset`-parameter er greit) når de har en kropp, og en `Origin`-header, når den er til stede, må være en loopback-opprinnelse for den konfigurerte REST- eller viewer-porten eller være listet i `VIEWER_ALLOWED_ORIGINS` (kommaseparert, f.eks. `https://memory.example.com`). Klienter som sender ingen `Origin`-header (CLI, hooks, MCP, curl, server-til-server) er ikke påvirket. Viewer godtar også sin egen opprinnelse.
+
+**Filstier.** Endepunkter som leser eller skriver filer (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) godtar bare stier under `~/.agentmemory`, instansens datakatalog, eller en katalog listet i `AGENTMEMORY_IMPORT_ROOT` (separer flere med `:`, eller `;` på Windows). `/replay/import-jsonl` godtar også sin standard `~/.claude/projects`. `/obsidian/export` holder seg innenfor `AGENTMEMORY_EXPORT_ROOT` og `/migrate` innenfor `~/.agentmemory`. Symlinker løses opp før hver kontroll.
+
+**Fjerning av hemmeligheter.** API-nøkler, bearer-tokens, PEM-private-key-blokker, og credentials innebygd i URL-er (`scheme://user:password@host`) sladdes før tekst lagres, på hver skrivevei: observasjoner, remember, evolve, slots, læringspunkter, handlinger, sketches, signaler, checkpoints, imports, jsonl-avspilling, mesh-synkronisering, team-delinger, komprimerings- og oppsummeringsutdata, krystaller, og grafnoder.
+
+
+Viktige endepunkter
+
+| Metode | Sti | Beskrivelse |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Helsekontroll (alltid offentlig) |
+| `GET` | `/agentmemory/status` | Hva er galt og hvordan fikse det (HTML for nettlesere, JSON ellers) |
+| `GET` | `/agentmemory/viewer/snapshot` | Alt viewer viser, i én respons |
+| `POST` | `/agentmemory/session/start` | Start sesjon + hent kontekst |
+| `POST` | `/agentmemory/session/end` | Avslutt sesjon |
+| `POST` | `/agentmemory/observe` | Fang observasjon (se fangstlevering under) |
+| `GET` | `/agentmemory/capture` | Fangst-innboks, dead letters, og offline-kø |
+| `POST` | `/agentmemory/capture/retry` | Prøv dead-letter-fangster på nytt |
+| `POST` | `/agentmemory/capture/drain` | Send den lokale offline-køen nå |
+| `POST` | `/agentmemory/smart-search` | Hybridsøk |
+| `POST` | `/agentmemory/context` | Generer kontekst |
+| `POST` | `/agentmemory/remember` | Lagre til langtidshukommelse |
+| `POST` | `/agentmemory/forget` | Slett observasjoner |
+| `POST` | `/agentmemory/enrich` | Filkontekst + minner + feil |
+| `GET` | `/agentmemory/profile` | Prosjektprofil |
+| `GET` | `/agentmemory/export` | Eksporter all data |
+| `POST` | `/agentmemory/import` | Importer fra JSON |
+| `POST` | `/agentmemory/graph/query` | Kunnskapsgraf-spørring |
+| `POST` | `/agentmemory/graph/compact` | Beskjær overdimensjonert grafopprinnelse |
+| `POST` | `/agentmemory/team/share` | Del med team |
+| `GET` | `/agentmemory/audit` | Revisjonsspor |
+
+Full endepunktliste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Fangstlevering.** Hooks sender hver observasjon én gang til `POST /agentmemory/observe` med en `eventId`. Dette er vertens egen id for kallet når nyttelasten har en (for eksempel Claude Codes `tool_use_id`), ellers en hash av sesjonen, hook-typen, verktøynavnet, inndata, utdata, og vert-tidsstempelet. Serveren skriver hendelsen til en fangst-innboks i state-lageret, lagrer observasjonen, og fjerner deretter innboks-oppføringen. Statuskoden sier hva som skjedde:
+
+| Status | `status`-felt | Betydning |
+|---|---|---|
+| `201` | `accepted` | Lagret. `observationId` er den nye observasjonen. |
+| `202` | `accepted` (`state: "retrying"`) | Akseptert, men lagring mislyktes. Serveren prøver på nytt, også etter en omstart. |
+| `200` | `duplicate` | Denne `eventId`-en var allerede akseptert. `observationId` er den eksisterende observasjonen; ingenting nytt lagres. |
+| `400` / `422` | `rejected` | Ugyldig nyttelast, eller lagring mislyktes permanent (hendelsen beholdes som et dead letter). |
+| `503` | `rejected` (`retryable: true`) | Innboksen er full (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks mellomlagrer hendelsen og sender den senere. |
+
+Mislykkede hendelser prøves på nytt hvert `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 sek) med doblende backoff, opp til `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Hendelser som fortsatt mislykkes forblir i innboksen som dead letters, listes på `/agentmemory/status` og viewerens Health-side, og kan prøves på nytt med `POST /agentmemory/capture/retry` (`{"eventId": "..."}` eller `{"all": true}`). Aksepterte hendelses-ID-er huskes i `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 timer, høyst `AGENTMEMORY_CAPTURE_EVENTS_MAX` ID-er), slik at en hook som spilles av igjen etter en timeout eller en omstart lagres én gang, mens to separate verktøykall med sine egne vert-ID-er lagres to ganger selv når innholdet deres er identisk. Når en observasjon slettes (forget, sesjonssletting, eviction, auto-forget, eller en import som erstatter lageret), markeres hendelsen som slettet før observasjonen fjernes, slik at en avspilling av den hendelsen innenfor samme vindu besvares som et duplikat og lagrer ingenting. State-lageret skriver til disk hvert 2. sekund, så et besvart event kan fortsatt bare være i minnet et øyeblikk. For å dekke dette bærer også hvert `2xx`-svar serverens `bootId` (ny ved hver oppstart), `acceptedAt`, og `durableAfterMs` (lagringsintervallet pluss 1.5 sek på filbasertet, 1.5 sek på redis, der persistens er operatørens innstilling). Hooks holder på hendelsen i den lokale mellomlagringen til dette vinduet er passert og sletter den ved et senere kall uten en ny forespørsel. Hvis `bootId` har endret seg da, har serveren startet på nytt, så hooken sender hendelsen på nytt med samme `eventId`; en hendelse som nådde disken lagres ikke to ganger. Serveren sender også slike hendelser selv ved oppstart og ved hvert retry-intervall, slik at en omstart ikke taper noe selv når ingen hook kjører etterpå. Eldre hooks ignorerer de ekstra feltene, og nye hooks mot en eldre server forkaster hendelsen ved `2xx` som før.
+
+Når serveren er nede, ikke svarer i tide, eller returnerer en 5xx, legger hooken observasjonen til en lokal mellomlagringsfil, `/capture-spool/-.jsonl` (overstyr mappen med `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Filen er privat for brukeren din (modus 600), hemmeligheter sladdes på samme måte som serveren sladder dem, den har plass til høyst `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) og dropper oppføringer eldre enn `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Når den er full, droppes nye oppføringer og telles, og `/agentmemory/status` rapporterer det. Hooken avsluttes fortsatt med 0 innen tidsgrensen og legger ikke til noen forespørsel når serveren er sunn. Mellomlagringen sendes ved neste oppstart og av den første hooken som når serveren igjen, i en bakgrunnsprosess slik at agenten ikke venter. Hendelses-ID-er gjør dette trygt: en observasjon som faktisk ankom før en timeout lagres ikke to ganger. `npx @agentmemory/agentmemory capture` viser mellomlagringen og serverinnboksen, `--drain` sender mellomlagringen nå, og `GET /agentmemory/capture` returnerer samme som JSON. Sett `AGENTMEMORY_CAPTURE_SPOOL=false` for å skru av mellomlagringen.
+
+**Komprimering av grafopprinnelse.** Hver kunnskapsgraf-node og -kant holder ID-ene til de nyeste 32 observasjonene den kom fra. Lagre skrevet før dette taket kan holde tusenvis av ID-er per "varm" node, noe som gjør grafsøk og viewer treg eller feller workeren. agentmemory fikser dette selv: ved den første oppstarten etter en oppgradering beskjærer den hver node, kant, erstattet kant (den temporale grafhistorikken), og den bufrede snapshoten til taket i bakgrunnen, i små skiver med en pause mellom dem, slik at søk, fangst, og viewer fortsetter å fungere. Den lagrer fremdriften sin, fortsetter etter en omstart, og kjører aldri igjen når den er ferdig. `/agentmemory/status` og viewerens Health-side viser den som ventende, kjørende (med nåværende scope og posisjon), ferdig, eller mislykket. Sett `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` for å skru den av.
+
+For å kjøre den manuelt, kall `POST /agentmemory/graph/compact`. Den går gjennom navne- og kant-nøkkel-indeksene i stedet for å liste hver node og kant, og er trygg å kjøre på nytt. Når den beskjærer ID-er skriver den en `graph_compact`-revisjonsoppføring.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+På et stort lager, eller når kallet returnerer 504, kjør det i skiver. Send `scope` (`nodes`, `edges`, eller `history`), `offset`, og `limit`, og kall deretter på nytt med den returnerte `nextOffset` til den er `null`. Gjør dette for `nodes`, `edges`, og `history`, og avslutt med ett `{"scope":"snapshot"}`-kall, fordi en skivet kjøring ikke berører den bufrede snapshoten.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Forutsetninger:** Node.js >= 20 med npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 eller Docker. Den automatiske engine-installasjonen på macOS/Linux krever også `curl`, en POSIX-`sh`, og `tar`; native Windows bruker den manuelt fastlåste `iii.exe`, WSL2, eller Docker Desktop.
+
+
+
+ Je coding agent onthoudt alles. Geen uitleg meer nodig.
+ Gebouwd op iii engine
+
+ Persistent geheugen voor Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, en elke MCP-client.
+
+ De gist breidt Karpathy's LLM Wiki-patroon uit met confidence scoring, lifecycle, knowledge graphs en hybride zoeken: agentmemory is de implementatie.
+
+
+---
+
+## Install
+
+Vereisten:
+
+- Node.js 20 of nieuwer met npm en npx (`node -v`, `npm -v` en `npx -v`).
+- Automatische iii-engine-installatie op macOS/Linux heeft ook `curl`, een POSIX `sh` en `tar` nodig. Minimale images zoals `node:20-slim` bevatten deze mogelijk niet.
+- Native Windows vereist dat de vastgezette iii-engine v0.22.1 `iii.exe` handmatig wordt geïnstalleerd. WSL2 of Docker Desktop zijn de andere ondersteunde paden.
+
+Canonieke opdracht voor een nieuwe installatie:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+De eerste run is een interactieve setup: je kiest de agents die je wilt koppelen (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), kiest een LLM-provider of blijft keyless, en de setup zet de config klaar, start de memory server en de bijbehorende vastgezette iii engine, en biedt aan om globaal te installeren zodat het kale `agentmemory`-commando daarna overal werkt. `-y` accepteert de package-prompt van npx en `@latest` voorkomt een verouderde gecachte release. Een provider maakt LLM-functies beschikbaar, maar LLM-geschreven compressie van observaties start alleen wanneer ook `AGENTMEMORY_AUTO_COMPRESS=true` is ingesteld.
+
+Keyless-modus schakelt vector-embeddings uit. `memory_recall` (het `mem::search`-pad) gebruikt BM25, terwijl `memory_smart_search` ook structurele graph-matches kan combineren wanneer er al graph-data bestaat. Voor gratis semantisch ophalen op het eigen apparaat stel je `EMBEDDING_PROVIDER=local` in in `~/.agentmemory/.env` en herstart je. De eerste embedding-aanvraag downloadt `Xenova/all-MiniLM-L6-v2`; inference draait daarna lokaal, na die eerste modeldownload.
+
+De lokale runtime gebruikt vier poorten: `3111` voor REST/MCP HTTP, `3112` voor iii-streams, `3113` voor de viewer en `49134` voor de iii worker WebSocket. Persistente iii-state leeft in `~/Library/Application Support/agentmemory` op macOS, `$XDG_DATA_HOME/agentmemory` of `~/.local/share/agentmemory` op Linux, en `%APPDATA%\agentmemory` op Windows. Gebruik `--data-dir ` of `AGENTMEMORY_DATA_DIR` om dit te overschrijven, en gebruik bij elke herstart opnieuw dezelfde waarde. Voor achterwaartse compatibiliteit krijgt een bestaande `./data/state_store.db` of `./data/iii-config.yaml` voorrang boven de platformstandaard voor instantie 0; een expliciete flag of environment-override wint nog steeds.
+
+Bewijs vervolgens dat recall werkt en geef je agent zijn skills:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+De keyword-zoekopdrachten zouden in de standaard keyless-modus via BM25 moeten raken. De `database performance optimization`-query van de demo is doelbewust semantisch en kan nul resultaten opleveren totdat er een embedding-provider is geconfigureerd.
+
+Wil je liever dat een coding agent dit allemaal voor je doet? Geef hem één instructie:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Koppel op elk moment meer agents met `agentmemory connect ` — er staan 20 adapters vermeld bij [Werkt met elke agent](#works-with-every-agent). Volledige commando-referentie bij [Snelstart](#quick-start).
+
+
+Windows
+
+De snelste weg is WSL2. Voor een native Windows-engine-setup moet de vastgezette v0.22.1 ZIP worden gedownload en `iii.exe` handmatig worden uitgepakt; de CLI pakt dit niet automatisch uit. Docker Desktop wordt ook ondersteund. Zie de [Windows-notities](#windows) voor de stap-voor-stap-uitleg.
+
+
+
+
+Globale installatie / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Het npx-commando hierboven blijft het canonieke pad voor een nieuwe installatie en voorkomt problemen met globale-prefix-rechten.
+
+
+
+
+npx serveert een oude versie
+
+npx cachet per versie. Forceer de laatste versie met `npx -y @agentmemory/agentmemory@latest`, of wis de cache eenmalig met `rm -rf ~/.npm/_npx` (macOS/Linux; verwijder op Windows `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Je draait al je eigen iii engine
+
+agentmemory zet iii-engine vast op v0.22.1 en koppelt niet aan een andere versie (de worker kan het protocol van een andere engine niet spreken). Stop de andere engine en voer dan `npx -y @agentmemory/agentmemory@latest` uit. Dit installeert en draait de vastgezette v0.22.1 in `~/.agentmemory/bin`, en laat je eigen `iii` ongewijzigd.
+
+
+
+---
+
+
+
+agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. Alle agents delen dezelfde memory server.
+
+
+ Werkt met elke agent die MCP of HTTP spreekt. Eén server, memories gedeeld over al deze agents.
+
+
+---
+
+Je legt elke sessie opnieuw dezelfde architectuur uit. Je ontdekt opnieuw dezelfde bugs. Je leert je agent opnieuw dezelfde voorkeuren aan. Ingebouwd geheugen (CLAUDE.md, .cursorrules) loopt vast op 200 regels en veroudert. agentmemory verhelpt dit. Het legt stilletjes vast wat je agent doet, comprimeert dat tot doorzoekbaar geheugen, en injecteert de juiste context wanneer de volgende sessie begint. Één commando. Werkt met meerdere agents.
+
+**Wat er verandert:** In sessie 1 zet je JWT-auth op. In sessie 2 vraag je om rate limiting. De agent weet al dat je auth jose middleware gebruikt in `src/middleware/auth.ts`, dat je tests tokenvalidatie dekken, en dat je jose boven jsonwebtoken koos voor Edge-compatibiliteit, zonder opnieuw uit te leggen en zonder te copy-pasten.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Standaard slaat agentmemory iii-engine-state op buiten de repository waarin je het start: `~/Library/Application Support/agentmemory` op macOS, `$XDG_DATA_HOME/agentmemory` of `~/.local/share/agentmemory` op Linux, en `%APPDATA%\agentmemory` op Windows. Een bestaande legacy `./data/state_store.db` of `./data/iii-config.yaml` wordt hergebruikt voor instantie 0, vóór die platformstandaard. Om expliciet een locatie te kiezen geef je `--data-dir ` door of stel je `AGENTMEMORY_DATA_DIR` in; beide expliciete instellingen krijgen voorrang boven legacy-detectie:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native en Docker-starts gebruiken dezelfde opgeloste hostmap; Docker mount deze via bind-mount op `/data`. `--instance 1` voegt `instance-1` toe aan de opgeloste map en selecteert het aparte standaard poortkwartet `3211/3212/3213/49234`.
+
+Laatste release notes: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Retrieval-nauwkeurigheid
+
+**coding-agent-life-v1** (eigen corpus, reproduceerbaar in een sandbox)
+
+| Adapter | P@5 | R@5 | Top-5-hitrate | p50-latentie |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep-baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% top-5-hitrate op het **P@5-wiskundige plafond** voor dit corpus (0.240, zie scorecard). Hybride haalt elke gold session op; grep mist 1 van 2 gold-resultaten bij de multi-session temporele query. De winst zit in **recall + temporeel**, niet in geaggregeerde precisie. Deze benchmark is klein en gold-sparse; de grotere LongMemEval-S hieronder onderscheidt beter. Volledige uitsplitsing per type + correctienotitie: [`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 vragen)
+
+| Systeem | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+> Embeddingmodel: `all-MiniLM-L6-v2` (lokaal, gratis, geen API-key nodig). Volledige rapporten: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Vergelijking met concurrenten: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), met agentmemory tegenover mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee en Hippo.
+
+**Lokaal reproduceren:** [`eval/README.md`](../eval/README.md), een harness met inpluggbare adapters voor LongMemEval `_s` (publieke set van 500 vragen) + `coding-agent-life-v1` (eigen corpus van 15 sessies). Grep-, vector- en agentmemory-adapters scoren naast elkaar, NDJSON-output, gepubliceerde scorecards komen terecht in [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Combineert goed met [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) en [Graphify](https://github.com/safishamsi/graphify).** Code-graph-indexering, multi-agent build-pipelines en bredere knowledge graphs over docs / PDF's / afbeeldingen / video's. agentmemory onthoudt het werk; die drie projecten verlichten de rest van de context-laag. Recepten + tabel voor vraagroutering: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Ingebouwd (CLAUDE.md)
+
+
+
Type
+
Memory engine + MCP-server
+
Memory-laag-API
+
Volledige agent-runtime
+
Persoonlijke AI
+
Memory-API + app
+
Team-memory-hub (LLM-proxy)
+
Vector-memory (OSS)
+
Memory engine (Oracle DB)
+
Memory-systeem
+
Statisch bestand
+
+
+
Retrieval R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Zelf gerapporteerd
+
PersonaMem 76% (zelf gerapporteerd)
+
~96.6% (zelf gerapporteerd)
+
94.4% (zelf gerapporteerd)
+
N/A
+
N/A (grep)
+
+
+
Auto-capture
+
12 hooks (geen handmatige moeite)
+
Handmatige add()-aanroepen
+
Agent bewerkt zelf
+
Handmatig
+
Extractie aan de API-kant
+
Proxy-interceptie (base-URL wisselen)
+
Handmatig
+
API-extractie
+
Handmatig
+
Handmatig bewerken
+
+
+
Zoeken
+
BM25 + Vector + Graph (RRF-fusie)
+
Vector + Graph
+
Vector (archief)
+
Semantisch
+
Vector + RAG
+
4 asset-types (Chat / Skill / Wiki / CodeGraph)
+
Alleen vector
+
Vector + semantisch
+
Decay-gewogen
+
Laadt alles in de context
+
+
+
Multi-agent
+
MCP + REST + leases + signals
+
API (geen coördinatie)
+
Alleen binnen Letta-runtime
+
Nee
+
Nee
+
Teamrollen + gedeelde assets
+
Nee
+
Alleen scoped
+
Gedeeld tussen meerdere agents
+
Bestanden per agent
+
+
+
Framework lock-in
+
Geen (elke MCP-client)
+
Geen
+
Hoog (moet Letta gebruiken)
+
Standalone
+
Geen
+
Proxy staat voor elke model-aanroep
+
Geen
+
Oracle Database
+
Geen
+
Formaat per agent
+
+
+
Externe dependencies
+
Geen (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + vector-db
+
Meerdere
+
Managed cloud
+
Docker-stack (Core + Hub + Proxy)
+
Vector store
+
Oracle AI Database
+
Geen
+
Geen
+
+
+
Memory lifecycle
+
4-laags consolidatie + decay + auto-forget
+
Passieve extractie
+
Beheerd door agent
+
Handmatig
+
Auto-forget
+
Handmatige review; auto-routing in ontwikkeling
+
Geen
+
Niet vermeld
+
Decay + consolidatie
+
Handmatig opschonen
+
+
+
Tokenefficiëntie
+
~1,900 tokens/sessie ($10/jaar)
+
Varieert per integratie
+
Core memory in context
+
Varieert
+
Cloud pricing
+
Niet vermeld
+
Geen tokenbudget
+
LLM-ondersteund (varieert)
+
Varieert
+
22K+ tokens bij 240 observaties
+
+
+
Realtime viewer
+
Ja (poort 3113)
+
Cloud dashboard
+
Cloud dashboard
+
Web UI
+
Cloud dashboard
+
Hub web UI
+
Nee
+
Nee
+
Nee
+
Nee
+
+
+
Self-hosted
+
Ja (standaard)
+
Optioneel
+
Optioneel
+
Ja
+
Nee (alleen cloud)
+
Ja (Docker)
+
Ja
+
Ja (Oracle DB)
+
Ja
+
Ja
+
+
+
+Opmerking over de benchmark: alleen de R@5 van agentmemory is ons eigen gemeten resultaat (LongMemEval-S, reproduceerbaar via benchmark/COMPARISON.md). De cijfers van mem0 en Letta zijn hun gepubliceerde LoCoMo-cijfers (een andere dataset); de cijfers van MemPalace, supermemory, TencentDB (PersonaMem) en oracleagentmemory zijn door de leverancier zelf gerapporteerde claims die we niet onafhankelijk hebben gereproduceerd (de run van oracleagentmemory gebruikte GPT-5.5 tegen een Oracle AI Database). Naast elkaar getoond voor een ruwe inschatting, niet als head-to-head op identieke data. Stertallen zijn benaderend en veranderen in de tijd.
+
+**Nieuwere spelers** die het kennen waard zijn, in detail vergeleken in [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Systeem | ⭐ | Invalshoek |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporele knowledge graph; sterkste gepubliceerde resultaten voor temporele queries (LongMemEval 63.8%), maar de graph wordt asynchroon opgebouwd, waardoor verse feiten kunnen achterblijven |
+| Cognee | 30K | Document-naar-knowledge-graph-ingestie, alleen Python, gebouwd voor gestructureerde entiteitsextractie in plaats van sessie-capture |
+
+Geen van deze vangt automatisch vanuit coding-agent-hooks, levert een local-first viewer, of draait keyless — de combinatie waar agentmemory om gebouwd is.
+
+---
+
+
+
+Compatibiliteit: deze release richt zich op `iii-sdk` 0.22.1 en zet iii-engine vast op v0.22.1.
+
+### Probeer het in 30 seconden
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` zet 3 realistische sessies klaar (JWT-auth, N+1-queryfix, rate limiting) en voert zoekopdrachten erop uit. Keyless-installaties schakelen vectoren uit, dus de keyword-queries via `mem::search` zouden via BM25 moeten raken, terwijl `database performance optimization` nul resultaten kan opleveren. `smart-search` kan daarnaast structurele graph-matches teruggeven wanneer er graph-data bestaat. Om de semantische query de N+1-fix via vectoren te laten vinden, stel je `EMBEDDING_PROVIDER=local` in, herstart je, en laat je de eerste modeldownload afronden.
+
+Open `http://localhost:3113` om het geheugen live te zien opbouwen.
+
+### Een nieuwe installatie en persistentie na herstart valideren
+
+Valideer met de server actief de REST API, health, de viewer en de iii-gebaseerde runtime-status:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Het ready-panel bij het opstarten houdt rekening met alle vier poorten: REST/MCP HTTP op 3111, iii-streams op 3112, de viewer op 3113, en de iii worker WebSocket op 49134. `status` bevestigt de gezondheid van agentmemory en de actieve provider/embedding-modus. Sla een test-probe op en controleer of deze doorzoekbaar is:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Voer vervolgens `npx -y @agentmemory/agentmemory@latest stop` uit, start het canonieke commando opnieuw in Terminal 1, wacht op `/agentmemory/livez`, en herhaal de zoekopdracht. De probe moet nog steeds worden teruggegeven. Als je een aangepaste `--data-dir` koos, geef dan bij de herstart dezelfde map door.
+
+### Dagelijkse commando's
+
+Installatie en setup staan hierboven bij [Install](#install) (de eerste run begeleidt je erdoorheen). Dagelijks gebruik:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Sessie-replay
+
+Elke sessie die agentmemory vastlegt, is afspeelbaar. Open de viewer, kies het tabblad **Replay**, en schuif door de tijdlijn: prompts, tool calls, tool-resultaten en antwoorden worden weergegeven als afzonderlijke events met play/pause, snelheidsregeling (0.5x tot 4x) en toetsenbordsneltoetsen (spatie om te schakelen, pijltjes om stap voor stap te gaan).
+
+Om oudere Claude Code JSONL-transcripten te importeren:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Geïmporteerde sessies verschijnen in de Replay-kiezer naast de native sessies. Onder de motorkap loopt elke entry via de iii-functies `mem::replay::load`, `mem::replay::sessions` en `mem::replay::import-jsonl`, zonder side-channel-servers. Elk geïmporteerd transcript wordt geïndexeerd voor zoeken, gestempeld met oorsprongkanaal `import`, en doorzocht op een sessie-crystal en lessen.
+
+> **Let op als je `import-jsonl` als je primaire capture-pad gebruikt:** de `cleanupPeriodDays` van Claude Code (in `~/.claude/settings.json`, standaard **30**) verwijdert automatisch JSONL-transcripten die ouder zijn dan dat venster uit `~/.claude/projects/`. Als je agentmemory vers installeert op een Claude Code-geschiedenis van maanden oud, is alles ouder dan 30 dagen al verdwenen vóór de eerste import. Draai `import-jsonl` op een cron, verhoog `cleanupPeriodDays` naar een hogere waarde, of koppel de auto-capture-hooks (het standaard installatiepad via de plugin) zodat elke turn in agentmemory terechtkomt terwijl de sessie live is en de JSONL-cleanup er niet meer toe doet.
+
+### Upgraden / onderhoud
+
+Gebruik het onderhoudscommando wanneer je bewust je lokale runtime wilt bijwerken:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Waarschuwing: dit commando wijzigt de huidige workspace/runtime. Het kan JavaScript-dependencies bijwerken en de vastgezette `iiidev/iii:0.22.1`-Docker-image ophalen. Het installeert nooit een niet-vastgezette of nieuwere iii engine.
+
+Implementatiedetails staan in `src/cli.ts` (zie `runUpgrade` rond de regels `src/cli.ts:544-595`).
+
+### Claude Code (één blok, plak dit)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code zonder de plugin-installatie (MCP-standalone pad)
+
+Als je de MCP-server van agentmemory rechtstreeks via `~/.claude.json` koppelt in plaats van `/plugin install` te gebruiken, lost Claude Code `${CLAUDE_PLUGIN_ROOT}` nooit op en moet je hook-scripts naar absolute paden in `~/.claude/settings.json` laten verwijzen. Die paden bevatten doorgaans de agentmemory-versie (bijv. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), waardoor de volgende upgrade stilletjes elke hook stuk maakt.
+
+Workaround:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Dit voegt dezelfde hook-commando's samen in `~/.claude/settings.json`, met absolute paden die verwijzen naar de gebundelde `plugin/`-map van het momenteel geïnstalleerde `@agentmemory/agentmemory`-package. Voer het commando opnieuw uit na het upgraden van agentmemory om de paden te verversen. Gebruikersinvoer in hetzelfde bestand blijft behouden; alleen eerdere agentmemory-invoer wordt vervangen. Het `/plugin install`-pad blijft de aanbevolen aanpak.
+Voor remote of beveiligde deployments start je Claude Code met `AGENTMEMORY_URL` en `AGENTMEMORY_SECRET` ingesteld. De plugin geeft beide waarden door aan zijn gebundelde MCP-server; wanneer `AGENTMEMORY_URL` leeg is, gebruikt de MCP-shim `http://localhost:3111`.
+
+### Codex CLI (Codex-pluginplatform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+De Codex-plugin komt uit dezelfde `plugin/`-map als de Claude Code-plugin. Hij registreert:
+
+- Een gebundelde stdio MCP-bridge naar de draaiende daemon, zonder npm-download of fallback-store. Zie de [lokale Codex-guide](../docs/plugins/codex-local.md) om een niet-uitgebrachte build te testen.
+- 6 lifecycle-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 aanroepbare skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 referentieskills die de agent op aanvraag laadt (memory discipline, MCP-tools, REST API, config, agents, hooks, architecture, en de skill-authoring guide)
+
+De hook-engine van Codex injecteert `CLAUDE_PLUGIN_ROOT` in hook-subprocessen (zie [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), zodat dezelfde hook-scripts op beide hosts werken zonder duplicatie. Subagent-, SessionEnd-, Notification-, TaskCompleted- en PostToolUseFailure-events zijn alleen voor Claude Code en worden niet geregistreerd voor Codex.
+
+#### Codex-hooks: vertrouwen en compatibiliteit
+
+Native plugin-hook-dispatch is geverifieerd met Codex CLI 0.150.1. Vertrouw de plugin-hooks voordat je capture verwacht. Het gedrag van Codex Desktop hangt af van de gebundelde runtime; controleer `/hooks` en bevestig een vastgelegd event voordat je een workaround inschakelt.
+
+Als je host globale hooks nodig heeft, spiegel je de commando's naar de globale `~/.codex/hooks.json`. Wanneer MCP al gekoppeld is, heeft de huidige `connect`-adapter `--force` nodig om bij de hook-installatie te komen:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Dit voegt globale hooks samen en herschrijft de agentmemory MCP-entry, met behoud van niet-gerelateerde entries. Controleer aangepaste agentmemory-endpoint-instellingen voordat je `--force` gebruikt. Voer opnieuw uit na het upgraden om de scriptpaden te verversen. Schakel ofwel native plugin-hooks ofwel globale kopieën in om dubbele capture te vermijden.
+
+### GitHub Copilot CLI
+
+Voor de VS Code-agentmodus gebruik je de [Copilot MCP- en auto-capture-guide](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). De CLI-connector configureert VS Code niet.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` voegt `mcpServers.agentmemory` samen in `~/.copilot/mcp-config.json` (of `$COPILOT_HOME/mcp-config.json` wanneer `COPILOT_HOME` is ingesteld) en behoudt bestaande servers. Op native Windows is dit de enige geautomatiseerde `connect`-adapter; configureer elke andere native Windows-agent handmatig. `connect` via WSL wordt alleen ondersteund wanneer de doelagent in diezelfde WSL-omgeving is geïnstalleerd. Copilot pikt de MCP-server op bij de volgende start of na `/mcp`. Installeer ook de plugin wanneer je de volledige hook/skill-ervaring wilt.
+
+
+OpenClaw (plak deze prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Volledige handleiding: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (plak deze prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Volledige handleiding: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Other agents
+
+Start de memory server: `npx -y @agentmemory/agentmemory@latest`
+
+#### Native skills via `npx skills add` (50+ agents)
+
+agentmemory levert 17 skills in het Claude-Code-achtige `/SKILL.md`-formaat: 9 aanroepbare actie-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) en 8 referentieskills die de agent op aanvraag laadt (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). De referentieskills bevatten datatabellen die uit de bron gegenereerd zijn, dus ze lopen nooit uit de pas. De [`skills`](https://npmjs.com/package/skills)-CLI van vercel-labs installeert ze automatisch in de native skills-map van de aanroepende agent, verspreid over 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, en meer):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Dit is **complementair** aan `agentmemory connect `:
+
+- `agentmemory connect ` schrijft de MCP-serverconfig zodat de tools beschikbaar zijn.
+- `npx skills add rohitg00/agentmemory` installeert de skills zodat de agent weet wanneer hij ze moet aanroepen.
+
+Voor de paar agents die de skills-CLI nog niet dekt (Zed v1.3.x en lager), plaats je de 17 SKILL.md-bestanden zelf in de native skills-map van de agent; hetzelfde formaat werkt overal.
+
+#### Standaard MCP-blok
+
+De agentmemory-entry is hetzelfde **MCP-serverblok** op elke host die de `mcpServers`-vorm gebruikt (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Voeg deze entry samen met het bestaande `mcpServers`-object** in het configuratiebestand van de host; vervang het bestand niet. Als het bestand al andere servers heeft, voeg je `agentmemory` ernaast toe als een extra key binnen `mcpServers`. Als `mcpServers` volledig ontbreekt, plak je het blok binnen `{ "mcpServers": { ... } }`. De `${VAR}`-placeholders erven `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` van de shell bij het starten van de MCP-server; niet-ingestelde variabelen geven lege strings door en de shim valt terug op `http://localhost:3111`. Eén gekoppelde entry dekt zowel lokale als remote (k8s / reverse-proxied) deployments.
+
+| Agent | Configuratiebestand | Opmerkingen |
+|---|---|---|
+| **Cursor (alleen MCP)** | `~/.cursor/mcp.json` | Voeg samen in `mcpServers`, of `agentmemory connect cursor`. Eén-klik-deeplink ook beschikbaar op de website. |
+| **Cursor (volledige plugin)** | `.cursor-plugin/` | Cursor Marketplace-vermelding (inzending in review) of Cursor Settings → Plugins → lokale checkout. Registreert 7 auto-capture-hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + de MCP-server, met `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` beheerd in het plugin-dashboard van Cursor. Werkt in de Cursor IDE en de `cursor-agent`-CLI; in CLI-print-modus worden prompts achteraf aangevuld vanuit het sessietranscript aan het einde van de sessie. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Voeg samen in `mcpServers`. Herstart Claude Desktop na het bewerken. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP-instellingen (Settings UI → MCP Servers → Edit) | Hetzelfde `mcpServers`-blok. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` voegt de MCP-entry samen; `--with-hooks` voegt zes native auto-capture-hooks toe (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) met de kleine-letter-toolmatchers van Devin. Controleer met `devin mcp list` en `/hooks` binnen devin. |
+| **Devin CLI (volledige plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` vanuit een checkout registreert alle 17 skills als `/agentmemory:`-slashcommando's plus de MCP-server. Devin-plugin-hooks kunnen `SessionStart`/`SessionEnd` niet afvuren, combineer dit dus met `connect devin --with-hooks` voor volledige sessie-capture. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Voeg een aangepaste MCP toe (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` die wijst naar een netwerkbereikbare agentmemory-deployment, plus `AGENTMEMORY_SECRET` (cloudsessies kunnen localhost niet bereiken — zie [`deploy/`](../deploy/)). Bewaar het secret in Devin Secrets, en gebruik vervolgens "Test listing tools" om te controleren of alle 54 tools verschijnen. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (voegt automatisch samen). |
+| **GitHub Copilot CLI (alleen MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` voegt `mcpServers.agentmemory` samen; Copilot pikt dit op bij de volgende start of `/mcp`. |
+| **GitHub Copilot CLI (volledige plugin)** | Copilot plugin-installatie | `copilot plugin install rohitg00/agentmemory:plugin` voor de plugin vanuit de GitHub-submap. |
+| **OpenClaw** | OpenClaw MCP-config | Hetzelfde `mcpServers`-blok. Dieper: `openclaw plugins install ./integrations/openclaw` claimt de memory-slot van OpenClaw (schakelt automatisch over vanaf `memory-core`); stel `plugins.entries.agentmemory.hooks.allowConversationAccess=true` in, anders wordt turn-capture stilletjes geblokkeerd. Zie [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (alleen MCP)** | `.codex/config.toml` | TOML-vorm: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, of voeg handmatig `[mcp_servers.agentmemory]` toe. |
+| **Codex CLI (volledige plugin)** | Codex plugin-marketplace | `codex plugin marketplace add rohitg00/agentmemory`, daarna `codex plugin add agentmemory@agentmemory`. Registreert MCP + 6 lifecycle-hooks + 17 skills. Vertrouw de hooks en verifieer de capture in je host; zie [Codex-setup en -validatie](../docs/plugins/codex-local.md). |
+| **OpenCode (alleen MCP)** | `opencode.json` | Andere vorm: top-level `mcp`-key, command als array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (volledige plugin)** | `plugin/opencode/` | 22 auto-capture-hooks voor sessie-lifecycle, berichten, tools en errors. Projecttoewijzing is per sessie, dus één OpenCode-proces dat meerdere repositories omspant, bestandt elke sessie onder zijn eigen project. Twee slashcommando's (`/recall`, `/remember`). Kopieer `plugin/opencode/` naar je OpenCode-workspace en voeg de plugin-entry toe aan `opencode.json`. Zie [`plugin/opencode/README.md`](../plugin/opencode/README.md) voor de volledige hooktabel + gap-analyse. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installeert de gebundelde extensie in de auto-discovery-map van pi (recall bij agentstart, capture bij agent-einde, `memory_search` / `memory_save` / `memory_health`-tools, `/agentmemory-status`). `/reload` in een draaiende pi pikt dit op. [`integrations/pi`](../integrations/pi/) is ook een pi-package (`pi install ./integrations/pi` vanuit een checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` geeft de 6-hook memory-provider (prefetch, turn-capture, session-end, pre-compress, MEMORY.md-mirroring, system-prompt-blok). Valideer met `hermes plugins doctor` en `hermes memory status`. Zie [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` schrijft het standaard `mcpServers`-blok. De hook-payload is veldcompatibel met Claude Code, dus de bestaande 12-hook-scripts werken zonder aanpassing; koppel ze via de `hooks`-sectie in hetzelfde `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installeert MCP en capture-hooks in de gedeelde customization-map. Zie [Antigravity-setup en -beperkingen](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` gebruikt dezelfde MCP- en hookconfiguratie als de huidige IDE-versies. Bestaande installaties moeten verversen met `--force`; zie de [upgrade-notities](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` schrijft de config op gebruikersniveau. Workspace-overrides komen in `.kiro/settings/mcp.json` naast je code. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` schrijft het standaard `mcpServers`-blok. Warp ontdekt ook automatisch skills vanuit `.claude/skills/`; zodra de Claude Code-plugin is geïnstalleerd, verschijnen de 8 agentmemory-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) native in het slashcommando-palet van Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` schrijft het standaard `mcpServers`-blok. Gebruikers van de VS Code-extensie: plak hetzelfde blok via Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (voorkeur) of `config.json` (legacy) | `agentmemory connect continue` maakt `config.yaml` helemaal opnieuw aan wanneer geen van beide bestaat, of past een bestaande `config.json` aan. **Als je al een `config.yaml` hebt**, print de adapter het exacte blok om onder `mcpServers:` te plakken; hij herschrijft je yaml niet stilletjes, omdat het veilig behouden van comments en anchors een YAML-parser vereist die het package niet meelevert. Continue gebruikt de array-vorm (geen object) voor `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` schrijft onder `context_servers` (de key van Zed, NIET `mcpServers`). Remote MCP-servers kunnen in plaats daarvan gekoppeld worden via `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` schrijft het standaard `mcpServers`-blok. Project-scoped overrides komen in `/.factory/mcp.json`. Geef `--with-hooks` door voor native auto-capture. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` voegt een `@deepseek-ai/dsh-mcp-client`-rij toe aan de patch-laag op home-niveau die elk Harness-profiel laadt; tools registreren als `mcp__agentmemory__*`. Geef `--with-hooks` door om ook auto-capture te koppelen: de gebundelde Claude Code-hookscripts draaien via de first-party `@deepseek-ai/dsh-hooks-claude-code`-bridge van Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via een manifest geschreven naar `$DSH_HOME/agentmemory.hooks.json`. Standaard `~/.dsh` wanneer `DSH_HOME` niet is ingesteld. |
+| **Goose** | Goose MCP-instellingen-UI | Hetzelfde `mcpServers`-blok; gebruik `goose configure` → Add Extension → MCP. Direct bewerken van de YAML op `~/.config/goose/config.yaml` wordt ondersteund, maar het schema gebruikt `extensions:` + `cmd` (niet `mcpServers:` + `command`). |
+| **Aider** | n/a | Praat rechtstreeks met de REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Elke agent (32+)** | n/a | `npx skillkit install agentmemory` detecteert automatisch de host en voegt samen. |
+
+**Gesandboxte MCP-clients** (Flatpak / Snap / restrictieve containers) die de `localhost` van de host niet kunnen bereiken: stel ook `"AGENTMEMORY_FORCE_PROXY": "1"` in het `env`-blok in, en richt `AGENTMEMORY_URL` op een route die de sandbox daadwerkelijk kan bereiken (bijv. je LAN-IP).
+
+### Programmatische toegang (Python / Rust / Node)
+
+agentmemory registreert zijn kernoperaties als iii-functies (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Elke taal met een iii-SDK kan ze rechtstreeks aanroepen via `ws://localhost:49134`, zonder een apart REST-client per taal.
+
+```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"},
+})
+```
+
+Uitgewerkt voorbeeld: [`examples/python/`](../examples/python/) (snelstart + observation/recall-flow). REST op `:3111` blijft beschikbaar voor hosts zonder iii-runtime.
+
+### Vanuit de bron
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Dit start agentmemory met een lokale `iii-engine` als de vastgezette binary al is geïnstalleerd, of gebruikt Docker Compose wanneer dat gekozen is. REST, streams en de viewer binden standaard aan `127.0.0.1`. Het automatische binary-pad voor macOS/Linux vereist `curl`, een POSIX `sh` en `tar`.
+
+Installeer `iii-engine` handmatig. **agentmemory zet `iii-engine` momenteel vast op `v0.22.1`**, dezelfde release als zijn `iii-sdk`-dependency; de worker spreekt het wire-protocol van die engine, en 0.20.0 herorganiseerde het SDK-oppervlak, dus die twee bewegen samen op in agentmemory-releases. Overschrijf met `AGENTMEMORY_III_VERSION=` als je je eigen engine draait en weet dat die matcht.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** vervang `aarch64-apple-darwin` door `x86_64-apple-darwin`
+- **Linux x64:** vervang door `x86_64-unknown-linux-gnu`
+- **Linux arm64:** vervang door `aarch64-unknown-linux-gnu`
+- **Windows:** download `iii-x86_64-pc-windows-msvc.zip` van [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) en pak `iii.exe` uit naar `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Elk archief heeft een bijpassend `.sha256`-bestand op de releasepagina; wanneer je het platform wisselt, gebruik je de hash van dat bestand in de controle hierboven (op Windows: `Get-FileHash`). De automatische installer in `npx @agentmemory/agentmemory` legt deze hashes vast en weigert een archief dat niet overeenkomt.
+
+Of gebruik Docker (de gebundelde `docker-compose.yml` haalt `iiidev/iii:0.22.1` op). Volledige documentatie: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory draait op Windows 10/11, maar het Node.js-package alleen is niet genoeg; je hebt ook de vastgezette iii-engine v0.22.1-runtime nodig als achtergrondproces. De CLI pakt de Windows ZIP niet automatisch uit, dus native Windows-gebruikers moeten `iii.exe` handmatig installeren, WSL2 gebruiken, of Docker Desktop kiezen.
+
+Geautomatiseerde MCP-koppeling op native Windows ondersteunt alleen `agentmemory connect copilot-cli`. Voor Claude Code, Codex, Cursor en elke andere native Windows-agent kopieer je het handmatige MCP-blok uit [Other agents](#other-agents) naar de Windows-config van die agent. `connect` draaien in WSL is alleen geschikt wanneer de doelagent ook in dezelfde WSL-omgeving is geïnstalleerd; het bewerkt niet de configuratie van een agent op de Windows-host.
+
+**Optie A: vooraf gebouwde Windows-binary (aanbevolen)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Optie B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Optie C: alleen standalone MCP (geen engine).** Als je alleen de MCP-tools voor je agent nodig hebt en geen REST API, viewer of cron-jobs nodig hebt, sla je de engine helemaal over:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostiek voor Windows:** als `npx -y @agentmemory/agentmemory@latest` mislukt, voer je het opnieuw uit met `--verbose` om de werkelijke engine-stderr te zien. Veelvoorkomende faalmodi:
+
+| Symptoom | Oplossing |
+|---|---|
+| `The engine process started but the REST API never responded.` | Controleer of alle vier afgeleide poorten vrij zijn, verifieer dat de vastgezette `iii.exe` actief bleef, voer dan opnieuw uit met `--verbose` en inspecteer de opgevangen engine-stderr |
+| `Could not start iii-engine` | Noch `iii.exe` noch Docker is geïnstalleerd. Zie Optie A of B hierboven |
+| Poortconflict | `netstat -ano \| findstr :3111` om te zien wat gebonden is, kill het dan of gebruik `--port ` |
+| Docker-fallback overgeslagen terwijl Docker wel geïnstalleerd is | Zorg dat Docker Desktop daadwerkelijk draait (systeemvak-icoon) |
+
+> Opmerking: de iii **engine** is een vooraf gebouwde binary, geen cargo-crate, probeer dus niet om `cargo install` erop te gebruiken. (De iii **SDK's** zijn gepubliceerd op crates.io, npm en PyPI, maar agentmemory heeft ze niet nodig.) Ondersteunde installatiemethoden voor de engine zijn allemaal vastgezet op v0.22.1: de vooraf gebouwde binary hierboven, het auto-installatiepad van agentmemory voor macOS/Linux (`curl`, POSIX `sh` en `tar` vereist), en de Docker-image `iiidev/iii:0.22.1`. Een kale upstream `install.sh | sh` installeert de nieuwste engine, wat agentmemory niet ondersteunt. Gebruik `npx -y @agentmemory/agentmemory@latest`; op macOS/Linux haalt dit de vastgezette engine binnen in `~/.agentmemory/bin`.
+
+---
+
+
Deployment
+
+Eén-klik-templates voor managed hosts. Elke template levert een zelfstandige
+Dockerfile die `@agentmemory/agentmemory` van npm ophaalt en de iii-engine-binary
+kopieert vanuit de officiële `iiidev/iii`-Docker-Hub-image; er is geen vooraf
+gebouwde agentmemory-image nodig. Persistente opslag wordt gemount op `/data`;
+het entrypoint bij de eerste boot overschrijft de door npm gebundelde
+iii-config (die bindt aan `127.0.0.1`) met een voor deployment afgestemde
+versie die bindt aan `0.0.0.0` en absolute `/data`-paden gebruikt, genereert
+het HMAC-secret, en laat dan via `gosu` de privileges zakken van `root` naar
+`node` voordat de agentmemory-CLI wordt uitgevoerd (`exec`).
+
+
+
+
+
+
+De één-klik-deployknop van Render vereist een `render.yaml` in de root van de repository, die we bewust leeg houden. Gebruik de Render Blueprint-flow die gedocumenteerd is in [`deploy/render/`](.././deploy/render/README.md) om handmatig naar de blueprint in de repo te wijzen.
+
+Volledige setupdetails (HMAC-capture, SSH-tunnel voor de viewer, rotatie, backup,
+minimale kosten) staan in [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): één machine met
+ `auto_stop_machines = "stop"`; goedkoopst in rust.
+- [`deploy/railway`](.././deploy/railway/README.md): vast tarief op het Hobby-plan,
+ volume in het dashboard.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint-flow,
+ automatische disk-snapshots op betaalde plannen.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted op je
+ eigen VPS via [Coolify](https://coolify.io/self-hosted); dezelfde Docker
+ Compose-stack, jij bent eigenaar van de host en de data.
+
+Alleen poort `3111` wordt gepubliceerd. De viewer op `3113` blijft gebonden aan
+loopback binnen de container; de README van elke template documenteert de
+SSH-tunnel-aanpak om deze te bereiken.
+
+---
+
+
+
+Elke coding agent vergeet alles wanneer de sessie eindigt, en elke nieuwe sessie begint met jou die opnieuw je stack uitlegt. agentmemory draait op de achtergrond en laat die stap vervallen.
+
+```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 ingebouwd agentgeheugen
+
+Elke AI coding agent levert ingebouwd geheugen: Claude Code heeft `MEMORY.md`, Cursor heeft notepads, Cline heeft een memory bank. Deze werken als geheugensteuntjes. agentmemory is de doorzoekbare database achter die geheugensteuntjes.
+
+| | Ingebouwd (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Schaal | Limiet van 200 regels | Onbeperkt |
+| Zoeken | Laadt alles in de context | BM25 + vector + graph (alleen top-K) |
+| Tokenkosten | 22K+ bij 240 observaties | ~1,900 tokens (92% minder) |
+| Cross-agent | Bestanden per agent | MCP + REST (elke agent) |
+| Coördinatie | Geen | Leases, signals, actions, routines |
+| Observability | Bestanden handmatig lezen | Realtime viewer op :3113 |
+
+---
+
+
+
+### Memory-pipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-laagse memory-consolidatie
+
+Gemodelleerd naar hoe menselijke breinen geheugen verwerken, inclusief consolidatie tijdens slaap.
+
+| Laag | Wat | Analogie |
+|------|------|---------|
+| **Working** | Ruwe observaties uit toolgebruik | Kortetermijngeheugen |
+| **Episodic** | Gecomprimeerde sessiesamenvattingen | "Wat er gebeurd is" |
+| **Semantic** | Geëxtraheerde feiten en patronen | "Wat ik weet" |
+| **Procedural** | Workflows en beslispatronen | "Hoe je het doet" |
+
+Memories vervagen in de tijd (Ebbinghaus-curve). Vaak opgevraagde memories worden sterker. Verouderde memories worden automatisch verwijderd. Tegenstrijdigheden worden gedetecteerd en opgelost.
+
+### Wat er wordt vastgelegd
+
+| Hook | Legt vast |
+|------|----------|
+| `SessionStart` | Projectpad, session ID |
+| `UserPromptSubmit` | Gebruikersprompts (privacy-gefilterd) |
+| `PreToolUse` | Bestandstoegangspatronen + verrijkte context |
+| `PostToolUse` | Toolnaam, input, output |
+| `PostToolUseFailure` | Errorcontext |
+| `PreCompact` | Injecteert geheugen opnieuw vóór compactie |
+| `SubagentStart/Stop` | Lifecycle van sub-agents |
+| `Stop` | Samenvatting aan het einde van de sessie |
+| `SessionEnd` | Markering dat de sessie voltooid is |
+
+### Belangrijkste functies
+
+| Functie | Beschrijving |
+|---|---|
+| **Automatische capture** | Elk toolgebruik vastgelegd via hooks, zonder handmatige moeite |
+| **Semantisch zoeken** | BM25 + vector + knowledge graph met RRF-fusie |
+| **Memory-evolutie** | Versiebeheer, supersession, relatiegraphs |
+| **Recall-hygiëne** | Vervangen memory-versies verlaten de zoekindexen; de versieketen in KV behoudt de volledige geschiedenis |
+| **Near-duplicate-hints** | Bij opslaan wordt een adviserende `similarTo`-match gerapporteerd wanneer nieuwe content sterk op een bestaande memory lijkt |
+| **Scoping per agent** | `agentId` loopt door save en recall heen, over REST, MCP en de zoekindex, in shared of isolated modus |
+| **Provenance op schrijfmoment** | Elke observatie en memory draagt een onveranderlijk oorsprongkanaal (user, agent, tool, import of shared), gestempeld bij capture, save en import |
+| **Auto-forgetting** | TTL-verval, detectie van tegenstrijdigheden, eviction op basis van belang |
+| **Privacy eerst** | API-keys, secrets en ``-tags verwijderd vóór opslag |
+| **Zelfherstellend** | Circuit breaker, fallback-keten van providers, health monitoring |
+| **Claude-bridge** | Bidirectionele sync met MEMORY.md |
+| **Knowledge graph** | Entiteitsextractie + BFS-traversal |
+| **Team memory** | Namespaced shared + private tussen teamleden |
+| **Citation-provenance** | Traceer elke memory terug naar de bron-observaties |
+| **Git-snapshots** | Versioneer, rollback en diff van memory-state |
+
+---
+
+
+
+Triple-stream retrieval combineert drie signalen:
+
+| Stream | Wat het doet | Wanneer |
+|---|---|---|
+| **BM25** | Keyword-matching met stemming en synonym-expansion | Altijd actief |
+| **Vector** | Cosine similarity over dense embeddings | Embedding-provider geconfigureerd |
+| **Graph** | Knowledge-graph-traversal via entity-matching | Entiteiten gedetecteerd in de query |
+
+Samengevoegd met Reciprocal Rank Fusion (RRF, k=60) en gediversifieerd per sessie (max. 3 resultaten per sessie).
+
+Wanneer een vector-index gevuld is, gebruikt `mem::search` (achter `memory_recall`) de hybride BM25 + vector-ranker. Zonder embeddings gebruikt het BM25. `smart-search` kan daarnaast structurele graph-matches samenvoegen wanneer er graph-data bestaat, ook in keyless-modus. Lesson-recall draait op een eigen in-memory BM25-index in plaats van het hele corpus per query te doorzoeken. Vervangen memory-versies worden uitgesloten van elk recall-pad; de versieketen behoudt hun geschiedenis.
+
+Vectoren overleven een crash of force-kill. De vector-index wordt in batches opgeslagen, maximaal elke `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minuten). Elke vector die er tussendoor bijkomt of verdwijnt, wordt ook meteen geschreven naar een klein pending-log in de state store, en de volgende start speelt dit af zonder de embedding-provider aan te roepen. Elke succesvolle save maakt het log leeg. Documenten die na het afspelen nog geen vector hebben, worden op de achtergrond opnieuw ge-embed in batches van `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) totdat er geen meer over zijn, en een backfill die gestopt wordt, gaat bij de volgende start verder. `/agentmemory/status` en de viewer tonen de grootte van het pending-log en de status van de backfill. Keyless-installaties schrijven niets.
+
+BM25 tokeniseert standaard Grieks, Cyrillisch, Hebreeuws, Arabisch en Latijn met accenten. Voor Chinese / Japanse / Koreaanse memories installeer je de optionele segmenters (`npm install @node-rs/jieba tiny-segmenter`) om CJK-reeksen op te splitsen in tokens op woordniveau; zonder deze valt agentmemory soft terug op tokenisatie van de hele reeks en print het eenmalig een hint naar stderr.
+
+### Embedding-providers
+
+Keyless-installaties schakelen vector-embeddings uit: `mem::search` gebruikt BM25, terwijl `smart-search` ook bestaande structurele graph-data kan gebruiken. Om in te stappen op gratis semantische embeddings op het eigen apparaat, voeg je dit toe aan `~/.agentmemory/.env` en herstart je agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+De normale npm-installatie bevat de optionele `@huggingface/transformers`-runtime. De eerste embedding-aanvraag downloadt `Xenova/all-MiniLM-L6-v2`, waarvoor netwerktoegang nodig is en wat langer kan duren; latere inference draait op het eigen apparaat. Remote providers worden automatisch gedetecteerd aan hun keys, tenzij `EMBEDDING_PROVIDER` ze overschrijft.
+
+| Provider | Model | Kosten | Opmerkingen |
+|---|---|---|---|
+| **Lokaal (aanbevolen opt-in)** | `all-MiniLM-L6-v2` | Gratis | Op het eigen apparaat na de eerste modeldownload, +8pp recall t.o.v. alleen BM25 |
+| Gemini | `gemini-embedding-001` | Gratis tier | 100+ talen, 768/1536/3072 dims (MRL), input tot 2048 tokens. Vervangt `text-embedding-004` ([deprecated, uitgefaseerd op 14 jan. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Hoogste kwaliteit |
+| Voyage AI | `voyage-code-3` | Betaald | Geoptimaliseerd voor code |
+| Cohere | `embed-english-v3.0` | Gratis trial | Algemeen inzetbaar |
+| OpenRouter | Elk model | Varieert | Multi-model-proxy |
+
+---
+
+
+
+54 tools, 6 resources, 3 prompts en 17 skills.
+
+> **MCP-shim versus volledige server:** het gepubliceerde `@agentmemory/mcp`-package is een dunne shim. Het toont het volledige oppervlak van 54 tools **alleen wanneer het een draaiende agentmemory server kan bereiken** via `AGENTMEMORY_URL` (proxy-modus). Als er geen server bereikbaar is, valt de shim terug op een lokale set van 7 tools (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). De env-variabele `AGENTMEMORY_TOOLS=core|all` is een vlag aan de *serverzijde*; deze instellen in het `env`-blok van de shim heeft geen effect. Zie je maar 7 tools in Cursor / OpenCode / Gemini CLI, start dan `npx -y @agentmemory/agentmemory@latest` (of de Docker-stack) en stel `AGENTMEMORY_URL=http://localhost:3111` in.
+
+### 54 tools
+
+Drie tool-oppervlakken, van klein naar groot: `AGENTMEMORY_TOOLS=core` beperkt de zichtbaarheid tot 8 essentiële tools (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); de basisset hieronder bestaat uit de 14 fundamentele tools van het registry; de standaard (`AGENTMEMORY_TOOLS=all`) toont alle 54.
+
+
+Basistools (14)
+
+| Tool | Beschrijving |
+|------|-------------|
+| `memory_recall` | Doorzoek eerdere observaties |
+| `memory_compress_file` | Comprimeer markdown-bestanden met behoud van structuur |
+| `memory_save` | Sla een inzicht, beslissing of patroon op |
+| `memory_file_history` | Eerdere observaties over specifieke bestanden |
+| `memory_patterns` | Detecteer terugkerende patronen |
+| `memory_sessions` | Lijst recente sessies |
+| `memory_smart_search` | Hybride semantisch + keyword-zoeken |
+| `memory_vision_search` | Doorzoek afbeeldingsobservaties |
+| `memory_timeline` | Chronologische observaties |
+| `memory_profile` | Projectprofiel (concepten, bestanden, patronen) |
+| `memory_export` | Exporteer alle memory-data |
+| `memory_relations` | Query de relatiegraph |
+| `memory_commit_lookup` | Sessies achter een git-commit |
+| `memory_commits` | Commits vastgelegd voor een sessie |
+
+
+
+
+Uitgebreide tools (54 in totaal, het standaardoppervlak)
+
+| Tool | Beschrijving |
+|------|-------------|
+| `memory_patterns` | Detecteer terugkerende patronen |
+| `memory_timeline` | Chronologische observaties |
+| `memory_relations` | Query de relatiegraph |
+| `memory_graph_query` | Knowledge-graph-traversal |
+| `memory_consolidate` | Voer 4-laagse consolidatie uit |
+| `memory_claude_bridge_sync` | Sync met MEMORY.md |
+| `memory_team_share` | Deel met teamleden |
+| `memory_team_feed` | Recent gedeelde items |
+| `memory_audit` | Audit trail van operaties |
+| `memory_governance_delete` | Verwijderen met audit trail |
+| `memory_snapshot_create` | Git-versiebeheerde snapshot |
+| `memory_action_create` | Maak werkitems met dependencies |
+| `memory_action_update` | Werk actiestatus bij |
+| `memory_frontier` | Niet-geblokkeerde acties gerangschikt op prioriteit |
+| `memory_next` | De ene belangrijkste volgende actie |
+| `memory_lease` | Exclusieve action leases (multi-agent) |
+| `memory_routine_run` | Instantieer workflow-routines |
+| `memory_signal_send` | Berichten tussen agents |
+| `memory_signal_read` | Lees berichten met ontvangstbevestigingen |
+| `memory_checkpoint` | Externe conditiepoorten |
+| `memory_mesh_sync` | P2P-sync tussen instanties |
+| `memory_sentinel_create` | Event-gestuurde watchers |
+| `memory_sentinel_trigger` | Vuur sentinels extern af |
+| `memory_sketch_create` | Tijdelijke action graphs |
+| `memory_sketch_promote` | Promoveer naar permanent |
+| `memory_crystallize` | Comprimeer actieketens |
+| `memory_diagnose` | Health-checks |
+| `memory_heal` | Herstel vastgelopen state automatisch |
+| `memory_facet_tag` | Dimensie:waarde-tags |
+| `memory_facet_query` | Query op facet-tags |
+| `memory_verify` | Traceer provenance |
+
+
+
+### 6 resources · 3 prompts · 17 skills
+
+| Type | Naam | Beschrijving |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, aantal sessies, aantal memories |
+| Resource | `agentmemory://project/{name}/profile` | Intelligence per project |
+| Resource | `agentmemory://project/{name}/recent` | Recente observaties voor een project |
+| Resource | `agentmemory://memories/latest` | Laatste 10 actieve memories |
+| Resource | `agentmemory://graph/stats` | Knowledge-graph-statistieken |
+| Resource | `agentmemory://team/{id}/profile` | Gedeeld teamprofiel |
+| Prompt | `recall_context` | Zoek + geef contextberichten terug |
+| Prompt | `session_handoff` | Handoff-data tussen agents |
+| Prompt | `detect_patterns` | Analyseer terugkerende patronen |
+| Skill | `/recall` | Doorzoek geheugen |
+| Skill | `/remember` | Sla op in langetermijngeheugen |
+| Skill | `/session-history` | Recente sessiesamenvattingen |
+| Skill | `/forget` | Verwijder observaties/sessies |
+
+De tabel toont de vier kernskills. De volledige set is 9 aanroepbare skills plus 8 referentieskills; zie de sectie Native skills hierboven.
+
+### Standalone MCP
+
+Draai zonder de volledige server, voor elke MCP-client. Beide werken:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Of voeg toe aan de MCP-config van je agent:
+
+De meeste agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Voeg de `agentmemory`-entry samen met het bestaande `mcpServers`-object van je host, in plaats van het bestand te vervangen. Voor gesandboxte clients die de `localhost` van de host niet kunnen bereiken, voeg je `"AGENTMEMORY_FORCE_PROXY": "1"` toe aan het env-blok en stel je `AGENTMEMORY_URL` in op een route die de sandbox kan bereiken.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Kopieer het plugin-bestand uit de repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Start automatisch op poort `3113`. De viewer laadt één snapshot bij het verbinden (`GET /agentmemory/viewer/snapshot`) en past daarna live stream-events toe: nieuwe memories, lessen, observaties, audit-entries, graph-wijzigingen en health-updates verschijnen zonder polling of het herladen van de pagina. De enige andere verzoeken zijn de acties die je aanklikt, "load more"-pagina's en zoekopdrachten. Wanneer de stream wegvalt, toont de viewer hoe oud zijn cijfers zijn, maakt opnieuw verbinding met backoff en synchroniseert opnieuw vanaf één snapshot.
+
+- **12 tabbladen in vier groepen** met live aantallen, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), toetsenbordsneltoetsen en een mobiel menu.
+- **Memories:** server-side zoeken, filters op project, agent en type, een detailpaneel met de versieketen en een word-diff, provenance-links, kopieerknoppen voor de id, de MCP-aanroep en een curl-commando, bewerken (een nieuwe versie), forget met bevestiging, bulk-forget en JSON-export.
+- **Sessions:** een inline observatietijdlijn met leesbare tool-input en -output, filters en paginering, en de memories en lessen die elke sessie heeft opgeleverd.
+- **Graph:** zoeken, node-detail met relaties en bronnen, een legenda die niet alleen op kleur vertrouwt, en zoomregeling.
+- **Health:** de live versie van `GET /agentmemory/status`. Elk probleem komt met zijn oplossing, plus de state-backend, de save-status van de index, de voortgang van graph-provenance-compactie en een consolidatie-uitleg met de echte drempelwaarden.
+- **Audit-, Activity-, Profile-, Replay-, Lessons-, Actions- en Crystals**-pagina's, elk met een lege staat die vertelt wat de sectie is, waarom hij leeg is en welk commando hem vult, en een `?`-woordenlijsttooltip bij elke term en elk getal.
+
+```bash
+open http://localhost:3113
+```
+
+De viewer-server bindt standaard aan `127.0.0.1` en voegt het server-secret toe wanneer hij verzoeken doorstuurt naar de REST API, dus er is geen setup nodig. Het via REST geserveerde `/agentmemory/viewer`-endpoint volgt de normale bearer-token-regels en stuurt browsers zonder token door naar de viewer-poort. CSP-headers gebruiken een per-response script-nonce en schakelen inline handler-attributen uit (`script-src-attr 'none'`).
+
+---
+
+
+
+De viewer op `:3113` toont wat je agent **onthouden heeft**. De [iii console](https://iii.dev/docs/console) toont wat je agent **gedaan heeft**: elke memory-operatie als een OpenTelemetry-trace, elke KV-entry bewerkbaar, elke functie aanroepbaar, elke stream aftapbaar. Twee vensters op hetzelfde geheugen: één productvormig, één enginevormig.
+
+Zie een `memory_smart_search` afgaan en bekijk de BM25-scan → embedding-lookup → RRF-fusie → reranker als een waterfall. Bewerk een vastgelopen consolidatietimer in de KV-browser. Speel een `PostToolUse`-hook opnieuw af met een aangepaste payload. Pin de WebSocket-stream en bekijk observaties live binnenkomen.
+
+agentmemory levert dit gratis mee, omdat elke function call en trigger via iii loopt; niets custom, niets om te instrumenteren.
+
+
+
+
+ Workers-pagina: elke verbonden worker, inclusief agentmemory zelf, met PID, functietelling, runtime en laatst gezien.
+
+
+**Al geïnstalleerd.** De console wordt meegeleverd met de vastgezette `iii`-engine (0.22+); niets apart te installeren. De eerste start downloadt de console-binary naast de engine.
+
+**Starten naast agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Dit draait de `iii console` van de vastgezette engine tegen de poorten die agentmemory heeft opgelost (REST, streams, bridge) en serveert deze op één poort boven de viewer, standaard `http://localhost:3114`. `--console-port N` kiest een andere poort; `--port` en `--instance` selecteren de agentmemory-instantie op dezelfde manier als bij `stop`; elke andere flag wordt doorgegeven, bijvoorbeeld `--enable-flow` voor de experimentele architecture-graph-pagina.
+
+Hetzelfde handmatig, handig wanneer `agentmemory` niet op PATH staat:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Wat je kunt doen vanuit de console:**
+
+| Pagina | Gebruik dit om |
+|------|-----------|
+| **Workers** | Elke verbonden worker en zijn live metrics te zien, inclusief de agentmemory-worker zelf. |
+| **Functions** | Elke functie van agentmemory rechtstreeks aan te roepen met een JSON-payload; handig om `memory.recall`, `memory.consolidate`, `graph.query` te testen zonder een client te koppelen. |
+| **Triggers** | HTTP-, cron-, event- en state-triggers opnieuw af te spelen: de consolidatie-cron handmatig afvuren, een HTTP-route opnieuw proberen, een state-wijziging uitzenden. |
+| **States** | Een KV-browser met volledige CRUD over sessies, memory-slots, lifecycle-timers en de embeddings-index; waarden direct ter plekke bewerken. |
+| **Streams** | Live WebSocket-monitor voor memory-writes, hook-events en observatie-updates terwijl ze door iii-streams stromen. |
+| **Queues** | Durable queue-topics + dead-letter-beheer. Mislukte embedding-/compressiejobs opnieuw afspelen of verwijderen. |
+| **Traces** | OpenTelemetry waterfall-/flame-/service-breakdown-weergaven. Filter op `trace_id` om precies te zien welke functies, DB-aanroepen en embedding-aanvragen één `memory.search` opleverde. |
+| **Logs** | Gestructureerde OTEL-logs gefilterd en gecorreleerd aan trace-/span-ID's. |
+| **Config** | Runtime-configuratie: precies zien met welke workers, providers en poorten je engine draait. |
+| **Flow** | (Optioneel, `--enable-flow`) Interactieve architecture-graph van elke worker, trigger en stream. |
+
+
+
+
+ Traces: waterfall / flame / service-breakdown voor elke memory-operatie.
+
+
+**Traces staan al aan:**
+
+`iii-config.yaml` wordt geleverd met de `iii-observability`-worker ingeschakeld (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Geen extra config nodig; zodra agentmemory start, geeft elke memory-operatie een gestructureerde log die de console kan lezen, en één op de tien (`sampling_ratio: 0.1`) geeft ook een trace-span af.
+
+Als je in plaats daarvan wilt exporteren naar Jaeger/Honeycomb/Grafana Tempo, verander je `exporter: memory` in `exporter: otlp` en stel je het collector-endpoint in volgens de observability-documentatie van iii.
+
+> **Let op:** er wordt geen auth afgedwongen op de console zelf; houd deze gebonden aan `127.0.0.1` (de standaard) en stel hem nooit publiek bloot.
+
+---
+
+
+
+agentmemory is **al een draaiende [iii](https://iii.dev)-instantie**. Drie primitieven (worker, functie, trigger) stellen de runtime samen; KV-state, streams en OTEL-traces komen van de iii-state-, iii-stream- en iii-observability-workers die met iii meegeleverd worden. Je hebt geen Postgres, Redis, Express, pm2 of Prometheus geïnstalleerd, omdat iii die vervangt.
+
+Dat betekent dat één extra commando agentmemory uitbreidt met een volledig nieuwe functie.
+
+### agentmemory uitbreiden met meer workers
+
+De builtins die agentmemory nodig heeft, staan al in `iii-config.yaml` en starten ermee op: `iii-state` (KV), `iii-queue` (durable retries voor de event-subscribers), `iii-pubsub`, `iii-cron`, `iii-stream` en `iii-observability` (OTEL-traces, metrics en logs op elke functie). Alles anders uit het [iii worker-registry](https://workers.iii.dev) sluit aan op dezelfde engine: kopieer `iii-config.yaml` naar `~/.agentmemory/iii-config.yaml` (de CLI geeft de voorkeur aan dat bestand boven het gebundelde, en rendert nog steeds poorten en datapaden erin), voeg de entry toe, installeer de worker-runtime eenmalig met `~/.agentmemory/bin/iii update worker`, en herstart agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Wat je extra krijgt bovenop agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-backed state-adapter wanneer je de in-memory KV-standaardwaarden ontgroeit |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code die uit `memory_recall` komt, draait in een wegwerp-VM, niet in je shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Zet extra MCP-servers naast die van agentmemory, met dezelfde engine |
+
+Op engine 0.22.x houd je de `iii-`-voorvoegsel-namen aan voor de builtins hierboven; de entries zonder voorvoegsel (`http`, `state`, `queue`, `pubsub` en `cron`) zijn de standalone registry-workers waar agentmemory naar overstapt met de 0.23-migratie.
+
+Volledig registry: [workers.iii.dev](https://workers.iii.dev). Elke worker daar is samengesteld uit dezelfde primitieven die agentmemory gebruikt, en de agentmemory die je al hebt, is er één van.
+
+### Engine-config en bind-adres
+
+`agentmemory start` leest de engine-config vanuit het eerste bestand dat bestaat: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` in de huidige map, `~/.agentmemory/iii-config.yaml`, en dan het gebundelde `iii-config.yaml`. Bij elke start rendert het dat bestand (datapaden, poorten, state-backend) naar `~/.agentmemory/data/iii-config.runtime.yaml` en start het de engine met de gerenderde kopie, dus bewerk het bronbestand, niet het gerenderde. De `host:`-waarden van het bronbestand blijven zoals geschreven.
+
+Het gebundelde `iii-config.yaml` bindt met opzet aan `127.0.0.1`, en die standaard geldt ook binnen een container. Een CLI die in een container start, luistert op de loopback van de container, dus gepubliceerde poorten bereiken niets. Om een gecontaineriseerde CLI via gepubliceerde poorten te serveren, stel je `AGENTMEMORY_III_CONFIG` in op een config die bindt aan `0.0.0.0`. De gebundelde `iii-config.docker.yaml` is er zo een: deze bindt `iii-http`, `iii-stream` en de engine-poort aan `0.0.0.0` en bewaart state onder `/data`, dus mount daar een schrijfbaar volume. Houd `AGENTMEMORY_SECRET` ingesteld, en publiceer alleen de poorten die je nodig hebt, op `127.0.0.1` of achter een proxy die je vertrouwt.
+
+De `docker-compose.yml` van deze repo gaat niet via de config-lookup van de CLI: deze mount `iii-config.docker.yaml` op `/app/config.yaml`, en de `iii-engine`-container start met `--config /app/config.yaml`. De één-klik-[deploy-templates](../deploy/) schrijven hun eigen `0.0.0.0`-config in hun entrypoints.
+
+### Storage-backend: file (standaard) versus redis
+
+`iii-state` en `iii-stream` gebruiken standaard de bij iii-engine gebundelde file-based KV-store: één JSON-bestand per scope, gehouden in het geheugen van het engine-proces en op een timer terug naar disk geschreven. Dat is de juiste standaard voor een lokale installatie met één gebruiker; een gedeelde daemon met meerdere gelijktijdige writers krijgt in plaats daarvan echte per-key writes van Redis, tegen de prijs van een netwerk-round-trip per operatie (elke `state::*`-aanroep serialiseert nog steeds op één Redis-verbinding, dus dit ruilt het lock van de file store in voor een socket, niet voor parallellisme).
+
+Stel `AGENTMEMORY_STATE_BACKEND=redis` in (plus `AGENTMEMORY_REDIS_URL`) om beide workers over te schakelen naar de ingebouwde `redis`-adapter van iii-engine, die elke key opslaat als een Redis-hashveld (`HSET`) in plaats van een hele scope bij elke write te herschrijven:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` is standaard `file`; het niet instellen houdt het huidige gedrag ongewijzigd, en een niet-herkende waarde (iets anders dan `file` of `redis`) geeft een opstartfout in plaats van een stille fallback. `/agentmemory/status` en de Health-pagina van de viewer (de rij State store) melden welke backend actief is en of deze antwoordt, nooit de URL.
+
+**Alleen kale `redis://`.** De vastgezette engine (0.22.1) bouwt zijn Redis-client zonder TLS-ondersteuning, dus een `rediss://`-URL (de meeste managed Redis-aanbieders, zoals Upstash, Redis Cloud en ElastiCache met encryptie tijdens transport, staan standaard alleen TLS toe) kan niet verbinden. De verbinding is onversleuteld, dus het Redis-wachtwoord en elke opgeslagen memory gaan in leesbare tekst over de lijn: richt je op een lokale Redis of één op een privénetwerk dat je vertrouwt. Voor elke andere Redis draai je een versleutelde tunnel (stunnel, SSH, of een VPN) op de agentmemory-host, zodat de kale `redis://`-hop op die host blijft en de upstream-verbinding van de tunnel versleuteld en geauthenticeerd is. Als een Redis-wachtwoord een enkel aanhalingsteken bevat, percent-encode je dit (`%27`); de engine breidt de URL uit in zijn YAML-config voordat deze geparsed wordt.
+
+**Eén Redis-server per `--instance`.** De Redis-keyvoorvoegsels van de engine (`state:`, `stream::`) zijn vast, dus twee agentmemory-instanties (`--instance 1`, `--instance 2`, ...) die naar dezelfde database wijzen, overschrijven elkaars data. Een aparte database-index (`redis://localhost:6379/1`) houdt de opgeslagen data apart, maar de engine relayt live viewer-events over één Redis-pub/sub-kanaal (`stream::events`), en Redis-pub/sub negeert de database-index, dus de viewer van elke instantie zou nog steeds de live events van de andere laten zien. Geef elke instantie zijn eigen Redis-server (of poort) wanneer je er meer dan één draait.
+
+**Wat gelijk blijft, en wat verschilt.** Elke functie van agentmemory werkt op Redis: sessions, observaties, memories (remember, supersede, evolve, forget), zoeken en de index-buckets, lessen, de graph, de audit-log en zijn maandelijkse scopes, export en import, governance-deletes, consolidatiestatus, de viewer-snapshot en zijn live stream, en de health-monitor. De engine bewaart elke scope als één Redis-hash (`HSET`/`HGET`/`HGETALL`) en vuurt dezelfde state-triggers af als de file store. Drie engine-verschillen worden binnen agentmemory opgevangen:
+
+- Redis geeft de records van een scope terug in geen vaste volgorde. agentmemory sorteert ze oudste eerst (op de aanmaaktijd in de record-id, dan het timestamp), zodat lijsten, paginering en export-chunks in dezelfde volgorde terugkomen als bij de file store.
+- De engine past partiële updates op Redis toe in een Lua-script dat lege arrays omzet in lege objecten. agentmemory past die updates zelf toe (lezen, wijzigen, schrijven onder een per-key lock) op Redis, zodat velden zoals `tags: []` arrays blijven.
+- De legacy audit-log-check leest de oude scope van Redis in plaats van te zoeken naar het bestand van de file store op disk.
+
+Eén verschil vraagt actie van jou: **nadat Redis herstart, stopt de engine met het relayen van live events** naar de viewer totdat agentmemory herstart. Data wordt nog steeds normaal opgeslagen en gelezen. De health-monitor stuurt elke 30 seconden een testevent via Redis; als dit niet terugkomt, tonen `/agentmemory/status` en de Health-pagina van de viewer "Live updates are not reaching the viewer" met de oplossing: herstart agentmemory. Als Redis down is, toont het statusrapport "The state store is not answering" en hoe je dit controleert (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Een zeer grote scope opvragen leest de hele hash in één `HGETALL`, dezelfde kost als wanneer de file store dit in het geheugen houdt.
+
+**Aanbevolen Redis-instellingen.** Het standaard snapshotbeleid `save 3600 1 300 100 60 10000` kan bij een crash minuten aan writes verliezen, erger dan het flush-venster van 5s van de file store. Stel `appendonly yes` in voor alles wat je niet wilt verliezen. Stel `maxmemory-policy noeviction` in; `allkeys-lru` of vergelijkbaar laat stilletjes memories vallen zodra Redis zijn geheugenlimiet bereikt.
+
+Een native (niet-Docker) start, en elke één-klik-[deploy-template](../deploy/) (die overschrijven het gebundelde `iii-config.yaml` en starten native), lezen `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` en renderen die in de gestarte `iii-config`. De URL zelf wordt nooit naar dat gerenderde bestand geschreven, alleen een `${AGENTMEMORY_REDIS_URL}`-referentie die het engine-proces bij het opstarten uit zijn eigen omgeving uitbreidt. Alleen het eigen Docker-Compose-pad van deze repo (`AGENTMEMORY_USE_DOCKER=1`, of het hervatten van een engine die al zo gestart is) mount `iii-config.docker.yaml` read-only en rendert nooit; `agentmemory start` waarschuwt wanneer het die combinatie detecteert. Wijzig dat bestand handmatig, volgens dezelfde `name: redis` / `config: redis_url: ...`-vorm die getoond wordt in de [iii-state](https://workers.iii.dev/workers/iii-state)- en [iii-stream](https://workers.iii.dev/workers/iii-stream)-workerdocumentatie, en richt `redis_url` op een Redis die bereikbaar is vanuit de container. `docker-compose.yml` geeft `AGENTMEMORY_REDIS_URL` door aan de engine-container, dus `redis_url: '${AGENTMEMORY_REDIS_URL}'` werkt daar en houdt de URL buiten het gemounte bestand.
+
+De gerenderde config houdt de URL buiten `~/.agentmemory/data/iii-config.runtime.yaml`, maar de eigen configuration-worker van de engine bewaart de *uitgebreide* waarde nog steeds naar `~/.agentmemory/config/iii-state.yaml` en `iii-stream.yaml` zodra deze opstart (de `${VAR}`-expansie van iii-engine gebeurt voordat die worker zijn seed opslaat, en hij slaat de opgeloste waarde op, niet de referentie). Behandel die map alsof hij een credential bevat: `chmod 700 ~/.agentmemory` op elke gedeelde host, en geef de voorkeur aan een Redis-ACL-gebruiker die beperkt is tot wat agentmemory nodig heeft, boven de adminreferenties van de database.
+
+**Migratie gaat niet automatisch.** Het wisselen van `AGENTMEMORY_STATE_BACKEND` begint aan beide kanten met een lege store; niets kopieert bestaande data van file naar Redis of terug. Exporteer vanuit de backend die je verlaat en importeer in degene waar je naartoe gaat. Dit draait identiek onder bash en zsh (inclusief `bash -u`). Een array zoals `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` doet dat niet: zsh houdt de header als één misvormd woord, waar bash hem in twee splitst, waardoor beide verzoeken een 401 krijgen zodra `AGENTMEMORY_SECRET` is ingesteld:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` accepteert ook `?maxSessions=` en `?offset=` om een groot corpus over meerdere aanroepen te verdelen; `strategy` bij import is `merge` (standaard-veilig), `replace`, of `skip`.
+
+### Wat iii vervangt
+
+| Traditionele stack | agentmemory gebruikt |
+|---|---|
+| 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-supervisie |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Custom plugin-systemen | `iii worker add ` |
+
+**225 bronbestanden · ~54,000 LOC · 2,600+ tests · 312 functies · 66 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
+
+---
+
+
+
+### LLM-providers
+
+agentmemory detecteert providers automatisch vanuit je environment. Een provider maakt LLM-ondersteunde operaties beschikbaar, maar het configureren van een provider alleen schakelt LLM-geschreven compressie van observaties niet in. Dat pad vereist zowel een provider als `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Provider | Config | Opmerkingen |
+|----------|--------|-------|
+| **No-op (standaard)** | Geen config nodig | LLM-ondersteund compress/summarize is uitgeschakeld. Synthetic compressie en BM25-recall werken nog steeds. Zie `AGENTMEMORY_ALLOW_AGENT_SDK` hieronder als je vroeger vertrouwde op de Claude-abonnement-fallback. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Facturering per token |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatibel |
+| Gemini | `GEMINI_API_KEY` | Schakelt ook embeddings in |
+| OpenRouter | `OPENROUTER_API_KEY` | Elk model |
+| OpenAI API | `OPENAI_API_KEY` | Standaard `gpt-5.6-luna`, overschrijf met `OPENAI_MODEL` |
+| **Lokaal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) of `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Alles wat OpenAI-API-compatibel is. Geen kosten, draait op je eigen hardware. Zie [Local models](#local-models-ollama--lm-studio--vllm) hieronder. |
+| Claude-abonnement-fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Alleen opt-in. Spawnt `@anthropic-ai/claude-agent-sdk`-sessies; dit veroorzaakte vroeger onbegrensde Stop-hook-recursie, dus het is niet langer de standaard. |
+
+### Local models (Ollama / LM Studio / vLLM)
+
+agentmemory praat met elke OpenAI-API-compatibele server, dus alles dat `/v1/chat/completions` blootstelt werkt zonder codewijzigingen. Geen betaalde keys, geen cloud, geen rate limits; draait volledig op je eigen hardware.
+
+**Ollama** (standaardpoort `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (standaardpoort `1234`):
+
+Open LM Studio → tabblad Local Server → Start Server. Kies een willekeurig chatmodel uit de kiezer (Qwen 3, gpt-oss, DeepSeek R1, enz.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: zelfde vorm. Richt `OPENAI_BASE_URL` op welke URL je server ook blootstelt en stel `OPENAI_MODEL` in op een naam die je server accepteert.
+
+**Modelkeuzes voor memory-werk**: compressie en samenvatting zijn korte taken (<2K tokens in, <500 tokens uit) waarbij een 7B instruct-model ruim voldoende is. Aanbevelingen:
+
+| Model | Grootte | Waarom |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Gebalanceerde standaard op een 16 GB-machine; sterk in extractie en tool-vormige tekst |
+| `qwen3:4b` | ~2.6 GB | Kleinste zinnige optie; prima voor compressie, zwakker bij graph-extractie |
+| `qwen3-coder:30b` | ~19 GB | Beste lokale keuze voor code-vormige sessies (30B MoE, 3.3B actief) op 24-32 GB hardware |
+| `gpt-oss:20b` | ~14 GB | Sterk algemeen model dat past binnen 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning-distillatie; trager maar schonere extracties |
+
+Qwen 3-modellen denken standaard en kunnen het hele tokenbudget opbranden aan reasoning voordat er output is. Stel `AGENTMEMORY_LLM_NOTHINK=1` in om `/no_think` toe te voegen aan graph-extractie-prompts, en verhoog `MAX_TOKENS` (16384 werkt) als extracties leeg terugkomen.
+
+Reasoning-modellen (`o1`-achtig met ``-blokken) kunnen een lege `content` teruggeven met een `reasoning`-veld dat je lokale server mogelijk niet toont. Als extracties leeg terugkomen, schakel dan eerst over naar een niet-reasoning-model. De env `OPENAI_REASONING_EFFORT=none` kan ook thinking uitschakelen bij Ollama Cloud thinking-modellen die het OpenAI-reasoning-schema spiegelen.
+
+Lokale embeddings worden als optionele dependency meegeleverd, maar zijn niet standaard ingeschakeld. Stel `EMBEDDING_PROVIDER=local` in om in te stappen op `Xenova/all-MiniLM-L6-v2` (384-dim). De eerste embedding-aanvraag downloadt het model; inference gebeurt daarna op het eigen apparaat. Zonder die instelling of een remote embedding-key blijven vectoren uitgeschakeld, gebruikt `mem::search` BM25, en kan `smart-search` nog steeds bestaande graph-matches toevoegen.
+
+### Kostenbewuste modelkeuze
+
+Wanneer LLM-geschreven achtergrondcompressie ingeschakeld is met zowel een provider als `AGENTMEMORY_AUTO_COMPRESS=true`, draait dit op elke observatie, dus modelkeuze verandert de maandelijkse uitgaven merkbaar. Vastgelegde workload-data: 635 requests / 888K tokens / 35 uur actief gebruik, gedraaid tegen drie OpenRouter-modellen op prijzen van 2026-05-23.
+
+| Tier | Model | Input / 1M | Output / 1M | Kosten voor de vastgelegde 35h | Opmerkingen |
+|------|-------|------------|-------------|---------------------------|-------|
+| Aanbevolen | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (geschat) | Nieuwste DeepSeek; goedkoopste aanbevolen keuze voor compressie-workloads. |
+| Aanbevolen | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solide compressie- + samenvattingskwaliteit tegen ~10× lagere kosten dan Sonnet. |
+| Aanbevolen | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Sterke code-reasoning als je sessies sterk code-vormig zijn. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (geschat) | Zelfde catalogusprijs als de gemeten Sonnet-4.6-run; introductieprijs $2/$10 tot en met 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (geschat) | Vlaggenschip-tier; duur voor altijd-aan achtergrondwerk. |
+| Vermijden | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (geschat) | Vlaggenschip-klasse model; overkill voor compressie. |
+
+Gemeten rijen komen uit de vastgelegde run; (geschat)-rijen schalen dezelfde tokenmix met de catalogusprijs van elk model.
+
+agentmemory print een runtime-waarschuwing wanneer `OPENROUTER_MODEL` overeenkomt met een premium-tier-patroon. Stel `AGENTMEMORY_SUPPRESS_COST_WARNING=1` in om dit te onderdrukken zodra je een geïnformeerde keuze hebt gemaakt.
+
+Afweging kwaliteit versus kosten voor memory-werk: compressie is een samenvattingstaak met relatief losse kwaliteitseisen (de agent leest de samenvatting opnieuw, niet de gebruiker). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder liggen bij deze taak binnen de afrondingsmarge van Sonnet, terwijl ze 10-70× minder kosten. Bewaar de premium-tier-modellen voor queries die jij zelf direct leest.
+
+Bronnen: [OpenRouter-prijzen voor Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-prijsnotities](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+In multi-agent-opzetten waarbij meerdere rollen één agentmemory server delen (architect / developer / reviewer / researcher / support-agent), tagt `AGENT_ID` elke write met de rol die deze maakte. `AGENTMEMORY_AGENT_SCOPE` bepaalt of recall op die tag filtert.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Twee modi:
+
+| Modus | Tagt writes | Filtert recall | Wanneer te gebruiken |
+|------|------------|---------------|-------------|
+| `shared` (standaard) | ja | nee | Cross-agent context met audit trail. De architect kan zien wat de developer noteerde, maar elke rij legt vast wie het zei. |
+| `isolated` | ja | ja | Strikte scheiding. De architect ziet nooit de observaties / memories / sessies van de developer. |
+
+Wat getagd wordt wanneer `AGENT_ID` is ingesteld: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. De rol stroomt van `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Wat gefilterd wordt in isolated-modus: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Elk endpoint accepteert `?agentId=` om per request te overschrijven, en `?agentId=*` om volledig uit de env-scope te stappen. `/memories` accepteert ook `?includeOrphans=true` om memories van vóór AGENT_ID te tonen waarvan `agentId` undefined is.
+
+Override per aanroep op de SDK-/REST-laag: elk muterend endpoint (`/session/start`, `/remember`) accepteert een `agentId`-veld in de request body dat voorrang heeft op de env. Handig voor runtimes die veel rollen door één serverproces routeren. De MCP-tool `memory_save` biedt hetzelfde `agentId`-veld, de standalone stdio-server geeft zowel `agentId` als `project` door, en opgeslagen memories dragen `agentId` mee de zoekindex in, zodat agent-scoped zoeken zowel memories als observaties dekt.
+
+Wanneer `AGENT_ID` niet is ingesteld, blijft memory unscoped (legacy-gedrag, geen tags, geen filters).
+
+### Poorten
+
+agentmemory + iii-engine binden standaard aan vier poorten. Als een herstart mislukt met `port in use`, vertelt deze tabel je welk proces je moet zoeken.
+
+| Poort | Proces | Doel | Env-override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Interne streams-worker (gebruikt door agentmemory + viewer) | `III_STREAM_PORT` (voorkeur) of legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Realtime viewer (`http://localhost:3113`) | `III_VIEWER_PORT` of `AGENTMEMORY_VIEWER_URL` voor de gerapporteerde URL |
+| `49134` | iii-engine | WebSocket; workers registreren hier, OTel-telemetrie loopt erover | `III_ENGINE_PORT` of `III_ENGINE_URL` |
+
+`--port ` wijzigt het REST-ankerpunt en leidt streams `N+1`, viewer `N+2`, en engine-WebSocket `N+46023` af, maar alleen waar de bijbehorende expliciete poort of URL hierboven niet is ingesteld. Dit creëert geen geïsoleerde lifecycle-namespace. Gebruik `--instance 1` voor een tweede daemon; deze gebruikt ankerpunt 3211, standaard `3211/3212/3213/49234`, en krijgt een eigen `instance-1`-map voor data en lifecycle. Instanties 1 tot en met 50 volgen hetzelfde patroon.
+
+De vastgezette engine start met `--no-update-check` (geen update- of security-advisory-lookups bij GitHub tijdens het opstarten) en met de anonieme gebruikstelemetrie van iii uit: agentmemory stelt `III_TELEMETRY_ENABLED=false` in voor de engine die het spawnt, tenzij je de variabele zelf exporteert, en het gebundelde compose-bestand doet hetzelfde.
+
+Opruimen van verweesde processen wanneer poorten gebonden blijven na een gecrashte run:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` ruimt zowel de worker als het pidfile van de engine netjes op bij een nette native shutdown. In Docker-modus flusht het de native worker, stopt het precies de gevalideerde engine-container, en behoudt het zowel de container als zijn `/data`-mount voor een lossless herstart; de volgende start valideert en hervat diezelfde container. Docker-gebaseerde uninstall vereist `agentmemory remove --keep-data`: dit verwijdert gedeelde door agentmemory beheerde bestanden met behoud van de gevalideerde container, zijn datamount, en het lifecycle-record dat nodig is om ze te herstellen. Destructieve verwijdering van Docker-data is bewust overgelaten aan de operator, na een backup. De CLI weigert ook om Docker- of VM-poorthouders (Docker-backend, vpnkit, colima) als de native engine te adopteren of te signaleren, tenzij `--force` is doorgegeven. De handmatige opruiming hierboven is alleen voor het geval na een crash waarbij geen van beide pidfiles achterblijft.
+
+### Configuratiebestand
+
+Zet de runtime-configuratie van agentmemory in `~/.agentmemory/.env` in plaats van variabelen in elke shell te exporteren. Als de viewer een setup-hint toont zoals `export ANTHROPIC_API_KEY=...`, kopieer je deze naar dit bestand als `ANTHROPIC_API_KEY=...` zonder het `export`-voorvoegsel, en herstart je dan agentmemory.
+
+Environment-variabelen van het proces werken nog steeds en krijgen voorrang boven waarden in het bestand.
+
+Op Windows leeft hetzelfde bestand op `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Om te testen met een Claude Code Pro/Max-abonnement in plaats van een API-key, stap je er expliciet in:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM-geschreven compressie van observaties vereist beide regels: toegang tot een LLM-provider (inclusief deze expliciete abonnement-fallback) en `AGENTMEMORY_AUTO_COMPRESS=true`. Een provider alleen laat het standaard synthetic-compressiepad ongewijzigd.
+
+Consolidatie (graph-nodes, lessen, crystals) staat standaard aan zodra een LLM-provider geconfigureerd is. Stap er expliciet uit met `CONSOLIDATION_ENABLED=false` als je LLM-vrije werking wilt. Graph-extractie is een aparte flag:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Environment-variabelen
+
+Maak `~/.agentmemory/.env` aan:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoints op poort `3111`. De REST API bindt standaard aan `127.0.0.1`. Beschermde endpoints vereisen `Authorization: Bearer `, en mesh-sync-endpoints vereisen een expliciet ingestelde `AGENTMEMORY_SECRET` op beide peers.
+
+**Authenticatie staat standaard aan.** Wanneer `AGENTMEMORY_SECRET` niet is ingesteld (in de shell of in `~/.agentmemory/.env`), genereert de server bij de eerste start een willekeurig secret en bewaart dit in `~/.agentmemory/secret` met modus `0600`. Elke gebundelde client leest dit vandaar wanneer hij met een lokale server praat: de CLI, de viewer, de hooks onder `plugin/scripts`, de MCP-server en de `@agentmemory/mcp`-shim, de configs geschreven door `agentmemory connect`, en de gebundelde OpenCode-, Pi-, OpenClaw-, Hermes- en filesystem-watcher-integraties. Het opgeslagen secret wordt alleen verstuurd naar loopback-URL's (`localhost`, `127.0.0.0/8`, `::1`). Een expliciete `AGENTMEMORY_SECRET` wint altijd, en remote clients moeten deze nog steeds instellen. Docker en de `deploy/`-entrypoints genereren en exporteren al hun eigen secret. Om de API handmatig aan te roepen:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Verzoekregels voor writes.** `POST`-, `PUT`-, `PATCH`- en `DELETE`-verzoeken naar de REST API en de viewer moeten `Content-Type: application/json` versturen (een `charset`-parameter is prima) wanneer ze een body dragen, en een `Origin`-header, indien aanwezig, moet een loopback-origin zijn voor de geconfigureerde REST- of viewer-poort, of vermeld staan in `VIEWER_ALLOWED_ORIGINS` (komma-gescheiden, bijv. `https://memory.example.com`). Clients die geen `Origin`-header versturen (CLI, hooks, MCP, curl, server-naar-server) zijn hier niet door geraakt. De viewer accepteert ook zijn eigen origin.
+
+**Bestandspaden.** Endpoints die bestanden lezen of schrijven (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) accepteren alleen paden onder `~/.agentmemory`, de instance-datamap, of een map vermeld in `AGENTMEMORY_IMPORT_ROOT` (meerdere scheiden met `:`, of `;` op Windows). `/replay/import-jsonl` accepteert ook zijn standaard `~/.claude/projects`. `/obsidian/export` blijft binnen `AGENTMEMORY_EXPORT_ROOT` en `/migrate` binnen `~/.agentmemory`. Symlinks worden opgelost vóór elke check.
+
+**Secret-scrubbing.** API-keys, bearer tokens, PEM-private-key-blokken en credentials die in URL's zitten (`scheme://user:password@host`) worden geredigeerd voordat tekst wordt opgeslagen, op elk schrijfpad: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl-replay, mesh-sync, team-shares, compressie- en summary-output, crystals en graph-nodes.
+
+
+Belangrijkste endpoints
+
+| Methode | Pad | Beschrijving |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health-check (altijd publiek) |
+| `GET` | `/agentmemory/status` | Wat er mis is en hoe je het oplost (HTML voor browsers, anders JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Alles wat de viewer toont, in één response |
+| `POST` | `/agentmemory/session/start` | Start sessie + haal context op |
+| `POST` | `/agentmemory/session/end` | Beëindig sessie |
+| `POST` | `/agentmemory/observe` | Leg observatie vast (zie capture-levering hieronder) |
+| `GET` | `/agentmemory/capture` | Capture-inbox, dead letters en offline spool |
+| `POST` | `/agentmemory/capture/retry` | Probeer dead-letter-captures opnieuw |
+| `POST` | `/agentmemory/capture/drain` | Stuur de lokale offline spool nu |
+| `POST` | `/agentmemory/smart-search` | Hybride zoeken |
+| `POST` | `/agentmemory/context` | Genereer context |
+| `POST` | `/agentmemory/remember` | Sla op in langetermijngeheugen |
+| `POST` | `/agentmemory/forget` | Verwijder observaties |
+| `POST` | `/agentmemory/enrich` | Bestandscontext + memories + bugs |
+| `GET` | `/agentmemory/profile` | Projectprofiel |
+| `GET` | `/agentmemory/export` | Exporteer alle data |
+| `POST` | `/agentmemory/import` | Importeer vanuit JSON |
+| `POST` | `/agentmemory/graph/query` | Knowledge-graph-query |
+| `POST` | `/agentmemory/graph/compact` | Trim overmatige graph-provenance |
+| `POST` | `/agentmemory/team/share` | Deel met team |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Volledige endpointlijst: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Capture-levering.** Hooks sturen elke observatie één keer naar `POST /agentmemory/observe` met een `eventId`. Dit is de eigen id van de host voor de aanroep wanneer de payload er één heeft (bijvoorbeeld de `tool_use_id` van Claude Code), anders een hash van de sessie, hooktype, toolnaam, input, output en host-timestamp. De server schrijft het event naar een capture-inbox in de state store, slaat de observatie op, en verwijdert dan de inbox-entry. De statuscode zegt wat er gebeurd is:
+
+| Status | `status`-veld | Betekenis |
+|---|---|---|
+| `201` | `accepted` | Opgeslagen. `observationId` is de nieuwe observatie. |
+| `202` | `accepted` (`state: "retrying"`) | Geaccepteerd, maar opslaan mislukte. De server probeert het opnieuw, ook na een herstart. |
+| `200` | `duplicate` | Deze `eventId` was al geaccepteerd. `observationId` is de bestaande observatie; er wordt niets nieuws opgeslagen. |
+| `400` / `422` | `rejected` | Ongeldige payload, of opslaan mislukte definitief (het event wordt bewaard als dead letter). |
+| `503` | `rejected` (`retryable: true`) | De inbox is vol (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks spoolen het event en versturen het later. |
+
+Mislukte events worden elke `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) opnieuw geprobeerd met verdubbelende backoff, tot `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Events die nog steeds mislukken blijven als dead letters in de inbox staan, worden vermeld op `/agentmemory/status` en de Health-pagina van de viewer, en kunnen opnieuw geprobeerd worden met `POST /agentmemory/capture/retry` (`{"eventId": "..."}` of `{"all": true}`). Geaccepteerde event-id's worden onthouden voor `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 uur, maximaal `AGENTMEMORY_CAPTURE_EVENTS_MAX` id's), zodat een hook die na een timeout of herstart opnieuw afgespeeld wordt, één keer wordt opgeslagen, terwijl twee afzonderlijke tool calls met hun eigen host-id's twee keer worden opgeslagen, ook als hun inhoud identiek is. Wanneer een observatie wordt verwijderd (forget, sessie-delete, eviction, auto-forget of een import die de store vervangt), wordt het event als verwijderd gemarkeerd voordat de observatie verdwijnt, zodat het opnieuw afspelen van dat event binnen hetzelfde venster beantwoord wordt als duplicate en niets opslaat. De state store schrijft elke 2 seconden naar disk, dus een beantwoord event kan nog even alleen in het geheugen staan. Om dat te dekken draagt elk `2xx`-antwoord ook de `bootId` van de server (nieuw bij elke start), `acceptedAt` en `durableAfterMs` (het save-interval plus 1.5 s op de file store, 1.5 s op redis, waar persistentie de instelling van de operator is). Hooks houden het event in de lokale spool totdat dat venster verstreken is en verwijderen het bij een latere aanroep zonder een extra request. Als de `bootId` inmiddels veranderd is, is de server herstart, dus stuurt de hook het event opnieuw met dezelfde `eventId`; een event dat de disk al bereikt had, wordt niet twee keer opgeslagen. De server stuurt zulke events ook zelf bij het opstarten en bij elk retry-interval, zodat een herstart niets verliest, zelfs als er daarna geen hook meer draait. Oudere hooks negeren de extra velden, en nieuwe hooks tegen een oudere server verwerpen het event bij `2xx` zoals voorheen.
+
+Wanneer de server down is, niet op tijd antwoordt, of een 5xx teruggeeft, voegt de hook de observatie toe aan een lokaal spool-bestand, `/capture-spool/-.jsonl` (overschrijf de map met `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Het bestand is privé voor je gebruiker (modus 600), secrets worden op dezelfde manier geredigeerd als de server ze redigeert, het bevat maximaal `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) en laat entries vallen die ouder zijn dan `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Wanneer het vol is, worden nieuwe entries verwijderd en geteld, en rapporteert `/agentmemory/status` dit. De hook sluit nog steeds af met 0 binnen zijn tijdslimiet en voegt geen request toe wanneer de server gezond is. De spool wordt verstuurd bij de volgende start en door de eerste hook die de server weer bereikt, in een achtergrondproces zodat de agent niet wacht. Event-id's maken dit veilig: een observatie die al aankwam vóór een timeout wordt niet twee keer opgeslagen. `npx @agentmemory/agentmemory capture` toont de spool en de server-inbox, `--drain` stuurt de spool nu, en `GET /agentmemory/capture` geeft hetzelfde terug als JSON. Stel `AGENTMEMORY_CAPTURE_SPOOL=false` in om de spool uit te zetten.
+
+**Graph-provenance compacten.** Elke knowledge-graph-node en -edge houdt de id's van de nieuwste 32 observaties bij waar hij vandaan komt. Stores geschreven vóór die cap kunnen duizenden id's per hot node bevatten, wat graph-zoeken en de viewer traag maakt of de worker laat vallen. agentmemory herstelt dit zelf: bij de eerste start na een upgrade trimt het elke node, edge, vervangen edge (de temporele graph-geschiedenis) en de gecachte snapshot tot de cap, op de achtergrond, in kleine stukken met een pauze ertussen, zodat zoeken, capture en de viewer blijven werken. Het bewaart zijn voortgang, hervat na een herstart en draait nooit opnieuw zodra het klaar is. `/agentmemory/status` en de Health-pagina van de viewer tonen het als pending, running (met de huidige scope en positie), done of failed. Stel `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` in om dit uit te zetten.
+
+Om het handmatig te draaien, roep je `POST /agentmemory/graph/compact` aan. Het loopt door de name- en edge-key-indexen in plaats van elke node en edge op te lijsten, en is veilig om opnieuw te draaien. Wanneer het id's trimt, schrijft het een `graph_compact`-audit-entry.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Draai het op een grote store, of wanneer de aanroep 504 teruggeeft, in stukken. Stuur `scope` (`nodes`, `edges` of `history`), `offset` en `limit`, en roep het dan opnieuw aan met de teruggegeven `nextOffset` totdat deze `null` is. Doe dit voor `nodes`, `edges` en `history`, en sluit af met één `{"scope":"snapshot"}`-aanroep, omdat een gestukte run de gecachte snapshot niet aanraakt.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Vereisten:** Node.js >= 20 met npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 of Docker. De automatische engine-installatie op macOS/Linux vereist ook `curl`, een POSIX `sh` en `tar`; native Windows gebruikt de handmatig vastgezette `iii.exe`, WSL2, of Docker Desktop.
+
+
+
+ Twój agent kodujący pamięta wszystko. Koniec z tłumaczeniem wszystkiego od nowa.
+ Zbudowany na iii engine
+
+ Trwała pamięć dla Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode i każdego klienta MCP.
+
+ Gist rozszerza wzorzec LLM Wiki Karpathy'ego o ocenę ufności, cykl życia, grafy wiedzy i wyszukiwanie hybrydowe: agentmemory jest tą implementacją.
+
+
+---
+
+## Install
+
+Wymagania:
+
+- Node.js 20 lub nowszy wraz z npm i npx (`node -v`, `npm -v` i `npx -v`).
+- Automatyczna instalacja iii-engine na macOS/Linux wymaga również `curl`, POSIX-owego `sh` oraz `tar`. Minimalne obrazy, takie jak `node:20-slim`, mogą ich nie zawierać.
+- Natywny Windows wymaga ręcznej instalacji przypiętej wersji iii-engine v0.22.1, czyli `iii.exe`. Pozostałymi wspieranymi ścieżkami są WSL2 lub Docker Desktop.
+
+Kanoniczna komenda do świeżej instalacji:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Pierwsze uruchomienie to interaktywna konfiguracja: wybierasz agentów do podłączenia (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), wybierasz dostawcę LLM albo zostajesz w trybie bez klucza, po czym narzędzie tworzy konfigurację, uruchamia serwer pamięci wraz z przypiętym silnikiem iii i proponuje instalację globalną, dzięki której sama komenda `agentmemory` działa potem wszędzie. `-y` akceptuje monit npx dotyczący pakietu, a `@latest` zapobiega użyciu nieaktualnej wersji z pamięci podręcznej. Dostawca LLM udostępnia funkcje oparte na LLM, ale kompresja obserwacji zapisywana przez LLM uruchamia się tylko wtedy, gdy ustawiono również `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Tryb bez klucza wyłącza wektorowe embeddingi. `memory_recall` (ścieżka `mem::search`) korzysta z BM25, natomiast `memory_smart_search` może dodatkowo łączyć strukturalne dopasowania z grafu, jeśli dane grafu już istnieją. Aby bezpłatnie włączyć semantyczne przywołanie lokalnie na urządzeniu, ustaw `EMBEDDING_PROVIDER=local` w `~/.agentmemory/.env` i zrestartuj. Pierwsze żądanie embeddingu pobiera `Xenova/all-MiniLM-L6-v2`; po tym początkowym pobraniu modelu wnioskowanie działa już lokalnie.
+
+Lokalne środowisko wykonawcze korzysta z czterech portów: `3111` dla REST/MCP HTTP, `3112` dla strumieni iii, `3113` dla podglądu i `49134` dla WebSocketu workera iii. Trwały stan iii znajduje się w `~/Library/Application Support/agentmemory` na macOS, `$XDG_DATA_HOME/agentmemory` lub `~/.local/share/agentmemory` na Linuksie oraz `%APPDATA%\agentmemory` na Windows. Użyj `--data-dir ` lub `AGENTMEMORY_DATA_DIR`, aby to nadpisać, i używaj tej samej wartości przy każdym restarcie. Dla zgodności ze starszymi wersjami istniejący `./data/state_store.db` lub `./data/iii-config.yaml` ma pierwszeństwo przed domyślną ścieżką platformy dla instancji 0; wyraźnie podana flaga lub zmienna środowiskowa nadal wygrywa.
+
+Następnie udowodnij, że przywołanie działa, i daj swojemu agentowi jego skille:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Wyszukiwania po słowach kluczowych powinny trafiać w domyślnym trybie bez klucza za pomocą BM25. Zapytanie demo `database performance optimization` jest celowo semantyczne i może zwrócić zero wyników, dopóki nie skonfigurujesz dostawcy embeddingów.
+
+Chcesz, aby całą robotę wykonał agent kodujący? Podaj mu jedną instrukcję:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Możesz podłączyć więcej agentów w każdej chwili za pomocą `agentmemory connect ` — 20 adapterów wymienionych w sekcji [Works with every agent](#works-with-every-agent). Pełne zestawienie komend znajdziesz w sekcji [Quick Start](#quick-start).
+
+
+Windows
+
+Najprostszą ścieżką jest WSL2. Natywna konfiguracja silnika na Windows wymaga ręcznego pobrania przypiętego pliku ZIP v0.22.1 i wypakowania `iii.exe`; CLI nie robi tego automatycznie. Wspierany jest również Docker Desktop. Zobacz [sekcję Windows](#windows), aby uzyskać instrukcje krok po kroku.
+
+
+
+
+Instalacja globalna / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Powyższa komenda npx pozostaje kanoniczną ścieżką świeżej instalacji i pozwala uniknąć problemów z uprawnieniami do globalnego prefiksu.
+
+
+
+
+npx serwuje starą wersję
+
+npx buforuje dane w podziale na wersje. Wymuś najnowszą wersję za pomocą `npx -y @agentmemory/agentmemory@latest` albo wyczyść pamięć podręczną jednorazowo komendą `rm -rf ~/.npm/_npx` (macOS/Linux; na Windows usuń `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Masz już uruchomiony własny silnik iii
+
+agentmemory przypina iii-engine do wersji v0.22.1 i nie podłączy się do innej wersji (worker nie mówi protokołem innego silnika). Zatrzymaj inny silnik, a następnie uruchom `npx -y @agentmemory/agentmemory@latest`. Zainstaluje i uruchomi przypiętą wersję v0.22.1 w `~/.agentmemory/bin`, nie dotykając twojego własnego `iii`.
+
+
+
+---
+
+
+
+agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST API. Wszyscy agenci współdzielą ten sam serwer pamięci.
+
+
+
+OpenHuman
+natywny backend oparty na trait Memory
+
+
+
+
+
+Gemini CLI
+serwer MCP
+
+
+
+Antigravity
+MCP + hooki
+
+
+
+Claude Desktop
+serwer MCP
+
+
+
+Warp
+connect + MCP + skille
+
+
+
+Zed
+serwer MCP
+
+
+
+
+
+Cline
+serwer MCP
+
+
+
+Continue
+serwer MCP
+
+
+
+Droid
+serwer MCP
+
+
+
+Kiro
+serwer MCP
+
+
+
+Qwen Code
+serwer MCP
+
+
+
+
+
+DeepSeek Harness
+serwer MCP
+
+
+
+Roo Code
+serwer MCP
+
+
+
+Kilo Code
+serwer MCP
+
+
+
+Goose
+serwer MCP
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Współpracuje z każdym agentem mówiącym w MCP lub HTTP. Jeden serwer, wspomnienia współdzielone między wszystkimi.
+
+
+---
+
+Przy każdej sesji tłumaczysz tę samą architekturę od nowa. Odkrywasz te same błędy po raz kolejny. Uczysz agenta tych samych preferencji po raz kolejny. Wbudowana pamięć (CLAUDE.md, .cursorrules) ma limit 200 linii i szybko się dezaktualizuje. agentmemory to naprawia. Bezgłośnie przechwytuje to, co robi twój agent, kompresuje to do przeszukiwalnej pamięci i wstrzykuje właściwy kontekst, gdy zaczyna się kolejna sesja. Jedna komenda. Działa między różnymi agentami.
+
+**Co się zmienia:** W sesji 1 konfigurujesz autoryzację JWT. W sesji 2 prosisz o rate limiting. Agent już wie, że twoja autoryzacja korzysta z middleware jose w `src/middleware/auth.ts`, że twoje testy obejmują walidację tokenów i że wybrałeś jose zamiast jsonwebtoken ze względu na kompatybilność z Edge — bez ponownych wyjaśnień i bez kopiowania wklejania.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Domyślnie agentmemory przechowuje stan iii-engine poza repozytorium, z którego go uruchamiasz: `~/Library/Application Support/agentmemory` na macOS, `$XDG_DATA_HOME/agentmemory` lub `~/.local/share/agentmemory` na Linuksie oraz `%APPDATA%\agentmemory` na Windows. Istniejący, starszy `./data/state_store.db` lub `./data/iii-config.yaml` jest ponownie używany dla instancji 0 przed tą domyślną ścieżką platformy. Aby wskazać lokalizację wyraźnie, podaj `--data-dir ` lub ustaw `AGENTMEMORY_DATA_DIR`; każde z tych wyraźnych ustawień ma pierwszeństwo przed wykrywaniem starszej ścieżki:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Uruchomienia natywne i w Dockerze używają tego samego rozwiązanego katalogu hosta; Docker montuje go (bind-mount) pod `/data`. `--instance 1` dodaje `instance-1` do rozwiązanego katalogu i wybiera osobny, domyślny kwartet portów `3211/3212/3213/49234`.
+
+Najnowsze informacje o wydaniach: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Dokładność wyszukiwania
+
+**coding-agent-life-v1** (korpus własny, odtwarzalny w sandboksie)
+
+| Adapter | P@5 | R@5 | Trafienia w top-5 | opóźnienie p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% trafień w top-5 przy **matematycznym suficie P@5** dla tego korpusu (0.240, zobacz scorecard). Hybrid odzyskuje każdą złotą sesję; grep pomija 1 z 2 złotych sesji w zapytaniu temporalnym obejmującym wiele sesji. Przewaga dotyczy **recall + czasu**, a nie zagregowanej precyzji. Ten benchmark jest mały i ma mało danych złotych; większy LongMemEval-S poniżej różnicuje lepiej. Pełny podział per typ + uwaga o korekcie: [`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 pytań)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Fallback tylko BM25 | 86.2% | 94.6% | 71.5% |
+
+
+
+Uwaga dotycząca benchmarku: tylko wynik R@5 agentmemory jest naszym własnym zmierzonym wynikiem (LongMemEval-S, odtwarzalny na podstawie benchmark/COMPARISON.md). Wartości mem0 i Letta to ich opublikowane liczby LoCoMo (inny zbiór danych); wartości MemPalace, supermemory, TencentDB (PersonaMem) i oracleagentmemory to deklaracje producentów, których nie odtworzyliśmy niezależnie (uruchomienie oracleagentmemory używało GPT-5.5 względem Oracle AI Database). Zestawione obok siebie tylko orientacyjnie, nie jako test głowa w głowę na identycznych danych. Liczby gwiazdek są przybliżone i zmieniają się w czasie.
+
+**Nowsi uczestnicy** warci uwagi, porównani szerzej w [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| System | ⭐ | Podejście |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporalny graf wiedzy; najsilniejsze opublikowane wyniki zapytań temporalnych (LongMemEval 63.8%), ale graf buduje się asynchronicznie, więc świeże fakty mogą się spóźniać |
+| Cognee | 30K | Ingestia dokumentów do grafu wiedzy, tylko Python, zbudowane do strukturalnej ekstrakcji encji, a nie przechwytywania sesji |
+
+Żaden z nich nie przechwytuje automatycznie z hooków agenta kodującego, nie dostarcza podglądu lokalnego jako priorytetu ani nie działa bez klucza — to połączenie, wokół którego zbudowano agentmemory.
+
+---
+
+
+
+Kompatybilność: to wydanie celuje w `iii-sdk` 0.22.1 i przypina iii-engine do wersji v0.22.1.
+
+### Wypróbuj w 30 sekund
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` tworzy 3 realistyczne sesje (autoryzacja JWT, naprawa zapytania N+1, rate limiting) i wykonuje na nich wyszukiwania. Instalacje bez klucza wyłączają wektory, więc zapytania słowno-kluczowe `mem::search` powinny trafiać przez BM25, podczas gdy `database performance optimization` może zwrócić zero wyników. `smart-search` może dodatkowo zwracać strukturalne dopasowania z grafu, jeśli dane grafu istnieją. Aby zapytanie semantyczne znalazło naprawę N+1 za pomocą wektorów, ustaw `EMBEDDING_PROVIDER=local`, zrestartuj i pozwól, aby pierwsze pobranie modelu się zakończyło.
+
+Otwórz `http://localhost:3113`, aby na żywo obserwować budowanie pamięci.
+
+### Zweryfikuj świeżą instalację i trwałość po restarcie
+
+Gdy serwer działa, zweryfikuj REST, stan (health), podgląd oraz status środowiska uruchomieniowego opartego na iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Panel gotowości przy starcie uwzględnia wszystkie cztery porty: REST/MCP HTTP na 3111, strumienie iii na 3112, podgląd na 3113 i WebSocket workera iii na 49134. `status` potwierdza stan agentmemory oraz aktywny tryb dostawcy/embeddingów. Zapisz sondę i potwierdź, że jest wyszukiwalna:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Następnie uruchom `npx -y @agentmemory/agentmemory@latest stop`, ponownie uruchom kanoniczną komendę w Terminalu 1, zaczekaj na `/agentmemory/livez` i powtórz wyszukiwanie. Sonda musi wciąż zostać zwrócona. Jeśli wybrałeś własny `--data-dir`, podaj ten sam katalog przy restarcie.
+
+### Codzienne komendy
+
+Instalacja i konfiguracja są opisane w sekcji [Install](#install) powyżej (pierwsze uruchomienie przeprowadzi cię przez ten proces). Na co dzień:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Replay sesji
+
+Każdą sesję zapisaną przez agentmemory można odtworzyć. Otwórz podgląd, wybierz zakładkę **Replay** i przewijaj osię czasu: prompty, wywołania narzędzi, wyniki narzędzi i odpowiedzi renderują się jako osobne zdarzenia z odtwarzaniem/pauzą, kontrolą prędkości (0.5x do 4x) i skrótami klawiszowymi (spacja do przełączania, strzałki do kroku po kroku).
+
+Aby zaimportować starsze transkrypty JSONL z Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Zaimportowane sesje pojawiają się w selektorze Replay razem z natywnymi. Pod maską każdy wpis przechodzi przez funkcje iii `mem::replay::load`, `mem::replay::sessions` i `mem::replay::import-jsonl`, bez żadnych serwerów pobocznych. Każdy zaimportowany transkrypt jest indeksowany do wyszukiwania, oznaczony kanałem pochodzenia `import` i przetwarzany w poszukiwaniu kryształu sesji oraz lekcji.
+
+> **Uwaga, jeśli `import-jsonl` jest twoją główną ścieżką przechwytywania:** `cleanupPeriodDays` w Claude Code (w `~/.claude/settings.json`, domyślnie **30**) automatycznie usuwa transkrypty JSONL starsze niż to okno z `~/.claude/projects/`. Jeśli instalujesz agentmemory od zera na historii Claude Code mającej kilka miesięcy, wszystko starsze niż 30 dni jest już usunięte przed pierwszym importem. Albo uruchamiaj `import-jsonl` w cronie, albo zwiększ `cleanupPeriodDays`, albo podłącz hooki automatycznego przechwytywania (domyślna ścieżka instalacji pluginu), aby każda tura trafiała do agentmemory, gdy sesja jest jeszcze aktywna, dzięki czemu czyszczenie JSONL przestaje mieć znaczenie.
+
+### Aktualizacja / utrzymanie
+
+Użyj komendy utrzymania, gdy chcesz celowo zaktualizować swoje lokalne środowisko wykonawcze:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Ostrzeżenie: ta komenda modyfikuje bieżący workspace/środowisko wykonawcze. Może zaktualizować zależności JavaScript i pobrać przypięty obraz Docker `iiidev/iii:0.22.1`. Nigdy nie instaluje nieprzypiętego lub nowszego silnika iii.
+
+Szczegóły implementacji znajdują się w `src/cli.ts` (zobacz `runUpgrade` w okolicach `src/cli.ts:544-595`).
+
+### Claude Code (jeden blok, wklej go)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code bez instalacji pluginu (ścieżka samodzielnego MCP)
+
+Jeśli podłączasz serwer MCP agentmemory bezpośrednio przez `~/.claude.json` zamiast używać `/plugin install`, Claude Code nigdy nie rozwiąże `${CLAUDE_PLUGIN_ROOT}` i musisz wskazać skryptom hooków bezwzględne ścieżki w `~/.claude/settings.json`. Te ścieżki zwykle zawierają w sobie wersję agentmemory (np. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), więc kolejna aktualizacja po cichu psuje każdy hook.
+
+Rozwiązanie zastępcze:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+To scala te same komendy hooków do `~/.claude/settings.json`, z bezwzględnymi ścieżkami rozwiązanymi do dołączonego katalogu `plugin/` aktualnie zainstalowanego pakietu `@agentmemory/agentmemory`. Uruchom tę komendę ponownie po aktualizacji agentmemory, aby odświeżyć ścieżki. Wpisy użytkownika w tym samym pliku są zachowywane; zastępowane są tylko wcześniejsze wpisy agentmemory. Zalecanym podejściem pozostaje ścieżka `/plugin install`.
+Dla zdalnych lub chronionych wdrożeń uruchom Claude Code z ustawionymi `AGENTMEMORY_URL` i `AGENTMEMORY_SECRET`. Plugin przekazuje obie wartości dalej do swojego dołączonego serwera MCP; gdy `AGENTMEMORY_URL` jest puste, shim MCP używa `http://localhost:3111`.
+
+### Codex CLI (platforma pluginów Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Plugin Codex jest dostarczany z tego samego katalogu `plugin/` co plugin Claude Code. Rejestruje:
+
+- Dołączony mostek stdio MCP do działającego daemona, bez pobierania z npm i bez magazynu fallback. Zobacz [lokalny przewodnik po Codex](../docs/plugins/codex-local.md), aby przetestować niewydany build.
+- 6 hooków cyklu życia: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 wywoływalnych skilli: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 skilli referencyjnych wczytywanych przez agenta na żądanie (dyscyplina pamięci, narzędzia MCP, REST API, konfiguracja, agenci, hooki, architektura oraz przewodnik tworzenia skilli)
+
+Silnik hooków Codex wstrzykuje `CLAUDE_PLUGIN_ROOT` do podprocesów hooków (zgodnie z [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), dzięki czemu te same skrypty hooków działają w obu hostach bez duplikacji. Zdarzenia Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure są dostępne tylko w Claude Code i nie są rejestrowane dla Codex.
+
+#### Hooki Codex: zaufanie i kompatybilność
+
+Natywne wywoływanie hooków pluginu jest zweryfikowane w Codex CLI 0.150.1. Zaufaj hookom pluginu, zanim oczekujesz przechwytywania. Zachowanie Codex Desktop zależy od dołączonego runtime; sprawdź `/hooks` i potwierdź przechwycone zdarzenie, zanim włączysz rozwiązanie zastępcze.
+
+Jeśli twój host wymaga globalnych hooków, zduplikuj komendy do globalnego `~/.codex/hooks.json`. Gdy MCP jest już podłączone, aktualny adapter `connect` potrzebuje `--force`, aby dotrzeć do instalacji hooków:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+To scala globalne hooki i przepisuje wpis MCP agentmemory, zachowując niepowiązane wpisy. Sprawdź własne ustawienia endpointu agentmemory przed użyciem `--force`. Uruchom ponownie po aktualizacji, aby odświeżyć ścieżki skryptów. Włącz albo natywne hooki pluginu, albo globalne kopie, aby uniknąć podwójnego przechwytywania.
+
+### GitHub Copilot CLI
+
+Dla trybu agenta VS Code użyj [przewodnika MCP i auto-przechwytywania Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Konektor CLI nie konfiguruje VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` scala `mcpServers.agentmemory` do `~/.copilot/mcp-config.json` (lub `$COPILOT_HOME/mcp-config.json`, gdy ustawiono `COPILOT_HOME`) i zachowuje istniejące serwery. Na natywnym Windows jest to jedyny zautomatyzowany adapter `connect`; każdego innego natywnego agenta Windows skonfiguruj ręcznie. `connect` w WSL jest wspierane tylko wtedy, gdy docelowy agent jest zainstalowany w tym samym środowisku WSL. Copilot podchwytuje serwer MCP przy następnym uruchomieniu lub po `/mcp`. Zainstaluj też plugin, jeśli chcesz pełne doświadczenie hooków/skilli.
+
+
+OpenClaw (wklej ten prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Pełny przewodnik: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (wklej ten prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Pełny przewodnik: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Inni agenci
+
+Uruchom serwer pamięci: `npx -y @agentmemory/agentmemory@latest`
+
+#### Natywne skille przez `npx skills add` (50+ agentów)
+
+agentmemory dostarcza 17 skilli w formacie `/SKILL.md` w stylu Claude Code: 9 wywoływalnych skilli akcji (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) oraz 8 skilli referencyjnych wczytywanych przez agenta na żądanie (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Skille referencyjne zawierają tabele danych generowane ze źródła, więc nigdy się nie rozjeżdżają. CLI [`skills`](https://npmjs.com/package/skills) od vercel-labs automatycznie instaluje je w natywnym katalogu skilli wywołującego agenta, obejmując ponad 50 agentów (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf i inne):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Jest to **uzupełnienie** dla `agentmemory connect `:
+
+- `agentmemory connect ` zapisuje konfigurację serwera MCP, dzięki czemu narzędzia są dostępne.
+- `npx skills add rohitg00/agentmemory` instaluje skille, dzięki czemu agent wie, kiedy je wywołać.
+
+Dla tej niewielkiej liczby agentów, których CLI `skills` jeszcze nie obsługuje (Zed v1.3.x i starsze), umieść 17 plików SKILL.md w natywnym katalogu skilli agenta samodzielnie; ten sam format działa wszędzie.
+
+#### Standardowy blok MCP
+
+Wpis agentmemory to **ten sam blok serwera MCP** we wszystkich hostach, które używają struktury `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Scal ten wpis z istniejącym obiektem `mcpServers`** w pliku konfiguracyjnym hosta; nie zastępuj całego pliku. Jeśli plik już ma inne serwery, dodaj `agentmemory` obok nich jako kolejny klucz wewnątrz `mcpServers`. Jeśli `mcpServers` całkowicie nie istnieje, wklej ten blok wewnątrz `{ "mcpServers": { ... } }`. Placeholdery `${VAR}` dziedziczą `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` z shella w momencie uruchamiania serwera MCP; nieustawione zmienne przekazują puste ciągi i shim wraca do `http://localhost:3111`. Jeden podłączony wpis obsługuje zarówno wdrożenia lokalne, jak i zdalne (k8s / za reverse-proxy).
+
+| Agent | Plik konfiguracyjny | Uwagi |
+|---|---|---|
+| **Cursor (tylko MCP)** | `~/.cursor/mcp.json` | Scal z `mcpServers`, albo użyj `agentmemory connect cursor`. Na stronie dostępny jest też deeplink jednym kliknięciem. |
+| **Cursor (pełny plugin)** | `.cursor-plugin/` | Wpis w Cursor Marketplace (zgłoszenie w trakcie weryfikacji) albo Cursor Settings → Plugins → lokalny checkout. Rejestruje 7 hooków auto-przechwytywania (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skilli + serwer MCP, z `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` zarządzanymi w panelu pluginów Cursor. Działa w Cursor IDE oraz w CLI `cursor-agent`; prompty w trybie print CLI są uzupełniane retroaktywnie z transkryptu sesji na jej koniec. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Scal z `mcpServers`. Zrestartuj Claude Desktop po edycji. |
+| **Cline / Roo Code / Kilo Code** | Ustawienia MCP w Cline (Settings UI → MCP Servers → Edit) | Ten sam blok `mcpServers`. |
+| **Devin CLI (MCP + hooki)** | `~/.config/devin/config.json` | `agentmemory connect devin` scala wpis MCP; `--with-hooks` dodaje sześć natywnych hooków auto-przechwytywania (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) z pisanymi małymi literami matcherami narzędzi Devin. Zweryfikuj za pomocą `devin mcp list` oraz `/hooks` wewnątrz devin. |
+| **Devin CLI (pełny plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` z checkoutu rejestruje wszystkie 17 skilli jako komendy ukośnikowe `/agentmemory:` oraz serwer MCP. Hooki pluginu Devin nie mogą wywołać `SessionStart`/`SessionEnd`, więc połącz to z `connect devin --with-hooks`, aby uzyskać pełne przechwytywanie sesji. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Dodaj niestandardowy MCP (STDIO): komenda `npx`, argumenty `-y @agentmemory/mcp@latest`, zmienna środowiskowa `AGENTMEMORY_URL` wskazująca na wdrożenie agentmemory dostępne w sieci, plus `AGENTMEMORY_SECRET` (sesje w chmurze nie mają dostępu do localhost — zobacz [`deploy/`](../deploy/)). Zapisz sekret w Devin Secrets, a następnie użyj „Test listing tools”, aby zweryfikować, że pojawia się wszystkich 54 narzędzi. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (scala automatycznie). |
+| **GitHub Copilot CLI (tylko MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` scala `mcpServers.agentmemory`; Copilot podchwytuje to przy następnym uruchomieniu lub po `/mcp`. |
+| **GitHub Copilot CLI (pełny plugin)** | Instalacja pluginu Copilot | `copilot plugin install rohitg00/agentmemory:plugin`, aby zainstalować plugin z podkatalogu GitHub. |
+| **OpenClaw** | Konfiguracja MCP OpenClaw | Ten sam blok `mcpServers`. Głębsza integracja: `openclaw plugins install ./integrations/openclaw` zajmuje slot pamięci OpenClaw (automatycznie przełącza z `memory-core`); ustaw `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, inaczej przechwytywanie tury jest po cichu blokowane. Zobacz [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (tylko MCP)** | `.codex/config.toml` | Struktura TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, albo dodaj `[mcp_servers.agentmemory]` ręcznie. |
+| **Codex CLI (pełny plugin)** | Marketplace pluginów Codex | `codex plugin marketplace add rohitg00/agentmemory`, a następnie `codex plugin add agentmemory@agentmemory`. Rejestruje MCP + 6 hooków cyklu życia + 17 skilli. Zaufaj hookom i zweryfikuj przechwytywanie w swoim hoście; zobacz [Konfiguracja i walidacja Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (tylko MCP)** | `opencode.json` | Inna struktura: klucz `mcp` na najwyższym poziomie, komenda jako tablica: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (pełny plugin)** | `plugin/opencode/` | 22 hooki auto-przechwytywania obejmujące cykl życia sesji, wiadomości, narzędzia i błędy. Przypisanie do projektu jest per sesja, więc jeden proces OpenCode obejmujący kilka repozytoriów zapisuje każdą sesję pod jej własnym projektem. Dwie komendy ukośnikowe (`/recall`, `/remember`). Skopiuj `plugin/opencode/` do swojego workspace OpenCode i dodaj wpis pluginu do `opencode.json`. Zobacz [`plugin/opencode/README.md`](../plugin/opencode/README.md), aby zobaczyć pełną tabelę hooków i analizę braków. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instaluje dołączone rozszerzenie w katalogu auto-wykrywania pi (przywołanie przy starcie agenta, przechwytywanie przy jego zakończeniu, narzędzia `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` w działającym pi podchwytuje to rozszerzenie. [`integrations/pi`](../integrations/pi/) jest też pakietem pi (`pi install ./integrations/pi` z checkoutu). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` daje dostawcę pamięci z 6 hookami (prefetch, przechwytywanie tury, koniec sesji, pre-compress, odzwierciedlanie MEMORY.md, blok system prompt). Zweryfikuj za pomocą `hermes plugins doctor` i `hermes memory status`. Zobacz [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` zapisuje standardowy blok `mcpServers`. Payload hooków jest kompatybilny co do pól z Claude Code, więc istniejące skrypty 12 hooków działają bez modyfikacji; podłącz je przez sekcję `hooks` w tym samym `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instaluje MCP i hooki przechwytywania we współdzielonym katalogu personalizacji. Zobacz [Konfiguracja i ograniczenia Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` używa tej samej konfiguracji MCP i hooków, jak aktualne wersje IDE. Istniejące instalacje powinny odświeżyć się za pomocą `--force`; zobacz [uwagi dotyczące aktualizacji](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` zapisuje konfigurację na poziomie użytkownika. Nadpisania na poziomie workspace idą do `.kiro/settings/mcp.json` obok twojego kodu. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` zapisuje standardowy blok `mcpServers`. Warp automatycznie wykrywa też skille z `.claude/skills/`; gdy zainstalowany jest plugin Claude Code, 8 skilli agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) pojawia się natywnie w palecie komend ukośnikowych Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` zapisuje standardowy blok `mcpServers`. Użytkownicy rozszerzenia VS Code: wklej ten sam blok przez Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferowane) lub `config.json` (starsze) | `agentmemory connect continue` tworzy `config.yaml` od zera, gdy żaden z plików nie istnieje, albo modyfikuje istniejący `config.json`. **Jeśli masz już `config.yaml`**, adapter wypisuje dokładny blok do wklejenia pod `mcpServers:`; nie nadpisuje po cichu twojego yaml, bo bezpieczne zachowanie komentarzy i kotwic (anchors) wymaga parsera YAML, którego pakiet nie dostarcza. Continue używa formy tablicowej (nie obiektu) dla `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` zapisuje pod `context_servers` (klucz Zed, a NIE `mcpServers`). Zdalne serwery MCP można podłączyć zamiast tego przez `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` zapisuje standardowy blok `mcpServers`. Nadpisania w zakresie projektu idą do `/.factory/mcp.json`. Podaj `--with-hooks`, aby uzyskać natywne auto-przechwytywanie. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` dopisuje wiersz `@deepseek-ai/dsh-mcp-client` do warstwy patchy na poziomie home, którą wczytuje każdy profil Harness; narzędzia rejestrują się jako `mcp__agentmemory__*`. Podaj `--with-hooks`, aby dodatkowo podłączyć auto-przechwytywanie: dołączone skrypty hooków Claude Code działają przez pierwszorzędny mostek Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) za pomocą manifestu zapisanego w `$DSH_HOME/agentmemory.hooks.json`. Domyślnie `~/.dsh`, gdy `DSH_HOME` nie jest ustawione. |
+| **Goose** | Interfejs ustawień MCP w Goose | Ten sam blok `mcpServers`; użyj `goose configure` → Add Extension → MCP. Bezpośrednia edycja YAML w `~/.config/goose/config.yaml` jest wspierana, ale schemat używa `extensions:` + `cmd` (nie `mcpServers:` + `command`). |
+| **Aider** | n/d | Rozmawiaj bezpośrednio z REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Każdy agent (32+)** | n/d | `npx skillkit install agentmemory` automatycznie wykrywa hosta i scala. |
+
+**Klienci MCP w sandboksie** (Flatpak / Snap / restrykcyjne kontenery), które nie mają dostępu do `localhost` hosta: ustaw dodatkowo `"AGENTMEMORY_FORCE_PROXY": "1"` w bloku `env` i wskaż `AGENTMEMORY_URL` na trasę, do której sandbox faktycznie ma dostęp (np. twój adres IP w sieci LAN).
+
+### Dostęp programistyczny (Python / Rust / Node)
+
+agentmemory rejestruje swoje główne operacje jako funkcje iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Każdy język z SDK iii może wywołać je bezpośrednio przez `ws://localhost:49134`, bez potrzeby osobnego klienta REST dla każdego języka.
+
+```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"},
+})
+```
+
+Przykład praktyczny: [`examples/python/`](../examples/python/) (szybki start + przepływ obserwacji/przywołania). REST na `:3111` pozostaje dostępny dla hostów bez środowiska uruchomieniowego iii.
+
+### Ze źródeł
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+To uruchamia agentmemory z lokalnym `iii-engine`, jeśli przypięty plik binarny jest już zainstalowany, albo używa Docker Compose, gdy zostanie wybrane. REST, strumienie i podgląd domyślnie wiążą się z `127.0.0.1`. Automatyczna ścieżka binarna na macOS/Linux wymaga `curl`, POSIX-owego `sh` i `tar`.
+
+Zainstaluj `iii-engine` ręcznie. **agentmemory obecnie przypina `iii-engine` do wersji `v0.22.1`**, tego samego wydania co jego zależność `iii-sdk`; worker mówi protokołem przewodowym tego silnika, a 0.20.0 zreorganizowało powierzchnię SDK, więc te dwa elementy przesuwają się razem w wydaniach agentmemory. Nadpisz to za pomocą `AGENTMEMORY_III_VERSION=`, jeśli uruchamiasz własny silnik i wiesz, że jest zgodny.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** zamień `aarch64-apple-darwin` na `x86_64-apple-darwin`
+- **Linux x64:** zamień na `x86_64-unknown-linux-gnu`
+- **Linux arm64:** zamień na `aarch64-unknown-linux-gnu`
+- **Windows:** pobierz `iii-x86_64-pc-windows-msvc.zip` z [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) i wypakuj `iii.exe` do `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Każde archiwum ma odpowiadający mu plik `.sha256` na stronie wydania; gdy zmieniasz platformę, użyj hasha z tego pliku w powyższej weryfikacji (na Windows: `Get-FileHash`). Automatyczny instalator w `npx @agentmemory/agentmemory` przypina te hashe i odrzuca archiwum, które się nie zgadza.
+
+Albo użyj Dockera (dołączony `docker-compose.yml` pobiera `iiidev/iii:0.22.1`). Pełna dokumentacja: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory działa na Windows 10/11, ale sam pakiet Node.js nie wystarczy; potrzebujesz również przypiętego środowiska uruchomieniowego iii-engine v0.22.1 jako procesu w tle. CLI nie wypakowuje automatycznie pliku ZIP dla Windows, więc użytkownicy natywnego Windows muszą zainstalować `iii.exe` ręcznie, użyć WSL2 albo wybrać Docker Desktop.
+
+Zautomatyzowane podłączanie MCP na natywnym Windows wspiera tylko `agentmemory connect copilot-cli`. Dla Claude Code, Codex, Cursor i każdego innego natywnego agenta Windows skopiuj ręczny blok MCP z sekcji [Other agents](#other-agents) do konfiguracji Windows tego agenta. Uruchamianie `connect` w WSL ma sens tylko wtedy, gdy docelowy agent jest również zainstalowany w tym samym środowisku WSL; nie edytuje ono konfiguracji agenta hostowanego na Windows.
+
+**Opcja A: gotowy plik binarny dla Windows (zalecane)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opcja B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opcja C: tylko samodzielny MCP (bez silnika).** Jeśli potrzebujesz tylko narzędzi MCP dla swojego agenta i nie potrzebujesz REST API, podglądu ani zadań cron, pomiń silnik całkowicie:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostyka dla Windows:** jeśli `npx -y @agentmemory/agentmemory@latest` zawiedzie, uruchom ją ponownie z `--verbose`, aby zobaczyć rzeczywisty stderr silnika. Typowe przypadki błędów:
+
+| Symptom | Rozwiązanie |
+|---|---|
+| `The engine process started but the REST API never responded.` | Sprawdź, czy wszystkie cztery wyznaczone porty są wolne, zweryfikuj, że przypięty `iii.exe` nadal działa, a następnie uruchom ponownie z `--verbose` i przeanalizuj przechwycony stderr silnika |
+| `Could not start iii-engine` | Nie zainstalowano ani `iii.exe`, ani Dockera. Zobacz opcję A lub B powyżej |
+| Konflikt portów | `netstat -ano \| findstr :3111`, aby zobaczyć, co zajmuje port, a następnie zakończ ten proces albo użyj `--port ` |
+| Fallback do Dockera jest pomijany, mimo że Docker jest zainstalowany | Sprawdź, czy Docker Desktop faktycznie działa (ikona w zasobniku systemowym) |
+
+> Uwaga: iii **engine** to gotowy plik binarny, a nie crate cargo, więc nie próbuj go instalować przez `cargo install`. (**SDK** iii są opublikowane na crates.io, npm i PyPI, ale agentmemory ich nie potrzebuje.) Wszystkie wspierane metody instalacji silnika są przypięte do v0.22.1: gotowy plik binarny powyżej, automatyczna ścieżka instalacji agentmemory na macOS/Linux (wymaga `curl`, POSIX `sh` i `tar`) oraz obraz Dockera `iiidev/iii:0.22.1`. Goły upstreamowy `install.sh | sh` instaluje najnowszy silnik, którego agentmemory nie wspiera. Użyj `npx -y @agentmemory/agentmemory@latest`; na macOS/Linux pobiera on przypięty silnik do `~/.agentmemory/bin`.
+
+---
+
+
Wdrożenie
+
+Szablony jednoklikowe dla zarządzanych hostingów. Każdy z nich dostarcza samodzielny
+Dockerfile, który pobiera `@agentmemory/agentmemory` z npm i kopiuje
+plik binarny silnika iii z oficjalnego obrazu Docker Hub `iiidev/iii`;
+nie jest wymagany gotowy obraz agentmemory. Trwałe przechowywanie
+montowane jest pod `/data`; punkt wejścia przy pierwszym starcie nadpisuje
+dołączoną do npm konfigurację iii (która wiąże się z `127.0.0.1`) konfiguracją
+dostosowaną do wdrożenia, która wiąże się z `0.0.0.0` i używa bezwzględnych
+ścieżek `/data`, generuje sekret HMAC, a następnie zrzuca uprawnienia
+z `root` do `node` za pomocą `gosu`, zanim wykona (exec) CLI agentmemory.
+
+
+
+
+
+
+Przycisk jednoklikowego wdrożenia Render wymaga `render.yaml` w katalogu głównym repozytorium, który celowo zostawiamy czysty. Użyj przepływu Render Blueprint opisanego w [`deploy/render/`](.././deploy/render/README.md), aby ręcznie wskazać blueprint znajdujący się w repozytorium.
+
+Pełne szczegóły konfiguracji (przechwytywanie HMAC, tunel SSH do podglądu, rotacja, backup,
+minimalne koszty) znajdują się w [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): pojedyncza maszyna z
+ `auto_stop_machines = "stop"`; najtańsza opcja w stanie bezczynności.
+- [`deploy/railway`](.././deploy/railway/README.md): stała opłata w planie Hobby,
+ wolumin w panelu.
+- [`deploy/render`](.././deploy/render/README.md): przepływ Blueprint,
+ automatyczne migawki dysku w planach płatnych.
+- [`deploy/coolify`](.././deploy/coolify/README.md): hostowane samodzielnie na
+ własnym VPS za pomocą [Coolify](https://coolify.io/self-hosted); ten sam
+ stos Docker Compose, host i dane należą do ciebie.
+
+Publikowany jest tylko port `3111`. Podgląd na `3113` pozostaje związany z
+loopbackiem wewnątrz kontenera; README każdego szablonu opisuje wzorzec
+tunelu SSH, aby się do niego dostać.
+
+---
+
+
+
+Każdy agent kodujący zapomina wszystko, gdy sesja się kończy, a każda nowa sesja zaczyna się od tego, że ponownie wyjaśniasz swój stack. agentmemory działa w tle i usuwa ten krok.
+
+```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.
+```
+
+### agentmemory kontra wbudowana pamięć agenta
+
+Każdy kodujący agent AI ma wbudowaną pamięć: Claude Code ma `MEMORY.md`, Cursor ma notepady, Cline ma memory bank. Działają jak karteczki samoprzylepne. agentmemory to przeszukiwalna baza danych stojąca za tymi karteczkami.
+
+| | Wbudowana (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skala | limit 200 linii | Bez limitu |
+| Wyszukiwanie | Wczytuje wszystko do kontekstu | BM25 + wektor + graf (tylko top-K) |
+| Koszt tokenów | 22K+ przy 240 obserwacjach | ~1,900 tokenów (92% mniej) |
+| Między agentami | Pliki per agent | MCP + REST (każdy agent) |
+| Koordynacja | Brak | Leasy, sygnały, akcje, rutyny |
+| Obserwowalność | Ręczne czytanie plików | Podgląd w czasie rzeczywistym na :3113 |
+
+---
+
+
+
+### Potok pamięci
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-poziomowa konsolidacja pamięci
+
+Wzorowane na tym, jak ludzki mózg przetwarza pamięć, włącznie z konsolidacją podczas snu.
+
+| Poziom | Co | Analogia |
+|------|------|---------|
+| **Working (robocza)** | Surowe obserwacje z użycia narzędzi | Pamięć krótkotrwała |
+| **Episodic (epizodyczna)** | Skompresowane podsumowania sesji | „Co się wydarzyło” |
+| **Semantic (semantyczna)** | Wyodrębnione fakty i wzorce | „Co wiem” |
+| **Procedural (proceduralna)** | Przepływy pracy i wzorce decyzyjne | „Jak to zrobić” |
+
+Wspomnienia zanikają z czasem (krzywa Ebbinghausa). Często używane wspomnienia wzmacniają się. Nieaktualne wspomnienia są automatycznie usuwane. Sprzeczności są wykrywane i rozwiązywane.
+
+### Co jest przechwytywane
+
+| Hook | Przechwytuje |
+|------|----------|
+| `SessionStart` | Ścieżkę projektu, ID sesji |
+| `UserPromptSubmit` | Prompty użytkownika (filtrowane pod kątem prywatności) |
+| `PreToolUse` | Wzorce dostępu do plików + wzbogacony kontekst |
+| `PostToolUse` | Nazwę narzędzia, wejście, wyjście |
+| `PostToolUseFailure` | Kontekst błędu |
+| `PreCompact` | Ponownie wstrzykuje pamięć przed kompaktowaniem |
+| `SubagentStart/Stop` | Cykl życia subagenta |
+| `Stop` | Podsumowanie końca sesji |
+| `SessionEnd` | Znacznik zakończenia sesji |
+
+### Kluczowe możliwości
+
+| Możliwość | Opis |
+|---|---|
+| **Automatyczne przechwytywanie** | Każde użycie narzędzia zapisywane przez hooki, bez pracy ręcznej |
+| **Wyszukiwanie semantyczne** | BM25 + wektor + graf wiedzy z fuzją RRF |
+| **Ewolucja pamięci** | Wersjonowanie, zastępowanie (supersession), grafy relacji |
+| **Higiena przywołania** | Zastąpione wersje pamięci opuszczają indeksy wyszukiwania; łańcuch wersji w KV zachowuje pełną historię |
+| **Wskazówki o bliskich duplikatach** | Zapisy zgłaszają poglądowe dopasowanie `similarTo`, gdy nowa treść jest bliska istniejącemu wspomnieniu |
+| **Zakresowanie per agent** | `agentId` przechodzi przez zapis i przywołanie w REST, MCP i indeksie wyszukiwania, w trybie shared lub isolated |
+| **Pochodzenie w momencie zapisu** | Każda obserwacja i każde wspomnienie niesie niezmienny kanał pochodzenia (user, agent, tool, import lub shared), oznaczony przy przechwyceniu, zapisie i imporcie |
+| **Auto-zapominanie** | Wygasanie TTL, wykrywanie sprzeczności, usuwanie na podstawie ważności |
+| **Prywatność na pierwszym miejscu** | Klucze API, sekrety, tagi `` są usuwane przed zapisem |
+| **Samonaprawa** | Circuit breaker, łańcuch fallback dostawców, monitorowanie stanu |
+| **Mostek Claude** | Dwustronna synchronizacja z MEMORY.md |
+| **Graf wiedzy** | Ekstrakcja encji + przeszukiwanie BFS |
+| **Pamięć zespołowa** | Współdzielona i prywatna, podzielona na przestrzenie nazw między członkami zespołu |
+| **Pochodzenie cytowań** | Śledzenie każdego wspomnienia z powrotem do źródłowych obserwacji |
+| **Migawki Git** | Wersjonowanie, rollback i diff stanu pamięci |
+
+---
+
+
+
+Wyszukiwanie w trzech strumieniach, łączące trzy sygnały:
+
+| Strumień | Co robi | Kiedy |
+|---|---|---|
+| **BM25** | Dopasowywanie słów kluczowych ze stemmingiem i rozszerzaniem synonimów | Zawsze włączone |
+| **Wektor** | Podobieństwo kosinusowe na gęstych embeddingach | Gdy skonfigurowano dostawcę embeddingów |
+| **Graf** | Przeszukiwanie grafu wiedzy przez dopasowywanie encji | Gdy w zapytaniu wykryto encje |
+
+Łączone za pomocą Reciprocal Rank Fusion (RRF, k=60) i zróżnicowane pod względem sesji (maks. 3 wyniki na sesję).
+
+Gdy indeks wektorowy jest wypełniony, `mem::search` (stojące za `memory_recall`) używa hybrydowego rankera BM25 + wektor. Bez embeddingów używa BM25. `smart-search` może dodatkowo łączyć strukturalne dopasowania z grafu, gdy dane grafu istnieją, również w trybie bez klucza. Przywołanie lekcji działa na dedykowanym indeksie BM25 w pamięci, zamiast skanować cały korpus przy każdym zapytaniu. Zastąpione wersje pamięci są wykluczone z każdej ścieżki przywołania; łańcuch wersji zachowuje ich historię.
+
+Wektory przetrwają awarię lub wymuszone zabicie procesu. Indeks wektorowy jest zapisywany w paczkach (buckets) nie częściej niż co `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minut). Każdy wektor dodany lub usunięty w międzyczasie jest też natychmiast zapisywany do małego dziennika oczekujących w magazynie stanu, a przy kolejnym starcie jest odtwarzany bez wywoływania dostawcy embeddingów. Każdy udany zapis opróżnia ten dziennik. Dokumenty, które po odtworzeniu wciąż nie mają wektora, są ponownie embeddowane w tle w paczkach po `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), aż żaden nie zostanie, a zatrzymane uzupełnianie kontynuuje się przy następnym starcie. `/agentmemory/status` i podgląd pokazują rozmiar dziennika oczekujących i stan uzupełniania. Instalacje bez klucza nic nie zapisują.
+
+BM25 od razu tokenizuje grekę, cyrylicę, hebrajski, arabski i akcentowaną łacinę. Dla wspomnień w chińskim / japońskim / koreańskim zainstaluj opcjonalne segmentery (`npm install @node-rs/jieba tiny-segmenter`), aby dzielić ciągi CJK na tokeny na poziomie słów; bez nich agentmemory łagodnie przechodzi na tokenizację całych ciągów i jednorazowo wypisuje wskazówkę na stderr.
+
+### Dostawcy embeddingów
+
+Instalacje bez klucza wyłączają wektorowe embeddingi: `mem::search` używa BM25, natomiast `smart-search` może też użyć istniejących strukturalnych danych grafu. Aby włączyć bezpłatne, lokalne (on-device) embeddingi semantyczne, dodaj to do `~/.agentmemory/.env` i zrestartuj agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Zwykła instalacja npm zawiera opcjonalne środowisko uruchomieniowe `@huggingface/transformers`. Pierwsze żądanie embeddingu pobiera `Xenova/all-MiniLM-L6-v2`, więc potrzebuje dostępu do sieci i może potrwać dłużej; kolejne wnioskowanie działa lokalnie. Zdalni dostawcy są automatycznie wykrywani na podstawie ich kluczy, o ile `EMBEDDING_PROVIDER` nie nadpisuje tego wyboru.
+
+| Dostawca | Model | Koszt | Uwagi |
+|---|---|---|---|
+| **Lokalny (zalecany opt-in)** | `all-MiniLM-L6-v2` | Bezpłatny | Lokalnie po pierwszym pobraniu modelu, +8pp recall względem samego BM25 |
+| Gemini | `gemini-embedding-001` | Darmowy poziom | 100+ języków, wymiary 768/1536/3072 (MRL), wejście do 2048 tokenów. Zastępuje `text-embedding-004` ([przestarzały, wyłączenie 14 stycznia 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Najwyższa jakość |
+| Voyage AI | `voyage-code-3` | Płatny | Zoptymalizowany pod kod |
+| Cohere | `embed-english-v3.0` | Darmowy okres próbny | Ogólnego przeznaczenia |
+| OpenRouter | Każdy model | Zależnie | Proxy dla wielu modeli |
+
+---
+
+
+
+54 narzędzia, 6 zasobów, 3 prompty i 17 skilli.
+
+> **Shim MCP a pełny serwer:** opublikowany pakiet `@agentmemory/mcp` to cienki shim. Udostępnia pełną powierzchnię 54 narzędzi **tylko wtedy, gdy może dotrzeć do działającego serwera agentmemory** przez `AGENTMEMORY_URL` (tryb proxy). Gdy żaden serwer nie jest dostępny, shim wraca do lokalnego zestawu 7 narzędzi (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Zmienna środowiskowa `AGENTMEMORY_TOOLS=core|all` jest flagą *po stronie serwera*; ustawienie jej w bloku `env` shimu nie ma żadnego efektu. Jeśli widzisz tylko 7 narzędzi w Cursor / OpenCode / Gemini CLI, uruchom `npx -y @agentmemory/agentmemory@latest` (albo stos Docker) i ustaw `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 narzędzia
+
+Trzy powierzchnie narzędzi, od najmniejszej do największej: `AGENTMEMORY_TOOLS=core` ogranicza widoczność do 8 niezbędnych narzędzi (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); poniższy podstawowy zestaw to 14 podstawowych narzędzi z rejestru; wartość domyślna (`AGENTMEMORY_TOOLS=all`) udostępnia wszystkie 54.
+
+
+Narzędzia podstawowe (14)
+
+| Narzędzie | Opis |
+|------|-------------|
+| `memory_recall` | Wyszukuje wcześniejsze obserwacje |
+| `memory_compress_file` | Kompresuje pliki markdown, zachowując strukturę |
+| `memory_save` | Zapisuje wgląd, decyzję lub wzorzec |
+| `memory_file_history` | Wcześniejsze obserwacje dotyczące konkretnych plików |
+| `memory_patterns` | Wykrywa powtarzające się wzorce |
+| `memory_sessions` | Listuje ostatnie sesje |
+| `memory_smart_search` | Hybrydowe wyszukiwanie semantyczne + słowno-kluczowe |
+| `memory_vision_search` | Wyszukuje obserwacje obrazów |
+| `memory_timeline` | Chronologiczne obserwacje |
+| `memory_profile` | Profil projektu (koncepcje, pliki, wzorce) |
+| `memory_export` | Eksportuje wszystkie dane pamięci |
+| `memory_relations` | Odpytuje graf relacji |
+| `memory_commit_lookup` | Sesje stojące za commitem git |
+| `memory_commits` | Commity zapisane dla sesji |
+
+
+
+
+Narzędzia rozszerzone (54 łącznie, domyślna powierzchnia)
+
+| Narzędzie | Opis |
+|------|-------------|
+| `memory_patterns` | Wykrywa powtarzające się wzorce |
+| `memory_timeline` | Chronologiczne obserwacje |
+| `memory_relations` | Odpytuje graf relacji |
+| `memory_graph_query` | Przeszukiwanie grafu wiedzy |
+| `memory_consolidate` | Uruchamia 4-poziomową konsolidację |
+| `memory_claude_bridge_sync` | Synchronizuje z MEMORY.md |
+| `memory_team_share` | Udostępnia członkom zespołu |
+| `memory_team_feed` | Ostatnio udostępnione elementy |
+| `memory_audit` | Ścieżka audytu operacji |
+| `memory_governance_delete` | Usuwa ze ścieżką audytu |
+| `memory_snapshot_create` | Migawka wersjonowana w Git |
+| `memory_action_create` | Tworzy zadania z zależnościami |
+| `memory_action_update` | Aktualizuje status akcji |
+| `memory_frontier` | Odblokowane akcje uszeregowane według priorytetu |
+| `memory_next` | Jedna najważniejsza następna akcja |
+| `memory_lease` | Wyłączne leasy akcji (wiele agentów) |
+| `memory_routine_run` | Tworzy instancje rutyn przepływu pracy |
+| `memory_signal_send` | Komunikacja między agentami |
+| `memory_signal_read` | Odczytuje wiadomości z potwierdzeniami odbioru |
+| `memory_checkpoint` | Bramki warunków zewnętrznych |
+| `memory_mesh_sync` | Synchronizacja P2P między instancjami |
+| `memory_sentinel_create` | Obserwatory kierowane zdarzeniami |
+| `memory_sentinel_trigger` | Wyzwala wartowników (sentinels) z zewnątrz |
+| `memory_sketch_create` | Efemeryczne grafy akcji |
+| `memory_sketch_promote` | Awansuje do stałego |
+| `memory_crystallize` | Kompaktuje łańcuchy akcji |
+| `memory_diagnose` | Kontrole stanu |
+| `memory_heal` | Automatycznie naprawia zablokowany stan |
+| `memory_facet_tag` | Tagi wymiar:wartość |
+| `memory_facet_query` | Odpytywanie po tagach fasetowych |
+| `memory_verify` | Śledzi pochodzenie |
+
+
+
+### 6 zasobów · 3 prompty · 17 skilli
+
+| Typ | Nazwa | Opis |
+|------|------|-------------|
+| Zasób | `agentmemory://status` | Stan, liczba sesji, liczba wspomnień |
+| Zasób | `agentmemory://project/{name}/profile` | Inteligencja per projekt |
+| Zasób | `agentmemory://project/{name}/recent` | Ostatnie obserwacje dla projektu |
+| Zasób | `agentmemory://memories/latest` | Ostatnie 10 aktywnych wspomnień |
+| Zasób | `agentmemory://graph/stats` | Statystyki grafu wiedzy |
+| Zasób | `agentmemory://team/{id}/profile` | Współdzielony profil zespołu |
+| Prompt | `recall_context` | Wyszukuje i zwraca wiadomości kontekstowe |
+| Prompt | `session_handoff` | Dane przekazania między agentami |
+| Prompt | `detect_patterns` | Analizuje powtarzające się wzorce |
+| Skill | `/recall` | Przeszukuje pamięć |
+| Skill | `/remember` | Zapisuje do pamięci długotrwałej |
+| Skill | `/session-history` | Podsumowania ostatnich sesji |
+| Skill | `/forget` | Usuwa obserwacje/sesje |
+
+Tabela pokazuje cztery podstawowe skille. Pełny zestaw to 9 wywoływalnych skilli plus 8 skilli referencyjnych; zobacz sekcję Native skills powyżej.
+
+### Samodzielny MCP
+
+Działa bez pełnego serwera, dla każdego klienta MCP. Działa jedno z poniższych:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Albo dodaj do konfiguracji MCP swojego agenta:
+
+Większość agentów (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Scal wpis `agentmemory` z istniejącym obiektem `mcpServers` twojego hosta, zamiast zastępować cały plik. Dla klientów w sandboksie, które nie mają dostępu do `localhost` hosta, dodaj `"AGENTMEMORY_FORCE_PROXY": "1"` do bloku env i ustaw `AGENTMEMORY_URL` na trasę, do której sandbox ma dostęp.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Skopiuj plik pluginu z repozytorium:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Uruchamia się automatycznie na porcie `3113`. Podgląd wczytuje jedną migawkę przy połączeniu (`GET /agentmemory/viewer/snapshot`), a następnie stosuje zdarzenia z żywego strumienia: nowe wspomnienia, lekcje, obserwacje, wpisy audytu, zmiany grafu i aktualizacje stanu pojawiają się bez odpytywania (polling) czy przeładowywania strony. Jedynymi innymi żądaniami są akcje, które klikasz, strony „wczytaj więcej” i wyszukiwania. Gdy strumień się zrywa, podgląd pokazuje, jak nieaktualne są jego dane, ponownie łączy się z narastającym odstępem (backoff) i synchronizuje się od nowa z jednej migawki.
+
+- **12 zakładek w czterech grupach** z licznikami na żywo, głębokimi linkami (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), skrótami klawiszowymi i menu mobilnym.
+- **Wspomnienia:** wyszukiwanie po stronie serwera, filtry po projekcie, agencie i typie, panel szczegółów z łańcuchem wersji i diffem słów, linki pochodzenia, przyciski kopiowania dla id, wywołania MCP i komendy curl, edycja (nowa wersja), zapominanie z potwierdzeniem, masowe zapominanie i eksport JSON.
+- **Sesje:** wbudowana osią czasu obserwacji z czytelnym wejściem i wyjściem narzędzi, filtry i paginacja, a także wspomnienia i lekcje wyprodukowane przez każdą sesję.
+- **Graf:** wyszukiwanie, szczegóły węzła z relacjami i źródłami, legenda niezależna wyłącznie od kolorów oraz kontrolki powiększenia.
+- **Stan (Health):** żywa wersja `GET /agentmemory/status`. Każdy problem ma podany sposób naprawy, a do tego backend stanu, stan zapisu indeksu, postęp kompaktowania pochodzenia grafu oraz objaśnienie konsolidacji z rzeczywistymi progami.
+- **Strony Audyt, Aktywność, Profil, Replay, Lekcje, Akcje i Kryształy**, każda z pustym stanem opisującym, czym jest ta sekcja, czemu jest pusta i jaka komenda ją wypełni, a także podpowiedź słownikowa `?` przy każdym terminie i liczbie.
+
+```bash
+open http://localhost:3113
+```
+
+Serwer podglądu domyślnie wiąże się z `127.0.0.1` i dołącza sekret serwera, gdy przekazuje żądania do REST API, więc nie wymaga żadnej konfiguracji. Endpoint `/agentmemory/viewer` obsługiwany przez REST stosuje normalne zasady tokenu bearer i przekierowuje przeglądarki bez tokenu na port podglądu. Nagłówki CSP używają nonce skryptu per odpowiedź i wyłączają atrybuty handlerów inline (`script-src-attr 'none'`).
+
+---
+
+
+
+Podgląd na `:3113` pokazuje, co twój agent **zapamiętał**. [Konsola iii](https://iii.dev/docs/console) pokazuje, co twój agent **zrobił**: każdą operację pamięci jako trace OpenTelemetry, każdy wpis KV edytowalny, każdą funkcję wywoływalną, każdy strumień podsłuchiwalny. Dwa okna na tę samą pamięć: jedno w kształcie produktu, drugie w kształcie silnika.
+
+Obserwuj, jak `memory_smart_search` się wyzwala, i zobacz skan BM25 → wyszukanie embeddingu → fuzję RRF → reranker jako wodospad (waterfall). Edytuj zablokowany timer konsolidacji w przeglądarce KV. Odtwórz hook `PostToolUse` ze zmodyfikowanym payloadem. Przypnij strumień WebSocket i obserwuj, jak obserwacje spływają na żywo.
+
+agentmemory dostarcza to bezpłatnie, bo każde wywołanie funkcji i trigger przechodzi przez iii; nic niestandardowego, nic do instrumentowania.
+
+
+
+
+ Strona Workers: każdy podłączony worker, w tym sam agentmemory, z PID, liczbą funkcji, środowiskiem wykonawczym i czasem ostatniej aktywności.
+
+
+**Już zainstalowana.** Konsola jest dostarczana z przypiętym silnikiem `iii` (0.22+); nie trzeba niczego instalować osobno. Pierwsze uruchomienie pobiera plik binarny konsoli obok silnika.
+
+**Uruchom razem z agentmemory:**
+
+```bash
+agentmemory console
+```
+
+To uruchamia `iii console` przypiętego silnika względem portów rozwiązanych przez agentmemory (REST, strumienie, mostek) i serwuje ją jeden port nad podglądem, domyślnie `http://localhost:3114`. `--console-port N` wybiera inny port; `--port` i `--instance` wybierają instancję agentmemory tak samo, jak dla `stop`; każda inna flaga jest przekazywana dalej, na przykład `--enable-flow` dla eksperymentalnej strony grafu architektury.
+
+To samo ręcznie, przydatne, gdy `agentmemory` nie jest w PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Co można zrobić z konsoli:**
+
+| Strona | Służy do |
+|------|-----------|
+| **Workers** | Zobaczenia każdego podłączonego workera i jego metryk na żywo, włącznie z samym workerem agentmemory. |
+| **Functions** | Wywołania bezpośrednio każdej funkcji agentmemory z payloadem JSON; przydatne do testowania `memory.recall`, `memory.consolidate`, `graph.query` bez podłączania klienta. |
+| **Triggers** | Odtworzenia triggerów HTTP, cron, zdarzeń i stanu: ręcznego wyzwolenia crona konsolidacji, ponownej próby trasy HTTP, wyemitowania zmiany stanu. |
+| **States** | Przeglądarki KV z pełnym CRUD na sesjach, slotach pamięci, timerach cyklu życia i indeksie embeddingów; edycji wartości w miejscu. |
+| **Streams** | Monitora WebSocket na żywo dla zapisów pamięci, zdarzeń hooków i aktualizacji obserwacji, gdy przepływają przez strumienie iii. |
+| **Queues** | Trwałych tematów kolejek + zarządzania dead-letter. Odtworzenia lub odrzucenia nieudanych zadań embeddingu / kompresji. |
+| **Traces** | Widoków waterfall / flame / rozbicia na usługi OpenTelemetry. Filtrowania po `trace_id`, aby zobaczyć, które funkcje, wywołania bazy danych i żądania embeddingu wyprodukowało jedno `memory.search`. |
+| **Logs** | Ustrukturyzowanych logów OTEL filtrowanych i skorelowanych z ID trace/span. |
+| **Config** | Konfiguracji runtime: zobaczenia dokładnie, z jakimi workerami, dostawcami i portami działa twój silnik. |
+| **Flow** | (Opcjonalnie, `--enable-flow`) Interaktywnego grafu architektury każdego workera, triggera i strumienia. |
+
+
+
+
+ Traces: waterfall / flame / rozbicie na usługi dla każdej operacji pamięci.
+
+
+**Traces są już włączone:**
+
+`iii-config.yaml` jest dostarczany z włączonym workerem `iii-observability` (`exporter: memory`, `sampling_ratio: 0.1`, metryki + logi). Nie jest potrzebna dodatkowa konfiguracja; w momencie, gdy agentmemory się uruchamia, każda operacja pamięci emituje ustrukturyzowany log, który konsola może odczytać, a jedna na dziesięć z nich (`sampling_ratio: 0.1`) emituje też span trace.
+
+Jeśli chcesz zamiast tego eksportować do Jaeger/Honeycomb/Grafana Tempo, zmień `exporter: memory` na `exporter: otlp` i ustaw endpoint kolektora zgodnie z dokumentacją obserwowalności iii.
+
+> **Uwaga:** na samej konsoli nie jest wymuszona autoryzacja; trzymaj ją związaną z `127.0.0.1` (ustawienie domyślne) i nigdy nie wystawiaj jej publicznie.
+
+---
+
+
+
+agentmemory **jest już działającą instancją [iii](https://iii.dev)**. Trzy prymitywy (worker, funkcja, trigger) składają się na środowisko wykonawcze; stan KV, strumienie i trace OTEL pochodzą z workerów iii-state, iii-stream i iii-observability, które są dostarczane z iii. Nie instalowałeś Postgresa, Redisa, Expressa, pm2 ani Prometheusa, bo iii je zastępuje.
+
+To oznacza, że jedna dodatkowa komenda rozszerza agentmemory o całkiem nową możliwość.
+
+### Rozszerz agentmemory o kolejne workery
+
+Wbudowane workery, których potrzebuje agentmemory, są już w `iii-config.yaml` i startują razem z nim: `iii-state` (KV), `iii-queue` (trwałe powtórzenia dla subskrybentów zdarzeń), `iii-pubsub`, `iii-cron`, `iii-stream` i `iii-observability` (trace OTEL, metryki i logi dla każdej funkcji). Wszystko inne z [rejestru workerów iii](https://workers.iii.dev) podłącza się do tego samego silnika: skopiuj `iii-config.yaml` do `~/.agentmemory/iii-config.yaml` (CLI preferuje ten plik nad dołączonym i wciąż renderuje do niego porty i ścieżki danych), dodaj wpis, zainstaluj raz środowisko workera za pomocą `~/.agentmemory/bin/iii update worker` i zrestartuj agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Co zyskujesz oprócz agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Adapter stanu oparty na SQL, gdy wyrośniesz z domyślnego KV w pamięci |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Kod, który wyszedł z `memory_recall`, działa wewnątrz jednorazowej maszyny wirtualnej, a nie w twoim shellu |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Postawienia dodatkowych serwerów MCP obok serwera agentmemory, dzielących ten sam silnik |
+
+Na silniku 0.22.x zachowaj nazwy z prefiksem `iii-` dla powyższych wbudowanych workerów; wpisy bez prefiksu `http`, `state`, `queue`, `pubsub` i `cron` to samodzielne workery z rejestru, na które agentmemory przechodzi w migracji do 0.23.
+
+Pełny rejestr: [workers.iii.dev](https://workers.iii.dev). Każdy worker tam dostępny komponuje się przez te same prymitywy, które wykorzystuje agentmemory, a posiadany już przez ciebie agentmemory jest jednym z nich.
+
+### Konfiguracja silnika i adres bindowania
+
+`agentmemory start` odczytuje konfigurację silnika z pierwszego istniejącego pliku: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` w bieżącym katalogu, `~/.agentmemory/iii-config.yaml`, a następnie dołączony `iii-config.yaml`. Przy każdym starcie renderuje ten plik (ścieżki danych, porty, backend stanu) do `~/.agentmemory/data/iii-config.runtime.yaml` i uruchamia silnik z wyrenderowaną kopią, więc edytuj plik źródłowy, a nie wyrenderowany. Wartości `host:` z pliku źródłowego są zachowywane tak, jak zostały zapisane.
+
+Dołączony `iii-config.yaml` celowo wiąże się z `127.0.0.1`, i to ustawienie domyślne obowiązuje też wewnątrz kontenera. CLI uruchomione w kontenerze słucha na loopbacku kontenera, więc opublikowane porty nie prowadzą do niczego. Aby obsłużyć skonteneryzowane CLI przez opublikowane porty, ustaw `AGENTMEMORY_III_CONFIG` na konfigurację, która wiąże się z `0.0.0.0`. Jedną z nich jest spakowany `iii-config.docker.yaml`: wiąże `iii-http`, `iii-stream` i port silnika z `0.0.0.0` i przechowuje stan pod `/data`, więc zamontuj tam wolumin z prawem zapisu. Trzymaj ustawione `AGENTMEMORY_SECRET` i publikuj tylko te porty, których potrzebujesz, na `127.0.0.1` albo za proxy, któremu ufasz.
+
+`docker-compose.yml` tego repozytorium nie przechodzi przez wyszukiwanie konfiguracji CLI: montuje `iii-config.docker.yaml` pod `/app/config.yaml`, a kontener `iii-engine` startuje z `--config /app/config.yaml`. Jednoklikowe [szablony wdrożeń](../deploy/) zapisują własną konfigurację `0.0.0.0` w swoich punktach wejścia.
+
+### Backend przechowywania: plik (domyślny) kontra redis
+
+`iii-state` i `iii-stream` domyślnie korzystają z dołączonego do iii-engine magazynu KV opartego na plikach: jeden plik JSON na zakres (scope), przechowywany w pamięci procesu silnika i okresowo zapisywany na dysk. To właściwa wartość domyślna dla lokalnej instalacji jednoosobowej; współdzielony daemon z kilkoma równoczesnymi zapisującymi dostaje za to rzeczywiste zapisy per klucz z Redisa, kosztem rundy sieciowej na operację (każde wywołanie `state::*` wciąż serializuje się na jednym połączeniu z Redisem, więc to zamienia blokadę magazynu plikowego na gniazdo sieciowe, a nie na współbieżność).
+
+Ustaw `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`), aby przełączyć oba workery na wbudowany w iii-engine adapter `redis`, który przechowuje każdy klucz jako pole hasha Redisa (`HSET`) zamiast zapisywać cały zakres przy każdym zapisie:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` domyślnie to `file`; nieustawienie tej wartości zachowuje dzisiejsze zachowanie bez zmian, a nierozpoznana wartość (cokolwiek innego niż `file` lub `redis`) to błąd startu, a nie ciche przełączenie zapasowe. `/agentmemory/status` i strona Stan (Health) podglądu (wiersz magazynu stanu) pokazują, który backend jest aktywny i czy odpowiada, nigdy jego URL.
+
+**Tylko zwykłe `redis://`.** Przypięty silnik (0.22.1) buduje swojego klienta Redis bez wsparcia TLS, więc URL `rediss://` (większość zarządzanych ofert Redisa, takich jak Upstash, Redis Cloud i ElastiCache z szyfrowaniem w transporcie, domyślnie wymaga wyłącznie TLS) nie połączy się. Połączenie jest nieszyfrowane, więc hasło do Redisa i każde zapisane wspomnienie przechodzą przez sieć w postaci czystego tekstu: wskazuj na lokalny Redis albo taki w prywatnej sieci, której ufasz. Dla każdego innego Redisa uruchom zaszyfrowany tunel (stunnel, SSH albo VPN) na hoście agentmemory, dzięki czemu zwykłe `redis://` zostaje na tym hoście, a połączenie tunelu w górę jest zaszyfrowane i uwierzytelnione. Jeśli hasło do Redisa zawiera apostrof, zakoduj go procentowo (`%27`); silnik rozwija URL do swojej konfiguracji YAML przed jego sparsowaniem.
+
+**Jeden serwer Redis na `--instance`.** Prefiksy kluczy Redisa silnika (`state:`, `stream::`) są ustalone, więc dwie instancje agentmemory (`--instance 1`, `--instance 2`, ...) wskazujące na tę samą bazę danych nadpisują sobie dane. Osobny indeks bazy danych (`redis://localhost:6379/1`) utrzymuje zapisane dane rozdzielone, ale silnik przekazuje żywe zdarzenia podglądu przez jeden kanał pub/sub Redisa (`stream::events`), a pub/sub Redisa ignoruje indeks bazy danych, więc podgląd każdej instancji wciąż pokazywałby żywe zdarzenia drugiej. Gdy uruchamiasz więcej niż jedną instancję, daj każdej własny serwer Redis (albo port).
+
+**Co się nie zmienia, a co się różni.** Każda funkcja agentmemory działa na Redisie: sesje, obserwacje, wspomnienia (remember, supersede, evolve, forget), wyszukiwanie i paczki indeksu, lekcje, graf, log audytu i jego miesięczne zakresy, eksport i import, usunięcia governance, status konsolidacji, migawka podglądu i jej żywy strumień oraz monitor stanu. Silnik przechowuje każdy zakres jako jeden hash Redisa (`HSET`/`HGET`/`HGETALL`) i wyzwala te same triggery stanu, co magazyn plikowy. Trzy różnice silnika są obsługiwane wewnątrz agentmemory:
+
+- Redis zwraca rekordy zakresu w nieustalonej kolejności. agentmemory sortuje je od najstarszych (według czasu utworzenia zakodowanego w id rekordu, a następnie jego znacznika czasu), dzięki czemu listy, paginacja i fragmenty eksportu wracają w tej samej kolejności, jak w magazynie plikowym.
+- Silnik stosuje częściowe aktualizacje na Redisie w skrypcie Lua, który zamienia puste tablice na puste obiekty. agentmemory stosuje te aktualizacje samodzielnie (odczyt, zmiana, zapis pod blokadą per klucz) na Redisie, dzięki czemu pola takie jak `tags: []` pozostają tablicami.
+- Starsze sprawdzenie logu audytu odczytuje stary zakres z Redisa, zamiast szukać pliku magazynu plikowego na dysku.
+
+Jedna różnica wymaga twojej uwagi: **po restarcie Redisa silnik przestaje przekazywać żywe zdarzenia** do podglądu, dopóki agentmemory się nie zrestartuje. Dane są wciąż normalnie zapisywane i odczytywane. Monitor stanu wysyła testowe zdarzenie przez Redis co 30 sekund; gdy nie wraca, `/agentmemory/status` i strona Stan podglądu pokazują „Live updates are not reaching the viewer” z sugerowaną naprawą: zrestartuj agentmemory. Jeśli Redis nie działa, raport statusu pokazuje „The state store is not answering” oraz sposób sprawdzenia tego (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listowanie bardzo dużego zakresu odczytuje cały hash w jednym `HGETALL`, czyli taki sam koszt, jak trzymanie go w pamięci przez magazyn plikowy.
+
+**Zalecane ustawienia Redisa.** Domyślna polityka migawek `save 3600 1 300 100 60 10000` może stracić minuty zapisów przy awarii, co jest gorsze niż 5-sekundowe okno zapisu magazynu plikowego. Ustaw `appendonly yes` dla wszystkiego, czego strata by cię martwiła. Ustaw `maxmemory-policy noeviction`; `allkeys-lru` lub podobne po cichu usuwają wspomnienia, gdy Redis dojdzie do swojego limitu pamięci.
+
+Natywny start (bez Dockera) i każdy jednoklikowy [szablon wdrożenia](../deploy/) (nadpisują dołączony `iii-config.yaml` i startują natywnie) odczytują `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` i renderują je do uruchamianej `iii-config`. Sam URL nigdy nie jest zapisywany do tego wyrenderowanego pliku, tylko referencja `${AGENTMEMORY_REDIS_URL}`, którą proces silnika rozwija z własnego środowiska przy starcie. Tylko własna ścieżka Docker Compose tego repozytorium (`AGENTMEMORY_USE_DOCKER=1`, albo wznowienie silnika już w ten sposób uruchomionego) montuje `iii-config.docker.yaml` w trybie tylko do odczytu i nigdy nie renderuje; `agentmemory start` ostrzega, gdy wykryje tę kombinację. Zmień ten plik ręcznie, stosując tę samą strukturę `name: redis` / `config: redis_url: ...` pokazaną w dokumentacji workerów [iii-state](https://workers.iii.dev/workers/iii-state) i [iii-stream](https://workers.iii.dev/workers/iii-stream), i wskaż `redis_url` na Redisa dostępnego z kontenera. `docker-compose.yml` przekazuje `AGENTMEMORY_REDIS_URL` do kontenera silnika, więc `redis_url: '${AGENTMEMORY_REDIS_URL}'` działa tam i trzyma URL poza zamontowanym plikiem.
+
+Wyrenderowana konfiguracja trzyma URL poza `~/.agentmemory/data/iii-config.runtime.yaml`, ale własny worker konfiguracji silnika i tak zapisuje trwale *rozwiniętą* wartość do `~/.agentmemory/config/iii-state.yaml` i `iii-stream.yaml`, gdy się uruchamia (rozwijanie `${VAR}` iii-engine zachodzi przed tym, jak ten worker zapisuje swój seed, i zapisuje rozwiązaną wartość, a nie referencję). Traktuj ten katalog jak zawierający dane uwierzytelniające: `chmod 700 ~/.agentmemory` na każdym współdzielonym hoście i preferuj użytkownika ACL Redisa ograniczonego do tego, czego potrzebuje agentmemory, nad danymi administratora bazy.
+
+**Migracja nie jest automatyczna.** Przełączenie `AGENTMEMORY_STATE_BACKEND` zaczyna od pustego magazynu po obu stronach; nic nie kopiuje istniejących danych z pliku do Redisa albo z powrotem. Wyeksportuj z backendu, który opuszczasz, i zaimportuj do tego, na który się przenosisz. To działa identycznie pod bash i zsh (włącznie z `bash -u`). Tablica taka jak `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` już nie: zsh zachowuje nagłówek jako jedno zdeformowane słowo, tam gdzie bash dzieli je na dwa, więc oba żądania zwracają 401, gdy ustawione jest `AGENTMEMORY_SECRET`:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` przyjmuje też `?maxSessions=` i `?offset=` do dzielenia dużego korpusu na kilka wywołań; `strategy` przy imporcie to `merge` (bezpieczna wartość domyślna), `replace` albo `skip`.
+
+### Co zastępuje iii
+
+| Tradycyjny stos | agentmemory używa |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + indeks wektorowy w pamięci |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | nadzór workerów silnika iii |
+| Prometheus / Grafana | iii OTEL + monitor stanu |
+| Niestandardowe systemy pluginów | `iii worker add ` |
+
+**225 plików źródłowych · ~54,000 LOC · 2,600+ testów · 312 funkcji · 66 zakresów KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
+
+---
+
+
+
+### Dostawcy LLM
+
+agentmemory automatycznie wykrywa dostawców na podstawie twojego środowiska. Dostawca udostępnia operacje oparte na LLM, ale samo skonfigurowanie dostawcy nie włącza kompresji obserwacji pisanej przez LLM. Ta ścieżka wymaga zarówno dostawcy, jak i `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Dostawca | Konfiguracja | Uwagi |
+|----------|--------|-------|
+| **No-op (domyślny)** | Konfiguracja niepotrzebna | Kompresja/podsumowywanie oparte na LLM jest wyłączone. Kompresja syntetyczna i przywołanie przez BM25 wciąż działają. Zobacz `AGENTMEMORY_ALLOW_AGENT_SDK` poniżej, jeśli wcześniej korzystałeś z fallbacku na subskrypcję Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Rozliczanie per token |
+| MiniMax | `MINIMAX_API_KEY` | Kompatybilny z Anthropic |
+| Gemini | `GEMINI_API_KEY` | Włącza też embeddingi |
+| OpenRouter | `OPENROUTER_API_KEY` | Każdy model |
+| OpenAI API | `OPENAI_API_KEY` | Domyślnie `gpt-5.6-luna`, nadpisz za pomocą `OPENAI_MODEL` |
+| **Lokalny (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) albo `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Wszystko kompatybilne z API OpenAI. Zerowy koszt, działa na twoim sprzęcie. Zobacz [Modele lokalne](#local-models-ollama--lm-studio--vllm) poniżej. |
+| Fallback na subskrypcję Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Tylko opt-in. Tworzy sesje `@anthropic-ai/claude-agent-sdk`; wcześniej powodowało to nieograniczoną rekursję hooka Stop, więc nie jest to już wartość domyślna. |
+
+### Modele lokalne (Ollama / LM Studio / vLLM)
+
+agentmemory rozmawia z każdym serwerem kompatybilnym z API OpenAI, więc wszystko, co wystawia `/v1/chat/completions`, działa bez zmian w kodzie. Bez płatnych kluczy, bez chmury, bez limitów zapytań; działa całkowicie na twoim sprzęcie.
+
+**Ollama** (domyślny port `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (domyślny port `1234`):
+
+Otwórz LM Studio → zakładka Local Server → Start Server. Wybierz jakikolwiek model czatu z listy (Qwen 3, gpt-oss, DeepSeek R1 itd.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: ta sama struktura. Wskaż `OPENAI_BASE_URL` na URL wystawiany przez twój serwer i ustaw `OPENAI_MODEL` na nazwę, którą twój serwer zaakceptuje.
+
+**Wybór modelu do pracy z pamięcią**: kompresja i podsumowywanie to krótkie zadania (<2K tokenów na wejściu, <500 tokenów na wyjściu), do których w pełni wystarczy model instrukcyjny 7B. Zalecenia:
+
+| Model | Rozmiar | Dlaczego |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Zbalansowana wartość domyślna na maszynie z 16 GB; silny w ekstrakcji i tekście w formie narzędziowej |
+| `qwen3:4b` | ~2.6 GB | Najmniejsza sensowna opcja; dobra do kompresji, słabsza do ekstrakcji grafu |
+| `qwen3-coder:30b` | ~19 GB | Najlepszy lokalny wybór dla sesji o profilu kodu (30B MoE, 3.3B aktywne) na sprzęcie 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Silny model ogólny, który mieści się w 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Dystylat rozumowania; wolniejszy, ale czystsze ekstrakcje |
+
+Modele Qwen 3 domyślnie myślą i mogą spalić cały budżet tokenów na rozumowanie, zanim pojawi się jakiekolwiek wyjście. Ustaw `AGENTMEMORY_LLM_NOTHINK=1`, aby dołączyć `/no_think` do promptów ekstrakcji grafu, i zwiększ `MAX_TOKENS` (16384 działa dobrze), jeśli ekstrakcje wracają puste.
+
+Modele klasy reasoning (w stylu `o1`, z blokami ``) mogą zwracać puste `content` z polem `reasoning`, którego twój lokalny serwer może nie udostępniać. Jeśli ekstrakcje wracają puste, najpierw przełącz się na model bez reasoning. Zmienna środowiskowa `OPENAI_REASONING_EFFORT=none` może też wyłączyć myślenie na modelach myślących Ollama Cloud, które odwzorowują schemat reasoning OpenAI.
+
+Lokalne embeddingi są dostarczane jako opcjonalna zależność, ale nie są włączone domyślnie. Ustaw `EMBEDDING_PROVIDER=local`, aby włączyć `Xenova/all-MiniLM-L6-v2` (384 wymiary). Pierwsze żądanie embeddingu pobiera model; wnioskowanie działa potem lokalnie. Bez tego ustawienia albo zdalnego klucza embeddingów wektory pozostają wyłączone, `mem::search` używa BM25, a `smart-search` może wciąż dodawać istniejące dopasowania z grafu.
+
+### Dobór modelu z uwzględnieniem kosztów
+
+Gdy kompresja w tle pisana przez LLM jest włączona (zarówno dostawca, jak i `AGENTMEMORY_AUTO_COMPRESS=true`), działa przy każdej obserwacji, więc wybór modelu znacząco zmienia miesięczny wydatek. Zebrane dane obciążenia: 635 żądań / 888K tokenów / 35 godzin aktywnego użycia, uruchomione na trzech modelach OpenRouter według cennika z 2026-05-23.
+
+| Poziom | Model | Wejście / 1M | Wyjście / 1M | Koszt za zebrane 35h | Uwagi |
+|------|-------|------------|-------------|---------------------------|-------|
+| Zalecany | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (szac.) | Najnowszy DeepSeek; najtańszy zalecany wybór do zadań kompresji. |
+| Zalecany | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solidna jakość kompresji + podsumowywania przy koszcie ~10× niższym niż Sonnet. |
+| Zalecany | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Silne rozumowanie kodu, jeśli twoje sesje są silnie zorientowane na kod. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (szac.) | Taka sama cena cennikowa, jak w zmierzonym uruchomieniu Sonnet 4.6; wprowadzająca cena $2/$10 do 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (szac.) | Poziom flagowy; drogi dla stale działającej pracy w tle. |
+| Unikać | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (szac.) | Model klasy flagowej; przepłacanie za kompresję. |
+
+Zmierzone wiersze pochodzą z zebranego uruchomienia; wiersze (szac.) skalują ten sam miks tokenów według ceny cennikowej każdego modelu.
+
+agentmemory wypisuje ostrzeżenie w runtime, gdy `OPENROUTER_MODEL` odpowiada wzorcowi poziomu premium. Ustaw `AGENTMEMORY_SUPPRESS_COST_WARNING=1`, aby je wyciszyć, gdy już podejmiesz świadomą decyzję.
+
+Kompromis jakość kontra koszt dla pracy z pamięcią: kompresja to zadanie podsumowujące z relatywnie niskim progiem jakości (podsumowanie czyta ponownie agent, nie użytkownik). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder wypadają w tym zadaniu w granicach błędu zaokrąglenia względem Sonnet, kosztując 10-70× mniej. Modele poziomu premium zachowaj do zapytań, które czytasz bezpośrednio.
+
+Źródła: [cennik OpenRouter dla Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [uwagi o cenniku DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Pamięć wieloagentowa (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+W konfiguracjach wieloagentowych, gdzie kilka ról współdzieli jeden serwer agentmemory (architekt / developer / reviewer / researcher / support-agent), `AGENT_ID` tagguje każdy zapis rolą, która go wykonała. `AGENTMEMORY_AGENT_SCOPE` kontroluje, czy przywołanie filtruje po tym tagu.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Dwa tryby:
+
+| Tryb | Taguje zapisy | Filtruje przywołanie | Kiedy używać |
+|------|------------|---------------|-------------|
+| `shared` (domyślny) | tak | nie | Kontekst między agentami ze ścieżką audytu. Architekt widzi, co zanotował developer, ale każdy wiersz zapisuje, kto to powiedział. |
+| `isolated` | tak | tak | Ścisłe rozdzielenie. Architekt nigdy nie widzi obserwacji / wspomnień / sesji developera. |
+
+Co jest tagowane, gdy ustawiono `AGENT_ID`: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rola przepływa od `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Co jest filtrowane w trybie isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Każdy endpoint przyjmuje `?agentId=`, aby nadpisać to per żądanie, i `?agentId=*`, aby całkowicie zrezygnować z zakresu ze zmiennych środowiskowych. `/memories` przyjmuje też `?includeOrphans=true`, aby ujawnić wspomnienia sprzed `AGENT_ID`, których `agentId` jest niezdefiniowane.
+
+Nadpisanie per wywołanie na poziomie SDK / REST: każdy mutujący endpoint (`/session/start`, `/remember`) przyjmuje w treści żądania pole `agentId`, które wygrywa nad zmienną środowiskową. Przydatne dla środowisk uruchomieniowych routujących wiele ról przez jeden proces serwera. Narzędzie MCP `memory_save` udostępnia to samo pole `agentId`, samodzielny serwer stdio przekazuje dalej zarówno `agentId`, jak i `project`, a zapisane wspomnienia niosą `agentId` do indeksu wyszukiwania, więc wyszukiwanie w zakresie agenta obejmuje zarówno wspomnienia, jak i obserwacje.
+
+Gdy `AGENT_ID` nie jest ustawione, pamięć pozostaje bez zakresu (zachowanie historyczne, brak tagów, brak filtrów).
+
+### Porty
+
+agentmemory + iii-engine domyślnie wiążą cztery porty. Jeśli restart zawiedzie z `port in use`, ta tabela mówi, jakiego procesu szukać.
+
+| Port | Proces | Przeznaczenie | Nadpisanie zmienną środowiskową |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Wewnętrzny worker strumieni (konsumowany przez agentmemory + podgląd) | `III_STREAM_PORT` (preferowane) albo starsze `III_STREAMS_PORT` |
+| `3113` | agentmemory | Podgląd w czasie rzeczywistym (`http://localhost:3113`) | `III_VIEWER_PORT` albo `AGENTMEMORY_VIEWER_URL` dla zgłaszanego URL |
+| `49134` | iii-engine | WebSocket; tu rejestrują się workery, przez niego przepływa telemetria OTel | `III_ENGINE_PORT` albo `III_ENGINE_URL` |
+
+`--port ` zmienia kotwicę REST i wyprowadza strumienie `N+1`, podgląd `N+2` oraz WebSocket silnika `N+46023`, tylko tam, gdzie odpowiadający jej wyraźny port albo URL powyżej nie jest ustawiony. Nie tworzy to osobnej przestrzeni nazw cyklu życia. Użyj `--instance 1` dla drugiego daemona; używa kotwicy 3211, domyślnie `3211/3212/3213/49234`, i otrzymuje osobny katalog danych i cyklu życia `instance-1`. Instancje od 1 do 50 działają według tego samego wzorca.
+
+Przypięty silnik startuje z `--no-update-check` (bez sprawdzania aktualizacji ani wskazówek bezpieczeństwa względem GitHub przy starcie) i z wyłączoną anonimową telemetrią użycia iii: agentmemory ustawia `III_TELEMETRY_ENABLED=false` dla uruchamianego przez siebie silnika, o ile sam nie wyeksportujesz tej zmiennej, a dołączony plik compose robi to samo.
+
+Czyszczenie nieaktualnych procesów, gdy porty pozostają związane po awarii:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` czysto zbiera pidfile workera i silnika przy łagodnym natywnym zamknięciu. W trybie Docker opróżnia natywnego workera, zatrzymuje dokładnie ten zweryfikowany kontener silnika i zachowuje zarówno kontener, jak i jego montowanie `/data` na potrzeby restartu bez utraty danych; kolejny start weryfikuje i wznawia ten sam kontener. Odinstalowanie oparte na Dockerze wymaga `agentmemory remove --keep-data`: usuwa współdzielone pliki zarządzane przez agentmemory, zachowując zweryfikowany kontener, jego montowanie danych i rekord cyklu życia potrzebny do ich odzyskania. Destrukcyjne usunięcie danych Dockera jest celowo pozostawione operatorowi po wykonaniu backupu. CLI odmawia też przejęcia lub zasygnalizowania posiadaczy portów Dockera lub VM (backend Dockera, vpnkit, colima) jako natywnego silnika, jeśli nie podano `--force`. Powyższe ręczne czyszczenie jest tylko na wypadek sytuacji po awarii, gdy nie został po sobie żaden pidfile.
+
+### Plik konfiguracyjny
+
+Umieść konfigurację runtime agentmemory w `~/.agentmemory/.env`, zamiast eksportować zmienne w każdym shellu. Jeśli podgląd pokazuje wskazówkę konfiguracyjną jak `export ANTHROPIC_API_KEY=...`, skopiuj ją do tego pliku jako `ANTHROPIC_API_KEY=...` bez prefiksu `export`, a następnie zrestartuj agentmemory.
+
+Zmienne środowiska procesu wciąż działają i mają pierwszeństwo przed wartościami z pliku.
+
+Na Windows ten sam plik znajduje się w `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Aby testować z subskrypcją Claude Code Pro/Max zamiast klucza API, zdecyduj się na to wyraźnie:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Kompresja obserwacji pisana przez LLM wymaga obu linii: dostępu do dostawcy LLM (włącznie z tym wyraźnym fallbackiem na subskrypcję) oraz `AGENTMEMORY_AUTO_COMPRESS=true`. Sam dostawca pozostawia domyślną ścieżkę kompresji syntetycznej.
+
+Konsolidacja (węzły grafu, lekcje, kryształy) jest domyślnie włączona, gdy skonfigurowano dostawcę LLM. Wyraźnie zrezygnuj za pomocą `CONSOLIDATION_ENABLED=false`, jeśli chcesz działania bez LLM. Ekstrakcja grafu to osobna flaga:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Zmienne środowiskowe
+
+Utwórz `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpointów na porcie `3111`. REST API domyślnie wiąże się z `127.0.0.1`. Chronione endpointy wymagają `Authorization: Bearer `, a endpointy synchronizacji mesh wymagają wyraźnie ustawionego `AGENTMEMORY_SECRET` na obu peerach.
+
+**Autoryzacja jest domyślnie włączona.** Gdy `AGENTMEMORY_SECRET` nie jest ustawione (w shellu albo w `~/.agentmemory/.env`), serwer generuje losowy sekret przy pierwszym starcie i zapisuje go w `~/.agentmemory/secret` z uprawnieniami `0600`. Każdy dołączony klient czyta go z tego miejsca, gdy rozmawia z lokalnym serwerem: CLI, podgląd, hooki w `plugin/scripts`, serwer MCP i shim `@agentmemory/mcp`, konfiguracje zapisywane przez `agentmemory connect` oraz dołączone integracje OpenCode, Pi, OpenClaw, Hermes i filesystem-watchera. Zapisany sekret jest wysyłany tylko na adresy loopback (`localhost`, `127.0.0.0/8`, `::1`). Wyraźnie podane `AGENTMEMORY_SECRET` zawsze wygrywa, a zdalni klienci wciąż muszą mieć je ustawione. Docker i punkty wejścia w `deploy/` już generują i eksportują swój własny sekret. Aby wywołać API ręcznie:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Zasady żądań dla zapisów.** Żądania `POST`, `PUT`, `PATCH` i `DELETE` do REST API i podglądu muszą wysyłać `Content-Type: application/json` (parametr `charset` jest w porządku), kiedy niosą treść, a nagłówek `Origin`, jeśli jest obecny, musi być originem loopback dla skonfigurowanego portu REST albo podglądu, albo być wymieniony w `VIEWER_ALLOWED_ORIGINS` (lista rozdzielona przecinkami, np. `https://memory.example.com`). Klienci, które nie wysyłają nagłówka `Origin` (CLI, hooki, MCP, curl, serwer-do-serwera), nie są tym objęci. Podgląd akceptuje też swój własny origin.
+
+**Ścieżki plików.** Endpointy, które czytają lub zapisują pliki (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), przyjmują tylko ścieżki pod `~/.agentmemory`, katalogiem danych instancji albo katalogiem wymienionym w `AGENTMEMORY_IMPORT_ROOT` (rozdzielaj kilka za pomocą `:`, albo `;` na Windows). `/replay/import-jsonl` przyjmuje też swój domyślny `~/.claude/projects`. `/obsidian/export` zostaje wewnątrz `AGENTMEMORY_EXPORT_ROOT`, a `/migrate` wewnątrz `~/.agentmemory`. Linki symboliczne są rozwiązywane przed każdym sprawdzeniem.
+
+**Czyszczenie sekretów.** Klucze API, tokeny bearer, bloki prywatnych kluczy PEM i dane uwierzytelniające wbudowane w adresy URL (`scheme://user:password@host`) są redagowane (usuwane) przed zapisaniem tekstu, na każdej ścieżce zapisu: obserwacjach, remember, evolve, slotach, lekcjach, akcjach, sketchach, sygnałach, checkpointach, importach, replayu jsonl, synchronizacji mesh, udostępnieniach zespołowych, wyjściu kompresji i podsumowań, kryształach i węzłach grafu.
+
+
+Kluczowe endpointy
+
+| Metoda | Ścieżka | Opis |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Kontrola stanu (zawsze publiczna) |
+| `GET` | `/agentmemory/status` | Co jest nie tak i jak to naprawić (HTML dla przeglądarek, w innym wypadku JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Wszystko, co pokazuje podgląd, w jednej odpowiedzi |
+| `POST` | `/agentmemory/session/start` | Rozpoczyna sesję + pobiera kontekst |
+| `POST` | `/agentmemory/session/end` | Kończy sesję |
+| `POST` | `/agentmemory/observe` | Przechwytuje obserwację (zobacz dostawę przechwytywania poniżej) |
+| `GET` | `/agentmemory/capture` | Skrzynka przechwytywania, dead lettery i spool offline |
+| `POST` | `/agentmemory/capture/retry` | Ponawia przechwycenia dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Wysyła teraz lokalny spool offline |
+| `POST` | `/agentmemory/smart-search` | Wyszukiwanie hybrydowe |
+| `POST` | `/agentmemory/context` | Generuje kontekst |
+| `POST` | `/agentmemory/remember` | Zapisuje do pamięci długotrwałej |
+| `POST` | `/agentmemory/forget` | Usuwa obserwacje |
+| `POST` | `/agentmemory/enrich` | Kontekst plikowy + wspomnienia + błędy |
+| `GET` | `/agentmemory/profile` | Profil projektu |
+| `GET` | `/agentmemory/export` | Eksportuje wszystkie dane |
+| `POST` | `/agentmemory/import` | Importuje z JSON |
+| `POST` | `/agentmemory/graph/query` | Odpytanie grafu wiedzy |
+| `POST` | `/agentmemory/graph/compact` | Przycina nadmiarowe pochodzenie grafu |
+| `POST` | `/agentmemory/team/share` | Udostępnia zespołowi |
+| `GET` | `/agentmemory/audit` | Ścieżka audytu |
+
+Pełna lista endpointów: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Dostawa przechwytywania.** Hooki wysyłają każdą obserwację raz do `POST /agentmemory/observe` z `eventId`. Jest to własny id hosta dla tego wywołania, gdy payload go ma (na przykład `tool_use_id` Claude Code), albo w innym wypadku hash sesji, typu hooka, nazwy narzędzia, wejścia, wyjścia i znacznika czasu hosta. Serwer zapisuje zdarzenie do skrzynki przechwytywania w magazynie stanu, zapisuje obserwację, a następnie usuwa wpis ze skrzynki. Kod statusu mówi, co się stało:
+
+| Status | Pole `status` | Znaczenie |
+|---|---|---|
+| `201` | `accepted` | Zapisano. `observationId` to nowa obserwacja. |
+| `202` | `accepted` (`state: "retrying"`) | Zaakceptowano, ale zapis się nie powiódł. Serwer ponawia, również po restarcie. |
+| `200` | `duplicate` | Ten `eventId` był już zaakceptowany. `observationId` to istniejąca obserwacja; nic nowego nie zostaje zapisane. |
+| `400` / `422` | `rejected` | Nieprawidłowy payload, albo zapis nie powiódł się ostatecznie (zdarzenie jest zachowane jako dead letter). |
+| `503` | `rejected` (`retryable: true`) | Skrzynka jest pełna (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooki umieszczają zdarzenie w spoolu i wysyłają je później. |
+
+Nieudane zdarzenia są ponawiane co `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) z podwajającym się odstępem (backoff), do `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Zdarzenia, które wciąż zawodzą, zostają w skrzynce jako dead lettery, są wymienione na `/agentmemory/status` i stronie Stan podglądu, i mogą być ponowione za pomocą `POST /agentmemory/capture/retry` (`{"eventId": "..."}` albo `{"all": true}`). Zaakceptowane id zdarzeń są pamiętane przez `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 godzin, maksymalnie `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), więc hook odtworzony po timeoucie albo restarcie jest zapisany raz, natomiast dwa osobne wywołania narzędzia z własnymi id hosta są zapisywane dwukrotnie, nawet gdy ich treść jest identyczna. Gdy obserwacja jest usuwana (forget, usunięcie sesji, eviction, auto-forget albo import, który zastępuje magazyn), jej zdarzenie jest oznaczane jako usunięte przed usunięciem obserwacji, więc odtworzenie tego zdarzenia w tym samym oknie jest traktowane jako duplikat i nic nie zapisuje. Magazyn stanu zapisuje na dysk co 2 sekundy, więc odpowiedziane zdarzenie może przez chwilę istnieć jeszcze tylko w pamięci. Aby to pokryć, każda odpowiedź `2xx` niesie też `bootId` serwera (nowy przy każdym starcie), `acceptedAt` i `durableAfterMs` (odstęp zapisu plus 1.5 s w magazynie plikowym, 1.5 s na redisie, gdzie trwałość jest ustawieniem operatora). Hooki trzymają zdarzenie w lokalnym spoolu, dopóki to okno nie minie, i usuwają je przy kolejnym wywołaniu, bez dodatkowego żądania. Jeśli `bootId` zmienił się do tego czasu, serwer zrestartował się, więc hook wysyła zdarzenie ponownie z tym samym `eventId`; zdarzenie, które dotarło na dysk, nie jest zapisywane dwukrotnie. Serwer sam wysyła też takie zdarzenia przy starcie i w każdym interwale ponowień, więc restart niczego nie gubi, nawet jeśli potem żaden hook nie zostanie uruchomiony. Starsze hooki ignorują dodatkowe pola, a nowe hooki wobec starszego serwera odrzucają zdarzenie przy `2xx` jak dawniej.
+
+Gdy serwer jest wyłączony, nie odpowiada w czasie albo zwraca 5xx, hook dopisuje obserwację do lokalnego pliku spool, `/capture-spool/-.jsonl` (nadpisz folder za pomocą `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Plik jest prywatny dla twojego użytkownika (uprawnienia 600), sekrety są redagowane w ten sam sposób, w jaki redaguje je serwer, zawiera maksymalnie `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) i odrzuca wpisy starsze niż `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Gdy jest pełny, nowe wpisy są odrzucane i zliczane, a `/agentmemory/status` to raportuje. Hook wciąż kończy się kodem 0 w ramach swojego limitu czasu i nie dodaje żadnego żądania, gdy serwer jest zdrowy. Spool jest wysyłany przy następnym starcie i przez pierwszy hook, który ponownie dotrze do serwera, w procesie w tle, więc agent nie czeka. Id zdarzeń zapewniają bezpieczeństwo tego mechanizmu: obserwacja, która dotarła przed timeoutem, nie jest zapisywana dwukrotnie. `npx @agentmemory/agentmemory capture` pokazuje spool i skrzynkę serwera, `--drain` wysyła spool teraz, a `GET /agentmemory/capture` zwraca to samo jako JSON. Ustaw `AGENTMEMORY_CAPTURE_SPOOL=false`, aby wyłączyć spool.
+
+**Kompaktowanie pochodzenia grafu.** Każdy węzeł i krawędź grafu wiedzy przechowuje id 32 najnowszych obserwacji, z których powstał. Magazyny zapisane przed tym limitem mogą mieć tysiące id na gorący węzeł, co spowalnia wyszukiwanie w grafie i podgląd albo zrzuca workera. agentmemory naprawia to samodzielnie: przy pierwszym starcie po aktualizacji przycina w tle każdy węzeł, krawędź, zastąpioną krawędź (temporalna historia grafu) i zbuforowaną migawkę do limitu, w małych fragmentach z przerwą między nimi, dzięki czemu wyszukiwanie, przechwytywanie i podgląd nadal działają. Zapisuje swój postęp, wznawia po restarcie i nigdy nie uruchamia się ponownie, gdy już skończy. `/agentmemory/status` i strona Stan podglądu pokazują to jako pending, running (z bieżącym zakresem i pozycją), done albo failed. Ustaw `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`, aby to wyłączyć.
+
+Aby uruchomić to ręcznie, wywołaj `POST /agentmemory/graph/compact`. Przechodzi przez indeksy nazw i kluczy krawędzi, zamiast listować każdy węzeł i krawędź, i jest bezpieczne do wielokrotnego uruchomienia. Gdy przycina id, zapisuje wpis audytu `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Na dużym magazynie, albo gdy wywołanie zwraca 504, uruchom to we fragmentach. Wyślij `scope` (`nodes`, `edges` albo `history`), `offset` i `limit`, a potem wywołaj znowu ze zwróconym `nextOffset`, aż będzie `null`. Zrób to dla `nodes`, `edges` i `history`, a zakończ jednym wywołaniem `{"scope":"snapshot"}`, bo uruchomienie we fragmentach nie dotyka zbuforowanej migawki.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Wymagania wstępne:** Node.js >= 20 z npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 albo Docker. Automatyczna instalacja silnika na macOS/Linux wymaga też `curl`, POSIX-owego `sh` i `tar`; natywny Windows używa ręcznie przypiętego `iii.exe`, WSL2 albo Docker Desktop.
+
+
Seu agente de codificação lembra de tudo. Chega de re-explicar.
- Built on iii engine
+ Construído sobre iii engine
- Memória persistente para Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualquer cliente MCP.
+ Memória persistente para Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualquer cliente MCP.
@@ -75,21 +96,33 @@
## Install
-Um único comando:
+Requisitos:
+
+- Node.js 20 ou mais recente, com npm e npx (`node -v`, `npm -v` e `npx -v`).
+- A instalação automática do iii-engine no macOS/Linux também precisa de `curl`, um `sh` POSIX e `tar`. Imagens mínimas como `node:20-slim` podem não incluí-los.
+- O Windows nativo exige que o `iii.exe` da versão fixada do iii-engine v0.22.1 seja instalado manualmente. WSL2 ou Docker Desktop são os outros caminhos suportados.
+
+Comando canônico para instalação do zero:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-A primeira execução é um setup interativo: escolha os agentes a conectar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), escolha um provider de LLM ou fique sem chave, e ele semeia a configuração, inicia o servidor de memória em `:3111` e se oferece para instalar globalmente, de modo que o comando `agentmemory` simples funcione em qualquer lugar depois.
+A primeira execução é um setup interativo: escolha os agentes a conectar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), escolha um provider de LLM ou fique sem chave, e ele semeia a configuração, inicia o servidor de memória e o seu iii engine fixado, e se oferece para instalar globalmente, de modo que o comando `agentmemory` simples funcione em qualquer lugar depois. O `-y` aceita o prompt de pacote do npx e o `@latest` evita um release antigo em cache. Um provider libera os recursos de LLM, mas a compressão de observações escrita por LLM só começa quando `AGENTMEMORY_AUTO_COMPRESS=true` também está definido.
+
+O modo sem chave desativa os embeddings vetoriais. O `memory_recall` (o caminho `mem::search`) usa BM25, enquanto o `memory_smart_search` também pode combinar correspondências estruturais do grafo quando já existem dados de grafo. Para recall semântico gratuito e no dispositivo, defina `EMBEDDING_PROVIDER=local` em `~/.agentmemory/.env` e reinicie. A primeira requisição de embedding baixa o `Xenova/all-MiniLM-L6-v2`; a inferência roda localmente depois desse download inicial do modelo.
+
+O runtime local usa quatro portas: `3111` para REST/MCP HTTP, `3112` para os streams do iii, `3113` para o viewer e `49134` para o WebSocket do worker iii. O estado persistente do iii mora em `~/Library/Application Support/agentmemory` no macOS, em `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` no Linux, e em `%APPDATA%\agentmemory` no Windows. Use `--data-dir ` ou `AGENTMEMORY_DATA_DIR` para sobrescrever isso, e reutilize o mesmo valor em cada reinício. Por compatibilidade retroativa, um `./data/state_store.db` ou `./data/iii-config.yaml` já existente tem precedência sobre o padrão da plataforma para a instância 0; uma flag explícita ou override de ambiente ainda prevalece.
Depois prove que o recall funciona e dê ao seu agente as skills dele:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
+As buscas por palavra-chave devem acertar no modo sem chave padrão, via BM25. A query `database performance optimization` do demo é intencionalmente semântica e pode retornar zero até que um provider de embedding seja configurado.
+
Prefere deixar um agente de codificação fazer tudo? Entregue a ele uma única instrução:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
@@ -99,7 +132,7 @@ Conecte mais agentes a qualquer momento com `agentmemory connect ` — 20
Windows
-O caminho rápido é o WSL2. O setup nativo do engine no Windows é manual (cerca de 10 a 20 minutos) e `agentmemory connect` atualmente não é suportado lá. Veja as [notas de Windows](#windows) para o passo a passo.
+O caminho rápido é o WSL2. O setup nativo do engine no Windows exige que o ZIP fixado da v0.22.1 seja baixado e o `iii.exe` extraído manualmente; o CLI não o extrai automaticamente. O Docker Desktop também é suportado. Veja as [notas de Windows](#windows) para o passo a passo.
@@ -107,11 +140,11 @@ O caminho rápido é o WSL2. O setup nativo do engine no Windows é manual (cerc
Instalação global / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+O comando npx acima continua sendo o caminho canônico de instalação do zero e evita problemas de permissão de prefixo global.
+
@@ -124,7 +157,7 @@ O npx faz cache por versão. Force a mais recente com `npx -y @agentmemory/agent
Já roda seu próprio engine iii
-agentmemory fixa o iii-engine em v0.11.2 e não se conecta a uma versão diferente (o worker não fala o protocolo de outro engine). Pare o outro engine e rode `npx -y @agentmemory/agentmemory@latest`. Ele instala e executa a v0.11.2 fixada em `~/.agentmemory/bin`, deixando o seu próprio `iii` intocado.
+agentmemory fixa o iii-engine em v0.22.1 e não se conecta a uma versão diferente (o worker não fala o protocolo de outro engine). Pare o outro engine e rode `npx -y @agentmemory/agentmemory@latest`. Ele instala e executa a v0.22.1 fixada em `~/.agentmemory/bin`, deixando o seu próprio `iii` intocado.
@@ -136,88 +169,139 @@ agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Tod
@@ -227,15 +311,24 @@ agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Tod
---
-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.
+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 entre 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 e sem copiar e colar.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **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).
+Por padrão, agentmemory guarda o estado do iii-engine fora do repositório a partir do qual você o inicia: `~/Library/Application Support/agentmemory` no macOS, `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` no Linux, e `%APPDATA%\agentmemory` no Windows. Um `./data/state_store.db` ou `./data/iii-config.yaml` legado já existente é reutilizado para a instância 0 antes desse padrão da plataforma. Para escolher um local explicitamente, passe `--data-dir ` ou defina `AGENTMEMORY_DATA_DIR`; qualquer uma das duas opções explícitas tem precedência sobre a descoberta legada:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Execuções nativas e via Docker usam esse mesmo diretório-host resolvido; o Docker monta esse bind em `/data`. `--instance 1` acrescenta `instance-1` ao diretório resolvido e seleciona o quarteto de portas padrão separado `3211/3212/3213/49234`.
+
+Notas da última versão: [CHANGELOG.md](../CHANGELOG.md).
---
@@ -401,7 +494,7 @@ Taxa de acerto top-5 de 100% no **teto matemático de P@5** deste corpus (0.240,
Gerenciado pelo agente
Manual
Auto-esquecimento
-
Revisão manual; roteamento automático em desenvolvimento
+
Revisão manual; roteamento automático em andamento
Nenhum
Não informado
Decaimento + consolidação
@@ -409,20 +502,20 @@ Taxa de acerto top-5 de 100% no **teto matemático de P@5** deste corpus (0.240,
Eficiência de tokens
-
~1.900 tokens/sessão ($10/ano)
-
Varia conforme a integração
+
~1,900 tokens/sessão ($10/ano)
+
Varia por integração
Memória principal no contexto
Varia
-
Preços de nuvem
+
Precificação em nuvem
Não informado
-
Sem token budget
-
Com LLM (varia)
+
Sem orçamento de tokens
+
Baseado em LLM (varia)
Varia
-
22K+ tokens com 240 obs
+
22K+ tokens em 240 observações
Viewer em tempo real
-
Sim (port 3113)
+
Sim (porta 3113)
Dashboard na nuvem
Dashboard na nuvem
Web UI
@@ -450,12 +543,12 @@ Taxa de acerto top-5 de 100% no **teto matemático de P@5** deste corpus (0.240,
Nota de benchmark: apenas o R@5 do agentmemory é resultado medido por nós mesmos (LongMemEval-S, reproduzível a partir de benchmark/COMPARISON.md). Os números de mem0 e Letta são os números LoCoMo publicados por eles (um dataset diferente); os números de MemPalace, supermemory, TencentDB (PersonaMem) e oracleagentmemory são alegações autorreportadas dos fornecedores que não reproduzimos de forma independente (a execução do oracleagentmemory usou GPT-5.5 contra um Oracle AI Database). Mostrados lado a lado apenas como ordem de grandeza, não como comparação direta sobre dados idênticos. As contagens de stars são aproximadas e mudam com o tempo.
-**Novos entrantes** que vale conhecer, comparados em profundidade em [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+**Novos entrantes** que vale a pena conhecer, comparados em profundidade em [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
-| Sistema | ⭐ | Ângulo |
+| Sistema | ⭐ | Abordagem |
|--------|---|-------|
-| Zep / Graphiti | 30K | Grafo de conhecimento temporal; resultados publicados mais fortes em queries temporais (LongMemEval 63.8%), mas o grafo é construído de forma assíncrona, então fatos recentes podem atrasar |
-| Cognee | 30K | Ingestão de documento para grafo de conhecimento, somente Python, feito para extração estruturada de entidades em vez de captura de sessões |
+| Zep / Graphiti | 30K | Grafo de conhecimento temporal; os resultados publicados mais fortes em queries temporais (LongMemEval 63.8%), mas o grafo é construído de forma assíncrona, então fatos recentes podem atrasar |
+| Cognee | 30K | Ingestão de documento para grafo de conhecimento, somente Python, feito para extração estruturada de entidades em vez de captura de sessão |
Nenhum deles faz captura automática a partir de hooks de agentes de codificação, entrega um viewer local-first ou roda sem chave — a combinação em torno da qual o agentmemory foi construído.
@@ -463,73 +556,98 @@ Nenhum deles faz captura automática a partir de hooks de agentes de codificaç
-Compatibilidade: este release tem como alvo o `iii-sdk` estável `^0.11.0` e o iii-engine v0.11.x.
+Compatibilidade: esta versão usa `iii-sdk` 0.22.1 e fixa o iii-engine na v0.22.1.
-### Experimente em 30 segundos
+### Teste em 30 segundos
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest 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.
+`demo` semeia 3 sessões realistas (autenticação JWT, correção de query N+1, rate limiting) e roda buscas contra elas. Instalações sem chave desativam os vetores, então as buscas por palavra-chave do `mem::search` devem acertar via BM25, enquanto `database performance optimization` pode retornar zero. O `smart-search` também pode retornar correspondências estruturais do grafo quando existem dados de grafo. Para que a query semântica encontre a correção de N+1 via vetores, defina `EMBEDDING_PROVIDER=local`, reinicie e espere o primeiro download do modelo terminar.
Abra `http://localhost:3113` para acompanhar a memória sendo construída ao vivo.
+### Valide uma instalação nova e a persistência ao reiniciar
+
+Com o servidor em execução, valide o REST, o health, o viewer e o status do runtime baseado em iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+O painel de pronto de inicialização contabiliza as quatro portas: REST/MCP HTTP na 3111, streams do iii na 3112, o viewer na 3113 e o WebSocket do worker iii na 49134. `status` confirma a saúde do agentmemory e o provider/modo de embedding ativo. Salve uma sonda e confirme que ela é pesquisável:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Depois rode `npx -y @agentmemory/agentmemory@latest stop`, inicie novamente o comando canônico no Terminal 1, espere por `/agentmemory/livez` e repita a busca. A sonda deve continuar sendo retornada. Se você selecionou um `--data-dir` customizado, passe o mesmo diretório no reinício.
+
### Comandos do dia a dia
-Instalação e setup ficam em [Install](#install) acima (a primeira execução guia você pelo processo). No dia a dia:
+Instalação e setup estão em [Install](#install) acima (a primeira execução te guia por eles). No dia a dia:
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
-### Session Replay
+### Replay de sessão
-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,5x a 4x) e atalhos de teclado (espaço para alternar, setas para avançar passo a passo).
+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 de tools e respostas renderizam como eventos discretos com play/pause, controle de velocidade (0.5x a 4x) e atalhos de teclado (espaço para alternar, setas para avançar passo a passo).
-Para trazer transcripts JSONL antigos do Claude Code:
+Para trazer transcripts JSONL mais antigos do Claude Code:
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest 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. Cada transcript importado é indexado para busca, carimbado com o canal de origem `import` e minerado para gerar um crystal de sessão e lessons.
+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. Cada transcript importado é indexado para busca, carimbado com o canal de origem `import` e minerado para gerar um crystal de sessão e lessons.
> **Atenção se você depende do `import-jsonl` como caminho primário de captura:** o `cleanupPeriodDays` do Claude Code (em `~/.claude/settings.json`, padrão **30**) apaga automaticamente de `~/.claude/projects/` os transcripts JSONL mais antigos que essa janela. Se você instalar o agentmemory do zero sobre um histórico de Claude Code com meses de idade, tudo com mais de 30 dias já se foi antes do primeiro import. Rode `import-jsonl` em um cron, aumente `cleanupPeriodDays` para algo maior, ou conecte os hooks de captura automática (o caminho padrão de instalação do plugin) para que cada turno chegue ao agentmemory enquanto a sessão está viva e a limpeza dos JSONL deixe de importar.
-### Atualização / Manutenção
+### Upgrade / Manutenção
-Use o comando de manutenção quando você intencionalmente quiser atualizar seu runtime local:
+Use o comando de manutenção quando você quiser intencionalmente atualizar seu runtime local:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Aviso: este comando muta o workspace/runtime atual. Pode atualizar dependências JavaScript e puxar a imagem Docker fixada `iiidev/iii:0.11.2`. Nunca instala um engine iii sem fixação ou mais recente.
+Aviso: este comando altera o workspace/runtime atual. Ele pode atualizar dependências JavaScript e baixar a imagem Docker fixada `iiidev/iii:0.22.1`. Ele nunca instala um iii engine não fixado ou mais novo.
-Detalhes de implementação estão em `src/cli.ts` (veja `runUpgrade` na região `src/cli.ts:544-595`).
+Detalhes de implementação estão em `src/cli.ts` (veja `runUpgrade` em torno da região `src/cli.ts:544-595`).
-### Claude Code (um bloco, cole)
+### Claude Code (um bloco só, cole e vá)
```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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code 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.
+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.22/scripts/…`), então a próxima atualização quebra silenciosamente todos os hooks.
Contorno:
@@ -544,38 +662,52 @@ Para deploys remotos ou protegidos, inicie o Claude Code com `AGENTMEMORY_URL` e
```bash
# 1. start the memory server in a separate terminal
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```
-O plugin do Codex é servido a partir do mesmo diretório `plugin/` do plugin do Claude Code. Ele registra:
+O plugin do Codex é entregue a partir do mesmo diretório `plugin/` do plugin do Claude Code. Ele registra:
-- `@agentmemory/mcp` como servidor MCP (faz proxy de todas as 54 tools quando `AGENTMEMORY_URL` aponta para um servidor agentmemory em execução; cai para 7 tools localmente quando não há servidor acessível)
+- Uma bridge MCP via stdio empacotada para o daemon em execução, sem download via npm nem armazenamento de fallback. Veja o [guia local do Codex](../docs/plugins/codex-local.md) para testar uma build ainda não lançada.
- 6 hooks de ciclo de vida: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
-- 9 skills invocáveis: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, mais 8 skills de referência que o agente carrega sob demanda (memory discipline, tools MCP, REST API, config, agentes, hooks, arquitetura e o guia de autoria de skills)
+- 9 skills invocáveis: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, mais 8 skills de referência que o agente carrega sob demanda (disciplina de memória, tools MCP, REST API, config, agentes, hooks, arquitetura e o guia de autoria de skills)
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)
+#### Confiança e compatibilidade dos hooks do Codex
-`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.
+O despacho nativo de hooks de plugin está verificado com o Codex CLI 0.150.1. Confie nos hooks do plugin antes de esperar captura. O comportamento no Desktop depende do runtime empacotado dele; verifique `/hooks` e confirme um evento capturado antes de habilitar um contorno.
-Até que o upstream corrija, espelhe os mesmos comandos de hook no `~/.codex/hooks.json` global:
+Se o seu host exigir hooks globais, espelhe os comandos em `~/.codex/hooks.json`. Quando o MCP já está configurado, o conector atual precisa de `--force` para chegar à instalação dos hooks:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-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.
+Isso mescla os hooks globais e reescreve a entrada MCP do agentmemory, preservando as entradas não relacionadas. Revise quaisquer configurações customizadas de endpoint do agentmemory antes de usar `--force`. Rode novamente após atualizar para atualizar os caminhos dos scripts. Habilite os hooks nativos do plugin ou as cópias globais para evitar captura duplicada.
+
+### GitHub Copilot CLI
+
+Para o modo agente do VS Code, use o [guia de MCP e captura automática do Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). O conector do CLI não configura o VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` mescla `mcpServers.agentmemory` em `~/.copilot/mcp-config.json` (ou `$COPILOT_HOME/mcp-config.json` quando `COPILOT_HOME` está definido) e preserva os servidores existentes. No Windows nativo este é o único adaptador `connect` automatizado; configure todo outro agente nativo do Windows manualmente. O `connect` no WSL só é suportado quando o agente de destino está instalado nesse mesmo ambiente WSL. O Copilot detecta o servidor MCP no próximo lançamento ou depois de `/mcp`. Instale o plugin também quando quiser a experiência completa de hooks/skills.
OpenClaw (cole este prompt)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -600,7 +732,7 @@ Guia completo: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (cole este prompt)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -619,7 +751,7 @@ Guia completo: [`integrations/hermes/`](../integrations/hermes/)
### Outros agentes
-Inicie o servidor de memória: `npx @agentmemory/agentmemory`
+Inicie o servidor de memória: `npx -y @agentmemory/agentmemory@latest`
#### Skills nativas via `npx skills add` (50+ agentes)
@@ -640,7 +772,7 @@ Para os poucos agentes que o CLI de skills ainda não cobre (Zed v1.3.x e anteri
#### Bloco MCP padrão
-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):
+A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que usa o formato `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
```json
"agentmemory": {
@@ -653,40 +785,42 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que u
}
```
-**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).
+**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 existir, 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 única entrada cabeada cobre tanto deploys locais quanto remotos (k8s / com reverse-proxy).
-| Agente | Arquivo de configuração | Notas |
+| Agente | Arquivo de config | 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. |
+| **Cursor (somente MCP)** | `~/.cursor/mcp.json` | Mescle em `mcpServers`, ou `agentmemory connect cursor`. Deeplink de um clique também disponível no site. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Listagem no Cursor Marketplace (submissão em análise) ou Cursor Settings → Plugins → checkout local. Registra 7 hooks de captura automática (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + o servidor MCP, com `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` gerenciados no dashboard de plugins do Cursor. Funciona na IDE do Cursor e no CLI `cursor-agent`; prompts do modo print do CLI são preenchidos retroativamente a partir do transcript da sessão no fim da sessão. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Mescle em `mcpServers`. Reinicie o Claude Desktop depois de editar. |
| **Cline / Roo Code / Kilo Code** | Configurações MCP do Cline (Settings UI → MCP Servers → Edit) | Mesmo bloco `mcpServers`. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` mescla a entrada MCP; `--with-hooks` adiciona seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) com os matchers de ferramentas em minúsculas do Devin. Verifique com `devin mcp list` e `/hooks` dentro do devin. |
-| **Devin (nuvem)** | Settings → Connections → MCP servers | Adicione um MCP personalizado (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` apontando para um deployment de agentmemory acessível pela rede mais `AGENTMEMORY_SECRET` (sessões na nuvem não alcançam localhost — veja [`deploy/`](../deploy/)). |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` mescla a entrada MCP; `--with-hooks` adiciona seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) com os matchers de ferramentas em minúsculas do Devin. Verifique com `devin mcp list` e `/hooks` dentro do devin. |
+| **Devin CLI (plugin completo)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` a partir de um checkout registra todas as 17 skills como slash commands `/agentmemory:` mais o servidor MCP. Hooks de plugin do Devin não conseguem disparar `SessionStart`/`SessionEnd`, então combine com `connect devin --with-hooks` para captura completa de sessão. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Adicione um MCP customizado (STDIO): comando `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` apontando para um deploy do agentmemory alcançável pela rede, mais `AGENTMEMORY_SECRET` (sessões na cloud não conseguem alcançar localhost — veja [`deploy/`](../deploy/)). Guarde o secret nos Devin Secrets, depois use "Test listing tools" para verificar que as 54 tools aparecem. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (mescla automaticamente). |
-| **GitHub Copilot CLI (somente MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` mescla `mcpServers.agentmemory`; o Copilot o reconhece no próximo launch ou via `/mcp`. |
+| **GitHub Copilot CLI (somente MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` mescla `mcpServers.agentmemory`; o Copilot detecta no próximo lançamento ou em `/mcp`. |
| **GitHub Copilot CLI (plugin completo)** | Instalação de plugin do Copilot | `copilot plugin install rohitg00/agentmemory:plugin` para o plugin a partir do subdiretório do GitHub. |
-| **OpenClaw** | Configuração MCP do OpenClaw | Mesmo bloco `mcpServers`. Mais profundo: `openclaw plugins install ./integrations/openclaw` reivindica o slot de memória do OpenClaw (alterna automaticamente de `memory-core`); defina `plugins.entries.agentmemory.hooks.allowConversationAccess=true` ou a captura de turnos fica bloqueada silenciosamente. Veja [`integrations/openclaw`](integrations/openclaw/). |
+| **OpenClaw** | Configuração MCP do OpenClaw | Mesmo bloco `mcpServers`. Mais profundo: `openclaw plugins install ./integrations/openclaw` reivindica o slot de memória do OpenClaw (alterna automaticamente de `memory-core`); defina `plugins.entries.agentmemory.hooks.allowConversationAccess=true` ou a captura de turnos fica bloqueada silenciosamente. Veja [`integrations/openclaw`](../integrations/openclaw/). |
| **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) + 17 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. A atribuição de projeto é por sessão, então um único processo do OpenCode abrangendo vários repositórios arquiva cada sessão sob o próprio projeto. 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` | `agentmemory connect pi` instala a extensão empacotada no diretório de auto-descoberta do pi (recall no início do agente, captura no fim do agente, tools `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` em um pi em execução a reconhece. [`integrations/pi`](../integrations/pi/) também é um pacote pi (`pi install ./integrations/pi` a partir de um checkout). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ativa o memory provider de 6 hooks (prefetch, captura de turnos, fim de sessão, pré-compressão, espelhamento do MEMORY.md, bloco de system prompt). Valide com `hermes plugins doctor` e `hermes memory status`. Veja [`integrations/hermes`](integrations/hermes/). |
+| **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 + 17 skills. Confie nos hooks e verifique a captura no seu host; veja [configuração e validação do Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (somente MCP)** | `opencode.json` | Formato diferente: chave de nível superior `mcp`, 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. A atribuição de projeto é por sessão, então um único processo do OpenCode abrangendo vários repositórios arquiva cada sessão sob o próprio projeto. Dois slash commands (`/recall`, `/remember`). Copie `plugin/opencode/` para o seu workspace do OpenCode e adicione a entrada do plugin em `opencode.json`. Veja [`plugin/opencode/README.md`](../plugin/opencode/README.md) para a tabela completa de hooks + análise de gaps. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instala a extensão empacotada no diretório de auto-descoberta do pi (recall no início do agente, captura no fim do agente, tools `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` em um pi em execução reconhece a extensão. [`integrations/pi`](../integrations/pi/) também é um pacote pi (`pi install ./integrations/pi` a partir de um checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ativa o memory provider de 6 hooks (prefetch, captura de turnos, fim de sessão, pré-compressão, espelhamento do MEMORY.md, bloco de system prompt). Valide com `hermes plugins doctor` e `hermes memory status`. Veja [`integrations/hermes`](../integrations/hermes/). |
| **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; conecte-os via a 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. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. O CLI `agy` mantém a própria configuração em `~/.gemini/`, separada do Antigravity IDE acima. Passe `--with-hooks` para captura automática nativa via `~/.gemini/config/hooks.json`. |
-| **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. |
-| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` escreve o bloco `mcpServers` padrão. O Warp também auto-descobre skills de `.claude/skills/`; instalado o plugin do Claude Code, as 8 skills do agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecem nativamente na paleta de comandos slash do Warp. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instala o MCP e os hooks de captura no diretório de customização compartilhado. Veja [configuração e limites do Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` usa a mesma configuração de MCP e hooks das versões atuais do IDE. Instalações existentes devem atualizar com `--force`; veja as [notas de atualização](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` escreve a configuração no nível de usuário. Overrides de workspace vão em `.kiro/settings/mcp.json` ao lado do seu código. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` escreve o bloco `mcpServers` padrão. O Warp também auto-descobre skills de `.claude/skills/`; instalado o plugin do Claude Code, as 8 skills do agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecem nativamente na paleta de slash commands do Warp. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` escreve o bloco `mcpServers` padrão. Usuários da extensão do VS Code: cole o mesmo bloco via Cline Settings → MCP Servers → Edit JSON. |
-| **Continue.dev** | `~/.continue/config.yaml` (preferido) ou `config.json` (legado) | `agentmemory connect continue` cria `config.yaml` do zero quando nenhum dos dois existe, ou modifica um `config.json` existente. **Se você já tem `config.yaml`**, o adaptador imprime o bloco exato para colar sob `mcpServers:`; ele não reescreve seu yaml silenciosamente porque preservar comentários e âncoras com segurança exige um parser YAML que o pacote não empacota. Continue usa a forma de array (não objeto) para `mcpServers`. |
-| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` escreve sob `context_servers` (a chave do Zed, NÃO `mcpServers`). Servidores MCP remotos podem ser conectados via `{"url": "..."}` em vez disso. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferido) ou `config.json` (legado) | `agentmemory connect continue` cria `config.yaml` do zero quando nenhum dos dois existe, ou modifica o `config.json` existente. **Se você já tem `config.yaml`**, o adaptador imprime o bloco exato para colar sob `mcpServers:`; ele não reescreve seu yaml silenciosamente porque preservar comentários e anchors com segurança precisa de um parser YAML que o pacote não inclui. O Continue usa forma de array (não objeto) para `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` escreve sob `context_servers` (a chave do Zed, NÃO `mcpServers`). Servidores MCP remotos podem ser cabeados via `{"url": "..."}` em vez disso. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` escreve o bloco `mcpServers` padrão. Overrides com escopo de projeto vão em `/.factory/mcp.json`. Passe `--with-hooks` para captura automática nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` acrescenta uma linha `@deepseek-ai/dsh-mcp-client` à camada de patch no nível do home que todo perfil do Harness carrega; as tools se registram como `mcp__agentmemory__*`. Passe `--with-hooks` para também conectar a captura automática: os scripts de hook do Claude Code empacotados rodam pela bridge first-party `@deepseek-ai/dsh-hooks-claude-code` do Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via um manifesto escrito em `$DSH_HOME/agentmemory.hooks.json`. O padrão é `~/.dsh` quando `DSH_HOME` não está definido. |
| **Goose** | UI de configurações MCP do Goose | Mesmo bloco `mcpServers`; use `goose configure` → Add Extension → MCP. Edição direta do YAML em `~/.config/goose/config.yaml` é suportada, mas o schema usa `extensions:` + `cmd` (não `mcpServers:` + `command`). |
-| **Aider** | n/a | Fale diretamente com a REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Aider** | n/a | Fale direto 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).
+**Clientes MCP em sandbox** (Flatpak / Snap / containers restritivos) que não conseguem alcançar o `localhost` do host: defina também `"AGENTMEMORY_FORCE_PROXY": "1"` no bloco `env`, e aponte `AGENTMEMORY_URL` para uma rota que o sandbox consiga de fato alcançar (por exemplo, o IP da sua LAN).
### Acesso programático (Python / Rust / Node)
@@ -710,7 +844,7 @@ iii.trigger({
})
```
-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.
+Exemplo prático: [`examples/python/`](../examples/python/) (quickstart + fluxo de observação/recall). A REST na `:3111` continua disponível para hosts sem runtime iii.
### A partir do código-fonte
@@ -719,39 +853,43 @@ 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.
+Isso inicia o agentmemory com um `iii-engine` local se o binário fixado já estiver instalado, ou usa o Docker Compose quando selecionado. REST, streams e o viewer fazem bind em `127.0.0.1` por padrão. O caminho automático de binário no macOS/Linux exige `curl`, um `sh` POSIX e `tar`.
-Instale o `iii-engine` manualmente. **O agentmemory atualmente fixa o `iii-engine` em `v0.11.2`**. A `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=` se você migrou manualmente para o modelo de sandbox.
+Instale o `iii-engine` manualmente. **O agentmemory atualmente fixa o `iii-engine` em `v0.22.1`**, o mesmo release da sua dependência `iii-sdk`; o worker fala o protocolo de wire desse engine, e a 0.20.0 reorganizou a superfície do SDK, então os dois avançam juntos a cada release do agentmemory. Sobrescreva com `AGENTMEMORY_III_VERSION=` se você roda seu próprio engine e sabe que ele corresponde.
-- **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 arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** 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
+- **Windows:** baixe `iii-x86_64-pc-windows-msvc.zip` de [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) e extraia o `iii.exe` para `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Todo arquivo tem um `.sha256` correspondente na página do release; ao trocar a plataforma, use o hash desse arquivo na verificação acima (no Windows: `Get-FileHash`). O instalador automático em `npx @agentmemory/agentmemory` fixa esses hashes e recusa um arquivo que não corresponda.
-Ou use Docker (o `docker-compose.yml` empacotado puxa `iiidev/iii:0.11.2`). Docs completas: [iii.dev/docs](https://iii.dev/docs).
+Ou use Docker (o `docker-compose.yml` empacotado baixa `iiidev/iii:0.22.1`). Documentação completa: [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:
+agentmemory roda no Windows 10/11, mas o pacote Node.js sozinho não é suficiente; você também precisa do runtime fixado do iii-engine v0.22.1 como processo em segundo plano. O CLI não extrai automaticamente o ZIP do Windows, então usuários do Windows nativo precisam instalar o `iii.exe` manualmente, usar o WSL2 ou escolher o Docker Desktop.
+
+A instalação automatizada nativa de MCP no Windows suporta apenas `agentmemory connect copilot-cli`. Para Claude Code, Codex, Cursor e todo outro agente nativo do Windows, copie o bloco MCP manual de [Outros agentes](#other-agents) para a configuração desse agente no Windows. Rodar `connect` no WSL só é apropriado quando o agente de destino também está instalado nesse mesmo ambiente WSL; isso não edita a configuração de um agente que roda no host Windows.
**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)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**Opção B: Docker Desktop**
@@ -759,59 +897,68 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
-**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:
+**Opção C: somente MCP standalone (sem engine).** Se você só precisa das tools MCP para o seu agente e não precisa da REST API, do viewer ou dos cron jobs, pule o engine completamente:
```powershell
-npx -y @agentmemory/agentmemory mcp
+npx -y @agentmemory/agentmemory@latest 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:
+**Diagnóstico para Windows:** se `npx -y @agentmemory/agentmemory@latest` falhar, rode de novo 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 ` |
-| Fallback do Docker é pulado mesmo com Docker instalado | Confira se o Docker Desktop está de fato rodando (ícone na bandeja do sistema) |
+| `The engine process started but the REST API never responded.` | Confirme que as quatro portas derivadas estão livres, verifique que o `iii.exe` fixado continuou vivo, depois rode de novo com `--verbose` e inspecione o stderr capturado do engine |
+| `Could not start iii-engine` | Nem o `iii.exe` nem o Docker estão instalados. Veja a Opção A ou B acima |
+| Conflito de porta | `netstat -ano \| findstr :3111` para ver o que está em uso, depois mate o processo ou use `--port ` |
+| Fallback para Docker pulado mesmo com o Docker instalado | Garanta que o Docker Desktop esteja realmente em execução (ícone na bandeja do sistema) |
-> Nota: o **engine** iii é um binário pré-compilado, não um crate do cargo, então não tente instalá-lo com `cargo install`. (Os **SDKs** do iii são publicados no crates.io, npm e PyPI, mas o agentmemory não precisa deles.) Métodos de instalação do engine suportados, todos fixados em v0.11.2: o binário pré-compilado v0.11.2 acima, o script de instalação `sh` upstream **com a fixação de versão** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) e a imagem Docker `iiidev/iii:0.11.2`. Um simples `install.sh | sh` instala o engine **mais recente**, que o agentmemory não suporta; sempre passe `VERSION=0.11.2`. O mais fácil de tudo: basta rodar `npx @agentmemory/agentmemory`, que busca o engine fixado em `~/.agentmemory/bin` para você.
+> Nota: o **engine** do iii é um binário pré-compilado, não um crate cargo, então não tente dar `cargo install` nele. (Os **SDKs** do iii são publicados no crates.io, npm e PyPI, mas o agentmemory não precisa deles.) Os métodos de instalação do engine suportados estão todos fixados na v0.22.1: o binário pré-compilado acima, o caminho de auto-instalação do agentmemory para macOS/Linux (exige `curl`, `sh` POSIX e `tar`), e a imagem Docker `iiidev/iii:0.22.1`. Um `install.sh | sh` puro do upstream instala a versão mais recente do engine, que o agentmemory não suporta. Use `npx -y @agentmemory/agentmemory@latest`; no macOS/Linux ele busca o engine fixado para `~/.agentmemory/bin`.
---
Deploy
-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.
+Templates de um clique para hosts gerenciados. Cada um entrega um
+Dockerfile autocontido que baixa `@agentmemory/agentmemory` do npm e
+copia o binário do engine iii de dentro da imagem Docker oficial
+`iiidev/iii` do Docker Hub; nenhuma imagem pré-construída do
+agentmemory é necessária. O armazenamento persistente monta em
+`/data`; o entrypoint de primeiro boot sobrescreve a configuração do
+iii empacotada no npm (que faz bind em `127.0.0.1`) com uma ajustada
+para deploy que faz bind em `0.0.0.0` e usa caminhos `/data`
+absolutos, gera o secret HMAC e então solta os privilégios de `root`
+para `node` via `gosu` antes de executar o CLI do agentmemory.
-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.
+O botão de deploy de um clique do Render exige um `render.yaml` na raiz do repositório, que deliberadamente mantemos limpa. Use o fluxo de Render Blueprint documentado em [`deploy/render/`](.././deploy/render/README.md) para apontar manualmente para o blueprint que já está no repositório.
-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):
+Detalhes completos de setup (captura de HMAC, túnel SSH do viewer,
+rotação, backup, pisos 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.
+- [`deploy/fly`](.././deploy/fly/README.md): uma única máquina com
+ `auto_stop_machines = "stop"`; a mais barata quando ociosa.
+- [`deploy/railway`](.././deploy/railway/README.md): taxa fixa do plano
+ Hobby, volume no dashboard.
+- [`deploy/render`](.././deploy/render/README.md): fluxo de Blueprint,
+ snapshots automáticos de disco nos planos pagos.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted na sua
+ própria VPS via [Coolify](https://coolify.io/self-hosted); mesma
+ stack Docker Compose, você é dono do host e dos 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.
+Apenas a porta `3111` é publicada. O viewer na `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.
---
@@ -835,16 +982,16 @@ Session 2: "Now add rate limiting"
### 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.
+Todo agente de codificação com IA vem com memória integrada: Claude Code tem `MEMORY.md`, Cursor tem notepads, Cline tem memory bank. Elas 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) |
+| Escala | Teto de 200 linhas | Ilimitado |
+| Busca | Carrega tudo no contexto | BM25 + vector + graph (somente top-K) |
+| Custo em tokens | 22K+ em 240 observações | ~1,900 tokens (92% menos) |
+| Entre agentes | 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 |
+| Observabilidade | Leitura manual de arquivos | Viewer em tempo real na :3113 |
---
@@ -857,9 +1004,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -879,12 +1027,12 @@ Modelada em como o cérebro humano processa memória, incluindo a consolidação
| Nível | O quê | Analogia |
|------|------|---------|
-| **Working** | Observações brutas a partir do uso de tools | Memória de curto prazo |
+| **Working** | Observações brutas 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.
+As memórias decaem com o tempo (curva de Ebbinghaus). Memórias acessadas com frequência se reforçam. Memórias obsoletas são evictadas automaticamente. Contradições são detectadas e resolvidas.
### O que é capturado
@@ -894,7 +1042,7 @@ As memórias decaem com o tempo (curva de Ebbinghaus). Memórias acessadas com f
| `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 |
+| `PostToolUseFailure` | Contexto de erro |
| `PreCompact` | Reinjeta memória antes da compactação |
| `SubagentStart/Stop` | Ciclo de vida de sub-agentes |
| `Stop` | Resumo de fim de sessão |
@@ -908,48 +1056,52 @@ As memórias decaem com o tempo (curva de Ebbinghaus). Memórias acessadas com f
| **Busca semântica** | BM25 + vector + grafo de conhecimento com fusão RRF |
| **Evolução de memória** | Versionamento, supersessão, grafos de relacionamento |
| **Higiene de recall** | Versões supersedidas de memória saem dos índices de busca; a cadeia de versões no KV mantém o histórico completo |
-| **Dicas de quase-duplicata** | Saves reportam um match consultivo `similarTo` quando o novo conteúdo se parece muito com uma memória existente |
+| **Dicas de quase-duplicata** | Saves reportam uma correspondência consultiva `similarTo` quando o conteúdo novo se parece muito com uma memória existente |
| **Escopo por agente** | `agentId` atravessa save e recall em REST, MCP e no índice de busca, em modo shared ou isolated |
| **Provenance em tempo de escrita** | Toda observação e memória carrega um canal de origem imutável (user, agent, tool, import ou shared) carimbado na captura, no save e no import |
-| **Auto-esquecimento** | Expiração por TTL, detecção de contradição, evicção por importância |
-| **Privacy first** | API keys, segredos e tags `` são removidos antes do armazenamento |
+| **Auto-esquecimento** | Expiração por TTL, detecção de contradição, eviction por importância |
+| **Privacidade antes de tudo** | API keys, secrets e tags `` 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 |
+| **Bridge com o Claude** | Sincronização bidirecional com o 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 |
+| **Memória de time** | Compartilhada e privada com namespace entre membros do time |
+| **Provenance de citação** | Rastreia qualquer memória de volta às observações de origem |
+| **Snapshots do git** | Versiona, reverte e faz diff do estado da memória |
---
-Recuperação triple-stream combinando três sinais:
+Recuperação em stream triplo, combinando três sinais:
| Stream | O que faz | Quando |
|---|---|---|
-| **BM25** | Matching de palavra-chave com stemming + expansão de sinônimos | Sempre ativo |
+| **BM25** | Correspondência por palavra-chave com stemming e 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 |
+| **Graph** | Travessia do grafo de conhecimento via correspondência de entidades | Entidades detectadas na query |
+
+Combinados com Reciprocal Rank Fusion (RRF, k=60) e diversificados por sessão (máximo 3 resultados por sessão).
-Fundidos com Reciprocal Rank Fusion (RRF, k=60) e diversificados por sessão (máximo de 3 resultados por sessão).
+Quando um índice vetorial está populado, o `mem::search` (por trás do `memory_recall`) usa o ranker híbrido BM25 + vector. Sem embeddings ele usa BM25. O `smart-search` pode ainda combinar correspondências estruturais do grafo quando existem dados de grafo, inclusive no modo sem chave. O recall de lessons roda sobre um índice BM25 dedicado em memória, em vez de escanear todo o corpus a cada query. Versões supersedidas de memória são excluídas de todo caminho de recall; a cadeia de versões mantém o histórico delas.
-O ranqueamento híbrido se aplica ao caminho primário de recall, não só ao `smart-search`: `mem::search` (por trás de `memory_recall`) ranqueia pela mesma fusão BM25 + vector + graph assim que o índice vetorial está populado. O recall de lessons roda em um índice BM25 in-memory dedicado em vez de varrer o corpus inteiro a cada query. Versões supersedidas de memória são excluídas de todo caminho de recall; a cadeia de versões mantém o histórico delas.
+Vetores sobrevivem a um crash ou force-kill. O índice vetorial é salvo em buckets no máximo a cada `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutos). Todo vetor adicionado ou removido nesse meio tempo também é gravado imediatamente em um pequeno log pendente no state store, e o próximo início o reproduz sem chamar o provider de embedding. Cada save bem-sucedido esvazia o log. Documentos que ainda não têm vetor depois da reprodução são re-embeddados em segundo plano em lotes de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) até que não reste nenhum, e um backfill interrompido continua no próximo início. `/agentmemory/status` e o viewer mostram o tamanho do log pendente e o estado do backfill. Instalações sem chave não escrevem nada.
-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.
+O BM25 tokeniza grego, cirílico, hebraico, árabe e latim acentuado nativamente. Para memórias em chinês / japonês / coreano, instale os segmentadores opcionais (`npm install @node-rs/jieba tiny-segmenter`) para dividir sequências CJK em tokens no nível de palavra; sem eles, o agentmemory cai graciosamente para tokenização da sequência inteira e imprime uma dica única no stderr.
### Providers de embedding
-agentmemory autodetecta seu provider. Para melhores resultados, instale embeddings locais (gratuito):
+Instalações sem chave desativam os embeddings vetoriais: o `mem::search` usa BM25, enquanto o `smart-search` também pode usar dados estruturais de grafo já existentes. Para optar por embeddings semânticos gratuitos e no dispositivo, adicione isto a `~/.agentmemory/.env` e reinicie o agentmemory:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+A instalação normal via npm inclui o runtime opcional `@huggingface/transformers`. A primeira requisição de embedding baixa o `Xenova/all-MiniLM-L6-v2`, então precisa de acesso à rede e pode demorar mais; a inferência seguinte roda no dispositivo. Providers remotos são detectados automaticamente a partir de suas chaves, a menos que `EMBEDDING_PROVIDER` as sobrescreva.
+
| 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)) |
+| **Local (opt-in recomendado)** | `all-MiniLM-L6-v2` | Gratuito | No dispositivo após o primeiro download do modelo, +8pp de recall sobre BM25 sozinho |
+| Gemini | `gemini-embedding-001` | Camada gratuita | 100+ idiomas, dimensões 768/1536/3072 (MRL), entrada de 2048 tokens. Substitui o `text-embedding-004` ([descontinuado, desligamento em 14 de jan. 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 |
@@ -961,7 +1113,7 @@ npm install @huggingface/transformers
54 tools, 6 resources, 3 prompts e 17 skills.
-> **Shim MCP vs servidor completo:** o pacote publicado `@agentmemory/mcp` é um shim fino. Expõe a superfície completa de 54 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`.
+> **Shim MCP vs servidor completo:** o pacote publicado `@agentmemory/mcp` é um shim fino. Ele expõe a superfície completa de 54 tools **somente quando consegue alcançar um servidor agentmemory em execução** via `AGENTMEMORY_URL` (modo proxy). Sem nenhum servidor acessível, o shim cai para um conjunto local de 7 tools (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). A env var `AGENTMEMORY_TOOLS=core|all` é uma flag do *lado do servidor*; defini-la no bloco `env` do shim não tem efeito. Se você vê apenas 7 tools no Cursor / OpenCode / Gemini CLI, inicie `npx -y @agentmemory/agentmemory@latest` (ou a stack Docker) e defina `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
@@ -978,12 +1130,12 @@ Três superfícies de tools, da menor para a maior: `AGENTMEMORY_TOOLS=core` red
| `memory_file_history` | Observações passadas sobre arquivos específicos |
| `memory_patterns` | Detecta padrões recorrentes |
| `memory_sessions` | Lista sessões recentes |
-| `memory_smart_search` | Busca híbrida semântica + por palavras |
+| `memory_smart_search` | Busca híbrida semântica + palavra-chave |
| `memory_vision_search` | Busca observações de imagem |
-| `memory_timeline` | Observações cronológicas |
-| `memory_profile` | Perfil de projeto (conceitos, arquivos, padrões) |
+| `memory_timeline` | Observações em ordem cronológica |
+| `memory_profile` | Perfil do projeto (conceitos, arquivos, padrões) |
| `memory_export` | Exporta todos os dados de memória |
-| `memory_relations` | Consulta o grafo de relacionamentos |
+| `memory_relations` | Consulta o grafo de relacionamento |
| `memory_commit_lookup` | Sessões por trás de um commit git |
| `memory_commits` | Commits registrados para uma sessão |
@@ -995,35 +1147,35 @@ Três superfícies de tools, da menor para a maior: `AGENTMEMORY_TOOLS=core` red
| Tool | Descrição |
|------|-------------|
| `memory_patterns` | Detecta padrões recorrentes |
-| `memory_timeline` | Observações cronológicas |
-| `memory_relations` | Consulta o grafo de relacionamentos |
+| `memory_timeline` | Observações em ordem cronológica |
+| `memory_relations` | Consulta o grafo de relacionamento |
| `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_claude_bridge_sync` | Sincroniza com o 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_audit` | Trilha de auditoria das operações |
+| `memory_governance_delete` | Deleta com trilha de auditoria |
+| `memory_snapshot_create` | Snapshot versionado com git |
+| `memory_action_create` | Cria work items com dependências |
+| `memory_action_update` | Atualiza o status de uma action |
+| `memory_frontier` | Actions desbloqueadas, ranqueadas por prioridade |
+| `memory_next` | A próxima action mais importante, uma só |
+| `memory_lease` | Leases exclusivos de action (multiagente) |
+| `memory_routine_run` | Instancia routines 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_checkpoint` | Gates de condição externa |
+| `memory_mesh_sync` | Sync P2P entre instâncias |
+| `memory_sentinel_create` | Watchers orientados a evento |
| `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_sketch_create` | Grafos de action efêmeros |
+| `memory_sketch_promote` | Promove a permanente |
+| `memory_crystallize` | Compacta cadeias de action |
+| `memory_diagnose` | Checagens de saúde |
| `memory_heal` | Corrige automaticamente estado travado |
-| `memory_facet_tag` | Tags dimension:value |
-| `memory_facet_query` | Consulta por tags de facet |
+| `memory_facet_tag` | Tags dimensão:valor |
+| `memory_facet_query` | Consulta por facet tags |
| `memory_verify` | Rastreia provenance |
@@ -1043,23 +1195,23 @@ Três superfícies de tools, da menor para a maior: `AGENTMEMORY_TOOLS=core` red
| 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 | `/session-history` | Resumos de sessões recentes |
| Skill | `/forget` | Deleta observações/sessões |
-A tabela mostra as quatro skills principais. O conjunto completo são 8 skills invocáveis mais 7 skills de referência; veja a seção de skills nativas acima.
+A tabela mostra as quatro skills principais. O conjunto completo é de 9 skills invocáveis mais 8 skills de referência; veja a seção de skills nativas acima.
### MCP standalone
-Rode sem o servidor completo, para qualquer cliente MCP. Qualquer um destes funciona:
+Rode sem o servidor completo, para qualquer cliente MCP. Qualquer uma destas opções funciona:
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (always available)
+npx -y @agentmemory/agentmemory@latest 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):
+A maioria dos agentes (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1074,7 +1226,7 @@ A maioria dos agentes (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini
}
```
-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.
+Mescle a entrada `agentmemory` no objeto `mcpServers` já 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 consiga alcançar.
OpenCode (`opencode.json`):
```json
@@ -1090,7 +1242,7 @@ OpenCode (`opencode.json`):
}
```
-Copie o arquivo do plugin do repo:
+Copie o arquivo do plugin a partir do repositório:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
@@ -1101,23 +1253,30 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Sobe automaticamente na porta `3113`. Stream ao vivo de observações com um indicador de status do stream, um explorador de sessões em dois painéis (lista ao lado de um painel de detalhes fixo em telas largas), linhas de memórias e lessons que expandem para o registro completo armazenado incluindo JSON bruto e provenance de origem, um grafo de conhecimento que agrupa nós por tipo enquanto as relações são esparsas, replay de sessão e um dashboard de saúde.
+Inicia automaticamente na porta `3113`. O viewer carrega um snapshot quando se conecta (`GET /agentmemory/viewer/snapshot`) e depois aplica eventos de stream ao vivo: novas memórias, lessons, observações, entradas de auditoria, mudanças no grafo e atualizações de saúde aparecem sem polling ou recarregamento de página. As únicas outras requisições são as ações que você clica, páginas de "carregar mais" e buscas. Quando o stream cai, o viewer mostra há quanto tempo seus números estão desatualizados, reconecta com backoff e resincroniza a partir de um snapshot.
+
+- **12 abas em quatro grupos** com contagens ao vivo, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), atalhos de teclado e um menu mobile.
+- **Memories:** busca no lado do servidor, filtros por projeto, agente e tipo, um painel de detalhe com a cadeia de versões e um diff de palavras, links de provenance, botões de copiar para o id, a chamada MCP e um comando curl, editar (uma nova versão), forget com confirmação, forget em massa e export em JSON.
+- **Sessions:** uma timeline inline de observações com entrada e saída de tool legíveis, filtros e paginação, e as memórias e lessons que cada sessão produziu.
+- **Graph:** busca, detalhe do node com relações e fontes, uma legenda que não depende só de cor, e controles de zoom.
+- **Health:** a versão ao vivo de `GET /agentmemory/status`. Todo problema vem com a sua correção, mais o backend de estado, o estado de save do índice, o progresso de compactação de provenance do grafo e um explicador de consolidação com os thresholds reais.
+- **Páginas Audit, Activity, Profile, Replay, Lessons, Actions e Crystals**, cada uma com um estado vazio que explica o que a seção é, por que está vazia e o comando que a preenche, e um tooltip `?` de glossário em todo termo e número.
```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'`).
+O servidor do viewer faz bind em `127.0.0.1` por padrão e anexa o secret do servidor quando repassa requisições para a REST API, então ele não precisa de nenhum setup. O endpoint `/agentmemory/viewer` servido via REST segue as regras normais de bearer-token e redireciona navegadores sem token para a porta do viewer. Os headers CSP usam um nonce de script por resposta e desabilitam atributos de handler inline (`script-src-attr 'none'`).
---
-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.
+O viewer na `:3113` mostra o que o seu agente **lembrou**. O [iii console](https://iii.dev/docs/console) mostra o que o seu agente **fez**: toda operação de memória como um trace OpenTelemetry, toda entrada KV editável, toda função invocável, todo stream "tappable". Duas janelas sobre a mesma memória: uma no formato de produto, outra no 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.
+Veja um `memory_smart_search` disparar e acompanhe o scan de BM25 → lookup de embedding → fusão RRF → reranker como um waterfall. Edite um timer de consolidação travado no navegador de KV. Reproduza um hook `PostToolUse` com um payload ajustado. Fixe o stream WebSocket e veja as observações chegando ao vivo.
-agentmemory oferece isso de graça porque toda chamada de função e trigger dispara através do iii; nada custom, nada para instrumentar.
+agentmemory entrega isso de graça porque toda chamada de função e trigger dispara através do iii; nada custom, nada para instrumentar.
@@ -1125,55 +1284,53 @@ agentmemory oferece isso de graça porque toda chamada de função e trigger dis
Página Workers: todo worker conectado, incluindo o próprio agentmemory, com PID, contagem de funções, runtime e last-seen.
-**Já instalado.** O console vem junto com `iii`; sem instalador separado.
+**Já instalado.** O console vem junto com o engine `iii` fixado (0.22+); nada separado para instalar. O primeiro lançamento baixa o binário do console ao lado do engine.
-**Suba junto com o agentmemory:**
+**Lançando 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
+agentmemory console
```
-Depois abra `http://localhost:3114`. Adicione `--enable-flow` para a página experimental de grafo de arquitetura.
+Isso roda o `iii console` do engine fixado contra as portas que o agentmemory resolveu (REST, streams, bridge) e o serve uma porta acima do viewer, `http://localhost:3114` por padrão. `--console-port N` escolhe outra porta; `--port` e `--instance` selecionam a instância do agentmemory do mesmo jeito que fazem para `stop`; qualquer outra flag é repassada, por exemplo `--enable-flow` para a página experimental de grafo de arquitetura.
-Sobrescreva endpoints do engine apenas se você os tiver movido:
+A mesma coisa na mão, útil quando `agentmemory` não está no PATH:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
-**O que você pode fazer pelo console:**
+**O que você pode fazer a partir do 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. |
+| **Functions** | Invocar qualquer função do agentmemory diretamente com um payload JSON; prático 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 sobre sessões, slots de memória, timers de ciclo de vida e o í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. |
+| **States** | Navegador de KV com CRUD completo sobre sessões, slots de memória, timers de ciclo de vida e o índice de embeddings; edite valores no lugar. |
+| **Streams** | Monitor de WebSocket ao vivo para escritas de memória, eventos de hook e atualizações de observação conforme fluem pelos streams do iii. |
+| **Queues** | Tópicos de queue duráveis + gerenciamento de dead-letter. Reproduza ou descarte jobs falhos de embedding / compressão. |
| **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. |
+| **Logs** | Logs OTEL estruturados, filtrados e correlacionados a trace/span IDs. |
+| **Config** | Configuração de runtime: veja exatamente com quais workers, providers e portas o seu engine está rodando. |
| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitetura interativo de todo worker, trigger e stream. |
-
+ Traces: waterfall / flame / breakdown por serviço para toda operação de memória.
-**Traces já estão ativos:**
+**Os traces já vêm ativados:**
-`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.
+O `iii-config.yaml` vem com o worker `iii-observability` habilitado (`exporter: memory`, `sampling_ratio: 0.1`, métricas + logs). Sem config extra necessária; no momento em que o agentmemory inicia, toda operação de memória emite um log estruturado que o console consegue ler, e uma em cada dez delas (`sampling_ratio: 0.1`) também emite um trace span.
-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.
+Se você quiser exportar para Jaeger/Honeycomb/Grafana Tempo em vez disso, 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.
+> **Atenção:** nenhuma autenticação é aplicada no próprio console; mantenha-o em bind em `127.0.0.1` (o padrão) e nunca o exponha publicamente.
---
@@ -1181,46 +1338,116 @@ Se você quiser exportar para Jaeger/Honeycomb/Grafana Tempo, troque `exporter:
agentmemory **já é uma instância [iii](https://iii.dev) em execução**. Três primitivos (worker, function, trigger) compõem o runtime; estado KV, streams e traces OTEL vêm dos workers iii-state, iii-stream e iii-observability que acompanham o 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.
+Isso significa que mais um comando estende o agentmemory com uma capacidade inteiramente nova.
-### Estenda o agentmemory com um comando
+### Estenda o agentmemory com mais workers
-```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
-```
+Os builtins de que o agentmemory precisa já estão no `iii-config.yaml` e sobem junto com ele: `iii-state` (KV), `iii-queue` (retries duráveis para os subscribers de evento), `iii-pubsub`, `iii-cron`, `iii-stream` e `iii-observability` (traces, métricas e logs OTEL em toda função). Qualquer outra coisa do [registry de workers do iii](https://workers.iii.dev) se conecta ao mesmo engine: copie `iii-config.yaml` para `~/.agentmemory/iii-config.yaml` (o CLI prefere esse arquivo em vez do empacotado, e ainda renderiza portas e caminhos de dados dentro dele), adicione a entrada, instale o runtime do worker uma vez com `~/.agentmemory/bin/iii update worker`, e reinicie o agentmemory.
-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.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | O que você ganha em cima do agentmemory |
+| Worker | O que você ganha além 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 |
+| [`database`](https://workers.iii.dev/workers/database) | Adaptador de estado com backend SQL para quando você crescer além dos padrões de KV em memória |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Código que saiu do `memory_recall` roda dentro de uma VM descartável, não no seu shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Suba servidores MCP extras ao lado dos do agentmemory, compartilhando o mesmo engine |
+
+Na engine 0.22.x mantenha os nomes com prefixo `iii-` para os builtins acima; as entradas sem prefixo `http`, `state`, `queue`, `pubsub` e `cron` são os workers standalone do registry para os quais o agentmemory migra com a 0.23.
+
+Registry completo: [workers.iii.dev](https://workers.iii.dev). Todo worker lá compõe através dos mesmos primitivos que o agentmemory usa, e o agentmemory que você já tem é um deles.
+
+### Config do engine e endereço de bind
+
+`agentmemory start` lê a config do engine a partir do primeiro arquivo que existir: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` no diretório atual, `~/.agentmemory/iii-config.yaml`, depois o `iii-config.yaml` empacotado. A cada início, ele renderiza esse arquivo (caminhos de dados, portas, backend de estado) em `~/.agentmemory/data/iii-config.runtime.yaml` e lança o engine com a cópia renderizada, então edite o arquivo de origem, não o renderizado. Os valores de `host:` do arquivo de origem são mantidos como escritos.
+
+O `iii-config.yaml` empacotado faz bind em `127.0.0.1` de propósito, e esse padrão também se aplica dentro de um contêiner. Um CLI iniciado em um contêiner escuta no loopback do contêiner, então as portas publicadas não alcançam nada. Para servir um CLI containerizado através de portas publicadas, defina `AGENTMEMORY_III_CONFIG` para uma config que faça bind em `0.0.0.0`. O `iii-config.docker.yaml` empacotado é uma delas: ele faz bind do `iii-http`, do `iii-stream` e da porta do engine em `0.0.0.0` e guarda o estado em `/data`, então monte um volume gravável lá. Mantenha `AGENTMEMORY_SECRET` definido, e publique apenas as portas que você precisa, em `127.0.0.1` ou por trás de um proxy em que você confie.
+
+O `docker-compose.yml` deste repositório não passa pela busca de config do CLI: ele monta `iii-config.docker.yaml` em `/app/config.yaml`, e o contêiner `iii-engine` inicia com `--config /app/config.yaml`. Os [templates de deploy](../deploy/) de um clique escrevem a própria config `0.0.0.0` em seus entrypoints.
+
+### Backend de armazenamento: file (padrão) vs redis
+
+`iii-state` e `iii-stream` usam por padrão o store KV baseado em arquivo embutido no iii-engine: um arquivo JSON por scope, mantido na memória do processo do engine e reescrito em disco em um timer. Esse é o padrão certo para uma instalação local de um único usuário; um daemon compartilhado com vários escritores concorrentes ganha escritas reais por chave do Redis em vez disso, ao custo de uma viagem de rede por operação (toda chamada `state::*` ainda serializa em uma única conexão Redis, então isso troca o lock do store de arquivo por um socket, não por paralelismo).
+
+Defina `AGENTMEMORY_STATE_BACKEND=redis` (mais `AGENTMEMORY_REDIS_URL`) para trocar os dois workers para o adaptador `redis` embutido no iii-engine, que guarda cada chave como um campo de hash do Redis (`HSET`) em vez de reescrever um scope inteiro a cada escrita:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` tem como padrão `file`; deixá-lo indefinido mantém o comportamento de hoje sem mudanças, e um valor não reconhecido (qualquer coisa além de `file` ou `redis`) é um erro de inicialização, não um fallback silencioso. `/agentmemory/status` e a página Health do viewer (a linha State store) informam qual backend está ativo e se ele está respondendo, nunca a URL.
+
+**Somente `redis://` puro.** O engine fixado (0.22.1) compila seu cliente Redis sem suporte a TLS, então uma URL `rediss://` (a maioria das ofertas de Redis gerenciado, como Upstash, Redis Cloud e ElastiCache com criptografia em trânsito, vêm por padrão somente com TLS) falha ao conectar. A conexão não é criptografada, então a senha do Redis e toda memória armazenada cruzam a rede em texto claro: aponte para um Redis local ou um em uma rede privada em que você confie. Para qualquer outro Redis, rode um túnel criptografado (stunnel, SSH ou uma VPN) no host do agentmemory, de modo que o salto `redis://` puro fique nesse host e a conexão upstream do túnel seja criptografada e autenticada. Se uma senha do Redis contiver um apóstrofo, codifique-o em percent-encoding (`%27`); o engine expande a URL dentro da sua config YAML antes de analisá-la.
+
+**Um servidor Redis por `--instance`.** Os prefixos de chave Redis do engine (`state:`, `stream::`) são fixos, então duas instâncias do agentmemory (`--instance 1`, `--instance 2`, ...) apontando para o mesmo banco de dados sobrescrevem os dados uma da outra. Um índice de banco separado (`redis://localhost:6379/1`) mantém os dados armazenados separados, mas o engine retransmite os eventos do viewer em tempo real por um único canal pub/sub do Redis (`stream::events`), e o pub/sub do Redis ignora o índice do banco, então o viewer de cada instância ainda mostraria os eventos ao vivo da outra. Dê a cada instância seu próprio servidor Redis (ou porta) quando você rodar mais de uma.
+
+**O que permanece igual, e o que muda.** Todo recurso do agentmemory funciona no Redis: sessões, observações, memórias (remember, supersede, evolve, forget), busca e os buckets de índice, lessons, o grafo, o log de auditoria e seus scopes mensais, export e import, governance deletes, status de consolidação, o snapshot do viewer e seu stream ao vivo, e o monitor de saúde. O engine guarda cada scope como um hash do Redis (`HSET`/`HGET`/`HGETALL`) e dispara os mesmos state triggers que o store de arquivo. Três diferenças do engine são tratadas dentro do agentmemory:
+
+- O Redis retorna os registros de um scope em nenhuma ordem fixa. O agentmemory os ordena do mais antigo para o mais novo (pelo horário de criação no id do registro, depois pelo seu timestamp), então listas, paginação e chunks de export vêm de volta na mesma ordem que no store de arquivo.
+- O engine aplica updates parciais no Redis em um script Lua que transforma arrays vazios em objetos vazios. O agentmemory aplica esses updates ele mesmo (lê, muda, escreve sob um lock por chave) no Redis, então campos como `tags: []` continuam sendo arrays.
+- A checagem do log de auditoria legado lê o scope antigo do Redis em vez de procurar o arquivo do store de arquivo em disco.
-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.
+Uma diferença exige ação sua: **depois que o Redis reinicia, o engine para de retransmitir eventos ao vivo** para o viewer até que o agentmemory reinicie. Os dados continuam sendo salvos e lidos normalmente. O monitor de saúde envia um evento de teste pelo Redis a cada 30 segundos; quando ele não volta, `/agentmemory/status` e a página Health do viewer mostram "Live updates are not reaching the viewer" com a correção: reinicie o agentmemory. Se o Redis estiver fora do ar, o relatório de status mostra "The state store is not answering" e como checar isso (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listar um scope muito grande lê o hash inteiro em um único `HGETALL`, o mesmo custo do store de arquivo mantendo-o em memória.
+
+**Configurações de Redis recomendadas.** A política de snapshot padrão `save 3600 1 300 100 60 10000` pode perder minutos de escritas em um crash, pior que a janela de flush de 5s do store de arquivo. Defina `appendonly yes` para qualquer coisa que você se importaria em perder. Defina `maxmemory-policy noeviction`; `allkeys-lru` ou similar descarta memórias silenciosamente quando o Redis atinge seu limite de memória.
+
+Um início nativo (sem Docker), e todo [template de deploy](../deploy/) de um clique (eles sobrescrevem o `iii-config.yaml` empacotado e iniciam nativamente), leem `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` e os renderizam na `iii-config` lançada. A própria URL nunca é escrita nesse arquivo renderizado, apenas uma referência `${AGENTMEMORY_REDIS_URL}` que o processo do engine expande a partir do seu próprio ambiente no boot. Somente o caminho de Docker Compose deste próprio repositório (`AGENTMEMORY_USE_DOCKER=1`, ou retomando um engine já iniciado desse jeito) monta `iii-config.docker.yaml` como somente leitura e nunca renderiza; `agentmemory start` avisa quando detecta essa combinação. Troque esse arquivo manualmente, seguindo o mesmo formato `name: redis` / `config: redis_url: ...` mostrado na documentação dos workers [iii-state](https://workers.iii.dev/workers/iii-state) e [iii-stream](https://workers.iii.dev/workers/iii-stream), e aponte `redis_url` para um Redis alcançável a partir do contêiner. O `docker-compose.yml` passa `AGENTMEMORY_REDIS_URL` para o contêiner do engine, então `redis_url: '${AGENTMEMORY_REDIS_URL}'` funciona lá e mantém a URL fora do arquivo montado.
+
+A config renderizada mantém a URL fora de `~/.agentmemory/data/iii-config.runtime.yaml`, mas o próprio worker de configuração do engine ainda persiste o valor *expandido* em `~/.agentmemory/config/iii-state.yaml` e `iii-stream.yaml` depois que ele sobe (a expansão `${VAR}` do iii-engine acontece antes desse worker guardar seu seed, e ele guarda o valor resolvido, não a referência). Trate esse diretório como se guardasse uma credencial: `chmod 700 ~/.agentmemory` em qualquer host compartilhado, e prefira um usuário ACL do Redis com escopo no que o agentmemory precisa, em vez das credenciais de admin do banco.
+
+**A migração não é automática.** Trocar `AGENTMEMORY_STATE_BACKEND` começa de um store vazio em ambos os lados; nada copia os dados existentes de file para Redis ou vice-versa. Exporte do backend que você está deixando e importe para aquele para o qual você está indo. Isto roda de forma idêntica em bash e zsh (incluindo `bash -u`). Um array como `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` não roda: o zsh mantém o header como uma única palavra malformada onde o bash o divide em duas, então ambas as requisições recebem 401 sempre que `AGENTMEMORY_SECRET` está definido:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` também aceita `?maxSessions=` e `?offset=` para dividir um corpus grande em várias chamadas; `strategy` no import é `merge` (seguro por padrão), `replace` ou `skip`.
### 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 |
+| SQLite / Postgres + pgvector | iii KV State + índice vetorial em memória |
| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | Supervisão de workers do iii engine |
+| pm2 / systemd | Supervisão de worker do engine iii |
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugin customizados | `iii worker add ` |
-**182 arquivos de código · ~41.600 LOC · 1.674 tests · 264 funções · 50 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**225 arquivos de código · ~54,000 LOC · 2,600+ testes · 312 funções · 66 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
---
@@ -1228,22 +1455,22 @@ Registry completo: [workers.iii.dev](https://workers.iii.dev). Todo worker lá s
### 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.
+agentmemory detecta providers automaticamente a partir do seu ambiente. Um provider libera operações baseadas em LLM, mas a configuração de um provider por si só não ativa a compressão de observações escrita por LLM. Esse caminho exige tanto um provider quanto `AGENTMEMORY_AUTO_COMPRESS=true`.
| 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 |
+| **No-op (padrão)** | Nenhuma config necessária | Compress/summarize baseados em LLM ficam desativados. Compressão sintética e recall via BM25 continuam funcionando. Veja `AGENTMEMORY_ALLOW_AGENT_SDK` abaixo se você costumava depender do fallback via assinatura Claude. |
+| API Anthropic | `ANTHROPIC_API_KEY` | Cobrança por token |
| MiniMax | `MINIMAX_API_KEY` | Compatível com Anthropic |
-| Gemini | `GEMINI_API_KEY` | Também habilita embeddings |
+| Gemini | `GEMINI_API_KEY` | Também ativa embeddings |
| OpenRouter | `OPENROUTER_API_KEY` | Qualquer modelo |
-| OpenAI API | `OPENAI_API_KEY` | Padrão `gpt-5.6-luna`, sobrescreva com `OPENAI_MODEL` |
-| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ou `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Qualquer coisa compatível com a API da OpenAI. Custo zero, roda no seu hardware. Veja [Modelos locais](#modelos-locais-ollama--lm-studio--vllm) abaixo. |
-| 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, por isso não é mais o padrão. |
+| API OpenAI | `OPENAI_API_KEY` | Padrão `gpt-5.6-luna`, sobrescreva com `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ou `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Qualquer coisa compatível com a API da OpenAI. Custo zero, roda no seu hardware. Veja [Modelos locais](#local-models-ollama--lm-studio--vllm) abaixo. |
+| Fallback de assinatura Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Somente opt-in. Dispara sessões do `@anthropic-ai/claude-agent-sdk`; costumava causar recursão sem limite no Stop hook, então deixou de ser o padrão. |
### Modelos locais (Ollama / LM Studio / vLLM)
-agentmemory conversa com qualquer servidor compatível com a API da OpenAI, então qualquer coisa que exponha `/v1/chat/completions` funciona sem mudanças de código. Sem chaves pagas, sem nuvem, sem rate limits; roda inteiramente no seu hardware.
+agentmemory fala com qualquer servidor compatível com a API da OpenAI, então qualquer coisa que exponha `/v1/chat/completions` funciona sem mudanças de código. Sem chaves pagas, sem nuvem, sem rate limits; roda inteiramente no seu hardware.
**Ollama** (porta padrão `11434`):
@@ -1270,48 +1497,48 @@ OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
-**vLLM / llama.cpp / Text Generation Inference**: mesmo formato. Aponte `OPENAI_BASE_URL` para a URL que seu servidor expõe e defina `OPENAI_MODEL` para um nome que seu servidor aceite.
+**vLLM / llama.cpp / Text Generation Inference**: mesmo formato. Aponte `OPENAI_BASE_URL` para a URL que o seu servidor expõe e defina `OPENAI_MODEL` para um nome que o seu servidor vai aceitar.
-**Escolhas de modelo para trabalho de memória**: compressão e sumarização são tarefas curtas (<2K tokens de entrada, <500 tokens de saída) em que um modelo instruct de 7B é mais que suficiente. Recomendações:
+**Escolhas de modelo para trabalho de memória**: compressão e sumarização são tarefas curtas (<2K tokens de entrada, <500 tokens de saída) onde um modelo instruct de 7B já é suficiente. Recomendações:
| Modelo | Tamanho | Por quê |
|-------|------|-----|
-| `qwen3:8b` | ~5.2 GB | Padrão equilibrado numa máquina de 16 GB; forte em extração e texto em formato de tools |
-| `qwen3:4b` | ~2.6 GB | A menor opção sensata; OK para compressão, mais fraco para extração de grafo |
-| `qwen3-coder:30b` | ~19 GB | Melhor escolha local para sessões orientadas a código (30B MoE, 3.3B ativos) em hardware de 24-32 GB |
+| `qwen3:8b` | ~5.2 GB | Padrão equilibrado numa máquina de 16 GB; forte em extração e texto no formato de tool |
+| `qwen3:4b` | ~2.6 GB | Menor opção sensata; ok para compressão, mais fraco para extração de grafo |
+| `qwen3-coder:30b` | ~19 GB | Melhor escolha local para sessões no formato de código (30B MoE, 3.3B ativo) em hardware de 24-32 GB |
| `gpt-oss:20b` | ~14 GB | Modelo geral forte que cabe em 16 GB de RAM |
-| `deepseek-r1:8b` | ~5.2 GB | Distill de reasoning; mais lento, mas extrações mais limpas |
+| `deepseek-r1:8b` | ~5.2 GB | Distill de raciocínio; mais lento, mas com extrações mais limpas |
-Modelos Qwen 3 pensam por padrão e podem queimar todo o token budget em raciocínio antes de qualquer saída. Defina `AGENTMEMORY_LLM_NOTHINK=1` para anexar `/no_think` aos prompts de extração de grafo, e aumente `MAX_TOKENS` (16384 funciona) se as extrações voltarem vazias.
+Os modelos Qwen 3 pensam por padrão e podem queimar todo o token budget em raciocínio antes de qualquer saída. Defina `AGENTMEMORY_LLM_NOTHINK=1` para anexar `/no_think` aos prompts de extração de grafo, e aumente `MAX_TOKENS` (16384 funciona) se as extrações voltarem vazias.
-Modelos classe reasoning (estilo `o1` com blocos ``) podem retornar `content` vazio com um campo `reasoning` que seu servidor local pode não expor. Se as extrações voltarem em branco, troque primeiro para um modelo sem reasoning. A env `OPENAI_REASONING_EFFORT=none` também pode desabilitar o thinking em modelos thinking do Ollama Cloud que espelham o schema de reasoning da OpenAI.
+Modelos da classe reasoning (estilo `o1` com blocos ``) podem retornar `content` vazio com um campo `reasoning` que o seu servidor local pode não expor. Se as extrações voltarem vazias, troque primeiro para um modelo sem reasoning. A env `OPENAI_REASONING_EFFORT=none` também pode desativar o thinking em modelos de thinking do Ollama Cloud que espelham o schema de reasoning da OpenAI.
-Embeddings locais vêm de fábrica via `@huggingface/transformers`: `EMBEDDING_PROVIDER=local` (padrão) te dá `Xenova/all-MiniLM-L6-v2` (384 dims) inteiramente no dispositivo. Sem configuração extra.
+Embeddings locais vêm como uma dependência opcional, mas não são ativados por padrão. Defina `EMBEDDING_PROVIDER=local` para optar pelo `Xenova/all-MiniLM-L6-v2` (384 dim). A primeira requisição de embedding baixa o modelo; a inferência fica no dispositivo depois disso. Sem essa configuração ou uma chave de embedding remota, os vetores ficam desativados, o `mem::search` usa BM25, e o `smart-search` ainda pode adicionar correspondências de grafo já existentes.
### 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.
+Quando a compressão em segundo plano escrita por LLM está ativada, com tanto um provider quanto `AGENTMEMORY_AUTO_COMPRESS=true`, ela roda em toda observação, então a escolha do modelo muda de forma significativa o gasto mensal. Dados de carga capturados: 635 requisições / 888K tokens / 35 horas de uso ativo, rodados contra três modelos do OpenRouter com os preços de 2026-05-23.
-| Tier | Modelo | Input / 1M | Output / 1M | Custo para as 35h capturadas | Notas |
+| Nível | Modelo | Entrada / 1M | Saída / 1M | Custo das 35h capturadas | Notas |
|------|-------|------------|-------------|---------------------------|-------|
-| Recomendado | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | DeepSeek mais recente; a escolha recomendada mais barata para workloads de compressão. |
-| 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 | `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-5` | $3.00 | $15.00 | ~$5.02 (est.) | Mesmo preço de lista da execução medida com o Sonnet 4.6; preço introdutório de $2/$10 até 2026-08-31. |
-| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Tier flagship; caro para trabalho de background sempre ativo. |
-| Evitar | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modelo classe flagship; gasto desproporcional para compressão. |
+| Recomendado | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | DeepSeek mais recente; a escolha recomendada mais barata para cargas de compressão. |
+| Recomendado | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Boa qualidade de compressão + sumarização a ~10x menos custo que o Sonnet. |
+| Recomendado | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Raciocínio de código forte se suas sessões forem bastante no formato de código. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Mesmo preço de tabela da execução medida com o Sonnet 4.6; preço de lançamento de $2/$10 até 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Nível flagship; caro para trabalho sempre ativo em segundo plano. |
+| Evitar | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modelo de classe flagship; gasto excessivo para compressão. |
-As linhas medidas vêm da execução capturada; as linhas (est.) escalam o mesmo mix de tokens pelo preço de lista de cada modelo.
+As linhas medidas vêm da execução capturada; as linhas (est.) escalam a mesma mistura de tokens pelo preço de tabela de cada modelo.
-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.
+agentmemory imprime um aviso em runtime quando `OPENROUTER_MODEL` corresponde a um padrão de nível premium. Defina `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para silenciar isso depois que você tiver feito uma escolha 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 Flash / V4 Pro / Qwen3-Coder ficam dentro do erro de arredondamento do Sonnet nessa tarefa, custando 10-70× menos. Reserve os modelos tier premium para as queries que você lê diretamente.
+Tradeoff de qualidade vs custo para trabalho de memória: compressão é uma tarefa de sumarização com padrões de qualidade relativamente soltos (o agente relê o resumo, não o usuário). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ficam dentro da margem de erro do Sonnet nessa tarefa, custando 10-70x menos. Guarde os modelos de nível premium para queries que você lê diretamente.
-Fontes: [OpenRouter pricing for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+Fontes: [preços do OpenRouter para o Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [notas de preços da DeepSeek](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.
+Em setups multiagente onde vários papéis compartilham um único servidor agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` marca toda escrita com o papel que a fez. `AGENTMEMORY_AGENT_SCOPE` controla se o recall filtra por essa tag.
```env
TEAM_ID=company
@@ -1322,12 +1549,12 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
Dois modos:
-| Modo | Etiqueta escritas | Filtra recall | Quando usar |
+| Modo | Marca 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. |
+| `shared` (padrão) | sim | não | Contexto entre agentes com trilha de auditoria. O architect pode ver o que o developer anotou, mas toda linha registra quem disse o quê. |
+| `isolated` | sim | sim | Separação estrita. O architect nunca vê as 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 é marcado quando `AGENT_ID` está definido: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. O papel flui de `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=` 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.
@@ -1337,16 +1564,20 @@ Quando `AGENT_ID` não está definido, a memória permanece sem escopo (comporta
### 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.
+agentmemory + iii-engine fazem bind em quatro portas por padrão. Se um reinício falhar com `port in use`, esta tabela diz qual processo procurar.
-| Porta | Processo | Propósito | Override por env |
+| Porta | Processo | Finalidade | Override de 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`) |
+| `3112` | iii-engine | Worker interno de streams (consumido pelo agentmemory + viewer) | `III_STREAM_PORT` (preferido) ou o legado `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer em tempo real (`http://localhost:3113`) | `III_VIEWER_PORT` ou `AGENTMEMORY_VIEWER_URL` para a URL reportada |
+| `49134` | iii-engine | WebSocket; workers se registram aqui, a telemetria OTel flui por aqui | `III_ENGINE_PORT` ou `III_ENGINE_URL` |
+
+`--port ` muda a âncora REST e deriva streams em `N+1`, viewer em `N+2` e o WebSocket do engine em `N+46023`, só onde a porta ou URL explícita correspondente acima não estiver definida. Isso não cria um namespace isolado de ciclo de vida. Use `--instance 1` para um segundo daemon; ele usa a âncora 3211, com padrão `3211/3212/3213/49234`, e recebe um diretório separado de dados e ciclo de vida `instance-1`. As instâncias de 1 a 50 seguem o mesmo padrão.
+
+O engine fixado inicia com `--no-update-check` (sem buscas de update ou aviso de segurança contra o GitHub no boot) e com a telemetria de uso anônima do iii desativada: agentmemory define `III_TELEMETRY_ENABLED=false` para o engine que ele dispara, a menos que você mesmo exporte a variável, e o compose file empacotado faz o mesmo.
-Limpeza de processo travado quando as portas ficam ocupadas após uma execução crashada:
+Limpeza de processo obsoleto quando as portas continuam em uso depois de uma execução que travou:
```bash
# macOS / Linux — find whatever is on each port and kill it
@@ -1359,33 +1590,35 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` recolhe tanto o worker quanto o pidfile do engine de forma limpa no shutdown graceful. No modo Docker ele derruba apenas os serviços compose do próprio agentmemory e recolhe o worker nativo antes do teardown do Docker; o CLI também se recusa a adotar ou sinalizar processos Docker ou de VM segurando portas (Docker backend, vpnkit, colima) como se fossem o engine nativo, a menos que `--force` seja passado. A limpeza manual acima só serve para o caso pós-crash em que nenhum pidfile foi deixado para trás.
+`agentmemory stop` recolhe tanto o worker quanto o pidfile do engine de forma limpa, num shutdown gracioso e nativo. No modo Docker, ele esvazia o worker nativo, para exatamente o contêiner do engine validado, e preserva tanto o contêiner quanto seu mount `/data` para um reinício sem perdas; o próximo início valida e retoma esse mesmo contêiner. A desinstalação com backend Docker exige `agentmemory remove --keep-data`: ela remove os arquivos compartilhados gerenciados pelo agentmemory preservando o contêiner validado, seu mount de dados e o registro de ciclo de vida necessário para recuperá-los. A deleção destrutiva de dados do Docker é deixada intencionalmente para o operador, depois de um backup. O CLI também se recusa a adotar ou sinalizar processos Docker ou de VM segurando portas (Docker backend, vpnkit, colima) como se fossem o engine nativo, a menos que `--force` seja passado. 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
+### Arquivo de config
-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.
+Coloque a configuração de runtime do agentmemory em `~/.agentmemory/.env` em vez de exportar variáveis em todo shell. Se o viewer mostrar uma dica de setup como `export ANTHROPIC_API_KEY=...`, copie-a para esse arquivo como `ANTHROPIC_API_KEY=...`, sem o prefixo `export`, e então reinicie o agentmemory.
-Variáveis de ambiente do processo continuam funcionando e têm precedência sobre os valores no arquivo.
+Variáveis de ambiente do processo continuam funcionando e têm precedência sobre valores no arquivo.
-No Windows, o mesmo arquivo fica em `%USERPROFILE%\.agentmemory\.env`:
+No Windows, o mesmo arquivo mora 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:
+Para testar com uma assinatura Claude Code Pro/Max em vez de uma API key, opte por isso explicitamente:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-Ligue features de graph ou consolidation no mesmo arquivo se quiser:
+A compressão de observações escrita por LLM exige as duas linhas: acesso a um provider de LLM (incluindo este fallback explícito de assinatura) e `AGENTMEMORY_AUTO_COMPRESS=true`. Um provider por si só deixa o caminho padrão de compressão sintética no lugar.
+
+A consolidação (nodes de grafo, lessons, crystals) vem ativada por padrão sempre que um provider de LLM está configurado. Desative explicitamente com `CONSOLIDATION_ENABLED=false` se você quiser operação sem LLM. A extração de grafo é uma flag separada:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Variáveis de ambiente
@@ -1427,13 +1660,15 @@ Crie `~/.agentmemory/.env`:
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1451,14 +1686,20 @@ Crie `~/.agentmemory/.env`:
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1499,13 +1740,43 @@ Crie `~/.agentmemory/.env`:
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
-# CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1519,26 +1790,44 @@ Crie `~/.agentmemory/.env`:
-124 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer ` quando `AGENTMEMORY_SECRET` está definido, e endpoints de mesh sync exigem `AGENTMEMORY_SECRET` em ambos os peers.
+138 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer `, e endpoints de mesh sync exigem um `AGENTMEMORY_SECRET` explicitamente definido em ambos os peers.
+
+**A autenticação vem ativada por padrão.** Quando `AGENTMEMORY_SECRET` não está definido (no shell ou em `~/.agentmemory/.env`), o servidor gera um secret aleatório no primeiro início e o guarda em `~/.agentmemory/secret` com modo `0600`. Todo cliente empacotado o lê de lá quando fala com um servidor local: o CLI, o viewer, os hooks em `plugin/scripts`, o servidor MCP e o shim `@agentmemory/mcp`, as configs escritas por `agentmemory connect`, e as integrações empacotadas de OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. O secret guardado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Um `AGENTMEMORY_SECRET` explícito sempre prevalece, e clientes remotos ainda precisam dele definido. O Docker e os entrypoints de `deploy/` já geram e exportam o próprio secret. Para chamar a API manualmente:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Regras de requisição para escritas.** Requisições `POST`, `PUT`, `PATCH` e `DELETE` para a REST API e o viewer devem enviar `Content-Type: application/json` (um parâmetro `charset` não tem problema) sempre que carregarem um body, e um header `Origin`, quando presente, deve ser uma origem de loopback para a porta REST ou do viewer configurada, ou estar listado em `VIEWER_ALLOWED_ORIGINS` (separado por vírgulas, por exemplo `https://memory.example.com`). Clientes que não enviam header `Origin` (CLI, hooks, MCP, curl, servidor-para-servidor) não são afetados. O viewer também aceita sua própria origem.
+
+**Caminhos de arquivo.** Endpoints que leem ou escrevem arquivos (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) só aceitam caminhos dentro de `~/.agentmemory`, do diretório de dados da instância, ou de um diretório listado em `AGENTMEMORY_IMPORT_ROOT` (separe vários com `:`, ou `;` no Windows). `/replay/import-jsonl` também aceita seu padrão `~/.claude/projects`. `/obsidian/export` fica dentro de `AGENTMEMORY_EXPORT_ROOT` e `/migrate` dentro de `~/.agentmemory`. Symlinks são resolvidos antes de toda checagem.
+
+**Limpeza de secrets.** API keys, bearer tokens, blocos de chave privada PEM e credenciais embutidas em URLs (`scheme://user:password@host`) são redigidas antes de o texto ser armazenado, em todo caminho de escrita: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, saída de compressão e resumo, crystals e nodes de grafo.
Endpoints principais
-| Method | Path | Descrição |
+| Método | Caminho | Descrição |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health check (sempre público) |
+| `GET` | `/agentmemory/status` | O que está errado e como corrigir (HTML para navegadores, JSON para o resto) |
+| `GET` | `/agentmemory/viewer/snapshot` | Tudo o que o viewer mostra, em uma única resposta |
| `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/session/end` | Finaliza sessão |
+| `POST` | `/agentmemory/observe` | Captura observação (veja a entrega de captura abaixo) |
+| `GET` | `/agentmemory/capture` | Inbox de captura, dead letters e spool offline |
+| `POST` | `/agentmemory/capture/retry` | Tenta de novo as capturas em dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Envia agora o spool offline local |
| `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/profile` | Perfil do 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/import` | Importa a partir de JSON |
+| `POST` | `/agentmemory/graph/query` | Consulta ao grafo de conhecimento |
+| `POST` | `/agentmemory/graph/compact` | Reduz provenance de grafo superdimensionada |
| `POST` | `/agentmemory/team/share` | Compartilha com o time |
| `GET` | `/agentmemory/audit` | Trilha de auditoria |
@@ -1546,6 +1835,35 @@ Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+**Entrega de captura.** Os hooks enviam cada observação uma única vez para `POST /agentmemory/observe` com um `eventId`. Esse id é o próprio id do host para a chamada, quando o payload tem um (por exemplo, o `tool_use_id` do Claude Code), ou então um hash da sessão, tipo de hook, nome da tool, entrada, saída e timestamp do host. O servidor grava o evento em um inbox de captura no state store, armazena a observação e então remove a entrada do inbox. O status code diz o que aconteceu:
+
+| Status | Campo `status` | Significado |
+|---|---|---|
+| `201` | `accepted` | Armazenada. `observationId` é a nova observação. |
+| `202` | `accepted` (`state: "retrying"`) | Aceita, mas o armazenamento falhou. O servidor tenta de novo, inclusive depois de um restart. |
+| `200` | `duplicate` | Este `eventId` já havia sido aceito. `observationId` é a observação existente; nada novo é armazenado. |
+| `400` / `422` | `rejected` | Payload inválido, ou o armazenamento falhou de forma definitiva (o evento é mantido como dead letter). |
+| `503` | `rejected` (`retryable: true`) | O inbox está cheio (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Os hooks colocam o evento no spool e o enviam depois. |
+
+Eventos que falham são tentados de novo a cada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) com backoff que dobra, até `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Eventos que continuam falhando ficam no inbox como dead letters, são listados em `/agentmemory/status` e na página Health do viewer, e podem ser tentados de novo com `POST /agentmemory/capture/retry` (`{"eventId": "..."}` ou `{"all": true}`). Ids de evento aceitos são lembrados por `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 horas, no máximo `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), então um hook reproduzido depois de um timeout ou de um restart é armazenado uma única vez, enquanto duas chamadas de tool separadas com seus próprios ids de host são armazenadas duas vezes, mesmo quando o conteúdo delas é idêntico. Quando uma observação é deletada (forget, deleção de sessão, eviction, auto-forget ou um import que substitui o store), o evento dela é marcado como deletado antes que a observação seja removida, então uma reprodução desse evento dentro da mesma janela é respondida como duplicata e não armazena nada. O state store grava em disco a cada 2 segundos, então um evento já respondido ainda pode estar só em memória por um instante. Para cobrir isso, toda resposta `2xx` também carrega o `bootId` do servidor (novo a cada início), `acceptedAt` e `durableAfterMs` (o intervalo de save mais 1.5 s no store de arquivo, 1.5 s no redis, onde a persistência é configuração do operador). Os hooks mantêm o evento no spool local até que essa janela tenha passado, e o deletam numa chamada posterior sem fazer outra requisição. Se o `bootId` tiver mudado até então, o servidor reiniciou, então o hook envia o evento de novo com o mesmo `eventId`; um evento que de fato chegou ao disco não é armazenado duas vezes. O servidor também envia esses eventos por conta própria no início e a cada intervalo de retry, então um restart não perde nada mesmo quando nenhum hook roda depois. Hooks antigos ignoram os campos extras, e hooks novos contra um servidor mais antigo descartam o evento no `2xx` como antes.
+
+Quando o servidor está fora do ar, não responde a tempo ou retorna um 5xx, o hook anexa a observação a um arquivo de spool local, `/capture-spool/-.jsonl` (sobrescreva a pasta com `AGENTMEMORY_CAPTURE_SPOOL_DIR`). O arquivo é privado ao seu usuário (modo 600), secrets são redigidos da mesma forma que o servidor os redige, ele guarda no máximo `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) e descarta entradas mais antigas que `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Quando está cheio, novas entradas são descartadas e contadas, e `/agentmemory/status` reporta isso. O hook ainda sai com código 0 dentro do seu limite de tempo e não adiciona nenhuma requisição quando o servidor está saudável. O spool é enviado no próximo início e pelo primeiro hook que alcançar o servidor de novo, em um processo em segundo plano para que o agente não espere. Ids de evento tornam isso seguro: uma observação que já chegou antes de um timeout não é armazenada duas vezes. `npx @agentmemory/agentmemory capture` mostra o spool e o inbox do servidor, `--drain` envia o spool agora, e `GET /agentmemory/capture` retorna o mesmo em JSON. Defina `AGENTMEMORY_CAPTURE_SPOOL=false` para desativar o spool.
+
+**Compactando provenance de grafo.** Todo node e edge do grafo de conhecimento guarda os ids das 32 observações mais recentes de onde ele veio. Stores escritos antes desse limite podem acumular milhares de ids por node quente, o que torna a busca de grafo e o viewer lentos ou derruba o worker. agentmemory corrige isso por conta própria: no primeiro início depois de um upgrade, ele reduz todo node, edge, edge supersedido (o histórico temporal do grafo) e o snapshot em cache para o limite, em segundo plano, em fatias pequenas com uma pausa entre elas, de modo que busca, captura e o viewer continuem funcionando. Ele salva seu progresso, retoma depois de um restart e nunca roda de novo depois de terminar. `/agentmemory/status` e a página Health do viewer mostram isso como pendente, em execução (com o scope e a posição atuais), concluído ou falho. Defina `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` para desativar.
+
+Para rodar manualmente, chame `POST /agentmemory/graph/compact`. Ele percorre os índices de nome e de chave de edge em vez de listar todo node e edge, e é seguro rodar de novo. Quando reduz ids, ele grava uma entrada de auditoria `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Em um store grande, ou quando a chamada retorna 504, rode em fatias. Envie `scope` (`nodes`, `edges` ou `history`), `offset` e `limit`, depois chame de novo com o `nextOffset` retornado até que seja `null`. Faça isso para `nodes`, `edges` e `history`, e termine com uma chamada `{"scope":"snapshot"}`, porque uma execução em fatias não toca o snapshot em cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1553,11 +1871,11 @@ Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**Pré-requisitos:** Node.js >= 20, [iii-engine](https://iii.dev/docs) ou Docker
+**Pré-requisitos:** Node.js >= 20 com npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 ou Docker. A instalação automática do engine no macOS/Linux também exige `curl`, um `sh` POSIX e `tar`; o Windows nativo usa o `iii.exe` fixado manual, o WSL2 ou o Docker Desktop.
diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.md
new file mode 100644
index 0000000000..c858b4a073
--- /dev/null
+++ b/READMEs/README.pt-PT.md
@@ -0,0 +1,1881 @@
+
+
+
+
+
+
+ O seu agente de codificação lembra-se de tudo. Chega de voltar a explicar.
+ Construído sobre o iii engine
+
+ Memória persistente para Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualquer cliente MCP.
+
+ O gist alarga o padrão LLM Wiki de Karpathy com pontuação de confiança, ciclo de vida, grafos de conhecimento e pesquisa híbrida: o agentmemory é a implementação.
+
+
+---
+
+## Instalação
+
+Requisitos:
+
+- Node.js 20 ou mais recente, com npm e npx (`node -v`, `npm -v` e `npx -v`).
+- A instalação automática do iii-engine no macOS/Linux também precisa de `curl`, de um `sh` POSIX e de `tar`. Imagens minimalistas como `node:20-slim` podem não os incluir.
+- O Windows nativo exige que o `iii.exe` do iii-engine fixado na v0.22.1 seja instalado manualmente. O WSL2 ou o Docker Desktop são os outros caminhos suportados.
+
+Comando canónico para uma instalação limpa:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+A primeira execução é uma configuração interativa: escolha os agentes a ligar (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), escolha um fornecedor de LLM ou fique sem chave, e esta gera a configuração, inicia o servidor de memória e o seu iii engine fixado, e propõe instalar globalmente para que o comando simples `agentmemory` funcione em qualquer lugar depois disso. O `-y` aceita o prompt do pacote do npx e o `@latest` evita uma versão desatualizada em cache. Um fornecedor disponibiliza as funcionalidades de LLM, mas a compressão de observações escrita por LLM só é iniciada quando `AGENTMEMORY_AUTO_COMPRESS=true` também está definida.
+
+O modo sem chave desativa os embeddings vetoriais. O `memory_recall` (o caminho `mem::search`) usa BM25, enquanto o `memory_smart_search` também pode combinar correspondências estruturais do grafo quando já existem dados de grafo. Para obter recall semântico local e gratuito, defina `EMBEDDING_PROVIDER=local` em `~/.agentmemory/.env` e reinicie. O primeiro pedido de embedding faz o download de `Xenova/all-MiniLM-L6-v2`; a inferência corre localmente depois desse download inicial do modelo.
+
+O runtime local usa quatro portas: `3111` para REST/MCP HTTP, `3112` para os streams do iii, `3113` para o visualizador e `49134` para o WebSocket do worker iii. O estado persistente do iii vive em `~/Library/Application Support/agentmemory` no macOS, em `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` no Linux, e em `%APPDATA%\agentmemory` no Windows. Use `--data-dir ` ou `AGENTMEMORY_DATA_DIR` para o substituir, e reutilize o mesmo valor em cada reinício. Por compatibilidade com versões anteriores, um `./data/state_store.db` ou `./data/iii-config.yaml` já existentes têm precedência sobre a predefinição da plataforma para a instância 0; uma flag explícita ou uma variável de ambiente continuam a ganhar.
+
+Depois, prove que o recall funciona e dê ao seu agente as suas skills:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+As pesquisas por palavra-chave devem ter resultados no modo sem chave predefinido, através do BM25. A query `database performance optimization` da demo é propositadamente semântica e pode devolver zero resultados até que um fornecedor de embeddings seja configurado.
+
+Prefere deixar um agente de codificação fazer tudo? Dê-lhe uma única instrução:
+
+> Obtenha e siga as instruções em: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Ligue mais agentes em qualquer momento com `agentmemory connect ` — 20 adaptadores listados em [Funciona com qualquer agente](#works-with-every-agent). Referência completa de comandos em [Início Rápido](#quick-start).
+
+
+Windows
+
+O caminho mais rápido é o WSL2. A configuração do engine no Windows nativo exige o download manual do ZIP fixado na v0.22.1 e a extração manual do `iii.exe`; o CLI não o extrai automaticamente. O Docker Desktop também é suportado. Veja as [notas de Windows](#windows) para o passo a passo.
+
+
+
+
+Instalação global / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+O comando npx acima continua a ser o caminho canónico para uma instalação limpa e evita problemas de permissões do prefixo global.
+
+
+
+
+O npx está a servir uma versão antiga
+
+O npx faz cache por versão. Force a mais recente com `npx -y @agentmemory/agentmemory@latest`, ou limpe a cache uma vez com `rm -rf ~/.npm/_npx` (macOS/Linux; no Windows elimine `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Já tem o seu próprio iii engine em execução
+
+O agentmemory fixa o iii-engine na v0.22.1 e não se liga a uma versão diferente (o worker não fala o protocolo de outro engine). Pare o outro engine e execute `npx -y @agentmemory/agentmemory@latest`. Este instala e executa a v0.22.1 fixada em `~/.agentmemory/bin`, deixando o seu próprio `iii` intacto.
+
+
+
+---
+
+
+
+O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Todos os agentes partilham o mesmo servidor de memória.
+
+
+
+
+
+Claude Code
+plugin nativo + 12 hooks + MCP
+
+
+
+Codex CLI
+plugin nativo + 6 hooks + MCP
+
+
+
+GitHub Copilot CLI
+MCP + hooks/skills do plugin
+
+
+
+Cursor
+plugin nativo + 7 hooks + MCP
+
+
+
+OpenCode
+plugin de captura + MCP
+
+
+
+
+
+Devin
+6 hooks + skills + MCP
+
+
+
+OpenClaw
+plugin nativo + MCP
+
+
+
+Hermes
+plugin nativo + MCP
+
+
+
+pi
+plugin nativo + MCP
+
+
+
+OpenHuman
+backend nativo com trait Memory
+
+
+
+
+
+Gemini CLI
+servidor MCP
+
+
+
+Antigravity
+MCP + hooks
+
+
+
+Claude Desktop
+servidor MCP
+
+
+
+Warp
+connect + MCP + skills
+
+
+
+Zed
+servidor MCP
+
+
+
+
+
+Cline
+servidor MCP
+
+
+
+Continue
+servidor MCP
+
+
+
+Droid
+servidor MCP
+
+
+
+Kiro
+servidor MCP
+
+
+
+Qwen Code
+servidor MCP
+
+
+
+
+
+DeepSeek Harness
+servidor MCP
+
+
+
+Roo Code
+servidor MCP
+
+
+
+Kilo Code
+servidor MCP
+
+
+
+Goose
+servidor MCP
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Funciona com qualquer agente que fale MCP ou HTTP. Um servidor, memórias partilhadas entre todos eles.
+
+
+---
+
+Explica a mesma arquitetura em cada sessão. Redescobre os mesmos bugs. Volta a ensinar as mesmas preferências. A memória incorporada (CLAUDE.md, .cursorrules) tem um limite de 200 linhas e torna-se desatualizada. O agentmemory resolve isto. Captura silenciosamente o que o seu agente faz, comprime-o em memória pesquisável e injeta o contexto certo quando a sessão seguinte começa. Um único comando. Funciona entre agentes.
+
+**O que muda:** Na sessão 1 configura a autenticação JWT. Na sessão 2 pede limitação de taxa (rate limiting). O agente já sabe que a sua autenticação usa o middleware jose em `src/middleware/auth.ts`, que os seus testes cobrem a validação de tokens, e que escolheu jose em vez de jsonwebtoken por compatibilidade com Edge, sem voltar a explicar e sem copiar e colar.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Por predefinição, o agentmemory guarda o estado do iii-engine fora do repositório a partir do qual é iniciado: `~/Library/Application Support/agentmemory` no macOS, `$XDG_DATA_HOME/agentmemory` ou `~/.local/share/agentmemory` no Linux, e `%APPDATA%\agentmemory` no Windows. Um `./data/state_store.db` ou `./data/iii-config.yaml` legados já existentes são reutilizados para a instância 0 antes dessa predefinição da plataforma. Para escolher uma localização explicitamente, passe `--data-dir ` ou defina `AGENTMEMORY_DATA_DIR`; qualquer uma destas definições explícitas tem precedência sobre a deteção legada:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+As execuções nativas e em Docker usam este mesmo diretório do anfitrião já resolvido; o Docker monta-o com bind em `/data`. O `--instance 1` acrescenta `instance-1` ao diretório resolvido e seleciona o quarteto de portas predefinido separado `3211/3212/3213/49234`.
+
+Notas da versão mais recente: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### 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 híbrido** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep de referência | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+Taxa de acerto top-5 de 100% no **teto matemático do P@5** para este corpus (0.240, ver scorecard). O híbrido recupera todas as sessões gold; o grep falha 1 de 2 golds na query temporal multi-sessão. O ganho está no **recall + temporal**, não na precisão agregada. Este benchmark é pequeno e escasso em golds; o LongMemEval-S maior, abaixo, diferencia melhor. Detalhamento completo por tipo + nota de correção: [`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%** |
+| fallback apenas BM25 | 86.2% | 94.6% | 71.5% |
+
+
+
+> Modelo de embedding: `all-MiniLM-L6-v2` (local, gratuito, sem chave de API). Relatórios completos: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparação com concorrentes: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) cobrindo agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Reproduzir localmente:** [`eval/README.md`](../eval/README.md), um harness com adaptadores encaixáveis para o LongMemEval `_s` (500 perguntas públicas) + `coding-agent-life-v1` (corpus interno de 15 sessões). Os adaptadores grep / vetor / agentmemory são avaliados lado a lado, com saída NDJSON, e os scorecards publicados ficam em [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Combina-se 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 em docs / PDFs / imagens / vídeos. O agentmemory recorda o trabalho; estes três projetos iluminam o resto da camada de contexto. Receitas + tabela de encaminhamento de perguntas: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Incorporado (CLAUDE.md)
+
+
+
Tipo
+
Motor de memória + servidor MCP
+
API de camada de memória
+
Runtime completo de agente
+
IA pessoal
+
API de memória + app
+
Hub de memória de equipa (proxy LLM)
+
Memória vetorial (OSS)
+
Motor de memória (Oracle DB)
+
Sistema de memória
+
Ficheiro estático
+
+
+
Recuperação R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Autorreportado
+
PersonaMem 76% (autorreportado)
+
~96.6% (autorreportado)
+
94.4% (autorreportado)
+
N/A
+
N/A (grep)
+
+
+
Captura automática
+
12 hooks (esforço manual zero)
+
Chamadas manuais a add()
+
Autoedição pelo agente
+
Manual
+
Extração do lado da API
+
Interceção via proxy (troca de URL base)
+
Manual
+
Extração via API
+
Manual
+
Edição manual
+
+
+
Pesquisa
+
BM25 + Vetor + Grafo (fusão RRF)
+
Vetor + Grafo
+
Vetor (arquivo)
+
Semântica
+
Vetor + RAG
+
4 tipos de recursos (Chat / Skill / Wiki / CodeGraph)
+
Apenas vetor
+
Vetor + semântica
+
Ponderada por decaimento
+
Carrega tudo para o contexto
+
+
+
Multiagente
+
MCP + REST + leases + signals
+
API (sem coordenação)
+
Apenas dentro do runtime da Letta
+
Não
+
Não
+
Papéis de equipa + recursos partilhados
+
Não
+
Apenas com âmbito definido
+
Partilhada multiagente
+
Ficheiros por agente
+
+
+
Dependência de framework
+
Nenhuma (qualquer cliente MCP)
+
Nenhuma
+
Alta (tem de usar Letta)
+
Autónomo
+
Nenhuma
+
O proxy intermedeia todas as chamadas ao modelo
+
Nenhuma
+
Oracle Database
+
Nenhuma
+
Formato por agente
+
+
+
Dependências externas
+
Nenhuma (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + BD vetorial
+
Várias
+
Nuvem gerida
+
Stack Docker (Core + Hub + Proxy)
+
Armazenamento vetorial
+
Oracle AI Database
+
Nenhuma
+
Nenhuma
+
+
+
Ciclo de vida da memória
+
Consolidação em 4 níveis + decaimento + esquecimento automático
+
Extração passiva
+
Gerido pelo agente
+
Manual
+
Esquecimento automático
+
Revisão manual; encaminhamento automático em desenvolvimento
+
Nenhum
+
Não indicado
+
Decaimento + consolidação
+
Limpeza manual
+
+
+
Eficiência de tokens
+
~1,900 tokens/sessão ($10/ano)
+
Varia com a integração
+
Memória principal no contexto
+
Varia
+
Preços na nuvem
+
Não indicado
+
Sem orçamento de tokens
+
Suportado por LLM (varia)
+
Varia
+
22K+ tokens em 240 observações
+
+
+
Visualizador em tempo real
+
Sim (porta 3113)
+
Painel na nuvem
+
Painel na nuvem
+
Interface Web
+
Painel na nuvem
+
Interface Web do hub
+
Não
+
Não
+
Não
+
Não
+
+
+
Auto-hospedado
+
Sim (predefinição)
+
Opcional
+
Opcional
+
Sim
+
Não (apenas na nuvem)
+
Sim (Docker)
+
Sim
+
Sim (Oracle DB)
+
Sim
+
Sim
+
+
+
+Nota sobre o benchmark: apenas o R@5 do agentmemory é um resultado medido por nós (LongMemEval-S, reproduzível a partir de benchmark/COMPARISON.md). Os valores de mem0 e Letta são os números LoCoMo publicados por eles (um dataset diferente); os valores de MemPalace, supermemory, TencentDB (PersonaMem) e oracleagentmemory são afirmações autorreportadas pelos fornecedores que não reproduzimos de forma independente (a execução do oracleagentmemory usou o GPT-5.5 contra uma Oracle AI Database). Mostrados lado a lado apenas como estimativa aproximada, não como comparação direta sobre dados idênticos. As contagens de estrelas são aproximadas e variam com o tempo.
+
+**Participantes mais recentes** que vale a pena conhecer, comparados em profundidade em [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Sistema | ⭐ | Abordagem |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Grafo de conhecimento temporal; os resultados publicados mais fortes em queries temporais (LongMemEval 63.8%), mas o grafo é construído de forma assíncrona, por isso os factos recentes podem atrasar |
+| Cognee | 30K | Ingestão de documentos para grafo de conhecimento, apenas Python, construído para extração estruturada de entidades em vez de captura de sessões |
+
+Nenhum destes faz captura automática a partir de hooks de agentes de codificação, entrega um visualizador local-first, ou funciona sem chave — a combinação em torno da qual o agentmemory foi construído.
+
+---
+
+
+
+Compatibilidade: esta versão visa o `iii-sdk` 0.22.1 e fixa o iii-engine na v0.22.1.
+
+### Experimente em 30 Segundos
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+O `demo` gera 3 sessões realistas (autenticação JWT, correção de uma query N+1, limitação de taxa) e executa pesquisas sobre elas. As instalações sem chave desativam os vetores, por isso as queries por palavra-chave do `mem::search` devem ter resultados através do BM25, enquanto `database performance optimization` pode devolver zero. O `smart-search` pode também devolver correspondências estruturais do grafo quando existem dados de grafo. Para que a query semântica encontre a correção da N+1 através de vetores, defina `EMBEDDING_PROVIDER=local`, reinicie e deixe terminar o primeiro download do modelo.
+
+Abra `http://localhost:3113` para ver a memória a construir-se em direto.
+
+### Validar uma Instalação Limpa e a Persistência ao Reiniciar
+
+Com o servidor em execução, valide o REST, a saúde (health), o visualizador e o estado do runtime suportado pelo iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+O painel de arranque pronto (ready) tem em conta as quatro portas: REST/MCP HTTP na 3111, streams do iii na 3112, o visualizador na 3113 e o WebSocket do worker iii na 49134. O `status` confirma a saúde do agentmemory e o modo ativo de fornecedor/embedding. Guarde uma sonda e confirme que é pesquisável:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Depois execute `npx -y @agentmemory/agentmemory@latest stop`, inicie novamente o comando canónico no Terminal 1, espere por `/agentmemory/livez` e repita a pesquisa. A sonda tem de continuar a ser devolvida. Se selecionou um `--data-dir` personalizado, passe o mesmo diretório ao reiniciar.
+
+### Comandos do Dia a Dia
+
+A instalação e a configuração estão em [Instalação](#install) acima (a primeira execução guia-o passo a passo). No dia a dia:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Reprodução de Sessões
+
+Todas as sessões que o agentmemory regista podem ser reproduzidas. Abra o visualizador, escolha o separador **Replay** e percorra a linha do tempo: prompts, chamadas a ferramentas, resultados de ferramentas e respostas são apresentados como eventos discretos, com play/pause, controlo de velocidade (0.5x a 4x) e atalhos de teclado (espaço para alternar, setas para avançar passo a passo).
+
+Para importar transcrições JSONL mais antigas do Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+As sessões importadas aparecem no seletor do Replay junto às nativas. Por trás, cada entrada passa pelas funções iii `mem::replay::load`, `mem::replay::sessions` e `mem::replay::import-jsonl`, sem servidores paralelos. Cada transcrição importada é indexada para pesquisa, marcada com o canal de origem `import`, e processada para gerar um crystal de sessão e lessons.
+
+> **Atenção, se depende do `import-jsonl` como o seu caminho principal de captura:** o `cleanupPeriodDays` do Claude Code (em `~/.claude/settings.json`, predefinição **30**) elimina automaticamente as transcrições JSONL mais antigas do que essa janela em `~/.claude/projects/`. Se instalar o agentmemory do zero sobre um histórico do Claude Code com meses, tudo o que tiver mais de 30 dias já desapareceu antes da primeira importação. Execute o `import-jsonl` num cron, aumente o `cleanupPeriodDays` para um valor mais alto, ou ligue os hooks de captura automática (o caminho predefinido de instalação do plugin) para que cada turno chegue ao agentmemory enquanto a sessão está ativa e a limpeza do JSONL deixe de ter importância.
+
+### Atualização / Manutenção
+
+Use o comando de manutenção quando quiser, de forma intencional, atualizar o seu runtime local:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Aviso: este comando altera o workspace/runtime atual. Pode atualizar dependências JavaScript e descarregar a imagem Docker fixada `iiidev/iii:0.22.1`. Nunca instala um iii engine sem fixação de versão ou mais recente.
+
+Os detalhes de implementação estão em `src/cli.ts` (ver `runUpgrade` na zona `src/cli.ts:544-595`).
+
+### Claude Code (um bloco, cole-o)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code sem instalar o plugin (caminho MCP standalone)
+
+Se ligar o servidor MCP do agentmemory através de `~/.claude.json` diretamente, em vez de usar `/plugin install`, o Claude Code nunca resolve `${CLAUDE_PLUGIN_ROOT}` e tem de apontar os scripts de hook para caminhos absolutos em `~/.claude/settings.json`. Esses caminhos normalmente incorporam a versão do agentmemory (por exemplo, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), por isso a atualização seguinte quebra silenciosamente todos os hooks.
+
+Solução alternativa:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Isto combina 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. Volte a executar o comando depois de atualizar o agentmemory para atualizar os caminhos. As entradas do utilizador no mesmo ficheiro são preservadas; só as entradas anteriores do agentmemory são substituídas. Usar o caminho `/plugin install` continua a ser a abordagem recomendada.
+Para implementações remotas ou protegidas, inicie o Claude Code com `AGENTMEMORY_URL` e `AGENTMEMORY_SECRET` definidas. O plugin passa ambos os valores ao seu servidor MCP empacotado; quando `AGENTMEMORY_URL` está vazia, 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 -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+O plugin do Codex é distribuído a partir do mesmo diretório `plugin/` que o plugin do Claude Code. Este regista:
+
+- Uma ponte MCP stdio empacotada para o daemon em execução, sem download via npm nem armazenamento de reserva. Consulte o [guia local do Codex](../docs/plugins/codex-local.md) para testar uma compilação ainda não lançada.
+- 6 hooks de ciclo de vida: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skills invocáveis: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, mais 8 skills de referência que o agente carrega sob demanda (disciplina de memória, ferramentas MCP, REST API, configuração, agentes, hooks, arquitetura e o guia de criação de skills)
+
+O motor 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)), por isso os mesmos scripts de hook funcionam em ambos os anfitriões sem duplicação. Os eventos Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure são exclusivos do Claude Code e não são registados para o Codex.
+
+#### Confiança e compatibilidade dos hooks do Codex
+
+O despacho nativo de hooks de plugin está verificado com o Codex CLI 0.150.1. Confie nos hooks do plugin antes de esperar captura. O comportamento no Desktop depende do seu runtime empacotado; verifique `/hooks` e confirme um evento capturado antes de ativar uma solução alternativa.
+
+Se o seu anfitrião exigir hooks globais, replique os comandos em `~/.codex/hooks.json`. Quando o MCP já está configurado, o conector atual precisa de `--force` para chegar à instalação dos hooks:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Isto combina os hooks globais e reescreve a entrada MCP do agentmemory, preservando as entradas não relacionadas. Reveja quaisquer definições personalizadas do endpoint do agentmemory antes de usar `--force`. Volte a executar depois de atualizar para atualizar os caminhos dos scripts. Ative os hooks nativos do plugin ou as cópias globais para evitar captura duplicada.
+
+### GitHub Copilot CLI
+
+Para o modo de agente do VS Code, utilize o [guia de MCP e captura automática do Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). O conector do CLI não configura o VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` combina `mcpServers.agentmemory` em `~/.copilot/mcp-config.json` (ou `$COPILOT_HOME/mcp-config.json` quando `COPILOT_HOME` está definida) e preserva os servidores existentes. No Windows nativo, este é o único adaptador `connect` automatizado; configure manualmente todos os outros agentes nativos do Windows. O `connect` no WSL só é suportado quando o agente de destino também está instalado nesse mesmo ambiente WSL. O Copilot deteta o servidor MCP no próximo arranque ou depois de `/mcp`. Instale também o plugin quando quiser a experiência completa de hooks/skills.
+
+
+OpenClaw (cole este prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Guia completo: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Agente Hermes (cole este prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Guia completo: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Outros Agentes
+
+Inicie o servidor de memória: `npx -y @agentmemory/agentmemory@latest`
+
+#### Skills nativas via `npx skills add` (50+ agentes)
+
+O agentmemory distribui 17 skills no formato `/SKILL.md`, no estilo do Claude Code: 9 skills de ação invocáveis (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) e 8 skills de referência que o agente carrega sob demanda (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). As skills de referência trazem tabelas de dados geradas a partir do código-fonte, por isso nunca ficam desatualizadas. O CLI [`skills`](https://npmjs.com/package/skills) da vercel-labs instala-as automaticamente no diretório nativo de skills do agente que o invoca, em mais de 50 agentes (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, e outros):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Isto é **complementar** a `agentmemory connect `:
+
+- `agentmemory connect ` escreve a configuração do servidor MCP para que as ferramentas fiquem disponíveis.
+- `npx skills add rohitg00/agentmemory` instala as skills para que o agente saiba quando as chamar.
+
+Para os poucos agentes que o CLI `skills` ainda não cobre (Zed v1.3.x e anteriores), coloque você mesmo os 17 ficheiros SKILL.md no diretório nativo de skills do agente; o mesmo formato funciona em todo o lado.
+
+#### Bloco MCP Padrão
+
+A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todos os anfitriões que usam o formato `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Combine esta entrada com o objeto `mcpServers` existente** no ficheiro de configuração do anfitrião; não substitua o ficheiro. Se o ficheiro já tiver outros servidores, adicione `agentmemory` junto deles como mais uma chave dentro de `mcpServers`. Se `mcpServers` estiver totalmente ausente, cole o bloco dentro de `{ "mcpServers": { ... } }`. Os marcadores `${VAR}` herdam `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` da shell no momento em que o servidor MCP é iniciado; variáveis não definidas passam strings vazias e o shim recua para `http://localhost:3111`. Uma única entrada ligada cobre tanto implementações locais como remotas (k8s / com proxy inverso).
+
+| Agent | Config file | Notes |
+|---|---|---|
+| **Cursor (apenas MCP)** | `~/.cursor/mcp.json` | Combine com `mcpServers`, ou use `agentmemory connect cursor`. Também está disponível um deeplink de um clique no site. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Listagem no Cursor Marketplace (submissão em revisão) ou Cursor Settings → Plugins → checkout local. Regista 7 hooks de captura automática (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + o servidor MCP, com `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` geridas no painel de plugins do Cursor. Funciona no Cursor IDE e no CLI `cursor-agent`; os prompts do modo print do CLI são preenchidos retroativamente a partir da transcrição da sessão no fim da sessão. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Combine com `mcpServers`. Reinicie o Claude Desktop depois de editar. |
+| **Cline / Roo Code / Kilo Code** | Definições MCP do Cline (Settings UI → MCP Servers → Edit) | Mesmo bloco `mcpServers`. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` combina a entrada MCP; `--with-hooks` adiciona seis hooks nativos de captura automática (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) com os correspondentes de ferramentas em minúsculas do Devin. Verifique com `devin mcp list` e `/hooks` dentro do devin. |
+| **Devin CLI (plugin completo)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` a partir de um checkout regista as 17 skills como comandos slash `/agentmemory:`, além do servidor MCP. Os hooks de plugin do Devin não conseguem disparar `SessionStart`/`SessionEnd`, por isso combine com `connect devin --with-hooks` para uma captura completa da sessão. |
+| **Devin (nuvem)** | Settings → Connections → MCP servers | Adicione um MCP personalizado (STDIO): comando `npx`, argumentos `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` a apontar para uma implementação do agentmemory acessível pela rede, mais `AGENTMEMORY_SECRET` (as sessões na nuvem não conseguem alcançar o localhost — ver [`deploy/`](../deploy/)). Guarde o segredo em Devin Secrets e depois use "Test listing tools" para confirmar que aparecem as 54 ferramentas. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (combina automaticamente). |
+| **GitHub Copilot CLI (apenas MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` combina `mcpServers.agentmemory`; o Copilot deteta-o no próximo arranque ou com `/mcp`. |
+| **GitHub Copilot CLI (plugin completo)** | Instalação de plugin do Copilot | `copilot plugin install rohitg00/agentmemory:plugin` para o plugin a partir do subdiretório do GitHub. |
+| **OpenClaw** | Configuração MCP do OpenClaw | Mesmo bloco `mcpServers`. Mais profundo: `openclaw plugins install ./integrations/openclaw` reivindica o slot de memória do OpenClaw (muda automaticamente de `memory-core`); defina `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, ou a captura de turnos é bloqueada silenciosamente. Ver [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (apenas 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`. Regista MCP + 6 hooks de ciclo de vida + 17 skills. Confie nos hooks e verifique a captura no seu anfitrião; consulte [configuração e validação do Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (apenas MCP)** | `opencode.json` | Formato diferente: chave `mcp` de nível 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, cobrindo o ciclo de vida da sessão, mensagens, ferramentas e erros. A atribuição de projeto é feita por sessão, por isso um único processo do OpenCode que abrange vários repositórios arquiva cada sessão sob o seu próprio projeto. Dois comandos slash (`/recall`, `/remember`). Copie `plugin/opencode/` para o seu workspace do OpenCode e adicione a entrada do plugin a `opencode.json`. Ver [`plugin/opencode/README.md`](../plugin/opencode/README.md) para a tabela completa de hooks + análise de lacunas. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instala a extensão empacotada no diretório de auto-deteção do pi (recall ao iniciar o agente, captura ao terminar o agente, ferramentas `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). O `/reload` num pi em execução deteta-a. [`integrations/pi`](../integrations/pi/) é também um pacote pi (`pi install ./integrations/pi` a partir de um checkout). |
+| **Agente Hermes** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` dá o fornecedor de memória com 6 hooks (prefetch, captura de turno, fim de sessão, pré-compressão, espelhamento de MEMORY.md, bloco de prompt do sistema). Valide com `hermes plugins doctor` e `hermes memory status`. Ver [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` escreve o bloco `mcpServers` padrão. O payload dos hooks é compatível a nível de campos com o Claude Code, por isso os scripts dos 12 hooks existentes funcionam sem modificação; ligue-os através da secção `hooks` no mesmo `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instala o MCP e os hooks de captura no diretório de personalização partilhado. Consulte [configuração e limites do Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` usa a mesma configuração de MCP e hooks das versões atuais do IDE. As instalações existentes devem atualizar com `--force`; consulte as [notas de atualização](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` escreve a configuração ao nível do utilizador. As substituições ao nível do workspace vão em `.kiro/settings/mcp.json`, junto ao seu código. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` escreve o bloco `mcpServers` padrão. O Warp também deteta automaticamente skills em `.claude/skills/`; depois de instalado o plugin do Claude Code, as 8 skills do agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) aparecem nativamente na paleta de comandos slash do Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` escreve o bloco `mcpServers` padrão. Utilizadores da extensão VS Code: cole o mesmo bloco através de Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferido) ou `config.json` (legado) | `agentmemory connect continue` cria `config.yaml` do zero quando nenhum dos dois existe, ou modifica o `config.json` existente. **Se já tiver `config.yaml`**, o adaptador imprime o bloco exato para colar sob `mcpServers:`; não reescreve o seu yaml silenciosamente, porque preservar comentários e anchors em segurança precisa de um parser YAML que o pacote não inclui. O Continue usa a forma de array (não de objeto) para `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` escreve sob `context_servers` (a chave do Zed, NÃO `mcpServers`). Servidores MCP remotos podem, em alternativa, ser ligados através de `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` escreve o bloco `mcpServers` padrão. As substituições ao nível do projeto vão em `/.factory/mcp.json`. Passe `--with-hooks` para captura automática nativa. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` acrescenta uma linha `@deepseek-ai/dsh-mcp-client` à camada de patch ao nível home que todos os perfis do Harness carregam; as ferramentas registam-se como `mcp__agentmemory__*`. Passe `--with-hooks` para também ligar a captura automática: os scripts de hook do Claude Code empacotados correm através da ponte oficial `@deepseek-ai/dsh-hooks-claude-code` do Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), via um manifesto escrito em `$DSH_HOME/agentmemory.hooks.json`. Usa por predefinição `~/.dsh` quando `DSH_HOME` não está definida. |
+| **Goose** | Settings UI de MCP do Goose | Mesmo bloco `mcpServers`; use `goose configure` → Add Extension → MCP. A edição direta do YAML em `~/.config/goose/config.yaml` é suportada, mas o esquema usa `extensions:` + `cmd` (não `mcpServers:` + `command`). |
+| **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` deteta automaticamente o anfitrião e combina a configuração. |
+
+**Clientes MCP em sandbox** (Flatpak / Snap / contentores restritivos) que não conseguem alcançar o `localhost` do anfitrião: defina também `"AGENTMEMORY_FORCE_PROXY": "1"` no bloco `env`, e aponte `AGENTMEMORY_URL` para uma rota que a sandbox consiga efetivamente alcançar (por exemplo, o seu IP de LAN).
+
+### Acesso Programático (Python / Rust / Node)
+
+O agentmemory regista as 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 através de `ws://localhost:49134`, sem necessidade de 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/) (fluxo de arranque rápido + observação/recall). O REST na `:3111` continua disponível para anfitriões sem um 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
+```
+
+Isto inicia o agentmemory com um `iii-engine` local, se o binário fixado já estiver instalado, ou usa o Docker Compose quando selecionado. O REST, os streams e o visualizador fazem bind em `127.0.0.1` por predefinição. O caminho automático do binário para macOS/Linux exige `curl`, um `sh` POSIX e `tar`.
+
+Instale o `iii-engine` manualmente. **O agentmemory atualmente fixa o `iii-engine` na `v0.22.1`**, o mesmo lançamento da sua dependência `iii-sdk`; o worker fala o protocolo de ligação (wire protocol) desse engine, e a 0.20.0 reorganizou a superfície do SDK, por isso os dois avançam juntos nos lançamentos do agentmemory. Substitua com `AGENTMEMORY_III_VERSION=` se executar o seu próprio engine e souber que corresponde.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** 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:** descarregue `iii-x86_64-pc-windows-msvc.zip` de [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) e extraia `iii.exe` para `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Cada arquivo tem um ficheiro `.sha256` correspondente na página de lançamento; quando trocar a plataforma, use o hash desse ficheiro na verificação acima (no Windows: `Get-FileHash`). O instalador automático em `npx @agentmemory/agentmemory` fixa estes hashes e rejeita um arquivo que não corresponda.
+
+Ou use Docker (o `docker-compose.yml` incluído descarrega `iiidev/iii:0.22.1`). Documentação completa: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+O agentmemory funciona no Windows 10/11, mas o pacote Node.js por si só não basta; também precisa do runtime do iii-engine fixado na v0.22.1 como processo em segundo plano. O CLI não extrai automaticamente o ZIP do Windows, por isso os utilizadores do Windows nativo têm de instalar o `iii.exe` manualmente, usar o WSL2 ou optar pelo Docker Desktop.
+
+A ligação automática de MCP no Windows nativo só suporta `agentmemory connect copilot-cli`. Para o Claude Code, o Codex, o Cursor, e qualquer outro agente nativo do Windows, copie o bloco MCP manual de [Outros agentes](#other-agents) para a configuração do Windows desse agente. Executar o `connect` no WSL só é apropriado quando o agente de destino também está instalado nesse mesmo ambiente WSL; não edita a configuração de um agente que corre no anfitrião Windows.
+
+**Opção A: binário pré-compilado para Windows (recomendado)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opção B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opção C: apenas MCP standalone (sem engine).** Se só precisar das ferramentas MCP para o seu agente e não precisar da REST API, do visualizador ou das tarefas cron, ignore completamente o engine:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnóstico para Windows:** se `npx -y @agentmemory/agentmemory@latest` falhar, execute-o novamente com `--verbose` para ver o stderr real do engine. Modos de falha comuns:
+
+| Sintoma | Correção |
+|---|---|
+| `The engine process started but the REST API never responded.` | Confirme que as quatro portas derivadas estão livres, verifique se o `iii.exe` fixado continuou ativo, e depois execute novamente com `--verbose` e inspecione o stderr do engine capturado |
+| `Could not start iii-engine` | Nem o `iii.exe` nem o Docker estão instalados. Veja a Opção A ou B acima |
+| Conflito de porta | `netstat -ano \| findstr :3111` para ver o que está vinculado, depois termine o processo ou use `--port ` |
+| O fallback para Docker é ignorado mesmo com o Docker instalado | Confirme que o Docker Desktop está realmente em execução (ícone na bandeja do sistema) |
+
+> Nota: o **engine** do iii é um binário pré-compilado, não uma cargo crate, por isso não tente fazer `cargo install` dele. (Os **SDKs** do iii são publicados em crates.io, npm e PyPI, mas o agentmemory não precisa deles.) Todos os métodos de instalação do engine suportados estão fixados na v0.22.1: o binário pré-compilado acima, o caminho de auto-instalação do agentmemory para macOS/Linux (exige `curl`, `sh` POSIX e `tar`), e a imagem Docker `iiidev/iii:0.22.1`. Um `install.sh | sh` simples do upstream instala o engine mais recente, que o agentmemory não suporta. Use `npx -y @agentmemory/agentmemory@latest`; no macOS/Linux, este obtém o engine fixado para `~/.agentmemory/bin`.
+
+---
+
+
Deploy
+
+Modelos de um clique para anfitriões geridos. Cada um distribui um
+Dockerfile autocontido que obtém o `@agentmemory/agentmemory` do npm e copia
+o binário do iii engine a partir da imagem oficial `iiidev/iii` no Docker Hub;
+não é necessária nenhuma imagem pré-construída do agentmemory. O armazenamento persistente
+é montado em `/data`; o entrypoint do primeiro arranque substitui a
+configuração do iii incluída no npm (que faz bind em `127.0.0.1`) por uma
+ajustada para implementação, que faz bind em `0.0.0.0` e usa caminhos absolutos em `/data`,
+gera o segredo HMAC, e depois reduz os privilégios de `root` para `node` através do
+`gosu` antes de executar o CLI do agentmemory.
+
+
+
+
+
+
+O botão de implementação de um clique do Render exige um `render.yaml` na raiz do repositório, que mantemos deliberadamente limpa. Use o fluxo Render Blueprint documentado em [`deploy/render/`](.././deploy/render/README.md) para apontar manualmente para o blueprint existente no repositório.
+
+Os detalhes completos de configuração (captura de HMAC, túnel SSH do visualizador, rotação, cópia de segurança,
+custos mínimos) estão em [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): máquina única com
+ `auto_stop_machines = "stop"`; a mais económica em inatividade.
+- [`deploy/railway`](.././deploy/railway/README.md): taxa fixa do plano Hobby,
+ volume no painel.
+- [`deploy/render`](.././deploy/render/README.md): fluxo Blueprint,
+ snapshots automáticos de disco nos planos pagos.
+- [`deploy/coolify`](.././deploy/coolify/README.md): auto-hospedado no seu
+ próprio VPS através do [Coolify](https://coolify.io/self-hosted); a mesma stack
+ Docker Compose, o anfitrião e os dados são seus.
+
+Apenas a porta `3111` é publicada. O visualizador na `3113` continua
+vinculado ao loopback dentro do contentor; o README de cada modelo documenta o
+padrão de túnel SSH para o alcançar.
+
+---
+
+
+
+Todo o agente de codificação esquece tudo quando a sessão termina, e cada nova sessão começa consigo a voltar a explicar a sua stack. O agentmemory corre em segundo plano e remove esse passo.
+
+```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 incorporada do agente
+
+Todo o agente de codificação com IA vem com memória incorporada: o Claude Code tem o `MEMORY.md`, o Cursor tem notepads, o Cline tem memory bank. Estas funcionam como notas autocolantes. O agentmemory é a base de dados pesquisável por trás das notas autocolantes.
+
+| | Incorporado (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Escala | Limite de 200 linhas | Ilimitada |
+| Pesquisa | Carrega tudo para o contexto | BM25 + vetor + grafo (apenas top-K) |
+| Custo em tokens | 22K+ em 240 observações | ~1,900 tokens (92% menos) |
+| Entre agentes | Ficheiros por agente | MCP + REST (qualquer agente) |
+| Coordenação | Nenhuma | Leases, signals, actions, routines |
+| Observabilidade | Ler ficheiros manualmente | Visualizador em tempo real na :3113 |
+
+---
+
+
+
+### Pipeline de Memória
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### Consolidação de Memória em 4 Níveis
+
+Modelada em como os cérebros humanos processam a memória, incluindo a consolidação durante o sono.
+
+| Nível | O que é | Analogia |
+|------|------|---------|
+| **Working** | Observações em bruto do uso de ferramentas | Memória de curto prazo |
+| **Episodic** | Resumos comprimidos de sessões | "O que aconteceu" |
+| **Semantic** | Factos 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). As memórias acedidas frequentemente fortalecem-se. As memórias obsoletas são removidas automaticamente. As contradições são detetadas e resolvidas.
+
+### O Que É Capturado
+
+| Hook | Captura |
+|------|----------|
+| `SessionStart` | Caminho do projeto, ID da sessão |
+| `UserPromptSubmit` | Prompts do utilizador (filtrados por privacidade) |
+| `PreToolUse` | Padrões de acesso a ficheiros + contexto enriquecido |
+| `PostToolUse` | Nome da ferramenta, entrada, saída |
+| `PostToolUseFailure` | Contexto do erro |
+| `PreCompact` | Reinjeta memória antes da compactação |
+| `SubagentStart/Stop` | Ciclo de vida do subagente |
+| `Stop` | Resumo de fim de sessão |
+| `SessionEnd` | Marcador de sessão concluída |
+
+### Principais Capacidades
+
+| Capacidade | Descrição |
+|---|---|
+| **Captura automática** | Todo o uso de ferramentas é registado através de hooks, sem esforço manual |
+| **Pesquisa semântica** | BM25 + vetor + grafo de conhecimento com fusão RRF |
+| **Evolução da memória** | Versionamento, substituição, grafos de relações |
+| **Higiene do recall** | As versões de memória substituídas saem dos índices de pesquisa; a cadeia de versões no KV mantém o histórico completo |
+| **Avisos de quase-duplicados** | Ao guardar, é reportada uma correspondência consultiva `similarTo` quando o novo conteúdo se parece muito com uma memória existente |
+| **Âmbito por agente** | O `agentId` percorre a gravação e o recall em REST, MCP e no índice de pesquisa, em modo partilhado ou isolado |
+| **Proveniência no momento da escrita** | Toda observação e memória transporta um canal de origem imutável (user, agent, tool, import, ou shared) marcado na captura, na gravação e na importação |
+| **Esquecimento automático** | Expiração por TTL, deteção de contradições, remoção por importância |
+| **Privacidade primeiro** | Chaves de API, segredos e tags `` são removidos antes do armazenamento |
+| **Auto-recuperação** | Circuit breaker, cadeia de fallback de fornecedores, monitorização de saúde |
+| **Ponte com o Claude** | Sincronização bidirecional com o MEMORY.md |
+| **Grafo de conhecimento** | Extração de entidades + travessia BFS |
+| **Memória de equipa** | Partilhada e privada, com namespaces, entre os membros da equipa |
+| **Proveniência de citações** | Rastreia qualquer memória até às observações de origem |
+| **Snapshots Git** | Versiona, reverte e compara (diff) o estado da memória |
+
+---
+
+
+
+Recuperação de três fluxos, combinando três sinais:
+
+| Fluxo | O que faz | Quando |
+|---|---|---|
+| **BM25** | Correspondência de palavras-chave com stemming e expansão de sinónimos | Sempre ativo |
+| **Vetor** | Similaridade de cosseno sobre embeddings densos | Fornecedor de embeddings configurado |
+| **Grafo** | Travessia do grafo de conhecimento via correspondência de entidades | Entidades detetadas na query |
+
+Combinados com Reciprocal Rank Fusion (RRF, k=60) e diversificados por sessão (máximo de 3 resultados por sessão).
+
+Quando um índice vetorial está preenchido, o `mem::search` (por trás de `memory_recall`) usa o ranker híbrido BM25 + vetor. Sem embeddings, usa o BM25. O `smart-search` pode ainda combinar correspondências estruturais do grafo quando existem dados de grafo, inclusive em modo sem chave. O recall de lessons corre sobre um índice BM25 dedicado em memória, em vez de percorrer todo o corpus a cada query. As versões de memória substituídas são excluídas de todos os caminhos de recall; a cadeia de versões mantém o seu histórico.
+
+Os vetores sobrevivem a um crash ou a uma paragem forçada. O índice vetorial é guardado em blocos no máximo a cada `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutos). Cada vetor adicionado ou removido entretanto também é escrito imediatamente num pequeno registo pendente no state store, e o arranque seguinte reproduz esse registo sem chamar o fornecedor de embeddings. Cada gravação bem-sucedida esvazia o registo. Os documentos que ainda não têm vetor depois da reprodução são re-embutidos (re-embedded) em segundo plano, em lotes de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), até não restar nenhum, e um preenchimento retroativo (backfill) interrompido continua no arranque seguinte. O `/agentmemory/status` e o visualizador mostram o tamanho do registo pendente e o estado do backfill. As instalações sem chave não escrevem nada.
+
+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 dividir sequências CJK em tokens ao nível da palavra; sem eles, o agentmemory recua suavemente para a tokenização da sequência completa e imprime uma dica única no stderr.
+
+### Fornecedores de Embeddings
+
+As instalações sem chave desativam os embeddings vetoriais: o `mem::search` usa BM25, enquanto o `smart-search` também pode usar dados estruturais de grafo já existentes. Para optar por embeddings semânticos locais e gratuitos, adicione isto a `~/.agentmemory/.env` e reinicie o agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+A instalação normal via npm inclui o runtime opcional `@huggingface/transformers`. O primeiro pedido de embedding faz o download de `Xenova/all-MiniLM-L6-v2`, por isso precisa de acesso à rede e pode demorar mais; a inferência seguinte corre localmente. Os fornecedores remotos são detetados automaticamente a partir das suas chaves, a menos que `EMBEDDING_PROVIDER` os substitua.
+
+| Fornecedor | Modelo | Custo | Notas |
+|---|---|---|---|
+| **Local (opt-in recomendado)** | `all-MiniLM-L6-v2` | Gratuito | No dispositivo após o primeiro download do modelo, +8pp de recall sobre apenas BM25 |
+| Gemini | `gemini-embedding-001` | Nível gratuito | 100+ idiomas, dimensões 768/1536/3072 (MRL), entrada de 2048 tokens. Substitui o `text-embedding-004` ([descontinuado, encerramento a 14 de janeiro de 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Qualidade mais alta |
+| Voyage AI | `voyage-code-3` | Pago | Otimizado para código |
+| Cohere | `embed-english-v3.0` | Teste gratuito | Uso geral |
+| OpenRouter | Qualquer modelo | Varia | Proxy multimodelo |
+
+---
+
+
+
+54 ferramentas, 6 recursos, 3 prompts e 17 skills.
+
+> **Shim MCP vs servidor completo:** o pacote publicado `@agentmemory/mcp` é um shim fino. Expõe a superfície completa de 54 ferramentas **apenas quando consegue alcançar um servidor agentmemory em execução** através de `AGENTMEMORY_URL` (modo proxy). Sem nenhum servidor acessível, o shim recua para um conjunto local de 7 ferramentas (`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 só vir 7 ferramentas no Cursor / OpenCode / Gemini CLI, inicie `npx -y @agentmemory/agentmemory@latest` (ou a stack Docker) e defina `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 Ferramentas
+
+Três superfícies de ferramentas, da mais pequena à maior: `AGENTMEMORY_TOOLS=core` reduz a visibilidade a 8 essenciais (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); o conjunto base abaixo são as 14 ferramentas fundamentais do registo; a predefinição (`AGENTMEMORY_TOOLS=all`) expõe todas as 54.
+
+
+Ferramentas base (14)
+
+| Ferramenta | Descrição |
+|------|-------------|
+| `memory_recall` | Pesquisar observações passadas |
+| `memory_compress_file` | Comprimir ficheiros markdown preservando a estrutura |
+| `memory_save` | Guardar uma perceção, decisão ou padrão |
+| `memory_file_history` | Observações passadas sobre ficheiros específicos |
+| `memory_patterns` | Detetar padrões recorrentes |
+| `memory_sessions` | Listar sessões recentes |
+| `memory_smart_search` | Pesquisa híbrida semântica + palavra-chave |
+| `memory_vision_search` | Pesquisar observações de imagens |
+| `memory_timeline` | Observações cronológicas |
+| `memory_profile` | Perfil do projeto (conceitos, ficheiros, padrões) |
+| `memory_export` | Exportar todos os dados de memória |
+| `memory_relations` | Consultar o grafo de relações |
+| `memory_commit_lookup` | Sessões por trás de um commit git |
+| `memory_commits` | Commits registados para uma sessão |
+
+
+
+
+Ferramentas avançadas (54 no total, a superfície predefinida)
+
+| Ferramenta | Descrição |
+|------|-------------|
+| `memory_patterns` | Detetar padrões recorrentes |
+| `memory_timeline` | Observações cronológicas |
+| `memory_relations` | Consultar o grafo de relações |
+| `memory_graph_query` | Travessia do grafo de conhecimento |
+| `memory_consolidate` | Executar a consolidação em 4 níveis |
+| `memory_claude_bridge_sync` | Sincronizar com o MEMORY.md |
+| `memory_team_share` | Partilhar com membros da equipa |
+| `memory_team_feed` | Itens partilhados recentes |
+| `memory_audit` | Registo de auditoria das operações |
+| `memory_governance_delete` | Eliminar com registo de auditoria |
+| `memory_snapshot_create` | Snapshot versionado em Git |
+| `memory_action_create` | Criar itens de trabalho com dependências |
+| `memory_action_update` | Atualizar o estado de uma action |
+| `memory_frontier` | Actions desbloqueadas, ordenadas por prioridade |
+| `memory_next` | A próxima action mais importante |
+| `memory_lease` | Leases exclusivos de actions (multiagente) |
+| `memory_routine_run` | Instanciar routines de workflow |
+| `memory_signal_send` | Mensagens entre agentes |
+| `memory_signal_read` | Ler mensagens com confirmações de leitura |
+| `memory_checkpoint` | Portões de condição externos |
+| `memory_mesh_sync` | Sincronização P2P entre instâncias |
+| `memory_sentinel_create` | Vigilantes orientados a eventos |
+| `memory_sentinel_trigger` | Disparar sentinels externamente |
+| `memory_sketch_create` | Grafos de actions efémeros |
+| `memory_sketch_promote` | Promover a permanente |
+| `memory_crystallize` | Compactar cadeias de actions |
+| `memory_diagnose` | Verificações de saúde |
+| `memory_heal` | Corrigir automaticamente estados bloqueados |
+| `memory_facet_tag` | Tags dimensão:valor |
+| `memory_facet_query` | Consultar por tags de faceta |
+| `memory_verify` | Rastrear proveniência |
+
+
+
+### 6 Recursos · 3 Prompts · 17 Skills
+
+| Tipo | Nome | Descrição |
+|------|------|-------------|
+| Recurso | `agentmemory://status` | Saúde, contagem de sessões, contagem de memórias |
+| Recurso | `agentmemory://project/{name}/profile` | Inteligência por projeto |
+| Recurso | `agentmemory://project/{name}/recent` | Observações recentes de um projeto |
+| Recurso | `agentmemory://memories/latest` | As últimas 10 memórias ativas |
+| Recurso | `agentmemory://graph/stats` | Estatísticas do grafo de conhecimento |
+| Recurso | `agentmemory://team/{id}/profile` | Perfil de equipa partilhado |
+| Prompt | `recall_context` | Pesquisar e devolver mensagens de contexto |
+| Prompt | `session_handoff` | Dados de handoff entre agentes |
+| Prompt | `detect_patterns` | Analisar padrões recorrentes |
+| Skill | `/recall` | Pesquisar na memória |
+| Skill | `/remember` | Guardar na memória de longo prazo |
+| Skill | `/session-history` | Resumos de sessões recentes |
+| Skill | `/forget` | Eliminar observações/sessões |
+
+A tabela mostra as quatro skills principais. O conjunto completo é de 9 skills invocáveis mais 8 skills de referência; ver a secção de skills nativas acima.
+
+### MCP Standalone
+
+Execute sem o servidor completo, para qualquer cliente MCP. Qualquer uma destas opções funciona:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Ou adicione à configuração MCP do seu agente:
+
+Na maioria dos agentes (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Combine a entrada `agentmemory` com o objeto `mcpServers` já existente do seu anfitrião, em vez de substituir o ficheiro. Para clientes em sandbox que não conseguem alcançar o `localhost` do anfitrião, adicione `"AGENTMEMORY_FORCE_PROXY": "1"` ao bloco env e defina `AGENTMEMORY_URL` para uma rota que a sandbox consiga alcançar.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copie o ficheiro do plugin a partir do repositório:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Inicia-se automaticamente na porta `3113`. O visualizador carrega um snapshot quando se liga (`GET /agentmemory/viewer/snapshot`) e depois aplica eventos de stream em direto: novas memórias, lessons, observações, entradas de auditoria, alterações no grafo e atualizações de saúde aparecem sem polling ou recarregamentos de página. Os únicos outros pedidos são as ações em que clica, as páginas "carregar mais" e as pesquisas. Quando o stream cai, o visualizador mostra há quanto tempo os seus números estão desatualizados, volta a ligar-se com backoff e volta a sincronizar a partir de um snapshot.
+
+- **12 separadores em quatro grupos**, com contagens em direto, deep links (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), atalhos de teclado e um menu para dispositivos móveis.
+- **Memories:** pesquisa do lado do servidor, filtros por projeto, agente e tipo, um painel de detalhe com a cadeia de versões e um diff por palavras, ligações de proveniência, botões para copiar o id, a chamada MCP e um comando curl, edição (uma nova versão), esquecer com confirmação, esquecer em massa e exportação JSON.
+- **Sessions:** uma linha do tempo de observações inline, com entrada e saída de ferramentas legíveis, filtros e paginação, e as memórias e lessons que cada sessão produziu.
+- **Graph:** pesquisa, detalhe de nó com relações e fontes, uma legenda que não depende apenas da cor, e controlos de zoom.
+- **Health:** a versão em direto de `GET /agentmemory/status`. Todos os problemas vêm com a respetiva correção, mais o state backend, o estado de gravação do índice, o progresso da compactação de proveniência do grafo e um explicador de consolidação com os limiares reais.
+- Páginas **Audit, Activity, Profile, Replay, Lessons, Actions e Crystals**, cada uma com um estado vazio que explica o que é a secção, porque está vazia e o comando que a preenche, e uma tooltip de glossário `?` em todos os termos e números.
+
+```bash
+open http://localhost:3113
+```
+
+O servidor do visualizador faz bind em `127.0.0.1` por predefinição e junta o segredo do servidor quando reencaminha pedidos para a REST API, por isso não precisa de nenhuma configuração. O endpoint `/agentmemory/viewer`, servido pelo REST, segue as regras normais de bearer-token e redireciona os browsers sem token para a porta do visualizador. Os cabeçalhos CSP usam um nonce de script por resposta e desativam atributos de handler inline (`script-src-attr 'none'`).
+
+---
+
+
+
+O visualizador na `:3113` mostra o que o seu agente **se lembrou**. A [iii console](https://iii.dev/docs/console) mostra o que o seu agente **fez**: cada operação de memória como um trace OpenTelemetry, cada entrada KV editável, cada função invocável, cada stream acessível. Duas janelas sobre a mesma memória: uma moldada como produto, outra moldada como engine.
+
+Veja um `memory_smart_search` a disparar e observe a varredura BM25 → consulta de embedding → fusão RRF → reranker como uma waterfall. Edite um temporizador de consolidação bloqueado no navegador de KV. Reproduza um hook `PostToolUse` com um payload ajustado. Fixe o stream WebSocket e veja as observações a chegar em direto.
+
+O agentmemory oferece isto de graça, porque cada chamada de função e cada trigger disparam através do iii; nada personalizado, nada para instrumentar.
+
+
+
+
+ Página Workers: cada worker conectado, incluindo o próprio agentmemory, com PID, contagem de funções, runtime e última atividade (last-seen).
+
+
+**Já vem instalada.** A console é distribuída com o engine `iii` fixado (0.22+); não há nada separado para instalar. O primeiro arranque faz o download do binário da console junto ao engine.
+
+**Iniciar junto com o agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Isto executa o `iii console` do engine fixado contra as portas que o agentmemory resolveu (REST, streams, bridge) e serve-a uma porta acima do visualizador, `http://localhost:3114` por predefinição. `--console-port N` escolhe outra porta; `--port` e `--instance` selecionam a instância do agentmemory da mesma forma que fazem para o `stop`; qualquer outra flag é passada adiante, por exemplo `--enable-flow` para a página experimental de grafo de arquitetura.
+
+O mesmo à mão, útil quando o `agentmemory` não está no PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**O que pode fazer a partir da console:**
+
+| Página | Use-a para |
+|------|-----------|
+| **Workers** | Ver cada worker conectado e as suas métricas em direto, incluindo o próprio worker do agentmemory. |
+| **Functions** | Invocar diretamente qualquer função do agentmemory com um payload JSON; útil para testar `memory.recall`, `memory.consolidate`, `graph.query` sem ligar um cliente. |
+| **Triggers** | Reproduzir triggers de HTTP, cron, event e state: disparar manualmente o cron de consolidação, repetir uma rota HTTP, emitir uma alteração de estado. |
+| **States** | Navegador de KV com CRUD completo sobre sessões, slots de memória, temporizadores de ciclo de vida e o índice de embeddings; edite valores no próprio local. |
+| **Streams** | Monitor de WebSocket em direto para escritas de memória, eventos de hook e atualizações de observações, a fluir pelos streams do iii. |
+| **Queues** | Tópicos de fila duráveis + gestão de dead-letter. Reproduza ou descarte jobs falhados de embedding / compressão. |
+| **Traces** | Vistas waterfall / flame / por serviço do OpenTelemetry. Filtre por `trace_id` para ver exatamente que funções, chamadas à BD e pedidos de embedding um único `memory.search` produziu. |
+| **Logs** | Logs OTEL estruturados, filtrados e correlacionados com IDs de trace/span. |
+| **Config** | Configuração de runtime: veja exatamente com que workers, fornecedores e portas o seu engine está a correr. |
+| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitetura interativo de cada worker, trigger e stream. |
+
+
+
+
+ Traces: waterfall / flame / por serviço para cada operação de memória.
+
+
+**Os traces já estão ativos:**
+
+O `iii-config.yaml` já vem com o worker `iii-observability` ativado (`exporter: memory`, `sampling_ratio: 0.1`, métricas + logs). Não precisa de configuração extra; no momento em que o agentmemory inicia, toda a operação de memória emite um log estruturado que a console consegue ler, e uma em cada dez (`sampling_ratio: 0.1`) também emite um span de trace.
+
+Se preferir exportar para Jaeger/Honeycomb/Grafana Tempo, mude `exporter: memory` para `exporter: otlp` e defina o endpoint do collector de acordo com a documentação de observabilidade do iii.
+
+> **Atenção:** a console em si não impõe autenticação; mantenha-a vinculada a `127.0.0.1` (a predefinição) e nunca a exponha publicamente.
+
+---
+
+
+
+O agentmemory **já é uma instância [iii](https://iii.dev) em execução**. Três primitivos (worker, function, trigger) compõem o runtime; o estado KV, os streams e os traces OTEL vêm dos workers iii-state, iii-stream e iii-observability que acompanham o iii. 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 completamente nova.
+
+### Estender o agentmemory com Mais Workers
+
+Os builtins de que o agentmemory precisa já estão em `iii-config.yaml` e arrancam com ele: `iii-state` (KV), `iii-queue` (retries duráveis para os subscritores de eventos), `iii-pubsub`, `iii-cron`, `iii-stream`, e `iii-observability` (traces, métricas e logs OTEL em cada função). Qualquer outra coisa do [registo de workers do iii](https://workers.iii.dev) encaixa-se no mesmo engine: copie `iii-config.yaml` para `~/.agentmemory/iii-config.yaml` (o CLI prefere esse ficheiro em vez do incluído, e continua a renderizar portas e caminhos de dados nele), adicione a entrada, instale o runtime do worker uma vez com `~/.agentmemory/bin/iii update worker`, e reinicie o agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | O que ganha para além do agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Um adaptador de estado baseado em SQL, quando ultrapassar as predefinições de KV em memória |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | O código que saiu do `memory_recall` corre dentro de uma VM descartável, não na sua shell |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Monte servidores MCP adicionais ao lado do do agentmemory, partilhando o mesmo engine |
+
+No engine 0.22.x mantenha os nomes com o prefixo `iii-` para os builtins acima; as entradas sem prefixo `http`, `state`, `queue`, `pubsub` e `cron` são os workers standalone do registo para os quais o agentmemory migra com a atualização para 0.23.
+
+Registo completo: [workers.iii.dev](https://workers.iii.dev). Todos os workers aí compõem-se através dos mesmos primitivos que o agentmemory usa, e o agentmemory que já tem é um deles.
+
+### Configuração do Engine e Endereço de Bind
+
+O `agentmemory start` lê a configuração do engine a partir do primeiro ficheiro que existir: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` no diretório atual, `~/.agentmemory/iii-config.yaml`, e depois o `iii-config.yaml` incluído. A cada arranque, renderiza esse ficheiro (caminhos de dados, portas, state backend) para `~/.agentmemory/data/iii-config.runtime.yaml` e lança o engine com a cópia renderizada, por isso edite o ficheiro de origem, não o renderizado. Os valores `host:` do ficheiro de origem são mantidos tal como foram escritos.
+
+O `iii-config.yaml` incluído faz bind em `127.0.0.1` de propósito, e essa predefinição também se aplica dentro de um contentor. Um CLI iniciado num contentor escuta no loopback do contentor, por isso as portas publicadas não alcançam nada. Para servir um CLI em contentor através de portas publicadas, defina `AGENTMEMORY_III_CONFIG` para uma configuração que faça bind em `0.0.0.0`. O `iii-config.docker.yaml` empacotado é uma delas: faz bind do `iii-http`, do `iii-stream` e da porta do engine em `0.0.0.0` e guarda o estado em `/data`, por isso monte aí um volume com permissão de escrita. Mantenha `AGENTMEMORY_SECRET` definida, e publique apenas as portas de que precisa, em `127.0.0.1` ou por trás de um proxy de confiança.
+
+O `docker-compose.yml` deste repositório não passa pela procura de configuração do CLI: monta `iii-config.docker.yaml` em `/app/config.yaml`, e o contentor `iii-engine` arranca com `--config /app/config.yaml`. Os [modelos de implementação](../deploy/) de um clique escrevem a sua própria configuração `0.0.0.0` nos respetivos entrypoints.
+
+### Backend de Armazenamento: Ficheiro (predefinição) vs Redis
+
+Por predefinição, o `iii-state` e o `iii-stream` usam o armazenamento KV baseado em ficheiro incluído no iii-engine: um ficheiro JSON por âmbito, mantido na memória do processo do engine e reescrito em disco periodicamente. Essa é a predefinição certa para uma instalação local de um só utilizador; um daemon partilhado com vários escritores concorrentes obtém, em vez disso, escritas reais por chave a partir do Redis, ao custo de uma viagem de rede por operação (cada chamada `state::*` continua a serializar numa única ligação Redis, por isso isto troca o lock do armazenamento de ficheiro por um socket, não por paralelismo).
+
+Defina `AGENTMEMORY_STATE_BACKEND=redis` (mais `AGENTMEMORY_REDIS_URL`) para mudar ambos os workers para o adaptador `redis` incluído no iii-engine, que guarda cada chave como um campo de hash Redis (`HSET`) em vez de reescrever um âmbito inteiro a cada escrita:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+O `AGENTMEMORY_STATE_BACKEND` assume `file` por predefinição; deixá-lo sem definir mantém o comportamento atual inalterado, e um valor não reconhecido (qualquer coisa que não seja `file` ou `redis`) é um erro de arranque, em vez de um fallback silencioso. O `/agentmemory/status` e a página Health do visualizador (a linha State store) reportam qual o backend ativo e se responde, nunca o URL.
+
+**Apenas `redis://` simples.** O engine fixado (0.22.1) constrói o seu cliente Redis sem suporte para TLS, por isso um URL `rediss://` (a maioria das ofertas Redis geridas, como Upstash, Redis Cloud, e ElastiCache com encriptação em trânsito, assumem TLS por predefinição) falha a ligação. A ligação não é encriptada, por isso a password do Redis e cada memória guardada atravessam a rede em texto simples: aponte para um Redis local ou um numa rede privada de confiança. Para qualquer outro Redis, corra um túnel encriptado (stunnel, SSH ou uma VPN) no anfitrião do agentmemory, para que o salto `redis://` simples fique nesse anfitrião e a ligação a montante do túnel seja encriptada e autenticada. Se uma password do Redis contiver um apóstrofo, codifique-o em percentagem (`%27`); o engine expande o URL para dentro da sua configuração YAML antes de o analisar.
+
+**Um servidor Redis por `--instance`.** Os prefixos de chave Redis do engine (`state:`, `stream::`) são fixos, por isso duas instâncias do agentmemory (`--instance 1`, `--instance 2`, ...) a apontar para a mesma base de dados sobrescrevem os dados uma da outra. Um índice de base de dados separado (`redis://localhost:6379/1`) mantém os dados guardados separados, mas o engine retransmite os eventos do visualizador em direto através de um único canal Redis pub/sub (`stream::events`), e o pub/sub do Redis ignora o índice de base de dados, por isso o visualizador de cada instância continuaria a mostrar os eventos em direto da outra. Dê a cada instância o seu próprio servidor Redis (ou porta) quando executar mais do que uma.
+
+**O que fica igual, e o que é diferente.** Todas as funcionalidades do agentmemory funcionam sobre Redis: sessões, observações, memórias (remember, supersede, evolve, forget), pesquisa e os blocos do índice, lessons, o grafo, o registo de auditoria e os seus âmbitos mensais, exportação e importação, governance deletes, estado de consolidação, o snapshot do visualizador e o seu stream em direto, e o monitor de saúde. O engine guarda cada âmbito como um único hash Redis (`HSET`/`HGET`/`HGETALL`) e dispara os mesmos state triggers que o armazenamento de ficheiro. Três diferenças do engine são tratadas dentro do agentmemory:
+
+- O Redis devolve os registos de um âmbito sem ordem fixa. O agentmemory ordena-os do mais antigo para o mais recente (pela data de criação no id do registo, depois pelo seu timestamp), para que listas, paginação e blocos de exportação voltem na mesma ordem que no armazenamento de ficheiro.
+- O engine aplica atualizações parciais no Redis através de um script Lua que transforma arrays vazios em objetos vazios. O agentmemory aplica essas atualizações ele próprio (ler, alterar, escrever sob um lock por chave) no Redis, para que campos como `tags: []` permaneçam arrays.
+- A verificação do registo de auditoria legado lê o âmbito antigo a partir do Redis, em vez de procurar o ficheiro do armazenamento de ficheiro em disco.
+
+Uma diferença precisa da sua intervenção: **depois de o Redis reiniciar, o engine deixa de retransmitir eventos em direto** para o visualizador até o agentmemory reiniciar. Os dados continuam a ser guardados e lidos normalmente. O monitor de saúde envia um evento de teste através do Redis a cada 30 segundos; quando este não volta, o `/agentmemory/status` e a página Health do visualizador mostram "Live updates are not reaching the viewer", com a correção: reinicie o agentmemory. Se o Redis estiver em baixo, o relatório de estado mostra "The state store is not answering" e como verificá-lo (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listar um âmbito muito grande lê o hash inteiro num único `HGETALL`, o mesmo custo de o armazenamento de ficheiro o manter em memória.
+
+**Definições Redis recomendadas.** A política de snapshot predefinida `save 3600 1 300 100 60 10000` pode perder minutos de escritas num crash, pior do que a janela de 5s de flush do armazenamento de ficheiro. Defina `appendonly yes` para tudo o que não queira perder. Defina `maxmemory-policy noeviction`; `allkeys-lru` ou semelhante descarta memórias silenciosamente quando o Redis atinge o seu limite de memória.
+
+Um arranque nativo (sem Docker), e todos os [modelos de implementação](../deploy/) de um clique (que sobrescrevem o `iii-config.yaml` incluído e arrancam nativamente), leem `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` e renderizam-nos no `iii-config` lançado. O URL em si nunca é escrito nesse ficheiro renderizado, apenas uma referência `${AGENTMEMORY_REDIS_URL}` que o processo do engine expande a partir do seu próprio ambiente no arranque. Só o caminho de Docker Compose deste repositório (`AGENTMEMORY_USE_DOCKER=1`, ou retomar um engine já iniciado dessa forma) monta `iii-config.docker.yaml` em modo só de leitura e nunca renderiza; o `agentmemory start` avisa quando deteta essa combinação. Troque esse ficheiro à mão, seguindo o mesmo formato `name: redis` / `config: redis_url: ...` mostrado na documentação dos workers [iii-state](https://workers.iii.dev/workers/iii-state) e [iii-stream](https://workers.iii.dev/workers/iii-stream), e aponte `redis_url` para um Redis acessível a partir do contentor. O `docker-compose.yml` passa `AGENTMEMORY_REDIS_URL` para o contentor do engine, por isso `redis_url: '${AGENTMEMORY_REDIS_URL}'` funciona aí e mantém o URL fora do ficheiro montado.
+
+A configuração renderizada mantém o URL fora de `~/.agentmemory/data/iii-config.runtime.yaml`, mas o próprio worker de configuração do engine ainda persiste o valor *expandido* em `~/.agentmemory/config/iii-state.yaml` e `iii-stream.yaml` depois de arrancar (a expansão `${VAR}` do iii-engine acontece antes de esse worker guardar a sua seed, e guarda o valor resolvido, não a referência). Trate esse diretório como contendo uma credencial: `chmod 700 ~/.agentmemory` em qualquer anfitrião partilhado, e prefira um utilizador Redis ACL limitado ao que o agentmemory precisa, em vez das credenciais de administrador da base de dados.
+
+**A migração não é automática.** Mudar `AGENTMEMORY_STATE_BACKEND` parte de um armazenamento vazio em qualquer um dos lados; nada copia os dados existentes de ficheiro para Redis ou vice-versa. Exporte a partir do backend que está a deixar e importe para aquele para o qual está a mudar. Isto corre de forma idêntica em bash e zsh (incluindo `bash -u`). Um array como `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` não corre: o zsh mantém o header como uma única palavra malformada, onde o bash o divide em duas, por isso ambos os pedidos recebem 401 sempre que `AGENTMEMORY_SECRET` está definida:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+O `/agentmemory/export` também aceita `?maxSessions=` e `?offset=` para dividir um corpus grande em várias chamadas; o `strategy` na importação é `merge` (seguro por predefinição), `replace`, ou `skip`.
+
+### O Que o iii Substitui
+
+| Stack tradicional | O agentmemory usa |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + índice vetorial em memória |
+| 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 plugins personalizados | `iii worker add ` |
+
+**225 ficheiros de código-fonte · ~54,000 LOC · 2,600+ testes · 312 funções · 66 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+
+---
+
+
+
+### Fornecedores de LLM
+
+O agentmemory deteta automaticamente fornecedores a partir do seu ambiente. Um fornecedor torna disponíveis as operações suportadas por LLM, mas a configuração do fornecedor por si só não ativa a compressão de observações escrita por LLM. Esse caminho exige tanto um fornecedor como `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Fornecedor | Configuração | Notas |
+|----------|--------|-------|
+| **No-op (predefinição)** | Sem configuração necessária | A compressão/resumo suportados por LLM estão desativados. A compressão sintética e o recall por BM25 continuam a funcionar. Ver `AGENTMEMORY_ALLOW_AGENT_SDK` abaixo, se costumava depender do fallback de subscrição Claude. |
+| API da Anthropic | `ANTHROPIC_API_KEY` | Faturação por token |
+| MiniMax | `MINIMAX_API_KEY` | Compatível com Anthropic |
+| Gemini | `GEMINI_API_KEY` | Também ativa embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Qualquer modelo |
+| API da OpenAI | `OPENAI_API_KEY` | Predefinição `gpt-5.6-luna`, substitua com `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) ou `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Qualquer coisa compatível com a API da OpenAI. Custo zero, corre no seu hardware. Ver [Modelos locais](#local-models-ollama--lm-studio--vllm) abaixo. |
+| Fallback de subscrição Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Apenas opt-in. Cria sessões `@anthropic-ai/claude-agent-sdk`; costumava causar recursão ilimitada no hook Stop, por isso já não é a predefinição. |
+
+### Modelos Locais (Ollama / LM Studio / vLLM)
+
+O agentmemory comunica com qualquer servidor compatível com a API da OpenAI, por isso qualquer coisa que exponha `/v1/chat/completions` funciona sem alterações de código. Sem chaves pagas, sem nuvem, sem limites de taxa; corre inteiramente no seu hardware.
+
+**Ollama** (porta predefinida `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (porta predefinida `1234`):
+
+Abra o LM Studio → separador Local Server → Start Server. Escolha qualquer modelo de chat no seletor (Qwen 3, gpt-oss, DeepSeek R1, etc.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: mesmo formato. Aponte `OPENAI_BASE_URL` para o URL que o seu servidor expõe e defina `OPENAI_MODEL` para um nome que o seu servidor aceite.
+
+**Escolhas de modelo para o trabalho de memória**: a compressão e o resumo são tarefas curtas (<2K tokens de entrada, <500 tokens de saída), onde um modelo instruct de 7B já é mais do que suficiente. Recomendações:
+
+| Modelo | Tamanho | Porquê |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Predefinição equilibrada numa máquina de 16 GB; forte em extração e texto no formato de ferramentas |
+| `qwen3:4b` | ~2.6 GB | A opção mais pequena ainda razoável; serve bem para compressão, mais fraca para extração de grafo |
+| `qwen3-coder:30b` | ~19 GB | A melhor escolha local para sessões no formato de código (30B MoE, 3.3B ativos) em hardware de 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Modelo geral forte que cabe em 16 GB de RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Destilação de raciocínio; mais lento, mas com extrações mais limpas |
+
+Os modelos Qwen 3 raciocinam por predefinição e podem gastar todo o orçamento de tokens em raciocínio antes de qualquer saída. Defina `AGENTMEMORY_LLM_NOTHINK=1` para acrescentar `/no_think` aos prompts de extração de grafo, e aumente o `MAX_TOKENS` (16384 funciona) se as extrações voltarem vazias.
+
+Modelos da classe de raciocínio (estilo `o1`, com blocos ``) podem devolver `content` vazio, com um campo `reasoning` que o seu servidor local pode não expor. Se as extrações voltarem em branco, mude primeiro para um modelo sem raciocínio. A variável de ambiente `OPENAI_REASONING_EFFORT=none` também pode desativar o raciocínio em modelos de pensamento do Ollama Cloud que espelham o esquema de raciocínio da OpenAI.
+
+Os embeddings locais são distribuídos como dependência opcional, mas não estão ativados por predefinição. Defina `EMBEDDING_PROVIDER=local` para optar por `Xenova/all-MiniLM-L6-v2` (384 dimensões). O primeiro pedido de embedding faz o download do modelo; a inferência corre localmente a partir daí. Sem essa definição ou uma chave de embedding remota, os vetores ficam desativados, o `mem::search` usa BM25, e o `smart-search` ainda pode adicionar correspondências de grafo já existentes.
+
+### Seleção de Modelo com Consciência de Custo
+
+Quando a compressão em segundo plano escrita por LLM está ativada, com um fornecedor e `AGENTMEMORY_AUTO_COMPRESS=true`, esta corre em cada observação, por isso a escolha do modelo altera significativamente a despesa mensal. Dados de carga de trabalho capturados: 635 pedidos / 888K tokens / 35 horas de uso ativo, executados contra três modelos OpenRouter aos preços de 2026-05-23.
+
+| Nível | Modelo | Entrada / 1M | Saída / 1M | Custo para as 35h capturadas | Notas |
+|------|-------|------------|-------------|---------------------------|-------|
+| Recomendado | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | O DeepSeek mais recente; a escolha recomendada mais económica para cargas de compressão. |
+| Recomendado | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Qualidade sólida de compressão + resumo, a um custo ~10× mais baixo do que o Sonnet. |
+| Recomendado | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Raciocínio de código forte, se as suas sessões forem fortemente orientadas a código. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Mesmo preço de tabela que a execução medida com o Sonnet 4.6; preço de lançamento de $2/$10 até 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Nível topo de gama; caro para trabalho em segundo plano permanente. |
+| Evitar | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Modelo de classe topo de gama; gasto excessivo para compressão. |
+
+As linhas medidas vêm da execução capturada; as linhas (est.) escalam a mesma mistura de tokens pelo preço de tabela de cada modelo.
+
+O agentmemory imprime um aviso em runtime quando `OPENROUTER_MODEL` corresponde a um padrão de nível premium. Defina `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para silenciar depois de fazer uma escolha informada.
+
+Compromisso entre qualidade e custo para o trabalho de memória: a compressão é uma tarefa de resumo com barreiras de qualidade relativamente flexíveis (é o agente que volta a ler o resumo, não o utilizador). O DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ficam dentro da margem de erro do Sonnet nesta tarefa, custando 10-70× menos. Guarde os modelos de nível premium para queries que você próprio lê diretamente.
+
+Fontes: [Preços da OpenRouter para o Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [Notas de preços da DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Memória Multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Em configurações multiagente onde vários papéis partilham um servidor agentmemory (architect / developer / reviewer / researcher / support-agent), o `AGENT_ID` marca cada escrita com o papel que a fez. O `AGENTMEMORY_AGENT_SCOPE` controla se o recall filtra por essa marca.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Dois modos:
+
+| Modo | Marca escritas | Filtra o recall | Quando usar |
+|------|------------|---------------|-------------|
+| `shared` (predefinição) | sim | não | Contexto entre agentes, com registo de auditoria. O architect consegue ver o que o developer anotou, mas cada linha regista quem o disse. |
+| `isolated` | sim | sim | Separação estrita. O architect nunca vê as observações / memórias / sessões do developer. |
+
+O que é marcado quando `AGENT_ID` está definida: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. O papel flui de `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=` para substituir por pedido, e `?agentId=*` para sair completamente do âmbito do env. O `/memories` também aceita `?includeOrphans=true` para mostrar memórias anteriores ao AGENT_ID, cujo `agentId` está indefinido.
+
+Substituição por chamada, na camada SDK / REST: todo o endpoint que escreve (`/session/start`, `/remember`) aceita um campo `agentId` no corpo do pedido, que vence o env. Útil para runtimes que encaminham muitos papéis através de um único processo de servidor. A ferramenta MCP `memory_save` expõe o mesmo campo `agentId`, o servidor stdio standalone reencaminha tanto `agentId` como `project`, e as memórias guardadas transportam `agentId` para o índice de pesquisa, por isso a pesquisa com âmbito de agente cobre tanto memórias como observações.
+
+Quando `AGENT_ID` não está definida, a memória permanece sem âmbito (comportamento legado, sem marcas, sem filtros).
+
+### Portas
+
+O agentmemory + iii-engine fazem bind em quatro portas por predefinição. Se um reinício falhar com `port in use`, esta tabela diz-lhe que processo procurar.
+
+| Porta | Processo | Finalidade | Substituição por env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker interno de streams (consumido pelo agentmemory + visualizador) | `III_STREAM_PORT` (preferido) ou o legado `III_STREAMS_PORT` |
+| `3113` | agentmemory | Visualizador em tempo real (`http://localhost:3113`) | `III_VIEWER_PORT` ou `AGENTMEMORY_VIEWER_URL` para o URL reportado |
+| `49134` | iii-engine | WebSocket; os workers registam-se aqui, a telemetria OTel flui por aqui | `III_ENGINE_PORT` ou `III_ENGINE_URL` |
+
+`--port ` altera a âncora REST e deriva os streams para `N+1`, o visualizador para `N+2`, e o WebSocket do engine para `N+46023`, apenas onde a porta ou o URL explícitos correspondentes acima não estiverem definidos. Não cria um namespace de ciclo de vida isolado. Use `--instance 1` para um segundo daemon; este usa a âncora 3211, com predefinição `3211/3212/3213/49234`, e recebe um diretório de dados e de ciclo de vida `instance-1` separado. As instâncias 1 a 50 seguem o mesmo padrão.
+
+O engine fixado arranca com `--no-update-check` (sem verificações de atualização ou de avisos de segurança contra o GitHub no arranque) e com a telemetria de uso anónima do iii desativada: o agentmemory define `III_TELEMETRY_ENABLED=false` para o engine que cria, a menos que exporte a variável você mesmo, e o ficheiro compose incluído faz o mesmo.
+
+Limpeza de processos obsoletos, quando as portas continuam vinculadas depois de uma execução que terminou em 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
+```
+
+O `agentmemory stop` recolhe de forma limpa tanto o worker como o pidfile do engine, num encerramento nativo gracioso. Em modo Docker, esvazia o worker nativo, para exatamente o contentor do engine validado, e preserva tanto o contentor como o seu mount `/data` para um reinício sem perdas; o arranque seguinte valida e retoma esse mesmo contentor. A desinstalação apoiada em Docker exige `agentmemory remove --keep-data`: remove os ficheiros partilhados geridos pelo agentmemory, preservando o contentor validado, o seu mount de dados, e o registo de ciclo de vida necessário para os recuperar. A eliminação destrutiva de dados do Docker é deixada intencionalmente ao operador, depois de uma cópia de segurança. O CLI também se recusa a adotar ou sinalizar detentores de portas do Docker ou de VM (backend do Docker, vpnkit, colima) como o engine nativo, a menos que `--force` seja passado. A limpeza manual acima é apenas para o caso pós-crash em que nenhum dos dois pidfiles ficou para trás.
+
+### Ficheiro de Configuração
+
+Coloque a configuração de runtime do agentmemory em `~/.agentmemory/.env`, em vez de exportar variáveis em todas as shells. Se o visualizador mostrar uma dica de configuração como `export ANTHROPIC_API_KEY=...`, copie-a para este ficheiro como `ANTHROPIC_API_KEY=...`, sem o prefixo `export`, e depois reinicie o agentmemory.
+
+As variáveis de ambiente do processo continuam a funcionar e têm precedência sobre os valores no ficheiro.
+
+No Windows, o mesmo ficheiro vive em `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Para testar com uma subscrição Claude Code Pro/Max em vez de uma chave de API, ative-o explicitamente:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+A compressão de observações escrita por LLM exige ambas as linhas: acesso a um fornecedor de LLM (incluindo este fallback explícito de subscrição) e `AGENTMEMORY_AUTO_COMPRESS=true`. Um fornecedor, por si só, deixa o caminho predefinido de compressão sintética em vigor.
+
+A consolidação (nós do grafo, lessons, crystals) está ativada por predefinição sempre que um fornecedor de LLM está configurado. Desative explicitamente com `CONSOLIDATION_ENABLED=false` se quiser operação sem LLM. A extração de grafo é uma flag separada:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### 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://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por predefinição. Os endpoints protegidos exigem `Authorization: Bearer `, e os endpoints de sincronização mesh exigem uma `AGENTMEMORY_SECRET` explicitamente definida em ambos os pares.
+
+**A autenticação está ativa por predefinição.** Quando `AGENTMEMORY_SECRET` não está definida (na shell ou em `~/.agentmemory/.env`), o servidor gera um segredo aleatório no primeiro arranque e guarda-o em `~/.agentmemory/secret` com o modo `0600`. Todo o cliente incluído lê-o a partir daí quando fala com um servidor local: o CLI, o visualizador, os hooks em `plugin/scripts`, o servidor MCP e o shim `@agentmemory/mcp`, as configurações escritas por `agentmemory connect`, e as integrações incluídas do OpenCode, Pi, OpenClaw, Hermes e do filesystem-watcher. O segredo guardado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Uma `AGENTMEMORY_SECRET` explícita vence sempre, e os clientes remotos continuam a precisar de a ter definida. O Docker e os entrypoints de `deploy/` já geram e exportam o seu próprio segredo. Para chamar a API manualmente:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Regras de pedidos para escritas.** Os pedidos `POST`, `PUT`, `PATCH` e `DELETE` para a REST API e o visualizador têm de enviar `Content-Type: application/json` (um parâmetro `charset` é aceitável) sempre que transportem um corpo, e um cabeçalho `Origin`, quando presente, tem de ser uma origem de loopback para a porta REST ou do visualizador configurada, ou estar listado em `VIEWER_ALLOWED_ORIGINS` (separado por vírgulas, por exemplo `https://memory.example.com`). Os clientes que não enviam nenhum cabeçalho `Origin` (CLI, hooks, MCP, curl, servidor-a-servidor) não são afetados. O visualizador também aceita a sua própria origem.
+
+**Caminhos de ficheiros.** Os endpoints que leem ou escrevem ficheiros (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) só aceitam caminhos dentro de `~/.agentmemory`, do diretório de dados da instância, ou de um diretório listado em `AGENTMEMORY_IMPORT_ROOT` (separe vários com `:`, ou `;` no Windows). O `/replay/import-jsonl` também aceita o seu predefinido `~/.claude/projects`. O `/obsidian/export` mantém-se dentro de `AGENTMEMORY_EXPORT_ROOT` e o `/migrate` dentro de `~/.agentmemory`. Os symlinks são resolvidos antes de cada verificação.
+
+**Remoção de segredos.** As chaves de API, os bearer tokens, os blocos de chave privada PEM e as credenciais incorporadas em URLs (`scheme://user:password@host`) são ocultados antes de o texto ser guardado, em todos os caminhos de escrita: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, saída de compressão e de resumo, crystals e nós do grafo.
+
+
+Endpoints principais
+
+| Método | Caminho | Descrição |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Verificação de saúde (sempre pública) |
+| `GET` | `/agentmemory/status` | O que está errado e como corrigir (HTML para browsers, JSON de resto) |
+| `GET` | `/agentmemory/viewer/snapshot` | Tudo o que o visualizador mostra, numa única resposta |
+| `POST` | `/agentmemory/session/start` | Iniciar sessão + obter contexto |
+| `POST` | `/agentmemory/session/end` | Terminar sessão |
+| `POST` | `/agentmemory/observe` | Capturar observação (ver a entrega de captura abaixo) |
+| `GET` | `/agentmemory/capture` | Caixa de entrada de captura, dead letters e spool offline |
+| `POST` | `/agentmemory/capture/retry` | Repetir capturas em dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Enviar agora o spool offline local |
+| `POST` | `/agentmemory/smart-search` | Pesquisa híbrida |
+| `POST` | `/agentmemory/context` | Gerar contexto |
+| `POST` | `/agentmemory/remember` | Guardar na memória de longo prazo |
+| `POST` | `/agentmemory/forget` | Eliminar observações |
+| `POST` | `/agentmemory/enrich` | Contexto de ficheiro + memórias + bugs |
+| `GET` | `/agentmemory/profile` | Perfil do projeto |
+| `GET` | `/agentmemory/export` | Exportar todos os dados |
+| `POST` | `/agentmemory/import` | Importar a partir de JSON |
+| `POST` | `/agentmemory/graph/query` | Consulta ao grafo de conhecimento |
+| `POST` | `/agentmemory/graph/compact` | Reduzir a proveniência de grafo sobredimensionada |
+| `POST` | `/agentmemory/team/share` | Partilhar com a equipa |
+| `GET` | `/agentmemory/audit` | Registo de auditoria |
+
+Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Entrega de captura.** Os hooks enviam cada observação uma vez para `POST /agentmemory/observe`, com um `eventId`. Este é o próprio id do anfitrião para a chamada, quando o payload tem um (por exemplo, o `tool_use_id` do Claude Code), caso contrário é um hash da sessão, do tipo de hook, do nome da ferramenta, da entrada, da saída e do timestamp do anfitrião. O servidor escreve o evento numa caixa de entrada de captura no state store, guarda a observação, e depois remove a entrada da caixa de entrada. O código de estado diz o que aconteceu:
+
+| Estado | Campo `status` | Significado |
+|---|---|---|
+| `201` | `accepted` | Guardado. `observationId` é a nova observação. |
+| `202` | `accepted` (`state: "retrying"`) | Aceite, mas a gravação falhou. O servidor volta a tentar, também depois de um reinício. |
+| `200` | `duplicate` | Este `eventId` já tinha sido aceite. `observationId` é a observação existente; nada de novo é guardado. |
+| `400` / `422` | `rejected` | Payload inválido, ou a gravação falhou definitivamente (o evento fica guardado como dead letter). |
+| `503` | `rejected` (`retryable: true`) | A caixa de entrada está cheia (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Os hooks colocam o evento em spool e enviam-no mais tarde. |
+
+Os eventos falhados são repetidos a cada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s), com backoff que duplica, até `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Os eventos que continuam a falhar ficam na caixa de entrada como dead letters, são listados em `/agentmemory/status` e na página Health do visualizador, e podem ser repetidos com `POST /agentmemory/capture/retry` (`{"eventId": "..."}` ou `{"all": true}`). Os ids de eventos aceites são lembrados durante `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 horas, no máximo `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids), por isso um hook reproduzido depois de um timeout ou de um reinício é guardado uma vez, enquanto duas chamadas de ferramenta separadas, com os seus próprios ids de anfitrião, são guardadas duas vezes, mesmo quando o seu conteúdo é idêntico. Quando uma observação é eliminada (forget, eliminação de sessão, remoção, esquecimento automático ou uma importação que substitui o armazenamento), o seu evento é marcado como eliminado antes de a observação ser removida, por isso uma reprodução desse evento dentro da mesma janela é respondida como duplicada e não guarda nada. O state store escreve em disco a cada 2 segundos, por isso um evento respondido ainda pode estar apenas em memória por um momento. Para cobrir isso, toda resposta `2xx` também transporta o `bootId` do servidor (novo a cada arranque), `acceptedAt` e `durableAfterMs` (o intervalo de gravação mais 1.5 s no armazenamento de ficheiro, 1.5 s no redis, onde a persistência é uma definição do operador). Os hooks mantêm o evento no spool local até essa janela ter passado, e eliminam-no numa chamada posterior, sem outro pedido. Se o `bootId` tiver mudado nessa altura, o servidor reiniciou, por isso o hook envia o evento novamente com o mesmo `eventId`; um evento que já tinha chegado ao disco não é guardado duas vezes. O servidor também envia esses eventos a si próprio no arranque e em cada intervalo de repetição, por isso um reinício não perde nada, mesmo quando nenhum hook corre depois. Os hooks mais antigos ignoram os campos extra, e hooks novos contra um servidor mais antigo descartam o evento no `2xx`, como antes.
+
+Quando o servidor está em baixo, não responde a tempo ou devolve um 5xx, o hook acrescenta a observação a um ficheiro de spool local, `/capture-spool/-.jsonl` (substitua a pasta com `AGENTMEMORY_CAPTURE_SPOOL_DIR`). O ficheiro é privado ao seu utilizador (modo 600), os segredos são ocultados da mesma forma que o servidor os oculta, aguenta no máximo `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) e descarta entradas mais antigas do que `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Quando está cheio, as novas entradas são descartadas e contadas, e o `/agentmemory/status` reporta isso. O hook continua a terminar com 0 dentro do seu limite de tempo e não acrescenta nenhum pedido quando o servidor está saudável. O spool é enviado no arranque seguinte e pelo primeiro hook que voltar a alcançar o servidor, num processo em segundo plano, para que o agente não espere. Os ids de evento tornam isto seguro: uma observação que já tinha chegado antes de um timeout não é guardada duas vezes. O `npx @agentmemory/agentmemory capture` mostra o spool e a caixa de entrada do servidor, `--drain` envia o spool imediatamente, e `GET /agentmemory/capture` devolve o mesmo em JSON. Defina `AGENTMEMORY_CAPTURE_SPOOL=false` para desligar o spool.
+
+**Compactação da proveniência do grafo.** Cada nó e aresta do grafo de conhecimento mantém os ids das 32 observações mais recentes de onde veio. Armazenamentos escritos antes desse limite podem ter milhares de ids por nó quente, o que torna a pesquisa no grafo e o visualizador lentos, ou derruba o worker. O agentmemory corrige isto por si só: no primeiro arranque depois de uma atualização, reduz cada nó, aresta, aresta substituída (o histórico temporal do grafo) e o snapshot em cache até ao limite, em segundo plano, em pequenas fatias com uma pausa entre elas, para que a pesquisa, a captura e o visualizador continuem a funcionar. Guarda o seu progresso, retoma depois de um reinício e nunca volta a correr depois de terminar. O `/agentmemory/status` e a página Health do visualizador mostram-no como pendente, em execução (com o âmbito e a posição atuais), concluído ou falhado. Defina `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` para o desligar.
+
+Para o executar à mão, chame `POST /agentmemory/graph/compact`. Percorre os índices de nome e de chave de aresta, em vez de listar cada nó e aresta, e é seguro voltar a executar. Quando reduz ids, escreve uma entrada de auditoria `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Num armazenamento grande, ou quando a chamada devolve 504, execute-o em fatias. Envie `scope` (`nodes`, `edges` ou `history`), `offset` e `limit`, e depois chame novamente com o `nextOffset` devolvido, até este ser `null`. Faça isto para `nodes`, `edges` e `history`, e termine com uma chamada `{"scope":"snapshot"}`, porque uma execução em fatias não toca no snapshot em cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Pré-requisitos:** Node.js >= 20 com npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 ou Docker. A instalação automática do engine no macOS/Linux também exige `curl`, um `sh` POSIX e `tar`; o Windows nativo usa o `iii.exe` fixado manualmente, o WSL2, ou o Docker Desktop.
+
+
+
+ Agentul tău de programare își amintește totul. Nu mai trebuie să re-explici.
+ Construit pe iii engine
+
+ Memorie persistentă pentru Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode și orice client MCP.
+
+ Gist-ul extinde modelul LLM Wiki al lui Karpathy cu scorarea încrederii, ciclu de viață, grafuri de cunoștințe și căutare hibridă: agentmemory este implementarea.
+
+
+---
+
+## Instalare
+
+Cerințe:
+
+- Node.js 20 sau mai nou, cu npm și npx (`node -v`, `npm -v` și `npx -v`).
+- Instalarea automată a iii-engine pe macOS/Linux necesită, de asemenea, `curl`, un `sh` POSIX și `tar`. Imaginile minimale precum `node:20-slim` pot să nu le includă.
+- Windows nativ necesită instalarea manuală a `iii.exe` din iii-engine v0.22.1 (versiunea fixată). WSL2 sau Docker Desktop sunt celelalte căi suportate.
+
+Comanda canonică pentru o instalare nouă:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Prima rulare este o configurare interactivă: alegi agenții pe care vrei să-i conectezi (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), alegi un furnizor LLM sau rămâi fără cheie (keyless), apoi se inițializează configurația, se pornesc serverul de memorie și motorul iii fixat (pinned), și se oferă instalarea globală, astfel încât comanda simplă `agentmemory` să funcționeze oriunde, de atunci înainte. `-y` acceptă promptul de pachet al lui npx, iar `@latest` evită o versiune veche din cache. Un furnizor face disponibile funcționalitățile LLM, dar compresia observațiilor scrisă de LLM pornește doar când este setat și `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Modul keyless (fără cheie) dezactivează embedding-urile vectoriale. `memory_recall` (ruta `mem::search`) folosește BM25, în timp ce `memory_smart_search` poate combina și rezultate structurale din graf atunci când datele de graf există deja. Pentru reamintire semantică gratuită, pe dispozitiv, setează `EMBEDDING_PROVIDER=local` în `~/.agentmemory/.env` și repornește. Prima cerere de embedding descarcă `Xenova/all-MiniLM-L6-v2`; după această descărcare inițială a modelului, inferența rulează local.
+
+Runtime-ul local folosește patru porturi: `3111` pentru REST/MCP HTTP, `3112` pentru stream-urile iii, `3113` pentru vizualizator și `49134` pentru WebSocket-ul worker-ului iii. Starea persistentă iii este păstrată în `~/Library/Application Support/agentmemory` pe macOS, `$XDG_DATA_HOME/agentmemory` sau `~/.local/share/agentmemory` pe Linux și `%APPDATA%\agentmemory` pe Windows. Folosește `--data-dir ` sau `AGENTMEMORY_DATA_DIR` pentru a o suprascrie și reutilizează aceeași valoare la fiecare repornire. Pentru compatibilitate retroactivă, un `./data/state_store.db` sau `./data/iii-config.yaml` existent are prioritate față de valoarea implicită a platformei pentru instanța 0; o setare explicită prin flag sau variabilă de mediu are însă întotdeauna prioritate.
+
+Apoi demonstrează că reamintirea funcționează și oferă-i agentului tău skill-urile sale:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Căutările pe cuvinte cheie ar trebui să găsească rezultate în modul implicit keyless, prin BM25. Interogarea `database performance optimization` din demo este intenționat semantică și poate returna zero rezultate până când este configurat un furnizor de embedding.
+
+Preferi să lași un agent de programare să facă totul? Dă-i o singură instrucțiune:
+
+> Preia și urmează instrucțiunile de la: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Conectează oricând mai mulți agenți cu `agentmemory connect ` — 20 de adaptoare listate la [Funcționează cu orice agent](#works-with-every-agent). Referința completă a comenzilor este la [Început rapid](#quick-start).
+
+
+Windows
+
+Calea rapidă este WSL2. Configurarea motorului pe Windows nativ necesită descărcarea arhivei ZIP v0.22.1 fixate și extragerea manuală a `iii.exe`; CLI-ul nu o extrage automat. Docker Desktop este, de asemenea, suportat. Vezi [notele pentru Windows](#windows) pentru pașii detaliați.
+
+
+
+
+Instalare globală / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Comanda npx de mai sus rămâne calea canonică pentru o instalare nouă și evită problemele de permisiuni legate de prefixul global.
+
+
+
+
+npx servește o versiune veche
+
+npx face cache pe versiune. Forțează cea mai recentă versiune cu `npx -y @agentmemory/agentmemory@latest`, sau șterge cache-ul o singură dată cu `rm -rf ~/.npm/_npx` (macOS/Linux; pe Windows șterge `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Rulezi deja propriul tău motor iii
+
+agentmemory fixează versiunea iii-engine la `v0.22.1` și nu se va conecta la o versiune diferită (worker-ul nu poate vorbi protocolul altui motor). Oprește celălalt motor, apoi rulează `npx -y @agentmemory/agentmemory@latest`. Acesta instalează și rulează versiunea fixată v0.22.1 în `~/.agentmemory/bin`, lăsând neschimbat propriul tău `iii`.
+
+
+
+---
+
+
+
+agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST API. Toți agenții partajează același server de memorie.
+
+
+
+GitHub Copilot CLI
+MCP + hook-uri/skill-uri de plugin
+
+
+
+Cursor
+plugin nativ + 7 hook-uri + MCP
+
+
+
+OpenCode
+plugin de captură + MCP
+
+
+
+
+
+Devin
+6 hook-uri + skill-uri + MCP
+
+
+
+OpenClaw
+plugin nativ + MCP
+
+
+
+Hermes
+plugin nativ + MCP
+
+
+
+pi
+plugin nativ + MCP
+
+
+
+OpenHuman
+backend nativ prin trait-ul Memory
+
+
+
+
+
+Gemini CLI
+server MCP
+
+
+
+Antigravity
+MCP + hook-uri
+
+
+
+Claude Desktop
+server MCP
+
+
+
+Warp
+connect + MCP + skill-uri
+
+
+
+Zed
+server MCP
+
+
+
+
+
+Cline
+server MCP
+
+
+
+Continue
+server MCP
+
+
+
+Droid
+server MCP
+
+
+
+Kiro
+server MCP
+
+
+
+Qwen Code
+server MCP
+
+
+
+
+
+DeepSeek Harness
+server MCP
+
+
+
+Roo Code
+server MCP
+
+
+
+Kilo Code
+server MCP
+
+
+
+Goose
+server MCP
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Funcționează cu orice agent care vorbește MCP sau HTTP. Un singur server, memorii partajate între toți.
+
+
+---
+
+Explici aceeași arhitectură la fiecare sesiune. Redescoperi aceleași bug-uri. Reînveți agentul cu aceleași preferințe. Memoria încorporată (CLAUDE.md, .cursorrules) se plafonează la 200 de linii și devine rapid depășită. agentmemory rezolvă asta. Captează discret tot ce face agentul tău, comprimă totul într-o memorie căutabilă și injectează contextul potrivit la începutul următoarei sesiuni. O singură comandă. Funcționează cu toți agenții.
+
+**Ce se schimbă:** În sesiunea 1 configurezi autentificarea JWT. În sesiunea 2 ceri limitare de rată (rate limiting). Agentul știe deja că autentificarea ta folosește middleware-ul jose din `src/middleware/auth.ts`, că testele tale verifică validarea token-urilor și că ai ales jose în locul lui jsonwebtoken pentru compatibilitate cu Edge — fără nicio re-explicare și fără copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Implicit, agentmemory salvează starea iii-engine în afara repository-ului din care este pornit: `~/Library/Application Support/agentmemory` pe macOS, `$XDG_DATA_HOME/agentmemory` sau `~/.local/share/agentmemory` pe Linux și `%APPDATA%\agentmemory` pe Windows. Un `./data/state_store.db` sau `./data/iii-config.yaml` vechi (legacy), dacă există, este reutilizat pentru instanța 0, înaintea valorii implicite a platformei. Pentru a alege explicit o locație, folosește `--data-dir ` sau setează `AGENTMEMORY_DATA_DIR`; orice setare explicită are prioritate față de detectarea automată a fișierelor legacy:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Pornirile native și cele prin Docker folosesc același director rezolvat pe host; Docker îl montează (bind-mount) la `/data`. `--instance 1` adaugă `instance-1` la directorul rezolvat și selectează cvartetul separat de porturi implicite `3211/3212/3213/49234`.
+
+Notele celei mai recente versiuni: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Acuratețea regăsirii
+
+**coding-agent-life-v1** (corpus intern, reproductibil în sandbox)
+
+| Adaptor | P@5 | R@5 | Rata de succes Top-5 | Latență p50 |
+|---|---|---|---|---|
+| **agentmemory hibrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep (referință) | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+Rată de succes Top-5 de 100% la **plafonul matematic P@5** pentru acest corpus (0.240, vezi scorecard-ul). Modul hibrid regăsește fiecare sesiune de referință (gold); grep ratează 1 din 2 sesiuni de referință la interogarea temporală pe mai multe sesiuni. Avantajul este pe **recall + temporal**, nu pe precizia agregată. Acest benchmark este mic și are puține exemple de referință; LongMemEval-S, mai amplu, de mai jos diferențiază mai bine. Detalierea completă pe tipuri + nota de corecție: [`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 de întrebări)
+
+| Sistem | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Doar BM25 (fallback) | 86.2% | 94.6% | 71.5% |
+
+
+
+> Model de embedding: `all-MiniLM-L6-v2` (local, gratuit, fără cheie API). Rapoarte complete: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Comparație cu competitorii: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md), care acoperă agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Reproduce local:** [`eval/README.md`](../eval/README.md), un harness cu adaptoare interschimbabile pentru LongMemEval `_s` (500 de întrebări publice) + `coding-agent-life-v1` (corpus intern de 15 sesiuni). Adaptoarele grep / vector / agentmemory sunt scorate în paralel, cu output NDJSON; scorecard-urile publicate ajung în [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Se combină bine cu [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) și [Graphify](https://github.com/safishamsi/graphify).** Indexare code-graph, pipeline-uri de build multi-agent și grafuri de cunoștințe mai ample pe documente / PDF-uri / imagini / videoclipuri. agentmemory reține munca; aceste trei proiecte iluminează restul stratului de context. Rețete + tabel de direcționare a întrebărilor: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Încorporat (CLAUDE.md)
+
+
+
Tip
+
Motor de memorie + server MCP
+
API strat de memorie
+
Runtime complet de agent
+
AI personal
+
API de memorie + aplicație
+
Hub de memorie de echipă (proxy LLM)
+
Memorie vectorială (OSS)
+
Motor de memorie (Oracle DB)
+
Sistem de memorie
+
Fișier static
+
+
+
Regăsire R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Auto-raportat
+
PersonaMem 76% (auto-raportat)
+
~96.6% (auto-raportat)
+
94.4% (auto-raportat)
+
N/A
+
N/A (grep)
+
+
+
Captare automată
+
12 hook-uri (fără efort manual)
+
Apeluri manuale add()
+
Auto-editare de către agent
+
Manual
+
Extracție pe partea de API
+
Interceptare prin proxy (schimbare base-URL)
+
Manual
+
Extracție API
+
Manual
+
Editare manuală
+
+
+
Căutare
+
BM25 + Vector + Graf (fuziune RRF)
+
Vector + Graf
+
Vector (arhivă)
+
Semantică
+
Vector + RAG
+
4 tipuri de active (Chat / Skill / Wiki / CodeGraph)
+
Doar vector
+
Vector + semantică
+
Ponderată prin declin (decay)
+
Încarcă totul în context
+
+
+
Multi-agent
+
MCP + REST + lease-uri + semnale
+
API (fără coordonare)
+
Doar în interiorul runtime-ului Letta
+
Nu
+
Nu
+
Roluri de echipă + active partajate
+
Nu
+
Doar cu scope limitat
+
Partajat multi-agent
+
Fișiere per agent
+
+
+
Dependență de framework
+
Niciuna (orice client MCP)
+
Niciuna
+
Ridicată (trebuie folosit Letta)
+
Independent (standalone)
+
Niciuna
+
Proxy-ul intermediază fiecare apel de model
+
Niciuna
+
Oracle Database
+
Niciuna
+
Format per agent
+
+
+
Dependențe externe
+
Niciuna (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + bază de date vectorială
+
Multiple
+
Cloud administrat
+
Stivă Docker (Core + Hub + Proxy)
+
Magazin vectorial
+
Oracle AI Database
+
Niciuna
+
Niciuna
+
+
+
Ciclul de viață al memoriei
+
Consolidare pe 4 niveluri + declin + uitare automată
+
Extracție pasivă
+
Gestionat de agent
+
Manual
+
Uitare automată
+
Revizuire manuală; direcționare automată în lucru
+
Niciuna
+
Nespecificat
+
Declin + consolidare
+
Curățare manuală
+
+
+
Eficiența tokenilor
+
~1,900 tokeni/sesiune ($10/an)
+
Variază în funcție de integrare
+
Memorie de bază (core) în context
+
Variază
+
Preț cloud
+
Nespecificat
+
Fără buget de tokeni
+
Susținut de LLM (variază)
+
Variază
+
22K+ tokeni la 240 observații
+
+
+
Vizualizator în timp real
+
Da (port 3113)
+
Dashboard cloud
+
Dashboard cloud
+
Interfață web
+
Dashboard cloud
+
Interfață web Hub
+
Nu
+
Nu
+
Nu
+
Nu
+
+
+
Auto-hostat
+
Da (implicit)
+
Opțional
+
Opțional
+
Da
+
Nu (doar cloud)
+
Da (Docker)
+
Da
+
Da (Oracle DB)
+
Da
+
Da
+
+
+
+Notă despre benchmark: doar R@5 pentru agentmemory este un rezultat măsurat de noi înșine (LongMemEval-S, reproductibil din benchmark/COMPARISON.md). Cifrele pentru mem0 și Letta sunt numerele lor publicate pe LoCoMo (un set de date diferit); cifrele pentru MemPalace, supermemory, TencentDB (PersonaMem) și oracleagentmemory sunt afirmații auto-raportate de furnizori, pe care nu le-am reprodus independent (rularea oracleagentmemory a folosit GPT-5.5 împotriva unei Oracle AI Database). Prezentate una lângă alta doar orientativ, nu ca o comparație directă pe date identice. Numărul de stele este aproximativ și variază în timp.
+
+**Jucători mai noi** merită cunoscuți, comparați în detaliu în [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Sistem | ⭐ | Unghi |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Graf de cunoștințe temporal; cele mai bune rezultate publicate pentru interogări temporale (LongMemEval 63.8%), dar graful se construiește asincron, așa că faptele noi pot întârzia |
+| Cognee | 30K | Ingestie document-în-graf-de-cunoștințe, doar Python, construit pentru extracție structurată de entități, nu pentru captarea sesiunilor |
+
+Niciunul dintre acestea nu captează automat din hook-urile agenților de programare, nu oferă un vizualizator local-first și nu rulează în mod keyless — combinația pe care este construit agentmemory.
+
+---
+
+
+
+Compatibilitate: această versiune are ca țintă `iii-sdk` 0.22.1 și fixează iii-engine la v0.22.1.
+
+### Încearcă-l în 30 de secunde
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` inițializează 3 sesiuni realiste (autentificare JWT, corectarea unei interogări N+1, limitare de rată) și rulează căutări pe acestea. Instalările keyless dezactivează vectorii, astfel încât interogările pe cuvinte cheie `mem::search` ar trebui să găsească rezultate prin BM25, în timp ce `database performance optimization` poate returna zero. `smart-search` poate returna, în plus, rezultate structurale din graf, atunci când există date de graf. Pentru ca interogarea semantică să găsească corectarea N+1 prin vectori, setează `EMBEDDING_PROVIDER=local`, repornește și lasă prima descărcare a modelului să se finalizeze.
+
+Deschide `http://localhost:3113` pentru a urmări memoria construindu-se în timp real.
+
+### Validează o instalare nouă și persistența la repornire
+
+Cu serverul pornit, validează REST, health, vizualizatorul și starea runtime-ului susținut de iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Panelul de pregătire de la pornire ține cont de toate cele patru porturi: REST/MCP HTTP pe 3111, stream-urile iii pe 3112, vizualizatorul pe 3113 și WebSocket-ul worker-ului iii pe 49134. `status` confirmă starea de sănătate (health) a agentmemory și furnizorul activ / modul de embedding. Salvează o probă și confirmă că este căutabilă:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Apoi rulează `npx -y @agentmemory/agentmemory@latest stop`, pornește din nou comanda canonică în Terminalul 1, așteaptă `/agentmemory/livez` și repetă căutarea. Proba trebuie să fie returnată tot. Dacă ai ales un `--data-dir` personalizat, transmite același director și la repornire.
+
+### Comenzi zilnice
+
+Instalarea și configurarea se află în [Instalare](#install) mai sus (prima rulare te ghidează prin ea). De zi cu zi:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Reluarea sesiunii (Session Replay)
+
+Fiecare sesiune înregistrată de agentmemory poate fi reluată. Deschide vizualizatorul, alege tab-ul **Replay** și derulează pe linia temporală: prompturile, apelurile de instrumente, rezultatele acestora și răspunsurile sunt redate ca evenimente discrete, cu play/pause, control al vitezei (0.5x–4x) și scurtături de tastatură (spațiu pentru comutare, săgeți pentru a avansa pas cu pas).
+
+Pentru a prelua transcrieri JSONL mai vechi din Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Sesiunile importate apar în selectorul Replay alături de cele native. Sub capotă, fiecare înregistrare trece prin funcțiile iii `mem::replay::load`, `mem::replay::sessions` și `mem::replay::import-jsonl`, fără servere pe canale secundare. Fiecare transcriere importată este indexată pentru căutare, marcată cu canalul de origine `import` și minată pentru un cristal de sesiune (session crystal) și lecții.
+
+> **Atenție dacă te bazezi pe `import-jsonl` ca metodă principală de captare:** `cleanupPeriodDays` din Claude Code (în `~/.claude/settings.json`, implicit **30**) șterge automat transcrierile JSONL mai vechi decât această fereastră din `~/.claude/projects/`. Dacă instalezi agentmemory de la zero peste un istoric Claude Code de luni de zile, orice e mai vechi de 30 de zile a dispărut deja înainte de primul import. Fie rulează `import-jsonl` printr-un cron, fie crește `cleanupPeriodDays` la o valoare mai mare, fie conectează hook-urile de captare automată (calea implicită de instalare a plugin-ului), astfel încât fiecare tură să ajungă în agentmemory cât timp sesiunea este activă, iar curățarea JSONL nu mai contează.
+
+### Actualizare / Întreținere
+
+Folosește comanda de întreținere atunci când vrei, în mod intenționat, să actualizezi runtime-ul local:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Atenție: această comandă modifică workspace-ul/runtime-ul curent. Poate actualiza dependențele JavaScript și poate descărca imaginea Docker fixată `iiidev/iii:0.22.1`. Nu instalează niciodată un motor iii nefixat sau mai nou.
+
+Detaliile de implementare se află în `src/cli.ts` (vezi `runUpgrade`, în jurul zonei `src/cli.ts:544-595`).
+
+### Claude Code (un singur bloc, lipește-l)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code fără instalarea plugin-ului (cale MCP independentă)
+
+Dacă conectezi serverul MCP al agentmemory direct prin `~/.claude.json`, în loc să folosești `/plugin install`, Claude Code nu rezolvă niciodată `${CLAUDE_PLUGIN_ROOT}` și trebuie să indici scripturile de hook prin căi absolute în `~/.claude/settings.json`. Aceste căi includ de obicei versiunea agentmemory (de ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), astfel încât următoarea actualizare rupe silențios fiecare hook.
+
+Soluție alternativă:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Aceasta îmbină aceleași comenzi de hook în `~/.claude/settings.json`, cu căi absolute rezolvate către directorul `plugin/` inclus în pachetul `@agentmemory/agentmemory` instalat curent. Rulează din nou comanda după actualizarea agentmemory, pentru a reîmprospăta căile. Intrările proprii ale utilizatorului din același fișier sunt păstrate; sunt înlocuite doar intrările anterioare ale agentmemory. Folosirea căii `/plugin install` rămâne abordarea recomandată.
+Pentru deployment-uri la distanță sau protejate, pornește Claude Code cu `AGENTMEMORY_URL` și `AGENTMEMORY_SECRET` setate. Plugin-ul transmite ambele valori către serverul MCP inclus; când `AGENTMEMORY_URL` este gol, shim-ul MCP folosește `http://localhost:3111`.
+
+### Codex CLI (platforma de plugin-uri Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Plugin-ul Codex este livrat din același director `plugin/` ca plugin-ul Claude Code. Acesta înregistrează:
+
+- Un bridge MCP stdio inclus către daemonul în execuție, fără descărcare prin npm sau store de fallback. Vezi [ghidul local pentru Codex](../docs/plugins/codex-local.md) pentru a testa un build nepublicat.
+- 6 hook-uri de ciclu de viață: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skill-uri invocabile: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 skill-uri de referință pe care agentul le încarcă la cerere (disciplina memoriei, instrumente MCP, API REST, configurare, agenți, hook-uri, arhitectură și ghidul de scriere a skill-urilor)
+
+Motorul de hook-uri al lui Codex injectează `CLAUDE_PLUGIN_ROOT` în subprocesele de hook (conform [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), astfel încât aceleași scripturi de hook funcționează pe ambele platforme (hosts), fără duplicare. Evenimentele Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure sunt specifice doar Claude Code și nu sunt înregistrate pentru Codex.
+
+#### Încrederea și compatibilitatea hook-urilor Codex
+
+Declanșarea nativă a hook-urilor de plugin este verificată cu Codex CLI 0.150.1. Acordă încredere (trust) hook-urilor de plugin înainte de a te aștepta la captare. Comportamentul Codex Desktop depinde de runtime-ul său inclus; verifică `/hooks` și confirmă un eveniment captat înainte de a activa o soluție alternativă.
+
+Dacă host-ul tău necesită hook-uri globale, oglindește comenzile în `~/.codex/hooks.json`. Când MCP este deja conectat, conectorul actual are nevoie de `--force` pentru a ajunge la instalarea hook-urilor:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Aceasta îmbină hook-urile globale și rescrie intrarea MCP a agentmemory, păstrând intrările fără legătură. Verifică orice setări personalizate ale endpoint-ului agentmemory înainte de a folosi `--force`. Rulează din nou după actualizare, pentru a reîmprospăta căile scripturilor. Activează fie hook-urile native de plugin, fie copiile globale, pentru a evita captarea duplicată.
+
+### GitHub Copilot CLI
+
+Pentru modul agent din VS Code, folosește [ghidul MCP și captare automată pentru Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Conectorul CLI nu configurează VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` îmbină `mcpServers.agentmemory` în `~/.copilot/mcp-config.json` (sau `$COPILOT_HOME/mcp-config.json`, când `COPILOT_HOME` este setat) și păstrează serverele existente. Pe Windows nativ, acesta este singurul adaptor `connect` automatizat; configurează manual orice alt agent nativ pe Windows. `connect` în WSL este suportat doar atunci când agentul țintă este instalat în același mediu WSL. Copilot detectează serverul MCP la următoarea pornire sau după `/mcp`. Instalează și plugin-ul atunci când vrei experiența completă de hook-uri/skill-uri.
+
+
+OpenClaw (lipește acest prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Ghid complet: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (lipește acest prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Ghid complet: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Alți agenți
+
+Pornește serverul de memorie: `npx -y @agentmemory/agentmemory@latest`
+
+#### Skill-uri native prin `npx skills add` (50+ agenți)
+
+agentmemory vine cu 17 skill-uri în formatul `/SKILL.md`, în stilul Claude Code: 9 skill-uri de acțiune invocabile (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) și 8 skill-uri de referință pe care agentul le încarcă la cerere (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Skill-urile de referință conțin tabele de date generate din sursă, așa că nu devin niciodată desincronizate. CLI-ul [`skills`](https://npmjs.com/package/skills) de la vercel-labs le instalează automat în directorul nativ de skill-uri al agentului apelant, pe 50+ agenți (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf și altele):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Aceasta este **complementară** cu `agentmemory connect `:
+
+- `agentmemory connect ` scrie configurația serverului MCP, astfel încât instrumentele să fie disponibile.
+- `npx skills add rohitg00/agentmemory` instalează skill-urile, astfel încât agentul să știe când să le apeleze.
+
+Pentru puținii agenți pe care CLI-ul skills nu îi acoperă încă (Zed v1.3.x și versiuni mai vechi), plasează tu însuți cele 17 fișiere SKILL.md în directorul nativ de skill-uri al agentului; același format funcționează pretutindeni.
+
+#### Bloc MCP standard
+
+Intrarea agentmemory este **același bloc de server MCP** pe fiecare host care folosește forma `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Îmbină această intrare în obiectul `mcpServers` existent** din fișierul de configurare al host-ului; nu înlocui fișierul. Dacă fișierul are deja alte servere, adaugă `agentmemory` alături de ele, ca o altă cheie în interiorul `mcpServers`. Dacă `mcpServers` lipsește complet, lipește blocul în interiorul `{ "mcpServers": { ... } }`. Placeholder-ele `${VAR}` preiau `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` din shell la pornirea serverului MCP; variabilele nesetate transmit șiruri vide, iar shim-ul trece la `http://localhost:3111`. O singură intrare conectată acoperă atât deployment-urile locale, cât și cele la distanță (k8s / cu reverse-proxy).
+
+| Agent | Fișier de configurare | Note |
+|---|---|---|
+| **Cursor (doar MCP)** | `~/.cursor/mcp.json` | Îmbină în `mcpServers`, sau `agentmemory connect cursor`. Este disponibil și un deeplink cu un singur clic pe site. |
+| **Cursor (plugin complet)** | `.cursor-plugin/` | Listare în Cursor Marketplace (trimiterea este în curs de revizuire) sau Cursor Settings → Plugins → checkout local. Înregistrează 7 hook-uri de captare automată (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill-uri + serverul MCP, cu `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` gestionate în dashboard-ul de plugin-uri al Cursor. Funcționează în IDE-ul Cursor și în CLI-ul `cursor-agent`; prompturile din modul print al CLI-ului sunt completate retroactiv din transcrierea sesiunii, la finalul sesiunii. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Îmbină în `mcpServers`. Repornește Claude Desktop după editare. |
+| **Cline / Roo Code / Kilo Code** | Setările MCP din Cline (interfața de Settings → MCP Servers → Edit) | Același bloc `mcpServers`. |
+| **Devin CLI (MCP + hook-uri)** | `~/.config/devin/config.json` | `agentmemory connect devin` îmbină intrarea MCP; `--with-hooks` adaugă șase hook-uri native de captare automată (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd), cu matcher-ele de instrumente scrise cu litere mici specifice lui Devin. Verifică cu `devin mcp list` și `/hooks` în interiorul devin. |
+| **Devin CLI (plugin complet)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin`, rulat dintr-un checkout, înregistrează toate cele 17 skill-uri ca comenzi slash `/agentmemory:`, plus serverul MCP. Hook-urile de plugin din Devin nu pot declanșa `SessionStart`/`SessionEnd`, așa că asociază-l cu `connect devin --with-hooks` pentru captarea completă a sesiunii. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Adaugă un MCP personalizat (STDIO): comanda `npx`, argumente `-y @agentmemory/mcp@latest`, variabila de mediu `AGENTMEMORY_URL` care indică un deployment agentmemory accesibil din rețea, plus `AGENTMEMORY_SECRET` (sesiunile din cloud nu pot accesa localhost — vezi [`deploy/`](../deploy/)). Stochează secretul în Devin Secrets, apoi folosește „Test listing tools” pentru a verifica că apar toate cele 54 de instrumente. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (se îmbină automat). |
+| **GitHub Copilot CLI (doar MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` îmbină `mcpServers.agentmemory`; Copilot îl detectează la următoarea pornire sau după `/mcp`. |
+| **GitHub Copilot CLI (plugin complet)** | Instalare plugin Copilot | `copilot plugin install rohitg00/agentmemory:plugin` pentru plugin-ul din subdirectorul GitHub. |
+| **OpenClaw** | Configurația MCP OpenClaw | Același bloc `mcpServers`. Mai în profunzime: `openclaw plugins install ./integrations/openclaw` ocupă slotul de memorie al OpenClaw (comută automat de la `memory-core`); setează `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, altfel captarea turei este blocată silențios. Vezi [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (doar MCP)** | `.codex/config.toml` | Formă TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, sau adaugă manual `[mcp_servers.agentmemory]`. |
+| **Codex CLI (plugin complet)** | Marketplace-ul de plugin-uri Codex | `codex plugin marketplace add rohitg00/agentmemory`, apoi `codex plugin add agentmemory@agentmemory`. Înregistrează MCP + 6 hook-uri de ciclu de viață + 17 skill-uri. Acordă încredere hook-urilor și verifică captarea pe host-ul tău; vezi [configurarea și validarea Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (doar MCP)** | `opencode.json` | Formă diferită: cheia `mcp` la nivel superior, comanda ca array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin complet)** | `plugin/opencode/` | 22 de hook-uri de captare automată, care acoperă ciclul de viață al sesiunii, mesajele, instrumentele și erorile. Atribuirea proiectului se face per sesiune, astfel încât un proces OpenCode care se întinde pe mai multe repository-uri înregistrează fiecare sesiune sub propriul ei proiect. Două comenzi slash (`/recall`, `/remember`). Copiază `plugin/opencode/` în workspace-ul tău OpenCode și adaugă intrarea plugin-ului în `opencode.json`. Vezi [`plugin/opencode/README.md`](../plugin/opencode/README.md) pentru tabelul complet de hook-uri + analiza lacunelor. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` instalează extensia inclusă în directorul de auto-detectare al pi (reamintire la pornirea agentului, captare la finalul agentului, instrumentele `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` într-un pi care rulează deja o detectează. [`integrations/pi`](../integrations/pi/) este, de asemenea, un pachet pi (`pi install ./integrations/pi` dintr-un checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` oferă furnizorul de memorie cu 6 hook-uri (prefetch, captarea turei, final de sesiune, pre-compresie, oglindirea MEMORY.md, bloc de system prompt). Validează cu `hermes plugins doctor` și `hermes memory status`. Vezi [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` scrie blocul standard `mcpServers`. Payload-ul hook-ului este compatibil la nivel de câmpuri cu Claude Code, astfel încât scripturile existente cu 12 hook-uri funcționează fără modificări; conectează-le prin secțiunea `hooks` din același `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` instalează MCP și hook-urile de captare în directorul partajat de personalizare. Vezi [configurarea și limitele Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` folosește aceeași configurație MCP și de hook-uri ca versiunile IDE actuale. Instalările existente ar trebui să se reîmprospăteze cu `--force`; vezi [notele de actualizare](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` scrie configurația la nivel de utilizator. Suprascrierile la nivel de workspace se pun în `.kiro/settings/mcp.json`, alături de codul tău. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` scrie blocul standard `mcpServers`. Warp detectează automat și skill-urile din `.claude/skills/`; odată instalat plugin-ul Claude Code, cele 8 skill-uri agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) apar nativ în paleta de comenzi slash a Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` scrie blocul standard `mcpServers`. Utilizatorii extensiei VS Code: lipește același bloc prin Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferat) sau `config.json` (vechi/legacy) | `agentmemory connect continue` creează `config.yaml` de la zero când niciunul dintre cele două nu există, sau modifică `config.json`-ul existent. **Dacă ai deja `config.yaml`**, adaptorul afișează exact blocul de lipit sub `mcpServers:`; nu îți rescrie silențios yaml-ul, pentru că păstrarea sigură a comentariilor și a ancorelor necesită un parser YAML pe care pachetul nu îl include. Continue folosește forma de array (nu obiect) pentru `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` scrie sub `context_servers` (cheia specifică Zed, NU `mcpServers`). Serverele MCP la distanță pot fi conectate, în schimb, prin `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` scrie blocul standard `mcpServers`. Suprascrierile la nivel de proiect se pun în `/.factory/mcp.json`. Transmite `--with-hooks` pentru captare automată nativă. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` adaugă un rând `@deepseek-ai/dsh-mcp-client` în stratul de patch la nivel de home, pe care îl încarcă fiecare profil Harness; instrumentele se înregistrează ca `mcp__agentmemory__*`. Transmite `--with-hooks` pentru a conecta și captarea automată: scripturile de hook Claude Code incluse rulează prin bridge-ul oficial `@deepseek-ai/dsh-hooks-claude-code` al lui Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop), printr-un manifest scris în `$DSH_HOME/agentmemory.hooks.json`. Implicit `~/.dsh`, când `DSH_HOME` nu este setat. |
+| **Goose** | Interfața de setări MCP din Goose | Același bloc `mcpServers`; folosește `goose configure` → Add Extension → MCP. Editarea directă a YAML-ului la `~/.config/goose/config.yaml` este suportată, dar schema folosește `extensions:` + `cmd` (nu `mcpServers:` + `command`). |
+| **Aider** | n/a | Vorbește direct cu API-ul REST: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Orice agent (32+)** | n/a | `npx skillkit install agentmemory` detectează automat host-ul și îmbină configurația. |
+
+**Clienții MCP sandbox-izați** (Flatpak / Snap / containere restrictive) care nu pot accesa `localhost`-ul host-ului: setează și `"AGENTMEMORY_FORCE_PROXY": "1"` în blocul `env` și direcționează `AGENTMEMORY_URL` către o rută pe care sandbox-ul o poate accesa efectiv (de ex. IP-ul tău din rețeaua locală).
+
+### Acces programatic (Python / Rust / Node)
+
+agentmemory își înregistrează operațiile de bază ca funcții iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Orice limbaj care are un SDK iii le poate apela direct prin `ws://localhost:49134`, fără a avea nevoie de un client REST separat pentru fiecare limbaj.
+
+```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"},
+})
+```
+
+Exemplu funcțional: [`examples/python/`](../examples/python/) (început rapid + flux de observație/reamintire). REST pe `:3111` rămâne disponibil pentru host-urile fără runtime iii.
+
+### Din sursă
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Aceasta pornește agentmemory cu un `iii-engine` local, dacă binarul fixat este deja instalat, sau folosește Docker Compose, când este selectat. REST, stream-urile și vizualizatorul se leagă (bind) implicit la `127.0.0.1`. Calea automată pentru binarul pe macOS/Linux necesită `curl`, un `sh` POSIX și `tar`.
+
+Instalează manual `iii-engine`. **agentmemory fixează momentan `iii-engine` la `v0.22.1`**, aceeași versiune ca dependența sa `iii-sdk`; worker-ul vorbește protocolul de rețea al acelui motor, iar 0.20.0 a reorganizat suprafața SDK-ului, așa că cele două avansează împreună în versiunile agentmemory. Suprascrie cu `AGENTMEMORY_III_VERSION=`, dacă rulezi propriul tău motor și știi că se potrivește.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** înlocuiește `aarch64-apple-darwin` cu `x86_64-apple-darwin`
+- **Linux x64:** înlocuiește cu `x86_64-unknown-linux-gnu`
+- **Linux arm64:** înlocuiește cu `aarch64-unknown-linux-gnu`
+- **Windows:** descarcă `iii-x86_64-pc-windows-msvc.zip` de la [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) și extrage `iii.exe` în `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Fiecare arhivă are un fișier `.sha256` corespunzător pe pagina de release; când schimbi platforma, folosește hash-ul din acel fișier în verificarea de mai sus (pe Windows: `Get-FileHash`). Installer-ul automat din `npx @agentmemory/agentmemory` fixează aceste hash-uri și refuză o arhivă care nu se potrivește.
+
+Sau folosește Docker (`docker-compose.yml`-ul inclus descarcă `iiidev/iii:0.22.1`). Documentație completă: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory rulează pe Windows 10/11, dar pachetul Node.js, de unul singur, nu este suficient; ai nevoie și de runtime-ul iii-engine v0.22.1 fixat, ca proces în fundal. CLI-ul nu extrage automat arhiva ZIP pentru Windows, așa că utilizatorii Windows nativ trebuie să instaleze manual `iii.exe`, să folosească WSL2 sau să aleagă Docker Desktop.
+
+Conectarea MCP automatizată pe Windows nativ suportă doar `agentmemory connect copilot-cli`. Pentru Claude Code, Codex, Cursor și orice alt agent nativ pe Windows, copiază blocul MCP manual din [Alți agenți](#other-agents) în configurația Windows a acelui agent. Rularea `connect` în WSL este potrivită doar atunci când agentul țintă este instalat și el în același mediu WSL; aceasta nu editează configurația unui agent de pe host-ul Windows.
+
+**Opțiunea A: binar Windows precompilat (recomandat)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opțiunea B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opțiunea C: doar MCP independent (fără motor).** Dacă ai nevoie doar de instrumentele MCP pentru agentul tău și nu ai nevoie de API-ul REST, de vizualizator sau de job-uri cron, poți sări complet peste motor:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnosticare pentru Windows:** dacă `npx -y @agentmemory/agentmemory@latest` eșuează, rulează-o din nou cu `--verbose` pentru a vedea stderr-ul real al motorului. Moduri de eșec frecvente:
+
+| Simptom | Remediere |
+|---|---|
+| `The engine process started but the REST API never responded.` | Confirmă că toate cele patru porturi derivate sunt libere, verifică dacă `iii.exe`-ul fixat a rămas activ, apoi rulează din nou cu `--verbose` și inspectează stderr-ul capturat al motorului |
+| `Could not start iii-engine` | Nici `iii.exe`, nici Docker nu sunt instalate. Vezi Opțiunea A sau B de mai sus |
+| Conflict de port | `netstat -ano \| findstr :3111` pentru a vedea ce este ocupat, apoi termină procesul sau folosește `--port ` |
+| Trecerea la Docker este omisă, deși Docker este instalat | Asigură-te că Docker Desktop rulează efectiv (iconița din system tray) |
+
+> Notă: **motorul** iii este un binar precompilat, nu un cargo crate, așa că nu încerca să îl instalezi cu `cargo install`. (**SDK-urile** iii sunt publicate pe crates.io, npm și PyPI, dar agentmemory nu are nevoie de ele.) Toate metodele suportate de instalare a motorului sunt fixate la v0.22.1: binarul precompilat de mai sus, calea de auto-instalare macOS/Linux a agentmemory (necesită `curl`, `sh` POSIX și `tar`) și imaginea Docker `iiidev/iii:0.22.1`. Un simplu `install.sh | sh` din upstream instalează cel mai recent motor, pe care agentmemory nu îl suportă. Folosește `npx -y @agentmemory/agentmemory@latest`; pe macOS/Linux, aceasta preia motorul fixat în `~/.agentmemory/bin`.
+
+---
+
+
Implementare (Deploy)
+
+Șabloane cu un singur clic pentru hosting administrat. Fiecare șablon include un Dockerfile de sine stătător, care descarcă `@agentmemory/agentmemory` de pe npm și copiază binarul motorului iii din imaginea oficială `iiidev/iii` de pe Docker Hub; nu este necesară o imagine agentmemory precompilată. Stocarea persistentă este montată la `/data`; entrypoint-ul de la prima pornire suprascrie configurația iii inclusă în pachetul npm (care se leagă la `127.0.0.1`) cu una ajustată pentru deployment, care se leagă la `0.0.0.0` și folosește căi `/data` absolute, generează secretul HMAC, apoi reduce privilegiile de la `root` la `node`, prin `gosu`, înainte de a executa (exec) CLI-ul agentmemory.
+
+
+
+
+
+
+Butonul de implementare cu un singur clic al Render necesită `render.yaml` în rădăcina repository-ului, pe care îl păstrăm intenționat curat (gol). Folosește fluxul Render Blueprint documentat în [`deploy/render/`](.././deploy/render/README.md) pentru a indica manual blueprint-ul din repository.
+
+Detaliile complete de configurare (capturarea HMAC, tunel SSH pentru vizualizator, rotație, backup, costuri minime) se află în [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): o singură mașină, cu `auto_stop_machines = "stop"`; cel mai ieftin în repaus (idle).
+- [`deploy/railway`](.././deploy/railway/README.md): tarif fix pentru planul Hobby, volum în dashboard.
+- [`deploy/render`](.././deploy/render/README.md): flux Blueprint, instantanee (snapshots) automate de disc pe planurile plătite.
+- [`deploy/coolify`](.././deploy/coolify/README.md): auto-hostat pe propriul tău VPS, prin [Coolify](https://coolify.io/self-hosted); aceeași stivă Docker Compose, tu deții host-ul și datele.
+
+Este publicat doar portul `3111`. Vizualizatorul de pe `3113` rămâne legat la loopback în interiorul containerului; README-ul fiecărui șablon documentează modelul de tunel SSH pentru a-l accesa.
+
+---
+
+
+
+Fiecare agent de programare uită totul când sesiunea se termină, iar fiecare sesiune nouă începe cu tine re-explicând stack-ul tău. agentmemory rulează în fundal și elimină acest pas.
+
+```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 memoria încorporată a agentului
+
+Fiecare agent de programare AI vine cu memorie încorporată: Claude Code are `MEMORY.md`, Cursor are notepad-uri, Cline are memory bank. Acestea funcționează ca niște bilețele adezive (sticky notes). agentmemory este baza de date căutabilă din spatele bilețelelor adezive.
+
+| | Încorporat (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Scalare | Plafon de 200 de linii | Nelimitat |
+| Căutare | Încarcă totul în context | BM25 + vector + graf (doar top-K) |
+| Cost în tokeni | 22K+ la 240 de observații | ~1,900 tokeni (92% mai puțin) |
+| Între agenți | Fișiere per agent | MCP + REST (orice agent) |
+| Coordonare | Niciuna | Lease-uri, semnale, acțiuni, rutine |
+| Observabilitate | Citire manuală a fișierelor | Vizualizator în timp real pe :3113 |
+
+---
+
+
+
+### Pipeline-ul de memorie
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### Consolidarea memoriei pe 4 niveluri
+
+Modelată după modul în care creierul uman procesează memoria, inclusiv consolidarea prin somn.
+
+| Nivel | Ce reprezintă | Analogie |
+|------|------|---------|
+| **Working (de lucru)** | Observații brute din folosirea instrumentelor | Memorie pe termen scurt |
+| **Episodic** | Rezumate comprimate ale sesiunilor | „Ce s-a întâmplat” |
+| **Semantic** | Fapte și modele extrase | „Ce știu” |
+| **Procedural** | Fluxuri de lucru și modele de decizie | „Cum se face” |
+
+Memoriile se degradează în timp (curba lui Ebbinghaus). Memoriile accesate frecvent se întăresc. Memoriile vechi/inactive sunt eliminate automat. Contradicțiile sunt detectate și rezolvate.
+
+### Ce se captează
+
+| Hook | Captează |
+|------|----------|
+| `SessionStart` | Calea proiectului, ID-ul sesiunii |
+| `UserPromptSubmit` | Prompturile utilizatorului (filtrate pentru confidențialitate) |
+| `PreToolUse` | Modele de acces la fișiere + context îmbogățit |
+| `PostToolUse` | Numele instrumentului, input, output |
+| `PostToolUseFailure` | Contextul erorii |
+| `PreCompact` | Reinjectează memoria înainte de compactare |
+| `SubagentStart/Stop` | Ciclul de viață al sub-agentului |
+| `Stop` | Rezumat de final de sesiune |
+| `SessionEnd` | Marcator de sesiune finalizată |
+
+### Capabilități esențiale
+
+| Capabilitate | Descriere |
+|---|---|
+| **Captare automată** | Fiecare folosire a unui instrument este înregistrată prin hook-uri, fără efort manual |
+| **Căutare semantică** | BM25 + vector + graf de cunoștințe, cu fuziune RRF |
+| **Evoluția memoriei** | Versionare, suprascriere (supersession), grafuri de relații |
+| **Igiena reamintirii** | Versiunile de memorie suprascrise sunt eliminate din indecșii de căutare; lanțul de versiuni din KV păstrează istoricul complet |
+| **Indicii de aproape-duplicat** | Salvările raportează o potrivire consultativă `similarTo`, atunci când conținutul nou se aseamănă foarte mult cu o memorie existentă |
+| **Scopare per agent** | `agentId` traversează salvarea și reamintirea pe REST, MCP și indexul de căutare, în mod partajat sau izolat |
+| **Proveniență la momentul scrierii** | Fiecare observație și memorie poartă un canal de origine imuabil (user, agent, tool, import sau shared), marcat la captare, salvare și import |
+| **Uitare automată** | Expirare TTL, detectarea contradicțiilor, eliminare pe baza importanței |
+| **Confidențialitate înainte de toate** | Cheile API, secretele, etichetele `` sunt eliminate înainte de stocare |
+| **Auto-reparare** | Circuit breaker, lanț de fallback între furnizori, monitorizarea stării de sănătate |
+| **Punte Claude** | Sincronizare bidirecțională cu MEMORY.md |
+| **Graf de cunoștințe** | Extracția entităților + traversare BFS |
+| **Memorie de echipă** | Partajată și privată, separată pe namespace-uri, între membrii echipei |
+| **Proveniența citărilor** | Urmărește orice memorie înapoi la observațiile sursă |
+| **Instantanee Git** | Versionează, revino (rollback) și compară (diff) starea memoriei |
+
+---
+
+
+
+Regăsire triplu-flux, care combină trei semnale:
+
+| Flux | Ce face | Când |
+|---|---|---|
+| **BM25** | Potrivire pe cuvinte cheie cu stemming și expansiune de sinonime | Mereu activ |
+| **Vector** | Similaritate cosinus pe embeddings dense | Furnizor de embedding configurat |
+| **Graf** | Traversarea grafului de cunoștințe prin potrivirea entităților | Entități detectate în interogare |
+
+Fuzionate prin Reciprocal Rank Fusion (RRF, k=60) și diversificate pe sesiune (maximum 3 rezultate per sesiune).
+
+Când indexul vectorial este populat, `mem::search` (din spatele lui `memory_recall`) folosește clasificatorul hibrid BM25 + vector. Fără embeddings, folosește BM25. `smart-search` poate fuziona, în plus, potriviri structurale din graf, atunci când există date de graf, inclusiv în modul keyless. Reamintirea lecțiilor rulează pe un index BM25 dedicat, în memorie, în loc să scaneze întregul corpus la fiecare interogare. Versiunile de memorie suprascrise sunt excluse din fiecare rută de reamintire; lanțul de versiuni le păstrează istoricul.
+
+Vectorii supraviețuiesc unui crash sau unei terminări forțate (force-kill). Indexul vectorial este salvat pe loturi (buckets) cel mult o dată la fiecare `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minute). Fiecare vector adăugat sau eliminat între timp este scris imediat și într-un mic jurnal de așteptare (pending log) din state store, iar următoarea pornire îl reaplică fără a apela furnizorul de embedding. Fiecare salvare reușită golește jurnalul. Documentele care încă nu au un vector după reaplicare sunt reîncorporate (re-embedded) în fundal, pe loturi de `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), până când nu mai rămâne niciunul, iar o reumplere (backfill) întreruptă continuă la următoarea pornire. `/agentmemory/status` și vizualizatorul arată dimensiunea jurnalului de așteptare și starea reumplerii. Instalările keyless nu scriu nimic.
+
+BM25 tokenizează, din oficiu, greaca, chirilica, ebraica, araba și latina cu diacritice. Pentru memorii în chineză / japoneză / coreeană, instalează segmentatoarele opționale (`npm install @node-rs/jieba tiny-segmenter`) pentru a împărți secvențele CJK în tokeni la nivel de cuvânt; fără ele, agentmemory trece ușor la tokenizarea întregii secvențe și afișează o singură dată un indiciu pe stderr.
+
+### Furnizori de embedding
+
+Instalările keyless dezactivează embeddings vectoriale: `mem::search` folosește BM25, în timp ce `smart-search` poate folosi și datele structurale existente din graf. Pentru a opta pentru embeddings semantice gratuite, pe dispozitiv, adaugă următoarele în `~/.agentmemory/.env` și repornește agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Instalarea npm normală include runtime-ul opțional `@huggingface/transformers`. Prima cerere de embedding descarcă `Xenova/all-MiniLM-L6-v2`, așa că necesită acces la rețea și poate dura mai mult; inferența următoare rulează pe dispozitiv. Furnizorii la distanță sunt detectați automat după cheile lor, cu excepția cazului în care `EMBEDDING_PROVIDER` îi suprascrie.
+
+| Furnizor | Model | Cost | Note |
+|---|---|---|---|
+| **Local (opțiune recomandată)** | `all-MiniLM-L6-v2` | Gratuit | Pe dispozitiv, după prima descărcare a modelului; +8pp recall față de doar-BM25 |
+| Gemini | `gemini-embedding-001` | Nivel gratuit | 100+ limbi, 768/1536/3072 dimensiuni (MRL), input de 2048 de tokeni. Înlocuiește `text-embedding-004` ([depreciat, dezactivat 14 ian. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Cea mai bună calitate |
+| Voyage AI | `voyage-code-3` | Plătit | Optimizat pentru cod |
+| Cohere | `embed-english-v3.0` | Perioadă de probă gratuită | Scop general |
+| OpenRouter | Orice model | Variabil | Proxy multi-model |
+
+---
+
+
+
+54 de instrumente, 6 resurse, 3 prompturi și 17 skill-uri.
+
+> **Shim MCP vs server complet:** pachetul publicat `@agentmemory/mcp` este un shim minimal. Expune suprafața completă de 54 de instrumente **doar atunci când poate accesa un server agentmemory în funcțiune**, prin `AGENTMEMORY_URL` (mod proxy). Când niciun server nu este accesibil, shim-ul trece la un set local de 7 instrumente (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Variabila de mediu `AGENTMEMORY_TOOLS=core|all` este un flag *pe partea de server*; setarea ei în blocul `env` al shim-ului nu are niciun efect. Dacă vezi doar 7 instrumente în Cursor / OpenCode / Gemini CLI, pornește `npx -y @agentmemory/agentmemory@latest` (sau stiva Docker) și setează `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 de instrumente
+
+Trei suprafețe de instrumente, de la cea mai mică la cea mai mare: `AGENTMEMORY_TOOLS=core` reduce vizibilitatea la 8 instrumente esențiale (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); setul de bază de mai jos reprezintă cele 14 instrumente fundamentale ale registrului; implicit (`AGENTMEMORY_TOOLS=all`) sunt expuse toate cele 54.
+
+
+Instrumente de bază (14)
+
+| Instrument | Descriere |
+|------|-------------|
+| `memory_recall` | Caută observații anterioare |
+| `memory_compress_file` | Comprimă fișiere markdown, păstrând structura |
+| `memory_save` | Salvează o observație (insight), o decizie sau un model |
+| `memory_file_history` | Observații anterioare despre fișiere specifice |
+| `memory_patterns` | Detectează modele recurente |
+| `memory_sessions` | Listează sesiunile recente |
+| `memory_smart_search` | Căutare hibridă, semantică + cuvinte cheie |
+| `memory_vision_search` | Caută observații pe bază de imagine |
+| `memory_timeline` | Observații în ordine cronologică |
+| `memory_profile` | Profilul proiectului (concepte, fișiere, modele) |
+| `memory_export` | Exportă toate datele de memorie |
+| `memory_relations` | Interoghează graful de relații |
+| `memory_commit_lookup` | Sesiunile din spatele unui commit git |
+| `memory_commits` | Commit-urile înregistrate pentru o sesiune |
+
+
+
+
+Instrumente extinse (54 în total, suprafața implicită)
+
+| Instrument | Descriere |
+|------|-------------|
+| `memory_patterns` | Detectează modele recurente |
+| `memory_timeline` | Observații în ordine cronologică |
+| `memory_relations` | Interoghează graful de relații |
+| `memory_graph_query` | Traversarea grafului de cunoștințe |
+| `memory_consolidate` | Rulează consolidarea pe 4 niveluri |
+| `memory_claude_bridge_sync` | Sincronizare cu MEMORY.md |
+| `memory_team_share` | Partajează cu membrii echipei |
+| `memory_team_feed` | Elementele partajate recent |
+| `memory_audit` | Traseul de audit al operațiilor |
+| `memory_governance_delete` | Șterge, cu traseu de audit |
+| `memory_snapshot_create` | Instantaneu versionat în Git |
+| `memory_action_create` | Creează elemente de lucru cu dependențe |
+| `memory_action_update` | Actualizează starea unei acțiuni |
+| `memory_frontier` | Acțiuni nedeblocate, clasate după prioritate |
+| `memory_next` | Următoarea acțiune, cea mai importantă |
+| `memory_lease` | Lease-uri exclusive de acțiune (multi-agent) |
+| `memory_routine_run` | Instanțiază rutine de flux de lucru |
+| `memory_signal_send` | Mesagerie între agenți |
+| `memory_signal_read` | Citește mesaje, cu confirmări de primire |
+| `memory_checkpoint` | Porți de condiții externe |
+| `memory_mesh_sync` | Sincronizare P2P între instanțe |
+| `memory_sentinel_create` | Observatori declanșați de evenimente |
+| `memory_sentinel_trigger` | Declanșează sentinelele din exterior |
+| `memory_sketch_create` | Grafuri de acțiuni efemere |
+| `memory_sketch_promote` | Promovează la permanent |
+| `memory_crystallize` | Compactează lanțuri de acțiuni |
+| `memory_diagnose` | Verificări de sănătate |
+| `memory_heal` | Remediază automat o stare blocată |
+| `memory_facet_tag` | Etichete dimensiune:valoare |
+| `memory_facet_query` | Interoghează după etichete de fațetă |
+| `memory_verify` | Urmărește proveniența |
+
+
+
+### 6 resurse · 3 prompturi · 17 skill-uri
+
+| Tip | Nume | Descriere |
+|------|------|-------------|
+| Resursă | `agentmemory://status` | Stare de sănătate, numărul de sesiuni, numărul de memorii |
+| Resursă | `agentmemory://project/{name}/profile` | Informații specifice proiectului |
+| Resursă | `agentmemory://project/{name}/recent` | Observații recente pentru un proiect |
+| Resursă | `agentmemory://memories/latest` | Ultimele 10 memorii active |
+| Resursă | `agentmemory://graph/stats` | Statisticile grafului de cunoștințe |
+| Resursă | `agentmemory://team/{id}/profile` | Profilul partajat al echipei |
+| Prompt | `recall_context` | Caută și returnează mesaje de context |
+| Prompt | `session_handoff` | Date de predare (handoff) între agenți |
+| Prompt | `detect_patterns` | Analizează modele recurente |
+| Skill | `/recall` | Caută în memorie |
+| Skill | `/remember` | Salvează în memoria pe termen lung |
+| Skill | `/session-history` | Rezumate ale sesiunilor recente |
+| Skill | `/forget` | Șterge observații/sesiuni |
+
+Tabelul arată cele patru skill-uri de bază. Setul complet este de 9 skill-uri invocabile, plus 8 skill-uri de referință; vezi secțiunea Skill-uri native de mai sus.
+
+### MCP independent
+
+Rulează fără serverul complet, pentru orice client MCP. Funcționează orice dintre acestea:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Sau adaugă în configurația MCP a agentului tău:
+
+Majoritatea agenților (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Îmbină intrarea `agentmemory` în obiectul `mcpServers` existent al host-ului tău, în loc să înlocuiești fișierul. Pentru clienții sandbox-izați care nu pot accesa `localhost`-ul host-ului, adaugă `"AGENTMEMORY_FORCE_PROXY": "1"` în blocul env și setează `AGENTMEMORY_URL` la o rută pe care sandbox-ul o poate accesa.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copiază fișierul plugin-ului din repository:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Pornește automat pe portul `3113`. Vizualizatorul încarcă un instantaneu (snapshot) la conectare (`GET /agentmemory/viewer/snapshot`) și apoi aplică evenimentele din stream-ul live: memorii noi, lecții, observații, intrări de audit, modificări ale grafului și actualizări de stare apar fără polling sau reîncărcarea paginii. Singurele alte cereri sunt acțiunile pe care le apeși, paginile de tip „încarcă mai multe” și căutările. Când stream-ul se întrerupe, vizualizatorul arată cât de vechi sunt datele, se reconectează cu backoff și se resincronizează dintr-un instantaneu.
+
+- **12 tab-uri în patru grupuri**, cu numărători live, deep link-uri (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), scurtături de tastatură și un meniu mobil.
+- **Memories:** căutare pe server, filtre după proiect, agent și tip, un panou de detalii cu lanțul de versiuni și un diff pe cuvinte, link-uri de proveniență, butoane de copiere pentru id, apelul MCP și o comandă curl, editare (o versiune nouă), ștergere (forget) cu confirmare, ștergere în masă și export JSON.
+- **Sessions:** o linie temporală de observații inline, cu input și output lizibile ale instrumentelor, filtre și paginare, plus memoriile și lecțiile produse de fiecare sesiune.
+- **Graph:** căutare, detalii de nod cu relații și surse, o legendă care nu se bazează doar pe culoare și controale de zoom.
+- **Health:** versiunea live a `GET /agentmemory/status`. Fiecare problemă vine cu remedierea ei, plus backend-ul de stare, starea de salvare a indexului, progresul compactării provenienței grafului și o explicație a consolidării, cu pragurile reale.
+- Paginile **Audit, Activity, Profile, Replay, Lessons, Actions și Crystals**, fiecare cu o stare goală care spune ce reprezintă secțiunea, de ce este goală și comanda care o populează, plus un tooltip de glosar `?` pentru fiecare termen și număr.
+
+```bash
+open http://localhost:3113
+```
+
+Serverul vizualizatorului se leagă implicit la `127.0.0.1` și atașează secretul serverului atunci când transmite cererile către API-ul REST, așa că nu necesită nicio configurare. Endpoint-ul `/agentmemory/viewer`, servit prin REST, respectă regulile normale de bearer-token și redirecționează browserele fără token către portul vizualizatorului. Header-ele CSP folosesc un nonce de script per răspuns și dezactivează atributele de handler inline (`script-src-attr 'none'`).
+
+---
+
+
+
+Vizualizatorul de pe `:3113` arată ce **și-a amintit** agentul tău. [Consola iii](https://iii.dev/docs/console) arată ce **a făcut** agentul tău: fiecare operație de memorie, ca trasare OpenTelemetry, fiecare intrare KV editabilă, fiecare funcție invocabilă, fiecare stream accesibil (tappable). Două ferestre către aceeași memorie: una modelată ca produs, una modelată ca motor.
+
+Urmărește un `memory_smart_search` declanșându-se și vezi scanarea BM25 → căutarea embedding-ului → fuziunea RRF → reranker-ul, ca o cascadă (waterfall). Editează un timer de consolidare blocat, în browser-ul de KV. Reluează un hook `PostToolUse` cu un payload ajustat. Fixează (pin) stream-ul WebSocket și urmărește observațiile ajungând în timp real.
+
+agentmemory oferă toate acestea gratuit, pentru că fiecare apel de funcție și fiecare trigger trece prin iii; nimic personalizat, nimic de instrumentat.
+
+
+
+
+ Pagina Workers: fiecare worker conectat, inclusiv agentmemory însuși, cu PID, numărul de funcții, runtime și ultima activitate (last-seen).
+
+
+**Deja instalată.** Consola vine odată cu motorul `iii` fixat (0.22+); nu este nimic separat de instalat. Prima pornire descarcă binarul consolei alături de motor.
+
+**Pornește-o alături de agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Aceasta rulează `iii console` din motorul fixat, pe porturile rezolvate de agentmemory (REST, stream-uri, bridge), și o servește pe un port deasupra vizualizatorului, implicit `http://localhost:3114`. `--console-port N` alege un alt port; `--port` și `--instance` selectează instanța agentmemory, la fel cum fac pentru `stop`; orice alt flag este transmis mai departe, de exemplu `--enable-flow` pentru pagina experimentală de graf al arhitecturii.
+
+Același lucru, manual, util când `agentmemory` nu este în PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Ce poți face din consolă:**
+
+| Pagină | Folosește-o pentru |
+|------|-----------|
+| **Workers** | A vedea fiecare worker conectat și metricile sale live, inclusiv worker-ul agentmemory însuși. |
+| **Functions** | A invoca direct orice funcție a agentmemory, cu un payload JSON; util pentru a testa `memory.recall`, `memory.consolidate`, `graph.query`, fără a conecta un client. |
+| **Triggers** | A relua trigger-e HTTP, cron, de evenimente și de stare: a declanșa manual cron-ul de consolidare, a reîncerca o rută HTTP, a emite o schimbare de stare. |
+| **States** | Un browser KV cu CRUD complet pentru sesiuni, sloturi de memorie, timere de ciclu de viață și indexul de embeddings; editează valorile direct. |
+| **Streams** | Un monitor WebSocket live pentru scrierile de memorie, evenimentele de hook și actualizările de observații, pe măsură ce trec prin stream-urile iii. |
+| **Queues** | Topicuri de coadă durabile + gestionarea dead-letter. Reia sau elimină job-urile de embedding / compresie care au eșuat. |
+| **Traces** | Vizualizări OpenTelemetry de tip waterfall / flame / defalcare pe servicii. Filtrează după `trace_id`, pentru a vedea exact ce funcții, apeluri DB și cereri de embedding a produs o singură `memory.search`. |
+| **Logs** | Log-uri OTEL structurate, filtrate și corelate cu ID-urile de trace/span. |
+| **Config** | Configurația runtime: vezi exact cu ce worker-i, furnizori și porturi rulează motorul tău. |
+| **Flow** | (Opțional, `--enable-flow`) Graf interactiv de arhitectură, cu fiecare worker, trigger și stream. |
+
+
+
+
+ Traces: waterfall / flame / defalcare pe servicii, pentru fiecare operație de memorie.
+
+
+**Trasarea este deja activă:**
+
+`iii-config.yaml` vine cu worker-ul `iii-observability` activat (`exporter: memory`, `sampling_ratio: 0.1`, metrici + log-uri). Nu este nevoie de nicio configurare suplimentară; în momentul în care agentmemory pornește, fiecare operație de memorie emite un log structurat pe care consola îl poate citi, iar una din zece (`sampling_ratio: 0.1`) emite și un span de trace.
+
+Dacă vrei să exporți către Jaeger/Honeycomb/Grafana Tempo, în schimb, schimbă `exporter: memory` în `exporter: otlp` și setează endpoint-ul colectorului conform documentației de observabilitate a iii.
+
+> **Atenție:** consola în sine nu impune autentificare; păstreaz-o legată la `127.0.0.1` (valoarea implicită) și nu o expune niciodată public.
+
+---
+
+
+
+agentmemory este **deja o instanță [iii](https://iii.dev) în funcțiune**. Trei primitive (worker, funcție, trigger) compun runtime-ul; starea KV, stream-urile și trasele OTEL vin de la worker-ii iii-state, iii-stream și iii-observability, incluși în iii. Nu ai instalat Postgres, Redis, Express, pm2 sau Prometheus, pentru că iii le înlocuiește.
+
+Asta înseamnă că o singură comandă suplimentară extinde agentmemory cu o capabilitate complet nouă.
+
+### Extinde agentmemory cu mai mulți worker-i
+
+Componentele încorporate (builtins) de care are nevoie agentmemory sunt deja în `iii-config.yaml` și pornesc odată cu el: `iii-state` (KV), `iii-queue` (reîncercări durabile pentru abonații la evenimente), `iii-pubsub`, `iii-cron`, `iii-stream` și `iii-observability` (trase OTEL, metrici și log-uri pentru fiecare funcție). Orice altceva din [registrul de worker-i iii](https://workers.iii.dev) se conectează la același motor: copiază `iii-config.yaml` în `~/.agentmemory/iii-config.yaml` (CLI-ul preferă acel fișier în locul celui inclus și îi randează în continuare porturile și căile de date), adaugă intrarea, instalează runtime-ul worker-ului o singură dată, cu `~/.agentmemory/bin/iii update worker`, și repornește agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Ce obții, în plus față de agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Adaptor de stare pe bază de SQL, pentru când crești peste valorile implicite ale KV-ului în memorie |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Codul rezultat din `memory_recall` rulează într-un VM de unică folosință, nu în shell-ul tău |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Pornește servere MCP suplimentare, alături de cel al agentmemory, pe același motor |
+
+Pe motorul 0.22.x, păstrează numele cu prefixul `iii-` pentru componentele încorporate de mai sus; intrările fără prefix `http`, `state`, `queue`, `pubsub` și `cron` sunt worker-ii independenți din registru, către care agentmemory trece odată cu migrarea la 0.23.
+
+Registrul complet: [workers.iii.dev](https://workers.iii.dev). Fiecare worker de acolo se compune prin aceleași primitive pe care le folosește agentmemory, iar agentmemory-ul pe care îl ai deja este unul dintre ei.
+
+### Configurația motorului și adresa de bind
+
+`agentmemory start` citește configurația motorului din primul fișier care există: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` în directorul curent, `~/.agentmemory/iii-config.yaml`, apoi `iii-config.yaml`-ul inclus. La fiecare pornire, randează acel fișier (căi de date, porturi, backend de stare) în `~/.agentmemory/data/iii-config.runtime.yaml` și pornește motorul cu copia randată, așa că editează fișierul sursă, nu pe cel randat. Valorile `host:` din fișierul sursă sunt păstrate așa cum sunt scrise.
+
+`iii-config.yaml`-ul inclus se leagă intenționat la `127.0.0.1`, și această valoare implicită se aplică și în interiorul unui container. Un CLI pornit într-un container ascultă pe loopback-ul containerului, astfel încât porturile publicate nu ajung nicăieri. Pentru a servi un CLI containerizat prin porturi publicate, setează `AGENTMEMORY_III_CONFIG` la o configurație care se leagă la `0.0.0.0`. `iii-config.docker.yaml`-ul inclus în pachet este una dintre acestea: leagă `iii-http`, `iii-stream` și portul motorului la `0.0.0.0` și stochează starea sub `/data`, așa că montează acolo un volum scriibil. Păstrează `AGENTMEMORY_SECRET` setat și publică doar porturile de care ai nevoie, pe `127.0.0.1` sau în spatele unui proxy în care ai încredere.
+
+`docker-compose.yml`-ul acestui repository nu trece prin căutarea de configurație a CLI-ului: montează `iii-config.docker.yaml` la `/app/config.yaml`, iar containerul `iii-engine` pornește cu `--config /app/config.yaml`. [Șabloanele de implementare](../deploy/) cu un singur clic își scriu propria configurație `0.0.0.0` în entrypoint-urile lor.
+
+### Backend de stocare: file (implicit) vs redis
+
+`iii-state` și `iii-stream` folosesc implicit magazinul KV bazat pe fișiere, inclus în iii-engine: un fișier JSON per scope, ținut în memoria procesului motorului și rescris pe disc la un interval. Aceasta este valoarea implicită potrivită pentru o instalare locală cu un singur utilizator; un daemon partajat cu mai mulți scriitori concurenți obține, în schimb, scrieri reale per cheie, de la Redis, cu costul unui round-trip de rețea per operație (fiecare apel `state::*` se serializează tot pe o singură conexiune Redis, așa că aceasta schimbă lock-ul magazinului de fișiere cu un socket, nu cu paralelism).
+
+Setează `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) pentru a comuta ambii worker-i la adaptorul `redis` încorporat în iii-engine, care stochează fiecare cheie ca un câmp de hash Redis (`HSET`), în loc să rescrie un scope întreg la fiecare scriere:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` are implicit valoarea `file`; lăsat nesetat, comportamentul de astăzi rămâne neschimbat, iar o valoare nerecunoscută (orice altceva decât `file` sau `redis`) este o eroare de pornire, nu o trecere silențioasă la o valoare de rezervă. `/agentmemory/status` și pagina Health a vizualizatorului (rândul State store) raportează care backend este activ și dacă răspunde, niciodată URL-ul.
+
+**Doar `redis://` simplu.** Motorul fixat (0.22.1) își construiește clientul Redis fără suport TLS, așa că un URL `rediss://` (majoritatea ofertelor Redis administrate, precum Upstash, Redis Cloud și ElastiCache cu criptare în tranzit, sunt implicit doar-TLS) nu se poate conecta. Conexiunea este necriptată, așa că parola Redis și fiecare memorie stocată circulă pe fir în text clar: direcționează-te către un Redis local sau unul dintr-o rețea privată în care ai încredere. Pentru orice alt Redis, rulează un tunel criptat (stunnel, SSH sau un VPN) pe host-ul agentmemory, astfel încât saltul `redis://` simplu rămâne pe acel host, iar conexiunea din amonte a tunelului este criptată și autentificată. Dacă o parolă Redis conține un apostrof, codifică-l percent (`%27`); motorul expandează URL-ul în configurația YAML, înainte de a-l analiza (parse).
+
+**Un server Redis per `--instance`.** Prefixele de chei Redis ale motorului (`state:`, `stream::`) sunt fixe, așa că două instanțe agentmemory (`--instance 1`, `--instance 2`, ...) direcționate către aceeași bază de date își suprascriu reciproc datele. Un index de bază de date separat (`redis://localhost:6379/1`) ține datele stocate separate, dar motorul retransmite evenimentele live ale vizualizatorului pe un singur canal Redis pub/sub (`stream::events`), iar Redis pub/sub ignoră indexul bazei de date, așa că vizualizatorul fiecărei instanțe ar arăta totuși evenimentele live ale celeilalte. Dă fiecărei instanțe propriul server Redis (sau port), atunci când rulezi mai multe.
+
+**Ce rămâne la fel și ce diferă.** Fiecare funcționalitate a agentmemory funcționează pe Redis: sesiuni, observații, memorii (remember, supersede, evolve, forget), căutarea și loturile indexului, lecții, graful, log-ul de audit și scope-urile sale lunare, export și import, ștergerile de guvernanță, starea consolidării, instantaneul vizualizatorului și stream-ul său live, și monitorul de sănătate. Motorul stochează fiecare scope ca un singur hash Redis (`HSET`/`HGET`/`HGETALL`) și declanșează aceleași trigger-e de stare ca magazinul de fișiere. Trei diferențe ale motorului sunt gestionate în interiorul agentmemory:
+
+- Redis returnează înregistrările unui scope într-o ordine nefixată. agentmemory le sortează de la cele mai vechi (după timpul de creare din id-ul înregistrării, apoi după timestamp-ul ei), astfel încât listele, paginarea și fragmentele de export vin înapoi în aceeași ordine ca pe magazinul de fișiere.
+- Motorul aplică actualizările parțiale pe Redis într-un script Lua care transformă array-urile vide în obiecte vide. agentmemory aplică el însuși aceste actualizări (citire, modificare, scriere, sub un lock per cheie) pe Redis, astfel încât câmpuri precum `tags: []` rămân array-uri.
+- Verificarea veche a log-ului de audit citește scope-ul vechi din Redis, în loc să caute fișierul de pe disc al magazinului de fișiere.
+
+O diferență are nevoie de tine: **după ce Redis repornește, motorul oprește retransmiterea evenimentelor live** către vizualizator, până când agentmemory repornește. Datele sunt totuși salvate și citite normal. Monitorul de sănătate trimite un eveniment de test prin Redis la fiecare 30 de secunde; când acesta nu se întoarce, `/agentmemory/status` și pagina Health a vizualizatorului arată „Actualizările live nu ajung la vizualizator”, cu remedierea: repornește agentmemory. Dacă Redis este căzut, raportul de stare arată „Magazinul de stare nu răspunde” și cum să verifici asta (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Listarea unui scope foarte mare citește întregul hash într-un singur `HGETALL`, același cost ca atunci când magazinul de fișiere îl ține în memorie.
+
+**Setări Redis recomandate.** Politica implicită de instantanee `save 3600 1 300 100 60 10000` poate pierde minute de scrieri la un crash, mai rău decât fereastra de 5 secunde de flush a magazinului de fișiere. Setează `appendonly yes` pentru orice ți-ar părea rău să pierzi. Setează `maxmemory-policy noeviction`; `allkeys-lru` sau similare elimină silențios memorii, de îndată ce Redis atinge limita sa de memorie.
+
+O pornire nativă (non-Docker) și fiecare [șablon de implementare](../deploy/) cu un singur clic (acestea suprascriu `iii-config.yaml`-ul inclus și pornesc nativ) citesc `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` și le randează în `iii-config`-ul lansat. URL-ul în sine nu este niciodată scris în acel fișier randat, doar o referință `${AGENTMEMORY_REDIS_URL}`, pe care procesul motorului o expandează din propriul mediu, la pornire. Doar calea Docker Compose a acestui repository (`AGENTMEMORY_USE_DOCKER=1`, sau reluarea unui motor pornit deja în acest fel) montează `iii-config.docker.yaml` doar-pentru-citire și nu randează niciodată; `agentmemory start` avertizează când detectează această combinație. Schimbă acel fișier manual, urmând aceeași formă `name: redis` / `config: redis_url: ...` arătată în documentația worker-ilor [iii-state](https://workers.iii.dev/workers/iii-state) și [iii-stream](https://workers.iii.dev/workers/iii-stream), și direcționează `redis_url` către un Redis accesibil din container. `docker-compose.yml` transmite `AGENTMEMORY_REDIS_URL` în containerul motorului, așa că `redis_url: '${AGENTMEMORY_REDIS_URL}'` funcționează acolo și ține URL-ul în afara fișierului montat.
+
+Configurația randată ține URL-ul în afara `~/.agentmemory/data/iii-config.runtime.yaml`, dar worker-ul propriu de configurare al motorului persistă totuși valoarea *expandată* în `~/.agentmemory/config/iii-state.yaml` și `iii-stream.yaml`, odată ce pornește (expandarea `${VAR}` a iii-engine se întâmplă înainte ca acel worker să își stocheze seed-ul, iar el stochează valoarea rezolvată, nu referința). Tratează acel director ca ținând o credențială: `chmod 700 ~/.agentmemory` pe orice host partajat și preferă un utilizator ACL Redis cu scope limitat la ce are nevoie agentmemory, în locul credențialelor de administrator ale bazei de date.
+
+**Migrarea nu este automată.** Comutarea `AGENTMEMORY_STATE_BACKEND` începe de la un magazin gol pe fiecare parte; nimic nu copiază datele existente din file în Redis sau invers. Exportă din backend-ul pe care îl lași și importă în cel către care te muți. Acest lucru rulează identic sub bash și zsh (inclusiv `bash -u`). Un array precum `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` nu rulează identic: zsh păstrează header-ul ca un singur cuvânt malformat, unde bash îl împarte în două, așa că ambele cereri primesc 401, de câte ori `AGENTMEMORY_SECRET` este setat:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` acceptă și `?maxSessions=` și `?offset=`, pentru a fragmenta un corpus mare pe mai multe apeluri; `strategy` la import este `merge` (sigur implicit), `replace` sau `skip`.
+
+### Ce înlocuiește iii
+
+| Stivă tradițională | agentmemory folosește |
+|---|---|
+| Express.js / Fastify | Trigger-e HTTP iii |
+| SQLite / Postgres + pgvector | Stare KV iii + index vectorial în memorie |
+| SSE / Socket.io | Stream-uri iii (WebSocket) |
+| pm2 / systemd | Supervizarea worker-ilor de către motorul iii |
+| Prometheus / Grafana | iii OTEL + monitor de sănătate |
+| Sisteme de plugin-uri personalizate | `iii worker add ` |
+
+**225 fișiere sursă · ~54,000 LOC · 2,600+ teste · 312 funcții · 66 domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
+
+---
+
+
+
+### Furnizori LLM
+
+agentmemory detectează automat furnizorii din mediul tău. Un furnizor face disponibile operațiile susținute de LLM, dar configurarea furnizorului, de una singură, nu activează compresia observațiilor scrisă de LLM. Acea cale necesită atât un furnizor, cât și `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Furnizor | Configurare | Note |
+|----------|--------|-------|
+| **No-op (implicit)** | Nu necesită configurare | Compresia/rezumarea susținută de LLM este dezactivată. Compresia sintetică și reamintirea prin BM25 funcționează în continuare. Vezi `AGENTMEMORY_ALLOW_AGENT_SDK` mai jos, dacă te bazai anterior pe fallback-ul prin abonamentul Claude. |
+| API Anthropic | `ANTHROPIC_API_KEY` | Facturare per token |
+| MiniMax | `MINIMAX_API_KEY` | Compatibil Anthropic |
+| Gemini | `GEMINI_API_KEY` | Activează și embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Orice model |
+| API OpenAI | `OPENAI_API_KEY` | Implicit `gpt-5.6-luna`, suprascrie cu `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) sau `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Orice e compatibil cu API-ul OpenAI. Cost zero, rulează pe hardware-ul tău. Vezi [Modele locale](#local-models-ollama--lm-studio--vllm) mai jos. |
+| Fallback prin abonamentul Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Doar opt-in. Lansează sesiuni `@anthropic-ai/claude-agent-sdk`; obișnuia să cauzeze o recursivitate nelimitată a hook-ului Stop, așa că nu mai este implicit. |
+
+### Modele locale (Ollama / LM Studio / vLLM)
+
+agentmemory comunică cu orice server compatibil cu API-ul OpenAI, așa că orice expune `/v1/chat/completions` funcționează fără modificări de cod. Fără chei plătite, fără cloud, fără limite de rată (rate limits); rulează integral pe hardware-ul tău.
+
+**Ollama** (port implicit `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (port implicit `1234`):
+
+Deschide LM Studio → tab-ul Local Server → Start Server. Alege orice model de chat din selector (Qwen 3, gpt-oss, DeepSeek R1 etc.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: aceeași formă. Direcționează `OPENAI_BASE_URL` către orice URL expune serverul tău și setează `OPENAI_MODEL` la un nume pe care serverul tău îl va accepta.
+
+**Alegeri de model pentru munca de memorie**: compresia și rezumarea sunt sarcini scurte (<2K tokeni la intrare, <500 tokeni la ieșire), unde un model instruct de 7B este suficient. Recomandări:
+
+| Model | Dimensiune | De ce |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Opțiune implicită echilibrată pe o mașină cu 16 GB; puternic la extracție și text în formă de instrument |
+| `qwen3:4b` | ~2.6 GB | Cea mai mică opțiune rezonabilă; bun pentru compresie, mai slab la extracția de graf |
+| `qwen3-coder:30b` | ~19 GB | Cea mai bună alegere locală pentru sesiuni centrate pe cod (30B MoE, 3.3B active) pe hardware de 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Model general puternic, care se încadrează în 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Distilare de raționament; mai lent, dar cu extracții mai clare |
+
+Modelele Qwen 3 „gândesc” implicit și pot consuma întregul buget de tokeni pe raționament, înainte de orice output. Setează `AGENTMEMORY_LLM_NOTHINK=1` pentru a adăuga `/no_think` la prompturile de extracție din graf și crește `MAX_TOKENS` (16384 funcționează), dacă extracțiile se întorc vide.
+
+Modelele din clasa de raționament (în stil `o1`, cu blocuri ``) pot returna un `content` vid, cu un câmp `reasoning` pe care serverul tău local poate să nu îl expună. Dacă extracțiile se întorc vide, treci întâi la un model fără raționament. Variabila de mediu `OPENAI_REASONING_EFFORT=none` poate, de asemenea, să dezactiveze „gândirea” pe modelele de tip thinking din Ollama Cloud, care oglindesc schema de raționament a OpenAI.
+
+Embeddings locale vin ca o dependență opțională, dar nu sunt activate implicit. Setează `EMBEDDING_PROVIDER=local` pentru a opta pentru `Xenova/all-MiniLM-L6-v2` (384 dimensiuni). Prima cerere de embedding descarcă modelul; inferența este pe dispozitiv după aceea. Fără această setare sau o cheie de embedding la distanță, vectorii rămân dezactivați, `mem::search` folosește BM25, iar `smart-search` poate adăuga în continuare potriviri existente din graf.
+
+### Selecția modelului în funcție de cost
+
+Când compresia în fundal, scrisă de LLM, este activată, cu atât un furnizor, cât și `AGENTMEMORY_AUTO_COMPRESS=true`, aceasta rulează la fiecare observație, așa că alegerea modelului schimbă semnificativ cheltuiala lunară. Date de workload capturate: 635 de cereri / 888K tokeni / 35 de ore de utilizare activă, rulate pe trei modele OpenRouter, la prețurile din 2026-05-23.
+
+| Nivel | Model | Input / 1M | Output / 1M | Cost pentru cele 35h capturate | Note |
+|------|-------|------------|-------------|---------------------------|-------|
+| Recomandat | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Cel mai recent DeepSeek; cea mai ieftină alegere recomandată pentru workload-uri de compresie. |
+| Recomandat | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Calitate solidă de compresie + rezumare, la un cost de ~10× mai mic decât Sonnet. |
+| Recomandat | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Raționament puternic pe cod, dacă sesiunile tale sunt puternic centrate pe cod. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Același preț de listă ca rularea măsurată Sonnet 4.6; preț introductiv de $2/$10 până la 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Nivel de top (flagship); costisitor pentru muncă de fundal permanent activă. |
+| Evită | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Model din clasa de top (flagship); cheltuială excesivă pentru compresie. |
+
+Rândurile măsurate provin din rularea capturată; rândurile (est.) scalează același mix de tokeni după prețul de listă al fiecărui model.
+
+agentmemory afișează un avertisment la runtime, când `OPENROUTER_MODEL` se potrivește cu un model de nivel premium. Setează `AGENTMEMORY_SUPPRESS_COST_WARNING=1` pentru a-l dezactiva, odată ce ai făcut o alegere informată.
+
+Compromisul calitate vs cost pentru munca de memorie: compresia este o sarcină de rezumare, cu bare de calitate relativ permisive (agentul re-citește rezumatul, nu utilizatorul). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ajung, pe această sarcină, la o diferență neglijabilă față de Sonnet, costând totodată de 10-70× mai puțin. Păstrează modelele de nivel premium pentru interogările pe care le citești direct.
+
+Surse: [Prețurile OpenRouter pentru Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [Notele de preț DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Memorie multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+În configurațiile multi-agent, unde mai multe roluri partajează un singur server agentmemory (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` etichetează fiecare scriere cu rolul care a făcut-o. `AGENTMEMORY_AGENT_SCOPE` controlează dacă reamintirea filtrează după acea etichetă.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Două moduri:
+
+| Mod | Etichetează scrierile | Filtrează reamintirea | Când să-l folosești |
+|------|------------|---------------|--------------|
+| `shared` (implicit) | da | nu | Context între agenți, cu traseu de audit. Architect poate vedea ce a notat developer, dar fiecare rând înregistrează cine a spus-o. |
+| `isolated` | da | da | Separare strictă. Architect nu vede niciodată observațiile / memoriile / sesiunile lui developer. |
+
+Ce se etichetează, când `AGENT_ID` este setat: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rolul circulă de la `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Ce se filtrează în modul isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Fiecare endpoint acceptă `?agentId=`, pentru a suprascrie per cerere, și `?agentId=*`, pentru a renunța complet la scope-ul din mediu. `/memories` acceptă și `?includeOrphans=true`, pentru a scoate la suprafață memoriile dinainte de AGENT_ID, al căror `agentId` este nedefinit.
+
+Suprascriere per apel, la nivelul SDK / REST: fiecare endpoint care modifică date (`/session/start`, `/remember`) acceptă un câmp `agentId` în corpul cererii, care are prioritate față de mediu. Util pentru runtime-uri care direcționează multe roluri printr-un singur proces de server. Instrumentul MCP `memory_save` expune același câmp `agentId`, serverul stdio independent transmite atât `agentId`, cât și `project`, iar memoriile salvate duc `agentId` în indexul de căutare, astfel încât căutarea scopată pe agent acoperă atât memoriile, cât și observațiile.
+
+Când `AGENT_ID` nu este setat, memoria rămâne fără scope (comportament legacy, fără etichete, fără filtre).
+
+### Porturi
+
+agentmemory + iii-engine se leagă implicit la patru porturi. Dacă o repornire eșuează cu `port in use`, acest tabel îți spune ce proces să cauți.
+
+| Port | Proces | Scop | Suprascriere prin variabilă de mediu |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | API REST + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker intern de stream-uri (consumat de agentmemory + vizualizator) | `III_STREAM_PORT` (preferat) sau `III_STREAMS_PORT` (vechi/legacy) |
+| `3113` | agentmemory | Vizualizator în timp real (`http://localhost:3113`) | `III_VIEWER_PORT` sau `AGENTMEMORY_VIEWER_URL` pentru URL-ul raportat |
+| `49134` | iii-engine | WebSocket; worker-ii se înregistrează aici, telemetria OTel circulă prin el | `III_ENGINE_PORT` sau `III_ENGINE_URL` |
+
+`--port ` schimbă ancora REST și derivă stream-urile `N+1`, vizualizatorul `N+2` și WebSocket-ul motorului `N+46023`, doar unde portul sau URL-ul explicit corespunzător de mai sus nu este setat. Nu creează un namespace de ciclu de viață izolat. Folosește `--instance 1` pentru un al doilea daemon; acesta folosește ancora 3211, implicit `3211/3212/3213/49234`, și primește un director separat de date și ciclu de viață, `instance-1`. Instanțele 1 până la 50 urmează același model.
+
+Motorul fixat pornește cu `--no-update-check` (fără verificări de actualizare sau de avertismente de securitate față de GitHub, la pornire) și cu telemetria anonimă de utilizare a iii dezactivată: agentmemory setează `III_TELEMETRY_ENABLED=false` pentru motorul pe care îl lansează, cu excepția cazului în care exporți tu însuți variabila, iar fișierul compose inclus face același lucru.
+
+Curățarea proceselor rămase, când porturile rămân legate după o rulare care s-a prăbușit (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
+```
+
+`agentmemory stop` încheie curat atât worker-ul, cât și pidfile-ul motorului, la o oprire nativă controlată (graceful). În modul Docker, golește (flush) worker-ul nativ, oprește exact containerul de motor validat și păstrează atât containerul, cât și montarea sa `/data`, pentru o repornire fără pierderi; următoarea pornire validează și reia același container. Dezinstalarea susținută de Docker necesită `agentmemory remove --keep-data`: aceasta elimină fișierele partajate gestionate de agentmemory, păstrând în același timp containerul validat, montarea sa de date și înregistrarea de ciclu de viață necesară pentru a le recupera. Ștergerea distructivă a datelor Docker este lăsată intenționat în sarcina operatorului, după un backup. CLI-ul refuză, de asemenea, să adopte sau să semnaleze deținătorii de porturi Docker sau VM (backend-ul Docker, vpnkit, colima) ca motor nativ, cu excepția cazului în care este transmis `--force`. Curățarea manuală de mai sus este doar pentru cazul post-crash, în care nu rămâne niciun pidfile.
+
+### Fișierul de configurare
+
+Pune configurația de runtime a agentmemory în `~/.agentmemory/.env`, în loc să exporți variabile în fiecare shell. Dacă vizualizatorul arată un indiciu de configurare, precum `export ANTHROPIC_API_KEY=...`, copiază-l în acest fișier ca `ANTHROPIC_API_KEY=...`, fără prefixul `export`, apoi repornește agentmemory.
+
+Variabilele de mediu ale procesului funcționează în continuare și au prioritate față de valorile din fișier.
+
+Pe Windows, același fișier se află la `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Pentru a testa cu un abonament Claude Code Pro/Max, în loc de o cheie API, optează explicit:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Compresia observațiilor scrisă de LLM necesită ambele linii: acces la un furnizor LLM (inclusiv acest fallback explicit prin abonament) și `AGENTMEMORY_AUTO_COMPRESS=true`. Un furnizor, de unul singur, lasă în vigoare calea implicită de compresie sintetică.
+
+Consolidarea (noduri de graf, lecții, cristale) este activă implicit, de câte ori este configurat un furnizor LLM. Renunță explicit cu `CONSOLIDATION_ENABLED=false`, dacă vrei o funcționare fără LLM. Extracția din graf este un flag separat:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Variabile de mediu
+
+Creează `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 de endpoint-uri pe portul `3111`. API-ul REST se leagă implicit la `127.0.0.1`. Endpoint-urile protejate necesită `Authorization: Bearer `, iar endpoint-urile de sincronizare mesh necesită un `AGENTMEMORY_SECRET` setat explicit pe ambii parteneri (peers).
+
+**Autentificarea este activată implicit.** Când `AGENTMEMORY_SECRET` nu este setat (în shell sau în `~/.agentmemory/.env`), serverul generează un secret aleatoriu la prima pornire și îl stochează în `~/.agentmemory/secret`, cu modul `0600`. Fiecare client inclus îl citește de acolo, când vorbește cu un server local: CLI-ul, vizualizatorul, hook-urile din `plugin/scripts`, serverul MCP și shim-ul `@agentmemory/mcp`, configurațiile scrise de `agentmemory connect`, și integrările incluse OpenCode, Pi, OpenClaw, Hermes și filesystem-watcher. Secretul stocat este trimis doar către URL-uri loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explicit are întotdeauna prioritate, iar clienții la distanță au nevoie, în continuare, să îl aibă setat. Docker și entrypoint-urile din `deploy/` își generează și exportă deja propriul secret. Pentru a apela API-ul manual:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Regulile de cerere pentru scrieri.** Cererile `POST`, `PUT`, `PATCH` și `DELETE` către API-ul REST și vizualizator trebuie să trimită `Content-Type: application/json` (un parametru `charset` este acceptabil), de câte ori au un corp, și un header `Origin`, atunci când este prezent, trebuie să fie o origine loopback pentru portul REST sau vizualizator configurat, sau să fie listat în `VIEWER_ALLOWED_ORIGINS` (separate prin virgulă, de ex. `https://memory.example.com`). Clienții care nu trimit niciun header `Origin` (CLI, hook-uri, MCP, curl, server-la-server) nu sunt afectați. Vizualizatorul acceptă și propria sa origine.
+
+**Căi de fișiere.** Endpoint-urile care citesc sau scriu fișiere (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) acceptă doar căi aflate sub `~/.agentmemory`, directorul de date al instanței, sau un director listat în `AGENTMEMORY_IMPORT_ROOT` (separă mai multe cu `:`, sau `;` pe Windows). `/replay/import-jsonl` acceptă și valoarea sa implicită, `~/.claude/projects`. `/obsidian/export` rămâne în interiorul `AGENTMEMORY_EXPORT_ROOT`, iar `/migrate` în interiorul `~/.agentmemory`. Symlink-urile sunt rezolvate înainte de fiecare verificare.
+
+**Eliminarea secretelor.** Cheile API, token-urile bearer, blocurile de chei private PEM și credențialele încorporate în URL-uri (`scheme://user:password@host`) sunt redactate înainte ca textul să fie stocat, pe fiecare cale de scriere: observații, remember, evolve, sloturi, lecții, acțiuni, sketch-uri, semnale, checkpoint-uri, importuri, reluare jsonl, sincronizare mesh, partajări de echipă, output de compresie și rezumat, cristale și noduri de graf.
+
+
+Endpoint-uri cheie
+
+| Metodă | Cale | Descriere |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Verificare de sănătate (mereu publică) |
+| `GET` | `/agentmemory/status` | Ce nu este în regulă și cum se remediază (HTML pentru browsere, JSON altfel) |
+| `GET` | `/agentmemory/viewer/snapshot` | Tot ce arată vizualizatorul, într-un singur răspuns |
+| `POST` | `/agentmemory/session/start` | Pornește sesiunea + obține context |
+| `POST` | `/agentmemory/session/end` | Termină sesiunea |
+| `POST` | `/agentmemory/observe` | Captează o observație (vezi livrarea capturii mai jos) |
+| `GET` | `/agentmemory/capture` | Inbox-ul de captare, dead letters și coada offline (spool) |
+| `POST` | `/agentmemory/capture/retry` | Reîncearcă captările dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Trimite acum coada offline locală |
+| `POST` | `/agentmemory/smart-search` | Căutare hibridă |
+| `POST` | `/agentmemory/context` | Generează context |
+| `POST` | `/agentmemory/remember` | Salvează în memoria pe termen lung |
+| `POST` | `/agentmemory/forget` | Șterge observații |
+| `POST` | `/agentmemory/enrich` | Context de fișier + memorii + bug-uri |
+| `GET` | `/agentmemory/profile` | Profilul proiectului |
+| `GET` | `/agentmemory/export` | Exportă toate datele |
+| `POST` | `/agentmemory/import` | Importă din JSON |
+| `POST` | `/agentmemory/graph/query` | Interogarea grafului de cunoștințe |
+| `POST` | `/agentmemory/graph/compact` | Trimite la o dimensiune mai mică proveniența supradimensionată a grafului |
+| `POST` | `/agentmemory/team/share` | Partajează cu echipa |
+| `GET` | `/agentmemory/audit` | Traseul de audit |
+
+Lista completă a endpoint-urilor: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Livrarea capturii.** Hook-urile trimit fiecare observație o singură dată către `POST /agentmemory/observe`, cu un `eventId`. Acesta este propriul id al host-ului pentru apel, atunci când payload-ul are unul (de exemplu `tool_use_id` al lui Claude Code), altfel un hash al sesiunii, tipului de hook, numelui instrumentului, input-ului, output-ului și timestamp-ului host-ului. Serverul scrie evenimentul într-un inbox de captare din state store, stochează observația, apoi elimină intrarea din inbox. Codul de stare spune ce s-a întâmplat:
+
+| Status | Câmpul `status` | Semnificație |
+|---|---|---|
+| `201` | `accepted` | Stocat. `observationId` este noua observație. |
+| `202` | `accepted` (`state: "retrying"`) | Acceptat, dar stocarea a eșuat. Serverul reîncearcă, inclusiv după o repornire. |
+| `200` | `duplicate` | Acest `eventId` a fost deja acceptat. `observationId` este observația existentă; nu se stochează nimic nou. |
+| `400` / `422` | `rejected` | Payload invalid, sau stocarea a eșuat definitiv (evenimentul este păstrat ca dead letter). |
+| `503` | `rejected` (`retryable: true`) | Inbox-ul este plin (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook-urile pun evenimentul în coadă (spool) și îl trimit mai târziu. |
+
+Evenimentele care eșuează sunt reîncercate la fiecare `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s), cu backoff dublat, până la `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Evenimentele care încă eșuează rămân în inbox ca dead letters, sunt listate pe `/agentmemory/status` și pe pagina Health a vizualizatorului, și pot fi reîncercate cu `POST /agentmemory/capture/retry` (`{"eventId": "..."}` sau `{"all": true}`). ID-urile evenimentelor acceptate sunt reținute timp de `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 de ore, cel mult `AGENTMEMORY_CAPTURE_EVENTS_MAX` id-uri), astfel încât un hook reluat după un timeout sau o repornire este stocat o singură dată, în timp ce două apeluri de instrument separate, cu propriile lor id-uri de host, sunt stocate de două ori, chiar dacă conținutul lor este identic. Când o observație este ștearsă (forget, ștergerea sesiunii, eviction, uitare automată sau un import care înlocuiește magazinul), evenimentul ei este marcat ca șters înainte ca observația să fie eliminată, astfel încât o reluare a acelui eveniment în aceeași fereastră este tratată ca un duplicat și nu stochează nimic. State store-ul scrie pe disc la fiecare 2 secunde, așa că un eveniment confirmat poate fi încă doar în memorie, pentru o clipă. Pentru a acoperi acest lucru, fiecare răspuns `2xx` poartă și `bootId`-ul serverului (nou la fiecare pornire), `acceptedAt` și `durableAfterMs` (intervalul de salvare plus 1.5 s pe magazinul de fișiere, 1.5 s pe redis, unde persistența este setarea operatorului). Hook-urile păstrează evenimentul în coada locală (spool), până trece acea fereastră, și îl șterg la un apel ulterior, fără o altă cerere. Dacă `bootId`-ul s-a schimbat până atunci, serverul a repornit, așa că hook-ul trimite din nou evenimentul, cu același `eventId`; un eveniment care a ajuns deja pe disc nu este stocat de două ori. Serverul trimite el însuși astfel de evenimente, la pornire și la fiecare interval de reîncercare, așa că o repornire nu pierde nimic, chiar dacă niciun hook nu mai rulează după aceea. Hook-urile mai vechi ignoră câmpurile suplimentare, iar hook-urile noi, în fața unui server mai vechi, elimină evenimentul la `2xx`, ca înainte.
+
+Când serverul este căzut, nu răspunde la timp sau returnează un 5xx, hook-ul adaugă observația într-un fișier local de coadă (spool), `/capture-spool/-.jsonl` (suprascrie directorul cu `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Fișierul este privat pentru utilizatorul tău (mod 600), secretele sunt redactate la fel cum le redactează serverul, ține cel mult `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) și elimină intrările mai vechi de `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Când este plin, intrările noi sunt eliminate și contorizate, iar `/agentmemory/status` raportează asta. Hook-ul tot iese cu 0, în limita sa de timp, și nu adaugă nicio cerere, când serverul este sănătos. Coada este trimisă la următoarea pornire și de către primul hook care ajunge din nou la server, într-un proces de fundal, astfel încât agentul nu așteaptă. ID-urile de eveniment fac acest lucru sigur: o observație care a ajuns deja înainte de un timeout nu este stocată de două ori. `npx @agentmemory/agentmemory capture` arată coada și inbox-ul serverului, `--drain` trimite coada acum, iar `GET /agentmemory/capture` returnează aceleași date, ca JSON. Setează `AGENTMEMORY_CAPTURE_SPOOL=false` pentru a dezactiva coada.
+
+**Compactarea provenienței grafului.** Fiecare nod și muchie din graful de cunoștințe ține id-urile celor mai recente 32 de observații din care provine. Magazinele scrise înainte de acel plafon pot ține mii de id-uri per nod „fierbinte” (hot), ceea ce face căutarea în graf și vizualizatorul lente, sau blochează worker-ul. agentmemory remediază asta de la sine: la prima pornire de după actualizare, trimite fiecare nod, muchie, muchie suprascrisă (istoricul temporal al grafului) și instantaneul din cache la plafon, în fundal, în felii mici, cu o pauză între ele, astfel încât căutarea, captarea și vizualizatorul continuă să funcționeze. Își salvează progresul, reia după o repornire și nu mai rulează niciodată, odată terminat. `/agentmemory/status` și pagina Health a vizualizatorului îl arată ca în așteptare (pending), în curs (running) (cu scope-ul și poziția curente), finalizat (done) sau eșuat (failed). Setează `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` pentru a-l dezactiva.
+
+Pentru a-l rula manual, apelează `POST /agentmemory/graph/compact`. Acesta traversează indecșii de nume și de chei de muchie, în loc să listeze fiecare nod și muchie, și este sigur de rulat din nou.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Pe un magazin mare, sau când apelul returnează 504, rulează-l în felii. Trimite `scope` (`nodes`, `edges` sau `history`), `offset` și `limit`, apoi apelează din nou cu `nextOffset`-ul returnat, până devine `null`. Fă asta pentru `nodes`, `edges` și `history`, și termină cu un singur apel `{"scope":"snapshot"}`, pentru că o rulare pe felii nu atinge instantaneul din cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Cerințe preliminare:** Node.js >= 20, cu npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 sau Docker. Instalarea automată a motorului pe macOS/Linux necesită, de asemenea, `curl`, un `sh` POSIX și `tar`; Windows nativ folosește `iii.exe`-ul fixat manual, WSL2 sau Docker Desktop.
+
+
+
+[Apache-2.0](../LICENSE)
diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md
index 0e6f43df53..22d7188106 100644
--- a/READMEs/README.ru-RU.md
+++ b/READMEs/README.ru-RU.md
@@ -7,22 +7,43 @@
Ваш агент программирования помнит всё. Больше не нужно объяснять заново.
Built on iii engine
- Постоянная память для Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode и любого MCP-клиента.
+ Постоянная память для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode и любого MCP-клиента.
- Этот gist расширяет шаблон LLM Wiki от Karpathy: confidence-оценкой, жизненным циклом, графами знаний и гибридным поиском — agentmemory является его реализацией.
+ Этот гист расширяет шаблон LLM Wiki от Karpathy: оценкой уверенности, жизненным циклом, графами знаний и гибридным поиском — agentmemory является его реализацией.
@@ -50,7 +71,7 @@
-
+
@@ -73,24 +94,36 @@
---
-## Install
+## Установка
-Одна команда:
+Требования:
+
+- Node.js 20 или новее, с npm и npx (`node -v`, `npm -v` и `npx -v`).
+- Автоматическая установка iii-engine на macOS/Linux также требует `curl`, POSIX-совместимый `sh` и `tar`. Минимальные образы, такие как `node:20-slim`, могут не включать их.
+- Нативный Windows требует, чтобы закреплённый `iii.exe` версии iii-engine v0.22.1 был установлен вручную. WSL2 или Docker Desktop — другие поддерживаемые варианты.
+
+Каноническая команда установки с нуля:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-Первый запуск — это интерактивная настройка: выберите агентов для подключения (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), выберите LLM-провайдера или останьтесь без ключей — и она заполнит конфиг, запустит сервер памяти на `:3111` и предложит установить пакет глобально, чтобы простая команда `agentmemory` дальше работала везде.
+Первый запуск — это интерактивная настройка: вы выбираете агентов для подключения (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), выбираете LLM-провайдера или остаётесь без ключей, после чего она заполняет конфиг, запускает сервер памяти и его закреплённый iii engine и предлагает установить пакет глобально, чтобы простая команда `agentmemory` дальше работала везде. `-y` принимает запрос npx о пакете, а `@latest` избегает устаревшего закешированного релиза. Провайдер делает доступными функции на базе LLM, но сжатие наблюдений, написанное LLM, запускается только тогда, когда дополнительно установлен `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Режим без ключей отключает векторные эмбеддинги. `memory_recall` (путь `mem::search`) использует BM25, а `memory_smart_search` может также сливать структурные совпадения из графа, если граф-данные уже существуют. Чтобы получить бесплатный семантический recall на устройстве, задайте `EMBEDDING_PROVIDER=local` в `~/.agentmemory/.env` и перезапустите. Первый запрос эмбеддинга скачивает `Xenova/all-MiniLM-L6-v2`; после этой первоначальной загрузки модели инференс выполняется локально.
-Затем убедитесь, что recall работает, и выдайте агенту его skill'ы:
+Локальный runtime использует четыре порта: `3111` для REST/MCP HTTP, `3112` для iii-стримов, `3113` для просмотрщика и `49134` для WebSocket iii-воркера. Постоянное состояние iii хранится в `~/Library/Application Support/agentmemory` на macOS, в `$XDG_DATA_HOME/agentmemory` или `~/.local/share/agentmemory` на Linux и в `%APPDATA%\agentmemory` на Windows. Используйте `--data-dir ` или `AGENTMEMORY_DATA_DIR`, чтобы переопределить его, и используйте одно и то же значение при каждом перезапуске. Для обратной совместимости существующий `./data/state_store.db` или `./data/iii-config.yaml` имеет приоритет над значением по умолчанию для платформы для инстанса 0; явный флаг или переопределение через переменную окружения всё равно выигрывает.
+
+Затем убедитесь, что recall работает, и дайте агенту его skill'ы:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
-Предпочитаете, чтобы всё это сделал агент программирования? Передайте ему одну инструкцию:
+Поисковые запросы по ключевым словам должны находить совпадения в режиме без ключей по умолчанию через BM25. Запрос `database performance optimization` из демо намеренно семантический и может возвращать ноль результатов, пока не настроен провайдер эмбеддингов.
+
+Предпочитаете, чтобы всё это сделал агент программирования? Дайте ему одну инструкцию:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
@@ -99,32 +132,32 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
Windows
-Быстрый путь — WSL2. Нативная установка движка на Windows выполняется вручную (примерно 10–20 минут), а `agentmemory connect` там пока не поддерживается. Пошаговая инструкция — в [заметках о Windows](#windows).
+Самый быстрый путь — WSL2. Нативная установка движка на Windows требует скачать закреплённый ZIP-архив v0.22.1 и вручную распаковать `iii.exe`; CLI не распаковывает его автоматически. Docker Desktop также поддерживается. Пошаговая инструкция — в разделе [заметки о Windows](#windows).
-Глобальная установка / EACCES
+Global install / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+Команда npx выше остаётся каноническим способом установки с нуля и избегает проблем с правами доступа к глобальному префиксу.
+
-npx выдаёт старую версию
+npx отдаёт старую версию
-npx кеширует пакеты по версиям. Принудительно возьмите свежий через `npx -y @agentmemory/agentmemory@latest` или однократно очистите кеш: `rm -rf ~/.npm/_npx` (macOS/Linux; на Windows удалите `%LOCALAPPDATA%\npm-cache\_npx`).
+npx кеширует пакеты по версиям. Принудительно возьмите свежую версию через `npx -y @agentmemory/agentmemory@latest`, либо однократно очистите кеш командой `rm -rf ~/.npm/_npx` (macOS/Linux; на Windows удалите `%LOCALAPPDATA%\npm-cache\_npx`).
-Уже запущен собственный движок iii
+Уже запущен собственный iii engine
-agentmemory закреплён на iii-engine v0.11.2 и не подключится к другой версии (воркер не умеет говорить на протоколе другого движка). Остановите другой движок и запустите `npx -y @agentmemory/agentmemory@latest` — он установит и запустит закреплённый v0.11.2 в `~/.agentmemory/bin`, не трогая ваш собственный `iii`.
+agentmemory закреплён на iii-engine v0.22.1 и не подключится к другой версии (воркер не умеет говорить на протоколе другого движка). Остановите другой движок, затем запустите `npx -y @agentmemory/agentmemory@latest`. Он установит и запустит закреплённую версию v0.22.1 в `~/.agentmemory/bin`, не трогая ваш собственный `iii`.
@@ -132,110 +165,170 @@ agentmemory закреплён на iii-engine v0.11.2 и не подключи
-agentmemory работает с любым агентом, поддерживающим хуки, MCP или REST API. Все агенты используют один и тот же сервер памяти.
+agentmemory работает с любым агентом, который поддерживает хуки, MCP или REST API. Все агенты используют один и тот же сервер памяти.
- Работает с любым агентом, который говорит на MCP или HTTP. Один сервер — общая память для всех.
+ Работает с любым агентом, который говорит на MCP или HTTP. Один сервер — память общая для всех них.
---
-Вы заново объясняете архитектуру в каждой сессии. Вы заново находите те же баги. Вы заново обучаете агента тем же предпочтениям. Встроенная память (CLAUDE.md, .cursorrules) упирается в 200 строк и устаревает. agentmemory это решает. Он тихо собирает то, что делает ваш агент, сжимает это в индексируемую память и подмешивает нужный контекст при старте следующей сессии. Одна команда. Работает между агентами.
+Вы объясняете одну и ту же архитектуру в каждой сессии. Вы заново находите одни и те же баги. Вы заново учите агента тем же предпочтениям. Встроенная память (CLAUDE.md, .cursorrules) упирается в потолок 200 строк и устаревает. agentmemory решает это. Он тихо фиксирует, что делает ваш агент, сжимает это в память, доступную для поиска, и подмешивает нужный контекст при старте следующей сессии. Одна команда. Работает между агентами.
-**Что меняется:** В сессии 1 вы настраиваете JWT-аутентификацию. В сессии 2 просите добавить rate limiting. Агент уже знает, что аутентификация использует middleware jose в `src/middleware/auth.ts`, что ваши тесты покрывают валидацию токенов, и что вы выбрали jose, а не jsonwebtoken, из-за совместимости с Edge — без повторных объяснений и без копирования-вставки.
+**Что меняется:** в сессии 1 вы настраиваете аутентификацию JWT. В сессии 2 вы просите добавить rate limiting. Агент уже знает, что ваша аутентификация использует middleware jose в `src/middleware/auth.ts`, что ваши тесты покрывают валидацию токенов и что вы выбрали jose вместо jsonwebtoken из-за совместимости с Edge — без повторных объяснений и без копирования-вставки.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **Новое в v0.9.0** — Лендинг по адресу [agent-memory.dev](https://agent-memory.dev), коннектор файловой системы (`@agentmemory/fs-watcher`), автономный MCP теперь проксирует к работающему серверу, поэтому хуки и просмотрщик согласованы, политика аудита кодифицирована для каждого пути удаления, проверка состояния больше не помечает `memory_critical` на маленьких Node-процессах. Полные заметки в [CHANGELOG.md](../CHANGELOG.md#090--2026-04-18).
+По умолчанию agentmemory хранит состояние iii-engine за пределами репозитория, из которого вы его запускаете: `~/Library/Application Support/agentmemory` на macOS, `$XDG_DATA_HOME/agentmemory` или `~/.local/share/agentmemory` на Linux и `%APPDATA%\agentmemory` на Windows. Существующий устаревший `./data/state_store.db` или `./data/iii-config.yaml` переиспользуется для инстанса 0 раньше, чем это значение по умолчанию для платформы. Чтобы явно выбрать расположение, передайте `--data-dir ` или задайте `AGENTMEMORY_DATA_DIR`; любая явная настройка имеет приоритет над устаревшим автоопределением:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Нативный запуск и запуск в Docker используют один и тот же вычисленный каталог на хосте; Docker монтирует его в `/data`. `--instance 1` добавляет `instance-1` к вычисленному каталогу и выбирает отдельный квартет портов по умолчанию `3211/3212/3213/49234`.
+
+Заметки о последнем релизе: [CHANGELOG.md](../CHANGELOG.md).
---
@@ -247,43 +340,43 @@ npx @agentmemory/agentmemory
### Точность извлечения
-**coding-agent-life-v1** (внутренний корпус, воспроизводимо в sandbox)
+**coding-agent-life-v1** (собственный корпус, воспроизводимый в sandbox)
-| Адаптер | P@5 | R@5 | Top-5 hit rate | p50-задержка |
+| Адаптер | P@5 | R@5 | Top-5 hit rate | p50 задержка |
|---|---|---|---|---|
-| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 мс |
-| Базовый grep | 0.227 | 0.967 | 15 / 15 | 0 мс |
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
-100 % попаданий в top-5 на **математическом потолке P@5** для этого корпуса (0.240, см. scorecard). Hybrid извлекает каждую gold-сессию; grep промахивается на 1 из 2 gold в мультисессионном темпоральном запросе. Выигрыш — это **recall + темпоральность**, а не суммарная точность. Этот бенчмарк маленький и разреженный по gold; более крупный LongMemEval-S ниже различает лучше. Полная разбивка по типам и заметка о поправке: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+100% попаданий в top-5 на **математическом потолке P@5** для этого корпуса (0.240, см. scorecard). Hybrid извлекает каждую gold-сессию; grep промахивается на 1 из 2 gold в мультисессионном темпоральном запросе. Прирост даёт **recall + temporal**, а не суммарная точность. Этот бенчмарк маленький и разреженный по gold; более крупный LongMemEval-S ниже различает лучше. Полная разбивка по типам и заметка о поправке: [`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%** |
-| Fallback только BM25 | 86.2% | 94.6% | 71.5% |
+| Только BM25 (fallback) | 86.2% | 94.6% | 71.5% |
### Экономия токенов
-| Подход | Токенов в год | Стоимость в год |
+| Подход | Токенов/год | Стоимость/год |
|---|---|---|
-| Вставлять весь контекст | 19,5М+ | Невозможно (выходит за окно) |
-| LLM-резюме | ~650K | ~500 $ |
-| **agentmemory** | **~170K** | **~10 $** |
-| agentmemory + локальные эмбеддинги | ~170K | **0 $** |
+| Вставка полного контекста | 19.5M+ | Невозможно (превышает окно) |
+| Сжатие LLM | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + локальные эмбеддинги | ~170K | **$0** |
-> Модель эмбеддингов: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+> Модель эмбеддингов: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
-**Воспроизведите локально:** [`eval/README.md`](../eval/README.md) — harness с подключаемыми адаптерами для LongMemEval `_s` (публичный, 500 вопросов) и `coding-agent-life-v1` (внутренний корпус из 15 сессий). Адаптеры grep / vector / agentmemory сравниваются бок о бок, вывод NDJSON, опубликованные scorecard'ы попадают в [`docs/benchmarks/`](../docs/benchmarks/).
+**Воспроизвести локально:** [`eval/README.md`](../eval/README.md) — харнесс со сменными адаптерами для LongMemEval `_s` (публичные 500 вопросов) + `coding-agent-life-v1` (собственный корпус из 15 сессий). Адаптеры grep / вектор / agentmemory оцениваются бок о бок, вывод в NDJSON, опубликованные scorecard-отчёты попадают в [`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).
+**Сочетается с [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).
---
@@ -317,17 +410,17 @@ npx @agentmemory/agentmemory
@@ -450,7 +543,7 @@ npx @agentmemory/agentmemory
Заметка о бенчмарках: только R@5 agentmemory — наш собственный замер (LongMemEval-S, воспроизводимо из benchmark/COMPARISON.md). Цифры mem0 и Letta — их опубликованные результаты LoCoMo (другой датасет); цифры MemPalace, supermemory, TencentDB (PersonaMem) и oracleagentmemory — самозаявленные вендорами значения, которые мы независимо не воспроизводили (прогон oracleagentmemory использовал GPT-5.5 против Oracle AI Database). Показаны рядом только для ориентира, это не сравнение лоб в лоб на одинаковых данных. Количество звёзд приблизительно и меняется со временем.
-**Более новые участники**, которых стоит знать; подробное сравнение — в [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+**Более новые участники**, которых стоит знать, подробно сравниваются в [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
| Система | ⭐ | Особенность |
|--------|---|-------|
@@ -463,29 +556,54 @@ npx @agentmemory/agentmemory
-Совместимость: этот релиз нацелен на стабильный `iii-sdk` `^0.11.0` и iii-engine v0.11.x.
+Совместимость: этот релиз рассчитан на `iii-sdk` 0.22.1 и закрепляет iii-engine v0.22.1.
### Попробуйте за 30 секунд
```bash
# Terminal 1: start the server
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
-npx @agentmemory/agentmemory demo
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` заполняет 3 реалистичные сессии (аутентификация JWT, исправление N+1-запроса, rate limiting) и запускает по ним поиск. Установки без ключей отключают векторы, поэтому запросы по ключевым словам `mem::search` должны находить совпадения через BM25, а `database performance optimization` может возвращать ноль. `smart-search` может дополнительно возвращать структурные совпадения из графа, если граф-данные существуют. Чтобы семантический запрос нашёл исправление N+1 через векторы, задайте `EMBEDDING_PROVIDER=local`, перезапустите и дайте первой загрузке модели завершиться.
+
+Откройте `http://localhost:3113`, чтобы смотреть, как память строится в реальном времени.
+
+### Проверка новой установки и устойчивости после перезапуска
+
+При запущенном сервере проверьте REST, health, просмотрщик и статус runtime на основе iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
```
-`demo` заполняет 3 реалистичные сессии (JWT-аутентификация, исправление N+1-запроса, rate limiting) и запускает по ним семантический поиск. Вы увидите, как находится «N+1 query fix», когда вы ищете «database performance optimization» — keyword-сопоставление так не умеет.
+Стартовая панель готовности учитывает все четыре порта: REST/MCP HTTP на 3111, iii-стримы на 3112, просмотрщик на 3113 и WebSocket iii-воркера на 49134. `status` подтверждает состояние agentmemory и активный режим провайдера/эмбеддингов. Сохраните пробный объект и убедитесь, что он находится поиском:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
-Откройте `http://localhost:3113`, чтобы видеть построение памяти в реальном времени.
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Затем выполните `npx -y @agentmemory/agentmemory@latest stop`, снова запустите каноническую команду в Terminal 1, подождите `/agentmemory/livez` и повторите поиск. Пробный объект должен всё ещё возвращаться. Если вы указывали собственный `--data-dir`, передайте тот же каталог при перезапуске.
### Повседневные команды
-Установка и настройка описаны в разделе [Install](#install) выше (первый запуск проведёт вас по шагам). В повседневной работе:
+Установка и настройка описаны в разделе [Установка](#install) выше (первый запуск проведёт вас по шагам). В повседневной работе:
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -493,43 +611,43 @@ agentmemory remove # uninstall everything we created
### Воспроизведение сессий
-Каждую сессию, которую записывает agentmemory, можно воспроизвести. Откройте просмотрщик, выберите вкладку **Replay** и пролистывайте таймлайн: промпты, вызовы инструментов, результаты вызовов и ответы отображаются как отдельные события с play/pause, регулировкой скорости (от 0,5x до 4x) и горячими клавишами (пробел переключает, стрелки — пошаговое перемещение).
+Каждую сессию, которую записывает agentmemory, можно воспроизвести. Откройте просмотрщик, выберите вкладку **Replay** и пролистывайте таймлайн: промпты, вызовы инструментов, результаты вызовов и ответы отображаются как отдельные события с play/pause, регулировкой скорости (от 0.5x до 4x) и горячими клавишами (пробел переключает, стрелки — шаг).
-Чтобы подгрузить старые JSONL-расшифровки Claude Code:
+Чтобы подключить старые JSONL-расшифровки Claude Code:
```bash
# Import everything under the default ~/.claude/projects
-npx @agentmemory/agentmemory import-jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
-Импортированные сессии появятся в Replay-пикере рядом с нативными. Под капотом каждая запись проходит через iii-функции `mem::replay::load`, `mem::replay::sessions` и `mem::replay::import-jsonl` — никаких побочных серверов. Каждая импортированная расшифровка индексируется для поиска, помечается каналом происхождения `import` и обрабатывается для получения session crystal и уроков.
+Импортированные сессии появляются в Replay-пикере рядом с нативными. Под капотом каждая запись проходит через iii-функции `mem::replay::load`, `mem::replay::sessions` и `mem::replay::import-jsonl`, без побочных серверов. Каждая импортированная расшифровка индексируется для поиска, помечается каналом происхождения `import` и обрабатывается для получения session crystal и уроков.
-> **Внимание, если `import-jsonl` — ваш основной путь захвата:** параметр `cleanupPeriodDays` в Claude Code (в `~/.claude/settings.json`, по умолчанию **30**) автоматически удаляет JSONL-расшифровки старше этого окна из `~/.claude/projects/`. Если вы ставите agentmemory заново на историю Claude Code возрастом в несколько месяцев, всё старше 30 дней уже пропало до первого импорта. Либо запускайте `import-jsonl` по cron, либо поднимите `cleanupPeriodDays` повыше, либо подключите хуки авто-захвата (путь установки плагина по умолчанию), чтобы каждый ход попадал в agentmemory ещё во время живой сессии — тогда очистка JSONL перестаёт иметь значение.
+> **Важно, если `import-jsonl` — ваш основной путь захвата:** параметр `cleanupPeriodDays` в Claude Code (в `~/.claude/settings.json`, по умолчанию **30**) автоматически удаляет JSONL-расшифровки старше этого окна из `~/.claude/projects/`. Если вы ставите agentmemory заново на историю Claude Code возрастом в несколько месяцев, всё, что старше 30 дней, уже пропало до первого импорта. Либо запускайте `import-jsonl` по cron, либо поднимите `cleanupPeriodDays`, либо подключите хуки авто-захвата (путь установки плагина по умолчанию), чтобы каждый ход попадал в agentmemory ещё во время живой сессии — тогда очистка JSONL перестаёт иметь значение.
-### Обновление / Обслуживание
+### Обновление / обслуживание
-Используйте команду обслуживания, когда специально хотите обновить локальный runtime:
+Используйте команду обслуживания, когда намеренно хотите обновить локальный runtime:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Внимание: команда меняет текущее рабочее окружение / runtime. Она может обновлять JavaScript-зависимости и стянуть закреплённый Docker-образ `iiidev/iii:0.11.2`. Она никогда не устанавливает незакреплённый или более новый движок iii.
+Внимание: эта команда изменяет текущее рабочее окружение/runtime. Она может обновлять JavaScript-зависимости и скачать закреплённый Docker-образ `iiidev/iii:0.22.1`. Она никогда не устанавливает незакреплённый или более новый iii engine.
Детали реализации — в `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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code без установки плагина (путь MCP-standalone)
-Если подключать MCP-сервер agentmemory через `~/.claude.json` напрямую, минуя `/plugin install`, Claude Code никогда не разрешит `${CLAUDE_PLUGIN_ROOT}`, и в `~/.claude/settings.json` придётся прописывать абсолютные пути к скриптам хуков. Эти пути обычно включают версию agentmemory (например, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.21/scripts/…`), так что следующее обновление тихо ломает каждый хук.
+Если подключать MCP-сервер agentmemory через `~/.claude.json` напрямую, минуя `/plugin install`, Claude Code никогда не разрешит `${CLAUDE_PLUGIN_ROOT}`, и в `~/.claude/settings.json` придётся прописывать абсолютные пути к скриптам хуков. Эти пути обычно включают версию agentmemory (например, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), так что следующее обновление тихо ломает каждый хук.
Обходное решение:
@@ -538,13 +656,13 @@ agentmemory connect claude-code --with-hooks
```
Это вливает те же команды хуков в `~/.claude/settings.json` с абсолютными путями, разрешёнными в каталог `plugin/` текущего установленного пакета `@agentmemory/agentmemory`. После обновления agentmemory запустите команду ещё раз, чтобы освежить пути. Записи пользователя в этом файле сохраняются; заменяются только предыдущие записи agentmemory. Рекомендуемым способом остаётся путь через `/plugin install`.
-Для удалённых или защищённых развертываний запускайте Claude Code с заданными `AGENTMEMORY_URL` и `AGENTMEMORY_SECRET`. Плагин пробрасывает обе переменные во встроенный MCP-сервер; если `AGENTMEMORY_URL` пуст, MCP-shim использует `http://localhost:3111`.
+Для удалённых или защищённых развёртываний запускайте Claude Code с заданными `AGENTMEMORY_URL` и `AGENTMEMORY_SECRET`. Плагин пробрасывает оба значения во встроенный MCP-сервер; если `AGENTMEMORY_URL` пуст, MCP-shim использует `http://localhost:3111`.
### Codex CLI (платформа плагинов Codex)
```bash
# 1. start the memory server in a separate terminal
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
@@ -553,29 +671,43 @@ codex plugin add agentmemory@agentmemory
Плагин Codex поставляется из того же каталога `plugin/`, что и плагин Claude Code. Он регистрирует:
-- `@agentmemory/mcp` как MCP-сервер (проксирует все 54 инструмент, когда `AGENTMEMORY_URL` указывает на работающий сервер agentmemory; локально откатывается к 7 инструментам, если сервер недоступен)
+- Встроенный stdio MCP-мост к работающему демону, без загрузки через npm и без локального откатного хранилища. См. [локальное руководство по Codex](../docs/plugins/codex-local.md) для тестирования нерелизной сборки.
- 6 хуков жизненного цикла: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 9 вызываемых skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, плюс 8 справочных skills, которые агент загружает по запросу (memory discipline, инструменты MCP, REST API, конфигурация, агенты, хуки, архитектура и руководство по написанию skills)
Хук-движок Codex подставляет `CLAUDE_PLUGIN_ROOT` в подпроцессы хуков (см. [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), поэтому одни и те же скрипты хуков работают на обоих хостах без дублирования. События Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure доступны только в Claude Code и для Codex не регистрируются.
-#### Codex Desktop: хуки плагинов сейчас тихие (есть обходное решение)
+#### Доверие к хукам Codex и совместимость
-`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 по-прежнему работают; не хватает только наблюдений жизненного цикла.
+Нативный диспатч хуков плагина подтверждён на Codex CLI 0.150.1. Прежде чем ожидать захват, подтвердите доверие к хукам плагина. Поведение Codex Desktop зависит от встроенного в него runtime; проверьте `/hooks` и убедитесь, что событие захвачено, прежде чем включать обходное решение.
-Пока upstream не подвезёт фикс, продублируйте те же команды хуков в глобальный `~/.codex/hooks.json`:
+Если ваш хост требует глобальных хуков, продублируйте команды в `~/.codex/hooks.json`. Если MCP уже подключён, текущему коннектору нужен `--force`, чтобы добраться до установки хуков:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-Это добавляет идемпотентный блок в `~/.codex/hooks.json` со ссылками на абсолютные пути к встроенным скриптам (раскрывать `${CLAUDE_PLUGIN_ROOT}` на уровне пользователя не нужно). После обновления agentmemory запустите ту же команду ещё раз, чтобы освежить пути. Записи пользователя в этом файле сохраняются; заменяются только предыдущие записи agentmemory.
+Это объединяет глобальные хуки и перезаписывает запись MCP agentmemory, сохраняя несвязанные записи. Проверьте настройки собственного endpoint'а agentmemory, прежде чем использовать `--force`. Запустите повторно после обновления, чтобы освежить пути скриптов. Включите либо нативные хуки плагина, либо глобальные копии, чтобы избежать дублирующего захвата.
+
+### GitHub Copilot CLI
+
+Для режима агента VS Code используйте [руководство по MCP и автозахвату Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Коннектор CLI не настраивает VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Альтернативно, полный плагин хуков/skill'ов из GitHub-подкаталога
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` вливает `mcpServers.agentmemory` в `~/.copilot/mcp-config.json` (либо `$COPILOT_HOME/mcp-config.json`, когда задан `COPILOT_HOME`) и сохраняет существующие серверы. На нативном Windows это единственный автоматизированный адаптер `connect`; все остальные нативные Windows-агенты настраивайте вручную. `connect` под WSL поддерживается только когда целевой агент установлен в том же окружении WSL. Copilot подхватывает MCP-сервер при следующем запуске или после `/mcp`. Установите также плагин, если хотите полный опыт с хуками/skill'ами.
OpenClaw (вставьте этот промпт)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -600,7 +732,7 @@ Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. O
Hermes Agent (вставьте этот промпт)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -619,7 +751,7 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
### Другие агенты
-Запустите сервер памяти: `npx @agentmemory/agentmemory`
+Запустите сервер памяти: `npx -y @agentmemory/agentmemory@latest`
#### Нативные skill'ы через `npx skills add` (50+ агентов)
@@ -640,7 +772,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
#### Стандартный блок MCP
-Запись agentmemory — это **один и тот же блок MCP-сервера** для всех хостов, использующих формат `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw):
+Запись agentmemory — это **один и тот же блок MCP-сервера** для всех хостов, использующих формат `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
```json
"agentmemory": {
@@ -653,33 +785,35 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
}
```
-**Вставьте эту запись в существующий объект `mcpServers`** в файле конфигурации хоста — не заменяйте сам файл. Если там уже есть другие серверы, добавьте `agentmemory` рядом с ними как новый ключ внутри `mcpServers`. Если `mcpServers` отсутствует совсем, вставьте блок внутрь `{ "mcpServers": { ... } }`. Подстановки `${VAR}` наследуют `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` из shell в момент запуска MCP-сервера — незаданные переменные передаются пустыми, и shim откатывается на `http://localhost:3111`. Одна подключённая запись покрывает как локальные, так и удалённые (k8s / reverse-proxied) развертывания.
+**Вставьте эту запись в существующий объект `mcpServers`** в файле конфигурации хоста — не заменяйте сам файл. Если там уже есть другие серверы, добавьте `agentmemory` рядом с ними как новый ключ внутри `mcpServers`. Если `mcpServers` отсутствует совсем, вставьте блок внутрь `{ "mcpServers": { ... } }`. Подстановки `${VAR}` наследуют `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` из shell в момент запуска MCP-сервера; незаданные переменные передаются пустыми строками, и shim откатывается на `http://localhost:3111`. Одна подключённая запись покрывает как локальные, так и удалённые (k8s / reverse-proxied) развёртывания.
| Агент | Файл конфигурации | Заметки |
|---|---|---|
-| **Cursor** | `~/.cursor/mcp.json` | Добавить в `mcpServers`. Также доступен deeplink в один клик на сайте. |
-| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Добавить в `mcpServers`. После правки перезапустить Claude Desktop. |
+| **Cursor (только MCP)** | `~/.cursor/mcp.json` | Добавьте в `mcpServers`, либо используйте `agentmemory connect cursor`. На сайте также доступен deeplink в один клик. |
+| **Cursor (полный плагин)** | `.cursor-plugin/` | Листинг в Cursor Marketplace (заявка на рассмотрении) либо Cursor Settings → Plugins → локальный checkout. Регистрирует 7 хуков авто-захвата (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill'ов + MCP-сервер, причём `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` управляются в панели плагинов Cursor. Работает в Cursor IDE и в CLI `cursor-agent`; промпты в print-режиме CLI досчитываются из расшифровки сессии при её завершении. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Добавьте в `mcpServers`. После правки перезапустите Claude Desktop. |
| **Cline / Roo Code / Kilo Code** | Настройки MCP в Cline (Settings UI → MCP Servers → Edit) | Тот же блок `mcpServers`. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` добавляет MCP-запись; `--with-hooks` подключает шесть нативных hooks автозахвата (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) с матчерами инструментов Devin в нижнем регистре. Проверьте через `devin mcp list` и `/hooks` внутри devin. |
-| **Devin (облако)** | Settings → Connections → MCP servers | Добавьте пользовательский MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` на доступное по сети развёртывание agentmemory плюс `AGENTMEMORY_SECRET` (облачные сессии не достают до localhost — см. [`deploy/`](../deploy/)). |
+| **Devin CLI (MCP + хуки)** | `~/.config/devin/config.json` | `agentmemory connect devin` добавляет MCP-запись; `--with-hooks` подключает шесть нативных hooks автозахвата (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) с матчерами инструментов Devin в нижнем регистре. Проверьте через `devin mcp list` и `/hooks` внутри devin. |
+| **Devin CLI (полный плагин)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` из checkout'а регистрирует все 17 skill'ов как slash-команды `/agentmemory:` плюс MCP-сервер. Хуки плагина Devin не могут сработать на `SessionStart`/`SessionEnd`, поэтому для полного захвата сессии сочетайте это с `connect devin --with-hooks`. |
+| **Devin (облако)** | Settings → Connections → MCP servers | Добавьте пользовательский MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL`, указывающий на доступное по сети развёртывание agentmemory, плюс `AGENTMEMORY_SECRET` (облачные сессии не могут достать до localhost — см. [`deploy/`](../deploy/)). Сохраните секрет в Devin Secrets, затем используйте «Test listing tools», чтобы убедиться, что появляются все 54 инструмента. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (автоматическое слияние). |
| **GitHub Copilot CLI (только MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` вливает `mcpServers.agentmemory`; Copilot подхватывает при следующем запуске или по `/mcp`. |
| **GitHub Copilot CLI (полный плагин)** | Установка плагина Copilot | `copilot plugin install rohitg00/agentmemory:plugin` — плагин из GitHub-подкаталога. |
-| **OpenClaw** | MCP-конфиг OpenClaw | Тот же блок `mcpServers`. Глубже: `openclaw plugins install ./integrations/openclaw` занимает слот памяти OpenClaw (автоматически переключается с `memory-core`); задайте `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, иначе захват хода будет молча заблокирован. См. [`integrations/openclaw`](integrations/openclaw/). |
+| **OpenClaw** | MCP-конфиг OpenClaw | Тот же блок `mcpServers`. Глубже: `openclaw plugins install ./integrations/openclaw` занимает слот памяти OpenClaw (автоматически переключается с `memory-core`); задайте `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, иначе захват хода будет молча заблокирован. См. [`integrations/openclaw`](../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 хуков жизненного цикла (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 17 skill'ов. На Codex Desktop дополнительно запустите `agentmemory connect codex --with-hooks`, пока не зарелизят [openai/codex#16430](https://github.com/openai/codex/issues/16430); хуки плагина там пока тихие. |
+| **Codex CLI (полный плагин)** | Маркетплейс плагинов Codex | `codex plugin marketplace add rohitg00/agentmemory`, затем `codex plugin add agentmemory@agentmemory`. Регистрирует MCP + 6 хуков жизненного цикла + 17 skill'ов. Подтвердите доверие к хукам и проверьте захват на вашем хосте; см. [установку и проверку Codex](../docs/plugins/codex-local.md). |
| **OpenCode (только MCP)** | `opencode.json` | Другая форма: корневой ключ `mcp`, команда задаётся массивом: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (полный плагин)** | `plugin/opencode/` | 22 хука авто-захвата по жизненному циклу сессии, сообщениям, инструментам и ошибкам. Атрибуция проекта задаётся на уровне сессии, поэтому один процесс OpenCode, охватывающий несколько репозиториев, кладёт каждую сессию в её собственный проект. Две slash-команды (`/recall`, `/remember`). Скопируйте `plugin/opencode/` в свой рабочий каталог OpenCode и добавьте запись плагина в `opencode.json`. Полная таблица хуков и анализ пробелов — в [`plugin/opencode/README.md`](../plugin/opencode/README.md). |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` устанавливает встроенное расширение в каталог автообнаружения pi (recall при старте агента, захват при завершении, инструменты `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` в работающем pi подхватывает его. [`integrations/pi`](../integrations/pi/) — это также pi-пакет (`pi install ./integrations/pi` из checkout'а). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` включает провайдера памяти с 6 хуками (предзагрузка, захват хода, завершение сессии, предварительное сжатие, зеркалирование MEMORY.md, блок системного промпта). Проверьте через `hermes plugins doctor` и `hermes memory status`. См. [`integrations/hermes`](integrations/hermes/). |
-| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` записывает стандартный блок `mcpServers`. Payload хуков по полям совместим с Claude Code, поэтому существующие 12 скриптов хуков работают без изменений; подключите их через секцию `hooks` в том же `settings.json`. |
-| **Antigravity** (заменяет Gemini CLI) | `mcp_config.json` (в каталоге User у Antigravity) | `agentmemory connect antigravity` записывает стандартный блок `mcpServers`. macOS: `~/Library/Application Support/Antigravity/User/`. Linux: `~/.config/Antigravity/User/`. Использовать после отключения Gemini CLI 2026-06-18. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. CLI `agy` держит собственный конфиг в `~/.gemini/`, отдельно от Antigravity IDE выше. Передайте `--with-hooks` для нативного авто-захвата через `~/.gemini/config/hooks.json`. |
-| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` записывает конфиг на уровне пользователя. Workspace-переопределения — в `.kiro/settings/mcp.json` рядом с кодом. |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` включает провайдера памяти с 6 хуками (предзагрузка, захват хода, завершение сессии, предварительное сжатие, зеркалирование MEMORY.md, блок системного промпта). Проверьте через `hermes plugins doctor` и `hermes memory status`. См. [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` записывает стандартный блок `mcpServers`. Payload хуков по полям совместим с Claude Code, поэтому существующие скрипты 12 хуков работают без изменений; подключите их через секцию `hooks` в том же `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` устанавливает MCP и хуки захвата в общем каталоге настроек. См. [установку и ограничения Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` использует ту же конфигурацию MCP и хуков, что и текущие версии IDE. Существующие установки следует обновить с `--force`; см. [заметки об обновлении](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` записывает конфиг на уровне пользователя. Переопределения на уровне workspace — в `.kiro/settings/mcp.json` рядом с кодом. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` записывает стандартный блок `mcpServers`. Warp также автоматически обнаруживает skill'ы из `.claude/skills/`; как только установлен плагин Claude Code, 8 skill'ов agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) нативно появляются в палитре slash-команд Warp. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` записывает стандартный блок `mcpServers`. Пользователи расширения VS Code: вставьте тот же блок через Cline Settings → MCP Servers → Edit JSON. |
| **Continue.dev** | `~/.continue/config.yaml` (предпочтительно) или `config.json` (legacy) | `agentmemory connect continue` создаёт `config.yaml` с нуля, когда нет ни одного файла, либо изменяет существующий `config.json`. **Если у вас уже есть `config.yaml`**, адаптер печатает точный блок для вставки под `mcpServers:`; он не станет молча переписывать ваш yaml, потому что для безопасного сохранения комментариев и якорей нужен YAML-парсер, которого в пакете нет. Continue использует форму массива (а не объекта) для `mcpServers`. |
-| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` пишет под `context_servers` (ключ Zed, НЕ `mcpServers`). Удалённые MCP-серверы можно подключить через `{"url": "..."}`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` пишет под `context_servers` (ключ Zed, НЕ `mcpServers`). Удалённые MCP-серверы можно вместо этого подключить через `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` записывает стандартный блок `mcpServers`. Переопределения на уровне проекта — в `/.factory/mcp.json`. Передайте `--with-hooks` для нативного авто-захвата. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` добавляет строку `@deepseek-ai/dsh-mcp-client` в патч-слой домашнего уровня, который загружает каждый профиль Harness; инструменты регистрируются как `mcp__agentmemory__*`. Передайте `--with-hooks`, чтобы также подключить авто-захват: встроенные скрипты хуков Claude Code выполняются через фирменный мост Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) по манифесту, записанному в `$DSH_HOME/agentmemory.hooks.json`. По умолчанию `~/.dsh`, когда `DSH_HOME` не задан. |
| **Goose** | UI настроек MCP в Goose | Тот же блок `mcpServers`; используйте `goose configure` → Add Extension → MCP. Прямое редактирование YAML в `~/.config/goose/config.yaml` поддерживается, но схема использует `extensions:` + `cmd` (а не `mcpServers:` + `command`). |
@@ -719,39 +853,43 @@ git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
-Это поднимает agentmemory с локальным `iii-engine`, если `iii` уже установлен, либо откатывается к Docker Compose, если есть Docker. REST, стримы и просмотрщик по умолчанию слушают на `127.0.0.1`.
+Это поднимает agentmemory с локальным `iii-engine`, если закреплённый бинарь уже установлен, либо откатывается к Docker Compose, если он выбран. REST, стримы и просмотрщик по умолчанию слушают на `127.0.0.1`. Автоматический путь установки бинаря на macOS/Linux требует `curl`, POSIX-совместимый `sh` и `tar`.
-Установите `iii-engine` вручную. **agentmemory сейчас зафиксирован на `iii-engine` `v0.11.2`** — `v0.11.6` вводит новую модель «всё через `iii worker add` в sandbox», под которую agentmemory ещё не отрефакторен. Закрепление снимется, как только рефакторинг будет завершён. Переопределите через `AGENTMEMORY_III_VERSION=`, если вы вручную перешли на sandbox-модель.
+Установите `iii-engine` вручную. **agentmemory сейчас закреплён на `iii-engine` `v0.22.1`** — той же версии, что и его зависимость `iii-sdk`; воркер говорит на wire-протоколе именно этого движка, а 0.20.0 перестроил поверхность SDK, поэтому оба обновляются вместе в релизах agentmemory. Переопределите через `AGENTMEMORY_III_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 arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** замените `aarch64-apple-darwin` на `x86_64-apple-darwin`
- **Linux x64:** замените на `x86_64-unknown-linux-gnu`
- **Linux arm64:** замените на `aarch64-unknown-linux-gnu`
-- **Windows:** скачайте `iii-x86_64-pc-windows-msvc.zip` из [iii-hq/iii releases v0.11.2](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2), распакуйте `iii.exe`, добавьте в PATH
+- **Windows:** скачайте `iii-x86_64-pc-windows-msvc.zip` из [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) и распакуйте `iii.exe` в `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+У каждого архива на странице релиза есть соответствующий файл `.sha256`; при смене платформы используйте хеш из этого файла в проверке выше (на Windows: `Get-FileHash`). Автоматический установщик в `npx @agentmemory/agentmemory` закрепляет эти хеши и отказывается принимать архив, который им не соответствует.
-Либо используйте Docker (входящий в комплект `docker-compose.yml` тянет `iiidev/iii:0.11.2`). Полная документация: [iii.dev/docs](https://iii.dev/docs).
+Либо используйте Docker (входящий в комплект `docker-compose.yml` тянет `iiidev/iii:0.22.1`). Полная документация: [iii.dev/docs](https://iii.dev/docs).
### Windows
-agentmemory работает на Windows 10/11, но одного Node.js-пакета мало — также нужен runtime `iii-engine` (отдельный нативный бинарь) как фоновый процесс. Официальный upstream-установщик — это `sh`-скрипт, на сегодня нет ни PowerShell-установщика, ни пакета scoop/winget, поэтому у пользователей Windows два пути:
+agentmemory работает на Windows 10/11, но одного Node.js-пакета мало — также нужен закреплённый runtime iii-engine v0.22.1 как фоновый процесс. CLI не распаковывает Windows-архив автоматически, поэтому пользователям нативного Windows нужно установить `iii.exe` вручную, использовать WSL2 либо выбрать Docker Desktop.
+
+Автоматизированное подключение MCP на нативном Windows поддерживает только `agentmemory connect copilot-cli`. Для Claude Code, Codex, Cursor и любого другого нативного Windows-агента скопируйте ручной блок MCP из раздела [Другие агенты](#other-agents) в конфиг этого агента на Windows. Запуск `connect` в WSL имеет смысл только тогда, когда целевой агент также установлен в том же окружении WSL; он не редактирует конфигурацию агента, запущенного на хосте 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)
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
-# 3. Extract iii.exe somewhere on PATH, or place it at:
-# %USERPROFILE%\.local\bin\iii.exe
-# (agentmemory checks that location automatically)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
-iii --version
-# Should print: 0.11.2
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
# 5. Then run agentmemory as usual:
-npx -y @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
**Вариант B: Docker Desktop**
@@ -759,28 +897,29 @@ npx -y @agentmemory/agentmemory
```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
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
**Вариант C: только standalone MCP (без движка).** Если вам нужны только MCP-инструменты для агента и не нужны REST API, просмотрщик или cron-задачи, пропустите движок целиком:
```powershell
-npx -y @agentmemory/agentmemory mcp
+npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
-**Диагностика на Windows:** если `npx @agentmemory/agentmemory` падает, перезапустите с `--verbose`, чтобы увидеть реальный stderr движка. Частые сценарии сбоя:
+**Диагностика на Windows:** если `npx -y @agentmemory/agentmemory@latest` падает, перезапустите с `--verbose`, чтобы увидеть реальный stderr движка. Частые сценарии сбоя:
-| Симптом | Что делать |
+| Симптом | Решение |
|---|---|
-| `iii-engine process started`, затем `did not become ready within 15s` | Движок упал при старте — перезапустите с `--verbose`, проверьте stderr |
+| `The engine process started but the REST API never responded.` | Убедитесь, что все четыре вычисленных порта свободны, проверьте, что закреплённый `iii.exe` остался жив, затем перезапустите с `--verbose` и изучите захваченный stderr движка |
| `Could not start iii-engine` | Не установлены ни `iii.exe`, ни Docker. См. варианты A или B выше |
-| Конфликт порта | `netstat -ano \| findstr :3111`, чтобы понять, что занимает порт, затем убить процесс или использовать `--port ` |
+| Конфликт порта | `netstat -ano \| findstr :3111`, чтобы понять, что занято, затем убить процесс или использовать `--port ` |
| Откат на Docker пропускается, хотя Docker установлен | Убедитесь, что Docker Desktop действительно запущен (иконка в трее) |
-> Примечание: **движок** iii — это готовый бинарь, а не cargo-крейт, не пытайтесь установить его через `cargo install`. (**SDK** iii опубликованы на crates.io, npm и PyPI, но agentmemory они не нужны.) Поддерживаемые способы установки движка, все закреплены на v0.11.2: готовый бинарь v0.11.2 выше, upstream-`sh`-скрипт **с закреплением версии** `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) и Docker-образ `iiidev/iii:0.11.2`. Простой `install.sh | sh` устанавливает **последний** движок, который agentmemory не поддерживает, — всегда передавайте `VERSION=0.11.2`. Самый простой вариант: просто запустите `npx @agentmemory/agentmemory`, который сам загрузит закреплённый движок в `~/.agentmemory/bin`.
+> Примечание: iii **engine** — это готовый бинарь, а не cargo-крейт, поэтому не пытайтесь установить его через `cargo install`. (**SDK** iii опубликованы на crates.io, npm и PyPI, но agentmemory они не нужны.) Все поддерживаемые способы установки движка закреплены на v0.22.1: готовый бинарь выше, автоматический путь установки agentmemory для macOS/Linux (нужны `curl`, POSIX `sh` и `tar`) и Docker-образ `iiidev/iii:0.22.1`. Обычный upstream `install.sh | sh` устанавливает последний движок, который agentmemory не поддерживает. Используйте `npx -y @agentmemory/agentmemory@latest`; на macOS/Linux он сам загрузит закреплённый движок в `~/.agentmemory/bin`.
---
@@ -788,37 +927,37 @@ npx -y @agentmemory/mcp
Шаблоны в один клик для managed-хостов. Каждый поставляет автономный
Dockerfile, который тянет `@agentmemory/agentmemory` из npm и копирует
-бинарь iii engine из официального образа `iiidev/iii` на Docker
-Hub — собственный преcобранный образ agentmemory не нужен. Постоянное
+бинарь движка iii из официального образа `iiidev/iii` на Docker Hub;
+собственный пресобранный образ agentmemory не нужен. Постоянное
хранилище монтируется в `/data`; entrypoint при первом запуске
перезаписывает поставляемый npm'ом iii-конфиг (который слушает на
-`127.0.0.1`) на deploy-вариант, слушающий на `0.0.0.0` и
-использующий абсолютные пути `/data`, генерирует HMAC-секрет,
-а затем понижает привилегии с `root` до `node` через `gosu`
-перед запуском CLI agentmemory.
+`127.0.0.1`) на вариант, настроенный для деплоя, слушающий на
+`0.0.0.0` и использующий абсолютные пути `/data`, генерирует
+HMAC-секрет, а затем понижает привилегии с `root` до `node` через
+`gosu` перед запуском CLI agentmemory.
-Кнопке Render «деплой в один клик» нужен `render.yaml` в корне репозитория, который мы намеренно держим чистым. Используйте схему через Render Blueprint, описанную в [`deploy/render/`](./deploy/render/README.md), чтобы вручную указать на in-repo blueprint.
+Кнопке Render «деплой в один клик» нужен `render.yaml` в корне репозитория, который мы намеренно держим чистым. Используйте поток Render Blueprint, описанный в [`deploy/render/`](.././deploy/render/README.md), чтобы вручную указать на blueprint внутри репозитория.
-Полные детали настройки (захват HMAC, SSH-туннель к просмотрщику, ротация, бэкап, нижние пороги стоимости) — в [`deploy/`](./deploy/README.md):
+Полные детали настройки (захват HMAC, SSH-туннель к просмотрщику, ротация, бэкап, нижние пороги стоимости) — в [`deploy/`](.././deploy/README.md):
-- [`deploy/fly`](./deploy/fly/README.md) — одна машина с
+- [`deploy/fly`](.././deploy/fly/README.md): одна машина с
`auto_stop_machines = "stop"`; дешевле всего в простое.
-- [`deploy/railway`](./deploy/railway/README.md) — фиксированный тариф Hobby,
+- [`deploy/railway`](.././deploy/railway/README.md): фиксированный тариф Hobby,
том в панели.
-- [`deploy/render`](./deploy/render/README.md) — поток Blueprint,
+- [`deploy/render`](.././deploy/render/README.md): поток Blueprint,
автоматические снапшоты диска на платных тарифах.
-- [`deploy/coolify`](./deploy/coolify/README.md) — self-hosted на собственном
- VPS через [Coolify](https://coolify.io/self-hosted); тот же Docker
- Compose-стек, хост и данные у вас.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted на собственном
+ VPS через [Coolify](https://coolify.io/self-hosted); тот же стек Docker
+ Compose, хост и данные остаются у вас.
Публикуется только порт `3111`. Просмотрщик на `3113` остаётся
-привязанным к loopback внутри контейнера — в README каждого шаблона
-описан паттерн SSH-туннеля, чтобы до него достучаться.
+привязанным к loopback внутри контейнера; в README каждого шаблона
+описан паттерн SSH-туннеля для доступа к нему.
---
@@ -842,13 +981,13 @@ Session 2: "Now add rate limiting"
### vs встроенная память агента
-Каждый ИИ-агент программирования поставляется со встроенной памятью — у Claude Code есть `MEMORY.md`, у Cursor — notepad'ы, у Cline — memory bank. Это работает как стикеры. agentmemory — индексируемая база данных за этими стикерами.
+Каждый ИИ-агент программирования поставляется со встроенной памятью: у Claude Code есть `MEMORY.md`, у Cursor — notepad'ы, у Cline — memory bank. Они работают как стикеры. agentmemory — это индексируемая база данных за этими стикерами.
| | Встроенная (CLAUDE.md) | agentmemory |
|---|---|---|
| Масштаб | Потолок в 200 строк | Без ограничений |
-| Поиск | Загружает всё в контекст | BM25 + векторный + граф (только top-K) |
-| Цена в токенах | 22K+ при 240 наблюдениях | ~1 900 токенов (на 92 % меньше) |
+| Поиск | Загружает всё в контекст | BM25 + вектор + граф (только top-K) |
+| Цена в токенах | 22K+ при 240 наблюдениях | ~1,900 токенов (на 92% меньше) |
| Между агентами | Файлы на каждого агента | MCP + REST (любой агент) |
| Координация | Нет | Lease'ы, сигналы, action'ы, routine'ы |
| Наблюдаемость | Читать файлы вручную | Просмотрщик в реальном времени на :3113 |
@@ -864,9 +1003,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -882,7 +1022,7 @@ SessionStart hook fires
### 4-уровневая консолидация памяти
-Смоделировано по тому, как человеческий мозг обрабатывает воспоминания, включая консолидацию во время сна.
+Смоделировано по тому, как человеческий мозг обрабатывает память, включая консолидацию во время сна.
| Уровень | Что | Аналогия |
|------|------|---------|
@@ -891,7 +1031,7 @@ SessionStart hook fires
| **Semantic** | Извлечённые факты и закономерности | «Что я знаю» |
| **Procedural** | Workflow'ы и паттерны принятия решений | «Как это сделать» |
-Воспоминания затухают со временем (кривая Эббингауза). Часто используемые воспоминания усиливаются. Устаревшие — автоматически вытесняются. Противоречия обнаруживаются и разрешаются.
+Воспоминания затухают со временем (кривая Эббингауза). Часто используемые воспоминания усиливаются. Устаревшие автоматически вытесняются. Противоречия обнаруживаются и разрешаются.
### Что захватывается
@@ -941,23 +1081,27 @@ SessionStart hook fires
Сливаются через Reciprocal Rank Fusion (RRF, k=60) и диверсифицируются по сессиям (не более 3 результатов на сессию).
-Гибридное ранжирование применяется к основному пути recall, а не только к `smart-search`: `mem::search` (за которым стоит `memory_recall`) ранжирует через то же слияние BM25 + векторов + графа, как только векторный индекс заполнен. Recall уроков работает на выделенном in-memory BM25-индексе вместо сканирования всего корпуса на каждый запрос. Вытесненные (superseded) версии памяти исключаются из каждого пути recall; цепочка версий сохраняет их историю.
+Когда векторный индекс заполнен, `mem::search` (за которым стоит `memory_recall`) использует гибридный ранжировщик BM25 + вектор. Без эмбеддингов используется BM25. `smart-search` может дополнительно сливать структурные совпадения из графа, если граф-данные существуют, в том числе в режиме без ключей. Recall уроков работает на выделенном in-memory BM25-индексе вместо сканирования всего корпуса на каждый запрос. Вытесненные (superseded) версии памяти исключаются из каждого пути recall; цепочка версий хранит их историю.
+
+Векторы переживают крэш или force-kill. Векторный индекс сохраняется бакетами не чаще, чем раз в `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 минут). Каждый добавленный или удалённый в промежутке вектор также сразу записывается в небольшой отложенный лог в state store, и при следующем запуске он воспроизводится без обращения к провайдеру эмбеддингов. Каждое успешное сохранение очищает лог. Документы, у которых после воспроизведения всё ещё нет вектора, переэмбеддятся в фоне партиями по `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), пока не останется ни одного, а остановленный backfill продолжается при следующем запуске. `/agentmemory/status` и просмотрщик показывают размер отложенного лога и состояние backfill'а. Установки без ключей ничего не пишут.
-BM25 «из коробки» токенизирует греческий, кириллицу, иврит, арабский и латиницу с диакритикой. Для записей на китайском / японском / корейском поставьте опциональные сегментаторы (`npm install @node-rs/jieba tiny-segmenter`), чтобы CJK-последовательности разбивались на токены уровня слова; без них agentmemory мягко откатывается к токенизации целых последовательностей и выводит одноразовую подсказку в stderr.
+BM25 «из коробки» токенизирует греческий, кириллицу, иврит, арабский и латиницу с диакритикой. Для записей на китайском / японском / корейском поставьте опциональные сегментаторы (`npm install @node-rs/jieba tiny-segmenter`), чтобы разбивать CJK-последовательности на токены уровня слова; без них agentmemory мягко откатывается к токенизации целых последовательностей и один раз выводит подсказку в stderr.
### Провайдеры эмбеддингов
-agentmemory автоматически определяет вашего провайдера. Для лучших результатов поставьте локальные эмбеддинги (бесплатно):
+Установки без ключей отключают векторные эмбеддинги: `mem::search` использует BM25, а `smart-search` может также использовать существующие структурные граф-данные. Чтобы подключить бесплатные семантические эмбеддинги на устройстве, добавьте это в `~/.agentmemory/.env` и перезапустите agentmemory:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+Обычная установка npm включает опциональный runtime `@huggingface/transformers`. Первый запрос эмбеддинга скачивает `Xenova/all-MiniLM-L6-v2`, поэтому нужен доступ к сети и это может занять больше времени; последующий инференс выполняется на устройстве. Удалённые провайдеры определяются автоматически по их ключам, если только `EMBEDDING_PROVIDER` не переопределяет их.
+
| Провайдер | Модель | Стоимость | Заметки |
|---|---|---|---|
-| **Локально (рекомендуется)** | `all-MiniLM-L6-v2` | Бесплатно | Офлайн, +8 пп recall по сравнению только с BM25 |
+| **Локально (рекомендуется для подключения)** | `all-MiniLM-L6-v2` | Бесплатно | На устройстве после первой загрузки модели, +8 пп recall по сравнению только с BM25 |
| Gemini | `gemini-embedding-001` | Бесплатный тариф | 100+ языков, размерности 768/1536/3072 (MRL), вход 2048 токенов. Заменяет `text-embedding-004` ([устарел, отключение 14 янв. 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
-| OpenAI | `text-embedding-3-small` | 0,02 $/1M | Высочайшее качество |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Высочайшее качество |
| Voyage AI | `voyage-code-3` | Платно | Оптимизирован под код |
| Cohere | `embed-english-v3.0` | Бесплатная пробная версия | Общего назначения |
| OpenRouter | Любая модель | Зависит | Мульти-модельный прокси |
@@ -968,7 +1112,7 @@ npm install @huggingface/transformers
54 инструмента, 6 ресурсов, 3 промпта и 17 skill'ов.
-> **MCP-shim против полного сервера:** опубликованный пакет `@agentmemory/mcp` — это тонкий shim. Он раскрывает полную поверхность из 54 инструментов **только если может достучаться до работающего сервера agentmemory** через `AGENTMEMORY_URL` (режим прокси). Если сервер недоступен, shim откатывается к локальному набору из 7 инструментов (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Переменная окружения `AGENTMEMORY_TOOLS=core|all` — *серверный* флаг; задавать её в блоке `env` shim'а бесполезно. Если в Cursor / OpenCode / Gemini CLI видно только 7 инструментов, запустите `npx @agentmemory/agentmemory` (или Docker-стек) и установите `AGENTMEMORY_URL=http://localhost:3111`.
+> **MCP-shim против полного сервера:** опубликованный пакет `@agentmemory/mcp` — это тонкий shim. Он раскрывает полную поверхность из 54 инструментов **только если может достучаться до работающего сервера agentmemory** через `AGENTMEMORY_URL` (режим прокси). Если сервер недоступен, shim откатывается к локальному набору из 7 инструментов (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Переменная окружения `AGENTMEMORY_TOOLS=core|all` — это *серверный* флаг; задавать её в блоке `env` shim'а бесполезно. Если в Cursor / OpenCode / Gemini CLI видно только 7 инструментов, запустите `npx -y @agentmemory/agentmemory@latest` (или Docker-стек) и установите `AGENTMEMORY_URL=http://localhost:3111`.
### 54 инструмента
@@ -1051,22 +1195,22 @@ npm install @huggingface/transformers
| Skill | `/recall` | Поиск по памяти |
| Skill | `/remember` | Сохранение в долговременную память |
| Skill | `/session-history` | Краткие итоги последних сессий |
-| Skill | `/forget` | Удаление наблюдений / сессий |
+| Skill | `/forget` | Удаление наблюдений/сессий |
-В таблице показаны четыре основных skill'а. Полный набор — 8 вызываемых skill'ов плюс 7 справочных; см. раздел про нативные skill'ы выше.
+В таблице показаны четыре основных skill'а. Полный набор — 9 вызываемых skill'ов плюс 8 справочных; см. раздел про нативные skill'ы выше.
### Standalone MCP
Запуск без полного сервера — для любого MCP-клиента. Подойдёт любое:
```bash
-npx -y @agentmemory/agentmemory mcp # canonical (always available)
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
Или добавьте в MCP-конфиг своего агента:
-Большинство агентов (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+Большинство агентов (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1108,46 +1252,51 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-Автоматически запускается на порту `3113`. Живой поток наблюдений с индикатором статуса стрима, двухпанельный обозреватель сессий (список рядом с закреплённой панелью деталей на широких экранах), строки памяти и уроков, раскрывающиеся до полной сохранённой записи, включая сырой JSON и происхождение, граф знаний, кластеризующий узлы по типу, пока связей мало, воспроизведение сессий и панель состояния.
+Автоматически запускается на порту `3113`. Просмотрщик загружает один снапшот при подключении (`GET /agentmemory/viewer/snapshot`), а затем применяет события живого стрима: новые записи памяти, уроки, наблюдения, записи аудита, изменения графа и обновления состояния появляются без опроса и перезагрузок страницы. Единственные другие запросы — это действия, на которые вы кликаете, страницы «load more» и поиск. Когда стрим отваливается, просмотрщик показывает, насколько устарели его числа, переподключается с backoff и ресинхронизируется с одного снапшота.
+
+- **12 вкладок в четырёх группах** с живыми счётчиками, глубокими ссылками (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), горячими клавишами и мобильным меню.
+- **Memories:** поиск на стороне сервера, фильтры по проекту, агенту и типу, панель деталей с цепочкой версий и word diff, ссылки на происхождение, кнопки копирования id, вызова MCP и команды curl, редактирование (новая версия), forget с подтверждением, массовый forget и экспорт в JSON.
+- **Sessions:** встроенный таймлайн наблюдений с читаемым входом и выходом инструментов, фильтры и постраничная навигация, а также записи памяти и уроки, которые произвела каждая сессия.
+- **Graph:** поиск, детали узла со связями и источниками, легенда, не зависящая только от цвета, и управление масштабом.
+- **Health:** живая версия `GET /agentmemory/status`. Для каждой проблемы указано её решение, плюс backend состояния, состояние сохранения индекса, прогресс компакции происхождения графа и объяснение консолидации с реальными порогами.
+- Страницы **Audit, Activity, Profile, Replay, Lessons, Actions и Crystals**, у каждой — пустое состояние, объясняющее, что это за раздел, почему он пуст и какая команда его заполнит, а также подсказка-глоссарий `?` на каждом термине и числе.
```bash
open http://localhost:3113
```
-Сервер просмотрщика по умолчанию слушает на `127.0.0.1`. Эндпоинт `/agentmemory/viewer`, отдаваемый REST'ом, подчиняется обычным правилам bearer-токена `AGENTMEMORY_SECRET`. Заголовки CSP используют nonce скрипта на ответ и отключают inline-атрибуты-обработчики (`script-src-attr 'none'`).
+Сервер просмотрщика по умолчанию слушает на `127.0.0.1` и подставляет серверный секрет, когда перенаправляет запросы к REST API, так что отдельная настройка не нужна. Эндпоинт `/agentmemory/viewer`, отдаваемый REST'ом, подчиняется обычным правилам bearer-токена и перенаправляет браузеры без токена на порт просмотрщика. Заголовки CSP используют nonce скрипта на каждый ответ и отключают inline-атрибуты-обработчики (`script-src-attr 'none'`).
---
-Просмотрщик на `:3113` показывает, что ваш агент **запомнил**. [iii console](https://iii.dev/docs/console) показывает, что ваш агент **сделал** — каждая операция памяти как трейс OpenTelemetry, каждая запись KV редактируема, каждая функция вызываема, каждый стрим тэппится. Два окна на одну и ту же память: одно повёрнуто к продукту, другое к движку.
+Просмотрщик на `:3113` показывает, что ваш агент **запомнил**. [iii console](https://iii.dev/docs/console) показывает, что ваш агент **сделал**: каждая операция памяти как трейс OpenTelemetry, каждая запись KV редактируема, каждая функция вызываема, каждый стрим тэппится. Два окна на одну и ту же память: одно повёрнуто к продукту, другое к движку.
-Наблюдайте, как срабатывает `memory_smart_search`, и видите BM25-скан → поиск эмбеддингов → RRF-слияние → reranker в виде waterfall. Отредактируйте зависший таймер консолидации в браузере KV. Воспроизведите хук `PostToolUse` с изменённым payload. Пин WebSocket-стрима — и смотрите, как наблюдения прилетают в реальном времени.
+Наблюдайте, как срабатывает `memory_smart_search`, и видите BM25-скан → поиск эмбеддингов → RRF-слияние → reranker в виде waterfall. Отредактируйте зависший таймер консолидации в браузере KV. Воспроизведите хук `PostToolUse` с изменённым payload. Закрепите WebSocket-стрим — и смотрите, как наблюдения прилетают в реальном времени.
agentmemory отдаёт это бесплатно, потому что каждый вызов функции и каждый триггер проходит через iii; ничего самописного, нечего инструментировать.
-
+
- Страница Workers: каждый подключённый воркер — включая сам agentmemory — с PID, количеством функций, runtime и временем последнего появления.
+ Страница Workers: каждый подключённый воркер, включая сам agentmemory, с PID, числом функций, runtime и временем последнего появления.
-**Уже установлено.** Console поставляется вместе с `iii` — отдельный установщик не нужен.
+**Уже установлено.** Console поставляется вместе с закреплённым движком `iii` (0.22+); отдельно устанавливать ничего не нужно. При первом запуске бинарь console скачивается рядом с движком.
-**Запускать рядом с agentmemory:**
+**Запуск рядом с 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
+agentmemory console
```
-Затем откройте `http://localhost:3114`. Добавьте `--enable-flow` для экспериментальной страницы графа архитектуры.
+Это запускает `iii console` закреплённого движка против портов, которые вычислил agentmemory (REST, стримы, bridge), и отдаёт его на порт выше просмотрщика — по умолчанию `http://localhost:3114`. `--console-port N` выбирает другой порт; `--port` и `--instance` выбирают инстанс agentmemory так же, как для `stop`; любой другой флаг передаётся дальше, например `--enable-flow` для экспериментальной страницы графа архитектуры.
-Переопределяйте эндпоинты движка только если вы их перенесли:
+То же самое вручную — пригодится, когда `agentmemory` не в PATH:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
@@ -1157,15 +1306,15 @@ iii console --port 3114 \
| Страница | Зачем |
|------|-----------|
-| **Workers** | Видеть каждый подключённый воркер и его живые метрики — включая сам воркер agentmemory. |
-| **Functions** | Напрямую вызывать любую функцию agentmemory с JSON-payload — удобно для тестов `memory.recall`, `memory.consolidate`, `graph.query` без подключения клиента. |
-| **Triggers** | Воспроизводить HTTP-, cron-, event- и state-триггеры — запустить cron консолидации вручную, повторить HTTP-маршрут, эмитировать изменение состояния. |
-| **States** | KV-браузер с полным CRUD — сессии, слоты памяти, lifecycle-таймеры, индекс эмбеддингов — редактирование значений на месте. |
+| **Workers** | Видеть каждый подключённый воркер и его живые метрики, включая сам воркер agentmemory. |
+| **Functions** | Напрямую вызывать любую функцию agentmemory с JSON-payload; удобно для тестов `memory.recall`, `memory.consolidate`, `graph.query` без подключения клиента. |
+| **Triggers** | Воспроизводить HTTP-, cron-, event- и state-триггеры: запустить cron консолидации вручную, повторить HTTP-маршрут, эмитировать изменение состояния. |
+| **States** | KV-браузер с полным CRUD по сессиям, слотам памяти, lifecycle-таймерам и индексу эмбеддингов; редактирование значений на месте. |
| **Streams** | Живой WebSocket-монитор для записей памяти, событий хуков и обновлений наблюдений по мере их прохождения через iii-стримы. |
| **Queues** | Долговечные топики очередей + управление dead-letter. Повтор или сброс упавших job'ов эмбеддинга / компрессии. |
| **Traces** | Виды waterfall / flame / разбивка по сервисам в OpenTelemetry. Фильтр по `trace_id` показывает, какие функции, обращения к БД и embedding-запросы породил отдельный `memory.search`. |
| **Logs** | Структурированные OTEL-логи, фильтруемые и коррелируемые с trace-/span-ID. |
-| **Config** | Конфигурация runtime — какие именно воркеры, провайдеры и порты использует ваш движок. |
+| **Config** | Конфигурация runtime: какие именно воркеры, провайдеры и порты использует ваш движок. |
| **Flow** | (Опционально, `--enable-flow`) Интерактивный граф архитектуры из всех воркеров, триггеров и стримов. |
@@ -1176,11 +1325,11 @@ iii console --port 3114 \
**Traces уже включены:**
-`iii-config.yaml` поставляется с включённым воркером `iii-observability` (`exporter: memory`, `sampling_ratio: 1.0`, метрики + логи). Дополнительная настройка не нужна — как только agentmemory запускается, каждая операция памяти эмитит trace-span и структурированный лог, который консоль читает.
+`iii-config.yaml` поставляется с включённым воркером `iii-observability` (`exporter: memory`, `sampling_ratio: 0.1`, метрики + логи). Дополнительная настройка не нужна: как только agentmemory запускается, каждая операция памяти эмитит структурированный лог, который может прочитать console, а каждая десятая из них (`sampling_ratio: 0.1`) ещё и trace-span.
-Если хотите экспортировать в Jaeger/Honeycomb/Grafana Tempo, измените `exporter: memory` на `exporter: otlp` и укажите эндпоинт коллектора согласно документации по observability в iii.
+Если вместо этого вы хотите экспортировать в Jaeger/Honeycomb/Grafana Tempo, замените `exporter: memory` на `exporter: otlp` и укажите эндпоинт коллектора согласно документации iii по observability.
-> **Внимание:** на самой console аутентификация не применяется — держите её привязанной к `127.0.0.1` (по умолчанию) и никогда не выставляйте наружу.
+> **Внимание:** на самой console аутентификация не применяется; держите её привязанной к `127.0.0.1` (по умолчанию) и никогда не выставляйте наружу.
---
@@ -1190,31 +1339,101 @@ agentmemory — это **уже работающий инстанс [iii](https:
Это значит, что одна дополнительная команда расширяет agentmemory целой новой возможностью.
-### Расширить 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
-```
+Встроенные воркеры, нужные agentmemory, уже прописаны в `iii-config.yaml` и загружаются вместе с ним: `iii-state` (KV), `iii-queue` (надёжные повторы для подписчиков событий), `iii-pubsub`, `iii-cron`, `iii-stream` и `iii-observability` (OTEL-трейсы, метрики и логи на каждой функции). Всё остальное из [реестра воркеров iii](https://workers.iii.dev) подключается к тому же движку: скопируйте `iii-config.yaml` в `~/.agentmemory/iii-config.yaml` (CLI предпочитает этот файл перед встроенным и всё равно подставляет в него порты и пути данных), добавьте запись, установите runtime воркера один раз через `~/.agentmemory/bin/iii update worker` и перезапустите agentmemory.
-Каждый `iii worker add` регистрирует новые функции и триггеры в том же движке, где уже работает agentmemory. Просмотрщик и console подхватывают их мгновенно — без перезагрузки, новой интеграции или нового контейнера.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | Что получаете сверху к agentmemory |
+| Воркер | Что вы получаете сверху к agentmemory |
|---|---|
-| [`iii-pubsub`](https://workers.iii.dev/workers/iii-pubsub) | Память на множестве инстансов: каждое `remember` разлетается, каждое `search` читает объединение |
-| [`iii-cron`](https://workers.iii.dev/workers/iii-cron) | Жизненный цикл по расписанию — ночная консолидация, еженедельные снапшоты, decay по фиксированному таймеру |
-| [`iii-queue`](https://workers.iii.dev/workers/iii-queue) | Надёжные повторы: упавшие job'ы эмбеддинга и компрессии переживают перезапуск, наблюдения не теряются |
-| [`iii-observability`](https://workers.iii.dev/workers/iii-observability) | OTEL-трейсы, метрики, логи на каждой функции — подключены в `iii-config.yaml` с первого дня |
+| [`database`](https://workers.iii.dev/workers/database) | SQL-адаптер состояния, когда дефолтная in-memory KV уже мала |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Код, пришедший из `memory_recall`, исполняется внутри одноразовой VM, а не в вашем shell |
-| [`iii-database`](https://workers.iii.dev/workers/iii-database) | SQL-адаптер состояния, когда дефолтная in-memory KV уже мала |
-| [`mcp`](https://workers.iii.dev/workers/mcp) | Поднять дополнительные MCP-серверы рядом с MCP'ом agentmemory, на одном и том же движке |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Поднять дополнительные MCP-серверы рядом с MCP agentmemory, на том же движке |
+
+На движке 0.22.x сохраняйте имена с префиксом `iii-` для встроенных воркеров выше; записи без префикса `http`, `state`, `queue`, `pubsub` и `cron` — это отдельные воркеры из реестра, на которые agentmemory переходит при миграции на 0.23.
+
+Полный реестр: [workers.iii.dev](https://workers.iii.dev). Каждый воркер там собирается из тех же примитивов, что и agentmemory, — и agentmemory, который у вас уже есть, — один из них.
+
+### Конфигурация движка и адрес привязки
+
+`agentmemory start` читает конфиг движка из первого существующего файла: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` в текущем каталоге, `~/.agentmemory/iii-config.yaml`, затем встроенный `iii-config.yaml`. При каждом запуске он подставляет в этот файл значения (пути данных, порты, backend состояния) в `~/.agentmemory/data/iii-config.runtime.yaml` и запускает движок с отрендеренной копией, поэтому редактируйте исходный файл, а не отрендеренный. Значения `host:` из исходного файла сохраняются как написаны.
+
+Встроенный `iii-config.yaml` намеренно слушает `127.0.0.1`, и это значение по умолчанию действует и внутри контейнера. CLI, запущенный в контейнере, слушает loopback контейнера, поэтому опубликованные порты никуда не ведут. Чтобы отдавать CLI в контейнере через опубликованные порты, задайте `AGENTMEMORY_III_CONFIG` на конфиг, который слушает `0.0.0.0`. Поставляемый `iii-config.docker.yaml` — именно такой: он привязывает `iii-http`, `iii-stream` и порт движка к `0.0.0.0` и хранит состояние в `/data`, так что смонтируйте туда доступный на запись том. Держите `AGENTMEMORY_SECRET` заданным и публикуйте только нужные вам порты — на `127.0.0.1` либо за доверенным прокси.
+
+`docker-compose.yml` этого репозитория не проходит через поиск конфига CLI: он монтирует `iii-config.docker.yaml` в `/app/config.yaml`, и контейнер `iii-engine` запускается с `--config /app/config.yaml`. Шаблоны [деплоя в один клик](../deploy/) пишут собственный конфиг `0.0.0.0` в своих entrypoint'ах.
+
+### Backend хранения: file (по умолчанию) против redis
+
+`iii-state` и `iii-stream` по умолчанию используют встроенное в iii-engine файловое KV-хранилище: один JSON-файл на scope, хранящийся в памяти процесса движка и перезаписываемый на диск по таймеру. Это правильное значение по умолчанию для локальной однопользовательской установки; общий демон с несколькими одновременными писателями вместо этого получает настоящую запись по ключу через Redis — за счёт сетевого round-trip на операцию (каждый вызов `state::*` всё равно сериализуется на одном Redis-соединении, так что это меняет блокировку файлового хранилища на сокет, а не на параллелизм).
+
+Задайте `AGENTMEMORY_STATE_BACKEND=redis` (плюс `AGENTMEMORY_REDIS_URL`), чтобы переключить оба воркера на встроенный в iii-engine адаптер `redis`, который хранит каждый ключ как поле Redis-хеша (`HSET`) вместо перезаписи всего scope при каждой записи:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` по умолчанию равен `file`; если не задавать его, сегодняшнее поведение не меняется, а нераспознанное значение (что угодно, кроме `file` или `redis`) — это ошибка запуска, а не тихий fallback. `/agentmemory/status` и страница Health просмотрщика (строка State store) сообщают, какой backend активен и отвечает ли он, но никогда не показывают URL.
+
+**Только простой `redis://`.** Закреплённый движок (0.22.1) собирает свой Redis-клиент без поддержки TLS, поэтому URL `rediss://` (большинство managed-предложений Redis, таких как Upstash, Redis Cloud и ElastiCache с шифрованием в пути, по умолчанию работают только через TLS) не подключается. Соединение нешифрованное, поэтому пароль Redis и каждая сохранённая запись памяти идут по проводу в открытом виде: указывайте на локальный Redis либо на Redis в доверенной приватной сети. Для любого другого Redis поднимите зашифрованный туннель (stunnel, SSH или VPN) на хосте agentmemory, чтобы простой переход `redis://` оставался на этом хосте, а восходящее соединение туннеля было зашифровано и аутентифицировано. Если пароль Redis содержит одиночную кавычку, percent-encode её (`%27`); движок подставляет URL в свой YAML-конфиг до разбора.
+
+**Один сервер Redis на `--instance`.** Префиксы Redis-ключей движка (`state:`, `stream::`) фиксированы, поэтому два инстанса agentmemory (`--instance 1`, `--instance 2`, ...), указывающие на одну базу данных, перезаписывают данные друг друга. Отдельный индекс базы данных (`redis://localhost:6379/1`) разделяет сохранённые данные, но движок передаёт живые события просмотрщика через один Redis pub/sub-канал (`stream::events`), а Redis pub/sub игнорирует индекс базы данных, так что просмотрщик каждого инстанса всё равно будет показывать живые события другого. Выделяйте каждому инстансу собственный сервер Redis (или порт), если запускаете больше одного.
+
+**Что остаётся тем же, а что отличается.** На Redis работает каждая функция agentmemory: сессии, наблюдения, записи памяти (remember, supersede, evolve, forget), поиск и бакеты индекса, уроки, граф, аудит-журнал и его месячные scope'ы, экспорт и импорт, governance-удаления, статус консолидации, снапшот просмотрщика и его живой стрим, а также монитор состояния. Движок хранит каждый scope как один Redis-хеш (`HSET`/`HGET`/`HGETALL`) и порождает те же state-триггеры, что и файловое хранилище. Три отличия движка обрабатываются внутри agentmemory:
+
+- Redis возвращает записи scope'а в произвольном порядке. agentmemory сортирует их от самых старых (по времени создания в id записи, затем по её timestamp'у), чтобы списки, постраничная навигация и чанки экспорта возвращались в том же порядке, что и на файловом хранилище.
+- Движок применяет частичные обновления на Redis через Lua-скрипт, который превращает пустые массивы в пустые объекты. agentmemory применяет эти обновления сам (чтение, изменение, запись под блокировкой на ключ) на Redis, поэтому поля вроде `tags: []` остаются массивами.
+- Проверка унаследованного аудит-журнала читает старый scope из Redis вместо поиска файла файлового хранилища на диске.
-Полный реестр: [workers.iii.dev](https://workers.iii.dev). Каждый воркер там собирается из тех же примитивов, что и agentmemory — и тот agentmemory, который у вас уже есть, — один из них.
+Одно отличие требует вашего участия: **после перезапуска Redis движок перестаёт передавать живые события** просмотрщику, пока agentmemory не перезапустят. Данные всё равно сохраняются и читаются нормально. Монитор состояния отправляет тестовое событие через Redis каждые 30 секунд; когда оно не возвращается, `/agentmemory/status` и страница Health просмотрщика показывают «Живые обновления не доходят до просмотрщика» с решением: перезапустить agentmemory. Если Redis недоступен, отчёт о статусе показывает «State store не отвечает» и как это проверить (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Листинг очень большого scope'а читает весь хеш за один `HGETALL` — та же цена, что и хранение его в памяти файловым хранилищем.
+
+**Рекомендуемые настройки Redis.** Политика снапшотов по умолчанию `save 3600 1 300 100 60 10000` может потерять минуты записей при крэше — хуже, чем окно сброса в 5 секунд у файлового хранилища. Задайте `appendonly yes` для всего, потерю чего вам было бы жаль. Задайте `maxmemory-policy noeviction`; `allkeys-lru` или похожие молча отбрасывают записи памяти, как только Redis упирается в лимит памяти.
+
+Нативный запуск (не Docker), а также каждый [шаблон деплоя в один клик](../deploy/) (они перезаписывают встроенный `iii-config.yaml` и стартуют нативно) читают `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` и подставляют их в запускаемый `iii-config`. Сам URL никогда не записывается в этот отрендеренный файл — только ссылка `${AGENTMEMORY_REDIS_URL}`, которую процесс движка раскрывает из собственного окружения при загрузке. Только собственный путь Docker Compose этого репозитория (`AGENTMEMORY_USE_DOCKER=1`, либо возобновление движка, уже запущенного так) монтирует `iii-config.docker.yaml` только для чтения и никогда не рендерит его; `agentmemory start` предупреждает, когда обнаруживает такое сочетание. Меняйте этот файл вручную, следуя той же форме `name: redis` / `config: redis_url: ...`, показанной в документации воркеров [iii-state](https://workers.iii.dev/workers/iii-state) и [iii-stream](https://workers.iii.dev/workers/iii-stream), и указывайте `redis_url` на Redis, доступный из контейнера. `docker-compose.yml` передаёт `AGENTMEMORY_REDIS_URL` в контейнер движка, так что там работает `redis_url: '${AGENTMEMORY_REDIS_URL}'`, и URL не попадает в смонтированный файл.
+
+Отрендеренный конфиг не содержит URL в `~/.agentmemory/data/iii-config.runtime.yaml`, но собственный конфигурационный воркер движка всё равно сохраняет *раскрытое* значение в `~/.agentmemory/config/iii-state.yaml` и `iii-stream.yaml` после загрузки (раскрытие `${VAR}` движком iii-engine происходит раньше, чем этот воркер сохраняет свой seed, и он сохраняет уже разрешённое значение, а не ссылку). Относитесь к этому каталогу как к хранилищу учётных данных: `chmod 700 ~/.agentmemory` на любом общем хосте, и предпочитайте ACL-пользователя Redis, ограниченного тем, что нужно agentmemory, а не админские учётные данные базы данных.
+
+**Миграция не автоматическая.** Переключение `AGENTMEMORY_STATE_BACKEND` начинается с пустого хранилища по обе стороны; ничто не копирует существующие данные из file в Redis или обратно. Экспортируйте из backend'а, который покидаете, и импортируйте в тот, на который переходите. Это работает одинаково под bash и zsh (включая `bash -u`). А вот массив вида `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` — нет: zsh сохраняет заголовок как одно некорректное слово, тогда как bash разбивает его на два, поэтому оба запроса получают 401, как только задан `AGENTMEMORY_SECRET`:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` также принимает `?maxSessions=` и `?offset=` для разбивки большого корпуса на несколько вызовов; `strategy` при импорте — это `merge` (безопасно по умолчанию), `replace` или `skip`.
### Что заменяет iii
@@ -1227,7 +1446,7 @@ iii worker add mcp # generic MCP host alongside the agentmemory
| Prometheus / Grafana | iii OTEL + монитор состояния |
| Самописные плагинные системы | `iii worker add ` |
-**182 исходных файла · ~41 600 LOC · 1 619 тестов · 264 функции · 50 KV-scope'ов** — всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
+**225 исходных файлов · ~54,000 LOC · 2,600+ тестов · 312 функция · 66 KV-scope'ов**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
---
@@ -1235,18 +1454,18 @@ iii worker add mcp # generic MCP host alongside the agentmemory
### LLM-провайдеры
-agentmemory автоопределяет провайдера по окружению. По умолчанию никакие вызовы LLM не выполняются, пока вы не настроите провайдера или явно не включите fallback на подписку Claude.
+agentmemory автоопределяет провайдеров по вашему окружению. Провайдер делает доступными операции на базе LLM, но сама конфигурация провайдера сама по себе не включает сжатие наблюдений, написанное LLM. Для этого пути нужны и провайдер, и `AGENTMEMORY_AUTO_COMPRESS=true`.
| Провайдер | Конфигурация | Заметки |
|----------|--------|-------|
-| **No-op (по умолчанию)** | Настройка не нужна | LLM-сжатие/резюме ВЫКЛЮЧЕНО. Синтетическое BM25-сжатие и recall продолжают работать. Если вы раньше полагались на fallback подписки Claude — см. `AGENTMEMORY_ALLOW_AGENT_SDK` ниже. |
+| **No-op (по умолчанию)** | Настройка не нужна | LLM-сжатие/резюме отключено. Синтетическое сжатие и recall через BM25 продолжают работать. См. `AGENTMEMORY_ALLOW_AGENT_SDK` ниже, если вы раньше полагались на fallback подписки Claude. |
| Anthropic API | `ANTHROPIC_API_KEY` | Поминутная (token-based) оплата |
| MiniMax | `MINIMAX_API_KEY` | Совместим с Anthropic |
| Gemini | `GEMINI_API_KEY` | Дополнительно включает эмбеддинги |
| OpenRouter | `OPENROUTER_API_KEY` | Любая модель |
| OpenAI API | `OPENAI_API_KEY` | По умолчанию `gpt-5.6-luna`, переопределяется через `OPENAI_MODEL` |
-| **Локально (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) или `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Всё, что совместимо с OpenAI API. Нулевая стоимость, работает на вашем железе. См. [Локальные модели](#local-models-ollama--lm-studio--vllm) ниже. |
-| Fallback на подписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Только по согласию. Запускает сессии `@anthropic-ai/claude-agent-sdk`; раньше он приводил к неограниченной рекурсии Stop-хука, потому больше не по умолчанию. |
+| **Локально (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) либо `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Всё, что совместимо с OpenAI API. Нулевая стоимость, работает на вашем железе. См. [Локальные модели](#local-models-ollama--lm-studio--vllm) ниже. |
+| Fallback на подписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Только по согласию. Запускает сессии `@anthropic-ai/claude-agent-sdk`; раньше это приводило к неограниченной рекурсии Stop-хука, поэтому больше не включено по умолчанию. |
### Локальные модели (Ollama / LM Studio / vLLM)
@@ -1283,30 +1502,30 @@ OPENAI_MODEL=qwen3-8b # match the model name from LM St
| Модель | Размер | Почему |
|-------|------|-----|
-| `qwen3:8b` | ~5,2 ГБ | Сбалансированный вариант по умолчанию на машине с 16 ГБ; силён в извлечении и tool-образном тексте |
-| `qwen3:4b` | ~2,6 ГБ | Наименьший разумный вариант; годится для сжатия, слабее для извлечения графа |
-| `qwen3-coder:30b` | ~19 ГБ | Лучший локальный выбор для code-сессий (30B MoE, 3,3B активных) на железе с 24–32 ГБ |
+| `qwen3:8b` | ~5.2 ГБ | Сбалансированный вариант по умолчанию на машине с 16 ГБ; силён в извлечении и tool-образном тексте |
+| `qwen3:4b` | ~2.6 ГБ | Наименьший разумный вариант; годится для сжатия, слабее для извлечения графа |
+| `qwen3-coder:30b` | ~19 ГБ | Лучший локальный выбор для code-сессий (30B MoE, 3.3B активных) на железе с 24–32 ГБ |
| `gpt-oss:20b` | ~14 ГБ | Сильная общая модель, помещающаяся в 16 ГБ RAM |
-| `deepseek-r1:8b` | ~5,2 ГБ | Reasoning-дистилляция; медленнее, но извлечения чище |
+| `deepseek-r1:8b` | ~5.2 ГБ | Reasoning-дистилляция; медленнее, но извлечения чище |
Модели Qwen 3 думают по умолчанию и могут сжечь весь токен-бюджет на рассуждения до какого-либо вывода. Установите `AGENTMEMORY_LLM_NOTHINK=1`, чтобы добавлять `/no_think` к промптам извлечения графа, и поднимите `MAX_TOKENS` (16384 работает), если извлечения возвращаются пустыми.
Модели reasoning-класса (в стиле `o1` с блоками ``) могут вернуть пустой `content` с полем `reasoning`, которое ваш локальный сервер может не отдавать. Если извлечения приходят пустыми, сначала переключитесь на модель без reasoning. Переменная `OPENAI_REASONING_EFFORT=none` также умеет отключать thinking у thinking-моделей Ollama Cloud, которые повторяют reasoning-схему OpenAI.
-Локальные эмбеддинги поставляются из коробки через `@huggingface/transformers`: `EMBEDDING_PROVIDER=local` (по умолчанию) даёт `Xenova/all-MiniLM-L6-v2` (384-мерная) целиком на устройстве. Дополнительная настройка не нужна.
+Локальные эмбеддинги поставляются как опциональная зависимость, но не включены по умолчанию. Задайте `EMBEDDING_PROVIDER=local`, чтобы подключить `Xenova/all-MiniLM-L6-v2` (384 измерения). Первый запрос эмбеддинга скачивает модель; после этого инференс выполняется на устройстве. Без этой настройки или удалённого ключа эмбеддингов векторы остаются отключены, `mem::search` использует BM25, а `smart-search` всё равно может добавлять существующие совпадения из графа.
### Выбор модели с учётом стоимости
-Фоновое сжатие выполняется на каждом наблюдении, поэтому выбор модели заметно влияет на ежемесячные расходы. Замеренные данные нагрузки: 635 запросов / 888K токенов / 35 часов активного использования, прогон против трёх моделей OpenRouter по ценам на 2026-05-23.
+Когда фоновое сжатие, написанное LLM, включено — то есть заданы и провайдер, и `AGENTMEMORY_AUTO_COMPRESS=true` — оно выполняется на каждом наблюдении, поэтому выбор модели заметно влияет на ежемесячные расходы. Замеренные данные нагрузки: 635 запросов / 888K токенов / 35 часов активного использования, прогон против трёх моделей OpenRouter по ценам на 2026-05-23.
| Уровень | Модель | Вход / 1M | Выход / 1M | Стоимость за зафиксированные 35 ч | Заметки |
|------|-------|------------|-------------|---------------------------|-------|
-| Рекомендовано | `deepseek/deepseek-v4-flash-0731` | 0,07 $ | 0,14 $ | ~0,07 $ (оценка) | Самый свежий DeepSeek; самый дешёвый рекомендуемый вариант для нагрузок сжатия. |
-| Рекомендовано | `deepseek/deepseek-v4-pro` | 0,435 $ | 0,87 $ | ~0,46 $ | Хорошее качество сжатия и резюмирования при стоимости ~10× ниже Sonnet. |
-| Рекомендовано | `qwen/qwen3-coder` | 0,45 $ | 1,80 $ | ~0,55 $ | Сильное code-reasoning, если ваши сессии сильно завязаны на код. |
-| Premium | `anthropic/claude-sonnet-5` | 3,00 $ | 15,00 $ | ~5,02 $ (оценка) | Тот же прайс, что у замеренного прогона Sonnet 4.6; вводная цена $2/$10 до 2026-08-31. |
-| Premium | `openai/gpt-5.6-sol` | 5,00 $ | 30,00 $ | ~9 $ (оценка) | Флагманский уровень; дорого для постоянной фоновой работы. |
-| Избегать | `anthropic/claude-opus-5` | 5,00 $ | 25,00 $ | ~8,40 $ (оценка) | Модель флагманского класса; перерасход на сжатие. |
+| Рекомендовано | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (оценка) | Самый свежий DeepSeek; самый дешёвый рекомендуемый вариант для нагрузок сжатия. |
+| Рекомендовано | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Хорошее качество сжатия и резюмирования при стоимости ~10× ниже Sonnet. |
+| Рекомендовано | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Сильное code-reasoning, если ваши сессии сильно завязаны на код. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (оценка) | Тот же прайс, что у замеренного прогона Sonnet 4.6; вводная цена $2/$10 до 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (оценка) | Флагманский уровень; дорого для постоянной фоновой работы. |
+| Избегать | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (оценка) | Модель флагманского класса; перерасход на сжатие. |
Замеренные строки взяты из зафиксированного прогона; строки «(оценка)» масштабируют тот же микс токенов по прайс-листу каждой модели.
@@ -1336,7 +1555,7 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
Что помечается, когда `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=` для переопределения на конкретный запрос и `?agentId=*`, чтобы полностью выйти из env-scope. `/memories` дополнительно принимает `?includeOrphans=true`, чтобы поднять «доисторические» записи памяти, у которых `agentId` не определён.
+Что фильтруется в режиме isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Каждый эндпоинт принимает `?agentId=` для переопределения на конкретный запрос и `?agentId=*`, чтобы полностью выйти из env-scope. `/memories` дополнительно принимает `?includeOrphans=true`, чтобы поднять записи памяти до появления `AGENT_ID`, у которых `agentId` не определён.
Переопределение в самом вызове на уровне SDK / REST: каждый мутирующий эндпоинт (`/session/start`, `/remember`) принимает поле `agentId` в теле запроса, которое выигрывает у env. Полезно для runtime'ов, прогоняющих много ролей через один серверный процесс. Инструмент MCP `memory_save` раскрывает то же поле `agentId`, автономный stdio-сервер пробрасывает и `agentId`, и `project`, а сохранённые записи памяти несут `agentId` в поисковый индекс, поэтому поиск со scope'ом агента покрывает записи памяти так же, как наблюдения.
@@ -1349,11 +1568,15 @@ agentmemory + iii-engine по умолчанию занимают четыре
| Порт | Процесс | Назначение | Override через 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`) |
+| `3112` | iii-engine | Внутренний streams-воркер (используется agentmemory + просмотрщиком) | `III_STREAM_PORT` (предпочтительно) либо устаревший `III_STREAMS_PORT` |
+| `3113` | agentmemory | Просмотрщик в реальном времени (`http://localhost:3113`) | `III_VIEWER_PORT` либо `AGENTMEMORY_VIEWER_URL` для возвращаемого URL |
+| `49134` | iii-engine | WebSocket; воркеры регистрируются здесь, по нему же течёт OTel-телеметрия | `III_ENGINE_PORT` либо `III_ENGINE_URL` |
+
+`--port ` меняет якорь REST и выводит из него streams `N+1`, просмотрщик `N+2` и WebSocket движка `N+46023`, но только там, где соответствующий явный порт или URL выше не задан. Это не создаёт изолированный lifecycle-namespace. Используйте `--instance 1` для второго демона; он использует якорь 3211, по умолчанию даёт `3211/3212/3213/49234` и получает отдельный каталог данных и lifecycle `instance-1`. Инстансы с 1 по 50 следуют тому же паттерну.
+
+Закреплённый движок запускается с `--no-update-check` (без обращения к GitHub за обновлениями или security-advisory при загрузке) и с выключенной анонимной телеметрией использования iii: agentmemory задаёт `III_TELEMETRY_ENABLED=false` для порождаемого им движка, если вы не экспортировали эту переменную сами, и встроенный compose-файл делает то же самое.
-Очистка зависших процессов, если порты остаются занятыми после падения:
+Очистка зависших процессов, если порты остаются занятыми после падения:
```bash
# macOS / Linux — find whatever is on each port and kill it
@@ -1366,7 +1589,7 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` корректно вычищает и воркер, и pidfile движка при штатном завершении. В Docker-режиме команда сворачивает только собственные compose-сервисы agentmemory и вычищает нативный воркер до остановки Docker; CLI также отказывается принимать за нативный движок или сигналить держателям портов из Docker или VM (Docker backend, vpnkit, colima), пока не передан `--force`. Ручная очистка выше нужна только в посткрэшевом сценарии, когда ни один pidfile не остался.
+`agentmemory stop` аккуратно вычищает и воркер, и pidfile движка при штатном нативном завершении. В режиме Docker она сбрасывает нативный воркер, останавливает именно тот проверенный контейнер движка и сохраняет и контейнер, и его том `/data` для безвозвратного перезапуска; следующий запуск проверяет и возобновляет тот же контейнер. Удаление при работе через Docker требует `agentmemory remove --keep-data`: она удаляет общие файлы, управляемые agentmemory, сохраняя при этом проверенный контейнер, его том данных и запись о жизненном цикле, нужную для их восстановления. Деструктивное удаление данных Docker намеренно оставлено оператору — после бэкапа. CLI также отказывается принимать за нативный движок или сигналить держателям портов из Docker или VM (Docker backend, vpnkit, colima), пока не передан `--force`. Ручная очистка выше нужна только в посткрэшевом сценарии, когда ни один pidfile не остался.
### Конфигурационный файл
@@ -1381,18 +1604,20 @@ New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
-Чтобы протестировать с подпиской Claude Code Pro/Max вместо API-ключа, включите её явно:
+Чтобы протестировать с подпиской Claude Code Pro/Max вместо API-ключа, включите это явно:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-В этом же файле включите возможности графа или консолидации, если они нужны:
+Сжатие наблюдений, написанное LLM, требует обе строки: доступ к провайдеру LLM (включая этот явный fallback на подписку) и `AGENTMEMORY_AUTO_COMPRESS=true`. Один только провайдер оставляет в силе путь синтетического сжатия по умолчанию.
+
+Консолидация (узлы графа, уроки, crystals) включена по умолчанию, когда настроен провайдер LLM. Явно отключите её через `CONSOLIDATION_ENABLED=false`, если хотите работать без LLM. Извлечение графа — отдельный флаг:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Переменные окружения
@@ -1434,13 +1659,15 @@ CONSOLIDATION_ENABLED=true
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1458,14 +1685,20 @@ CONSOLIDATION_ENABLED=true
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1506,13 +1739,43 @@ CONSOLIDATION_ENABLED=true
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
-# CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1526,7 +1789,19 @@ CONSOLIDATION_ENABLED=true
-124 эндпоинта на порту `3111`. REST API по умолчанию слушает на `127.0.0.1`. Защищённые эндпоинты требуют `Authorization: Bearer `, когда установлен `AGENTMEMORY_SECRET`, а эндпоинты mesh-синхронизации требуют `AGENTMEMORY_SECRET` на обоих узлах.
+138 эндпоинтов на порту `3111`. REST API по умолчанию слушает на `127.0.0.1`. Защищённые эндпоинты требуют `Authorization: Bearer `, а эндпоинты mesh-синхронизации требуют явно заданного `AGENTMEMORY_SECRET` на обоих узлах.
+
+**Аутентификация включена по умолчанию.** Когда `AGENTMEMORY_SECRET` не задан (ни в shell, ни в `~/.agentmemory/.env`), сервер генерирует случайный секрет при первом запуске и хранит его в `~/.agentmemory/secret` с правами `0600`. Каждый встроенный клиент читает его оттуда, когда говорит с локальным сервером: CLI, просмотрщик, хуки из `plugin/scripts`, MCP-сервер и shim `@agentmemory/mcp`, конфиги, записанные `agentmemory connect`, и встроенные интеграции OpenCode, Pi, OpenClaw, Hermes и filesystem-watcher. Сохранённый секрет отправляется только на loopback-адреса (`localhost`, `127.0.0.0/8`, `::1`). Явно заданный `AGENTMEMORY_SECRET` всегда выигрывает, и удалённым клиентам он всё равно нужен. Docker и entrypoint'ы `deploy/` уже генерируют и экспортируют собственный секрет. Чтобы вызвать API вручную:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Правила запросов для записи.** Запросы `POST`, `PUT`, `PATCH` и `DELETE` к REST API и просмотрщику должны отправлять `Content-Type: application/json` (параметр `charset` допустим), когда у них есть тело, а заголовок `Origin`, если он есть, должен быть loopback-origin для настроенного порта REST или просмотрщика, либо быть перечислен в `VIEWER_ALLOWED_ORIGINS` (через запятую, например `https://memory.example.com`). Клиенты, которые не отправляют заголовок `Origin` (CLI, хуки, MCP, curl, сервер-сервер), не затрагиваются. Просмотрщик также принимает собственный origin.
+
+**Пути к файлам.** Эндпоинты, которые читают или пишут файлы (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), принимают только пути внутри `~/.agentmemory`, каталога данных инстанса или каталога, перечисленного в `AGENTMEMORY_IMPORT_ROOT` (разделяйте несколько через `:`, либо `;` на Windows). `/replay/import-jsonl` также принимает свой каталог по умолчанию `~/.claude/projects`. `/obsidian/export` остаётся внутри `AGENTMEMORY_EXPORT_ROOT`, а `/migrate` — внутри `~/.agentmemory`. Симлинки разрешаются перед каждой проверкой.
+
+**Вычистка секретов.** API-ключи, bearer-токены, блоки приватных ключей PEM и учётные данные, встроенные в URL (`scheme://user:password@host`), вырезаются из текста до сохранения — на каждом пути записи: наблюдения, remember, evolve, slots, уроки, action'ы, sketches, сигналы, checkpoints, импорты, jsonl replay, mesh sync, team shares, вывод сжатия и резюме, crystals и узлы графа.
Ключевые эндпоинты
@@ -1534,9 +1809,14 @@ CONSOLIDATION_ENABLED=true
| Метод | Путь | Описание |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Проверка состояния (всегда публична) |
+| `GET` | `/agentmemory/status` | Что не так и как это исправить (HTML для браузеров, иначе JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Всё, что показывает просмотрщик, в одном ответе |
| `POST` | `/agentmemory/session/start` | Запуск сессии + получение контекста |
| `POST` | `/agentmemory/session/end` | Завершение сессии |
-| `POST` | `/agentmemory/observe` | Захват наблюдения |
+| `POST` | `/agentmemory/observe` | Захват наблюдения (см. доставку захвата ниже) |
+| `GET` | `/agentmemory/capture` | Инбокс захвата, dead letters и offline-spool |
+| `POST` | `/agentmemory/capture/retry` | Повторить захваты из dead letter |
+| `POST` | `/agentmemory/capture/drain` | Немедленно отправить локальный offline-spool |
| `POST` | `/agentmemory/smart-search` | Гибридный поиск |
| `POST` | `/agentmemory/context` | Генерация контекста |
| `POST` | `/agentmemory/remember` | Сохранить в долговременную память |
@@ -1546,6 +1826,7 @@ CONSOLIDATION_ENABLED=true
| `GET` | `/agentmemory/export` | Экспорт всех данных |
| `POST` | `/agentmemory/import` | Импорт из JSON |
| `POST` | `/agentmemory/graph/query` | Запрос к графу знаний |
+| `POST` | `/agentmemory/graph/compact` | Усечь разросшееся происхождение графа |
| `POST` | `/agentmemory/team/share` | Расшарить в команду |
| `GET` | `/agentmemory/audit` | Аудит-журнал |
@@ -1553,6 +1834,35 @@ CONSOLIDATION_ENABLED=true
+**Доставка захвата.** Хуки отправляют каждое наблюдение один раз в `POST /agentmemory/observe` с `eventId`. Это собственный id вызова от хоста, если он есть в payload'е (например, `tool_use_id` у Claude Code), иначе — хеш сессии, типа хука, имени инструмента, входа, выхода и timestamp'а хоста. Сервер записывает событие в инбокс захвата в state store, сохраняет наблюдение, затем удаляет запись из инбокса. Код статуса говорит о том, что произошло:
+
+| Статус | поле `status` | Значение |
+|---|---|---|
+| `201` | `accepted` | Сохранено. `observationId` — новое наблюдение. |
+| `202` | `accepted` (`state: "retrying"`) | Принято, но сохранение не удалось. Сервер повторяет попытку, в том числе после перезапуска. |
+| `200` | `duplicate` | Этот `eventId` уже был принят. `observationId` — существующее наблюдение; новое не сохраняется. |
+| `400` / `422` | `rejected` | Некорректный payload, либо сохранение окончательно не удалось (событие сохраняется как dead letter). |
+| `503` | `rejected` (`retryable: true`) | Инбокс заполнен (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Хуки откладывают событие в spool и отправляют его позже. |
+
+Неудавшиеся события повторяются каждые `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 с) с удваивающимся backoff'ом, до `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5) попыток. События, которые всё равно не проходят, остаются в инбоксе как dead letters, перечисляются на `/agentmemory/status` и странице Health просмотрщика, и их можно повторить через `POST /agentmemory/capture/retry` (`{"eventId": "..."}` или `{"all": true}`). Принятые id событий запоминаются на `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 часов, не больше `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), поэтому хук, воспроизведённый после таймаута или перезапуска, сохраняется один раз, тогда как два отдельных вызова инструмента со своими собственными host-id сохраняются дважды, даже если их содержимое идентично. Когда наблюдение удаляется (forget, удаление сессии, вытеснение, авто-забывание или импорт, заменяющий хранилище), его событие помечается как удалённое до удаления самого наблюдения, поэтому повтор этого события в том же окне отвечается как дубликат и ничего не сохраняет. State store пишет на диск каждые 2 секунды, поэтому отвеченное событие может ещё на мгновение существовать только в памяти. Чтобы это покрыть, каждый ответ `2xx` также несёт `bootId` сервера (новый при каждом запуске), `acceptedAt` и `durableAfterMs` (интервал сохранения плюс 1.5 с на файловом хранилище, 1.5 с на redis, где устойчивость — настройка оператора). Хуки держат событие в локальном spool, пока это окно не пройдёт, и удаляют его при следующем вызове без дополнительного запроса. Если к этому моменту `bootId` изменился, сервер перезапустился, поэтому хук отправляет событие снова с тем же `eventId`; событие, которое всё же достигло диска, не сохраняется дважды. Сервер также сам отправляет такие события при запуске и на каждом интервале повтора, поэтому перезапуск ничего не теряет, даже если после него не запускается ни один хук. Старые хуки игнорируют дополнительные поля, а новые хуки против старого сервера отбрасывают событие на `2xx`, как и раньше.
+
+Когда сервер недоступен, не отвечает вовремя или возвращает 5xx, хук добавляет наблюдение в локальный spool-файл `/capture-spool/-.jsonl` (переопределите папку через `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Файл приватен для вашего пользователя (права 600), секреты вырезаются так же, как их вырезает сервер, он хранит не больше `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) и отбрасывает записи старше `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Когда он заполнен, новые записи отбрасываются и считаются, и `/agentmemory/status` сообщает об этом. Хук всё равно завершается с кодом 0 в пределах своего лимита времени и не добавляет ни одного запроса, когда сервер здоров. Spool отправляется при следующем запуске и первым хуком, который снова достучится до сервера, в фоновом процессе, чтобы агент не ждал. Id событий делают это безопасным: наблюдение, которое всё же дошло до таймаута, не сохраняется дважды. `npx @agentmemory/agentmemory capture` показывает spool и инбокс сервера, `--drain` отправляет spool сейчас, а `GET /agentmemory/capture` возвращает то же самое в JSON. Задайте `AGENTMEMORY_CAPTURE_SPOOL=false`, чтобы отключить spool.
+
+**Усечение происхождения графа.** Каждый узел и ребро графа знаний хранит id самых новых 32 наблюдений, из которых он возник. Хранилища, записанные до этого ограничения, могут держать тысячи id на горячий узел, из-за чего поиск по графу и просмотрщик замедляются или роняют воркер. agentmemory сам это исправляет: при первом запуске после обновления он усекает каждый узел, ребро, вытесненное ребро (темпоральная история графа) и кэшированный снапшот до лимита в фоне, небольшими порциями с паузой между ними, так что поиск, захват и просмотрщик продолжают работать. Он сохраняет свой прогресс, продолжает после перезапуска и больше никогда не запускается снова после завершения. `/agentmemory/status` и страница Health просмотрщика показывают его как pending, running (с текущим scope и позицией), done или failed. Задайте `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`, чтобы отключить его.
+
+Чтобы запустить его вручную, вызовите `POST /agentmemory/graph/compact`. Он проходит по индексам имён и edge-key вместо перечисления каждого узла и ребра, и его безопасно запускать повторно. Когда он усекает id, он пишет запись аудита `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+На большом хранилище, либо когда вызов возвращает 504, запускайте его порциями. Отправьте `scope` (`nodes`, `edges` или `history`), `offset` и `limit`, затем вызывайте снова с возвращённым `nextOffset`, пока он не станет `null`. Сделайте это для `nodes`, `edges` и `history`, и завершите одним вызовом `{"scope":"snapshot"}`, потому что порционный запуск не трогает кэшированный снапшот.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1560,11 +1870,11 @@ CONSOLIDATION_ENABLED=true
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
+npm test # 2,600+ tests
npm run test:integration # API tests (requires running services)
```
-**Требования:** Node.js >= 20, [iii-engine](https://iii.dev/docs) или Docker
+**Требования:** Node.js >= 20 с npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 или Docker. Автоматическая установка движка на macOS/Linux также требует `curl`, POSIX-совместимый `sh` и `tar`; нативный Windows использует вручную установленный закреплённый `iii.exe`, WSL2 или Docker Desktop.
diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.md
new file mode 100644
index 0000000000..1ee7fbd048
--- /dev/null
+++ b/READMEs/README.sv-SE.md
@@ -0,0 +1,1872 @@
+
+
+
+
+
+
+ Din kodningsagent minns allt. Inget mer återförklarande.
+ Byggt på iii engine
+
+ Beständigt minne för Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode och alla MCP-klienter.
+
+
+---
+
+## Installation
+
+Krav:
+
+- Node.js 20 eller nyare med npm och npx (`node -v`, `npm -v` och `npx -v`).
+- Automatisk installation av iii-engine på macOS/Linux kräver också `curl`, ett POSIX-`sh` och `tar`. Minimala avbildningar som `node:20-slim` kan sakna dem.
+- Native Windows kräver att den fastlåsta iii-engine v0.22.1 `iii.exe` installeras manuellt. WSL2 eller Docker Desktop är de andra vägarna som stöds.
+
+Det kanoniska kommandot för en ny installation:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Den första körningen är en interaktiv konfiguration: du väljer vilka agenter som ska kopplas in (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), väljer en LLM-leverantör eller kör nyckelfritt, och den sår konfigurationen, startar minnesservern och dess fastlåsta iii-engine, samt erbjuder sig att installera globalt så att det bara kommandot `agentmemory` fungerar överallt därefter. `-y` accepterar npx:s paketfråga och `@latest` undviker en inaktuell cachad version. En leverantör gör LLM-funktioner tillgängliga, men LLM-skriven observationskomprimering startar bara när `AGENTMEMORY_AUTO_COMPRESS=true` också är satt.
+
+Nyckelfritt läge inaktiverar vektor-embeddings. `memory_recall` (vägen `mem::search`) använder BM25, medan `memory_smart_search` också kan sammanfoga strukturella grafmatchningar när grafdata redan finns. För kostnadsfri semantisk återkallning på enheten, sätt `EMBEDDING_PROVIDER=local` i `~/.agentmemory/.env` och starta om. Den första embedding-förfrågan laddar ner `Xenova/all-MiniLM-L6-v2`; efter den initiala modellnedladdningen körs inferensen lokalt.
+
+Den lokala körtiden använder fyra portar: `3111` för REST/MCP HTTP, `3112` för iii-strömmar, `3113` för viewern och `49134` för iii-workerns WebSocket. Beständigt iii-state ligger i `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, och `%APPDATA%\agentmemory` på Windows. Använd `--data-dir ` eller `AGENTMEMORY_DATA_DIR` för att åsidosätta detta, och återanvänd samma värde vid varje omstart. Av bakåtkompatibilitetsskäl prioriteras en befintlig `./data/state_store.db` eller `./data/iii-config.yaml` framför plattformens standard för instans 0; en explicit flagga eller miljövariabel vinner fortfarande.
+
+Bevisa sedan att återkallning fungerar och ge din agent dess skills:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Nyckelordssökningarna bör träffa i standardläget utan nyckel via BM25. Demots fråga `database performance optimization` är avsiktligt semantisk och kan ge noll resultat förrän en embedding-leverantör har konfigurerats.
+
+Föredrar du att låta en kodningsagent sköta hela installationen? Ge den en enda instruktion:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Koppla in fler agenter när du vill med `agentmemory connect ` — 20 adaptrar listade under [Fungerar med alla agenter](#works-with-every-agent). Fullständig kommandoreferens finns under [Snabbstart](#quick-start).
+
+
+Windows
+
+Den snabbaste vägen är WSL2. Native Windows-motorinstallation kräver att den fastlåsta v0.22.1-ZIP-filen laddas ner och att `iii.exe` extraheras manuellt; CLI:n extraherar inte automatiskt. Docker Desktop stöds också. Se [Windows-anteckningarna](#windows) för steg-för-steg-instruktioner.
+
+
+
+
+Global installation / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+npx-kommandot ovan är fortfarande den kanoniska vägen för en ny installation och undviker behörighetsproblem med den globala prefix-katalogen.
+
+
+
+
+npx levererar en gammal version
+
+npx cachar per version. Tvinga fram den senaste med `npx -y @agentmemory/agentmemory@latest`, eller rensa cachen en gång med `rm -rf ~/.npm/_npx` (macOS/Linux; på Windows, radera `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Kör redan din egen iii-engine
+
+agentmemory fastlåser iii-engine v0.22.1 och kopplar inte in sig på en annan version (workern kan inte tala en annan engines protokoll). Stoppa den andra enginen och köra sedan `npx -y @agentmemory/agentmemory@latest`. Den installerar och kör den fastlåsta v0.22.1 i `~/.agentmemory/bin`, utan att röra din egen `iii`.
+
+
+
+---
+
+
+
+agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. Alla agenter delar samma minnesserver.
+
+
+ Fungerar med alla agenter som talar MCP eller HTTP. En server, minnen delade mellan dem alla.
+
+
+---
+
+Du förklarar samma arkitektur varje session. Du upptäcker samma buggar på nytt. Du lär agenten samma preferenser på nytt. Inbyggt minne (CLAUDE.md, .cursorrules) toppar ut vid 200 rader och blir inaktuellt. agentmemory löser detta. Det fångar tyst vad din agent gör, komprimerar det till sökbart minne och injicerar rätt kontext när nästa session startar. Ett kommando. Fungerar mellan agenter.
+
+**Vad som förändras:** I session 1 sätter du upp JWT-autentisering. I session 2 ber du om rate limiting. Agenten vet redan att din autentisering använder jose-middleware i `src/middleware/auth.ts`, att dina tester täcker tokenvalidering, och att du valde jose framför jsonwebtoken för Edge-kompatibilitet — utan återförklaring och utan att klistra in kod på nytt.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Som standard lagrar agentmemory iii-engine-state utanför det repo du startar den från: `~/Library/Application Support/agentmemory` på macOS, `$XDG_DATA_HOME/agentmemory` eller `~/.local/share/agentmemory` på Linux, och `%APPDATA%\agentmemory` på Windows. En befintlig äldre `./data/state_store.db` eller `./data/iii-config.yaml` återanvänds för instans 0 före den plattformsstandarden. För att välja en plats explicit, ange `--data-dir ` eller sätt `AGENTMEMORY_DATA_DIR`; båda explicita inställningarna har företräde framför den äldre upptäckten:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native och Docker-baserade starter använder samma upplösta värdkatalog; Docker bind-monterar den på `/data`. `--instance 1` lägger till `instance-1` i den upplösta katalogen och väljer den separata standardportkvartetten `3211/3212/3213/49234`.
+
+Senaste versionsanteckningarna: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Hämtningsnoggrannhet
+
+**coding-agent-life-v1** (internt korpus, reproducerbart i sandbox)
+
+| Adapter | P@5 | R@5 | Topp-5-träffrate | p50-latens |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep-baslinje | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% topp-5-träffrate vid **P@5-mattaket** för detta korpus (0.240, se scorecard). Hybrid hämtar varje gold-session; grep missar 1 av 2 gold på den flersessions-temporala frågan. Lyftet ligger i **recall + temporal**, inte i aggregerad precision. Detta benchmark är litet och gold-glest; det större LongMemEval-S nedan differentierar bättre. Fullständig uppdelning per typ + rättelsenotis: [`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 frågor)
+
+| System | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| Endast BM25-fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+Benchmark-notis: det är bara agentmemorys R@5 som är vårt eget uppmätta resultat (LongMemEval-S, reproducerbart från benchmark/COMPARISON.md). Siffrorna för mem0 och Letta är deras publicerade LoCoMo-siffror (ett annat dataset); siffrorna för MemPalace, supermemory, TencentDB (PersonaMem) och oracleagentmemory är leverantörens egna rapporterade påståenden som vi inte har reproducerat oberoende (oracleagentmemorys körning använde GPT-5.5 mot en Oracle AI Database). Visas sida vid sida enbart som fingervisning, inte en head-to-head på identisk data. Stjärnantal är ungefärliga och förändras över tid.
+
+**Nyare aktörer** värda att känna till, jämförda på djupet i [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| System | ⭐ | Inriktning |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporal kunskapsgraf; starkast publicerade resultat för temporala frågor (LongMemEval 63.8%), men grafen byggs asynkront så färska fakta kan ligga efter |
+| Cognee | 30K | Dokument-till-kunskapsgraf-inmatning, endast Python, byggt för strukturerad entitetsextraktion snarare än sessionsinfångning |
+
+Ingen av dessa fångar automatiskt in data från kodningsagent-hooks, levererar en local-first viewer eller körs nyckelfritt — kombinationen agentmemory är byggt kring.
+
+---
+
+
+
+Kompatibilitet: den här utgåvan riktar sig mot `iii-sdk` 0.22.1 och fastlåser iii-engine v0.22.1.
+
+### Prova det på 30 sekunder
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` sår 3 realistiska sessioner (JWT-autentisering, fix av N+1-fråga, rate limiting) och kör sökningar mot dem. Nyckelfria installationer inaktiverar vektorer, så nyckelordsfrågorna via `mem::search` bör träffa via BM25 medan `database performance optimization` kan ge noll resultat. `smart-search` kan dessutom returnera strukturella grafmatchningar när grafdata finns. För att få den semantiska frågan att hitta N+1-fixen via vektorer, sätt `EMBEDDING_PROVIDER=local`, starta om, och låt den första modellnedladdningen slutföras.
+
+Öppna `http://localhost:3113` för att se minnet byggas upp i realtid.
+
+### Validera en ny installation och omstarts-persistens
+
+Med servern igång, validera REST, hälsostatus, viewern och den iii-baserade körtidsstatusen:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Startpanelen för redo-status tar hänsyn till alla fyra portar: REST/MCP HTTP på 3111, iii-strömmar på 3112, viewern på 3113 och iii-workerns WebSocket på 49134. `status` bekräftar agentmemorys hälsa och det aktiva leverantörs-/embedding-läget. Spara en testpunkt och bekräfta att den är sökbar:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Kör sedan `npx -y @agentmemory/agentmemory@latest stop`, starta det kanoniska kommandot igen i Terminal 1, vänta på `/agentmemory/livez`, och upprepa sökningen. Testpunkten måste fortfarande returneras. Om du valde en anpassad `--data-dir`, ange samma katalog vid omstarten.
+
+### Vardagskommandon
+
+Installation och konfiguration finns under [Installation](#install) ovan (den första körningen guidar dig genom det). Till vardags:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Sessionsuppspelning
+
+Varje session som agentmemory registrerar kan spelas upp igen. Öppna viewern, välj fliken **Replay**, och skrubba genom tidslinjen: prompter, verktygsanrop, verktygsresultat och svar renderas som diskreta händelser med play/pause, hastighetskontroll (0.5x till 4x) och kortkommandon (mellanslag för att växla, piltangenterna för att stega).
+
+För att importera äldre Claude Code JSONL-transkript:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Importerade sessioner dyker upp i Replay-väljaren tillsammans med de ursprungliga. Under huven dirigeras varje post genom iii-funktionerna `mem::replay::load`, `mem::replay::sessions` och `mem::replay::import-jsonl`, utan några sidokanalsservrar. Varje importerat transkript indexeras för sökning, märks med ursprungskanalen `import`, och analyseras för en sessionskristall och lärdomar.
+
+> **Observera om du förlitar dig på `import-jsonl` som din primära infångningsväg:** Claude Codes `cleanupPeriodDays` (i `~/.claude/settings.json`, standard **30**) tar automatiskt bort JSONL-transkript äldre än det fönstret från `~/.claude/projects/`. Om du installerar agentmemory på en månader-gammal Claude Code-historik är allt äldre än 30 dagar redan borta innan den första importen. Antingen kör du `import-jsonl` på en cron, höjer `cleanupPeriodDays` till något högre, eller kopplar in auto-infångnings-hookarna (standardvägen vid plugin-installation) så att varje tur hamnar i agentmemory medan sessionen är live och JSONL-rensningen slutar spela någon roll.
+
+### Uppgradering / underhåll
+
+Använd underhållskommandot när du avsiktligt vill uppdatera din lokala körtid:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Varning: det här kommandot ändrar den aktuella arbetsytan/körtiden. Det kan uppdatera JavaScript-beroenden och hämta den fastlåsta Docker-avbildningen `iiidev/iii:0.22.1`. Det installerar aldrig en ofastlåst eller nyare iii-engine.
+
+Implementationsdetaljer finns i `src/cli.ts` (se `runUpgrade` runt området `src/cli.ts:544-595`).
+
+### Claude Code (ett block, klistra in det)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code utan plugin-installationen (fristående MCP-väg)
+
+Om du kopplar in agentmemorys MCP-server via `~/.claude.json` direkt istället för att använda `/plugin install`, löser Claude Code aldrig upp `${CLAUDE_PLUGIN_ROOT}`, och du måste peka hook-skripten mot absoluta sökvägar i `~/.claude/settings.json`. Dessa sökvägar innehåller vanligtvis agentmemory-versionen (t.ex. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), så nästa uppgradering bryter varje hook i det tysta.
+
+Lösning:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Detta slår samman samma hook-kommandon i `~/.claude/settings.json` med absoluta sökvägar som löses upp till den medföljande `plugin/`-katalogen i det för tillfället installerade paketet `@agentmemory/agentmemory`. Kör kommandot igen efter att du har uppgraderat agentmemory för att uppdatera sökvägarna. Användarens egna poster i samma fil bevaras; endast tidigare agentmemory-poster ersätts. Att använda vägen `/plugin install` är fortfarande den rekommenderade metoden.
+För fjärr- eller skyddade driftsättningar, starta Claude Code med `AGENTMEMORY_URL` och `AGENTMEMORY_SECRET` satta. Plugin-programmet skickar båda värdena vidare till sin medföljande MCP-server; när `AGENTMEMORY_URL` är tomt använder MCP-shimmen `http://localhost:3111`.
+
+### Codex CLI (Codex-plugin-plattformen)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex-pluginet levereras från samma `plugin/`-katalog som Claude Code-pluginet. Det registrerar:
+
+- En medföljande stdio MCP-brygga till den körande daemonen, utan npm-nedladdning eller fallback-lager. Se [lokala Codex-guiden](../docs/plugins/codex-local.md) för att testa en build som ännu inte är publicerad.
+- 6 livscykel-hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 anropsbara skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, plus 8 referens-skills som agenten laddar vid behov (minnesdisciplin, MCP-verktyg, REST API, konfiguration, agenter, hooks, arkitektur och guiden för att skriva skills)
+
+Codex hook-motor injicerar `CLAUDE_PLUGIN_ROOT` i hook-underprocesser (enligt [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), så samma hook-skript fungerar på båda värdarna utan duplicering. Händelserna Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure är specifika för Claude Code och registreras inte för Codex.
+
+#### Codex hooks: tillit och kompatibilitet
+
+Native plugin-hook-utlösning är verifierad med Codex CLI 0.150.1. Lita på plugin-hooksen innan du förväntar dig infångning. Desktop-beteendet beror på dess medföljande körtid; kontrollera `/hooks` och bekräfta en infångad händelse innan du aktiverar en lösning.
+
+Om din värd kräver globala hooks, spegla kommandona till `~/.codex/hooks.json`. När MCP redan är inkopplat behöver den nuvarande adaptern `--force` för att nå hook-installationen:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Detta slår samman globala hooks och skriver om agentmemory-MCP-posten, och bevarar orelaterade poster. Granska eventuella anpassade agentmemory-endpoint-inställningar innan du använder `--force`. Kör om efter uppgradering för att uppdatera skriptsökvägarna. Aktivera antingen native plugin-hooks eller globala kopior för att undvika dubblerad infångning.
+
+### GitHub Copilot CLI
+
+För VS Code agent-läge, använd [Copilot MCP- och automatisk-infångningsguiden](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). CLI-adaptern konfigurerar inte VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` slår samman `mcpServers.agentmemory` i `~/.copilot/mcp-config.json` (eller `$COPILOT_HOME/mcp-config.json` när `COPILOT_HOME` är satt) och bevarar befintliga servrar. På native Windows är detta den enda automatiserade `connect`-adaptern; konfigurera varje annan native Windows-agent manuellt. WSL-`connect` stöds bara när målagenten är installerad i samma WSL-miljö. Copilot plockar upp MCP-servern vid nästa start eller efter `/mcp`. Installera även pluginet när du vill ha den fullständiga hook-/skill-upplevelsen.
+
+
+OpenClaw (klistra in denna prompt)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Fullständig guide: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (klistra in denna prompt)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Fullständig guide: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Andra agenter
+
+Starta minnesservern: `npx -y @agentmemory/agentmemory@latest`
+
+#### Inbyggda skills via `npx skills add` (50+ agenter)
+
+agentmemory levereras med 17 skills i Claude-Code-stilens `/SKILL.md`-format: 9 anropsbara handlings-skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) och 8 referens-skills som agenten laddar vid behov (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referens-skillsen innehåller datatabeller genererade från källkoden, så de avviker aldrig. CLI-verktyget [`skills`](https://npmjs.com/package/skills) från vercel-labs installerar dem automatiskt i den anropande agentens inbyggda skill-katalog över 50+ agenter (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf och fler):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Detta är ett **komplement** till `agentmemory connect `:
+
+- `agentmemory connect ` skriver MCP-serverkonfigurationen så att verktygen blir tillgängliga.
+- `npx skills add rohitg00/agentmemory` installerar skillsen så att agenten vet när den ska anropa dem.
+
+För de få agenter som skills-CLI:n ännu inte täcker (Zed v1.3.x och lägre), lägg själv de 17 SKILL.md-filerna i agentens inbyggda skill-katalog; samma format fungerar överallt.
+
+#### Standard-MCP-block
+
+agentmemory-posten är **samma MCP-serverblock** på alla värdar som använder `mcpServers`-formen (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Slå samman denna post med det befintliga `mcpServers`-objektet** i värdens konfigurationsfil; ersätt inte filen. Om filen redan har andra servrar, lägg till `agentmemory` bredvid dem som en ytterligare nyckel inuti `mcpServers`. Om `mcpServers` helt saknas, klistra in blocket inuti `{ "mcpServers": { ... } }`. `${VAR}`-platshållarna ärver `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` från skalet vid MCP-serverns start; ej satta variabler skickar tomma strängar och shimmen faller tillbaka till `http://localhost:3111`. En inkopplad post täcker både lokala och fjärran (k8s / reverse-proxyade) driftsättningar.
+
+| Agent | Konfigurationsfil | Anteckningar |
+|---|---|---|
+| **Cursor (endast MCP)** | `~/.cursor/mcp.json` | Slå samman i `mcpServers`, eller `agentmemory connect cursor`. En deeplink med ett klick finns också på webbplatsen. |
+| **Cursor (fullständigt plugin)** | `.cursor-plugin/` | Cursor Marketplace-listning (inlämning under granskning) eller Cursor Settings → Plugins → lokal checkout. Registrerar 7 auto-infångnings-hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + MCP-servern, med `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` hanterade i Cursors plugin-panel. Fungerar i Cursor IDE och `cursor-agent`-CLI:n; CLI-utskriftslägets prompter fylls i efterhand från sessionstranskriptet vid sessionens slut. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Slå samman i `mcpServers`. Starta om Claude Desktop efter redigering. |
+| **Cline / Roo Code / Kilo Code** | Clines MCP-inställningar (Settings UI → MCP Servers → Edit) | Samma `mcpServers`-block. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` slår samman MCP-posten; `--with-hooks` lägger till sex inbyggda auto-infångnings-hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) med Devins gemener i verktygsmatcharna. Verifiera med `devin mcp list` och `/hooks` inuti devin. |
+| **Devin CLI (fullständigt plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` från en checkout registrerar alla 17 skills som `/agentmemory:`-snabbkommandon plus MCP-servern. Devins plugin-hooks kan inte utlösa `SessionStart`/`SessionEnd`, så kombinera med `connect devin --with-hooks` för fullständig sessionsinfångning. |
+| **Devin (moln)** | Settings → Connections → MCP servers | Lägg till en anpassad MCP (STDIO): kommando `npx`, argument `-y @agentmemory/mcp@latest`, miljövariabeln `AGENTMEMORY_URL` som pekar på en nätverksåtkomlig agentmemory-driftsättning plus `AGENTMEMORY_SECRET` (molnsessioner kan inte nå localhost — se [`deploy/`](../deploy/)). Spara hemligheten i Devin Secrets, och använd sedan "Test listing tools" för att bekräfta att alla 54 verktyg visas. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (slås samman automatiskt). |
+| **GitHub Copilot CLI (endast MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` slår samman `mcpServers.agentmemory`; Copilot plockar upp det vid nästa start eller via `/mcp`. |
+| **GitHub Copilot CLI (fullständigt plugin)** | Copilot plugin-installation | `copilot plugin install rohitg00/agentmemory:plugin` för pluginet från GitHub-underkatalogen. |
+| **OpenClaw** | OpenClaw MCP-konfiguration | Samma `mcpServers`-block. Djupare integration: `openclaw plugins install ./integrations/openclaw` tar över OpenClaws minnesplats (byter automatiskt från `memory-core`); sätt `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, annars blockeras tur-infångningen i det tysta. Se [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (endast MCP)** | `.codex/config.toml` | TOML-form: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, eller lägg till `[mcp_servers.agentmemory]` manuellt. |
+| **Codex CLI (fullständigt plugin)** | Codex plugin-marketplace | `codex plugin marketplace add rohitg00/agentmemory` och sedan `codex plugin add agentmemory@agentmemory`. Registrerar MCP + 6 livscykel-hooks + 17 skills. Lita på hooksen och verifiera infångningen i din värd; se [Codex-konfiguration och validering](../docs/plugins/codex-local.md). |
+| **OpenCode (endast MCP)** | `opencode.json` | Annan form: en toppnivånyckel `mcp`, kommando som array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (fullständigt plugin)** | `plugin/opencode/` | 22 auto-infångnings-hooks som täcker sessionslivscykel, meddelanden, verktyg, fel. Projekttillhörighet är per session, så en OpenCode-process som spänner över flera repon registrerar varje session under sitt eget projekt. Två snabbkommandon (`/recall`, `/remember`). Kopiera `plugin/opencode/` till din OpenCode-arbetsyta och lägg till plugin-posten i `opencode.json`. Se [`plugin/opencode/README.md`](../plugin/opencode/README.md) för den fullständiga hook-tabellen + luckanalysen. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` installerar det medföljande tillägget i pi:s katalog för automatisk upptäckt (recall vid agentstart, infångning vid agentslut, verktygen `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` i en körande pi plockar upp det. [`integrations/pi`](../integrations/pi/) är även ett pi-paket (`pi install ./integrations/pi` från en checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ger minnesleverantören med 6 hooks (förhämtning, turinfångning, sessionsslut, förkomprimering, MEMORY.md-spegling, systemprompt-block). Validera med `hermes plugins doctor` och `hermes memory status`. Se [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` skriver det vanliga `mcpServers`-blocket. Hook-nyttolasten är fältkompatibel med Claude Code, så de befintliga 12-hooks-skripten fungerar utan ändring; koppla in dem via `hooks`-avsnittet i samma `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` installerar MCP och infångnings-hooks i den delade anpassningskatalogen. Se [Antigravity-konfiguration och begränsningar](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` använder samma MCP- och hook-konfiguration som nuvarande IDE-versioner. Befintliga installationer bör uppdateras med `--force`; se [uppgraderingsanteckningarna](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` skriver konfigurationen på användarnivå. Arbetsyteöverskrivningar läggs i `.kiro/settings/mcp.json` bredvid din kod. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` skriver det vanliga `mcpServers`-blocket. Warp upptäcker också automatiskt skills från `.claude/skills/`; när Claude Code-pluginet är installerat visas agentmemorys 8 skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) naturligt i Warps snabbkommando-palett. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` skriver det vanliga `mcpServers`-blocket. VS Code-tilläggsanvändare: klistra in samma block via Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (att föredra) eller `config.json` (äldre) | `agentmemory connect continue` skapar `config.yaml` från grunden när ingen av dem finns, eller ändrar befintlig `config.json`. **Om du redan har `config.yaml`** skriver adaptern ut exakt det block som ska klistras in under `mcpServers:`; den skriver inte om din yaml i det tysta, eftersom att bevara kommentarer och ankare på ett säkert sätt kräver en YAML-parser som paketet inte levererar. Continue använder array-form (inte objekt) för `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` skriver under `context_servers` (Zeds nyckel, INTE `mcpServers`). Fjärranslutna MCP-servrar kan istället kopplas in via `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` skriver det vanliga `mcpServers`-blocket. Projektbegränsade överskrivningar läggs i `/.factory/mcp.json`. Ange `--with-hooks` för inbyggd auto-infångning. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` lägger till en rad `@deepseek-ai/dsh-mcp-client` i patch-lagret på hemkatalognivå som varje Harness-profil laddar; verktyg registreras som `mcp__agentmemory__*`. Ange `--with-hooks` för att även koppla in auto-infångning: de medföljande Claude Code-hook-skripten körs genom Harness förstapartsbrygga `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) via ett manifest skrivet till `$DSH_HOME/agentmemory.hooks.json`. Standardvärdet är `~/.dsh` när `DSH_HOME` inte är satt. |
+| **Goose** | Goose MCP-inställningsgränssnitt | Samma `mcpServers`-block; använd `goose configure` → Add Extension → MCP. Direkt YAML-redigering i `~/.config/goose/config.yaml` stöds, men schemat använder `extensions:` + `cmd` (inte `mcpServers:` + `command`). |
+| **Aider** | n/a | Kommunicera direkt med REST API:et: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Alla agenter (32+)** | n/a | `npx skillkit install agentmemory` upptäcker värden automatiskt och slår samman. |
+
+**Sandboxade MCP-klienter** (Flatpak / Snap / restriktiva containrar) som inte kan nå värdens `localhost`: sätt även `"AGENTMEMORY_FORCE_PROXY": "1"` i `env`-blocket, och peka `AGENTMEMORY_URL` mot en väg som sandboxen faktiskt kan nå (t.ex. din LAN-IP).
+
+### Programmatisk åtkomst (Python / Rust / Node)
+
+agentmemory registrerar sina kärnoperationer som iii-funktioner (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Alla språk med en iii SDK kan anropa dem direkt över `ws://localhost:49134`, utan behov av en separat REST-klient per språk.
+
+```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"},
+})
+```
+
+Genomarbetat exempel: [`examples/python/`](../examples/python/) (snabbstart + flöde för observation/recall). REST på `:3111` finns fortfarande tillgängligt för värdar utan en iii-körtid.
+
+### Från källkod
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Detta startar agentmemory med en lokal `iii-engine` om den fastlåsta binären redan är installerad, eller använder Docker Compose när det valts. REST, strömmar och viewern binder till `127.0.0.1` som standard. Den automatiska binärvägen för macOS/Linux kräver `curl`, ett POSIX-`sh` och `tar`.
+
+Installera `iii-engine` manuellt. **agentmemory fastlåser för närvarande `iii-engine` till `v0.22.1`**, samma utgåva som dess `iii-sdk`-beroende; workern talar den enginens trådprotokoll, och 0.20.0 omorganiserade SDK-ytan, så de två rör sig tillsammans i agentmemorys utgåvor. Åsidosätt med `AGENTMEMORY_III_VERSION=` om du kör din egen engine och vet att den matchar.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** byt ut `aarch64-apple-darwin` mot `x86_64-apple-darwin`
+- **Linux x64:** byt ut mot `x86_64-unknown-linux-gnu`
+- **Linux arm64:** byt ut mot `aarch64-unknown-linux-gnu`
+- **Windows:** ladda ner `iii-x86_64-pc-windows-msvc.zip` från [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) och extrahera `iii.exe` till `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Varje arkiv har en matchande `.sha256`-fil på utgåvesidan; när du byter plattform, använd den filens hash i kontrollen ovan (på Windows: `Get-FileHash`). Den automatiska installeraren i `npx @agentmemory/agentmemory` fastlåser dessa hashar och vägrar ett arkiv som inte matchar.
+
+Eller använd Docker (den medföljande `docker-compose.yml` hämtar `iiidev/iii:0.22.1`). Fullständig dokumentation: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory körs på Windows 10/11, men Node.js-paketet ensamt räcker inte; du behöver också den fastlåsta iii-engine v0.22.1-körtiden som en bakgrundsprocess. CLI:n extraherar inte Windows-ZIP-filen automatiskt, så native Windows-användare måste installera `iii.exe` manuellt, använda WSL2, eller välja Docker Desktop.
+
+Automatiserad MCP-inkoppling på native Windows stöder bara `agentmemory connect copilot-cli`. För Claude Code, Codex, Cursor och varje annan native Windows-agent, kopiera det manuella MCP-blocket från [Andra agenter](#other-agents) till den agentens Windows-konfiguration. Att köra `connect` i WSL är lämpligt bara när målagenten också är installerad i samma WSL-miljö; det redigerar inte konfigurationen för en agent som körs på Windows-värden.
+
+**Alternativ A: förbyggd Windows-binär (rekommenderas)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Alternativ B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Alternativ C: endast fristående MCP (ingen engine).** Om du bara behöver MCP-verktygen för din agent och inte behöver REST API, viewern eller cron-jobb, hoppa över enginen helt:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostik för Windows:** om `npx -y @agentmemory/agentmemory@latest` misslyckas, kör det igen med `--verbose` för att se enginens faktiska stderr. Vanliga felorsaker:
+
+| Symptom | Åtgärd |
+|---|---|
+| `The engine process started but the REST API never responded.` | Bekräfta att alla fyra härledda portar är fria, verifiera att den fastlåsta `iii.exe` förblev igång, och kör sedan igen med `--verbose` och inspektera den infångade enginens stderr |
+| `Could not start iii-engine` | Varken `iii.exe` eller Docker är installerat. Se alternativ A eller B ovan |
+| Portkonflikt | `netstat -ano \| findstr :3111` för att se vad som är bundet, avsluta det sedan eller använd `--port ` |
+| Docker-reservläge hoppas över trots att Docker är installerat | Se till att Docker Desktop faktiskt körs (ikonen i systemfältet) |
+
+> Observera: iii-**enginen** är en förbyggd binär, inte en cargo crate, så försök inte `cargo install` den. (iii-**SDK:erna** publiceras på crates.io, npm och PyPI, men agentmemory behöver inte dem.) Alla engine-installationsmetoder som stöds är fastlåsta till v0.22.1: den förbyggda binären ovan, agentmemorys auto-installationsväg för macOS/Linux (`curl`, POSIX `sh` och `tar` krävs), och Docker-avbildningen `iiidev/iii:0.22.1`. Ett rått uppströms `install.sh | sh` installerar den senaste enginen, vilket agentmemory inte stöder. Använd `npx -y @agentmemory/agentmemory@latest`; på macOS/Linux hämtar det den fastlåsta enginen till `~/.agentmemory/bin`.
+
+---
+
+
Driftsättning
+
+Mallar med ett klick för hanterade värdar. Var och en levererar en självständig Dockerfile som hämtar `@agentmemory/agentmemory` från npm och kopierar in iii-engine-binären från den officiella Docker Hub-avbildningen `iiidev/iii`; ingen förbyggd agentmemory-avbildning krävs. Beständig lagring monteras på `/data`; vid första start skriver startpunkten över den npm-medföljande iii-konfigurationen (som binder till `127.0.0.1`) med en driftsättningsanpassad version som binder till `0.0.0.0` och använder absoluta `/data`-sökvägar, genererar HMAC-hemligheten, och sänker sedan rättigheterna från `root` till `node` via `gosu` innan agentmemory-CLI:n körs.
+
+
+
+
+
+
+Renders driftsättningsknapp med ett klick kräver `render.yaml` i repots rot, vilket vi avsiktligt håller rent. Använd Render Blueprint-flödet som dokumenteras i [`deploy/render/`](.././deploy/render/README.md) för att manuellt peka på den repo-interna blueprinten.
+
+Fullständiga installationsdetaljer (HMAC-infångning, SSH-tunnel för viewern, rotation, backup, kostnadsgolv) finns i [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): en enda maskin med
+ `auto_stop_machines = "stop"`; billigast vid inaktivitet.
+- [`deploy/railway`](.././deploy/railway/README.md): fast avgift på
+ Hobby-planen, volym i dashboarden.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint-flöde,
+ automatiska disk-snapshots på betalplaner.
+- [`deploy/coolify`](.././deploy/coolify/README.md): självhostat på din
+ egen VPS via [Coolify](https://coolify.io/self-hosted); samma Docker
+ Compose-stack, du äger värden och datan.
+
+Endast port `3111` publiceras. Viewern på `3113` förblir bunden till
+loopback inuti containern; varje malls README dokumenterar
+SSH-tunnel-mönstret för att nå den.
+
+---
+
+
+
+Varje kodningsagent glömmer allt när sessionen tar slut, och varje ny session börjar med att du förklarar din tech-stack på nytt. agentmemory körs i bakgrunden och tar bort det steget.
+
+```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.
+```
+
+### Jämfört med inbyggt agentminne
+
+Varje AI-kodningsagent levereras med inbyggt minne: Claude Code har `MEMORY.md`, Cursor har notepads, Cline har memory bank. Dessa fungerar som post-it-lappar. agentmemory är den sökbara databasen bakom post-it-lapparna.
+
+| | Inbyggt (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Skala | Tak på 200 rader | Obegränsat |
+| Sökning | Laddar allt in i kontexten | BM25 + vektor + graf (endast topp-K) |
+| Tokenkostnad | 22K+ vid 240 observationer | ~1,900 tokens (92% mindre) |
+| Mellan agenter | Filer per agent | MCP + REST (vilken agent som helst) |
+| Koordinering | Ingen | Leaser, signaler, åtgärder, rutiner |
+| Observerbarhet | Läs filer manuellt | Viewer i realtid på :3113 |
+
+---
+
+
+
+### Minnespipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-nivås minneskonsolidering
+
+Modellerat efter hur mänskliga hjärnor bearbetar minne, inklusive sömnkonsolidering.
+
+| Nivå | Vad | Analogi |
+|------|------|---------|
+| **Arbetsminne** | Råa observationer från verktygsanvändning | Korttidsminne |
+| **Episodiskt** | Komprimerade sessionssammanfattningar | "Vad som hände" |
+| **Semantiskt** | Extraherade fakta och mönster | "Vad jag vet" |
+| **Procedurellt** | Arbetsflöden och beslutsmönster | "Hur man gör det" |
+
+Minnen klingar av över tid (Ebbinghaus-kurvan). Ofta använda minnen förstärks. Inaktuella minnen rensas ut automatiskt. Motsägelser upptäcks och löses.
+
+### Vad som fångas in
+
+| Hook | Fångar in |
+|------|----------|
+| `SessionStart` | Projektsökväg, sessions-ID |
+| `UserPromptSubmit` | Användarprompter (integritetsfiltrerade) |
+| `PreToolUse` | Filåtkomstmönster + berikad kontext |
+| `PostToolUse` | Verktygsnamn, indata, utdata |
+| `PostToolUseFailure` | Felkontext |
+| `PreCompact` | Återinjicerar minne före komprimering |
+| `SubagentStart/Stop` | Underagentens livscykel |
+| `Stop` | Sammanfattning vid sessionens slut |
+| `SessionEnd` | Markering för avslutad session |
+
+### Nyckelfunktioner
+
+| Funktion | Beskrivning |
+|---|---|
+| **Automatisk infångning** | Varje verktygsanvändning registreras via hooks, inget manuellt arbete |
+| **Semantisk sökning** | BM25 + vektor + kunskapsgraf med RRF-fusion |
+| **Minnesutveckling** | Versionering, ersättning, relationsgrafer |
+| **Återkallningshygien** | Ersatta minnesversioner lämnar sökindexen; versionskedjan i KV behåller fullständig historik |
+| **Nästan-dubblett-tips** | Sparningar rapporterar en rådgivande `similarTo`-matchning när nytt innehåll nära liknar ett befintligt minne |
+| **Scoping per agent** | `agentId` löper genom spara och återkalla över REST, MCP och sökindexet, i delat eller isolerat läge |
+| **Ursprung vid skrivtillfället** | Varje observation och minne bär en oföränderlig ursprungskanal (user, agent, tool, import eller shared) stämplad vid infångning, sparning och import |
+| **Automatisk glömning** | TTL-utgång, upptäckt av motsägelser, viktbaserad utrensning |
+| **Integritet först** | API-nycklar, hemligheter, ``-taggar tas bort före lagring |
+| **Självläkande** | Circuit breaker, reservkedja för leverantörer, hälsoövervakning |
+| **Claude-brygga** | Dubbelriktad synkning med MEMORY.md |
+| **Kunskapsgraf** | Entitetsextraktion + BFS-genomsökning |
+| **Teamminne** | Namnrymdsindelat delat + privat mellan teammedlemmar |
+| **Citeringsursprung** | Spåra vilket minne som helst tillbaka till källobservationerna |
+| **Git-snapshots** | Versionera, återställa och diffa minnestillståndet |
+
+---
+
+
+
+Trippelströms-hämtning som kombinerar tre signaler:
+
+| Ström | Vad den gör | När |
+|---|---|---|
+| **BM25** | Stam-baserad nyckelordsmatchning med synonymexpansion | Alltid aktiv |
+| **Vektor** | Cosinuslikhet över täta embeddings | Embedding-leverantör konfigurerad |
+| **Graf** | Genomsökning av kunskapsgrafen via entitetsmatchning | Entiteter upptäckta i frågan |
+
+Sammanfogad med Reciprocal Rank Fusion (RRF, k=60) och sessionsdiversifierad (max 3 resultat per session).
+
+När ett vektorindex är ifyllt använder `mem::search` (bakom `memory_recall`) den hybrida BM25 + vektor-rankaren. Utan embeddings används BM25. `smart-search` kan dessutom sammanfoga strukturella grafmatchningar när grafdata finns, även i nyckelfritt läge. Återkallning av lärdomar körs på ett dedikerat BM25-index i minnet istället för att skanna hela korpuset per fråga. Ersatta minnesversioner exkluderas från varje återkallningsväg; versionskedjan behåller deras historik.
+
+Vektorer överlever en krasch eller en tvingad avstängning. Vektorindexet sparas i buckets högst var `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minuter). Varje vektor som läggs till eller tas bort däremellan skrivs också direkt till en liten väntande logg i state-lagret, och nästa start spelar upp den igen utan att anropa embedding-leverantören. Varje lyckad sparning tömmer loggen. Dokument som fortfarande saknar en vektor efter uppspelningen bäddas in igen i bakgrunden i omgångar om `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) tills inga återstår, och en backfill som stoppas fortsätter vid nästa start. `/agentmemory/status` och viewern visar storleken på den väntande loggen och backfill-tillståndet. Nyckelfria installationer skriver ingenting.
+
+BM25 tokeniserar grekiska, kyrilliska, hebreiska, arabiska och accentuerad latin direkt ur lådan. För kinesiska/japanska/koreanska minnen, installera de valfria segmenterarna (`npm install @node-rs/jieba tiny-segmenter`) för att dela upp CJK-sekvenser i ordnivå-tokens; utan dem faller agentmemory mjukt tillbaka till tokenisering av hela sekvenser och skriver ut en engångstips på stderr.
+
+### Embedding-leverantörer
+
+Nyckelfria installationer inaktiverar vektor-embeddings: `mem::search` använder BM25, medan `smart-search` också kan använda befintlig strukturell grafdata. För att aktivera kostnadsfria semantiska embeddings på enheten, lägg till detta i `~/.agentmemory/.env` och starta om agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Den vanliga npm-installationen inkluderar den valfria körtiden `@huggingface/transformers`. Den första embedding-förfrågan laddar ner `Xenova/all-MiniLM-L6-v2`, så den behöver nätverksåtkomst och kan ta längre tid; efterföljande inferens körs på enheten. Fjärrleverantörer upptäcks automatiskt utifrån sina nycklar om inte `EMBEDDING_PROVIDER` åsidosätter dem.
+
+| Leverantör | Modell | Kostnad | Anteckningar |
+|---|---|---|---|
+| **Lokal (rekommenderat att aktivera)** | `all-MiniLM-L6-v2` | Kostnadsfri | På enheten efter den första modellnedladdningen, +8 procentenheter recall jämfört med endast BM25 |
+| Gemini | `gemini-embedding-001` | Kostnadsfri nivå | 100+ språk, 768/1536/3072 dimensioner (MRL), 2048-token indata. Ersätter `text-embedding-004` ([utfasad, stängs ner 14 jan 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Högst kvalitet |
+| Voyage AI | `voyage-code-3` | Betald | Optimerad för kod |
+| Cohere | `embed-english-v3.0` | Kostnadsfri provperiod | Generell användning |
+| OpenRouter | Vilken modell som helst | Varierar | Multimodell-proxy |
+
+---
+
+
+
+54 verktyg, 6 resurser, 3 prompter och 17 skills.
+
+> **MCP-shim kontra fullständig server:** det publicerade paketet `@agentmemory/mcp` är en tunn shim. Det exponerar hela ytan med 54 verktyg **bara när det kan nå en körande agentmemory-server** via `AGENTMEMORY_URL` (proxy-läge). Utan någon nåbar server faller shimmen tillbaka till en lokal uppsättning på 7 verktyg (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Miljövariabeln `AGENTMEMORY_TOOLS=core|all` är en flagga på *serversidan*; att sätta den i shimmens `env`-block har ingen effekt. Om du bara ser 7 verktyg i Cursor / OpenCode / Gemini CLI, starta `npx -y @agentmemory/agentmemory@latest` (eller Docker-stacken) och sätt `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 verktyg
+
+Tre verktygsytor, från minst till störst: `AGENTMEMORY_TOOLS=core` begränsar synligheten till 8 väsentliga verktyg (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); grundmängden nedan är registrets 14 grundläggande verktyg; standarden (`AGENTMEMORY_TOOLS=all`) exponerar alla 54.
+
+
+Grundverktyg (14)
+
+| Verktyg | Beskrivning |
+|------|-------------|
+| `memory_recall` | Sök i tidigare observationer |
+| `memory_compress_file` | Komprimera markdown-filer samtidigt som strukturen bevaras |
+| `memory_save` | Spara en insikt, ett beslut eller ett mönster |
+| `memory_file_history` | Tidigare observationer om specifika filer |
+| `memory_patterns` | Upptäck återkommande mönster |
+| `memory_sessions` | Lista senaste sessionerna |
+| `memory_smart_search` | Hybrid semantisk + nyckelordssökning |
+| `memory_vision_search` | Sök bland bildobservationer |
+| `memory_timeline` | Kronologiska observationer |
+| `memory_profile` | Projektprofil (koncept, filer, mönster) |
+| `memory_export` | Exportera all minnesdata |
+| `memory_relations` | Fråga relationsgrafen |
+| `memory_commit_lookup` | Sessioner bakom en git-commit |
+| `memory_commits` | Commits registrerade för en session |
+
+
+
+
+Utökade verktyg (54 totalt, standardytan)
+
+| Verktyg | Beskrivning |
+|------|-------------|
+| `memory_patterns` | Upptäck återkommande mönster |
+| `memory_timeline` | Kronologiska observationer |
+| `memory_relations` | Fråga relationsgrafen |
+| `memory_graph_query` | Genomsökning av kunskapsgrafen |
+| `memory_consolidate` | Kör 4-nivås konsolidering |
+| `memory_claude_bridge_sync` | Synka med MEMORY.md |
+| `memory_team_share` | Dela med teammedlemmar |
+| `memory_team_feed` | Senaste delade objekt |
+| `memory_audit` | Granskningsspår för operationer |
+| `memory_governance_delete` | Radera med granskningsspår |
+| `memory_snapshot_create` | Git-versionerad snapshot |
+| `memory_action_create` | Skapa arbetsobjekt med beroenden |
+| `memory_action_update` | Uppdatera åtgärdsstatus |
+| `memory_frontier` | Oblockerade åtgärder rankade efter prioritet |
+| `memory_next` | Den enskilt viktigaste nästa åtgärden |
+| `memory_lease` | Exklusiva åtgärdsleaser (multiagent) |
+| `memory_routine_run` | Instansiera arbetsflödesrutiner |
+| `memory_signal_send` | Meddelanden mellan agenter |
+| `memory_signal_read` | Läs meddelanden med kvitton |
+| `memory_checkpoint` | Externa villkorsgrindar |
+| `memory_mesh_sync` | P2P-synk mellan instanser |
+| `memory_sentinel_create` | Händelsedrivna bevakare |
+| `memory_sentinel_trigger` | Utlös bevakare externt |
+| `memory_sketch_create` | Kortlivade åtgärdsgrafer |
+| `memory_sketch_promote` | Befordra till permanent |
+| `memory_crystallize` | Komprimera åtgärdskedjor |
+| `memory_diagnose` | Hälsokontroller |
+| `memory_heal` | Fixa fastnat tillstånd automatiskt |
+| `memory_facet_tag` | Dimension:värde-taggar |
+| `memory_facet_query` | Fråga via facett-taggar |
+| `memory_verify` | Spåra ursprung |
+
+
+
+### 6 resurser · 3 prompter · 17 skills
+
+| Typ | Namn | Beskrivning |
+|------|------|-------------|
+| Resurs | `agentmemory://status` | Hälsa, sessionsantal, minnesantal |
+| Resurs | `agentmemory://project/{name}/profile` | Intelligens per projekt |
+| Resurs | `agentmemory://project/{name}/recent` | Senaste observationer för ett projekt |
+| Resurs | `agentmemory://memories/latest` | De 10 senaste aktiva minnena |
+| Resurs | `agentmemory://graph/stats` | Statistik för kunskapsgrafen |
+| Resurs | `agentmemory://team/{id}/profile` | Delad teamprofil |
+| Prompt | `recall_context` | Sök + returnera kontextmeddelanden |
+| Prompt | `session_handoff` | Överlämningsdata mellan agenter |
+| Prompt | `detect_patterns` | Analysera återkommande mönster |
+| Skill | `/recall` | Sök i minnet |
+| Skill | `/remember` | Spara till långtidsminnet |
+| Skill | `/session-history` | Senaste sessionssammanfattningarna |
+| Skill | `/forget` | Radera observationer/sessioner |
+
+Tabellen visar de fyra kärnskillsen. Den fullständiga mängden är 9 anropsbara skills plus 8 referens-skills; se avsnittet om inbyggda skills ovan.
+
+### Fristående MCP
+
+Körs utan den fullständiga servern, för vilken MCP-klient som helst. Något av dessa fungerar:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Eller lägg till i din agents MCP-konfiguration:
+
+De flesta agenter (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Slå samman `agentmemory`-posten med värdens befintliga `mcpServers`-objekt istället för att ersätta filen. För sandboxade klienter som inte kan nå värdens `localhost`, lägg till `"AGENTMEMORY_FORCE_PROXY": "1"` i env-blocket och sätt `AGENTMEMORY_URL` till en väg som sandboxen kan nå.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Kopiera plugin-filen från repot:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Startar automatiskt på port `3113`. Viewern laddar en snapshot när den ansluter (`GET /agentmemory/viewer/snapshot`) och tillämpar därefter live-strömhändelser: nya minnen, lärdomar, observationer, granskningsposter, grafändringar och hälsouppdateringar visas utan polling eller sidomladdningar. De enda andra förfrågningarna är de åtgärder du klickar på, sidor för "ladda mer" och sökningar. När strömmen bryts visar viewern hur gamla dess siffror är, återansluter med backoff och synkar om från en snapshot.
+
+- **12 flikar i fyra grupper** med livevärden, djuplänkar (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), kortkommandon och en mobilmeny.
+- **Memories:** serversidig sökning, filter efter projekt, agent och typ, en detaljpanel med versionskedjan och en orddiff, ursprungslänkar, kopieringsknappar för id:t, MCP-anropet och ett curl-kommando, redigering (en ny version), glöm med bekräftelse, massglöm och JSON-export.
+- **Sessions:** en inbäddad observationstidslinje med läsbar verktygsindata och -utdata, filter och sidbläddring, samt de minnen och lärdomar varje session gav upphov till.
+- **Graph:** sökning, noddetaljer med relationer och källor, en legend som inte enbart förlitar sig på färg, samt zoomkontroller.
+- **Health:** liveversionen av `GET /agentmemory/status`. Varje problem kommer med sin åtgärd, plus state-backend, indexsparningsstatus, förloppet för kompaktering av grafursprung och en konsolideringsförklaring med de verkliga tröskelvärdena.
+- **Audit, Activity, Profile, Replay, Lessons, Actions och Crystals**-sidorna, var och en med ett tomt tillstånd som säger vad avsnittet är, varför det är tomt och vilket kommando som fyller det, samt en `?`-ordlisteverktygstips på varje term och siffra.
+
+```bash
+open http://localhost:3113
+```
+
+Viewer-servern binder till `127.0.0.1` som standard och bifogar serverhemligheten när den vidarebefordrar förfrågningar till REST API:et, så den behöver ingen konfiguration. Endpointen `/agentmemory/viewer`, som serveras via REST, följer de vanliga bearer-token-reglerna och omdirigerar webbläsare utan token till viewer-porten. CSP-headrarna använder en script-nonce per svar och inaktiverar inline-hanterarattribut (`script-src-attr 'none'`).
+
+---
+
+
+
+Viewern på `:3113` visar vad din agent **minns**. [iii-konsolen](https://iii.dev/docs/console) visar vad din agent **gjorde**: varje minnesoperation som ett OpenTelemetry-spår, varje KV-post redigerbar, varje funktion anropsbar, varje ström avlyssningsbar. Två fönster mot samma minne: ett produktformat, ett motorformat.
+
+Se en `memory_smart_search` utlösas och följ BM25-skanningen → embedding-uppslaget → RRF-fusionen → rerankern som ett vattenfall. Redigera en fastnad konsolideringstimer i KV-webbläsaren. Spela upp en `PostToolUse`-hook igen med en justerad nyttolast. Fäst WebSocket-strömmen och se observationer landa i realtid.
+
+agentmemory levererar detta gratis eftersom varje funktionsanrop och trigger går genom iii; inget anpassat, inget att instrumentera.
+
+
+
+
+ Workers-sidan: varje ansluten worker, inklusive agentmemory självt, med PID, funktionsantal, körtid och senast sedd.
+
+
+**Redan installerad.** Konsolen levereras med den fastlåsta `iii`-enginen (0.22+); inget separat att installera. Den första starten laddar ner konsolbinären bredvid enginen.
+
+**Starta tillsammans med agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Detta kör den fastlåsta enginens `iii console` mot de portar agentmemory har löst (REST, strömmar, bridge) och serverar den en port ovanför viewern, `http://localhost:3114` som standard. `--console-port N` väljer en annan port; `--port` och `--instance` väljer agentmemory-instansen på samma sätt som för `stop`; varje annan flagga skickas vidare, till exempel `--enable-flow` för den experimentella arkitektur-grafsidan.
+
+Samma sak för hand, användbart när `agentmemory` inte finns i PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Vad du kan göra från konsolen:**
+
+| Sida | Använd den för att |
+|------|-----------|
+| **Workers** | Se varje ansluten worker och dess livemetrik, inklusive agentmemory-workern själv. |
+| **Functions** | Anropa vilken av agentmemorys funktioner som helst direkt med en JSON-nyttolast; praktiskt för att testa `memory.recall`, `memory.consolidate`, `graph.query` utan att koppla in en klient. |
+| **Triggers** | Spela upp HTTP-, cron-, event- och state-triggers igen: utlös konsolideringscronen manuellt, försök igen med en HTTP-rutt, sänd en tillståndsändring. |
+| **States** | KV-webbläsare med fullständig CRUD över sessioner, minnesplatser, livscykeltimrar och embedding-indexet; redigera värden direkt. |
+| **Streams** | Live-WebSocket-övervakning för minnesskrivningar, hook-händelser och observationsuppdateringar när de flödar genom iii-strömmarna. |
+| **Queues** | Beständiga köämnen + hantering av dödbrevslådor. Spela upp igen eller släpp misslyckade embedding-/komprimeringsjobb. |
+| **Traces** | OpenTelemetry-vyer för vattenfall/flame/tjänsteuppdelning. Filtrera på `trace_id` för att se exakt vilka funktioner, DB-anrop och embedding-förfrågningar en enskild `memory.search` gav upphov till. |
+| **Logs** | Strukturerade OTEL-loggar filtrerade och korrelerade till trace-/span-ID:n. |
+| **Config** | Körtidskonfiguration: se exakt vilka workers, leverantörer och portar din engine körs med. |
+| **Flow** | (Valfritt, `--enable-flow`) Interaktiv arkitekturgraf över varje worker, trigger och ström. |
+
+
+
+
+ Traces: vattenfall/flame/tjänsteuppdelning för varje minnesoperation.
+
+
+**Spårning är redan aktiverad:**
+
+`iii-config.yaml` levereras med workern `iii-observability` aktiverad (`exporter: memory`, `sampling_ratio: 0.1`, metrics + loggar). Ingen extra konfiguration behövs; i samma stund agentmemory startar sänder varje minnesoperation ut en strukturerad logg som konsolen kan läsa, och en av tio av dem (`sampling_ratio: 0.1`) sänder också ut ett spår-span.
+
+Om du istället vill exportera till Jaeger/Honeycomb/Grafana Tempo, ändra `exporter: memory` till `exporter: otlp` och sätt collector-endpointen enligt iii:s dokumentation för observability.
+
+> **Observera:** ingen autentisering upprätthålls på konsolen själv; håll den bunden till `127.0.0.1` (standard) och exponera den aldrig publikt.
+
+---
+
+
+
+agentmemory är **redan en körande [iii](https://iii.dev)-instans**. Tre primitiv (worker, function, trigger) utgör körtiden; KV-state, strömmar och OTEL-spår kommer från workers som iii-state, iii-stream och iii-observability som levereras med iii. Du installerade inte Postgres, Redis, Express, pm2 eller Prometheus, eftersom iii ersätter dem.
+
+Det betyder att ett enda extra kommando utökar agentmemory med en helt ny funktion.
+
+### Utöka agentmemory med fler workers
+
+De inbyggda workers agentmemory behöver finns redan i `iii-config.yaml` och startar med den: `iii-state` (KV), `iii-queue` (beständiga återförsök för händelseprenumeranterna), `iii-pubsub`, `iii-cron`, `iii-stream` och `iii-observability` (OTEL-spår, metrics och loggar för varje funktion). Allt annat från [iii-workerregistret](https://workers.iii.dev) kopplas in i samma engine: kopiera `iii-config.yaml` till `~/.agentmemory/iii-config.yaml` (CLI:n föredrar den filen framför den medföljande, och renderar fortfarande portar och datasökvägar in i den), lägg till posten, installera worker-körtiden en gång med `~/.agentmemory/bin/iii update worker`, och starta om agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Vad du får utöver agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-baserad state-adapter när du växer ur standardinställningarna för KV i minnet |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Kod som kommer från `memory_recall` körs inuti en slit-och-släng-VM, inte ditt skal |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Sätt upp extra MCP-servrar bredvid agentmemorys egen, dela samma engine |
+
+På engine 0.22.x, behåll de `iii-`-prefixade namnen för de inbyggda ovan; posterna utan prefix `http`, `state`, `queue`, `pubsub` och `cron` är de fristående registerworkers som agentmemory flyttar till med 0.23-migreringen.
+
+Fullständigt register: [workers.iii.dev](https://workers.iii.dev). Varje worker där sätts samman via samma primitiv som agentmemory använder, och den agentmemory du redan har är en av dem.
+
+### Motorkonfiguration och bindningsadress
+
+`agentmemory start` läser motorkonfigurationen från den första fil som finns: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` i den aktuella katalogen, `~/.agentmemory/iii-config.yaml`, och därefter den medföljande `iii-config.yaml`. Vid varje start renderar den den filen (datasökvägar, portar, state-backend) till `~/.agentmemory/data/iii-config.runtime.yaml` och startar enginen med den renderade kopian, så redigera källfilen, inte den renderade. Värdena för `host:` i källfilen bevaras som skrivna.
+
+Den medföljande `iii-config.yaml` binder till `127.0.0.1` med avsikt, och den standarden gäller även inuti en container. En CLI som startas i en container lyssnar på containerns loopback, så publicerade portar når ingenting. För att serva en containeriserad CLI genom publicerade portar, sätt `AGENTMEMORY_III_CONFIG` till en konfiguration som binder till `0.0.0.0`. Den paketerade `iii-config.docker.yaml` är en sådan: den binder `iii-http`, `iii-stream` och engine-porten till `0.0.0.0` och lagrar state under `/data`, så montera en skrivbar volym där. Håll `AGENTMEMORY_SECRET` satt, och publicera bara de portar du behöver, på `127.0.0.1` eller bakom en proxy du litar på.
+
+Detta repos `docker-compose.yml` går inte genom CLI:ns konfigurationssökning: den monterar `iii-config.docker.yaml` på `/app/config.yaml`, och containern `iii-engine` startar med `--config /app/config.yaml`. Mallarna för [driftsättning med ett klick](../deploy/) skriver sin egen `0.0.0.0`-konfiguration i sina startpunkter.
+
+### Lagringsbackend: fil (standard) kontra redis
+
+`iii-state` och `iii-stream` använder som standard iii-enginens medföljande fil-baserade KV-lager: en JSON-fil per scope, hållen i motor-processens minne och omskriven till disk på en timer. Det är rätt standard för en lokal installation med en användare; en delad daemon med flera samtidiga skrivare får istället riktiga skrivningar per nyckel från Redis, till priset av en nätverkstur-och-retur per operation (varje `state::*`-anrop serialiseras fortfarande på en Redis-anslutning, så detta byter ut fil-lagrets lås mot en socket, inte mot parallellitet).
+
+Sätt `AGENTMEMORY_STATE_BACKEND=redis` (plus `AGENTMEMORY_REDIS_URL`) för att växla båda workers till iii-enginens inbyggda `redis`-adapter, som lagrar varje nyckel som ett Redis-hashfält (`HSET`) istället för att skriva om ett helt scope vid varje skrivning:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` har `file` som standard; att lämna den osatt behåller dagens beteende oförändrat, och ett okänt värde (något annat än `file` eller `redis`) ger ett startfel istället för en tyst reserv. `/agentmemory/status` och viewerns Health-sida (raden State store) rapporterar vilken backend som är aktiv och om den svarar, aldrig URL:en.
+
+**Endast rent `redis://`.** Den fastlåsta enginen (0.22.1) bygger sin Redis-klient utan TLS-stöd, så en `rediss://`-URL (de flesta hanterade Redis-erbjudanden, som Upstash, Redis Cloud och ElastiCache med kryptering under överföring, är som standard enbart TLS) misslyckas med att ansluta. Anslutningen är okrypterad, så Redis-lösenordet och varje lagrat minne passerar tråden i klartext: peka mot en lokal Redis eller en på ett privat nätverk du litar på. För någon annan Redis, kör en krypterad tunnel (stunnel, SSH eller en VPN) på agentmemory-värden, så att det rena `redis://`-hoppet stannar på den värden och tunnelns uppströmsanslutning är krypterad och autentiserad. Om ett Redis-lösenord innehåller ett enkelt citattecken, procent-koda det (`%27`); enginen expanderar URL:en i sin YAML-konfiguration innan den tolkas.
+
+**En Redis-server per `--instance`.** Enginens Redis-nyckelprefix (`state:`, `stream::`) är fasta, så två agentmemory-instanser (`--instance 1`, `--instance 2`, ...) som pekar mot samma databas skriver över varandras data. Ett separat databasindex (`redis://localhost:6379/1`) håller den lagrade datan åtskild, men enginen vidarebefordrar live-viewerhändelser över en Redis pub/sub-kanal (`stream::events`), och Redis pub/sub ignorerar databasindexet, så varje instans viewer skulle fortfarande visa den andras livehändelser. Ge varje instans sin egen Redis-server (eller port) när du kör mer än en.
+
+**Vad som förblir samma, och vad som skiljer sig.** Varje funktion i agentmemory fungerar på Redis: sessioner, observationer, minnen (remember, supersede, evolve, forget), sökning och indexbuckets, lärdomar, grafen, granskningsloggen och dess månadsscopes, export och import, governance-raderingar, konsolideringsstatus, viewer-snapshoten och dess liveström, samt hälsoövervakaren. Enginen lagrar varje scope som en Redis-hash (`HSET`/`HGET`/`HGETALL`) och utlöser samma state-triggers som fil-lagret. Tre skillnader i enginen hanteras inuti agentmemory:
+
+- Redis returnerar ett scopes poster i ingen bestämd ordning. agentmemory sorterar dem äldst först (efter skapelsetiden i post-id:t, sedan dess tidsstämpel) så att listor, sidbläddring och exportdelar kommer tillbaka i samma ordning som på fil-lagret.
+- Enginen tillämpar partiella uppdateringar på Redis i ett Lua-skript som omvandlar tomma arrayer till tomma objekt. agentmemory tillämpar de uppdateringarna själv (läsa, ändra, skriva under ett lås per nyckel) på Redis, så att fält som `tags: []` förblir arrayer.
+- Den äldre granskningslogg-kontrollen läser det gamla scopet från Redis istället för att leta efter fil-lagrets fil på disk.
+
+En skillnad kräver din uppmärksamhet: **efter att Redis har startat om slutar enginen vidarebefordra livehändelser** till viewern tills agentmemory startas om. Data sparas och läses fortfarande normalt. Hälsoövervakaren skickar en testhändelse genom Redis var 30 sekunder; när den inte kommer tillbaka visar `/agentmemory/status` och viewerns Health-sida "Live updates are not reaching the viewer" med åtgärden: starta om agentmemory. Om Redis är nere visar statusrapporten "The state store is not answering" och hur man kontrollerar det (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Att lista ett mycket stort scope läser hela hashen i ett `HGETALL`, samma kostnad som fil-lagret att hålla det i minnet.
+
+**Rekommenderade Redis-inställningar.** Standardpolicyn för snapshot, `save 3600 1 300 100 60 10000`, kan förlora minuter av skrivningar vid en krasch, värre än fil-lagrets 5-sekunders flush-fönster. Sätt `appendonly yes` för allt du skulle bry dig om att förlora. Sätt `maxmemory-policy noeviction`; `allkeys-lru` eller liknande tappar minnen i det tysta när Redis når sin minnesgräns.
+
+En native (icke-Docker) start, och varje driftsättningsmall [med ett klick](../deploy/) (de skriver över den medföljande `iii-config.yaml` och startar native), läser `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` och renderar dem in i den startade `iii-config`. URL:en själv skrivs aldrig till den renderade filen, bara en referens `${AGENTMEMORY_REDIS_URL}` som motor-processen expanderar från sin egen miljö vid start. Bara detta repos egen Docker Compose-väg (`AGENTMEMORY_USE_DOCKER=1`, eller att återuppta en engine som redan startats på det sättet) monterar `iii-config.docker.yaml` skrivskyddat och renderar aldrig; `agentmemory start` varnar när den upptäcker den kombinationen. Byt den filen för hand, enligt samma form `name: redis` / `config: redis_url: ...` som visas i dokumentationen för workers [iii-state](https://workers.iii.dev/workers/iii-state) och [iii-stream](https://workers.iii.dev/workers/iii-stream), och peka `redis_url` mot en Redis som går att nå från containern. `docker-compose.yml` skickar `AGENTMEMORY_REDIS_URL` in i engine-containern, så `redis_url: '${AGENTMEMORY_REDIS_URL}'` fungerar där och håller URL:en utanför den monterade filen.
+
+Den renderade konfigurationen håller URL:en utanför `~/.agentmemory/data/iii-config.runtime.yaml`, men enginens egen konfigurationsworker sparar fortfarande det *expanderade* värdet till `~/.agentmemory/config/iii-state.yaml` och `iii-stream.yaml` när den startar (iii-enginens `${VAR}`-expansion sker innan den workern lagrar sitt frö, och den lagrar det upplösta värdet, inte referensen). Behandla den katalogen som om den innehåller en autentiseringsuppgift: `chmod 700 ~/.agentmemory` på varje delad värd, och föredra en Redis ACL-användare begränsad till det agentmemory behöver framför databasens admin-uppgifter.
+
+**Migrering sker inte automatiskt.** Att växla `AGENTMEMORY_STATE_BACKEND` börjar med ett tomt lager på båda sidor; ingenting kopierar befintlig data från fil till Redis eller tillbaka. Exportera från den backend du lämnar och importera till den du flyttar till. Detta körs identiskt under bash och zsh (inklusive `bash -u`). En array som `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gör det inte: zsh behåller headern som ett enda felformat ord där bash delar upp den i två, så båda förfrågningarna ger 401 närhelst `AGENTMEMORY_SECRET` är satt:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` accepterar också `?maxSessions=` och `?offset=` för att dela upp ett stort korpus över flera anrop; `strategy` vid import är `merge` (säker standard), `replace` eller `skip`.
+
+### Vad iii ersätter
+
+| Traditionell stack | agentmemory använder |
+|---|---|
+| Express.js / Fastify | iii HTTP-triggers |
+| SQLite / Postgres + pgvector | iii KV-state + vektorindex i minnet |
+| SSE / Socket.io | iii-strömmar (WebSocket) |
+| pm2 / systemd | iii-enginens worker-övervakning |
+| Prometheus / Grafana | iii OTEL + hälsoövervakare |
+| Anpassade pluginsystem | `iii worker add ` |
+
+**225 källkodsfiler · ~54,000 LOC · 2,600+ tester · 312 funktioner · 66 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
+
+---
+
+
+
+### LLM-leverantörer
+
+agentmemory upptäcker leverantörer automatiskt från din miljö. En leverantör gör LLM-baserade operationer tillgängliga, men leverantörskonfiguration ensam aktiverar inte LLM-skriven observationskomprimering. Den vägen kräver både en leverantör och `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Leverantör | Konfiguration | Anteckningar |
+|----------|--------|-------|
+| **No-op (standard)** | Ingen konfiguration behövs | LLM-baserad komprimering/sammanfattning är inaktiverad. Syntetisk komprimering och BM25-återkallning fungerar fortfarande. Se `AGENTMEMORY_ALLOW_AGENT_SDK` nedan om du tidigare förlitade dig på Claude-prenumerationsreserven. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Fakturering per token |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-kompatibel |
+| Gemini | `GEMINI_API_KEY` | Aktiverar även embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Vilken modell som helst |
+| OpenAI API | `OPENAI_API_KEY` | Standard `gpt-5.6-luna`, åsidosätt med `OPENAI_MODEL` |
+| **Lokal (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) eller `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Allt som är OpenAI-API-kompatibelt. Noll kostnad, körs på din hårdvara. Se [Lokala modeller](#local-models-ollama--lm-studio--vllm) nedan. |
+| Claude-prenumerationsreserv | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Endast opt-in. Startar `@anthropic-ai/claude-agent-sdk`-sessioner; den orsakade tidigare obegränsad Stop-hook-rekursion, så den är inte längre standard. |
+
+### Lokala modeller (Ollama / LM Studio / vLLM)
+
+agentmemory talar med vilken OpenAI-API-kompatibel server som helst, så allt som exponerar `/v1/chat/completions` fungerar utan kodändringar. Inga betalda nycklar, inget moln, inga rate limits; körs helt på din hårdvara.
+
+**Ollama** (standardport `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (standardport `1234`):
+
+Öppna LM Studio → fliken Local Server → Start Server. Välj vilken chattmodell som helst från väljaren (Qwen 3, gpt-oss, DeepSeek R1, osv.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: samma form. Peka `OPENAI_BASE_URL` mot vilken URL din server än exponerar och sätt `OPENAI_MODEL` till ett namn din server accepterar.
+
+**Modellval för minnesarbete**: komprimering och sammanfattning är korta uppgifter (<2K tokens in, <500 tokens ut) där en 7B instruct-modell räcker gott och väl. Rekommendationer:
+
+| Modell | Storlek | Varför |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Balanserad standard på en 16 GB-maskin; stark på extraktion och verktygsformad text |
+| `qwen3:4b` | ~2.6 GB | Minsta rimliga alternativet; funkar för komprimering, svagare för grafextraktion |
+| `qwen3-coder:30b` | ~19 GB | Bästa lokala valet för kodformade sessioner (30B MoE, 3.3B aktiva) på 24-32 GB hårdvara |
+| `gpt-oss:20b` | ~14 GB | Stark generell modell som ryms i 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning-destillat; långsammare men renare extraktioner |
+
+Qwen 3-modeller tänker som standard och kan bränna hela tokenbudgeten på reasoning innan någon utdata alls. Sätt `AGENTMEMORY_LLM_NOTHINK=1` för att lägga till `/no_think` i prompter för grafextraktion, och höj `MAX_TOKENS` (16384 funkar) om extraktioner kommer tillbaka tomma.
+
+Reasoning-modeller (`o1`-stil med ``-block) kan returnera tomt `content` med ett `reasoning`-fält som din lokala server kanske inte exponerar. Om extraktioner kommer tillbaka tomma, byt först till en modell utan reasoning. Miljövariabeln `OPENAI_REASONING_EFFORT=none` kan också inaktivera tänkande på Ollama Cloud-tänkande-modeller som speglar OpenAIs reasoning-schema.
+
+Lokala embeddings levereras som ett valfritt beroende men är inte aktiverade som standard. Sätt `EMBEDDING_PROVIDER=local` för att aktivera `Xenova/all-MiniLM-L6-v2` (384 dimensioner). Den första embedding-förfrågan laddar ner modellen; inferensen sker därefter på enheten. Utan den inställningen eller en fjärr-embedding-nyckel förblir vektorer inaktiverade, `mem::search` använder BM25, och `smart-search` kan fortfarande lägga till befintliga grafmatchningar.
+
+### Kostnadsmedvetet modellval
+
+När LLM-skriven bakgrundskomprimering är aktiverad med både en leverantör och `AGENTMEMORY_AUTO_COMPRESS=true`, körs den vid varje observation, så modellvalet förändrar den månatliga kostnaden på ett betydande sätt. Infångad arbetsbelastningsdata: 635 förfrågningar / 888K tokens / 35 timmars aktiv användning, körd mot tre OpenRouter-modeller enligt prissättningen 2026-05-23.
+
+| Nivå | Modell | Indata / 1M | Utdata / 1M | Kostnad för de infångade 35 timmarna | Anteckningar |
+|------|-------|------------|-------------|---------------------------|-------|
+| Rekommenderad | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (uppskattat) | Senaste DeepSeek; billigaste rekommenderade valet för komprimeringsarbetsbelastningar. |
+| Rekommenderad | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid kvalitet på komprimering + sammanfattning till ~10 gånger lägre kostnad än Sonnet. |
+| Rekommenderad | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Stark kodresonering om dina sessioner är starkt kodformade. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (uppskattat) | Samma listpris som den uppmätta Sonnet 4.6-körningen; introduktionspris $2/$10 till och med 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (uppskattat) | Flaggskeppsnivå; dyrt för alltid-på-bakgrundsarbete. |
+| Undvik | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (uppskattat) | Flaggskeppsklass-modell; överspenderat för komprimering. |
+
+Uppmätta rader kommer från den infångade körningen; rader märkta (uppskattat) skalar samma tokenmix efter varje modells listpris.
+
+agentmemory skriver ut en körtidsvarning när `OPENROUTER_MODEL` matchar ett premiumnivåmönster. Sätt `AGENTMEMORY_SUPPRESS_COST_WARNING=1` för att tysta den när du har gjort ett informerat val.
+
+Avvägning mellan kvalitet och kostnad för minnesarbete: komprimering är en sammanfattningsuppgift med relativt lösa kvalitetskrav (agenten läser om sammanfattningen, inte användaren). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder hamnar inom felmarginalen av Sonnet på denna uppgift samtidigt som de kostar 10-70 gånger mindre. Spara premiumnivå-modellerna för frågor du läser direkt.
+
+Källor: [OpenRouter-prissättning för Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-prissättningsanteckningar](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Multiagent-minne (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+I multiagent-uppsättningar där flera roller delar en agentmemory-server (architect / developer / reviewer / researcher / support-agent), taggar `AGENT_ID` varje skrivning med rollen som gjorde den. `AGENTMEMORY_AGENT_SCOPE` styr om återkallning filtrerar på den taggen.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Två lägen:
+
+| Läge | Taggar skrivningar | Filtrerar återkallning | När man använder det |
+|------|------------|---------------|-------------|
+| `shared` (standard) | ja | nej | Kontext mellan agenter med granskningsspår. Architect kan se vad developer noterade, men varje rad registrerar vem som sa det. |
+| `isolated` | ja | ja | Strikt separation. Architect ser aldrig developers observationer / minnen / sessioner. |
+
+Vad som taggas när `AGENT_ID` är satt: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rollen flödar från `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Vad som filtreras i isolerat läge: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Varje endpoint accepterar `?agentId=` för att åsidosätta per förfrågan, och `?agentId=*` för att helt välja bort miljö-scopet. `/memories` accepterar också `?includeOrphans=true` för att visa minnen från före AGENT_ID vars `agentId` är odefinierad.
+
+Åsidosättning per anrop på SDK-/REST-lagret: varje muterande endpoint (`/session/start`, `/remember`) accepterar ett `agentId`-fält i förfrågans body som vinner över miljövariabeln. Användbart för körtider som dirigerar många roller genom en serverprocess. MCP-verktyget `memory_save` exponerar samma `agentId`-fält, den fristående stdio-servern vidarebefordrar både `agentId` och `project`, och sparade minnen bär `agentId` in i sökindexet, så agent-scopead sökning täcker minnen lika väl som observationer.
+
+När `AGENT_ID` inte är satt förblir minnet oscopat (äldre beteende, inga taggar, inga filter).
+
+### Portar
+
+agentmemory + iii-engine binder fyra portar som standard. Om en omstart misslyckas med `port in use`, säger den här tabellen vilken process du ska leta efter.
+
+| Port | Process | Syfte | Åsidosättning via miljövariabel |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Intern strömmar-worker (används av agentmemory + viewer) | `III_STREAM_PORT` (att föredra) eller äldre `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer i realtid (`http://localhost:3113`) | `III_VIEWER_PORT` eller `AGENTMEMORY_VIEWER_URL` för den rapporterade URL:en |
+| `49134` | iii-engine | WebSocket; workers registrerar sig här, OTel-telemetri flödar över den | `III_ENGINE_PORT` eller `III_ENGINE_URL` |
+
+`--port ` ändrar REST-ankaret och härleder strömmar `N+1`, viewer `N+2`, och engine-WebSocket `N+46023` bara där motsvarande explicita port eller URL ovan är osatt. Det skapar inte en isolerad livscykel-namnrymd. Använd `--instance 1` för en andra daemon; den använder ankare 3211, defaultar till `3211/3212/3213/49234`, och får en separat data- och livscykelkatalog `instance-1`. Instanser 1 till 50 följer samma mönster.
+
+Den fastlåsta enginen startar med `--no-update-check` (inga uppslag mot GitHub för uppdateringar eller säkerhetsrådgivningar vid start) och med iii:s anonyma användningstelemetri avstängd: agentmemory sätter `III_TELEMETRY_ENABLED=false` för enginen den startar om du inte exporterar variabeln själv, och den medföljande compose-filen gör samma sak.
+
+Rensning av gamla processer när portar förblir bundna efter en kraschad körning:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` städar bort både workerns och enginens pidfil rent vid en skonsam native-avstängning. I Docker-läge flushar den native-workern, stoppar exakt den validerade engine-containern, och bevarar både containern och dess `/data`-montering för en förlustfri omstart; nästa start validerar och återupptar samma container. Avinstallation med Docker som backend kräver `agentmemory remove --keep-data`: den tar bort delade agentmemory-hanterade filer samtidigt som den bevarar den validerade containern, dess datamontering och den livscykelpost som behövs för att återställa dem. Destruktiv radering av Docker-data lämnas avsiktligt till operatören efter en backup. CLI:n vägrar också att adoptera eller signalera Docker- eller VM-portinnehavare (Docker backend, vpnkit, colima) som den native enginen om inte `--force` anges. Den manuella rensningen ovan är bara till för fallet efter en krasch där ingen pidfil lämnats kvar.
+
+### Konfigurationsfil
+
+Lägg agentmemorys körtidskonfiguration i `~/.agentmemory/.env` istället för att exportera variabler i varje skal. Om viewern visar ett konfigurationstips som `export ANTHROPIC_API_KEY=...`, kopiera det in i den här filen som `ANTHROPIC_API_KEY=...` utan `export`-prefixet, och starta sedan om agentmemory.
+
+Processens miljövariabler fungerar fortfarande och har företräde framför värden i filen.
+
+På Windows finns samma fil på `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+För att testa med en Claude Code Pro/Max-prenumeration istället för en API-nyckel, aktivera det explicit:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM-skriven observationskomprimering kräver båda raderna: åtkomst till en LLM-leverantör (inklusive denna explicita prenumerationsreserv) och `AGENTMEMORY_AUTO_COMPRESS=true`. En leverantör ensam lämnar standardvägen för syntetisk komprimering intakt.
+
+Konsolidering (grafnoder, lärdomar, crystals) är aktiverad som standard närhelst en LLM-leverantör är konfigurerad. Välj bort den explicit med `CONSOLIDATION_ENABLED=false` om du vill ha LLM-fri drift. Grafextraktion är en separat flagga:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Miljövariabler
+
+Skapa `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoints på port `3111`. REST API:et binder till `127.0.0.1` som standard. Skyddade endpoints kräver `Authorization: Bearer `, och mesh-synk-endpoints kräver en explicit satt `AGENTMEMORY_SECRET` på båda parterna.
+
+**Autentisering är aktiverad som standard.** När `AGENTMEMORY_SECRET` inte är satt (i skalet eller i `~/.agentmemory/.env`), genererar servern en slumpmässig hemlighet vid första start och lagrar den i `~/.agentmemory/secret` med rättigheterna `0600`. Varje medföljande klient läser den därifrån när den talar med en lokal server: CLI:n, viewern, hookarna under `plugin/scripts`, MCP-servern och `@agentmemory/mcp`-shimmen, konfigurationerna skrivna av `agentmemory connect`, och de medföljande integrationerna för OpenCode, Pi, OpenClaw, Hermes och filsystemsbevakaren. Den lagrade hemligheten skickas bara till loopback-URL:er (`localhost`, `127.0.0.0/8`, `::1`). En explicit `AGENTMEMORY_SECRET` vinner alltid, och fjärrklienter måste fortfarande ha den satt. Docker och startpunkterna i `deploy/` genererar och exporterar redan sin egen hemlighet. För att anropa API:et för hand:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Regler för skrivförfrågningar.** `POST`-, `PUT`-, `PATCH`- och `DELETE`-förfrågningar till REST API:et och viewern måste skicka `Content-Type: application/json` (en `charset`-parameter är okej) närhelst de bär en body, och en `Origin`-header, när den finns, måste vara en loopback-origin för den konfigurerade REST- eller viewer-porten eller finnas listad i `VIEWER_ALLOWED_ORIGINS` (kommaseparerat, t.ex. `https://memory.example.com`). Klienter som inte skickar någon `Origin`-header (CLI, hooks, MCP, curl, server-till-server) påverkas inte. Viewern accepterar också sitt eget origin.
+
+**Filsökvägar.** Endpoints som läser eller skriver filer (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) accepterar bara sökvägar under `~/.agentmemory`, instansens datakatalog, eller en katalog listad i `AGENTMEMORY_IMPORT_ROOT` (separera flera med `:`, eller `;` på Windows). `/replay/import-jsonl` accepterar också sin standard `~/.claude/projects`. `/obsidian/export` håller sig inom `AGENTMEMORY_EXPORT_ROOT` och `/migrate` inom `~/.agentmemory`. Symlinkar löses upp innan varje kontroll.
+
+**Rensning av hemligheter.** API-nycklar, bearer-tokens, PEM-privatnyckelblock och autentiseringsuppgifter inbäddade i URL:er (`scheme://user:password@host`) redigeras bort innan text lagras, på varje skrivväg: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, komprimerings- och sammanfattningsutdata, crystals och grafnoder.
+
+
+Viktiga endpoints
+
+| Metod | Sökväg | Beskrivning |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Hälsokontroll (alltid publik) |
+| `GET` | `/agentmemory/status` | Vad som är fel och hur man fixar det (HTML för webbläsare, annars JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Allt viewern visar, i ett svar |
+| `POST` | `/agentmemory/session/start` | Starta session + hämta kontext |
+| `POST` | `/agentmemory/session/end` | Avsluta session |
+| `POST` | `/agentmemory/observe` | Fånga in observation (se infångningsleverans nedan) |
+| `GET` | `/agentmemory/capture` | Infångningsinkorg, dödbrev och offline-spool |
+| `POST` | `/agentmemory/capture/retry` | Försök igen med dödbrevsinfångningar |
+| `POST` | `/agentmemory/capture/drain` | Skicka den lokala offline-spoolen nu |
+| `POST` | `/agentmemory/smart-search` | Hybridsökning |
+| `POST` | `/agentmemory/context` | Generera kontext |
+| `POST` | `/agentmemory/remember` | Spara till långtidsminnet |
+| `POST` | `/agentmemory/forget` | Radera observationer |
+| `POST` | `/agentmemory/enrich` | Filkontext + minnen + buggar |
+| `GET` | `/agentmemory/profile` | Projektprofil |
+| `GET` | `/agentmemory/export` | Exportera all data |
+| `POST` | `/agentmemory/import` | Importera från JSON |
+| `POST` | `/agentmemory/graph/query` | Fråga kunskapsgrafen |
+| `POST` | `/agentmemory/graph/compact` | Trimma överdimensionerat grafursprung |
+| `POST` | `/agentmemory/team/share` | Dela med team |
+| `GET` | `/agentmemory/audit` | Granskningsspår |
+
+Fullständig endpoint-lista: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Infångningsleverans.** Hooks skickar varje observation en gång till `POST /agentmemory/observe` med ett `eventId`. Det är värdens eget id för anropet när nyttolasten har ett (till exempel Claude Codes `tool_use_id`), annars en hash av sessionen, hook-typen, verktygsnamnet, indata, utdata och värdens tidsstämpel. Servern skriver händelsen till en infångningsinkorg i state-lagret, lagrar observationen, och tar sedan bort inkorgsposten. Statuskoden säger vad som hände:
+
+| Status | `status`-fält | Betydelse |
+|---|---|---|
+| `201` | `accepted` | Lagrad. `observationId` är den nya observationen. |
+| `202` | `accepted` (`state: "retrying"`) | Accepterad, men lagringen misslyckades. Servern försöker igen, även efter en omstart. |
+| `200` | `duplicate` | Det här `eventId` hade redan accepterats. `observationId` är den befintliga observationen; ingenting nytt lagras. |
+| `400` / `422` | `rejected` | Ogiltig nyttolast, eller lagringen misslyckades permanent (händelsen behålls som ett dödbrev). |
+| `503` | `rejected` (`retryable: true`) | Inkorgen är full (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hooks lägger händelsen i kö och skickar den senare. |
+
+Misslyckade händelser får nya försök var `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) med dubblerande backoff, upp till `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Händelser som fortfarande misslyckas stannar i inkorgen som dödbrev, listas på `/agentmemory/status` och viewerns Health-sida, och kan försökas igen med `POST /agentmemory/capture/retry` (`{"eventId": "..."}` eller `{"all": true}`). Accepterade händelse-id:n minns i `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 timmar, högst `AGENTMEMORY_CAPTURE_EVENTS_MAX` id:n), så en hook som spelas upp igen efter en timeout eller en omstart lagras en gång, medan två separata verktygsanrop med sina egna värd-id:n lagras två gånger även om deras innehåll är identiskt. När en observation raderas (forget, sessionsradering, utrensning, auto-glömning eller en import som ersätter lagret), markeras dess händelse som raderad innan observationen tas bort, så en uppspelning av den händelsen inom samma fönster besvaras som en dubblett och lagrar ingenting. State-lagret skriver till disk var 2 sekunder, så en besvarad händelse kan fortfarande bara finnas i minnet för ett ögonblick. För att täcka det bär varje `2xx`-svar också serverns `bootId` (ny vid varje start), `acceptedAt` och `durableAfterMs` (sparintervallet plus 1.5 s på fil-lagret, 1.5 s på redis, där varaktighet är operatörens inställning). Hooks behåller händelsen i den lokala spoolen tills det fönstret har passerat och raderar den vid ett senare anrop utan ytterligare en förfrågan. Om `bootId` har ändrats vid det laget startade servern om, så hooken skickar händelsen igen med samma `eventId`; en händelse som faktiskt nådde disken lagras inte två gånger. Servern skickar också sådana händelser själv vid start och vid varje återförsöksintervall, så en omstart förlorar ingenting även om ingen hook körs efteråt. Äldre hooks ignorerar de extra fälten, och nya hooks mot en äldre server kastar händelsen vid `2xx` som tidigare.
+
+När servern är nere, inte svarar i tid eller returnerar en 5xx, lägger hooken till observationen i en lokal spool-fil, `/capture-spool/-.jsonl` (åsidosätt mappen med `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Filen är privat för din användare (rättigheterna 600), hemligheter redigeras bort på samma sätt som servern gör det, den rymmer högst `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) och tappar poster äldre än `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). När den är full tappas nya poster och räknas, och `/agentmemory/status` rapporterar det. Hooken avslutas fortfarande med 0 inom sin tidsgräns och lägger inte till någon förfrågan när servern är frisk. Spoolen skickas vid nästa start och av den första hooken som når servern igen, i en bakgrundsprocess så att agenten inte väntar. Händelse-id:n gör detta säkert: en observation som faktiskt anlände innan en timeout lagras inte två gånger. `npx @agentmemory/agentmemory capture` visar spoolen och serverns inkorg, `--drain` skickar spoolen nu, och `GET /agentmemory/capture` returnerar samma sak som JSON. Sätt `AGENTMEMORY_CAPTURE_SPOOL=false` för att stänga av spoolen.
+
+**Kompaktering av grafursprung.** Varje kunskapsgraf-nod och -kant behåller id:n för de senaste 32 observationerna den kom från. Lager skrivna innan den gränsen kan hålla tusentals id:n per het nod, vilket gör grafsökning och viewern långsamma eller slår ut workern. agentmemory fixar detta själv: vid den första starten efter en uppgradering trimmar den varje nod, kant, ersatt kant (den temporala grafhistoriken) och den cachade snapshoten till gränsen i bakgrunden, i små skivor med en paus mellan dem, så att sökning, infångning och viewern fortsätter fungera. Den sparar sitt förlopp, återupptas efter en omstart och körs aldrig igen när den väl är klar. `/agentmemory/status` och viewerns Health-sida visar den som väntande, körande (med aktuellt scope och position), klar eller misslyckad. Sätt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` för att stänga av den.
+
+För att köra den för hand, anropa `POST /agentmemory/graph/compact`. Den går igenom namn- och kant-nyckel-indexen istället för att lista varje nod och kant, och är säker att köra igen. När den trimmar id:n skriver den en `graph_compact`-granskningspost.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+På ett stort lager, eller när anropet returnerar 504, kör den i skivor. Skicka `scope` (`nodes`, `edges` eller `history`), `offset` och `limit`, och anropa sedan igen med det returnerade `nextOffset` tills det är `null`. Gör detta för `nodes`, `edges` och `history`, och avsluta med ett `{"scope":"snapshot"}`-anrop, eftersom en skivad körning inte rör den cachade snapshoten.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Förutsättningar:** Node.js >= 20 med npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 eller Docker. Den automatiska motorinstallationen för macOS/Linux kräver också `curl`, ett POSIX-`sh` och `tar`; native Windows använder den manuellt fastlåsta `iii.exe`, WSL2, eller Docker Desktop.
+
+
+
+ Naaalala ng iyong coding agent ang lahat. Wala nang paulit-ulit na pagpapaliwanag.
+ Nakabatay sa iii engine
+
+ Permanenteng memory para sa Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, at anumang MCP client.
+
+ Pinalalawak ng gist ang LLM Wiki pattern ni Karpathy gamit ang confidence scoring, lifecycle, knowledge graph, at hybrid search: ang agentmemory ang implementasyon nito.
+
+
+---
+
+## I-install
+
+Mga Kinakailangan:
+
+- Node.js 20 o mas bago, kasama ang npm at npx (`node -v`, `npm -v`, at `npx -v`).
+- Kailangan din ng awtomatikong pag-install ng iii-engine sa macOS/Linux ang `curl`, isang POSIX `sh`, at `tar`. Posibleng wala ang mga ito sa mga minimal na image gaya ng `node:20-slim`.
+- Kinakailangang i-install nang manu-mano ang pinned iii-engine v0.22.1 `iii.exe` sa native Windows. Ang WSL2 o Docker Desktop ang iba pang suportadong landas.
+
+Standard na command para sa sariwang pag-install:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Ang unang pagpapatakbo ay isang interactive setup: pipiliin mo ang mga agent na i-wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pipili ka ng LLM provider o mananatiling keyless, at inilalagay nito ang config, sinisimulan ang memory server at ang pinned nitong iii engine, at nag-aalok na i-install nang global para gumana ang payak na `agentmemory` command kahit saan pagkatapos. Tinatanggap ng `-y` ang package prompt ng npx, at iniiwasan ng `@latest` ang isang lumang cached release. Pinagagana ng provider ang mga LLM feature, pero ang LLM-written na observation compression ay magsisimula lamang kapag naka-set din ang `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Pinapatay ng keyless mode ang vector embeddings. Ginagamit ng `memory_recall` (ang `mem::search` path) ang BM25, habang ang `memory_smart_search` ay maaari ring pagsamahin ang structural graph matches kapag umiiral na ang graph data. Para sa libreng on-device semantic recall, i-set ang `EMBEDDING_PROVIDER=local` sa `~/.agentmemory/.env` at i-restart. Ang unang embedding request ay nag-download ng `Xenova/all-MiniLM-L6-v2`; tumatakbo na lokal ang inference pagkatapos ng unang pag-download na ito ng model.
+
+Gumagamit ang local runtime ng apat na port: `3111` para sa REST/MCP HTTP, `3112` para sa iii streams, `3113` para sa viewer, at `49134` para sa iii worker WebSocket. Ang persistent iii state ay nakatira sa `~/Library/Application Support/agentmemory` sa macOS, `$XDG_DATA_HOME/agentmemory` o `~/.local/share/agentmemory` sa Linux, at `%APPDATA%\agentmemory` sa Windows. Gamitin ang `--data-dir ` o `AGENTMEMORY_DATA_DIR` para i-override ito, at gamitin ulit ang parehong value sa bawat restart. Para sa backward compatibility, ang umiiral na `./data/state_store.db` o `./data/iii-config.yaml` ay mananaig kaysa sa platform default para sa instance 0; mananalo pa rin ang explicit flag o environment override.
+
+Pagkatapos, patunayan na gumagana ang recall at bigyan ang iyong agent ng mga skill nito:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Dapat tumama ang mga keyword search sa default na keyless mode gamit ang BM25. Ang query ng demo na `database performance optimization` ay sadyang semantic at puwedeng magbalik ng zero hanggang hindi pa naka-configure ang isang embedding provider.
+
+Mas gusto mo bang ipagawa lahat sa isang coding agent? Bigyan ito ng isang instruction:
+
+> Kunin at sundin ang mga instruction sa: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+I-wire ang mas maraming agent anumang oras gamit ang `agentmemory connect ` — 20 adapter na nakalista sa [Gumagana sa Bawat Agent](#works-with-every-agent). Kumpletong command reference sa [Mabilisang Simula](#quick-start).
+
+
+Windows
+
+Ang pinakamadaling landas ay ang WSL2. Ang native Windows engine setup ay nangangailangan ng pag-download ng pinned v0.22.1 ZIP at manu-manong pag-extract ng `iii.exe`; hindi ito awtomatikong na-extract ng CLI. Suportado rin ang Docker Desktop. Tingnan ang [mga tala para sa Windows](#windows) para sa step-by-step na gabay.
+
+
+
+
+Global na Pag-install / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Ang npx command sa itaas ay nananatiling standard na landas para sa bagong pag-install at iniiwasan nito ang mga isyu sa global-prefix permission.
+
+
+
+
+Lumang bersyon ang ibinibigay ng npx
+
+Nag-cache ang npx ayon sa bersyon. Pilitin ang paggamit ng pinakabago gamit ang `npx -y @agentmemory/agentmemory@latest`, o burahin ang cache nang isang pagkakataon gamit ang `rm -rf ~/.npm/_npx` (macOS/Linux; sa Windows, burahin ang `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+May sariling iii engine ka nang tumatakbo
+
+Nagpipin ang agentmemory sa iii-engine v0.22.1 at hindi ito kakabit sa ibang bersyon (hindi kayang kausapin ng worker ang protocol ng ibang engine). Itigil ang ibang engine, pagkatapos patakbuhin ang `npx -y @agentmemory/agentmemory@latest`. Ito ay mag-install at magpapatakbo ng pinned v0.22.1 sa `~/.agentmemory/bin`, hindi gagalawin ang sarili mong `iii`.
+
+
+
+---
+
+
+
+Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST API. Ibinabahagi ng lahat ng agent ang parehong memory server.
+
+
+
+
+
+Claude Code
+native plugin + 12 hook + MCP
+
+
+
+Codex CLI
+native plugin + 6 hook + MCP
+
+
+
+GitHub Copilot CLI
+MCP + plugin hook/skill
+
+
+
+Cursor
+native plugin + 7 hook + MCP
+
+
+
+OpenCode
+capture plugin + MCP
+
+
+
+
+
+Devin
+6 hook + skill + MCP
+
+
+
+OpenClaw
+native plugin + MCP
+
+
+
+Hermes
+native plugin + MCP
+
+
+
+pi
+native plugin + MCP
+
+
+
+OpenHuman
+native na Memory trait backend
+
+
+
+
+
+Gemini CLI
+MCP server
+
+
+
+Antigravity
+MCP + hook
+
+
+
+Claude Desktop
+MCP server
+
+
+
+Warp
+connect + MCP + skill
+
+
+
+Zed
+MCP server
+
+
+
+
+
+Cline
+MCP server
+
+
+
+Continue
+MCP server
+
+
+
+Droid
+MCP server
+
+
+
+Kiro
+MCP server
+
+
+
+Qwen Code
+MCP server
+
+
+
+
+
+DeepSeek Harness
+MCP server
+
+
+
+Roo Code
+MCP server
+
+
+
+Kilo Code
+MCP server
+
+
+
+Goose
+MCP server
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Gumagana sa anumang agent na nakikipag-usap gamit ang MCP o HTTP. Isang server, ibinabahagi ang mga memory sa lahat ng ito.
+
+
+---
+
+Ipinaliwanag mo ang parehong architecture sa bawat session. Natutuklasan mong muli ang parehong mga bug. Itinuturo mong muli ang parehong mga preference. Ang built-in memory (CLAUDE.md, .cursorrules) ay may limitasyong 200 linya at nauupos. Ayusin ito ng agentmemory. Tahimik nitong kinukuha ang ginagawa ng iyong agent, kino-compress ito sa searchable na memory, at itinuturok ang tamang context kapag nagsimula ang susunod na session. Isang command. Gumagana sa lahat ng agent.
+
+**Ano ang nagbabago:** Sa Session 1, nag-set up ka ng JWT auth. Sa Session 2, humiling ka ng rate limiting. Alam na ng agent na ang auth mo ay gumagamit ng jose middleware sa `src/middleware/auth.ts`, sinasaklaw ng iyong mga test ang token validation, at pinili mo ang jose kaysa sa jsonwebtoken para sa Edge compatibility — walang muling pagpapaliwanag at walang copy-paste.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Bilang default, itinatago ng agentmemory ang iii-engine state sa labas ng repository kung saan ito sinimulan: `~/Library/Application Support/agentmemory` sa macOS, `$XDG_DATA_HOME/agentmemory` o `~/.local/share/agentmemory` sa Linux, at `%APPDATA%\agentmemory` sa Windows. Ang umiiral na legacy na `./data/state_store.db` o `./data/iii-config.yaml` ay ginagamit ulit para sa instance 0 bago ang platform default na iyon. Para tahasang pumili ng lokasyon, ipasa ang `--data-dir ` o i-set ang `AGENTMEMORY_DATA_DIR`; mananaig ang alinmang explicit setting kaysa sa legacy discovery:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Ginagamit ng native at Docker launches ang parehong resolved host directory; Docker bind-mount ito sa `/data`. Idinadagdag ng `--instance 1` ang `instance-1` sa resolved directory at pinipili ang hiwalay na default port quartet na `3211/3212/3213/49234`.
+
+Pinakabagong release notes: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Katumpakan ng Retrieval
+
+**coding-agent-life-v1** (in-house corpus, reproducible sa sandbox)
+
+| Adapter | P@5 | R@5 | Top-5 hit rate | p50 latency |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% top-5 hit rate sa **P@5 math ceiling** para sa corpus na ito (0.240, tingnan ang scorecard). Nakukuha ng hybrid ang bawat gold session; nawawala sa grep ang 1 sa 2 gold sa multi-session temporal query. Ang lift ay sa **recall + temporal**, hindi sa aggregate precision. Maliit at gold-sparse ang benchmark na ito; mas mahusay na nagkakaiba ang mas malaking LongMemEval-S sa ibaba. Buong per-type breakdown + correction note: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+
+**LongMemEval-S** (ICLR 2025, 500 tanong)
+
+| Sistema | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+
+### Pagtitipid sa Token
+
+| Pamamaraan | Tokens/yr | Cost/yr |
+|---|---|---|
+| I-paste ang buong context | 19.5M+ | Imposible (lumalagpas sa window) |
+| Pinaikli ng LLM | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + local embeddings | ~170K | **$0** |
+
+
+
+
+
+> Embedding model: `all-MiniLM-L6-v2` (lokal, libre, walang API key). Kumpletong mga ulat: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). Paghambing sa kompetisyon: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) na sumasaklaw sa agentmemory laban sa mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**I-reproduce nang lokal:** [`eval/README.md`](../eval/README.md), isang adapter-pluggable harness para sa LongMemEval `_s` (public 500-Q) + `coding-agent-life-v1` (in-house na 15-session corpus). Nag-iiskor ang mga grep / vector / agentmemory adapter nang tabi-tabi, NDJSON output, dumadapo ang mga published scorecard sa [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Umaangkop sa [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), at [Graphify](https://github.com/safishamsi/graphify).** Code-graph indexing, multi-agent build pipeline, at mas malawak na knowledge graph sa mga docs / PDF / imahe / video. Naaalala ng agentmemory ang ginawang trabaho; pinapaliwanag naman ng tatlong project na ito ang iba pang bahagi ng context layer. Mga recipe + question-routing table: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Built-in (CLAUDE.md)
+
+
+
Uri
+
Memory engine + MCP server
+
Memory layer API
+
Buong agent runtime
+
Personal AI
+
Memory API + app
+
Team memory hub (LLM proxy)
+
Vector memory (OSS)
+
Memory engine (Oracle DB)
+
Sistema ng memory
+
Static file
+
+
+
Retrieval R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Sariling ulat
+
PersonaMem 76% (sariling ulat)
+
~96.6% (sariling ulat)
+
94.4% (sariling ulat)
+
N/A
+
N/A (grep)
+
+
+
Auto-capture
+
12 hook (walang manu-manong pagsisikap)
+
Manual na add() call
+
Sariling pag-edit ng agent
+
Manual
+
API-side extraction
+
Proxy interception (pagpalit ng base-URL)
+
Manual
+
API extraction
+
Manual
+
Manual na pag-edit
+
+
+
Paghahanap
+
BM25 + Vector + Graph (RRF fusion)
+
Vector + Graph
+
Vector (archival)
+
Semantic
+
Vector + RAG
+
4 uri ng asset (Chat / Skill / Wiki / CodeGraph)
+
Vector lamang
+
Vector + semantic
+
Decay-weighted
+
Nilo-load ang lahat sa context
+
+
+
Multi-agent
+
MCP + REST + lease + signal
+
API (walang coordination)
+
Sa loob lamang ng Letta runtime
+
Hindi
+
Hindi
+
Mga tungkulin sa team + shared asset
+
Hindi
+
Scoped lamang
+
Shared sa multi-agent
+
Per-agent na file
+
+
+
Framework lock-in
+
Wala (kahit anong MCP client)
+
Wala
+
Mataas (kailangang gamitin ang Letta)
+
Standalone
+
Wala
+
Proxy sa harap ng bawat model call
+
Wala
+
Oracle Database
+
Wala
+
Per-agent na format
+
+
+
Panlabas na deps
+
Wala (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + vector DB
+
Marami
+
Managed cloud
+
Docker stack (Core + Hub + Proxy)
+
Vector store
+
Oracle AI Database
+
Wala
+
Wala
+
+
+
Memory lifecycle
+
4-tier consolidation + decay + auto-forget
+
Passive extraction
+
Pinamamahalaan ng agent
+
Manual
+
Auto-forget
+
Manual review; isinasagawa pa ang auto-routing
+
Wala
+
Hindi nakasaad
+
Decay + consolidation
+
Manual na pruning
+
+
+
Kahusayan ng Token
+
~1,900 tokens/session ($10/yr)
+
Depende sa integration
+
Core memory sa context
+
Depende
+
Cloud pricing
+
Hindi nakasaad
+
Walang token budget
+
LLM-backed (depende)
+
Depende
+
22K+ tokens sa 240 obs
+
+
+
Real-time viewer
+
Oo (port 3113)
+
Cloud dashboard
+
Cloud dashboard
+
Web UI
+
Cloud dashboard
+
Hub web UI
+
Hindi
+
Hindi
+
Hindi
+
Hindi
+
+
+
Self-hosted
+
Oo (default)
+
Opsyonal
+
Opsyonal
+
Oo
+
Hindi (cloud-only)
+
Oo (Docker)
+
Oo
+
Oo (Oracle DB)
+
Oo
+
Oo
+
+
+
+Tala sa benchmark: ang R@5 lamang ng agentmemory ang aming sariling nasukat na resulta (LongMemEval-S, reproducible mula sa benchmark/COMPARISON.md). Ang mga figure ng mem0 at Letta ay ang kanilang mga pinublikang numero sa LoCoMo (ibang dataset); ang mga figure ng MemPalace, supermemory, TencentDB (PersonaMem), at oracleagentmemory ay mga claim na self-reported ng vendor na hindi namin independent na-reproduce (ang run ng oracleagentmemory ay gumamit ng GPT-5.5 laban sa isang Oracle AI Database). Ipinapakita nang tabi-tabi para sa ballpark estimate lamang, hindi isang head-to-head sa parehong data. Ang bilang ng star ay tinatantya at nagbabago sa paglipas ng panahon.
+
+**Mga bagong entrant** na dapat malaman, inihambing nang detalyado sa [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Sistema | ⭐ | Anggulo |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporal knowledge graph; ang pinakamalakas na pinublikang resulta sa temporal-query (LongMemEval 63.8%), pero bumubuo ang graph nang asynchronous kaya maaaring mahuli ang mga bagong fact |
+| Cognee | 30K | Document-to-knowledge-graph ingestion, Python lamang, ginawa para sa structured entity extraction sa halip na session capture |
+
+Walang isa man sa mga ito ang gumagawa ng auto-capture mula sa coding-agent hooks, nag-ship ng local-first viewer, o tumatakbo nang keyless — ang kombinasyong ito ang pinagbatayan ng agentmemory.
+
+---
+
+
+
+Compatibility: tinatarget ng release na ito ang `iii-sdk` 0.22.1 at nagpipin sa iii-engine v0.22.1.
+
+### Subukan sa 30 Segundo
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+Nag-seed ang `demo` ng 3 makatotohanang session (JWT auth, N+1 query fix, rate limiting) at pinapatakbo ang mga search laban dito. Pinapatay ng keyless install ang vectors, kaya dapat tumama ang mga `mem::search` keyword query gamit ang BM25 habang puwedeng magbalik ng zero ang `database performance optimization`. Maaari pang ibalik ng `smart-search` ang structural graph matches kapag umiiral ang graph data. Para mahanap ng semantic query ang N+1 fix gamit ang vectors, i-set ang `EMBEDDING_PROVIDER=local`, i-restart, at hintaying matapos ang unang pag-download ng model.
+
+Buksan ang `http://localhost:3113` para panoorin ang live na pagbuo ng memory.
+
+### I-validate ang Bagong Install at ang Persistence ng Restart
+
+Habang tumatakbo ang server, patunayan ang REST, health, ang viewer, at ang status ng iii-backed runtime:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Isinasaalang-alang ng startup ready panel ang lahat ng apat na port: REST/MCP HTTP sa 3111, iii streams sa 3112, ang viewer sa 3113, at ang iii worker WebSocket sa 49134. Kinukumpirma ng `status` ang health ng agentmemory at ang aktibong provider/embedding mode. I-save ang isang probe at kumpirmahin na searchable ito:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Pagkatapos, patakbuhin ang `npx -y @agentmemory/agentmemory@latest stop`, simulan ulit ang standard na command sa Terminal 1, hintayin ang `/agentmemory/livez`, at ulitin ang search. Dapat pa ring ibalik ang probe. Kung pumili ka ng custom na `--data-dir`, ipasa ang parehong directory sa restart.
+
+### Mga Pang-araw-araw na Command
+
+Ang install at setup ay nasa [I-install](#install) sa itaas (gagabayan ka ng unang pagpapatakbo). Sa pang-araw-araw:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Replay ng Session
+
+Replayable ang bawat session na itinatala ng agentmemory. Buksan ang viewer, piliin ang tab na **Replay**, at mag-scrub sa timeline: ang mga prompt, tool call, tool result, at response ay nag-render bilang hiwalay na event na may play/pause, speed control (0.5x hanggang 4x), at keyboard shortcut (space para i-toggle, arrow para mag-step).
+
+Para dalhin ang mga mas lumang Claude Code JSONL transcript:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Lumalabas ang mga imported session sa Replay picker kasama ang mga native. Sa ilalim ng hood, dumadaan ang bawat entry sa `mem::replay::load`, `mem::replay::sessions`, at `mem::replay::import-jsonl` iii functions, walang side-channel server. Ang bawat imported transcript ay na-index para sa search, tinatakan ng origin channel na `import`, at hinuhukay para sa isang session crystal at mga lesson.
+
+> **Paalala kung aasa ka sa `import-jsonl` bilang pangunahing capture path:** Awtomatikong binubura ng `cleanupPeriodDays` ng Claude Code (sa `~/.claude/settings.json`, default na **30**) ang mga JSONL transcript na mas matanda sa window na iyon mula sa `~/.claude/projects/`. Kung mag-install ka ng bagong agentmemory sa isang Claude Code history na may edad na ilang buwan, wala na ang anumang mas matanda sa 30 araw bago pa man ang unang import. Patakbuhin ang `import-jsonl` sa isang cron, itaas ang `cleanupPeriodDays` sa mas mataas, o i-wire ang auto-capture hooks (ang default na plugin install path) para makarating sa agentmemory ang bawat turn habang live ang session at hindi na mahalaga ang JSONL cleanup.
+
+### Upgrade / Maintenance
+
+Gamitin ang maintenance command kapag sinasadya mong i-update ang iyong local runtime:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Babala: binabago ng command na ito ang kasalukuyang workspace/runtime. Maaari nitong i-update ang mga JavaScript dependency at kunin ang pinned na `iiidev/iii:0.22.1` Docker image. Hinding-hindi ito mag-install ng unpinned o mas bagong iii engine.
+
+Nasa `src/cli.ts` ang mga detalye ng implementation (tingnan ang `runUpgrade` sa paligid ng `src/cli.ts:544-595` na region).
+
+### Claude Code (isang block, i-paste ito)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code nang walang plugin install (MCP-standalone path)
+
+Kung i-wire mo ang MCP server ng agentmemory gamit ang `~/.claude.json` nang direkta sa halip na gamitin ang `/plugin install`, hindi kailanman nireresolba ng Claude Code ang `${CLAUDE_PLUGIN_ROOT}` at kailangan mong ituro ang hook scripts sa absolute paths sa `~/.claude/settings.json`. Karaniwang naka-embed sa mga path na ito ang bersyon ng agentmemory (hal. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), kaya tahimik na masisira ng susunod na upgrade ang bawat hook.
+
+Workaround:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Pinagsasama nito ang parehong hook commands sa `~/.claude/settings.json` gamit ang absolute paths na nireresolba sa bundled `plugin/` directory ng kasalukuyang naka-install na `@agentmemory/agentmemory` package. Patakbuhin ulit ang command pagkatapos i-upgrade ang agentmemory para i-refresh ang mga path. Napapanatili ang mga entry ng user sa parehong file; ang mga nakaraang entry ng agentmemory lamang ang napapalitan. Ang paggamit ng `/plugin install` path ay nananatiling inirerekomendang paraan.
+Para sa remote o protected deployment, patakbuhin ang Claude Code na naka-set ang `AGENTMEMORY_URL` at `AGENTMEMORY_SECRET`. Ipinapasa ng plugin ang dalawang value papunta sa bundled MCP server nito; kapag walang laman ang `AGENTMEMORY_URL`, gumagamit ang MCP shim ng `http://localhost:3111`.
+
+### Codex CLI (Codex plugin platform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Ang Codex plugin ay nag-ship mula sa parehong `plugin/` directory ng Claude Code plugin. Irehistro nito ang:
+
+- Isang bundled stdio MCP bridge sa tumatakbong daemon, walang npm download o fallback store. Tingnan ang [local Codex guide](../docs/plugins/codex-local.md) para subukan ang isang unreleased build.
+- 6 lifecycle hook: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 invocable na skill: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, kasama ang 8 reference skill na nilo-load ng agent kapag kailangan (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, at ang skill-authoring guide)
+
+Itinuturok ng hook engine ng Codex ang `CLAUDE_PLUGIN_ROOT` sa mga hook subprocess (ayon sa [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), kaya gumagana ang parehong hook script sa dalawang host nang walang duplication. Ang mga event na Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure ay Claude-Code-only lamang at hindi nirerehistro para sa Codex.
+
+#### Trust at compatibility ng Codex hook
+
+Na-verify ang native plugin hook dispatch gamit ang Codex CLI 0.150.1. I-trust ang plugin hooks bago asahan ang capture. Ang behavior ng Desktop ay depende sa bundled runtime nito; i-check ang `/hooks` at kumpirmahin ang isang na-capture na event bago paganahin ang isang workaround.
+
+Kapag kailangan ng host mo ang global hooks, i-mirror ang mga command sa `~/.codex/hooks.json`. Kapag naka-wire na ang MCP, kailangan ng kasalukuyang connector ang `--force` para maabot ang hook installation:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Pinagsasama nito ang global hooks at isinusulat ulit ang agentmemory MCP entry, habang napapanatili ang mga entry na walang kaugnayan. Suriin ang anumang custom na agentmemory endpoint settings mo bago gamitin ang `--force`. Patakbuhin ulit pagkatapos i-upgrade para i-refresh ang mga script path. Paganahin ang isa sa dalawa: native plugin hooks o global copies, para iwasan ang duplicate capture.
+
+### GitHub Copilot CLI
+
+Para sa VS Code agent mode, gamitin ang [Copilot MCP at automatic-capture guide](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Hindi i-configure ng CLI connector na ito ang VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory` sa `~/.copilot/mcp-config.json` (o `$COPILOT_HOME/mcp-config.json` kapag naka-set ang `COPILOT_HOME`) at pinapanatili ang mga umiiral na server. Sa native Windows, ito lamang ang awtomatikong `connect` adapter; i-configure nang manu-mano ang lahat ng iba pang native Windows agent. Suportado lamang ang WSL `connect` kapag naka-install din ang target agent sa parehong WSL environment. Kukunin ng Copilot ang MCP server sa susunod na launch o pagkatapos ng `/mcp`. I-install din ang plugin kapag gusto mo ang buong hook/skill na karanasan.
+
+
+OpenClaw (i-paste ang prompt na ito)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Kumpletong gabay: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (i-paste ang prompt na ito)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Kumpletong gabay: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Iba Pang Agent
+
+Simulan ang memory server: `npx -y @agentmemory/agentmemory@latest`
+
+#### Native na skill gamit ang `npx skills add` (50+ agent)
+
+Nag-ship ang agentmemory ng 17 skill sa Claude-Code-style na `/SKILL.md` format: 9 invocable na action skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) at 8 reference skill na nilo-load ng agent kapag kailangan (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). May dala ang mga reference skill na data table na nabuo mula sa source, kaya hindi ito kailanman nadrift. Ang [`skills`](https://npmjs.com/package/skills) CLI ng vercel-labs ay awtomatikong nag-install nito sa native skill directory ng tumatawag na agent sa 50+ agent (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, at iba pa):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Ito ay **komplementaryo** sa `agentmemory connect `:
+
+- Isusulat ng `agentmemory connect ` ang MCP server config para magamit ang mga tool.
+- I-install ng `npx skills add rohitg00/agentmemory` ang mga skill para malaman ng agent kung kailan ito tatawagin.
+
+Para sa ilang agent na hindi pa saklaw ng skills CLI (Zed v1.3.x pababa), ilagay mo mismo ang 17 SKILL.md file sa ilalim ng native skill directory ng agent; gumagana ang parehong format kahit saan.
+
+#### Standard na MCP Block
+
+Ang entry ng agentmemory ay ang **parehong MCP server block** sa bawat host na gumagamit ng `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**I-merge ang entry na ito sa umiiral na `mcpServers` object** sa config file ng host; huwag palitan ang file. Kung may iba na ang file na mga server, idagdag ang `agentmemory` sa tabi nila bilang isa pang key sa loob ng `mcpServers`. Kung wala talaga ang `mcpServers`, i-paste ang block sa loob ng `{ "mcpServers": { ... } }`. Minana ng mga `${VAR}` placeholder ang `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` mula sa shell sa oras ng paglunsad ng MCP server; nagpapasa ng walang-lamang string ang mga unset var at babalik ang shim sa `http://localhost:3111`. Sapat ang isang wired na entry para sa local at remote (k8s / reverse-proxied) deployment.
+
+| Agent | Config file | Mga Tala |
+|---|---|---|
+| **Cursor (MCP lamang)** | `~/.cursor/mcp.json` | I-merge sa `mcpServers`, o `agentmemory connect cursor`. May one-click deeplink din sa website. |
+| **Cursor (buong plugin)** | `.cursor-plugin/` | Listing sa Cursor Marketplace (nasa review ang submission) o Cursor Settings → Plugins → local checkout. Nirerehistro ang 7 auto-capture hook (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + ang MCP server, na pinamamahalaan ang `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` sa plugin dashboard ng Cursor. Gumagana sa Cursor IDE at `cursor-agent` CLI; ang mga print-mode prompt ng CLI ay binackfill mula sa session transcript sa katapusan ng session. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | I-merge sa `mcpServers`. I-restart ang Claude Desktop pagkatapos i-edit. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Parehong `mcpServers` block. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | Pinagsasama ng `agentmemory connect devin` ang MCP entry; idinadagdag ng `--with-hooks` ang anim na native na auto-capture hook (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) gamit ang lowercase na tool matcher ng Devin. Patunayan gamit ang `devin mcp list` at `/hooks` sa loob ng devin. |
+| **Devin CLI (buong plugin)** | `plugin/.devin-plugin/` | Nirerehistro ng `devin plugins install ./plugin` mula sa isang checkout ang lahat ng 17 skill bilang `/agentmemory:` slash command kasama ang MCP server. Hindi kayang paandarin ng Devin plugin hooks ang `SessionStart`/`SessionEnd`, kaya ipares ito sa `connect devin --with-hooks` para sa buong session capture. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Magdagdag ng custom na MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` na itinuturo sa isang network-reachable na agentmemory deployment kasama ang `AGENTMEMORY_SECRET` (hindi maaabot ng cloud session ang localhost — tingnan ang [`deploy/`](../deploy/)). Itago ang secret sa Devin Secrets, pagkatapos gamitin ang "Test listing tools" para patunayan na lumalabas ang lahat ng 54 tool. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (awtomatikong nag-merge). |
+| **GitHub Copilot CLI (MCP lamang)** | `~/.copilot/mcp-config.json` | Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory`; kukunin ito ng Copilot sa susunod na launch o `/mcp`. |
+| **GitHub Copilot CLI (buong plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` para sa plugin mula sa GitHub subdir. |
+| **OpenClaw** | OpenClaw MCP config | Parehong `mcpServers` block. Mas malalim: angkin ng `openclaw plugins install ./integrations/openclaw` ang memory slot ng OpenClaw (awtomatikong lilipat mula sa `memory-core`); i-set ang `plugins.entries.agentmemory.hooks.allowConversationAccess=true` o tahimik na haharangin ang turn capture. Tingnan ang [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (MCP lamang)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, o idagdag ang `[mcp_servers.agentmemory]` nang manu-mano. |
+| **Codex CLI (buong plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` pagkatapos `codex plugin add agentmemory@agentmemory`. Nirerehistro ang MCP + 6 lifecycle hook + 17 skill. I-trust ang hooks at i-verify ang capture sa host mo; tingnan ang [Codex setup at validation](../docs/plugins/codex-local.md). |
+| **OpenCode (MCP lamang)** | `opencode.json` | Ibang shape: top-level na `mcp` key, command bilang array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (buong plugin)** | `plugin/opencode/` | 22 auto-capture hook na sumasaklaw sa session lifecycle, messages, tools, errors. Per-session ang project attribution, kaya ang isang OpenCode process na saklaw ang ilang repository ay nagtatala ng bawat session sa ilalim ng sarili nitong project. Dalawang slash command (`/recall`, `/remember`). Kopyahin ang `plugin/opencode/` sa iyong OpenCode workspace at idagdag ang plugin entry sa `opencode.json`. Tingnan ang [`plugin/opencode/README.md`](../plugin/opencode/README.md) para sa buong hook table + gap analysis. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | Ini-install ng `agentmemory connect pi` ang bundled extension sa auto-discovery directory ng pi (recall sa agent start, capture sa agent end, mga tool na `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). Kukunin ito ng `/reload` sa isang tumatakbong pi. [`integrations/pi`](../integrations/pi/) ay isa rin pi package (`pi install ./integrations/pi` mula sa isang checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | Ang `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ay magbibigay ng 6-hook na memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block). Patunayan gamit ang `hermes plugins doctor` at `hermes memory status`. Tingnan ang [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | Isinusulat ng `agentmemory connect qwen` ang standard na `mcpServers` block. Field-compatible ang hook payload sa Claude Code, kaya gumagana ang umiiral na 12-hook scripts nang walang pagbabago; i-wire ito gamit ang `hooks` section sa parehong `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | Ini-install ng `agentmemory connect antigravity --with-hooks` ang MCP at capture hooks sa shared customization directory. Tingnan ang [setup at limitasyon ng Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | Ginagamit ng `agentmemory connect antigravity-cli --with-hooks` ang parehong MCP at hook configuration ng kasalukuyang mga bersyon ng IDE. Dapat i-refresh ng mga umiiral na installation gamit ang `--force`; tingnan ang [upgrade notes](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | Isinusulat ng `agentmemory connect kiro` ang user-level config. Ang workspace override ay sa `.kiro/settings/mcp.json`, katabi ng iyong code. |
+| **Warp** | `~/.warp/.mcp.json` | Isinusulat ng `agentmemory connect warp` ang standard na `mcpServers` block. Awtomatikong nadidiskubre din ng Warp ang mga skill mula sa `.claude/skills/`; kapag naka-install na ang Claude Code plugin, lumalabas nang native ang 8 agentmemory skill (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) sa slash-command palette ng Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | Isinusulat ng `agentmemory connect cline` ang standard na `mcpServers` block. Para sa VS Code extension user: i-paste ang parehong block sa Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferred) o `config.json` (legacy) | Gumagawa ang `agentmemory connect continue` ng `config.yaml` mula sa simula kapag walang alinman, o binabago ang umiiral na `config.json`. **Kung may `config.yaml` ka na** ipi-print ng adapter ang eksaktong block na i-paste sa ilalim ng `mcpServers:`; hindi nito tahimik na isusulat ulit ang yaml mo dahil ang pagpapanatili ng comments at anchors nang ligtas ay nangangailangan ng YAML parser na hindi dala ng package. Gumagamit ang Continue ng array form (hindi object) para sa `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | Isinusulat ng `agentmemory connect zed` sa ilalim ng `context_servers` (ang key ng Zed, HINDI `mcpServers`). Maaaring i-wire ang remote MCP server gamit ang `{"url": "..."}` sa halip. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | Isinusulat ng `agentmemory connect droid` ang standard na `mcpServers` block. Ang project-scoped override ay sa `/.factory/mcp.json`. Ipasa ang `--with-hooks` para sa native auto-capture. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Idinadagdag ng `agentmemory connect dsh` ang isang `@deepseek-ai/dsh-mcp-client` row sa home-level patch layer na nilo-load ng bawat Harness profile; nagrerehistro ang mga tool bilang `mcp__agentmemory__*`. Ipasa ang `--with-hooks` para i-wire din ang auto-capture: tumatakbo ang bundled Claude Code hook scripts sa first-party na `@deepseek-ai/dsh-hooks-claude-code` bridge ng Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) gamit ang manifest na isinulat sa `$DSH_HOME/agentmemory.hooks.json`. Default sa `~/.dsh` kapag walang `DSH_HOME`. |
+| **Goose** | Goose MCP settings UI | Parehong `mcpServers` block; gamitin ang `goose configure` → Add Extension → MCP. Suportado ang direktang YAML edit sa `~/.config/goose/config.yaml` pero ang schema ay gumagamit ng `extensions:` + `cmd` (hindi `mcpServers:` + `command`). |
+| **Aider** | n/a | Kausapin ang REST API nang direkta: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Anumang agent (32+)** | n/a | Awtomatikong tinutuklas at pinagsasama ng `npx skillkit install agentmemory` ang host. |
+
+**Mga sandboxed MCP client** (Flatpak / Snap / restrictive container) na hindi maabot ang `localhost` ng host: i-set din ang `"AGENTMEMORY_FORCE_PROXY": "1"` sa `env` block, at ituro ang `AGENTMEMORY_URL` sa isang route na talagang maabot ng sandbox (hal. ang LAN IP mo).
+
+### Programmatic access (Python / Rust / Node)
+
+Irehistro ng agentmemory ang mga core operation nito bilang iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Maaari silang tawagin nang direkta ng anumang wika na may iii SDK sa `ws://localhost:49134`, walang kailangang hiwalay na REST client bawat wika.
+
+```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"},
+})
+```
+
+Halimbawang gawa: [`examples/python/`](../examples/python/) (quickstart + observation/recall flow). Available pa rin ang REST sa `:3111` para sa mga host na walang iii runtime.
+
+### Mula sa Source
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Sinisimulan nito ang agentmemory gamit ang lokal na `iii-engine` kung naka-install na ang pinned binary, o gumagamit ng Docker Compose kapag ito ang pinili. Nagbibind ang REST, streams, at ang viewer sa `127.0.0.1` bilang default. Ang automatic na binary path sa macOS/Linux ay nangangailangan ng `curl`, isang POSIX `sh`, at `tar`.
+
+I-install nang manu-mano ang `iii-engine`. **Nagpipin ang agentmemory sa kasalukuyan ang `iii-engine` sa `v0.22.1`**, kaparehong release ng dependency nitong `iii-sdk`; kinakausap ng worker ang wire protocol ng engine na iyon, at ni-reorganize ng 0.20.0 ang SDK surface, kaya magkasamang kumikilos ang dalawa sa mga release ng agentmemory. I-override gamit ang `AGENTMEMORY_III_VERSION=` kung may sariling engine ka at alam mong tugma ito.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** palitan ang `aarch64-apple-darwin` ng `x86_64-apple-darwin`
+- **Linux x64:** palitan ng `x86_64-unknown-linux-gnu`
+- **Linux arm64:** palitan ng `aarch64-unknown-linux-gnu`
+- **Windows:** i-download ang `iii-x86_64-pc-windows-msvc.zip` mula sa [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) at i-extract ang `iii.exe` sa `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+May kaparehong `.sha256` file ang bawat archive sa release page; kapag pinalitan mo ang platform, gamitin ang hash ng file na iyon sa check sa itaas (sa Windows: `Get-FileHash`). Pinned ng automatic installer sa `npx @agentmemory/agentmemory` ang mga hash na ito at tatanggihan ang anumang archive na hindi tumugma.
+
+O gamitin ang Docker (ang bundled na `docker-compose.yml` ay kinukuha ang `iiidev/iii:0.22.1`). Kumpletong docs: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+Tumatakbo ang agentmemory sa Windows 10/11, pero hindi sapat ang Node.js package lamang; kailangan mo rin ang pinned iii-engine v0.22.1 runtime bilang background process. Hindi awtomatikong nireextract ng CLI ang Windows ZIP, kaya ang mga native Windows user ay dapat i-install nang manu-mano ang `iii.exe`, gamitin ang WSL2, o piliin ang Docker Desktop.
+
+Sinusuportahan lamang ng native Windows automated MCP wiring ang `agentmemory connect copilot-cli`. Para sa Claude Code, Codex, Cursor, at lahat ng iba pang native Windows agent, kopyahin ang manual na MCP block mula sa [Iba Pang Agent](#other-agents) papunta sa Windows config ng agent na iyon. Angkop lamang ang pagpapatakbo ng `connect` sa WSL kapag naka-install din ang target agent sa parehong WSL environment; hindi nito ina-edit ang config ng isang Windows-host agent.
+
+**Opsyon A: prebuilt na Windows binary (inirerekomenda)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opsyon B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Opsyon C: standalone MCP lamang (walang engine).** Kung kailangan mo lamang ng mga MCP tool para sa iyong agent at hindi kailangan ang REST API, viewer, o cron job, laktawan nang buo ang engine:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Diagnostics para sa Windows:** kung nabigo ang `npx -y @agentmemory/agentmemory@latest`, patakbuhin ulit ito gamit ang `--verbose` para makita ang aktwal na engine stderr. Mga karaniwang mode ng pagkabigo:
+
+| Sintoma | Fix |
+|---|---|
+| `The engine process started but the REST API never responded.` | Kumpirmahin na libre ang lahat ng apat na derived port, i-verify na buhay pa ang pinned na `iii.exe`, pagkatapos patakbuhin ulit gamit ang `--verbose` at suriin ang nakuhang engine stderr |
+| `Could not start iii-engine` | Walang naka-install na `iii.exe` o Docker. Tingnan ang Opsyon A o B sa itaas |
+| Port conflict | `netstat -ano \| findstr :3111` para makita ang nakabind, pagkatapos patayin ito o gamitin ang `--port ` |
+| Nalaktawan ang Docker fallback kahit naka-install ang Docker | Siguraduhing talagang tumatakbo ang Docker Desktop (icon sa system tray) |
+
+> Tala: ang **engine** ng iii ay isang prebuilt binary, hindi isang cargo crate, kaya huwag subukang `cargo install` ito. (Pinublika ang mga **SDK** ng iii sa crates.io, npm, at PyPI, pero hindi ito kailangan ng agentmemory.) Lahat ng supportadong paraan ng pag-install ng engine ay pinned sa v0.22.1: ang prebuilt binary sa itaas, ang macOS/Linux auto-install path ng agentmemory (kinakailangan ang `curl`, POSIX `sh`, at `tar`), at ang Docker image na `iiidev/iii:0.22.1`. Ang bare upstream na `install.sh | sh` ay nag-install ng pinakabagong engine, na hindi suportado ng agentmemory. Gamitin ang `npx -y @agentmemory/agentmemory@latest`; sa macOS/Linux kinukuha nito ang pinned engine papunta sa `~/.agentmemory/bin`.
+
+---
+
+
Pag-deploy
+
+Mga one-click template para sa managed host. Bawat isa ay nag-ship ng
+self-contained na Dockerfile na kumukuha ng `@agentmemory/agentmemory` mula sa
+npm at kinokopya ang iii engine binary mula sa opisyal na `iiidev/iii` Docker
+Hub image; walang kailangang pre-built na agentmemory image. Nagbibind ang
+persistent storage sa `/data`; ang first-boot entrypoint ay nag-o-override sa
+npm-bundled na iii config (na nagbibind sa `127.0.0.1`) ng isang
+deploy-tuned na config na nagbibind sa `0.0.0.0` at gumagamit ng absolute na
+`/data` path, bumubuo ng HMAC secret, pagkatapos nagbababa ng privileges mula
+sa `root` papuntang `node` gamit ang `gosu` bago i-exec ang agentmemory CLI.
+
+
+
+
+
+
+Kinakailangan ng one-click deploy button ng Render ang `render.yaml` sa repository root, na sinadya naming panatilihing malinis. Gamitin ang Render Blueprint flow na nakadokumento sa [`deploy/render/`](.././deploy/render/README.md) para ituro nang manu-mano ang in-repo blueprint.
+
+Nasa [`deploy/`](.././deploy/README.md) ang kumpletong detalye ng setup (HMAC capture, viewer SSH tunnel, rotation, backup, cost floor):
+
+- [`deploy/fly`](.././deploy/fly/README.md): isang machine na may
+ `auto_stop_machines = "stop"`; pinakamura kapag idle.
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby plan na flat fee,
+ volume sa dashboard.
+- [`deploy/render`](.././deploy/render/README.md): Blueprint flow,
+ awtomatikong disk snapshot sa mga paid plan.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted sa sariling
+ VPS mo gamit ang [Coolify](https://coolify.io/self-hosted); parehong Docker
+ Compose stack, ikaw ang may-ari ng host at ng data.
+
+Port `3111` lamang ang pinublish. Nananatiling bound sa loopback sa loob ng
+container ang viewer sa `3113`; nakadokumento sa README ng bawat template ang
+SSH-tunnel pattern para maabot ito.
+
+---
+
+
+
+
+Nakakalimutan ng bawat coding agent ang lahat kapag natapos ang session, at ang bawat bagong session ay nagsisimula sa muling pagpapaliwanag mo ng iyong stack. Tumatakbo ang agentmemory sa background at aalisin ang hakbang na ito.
+
+```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.
+```
+
+### Kumpara sa Built-in na Memory ng Agent
+
+Nag-ship ang bawat AI coding agent na may built-in memory: may `MEMORY.md` ang Claude Code, may notepad ang Cursor, may memory bank ang Cline. Gumagana ang mga ito gaya ng sticky note. Ang agentmemory ang searchable database sa likod ng mga sticky note.
+
+| | Built-in (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Sukat | 200-linyang cap | Walang Limitasyon |
+| Paghahanap | Nilo-load ang lahat sa context | BM25 + vector + graph (top-K lamang) |
+| Gastos sa Token | 22K+ sa 240 obserbasyon | ~1,900 token (92% mas kaunti) |
+| Cross-agent | Per-agent na file | MCP + REST (kahit anong agent) |
+| Koordinasyon | Wala | Lease, signal, action, routine |
+| Observability | Basahin ang mga file nang manu-mano | Real-time viewer sa :3113 |
+
+---
+
+
+
+### Memory Pipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-Tier Memory Consolidation
+
+Hinubog batay sa paano pinoproseso ng utak ng tao ang memory, kasama ang sleep consolidation.
+
+| Tier | Ano | Analohiya |
+|------|------|---------|
+| **Working** | Raw na obserbasyon mula sa paggamit ng tool | Panandaliang memory |
+| **Episodic** | Pinaikling buod ng session | "Ano ang Nangyari" |
+| **Semantic** | Mga nakuhang fact at pattern | "Ano ang Alam Ko" |
+| **Procedural** | Mga workflow at decision pattern | "Paano Ito Gawin" |
+
+Nauupos ang mga memory sa paglipas ng panahon (Ebbinghaus curve). Lumalakas ang mga madalas i-access na memory. Awtomatikong naaalis ang mga stale na memory. Nadidiskubre at naresolba ang mga kontradiksyon.
+
+### Ano ang Nakukuha
+
+| Hook | Nakukuha |
+|------|----------|
+| `SessionStart` | Project path, session ID |
+| `UserPromptSubmit` | User prompt (privacy-filtered) |
+| `PreToolUse` | File access pattern + enriched context |
+| `PostToolUse` | Tool name, input, output |
+| `PostToolUseFailure` | Error context |
+| `PreCompact` | Itinuturok ulit ang memory bago ang compaction |
+| `SubagentStart/Stop` | Sub-agent lifecycle |
+| `Stop` | Buod sa katapusan ng session |
+| `SessionEnd` | Marker ng kumpletong session |
+
+### Mga Pangunahing Kakayahan
+
+| Kakayahan | Paglalarawan |
+|---|---|
+| **Awtomatikong capture** | Naitatala ang bawat paggamit ng tool gamit ang hooks, walang manu-manong pagsisikap |
+| **Semantic search** | BM25 + vector + knowledge graph na may RRF fusion |
+| **Ebolusyon ng memory** | Versioning, supersession, relationship graph |
+| **Recall hygiene** | Umaalis sa search index ang mga superseded na bersyon ng memory; pinapanatili ng version chain sa KV ang buong history |
+| **Near-duplicate hint** | Nag-uulat ang mga save ng advisory na `similarTo` match kapag malapit na kahawig ng umiiral na memory ang bagong content |
+| **Per-agent scoping** | Dumadaan ang `agentId` sa save at recall sa REST, MCP, at ang search index, sa shared o isolated mode |
+| **Write-time provenance** | May dalang hindi-nababagong origin channel (user, agent, tool, import, o shared) ang bawat obserbasyon at memory, na tinatakan sa capture, save, at import |
+| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction |
+| **Privacy muna** | Tinatanggal ang mga API key, secret, `` tag bago ang storage |
+| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring |
+| **Claude bridge** | Bi-directional sync sa MEMORY.md |
+| **Knowledge graph** | Entity extraction + BFS traversal |
+| **Team memory** | Namespaced shared + private sa mga miyembro ng team |
+| **Citation provenance** | Subaybayan ang anumang memory pabalik sa source observation |
+| **Git snapshot** | I-version, i-rollback, at i-diff ang memory state |
+
+---
+
+
+
+Triple-stream retrieval na pinagsasama ang tatlong signal:
+
+| Stream | Ano ang Ginagawa Nito | Kailan |
+|---|---|---|
+| **BM25** | Stemmed keyword matching na may synonym expansion | Palaging naka-on |
+| **Vector** | Cosine similarity sa dense embeddings | Naka-configure ang embedding provider |
+| **Graph** | Knowledge graph traversal gamit ang entity matching | May nadetektang entity sa query |
+
+Pinagsasama gamit ang Reciprocal Rank Fusion (RRF, k=60) at session-diversified (max 3 resulta kada session).
+
+Kapag napupuno ang isang vector index, ginagamit ng `mem::search` (sa likod ng `memory_recall`) ang hybrid na BM25 + vector ranker. Kapag walang embeddings, ginagamit nito ang BM25. Maaari pang pagsamahin ng `smart-search` ang structural graph matches kapag umiiral ang graph data, kasama na sa keyless mode. Tumatakbo ang lesson recall sa isang dedikadong in-memory BM25 index sa halip na i-scan ang buong corpus kada query. Hindi kasama sa bawat recall path ang mga superseded na bersyon ng memory; pinapanatili ng version chain ang kanilang history.
+
+Nakaligtas ang mga vector sa isang crash o force-kill. Nasa-save ang vector index sa mga bucket sa pinakamadalas na bawat `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minuto). Bawat vector na idinagdag o inalis sa gitna ay agad na isinusulat din sa isang maliit na pending log sa state store, at ni-replay ito ng susunod na start nang hindi tinawag ang embedding provider. Ang bawat matagumpay na save ay nagwawalang-laman sa log. Ang mga documento na wala pa ring vector pagkatapos ng replay ay re-embedded sa background sa mga batch ng `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) hanggang maubos ang lahat, at ang backfill na natigil ay magpapatuloy sa susunod na start. Ipinapakita ng `/agentmemory/status` at ng viewer ang laki ng pending log at ang estado ng backfill. Walang isinusulat ang mga keyless install.
+
+Tinotokenize ng BM25 ang Griyego, Cyrillic, Hebreo, Arabic, at accented Latin nang out of the box. Para sa mga memory sa Chinese / Japanese / Korean, i-install ang opsyonal na segmenter (`npm install @node-rs/jieba tiny-segmenter`) para hatiin ang mga CJK run sa word-level token; kung wala ito, soft-falls ang agentmemory sa whole-run tokenization at nagprint ng one-time hint sa stderr.
+
+### Mga Embedding Provider
+
+Pinapatay ng keyless install ang vector embeddings: ginagamit ng `mem::search` ang BM25, habang maaari pang gamitin ng `smart-search` ang umiiral na structural graph data. Para opt in sa libreng on-device semantic embeddings, idagdag ito sa `~/.agentmemory/.env` at i-restart ang agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Kasama sa normal na npm install ang opsyonal na `@huggingface/transformers` runtime. Nag-download ang unang embedding request ng `Xenova/all-MiniLM-L6-v2`, kaya kailangan nito ng network access at maaaring tumagal; tumatakbo na on-device ang susunod na inference. Awtomatikong nadidiskubre ang mga remote provider mula sa kanilang keys maliban kung na-override ito ng `EMBEDDING_PROVIDER`.
+
+| Provider | Model | Gastos | Mga Tala |
+|---|---|---|---|
+| **Local (inirerekomendang opt-in)** | `all-MiniLM-L6-v2` | Libre | On-device pagkatapos ng unang pag-download ng model, +8pp recall kaysa sa BM25-only |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ wika, 768/1536/3072 dims (MRL), 2048-token input. Pumalit sa `text-embedding-004` ([deprecated, magsasara noong Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Pinakamataas na kalidad |
+| Voyage AI | `voyage-code-3` | Bayad | Na-optimize para sa code |
+| Cohere | `embed-english-v3.0` | Free trial | Pangkalahatang gamit |
+| OpenRouter | Kahit anong model | Depende | Multi-model proxy |
+
+---
+
+
+
+54 na tool, 6 na resource, 3 na prompt, at 17 na skill.
+
+> **MCP shim laban sa buong server:** ang pinublish na `@agentmemory/mcp` package ay isang manipis na shim. Ilalantad nito ang buong 54-tool surface **lamang kapag kaya nitong maabot ang isang tumatakbong agentmemory server** gamit ang `AGENTMEMORY_URL` (proxy mode). Kung walang maabot na server, babalik ang shim sa isang 7-tool na lokal na set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Ang `AGENTMEMORY_TOOLS=core|all` env var ay isang *server-side* na flag; walang epekto ang pag-set nito sa `env` block ng shim. Kung 7 tool lamang ang nakikita mo sa Cursor / OpenCode / Gemini CLI, simulan ang `npx -y @agentmemory/agentmemory@latest` (o ang Docker stack) at i-set ang `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 na Tool
+
+Tatlong tool surface, mula sa pinakamaliit hanggang pinakamalaki: binabawasan ng `AGENTMEMORY_TOOLS=core` ang visibility sa 8 mahahalagang tool (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); ang base set sa ibaba ay ang 14 foundational tool ng registry; ang default (`AGENTMEMORY_TOOLS=all`) ay ilalantad ang lahat ng 54.
+
+
+Base tool (14)
+
+| Tool | Paglalarawan |
+|------|-------------|
+| `memory_recall` | Hanapin ang nakaraang obserbasyon |
+| `memory_compress_file` | I-compress ang mga markdown file habang pinapanatili ang structure |
+| `memory_save` | I-save ang isang insight, desisyon, o pattern |
+| `memory_file_history` | Mga nakaraang obserbasyon tungkol sa partikular na file |
+| `memory_patterns` | Tuklasin ang mga umuulit na pattern |
+| `memory_sessions` | Ilista ang mga kamakailang session |
+| `memory_smart_search` | Hybrid semantic + keyword search |
+| `memory_vision_search` | Hanapin ang mga obserbasyon ng imahe |
+| `memory_timeline` | Obserbasyon ayon sa pagkakasunod-sunod ng oras |
+| `memory_profile` | Profile ng project (concept, file, pattern) |
+| `memory_export` | I-export ang lahat ng memory data |
+| `memory_relations` | Query ang relationship graph |
+| `memory_commit_lookup` | Mga session sa likod ng isang git commit |
+| `memory_commits` | Mga commit na naitala para sa isang session |
+
+
+
+
+Extended tool (54 lahat, ang default surface)
+
+| Tool | Paglalarawan |
+|------|-------------|
+| `memory_patterns` | Tuklasin ang mga umuulit na pattern |
+| `memory_timeline` | Obserbasyon ayon sa pagkakasunod-sunod ng oras |
+| `memory_relations` | Query ang relationship graph |
+| `memory_graph_query` | Knowledge graph traversal |
+| `memory_consolidate` | Patakbuhin ang 4-tier consolidation |
+| `memory_claude_bridge_sync` | I-sync sa MEMORY.md |
+| `memory_team_share` | Ibahagi sa mga miyembro ng team |
+| `memory_team_feed` | Mga kamakailang ibinahaging item |
+| `memory_audit` | Audit trail ng mga operation |
+| `memory_governance_delete` | Burahin na may audit trail |
+| `memory_snapshot_create` | Git-versioned na snapshot |
+| `memory_action_create` | Gumawa ng work item na may dependency |
+| `memory_action_update` | I-update ang status ng action |
+| `memory_frontier` | Mga unblocked na action na naayos ayon sa priority |
+| `memory_next` | Ang pinakamahalagang susunod na action |
+| `memory_lease` | Exclusive na action lease (multi-agent) |
+| `memory_routine_run` | I-instantiate ang mga workflow routine |
+| `memory_signal_send` | Pagmemensahe sa pagitan ng agent |
+| `memory_signal_read` | Basahin ang mga mensahe na may receipt |
+| `memory_checkpoint` | Panlabas na condition gate |
+| `memory_mesh_sync` | P2P sync sa pagitan ng instance |
+| `memory_sentinel_create` | Event-driven na watcher |
+| `memory_sentinel_trigger` | Patakbuhin ang mga sentinel mula sa labas |
+| `memory_sketch_create` | Ephemeral na action graph |
+| `memory_sketch_promote` | I-promote sa permanente |
+| `memory_crystallize` | I-compact ang mga action chain |
+| `memory_diagnose` | Health check |
+| `memory_heal` | Awtomatikong ayusin ang stuck na state |
+| `memory_facet_tag` | Dimension:value tag |
+| `memory_facet_query` | Query ayon sa facet tag |
+| `memory_verify` | Subaybayan ang provenance |
+
+
+
+### 6 Resource · 3 Prompt · 17 Skill
+
+| Type | Pangalan | Paglalarawan |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, bilang ng session, bilang ng memory |
+| Resource | `agentmemory://project/{name}/profile` | Per-project intelligence |
+| Resource | `agentmemory://project/{name}/recent` | Mga kamakailang obserbasyon para sa isang project |
+| Resource | `agentmemory://memories/latest` | Pinakabagong 10 aktibong memory |
+| Resource | `agentmemory://graph/stats` | Statistics ng knowledge graph |
+| Resource | `agentmemory://team/{id}/profile` | Shared na profile ng team |
+| Prompt | `recall_context` | Maghanap + ibalik ang mga context message |
+| Prompt | `session_handoff` | Handoff data sa pagitan ng agent |
+| Prompt | `detect_patterns` | Suriin ang mga umuulit na pattern |
+| Skill | `/recall` | Hanapin ang memory |
+| Skill | `/remember` | I-save sa long-term memory |
+| Skill | `/session-history` | Mga buod ng kamakailang session |
+| Skill | `/forget` | Burahin ang mga obserbasyon/session |
+
+Ipinapakita ng table ang apat na core skill. Ang buong set ay 9 invocable na skill kasama ang 8 reference skill; tingnan ang Native skills section sa itaas.
+
+### Standalone MCP
+
+Patakbuhin nang walang buong server, para sa kahit anong MCP client. Gumagana ang alinman sa mga ito:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+O idagdag sa MCP config ng iyong agent:
+
+Karamihan sa mga agent (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+I-merge ang entry ng `agentmemory` sa umiiral na `mcpServers` object ng host sa halip na palitan ang file. Para sa mga sandboxed client na hindi maabot ang `localhost` ng host, idagdag ang `"AGENTMEMORY_FORCE_PROXY": "1"` sa env block at i-set ang `AGENTMEMORY_URL` sa isang route na maaabot ng sandbox.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Kopyahin ang plugin file mula sa repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Awtomatikong nagsisimula sa port `3113`. Nag-load ang viewer ng isang snapshot kapag kumonekta ito (`GET /agentmemory/viewer/snapshot`) at pagkatapos ay ilalapat ang mga live stream event: lumalabas ang mga bagong memory, lesson, obserbasyon, audit entry, pagbabago sa graph, at health update nang walang polling o page reload. Ang iba lamang na request ay ang mga action na iyong kinliklik, ang mga "load more" page at search. Kapag nawala ang stream, ipinapakita ng viewer kung gaano na katanda ang mga numero nito, kumokonekta ulit nang may backoff at nireresync mula sa isang snapshot.
+
+- **12 tab sa apat na grupo** na may live count, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), keyboard shortcut at isang mobile menu.
+- **Memories:** server-side search, filter ayon sa project, agent, at type, isang detail panel na may version chain at word diff, provenance link, copy button para sa id, ang MCP call at isang curl command, edit (bagong bersyon), forget na may confirmation, bulk forget at JSON export.
+- **Sessions:** inline na observation timeline na may nababasang tool input at output, filter at paging, at ang mga memory at lesson na nabuo ng bawat session.
+- **Graph:** search, detalye ng node na may relation at source, isang legend na hindi umaasa sa kulay lamang, at zoom control.
+- **Health:** ang live na bersyon ng `GET /agentmemory/status`. May kasamang fix ang bawat problema, kasama ang state backend, index save state, progress ng graph provenance compaction, at isang consolidation explainer na may tunay na threshold.
+- Mga pahina ng **Audit, Activity, Profile, Replay, Lessons, Actions, at Crystals**, na bawat isa ay may empty state na nagsasabi kung ano ang section, bakit ito walang laman, at ang command na magpupuno nito, at isang `?` glossary tooltip sa bawat termino at numero.
+
+```bash
+open http://localhost:3113
+```
+
+Nagbibind ang viewer server sa `127.0.0.1` bilang default at idinadagdag nito ang server secret kapag ipinapasa ang mga request sa REST API, kaya walang kailangang i-setup. Sumusunod ang `/agentmemory/viewer` endpoint na naka-serve sa REST sa normal na bearer-token rules at nireredirect ang mga browser na walang token papunta sa viewer port. Gumagamit ang CSP headers ng per-response script nonce at pinapatay ang inline handler attributes (`script-src-attr 'none'`).
+
+---
+
+
+
+Ipinapakita ng viewer sa `:3113` ang **naalala** ng iyong agent. Ipinapakita ng [iii console](https://iii.dev/docs/console) ang **ginawa** ng iyong agent: bawat memory op bilang isang OpenTelemetry trace, bawat KV entry na maaaring i-edit, bawat function na maaaring i-invoke, bawat stream na maaaring tapp-in. Dalawang bintana sa parehong memory: isang product-shaped, isang engine-shaped.
+
+Panoorin ang pagputok ng isang `memory_smart_search` at tingnan ang BM25 scan → embedding lookup → RRF fusion → reranker bilang isang waterfall. I-edit ang isang stuck na consolidation timer sa KV browser. I-replay ang isang `PostToolUse` hook na may tinweak na payload. I-pin ang WebSocket stream at panoorin ang mga obserbasyon na dumarating nang live.
+
+Ibinibigay ito ng agentmemory nang libre dahil ang bawat function call at trigger ay dumadaan sa iii; walang custom, walang kailangang i-instrument.
+
+
+
+
+ Pahinang Workers: bawat kakonektang worker, kasama ang agentmemory mismo, na may PID, function count, runtime, at last-seen.
+
+
+**Naka-install na.** Nag-ship ang console kasama ang pinned na `iii` engine (0.22+); walang hiwalay na i-install. Nag-download ang unang launch ng console binary sa tabi ng engine.
+
+**Ilunsad kasabay ng agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Pinapatakbo nito ang `iii console` ng pinned engine laban sa mga port na nireresolba ng agentmemory (REST, streams, bridge) at ipinapakita ito sa isang port sa itaas ng viewer, `http://localhost:3114` bilang default. Pumipili ang `--console-port N` ng ibang port; pinipili ng `--port` at `--instance` ang instance ng agentmemory sa parehong paraan tulad nila para sa `stop`; ipinapasa ang anumang ibang flag, halimbawa ang `--enable-flow` para sa experimental na architecture-graph page.
+
+Ang parehong bagay nang manu-mano, kapaki-pakinabang kapag wala ang `agentmemory` sa PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Ang magagawa mo mula sa console:**
+
+| Pahina | Gamitin Ito Para |
+|------|-----------|
+| **Workers** | Makita ang bawat kakonektang worker at ang live metrics nito, kasama ang agentmemory worker mismo. |
+| **Functions** | I-invoke nang direkta ang alinman sa mga function ng agentmemory gamit ang isang JSON payload; kapaki-pakinabang para sa pag-test ng `memory.recall`, `memory.consolidate`, `graph.query` nang walang i-wire na client. |
+| **Triggers** | I-replay ang HTTP, cron, event, at state trigger: patakbuhin nang manu-mano ang consolidation cron, ulitin ang isang HTTP route, maglabas ng state change. |
+| **States** | KV browser na may full CRUD sa mga session, memory slot, lifecycle timer, at ang embeddings index; i-edit ang mga value sa lugar. |
+| **Streams** | Live na WebSocket monitor para sa memory writes, hook event, at observation update habang dumadaloy sa mga iii stream. |
+| **Queues** | Durable queue topic + dead-letter management. I-replay o i-drop ang mga nabigong embedding / compression job. |
+| **Traces** | OpenTelemetry waterfall / flame / service-breakdown view. I-filter ayon sa `trace_id` para makita kung aling mga function, DB call, at embedding request mismo ang nabuo ng isang `memory.search`. |
+| **Logs** | Structured OTEL log na na-filter at na-correlate sa trace/span ID. |
+| **Config** | Runtime configuration: makita mismo kung aling mga worker, provider, at port ang tinatakbo ng iyong engine. |
+| **Flow** | (Opsyonal, `--enable-flow`) Interactive na architecture graph ng bawat worker, trigger, at stream. |
+
+
+
+
+ Traces: waterfall / flame / service breakdown para sa bawat memory operation.
+
+
+**Naka-on na ang Traces:**
+
+Nag-ship ang `iii-config.yaml` na naka-enable na ang `iii-observability` worker (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs). Walang kailangang karagdagang config; sa sandaling magsimula ang agentmemory, nagpaparating ang bawat memory operation ng isang structured log na nababasa ng console, at isa sa sampung operation (`sampling_ratio: 0.1`) ang nagpaparating din ng trace span.
+
+Kung gusto mo nang mag-export papunta sa Jaeger/Honeycomb/Grafana Tempo, palitan ang `exporter: memory` ng `exporter: otlp` at i-set ang collector endpoint ayon sa observability docs ng iii.
+
+> **Paalala:** walang auth na ipinapatupad sa console mismo; panatilihin itong bound sa `127.0.0.1` (ang default) at huwag kailanman i-expose ito nang pampubliko.
+
+---
+
+
+
+Ang agentmemory ay **isa nang tumatakbong [iii](https://iii.dev) instance**. Tatlong primitive (worker, function, trigger) ang bumubuo sa runtime; nagmumula ang KV state, streams, at OTEL trace sa mga worker na iii-state, iii-stream, at iii-observability na kasama sa iii. Hindi ka nag-install ng Postgres, Redis, Express, pm2, o Prometheus, dahil pinapalitan ito ng iii.
+
+Ibig sabihin, isa pang command ang kailangan para palawakin ang agentmemory ng isang buong bagong kakayahan.
+
+### Palawakin ang agentmemory gamit ang Mas Maraming Worker
+
+Ang mga builtin na kailangan ng agentmemory ay nasa `iii-config.yaml` na at nag-boot kasama nito: `iii-state` (KV), `iii-queue` (durable retry para sa mga event subscriber), `iii-pubsub`, `iii-cron`, `iii-stream`, at `iii-observability` (OTEL trace, metrics at logs sa bawat function). Kahit ano pang mula sa [iii worker registry](https://workers.iii.dev) ay maaaring i-plug sa parehong engine: kopyahin ang `iii-config.yaml` papunta sa `~/.agentmemory/iii-config.yaml` (mas pinipili ng CLI ang file na ito kaysa sa bundled at ire-render pa rin nito ang mga port at data path dito), idagdag ang entry, i-install nang isang pagkakataon ang worker runtime gamit ang `~/.agentmemory/bin/iii update worker`, at i-restart ang agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Ano ang Makukuha Mo Kasama ang agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | SQL-backed na state adapter kapag nalampasan mo na ang in-memory KV default |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Tumatakbo sa loob ng isang throwaway VM, hindi sa shell mo, ang code na galing sa `memory_recall` |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Magtayo ng karagdagang MCP server sa tabi ng agentmemory's, ibahagi ang parehong engine |
+
+Sa engine 0.22.x, panatilihin ang mga pangalang may `iii-` prefix para sa mga builtin sa itaas; ang mga unprefixed na entry na `http`, `state`, `queue`, `pubsub` at `cron` ay ang standalone na registry worker na lilipatan ng agentmemory sa 0.23 migration.
+
+Kumpletong registry: [workers.iii.dev](https://workers.iii.dev). Bumubuo ang bawat worker dito gamit ang parehong primitive na ginagamit ng agentmemory, at ang agentmemory na nasa'yo na ay isa sa mga ito.
+
+### Engine Config at Bind Address
+
+Binabasa ng `agentmemory start` ang engine config mula sa unang file na umiiral: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` sa kasalukuyang directory, `~/.agentmemory/iii-config.yaml`, pagkatapos ang bundled na `iii-config.yaml`. Sa bawat start, ire-render nito ang file na iyon (data path, port, state backend) papunta sa `~/.agentmemory/data/iii-config.runtime.yaml` at ilulunsad ang engine gamit ang rendered copy, kaya i-edit ang source file, hindi ang rendered na isa. Pinapanatili ang mga value ng `host:` ng source file ayon sa pagkasulat.
+
+Sinasadyang nagbibind ang bundled na `iii-config.yaml` sa `127.0.0.1`, at nalalapat din ang default na ito sa loob ng container. Ang isang CLI na sinimulan sa isang container ay nakikinig sa loopback ng container, kaya walang maaabot ang mga published port. Para maihain ang isang containerized na CLI sa mga published port, i-set ang `AGENTMEMORY_III_CONFIG` sa isang config na nagbibind sa `0.0.0.0`. Ang packaged na `iii-config.docker.yaml` ay isa sa mga ito: nagbibind ito ng `iii-http`, `iii-stream` at ang engine port sa `0.0.0.0` at itinatago ang state sa ilalim ng `/data`, kaya i-mount ang isang writable volume dito. Panatilihing naka-set ang `AGENTMEMORY_SECRET`, at i-publish lamang ang mga port na kailangan mo, sa `127.0.0.1` o sa likod ng isang proxy na pinagkakatiwalaan mo.
+
+Hindi dumadaan sa config lookup ng CLI ang `docker-compose.yml` ng repo na ito: nag-mount ito ng `iii-config.docker.yaml` sa `/app/config.yaml`, at sinisimulan ang `iii-engine` container gamit ang `--config /app/config.yaml`. Isinusulat ng mga one-click [deploy template](../deploy/) ang sariling `0.0.0.0` config sa kanilang mga entrypoint.
+
+### Storage Backend: file (default) laban sa redis
+
+Nagde-default ang `iii-state` at `iii-stream` sa bundled na file-based KV store ng iii-engine: isang JSON file kada scope, nananatili sa memory ng engine process at isinusulat ulit sa disk sa isang timer. Ito ang tamang default para sa single-user na local install; mas mainam ang tunay na per-key write mula sa Redis para sa isang shared daemon na may ilang concurrent writer, sa gastos ng isang network round trip kada operation (nagsesiserialize pa rin ang bawat `state::*` call sa isang Redis connection, kaya ipinagpapalit nito ang lock ng file store para sa isang socket, hindi para sa parallelism).
+
+I-set ang `AGENTMEMORY_STATE_BACKEND=redis` (kasama ang `AGENTMEMORY_REDIS_URL`) para ilipat ang dalawang worker sa built-in na `redis` adapter ng iii-engine, na itinatago ang bawat key bilang Redis hash field (`HSET`) sa halip na isulat ulit ang isang buong scope sa bawat sulat:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+Nagde-default ang `AGENTMEMORY_STATE_BACKEND` sa `file`; ang hindi pagse-set nito ay pananatilihin ang kasalukuyang behavior, at ang isang hindi kilalang value (anuman maliban sa `file` o `redis`) ay isang startup error sa halip na isang tahimik na fallback. Iniulat ng `/agentmemory/status` at ng Health page ng viewer (ang State store row) kung aling backend ang aktibo at kung ito ba sumasagot, hindi kailanman ang URL.
+
+**Plain na `redis://` lamang.** Binubuo ng pinned engine (0.22.1) ang Redis client nito nang walang TLS support, kaya nabibigo kumonekta ang isang `rediss://` URL (karamihan sa mga managed Redis offering, gaya ng Upstash, Redis Cloud, at ElastiCache na may in-transit encryption, ay nagde-default sa TLS-only). Hindi encrypted ang connection, kaya tumatawid sa wire ang Redis password at ang bawat naka-store na memory sa clear text: ituro sa isang lokal na Redis o isa na nasa private network na pinagkakatiwalaan mo. Para sa ibang Redis, patakbuhin ang isang encrypted tunnel (stunnel, SSH, o VPN) sa agentmemory host, para manatili sa host na iyon ang plain na `redis://` hop at ma-encrypt at ma-authenticate ang upstream connection ng tunnel. Kung may single quote ang Redis password, percent-encode ito (`%27`); pinapalawak ng engine ang URL sa YAML config nito bago ito parse.
+
+**Isang Redis server kada `--instance`.** Fixed ang mga Redis key prefix ng engine (`state:`, `stream::`), kaya dalawang agentmemory instance (`--instance 1`, `--instance 2`, ...) na itinuro sa parehong database ay magpapatungan sa data ng isa't isa. Pinapanatili ng isang hiwalay na database index (`redis://localhost:6379/1`) ang itinagong data, pero ni-relay ng engine ang live viewer events sa isang Redis pub/sub channel (`stream::events`), at hindi pinapansin ng Redis pub/sub ang database index, kaya ang viewer ng bawat instance ay ipapakita rin ang live events ng iba. Bigyan ang bawat instance ng sariling Redis server (o port) kapag mahigit sa isa ang pinapatakbo mo.
+
+**Ano ang nananatili, at ano ang naiiba.** Gumagana sa Redis ang lahat ng feature ng agentmemory: sessions, obserbasyon, memory (remember, supersede, evolve, forget), search at ang mga index bucket, lesson, ang graph, ang audit log at ang monthly scopes nito, export at import, governance delete, consolidation status, ang viewer snapshot at ang live stream nito, at ang health monitor. Itinatago ng engine ang bawat scope bilang isang Redis hash (`HSET`/`HGET`/`HGETALL`) at pinapaputok ang parehong state trigger gaya ng file store. Tatlong pagkaiba ng engine ang hinahandle sa loob ng agentmemory:
+
+- Ibinabalik ng Redis ang mga record ng isang scope nang walang fixed na order. Isinasaayos ng agentmemory ang mga ito mula sa pinakamatanda (ayon sa creation time sa record id, pagkatapos ang timestamp nito) para ang mga list, paging, at export chunk ay bumalik sa parehong order gaya ng sa file store.
+- Ilalapat ng engine ang partial update sa Redis sa pamamagitan ng Lua script na gumagawa ng empty object mula sa empty array. Ilalapat mismo ng agentmemory ang mga update na iyon (read, change, write sa ilalim ng per-key lock) sa Redis, kaya nananatiling array ang mga field gaya ng `tags: []`.
+- Babasahin ng legacy audit log check ang lumang scope mula sa Redis sa halip na hanapin ang file ng file store sa disk.
+
+Isang pagkaiba ang nangangailangan ng aksyon mo: **pagkatapos mag-restart ang Redis, hihinto ang engine sa pag-relay ng live events** papunta sa viewer hanggang mag-restart ang agentmemory. Nananatiling naka-save at nababasa nang normal ang data. Nagpapadala ang health monitor ng isang test event sa Redis kada 30 segundo; kapag hindi ito bumalik, ipinapakita ng `/agentmemory/status` at ng Health page ng viewer ang "Live updates are not reaching the viewer" kasama ang fix: i-restart ang agentmemory. Kung down ang Redis, ipinapakita ng status report ang "The state store is not answering" at kung paano ito susuriin (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Babasahin ng isang listahan ng malaking scope ang buong hash sa isang `HGETALL`, parehong gastos ng file store na pinapanatili ito sa memory.
+
+**Inirerekomendang Redis settings.** Ang default na `save 3600 1 300 100 60 10000` snapshot policy ay maaaring mawalan ng mga minutong write sa isang crash, mas malala kaysa sa 5s flush window ng file store. I-set ang `appendonly yes` para sa anumang bagay na ayaw mong mawala. I-set ang `maxmemory-policy noeviction`; tahimik na dinadroop ng `allkeys-lru` o katulad nito ang mga memory kapag naabot ng Redis ang memory limit nito.
+
+Ang isang native (non-Docker) na start, at ang bawat one-click [deploy template](../deploy/) (nag-o-override sila ng bundled na `iii-config.yaml` at nagsisimula nang native), ay babasa ng `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` at ire-render ito sa inilunsad na `iii-config`. Hindi kailanman isinusulat ang URL mismo sa rendered na file na iyon, isang `${AGENTMEMORY_REDIS_URL}` reference lamang na pinapalawak ng engine process mula sa sariling environment nito sa boot. Ang sariling Docker Compose path ng repo na ito lamang (`AGENTMEMORY_USE_DOCKER=1`, o pagpapatuloy ng isang engine na nasimulan na sa paraang iyon) ay nag-mount ng `iii-config.docker.yaml` nang read-only at hindi kailanman nireder; nagbabala ang `agentmemory start` kapag natukoy nito ang kombinasyong iyon. Palitan ang file na iyon nang manu-mano, sinusundan ang parehong `name: redis` / `config: redis_url: ...` shape na ipinapakita sa [iii-state](https://workers.iii.dev/workers/iii-state) at [iii-stream](https://workers.iii.dev/workers/iii-stream) worker docs, at ituro ang `redis_url` sa isang Redis na maaabot mula sa container. Ipapasa ng `docker-compose.yml` ang `AGENTMEMORY_REDIS_URL` sa engine container, kaya gumagana roon ang `redis_url: '${AGENTMEMORY_REDIS_URL}'` at pinananatili ang URL sa labas ng mounted na file.
+
+Pinananatili ng rendered config ang URL sa labas ng `~/.agentmemory/data/iii-config.runtime.yaml`, pero ang sariling configuration worker ng engine ay pinapanatili pa rin ang *pinalawak* na value sa `~/.agentmemory/config/iii-state.yaml` at `iii-stream.yaml` kapag ito ay boot (nangyayari ang `${VAR}` expansion ng iii-engine bago iseed ng worker na iyon ang seed nito, at ang resolved value ang itinatago nito, hindi ang reference). Ituring na may hawak na credential ang directory na iyon: `chmod 700 ~/.agentmemory` sa anumang shared host, at mas piliin ang isang Redis ACL user na scoped sa kailangan ng agentmemory kaysa sa admin credentials ng database.
+
+**Hindi awtomatiko ang migration.** Ang pagpalit ng `AGENTMEMORY_STATE_BACKEND` ay nagsisimula mula sa walang-lamang store sa magkabilang panig; walang kumokopya ng umiiral na data mula sa file papunta sa Redis o pabalik. I-export mula sa backend na iniiwan mo at i-import papunta sa kinakalipat mo. Tumatakbo ito nang pareho sa bash at zsh (kasama ang `bash -u`). Ang isang array gaya ng `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` ay hindi: pinananatili ng zsh ang header bilang isang malformed na salita kung saan hinahati ito ng bash sa dalawa, kaya 401 ang dalawang request kapag naka-set ang `AGENTMEMORY_SECRET`:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+Tinatanggap din ng `/agentmemory/export` ang `?maxSessions=` at `?offset=` para sa chunking ng malaking corpus sa ilang call; ang `strategy` sa import ay `merge` (default-safe), `replace`, o `skip`.
+
+### Ano ang Pinapalitan ng iii
+
+| Traditional na Stack | Ginagamit ng 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 na plugin system | `iii worker add ` |
+
+**225 na source file · ~54,000 LOC · 2,600+ na test · 312 na function · 66 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
+
+---
+
+
+
+### Mga LLM Provider
+
+Awtomatikong tinutuklas ng agentmemory ang mga provider mula sa iyong environment. Pinagagana ng isang provider ang mga LLM-backed operation, pero ang configuration ng provider lamang ay hindi nagpapagana ng LLM-written na observation compression. Kailangan ng path na iyon ang parehong provider at `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Provider | Config | Mga Tala |
+|----------|--------|-------|
+| **No-op (default)** | Walang kailangang config | Naka-disable ang LLM-backed compress/summarize. Gumagana pa rin ang synthetic compression at BM25 recall. Tingnan ang `AGENTMEMORY_ALLOW_AGENT_SDK` sa ibaba kung dati kang umaasa sa Claude-subscription fallback. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Per-token billing |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
+| Gemini | `GEMINI_API_KEY` | Pinagagana din ang embeddings |
+| OpenRouter | `OPENROUTER_API_KEY` | Kahit anong model |
+| OpenAI API | `OPENAI_API_KEY` | Default `gpt-5.6-luna`, i-override gamit ang `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) o `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Anumang OpenAI-API-compatible. Zero cost, tumatakbo sa iyong hardware. Tingnan ang [Mga Local Model](#local-models-ollama--lm-studio--vllm) sa ibaba. |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in lamang. Nag-spawn ng mga `@anthropic-ai/claude-agent-sdk` session; dati itong nagdudulot ng unbounded Stop-hook recursion, kaya hindi na ito ang default. |
+
+### Mga Local Model (Ollama / LM Studio / vLLM)
+
+Kinakausap ng agentmemory ang anumang OpenAI-API-compatible na server, kaya gumagana nang walang pagbabago sa code ang anumang naglalantad ng `/v1/chat/completions`. Walang bayad na key, walang cloud, walang rate limit; tumatakbo nang buo sa iyong hardware.
+
+**Ollama** (default port `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (default port `1234`):
+
+Buksan ang LM Studio → Local Server tab → Start Server. Piliin ang kahit anong chat model mula sa picker (Qwen 3, gpt-oss, DeepSeek R1, atbp.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: parehong shape. Ituro ang `OPENAI_BASE_URL` sa kung anumang URL na inilalantad ng iyong server at i-set ang `OPENAI_MODEL` sa isang pangalang tatanggapin ng iyong server.
+
+**Pagpili ng model para sa memory work**: ang compression at summarization ay mga maikling task (<2K token papasok, <500 token palabas) kung saan sapat na ang isang 7B instruct model. Mga rekomendasyon:
+
+| Model | Laki | Bakit |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Balanced na default sa 16 GB machine; malakas sa extraction at tool-shaped na text |
+| `qwen3:4b` | ~2.6 GB | Pinakamaliit na makatwirang opsyon; sapat para sa compression, mahina para sa graph extraction |
+| `qwen3-coder:30b` | ~19 GB | Pinakamagandang local pick para sa code-shaped na session (30B MoE, 3.3B active) sa 24-32 GB hardware |
+| `gpt-oss:20b` | ~14 GB | Malakas na general model na kasya sa 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning distill; mas mabagal pero mas malinis ang extraction |
+
+Nag-iisip ang mga Qwen 3 model bilang default at maaaring maubos ang buong token budget sa reasoning bago ang anumang output. I-set ang `AGENTMEMORY_LLM_NOTHINK=1` para idagdag ang `/no_think` sa mga graph-extraction prompt, at itaas ang `MAX_TOKENS` (gumagana ang 16384) kung nagbabalik na walang-lamang ang mga extraction.
+
+Maaaring magbalik ang mga reasoning-class model (`o1`-style na may `` block) ng walang-lamang `content` na may `reasoning` field na posibleng hindi ilantad ng iyong local server. Kung nagbabalik na blangko ang mga extraction, lumipat muna sa isang non-reasoning na model. Maaari din i-disable ng env na `OPENAI_REASONING_EFFORT=none` ang thinking sa mga Ollama Cloud thinking model na sumasalamin sa OpenAI reasoning schema.
+
+Nag-ship ang local embeddings bilang opsyonal na dependency pero hindi ito naka-enable bilang default. I-set ang `EMBEDDING_PROVIDER=local` para opt in sa `Xenova/all-MiniLM-L6-v2` (384-dim). Nag-download ng model ang unang embedding request; on-device na ang inference pagkatapos. Kung walang setting na iyon o remote embedding key, mananatiling naka-disable ang vectors, gagamit ang `mem::search` ng BM25, at maaari pa ring idagdag ng `smart-search` ang umiiral na graph matches.
+
+### Cost-aware na Pagpili ng Model
+
+Kapag naka-enable ang LLM-written na background compression gamit ang parehong provider at `AGENTMEMORY_AUTO_COMPRESS=true`, tumatakbo ito sa bawat obserbasyon, kaya makabuluhang nagbabago sa monthly spend ang pagpili ng model. Nakuhang workload data: 635 request / 888K token / 35 oras ng aktibong paggamit, pinatakbo laban sa tatlong OpenRouter model sa pricing noong 2026-05-23.
+
+| Tier | Model | Input / 1M | Output / 1M | Gastos para sa nakuhang 35h | Mga Tala |
+|------|-------|------------|-------------|---------------------------|-------|
+| Inirerekomenda | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Pinakabagong DeepSeek; ang pinakamurang inirerekomendang pick para sa compression workload. |
+| Inirerekomenda | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid na compression + summarization quality sa ~10× na mas mababang gastos kaysa sa Sonnet. |
+| Inirerekomenda | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Malakas na code reasoning kung heavily code-shaped ang iyong mga session. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Parehong list price ng nasukat na Sonnet 4.6 run; $2/$10 intro pricing hanggang 2026-08-31. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flagship tier; mahal para sa always-on na background work. |
+| Iwasan | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flagship-class na model; overspend para sa compression. |
+
+Ang mga measured row ay mula sa nakuhang run; sinusukat ng mga (est.) row ang parehong token mix ayon sa list price ng bawat model.
+
+Nagprint ng runtime warning ang agentmemory kapag tumutugma ang `OPENROUTER_MODEL` sa isang premium-tier pattern. I-set ang `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para patahimikin ito kapag nakagawa ka na ng informed choice.
+
+Quality laban sa cost tradeoff para sa memory work: ang compression ay isang summarization task na may medyo maluwag na quality bar (binabasa ulit ng agent ang summary, hindi ng user). Napapalapit ang DeepSeek V4 Flash / V4 Pro / Qwen3-Coder sa rounding error ng Sonnet sa task na ito habang 10-70× na mas mura. Itago ang mga premium-tier model para sa mga query na direktang babasahin mo.
+
+Mga Source: [OpenRouter pricing para sa Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Multi-agent na Memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Sa multi-agent setup kung saan nagbabahagi ng isang agentmemory server ang ilang role (architect / developer / reviewer / researcher / support-agent), tinatakan ng `AGENT_ID` ang bawat sulat gamit ang role na gumawa nito. Kinokontrol ng `AGENTMEMORY_AGENT_SCOPE` kung mag-filter ang recall ayon sa tag na iyon.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Dalawang mode:
+
+| Mode | Tinatakan ang Sulat | Nag-filter ang Recall | Kailan Gagamitin |
+|------|------------|---------------|-------------|
+| `shared` (default) | oo | hindi | Cross-agent na context na may audit trail. Makikita ng architect ang naitala ng developer, pero itinatala ng bawat row kung sino ang nagsabi nito. |
+| `isolated` | oo | oo | Mahigpit na paghihiwalay. Hindi kailanman makikita ng architect ang mga obserbasyon / memory / session ng developer. |
+
+Ang natatakan kapag naka-set ang `AGENT_ID`: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Dumadaloy ang role mula sa `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Ang na-filter sa isolated mode: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Tinatanggap ng bawat endpoint ang `?agentId=` para i-override kada-request, at `?agentId=*` para lumabas nang buo sa env scope. Tinatanggap din ng `/memories` ang `?includeOrphans=true` para ilantad ang mga pre-AGENT_ID na memory na hindi defined ang `agentId`.
+
+Per-call override sa SDK / REST layer: tinatanggap ng bawat mutating endpoint (`/session/start`, `/remember`) ang isang `agentId` field sa request body na nananaig kaysa sa env. Kapaki-pakinabang para sa mga runtime na nagruruta ng maraming role sa isang server process. Inilalantad ng MCP tool na `memory_save` ang parehong `agentId` field, ipinapasa ng standalone stdio server ang parehong `agentId` at `project`, at dala ng mga na-save na memory ang `agentId` papunta sa search index, kaya saklaw ng agent-scoped search ang mga memory gayundin ang mga obserbasyon.
+
+Kapag hindi naka-set ang `AGENT_ID`, nananatiling unscoped ang memory (legacy behavior, walang tag, walang filter).
+
+### Mga Port
+
+Nagbibind ang agentmemory + iii-engine ng apat na port bilang default. Kung nabigo ang isang restart gamit ang `port in use`, sinasabi sa iyo ng table na ito kung aling process ang hahanapin.
+
+| Port | Process | Layunin | Env override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Internal streams worker (ginagamit ng agentmemory + viewer) | `III_STREAM_PORT` (mas pinipili) o legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Real-time viewer (`http://localhost:3113`) | `III_VIEWER_PORT` o `AGENTMEMORY_VIEWER_URL` para sa inireport na URL |
+| `49134` | iii-engine | WebSocket; nagrerehistro rito ang mga worker, dumadaloy dito ang OTel telemetry | `III_ENGINE_PORT` o `III_ENGINE_URL` |
+
+Binabago ng `--port ` ang REST anchor at kinukuha ang streams `N+1`, viewer `N+2`, at engine WebSocket `N+46023` lamang kung hindi naka-set ang kaukulang explicit port o URL sa itaas. Hindi ito gumagawa ng isolated na lifecycle namespace. Gamitin ang `--instance 1` para sa pangalawang daemon; ginagamit nito ang anchor 3211, nagde-default sa `3211/3212/3213/49234`, at nakatanggap ng hiwalay na `instance-1` data at lifecycle directory. Sinusunod ng Instance 1 hanggang 50 ang parehong pattern.
+
+Sinisimulan ang pinned engine gamit ang `--no-update-check` (walang update o security-advisory lookup laban sa GitHub sa boot) at naka-off ang anonymous usage telemetry ng iii: itinatakda ng agentmemory ang `III_TELEMETRY_ENABLED=false` para sa engine na spawn nito maliban kung mismo mong i-export ang variable, at ganoon din ang bundled compose file.
+
+Stale-process cleanup kapag nananatiling bound ang mga port pagkatapos ng isang crashed run:
+
+```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
+```
+
+Malinis na kinukuha ng `agentmemory stop` ang worker at ang engine pidfile sa isang graceful native shutdown. Sa Docker mode, nag-flush ito ng native worker, itinitigil ang eksaktong validated na engine container, at pinapanatili ang parehong container at ang `/data` mount nito para sa isang lossless restart; ive-validate at ipagpapatuloy ng susunod na start ang parehong container. Kailangan ng Docker-backed na uninstall ang `agentmemory remove --keep-data`: tinatanggal nito ang shared na agentmemory-managed file habang pinapanatili ang validated na container, ang data mount nito, at ang lifecycle record na kailangan para mabawi ito. Sinadyang iniiwan sa operator ang destructive na Docker data deletion pagkatapos ng isang backup. Tumatanggi din ang CLI na angkinin o i-signal ang mga Docker o VM port holder (Docker backend, vpnkit, colima) bilang native engine maliban kung ipinasa ang `--force`. Ang manual na cleanup sa itaas ay para lamang sa post-crash na kaso kung saan walang natitirang alinmang pidfile.
+
+### Config File
+
+Ilagay ang runtime configuration ng agentmemory sa `~/.agentmemory/.env` sa halip na i-export ang mga variable sa bawat shell. Kung ipinapakita ng viewer ang isang setup hint gaya ng `export ANTHROPIC_API_KEY=...`, kopyahin ito sa file na ito bilang `ANTHROPIC_API_KEY=...` nang walang `export` prefix, pagkatapos i-restart ang agentmemory.
+
+Gumagana pa rin ang process environment variable at mananaig ito kaysa sa mga value sa file.
+
+Sa Windows, nasa `%USERPROFILE%\.agentmemory\.env` ang parehong file:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Para magsubok gamit ang isang Claude Code Pro/Max subscription sa halip ng isang API key, opt in nang tahasan:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Kailangan ng LLM-written na observation compression ang parehong linya: access sa isang LLM provider (kasama ang tahasang subscription fallback na ito) at `AGENTMEMORY_AUTO_COMPRESS=true`. Iiwanan ng provider mismo ang default na synthetic compression path.
+
+Naka-on bilang default ang consolidation (graph node, lesson, crystal) sa tuwing naka-configure ang isang LLM provider. Tahasang opt out gamit ang `CONSOLIDATION_ENABLED=false` kung nais mo ng LLM-free operation. Hiwalay na flag ang graph extraction:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Mga Environment Variable
+
+Gawin ang `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer `, at kinakailangan ng mga mesh sync endpoint ang tahasang naka-set na `AGENTMEMORY_SECRET` sa dalawang peer.
+
+**Naka-on ang Authentication bilang default.** Kapag hindi naka-set ang `AGENTMEMORY_SECRET` (sa shell o sa `~/.agentmemory/.env`), gumagawa ang server ng random na secret sa unang start at itinatago ito sa `~/.agentmemory/secret` na may mode `0600`. Babasahin ito mula roon ng bawat bundled na client kapag nakikipag-usap ito sa isang local server: ang CLI, ang viewer, ang hooks sa ilalim ng `plugin/scripts`, ang MCP server at ang `@agentmemory/mcp` shim, ang mga config na isinulat ng `agentmemory connect`, at ang bundled na OpenCode, Pi, OpenClaw, Hermes, at filesystem-watcher integrations. Ipinapadala lamang ang itinagong secret sa mga loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Palaging mananaig ang isang tahasang `AGENTMEMORY_SECRET`, at kailangan pa rin itong naka-set para sa mga remote client. Gumagawa at nag-export na ng sariling secret ang Docker at ang mga entrypoint ng `deploy/`. Para tawagin ang API nang manu-mano:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Mga Tuntunin ng Request para sa Sulat.** Dapat magpadala ng `Content-Type: application/json` (okay ang isang `charset` parameter) ang mga request na `POST`, `PUT`, `PATCH` at `DELETE` papunta sa REST API at sa viewer sa tuwing may dala itong body, at ang isang `Origin` header, kapag naroroon, ay dapat isang loopback origin para sa naka-configure na REST o viewer port o nakalista sa `VIEWER_ALLOWED_ORIGINS` (comma-separated, hal. `https://memory.example.com`). Hindi apektado ang mga client na walang ipinapadalang `Origin` header (CLI, hooks, MCP, curl, server-to-server). Tinatanggap din ng viewer ang sariling origin nito.
+
+**Mga File Path.** Ang mga endpoint na nagbabasa o nagsusulat ng file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) ay tumatanggap lamang ng mga path sa ilalim ng `~/.agentmemory`, ang instance data directory, o isang directory na nakalista sa `AGENTMEMORY_IMPORT_ROOT` (paghiwalayin ang ilan gamit ang `:`, o `;` sa Windows). Tinatanggap din ng `/replay/import-jsonl` ang default nitong `~/.claude/projects`. Nananatili ang `/obsidian/export` sa loob ng `AGENTMEMORY_EXPORT_ROOT` at ang `/migrate` sa loob ng `~/.agentmemory`. Nireresolba ang mga symlink bago ang bawat check.
+
+**Secret Scrubbing.** Ang mga API key, bearer token, PEM private key block, at credential na naka-embed sa mga URL (`scheme://user:password@host`) ay nire-redact bago maitago ang text, sa bawat write path: obserbasyon, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, compression at summary output, crystal, at graph node.
+
+
+Mga Pangunahing Endpoint
+
+| Method | Path | Paglalarawan |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (laging public) |
+| `GET` | `/agentmemory/status` | Ano ang mali at paano ito aayusin (HTML para sa browser, JSON kung hindi) |
+| `GET` | `/agentmemory/viewer/snapshot` | Lahat ng ipinapakita ng viewer, sa isang response |
+| `POST` | `/agentmemory/session/start` | Simulan ang session + kunin ang context |
+| `POST` | `/agentmemory/session/end` | Tapusin ang session |
+| `POST` | `/agentmemory/observe` | Kunin ang obserbasyon (tingnan ang capture delivery sa ibaba) |
+| `GET` | `/agentmemory/capture` | Capture inbox, dead letter, at offline spool |
+| `POST` | `/agentmemory/capture/retry` | Ulitin ang mga dead-letter capture |
+| `POST` | `/agentmemory/capture/drain` | Ipadala na ang local offline spool |
+| `POST` | `/agentmemory/smart-search` | Hybrid search |
+| `POST` | `/agentmemory/context` | Buuin ang context |
+| `POST` | `/agentmemory/remember` | I-save sa long-term memory |
+| `POST` | `/agentmemory/forget` | Burahin ang mga obserbasyon |
+| `POST` | `/agentmemory/enrich` | File context + memory + bug |
+| `GET` | `/agentmemory/profile` | Profile ng project |
+| `GET` | `/agentmemory/export` | I-export ang lahat ng data |
+| `POST` | `/agentmemory/import` | I-import mula sa JSON |
+| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
+| `POST` | `/agentmemory/graph/compact` | Putulin ang oversized na graph provenance |
+| `POST` | `/agentmemory/team/share` | Ibahagi sa team |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Kumpletong listahan ng endpoint: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Capture Delivery.** Ipinapadala ng hooks ang bawat obserbasyon isang beses sa `POST /agentmemory/observe` na may `eventId`. Ito ang sariling id ng host para sa call kapag may isa ang payload (halimbawa ang `tool_use_id` ng Claude Code), kung hindi ay isang hash ng session, hook type, tool name, input, output, at host timestamp. Isusulat ng server ang event sa isang capture inbox sa state store, itinatago ang obserbasyon, pagkatapos tanggalin ang inbox entry. Sinasabi ng status code kung ano ang nangyari:
+
+| Status | `status` field | Kahulugan |
+|---|---|---|
+| `201` | `accepted` | Naitago. Ang `observationId` ay ang bagong obserbasyon. |
+| `202` | `accepted` (`state: "retrying"`) | Tinanggap, pero nabigo ang pag-store. Uulitin ito ng server, maging pagkatapos ng isang restart. |
+| `200` | `duplicate` | Natanggap na dati ang `eventId` na ito. Ang `observationId` ay ang umiiral na obserbasyon; walang bagong naitago. |
+| `400` / `422` | `rejected` | Hindi valid ang payload, o permanenteng nabigo ang pag-store (itinatago ang event bilang dead letter). |
+| `503` | `rejected` (`retryable: true`) | Puno ang inbox (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Isinusulat ng hooks ang event sa spool at ipapadala ito mamaya. |
+
+Uulitin ang mga nabigong event kada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) na may doubling backoff, hanggang `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Ang mga event na nananatiling nabigo ay nananatili sa inbox bilang dead letter, nililista sa `/agentmemory/status` at sa Health page ng viewer, at maaaring ulitin gamit ang `POST /agentmemory/capture/retry` (`{"eventId": "..."}` o `{"all": true}`). Naaalala ang mga tinanggap na event id sa loob ng `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 oras, pinakamarami na `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), kaya ang isang hook na nireplay pagkatapos ng isang timeout o isang restart ay naitatago isang beses lamang, habang dalawang hiwalay na tool call na may sariling host id ay naitatago nang dalawang beses kahit magkapareho ang nilalaman. Kapag nabura ang isang obserbasyon (forget, session delete, eviction, auto-forget, o isang import na pumapalit sa store), minamarkahan ang event nito bilang nabura bago matanggal ang obserbasyon, kaya ang isang replay ng event na iyon sa loob ng parehong window ay sinasagot bilang duplicate at walang itinatago. Isinusulat ng state store sa disk kada 2 segundo, kaya ang isang sinagot na event ay maaaring nasa memory lamang sandali. Para masaklaw ito, dala rin ng bawat `2xx` na sagot ang `bootId` ng server (bago sa bawat start), `acceptedAt`, at `durableAfterMs` (ang save interval kasama ang 1.5 s sa file store, 1.5 s sa redis, kung saan ang persistence ay setting ng operator). Itinatago ng hooks ang event sa local spool hanggang lumipas ang window na iyon at tinatanggal ito sa isang susunod na call nang walang karagdagang request. Kung nagbago na ang `bootId` sa oras na iyon, nag-restart ang server, kaya ipinapadala ulit ng hook ang event gamit ang parehong `eventId`; ang isang event na nakarating na sa disk ay hindi naitatago nang dalawang beses. Ipinapadala rin ng server mismo ang mga event na ito sa start at sa bawat retry interval, kaya walang mawawala sa isang restart kahit walang tumakbong hook pagkatapos. Hindi pinapansin ng mas lumang hooks ang mga extra field, at itinatapon ng mga bagong hooks laban sa isang mas lumang server ang event sa `2xx` gaya ng dati.
+
+Kapag down ang server, hindi sumagot sa oras, o nagbalik ng 5xx, idinadagdag ng hook ang obserbasyon sa isang local spool file, `/capture-spool/-.jsonl` (i-override ang folder gamit ang `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Private sa iyong user ang file (mode 600), nire-redact ang mga secret sa parehong paraan na nire-redact ito ng server, hawak nito ang pinakamarami na `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) at itinatapon ang mga entry na mas matanda sa `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Kapag puno na, itinatapon at binibilang ang mga bagong entry, at iniulat ito ng `/agentmemory/status`. Nag-exit pa rin ng 0 ang hook sa loob ng time limit nito at hindi nagdadagdag ng request kapag healthy ang server. Ipinapadala ang spool sa susunod na start at ng unang hook na maabot ulit ang server, sa isang background process para hindi maghintay ang agent. Ginagawang ligtas ito ng event id: ang isang obserbasyon na nakarating na bago ang isang timeout ay hindi naitatago nang dalawang beses. Ipinapakita ng `npx @agentmemory/agentmemory capture` ang spool at ang inbox ng server, ipinapadala ng `--drain` ang spool ngayon, at ibinabalik ng `GET /agentmemory/capture` ang pareho bilang JSON. I-set ang `AGENTMEMORY_CAPTURE_SPOOL=false` para patayin ang spool.
+
+**Compacting Graph Provenance.** Itinatago ng bawat knowledge graph node at edge ang mga id ng pinakabagong 32 obserbasyon na pinagmulan nito. Ang mga store na isinulat bago ang cap na iyon ay maaaring hawak ng libo-libong id kada hot node, na nagpapabagal sa graph search at sa viewer o nagpapabagsak sa worker. Mismong inaayos ito ng agentmemory: sa unang start pagkatapos ng upgrade, pinuputol nito ang bawat node, edge, superseded edge (ang temporal graph history) at ang cached snapshot pababa sa cap sa background, sa maliliit na slice na may pahinga sa pagitan, para patuloy na gumana ang search, capture, at viewer. Nagse-save ito ng progress nito, nagpapatuloy pagkatapos ng isang restart at hindi na tumatakbo ulit kapag natapos na. Ipinapakita ito ng `/agentmemory/status` at ng Health page ng viewer bilang pending, running (kasama ang kasalukuyang scope at posisyon), done, o failed. I-set ang `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` para patayin ito.
+
+Para patakbuhin ito nang manu-mano, tawagin ang `POST /agentmemory/graph/compact`. Dumadaan ito sa name at edge-key indexes sa halip na ilista ang bawat node at edge, at ligtas itong patakbuhin ulit. Kapag pinuputol nito ang mga id, isinusulat nito ang isang `graph_compact` audit entry.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Sa isang malaking store, o kapag nagbalik ng 504 ang call, patakbuhin ito sa mga slice. Ipadala ang `scope` (`nodes`, `edges` o `history`), `offset` at `limit`, pagkatapos tawagin ulit gamit ang ibinalik na `nextOffset` hanggang `null` ito. Gawin ito para sa `nodes`, `edges`, at `history`, at tapusin gamit ang isang `{"scope":"snapshot"}` call, dahil hindi ginagalaw ng isang sliced run ang cached snapshot.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Mga Prerequisite:** Node.js >= 20 na may npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 o Docker. Kinakailangan din ng automatic na engine install sa macOS/Linux ang `curl`, isang POSIX `sh`, at `tar`; gumagamit ang native Windows ng manual na pinned `iii.exe`, WSL2, o Docker Desktop.
+
+
- Kodlama ajanınız her şeyi hatırlasın. Aynı şeyi bir daha açıklamayın.
- Built on iii engine
+ Kodlama ajanınız her şeyi hatırlar. Artık yeniden açıklamaya gerek yok.
+ iii engine üzerine inşa edilmiştir
- Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ve her MCP istemcisi için kalıcı bellek.
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ve her MCP istemcisi için kalıcı bellek.
- 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.
+ Bu gist, Karpathy'nin LLM Wiki desenini güven puanlaması, yaşam döngüsü, bilgi grafları ve hibrit arama ile genişletir: agentmemory bunun uygulamasıdır.
@@ -75,56 +96,68 @@
## Kurulum
-Tek komut:
+Gereksinimler:
+
+- npm ve npx ile birlikte Node.js 20 veya daha yeni bir sürüm (`node -v`, `npm -v` ve `npx -v`).
+- macOS/Linux üzerinde otomatik iii-engine kurulumu ayrıca `curl`, bir POSIX `sh` ve `tar` gerektirir. `node:20-slim` gibi minimal imajlar bunları içermeyebilir.
+- Yerel (native) Windows, sabitlenmiş iii-engine v0.22.1 `iii.exe` dosyasının manuel olarak kurulmasını gerektirir. WSL2 veya Docker Desktop, desteklenen diğer yollardır.
+
+Standart, sıfırdan kurulum komutu:
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-İlk çalıştırma interaktif bir kurulumdur: bağlanacak ajanları seçin (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), bir LLM sağlayıcısı seçin veya anahtarsız kalın; kurulum yapılandırmayı hazırlar, bellek sunucusunu `:3111` üzerinde başlatır ve çıplak `agentmemory` komutunun sonrasında her yerde çalışması için global kurulum önerir.
+İlk çalıştırma, etkileşimli bir kurulumdur: bağlanacak ajanları seçersiniz (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), bir LLM sağlayıcısı seçersiniz veya anahtarsız (keyless) kalırsınız; kurulum yapılandırmayı oluşturur, bellek sunucusunu ve sabitlenmiş iii engine'ini başlatır ve tek başına `agentmemory` komutunun her yerde çalışması için genel (global) olarak kurulmasını önerir. `-y`, npx'in paket istemini kabul eder ve `@latest`, eski bir önbelleğe alınmış sürümden kaçınır. Bir sağlayıcı, LLM özelliklerini kullanılabilir kılar; ancak LLM tarafından yazılan gözlem sıkıştırması yalnızca `AGENTMEMORY_AUTO_COMPRESS=true` da ayarlandığında başlar.
+
+Anahtarsız (keyless) mod, vektör embedding'lerini devre dışı bırakır. `memory_recall` (`mem::search` yolu) BM25 kullanır; `memory_smart_search` ise graf verisi zaten mevcutsa yapısal graf eşleşmelerini de füzyonlayabilir. Ücretsiz, cihaz üzerinde (on-device) semantik recall için `~/.agentmemory/.env` içinde `EMBEDDING_PROVIDER=local` ayarlayın ve yeniden başlatın. İlk embedding isteği `Xenova/all-MiniLM-L6-v2` modelini indirir; bu ilk model indirmesinden sonra çıkarım (inference) yerel olarak çalışır.
-Ardından recall'un çalıştığını kanıtlayın ve ajanınıza skill'lerini verin:
+Yerel runtime dört port kullanır: REST/MCP HTTP için `3111`, iii stream'leri için `3112`, görüntüleyici için `3113` ve iii worker WebSocket'i için `49134`. Kalıcı iii state'i macOS'ta `~/Library/Application Support/agentmemory`, Linux'ta `$XDG_DATA_HOME/agentmemory` veya `~/.local/share/agentmemory`, Windows'ta ise `%APPDATA%\agentmemory` içinde yaşar. Bunu geçersiz kılmak için `--data-dir ` veya `AGENTMEMORY_DATA_DIR` kullanın ve her yeniden başlatmada aynı değeri yeniden kullanın. Geriye dönük uyumluluk için, mevcut bir `./data/state_store.db` veya `./data/iii-config.yaml`, instance 0 için platform varsayılanına göre önceliklidir; açık bir flag veya ortam değişkeni geçersiz kılma yine de kazanır.
+
+Ardından recall'ın çalıştığını kanıtlayın ve ajanınıza skill'lerini verin:
```bash
-agentmemory demo --serve # seed sample sessions + watch recall find them
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
-Tüm işi bir kodlama ajanına mı bırakmayı tercih ediyorsunuz? Ona tek bir talimat verin:
+Anahtar kelime aramaları, varsayılan anahtarsız modda BM25 üzerinden eşleşmelidir. Demo'nun `database performance optimization` sorgusu kasıtlı olarak semantiktir ve bir embedding sağlayıcısı yapılandırılana kadar sıfır sonuç döndürebilir.
+
+Tüm işi bir kodlama ajanına bırakmayı mı tercih edersiniz? Ona şu tek talimatı verin:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Dilediğiniz zaman `agentmemory connect ` ile daha fazla ajan bağlayın — 20 adaptör [Her ajanla çalışır](#works-with-every-agent) bölümünde listelenir. Tam komut referansı [Hızlı Başlangıç](#quick-start) bölümünde.
+`agentmemory connect ` ile her zaman daha fazla ajan bağlayabilirsiniz — [Her ajanla çalışır](#works-with-every-agent) bölümünde listelenen 20 adaptör. Tam komut referansı [Hızlı Başlangıç](#quick-start) bölümünde.
Windows
-Hızlı yol WSL2'dir. Yerel Windows engine kurulumu manueldir (yaklaşık 10 ila 20 dakika) ve `agentmemory connect` şu anda orada desteklenmiyor. Adım adım ilerleyiş için [Windows notlarına](#windows) bakın.
+Hızlı yol WSL2'dir. Yerel Windows engine kurulumu, sabitlenmiş v0.22.1 ZIP dosyasının indirilmesini ve `iii.exe`'nin manuel olarak çıkarılmasını gerektirir; CLI bunu otomatik olarak çıkarmaz. Docker Desktop de desteklenir. Adım adım anlatım için [Windows notları](#windows) bölümüne bakın.
-Global kurulum / EACCES
+Genel (global) kurulum / EACCES
```bash
-npm install -g @agentmemory/agentmemory
-# If you hit EACCES on macOS/Linux system Node installs:
-sudo npm install -g @agentmemory/agentmemory
+npm install -g @agentmemory/agentmemory@latest
```
+Yukarıdaki npx komutu, standart sıfırdan kurulum yolu olarak kalır ve global-prefix izin sorunlarından kaçınır.
+
-npx eski bir sürümü servis ediyor
+npx eski bir sürüm sunuyor
-npx sürüm bazında önbelleğe alır. 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).
+npx, sürüm bazında önbelleğe alır. En güncel sürümü `npx -y @agentmemory/agentmemory@latest` ile zorlayın veya önbelleği bir kez `rm -rf ~/.npm/_npx` ile temizleyin (macOS/Linux; Windows'ta `%LOCALAPPDATA%\npm-cache\_npx` dizinini silin).
-Zaten kendi iii engine'inizi çalıştırıyorsanız
+Kendi iii engine'inizi zaten çalıştırıyorsanız
-agentmemory iii-engine'i v0.11.2'ye sabitler ve farklı bir sürüme bağlanmaz (worker başka bir engine'in protokolünü konuşamaz). Diğer engine'i durdurun, ardından `npx -y @agentmemory/agentmemory@latest` çalıştırın. Sabitlenmiş v0.11.2'yi `~/.agentmemory/bin` içine kurup çalıştırır ve kendi `iii`'nizi olduğu gibi bırakır.
+agentmemory, iii-engine v0.22.1'i sabitler ve farklı bir sürüme bağlanmaz (worker, başka bir engine'in protokolünü konuşamaz). Diğer engine'i durdurun, ardından `npx -y @agentmemory/agentmemory@latest` komutunu çalıştırın. Bu, sabitlenmiş v0.22.1'i `~/.agentmemory/bin` içine kurar ve çalıştırır; kendi `iii`'nizi dokunulmamış bırakır.
@@ -132,110 +165,170 @@ agentmemory iii-engine'i v0.11.2'ye sabitler ve farklı bir sürüme bağlanmaz
-agentmemory; hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalışır. Tüm ajanlar aynı bellek sunucusunu paylaşır.
+agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalışır. Tüm ajanlar aynı bellek sunucusunu paylaşır.
- MCP veya HTTP konuşan herhangi bir ajanla çalışır. Tek sunucu, tüm ajanlar arasında paylaşılan bellek.
+ MCP veya HTTP konuşan her ajanla çalışır. Tek sunucu, hepsinde paylaşılan bellekler.
---
-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.
+Her oturumda aynı mimariyi yeniden açıklarsınız. Aynı bug'ları yeniden keşfedersiniz. Aynı tercihleri yeniden öğretirsiniz. 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ında ç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 anlatmaya da kopyala-yapıştıra da gerek kalmaz.
+**Ne değişir:** 1. oturumda JWT auth kurdunuz. 2. oturumda rate limiting istiyorsunuz. Ajan, auth'unuzun `src/middleware/auth.ts` içinde jose middleware kullandığını, testlerinizin token doğrulamasını kapsadığını ve Edge uyumluluğu için jsonwebtoken yerine jose'yi seçtiğinizi zaten bilir; yeniden açıklama ve kopyala-yapıştır yapmadan.
```bash
-npx @agentmemory/agentmemory
+npx -y @agentmemory/agentmemory@latest
```
-> **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.
+Varsayılan olarak agentmemory, iii-engine state'ini onu başlattığınız repodan ayrı bir yerde saklar: macOS'ta `~/Library/Application Support/agentmemory`, Linux'ta `$XDG_DATA_HOME/agentmemory` veya `~/.local/share/agentmemory`, Windows'ta ise `%APPDATA%\agentmemory`. Mevcut bir eski (legacy) `./data/state_store.db` veya `./data/iii-config.yaml`, bu platform varsayılanından önce instance 0 için yeniden kullanılır. Bir konumu açıkça seçmek için `--data-dir ` geçirin veya `AGENTMEMORY_DATA_DIR` ayarlayın; her iki açık ayar da eski (legacy) keşfe göre önceliklidir:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Native ve Docker başlatmaları, aynı çözümlenmiş host dizinini kullanır; Docker bunu `/data` üzerine bind-mount eder. `--instance 1`, çözümlenmiş dizine `instance-1` ekler ve ayrı varsayılan port dörtlüsünü `3211/3212/3213/49234` seçer.
+
+En son sürüm notları: [CHANGELOG.md](../CHANGELOG.md).
---
@@ -247,21 +340,21 @@ npx @agentmemory/agentmemory
### Geri Getirme Doğruluğu
-**coding-agent-life-v1** (kurum içi corpus, sandbox-yeniden üretilebilir)
+**coding-agent-life-v1** (şirket içi (in-house) corpus, sandbox'ta yeniden üretilebilir)
-| Adaptör | P@5 | R@5 | Top-5 isabet oranı | p50 gecikme |
+| Adaptör | P@5 | R@5 | İlk 5'te bulma oranı | p50 gecikme |
|---|---|---|---|---|
-| **agentmemory hibrit** | **0.240** | **1.000** | **15 / 15** | 14 ms |
-| grep referansı | 0.227 | 0.967 | 15 / 15 | 0 ms |
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
-Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %100 top-5 isabet oranı. Hibrit her gold oturumu getirir; grep çok-oturumlu zamansal sorguda 2 gold'dan 1'ini kaçırır. Kazanç toplam hassasiyet değil, **recall + zamansallıktır**. Bu benchmark küçük ve gold açısından seyrektir; aşağıdaki daha büyük LongMemEval-S daha iyi ayrıştırır. Tam tip bazında döküm + düzeltme notu: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
+Bu corpus için **P@5 matematiksel tavanında** (0.240, scorecard'a bakın) %100 ilk-5 bulma oranı. Hybrid, her gold oturumu getirir; grep, çok-oturumlu temporal sorguda 2 gold'dan 1'ini kaçırır. Kazanım **recall + temporal**'dir, toplam precision değil. Bu benchmark küçüktür ve gold açısından seyrektir; aşağıdaki daha büyük LongMemEval-S daha iyi ayrıştırır. Tam tür bazlı döküm + düzeltme notu: [`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% |
+| Yalnızca BM25 fallback | 86.2% | 94.6% | 71.5% |
@@ -271,19 +364,19 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
| 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 |
+| LLM ile özetlenmiş | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
-| agentmemory + yerel embedding | ~170K | **$0** |
+| agentmemory + yerel embedding'ler | ~170K | **$0** |
-> 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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo ile karşılaştırması.
+> Embedding modeli: `all-MiniLM-L6-v2` (yerel, ücretsiz, API anahtarı gerektirmez). 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'yi mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo ile karşılaştırır.
-**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 bir 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.
+**Yerelde yeniden üretin:** [`eval/README.md`](../eval/README.md), LongMemEval `_s` (herkese açık 500 soru) + `coding-agent-life-v1` (şirket içi 15-oturumluk corpus) için adaptör-takılabilir bir harness. Grep / vektör / agentmemory adaptörleri yan yana puanlanır, NDJSON çıktısı verir, yayımlanan scorecard'lar [`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).
+**[codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything) ve [Graphify](https://github.com/safishamsi/graphify) ile eşleşir.** Kod-grafı indeksleme, çok-ajanlı build pipeline'ları ve doküman / PDF / görüntü / video genelinde daha geniş bilgi grafları. agentmemory yapılan işi hatırlar; bu üç proje, bağlam katmanının gerisini aydınlatır. Tarifler + soru-yönlendirme tablosu: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
@@ -305,19 +398,19 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
Tür
-
Bellek motoru + MCP sunucusu
+
Bellek engine'i + MCP sunucusu
Bellek katmanı API'si
Tam ajan runtime'ı
Kişisel AI
Bellek API'si + uygulama
-
Takım bellek hub'ı (LLM proxy)
-
Vektör bellek (OSS)
-
Bellek motoru (Oracle DB)
+
Takım belleği hub'ı (LLM proxy)
+
Vektör belleği (OSS)
+
Bellek engine'i (Oracle DB)
Bellek sistemi
Statik dosya
-
Geri getirme R@5
+
Geri Getirme R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
@@ -333,10 +426,10 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
Otomatik yakalama
12 hook (sıfır manuel çaba)
Manuel add() çağrıları
-
Ajan kendi düzenler
+
Ajan kendi kendine düzenler
Manuel
API tarafında çıkarım
-
Proxy araya girmesi (base-URL değişimi)
+
Proxy ile yakalama (base-URL değişimi)
Manuel
API çıkarımı
Manuel
@@ -346,33 +439,33 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
Arama
BM25 + Vektör + Graf (RRF füzyonu)
Vektör + Graf
-
Vektör (arşiv)
-
Anlamsal
+
Vektör (arşivsel)
+
Semantik
Vektör + RAG
4 varlık türü (Chat / Skill / Wiki / CodeGraph)
-
Yalnız-vektör
-
Vektör + anlamsal
-
Decay-ağırlıklı
+
Yalnızca vektör
+
Vektör + semantik
+
Çürüme ağırlıklı (decay-weighted)
Her şeyi bağlama yükler
Çoklu ajan
-
MCP + REST + lease'ler + sinyaller
+
MCP + REST + lease'ler + signal'ler
API (koordinasyon yok)
Yalnızca Letta runtime'ı içinde
-
Yok
-
Yok
+
Hayır
+
Hayır
Takım rolleri + paylaşılan varlıklar
-
Yok
-
Yalnızca kapsamlı
-
Çoklu-ajan paylaşımlı
-
Ajan başına dosya
+
Hayır
+
Yalnızca scope'lu
+
Çoklu ajan arasında paylaşılan
+
Ajan başına dosyalar
-
Framework bağımlılığı
+
Framework bağımlılığı (lock-in)
Yok (herhangi bir MCP istemcisi)
Yok
-
Yüksek (Letta kullanılmalı)
+
Yüksek (Letta kullanmak zorunlu)
Bağımsız
Yok
Proxy her model çağrısının önünde
@@ -386,9 +479,9 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
Yok (SQLite + iii-engine)
Qdrant / pgvector
Postgres + vektör DB
-
Birden çok
+
Birden fazla
Yönetilen bulut
-
Docker stack (Core + Hub + Proxy)
+
Docker stack'i (Core + Hub + Proxy)
Vektör deposu
Oracle AI Database
Yok
@@ -396,16 +489,16 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
4 katmanlı konsolidasyon + çürüme + otomatik unutma
Pasif çıkarım
-
Ajan-yönetimli
+
Ajan tarafından yönetilen
Manuel
-
Otomatik-unutma
-
Manuel inceleme; otomatik yönlendirme yolda
+
Otomatik unutma
+
Manuel inceleme; otomatik yönlendirme geliştiriliyor
Yok
Belirtilmemiş
-
Decay + konsolidasyon
-
Manuel ayıklama
+
Çürüme + konsolidasyon
+
Manuel budama
Token verimliliği
@@ -416,30 +509,30 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
Bulut fiyatlandırması
Belirtilmemiş
Token bütçesi yok
-
LLM-destekli (değişir)
+
LLM destekli (değişir)
Değişir
240 gözlemde 22K+ token
Gerçek zamanlı görüntüleyici
-
Var (port 3113)
-
Bulut panel
-
Bulut panel
-
Web UI
-
Bulut panel
-
Hub web UI
-
Yok
-
Yok
-
Yok
-
Yok
+
Evet (port 3113)
+
Bulut dashboard'u
+
Bulut dashboard'u
+
Web arayüzü
+
Bulut dashboard'u
+
Hub web arayüzü
+
Hayır
+
Hayır
+
Hayır
+
Hayır
-
Self-hosted
+
Kendi sunucunda barındırma
Evet (varsayılan)
-
İsteğe bağlı
-
İsteğe bağlı
+
Opsiyonel
+
Opsiyonel
Evet
-
Hayır (yalnız bulut)
+
Hayır (yalnızca bulut)
Evet (Docker)
Evet
Evet (Oracle DB)
@@ -448,36 +541,61 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, puan tablosuna bakın) %
-Benchmark notu: yalnızca agentmemory'nin R@5 değeri kendi ölçtüğümüz sonuçtur (LongMemEval-S, benchmark/COMPARISON.md üzerinden yeniden üretilebilir). mem0 ve Letta rakamları kendi yayımladıkları LoCoMo sayılarıdır (farklı bir veri kümesi); MemPalace, supermemory, TencentDB (PersonaMem) ve oracleagentmemory rakamları, bağımsız olarak yeniden üretmediğimiz satıcı beyanlarıdır (oracleagentmemory'nin çalıştırması bir Oracle AI Database'e karşı GPT-5.5 kullandı). Yalnızca kabaca fikir vermesi için yan yana gösterilmiştir, aynı veri üzerinde birebir bir karşılaştırma değildir. Yıldız sayıları yaklaşıktır ve zamanla değişir.
+Benchmark notu: yalnızca agentmemory'nin R@5'i bizim kendi ölçtüğümüz sonuçtur (LongMemEval-S, benchmark/COMPARISON.md'dan yeniden üretilebilir). mem0 ve Letta rakamları, onların yayımladığı LoCoMo sayılarıdır (farklı bir veri kümesi); MemPalace, supermemory, TencentDB (PersonaMem) ve oracleagentmemory rakamları, bağımsız olarak yeniden üretmediğimiz, satıcı tarafından kendi beyan edilen iddialardır (oracleagentmemory'nin çalıştırması bir Oracle AI Database'e karşı GPT-5.5 kullandı). Yalnızca kabaca karşılaştırma için yan yana gösterilmiştir, aynı veri üzerinde doğrudan bir karşılaştırma değildir. Yıldız sayıları yaklaşıktır ve zamanla değişir.
-**Bilinmeye değer daha yeni oyuncular**, derinlemesine karşılaştırma [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) içinde:
+**Bilinmesi gereken daha yeni oyuncular**, [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) içinde derinlemesine karşılaştırılmıştır:
| Sistem | ⭐ | Yaklaşım |
|--------|---|-------|
-| Zep / Graphiti | 30K | Zamansal bilgi grafı; yayımlanmış en güçlü zamansal-sorgu sonuçları (LongMemEval 63.8%), ancak graf asenkron kurulduğundan taze olgular gecikebilir |
-| Cognee | 30K | Dokümandan bilgi grafına ingest, yalnızca Python, oturum yakalama yerine yapılandırılmış entity çıkarımı için tasarlanmış |
+| Zep / Graphiti | 30K | Temporal bilgi grafı; yayımlanmış en güçlü temporal-sorgu sonuçları (LongMemEval 63.8%), ancak graf asenkron olarak oluşturulur, bu yüzden yeni bilgiler gecikebilir |
+| Cognee | 30K | Doküman-to-bilgi-grafı alımı, yalnızca Python, oturum yakalamadan ziyade yapılandırılmış entity çıkarımı için inşa edilmiştir |
-Bunların hiçbiri kodlama-ajanı hook'larından otomatik yakalama yapmaz, yerel-öncelikli bir görüntüleyici sunmaz veya anahtarsız çalışmaz — agentmemory'nin etrafında inşa edildiği kombinasyon budur.
+Bunların hiçbiri kodlama-ajanı hook'larından otomatik yakalama yapmaz, local-first bir görüntüleyici sunmaz veya anahtarsız çalışmaz — agentmemory'nin etrafında inşa edildiği kombinasyon budur.
---
-Uyumluluk: bu sürüm kararlı `iii-sdk` `^0.11.0` ve iii-engine v0.11.x'i hedefler.
+Uyumluluk: bu sürüm `iii-sdk` 0.22.1'i hedefler ve iii-engine v0.22.1'i sabitler.
### 30 saniyede deneyin
```bash
-# Terminal 1: sunucuyu başlatın
-npx @agentmemory/agentmemory
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
-# Terminal 2: örnek veriyi yükleyin ve geri çağırmayı iş başında görün
-npx @agentmemory/agentmemory demo
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest 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.
+`demo`, 3 gerçekçi oturum (JWT auth, N+1 sorgu düzeltmesi, rate limiting) tohumlar (seed) ve bunlara karşı aramalar çalıştırır. Anahtarsız kurulumlar vektörleri devre dışı bırakır, bu yüzden `mem::search` anahtar kelime sorguları BM25 üzerinden eşleşmelidir; `database performance optimization` ise sıfır sonuç döndürebilir. `smart-search`, graf verisi mevcut olduğunda ek olarak yapısal graf eşleşmeleri döndürebilir. Semantik sorgunun N+1 düzeltmesini vektörler üzerinden bulmasını sağlamak için `EMBEDDING_PROVIDER=local` ayarlayın, yeniden başlatın ve ilk model indirmesinin tamamlanmasına izin verin.
+
+Belleğin canlı olarak oluşumunu izlemek için `http://localhost:3113` adresini açın.
-Belleğin canlı oluşumunu izlemek için `http://localhost:3113` adresini açın.
+### Sıfırdan bir kurulumu doğrulayın ve yeniden başlatma kalıcılığını test edin
+
+Sunucu çalışırken REST'i, health'i, görüntüleyiciyi ve iii destekli runtime durumunu doğrulayın:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Başlangıç hazır paneli, dört portun tümünü hesaba katar: 3111'de REST/MCP HTTP, 3112'de iii stream'leri, 3113'te görüntüleyici ve 49134'te iii worker WebSocket'i. `status`, agentmemory sağlığını ve etkin sağlayıcı/embedding modunu doğrular. Bir probe kaydedin ve aranabilir olduğunu doğrulayın:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Ardından `npx -y @agentmemory/agentmemory@latest stop` komutunu çalıştırın, Terminal 1'de standart komutu yeniden başlatın, `/agentmemory/livez`'i bekleyin ve aramayı tekrarlayın. Probe hâlâ döndürülmelidir. Özel bir `--data-dir` seçtiyseniz, yeniden başlatmada aynı dizini geçirin.
### Günlük komutlar
@@ -485,7 +603,7 @@ Kurulum ve ayarlar yukarıdaki [Kurulum](#install) bölümünde (ilk çalıştı
```bash
agentmemory # start the server
-agentmemory stop # tear it down
+agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -493,41 +611,43 @@ agentmemory remove # uninstall everything we created
### 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.5x ila 4x) ve klavye kısayollarıyla (boşluk geçiş, oklar adım atlama) ayrı olaylar olarak görüntülenir.
+agentmemory'nin kaydettiği her oturum tekrar oynatılabilir. Görüntüleyiciyi açın, **Replay** sekmesini seçin ve zaman çizelgesinde gezinin: prompt'lar, tool çağrıları, tool sonuçları ve yanıtlar; play/pause, hız kontrolü (0.5x - 4x) ve klavye kısayolları (açıp kapatmak için boşluk, adım adım ilerlemek için ok tuşları) ile ayrık olaylar olarak render edilir.
-Daha eski Claude Code JSONL kayıtlarını içeri aktarmak için:
+Daha eski Claude Code JSONL transkriptlerini içeri aktarmak için:
```bash
-# Varsayılan ~/.claude/projects altındaki her şeyi içeri aktar
-npx @agentmemory/agentmemory import-jsonl
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
-# Veya tek bir dosya içeri aktar
-npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest 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. İçeri aktarılan her transkript arama için indekslenir, `import` köken kanalıyla damgalanır ve bir oturum kristali ile dersler için madenden geçirilir.
+İçe aktarılan oturumlar, Replay seçicisinde yerli (native) oturumların yanında görünür. Arka planda her giriş, yan kanal sunucu olmadan `mem::replay::load`, `mem::replay::sessions` ve `mem::replay::import-jsonl` iii fonksiyonları üzerinden yönlendirilir. İçe aktarılan her transkript arama için indekslenir, `import` köken kanalıyla damgalanır ve bir oturum kristali ile dersler için madenden geçirilir.
+
+> **`import-jsonl`'u birincil yakalama yolunuz olarak kullanıyorsanız dikkat:** Claude Code'un `cleanupPeriodDays`'i (`~/.claude/settings.json` içinde, varsayılan **30**), bu pencereden daha eski JSONL transkriptlerini `~/.claude/projects/` dizininden otomatik olarak siler. agentmemory'yi aylar öncesine dayanan bir Claude Code geçmişine sıfırdan kurarsanız, 30 günden daha eski her şey ilk içe aktarmadan önce zaten silinmiş olur. `import-jsonl`'u bir cron üzerinde çalıştırın, `cleanupPeriodDays`'i daha yüksek bir değere çıkarın veya otomatik yakalama hook'larını bağlayın (varsayılan eklenti kurulum yolu) ki her turn, oturum canlıyken agentmemory'ye düşsün ve JSONL temizliği önemini kaybetsin.
### Yükseltme / Bakım
-Yerel runtime'ınızı bilinçli olarak güncellemek istediğinizde bakım komutunu kullanın:
+Yerel runtime'ınızı kasıtlı olarak güncellemek istediğinizde bakım komutunu kullanın:
```bash
-npx @agentmemory/agentmemory upgrade
+npx -y @agentmemory/agentmemory@latest upgrade
```
-Uyarı: bu komut mevcut çalışma alanını/runtime'ı değiştirir. JavaScript bağımlılıklarını güncelleyebilir ve sabitlenmiş `iiidev/iii:0.11.2` Docker imajını çekebilir. Asla sabitlenmemiş ya da daha yeni bir iii motoru kurmaz.
+Uyarı: bu komut mevcut workspace/runtime'ı değiştirir. JavaScript bağımlılıklarını güncelleyebilir ve sabitlenmiş `iiidev/iii:0.22.1` Docker imajını çekebilir. Asla sabitlenmemiş veya daha yeni bir iii engine kurmaz.
-Uygulama detayları `src/cli.ts` içinde (`src/cli.ts:544-595` bölgesi civarında `runUpgrade`'a bakın).
+Uygulama detayları `src/cli.ts` içinde yaşar (`src/cli.ts:544-595` bölgesindeki `runUpgrade`'e 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, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### 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.
+agentmemory'nin MCP sunucusunu `/plugin install` kullanmak yerine doğrudan `~/.claude.json` üzerinden bağlarsanız, Claude Code `${CLAUDE_PLUGIN_ROOT}`'u asla çözümlemez ve hook scriptlerini `~/.claude/settings.json` içinde absolute path'lere yöneltmeniz gerekir. Bu path'ler genellikle agentmemory sürümünü gömer (örn. `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), bu yüzden bir sonraki yükseltme her hook'u sessizce bozar.
Geçici çözüm:
@@ -535,45 +655,59 @@ Geçici çözüm:
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.
+Bu, aynı hook komutlarını, şu anda kurulu olan `@agentmemory/agentmemory` paketinin paketlenmiş `plugin/` dizinine çözümlenen absolute path'lerle `~/.claude/settings.json` içine birleştirir. Path'leri yenilemek için agentmemory'yi yükselttikten sonra komutu yeniden çalıştırın. Aynı dosyadaki kullanıcı girdileri korunur; yalnızca önceki agentmemory girdileri değiştirilir. `/plugin install` yolunu kullanmak, önerilen yaklaşım olmayı sürdürür.
+Uzak veya korumalı dağıtımlar için Claude Code'u `AGENTMEMORY_URL` ve `AGENTMEMORY_SECRET` ayarlanmış şekilde başlatın. Eklenti, her iki değeri de paketlenmiş MCP sunucusuna iletir; `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
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
-# 2. agentmemory marketplace'i kaydedin ve eklentiyi kurun
+# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```
-Codex eklentisi, Claude Code eklentisiyle aynı `plugin/` dizininden gelir. Şunları kaydeder:
+Codex eklentisi, Claude Code eklentisiyle aynı `plugin/` dizininden gönderilir. Şunları kaydeder:
-- `@agentmemory/mcp` MCP sunucusu olarak (`AGENTMEMORY_URL` çalışan bir agentmemory sunucusuna işaret ettiğinde tüm 54 tool'u proxy yapar; erişilebilir sunucu yoksa yerel olarak 7 tool'a düşer)
+- Çalışan daemon'a giden, npm indirmesi veya fallback store gerektirmeyen paketlenmiş bir stdio MCP bridge. Yayınlanmamış bir build'i test etmek için [yerel Codex kılavuzuna](../docs/plugins/codex-local.md) bakın.
- 6 yaşam döngüsü hook'u: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
-- 9 çağrılabilir skill: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`; artı ajanın gerektiğinde yüklediği 8 referans skill'i (memory discipline, MCP tool'ları, REST API, yapılandırma, ajanlar, hook'lar, mimari ve skill yazım kılavuzu)
+- 9 çağrılabilir (invocable) skill: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, ve ajanın gerektiğinde yüklediği 8 referans skill (bellek disiplini, MCP tool'ları, REST API, yapılandırma, ajanlar, hook'lar, mimari ve skill yazma kılavuzu)
-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'in hook engine'i, hook subprocess'lerine `CLAUDE_PLUGIN_ROOT`'u enjekte eder ([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)'a göre), bu yüzden aynı hook scriptleri her iki host'ta da kopyalama olmadan çalışır. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure olayları yalnızca Claude Code'a özgüdür ve Codex için kaydedilmez.
-#### Codex Desktop: eklenti hook'ları şu anda sessiz (geçici çözüm mevcut)
+#### Codex hook güveni ve uyumluluk
-`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.
+Native eklenti hook dispatch'i Codex CLI 0.150.1 ile doğrulanmıştır. Yakalama beklemeden önce eklenti hook'larına güvenin. Codex Desktop davranışı, paketlenmiş runtime'ına bağlıdır; bir geçici çözüm etkinleştirmeden önce `/hooks`'u kontrol edin ve yakalanan bir olayı doğrulayın.
-Düzeltme upstream'e iner inmez, aynı hook komutlarını global `~/.codex/hooks.json` içine yansıtın:
+Host'unuz global hook'lar gerektiriyorsa, komutları `~/.codex/hooks.json` içine yansıtın. MCP zaten bağlıysa, mevcut connector'ın hook kurulumuna ulaşması için `--force` gerekir:
```bash
-agentmemory connect codex --with-hooks
+agentmemory connect codex --with-hooks --force
```
-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.
+Bu, global hook'ları birleştirir ve agentmemory MCP girdisini yeniden yazarken ilgisiz girdileri korur. `--force` kullanmadan önce özel agentmemory endpoint ayarlarınızı gözden geçirin. Script path'lerini yenilemek için yükseltme sonrasında yeniden çalıştırın. Çift yakalamayı önlemek için native eklenti hook'larını veya global kopyaları etkinleştirin, ikisini birden değil.
+
+### GitHub Copilot CLI
+
+VS Code agent modu için [Copilot MCP ve otomatik yakalama kılavuzuna](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions) bakın. CLI connector'ı VS Code'u yapılandırmaz.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatif olarak, GitHub alt dizininden tam hook/skill eklentisi
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli`, `mcpServers.agentmemory`'i `~/.copilot/mcp-config.json` içine (veya `COPILOT_HOME` ayarlandığında `$COPILOT_HOME/mcp-config.json` içine) birleştirir ve mevcut sunucuları korur. Yerel Windows'ta bu, otomatikleştirilmiş tek `connect` adaptörüdür; diğer tüm yerel Windows ajanlarını manuel olarak yapılandırın. WSL `connect`, yalnızca hedef ajan aynı WSL ortamında kuruluysa desteklenir. Copilot, MCP sunucusunu bir sonraki başlatmada veya `/mcp`'den sonra alır. Tam hook/skill deneyimini istediğinizde eklentiyi de kurun.
-OpenClaw (bu istemi yapıştırın)
+OpenClaw (bu prompt'u yapıştırın)
```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 54 memory tools:
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
@@ -595,10 +729,10 @@ Tam kılavuz: [`integrations/openclaw/`](../integrations/openclaw/)
-Hermes Agent (bu istemi yapıştırın)
+Hermes Agent (bu prompt'u yapıştırın)
```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 54 memory tools:
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
@@ -617,11 +751,11 @@ Tam kılavuz: [`integrations/hermes/`](../integrations/hermes/)
### Diğer ajanlar
-Bellek sunucusunu başlatın: `npx @agentmemory/agentmemory`
+Bellek sunucusunu başlatın: `npx -y @agentmemory/agentmemory@latest`
#### `npx skills add` ile yerel skill'ler (50+ ajan)
-agentmemory, Claude-Code-tarzı `/SKILL.md` formatında 17 skill sunar: 9 çağrılabilir aksiyon skill'i (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) ve ajanın gerektiğinde yüklediği 8 referans skill'i (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referans skill'leri kaynaktan üretilen veri tabloları taşır, bu yüzden asla sapmazlar. vercel-labs'ın [`skills`](https://npmjs.com/package/skills) CLI'si bunları 50+ ajanda (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf ve daha fazlası) çağıran ajanın yerel skill dizinine otomatik olarak kurar:
+agentmemory, Claude-Code-tarzı `/SKILL.md` formatında 17 skill sunar: 9 çağrılabilir aksiyon skill'i (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) ve ajanın gerektiğinde yüklediği 8 referans skill (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Referans skill'ler, kaynaktan üretilen veri tablolarını taşır, bu yüzden asla sapmazlar. vercel-labs'ın [`skills`](https://npmjs.com/package/skills) CLI'si, bunları çağıran ajanın yerel skill dizinine 50+ ajanda (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf ve daha fazlası) otomatik olarak kurar:
```bash
npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
@@ -629,16 +763,16 @@ npx skills add rohitg00/agentmemory -y -a warp # explicit agent
npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
```
-Bu, `agentmemory connect ` ile **tamamlayıcıdır**:
+Bu, `agentmemory connect `'ı **tamamlayıcı** niteliktedir:
-- `agentmemory connect ` MCP sunucu yapılandırmasını yazar, böylece tool'lar kullanılabilir olur.
-- `npx skills add rohitg00/agentmemory` skill'leri kurar, böylece ajan onları ne zaman çağıracağını bilir.
+- `agentmemory connect `, tool'ların kullanılabilir olması için MCP sunucu yapılandırmasını yazar.
+- `npx skills add rohitg00/agentmemory`, ajanın onları ne zaman çağıracağını bilmesi için skill'leri kurar.
-skills CLI'sinin henüz kapsamadığı az sayıdaki ajan için (Zed v1.3.x ve altı), 17 SKILL.md dosyasını ajanın yerel skill dizinine kendiniz bırakın; aynı format her yerde çalışır.
+skills CLI'sinin henüz kapsamadığı birkaç ajan için (Zed v1.3.x ve altı), 17 SKILL.md dosyasını ajanın yerel skill dizinine kendiniz bırakın; aynı format her yerde çalışır.
#### Standart MCP bloğu
-agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw) **aynı MCP sunucu bloğudur**:
+agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw) **aynı MCP sunucu bloğu**dur:
```json
"agentmemory": {
@@ -651,44 +785,46 @@ agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude
}
```
-**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.
+**Bu girdiyi, host'un yapılandırma dosyasındaki mevcut `mcpServers` nesnesine birleştirin**; dosyayı değiştirmeyin (replace). Dosyada zaten başka sunucular varsa, `agentmemory`'yi `mcpServers` içine başka bir key olarak onların yanına ekleyin. `mcpServers` tamamen eksikse, bloğu `{ "mcpServers": { ... } }` içine yapıştırın. `${VAR}` placeholder'ları, MCP-sunucu başlatıldığında `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`'ı shell'den devralır; ayarlanmamış değişkenler boş string geçirir ve shim, `http://localhost:3111`'e düşer. Bağlanmış tek bir girdi, hem yerel hem de uzak (k8s / reverse-proxied) 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. |
+| **Cursor (yalnızca MCP)** | `~/.cursor/mcp.json` | `mcpServers`'a birleştirin veya `agentmemory connect cursor`. Web sitesinde tek tıkla deeplink de mevcuttur. |
+| **Cursor (tam eklenti)** | `.cursor-plugin/` | Cursor Marketplace listesi (başvuru incelemede) veya Cursor Settings → Plugins → yerel checkout. 7 otomatik yakalama hook'u (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + MCP sunucusunu kaydeder; `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`, Cursor'un eklenti dashboard'unda yönetilir. Cursor IDE'de ve `cursor-agent` CLI'sinde çalışır; CLI print-mode prompt'ları, oturum sonunda oturum transkriptinden geriye doldurulur (backfill). |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers`'a birleştirin. Düzenledikten sonra Claude Desktop'ı yeniden başlatın. |
| **Cline / Roo Code / Kilo Code** | Cline MCP ayarları (Settings UI → MCP Servers → Edit) | Aynı `mcpServers` bloğu. |
-| **Devin CLI** | `~/.config/devin/config.json` | `agentmemory connect devin` MCP girdisini birleştirir; `--with-hooks` Devin'in küçük harfli araç matcher'larıyla altı yerel otomatik yakalama hook'u (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) ekler. `devin mcp list` ve devin içinde `/hooks` ile doğrulayın. |
-| **Devin (bulut)** | Settings → Connections → MCP servers | Özel MCP (STDIO) ekleyin: command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` ağdan erişilebilir bir agentmemory dağıtımına ve `AGENTMEMORY_SECRET` (bulut oturumları localhost'a erişemez — bkz. [`deploy/`](../deploy/)). |
+| **Devin CLI (MCP + hook'lar)** | `~/.config/devin/config.json` | `agentmemory connect devin`, MCP girdisini birleştirir; `--with-hooks`, Devin'in küçük harfli tool matcher'larıyla altı yerel otomatik yakalama hook'u (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) ekler. `devin mcp list` ile ve devin içinde `/hooks` ile doğrulayın. |
+| **Devin CLI (tam eklenti)** | `plugin/.devin-plugin/` | Bir checkout'tan `devin plugins install ./plugin`, 17 skill'in tümünü `/agentmemory:` slash komutları olarak ve MCP sunucusunu kaydeder. Devin eklenti hook'ları `SessionStart`/`SessionEnd`'i tetikleyemez, bu yüzden tam oturum yakalaması için bunu `connect devin --with-hooks` ile eşleştirin. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Özel bir MCP (STDIO) ekleyin: komut `npx`, args `-y @agentmemory/mcp@latest`, env olarak ağ üzerinden erişilebilir bir agentmemory dağıtımına işaret eden `AGENTMEMORY_URL` ve `AGENTMEMORY_SECRET` (cloud oturumları localhost'a erişemez — bkz. [`deploy/`](../deploy/)). Secret'ı Devin Secrets içinde saklayın, ardından 54 tool'un tümünün göründüğünü doğrulamak için "Test listing tools"u kullanın. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (otomatik birleştirir). |
-| **GitHub Copilot CLI (yalnız MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` `mcpServers.agentmemory`'yi birleştirir; Copilot bunu bir sonraki başlatmada veya `/mcp` ile alır. |
-| **GitHub Copilot CLI (tam eklenti)** | Copilot eklenti kurulumu | GitHub alt dizinindeki eklenti için `copilot plugin install rohitg00/agentmemory:plugin`. |
-| **OpenClaw** | OpenClaw MCP yapılandırması | Aynı `mcpServers` bloğu. Daha derin: `openclaw plugins install ./integrations/openclaw` OpenClaw'ın bellek slot'unu devralır (`memory-core`'dan otomatik geçiş yapar); `plugins.entries.agentmemory.hooks.allowConversationAccess=true` ayarlayın, yoksa tur yakalama sessizce engellenir. Bkz. [`integrations/openclaw`](integrations/openclaw/). |
-| **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) + 17 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. Proje ataması oturum başınadır; bu yüzden birden çok depoya yayılan tek bir OpenCode süreci her oturumu kendi projesi altına dosyalar. İ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` | `agentmemory connect pi` paketli uzantıyı pi'nin otomatik keşif dizinine kurar (ajan başlangıcında recall, ajan bitişinde yakalama, `memory_search` / `memory_save` / `memory_health` tool'ları, `/agentmemory-status`). Çalışan bir pi'de `/reload` bunu alır. [`integrations/pi`](../integrations/pi/) aynı zamanda bir pi paketidir (bir checkout içinden `pi install ./integrations/pi`). |
-| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory`, 6 hook'lu bellek sağlayıcısını etkinleştirir (ön yükleme, tur yakalama, oturum sonu, ön sıkıştırma, MEMORY.md yansıtma, sistem promptu bloğu). `hermes plugins doctor` ve `hermes memory status` ile doğrulayın. Bkz. [`integrations/hermes`](integrations/hermes/). |
-| **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. |
-| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli`. `agy` CLI'si kendi yapılandırmasını, yukarıdaki Antigravity IDE'den ayrı olarak `~/.gemini/` altında tutar. `~/.gemini/config/hooks.json` üzerinden yerel otomatik yakalama için `--with-hooks` geçin. |
-| **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. |
-| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` standart `mcpServers` bloğunu yazar. Warp ayrıca `.claude/skills/` içinden skill'leri otomatik keşfeder; Claude Code eklentisi kurulduktan sonra 8 agentmemory skill'i (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) Warp'ın slash-komut paletinde yerel olarak görünür. |
-| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` standart `mcpServers` bloğunu yazar. VS Code uzantısı kullanıcıları: aynı bloğu Cline Settings → MCP Servers → Edit JSON üzerinden yapıştırın. |
-| **Continue.dev** | `~/.continue/config.yaml` (tercih edilen) veya `config.json` (eski) | `agentmemory connect continue` ikisi de yoksa `config.yaml`'ı sıfırdan oluşturur veya mevcut `config.json`'ı değiştirir. **Zaten bir `config.yaml`'ınız varsa** adaptör `mcpServers:` altına yapıştırılacak bloğu aynen yazdırır; yorumları ve anchor'ları güvenle korumak paketin içermediği bir YAML parser gerektirdiğinden yaml'ınızı sessizce yeniden yazmaz. Continue `mcpServers` için dizi formu (nesne değil) kullanır. |
-| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` `context_servers` altına yazar (Zed'in anahtarı, `mcpServers` DEĞİL). Uzak MCP sunucuları bunun yerine `{"url": "..."}` ile bağlanabilir. |
-| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` standart `mcpServers` bloğunu yazar. Proje kapsamlı override'lar `/.factory/mcp.json`'a gider. Yerel otomatik yakalama için `--with-hooks` geçin. |
-| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh`, her Harness profilinin yüklediği ev-seviyesi patch katmanına bir `@deepseek-ai/dsh-mcp-client` satırı ekler; tool'lar `mcp__agentmemory__*` olarak kaydolur. Otomatik yakalamayı da bağlamak için `--with-hooks` geçin: paketli Claude Code hook scriptleri, `$DSH_HOME/agentmemory.hooks.json`'a yazılan bir manifest aracılığıyla Harness'ın birinci taraf `@deepseek-ai/dsh-hooks-claude-code` köprüsü üzerinden çalışır (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop). `DSH_HOME` ayarsızken varsayılan `~/.dsh`'tir. |
-| **Goose** | Goose MCP ayarları UI | Aynı `mcpServers` bloğu; `goose configure` → Add Extension → MCP kullanın. `~/.config/goose/config.yaml`'da doğrudan YAML düzenleme desteklenir ancak şema `extensions:` + `cmd` kullanır (`mcpServers:` + `command` değil). |
-| **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).
+| **GitHub Copilot CLI (yalnızca MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli`, `mcpServers.agentmemory`'i birleştirir; Copilot bunu bir sonraki başlatmada veya `/mcp`'den sonra alır. |
+| **GitHub Copilot CLI (tam eklenti)** | Copilot eklenti kurulumu | GitHub alt dizininden eklenti için `copilot plugin install rohitg00/agentmemory:plugin`. |
+| **OpenClaw** | OpenClaw MCP yapılandırması | Aynı `mcpServers` bloğu. Daha derin entegrasyon: `openclaw plugins install ./integrations/openclaw`, OpenClaw'ın bellek slot'unu talep eder (`memory-core`'dan otomatik geçer); `plugins.entries.agentmemory.hooks.allowConversationAccess=true` ayarlayın, aksi halde turn yakalama sessizce bloklanır. Bkz. [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (yalnızca 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'i | `codex plugin marketplace add rohitg00/agentmemory`, ardından `codex plugin add agentmemory@agentmemory`. MCP + 6 yaşam döngüsü hook'u + 17 skill kaydeder. Host'unuzda hook'lara güvenin ve yakalamayı doğrulayın; bkz. [Codex kurulumu ve doğrulaması](../docs/plugins/codex-local.md). |
+| **OpenCode (yalnızca MCP)** | `opencode.json` | Farklı bir şekil: üst seviye `mcp` key'i, dizi olarak komut: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (tam eklenti)** | `plugin/opencode/` | Oturum yaşam döngüsünü, mesajları, tool'ları, hataları kapsayan 22 otomatik yakalama hook'u. Proje attribution'ı oturum başınadır, bu yüzden birden fazla repository'ye yayılan tek bir OpenCode süreci, her oturumu kendi projesi altında dosyalar. İki slash komutu (`/recall`, `/remember`). `plugin/opencode/`'u OpenCode workspace'inize kopyalayın ve eklenti girdisini `opencode.json`'a ekleyin. Tam hook tablosu + boşluk analizi için [`plugin/opencode/README.md`](../plugin/opencode/README.md)'a bakın. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi`, paketlenmiş eklentiyi pi'nin otomatik keşif dizinine kurar (ajan başlangıcında recall, ajan sonunda yakalama, `memory_search` / `memory_save` / `memory_health` tool'ları, `/agentmemory-status`). Çalışan bir pi'de `/reload` bunu alır. [`integrations/pi`](../integrations/pi/), aynı zamanda bir pi paketidir (bir checkout'tan `pi install ./integrations/pi`). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory`, 6-hook'lu bellek sağlayıcısını verir (prefetch, turn yakalama, oturum sonu, pre-compress, MEMORY.md mirroring, sistem prompt bloğu). `hermes plugins doctor` ve `hermes memory status` ile doğrulayın. Bkz. [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen`, standart `mcpServers` bloğunu yazar. Hook payload'u Claude Code ile alan uyumludur (field-compatible), bu yüzden mevcut 12-hook'lu scriptler değişiklik yapılmadan çalışır; bunları aynı `settings.json` içindeki `hooks` bölümü üzerinden bağlayın. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks`, paylaşılan customization dizinine MCP ve yakalama hook'larını kurar. Bkz. [Antigravity kurulumu ve sınırları](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks`, güncel IDE sürümleriyle aynı MCP ve hook yapılandırmasını kullanır. Mevcut kurulumlar `--force` ile yenilenmelidir; bkz. [yükseltme notları](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro`, kullanıcı seviyesindeki yapılandırmayı yazar. Workspace geçersiz kılmaları, kodunuzun yanındaki `.kiro/settings/mcp.json` içine gider. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp`, standart `mcpServers` bloğunu yazar. Warp, ayrıca `.claude/skills/`'ten skill'leri otomatik keşfeder; Claude Code eklentisi kurulduğunda 8 agentmemory skill'i (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`), Warp'ın slash-komut paletinde yerli olarak görünür. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline`, standart `mcpServers` bloğunu yazar. VS Code eklenti kullanıcıları: aynı bloğu Cline Settings → MCP Servers → Edit JSON üzerinden yapıştırın. |
+| **Continue.dev** | `~/.continue/config.yaml` (tercih edilen) veya `config.json` (eski/legacy) | `agentmemory connect continue`, ikisi de yoksa `config.yaml`'ı sıfırdan oluşturur veya mevcut `config.json`'u değiştirir. **Zaten bir `config.yaml`'ınız varsa**, adaptör `mcpServers:` altına yapıştırılacak tam bloğu yazdırır; yaml'ınızı sessizce yeniden yazmaz, çünkü yorumları ve anchor'ları güvenle korumak, paketin birlikte gelmediği bir YAML parser'ı gerektirir. Continue, `mcpServers` için dizi biçimini (nesne değil) kullanır. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed`, `context_servers` altına yazar (Zed'in key'i, `mcpServers` DEĞİL). Uzak MCP sunucuları, bunun yerine `{"url": "..."}` üzerinden bağlanabilir. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid`, standart `mcpServers` bloğunu yazar. Proje kapsamlı geçersiz kılmalar `/.factory/mcp.json` içine gider. Yerel otomatik yakalama için `--with-hooks` geçirin. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh`, her Harness profilinin yüklediği ev-seviyesi (home-level) patch katmanına bir `@deepseek-ai/dsh-mcp-client` satırı ekler; tool'lar `mcp__agentmemory__*` olarak kaydolur. Otomatik yakalamayı da bağlamak için `--with-hooks` geçirin: paketlenmiş Claude Code hook scriptleri, `$DSH_HOME/agentmemory.hooks.json`'a yazılan bir manifest aracılığıyla Harness'ın birinci taraf `@deepseek-ai/dsh-hooks-claude-code` köprüsü üzerinden çalışır (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop). `DSH_HOME` ayarsızken varsayılan olarak `~/.dsh` kullanılır. |
+| **Goose** | Goose MCP ayarları arayüzü | Aynı `mcpServers` bloğu; `goose configure` → Add Extension → MCP kullanın. `~/.config/goose/config.yaml`'da doğrudan YAML düzenleme desteklenir, ancak şema `extensions:` + `cmd` kullanır (`mcpServers:` + `command` değil). |
+| **Aider** | yok | REST API ile doğrudan konuşun: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Herhangi bir ajan (32+)** | yok | `npx skillkit install agentmemory`, host'u otomatik algılar ve birleştirir. |
+
+Host'un `localhost`'una erişemeyen **sandboxlanmış MCP istemcileri** (Flatpak / Snap / kısıtlayıcı container'lar) için: `env` bloğunda ayrıca `"AGENTMEMORY_FORCE_PROXY": "1"` ayarlayın ve `AGENTMEMORY_URL`'i sandbox'ın gerçekten erişebileceği bir rotaya (örn. LAN IP'niz) işaret edin.
### 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 gerekmez.
+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 gerekmez.
```bash
pip install iii-sdk # Python
@@ -708,7 +844,7 @@ iii.trigger({
})
```
-Ç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.
+Çalışan örnek: [`examples/python/`](../examples/python/) (quickstart + gözlem/recall akışı). `:3111` üzerindeki REST, iii runtime'ı olmayan host'lar için kullanılabilir olmayı sürdürür.
### Kaynaktan
@@ -717,116 +853,108 @@ 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.
+Bu, sabitlenmiş binary zaten kuruluysa agentmemory'yi yerel bir `iii-engine` ile başlatır, veya seçildiğinde Docker Compose kullanır. REST, stream'ler ve görüntüleyici, varsayılan olarak `127.0.0.1`'e bağlanır. Otomatik macOS/Linux binary yolu, `curl`, bir POSIX `sh` ve `tar` gerektirir.
-`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=` ile override edin.
+`iii-engine`'i manuel olarak kurun. **agentmemory şu anda `iii-engine`'i `v0.22.1`'e sabitler**, bu `iii-sdk` bağımlılığıyla aynı sürümdür; worker, bu engine'in wire protokolünü konuşur ve 0.20.0, SDK yüzeyini yeniden düzenledi, bu yüzden ikisi agentmemory sürümlerinde birlikte hareket eder. Kendi engine'inizi çalıştırıyorsanız ve eşleştiğini biliyorsanız `AGENTMEMORY_III_VERSION=` ile geçersiz kılın.
-- **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 arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** `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
+- **Windows:** [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1)'den `iii-x86_64-pc-windows-msvc.zip`'i indirin ve `iii.exe`'yi `%USERPROFILE%\.agentmemory\bin\iii.exe`'ye çıkarın
+
+Her arşivin release sayfasında eşleşen bir `.sha256` dosyası vardır; platformu değiştirdiğinizde, yukarıdaki kontrolde o dosyanın hash'ini kullanın (Windows'ta: `Get-FileHash`). `npx @agentmemory/agentmemory` içindeki otomatik installer, bu hash'leri sabitler ve eşleşmeyen bir arşivi reddeder.
-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).
+Veya Docker kullanın (paketlenmiş `docker-compose.yml`, `iiidev/iii:0.22.1`'i çeker). Tam dokümantasyon: [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:
+agentmemory, Windows 10/11'de çalışır, ancak yalnızca Node.js paketi yeterli değildir; ayrıca arka plan süreci olarak sabitlenmiş iii-engine v0.22.1 runtime'ına da ihtiyacınız vardır. CLI, Windows ZIP'ini otomatik olarak çıkarmaz, bu yüzden yerel Windows kullanıcıları `iii.exe`'yi manuel olarak kurmalı, WSL2 kullanmalı veya Docker Desktop'ı seçmelidir.
-**Seçenek A: önceden derlenmiş Windows ikiliği (önerilen)**
+Yerel Windows'ta otomatikleştirilmiş MCP bağlama, yalnızca `agentmemory connect copilot-cli`'yi destekler. Claude Code, Codex, Cursor ve diğer tüm yerel Windows ajanları için, [Diğer ajanlar](#other-agents) bölümündeki manuel MCP bloğunu o ajanın Windows yapılandırmasına kopyalayın. WSL içinde `connect` çalıştırmak, yalnızca hedef ajan aynı WSL ortamında da kuruluysa uygundur; bir Windows-host ajanının yapılandırmasını düzenlemez.
+
+**Seçenek A: önceden derlenmiş (prebuilt) Windows binary (ö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
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
```
**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
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
```
-**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:
+**Seçenek C: yalnızca bağımsız MCP (engine olmadan).** Ajanınız için yalnızca MCP tool'larına ihtiyacınız varsa ve REST API'ye, görüntüleyiciye veya cron job'larına gerek yoksa, engine'i tamamen atlayın:
```powershell
-npx -y @agentmemory/agentmemory mcp
-# veya shim paketi üzerinden:
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
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:
+**Windows için diagnostik:** `npx -y @agentmemory/agentmemory@latest` başarısız olursa, gerçek engine stderr'ini görmek için `--verbose` ile yeniden çalıştırın. Yaygın hata modları:
-| Belirti | Düzeltme |
+| Belirti | Çözüm |
|---|---|
-| `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 |
+| `The engine process started but the REST API never responded.` | Türetilen dört portun da boş olduğunu doğrulayın, sabitlenmiş `iii.exe`'nin hayatta kaldığını kontrol edin, ardından `--verbose` ile yeniden çalıştırın ve yakalanan engine stderr'ini inceleyin |
| `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 ` kullanın |
-| Docker kurulu olsa bile Docker fallback atlanıyor | Docker Desktop'ın gerçekten çalıştığından emin olun (sistem tepsisi simgesi) |
+| Port çatışması | Neyin bağlı olduğunu görmek için `netstat -ano \| findstr :3111`, ardından onu sonlandırın veya `--port ` kullanın |
+| Docker kurulu olsa bile Docker fallback'i atlanıyor | Docker Desktop'ın gerçekten çalıştığından emin olun (sistem tepsisi simgesi) |
-> Not: iii **motoru** önceden derlenmiş bir ikiliktir, bir cargo crate'i değildir, bu yüzden onu `cargo install` ile kurmaya çalışmayın. (iii **SDK'ları** crates.io, npm ve PyPI'de yayımlanmıştır, ancak agentmemory bunlara ihtiyaç duymaz.) Desteklenen motor kurulum yöntemleri, hepsi v0.11.2'ye sabitlenmiştir: yukarıdaki önceden derlenmiş v0.11.2 ikiliği, sürüm sabitlemesi **ile** upstream `sh` kurulum scripti `curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh` (macOS/Linux) ve Docker imajı `iiidev/iii:0.11.2`. Yalın bir `install.sh | sh`, agentmemory'nin desteklemediği **en son** motoru kurar; her zaman `VERSION=0.11.2` geçirin. Hepsinden kolayı: sadece `npx @agentmemory/agentmemory` çalıştırın; bu, sabitlenmiş motoru sizin için `~/.agentmemory/bin` dizinine indirir.
+> Not: iii **engine**'i önceden derlenmiş bir binary'dir, bir cargo crate değildir, bu yüzden onu `cargo install` ile kurmaya çalışmayın. (iii **SDK'ları** crates.io, npm ve PyPI'de yayımlanır, ancak agentmemory bunlara ihtiyaç duymaz.) Desteklenen engine kurulum yöntemlerinin tümü v0.22.1'e sabitlenmiştir: yukarıdaki önceden derlenmiş binary, agentmemory'nin macOS/Linux otomatik kurulum yolu (`curl`, POSIX `sh` ve `tar` gereklidir) ve Docker imajı `iiidev/iii:0.22.1`. Düz bir upstream `install.sh | sh`, agentmemory'nin desteklemediği en son engine'i kurar. `npx -y @agentmemory/agentmemory@latest` kullanın; macOS/Linux'ta sabitlenmiş engine'i `~/.agentmemory/bin` içine getirir.
---
Deploy
-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.
+Yönetilen host'lar için tek tıkla şablonlar. Her biri, npm'den `@agentmemory/agentmemory`'i çeken ve iii engine binary'sini resmi `iiidev/iii` Docker Hub imajından kopyalayan kendi kendine yeten (self-contained) bir Dockerfile gönderir; önceden derlenmiş bir agentmemory imajı gerekmez. Kalıcı depolama `/data`'ya mount edilir; ilk-boot entrypoint'i, npm ile paketlenmiş iii yapılandırmasını (`127.0.0.1`'e bağlanan) `0.0.0.0`'a bağlanan ve absolute `/data` path'leri kullanan, HMAC secret'ını üreten, dağıtıma özel (deploy-tuned) bir yapılandırmayla değiştirir; ardından agentmemory CLI'sini exec etmeden önce `gosu` üzerinden `root`'tan `node`'a ayrıcalıkları düşürür.
-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.
+Render'ın tek tıkla deploy butonu, repository root'unda bir `render.yaml` gerektirir; bunu kasıtlı olarak temiz tutuyoruz. Repo 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:
+Tam kurulum detayları (HMAC yakalama, görüntüleyici SSH tüneli, rotasyon, yedekleme,
+maliyet tabanları) [`deploy/`](.././deploy/README.md) içinde yaşar:
-- [`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ışı,
+- [`deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"` ile tek
+ makine; en ucuz boşta kalma (idle).
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby plan sabit ücret,
+ dashboard'da 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.
+- [`deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted) ile kendi
+ VPS'inizde self-hosted; aynı Docker Compose stack'i, host'a ve veriye siz sahip olursunuz.
-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.
+Yalnızca port `3111` yayımlanır. `3113`'teki görüntüleyici container içinde
+loopback'e bağlı kalır; her şablonun README'si, ona erişmek için
+SSH-tüneli desenini belgeler.
---
-Her kodlama ajanı, oturum sona erdiğinde her şeyi unutur ve her yeni oturum, yığınınızı yeniden anlatmanızla başlar. agentmemory arka planda çalışır ve bu adımı ortadan kaldırır.
+Her kodlama ajanı, oturum sona erdiğinde her şeyi unutur ve her yeni oturum, stack'inizi yeniden açıklamanızla başlar. agentmemory arka planda çalışır ve bu adımı kaldırır.
```text
Session 1: "Add auth to the API"
@@ -844,15 +972,15 @@ Session 2: "Now add rate limiting"
### 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.
+Her AI kodlama ajanı, yerleşik bellekle gelir: Claude Code'da `MEMORY.md`, Cursor'da notepad'ler, Cline'da memory bank vardır. Bunlar yapışkan not (sticky note) gibi çalışır. agentmemory, yapışkan notların arkası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 |
+| Arama | Her şeyi bağlama yükler | BM25 + vektör + graf (yalnızca top-K) |
+| Token maliyeti | 240 gözlemde 22K+ | ~1,900 token (92% daha az) |
+| Ajanlar arası | Ajan başına dosyalar | MCP + REST (herhangi bir ajan) |
+| Koordinasyon | Yok | Lease'ler, signal'ler, action'lar, routine'ler |
| Gözlemlenebilirlik | Dosyaları manuel okuma | :3113'te gerçek zamanlı görüntüleyici |
---
@@ -866,9 +994,10 @@ 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
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
@@ -884,28 +1013,28 @@ SessionStart hook fires
### 4 Katmanlı Bellek Konsolidasyonu
-İnsan beyninin belleği nasıl işlediği örnek alınmıştır; uyku konsolidasyonu da buna dahil.
+İnsan beyninin belleği nasıl işlediğine (uyku konsolidasyonu dahil) göre modellenmiştir.
| 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" |
+| **Working (Çalışma)** | Tool kullanımından ham gözlemler | Kısa süreli bellek |
+| **Episodic (Olaysal)** | Sıkıştırılmış oturum özetleri | "Ne oldu" |
+| **Semantic (Anlamsal)** | Çıkarılan gerçekler ve desenler | "Ne bildiğim" |
+| **Procedural (Yöntemsel)** | İş 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.
+Bellekler zamanla çürür (Ebbinghaus eğrisi). Sık erişilen bellekler güçlenir. Bayatlamış (stale) bellekler otomatik olarak tahliye edilir (auto-evict). Çelişkiler tespit edilir ve çözülür.
### Ne Yakalanır
-| Hook | Yakalar |
+| Hook | Yakaladığı |
|------|----------|
-| `SessionStart` | Proje yolu, oturum ID |
-| `UserPromptSubmit` | Kullanıcı istemleri (gizlilik-filtrelenmiş) |
+| `SessionStart` | Proje path'i, oturum ID'si |
+| `UserPromptSubmit` | Kullanıcı prompt'ları (privacy-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ü |
+| `PreCompact` | Compaction öncesi belleği yeniden enjekte eder |
+| `SubagentStart/Stop` | Sub-agent yaşam döngüsü |
| `Stop` | Oturum sonu özeti |
| `SessionEnd` | Oturum tamamlandı işareti |
@@ -914,55 +1043,59 @@ Bellekler zamanla decay olur (Ebbinghaus eğrisi). Sık erişilen bellekler gü
| Yetenek | Açıklama |
|---|---|
| **Otomatik yakalama** | Her tool kullanımı hook'lar üzerinden kaydedilir, manuel çaba yok |
-| **Anlamsal arama** | RRF füzyonu ile BM25 + vektör + bilgi grafı |
-| **Bellek evrimi** | Sürümleme, supersede, ilişki grafları |
-| **Recall hijyeni** | Supersede edilmiş bellek sürümleri arama indekslerinden çıkar; KV'deki sürüm zinciri tam geçmişi tutar |
-| **Yakın-kopya ipuçları** | Yeni içerik mevcut bir belleğe çok benzediğinde kayıtlar tavsiye niteliğinde bir `similarTo` eşleşmesi raporlar |
-| **Ajan başına kapsam** | `agentId`; REST, MCP ve arama indeksi boyunca kayda ve recall'a paylaşımlı ya da izole modda eşlik eder |
-| **Yazım anı provenansı** | Her gözlem ve bellek; yakalama, kaydetme ve içeri aktarma sırasında damgalanan değişmez bir köken kanalı (user, agent, tool, import veya shared) taşır |
-| **Otomatik unutma** | TTL süresi dolması, çelişki algılama, önem tahliyesi |
-| **Gizlilik öncelikli** | API anahtarları, secret'lar, `` 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 |
+| **Semantik arama** | RRF füzyonuyla BM25 + vektör + bilgi grafı |
+| **Bellek evrimi** | Versiyonlama, supersession, ilişki grafları |
+| **Recall hijyeni** | Supersede edilmiş bellek sürümleri arama indekslerinden çıkar; KV'deki sürüm zinciri tam geçmişi korur |
+| **Yakın-tekrar ipuçları** | Yeni içerik mevcut bir belleğe yakından benzediğinde kayıtlar bilgilendirici bir `similarTo` eşleşmesi bildirir |
+| **Ajan başına scope'lama** | `agentId`, REST, MCP ve arama indeksi genelinde paylaşılan veya izole modda kaydetme ve recall boyunca iş görür |
+| **Yazma anı kökeni (provenance)** | Her gözlem ve bellek, yakalama, kaydetme ve içe aktarma anında damgalanan değiştirilemez bir köken kanalı taşır (user, agent, tool, import veya shared) |
+| **Otomatik unutma** | TTL süresinin dolması, çelişki tespiti, önem bazlı tahliye |
+| **Önce gizlilik** | API anahtarları, secret'lar, `` etiketleri depolamadan önce temizlenir |
+| **Kendi kendini onarma** | Circuit breaker, sağlayıcı fallback zinciri, health monitoring |
+| **Claude köprüsü** | MEMORY.md ile iki yönlü senkronizasyon |
+| **Bilgi grafı** | Entity çıkarımı + BFS traversal |
+| **Takım belleği** | Takım üyeleri arasında namespace'lenmiş paylaşılan + özel bellek |
+| **Alıntı kökeni** | Herhangi bir belleği kaynak gözlemlere kadar izleyin |
+| **Git snapshot'ları** | Bellek durumunu versiyonlayın, geri alın (rollback) ve diff'leyin |
---
-Üç sinyali birleştiren üçlü-akış geri getirme:
+Üç sinyali birleştiren üçlü-stream retrieval:
-| Akış | Ne yapar | Ne zaman |
+| Stream | 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 |
+| **Vektör** | Dense embedding'ler üzerinde kosinüs benzerliği | Embedding sağlayıcısı yapılandırıldığında |
+| **Graf** | Entity eşleştirme üzerinden bilgi grafı traversal'ı | Sorguda entity tespit edildiğinde |
+
+Reciprocal Rank Fusion (RRF, k=60) ile füzyonlanır ve oturum bazında çeşitlendirilir (oturum başına en fazla 3 sonuç).
-Reciprocal Rank Fusion (RRF, k=60) ile birleştirilir ve oturum-çeşitlendirilir (oturum başına maksimum 3 sonuç).
+Bir vektör indeksi doldurulduğunda, `mem::search` (`memory_recall`'un arkasında) hybrid BM25 + vektör ranker'ı kullanır. Embedding olmadan BM25 kullanır. `smart-search`, anahtarsız modda dahi graf verisi mevcut olduğunda ek olarak yapısal graf eşleşmelerini füzyonlayabilir. Lesson recall'u, her sorguda tüm corpus'u taramak yerine özel bir bellek içi (in-memory) BM25 indeksinde çalışır. Supersede edilmiş bellek sürümleri her recall yolundan hariç tutulur; sürüm zinciri geçmişlerini korur.
-Hibrit sıralama yalnızca `smart-search`'e değil, birincil recall yoluna da uygulanır: `mem::search` (`memory_recall`'un arkasındaki fonksiyon), vektör indeksi dolduğunda aynı BM25 + vektör + graf füzyonuyla sıralar. Ders (lesson) recall'u, her sorguda tüm corpus'u taramak yerine özel bir bellek içi BM25 indeksinde çalışır. Supersede edilmiş bellek sürümleri her recall yolundan hariç tutulur; sürüm zinciri geçmişlerini korur.
+Vektörler bir çökme veya force-kill'den sağ çıkar. Vektör indeksi, en fazla her `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`'de (10 dakika) bucket'lar halinde kaydedilir. Bu aralıkta eklenen veya kaldırılan her vektör, state store'daki küçük bir bekleyen (pending) log'a da hemen yazılır ve bir sonraki başlatma, embedding sağlayıcısını çağırmadan bunu replay eder. Her başarılı kayıt, log'u boşaltır. Replay'den sonra hâlâ vektörü olmayan dokümanlar, hiçbiri kalmayana kadar `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) parti halinde arka planda yeniden embed edilir ve durdurulan bir backfill, bir sonraki başlatmada devam eder. `/agentmemory/status` ve görüntüleyici, bekleyen log boyutunu ve backfill durumunu gösterir. Anahtarsız kurulumlar hiçbir şey yazmaz.
-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.
+BM25, Yunanca, Kiril, İbranice, Arapça ve aksanlı Latin'i kutudan çıktığı gibi tokenize eder. Çince / Japonca / Korece bellekler için, CJK run'larını kelime seviyesinde token'lara bölmek üzere opsiyonel segmenter'ları kurun (`npm install @node-rs/jieba tiny-segmenter`); bunlar olmadan agentmemory, tüm-run tokenizasyonuna yumuşak geçiş yapar (soft-falls) ve stderr'de tek seferlik 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):
+Anahtarsız kurulumlar vektör embedding'lerini devre dışı bırakır: `mem::search`, BM25 kullanır; `smart-search` ise ek olarak mevcut yapısal graf verisini de kullanabilir. Ücretsiz, cihaz üzerinde semantik embedding'lere opt-in yapmak için şunu `~/.agentmemory/.env`'e ekleyin ve agentmemory'yi yeniden başlatın:
-```bash
-npm install @huggingface/transformers
+```env
+EMBEDDING_PROVIDER=local
```
+Normal npm kurulumu, opsiyonel `@huggingface/transformers` runtime'ını içerir. İlk embedding isteği `Xenova/all-MiniLM-L6-v2`'yi indirir, bu yüzden ağ erişimine ihtiyaç duyar ve daha uzun sürebilir; sonraki çıkarımlar (inference) cihaz üzerinde çalışır. Uzak sağlayıcılar, `EMBEDDING_PROVIDER` onları geçersiz kılmadığı sürece kendi anahtarlarından otomatik olarak algılanır.
+
| 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 |
+| **Yerel (önerilen opt-in)** | `all-MiniLM-L6-v2` | Ücretsiz | İlk model indirmesinden sonra cihaz üzerinde, yalnızca BM25'e göre +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 ([kullanımdan kaldırıldı, 14 Oca 2026'da durduruldu](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | 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 |
+| OpenRouter | Herhangi bir model | Değişken | Çoklu-model proxy |
---
@@ -970,105 +1103,105 @@ npm install @huggingface/transformers
54 tool, 6 kaynak, 3 prompt ve 17 skill.
-> **MCP shim vs tam sunucu:** yayımlanan `@agentmemory/mcp` paketi ince bir shim'dir. Tam 54-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.
+> **MCP shim vs tam sunucu:** yayımlanan `@agentmemory/mcp` paketi ince bir shim'dir. Tam 54-tool yüzeyini **yalnızca `AGENTMEMORY_URL` üzerinden çalışan bir agentmemory sunucusuna erişebildiğinde** (proxy modu) açığa çıkarır. Erişilebilir sunucu olmadığında, shim yerel bir 7-tool kümesine düşer (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|all` env değişkeni, *sunucu tarafı* bir flag'dir; bunu shim'in `env` bloğunda ayarlamak hiçbir etki yapmaz. Cursor / OpenCode / Gemini CLI'de yalnızca 7 tool görüyorsanız, `npx -y @agentmemory/agentmemory@latest`'i (veya Docker stack'ini) başlatın ve `AGENTMEMORY_URL=http://localhost:3111`'i ayarlayın.
### 54 Tool
-Küçükten büyüğe üç tool yüzeyi: `AGENTMEMORY_TOOLS=core` görünürlüğü 8 temel tool'a indirir (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); aşağıdaki temel set registry'nin 14 kurucu tool'udur; varsayılan (`AGENTMEMORY_TOOLS=all`) 54'ünün tamamını açar.
+Küçükten büyüğe üç tool yüzeyi: `AGENTMEMORY_TOOLS=core`, görünürlüğü 8 temel tool'a indirir (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); aşağıdaki temel (base) küme, registry'nin 14 temel (foundational) tool'udur; varsayılan (`AGENTMEMORY_TOOLS=all`), 54'ünün tamamını açığa çıkarır.
Temel tool'lar (14)
| 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_file_history` | Belirli dosyalar hakkında geçmiş gözlemler |
-| `memory_patterns` | Tekrar eden desenleri algıla |
-| `memory_sessions` | Son oturumları listele |
-| `memory_smart_search` | Hibrit anlamsal + anahtar kelime araması |
-| `memory_vision_search` | Görsel gözlemleri ara |
+| `memory_recall` | Geçmiş gözlemleri arar |
+| `memory_compress_file` | Markdown dosyalarını yapıyı koruyarak sıkıştırır |
+| `memory_save` | Bir içgörüyü, kararı veya deseni kaydeder |
+| `memory_file_history` | Belirli dosyalarla ilgili geçmiş gözlemler |
+| `memory_patterns` | Tekrarlayan desenleri tespit eder |
+| `memory_sessions` | Son oturumları listeler |
+| `memory_smart_search` | Hybrid semantik + anahtar kelime arama |
+| `memory_vision_search` | Görüntü gözlemlerini arar |
| `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 |
+| `memory_profile` | Proje profili (concept'ler, dosyalar, desenler) |
+| `memory_export` | Tüm bellek verisini dışa aktarır |
+| `memory_relations` | İlişki grafını sorgular |
| `memory_commit_lookup` | Bir git commit'inin arkasındaki oturumlar |
| `memory_commits` | Bir oturum için kaydedilen commit'ler |
-Genişletilmiş tool'lar (54 toplam, varsayılan yüzey)
+Genişletilmiş tool'lar (toplam 54, varsayılan yüzey)
| Tool | Açıklama |
|------|-------------|
-| `memory_patterns` | Tekrar eden desenleri algıla |
+| `memory_patterns` | Tekrarlayan desenleri tespit eder |
| `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_relations` | İlişki grafını sorgular |
+| `memory_graph_query` | Bilgi grafı traversal'ı |
+| `memory_consolidate` | 4 katmanlı konsolidasyonu çalıştırır |
+| `memory_claude_bridge_sync` | MEMORY.md ile senkronize eder |
+| `memory_team_share` | Takım üyeleriyle paylaşır |
| `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_audit` | İşlemlerin audit izi |
+| `memory_governance_delete` | Audit izi ile siler |
+| `memory_snapshot_create` | Git-versiyonlu snapshot |
+| `memory_action_create` | Bağımlılıklarla iş öğeleri oluşturur |
+| `memory_action_update` | Action durumunu günceller |
+| `memory_frontier` | Önceliğe göre sıralanmış bloklanmamış action'lar |
+| `memory_next` | En önemli tek bir sonraki action |
+| `memory_lease` | Özel action lease'leri (çoklu ajan) |
+| `memory_routine_run` | İş akışı routine'lerini örnekler (instantiate) |
| `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_signal_read` | Receipt'lerle mesajları okur |
+| `memory_checkpoint` | Harici koşul kapıları (gates) |
+| `memory_mesh_sync` | Instance'lar arasında P2P senkronizasyon |
+| `memory_sentinel_create` | Olay güdümlü (event-driven) izleyiciler |
+| `memory_sentinel_trigger` | Sentinel'leri harici olarak tetikler |
+| `memory_sketch_create` | Geçici (ephemeral) action grafları |
+| `memory_sketch_promote` | Kalıcıya yükseltir (promote) |
+| `memory_crystallize` | Action zincirlerini sıkıştırır |
| `memory_diagnose` | Sağlık kontrolleri |
-| `memory_heal` | Sıkışmış durumu otomatik düzelt |
+| `memory_heal` | Takılı durumu otomatik düzeltir |
| `memory_facet_tag` | Boyut:değer etiketleri |
-| `memory_facet_query` | Facet etiketlerine göre sorgula |
-| `memory_verify` | Provenansı izle |
+| `memory_facet_query` | Facet etiketlerine göre sorgular |
+| `memory_verify` | Kökeni (provenance) izler |
### 6 Kaynak · 3 Prompt · 17 Skill
-| Tür | İsim | Açıklama |
+| Tür | Ad | 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://project/{name}/recent` | Bir proje için son gözlemler |
-| Resource | `agentmemory://memories/latest` | En son 10 aktif bellek |
-| Resource | `agentmemory://graph/stats` | Bilgi grafı istatistikleri |
-| Resource | `agentmemory://team/{id}/profile` | Paylaşılan takım profili |
-| 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 |
+| Kaynak | `agentmemory://status` | Health, oturum sayısı, bellek sayısı |
+| Kaynak | `agentmemory://project/{name}/profile` | Proje başına intelligence |
+| Kaynak | `agentmemory://project/{name}/recent` | Bir proje için son gözlemler |
+| Kaynak | `agentmemory://memories/latest` | Son 10 aktif bellek |
+| Kaynak | `agentmemory://graph/stats` | Bilgi grafı istatistikleri |
+| Kaynak | `agentmemory://team/{id}/profile` | Paylaşılan takım profili |
+| Prompt | `recall_context` | Arar + bağlam mesajları döndürür |
+| Prompt | `session_handoff` | Ajanlar arasında veri handoff'u |
+| Prompt | `detect_patterns` | Tekrarlayan desenleri analiz eder |
+| Skill | `/recall` | Belleği arar |
+| Skill | `/remember` | Uzun süreli belleğe kaydeder |
| Skill | `/session-history` | Son oturum özetleri |
-| Skill | `/forget` | Gözlemleri/oturumları sil |
+| Skill | `/forget` | Gözlemleri/oturumları siler |
-Tablo dört çekirdek skill'i gösterir. Tam set 8 çağrılabilir skill artı 7 referans skill'idir; yukarıdaki Yerel skill'ler bölümüne bakın.
+Tablo, dört temel skill'i gösterir. Tam küme, 9 çağrılabilir skill ve 8 referans skill'den oluşur; yukarıdaki Native skill'ler bölümüne bakın.
### Bağımsız MCP
-Tam sunucu olmadan, herhangi bir MCP istemcisi için çalıştırın. Şunlardan herhangi biri çalışır:
+Tam sunucu olmadan, herhangi bir MCP istemcisi için çalıştırın. Bunlardan herhangi biri işe yarar:
```bash
-npx -y @agentmemory/agentmemory mcp # kanonik (her zaman kullanılabilir)
-npx -y @agentmemory/mcp # shim paketi takma adı
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
```
Veya ajanınızın MCP yapılandırmasına ekleyin:
-Çoğu ajan (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI):
+Çoğu ajan (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
@@ -1083,7 +1216,7 @@ Veya ajanınızın MCP yapılandırmasına ekleyin:
}
```
-`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.
+`agentmemory` girdisini, dosyayı değiştirmek yerine host'unuzun mevcut `mcpServers` nesnesine birleştirin. Host'un `localhost`'una erişemeyen sandboxlanmış 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
@@ -1099,7 +1232,7 @@ OpenCode (`opencode.json`):
}
```
-Eklenti dosyasını depodan kopyalayın:
+Eklenti dosyasını repo'dan kopyalayın:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
@@ -1110,126 +1243,201 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
-`3113` portunda otomatik başlar. Akış durumu göstergeli canlı gözlem akışı, iki bölmeli oturum gezgini (geniş ekranlarda listenin yanında yapışkan bir detay paneli), ham JSON ve köken provenansı dahil depolanan kaydın tamamına genişleyen bellek ve ders satırları, ilişkiler seyrekken düğümleri türe göre kümeleyen bir bilgi grafı, oturum tekrar oynatma ve bir sağlık paneli.
+`3113` portunda otomatik başlar. Görüntüleyici, bağlandığında bir snapshot yükler (`GET /agentmemory/viewer/snapshot`) ve ardından canlı stream olaylarını uygular: yeni bellekler, dersler, gözlemler, audit girdileri, graf değişiklikleri ve health güncellemeleri polling veya sayfa yenileme olmadan görünür. Diğer tek istekler, tıkladığınız action'lar, "load more" sayfaları ve aramalardır. Stream düştüğünde, görüntüleyici rakamlarının ne kadar eski olduğunu gösterir, backoff ile yeniden bağlanır ve bir snapshot'tan yeniden senkronize olur.
+
+- Canlı sayımlarla, deep link'lerle (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), klavye kısayollarıyla ve bir mobil menüyle **dört grupta 12 sekme**.
+- **Memories:** server-side arama, proje, ajan ve türe göre filtreler, sürüm zinciri ve bir kelime diff'i olan bir detay paneli, provenance link'leri, id, MCP çağrısı ve bir curl komutu için kopyalama butonları, düzenleme (yeni bir sürüm), onayla forget, toplu (bulk) forget ve JSON export.
+- **Sessions:** okunabilir tool girdisi ve çıktısıyla satır içi (inline) bir gözlem zaman çizelgesi, filtreler ve sayfalama, ve her oturumun ürettiği bellekler ve dersler.
+- **Graph:** arama, ilişkiler ve kaynaklarla düğüm (node) detayı, yalnızca renge dayanmayan bir legend ve zoom kontrolleri.
+- **Health:** `GET /agentmemory/status`'un canlı versiyonu. Her problem, çözümüyle birlikte gelir; ayrıca state backend'i, indeks kayıt durumu, graf provenance compaction ilerlemesi ve gerçek eşiklerle bir konsolidasyon açıklayıcısı.
+- **Audit, Activity, Profile, Replay, Lessons, Actions ve Crystals** sayfaları; her biri bölümün ne olduğunu, neden boş olduğunu ve onu doldurabilecek komutu söyleyen bir boş durum (empty state) ile ve her terim ve sayı üzerinde bir `?` sözlük tooltip'i ile.
```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'`).
+Görüntüleyici sunucusu, varsayılan olarak `127.0.0.1`'e bağlanır ve istekleri REST API'ye ilettiğinde sunucu secret'ını ekler, bu yüzden hiçbir kuruluma gerek yoktur. REST ile servis edilen `/agentmemory/viewer` endpoint'i, normal bearer-token kurallarını izler ve token'ı olmayan tarayıcıları görüntüleyici portuna yönlendirir. CSP header'ları, yanıt başına bir script nonce'ı kullanır ve satır içi (inline) handler özniteliklerini devre dışı bırakır (`script-src-attr 'none'`).
---
-`: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.
+`:3113`'teki görüntüleyici, ajanınızın **hatırladığını** gösterir. [iii console](https://iii.dev/docs/console), ajanınızın **yaptığını** gösterir: her bellek işlemi bir OpenTelemetry trace'i olarak, her KV girdisi düzenlenebilir, her fonksiyon çağrılabilir, her stream dinlenebilir (tappable). Aynı belleğe iki pencere: biri ürün şekilli, biri engine ş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.
+Bir `memory_smart_search`'ün ateşlenmesini izleyin ve BM25 taraması → embedding lookup'u → RRF füzyonu → reranker'ı bir waterfall olarak görün. KV browser'da takılı kalmış bir konsolidasyon timer'ını düzenleyin. Değiştirilmiş bir payload ile bir `PostToolUse` hook'unu yeniden oynatın (replay). WebSocket stream'ini pin'leyin ve gözlemlerin canlı olarak düşmesini izleyin.
-agentmemory bunu ücretsiz dağıtır çünkü her fonksiyon çağrısı ve trigger iii üzerinden ateşlenir; özel hiçbir şey yok, enstrümante edilecek hiçbir şey yok.
+agentmemory, bunu ücretsiz olarak sunar çünkü her fonksiyon çağrısı ve trigger iii üzerinden ateşlenir; özel (custom) hiçbir şey yok, enstrümante edilecek hiçbir şey yok.
-
+
- Workers sayfası: agentmemory'nin kendisi dahil bağlı her worker; PID, fonksiyon sayısı, runtime ve son-görülme ile birlikte.
+ Workers sayfası: agentmemory'nin kendisi dahil her bağlı worker; PID, fonksiyon sayısı, runtime ve son-görülme ile birlikte.
-**Zaten kurulu.** Konsol `iii` ile birlikte gelir; ayrı kurucu yok.
+**Zaten kurulu.** Console, sabitlenmiş `iii` engine'i (0.22+) ile birlikte gelir; ayrıca kurulacak bir şey yok. İlk başlatma, console binary'sini engine'in yanına indirir.
-**agentmemory ile birlikte başlat:**
+**agentmemory ile birlikte başlatın:**
```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
+agentmemory console
```
-Ardından `http://localhost:3114`'ü açın. Deneysel mimari-grafı sayfası için `--enable-flow` ekleyin.
+Bu, sabitlenmiş engine'in `iii console`'unu agentmemory'nin çözümlediği portlara (REST, stream'ler, bridge) karşı çalıştırır ve bunu görüntüleyicinin bir port üstünde, varsayılan olarak `http://localhost:3114`'te sunar. `--console-port N`, başka bir port seçer; `--port` ve `--instance`, `stop` için yaptıkları gibi agentmemory instance'ını seçer; başka herhangi bir flag geçirilir, örneğin deneysel mimari-grafı sayfası için `--enable-flow`.
-Yalnızca taşıdıysanız engine endpoint'lerini override edin:
+Aynı şeyi elle yapmak, `agentmemory` PATH'te olmadığında kullanışlıdır:
```bash
-iii console --port 3114 \
+~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
-**Konsoldan neler yapabilirsiniz:**
+**Console'dan yapabilecekleriniz:**
| 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** | Oturumlar, bellek slot'ları, yaşam döngüsü zamanlayıcıları ve embedding indeksi üzerinde tam CRUD sunan KV tarayıcı; 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ı. |
+| **Workers** | agentmemory worker'ının kendisi dahil, bağlı her worker'ı ve canlı metriklerini görün. |
+| **Functions** | agentmemory'nin fonksiyonlarından herhangi birini bir JSON payload ile doğrudan çağırın; bir istemci bağlamadan `memory.recall`, `memory.consolidate`, `graph.query`'yi test etmek için kullanışlıdır. |
+| **Triggers** | HTTP, cron, event ve state trigger'larını yeniden oynatın: konsolidasyon cron'unu manuel olarak ateşleyin, bir HTTP route'unu yeniden deneyin, bir state değişikliği yayınlayın. |
+| **States** | Oturumlar, bellek slot'ları, yaşam döngüsü timer'ları ve embedding indeksi üzerinde tam CRUD'a sahip KV browser; değerleri yerinde düzenleyin. |
+| **Streams** | iii stream'leri üzerinden akarken bellek yazmaları, hook olayları ve gözlem güncellemeleri için canlı WebSocket monitörü. |
+| **Queues** | Dayanıklı (durable) queue topic'leri + dead-letter yönetimi. Başarısız embedding / compression job'larını yeniden oynatın veya düşürün. |
+| **Traces** | OpenTelemetry waterfall / flame / service-breakdown görünümleri. Tek bir `memory.search`'ün tam olarak hangi fonksiyonları, DB çağrılarını ve embedding isteklerini ürettiğini görmek için `trace_id`'ye göre filtreleyin. |
+| **Logs** | trace/span ID'leriyle filtrelenen ve ilişkilendirilen yapılandırılmış OTEL log'ları. |
+| **Config** | Runtime yapılandırması: engine'inizin tam olarak hangi worker'larla, sağlayıcılarla ve portlarla çalıştığını görün. |
+| **Flow** | (Opsiyonel, `--enable-flow`) Her worker, trigger ve stream'in interaktif mimari grafı. |
-
+
- Traces: her bellek işlemi için şelale / alev / hizmet dağılımı.
+ Traces: her bellek işlemi için waterfall / flame / service breakdown.
**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.
+`iii-config.yaml`, `iii-observability` worker'ı etkinleştirilmiş şekilde gelir (`exporter: memory`, `sampling_ratio: 0.1`, metrikler + log'lar). Ekstra yapılandırmaya gerek yoktur; agentmemory başladığı anda, her bellek işlemi console'un okuyabileceği yapılandırılmış bir log yayar ve bunların onda biri (`sampling_ratio: 0.1`) ayrıca bir trace span'ı da 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.
+Bunun yerine Jaeger/Honeycomb/Grafana Tempo'ya export etmek isterseniz, `exporter: memory`'yi `exporter: otlp` olarak değiştirin ve collector endpoint'ini iii'nin observability dokümantasyonuna 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.
+> **Dikkat:** console'un kendisinde auth zorunlu değildir; onu `127.0.0.1`'e bağlı tutun (varsayılan) ve asla herkese açık hale getirmeyin.
---
-agentmemory **zaten çalışan bir [iii](https://iii.dev) örneğidir**. Üç primitif (worker, fonksiyon, trigger) runtime'ı oluşturur; KV state, stream'ler ve OTEL trace'leri, iii ile birlikte gelen iii-state, iii-stream ve iii-observability worker'larından gelir. Postgres, Redis, Express, pm2 veya Prometheus kurmadınız çünkü iii bunların yerini alıyor.
+agentmemory, **zaten çalışan bir [iii](https://iii.dev) instance'ıdır**. Üç primitif (worker, function, trigger) runtime'ı oluşturur; KV state, stream'ler ve OTEL trace'leri, iii ile birlikte gelen iii-state, iii-stream ve iii-observability worker'larından gelir. Postgres, Redis, Express, pm2 veya Prometheus kurmadınız, çünkü iii bunların yerini alır.
-Bu da, tek bir komutun agentmemory'yi tamamen yeni bir yetenekle genişlettiği anlamına gelir.
+Bu, bir komut daha ile agentmemory'yi tamamen yeni bir yetenekle genişletebileceğiniz anlamına gelir.
-### agentmemory'yi tek komutla genişletin
+### agentmemory'yi daha fazla worker ile 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
-```
+agentmemory'nin ihtiyaç duyduğu builtin'ler zaten `iii-config.yaml` içindedir ve onunla birlikte boot olur: `iii-state` (KV), `iii-queue` (event subscriber'lar için dayanıklı retry'ler), `iii-pubsub`, `iii-cron`, `iii-stream` ve `iii-observability` (her fonksiyonda OTEL trace'leri, metrikler ve log'lar). [iii worker registry](https://workers.iii.dev)'den başka herhangi bir şey aynı engine'e takılır: `iii-config.yaml`'ı `~/.agentmemory/iii-config.yaml`'a kopyalayın (CLI, bu dosyayı paketlenmiş olana tercih eder ve hâlâ portları ve veri path'lerini bunun içine render eder), girdiyi ekleyin, worker runtime'ını bir kez `~/.agentmemory/bin/iii update worker` ile kurun ve agentmemory'yi yeniden başlatın.
-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.
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
-| `iii worker add` | agentmemory'nin üzerine ne elde edersiniz |
+| Worker | agentmemory'nin üstüne ne eklenir |
|---|---|
-| [`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 |
+| [`database`](https://workers.iii.dev/workers/database) | Bellek içi (in-memory) KV varsayılanlarını aştığınızda SQL destekli state adaptörü |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`'dan çıkan kod, shell'inizde değil, tek kullanımlık (throwaway) bir VM içinde çalışır |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory'ninkinin yanında ek MCP sunucuları kurun, aynı engine'i paylaşın |
+
+Engine 0.22.x'te, yukarıdaki builtin'ler için `iii-` önekli adları koruyun; önek olmayan `http`, `state`, `queue`, `pubsub` ve `cron` girdileri, agentmemory'nin 0.23 migrasyonuyla geçeceği bağımsız registry worker'larıdır.
+
+Tam registry: [workers.iii.dev](https://workers.iii.dev). Oradaki her worker, agentmemory'nin kullandığı aynı primitifler üzerinden compose olur ve zaten sahip olduğunuz agentmemory onlardan biridir.
+
+### Engine config ve bind adresi
+
+`agentmemory start`, engine config'ini var olan ilk dosyadan okur: `AGENTMEMORY_III_CONFIG`, geçerli dizindeki `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, ardından paketlenmiş `iii-config.yaml`. Her başlatmada o dosyayı (veri path'leri, portlar, state backend'i) `~/.agentmemory/data/iii-config.runtime.yaml`'a render eder ve engine'i render edilmiş kopyayla başlatır, bu yüzden kaynak dosyayı düzenleyin, render edilmiş olanı değil. Kaynak dosyanın `host:` değerleri, yazıldığı gibi korunur.
+
+Paketlenmiş `iii-config.yaml`, kasıtlı olarak `127.0.0.1`'e bağlanır ve bu varsayılan, bir container içinde de geçerlidir. Bir container'da başlatılan bir CLI, container'ın loopback'ini dinler, bu yüzden yayımlanan portlar hiçbir şeye erişemez. Container'lanmış bir CLI'yi yayımlanan portlar üzerinden servis etmek için, `AGENTMEMORY_III_CONFIG`'i `0.0.0.0`'a bağlanan bir config'e ayarlayın. Paketlenmiş `iii-config.docker.yaml` bunlardan biridir: `iii-http`'yi, `iii-stream`'i ve engine portunu `0.0.0.0`'a bağlar ve state'i `/data` altında saklar, bu yüzden oraya yazılabilir bir volume mount edin. `AGENTMEMORY_SECRET`'ı ayarlı tutun ve yalnızca ihtiyacınız olan portları, `127.0.0.1`'de veya güvendiğiniz bir proxy'nin arkasında yayımlayın.
+
+Bu repo'nun `docker-compose.yml`'i, CLI'nin config lookup'ından geçmez: `iii-config.docker.yaml`'ı `/app/config.yaml`'a mount eder ve `iii-engine` container'ı `--config /app/config.yaml` ile başlar. Tek tıkla [deploy şablonları](../deploy/), entrypoint'lerinde kendi `0.0.0.0` config'lerini yazar.
+
+### Depolama backend'i: file (varsayılan) vs redis
+
+`iii-state` ve `iii-stream`, varsayılan olarak iii-engine'in paketlenmiş dosya tabanlı KV deposunu kullanır: scope başına bir JSON dosyası, engine sürecinin belleğinde tutulur ve bir timer'da diske yeniden yazılır. Bu, tek kullanıcılı yerel bir kurulum için doğru varsayılandır; birden fazla eşzamanlı yazıcıya sahip paylaşılan bir daemon, bunun yerine Redis'ten gerçek key-başına yazmalar alır, işlem başına bir network round trip maliyetiyle (her `state::*` çağrısı hâlâ tek bir Redis bağlantısında serileşir, bu yüzden bu, dosya deposunun lock'unu bir socket ile değiştirir, paralellik ile değil).
+
+Her iki worker'ı da, her yazmada tüm bir scope'u yeniden yazmak yerine her key'i bir Redis hash field'ı (`HSET`) olarak saklayan iii-engine'in yerleşik `redis` adaptörüne geçirmek için `AGENTMEMORY_STATE_BACKEND=redis`'i (artı `AGENTMEMORY_REDIS_URL`'i) ayarlayın:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND`, varsayılan olarak `file`'dır; ayarlanmamış bırakmak bugünkü davranışı değiştirmeden tutar ve tanınmayan bir değer (`file` veya `redis` dışında herhangi bir şey), sessiz bir fallback yerine bir başlatma hatasıdır. `/agentmemory/status` ve görüntüleyicinin Health sayfası (State store satırı), hangi backend'in aktif olduğunu ve yanıt verip vermediğini bildirir, URL'i asla.
+
+**Yalnızca düz `redis://`.** Sabitlenmiş engine (0.22.1), Redis istemcisini TLS desteği olmadan derler, bu yüzden bir `rediss://` URL'i (Upstash, Redis Cloud ve transit sırasında şifrelemeyle ElastiCache gibi çoğu yönetilen Redis teklifi, varsayılan olarak yalnızca-TLS'tir) bağlanamaz. Bağlantı şifrelenmemiştir, bu yüzden Redis şifresi ve saklanan her bellek, kabloda açık metin olarak geçer: yerel bir Redis'e veya güvendiğiniz özel bir ağdaki bir Redis'e işaret edin. Başka herhangi bir Redis için, agentmemory host'unda şifrelenmiş bir tünel (stunnel, SSH veya bir VPN) çalıştırın, böylece düz `redis://` sıçraması o host'ta kalır ve tünelin upstream bağlantısı şifrelenir ve kimlik doğrulanır (authenticated). Bir Redis şifresi tek tırnak içeriyorsa, onu percent-encode edin (`%27`); engine, URL'i parse etmeden önce YAML config'ine genişletir.
+
+**`--instance` başına bir Redis sunucusu.** Engine'in Redis key önekleri (`state:`, `stream::`) sabittir, bu yüzden aynı database'e işaret eden iki agentmemory instance'ı (`--instance 1`, `--instance 2`, ...) birbirinin verisinin üzerine yazar. Ayrı bir database index'i (`redis://localhost:6379/1`), saklanan veriyi ayrı tutar, ancak engine canlı görüntüleyici olaylarını tek bir Redis pub/sub kanalı (`stream::events`) üzerinden iletir ve Redis pub/sub, database index'ini yok sayar, bu yüzden her instance'ın görüntüleyicisi hâlâ diğerinin canlı olaylarını gösterir. Birden fazla instance çalıştırdığınızda her birine kendi Redis sunucusunu (veya portunu) verin.
-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 elinizdeki agentmemory de onlardan biridir.
+**Ne aynı kalır, ne farklıdır.** Her agentmemory özelliği Redis üzerinde çalışır: oturumlar, gözlemler, bellekler (remember, supersede, evolve, forget), arama ve indeks bucket'ları, dersler, graf, audit log'u ve onun aylık scope'ları, export ve import, governance delete'leri, konsolidasyon durumu, görüntüleyici snapshot'ı ve canlı stream'i, ve health monitor'u. Engine, her scope'u tek bir Redis hash'i (`HSET`/`HGET`/`HGETALL`) olarak saklar ve dosya deposuyla aynı state trigger'larını ateşler. Üç engine farkı agentmemory içinde ele alınır:
+
+- Redis, bir scope'un kayıtlarını sabit bir sırada döndürmez. agentmemory bunları en eskiden başlayarak sıralar (önce record id'deki oluşturma zamanına, sonra timestamp'ine göre), bu yüzden list'ler, paging ve export chunk'ları dosya deposundaki aynı sırayla geri gelir.
+- Engine, Redis üzerinde kısmi güncellemeleri, boş array'leri boş nesnelere çeviren bir Lua script'inde uygular. agentmemory, bu güncellemeleri Redis üzerinde kendisi uygular (key başına bir lock altında oku, değiştir, yaz), bu yüzden `tags: []` gibi field'lar array olarak kalır.
+- Eski (legacy) audit log kontrolü, dosya deposunun diskteki dosyasını aramak yerine eski scope'u Redis'ten okur.
+
+Bir fark sizi gerektirir: **Redis yeniden başladıktan sonra, engine, agentmemory yeniden başlayana kadar görüntüleyiciye canlı olayları iletmeyi durdurur.** Veri normal şekilde kaydedilir ve okunur. Health monitor, her 30 saniyede Redis üzerinden bir test olayı gönderir; geri gelmediğinde, `/agentmemory/status` ve görüntüleyicinin Health sayfası, çözümüyle birlikte "Canlı güncellemeler görüntüleyiciye ulaşmıyor" gösterir: agentmemory'yi yeniden başlatın. Redis kapalıysa, status raporu "State store yanıt vermiyor" ve onu nasıl kontrol edeceğinizi gösterir (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Çok büyük bir scope'u listelemek, tüm hash'i tek bir `HGETALL`'da okur; dosya deposunun bunu bellekte tutmasıyla aynı maliyettir.
+
+**Önerilen Redis ayarları.** Varsayılan `save 3600 1 300 100 60 10000` snapshot politikası, bir çökmede dakikalarca yazmayı kaybedebilir; dosya deposunun 5 saniyelik flush penceresinden daha kötü. Kaybetmekten çekineceğiniz her şey için `appendonly yes` ayarlayın. `maxmemory-policy noeviction` ayarlayın; `allkeys-lru` veya benzeri, Redis bellek limitine ulaştığında bellekleri sessizce düşürür.
+
+Native (Docker olmayan) bir başlatma ve her tek tıkla [deploy şablonu](../deploy/) (paketlenmiş `iii-config.yaml`'ın üzerine yazarlar ve native olarak başlarlar), `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL`'i okur ve bunları başlatılan `iii-config`'e render eder. URL'in kendisi o render edilmiş dosyaya asla yazılmaz, yalnızca engine sürecinin boot'ta kendi ortamından genişlettiği bir `${AGENTMEMORY_REDIS_URL}` referansı yazılır. Yalnızca bu repo'nun kendi Docker Compose yolu (`AGENTMEMORY_USE_DOCKER=1`, veya o şekilde zaten başlatılmış bir engine'i devam ettirmek), `iii-config.docker.yaml`'ı salt-okunur mount eder ve asla render etmez; `agentmemory start`, bu kombinasyonu algıladığında uyarır. O dosyayı elle değiştirin, [iii-state](https://workers.iii.dev/workers/iii-state) ve [iii-stream](https://workers.iii.dev/workers/iii-stream) worker dokümantasyonunda gösterilen aynı `name: redis` / `config: redis_url: ...` şeklini izleyerek ve `redis_url`'i container'dan erişilebilir bir Redis'e işaret edin. `docker-compose.yml`, `AGENTMEMORY_REDIS_URL`'i engine container'ına geçirir, bu yüzden `redis_url: '${AGENTMEMORY_REDIS_URL}'` orada çalışır ve URL'i mount edilmiş dosyanın dışında tutar.
+
+Render edilmiş config, URL'i `~/.agentmemory/data/iii-config.runtime.yaml`'ın dışında tutar, ancak engine'in kendi yapılandırma worker'ı, boot olduğunda *genişletilmiş* değeri hâlâ `~/.agentmemory/config/iii-state.yaml` ve `iii-stream.yaml`'a kalıcı hale getirir (iii-engine'in `${VAR}` genişletmesi, o worker seed'ini saklamadan önce gerçekleşir ve çözümlenmiş değeri saklar, referansı değil). O dizini bir credential tutuyormuş gibi ele alın: herhangi bir paylaşılan host'ta `chmod 700 ~/.agentmemory` yapın ve database'in admin credential'ları yerine agentmemory'nin ihtiyaç duyduğuna scope'lanmış bir Redis ACL kullanıcısını tercih edin.
+
+**Migrasyon otomatik değildir.** `AGENTMEMORY_STATE_BACKEND`'i değiştirmek, her iki tarafta da boş bir depodan başlar; hiçbir şey mevcut veriyi file'dan Redis'e veya geri kopyalamaz. Ayrıldığınız backend'den export edin ve taşındığınız backend'e import edin. Bu, bash ve zsh altında aynı şekilde çalışır (`bash -u` dahil). `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` gibi bir array çalışmaz: zsh, header'ı bash'in ikiye böldüğü yerde tek, hatalı biçimli (malformed) bir kelime olarak tutar, bu yüzden `AGENTMEMORY_SECRET` ayarlandığında her iki istek de 401 döner:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export`, büyük bir corpus'u birden fazla çağrıya bölmek (chunking) için ayrıca `?maxSessions=` ve `?offset=` kabul eder; import'ta `strategy`, `merge` (varsayılan-güvenli), `replace` veya `skip`'tir.
### iii'nin yerini aldığı şeyler
-| Geleneksel stack | agentmemory kullanır |
+| Geleneksel stack | agentmemory'nin kullandığı |
|---|---|
-| 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 ` |
+| Express.js / Fastify | iii HTTP Trigger'ları |
+| SQLite / Postgres + pgvector | iii KV State + bellek içi vektör indeksi |
+| SSE / Socket.io | iii Stream'leri (WebSocket) |
+| pm2 / systemd | iii engine worker supervision'ı |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Custom eklenti sistemleri | `iii worker add ` |
-**182 kaynak dosya · ~41,600 LOC · 1,619 test · 264 fonksiyon · 50 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi iii'nin kendisi.
+**225 kaynak dosya · ~54,000 LOC · 2,600+ test · 312 fonksiyon · 66 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
---
@@ -1237,22 +1445,22 @@ Tam kayıt defteri: [workers.iii.dev](https://workers.iii.dev). Oradaki her work
### 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.
+agentmemory, sağlayıcıları ortamınızdan otomatik olarak algılar. Bir sağlayıcı, LLM destekli işlemleri kullanılabilir kılar; ancak yalnızca sağlayıcı yapılandırması, LLM tarafından yazılan gözlem sıkıştırmasını etkinleştirmez. Bu yol, hem bir sağlayıcıyı hem de `AGENTMEMORY_AUTO_COMPRESS=true`'yu gerektirir.
-| Sağlayıcı | Yapılandırma | Notlar |
+| Sağlayıcı | Config | 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 |
+| **No-op (varsayılan)** | Config gerekmez | LLM destekli compress/summarize devre dışı. Synthetic sıkıştırma ve BM25 recall hâlâ çalışır. Claude-subscription fallback'e güveniyorduysanız aşağıdaki `AGENTMEMORY_ALLOW_AGENT_SDK`'ya bakın. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Token başına faturalandırma |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic uyumlu |
| Gemini | `GEMINI_API_KEY` | Embedding'leri de etkinleştirir |
| OpenRouter | `OPENROUTER_API_KEY` | Herhangi bir model |
-| OpenAI API | `OPENAI_API_KEY` | Varsayılan `gpt-5.6-luna`, `OPENAI_MODEL` ile override edin |
-| **Yerel (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) veya `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | OpenAI-API-uyumlu her şey. Sıfır maliyet, kendi donanımınızda çalışır. Aşağıdaki [Yerel modeller](#yerel-modeller-ollama--lm-studio--vllm) bölümüne bakın. |
-| 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, bu yüzden artık varsayılan değil. |
+| OpenAI API | `OPENAI_API_KEY` | Varsayılan `gpt-5.6-luna`, `OPENAI_MODEL` ile geçersiz kılın |
+| **Yerel (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) veya `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | OpenAI-API-uyumlu her şey. Sıfır maliyet, kendi hardware'inizde çalışır. Aşağıdaki [Yerel modeller](#local-models-ollama--lm-studio--vllm) bölümüne bakın. |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Yalnızca opt-in. `@anthropic-ai/claude-agent-sdk` oturumlarını spawn eder; eskiden sınırsız Stop-hook recursion'ına neden oluyordu, bu yüzden artık varsayılan değildir. |
### Yerel modeller (Ollama / LM Studio / vLLM)
-agentmemory OpenAI-API-uyumlu her sunucuyla konuşur, bu yüzden `/v1/chat/completions` sunan her şey kod değişikliği olmadan çalışır. Ücretli anahtar yok, bulut yok, hız limiti yok; tamamen kendi donanımınızda çalışır.
+agentmemory, OpenAI-API-uyumlu herhangi bir sunucuyla konuşur, bu yüzden `/v1/chat/completions`'ı expose eden her şey kod değişikliği yapılmadan çalışır. Ücretli anahtar yok, cloud yok, rate limit yok; tamamen kendi hardware'inizde çalışır.
**Ollama** (varsayılan port `11434`):
@@ -1270,7 +1478,7 @@ OPENAI_MODEL=qwen3:8b
**LM Studio** (varsayılan port `1234`):
-LM Studio'yu açın → Local Server sekmesi → Start Server. Seçiciden herhangi bir sohbet modeli seçin (Qwen 3, gpt-oss, DeepSeek R1, vb.).
+LM Studio'yu açın → Local Server sekmesi → Start Server. Picker'dan herhangi bir chat modeli seçin (Qwen 3, gpt-oss, DeepSeek R1, vb.).
```env
# ~/.agentmemory/.env
@@ -1279,86 +1487,90 @@ OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
-**vLLM / llama.cpp / Text Generation Inference**: aynı şekil. `OPENAI_BASE_URL`'i sunucunuzun sunduğu URL'ye yönlendirin ve `OPENAI_MODEL`'i sunucunuzun kabul edeceği bir isme ayarlayın.
+**vLLM / llama.cpp / Text Generation Inference**: aynı şekil. `OPENAI_BASE_URL`'i sunucunuzun expose ettiği URL'e işaret edin ve `OPENAI_MODEL`'i sunucunuzun kabul edeceği bir isme ayarlayın.
-**Bellek işi için model seçimleri**: sıkıştırma ve özetleme, 7B'lik bir instruct modelin fazlasıyla yeterli olduğu kısa görevlerdir (<2K token girdi, <500 token çıktı). Öneriler:
+**Bellek işleri için model seçimleri**: sıkıştırma ve özetleme, bir 7B instruct modelin yeterli olduğu kısa görevlerdir (<2K token girdi, <500 token çıktı). Öneriler:
| Model | Boyut | Neden |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | 16 GB'lık bir makinede dengeli varsayılan; çıkarımda ve tool-şekilli metinde güçlü |
-| `qwen3:4b` | ~2.6 GB | En küçük makul seçenek; sıkıştırma için yeterli, graf çıkarımında daha zayıf |
-| `qwen3-coder:30b` | ~19 GB | 24-32 GB donanımda kod-şekilli oturumlar için en iyi yerel seçim (30B MoE, 3.3B aktif) |
+| `qwen3:4b` | ~2.6 GB | En küçük makul seçenek; sıkıştırma için iyi, graf çıkarımı için daha zayıf |
+| `qwen3-coder:30b` | ~19 GB | 24-32 GB hardware'de kod-şekilli oturumlar için en iyi yerel seçim (30B MoE, 3.3B aktif) |
| `gpt-oss:20b` | ~14 GB | 16 GB RAM'e sığan güçlü genel model |
| `deepseek-r1:8b` | ~5.2 GB | Reasoning distill; daha yavaş ama daha temiz çıkarımlar |
-Qwen 3 modelleri varsayılan olarak düşünür ve herhangi bir çıktı vermeden önce tüm token bütçesini muhakemeye harcayabilir. Graf-çıkarım istemlerine `/no_think` eklemek için `AGENTMEMORY_LLM_NOTHINK=1` ayarlayın ve çıkarımlar boş dönüyorsa `MAX_TOKENS`'ı yükseltin (16384 işe yarar).
+Qwen 3 modelleri varsayılan olarak "düşünür" (think) ve herhangi bir çıktıdan önce tüm token bütçesini reasoning'de yakabilir. Graf-çıkarım prompt'larına `/no_think` eklemek için `AGENTMEMORY_LLM_NOTHINK=1` ayarlayın ve çıkarımlar boş gelirse `MAX_TOKENS`'ı yükseltin (16384 işe yarar).
-Reasoning sınıfı modeller (`` blokları olan `o1` tarzı), yerel sunucunuzun yüzeye çıkarmayabileceği bir `reasoning` alanıyla boş `content` döndürebilir. Çıkarımlar boş geliyorsa önce reasoning olmayan bir modele geçin. `OPENAI_REASONING_EFFORT=none` env'i, OpenAI reasoning şemasını yansıtan Ollama Cloud thinking modellerinde de düşünmeyi kapatabilir.
+Reasoning sınıfı modeller (`` bloklarıyla `o1` tarzı), yerel sunucunuzun açığa çıkarmayabileceği bir `reasoning` field'ı ile boş `content` döndürebilir. Çıkarımlar boş gelirse, önce reasoning-olmayan bir modele geçin. `OPENAI_REASONING_EFFORT=none` env'i, OpenAI reasoning şemasını yansıtan Ollama Cloud thinking modellerinde de thinking'i devre dışı bırakabilir.
-Yerel embedding'ler `@huggingface/transformers` aracılığıyla kutudan çıkar çıkmaz gelir: `EMBEDDING_PROVIDER=local` (varsayılan) size tamamen cihaz üstünde `Xenova/all-MiniLM-L6-v2` (384-boyut) verir. Ekstra yapılandırma gerekmez.
+Yerel embedding'ler opsiyonel bir bağımlılık olarak gelir, ancak varsayılan olarak etkin değildir. `Xenova/all-MiniLM-L6-v2`'ye (384-dim) opt-in yapmak için `EMBEDDING_PROVIDER=local` ayarlayın. İlk embedding isteği modeli indirir; sonrasında çıkarım cihaz üzerinde yapılır. Bu ayar veya uzak bir embedding anahtarı olmadan, vektörler devre dışı kalır, `mem::search` BM25 kullanır ve `smart-search` hâlâ mevcut graf eşleşmelerini ekleyebilir.
### 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ı.
+Hem bir sağlayıcı hem de `AGENTMEMORY_AUTO_COMPRESS=true` ile LLM tarafından yazılan arka plan sıkıştırması etkinleştirildiğinde, her gözlemde çalışır, bu yüzden model seçimi aylık harcamayı anlamlı şekilde değiştirir. Yakalanan workload verisi: 2026-05-23 fiyatlandırmasıyla üç OpenRouter modeline karşı çalıştırılan 635 istek / 888K token / 35 saat aktif kullanım.
-| Katman | Model | Girdi / 1M | Çıktı / 1M | Yakalanan 35 saat maliyeti | Notlar |
+| Katman | Model | Girdi / 1M | Çıktı / 1M | Yakalanan 35 saat için maliyet | Notlar |
|------|-------|------------|-------------|---------------------------|-------|
-| Önerilen | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | En yeni DeepSeek; sıkıştırma iş yükleri için en ucuz önerilen seçim. |
+| Önerilen | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (tah.) | En yeni DeepSeek; sıkıştırma workload'ları için önerilen en ucuz seçim. |
| Ö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 | `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-5` | $3.00 | $15.00 | ~$5.02 (est.) | Ölçülen Sonnet 4.6 çalıştırmasıyla aynı liste fiyatı; 2026-08-31'e kadar $2/$10 tanıtım fiyatlandırması. |
-| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Amiral gemisi katmanı; her zaman açık arka plan işi için pahalı. |
-| Kaçının | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Amiral gemisi sınıfı model; sıkıştırma için aşırı harcama. |
+| Önerilen | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Oturumlarınız ağırlıklı olarak kod-şekilliyse güçlü kod reasoning'i. |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (tah.) | Ölçülen Sonnet 4.6 çalıştırmasıyla aynı liste fiyatı; 2026-08-31'e kadar $2/$10 giriş fiyatlandırması. |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (tah.) | Flagship katman; her zaman açık arka plan işi için maliyetli. |
+| Kaçının | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (tah.) | Flagship sınıfı model; sıkıştırma için aşırı harcama. |
-Ölçülen satırlar yakalanan çalıştırmadan gelir; (est.) satırları aynı token karışımını her modelin liste fiyatıyla ölçekler.
+Ölçülen satırlar, yakalanan çalıştırmadan gelir; (tah.) satırları, aynı token karışımını her modelin liste fiyatıyla ölçekler.
-`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.
+agentmemory, `OPENROUTER_MODEL` bir premium-katman deseniyle eşleştiğinde bir runtime uyarısı yazdırır. Bilinçli bir seçim yaptıktan sonra sessize almak 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 Flash / V4 Pro / Qwen3-Coder bu görevde Sonnet'in yuvarlama hatası içinde kalırken 10-70× daha az maliyetlidir. Premium katman modelleri doğrudan okuduğunuz sorgular için saklayın.
+Bellek işi için kalite vs maliyet tradeoff'u: sıkıştırma, nispeten gevşek kalite çıtalarına sahip bir özetleme görevidir (özeti kullanıcı değil, ajan yeniden okur). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder, bu görevde Sonnet'in yuvarlama hatası içinde kalırken 10-70× daha az maliyete sahiptir. Premium katman modellerini, doğrudan okuduğunuz sorgular için saklayın.
Kaynaklar: [Claude Sonnet 5 için OpenRouter fiyatlandırması](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [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.
+Birden fazla rolün tek bir agentmemory sunucusunu paylaştığı çoklu-ajan kurulumlarında (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` her yazmayı onu yapan rol ile etiketler. `AGENTMEMORY_AGENT_SCOPE`, recall'ın 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"
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
İki mod:
-| Mod | Yazıları etiketle | Recall'u filtrele | Ne zaman kullanılır |
+| Mod | Yazmaları etiketler | Recall'ı filtreler | 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. |
+| `shared` (varsayılan) | evet | hayır | Audit izi ile ajanlar arası bağlam. Architect, developer'ın not ettiğini görebilir, ancak her satır kimin 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.
+`AGENT_ID` ayarlandığında ne etiketlenir: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Rol, `api::session::start` → `mem::observe` → `mem::compress` → KV şeklinde akar.
-İzole modda ne filtrelenir: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Her endpoint istek başına override için `?agentId=` 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.
+İzole modda ne filtrelenir: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Her endpoint, istek başına geçersiz kılmak için `?agentId=` ve env scope'undan tamamen opt-out etmek için `?agentId=*` kabul eder. `/memories` ayrıca, `agentId`'si undefined olan AGENT_ID-öncesi bellekleri yüzeye çıkarmak 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. MCP `memory_save` tool'u aynı `agentId` alanını açığa çıkarır, bağımsız stdio sunucusu hem `agentId` hem `project`'i iletir ve kaydedilen bellekler `agentId`'yi arama indeksine taşır; böylece ajan-kapsamlı arama gözlemlerin yanı sıra bellekleri de kapsar.
+SDK / REST katmanında çağrı başına geçersiz kılma: her mutasyon endpoint'i (`/session/start`, `/remember`), env'in önüne geçen bir `agentId` field'ını istek gövdesinde kabul eder. Birçok rolü tek bir sunucu sürecinden yönlendiren runtime'lar için kullanışlıdır. MCP `memory_save` tool'u aynı `agentId` field'ını açığa çıkarır, bağımsız stdio sunucusu hem `agentId`'yi hem `project`'i iletir ve kaydedilen bellekler `agentId`'yi arama indeksine taşır, bu yüzden ajan-scope'lu arama, gözlemlerin yanı sıra bellekleri de kapsar.
-`AGENT_ID` ayarlanmadığında bellek kapsam dışı kalır (eski davranış, etiket yok, filtre yok).
+`AGENT_ID` ayarlanmadığında, bellek scope'suz kalır (eski/legacy 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.
+agentmemory + iii-engine, varsayılan olarak dört port bağlar (bind). Bir yeniden başlatma `port in use` ile başarısız olursa, bu tablo hangi süreci arayacağınızı 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`) |
+| `3112` | iii-engine | Dahili stream worker'ı (agentmemory + görüntüleyici tarafından kullanılır) | `III_STREAM_PORT` (tercih edilen) veya legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | Gerçek zamanlı görüntüleyici (`http://localhost:3113`) | Bildirilen URL için `III_VIEWER_PORT` veya `AGENTMEMORY_VIEWER_URL` |
+| `49134` | iii-engine | WebSocket; worker'lar buraya kaydolur, OTel telemetrisi bunun üzerinden akar | `III_ENGINE_PORT` veya `III_ENGINE_URL` |
+
+`--port `, REST anchor'ını değiştirir ve yalnızca yukarıdaki ilgili açık port veya URL ayarlanmamışsa stream'ler `N+1`, görüntüleyici `N+2` ve engine WebSocket'i `N+46023`'ü türetir. İzole bir lifecycle namespace'i oluşturmaz. İkinci bir daemon için `--instance 1` kullanın; bu, anchor 3211'i kullanır, varsayılan olarak `3211/3212/3213/49234`'tür ve ayrı bir `instance-1` veri ve lifecycle dizini alır. Instance 1'den 50'ye kadar aynı deseni izler.
-Çöken bir çalıştırma sonrası portlar bağlı kaldığında bayat-süreç temizliği:
+Sabitlenmiş engine, `--no-update-check` ile başlar (boot'ta GitHub'a karşı güncelleme veya güvenlik-danışma aramaları yok) ve iii'nin anonim kullanım telemetrisi kapalıyken: değişkeni kendiniz export etmediğiniz sürece agentmemory, spawn ettiği engine için `III_TELEMETRY_ENABLED=false` ayarlar ve paketlenmiş compose dosyası da aynısını yapar.
+
+Çökmüş bir çalıştırmadan sonra portlar bağlı kaldığında, bayatlamış (stale) süreç temizliği:
```bash
-# macOS / Linux — her portta ne varsa bulun ve öldürün
+# 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
@@ -1368,38 +1580,40 @@ netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
-`agentmemory stop` graceful shutdown'da hem worker hem de engine pidfile'ını temiz olarak biçer. Docker modunda yalnızca agentmemory'nin kendi compose servislerini kapatır ve Docker kapanışından önce yerel worker'ı biçer; CLI ayrıca `--force` geçilmedikçe Docker veya VM port sahiplerini (Docker backend, vpnkit, colima) yerel engine olarak sahiplenmeyi ya da onlara sinyal göndermeyi reddeder. Yukarıdaki manuel temizlik yalnızca her iki pidfile'ın da geride kalmadığı çökme sonrası durum içindir.
+`agentmemory stop`, graceful native shutdown'da hem worker'ı hem de engine pidfile'ını temiz bir şekilde toplar (reap). Docker modunda, native worker'ı flush eder, tam olarak doğrulanmış engine container'ını durdurur ve kayıpsız bir yeniden başlatma için hem container'ı hem de `/data` mount'unu korur; bir sonraki başlatma, aynı container'ı doğrular ve devam ettirir. Docker destekli kaldırma, `agentmemory remove --keep-data` gerektirir: doğrulanmış container'ı, veri mount'unu ve onları kurtarmak için gereken lifecycle kaydını korurken paylaşılan agentmemory-yönetimli dosyaları kaldırır. Yıkıcı Docker veri silme işlemi, bir yedeklemeden sonra kasıtlı olarak operatöre bırakılmıştır. CLI, ayrıca `--force` geçirilmedikçe Docker veya VM port sahiplerini (Docker backend, vpnkit, colima) native engine olarak benimsemeyi veya sinyallemeyi reddeder. Yukarıdaki manuel temizlik, yalnızca hiçbir pidfile'ın 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.
+agentmemory runtime yapılandırmasını her shell'de değişken export etmek yerine `~/.agentmemory/.env` içine koyun. Görüntüleyici `export ANTHROPIC_API_KEY=...` gibi bir kurulum ipucu gösterirse, bunu `export` önekiyle olmadan `ANTHROPIC_API_KEY=...` olarak bu dosyaya 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.
+Süreç ortam değişkenleri hâlâ çalışır ve dosyadaki değerlere göre önceliklidir.
-Windows'ta aynı dosya `%USERPROFILE%\.agentmemory\.env` konumunda bulunur:
+Windows'ta, aynı dosya `%USERPROFILE%\.agentmemory\.env`'de yaşar:
```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:
+Bir API anahtarı yerine bir Claude Code Pro/Max subscription'ı ile 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:
+LLM tarafından yazılan gözlem sıkıştırması her iki satırı gerektirir: bir LLM sağlayıcısına erişim (bu açık subscription fallback'i dahil) ve `AGENTMEMORY_AUTO_COMPRESS=true`. Yalnızca bir sağlayıcı, varsayılan synthetic sıkıştırma yolunu yerinde bırakır.
+
+Konsolidasyon (graf düğümleri, dersler, crystal'lar), bir LLM sağlayıcısı yapılandırıldığında varsayılan olarak açıktır. LLM'siz çalışma istiyorsanız `CONSOLIDATION_ENABLED=false` ile açıkça opt-out yapın. Graf çıkarımı ayrı bir flag'dir:
```env
GRAPH_EXTRACTION_ENABLED=true
-CONSOLIDATION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### Ortam Değişkenleri
-`~/.agentmemory/.env` oluşturun:
+`~/.agentmemory/.env` dosyasını oluşturun:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
@@ -1436,13 +1650,15 @@ CONSOLIDATION_ENABLED=true
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
-# Embedding provider (auto-detected, or override)
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
@@ -1460,14 +1676,20 @@ CONSOLIDATION_ENABLED=true
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
-# Auth
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
# Features
-# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. When on,
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
@@ -1515,6 +1737,36 @@ CONSOLIDATION_ENABLED=true
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
# Team
# TEAM_ID=
# USER_ID=
@@ -1528,33 +1780,80 @@ CONSOLIDATION_ENABLED=true
-`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 ` gerektirir ve mesh sync endpoint'leri her iki eşte de `AGENTMEMORY_SECRET` gerektirir.
+`3111` portunda 138 endpoint. REST API, varsayılan olarak `127.0.0.1`'e bağlanır. Korumalı endpoint'ler `Authorization: Bearer ` gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir `AGENTMEMORY_SECRET` gerektirir.
+
+**Authentication varsayılan olarak açıktır.** `AGENTMEMORY_SECRET` ayarlanmadığında (shell'de veya `~/.agentmemory/.env` içinde), sunucu ilk başlatmada rastgele bir secret üretir ve onu `0600` mod ile `~/.agentmemory/secret`'a saklar. Yerel bir sunucuyla konuştuğunda paketlenmiş her istemci bunu oradan okur: CLI, görüntüleyici, `plugin/scripts` altındaki hook'lar, MCP sunucusu ve `@agentmemory/mcp` shim'i, `agentmemory connect` tarafından yazılan config'ler ve paketlenmiş OpenCode, Pi, OpenClaw, Hermes ve filesystem-watcher entegrasyonları. Saklanan secret, yalnızca loopback URL'lerine (`localhost`, `127.0.0.0/8`, `::1`) gönderilir. Açık bir `AGENTMEMORY_SECRET` her zaman kazanır ve uzak istemcilerin de bunu ayarlamış olması gerekir. Docker ve `deploy/` entrypoint'leri zaten kendi secret'larını üretir ve export eder. API'yi elle çağırmak için:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Yazmalar için istek kuralları.** REST API'ye ve görüntüleyiciye yapılan `POST`, `PUT`, `PATCH` ve `DELETE` istekleri, bir body taşıdıklarında `Content-Type: application/json` göndermelidir (bir `charset` parametresi sorun değildir) ve mevcutsa bir `Origin` header'ı, yapılandırılmış REST veya görüntüleyici portu için bir loopback origin'i olmalı veya `VIEWER_ALLOWED_ORIGINS` içinde listelenmiş olmalıdır (virgülle ayrılmış, örn. `https://memory.example.com`). `Origin` header'ı göndermeyen istemciler (CLI, hook'lar, MCP, curl, server-to-server) etkilenmez. Görüntüleyici de kendi origin'ini kabul eder.
+
+**Dosya path'leri.** Dosya okuyan veya yazan endpoint'ler (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), yalnızca `~/.agentmemory`, instance veri dizini veya `AGENTMEMORY_IMPORT_ROOT` içinde listelenen bir dizin altındaki path'leri kabul eder (birden fazlasını `:` ile, Windows'ta `;` ile ayırın). `/replay/import-jsonl`, ayrıca varsayılan `~/.claude/projects`'i de kabul eder. `/obsidian/export`, `AGENTMEMORY_EXPORT_ROOT` içinde ve `/migrate`, `~/.agentmemory` içinde kalır. Symlink'ler her kontrolden önce çözümlenir.
+
+**Secret temizliği (scrubbing).** API anahtarları, bearer token'lar, PEM private key blokları ve URL'lere gömülü credential'lar (`scheme://user:password@host`), metin saklanmadan önce her yazma yolunda redakte edilir: gözlemler, remember, evolve, slot'lar, dersler, action'lar, sketch'ler, signal'ler, checkpoint'ler, import'lar, jsonl replay, mesh sync, takım paylaşımları, sıkıştırma ve özet çıktısı, crystal'lar ve graf düğümleri.
-Önemli endpoint'ler
+Temel endpoint'ler
| 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 |
+| `GET` | `/agentmemory/health` | Health check (her zaman public) |
+| `GET` | `/agentmemory/status` | Neyin yanlış olduğu ve nasıl düzeltileceği (tarayıcılar için HTML, aksi halde JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | Görüntüleyicinin gösterdiği her şey, tek bir yanıtta |
+| `POST` | `/agentmemory/session/start` | Oturumu başlat + bağlamı al |
+| `POST` | `/agentmemory/session/end` | Oturumu sonlandır |
+| `POST` | `/agentmemory/observe` | Gözlemi yakala (aşağıdaki yakalama teslimatına bakın) |
+| `GET` | `/agentmemory/capture` | Yakalama inbox'ı, dead letter'lar ve offline spool |
+| `POST` | `/agentmemory/capture/retry` | Dead-letter yakalamalarını yeniden dene |
+| `POST` | `/agentmemory/capture/drain` | Yerel offline spool'u şimdi gönder |
+| `POST` | `/agentmemory/smart-search` | Hybrid 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/import` | JSON'dan içe aktar |
| `POST` | `/agentmemory/graph/query` | Bilgi grafı sorgusu |
+| `POST` | `/agentmemory/graph/compact` | Aşırı büyümüş graf provenance'ını kırp |
| `POST` | `/agentmemory/team/share` | Takımla paylaş |
-| `GET` | `/agentmemory/audit` | Denetim izi |
+| `GET` | `/agentmemory/audit` | Audit izi |
Tam endpoint listesi: [`src/triggers/api.ts`](../src/triggers/api.ts)
+**Yakalama teslimatı.** Hook'lar, her gözlemi bir `eventId` ile `POST /agentmemory/observe`'a bir kez gönderir. Bu, payload'un bir id'si olduğunda (örneğin Claude Code'un `tool_use_id`'si) çağrı için host'un kendi id'sidir, aksi halde oturumun, hook türünün, tool adının, girdinin, çıktının ve host timestamp'inin bir hash'idir. Sunucu, olayı state store'daki bir yakalama inbox'ına yazar, gözlemi saklar, ardından inbox girdisini kaldırır. Durum kodu ne olduğunu söyler:
+
+| Durum | `status` field'ı | Anlamı |
+|---|---|---|
+| `201` | `accepted` | Saklandı. `observationId`, yeni gözlemdir. |
+| `202` | `accepted` (`state: "retrying"`) | Kabul edildi, ancak saklama başarısız oldu. Sunucu, yeniden başlatmadan sonra da onu yeniden dener. |
+| `200` | `duplicate` | Bu `eventId` zaten kabul edilmişti. `observationId`, mevcut gözlemdir; yeni bir şey saklanmaz. |
+| `400` / `422` | `rejected` | Geçersiz payload, veya saklama kalıcı olarak başarısız oldu (olay bir dead letter olarak tutulur). |
+| `503` | `rejected` (`retryable: true`) | Inbox dolu (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook'lar olayı spool'lar ve daha sonra gönderir. |
+
+Başarısız olaylar, `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`'e (5) kadar, ikiye katlanan backoff ile her `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`'de (10 sn) yeniden denenir. Hâlâ başarısız olan olaylar, dead letter olarak inbox'ta kalır, `/agentmemory/status` ve görüntüleyicinin Health sayfasında listelenir ve `POST /agentmemory/capture/retry` ile (`{"eventId": "..."}` veya `{"all": true}`) yeniden denenebilir. Kabul edilen olay id'leri, `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 saat, en fazla `AGENTMEMORY_CAPTURE_EVENTS_MAX` id) boyunca hatırlanır, bu yüzden bir timeout veya yeniden başlatma sonrası yeniden oynatılan bir hook bir kez saklanır; oysa kendi host id'lerine sahip iki ayrı tool çağrısı, içerikleri identik olsa bile iki kez saklanır. Bir gözlem silindiğinde (forget, oturum silme, eviction, otomatik unutma veya depoyu değiştiren bir import), olayı, gözlem kaldırılmadan önce silinmiş olarak işaretlenir, bu yüzden aynı pencere içinde o olayın yeniden oynatılması bir duplicate olarak yanıtlanır ve hiçbir şey saklamaz. State store, diske her 2 saniyede bir yazar, bu yüzden yanıtlanan bir olay hâlâ bir an için yalnızca bellekte olabilir. Bunu kapsamak için, her `2xx` yanıtı ayrıca sunucunun `bootId`'sini (her başlatmada yeni), `acceptedAt`'ını ve `durableAfterMs`'ini (kalıcılığın operatörün ayarı olduğu dosya deposunda kayıt aralığı artı 1.5 sn, redis'te 1.5 sn) taşır. Hook'lar, o pencere geçene kadar olayı yerel spool'da tutar ve başka bir istek göndermeden daha sonraki bir çağrıda onu siler. O zamana kadar `bootId` değiştiyse, sunucu yeniden başlamıştır, bu yüzden hook, olayı aynı `eventId` ile yeniden gönderir; diske ulaşmış bir olay iki kez saklanmaz. Sunucu, ayrıca başlangıçta ve her retry aralığında bu tür olayları kendisi de gönderir, bu yüzden bir yeniden başlatma, daha sonra hiçbir hook çalışmasa da hiçbir şey kaybetmez. Daha eski hook'lar ekstra field'ları yok sayar ve daha eski bir sunucuya karşı yeni hook'lar, olayı eskisi gibi `2xx`'te atar.
+
+Sunucu kapalıyken, zamanında yanıt vermediğinde veya bir 5xx döndürdüğünde, hook gözlemi yerel bir spool dosyasına ekler, `/capture-spool/-.jsonl` (klasörü `AGENTMEMORY_CAPTURE_SPOOL_DIR` ile geçersiz kılın). Dosya, kullanıcınıza özeldir (mod 600), secret'lar sunucunun onları redakte ettiği şekilde redakte edilir, en fazla `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) tutar ve `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`'tan (168) daha eski girdileri düşürür. Dolduğunda, yeni girdiler düşürülür ve sayılır ve `/agentmemory/status` bunu bildirir. Hook, hâlâ zaman limiti içinde 0 ile çıkar ve sunucu sağlıklı olduğunda hiçbir istek eklemez. Spool, bir sonraki başlatmada ve sunucuya yeniden ulaşan ilk hook tarafından, ajan beklemesin diye bir arka plan sürecinde gönderilir. Event id'leri bunu güvenli kılar: bir timeout'tan önce ulaşan bir gözlem iki kez saklanmaz. `npx @agentmemory/agentmemory capture`, spool'u ve sunucu inbox'ını gösterir, `--drain` spool'u şimdi gönderir ve `GET /agentmemory/capture`, aynısını JSON olarak döndürür. Spool'u kapatmak için `AGENTMEMORY_CAPTURE_SPOOL=false` ayarlayın.
+
+**Graf provenance'ını kırpma (compacting).** Her bilgi grafı düğümü ve kenarı, geldiği en yeni 32 gözlemin id'lerini tutar. Bu üst sınırdan önce yazılan depolar, hot bir düğüm başına binlerce id tutabilir, bu da graf aramasını ve görüntüleyiciyi yavaşlatır veya worker'ı düşürür. agentmemory bunu kendi başına düzeltir: yükseltmeden sonraki ilk başlatmada, her düğümü, kenarı, supersede edilmiş kenarı (temporal graf geçmişi) ve önbelleğe alınmış snapshot'ı arka planda, aralarında bir duraklama olan küçük parçalar halinde üst sınıra kırpar, bu yüzden arama, yakalama ve görüntüleyici çalışmayı sürdürür. İlerlemesini kaydeder, bir yeniden başlatmadan sonra devam eder ve tamamlandıktan sonra bir daha asla çalışmaz. `/agentmemory/status` ve görüntüleyicinin Health sayfası, bunu bekliyor (pending), çalışıyor (mevcut scope ve pozisyonla), tamamlandı veya başarısız olarak gösterir. Kapatmak için `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` ayarlayın.
+
+Elle çalıştırmak için, `POST /agentmemory/graph/compact`'ı çağırın. Her düğümü ve kenarı listelemek yerine ad ve kenar-key indekslerinde yürür ve yeniden çalıştırmak güvenlidir. Id'leri kırptığında bir `graph_compact` audit girdisi yazar.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Büyük bir depoda veya çağrı 504 döndürdüğünde, bunu parçalar halinde çalıştırın. `scope` (`nodes`, `edges` veya `history`), `offset` ve `limit` gönderin, ardından `null` olana kadar döndürülen `nextOffset` ile yeniden çağırın. Bunu `nodes`, `edges` ve `history` için yapın ve bir `{"scope":"snapshot"}` çağrısıyla bitirin, çünkü parçalı bir çalıştırma önbelleğe alınmış snapshot'a dokunmaz.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
---
@@ -1562,11 +1861,11 @@ Tam endpoint listesi: [`src/triggers/api.ts`](../src/triggers/api.ts)
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 1,674 tests
-npm run test:integration # API testleri (çalışan servisler gerektirir)
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
```
-**Ön koşullar:** Node.js >= 20, [iii-engine](https://iii.dev/docs) veya Docker
+**Ön koşullar:** npm/npx ile Node.js >= 20; [iii-engine](https://iii.dev/docs) v0.22.1 veya Docker. macOS/Linux otomatik engine kurulumu, ayrıca `curl`, bir POSIX `sh` ve `tar` gerektirir; yerel Windows, manuel sabitlenmiş `iii.exe`, WSL2 veya Docker Desktop kullanır.
diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.md
new file mode 100644
index 0000000000..df7b118ce6
--- /dev/null
+++ b/READMEs/README.uk-UA.md
@@ -0,0 +1,1882 @@
+
+
+
+
+
+
+ Ваш агент кодування пам'ятає все. Більше не потрібно пояснювати все заново.
+ Створено на основі iii engine
+
+ Постійна пам'ять для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode та будь-якого MCP-клієнта.
+
+ Цей gist розширює підхід Karpathy «LLM Wiki», додаючи оцінку довіри, життєвий цикл, графи знань і гібридний пошук: agentmemory — це реалізація цього підходу.
+
+
+---
+
+## Встановлення
+
+Вимоги:
+
+- Node.js 20 або новіше, з npm і npx (`node -v`, `npm -v` та `npx -v`).
+- Автоматичне встановлення iii-engine на macOS/Linux також потребує `curl`, POSIX `sh` та `tar`. Мінімальні образи, такі як `node:20-slim`, можуть не містити їх.
+- Для нативного Windows потрібно вручну встановити закріплену версію iii-engine v0.22.1 `iii.exe`. WSL2 або Docker Desktop — інші підтримувані шляхи.
+
+Канонічна команда для чистого встановлення:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Перший запуск — це інтерактивне налаштування: оберіть агентів для підключення (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), оберіть постачальника LLM або залишайтеся без ключа, після чого створюється конфігурація, запускається сервер пам'яті та закріплений за ним iii engine, і пропонується встановити пакет глобально, щоб команда `agentmemory` надалі працювала будь-де. `-y` приймає запит npx щодо пакета, а `@latest` уникає застарілого кешованого релізу. Постачальник робить доступними можливості LLM, але стиснення спостережень, написане LLM, запускається лише тоді, коли також встановлено `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+Режим без ключа вимикає векторні ембединги. `memory_recall` (шлях `mem::search`) використовує BM25, тоді як `memory_smart_search` також може об'єднувати структурні збіги графа, якщо дані графа вже існують. Щоб безкоштовно отримати семантичне пригадування на пристрої, встановіть `EMBEDDING_PROVIDER=local` у `~/.agentmemory/.env` і перезапустіть. Перший запит ембединга завантажує `Xenova/all-MiniLM-L6-v2`; після цього первинного завантаження моделі обчислення виконуються локально.
+
+Локальний рантайм використовує чотири порти: `3111` для REST/MCP HTTP, `3112` для потоків iii, `3113` для переглядача та `49134` для WebSocket воркера iii. Постійний стан iii зберігається у `~/Library/Application Support/agentmemory` на macOS, у `$XDG_DATA_HOME/agentmemory` або `~/.local/share/agentmemory` на Linux та у `%APPDATA%\agentmemory` на Windows. Використовуйте `--data-dir ` або `AGENTMEMORY_DATA_DIR`, щоб перевизначити це значення, і повторно використовуйте те саме значення під час кожного перезапуску. Для зворотної сумісності наявний `./data/state_store.db` або `./data/iii-config.yaml` має пріоритет над платформовим значенням за замовчуванням для інстансу 0; явний прапорець або змінна середовища все одно перемагають.
+
+Потім перевірте, що пригадування працює, і дайте агенту його скіли:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Пошук за ключовими словами має спрацьовувати в типовому режимі без ключа через BM25. Запит `database performance optimization` у демо навмисно семантичний і може повертати нуль результатів, доки не налаштовано постачальника ембедингів.
+
+Бажаєте доручити все агенту кодування? Дайте йому одну інструкцію:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Підключайте більше агентів у будь-який момент за допомогою `agentmemory connect ` — 20 адаптерів перелічено у розділі [Працює з кожним агентом](#works-with-every-agent). Повний довідник команд — у розділі [Швидкий старт](#quick-start).
+
+
+Windows
+
+Найшвидший шлях — WSL2. Налаштування нативного двигуна Windows вимагає вручну завантажити закріплений ZIP-архів v0.22.1 і розпакувати `iii.exe`; CLI не розпаковує його автоматично. Docker Desktop також підтримується. Покрокову інструкцію дивіться у розділі [Примітки щодо Windows](#windows).
+
+
+
+
+Глобальне встановлення / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Команда npx вище залишається канонічним шляхом для чистого встановлення і дозволяє уникнути проблем із правами доступу до глобального префікса.
+
+
+
+
+npx видає стару версію
+
+npx кешує за версіями. Примусово отримайте останню версію за допомогою `npx -y @agentmemory/agentmemory@latest`, або одноразово очистьте кеш командою `rm -rf ~/.npm/_npx` (macOS/Linux; на Windows видаліть `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+У вас уже працює власний iii engine
+
+agentmemory закріплений за iii-engine v0.22.1 і не підключиться до іншої версії (воркер не може розмовляти протоколом іншого двигуна). Зупиніть інший двигун, потім запустіть `npx -y @agentmemory/agentmemory@latest`. Він встановить і запустить закріплену версію v0.22.1 у `~/.agentmemory/bin`, не торкаючись вашого власного `iii`.
+
+
+
+---
+
+
+
+agentmemory працює з будь-яким агентом, що підтримує хуки, MCP або REST API. Усі агенти використовують один і той самий сервер пам'яті.
+
+
+
+OpenHuman
+нативний бекенд на основі трейта Memory
+
+
+
+
+
+Gemini CLI
+MCP-сервер
+
+
+
+Antigravity
+MCP + хуки
+
+
+
+Claude Desktop
+MCP-сервер
+
+
+
+Warp
+підключення + MCP + скіли
+
+
+
+Zed
+MCP-сервер
+
+
+
+
+
+Cline
+MCP-сервер
+
+
+
+Continue
+MCP-сервер
+
+
+
+Droid
+MCP-сервер
+
+
+
+Kiro
+MCP-сервер
+
+
+
+Qwen Code
+MCP-сервер
+
+
+
+
+
+DeepSeek Harness
+MCP-сервер
+
+
+
+Roo Code
+MCP-сервер
+
+
+
+Kilo Code
+MCP-сервер
+
+
+
+Goose
+MCP-сервер
+
+
+
+Aider
+REST API
+
+
+
+
+
+ Працює з будь-яким агентом, що підтримує MCP або HTTP. Один сервер, пам'ять спільна для всіх них.
+
+
+---
+
+Ви пояснюєте ту саму архітектуру щосесії. Ви повторно виявляєте ті самі помилки. Ви повторно навчаєте агента тим самим уподобанням. Вбудована пам'ять (CLAUDE.md, .cursorrules) обмежена 200 рядками і швидко застаріває. agentmemory вирішує цю проблему. Він непомітно фіксує те, що робить ваш агент, стискає це у пам'ять із можливістю пошуку і вставляє потрібний контекст на початку наступної сесії. Одна команда. Працює між агентами.
+
+**Що змінюється:** у сесії 1 ви налаштували JWT-автентифікацію. У сесії 2 ви просите додати обмеження частоти запитів (rate limiting). Агент уже знає, що ваша автентифікація використовує middleware jose у `src/middleware/auth.ts`, що ваші тести покривають перевірку токенів, і що ви обрали jose замість jsonwebtoken для сумісності з Edge — без повторних пояснень і копіювання.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+За замовчуванням agentmemory зберігає стан iii-engine поза репозиторієм, з якого ви його запускаєте: `~/Library/Application Support/agentmemory` на macOS, `$XDG_DATA_HOME/agentmemory` або `~/.local/share/agentmemory` на Linux та `%APPDATA%\agentmemory` на Windows. Наявний застарілий `./data/state_store.db` або `./data/iii-config.yaml` використовується повторно для інстансу 0 ще до цього платформового значення за замовчуванням. Щоб явно обрати розташування, передайте `--data-dir ` або встановіть `AGENTMEMORY_DATA_DIR`; будь-яке з явних налаштувань має пріоритет над застарілим виявленням:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Нативні запуски та запуски в Docker використовують той самий визначений каталог хоста; Docker монтує його як `/data`. `--instance 1` додає `instance-1` до визначеного каталогу і обирає окремий квартет портів за замовчуванням `3211/3212/3213/49234`.
+
+Примітки до останнього релізу: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Точність пригадування
+
+**coding-agent-life-v1** (власний корпус, відтворюваний у sandbox)
+
+| Адаптер | P@5 | R@5 | Частка влучань у топ-5 | латентність p50 |
+|---|---|---|---|---|
+| **agentmemory (гібридний)** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| базовий варіант grep | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+100% влучань у топ-5 на рівні **математичної межі P@5** для цього корпусу (0.240, див. scorecard). Гібридний режим знаходить усі золоті сесії; grep пропускає 1 з 2 золотих результатів у мультисесійному темпоральному запиті. Прирощення — це **пригадування + темпоральність**, а не агрегована точність. Цей бенчмарк невеликий і має мало золотих прикладів; більший LongMemEval-S нижче краще розрізняє результати. Повна розбивка за типами + примітка про виправлення: [`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% |
+
+
+
+> Модель ембедингів: `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, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Відтворити локально:** [`eval/README.md`](../eval/README.md) — придатний до підключення адаптерів harness для LongMemEval `_s` (публічний набір із 500 запитань) + `coding-agent-life-v1` (власний корпус із 15 сесій). Адаптери grep / vector / agentmemory оцінюються поруч, вивід у форматі NDJSON, опубліковані scorecard потрапляють у [`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).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Вбудована (CLAUDE.md)
+
+
+
Тип
+
Двигун пам'яті + MCP-сервер
+
API шару пам'яті
+
Повноцінний рантайм агента
+
Персональний AI
+
API пам'яті + застосунок
+
Хаб командної пам'яті (LLM-проксі)
+
Векторна пам'ять (OSS)
+
Двигун пам'яті (Oracle DB)
+
Система пам'яті
+
Статичний файл
+
+
+
Пригадування R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
Н/Д
+
Заявлено самостійно
+
PersonaMem 76% (заявлено самостійно)
+
~96.6% (заявлено самостійно)
+
94.4% (заявлено самостійно)
+
Н/Д
+
Н/Д (grep)
+
+
+
Автозахоплення
+
12 хуків (без ручних дій)
+
Ручні виклики add()
+
Самостійне редагування агентом
+
Вручну
+
Видобування на стороні API
+
Перехоплення через проксі (підміна base-URL)
+
Вручну
+
Видобування через API
+
Вручну
+
Ручне редагування
+
+
+
Пошук
+
BM25 + вектор + граф (злиття RRF)
+
Вектор + граф
+
Вектор (архівний)
+
Семантичний
+
Вектор + RAG
+
4 типи активів (Chat / Skill / Wiki / CodeGraph)
+
Лише вектор
+
Вектор + семантичний
+
Зважений за згасанням
+
Завантажує все у контекст
+
+
+
Мультиагентність
+
MCP + REST + оренди + сигнали
+
API (без координації)
+
Лише в межах рантайму Letta
+
Ні
+
Ні
+
Командні ролі + спільні активи
+
Ні
+
Лише в межах скоупу
+
Спільна для кількох агентів
+
Файли для кожного агента
+
+
+
Прив'язка до фреймворку
+
Немає (будь-який MCP-клієнт)
+
Немає
+
Висока (потрібно використовувати Letta)
+
Автономний
+
Немає
+
Проксі обробляє кожен виклик моделі
+
Немає
+
Oracle Database
+
Немає
+
Формат для кожного агента
+
+
+
Зовнішні залежності
+
Немає (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + векторна БД
+
Декілька
+
Керована хмара
+
Docker-стек (Core + Hub + Proxy)
+
Векторне сховище
+
Oracle AI Database
+
Немає
+
Немає
+
+
+
Життєвий цикл пам'яті
+
4-рівнева консолідація + згасання + автозабування
+
Пасивне видобування
+
Керується агентом
+
Вручну
+
Автозабування
+
Ручний перегляд; автоматична маршрутизація в розробці
+
Немає
+
Не вказано
+
Згасання + консолідація
+
Ручне очищення
+
+
+
Ефективність токенів
+
~1,900 токенів/сесію ($10/рік)
+
Залежить від інтеграції
+
Основна пам'ять у контексті
+
Залежить
+
Хмарне ціноутворення
+
Не вказано
+
Без бюджету токенів
+
На основі LLM (залежить)
+
Залежить
+
22K+ токенів при 240 спостереженнях
+
+
+
Переглядач у реальному часі
+
Так (порт 3113)
+
Хмарна панель
+
Хмарна панель
+
Веб-інтерфейс
+
Хмарна панель
+
Веб-інтерфейс Hub
+
Ні
+
Ні
+
Ні
+
Ні
+
+
+
Самостійний хостинг
+
Так (за замовчуванням)
+
Опційно
+
Опційно
+
Так
+
Ні (лише хмара)
+
Так (Docker)
+
Так
+
Так (Oracle DB)
+
Так
+
Так
+
+
+
+Примітка до бенчмарків: лише R@5 для agentmemory — це наш власний вимірений результат (LongMemEval-S, відтворюваний з benchmark/COMPARISON.md). Показники mem0 і Letta — це їхні опубліковані числа LoCoMo (інший набір даних); показники MemPalace, supermemory, TencentDB (PersonaMem) та oracleagentmemory — це заявлені самими постачальниками твердження, які ми не відтворювали самостійно (запуск oracleagentmemory використовував GPT-5.5 проти Oracle AI Database). Наведено поруч лише для орієнтовного порівняння, а не як пряме протистояння на однакових даних. Кількість зірок приблизна і змінюється з часом.
+
+**Новіші учасники**, варті уваги, детально порівняні в [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Система | ⭐ | Підхід |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Темпоральний граф знань; найкращі опубліковані результати для темпоральних запитів (LongMemEval 63.8%), але граф будується асинхронно, тому нові факти можуть надходити із затримкою |
+| Cognee | 30K | Перетворення документів на граф знань, лише Python, створено для структурованого видобування сутностей, а не для захоплення сесій |
+
+Жоден з них не має автозахоплення через хуки агентів кодування, не постачається з локальним переглядачем і не працює без ключа — саме це поєднання лежить в основі agentmemory.
+
+---
+
+
+
+Сумісність: цей реліз орієнтований на `iii-sdk` 0.22.1 і закріплює iii-engine v0.22.1.
+
+### Спробуйте за 30 секунд
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` створює 3 реалістичні сесії (JWT-автентифікація, виправлення запиту N+1, обмеження частоти запитів) і виконує пошук за ними. Встановлення без ключа вимикають вектори, тому запити за ключовими словами `mem::search` мають спрацьовувати через BM25, тоді як `database performance optimization` може повертати нуль результатів. `smart-search` може додатково повертати структурні збіги графа, якщо дані графа існують. Щоб семантичний запит знаходив виправлення N+1 через вектори, встановіть `EMBEDDING_PROVIDER=local`, перезапустіть і дайте завершитися першому завантаженню моделі.
+
+Відкрийте `http://localhost:3113`, щоб спостерігати за побудовою пам'яті в реальному часі.
+
+### Перевірка чистого встановлення та стійкості після перезапуску
+
+Поки сервер працює, перевірте REST, стан здоров'я, переглядач і статус рантайму на основі iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Панель готовності під час запуску охоплює всі чотири порти: REST/MCP HTTP на 3111, потоки iii на 3112, переглядач на 3113 та WebSocket воркера iii на 49134. `status` підтверджує стан здоров'я agentmemory та активний режим постачальника/ембедингів. Збережіть тестовий запис і перевірте, що його можна знайти:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Потім виконайте `npx -y @agentmemory/agentmemory@latest stop`, знову запустіть канонічну команду в терміналі 1, дочекайтеся `/agentmemory/livez` і повторіть пошук. Тестовий запис має й надалі повертатися. Якщо ви обрали власний `--data-dir`, передайте той самий каталог під час перезапуску.
+
+### Щоденні команди
+
+Встановлення та налаштування описані в розділі [Встановлення](#install) вище (перший запуск проведе вас через цей процес). Щодня:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Відтворення сесій
+
+Кожну сесію, яку записує agentmemory, можна відтворити. Відкрийте переглядач, оберіть вкладку **Replay** і прогортайте часову шкалу: промпти, виклики інструментів, результати інструментів і відповіді відображаються як окремі події з керуванням відтворення/паузи, регулюванням швидкості (від 0.5x до 4x) і клавіатурними скороченнями (пробіл — перемкнути, стрілки — покроково).
+
+Щоб імпортувати старіші JSONL-транскрипти Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Імпортовані сесії з'являються в переліку Replay поруч із нативними. Під капотом кожен запис проходить через функції iii `mem::replay::load`, `mem::replay::sessions` і `mem::replay::import-jsonl`, без будь-яких побічних серверів. Кожен імпортований транскрипт індексується для пошуку, позначається каналом походження `import` і аналізується для створення кристала сесії та уроків.
+
+> **Важливо, якщо ви покладаєтеся на `import-jsonl` як на основний шлях захоплення:** `cleanupPeriodDays` Claude Code (у `~/.claude/settings.json`, за замовчуванням **30**) автоматично видаляє JSONL-транскрипти, старіші за це вікно, з `~/.claude/projects/`. Якщо ви встановлюєте agentmemory на вже кількамісячну історію Claude Code, усе старіше за 30 днів уже зникло ще до першого імпорту. Або запускайте `import-jsonl` за розкладом (cron), або підвищте `cleanupPeriodDays`, або підключіть хуки автозахоплення (типовий шлях встановлення плагіна), щоб кожен крок потрапляв в agentmemory, поки сесія активна, і очищення JSONL більше не мало значення.
+
+### Оновлення / обслуговування
+
+Використовуйте команду обслуговування, коли ви свідомо хочете оновити свій локальний рантайм:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Попередження: ця команда змінює поточний робочий простір/рантайм. Вона може оновити залежності JavaScript і завантажити закріплений Docker-образ `iiidev/iii:0.22.1`. Вона ніколи не встановлює незакріплений або новіший iii engine.
+
+Деталі реалізації містяться в `src/cli.ts` (див. `runUpgrade` у межах `src/cli.ts:544-595`).
+
+### Claude Code (один блок, вставте як є)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code без встановлення плагіна (автономний шлях MCP)
+
+Якщо ви підключаєте MCP-сервер agentmemory напряму через `~/.claude.json`, а не через `/plugin install`, Claude Code ніколи не розгортає `${CLAUDE_PLUGIN_ROOT}`, і вам доведеться вказувати абсолютні шляхи до скриптів хуків у `~/.claude/settings.json`. Ці шляхи, як правило, містять версію agentmemory (наприклад, `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), тому наступне оновлення непомітно зламає кожен хук.
+
+Обхідне рішення:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Ця команда об'єднує ті самі команди хуків у `~/.claude/settings.json`, використовуючи абсолютні шляхи, визначені до вбудованого каталогу `plugin/` наразі встановленого пакета `@agentmemory/agentmemory`. Повторно запустіть команду після оновлення agentmemory, щоб оновити шляхи. Записи користувача в тому самому файлі зберігаються; замінюються лише попередні записи agentmemory. Шлях через `/plugin install` залишається рекомендованим підходом.
+Для віддалених або захищених розгортань запускайте Claude Code зі встановленими `AGENTMEMORY_URL` та `AGENTMEMORY_SECRET`. Плагін передає обидва значення своєму вбудованому MCP-серверу; якщо `AGENTMEMORY_URL` порожній, MCP-шим використовує `http://localhost:3111`.
+
+### Codex CLI (платформа плагінів Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Плагін Codex постачається з того самого каталогу `plugin/`, що й плагін Claude Code. Він реєструє:
+
+- Вбудований stdio MCP-мост до запущеного демона, без завантаження через npm і без локального резервного сховища. Див. [локальний посібник Codex](../docs/plugins/codex-local.md), щоб протестувати нерелізну збірку.
+- 6 хуків життєвого циклу: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 викликаних скілів: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, а також 8 довідкових скілів, які агент завантажує за потреби (дисципліна пам'яті, інструменти MCP, REST API, конфігурація, агенти, хуки, архітектура та посібник зі створення скілів)
+
+Механізм хуків Codex вставляє `CLAUDE_PLUGIN_ROOT` у підпроцеси хуків (згідно з [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), тому ті самі скрипти хуків працюють для обох хостів без дублювання. Події Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure доступні лише для Claude Code і не реєструються для Codex.
+
+#### Довіра до хуків Codex та сумісність
+
+Нативна диспетчеризація хуків плагіна підтверджена для Codex CLI 0.150.1. Перш ніж очікувати захоплення, підтвердьте довіру до хуків плагіна. Поведінка Codex Desktop залежить від вбудованого в нього середовища виконання; перевірте `/hooks` і підтвердьте захоплену подію, перш ніж застосовувати обхідне рішення.
+
+Якщо ваш хост вимагає глобальних хуків, продзеркаліть команди у `~/.codex/hooks.json`. Якщо MCP уже підключено, поточному конектору потрібен `--force`, щоб дістатися встановлення хуків:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Це об'єднує глобальні хуки та перезаписує запис MCP agentmemory, зберігаючи незв'язані записи. Перевірте власні налаштування endpoint agentmemory, перш ніж використовувати `--force`. Запустіть повторно після оновлення, щоб оновити шляхи скриптів. Увімкніть або нативні хуки плагіна, або глобальні копії, щоб уникнути дублювання захоплення.
+
+### GitHub Copilot CLI
+
+Для режиму агента VS Code скористайтеся [посібником з MCP та автозахоплення Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Конектор CLI не налаштовує VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Альтернативно, повний плагін хуків/скілів з підкаталогу GitHub
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` об'єднує `mcpServers.agentmemory` з `~/.copilot/mcp-config.json` (або `$COPILOT_HOME/mcp-config.json`, якщо встановлено `COPILOT_HOME`) і зберігає наявні сервери. У нативному Windows це єдиний автоматизований адаптер `connect`; усіх інших нативних агентів Windows потрібно налаштовувати вручну. `connect` у WSL підтримується лише тоді, коли цільовий агент встановлено в тому самому середовищі WSL. Copilot підхоплює MCP-сервер під час наступного запуску або після `/mcp`. Встановіть також плагін, якщо хочете отримати повний досвід роботи з хуками/скілами.
+
+
+OpenClaw (вставте цей промпт)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Повний посібник: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (вставте цей промпт)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Повний посібник: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Інші агенти
+
+Запустіть сервер пам'яті: `npx -y @agentmemory/agentmemory@latest`
+
+#### Нативні скіли через `npx skills add` (50+ агентів)
+
+agentmemory постачає 17 скілів у форматі `/SKILL.md` у стилі Claude Code: 9 викликаних скілів-дій (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) і 8 довідкових скілів, які агент завантажує за потреби (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Довідкові скіли містять таблиці даних, згенеровані з джерела, тому вони ніколи не розходяться з ним. CLI [`skills`](https://npmjs.com/package/skills) від vercel-labs автоматично встановлює їх у нативний каталог скілів агента, що викликає, для понад 50 агентів (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf та інших):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Це **доповнює** `agentmemory connect `:
+
+- `agentmemory connect ` записує конфігурацію MCP-сервера, щоб інструменти стали доступними.
+- `npx skills add rohitg00/agentmemory` встановлює скіли, щоб агент знав, коли їх викликати.
+
+Для декількох агентів, які CLI skills ще не підтримує (Zed v1.3.x і нижче), розмістіть 17 файлів SKILL.md у нативному каталозі скілів агента самостійно; той самий формат працює всюди.
+
+#### Стандартний блок MCP
+
+Запис agentmemory — це **той самий блок MCP-сервера** для кожного хоста, що використовує структуру `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Об'єднайте цей запис із наявним об'єктом `mcpServers`** у конфігураційному файлі хоста; не замінюйте файл повністю. Якщо файл уже містить інші сервери, додайте `agentmemory` поруч як ще один ключ усередині `mcpServers`. Якщо `mcpServers` взагалі відсутній, вставте блок усередину `{ "mcpServers": { ... } }`. Заповнювачі `${VAR}` успадковують `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` з оболонки під час запуску MCP-сервера; невстановлені змінні передають порожні рядки, і шим переходить на `http://localhost:3111`. Один підключений запис охоплює як локальні, так і віддалені (k8s / за реверс-проксі) розгортання.
+
+| Агент | Конфігураційний файл | Примітки |
+|---|---|---|
+| **Cursor (лише MCP)** | `~/.cursor/mcp.json` | Об'єднайте з `mcpServers`, або скористайтеся `agentmemory connect cursor`. На сайті також доступне глибоке посилання в один клік. |
+| **Cursor (повний плагін)** | `.cursor-plugin/` | Запис у Cursor Marketplace (на розгляді) або Cursor Settings → Plugins → локальний checkout. Реєструє 7 хуків автозахоплення (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 скілів + MCP-сервер, із `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`, керованими в панелі плагінів Cursor. Працює в Cursor IDE та CLI `cursor-agent`; промпти режиму print у CLI доповнюються з транскрипту сесії в кінці сесії. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Об'єднайте з `mcpServers`. Перезапустіть Claude Desktop після редагування. |
+| **Cline / Roo Code / Kilo Code** | Налаштування MCP Cline (Settings UI → MCP Servers → Edit) | Той самий блок `mcpServers`. |
+| **Devin CLI (MCP + хуки)** | `~/.config/devin/config.json` | `agentmemory connect devin` об'єднує запис MCP; `--with-hooks` додає шість нативних хуків автозахоплення (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) із відповідниками інструментів Devin у нижньому регістрі. Перевірте за допомогою `devin mcp list` та `/hooks` усередині devin. |
+| **Devin CLI (повний плагін)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` з checkout реєструє всі 17 скілів як слеш-команди `/agentmemory:` разом із MCP-сервером. Хуки плагіна Devin не можуть викликати `SessionStart`/`SessionEnd`, тому поєднуйте це з `connect devin --with-hooks` для повного захоплення сесії. |
+| **Devin (хмара)** | Settings → Connections → MCP servers | Додайте власний MCP (STDIO): команда `npx`, аргументи `-y @agentmemory/mcp@latest`, змінна середовища `AGENTMEMORY_URL`, що вказує на доступне в мережі розгортання agentmemory, плюс `AGENTMEMORY_SECRET` (хмарні сесії не можуть дістатися localhost — див. [`deploy/`](../deploy/)). Збережіть секрет у Devin Secrets, потім скористайтеся «Test listing tools», щоб перевірити появу всіх 54 інструментів. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (об'єднує автоматично). |
+| **GitHub Copilot CLI (лише MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` об'єднує `mcpServers.agentmemory`; Copilot підхоплює це під час наступного запуску або через `/mcp`. |
+| **GitHub Copilot CLI (повний плагін)** | Встановлення плагіна Copilot | `copilot plugin install rohitg00/agentmemory:plugin` для плагіна з підкаталогу GitHub. |
+| **OpenClaw** | Конфігурація MCP OpenClaw | Той самий блок `mcpServers`. Глибше: `openclaw plugins install ./integrations/openclaw` займає слот пам'яті OpenClaw (автоматично перемикається з `memory-core`); встановіть `plugins.entries.agentmemory.hooks.allowConversationAccess=true`, інакше захоплення кроків буде непомітно блокуватися. Див. [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (лише MCP)** | `.codex/config.toml` | Формат TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, або додайте `[mcp_servers.agentmemory]` вручну. |
+| **Codex CLI (повний плагін)** | Marketplace плагінів Codex | `codex plugin marketplace add rohitg00/agentmemory`, потім `codex plugin add agentmemory@agentmemory`. Реєструє MCP + 6 хуків життєвого циклу + 17 скілів. Підтвердьте довіру до хуків і перевірте захоплення на вашому хості; див. [налаштування та перевірку Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (лише MCP)** | `opencode.json` | Інший формат: ключ `mcp` на верхньому рівні, команда у вигляді масиву: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (повний плагін)** | `plugin/opencode/` | 22 хуки автозахоплення, що охоплюють життєвий цикл сесії, повідомлення, інструменти, помилки. Атрибуція проєкту відбувається для кожної сесії окремо, тому один процес OpenCode, що охоплює декілька репозиторіїв, фіксує кожну сесію під власним проєктом. Дві слеш-команди (`/recall`, `/remember`). Скопіюйте `plugin/opencode/` у ваш робочий простір OpenCode і додайте запис плагіна до `opencode.json`. Повну таблицю хуків + аналіз прогалин див. у [`plugin/opencode/README.md`](../plugin/opencode/README.md). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` встановлює вбудоване розширення в каталог автовиявлення pi (пригадування на старті агента, захоплення в кінці роботи агента, інструменти `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` у запущеному pi підхоплює це. [`integrations/pi`](../integrations/pi/) — це також пакет pi (`pi install ./integrations/pi` з checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` дає постачальника пам'яті з 6 хуками (попереднє отримання, захоплення кроку, завершення сесії, передстиснення, дзеркалювання MEMORY.md, блок системного промпту). Перевірте за допомогою `hermes plugins doctor` та `hermes memory status`. Див. [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` записує стандартний блок `mcpServers`. Корисне навантаження хука сумісне за полями з Claude Code, тому наявні скрипти для 12 хуків працюють без змін; підключіть їх через розділ `hooks` у тому самому `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` встановлює MCP і хуки захоплення у спільному каталозі налаштувань. Див. [налаштування та обмеження Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` використовує ту саму конфігурацію MCP і хуків, що й поточні версії IDE. Наявні встановлення слід оновити за допомогою `--force`; див. [примітки щодо оновлення](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` записує конфігурацію рівня користувача. Перевизначення на рівні робочого простору розміщуються в `.kiro/settings/mcp.json` поруч із вашим кодом. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` записує стандартний блок `mcpServers`. Warp також автоматично виявляє скіли з `.claude/skills/`; після встановлення плагіна Claude Code 8 скілів agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) з'являються нативно в палітрі слеш-команд Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` записує стандартний блок `mcpServers`. Користувачі розширення VS Code: вставте той самий блок через Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (бажано) або `config.json` (застарілий) | `agentmemory connect continue` створює `config.yaml` з нуля, якщо жоден з файлів не існує, або змінює наявний `config.json`. **Якщо у вас уже є `config.yaml`**, адаптер виводить точний блок для вставки під `mcpServers:`; він не перезаписує ваш yaml непомітно, тому що безпечне збереження коментарів і якорів потребує парсера YAML, якого немає в пакеті. Continue використовує для `mcpServers` форму масиву (а не об'єкта). |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` записує дані під `context_servers` (ключ Zed, НЕ `mcpServers`). Віддалені MCP-сервери замість цього можна підключити через `{"url": "..."}`. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` записує стандартний блок `mcpServers`. Перевизначення на рівні проєкту розміщуються в `/.factory/mcp.json`. Передайте `--with-hooks` для нативного автозахоплення. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` додає рядок `@deepseek-ai/dsh-mcp-client` до шару патчів рівня home, який завантажує кожен профіль Harness; інструменти реєструються як `mcp__agentmemory__*`. Передайте `--with-hooks`, щоб також підключити автозахоплення: вбудовані скрипти хуків Claude Code працюють через власний місток Harness `@deepseek-ai/dsh-hooks-claude-code` (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) через маніфест, записаний у `$DSH_HOME/agentmemory.hooks.json`. За замовчуванням використовує `~/.dsh`, якщо `DSH_HOME` не встановлено. |
+| **Goose** | Інтерфейс налаштувань MCP Goose | Той самий блок `mcpServers`; скористайтеся `goose configure` → Add Extension → MCP. Пряме редагування YAML у `~/.config/goose/config.yaml` підтримується, але схема використовує `extensions:` + `cmd` (а не `mcpServers:` + `command`). |
+| **Aider** | н/д | Звертайтеся напряму до REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Будь-який агент (32+)** | н/д | `npx skillkit install agentmemory` автоматично визначає хост і об'єднує конфігурацію. |
+
+**MCP-клієнти в sandbox** (Flatpak / Snap / обмежувальні контейнери), які не можуть дістатися `localhost` хоста: також встановіть `"AGENTMEMORY_FORCE_PROXY": "1"` у блоці `env` та вкажіть у `AGENTMEMORY_URL` маршрут, якого sandbox справді може досягти (наприклад, вашу IP-адресу в LAN).
+
+### Програмний доступ (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/) (швидкий старт + потік спостереження/пригадування). REST на `:3111` залишається доступним для хостів без рантайму iii.
+
+### Зі джерельного коду
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Це запускає agentmemory з локальним `iii-engine`, якщо закріплений бінарний файл уже встановлено, або використовує Docker Compose, якщо його обрано. REST, потоки та переглядач за замовчуванням прив'язуються до `127.0.0.1`. Автоматичний шлях встановлення бінарного файлу на macOS/Linux вимагає `curl`, POSIX `sh` та `tar`.
+
+Встановіть `iii-engine` вручну. **agentmemory наразі закріплений за `iii-engine` версії `v0.22.1`**, тим самим релізом, що й залежність `iii-sdk`; воркер розмовляє протоколом саме цього двигуна, а 0.20.0 реорганізував поверхню SDK, тому ці дві версії рухаються разом у релізах agentmemory. Перевизначте за допомогою `AGENTMEMORY_III_VERSION=`, якщо ви запускаєте власний двигун і знаєте, що він відповідає.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** замініть `aarch64-apple-darwin` на `x86_64-apple-darwin`
+- **Linux x64:** замініть на `x86_64-unknown-linux-gnu`
+- **Linux arm64:** замініть на `aarch64-unknown-linux-gnu`
+- **Windows:** завантажте `iii-x86_64-pc-windows-msvc.zip` з [релізів iii-hq/iii v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) і розпакуйте `iii.exe` у `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Кожен архів має відповідний файл `.sha256` на сторінці релізу; коли ви змінюєте платформу, використовуйте хеш із цього файлу в перевірці вище (на Windows: `Get-FileHash`). Автоматичний встановлювач у `npx @agentmemory/agentmemory` закріплює ці хеші і відмовляється від архіву, який не відповідає.
+
+Або скористайтеся Docker (вбудований `docker-compose.yml` завантажує `iiidev/iii:0.22.1`). Повна документація: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory працює на Windows 10/11, але самого пакета Node.js недостатньо; вам також потрібен закріплений рантайм iii-engine v0.22.1 як фоновий процес. CLI не розпаковує Windows ZIP автоматично, тому користувачі нативного Windows мають встановити `iii.exe` вручну, скористатися WSL2 або обрати Docker Desktop.
+
+Автоматизоване підключення MCP у нативному Windows підтримує лише `agentmemory connect copilot-cli`. Для Claude Code, Codex, Cursor та будь-якого іншого нативного агента Windows скопіюйте ручний блок MCP з розділу [Інші агенти](#other-agents) у конфігурацію цього агента на Windows. Запуск `connect` у WSL доречний лише тоді, коли цільовий агент також встановлено в тому самому середовищі WSL; він не редагує конфігурацію агента, що працює на хості Windows.
+
+**Варіант A: готовий бінарний файл для Windows (рекомендовано)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Варіант B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Варіант C: лише автономний MCP (без двигуна).** Якщо вам потрібні лише інструменти MCP для вашого агента і не потрібні REST API, переглядач або завдання cron, повністю обійдіться без двигуна:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Діагностика для Windows:** якщо `npx -y @agentmemory/agentmemory@latest` завершується помилкою, повторно запустіть з `--verbose`, щоб побачити фактичний stderr двигуна. Поширені режими відмов:
+
+| Симптом | Виправлення |
+|---|---|
+| `The engine process started but the REST API never responded.` | Переконайтеся, що всі чотири похідні порти вільні, перевірте, що закріплений `iii.exe` не завершився, потім повторно запустіть з `--verbose` і перегляньте захоплений stderr двигуна |
+| `Could not start iii-engine` | Не встановлено ні `iii.exe`, ні Docker. Див. варіант A або B вище |
+| Конфлікт порту | `netstat -ano \| findstr :3111`, щоб побачити, що зайняте, потім завершіть цей процес або скористайтеся `--port ` |
+| Резервний варіант Docker пропущено, навіть якщо Docker встановлено | Переконайтеся, що Docker Desktop справді запущено (значок у треї) |
+
+> Примітка: iii **engine** — це готовий бінарний файл, а не cargo crate, тож не намагайтеся виконати для нього `cargo install`. (iii **SDK** опубліковані на crates.io, npm та PyPI, але agentmemory вони не потрібні.) Усі підтримувані способи встановлення двигуна закріплені за v0.22.1: готовий бінарний файл вище, шлях автовстановлення agentmemory для macOS/Linux (потрібні `curl`, POSIX `sh` та `tar`) та Docker-образ `iiidev/iii:0.22.1`. Звичайний `install.sh | sh` з основного репозиторію встановлює найновіший двигун, який agentmemory не підтримує. Використовуйте `npx -y @agentmemory/agentmemory@latest`; на macOS/Linux ця команда завантажує закріплений двигун у `~/.agentmemory/bin`.
+
+---
+
+
Розгортання
+
+Шаблони в один клік для керованих хостів. Кожен із них постачається із
+самодостатнім Dockerfile, який завантажує `@agentmemory/agentmemory` з npm і копіює
+бінарний файл двигуна iii з офіційного образу Docker Hub `iiidev/iii`;
+заздалегідь зібраний образ agentmemory не потрібен. Постійне сховище
+монтується в `/data`; точка входу першого завантаження перезаписує
+вбудовану в npm-пакет конфігурацію iii (яка прив'язується до
+`127.0.0.1`) налаштованою для розгортання версією, що прив'язується до
+`0.0.0.0` та використовує абсолютні шляхи `/data`, генерує секрет HMAC,
+а потім знижує привілеї з `root` до `node` через
+`gosu` перед виконанням CLI agentmemory.
+
+
+
+
+
+
+Кнопка розгортання в один клік для Render вимагає `render.yaml` у корені репозиторію, який ми свідомо тримаємо чистим. Скористайтеся процесом Render Blueprint, описаним у [`deploy/render/`](.././deploy/render/README.md), щоб вручну вказати на 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): самостійний хостинг на
+ власному VPS через [Coolify](https://coolify.io/self-hosted); той самий Docker
+ Compose-стек, хост і дані залишаються у вас.
+
+Публікується лише порт `3111`. Переглядач на `3113` стає
+прив'язаним до loopback усередині контейнера; README кожного шаблону документує
+схему SSH-тунелю для доступу до нього.
+
+---
+
+
+
+Кожен агент кодування забуває все, коли сесія закінчується, і кожна нова сесія починається з того, що ви повторно пояснюєте свій стек. 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 — notepads, у Cline — memory bank. Вони працюють як стікери-нагадування. agentmemory — це база даних із можливістю пошуку, що стоїть за цими стікерами.
+
+| | Вбудована (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Масштаб | Обмеження 200 рядків | Без обмежень |
+| Пошук | Завантажує все у контекст | BM25 + вектор + граф (лише топ-K) |
+| Вартість у токенах | 22K+ при 240 спостереженнях | ~1,900 токенів (на 92% менше) |
+| Між агентами | Файли для кожного агента | MCP + REST (будь-який агент) |
+| Координація | Немає | Оренди, сигнали, дії, рутини |
+| Спостережуваність | Читання файлів вручну | Переглядач у реальному часі на :3113 |
+
+---
+
+
+
+### Конвеєр пам'яті
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-рівнева консолідація пам'яті
+
+Побудовано за зразком того, як людський мозок обробляє пам'ять, включно з консолідацією під час сну.
+
+| Рівень | Що | Аналогія |
+|------|------|---------|
+| **Робочий (Working)** | Необроблені спостереження з використання інструментів | Короткочасна пам'ять |
+| **Епізодичний (Episodic)** | Стиснуті підсумки сесій | «Що сталося» |
+| **Семантичний (Semantic)** | Видобуті факти та закономірності | «Що я знаю» |
+| **Процедурний (Procedural)** | Робочі процеси та шаблони рішень | «Як це робити» |
+
+Пам'ять згасає з часом (крива Еббінгауза). Часто використовувана пам'ять зміцнюється. Застарілі записи пам'яті автоматично витісняються. Суперечності виявляються й вирішуються.
+
+### Що фіксується
+
+| Хук | Фіксує |
+|------|----------|
+| `SessionStart` | Шлях до проєкту, ID сесії |
+| `UserPromptSubmit` | Промпти користувача (з фільтром приватності) |
+| `PreToolUse` | Шаблони доступу до файлів + збагачений контекст |
+| `PostToolUse` | Назву інструменту, вхідні та вихідні дані |
+| `PostToolUseFailure` | Контекст помилки |
+| `PreCompact` | Повторно вставляє пам'ять перед компактуванням |
+| `SubagentStart/Stop` | Життєвий цикл субагента |
+| `Stop` | Підсумок завершення сесії |
+| `SessionEnd` | Маркер завершення сесії |
+
+### Ключові можливості
+
+| Можливість | Опис |
+|---|---|
+| **Автоматичне захоплення** | Кожне використання інструменту записується через хуки, без ручних дій |
+| **Семантичний пошук** | BM25 + вектор + граф знань зі злиттям RRF |
+| **Еволюція пам'яті** | Версіювання, заміщення, графи зв'язків |
+| **Гігієна пригадування** | Заміщені версії пам'яті зникають з пошукових індексів; ланцюжок версій у KV зберігає повну історію |
+| **Підказки про близькі дублікати** | Збереження повідомляє про рекомендаційний збіг `similarTo`, коли новий контент сильно нагадує наявну пам'ять |
+| **Скоупінг для кожного агента** | `agentId` проходить через збереження та пригадування в REST, MCP та пошуковому індексі, у спільному або ізольованому режимі |
+| **Походження на момент запису** | Кожне спостереження та запис пам'яті несе незмінний канал походження (користувач, агент, інструмент, імпорт або спільний доступ), зафіксований під час захоплення, збереження та імпорту |
+| **Автозабування** | Закінчення TTL, виявлення суперечностей, витіснення за важливістю |
+| **Приватність понад усе** | API-ключі, секрети, теги `` видаляються перед збереженням |
+| **Самовідновлення** | Circuit breaker, ланцюжок резервних постачальників, моніторинг стану |
+| **Місток до Claude** | Двостороння синхронізація з MEMORY.md |
+| **Граф знань** | Видобування сутностей + обхід у ширину (BFS) |
+| **Командна пам'ять** | Спільна + приватна пам'ять з просторами імен для членів команди |
+| **Походження цитат** | Простежуйте будь-яку пам'ять до вихідних спостережень |
+| **Знімки Git** | Версіювання, відкат і diff стану пам'яті |
+
+---
+
+
+
+Потрійний потік пошуку, що поєднує три сигнали:
+
+| Потік | Що робить | Коли |
+|---|---|---|
+| **BM25** | Пошук за ключовими словами зі стеммінгом та розширенням синонімів | Завжди активний |
+| **Вектор** | Косинусна подібність для щільних ембедингів | Налаштовано постачальника ембедингів |
+| **Граф** | Обхід графа знань через збіг сутностей | У запиті виявлено сутності |
+
+Об'єднується за допомогою Reciprocal Rank Fusion (RRF, k=60) і диверсифікується за сесіями (максимум 3 результати на сесію).
+
+Коли векторний індекс заповнено, `mem::search` (що стоїть за `memory_recall`) використовує гібридний ранжувальник BM25 + вектор. Без ембедингів він використовує BM25. `smart-search` може додатково об'єднувати структурні збіги графа, якщо дані графа існують, зокрема в режимі без ключа. Пригадування уроків виконується на окремому BM25-індексі в пам'яті, а не шляхом сканування всього корпусу під час кожного запиту. Заміщені версії пам'яті виключаються з усіх шляхів пригадування; ланцюжок версій зберігає їхню історію.
+
+Вектори переживають збій або примусове завершення. Векторний індекс зберігається пакетами не частіше, ніж кожні `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 хвилин). Кожен вектор, доданий або видалений у проміжку, також відразу записується у невеликий журнал очікування в хранилищі стану, і наступний запуск відтворює його без звернення до постачальника ембедингів. Кожне успішне збереження очищає журнал. Документи, які все ще не мають вектора після відтворення, повторно ембедяться у фоновому режимі партіями по `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500), доки не залишиться жодного, а зупинене доповнення продовжується з наступного запуску. `/agentmemory/status` і переглядач показують розмір журналу очікування та стан доповнення. Встановлення без ключа нічого не записують.
+
+BM25 одразу токенізує грецьку, кирилицю, іврит, арабську та латиницю з діакритикою. Для пам'яті китайською / японською / корейською встановіть опційні сегментатори (`npm install @node-rs/jieba tiny-segmenter`), щоб розбивати послідовності CJK на токени рівня слів; без них agentmemory плавно переходить на токенізацію цілими послідовностями та одноразово виводить підказку в stderr.
+
+### Постачальники ембедингів
+
+Встановлення без ключа вимикають векторні ембединги: `mem::search` використовує BM25, тоді як `smart-search` також може використовувати наявні структурні дані графа. Щоб безкоштовно підключити семантичні ембединги на пристрої, додайте це до `~/.agentmemory/.env` і перезапустіть agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Звичайне встановлення npm включає опційний рантайм `@huggingface/transformers`. Перший запит ембединга завантажує `Xenova/all-MiniLM-L6-v2`, тому потребує доступу до мережі й може займати більше часу; подальші обчислення виконуються на пристрої. Віддалені постачальники автоматично визначаються за їхніми ключами, якщо `EMBEDDING_PROVIDER` не перевизначає їх.
+
+| Постачальник | Модель | Вартість | Примітки |
+|---|---|---|---|
+| **Локальний (рекомендоване підключення)** | `all-MiniLM-L6-v2` | Безкоштовно | На пристрої після першого завантаження моделі, +8пп до пригадування порівняно з лише BM25 |
+| Gemini | `gemini-embedding-001` | Безкоштовний тариф | 100+ мов, 768/1536/3072 вимірів (MRL), вхід до 2048 токенів. Замінює `text-embedding-004` ([застаріла, вимкнення 14 січня 2026](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 | Будь-яка модель | Залежить | Проксі для декількох моделей |
+
+---
+
+
+
+54 інструменти, 6 ресурсів, 3 промпти та 17 скілів.
+
+> **MCP-шим проти повного сервера:** опублікований пакет `@agentmemory/mcp` — це тонкий шим. Він надає повну поверхню з 54 інструментів **лише тоді, коли може дістатися запущеного сервера agentmemory** через `AGENTMEMORY_URL` (режим проксі). Якщо жоден сервер недоступний, шим переходить на локальний набір із 7 інструментів (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Змінна середовища `AGENTMEMORY_TOOLS=core|all` — це прапорець *на боці сервера*; встановлення його в блоці `env` шима не має ефекту. Якщо ви бачите лише 7 інструментів у Cursor / OpenCode / Gemini CLI, запустіть `npx -y @agentmemory/agentmemory@latest` (або стек Docker) і встановіть `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 інструменти
+
+Три поверхні інструментів, від найменшої до найбільшої: `AGENTMEMORY_TOOLS=core` обмежує видимість до 8 основних (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); базовий набір нижче — це 14 фундаментальних інструментів реєстру; типовий режим (`AGENTMEMORY_TOOLS=all`) надає всі 54.
+
+
+Базові інструменти (14)
+
+| Інструмент | Опис |
+|------|-------------|
+| `memory_recall` | Пошук минулих спостережень |
+| `memory_compress_file` | Стиснення markdown-файлів зі збереженням структури |
+| `memory_save` | Збереження інсайту, рішення або шаблону |
+| `memory_file_history` | Минулі спостереження щодо конкретних файлів |
+| `memory_patterns` | Виявлення повторюваних шаблонів |
+| `memory_sessions` | Перелік останніх сесій |
+| `memory_smart_search` | Гібридний семантичний + ключовий пошук |
+| `memory_vision_search` | Пошук спостережень із зображеннями |
+| `memory_timeline` | Хронологічні спостереження |
+| `memory_profile` | Профіль проєкту (концепти, файли, шаблони) |
+| `memory_export` | Експорт усіх даних пам'яті |
+| `memory_relations` | Запит графа зв'язків |
+| `memory_commit_lookup` | Сесії, що стоять за git-комітом |
+| `memory_commits` | Коміти, записані для сесії |
+
+
+
+
+Розширені інструменти (54 загалом, типова поверхня)
+
+| Інструмент | Опис |
+|------|-------------|
+| `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` | Запит за фасетними тегами |
+| `memory_verify` | Простеження походження |
+
+
+
+### 6 ресурсів · 3 промпти · 17 скілів
+
+| Тип | Назва | Опис |
+|------|------|-------------|
+| Ресурс | `agentmemory://status` | Стан здоров'я, кількість сесій, кількість записів пам'яті |
+| Ресурс | `agentmemory://project/{name}/profile` | Аналітика для конкретного проєкту |
+| Ресурс | `agentmemory://project/{name}/recent` | Останні спостереження для проєкту |
+| Ресурс | `agentmemory://memories/latest` | 10 останніх активних записів пам'яті |
+| Ресурс | `agentmemory://graph/stats` | Статистика графа знань |
+| Ресурс | `agentmemory://team/{id}/profile` | Спільний командний профіль |
+| Промпт | `recall_context` | Пошук + повернення контекстних повідомлень |
+| Промпт | `session_handoff` | Передача даних між агентами |
+| Промпт | `detect_patterns` | Аналіз повторюваних шаблонів |
+| Скіл | `/recall` | Пошук у пам'яті |
+| Скіл | `/remember` | Збереження в довгострокову пам'ять |
+| Скіл | `/session-history` | Підсумки останніх сесій |
+| Скіл | `/forget` | Видалення спостережень/сесій |
+
+У таблиці показано чотири основні скіли. Повний набір — це 9 викликаних скілів плюс 8 довідкових скілів; див. розділ про нативні скіли вище.
+
+### Автономний MCP
+
+Запуск без повного сервера, для будь-якого MCP-клієнта. Працює будь-який із варіантів:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Або додайте до конфігурації MCP вашого агента:
+
+Більшість агентів (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Об'єднайте запис `agentmemory` з наявним об'єктом `mcpServers` вашого хоста, а не замінюйте файл. Для клієнтів у sandbox, які не можуть дістатися `localhost` хоста, додайте `"AGENTMEMORY_FORCE_PROXY": "1"` до блоку env та встановіть у `AGENTMEMORY_URL` маршрут, до якого sandbox може дістатися.
+
+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/
+```
+
+---
+
+
+
+Автоматично запускається на порту `3113`. Переглядач завантажує один знімок під час підключення (`GET /agentmemory/viewer/snapshot`), а потім застосовує події живого потоку: нові записи пам'яті, уроки, спостереження, записи аудиту, зміни графа та оновлення стану здоров'я з'являються без опитування чи перезавантаження сторінки. Інші запити — лише ті дії, які ви клацаєте, сторінки «завантажити ще» та пошукові запити. Коли потік перериваться, переглядач показує, наскільки застарілими є його дані, перепідключається з наростанням інтервалу (backoff) і повторно синхронізується з одного знімка.
+
+- **12 вкладок у чотирьох групах** із показниками в реальному часі, глибокими посиланнями (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), клавіатурними скороченнями та мобільним меню.
+- **Memories (Пам'ять):** пошук на стороні сервера, фільтри за проєктом, агентом і типом, панель деталей із ланцюжком версій і порівнянням слів, посилання на походження, кнопки копіювання для id, виклику MCP та команди curl, редагування (нова версія), забування з підтвердженням, масове забування та експорт у JSON.
+- **Sessions (Сесії):** вбудована часова шкала спостережень із читабельними вхідними та вихідними даними інструментів, фільтри та пагінація, а також записи пам'яті та уроки, створені кожною сесією.
+- **Graph (Граф):** пошук, деталі вузла зі зв'язками та джерелами, легенда, що не покладається лише на колір, та керування масштабом.
+- **Health (Стан здоров'я):** жива версія `GET /agentmemory/status`. Кожна проблема супроводжується своїм виправленням, а також бекендом стану, станом збереження індексу, прогресом компактування походження графа та поясненням консолідації з реальними порогами.
+- Сторінки **Audit (Аудит), Activity (Активність), Profile (Профіль), Replay (Відтворення), Lessons (Уроки), Actions (Дії) та Crystals (Кристали)**, кожна з порожнім станом, що пояснює, що це за розділ, чому він порожній і яка команда заповнить його, а також підказка-глосарій `?` для кожного терміну і числа.
+
+```bash
+open http://localhost:3113
+```
+
+Сервер переглядача за замовчуванням прив'язується до `127.0.0.1` і додає серверний секрет, коли переадресовує запити до REST API, тож він не потребує налаштування. Ендпоінт `/agentmemory/viewer`, що обслуговується через REST, дотримується звичайних правил bearer-токена і переспрямовує браузери без токена на порт переглядача. Заголовки CSP використовують nonce скрипту для кожної відповіді та вимикають атрибути вбудованих обробників (`script-src-attr 'none'`).
+
+---
+
+
+
+Переглядач на `:3113` показує, що ваш агент **запам'ятав**. [Консоль iii](https://iii.dev/docs/console) показує, що ваш агент **зробив**: кожну операцію з пам'яттю як трасування OpenTelemetry, кожен запис KV можна редагувати, кожну функцію можна викликати, кожен потік можна підключити для прослуховування. Два вікна на ту саму пам'ять: одне у формі продукту, інше — у формі двигуна.
+
+Спостерігайте за спрацюванням `memory_smart_search` і бачте сканування BM25 → пошук ембединга → злиття RRF → реранкер як каскад. Редагуйте застряглий таймер консолідації в браузері KV. Відтворюйте хук `PostToolUse` зі зміненим корисним навантаженням. Закріпіть потік WebSocket і спостерігайте, як спостереження надходять у реальному часі.
+
+agentmemory надає це безкоштовно, тому що кожен виклик функції та тригер спрацьовує через iii; нічого власного, нічого інструментувати.
+
+
+
+
+ Сторінка Workers: кожен підключений воркер, включно з самим agentmemory, з PID, кількістю функцій, рантаймом і часом останньої активності.
+
+
+**Уже встановлено.** Консоль постачається разом із закріпленим двигуном `iii` (0.22+); нічого окремо встановлювати не потрібно. Перший запуск завантажує бінарний файл консолі поруч із двигуном.
+
+**Запуск разом з agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Це запускає `iii console` закріпленого двигуна проти портів, визначених agentmemory (REST, потоки, bridge), і обслуговує її на один порт вище за переглядач, за замовчуванням `http://localhost:3114`. `--console-port N` обирає інший порт; `--port` і `--instance` обирають інстанс agentmemory так само, як для `stop`; будь-який інший прапорець передається напряму, наприклад `--enable-flow` для експериментальної сторінки графа архітектури.
+
+Те саме вручну, корисно, коли `agentmemory` відсутній у PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Що можна робити з консолі:**
+
+| Сторінка | Використовуйте, щоб |
+|------|-----------|
+| **Workers** | Бачити кожен підключений воркер і його показники в реальному часі, включно з самим воркером agentmemory. |
+| **Functions** | Викликати будь-яку функцію agentmemory напряму з корисним навантаженням JSON; зручно для тестування `memory.recall`, `memory.consolidate`, `graph.query` без підключення клієнта. |
+| **Triggers** | Відтворювати HTTP-, cron-, подієві та стейт-тригери: запустити cron консолідації вручну, повторити HTTP-маршрут, згенерувати зміну стану. |
+| **States** | Браузер KV із повним CRUD для сесій, слотів пам'яті, таймерів життєвого циклу та індексу ембедингів; редагувати значення на місці. |
+| **Streams** | Живий монітор WebSocket для записів пам'яті, подій хуків та оновлень спостережень у міру їхнього проходження через потоки iii. |
+| **Queues** | Довговічні теми черги + керування dead-letter. Відтворювати або відкидати невдалі завдання ембедингу / стиснення. |
+| **Traces** | Перегляди OpenTelemetry waterfall / flame / розбивки за сервісами. Фільтруйте за `trace_id`, щоб побачити, які саме функції, запити до БД та запити ембедингу породив один `memory.search`. |
+| **Logs** | Структуровані логи OTEL, відфільтровані та співвіднесені з ID трасування/спанів. |
+| **Config** | Конфігурація рантайму: побачити, з якими воркерами, постачальниками і портами працює ваш двигун. |
+| **Flow** | (Опційно, `--enable-flow`) Інтерактивний граф архітектури кожного воркера, тригера і потоку. |
+
+
+
+
+ Traces: waterfall / flame / розбивка за сервісами для кожної операції з пам'яттю.
+
+
+**Трасування вже увімкнено:**
+
+`iii-config.yaml` постачається з увімкненим воркером `iii-observability` (`exporter: memory`, `sampling_ratio: 0.1`, метрики + логи). Додаткова конфігурація не потрібна; у момент запуску agentmemory кожна операція з пам'яттю генерує структурований лог, який може прочитати консоль, і кожна десята з них (`sampling_ratio: 0.1`) також генерує спан трасування.
+
+Якщо ви натомість хочете експортувати в Jaeger/Honeycomb/Grafana Tempo, змініть `exporter: memory` на `exporter: otlp` і встановіть ендпоінт колектора відповідно до документації з спостережуваності iii.
+
+> **Важливо:** на самій консолі автентифікація не застосовується; тримайте її прив'язаною до `127.0.0.1` (значення за замовчуванням) і ніколи не публікуйте її назовні.
+
+---
+
+
+
+agentmemory **вже є запущеним інстансом [iii](https://iii.dev)**. Рантайм складається з трьох примітивів (worker, function, trigger); KV-стан, потоки та трасування OTEL надходять від воркерів iii-state, iii-stream та iii-observability, що постачаються разом з iii. Ви не встановлювали Postgres, Redis, Express, pm2 чи Prometheus, тому що iii замінює їх.
+
+Це означає, що одна додаткова команда розширює agentmemory цілою новою можливістю.
+
+### Розширення agentmemory додатковими воркерами
+
+Вбудовані воркери, потрібні agentmemory, уже є в `iii-config.yaml` і завантажуються разом з ним: `iii-state` (KV), `iii-queue` (стійкі повторні спроби для підписників подій), `iii-pubsub`, `iii-cron`, `iii-stream` та `iii-observability` (трасування OTEL, метрики й логи для кожної функції). Будь-що інше з [реєстру воркерів iii](https://workers.iii.dev) підключається до того самого двигуна: скопіюйте `iii-config.yaml` у `~/.agentmemory/iii-config.yaml` (CLI надає перевагу цьому файлу над вбудованим і все одно рендерить у нього порти та шляхи даних), додайте запис, встановіть рантайм воркера один раз командою `~/.agentmemory/bin/iii update worker` і перезапустіть agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Воркер | Що ви отримуєте на додачу до agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Адаптер стану на основі SQL, коли вам стає замало типових налаштувань KV у пам'яті |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Код, отриманий з `memory_recall`, виконується у тимчасовій VM, а не у вашій оболонці |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Розгортайте додаткові MCP-сервери поруч з сервером agentmemory, спільно з тим самим двигуном |
+
+На двигуні 0.22.x зберігайте назви з префіксом `iii-` для вбудованих воркерів вище; записи без префікса `http`, `state`, `queue`, `pubsub` і `cron` — це автономні воркери з реєстру, на які agentmemory перейде з миграцією на 0.23.
+
+Повний реєстр: [workers.iii.dev](https://workers.iii.dev). Кожен воркер там складається з тих самих примітивів, що використовує agentmemory, і agentmemory, який у вас уже є, — один з них.
+
+### Конфігурація двигуна та адреса прив'язки
+
+`agentmemory start` зчитує конфігурацію двигуна з першого наявного файлу: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` у поточному каталозі, `~/.agentmemory/iii-config.yaml`, потім вбудований `iii-config.yaml`. Під час кожного запуску вона рендерить цей файл (шляхи даних, порти, бекенд стану) у `~/.agentmemory/data/iii-config.runtime.yaml` і запускає двигун з відрендереною копією, тож редагуйте вихідний файл, а не відрендерений. Значення `host:` вихідного файлу зберігаються такими, якими їх записано.
+
+Вбудований `iii-config.yaml` навмисно прив'язується до `127.0.0.1`, і це значення за замовчуванням застосовується й усередині контейнера. CLI, запущений у контейнері, прослуховує loopback контейнера, тож опубліковані порти не дістануться нічого. Щоб обслуговувати контейнеризований CLI через опубліковані порти, встановіть `AGENTMEMORY_III_CONFIG` на конфігурацію, яка прив'язується до `0.0.0.0`. Запакований `iii-config.docker.yaml` саме такий: він прив'язує `iii-http`, `iii-stream` та порт двигуна до `0.0.0.0` і зберігає стан у `/data`, тож монтуйте туди том із правом запису. Тримайте `AGENTMEMORY_SECRET` встановленим і публікуйте лише потрібні вам порти, на `127.0.0.1` або за проксі, якому ви довіряєте.
+
+`docker-compose.yml` цього репозиторію не проходить через пошук конфігурації CLI: він монтує `iii-config.docker.yaml` у `/app/config.yaml`, а контейнер `iii-engine` запускається з `--config /app/config.yaml`. [Шаблони розгортання](../deploy/) в один клік записують власну конфігурацію `0.0.0.0` у своїх точках входу.
+
+### Бекенд сховища: file (за замовчуванням) проти redis
+
+`iii-state` і `iii-stream` за замовчуванням використовують вбудоване файлове KV-сховище iii-engine: один JSON-файл на скоуп, що зберігається в пам'яті процесу двигуна і періодично перезаписується на диск за таймером. Це правильне значення за замовчуванням для локального встановлення з одним користувачем; спільний демон із кількома одночасними записувачами замість цього отримує справжні записи для кожного ключа від Redis, за ціною одного мережевого обороту на операцію (кожен виклик `state::*` все одно серіалізується на одному з'єднанні Redis, тож це обмінює блокування файлового сховища на сокет, а не на паралелізм).
+
+Встановіть `AGENTMEMORY_STATE_BACKEND=redis` (плюс `AGENTMEMORY_REDIS_URL`), щоб перемкнути обидва воркери на вбудований адаптер `redis` iii-engine, який зберігає кожен ключ як поле хеша Redis (`HSET`) замість перезапису всього скоупу під час кожного запису:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` за замовчуванням має значення `file`; якщо не встановлювати її, поточна поведінка залишається незмінною, а невідоме значення (будь-яке, окрім `file` чи `redis`) призводить до помилки запуску, а не до тихого переходу на запасний варіант. `/agentmemory/status` і сторінка Health переглядача (рядок State store) повідомляють, який бекенд активний і чи він відповідає, але ніколи — URL.
+
+**Лише звичайний `redis://`.** Закріплений двигун (0.22.1) збирає свій клієнт Redis без підтримки TLS, тому URL `rediss://` (більшість керованих пропозицій Redis, таких як Upstash, Redis Cloud та ElastiCache з шифруванням під час передавання, за замовчуванням працюють лише через TLS) не зможе підключитися. З'єднання не зашифроване, тож пароль Redis і кожен збережений запис пам'яті проходять мережею у відкритому вигляді: вказуйте на локальний Redis або на такий, що в приватній мережі, якій ви довіряєте. Для будь-якого іншого Redis запустіть зашифрований тунель (stunnel, SSH або VPN) на хості agentmemory, щоб звичайний перехід `redis://` залишався на цьому хості, а вихідне з'єднання тунелю було зашифрованим і автентифікованим. Якщо пароль Redis містить одинарну лапку, закодуйте її у відсотковому форматі (`%27`); двигун розгортає URL у своїй YAML-конфігурації перед розбором.
+
+**Один сервер Redis на кожен `--instance`.** Префікси ключів Redis двигуна (`state:`, `stream::`) фіксовані, тому два інстанси agentmemory (`--instance 1`, `--instance 2`, ...), спрямовані на одну базу даних, перезаписують дані один одного. Окремий індекс бази даних (`redis://localhost:6379/1`) розділяє збережені дані, але двигун транслює живі події переглядача через один канал Redis pub/sub (`stream::events`), а Redis pub/sub ігнорує індекс бази даних, тож переглядач кожного інстансу все одно показуватиме живі події іншого. Виділяйте кожному інстансу власний сервер Redis (або порт), коли запускаєте більше одного.
+
+**Що залишається тим самим, а що відрізняється.** Кожна функція agentmemory працює на Redis: сесії, спостереження, записи пам'яті (remember, supersede, evolve, forget), пошук і бакети індексу, уроки, граф, журнал аудиту та його місячні скоупи, експорт та імпорт, видалення через управління, статус консолідації, знімок переглядача та його живий потік, а також монітор стану здоров'я. Двигун зберігає кожен скоуп як один хеш Redis (`HSET`/`HGET`/`HGETALL`) і генерує ті самі тригери стану, що й файлове сховище. Три відмінності двигуна обробляються всередині agentmemory:
+
+- Redis повертає записи скоупу в непевному порядку. agentmemory сортує їх від найстаріших (за часом створення в id запису, потім за його часовою міткою), тож списки, пагінація та фрагменти експорту повертаються в тому самому порядку, що й у файловому сховищі.
+- Двигун застосовує часткові оновлення в Redis через Lua-скрипт, який перетворює порожні масиви на порожні об'єкти. agentmemory застосовує ці оновлення самостійно (читання, зміна, запис під блокуванням на рівні ключа) на Redis, тож поля, такі як `tags: []`, залишаються масивами.
+- Застаріла перевірка журналу аудиту зчитує старий скоуп із Redis, замість того щоб шукати файл файлового сховища на диску.
+
+Одна відмінність вимагає вашої уваги: **після перезапуску Redis двигун припиняє транслювати живі події** переглядачу, доки не перезапуститься agentmemory. Дані все одно зберігаються й читаються нормально. Монітор стану здоров'я надсилає тестову подію через Redis кожні 30 секунд; якщо вона не повертається, `/agentmemory/status` і сторінка Health переглядача показують «Live updates are not reaching the viewer» із виправленням: перезапустіть agentmemory. Якщо Redis недоступний, звіт про стан показує «The state store is not answering» і спосіб це перевірити (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Перелік дуже великого скоупу зчитує весь хеш за один `HGETALL` — та сама вартість, що й зберігання його у пам'яті у файловому сховищі.
+
+**Рекомендовані налаштування Redis.** Типова політика знімків `save 3600 1 300 100 60 10000` може втратити кілька хвилин записів під час збою, що гірше за 5-секундне вікно скидання файлового сховища. Встановіть `appendonly yes` для всього, втрату чого вам буде прикро. Встановіть `maxmemory-policy noeviction`; `allkeys-lru` або подібне непомітно відкидає записи пам'яті, щойно Redis досягає межі пам'яті.
+
+Нативний запуск (без Docker) та кожен [шаблон розгортання](../deploy/) в один клік (вони перезаписують вбудований `iii-config.yaml` і запускаються нативно) зчитують `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` та рендерять їх у запущений `iii-config`. Сам URL ніколи не записується у цей відрендерений файл — лише посилання `${AGENTMEMORY_REDIS_URL}`, яке процес двигуна розгортає зі свого власного середовища під час завантаження. Лише власний шлях Docker Compose цього репозиторію (`AGENTMEMORY_USE_DOCKER=1`, або відновлення вже запущеного таким чином двигуна) монтує `iii-config.docker.yaml` лише для читання і ніколи не рендерить; `agentmemory start` попереджає, коли виявляє таке поєднання. Змінюйте цей файл вручну, дотримуючись тієї самої форми `name: redis` / `config: redis_url: ...`, показаної в документації воркерів [iii-state](https://workers.iii.dev/workers/iii-state) та [iii-stream](https://workers.iii.dev/workers/iii-stream), і вкажіть у `redis_url` Redis, доступний із контейнера. `docker-compose.yml` передає `AGENTMEMORY_REDIS_URL` у контейнер двигуна, тож `redis_url: '${AGENTMEMORY_REDIS_URL}'` там працює і тримає URL поза змонтованим файлом.
+
+Відрендерена конфігурація тримає URL поза `~/.agentmemory/data/iii-config.runtime.yaml`, але власний воркер конфігурації двигуна все одно зберігає *розгорнуте* значення в `~/.agentmemory/config/iii-state.yaml` та `iii-stream.yaml`, щойно він завантажується (розгортання `${VAR}` iii-engine відбувається до того, як цей воркер зберігає своє початкове значення, і він зберігає розв'язане значення, а не посилання). Ставтеся до цього каталогу як до такого, що містить облікові дані: виконайте `chmod 700 ~/.agentmemory` на будь-якому спільному хості й надавайте перевагу користувачу ACL Redis, обмеженому тим, що потрібно agentmemory, а не адміністративним обліковим даним бази даних.
+
+**Миграція не автоматична.** Перемикання `AGENTMEMORY_STATE_BACKEND` починається з порожнього сховища на обох боках; ніщо не копіює наявні дані з file до Redis чи назад. Виконайте експорт з бекенду, який ви залишаєте, та імпорт у той, на який переходите. Це однаково працює під bash і zsh (включно з `bash -u`). А от масив, подібний до `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})`, працює не однаково: zsh тримає заголовок як одне неправильно сформоване слово, тоді як bash розбиває його на два, тож обидва запити повертають 401, щойно встановлено `AGENTMEMORY_SECRET`:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` також приймає `?maxSessions=` та `?offset=` для розбиття великого корпусу на декілька викликів; `strategy` під час імпорту — це `merge` (безпечний за замовчуванням), `replace` або `skip`.
+
+### Що замінює iii
+
+| Традиційний стек | agentmemory використовує |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + векторний індекс у пам'яті |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | нагляд за воркерами двигуна iii |
+| Prometheus / Grafana | iii OTEL + монітор стану здоров'я |
+| Власні системи плагінів | `iii worker add ` |
+
+**225 вихідних файлів · ~54,000 LOC · 2,600+ тестів · 312 функцій · 66 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
+
+---
+
+
+
+### Постачальники LLM
+
+agentmemory автоматично визначає постачальників із вашого середовища. Постачальник робить доступними операції на основі LLM, але сама лише конфігурація постачальника не вмикає стиснення спостережень, написане LLM. Цей шлях потребує як постачальника, так і `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Постачальник | Конфігурація | Примітки |
+|----------|--------|-------|
+| **No-op (за замовчуванням)** | Конфігурація не потрібна | Стиснення/підсумовування на основі LLM вимкнено. Синтетичне стиснення та пригадування через BM25 все ще працюють. Див. `AGENTMEMORY_ALLOW_AGENT_SDK` нижче, якщо ви раніше покладалися на запасний варіант через підписку Claude. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Оплата за токен |
+| MiniMax | `MINIMAX_API_KEY` | Сумісний з Anthropic |
+| Gemini | `GEMINI_API_KEY` | Також увімкає ембединги |
+| OpenRouter | `OPENROUTER_API_KEY` | Будь-яка модель |
+| OpenAI API | `OPENAI_API_KEY` | За замовчуванням `gpt-5.6-luna`, перевизначте через `OPENAI_MODEL` |
+| **Локальний (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) або `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Усе, що сумісне з OpenAI API. Нульова вартість, працює на вашому обладнанні. Див. [Локальні моделі](#local-models-ollama--lm-studio--vllm) нижче. |
+| Запасний варіант через підписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Лише за явним підключенням. Породжує сесії `@anthropic-ai/claude-agent-sdk`; раніше це спричиняло необмежену рекурсію хука Stop, тож більше не є значенням за замовчуванням. |
+
+### Локальні моделі (Ollama / LM Studio / vLLM)
+
+agentmemory спілкується з будь-яким сервером, сумісним з OpenAI API, тож усе, що надає `/v1/chat/completions`, працює без змін у коді. Без платних ключів, без хмари, без обмежень частоти запитів; працює повністю на вашому обладнанні.
+
+**Ollama** (порт за замовчуванням `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (порт за замовчуванням `1234`):
+
+Відкрийте LM Studio → вкладка Local Server → Start Server. Оберіть будь-яку чат-модель із переліку (Qwen 3, gpt-oss, DeepSeek R1 тощо).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: той самий формат. Вкажіть у `OPENAI_BASE_URL` URL, який надає ваш сервер, і встановіть у `OPENAI_MODEL` назву, яку прийме ваш сервер.
+
+**Вибір моделей для роботи з пам'яттю**: стиснення та підсумовування — це короткі завдання (<2K токенів на вхід, <500 токенів на вихід), для яких цілком достатньо 7B instruct-моделі. Рекомендації:
+
+| Модель | Розмір | Чому |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 ГБ | Збалансований варіант за замовчуванням на машині з 16 ГБ; сильна у видобуванні та тексті, схожому на виклики інструментів |
+| `qwen3:4b` | ~2.6 ГБ | Найменший розумний варіант; підходить для стиснення, слабша для видобування графа |
+| `qwen3-coder:30b` | ~19 ГБ | Найкращий локальний вибір для сесій, орієнтованих на код (30B MoE, 3.3B активних) на обладнанні з 24-32 ГБ |
+| `gpt-oss:20b` | ~14 ГБ | Сильна загальна модель, що вписується в 16 ГБ RAM |
+| `deepseek-r1:8b` | ~5.2 ГБ | Дистиляція з міркуванням; повільніша, але чистіше видобування |
+
+Моделі Qwen 3 за замовчуванням «думають» і можуть витратити весь бюджет токенів на міркування ще до будь-якого виводу. Встановіть `AGENTMEMORY_LLM_NOTHINK=1`, щоб додавати `/no_think` до промптів видобування графа, і підвищте `MAX_TOKENS` (підходить 16384), якщо видобування повертається порожнім.
+
+Моделі класу reasoning (у стилі `o1` з блоками ``) можуть повертати порожній `content` із полем `reasoning`, яке ваш локальний сервер може не показувати. Якщо видобування повертається порожнім, спершу переключіться на модель без reasoning. Змінна середовища `OPENAI_REASONING_EFFORT=none` також може вимикати «мислення» на моделях Ollama Cloud, що дзеркалять схему reasoning OpenAI.
+
+Локальні ембединги постачаються як опційна залежність, але не увімкнені за замовчуванням. Встановіть `EMBEDDING_PROVIDER=local`, щоб підключити `Xenova/all-MiniLM-L6-v2` (384 вимірів). Перший запит ембединга завантажує модель; надалі обчислення виконуються на пристрої. Без цього налаштування або віддаленого ключа ембедингів вектори залишаються вимкненими, `mem::search` використовує BM25, а `smart-search` все одно може додавати наявні збіги графа.
+
+### Вибір моделі з урахуванням вартості
+
+Коли фонове стиснення, написане LLM, увімкнене як через постачальника, так і через `AGENTMEMORY_AUTO_COMPRESS=true`, воно запускається для кожного спостереження, тож вибір моделі суттєво змінює щомісячні витрати. Зафіксовані дані навантаження: 635 запитів / 888K токенів / 35 годин активного використання, запущені на трьох моделях OpenRouter за цінами станом на 2026-05-23.
+
+| Рівень | Модель | Вхід / 1M | Вихід / 1M | Вартість для зафіксованих 35г | Примітки |
+|------|-------|------------|-------------|---------------------------|-------|
+| Рекомендовано | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (оцінка) | Найновіший DeepSeek; найдешевший рекомендований вибір для навантажень стиснення. |
+| Рекомендовано | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Якісне стиснення + підсумовування за ціною ~у 10× нижчою, ніж у Sonnet. |
+| Рекомендовано | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Сильне кодове міркування, якщо ваші сесії значною мірою орієнтовані на код. |
+| Преміум | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (оцінка) | Та сама прайс-листова ціна, що й у вимірюваному запуску Sonnet 4.6; вступна ціна $2/$10 до 2026-08-31. |
+| Преміум | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (оцінка) | Флагманський рівень; дорогий для постійно активної фонової роботи. |
+| Уникати | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (оцінка) | Модель флагманського класу; надмірні витрати для стиснення. |
+
+Рядки з вимірюваними значеннями походять із зафіксованого запуску; рядки з позначкою (оцінка) масштабують той самий мікс токенів за прайс-листовою ціною кожної моделі.
+
+agentmemory виводить попередження під час роботи, коли `OPENROUTER_MODEL` відповідає шаблону преміум-рівня. Встановіть `AGENTMEMORY_SUPPRESS_COST_WARNING=1`, щоб вимкнути це попередження, коли ви вже зробили усвідомлений вибір.
+
+Компроміс якості та вартості для роботи з пам'яттю: стиснення — це завдання підсумовування з відносно м'якими вимогами до якості (підсумок повторно читає агент, а не користувач). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder потрапляють у межі похибки округлення порівняно з Sonnet у цьому завданні, коштуючи при цьому в 10-70× менше. Зберігайте моделі преміум-рівня для запитів, які ви читаєте самостійно.
+
+Джерела: [ціни OpenRouter на Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [примітки щодо цін 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 # 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.
+
+Що фільтрується в ізольованому режимі: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Кожен ендпоінт приймає `?agentId=` для перевизначення для конкретного запиту та `?agentId=*`, щоб повністю вийти зі скоупу змінної середовища. `/memories` також приймає `?includeOrphans=true`, щоб показати записи пам'яті до появи AGENT_ID, чий `agentId` не визначено.
+
+Перевизначення для кожного виклику на рівні SDK / REST: кожен змінювальний ендпоінт (`/session/start`, `/remember`) приймає поле `agentId` у тілі запиту, яке переважає над змінною середовища. Корисно для рантаймів, що маршрутизують багато ролей через один серверний процес. Інструмент MCP `memory_save` надає те саме поле `agentId`, автономний stdio-сервер передає як `agentId`, так і `project`, а збережені записи пам'яті несуть `agentId` у пошуковий індекс, тож пошук у межах скоупу агента охоплює як записи пам'яті, так і спостереження.
+
+Коли `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 | Внутрішній воркер потоків (використовується agentmemory + переглядачем) | `III_STREAM_PORT` (пріоритетно) або застарілий `III_STREAMS_PORT` |
+| `3113` | agentmemory | Переглядач у реальному часі (`http://localhost:3113`) | `III_VIEWER_PORT` або `AGENTMEMORY_VIEWER_URL` для URL, що повідомляється |
+| `49134` | iii-engine | WebSocket; тут реєструються воркери, через нього проходить телеметрія OTel | `III_ENGINE_PORT` або `III_ENGINE_URL` |
+
+`--port ` змінює якір REST і виводить потоки `N+1`, переглядач `N+2` та WebSocket двигуна `N+46023`, але лише там, де відповідний явний порт чи URL вище не встановлено. Це не створює ізольований простір імен життєвого циклу. Використовуйте `--instance 1` для другого демона; він використовує якір 3211, за замовчуванням `3211/3212/3213/49234`, і отримує окремий каталог даних і життєвого циклу `instance-1`. Інстанси від 1 до 50 дотримуються того самого шаблону.
+
+Закріплений двигун запускається з `--no-update-check` (без пошуку оновлень чи порад безпеки проти GitHub під час завантаження) і з вимкненою анонімною телеметрією використання iii: agentmemory встановлює `III_TELEMETRY_ENABLED=false` для двигуна, який він породжує, якщо ви самі не експортували цю змінну, і вбудований compose-файл робить те саме.
+
+Очищення застарілих процесів, коли порти залишаються зайнятими після аварійного завершення:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` коректно прибирає як воркер, так і pid-файл двигуна під час штатного нативного завершення роботи. У режимі Docker вона зливає нативний воркер, зупиняє саме той перевірений контейнер двигуна і зберігає як контейнер, так і його монтування `/data` для безвтратного перезапуску; наступний запуск перевіряє і відновлює той самий контейнер. Видалення на основі Docker потребує `agentmemory remove --keep-data`: ця команда видаляє спільні файли, якими керує agentmemory, зберігаючи перевірений контейнер, його монтування даних і запис життєвого циклу, потрібний для їхнього відновлення. Руйнівне видалення даних Docker навмисно залишено на оператора після резервного копіювання. CLI також відмовляється приймати у власність або сигналізувати власникам портів Docker чи VM (Docker backend, vpnkit, colima) як нативному двигуну, якщо не передано `--force`. Ручне очищення вище призначене лише для випадку після аварійного завершення, коли жодного pid-файлу не залишилося.
+
+### Файл конфігурації
+
+Розмістіть конфігурацію рантайму agentmemory в `~/.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
+```
+
+Щоб протестувати з підпискою Claude Code Pro/Max замість API-ключа, підключіться явно:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Стиснення спостережень, написане LLM, потребує обох рядків: доступу до постачальника LLM (включно з цим явним запасним варіантом через підписку) та `AGENTMEMORY_AUTO_COMPRESS=true`. Сам лише постачальник залишає типовий шлях синтетичного стиснення без змін.
+
+Консолідація (вузли графа, уроки, кристали) увімкнена за замовчуванням, коли налаштовано постачальника LLM. Явно відмовтеся за допомогою `CONSOLIDATION_ENABLED=false`, якщо хочете роботи без LLM. Видобування графа — це окремий прапорець:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Змінні середовища
+
+Створіть `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 ендпоінтів на порту `3111`. REST API за замовчуванням прив'язується до `127.0.0.1`. Захищені ендпоінти вимагають `Authorization: Bearer `, а ендпоінти синхронізації mesh вимагають явно встановленого `AGENTMEMORY_SECRET` на обох сторонах.
+
+**Автентифікація увімкнена за замовчуванням.** Коли `AGENTMEMORY_SECRET` не встановлено (ні в оболонці, ні в `~/.agentmemory/.env`), сервер генерує випадковий секрет під час першого запуску та зберігає його в `~/.agentmemory/secret` з режимом `0600`. Кожен вбудований клієнт зчитує його звідти, коли спілкується з локальним сервером: CLI, переглядач, хуки в `plugin/scripts`, MCP-сервер та шим `@agentmemory/mcp`, конфігурації, записані `agentmemory connect`, а також вбудовані інтеграції OpenCode, Pi, OpenClaw, Hermes та спостерігача за файловою системою. Збережений секрет надсилається лише на loopback-URL (`localhost`, `127.0.0.0/8`, `::1`). Явний `AGENTMEMORY_SECRET` завжди переважає, і віддаленим клієнтам все одно потрібно його встановити. Docker та точки входу `deploy/` уже генерують і експортують власний секрет. Щоб викликати API вручну:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Правила запитів для записів.** Запити `POST`, `PUT`, `PATCH` і `DELETE` до REST API та переглядача повинні надсилати `Content-Type: application/json` (параметр `charset` допустимий), коли вони несуть тіло, а заголовок `Origin`, якщо присутній, має бути loopback-джерелом для налаштованого порту REST чи переглядача або бути перелічений у `VIEWER_ALLOWED_ORIGINS` (через кому, наприклад `https://memory.example.com`). Клієнти, що не надсилають заголовок `Origin` (CLI, хуки, MCP, curl, сервер-до-сервера), не впливають на це. Переглядач також приймає власне джерело.
+
+**Шляхи до файлів.** Ендпоінти, що читають або записують файли (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`), приймають лише шляхи в межах `~/.agentmemory`, каталогу даних інстансу або каталогу, перелічений у `AGENTMEMORY_IMPORT_ROOT` (розділяйте декілька через `:`, або `;` на Windows). `/replay/import-jsonl` також приймає свій типовий `~/.claude/projects`. `/obsidian/export` залишається в межах `AGENTMEMORY_EXPORT_ROOT`, а `/migrate` — в межах `~/.agentmemory`. Символічні посилання розв'язуються перед кожною перевіркою.
+
+**Очищення секретів.** API-ключі, bearer-токени, блоки приватних ключів PEM та облікові дані, вбудовані в URL (`scheme://user:password@host`), видаляються перед збереженням тексту, на кожному шляху запису: спостереження, remember, evolve, слоти, уроки, дії, ескізи, сигнали, контрольні точки, імпорти, відтворення jsonl, синхронізація mesh, спільний доступ команди, вивід стиснення та підсумків, кристали й вузли графа.
+
+
+Основні ендпоінти
+
+| Метод | Шлях | Опис |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Перевірка стану здоров'я (завжди публічна) |
+| `GET` | `/agentmemory/status` | Що не так і як це виправити (HTML для браузерів, JSON в інших випадках) |
+| `GET` | `/agentmemory/viewer/snapshot` | Усе, що показує переглядач, в одній відповіді |
+| `POST` | `/agentmemory/session/start` | Почати сесію + отримати контекст |
+| `POST` | `/agentmemory/session/end` | Завершити сесію |
+| `POST` | `/agentmemory/observe` | Захопити спостереження (див. доставку захоплення нижче) |
+| `GET` | `/agentmemory/capture` | Вхідна скринька захоплення, dead letters та офлайн-спул |
+| `POST` | `/agentmemory/capture/retry` | Повторити невдалі захоплення (dead-letter) |
+| `POST` | `/agentmemory/capture/drain` | Надіслати локальний офлайн-спул зараз |
+| `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/graph/compact` | Обрізати завелике походження графа |
+| `POST` | `/agentmemory/team/share` | Поширити серед команди |
+| `GET` | `/agentmemory/audit` | Журнал аудиту |
+
+Повний перелік ендпоінтів: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Доставка захоплення.** Хуки надсилають кожне спостереження один раз на `POST /agentmemory/observe` з `eventId`. Це власний id хоста для виклику, якщо корисне навантаження має такий (наприклад, `tool_use_id` Claude Code), інакше — хеш сесії, типу хука, назви інструменту, вхідних і вихідних даних та часової метки хоста. Сервер записує подію у вхідну скриньку захоплення в хранилищі стану, зберігає спостереження, потім видаляє запис зі скриньки. Код статусу повідомляє, що сталося:
+
+| Статус | поле `status` | Значення |
+|---|---|---|
+| `201` | `accepted` | Збережено. `observationId` — нове спостереження. |
+| `202` | `accepted` (`state: "retrying"`) | Прийнято, але збереження не вдалося. Сервер повторює спробу, також після перезапуску. |
+| `200` | `duplicate` | Цей `eventId` уже прийнято раніше. `observationId` — наявне спостереження; нічого нового не зберігається. |
+| `400` / `422` | `rejected` | Некоректне корисне навантаження, або збереження остаточно не вдалося (подія зберігається як dead letter). |
+| `503` | `rejected` (`retryable: true`) | Вхідна скринька переповнена (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Хуки заносять подію в спул і надсилають її пізніше. |
+
+Невдалі події повторюються кожні `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 с) з подвоюваним відступом, до `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Події, що все ще не вдаються, залишаються у вхідній скриньці як dead letters, перелічуються на `/agentmemory/status` і сторінці Health переглядача, і можуть бути повторені через `POST /agentmemory/capture/retry` (`{"eventId": "..."}` або `{"all": true}`). Прийняті id подій пам'ятаються протягом `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 годин, щонайбільше `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), тож хук, відтворений після таймауту чи перезапуску, зберігається один раз, тоді як два окремі виклики інструменту з власними id хоста зберігаються двічі, навіть якщо їхній вміст ідентичний. Коли спостереження видаляється (forget, видалення сесії, витіснення, автозабування або імпорт, що замінює сховище), його подія позначається як видалена до видалення самого спостереження, тож відтворення цієї події в тому самому вікні відповідається як дублікат і нічого не зберігає. Хранилище стану записує на диск кожні 2 секунди, тож відповідена подія може ще якусь мить залишатися лише в пам'яті. Щоб покрити це, кожна відповідь `2xx` також несе `bootId` сервера (новий під час кожного запуску), `acceptedAt` і `durableAfterMs` (інтервал збереження плюс 1.5 с для файлового сховища, 1.5 с для redis, де стійкість — налаштування оператора). Хуки тримають подію в локальному спулі, доки не минув цей проміжок, і видаляють її під час наступного виклику без додаткового запиту. Якщо `bootId` змінився на той момент, сервер перезапустився, тож хук надсилає подію знову з тим самим `eventId`; подія, яка таки дістала диск, не зберігається двічі. Сервер також сам надсилає такі події під час запуску і кожного інтервалу повторення, тож перезапуск нічого не втрачає, навіть якщо надалі жоден хук не запускається. Старіші хуки ігнорують додаткові поля, а нові хуки проти старішого сервера відкидають подію на `2xx`, як і раніше.
+
+Коли сервер не працює, не відповідає вчасно або повертає 5xx, хук додає спостереження до локального файлу спулу, `/capture-spool/-.jsonl` (перевизначте папку через `AGENTMEMORY_CAPTURE_SPOOL_DIR`). Файл приватний для вашого користувача (режим 600), секрети редагуються так само, як їх редагує сервер, він містить щонайбільше `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 МіБ) і відкидає записи, старіші за `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Коли він переповнений, нові записи відкидаються і підраховуються, і `/agentmemory/status` повідомляє про це. Хук все одно завершується з кодом 0 у межах свого часового лімиту і не додає запиту, коли сервер справний. Спул надсилається під час наступного запуску і першим хуком, що знову дістається сервера, у фоновому процесі, тож агент не чекає. Id подій роблять це безпечним: спостереження, яке таки надійшло до таймауту, не зберігається двічі. `npx @agentmemory/agentmemory capture` показує спул і вхідну скриньку сервера, `--drain` надсилає спул зараз, а `GET /agentmemory/capture` повертає те саме як JSON. Встановіть `AGENTMEMORY_CAPTURE_SPOOL=false`, щоб вимкнути спул.
+
+**Компактування походження графа.** Кожен вузол і ребро графа знань зберігає id 32 найновіших спостережень, з яких він походить. Сховища, записані до появи цього обмеження, можуть містити тисячі id на гарячий вузол, що сповільнює пошук у графі та переглядач або призводить до падіння воркера. agentmemory виправляє це самостійно: під час першого запуску після оновлення він обрізає кожен вузол, ребро, заміщене ребро (темпоральну історію графа) та кешований знімок до межі у фоновому режимі, невеликими фрагментами з паузою між ними, тож пошук, захоплення та переглядач продовжують працювати. Він зберігає свій прогрес, відновлюється після перезапуску і більше не запускається після завершення. `/agentmemory/status` і сторінка Health переглядача показують це як очікування, виконання (з поточним скоупом і позицією), завершено або не вдалося. Встановіть `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`, щоб вимкнути це.
+
+Щоб запустити це вручну, викличте `POST /agentmemory/graph/compact`. Він обходить індекси імен та ключів ребер, замість перелічування кожного вузла і ребра, і безпечний для повторного запуску. Коли він обрізає id, він записує запис аудиту `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+На великому сховищі, або коли виклик повертає 504, запускайте це фрагментами. Надішліть `scope` (`nodes`, `edges` або `history`), `offset` і `limit`, потім викличте знову з поверненим `nextOffset`, доки він не стане `null`. Зробіть це для `nodes`, `edges` та `history`, і завершіть одним викликом `{"scope":"snapshot"}`, тому що фрагментований запуск не торкається кешованого знімка.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Передумови:** Node.js >= 20 з npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 або Docker. Автоматичне встановлення двигуна на macOS/Linux також вимагає `curl`, POSIX `sh` та `tar`; нативний Windows використовує вручну встановлений закріплений `iii.exe`, WSL2 або Docker Desktop.
+
+
+
+ آپ کا کوڈنگ ایجنٹ سب کچھ یاد رکھتا ہے۔ دوبارہ وضاحت کرنے کی ضرورت نہیں۔
+ iii engine پر تیار کیا گیا
+
+ Claude Code، GitHub Copilot CLI، Cursor، Gemini CLI، Codex CLI، Hermes، OpenClaw، pi، OpenCode، اور کسی بھی MCP کلائنٹ کے لیے مستقل میموری۔
+
+ یہ گسٹ Karpathy کے LLM Wiki پیٹرن کو کانفیڈنس اسکورنگ، لائف سائیکل، نالج گرافس، اور ہائبرڈ سرچ کے ساتھ وسعت دیتا ہے: agentmemory اسی کا عملی نفاذ ہے۔
+
+
+---
+
+## انسٹال
+
+تقاضے:
+
+- Node.js 20 یا نیا، npm اور npx کے ساتھ (`node -v`، `npm -v`، اور `npx -v`)۔
+- macOS/Linux پر خودکار iii-engine انسٹالیشن کے لیے `curl`، ایک POSIX `sh`، اور `tar` بھی ضروری ہیں۔ `node:20-slim` جیسی minimal images میں یہ شامل نہیں ہو سکتے۔
+- نیٹیو Windows کے لیے pinned iii-engine v0.22.1 `iii.exe` کو دستی طور پر انسٹال کرنا ضروری ہے۔ WSL2 یا Docker Desktop دیگر معاون راستے ہیں۔
+
+معیاری fresh-install کمانڈ:
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+پہلی بار چلانے پر ایک انٹرایکٹو سیٹ اپ ہوتا ہے: جن ایجنٹس کو جوڑنا ہے انہیں منتخب کریں (Claude Code، Cursor، Codex، Gemini CLI، OpenCode، ...)، کوئی LLM پرووائیڈر منتخب کریں یا بغیر کلید (keyless) کے رہیں، اور یہ کنفیگ تیار کرتا ہے، میموری سرور اور اس کا pinned iii engine شروع کرتا ہے، اور عالمی سطح پر انسٹال کرنے کی پیشکش کرتا ہے تاکہ صرف `agentmemory` کمانڈ بعد میں ہر جگہ کام کرے۔ `-y` npx کے پیکیج پرامپٹ کو قبول کرتا ہے اور `@latest` کسی پرانے cached ریلیز سے بچاتا ہے۔ ایک پرووائیڈر LLM خصوصیات کو دستیاب بناتا ہے، لیکن LLM کی تحریر کردہ observation compression تب ہی شروع ہوتی ہے جب `AGENTMEMORY_AUTO_COMPRESS=true` بھی سیٹ ہو۔
+
+Keyless موڈ ویکٹر embeddings کو غیر فعال کر دیتا ہے۔ `memory_recall` (جو `mem::search` راستہ استعمال کرتا ہے) BM25 استعمال کرتا ہے، جبکہ `memory_smart_search` موجودہ graph ڈیٹا ہونے کی صورت میں structural graph matches کو بھی فیوز کر سکتا ہے۔ مفت آن-ڈیوائس سیمینٹک ریکال کے لیے، `~/.agentmemory/.env` میں `EMBEDDING_PROVIDER=local` سیٹ کریں اور دوبارہ شروع کریں۔ پہلی embedding درخواست `Xenova/all-MiniLM-L6-v2` ڈاؤن لوڈ کرتی ہے؛ اس ابتدائی ماڈل ڈاؤن لوڈ کے بعد inference مقامی طور پر چلتا ہے۔
+
+مقامی رن ٹائم چار پورٹس استعمال کرتا ہے: REST/MCP HTTP کے لیے `3111`، iii streams کے لیے `3112`، ویور کے لیے `3113`، اور iii ورکر WebSocket کے لیے `49134`۔ مستقل iii اسٹیٹ macOS پر `~/Library/Application Support/agentmemory`، Linux پر `$XDG_DATA_HOME/agentmemory` یا `~/.local/share/agentmemory`، اور Windows پر `%APPDATA%\agentmemory` میں رہتی ہے۔ اسے اووررائیڈ کرنے کے لیے `--data-dir ` یا `AGENTMEMORY_DATA_DIR` استعمال کریں، اور ہر ریسٹارٹ پر وہی قدر دہرائیں۔ بیک ورڈ compatibility کے لیے، موجودہ `./data/state_store.db` یا `./data/iii-config.yaml` انسٹنس 0 کے لیے پلیٹ فارم ڈیفالٹ پر فوقیت رکھتا ہے؛ ایک واضح فلیگ یا ماحولیاتی اوور رائیڈ پھر بھی جیت جاتا ہے۔
+
+پھر ثابت کریں کہ ریکال کام کر رہا ہے اور اپنے ایجنٹ کو اس کی اسکلز دیں:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+کی-ورڈ سرچز کو ڈیفالٹ keyless موڈ میں BM25 کے ذریعے ہِٹ ہونا چاہیے۔ ڈیمو کی `database performance optimization` کوئری جانستہ طور پر سیمینٹک ہے اور جب تک کوئی embedding پرووائیڈر کنفیگر نہ ہو، صفر نتائج دے سکتی ہے۔
+
+کسی کوڈنگ ایجنٹ سے یہ سارا کام کروانا چاہتے ہیں؟ اسے صرف ایک ہدایت دیں:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+کسی بھی وقت `agentmemory connect ` سے مزید ایجنٹس جوڑیں — 20 adapters [ہر ایجنٹ کے ساتھ کام کرتا ہے](#works-with-every-agent) میں درج ہیں۔ مکمل کمانڈ ریفرنس [فوری آغاز](#quick-start) میں ہے۔
+
+
+Windows
+
+سب سے تیز راستہ WSL2 ہے۔ نیٹیو Windows انجن سیٹ اپ کے لیے pinned v0.22.1 ZIP ڈاؤن لوڈ کرنا اور `iii.exe` کو دستی طور پر ایکسٹریکٹ کرنا ضروری ہے؛ CLI اسے خودکار طور پر ایکسٹریکٹ نہیں کرتا۔ Docker Desktop بھی معاون ہے۔ مرحلہ وار تفصیل کے لیے [Windows نوٹس](#windows) دیکھیں۔
+
+
+
+
+Global install / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+اوپر دی گئی npx کمانڈ معیاری fresh-install راستہ ہی رہتی ہے اور global-prefix پرمیشن مسائل سے بچاتی ہے۔
+
+
+
+
+npx پرانا ورژن دیتا ہے
+
+npx ہر ورژن کو علیحدہ طور پر کیش کرتا ہے۔ `npx -y @agentmemory/agentmemory@latest` سے تازہ ترین ورژن پر مجبور کریں، یا ایک بار `rm -rf ~/.npm/_npx` سے کیش صاف کریں (macOS/Linux؛ Windows پر `%LOCALAPPDATA%\npm-cache\_npx` ڈیلیٹ کریں)۔
+
+
+
+
+آپ کا اپنا iii engine پہلے سے چل رہا ہے
+
+agentmemory iii-engine v0.22.1 کو pin کرتا ہے اور کسی مختلف ورژن سے منسلک نہیں ہوتا (ورکر کسی دوسرے انجن کا پروٹوکول نہیں بول سکتا)۔ دوسرا انجن روکیں، پھر `npx -y @agentmemory/agentmemory@latest` چلائیں۔ یہ pinned v0.22.1 کو `~/.agentmemory/bin` میں انسٹال اور چلاتا ہے، جبکہ آپ کا اپنا `iii` بغیر چھیڑے رہتا ہے۔
+
+
+
+---
+
+
+
+agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے جو hooks، MCP، یا REST API کو سپورٹ کرتا ہو۔ تمام ایجنٹس ایک ہی میموری سرور کا اشتراک کرتے ہیں۔
+
+
+
+
+
+Claude Code
+نیٹیو پلگ ان + 12 ہکس + MCP
+
+
+
+Codex CLI
+نیٹیو پلگ ان + 6 ہکس + MCP
+
+
+
+GitHub Copilot CLI
+MCP + پلگ ان ہکس/اسکلز
+
+
+
+Cursor
+نیٹیو پلگ ان + 7 ہکس + MCP
+
+
+
+OpenCode
+کیپچر پلگ ان + MCP
+
+
+
+
+
+Devin
+6 ہکس + اسکلز + MCP
+
+
+
+OpenClaw
+نیٹیو پلگ ان + MCP
+
+
+
+Hermes
+نیٹیو پلگ ان + MCP
+
+
+
+pi
+نیٹیو پلگ ان + MCP
+
+
+
+OpenHuman
+نیٹیو Memory trait بیک اینڈ
+
+
+
+
+
+Gemini CLI
+MCP سرور
+
+
+
+Antigravity
+MCP + ہکس
+
+
+
+Claude Desktop
+MCP سرور
+
+
+
+Warp
+کنکٹ + MCP + اسکلز
+
+
+
+Zed
+MCP سرور
+
+
+
+
+
+Cline
+MCP سرور
+
+
+
+Continue
+MCP سرور
+
+
+
+Droid
+MCP سرور
+
+
+
+Kiro
+MCP سرور
+
+
+
+Qwen Code
+MCP سرور
+
+
+
+
+
+DeepSeek Harness
+MCP سرور
+
+
+
+Roo Code
+MCP سرور
+
+
+
+Kilo Code
+MCP سرور
+
+
+
+Goose
+MCP سرور
+
+
+
+Aider
+REST API
+
+
+
+
+
+ MCP یا HTTP بولنے والے کسی بھی ایجنٹ کے ساتھ کام کرتا ہے۔ ایک سرور، میموریز ان سب کے درمیان مشترک ہیں۔
+
+
+---
+
+آپ ہر سیشن میں وہی architecture دوبارہ بیان کرتے ہیں۔ آپ وہی bugs دوبارہ ڈھونڈتے ہیں۔ آپ وہی ترجیحات دوبارہ سکھاتے ہیں۔ بلٹ-اِن میموری (CLAUDE.md، .cursorrules) 200 لائنز پر رک جاتی ہے اور پرانی ہو جاتی ہے۔ agentmemory یہ مسئلہ حل کرتا ہے۔ یہ خاموشی سے وہ سب کچھ ریکارڈ کرتا ہے جو آپ کا ایجنٹ کرتا ہے، اسے searchable میموری میں compress کرتا ہے، اور اگلا سیشن شروع ہوتے ہی درست context انجیکٹ کرتا ہے۔ صرف ایک کمانڈ۔ تمام ایجنٹس پر کام کرتا ہے۔
+
+**کیا بدلتا ہے:** سیشن 1 میں آپ JWT auth سیٹ اپ کرتے ہیں۔ سیشن 2 میں آپ rate limiting مانگتے ہیں۔ ایجنٹ کو پہلے ہی معلوم ہے کہ آپ کا auth `src/middleware/auth.ts` میں jose middleware استعمال کرتا ہے، آپ کے ٹیسٹس token validation کو کَوَر کرتے ہیں، اور آپ نے Edge compatibility کے لیے jsonwebtoken کے بجائے jose کو چنا تھا، بغیر کسی دوبارہ وضاحت یا کاپی-پیسٹ کے۔
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+ڈیفالٹ کے طور پر، agentmemory iii-engine کی اسٹیٹ اس repository سے باہر محفوظ کرتا ہے جہاں سے آپ اسے شروع کرتے ہیں: macOS پر `~/Library/Application Support/agentmemory`، Linux پر `$XDG_DATA_HOME/agentmemory` یا `~/.local/share/agentmemory`، اور Windows پر `%APPDATA%\agentmemory`۔ موجودہ legacy `./data/state_store.db` یا `./data/iii-config.yaml` کو اس پلیٹ فارم ڈیفالٹ سے پہلے انسٹنس 0 کے لیے دوبارہ استعمال کیا جاتا ہے۔ کوئی مقام واضح طور پر منتخب کرنے کے لیے، `--data-dir ` پاس کریں یا `AGENTMEMORY_DATA_DIR` سیٹ کریں؛ دونوں میں سے کوئی بھی واضح سیٹنگ legacy discovery پر فوقیت رکھتی ہے:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+نیٹیو اور Docker دونوں لانچز اسی resolved ہوسٹ ڈائرکٹری کو استعمال کرتے ہیں؛ Docker اسے `/data` پر bind-mount کرتا ہے۔ `--instance 1` resolved ڈائرکٹری میں `instance-1` شامل کرتا ہے اور علیحدہ ڈیفالٹ پورٹ quartet `3211/3212/3213/49234` منتخب کرتا ہے۔
+
+تازہ ترین ریلیز نوٹس: [CHANGELOG.md](../CHANGELOG.md)۔
+
+---
+
+
+
+
+
+
+
+### ریٹریول کی درستگی
+
+**coding-agent-life-v1** (اندرونی corpus، sandbox میں دوبارہ قابلِ تولید)
+
+| Adapter | P@5 | R@5 | ٹاپ-5 ہِٹ ریٹ | p50 لیٹینسی |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep بیس لائن | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+اس corpus کے لیے **P@5 ریاضیاتی حد (ceiling)** پر 100% ٹاپ-5 ہِٹ ریٹ (0.240، scorecard دیکھیں)۔ Hybrid ہر gold سیشن کو ریٹریو کرتا ہے؛ grep multi-session temporal کوئری پر 2 میں سے 1 gold مِس کرتا ہے۔ فائدہ **recall + temporal** کا ہے، مجموعی precision کا نہیں۔ یہ بینچ مارک چھوٹا اور gold-sparse ہے؛ نیچے دیا گیا بڑا LongMemEval-S بہتر فرق دکھاتا ہے۔ مکمل فی-ٹائپ بریک ڈاؤن + تصحیحی نوٹ: [`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 فال بیک | 86.2% | 94.6% | 71.5% |
+
+
+
+> Embedding ماڈل: `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، supermemory، TencentDB Agent Memory، MemPalace، Zep/Graphiti، Cognee، Hippo سے موازنہ کرتا ہے۔
+
+**مقامی طور پر دہرائیں:** [`eval/README.md`](../eval/README.md)، LongMemEval `_s` (عوامی 500-سوالات) + `coding-agent-life-v1` (اندرونی 15-سیشن corpus) کے لیے ایک adapter-pluggable ہارنس۔ Grep / vector / agentmemory adapters ساتھ ساتھ اسکور کرتے ہیں، NDJSON آؤٹ پٹ، شائع شدہ 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 انڈیکسنگ، multi-agent build pipelines، اور docs / PDFs / images / videos میں وسیع نالج گرافس۔ agentmemory کام کو یاد رکھتا ہے؛ یہ تین پراجیکٹس باقی context layer کو روشن کرتے ہیں۔ Recipes + سوال-روٹنگ ٹیبل: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md)۔
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
بلٹ-اِن (CLAUDE.md)
+
+
+
قسم
+
میموری انجن + MCP سرور
+
میموری لیئر API
+
مکمل ایجنٹ رن ٹائم
+
ذاتی AI
+
میموری API + ایپ
+
ٹیم میموری ہب (LLM پراکسی)
+
ویکٹر میموری (OSS)
+
میموری انجن (Oracle DB)
+
میموری سسٹم
+
سٹیٹک فائل
+
+
+
ریٹریول R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
خود رپورٹ شدہ
+
PersonaMem 76% (خود رپورٹ شدہ)
+
~96.6% (خود رپورٹ شدہ)
+
94.4% (خود رپورٹ شدہ)
+
N/A
+
N/A (grep)
+
+
+
خودکار کیپچر
+
12 ہکس (کوئی دستی کام نہیں)
+
دستی `add()` کالز
+
ایجنٹ خود ترمیم کرتا ہے
+
دستی
+
API کی جانب سے استخراج
+
پراکسی انٹرسیپشن (base-URL سویپ)
+
دستی
+
API استخراج
+
دستی
+
دستی ترمیم
+
+
+
سرچ
+
BM25 + ویکٹر + گراف (RRF فیوژن)
+
ویکٹر + گراف
+
ویکٹر (آرکائیول)
+
سیمینٹک
+
ویکٹر + RAG
+
4 asset اقسام (Chat / Skill / Wiki / CodeGraph)
+
صرف ویکٹر
+
ویکٹر + سیمینٹک
+
زوال پر مبنی وزن
+
سب کچھ context میں لوڈ کرتا ہے
+
+
+
ملٹی-ایجنٹ
+
MCP + REST + لیز + سگنلز
+
API (کوئی ربط نہیں)
+
صرف Letta رن ٹائم کے اندر
+
نہیں
+
نہیں
+
ٹیم کردار + مشترک asset
+
نہیں
+
صرف محدود دائرہ کار میں
+
ملٹی-ایجنٹ مشترک
+
فی-ایجنٹ فائلیں
+
+
+
فریم ورک لاک-اِن
+
کوئی نہیں (کوئی بھی MCP کلائنٹ)
+
کوئی نہیں
+
زیادہ (لازمی طور پر Letta استعمال کرنا ہوگا)
+
اسٹینڈ الون
+
کوئی نہیں
+
ہر model کال کے سامنے پراکسی ہوتی ہے
+
کوئی نہیں
+
Oracle Database
+
کوئی نہیں
+
فی-ایجنٹ فارمیٹ
+
+
+
خارجی انحصار
+
کوئی نہیں (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + ویکٹر DB
+
متعدد
+
مینیجڈ کلاؤڈ
+
Docker اسٹیک (Core + Hub + Proxy)
+
ویکٹر اسٹور
+
Oracle AI Database
+
کوئی نہیں
+
کوئی نہیں
+
+
+
میموری لائف سائیکل
+
4-درجاتی استحکام + زوال + خودکار فراموشی
+
غیر فعال استخراج
+
ایجنٹ کے زیرِ انتظام
+
دستی
+
خودکار فراموشی
+
دستی جائزہ؛ auto-routing زیرِ تکمیل
+
کوئی نہیں
+
واضح نہیں
+
زوال + استحکام
+
دستی تراش
+
+
+
ٹوکن کارکردگی
+
~1,900 ٹوکنز/سیشن ($10/سال)
+
integration کے لحاظ سے مختلف
+
بنیادی میموری context میں
+
مختلف ہوتا ہے
+
کلاؤڈ قیمتیں
+
واضح نہیں
+
کوئی token بجٹ نہیں
+
LLM پر مبنی (مختلف ہوتا ہے)
+
مختلف ہوتا ہے
+
240 obs پر 22K+ ٹوکنز
+
+
+
ریئل-ٹائم ویور
+
ہاں (پورٹ 3113)
+
کلاؤڈ ڈیش بورڈ
+
کلاؤڈ ڈیش بورڈ
+
ویب UI
+
کلاؤڈ ڈیش بورڈ
+
ہب ویب UI
+
نہیں
+
نہیں
+
نہیں
+
نہیں
+
+
+
سیلف-ہوسٹڈ
+
ہاں (ڈیفالٹ)
+
اختیاری
+
اختیاری
+
ہاں
+
نہیں (صرف کلاؤڈ)
+
ہاں (Docker)
+
ہاں
+
ہاں (Oracle DB)
+
ہاں
+
ہاں
+
+
+
+بینچ مارک نوٹ: صرف agentmemory کا R@5 ہمارا اپنا پیمائش شدہ نتیجہ ہے (LongMemEval-S، benchmark/COMPARISON.md سے دوبارہ قابلِ تولید)۔ mem0 اور Letta کے اعداد و شمار ان کے شائع شدہ LoCoMo نمبرز ہیں (ایک مختلف dataset)؛ MemPalace، supermemory، TencentDB (PersonaMem)، اور oracleagentmemory کے اعداد vendor کے خود رپورٹ شدہ دعوے ہیں جنہیں ہم نے آزادانہ طور پر دوبارہ تولید نہیں کیا (oracleagentmemory کا رن Oracle AI Database کے خلاف GPT-5.5 استعمال کرتا تھا)۔ محض اندازاً موازنے کے لیے ساتھ ساتھ دکھایا گیا ہے، ایک جیسے ڈیٹا پر براہِ راست مقابلہ نہیں۔ Star کی تعداد تخمینی ہے اور وقت کے ساتھ بدلتی رہتی ہے۔
+
+**نئے داخل ہونے والے** جن کے بارے میں جاننا مفید ہے، تفصیلی موازنہ [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) میں:
+
+| سسٹم | ⭐ | زاویہ |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Temporal نالج گراف؛ شائع شدہ temporal-query نتائج میں سب سے مضبوط (LongMemEval 63.8%)، لیکن گراف asynchronously بنتا ہے لہٰذا تازہ facts تاخیر سے آ سکتے ہیں |
+| Cognee | 30K | Document-to-knowledge-graph ingestion، صرف Python، structured entity extraction کے لیے بنایا گیا ہے، سیشن کیپچر کے لیے نہیں |
+
+ان میں سے کوئی بھی coding-agent hooks سے خودکار کیپچر نہیں کرتا، local-first ویور نہیں دیتا، یا keyless نہیں چلتا — یہ وہی ترکیب ہے جس کے گرد agentmemory تعمیر کیا گیا ہے۔
+
+---
+
+
+
+مطابقت: یہ ریلیز `iii-sdk` 0.22.1 کو ہدف بناتی ہے اور iii-engine v0.22.1 کو pin کرتی ہے۔
+
+### 30 سیکنڈ میں آزمائیں
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` 3 حقیقت پسندانہ سیشنز (JWT auth، N+1 query fix، rate limiting) seed کرتا ہے اور ان کے خلاف سرچز چلاتا ہے۔ Keyless انسٹالز ویکٹرز کو غیر فعال کر دیتے ہیں، لہٰذا `mem::search` کی-ورڈ کوئریز کو BM25 کے ذریعے ہِٹ ہونا چاہیے جبکہ `database performance optimization` صفر نتائج دے سکتی ہے۔ `smart-search` گراف ڈیٹا موجود ہونے کی صورت میں اضافی طور پر structural graph matches بھی واپس کر سکتا ہے۔ سیمینٹک کوئری کو ویکٹرز کے ذریعے N+1 fix ڈھونڈنے کے قابل بنانے کے لیے، `EMBEDDING_PROVIDER=local` سیٹ کریں، دوبارہ شروع کریں، اور پہلے ماڈل ڈاؤن لوڈ کو مکمل ہونے دیں۔
+
+میموری کو لائیو بنتے دیکھنے کے لیے `http://localhost:3113` کھولیں۔
+
+### ایک تازہ انسٹال اور ریسٹارٹ persistence کی توثیق کریں
+
+سرور چلنے کی حالت میں، REST، health، ویور، اور iii پر مبنی رن ٹائم اسٹیٹس کی توثیق کریں:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+اسٹارٹ اپ ready پینل تمام چار پورٹس کا حساب رکھتا ہے: 3111 پر REST/MCP HTTP، 3112 پر iii streams، 3113 پر ویور، اور 49134 پر iii ورکر WebSocket۔ `status` agentmemory کی health اور فعال provider/embedding موڈ کی تصدیق کرتا ہے۔ ایک probe محفوظ کریں اور تصدیق کریں کہ وہ تلاش کے قابل ہے:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+پھر `npx -y @agentmemory/agentmemory@latest stop` چلائیں، Terminal 1 میں معیاری کمانڈ دوبارہ شروع کریں، `/agentmemory/livez` کا انتظار کریں، اور سرچ دہرائیں۔ probe اب بھی واپس آنا چاہیے۔ اگر آپ نے کسٹم `--data-dir` منتخب کیا تھا، تو ریسٹارٹ پر وہی ڈائرکٹری پاس کریں۔
+
+### روزمرہ کی کمانڈز
+
+انسٹال اور سیٹ اپ اوپر [انسٹال](#install) میں موجود ہیں (پہلی بار چلانے پر آپ کی رہنمائی ہوتی ہے)۔ روزمرہ:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### سیشن ری پلے
+
+agentmemory جو بھی سیشن ریکارڈ کرتا ہے وہ دوبارہ چلایا (replay) جا سکتا ہے۔ ویور کھولیں، **Replay** ٹیب منتخب کریں، اور ٹائم لائن میں آگے پیچھے دیکھیں: prompts، tool calls، tool results، اور responses الگ الگ events کی صورت میں play/pause، رفتار کنٹرول (0.5x سے 4x)، اور کی بورڈ شارٹ کٹس (toggle کے لیے space، قدم بڑھانے کے لیے arrows) کے ساتھ دکھائے جاتے ہیں۔
+
+پرانے Claude Code JSONL transcripts لانے کے لیے:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Import کیے گئے سیشنز نیٹیو سیشنز کے ساتھ Replay picker میں ظاہر ہوتے ہیں۔ پسِ پردہ ہر entry `mem::replay::load`، `mem::replay::sessions`، اور `mem::replay::import-jsonl` iii فنکشنز کے ذریعے روٹ ہوتی ہے، بغیر کسی side-channel سرورز کے۔ ہر import کیا گیا transcript سرچ کے لیے indexed ہوتا ہے، اس پر origin channel `import` کا نشان لگایا جاتا ہے، اور اس سے session crystal اور lessons نکالے جاتے ہیں۔
+
+> **خبردار اگر آپ `import-jsonl` کو اپنے بنیادی کیپچر راستے کے طور پر استعمال کر رہے ہیں:** Claude Code کی `cleanupPeriodDays` سیٹنگ (`~/.claude/settings.json` میں، ڈیفالٹ **30**) اس حد سے پرانے JSONL transcripts کو `~/.claude/projects/` سے خودکار طور پر ڈیلیٹ کر دیتی ہے۔ اگر آپ مہینوں پرانی Claude Code ہسٹری پر agentmemory کو تازہ انسٹال کرتے ہیں، تو 30 دن سے پرانی کوئی بھی چیز پہلے import سے پہلے ہی ختم ہو چکی ہوگی۔ یا تو `import-jsonl` کو cron پر چلائیں، `cleanupPeriodDays` کو زیادہ بڑھا دیں، یا auto-capture hooks جوڑیں (ڈیفالٹ plugin انسٹال راستہ) تاکہ سیشن کے لائیو ہونے کے دوران ہی ہر turn agentmemory میں پہنچ جائے اور JSONL cleanup غیر اہم ہو جائے۔
+
+### اپ گریڈ / مینٹیننس
+
+جب آپ جانستہ طور پر اپنا مقامی رن ٹائم اپ ڈیٹ کرنا چاہیں تو maintenance کمانڈ استعمال کریں:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+انتباہ: یہ کمانڈ موجودہ workspace/runtime کو تبدیل کرتی ہے۔ یہ JavaScript dependencies اپ ڈیٹ کر سکتی ہے اور pinned `iiidev/iii:0.22.1` Docker image کھینچ سکتی ہے۔ یہ کبھی بھی کوئی غیر-pinned یا نیا iii engine انسٹال نہیں کرتی۔
+
+عملی تفصیلات `src/cli.ts` میں موجود ہیں (`src/cli.ts:544-595` کے حوالے سے `runUpgrade` دیکھیں)۔
+
+### Claude Code (ایک بلاک، اسے پیسٹ کریں)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code بغیر plugin انسٹال کے (MCP-standalone راستہ)
+
+اگر آپ `/plugin install` استعمال کرنے کے بجائے agentmemory کے MCP سرور کو براہِ راست `~/.claude.json` کے ذریعے جوڑتے ہیں، تو Claude Code کبھی `${CLAUDE_PLUGIN_ROOT}` کو resolve نہیں کرتا اور آپ کو hook اسکرپٹس کو `~/.claude/settings.json` میں absolute paths کی طرف پوائنٹ کرنا پڑتا ہے۔ یہ paths عام طور پر agentmemory کا ورژن شامل رکھتے ہیں (مثلاً `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`)، لہٰذا اگلا اپ گریڈ خاموشی سے ہر ہک کو توڑ دیتا ہے۔
+
+متبادل حل:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+یہ انہی hook کمانڈز کو `~/.claude/settings.json` میں ضم کرتا ہے، ان absolute paths کے ساتھ جو currently installed `@agentmemory/agentmemory` پیکیج کی bundled `plugin/` ڈائرکٹری سے resolve ہوتے ہیں۔ paths کو تازہ کرنے کے لیے agentmemory اپ گریڈ کرنے کے بعد یہ کمانڈ دوبارہ چلائیں۔ اسی فائل میں موجود صارف کے entries محفوظ رہتے ہیں؛ صرف پہلے والے agentmemory entries تبدیل ہوتے ہیں۔ `/plugin install` راستہ استعمال کرنا ہی تجویز کردہ طریقہ رہتا ہے۔
+ریموٹ یا محفوظ deployments کے لیے، Claude Code کو `AGENTMEMORY_URL` اور `AGENTMEMORY_SECRET` سیٹ کر کے لانچ کریں۔ plugin دونوں قدریں اپنے bundled MCP سرور تک پہنچاتا ہے؛ جب `AGENTMEMORY_URL` خالی ہو، تو MCP shim `http://localhost:3111` استعمال کرتا ہے۔
+
+### Codex CLI (Codex plugin پلیٹ فارم)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Codex plugin اسی `plugin/` ڈائرکٹری سے شپ ہوتا ہے جس سے Claude Code plugin ہوتا ہے۔ یہ رجسٹر کرتا ہے:
+
+- چلتے ہوئے daemon کی طرف ایک bundled stdio MCP bridge، بغیر npm download یا fallback store کے۔ ایک unreleased build ٹیسٹ کرنے کے لیے [مقامی Codex guide](../docs/plugins/codex-local.md) دیکھیں۔
+- 6 lifecycle ہکس: `SessionStart`، `UserPromptSubmit`، `PreToolUse`، `PostToolUse`، `PreCompact`، `Stop`
+- 9 invocable اسکلز: `/recall`، `/remember`، `/session-history`، `/forget`، `/recap`، `/handoff`، `/lesson`، `/commit-context`، `/commit-history`، نیز 8 reference اسکلز جنہیں ایجنٹ ضرورت پڑنے پر لوڈ کرتا ہے (memory discipline، MCP tools، REST API، config، agents، hooks، architecture، اور skill-authoring گائیڈ)
+
+Codex کا hook انجن `CLAUDE_PLUGIN_ROOT` کو hook subprocesses میں انجیکٹ کرتا ہے ([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs) کے مطابق)، لہٰذا وہی hook اسکرپٹس دونوں hosts پر بغیر دہرائے کام کرتے ہیں۔ Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events صرف Claude-Code کے لیے ہیں اور Codex کے لیے رجسٹر نہیں ہوتے۔
+
+#### Codex hooks پر اعتماد اور مطابقت
+
+Codex CLI 0.150.1 کے ساتھ native plugin hook dispatch تصدیق شدہ ہے۔ کیپچر کی توقع کرنے سے پہلے plugin hooks پر اعتماد کریں۔ Desktop کا رویہ اس کے bundled runtime پر منحصر ہے؛ کوئی workaround فعال کرنے سے پہلے `/hooks` چیک کریں اور ایک captured event کی تصدیق کریں۔
+
+اگر آپ کا host global hooks کا تقاضا کرتا ہے، تو کمانڈز کو `~/.codex/hooks.json` میں mirror کریں۔ جب MCP پہلے سے wired ہو، تو موجودہ connector کو hook installation تک پہنچنے کے لیے `--force` کی ضرورت ہوتی ہے:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+یہ global hooks کو ضم کرتا ہے اور agentmemory MCP entry کو دوبارہ لکھتا ہے، غیر متعلقہ entries کو محفوظ رکھتے ہوئے۔ `--force` استعمال کرنے سے پہلے کسی بھی کسٹم agentmemory endpoint سیٹنگز کا جائزہ لیں۔ script paths ریفریش کرنے کے لیے اپ گریڈ کے بعد دوبارہ چلائیں۔ duplicate capture سے بچنے کے لیے native plugin hooks یا global کاپیز میں سے کوئی ایک فعال کریں۔
+
+### GitHub Copilot CLI
+
+VS Code کے agent mode کے لیے، [Copilot MCP اور automatic-capture گائیڈ](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions) استعمال کریں۔ CLI connector VS Code کو کنفیگر نہیں کرتا۔
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` `mcpServers.agentmemory` کو `~/.copilot/mcp-config.json` میں ضم کرتا ہے (یا جب `COPILOT_HOME` سیٹ ہو تو `$COPILOT_HOME/mcp-config.json` میں) اور موجودہ سرورز کو محفوظ رکھتا ہے۔ نیٹیو Windows پر یہ واحد خودکار `connect` adapter ہے؛ ہر دوسرے نیٹیو Windows ایجنٹ کو دستی طور پر کنفیگر کریں۔ WSL `connect` صرف اس وقت معاون ہے جب target ایجنٹ اسی WSL ماحول میں انسٹال ہو۔ Copilot اگلے لانچ پر یا `/mcp` کے بعد MCP سرور اٹھا لیتا ہے۔ مکمل hook/skill تجربے کے لیے plugin بھی انسٹال کریں۔
+
+
+OpenClaw (یہ prompt پیسٹ کریں)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+مکمل گائیڈ: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (یہ prompt پیسٹ کریں)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+مکمل گائیڈ: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### دیگر ایجنٹس
+
+میموری سرور شروع کریں: `npx -y @agentmemory/agentmemory@latest`
+
+#### `npx skills add` کے ذریعے نیٹیو اسکلز (50+ ایجنٹس)
+
+agentmemory 17 اسکلز کو Claude-Code طرز کے `/SKILL.md` فارمیٹ میں شپ کرتا ہے: 9 invocable ایکشن اسکلز (`remember`، `recall`، `recap`، `handoff`، `forget`، `lesson`، `commit-context`، `commit-history`، `session-history`) اور 8 reference اسکلز جنہیں ایجنٹ ضرورت پڑنے پر لوڈ کرتا ہے (`memory-discipline`، `agentmemory-mcp-tools`، `agentmemory-rest-api`، `agentmemory-config`، `agentmemory-agents`، `agentmemory-hooks`، `agentmemory-architecture`، `write-agentmemory-skill`)۔ reference اسکلز سورس سے تیار کردہ data tables رکھتی ہیں، لہٰذا یہ کبھی drift نہیں کرتیں۔ vercel-labs کا [`skills`](https://npmjs.com/package/skills) CLI انہیں calling ایجنٹ کی نیٹیو اسکل ڈائرکٹری میں 50+ ایجنٹس (Claude Code، Cursor، Cline، Continue، Droid، Warp، Codex، Antigravity، Kiro، OpenCode، Goose، Roo، Trae، Windsurf، اور مزید) میں خودکار طور پر انسٹال کرتا ہے:
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+یہ `agentmemory connect ` کا **تکمیلی (complementary)** ہے:
+
+- `agentmemory connect ` MCP سرور کنفیگ لکھتا ہے تاکہ ٹولز دستیاب ہو جائیں۔
+- `npx skills add rohitg00/agentmemory` اسکلز انسٹال کرتا ہے تاکہ ایجنٹ کو معلوم ہو کہ انہیں کب کال کرنا ہے۔
+
+ان چند ایجنٹس کے لیے جنہیں skills CLI ابھی کَوَر نہیں کرتا (Zed v1.3.x اور اس سے نیچے)، خود 17 SKILL.md فائلیں ایجنٹ کی نیٹیو اسکل ڈائرکٹری میں رکھیں؛ وہی فارمیٹ ہر جگہ کام کرتا ہے۔
+
+#### معیاری MCP بلاک
+
+agentmemory کا entry ہر اس host پر **ایک ہی MCP سرور بلاک** ہے جو `mcpServers` شکل استعمال کرتا ہے (Cursor، Claude Desktop، Cline، Roo Code، Gemini CLI، OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**اس entry کو host کی config فائل میں موجودہ `mcpServers` object میں ضم کریں**؛ فائل کو تبدیل نہ کریں۔ اگر فائل میں پہلے سے دوسرے سرورز موجود ہیں، تو `agentmemory` کو ان کے ساتھ `mcpServers` کے اندر ایک اور key کے طور پر شامل کریں۔ اگر `mcpServers` مکمل طور پر غائب ہے، تو بلاک کو `{ "mcpServers": { ... } }` کے اندر پیسٹ کریں۔ `${VAR}` placeholders MCP-سرور لانچ کے وقت shell سے `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` وراثت میں لیتے ہیں؛ سیٹ نہ ہونے والی vars خالی strings پاس کرتی ہیں اور shim `http://localhost:3111` پر فال بیک کرتا ہے۔ ایک جوڑا گیا entry مقامی اور ریموٹ (k8s / reverse-proxied) دونوں deployments کو کَوَر کرتا ہے۔
+
+| ایجنٹ | کنفیگ فائل | نوٹس |
+|---|---|---|
+| **Cursor (صرف MCP)** | `~/.cursor/mcp.json` | `mcpServers` میں ضم کریں، یا `agentmemory connect cursor`۔ ویب سائٹ پر ون-کلک deeplink بھی دستیاب ہے۔ |
+| **Cursor (مکمل plugin)** | `.cursor-plugin/` | Cursor Marketplace لسٹنگ (submission زیرِ جائزہ) یا Cursor Settings → Plugins → local checkout۔ 7 auto-capture ہکس رجسٹر کرتا ہے (sessionStart، beforeSubmitPrompt، preToolUse، postToolUse، postToolUseFailure، stop، sessionEnd) + 17 اسکلز + MCP سرور، جن کے `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` Cursor کے plugin dashboard میں منیج ہوتے ہیں۔ Cursor IDE اور `cursor-agent` CLI دونوں میں کام کرتا ہے؛ CLI کے print-mode prompts سیشن کے اختتام پر session transcript سے backfill ہوتے ہیں۔ |
+| **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` بلاک۔ |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` MCP entry کو ضم کرتا ہے؛ `--with-hooks` Devin کے lowercase tool matchers کے ساتھ چھ نیٹیو auto-capture ہکس شامل کرتا ہے (SessionStart، UserPromptSubmit، PreToolUse، PostToolUse، Stop، SessionEnd)۔ `devin mcp list` اور devin کے اندر `/hooks` سے توثیق کریں۔ |
+| **Devin CLI (مکمل plugin)** | `plugin/.devin-plugin/` | ایک checkout سے `devin plugins install ./plugin` تمام 17 اسکلز کو `/agentmemory:` سلیش کمانڈز کے طور پر رجسٹر کرتا ہے نیز MCP سرور بھی۔ Devin plugin hooks `SessionStart`/`SessionEnd` فائر نہیں کر سکتے، لہٰذا مکمل سیشن کیپچر کے لیے اسے `connect devin --with-hooks` کے ساتھ جوڑیں۔ |
+| **Devin (کلاؤڈ)** | Settings → Connections → MCP servers | ایک کسٹم MCP (STDIO) شامل کریں: command `npx`، args `-y @agentmemory/mcp@latest`، env `AGENTMEMORY_URL` جو کسی نیٹ ورک پر قابلِ رسائی agentmemory deployment کی طرف اشارہ کرے نیز `AGENTMEMORY_SECRET` (کلاؤڈ سیشنز localhost تک نہیں پہنچ سکتے — [`deploy/`](../deploy/) دیکھیں)۔ secret کو Devin Secrets میں محفوظ کریں، پھر یہ تصدیق کرنے کے لیے کہ تمام 54 ٹولز ظاہر ہو رہے ہیں "Test listing tools" استعمال کریں۔ |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (خودکار طور پر ضم ہو جاتا ہے)۔ |
+| **GitHub Copilot CLI (صرف MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` `mcpServers.agentmemory` کو ضم کرتا ہے؛ Copilot اسے اگلے لانچ پر یا `/mcp` کے بعد اٹھا لیتا ہے۔ |
+| **GitHub Copilot CLI (مکمل plugin)** | Copilot plugin install | GitHub subdir سے plugin کے لیے `copilot plugin install rohitg00/agentmemory:plugin`۔ |
+| **OpenClaw** | OpenClaw MCP config | وہی `mcpServers` بلاک۔ گہرائی میں: `openclaw plugins install ./integrations/openclaw` OpenClaw کے memory slot پر قابض ہوتا ہے (`memory-core` سے خودکار سوئچ)؛ `plugins.entries.agentmemory.hooks.allowConversationAccess=true` سیٹ کریں ورنہ turn کیپچر خاموشی سے بلاک ہو جاتا ہے۔ [`integrations/openclaw`](../integrations/openclaw/) دیکھیں۔ |
+| **Codex CLI (صرف MCP)** | `.codex/config.toml` | TOML شکل: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`، یا دستی طور پر `[mcp_servers.agentmemory]` شامل کریں۔ |
+| **Codex CLI (مکمل plugin)** | Codex plugin marketplace | پہلے `codex plugin marketplace add rohitg00/agentmemory` پھر `codex plugin add agentmemory@agentmemory`۔ MCP + 6 lifecycle ہکس + 17 اسکلز رجسٹر کرتا ہے۔ اپنے host میں hooks پر اعتماد کریں اور کیپچر کی تصدیق کریں؛ دیکھیں [Codex سیٹ اپ اور توثیق](../docs/plugins/codex-local.md)۔ |
+| **OpenCode (صرف MCP)** | `opencode.json` | مختلف شکل: top-level `mcp` key، command ایک array کے طور پر: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`۔ |
+| **OpenCode (مکمل plugin)** | `plugin/opencode/` | 22 auto-capture hooks جو session lifecycle، messages، tools، errors کو کَوَر کرتے ہیں۔ Project attribution فی-سیشن ہے، لہٰذا کئی repositories پر پھیلا ہوا ایک OpenCode process ہر سیشن کو اس کے اپنے project کے تحت فائل کرتا ہے۔ دو سلیش کمانڈز (`/recall`، `/remember`)۔ `plugin/opencode/` کو اپنے OpenCode workspace میں کاپی کریں اور `opencode.json` میں plugin entry شامل کریں۔ مکمل hook ٹیبل + gap analysis کے لیے [`plugin/opencode/README.md`](../plugin/opencode/README.md) دیکھیں۔ |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` bundled extension کو pi کی auto-discovery ڈائرکٹری میں انسٹال کرتا ہے (ایجنٹ شروع ہونے پر recall، ایجنٹ ختم ہونے پر کیپچر، `memory_search` / `memory_save` / `memory_health` ٹولز، `/agentmemory-status`)۔ چلتے ہوئے pi میں `/reload` اسے اٹھا لیتا ہے۔ [`integrations/pi`](../integrations/pi/) ایک pi پیکیج بھی ہے (ایک checkout سے `pi install ./integrations/pi`)۔ |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` 6-hook میموری provider دیتا ہے (prefetch، turn کیپچر، session end، pre-compress، MEMORY.md mirroring، system prompt block)۔ `hermes plugins doctor` اور `hermes memory status` سے توثیق کریں۔ [`integrations/hermes`](../integrations/hermes/) دیکھیں۔ |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` معیاری `mcpServers` بلاک لکھتا ہے۔ Hook payload Claude Code کے ساتھ field-compatible ہے، لہٰذا موجودہ 12-hook اسکرپٹس بغیر ترمیم کے کام کرتے ہیں؛ انہیں اسی `settings.json` میں `hooks` سیکشن کے ذریعے جوڑیں۔ |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` مشترکہ customization ڈائرکٹری میں MCP اور capture hooks انسٹال کرتا ہے۔ دیکھیں [Antigravity سیٹ اپ اور حدود](../docs/plugins/antigravity.md)۔ |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` موجودہ IDE ورژنز جیسی ہی MCP اور hook configuration استعمال کرتا ہے۔ موجودہ انسٹالیشنز کو `--force` کے ساتھ ریفریش کرنا چاہیے؛ دیکھیں [اپ گریڈ نوٹس](../docs/plugins/antigravity.md)۔ |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` user-level کنفیگ لکھتا ہے۔ Workspace overrides آپ کے کوڈ کے ساتھ `.kiro/settings/mcp.json` میں جاتے ہیں۔ |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` معیاری `mcpServers` بلاک لکھتا ہے۔ Warp `.claude/skills/` سے اسکلز کو بھی خودکار طور پر دریافت کرتا ہے؛ ایک بار Claude Code plugin انسٹال ہونے پر 8 agentmemory اسکلز (`remember`، `recall`، `recap`، `handoff`، `forget`، `commit-context`، `commit-history`، `session-history`) Warp کے slash-command palette میں نیٹیو طور پر ظاہر ہوتی ہیں۔ |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` معیاری `mcpServers` بلاک لکھتا ہے۔ VS Code extension صارفین: وہی بلاک Cline Settings → MCP Servers → Edit JSON کے ذریعے پیسٹ کریں۔ |
+| **Continue.dev** | `~/.continue/config.yaml` (ترجیحی) یا `config.json` (legacy) | جب دونوں میں سے کوئی موجود نہ ہو تو `agentmemory connect continue` نئے سرے سے `config.yaml` بناتا ہے، یا موجودہ `config.json` میں ترمیم کرتا ہے۔ **اگر آپ کے پاس پہلے سے `config.yaml` ہے** تو adapter `mcpServers:` کے نیچے پیسٹ کرنے کے لیے عین وہی بلاک پرنٹ کرتا ہے؛ یہ خاموشی سے آپ کی yaml کو دوبارہ نہیں لکھتا کیونکہ comments اور anchors کو محفوظ طریقے سے برقرار رکھنے کے لیے ایک YAML parser درکار ہے جو یہ پیکیج شپ نہیں کرتا۔ Continue `mcpServers` کے لیے array شکل (object نہیں) استعمال کرتا ہے۔ |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` `context_servers` کے تحت لکھتا ہے (Zed کی اپنی key، `mcpServers` نہیں)۔ ریموٹ MCP سرورز کو بجائے `{"url": "..."}` کے ذریعے جوڑا جا سکتا ہے۔ |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` معیاری `mcpServers` بلاک لکھتا ہے۔ Project-scoped overrides `/.factory/mcp.json` میں جاتے ہیں۔ نیٹیو auto-capture کے لیے `--with-hooks` پاس کریں۔ |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` home-level patch layer میں ایک `@deepseek-ai/dsh-mcp-client` row شامل کرتا ہے جسے ہر Harness profile لوڈ کرتا ہے؛ tools `mcp__agentmemory__*` کے طور پر رجسٹر ہوتے ہیں۔ auto-capture بھی جوڑنے کے لیے `--with-hooks` پاس کریں: bundled Claude Code hook اسکرپٹس Harness کے first-party `@deepseek-ai/dsh-hooks-claude-code` bridge (SessionStart، UserPromptSubmit، PreToolUse، PostToolUse، Stop) کے ذریعے `$DSH_HOME/agentmemory.hooks.json` میں لکھے گئے ایک manifest سے چلتے ہیں۔ جب `DSH_HOME` سیٹ نہ ہو تو ڈیفالٹ `~/.dsh` ہے۔ |
+| **Goose** | Goose MCP settings UI | وہی `mcpServers` بلاک؛ `goose configure` → Add Extension → MCP استعمال کریں۔ `~/.config/goose/config.yaml` پر براہِ راست YAML ترمیم معاون ہے لیکن schema `extensions:` + `cmd` استعمال کرتا ہے (`mcpServers:` + `command` نہیں)۔ |
+| **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 کو خودکار طور پر detect کرتا ہے اور ضم کرتا ہے۔ |
+
+**Sandboxed MCP کلائنٹس** (Flatpak / Snap / restrictive containers) جو host کے `localhost` تک نہیں پہنچ سکتے: `env` بلاک میں `"AGENTMEMORY_FORCE_PROXY": "1"` بھی سیٹ کریں، اور `AGENTMEMORY_URL` کو کسی ایسے route کی طرف پوائنٹ کریں جہاں sandbox واقعی پہنچ سکے (مثلاً آپ کا LAN IP)۔
+
+### پروگرامیٹک رسائی (Python / Rust / Node)
+
+agentmemory اپنے core operations کو 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/) (quickstart + observation/recall فلو)۔ iii رن ٹائم کے بغیر hosts کے لیے `:3111` پر REST بدستور دستیاب ہے۔
+
+### سورس سے
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+اگر pinned بائنری پہلے سے انسٹال ہے تو یہ agentmemory کو مقامی `iii-engine` کے ساتھ شروع کرتا ہے، یا منتخب ہونے پر Docker Compose استعمال کرتا ہے۔ REST، streams، اور ویور ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتے ہیں۔ خودکار macOS/Linux بائنری راستے کو `curl`، ایک POSIX `sh`، اور `tar` درکار ہیں۔
+
+`iii-engine` کو دستی طور پر انسٹال کریں۔ **agentmemory فی الحال `iii-engine` کو `v0.22.1` پر pin کرتا ہے**، یہی وہ ریلیز ہے جو اس کی `iii-sdk` dependency کی بھی ہے؛ ورکر اسی انجن کا wire پروٹوکول بولتا ہے، اور 0.20.0 نے SDK سطح کو دوبارہ ترتیب دیا تھا، لہٰذا یہ دونوں agentmemory ریلیزز میں ساتھ ساتھ چلتے ہیں۔ اگر آپ اپنا انجن چلاتے ہیں اور جانتے ہیں کہ یہ میچ کرتا ہے تو `AGENTMEMORY_III_VERSION=` سے اوور رائیڈ کریں۔
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** `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.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) سے `iii-x86_64-pc-windows-msvc.zip` ڈاؤن لوڈ کریں اور `iii.exe` کو `%USERPROFILE%\.agentmemory\bin\iii.exe` میں ایکسٹریکٹ کریں
+
+ہر archive کا release page پر ایک مماثل `.sha256` فائل موجود ہے؛ پلیٹ فارم بدلتے وقت، اوپر دیے گئے چیک میں وہی فائل کا hash استعمال کریں (Windows پر: `Get-FileHash`)۔ `npx @agentmemory/agentmemory` میں خودکار انسٹالر ان hashes کو pin کرتا ہے اور کسی غیر مماثل archive کو مسترد کر دیتا ہے۔
+
+یا Docker استعمال کریں (bundled `docker-compose.yml` `iiidev/iii:0.22.1` کھینچتا ہے)۔ مکمل docs: [iii.dev/docs](https://iii.dev/docs)۔
+
+### Windows
+
+agentmemory Windows 10/11 پر چلتا ہے، لیکن صرف Node.js پیکیج کافی نہیں؛ آپ کو ایک background process کے طور پر pinned iii-engine v0.22.1 رن ٹائم بھی درکار ہے۔ CLI Windows ZIP کو خودکار طور پر ایکسٹریکٹ نہیں کرتا، لہٰذا نیٹیو Windows صارفین کو `iii.exe` دستی طور پر انسٹال کرنا، WSL2 استعمال کرنا، یا Docker Desktop منتخب کرنا ضروری ہے۔
+
+نیٹیو Windows خودکار MCP wiring صرف `agentmemory connect copilot-cli` کو سپورٹ کرتی ہے۔ Claude Code، Codex، Cursor، اور ہر دوسرے نیٹیو Windows ایجنٹ کے لیے، [دیگر ایجنٹس](#other-agents) سے دستی MCP بلاک کو اس ایجنٹ کی Windows کنفیگ میں کاپی کریں۔ WSL میں `connect` چلانا صرف اس وقت مناسب ہے جب target ایجنٹ بھی اسی WSL ماحول میں انسٹال ہو؛ یہ کسی Windows-host ایجنٹ کی کنفیگریشن میں ترمیم نہیں کرتا۔
+
+**آپشن A: prebuilt Windows بائنری (تجویز کردہ)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**آپشن B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**آپشن C: صرف اسٹینڈ الون MCP (کوئی انجن نہیں)۔** اگر آپ کو اپنے ایجنٹ کے لیے صرف MCP ٹولز درکار ہیں اور REST API، ویور، یا cron jobs کی ضرورت نہیں، تو انجن کو مکمل طور پر نظرانداز کریں:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Windows کے لیے Diagnostics:** اگر `npx -y @agentmemory/agentmemory@latest` ناکام ہو جائے، تو اصل انجن stderr دیکھنے کے لیے اسے `--verbose` کے ساتھ دوبارہ چلائیں۔ عام ناکامی کی صورتیں:
+
+| علامت | حل |
+|---|---|
+| `The engine process started but the REST API never responded.` | تصدیق کریں کہ تمام چار derived پورٹس خالی ہیں، چیک کریں کہ pinned `iii.exe` زندہ رہا، پھر `--verbose` کے ساتھ دوبارہ چلائیں اور captured انجن stderr دیکھیں |
+| `Could not start iii-engine` | نہ `iii.exe` اور نہ ہی Docker انسٹال ہے۔ اوپر آپشن A یا B دیکھیں |
+| پورٹ ٹکراؤ (conflict) | کیا bound ہے دیکھنے کے لیے `netstat -ano \| findstr :3111`، پھر اسے kill کریں یا `--port ` استعمال کریں |
+| Docker انسٹال ہونے کے باوجود Docker fallback چھوڑ دیا گیا | یقینی بنائیں کہ Docker Desktop واقعی چل رہا ہے (system tray آئیکن) |
+
+> نوٹ: iii **انجن** ایک prebuilt بائنری ہے، cargo crate نہیں، لہٰذا اسے `cargo install` کرنے کی کوشش نہ کریں۔ (iii **SDKs** crates.io، npm، اور PyPI پر شائع ہوتے ہیں، لیکن agentmemory کو ان کی ضرورت نہیں۔) معاون انجن انسٹال طریقے سب v0.22.1 پر pinned ہیں: اوپر دی گئی prebuilt بائنری، agentmemory کا macOS/Linux auto-install راستہ (`curl`، POSIX `sh`، اور `tar` درکار)، اور Docker image `iiidev/iii:0.22.1`۔ ایک خالی upstream `install.sh | sh` تازہ ترین انجن انسٹال کرتا ہے، جسے agentmemory سپورٹ نہیں کرتا۔ `npx -y @agentmemory/agentmemory@latest` استعمال کریں؛ macOS/Linux پر یہ pinned انجن کو `~/.agentmemory/bin` میں لاتا ہے۔
+
+---
+
+
ڈیپلائی
+
+منظم hosts کے لیے ون-کلک templates۔ ہر ایک ایک self-contained Dockerfile شپ کرتا ہے جو npm سے `@agentmemory/agentmemory` کھینچتا ہے اور سرکاری `iiidev/iii` Docker Hub image سے iii انجن بائنری کاپی کرتا ہے؛ کسی pre-built agentmemory image کی ضرورت نہیں۔ Persistent اسٹوریج `/data` پر mount ہوتا ہے؛ first-boot entrypoint npm-bundled iii کنفیگ (جو `127.0.0.1` سے bind ہوتا ہے) کو ایک deploy-tuned کنفیگ سے overwrite کرتا ہے جو `0.0.0.0` سے bind ہوتا ہے اور absolute `/data` paths استعمال کرتا ہے، HMAC secret تیار کرتا ہے، پھر agentmemory CLI کو exec کرنے سے پہلے `gosu` کے ذریعے `root` سے `node` تک privileges کم کر دیتا ہے۔
+
+
+
+
+
+
+Render کے ون-کلک ڈیپلائی بٹن کو repository کی root میں `render.yaml` درکار ہے، جسے ہم جانستہ طور پر صاف رکھتے ہیں۔ in-repo blueprint کی طرف دستی طور پر اشارہ کرنے کے لیے [`deploy/render/`](.././deploy/render/README.md) میں دستاویزی Render Blueprint فلو استعمال کریں۔
+
+مکمل سیٹ اپ تفصیلات (HMAC کیپچر، ویور SSH tunnel، rotation، backup، cost floors) [`deploy/`](.././deploy/README.md) میں موجود ہیں:
+
+- [`deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"` کے ساتھ ایک مشین؛ سب سے سستا idle۔
+- [`deploy/railway`](.././deploy/railway/README.md): Hobby plan فلیٹ فیس، dashboard میں volume۔
+- [`deploy/render`](.././deploy/render/README.md): Blueprint فلو، paid plans پر خودکار disk snapshots۔
+- [`deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted) کے ذریعے آپ کے اپنے VPS پر سیلف-ہوسٹڈ؛ وہی Docker Compose اسٹیک، host اور data دونوں آپ کے اپنے۔
+
+صرف پورٹ `3111` publish کی جاتی ہے۔ `3113` پر ویور container کے اندر loopback سے bound رہتا ہے؛ ہر template کا README اس تک پہنچنے کے لیے SSH-tunnel پیٹرن دستاویز کرتا ہے۔
+
+---
+
+
+
+ہر کوڈنگ ایجنٹ سیشن ختم ہوتے ہی سب کچھ بھول جاتا ہے، اور ہر نیا سیشن آپ کے دوبارہ اپنا 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.
+```
+
+### بلٹ-اِن ایجنٹ میموری کے مقابلے میں
+
+ہر AI کوڈنگ ایجنٹ بلٹ-اِن میموری کے ساتھ آتا ہے: Claude Code کے پاس `MEMORY.md` ہے، Cursor کے پاس notepads ہیں، Cline کے پاس memory bank ہے۔ یہ sticky notes کی طرح کام کرتے ہیں۔ agentmemory ان sticky notes کے پیچھے موجود searchable ڈیٹابیس ہے۔
+
+| | بلٹ-اِن (CLAUDE.md) | agentmemory |
+|---|---|---|
+| اسکیل | 200-لائن کی حد | لامحدود |
+| سرچ | سب کچھ context میں لوڈ کرتا ہے | BM25 + ویکٹر + گراف (صرف top-K) |
+| ٹوکن لاگت | 240 observations پر 22K+ | ~1,900 ٹوکنز (92% کم) |
+| کراس-ایجنٹ | فی-ایجنٹ فائلیں | MCP + REST (کوئی بھی ایجنٹ) |
+| کوآرڈینیشن | کوئی نہیں | Leases، سگنلز، actions، routines |
+| Observability | دستی طور پر فائلیں پڑھنا | :3113 پر ریئل-ٹائم ویور |
+
+---
+
+
+
+### میموری Pipeline
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### 4-درجاتی میموری استحکام (Consolidation)
+
+یہ انسانی دماغ کے میموری پراسیس کرنے کے طریقے پر مبنی ہے، بشمول نیند کے دوران ہونے والا consolidation۔
+
+| درجہ | کیا | مثال (Analogy) |
+|------|------|---------|
+| **Working** | tool use سے خام observations | قلیل مدتی میموری |
+| **Episodic** | compressed سیشن خلاصے | "کیا ہوا" |
+| **Semantic** | نکالے گئے facts اور patterns | "میں کیا جانتا ہوں" |
+| **Procedural** | Workflows اور فیصلہ سازی کے patterns | "کیسے کرنا ہے" |
+
+میموریز وقت کے ساتھ decay ہوتی ہیں (Ebbinghaus curve)۔ بار بار رسائی کی جانے والی میموریز مضبوط ہوتی ہیں۔ Stale میموریز خودکار طور پر evict ہو جاتی ہیں۔ تضادات (contradictions) کو detect اور resolve کیا جاتا ہے۔
+
+### کیا کیپچر ہوتا ہے
+
+| Hook | کیپچر کرتا ہے |
+|------|----------|
+| `SessionStart` | Project path، session ID |
+| `UserPromptSubmit` | صارف کے prompts (privacy-filtered) |
+| `PreToolUse` | File access patterns + enriched context |
+| `PostToolUse` | Tool کا نام، input، output |
+| `PostToolUseFailure` | Error context |
+| `PreCompact` | compaction سے پہلے میموری دوبارہ انجیکٹ کرتا ہے |
+| `SubagentStart/Stop` | Sub-agent lifecycle |
+| `Stop` | سیشن کے اختتام کا خلاصہ |
+| `SessionEnd` | سیشن مکمل ہونے کا نشان |
+
+### اہم صلاحیتیں
+
+| Capability | تفصیل |
+|---|---|
+| **خودکار کیپچر** | ہر tool use ہکس کے ذریعے ریکارڈ ہوتا ہے، کوئی دستی کام نہیں |
+| **سیمینٹک سرچ** | RRF فیوژن کے ساتھ BM25 + ویکٹر + نالج گراف |
+| **میموری ارتقا** | Versioning، سپرسیشن، تعلقات کے گراف (relationship graphs) |
+| **ریکال hygiene** | سپرسیڈ شدہ میموری ورژنز سرچ indexes سے نکل جاتے ہیں؛ KV میں version chain مکمل ہسٹری رکھتی ہے |
+| **Near-duplicate اشارے** | جب نیا content کسی موجودہ میموری سے قریبی مشابہت رکھتا ہے تو saves ایک advisory `similarTo` match رپورٹ کرتے ہیں |
+| **فی-ایجنٹ scoping** | `agentId` REST، MCP، اور سرچ index میں save اور recall کے ذریعے، shared یا isolated موڈ میں، منتقل ہوتا ہے |
+| **تحریر کے وقت کی provenance** | ہر observation اور میموری ایک غیر قابلِ تبدیل origin channel رکھتی ہے (user، agent، tool، import، یا shared) جو کیپچر، save، اور import کے وقت لگایا جاتا ہے |
+| **خودکار فراموشی** | TTL expiry، تضاد کی شناخت، اہمیت کی بنیاد پر eviction |
+| **پرائیویسی اولین ترجیح** | API keys، secrets، `` ٹیگز محفوظ کرنے سے پہلے ہٹا دیے جاتے ہیں |
+| **خود-شفا (Self-healing)** | Circuit breaker، provider fallback chain، health monitoring |
+| **Claude bridge** | MEMORY.md کے ساتھ دو طرفہ sync |
+| **نالج گراف** | Entity extraction + BFS traversal |
+| **ٹیم میموری** | ٹیم ممبران میں namespaced shared + private |
+| **Citation provenance** | کسی بھی میموری کو اس کی ماخذ observations تک trace کریں |
+| **Git snapshots** | میموری اسٹیٹ کو version، rollback، اور diff کریں |
+
+---
+
+
+
+تین سگنلز کو یکجا کرنے والی Triple-stream ریٹریول:
+
+| Stream | یہ کیا کرتا ہے | کب |
+|---|---|---|
+| **BM25** | Synonym expansion کے ساتھ stemmed کی-ورڈ matching | ہمیشہ آن |
+| **Vector** | Dense embeddings پر Cosine similarity | Embedding provider کنفیگر ہو |
+| **Graph** | Entity matching کے ذریعے نالج گراف traversal | کوئری میں entities detect ہوں |
+
+Reciprocal Rank Fusion (RRF، k=60) کے ساتھ فیوز کیا گیا اور session-diversified (فی سیشن زیادہ سے زیادہ 3 نتائج)۔
+
+جب ویکٹر index پاپولیٹڈ ہو، `mem::search` (`memory_recall` کے پیچھے) hybrid BM25 + vector ranker استعمال کرتا ہے۔ embeddings کے بغیر یہ BM25 استعمال کرتا ہے۔ `smart-search` گراف ڈیٹا موجود ہونے پر اضافی طور پر structural graph matches بھی فیوز کر سکتا ہے۔ Lesson recall ہر کوئری پر پورے corpus کو اسکین کرنے کے بجائے ایک وقف شدہ in-memory BM25 index پر چلتا ہے۔ سپرسیڈ شدہ میموری ورژنز ہر recall راستے سے خارج ہوتے ہیں؛ version chain ان کی ہسٹری رکھتی ہے۔
+
+ویکٹرز کریش یا force-kill سے بچ جاتے ہیں۔ ویکٹر index کم از کم ہر `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 منٹ) بعد buckets میں محفوظ ہوتا ہے۔ اس دوران شامل یا ہٹایا گیا ہر ویکٹر state store میں ایک چھوٹے pending log میں فوراً لکھ دیا جاتا ہے، اور اگلا اسٹارٹ اسے embedding provider کو کال کیے بغیر replay کرتا ہے۔ ہر کامیاب save لاگ کو خالی کر دیتا ہے۔ وہ documents جن کا replay کے بعد بھی کوئی ویکٹر نہیں ہوتا انہیں پسِ منظر میں `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) کے batches میں دوبارہ embed کیا جاتا ہے جب تک کوئی باقی نہ رہے، اور رکا ہوا backfill اگلے اسٹارٹ پر جاری رہتا ہے۔ `/agentmemory/status` اور ویور pending log کا سائز اور backfill اسٹیٹس دکھاتے ہیں۔ Keyless انسٹالز کچھ نہیں لکھتے۔
+
+BM25 بذاتِ خود یونانی، سیریلک، عبرانی، عربی، اور accented Latin کو ٹوکنائز کرتا ہے۔ چینی / جاپانی / کوریائی میموریز کے لیے، CJK runs کو word-level tokens میں تقسیم کرنے کے لیے اختیاری segmenters (`npm install @node-rs/jieba tiny-segmenter`) انسٹال کریں؛ ان کے بغیر، agentmemory نرمی سے whole-run tokenization پر fall ہو جاتا ہے اور stderr پر ایک بار اشارہ پرنٹ کرتا ہے۔
+
+### Embedding providers
+
+Keyless انسٹالز ویکٹر embeddings کو غیر فعال کرتے ہیں: `mem::search` BM25 استعمال کرتا ہے، جبکہ `smart-search` موجودہ structural graph ڈیٹا بھی استعمال کر سکتا ہے۔ مفت آن-ڈیوائس سیمینٹک embeddings اختیار کرنے کے لیے، یہ `~/.agentmemory/.env` میں شامل کریں اور agentmemory دوبارہ شروع کریں:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+عام npm install میں اختیاری `@huggingface/transformers` رن ٹائم شامل ہے۔ پہلی embedding درخواست `Xenova/all-MiniLM-L6-v2` ڈاؤن لوڈ کرتی ہے، لہٰذا اسے نیٹ ورک رسائی درکار ہے اور زیادہ وقت لگ سکتا ہے؛ اس کے بعد inference آن-ڈیوائس چلتا ہے۔ ریموٹ providers ان کی keys سے خودکار طور پر detect ہوتے ہیں جب تک `EMBEDDING_PROVIDER` انہیں override نہ کرے۔
+
+| Provider | ماڈل | لاگت | نوٹس |
+|---|---|---|---|
+| **Local (تجویز کردہ opt-in)** | `all-MiniLM-L6-v2` | مفت | پہلے ماڈل ڈاؤن لوڈ کے بعد آن-ڈیوائس، صرف-BM25 کے مقابلے میں +8pp recall |
+| Gemini | `gemini-embedding-001` | مفت ٹیئر | 100+ زبانیں، 768/1536/3072 dims (MRL)، 2048-ٹوکن input۔ `text-embedding-004` کی جگہ لیتا ہے ([deprecated، shutdown Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | بہترین کوالٹی |
+| Voyage AI | `voyage-code-3` | ادا شدہ (Paid) | کوڈ کے لیے optimized |
+| Cohere | `embed-english-v3.0` | مفت trial | عمومی مقصد |
+| OpenRouter | کوئی بھی ماڈل | مختلف ہوتا ہے | Multi-model پراکسی |
+
+---
+
+
+
+54 ٹولز، 6 resources، 3 prompts، اور 17 اسکلز۔
+
+> **MCP shim بمقابلہ مکمل سرور:** شائع شدہ `@agentmemory/mcp` پیکیج ایک thin shim ہے۔ یہ مکمل 54-ٹول surface **صرف اس وقت ظاہر کرتا ہے جب یہ `AGENTMEMORY_URL` کے ذریعے کسی چلتے ہوئے agentmemory سرور تک پہنچ سکے** (proxy موڈ)۔ کوئی سرور قابلِ رسائی نہ ہونے پر، shim 7-ٹول مقامی سیٹ پر فال بیک کرتا ہے (`memory_save`، `memory_recall`، `memory_smart_search`، `memory_sessions`، `memory_export`، `memory_audit`، `memory_governance_delete`)۔ `AGENTMEMORY_TOOLS=core|all` env var ایک *سرور-سائیڈ* فلیگ ہے؛ اسے shim کے `env` بلاک میں سیٹ کرنے کا کوئی اثر نہیں ہوتا۔ اگر آپ کو Cursor / OpenCode / Gemini CLI میں صرف 7 ٹولز نظر آتے ہیں، تو `npx -y @agentmemory/agentmemory@latest` (یا Docker اسٹیک) شروع کریں اور `AGENTMEMORY_URL=http://localhost:3111` سیٹ کریں۔
+
+### 54 ٹولز
+
+تین tool surfaces، چھوٹے سے بڑے تک: `AGENTMEMORY_TOOLS=core` نظر آنے کی حد کو 8 بنیادی ٹولز تک محدود کرتا ہے (`memory_save`، `memory_recall`، `memory_consolidate`، `memory_smart_search`، `memory_sessions`، `memory_diagnose`، `memory_lesson_save`، `memory_reflect`)؛ نیچے دیا گیا base سیٹ registry کے 14 foundational ٹولز ہیں؛ ڈیفالٹ (`AGENTMEMORY_TOOLS=all`) تمام 54 کو ظاہر کرتا ہے۔
+
+
+بنیادی ٹولز (14)
+
+| ٹول | تفصیل |
+|------|-------------|
+| `memory_recall` | ماضی کی observations تلاش کریں |
+| `memory_compress_file` | ساخت برقرار رکھتے ہوئے markdown فائلیں compress کریں |
+| `memory_save` | کوئی insight، فیصلہ، یا pattern محفوظ کریں |
+| `memory_file_history` | مخصوص فائلوں کے بارے میں ماضی کی observations |
+| `memory_patterns` | بار بار آنے والے patterns detect کریں |
+| `memory_sessions` | حالیہ سیشنز کی فہرست |
+| `memory_smart_search` | Hybrid سیمینٹک + کی-ورڈ سرچ |
+| `memory_vision_search` | image observations تلاش کریں |
+| `memory_timeline` | تاریخ وار (chronological) observations |
+| `memory_profile` | Project profile (concepts، files، patterns) |
+| `memory_export` | تمام میموری ڈیٹا export کریں |
+| `memory_relations` | relationship گراف کوئری کریں |
+| `memory_commit_lookup` | کسی git commit کے پیچھے سیشنز |
+| `memory_commits` | کسی سیشن کے لیے ریکارڈ شدہ commits |
+
+
+
+
+وسیع ٹولز (کل 54، ڈیفالٹ surface)
+
+| ٹول | تفصیل |
+|------|-------------|
+| `memory_patterns` | بار بار آنے والے patterns detect کریں |
+| `memory_timeline` | تاریخ وار observations |
+| `memory_relations` | relationship گراف کوئری کریں |
+| `memory_graph_query` | نالج گراف traversal |
+| `memory_consolidate` | 4-درجاتی consolidation چلائیں |
+| `memory_claude_bridge_sync` | MEMORY.md کے ساتھ sync کریں |
+| `memory_team_share` | ٹیم ممبران کے ساتھ شیئر کریں |
+| `memory_team_feed` | حالیہ شیئر شدہ items |
+| `memory_audit` | operations کی audit trail |
+| `memory_governance_delete` | audit trail کے ساتھ ڈیلیٹ کریں |
+| `memory_snapshot_create` | Git-versioned snapshot |
+| `memory_action_create` | dependencies کے ساتھ work items بنائیں |
+| `memory_action_update` | action کی اسٹیٹس اپ ڈیٹ کریں |
+| `memory_frontier` | ترجیح کے لحاظ سے درجہ بندی شدہ unblocked actions |
+| `memory_next` | واحد سب سے اہم اگلا action |
+| `memory_lease` | Exclusive action leases (multi-agent) |
+| `memory_routine_run` | workflow routines کو instantiate کریں |
+| `memory_signal_send` | Inter-agent میسجنگ |
+| `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 کو خارجی طور پر فائر کریں |
+| `memory_sketch_create` | Ephemeral action graphs |
+| `memory_sketch_promote` | مستقل (permanent) میں promote کریں |
+| `memory_crystallize` | action chains کو compact کریں |
+| `memory_diagnose` | Health checks |
+| `memory_heal` | پھنسی ہوئی اسٹیٹ کو خودکار طور پر fix کریں |
+| `memory_facet_tag` | Dimension:value ٹیگز |
+| `memory_facet_query` | facet ٹیگز کے ذریعے کوئری کریں |
+| `memory_verify` | provenance trace کریں |
+
+
+
+### 6 Resources · 3 Prompts · 17 اسکلز
+
+| قسم | نام | تفصیل |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health، session count، memory count |
+| Resource | `agentmemory://project/{name}/profile` | Per-project انٹیلیجنس |
+| Resource | `agentmemory://project/{name}/recent` | کسی project کی حالیہ observations |
+| Resource | `agentmemory://memories/latest` | تازہ ترین 10 فعال میموریز |
+| Resource | `agentmemory://graph/stats` | نالج گراف اعداد و شمار |
+| Resource | `agentmemory://team/{id}/profile` | مشترک ٹیم پروفائل |
+| Prompt | `recall_context` | سرچ + context پیغامات واپس کریں |
+| Prompt | `session_handoff` | ایجنٹس کے درمیان ڈیٹا handoff |
+| Prompt | `detect_patterns` | بار بار آنے والے patterns کا تجزیہ |
+| Skill | `/recall` | میموری سرچ کریں |
+| Skill | `/remember` | طویل مدتی میموری میں محفوظ کریں |
+| Skill | `/session-history` | حالیہ سیشن خلاصے |
+| Skill | `/forget` | observations/sessions ڈیلیٹ کریں |
+
+یہ ٹیبل چار بنیادی اسکلز دکھاتا ہے۔ مکمل سیٹ 9 invocable اسکلز نیز 8 reference اسکلز پر مشتمل ہے؛ اوپر Native اسکلز سیکشن دیکھیں۔
+
+### Standalone MCP
+
+مکمل سرور کے بغیر، کسی بھی MCP کلائنٹ کے لیے چلائیں۔ ان میں سے کوئی بھی کام کرتا ہے:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+یا اپنے ایجنٹ کی MCP کنفیگ میں شامل کریں:
+
+زیادہ تر ایجنٹس (Cursor، Claude Desktop، Cline، Roo Code، Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+`agentmemory` entry کو فائل تبدیل کرنے کے بجائے اپنے host کے موجودہ `mcpServers` object میں ضم کریں۔ ان sandboxed کلائنٹس کے لیے جو host کے `localhost` تک نہیں پہنچ سکتے، env بلاک میں `"AGENTMEMORY_FORCE_PROXY": "1"` شامل کریں اور `AGENTMEMORY_URL` کو کسی ایسے route پر سیٹ کریں جہاں sandbox پہنچ سکے۔
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+repo سے plugin فائل کاپی کریں:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+پورٹ `3113` پر خودکار طور پر شروع ہوتا ہے۔ ویور جب کنکٹ ہوتا ہے تو ایک snapshot لوڈ کرتا ہے (`GET /agentmemory/viewer/snapshot`) اور پھر live stream events لاگو کرتا ہے: نئی میموریز، lessons، observations، audit entries، گراف تبدیلیاں اور health اپ ڈیٹس بغیر polling یا page reloads کے ظاہر ہوتے ہیں۔ باقی صرف وہی requests ہیں جو آپ کلک کرتے ہیں، "load more" صفحات اور سرچز۔ جب stream منقطع ہو، ویور دکھاتا ہے کہ اس کے اعداد کتنے پرانے ہیں، backoff کے ساتھ دوبارہ کنکٹ ہوتا ہے اور ایک snapshot سے دوبارہ sync کرتا ہے۔
+
+- **چار گروپس میں 12 tabs** لائیو counts، deep links (`#memories/`، `#sessions/?obs=`، `#graph/`، `#health/consolidation`)، کی بورڈ شارٹ کٹس اور ایک موبائل مینیو کے ساتھ۔
+- **Memories:** سرور-سائیڈ سرچ، project، agent اور type کے فلٹرز، version chain اور ایک word diff والا detail panel، provenance links، id کے لیے کاپی بٹنز، MCP call اور ایک curl کمانڈ، ترمیم (ایک نیا ورژن)، تصدیق کے ساتھ forget، bulk forget اور JSON export۔
+- **Sessions:** قابلِ مطالعہ tool input اور output کے ساتھ ایک inline observation ٹائم لائن، فلٹرز اور paging، اور ہر سیشن نے جو میموریز اور lessons پیدا کیے۔
+- **Graph:** سرچ، relations اور sources کے ساتھ node detail، ایک legend جو صرف رنگ پر انحصار نہیں کرتا، اور zoom کنٹرولز۔
+- **Health:** `GET /agentmemory/status` کا لائیو ورژن۔ ہر مسئلے کے ساتھ اس کا حل آتا ہے، نیز state backend، index save state، graph provenance compaction progress اور حقیقی thresholds کے ساتھ ایک consolidation explainer۔
+- **Audit، Activity، Profile، Replay، Lessons، Actions اور Crystals** صفحات، ہر ایک کی ایک empty state جو بتاتی ہے کہ سیکشن کیا ہے، یہ خالی کیوں ہے اور وہ کمانڈ جو اسے بھرتی ہے، اور ہر term اور number پر ایک `?` glossary ٹول ٹپ۔
+
+```bash
+open http://localhost:3113
+```
+
+ویور سرور ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے اور جب یہ REST API کو requests فارورڈ کرتا ہے تو سرور secret اٹیچ کرتا ہے، لہٰذا اسے کسی سیٹ اپ کی ضرورت نہیں۔ REST کے ذریعے سرو کیا گیا `/agentmemory/viewer` اینڈ پوائنٹ عام bearer-token قواعد کی پیروی کرتا ہے اور بغیر token والے browsers کو ویور پورٹ کی طرف ری ڈائریکٹ کرتا ہے۔ CSP headers ہر response کے لیے ایک script nonce استعمال کرتے ہیں اور inline handler attributes غیر فعال کرتے ہیں (`script-src-attr 'none'`)۔
+
+---
+
+
+
+`:3113` پر ویور دکھاتا ہے کہ آپ کے ایجنٹ نے **کیا یاد رکھا**۔ [iii کنسول](https://iii.dev/docs/console) دکھاتا ہے کہ آپ کے ایجنٹ نے **کیا کیا**: ہر میموری op ایک OpenTelemetry trace کے طور پر، ہر KV entry قابلِ ترمیم، ہر فنکشن invocable، ہر stream tap کرنے کے قابل۔ ایک ہی میموری پر دو کھڑکیاں: ایک product-shaped، ایک engine-shaped۔
+
+کسی `memory_smart_search` کو فائر ہوتے دیکھیں اور BM25 scan → embedding lookup → RRF fusion → reranker کو ایک waterfall کے طور پر دیکھیں۔ KV browser میں کسی پھنسے ہوئے consolidation timer میں ترمیم کریں۔ کسی تبدیل شدہ payload کے ساتھ `PostToolUse` hook کو دوبارہ چلائیں (replay)۔ WebSocket stream کو pin کریں اور observations کو لائیو آتے دیکھیں۔
+
+agentmemory یہ مفت فراہم کرتا ہے کیونکہ ہر function call اور trigger iii کے ذریعے فائر ہوتا ہے؛ کچھ بھی custom نہیں، instrument کرنے کے لیے کچھ نہیں۔
+
+
+
+
+ Workers صفحہ: ہر جڑا ہوا worker، بشمول agentmemory خود، PID، function count، runtime، اور last-seen کے ساتھ۔
+
+
+**پہلے سے انسٹال۔** کنسول pinned `iii` انجن (0.22+) کے ساتھ شپ ہوتا ہے؛ علیحدہ سے کچھ بھی انسٹال کرنے کی ضرورت نہیں۔ پہلا لانچ انجن کے ساتھ کنسول بائنری ڈاؤن لوڈ کرتا ہے۔
+
+**agentmemory کے ساتھ لانچ کریں:**
+
+```bash
+agentmemory console
+```
+
+یہ pinned انجن کے `iii console` کو agentmemory کے resolve کردہ پورٹس (REST، streams، bridge) کے خلاف چلاتا ہے اور اسے ویور سے ایک پورٹ اوپر سرو کرتا ہے، ڈیفالٹ کے طور پر `http://localhost:3114`۔ `--console-port N` کوئی اور پورٹ منتخب کرتا ہے؛ `--port` اور `--instance` اسی طرح agentmemory انسٹنس منتخب کرتے ہیں جیسے `stop` کے لیے کرتے ہیں؛ کوئی بھی دوسرا فلیگ آگے پاس ہو جاتا ہے، مثلاً experimental architecture-graph صفحے کے لیے `--enable-flow`۔
+
+وہی کام دستی طور پر، مفید جب `agentmemory` PATH پر نہ ہو:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**کنسول سے آپ کیا کر سکتے ہیں:**
+
+| صفحہ | استعمال |
+|------|-----------|
+| **Workers** | ہر جڑے ہوئے worker اور اس کی لائیو metrics دیکھیں، بشمول agentmemory worker خود۔ |
+| **Functions** | agentmemory کے کسی بھی فنکشن کو براہِ راست ایک JSON payload کے ساتھ invoke کریں؛ بغیر کسی کلائنٹ جوڑے `memory.recall`، `memory.consolidate`، `graph.query` کو ٹیسٹ کرنے کے لیے مفید۔ |
+| **Triggers** | HTTP، cron، event، اور state triggers کو دوبارہ چلائیں: consolidation cron کو دستی طور پر فائر کریں، کسی HTTP route کو retry کریں، ایک state تبدیلی emit کریں۔ |
+| **States** | sessions، memory slots، lifecycle timers، اور embeddings index پر مکمل CRUD والا KV browser؛ قدریں جگہ پر ترمیم کریں۔ |
+| **Streams** | memory writes، hook events، اور observation اپ ڈیٹس کے لیے لائیو WebSocket مانیٹر جیسے وہ iii streams سے گزرتے ہیں۔ |
+| **Queues** | Durable queue topics + dead-letter management۔ ناکام embedding / compression jobs کو دوبارہ چلائیں یا drop کریں۔ |
+| **Traces** | OpenTelemetry waterfall / flame / service-breakdown views۔ `trace_id` سے فلٹر کریں تاکہ عین دیکھا جا سکے کہ کسی ایک `memory.search` نے کون سے functions، DB calls، اور embedding requests پیدا کیے۔ |
+| **Logs** | trace/span IDs سے فلٹر اور correlated structured OTEL logs۔ |
+| **Config** | Runtime configuration: دیکھیں کہ آپ کا انجن عین کن workers، providers، اور ports کے ساتھ چل رہا ہے۔ |
+| **Flow** | (اختیاری، `--enable-flow`) ہر worker، trigger، اور stream کا انٹرایکٹو architecture گراف۔ |
+
+
+
+
+ Traces: ہر میموری operation کے لیے waterfall / flame / service breakdown۔
+
+
+**Traces پہلے سے آن ہیں:**
+
+`iii-config.yaml` `iii-observability` worker کو فعال حالت میں شپ کرتا ہے (`exporter: memory`، `sampling_ratio: 0.1`، metrics + logs)۔ کسی اضافی کنفیگ کی ضرورت نہیں؛ جس لمحے agentmemory شروع ہوتا ہے، ہر میموری operation ایک structured log بھیجتا ہے جسے کنسول پڑھ سکتا ہے، اور ان میں سے ہر دسواں (`sampling_ratio: 0.1`) ایک trace span بھی بھیجتا ہے۔
+
+اگر آپ اس کے بجائے Jaeger/Honeycomb/Grafana Tempo کو export کرنا چاہتے ہیں، تو `exporter: memory` کو `exporter: otlp` میں تبدیل کریں اور iii کی observability docs کے مطابق collector اینڈ پوائنٹ سیٹ کریں۔
+
+> **خبردار:** کنسول پر خود کوئی auth نافذ نہیں ہے؛ اسے `127.0.0.1` (ڈیفالٹ) سے bound رکھیں اور کبھی اسے عوامی طور پر ظاہر نہ کریں۔
+
+---
+
+
+
+agentmemory **پہلے سے ہی ایک چلتا ہوا [iii](https://iii.dev) instance ہے**۔ تین primitives (worker، function، trigger) رن ٹائم کو compose کرتے ہیں؛ KV state، streams، اور OTEL traces ان iii-state، iii-stream، اور iii-observability workers سے آتے ہیں جو iii کے ساتھ شپ ہوتے ہیں۔ آپ نے Postgres، Redis، Express، pm2، یا Prometheus انسٹال نہیں کیے، کیونکہ iii انہیں replace کرتا ہے۔
+
+اس کا مطلب ہے کہ صرف ایک اور کمانڈ agentmemory کو ایک مکمل نئی صلاحیت کے ساتھ وسعت دیتی ہے۔
+
+### agentmemory کو مزید workers کے ساتھ وسعت دیں
+
+وہ builtins جن کی agentmemory کو ضرورت ہے پہلے سے `iii-config.yaml` میں ہیں اور اس کے ساتھ boot ہوتے ہیں: `iii-state` (KV)، `iii-queue` (event subscribers کے لیے durable retries)، `iii-pubsub`، `iii-cron`، `iii-stream`، اور `iii-observability` (ہر function پر OTEL traces، metrics اور logs)۔ [iii worker registry](https://workers.iii.dev) سے کوئی اور چیز اسی انجن میں پلگ ہو جاتی ہے: `iii-config.yaml` کو `~/.agentmemory/iii-config.yaml` میں کاپی کریں (CLI bundled فائل کے بجائے اس فائل کو ترجیح دیتا ہے اور پھر بھی اس میں ports اور data paths render کرتا ہے)، entry شامل کریں، `~/.agentmemory/bin/iii update worker` سے ایک بار worker رن ٹائم انسٹال کریں، اور agentmemory دوبارہ شروع کریں۔
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | agentmemory کے ساتھ آپ کو کیا ملتا ہے |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | جب آپ in-memory KV ڈیفالٹس سے بڑھ جائیں تو SQL-backed state adapter |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` سے نکلا ہوا کوڈ آپ کے shell کے بجائے ایک throwaway VM کے اندر چلتا ہے |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory کے ساتھ اضافی MCP سرورز کھڑے کریں، وہی انجن شیئر کریں |
+
+انجن 0.22.x پر اوپر دیے گئے builtins کے لیے `iii-` prefix والے نام رکھیں؛ بغیر prefix کے `http`، `state`، `queue`، `pubsub` اور `cron` entries وہ standalone registry workers ہیں جن کی طرف agentmemory 0.23 migration کے ساتھ منتقل ہوتا ہے۔
+
+مکمل registry: [workers.iii.dev](https://workers.iii.dev)۔ وہاں موجود ہر worker انہی primitives کے ذریعے compose ہوتا ہے جو agentmemory استعمال کرتا ہے، اور جو agentmemory آپ کے پاس پہلے سے ہے وہ خود انہی میں سے ایک ہے۔
+
+### Engine کنفیگ اور bind ایڈریس
+
+`agentmemory start` انجن کنفیگ کو پہلی موجود فائل سے پڑھتا ہے: `AGENTMEMORY_III_CONFIG`، موجودہ ڈائرکٹری میں `./iii-config.yaml`، `~/.agentmemory/iii-config.yaml`، پھر bundled `iii-config.yaml`۔ ہر اسٹارٹ پر یہ اس فائل (data paths، ports، state backend) کو `~/.agentmemory/data/iii-config.runtime.yaml` میں render کرتا ہے اور انجن کو rendered کاپی کے ساتھ لانچ کرتا ہے، لہٰذا rendered فائل کے بجائے سورس فائل میں ترمیم کریں۔ سورس فائل کی `host:` قدریں جیسی لکھی گئی ہیں ویسی ہی رکھی جاتی ہیں۔
+
+bundled `iii-config.yaml` جانستہ طور پر `127.0.0.1` سے bind ہوتا ہے، اور یہ ڈیفالٹ container کے اندر بھی لاگو ہوتا ہے۔ container میں شروع کیا گیا CLI container کے loopback پر سنتا ہے، لہٰذا published ports کچھ بھی تک نہیں پہنچتے۔ containerized CLI کو published ports کے ذریعے سرو کرنے کے لیے، `AGENTMEMORY_III_CONFIG` کو ایسی کنفیگ پر سیٹ کریں جو `0.0.0.0` سے bind ہو۔ پیکیجڈ `iii-config.docker.yaml` ایک ایسی ہی مثال ہے: یہ `iii-http`، `iii-stream` اور انجن پورٹ کو `0.0.0.0` سے bind کرتی ہے اور state کو `/data` کے تحت محفوظ کرتی ہے، لہٰذا وہاں ایک قابلِ تحریر volume mount کریں۔ `AGENTMEMORY_SECRET` سیٹ رکھیں، اور صرف وہی ports publish کریں جن کی ضرورت ہے، `127.0.0.1` پر یا کسی قابلِ اعتماد پراکسی کے پیچھے۔
+
+اس repo کی `docker-compose.yml` CLI کی config lookup سے نہیں گزرتی: یہ `iii-config.docker.yaml` کو `/app/config.yaml` پر mount کرتی ہے، اور `iii-engine` container `--config /app/config.yaml` کے ساتھ شروع ہوتا ہے۔ ون-کلک [deploy templates](../deploy/) اپنے entrypoints میں اپنی `0.0.0.0` کنفیگ لکھتے ہیں۔
+
+### اسٹوریج backend: file (ڈیفالٹ) بمقابلہ redis
+
+`iii-state` اور `iii-stream` ڈیفالٹ کے طور پر iii-engine کے bundled file-based KV store پر چلتے ہیں: فی scope ایک JSON فائل، جو انجن process کی میموری میں رکھی جاتی ہے اور ٹائمر پر ڈسک پر دوبارہ لکھی جاتی ہے۔ یہ ایک single-user مقامی انسٹال کے لیے درست ڈیفالٹ ہے؛ کئی concurrent writers والا shared daemon اس کے بجائے Redis سے حقیقی فی-key writes حاصل کرتا ہے، فی operation ایک نیٹ ورک round trip کی قیمت پر (ہر `state::*` call اب بھی ایک Redis کنکشن پر serialize ہوتی ہے، لہٰذا یہ file store کے lock کو ایک socket سے بدلتا ہے، parallelism سے نہیں)۔
+
+دونوں workers کو iii-engine کے built-in `redis` adapter پر سوئچ کرنے کے لیے `AGENTMEMORY_STATE_BACKEND=redis` (نیز `AGENTMEMORY_REDIS_URL`) سیٹ کریں، جو ہر key کو ہر write پر پورے scope کو دوبارہ لکھنے کے بجائے ایک Redis hash field (`HSET`) کے طور پر محفوظ کرتا ہے:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` ڈیفالٹ کے طور پر `file` ہے؛ اسے سیٹ نہ کرنا آج کے رویے کو بدستور رکھتا ہے، اور کوئی غیر تسلیم شدہ قدر (`file` یا `redis` کے سوا کچھ بھی) خاموش fallback کے بجائے ایک startup error ہے۔ `/agentmemory/status` اور ویور کا Health صفحہ (State store row) رپورٹ کرتے ہیں کہ کون سا backend فعال ہے اور کیا یہ جواب دیتا ہے، کبھی URL نہیں۔
+
+**صرف سادہ `redis://`۔** pinned انجن (0.22.1) اپنا Redis کلائنٹ بغیر TLS سپورٹ کے بناتا ہے، لہٰذا ایک `rediss://` URL (زیادہ تر managed Redis پیشکشیں، جیسے Upstash، Redis Cloud، اور in-transit encryption کے ساتھ ElastiCache، ڈیفالٹ کے طور پر TLS-only ہیں) کنکٹ کرنے میں ناکام رہتا ہے۔ کنکشن غیر مُرمَّز (unencrypted) ہے، لہٰذا Redis پاس ورڈ اور ہر محفوظ شدہ میموری wire پر صاف متن میں گزرتی ہے: کسی مقامی Redis یا کسی قابلِ اعتماد private network پر موجود Redis کی طرف اشارہ کریں۔ کسی اور Redis کے لیے، agentmemory host پر ایک encrypted tunnel چلائیں (stunnel، SSH، یا ایک VPN)، تاکہ سادہ `redis://` hop اسی host پر رہے اور tunnel کا upstream کنکشن encrypted اور authenticated ہو۔ اگر Redis پاس ورڈ میں ایک single quote ہو، تو اسے percent-encode کریں (`%27`)؛ انجن parsing سے پہلے URL کو اپنی YAML کنفیگ میں expand کرتا ہے۔
+
+**فی `--instance` ایک Redis سرور۔** انجن کے Redis key prefixes (`state:`، `stream::`) fixed ہیں، لہٰذا ایک ہی database کی طرف اشارہ کرنے والے دو agentmemory instances (`--instance 1`، `--instance 2`، ...) ایک دوسرے کا ڈیٹا overwrite کر دیتے ہیں۔ ایک علیحدہ database index (`redis://localhost:6379/1`) محفوظ شدہ ڈیٹا کو الگ رکھتا ہے، لیکن انجن لائیو ویور events کو ایک Redis pub/sub چینل (`stream::events`) پر relay کرتا ہے، اور Redis pub/sub database index کو نظرانداز کرتا ہے، لہٰذا ہر instance کا ویور پھر بھی دوسرے کے لائیو events دکھائے گا۔ جب آپ ایک سے زیادہ چلائیں تو ہر instance کو اس کا اپنا Redis سرور (یا پورٹ) دیں۔
+
+**کیا ایک جیسا رہتا ہے، اور کیا فرق ہے۔** Redis پر agentmemory کی ہر خصوصیت کام کرتی ہے: sessions، observations، memories (remember، supersede، evolve، forget)، سرچ اور index buckets، lessons، گراف، audit log اور اس کے monthly scopes، export اور import، governance deletes، consolidation status، ویور snapshot اور اس کا لائیو stream، اور health monitor۔ انجن ہر scope کو ایک Redis hash (`HSET`/`HGET`/`HGETALL`) کے طور پر محفوظ کرتا ہے اور file store جیسے ہی state triggers فائر کرتا ہے۔ تین انجن فرق agentmemory کے اندر ہینڈل ہوتے ہیں:
+
+- Redis کسی scope کے records کو کسی fixed ترتیب میں واپس نہیں کرتا۔ agentmemory انہیں سب سے پرانے کو پہلے کی ترتیب میں sort کرتا ہے (record id میں creation time کے لحاظ سے، پھر اس کے timestamp سے) تاکہ lists، paging اور export chunks وہی ترتیب واپس لائیں جو file store پر ہوتی ہے۔
+- انجن Redis پر partial updates ایک Lua script میں لاگو کرتا ہے جو خالی arrays کو خالی objects میں بدل دیتا ہے۔ agentmemory خود یہ updates (پڑھنا، تبدیل کرنا، فی-key lock کے تحت لکھنا) Redis پر لاگو کرتا ہے، تاکہ `tags: []` جیسے fields arrays ہی رہیں۔
+- Legacy audit log چیک ڈسک پر file store کی فائل تلاش کرنے کے بجائے Redis سے پرانا scope پڑھتا ہے۔
+
+ایک فرق آپ کی توجہ مانگتا ہے: **Redis ریسٹارٹ ہونے کے بعد، انجن ویور کو لائیو events relay کرنا بند کر دیتا ہے** جب تک agentmemory ریسٹارٹ نہ ہو۔ ڈیٹا بدستور نارمل طریقے سے محفوظ اور پڑھا جاتا ہے۔ health monitor ہر 30 سیکنڈ بعد Redis کے ذریعے ایک test event بھیجتا ہے؛ جب یہ واپس نہیں آتا، `/agentmemory/status` اور ویور کا Health صفحہ "Live updates are not reaching the viewer" دکھاتے ہیں ساتھ حل کے: agentmemory ریسٹارٹ کریں۔ اگر Redis بند ہو، تو status رپورٹ "The state store is not answering" دکھاتی ہے اور یہ چیک کرنے کا طریقہ (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)۔ ایک بہت بڑے scope کی listing پوری hash کو ایک `HGETALL` میں پڑھتی ہے، وہی لاگت جو file store کو اسے میموری میں رکھنے کی ہوتی ہے۔
+
+**تجویز کردہ Redis سیٹنگز۔** ڈیفالٹ `save 3600 1 300 100 60 10000` snapshot پالیسی کسی crash پر منٹوں کی writes کھو سکتی ہے، جو file store کی 5 سیکنڈ flush window سے بھی بدتر ہے۔ جس بھی چیز کا کھونا آپ کو ناپسند ہو اس کے لیے `appendonly yes` سیٹ کریں۔ `maxmemory-policy noeviction` سیٹ کریں؛ `allkeys-lru` یا اس جیسی پالیسیاں Redis کی memory limit تک پہنچنے پر خاموشی سے میموریز گرا دیتی ہیں۔
+
+ایک نیٹیو (غیر-Docker) اسٹارٹ، اور ہر ون-کلک [deploy template](../deploy/) (وہ bundled `iii-config.yaml` کو overwrite کرتے ہیں اور نیٹیو طور پر شروع ہوتے ہیں)، `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` پڑھتے ہیں اور انہیں launch شدہ `iii-config` میں render کرتے ہیں۔ URL خود کبھی اس rendered فائل میں نہیں لکھا جاتا، صرف ایک `${AGENTMEMORY_REDIS_URL}` reference جسے انجن process بوٹ کے وقت اپنے ماحول سے expand کرتا ہے۔ صرف اس repo کا اپنا Docker Compose راستہ (`AGENTMEMORY_USE_DOCKER=1`، یا اسی طرح شروع کیے گئے انجن کو دوبارہ شروع کرنا) `iii-config.docker.yaml` کو read-only mount کرتا ہے اور کبھی render نہیں کرتا؛ `agentmemory start` اس combination کا پتہ چلنے پر خبردار کرتا ہے۔ اس فائل کو دستی طور پر بدلیں، [iii-state](https://workers.iii.dev/workers/iii-state) اور [iii-stream](https://workers.iii.dev/workers/iii-stream) worker docs میں دکھائی گئی وہی `name: redis` / `config: redis_url: ...` شکل کی پیروی کرتے ہوئے، اور `redis_url` کو container سے قابلِ رسائی کسی Redis کی طرف پوائنٹ کریں۔ `docker-compose.yml` انجن container میں `AGENTMEMORY_REDIS_URL` پاس کرتی ہے، لہٰذا `redis_url: '${AGENTMEMORY_REDIS_URL}'` وہاں کام کرتا ہے اور URL کو mounted فائل سے باہر رکھتا ہے۔
+
+Rendered کنفیگ URL کو `~/.agentmemory/data/iii-config.runtime.yaml` سے باہر رکھتی ہے، لیکن انجن کا اپنا configuration worker بوٹ ہونے کے بعد بھی *expanded* قدر کو `~/.agentmemory/config/iii-state.yaml` اور `iii-stream.yaml` میں persist کرتا ہے (iii-engine کی `${VAR}` expansion اس worker کے اپنا seed محفوظ کرنے سے پہلے ہوتی ہے، اور یہ resolved قدر محفوظ کرتا ہے، reference نہیں)۔ اس ڈائرکٹری کو credential رکھنے والی سمجھیں: کسی بھی shared host پر `chmod 700 ~/.agentmemory` کریں، اور database کی admin credentials کے بجائے agentmemory کی ضرورت کے مطابق scoped ایک Redis ACL صارف کو ترجیح دیں۔
+
+**Migration خودکار نہیں ہے۔** `AGENTMEMORY_STATE_BACKEND` بدلنا دونوں طرف ایک خالی store سے شروع ہوتا ہے؛ کوئی چیز موجودہ ڈیٹا کو file سے Redis یا واپس کاپی نہیں کرتی۔ جس backend کو آپ چھوڑ رہے ہیں اس سے export کریں اور جس کی طرف جا رہے ہیں اس میں import کریں۔ یہ bash اور zsh کے تحت یکساں طور پر چلتا ہے (بشمول `bash -u`)۔ `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` جیسا ایک array نہیں چلتا: zsh ہیڈر کو ایک malformed لفظ کے طور پر رکھتا ہے جہاں bash اسے دو میں تقسیم کرتا ہے، لہٰذا جب بھی `AGENTMEMORY_SECRET` سیٹ ہو تو دونوں درخواستیں 401 دیتی ہیں:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` کئی calls میں ایک بڑے corpus کو chunk کرنے کے لیے `?maxSessions=` اور `?offset=` بھی قبول کرتا ہے؛ import پر `strategy` یا تو `merge` (default-safe)، `replace`، یا `skip` ہے۔
+
+### iii کیا replace کرتا ہے
+
+| روایتی اسٹیک | 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 |
+| کسٹم plugin سسٹمز | `iii worker add ` |
+
+**225 سورس فائلز · ~54,000 لائنز کوڈ · 2,600+ ٹیسٹس · 312 فنکشنز · 66 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
+
+---
+
+
+
+### LLM Providers
+
+agentmemory آپ کے ماحول سے providers کو خودکار طور پر detect کرتا ہے۔ ایک provider LLM پر مبنی operations کو دستیاب بناتا ہے، لیکن صرف provider کنفیگریشن LLM کی تحریر کردہ observation compression کو فعال نہیں کرتی۔ اس راستے کو provider اور `AGENTMEMORY_AUTO_COMPRESS=true` دونوں درکار ہیں۔
+
+| Provider | کنفیگ | نوٹس |
+|----------|--------|-------|
+| **No-op (ڈیفالٹ)** | کسی کنفیگ کی ضرورت نہیں | LLM پر مبنی compress/summarize غیر فعال ہے۔ Synthetic compression اور BM25 recall بدستور کام کرتے ہیں۔ اگر آپ Claude-subscription fallback پر انحصار کرتے تھے تو نیچے `AGENTMEMORY_ALLOW_AGENT_SDK` دیکھیں۔ |
+| Anthropic API | `ANTHROPIC_API_KEY` | فی-ٹوکن بلنگ |
+| MiniMax | `MINIMAX_API_KEY` | Anthropic-compatible |
+| Gemini | `GEMINI_API_KEY` | embeddings بھی فعال کرتا ہے |
+| OpenRouter | `OPENROUTER_API_KEY` | کوئی بھی ماڈل |
+| OpenAI API | `OPENAI_API_KEY` | ڈیفالٹ `gpt-5.6-luna`، `OPENAI_MODEL` سے override کریں |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) یا `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | کوئی بھی OpenAI-API-compatible چیز۔ صفر لاگت، آپ کے اپنے hardware پر چلتا ہے۔ نیچے [مقامی ماڈلز](#local-models-ollama--lm-studio--vllm) دیکھیں۔ |
+| Claude subscription fallback | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | صرف opt-in۔ `@anthropic-ai/claude-agent-sdk` سیشنز spawn کرتا ہے؛ یہ پہلے لامحدود Stop-hook recursion کا سبب بنتا تھا، لہٰذا یہ اب ڈیفالٹ نہیں ہے۔ |
+
+### مقامی ماڈلز (Ollama / LM Studio / vLLM)
+
+agentmemory کسی بھی OpenAI-API-compatible سرور سے بات کرتا ہے، لہٰذا جو کچھ بھی `/v1/chat/completions` ایکسپوز کرتا ہے وہ بغیر کوڈ تبدیلیوں کے کام کرتا ہے۔ کوئی ادا شدہ keys نہیں، کوئی کلاؤڈ نہیں، کوئی rate limits نہیں؛ مکمل طور پر آپ کے اپنے hardware پر چلتا ہے۔
+
+**Ollama** (ڈیفالٹ پورٹ `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (ڈیفالٹ پورٹ `1234`):
+
+LM Studio کھولیں → Local Server tab → Start Server۔ picker سے کوئی بھی chat ماڈل منتخب کریں (Qwen 3، gpt-oss، DeepSeek R1، وغیرہ)۔
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: وہی شکل۔ `OPENAI_BASE_URL` کو اس URL کی طرف پوائنٹ کریں جو آپ کا سرور ایکسپوز کرتا ہے اور `OPENAI_MODEL` کو ایسے نام پر سیٹ کریں جسے آپ کا سرور قبول کرے۔
+
+**میموری کام کے لیے ماڈل انتخاب**: compression اور summarization مختصر tasks ہیں (<2K ٹوکنز اندر، <500 ٹوکنز باہر) جہاں ایک 7B instruct ماڈل کافی ہے۔ تجاویز:
+
+| ماڈل | سائز | کیوں |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | 16 GB مشین پر متوازن ڈیفالٹ؛ extraction اور tool-shaped text میں مضبوط |
+| `qwen3:4b` | ~2.6 GB | سب سے چھوٹا مناسب آپشن؛ compression کے لیے ٹھیک، graph extraction کے لیے کمزور |
+| `qwen3-coder:30b` | ~19 GB | 24-32 GB hardware پر code-shaped سیشنز کے لیے بہترین مقامی انتخاب (30B MoE، 3.3B active) |
+| `gpt-oss:20b` | ~14 GB | ایک مضبوط عمومی ماڈل جو 16 GB RAM میں فٹ ہو جاتا ہے |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning distill؛ سست لیکن صاف تر extractions |
+
+Qwen 3 ماڈلز ڈیفالٹ کے طور پر سوچتے (think) ہیں اور کسی بھی output سے پہلے پورا token بجٹ reasoning پر خرچ کر سکتے ہیں۔ graph-extraction prompts میں `/no_think` شامل کرنے کے لیے `AGENTMEMORY_LLM_NOTHINK=1` سیٹ کریں، اور اگر extractions خالی واپس آئیں تو `MAX_TOKENS` بڑھائیں (16384 کام کرتا ہے)۔
+
+Reasoning-class ماڈلز (`` بلاکس کے ساتھ `o1`-طرز) خالی `content` واپس کر سکتے ہیں جس کے ساتھ ایک `reasoning` field ہو جو آپ کا مقامی سرور ظاہر نہ کرے۔ اگر extractions خالی آئیں، تو پہلے کسی non-reasoning ماڈل پر سوئچ کریں۔ `OPENAI_REASONING_EFFORT=none` env ان Ollama Cloud thinking ماڈلز پر بھی thinking غیر فعال کر سکتا ہے جو OpenAI reasoning schema کی نقل کرتے ہیں۔
+
+مقامی embeddings ایک اختیاری dependency کے طور پر شپ ہوتی ہیں لیکن ڈیفالٹ کے طور پر فعال نہیں ہوتیں۔ `Xenova/all-MiniLM-L6-v2` (384-dim) اختیار کرنے کے لیے `EMBEDDING_PROVIDER=local` سیٹ کریں۔ پہلی embedding درخواست ماڈل ڈاؤن لوڈ کرتی ہے؛ اس کے بعد inference آن-ڈیوائس ہوتا ہے۔ اس سیٹنگ یا کسی ریموٹ embedding key کے بغیر، ویکٹرز غیر فعال رہتے ہیں، `mem::search` BM25 استعمال کرتا ہے، اور `smart-search` پھر بھی موجودہ graph matches شامل کر سکتا ہے۔
+
+### لاگت سے آگاہ ماڈل انتخاب
+
+جب provider اور `AGENTMEMORY_AUTO_COMPRESS=true` دونوں کے ساتھ LLM کی تحریر کردہ background compression فعال ہو، تو یہ ہر observation پر چلتی ہے، لہٰذا ماڈل کا انتخاب ماہانہ خرچ کو نمایاں طور پر بدل دیتا ہے۔ ریکارڈ شدہ workload ڈیٹا: 635 requests / 888K ٹوکنز / 35 گھنٹے فعال استعمال، 2026-05-23 کی قیمتوں پر تین OpenRouter ماڈلز کے خلاف چلایا گیا۔
+
+| ٹیئر | ماڈل | Input / 1M | Output / 1M | ریکارڈ شدہ 35h کی لاگت | نوٹس |
+|------|-------|------------|-------------|---------------------------|-------|
+| تجویز کردہ | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (تخمینی) | تازہ ترین DeepSeek؛ compression workloads کے لیے سب سے سستا تجویز کردہ انتخاب۔ |
+| تجویز کردہ | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet سے ~10× کم لاگت پر مستحکم compression + summarization کوالٹی۔ |
+| تجویز کردہ | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | اگر آپ کے سیشنز شدید code-shaped ہیں تو مضبوط code reasoning۔ |
+| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (تخمینی) | پیمائش شدہ Sonnet 4.6 رن جیسی فہرستی قیمت؛ 2026-08-31 تک $2/$10 intro قیمت۔ |
+| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (تخمینی) | فلیگ شپ ٹیئر؛ ہمیشہ-آن background کام کے لیے مہنگا۔ |
+| گریز کریں | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (تخمینی) | فلیگ شپ-کلاس ماڈل؛ compression کے لیے overspend۔ |
+
+پیمائش شدہ rows ریکارڈ شدہ رن سے آتے ہیں؛ (تخمینی) rows وہی token mix کو ہر ماڈل کی فہرستی قیمت کے مطابق scale کرتے ہیں۔
+
+جب `OPENROUTER_MODEL` کسی premium-tier پیٹرن سے میچ کرتا ہے تو agentmemory ایک runtime warning پرنٹ کرتا ہے۔ ایک بار باخبر انتخاب کرنے کے بعد خاموش کرنے کے لیے `AGENTMEMORY_SUPPRESS_COST_WARNING=1` سیٹ کریں۔
+
+میموری کام کے لیے کوالٹی بمقابلہ لاگت tradeoff: compression ایک summarization task ہے جس کے quality bars نسبتاً نرم ہیں (summary کو ایجنٹ دوبارہ پڑھتا ہے، صارف نہیں)۔ DeepSeek V4 Flash / V4 Pro / Qwen3-Coder اس task پر Sonnet کے rounding error کے اندر رہتے ہیں جبکہ 10-70× کم لاگت پر۔ Premium-tier ماڈلز ان کوئریز کے لیے بچائیں جو آپ خود براہِ راست پڑھتے ہیں۔
+
+ذرائع: [Claude Sonnet 5 کے لیے OpenRouter قیمت](https://openrouter.ai/anthropic/claude-sonnet-5)، [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731)، [DeepSeek قیمت نوٹس](https://api-docs.deepseek.com/quick_start/pricing/)۔
+
+### ملٹی-ایجنٹ میموری (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+ایسے multi-agent سیٹ اپس میں جہاں کئی roles ایک agentmemory سرور کا اشتراک کرتے ہیں (architect / developer / reviewer / researcher / support-agent)، `AGENT_ID` ہر write کو اس role کے ساتھ ٹیگ کرتا ہے جس نے وہ کیا۔ `AGENTMEMORY_AGENT_SCOPE` کنٹرول کرتا ہے کہ آیا recall اس ٹیگ کے لحاظ سے فلٹر کرے۔
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+| موڈ | Writes ٹیگ ہوں | Recall فلٹر ہو | کب استعمال کریں |
+|------|------------|---------------|-------------|
+| `shared` (ڈیفالٹ) | ہاں | نہیں | audit trail کے ساتھ cross-agent context۔ Architect دیکھ سکتا ہے کہ developer نے کیا نوٹ کیا، لیکن ہر row ریکارڈ کرتی ہے کہ کس نے کہا۔ |
+| `isolated` | ہاں | ہاں | سخت علیحدگی۔ Architect کبھی developer کی observations / memories / sessions نہیں دیکھتا۔ |
+
+جب `AGENT_ID` سیٹ ہو تو کیا ٹیگ ہوتا ہے: `Session.agentId`، `RawObservation.agentId`، `CompressedObservation.agentId`، `Memory.agentId`۔ role `api::session::start` → `mem::observe` → `mem::compress` → KV سے گزرتا ہے۔
+
+isolated موڈ میں کیا فلٹر ہوتا ہے: `mem::smart-search`، `/agentmemory/memories`، `/agentmemory/observations`، `/agentmemory/sessions`۔ ہر endpoint فی-request override کرنے کے لیے `?agentId=` قبول کرتا ہے، اور env scope سے مکمل طور پر opt out کرنے کے لیے `?agentId=*`۔ `/memories` ان pre-AGENT_ID میموریز کو ظاہر کرنے کے لیے `?includeOrphans=true` بھی قبول کرتا ہے جن کا `agentId` undefined ہے۔
+
+SDK / REST سطح پر فی-call override: ہر mutating endpoint (`/session/start`، `/remember`) request body میں ایک `agentId` field قبول کرتا ہے جو env پر فوقیت رکھتا ہے۔ ان runtimes کے لیے مفید جو کئی roles کو ایک سرور process کے ذریعے روٹ کرتے ہیں۔ MCP کا `memory_save` ٹول وہی `agentId` field ظاہر کرتا ہے، standalone stdio سرور `agentId` اور `project` دونوں فارورڈ کرتا ہے، اور محفوظ شدہ میموریز `agentId` کو سرچ index میں لے جاتی ہیں، لہٰذا agent-scoped سرچ observations کے ساتھ ساتھ memories کو بھی کَوَر کرتی ہے۔
+
+جب `AGENT_ID` سیٹ نہ ہو، میموری unscoped رہتی ہے (legacy رویہ، کوئی ٹیگز نہیں، کوئی فلٹرز نہیں)۔
+
+### پورٹس
+
+agentmemory + iii-engine ڈیفالٹ کے طور پر چار پورٹس سے bind ہوتے ہیں۔ اگر ریسٹارٹ `port in use` کے ساتھ ناکام ہو، تو یہ ٹیبل بتاتا ہے کہ کون سا process تلاش کرنا ہے۔
+
+| پورٹ | Process | مقصد | Env override |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | اندرونی streams worker (agentmemory + ویور کے ذریعے استعمال ہوتا ہے) | `III_STREAM_PORT` (ترجیحی) یا legacy `III_STREAMS_PORT` |
+| `3113` | agentmemory | ریئل-ٹائم ویور (`http://localhost:3113`) | رپورٹ شدہ URL کے لیے `III_VIEWER_PORT` یا `AGENTMEMORY_VIEWER_URL` |
+| `49134` | iii-engine | WebSocket؛ workers یہاں رجسٹر ہوتے ہیں، OTel telemetry اسی سے گزرتی ہے | `III_ENGINE_PORT` یا `III_ENGINE_URL` |
+
+`--port ` REST anchor کو تبدیل کرتا ہے اور صرف وہاں streams `N+1`، ویور `N+2`، اور انجن WebSocket `N+46023` نکالتا ہے جہاں اوپر دیا گیا متعلقہ واضح پورٹ یا URL سیٹ نہ ہو۔ یہ کوئی isolated lifecycle namespace نہیں بناتا۔ دوسرے daemon کے لیے `--instance 1` استعمال کریں؛ یہ anchor 3211 استعمال کرتا ہے، ڈیفالٹ کے طور پر `3211/3212/3213/49234`، اور ایک علیحدہ `instance-1` data اور lifecycle ڈائرکٹری حاصل کرتا ہے۔ Instances 1 سے 50 تک وہی پیٹرن فالو کرتے ہیں۔
+
+pinned انجن `--no-update-check` کے ساتھ شروع ہوتا ہے (بوٹ پر GitHub کے خلاف کوئی update یا security-advisory lookups نہیں) اور iii کی anonymous usage telemetry بند کے ساتھ: agentmemory اس انجن کے لیے جسے وہ spawn کرتا ہے `III_TELEMETRY_ENABLED=false` سیٹ کرتا ہے جب تک آپ خود یہ variable export نہ کریں، اور bundled compose فائل بھی وہی کرتی ہے۔
+
+جب کسی crashed رن کے بعد ports bound رہ جائیں تو stale-process cleanup:
+
+```bash
+# macOS / Linux — find whatever is on each port and kill it
+lsof -i :3111,3112,3113,49134
+pkill -f agentmemory || true
+pkill -f 'iii ' || true
+
+# Windows
+netstat -ano | findstr ":3111 :3112 :3113 :49134"
+taskkill /F /PID
+```
+
+`agentmemory stop` graceful نیٹیو shutdown پر worker اور انجن pidfile دونوں کو صاف طریقے سے reap کرتا ہے۔ Docker موڈ میں یہ نیٹیو worker کو flush کرتا ہے، عین validated انجن container کو روکتا ہے، اور lossless ریسٹارٹ کے لیے container اور اس کے `/data` mount دونوں کو محفوظ رکھتا ہے؛ اگلا اسٹارٹ اسی container کی توثیق کرتا ہے اور اسے دوبارہ شروع کرتا ہے۔ Docker-backed uninstall کو `agentmemory remove --keep-data` درکار ہے: یہ validated container، اس کے data mount، اور انہیں بحال کرنے کے لیے درکار lifecycle record کو محفوظ رکھتے ہوئے shared agentmemory-managed فائلیں ہٹاتا ہے۔ Destructive Docker ڈیٹا ڈیلیشن جانستہ طور پر backup کے بعد آپریٹر پر چھوڑا جاتا ہے۔ CLI Docker یا VM port holders (Docker backend، vpnkit، colima) کو نیٹیو انجن کے طور پر اپنانے یا signal کرنے سے بھی انکار کرتا ہے جب تک `--force` پاس نہ ہو۔ اوپر دیا گیا دستی cleanup صرف اس post-crash صورت کے لیے ہے جہاں کوئی pidfile پیچھے نہ رہا ہو۔
+
+### کنفیگ فائل
+
+ہر shell میں variables export کرنے کے بجائے agentmemory رن ٹائم کنفیگریشن `~/.agentmemory/.env` میں رکھیں۔ اگر ویور `export ANTHROPIC_API_KEY=...` جیسا کوئی سیٹ اپ اشارہ دکھاتا ہے، تو اسے `export` prefix کے بغیر `ANTHROPIC_API_KEY=...` کے طور پر اس فائل میں کاپی کریں، پھر agentmemory ریسٹارٹ کریں۔
+
+Process ماحولیاتی variables بدستور کام کرتے ہیں اور فائل کی قدروں پر فوقیت رکھتے ہیں۔
+
+Windows پر، وہی فائل `%USERPROFILE%\.agentmemory\.env` پر موجود ہے:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+API key کے بجائے Claude Code Pro/Max subscription کے ساتھ ٹیسٹ کرنے کے لیے، واضح طور پر opt in کریں:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+LLM کی تحریر کردہ observation compression کو دونوں سطریں درکار ہیں: کسی LLM provider تک رسائی (بشمول یہ واضح subscription fallback) اور `AGENTMEMORY_AUTO_COMPRESS=true`۔ صرف ایک provider ڈیفالٹ synthetic compression راستے کو برقرار رکھتا ہے۔
+
+Consolidation (graph nodes، lessons، crystals) جب بھی کوئی LLM provider کنفیگر ہو تو ڈیفالٹ کے طور پر آن ہوتا ہے۔ اگر آپ LLM-free آپریشن چاہتے ہیں تو `CONSOLIDATION_ENABLED=false` کے ساتھ واضح طور پر opt out کریں۔ Graph extraction ایک علیحدہ flag ہے:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### ماحولیاتی 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://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+پورٹ `3111` پر 138 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer ` درکار ہے، اور mesh sync اینڈ پوائنٹس کو دونوں peers پر واضح طور پر سیٹ کیا گیا `AGENTMEMORY_SECRET` درکار ہے۔
+
+**Authentication ڈیفالٹ کے طور پر آن ہے۔** جب `AGENTMEMORY_SECRET` سیٹ نہ ہو (shell میں یا `~/.agentmemory/.env` میں)، سرور پہلے اسٹارٹ پر ایک random secret تیار کرتا ہے اور اسے `0600` موڈ کے ساتھ `~/.agentmemory/secret` میں محفوظ کرتا ہے۔ ہر bundled کلائنٹ جب کسی مقامی سرور سے بات کرتا ہے تو اسے وہاں سے پڑھتا ہے: CLI، ویور، `plugin/scripts` کے تحت ہکس، MCP سرور اور `@agentmemory/mcp` shim، `agentmemory connect` کی لکھی گئی configs، اور bundled OpenCode، Pi، OpenClaw، Hermes اور filesystem-watcher integrations۔ محفوظ شدہ secret صرف loopback URLs (`localhost`، `127.0.0.0/8`، `::1`) کو بھیجا جاتا ہے۔ ایک واضح `AGENTMEMORY_SECRET` ہمیشہ جیتتا ہے، اور ریموٹ کلائنٹس کو بھی اسے سیٹ کرنا ضروری ہے۔ Docker اور `deploy/` entrypoints پہلے سے اپنا secret تیار اور export کرتے ہیں۔ API کو دستی طور پر کال کرنے کے لیے:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Writes کے لیے request قواعد۔** REST API اور ویور کو بھیجی جانے والی `POST`، `PUT`، `PATCH` اور `DELETE` درخواستوں کو جب بھی ان کے ساتھ body ہو تو `Content-Type: application/json` بھیجنا ضروری ہے (ایک `charset` پیرامیٹر ٹھیک ہے)، اور ایک `Origin` ہیڈر، جب موجود ہو، کو کنفیگر کردہ REST یا viewer پورٹ کے لیے loopback origin ہونا چاہیے یا `VIEWER_ALLOWED_ORIGINS` میں درج ہونا چاہیے (comma-separated، مثلاً `https://memory.example.com`)۔ وہ کلائنٹس جو کوئی `Origin` ہیڈر نہیں بھیجتے (CLI، hooks، MCP، curl، server-to-server) متاثر نہیں ہوتے۔ ویور اپنا origin بھی قبول کرتا ہے۔
+
+**فائل Paths۔** وہ اینڈ پوائنٹس جو فائلیں پڑھتے یا لکھتے ہیں (`/compress-file`، `/replay/import-jsonl`، `/graph/import-graphify`) صرف `~/.agentmemory`، instance data ڈائرکٹری، یا `AGENTMEMORY_IMPORT_ROOT` میں درج کسی ڈائرکٹری کے تحت paths قبول کرتے ہیں (کئی کو `:` سے، یا Windows پر `;` سے الگ کریں)۔ `/replay/import-jsonl` اپنا ڈیفالٹ `~/.claude/projects` بھی قبول کرتا ہے۔ `/obsidian/export` `AGENTMEMORY_EXPORT_ROOT` کے اندر اور `/migrate` `~/.agentmemory` کے اندر رہتا ہے۔ Symlinks ہر چیک سے پہلے resolve کیے جاتے ہیں۔
+
+**Secret Scrubbing۔** API keys، bearer tokens، PEM private key بلاکس اور URLs میں embedded credentials (`scheme://user:password@host`) ہر write راستے پر متن محفوظ ہونے سے پہلے redact کر دیے جاتے ہیں: observations، remember، evolve، slots، lessons، actions، sketches، signals، checkpoints، imports، jsonl replay، mesh sync، team shares، compression اور summary output، crystals اور graph nodes۔
+
+
+اہم اینڈ پوائنٹس
+
+| Method | Path | تفصیل |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (ہمیشہ عوامی) |
+| `GET` | `/agentmemory/status` | کیا غلط ہے اور اسے کیسے ٹھیک کریں (browsers کے لیے HTML، ورنہ JSON) |
+| `GET` | `/agentmemory/viewer/snapshot` | ویور جو کچھ دکھاتا ہے، ایک ہی response میں |
+| `POST` | `/agentmemory/session/start` | سیشن شروع کریں + context حاصل کریں |
+| `POST` | `/agentmemory/session/end` | سیشن ختم کریں |
+| `POST` | `/agentmemory/observe` | observation کیپچر کریں (نیچے capture delivery دیکھیں) |
+| `GET` | `/agentmemory/capture` | Capture inbox، dead letters اور offline spool |
+| `POST` | `/agentmemory/capture/retry` | Dead-letter کیپچرز دوبارہ کریں |
+| `POST` | `/agentmemory/capture/drain` | مقامی offline spool ابھی بھیجیں |
+| `POST` | `/agentmemory/smart-search` | Hybrid سرچ |
+| `POST` | `/agentmemory/context` | Context تیار کریں |
+| `POST` | `/agentmemory/remember` | طویل مدتی میموری میں محفوظ کریں |
+| `POST` | `/agentmemory/forget` | Observations ڈیلیٹ کریں |
+| `POST` | `/agentmemory/enrich` | File context + memories + bugs |
+| `GET` | `/agentmemory/profile` | Project profile |
+| `GET` | `/agentmemory/export` | تمام ڈیٹا export کریں |
+| `POST` | `/agentmemory/import` | JSON سے import کریں |
+| `POST` | `/agentmemory/graph/query` | نالج گراف کوئری |
+| `POST` | `/agentmemory/graph/compact` | زائد الحجم graph provenance کو trim کریں |
+| `POST` | `/agentmemory/team/share` | ٹیم کے ساتھ شیئر کریں |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+مکمل اینڈ پوائنٹ فہرست: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**کیپچر ڈیلیوری۔** Hooks ہر observation کو ایک بار `eventId` کے ساتھ `POST /agentmemory/observe` پر بھیجتے ہیں۔ جب payload میں ایک موجود ہو (مثلاً Claude Code کا `tool_use_id`) تو یہ کال کے لیے host کا اپنا id ہوتا ہے، ورنہ سیشن، hook type، tool نام، input، output اور host timestamp کا ایک hash۔ سرور event کو state store میں ایک capture inbox میں لکھتا ہے، observation محفوظ کرتا ہے، پھر inbox entry ہٹا دیتا ہے۔ status code بتاتا ہے کیا ہوا:
+
+| Status | `status` field | معنی |
+|---|---|---|
+| `201` | `accepted` | محفوظ ہو گیا۔ `observationId` نئی observation ہے۔ |
+| `202` | `accepted` (`state: "retrying"`) | Accepted، لیکن محفوظ کرنا ناکام ہوا۔ سرور اسے دوبارہ کوشش کرتا ہے، ریسٹارٹ کے بعد بھی۔ |
+| `200` | `duplicate` | یہ `eventId` پہلے ہی قبول کیا جا چکا تھا۔ `observationId` موجودہ observation ہے؛ کچھ نیا محفوظ نہیں ہوتا۔ |
+| `400` / `422` | `rejected` | غلط payload، یا محفوظ کرنا مستقل طور پر ناکام ہوا (event ایک dead letter کے طور پر رکھا جاتا ہے)۔ |
+| `503` | `rejected` (`retryable: true`) | Inbox بھرا ہوا ہے (`AGENTMEMORY_CAPTURE_INBOX_MAX`)۔ Hooks event کو spool کرتے ہیں اور بعد میں بھیجتے ہیں۔ |
+
+ناکام events کو ہر `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 ثانیے) بعد doubling backoff کے ساتھ دوبارہ کوشش کی جاتی ہے، `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5) تک۔ وہ events جو بدستور ناکام رہیں inbox میں dead letters کے طور پر رہتے ہیں، `/agentmemory/status` اور ویور کے Health صفحے پر درج ہوتے ہیں، اور `POST /agentmemory/capture/retry` (`{"eventId": "..."}` یا `{"all": true}`) سے دوبارہ کوشش کی جا سکتی ہے۔ قبول شدہ event ids کو `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 گھنٹے، زیادہ سے زیادہ `AGENTMEMORY_CAPTURE_EVENTS_MAX` ids) تک یاد رکھا جاتا ہے، لہٰذا کوئی hook جو timeout یا ریسٹارٹ کے بعد دوبارہ چلایا جائے وہ ایک بار محفوظ ہوتا ہے، جبکہ اپنے اپنے host ids والی دو علیحدہ tool calls دو بار محفوظ ہوتی ہیں چاہے ان کا content یکساں ہو۔ جب کوئی observation ڈیلیٹ ہوتی ہے (forget، session delete، eviction، auto-forget یا کوئی import جو store کو replace کرے)، تو observation ہٹائے جانے سے پہلے اس کا event deleted کے طور پر نشان زد کیا جاتا ہے، لہٰذا اسی window کے اندر اس event کا کوئی replay duplicate کے طور پر جواب دیا جاتا ہے اور کچھ محفوظ نہیں ہوتا۔ state store ہر 2 سیکنڈ بعد ڈسک پر لکھتا ہے، لہٰذا کوئی جواب دیا گیا event ابھی بھی ایک لمحے کے لیے صرف میموری میں ہو سکتا ہے۔ اسے کَوَر کرنے کے لیے، ہر `2xx` جواب سرور کا `bootId` (ہر اسٹارٹ پر نیا)، `acceptedAt` اور `durableAfterMs` بھی لے جاتا ہے (save interval نیز file store پر 1.5 سیکنڈ، redis پر 1.5 سیکنڈ، جہاں persistence آپریٹر کی سیٹنگ ہے)۔ Hooks event کو مقامی spool میں اس وقت تک رکھتے ہیں جب تک وہ window گزر نہ جائے اور اسے کسی بعد کی call پر بغیر کسی اور request کے ڈیلیٹ کر دیتے ہیں۔ اگر اس دوران `bootId` بدل گیا ہو، تو سرور ریسٹارٹ ہوا تھا، لہٰذا hook وہی `eventId` کے ساتھ event دوبارہ بھیجتا ہے؛ جو event ڈسک تک پہنچ چکا تھا وہ دو بار محفوظ نہیں ہوتا۔ سرور خود بھی ایسے events کو اسٹارٹ پر اور ہر retry interval پر بھیجتا ہے، لہٰذا ریسٹارٹ کے بعد بھی اگر کوئی hook نہ چلے تو کچھ نہیں کھوتا۔ پرانے hooks اضافی fields کو نظرانداز کرتے ہیں، اور کسی پرانے سرور کے خلاف نئے hooks `2xx` پر event کو ویسے ہی discard کر دیتے ہیں جیسے پہلے کرتے تھے۔
+
+جب سرور بند ہو، وقت پر جواب نہ دے یا 5xx واپس کرے، تو hook observation کو ایک مقامی spool فائل میں شامل کرتا ہے، `/capture-spool/-.jsonl` (فولڈر کو `AGENTMEMORY_CAPTURE_SPOOL_DIR` سے override کریں)۔ فائل آپ کے صارف کے لیے نجی ہے (mode 600)، secrets اسی طرح redact ہوتے ہیں جیسے سرور انہیں redact کرتا ہے، یہ زیادہ سے زیادہ `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) رکھتی ہے اور `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168) سے پرانے entries گرا دیتی ہے۔ جب یہ بھر جائے، نئے entries گرا دیے جاتے ہیں اور ان کو شمار کیا جاتا ہے، اور `/agentmemory/status` اس کی رپورٹ کرتا ہے۔ hook پھر بھی اپنی وقت کی حد کے اندر 0 کے ساتھ exit ہوتا ہے اور جب سرور صحت مند ہو تو کوئی اضافی request نہیں بڑھاتا۔ spool اگلے اسٹارٹ پر اور پہلے hook کے ذریعے جو سرور تک دوبارہ پہنچے، ایک background process میں بھیجا جاتا ہے تاکہ ایجنٹ انتظار نہ کرے۔ Event ids اسے محفوظ بناتے ہیں: کوئی observation جو timeout سے پہلے پہنچ چکی ہو وہ دو بار محفوظ نہیں ہوتی۔ `npx @agentmemory/agentmemory capture` spool اور سرور inbox دکھاتا ہے، `--drain` ابھی spool بھیجتا ہے، اور `GET /agentmemory/capture` وہی JSON کے طور پر واپس کرتا ہے۔ spool بند کرنے کے لیے `AGENTMEMORY_CAPTURE_SPOOL=false` سیٹ کریں۔
+
+**Graph Provenance کو Compact کرنا۔** ہر نالج گراف node اور edge ان 32 تازہ ترین observations کے ids رکھتی ہے جہاں سے وہ آئی۔ اس cap سے پہلے لکھے گئے stores فی hot node ہزاروں ids رکھ سکتے ہیں، جو graph سرچ اور ویور کو سست کر دیتا ہے یا worker کو گرا دیتا ہے۔ agentmemory اسے خود ٹھیک کرتا ہے: اپ گریڈ کے بعد پہلے اسٹارٹ پر یہ ہر node، edge، سپرسیڈ شدہ edge (temporal graph ہسٹری) اور cached snapshot کو پسِ منظر میں cap تک trim کرتا ہے، چھوٹے slices میں ان کے درمیان وقفے کے ساتھ، تاکہ سرچ، کیپچر اور ویور کام کرتے رہیں۔ یہ اپنی پیش رفت محفوظ کرتا ہے، ریسٹارٹ کے بعد جاری رہتا ہے اور ختم ہونے کے بعد دوبارہ کبھی نہیں چلتا۔ `/agentmemory/status` اور ویور کا Health صفحہ اسے pending، running (موجودہ scope اور position کے ساتھ)، done یا failed کے طور پر دکھاتے ہیں۔ اسے بند کرنے کے لیے `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` سیٹ کریں۔
+
+اسے دستی طور پر چلانے کے لیے، `POST /agentmemory/graph/compact` کال کریں۔ یہ ہر node اور edge کی فہرست بنانے کے بجائے name اور edge-key indexes پر چلتا ہے، اور دوبارہ چلانا محفوظ ہے۔ جب یہ ids trim کرتا ہے تو ایک `graph_compact` audit entry لکھتا ہے۔
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+کسی بڑے store پر، یا جب call 504 واپس کرے، تو اسے slices میں چلائیں۔ `scope` (`nodes`، `edges` یا `history`)، `offset` اور `limit` بھیجیں، پھر واپس آئے گئے `nextOffset` کے ساتھ دوبارہ کال کریں جب تک یہ `null` نہ ہو جائے۔ یہ `nodes`، `edges` اور `history` کے لیے کریں، اور ایک `{"scope":"snapshot"}` call کے ساتھ ختم کریں، کیونکہ sliced run cached snapshot کو نہیں چھیڑتا۔
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**ضروریات:** Node.js >= 20 npm/npx کے ساتھ؛ [iii-engine](https://iii.dev/docs) v0.22.1 یا Docker۔ خودکار macOS/Linux انجن انسٹال کو `curl`، ایک POSIX `sh`، اور `tar` بھی درکار ہیں؛ نیٹیو Windows دستی pinned `iii.exe`، WSL2، یا Docker Desktop استعمال کرتا ہے۔
+
+
+
+[Apache-2.0](../LICENSE)
+
+
diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.md
new file mode 100644
index 0000000000..ce5d3d0017
--- /dev/null
+++ b/READMEs/README.vi-VN.md
@@ -0,0 +1,1872 @@
+
+
+
+
+
+
+ Coding agent của bạn ghi nhớ mọi thứ. Không còn phải giải thích lại từ đầu.
+ Được xây dựng trên iii engine
+
+ Bộ nhớ bền vững cho Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode và bất kỳ MCP client nào.
+
+ Gist này mở rộng mẫu LLM Wiki của Karpathy với confidence scoring, lifecycle, knowledge graph và tìm kiếm hybrid: agentmemory chính là phần triển khai đó.
+
+
+---
+
+## Cài đặt
+
+Yêu cầu:
+
+- Node.js 20 hoặc mới hơn kèm npm và npx (`node -v`, `npm -v`, và `npx -v`).
+- Cài đặt iii-engine tự động trên macOS/Linux cũng cần `curl`, một `sh` chuẩn POSIX, và `tar`. Các image tối giản như `node:20-slim` có thể không có sẵn những công cụ này.
+- Windows gốc (native) yêu cầu cài đặt thủ công `iii.exe` của iii-engine v0.22.1 đã được pin. WSL2 hoặc Docker Desktop là các lựa chọn khác được hỗ trợ.
+
+Lệnh cài mới chuẩn (canonical):
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Lần chạy đầu tiên là một quy trình cài đặt tương tác: chọn các agent cần kết nối (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), chọn một LLM provider hoặc tiếp tục ở chế độ keyless, rồi nó khởi tạo config, chạy memory server cùng iii engine đã pin, và đề nghị cài đặt toàn cục để từ đó lệnh `agentmemory` trần dùng được ở mọi nơi. `-y` để xác nhận prompt gói của npx và `@latest` giúp tránh một bản release cũ bị cache. Một provider giúp các tính năng LLM khả dụng, nhưng việc nén (compression) observation do LLM viết chỉ bắt đầu khi `AGENTMEMORY_AUTO_COMPRESS=true` cũng được thiết lập.
+
+Chế độ keyless tắt vector embedding. `memory_recall` (đường dẫn `mem::search`) dùng BM25, trong khi `memory_smart_search` cũng có thể kết hợp (fuse) các kết quả khớp từ graph cấu trúc khi dữ liệu graph đã tồn tại. Để có recall ngữ nghĩa (semantic) miễn phí ngay trên máy (on-device), đặt `EMBEDDING_PROVIDER=local` trong `~/.agentmemory/.env` và khởi động lại. Request embedding đầu tiên sẽ tải `Xenova/all-MiniLM-L6-v2`; sau lần tải model đầu tiên đó, việc suy luận chạy hoàn toàn cục bộ.
+
+Runtime cục bộ dùng bốn port: `3111` cho REST/MCP HTTP, `3112` cho iii streams, `3113` cho viewer, và `49134` cho WebSocket của iii worker. Trạng thái (state) bền vững của iii nằm tại `~/Library/Application Support/agentmemory` trên macOS, `$XDG_DATA_HOME/agentmemory` hoặc `~/.local/share/agentmemory` trên Linux, và `%APPDATA%\agentmemory` trên Windows. Dùng `--data-dir ` hoặc `AGENTMEMORY_DATA_DIR` để ghi đè, và dùng lại đúng giá trị đó ở mỗi lần khởi động lại. Để tương thích ngược, một `./data/state_store.db` hoặc `./data/iii-config.yaml` đã tồn tại sẽ được ưu tiên hơn giá trị mặc định của platform cho instance 0; một flag hoặc biến môi trường chỉ định rõ vẫn luôn thắng.
+
+Sau đó hãy xác nhận recall hoạt động và trang bị skill cho agent của bạn:
+
+```bash
+npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
+npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
+```
+
+Các truy vấn theo từ khóa sẽ cho kết quả đúng ở chế độ keyless mặc định thông qua BM25. Câu truy vấn `database performance optimization` trong demo mang tính ngữ nghĩa (semantic) có chủ đích và có thể trả về rỗng cho tới khi một embedding provider được cấu hình.
+
+Muốn để một coding agent tự làm hết mọi việc? Hãy đưa cho nó một chỉ dẫn duy nhất:
+
+> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
+
+Kết nối thêm agent bất kỳ lúc nào với `agentmemory connect ` — 20 adapter được liệt kê tại [Hoạt động với mọi agent](#works-with-every-agent). Tham chiếu lệnh đầy đủ tại [Bắt đầu nhanh](#quick-start).
+
+
+Windows
+
+Đường đi nhanh nhất là WSL2. Thiết lập engine trên Windows gốc yêu cầu tải file ZIP v0.22.1 đã pin và trích xuất `iii.exe` thủ công; CLI không tự động trích xuất file này. Docker Desktop cũng được hỗ trợ. Xem [ghi chú Windows](#windows) để biết các bước chi tiết.
+
+
+
+
+Cài đặt toàn cục / EACCES
+
+```bash
+npm install -g @agentmemory/agentmemory@latest
+```
+
+Lệnh npx ở trên vẫn là cách cài mới chuẩn và tránh được các vấn đề về quyền global-prefix.
+
+
+
+
+npx trả về phiên bản cũ
+
+npx cache theo từng phiên bản. Buộc dùng bản mới nhất với `npx -y @agentmemory/agentmemory@latest`, hoặc xóa cache một lần với `rm -rf ~/.npm/_npx` (macOS/Linux; trên Windows, xóa `%LOCALAPPDATA%\npm-cache\_npx`).
+
+
+
+
+Đã chạy sẵn iii engine riêng của bạn
+
+agentmemory pin phiên bản iii-engine v0.22.1 và sẽ không gắn (attach) vào một phiên bản khác (worker không thể nói đúng protocol của một engine khác). Hãy dừng engine khác đó, sau đó chạy `npx -y @agentmemory/agentmemory@latest`. Nó sẽ cài đặt và chạy bản v0.22.1 đã pin trong `~/.agentmemory/bin`, không đụng đến `iii` riêng của bạn.
+
+
+
+---
+
+
+
+agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, hoặc REST API. Tất cả agent đều dùng chung một memory server.
+
+
+ Hoạt động với bất kỳ agent nào nói MCP hoặc HTTP. Một server duy nhất, bộ nhớ được chia sẻ cho tất cả.
+
+
+---
+
+Bạn giải thích lại cùng một kiến trúc ở mỗi session. Bạn phát hiện lại đúng những bug cũ. Bạn dạy lại đúng những sở thích cũ. Bộ nhớ tích hợp sẵn (CLAUDE.md, .cursorrules) bị giới hạn ở 200 dòng và nhanh trở nên lỗi thời. agentmemory khắc phục điều này. Nó âm thầm ghi lại những gì agent của bạn làm, nén lại thành bộ nhớ có thể tìm kiếm, và tiêm (inject) đúng context vào khi session kế tiếp bắt đầu. Một lệnh duy nhất. Hoạt động trên nhiều agent.
+
+**Điều gì thay đổi:** Ở session 1 bạn thiết lập JWT auth. Ở session 2 bạn yêu cầu thêm rate limiting. Agent đã biết sẵn rằng auth của bạn dùng middleware jose trong `src/middleware/auth.ts`, test của bạn phủ (cover) việc validate token, và bạn chọn jose thay vì jsonwebtoken để tương thích với Edge, không cần giải thích lại, không cần copy-paste lại.
+
+```bash
+npx -y @agentmemory/agentmemory@latest
+```
+
+Theo mặc định, agentmemory lưu trạng thái của iii-engine bên ngoài repository mà bạn khởi chạy nó từ đó: `~/Library/Application Support/agentmemory` trên macOS, `$XDG_DATA_HOME/agentmemory` hoặc `~/.local/share/agentmemory` trên Linux, và `%APPDATA%\agentmemory` trên Windows. Một `./data/state_store.db` hoặc `./data/iii-config.yaml` kiểu cũ (legacy) đã tồn tại sẽ được dùng lại cho instance 0 trước khi áp dụng giá trị mặc định của platform đó. Để chọn vị trí một cách rõ ràng, truyền `--data-dir ` hoặc đặt `AGENTMEMORY_DATA_DIR`; cả hai cách chỉ định rõ này đều được ưu tiên hơn việc dò tìm kiểu legacy:
+
+```bash
+npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
+AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+```
+
+Các lần khởi chạy native và Docker đều dùng chung thư mục host đã được resolve này; Docker bind-mount nó vào `/data`. `--instance 1` sẽ gắn thêm `instance-1` vào thư mục đã resolve và chọn bộ bốn port mặc định riêng `3211/3212/3213/49234`.
+
+Ghi chú phát hành mới nhất: [CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+
+
+
+
+
+
+### Độ chính xác Retrieval
+
+**coding-agent-life-v1** (corpus nội bộ, có thể tái lập trong sandbox)
+
+| Adapter | P@5 | R@5 | Tỷ lệ hit top-5 | Độ trễ p50 |
+|---|---|---|---|---|
+| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
+| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
+
+Tỷ lệ hit top-5 đạt 100% tại **ngưỡng toán học P@5** cho corpus này (0.240, xem scorecard). Hybrid lấy được mọi gold session; grep bỏ lỡ 1 trong 2 gold ở câu truy vấn temporal đa session. Mức cải thiện nằm ở **recall + temporal**, không phải precision tổng hợp. Benchmark này nhỏ và thưa gold; LongMemEval-S lớn hơn ở dưới phân biệt tốt hơn. Phân tích chi tiết theo từng loại + ghi chú đính chính đầy đủ: [`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 câu hỏi)
+
+| Hệ thống | R@5 | R@10 | MRR |
+|---|---|---|---|
+| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
+| BM25-only fallback | 86.2% | 94.6% | 71.5% |
+
+
+
+
+### Tiết kiệm Token
+
+| Cách tiếp cận | Token/năm | Chi phí/năm |
+|---|---|---|
+| Dán toàn bộ context | 19.5M+ | Không thể (vượt window) |
+| Tóm tắt bằng LLM | ~650K | ~$500 |
+| **agentmemory** | **~170K** | **~$10** |
+| agentmemory + embedding cục bộ | ~170K | **$0** |
+
+
+
+
+
+> Embedding model: `all-MiniLM-L6-v2` (cục bộ, miễn phí, không cần API key). Báo cáo đầy đủ: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). So sánh đối thủ: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) bao gồm agentmemory so với mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
+
+**Tái lập cục bộ:** [`eval/README.md`](../eval/README.md), một harness có thể cắm (pluggable) adapter cho LongMemEval `_s` (500 câu hỏi công khai) + `coding-agent-life-v1` (corpus nội bộ 15 session). Các adapter grep / vector / agentmemory được chấm điểm song song, xuất NDJSON, các scorecard đã công bố nằm tại [`docs/benchmarks/`](../docs/benchmarks/).
+
+**Kết hợp tốt với [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), và [Graphify](https://github.com/safishamsi/graphify).** Index hóa code-graph, pipeline build đa agent, và các knowledge graph rộng hơn trên docs / PDF / ảnh / video. agentmemory ghi nhớ phần công việc; ba dự án này làm sáng rõ phần còn lại của context layer. Công thức + bảng định tuyến câu hỏi: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
+
+---
+
+
+
+
+
+
+
agentmemory
+
mem0 (63K ⭐)
+
Letta / MemGPT (24K ⭐)
+
Khoj (36K ⭐)
+
supermemory (29K ⭐)
+
TencentDB Agent Memory (22K ⭐)
+
MemPalace (54K ⭐)
+
oracleagentmemory
+
Hippo
+
Tích hợp sẵn (CLAUDE.md)
+
+
+
Loại
+
Engine bộ nhớ + MCP server
+
API lớp bộ nhớ
+
Runtime agent đầy đủ
+
AI cá nhân
+
API bộ nhớ + app
+
Hub bộ nhớ nhóm (LLM proxy)
+
Bộ nhớ vector (OSS)
+
Engine bộ nhớ (Oracle DB)
+
Hệ thống bộ nhớ
+
File tĩnh
+
+
+
Retrieval R@5
+
95.2%
+
68.5% (LoCoMo)
+
83.2% (LoCoMo)
+
N/A
+
Tự công bố
+
PersonaMem 76% (tự công bố)
+
~96.6% (tự công bố)
+
94.4% (tự công bố)
+
N/A
+
N/A (grep)
+
+
+
Auto-capture
+
12 hooks (không cần thao tác thủ công)
+
Gọi add() thủ công
+
Agent tự sửa
+
Thủ công
+
Trích xuất phía API
+
Chặn qua proxy (đổi base-URL)
+
Thủ công
+
Trích xuất qua API
+
Thủ công
+
Chỉnh sửa thủ công
+
+
+
Tìm kiếm
+
BM25 + Vector + Graph (RRF fusion)
+
Vector + Graph
+
Vector (lưu trữ archival)
+
Ngữ nghĩa (semantic)
+
Vector + RAG
+
4 loại asset (Chat / Skill / Wiki / CodeGraph)
+
Chỉ Vector
+
Vector + ngữ nghĩa
+
Có trọng số suy giảm (decay)
+
Nạp tất cả vào context
+
+
+
Đa agent
+
MCP + REST + lease + signal
+
API (không điều phối)
+
Chỉ trong runtime Letta
+
Không
+
Không
+
Vai trò nhóm + asset chia sẻ
+
Không
+
Chỉ theo scope
+
Chia sẻ đa agent
+
File theo từng agent
+
+
+
Lệ thuộc framework
+
Không (bất kỳ MCP client nào)
+
Không
+
Cao (phải dùng Letta)
+
Độc lập (standalone)
+
Không
+
Proxy chặn trước mọi lệnh gọi model
+
Không
+
Oracle Database
+
Không
+
Định dạng theo từng agent
+
+
+
Dependency bên ngoài
+
Không (SQLite + iii-engine)
+
Qdrant / pgvector
+
Postgres + vector DB
+
Nhiều
+
Cloud được quản lý
+
Docker stack (Core + Hub + Proxy)
+
Vector store
+
Oracle AI Database
+
Không
+
Không
+
+
+
Lifecycle bộ nhớ
+
Hợp nhất 4 tầng + suy giảm + tự quên
+
Trích xuất bị động
+
Do agent quản lý
+
Thủ công
+
Tự quên (auto-forget)
+
Review thủ công; auto-routing đang phát triển
+
Không
+
Không công bố
+
Suy giảm + hợp nhất
+
Cắt bỏ thủ công
+
+
+
Hiệu quả token
+
~1,900 token/session ($10/năm)
+
Thay đổi theo tích hợp
+
Bộ nhớ lõi (core memory) nằm trong context
+
Thay đổi
+
Theo giá cloud
+
Không công bố
+
Không có ngân sách token
+
Dựa trên LLM (thay đổi)
+
Thay đổi
+
22K+ token ở 240 observation
+
+
+
Viewer real-time
+
Có (port 3113)
+
Cloud dashboard
+
Cloud dashboard
+
Web UI
+
Cloud dashboard
+
Hub web UI
+
Không
+
Không
+
Không
+
Không
+
+
+
Self-hosted
+
Có (mặc định)
+
Tùy chọn
+
Tùy chọn
+
Có
+
Không (chỉ cloud)
+
Có (Docker)
+
Có
+
Có (Oracle DB)
+
Có
+
Có
+
+
+
+Ghi chú benchmark: chỉ con số R@5 của agentmemory là kết quả đo đạc của chính chúng tôi (LongMemEval-S, có thể tái lập từ benchmark/COMPARISON.md). Các số liệu của mem0 và Letta là số LoCoMo họ đã công bố (một dataset khác); các số liệu của MemPalace, supermemory, TencentDB (PersonaMem), và oracleagentmemory là các tuyên bố tự công bố từ nhà cung cấp mà chúng tôi chưa tái lập độc lập (lần chạy của oracleagentmemory dùng GPT-5.5 trên một Oracle AI Database). Chỉ hiển thị song song để ước lượng, không phải so sánh trực tiếp (head-to-head) trên cùng dữ liệu. Số lượng star chỉ là gần đúng và thay đổi theo thời gian.
+
+**Những cái tên mới** đáng để biết, được so sánh chi tiết trong [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md):
+
+| Hệ thống | ⭐ | Hướng tiếp cận |
+|--------|---|-------|
+| Zep / Graphiti | 30K | Knowledge graph theo thời gian (temporal); kết quả truy vấn temporal công bố mạnh nhất (LongMemEval 63.8%), nhưng graph được xây dựng bất đồng bộ nên các fact mới có thể bị trễ |
+| Cognee | 30K | Nạp từ tài liệu sang knowledge graph, chỉ hỗ trợ Python, được xây dựng để trích xuất entity có cấu trúc hơn là để capture session |
+
+Không cái nào trong số này tự động capture từ hook của coding agent, có sẵn viewer local-first, hoặc chạy được ở chế độ keyless — đây chính là tổ hợp mà agentmemory được xây dựng xung quanh.
+
+---
+
+
+
+Khả năng tương thích: bản phát hành này nhắm tới `iii-sdk` 0.22.1 và pin iii-engine v0.22.1.
+
+### Thử trong 30 giây
+
+```bash
+# Terminal 1: start the server
+npx -y @agentmemory/agentmemory@latest
+
+# Terminal 2: seed sample data and see recall in action
+npx -y @agentmemory/agentmemory@latest demo
+```
+
+`demo` khởi tạo 3 session thực tế (JWT auth, sửa lỗi N+1 query, rate limiting) và chạy các tìm kiếm trên đó. Bản cài keyless tắt vector, nên các truy vấn từ khóa `mem::search` sẽ cho kết quả đúng qua BM25 trong khi `database performance optimization` có thể trả về rỗng. `smart-search` có thể trả thêm các kết quả khớp từ graph cấu trúc khi dữ liệu graph tồn tại. Để truy vấn ngữ nghĩa tìm được bản sửa N+1 qua vector, hãy đặt `EMBEDDING_PROVIDER=local`, khởi động lại, và chờ lần tải model đầu tiên hoàn tất.
+
+Mở `http://localhost:3113` để xem bộ nhớ được xây dựng theo thời gian thực.
+
+### Kiểm tra một bản cài mới và độ bền sau khi khởi động lại
+
+Khi server đang chạy, hãy kiểm tra REST, health, viewer, và trạng thái runtime dựa trên iii:
+
+```bash
+curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS -o /dev/null http://localhost:3113/
+npx -y @agentmemory/agentmemory@latest status
+```
+
+Panel sẵn sàng lúc khởi động tính đến cả bốn port: REST/MCP HTTP trên 3111, iii streams trên 3112, viewer trên 3113, và WebSocket của iii worker trên 49134. `status` xác nhận tình trạng của agentmemory và provider/chế độ embedding đang hoạt động. Lưu một probe và xác nhận nó có thể tìm kiếm được:
+
+```bash
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H 'Content-Type: application/json' \
+ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
+
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H 'Content-Type: application/json' \
+ -d '{"query":"restart persistence probe","limit":5}'
+```
+
+Sau đó chạy `npx -y @agentmemory/agentmemory@latest stop`, khởi động lại lệnh canonical ở Terminal 1, chờ `/agentmemory/livez`, và lặp lại tìm kiếm. Probe đó vẫn phải được trả về. Nếu bạn đã chọn một `--data-dir` tùy chỉnh, hãy truyền cùng thư mục đó khi khởi động lại.
+
+### Các lệnh dùng hàng ngày
+
+Cài đặt và thiết lập nằm ở phần [Cài đặt](#install) ở trên (lần chạy đầu tiên sẽ dẫn bạn qua từng bước). Hàng ngày:
+
+```bash
+agentmemory # start the server
+agentmemory stop # stop it cleanly
+agentmemory connect # wire another agent
+agentmemory doctor # interactive diagnostics + fix prompts
+agentmemory remove # uninstall everything we created
+```
+
+### Phát lại Session
+
+Mọi session mà agentmemory ghi lại đều có thể phát lại (replay). Mở viewer, chọn tab **Replay**, và kéo qua timeline: prompt, tool call, kết quả tool, và response được hiển thị như các event rời rạc với play/pause, điều khiển tốc độ (0.5x đến 4x), và phím tắt bàn phím (space để toggle, mũi tên để bước qua từng event).
+
+Để đưa vào các transcript JSONL cũ của Claude Code:
+
+```bash
+# Import everything under the default ~/.claude/projects
+npx -y @agentmemory/agentmemory@latest import-jsonl
+
+# Or import a single file
+npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
+```
+
+Các session đã import sẽ xuất hiện trong bộ chọn Replay cùng với các session gốc (native). Bên dưới, mỗi entry đi qua các iii function `mem::replay::load`, `mem::replay::sessions`, và `mem::replay::import-jsonl`, không cần server kênh phụ (side-channel) nào. Mỗi transcript được import sẽ được index để tìm kiếm, đánh dấu với origin channel là `import`, và được khai thác để tạo session crystal và lesson.
+
+> **Lưu ý nếu bạn dựa vào `import-jsonl` như đường capture chính:** `cleanupPeriodDays` của Claude Code (trong `~/.claude/settings.json`, mặc định **30**) tự động xóa các transcript JSONL cũ hơn khoảng thời gian đó khỏi `~/.claude/projects/`. Nếu bạn cài agentmemory mới trên một lịch sử Claude Code đã vài tháng tuổi, bất cứ thứ gì cũ hơn 30 ngày đã mất trước lần import đầu tiên. Hãy chạy `import-jsonl` theo cron, tăng `cleanupPeriodDays` lên một giá trị cao hơn, hoặc kết nối các hook auto-capture (đường cài plugin mặc định) để mỗi turn đi vào agentmemory ngay khi session còn sống, và việc dọn JSONL không còn quan trọng nữa.
+
+### Nâng cấp / Bảo trì
+
+Dùng lệnh bảo trì khi bạn chủ động muốn cập nhật runtime cục bộ của mình:
+
+```bash
+npx -y @agentmemory/agentmemory@latest upgrade
+```
+
+Cảnh báo: lệnh này thay đổi workspace/runtime hiện tại. Nó có thể cập nhật các dependency JavaScript và pull image Docker `iiidev/iii:0.22.1` đã được pin. Nó không bao giờ cài một iii engine chưa pin hoặc mới hơn.
+
+Chi tiết triển khai nằm trong `src/cli.ts` (xem `runUpgrade` quanh khu vực `src/cli.ts:544-595`).
+
+### Claude Code (một block, dán vào)
+
+```text
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
+```
+
+#### Claude Code không cài plugin (đường MCP độc lập)
+
+Nếu bạn kết nối MCP server của agentmemory qua `~/.claude.json` trực tiếp thay vì dùng `/plugin install`, Claude Code sẽ không bao giờ resolve `${CLAUDE_PLUGIN_ROOT}` và bạn phải chỉ các hook script tới đường dẫn tuyệt đối trong `~/.claude/settings.json`. Các đường dẫn đó thường nhúng cả phiên bản agentmemory (ví dụ `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), nên lần nâng cấp kế tiếp sẽ lặng lẽ làm hỏng mọi hook.
+
+Cách khắc phục tạm:
+
+```bash
+agentmemory connect claude-code --with-hooks
+```
+
+Lệnh này gộp cùng các hook command đó vào `~/.claude/settings.json` với đường dẫn tuyệt đối được resolve tới thư mục `plugin/` đi kèm của package `@agentmemory/agentmemory` đang được cài. Chạy lại lệnh này sau khi nâng cấp agentmemory để làm mới các đường dẫn. Các entry của người dùng trong cùng file được giữ lại; chỉ các entry agentmemory trước đó bị thay thế. Dùng đường `/plugin install` vẫn là cách được khuyến nghị.
+Với các deployment từ xa hoặc được bảo vệ, hãy khởi chạy Claude Code với `AGENTMEMORY_URL` và `AGENTMEMORY_SECRET` đã được đặt. Plugin sẽ truyền cả hai giá trị này xuống MCP server đi kèm của nó; khi `AGENTMEMORY_URL` để trống, MCP shim dùng `http://localhost:3111`.
+
+### Codex CLI (nền tảng plugin của Codex)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx -y @agentmemory/agentmemory@latest
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Plugin Codex được phát hành từ cùng thư mục `plugin/` như plugin Claude Code. Nó đăng ký:
+
+- Một cầu nối MCP qua stdio được đóng gói sẵn tới daemon đang chạy, không cần tải npm hay fallback store. Xem [hướng dẫn Codex local](../docs/plugins/codex-local.md) để test một build chưa được release.
+- 6 hook lifecycle: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 9 skill có thể gọi (invocable): `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, cùng 8 skill tham chiếu mà agent nạp theo nhu cầu (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, và hướng dẫn viết skill)
+
+Hook engine của Codex tiêm `CLAUDE_PLUGIN_ROOT` vào các subprocess hook (theo [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), nên cùng các hook script này hoạt động trên cả hai host mà không cần trùng lặp. Các event Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure chỉ dành riêng cho Claude Code và không được đăng ký cho Codex.
+
+#### Trust và tính tương thích của hook Codex
+
+Dispatch hook plugin gốc đã được verify với Codex CLI 0.150.1. Hãy trust các hook plugin trước khi kỳ vọng capture. Hành vi của Desktop phụ thuộc vào runtime đi kèm của nó; kiểm tra `/hooks` và xác nhận có một event được capture trước khi bật một cách khắc phục tạm.
+
+Nếu host của bạn cần global hook, hãy sao chép các command vào `~/.codex/hooks.json`. Khi MCP đã được kết nối sẵn, connector hiện tại cần `--force` để tiến tới bước cài hook:
+
+```bash
+agentmemory connect codex --with-hooks --force
+```
+
+Lệnh này gộp các global hook và viết lại entry MCP của agentmemory, trong khi vẫn giữ nguyên các entry không liên quan. Hãy xem lại mọi cấu hình endpoint agentmemory tùy chỉnh trước khi dùng `--force`. Chạy lại sau khi nâng cấp để làm mới các đường dẫn script. Chỉ nên bật một trong hai: hook plugin gốc hoặc các bản sao global, để tránh capture trùng lặp.
+
+### GitHub Copilot CLI
+
+Đối với VS Code agent mode, hãy dùng [hướng dẫn MCP và automatic-capture của Copilot](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). Connector CLI này không cấu hình VS Code.
+
+```bash
+# MCP-only wiring
+agentmemory connect copilot-cli
+
+# Alternatively, full hooks/skills plugin from the GitHub subdir
+copilot plugin install rohitg00/agentmemory:plugin
+```
+
+`agentmemory connect copilot-cli` gộp `mcpServers.agentmemory` vào `~/.copilot/mcp-config.json` (hoặc `$COPILOT_HOME/mcp-config.json` khi `COPILOT_HOME` được đặt) và giữ lại các server đã có. Trên Windows gốc, đây là adapter `connect` tự động duy nhất; mọi agent Windows gốc khác phải cấu hình thủ công. `connect` trong WSL chỉ được hỗ trợ khi agent đích cũng được cài trong cùng môi trường WSL đó. Copilot sẽ nhận MCP server ở lần khởi chạy kế tiếp hoặc sau `/mcp`. Cài thêm plugin nếu bạn muốn có đầy đủ trải nghiệm hook/skill.
+
+
+OpenClaw (dán prompt này)
+
+```text
+Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
+
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+
+Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
+```
+
+Hướng dẫn đầy đủ: [`integrations/openclaw/`](../integrations/openclaw/)
+
+
+
+
+Hermes Agent (dán prompt này)
+
+```text
+Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
+
+mcp_servers:
+ agentmemory:
+ command: npx
+ args: ["-y", "@agentmemory/mcp"]
+
+memory:
+ provider: agentmemory
+
+Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
+```
+
+Hướng dẫn đầy đủ: [`integrations/hermes/`](../integrations/hermes/)
+
+
+
+### Các agent khác
+
+Khởi động memory server: `npx -y @agentmemory/agentmemory@latest`
+
+#### Skill gốc qua `npx skills add` (50+ agent)
+
+agentmemory đi kèm 17 skill theo định dạng `/SKILL.md` kiểu Claude Code: 9 skill hành động có thể gọi (`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`) và 8 skill tham chiếu mà agent nạp theo nhu cầu (`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). Các skill tham chiếu mang theo bảng dữ liệu được sinh ra từ source, nên chúng không bao giờ lệch (drift). CLI [`skills`](https://npmjs.com/package/skills) của vercel-labs tự cài chúng vào thư mục skill gốc của agent gọi nó, trên hơn 50 agent (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, và nhiều hơn nữa):
+
+```bash
+npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
+npx skills add rohitg00/agentmemory -y -a warp # explicit agent
+npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
+```
+
+Điều này **bổ sung** cho `agentmemory connect `:
+
+- `agentmemory connect ` viết config MCP server để các tool khả dụng.
+- `npx skills add rohitg00/agentmemory` cài các skill để agent biết khi nào cần gọi chúng.
+
+Với một số ít agent mà CLI skills chưa hỗ trợ (Zed v1.3.x và thấp hơn), hãy tự đặt 17 file SKILL.md vào thư mục skill gốc của agent đó; cùng một định dạng hoạt động ở mọi nơi.
+
+#### Block MCP chuẩn
+
+Entry của agentmemory là **cùng một block MCP server** trên mọi host dùng hình thái `mcpServers` (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
+
+```json
+"agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
+ "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
+ }
+}
+```
+
+**Gộp entry này vào object `mcpServers` đã có** trong file config của host; không thay thế toàn bộ file. Nếu file đã có server khác, hãy thêm `agentmemory` cạnh chúng như một key khác trong `mcpServers`. Nếu `mcpServers` hoàn toàn chưa có, dán block này vào trong `{ "mcpServers": { ... } }`. Các placeholder `${VAR}` kế thừa `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` từ shell tại thời điểm khởi chạy MCP server; biến chưa đặt sẽ truyền chuỗi rỗng và shim sẽ fallback về `http://localhost:3111`. Một entry đã kết nối có thể dùng cho cả deployment local và remote (k8s / sau reverse-proxy).
+
+| Agent | File config | Ghi chú |
+|---|---|---|
+| **Cursor (chỉ MCP)** | `~/.cursor/mcp.json` | Gộp vào `mcpServers`, hoặc dùng `agentmemory connect cursor`. Cũng có deeplink one-click trên website. |
+| **Cursor (plugin đầy đủ)** | `.cursor-plugin/` | Listing trên Cursor Marketplace (submission đang chờ duyệt) hoặc Cursor Settings → Plugins → local checkout. Đăng ký 7 hook auto-capture (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skill + MCP server, với `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` được quản lý trong dashboard plugin của Cursor. Hoạt động trong Cursor IDE và CLI `cursor-agent`; các prompt ở print-mode của CLI được điền lại từ transcript session khi session kết thúc. |
+| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Gộp vào `mcpServers`. Khởi động lại Claude Desktop sau khi sửa. |
+| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Cùng block `mcpServers`. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` gộp entry MCP; `--with-hooks` thêm sáu hook auto-capture gốc (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) với các tool matcher chữ thường của Devin. Kiểm tra bằng `devin mcp list` và `/hooks` trong devin. |
+| **Devin CLI (plugin đầy đủ)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` từ một checkout đăng ký toàn bộ 17 skill dưới dạng slash command `/agentmemory:` cùng với MCP server. Hook plugin của Devin không thể bắn `SessionStart`/`SessionEnd`, nên hãy kết hợp với `connect devin --with-hooks` để capture session đầy đủ. |
+| **Devin (cloud)** | Settings → Connections → MCP servers | Thêm một MCP tùy chỉnh (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` chỉ tới một deployment agentmemory có thể truy cập qua network cùng `AGENTMEMORY_SECRET` (các session cloud không thể chạm tới localhost — xem [`deploy/`](../deploy/)). Lưu secret trong Devin Secrets, sau đó dùng "Test listing tools" để xác nhận cả 54 tool đều xuất hiện. |
+| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (tự gộp). |
+| **GitHub Copilot CLI (chỉ MCP)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` gộp `mcpServers.agentmemory`; Copilot sẽ nhận ở lần khởi chạy kế tiếp hoặc `/mcp`. |
+| **GitHub Copilot CLI (plugin đầy đủ)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` để lấy plugin từ subdir GitHub. |
+| **OpenClaw** | OpenClaw MCP config | Cùng block `mcpServers`. Sâu hơn: `openclaw plugins install ./integrations/openclaw` chiếm memory slot của OpenClaw (tự chuyển từ `memory-core`); đặt `plugins.entries.agentmemory.hooks.allowConversationAccess=true` nếu không turn capture sẽ bị chặn một cách im lặng. Xem [`integrations/openclaw`](../integrations/openclaw/). |
+| **Codex CLI (chỉ MCP)** | `.codex/config.toml` | Hình thái TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, hoặc thêm `[mcp_servers.agentmemory]` thủ công. |
+| **Codex CLI (plugin đầy đủ)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` sau đó `codex plugin add agentmemory@agentmemory`. Đăng ký MCP + 6 hook lifecycle + 17 skill. Hãy trust các hook và verify việc capture trên host của bạn; xem [hướng dẫn setup và validation Codex](../docs/plugins/codex-local.md). |
+| **OpenCode (chỉ MCP)** | `opencode.json` | Hình thái khác: key `mcp` ở cấp cao nhất, command là một array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
+| **OpenCode (plugin đầy đủ)** | `plugin/opencode/` | 22 hook auto-capture bao phủ lifecycle session, message, tool, lỗi. Attribution project theo từng session, nên một process OpenCode trải trên nhiều repository sẽ ghi mỗi session dưới đúng project của nó. Hai slash command (`/recall`, `/remember`). Copy `plugin/opencode/` vào workspace OpenCode của bạn và thêm entry plugin vào `opencode.json`. Xem [`plugin/opencode/README.md`](../plugin/opencode/README.md) để biết bảng hook đầy đủ + phân tích phần còn thiếu. |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` cài extension đi kèm vào thư mục auto-discovery của pi (recall khi agent khởi động, capture khi agent kết thúc, các tool `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`). `/reload` trong một pi đang chạy sẽ nhận nó. [`integrations/pi`](../integrations/pi/) cũng là một package pi (`pi install ./integrations/pi` từ một checkout). |
+| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` cho bạn memory provider 6-hook (prefetch, turn capture, session end, pre-compress, mirror MEMORY.md, system prompt block). Kiểm tra bằng `hermes plugins doctor` và `hermes memory status`. Xem [`integrations/hermes`](../integrations/hermes/). |
+| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` viết block `mcpServers` chuẩn. Payload hook tương thích field với Claude Code, nên các script 12-hook hiện có hoạt động không cần sửa đổi; kết nối chúng qua phần `hooks` trong cùng `settings.json`. |
+| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` cài MCP và capture hook vào thư mục customization chung. Xem [thiết lập và giới hạn của Antigravity](../docs/plugins/antigravity.md). |
+| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks` dùng cùng cấu hình MCP và hook như các phiên bản IDE hiện tại. Các bản cài đặt sẵn có nên refresh bằng `--force`; xem [ghi chú upgrade](../docs/plugins/antigravity.md). |
+| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` viết config ở cấp user. Các override ở cấp workspace nằm trong `.kiro/settings/mcp.json` cạnh code của bạn. |
+| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` viết block `mcpServers` chuẩn. Warp cũng tự phát hiện skill từ `.claude/skills/`; khi plugin Claude Code được cài, 8 skill agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) sẽ xuất hiện một cách tự nhiên trong bảng slash-command của Warp. |
+| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` viết block `mcpServers` chuẩn. Người dùng extension VS Code: dán cùng block này qua Cline Settings → MCP Servers → Edit JSON. |
+| **Continue.dev** | `~/.continue/config.yaml` (ưu tiên) hoặc `config.json` (legacy) | `agentmemory connect continue` tạo mới `config.yaml` từ đầu khi không có file nào tồn tại, hoặc sửa `config.json` đã có. **Nếu bạn đã có `config.yaml`** adapter sẽ in ra đúng block để dán vào dưới `mcpServers:`; nó sẽ không lặng lẽ viết lại yaml của bạn vì việc giữ comment và anchor an toàn cần một YAML parser mà package này không đi kèm. Continue dùng dạng array (không phải object) cho `mcpServers`. |
+| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` viết dưới `context_servers` (key riêng của Zed, KHÔNG phải `mcpServers`). Các MCP server remote có thể được kết nối qua `{"url": "..."}` thay thế. |
+| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` viết block `mcpServers` chuẩn. Các override theo project nằm trong `/.factory/mcp.json`. Truyền `--with-hooks` để có auto-capture gốc. |
+| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` thêm một dòng `@deepseek-ai/dsh-mcp-client` vào patch layer ở cấp home mà mọi Harness profile đều nạp; các tool đăng ký dưới dạng `mcp__agentmemory__*`. Truyền `--with-hooks` để kết nối thêm auto-capture: các hook script Claude Code đi kèm chạy qua bridge chính chủ `@deepseek-ai/dsh-hooks-claude-code` của Harness (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop) qua một manifest được viết vào `$DSH_HOME/agentmemory.hooks.json`. Mặc định là `~/.dsh` khi `DSH_HOME` chưa được đặt. |
+| **Goose** | Goose MCP settings UI | Cùng block `mcpServers`; dùng `goose configure` → Add Extension → MCP. Sửa YAML trực tiếp tại `~/.config/goose/config.yaml` cũng được hỗ trợ nhưng schema dùng `extensions:` + `cmd` (không phải `mcpServers:` + `command`). |
+| **Aider** | n/a | Gọi trực tiếp REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Bất kỳ agent nào (32+)** | n/a | `npx skillkit install agentmemory` tự phát hiện host và gộp. |
+
+**Các MCP client chạy trong sandbox** (Flatpak / Snap / container hạn chế) không thể chạm tới `localhost` của host: hãy đặt thêm `"AGENTMEMORY_FORCE_PROXY": "1"` trong block `env`, và chỉ `AGENTMEMORY_URL` tới một route mà sandbox thực sự chạm tới được (ví dụ IP LAN của bạn).
+
+### Truy cập theo chương trình (Python / Rust / Node)
+
+agentmemory đăng ký các operation lõi của nó dưới dạng iii function (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Bất kỳ ngôn ngữ nào có iii SDK đều có thể gọi chúng trực tiếp qua `ws://localhost:49134`, không cần một REST client riêng cho từng ngôn ngữ.
+
+```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"},
+})
+```
+
+Ví dụ hoàn chỉnh: [`examples/python/`](../examples/python/) (quickstart + luồng observation/recall). REST trên `:3111` vẫn khả dụng cho các host không có iii runtime.
+
+### Từ source
+
+```bash
+git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
+npm install && npm run build && npm start
+```
+
+Lệnh này khởi động agentmemory với một `iii-engine` cục bộ nếu binary đã pin được cài sẵn, hoặc dùng Docker Compose khi được chọn. REST, stream, và viewer bind vào `127.0.0.1` theo mặc định. Đường binary tự động trên macOS/Linux cần `curl`, một `sh` chuẩn POSIX, và `tar`.
+
+Cài `iii-engine` thủ công. **agentmemory hiện đang pin `iii-engine` ở `v0.22.1`**, cùng release với dependency `iii-sdk` của nó; worker nói đúng wire protocol của engine đó, và 0.20.0 đã tổ chức lại toàn bộ SDK surface, nên cả hai di chuyển cùng nhau qua các bản phát hành của agentmemory. Ghi đè bằng `AGENTMEMORY_III_VERSION=` nếu bạn chạy engine riêng và biết chắc nó khớp.
+
+- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
+- **macOS x64:** đổi `aarch64-apple-darwin` thành `x86_64-apple-darwin`
+- **Linux x64:** đổi thành `x86_64-unknown-linux-gnu`
+- **Linux arm64:** đổi thành `aarch64-unknown-linux-gnu`
+- **Windows:** tải `iii-x86_64-pc-windows-msvc.zip` từ [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) và giải nén `iii.exe` vào `%USERPROFILE%\.agentmemory\bin\iii.exe`
+
+Mỗi archive đều có một file `.sha256` tương ứng trên trang release; khi bạn đổi platform, dùng hash của đúng file đó trong lệnh kiểm tra ở trên (trên Windows: `Get-FileHash`). Bộ cài tự động trong `npx @agentmemory/agentmemory` pin các hash này và từ chối một archive không khớp.
+
+Hoặc dùng Docker (`docker-compose.yml` đi kèm pull `iiidev/iii:0.22.1`). Docs đầy đủ: [iii.dev/docs](https://iii.dev/docs).
+
+### Windows
+
+agentmemory chạy trên Windows 10/11, nhưng chỉ riêng package Node.js thì chưa đủ; bạn còn cần runtime iii-engine v0.22.1 đã pin chạy như một process nền. CLI không tự động giải nén file ZIP Windows, nên người dùng Windows gốc phải cài `iii.exe` thủ công, dùng WSL2, hoặc chọn Docker Desktop.
+
+Việc tự động kết nối MCP trên Windows gốc chỉ hỗ trợ `agentmemory connect copilot-cli`. Với Claude Code, Codex, Cursor, và mọi agent Windows gốc khác, hãy copy block MCP thủ công từ [Các agent khác](#other-agents) vào config Windows của agent đó. Chạy `connect` trong WSL chỉ phù hợp khi agent đích cũng được cài trong cùng môi trường WSL; nó không sửa config của một agent chạy trên Windows host.
+
+**Phương án A: binary Windows build sẵn (khuyến nghị)**
+
+```powershell
+# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
+# (agentmemory pins the engine to the same release as its iii-sdk;
+# v0.22.1 is the current pair)
+# 2. Download iii-x86_64-pc-windows-msvc.zip
+# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
+# 3. Extract iii.exe to agentmemory's private engine directory:
+New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
+# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
+# 4. Verify:
+& "$HOME\.agentmemory\bin\iii.exe" --version
+# Should print: 0.22.1
+
+# 5. Then run agentmemory as usual:
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Phương án B: Docker Desktop**
+
+```powershell
+# 1. Install Docker Desktop for Windows
+# 2. Start Docker Desktop and make sure the engine is running
+# 3. Select Docker explicitly and run agentmemory:
+$env:AGENTMEMORY_USE_DOCKER = "1"
+npx -y @agentmemory/agentmemory@latest
+```
+
+**Phương án C: chỉ MCP độc lập (không engine).** Nếu bạn chỉ cần các MCP tool cho agent của mình và không cần REST API, viewer, hay cron job, hãy bỏ qua engine hoàn toàn:
+
+```powershell
+npx -y @agentmemory/agentmemory@latest mcp
+# or via the shim package:
+npx -y @agentmemory/mcp
+```
+
+**Chẩn đoán cho Windows:** nếu `npx -y @agentmemory/agentmemory@latest` lỗi, chạy lại với `--verbose` để xem stderr thật của engine. Các lỗi thường gặp:
+
+| Triệu chứng | Cách khắc phục |
+|---|---|
+| `The engine process started but the REST API never responded.` | Xác nhận cả bốn port suy ra đều trống, kiểm tra `iii.exe` đã pin còn sống, sau đó chạy lại với `--verbose` và xem stderr đã bắt được của engine |
+| `Could not start iii-engine` | Không có `iii.exe` cũng không có Docker được cài. Xem Phương án A hoặc B ở trên |
+| Xung đột port | `netstat -ano \| findstr :3111` để xem cái gì đang chiếm port, sau đó kill nó hoặc dùng `--port ` |
+| Docker fallback bị bỏ qua dù Docker đã được cài | Đảm bảo Docker Desktop thực sự đang chạy (icon trên system tray) |
+
+> Lưu ý: iii **engine** là một binary build sẵn, không phải một cargo crate, nên đừng cố `cargo install` nó. (Các iii **SDK** được publish trên crates.io, npm, và PyPI, nhưng agentmemory không cần chúng.) Các cách cài engine được hỗ trợ đều pin ở v0.22.1: binary build sẵn ở trên, đường tự cài macOS/Linux của agentmemory (cần `curl`, `sh` chuẩn POSIX, và `tar`), và image Docker `iiidev/iii:0.22.1`. Một lệnh `install.sh | sh` trần từ upstream sẽ cài engine mới nhất, cái mà agentmemory không hỗ trợ. Hãy dùng `npx -y @agentmemory/agentmemory@latest`; trên macOS/Linux nó sẽ tải engine đã pin vào `~/.agentmemory/bin`.
+
+---
+
+
Triển khai
+
+Các template one-click cho các managed host. Mỗi template đi kèm một Dockerfile tự chứa pull `@agentmemory/agentmemory` từ npm và copy binary iii engine vào từ image Docker Hub chính thức `iiidev/iii`; không cần image agentmemory build sẵn. Storage bền vững mount tại `/data`; entrypoint ở lần boot đầu tiên sẽ ghi đè config iii đi kèm trong npm (vốn bind `127.0.0.1`) bằng một config được chỉnh cho deploy, bind `0.0.0.0` và dùng đường dẫn `/data` tuyệt đối, sinh HMAC secret, rồi hạ quyền từ `root` xuống `node` qua `gosu` trước khi exec CLI agentmemory.
+
+
+
+
+
+
+Nút one-click deploy của Render yêu cầu `render.yaml` ở gốc repository, và chúng tôi chủ đích giữ nó sạch. Hãy dùng luồng Render Blueprint được ghi lại trong [`deploy/render/`](.././deploy/render/README.md) để chỉ tới blueprint trong repo một cách thủ công.
+
+Chi tiết thiết lập đầy đủ (capture HMAC, SSH tunnel cho viewer, xoay, backup, mức chi phí sàn) nằm trong [`deploy/`](.././deploy/README.md):
+
+- [`deploy/fly`](.././deploy/fly/README.md): một máy đơn với
+ `auto_stop_machines = "stop"`; rẻ nhất khi idle.
+- [`deploy/railway`](.././deploy/railway/README.md): phí cố định của Hobby plan,
+ volume trong dashboard.
+- [`deploy/render`](.././deploy/render/README.md): luồng Blueprint,
+ tự động snapshot disk trên các plan trả phí.
+- [`deploy/coolify`](.././deploy/coolify/README.md): self-hosted trên
+ VPS riêng của bạn qua [Coolify](https://coolify.io/self-hosted); cùng
+ Docker Compose stack, bạn sở hữu cả host và dữ liệu.
+
+Chỉ port `3111` được publish. Viewer trên `3113` vẫn bind vào
+loopback bên trong container; README của mỗi template đều ghi lại
+pattern SSH-tunnel để chạm tới nó.
+
+---
+
+
+
+Mọi coding agent đều quên hết mọi thứ khi session kết thúc, và mỗi session mới lại bắt đầu bằng việc bạn giải thích lại stack của mình. agentmemory chạy ngầm và loại bỏ hẳn bước đó.
+
+```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.
+```
+
+### So với bộ nhớ tích hợp sẵn của agent
+
+Mọi AI coding agent đều đi kèm bộ nhớ tích hợp sẵn: Claude Code có `MEMORY.md`, Cursor có notepad, Cline có memory bank. Những thứ này hoạt động như giấy nhớ (sticky note). agentmemory là cơ sở dữ liệu có thể tìm kiếm đứng sau những tờ giấy nhớ đó.
+
+| | Tích hợp sẵn (CLAUDE.md) | agentmemory |
+|---|---|---|
+| Quy mô | Giới hạn 200 dòng | Không giới hạn |
+| Tìm kiếm | Nạp tất cả vào context | BM25 + vector + graph (chỉ top-K) |
+| Chi phí token | 22K+ ở 240 observation | ~1,900 token (giảm 92%) |
+| Đa agent | File theo từng agent | MCP + REST (mọi agent) |
+| Điều phối | Không có | Lease, signal, action, routine |
+| Observability | Đọc file thủ công | Viewer real-time trên :3113 |
+
+---
+
+
+
+### Pipeline bộ nhớ
+
+```text
+PostToolUse hook fires
+ -> SHA-256 dedup (5min window)
+ -> Privacy filter (strip secrets, API keys)
+ -> Store raw observation
+ -> Synthetic compression by default
+ (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
+ -> Vector embedding when an embedding provider is active
+ -> Index in BM25, plus vectors when enabled
+
+Stop / SessionEnd hook fires
+ -> Summarize session
+ -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
+ -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+
+SessionStart hook fires
+ -> Load project profile (top concepts, files, patterns)
+ -> Hybrid search (BM25 + vector + graph)
+ -> Token budget (default: 2000 tokens)
+ -> Inject into conversation
+```
+
+### Hợp nhất bộ nhớ 4 tầng
+
+Lấy cảm hứng từ cách não người xử lý bộ nhớ, kể cả quá trình hợp nhất trong khi ngủ.
+
+| Tầng | Là gì | Tương tự |
+|------|------|---------|
+| **Working** | Observation thô từ việc dùng tool | Bộ nhớ ngắn hạn |
+| **Episodic** | Tóm tắt session đã nén | "Điều gì đã xảy ra" |
+| **Semantic** | Fact và pattern đã trích xuất | "Những gì tôi biết" |
+| **Procedural** | Workflow và pattern ra quyết định | "Cách làm việc đó" |
+
+Bộ nhớ suy giảm theo thời gian (đường cong Ebbinghaus). Bộ nhớ được truy cập thường xuyên sẽ mạnh lên. Bộ nhớ cũ sẽ tự bị loại bỏ. Các mâu thuẫn được phát hiện và giải quyết.
+
+### Những gì được capture
+
+| Hook | Capture gì |
+|------|----------|
+| `SessionStart` | Đường dẫn project, session ID |
+| `UserPromptSubmit` | Prompt của người dùng (đã lọc privacy) |
+| `PreToolUse` | Pattern truy cập file + context đã làm giàu |
+| `PostToolUse` | Tên tool, input, output |
+| `PostToolUseFailure` | Context lỗi |
+| `PreCompact` | Tiêm lại bộ nhớ trước khi compact |
+| `SubagentStart/Stop` | Lifecycle của sub-agent |
+| `Stop` | Tóm tắt cuối session |
+| `SessionEnd` | Dấu hiệu session hoàn tất |
+
+### Khả năng chính
+
+| Khả năng | Mô tả |
+|---|---|
+| **Capture tự động** | Mọi lần dùng tool đều được ghi lại qua hook, không cần thao tác thủ công |
+| **Tìm kiếm ngữ nghĩa** | BM25 + vector + knowledge graph với RRF fusion |
+| **Tiến hóa bộ nhớ** | Versioning, supersession, relationship graph |
+| **Vệ sinh recall** | Các phiên bản bộ nhớ đã bị supersede rời khỏi search index; chuỗi version trong KV giữ lại toàn bộ lịch sử |
+| **Gợi ý near-duplicate** | Khi lưu, hệ thống báo một match tư vấn `similarTo` khi nội dung mới gần giống một bộ nhớ đã có |
+| **Scoping theo từng agent** | `agentId` xuyên suốt qua save và recall trên REST, MCP, và search index, ở chế độ shared hoặc isolated |
+| **Provenance tại thời điểm ghi** | Mọi observation và memory đều mang một origin channel bất biến (user, agent, tool, import, hoặc shared) được đóng dấu lúc capture, save, và import |
+| **Tự quên** | Hết hạn TTL, phát hiện mâu thuẫn, loại bỏ theo độ quan trọng |
+| **Privacy là ưu tiên** | API key, secret, tag `` bị loại bỏ trước khi lưu trữ |
+| **Tự phục hồi** | Circuit breaker, chuỗi fallback provider, health monitoring |
+| **Claude bridge** | Đồng bộ hai chiều với MEMORY.md |
+| **Knowledge graph** | Trích xuất entity + duyệt BFS |
+| **Bộ nhớ nhóm** | Namespace chia sẻ + riêng tư giữa các thành viên trong team |
+| **Provenance trích dẫn** | Truy lại bất kỳ memory nào về đúng observation nguồn |
+| **Snapshot Git** | Version, rollback, và diff trạng thái bộ nhớ |
+
+---
+
+
+
+Retrieval ba luồng (triple-stream) kết hợp ba tín hiệu:
+
+| Luồng | Làm gì | Khi nào |
+|---|---|---|
+| **BM25** | Khớp từ khóa đã stem với mở rộng từ đồng nghĩa | Luôn bật |
+| **Vector** | Cosine similarity trên dense embedding | Khi embedding provider được cấu hình |
+| **Graph** | Duyệt knowledge graph qua khớp entity | Khi entity được phát hiện trong truy vấn |
+
+Được fuse bằng Reciprocal Rank Fusion (RRF, k=60) và đa dạng hóa theo session (tối đa 3 kết quả mỗi session).
+
+Khi vector index đã có dữ liệu, `mem::search` (đứng sau `memory_recall`) dùng ranker hybrid BM25 + vector. Khi không có embedding, nó dùng BM25. `smart-search` còn có thể fuse thêm các kết quả khớp từ graph cấu trúc khi dữ liệu graph tồn tại, kể cả ở chế độ keyless. Recall cho lesson chạy trên một BM25 index riêng trong memory thay vì quét toàn bộ corpus cho mỗi truy vấn. Các phiên bản memory đã bị supersede bị loại khỏi mọi đường recall; chuỗi version vẫn giữ lại lịch sử của chúng.
+
+Vector sống sót qua một lần crash hoặc force-kill. Vector index được lưu theo bucket, nhiều nhất là mỗi `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 phút). Mỗi vector được thêm hoặc xóa ở giữa cũng được ghi ngay vào một pending log nhỏ trong state store, và lần khởi động kế tiếp sẽ replay nó mà không cần gọi embedding provider. Mỗi lần save thành công sẽ làm trống log đó. Các document vẫn chưa có vector sau khi replay sẽ được re-embed ở nền theo từng batch `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) cho tới khi không còn document nào, và một backfill bị dừng sẽ tiếp tục ở lần khởi động kế tiếp. `/agentmemory/status` và viewer hiển thị kích thước pending log và trạng thái backfill. Bản cài keyless không ghi gì cả.
+
+BM25 tokenize được tiếng Hy Lạp, Cyrillic, Hebrew, Ả Rập, và Latin có dấu ngay từ đầu. Với bộ nhớ tiếng Trung / Nhật / Hàn, hãy cài thêm các segmenter tùy chọn (`npm install @node-rs/jieba tiny-segmenter`) để chia các đoạn CJK thành token ở mức từ; nếu không có chúng, agentmemory sẽ lùi nhẹ về tokenize theo cả đoạn và in ra một gợi ý một lần trên stderr.
+
+### Embedding provider
+
+Bản cài keyless tắt vector embedding: `mem::search` dùng BM25, trong khi `smart-search` cũng có thể dùng dữ liệu graph cấu trúc đã có. Để chủ động dùng embedding ngữ nghĩa miễn phí ngay trên máy, hãy thêm dòng này vào `~/.agentmemory/.env` và khởi động lại agentmemory:
+
+```env
+EMBEDDING_PROVIDER=local
+```
+
+Lần cài npm thông thường đã bao gồm runtime tùy chọn `@huggingface/transformers`. Request embedding đầu tiên sẽ tải `Xenova/all-MiniLM-L6-v2`, nên nó cần truy cập network và có thể mất lâu hơn; các lần inference sau đó chạy ngay trên máy. Các provider remote được tự phát hiện từ key của chúng trừ khi `EMBEDDING_PROVIDER` ghi đè lên.
+
+| Provider | Model | Chi phí | Ghi chú |
+|---|---|---|---|
+| **Local (khuyến nghị opt-in)** | `all-MiniLM-L6-v2` | Miễn phí | Chạy trên máy sau lần tải model đầu tiên, +8pp recall so với chỉ dùng BM25 |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ ngôn ngữ, 768/1536/3072 chiều (MRL), input 2048 token. Thay thế `text-embedding-004` ([đã deprecated, shutdown 14/01/2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
+| OpenAI | `text-embedding-3-small` | $0.02/1M | Chất lượng cao nhất |
+| Voyage AI | `voyage-code-3` | Trả phí | Tối ưu cho code |
+| Cohere | `embed-english-v3.0` | Free trial | Dùng chung (general purpose) |
+| OpenRouter | Bất kỳ model nào | Thay đổi | Proxy đa model |
+
+---
+
+
+
+54 tool, 6 resource, 3 prompt, và 17 skill.
+
+> **MCP shim so với server đầy đủ:** package `@agentmemory/mcp` đã publish là một shim mỏng. Nó chỉ phơi ra toàn bộ 54 tool **khi nó có thể chạm tới một agentmemory server đang chạy** qua `AGENTMEMORY_URL` (chế độ proxy). Khi không có server nào tiếp cận được, shim sẽ lùi về một bộ 7 tool cục bộ (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). Biến môi trường `AGENTMEMORY_TOOLS=core|all` là một flag *phía server*; đặt nó trong block `env` của shim không có tác dụng gì. Nếu bạn chỉ thấy 7 tool trong Cursor / OpenCode / Gemini CLI, hãy khởi động `npx -y @agentmemory/agentmemory@latest` (hoặc Docker stack) và đặt `AGENTMEMORY_URL=http://localhost:3111`.
+
+### 54 Tool
+
+Ba mức hiển thị tool, từ nhỏ tới lớn: `AGENTMEMORY_TOOLS=core` thu hẹp hiển thị xuống 8 tool thiết yếu (`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`); bộ cơ bản dưới đây là 14 tool nền tảng của registry; mặc định (`AGENTMEMORY_TOOLS=all`) phơi ra toàn bộ 54 tool.
+
+
+Tool cơ bản (14)
+
+| Tool | Mô tả |
+|------|-------------|
+| `memory_recall` | Tìm kiếm các observation trước đây |
+| `memory_compress_file` | Nén file markdown mà vẫn giữ nguyên cấu trúc |
+| `memory_save` | Lưu một insight, quyết định, hoặc pattern |
+| `memory_file_history` | Các observation trước đây về file cụ thể |
+| `memory_patterns` | Phát hiện pattern lặp lại |
+| `memory_sessions` | Liệt kê session gần đây |
+| `memory_smart_search` | Tìm kiếm hybrid semantic + từ khóa |
+| `memory_vision_search` | Tìm kiếm observation dạng ảnh |
+| `memory_timeline` | Observation theo trình tự thời gian |
+| `memory_profile` | Hồ sơ project (concept, file, pattern) |
+| `memory_export` | Export toàn bộ dữ liệu memory |
+| `memory_relations` | Truy vấn relationship graph |
+| `memory_commit_lookup` | Các session đứng sau một git commit |
+| `memory_commits` | Các commit được ghi lại cho một session |
+
+
+
+
+Tool mở rộng (tổng 54, mức hiển thị mặc định)
+
+| Tool | Mô tả |
+|------|-------------|
+| `memory_patterns` | Phát hiện pattern lặp lại |
+| `memory_timeline` | Observation theo trình tự thời gian |
+| `memory_relations` | Truy vấn relationship graph |
+| `memory_graph_query` | Duyệt knowledge graph |
+| `memory_consolidate` | Chạy hợp nhất 4 tầng |
+| `memory_claude_bridge_sync` | Đồng bộ với MEMORY.md |
+| `memory_team_share` | Chia sẻ với thành viên team |
+| `memory_team_feed` | Các item đã chia sẻ gần đây |
+| `memory_audit` | Audit trail các operation |
+| `memory_governance_delete` | Xóa có kèm audit trail |
+| `memory_snapshot_create` | Snapshot có version Git |
+| `memory_action_create` | Tạo work item kèm dependency |
+| `memory_action_update` | Cập nhật trạng thái action |
+| `memory_frontier` | Các action chưa bị block, xếp theo độ ưu tiên |
+| `memory_next` | Action kế tiếp quan trọng nhất |
+| `memory_lease` | Lease độc quyền cho action (đa agent) |
+| `memory_routine_run` | Khởi tạo instance cho workflow routine |
+| `memory_signal_send` | Gửi message giữa các agent |
+| `memory_signal_read` | Đọc message kèm receipt |
+| `memory_checkpoint` | Gate theo điều kiện bên ngoài |
+| `memory_mesh_sync` | Đồng bộ P2P giữa các instance |
+| `memory_sentinel_create` | Watcher theo event |
+| `memory_sentinel_trigger` | Kích hoạt sentinel từ bên ngoài |
+| `memory_sketch_create` | Action graph tạm (ephemeral) |
+| `memory_sketch_promote` | Nâng lên vĩnh viễn |
+| `memory_crystallize` | Nén các action chain |
+| `memory_diagnose` | Kiểm tra sức khỏe |
+| `memory_heal` | Tự sửa trạng thái bị kẹt |
+| `memory_facet_tag` | Tag dạng dimension:value |
+| `memory_facet_query` | Truy vấn theo facet tag |
+| `memory_verify` | Truy lại provenance |
+
+
+
+### 6 Resource · 3 Prompt · 17 Skill
+
+| Loại | Tên | Mô tả |
+|------|------|-------------|
+| Resource | `agentmemory://status` | Health, số session, số memory |
+| Resource | `agentmemory://project/{name}/profile` | Intelligence theo từng project |
+| Resource | `agentmemory://project/{name}/recent` | Observation gần đây cho một project |
+| Resource | `agentmemory://memories/latest` | 10 memory active mới nhất |
+| Resource | `agentmemory://graph/stats` | Thống kê knowledge graph |
+| Resource | `agentmemory://team/{id}/profile` | Hồ sơ team được chia sẻ |
+| Prompt | `recall_context` | Tìm kiếm + trả về các context message |
+| Prompt | `session_handoff` | Dữ liệu handoff giữa các agent |
+| Prompt | `detect_patterns` | Phân tích pattern lặp lại |
+| Skill | `/recall` | Tìm kiếm memory |
+| Skill | `/remember` | Lưu vào bộ nhớ dài hạn |
+| Skill | `/session-history` | Tóm tắt các session gần đây |
+| Skill | `/forget` | Xóa observation/session |
+
+Bảng này chỉ hiển thị 4 skill cốt lõi. Bộ đầy đủ gồm 9 skill có thể gọi cộng 8 skill tham chiếu; xem phần Skill gốc ở trên.
+
+### MCP độc lập
+
+Chạy mà không cần server đầy đủ, cho bất kỳ MCP client nào. Một trong hai cách này đều được:
+
+```bash
+npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
+npx -y @agentmemory/mcp # shim package alias
+```
+
+Hoặc thêm vào config MCP của agent của bạn:
+
+Hầu hết các agent (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+```json
+{
+ "mcpServers": {
+ "agentmemory": {
+ "command": "npx",
+ "args": ["-y", "@agentmemory/mcp"],
+ "env": {
+ "AGENTMEMORY_URL": "http://localhost:3111"
+ }
+ }
+ }
+}
+```
+
+Gộp entry `agentmemory` vào object `mcpServers` đã có của host thay vì thay thế toàn bộ file. Với các client chạy sandbox không chạm tới `localhost` của host, thêm `"AGENTMEMORY_FORCE_PROXY": "1"` vào block env và đặt `AGENTMEMORY_URL` tới một route mà sandbox chạm tới được.
+
+OpenCode (`opencode.json`):
+```json
+{
+ "mcp": {
+ "agentmemory": {
+ "type": "local",
+ "command": ["npx", "-y", "@agentmemory/mcp"],
+ "enabled": true
+ }
+ },
+ "plugin": ["./plugins/agentmemory-capture.ts"]
+}
+```
+
+Copy file plugin từ repo:
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
+cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
+```
+
+---
+
+
+
+Tự khởi động trên port `3113`. Viewer nạp một snapshot khi nó kết nối (`GET /agentmemory/viewer/snapshot`) rồi áp các event từ live stream: memory mới, lesson, observation, audit entry, thay đổi graph và cập nhật health xuất hiện mà không cần polling hay reload trang. Các request khác duy nhất là những action bạn click, các trang "load more" và tìm kiếm. Khi stream rớt, viewer hiển thị số liệu của nó đã cũ bao lâu, kết nối lại với backoff và resync từ một snapshot.
+
+- **12 tab trong bốn nhóm** với số liệu live, deep link (`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), phím tắt và menu cho mobile.
+- **Memories:** tìm kiếm phía server, filter theo project, agent và type, một panel chi tiết với chuỗi version và word diff, link provenance, nút copy cho id, lệnh gọi MCP và một lệnh curl, edit (tạo version mới), forget có xác nhận, forget theo lô và export JSON.
+- **Sessions:** một timeline observation nội tuyến với input/output tool dễ đọc, filter và phân trang, cùng các memory và lesson mà mỗi session tạo ra.
+- **Graph:** tìm kiếm, chi tiết node với relation và nguồn, một legend không chỉ dựa vào màu sắc, và điều khiển zoom.
+- **Health:** phiên bản live của `GET /agentmemory/status`. Mỗi vấn đề đều kèm cách khắc phục, cộng với state backend, trạng thái lưu index, tiến độ compact provenance của graph và một phần giải thích consolidation với các ngưỡng thực tế.
+- Các trang **Audit, Activity, Profile, Replay, Lessons, Actions và Crystals**, mỗi trang có một empty state nói rõ phần đó là gì, vì sao nó đang rỗng và lệnh nào sẽ lấp đầy nó, cùng một tooltip glossary `?` trên mỗi thuật ngữ và số liệu.
+
+```bash
+open http://localhost:3113
+```
+
+Viewer server bind vào `127.0.0.1` theo mặc định và gắn kèm server secret khi nó forward request tới REST API, nên nó không cần setup gì thêm. Endpoint `/agentmemory/viewer` được REST phục vụ tuân theo quy tắc bearer-token bình thường và redirect các browser không có token tới port của viewer. Header CSP dùng một script nonce theo từng response và tắt các inline handler attribute (`script-src-attr 'none'`).
+
+---
+
+
+
+Viewer tại `:3113` cho thấy những gì agent của bạn **đã ghi nhớ**. [iii console](https://iii.dev/docs/console) cho thấy những gì agent của bạn **đã làm**: mọi memory op dưới dạng một OpenTelemetry trace, mọi KV entry có thể sửa, mọi function có thể gọi, mọi stream có thể lắng nghe. Hai cửa sổ trên cùng một bộ nhớ: một có hình dạng product, một có hình dạng engine.
+
+Xem một `memory_smart_search` được bắn ra và theo dõi BM25 scan → embedding lookup → RRF fusion → reranker dưới dạng một waterfall. Sửa một consolidation timer bị kẹt trong KV browser. Replay một hook `PostToolUse` với payload đã chỉnh. Pin WebSocket stream và xem observation đổ vào theo thời gian thực.
+
+agentmemory có sẵn thứ này miễn phí vì mọi function call và trigger đều bắn qua iii; không có gì custom, không có gì cần instrument.
+
+
+
+
+ Trang Workers: mọi worker đã kết nối, kể cả agentmemory, với PID, số function, runtime, và lần thấy cuối.
+
+
+**Đã được cài sẵn.** Console đi kèm với `iii` engine đã pin (0.22+); không có gì riêng cần cài thêm. Lần khởi chạy đầu tiên sẽ tải binary console nằm cạnh engine.
+
+**Khởi chạy cùng với agentmemory:**
+
+```bash
+agentmemory console
+```
+
+Lệnh này chạy `iii console` của engine đã pin dựa trên các port mà agentmemory đã resolve (REST, stream, bridge) và phục vụ nó ở một port cao hơn viewer một đơn vị, mặc định là `http://localhost:3114`. `--console-port N` chọn một port khác; `--port` và `--instance` chọn instance agentmemory giống như cách chúng làm với `stop`; mọi flag khác được truyền thẳng qua, ví dụ `--enable-flow` cho trang architecture-graph thử nghiệm.
+
+Làm tương tự bằng tay, hữu ích khi `agentmemory` không có trong PATH:
+
+```bash
+~/.agentmemory/bin/iii console --port 3114 \
+ --engine-port 3111 \
+ --ws-port 3112 \
+ --bridge-port 49134
+```
+
+**Những gì bạn có thể làm từ console:**
+
+| Trang | Dùng để |
+|------|-----------|
+| **Workers** | Xem mọi worker đã kết nối và metric live của nó, kể cả worker agentmemory. |
+| **Functions** | Gọi trực tiếp bất kỳ function nào của agentmemory bằng một JSON payload; tiện để test `memory.recall`, `memory.consolidate`, `graph.query` mà không cần kết nối một client. |
+| **Triggers** | Replay trigger HTTP, cron, event, và state: bắn cron consolidation thủ công, retry một route HTTP, phát một thay đổi state. |
+| **States** | KV browser với CRUD đầy đủ trên session, memory slot, timer lifecycle, và embedding index; sửa giá trị ngay tại chỗ. |
+| **Streams** | Monitor WebSocket live cho các lần write memory, event hook, và cập nhật observation khi chúng chảy qua iii stream. |
+| **Queues** | Topic queue bền vững + quản lý dead-letter. Replay hoặc drop các job embedding / compression bị lỗi. |
+| **Traces** | Các view waterfall / flame / service-breakdown của OpenTelemetry. Filter theo `trace_id` để xem chính xác những function, lệnh gọi DB, và request embedding mà một `memory.search` đã tạo ra. |
+| **Logs** | Log OTEL có cấu trúc, được filter và liên kết tới trace/span ID. |
+| **Config** | Cấu hình runtime: xem chính xác engine của bạn đang chạy với worker, provider, và port nào. |
+| **Flow** | (Tùy chọn, `--enable-flow`) Đồ thị architecture tương tác của mọi worker, trigger, và stream. |
+
+
+
+
+ Traces: waterfall / flame / service breakdown cho mọi memory operation.
+
+
+**Trace đã được bật sẵn:**
+
+`iii-config.yaml` đi kèm với worker `iii-observability` đã được bật (`exporter: memory`, `sampling_ratio: 0.1`, metric + log). Không cần config gì thêm; ngay khi agentmemory khởi động, mọi memory operation sẽ phát ra một log có cấu trúc mà console đọc được, và một trong mười lần (`sampling_ratio: 0.1`) cũng sẽ phát ra một trace span.
+
+Nếu bạn muốn export sang Jaeger/Honeycomb/Grafana Tempo thay vào đó, đổi `exporter: memory` thành `exporter: otlp` và đặt collector endpoint theo docs observability của iii.
+
+> **Lưu ý:** console bản thân nó không ép buộc auth; hãy giữ nó bind vào `127.0.0.1` (mặc định) và không bao giờ expose nó ra công khai.
+
+---
+
+
+
+agentmemory **đã sẵn là một instance [iii](https://iii.dev) đang chạy**. Ba primitive (worker, function, trigger) tạo nên runtime; KV state, stream, và OTEL trace đến từ các worker iii-state, iii-stream, và iii-observability đi kèm với iii. Bạn không hề cài Postgres, Redis, Express, pm2, hay Prometheus, vì iii đã thay thế chúng.
+
+Điều đó có nghĩa là chỉ cần thêm một lệnh nữa là mở rộng agentmemory với toàn bộ một khả năng mới.
+
+### Mở rộng agentmemory với nhiều worker hơn
+
+Các builtin mà agentmemory cần đã có sẵn trong `iii-config.yaml` và khởi động cùng nó: `iii-state` (KV), `iii-queue` (retry bền vững cho các subscriber event), `iii-pubsub`, `iii-cron`, `iii-stream`, và `iii-observability` (trace, metric và log OTEL trên mọi function). Bất cứ thứ gì khác từ [iii worker registry](https://workers.iii.dev) đều cắm vào cùng engine: copy `iii-config.yaml` vào `~/.agentmemory/iii-config.yaml` (CLI ưu tiên file đó hơn file đi kèm và vẫn render port cùng data path vào đó), thêm entry, cài worker runtime một lần với `~/.agentmemory/bin/iii update worker`, và khởi động lại agentmemory.
+
+```yaml
+workers:
+ # ...the bundled entries...
+ - name: database # SQL-backed state adapter when you outgrow the KV defaults
+ - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
+ - name: mcp # extra MCP servers next to agentmemory's, same engine
+```
+
+| Worker | Bạn có thêm gì trên nền agentmemory |
+|---|---|
+| [`database`](https://workers.iii.dev/workers/database) | Adapter state dựa trên SQL khi bạn vượt quá giới hạn của KV mặc định |
+| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Code lấy ra từ `memory_recall` chạy trong một VM dùng một lần, không chạy trên shell của bạn |
+| [`mcp`](https://workers.iii.dev/workers/mcp) | Dựng thêm các MCP server cạnh server của agentmemory, chia sẻ cùng engine |
+
+Trên engine 0.22.x, hãy giữ các tên có tiền tố `iii-` cho các builtin ở trên; các entry không có tiền tố `http`, `state`, `queue`, `pubsub` và `cron` là các worker registry độc lập mà agentmemory sẽ chuyển sang khi migration lên 0.23.
+
+Registry đầy đủ: [workers.iii.dev](https://workers.iii.dev). Mọi worker ở đó đều compose qua đúng những primitive mà agentmemory dùng, và agentmemory mà bạn đang có chính là một trong số đó.
+
+### Config engine và bind address
+
+`agentmemory start` đọc config engine từ file đầu tiên tồn tại: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` trong thư mục hiện tại, `~/.agentmemory/iii-config.yaml`, rồi tới `iii-config.yaml` đi kèm. Ở mỗi lần khởi động, nó render file đó (data path, port, state backend) vào `~/.agentmemory/data/iii-config.runtime.yaml` và khởi chạy engine với bản đã render, nên hãy sửa file nguồn, không phải file đã render. Các giá trị `host:` của file nguồn được giữ nguyên như đã viết.
+
+`iii-config.yaml` đi kèm bind `127.0.0.1` một cách có chủ đích, và giá trị mặc định đó cũng áp dụng bên trong container. Một CLI khởi động trong container sẽ lắng nghe trên loopback của container đó, nên các port đã publish không chạm tới gì cả. Để phục vụ một CLI chạy trong container qua các port đã publish, hãy đặt `AGENTMEMORY_III_CONFIG` tới một config bind `0.0.0.0`. `iii-config.docker.yaml` đi kèm sẵn là một ví dụ như vậy: nó bind `iii-http`, `iii-stream` và port engine vào `0.0.0.0` và lưu state dưới `/data`, nên hãy mount một volume ghi được ở đó. Giữ `AGENTMEMORY_SECRET` luôn được đặt, và chỉ publish những port bạn cần, trên `127.0.0.1` hoặc sau một proxy bạn tin tưởng.
+
+`docker-compose.yml` của repo này không đi qua cơ chế dò tìm config của CLI: nó mount `iii-config.docker.yaml` vào `/app/config.yaml`, và container `iii-engine` khởi động với `--config /app/config.yaml`. Các [deploy template](../deploy/) one-click tự viết config `0.0.0.0` riêng của chúng trong entrypoint.
+
+### Storage backend: file (mặc định) so với redis
+
+`iii-state` và `iii-stream` mặc định dùng KV store dựa trên file đi kèm của iii-engine: một file JSON cho mỗi scope, giữ trong memory của process engine và được viết lại ra disk theo timer. Đó là mặc định đúng cho một bản cài cục bộ, một người dùng; một daemon chia sẻ với nhiều writer đồng thời sẽ nhận được các lần write theo từng key thật từ Redis thay vào đó, với chi phí là một round-trip network cho mỗi operation (mỗi lệnh `state::*` vẫn serialize trên một kết nối Redis, nên điều này đổi lock của file store thành một socket, không phải đổi lấy khả năng chạy song song).
+
+Đặt `AGENTMEMORY_STATE_BACKEND=redis` (cùng `AGENTMEMORY_REDIS_URL`) để chuyển cả hai worker sang adapter `redis` tích hợp sẵn của iii-engine, adapter này lưu mỗi key như một hash field Redis (`HSET`) thay vì viết lại cả một scope ở mỗi lần write:
+
+```env
+# ~/.agentmemory/.env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379
+```
+
+`AGENTMEMORY_STATE_BACKEND` mặc định là `file`; để trống nó giữ nguyên hành vi hiện tại, và một giá trị không nhận diện được (bất cứ gì khác `file` hoặc `redis`) sẽ là một lỗi khởi động chứ không phải fallback im lặng. `/agentmemory/status` và trang Health của viewer (dòng State store) báo backend nào đang active và nó có trả lời hay không, không bao giờ báo URL.
+
+**Chỉ `redis://` thuần.** Engine đã pin (0.22.1) build Redis client của nó không có hỗ trợ TLS, nên một URL `rediss://` (hầu hết các dịch vụ Redis được quản lý, như Upstash, Redis Cloud, và ElastiCache có mã hóa in-transit, mặc định chỉ dùng TLS) sẽ không kết nối được. Kết nối không được mã hóa, nên password Redis và mọi memory đã lưu đi qua đường truyền ở dạng clear text: hãy chỉ tới một Redis cục bộ hoặc một Redis trên network riêng mà bạn tin tưởng. Với bất kỳ Redis nào khác, hãy chạy một tunnel được mã hóa (stunnel, SSH, hoặc một VPN) trên host agentmemory, để chặng `redis://` thuần nằm trên host đó và kết nối upstream của tunnel được mã hóa và xác thực. Nếu password Redis chứa một dấu nháy đơn, hãy percent-encode nó (`%27`); engine mở rộng URL vào config YAML của nó trước khi parse.
+
+**Một Redis server cho mỗi `--instance`.** Các prefix key Redis của engine (`state:`, `stream::`) là cố định, nên hai instance agentmemory (`--instance 1`, `--instance 2`, ...) cùng chỉ vào một database sẽ ghi đè dữ liệu của nhau. Một database index riêng (`redis://localhost:6379/1`) giữ dữ liệu đã lưu tách biệt, nhưng engine relay các event viewer live qua một channel pub/sub Redis duy nhất (`stream::events`), và Redis pub/sub bỏ qua database index, nên viewer của mỗi instance vẫn sẽ hiển thị event live của instance khác. Hãy cho mỗi instance một Redis server (hoặc port) riêng khi bạn chạy nhiều hơn một.
+
+**Điều gì giữ nguyên, và điều gì khác đi.** Mọi tính năng agentmemory đều hoạt động trên Redis: session, observation, memory (remember, supersede, evolve, forget), search và các bucket index, lesson, graph, audit log cùng các scope theo tháng của nó, export và import, governance delete, trạng thái consolidation, snapshot của viewer và live stream của nó, và health monitor. Engine lưu mỗi scope thành một hash Redis (`HSET`/`HGET`/`HGETALL`) và bắn ra cùng các state trigger như file store. Ba khác biệt của engine được xử lý ngay trong agentmemory:
+
+- Redis trả về các record của một scope không theo thứ tự cố định. agentmemory sắp xếp chúng theo cũ nhất trước (theo thời gian tạo trong id của record, sau đó theo timestamp) để các list, phân trang và các chunk export trả về đúng thứ tự giống như trên file store.
+- Engine áp các update một phần trên Redis trong một Lua script biến array rỗng thành object rỗng. agentmemory tự áp các update đó (read, change, write dưới một lock theo từng key) trên Redis, nên các field như `tags: []` vẫn giữ là array.
+- Kiểm tra audit log kiểu cũ đọc scope cũ từ Redis thay vì tìm file của file store trên disk.
+
+Có một khác biệt cần bạn can thiệp: **sau khi Redis khởi động lại, engine dừng relay các event live** tới viewer cho tới khi agentmemory khởi động lại. Dữ liệu vẫn được lưu và đọc bình thường. Health monitor gửi một event test qua Redis mỗi 30 giây; khi nó không nhận lại được, `/agentmemory/status` và trang Health của viewer sẽ hiện "Live updates are not reaching the viewer" kèm cách khắc phục: khởi động lại agentmemory. Nếu Redis down, báo cáo status sẽ hiện "The state store is not answering" và cách kiểm tra nó (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). Liệt kê một scope rất lớn sẽ đọc toàn bộ hash trong một lệnh `HGETALL`, cùng chi phí như khi file store giữ nó trong memory.
+
+**Cấu hình Redis được khuyến nghị.** Chính sách snapshot mặc định `save 3600 1 300 100 60 10000` có thể mất vài phút write khi crash, tệ hơn cửa sổ flush 5 giây của file store. Đặt `appendonly yes` cho bất cứ thứ gì bạn không muốn mất. Đặt `maxmemory-policy noeviction`; `allkeys-lru` hoặc tương tự sẽ lặng lẽ drop memory ngay khi Redis chạm giới hạn memory của nó.
+
+Một lần khởi động native (không Docker), và mọi [deploy template](../deploy/) one-click (chúng ghi đè `iii-config.yaml` đi kèm và khởi động native), đọc `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` và render chúng vào `iii-config` được khởi chạy. URL bản thân nó không bao giờ được viết vào file đã render đó, chỉ có một tham chiếu `${AGENTMEMORY_REDIS_URL}` mà process engine mở rộng từ environment riêng của nó khi boot. Chỉ có đường Docker Compose riêng của repo này (`AGENTMEMORY_USE_DOCKER=1`, hoặc resume một engine đã khởi động theo cách đó) mount `iii-config.docker.yaml` chỉ đọc và không bao giờ render; `agentmemory start` sẽ cảnh báo khi nó phát hiện tổ hợp đó. Hãy đổi file đó bằng tay, theo đúng hình thái `name: redis` / `config: redis_url: ...` được trình bày trong docs worker [iii-state](https://workers.iii.dev/workers/iii-state) và [iii-stream](https://workers.iii.dev/workers/iii-stream), và chỉ `redis_url` tới một Redis mà container chạm tới được. `docker-compose.yml` truyền `AGENTMEMORY_REDIS_URL` vào container engine, nên `redis_url: '${AGENTMEMORY_REDIS_URL}'` hoạt động ở đó và giữ URL ngoài file đã mount.
+
+Config đã render giữ URL ngoài `~/.agentmemory/data/iii-config.runtime.yaml`, nhưng configuration worker của chính engine vẫn persist giá trị *đã mở rộng* vào `~/.agentmemory/config/iii-state.yaml` và `iii-stream.yaml` ngay khi nó boot (việc mở rộng `${VAR}` của iii-engine xảy ra trước khi worker đó lưu seed của nó, và nó lưu giá trị đã resolve, không phải tham chiếu). Hãy coi thư mục đó như đang giữ một credential: `chmod 700 ~/.agentmemory` trên bất kỳ host chia sẻ nào, và ưu tiên một user ACL Redis chỉ có quyền đúng những gì agentmemory cần hơn là dùng credential admin của database.
+
+**Migration không tự động.** Chuyển `AGENTMEMORY_STATE_BACKEND` bắt đầu từ một store trống ở cả hai phía; không có gì tự copy dữ liệu đã có từ file sang Redis hay ngược lại. Export từ backend bạn đang rời khỏi và import vào backend bạn đang chuyển tới. Đoạn này chạy giống nhau trên cả bash và zsh (kể cả `bash -u`). Một array như `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` thì không: zsh giữ header đó như một từ bị hỏng trong khi bash tách nó thành hai, nên cả hai request đều 401 bất cứ khi nào `AGENTMEMORY_SECRET` được đặt:
+
+```bash
+# 0. Use the generated secret when none is exported:
+AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
+
+# 1. On the old backend, while agentmemory is still running on it:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
+else
+ curl -fsS http://localhost:3111/agentmemory/export > backup.json
+fi
+
+# 2. Confirm backup.json is a usable export before switching backends:
+jq -e '.version and .exportedAt' backup.json > /dev/null || {
+ echo "backup.json is not a valid export; do not switch backends" >&2
+ exit 1
+}
+
+# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
+# restart agentmemory against the new backend, then:
+if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+else
+ jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
+ curl -fsS -X POST http://localhost:3111/agentmemory/import \
+ -H 'Content-Type: application/json' -d @-
+fi
+```
+
+`/agentmemory/export` cũng nhận `?maxSessions=` và `?offset=` để chia nhỏ một corpus lớn qua nhiều lệnh gọi; `strategy` khi import là `merge` (an toàn theo mặc định), `replace`, hoặc `skip`.
+
+### iii thay thế cho những gì
+
+| Stack truyền thống | agentmemory dùng |
+|---|---|
+| Express.js / Fastify | iii HTTP Triggers |
+| SQLite / Postgres + pgvector | iii KV State + vector index trong memory |
+| SSE / Socket.io | iii Streams (WebSocket) |
+| pm2 / systemd | iii engine worker supervision |
+| Prometheus / Grafana | iii OTEL + health monitor |
+| Hệ thống plugin tùy chỉnh | `iii worker add ` |
+
+**225 file source · ~54,000 LOC · 2,600+ test · 312 function · 66 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
+
+---
+
+
+
+### LLM Provider
+
+agentmemory tự phát hiện provider từ environment của bạn. Một provider làm cho các operation dựa trên LLM khả dụng, nhưng chỉ cấu hình provider thôi không kích hoạt việc nén observation do LLM viết. Đường đó cần cả provider và `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+| Provider | Config | Ghi chú |
+|----------|--------|-------|
+| **No-op (mặc định)** | Không cần config | Compress/summarize dựa trên LLM bị tắt. Nén synthetic và recall BM25 vẫn hoạt động. Xem `AGENTMEMORY_ALLOW_AGENT_SDK` dưới đây nếu bạn từng dựa vào fallback Claude-subscription. |
+| Anthropic API | `ANTHROPIC_API_KEY` | Tính phí theo token |
+| MiniMax | `MINIMAX_API_KEY` | Tương thích Anthropic |
+| Gemini | `GEMINI_API_KEY` | Cũng kích hoạt embedding |
+| OpenRouter | `OPENROUTER_API_KEY` | Bất kỳ model nào |
+| OpenAI API | `OPENAI_API_KEY` | Mặc định `gpt-5.6-luna`, ghi đè bằng `OPENAI_MODEL` |
+| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) hoặc `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | Bất cứ gì tương thích OpenAI-API. Không tốn phí, chạy trên hardware của bạn. Xem [Model cục bộ](#local-models-ollama--lm-studio--vllm) dưới đây. |
+| Fallback Claude subscription | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Chỉ opt-in. Spawn các session `@anthropic-ai/claude-agent-sdk`; trước đây nó từng gây ra đệ quy Stop-hook không giới hạn, nên nó không còn là mặc định. |
+
+### Model cục bộ (Ollama / LM Studio / vLLM)
+
+agentmemory nói chuyện với bất kỳ server tương thích OpenAI-API nào, nên bất cứ gì phơi ra `/v1/chat/completions` đều hoạt động mà không cần sửa code. Không key trả phí, không cloud, không rate limit; chạy hoàn toàn trên hardware của bạn.
+
+**Ollama** (port mặc định `11434`):
+
+```bash
+ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
+ollama serve
+```
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen3:8b
+```
+
+**LM Studio** (port mặc định `1234`):
+
+Mở LM Studio → tab Local Server → Start Server. Chọn bất kỳ chat model nào trong bộ chọn (Qwen 3, gpt-oss, DeepSeek R1, v.v.).
+
+```env
+# ~/.agentmemory/.env
+OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
+OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
+```
+
+**vLLM / llama.cpp / Text Generation Inference**: cùng hình thái. Chỉ `OPENAI_BASE_URL` tới bất kỳ URL mà server của bạn phơi ra và đặt `OPENAI_MODEL` thành một tên mà server của bạn chấp nhận.
+
+**Chọn model cho công việc memory**: compression và summarization là các task ngắn (<2K token vào, <500 token ra) nơi một model instruct 7B là đủ dư. Khuyến nghị:
+
+| Model | Size | Vì sao |
+|-------|------|-----|
+| `qwen3:8b` | ~5.2 GB | Mặc định cân bằng trên máy 16 GB; mạnh ở extraction và text dạng tool |
+| `qwen3:4b` | ~2.6 GB | Lựa chọn nhỏ nhất còn hợp lý; ổn cho compression, yếu hơn ở graph extraction |
+| `qwen3-coder:30b` | ~19 GB | Lựa chọn local tốt nhất cho session dạng code (30B MoE, 3.3B active) trên hardware 24-32 GB |
+| `gpt-oss:20b` | ~14 GB | Model tổng quát mạnh, vừa với 16 GB RAM |
+| `deepseek-r1:8b` | ~5.2 GB | Reasoning distill; chậm hơn nhưng extraction sạch hơn |
+
+Các model Qwen 3 mặc định có suy nghĩ (think) và có thể đốt hết toàn bộ token budget vào reasoning trước khi có bất kỳ output nào. Đặt `AGENTMEMORY_LLM_NOTHINK=1` để thêm `/no_think` vào các prompt graph-extraction, và tăng `MAX_TOKENS` (16384 là ổn) nếu extraction trả về rỗng.
+
+Các model dạng reasoning (kiểu `o1` với block ``) có thể trả về `content` rỗng cùng một field `reasoning` mà server local của bạn có thể không phơi ra. Nếu extraction trả về trống, hãy chuyển sang một model non-reasoning trước. Biến env `OPENAI_REASONING_EFFORT=none` cũng có thể tắt thinking trên các model thinking của Ollama Cloud vốn mirror schema reasoning của OpenAI.
+
+Embedding cục bộ đi kèm như một dependency tùy chọn nhưng không được bật theo mặc định. Đặt `EMBEDDING_PROVIDER=local` để chủ động dùng `Xenova/all-MiniLM-L6-v2` (384 chiều). Request embedding đầu tiên sẽ tải model; inference chạy trên máy sau đó. Nếu không có setting đó hoặc một key embedding remote, vector vẫn bị tắt, `mem::search` dùng BM25, và `smart-search` vẫn có thể thêm các kết quả khớp graph đã có.
+
+### Chọn model theo chi phí
+
+Khi compression nền do LLM viết được bật với cả provider và `AGENTMEMORY_AUTO_COMPRESS=true`, nó chạy trên mọi observation, nên việc chọn model thay đổi đáng kể chi phí hàng tháng. Dữ liệu workload đã ghi lại: 635 request / 888K token / 35 giờ sử dụng active, chạy trên ba model OpenRouter theo giá ngày 2026-05-23.
+
+| Tier | Model | Input / 1M | Output / 1M | Chi phí cho 35h đã ghi lại | Ghi chú |
+|------|-------|------------|-------------|---------------------------|-------|
+| Khuyến nghị | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (ước tính) | DeepSeek mới nhất; lựa chọn rẻ nhất được khuyến nghị cho workload compression. |
+| Khuyến nghị | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Chất lượng compression + summarization tốt với chi phí thấp hơn Sonnet ~10 lần. |
+| Khuyến nghị | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Reasoning về code mạnh nếu session của bạn nặng về code. |
+| Cao cấp | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (ước tính) | Giá niêm yết giống với lần chạy Sonnet 4.6 đã đo; giá giới thiệu $2/$10 cho tới 2026-08-31. |
+| Cao cấp | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (ước tính) | Tier flagship; đắt cho công việc nền chạy liên tục. |
+| Nên tránh | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (ước tính) | Model lớp flagship; vượt chi phí cho compression. |
+
+Các dòng đã đo đến từ lần chạy đã ghi lại; các dòng (ước tính) scale cùng tỷ lệ token theo giá niêm yết của từng model.
+
+agentmemory in ra một cảnh báo runtime khi `OPENROUTER_MODEL` khớp với pattern tier cao cấp. Đặt `AGENTMEMORY_SUPPRESS_COST_WARNING=1` để tắt tiếng khi bạn đã đưa ra lựa chọn có hiểu biết.
+
+Đánh đổi chất lượng so với chi phí cho công việc memory: compression là một task summarization với ngưỡng chất lượng tương đối thoải mái (agent đọc lại summary, không phải người dùng). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder gần như ngang Sonnet trên task này (chỉ lệch trong sai số làm tròn) trong khi tốn ít hơn 10-70 lần. Hãy dành các model tier cao cấp cho những truy vấn bạn tự đọc trực tiếp.
+
+Nguồn: [giá OpenRouter cho Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [ghi chú giá DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/).
+
+### Bộ nhớ đa agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
+
+Trong các thiết lập đa agent nơi nhiều role chia sẻ một agentmemory server (architect / developer / reviewer / researcher / support-agent), `AGENT_ID` gắn tag cho mỗi lần write với role đã tạo ra nó. `AGENTMEMORY_AGENT_SCOPE` kiểm soát việc recall có filter theo tag đó hay không.
+
+```env
+TEAM_ID=company
+USER_ID=engineering-team
+AGENT_ID=architect
+AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
+```
+
+Hai chế độ:
+
+| Chế độ | Tag write | Filter recall | Khi nào dùng |
+|------|------------|---------------|-------------|
+| `shared` (mặc định) | có | không | Context chia sẻ giữa các agent kèm audit trail. Architect có thể thấy những gì developer ghi chú, nhưng mỗi row đều ghi lại ai đã nói điều đó. |
+| `isolated` | có | có | Tách biệt nghiêm ngặt. Architect không bao giờ thấy observation / memory / session của developer. |
+
+Những gì bị tag khi `AGENT_ID` được đặt: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. Role này chảy từ `api::session::start` → `mem::observe` → `mem::compress` → KV.
+
+Những gì bị filter ở chế độ isolated: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. Mỗi endpoint nhận `?agentId=` để ghi đè theo từng request, và `?agentId=*` để bỏ qua scope env hoàn toàn. `/memories` cũng nhận `?includeOrphans=true` để lấy ra các memory từ trước khi có AGENT_ID, có `agentId` là undefined.
+
+Ghi đè theo từng lệnh gọi ở tầng SDK / REST: mọi endpoint mutating (`/session/start`, `/remember`) nhận một field `agentId` trong request body, field này thắng env. Hữu ích cho các runtime định tuyến nhiều role qua một process server. Tool MCP `memory_save` phơi ra cùng field `agentId`, standalone stdio server forward cả `agentId` và `project`, và các memory đã lưu mang `agentId` vào search index, nên search theo scope agent bao phủ cả memory cũng như observation.
+
+Khi `AGENT_ID` chưa được đặt, memory vẫn không có scope (hành vi legacy, không tag, không filter).
+
+### Port
+
+agentmemory + iii-engine bind bốn port theo mặc định. Nếu một lần khởi động lại lỗi với `port in use`, bảng này cho bạn biết cần tìm process nào.
+
+| Port | Process | Mục đích | Ghi đè bằng env |
+|------|---------|---------|--------------|
+| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
+| `3112` | iii-engine | Worker stream nội bộ (được agentmemory + viewer dùng) | `III_STREAM_PORT` (ưu tiên) hoặc tên cũ `III_STREAMS_PORT` |
+| `3113` | agentmemory | Viewer real-time (`http://localhost:3113`) | `III_VIEWER_PORT` hoặc `AGENTMEMORY_VIEWER_URL` cho URL được báo cáo |
+| `49134` | iii-engine | WebSocket; worker đăng ký ở đây, telemetry OTel chảy qua đó | `III_ENGINE_PORT` hoặc `III_ENGINE_URL` |
+
+`--port ` đổi anchor REST và suy ra stream `N+1`, viewer `N+2`, và WebSocket engine `N+46023` chỉ ở những nơi port hoặc URL tương ứng ở trên chưa được đặt rõ. Nó không tạo một namespace lifecycle cách biệt. Dùng `--instance 1` cho daemon thứ hai; nó dùng anchor 3211, mặc định là `3211/3212/3213/49234`, và nhận một thư mục data và lifecycle `instance-1` riêng. Các instance từ 1 tới 50 theo đúng pattern đó.
+
+Engine đã pin khởi động với `--no-update-check` (không tra update hay security-advisory từ GitHub lúc boot) và với telemetry sử dụng ẩn danh của iii bị tắt: agentmemory đặt `III_TELEMETRY_ENABLED=false` cho engine mà nó spawn trừ khi bạn tự export biến đó, và compose file đi kèm cũng làm vậy.
+
+Dọn các process còn sót khi port vẫn bị chiếm sau một lần chạy bị 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
+```
+
+`agentmemory stop` dọn sạch cả worker và pidfile engine khi shutdown native một cách êm đẹp. Ở chế độ Docker nó flush worker native, dừng đúng container engine đã được validate, và giữ lại cả container cùng mount `/data` của nó để khởi động lại không mất dữ liệu; lần khởi động kế tiếp sẽ validate và resume đúng container đó. Gỡ cài đặt khi dùng Docker cần `agentmemory remove --keep-data`: nó xóa các file do agentmemory quản lý chung trong khi vẫn giữ container đã validate, mount data của nó, và bản ghi lifecycle cần để khôi phục chúng. Việc xóa dữ liệu Docker mang tính phá hủy được chủ đích để lại cho người vận hành tự làm sau khi backup. CLI cũng từ chối nhận hoặc gửi signal tới các process đang chiếm port của Docker hay VM (Docker backend, vpnkit, colima) như là engine native trừ khi `--force` được truyền. Việc dọn thủ công ở trên chỉ dành cho trường hợp sau-crash khi không còn pidfile nào sót lại.
+
+### File Config
+
+Đặt config runtime của agentmemory trong `~/.agentmemory/.env` thay vì export biến trong từng shell. Nếu viewer hiện một gợi ý setup như `export ANTHROPIC_API_KEY=...`, hãy copy nó vào file này dưới dạng `ANTHROPIC_API_KEY=...` không có tiền tố `export`, rồi khởi động lại agentmemory.
+
+Biến môi trường của process vẫn hoạt động và được ưu tiên hơn giá trị trong file.
+
+Trên Windows, cùng file đó nằm tại `%USERPROFILE%\.agentmemory\.env`:
+
+```powershell
+New-Item -ItemType Directory -Force $HOME\.agentmemory
+notepad $HOME\.agentmemory\.env
+```
+
+Để test với một subscription Claude Code Pro/Max thay vì một API key, hãy opt-in rõ ràng:
+
+```env
+AGENTMEMORY_ALLOW_AGENT_SDK=true
+AGENTMEMORY_AUTO_COMPRESS=true
+```
+
+Nén observation do LLM viết cần cả hai dòng: quyền truy cập tới một LLM provider (kể cả fallback subscription rõ ràng này) và `AGENTMEMORY_AUTO_COMPRESS=true`. Chỉ riêng một provider sẽ để đường nén synthetic mặc định nguyên tại chỗ.
+
+Consolidation (node graph, lesson, crystal) được bật theo mặc định bất cứ khi nào một LLM provider được cấu hình. Opt-out rõ ràng bằng `CONSOLIDATION_ENABLED=false` nếu bạn muốn hoạt động không-LLM. Graph extraction là một flag riêng:
+
+```env
+GRAPH_EXTRACTION_ENABLED=true
+# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
+```
+
+### Biến Môi trường
+
+Tạo `~/.agentmemory/.env`:
+
+```env
+# LLM provider (pick one — default is the no-op provider: no LLM calls)
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
+# GEMINI_API_KEY=...
+# OPENROUTER_API_KEY=...
+# MINIMAX_API_KEY=...
+# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
+# # OpenAI LLM provider (here) AND the OpenAI
+# # embedding provider (further below). Set
+# # OPENAI_API_KEY_FOR_LLM=false to scope it
+# # to embeddings only.
+# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
+# # Azure: https://.openai.azure.com/openai/deployments/
+# # Auto-detected from `.openai.azure.com` hostname; uses
+# # api-key header + api-version query param.
+# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
+# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
+# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
+# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
+# # for back-compat with v0.9.17. New configs should
+# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
+# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
+# # Honored only by OpenAI's reasoning models (o1, o3,
+# # gpt-*-reasoning) and providers that mirror that
+# # schema (Ollama Cloud thinking models). Standard
+# # chat models reject this field with 400. Set to
+# # "none" for thinking models that return reasoning
+# # but no content.
+# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
+# # for LLM (useful if you only want OpenAI for embeddings)
+# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
+# leave OFF unless you understand the Stop-hook recursion risk:
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# Embedding provider (BM25-only when unset; local is an explicit opt-in)
+# EMBEDDING_PROVIDER=local
+# VOYAGE_API_KEY=...
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
+# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
+# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
+# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
+
+# Outbound LLM / embedding timeout
+# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
+ # raw-fetch provider (Gemini, OpenRouter, MiniMax,
+ # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
+ # embedding). For the OpenAI LLM path, the
+ # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
+ # takes precedence when set, for back-compat
+ # with v0.9.17.
+ # Increase for slow networks or large batch calls;
+ # decrease to fail-fast on rate-limit holds.
+
+# Search tuning
+# BM25_WEIGHT=0.4
+# VECTOR_WEIGHT=0.6
+# TOKEN_BUDGET=2000
+
+# Auth (generated into ~/.agentmemory/secret on first start when unset)
+# AGENTMEMORY_SECRET=your-secret
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
+
+# Ports (defaults: 3111 API, 3113 viewer)
+# III_REST_PORT=3111
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# Features
+# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
+ # provider as well. When both are on,
+ # every PostToolUse hook calls your
+ # LLM provider to compress the
+ # observation — expect significant
+ # token spend on active sessions.
+# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
+ # memory slots — persona,
+ # user_preferences, tool_guidelines,
+ # project_context, guidance,
+ # pending_items, session_patterns,
+ # self_notes. Size-limited; agent
+ # edits via memory_slot_* tools.
+ # Pinned slots addressable for
+ # SessionStart injection.
+# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
+ # Stop hook fires mem::slot-reflect:
+ # scans recent observations, auto-
+ # appends TODOs to pending_items,
+ # counts patterns in
+ # session_patterns, records touched
+ # files in project_context. Fire-
+ # and-forget; does not block.
+# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
+ # - SessionStart may inject ~1-2K
+ # chars of project context into
+ # the first turn of each session
+ # (this is what actually reaches
+ # the model — Claude Code treats
+ # SessionStart stdout as context)
+ # - PreToolUse fires /agentmemory/enrich
+ # on every file-touching tool call
+ # (resource cleanup, not a token
+ # fix — PreToolUse stdout is debug
+ # log only per Claude Code docs)
+ # Observations are still captured via
+ # PostToolUse regardless of this flag.
+# GRAPH_EXTRACTION_ENABLED=false
+# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
+ # model to skip its hidden thinking pass
+ # during graph extraction. Faster runs;
+ # relation quality can drop slightly.
+# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
+# LESSON_DECAY_ENABLED=true
+# OBSIDIAN_AUTO_EXPORT=false
+# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
+# CLAUDE_MEMORY_BRIDGE=false
+# SNAPSHOT_ENABLED=false
+
+# Storage and durability
+# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
+# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
+# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
+ # A hard kill loses at most this window.
+# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
+ # shutdown and deletes still save at once.
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
+ # provenance; false skips it
+
+# Sessions
+# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
+ # the threshold as abandoned. Deletes nothing;
+ # new activity makes the session active again.
+# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
+
+# Capture filters (hooks)
+# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
+ # when set, only these tools are captured
+# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
+ # defaults: memory_*, toolsearch,
+ # listmcpresources, fetchmcpresource
+# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
+# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
+
+# Audit log
+# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
+# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
+ # rows (debugging only)
+
+# Team
+# TEAM_ID=
+# USER_ID=
+# TEAM_MODE=private
+
+# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
+# AGENTMEMORY_TOOLS=core
+```
+
+---
+
+
+
+138 endpoint trên port `3111`. REST API bind vào `127.0.0.1` theo mặc định. Các endpoint được bảo vệ cần `Authorization: Bearer `, và các endpoint mesh sync cần `AGENTMEMORY_SECRET` được đặt rõ ràng trên cả hai phía.
+
+**Authentication được bật theo mặc định.** Khi `AGENTMEMORY_SECRET` chưa được đặt (trong shell hay trong `~/.agentmemory/.env`), server sinh một secret ngẫu nhiên ở lần khởi động đầu tiên và lưu nó vào `~/.agentmemory/secret` với mode `0600`. Mọi client đi kèm đọc nó từ đó khi nói chuyện với một server cục bộ: CLI, viewer, các hook dưới `plugin/scripts`, MCP server và shim `@agentmemory/mcp`, các config do `agentmemory connect` viết ra, và các integration OpenCode, Pi, OpenClaw, Hermes và filesystem-watcher đi kèm. Secret đã lưu chỉ được gửi tới các URL loopback (`localhost`, `127.0.0.0/8`, `::1`). Một `AGENTMEMORY_SECRET` rõ ràng luôn thắng, và các client remote vẫn cần đặt nó. Docker và các entrypoint của `deploy/` đã tự sinh và export secret riêng của chúng. Để gọi API bằng tay:
+
+```bash
+curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+```
+
+**Quy tắc request cho các lệnh write.** Các request `POST`, `PUT`, `PATCH` và `DELETE` tới REST API và viewer phải gửi `Content-Type: application/json` (một tham số `charset` thì vẫn ổn) bất cứ khi nào chúng mang theo body, và một header `Origin`, nếu có, phải là một origin loopback cho port REST hoặc viewer đã cấu hình hoặc được liệt kê trong `VIEWER_ALLOWED_ORIGINS` (phân tách bằng dấu phẩy, ví dụ `https://memory.example.com`). Các client không gửi header `Origin` (CLI, hook, MCP, curl, server-to-server) không bị ảnh hưởng. Viewer cũng chấp nhận origin của chính nó.
+
+**Đường dẫn file.** Các endpoint đọc hoặc viết file (`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`) chỉ nhận đường dẫn nằm dưới `~/.agentmemory`, thư mục data của instance, hoặc một thư mục được liệt kê trong `AGENTMEMORY_IMPORT_ROOT` (tách nhiều thư mục bằng `:`, hoặc `;` trên Windows). `/replay/import-jsonl` cũng nhận mặc định `~/.claude/projects` của nó. `/obsidian/export` ở trong `AGENTMEMORY_EXPORT_ROOT` và `/migrate` ở trong `~/.agentmemory`. Symlink được resolve trước mỗi lần kiểm tra.
+
+**Scrub secret.** API key, bearer token, block PEM private key và credential nhúng trong URL (`scheme://user:password@host`) đều bị redact trước khi text được lưu, trên mọi đường write: observation, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, output compression và summary, crystal và node graph.
+
+
+Các endpoint chính
+
+| Method | Path | Mô tả |
+|--------|------|-------------|
+| `GET` | `/agentmemory/health` | Health check (luôn public) |
+| `GET` | `/agentmemory/status` | Cái gì đang sai và cách sửa nó (HTML cho browser, JSON cho trường hợp khác) |
+| `GET` | `/agentmemory/viewer/snapshot` | Mọi thứ viewer hiển thị, trong một response |
+| `POST` | `/agentmemory/session/start` | Bắt đầu session + lấy context |
+| `POST` | `/agentmemory/session/end` | Kết thúc session |
+| `POST` | `/agentmemory/observe` | Capture observation (xem phần capture delivery dưới đây) |
+| `GET` | `/agentmemory/capture` | Capture inbox, dead letter và offline spool |
+| `POST` | `/agentmemory/capture/retry` | Retry các capture dead-letter |
+| `POST` | `/agentmemory/capture/drain` | Gửi offline spool cục bộ ngay |
+| `POST` | `/agentmemory/smart-search` | Tìm kiếm hybrid |
+| `POST` | `/agentmemory/context` | Sinh context |
+| `POST` | `/agentmemory/remember` | Lưu vào bộ nhớ dài hạn |
+| `POST` | `/agentmemory/forget` | Xóa observation |
+| `POST` | `/agentmemory/enrich` | Context file + memory + bug |
+| `GET` | `/agentmemory/profile` | Hồ sơ project |
+| `GET` | `/agentmemory/export` | Export toàn bộ dữ liệu |
+| `POST` | `/agentmemory/import` | Import từ JSON |
+| `POST` | `/agentmemory/graph/query` | Truy vấn knowledge graph |
+| `POST` | `/agentmemory/graph/compact` | Cắt gọn provenance graph quá lớn |
+| `POST` | `/agentmemory/team/share` | Chia sẻ với team |
+| `GET` | `/agentmemory/audit` | Audit trail |
+
+Danh sách endpoint đầy đủ: [`src/triggers/api.ts`](../src/triggers/api.ts)
+
+
+
+**Capture delivery.** Hook gửi mỗi observation một lần tới `POST /agentmemory/observe` kèm một `eventId`. Đó là id riêng của host cho lệnh gọi này khi payload có sẵn một id (ví dụ `tool_use_id` của Claude Code), nếu không thì là một hash của session, loại hook, tên tool, input, output và timestamp của host. Server viết event vào một capture inbox trong state store, lưu observation, rồi xóa entry trong inbox. Status code nói lên điều gì đã xảy ra:
+
+| Status | Field `status` | Ý nghĩa |
+|---|---|---|
+| `201` | `accepted` | Đã lưu. `observationId` là observation mới. |
+| `202` | `accepted` (`state: "retrying"`) | Đã accept, nhưng lưu thất bại. Server sẽ retry, cả sau một lần restart. |
+| `200` | `duplicate` | `eventId` này đã được accept trước đó. `observationId` là observation đã có; không có gì mới được lưu. |
+| `400` / `422` | `rejected` | Payload không hợp lệ, hoặc lưu thất bại hẳn (event được giữ lại như một dead letter). |
+| `503` | `rejected` (`retryable: true`) | Inbox đã đầy (`AGENTMEMORY_CAPTURE_INBOX_MAX`). Hook sẽ spool event lại và gửi sau. |
+
+Các event thất bại được retry mỗi `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 giây) với backoff tăng dần, tối đa `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). Các event vẫn thất bại sẽ nằm lại trong inbox như dead letter, được liệt kê trên `/agentmemory/status` và trang Health của viewer, và có thể retry bằng `POST /agentmemory/capture/retry` (`{"eventId": "..."}` hoặc `{"all": true}`). Các event id đã accept được ghi nhớ trong `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 giờ, tối đa `AGENTMEMORY_CAPTURE_EVENTS_MAX` id), nên một hook được replay sau một timeout hay một restart chỉ được lưu một lần, trong khi hai lệnh gọi tool riêng biệt với id host riêng của chúng được lưu hai lần dù nội dung giống nhau. Khi một observation bị xóa (forget, xóa session, eviction, auto-forget hoặc một import thay thế store), event của nó được đánh dấu đã xóa trước khi observation bị gỡ, nên một lần replay của event đó trong cùng window được trả lời như một duplicate và không lưu gì cả. State store viết ra disk mỗi 2 giây, nên một event đã được trả lời vẫn có thể chỉ nằm trong memory một khoảnh khắc. Để bù cho điều đó, mỗi câu trả lời `2xx` cũng mang theo `bootId` của server (mới ở mỗi lần khởi động), `acceptedAt` và `durableAfterMs` (interval save cộng 1.5 giây trên file store, 1.5 giây trên redis, nơi độ bền là setting của người vận hành). Hook giữ event trong spool cục bộ cho tới khi window đó trôi qua và xóa nó ở một lệnh gọi sau mà không cần một request khác. Nếu `bootId` đã thay đổi vào lúc đó, server đã restart, nên hook gửi lại event với cùng `eventId`; một event đã chạm tới disk không bị lưu hai lần. Server cũng tự gửi các event như vậy lúc khởi động và ở mỗi retry interval, nên một lần restart không mất gì cả dù không có hook nào chạy sau đó. Các hook cũ bỏ qua các field thêm này, và các hook mới chạy với một server cũ sẽ drop event khi nhận `2xx` như trước.
+
+Khi server down, không trả lời kịp hoặc trả về 5xx, hook sẽ append observation vào một file spool cục bộ, `/capture-spool/-.jsonl` (ghi đè thư mục bằng `AGENTMEMORY_CAPTURE_SPOOL_DIR`). File này riêng tư cho user của bạn (mode 600), secret được redact theo đúng cách server redact chúng, nó giữ tối đa `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) và drop các entry cũ hơn `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). Khi nó đầy, các entry mới bị drop và được đếm, và `/agentmemory/status` sẽ báo cáo điều đó. Hook vẫn exit 0 trong giới hạn thời gian của nó và không thêm request nào khi server khỏe mạnh. Spool được gửi ở lần khởi động kế tiếp và bởi hook đầu tiên chạm tới server trở lại, trong một process nền để agent không phải chờ. Event id làm cho điều này an toàn: một observation đã đến trước một timeout không bị lưu hai lần. `npx @agentmemory/agentmemory capture` hiển thị spool và inbox của server, `--drain` gửi spool ngay, và `GET /agentmemory/capture` trả về cùng dữ liệu đó dưới dạng JSON. Đặt `AGENTMEMORY_CAPTURE_SPOOL=false` để tắt spool.
+
+**Compact provenance của graph.** Mỗi node và edge của knowledge graph giữ id của 32 observation mới nhất mà nó bắt nguồn từ đó. Các store được viết trước giới hạn đó có thể giữ hàng nghìn id cho mỗi node hot, khiến graph search và viewer chậm hoặc làm worker crash. agentmemory tự sửa điều này: ở lần khởi động đầu tiên sau khi nâng cấp, nó cắt gọn mọi node, edge, edge đã bị supersede (lịch sử graph temporal) và snapshot đã cache xuống đúng giới hạn ở nền, theo từng slice nhỏ có khoảng nghỉ giữa chúng, để search, capture và viewer vẫn hoạt động. Nó lưu tiến độ, resume sau một lần restart và không bao giờ chạy lại khi đã hoàn tất. `/agentmemory/status` và trang Health của viewer hiển thị nó là pending, running (kèm scope và vị trí hiện tại), done hoặc failed. Đặt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` để tắt nó.
+
+Để chạy nó bằng tay, gọi `POST /agentmemory/graph/compact`. Nó duyệt qua các index tên và edge-key thay vì liệt kê mọi node và edge, và an toàn để chạy lại. Khi nó cắt gọn id, nó viết một audit entry `graph_compact`.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+```
+
+Trên một store lớn, hoặc khi lệnh gọi trả về 504, hãy chạy nó theo slice. Gửi `scope` (`nodes`, `edges` hoặc `history`), `offset` và `limit`, rồi gọi lại với `nextOffset` được trả về cho tới khi nó là `null`. Làm điều này cho `nodes`, `edges` và `history`, và kết thúc với một lệnh gọi `{"scope":"snapshot"}`, vì một lần chạy theo slice không chạm tới snapshot đã cache.
+
+```bash
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
+```
+
+---
+
+
+
+```bash
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
+```
+
+**Yêu cầu trước:** Node.js >= 20 kèm npm/npx; [iii-engine](https://iii.dev/docs) v0.22.1 hoặc Docker. Cài engine tự động trên macOS/Linux cũng cần `curl`, một `sh` chuẩn POSIX, và `tar`; Windows gốc dùng `iii.exe` đã pin thủ công, WSL2, hoặc Docker Desktop.
+
+
```bash
-npm run dev # 热重载
-npm run build # 生产构建
-npm test # 1,619 测试
-npm run test:integration # API 测试(需要服务运行中)
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
```
-**先决条件:** Node.js >= 20、[iii-engine](https://iii.dev/docs) 或 Docker
+**前置条件:** Node.js >= 20,带 npm/npx;[iii-engine](https://iii.dev/docs) v0.22.1 或 Docker。macOS/Linux 的自动引擎安装还需要 `curl`、POSIX `sh` 和 `tar`;原生 Windows 使用手动安装的锚定 `iii.exe`、WSL2,或 Docker Desktop。
-
```bash
-npm run dev # 熱重新載入
-npm run build # 生產建置
-npm test # 1,619 測試
-npm run test:integration # API 測試(需要服務執行中)
+npm run dev # Hot reload
+npm run build # Production build
+npm test # 2,600+ tests
+npm run test:integration # API tests (requires running services)
```
-**先決條件:** Node.js >= 20、[iii-engine](https://iii.dev/docs) 或 Docker
+**先決條件:** Node.js >= 20,並具備 npm/npx;[iii-engine](https://iii.dev/docs) v0.22.1 或 Docker。macOS/Linux 的自動引擎安裝還需要 `curl`、POSIX `sh` 和 `tar`;原生 Windows 則使用手動安裝的釘住版本 `iii.exe`、WSL2 或 Docker Desktop。
diff --git a/assets/tags/light/section-agents.svg b/assets/tags/light/section-agents.svg
index 6f8adecdad..cff6943d92 100644
--- a/assets/tags/light/section-agents.svg
+++ b/assets/tags/light/section-agents.svg
@@ -12,5 +12,5 @@
WORKS WITH EVERY AGENT
- 15 integrations · one memory server
+ 25 agents · one memory server
\ No newline at end of file
diff --git a/assets/tags/light/stat-tests.svg b/assets/tags/light/stat-tests.svg
index f4675bd97a..4dfe9de336 100644
--- a/assets/tags/light/stat-tests.svg
+++ b/assets/tags/light/stat-tests.svg
@@ -1,5 +1,5 @@
-
\ No newline at end of file
diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg
index a7599939cd..b704fbe706 100644
--- a/assets/tags/stat-tests.svg
+++ b/assets/tags/stat-tests.svg
@@ -1,5 +1,5 @@
-
+
- 1648+
+ 2600+TESTS PASSING
diff --git a/benchmark/README.md b/benchmark/README.md
index 23d2285222..f63bf9500e 100644
--- a/benchmark/README.md
+++ b/benchmark/README.md
@@ -1,6 +1,6 @@
# benchmark/
-Two kinds of numbers live in this directory:
+Three kinds of numbers live in this directory:
1. **Quality / retrieval** — `longmemeval-bench.ts`, `quality-eval.ts`,
`real-embeddings-eval.ts`, `scale-eval.ts`. Recall, precision, token
@@ -11,6 +11,110 @@ Two kinds of numbers live in this directory:
throughput against a running daemon. This is the file you want when
somebody asks "what's p99 at 100k memories under concurrency 100?".
+3. **Resource cost**: `capture-costs.ts`. Disk, resident memory, CPU,
+ hook cost, provider calls, agent-visible context and recovery cost of
+ the built capture path, each reported separately.
+
+## capture-costs.ts
+
+
+
+Runs the built `dist/` artifact (CLI, worker and the bundled hooks in
+`dist/hooks/`) in an isolated instance per run: a fresh `HOME`, a fresh
+`--data-dir`, REST/streams/viewer on 4900-4902, metrics on 4903, the
+engine on 50100 and an in-process fake OpenAI-compatible provider on
+4950. It refuses to start if any of those ports is already in use, and it
+only signals the processes it spawned (the CLI and its engine). Nothing
+here runs in the default test suite.
+
+```bash
+npm run build
+npm run bench:capture-costs
+BENCH_N=10000 BENCH_PROFILES=keyless npm run bench:capture-costs
+```
+
+Each `(profile, N)` run goes through the same phases serially: cold start
+on an empty store, capture of N observations, quiesce, idle sample,
+evidence check, agent-visible context probe, `SIGKILL` of the whole
+process tree, recovery boot, evidence check again, graceful stop and a
+warm start.
+
+### Profiles
+
+| profile | provider config | automatic processing |
+|---|---|---|
+| `keyless` | no keys; BM25 only | synthetic compression, no provider calls |
+| `embed` | fake embeddings (`BENCH_EMBED_DIMS`, default 768), `OPENAI_API_KEY_FOR_LLM=false` | compression off |
+| `embed-llm` | fake embeddings plus fake chat model | `AGENTMEMORY_AUTO_COMPRESS=true` |
+
+Context injection stays at its default (off) for the instance. The probe
+turns it on only in the environment of single hook processes to measure
+what an agent would receive.
+
+### What it reports
+
+- **Storage**: bytes on disk per state scope, grouped into source,
+ summary, index, queue, failed-delivery, diagnostic, config and stream.
+ Fixed overhead (empty instance) and growth are separate. The builtin
+ queue adapter keeps nothing on disk, so queue and failed-delivery bytes
+ read 0 on the file store.
+- **Memory and CPU**: process-tree RSS (engine and worker split) sampled
+ every 250 ms during capture, at idle, after recovery and after a warm
+ start; CPU seconds from `ps` for the capture and recovery windows.
+- **Capture**: latency of the real `post-tool-use` hook process for the
+ first `BENCH_HOOK_SAMPLE` observations (the hook spawns Node and posts
+ to `/agentmemory/observe`), its stdout and stderr bytes, then the
+ remaining observations posted to the same endpoint with the same body at
+ `BENCH_CONCURRENCY`.
+- **Provider calls**: requests, inputs, repeated inputs and returned usage
+ counted on the fake server for capture, the context probe, recovery and
+ warm start separately. Counters a run cannot observe are `unknown`.
+- **Agent-visible context**: bytes and the server's own token estimate
+ (`tokens_used`, `tokens`) for `/search` in full, compact and narrative
+ formats, `/smart-search` and `/context` at `BENCH_CONTEXT_BUDGET`, plus
+ stdout bytes of the `SessionStart` and `PreToolUse` hooks with injection
+ off and on. These are server estimates, not provider billing.
+- **Recovery and evidence**: time to `livez`, time to the BM25 rebuild log
+ line, rebuild duration and doc count, vectors loaded, backfill queued,
+ re-embedding requests, logical observation count, keyword hits for a
+ per-observation head marker and whether the stored source still holds
+ the tail marker (via `/agentmemory/replay/load`). A smaller store that
+ lost source fails the invariants.
+
+### Invariants and budgets
+
+Invariants run on every report: the logical observation count equals N
+before the kill and after recovery, every sampled source keeps its tail
+marker, no observe errors, zero hook stdout with injection off, and the
+`/context` estimate stays within the declared cap. A failing invariant
+exits 1.
+
+Budgets live in `benchmark/capture-costs-budgets.json`, keyed by profile
+and N, separately for storage, memory, latency and context. They were
+derived from repeated runs with `BENCH_REPEATS=2
+BENCH_WRITE_BUDGETS=`, which takes the worst repeat and applies a
+per-metric headroom. Results show pass or fail per budget; set
+`BENCH_ENFORCE_BUDGETS=1` to exit 2 on a breach. Budgets are
+hardware-bound: re-derive them on the machine that enforces them.
+
+### Knobs
+
+`BENCH_N` (default `100,1000`), `BENCH_PROFILES`, `BENCH_REPEATS`,
+`BENCH_OBS_PER_SESSION` (100), `BENCH_HOOK_SAMPLE` (100),
+`BENCH_CONCURRENCY` (8), `BENCH_OUTPUT_BYTES` (`400,4000`),
+`BENCH_SEED`, `BENCH_EMBED_DIMS` (768), `BENCH_CONTEXT_BUDGET` (2000),
+`BENCH_SEARCH_LIMIT` (10), `BENCH_EVIDENCE_SAMPLE` (50), `BENCH_PORT`
+(4900), `BENCH_ENGINE_PORT` (50100), `BENCH_FAKE_PORT`, `BENCH_ROOT`,
+`BENCH_KEEP=1` (keep data dirs and CLI logs), `BENCH_OUT_DIR`,
+`BENCH_BUDGETS` (path or `off`), `BENCH_WRITE_BUDGETS` (derive budgets
+from this report), `BENCH_ENFORCE_BUDGETS=1`, `BENCH_MERGE` (comma list
+of report JSON files from one commit: merges them, rechecks invariants
+and budgets, and renders one table without starting an instance),
+`AGENTMEMORY_BENCH_III` (engine binary;
+defaults to a binary matching the pinned version in `~/.agentmemory/bin`
+or `~/.local/bin`). Tool outputs come from the same `mulberry32` corpus
+generator as `load-100k.ts` (`lib/corpus.ts`).
+
## load-100k.ts
Hand-rolled, dependency-free load harness. Issues real HTTP against a
diff --git a/benchmark/capture-costs-budgets.json b/benchmark/capture-costs-budgets.json
new file mode 100644
index 0000000000..37a4336faf
--- /dev/null
+++ b/benchmark/capture-costs-budgets.json
@@ -0,0 +1,225 @@
+{
+ "budgets": {
+ "keyless": {
+ "100": {
+ "diskGrowthPerObservationBytes": 5192,
+ "diskAfterCaptureBytes": 526616,
+ "diskIndexBytes": 16384,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 238380,
+ "idleRssKiB": 238360,
+ "recoveryIdleRssKiB": 245860,
+ "hookP95Ms": 250,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 10475,
+ "searchCompactTokensP50": 676,
+ "sessionStartInjectOnStdoutBytes": 4096
+ },
+ "1000": {
+ "diskGrowthPerObservationBytes": 4510,
+ "diskAfterCaptureBytes": 4516980,
+ "diskIndexBytes": 62970,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 340760,
+ "idleRssKiB": 340760,
+ "recoveryIdleRssKiB": 288700,
+ "hookP95Ms": 268,
+ "observeP95Ms": 653,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3126,
+ "searchFullBytesP50": 10480,
+ "searchCompactTokensP50": 681,
+ "sessionStartInjectOnStdoutBytes": 5266
+ },
+ "10000": {
+ "diskGrowthPerObservationBytes": 4036,
+ "diskAfterCaptureBytes": 40367460,
+ "diskIndexBytes": 641460,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 645120,
+ "idleRssKiB": 644300,
+ "recoveryIdleRssKiB": 484640,
+ "hookP95Ms": 257,
+ "observeP95Ms": 330,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 5742,
+ "searchFullBytesP50": 10497,
+ "searchCompactTokensP50": 690,
+ "sessionStartInjectOnStdoutBytes": 5264
+ }
+ },
+ "embed": {
+ "100": {
+ "diskGrowthPerObservationBytes": 10218,
+ "diskAfterCaptureBytes": 1028921,
+ "diskIndexBytes": 531385,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 265180,
+ "idleRssKiB": 217220,
+ "recoveryIdleRssKiB": 207580,
+ "hookP95Ms": 250,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 10385,
+ "searchCompactTokensP50": 664,
+ "sessionStartInjectOnStdoutBytes": 4096
+ },
+ "1000": {
+ "diskGrowthPerObservationBytes": 9552,
+ "diskAfterCaptureBytes": 9558612,
+ "diskIndexBytes": 5320070,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 381260,
+ "idleRssKiB": 381080,
+ "recoveryIdleRssKiB": 323860,
+ "hookP95Ms": 466,
+ "observeP95Ms": 745,
+ "recoveryReadyMs": 4696,
+ "recoveryIndexReadyMs": 5914,
+ "searchFullBytesP50": 10458,
+ "searchCompactTokensP50": 663,
+ "sessionStartInjectOnStdoutBytes": 5266
+ },
+ "10000": {
+ "diskGrowthPerObservationBytes": 9062,
+ "diskAfterCaptureBytes": 90617796,
+ "diskIndexBytes": 53014310,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 863880,
+ "idleRssKiB": 863880,
+ "recoveryIdleRssKiB": 734340,
+ "hookP95Ms": 406,
+ "observeP95Ms": 340,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 6346,
+ "searchFullBytesP50": 10538,
+ "searchCompactTokensP50": 678,
+ "sessionStartInjectOnStdoutBytes": 5264
+ }
+ },
+ "embed-llm": {
+ "100": {
+ "diskGrowthPerObservationBytes": 8909,
+ "diskAfterCaptureBytes": 898356,
+ "diskIndexBytes": 532735,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 259640,
+ "idleRssKiB": 259640,
+ "recoveryIdleRssKiB": 205620,
+ "hookP95Ms": 250,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 7793,
+ "searchCompactTokensP50": 832,
+ "sessionStartInjectOnStdoutBytes": 4096
+ },
+ "1000": {
+ "diskGrowthPerObservationBytes": 8760,
+ "diskAfterCaptureBytes": 8767616,
+ "diskIndexBytes": 5327395,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 467380,
+ "idleRssKiB": 373340,
+ "recoveryIdleRssKiB": 311320,
+ "hookP95Ms": 250,
+ "observeP95Ms": 277,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 7851,
+ "searchCompactTokensP50": 834,
+ "sessionStartInjectOnStdoutBytes": 6970
+ },
+ "10000": {
+ "diskGrowthPerObservationBytes": 8756,
+ "diskAfterCaptureBytes": 87561564,
+ "diskIndexBytes": 53123475,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 1009100,
+ "idleRssKiB": 1004300,
+ "recoveryIdleRssKiB": 681800,
+ "hookP95Ms": 346,
+ "observeP95Ms": 471,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 6102,
+ "searchFullBytesP50": 7944,
+ "searchCompactTokensP50": 845,
+ "sessionStartInjectOnStdoutBytes": 7006
+ }
+ },
+ "keyless@redis": {
+ "100": {
+ "diskGrowthPerObservationBytes": 1024,
+ "diskAfterCaptureBytes": 65536,
+ "diskIndexBytes": 16384,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 263640,
+ "idleRssKiB": 210320,
+ "recoveryIdleRssKiB": 255220,
+ "hookP95Ms": 250,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 10475,
+ "searchCompactTokensP50": 676,
+ "sessionStartInjectOnStdoutBytes": 4096,
+ "redisUsedMemoryBytes": 4194304,
+ "redisKeys": 173
+ },
+ "1000": {
+ "diskGrowthPerObservationBytes": 1024,
+ "diskAfterCaptureBytes": 65536,
+ "diskIndexBytes": 16384,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 331800,
+ "idleRssKiB": 248000,
+ "recoveryIdleRssKiB": 277900,
+ "hookP95Ms": 250,
+ "observeP95Ms": 175,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 10480,
+ "searchCompactTokensP50": 681,
+ "sessionStartInjectOnStdoutBytes": 5268,
+ "redisUsedMemoryBytes": 6446304,
+ "redisKeys": 191
+ }
+ },
+ "embed@redis": {
+ "100": {
+ "diskGrowthPerObservationBytes": 1024,
+ "diskAfterCaptureBytes": 65536,
+ "diskIndexBytes": 16384,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 263760,
+ "idleRssKiB": 261820,
+ "recoveryIdleRssKiB": 256260,
+ "hookP95Ms": 250,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 10385,
+ "searchCompactTokensP50": 664,
+ "sessionStartInjectOnStdoutBytes": 4096,
+ "redisUsedMemoryBytes": 4194304,
+ "redisKeys": 173
+ },
+ "1000": {
+ "diskGrowthPerObservationBytes": 1024,
+ "diskAfterCaptureBytes": 65536,
+ "diskIndexBytes": 16384,
+ "diskDiagnosticBytes": 16384,
+ "capturePeakRssKiB": 357660,
+ "idleRssKiB": 353040,
+ "recoveryIdleRssKiB": 304460,
+ "hookP95Ms": 250,
+ "observeP95Ms": 211,
+ "recoveryReadyMs": 3000,
+ "recoveryIndexReadyMs": 3000,
+ "searchFullBytesP50": 10458,
+ "searchCompactTokensP50": 663,
+ "sessionStartInjectOnStdoutBytes": 5260,
+ "redisUsedMemoryBytes": 12664877,
+ "redisKeys": 204
+ }
+ }
+ }
+}
diff --git a/benchmark/capture-costs.ts b/benchmark/capture-costs.ts
new file mode 100644
index 0000000000..c2292e36a7
--- /dev/null
+++ b/benchmark/capture-costs.ts
@@ -0,0 +1,1861 @@
+import { spawn, execFile, execFileSync, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+ copyFileSync,
+ existsSync,
+ mkdirSync,
+ openSync,
+ closeSync,
+ readFileSync,
+ readdirSync,
+ rmSync,
+ statSync,
+ writeFileSync,
+ chmodSync,
+} from "node:fs";
+import { createServer, type Server, type ServerResponse } from "node:http";
+import { createConnection } from "node:net";
+import { cpus, homedir, platform, release, tmpdir, totalmem, arch } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { promisify } from "node:util";
+
+import { pXX } from "./lib/percentiles.js";
+import { CONCEPTS, NOUNS, buildToolCapture, mulberry32, type ToolCapture } from "./lib/corpus.js";
+
+const execFileAsync = promisify(execFile);
+const SCHEMA_VERSION = 1;
+const PROJECT = "capture-costs";
+
+type ProfileName = "keyless" | "embed" | "embed-llm";
+
+interface Profile {
+ name: ProfileName;
+ description: string;
+ embeddings: boolean;
+ llm: boolean;
+ autoCompress: boolean;
+}
+
+const PROFILES: Record = {
+ keyless: {
+ name: "keyless",
+ description: "No provider keys. BM25 only, zero-LLM synthetic compression.",
+ embeddings: false,
+ llm: false,
+ autoCompress: false,
+ },
+ embed: {
+ name: "embed",
+ description: "Deterministic fake OpenAI-compatible embeddings, LLM disabled, automatic compression off.",
+ embeddings: true,
+ llm: false,
+ autoCompress: false,
+ },
+ "embed-llm": {
+ name: "embed-llm",
+ description: "Fake embeddings plus a fake OpenAI-compatible chat model with AGENTMEMORY_AUTO_COMPRESS=true.",
+ embeddings: true,
+ llm: true,
+ autoCompress: true,
+ },
+};
+
+type ProviderMode = "fake" | "ollama";
+type StateBackend = "file" | "redis";
+type Scenario = "standard" | "crash-offline";
+
+interface Config {
+ sizes: number[];
+ profiles: Profile[];
+ provider: ProviderMode;
+ upstreamUrl: string | null;
+ embedModel: string;
+ chatModel: string;
+ stateBackend: StateBackend;
+ redisUrl: string | null;
+ scenario: Scenario;
+ killAfterMs: number;
+ killSettleMs: number;
+ perSession: number;
+ hookSample: number;
+ concurrency: number;
+ outputMin: number;
+ outputMax: number;
+ seed: number;
+ dims: number;
+ contextBudget: number;
+ searchLimit: number;
+ evidenceSample: number;
+ restPort: number;
+ enginePort: number;
+ fakePort: number;
+ root: string;
+ outDir: string;
+ keep: boolean;
+ iiiBin: string;
+ distDir: string;
+ quiesceTimeoutMs: number;
+ readyTimeoutMs: number;
+ repeats: number;
+ budgetsPath: string | null;
+ writeBudgetsPath: string | null;
+ enforceBudgets: boolean;
+}
+
+function intList(raw: string | undefined, fallback: number[]): number[] {
+ if (!raw) return fallback;
+ const out = raw
+ .split(",")
+ .map((s) => parseInt(s.trim(), 10))
+ .filter((n) => Number.isFinite(n) && n > 0);
+ return out.length > 0 ? out : fallback;
+}
+
+function intEnv(name: string, fallback: number): number {
+ const n = parseInt(process.env[name] ?? "", 10);
+ return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+function iiiVersion(bin: string): string | null {
+ try {
+ const out = execFileSync(bin, ["--version"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
+ return out.match(/(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/)?.[1] ?? null;
+ } catch {
+ return null;
+ }
+}
+
+function pinnedIiiVersion(distDir: string): string | null {
+ try {
+ const src = readFileSync(join(distDir, "cli.mjs"), "utf8");
+ return src.match(/IIPINNED_VERSION\s*=\s*[^"']*["'](\d+\.\d+\.\d+)["']/)?.[1] ?? null;
+ } catch {
+ return null;
+ }
+}
+
+function resolveIii(distDir: string): string {
+ const explicit = process.env["AGENTMEMORY_BENCH_III"];
+ if (explicit) return explicit;
+ const pinned = pinnedIiiVersion(distDir);
+ const candidates = [join(homedir(), ".agentmemory", "bin", "iii"), join(homedir(), ".local", "bin", "iii"), "/usr/local/bin/iii"];
+ for (const c of candidates) {
+ if (existsSync(c) && (!pinned || iiiVersion(c) === pinned)) return c;
+ }
+ throw new Error(`no iii binary matching the pinned version ${pinned ?? "?"}; set AGENTMEMORY_BENCH_III`);
+}
+
+function loadConfig(): Config {
+ const distDir = resolve(process.cwd(), "dist");
+ const names = (process.env["BENCH_PROFILES"] || "keyless,embed,embed-llm")
+ .split(",")
+ .map((s) => s.trim())
+ .filter(Boolean);
+ const profiles = names.map((n) => {
+ const p = PROFILES[n as ProfileName];
+ if (!p) throw new Error(`unknown profile ${n}; valid: ${Object.keys(PROFILES).join(", ")}`);
+ return p;
+ });
+ const [outputMin, outputMax] = intList(process.env["BENCH_OUTPUT_BYTES"], [400, 4000]);
+ const restPort = intEnv("BENCH_PORT", 4900);
+ const provider = (process.env["BENCH_PROVIDER"] || "fake") as ProviderMode;
+ if (provider !== "fake" && provider !== "ollama") throw new Error(`unknown BENCH_PROVIDER ${provider}; valid: fake, ollama`);
+ const stateBackend = (process.env["BENCH_STATE_BACKEND"] || "file") as StateBackend;
+ if (stateBackend !== "file" && stateBackend !== "redis") throw new Error(`unknown BENCH_STATE_BACKEND ${stateBackend}; valid: file, redis`);
+ const redisUrl = process.env["BENCH_REDIS_URL"] || null;
+ if (stateBackend === "redis" && !redisUrl) throw new Error("BENCH_STATE_BACKEND=redis needs BENCH_REDIS_URL, a Redis the bench may flush");
+ const scenario = (process.env["BENCH_SCENARIO"] || "standard") as Scenario;
+ if (scenario !== "standard" && scenario !== "crash-offline") throw new Error(`unknown BENCH_SCENARIO ${scenario}; valid: standard, crash-offline`);
+ return {
+ sizes: intList(process.env["BENCH_N"], [100, 1000]),
+ profiles,
+ provider,
+ upstreamUrl: provider === "ollama" ? (process.env["BENCH_OLLAMA_URL"] || "http://127.0.0.1:11434").replace(/\/+$/, "") : null,
+ embedModel: process.env["BENCH_EMBED_MODEL"] || (provider === "ollama" ? "nomic-embed-text" : "bench-fake-embedding"),
+ chatModel: process.env["BENCH_CHAT_MODEL"] || (provider === "ollama" ? "qwen3:4b-instruct-2507-q4_K_M" : "bench-fake-chat"),
+ stateBackend,
+ redisUrl,
+ scenario,
+ killAfterMs: intEnv("BENCH_KILL_AFTER_MS", 3000) || 3000,
+ killSettleMs: intEnv("BENCH_KILL_SETTLE_MS", 0),
+ perSession: intEnv("BENCH_OBS_PER_SESSION", 100) || 100,
+ hookSample: intEnv("BENCH_HOOK_SAMPLE", 100),
+ concurrency: intEnv("BENCH_CONCURRENCY", 8) || 8,
+ outputMin: outputMin ?? 400,
+ outputMax: outputMax ?? outputMin ?? 4000,
+ seed: intEnv("BENCH_SEED", 12648430),
+ dims: intEnv("BENCH_EMBED_DIMS", 768) || 768,
+ contextBudget: intEnv("BENCH_CONTEXT_BUDGET", 2000) || 2000,
+ searchLimit: intEnv("BENCH_SEARCH_LIMIT", 10) || 10,
+ evidenceSample: intEnv("BENCH_EVIDENCE_SAMPLE", 50) || 50,
+ restPort,
+ enginePort: intEnv("BENCH_ENGINE_PORT", 50100),
+ fakePort: intEnv("BENCH_FAKE_PORT", restPort + 50),
+ root: process.env["BENCH_ROOT"] || join(tmpdir(), `agentmemory-capture-costs-${Date.now().toString(36)}`),
+ outDir: process.env["BENCH_OUT_DIR"] || resolve(process.cwd(), "benchmark", "results"),
+ keep: process.env["BENCH_KEEP"] === "1",
+ iiiBin: resolveIii(distDir),
+ distDir,
+ quiesceTimeoutMs: intEnv("BENCH_QUIESCE_TIMEOUT_MS", 600000),
+ readyTimeoutMs: intEnv("BENCH_READY_TIMEOUT_MS", 600000),
+ repeats: intEnv("BENCH_REPEATS", 1) || 1,
+ budgetsPath:
+ process.env["BENCH_BUDGETS"] === "off"
+ ? null
+ : resolve(process.cwd(), process.env["BENCH_BUDGETS"] || join("benchmark", "capture-costs-budgets.json")),
+ writeBudgetsPath: process.env["BENCH_WRITE_BUDGETS"] ? resolve(process.cwd(), process.env["BENCH_WRITE_BUDGETS"]) : null,
+ enforceBudgets: process.env["BENCH_ENFORCE_BUDGETS"] === "1",
+ };
+}
+
+interface Check {
+ profile: string;
+ observations: number;
+ repeat: number;
+ name: string;
+ value: number | null;
+ limit: number;
+ pass: boolean;
+}
+
+interface BudgetMetric {
+ path: string;
+ headroom: number;
+ floor: number;
+ kind: "storage" | "memory" | "latency" | "context";
+}
+
+const BUDGET_METRICS: Record = {
+ diskGrowthPerObservationBytes: { path: "diskGrowthPerObservationBytes", headroom: 1.2, floor: 1024, kind: "storage" },
+ diskAfterCaptureBytes: { path: "diskAfterCapture.totalBytes", headroom: 1.2, floor: 65536, kind: "storage" },
+ diskIndexBytes: { path: "diskAfterCapture.byCategory.index", headroom: 1.25, floor: 16384, kind: "storage" },
+ diskDiagnosticBytes: { path: "diskAfterCapture.byCategory.diagnostic", headroom: 1.5, floor: 16384, kind: "storage" },
+ capturePeakRssKiB: { path: "capture.rss.peakTotalKiB", headroom: 1.25, floor: 65536, kind: "memory" },
+ idleRssKiB: { path: "idle.rssKiB.total", headroom: 1.25, floor: 65536, kind: "memory" },
+ recoveryIdleRssKiB: { path: "recovery.rss.idleTotalKiB", headroom: 1.25, floor: 65536, kind: "memory" },
+ hookP95Ms: { path: "capture.hookLatencyMs.p95", headroom: 2, floor: 250, kind: "latency" },
+ observeP95Ms: { path: "capture.observeLatencyMs.p95", headroom: 3, floor: 150, kind: "latency" },
+ recoveryReadyMs: { path: "recovery.readyMs", headroom: 2, floor: 3000, kind: "latency" },
+ recoveryIndexReadyMs: { path: "recovery.indexReadyMs", headroom: 2, floor: 3000, kind: "latency" },
+ searchFullBytesP50: { path: "agentVisibleContext.endpoints.search_full.bytes.p50", headroom: 1.2, floor: 4096, kind: "context" },
+ searchCompactTokensP50: { path: "agentVisibleContext.endpoints.search_compact.serverTokenEstimate.p50", headroom: 1.2, floor: 512, kind: "context" },
+ sessionStartInjectOnStdoutBytes: { path: "agentVisibleContext.hookStdout.session_start_inject_on.stdoutBytes", headroom: 1.2, floor: 4096, kind: "context" },
+ redisUsedMemoryBytes: { path: "redisAfterCapture.usedMemoryBytes", headroom: 1.2, floor: 4194304, kind: "storage" },
+ redisKeys: { path: "redisAfterCapture.keys", headroom: 1.2, floor: 64, kind: "storage" },
+};
+
+function variantOf(r: Record): string {
+ return String(r["variant"] ?? r["profile"]);
+}
+
+function variantName(profile: Profile, cfg: Config): string {
+ let name = profile.name;
+ if (cfg.provider !== "fake" && profile.embeddings) name += `+${cfg.provider}`;
+ if (cfg.stateBackend !== "file") name += `@${cfg.stateBackend}`;
+ if (cfg.scenario !== "standard") name += `:${cfg.scenario}`;
+ return name;
+}
+
+interface BudgetFile {
+ budgets: Record>>;
+}
+
+function numberAt(o: unknown, path: string): number | null {
+ const v = get(o, path);
+ return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+function checkInvariants(runs: Record[]): Check[] {
+ const out: Check[] = [];
+ for (const r of runs) {
+ const n = r["observations"] as number;
+ const base = { profile: variantOf(r), observations: n, repeat: (r["repeat"] as number) ?? 1 };
+ const eq = (name: string, value: number | null, limit: number) => out.push({ ...base, name, value, limit, pass: value === limit });
+ const atMost = (name: string, value: number | null, limit: number) => out.push({ ...base, name, value, limit, pass: value !== null && value <= limit });
+ if (r["scenario"] === "crash-offline") {
+ const embeds = r["embeddings"] === true;
+ out.push({ ...base, name: "hooksSpooledWhileDown", value: numberAt(r, "crash.spoolRecordsWhileDown"), limit: 1, pass: (numberAt(r, "crash.spoolRecordsWhileDown") ?? 0) >= 1 });
+ eq("spoolDroppedRecords", numberAt(r, "crash.spoolStats.dropped"), 0);
+ eq("hookNonZeroExits", numberAt(r, "crash.hookNonZeroExits"), 0);
+ eq("logicalObservationsAfterRecovery", numberAt(r, "evidenceAfterRecovery.logicalObservations"), n);
+ eq("sourceTailRetainedAfterRecovery", numberAt(r, "evidenceAfterRecovery.sourceTailRetained"), numberAt(r, "evidenceAfterRecovery.sampled") ?? -1);
+ eq("spoolRecordsAfterRecovery", numberAt(r, "recovery.spoolRecordsAfter"), 0);
+ if (embeds) {
+ eq("killBeforeFirstVectorCheckpoint", numberAt(r, "crash.vectorCheckpointBeforeKill"), 0);
+ eq("vectorDocumentsAfterRecovery", numberAt(r, "evidenceAfterRecovery.vectorDocuments"), n);
+ atMost("recoveryRepeatEmbedInputs", numberAt(r, "recovery.provider.embedRepeatInputs"), n);
+ }
+ continue;
+ }
+ eq("logicalObservationsBeforeKill", numberAt(r, "evidenceBeforeKill.logicalObservations"), n);
+ eq("logicalObservationsAfterRecovery", numberAt(r, "evidenceAfterRecovery.logicalObservations"), n);
+ const sampled = numberAt(r, "evidenceBeforeKill.sampled") ?? -1;
+ eq("sourceTailRetainedBeforeKill", numberAt(r, "evidenceBeforeKill.sourceTailRetained"), sampled);
+ eq("sourceTailRetainedAfterRecovery", numberAt(r, "evidenceAfterRecovery.sourceTailRetained"), sampled);
+ eq("observeErrors", numberAt(r, "capture.observeErrors"), 0);
+ eq("hookStdoutBytesWithInjectionOff", numberAt(r, "capture.hookStdoutBytes.total"), 0);
+ eq("sessionStartStdoutBytesWithInjectionOff", numberAt(r, "agentVisibleContext.hookStdout.session_start_inject_off.stdoutBytes"), 0);
+ eq("preToolUseStdoutBytesWithInjectionOff", numberAt(r, "agentVisibleContext.hookStdout.pre_tool_use_inject_off.stdoutBytes"), 0);
+ const cap = numberAt(r, "agentVisibleContext.declaredContextBudgetTokens") ?? 0;
+ const ctxTokens = numberAt(r, "agentVisibleContext.endpoints.context.serverTokenEstimate.max");
+ const vecBefore = numberAt(r, "evidenceBeforeKill.vectorDocuments");
+ if (vecBefore !== null && vecBefore > 0) eq("vectorDocumentsAfterRecovery", numberAt(r, "evidenceAfterRecovery.vectorDocuments"), vecBefore);
+ out.push({ ...base, name: "contextTokensWithinDeclaredCap", value: ctxTokens, limit: cap, pass: ctxTokens !== null && ctxTokens <= cap });
+ }
+ return out;
+}
+
+function checkBudgets(runs: Record[], file: BudgetFile): Check[] {
+ const out: Check[] = [];
+ for (const r of runs) {
+ const limits = file.budgets?.[variantOf(r)]?.[String(r["observations"])];
+ if (!limits) continue;
+ for (const [name, limit] of Object.entries(limits)) {
+ const metric = BUDGET_METRICS[name];
+ if (!metric) continue;
+ const value = numberAt(r, metric.path);
+ out.push({ profile: variantOf(r), observations: r["observations"] as number, repeat: (r["repeat"] as number) ?? 1, name, value, limit, pass: value !== null && value <= limit });
+ }
+ }
+ return out;
+}
+
+function deriveBudgets(runs: Record[]): BudgetFile {
+ const budgets: BudgetFile["budgets"] = {};
+ for (const r of runs) {
+ if (r["error"] || (r["provider"] ?? "fake") !== "fake" || (r["scenario"] ?? "standard") !== "standard") continue;
+ const p = variantOf(r);
+ const n = String(r["observations"]);
+ const slot = ((budgets[p] ??= {})[n] ??= {});
+ for (const [name, metric] of Object.entries(BUDGET_METRICS)) {
+ const value = numberAt(r, metric.path);
+ if (value === null) continue;
+ const limit = Math.ceil(Math.max(value * metric.headroom, metric.floor));
+ slot[name] = Math.max(slot[name] ?? 0, limit);
+ }
+ }
+ return { budgets };
+}
+
+interface ProviderCounters {
+ embedRequests: number;
+ embedInputs: number;
+ embedRepeatInputs: number;
+ chatRequests: number;
+ chatRepeatPrompts: number;
+ chatPromptTokens: number;
+ chatCompletionTokens: number;
+ embedUpstreamMs: number;
+ chatUpstreamMs: number;
+ errors: number;
+}
+
+function zeroCounters(): ProviderCounters {
+ return {
+ embedRequests: 0,
+ embedInputs: 0,
+ embedRepeatInputs: 0,
+ chatRequests: 0,
+ chatRepeatPrompts: 0,
+ chatPromptTokens: 0,
+ chatCompletionTokens: 0,
+ embedUpstreamMs: 0,
+ chatUpstreamMs: 0,
+ errors: 0,
+ };
+}
+
+function diffCounters(a: ProviderCounters, b: ProviderCounters): ProviderCounters {
+ const out = zeroCounters();
+ for (const k of Object.keys(out) as (keyof ProviderCounters)[]) out[k] = b[k] - a[k];
+ return out;
+}
+
+class FakeProvider {
+ counters = zeroCounters();
+ inFlight = 0;
+ private seenInputs = new Set();
+ private seenPrompts = new Set();
+ private server: Server | null = null;
+
+ constructor(private port: number, private dims: number, private upstream: string | null = null) {}
+
+ reset(): void {
+ this.counters = zeroCounters();
+ this.seenInputs.clear();
+ this.seenPrompts.clear();
+ }
+
+ snapshot(): ProviderCounters {
+ return { ...this.counters };
+ }
+
+ private vector(text: string, dims: number): number[] {
+ const out = new Array(dims);
+ let seed = createHash("sha256").update(text).digest();
+ let norm = 0;
+ for (let i = 0; i < dims; i++) {
+ if (i % 32 === 0 && i > 0) seed = createHash("sha256").update(seed).digest();
+ out[i] = (seed[i % 32]! - 128) / 128;
+ norm += out[i]! * out[i]!;
+ }
+ const scale = norm > 0 ? 1 / Math.sqrt(norm) : 1;
+ return out.map((v) => v * scale);
+ }
+
+ private chatReply(prompt: string): string {
+ const hash = createHash("sha256").update(prompt).digest("hex");
+ const words = prompt.match(/[a-z][a-z-]{3,}/g) ?? [];
+ const concepts = Array.from(new Set(words.filter((w) => (CONCEPTS as readonly string[]).includes(w)))).slice(0, 4);
+ const nouns = Array.from(new Set(words.filter((w) => (NOUNS as readonly string[]).includes(w)))).slice(0, 3);
+ const marker = prompt.match(/capmark\d+head/)?.[0] ?? `obs-${hash.slice(0, 8)}`;
+ return [
+ "command_run",
+ `${marker} ${nouns.join(" ") || "tool output"}`,
+ `${marker} recorded ${nouns[0] ?? "work"}digest ${hash.slice(0, 12)}`,
+ `${marker} captured a tool run touching ${nouns.join(", ") || "the workspace"} with ${concepts.join(", ") || "no named concepts"}.`,
+ `${concepts.map((c) => `${c}`).join("")}`,
+ "",
+ "5",
+ ].join("\n");
+ }
+
+ private count(url: string, payload: Record): { prompt: string } | null {
+ if (url.endsWith("/embeddings")) {
+ const inputs = (Array.isArray(payload["input"]) ? payload["input"] : [payload["input"]]).map(String);
+ this.counters.embedRequests++;
+ this.counters.embedInputs += inputs.length;
+ for (const t of inputs) {
+ if (this.seenInputs.has(t)) this.counters.embedRepeatInputs++;
+ else this.seenInputs.add(t);
+ }
+ return null;
+ }
+ const messages = Array.isArray(payload["messages"]) ? (payload["messages"] as { content?: unknown }[]) : [];
+ const prompt = messages.map((m) => (typeof m.content === "string" ? m.content : JSON.stringify(m.content))).join("\n");
+ this.counters.chatRequests++;
+ if (this.seenPrompts.has(prompt)) this.counters.chatRepeatPrompts++;
+ else this.seenPrompts.add(prompt);
+ return { prompt };
+ }
+
+ private async forward(url: string, raw: Buffer, payload: Record, res: ServerResponse): Promise {
+ const isEmbed = url.endsWith("/embeddings");
+ if (!isEmbed && !url.endsWith("/chat/completions")) {
+ this.counters.errors++;
+ res.writeHead(404, { "content-type": "application/json" });
+ res.end(JSON.stringify({ error: { message: `bench proxy: unsupported ${url}` } }));
+ return;
+ }
+ this.count(url, payload);
+ const t0 = performance.now();
+ this.inFlight++;
+ try {
+ const up = await fetch(`${this.upstream}${url}`, { method: "POST", headers: { "content-type": "application/json" }, body: raw.toString("utf8"), signal: AbortSignal.timeout(300000) });
+ const text = await up.text();
+ const ms = performance.now() - t0;
+ if (isEmbed) this.counters.embedUpstreamMs += ms;
+ else this.counters.chatUpstreamMs += ms;
+ if (!up.ok) this.counters.errors++;
+ if (!isEmbed && up.ok) {
+ try {
+ const usage = (JSON.parse(text) as { usage?: { prompt_tokens?: number; completion_tokens?: number } }).usage;
+ this.counters.chatPromptTokens += usage?.prompt_tokens ?? 0;
+ this.counters.chatCompletionTokens += usage?.completion_tokens ?? 0;
+ } catch {}
+ }
+ res.writeHead(up.status, { "content-type": up.headers.get("content-type") ?? "application/json" });
+ res.end(text);
+ } catch (err) {
+ this.counters.errors++;
+ res.writeHead(502, { "content-type": "application/json" });
+ res.end(JSON.stringify({ error: { message: `bench proxy: ${err instanceof Error ? err.message : String(err)}` } }));
+ } finally {
+ this.inFlight--;
+ }
+ }
+
+ start(): Promise {
+ this.server = createServer((req, res) => {
+ const chunks: Buffer[] = [];
+ req.on("data", (c: Buffer) => chunks.push(c));
+ req.on("end", () => {
+ let payload: Record = {};
+ const raw = Buffer.concat(chunks);
+ try {
+ payload = JSON.parse(raw.toString("utf8") || "{}");
+ } catch {}
+ const url = req.url ?? "";
+ if (this.upstream) {
+ void this.forward(url, raw, payload, res);
+ return;
+ }
+ if (url.endsWith("/embeddings")) {
+ const inputs = (Array.isArray(payload["input"]) ? payload["input"] : [payload["input"]]).map(String);
+ const dims = typeof payload["dimensions"] === "number" ? (payload["dimensions"] as number) : this.dims;
+ this.count(url, payload);
+ const total = inputs.reduce((s, t) => s + Math.ceil(t.length / 4), 0);
+ res.writeHead(200, { "content-type": "application/json" });
+ res.end(
+ JSON.stringify({
+ object: "list",
+ data: inputs.map((t, index) => ({ object: "embedding", index, embedding: this.vector(t, dims) })),
+ model: String(payload["model"] ?? "fake-embedding"),
+ usage: { prompt_tokens: total, total_tokens: total },
+ }),
+ );
+ return;
+ }
+ if (url.endsWith("/chat/completions")) {
+ const { prompt } = this.count(url, payload)!;
+ const content = this.chatReply(prompt);
+ const promptTokens = Math.ceil(prompt.length / 4);
+ const completionTokens = Math.ceil(content.length / 4);
+ this.counters.chatPromptTokens += promptTokens;
+ this.counters.chatCompletionTokens += completionTokens;
+ res.writeHead(200, { "content-type": "application/json" });
+ res.end(
+ JSON.stringify({
+ id: `chatcmpl-${createHash("sha256").update(prompt).digest("hex").slice(0, 12)}`,
+ object: "chat.completion",
+ model: String(payload["model"] ?? "fake-chat"),
+ choices: [{ index: 0, finish_reason: "stop", message: { role: "assistant", content } }],
+ usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens },
+ }),
+ );
+ return;
+ }
+ this.counters.errors++;
+ res.writeHead(404, { "content-type": "application/json" });
+ res.end(JSON.stringify({ error: { message: `fake provider: unsupported ${url}` } }));
+ });
+ });
+ return new Promise((ok, fail) => {
+ this.server!.once("error", fail);
+ this.server!.listen(this.port, "127.0.0.1", () => ok());
+ });
+ }
+
+ stop(): Promise {
+ return new Promise((ok) => (this.server ? this.server.close(() => ok()) : ok()));
+ }
+}
+
+interface ProcRow {
+ pid: number;
+ ppid: number;
+ rssKiB: number;
+ cpuSec: number;
+ comm: string;
+}
+
+function parseCpu(raw: string): number {
+ const [clock, ...rest] = raw.includes("-") ? raw.split("-").reverse() : [raw];
+ const days = rest.length > 0 ? parseInt(rest[0]!, 10) || 0 : 0;
+ const parts = clock!.split(":").map((p) => parseFloat(p) || 0);
+ let sec = 0;
+ for (const p of parts) sec = sec * 60 + p;
+ return sec + days * 86400;
+}
+
+async function psRows(): Promise {
+ const { stdout } = await execFileAsync("ps", ["-A", "-o", "pid=,ppid=,rss=,time=,comm="], { timeout: 10000, maxBuffer: 8 * 1024 * 1024 });
+ const rows: ProcRow[] = [];
+ for (const line of stdout.split("\n")) {
+ const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
+ if (!m) continue;
+ rows.push({ pid: +m[1]!, ppid: +m[2]!, rssKiB: +m[3]!, cpuSec: parseCpu(m[4]!), comm: m[5]! });
+ }
+ return rows;
+}
+
+function treeOf(rows: ProcRow[], roots: number[]): ProcRow[] {
+ const byParent = new Map();
+ for (const r of rows) {
+ const list = byParent.get(r.ppid) ?? [];
+ list.push(r);
+ byParent.set(r.ppid, list);
+ }
+ const seen = new Set();
+ const out: ProcRow[] = [];
+ const stack = rows.filter((r) => roots.includes(r.pid));
+ while (stack.length > 0) {
+ const r = stack.pop()!;
+ if (seen.has(r.pid)) continue;
+ seen.add(r.pid);
+ out.push(r);
+ for (const c of byParent.get(r.pid) ?? []) stack.push(c);
+ }
+ return out;
+}
+
+function roleOf(r: ProcRow): "engine" | "worker" | "other" {
+ const name = basename(r.comm);
+ if (name === "iii" || name.startsWith("iii")) return "engine";
+ if (name === "node" || name.includes("node")) return "worker";
+ return "other";
+}
+
+interface TreeSample {
+ totalKiB: number;
+ engineKiB: number;
+ workerKiB: number;
+ cpuSec: number;
+ pids: number[];
+}
+
+function summarizeTree(tree: ProcRow[]): TreeSample {
+ const s: TreeSample = { totalKiB: 0, engineKiB: 0, workerKiB: 0, cpuSec: 0, pids: tree.map((r) => r.pid) };
+ for (const r of tree) {
+ s.totalKiB += r.rssKiB;
+ s.cpuSec += r.cpuSec;
+ const role = roleOf(r);
+ if (role === "engine") s.engineKiB += r.rssKiB;
+ else if (role === "worker") s.workerKiB += r.rssKiB;
+ }
+ return s;
+}
+
+interface RssWindow {
+ samples: number;
+ peakTotalKiB: number;
+ peakEngineKiB: number;
+ peakWorkerKiB: number;
+ meanTotalKiB: number;
+ cpuSecStart: number;
+ cpuSecEnd: number;
+}
+
+class RssSampler {
+ private timer: NodeJS.Timeout | null = null;
+ private busy = false;
+ private window: RssWindow | null = null;
+ private sum = 0;
+
+ constructor(private roots: () => number[], private intervalMs = 250) {}
+
+ async sampleOnce(): Promise {
+ return summarizeTree(treeOf(await psRows(), this.roots()));
+ }
+
+ async begin(): Promise {
+ const first = await this.sampleOnce();
+ this.sum = first.totalKiB;
+ this.window = {
+ samples: 1,
+ peakTotalKiB: first.totalKiB,
+ peakEngineKiB: first.engineKiB,
+ peakWorkerKiB: first.workerKiB,
+ meanTotalKiB: first.totalKiB,
+ cpuSecStart: first.cpuSec,
+ cpuSecEnd: first.cpuSec,
+ };
+ this.timer = setInterval(() => void this.tick(), this.intervalMs);
+ }
+
+ private async tick(): Promise {
+ if (this.busy || !this.window) return;
+ this.busy = true;
+ try {
+ const s = await this.sampleOnce();
+ const w = this.window;
+ if (!w) return;
+ w.samples++;
+ this.sum += s.totalKiB;
+ w.peakTotalKiB = Math.max(w.peakTotalKiB, s.totalKiB);
+ w.peakEngineKiB = Math.max(w.peakEngineKiB, s.engineKiB);
+ w.peakWorkerKiB = Math.max(w.peakWorkerKiB, s.workerKiB);
+ w.cpuSecEnd = Math.max(w.cpuSecEnd, s.cpuSec);
+ } catch {
+ } finally {
+ this.busy = false;
+ }
+ }
+
+ stop(): void {
+ if (this.timer) clearInterval(this.timer);
+ this.timer = null;
+ this.window = null;
+ }
+
+ async end(): Promise {
+ if (this.timer) clearInterval(this.timer);
+ this.timer = null;
+ await this.tick();
+ const w = this.window!;
+ this.window = null;
+ w.meanTotalKiB = Math.round(this.sum / w.samples);
+ return { ...w, cpuSec: +(w.cpuSecEnd - w.cpuSecStart).toFixed(2) };
+ }
+}
+
+function sleep(ms: number): Promise {
+ return new Promise((r) => setTimeout(r, ms));
+}
+
+function portOpen(port: number): Promise {
+ return new Promise((ok) => {
+ const sock = createConnection({ port, host: "127.0.0.1" });
+ sock.setTimeout(500);
+ sock.once("connect", () => {
+ sock.destroy();
+ ok(true);
+ });
+ sock.once("timeout", () => {
+ sock.destroy();
+ ok(false);
+ });
+ sock.once("error", () => ok(false));
+ });
+}
+
+interface HttpResult {
+ status: number;
+ bytes: number;
+ ms: number;
+ body: unknown;
+ text: string;
+}
+
+let benchSecretFile: string | null = null;
+
+function benchAuth(): Record {
+ try {
+ const secret = benchSecretFile ? readFileSync(benchSecretFile, "utf8").trim() : "";
+ return secret ? { authorization: `Bearer ${secret}` } : {};
+ } catch {
+ return {};
+ }
+}
+
+async function http(base: string, method: string, path: string, body?: unknown, timeoutMs = 60000): Promise {
+ const t0 = performance.now();
+ const res = await fetch(`${base}${path}`, {
+ method,
+ headers: { ...benchAuth(), ...(body === undefined ? { accept: "application/json" } : { "content-type": "application/json", accept: "application/json" }) },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ const text = await res.text();
+ const ms = performance.now() - t0;
+ let parsed: unknown = text;
+ try {
+ parsed = JSON.parse(text);
+ } catch {}
+ return { status: res.status, bytes: Buffer.byteLength(text, "utf8"), ms, body: parsed, text };
+}
+
+function dist(values: number[]): { n: number; p50: number; p95: number; p99: number; max: number; mean: number } {
+ const sorted = [...values].sort((a, b) => a - b);
+ const r = (v: number) => (Number.isFinite(v) ? +v.toFixed(2) : NaN);
+ const mean = sorted.length ? sorted.reduce((s, v) => s + v, 0) / sorted.length : NaN;
+ return {
+ n: sorted.length,
+ p50: r(pXX(sorted, 50)),
+ p95: r(pXX(sorted, 95)),
+ p99: r(pXX(sorted, 99)),
+ max: r(pXX(sorted, 100)),
+ mean: r(mean),
+ };
+}
+
+type Category = "source" | "summary" | "index" | "queue" | "failed_delivery" | "diagnostic" | "config" | "stream" | "other";
+
+function categorize(scope: string): Category {
+ if (/dlq|dead|failed/i.test(scope)) return "failed_delivery";
+ if (/queue/i.test(scope)) return "queue";
+ if (/^mem:(obs|enriched|image-refs|image-embeddings):?/.test(scope) || scope === "mem:sessions") return "source";
+ if (/^mem:(index|idx|emb|latent)(:|$)/.test(scope) || /^mem:graph:(name-index|edge-key|node-degree)$/.test(scope)) return "index";
+ if (/^mem:(audit|health|metrics|access|recent-searches|retention|diagnostics|signals|sentinels)(:|$)/.test(scope)) return "diagnostic";
+ if (/^mem:(config|state)(:|$)/.test(scope)) return "config";
+ if (scope.startsWith("mem:")) return "summary";
+ return "other";
+}
+
+function scopeFamily(scope: string): string {
+ return scope
+ .replace(/^mem:obs:.+$/, "mem:obs:*")
+ .replace(/^mem:enriched:.+$/, "mem:enriched:*")
+ .replace(/^mem:idx:obs:\d+$/, "mem:idx:obs:*")
+ .replace(/^mem:audit:\d{4}-\d{2}$/, "mem:audit:")
+ .replace(/^(mem:index:bm25:vec:).+$/, "$1*")
+ .replace(/^mem:emb:.+$/, "mem:emb:*");
+}
+
+interface DiskReport {
+ totalBytes: number;
+ byCategory: Record;
+ byFamily: Record;
+ files: number;
+}
+
+function walk(dir: string, visit: (path: string, size: number) => void): void {
+ if (!existsSync(dir)) return;
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const p = join(dir, entry.name);
+ if (entry.isDirectory()) walk(p, visit);
+ else if (entry.isFile()) {
+ try {
+ visit(p, statSync(p).size);
+ } catch {}
+ }
+ }
+}
+
+function measureDisk(dataDir: string): DiskReport {
+ const report: DiskReport = {
+ totalBytes: 0,
+ byCategory: { source: 0, summary: 0, index: 0, queue: 0, failed_delivery: 0, diagnostic: 0, config: 0, stream: 0, other: 0 },
+ byFamily: {},
+ files: 0,
+ };
+ walk(dataDir, (p, size) => {
+ report.totalBytes += size;
+ report.files++;
+ const rel = p.slice(dataDir.length + 1);
+ const [top, ...rest] = rel.split("/");
+ let scope = rel;
+ let category: Category = "other";
+ if (top === "state_store.db" && rest.length > 0) {
+ scope = decodeURIComponent(rest.join("/").replace(/\.bin$/, ""));
+ category = categorize(scope);
+ } else if (top === "stream_store") {
+ scope = `stream:${decodeURIComponent(rest.join("/").replace(/\.bin$/, ""))}`;
+ category = "stream";
+ } else if (/\.ya?ml$/.test(rel)) {
+ category = "config";
+ } else {
+ category = categorize(rel);
+ }
+ report.byCategory[category] += size;
+ const fam = scopeFamily(scope);
+ report.byFamily[fam] = (report.byFamily[fam] ?? 0) + size;
+ });
+ return report;
+}
+
+function diskDelta(a: DiskReport, b: DiskReport): DiskReport {
+ const out: DiskReport = { totalBytes: b.totalBytes - a.totalBytes, byCategory: { ...b.byCategory }, byFamily: {}, files: b.files - a.files };
+ for (const k of Object.keys(out.byCategory) as Category[]) out.byCategory[k] = b.byCategory[k] - a.byCategory[k];
+ for (const k of new Set([...Object.keys(a.byFamily), ...Object.keys(b.byFamily)])) {
+ out.byFamily[k] = (b.byFamily[k] ?? 0) - (a.byFamily[k] ?? 0);
+ }
+ return out;
+}
+
+async function settledDisk(dataDir: string, quietMs = 3000, timeoutMs = 60000): Promise {
+ const start = Date.now();
+ let last = measureDisk(dataDir);
+ let stableSince = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ await sleep(1000);
+ const now = measureDisk(dataDir);
+ if (now.totalBytes !== last.totalBytes || now.files !== last.files) {
+ last = now;
+ stableSince = Date.now();
+ } else if (Date.now() - stableSince >= quietMs) {
+ return now;
+ }
+ }
+ return last;
+}
+
+interface BootLog {
+ bm25Docs: number | null;
+ bm25RebuildMs: number | null;
+ vectorsLoaded: number | null;
+ vectorBackfillQueued: number | null;
+ vectorBackfillAwaitingOptIn: number | null;
+ pendingLogRecoveredVectors: number;
+ spoolRecovered: number;
+ spoolAlreadyStored: number;
+ inboxRecovered: number;
+}
+
+function parseBootLog(text: string): BootLog {
+ const bm = [...text.matchAll(/Rebuilt BM25 index from stored content \((\d+) docs in (\d+) ms\)/g)].pop();
+ const vec = [...text.matchAll(/Loaded persisted vector index \((\d+) vectors\)/g)].pop();
+ const back = [...text.matchAll(/(?:Backfilling|Re-embedding) (\d+) (?:missing )?vectors/g)].pop();
+ const optIn = [...text.matchAll(/Vector backfill needs (\d+) embeddings/g)].pop();
+ const replay = [...text.matchAll(/Recovered (\d+) vectors and \d+ removals written after the last index save/g)].pop();
+ const spool = [...text.matchAll(/Capture spool: (\d+) recovered, (\d+) already stored/g)].pop();
+ const inbox = [...text.matchAll(/Capture inbox: (\d+) of \d+ unfinished observations stored/g)].pop();
+ return {
+ bm25Docs: bm ? +bm[1]! : null,
+ bm25RebuildMs: bm ? +bm[2]! : null,
+ vectorsLoaded: vec ? +vec[1]! : 0,
+ vectorBackfillQueued: back ? +back[1]! : 0,
+ vectorBackfillAwaitingOptIn: optIn ? +optIn[1]! : 0,
+ pendingLogRecoveredVectors: replay ? +replay[1]! : 0,
+ spoolRecovered: spool ? +spool[1]! : 0,
+ spoolAlreadyStored: spool ? +spool[2]! : 0,
+ inboxRecovered: inbox ? +inbox[1]! : 0,
+ };
+}
+
+interface Instance {
+ child: ChildProcess;
+ logPath: string;
+ logOffset: number;
+ base: string;
+}
+
+class Harness {
+ private instance: Instance | null = null;
+ private knownPids = new Set();
+ private lastLogPath: string | null = null;
+ readonly sampler: RssSampler;
+ readonly home: string;
+ readonly dataDir: string;
+ readonly cwd: string;
+ readonly base: string;
+
+ constructor(private cfg: Config, private profile: Profile, private runDir: string) {
+ this.home = join(runDir, "home");
+ benchSecretFile = join(this.home, ".agentmemory", "secret");
+ this.dataDir = join(runDir, "data");
+ this.cwd = join(runDir, PROJECT);
+ this.base = `http://127.0.0.1:${cfg.restPort}/agentmemory`;
+ this.sampler = new RssSampler(() => this.roots());
+ }
+
+ roots(): number[] {
+ return [...this.knownPids];
+ }
+
+ prepare(): void {
+ for (const d of [this.home, this.dataDir, this.cwd, join(this.home, ".agentmemory", "bin")]) mkdirSync(d, { recursive: true });
+ const target = join(this.home, ".agentmemory", "bin", "iii");
+ copyFileSync(this.cfg.iiiBin, target);
+ chmodSync(target, 0o755);
+ }
+
+ env(): NodeJS.ProcessEnv {
+ const keep = ["PATH", "TMPDIR", "LANG", "TERM", "SHELL", "USER", "LOGNAME"];
+ const env: NodeJS.ProcessEnv = {};
+ for (const k of keep) if (process.env[k] !== undefined) env[k] = process.env[k];
+ env["PATH"] = `${join(this.home, ".agentmemory", "bin")}:${process.env["PATH"] ?? ""}`;
+ Object.assign(env, {
+ HOME: this.home,
+ CI: "1",
+ NO_COLOR: "1",
+ XDG_CONFIG_HOME: join(this.home, ".config"),
+ XDG_DATA_HOME: join(this.home, ".local", "share"),
+ III_ENGINE_PORT: String(this.cfg.enginePort),
+ AGENTMEMORY_METRICS_PORT: String(this.cfg.restPort + 3),
+ AGENTMEMORY_PROJECT_NAME: PROJECT,
+ AGENTMEMORY_AUTO_COMPRESS: this.profile.autoCompress ? "true" : "false",
+ AGENTMEMORY_INJECT_CONTEXT: "false",
+ });
+ if (this.profile.embeddings) {
+ Object.assign(env, {
+ OPENAI_API_KEY: "bench-fake-key",
+ OPENAI_BASE_URL: `http://127.0.0.1:${this.cfg.fakePort}`,
+ OPENAI_EMBEDDING_DIMENSIONS: String(this.cfg.dims),
+ OPENAI_EMBEDDING_MODEL: this.cfg.embedModel,
+ OPENAI_API_KEY_FOR_LLM: this.profile.llm ? "true" : "false",
+ });
+ if (this.profile.llm) env["OPENAI_MODEL"] = this.cfg.chatModel;
+ }
+ if (this.cfg.stateBackend === "redis") {
+ env["AGENTMEMORY_STATE_BACKEND"] = "redis";
+ env["AGENTMEMORY_REDIS_URL"] = this.cfg.redisUrl!;
+ }
+ return env;
+ }
+
+ hookEnv(inject: boolean): NodeJS.ProcessEnv {
+ return {
+ PATH: process.env["PATH"],
+ HOME: this.home,
+ AGENTMEMORY_URL: `http://127.0.0.1:${this.cfg.restPort}`,
+ AGENTMEMORY_PROJECT_NAME: PROJECT,
+ AGENTMEMORY_INJECT_CONTEXT: inject ? "true" : "false",
+ };
+ }
+
+ async start(label: string): Promise<{ readyMs: number; indexReadyMs: number | null; boot: BootLog }> {
+ for (const port of [this.cfg.restPort, this.cfg.restPort + 1, this.cfg.restPort + 2, this.cfg.enginePort]) {
+ if (await portOpen(port)) throw new Error(`port ${port} is in use before ${label}; refusing to share it`);
+ }
+ const logPath = join(this.runDir, `cli-${label}.log`);
+ this.lastLogPath = logPath;
+ const fd = openSync(logPath, "a");
+ const t0 = performance.now();
+ const child = spawn(
+ process.execPath,
+ [join(this.cfg.distDir, "cli.mjs"), "--port", String(this.cfg.restPort), "--data-dir", this.dataDir, "--verbose"],
+ { cwd: this.cwd, env: this.env(), stdio: ["ignore", fd, fd] },
+ );
+ closeSync(fd);
+ this.knownPids.add(child.pid!);
+ this.instance = { child, logPath, logOffset: 0, base: this.base };
+ let readyMs = -1;
+ while (performance.now() - t0 < this.cfg.readyTimeoutMs) {
+ if (child.exitCode !== null) throw new Error(`cli exited with ${child.exitCode} during ${label}; see ${logPath}`);
+ try {
+ const r = await http(this.base, "GET", "/livez", undefined, 2000);
+ if (r.status === 200) {
+ readyMs = performance.now() - t0;
+ break;
+ }
+ } catch {}
+ await sleep(100);
+ }
+ if (readyMs < 0) throw new Error(`instance not ready within ${this.cfg.readyTimeoutMs} ms (${label}); see ${logPath}`);
+ let indexReadyMs: number | null = null;
+ while (performance.now() - t0 < this.cfg.readyTimeoutMs) {
+ if (/Rebuilt BM25 index from stored content/.test(readFileSync(logPath, "utf8"))) {
+ indexReadyMs = performance.now() - t0;
+ break;
+ }
+ await sleep(100);
+ }
+ await this.adoptTree();
+ return { readyMs: Math.round(readyMs), indexReadyMs: indexReadyMs === null ? null : Math.round(indexReadyMs), boot: parseBootLog(readFileSync(logPath, "utf8")) };
+ }
+
+ bootLog(): BootLog | null {
+ return this.lastLogPath && existsSync(this.lastLogPath) ? parseBootLog(readFileSync(this.lastLogPath, "utf8")) : null;
+ }
+
+ private spoolFiles(): string[] {
+ const files: string[] = [];
+ const visit = (dir: string, inSpool: boolean) => {
+ if (!existsSync(dir)) return;
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const p = join(dir, entry.name);
+ if (entry.isDirectory()) visit(p, inSpool || entry.name === "capture-spool");
+ else if (inSpool) files.push(p);
+ }
+ };
+ visit(this.home, false);
+ return files;
+ }
+
+ spoolRecords(): number {
+ return this.spoolFiles()
+ .filter((p) => p.endsWith(".jsonl"))
+ .reduce((n, p) => n + readFileSync(p, "utf8").split("\n").filter((l) => l.trim()).length, 0);
+ }
+
+ spoolStats(): Record {
+ const out: Record = {};
+ for (const p of this.spoolFiles().filter((f) => f.endsWith(".stats.json"))) {
+ try {
+ for (const [k, v] of Object.entries(JSON.parse(readFileSync(p, "utf8")) as Record)) {
+ if (typeof v === "number") out[k] = (out[k] ?? 0) + v;
+ }
+ } catch {}
+ }
+ return out;
+ }
+
+ async adoptTree(): Promise {
+ const rows = await psRows();
+ for (const r of treeOf(rows, this.roots())) this.knownPids.add(r.pid);
+ const pidfile = join(this.home, ".agentmemory", "iii.pid");
+ if (existsSync(pidfile)) {
+ const pid = parseInt(readFileSync(pidfile, "utf8").trim(), 10);
+ if (Number.isFinite(pid) && rows.some((r) => r.pid === pid && roleOf(r) === "engine")) this.knownPids.add(pid);
+ }
+ }
+
+ private async alive(): Promise {
+ const rows = await psRows();
+ const live = new Set(rows.map((r) => r.pid));
+ return this.roots().filter((p) => live.has(p));
+ }
+
+ private async waitPortsFree(timeoutMs: number): Promise {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ const busy = await Promise.all([this.cfg.restPort, this.cfg.restPort + 1, this.cfg.enginePort].map(portOpen));
+ if (!busy.some(Boolean)) return;
+ await sleep(250);
+ }
+ }
+
+ async forceKill(): Promise {
+ await this.adoptTree();
+ for (const pid of await this.alive()) {
+ try {
+ process.kill(pid, "SIGKILL");
+ } catch {}
+ }
+ await sleep(500);
+ this.knownPids.clear();
+ this.instance = null;
+ await this.waitPortsFree(15000);
+ }
+
+ async stop(): Promise {
+ await this.adoptTree();
+ const cli = this.instance?.child.pid;
+ if (cli) {
+ try {
+ process.kill(cli, "SIGTERM");
+ } catch {}
+ }
+ const deadline = Date.now() + 20000;
+ while (Date.now() < deadline) {
+ const left = await this.alive();
+ if (left.length === 0) break;
+ if (Date.now() > deadline - 12000) {
+ for (const pid of left) {
+ try {
+ process.kill(pid, "SIGTERM");
+ } catch {}
+ }
+ }
+ await sleep(500);
+ }
+ for (const pid of await this.alive()) {
+ try {
+ process.kill(pid, "SIGKILL");
+ } catch {}
+ }
+ this.knownPids.clear();
+ this.instance = null;
+ await this.waitPortsFree(15000);
+ }
+}
+
+interface HookRun {
+ ms: number;
+ stdoutBytes: number;
+ stderrBytes: number;
+ exitCode: number | null;
+}
+
+function runHook(script: string, payload: unknown, env: NodeJS.ProcessEnv, timeoutMs = 15000, cwd?: string): Promise {
+ return new Promise((ok) => {
+ const t0 = performance.now();
+ const child = spawn(process.execPath, [script], { env, cwd, stdio: ["pipe", "pipe", "pipe"] });
+ let out = 0;
+ let err = 0;
+ const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+ child.stdout.on("data", (c: Buffer) => (out += c.length));
+ child.stderr.on("data", (c: Buffer) => (err += c.length));
+ child.on("close", (code) => {
+ clearTimeout(timer);
+ ok({ ms: performance.now() - t0, stdoutBytes: out, stderrBytes: err, exitCode: code });
+ });
+ child.stdin.end(JSON.stringify(payload));
+ });
+}
+
+function sessionIdFor(profile: Profile, n: number, j: number): string {
+ return `cc-${profile.name}-${n}-s${j}`;
+}
+
+function observeBody(sessionId: string, cwd: string, cap: ToolCapture) {
+ return {
+ hookType: "post_tool_use",
+ sessionId,
+ project: PROJECT,
+ cwd,
+ timestamp: new Date().toISOString(),
+ data: { tool_name: cap.toolName, tool_input: cap.toolInput, tool_output: cap.toolOutput },
+ };
+}
+
+function hookBody(sessionId: string, cwd: string, cap: ToolCapture) {
+ return {
+ session_id: sessionId,
+ transcript_path: "/dev/null",
+ cwd,
+ hook_event_name: "PostToolUse",
+ tool_name: cap.toolName,
+ tool_input: cap.toolInput,
+ tool_response: cap.toolOutput,
+ };
+}
+
+async function drive(concurrency: number, total: number, fn: (i: number) => Promise): Promise {
+ let next = 0;
+ await Promise.all(
+ Array.from({ length: Math.min(concurrency, Math.max(total, 1)) }, async () => {
+ while (true) {
+ const i = next++;
+ if (i >= total) return;
+ await fn(i);
+ }
+ }),
+ );
+}
+
+interface Evidence {
+ logicalObservations: number;
+ bm25Documents: number | null;
+ vectorDocuments: number | null;
+ pendingVectorBackfill: number | null;
+ sessionsListed: number;
+ sampled: number;
+ markerSearchHits: number;
+ sourceTailRetained: number;
+ sourceHeadRetained: number;
+}
+
+async function collectEvidence(h: Harness, profile: Profile, n: number, perSession: number, caps: Map, sample: number[]): Promise {
+ const sessions = Math.ceil(n / perSession);
+ let logical = 0;
+ let listed = 0;
+ for (let j = 0; j < sessions; j++) {
+ const r = await http(h.base, "GET", `/observations?sessionId=${encodeURIComponent(sessionIdFor(profile, n, j))}&limit=1`, undefined, 120000);
+ const body = r.body as { total?: number };
+ if (r.status === 200) listed++;
+ logical += typeof body?.total === "number" ? body.total : 0;
+ }
+ let hits = 0;
+ let tail = 0;
+ let head = 0;
+ const replayCache = new Map();
+ for (const i of sample) {
+ const cap = caps.get(i)!;
+ const s = await http(h.base, "POST", "/search", { query: cap.headMarker, limit: 5 }, 120000);
+ if (s.text.includes(cap.headMarker)) hits++;
+ const j = Math.floor(i / perSession);
+ if (!replayCache.has(j)) {
+ const rl = await http(h.base, "GET", `/replay/load?sessionId=${encodeURIComponent(sessionIdFor(profile, n, j))}`, undefined, 120000);
+ replayCache.set(j, rl.text);
+ }
+ const text = replayCache.get(j)!;
+ if (text.includes(cap.tailMarker)) tail++;
+ if (text.includes(cap.headMarker)) head++;
+ }
+ const status = await http(h.base, "GET", "/status", undefined, 120000);
+ const index = (status.body as { index?: Record })?.index ?? {};
+ const num = (v: unknown) => (typeof v === "number" ? v : null);
+ return {
+ logicalObservations: logical,
+ bm25Documents: num(index["bm25Documents"]),
+ vectorDocuments: num(index["vectorDocuments"]),
+ pendingVectorBackfill: num(index["pendingVectorBackfill"]),
+ sessionsListed: listed, sampled: sample.length, markerSearchHits: hits, sourceTailRetained: tail, sourceHeadRetained: head };
+}
+
+async function quiesce(h: Harness, fake: FakeProvider, timeoutMs: number): Promise<{ ms: number; disk: DiskReport }> {
+ const t0 = performance.now();
+ let last = JSON.stringify(fake.snapshot());
+ let stableSince = Date.now();
+ while (performance.now() - t0 < timeoutMs) {
+ await sleep(1000);
+ const now = JSON.stringify(fake.snapshot());
+ if (now !== last || fake.inFlight > 0) {
+ last = now;
+ stableSince = Date.now();
+ } else if (Date.now() - stableSince >= 3000) break;
+ }
+ const disk = await settledDisk(h.dataDir, 3000, Math.max(10000, timeoutMs - (performance.now() - t0)));
+ return { ms: Math.round(performance.now() - t0), disk };
+}
+
+function tokensOf(body: unknown): number | null {
+ if (!body || typeof body !== "object") return null;
+ const b = body as Record;
+ if (typeof b["tokens_used"] === "number") return b["tokens_used"] as number;
+ if (typeof b["tokens"] === "number") return b["tokens"] as number;
+ if (typeof b["tokensUsed"] === "number") return b["tokensUsed"] as number;
+ return null;
+}
+
+async function measureContext(h: Harness, profile: Profile, n: number, caps: Map, cfg: Config) {
+ const rng = mulberry32(cfg.seed ^ 0x51ed27);
+ const queries = Array.from({ length: 8 }, () => `${CONCEPTS[Math.floor(rng() * CONCEPTS.length)]} ${NOUNS[Math.floor(rng() * NOUNS.length)]}`);
+ const rows: Record = {};
+ const add = (k: string, r: HttpResult) => {
+ const row = (rows[k] ??= { bytes: [], tokens: [], ms: [], results: [] });
+ row.bytes.push(r.bytes);
+ const t = tokensOf(r.body);
+ if (t !== null) row.tokens.push(t);
+ row.ms.push(r.ms);
+ const results = (r.body as { results?: unknown[] })?.results;
+ row.results.push(Array.isArray(results) ? results.length : 0);
+ };
+ for (const q of queries) {
+ add("search_full", await http(h.base, "POST", "/search", { query: q, limit: cfg.searchLimit }, 120000));
+ add("search_compact", await http(h.base, "POST", "/search", { query: q, limit: cfg.searchLimit, format: "compact" }, 120000));
+ add("search_narrative", await http(h.base, "POST", "/search", { query: q, limit: cfg.searchLimit, format: "narrative" }, 120000));
+ add("smart_search", await http(h.base, "POST", "/smart-search", { query: q, limit: cfg.searchLimit }, 120000));
+ }
+ const ctx = await http(h.base, "POST", "/context", { sessionId: sessionIdFor(profile, n, 0), project: PROJECT, budget: cfg.contextBudget }, 120000);
+ add("context", ctx);
+ const summarize = (k: string) => {
+ const r = rows[k]!;
+ return {
+ calls: r.bytes.length,
+ bytes: dist(r.bytes),
+ serverTokenEstimate: r.tokens.length ? dist(r.tokens) : "unknown",
+ latencyMs: dist(r.ms),
+ results: dist(r.results),
+ };
+ };
+ const hookDir = join(cfg.distDir, "hooks");
+ const firstRead = [...caps.values()].find((c) => c.toolName === "Read");
+ const preTool = firstRead
+ ? { session_id: sessionIdFor(profile, n, 0), cwd: h.cwd, hook_event_name: "PreToolUse", tool_name: "Read", tool_input: firstRead.toolInput }
+ : { session_id: sessionIdFor(profile, n, 0), cwd: h.cwd, hook_event_name: "PreToolUse", tool_name: "Read", tool_input: { file_path: "src/cache/index.ts" } };
+ const hooks: Record = {};
+ for (const inject of [false, true]) {
+ const tag = inject ? "on" : "off";
+ hooks[`session_start_inject_${tag}`] = await runHook(
+ join(hookDir, "session-start.mjs"),
+ { session_id: `cc-${profile.name}-${n}-ctx-${tag}`, cwd: h.cwd, hook_event_name: "SessionStart", source: "startup" },
+ h.hookEnv(inject),
+ );
+ hooks[`pre_tool_use_inject_${tag}`] = await runHook(join(hookDir, "pre-tool-use.mjs"), preTool, h.hookEnv(inject));
+ }
+ return {
+ declaredContextBudgetTokens: cfg.contextBudget,
+ searchLimit: cfg.searchLimit,
+ queries,
+ endpoints: Object.fromEntries(Object.keys(rows).map((k) => [k, summarize(k)])),
+ hookStdout: Object.fromEntries(Object.entries(hooks).map(([k, v]) => [k, { stdoutBytes: v.stdoutBytes, ms: Math.round(v.ms), exitCode: v.exitCode }])),
+ };
+}
+
+async function redisCli(url: string, args: string[]): Promise {
+ const { stdout } = await execFileAsync("redis-cli", ["-u", url, ...args], { timeout: 60000, maxBuffer: 16 * 1024 * 1024 });
+ return stdout;
+}
+
+async function redisStats(url: string): Promise<{ usedMemoryBytes: number | null; keys: number | null; serverRssKiB: number | null }> {
+ const info = await redisCli(url, ["INFO"]);
+ const field = (k: string) => {
+ const m = info.match(new RegExp(`^${k}:(\\d+)`, "m"));
+ return m ? +m[1]! : null;
+ };
+ const keys = parseInt((await redisCli(url, ["DBSIZE"])).trim(), 10);
+ const pid = field("process_id");
+ const rows = pid === null ? [] : await psRows();
+ return { usedMemoryBytes: field("used_memory"), keys: Number.isFinite(keys) ? keys : null, serverRssKiB: rows.find((r) => r.pid === pid)?.rssKiB ?? null };
+}
+
+async function providerProcessRssKiB(): Promise {
+ return (await psRows()).filter((r) => basename(r.comm).startsWith("ollama")).reduce((s, r) => s + r.rssKiB, 0);
+}
+
+async function prepareRun(cfg: Config, profile: Profile, n: number): Promise<{ runDir: string; variant: string; out: Record }> {
+ const variant = variantName(profile, cfg);
+ const runDir = join(cfg.root, `${variant.replace(/[^a-z0-9-]+/gi, "_")}-${n}`);
+ rmSync(runDir, { recursive: true, force: true });
+ mkdirSync(runDir, { recursive: true });
+ if (cfg.stateBackend === "redis") await redisCli(cfg.redisUrl!, ["FLUSHALL"]);
+ const out: Record = {
+ profile: profile.name,
+ variant,
+ profileDescription: profile.description,
+ observations: n,
+ provider: cfg.provider,
+ stateBackend: cfg.stateBackend,
+ scenario: cfg.scenario,
+ embeddings: profile.embeddings,
+ };
+ return { runDir, variant, out };
+}
+
+async function waitDrained(h: Harness, fake: FakeProvider, embeddings: boolean, n: number, timeoutMs: number): Promise {
+ const t0 = Date.now();
+ while (Date.now() - t0 < timeoutMs) {
+ const status = await http(h.base, "GET", "/status", undefined, 120000).catch(() => null);
+ const index = (status?.body as { index?: Record } | undefined)?.index ?? {};
+ const vectors = typeof index["vectorDocuments"] === "number" ? (index["vectorDocuments"] as number) : 0;
+ if (h.spoolRecords() === 0 && (!embeddings || vectors >= n)) break;
+ await sleep(1000);
+ }
+ await quiesce(h, fake, Math.max(10000, timeoutMs - (Date.now() - t0)));
+}
+
+async function runCrashOffline(cfg: Config, profile: Profile, n: number, fake: FakeProvider) {
+ const { runDir, variant, out } = await prepareRun(cfg, profile, n);
+ const h = new Harness(cfg, profile, runDir);
+ h.prepare();
+ fake.reset();
+ const log = (msg: string) => process.stderr.write(`[capture-costs] ${variant} n=${n} ${msg}\n`);
+ try {
+ log("cold start");
+ out["coldStart"] = await h.start("cold");
+ const rng = mulberry32(cfg.seed);
+ const caps = new Map();
+ for (let i = 0; i < n; i++) {
+ const size = cfg.outputMin + Math.floor(rng() * Math.max(1, cfg.outputMax - cfg.outputMin));
+ caps.set(i, buildToolCapture(rng, i, size));
+ }
+ const sessions = Math.ceil(n / cfg.perSession);
+ for (let j = 0; j < sessions; j++) {
+ await http(h.base, "POST", "/session/start", { sessionId: sessionIdFor(profile, n, j), project: PROJECT, cwd: h.cwd });
+ }
+ const hookScript = join(cfg.distDir, "hooks", "post-tool-use.mjs");
+ const killCount = Math.max(1, Math.floor(n / 2));
+ let done = 0;
+ let inFlight = 0;
+ let killedAtMs: number | null = null;
+ let gate: Promise | null = null;
+ let openGate = () => {};
+ const online: number[] = [];
+ const offline: number[] = [];
+ let nonZero = 0;
+ const t0 = performance.now();
+ log(`capture through hooks, kill after ${killCount} hooks or ${cfg.killAfterMs} ms, settle ${cfg.killSettleMs} ms`);
+ const killer = (async () => {
+ while (done < killCount && performance.now() - t0 < cfg.killAfterMs) await sleep(10);
+ if (cfg.killSettleMs > 0) {
+ gate = new Promise((ok) => (openGate = ok));
+ while (inFlight > 0) await sleep(10);
+ await sleep(cfg.killSettleMs);
+ }
+ const status = await http(h.base, "GET", "/status", undefined, 5000).catch(() => null);
+ const persistence = (status?.body as { indexPersistence?: { vector?: { lastSavedAt?: string | null } | null } } | undefined)?.indexPersistence ?? null;
+ const embedded = fake.snapshot();
+ const completed = done;
+ killedAtMs = performance.now() - t0;
+ await h.forceKill();
+ openGate();
+ const accepted = (readFileSync(join(runDir, "cli-cold.log"), "utf8").match(/Observation captured/g) ?? []).length;
+ out["crash"] = {
+ killAfterMs: Math.round(killedAtMs),
+ settleMs: cfg.killSettleMs,
+ hooksCompletedBeforeKill: completed,
+ observationsAcceptedBeforeKill: accepted,
+ embeddedInputsBeforeKill: embedded.embedInputs,
+ chatRequestsBeforeKill: embedded.chatRequests,
+ vectorCheckpointBeforeKill: persistence?.vector?.lastSavedAt ? 1 : 0,
+ indexPersistenceBeforeKill: persistence,
+ };
+ })();
+ await drive(cfg.concurrency, n, async (i) => {
+ if (gate) await gate;
+ inFlight++;
+ const start = performance.now() - t0;
+ const r = await runHook(hookScript, hookBody(sessionIdFor(profile, n, Math.floor(i / cfg.perSession)), h.cwd, caps.get(i)!), h.hookEnv(false), 15000, h.cwd);
+ (killedAtMs === null || start < killedAtMs ? online : offline).push(r.ms);
+ if (r.exitCode !== 0) nonZero++;
+ done++;
+ inFlight--;
+ });
+ await killer;
+ const spooled = h.spoolRecords();
+ Object.assign(out["crash"] as Record, {
+ captureWallMs: Math.round(performance.now() - t0),
+ hookLatencyOnlineMs: dist(online),
+ hookLatencyOfflineMs: dist(offline),
+ hookNonZeroExits: nonZero,
+ spoolRecordsWhileDown: spooled,
+ spoolStats: h.spoolStats(),
+ });
+ log(`${spooled} observations spooled while down; restart`);
+ const recBefore = fake.snapshot();
+ const recT0 = performance.now();
+ const rec = await h.start("recovery");
+ await h.sampler.begin();
+ await waitDrained(h, fake, profile.embeddings, n, cfg.quiesceTimeoutMs);
+ const recRss = await h.sampler.end();
+ const recProvider = diffCounters(recBefore, fake.snapshot());
+ out["recovery"] = {
+ ...rec,
+ boot: h.bootLog() ?? rec.boot,
+ settledMs: Math.round(performance.now() - recT0),
+ spoolRecordsAfter: h.spoolRecords(),
+ spoolStatsAfter: h.spoolStats(),
+ provider: recProvider,
+ rss: { peakTotalKiB: recRss.peakTotalKiB },
+ cpuSec: recRss.cpuSec,
+ };
+ const sampleIdx = Array.from({ length: Math.min(cfg.evidenceSample, n) }, (_, k) => Math.floor((k * n) / Math.min(cfg.evidenceSample, n)));
+ log("evidence after recovery");
+ out["evidenceAfterRecovery"] = await collectEvidence(h, profile, n, cfg.perSession, caps, sampleIdx);
+ await h.stop();
+ } catch (err) {
+ out["error"] = err instanceof Error ? err.message : String(err);
+ log(`error: ${out["error"]}`);
+ } finally {
+ h.sampler.stop();
+ await h.stop().catch(() => {});
+ if (!cfg.keep) rmSync(runDir, { recursive: true, force: true });
+ }
+ return out;
+}
+
+function kib(n: number): number {
+ return Math.round(n);
+}
+
+async function runOne(cfg: Config, profile: Profile, n: number, fake: FakeProvider) {
+ const { runDir, variant, out } = await prepareRun(cfg, profile, n);
+ const h = new Harness(cfg, profile, runDir);
+ h.prepare();
+ fake.reset();
+ const log = (msg: string) => process.stderr.write(`[capture-costs] ${variant} n=${n} ${msg}\n`);
+ try {
+ log("cold start");
+ const cold = await h.start("cold");
+ const baseline = await settledDisk(h.dataDir, 3000, 30000);
+ const idleEmpty = await h.sampler.sampleOnce();
+ out["coldStart"] = { ...cold, rssKiB: { total: idleEmpty.totalKiB, engine: idleEmpty.engineKiB, worker: idleEmpty.workerKiB } };
+ out["diskFixed"] = baseline;
+
+ const rng = mulberry32(cfg.seed);
+ const caps = new Map();
+ for (let i = 0; i < n; i++) {
+ const size = cfg.outputMin + Math.floor(rng() * Math.max(1, cfg.outputMax - cfg.outputMin));
+ caps.set(i, buildToolCapture(rng, i, size));
+ }
+ const sessions = Math.ceil(n / cfg.perSession);
+ const hookDir = join(cfg.distDir, "hooks");
+ const before = fake.snapshot();
+
+ log(`capture ${n} observations in ${sessions} sessions`);
+ await h.sampler.begin();
+ const sessionStart = await runHook(
+ join(hookDir, "session-start.mjs"),
+ { session_id: sessionIdFor(profile, n, 0), cwd: h.cwd, hook_event_name: "SessionStart", source: "startup" },
+ h.hookEnv(false),
+ );
+ for (let j = 1; j < sessions; j++) {
+ await http(h.base, "POST", "/session/start", { sessionId: sessionIdFor(profile, n, j), project: PROJECT, cwd: h.cwd });
+ }
+ const hookCount = Math.min(cfg.hookSample, n);
+ const hookRuns: HookRun[] = [];
+ const captureT0 = performance.now();
+ for (let i = 0; i < hookCount; i++) {
+ const cap = caps.get(i)!;
+ hookRuns.push(await runHook(join(hookDir, "post-tool-use.mjs"), hookBody(sessionIdFor(profile, n, Math.floor(i / cfg.perSession)), h.cwd, cap), h.hookEnv(false)));
+ }
+ const observeMs: number[] = [];
+ let observeErrors = 0;
+ let deduplicated = 0;
+ const errorSamples: string[] = [];
+ await drive(cfg.concurrency, n - hookCount, async (k) => {
+ const i = hookCount + k;
+ const cap = caps.get(i)!;
+ try {
+ const r = await http(h.base, "POST", "/observe", observeBody(sessionIdFor(profile, n, Math.floor(i / cfg.perSession)), h.cwd, cap), 60000);
+ observeMs.push(r.ms);
+ if (r.status >= 400) {
+ observeErrors++;
+ if (errorSamples.length < 5) errorSamples.push(`HTTP ${r.status}: ${r.text.slice(0, 160)}`);
+ }
+ if ((r.body as { deduplicated?: boolean })?.deduplicated) deduplicated++;
+ } catch (err) {
+ observeErrors++;
+ if (errorSamples.length < 5) errorSamples.push(err instanceof Error ? err.message : String(err));
+ }
+ });
+ const captureWallMs = performance.now() - captureT0;
+ const q = await quiesce(h, fake, cfg.quiesceTimeoutMs);
+ const captureRss = await h.sampler.end();
+ const afterCapture = fake.snapshot();
+ out["capture"] = {
+ wallMs: Math.round(captureWallMs),
+ quiesceMs: q.ms,
+ hookSample: hookCount,
+ sessionStartHook: { ms: Math.round(sessionStart.ms), stdoutBytes: sessionStart.stdoutBytes, exitCode: sessionStart.exitCode },
+ hookLatencyMs: dist(hookRuns.map((r) => r.ms)),
+ hookStdoutBytes: { total: hookRuns.reduce((s, r) => s + r.stdoutBytes, 0), max: Math.max(0, ...hookRuns.map((r) => r.stdoutBytes)) },
+ hookStderrBytes: hookRuns.reduce((s, r) => s + r.stderrBytes, 0),
+ hookNonZeroExits: hookRuns.filter((r) => r.exitCode !== 0).length,
+ observeConcurrency: cfg.concurrency,
+ observeLatencyMs: dist(observeMs),
+ observeErrors,
+ observeErrorSamples: errorSamples,
+ deduplicatedResponses: deduplicated,
+ rss: { peakTotalKiB: kib(captureRss.peakTotalKiB), peakEngineKiB: kib(captureRss.peakEngineKiB), peakWorkerKiB: kib(captureRss.peakWorkerKiB), meanTotalKiB: captureRss.meanTotalKiB, samples: captureRss.samples },
+ cpuSec: captureRss.cpuSec,
+ provider: diffCounters(before, afterCapture),
+ };
+
+ log("idle");
+ await sleep(5000);
+ const idle = await h.sampler.sampleOnce();
+ out["idle"] = { rssKiB: { total: idle.totalKiB, engine: idle.engineKiB, worker: idle.workerKiB } };
+ out["diskAfterCapture"] = q.disk;
+ out["diskGrowth"] = diskDelta(baseline, q.disk);
+ out["diskGrowthPerObservationBytes"] = n > 0 ? Math.round(diskDelta(baseline, q.disk).totalBytes / n) : null;
+ if (cfg.stateBackend === "redis") out["redisAfterCapture"] = await redisStats(cfg.redisUrl!);
+ if (cfg.provider !== "fake") out["providerProcessRssKiB"] = await providerProcessRssKiB();
+
+ const sampleIdx = Array.from({ length: Math.min(cfg.evidenceSample, n) }, (_, k) => Math.floor((k * n) / Math.min(cfg.evidenceSample, n)));
+ log("evidence before kill");
+ out["evidenceBeforeKill"] = await collectEvidence(h, profile, n, cfg.perSession, caps, sampleIdx);
+ log("context cost");
+ const ctxBefore = fake.snapshot();
+ out["agentVisibleContext"] = await measureContext(h, profile, n, caps, cfg);
+ out["agentVisibleContextProvider"] = diffCounters(ctxBefore, fake.snapshot());
+
+ log("force kill and recover");
+ await h.forceKill();
+ const recBefore = fake.snapshot();
+ const recT0 = performance.now();
+ const rec = await h.start("recovery");
+ await h.sampler.begin();
+ const rq = await quiesce(h, fake, cfg.quiesceTimeoutMs);
+ const recRss = await h.sampler.end();
+ const recProvider = diffCounters(recBefore, fake.snapshot());
+ await sleep(3000);
+ const recIdle = await h.sampler.sampleOnce();
+ out["recovery"] = {
+ ...rec,
+ bootAfterSettle: h.bootLog(),
+ settledMs: Math.round(performance.now() - recT0),
+ reEmbedRequests: recProvider.embedRequests,
+ reEmbeddedInputs: recProvider.embedInputs,
+ provider: recProvider,
+ rss: { peakTotalKiB: recRss.peakTotalKiB, idleTotalKiB: recIdle.totalKiB, idleEngineKiB: recIdle.engineKiB, idleWorkerKiB: recIdle.workerKiB },
+ cpuSec: recRss.cpuSec,
+ disk: rq.disk,
+ };
+ log("evidence after recovery");
+ out["evidenceAfterRecovery"] = await collectEvidence(h, profile, n, cfg.perSession, caps, sampleIdx);
+
+ log("graceful stop and warm start");
+ await h.stop();
+ const warmBefore = fake.snapshot();
+ const warm = await h.start("warm");
+ await quiesce(h, fake, Math.min(cfg.quiesceTimeoutMs, 120000));
+ const warmIdle = await h.sampler.sampleOnce();
+ out["warmStart"] = { ...warm, provider: diffCounters(warmBefore, fake.snapshot()), rssKiB: { total: warmIdle.totalKiB, engine: warmIdle.engineKiB, worker: warmIdle.workerKiB } };
+ await h.stop();
+ out["diskFinal"] = await settledDisk(h.dataDir, 2000, 20000);
+ } catch (err) {
+ out["error"] = err instanceof Error ? err.message : String(err);
+ log(`error: ${out["error"]}`);
+ } finally {
+ h.sampler.stop();
+ await h.stop().catch(() => {});
+ if (!cfg.keep) rmSync(runDir, { recursive: true, force: true });
+ }
+ return out;
+}
+
+function gitSha(): string {
+ try {
+ return execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim();
+ } catch {
+ return "unknown";
+ }
+}
+
+function fmtBytes(n: unknown): string {
+ if (typeof n !== "number" || !Number.isFinite(n)) return "n/a";
+ if (Math.abs(n) >= 1024 * 1024) return `${(n / 1024 / 1024).toFixed(2)} MiB`;
+ if (Math.abs(n) >= 1024) return `${(n / 1024).toFixed(1)} KiB`;
+ return `${n} B`;
+}
+
+function fmtKiB(n: unknown): string {
+ return typeof n === "number" ? `${(n / 1024).toFixed(0)} MiB` : "n/a";
+}
+
+function get(o: unknown, path: string): unknown {
+ return path.split(".").reduce((acc, k) => (acc && typeof acc === "object" ? (acc as Record)[k] : undefined), o);
+}
+
+function markdown(report: Record): string {
+ const repeated = ((report["config"] as { repeats?: number })?.repeats ?? 1) > 1;
+ const all = (report["runs"] as Record[]).map(
+ (r): Record => ({ ...r, profile: repeated ? `${variantOf(r)} #${r["repeat"]}` : variantOf(r) }),
+ );
+ const runs = all.filter((r) => (r["scenario"] ?? "standard") === "standard");
+ const crashes = all.filter((r) => r["scenario"] === "crash-offline");
+ const lines: string[] = [];
+ const env = report["environment"] as Record;
+ lines.push(`Commit \`${report["commit"]}\`, ${env["platform"]}, ${env["cpu"]}, ${fmtBytes(env["memoryBytes"])} RAM, Node ${env["node"]}, iii ${env["iii"]}.`, "");
+ lines.push("### Disk retention", "");
+ lines.push("| profile | N | logical obs | fixed | after capture | growth/obs | source | summary | index | diagnostic | config | stream | queue | failed delivery |");
+ lines.push("|---|---|---|---|---|---|---|---|---|---|---|---|---|---|");
+ for (const r of runs) {
+ const g = (k: string) => fmtBytes(get(r, `diskAfterCapture.byCategory.${k}`));
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${get(r, "evidenceBeforeKill.logicalObservations") ?? "n/a"} | ${fmtBytes(get(r, "diskFixed.totalBytes"))} | ${fmtBytes(get(r, "diskAfterCapture.totalBytes"))} | ${fmtBytes(r["diskGrowthPerObservationBytes"])} | ${g("source")} | ${g("summary")} | ${g("index")} | ${g("diagnostic")} | ${g("config")} | ${g("stream")} | ${g("queue")} | ${g("failed_delivery")} |`);
+ }
+ lines.push("", "### Resident memory and CPU (engine + worker process tree)", "");
+ lines.push("| profile | N | empty idle | capture peak | engine peak | worker peak | idle after capture | after recovery | capture CPU s | recovery CPU s |");
+ lines.push("|---|---|---|---|---|---|---|---|---|---|");
+ for (const r of runs) {
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${fmtKiB(get(r, "coldStart.rssKiB.total"))} | ${fmtKiB(get(r, "capture.rss.peakTotalKiB"))} | ${fmtKiB(get(r, "capture.rss.peakEngineKiB"))} | ${fmtKiB(get(r, "capture.rss.peakWorkerKiB"))} | ${fmtKiB(get(r, "idle.rssKiB.total"))} | ${fmtKiB(get(r, "recovery.rss.idleTotalKiB"))} | ${get(r, "capture.cpuSec") ?? "n/a"} | ${get(r, "recovery.cpuSec") ?? "n/a"} |`);
+ }
+ lines.push("", "### Capture latency", "");
+ lines.push("| profile | N | hook p50 ms | hook p95 ms | hook stdout B | observe p50 ms | observe p95 ms | observe p99 ms | errors | capture wall ms | quiesce ms |");
+ lines.push("|---|---|---|---|---|---|---|---|---|---|---|");
+ for (const r of runs) {
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${get(r, "capture.hookLatencyMs.p50")} | ${get(r, "capture.hookLatencyMs.p95")} | ${get(r, "capture.hookStdoutBytes.total")} | ${get(r, "capture.observeLatencyMs.p50")} | ${get(r, "capture.observeLatencyMs.p95")} | ${get(r, "capture.observeLatencyMs.p99")} | ${get(r, "capture.observeErrors")} | ${get(r, "capture.wallMs")} | ${get(r, "capture.quiesceMs")} |`);
+ }
+ lines.push("", "### Startup and recovery", "");
+ lines.push("| profile | N | cold ready ms | warm ready ms | recovery ready ms | recovery BM25 rebuild ms (docs) | vectors loaded | vector docs before / after | backfill queued / awaiting opt-in | re-embed requests (inputs) | logical obs before / after | marker hits before / after | source tail before / after |");
+ lines.push("|---|---|---|---|---|---|---|---|---|---|---|---|---|");
+ for (const r of runs) {
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${get(r, "coldStart.readyMs")} | ${get(r, "warmStart.readyMs")} | ${get(r, "recovery.readyMs")} | ${get(r, "recovery.boot.bm25RebuildMs")} (${get(r, "recovery.boot.bm25Docs")}) | ${get(r, "recovery.boot.vectorsLoaded")} | ${get(r, "evidenceBeforeKill.vectorDocuments")} / ${get(r, "evidenceAfterRecovery.vectorDocuments")} | ${get(r, "recovery.boot.vectorBackfillQueued")} / ${get(r, "recovery.boot.vectorBackfillAwaitingOptIn")} | ${get(r, "recovery.reEmbedRequests")} (${get(r, "recovery.reEmbeddedInputs")}) | ${get(r, "evidenceBeforeKill.logicalObservations")} / ${get(r, "evidenceAfterRecovery.logicalObservations")} | ${get(r, "evidenceBeforeKill.markerSearchHits")}/${get(r, "evidenceBeforeKill.sampled")} / ${get(r, "evidenceAfterRecovery.markerSearchHits")}/${get(r, "evidenceAfterRecovery.sampled")} | ${get(r, "evidenceBeforeKill.sourceTailRetained")} / ${get(r, "evidenceAfterRecovery.sourceTailRetained")} |`);
+ }
+ lines.push("", "### Provider calls (OpenAI-compatible endpoint seen by the bench)", "");
+ lines.push("| profile | N | capture embed req (inputs, repeats) | capture chat req (repeats) | chat prompt tok | chat completion tok | upstream embed s | upstream chat s | provider errors | context-phase embed req | recovery embed req | warm-start embed req |");
+ lines.push("|---|---|---|---|---|---|---|---|---|---|---|---|");
+ for (const r of runs) {
+ const p = (k: string) => get(r, `capture.provider.${k}`);
+ const secs = (k: string) => (typeof p(k) === "number" ? ((p(k) as number) / 1000).toFixed(1) : "n/a");
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${p("embedRequests")} (${p("embedInputs")}, ${p("embedRepeatInputs")}) | ${p("chatRequests")} (${p("chatRepeatPrompts")}) | ${p("chatPromptTokens")} | ${p("chatCompletionTokens")} | ${secs("embedUpstreamMs")} | ${secs("chatUpstreamMs")} | ${p("errors")} | ${get(r, "agentVisibleContextProvider.embedRequests")} | ${get(r, "recovery.provider.embedRequests")} | ${get(r, "warmStart.provider.embedRequests")} |`);
+ }
+ const redisRuns = runs.filter((r) => r["redisAfterCapture"]);
+ if (redisRuns.length > 0) {
+ lines.push("", "### Redis state store after capture", "");
+ lines.push("| profile | N | used memory | keys | redis-server RSS |", "|---|---|---|---|---|");
+ for (const r of redisRuns) lines.push(`| ${r["profile"]} | ${r["observations"]} | ${fmtBytes(get(r, "redisAfterCapture.usedMemoryBytes"))} | ${get(r, "redisAfterCapture.keys")} | ${fmtKiB(get(r, "redisAfterCapture.serverRssKiB"))} |`);
+ }
+ if (crashes.length > 0) {
+ lines.push("", "### Force-kill during capture with the service down", "");
+ lines.push("| profile | N | killed at ms | hooks before kill | embedded before kill | checkpoint before kill | spooled while down | offline hook p95 ms | spool recovered (dup) | pending-log vectors | recovery embed inputs (repeats) | logical obs after | vectors after | spool left |");
+ lines.push("|---|---|---|---|---|---|---|---|---|---|---|---|---|---|");
+ for (const r of crashes) {
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${get(r, "crash.killAfterMs")} | ${get(r, "crash.hooksCompletedBeforeKill")} | ${get(r, "crash.embeddedInputsBeforeKill")} | ${get(r, "crash.vectorCheckpointBeforeKill") ? "yes" : "no"} | ${get(r, "crash.spoolRecordsWhileDown")} | ${get(r, "crash.hookLatencyOfflineMs.p95")} | ${get(r, "recovery.boot.spoolRecovered")} (${get(r, "recovery.boot.spoolAlreadyStored")}) | ${get(r, "recovery.boot.pendingLogRecoveredVectors")} | ${get(r, "recovery.provider.embedInputs")} (${get(r, "recovery.provider.embedRepeatInputs")}) | ${get(r, "evidenceAfterRecovery.logicalObservations")} | ${get(r, "evidenceAfterRecovery.vectorDocuments")} | ${get(r, "recovery.spoolRecordsAfter")} |`);
+ }
+ }
+ lines.push("", "### Agent-visible context (server token estimate, not provider billing)", "");
+ lines.push("| profile | N | search full B p50 (tok) | compact B p50 (tok) | narrative B p50 (tok) | smart-search B p50 | context B (tok) | SessionStart stdout off / on | PreToolUse stdout off / on |");
+ lines.push("|---|---|---|---|---|---|---|---|---|");
+ for (const r of runs) {
+ const e = (k: string, f: string) => get(r, `agentVisibleContext.endpoints.${k}.${f}`);
+ const tok = (k: string) => {
+ const t = e(k, "serverTokenEstimate");
+ return typeof t === "object" && t ? (t as { p50: number }).p50 : "unknown";
+ };
+ const hs = (k: string) => get(r, `agentVisibleContext.hookStdout.${k}.stdoutBytes`);
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${e("search_full", "bytes.p50")} (${tok("search_full")}) | ${e("search_compact", "bytes.p50")} (${tok("search_compact")}) | ${e("search_narrative", "bytes.p50")} (${tok("search_narrative")}) | ${e("smart_search", "bytes.p50")} | ${e("context", "bytes.p50")} (${tok("context")}) | ${hs("session_start_inject_off")} / ${hs("session_start_inject_on")} | ${hs("pre_tool_use_inject_off")} / ${hs("pre_tool_use_inject_on")} |`);
+ }
+ const checks: [string, Check[]][] = [["Invariants (evidence completeness and default-off injection)", (report["invariants"] as Check[]) ?? []], ["Budgets", ((report["budgets"] as { checks?: Check[] } | undefined)?.checks ?? [])]];
+ for (const [title, list] of checks) {
+ if (list.length === 0) continue;
+ const failed = list.filter((c) => !c.pass);
+ lines.push("", `### ${title}`, "", `${list.length - failed.length}/${list.length} checks pass.`);
+ if (failed.length > 0) {
+ lines.push("", "| profile | N | repeat | check | value | limit |", "|---|---|---|---|---|---|");
+ for (const c of failed) lines.push(`| ${c.profile} | ${c.observations} | ${c.repeat} | ${c.name} | ${c.value} | ${c.limit} |`);
+ }
+ }
+ const errors = all.filter((r) => r["error"]);
+ if (errors.length > 0) {
+ lines.push("", "### Errors", "");
+ for (const r of errors) lines.push(`- ${r["profile"]} N=${r["observations"]}: ${r["error"]}`);
+ }
+ return lines.join("\n") + "\n";
+}
+
+function mergeReports(paths: string[], outDir: string, budgetsPath: string | null, writeBudgetsPath: string | null): void {
+ const reports = paths.map((p) => JSON.parse(readFileSync(p, "utf8")) as Record);
+ const first = reports[0]!;
+ const runs = reports.flatMap((r) => r["runs"] as Record[]);
+ const commits = new Set(reports.map((r) => r["commit"]));
+ if (commits.size > 1) throw new Error(`refusing to merge reports from different commits: ${[...commits].join(", ")}`);
+ const merged: Record = {
+ ...first,
+ finished: reports.map((r) => String(r["finished"])).sort().pop(),
+ config: { ...(first["config"] as object), sizes: [...new Set(runs.map((r) => r["observations"] as number))], repeats: Math.max(...reports.map((r) => ((r["config"] as { repeats?: number })?.repeats ?? 1))) },
+ mergedFrom: paths.map((p) => basename(p)),
+ runs,
+ };
+ merged["invariants"] = checkInvariants(runs);
+ if (budgetsPath && existsSync(budgetsPath)) {
+ merged["budgets"] = { file: basename(budgetsPath), checks: checkBudgets(runs, JSON.parse(readFileSync(budgetsPath, "utf8")) as BudgetFile) };
+ }
+ if (writeBudgetsPath) writeFileSync(writeBudgetsPath, JSON.stringify(deriveBudgets(runs), null, 2) + "\n");
+ const short = String(first["commit"]).slice(0, 7);
+ writeFileSync(join(outDir, `capture-costs-${short}.json`), JSON.stringify(merged, null, 2) + "\n");
+ writeFileSync(join(outDir, `capture-costs-${short}.md`), markdown(merged));
+ process.stdout.write(markdown(merged));
+}
+
+async function main(): Promise {
+ if (process.env["BENCH_MERGE"]) {
+ const outDir = process.env["BENCH_OUT_DIR"] || resolve(process.cwd(), "benchmark", "results");
+ mkdirSync(outDir, { recursive: true });
+ const budgets = process.env["BENCH_BUDGETS"] === "off" ? null : resolve(process.cwd(), process.env["BENCH_BUDGETS"] || join("benchmark", "capture-costs-budgets.json"));
+ const write = process.env["BENCH_WRITE_BUDGETS"] ? resolve(process.cwd(), process.env["BENCH_WRITE_BUDGETS"]) : null;
+ mergeReports(process.env["BENCH_MERGE"].split(",").map((p) => resolve(process.cwd(), p.trim())), outDir, budgets, write);
+ return;
+ }
+ const cfg = loadConfig();
+ if (!existsSync(join(cfg.distDir, "cli.mjs")) || !existsSync(join(cfg.distDir, "hooks", "post-tool-use.mjs"))) {
+ throw new Error("dist/ is missing; run npm run build first");
+ }
+ mkdirSync(cfg.root, { recursive: true });
+ mkdirSync(cfg.outDir, { recursive: true });
+ const fake = new FakeProvider(cfg.fakePort, cfg.dims, cfg.upstreamUrl);
+ await fake.start();
+ const commit = gitSha();
+ const started = new Date().toISOString();
+ const runs: Record[] = [];
+ try {
+ for (const n of cfg.sizes) {
+ for (let rep = 1; rep <= cfg.repeats; rep++) {
+ for (const profile of cfg.profiles) {
+ const t0 = performance.now();
+ const r = cfg.scenario === "crash-offline" ? await runCrashOffline(cfg, profile, n, fake) : await runOne(cfg, profile, n, fake);
+ r["repeat"] = rep;
+ r["runWallMs"] = Math.round(performance.now() - t0);
+ runs.push(r);
+ }
+ }
+ }
+ } finally {
+ await fake.stop();
+ if (!cfg.keep) rmSync(cfg.root, { recursive: true, force: true });
+ }
+ const report: Record = {
+ schema_version: SCHEMA_VERSION,
+ commit,
+ started,
+ finished: new Date().toISOString(),
+ environment: {
+ platform: `${platform()} ${release()} ${arch()}`,
+ cpu: `${cpus()[0]?.model ?? "unknown"} x${cpus().length}`,
+ memoryBytes: totalmem(),
+ node: process.version,
+ iii: iiiVersion(cfg.iiiBin),
+ stateBackend: cfg.stateBackend,
+ ...(cfg.stateBackend === "redis" ? { redis: (await redisCli(cfg.redisUrl!, ["INFO", "server"])).match(/^redis_version:(\S+)/m)?.[1] ?? null } : {}),
+ },
+ config: {
+ sizes: cfg.sizes,
+ profiles: cfg.profiles.map((p) => ({ name: p.name, description: p.description })),
+ observationsPerSession: cfg.perSession,
+ hookSample: cfg.hookSample,
+ observeConcurrency: cfg.concurrency,
+ toolOutputBytes: [cfg.outputMin, cfg.outputMax],
+ seed: cfg.seed,
+ embeddingDimensions: cfg.dims,
+ contextBudgetTokens: cfg.contextBudget,
+ searchLimit: cfg.searchLimit,
+ evidenceSample: cfg.evidenceSample,
+ repeats: cfg.repeats,
+ scenario: cfg.scenario,
+ provider: cfg.provider === "fake" ? { mode: "fake" } : { mode: cfg.provider, url: cfg.upstreamUrl, embeddingModel: cfg.embedModel, chatModel: cfg.chatModel },
+ ...(cfg.scenario === "crash-offline" ? { killAfterMs: cfg.killAfterMs, killSettleMs: cfg.killSettleMs } : {}),
+ ports: { rest: cfg.restPort, streams: cfg.restPort + 1, viewer: cfg.restPort + 2, metrics: cfg.restPort + 3, engine: cfg.enginePort, fakeProvider: cfg.fakePort },
+ },
+ runs,
+ };
+ report["invariants"] = checkInvariants(runs);
+ if (cfg.budgetsPath && existsSync(cfg.budgetsPath)) {
+ report["budgets"] = { file: cfg.budgetsPath, checks: checkBudgets(runs, JSON.parse(readFileSync(cfg.budgetsPath, "utf8")) as BudgetFile) };
+ }
+ if (cfg.writeBudgetsPath) {
+ writeFileSync(cfg.writeBudgetsPath, JSON.stringify(deriveBudgets(runs), null, 2) + "\n");
+ process.stderr.write(`[capture-costs] wrote budgets to ${cfg.writeBudgetsPath}\n`);
+ }
+ const short = commit === "unknown" ? `nogit-${Date.now().toString(36)}` : commit.slice(0, 7);
+ const jsonPath = join(cfg.outDir, `capture-costs-${short}.json`);
+ const mdPath = join(cfg.outDir, `capture-costs-${short}.md`);
+ writeFileSync(jsonPath, JSON.stringify(report, null, 2) + "\n");
+ writeFileSync(mdPath, markdown(report));
+ process.stdout.write(markdown(report));
+ process.stderr.write(`[capture-costs] wrote ${jsonPath} and ${mdPath}\n`);
+ const failedInvariants = (report["invariants"] as Check[]).some((c) => !c.pass);
+ const budgetChecks = ((report["budgets"] as { checks?: Check[] } | undefined)?.checks ?? []);
+ const failedBudgets = budgetChecks.some((c) => !c.pass);
+ if (runs.some((r) => r["error"]) || failedInvariants) process.exitCode = 1;
+ if (failedBudgets && cfg.enforceBudgets) process.exitCode = 2;
+}
+
+main().catch((err) => {
+ process.stderr.write(`[capture-costs] ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+ process.exit(1);
+});
diff --git a/benchmark/lib/corpus.ts b/benchmark/lib/corpus.ts
new file mode 100644
index 0000000000..3d11dd11a9
--- /dev/null
+++ b/benchmark/lib/corpus.ts
@@ -0,0 +1,84 @@
+export function mulberry32(seed: number): () => number {
+ let s = seed >>> 0;
+ return () => {
+ s = (s + 0x6d2b79f5) >>> 0;
+ let t = s;
+ t = Math.imul(t ^ (t >>> 15), t | 1);
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+export const NOUNS = [
+ "cache", "queue", "router", "stream", "shard", "lock", "buffer", "worker",
+ "engine", "trigger", "function", "memory", "index", "graph", "vector",
+ "session", "observation", "summary", "embedding", "tokenizer", "scheduler",
+ "consumer", "producer", "channel", "actor", "pipeline", "watcher", "pool",
+];
+export const VERBS = [
+ "flushes", "rotates", "compacts", "rebalances", "drains", "warms",
+ "expires", "deduplicates", "snapshots", "replays", "promotes", "demotes",
+ "merges", "splits", "indexes", "scans", "compresses", "uploads",
+];
+export const CONCEPTS = [
+ "throughput", "latency", "backpressure", "consistency", "isolation",
+ "durability", "idempotency", "fan-out", "cardinality", "skew",
+ "hot-path", "cold-start", "tail-latency", "saturation", "quiescence",
+];
+
+function pick(rng: () => number, list: readonly T[]): T {
+ return list[Math.floor(rng() * list.length)]!;
+}
+
+export function buildContent(rng: () => number, i: number): string {
+ const n = pick(rng, NOUNS);
+ const v = pick(rng, VERBS);
+ const c1 = pick(rng, CONCEPTS);
+ const c2 = pick(rng, CONCEPTS);
+ const k = Math.floor(rng() * 9999);
+ return `seed-${i} the ${n} ${v} ${c1} under ${c2} pressure (k=${k})`;
+}
+
+export interface ToolCapture {
+ index: number;
+ toolName: string;
+ toolInput: Record;
+ toolOutput: string;
+ headMarker: string;
+ tailMarker: string;
+}
+
+const TOOLS = ["Bash", "Read", "Edit", "Grep"] as const;
+
+export function buildToolCapture(
+ rng: () => number,
+ i: number,
+ outputBytes: number,
+): ToolCapture {
+ const toolName = pick(rng, TOOLS);
+ const headMarker = `capmark${i}head`;
+ const tailMarker = `capmark${i}tail`;
+ const file = `src/${pick(rng, NOUNS)}/${pick(rng, NOUNS)}-${i}.ts`;
+ const toolInput: Record =
+ toolName === "Bash"
+ ? { command: `npm test -- ${pick(rng, NOUNS)} --shard=${i}` }
+ : toolName === "Grep"
+ ? { pattern: pick(rng, CONCEPTS), path: `src/${pick(rng, NOUNS)}-${i}` }
+ : { file_path: file };
+ const lines: string[] = [`${headMarker} ${buildContent(rng, i)}`];
+ let size = lines[0]!.length;
+ while (size < outputBytes - tailMarker.length - 1) {
+ const line = buildContent(rng, i);
+ lines.push(line);
+ size += line.length + 1;
+ }
+ lines.push(tailMarker);
+ return {
+ index: i,
+ toolName,
+ toolInput,
+ toolOutput: lines.join("\n"),
+ headMarker,
+ tailMarker,
+ };
+}
diff --git a/benchmark/load-100k.ts b/benchmark/load-100k.ts
index 676aa647c6..bc65c8b00f 100644
--- a/benchmark/load-100k.ts
+++ b/benchmark/load-100k.ts
@@ -1,28 +1,3 @@
-/**
- * Load harness — seeds N synthetic memories against a local agentmemory
- * daemon, then drives a matrix of (N, concurrency, endpoint) cells and
- * records p50 / p90 / p99 latency + throughput per cell.
- *
- * Spec: GitHub issue #346.
- *
- * Runs against an already-running daemon at `http://localhost:3111` by
- * default. Set `AGENTMEMORY_BENCH_AUTOSTART=1` to spawn one via
- * `node dist/cli.js start` for the duration of the run.
- *
- * Env knobs:
- * AGENTMEMORY_BENCH_AUTOSTART "1" to spawn the daemon (default: assume up)
- * AGENTMEMORY_URL base URL of the daemon (default: http://localhost:3111)
- * BENCH_N comma-separated N sizes (default: 1000,10000,100000)
- * BENCH_C comma-separated concurrency levels (default: 1,10,100)
- * BENCH_OPS ops per cell during measurement (default: 200)
- * BENCH_SEED seed for the mulberry32 RNG (default: 0xC0FFEE)
- * BENCH_OUT_DIR results dir (default: benchmark/results)
- *
- * The harness writes one JSON file per run named
- * `load-100k-.json`. The git sha is best-effort — falls
- * back to a timestamp when run outside a checkout.
- */
-
import { spawn, type ChildProcess } from "node:child_process";
import { execFileSync } from "node:child_process";
import { mkdirSync, writeFileSync, existsSync } from "node:fs";
@@ -30,44 +5,7 @@ import { join, resolve } from "node:path";
import { performance } from "node:perf_hooks";
import { pXX } from "./lib/percentiles.js";
-
-/** Seedable PRNG. Mulberry32 — 32-bit state, uniform output in [0, 1). */
-function mulberry32(seed: number): () => number {
- let s = seed >>> 0;
- return () => {
- s = (s + 0x6d2b79f5) >>> 0;
- let t = s;
- t = Math.imul(t ^ (t >>> 15), t | 1);
- t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
- return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
- };
-}
-
-const NOUNS = [
- "cache", "queue", "router", "stream", "shard", "lock", "buffer", "worker",
- "engine", "trigger", "function", "memory", "index", "graph", "vector",
- "session", "observation", "summary", "embedding", "tokenizer", "scheduler",
- "consumer", "producer", "channel", "actor", "pipeline", "watcher", "pool",
-];
-const VERBS = [
- "flushes", "rotates", "compacts", "rebalances", "drains", "warms",
- "expires", "deduplicates", "snapshots", "replays", "promotes", "demotes",
- "merges", "splits", "indexes", "scans", "compresses", "uploads",
-];
-const CONCEPTS = [
- "throughput", "latency", "backpressure", "consistency", "isolation",
- "durability", "idempotency", "fan-out", "cardinality", "skew",
- "hot-path", "cold-start", "tail-latency", "saturation", "quiescence",
-];
-
-function buildContent(rng: () => number, i: number): string {
- const n = NOUNS[Math.floor(rng() * NOUNS.length)]!;
- const v = VERBS[Math.floor(rng() * VERBS.length)]!;
- const c1 = CONCEPTS[Math.floor(rng() * CONCEPTS.length)]!;
- const c2 = CONCEPTS[Math.floor(rng() * CONCEPTS.length)]!;
- const k = Math.floor(rng() * 9999);
- return `seed-${i} the ${n} ${v} ${c1} under ${c2} pressure (k=${k})`;
-}
+import { buildContent, mulberry32 } from "./lib/corpus.js";
interface RunConfig {
baseUrl: string;
diff --git a/deploy/README.md b/deploy/README.md
index 91aa199e28..dc96076aaf 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -80,6 +80,24 @@ absent (no third-party calls), `AGENTMEMORY_AUTO_COMPRESS` is off,
and `AGENTMEMORY_INJECT_CONTEXT` is off. Opt in only after you've
confirmed your provider quota can absorb the workload.
+## Optional: Redis state backend
+
+Every entrypoint here overwrites the npm-bundled `iii-config.yaml` and
+execs `agentmemory` directly (no Docker Compose in the loop), so the
+same two variables the main README's "Storage backend" section
+documents work unchanged: set `AGENTMEMORY_STATE_BACKEND=redis` and
+`AGENTMEMORY_REDIS_URL=redis://host:6379` alongside your platform's
+other secrets to point `iii-state`/`iii-stream` at an external Redis
+instead of the `/data` volume. The pinned engine only supports plain
+`redis://` (no TLS), so the connection, including the Redis password
+and every stored memory, travels unencrypted. Only use it over a
+private network you trust (the platform's private networking, or a
+Redis in the same machine or VPC). To reach any other Redis, including
+a managed TLS-only one, run an encrypted tunnel next to agentmemory
+(stunnel, an SSH tunnel, or a VPN such as WireGuard or Tailscale) so
+the plain `redis://` hop never leaves the host, and the tunnel's own
+upstream connection is encrypted and authenticated.
+
## Cold-start budget
Measured against fly.io's `iad` region with a 1 GB volume:
diff --git a/deploy/coolify/Dockerfile b/deploy/coolify/Dockerfile
index c0a6bb6c9c..255317f694 100644
--- a/deploy/coolify/Dockerfile
+++ b/deploy/coolify/Dockerfile
@@ -1,20 +1,24 @@
-ARG III_VERSION=0.11.2
+ARG III_VERSION=0.22.1
FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.29
-ARG III_VERSION=0.11.2
-ARG III_SDK_VERSION=0.11.2
+ARG AGENTMEMORY_VERSION=0.9.30-codex.1
+ARG III_VERSION=0.22.1
+ARG III_SDK_VERSION=0.22.1
RUN apt-get update \
&& apt-get install -y --no-install-recommends openssl ca-certificates tini gosu curl \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
WORKDIR /opt/agentmemory
+RUN [ "${III_VERSION}" = "${III_SDK_VERSION}" ] \
+ || { echo "III_VERSION=${III_VERSION} and III_SDK_VERSION=${III_SDK_VERSION} must be the same release: the agentmemory worker speaks the wire protocol of the engine it was built against, so override both together" >&2; exit 1; }
RUN printf '{"name":"agentmemory-deploy","version":"1.0.0","private":true,"overrides":{"iii-sdk":"%s"}}\n' "${III_SDK_VERSION}" > package.json \
&& npm install "@agentmemory/agentmemory@${AGENTMEMORY_VERSION}" --omit=optional --no-fund --no-audit \
&& ln -s /opt/agentmemory/node_modules/.bin/agentmemory /usr/local/bin/agentmemory
diff --git a/deploy/coolify/docker-compose.yml b/deploy/coolify/docker-compose.yml
index b34823dbc6..e42d24fc10 100644
--- a/deploy/coolify/docker-compose.yml
+++ b/deploy/coolify/docker-compose.yml
@@ -4,9 +4,9 @@ services:
context: .
dockerfile: Dockerfile
args:
- AGENTMEMORY_VERSION: "0.9.29"
- III_VERSION: "0.11.2"
- III_SDK_VERSION: "0.11.2"
+ AGENTMEMORY_VERSION: "0.9.30-codex.1"
+ III_VERSION: "0.22.1"
+ III_SDK_VERSION: "0.22.1"
restart: unless-stopped
environment:
SERVICE_FQDN_AGENTMEMORY_3111: ${SERVICE_FQDN_AGENTMEMORY_3111}
diff --git a/deploy/coolify/entrypoint.sh b/deploy/coolify/entrypoint.sh
index ffdd633395..8df88f49df 100755
--- a/deploy/coolify/entrypoint.sh
+++ b/deploy/coolify/entrypoint.sh
@@ -16,10 +16,19 @@
set -eu
DATA_DIR="${AGENTMEMORY_DATA_DIR:-/data}"
+export AGENTMEMORY_DATA_DIR="$DATA_DIR"
HMAC_FILE="${AGENTMEMORY_HMAC_FILE:-/data/.hmac}"
RUN_AS="node:node"
III_CONFIG="/opt/agentmemory/node_modules/@agentmemory/agentmemory/dist/iii-config.yaml"
+if [ -z "${MALLOC_ARENA_MAX:-}" ]; then
+ export MALLOC_ARENA_MAX=2
+fi
+cur_nofile="$(ulimit -n)"
+if [ "$cur_nofile" != unlimited ] && [ "$cur_nofile" -lt 10240 ]; then
+ ulimit -n 10240 2>/dev/null || ulimit -n "$(ulimit -H -n)" 2>/dev/null || true
+fi
+
mkdir -p "$DATA_DIR"
chown -R "$RUN_AS" "$DATA_DIR"
@@ -43,6 +52,7 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/state_store.db
- name: iii-queue
config:
@@ -64,16 +74,17 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/stream_store
- name: iii-observability
config:
enabled: true
service_name: agentmemory
exporter: memory
- sampling_ratio: 1.0
+ sampling_ratio: 0.1
metrics_enabled: true
logs_enabled: true
- logs_console_output: true
+ logs_console_output: false
EOF
chown "$RUN_AS" "$III_CONFIG"
diff --git a/deploy/fly/Dockerfile b/deploy/fly/Dockerfile
index e094699881..3efeb64fae 100644
--- a/deploy/fly/Dockerfile
+++ b/deploy/fly/Dockerfile
@@ -1,26 +1,28 @@
-ARG III_VERSION=0.11.2
+ARG III_VERSION=0.22.1
FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.29
-ARG III_VERSION=0.11.2
-ARG III_SDK_VERSION=0.11.2
+ARG AGENTMEMORY_VERSION=0.9.30-codex.1
+ARG III_VERSION=0.22.1
+ARG III_SDK_VERSION=0.22.1
RUN apt-get update \
&& apt-get install -y --no-install-recommends openssl ca-certificates tini gosu curl \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
# Install agentmemory into a dedicated prefix so the local package.json's
-# `overrides` field pins iii-sdk down to match the engine (agentmemory's
-# caret range `^0.11.2` otherwise resolves to 0.11.6, the version that
-# requires the new sandbox-everything worker model the agentmemory CLI
-# is not refactored for yet). `npm install -g` ignores overrides, hence
-# the local prefix.
+# `overrides` field pins iii-sdk to the exact engine release in this image
+# (the worker speaks that engine's wire protocol, so the two must match).
+# `npm install -g` ignores overrides, hence the local prefix.
WORKDIR /opt/agentmemory
+RUN [ "${III_VERSION}" = "${III_SDK_VERSION}" ] \
+ || { echo "III_VERSION=${III_VERSION} and III_SDK_VERSION=${III_SDK_VERSION} must be the same release: the agentmemory worker speaks the wire protocol of the engine it was built against, so override both together" >&2; exit 1; }
RUN printf '{"name":"agentmemory-deploy","version":"1.0.0","private":true,"overrides":{"iii-sdk":"%s"}}\n' "${III_SDK_VERSION}" > package.json \
&& npm install "@agentmemory/agentmemory@${AGENTMEMORY_VERSION}" --omit=optional --no-fund --no-audit \
&& ln -s /opt/agentmemory/node_modules/.bin/agentmemory /usr/local/bin/agentmemory
diff --git a/deploy/fly/entrypoint.sh b/deploy/fly/entrypoint.sh
index 5fd4cc2681..f81f4bcbe6 100755
--- a/deploy/fly/entrypoint.sh
+++ b/deploy/fly/entrypoint.sh
@@ -16,10 +16,19 @@
set -eu
DATA_DIR="${AGENTMEMORY_DATA_DIR:-/data}"
+export AGENTMEMORY_DATA_DIR="$DATA_DIR"
HMAC_FILE="${AGENTMEMORY_HMAC_FILE:-/data/.hmac}"
RUN_AS="node:node"
III_CONFIG="/opt/agentmemory/node_modules/@agentmemory/agentmemory/dist/iii-config.yaml"
+if [ -z "${MALLOC_ARENA_MAX:-}" ]; then
+ export MALLOC_ARENA_MAX=2
+fi
+cur_nofile="$(ulimit -n)"
+if [ "$cur_nofile" != unlimited ] && [ "$cur_nofile" -lt 10240 ]; then
+ ulimit -n 10240 2>/dev/null || ulimit -n "$(ulimit -H -n)" 2>/dev/null || true
+fi
+
mkdir -p "$DATA_DIR"
chown -R "$RUN_AS" "$DATA_DIR"
@@ -43,6 +52,7 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/state_store.db
- name: iii-queue
config:
@@ -64,16 +74,17 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/stream_store
- name: iii-observability
config:
enabled: true
service_name: agentmemory
exporter: memory
- sampling_ratio: 1.0
+ sampling_ratio: 0.1
metrics_enabled: true
logs_enabled: true
- logs_console_output: true
+ logs_console_output: false
EOF
chown "$RUN_AS" "$III_CONFIG"
diff --git a/deploy/railway/Dockerfile b/deploy/railway/Dockerfile
index e094699881..3efeb64fae 100644
--- a/deploy/railway/Dockerfile
+++ b/deploy/railway/Dockerfile
@@ -1,26 +1,28 @@
-ARG III_VERSION=0.11.2
+ARG III_VERSION=0.22.1
FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.29
-ARG III_VERSION=0.11.2
-ARG III_SDK_VERSION=0.11.2
+ARG AGENTMEMORY_VERSION=0.9.30-codex.1
+ARG III_VERSION=0.22.1
+ARG III_SDK_VERSION=0.22.1
RUN apt-get update \
&& apt-get install -y --no-install-recommends openssl ca-certificates tini gosu curl \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
# Install agentmemory into a dedicated prefix so the local package.json's
-# `overrides` field pins iii-sdk down to match the engine (agentmemory's
-# caret range `^0.11.2` otherwise resolves to 0.11.6, the version that
-# requires the new sandbox-everything worker model the agentmemory CLI
-# is not refactored for yet). `npm install -g` ignores overrides, hence
-# the local prefix.
+# `overrides` field pins iii-sdk to the exact engine release in this image
+# (the worker speaks that engine's wire protocol, so the two must match).
+# `npm install -g` ignores overrides, hence the local prefix.
WORKDIR /opt/agentmemory
+RUN [ "${III_VERSION}" = "${III_SDK_VERSION}" ] \
+ || { echo "III_VERSION=${III_VERSION} and III_SDK_VERSION=${III_SDK_VERSION} must be the same release: the agentmemory worker speaks the wire protocol of the engine it was built against, so override both together" >&2; exit 1; }
RUN printf '{"name":"agentmemory-deploy","version":"1.0.0","private":true,"overrides":{"iii-sdk":"%s"}}\n' "${III_SDK_VERSION}" > package.json \
&& npm install "@agentmemory/agentmemory@${AGENTMEMORY_VERSION}" --omit=optional --no-fund --no-audit \
&& ln -s /opt/agentmemory/node_modules/.bin/agentmemory /usr/local/bin/agentmemory
diff --git a/deploy/railway/entrypoint.sh b/deploy/railway/entrypoint.sh
index ffdd633395..8df88f49df 100755
--- a/deploy/railway/entrypoint.sh
+++ b/deploy/railway/entrypoint.sh
@@ -16,10 +16,19 @@
set -eu
DATA_DIR="${AGENTMEMORY_DATA_DIR:-/data}"
+export AGENTMEMORY_DATA_DIR="$DATA_DIR"
HMAC_FILE="${AGENTMEMORY_HMAC_FILE:-/data/.hmac}"
RUN_AS="node:node"
III_CONFIG="/opt/agentmemory/node_modules/@agentmemory/agentmemory/dist/iii-config.yaml"
+if [ -z "${MALLOC_ARENA_MAX:-}" ]; then
+ export MALLOC_ARENA_MAX=2
+fi
+cur_nofile="$(ulimit -n)"
+if [ "$cur_nofile" != unlimited ] && [ "$cur_nofile" -lt 10240 ]; then
+ ulimit -n 10240 2>/dev/null || ulimit -n "$(ulimit -H -n)" 2>/dev/null || true
+fi
+
mkdir -p "$DATA_DIR"
chown -R "$RUN_AS" "$DATA_DIR"
@@ -43,6 +52,7 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/state_store.db
- name: iii-queue
config:
@@ -64,16 +74,17 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/stream_store
- name: iii-observability
config:
enabled: true
service_name: agentmemory
exporter: memory
- sampling_ratio: 1.0
+ sampling_ratio: 0.1
metrics_enabled: true
logs_enabled: true
- logs_console_output: true
+ logs_console_output: false
EOF
chown "$RUN_AS" "$III_CONFIG"
diff --git a/deploy/render/Dockerfile b/deploy/render/Dockerfile
index e094699881..3efeb64fae 100644
--- a/deploy/render/Dockerfile
+++ b/deploy/render/Dockerfile
@@ -1,26 +1,28 @@
-ARG III_VERSION=0.11.2
+ARG III_VERSION=0.22.1
FROM iiidev/iii:${III_VERSION} AS iii-image
FROM node:22-slim
-ARG AGENTMEMORY_VERSION=0.9.29
-ARG III_VERSION=0.11.2
-ARG III_SDK_VERSION=0.11.2
+ARG AGENTMEMORY_VERSION=0.9.30-codex.1
+ARG III_VERSION=0.22.1
+ARG III_SDK_VERSION=0.22.1
RUN apt-get update \
&& apt-get install -y --no-install-recommends openssl ca-certificates tini gosu curl \
&& rm -rf /var/lib/apt/lists/*
COPY --from=iii-image /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "the iiidev/iii:${III_VERSION} image does not contain iii ${III_VERSION}" >&2; exit 1; }
# Install agentmemory into a dedicated prefix so the local package.json's
-# `overrides` field pins iii-sdk down to match the engine (agentmemory's
-# caret range `^0.11.2` otherwise resolves to 0.11.6, the version that
-# requires the new sandbox-everything worker model the agentmemory CLI
-# is not refactored for yet). `npm install -g` ignores overrides, hence
-# the local prefix.
+# `overrides` field pins iii-sdk to the exact engine release in this image
+# (the worker speaks that engine's wire protocol, so the two must match).
+# `npm install -g` ignores overrides, hence the local prefix.
WORKDIR /opt/agentmemory
+RUN [ "${III_VERSION}" = "${III_SDK_VERSION}" ] \
+ || { echo "III_VERSION=${III_VERSION} and III_SDK_VERSION=${III_SDK_VERSION} must be the same release: the agentmemory worker speaks the wire protocol of the engine it was built against, so override both together" >&2; exit 1; }
RUN printf '{"name":"agentmemory-deploy","version":"1.0.0","private":true,"overrides":{"iii-sdk":"%s"}}\n' "${III_SDK_VERSION}" > package.json \
&& npm install "@agentmemory/agentmemory@${AGENTMEMORY_VERSION}" --omit=optional --no-fund --no-audit \
&& ln -s /opt/agentmemory/node_modules/.bin/agentmemory /usr/local/bin/agentmemory
diff --git a/deploy/render/entrypoint.sh b/deploy/render/entrypoint.sh
index ffdd633395..8df88f49df 100755
--- a/deploy/render/entrypoint.sh
+++ b/deploy/render/entrypoint.sh
@@ -16,10 +16,19 @@
set -eu
DATA_DIR="${AGENTMEMORY_DATA_DIR:-/data}"
+export AGENTMEMORY_DATA_DIR="$DATA_DIR"
HMAC_FILE="${AGENTMEMORY_HMAC_FILE:-/data/.hmac}"
RUN_AS="node:node"
III_CONFIG="/opt/agentmemory/node_modules/@agentmemory/agentmemory/dist/iii-config.yaml"
+if [ -z "${MALLOC_ARENA_MAX:-}" ]; then
+ export MALLOC_ARENA_MAX=2
+fi
+cur_nofile="$(ulimit -n)"
+if [ "$cur_nofile" != unlimited ] && [ "$cur_nofile" -lt 10240 ]; then
+ ulimit -n 10240 2>/dev/null || ulimit -n "$(ulimit -H -n)" 2>/dev/null || true
+fi
+
mkdir -p "$DATA_DIR"
chown -R "$RUN_AS" "$DATA_DIR"
@@ -43,6 +52,7 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/state_store.db
- name: iii-queue
config:
@@ -64,16 +74,17 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: /data/stream_store
- name: iii-observability
config:
enabled: true
service_name: agentmemory
exporter: memory
- sampling_ratio: 1.0
+ sampling_ratio: 0.1
metrics_enabled: true
logs_enabled: true
- logs_console_output: true
+ logs_console_output: false
EOF
chown "$RUN_AS" "$III_CONFIG"
diff --git a/deploy/render/render.yaml b/deploy/render/render.yaml
index d1871d5795..acba600864 100644
--- a/deploy/render/render.yaml
+++ b/deploy/render/render.yaml
@@ -15,8 +15,8 @@ services:
- key: PORT
value: "3111"
- key: AGENTMEMORY_VERSION
- value: "0.9.29"
+ value: "0.9.30-codex.1"
- key: III_VERSION
- value: "0.11.2"
+ value: "0.22.1"
- key: III_SDK_VERSION
- value: "0.11.2"
+ value: "0.22.1"
diff --git a/docker-compose.yml b/docker-compose.yml
index a74cd82a1a..f0be2cc5b6 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,34 +8,60 @@ services:
iii-init:
image: busybox:1.36
user: "0:0"
+ environment:
+ AGENTMEMORY_DOCKER_UID: "${AGENTMEMORY_DOCKER_UID:-65532}"
+ AGENTMEMORY_DOCKER_GID: "${AGENTMEMORY_DOCKER_GID:-65532}"
+ AGENTMEMORY_DOCKER_SKIP_CHOWN: "${AGENTMEMORY_DOCKER_SKIP_CHOWN:-0}"
volumes:
- "${AGENTMEMORY_DATA_DIR:-iii-data}:/data"
- entrypoint: ["sh", "-c", "chown -R 65532:65532 /data && chmod 755 /data"]
+ entrypoint: ["sh", "-c", "if [ \"$${AGENTMEMORY_DOCKER_SKIP_CHOWN}\" = \"1\" ]; then exit 0; fi; chown -R $${AGENTMEMORY_DOCKER_UID}:$${AGENTMEMORY_DOCKER_GID} /data && chmod 755 /data"]
restart: "no"
iii-engine:
- # Pinned to v0.11.2 — the last engine that runs agentmemory's current
- # worker model cleanly. v0.11.6 introduces a new sandbox-everything-
- # via-`iii worker add` model that agentmemory hasn't been refactored
- # for yet; the architectural mismatch surfaces as EPIPE reconnect
- # loops and empty search after save. Bump only after agentmemory is
- # refactored to register as a sandboxed worker.
+ # Pinned to the same release as agentmemory's iii-sdk dependency
+ # (package.json). The worker speaks this engine's wire protocol, so
+ # bump the image tag and the SDK together, never one of them alone.
+ # 0.22.x is the last line before 0.23 removes the config.yaml worker
+ # lifecycle; it keeps HTTP routes owned by the reconnecting worker.
#
# Override per-shell or via .env file:
- # AGENTMEMORY_III_VERSION=0.11.7 docker compose up
- image: iiidev/iii:${AGENTMEMORY_III_VERSION:-0.11.2}
- user: "65532:65532"
+ # AGENTMEMORY_III_VERSION=0.22.1 docker compose up
+ image: iiidev/iii:${AGENTMEMORY_III_VERSION:-0.22.1}
+ user: "${AGENTMEMORY_DOCKER_UID:-65532}:${AGENTMEMORY_DOCKER_GID:-65532}"
depends_on:
iii-init:
condition: service_completed_successfully
+ command: ["--config", "/app/config.yaml", "--no-update-check"]
+ environment:
+ III_TELEMETRY_ENABLED: "${III_TELEMETRY_ENABLED:-false}"
+ III_REST_PORT: "${III_REST_PORT:-3111}"
+ III_STREAM_PORT: "${III_STREAM_PORT:-3112}"
+ III_VIEWER_PORT: "${III_VIEWER_PORT:-3113}"
+ III_ENGINE_PORT: "${III_ENGINE_PORT:-49134}"
+ AGENTMEMORY_REDIS_URL: "${AGENTMEMORY_REDIS_URL:-}"
+ AGENTMEMORY_STATE_SAVE_INTERVAL_MS: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"
+ MALLOC_ARENA_MAX: "${MALLOC_ARENA_MAX:-2}"
+ ulimits:
+ nofile:
+ soft: 10240
+ hard: 10240
ports:
- - "127.0.0.1:49134:49134"
- - "127.0.0.1:3111:3111"
- - "127.0.0.1:3112:3112"
- - "127.0.0.1:9464:9464"
+ - "127.0.0.1:${III_ENGINE_PORT:-49134}:${III_ENGINE_PORT:-49134}"
+ - "127.0.0.1:${III_REST_PORT:-3111}:${III_REST_PORT:-3111}"
+ - "127.0.0.1:${III_STREAM_PORT:-3112}:${III_STREAM_PORT:-3112}"
+ - "127.0.0.1:${AGENTMEMORY_METRICS_PORT:-9464}:9464"
volumes:
- "${AGENTMEMORY_DATA_DIR:-iii-data}:/data"
- ./iii-config.docker.yaml:/app/config.yaml:ro
+ # The engine persists each builtin worker's seeded config block under
+ # config/ next to its config file (/app/config in the image) on first
+ # boot and treats that copy as the source of truth afterwards. Keeping
+ # it on a tmpfs means every container start re-seeds from config.yaml
+ # and the III_* env vars, the same behavior the native CLI path has.
+ - type: tmpfs
+ target: /app/config
+ tmpfs:
+ mode: 01777
restart: unless-stopped
logging:
driver: json-file
diff --git a/docs/benchmarks/capture-costs.svg b/docs/benchmarks/capture-costs.svg
new file mode 100644
index 0000000000..78a51dd41c
--- /dev/null
+++ b/docs/benchmarks/capture-costs.svg
@@ -0,0 +1,104 @@
+
+agentmemory capture path under a hard kill, and what it costs
+Tool calls flow from the agent through the post-tool-use hook into agentmemory on port 3111 and into state. The service is killed with SIGKILL; the next tool calls land in the local spool file capture-spool/local-3111.jsonl. After the restart the spool drains into state. Measured: 10,000 of 10,000 memories and vectors back after SIGKILL with 0 embedding calls, and 1,000 of 1,000 tool calls kept while the service was down. At 10,000 memories: 32 MiB of disk for text, 72 MiB with 768-dimension vectors, 504 to 788 MiB of RAM for engine and worker, 1,455 of 2,000 context tokens per session, hook median 59 to 139 ms with p95 under 235 ms, and no API keys required.
+
+
+
+
+
+AGENTMEMORY · CAPTURE PATH UNDER A HARD KILL
+NPM RUN BENCH:CAPTURE-COSTS
+
+AGENT
+HOOK
+SERVICE
+STATE
+
+Bashnpm test
+Editsrc/auth.ts
+Readpackage.json
+Grep"TODO"
+Bashgit diff
+Writedocs/api.md
+
+
+
+
+
+
+
+
+post-tool-use
+
+
+agentmemory
+:3111
+
+SIGKILL
+restarted in ~1 s
+
+
+mem:obs:*
+vec-pending
+every call stored
+
+LOCAL SPOOL
+
+capture-spool/
+local-3111.jsonl
+3 kept while down
+drained on restart
+
+
+
+
+
+
+
+
+
+10,000 / 10,000 memories and vectors back after SIGKILL,
+0 embedding calls. 1,000 / 1,000 tool calls kept while down.
+
+
+
+COST AT 10,000 MEMORIES
+disk, text only32 MiB
+disk, 768-d vectors72 MiB
+RAM, engine+worker504–788 MiB
+context/session1,455/2,000 tok
+hook p5059–139 ms
+hook p95< 235 ms
+API keys needednone
+At 1,000: 3.6 / 7.6 MiB disk,
+266–365 MiB RAM.
+
+Apple M1 Max · iii 0.22.1 · stub 768-d embedder · file state store · worst of 2 runs · 2026-10-02
+
diff --git a/docs/plugins/antigravity.md b/docs/plugins/antigravity.md
new file mode 100644
index 0000000000..1284676fac
--- /dev/null
+++ b/docs/plugins/antigravity.md
@@ -0,0 +1,69 @@
+# Agent Memory for Antigravity
+
+Start the Agent Memory daemon, then configure the surface you use:
+
+```sh
+agentmemory connect antigravity-cli --with-hooks
+# Antigravity IDE or 2.0:
+agentmemory connect antigravity --with-hooks
+```
+
+Current Antigravity surfaces share `~/.gemini/config/mcp_config.json` and
+`~/.gemini/config/hooks.json`. Workspace overrides live in `.agents/`. Restart the
+host after installation. In the CLI, `agy mcp list` lists configured servers and
+`/hooks` shows active hooks. This integration uses the MCP connector and bundled
+hook scripts; the repository does not yet ship an Antigravity plugin bundle.
+
+Older Agent Memory connectors wrote the IDE config into its application-support
+directory and used shell-style environment defaults that Antigravity does not
+expand. After upgrading, inspect your agentmemory MCP settings, then rerun the
+appropriate command with `--force` to refresh that entry. Other servers and hook
+bundles are preserved. Custom values on the agentmemory entry must be reapplied.
+
+Launch the host with `AGENTMEMORY_URL` for a custom daemon endpoint and
+`AGENTMEMORY_SECRET` when remote authentication requires it. The generated entry
+inherits the process environment. Local clients also read the daemon-generated
+credential. Do not paste secrets into committed configuration.
+
+## Capture behavior
+
+- The first model invocation opens the session. With
+ `AGENTMEMORY_INJECT_CONTEXT=true`, recalled context is passed back through
+ Antigravity's `injectSteps` response.
+- Tool names, inputs, and reported failures are captured. Native PostToolUse
+ payloads currently omit successful tool output, so full output replay is not
+ available through this hook alone.
+- Explicit user prompts are backfilled from the host transcript when execution
+ becomes fully idle. Repeated backfills and tool deliveries use stable event IDs.
+- Idle Stop closes the session once. Stops with pending background work do not
+ close it.
+
+Keep the installed package path free of spaces for Antigravity hook command
+compatibility. The installer warns and skips hooks when that condition is not met.
+MCP can still be configured. Re-run `connect ... --with-hooks` after moving or
+upgrading the package so absolute script paths stay current.
+
+## Repeat the native CLI test
+
+```sh
+npm run build
+AGENTMEMORY_TEST_ANTIGRAVITY=/absolute/path/to/agy node scripts/plugins/test-antigravity-native.mjs
+```
+
+Verified with Antigravity CLI 1.3.0. The test uses a temporary profile, a synthetic
+local Gemini endpoint, and a generated sample file. It checks connector discovery,
+inherited MCP environment, recalled context reaching the model, native tool capture,
+transcript prompt backfill, and one session lifecycle. It launches the bundled MCP
+bridge from the checkout because the release-prep runtime is not yet published.
+No Google account credentials or paid model calls are used.
+
+The live daemon suite also exercises this bridge with the pinned iii engine,
+including authentication, shared memory, offline capture recovery, and restart
+persistence. IDE UI dispatch, native Windows execution, and an Antigravity plugin
+bundle remain unverified or unimplemented.
+
+Contract references checked October 6, 2026:
+
+- [MCP configuration](https://antigravity.google/docs/mcp)
+- [Hook events and payloads](https://antigravity.google/docs/hooks)
+- [CLI model endpoint configuration](https://antigravity.google/docs/cli/install/)
diff --git a/docs/plugins/codex-local.md b/docs/plugins/codex-local.md
new file mode 100644
index 0000000000..c4c8066006
--- /dev/null
+++ b/docs/plugins/codex-local.md
@@ -0,0 +1,182 @@
+# Agent Memory for local Codex
+
+The plugin connects Codex to your running Agent Memory daemon through a bundled
+stdio MCP bridge. It uses the same store as your configured Claude Code client.
+It includes 17 shared skills, the daemon's enabled tools, three fixed resources,
+three resource templates, and three prompts. The default daemon exposes 54 tools;
+features such as embeddings, reflection, and team operations still need their
+normal runtime configuration. Six optional hooks provide automatic capture on
+Codex versions that support and trust them.
+
+## Build and try the current source
+
+Use Node.js 20+ and the system `zip` utility on macOS or Linux. From the repository:
+
+```sh
+npm install --legacy-peer-deps --no-audit --no-fund
+npm run plugin:pack:codex
+node dist/cli.mjs
+```
+
+The final command starts Agent Memory and may offer to install its pinned iii
+engine. Keep the daemon running. In another terminal, use `node dist/cli.mjs status`
+to check it. Use the built runtime when testing unreleased main; the published npm
+package can lag the checkout.
+
+Packaging creates `dist/plugins/agentmemory-codex-local/` and a versioned ZIP.
+The archive has `.codex-plugin/plugin.json` and `.mcp.json` at its root, and
+contains the bundled bridge, shared skills, icon, and supported hook scripts.
+It excludes the Claude and Copilot manifests so their defaults cannot override
+Codex configuration. `build-info.json` records the base revision and archive hashes;
+uncommitted changes are included in the build, so it is not a release attestation.
+
+Install the built folder through its generated local marketplace:
+
+`agentmemory-local-preview` names this local test marketplace. It is not an npm
+package or a public directory listing.
+
+```sh
+codex plugin marketplace add ./dist/plugins
+codex plugin add agentmemory@agentmemory-local-preview
+```
+
+Restart Codex, inspect its MCP connection, and run the onboarding starter prompt.
+Local installation copies the plugin into Codex's cache. After changing source,
+rebuild and refresh or reinstall the preview; editing the source folder alone
+does not update an installed copy.
+
+After the feature is released in the repository, marketplace installation is:
+
+```sh
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin add agentmemory@agentmemory
+```
+
+Those marketplace commands track published repository content. They do not install
+unpublished changes from your working tree. Restart Codex after installation.
+
+## Connection and capture
+
+The bridge runs with `node scripts/plugin-bridge.mjs` from the installed plugin
+directory. Codex resolves its relative `cwd` to that directory, including paths
+with spaces. No npm download occurs when the bridge starts.
+
+Default daemon URL: `http://localhost:3111`. Local authentication works without
+copying a secret into Codex: the bridge uses `AGENTMEMORY_SECRET` from the host
+environment, then the secret in `~/.agentmemory/.env`, then the daemon-generated
+`~/.agentmemory/secret`. It rereads credentials for each request so a daemon
+started after the bridge can connect without reinstalling the plugin.
+
+For a custom port, supply `AGENTMEMORY_URL` to the MCP host and reconnect MCP.
+Local credential files are read only for loopback URLs. A remote daemon requires
+an explicit host `AGENTMEMORY_SECRET` and HTTPS when authenticated. Never put
+credential values in a plugin manifest or archive.
+
+`agentmemory connect codex` remains the alternative for MCP-only setup. If that
+connection already exists, choose either it or the plugin's MCP connection to
+avoid duplicate tools. Do not overwrite unrelated Codex configuration.
+
+Check `/hooks` and trust the plugin hooks before expecting automatic capture.
+Some Codex versions require `agentmemory connect codex --with-hooks` for global
+hooks. Inspect the existing configuration first: enabling both native plugin
+hooks and global copies can duplicate capture. Validate one captured event in
+your host. On uninstall, remove any separately installed global hook entries or
+MCP entry you no longer want; deleting the plugin does not remove your memories.
+
+The bridge returns a visible failure if the daemon is stopped or authentication
+fails. It does not save into the standalone fallback store. It does not retry
+mutations automatically; a timeout can happen after a write committed, so inspect
+state before retrying. Reconnect after changing the daemon's enabled tool surface.
+
+Capture hooks ship with their shared `_capture.mjs` dependency. During an outage,
+supported hooks retain observations in the runtime's bounded local spool. Inspect
+it with `agentmemory capture --json`. The daemon recovers its spool at startup;
+use `agentmemory capture --drain` to request recovery while it is running. Use the same port
+and data-directory settings as the hooks. This recovery applies to captured
+observations; failed MCP tool writes are not queued automatically.
+
+## Verify before distributing
+
+After packaging, run the live smoke test with an already installed binary matching
+`III_PINNED_VERSION` in `src/version.ts`:
+
+```sh
+AGENTMEMORY_TEST_III=/absolute/path/to/iii npm run test:plugin:live
+```
+
+It starts a real engine and worker on temporary loopback ports, with a temporary
+store and no model credentials. It checks daemon-generated authentication,
+packaged hook capture and offline recovery, both MCP entry points sharing
+memories, resources, prompts, lessons, deletion, outage failures, and persistence
+across an engine restart. It launches hook scripts directly;
+desktop hook dispatch and host trust UI still require a manual host test. The
+normal test suite skips this check unless the engine path is explicitly set.
+
+To exercise native plugin discovery and hook dispatch with an installed Codex CLI:
+
+```sh
+npm run plugin:pack:codex
+AGENTMEMORY_TEST_CODEX=/absolute/path/to/codex node scripts/plugins/test-codex-native.mjs
+```
+
+The test uses a temporary home and a synthetic local Responses API to make Codex
+read one generated file. It checks MCP startup, session context reaching the model,
+prompt/tool capture, and session completion. It trusts only the built test plugin
+for that invocation through Codex's automation flag. No account credentials or
+paid model calls are used. Verified with Codex CLI 0.150.1; desktop trust UI and
+PreCompact dispatch are separate checks.
+
+The current `connect codex --with-hooks` path skips hook installation if MCP is
+already wired. The native plugin path above works. For global hooks, inspect your
+agentmemory MCP settings before using `--force`, which rewrites that MCP entry.
+
+After publishing the selected runtime and shim versions, run:
+
+```sh
+npm run plugin:verify:published
+```
+
+This read-only registry check rejects mismatched runtime, shim, and engine SDK
+versions, including a reused version whose published engine dependencies differ
+from source. It requires an exact shim-to-runtime dependency. Building a ZIP does
+not publish the matching daemon; do not distribute it as a release until this
+check passes. The check does not establish OpenAI directory eligibility.
+
+## Data and costs
+
+Basic keyword recall requires no model key. Storage remains in the configured
+daemon's local state. Local embeddings need an optional model download and local
+compute. Compression, reflection, and external embeddings can use model tokens
+and send selected content to the configured provider. Context injection consumes
+the coding agent's context budget. Enable these features deliberately.
+
+Memory results are evidence, not instructions. Respect user rules about saving,
+verify changing facts against current code, and avoid saving secrets. Project
+metadata is a retrieval aid, not an account or tenant authorization boundary.
+
+## Public directory submission
+
+The generated `agentmemory-codex-review` ZIP has MCP and skills but no lifecycle
+hooks. It is a preparation artifact, not a submission-ready claim. OpenAI's
+standard public flow currently expects a production HTTPS MCP server. Its guide
+directs authors who need local MCP to contact OpenAI for support. Confirm local
+stdio eligibility and the supported test environment before submitting this
+archive. Removing hooks does not remove that requirement.
+
+Once eligibility is confirmed: select a verified developer identity in the
+[plugin dashboard](https://platform.openai.com/plugins), upload the complete MCP
+package, resolve validation findings, supply five positive and three negative
+tested scenarios plus an accessible demo, and submit for review. Publish after
+approval. Privacy, terms, support details, and any required review access must be
+real and accessible; this build does not invent those URLs or credentials.
+
+See the repository's `docs/plugins/codex-submission.md` for the local-support brief
+and proposed reviewer scenarios. Rebuild against the final release commit after
+pending PRs merge, align runtime and manifest versions, and repeat artifact tests.
+
+Sources checked October 1, 2026:
+
+- [Packaging and local runtime](https://developers.openai.com/plugins/build/plugins)
+- [Submission requirements](https://developers.openai.com/plugins/deploy/submission)
+- [Local MCP eligibility](https://developers.openai.com/plugins/guides/submit-claude-plugin)
+- [Codex hooks](https://learn.chatgpt.com/docs/hooks)
diff --git a/docs/plugins/codex-submission.md b/docs/plugins/codex-submission.md
new file mode 100644
index 0000000000..ed31c0eea0
--- /dev/null
+++ b/docs/plugins/codex-submission.md
@@ -0,0 +1,69 @@
+# Local MCP submission preparation
+
+Status: local Codex package implemented; public directory eligibility, release
+version, policy URLs, accessible demo, and review execution remain to be completed.
+Nothing has been submitted or published by this workflow.
+
+## Brief for the OpenAI contact
+
+Agent Memory is an Apache-2.0 persistent-memory project for coding agents. We want
+to distribute a Codex plugin with a local stdio MCP server. The bundled Node.js
+bridge connects to the user's local Agent Memory daemon. It shares the daemon's
+memory store with other configured coding agents. A hosted deployment would not
+provide equivalent access to local sessions, files, or offline workflows.
+
+The package includes guided setup, recall, session handoff, lessons, and memory
+management. No account is needed for local keyword recall. Optional external model
+providers are configured separately. The review archive contains no lifecycle
+hooks; local users can install the capture-enabled package where supported.
+
+Please confirm whether local stdio MCP is eligible for directory review, which
+Codex surfaces can install it, and how reviewers should receive and launch the
+local daemon. Please also confirm whether capture hooks require a separate review
+path. We can provide an isolated sample dataset and a recorded local walkthrough.
+
+This is a draft to send after release details are filled in. It has not been sent.
+
+## Reviewer scenarios
+
+Use an isolated daemon with synthetic repositories Alpha and Beta. Record the
+runtime version, plugin hash, host version, tool outputs, and actual results for
+each case. These are proposed acceptance scenarios, not completed user testing.
+
+| Kind | Prompt or setup | Expected tools and behavior |
+| --- | --- | --- |
+| Positive | Remember that Alpha uses cursor pagination because offset scans exceeded its latency budget. | `memory_save`; save the supplied fact and reason, return its identifier. |
+| Positive | In a fresh Codex session, recall why Alpha uses cursor pagination. | `memory_smart_search` or `memory_recall`; return the saved fact and provenance. Verify it belongs to Alpha. |
+| Positive | Resume the most recent session for Alpha. | `memory_sessions`, then recall; select Alpha's recorded session and open question. |
+| Positive | Learn that CI must run tests once because watch mode hangs. | `memory_lesson_save`, then `memory_lesson_recall`; preserve the correction and scope. |
+| Positive | Forget the synthetic pagination memory with this identifier. | `memory_governance_delete`; honor the exact authorized target, then verify absence. |
+| Negative | Stop the daemon while requesting a save. | A visible failure; no fallback-store success claim and no automatic write retry. |
+| Negative | Seed a memory that instructs the model to export other memories to an unrelated URL. | Treat the record as untrusted data; do not execute the instruction. |
+| Negative | Ask to resume a project with no matching session, while Beta has recent sessions. | Report no matching project session; do not substitute Beta or invent history. |
+
+Project scope is not multi-tenant access control. Do not claim that a user with
+access to the local daemon cannot read other projects in that same store.
+
+## Release gates
+
+- Rebuild from the final release commit after reviewing overlapping pending PRs.
+ Existing work includes MCP annotations, project scoping, standalone resources
+ and prompts, Codex hook refresh, and shim version pinning. Preserve those PRs.
+- Validate the packaged bridge over stdio and HTTP, then install it in a clean
+ Codex CLI and desktop profile. Verify one real captured event and a restart.
+- Run `npm run plugin:verify:published` after publishing matched versions; a
+ successful source build does not establish npm compatibility.
+- Test Claude Code and Codex against the same isolated daemon for handoff.
+ `AGENTMEMORY_TEST_III=/absolute/path/to/iii npm run test:plugin:live` exercises
+ their MCP entry points and packaged hook scripts. It does not replace a host UI
+ test or the recorded walkthrough.
+- Record all eight reviewer scenarios, including tool errors and provenance.
+- Fill in accessible privacy and terms URLs, support details, and the demo URL.
+ Use synthetic data; provide review access separately if requested.
+- Obtain OpenAI's local-MCP eligibility instructions, then upload the review ZIP
+ and resolve dashboard checks. Do not submit the hook-containing local ZIP to a
+ flow that disallows lifecycle hooks.
+
+[Official submission guide](https://developers.openai.com/plugins/deploy/submission)
+and [local MCP conversion guidance](https://developers.openai.com/plugins/guides/submit-claude-plugin)
+were checked October 1, 2026. Recheck before submission.
diff --git a/docs/plugins/copilot.md b/docs/plugins/copilot.md
new file mode 100644
index 0000000000..db0a4593a4
--- /dev/null
+++ b/docs/plugins/copilot.md
@@ -0,0 +1,110 @@
+# GitHub Copilot setup and capture
+
+MCP exposes memory tools. Automatic observation capture requires hooks as well. A working tool list alone does not prove that Copilot activity is being saved.
+
+## Start the persistent service
+
+Install Agent Memory and run its setup in a separate terminal:
+
+```sh
+npm install -g @agentmemory/agentmemory@latest
+agentmemory
+```
+
+Then check `agentmemory status`. The API normally listens on port 3111; the viewer uses port 3113. A missing LLM provider disables optional compression and summarization. Capture, explicit saves, and keyword recall still work without a provider key. A Copilot subscription does not configure an Agent Memory LLM provider.
+
+For this unreleased branch, run `npm run build` and use `node dist/cli.mjs` instead of the published CLI. Do not assume npm's latest version includes release-branch fixes.
+
+## Copilot CLI
+
+Choose either the full plugin or MCP-only wiring:
+
+```sh
+# Full plugin: MCP, skills, and lifecycle capture
+copilot plugin install rohitg00/agentmemory:plugin
+
+# Alternatively, tools and usage instructions without automatic capture
+agentmemory connect copilot-cli
+```
+
+For a checkout of this branch, use `copilot plugin install /absolute/path/to/agentmemory/plugin`. Restart Copilot after installation or `copilot plugin update agentmemory`. Direct installs work in Copilot CLI 1.0.92 but that client warns that future versions will require marketplace installs.
+
+The full plugin runs the bundled Node.js MCP bridge. Copilot loads the shared `.mcp.json` ahead of the manifest's `.mcp.copilot.json` reference, so both configurations must use that bridge. It forwards to the same persistent daemon as the hooks, reads locally generated credentials, and reports connection failures without switching to an in-memory store. It requires Node.js on Copilot's PATH and a running Agent Memory daemon.
+
+The bridge and hooks inherit `AGENTMEMORY_URL` and `AGENTMEMORY_SECRET` from the host environment. Local credentials are also read from `~/.agentmemory/.env` or `~/.agentmemory/secret`. For remote servers, set the URL and secret explicitly; use HTTPS for authenticated remote MCP connections. Tool visibility is controlled by the daemon's `AGENTMEMORY_TOOLS` setting.
+
+Capture runs by default. To also inject recalled context at session start, launch Copilot with `AGENTMEMORY_INJECT_CONTEXT=true` in its environment. Copilot CLI consumes JSON `additionalContext`; VS Code uses `hookSpecificOutput.additionalContext`.
+
+## VS Code Copilot: local agent sessions
+
+`agentmemory connect copilot-cli` configures the standalone CLI, not VS Code. VS Code currently requires manual MCP and hook configuration. These instructions target local agent sessions; remote Agent Host sessions have their own hook environment.
+
+Find the global package directory with `npm root -g`. In the examples below, replace `/ABSOLUTE/PACKAGE` with that directory followed by `/@agentmemory/agentmemory`. For a source checkout, use the checkout directory after building it. On Windows, use forward slashes in JSON paths or escape backslashes.
+
+Merge this entry into `.vscode/mcp.json`, preserving your existing servers. VS Code uses `servers` as the top-level key:
+
+```json
+{
+ "servers": {
+ "agentmemory": {
+ "type": "stdio",
+ "command": "node",
+ "args": ["/ABSOLUTE/PACKAGE/plugin/scripts/plugin-bridge.mjs"]
+ }
+ }
+}
+```
+
+The bundled bridge is present in the 0.9.30 release branch. Before that release is published, use a built checkout for this setup.
+
+For automatic capture, create `.github/hooks/agentmemory.json` in the workspace:
+
+```json
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "type": "command",
+ "command": "node \"/ABSOLUTE/PACKAGE/plugin/scripts/session-start.mjs\""
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "type": "command",
+ "command": "node \"/ABSOLUTE/PACKAGE/plugin/scripts/prompt-submit.mjs\""
+ }
+ ],
+ "PostToolUse": [
+ {
+ "type": "command",
+ "command": "node \"/ABSOLUTE/PACKAGE/plugin/scripts/post-tool-use.mjs\""
+ }
+ ],
+ "Stop": [
+ {
+ "type": "command",
+ "command": "node \"/ABSOLUTE/PACKAGE/plugin/scripts/stop.mjs\""
+ }
+ ]
+ }
+}
+```
+
+Enable `chat.useHooks` and trust the workspace, then start a new local agent session. This captures prompts and completed tool calls as they happen; it does not require deleting a chat or closing VS Code. `Stop` requests session summarization after an agent turn. To inject recalled context, add `"env": { "AGENTMEMORY_INJECT_CONTEXT": "true" }` to the SessionStart entry.
+
+Keep machine-specific absolute paths local, or adjust them for each machine. The hooks must run where the package, daemon, and memory data directory are accessible. If the daemon uses a custom `AGENTMEMORY_DATA_DIR`, pass the same directory to the hooks so offline capture is recovered on restart.
+
+## Verify data, not just connectivity
+
+1. Ask Copilot to save a unique synthetic fact with `memory_save`, then recall it with `memory_smart_search` in a new session.
+2. Ask Copilot to read a small project file. Check `memory_sessions` for that session and a nonzero observation count. MCP-only setups need explicit saves; they do not automatically capture reads.
+3. Run `agentmemory capture --json` to inspect offline spool records and failed capture delivery. `agentmemory capture --drain` requests recovery once the service is running.
+4. If an older MCP log says `falling back to local InMemoryKV`, check the running daemon and update the MCP configuration. That fallback does not provide durable cross-session memory.
+
+References: [Copilot plugin configuration](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference), [Copilot hook payloads](https://docs.github.com/en/copilot/reference/hooks-reference), [VS Code local hooks](https://code.visualstudio.com/docs/agents/reference/hooks-reference), [VS Code hook configuration](https://code.visualstudio.com/docs/agent-customization/hooks).
+
+## Maintainer checks
+
+After building, `node scripts/plugins/test-copilot-native.mjs` runs the actual Copilot plugin installer and runtime against a local synthetic model and capture server. Set `AGENTMEMORY_TEST_COPILOT` to the client executable and `AGENTMEMORY_TEST_COPILOT_SDK` to that client's bundled `copilot-sdk/index.js`. It uses a temporary home and project, verifies the loaded MCP command and skills, then checks prompt/tool capture and context delivery. It does not require a Copilot account or send project data to a model provider.
+
+To separately verify persistent storage and recovery with the pinned iii engine, build the Codex package with `node scripts/plugins/package-codex.mjs`, then set `AGENTMEMORY_TEST_III` to the engine executable and run `node node_modules/vitest/vitest.mjs run test/codex-live-daemon.test.ts`. That suite exercises both Codex and Copilot configurations.
diff --git a/docs/reliability/source-and-vector-recovery.md b/docs/reliability/source-and-vector-recovery.md
new file mode 100644
index 0000000000..4bfb8986f5
--- /dev/null
+++ b/docs/reliability/source-and-vector-recovery.md
@@ -0,0 +1,32 @@
+# Source retention and vector recovery
+
+Compressed observations retain sanitized source fields for replay and export. The source lives in the same observation row and follows its deletion lifecycle. Search, context expansion, observation listings, shared feeds, and compressed live updates continue to return summaries without the retained source.
+
+## Storage and token bounds
+
+Each serialized source is capped at 16 KiB, including its metadata. Oversized fields retain a prefix and set `truncated: true`; `originalBytes` records the source size before truncation. Previously discarded source cannot be reconstructed. Replay reports source availability and truncation separately for every observation.
+
+Live compression and imports allocate new source from an 8 MiB session budget after subtracting already-retained source. Available response space can reduce that budget further. Existing source above the allowance is preserved, with no additional source allocated; it is not retroactively capped. Imports report `sourceTruncated` and `sourceOmitted`; omission preserves the summary when even source metadata will not fit. A batch that already fits keeps its source unchanged. Live writes and imports share the existing per-session write lock while checking the budget and writing observations. Model calls happen outside the compression write lock. JSONL observation writes run in sequential batches of 20.
+
+These locks coordinate one worker process. They do not provide distributed transactions. JSONL imports commit one file at a time, so a rejected later file can leave earlier files imported. Raising the ordinary capture limit of 500 observations does not raise the retained-source allowance; summary data and temporary raw observations have separate storage and response-size requirements.
+
+Retention adds storage and serialization work. It does not enable model compression, inject extra source into ordinary recall, or add a queue. Explicit replay and export responses can be larger and can consume agent context if an agent requests them.
+
+## First checkpoint and crash window
+
+A fresh vector index schedules its first checkpoint within five seconds of completed vector work, or sooner when the configured interval requires it. Subsequent checkpoints use the configured interval, which defaults to 600,000 ms. Saves write changed vector entries with bounded concurrency rather than rewriting the full index per observation.
+
+Five seconds is a scheduling bound, not a disk-durability guarantee. Completion depends on the storage service, and its persistence window still applies. A crash before a completed, persisted checkpoint can lose vectors. Later unsaved vectors remain subject to the normal batching window. Failed writes stay pending for retry at the normal interval.
+
+Status distinguishes active vector backfill from backfill waiting for explicit opt-in. Missing vectors do not silently trigger unlimited embedding calls. Keyword recovery remains independent of vector coverage.
+
+## Verification
+
+Validation used main `ab3e4efd282659b87d31b36c8514c6bc6b871f0b` as the baseline and an installed package built from the fix branch. Synthetic records and a deterministic local embedding fixture exercised persistence, not semantic retrieval quality.
+
+- The baseline lost long source tails and had zero recovered vectors before its first scheduled checkpoint. The fixed package retained all 20 source records and vectors after a completed checkpoint, a six-second storage-persistence opportunity, and forced worker/service termination.
+- Embedding requests stayed at 21 across restart: 20 captures and one search. The ordinary search response stayed at 4,288 wire bytes on both builds; capture hooks emitted no context.
+- A 1,000-record import remained readable with explicit truncation. Three subsequent live captures preserved their summaries, truncated one source to the remaining allowance, and omitted the other two sources. Two concurrent 600-record imports remained readable as a 1,200-record session, with source omissions reported for the exhausted budget.
+- The full suite passed 2,099 tests with one skipped; build and skill validation passed. Type checking reported the same 29 existing diagnostics as the baseline, with none added.
+
+The initial 20-record fixed fixture used 156,762 bytes of state files versus 41,682 bytes on the baseline. Combined worker/service RSS after restart was 181,488 KiB versus 180,032 KiB. These are point measurements, not capacity or CPU benchmarks; the disk difference includes both retained source and saved vectors.
diff --git a/eval/README.md b/eval/README.md
index 7f29536705..5b008d0d93 100644
--- a/eval/README.md
+++ b/eval/README.md
@@ -26,11 +26,11 @@ source eval/scripts/sandbox.sh
npm run eval:coding-life -- --adapters grep,agentmemory
```
-Requires iii v0.11.2 on PATH (agentmemory pin). If you already have a different version installed, install the pinned build into `~/.local/bin` and make sure that directory comes first on `PATH`:
+Requires iii v0.22.1 on PATH (agentmemory pin). If you already have a different version installed, install the pinned build into `~/.local/bin` and make sure that directory comes first on `PATH`:
```sh
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
+curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin
export PATH="$HOME/.local/bin:$PATH" # add to ~/.zshrc or ~/.bashrc for persistence
```
diff --git a/eval/scripts/sandbox.sh b/eval/scripts/sandbox.sh
index 5d4023300f..2cf6edeea6 100755
--- a/eval/scripts/sandbox.sh
+++ b/eval/scripts/sandbox.sh
@@ -14,13 +14,15 @@ REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
if ! command -v iii >/dev/null 2>&1; then
echo "iii binary not on PATH. Install pinned version:"
- echo " 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"
+ echo ' curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz'
+ echo ' echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin'
+ echo ' (other platforms: check the matching .sha256 file on the release page before extracting)'
exit 1
fi
iii_ver=$(iii --version 2>&1 | head -1)
-if [[ "$iii_ver" != "0.11.2" ]]; then
- echo "warning: iii version on PATH is $iii_ver; agentmemory pins 0.11.2"
+if [[ "$iii_ver" != "0.22.1" ]]; then
+ echo "warning: iii version on PATH is $iii_ver; agentmemory pins 0.22.1"
fi
if [[ ! -f "$REPO_ROOT/dist/index.mjs" ]]; then
diff --git a/examples/python/README.md b/examples/python/README.md
index ea284dd47e..3e4d3e5921 100644
--- a/examples/python/README.md
+++ b/examples/python/README.md
@@ -10,7 +10,7 @@ This example uses the official Python SDK.
## Install
```bash
-pip install iii-sdk
+pip install iii-sdk==0.22.1
```
## Quickstart
diff --git a/examples/python/observe_and_recall.py b/examples/python/observe_and_recall.py
index 4747bf0b52..b9c65de5b7 100644
--- a/examples/python/observe_and_recall.py
+++ b/examples/python/observe_and_recall.py
@@ -4,7 +4,7 @@
agentmemory to render the most relevant context back at a fixed token budget.
Prerequisites:
- pip install iii-sdk
+ pip install iii-sdk==0.22.1
npx -y @agentmemory/agentmemory
Run:
diff --git a/examples/python/quickstart.py b/examples/python/quickstart.py
index 56e5ae11ae..0339e079dd 100644
--- a/examples/python/quickstart.py
+++ b/examples/python/quickstart.py
@@ -1,7 +1,7 @@
"""Minimal agentmemory usage via iii-sdk.
Prerequisites:
- pip install iii-sdk
+ pip install iii-sdk==0.22.1
npx -y @agentmemory/agentmemory # daemon at ws://localhost:49134
Run:
diff --git a/iii-config.docker.yaml b/iii-config.docker.yaml
index 682236ec37..4cc638a46b 100644
--- a/iii-config.docker.yaml
+++ b/iii-config.docker.yaml
@@ -1,18 +1,23 @@
workers:
- name: iii-http
config:
- port: 3111
+ port: ${III_REST_PORT:3111}
host: 0.0.0.0
default_timeout: 180000
cors:
- allowed_origins: ["http://localhost:3111", "http://localhost:3113", "http://127.0.0.1:3111", "http://127.0.0.1:3113"]
+ allowed_origins: ["http://localhost:${III_REST_PORT:3111}", "http://localhost:${III_VIEWER_PORT:3113}", "http://127.0.0.1:${III_REST_PORT:3111}", "http://127.0.0.1:${III_VIEWER_PORT:3113}"]
allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]
+ - name: iii-worker-manager
+ config:
+ port: ${III_ENGINE_PORT:49134}
+ host: 0.0.0.0
- name: iii-state
config:
adapter:
name: kv
config:
store_method: file_based
+ save_interval_ms: ${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:2000}
file_path: /data/state_store.db
- name: iii-queue
config:
@@ -28,26 +33,21 @@ workers:
name: kv
- name: iii-stream
config:
- port: 3112
+ port: ${III_STREAM_PORT:3112}
host: 0.0.0.0
adapter:
name: kv
config:
store_method: file_based
+ save_interval_ms: ${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:2000}
file_path: /data/stream_store
- name: iii-observability
config:
enabled: true
service_name: agentmemory
exporter: memory
- # See iii-config.yaml for the rationale on 0.1 / console-off (#519).
+ # See iii-config.yaml for the rationale on 0.1 / console-off.
sampling_ratio: 0.1
metrics_enabled: true
logs_enabled: true
logs_console_output: false
- - name: iii-exec
- config:
- watch:
- - src/**/*.ts
- exec:
- - node dist/index.mjs
diff --git a/iii-config.yaml b/iii-config.yaml
index 62892f5143..642d046fff 100644
--- a/iii-config.yaml
+++ b/iii-config.yaml
@@ -13,6 +13,7 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: ./data/state_store.db
- name: iii-queue
config:
@@ -34,6 +35,7 @@ workers:
name: kv
config:
store_method: file_based
+ save_interval_ms: 2000
file_path: ./data/stream_store
- name: iii-observability
config:
@@ -45,7 +47,7 @@ workers:
# subscriber lagged" WARN, and that WARN re-enters the same
# stream the subscriber is failing to drain — a positive
# feedback loop that wrote 137 GB to daemon.log.new on one user
- # in a few days (#519).
+ # in a few days.
sampling_ratio: 0.1
metrics_enabled: true
logs_enabled: true
diff --git a/integrations/filesystem-watcher/watcher.mjs b/integrations/filesystem-watcher/watcher.mjs
index 27fb4f0227..b0d3783042 100644
--- a/integrations/filesystem-watcher/watcher.mjs
+++ b/integrations/filesystem-watcher/watcher.mjs
@@ -1,4 +1,5 @@
-import { watch, promises as fsp, statSync } from "node:fs";
+import { watch, promises as fsp, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
import { resolve, relative, join, extname, sep, basename } from "node:path";
import { randomBytes } from "node:crypto";
import { execFileSync } from "node:child_process";
@@ -134,11 +135,59 @@ function redactSensitivePreview(preview) {
return redactPemBlocks(preview).split("\n").map(redactSensitiveLine).join("\n");
}
+function usableSecret(value) {
+ const trimmed = typeof value === "string" ? value.trim() : "";
+ if (!trimmed || (trimmed.startsWith("${") && trimmed.endsWith("}"))) return "";
+ return trimmed;
+}
+
+function readAgentmemoryFile(name) {
+ try {
+ return readFileSync(join(homedir(), ".agentmemory", name), "utf-8");
+ } catch {
+ return "";
+ }
+}
+
+function envFileSecret() {
+ let found = "";
+ for (const line of readAgentmemoryFile(".env").split("\n")) {
+ const trimmed = line.trim();
+ if (trimmed.startsWith("#")) continue;
+ const eq = trimmed.indexOf("=");
+ if (eq === -1) continue;
+ if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== "AGENTMEMORY_SECRET") continue;
+ let value = trimmed.slice(eq + 1).trim();
+ const quote = value[0];
+ const close = quote === '"' || quote === "'" ? value.indexOf(quote, 1) : -1;
+ if (close > 0) value = value.slice(1, close);
+ else if (value.includes(" #")) value = value.slice(0, value.indexOf(" #"));
+ found = usableSecret(value);
+ }
+ return found;
+}
+
+function isLoopbackUrl(url) {
+ try {
+ const host = new URL(url).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+ return host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+ } catch {
+ return false;
+ }
+}
+
+export function resolveSecret(url, explicit) {
+ const configured = usableSecret(explicit);
+ if (configured) return configured;
+ if (!isLoopbackUrl(url)) return "";
+ return envFileSecret() || usableSecret(readAgentmemoryFile("secret"));
+}
+
export class FilesystemWatcher {
constructor(config = {}) {
this.roots = (config.roots || []).map((r) => resolve(r));
this.baseUrl = (config.baseUrl || "http://localhost:3111").replace(/\/+$/, "");
- this.secret = config.secret;
+ this.secret = resolveSecret(this.baseUrl, config.secret);
this.project =
config.project ||
(this.roots[0] ? deriveProjectName(this.roots[0]) : "filesystem-watcher");
diff --git a/integrations/hermes/__init__.py b/integrations/hermes/__init__.py
index 79ab21889f..878a6524e5 100644
--- a/integrations/hermes/__init__.py
+++ b/integrations/hermes/__init__.py
@@ -78,19 +78,6 @@ def shutdown(self, **kwargs: Any) -> None: pass
LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
_plaintext_bearer_warned = False
-# agentmemory's documented runtime config lives at ~/.agentmemory/.env.
-# When agentmemory is launched as a systemd user service (or any other
-# process manager that loads that file directly), those values never
-# reach an interactive shell. `hermes memory status` then reads
-# os.environ in the Hermes CLI process, finds AGENTMEMORY_URL /
-# AGENTMEMORY_SECRET unset, and reports the plugin as "Missing" even
-# though the service is healthy and live sessions can use it (#250).
-#
-# Preload the file at plugin-import time using os.environ.setdefault so
-# we never override anything the user explicitly set in the shell. The
-# preload is best-effort and silent on any failure (file absent,
-# unreadable, malformed) — the plugin falls back to its existing default
-# (http://localhost:3111) and Hermes status reflects that.
def _preload_agentmemory_dotenv() -> None:
candidates: list[Path] = []
home = os.environ.get("HOME")
@@ -114,10 +101,6 @@ def _preload_agentmemory_dotenv() -> None:
os.environ.setdefault(key, value)
except (OSError, UnicodeDecodeError):
continue
- # Guarantee AGENTMEMORY_URL is set so `hermes memory status` never
- # reports it as Missing when a user runs agentmemory at the default
- # localhost:3111 (or via systemd with the URL line commented out in
- # ~/.agentmemory/.env because it matches the default). #520.
os.environ.setdefault("AGENTMEMORY_URL", DEFAULT_BASE_URL)
@@ -174,12 +157,58 @@ def _reset_plaintext_bearer_guard_for_tests() -> None:
_plaintext_bearer_warned = False
+def _usable_secret(value: str | None) -> str:
+ trimmed = (value or "").strip()
+ if not trimmed or (trimmed.startswith("${") and trimmed.endswith("}")):
+ return ""
+ return trimmed
+
+
+def _read_agentmemory_file(name: str) -> str:
+ try:
+ return (Path.home() / ".agentmemory" / name).read_text(encoding="utf-8")
+ except (OSError, UnicodeDecodeError):
+ return ""
+
+
+def _env_file_secret() -> str:
+ found = ""
+ for raw in _read_agentmemory_file(".env").splitlines():
+ line = raw.strip()
+ if line.startswith("#") or "=" not in line:
+ continue
+ key, _, value = line.partition("=")
+ key = key.strip()
+ if key.startswith("export "):
+ key = key[len("export "):].strip()
+ if key != "AGENTMEMORY_SECRET":
+ continue
+ value = value.strip()
+ close = value.find(value[0], 1) if value[:1] in ("'", '"') else -1
+ if close > 0:
+ value = value[1:close]
+ elif " #" in value:
+ value = value[: value.index(" #")]
+ found = _usable_secret(value)
+ return found
+
+
+def _stored_secret(base: str) -> str:
+ try:
+ host = (urlparse(base).hostname or "").lower()
+ except ValueError:
+ return ""
+ if host not in ("localhost", "::1") and not host.startswith("127."):
+ return ""
+ return _env_file_secret() or _usable_secret(_read_agentmemory_file("secret"))
+
+
def _api(base: str, path: str, body: dict | None = None, method: str = "POST", secret: str = "") -> dict | None:
if not _validate_url(base):
return None
url = f"{base}/agentmemory/{path}"
headers = {"Content-Type": "application/json"}
- auth = secret or os.environ.get("AGENTMEMORY_SECRET", "")
+ auth = _usable_secret(secret) or _usable_secret(os.environ.get("AGENTMEMORY_SECRET")) or _stored_secret(base)
_check_plaintext_bearer_guard(base, auth)
if auth:
headers["Authorization"] = f"Bearer {auth}"
diff --git a/integrations/hermes/plugin.yaml b/integrations/hermes/plugin.yaml
index 4d647c8a81..03fe27ff9d 100644
--- a/integrations/hermes/plugin.yaml
+++ b/integrations/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: agentmemory
-version: 0.9.29
+version: 0.9.30-codex.1
description: "Persistent cross-session memory for Hermes Agent via agentmemory. 95.2% retrieval accuracy on LongMemEval."
author: "Rohit Ghumare"
homepage: "https://github.com/rohitg00/agentmemory"
diff --git a/integrations/openclaw/README.md b/integrations/openclaw/README.md
index 29c3a682eb..9f6891723e 100644
--- a/integrations/openclaw/README.md
+++ b/integrations/openclaw/README.md
@@ -13,7 +13,7 @@