Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

Upgrade to iii 0.25.0 with Worker Compose (#1592)

Guilherme de S. Vieira Beira36bdbe9d3ac3
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..93e2a804
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,17 @@
+.git
+.iii
+.src
+.run
+upgrade
+upgrade-cli
+upgrade-docker
+upgrade-lat
+node_modules
+**/node_modules
+**/target
+**/dist
+**/.cache
+**/coverage
+**/tmp
+*.log
+*.tsbuildinfo
diff --git a/.env.example b/.env.example
index 34dfc2ac..4699a9b9 100644
--- a/.env.example
+++ b/.env.example
@@ -5,9 +5,9 @@
# Copy this file to `~/.agentmemory/.env` (or to your project root if you
# prefer scoped config) and uncomment the lines you want to override.
#
-# Every line is OFF by default — `agentmemory` runs out of the box with no
-# LLM key, no embedding key, and no API auth. Set keys here only when you
-# want to enable the corresponding feature.
+# Optional providers and features are off by default — `agentmemory` runs
+# without an LLM or embedding key. Local API authentication uses a generated
+# secret unless you set AGENTMEMORY_SECRET explicitly.
#
# Run `npx -y @agentmemory/agentmemory@latest init` to copy this file into
# place automatically. Run `npx -y @agentmemory/agentmemory@latest doctor`
@@ -108,10 +108,10 @@
# -----------------------------------------------------------------------------
#
# Bearer-token auth for the REST API + viewer + all integration plugins.
-# Without a secret, REST endpoints are open on loopback. Set this when
-# you expose the daemon beyond loopback or run behind a reverse proxy.
+# The CLI generates a secret when unset and local clients retrieve it from
+# the data directory. Set this explicitly for remote clients/deployments.
-# AGENTMEMORY_SECRET=your-secret # generated into ~/.agentmemory/secret on first start when unset
+# AGENTMEMORY_SECRET=your-secret # generated into the selected data directory on first start when unset
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
@@ -122,7 +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
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false # Report boot compaction as off (otherwise deferred; manual maintenance only)
# 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.
@@ -155,7 +155,6 @@
# 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
@@ -170,32 +169,25 @@
# AGENTMEMORY_ENGINE_READY_TIMEOUT_MS=120000 # CLI engine readiness deadline (2 minutes)
# Startup deadlines accept whole milliseconds from 1 to 3600000. Shell
# environment overrides this file. Engine and worker waits have separate
-# budgets; Docker/orchestrator healthcheck grace must allow for both when
-# increasing them for a slow store.
-# AGENTMEMORY_ENGINE_MANAGES_WORKER=true # Custom engine config launches the worker through a wrapper
-# Direct AgentMemory worker commands are detected automatically. Set true
-# for custom launch wrappers so the CLI waits instead of starting a second
-# worker; set false when custom exec jobs are unrelated to AgentMemory.
+# budgets; increase them only for a slow store.
+# AGENTMEMORY_ENGINE_MANAGES_WORKER=true # Custom engine-managed worker wrapper; unset detects direct worker commands
# 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
+# Persistent iii state; same override as `--data-dir`. Instance 0 reuses
+# an existing ./data/state_store.db before platform 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_ENV_FILE=/absolute/path/to/.env # Config file override (default ~/.agentmemory/.env)
+# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Root directory for Obsidian vault exports
-# AGENTMEMORY_STATE_BACKEND=redis # file (default) | redis — storage adapter for iii-state and iii-stream, see README "Storage backend"
+# AGENTMEMORY_STATE_BACKEND=redis # file (default) | redis — backend used by the state worker, 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
-# Snapshot exporter — periodic snapshots of state_store + stream_store.
+# Snapshot exporter — periodic snapshots of state_store.
# SNAPSHOT_ENABLED=true
# SNAPSHOT_DIR=~/.agentmemory/snapshots
# SNAPSHOT_INTERVAL=3600 # Seconds between snapshots
@@ -210,24 +202,20 @@
# -----------------------------------------------------------------------------
# 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.
+# `--instance 1` selects REST/viewer/engine ports 3211/3213/49234 and an instance-1 data subdir.
# -----------------------------------------------------------------------------
# 8. iii engine pin
# -----------------------------------------------------------------------------
#
-# 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
+# agentmemory pins iii-engine and its iii-sdk dependencies to v0.25.0.
+# The CLI downloads the engine into ~/.agentmemory/bin on macOS/Linux.
+# Native Windows requires installing the matching iii.exe manually.
+# AGENTMEMORY_III_VERSION=0.25.0 # Override only when deliberately matching a different engine
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
diff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.yml
index f2b8c1c9..60311d1b 100644
--- a/.github/workflows/release-gate.yml
+++ b/.github/workflows/release-gate.yml
@@ -44,6 +44,14 @@ jobs:
node-version: 22
- run: npm install --legacy-peer-deps --no-audit --no-fund
- run: npm run release:gate -- --out "${{ runner.temp }}/release-gate"
+ - name: Verify live workers and plugins on Linux
+ if: runner.os == 'Linux'
+ shell: bash
+ run: |
+ engine_pin=$(node --import tsx --input-type=module -e 'import { III_PINNED_VERSION } from "./src/version.ts"; console.log(III_PINNED_VERSION)')
+ engine_bin="$HOME/.cache/agentmemory-release-gate/iii-${engine_pin}-linux-x64"
+ test -x "$engine_bin"
+ AGENTMEMORY_TEST_III="$engine_bin" AGENTMEMORY_REQUIRE_LIVE_TESTS=1 npx vitest run test/compose-supervision-integration.test.ts test/codex-live-daemon.test.ts
- run: npm run test:startup:packaged -- --skip-build --out "${{ runner.temp }}/startup-gate"
- name: Test packaged vector recovery
shell: bash
diff --git a/AGENTS.md b/AGENTS.md
index 628dbcd0..21b81dec 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,8 +4,8 @@
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 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`)
+- **Engine**: iii-sdk 0.25.0 with @iii-dev/helpers 0.25.0 (Worker Compose-managed iii-engine 0.25.0 on port 49134; the client type is `IIIClient`, HTTP requests are `HttpRequest` from `@iii-dev/helpers/http`)
+- **State**: iii state worker with a file-backed KV store by default (`./data/state_store.db`); Docker pins `save_interval_ms` to 2000 ms
- **Build**: TypeScript → ESM via tsdown, output to `dist/`
- **Test**: vitest (`npm test` excludes integration tests)
@@ -86,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). `stop` awaits its reply capture (bounded by `OBSERVE_TIMEOUT_MS`, capped at that timeout plus 1500ms) before posting `/session/end`, so the reply is stored before finalization is requested, and then gives `/session/end` the usual 1500ms; a Stop without a reply exits as it did before. An acknowledged capture does not mean the session summary already reflects the reply — compression for the turn can still be pending when finalization runs. 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.
+- **Telemetry-only hooks** (`notification`, `post-tool-failure`, `post-tool-use`, `prompt-submit`, `stop`, `session-end`, `subagent-start`, `subagent-stop`, `task-completed`) write nothing to stdout. These MUST use fire-and-forget `fetch(..., { signal: AbortSignal.timeout(N) }).catch(() => {})` paired with `setTimeout(() => process.exit(0), 500).unref()`. The unawaited fetch dispatches the request; the unref'd `setTimeout` force-exits the process after the request has been flushed to the local daemon's socket buffer (~500ms is enough for single-request hooks; use 1500ms for multi-request hooks like `stop` and `session-end` so all fetches have time to start, especially when `AGENTMEMORY_URL` points to a remote daemon). Without the `setTimeout` Node keeps the event loop alive waiting for any in-flight fetch to settle, which means the hook still blocks Claude Code's next-prompt boundary for up to the AbortSignal duration — exactly the bug fire-and-forget is meant to fix.
## Coding Standards
@@ -109,9 +109,9 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
## Current Stats (v0.9.30)
-- 54 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
-- 143 REST endpoints
+- 54 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials
+- 146 REST endpoints
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 17 skills
-- 324+ iii functions
+- 322+ iii functions
- 4,000+ tests
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d9a398cc..02c4a2e3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -107,7 +107,7 @@ 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-<version>.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.
-For startup changes, also run `npm run test:startup:packaged`. It installs the packed CLI in isolated homes and tests delayed workers, existing-engine adoption, `--no-engine`, doctor, demo, timeout failures and process cleanup. The default slow-worker case waits 48 seconds before importing the installed worker. Pass `--tarball <file.tgz>` to test an existing artifact. Run the standard release gate first to cache the pinned engine, or set `AGENTMEMORY_GATE_ENGINE` to that engine binary. Docker scenarios require a working Docker daemon; the report records unavailable Docker coverage explicitly.
+For startup changes, also run `npm run test:startup:packaged`. It installs the packed CLI in isolated homes and tests delayed and externally managed Worker Compose runtimes, `--no-engine` joining, worker and readiness failures, timeout cleanup, environment-file precedence, doctor, observability storage, and demo. It does not test adoption of an arbitrary already-running engine or Docker-specific CLI startup scenarios. The default slow-worker case waits 48 seconds before importing the installed worker. Pass `--tarball <file.tgz>` to test an existing artifact. Run the standard release gate first to cache the pinned engine, or set `AGENTMEMORY_GATE_ENGINE` to that engine binary.
For Hermes, OpenClaw or shared skill changes, follow [Native integration tests](docs/native-integration-tests.md). Those gates load plugins and skills from an installed tarball and inspect the native model requests and backend records. Source tests alone do not establish native lifecycle capture or skill discovery.
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index e0599b52..49d6e111 100644
--- a/INSTALL_FOR_AGENTS.md
+++ b/INSTALL_FOR_AGENTS.md
@@ -4,9 +4,9 @@ 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 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.
+agentmemory is a local memory server for coding agents. Its CLI starts an iii Worker Compose runtime using the pinned iii 0.25.0 engine and registry workers `[email protected]` and `[email protected]`. The default listeners are REST/MCP HTTP on port 3111, the viewer on 3113, and the internal engine WebSocket on 49134. The viewer receives live updates as SSE through `GET /agentmemory/viewer/events` on the REST port.
-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 <path>` 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.
+The CLI downloads the pinned engine into `~/.agentmemory/bin` on macOS/Linux. Native Windows needs a manually installed pinned `iii.exe`; WSL2 follows the Linux path. Persistent state defaults to `~/Library/Application Support/agentmemory` on macOS, `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` on Linux, and `%APPDATA%\agentmemory` on Windows. Override the directory with `--data-dir <path>` or `AGENTMEMORY_DATA_DIR`, and reuse the same override on every restart. `AGENTMEMORY_ENV_FILE` selects a non-default env file. Instance 0 reuses an existing `./data/state_store.db` when present. `--instance N` creates an isolated directory and port set for another runtime.
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`.
@@ -14,8 +14,8 @@ Default keyless mode needs no API key or cloud account and disables vector embed
- 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).
+- Windows: WSL2 follows the Linux path. Native Windows requires the pinned iii-engine v0.25.0 binary installed manually. Native automated `connect` supports only `copilot-cli`; configure other Windows agents manually. WSL `connect` applies only to agents installed in that same WSL environment.
+- Default ports 3111 (REST), 3113 (viewer), and 49134 (engine) must be free. Viewer events are carried over REST.
## Running non-interactively
@@ -37,13 +37,13 @@ Expect: Node prints v20 or newer, npm succeeds, and macOS/Linux prints a path fo
For native Windows, install the engine before continuing:
```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
+# Download the matching archive from the pinned release:
+# https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0
+# Extract iii.exe to a directory on PATH, such as $HOME\.local\bin, then verify:
+iii.exe --version
```
-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.
+Expect: exactly `0.25.0`. Verify the archive against its matching SHA-256 asset before extracting it. Do not install an unpinned iii release.
## 2. Start the server
@@ -53,24 +53,23 @@ The canonical command downloads the npm package and, on macOS/Linux, auto-instal
npx -y @agentmemory/agentmemory@latest
```
-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:
+To choose persistent storage, pass an absolute path and reuse it on every start:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir /absolute/path/to/agentmemory-data
```
-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.
+For a second isolated runtime, add `--instance 1`; it stores data under `instance-1` and defaults to ports 3211 (REST), 3213 (viewer), and 49234 (engine). `--instance N` supports N from 0 to 50. Do not use `--port` alone for concurrent daemons: it changes ports but preserves 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.
+Expect: iii 0.25.0 starts, the agentmemory worker registers with iii, and the ready panel lists REST, viewer, and engine addresses. First boot can take longer while the engine binary and registry workers are installed.
-## 3. Validate the server and all four ports
+## 3. Validate the server and runtime 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 |
+| 3111 | registry `http` worker | `/agentmemory/livez` returns 200; viewer SSE is at `/agentmemory/viewer/events` |
| 3113 | agentmemory viewer | opening the URL returns the viewer |
-| 49134 | iii engine WebSocket | listed in the ready panel and worker registration succeeds |
+| 49134 | iii engine | internal worker WebSocket; worker registration succeeds |
From a second terminal, run:
@@ -81,7 +80,7 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-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`.
+Expect: the REST liveness check returns JSON, the viewer request succeeds, the startup ready panel lists the three endpoints, and `status` reports healthy agentmemory state. `/agentmemory/status` reports the pinned engine version as `enginePinnedVersion`. 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. Exercise default recall and optional local semantics
@@ -107,7 +106,7 @@ Detect which agent is running this runbook, then wire its MCP config. On native
npx -y @agentmemory/agentmemory@latest connect <agent>
```
-`connect` merges agentmemory into that agent's MCP config and preserves any existing servers. Supported agent names:
+Supported agent names:
`claude-code`, `copilot-cli`, `codex`, `cursor`, `gemini-cli`, `opencode`, `cline`, `continue`, `droid`, `hermes`, `openclaw`, `openhuman`, `pi`, `omp`, `qwen`, `warp`, `zed`, `antigravity`, `kiro`.
@@ -133,38 +132,46 @@ Expect: the skills are installed for the detected agent.
## 7. Verify save, recall, and restart persistence
-Confirm health first:
+Confirm the server is alive first:
```bash
-curl -fsS http://localhost:3111/agentmemory/health
+curl -fsS http://localhost:3111/agentmemory/livez
```
Expect: a JSON body with an ok status.
Now write a memory and read it back. If MCP is wired, call the `memory_save` tool followed by `memory_smart_search`. Otherwise use REST directly (note: these are the REST paths, which differ from the MCP tool names):
+REST writes always require the bearer secret. If you configured `AGENTMEMORY_SECRET` in the daemon environment or env file, set that same value in this terminal. For the default generated local secret, load it without printing it:
+
+```bash
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+```
+
```bash
-curl -X POST http://localhost:3111/agentmemory/remember \
+curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H "Content-Type: application/json" \
-d '{"content":"agentmemory install verification probe","concepts":["install-check"]}'
-curl -X POST http://localhost:3111/agentmemory/smart-search \
+curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H "Content-Type: application/json" \
-d '{"query":"install verification probe","limit":5}'
```
Expect: the first call returns `201`, the second returns `200` with results that include the probe memory you just saved.
-If `AGENTMEMORY_SECRET` is set in the environment, the REST API requires it. Add `-H "Authorization: Bearer $AGENTMEMORY_SECRET"` to both calls. By default no secret is set and localhost is open.
+The generated local secret is stored at `~/.agentmemory/secret` and mirrored to `<data dir>/secret`. The CLI, viewer, and MCP shim read it automatically. Keep using the same secret after restarting.
-Now stop and restart the processes, using the same `--data-dir` value if you set one:
+Now stop and restart the processes. If you selected a custom `--data-dir`, add that same option and value to both commands:
```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.
+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 data directory is persistent rather than only proving the in-memory index.
## Optional: install a global command
@@ -191,9 +198,9 @@ The MCP server exposes 54 tools by default (`--tools all`). Use `--tools core` (
## Lifecycle commands
-- `npx -y @agentmemory/agentmemory@latest status` shows server health, viewer, provider, and embedding state.
+- `npx -y @agentmemory/agentmemory@latest status` shows server health, viewer, provider, embedding state, and pinned engine version.
- `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 stop` stops the engine this CLI started. If an older install was started with Docker, the CLI prints a command for stopping that existing container; it never starts or manages Docker containers.
- `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 <file>` imports prior Claude Code session logs as memories.
@@ -201,16 +208,15 @@ The MCP server exposes 54 tools by default (`--tools all`). Use `--tools core` (
## Troubleshooting
- `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.
+- Automatic iii install fails on macOS/Linux: verify `command -v curl sh tar`; install the missing prerequisite, then retry.
- 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.
-- Custom REST port: `--port <N>` 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`).
+- Port already in use: another process holds 3111 (REST), 3113 (viewer), or 49134 (engine). Stop that process, then re-run.
+- Custom REST port: `--port <N>` derives the viewer port as `N+2` and the iii worker WebSocket as `N+46023` unless `III_VIEWER_PORT`, `III_ENGINE_PORT`, or `III_ENGINE_URL` explicitly overrides the corresponding value. `--instance N` selects an isolated runtime and data directory.
- 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, 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`.
+- `The engine process started but the REST API never responded.`: inspect the REST, viewer, and engine ports, confirm the pinned iii process stayed alive, and use `--verbose` for captured engine stderr.
+- Engine version conflict / another iii engine already running: if an unmanaged engine is already listening on the engine port, agentmemory will not adopt it. Stop that engine or choose another `--instance` or `--port`. The CLI keeps its private pinned binary separate from 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.
+- Native Windows: install the pinned v0.25.0 `iii.exe` manually or use WSL2. 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
@@ -218,7 +224,7 @@ The MCP server exposes 54 tools by default (`--tools all`). Use `--tools core` (
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
+- iii-engine v0.25.0 running, the selected platform data directory, REST/viewer/engine ports, and the status `enginePinnedVersion`
- 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 after a full stop/start
- the viewer is available at `http://localhost:3113`
diff --git a/README.md b/README.md
index 6a880f69..1417ee85 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Your coding agent remembers everything. No more re-explaining.
- Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Persistent memory across coding sessions and agents.
</strong><br/>
- Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, OpenCode, and any MCP client.
+ Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, OpenCode, DeepSeek Harness, and any MCP client.
</p>
<p align="center">
@@ -59,11 +58,11 @@
</p>
<p align="center">
- <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory" alt="skills.sh" height="28" /></a>
<a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm&style=for-the-badge&logo=npm" alt="npm version" /></a>
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -88,32 +87,38 @@
<a href="#how-it-works">How It Works</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Config</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory captures coding sessions, makes decisions and fixes searchable, and lets your agents recall them later. Keep one memory store across tools, inspect what was saved, and choose how much context reaches the model.
+
+- **Capture:** native hooks and plugins record supported session events, with secret scrubbing and offline replay.
+- **Recall:** keyword search works without an API key; local or remote embeddings add semantic search.
+- **Continue:** retrieve project history, lessons and session handoffs from another agent.
+- **Inspect:** browse, edit, export and forget memories in the live viewer.
+
## Install
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.
+- macOS/Linux also need `curl`, a POSIX `sh`, and `tar` for automatic runtime setup.
+- Windows users can use WSL2 or follow the [native Windows setup](#windows).
-Canonical fresh-install command:
+Start setup:
```bash
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 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.
+Choose your agents and either a provider or keyless mode. Setup writes the configuration, starts the memory server, and offers a global install for the `agentmemory` command. `-y` accepts the npm package prompt; `@latest` selects the current release. LLM-written observation compression is opt-in with a provider and `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+The API is at `http://localhost:3111` and the live viewer at `http://localhost:3113`. Both bind to loopback by default. Configuration lives in `~/.agentmemory/.env`; see [data storage](#data-storage) for memory locations and separate instances.
Then prove recall works and give your agent its skills:
@@ -128,14 +133,7 @@ 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
-Wire more agents any time with `agentmemory connect <agent>` — 20 adapters listed at [Works with every agent](#works-with-every-agent). Full command reference at [Quick Start](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Connect another agent with `agentmemory connect <agent>`. See [supported integrations](#works-with-every-agent) and [everyday commands](#everyday-commands).
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -155,13 +153,6 @@ npx caches per version. Force the latest with `npx -y @agentmemory/agentmemory@l
</details>
-<details>
-<summary><strong>Already running your own iii engine</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-agents.svg"><img src="assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -188,7 +179,7 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>native plugin + lifecycle hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -215,7 +206,7 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
<td align="center" width="20%">
<a href="integrations/pi/"><img src="assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>native recall + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -281,7 +272,7 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>native capture + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -304,6 +295,12 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>native recall + capture + skills + optional MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -312,22 +309,24 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
---
-You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.
+### Data storage
-**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.
+Memories stay outside your repository by default:
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+| Platform | Data directory |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` or `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
-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 <path>` or set `AGENTMEMORY_DATA_DIR`; either explicit setting takes precedence over legacy discovery:
+An existing `./data/state_store.db` is reused for instance 0. Choose another directory with `--data-dir <path>` or `AGENTMEMORY_DATA_DIR`. Keep the same directory when restarting or upgrading.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` uses an `instance-1` subdirectory, API port `3211` and viewer port `3213`. See [storage and backups](docs/reliability/state-storage.md) for Redis and backend migration.
Latest release notes: [CHANGELOG.md](CHANGELOG.md).
@@ -477,7 +476,7 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md).
</tr>
<tr>
<td><strong>External deps</strong></td>
-<td>None (SQLite + iii-engine)</td>
+<td>No separate database service required</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>Multiple</td>
@@ -551,14 +550,12 @@ Latest release notes: [CHANGELOG.md](CHANGELOG.md).
| Zep / Graphiti | 30K | Temporal knowledge graph; strongest published temporal-query results (LongMemEval 63.8%), but graph builds asynchronously so fresh facts can lag |
| Cognee | 30K | Document-to-knowledge-graph ingestion, Python-only, built for structured entity extraction rather than session capture |
-None of these auto-capture from coding-agent hooks, ship a local-first viewer, or run keyless — the combination agentmemory is built around.
+AgentMemory combines coding-agent capture, searchable project history and a local viewer, with keyless operation available from the first run.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-quickstart.svg"><img src="assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-Compatibility: this release targets `iii-sdk` 0.22.1 and pins iii-engine v0.22.1.
-
### Try it in 30 seconds
```bash
@@ -575,7 +572,7 @@ 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:
+With the server running, check health, the viewer and status:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -584,14 +581,20 @@ 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:
+`status` reports server health, provider and embedding mode, capture delivery, and recovery state. Save a probe and confirm it is searchable. Protected REST requests require the daemon secret. If you configured `AGENTMEMORY_SECRET`, use that value in this terminal; otherwise load the generated local secret:
+
+```bash
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+```
```bash
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
@@ -605,7 +608,10 @@ Install and setup live in [Install](#install) above (the first run walks you thr
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -624,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-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.
+Imported sessions appear alongside native sessions in Replay. Transcripts are indexed for search and marked with origin channel `import`; session processing can also produce crystals and lessons.
> **Heads-up if you rely on `import-jsonl` as your primary capture path:** Claude Code's `cleanupPeriodDays` (in `~/.claude/settings.json`, default **30**) auto-deletes JSONL transcripts older than that window from `~/.claude/projects/`. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run `import-jsonl` on a cron, raise `cleanupPeriodDays` to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering.
@@ -636,14 +642,12 @@ Use the maintenance command when you intentionally want to update your local run
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.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).
+This updates the local runtime and may update JavaScript dependencies in the current workspace. Back up your data and read the [upgrade guide](docs/upgrades/iii-0.25.md) before updating an existing installation.
### Claude Code (one block, paste it)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code without the plugin install (MCP-standalone path)
@@ -713,39 +717,69 @@ agentmemory connect cursor
Then add the native hooks: **Settings → Plugins → Add marketplace** → select an agentmemory checkout (the directory containing `.cursor-plugin/plugin.json`), enable the **agentmemory** plugin, and reload the window.
-Cursor runs the same lifecycle hooks as every other host — they are the canonical `plugin/scripts/*.mjs`, not a separate implementation. A thin adapter in front of them resolves which project a session belongs to, which Cursor does not reliably report: its payload `cwd` can be `.cursor`, the Cursor install directory, or missing entirely. Do not also wire hooks into `~/.cursor/hooks.json` — the plugin already dispatches them, and both copies firing records every observation twice.
+The plugin provides lifecycle capture, workspace-aware project attribution, skills and MCP. Enable either the plugin hooks or manual hooks in `~/.cursor/hooks.json` to avoid duplicate capture.
Full guide: [`integrations/cursor/`](integrations/cursor/)
-### OpenClaw
-
-Start the installed AgentMemory server in a separate terminal, then install its native plugin and skills:
+### Pi, Oh My Pi and DeepSeek Harness
```bash
-agentmemory
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
```
-```bash
-agentmemory connect openclaw
+Choose the command for your host. Pi and OMP install native recall/capture, offline replay and 17 skills; `--with-mcp` adds the full toolset. Run `/reload` in Pi or restart OMP, then check `/agentmemory-status`. DSH installs MCP and the bundled capture plugin; restart DSH after connecting.
+
+Pi also supports an installable `@agentmemory/pi` package. See the [Pi package guide](integrations/pi/) for local installation and npm availability. Use one installation method per host.
+
+Guides: [Pi](integrations/pi/), [Oh My Pi](integrations/omp/), [DSH](docs/dsh.md).
+
+<details>
+<summary><b>OpenClaw (paste this prompt)</b></summary>
+
+```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`.
```
-The connector uses the active OpenClaw state directory, installs the packaged plugin and its skills, and enables its memory slot and conversation access. Existing custom settings are preserved; replacing a different memory plugin requires `--force` and creates a backup. Restart OpenClaw and verify capture followed by recall in a fresh session. Native memories are scoped by the OpenClaw profile and agent identity.
+Full guide: [`integrations/openclaw/`](integrations/openclaw/)
-For the wider memory tool surface, opt in with `agentmemory connect openclaw --with-mcp`. OpenClaw uses `mcp.servers`, not the legacy `mcpServers` key. The MCP tools access the configured backend without the native plugin's automatic profile filters, so use them only for a trusted, deliberately shared backend. See [OpenClaw setup, credentials, and verification](integrations/openclaw/).
+</details>
-### Hermes Agent
+<details>
+<summary><b>Hermes Agent (paste this prompt)</b></summary>
-With the installed AgentMemory server running, install its provider and bundled skills, then configure credentials through 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:
-```bash
-agentmemory connect hermes
-hermes memory setup
-hermes memory status
+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.
```
-Use the same `HERMES_HOME` for setup and subsequent Hermes sessions. The connector installs files before enabling `memory.provider: agentmemory` and preserves unrelated YAML settings. In Hermes setup, select AgentMemory and enter the backend URL and bearer credential. The provider reads credentials through Hermes's scoped API; it does not read the local AgentMemory secret file.
+Full guide: [`integrations/hermes/`](integrations/hermes/)
-Native save, recall, and automatic capture default to the active profile and gateway author. Verify a save in one session and recall in a fresh session under the same profile. `agentmemory connect hermes --with-mcp` optionally adds the wider tools under `mcp_servers`; those tools access the configured backend without automatic native profile filters. See [Hermes setup, scope, and verification](integrations/hermes/).
+</details>
### Other agents
@@ -770,7 +804,7 @@ For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop
#### Standard MCP block
-The agentmemory entry is the **same MCP server block** across every host that uses the `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
+The agentmemory entry is the **same MCP server block** across every host that uses the `mcpServers` shape (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):
```json
"agentmemory": {
@@ -791,13 +825,13 @@ The agentmemory entry is the **same MCP server block** across every host that us
| **Cursor (full plugin)** | `.cursor-plugin/` | Cursor Marketplace listing or Settings → Plugins → local checkout. Registers lifecycle hooks via a thin adapter that delegates to the canonical `plugin/scripts/*.mjs`, plus skills and MCP. The adapter resolves the workspace Cursor does not reliably report. See [Cursor](#cursor). Works in the Cursor IDE and `cursor-agent` CLI. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge into `mcpServers`. Restart Claude Desktop after editing. |
| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Same `mcpServers` block. |
-| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` merges the MCP entry; `--with-hooks` adds six native auto-capture hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) with Devin'"'"'s lowercase tool matchers. Verify with `devin mcp list` and `/hooks` inside devin. |
-| **Devin CLI + Desktop (full plugin)** | `plugin/.devin-plugin/` | `devin plugins install rohitg00/agentmemory#plugin` registers all 17 skills as `/agentmemory:<skill>` slash commands, the MCP server, and six auto-capture hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) from `plugin/hooks.json`. Verify with `devin plugins info agentmemory` and `/hooks`. Local sessions only: cloud Devin sessions cannot reach a local agentmemory server. |
+| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` merges the MCP entry; `--with-hooks` adds six native auto-capture hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) with Devin's lowercase tool matchers. Verify with `devin mcp list` and `/hooks` inside devin. |
+| **Devin CLI (full plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` from a checkout registers all 17 skills as `/agentmemory:<skill>` slash commands plus the MCP server. Devin plugin hooks cannot fire `SessionStart`/`SessionEnd`, so pair it with `connect devin --with-hooks` for full session capture. |
| **Devin (cloud)** | Settings → Connections → MCP servers | Add a custom MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` pointing at a network-reachable agentmemory deployment plus `AGENTMEMORY_SECRET` (cloud sessions cannot reach localhost — see [`deploy/`](deploy/)). Store the secret in Devin Secrets, then use "Test listing tools" to verify all 54 tools appear. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges). |
| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` merges `mcpServers.agentmemory`; Copilot picks it up on next launch or `/mcp`. |
| **GitHub Copilot CLI (full plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` for the plugin from the GitHub subdir. |
-| **OpenClaw** | Active OpenClaw state directory | `agentmemory connect openclaw` installs native recall/capture and bundled skills. Add `--with-mcp` for the wider tool surface using `mcp.servers`. See [setup and scope](integrations/openclaw/). |
+| **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 + 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}}}`. |
@@ -811,39 +845,21 @@ The agentmemory entry is the **same MCP server block** across every host that us
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` writes the user-level config. Workspace overrides go in `.kiro/settings/mcp.json` next to your code. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` writes the standard `mcpServers` block. Warp also auto-discovers skills from `.claude/skills/`; once the Claude Code plugin is installed the 8 agentmemory skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) appear natively in Warp's slash-command palette. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` writes the standard `mcpServers` block. VS Code extension users: paste the same block via Cline Settings → MCP Servers → Edit JSON. |
-| **Continue.dev** | `~/.continue/config.yaml` (preferred) or `config.json` (legacy) | `agentmemory connect continue` creates `config.yaml` from scratch when neither exists, or modifies existing `config.json`. **If you already have `config.yaml`** the adapter prints the exact block to paste under `mcpServers:`; it won't silently rewrite your yaml because preserving comments and anchors safely needs a YAML parser the package doesn't ship. Continue uses array form (not object) for `mcpServers`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferred) or `config.json` (legacy) | `agentmemory connect continue` creates `config.yaml` from scratch when neither exists, or modifies existing `config.json`. **If you already have `config.yaml`** the adapter prints the exact block to paste under `mcpServers:`; it won't silently rewrite your yaml so your existing comments and anchors are preserved. Continue uses array form (not object) for `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` writes under `context_servers` (Zed's key, NOT `mcpServers`). Remote MCP servers can be wired via `{"url": "..."}` instead. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` writes the standard `mcpServers` block. Project-scoped overrides go in `<repo>/.factory/mcp.json`. Pass `--with-hooks` for native auto-capture. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` enables MCP tools. Add `--with-hooks` to load the native capture plugin bundled with AgentMemory. No separate plugin package is needed. [DSH](docs/dsh.md). |
| **Goose** | Goose MCP settings UI | Same `mcpServers` block; use `goose configure` → Add Extension → MCP. Direct YAML edit at `~/.config/goose/config.yaml` is supported but the schema uses `extensions:` + `cmd` (not `mcpServers:` + `command`). |
-| **Aider** | n/a | Talk to the REST API directly: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Aider** | n/a | Use the [authenticated REST examples](#validate-a-fresh-install-and-restart-persistence) to save and search memory from scripts. |
| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` auto-detects the host and merges. |
**Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP).
-### Programmatic access (Python / Rust / Node)
-
-agentmemory registers its core operations as iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any language with an iii SDK can call them directly over `ws://localhost:49134`, with no separate REST client per language.
-
-```bash
-pip install iii-sdk # Python
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
+### Programmatic access
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
+Use the [REST API](#api) from any language or the [MCP tools](#mcp-server) from an agent. REST requests use JSON and bearer authentication; see the [save and search example](#validate-a-fresh-install-and-restart-persistence).
-Worked example: [`examples/python/`](examples/python/) (quickstart + observation/recall flow). REST on `:3111` remains available for hosts without an iii runtime.
+For direct runtime integration, see the [Python examples](examples/python/).
### From source
@@ -852,91 +868,33 @@ 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 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.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=<version>` if you run your own engine and know it matches.
-
-- **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.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.22.1`). Full docs: [iii.dev/docs](https://iii.dev/docs).
+`npm start` launches the same local server as the installed CLI. Dependencies for automatic setup are listed under [Install](#install); the API and viewer bind to `127.0.0.1`.
### Windows
-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.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
-```
+agentmemory runs on Windows 10/11. WSL2 follows the Linux path and can install the pinned engine automatically. Native Windows requires the pinned iii-engine v0.25.0 binary installed manually; download the matching archive from the [iii v0.25.0 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verify its checksum, and place `iii.exe` on `PATH` (for example `%USERPROFILE%\.local\bin\iii.exe`). The CLI does not extract the Windows ZIP automatically.
-**Option 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
-```
+Native Windows automated MCP wiring supports only `agentmemory connect copilot-cli`. For other native Windows agents, use the manual MCP block from [Other agents](#other-agents). Run `connect` inside WSL only when the target agent is installed in that same WSL environment.
-**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:
+**Standalone MCP only (no engine).** If you only need MCP tools and do not need the REST API, viewer, or runtime services:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**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 |
-|---|---|
-| `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 <N>` |
-| 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 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`.
+**Diagnostics:** Run `agentmemory doctor` or restart with `--verbose`. Use `--port <N>` or `--instance <N>` if the default ports are occupied. See the [upgrade guide](docs/upgrades/iii-0.25.md) for runtime compatibility and recovery.
---
<h2 id="deploy">Deploy</h2>
-One-click templates for managed hosts. Each one ships a self-contained
-Dockerfile that pulls `@agentmemory/agentmemory` from npm and copies
-the iii engine binary in from the official `iiidev/iii` Docker Hub
-image; no pre-built agentmemory image required. Persistent storage
-mounts at `/data`; the first-boot entrypoint overwrites the
-npm-bundled iii config (which binds `127.0.0.1`) with a deploy-tuned
-one that binds `0.0.0.0` and uses absolute `/data` paths, generates
-the HMAC secret, then drops privileges from `root` to `node` via
-`gosu` before exec'ing the agentmemory CLI.
+Self-host with Docker Compose or the platform templates below. Persistent memory and credentials live on the `/data` volume. Back up and reuse that volume when upgrading. See the [deployment guide](deploy/README.md) for authentication, network access, backups and migration.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Render's one-click deploy button requires `render.yaml` at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in [`deploy/render/`](./deploy/render/README.md) to point at the in-repo blueprint manually.
@@ -954,28 +912,26 @@ cost floors) live in [`deploy/`](./deploy/README.md):
own VPS via [Coolify](https://coolify.io/self-hosted); same Docker
Compose stack, you own the host and the data.
-Only port `3111` is published. The viewer on `3113` stays bound to
-loopback inside the container; every template's README documents the
-SSH-tunnel pattern for reaching it.
+REST uses port `3111`; the viewer uses `3113`. Keep both private or protect them with authentication and TLS. Platform-specific exposure settings and [legacy Docker migration](deploy/README.md#migrating-from-the-legacy-cli-docker-mode) are covered in the deployment guide.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-why.svg"><img src="assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-Every coding agent forgets everything when the session ends, and each new session starts with you re-explaining your stack. agentmemory runs in the background and removes that step.
+Project knowledge gets scattered across chats and instruction files. AgentMemory makes past decisions, fixes and lessons searchable from the agent you are using now.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs built-in agent memory
@@ -984,7 +940,7 @@ Every AI coding agent ships with built-in memory: Claude Code has `MEMORY.md`, C
| | Built-in (CLAUDE.md) | agentmemory |
|---|---|---|
-| Scale | 200-line cap | Unlimited |
+| Upkeep | Manually curated instructions | Indexed session history and memories |
| Search | Loads everything into context | BM25 + vector + graph (top-K only) |
| Token cost | 22K+ at 240 observations | ~1,900 tokens (92% less) |
| Cross-agent | Per-agent files | MCP + REST (any agent) |
@@ -1010,13 +966,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-Tier Memory Consolidation
@@ -1034,6 +990,8 @@ Memories decay over time (Ebbinghaus curve). Frequently accessed memories streng
### What Gets Captured
+The table below describes the Claude Code hook surface. Other integrations capture the events their host provides; see the individual setup guides. Automatic context injection through the shared hooks is opt-in with `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Captures |
|------|----------|
| `SessionStart` | Project path, session ID |
@@ -1050,7 +1008,7 @@ Memories decay over time (Ebbinghaus curve). Frequently accessed memories streng
| Capability | Description |
|---|---|
-| **Automatic capture** | Every tool use recorded via hooks, no manual effort |
+| **Automatic capture** | Supported session and tool events recorded by native integrations |
| **Semantic search** | BM25 + vector + knowledge graph with RRF fusion |
| **Memory evolution** | Versioning, supersession, relationship graphs |
| **Recall hygiene** | Superseded memory versions leave the search indexes; the version chain in KV keeps full history |
@@ -1115,7 +1073,7 @@ The normal npm install includes the optional `@huggingface/transformers` runtime
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 -y @agentmemory/agentmemory@latest` (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 connect to a self-hosted server) and set `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
@@ -1255,7 +1213,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
-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.
+Auto-starts on port `3113`. The viewer loads one snapshot when it connects (`GET /agentmemory/viewer/snapshot`) and then applies live events over SSE at `/agentmemory/viewer/events` on the REST worker: 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/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1268,188 +1226,7 @@ Auto-starts on port `3113`. The viewer loads one snapshot when it connects (`GET
open http://localhost:3113
```
-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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-viewer.svg"><img src="assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-The viewer at `:3113` shows what your agent **remembered**. The [iii console](https://iii.dev/docs/console) shows what your agent **did**: every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped.
-
-Watch a `memory_smart_search` fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a `PostToolUse` hook with a tweaked payload. Pin the WebSocket stream and watch observations land live.
-
-agentmemory ships this for free because every function call and trigger fires through iii; nothing custom, nothing to instrument.
-
-<p align="center">
- <img src="assets/iii-console/workers.png" alt="iii console Workers page: connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
- <br/>
- <em>Workers page: every connected worker, including agentmemory itself, with PID, function count, runtime, and last-seen.</em>
-</p>
-
-**Already installed.** The console ships with 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 console
-```
-
-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.
-
-The same thing by hand, useful when `agentmemory` is not on PATH:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**What you can do from the console:**
-
-| Page | Use it to |
-|------|-----------|
-| **Workers** | See every connected worker and its live metrics, including the agentmemory worker itself. |
-| **Functions** | Invoke any of agentmemory's functions directly with a JSON payload; handy for testing `memory.recall`, `memory.consolidate`, `graph.query` without wiring a client. |
-| **Triggers** | Replay HTTP, cron, event, and state triggers: fire the consolidation cron manually, retry an HTTP route, emit a state change. |
-| **States** | KV browser with full CRUD over sessions, memory slots, lifecycle timers, and the embeddings index; edit values in place. |
-| **Streams** | Live WebSocket monitor for memory writes, hook events, and observation updates as they flow through iii streams. |
-| **Queues** | Durable queue topics + dead-letter management. Replay or drop failed embedding / compression jobs. |
-| **Traces** | OpenTelemetry waterfall / flame / service-breakdown views. Filter by `trace_id` to see exactly which functions, DB calls, and embedding requests a single `memory.search` produced. |
-| **Logs** | Structured OTEL logs filtered and correlated to trace/span IDs. |
-| **Config** | Runtime configuration: see exactly which workers, providers, and ports your engine is running with. |
-| **Flow** | (Optional, `--enable-flow`) Interactive architecture graph of every worker, trigger, and stream. |
-
-<p align="center">
- <img src="assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service breakdown for every memory operation.</em>
-</p>
-
-**Traces are already on:**
-
-`iii-config.yaml` ships with the `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 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.
-
-> **Heads-up:** no auth is enforced on the console itself; keep it bound to `127.0.0.1` (the default) and never expose it publicly.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-architecture.svg"><img src="assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory is **already a running [iii](https://iii.dev) instance**. Three primitives (worker, function, trigger) compose the runtime; KV state, streams, and OTEL traces come from iii-state, iii-stream, and iii-observability workers that ship with iii. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them.
-
-That means one more command extends agentmemory with an entire new capability.
-
-### Extend agentmemory with more workers
-
-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.
-
-```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 | What you get on top of agentmemory |
-|---|---|
-| [`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 |
-| [`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:<scope>`, `stream:<name>:<group>`) 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, `?collectionLimit=` and `?collectionOffset=` to page memories, the graph and the other collections, and `?collections=` to return only the named ones; `strategy` on import is `merge` (default-safe), `replace`, or `skip`, and `replace` refuses a paged or selected export.
-
-### What iii replaces
-
-| Traditional stack | agentmemory uses |
-|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
-| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | iii engine worker supervision |
-| Prometheus / Grafana | iii OTEL + health monitor |
-| Custom plugin systems | `iii worker add <name>` |
-
-**250 source files · ~55,000 LOC · 3,400+ tests · 324 functions · 67 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+The viewer server binds to `127.0.0.1` by default and attaches the server secret when it forwards requests to the REST API. On a non-loopback bind, the HTML shell remains public but every proxy request requires the bearer; the viewer prompts for it and stores it in session storage. Configure explicit host/origin allowlists and TLS before exposing a viewer. 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'`).
---
@@ -1519,24 +1296,9 @@ Local embeddings ship as an optional dependency but are not enabled by default.
### Cost-aware model selection
-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.
+Start keyless for capture and keyword recall. Enable `EMBEDDING_PROVIDER=local` for on-device semantic search after the initial model download. LLM-written compression requires a provider and `AGENTMEMORY_AUTO_COMPRESS=true`; it can make a request for each captured observation, so check your provider's current pricing before enabling it.
-| Tier | Model | Input / 1M | Output / 1M | Cost for the captured 35h | Notes |
-|------|-------|------------|-------------|---------------------------|-------|
-| Recommended | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | Latest DeepSeek; cheapest recommended pick for compression workloads. |
-| Recommended | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Solid compression + summarization quality at ~10× lower cost than Sonnet. |
-| Recommended | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | Strong code reasoning if your sessions are heavily code-shaped. |
-| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Same list price as the measured Sonnet 4.6 run; $2/$10 intro pricing through 2026-08-31. |
-| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flagship tier; expensive for always-on background work. |
-| Avoid | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flagship-class model; overspend for compression. |
-
-Measured rows come from the captured run; (est.) rows scale the same token mix by each model's list price.
-
-agentmemory prints a runtime warning when `OPENROUTER_MODEL` matches a premium-tier pattern. Set `AGENTMEMORY_SUPPRESS_COST_WARNING=1` to silence once you've made an informed choice.
-
-Quality vs cost tradeoff for memory work: compression is a summarization task with relatively loose quality bars (the agent re-reads the summary, not the user). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder land within rounding error of Sonnet on this task while costing 10-70× less. Save the premium-tier models for queries you read directly.
-
-Sources: [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/).
+The viewer and `agentmemory status` show the active providers. Local OpenAI-compatible servers work with the same configuration shape as hosted providers.
### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1566,39 +1328,24 @@ When `AGENT_ID` is unset, memory remains unscoped (legacy behavior, no tags, no
### Ports
-agentmemory + iii-engine bind four ports by default. If a restart fails with `port in use`, this table tells you which process to look for.
-
-| Port | Process | Purpose | Env override |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | Internal streams worker (consumed by agentmemory + viewer) | `III_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` |
+The API and viewer bind to loopback by default.
-`--port <N>` 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.
+| Port | Purpose | Env override |
+|---|---|---|
+| `3111` | REST API, MCP HTTP and live viewer events | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-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.
+`--port <N>` sets the REST port and defaults the viewer to `N+2`. Use `--instance N` for a separate runtime. Internal runtime listeners must remain private; see the [deployment guide](deploy/README.md) before exposing the service remotely.
-Stale-process cleanup when ports stay bound after a crashed run:
+### Storage backend: file (default) vs Redis
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
-
-`agentmemory stop` 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.
+The default file store needs no separate database service. Redis is optional with `AGENTMEMORY_STATE_BACKEND=redis` and `AGENTMEMORY_REDIS_URL`. Changing backends does not copy existing memories. Follow the [storage and backup guide](docs/reliability/state-storage.md) for persistence settings, Redis limitations and authenticated export/import.
### Config File
-Put agentmemory runtime configuration in `~/.agentmemory/.env` instead of exporting variables in every shell. If the viewer shows a setup hint like `export ANTHROPIC_API_KEY=...`, copy it into this file as `ANTHROPIC_API_KEY=...` without the `export` prefix, then restart agentmemory.
+Put agentmemory runtime configuration in `~/.agentmemory/.env` instead of exporting variables in every shell. If the viewer shows a setup hint like `export ANTHROPIC_API_KEY=...`, copy it into this file as `ANTHROPIC_API_KEY=...` without the `export` prefix, then restart agentmemory. Set `AGENTMEMORY_ENV_FILE` to use another env-file path.
-Process environment variables still work and take precedence over values in the file.
+Process environment variables take precedence over values in the file. Restart the server after changing its configuration.
On Windows, the same file lives at `%USERPROFILE%\.agentmemory\.env`:
@@ -1625,182 +1372,39 @@ GRAPH_EXTRACTION_ENABLED=true
### Environment Variables
-Create `~/.agentmemory/.env`:
+Common options for `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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
-# AGENTMEMORY_FINALIZE_IDLE_MS=120000 # Per-turn Stop hooks leave the session open; it
- # is completed and summarized once it has been idle
- # this long. 0 completes it on every Stop.
-
-# 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)
+# Semantic recall on your machine, after the first model download
+EMBEDDING_PROVIDER=local
+
+# Optional automatic context injection through the shared hooks
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# Optional LLM-written compression; also requires a configured provider
+# AGENTMEMORY_AUTO_COMPRESS=true
+
+# Show 8 essential MCP tools instead of the default 54
# AGENTMEMORY_TOOLS=core
+
+# Disable scheduled auto-forget and lesson/insight decay
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+The complete reference is [`.env.example`](.env.example), including provider credentials, capture filters, retention, storage, team scope and optional features. `AGENTMEMORY_ENV_FILE` selects another file. Never commit a populated `.env` or bearer secret.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>`, and mesh sync endpoints require an explicitly set `AGENTMEMORY_SECRET` on both peers.
+146 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>`, 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`. Most bundled clients read it from there when they talk 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 and filesystem-watcher integrations. The Hermes provider and its optional MCP connection instead use credentials managed by Hermes; configure them with `hermes memory setup`. 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:
+**Authentication is on by default.** When `AGENTMEMORY_SECRET` is not set (in the shell or in `~/.agentmemory/.env`), the CLI generates a random secret on first start and stores it at `~/.agentmemory/secret`, mirrored to the selected data directory as `secret`, with mode `0600` (the platform-specific default data directory is described above). Bundled clients read the canonical secret first when they talk 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 need the secret set in their environment. Repository-based Docker self-host deployments and the `deploy/` entrypoints 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
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1837,7 +1441,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Share with team |
| `GET` | `/agentmemory/audit` | Audit trail |
-Full endpoint list: [`src/triggers/api.ts`](src/triggers/api.ts)
+Full endpoint list: [generated REST reference](plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1859,19 +1463,19 @@ When the server is down, does not answer in time or returns a 5xx, the hook appe
**Upgrading from v0.9.30:** if you already reset the graph before upgrading, run `POST /agentmemory/graph/reset` again after the upgrade. Earlier reset timestamps are not used to infer a completed generation reset.
-**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.
+**Compacting graph provenance.** Legacy provenance compaction is deferred at startup because it reads complete legacy scopes. `/agentmemory/status` reports `deferred`, or `off` with `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Run the manual compaction below during maintenance. Retrieval index migration is separate: use `agentmemory graph-index migrate --allow-legacy-scan` as described in the [maintenance guide](docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1885,7 +1489,7 @@ npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
```
-**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.
+**Prerequisites:** see [Install](#install). Contribution rules and release checks are in [CONTRIBUTING.md](CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-license.svg"><img src="assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.md
index e9746827..75cdd6c7 100644
--- a/READMEs/README.ar-SA.md
+++ b/READMEs/README.ar-SA.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- وكيل الترميز الخاص بك يتذكر كل شيء. لا حاجة لإعادة الشرح من جديد.
- مبنيّ على <a href="https://github.com/iii-hq/iii">iii engine</a>
+ ذاكرة دائمة بين جلسات البرمجة والوكلاء.
</strong><br/>
- ذاكرة دائمة لـ Claude Code وGitHub Copilot CLI وCursor وGemini CLI وCodex CLI وHermes وOpenClaw وpi وOpenCode، ولأي عميل MCP.
+ ذاكرة دائمة لـ Claude Code وGitHub Copilot CLI وCursor وGemini CLI وCodex CLI وHermes وOpenClaw وpi وOh My Pi وDeepSeek Harness وOpenCode، ولأي عميل MCP.
</p>
<p align="center">
@@ -65,6 +64,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -89,20 +89,23 @@
<a href="#how-it-works">آلية العمل</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">العارض</a> &bull;
- <a href="#powered-by-iii">مدعوم بـ iii</a> &bull;
<a href="#configuration">الإعدادات</a> &bull;
<a href="#api">API</a>
</p>
---
+يسجل AgentMemory أحداث الجلسات المدعومة ويتيح البحث عن القرارات والإصلاحات والدروس عبر الوكلاء. يمكنك فحص الذكريات وتعديلها وتصديرها وحذفها في العارض. يعمل البحث بالكلمات دون مفتاح API؛ وتضيف التضمينات البحث الدلالي.
+
+<a id="install"></a>
+
## التثبيت
المتطلبات:
- يتطلب الأمر 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 فهما المساران المدعومان الآخران.
+- يحتاج macOS/Linux أيضًا إلى `curl` وصدفة POSIX `sh` و`tar` لإعداد البيئة تلقائيًا.
+- في Windows استخدم WSL2 أو [تعليمات التثبيت الأصلي](#windows).
أمر التثبيت الجديد المعياري:
@@ -110,11 +113,11 @@
npx -y @agentmemory/agentmemory@latest
```
-التشغيل الأول هو إعداد تفاعلي: تختار الوكلاء المراد ربطهم (Claude Code وCursor وCodex وGemini CLI وOpenCode، ...)، وتختار مزوّد LLM أو تبقى بلا مفتاح، فيقوم الإعداد بتوليد ملف التكوين، وتشغيل خادم الذاكرة ومحرك iii المثبَّت الخاص به، ويعرض عليك تثبيته عالميًا بحيث يعمل أمر `agentmemory` المجرد في كل مكان بعد ذلك. تقبل `-y` مطالبة npx بتثبيت الحزمة، وتتجنّب `@latest` إصدارًا قديمًا مخزَّنًا مؤقتًا. يُتيح المزوّد ميزات LLM، لكن ضغط الملاحظات المكتوب بواسطة LLM لا يبدأ إلا عند ضبط `AGENTMEMORY_AUTO_COMPRESS=true` أيضًا.
+اختر الوكلاء ومزوّدًا أو الوضع دون مفتاح. يحفظ الإعداد التهيئة ويشغّل خادم الذاكرة ويعرض تثبيت أمر `agentmemory` عالميًا. يقبل `-y` مطالبة npm؛ ويختار `@latest` الإصدار الحالي. يتطلب ضغط 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 <path>` أو `AGENTMEMORY_DATA_DIR` لتجاوز ذلك المسار، وأعد استخدام القيمة نفسها في كل إعادة تشغيل. للحفاظ على التوافق مع الإصدارات السابقة، يُعطى `./data/state_store.db` أو `./data/iii-config.yaml` الموجودان مسبقًا الأسبقية على المسار الافتراضي للنظام في النسخة 0؛ وتظل الراية الصريحة أو تجاوز متغيرات البيئة هي الأعلى أسبقية.
+واجهة API على `http://localhost:3111` والعارض على `http://localhost:3113`. يستمع كلاهما افتراضيًا للاتصالات المحلية فقط. الإعدادات في `~/.agentmemory/.env`؛ ويوضح [تخزين البيانات](#data-storage) مجلدات الذاكرة والمثيلات المنفصلة.
بعد ذلك، تحقَّق من أن الاسترجاع يعمل، وأعطِ وكيلك مهاراته:
@@ -129,14 +132,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-اربط وكلاء إضافيين في أي وقت باستخدام `agentmemory connect <agent>` — توجد 20 حزمة توصيل مُدرَجة في [يعمل مع كل وكيل](#works-with-every-agent). المرجع الكامل للأوامر في [البدء السريع](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-المسار الأسرع هو WSL2. يتطلب إعداد المحرك على Windows الأصلي تنزيل أرشيف ZIP الخاص بالإصدار المثبَّت v0.22.1 واستخراج `iii.exe` يدويًا؛ فالواجهة الطرفية CLI لا تستخرجه تلقائيًا. كما يُدعم Docker Desktop أيضًا. راجع [ملاحظات Windows](#windows) للاطلاع على الخطوات التفصيلية.
-
-</details>
+اربط وكيلًا آخر باستخدام `agentmemory connect <agent>`. راجع [التكاملات](#works-with-every-agent) و[الأوامر اليومية](#everyday-commands).
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -156,13 +152,6 @@ npm install -g @agentmemory/agentmemory@latest
</details>
-<details>
-<summary><strong>لديك محرك iii خاص بك يعمل مسبقًا</strong></summary>
-
-يُثبّت agentmemory الإصدار v0.22.1 من iii-engine تحديدًا، ولن يرتبط بإصدار مختلف (لأن العامل لا يستطيع التحدث ببروتوكول محرك آخر). أوقف المحرك الآخر، ثم شغّل `npx -y @agentmemory/agentmemory@latest`. سيثبّت ويشغّل الإصدار المثبَّت v0.22.1 في `~/.agentmemory/bin`، تاركًا نسخة `iii` الخاصة بك دون أي تغيير.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -189,7 +178,7 @@ npm install -g @agentmemory/agentmemory@latest
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>إضافة أصلية + 7 خطافات + MCP</sub>
+<sub>إضافة أصلية + خطافات دورة الحياة + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -216,7 +205,7 @@ npm install -g @agentmemory/agentmemory@latest
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>إضافة أصلية + MCP</sub>
+<sub>استرجاع أصلي + التقاط + مهارات</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -282,7 +271,7 @@ npm install -g @agentmemory/agentmemory@latest
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>خادم MCP</sub>
+<sub>التقاط أصلي + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -305,6 +294,12 @@ npm install -g @agentmemory/agentmemory@latest
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>استرجاع أصلي + التقاط + مهارات + MCP اختياري</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -313,22 +308,26 @@ npm install -g @agentmemory/agentmemory@latest
---
-أنت تشرح نفس البنية المعمارية في كل جلسة. وتعيد اكتشاف نفس الأخطاء مرارًا. وتُعلِّم نفس التفضيلات من جديد. تتوقف الذاكرة المدمجة (CLAUDE.md، .cursorrules) عند حد 200 سطر وتصبح قديمة بمرور الوقت. يحل agentmemory هذه المشكلة. فهو يلتقط بصمت ما يفعله وكيلك، ويضغطه في ذاكرة قابلة للبحث، ويحقن السياق المناسب عند بدء الجلسة التالية. أمر واحد فقط. ويعمل عبر الوكلاء كافة.
+<a id="data-storage"></a>
-**ما الذي يتغيّر:** في الجلسة 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 <path>` أو اضبط `AGENTMEMORY_DATA_DIR`؛ وأيٌّ من هذين الضبطين الصريحين يسبق آلية الاكتشاف القديمة في الأولوية:
+| المنصة | مجلد البيانات |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+يعيد المثيل 0 استخدام `./data/state_store.db` الموجود. اختر مجلدًا آخر عبر `--data-dir <path>` أو `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
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-تستخدم عمليات التشغيل الأصلية (native) وعبر Docker نفس دليل المضيف المُحلَّل؛ ويربطه Docker (bind-mount) عند `/data`. يُضيف الخيار `--instance 1` اللاحقة `instance-1` إلى الدليل المُحلَّل، ويختار رباعية المنافذ الافتراضية المستقلة `3211/3212/3213/49234`.
+يستخدم `--instance 1` المجلد الفرعي `instance-1` ومنفذ API ‏`3211` والعارض `3213`. راجع [دليل التخزين والنسخ الاحتياطي](../docs/reliability/state-storage.md) لمعرفة Redis والترحيل.
ملاحظات آخر إصدار: [CHANGELOG.md](../CHANGELOG.md).
@@ -478,7 +477,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>الاعتماديات الخارجية</strong></td>
-<td>لا يوجد (SQLite + iii-engine)</td>
+<td>لا يتطلب خدمة قاعدة بيانات منفصلة</td>
<td>Qdrant / pgvector</td>
<td>Postgres + قاعدة بيانات متجهية</td>
<td>متعددة</td>
@@ -552,14 +551,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | رسم بياني معرفي زمني؛ يملك أقوى نتائج منشورة للاستعلامات الزمنية (LongMemEval 63.8%)، لكن بناء الرسم البياني يتم بشكل غير متزامن، فقد تتأخر الحقائق الجديدة |
| Cognee | 30K | استيعاب يحوّل المستندات إلى رسم بياني معرفي، مخصص لـ Python فقط، ومبني لاستخراج الكيانات البنيوية لا لالتقاط الجلسات |
-لا يلتقط أي منها تلقائيًا من خطافات وكيل الترميز، ولا يقدّم عارضًا يُبنى أولاً للتشغيل المحلي، ولا يعمل بلا مفتاح — وهذا المزيج هو ما بُني agentmemory حوله.
+يجمع AgentMemory التقاط الجلسات وسجل المشروع القابل للبحث والعارض المحلي، مع العمل دون مفتاح منذ التشغيل الأول.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-التوافق: يستهدف هذا الإصدار `iii-sdk` بالإصدار 0.22.1، ويثبّت iii-engine على الإصدار v0.22.1.
-
### جرّبه في 30 ثانية
```bash
@@ -574,9 +571,11 @@ npx -y @agentmemory/agentmemory@latest demo
افتح `http://localhost:3113` لمشاهدة بناء الذاكرة مباشرةً.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### التحقق من تثبيت جديد واستمرارية البيانات بعد إعادة التشغيل
-مع تشغيل الخادم، تحقّق من REST، والحالة الصحية (health)، والعارض، وحالة بيئة التشغيل المعتمدة على iii:
+عندما يعمل الخادم، تحقق من الصحة والعارض والحالة:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -585,20 +584,27 @@ 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) وتأكّد من إمكانية البحث عنها:
+يعرض `status` صحة الخادم والمزوّدين ووضع التضمين وتسليم الملاحظات والاستعادة. تتطلب طلبات REST المحمية سر الخادم. استخدم قيمة `AGENTMEMORY_SECRET` التي حددتها؛ وإلا فاقرأ السر المحلي المُنشأ:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
ثم شغّل `npx -y @agentmemory/agentmemory@latest stop`، وأعد تشغيل الأمر المعياري من جديد في الطرفية 1، وانتظر استجابة `/agentmemory/livez`، وكرِّر عملية البحث. يجب أن تظل عيّنة الاختبار مُستردَّة. إذا اخترت مسار `--data-dir` مخصصًا، مرّر الدليل نفسه عند إعادة التشغيل.
+<a id="everyday-commands"></a>
+
### أوامر الاستخدام اليومي
تعليمات التثبيت والإعداد موجودة في [التثبيت](#install) أعلاه (يرشدك التشغيل الأول خلالها). في الاستخدام اليومي:
@@ -606,6 +612,9 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -625,7 +634,7 @@ npx -y @agentmemory/agentmemory@latest import-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`، ويُستخرج منه بلورة جلسة (crystal) ودروس مستفادة (lessons).
+تظهر الجلسات المستوردة في Replay بجانب الجلسات الأصلية. تُفهرس النصوص وتُوسم بقناة المصدر `import`؛ ويمكن أن ينتج عن المعالجة بلورات جلسات ودروس أيضًا.
> **تنبيه إذا كنت تعتمد على `import-jsonl` كمسارك الأساسي للالتقاط:** يحذف إعداد `cleanupPeriodDays` الخاص بـ Claude Code (في `~/.claude/settings.json`، والافتراضي **30**) تلقائيًا محاضر JSONL الأقدم من تلك النافذة الزمنية من `~/.claude/projects/`. إذا ثبّت agentmemory حديثًا على سجل Claude Code يمتد لعدة أشهر، فإن كل ما هو أقدم من 30 يومًا يكون قد اختفى مسبقًا قبل أول استيراد. إما أن تشغّل `import-jsonl` عبر مهمة cron، أو ترفع قيمة `cleanupPeriodDays` إلى رقم أعلى، أو تربط خطافات الالتقاط التلقائي (مسار تثبيت الإضافة الافتراضي) حتى تصل كل مداولة إلى agentmemory والجلسة لا تزال نشطة، فلا يعود تنظيف JSONL ذا أهمية.
@@ -637,14 +646,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-تحذير: يُغيّر هذا الأمر مساحة العمل/بيئة التشغيل الحالية. فقد يُحدِّث اعتماديات JavaScript ويسحب صورة Docker المثبَّتة `iiidev/iii:0.22.1`. ولن يُثبّت مطلقًا محرك iii غير مثبَّت الإصدار أو أحدث منه.
-
-تفاصيل التنفيذ موجودة في `src/cli.ts` (راجع `runUpgrade` حول نطاق `src/cli.ts:544-595`).
+يحدّث الأمر البيئة المحلية وقد يغيّر تبعيات JavaScript في مساحة العمل الحالية. انسخ البيانات احتياطيًا واقرأ [دليل الترقية](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code بدون تثبيت الإضافة (مسار MCP القائم بذاته)
@@ -705,6 +712,30 @@ 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`. ثبّت الإضافة أيضًا إذا رغبت في تجربة الخطافات/المهارات الكاملة.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+بعد ذلك، من **Settings → Plugins → Add marketplace** اختر مجلد agentmemory الذي يحتوي على `.cursor-plugin/plugin.json`، وفعّل إضافة **agentmemory** وأعد تحميل النافذة. توفر الإضافة التقاط دورة الحياة وإسناد المشروع حسب مساحة العمل والمهارات وMCP. فعّل خطافات الإضافة أو الخطافات اليدوية في `~/.cursor/hooks.json` لتجنب التسجيل المكرر.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+اختر أمر العميل الذي تستخدمه. يثبت Pi وOMP الاسترجاع والتقاط الأحداث وإعادة إرسال البيانات غير المتصلة والمهارات؛ ويضيف `--with-mcp` جميع الأدوات. شغّل `/reload` في Pi أو أعد تشغيل OMP، ثم تحقق من `/agentmemory-status`. يثبت DSH ‏MCP وإضافة الالتقاط المرفقة؛ أعد تشغيل DSH بعد الربط.
+
+يدعم Pi أيضًا الحزمة القابلة للتثبيت `@agentmemory/pi`. يوضح [دليل Pi](../integrations/pi/) التثبيت المحلي وتوفر npm. استخدم طريقة تثبيت واحدة لكل عميل.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (الصق هذا الموجّه)</b></summary>
@@ -751,6 +782,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### وكلاء آخرون
شغّل خادم الذاكرة: `npx -y @agentmemory/agentmemory@latest`
@@ -767,8 +800,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
هذا **مُكمِّل** لأمر `agentmemory connect <agent>`:
-- يكتب `agentmemory connect <agent>` إعدادات خادم MCP بحيث تصبح الأدوات متاحة.
-- يُثبّت `npx skills add rohitg00/agentmemory` المهارات بحيث يعرف الوكيل متى يستدعيها.
+- يكتب `agentmemory connect <agent>` عادةً إعدادات MCP. يثبت Hermes وOpenClaw وPi وOh My Pi التكامل الأصلي والمهارات افتراضيًا؛ ويمكن تفعيل MCP باستخدام `--with-mcp`.
+- يثبت `npx skills add rohitg00/agentmemory` المهارات للوكلاء الذين لا تتضمن حزمهم مهارات أصلية. تخطّ هذه الخطوة مع Hermes وOpenClaw وPi وOh My Pi؛ فموصلاتها تثبت المهارات بالفعل.
بالنسبة للوكلاء القليلين الذين لا تغطيهم واجهة سطر الأوامر skills بعد (Zed بالإصدار v1.3.x وما قبله)، ضع ملفات SKILL.md الـ17 بنفسك تحت دليل المهارات الأصلي للوكيل؛ فالتنسيق نفسه يعمل في كل مكان.
@@ -792,7 +825,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| الوكيل | ملف الإعدادات | ملاحظات |
|---|---|---|
| **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 من محضر الجلسة عند انتهائها. |
+| **Cursor (الإضافة الكاملة)** | `.cursor-plugin/` | توفر الإضافة خطافات دورة الحياة وتحديد مساحة العمل والمهارات وMCP في Cursor IDE و`cursor-agent`. راجع [إعداد Cursor](#cursor). |
| **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. |
@@ -806,47 +839,28 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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/). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. استرجاع أصلي + التقاط + مهارات. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. استرجاع أصلي + التقاط + مهارات. [Oh My Pi](../integrations/omp/). |
+| **وكيل 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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (مفضّل) أو `config.json` (قديم) | ينشئ `agentmemory connect continue` ملف `config.yaml` عند غياب الإعدادات، أو يعدّل `config.json` الموجود. بالنسبة إلى YAML موجود، يعرض الكتلة لإضافتها تحت `mcpServers:` للحفاظ على التعليقات والمراسي. يستخدم Continue مصفوفة لا كائنًا. |
| **Zed** | `~/.config/zed/settings.json` | يكتب `agentmemory connect zed` تحت `context_servers` (مفتاح Zed الخاص، وليس `mcpServers`). يمكن ربط خوادم MCP البعيدة بدلًا من ذلك عبر `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | يكتب `agentmemory connect droid` كتلة `mcpServers` القياسية. وتوضع تجاوزات نطاق المشروع في `<repo>/.factory/mcp.json`. مرّر `--with-hooks` لالتقاط تلقائي أصلي. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | يُفعّل `agentmemory connect dsh` أدوات MCP. أضف `--with-hooks` لتحميل إضافة الالتقاط الأصلية المضمّنة مع AgentMemory، دون حزمة إضافية. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | لا ينطبق | استخدم [أمثلة REST الموثّقة](#validate-a-fresh-install-and-restart-persistence) للحفظ والبحث من السكربتات. |
| **أي وكيل (أكثر من 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.
+استخدم [REST API](#api) من أي لغة أو [أدوات MCP](#mcp-server) من وكيل. يستخدم REST ‏JSON ومصادقة bearer؛ راجع [مثال الحفظ والبحث](#validate-a-fresh-install-and-restart-persistence). للتكامل المباشر مع بيئة التشغيل، راجع [أمثلة Python](../examples/python/).
### من المصدر
@@ -855,83 +869,33 @@ 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=<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).
+يشغّل `npm start` الخادم المحلي نفسه الذي يشغّله CLI المثبّت. المتطلبات في [التثبيت](#install)؛ ويستمع API والعارض على `127.0.0.1`.
### 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**
+يعمل agentmemory على Windows 10/11. يتبع WSL2 مسار Linux ويمكنه تثبيت المحرك المثبّت تلقائيًا. يتطلب Windows الأصلي تثبيت ملف iii-engine 0.25.0 المثبّت يدويًا؛ نزّل الأرشيف المطابق من [صفحة إصدار iii 0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0)، وتحقق من بصمته، وضع `iii.exe` على `PATH` (مثل `%USERPROFILE%\.local\bin\iii.exe`). لا يستخرج CLI ملف ZIP الخاص بـ Windows تلقائيًا.
-```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 على Windows الأصلي إلا `agentmemory connect copilot-cli`. أما وكلاء Windows الأصليون الآخرون، فاستخدم كتلة MCP اليدوية من [وكلاء آخرون](#other-agents). شغّل `connect` داخل WSL فقط عندما يكون الوكيل المستهدف مثبتًا في بيئة WSL نفسها.
-**الخيار ج: MCP قائم بذاته فقط (بلا محرك).** إذا كنت تحتاج فقط إلى أدوات MCP لوكيلك ولا تحتاج إلى REST API أو العارض أو مهام cron، تجاوز المحرك كليًا:
+**MCP القائم بذاته فقط (من دون المحرك).** إذا كنت تحتاج إلى أدوات MCP فقط ولا تحتاج إلى REST API أو العارض أو خدمات runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| تجاوز الرجوع إلى 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`.
+شغّل `agentmemory doctor` أو أعد التشغيل مع `--verbose`. إذا كانت المنافذ مشغولة، استخدم `--port <N>` أو `--instance <N>`. يوضح [دليل الترقية](../docs/upgrades/iii-0.25.md) التوافق والاستعادة.
---
<h2 id="deploy">النشر</h2>
-قوالب نشر بنقرة واحدة للمضيفين المُدارين. يشحن كل قالب ملف 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.
+للاستضافة الذاتية استخدم Docker Compose أو القوالب أدناه. توجد الذاكرة وبيانات الاعتماد على وحدة `/data`؛ انسخها احتياطيًا وأعد استخدامها عند الترقية. يوضح [دليل النشر](../deploy/README.md) المصادقة والشبكة والنسخ الاحتياطي والترحيل.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
يتطلب زر نشر Render بنقرة واحدة وجود `render.yaml` في جذر المستودع، وهو ما نتركه نظيفًا عمدًا. استخدم مسار Render Blueprint المُوثَّق في [`deploy/render/`](.././deploy/render/README.md) للإشارة يدويًا إلى المخطط الموجود في المستودع.
@@ -948,29 +912,13 @@ npx -y @agentmemory/mcp
خادمك الخاص عبر [Coolify](https://coolify.io/self-hosted)؛ نفس حزمة Docker
Compose، وأنت من يملك المضيف والبيانات.
-لا يُنشر إلا المنفذ `3111`. ويبقى العارض على `3113`
-مرتبطًا بعنوان loopback داخل الحاوية؛ ويوثِّق ملف README لكل قالب نمط
-نفق SSH للوصول إليه.
+يستخدم REST المنفذ `3111` والعارض `3113`. أبقهما خاصين أو احمهما بالمصادقة وTLS. إعدادات المنصات و[ترحيل Docker القديم](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) موضحة في دليل النشر.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-ينسى كل وكيل ترميز كل شيء عند انتهاء الجلسة، وتبدأ كل جلسة جديدة بإعادتك شرح مكدّسك التقني من جديد. يعمل 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.
-```
+تتوزع معرفة المشروع بين المحادثات وملفات التعليمات. يتيح AgentMemory البحث عن القرارات والإصلاحات والدروس السابقة من الوكيل المستخدم حاليًا.
### مقابل ذاكرة الوكيل المدمجة
@@ -978,7 +926,7 @@ Session 2: "Now add rate limiting"
| | مدمج (CLAUDE.md) | agentmemory |
|---|---|---|
-| الحجم | حد 200 سطر | غير محدود |
+| الصيانة | تعليمات تُدار يدويًا | سجل جلسات وذكريات مفهرسة |
| البحث | يحمّل كل شيء إلى السياق | BM25 + متجهات + رسم بياني (أفضل K فقط) |
| تكلفة الرموز | أكثر من 22K عند 240 ملاحظة | ~1,900 رمز (أقل بنسبة 92%) |
| بين الوكلاء | ملفات لكل وكيل | MCP + REST (أي وكيل) |
@@ -1004,13 +952,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### توحيد الذاكرة الرباعي المستويات
@@ -1028,6 +976,8 @@ SessionStart hook fires
### ما الذي يُلتَقط
+يصف الجدول خطافات Claude Code. تلتقط التكاملات الأخرى الأحداث التي يوفرها عميلها. حقن السياق التلقائي عبر الخطافات المشتركة اختياري: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| الخطاف | يلتقط |
|------|----------|
| `SessionStart` | مسار المشروع، ومعرّف الجلسة |
@@ -1044,7 +994,7 @@ SessionStart hook fires
| القدرة | الوصف |
|---|---|
-| **الالتقاط التلقائي** | يُسجَّل كل استخدام للأدوات عبر الخطافات، دون أي جهد يدوي |
+| **الالتقاط التلقائي** | أحداث الجلسات والأدوات المدعومة التي تسجلها التكاملات الأصلية |
| **البحث الدلالي** | BM25 + متجهات + رسم بياني معرفي بدمج RRF |
| **تطوّر الذاكرة** | إصدارات، وإحلال (supersession)، ورسوم بيانية للعلاقات |
| **نظافة الاسترجاع** | تخرج نسخ الذاكرة المُستبدَلة من فهارس البحث؛ وتحتفظ سلسلة الإصدارات في KV بالتاريخ الكامل |
@@ -1105,7 +1055,7 @@ EMBEDDING_PROVIDER=local
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`.
+> **وسيط 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` (أو اتصل بخادم استضافة ذاتية) واضبط `AGENTMEMORY_URL=http://localhost:3111`.
### 54 أداة
@@ -1245,7 +1195,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
-يبدأ تلقائيًا على المنفذ `3113`. يحمّل العارض لقطة واحدة (snapshot) عند الاتصال (`GET /agentmemory/viewer/snapshot`)، ثم يطبّق أحداث التيار المباشر: تظهر الذكريات الجديدة، والدروس المستفادة، والملاحظات، وإدخالات التدقيق، وتغييرات الرسم البياني، وتحديثات الحالة الصحية دون أي استقصاء دوري أو إعادة تحميل للصفحة. والطلبات الأخرى الوحيدة هي الإجراءات التي تنقر عليها، وصفحات "تحميل المزيد"، وعمليات البحث. وعند انقطاع التيار، يُظهر العارض مدى قِدَم أرقامه، ويعيد الاتصال بتراجع تدريجي (backoff)، ويعيد المزامنة من لقطة واحدة.
+يبدأ العارض تلقائيًا على المنفذ `3113`. يحمّل لقطة واحدة عند الاتصال (`GET /agentmemory/viewer/snapshot`)، ثم يطبّق الأحداث الحية عبر SSE عند `/agentmemory/viewer/events` على عامل REST: تظهر الذكريات الجديدة والدروس والملاحظات وإدخالات التدقيق وتغييرات الرسم البياني وتحديثات الحالة الصحية دون استقصاء دوري أو إعادة تحميل للصفحة. والطلبات الأخرى الوحيدة هي الإجراءات التي تنقر عليها وصفحات "تحميل المزيد" وعمليات البحث. عند انقطاع التيار، يُظهر العارض مدى قِدَم بياناته، ويعيد الاتصال بتراجع تدريجي (backoff)، ثم يعيد المزامنة من لقطة واحدة.
- **12 تبويبًا في أربع مجموعات** مع عدادات حية، وروابط عميقة (`#memories/<id>`، و`#sessions/<id>?obs=<id>`، و`#graph/<id>`، و`#health/consolidation`)، واختصارات لوحة المفاتيح، وقائمة للهاتف المحمول.
- **الذكريات:** بحث من جانب الخادم، ومرشِّحات حسب المشروع والوكيل والنوع، ولوحة تفاصيل تضم سلسلة الإصدارات ومقارنة فروق الكلمات (word diff)، وروابط المصدرية، وأزرار نسخ للمعرّف، واستدعاء MCP، وأمر curl، وتعديل (ينشئ إصدارًا جديدًا)، ونسيان مع تأكيد، ونسيان جماعي، وتصدير JSON.
@@ -1258,190 +1208,10 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
open http://localhost:3113
```
-يرتبط خادم العارض بـ `127.0.0.1` افتراضيًا، ويُرفق سر الخادم عند تمرير الطلبات إلى REST API، فلا يحتاج إلى أي إعداد. وتتبع نقطة النهاية `/agentmemory/viewer` المُقدَّمة عبر REST القواعد العادية لرمز الحامل (bearer token)، وتُعيد توجيه المتصفحات التي لا تحمل رمزًا إلى منفذ العارض. وتستخدم ترويسات CSP قيمة nonce خاصة بالنص البرمجي لكل استجابة، وتُعطِّل سمات المعالج المضمَّنة inline (`script-src-attr 'none'`).
+يرتبط خادم العارض بـ `127.0.0.1` افتراضيًا ويُرفق سر الخادم عند تمرير الطلبات إلى REST API. عند الارتباط بعنوان غير loopback، تظل واجهة HTML متاحة للعامة، لكن كل طلب وكيل يتطلب رمز الحامل؛ ويطلبه العارض ويحفظه في تخزين الجلسة. اضبط قوائم سماح صريحة للمضيفين والمنشأات وTLS قبل إتاحة العارض. وتتبع نقطة النهاية `/agentmemory/viewer` المقدمة عبر REST قواعد رمز الحامل المعتادة، وتعيد توجيه المتصفحات التي لا تحمل رمزًا إلى منفذ العارض. تستخدم ترويسات CSP قيمة nonce خاصة بالنص البرمجي لكل استجابة، وتعطّل سمات المعالج المضمّنة (`script-src-attr 'none'`).
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-يُظهر العارض على `:3113` ما **تذكّره** وكيلك. أما [لوحة تحكم iii](https://iii.dev/docs/console) فتُظهر ما **فعله** وكيلك: كل عملية ذاكرة كتتبع OpenTelemetry، وكل إدخال KV قابل للتعديل، وكل دالة قابلة للاستدعاء، وكل تيار قابل للاستماع إليه. نافذتان على الذاكرة نفسها: واحدة بشكل المنتج، وأخرى بشكل المحرك.
-
-شاهد `memory_smart_search` وهو يُطلَق وتابع مسح BM25 ← البحث في التضمينات ← دمج RRF ← إعادة الترتيب (reranker) كشكل شلالي (waterfall). عدِّل مؤقِّت توحيد عالقًا في مستعرض KV. أعد تشغيل خطاف `PostToolUse` بحمولة مُعدَّلة. ثبِّت تيار WebSocket وشاهد الملاحظات وهي تصل لحظيًا.
-
-يقدّم agentmemory هذا مجانًا لأن كل استدعاء دالة ومحفِّز يمر عبر iii؛ فلا شيء مخصص، ولا شيء يحتاج إلى تثبيت أدوات قياس (instrumentation).
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="صفحة العمّال في لوحة تحكم iii: العمّال المتصلون بما فيهم نُسخ agentmemory مع عدادات الدوال الحية وبيانات التعريف الخاصة ببيئة التشغيل" width="720" />
- <br/>
- <em>صفحة العمّال: كل عامل متصل، بما في ذلك agentmemory نفسه، مع PID، وعدد الدوال، وبيئة التشغيل، وآخر ظهور.</em>
-</p>
-
-**مثبَّت مسبقًا.** تُشحن لوحة التحكم مع محرك `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`) رسم بياني معماري تفاعلي لكل عامل، ومحفِّز، وتيار. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="عرض شلالي للتتبّعات في لوحة تحكم iii يُظهر مدة كل span" width="720" />
- <br/>
- <em>التتبّعات: عرض شلالي / لهبي / تفصيلي بالخدمة لكل عملية ذاكرة.</em>
-</p>
-
-**التتبّعات مُفعَّلة مسبقًا:**
-
-يُشحن `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` (الافتراضي) ولا تُعرِّضها علنًا مطلقًا.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory هو **فعليًا نسخة تشغيل من [iii](https://iii.dev)**. تُؤلِّف ثلاث بنى أساسية (العامل، والدالة، والمحفِّز) بيئة التشغيل؛ وتأتي حالة KV، والتيارات، وتتبّعات OTEL من عمّال iii-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:<scope>`، و`stream:<name>:<group>`) ثابتة، فإذا أشارت نسختان من 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 <name>` |
-
-**250 ملف مصدري · ~55,000 سطر برمجي · 3,800+ اختبار · 324 دالة · 67 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
### مزوّدو LLM
@@ -1459,6 +1229,8 @@ fi
| **محلي (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=<your model>` | أي شيء متوافق مع OpenAI API. بلا تكلفة، ويعمل على جهازك. راجع [النماذج المحلية](#local-models-ollama--lm-studio--vllm) أدناه. |
| الرجوع لاشتراك Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | اختياري الانضمام فقط. يُولِّد جلسات `@anthropic-ai/claude-agent-sdk`؛ وكان يتسبب سابقًا في تكرار (recursion) غير محدود لخطاف Stop، فلم يعد الافتراضي. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### النماذج المحلية (Ollama / LM Studio / vLLM)
يتحدّث agentmemory مع أي خادم متوافق مع OpenAI API، فأي خادم يُعرِّض `/v1/chat/completions` يعمل دون أي تعديل في الشفرة. لا مفاتيح مدفوعة، ولا سحابة، ولا حدود لمعدل الطلبات؛ ويعمل بالكامل على جهازك.
@@ -1508,24 +1280,7 @@ OPENAI_MODEL=qwen3-8b # match the model name from LM St
### اختيار النموذج الواعي بالتكلفة
-عندما يُفعَّل الضغط الخلفي المكتوب بواسطة 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/).
+ابدأ دون مفتاح لالتقاط الأحداث والبحث بالكلمات. يفعّل `EMBEDDING_PROVIDER=local` البحث الدلالي المحلي بعد تنزيل النموذج. يتطلب ضغط LLM مزوّدًا و`AGENTMEMORY_AUTO_COMPRESS=true`؛ وقد يرسل طلبًا لكل ملاحظة، لذا تحقق من الأسعار الحالية. يعرض العارض و`agentmemory status` المزوّدين النشطين.
### ذاكرة متعددة الوكلاء (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1555,57 +1310,40 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### المنافذ
-يرتبط 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 | الغرض | متغير البيئة |
+|---|---|---|
+| `3111` | REST API وMCP HTTP وأحداث العارض المباشرة | `III_REST_PORT` |
+| `3113` | واجهة العارض | `III_VIEWER_PORT` |
-يُغيِّر `--port <N>` مرساة REST ويستمد منفذ التيارات `N+1`، والعارض `N+2`، وWebSocket المحرك `N+46023`، فقط حيث يكون المنفذ أو العنوان الصريح المقابل أعلاه غير مضبوط. ولا يُنشئ مساحة أسماء دورة حياة معزولة. استخدم `--instance 1` لعفريت (daemon) ثانٍ؛ فهو يستخدم المرساة 3211، وافتراضيًا `3211/3212/3213/49234`، ويحصل على دليل بيانات ودورة حياة منفصل باسم `instance-1`. وتتبع النُّسخ من 1 إلى 50 النمط نفسه.
+يضبط `--port <N>` منفذ REST والعارض افتراضيًا على `N+2`. ينشئ `--instance N` بيئة منفصلة. يجب أن تبقى المنافذ الداخلية خاصة؛ اقرأ [دليل النشر](../deploy/README.md) قبل الوصول عن بُعد.
-يبدأ المحرك المثبَّت بخيار `--no-update-check` (بلا أي بحث عن تحديثات أو تنبيهات أمنية مقابل GitHub عند الإقلاع) ومع تعطيل قياس الاستخدام المجهول لـ iii: يضبط agentmemory `III_TELEMETRY_ENABLED=false` للمحرك الذي يُولِّده إلا إذا صدَّرت المتغير بنفسك، ويفعل ملف compose المُضمَّن الشيء نفسه.
+### التخزين: ملف أو Redis
-تنظيف العمليات العالقة عندما تظل المنافذ مربوطة بعد تشغيل منهار:
-
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
-
-يحصد `agentmemory stop` كلًا من ملف pid الخاص بالعامل والمحرك بنظافة عند الإيقاف الأصلي السَّلِس (graceful). وفي وضع Docker، يُفرِّغ العامل الأصلي، ويُوقِف حاوية المحرك المُصادَق عليها تحديدًا، ويحافظ على كلٍّ من الحاوية وربطها بـ `/data` لإعادة تشغيل بلا فقد بيانات؛ ويتحقق التشغيل التالي من تلك الحاوية نفسها ويستأنفها. ويتطلب إلغاء التثبيت المعتمد على Docker أمر `agentmemory remove --keep-data`: فهو يحذف ملفات agentmemory المُشتركة والمُدارة بينما يحافظ على الحاوية المُصادَق عليها، وربط بياناتها، وسجل دورة الحياة اللازم لاستعادتها. ويُترَك حذف بيانات Docker المدمِّر عمدًا للمُشغِّل بعد نسخة احتياطية. وترفض الواجهة الطرفية CLI أيضًا تبنّي أو إرسال إشارة إلى حائزي منافذ Docker أو الأجهزة الافتراضية (خلفية Docker، أو vpnkit، أو colima) باعتبارهم المحرك الأصلي إلا إذا مُرِّرت `--force`. والتنظيف اليدوي أعلاه مخصص فقط لحالة ما بعد الانهيار التي لا يُترَك فيها أي ملف pid.
+لا يتطلب التخزين الافتراضي بالملفات قاعدة منفصلة. Redis اختياري عبر `AGENTMEMORY_STATE_BACKEND=redis` و`AGENTMEMORY_REDIS_URL`. تغيير الخلفية لا ينقل الذكريات الموجودة. الاستمرارية وقيود Redis والتصدير والاستيراد بالمصادقة موضحة في [دليل التخزين](../docs/reliability/state-storage.md).
### ملف الإعدادات
-ضع إعدادات بيئة تشغيل agentmemory في `~/.agentmemory/.env` بدلًا من تصدير المتغيرات في كل صدفة. إذا أظهر العارض تلميح إعداد مثل `export ANTHROPIC_API_KEY=...`، انسخه إلى هذا الملف كـ `ANTHROPIC_API_KEY=...` دون بادئة `export`، ثم أعد تشغيل agentmemory.
+ضع إعدادات runtime الخاصة بـ agentmemory في `~/.agentmemory/.env` بدل تصدير المتغيرات في كل صدفة. إذا عرض العارض تلميح إعداد مثل `export ANTHROPIC_API_KEY=...`، فانسخه إلى هذا الملف كـ `ANTHROPIC_API_KEY=...` دون السابقة `export`، ثم أعد تشغيل agentmemory. اضبط `AGENTMEMORY_ENV_FILE` لاستخدام مسار آخر لملف البيئة.
-لا تزال متغيرات بيئة العملية تعمل وتسبق في الأولوية القيم الموجودة في الملف.
+تتقدم متغيرات بيئة العملية على قيم الملف. أعد تشغيل الخادم بعد تغيير الإعدادات.
-على Windows، يعيش الملف نفسه عند `%USERPROFILE%\.agentmemory\.env`:
+على Windows، يوجد الملف نفسه في `%USERPROFILE%\.agentmemory\.env`:
```powershell
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 (بما في ذلك هذا الرجوع الصريح للاشتراك) و`AGENTMEMORY_AUTO_COMPRESS=true`. ويترك المزوّد وحده مسار الضغط التركيبي الافتراضي كما هو.
+يتطلب ضغط الملاحظات المكتوب بواسطة LLM السطرين معًا: الوصول إلى مزوّد LLM (بما في ذلك خيار الاشتراك الصريح هذا) و`AGENTMEMORY_AUTO_COMPRESS=true`. لا يغيّر وجود المزوّد وحده مسار الضغط الاصطناعي الافتراضي.
-يكون التوحيد (عُقَد الرسم البياني، والدروس المستفادة، والبلورات) مُفعَّلًا افتراضيًا كلما ضُبط مزوّد LLM. استثنِ نفسك صريحًا بـ `CONSOLIDATION_ENABLED=false` إذا أردت تشغيلًا بلا LLM. واستخراج الرسم البياني راية مستقلة:
+يكون التوحيد (عُقد الرسم البياني والدروس والبلورات) مفعّلًا افتراضيًا عند إعداد مزوّد LLM. عطّله صراحةً عبر `CONSOLIDATION_ENABLED=false` إذا أردت التشغيل دون LLM. استخراج الرسم البياني راية منفصلة:
```env
GRAPH_EXTRACTION_ENABLED=true
@@ -1614,179 +1352,30 @@ GRAPH_EXTRACTION_ENABLED=true
### متغيرات البيئة
-أنشئ `~/.agentmemory/.env`:
+خيارات شائعة في `~/.agentmemory/.env`. حقن السياق والضغط اختياريان؛ ويتطلب الضغط مزوّدًا أيضًا. يحد وضع `core` من أدوات MCP الظاهرة:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+يشمل المرجع الكامل [`.env.example`](../.env.example) المزوّدين ومرشحات الالتقاط والاحتفاظ والتخزين والفرق والميزات الاختيارية. يختار `AGENTMEMORY_ENV_FILE` ملفًا آخر. لا تُضمّن ملف `.env` ممتلئًا أو سر bearer في أي commit.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer <secret>`، وتتطلب نقاط نهاية مزامنة mesh ضبط `AGENTMEMORY_SECRET` صريحًا على كلا الطرفين.
+146 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer <secret>`، وتتطلب نقاط نهاية مزامنة 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/) سرها الخاص وتُصدِّره مسبقًا. ولاستدعاء الواجهة البرمجية يدويًا:
+**المصادقة مُفعّلة افتراضيًا.** إذا لم يُضبط `AGENTMEMORY_SECRET`، ينشئ CLI عند التشغيل الأول سرًا عشوائيًا في `~/.agentmemory/secret` بصلاحيات `0600` وينسخه أيضًا إلى مجلد البيانات المحدد. يقرأ كل عميل مضمّن هذا السر عند الاتصال بخادم محلي: CLI والعارض والخطافات تحت `plugin/scripts` وخادم MCP ووسيط `@agentmemory/mcp` والإعدادات التي يكتبها `agentmemory connect` وتكاملات OpenCode وPi وOpenClaw وHermes ومراقب نظام الملفات المضمّنة. لا يُرسل السر المحفوظ إلا إلى عناوين loopback (`localhost` و`127.0.0.0/8` و`::1`). وتكون الأولوية دائمًا لقيمة `AGENTMEMORY_SECRET` الصريحة، كما يجب ضبط السر في بيئة العملاء البعيدين. تنشئ عمليات الاستضافة الذاتية عبر Docker من المستودع ونقاط دخول [`deploy/`](../deploy/) سرها وتصدّره. لاستدعاء API يدويًا:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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، ومن خادم إلى خادم) فلا يتأثرون. ويقبل العارض أيضًا أصله الخاص.
@@ -1822,7 +1411,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | المشاركة مع الفريق |
| `GET` | `/agentmemory/audit` | مسار التدقيق |
-قائمة نقاط النهاية الكاملة: [`src/triggers/api.ts`](../src/triggers/api.ts)
+قائمة نقاط النهاية الكاملة: [مرجع REST المُولّد](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1840,19 +1429,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
وعندما يكون الخادم متوقفًا، أو لا يُجيب في الوقت المناسب، أو يُعيد 5xx، يُلحق الخطاف الملاحظة بملف تخزين مؤقت محلي، `<data dir>/capture-spool/<host>-<port>.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` لتعطيله.
+**ضغط مصدرية الرسم البياني.** يؤجَّل ضغط المصدرية القديمة عند بدء التشغيل لأنه يقرأ النطاقات القديمة كاملة. يعرض `/agentmemory/status` الحالة `deferred`، أو `off` عند ضبط `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. شغّل الضغط اليدوي أدناه أثناء الصيانة. ترحيل فهرس الاسترجاع عملية منفصلة: استخدم `agentmemory graph-index migrate --allow-legacy-scan` كما يوضح [دليل الصيانة](../docs/reliability/graph-index-migration.md).
لتشغيله يدويًا، استدعِ `POST /agentmemory/graph/compact`. فهو يتجوّل عبر فهارس الأسماء ومفاتيح الحواف بدلًا من سرد كل عقدة وحافة، وهو آمن لإعادة التشغيل. وعندما يُقلِّص المعرّفات، يكتب إدخال تدقيق `graph_compact`.
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1866,7 +1455,7 @@ npm test # 4,000+ 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.
+المتطلبات في [التثبيت](#install). قواعد المساهمة وفحوص الإصدار في [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.md
index 46c3647c..60351d42 100644
--- a/READMEs/README.bn-BD.md
+++ b/READMEs/README.bn-BD.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- আপনার কোডিং এজেন্ট সবকিছু মনে রাখে। আর বারবার ব্যাখ্যা করতে হয় না।
- <a href="https://github.com/iii-hq/iii">iii engine</a>-এর উপর তৈরি
+ কোডিং সেশন ও এজেন্ট জুড়ে স্থায়ী মেমরি।
</strong><br/>
- Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode এবং যে কোনো MCP ক্লায়েন্টের জন্য স্থায়ী মেমরি।
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode এবং যে কোনো MCP ক্লায়েন্টের জন্য স্থায়ী মেমরি।
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">এটি যেভাবে কাজ করে</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">ভিউয়ার</a> &bull;
- <a href="#powered-by-iii">iii দ্বারা চালিত</a> &bull;
<a href="#configuration">কনফিগ</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory কোডিং সেশন রেকর্ড করে, যাতে আগের সিদ্ধান্ত ও সমাধান খুঁজে পাওয়া যায়। বিভিন্ন টুলে একই মেমরি ব্যবহার করুন, সংরক্ষিত তথ্য দেখুন এবং মডেলকে কতটা প্রসঙ্গ দেওয়া হবে তা বেছে নিন।
+
+<a id="install"></a>
+
## ইনস্টল
প্রয়োজনীয়তা:
- 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 অন্য সাপোর্টেড পথ।
+- macOS/Linux-এ স্বয়ংক্রিয় সেটআপের জন্য `curl`, POSIX `sh` ও `tar` লাগে।
+- Windows / WSL2: [Windows](#windows).
ক্যানোনিকাল ফ্রেশ-ইনস্টল কমান্ড:
@@ -108,11 +111,11 @@
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`-ও সেট করা থাকে।
+এজেন্ট ও প্রোভাইডার অথবা কী ছাড়া মোড বেছে নিন। সেটআপ কনফিগারেশন সংরক্ষণ করে, মেমরি সার্ভার চালু করে এবং গ্লোবাল ইনস্টলের সুযোগ দেয়। `-y` npm-এর নিশ্চিতকরণ গ্রহণ করে; `@latest` সর্বশেষ রিলিজ বেছে নেয়। 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 <path>` বা `AGENTMEMORY_DATA_DIR` ব্যবহার করুন, এবং প্রতি রিস্টার্টে একই ভ্যালু পুনরায় ব্যবহার করুন। ব্যাকওয়ার্ড কম্প্যাটিবিলিটির জন্য, ইনস্ট্যান্স 0-এর জন্য প্ল্যাটফর্মের ডিফল্টের চেয়ে আগে থেকে থাকা `./data/state_store.db` বা `./data/iii-config.yaml`-কে প্রাধান্য দেওয়া হয়; একটি এক্সপ্লিসিট ফ্ল্যাগ বা এনভায়রনমেন্ট ওভাররাইড তখনও জেতে।
+API হলো `http://localhost:3111`, লাইভ ভিউয়ার `http://localhost:3113`। ডিফল্টভাবে দুটোই loopback-এ চলে। কনফিগারেশন থাকে `~/.agentmemory/.env`-এ। [ডেটা স্টোরেজ](#data-storage).
তারপর প্রমাণ করুন রিকল কাজ করছে এবং আপনার এজেন্টকে তার স্কিল দিন:
@@ -127,14 +130,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-`agentmemory connect <agent>`-এর মাধ্যমে যেকোনো সময় আরও এজেন্ট ওয়্যার করুন — [Works with every agent](#works-with-every-agent)-এ ২০টি অ্যাডাপ্টার তালিকাভুক্ত আছে। সম্পূর্ণ কমান্ড রেফারেন্স [Quick Start](#quick-start)-এ।
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-সবচেয়ে সহজ পথ WSL2। নেটিভ Windows ইঞ্জিন সেটআপের জন্য পিন করা v0.22.1 ZIP ডাউনলোড করে `iii.exe` ম্যানুয়ালি এক্সট্র্যাক্ট করতে হয়; CLI এটি অটো-এক্সট্র্যাক্ট করে না। Docker Desktop-ও সাপোর্টেড। স্টেপ-বাই-স্টেপের জন্য [Windows notes](#windows) দেখুন।
-
-</details>
+`agentmemory connect <agent>` দিয়ে আরও এজেন্ট যুক্ত করুন। [সমর্থিত ইন্টিগ্রেশন](#works-with-every-agent) ও [দৈনন্দিন কমান্ড](#everyday-commands) দেখুন।
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx প্রতি ভার্সন অনুযায়ী ক্যাশ
</details>
-<details>
-<summary><strong>নিজের iii engine ইতিমধ্যে চলছে</strong></summary>
-
-agentmemory iii-engine v0.22.1 পিন করে এবং অন্য ভার্সনের সাথে অ্যাটাচ করবে না (ওয়ার্কার অন্য ইঞ্জিনের প্রোটোকল বলতে পারে না)। অন্য ইঞ্জিনটি থামান, তারপর `npx -y @agentmemory/agentmemory@latest` চালান। এটি পিন করা v0.22.1 `~/.agentmemory/bin`-এ ইনস্টল ও রান করে, আপনার নিজের `iii` অক্ষতই রাখে।
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory এমন যেকোনো এজেন্টের সাথে
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>নেটিভ প্লাগইন + 7 হুক + MCP</sub>
+<sub>নেটিভ প্লাগইন + lifecycle hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory এমন যেকোনো এজেন্টের সাথে
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>নেটিভ প্লাগইন + MCP</sub>
+<sub>নেটিভ recall + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory এমন যেকোনো এজেন্টের সাথে
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP সার্ভার</sub>
+<sub>নেটিভ capture + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory এমন যেকোনো এজেন্টের সাথে
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>নেটিভ recall + capture + skills + ঐচ্ছিক MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ agentmemory এমন যেকোনো এজেন্টের সাথে
---
-আপনি প্রতি সেশনে একই আর্কিটেকচার ব্যাখ্যা করেন। আপনি একই বাগ আবার খুঁজে পান। আপনি একই পছন্দগুলো পুনরায় শেখান। বিল্ট-ইন মেমরি (CLAUDE.md, .cursorrules) ২০০ লাইনে আটকে যায় এবং বাসি হয়ে যায়। agentmemory এটা ঠিক করে। এটি নিঃশব্দে আপনার এজেন্ট যা করে তা ক্যাপচার করে, সার্চযোগ্য মেমরিতে কম্প্রেস করে, এবং পরের সেশন শুরু হলে সঠিক কনটেক্সট ইনজেক্ট করে। একটি কমান্ড। সব এজেন্টে কাজ করে।
+<a id="data-storage"></a>
-**কী বদলে যায়:** সেশন ১-এ আপনি JWT auth সেটআপ করলেন। সেশন ২-এ আপনি রেট লিমিটিং চাইলেন। এজেন্ট আগে থেকেই জানে আপনার auth `src/middleware/auth.ts`-এ jose middleware ব্যবহার করে, আপনার টেস্ট টোকেন ভ্যালিডেশন কভার করে, এবং আপনি Edge কম্প্যাটিবিলিটির জন্য jsonwebtoken-এর বদলে jose বেছে নিয়েছিলেন — আর কোনো পুনরায় ব্যাখ্যা বা কপি-পেস্ট ছাড়াই।
+### ডেটা স্টোরেজ
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+মেমরি ডিফল্টভাবে রিপোজিটরির বাইরে থাকে। ইনস্ট্যান্স 0 বিদ্যমান `./data/state_store.db` পুনরায় ব্যবহার করে। `--data-dir <path>` বা `AGENTMEMORY_DATA_DIR` দিয়ে অবস্থান বেছে নিন এবং রিস্টার্ট ও আপগ্রেডে একই ডিরেক্টরি রাখুন।
-ডিফল্টভাবে, 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 <path>` পাস করুন বা `AGENTMEMORY_DATA_DIR` সেট করুন; এই দুটি এক্সপ্লিসিট সেটিংই লিগ্যাসি ডিসকভারির উপর প্রাধান্য পায়:
+| প্ল্যাটফর্ম | ডেটা ডিরেক্টরি |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-নেটিভ এবং Docker লঞ্চ একই রিজলভড হোস্ট ডিরেক্টরি ব্যবহার করে; Docker এটি `/data`-এ বাইন্ড-মাউন্ট করে। `--instance 1` রিজলভড ডিরেক্টরিতে `instance-1` যুক্ত করে এবং আলাদা ডিফল্ট পোর্ট চতুষ্টয় `3211/3212/3213/49234` বেছে নেয়।
+`--instance 1` ব্যবহার করে `instance-1` সাবডিরেক্টরি, API পোর্ট `3211` এবং ভিউয়ার পোর্ট `3213`। Redis ও ব্যাকএন্ড স্থানান্তরের জন্য [স্টোরেজ ও ব্যাকআপ](../docs/reliability/state-storage.md) দেখুন।
সর্বশেষ রিলিজ নোট: [CHANGELOG.md](../CHANGELOG.md)।
@@ -476,7 +473,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>এক্সটার্নাল ডিপেন্ডেন্সি</strong></td>
-<td>নেই (SQLite + iii-engine)</td>
+<td>আলাদা ডেটাবেস সেবা দরকার নেই</td>
<td>Qdrant / pgvector</td>
<td>Postgres + ভেক্টর DB</td>
<td>একাধিক</td>
@@ -550,14 +547,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | টেম্পোরাল নলেজ গ্রাফ; সবচেয়ে শক্তিশালী প্রকাশিত টেম্পোরাল-কোয়েরি ফল (LongMemEval 63.8%), কিন্তু গ্রাফ অ্যাসিনক্রোনাসভাবে তৈরি হয় তাই নতুন তথ্য দেরিতে আসতে পারে |
| Cognee | 30K | ডকুমেন্ট-থেকে-নলেজ-গ্রাফ ইনজেশন, কেবল Python, সেশন ক্যাপচারের বদলে স্ট্রাকচারড এনটিটি এক্সট্র্যাকশনের জন্য তৈরি |
-এদের কেউই কোডিং-এজেন্ট হুক থেকে অটো-ক্যাপচার করে না, লোকাল-ফার্স্ট ভিউয়ার দেয় না, বা কিলেস চলে না — যে কম্বিনেশনের উপর agentmemory তৈরি।
+AgentMemory সেশন ক্যাপচার, অনুসন্ধানযোগ্য প্রজেক্ট ইতিহাস ও লোকাল ভিউয়ার একসঙ্গে দেয়; প্রথমবার থেকেই কী ছাড়া ব্যবহার করা যায়।
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="কুইক স্টার্ট" height="32" /></picture></h2>
-কম্প্যাটিবিলিটি: এই রিলিজ `iii-sdk` 0.22.1 টার্গেট করে এবং iii-engine v0.22.1 পিন করে।
-
### 30 সেকেন্ডে ট্রাই করুন
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
মেমরি লাইভ তৈরি হওয়া দেখতে `http://localhost:3113` খুলুন।
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### ফ্রেশ ইনস্টল এবং রিস্টার্ট পারসিস্টেন্স যাচাই করুন
-সার্ভার চলা অবস্থায়, REST, health, ভিউয়ার, এবং iii-ব্যাকড রানটাইম স্ট্যাটাস যাচাই করুন:
+সার্ভার চালু রেখে স্বাস্থ্য, ভিউয়ার ও অবস্থা পরীক্ষা করুন।
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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-র স্বাস্থ্য এবং অ্যাক্টিভ প্রোভাইডার/এমবেডিং মোড নিশ্চিত করে। একটি প্রোব সেভ করুন এবং নিশ্চিত করুন এটি সার্চযোগ্য:
+`status` সার্ভারের স্বাস্থ্য, প্রোভাইডার, embedding mode, capture delivery ও recovery দেখায়। সুরক্ষিত REST অনুরোধে সার্ভারের secret দরকার। নির্ধারিত `AGENTMEMORY_SECRET` ব্যবহার করুন; না থাকলে তৈরি হওয়া লোকাল secret পড়ুন।
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
তারপর `npx -y @agentmemory/agentmemory@latest stop` চালান, Terminal 1-এ ক্যানোনিকাল কমান্ড আবার শুরু করুন, `/agentmemory/livez`-এর জন্য অপেক্ষা করুন, এবং সার্চটি আবার করুন। প্রোবটি তখনও রিটার্ন হতে হবে। কাস্টম `--data-dir` বেছে নিয়ে থাকলে, রিস্টার্টেও একই ডিরেক্টরি পাস করুন।
+<a id="everyday-commands"></a>
+
### দৈনন্দিন কমান্ড
ইনস্টল ও সেটআপ উপরে [Install](#install)-এ আছে (প্রথম রান আপনাকে গাইড করে)। দৈনন্দিন ব্যবহারের জন্য:
@@ -604,7 +608,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-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 ফাংশনের মধ্য দিয়ে যায়, কোনো সাইড-চ্যানেল সার্ভার ছাড়াই। প্রতিটি ইমপোর্ট করা ট্রান্সক্রিপ্ট সার্চের জন্য ইনডেক্সড হয়, `import` অরিজিন চ্যানেলে স্ট্যাম্পড হয়, এবং একটি সেশন ক্রিস্টাল ও লেসনের জন্য মাইনড হয়।
+ইমপোর্ট করা সেশন Replay-তে নেটিভ সেশনের পাশে দেখা যায়, অনুসন্ধানের জন্য ইনডেক্স হয় এবং origin channel `import` পায়। সেশন প্রসেসিং থেকে crystal ও lesson-ও তৈরি হতে পারে।
> **`import-jsonl`-কে আপনার মূল ক্যাপচার পাথ হিসেবে ব্যবহার করলে এটা জেনে রাখুন:** Claude Code-এর `cleanupPeriodDays` (`~/.claude/settings.json`-এ, ডিফল্ট **30**) সেই উইন্ডোর চেয়ে পুরোনো JSONL ট্রান্সক্রিপ্ট `~/.claude/projects/` থেকে অটো-ডিলিট করে দেয়। মাস-কয়েক পুরোনো Claude Code হিস্ট্রির উপর যদি আপনি agentmemory ফ্রেশ ইনস্টল করেন, তাহলে 30 দিনের চেয়ে পুরোনো যা কিছু প্রথম ইমপোর্টের আগেই হারিয়ে গেছে। এক্ষেত্রে cron-এ `import-jsonl` চালান, `cleanupPeriodDays` বাড়িয়ে দিন, বা অটো-ক্যাপচার হুক ওয়্যার করুন (ডিফল্ট প্লাগইন ইনস্টল পাথ) যাতে সেশন লাইভ থাকা অবস্থায় প্রতিটি টার্ন agentmemory-তে পৌঁছে যায় এবং JSONL ক্লিনআপ আর গুরুত্বপূর্ণ না থাকে।
@@ -635,14 +642,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
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`)।
+এটি লোকাল রানটাইম আপডেট করে এবং বর্তমান কাজের ডিরেক্টরির JavaScript ডিপেন্ডেন্সিও আপডেট করতে পারে। ডেটার ব্যাকআপ নিন এবং বিদ্যমান ইনস্টলেশন আপডেটের আগে [আপগ্রেড গাইড](../docs/upgrades/iii-0.25.md) পড়ুন।
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### প্লাগইন ইনস্টল ছাড়া Claude Code (MCP-স্ট্যান্ডঅ্যালোন পাথ)
@@ -703,6 +708,26 @@ 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 সার্ভারটি নিয়ে নেয়। পূর্ণ হুক/স্কিল অভিজ্ঞতা চাইলে প্লাগইনটিও ইনস্টল করুন।
+### Cursor
+
+`agentmemory connect cursor` দিয়ে MCP সেট করুন। **Settings → Plugins → Add marketplace** থেকে `.cursor-plugin/plugin.json` থাকা checkout বেছে agentmemory চালু করে reload করুন। প্লাগইন lifecycle capture, workspace শনাক্তকরণ, skills ও MCP দেয়। একই ঘটনা দুবার রেকর্ড এড়াতে প্লাগইন hooks বা `~/.cursor/hooks.json`-এর ম্যানুয়াল hooks-এর একটি ব্যবহার করুন।
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+আপনার হোস্টের কমান্ড বেছে নিন। Pi ও OMP নেটিভ recall/capture, অফলাইন replay এবং 17 skills ইনস্টল করে; `--with-mcp` সব টুল যোগ করে। Pi-তে `/reload` চালান অথবা OMP রিস্টার্ট করুন, তারপর `/agentmemory-status` দেখুন। DSH MCP ও সঙ্গে থাকা capture plugin ইনস্টল করে; সংযোগের পরে রিস্টার্ট করুন।
+
+Pi-এর জন্য ইনস্টলযোগ্য `@agentmemory/pi` প্যাকেজও আছে। লোকাল ইনস্টল ও npm-এ প্রাপ্যতার জন্য [Pi গাইড](../integrations/pi/) দেখুন। প্রতিটি হোস্টে একটি ইনস্টল পদ্ধতি ব্যবহার করুন।
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (এই প্রম্পট পেস্ট করুন)</b></summary>
@@ -749,6 +774,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### অন্য এজেন্ট
মেমরি সার্ভার শুরু করুন: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
এটি `agentmemory connect <agent>`-এর সাথে **পরিপূরক**:
-- `agentmemory connect <agent>` MCP সার্ভার কনফিগ লেখে যাতে টুলগুলো উপলব্ধ হয়।
-- `npx skills add rohitg00/agentmemory` স্কিলগুলো ইনস্টল করে যাতে এজেন্ট জানে কখন এগুলো কল করতে হবে।
+Hermes, OpenClaw, Pi ও Oh My Pi কানেক্টর ডিফল্টভাবে নেটিভ ইন্টিগ্রেশন ও skills ইনস্টল করে; MCP যোগ করতে `--with-mcp` ব্যবহার করুন। অন্য হোস্টে `npx skills add rohitg00/agentmemory` দিয়ে skills ইনস্টল করুন।
স্কিল CLI এখনও যে কয়েকটা এজেন্ট কভার করে না (Zed v1.3.x এবং তার নিচে), সেগুলোতে 17টি SKILL.md ফাইল নিজেই এজেন্টের নেটিভ স্কিল ডিরেক্টরিতে রাখুন; একই ফরম্যাট সবখানে কাজ করে।
@@ -790,7 +816,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| এজেন্ট | কনফিগ ফাইল | নোট |
|---|---|---|
| **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 প্রিন্ট-মোড প্রম্পটগুলো সেশন শেষে সেশন ট্রান্সক্রিপ্ট থেকে ব্যাকফিল করা হয়। |
+| **Cursor (পূর্ণ প্লাগইন)** | `.cursor-plugin/` | Cursor Marketplace অথবা Settings → Plugins → লোকাল checkout দিয়ে ইনস্টল করুন। ছোট adapter শেয়ার করা `plugin/scripts/*.mjs` চালিয়ে lifecycle hooks নিবন্ধন করে এবং skills ও MCP দেয়। এটি Cursor ঠিকভাবে না জানানো workspace শনাক্ত করে। [Cursor](#cursor) দেখুন। Cursor IDE ও `cursor-agent` 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` দিয়ে যাচাই করুন। |
@@ -804,7 +830,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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`)। |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · নেটিভ recall + capture + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · নেটিভ recall + capture + skills. [Oh My Pi](../integrations/omp/) |
| **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)। |
@@ -812,39 +839,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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`-এর জন্য (অবজেক্ট না) অ্যারে ফর্ম ব্যবহার করে। |
+| **Continue.dev** | `~/.continue/config.yaml` (পছন্দনীয়) বা `config.json` (লেগ্যাসি) | `agentmemory connect continue` কনফিগারেশন না থাকলে `config.yaml` তৈরি করে অথবা বর্তমান `config.json` আপডেট করে। বিদ্যমান YAML-এর comment ও anchor বাঁচাতে সেটি না বদলে `mcpServers:`-এর নিচে বসানোর block দেখায়। Continue-এর `mcpServers` একটি array। |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` `context_servers`-এর নিচে লেখে (Zed-র কি, `mcpServers` নয়)। রিমোট MCP সার্ভার এর বদলে `{"url": "..."}` দিয়েও ওয়্যার করা যায়। |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` স্ট্যান্ডার্ড `mcpServers` ব্লক লেখে। প্রজেক্ট-স্কোপড ওভাররাইড যায় `<repo>/.factory/mcp.json`-এ। নেটিভ অটো-ক্যাপচারের জন্য `--with-hooks` পাস করুন। |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` MCP টুল চালু করে। AgentMemory-এর সঙ্গে থাকা নেটিভ ক্যাপচার প্লাগইন চালু করতে `--with-hooks` যোগ করুন। আলাদা প্লাগইন প্যাকেজ প্রয়োজন নেই। [DSH](../docs/dsh.md). |
| **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"}'`। |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **যেকোনো এজেন্ট (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 তখনও উপলব্ধ।
+যেকোনো ভাষা থেকে [REST API](#api) বা এজেন্ট থেকে [MCP টুল](#mcp-server) ব্যবহার করুন। REST-এ JSON ও Bearer প্রমাণীকরণ লাগে; [সংরক্ষণ ও খোঁজার উদাহরণ](#validate-a-fresh-install-and-restart-persistence) দেখুন। সরাসরি রানটাইম সংযোগের জন্য [Python উদাহরণ](../examples/python/) আছে।
### সোর্স থেকে
@@ -853,83 +860,33 @@ 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=<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)।
+`npm start` ইনস্টল করা CLI-এর মতো একই লোকাল সার্ভার চালু করে। প্রয়োজনীয়তা [ইনস্টল](#install)-এ আছে; API ও ভিউয়ার `127.0.0.1`-এ চলে।
### Windows
-agentmemory Windows 10/11-এ চলে, কিন্তু কেবল Node.js প্যাকেজটাই পর্যাপ্ত নয়; ব্যাকগ্রাউন্ড প্রসেস হিসেবে পিন করা iii-engine v0.22.1 রানটাইমও প্রয়োজন। CLI Windows ZIP অটো-এক্সট্র্যাক্ট করে না, তাই নেটিভ Windows ইউজারদের `iii.exe` ম্যানুয়ালি ইনস্টল করতে হবে, WSL2 ব্যবহার করতে হবে, বা Docker Desktop বেছে নিতে হবে।
+agentmemory Windows 10/11-এ চলে। WSL2 Linux-এর পথ অনুসরণ করে এবং পিন করা engine স্বয়ংক্রিয়ভাবে ইনস্টল করতে পারে। নেটিভ Windows-এর জন্য পিন করা iii-engine 0.25.0 বাইনারি ম্যানুয়ালি ইনস্টল করতে হবে; [iii 0.25.0 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) থেকে মিলে যাওয়া archive ডাউনলোড করে checksum যাচাই করুন, তারপর `iii.exe` `PATH`-এ রাখুন (যেমন `%USERPROFILE%\.local\bin\iii.exe`)। CLI Windows ZIP স্বয়ংক্রিয়ভাবে extract করে না।
-নেটিভ Windows অটোমেটেড MCP ওয়্যারিং কেবল `agentmemory connect copilot-cli` সাপোর্ট করে। Claude Code, Codex, Cursor, এবং অন্য প্রতিটি নেটিভ Windows এজেন্টের জন্য, [Other agents](#other-agents)-এর ম্যানুয়াল MCP ব্লকটি সেই এজেন্টের Windows কনফিগে কপি করুন। WSL-এ `connect` চালানো তখনই যথাযথ যখন টার্গেট এজেন্টও সেই একই WSL এনভায়রনমেন্টে ইনস্টল করা আছে; এটি Windows-হোস্টেড কোনো এজেন্টের কনফিগ এডিট করে না।
+নেটিভ Windows-এ স্বয়ংক্রিয় MCP wiring কেবল `agentmemory connect copilot-cli` সাপোর্ট করে। অন্য নেটিভ Windows এজেন্টের জন্য [Other agents](#other-agents) থেকে ম্যানুয়াল MCP block ব্যবহার করুন। লক্ষ্য এজেন্টটি একই WSL পরিবেশে ইনস্টল থাকলেই কেবল WSL-এর ভিতরে `connect` চালান।
-**অপশন 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 প্রয়োজন না হলে, ইঞ্জিনটি সম্পূর্ণ স্কিপ করুন:
+**শুধু Standalone MCP (engine ছাড়া)।** আপনার কেবল MCP tools দরকার এবং REST API, viewer, বা runtime service দরকার না হলে:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` ব্যবহার করুন |
-| 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`-এ নিয়ে আসে।
+`agentmemory doctor` চালান অথবা `--verbose` দিয়ে রিস্টার্ট করুন। ডিফল্ট পোর্ট ব্যস্ত থাকলে `--port <N>` বা `--instance <N>` ব্যবহার করুন। সামঞ্জস্য ও পুনরুদ্ধারের জন্য [আপগ্রেড গাইড](../docs/upgrades/iii-0.25.md) দেখুন।
---
<h2 id="deploy">Deploy</h2>
-ম্যানেজড হোস্টের জন্য ওয়ান-ক্লিক টেমপ্লেট। প্রতিটিতে একটি সেলফ-কনটেইনড 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`-এ প্রিভিলেজ নামিয়ে আনে।
+Docker Compose অথবা নিচের প্ল্যাটফর্ম টেমপ্লেট দিয়ে নিজে হোস্ট করুন। মেমরি ও পরিচয়প্রমাণ `/data` ভলিউমে থাকে। আপগ্রেডের সময় ব্যাকআপ নিয়ে একই ভলিউম ব্যবহার করুন। প্রমাণীকরণ, নেটওয়ার্ক ও স্থানান্তরের জন্য [ডিপ্লয়মেন্ট গাইড](../deploy/README.md) দেখুন।
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Render-এর ওয়ান-ক্লিক ডিপ্লয় বাটনের জন্য রিপোজিটরি রুটে `render.yaml` লাগে, যা আমরা ইচ্ছাকৃতভাবে পরিষ্কার রাখি। ম্যানুয়ালি রেপোর ভেতরের ব্লুপ্রিন্টের দিকে পয়েন্ট করতে [`deploy/render/`](.././deploy/render/README.md)-এ ডকুমেন্টেড Render Blueprint ফ্লো ব্যবহার করুন।
@@ -946,28 +903,26 @@ Render-এর ওয়ান-ক্লিক ডিপ্লয় বাটন
- [`deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted)-এর
মাধ্যমে নিজের VPS-এ সেলফ-হোস্টেড; একই Docker Compose স্ট্যাক, হোস্ট ও ডেটা আপনার নিজের।
-কেবল `3111` পোর্টই পাবলিশড। কন্টেইনারের ভেতরে `3113`-এর ভিউয়ার
-লুপব্যাকেই বাঁধা থাকে; প্রতিটি টেমপ্লেটের README সেটায় পৌঁছানোর
-SSH-টানেল প্যাটার্ন ডকুমেন্ট করে।
+REST পোর্ট `3111` ও ভিউয়ার `3113` ব্যবহার করে। ব্যক্তিগত রাখুন অথবা প্রমাণীকরণ ও TLS দিয়ে সুরক্ষিত করুন। প্ল্যাটফর্মভেদে প্রবেশের সেটিং ও [পুরোনো Docker স্থানান্তর](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ডিপ্লয়মেন্ট গাইডে আছে।
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="কেন agentmemory" height="32" /></picture></h2>
-সেশন শেষ হলে প্রতিটি কোডিং এজেন্ট সবকিছু ভুলে যায়, এবং প্রতিটি নতুন সেশন শুরু হয় আপনার স্ট্যাক আবার ব্যাখ্যা করা দিয়ে। agentmemory ব্যাকগ্রাউন্ডে চলে এবং এই স্টেপটা বাদ দিয়ে দেয়।
+প্রজেক্টের জ্ঞান চ্যাট ও নির্দেশনার ফাইলে ছড়িয়ে থাকে। 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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### বিল্ট-ইন এজেন্ট মেমরির তুলনায়
@@ -976,7 +931,7 @@ Session 2: "Now add rate limiting"
| | বিল্ট-ইন (CLAUDE.md) | agentmemory |
|---|---|---|
-| স্কেল | 200-লাইন ক্যাপ | আনলিমিটেড |
+| রক্ষণাবেক্ষণ | হাতে সাজানো নির্দেশনা | ইনডেক্স করা সেশন ইতিহাস ও মেমরি |
| সার্চ | সবকিছু কনটেক্সটে লোড করে | BM25 + vector + graph (কেবল top-K) |
| টোকেন খরচ | 240 অবজারভেশনে 22K+ | ~1,900 টোকেন (92% কম) |
| ক্রস-এজেন্ট | প্রতি-এজেন্ট ফাইল | MCP + REST (যেকোনো এজেন্ট) |
@@ -1002,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-স্তর মেমরি কনসোলিডেশন
@@ -1026,6 +981,8 @@ SessionStart hook fires
### কী ক্যাপচার হয়
+নিচের টেবিল Claude Code-এর hooks দেখায়। অন্য ইন্টিগ্রেশন নিজ নিজ হোস্টের দেওয়া ইভেন্ট ক্যাপচার করে। শেয়ার করা hooks দিয়ে স্বয়ংক্রিয় প্রসঙ্গ যোগ করতে `AGENTMEMORY_INJECT_CONTEXT=true` চালু করতে হবে।
+
| হুক | যা ক্যাপচার করে |
|------|----------|
| `SessionStart` | প্রজেক্ট পাথ, সেশন ID |
@@ -1042,7 +999,7 @@ SessionStart hook fires
| সক্ষমতা | বর্ণনা |
|---|---|
-| **অটোমেটিক ক্যাপচার** | হুকের মাধ্যমে প্রতিটি টুল ব্যবহার রেকর্ড হয়, কোনো ম্যানুয়াল পরিশ্রম ছাড়াই |
+| **অটোমেটিক ক্যাপচার** | নেটিভ ইন্টিগ্রেশন সমর্থিত সেশন ও টুল ইভেন্ট রেকর্ড করে |
| **সিম্যান্টিক সার্চ** | RRF ফিউশন সহ BM25 + vector + নলেজ গ্রাফ |
| **মেমরি ইভোলিউশন** | ভার্সনিং, সুপারসেশন, রিলেশনশিপ গ্রাফ |
| **রিকল হাইজিন** | রিপ্লেসড মেমরি ভার্সন সার্চ ইনডেক্স থেকে বাদ পড়ে; KV-এর ভার্সন চেইন সম্পূর্ণ ইতিহাস রাখে |
@@ -1243,7 +1200,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="রিয়েল-টাইম ভিউয়ার" height="32" /></picture></h2>
-`3113` পোর্টে অটো-স্টার্ট হয়। ভিউয়ার কানেক্ট হওয়ার সময় একটি স্ন্যাপশট লোড করে (`GET /agentmemory/viewer/snapshot`) এবং তারপর লাইভ স্ট্রিম ইভেন্ট অ্যাপ্লাই করে: নতুন মেমরি, লেসন, অবজারভেশন, অডিট এন্ট্রি, গ্রাফ পরিবর্তন, এবং হেলথ আপডেট পোলিং বা পেজ রিলোড ছাড়াই দেখা যায়। অন্য একমাত্র রিকোয়েস্টগুলো হলো আপনি যে অ্যাকশনে ক্লিক করেন, "load more" পেজ, এবং সার্চ। স্ট্রিম বিচ্ছিন্ন হলে, ভিউয়ার দেখায় তার সংখ্যাগুলো কত পুরোনো, ব্যাকঅফ দিয়ে রিকানেক্ট করে এবং একটি স্ন্যাপশট থেকে রিসিঙ্ক করে।
+`3113` পোর্টে viewer স্বয়ংক্রিয়ভাবে চালু হয়। সংযোগের সময় এটি একটি snapshot লোড করে (`GET /agentmemory/viewer/snapshot`), তারপর REST worker-এর `/agentmemory/viewer/events`-এ SSE দিয়ে live event প্রয়োগ করে: নতুন memory, lesson, observation, audit entry, graph পরিবর্তন ও health update polling বা পেজ reload ছাড়াই দেখা যায়। বাকি request কেবল আপনার ক্লিক করা action, "load more" পেজ ও search। stream বিচ্ছিন্ন হলে viewer ডেটার বয়স দেখায়, backoff দিয়ে পুনরায় সংযোগ করে এবং একটি snapshot থেকে resync করে।
- **চারটি গ্রুপে 12টি ট্যাব**, লাইভ কাউন্ট, ডিপ লিংক (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#health/consolidation`), কিবোর্ড শর্টকাট এবং মোবাইল মেনু সহ।
- **Memories:** সার্ভার-সাইড সার্চ, প্রজেক্ট, এজেন্ট ও টাইপ অনুযায়ী ফিল্টার, ভার্সন চেইন ও একটি word diff সহ একটি ডিটেল প্যানেল, প্রোভেন্যান্স লিংক, id-র জন্য কপি বাটন, MCP কল এবং একটি curl কমান্ড, এডিট (একটি নতুন ভার্সন), কনফার্মেশন সহ forget, বাল্ক forget, এবং JSON এক্সপোর্ট।
@@ -1256,188 +1213,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
open http://localhost:3113
```
-ভিউয়ার সার্ভার ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে এবং REST API-তে রিকোয়েস্ট ফরওয়ার্ড করার সময় সার্ভার সিক্রেট যুক্ত করে, তাই এর কোনো সেটআপ লাগে না। REST-সার্ভড `/agentmemory/viewer` এন্ডপয়েন্ট নরমাল bearer-token নিয়ম মেনে চলে এবং টোকেন ছাড়া ব্রাউজারগুলোকে ভিউয়ার পোর্টে রিডাইরেক্ট করে। CSP হেডার প্রতি-রেসপন্স script nonce ব্যবহার করে এবং ইনলাইন হ্যান্ডলার অ্যাট্রিবিউট বন্ধ রাখে (`script-src-attr 'none'`)।
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-`:3113`-এর ভিউয়ার দেখায় আপনার এজেন্ট কী **মনে রেখেছে**। [iii console](https://iii.dev/docs/console) দেখায় আপনার এজেন্ট কী **করেছে**: প্রতিটি মেমরি অপারেশন একটি OpenTelemetry ট্রেস হিসেবে, প্রতিটি KV এন্ট্রি এডিটযোগ্য, প্রতিটি ফাংশন ইনভোকেবল, প্রতিটি স্ট্রিম ট্যাপযোগ্য। একই মেমরির উপর দুটি জানালা: একটি প্রোডাক্ট-শেপড, একটি ইঞ্জিন-শেপড।
-
-একটি `memory_smart_search` ফায়ার হতে দেখুন এবং BM25 স্ক্যান → embedding lookup → RRF ফিউশন → reranker-কে একটি waterfall হিসেবে দেখুন। KV ব্রাউজারে একটি আটকে থাকা কনসোলিডেশন টাইমার এডিট করুন। একটি টুইকড পেলোড দিয়ে `PostToolUse` হুক রিপ্লে করুন। WebSocket স্ট্রিম পিন করুন এবং অবজারভেশনগুলো লাইভ ল্যান্ড করতে দেখুন।
-
-agentmemory এটা ফ্রিতে দেয় কারণ প্রতিটি ফাংশন কল ও ট্রিগার iii-এর মধ্য দিয়ে ফায়ার হয়; কিছুই কাস্টম নয়, ইন্সট্রুমেন্ট করার কিছু নেই।
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console-র Workers পেজ: লাইভ ফাংশন কাউন্ট ও রানটাইম মেটাডেটা সহ agentmemory ইনস্ট্যান্স-সহ কানেক্টেড ওয়ার্কার" width="720" />
- <br/>
- <em>Workers পেজ: প্রতিটি কানেক্টেড ওয়ার্কার, agentmemory নিজেও সহ, PID, ফাংশন কাউন্ট, রানটাইম, এবং last-seen সহ।</em>
-</p>
-
-**আগে থেকেই ইনস্টলড।** কনসোলটি পিন করা `iii` 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`) প্রতিটি ওয়ার্কার, ট্রিগার, এবং স্ট্রিমের ইন্টারঅ্যাক্টিভ আর্কিটেকচার গ্রাফ। |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="প্রতি-স্প্যান ডিউরেশন দেখানো iii console trace waterfall ভিউ" width="720" />
- <br/>
- <em>Traces: প্রতিটি মেমরি অপারেশনের জন্য waterfall / flame / service breakdown।</em>
-</p>
-
-**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`-এই (ডিফল্ট) বাঁধা রাখুন এবং কখনো পাবলিকলি এক্সপোজ করবেন না।
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="iii দ্বারা চালিত" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) ফিক্সড, তাই একই ডেটাবেসের দিকে পয়েন্ট করা দুটি 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 <name>` |
-
-**250 সোর্স ফাইল · ~55,000 LOC · 3,400+ টেস্ট · 324 ফাংশন · 67 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
+ভিউয়ার সার্ভার ডিফল্টভাবে `127.0.0.1`-এ bind করে এবং REST API-তে request forward করার সময় server secret যুক্ত করে। non-loopback bind-এ HTML shell public থাকে, কিন্তু প্রতিটি proxy request-এর জন্য bearer token লাগে; viewer সেটি চায় এবং session storage-এ রাখে। viewer প্রকাশ করার আগে নির্দিষ্ট host/origin allowlist এবং TLS কনফিগার করুন। REST-এ পরিবেশিত `/agentmemory/viewer` endpoint স্বাভাবিক bearer-token নিয়ম মেনে চলে এবং token ছাড়া browser-কে viewer port-এ redirect করে। CSP header প্রতি response-এ script nonce ব্যবহার করে এবং inline handler attribute বন্ধ করে (`script-src-attr 'none'`)।
---
@@ -1458,6 +1234,8 @@ agentmemory আপনার এনভায়রনমেন্ট থেকে
| **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-হুক রিকার্শন তৈরি করত, তাই এটা আর ডিফল্ট নয়। |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### লোকাল মডেল (Ollama / LM Studio / vLLM)
agentmemory যেকোনো OpenAI-API-কম্প্যাটিবল সার্ভারের সাথে কথা বলে, তাই `/v1/chat/completions` এক্সপোজ করা যা কিছুই কোনো কোড পরিবর্তন ছাড়া কাজ করে। কোনো পেইড কী নেই, কোনো ক্লাউড নেই, কোনো রেট লিমিট নেই; সম্পূর্ণভাবে আপনার হার্ডওয়্যারে চলে।
@@ -1507,24 +1285,9 @@ Qwen 3 মডেল ডিফল্টভাবে থিংক করে এব
### কস্ট-অ্যাওয়্যার মডেল বাছাই
-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.) সারিগুলো একই টোকেন মিক্সকে প্রতিটি মডেলের লিস্ট প্রাইস দিয়ে স্কেল করে।
+কী ছাড়াই ক্যাপচার ও কীওয়ার্ড অনুসন্ধান শুরু করা যায়। `EMBEDDING_PROVIDER=local` প্রথম মডেল ডাউনলোডের পরে ডিভাইসে অর্থভিত্তিক অনুসন্ধান দেয়। LLM কম্প্রেশনে প্রোভাইডার ও `AGENTMEMORY_AUTO_COMPRESS=true` লাগে; প্রতি পর্যবেক্ষণে অনুরোধ হতে পারে, তাই বর্তমান মূল্য দেখুন।
-`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/)।
+`agentmemory status` / http://localhost:3113
### মাল্টি-এজেন্ট মেমরি (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1554,57 +1317,42 @@ SDK / REST লেয়ারে প্রতি-কল ওভাররাইড
### পোর্ট
-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 <N>` REST অ্যাঙ্কর বদলে দেয় এবং স্ট্রিম `N+1`, ভিউয়ার `N+2`, এবং ইঞ্জিন WebSocket `N+46023` ডিরাইভ করে, কেবল যেখানে উপরের সংশ্লিষ্ট এক্সপ্লিসিট পোর্ট বা URL আনসেট আছে। এটা কোনো আইসোলেটেড লাইফসাইকেল নেমস্পেস তৈরি করে না। দ্বিতীয় ডেমনের জন্য `--instance 1` ব্যবহার করুন; এটা অ্যাঙ্কর 3211 ব্যবহার করে, ডিফল্টভাবে `3211/3212/3213/49234`, এবং একটি আলাদা `instance-1` ডেটা ও লাইফসাইকেল ডিরেক্টরি পায়। ইনস্ট্যান্স 1 থেকে 50 একই প্যাটার্ন অনুসরণ করে।
+API ও ভিউয়ার ডিফল্টভাবে loopback-এ চলে।
-পিন করা ইঞ্জিন `--no-update-check` দিয়ে শুরু হয় (বুটে GitHub-এর বিরুদ্ধে কোনো আপডেট বা সিকিউরিটি-অ্যাডভাইজরি লুকআপ নেই) এবং iii-র অ্যানোনিমাস ইউসেজ টেলিমেট্রি বন্ধ রেখে: agentmemory যে ইঞ্জিন স্পন করে তার জন্য `III_TELEMETRY_ENABLED=false` সেট করে যদি না আপনি নিজে ভ্যারিয়েবলটি এক্সপোর্ট করেন, এবং বান্ডলড compose ফাইলও একই কাজ করে।
+| Port | API / ভিউয়ার | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | ভিউয়ার | `III_VIEWER_PORT` |
-একটি ক্র্যাশড রান শেষে পোর্টগুলো বাঁধা থেকে গেলে, বাসি প্রসেস ক্লিনআপ:
+`--port <N>` API পোর্ট নির্ধারণ করে; ভিউয়ার ডিফল্টভাবে `N+2` ব্যবহার করে। আলাদা ইনস্ট্যান্সের জন্য `--instance N` ব্যবহার করুন। ভেতরের listener ব্যক্তিগত রাখুন। দূরবর্তী প্রবেশ ও [পুরোনো Docker স্থানান্তর](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) নিয়ে ডিপ্লয়মেন্ট গাইড দেখুন।
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage backend: file (ডিফল্ট) বনাম Redis
-গ্রেসফুল নেটিভ শাটডাউনে `agentmemory stop` ওয়ার্কার এবং ইঞ্জিন পিডফাইল দুটোই পরিষ্কারভাবে রিপ করে। Docker মোডে এটা নেটিভ ওয়ার্কার ফ্লাশ করে, ঠিক ভ্যালিডেটেড ইঞ্জিন কন্টেইনারটি থামায়, এবং লসলেস রিস্টার্টের জন্য কন্টেইনার ও তার `/data` মাউন্ট দুটোই রক্ষা করে; পরের স্টার্ট সেই একই কন্টেইনার যাচাই করে পুনরায় শুরু করে। Docker-ব্যাকড আনইনস্টলের জন্য `agentmemory remove --keep-data` লাগে: এটা শেয়ার্ড agentmemory-ম্যানেজড ফাইল সরিয়ে দেয়, ভ্যালিডেটেড কন্টেইনার, তার ডেটা মাউন্ট, এবং সেগুলো রিকভার করতে প্রয়োজনীয় লাইফসাইকেল রেকর্ড রক্ষা করে। ডেস্ট্রাক্টিভ Docker ডেটা ডিলিশন ইচ্ছাকৃতভাবে ব্যাকআপের পর অপারেটরের হাতে ছেড়ে দেওয়া। `--force` পাস না করলে CLI Docker বা VM পোর্ট হোল্ডারদের (Docker backend, vpnkit, colima) নেটিভ ইঞ্জিন হিসেবে গ্রহণ বা সিগন্যাল করতেও অস্বীকার করে। উপরের ম্যানুয়াল ক্লিনআপ শুধু পোস্ট-ক্র্যাশ কেসের জন্য যেখানে কোনো পিডফাইলই বাকি নেই।
+আলাদা ডেটাবেস সেবা দরকার নেই. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. ব্যাকএন্ড বদলালে আগের মেমরি নিজে থেকে কপি হয় না। [ডেটা স্টোরেজ](../docs/reliability/state-storage.md).
### কনফিগ ফাইল
-প্রতিটি শেলে ভ্যারিয়েবল এক্সপোর্ট করার বদলে agentmemory-র রানটাইম কনফিগারেশন `~/.agentmemory/.env`-এ রাখুন। ভিউয়ার `export ANTHROPIC_API_KEY=...`-র মতো একটি সেটআপ হিন্ট দেখালে, `export` প্রিফিক্স ছাড়া `ANTHROPIC_API_KEY=...` হিসেবে এটা এই ফাইলে কপি করুন, তারপর agentmemory রিস্টার্ট করুন।
+প্রতিটি shell-এ variable export না করে agentmemory runtime config `~/.agentmemory/.env`-এ রাখুন। viewer `export ANTHROPIC_API_KEY=...`-এর মতো setup hint দেখালে, `export` prefix বাদ দিয়ে `ANTHROPIC_API_KEY=...` হিসেবে এই ফাইলে কপি করুন, তারপর agentmemory restart করুন। অন্য env-file path ব্যবহার করতে `AGENTMEMORY_ENV_FILE` সেট করুন।
-প্রসেস এনভায়রনমেন্ট ভ্যারিয়েবল তখনও কাজ করে এবং ফাইলের ভ্যালুর উপর প্রাধান্য পায়।
+Process environment variable-ও কাজ করে এবং ফাইলের মানের চেয়ে অগ্রাধিকার পায়। CLI-নির্মিত Worker Compose project `AGENTMEMORY_STATE_BACKEND` ও `AGENTMEMORY_REDIS_URL` থেকে Redis settings নিয়ে `state` worker-এ দেয়।
-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 সাবস্ক্রিপশন দিয়ে টেস্ট করতে, স্পষ্টভাবে অপ্ট-ইন করুন:
+API key-এর বদলে Claude Code Pro/Max subscription দিয়ে পরীক্ষা করতে স্পষ্টভাবে opt-in করুন:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
-LLM-লিখিত অবজারভেশন কম্প্রেশনের জন্য দুই লাইনই লাগে: একটি LLM প্রোভাইডারে অ্যাক্সেস (এই এক্সপ্লিসিট সাবস্ক্রিপশন ফলব্যাক সহ) এবং `AGENTMEMORY_AUTO_COMPRESS=true`। একটি প্রোভাইডার একা ডিফল্ট সিন্থেটিক কম্প্রেশন পাথ রেখে দেয়।
+LLM-লিখিত observation compression-এর জন্য দুই লাইনই দরকার: LLM provider-এ access (এই স্পষ্ট subscription fallback-সহ) এবং `AGENTMEMORY_AUTO_COMPRESS=true`। শুধু provider থাকলে ডিফল্ট synthetic compression path-ই থাকে।
-কনসোলিডেশন (গ্রাফ নোড, লেসন, ক্রিস্টাল) একটি LLM প্রোভাইডার কনফিগার করা থাকলেই ডিফল্টভাবে চালু থাকে। LLM-ফ্রি অপারেশন চাইলে স্পষ্টভাবে `CONSOLIDATION_ENABLED=false` দিয়ে অপ্ট-আউট করুন। গ্রাফ এক্সট্র্যাকশন একটা আলাদা ফ্ল্যাগ:
+LLM provider কনফিগার করা থাকলে consolidation (graph node, lesson, crystal) ডিফল্টভাবে চালু থাকে। LLM ছাড়া চালাতে `CONSOLIDATION_ENABLED=false` দিয়ে opt-out করুন। Graph extraction আলাদা flag:
```env
GRAPH_EXTRACTION_ENABLED=true
@@ -1613,179 +1361,34 @@ GRAPH_EXTRACTION_ENABLED=true
### এনভায়রনমেন্ট ভ্যারিয়েবল
-`~/.agentmemory/.env` তৈরি করুন:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+সম্পূর্ণ সেটিংস [`.env.example`](../.env.example)-এ আছে: প্রোভাইডার, capture filter, সংরক্ষণকাল, স্টোরেজ ও team scope। `AGENTMEMORY_ENV_FILE` দিয়ে অন্য ফাইল বাছা যায়। পরিবর্তনের পরে রিস্টার্ট করুন। আসল মানসহ `.env` বা Bearer secret কমিট করবেন না।
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-`3111` পোর্টে 143 এন্ডপয়েন্ট। REST API ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে। প্রোটেক্টেড এন্ডপয়েন্টে `Authorization: Bearer <secret>` লাগে, এবং mesh sync এন্ডপয়েন্টে দুই পিয়ারেই স্পষ্টভাবে সেট করা `AGENTMEMORY_SECRET` লাগে।
+`3111` পোর্টে 146 এন্ডপয়েন্ট। REST API ডিফল্টভাবে `127.0.0.1`-এ বাইন্ড করে। প্রোটেক্টেড এন্ডপয়েন্টে `Authorization: Bearer <secret>` লাগে, এবং 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 কল করতে:
+প্রমাণীকরণ ডিফল্টভাবে চালু। `AGENTMEMORY_SECRET` নির্ধারিত না থাকলে CLI প্রথমবার একটি random secret `~/.agentmemory/secret`-এ রাখে এবং নির্বাচিত ডেটা ডিরেক্টরির `secret`-এ কপি করে; অনুমতি `0600`। সঙ্গে থাকা ক্লায়েন্ট লোকাল সংযোগে মূল ফাইলটিকে অগ্রাধিকার দেয় এবং সংরক্ষিত secret শুধু loopback URL-এ পাঠায়। স্পষ্ট `AGENTMEMORY_SECRET` অগ্রাধিকার পায়; রিমোট ক্লায়েন্টকে environment-এ সেট করতে হয়। Docker নিজস্ব secret তৈরি করে।
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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-ও গ্রহণ করে।
@@ -1821,7 +1424,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | টিমের সাথে শেয়ার করুন |
| `GET` | `/agentmemory/audit` | অডিট ট্রেইল |
-সম্পূর্ণ এন্ডপয়েন্ট তালিকা: [`src/triggers/api.ts`](../src/triggers/api.ts)
+সম্পূর্ণ এন্ডপয়েন্ট তালিকা: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1839,19 +1442,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
সার্ভার ডাউন থাকলে, সময়মতো উত্তর না দিলে, বা একটা 5xx রিটার্ন করলে, হুক অবজারভেশনটিকে একটি লোকাল স্পুল ফাইলে যুক্ত করে, `<data dir>/capture-spool/<host>-<port>.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` সেট করুন।
+**গ্রাফ প্রোভেন্যান্স কমপ্যাক্ট করা।** পুরোনো provenance কমপ্যাকশন শুরুতে স্থগিত থাকে, কারণ এটি সম্পূর্ণ পুরোনো scope পড়ে। `/agentmemory/status`-এ `deferred` দেখায়, অথবা `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` হলে `off`। রক্ষণাবেক্ষণের সময় নিচের ম্যানুয়াল কমপ্যাকশন চালান। Retrieval index migration আলাদা: [রক্ষণাবেক্ষণ নির্দেশিকা](../docs/reliability/graph-index-migration.md) অনুযায়ী `agentmemory graph-index migrate --allow-legacy-scan` ব্যবহার করুন।
হাতে চালাতে, `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1865,7 +1468,7 @@ npm test # 4,000+ 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 ব্যবহার করে।
+প্রয়োজনীয়তা [ইনস্টল](#install)-এ এবং অবদান ও রিলিজের নিয়ম [CONTRIBUTING.md](../CONTRIBUTING.md)-এ আছে।
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="লাইসেন্স" height="32" /></picture></h2>
diff --git a/READMEs/README.cs-CZ.md b/READMEs/README.cs-CZ.md
index 175a13d8..0c88f19e 100644
--- a/READMEs/README.cs-CZ.md
+++ b/READMEs/README.cs-CZ.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Váš kódovací agent si pamatuje všechno. Žádné další opakované vysvětlování.
- Založeno na <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Trvalá paměť napříč sessions a kódovacími agenty.
</strong><br/>
- Trvalá paměť pro Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode a jakéhokoli klienta MCP.
+ Trvalá paměť pro Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode a jakéhokoli klienta MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licence" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Hvězdy" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Jak to funguje</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Založeno na iii</a> &bull;
<a href="#configuration">Konfigurace</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory zachycuje podporované události sessions, umožňuje vyhledávat rozhodnutí a opravy a sdílí projektovou paměť mezi agenty. Prohlížejte, upravujte, exportujte a mažte vzpomínky ve vieweru. Vyhledávání podle klíčových slov funguje bez API klíče; embeddingy přidávají sémantické vyhledávání.
+
+<a id="install"></a>
+
## 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.
+- macOS/Linux také potřebují `curl`, POSIX `sh` a `tar` pro automatické nastavení běhového prostředí.
+- Ve Windows použijte WSL2 nebo [návod pro nativní Windows](#windows).
Kanonický příkaz pro čistou instalaci:
@@ -108,11 +111,11 @@ Kanonický příkaz pro čistou instalaci:
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`.
+Vyberte agenty a poskytovatele, nebo režim bez klíče. Průvodce zapíše konfiguraci, spustí paměťový server a nabídne globální instalaci příkazu `agentmemory`. `-y` potvrdí výzvu npm; `@latest` vybere aktuální vydání. Komprese pomocí LLM vyžaduje poskytovatele a `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 <path>` 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.
+API běží na `http://localhost:3111` a živý viewer na `http://localhost:3113`. Oba standardně naslouchají pouze lokálně. Konfigurace je v `~/.agentmemory/.env`; umístění paměti a samostatné instance popisuje [ukládání dat](#data-storage).
Pak ověřte, že vyhledávání funguje, a dejte svému agentovi jeho skills:
@@ -127,14 +130,7 @@ 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 <agent>` — 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).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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).
-
-</details>
+Dalšího agenta připojte pomocí `agentmemory connect <agent>`. Viz [podporované integrace](#works-with-every-agent) a [běžné příkazy](#everyday-commands).
<details>
<summary><strong>Globální instalace / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx cachuje podle verze. Vynuťte nejnovější verzi pomocí `npx -y @agentmemo
</details>
-<details>
-<summary><strong>Už mám běžící vlastní iii engine</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funguje s každým agentem" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>nativní plugin + 7 hooks + MCP</sub>
+<sub>nativní plugin + hooks životního cyklu + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>nativní plugin + MCP</sub>
+<sub>nativní recall + zachycení + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>server MCP</sub>
+<sub>nativní zachycení + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>nativní recall + zachycení + skills + volitelné MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ agentmemory funguje s jakýmkoli agentem, který podporuje hooks, MCP nebo REST
---
-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.
+<a id="data-storage"></a>
-**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í.
+### Ukládání dat
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Vzpomínky se standardně ukládají mimo repozitář:
-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 <path>` nebo nastavte `AGENTMEMORY_DATA_DIR`; kterékoli z explicitních nastavení má přednost před starším vyhledáváním:
+| Platforma | Adresář dat |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instance 0 znovu použije existující `./data/state_store.db`. Jiné umístění nastavíte pomocí `--data-dir <path>` nebo `AGENTMEMORY_DATA_DIR`. Při restartu a aktualizaci zachovejte stejný adresář.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` používá podadresář `instance-1`, API port `3211` a viewer port `3213`. Redis a migraci backendu popisuje [průvodce úložištěm a zálohami](../docs/reliability/state-storage.md).
Nejnovější poznámky k vydání: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ Nejnovější poznámky k vydání: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Externí závislosti</strong></td>
-<td>Žádné (SQLite + iii-engine)</td>
+<td>Není potřeba samostatná databázová služba</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektorová DB</td>
<td>Více</td>
@@ -550,14 +549,12 @@ Nejnovější poznámky k vydání: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory spojuje zachycení sessions, prohledávatelnou historii projektu a lokální viewer; bez klíče funguje od prvního spuštění.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Rychlý start" height="32" /></picture></h2>
-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
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Otevřete `http://localhost:3113` a sledujte, jak se paměť živě staví.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Se spuštěným serverem ověřte zdraví, viewer a stav:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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á:
+`status` ukazuje zdraví serveru, poskytovatele, režim embeddingů, doručování záznamů a obnovu. Chráněné REST požadavky vyžadují secret serveru. Pokud používáte vlastní `AGENTMEMORY_SECRET`, použijte stejnou hodnotu; jinak načtěte automaticky vygenerovaný lokální secret:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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ář.
+<a id="everyday-commands"></a>
+
### 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:
@@ -604,6 +610,9 @@ Instalace a nastavení jsou popsány výše v sekci [Instalace](#install) (prvn
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Importované sessions se objeví v Replay vedle nativních. Transkripty jsou indexovány pro vyhledávání a označeny kanálem `import`; zpracování sessions může vytvořit také krystaly 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.
@@ -635,14 +644,12 @@ Příkaz pro údržbu použijte, když chcete úmyslně aktualizovat svůj loká
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`).
+Příkaz aktualizuje místní běhové prostředí a může změnit JavaScriptové závislosti v aktuálním workspace. Zálohujte data a před aktualizací si přečtěte [průvodce upgradem](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code bez instalace pluginu (cesta MCP-standalone)
@@ -703,6 +710,30 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Potom v **Settings → Plugins → Add marketplace** vyberte checkout agentmemory obsahující `.cursor-plugin/plugin.json`, povolte plugin **agentmemory** a znovu načtěte okno. Plugin poskytuje zachycení životního cyklu, přiřazení projektu podle workspace, skills a MCP. Zapněte buď hooks pluginu, nebo manuální hooks v `~/.cursor/hooks.json`, abyste nezaznamenávali události dvakrát.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Vyberte příkaz pro svého hostitele. Pi a OMP instalují nativní recall, zachycení, offline replay a skills; `--with-mcp` přidá úplnou sadu nástrojů. V Pi spusťte `/reload`, OMP restartujte a ověřte `/agentmemory-status`. DSH instaluje MCP a přibalený plugin pro zachycení; po připojení DSH restartujte.
+
+Pi podporuje také instalovatelný balíček `@agentmemory/pi`. Lokální instalaci a dostupnost na npm popisuje [průvodce Pi](../integrations/pi/). Pro každého hostitele používejte jen jeden způsob instalace.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (vložte tento prompt)</b></summary>
@@ -749,6 +780,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### Další agenti
Spusťte server paměti: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +798,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Toto je **doplňkové** k `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` obvykle zapisuje konfiguraci MCP. Hermes, OpenClaw, Pi a Oh My Pi standardně instalují nativní integraci a skills; MCP zapnete pomocí `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` instaluje skills pro agenty bez přibalených nativních skills. U Hermes, OpenClaw, Pi a Oh My Pi tento krok vynechte; skills už instaluje jejich konektor.
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.
@@ -790,7 +823,7 @@ Položka agentmemory je **stejný blok serveru MCP** na všech hostitelích, kte
| 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. |
+| **Cursor (plný plugin)** | `.cursor-plugin/` | Plugin poskytuje hooks životního cyklu, rozpoznání workspace, skills a MCP v Cursor IDE i `cursor-agent`. Viz [nastavení Cursoru](#cursor). |
| **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. |
@@ -804,7 +837,8 @@ Položka agentmemory je **stejný blok serveru MCP** na všech hostitelích, kte
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. nativní recall + zachycení + skills. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. nativní recall + zachycení + skills. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +846,19 @@ Položka agentmemory je **stejný blok serveru MCP** na všech hostitelích, kte
| **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). |
+| **Continue.dev** | `~/.continue/config.yaml` (preferované) nebo `config.json` (starší) | `agentmemory connect continue` vytvoří `config.yaml`, pokud konfigurace chybí, nebo upraví existující `config.json`. U existujícího YAML vypíše blok k vložení pod `mcpServers:`, aby zachoval komentáře a kotvy. Continue používá pole, nikoli objekt. |
| **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 `<repo>/.factory/mcp.json`. Pro nativní automatické zachycení přidejte `--with-hooks`. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` zapne nástroje MCP. Přidejte `--with-hooks` pro nativní zachytávání zahrnuté v AgentMemory. Samostatný balíček pluginu není potřeba. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Použijte [autentizované REST příklady](#validate-a-fresh-install-and-restart-persistence) pro ukládání a vyhledávání ze skriptů. |
| **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.
+Použijte [REST API](#api) z libovolného jazyka nebo [MCP nástroje](#mcp-server) z agenta. REST používá JSON a bearer autentizaci; viz [příklad ukládání a vyhledávání](#validate-a-fresh-install-and-restart-persistence). Přímou integraci běhového prostředí ukazují [příklady v Pythonu](../examples/python/).
### Ze zdroje
@@ -853,91 +867,33 @@ 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=<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).
+`npm start` spustí stejný lokální server jako nainstalované CLI. Požadavky jsou v sekci [Instalace](#install); API a viewer naslouchají na `127.0.0.1`.
### 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.
+agentmemory běží na Windows 10/11. WSL2 používá cestu pro Linux a může pinned engine nainstalovat automaticky. Nativní Windows vyžaduje ručně nainstalovanou binárku iii-engine v0.25.0; stáhněte odpovídající archiv ze [stránky vydání iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), ověřte kontrolní součet a umístěte `iii.exe` do `PATH` (například `%USERPROFILE%\.local\bin\iii.exe`). CLI ZIP pro Windows automaticky nerozbaluje.
-**Varianta A: předpřipravená binárka pro Windows (doporučeno)**
+Automatizované zapojení MCP na nativním Windows podporuje pouze `agentmemory connect copilot-cli`. U ostatních nativních agentů použijte manuální blok MCP ze sekce [Další agenti](#other-agents). `connect` ve WSL spouštějte pouze tehdy, pokud je cílový agent nainstalován ve stejném prostředí WSL.
-```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:
+**Pouze samostatné MCP (bez enginu).** Pokud potřebujete jen nástroje MCP a nikoli REST API, viewer nebo služby runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Spusťte `agentmemory doctor` nebo restartujte s `--verbose`. Jsou-li výchozí porty obsazené, použijte `--port <N>` nebo `--instance <N>`. Kompatibilitu a obnovu popisuje [průvodce upgradem](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Nasazení</h2>
-Š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.
+Pro vlastní hosting použijte Docker Compose nebo šablony níže. Paměť a přihlašovací údaje jsou na svazku `/data`; při aktualizaci ho zálohujte a znovu použijte. Autentizaci, síťový přístup, zálohy a migraci popisuje [průvodce nasazením](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Nasadit na fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Nasadit na Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Nasadit na fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Nasadit na Railway" /></a>
</p>
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).
@@ -955,29 +911,13 @@ spodní hranice nákladů) jsou v [`deploy/`](.././deploy/README.md):
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.
+REST používá `3111`, viewer `3113`. Ponechte je v privátní síti, nebo je chraňte autentizací a TLS. Nastavení platforem a [migraci starého Dockeru](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) popisuje průvodce nasazením.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Proč agentmemory" height="32" /></picture></h2>
-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.
-```
+Znalosti o projektu se rozptylují mezi chaty a soubory instrukcí. AgentMemory umožňuje najít dřívější rozhodnutí, opravy a lessons z právě používaného agenta.
### vs vestavěná paměť agenta
@@ -985,7 +925,7 @@ Každý AI kódovací agent se dodává s vestavěnou pamětí: Claude Code má
| | Vestavěné (CLAUDE.md) | agentmemory |
|---|---|---|
-| Rozsah | strop 200 řádků | neomezený |
+| Údržba | Ručně spravované instrukce | Indexovaná historie sessions a vzpomínky |
| 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) |
@@ -1011,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4úrovňová konsolidace paměti
@@ -1035,6 +975,8 @@ Paměti v čase slábnou (Ebbinghausova křivka). Často navštěvované paměti
### Co se zachycuje
+Tabulka popisuje hooks Claude Code. Ostatní integrace zachycují události poskytované svým hostitelem. Automatické vkládání kontextu přes sdílené hooks je volitelné: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Zachycuje |
|------|----------|
| `SessionStart` | cestu k projektu, ID session |
@@ -1051,7 +993,7 @@ Paměti v čase slábnou (Ebbinghausova křivka). Často navštěvované paměti
| Schopnost | Popis |
|---|---|
-| **Automatické zachycení** | každé použití nástroje se zaznamená přes hooks, bez manuálního úsilí |
+| **Automatické zachycení** | Podporované události sessions a nástrojů zaznamenané nativními integracemi |
| **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 |
@@ -1112,7 +1054,7 @@ Běžná instalace npm obsahuje volitelný runtime `@huggingface/transformers`.
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`.
+> **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 se připojte k self-hostovanému serveru a nastavte `AGENTMEMORY_URL=http://localhost:3111`.
### 54 nástrojů
@@ -1252,7 +1194,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Viewer v reálném čase" height="32" /></picture></h2>
-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.
+Automaticky se spouští na portu `3113`. Viewer při připojení načte jeden snapshot (`GET /agentmemory/viewer/snapshot`) a pak aplikuje živé události přes SSE na `/agentmemory/viewer/events` workeru REST: nové paměti, lessons, pozorování, audit záznamy, změny grafu a aktualizace zdraví se zobrazují bez pollingu nebo obnovení stránky. Další požadavky vznikají jen při akcích, které provedete, načtení dalších stránek nebo vyhledávání. Při výpadku streamu viewer ukáže stáří údajů, znovu se připojí s odstupňovaným prodlením a synchronizuje se z nového snapshotu.
- **12 záložek ve čtyřech skupinách** s živými počty, deep linky (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1207,7 @@ Automaticky se spouští na portu `3113`. Viewer při připojení načte jeden s
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Stránka Workers v iii console: připojení workeři včetně instancí agentmemory s živými počty funkcí a metadaty runtime" width="720" />
- <br/>
- <em>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.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Pohled waterfall na trace v iii console zobrazující dobu trvání jednotlivých spanů" width="720" />
- <br/>
- <em>Traces: waterfall / flame / rozpad podle služby pro každou operaci s pamětí.</em>
-</p>
-
-**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ě.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Založeno na iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 zdrojových souborů · ~55,000 řádků kódu · 3,400+ testů · 324 funkcí · 67 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
+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. Při bindu mimo loopback zůstává HTML shell veřejný, ale každý proxy požadavek vyžaduje bearer token; viewer si o něj řekne a uloží jej do session storage. Před vystavením vieweru nakonfigurujte výslovné povolené hostitele/originy a TLS. REST endpoint `/agentmemory/viewer` podléhá běžným pravidlům 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 zakazují inline atributy handlerů (`script-src-attr 'none'`).
---
@@ -1467,6 +1228,8 @@ agentmemory automaticky detekuje poskytovatele z vašeho prostředí. Poskytovat
| **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=<your 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í. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1279,7 @@ Lokální embeddingy se dodávají jako volitelná závislost, ale ve výchozím
### 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/).
+Začněte bez klíče pro zachycení a vyhledávání podle klíčových slov. `EMBEDDING_PROVIDER=local` zapne lokální sémantické vyhledávání po prvním stažení modelu. Komprese pomocí LLM vyžaduje poskytovatele a `AGENTMEMORY_AUTO_COMPRESS=true`; může odeslat požadavek pro každé pozorování, proto ověřte aktuální ceny poskytovatele. Aktivní poskytovatele ukazuje viewer a `agentmemory status`.
### Paměť pro víc agentů (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1309,22 @@ Když `AGENT_ID` není nastaveno, paměť zůstává bez rozsahu (starší chov
### 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 | Účel | Proměnná prostředí |
+|---|---|---|
+| `3111` | REST API, MCP HTTP a živé události vieweru | `III_REST_PORT` |
+| `3113` | Rozhraní vieweru | `III_VIEWER_PORT` |
-`--port <N>` 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.
+`--port <N>` nastaví REST port a výchozí port vieweru na `N+2`. `--instance N` vytvoří samostatné prostředí. Interní porty musí zůstat privátní; před vzdáleným zpřístupněním si přečtěte [průvodce nasazením](../deploy/README.md).
-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éž.
+### Úložiště: soubor nebo Redis
-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 <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.
+Výchozí souborové úložiště nepotřebuje samostatnou databázi. Redis je volitelný přes `AGENTMEMORY_STATE_BACKEND=redis` a `AGENTMEMORY_REDIS_URL`. Změna backendu nepřenese existující paměť. Nastavení persistence, omezení Redis a autentizovaný export/import jsou v [průvodci úložištěm](../docs/reliability/state-storage.md).
### 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.
+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. Pro výběr jiného souboru env nastavte `AGENTMEMORY_ENV_FILE`.
-Proměnné prostředí procesu stále fungují a mají přednost před hodnotami v souboru.
+Proměnné prostředí procesu mají přednost před souborem. Po změně konfigurace server restartujte.
Na Windows žije stejný soubor na `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,179 +1351,30 @@ GRAPH_EXTRACTION_ENABLED=true
### Proměnné prostředí
-Vytvořte `~/.agentmemory/.env`:
+Běžné volby pro `~/.agentmemory/.env`. Vkládání kontextu a komprese jsou volitelné; komprese navíc vyžaduje poskytovatele. Režim `core` omezuje viditelné nástroje MCP:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Úplný přehled je v [`.env.example`](../.env.example): přihlašovací údaje poskytovatelů, filtry zachycení, retence, úložiště, týmové scope a volitelné funkce. `AGENTMEMORY_ENV_FILE` vybere jiný soubor. Vyplněný `.env` ani bearer secret nikdy necommitujte.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 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 <secret>`, a endpointy pro mesh sync vyžadují explicitně nastavené `AGENTMEMORY_SECRET` na obou stranách.
+146 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 <secret>`, 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:
+**Autentizace je ve výchozím stavu zapnutá.** Pokud `AGENTMEMORY_SECRET` není nastaveno, CLI při prvním spuštění vygeneruje náhodný secret v `~/.agentmemory/secret` s oprávněním `0600` a zkopíruje jej také do vybraného datového adresáře. Všichni zabalení klienti jej načítají odtud při komunikaci s lokálním serverem: CLI, viewer, hooks v `plugin/scripts`, server MCP a shim `@agentmemory/mcp`, konfigurace zapsané pomocí `agentmemory connect` a zabalené integrace OpenCode, Pi, OpenClaw, Hermes a filesystem-watcher. Uložený secret se odesílá pouze na loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Výslovně nastavená `AGENTMEMORY_SECRET` má vždy přednost a vzdálení klienti ji musí mít ve svém prostředí. Self-host nasazení Dockeru z repozitáře a entrypointy `deploy/` generují a exportují vlastní secret. Pro ruční volání API:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1830,7 +1410,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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)
+Úplný seznam endpointů: [Generovaný přehled REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1428,19 @@ Neúspěšné události se opakují každých `AGENTMEMORY_CAPTURE_RETRY_INTERVA
Když je server mimo provoz, neodpoví včas nebo vrátí 5xx, hook připojí pozorování do lokálního souboru spoolu, `<data dir>/capture-spool/<host>-<port>.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.
+**Komprimace provenience grafu.** Komprimace starší provenience se při spuštění odkládá, protože načítá celé starší rozsahy. `/agentmemory/status` hlásí `deferred`, nebo `off` při `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Níže uvedenou ruční komprimaci spusťte během údržby. Migrace vyhledávacího indexu je samostatná: použijte `agentmemory graph-index migrate --allow-legacy-scan` podle [průvodce údržbou](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1454,7 @@ npm test # 4,000+ 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.
+Požadavky jsou v sekci [Instalace](#install). Pravidla přispívání a kontroly vydání najdete v [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licence" height="32" /></picture></h2>
diff --git a/READMEs/README.da-DK.md b/READMEs/README.da-DK.md
index 8ab557d4..3453b4a4 100644
--- a/READMEs/README.da-DK.md
+++ b/READMEs/README.da-DK.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Din kodeagent husker alt. Ikke mere genforklaring.
- Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Vedvarende hukommelse på tværs af kodningssessioner og agenter.
</strong><br/>
- Persistent hukommelse til Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode og enhver MCP-klient.
+ Persistent hukommelse til Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode og enhver MCP-klient.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licens" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stjerner" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Hvordan det virker</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Drevet af iii</a> &bull;
<a href="#configuration">Konfiguration</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory registrerer kodningssessioner og gør beslutninger, rettelser og erfaringer søgbare. Del ét lager mellem agenter, undersøg det gemte indhold, og vælg, hvor meget kontekst modellen modtager.
+
+<a id="install"></a>
+
## 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.
+- På macOS/Linux kræver automatisk opsætning også `curl`, en POSIX-`sh` og `tar`.
+- Brug WSL2 på Windows, eller følg [opsætningen til native Windows](#windows).
Den kanoniske kommando til en ny installation:
@@ -108,11 +111,11 @@ Den kanoniske kommando til en ny installation:
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.
+Vælg dine agenter og en udbyder, eller brug tilstanden uden nøgle. Opsætningen skriver konfigurationen, starter hukommelsesserveren og tilbyder en global installation af kommandoen `agentmemory`. `-y` accepterer npm-prompten; `@latest` vælger den aktuelle version. LLM-komprimering er valgfri og kræver en udbyder samt `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+API'et findes på `http://localhost:3111`, og viewer på `http://localhost:3113`. Begge lytter som standard på loopback. Konfigurationen ligger i `~/.agentmemory/.env`; se [datalagring](#data-storage) for placeringer og separate instanser.
Bevis derefter, at recall virker, og giv din agent dens skills:
@@ -127,14 +130,7 @@ Foretrækker du, at en kodeagent gør det hele selv? Giv den en enkelt instrukti
> 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 <agent>` — 20 adaptere er listet under [Works with every agent](#works-with-every-agent). Fuld kommandoreference under [Quick Start](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Tilslut en anden agent med `agentmemory connect <agent>`. Se [integrationer](#works-with-every-agent) og [daglige kommandoer](#everyday-commands).
<details>
<summary><strong>Global installation / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx cacher pr. version. Tving den nyeste med `npx -y @agentmemory/agentmemory@la
</details>
-<details>
-<summary><strong>Kører allerede din egen iii-engine</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Fungerer med alle agenter" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST A
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>native plugin + lifecycle-hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST A
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>native søgning + registrering + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST A
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>native registrering + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST A
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>native søgning + registrering + skills + Valgfri MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +306,25 @@ agentmemory fungerer med enhver agent, der understøtter hooks, MCP eller REST A
---
-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.
+<a id="data-storage"></a>
-**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.
+### Datalagring
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Hukommelsen gemmes som standard uden for dit repository:
-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 <path>` eller sæt `AGENTMEMORY_DATA_DIR`; begge eksplicitte indstillinger har forrang over den forældede opdagelse:
+| Platform | Datamappe |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instans 0 genbruger en eksisterende `./data/state_store.db`. Vælg en anden placering med `--data-dir <path>` eller `AGENTMEMORY_DATA_DIR`, og behold den ved genstart og opgradering. `--instance 1` bruger undermappen `instance-1`, API-port `3211` og viewer-port `3213`. Se [lagring og backup](../docs/reliability/state-storage.md) for Redis og migrering.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +473,7 @@ Seneste udgivelsesnoter: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Eksterne afhængigheder</strong></td>
-<td>Ingen (SQLite + iii-engine)</td>
+<td>Ingen separat databasetjeneste nødvendig</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektordatabase</td>
<td>Flere</td>
@@ -550,14 +547,12 @@ Seneste udgivelsesnoter: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory kombinerer registrering fra kodningsagenter, søgbar projekthistorik og en lokal viewer. Du kan arbejde uden nøgle fra første start.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Hurtig start" height="32" /></picture></h2>
-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
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Åbn `http://localhost:3113` for at se hukommelsen bygges live.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Validér en frisk installation og persistens ved genstart
-Mens serveren kører, validér REST, health, viewer og den iii-baserede runtime-status:
+Kontrollér sundhed, viewer og status, mens serveren kører:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` viser serverens tilstand og de aktive udbydere og embeddings. Gem en testhukommelse, og kontrollér søgningen:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Daglige kommandoer
Installation og opsætning findes under [Install](#install) ovenfor (den første kørsel guider dig igennem det). Til dagligt brug:
@@ -623,7 +627,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Importerede sessioner vises i Replay-vælgeren sammen med de native. 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.
@@ -635,14 +639,12 @@ Brug vedligeholdelseskommandoen, når du bevidst vil opdatere din lokale runtime
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`).
+Kommandoen opdaterer den lokale runtime og kan opdatere JavaScript-afhængigheder i det aktuelle workspace. Tag en backup, og læs [opgraderingsvejledningen](../docs/upgrades/iii-0.25.md), før du fortsætter.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code uden plugin-installation (MCP-standalone-vej)
@@ -703,6 +705,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Tilføj derefter det native plugin fra en AgentMemory-checkout via **Settings → Plugins → Add marketplace**, og genindlæs vinduet. Pluginet giver lifecycle-registrering, projekttilknytning, skills og MCP. Aktivér enten pluginets hooks eller manuelle hooks i `~/.cursor/hooks.json` for at undgå dobbelt registrering. [Cursor-vejledning](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Vælg kommandoen til din host. Pi og OMP installerer søgning, registrering, offline-gensendelse og 17 skills; `--with-mcp` tilføjer alle værktøjer. Kør `/reload` i Pi, eller genstart OMP, og kontrollér `/agentmemory-status`. DSH installerer MCP og det medfølgende registreringsplugin; genstart DSH bagefter.
+
+Pi understøtter også pakken `@agentmemory/pi`. [Pi-vejledningen](../integrations/pi/) beskriver lokal installation og tilgængelighed på npm. Brug én installationsmetode pr. host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (indsæt denne prompt)</b></summary>
@@ -749,6 +773,8 @@ Fuld guide: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Andre agenter
Start hukommelsesserveren: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +791,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Dette er et **supplement** til `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` skriver normalt MCP-konfigurationen. Hermes, OpenClaw, Pi og Oh My Pi installerer som standard deres native integration og medfølgende skills; MCP tilvælges med `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` installerer skills til agenter uden medfølgende native skills. Spring dette trin over for Hermes, OpenClaw, Pi og Oh My Pi: deres connectorer installerer allerede disse skills.
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.
@@ -790,7 +816,7 @@ agentmemory-indgangen er den **samme MCP-serverblok** på alle hosts, der bruger
| 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. |
+| **Cursor (fuldt plugin)** | `.cursor-plugin/` | Tilføj derefter det native plugin fra en AgentMemory-checkout via **Settings → Plugins → Add marketplace**, og genindlæs vinduet. Pluginet giver lifecycle-registrering, projekttilknytning, skills og MCP. Aktivér enten pluginets hooks eller manuelle hooks i `~/.cursor/hooks.json` for at undgå dobbelt registrering. [Cursor-vejledning](../integrations/cursor/). |
| **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. |
@@ -804,7 +830,7 @@ agentmemory-indgangen er den **samme MCP-serverblok** på alle hosts, der bruger
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | native søgning + registrering + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +838,19 @@ agentmemory-indgangen er den **samme MCP-serverblok** på alle hosts, der bruger
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (foretrukket) eller `config.json` (legacy) | `agentmemory connect continue` opretter en manglende `config.yaml` eller ændrer eksisterende `config.json`. Hvis YAML-filen findes, vises blokken til `mcpServers:`, så kommentarer og ankre bevares. Continue bruger et array, ikke et objekt. |
| **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 `<repo>/.factory/mcp.json`. Angiv `--with-hooks` for native auto-capture. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` aktiverer MCP-værktøjer. Tilføj `--with-hooks` for at indlæse det native registreringsplugin, der følger med AgentMemory. Ingen separat pluginpakke er nødvendig. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Brug de [autentificerede REST-eksempler](#validate-a-fresh-install-and-restart-persistence) til at gemme og søge i hukommelsen fra scripts. |
| **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.
+Brug [REST API'et](#api) fra ethvert sprog eller [MCP-værktøjerne](#mcp-server) fra en agent. REST bruger JSON og bearer-autentificering; se [eksemplet på lagring og søgning](#validate-a-fresh-install-and-restart-persistence). [Python-eksemplerne](../examples/python/) viser direkte runtime-integration.
### Fra kildekode
@@ -853,83 +859,33 @@ 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=<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).
+`npm start` starter samme lokale server som den installerede CLI. Kravene står under [Install](#install); API og viewer lytter på `127.0.0.1`.
### 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.
+agentmemory kører på Windows 10/11. WSL2 følger Linux-vejen og kan installere den fastlåste engine automatisk. Native Windows kræver, at den fastlåste iii-engine v0.25.0-binary installeres manuelt; download det tilsvarende arkiv fra [iii v0.25.0-udgivelsessiden](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verificér checksum, og placér `iii.exe` på `PATH` (for eksempel `%USERPROFILE%\.local\bin\iii.exe`). CLI’en pakker ikke Windows-ZIP’en ud automatisk.
-**Mulighed A: prækompileret Windows-binary (anbefalet)**
+Automatisk MCP-opsætning på native Windows understøtter kun `agentmemory connect copilot-cli`. Brug den manuelle MCP-blok fra [Andre agenter](#other-agents) til andre native Windows-agenter. Kør kun `connect` i WSL, hvis målagenten er installeret i samme WSL-miljø.
-```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:
+**Kun standalone MCP (uden engine).** Hvis du kun har brug for MCP-værktøjerne og ikke REST API, viewer eller runtime-tjenester:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Kør `agentmemory doctor`, eller genstart med `--verbose`. Brug `--port <N>` eller `--instance <N>`, hvis portene er optaget. Se [opgraderingsvejledningen](../docs/upgrades/iii-0.25.md) for kompatibilitet og gendannelse.
---
<h2 id="deploy">Deployment</h2>
-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.
+Host tjenesten med Docker Compose eller skabelonerne nedenfor. Hukommelse og legitimationsoplysninger ligger på `/data`-volumenet. Tag backup af det, og genbrug det ved opgradering. [Deployment-vejledningen](../deploy/README.md) beskriver autentificering, netværk, backup og migrering.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy til fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy til Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy til fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy til Railway" /></a>
</p>
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.
@@ -947,28 +903,26 @@ minimumsomkostninger) findes i [`deploy/`](.././deploy/README.md):
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.
+REST bruger port `3111`; viewer bruger `3113`. Hold dem private, eller beskyt dem med autentificering og TLS. Deployment-vejledningen dækker netværksadgang og [migrering af ældre Docker-installationer](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Hvorfor agentmemory" height="32" /></picture></h2>
-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.
+Projektviden spredes mellem chats og instruktionsfiler. AgentMemory gør tidligere beslutninger, rettelser og erfaringer søgbare fra den agent, du bruger nu.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs. indbygget agenthukommelse
@@ -977,7 +931,7 @@ Hver AI-kodeagent leveres med indbygget hukommelse: Claude Code har `MEMORY.md`,
| | Indbygget (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skala | 200-linjers-loft | Ubegrænset |
+| Vedligeholdelse | Manuelt vedligeholdte instruktioner | Indekseret sessionshistorik og hukommelse |
| 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) |
@@ -1003,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-lags hukommelseskonsolidering
@@ -1027,6 +981,8 @@ Hukommelser forfalder over tid (Ebbinghaus-kurven). Ofte tilgåede hukommelser s
### Hvad der indsamles
+Tabellen beskriver Claude Codes hooks. Andre integrationer registrerer de hændelser, deres host tilbyder; se de enkelte vejledninger. Automatisk kontekstindsættelse via delte hooks aktiveres med `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Indsamler |
|------|----------|
| `SessionStart` | Projektsti, session-ID |
@@ -1043,7 +999,7 @@ Hukommelser forfalder over tid (Ebbinghaus-kurven). Ofte tilgåede hukommelser s
| Funktion | Beskrivelse |
|---|---|
-| **Automatisk indsamling** | Hver tool-brug registreres via hooks, ingen manuel indsats |
+| **Automatisk indsamling** | Native integrationer registrerer understøttede sessions- og værktøjshændelser |
| **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 |
@@ -1244,7 +1200,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Realtids-viewer" height="32" /></picture></h2>
-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.
+Starter automatisk på port `3113`. Viewer indlæser ét snapshot, når den forbinder (`GET /agentmemory/viewer/snapshot`), og anvender derefter livehændelser via SSE på `/agentmemory/viewer/events` i REST-workeren: nye hukommelser, lessons, observationer, audit-poster, grafændringer og health-opdateringer vises uden polling eller genindlæsning af siden. De eneste andre forespørgsler er de handlinger, du klikker på, "load more"-sider og søgninger. Når feedet afbrydes, viser viewer, hvor gamle dens tal er, genopretter forbindelsen med backoff og synkroniserer fra ét snapshot.
- **12 faner i fire grupper** med live-tal, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1257,186 +1213,7 @@ Starter automatisk på port `3113`. Viewer indlæser ét snapshot, når den forb
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers-siden: forbundne workers inklusive agentmemory-instanser med live funktionstal og runtime-metadata" width="720" />
- <br/>
- <em>Workers-siden: hver forbundne worker, inklusive agentmemory selv, med PID, funktionstal, runtime og senest set.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace-waterfall-visning, der viser varighed pr. span" width="720" />
- <br/>
- <em>Traces: waterfall-/flame-/service-breakdown for hver hukommelsesoperation.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Drevet af iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 kildefiler · ~55,000 LOC · 3,400+ tests · 324 funktioner · 67 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
+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. Ved bind uden for loopback forbliver HTML-skallen offentlig, men hver proxy-forespørgsel kræver bearer-token; viewer beder om det og gemmer det i session storage. Konfigurér eksplicitte host-/origin-allowlists og TLS, før viewer eksponeres. REST-endpointet `/agentmemory/viewer` følger de normale bearer-token-regler og omdirigerer browsere uden token til viewer-porten. CSP-headers bruger en per-response script-nonce og forbyder inline handler-attributter (`script-src-attr 'none'`).
---
@@ -1457,6 +1234,8 @@ agentmemory opdager automatisk udbydere fra dit miljø. En udbyder gør LLM-base
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1506,24 +1285,7 @@ Lokale embeddings leveres som en valgfri afhængighed, men er ikke aktiveret som
### 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/).
+Start uden nøgle til registrering og nøgleordssøgning. `EMBEDDING_PROVIDER=local` aktiverer lokal semantisk søgning efter den første modeldownload. LLM-komprimering kræver en udbyder og `AGENTMEMORY_AUTO_COMPRESS=true`; den kan sende én anmodning pr. observation. Kontrollér de aktuelle priser først. Viewer og `agentmemory status` viser de aktive udbydere.
### Multi-agent-hukommelse (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1553,39 +1315,22 @@ Når `AGENT_ID` ikke er sat, forbliver hukommelsen uscopet (legacy-opførsel, in
### 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 <N>` æ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.
+| Port | Formål | Konfiguration |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Rydning af forældede processer, når porte forbliver bundet efter en crashet kørsel:
+`--port <N>` sætter API-porten og som standard viewer til `N+2`. Brug `--instance N` til en separat instans. Hold interne porte private; læs [deployment-vejledningen](../deploy/README.md), før du tillader fjernadgang.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage-backend: file (standard) vs. redis
-`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.
+Standardlageret bruger filer og kræver ingen separat databasetjeneste. Redis er valgfrit med `AGENTMEMORY_STATE_BACKEND=redis` og `AGENTMEMORY_REDIS_URL`. Et backendskift kopierer ikke hukommelsen. Se [lagring og backup](../docs/reliability/state-storage.md) for persistens, Redis-begrænsninger og autentificeret eksport/import.
### 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.
+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. Sæt `AGENTMEMORY_ENV_FILE` for at vælge en anden env-fil.
-Procesmiljøvariabler fungerer stadig og har forrang over værdier i filen.
+Procesmiljøvariabler har forrang over filens værdier. Genstart serveren efter konfigurationsændringer.
På Windows ligger samme fil på `%USERPROFILE%\.agentmemory\.env`:
@@ -1612,179 +1357,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Miljøvariabler
-Opret `~/.agentmemory/.env`:
+Almindelige indstillinger for `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Den fulde reference er [`.env.example`](../.env.example) med legitimationsoplysninger, registreringsfiltre, opbevaring, lagring, teamafgrænsning og tilvalg. `AGENTMEMORY_ENV_FILE` vælger en anden fil. Commit aldrig en udfyldt `.env` eller en bearer-hemmelighed.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints på port `3111`. REST API'et binder til `127.0.0.1` som standard. Beskyttede endpoints kræver `Authorization: Bearer <secret>`, og mesh-sync-endpoints kræver en eksplicit sat `AGENTMEMORY_SECRET` på begge peers.
+146 endpoints på port `3111`. REST API'et binder til `127.0.0.1` som standard. Beskyttede endpoints kræver `Authorization: Bearer <secret>`, 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:
+**Autentificering er slået til som standard.** Hvis `AGENTMEMORY_SECRET` hverken er sat i shellen eller i `~/.agentmemory/.env`, opretter CLI’en en tilfældig hemmelighed ved første start i `~/.agentmemory/secret` og en kopi med navnet `secret` i den valgte datamappe, med filtilstanden `0600`. Alle medfølgende klienter læser den derfra, når de 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 have den i deres miljø. Docker-self-hosting fra repositoryet og `deploy/`-entrypoints genererer og eksporterer deres egen secret. Sådan kaldes API’et manuelt:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1820,7 +1418,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Del med team |
| `GET` | `/agentmemory/audit` | Audit trail |
-Fuld endpoint-liste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Fuld endpoint-liste: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1838,19 +1436,19 @@ Mislykkede events gentages hvert `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 sek
Når serveren er nede, ikke svarer i tide, eller returnerer en 5xx, tilføjer hooken observationen til en lokal spool-fil, `<data dir>/capture-spool/<host>-<port>.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.
+**Komprimering af graf-herkomst.** Komprimering af ældre herkomstdata udskydes ved opstart, fordi den læser hele de ældre scopes. `/agentmemory/status` viser `deferred`, eller `off` med `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Kør den manuelle komprimering nedenfor under vedligeholdelse. Migrering af søgeindekset er separat: brug `agentmemory graph-index migrate --allow-legacy-scan` som beskrevet i [vedligeholdelsesvejledningen](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1864,7 +1462,7 @@ npm test # 4,000+ 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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licens" height="32" /></picture></h2>
diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md
index 25b708aa..60de1d5a 100644
--- a/READMEs/README.de-DE.md
+++ b/READMEs/README.de-DE.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Ihr Coding-Agent merkt sich alles. Schluss mit dem ständigen Wiederholen.
- Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Persistentes Gedächtnis über Coding-Sessions und Agenten hinweg.
</strong><br/>
- Persistentes Gedächtnis für Claude Code, GitHub Copilot CLI, 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, Oh My Pi, DeepSeek Harness, OpenCode und jeden MCP-Client.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">Funktionsweise</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Konfiguration</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory erfasst Coding-Sessions und macht Entscheidungen, Lösungen und Erfahrungen später durchsuchbar. Nutzen Sie einen gemeinsamen Speicher über mehrere Agenten hinweg, prüfen Sie gespeicherte Inhalte und bestimmen Sie, wie viel Kontext das Modell erhält.
+
## Install
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.
+- Unter macOS/Linux werden für die automatische Einrichtung außerdem `curl`, eine POSIX-`sh` und `tar` benötigt.
+- Unter Windows verwenden Sie WSL2 oder folgen der [nativen Windows-Einrichtung](#windows).
Kanonischer Befehl für die Frischinstallation:
@@ -108,11 +109,11 @@ Kanonischer Befehl für die Frischinstallation:
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 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.
+Wählen Sie Ihre Agenten und einen Provider oder den schlüssellosen Modus. Das Setup schreibt die Konfiguration, startet den Memory-Server und bietet eine globale Installation für den Befehl `agentmemory` an. `-y` bestätigt die npm-Paketabfrage; `@latest` wählt die aktuelle Version. LLM-Kompression ist optional und benötigt einen Provider sowie `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+Die API ist unter `http://localhost:3111`, der Live-Viewer unter `http://localhost:3113` erreichbar. Beide binden standardmäßig an Loopback. Die Konfiguration liegt in `~/.agentmemory/.env`; Speicherorte und separate Instanzen stehen unter [Datenspeicherung](#data-storage).
Beweisen Sie dann, dass Recall funktioniert, und geben Sie Ihrem Agenten seine Skills:
@@ -127,14 +128,7 @@ Möchten Sie das Ganze lieber von einem Coding-Agenten erledigen lassen? Geben S
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Verdrahten Sie jederzeit weitere Agenten mit `agentmemory connect <agent>` — 20 Adapter sind unter [Funktioniert mit jedem Agenten](#works-with-every-agent) aufgelistet. Vollständige Befehlsreferenz unter [Schnellstart](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Verbinden Sie weitere Agenten mit `agentmemory connect <agent>`. Siehe [Integrationen](#works-with-every-agent) und [Alltagsbefehle](#everyday-commands).
<details>
<summary><strong>Globale Installation / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx cached pro Version. Erzwingen Sie die neueste mit `npx -y @agentmemory/agent
</details>
-<details>
-<summary><strong>Sie betreiben bereits eine eigene iii-Engine</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funktioniert mit jedem Agenten" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterst
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>natives Plugin + 7 Hooks + MCP</sub>
+<sub>natives Plugin + Lifecycle-Hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterst
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>natives Plugin + MCP</sub>
+<sub>native Suche + Erfassung + Skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterst
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP-Server</sub>
+<sub>native Erfassung + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterst
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>native Suche + Erfassung + Skills + Optionales MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +304,25 @@ agentmemory funktioniert mit jedem Agenten, der Hooks, MCP oder REST API unterst
---
-Sie erklären in jeder Session dieselbe Architektur. Sie entdecken dieselben Bugs erneut. Sie bringen dem Agenten dieselben Präferenzen wieder bei. Eingebautes Gedächtnis (CLAUDE.md, .cursorrules) ist bei 200 Zeilen am Ende und veraltet. agentmemory behebt das. Es erfasst stillschweigend, was Ihr Agent tut, komprimiert das Ganze in durchsuchbares Gedächtnis und injiziert beim Start der nächsten Session den passenden Kontext. Ein Befehl. Funktioniert über Agenten hinweg.
+<a id="data-storage"></a>
-**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.
+### Datenspeicherung
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Erinnerungen werden standardmäßig außerhalb Ihres Repositorys gespeichert:
-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 <path>` oder setzen Sie `AGENTMEMORY_DATA_DIR`; beide expliziten Einstellungen haben Vorrang vor der Legacy-Erkennung:
+| Plattform | Datenverzeichnis |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instanz 0 verwendet eine vorhandene `./data/state_store.db` weiter. Wählen Sie mit `--data-dir <path>` oder `AGENTMEMORY_DATA_DIR` einen anderen Speicherort und behalten Sie ihn bei Neustarts und Upgrades bei. `--instance 1` verwendet das Unterverzeichnis `instance-1`, API-Port `3211` und Viewer-Port `3213`. Hinweise zu Redis und Migrationen stehen im [Leitfaden zu Speicherung und Backups](../docs/reliability/state-storage.md).
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +471,7 @@ Neueste Release-Hinweise: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Externe Abhängigkeiten</strong></td>
-<td>Keine (SQLite + iii-engine)</td>
+<td>Kein separater Datenbankdienst erforderlich</td>
<td>Qdrant / pgvector</td>
<td>Postgres + Vector-DB</td>
<td>Mehrere</td>
@@ -550,14 +545,12 @@ Neueste Release-Hinweise: [CHANGELOG.md](../CHANGELOG.md).
| Zep / Graphiti | 30K | Temporaler Knowledge Graph; stärkste veröffentlichte Temporal-Query-Ergebnisse (LongMemEval 63.8%), aber der Graph wird asynchron aufgebaut, sodass frische Fakten hinterherhinken können |
| Cognee | 30K | Dokument-zu-Knowledge-Graph-Ingestion, nur Python, gebaut für strukturierte Entitäten-Extraktion statt Session-Erfassung |
-Keines davon erfasst automatisch aus Coding-Agent-Hooks, liefert einen local-first Viewer mit oder läuft ohne Schlüssel — die Kombination, um die agentmemory herum gebaut ist.
+AgentMemory verbindet die Erfassung durch Coding-Agenten mit durchsuchbarer Projekthistorie und einem lokalen Viewer. Der Betrieb ohne API-Schlüssel ist vom ersten Start an möglich.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Schnellstart" height="32" /></picture></h2>
-Kompatibilität: Diese Version zielt auf `iii-sdk` 0.22.1 und pinnt iii-engine v0.22.1.
-
### In 30 Sekunden ausprobieren
```bash
@@ -572,9 +565,11 @@ npx -y @agentmemory/agentmemory@latest demo
Öffnen Sie `http://localhost:3113`, um das Memory in Echtzeit aufgebaut zu sehen.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Prüfen Sie bei laufendem Server Health, Viewer und Status:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +578,27 @@ 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:
+`status` zeigt den Zustand des Servers sowie die aktiven Provider und Embeddings. Speichern Sie eine Test-Erinnerung und prüfen Sie die Suche:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Alltagsbefehle
Installation und Setup stehen oben unter [Install](#install) (der erste Lauf führt Sie hindurch). Im Alltag:
@@ -623,7 +625,7 @@ npx -y @agentmemory/agentmemory@latest import-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.
+Importierte Sessions tauchen im Replay-Picker neben den nativen auf. 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.
@@ -635,14 +637,12 @@ Verwenden Sie den Wartungsbefehl, wenn Sie Ihr lokales Runtime bewusst aktualisi
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.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`).
+Dieser Befehl aktualisiert die lokale Laufzeit und gegebenenfalls JavaScript-Abhängigkeiten im aktuellen Workspace. Sichern Sie Ihre Daten und lesen Sie vor dem Update den [Upgrade-Leitfaden](../docs/upgrades/iii-0.25.md).
### Claude Code (ein Block, einfügen)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code ohne Plugin-Installation (MCP-Standalone-Pfad)
@@ -703,6 +703,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Fügen Sie danach das native Plugin unter **Settings → Plugins → Add marketplace** aus einem AgentMemory-Checkout hinzu und laden Sie das Fenster neu. Das Plugin bietet Lifecycle-Erfassung, projektbezogene Zuordnung, Skills und MCP. Aktivieren Sie entweder Plugin-Hooks oder manuelle Hooks in `~/.cursor/hooks.json`, um doppelte Erfassung zu vermeiden. [Cursor-Leitfaden](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Wählen Sie den Befehl für Ihren Host. Pi und OMP installieren native Suche, Erfassung, Offline-Wiederholung und 17 Skills; `--with-mcp` ergänzt den vollständigen Werkzeugsatz. Führen Sie in Pi `/reload` aus oder starten Sie OMP neu und prüfen Sie `/agentmemory-status`. DSH installiert MCP und das mitgelieferte Erfassungsplugin; starten Sie DSH danach neu.
+
+Pi unterstützt außerdem das installierbare Paket `@agentmemory/pi`. Lokale Installation und npm-Verfügbarkeit stehen im [Pi-Leitfaden](../integrations/pi/). Verwenden Sie pro Host nur eine Installationsmethode.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (diesen Prompt einfügen)</b></summary>
@@ -749,6 +771,8 @@ Vollständiger Leitfaden: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Andere Agenten
Starten Sie den Memory-Server: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +789,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Das ist **komplementär** zu `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` schreibt die MCP-Server-Konfig, damit die Tools verfügbar sind.
-- `npx skills add rohitg00/agentmemory` installiert die Skills, damit der Agent weiß, wann er sie aufrufen soll.
+- `agentmemory connect <agent>` schreibt normalerweise die MCP-Konfiguration. Hermes, OpenClaw, Pi und Oh My Pi installieren standardmäßig ihre native Integration und die mitgelieferten Skills; MCP wird mit `--with-mcp` ergänzt.
+- `npx skills add rohitg00/agentmemory` installiert Skills für Agenten ohne mitgelieferte native Skills. Überspringen Sie diesen Schritt bei Hermes, OpenClaw, Pi und Oh My Pi; ihre Connectoren installieren die Skills bereits.
Für die wenigen Agenten, die die skills-CLI noch nicht abdeckt (Zed v1.3.x und darunter), legen Sie die 17 SKILL.md-Dateien selbst unter dem nativen Skill-Verzeichnis des Agenten ab; dasselbe Format funktioniert überall.
@@ -790,7 +814,7 @@ Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, de
| Agent | Konfigurationsdatei | Hinweise |
|---|---|---|
| **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. |
+| **Cursor (volles Plugin)** | `.cursor-plugin/` | Fügen Sie danach das native Plugin unter **Settings → Plugins → Add marketplace** aus einem AgentMemory-Checkout hinzu und laden Sie das Fenster neu. Das Plugin bietet Lifecycle-Erfassung, projektbezogene Zuordnung, Skills und MCP. Aktivieren Sie entweder Plugin-Hooks oder manuelle Hooks in `~/.cursor/hooks.json`, um doppelte Erfassung zu vermeiden. [Cursor-Leitfaden](../integrations/cursor/). |
| **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 (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. |
@@ -804,7 +828,7 @@ Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, de
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | native Suche + Erfassung + Skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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 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). |
@@ -812,39 +836,19 @@ Der agentmemory-Eintrag ist der **gleiche MCP-Server-Block** für jeden Host, de
| **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. |
-| **Continue.dev** | `~/.continue/config.yaml` (bevorzugt) oder `config.json` (Legacy) | `agentmemory connect continue` erstellt `config.yaml` von Grund auf, wenn keine der beiden existiert, oder modifiziert eine bestehende `config.json`. **Wenn Sie bereits eine `config.yaml` haben**, gibt der Adapter den exakten Block aus, den Sie unter `mcpServers:` einfügen; er schreibt Ihre yaml nicht stillschweigend um, weil das sichere Bewahren von Kommentaren und Ankern einen YAML-Parser braucht, den das Paket nicht mitliefert. Continue verwendet die Array-Form (kein Objekt) für `mcpServers`. |
+| **Continue.dev** | `~/.continue/config.yaml` (bevorzugt) oder `config.json` (Legacy) | `agentmemory connect continue` erstellt eine fehlende `config.yaml` oder aktualisiert eine vorhandene `config.json`. Bei bestehender YAML-Datei zeigt der Adapter den Block für `mcpServers:` zum Einfügen an; Kommentare und Anker bleiben erhalten. Continue verwendet dort ein Array, kein Objekt. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` schreibt unter `context_servers` (Zeds Schlüssel, NICHT `mcpServers`). Remote-MCP-Server können stattdessen via `{"url": "..."}` verdrahtet werden. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` schreibt den standardmäßigen `mcpServers`-Block. Projektbezogene Overrides liegen in `<repo>/.factory/mcp.json`. Übergeben Sie `--with-hooks` für native Auto-Erfassung. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` aktiviert MCP-Werkzeuge. Mit `--with-hooks` wird das in AgentMemory enthaltene native Erfassungsplugin geladen. Kein separates Pluginpaket erforderlich. [DSH](../docs/dsh.md). |
| **Goose** | Goose-MCP-Einstellungen-UI | Gleicher `mcpServers`-Block; nutzen Sie `goose configure` → Add Extension → MCP. Direktes YAML-Editieren unter `~/.config/goose/config.yaml` wird unterstützt, aber das Schema verwendet `extensions:` + `cmd` (nicht `mcpServers:` + `command`). |
-| **Aider** | n/v | Sprechen Sie direkt mit der REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Aider** | n/v | Nutzen Sie die [authentifizierten REST-Beispiele](#validate-a-fresh-install-and-restart-persistence), um Erinnerungen aus Skripten zu speichern und zu suchen. |
| **Jeder Agent (32+)** | n/v | `npx skillkit install agentmemory` erkennt den Host automatisch und merged. |
**MCP-Clients in Sandboxen** (Flatpak / Snap / restriktive Container), die den `localhost` des Hosts nicht erreichen können: Setzen Sie zusätzlich `"AGENTMEMORY_FORCE_PROXY": "1"` im `env`-Block und lassen Sie `AGENTMEMORY_URL` auf eine Route zeigen, die die Sandbox tatsächlich erreichen kann (z. B. Ihre LAN-IP).
### Programmatischer Zugriff (Python / Rust / Node)
-agentmemory registriert seine Kernoperationen als iii-Funktionen (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Jede Sprache mit einem iii-SDK kann sie direkt über `ws://localhost:49134` aufrufen, ohne separaten REST-Client pro Sprache.
-
-```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"},
-})
-```
-
-Durchgearbeitetes Beispiel: [`examples/python/`](../examples/python/) (Quickstart + Beobachtungs-/Recall-Fluss). REST auf `:3111` bleibt verfügbar für Hosts ohne iii-Runtime.
+Verwenden Sie die [REST-API](#api) aus jeder Programmiersprache oder die [MCP-Tools](#mcp-server) aus einem Agenten. REST-Anfragen nutzen JSON und Bearer-Authentifizierung; siehe das [Speicher- und Suchbeispiel](#validate-a-fresh-install-and-restart-persistence). Direkte Laufzeitintegration zeigen die [Python-Beispiele](../examples/python/).
### Aus den Quellen
@@ -853,91 +857,33 @@ 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 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.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=<version>` überschreiben, wenn Sie eine eigene Engine betreiben und wissen, dass sie passt.
-
-- **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.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.22.1`). Vollständige Doku: [iii.dev/docs](https://iii.dev/docs).
+`npm start` startet denselben lokalen Server wie die installierte CLI. Voraussetzungen stehen unter [Install](#install); API und Viewer binden an `127.0.0.1`.
### Windows
-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.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
-```
-
-**Option B: Docker Desktop**
+agentmemory läuft unter Windows 10/11. WSL2 folgt dem Linux-Pfad und kann die gepinnte Engine automatisch installieren. Unter nativem Windows muss das gepinnte iii-engine-Binary v0.25.0 manuell installiert werden: Laden Sie das passende Archiv von der [iii-v0.25.0-Release-Seite](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) herunter, prüfen Sie die Prüfsumme und legen Sie `iii.exe` auf den `PATH` (zum Beispiel `%USERPROFILE%\.local\bin\iii.exe`). Die CLI entpackt das Windows-ZIP nicht automatisch.
-```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
-```
+Die automatisierte MCP-Verdrahtung unter nativem Windows unterstützt nur `agentmemory connect copilot-cli`. Für andere native Windows-Agenten verwenden Sie den manuellen MCP-Block unter [Andere Agenten](#other-agents). Führen Sie `connect` in WSL nur aus, wenn der Ziel-Agent in derselben WSL-Umgebung installiert ist.
-**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:
+**Nur Standalone-MCP (ohne Engine).** Wenn Sie nur MCP-Tools benötigen und weder REST API, Viewer noch Runtime-Dienste brauchen:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**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 |
-|---|---|
-| `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 <N>` 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, 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`.
+Führen Sie `agentmemory doctor` aus oder starten Sie mit `--verbose` neu. Verwenden Sie bei belegten Ports `--port <N>` oder `--instance <N>`. Kompatibilität und Wiederherstellung stehen im [Upgrade-Leitfaden](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Deploy</h2>
-Ein-Klick-Vorlagen für gemanagte Hosts. Jede liefert ein autonomes
-Dockerfile aus, das `@agentmemory/agentmemory` aus npm bezieht und das
-iii-engine-Binary aus dem offiziellen `iiidev/iii`-Image vom Docker Hub
-kopiert; 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 dann die
-Privilegien von `root` auf `node` via `gosu`, bevor er die agentmemory-CLI exec't.
+Nutzen Sie Docker Compose oder die Plattformvorlagen zum Self-Hosting. Erinnerungen und Zugangsdaten liegen auf dem `/data`-Volume. Sichern Sie dieses Volume und verwenden Sie es bei Upgrades weiter. Der [Deployment-Leitfaden](../deploy/README.md) beschreibt Authentifizierung, Netzwerkzugriff, Backups und Migration.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Der Ein-Klick-Deploy-Button von Render erfordert eine `render.yaml` im Repository-Root, das wir bewusst sauber halten. Verwenden Sie den Render-Blueprint-Fluss, dokumentiert in [`deploy/render/`](.././deploy/render/README.md), um manuell auf das im Repo liegende Blueprint zu zeigen.
@@ -955,28 +901,26 @@ Kostenuntergrenzen) finden Sie in [`deploy/`](.././deploy/README.md):
eigenen VPS via [Coolify](https://coolify.io/self-hosted); derselbe
Docker-Compose-Stack, Sie besitzen Host und Daten.
-Nur Port `3111` wird veröffentlicht. Der Viewer auf `3113` bleibt im
-Container an Loopback gebunden; jedes Template-README dokumentiert
-das SSH-Tunnel-Muster, um ihn zu erreichen.
+REST nutzt Port `3111`, der Viewer `3113`. Halten Sie beide privat oder schützen Sie sie mit Authentifizierung und TLS. Details zur Freigabe und zur [Migration älterer Docker-Installationen](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) stehen im Deployment-Leitfaden.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Warum agentmemory" height="32" /></picture></h2>
-Jeder Coding-Agent vergisst alles, wenn die Session endet, und jede neue Session beginnt damit, dass Sie Ihren Stack erneut erklären. agentmemory läuft im Hintergrund und schafft diesen Schritt ab.
+Projektwissen verteilt sich auf Chats und Anweisungsdateien. AgentMemory macht frühere Entscheidungen, Lösungen und Erfahrungen im aktuell verwendeten Agenten durchsuchbar.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs. eingebautes Agent-Memory
@@ -985,7 +929,7 @@ Jeder KI-Coding-Agent kommt mit eingebautem Memory: Claude Code hat `MEMORY.md`,
| | Eingebaut (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skalierung | 200-Zeilen-Limit | Unbegrenzt |
+| Pflege | Manuell gepflegte Anweisungen | Indizierte Session-Historie und Erinnerungen |
| Suche | Lädt alles in den Kontext | BM25 + Vector + Graph (nur Top-K) |
| Token-Kosten | 22K+ bei 240 Beobachtungen | ~1,900 Tokens (92 % weniger) |
| Agentenübergreifend | Dateien pro Agent | MCP + REST (jeder Agent) |
@@ -1011,13 +955,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-stufige Memory-Konsolidierung
@@ -1035,6 +979,8 @@ Erinnerungen klingen mit der Zeit ab (Ebbinghaus-Kurve). Häufig abgerufene Erin
### Was erfasst wird
+Diese Tabelle beschreibt die Claude-Code-Hooks. Andere Integrationen erfassen die Ereignisse, die ihr Host bereitstellt; siehe die jeweiligen Anleitungen. Automatische Kontextinjektion über gemeinsame Hooks ist mit `AGENTMEMORY_INJECT_CONTEXT=true` optional aktivierbar.
+
| Hook | Erfasst |
|------|----------|
| `SessionStart` | Projektpfad, Session-ID |
@@ -1051,7 +997,7 @@ Erinnerungen klingen mit der Zeit ab (Ebbinghaus-Kurve). Häufig abgerufene Erin
| Fähigkeit | Beschreibung |
|---|---|
-| **Automatische Erfassung** | Jede Tool-Nutzung via Hooks aufgezeichnet, kein manueller Aufwand |
+| **Automatische Erfassung** | Unterstützte Session- und Tool-Ereignisse werden durch native Integrationen erfasst |
| **Semantische Suche** | BM25 + Vector + Knowledge Graph mit RRF-Fusion |
| **Memory-Evolution** | Versionierung, Supersession, Beziehungsgraphen |
| **Recall-Hygiene** | Überholte Memory-Versionen verlassen die Suchindizes; die Versionskette im KV behält die volle Historie |
@@ -1112,7 +1058,7 @@ Die normale npm-Installation enthält die optionale `@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 -y @agentmemory/agentmemory@latest` (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 verbinden Sie sich mit einem selbst gehosteten Server) und setzen Sie `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
@@ -1252,7 +1198,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Echtzeit-Viewer" height="32" /></picture></h2>
-Startet automatisch auf Port `3113`. 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.
+Startet automatisch auf Port `3113`. Beim Verbinden lädt der Viewer einen Snapshot (`GET /agentmemory/viewer/snapshot`) und verarbeitet danach Live-Ereignisse per SSE unter `/agentmemory/viewer/events` über den REST-Worker: Neue Memories, Lessons, Beobachtungen, Audit-Einträge, Graph-Änderungen und Health-Updates erscheinen ohne Polling oder Neuladen. Weitere Requests entstehen nur durch angeklickte Aktionen, „Mehr laden“ und Suchen. Bei einer unterbrochenen Verbindung zeigt der Viewer das Alter seiner Daten, verbindet sich mit Backoff erneut und synchronisiert sich über einen Snapshot.
- **12 Tabs in vier Gruppen** mit Live-Zählern, Deep-Links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1211,7 @@ Startet automatisch auf Port `3113`. Der Viewer lädt beim Verbinden einen Snaps
open http://localhost:3113
```
-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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-Der Viewer auf `:3113` zeigt, was Ihr Agent **gespeichert hat**. Die [iii console](https://iii.dev/docs/console) zeigt, was Ihr Agent **getan hat**: jede Memory-Operation als OpenTelemetry-Trace, jeden KV-Eintrag editierbar, jede Funktion aufrufbar, jeden Stream abgreifbar. Zwei Fenster auf dasselbe Memory: eines produktnah, eines engine-nah.
-
-Sehen Sie, wie ein `memory_smart_search` feuert, und beobachten Sie BM25-Scan → Embedding-Lookup → RRF-Fusion → Reranker als Wasserfall. Editieren Sie einen festsitzenden Konsolidierungs-Timer im KV-Browser. Spielen Sie einen `PostToolUse`-Hook mit angepasster Payload erneut ab. Pinnen Sie den WebSocket-Stream an und sehen Sie Beobachtungen live eintrudeln.
-
-agentmemory liefert das umsonst, weil jeder Funktionsaufruf und jeder Trigger durch iii feuert; nichts Eigenes, nichts zu instrumentieren.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers-Seite: verbundene Worker, einschließlich agentmemory-Instanzen mit Live-Funktionszahlen und Runtime-Metadaten" width="720" />
- <br/>
- <em>Workers-Seite: jeder verbundene Worker, einschließlich agentmemory selbst, mit PID, Funktionsanzahl, Runtime und last-seen.</em>
-</p>
-
-**Bereits installiert.** Die Console wird mit 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 console
-```
-
-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.
-
-Dasselbe von Hand, nützlich, wenn `agentmemory` nicht im PATH liegt:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**Was Sie aus der Console heraus tun können:**
-
-| Seite | Verwenden Sie sie für |
-|------|-----------|
-| **Workers** | Jeden verbundenen Worker und seine Live-Metriken sehen, einschließlich des agentmemory-Workers selbst. |
-| **Functions** | Jede Funktion von agentmemory direkt mit einer JSON-Payload aufrufen; handlich zum Testen von `memory.recall`, `memory.consolidate`, `graph.query` ohne Client zu verdrahten. |
-| **Triggers** | HTTP-, Cron-, Event- und State-Trigger erneut abspielen: den Konsolidierungs-Cron manuell auslösen, eine HTTP-Route wiederholen, einen State-Change emittieren. |
-| **States** | KV-Browser mit vollem CRUD ü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. |
-| **Logs** | Strukturierte OTEL-Logs, gefiltert und korreliert mit Trace-/Span-IDs. |
-| **Config** | Runtime-Konfiguration: sehen Sie genau, mit welchen Workern, Providern und Ports Ihre Engine läuft. |
-| **Flow** | (Optional, `--enable-flow`) Interaktiver Architekturgraph jedes Workers, Triggers und Streams. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console Trace-Wasserfall-Ansicht mit Span-Dauer" width="720" />
- <br/>
- <em>Traces: Wasserfall / Flame / Service-Breakdown für jede Memory-Operation.</em>
-</p>
-
-**Traces sind bereits aktiv:**
-
-`iii-config.yaml` wird mit aktiviertem `iii-observability`-Worker ausgeliefert (`exporter: memory`, `sampling_ratio: 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.
-
-> **Achtung:** Auf der Console selbst wird keine Auth erzwungen; lassen Sie sie an `127.0.0.1` gebunden (Standard) und stellen Sie sie niemals öffentlich bereit.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory ist **bereits eine laufende [iii](https://iii.dev)-Instanz**. Drei Primitiven (Worker, Funktion, Trigger) bilden die Runtime; KV-State, Streams und OTEL-Traces kommen von den Workern iii-state, iii-stream und iii-observability, die mit iii ausgeliefert werden. Sie haben weder Postgres noch Redis, Express, pm2 oder Prometheus installiert, weil iii sie ersetzt.
-
-Das bedeutet, ein weiterer Befehl erweitert agentmemory um eine komplett neue Fähigkeit.
-
-### agentmemory mit weiteren Workern erweitern
-
-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.
-
-```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 | Was Sie zusätzlich zu agentmemory erhalten |
-|---|---|
-| [`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:<scope>`, `stream:<name>:<group>`) 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 |
-|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
-| SQLite / Postgres + pgvector | iii KV State + In-Memory-Vector-Index |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | iii-Engine-Worker-Supervision |
-| Prometheus / Grafana | iii OTEL + Health-Monitor |
-| Eigene Plugin-Systeme | `iii worker add <name>` |
-
-**250 Quelldateien · ~55,000 LOC · 3,400+ Tests · 324 Funktionen · 67 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+Der Viewer-Server bindet sich standardmäßig an `127.0.0.1` und hängt bei der Weiterleitung von Requests an die REST API das Server-Secret an. Bei einer Bindung außerhalb des Loopbacks bleibt die HTML-Hülle öffentlich, aber jede Proxy-Anfrage erfordert ein Bearer-Token; der Viewer fordert es an und speichert es in der Session-Storage. Richten Sie explizite Host-/Origin-Allowlists und TLS ein, bevor Sie einen Viewer öffentlich erreichbar machen. Der per REST ausgelieferte `/agentmemory/viewer`-Endpunkt folgt den normalen Bearer-Token-Regeln und leitet Browser ohne Token zum Viewer-Port weiter. CSP-Header verwenden eine Skript-Nonce pro Response und deaktivieren Inline-Handler-Attribute (`script-src-attr 'none'`).
---
@@ -1467,6 +1232,8 @@ agentmemory erkennt Provider automatisch aus Ihrer Umgebung. Ein Provider macht
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Lokale Modelle (Ollama / LM Studio / vLLM)
agentmemory spricht mit jedem OpenAI-API-kompatiblen Server, daher funktioniert alles, was `/v1/chat/completions` bereitstellt, ohne Codeänderungen. Keine bezahlten Schlüssel, keine Cloud, keine Rate-Limits; läuft vollständig auf Ihrer Hardware.
@@ -1516,24 +1283,7 @@ Lokale Embeddings werden als optionale Abhängigkeit ausgeliefert, sind aber sta
### Kostenbewusste Modellwahl
-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. |
-
-Gemessene Zeilen stammen aus dem erfassten Lauf; (est.)-Zeilen skalieren denselben Token-Mix mit dem Listenpreis des jeweiligen Modells.
-
-agentmemory gibt eine Runtime-Warnung aus, wenn `OPENROUTER_MODEL` auf ein Premium-Tier-Muster passt. Setzen Sie `AGENTMEMORY_SUPPRESS_COST_WARNING=1`, um sie zum Schweigen zu bringen, sobald Sie eine bewusste Wahl getroffen haben.
-
-Qualitäts-Kosten-Abwägung für Memory-Arbeit: Kompression ist eine Summarize-Aufgabe mit eher lockerer Qualitätsanforderung (der Agent liest die Zusammenfassung erneut, nicht der Benutzer). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder landen bei dieser Aufgabe innerhalb von Rundungsfehlern an Sonnet, bei 10-70× weniger Kosten. Heben Sie Premium-Modelle für Anfragen auf, die Sie direkt lesen.
-
-Quellen: [OpenRouter-Preise für Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek-Preis-Hinweise](https://api-docs.deepseek.com/quick_start/pricing/).
+Starten Sie schlüssellos mit Erfassung und Stichwortsuche. `EMBEDDING_PROVIDER=local` aktiviert nach dem ersten Modelldownload die lokale semantische Suche. LLM-Kompression benötigt einen Provider und `AGENTMEMORY_AUTO_COMPRESS=true`; dabei kann für jede erfasste Beobachtung eine Anfrage anfallen. Prüfen Sie vorher die aktuellen Preise Ihres Providers. Viewer und `agentmemory status` zeigen die aktiven Provider.
### Multi-Agent-Memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1313,22 @@ Wenn `AGENT_ID` nicht gesetzt ist, bleibt Memory unscoped (Legacy-Verhalten, kei
### Ports
-agentmemory + iii-engine binden standardmäßig vier Ports. Wenn ein Neustart mit `port in use` fehlschlägt, sagt Ihnen diese Tabelle, nach welchem Prozess Sie suchen müssen.
-
-| Port | Prozess | Zweck | Env-Override |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | Interner Streams-Worker (von agentmemory + Viewer verwendet) | `III_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 <N>` ä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.
+| Port | Zweck | Konfiguration |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Aufräumen veralteter Prozesse, wenn Ports nach einem abgestürzten Lauf gebunden bleiben:
+`--port <N>` setzt den API-Port und standardmäßig den Viewer auf `N+2`. `--instance N` startet eine separate Laufzeit. Interne Listener müssen privat bleiben; lesen Sie vor einer entfernten Freigabe den [Deployment-Leitfaden](../deploy/README.md).
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage-Backend: file (Standard) vs. Redis
-`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.
+Der standardmäßige Dateispeicher benötigt keinen separaten Datenbankdienst. Redis ist mit `AGENTMEMORY_STATE_BACKEND=redis` und `AGENTMEMORY_REDIS_URL` optional. Ein Backend-Wechsel kopiert keine Erinnerungen. Der [Speicher- und Backup-Leitfaden](../docs/reliability/state-storage.md) beschreibt Persistenz, Redis-Grenzen und authentifizierten Export/Import.
### Konfigurationsdatei
-Legen Sie die agentmemory-Runtime-Konfiguration in `~/.agentmemory/.env` ab, statt Variablen in jeder Shell zu exportieren. Wenn der Viewer einen Setup-Hinweis wie `export ANTHROPIC_API_KEY=...` zeigt, kopieren Sie ihn als `ANTHROPIC_API_KEY=...` ohne `export`-Präfix in diese Datei und starten Sie agentmemory neu.
+Legen Sie die agentmemory-Runtime-Konfiguration in `~/.agentmemory/.env` ab, statt Variablen in jeder Shell zu exportieren. Wenn der Viewer einen Setup-Hinweis wie `export ANTHROPIC_API_KEY=...` zeigt, kopieren Sie ihn ohne das Präfix `export` als `ANTHROPIC_API_KEY=...` in diese Datei und starten Sie agentmemory neu. Setzen Sie `AGENTMEMORY_ENV_FILE`, um einen anderen Pfad für die Env-Datei zu verwenden.
-Prozess-Umgebungsvariablen funktionieren weiterhin und haben Vorrang vor Werten in der Datei.
+Prozess-Umgebungsvariablen haben Vorrang vor Werten in der Datei. Starten Sie den Server nach Änderungen neu.
Unter Windows liegt dieselbe Datei unter `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,176 +1355,29 @@ GRAPH_EXTRACTION_ENABLED=true
### Umgebungsvariablen
-`~/.agentmemory/.env` anlegen:
+Häufig verwendete Optionen für `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Die vollständige Referenz steht in [`.env.example`](../.env.example), einschließlich Provider-Zugangsdaten, Erfassungsfiltern, Aufbewahrung, Speicher, Team-Scope und optionalen Funktionen. `AGENTMEMORY_ENV_FILE` wählt eine andere Datei. Committen Sie keine ausgefüllte `.env` oder Bearer-Secrets.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer <secret>`, und Mesh-Sync-Endpunkte erfordern ein explizit gesetztes `AGENTMEMORY_SECRET` auf beiden Peers.
+146 Endpunkte auf Port `3111`. Die REST API bindet sich standardmäßig an `127.0.0.1`. Geschützte Endpunkte verlangen `Authorization: Bearer <secret>`, 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:
+**Authentifizierung ist standardmäßig aktiv.** Wenn `AGENTMEMORY_SECRET` weder in der Shell noch in `~/.agentmemory/.env` gesetzt ist, erzeugt die CLI beim ersten Start ein zufälliges Secret unter `~/.agentmemory/secret` und spiegelt es als `secret` in das ausgewählte Datenverzeichnis, jeweils mit Dateimodus `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
@@ -1830,7 +1416,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Mit Team teilen |
| `GET` | `/agentmemory/audit` | Audit-Trail |
-Volle Endpunktliste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Volle Endpunktliste: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1434,19 @@ Fehlgeschlagene Events werden alle `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s
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, `<data dir>/capture-spool/<host>-<port>.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.
+**Graph-Provenienz kompaktieren.** Die Kompaktierung älterer Provenienzdaten wird beim Start aufgeschoben, da sie vollständige ältere Scopes einliest. `/agentmemory/status` meldet `deferred`, bei `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` dagegen `off`. Führen Sie die unten beschriebene manuelle Kompaktierung während der Wartung aus. Die Migration des Suchindex ist separat: Verwenden Sie `agentmemory graph-index migrate --allow-legacy-scan` wie im [Wartungsleitfaden](../docs/reliability/graph-index-migration.md) beschrieben.
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1460,7 @@ npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
```
-**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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Lizenz" height="32" /></picture></h2>
diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.md
index c9becaf8..d3565706 100644
--- a/READMEs/README.el-GR.md
+++ b/READMEs/README.el-GR.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Ο agent κώδικα σας θυμάται τα πάντα. Τέλος οι επαναλαμβανόμενες εξηγήσεις.
- Βασισμένο στο <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Μόνιμη μνήμη μεταξύ συνεδριών και agents προγραμματισμού.
</strong><br/>
- Μόνιμη μνήμη για τα Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, και κάθε client MCP.
+ Μόνιμη μνήμη για τα Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, και κάθε client MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Πώς Λειτουργεί</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Ρυθμίσεις</a> &bull;
<a href="#api">API</a>
</p>
---
+Το AgentMemory καταγράφει υποστηριζόμενα συμβάντα συνεδριών και κάνει αποφάσεις, διορθώσεις και μαθήματα αναζητήσιμα μεταξύ agents. Στο viewer μπορείτε να εξετάζετε, επεξεργάζεστε, εξάγετε και διαγράφετε μνήμες. Η αναζήτηση λέξεων λειτουργεί χωρίς κλειδί API· τα embeddings προσθέτουν σημασιολογική αναζήτηση.
+
+<a id="install"></a>
+
## Εγκατάσταση
Απαιτήσεις:
- 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 είναι οι άλλες υποστηριζόμενες διαδρομές.
+- Τα macOS/Linux χρειάζονται επίσης `curl`, POSIX `sh` και `tar` για αυτόματη ρύθμιση του περιβάλλοντος.
+- Στα Windows χρησιμοποιήστε WSL2 ή τις [οδηγίες εγγενούς εγκατάστασης](#windows).
Η κανονική εντολή εγκατάστασης από την αρχή:
@@ -108,11 +111,11 @@
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`.
+Επιλέξτε agents και πάροχο ή λειτουργία χωρίς κλειδί. Ο οδηγός αποθηκεύει τις ρυθμίσεις, ξεκινά τον διακομιστή μνήμης και προσφέρει καθολική εγκατάσταση της εντολής `agentmemory`. Το `-y` αποδέχεται την προτροπή npm· το `@latest` επιλέγει την τρέχουσα έκδοση. Η συμπίεση 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 <path>` ή `AGENTMEMORY_DATA_DIR` για να το παρακάμψετε, και επαναχρησιμοποιήστε την ίδια τιμή σε κάθε επανεκκίνηση. Για λόγους συμβατότητας προς τα πίσω, ένα υπάρχον `./data/state_store.db` ή `./data/iii-config.yaml` υπερισχύει της προεπιλογής της πλατφόρμας για το instance 0· μια ρητή σημαία ή παράκαμψη περιβάλλοντος εξακολουθεί να υπερισχύει.
+Το API είναι στο `http://localhost:3111` και το viewer στο `http://localhost:3113`. Και τα δύο δέχονται μόνο τοπικές συνδέσεις από προεπιλογή. Οι ρυθμίσεις βρίσκονται στο `~/.agentmemory/.env`· η [αποθήκευση δεδομένων](#data-storage) περιγράφει καταλόγους και ξεχωριστά instances.
Στη συνέχεια, επιβεβαιώστε ότι η ανάκληση λειτουργεί και δώστε στον agent σας τα skills του:
@@ -127,14 +130,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Ανακτήστε και ακολουθήστε τις οδηγίες στο: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Συνδέστε περισσότερους agents όποτε θέλετε με `agentmemory connect <agent>` — 20 adapters αναφέρονται στο [Λειτουργεί με κάθε agent](#works-with-every-agent). Πλήρης αναφορά εντολών στο [Γρήγορη Εκκίνηση](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-Η πιο γρήγορη διαδρομή είναι το WSL2. Η native ρύθμιση του engine σε Windows απαιτεί τη λήψη του καθορισμένου ZIP v0.22.1 και την χειροκίνητη εξαγωγή του `iii.exe`· το CLI δεν το εξάγει αυτόματα. Υποστηρίζεται επίσης το Docker Desktop. Δείτε τις [σημειώσεις Windows](#windows) για τα βήματα.
-
-</details>
+Συνδέστε άλλον agent με `agentmemory connect <agent>`. Δείτε τις [ενσωματώσεις](#works-with-every-agent) και τις [καθημερινές εντολές](#everyday-commands).
<details>
<summary><strong>Καθολική εγκατάσταση / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npm install -g @agentmemory/agentmemory@latest
</details>
-<details>
-<summary><strong>Έχετε ήδη τον δικό σας iii engine σε εκτέλεση</strong></summary>
-
-Το agentmemory καθορίζει τον iii-engine στην v0.22.1 και δεν θα συνδεθεί σε διαφορετική έκδοση (ο worker δεν μπορεί να μιλήσει το πρωτόκολλο ενός άλλου engine). Σταματήστε τον άλλο engine, και μετά εκτελέστε `npx -y @agentmemory/agentmemory@latest`. Εγκαθιστά και εκτελεί την καθορισμένη v0.22.1 στο `~/.agentmemory/bin`, αφήνοντας τον δικό σας `iii` ανεπηρέαστο.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Λειτουργεί με κάθε agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ npm install -g @agentmemory/agentmemory@latest
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>εγγενές plugin + 7 hooks + MCP</sub>
+<sub>εγγενές plugin + hooks κύκλου ζωής + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ npm install -g @agentmemory/agentmemory@latest
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>εγγενές plugin + MCP</sub>
+<sub>εγγενής ανάκληση + καταγραφή + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ npm install -g @agentmemory/agentmemory@latest
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>διακομιστής MCP</sub>
+<sub>εγγενής καταγραφή + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ npm install -g @agentmemory/agentmemory@latest
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>εγγενής ανάκληση + καταγραφή + skills + προαιρετικό MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ npm install -g @agentmemory/agentmemory@latest
---
-Εξηγείτε την ίδια αρχιτεκτονική σε κάθε συνεδρία. Ανακαλύπτετε ξανά τα ίδια bugs. Ξαναδιδάσκετε τις ίδιες προτιμήσεις. Η ενσωματωμένη μνήμη (CLAUDE.md, .cursorrules) φτάνει στο όριο των 200 γραμμών και μπαγιατεύει. Το agentmemory το διορθώνει αυτό. Καταγράφει σιωπηλά τι κάνει ο agent σας, το συμπιέζει σε αναζητήσιμη μνήμη, και εισάγει το σωστό πλαίσιο όταν ξεκινά η επόμενη συνεδρία. Μία εντολή. Λειτουργεί σε όλους τους agents.
+<a id="data-storage"></a>
-**Τι αλλάζει:** Στη συνεδρία 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 <path>` ή ρυθμίστε `AGENTMEMORY_DATA_DIR`· κάθε ρητή ρύθμιση υπερισχύει της παλιάς ανακάλυψης:
+| Πλατφόρμα | Κατάλογος δεδομένων |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Το instance 0 επαναχρησιμοποιεί το υπάρχον `./data/state_store.db`. Επιλέξτε άλλο κατάλογο με `--data-dir <path>` ή `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
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-Οι native και Docker εκκινήσεις χρησιμοποιούν τον ίδιο επιλυμένο κατάλογο host· το Docker τον κάνει bind-mount στο `/data`. Το `--instance 1` προσθέτει `instance-1` στον επιλυμένο κατάλογο και επιλέγει το ξεχωριστό προεπιλεγμένο quartet θυρών `3211/3212/3213/49234`.
+Το `--instance 1` χρησιμοποιεί τον υποκατάλογο `instance-1`, τη θύρα API `3211` και viewer `3213`. Redis και μεταφορά περιγράφονται στον [οδηγό αποθήκευσης και αντιγράφων ασφαλείας](../docs/reliability/state-storage.md).
Τελευταίες σημειώσεις έκδοσης: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>Εξωτερικές εξαρτήσεις</strong></td>
-<td>Καμία (SQLite + iii-engine)</td>
+<td>Δεν απαιτείται ξεχωριστή υπηρεσία βάσης δεδομένων</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>Πολλαπλές</td>
@@ -550,14 +549,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | Χρονικός γράφος γνώσης· τα ισχυρότερα δημοσιευμένα αποτελέσματα σε χρονικά ερωτήματα (LongMemEval 63.8%), αλλά ο γράφος χτίζεται ασύγχρονα, οπότε τα νέα δεδομένα μπορεί να καθυστερούν |
| Cognee | 30K | Εισαγωγή εγγράφων σε γράφο γνώσης, μόνο σε Python, σχεδιασμένο για δομημένη εξαγωγή οντοτήτων παρά για καταγραφή συνεδριών |
-Κανένα από αυτά δεν κάνει αυτόματη καταγραφή από hooks agent κώδικα, δεν διαθέτει local-first viewer, και δεν λειτουργεί χωρίς κλειδί — τον συνδυασμό γύρω από τον οποίο είναι χτισμένο το agentmemory.
+Το AgentMemory συνδυάζει καταγραφή συνεδριών, αναζητήσιμο ιστορικό έργου και τοπικό viewer, με λειτουργία χωρίς κλειδί από την πρώτη εκκίνηση.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Γρήγορη Εκκίνηση" height="32" /></picture></h2>
-Συμβατότητα: αυτή η έκδοση στοχεύει το `iii-sdk` 0.22.1 και καθορίζει τον iii-engine στην v0.22.1.
-
### Δοκιμάστε το σε 30 δευτερόλεπτα
```bash
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Ανοίξτε το `http://localhost:3113` για να παρακολουθήσετε τη μνήμη να χτίζεται ζωντανά.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Επιβεβαιώστε μια νέα εγκατάσταση και τη μονιμότητα μετά από επανεκκίνηση
-Με τον διακομιστή σε λειτουργία, επιβεβαιώστε το REST, το health, το viewer, και την κατάσταση του runtime που βασίζεται στο iii:
+Με τον διακομιστή ενεργό, ελέγξτε την υγεία, το viewer και την κατάσταση:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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) και επιβεβαιώστε ότι είναι αναζητήσιμη:
+Το `status` δείχνει υγεία διακομιστή, παρόχους, λειτουργία embeddings, παράδοση καταγραφών και ανάκτηση. Τα προστατευμένα REST αιτήματα απαιτούν το μυστικό του διακομιστή. Χρησιμοποιήστε το δικό σας `AGENTMEMORY_SECRET` αν έχει οριστεί, αλλιώς φορτώστε το τοπικό μυστικό που δημιουργήθηκε:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Στη συνέχεια εκτελέστε `npx -y @agentmemory/agentmemory@latest stop`, ξεκινήστε ξανά την κανονική εντολή στο Terminal 1, περιμένετε το `/agentmemory/livez`, και επαναλάβετε την αναζήτηση. Το probe πρέπει να επιστρέφεται ακόμα. Αν επιλέξατε προσαρμοσμένο `--data-dir`, περάστε τον ίδιο κατάλογο στην επανεκκίνηση.
+<a id="everyday-commands"></a>
+
### Καθημερινές εντολές
Η εγκατάσταση και η ρύθμιση βρίσκονται στο [Εγκατάσταση](#install) παραπάνω (η πρώτη εκτέλεση σας καθοδηγεί). Καθημερινά:
@@ -604,6 +610,9 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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 και μαθήματα.
+Οι εισαγόμενες συνεδρίες εμφανίζονται στο Replay δίπλα στις εγγενείς. Τα transcripts ευρετηριάζονται και σημειώνονται με κανάλι προέλευσης `import`· η επεξεργασία μπορεί επίσης να δημιουργήσει κρυστάλλους συνεδριών και μαθήματα.
> **Σημαντική σημείωση αν βασίζεστε στο `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 να σταματήσει να έχει σημασία.
@@ -635,14 +644,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
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`).
+Η εντολή ενημερώνει το τοπικό περιβάλλον και μπορεί να αλλάξει εξαρτήσεις JavaScript στον τρέχοντα χώρο εργασίας. Δημιουργήστε αντίγραφο δεδομένων και διαβάστε τον [οδηγό αναβάθμισης](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code χωρίς εγκατάσταση plugin (αυτόνομη διαδρομή MCP)
@@ -703,6 +710,30 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Έπειτα στο **Settings → Plugins → Add marketplace** επιλέξτε τον κατάλογο agentmemory με το `.cursor-plugin/plugin.json`, ενεργοποιήστε το plugin **agentmemory** και επαναφορτώστε το παράθυρο. Το plugin παρέχει καταγραφή κύκλου ζωής, αντιστοίχιση έργου βάσει workspace, skills και MCP. Ενεργοποιήστε είτε τα hooks του plugin είτε τα χειροκίνητα hooks στο `~/.cursor/hooks.json`, για αποφυγή διπλής καταγραφής.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Επιλέξτε την εντολή για τον client σας. Pi και OMP εγκαθιστούν εγγενή ανάκληση, καταγραφή, επανάληψη αποστολών offline και skills· το `--with-mcp` προσθέτει όλα τα εργαλεία. Εκτελέστε `/reload` στο Pi ή επανεκκινήστε το OMP και ελέγξτε `/agentmemory-status`. Το DSH εγκαθιστά MCP και το ενσωματωμένο plugin καταγραφής· επανεκκινήστε το DSH μετά τη σύνδεση.
+
+Το Pi υποστηρίζει επίσης το εγκαταστάσιμο πακέτο `@agentmemory/pi`. Τοπική εγκατάσταση και διαθεσιμότητα npm περιγράφονται στον [οδηγό Pi](../integrations/pi/). Χρησιμοποιήστε μία μέθοδο εγκατάστασης ανά client.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (επικολλήστε αυτό το prompt)</b></summary>
@@ -749,6 +780,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### Άλλοι agents
Ξεκινήστε τον διακομιστή μνήμης: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +798,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Αυτό είναι **συμπληρωματικό** του `agentmemory connect <agent>`:
-- Το `agentmemory connect <agent>` γράφει τις ρυθμίσεις του διακομιστή MCP ώστε να είναι διαθέσιμα τα εργαλεία.
-- Το `npx skills add rohitg00/agentmemory` εγκαθιστά τα skills ώστε ο agent να ξέρει πότε να τα καλέσει.
+- Το `agentmemory connect <agent>` συνήθως γράφει τη ρύθμιση MCP. Hermes, OpenClaw, Pi και Oh My Pi εγκαθιστούν προεπιλεγμένα εγγενή ενσωμάτωση και skills· το MCP ενεργοποιείται με `--with-mcp`.
+- Το `npx skills add rohitg00/agentmemory` εγκαθιστά skills για agents χωρίς ενσωματωμένα εγγενή skills. Παραλείψτε το για Hermes, OpenClaw, Pi και Oh My Pi· οι connectors τους τα εγκαθιστούν ήδη.
Για τους λίγους agents που το CLI skills δεν καλύπτει ακόμα (Zed v1.3.x και παλαιότερα), τοποθετήστε τα 17 αρχεία SKILL.md μόνοι σας στον εγγενή κατάλογο skills του agent· η ίδια μορφή λειτουργεί παντού.
@@ -790,7 +823,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| 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 της συνεδρίας στο τέλος της συνεδρίας. |
+| **Cursor (full plugin)** | `.cursor-plugin/` | Το plugin προσφέρει hooks κύκλου ζωής, αναγνώριση workspace, skills και MCP στο Cursor IDE και στο `cursor-agent`. Δείτε τη [ρύθμιση Cursor](#cursor). |
| **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. |
@@ -804,7 +837,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. εγγενής ανάκληση + καταγραφή + skills. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. εγγενής ανάκληση + καταγραφή + skills. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +846,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (προτιμώμενο) ή `config.json` (παλαιό) | Το `agentmemory connect continue` δημιουργεί `config.yaml` αν λείπουν οι ρυθμίσεις ή αλλάζει υπάρχον `config.json`. Για υπάρχον YAML εμφανίζει το block προς προσθήκη στο `mcpServers:`, διατηρώντας σχόλια και anchors. Το Continue χρησιμοποιεί πίνακα, όχι αντικείμενο. |
| **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 μπαίνουν στο `<repo>/.factory/mcp.json`. Περάστε `--with-hooks` για εγγενή αυτόματη καταγραφή. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Το `agentmemory connect dsh` ενεργοποιεί τα εργαλεία MCP. Προσθέστε `--with-hooks` για το εγγενές πρόσθετο καταγραφής που περιλαμβάνεται στο AgentMemory. Δεν χρειάζεται ξεχωριστό πακέτο. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Χρησιμοποιήστε τα [αυθεντικοποιημένα παραδείγματα REST](#validate-a-fresh-install-and-restart-persistence) για αποθήκευση και αναζήτηση από scripts. |
| **Οποιοσδήποτε 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.
+Χρησιμοποιήστε το [REST API](#api) από οποιαδήποτε γλώσσα ή τα [εργαλεία MCP](#mcp-server) από agent. Το REST χρησιμοποιεί JSON και bearer authentication· δείτε το [παράδειγμα αποθήκευσης και αναζήτησης](#validate-a-fresh-install-and-restart-persistence). Για άμεση ενσωμάτωση περιβάλλοντος, δείτε τα [παραδείγματα Python](../examples/python/).
### Από τον πηγαίο κώδικα
@@ -853,83 +867,33 @@ 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=<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).
+Το `npm start` ξεκινά τον ίδιο τοπικό διακομιστή με το εγκατεστημένο CLI. Οι απαιτήσεις είναι στην [Εγκατάσταση](#install)· API και viewer ακούν στο `127.0.0.1`.
### 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.
+Το agentmemory εκτελείται σε Windows 10/11. Το WSL2 ακολουθεί τη διαδρομή Linux και μπορεί να εγκαταστήσει αυτόματα τον καρφιτσωμένο engine. Σε native Windows απαιτείται χειροκίνητη εγκατάσταση του καρφιτσωμένου binary iii-engine v0.25.0: κατεβάστε το αντίστοιχο archive από τη [σελίδα έκδοσης iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), επαληθεύστε το checksum και τοποθετήστε το `iii.exe` στο `PATH` (για παράδειγμα `%USERPROFILE%\.local\bin\iii.exe`). Το CLI δεν εξάγει αυτόματα το Windows ZIP.
-**Επιλογή A: προκατασκευασμένο binary για Windows (προτείνεται)**
+Η αυτοματοποιημένη ρύθμιση MCP σε native Windows υποστηρίζει μόνο το `agentmemory connect copilot-cli`. Για άλλους native Windows agents, χρησιμοποιήστε το χειροκίνητο block MCP από τους [Άλλους agents](#other-agents). Εκτελέστε `connect` μέσα στο WSL μόνο αν ο agent-στόχος είναι εγκατεστημένος στο ίδιο περιβάλλον WSL.
-```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:
+**Μόνο standalone MCP (χωρίς engine).** Αν χρειάζεστε μόνο εργαλεία MCP και όχι το REST API, το viewer ή υπηρεσίες runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| Η εναλλακτική λύση 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`.
+Εκτελέστε `agentmemory doctor` ή επανεκκινήστε με `--verbose`. Για κατειλημμένες θύρες χρησιμοποιήστε `--port <N>` ή `--instance <N>`. Συμβατότητα και ανάκτηση περιγράφονται στον [οδηγό αναβάθμισης](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Ανάπτυξη</h2>
-Πρότυπα ανάπτυξης με ένα κλικ για διαχειριζόμενους 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.
+Για δική σας φιλοξενία χρησιμοποιήστε Docker Compose ή τα παρακάτω πρότυπα. Μνήμη και διαπιστευτήρια βρίσκονται στον τόμο `/data`· κρατήστε αντίγραφο και επαναχρησιμοποιήστε τον στην αναβάθμιση. Authentication, δίκτυο, αντίγραφα και μεταφορά περιγράφονται στον [οδηγό ανάπτυξης](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Το κουμπί ανάπτυξης με ένα κλικ του Render απαιτεί `render.yaml` στη ρίζα του αποθετηρίου, το οποίο σκόπιμα το κρατάμε καθαρό. Χρησιμοποιήστε τη ροή Render Blueprint που τεκμηριώνεται στο [`deploy/render/`](.././deploy/render/README.md) για να δείξετε χειροκίνητα στο blueprint εντός του αποθετηρίου.
@@ -947,29 +911,13 @@ npx -y @agentmemory/mcp
VPS μέσω του [Coolify](https://coolify.io/self-hosted)· το ίδιο Docker
Compose stack, εσείς κατέχετε τον host και τα δεδομένα.
-Δημοσιεύεται μόνο η θύρα `3111`. Το viewer στη `3113` παραμένει συνδεδεμένο στο
-loopback εντός του container· το README κάθε προτύπου τεκμηριώνει το μοτίβο
-SSH-tunnel για να το προσεγγίσετε.
+Το REST χρησιμοποιεί `3111` και το viewer `3113`. Διατηρήστε τα ιδιωτικά ή προστατέψτε τα με authentication και TLS. Ρυθμίσεις πλατφορμών και [μεταφορά παλιού Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) περιγράφονται στον οδηγό ανάπτυξης.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Γιατί το agentmemory" height="32" /></picture></h2>
-Κάθε 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.
-```
+Η γνώση του έργου διασκορπίζεται σε συνομιλίες και αρχεία οδηγιών. Το AgentMemory κάνει προηγούμενες αποφάσεις, διορθώσεις και μαθήματα αναζητήσιμα από τον τρέχοντα agent.
### Έναντι της ενσωματωμένης μνήμης agent
@@ -977,7 +925,7 @@ Session 2: "Now add rate limiting"
| | Ενσωματωμένο (CLAUDE.md) | agentmemory |
|---|---|---|
-| Κλίμακα | Όριο 200 γραμμών | Απεριόριστο |
+| Συντήρηση | Χειροκίνητα διαχειριζόμενες οδηγίες | Ευρετηριασμένο ιστορικό συνεδριών και μνήμες |
| Αναζήτηση | Φορτώνει τα πάντα στο context | BM25 + vector + graph (μόνο top-K) |
| Κόστος tokens | 22K+ σε 240 παρατηρήσεις | ~1,900 tokens (92% λιγότερο) |
| Μεταξύ agents | Αρχεία ανά agent | MCP + REST (οποιοσδήποτε agent) |
@@ -1003,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Ενοποίηση Μνήμης 4 Επιπέδων
@@ -1027,6 +975,8 @@ SessionStart hook fires
### Τι Καταγράφεται
+Ο πίνακας περιγράφει τα hooks του Claude Code. Άλλες ενσωματώσεις καταγράφουν συμβάντα που διαθέτει ο client τους. Η αυτόματη εισαγωγή context μέσω κοινών hooks είναι προαιρετική: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Καταγράφει |
|------|----------|
| `SessionStart` | Διαδρομή project, ID συνεδρίας |
@@ -1043,7 +993,7 @@ SessionStart hook fires
| Δυνατότητα | Περιγραφή |
|---|---|
-| **Αυτόματη καταγραφή** | Κάθε χρήση εργαλείου καταγράφεται μέσω hooks, χωρίς χειροκίνητη προσπάθεια |
+| **Αυτόματη καταγραφή** | Υποστηριζόμενα συμβάντα συνεδριών και εργαλείων από εγγενείς ενσωματώσεις |
| **Σημασιολογική αναζήτηση** | BM25 + vector + γράφος γνώσης με συγχώνευση RRF |
| **Εξέλιξη μνήμης** | Versioning, αντικατάσταση (supersession), γράφοι σχέσεων |
| **Υγιεινή ανάκλησης** | Οι αντικατεστημένες εκδόσεις μνήμης αφαιρούνται από τα ευρετήρια αναζήτησης· η αλυσίδα εκδόσεων στο KV διατηρεί το πλήρες ιστορικό |
@@ -1104,7 +1054,7 @@ EMBEDDING_PROVIDER=local
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`.
+> **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` (ή συνδεθείτε σε self-hosted server) και ρυθμίστε `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Εργαλεία
@@ -1244,7 +1194,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Viewer σε Πραγματικό Χρόνο" height="32" /></picture></h2>
-Ξεκινά αυτόματα στη θύρα `3113`. Το viewer φορτώνει ένα snapshot όταν συνδέεται (`GET /agentmemory/viewer/snapshot`) και μετά εφαρμόζει live stream events: νέες μνήμες, μαθήματα, παρατηρήσεις, καταχωρήσεις audit, αλλαγές γράφου, και ενημερώσεις υγείας εμφανίζονται χωρίς polling ή επαναφόρτωση σελίδας. Τα μόνα άλλα αιτήματα είναι οι ενέργειες που κάνετε κλικ, οι σελίδες "load more" και οι αναζητήσεις. Όταν το stream διακόπτεται, το viewer δείχνει πόσο παλιά είναι οι αριθμοί του, επανασυνδέεται με backoff και επανασυγχρονίζεται από ένα snapshot.
+Ξεκινά αυτόματα στη θύρα `3113`. Κατά τη σύνδεση, το viewer φορτώνει ένα snapshot (`GET /agentmemory/viewer/snapshot`) και έπειτα εφαρμόζει live events μέσω SSE στο `/agentmemory/viewer/events` από τον worker REST: νέες μνήμες, lessons, παρατηρήσεις, εγγραφές audit, αλλαγές γράφου και ενημερώσεις health εμφανίζονται χωρίς polling ή επαναφόρτωση της σελίδας. Τα μόνα άλλα requests προκύπτουν από τις ενέργειες που πατάτε, τις σελίδες «φόρτωσε περισσότερα» και τις αναζητήσεις. Αν διακοπεί η ροή, το viewer δείχνει πόσο παλιά είναι τα δεδομένα, επανασυνδέεται με backoff και συγχρονίζεται ξανά από ένα snapshot.
- **12 καρτέλες σε τέσσερις ομάδες** με ζωντανές μετρήσεις, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#health/consolidation`), συντομεύσεις πληκτρολογίου, και ένα μενού για κινητά.
- **Memories:** αναζήτηση από την πλευρά του server, φίλτρα ανά project, agent, και τύπο, ένα πάνελ λεπτομερειών με την αλυσίδα εκδόσεων και ένα word diff, συνδέσμους προέλευσης, κουμπιά αντιγραφής για το id, την κλήση MCP, και μια εντολή curl, επεξεργασία (νέα έκδοση), forget με επιβεβαίωση, μαζικό forget, και εξαγωγή JSON.
@@ -1257,188 +1207,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-Το 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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="σελίδα Workers της iii console: συνδεδεμένοι workers συμπεριλαμβανομένων των instances του agentmemory, με ζωντανές μετρήσεις functions και μεταδεδομένα runtime" width="720" />
- <br/>
- <em>Σελίδα Workers: κάθε συνδεδεμένος worker, συμπεριλαμβανομένου του ίδιου του agentmemory, με PID, αριθμό functions, runtime, και last-seen.</em>
-</p>
-
-**Είναι ήδη εγκατεστημένη.** Η 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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="προβολή waterfall traces της iii console που δείχνει τη διάρκεια ανά span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service breakdown για κάθε λειτουργία μνήμης.</em>
-</p>
-
-**Τα 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` (η προεπιλογή) και ποτέ μην την εκθέσετε δημόσια.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Τροφοδοτείται από το iii" height="32" /></picture></h2>
-
-Το 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:<scope>`, `stream:<name>:<group>`) είναι σταθερά, οπότε δύο 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 <name>` |
-
-**250 αρχεία πηγαίου κώδικα · ~55,000 LOC · 3,400+ δοκιμές · 324 functions · 67 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
+Ο διακομιστής viewer συνδέεται στο `127.0.0.1` από προεπιλογή και επισυνάπτει το secret του διακομιστή όταν προωθεί αιτήματα στο REST API. Σε σύνδεση εκτός loopback, το HTML shell παραμένει δημόσιο, αλλά κάθε αίτημα proxy απαιτεί bearer· το viewer το ζητά και το αποθηκεύει στο session storage. Διαμορφώστε ρητές allowlists host/origin και TLS πριν εκθέσετε το viewer. Το endpoint `/agentmemory/viewer` που εξυπηρετείται από το REST ακολουθεί τους κανονικούς κανόνες bearer-token και ανακατευθύνει browsers χωρίς token στη θύρα του viewer. Οι κεφαλίδες CSP χρησιμοποιούν ένα script nonce ανά απάντηση και απενεργοποιούν τα inline handler attributes (`script-src-attr 'none'`).
---
@@ -1459,6 +1228,8 @@ fi
| **Τοπικό (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=<your model>` | Οτιδήποτε συμβατό με το OpenAI API. Μηδενικό κόστος, τρέχει στο δικό σας hardware. Δείτε [Τοπικά μοντέλα](#local-models-ollama--lm-studio--vllm) παρακάτω. |
| Εναλλακτική λύση συνδρομής Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Μόνο με ρητή ενεργοποίηση. Δημιουργεί συνεδρίες `@anthropic-ai/claude-agent-sdk`· παλαιότερα προκαλούσε απεριόριστη αναδρομή στο Stop-hook, οπότε δεν είναι πλέον η προεπιλογή. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Τοπικά Μοντέλα (Ollama / LM Studio / vLLM)
Το agentmemory επικοινωνεί με οποιονδήποτε διακομιστή συμβατό με το OpenAI API, οπότε οτιδήποτε εκθέτει το `/v1/chat/completions` λειτουργεί χωρίς αλλαγές κώδικα. Χωρίς επί πληρωμή κλειδιά, χωρίς cloud, χωρίς rate limits· τρέχει εξολοκλήρου στο δικό σας hardware.
@@ -1508,24 +1279,7 @@ OPENAI_MODEL=qwen3-8b # match the model name from LM St
### Επιλογή Μοντέλου με Επίγνωση Κόστους
-Όταν η συμπίεση παρασκηνίου γραμμένη από 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/).
+Ξεκινήστε χωρίς κλειδί για καταγραφή και αναζήτηση λέξεων. Το `EMBEDDING_PROVIDER=local` ενεργοποιεί τοπική σημασιολογική αναζήτηση μετά τη λήψη μοντέλου. Η συμπίεση LLM απαιτεί πάροχο και `AGENTMEMORY_AUTO_COMPRESS=true`· μπορεί να στέλνει αίτημα ανά παρατήρηση, οπότε ελέγξτε τις τρέχουσες τιμές. Viewer και `agentmemory status` δείχνουν τους ενεργούς παρόχους.
### Μνήμη Πολλών Agents (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1555,39 +1309,22 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### Θύρες
-Το 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 | Σκοπός | Μεταβλητή περιβάλλοντος |
+|---|---|---|
+| `3111` | REST API, MCP HTTP και ζωντανά συμβάντα viewer | `III_REST_PORT` |
+| `3113` | Διεπαφή viewer | `III_VIEWER_PORT` |
-Το `--port <N>` αλλάζει την άγκυρα 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 ακολουθούν το ίδιο μοτίβο.
+Το `--port <N>` ορίζει τη θύρα REST και προεπιλεγμένα το viewer στο `N+2`. Το `--instance N` δημιουργεί ξεχωριστό περιβάλλον. Οι εσωτερικές θύρες πρέπει να παραμένουν ιδιωτικές· διαβάστε τον [οδηγό ανάπτυξης](../deploy/README.md) πριν από απομακρυσμένη πρόσβαση.
-Ο καθορισμένος engine ξεκινά με `--no-update-check` (χωρίς αναζητήσεις ενημέρωσης ή security-advisory προς το GitHub κατά την εκκίνηση) και με την ανώνυμη τηλεμετρία χρήσης του iii απενεργοποιημένη: το agentmemory ρυθμίζει το `III_TELEMETRY_ENABLED=false` για τον engine που δημιουργεί, εκτός αν εξάγετε εσείς τη μεταβλητή, και το ενσωματωμένο αρχείο compose κάνει το ίδιο.
+### Αποθήκευση: αρχείο ή Redis
-Καθαρισμός παλιωμένων διαδικασιών όταν οι θύρες παραμένουν δεσμευμένες μετά από μια εκτέλεση που κατέρρευσε:
-
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
-
-Το `agentmemory stop` τερματίζει καθαρά τόσο τον 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.
+Η προεπιλεγμένη αποθήκευση αρχείων δεν απαιτεί ξεχωριστή βάση. Το Redis είναι προαιρετικό μέσω `AGENTMEMORY_STATE_BACKEND=redis` και `AGENTMEMORY_REDIS_URL`. Η αλλαγή backend δεν αντιγράφει τη μνήμη. Μονιμότητα, περιορισμοί Redis και αυθεντικοποιημένη εξαγωγή/εισαγωγή περιγράφονται στον [οδηγό αποθήκευσης](../docs/reliability/state-storage.md).
### Αρχείο Ρυθμίσεων
-Βάλτε τις ρυθμίσεις runtime του agentmemory στο `~/.agentmemory/.env` αντί να εξάγετε μεταβλητές σε κάθε shell. Αν το viewer δείξει μια υπόδειξη ρύθμισης όπως `export ANTHROPIC_API_KEY=...`, αντιγράψτε την σε αυτό το αρχείο ως `ANTHROPIC_API_KEY=...` χωρίς το πρόθεμα `export`, και μετά κάντε επανεκκίνηση του agentmemory.
+Βάλτε τις ρυθμίσεις runtime του agentmemory στο `~/.agentmemory/.env` αντί να εξάγετε μεταβλητές σε κάθε shell. Αν το viewer δείξει υπόδειξη όπως `export ANTHROPIC_API_KEY=...`, αντιγράψτε την εδώ ως `ANTHROPIC_API_KEY=...` χωρίς το πρόθεμα `export` και επανεκκινήστε το agentmemory. Ορίστε το `AGENTMEMORY_ENV_FILE` για να χρησιμοποιήσετε διαφορετική διαδρομή αρχείου env.
-Οι μεταβλητές περιβάλλοντος της διαδικασίας εξακολουθούν να λειτουργούν και υπερισχύουν των τιμών στο αρχείο.
+Οι μεταβλητές περιβάλλοντος της διεργασίας υπερισχύουν του αρχείου. Επανεκκινήστε τον διακομιστή μετά από αλλαγές ρυθμίσεων.
Σε Windows, το ίδιο αρχείο βρίσκεται στο `%USERPROFILE%\.agentmemory\.env`:
@@ -1614,176 +1351,27 @@ GRAPH_EXTRACTION_ENABLED=true
### Μεταβλητές Περιβάλλοντος
-Δημιουργήστε το `~/.agentmemory/.env`:
+Συνήθεις επιλογές για `~/.agentmemory/.env`. Εισαγωγή context και συμπίεση είναι προαιρετικές· η συμπίεση απαιτεί και πάροχο. Το `core` περιορίζει τα ορατά εργαλεία MCP:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Η πλήρης αναφορά [`.env.example`](../.env.example) καλύπτει παρόχους, φίλτρα καταγραφής, διατήρηση, αποθήκευση, ομάδες και προαιρετικές λειτουργίες. Το `AGENTMEMORY_ENV_FILE` επιλέγει άλλο αρχείο. Μην κάνετε commit συμπληρωμένο `.env` ή bearer secret.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints στη θύρα `3111`. Το REST API συνδέεται στο `127.0.0.1` από προεπιλογή. Τα προστατευμένα endpoints απαιτούν `Authorization: Bearer <secret>`, και τα endpoints mesh sync απαιτούν ένα ρητά ρυθμισμένο `AGENTMEMORY_SECRET` και στους δύο peers.
+146 endpoints στη θύρα `3111`. Το REST API συνδέεται στο `127.0.0.1` από προεπιλογή. Τα προστατευμένα endpoints απαιτούν `Authorization: Bearer <secret>`, και τα 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 χειροκίνητα:
+**Η πιστοποίηση είναι ενεργή από προεπιλογή.** Όταν δεν ορίζεται `AGENTMEMORY_SECRET`, στην πρώτη εκκίνηση το CLI δημιουργεί τυχαίο μυστικό στο `~/.agentmemory/secret` με δικαιώματα `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
@@ -1822,7 +1410,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Κοινοποίηση σε ομάδα |
| `GET` | `/agentmemory/audit` | Ιστορικό ελέγχου |
-Πλήρης λίστα endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Πλήρης λίστα endpoints: [Παραγόμενη αναφορά REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1836,23 +1424,23 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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` όπως πριν.
+Τα αποτυχημένα 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 γράφει στον δίσκο περιοδικά, οπότε ένα 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, `<data dir>/capture-spool/<host>-<port>.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` για να το απενεργοποιήσετε.
+**Συμπύκνωση προέλευσης γράφου.** Η συμπύκνωση παλαιών δεδομένων προέλευσης αναβάλλεται κατά την εκκίνηση, επειδή διαβάζει ολόκληρα τα παλαιά scopes. Το `/agentmemory/status` αναφέρει `deferred`, ή `off` με `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Εκτελέστε τη χειροκίνητη συμπύκνωση παρακάτω κατά τη συντήρηση. Η μετεγκατάσταση του ευρετηρίου ανάκτησης είναι ξεχωριστή: χρησιμοποιήστε `agentmemory graph-index migrate --allow-legacy-scan` όπως περιγράφει ο [οδηγός συντήρησης](../docs/reliability/graph-index-migration.md).
Για να το εκτελέσετε χειροκίνητα, καλέστε `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1866,7 +1454,7 @@ npm test # 4,000+ 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.
+Οι απαιτήσεις είναι στην [Εγκατάσταση](#install). Κανόνες συνεισφοράς και έλεγχοι έκδοσης βρίσκονται στο [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Άδεια Χρήσης" height="32" /></picture></h2>
diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md
index 08cc2ae6..4bd12424 100644
--- a/READMEs/README.es-ES.md
+++ b/READMEs/README.es-ES.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Tu agente de codificación lo recuerda todo. Se acabó volver a explicarlo.
- Basado en el <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Memoria persistente entre sesiones y agentes de programación.
</strong><br/>
- Memoria persistente para Claude Code, GitHub Copilot CLI, 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, Oh My Pi, DeepSeek Harness, OpenCode y cualquier cliente MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Cómo funciona</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Visor</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Config</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory captura sesiones de programación y permite buscar decisiones, soluciones y aprendizajes. Comparte un mismo almacenamiento entre agentes, revisa lo guardado y elige cuánto contexto recibe el modelo.
+
+<a id="install"></a>
+
## Instalación
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.
+- En macOS/Linux, la configuración automática también necesita `curl`, un `sh` POSIX y `tar`.
+- En Windows, usa WSL2 o sigue la [configuración nativa](#windows).
Comando canónico de instalación limpia:
@@ -108,11 +111,11 @@ Comando canónico de instalación limpia:
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 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`.
+Elige tus agentes y un proveedor, o el modo sin clave. El asistente escribe la configuración, inicia el servidor de memoria y ofrece instalar globalmente el comando `agentmemory`. `-y` acepta la confirmación de npm; `@latest` selecciona la versión actual. La compresión con LLM es opcional y requiere un proveedor y `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 <path>` 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.
+La API está en `http://localhost:3111` y el visor en `http://localhost:3113`. Ambos escuchan en loopback por defecto. La configuración está en `~/.agentmemory/.env`; consulta [almacenamiento de datos](#data-storage) para las rutas y las instancias separadas.
Después demuestra que el recall funciona y dale a tu agente sus skills:
@@ -127,14 +130,7 @@ Las búsquedas por palabra clave deberían acertar en el modo sin claves por def
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Conecta más agentes en cualquier momento con `agentmemory connect <agent>` — 20 adaptadores listados en [Funciona con cualquier agente](#works-with-every-agent). Referencia completa de comandos en [Inicio rápido](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Conecta otro agente con `agentmemory connect <agent>`. Consulta las [integraciones](#works-with-every-agent) y los [comandos habituales](#everyday-commands).
<details>
<summary><strong>Instalación global / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx cachea por versión. Fuerza la última con `npx -y @agentmemory/agentmemory@
</details>
-<details>
-<summary><strong>Ya ejecutas tu propio iii engine</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funciona con cualquier agente" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Tod
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin nativo + 7 hooks + MCP</sub>
+<sub>plugin nativo + hooks del ciclo de vida + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Tod
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin nativo + MCP</sub>
+<sub>búsqueda nativa + captura + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Tod
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>servidor MCP</sub>
+<sub>captura nativa + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Tod
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>búsqueda nativa + captura + skills + MCP opcional</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +306,25 @@ agentmemory funciona con cualquier agente que soporte hooks, MCP o REST API. Tod
---
-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.
+<a id="data-storage"></a>
-**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.
+### Almacenamiento de datos
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Los recuerdos se guardan fuera del repositorio por defecto:
-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 <path>` o define `AGENTMEMORY_DATA_DIR`; cualquiera de los dos ajustes explícitos tiene prioridad sobre el descubrimiento legacy:
+| Plataforma | Directorio de datos |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+La instancia 0 reutiliza un `./data/state_store.db` existente. Elige otra ruta con `--data-dir <path>` o `AGENTMEMORY_DATA_DIR` y consérvala al reiniciar o actualizar. `--instance 1` usa el subdirectorio `instance-1`, el puerto API `3211` y el visor `3213`. Consulta [almacenamiento y copias de seguridad](../docs/reliability/state-storage.md) para Redis y migraciones.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +473,7 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
</tr>
<tr>
<td><strong>Dependencias externas</strong></td>
-<td>Ninguna (SQLite + iii-engine)</td>
+<td>No necesita un servicio de base de datos separado</td>
<td>Qdrant / pgvector</td>
<td>Postgres + BD vectorial</td>
<td>Varias</td>
@@ -550,14 +547,12 @@ Tasa de aciertos top-5 del 100% en el **techo matemático de P@5** para este cor
| 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.
+AgentMemory combina captura desde agentes de programación, historial de proyecto consultable y un visor local. Puedes usarlo sin clave desde el primer inicio.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Inicio rápido" height="32" /></picture></h2>
-Compatibilidad: esta release apunta a `iii-sdk` 0.22.1 y fija iii-engine v0.22.1.
-
### Pruébalo en 30 segundos
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Abre `http://localhost:3113` para ver cómo se construye la memoria en directo.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Con el servidor en marcha, comprueba su salud, el visor y el estado:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` muestra la salud del servidor y los proveedores y embeddings activos. Guarda un recuerdo de prueba y comprueba la búsqueda:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Comandos del 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:
@@ -623,7 +627,7 @@ npx -y @agentmemory/agentmemory@latest import-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.
+Las sesiones importadas aparecen en el selector de Replay junto a las nativas. 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 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.
@@ -635,14 +639,12 @@ Usa el comando de mantenimiento cuando quieras actualizar intencionadamente tu r
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.22.1`. Nunca instala un iii engine sin fijar ni más nuevo.
-
-Los detalles de implementación viven en `src/cli.ts` (ver `runUpgrade` alrededor de la región `src/cli.ts:544-595`).
+Este comando actualiza el entorno local y puede actualizar las dependencias JavaScript del espacio de trabajo actual. Haz una copia de seguridad y lee la [guía de actualización](../docs/upgrades/iii-0.25.md) antes de continuar.
### Claude Code (un bloque, pégalo)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code sin instalar el plugin (ruta MCP standalone)
@@ -703,6 +705,28 @@ copilot plugin install rohitg00/agentmemory:plugin
`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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Después añade el plugin nativo desde un checkout de AgentMemory en **Settings → Plugins → Add marketplace** y recarga la ventana. El plugin ofrece captura del ciclo de vida, atribución al proyecto, skills y MCP. Activa los hooks del plugin o los manuales de `~/.cursor/hooks.json`, no ambos, para evitar capturas duplicadas. [Guía de Cursor](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Elige el comando de tu host. Pi y OMP instalan búsqueda, captura, reenvío sin conexión y 17 skills; `--with-mcp` añade todas las herramientas. Ejecuta `/reload` en Pi o reinicia OMP y comprueba `/agentmemory-status`. DSH instala MCP y el plugin de captura incluido; reinicia DSH después.
+
+Pi también admite el paquete instalable `@agentmemory/pi`. La [guía de Pi](../integrations/pi/) explica la instalación local y la disponibilidad en npm. Usa un solo método de instalación por host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (pega este prompt)</b></summary>
@@ -749,6 +773,8 @@ Guía completa: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Otros agentes
Arranca el servidor de memoria: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +791,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Esto es **complementario** a `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` normalmente escribe la configuración MCP. Hermes, OpenClaw, Pi y Oh My Pi instalan su integración nativa y las skills incluidas por defecto; MCP se añade con `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` instala skills para agentes que no las incluyen de forma nativa. Omite este paso con Hermes, OpenClaw, Pi y Oh My Pi: sus conectores ya las instalan.
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.
@@ -790,7 +816,7 @@ La entrada de agentmemory es el **mismo bloque de servidor MCP** en todos los ho
| Agente | Fichero de configuración | Notas |
|---|---|---|
| **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. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Después añade el plugin nativo desde un checkout de AgentMemory en **Settings → Plugins → Add marketplace** y recarga la ventana. El plugin ofrece captura del ciclo de vida, atribución al proyecto, skills y MCP. Activa los hooks del plugin o los manuales de `~/.cursor/hooks.json`, no ambos, para evitar capturas duplicadas. [Guía de Cursor](../integrations/cursor/). |
| **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. |
@@ -804,7 +830,7 @@ La entrada de agentmemory es el **mismo bloque de servidor MCP** en todos los ho
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | búsqueda nativa + captura + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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 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). |
@@ -812,39 +838,19 @@ La entrada de agentmemory es el **mismo bloque de servidor MCP** en todos los ho
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferido) o `config.json` (legacy) | `agentmemory connect continue` crea `config.yaml` si falta o modifica el `config.json` existente. Si ya existe YAML, muestra el bloque que debes añadir a `mcpServers:` para conservar comentarios y anclas. Continue usa un array, no un objeto. |
| **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 `<repo>/.factory/mcp.json`. Pasa `--with-hooks` para captura automática nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` activa las herramientas MCP. Añade `--with-hooks` para cargar el complemento nativo de captura incluido en AgentMemory. No requiere un paquete adicional. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Usa los [ejemplos REST autenticados](#validate-a-fresh-install-and-restart-persistence) para guardar y buscar recuerdos desde scripts. |
| **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"` 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 de iii puede llamarlas directamente sobre `ws://localhost:49134`, sin necesidad de un cliente REST separado por lenguaje.
-
-```bash
-pip install iii-sdk # Python
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
-
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-Ejemplo trabajado: [`examples/python/`](../examples/python/) (quickstart + flujo de observación/recall). La REST en `:3111` sigue disponible para hosts sin runtime de iii.
+Usa la [API REST](#api) desde cualquier lenguaje o las [herramientas MCP](#mcp-server) desde un agente. REST utiliza JSON y autenticación bearer; consulta el [ejemplo de guardado y búsqueda](#validate-a-fresh-install-and-restart-persistence). Los [ejemplos Python](../examples/python/) cubren la integración directa con el runtime.
### Desde el código fuente
@@ -853,93 +859,29 @@ 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 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=<version>` si ejecutas tu propio motor y sabes que coincide.
-
-- **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`
-
-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 trae `iiidev/iii:0.22.1`). Documentación completa: [iii.dev/docs](https://iii.dev/docs).
+`npm start` inicia el mismo servidor local que la CLI instalada. Los requisitos están en [Install](#install); la API y el visor escuchan en `127.0.0.1`.
### Windows
-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.
-
-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.
+agentmemory funciona en Windows 10/11. WSL2 sigue la ruta de Linux y puede instalar el motor fijado automáticamente. Windows nativo requiere instalar manualmente el binario fijado de iii-engine v0.25.0; descarga el archivo correspondiente desde la [página de la release iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verifica su checksum y coloca `iii.exe` en `PATH` (por ejemplo, `%USERPROFILE%\.local\bin\iii.exe`). La CLI no extrae automáticamente el ZIP de Windows.
-**Opción A: binario de Windows preconstruido (recomendado)**
+La conexión MCP automatizada en Windows nativo solo admite `agentmemory connect copilot-cli`. Para otros agentes nativos de Windows, usa el bloque MCP manual de [Otros agentes](#other-agents). Ejecuta `connect` dentro de WSL solo si el agente de destino está instalado en ese mismo entorno WSL.
-```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
-```
-
-**Opció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
-```
-
-**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:
+**Solo MCP independiente (sin motor).** Si solo necesitas herramientas MCP y no necesitas la API REST, el visor ni los servicios del runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# o
npx -y @agentmemory/mcp
```
-**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 |
-|---|---|
-| `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 <N>` |
-| 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** 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`.
+Ejecuta `agentmemory doctor` o reinicia con `--verbose`. Usa `--port <N>` o `--instance <N>` si los puertos están ocupados. Consulta compatibilidad y recuperación en la [guía de actualización](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Deploy</h2>
-Plantillas de un clic para hosts gestionados. Cada una incluye un
-Dockerfile autocontenido que descarga `@agentmemory/agentmemory` desde npm
-y copia el binario del iii engine desde la imagen oficial `iiidev/iii` de
-Docker Hub; no se requiere una imagen preconstruida de agentmemory. El
-almacenamiento persistente se monta en `/data`; el entrypoint del primer
-arranque sobrescribe la configuración 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
-luego baja privilegios de `root` a `node` con `gosu` antes de hacer exec
-del CLI de agentmemory.
-
-<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
-</p>
+Aloja el servicio con Docker Compose o las plantillas siguientes. La memoria y las credenciales están en el volumen `/data`. Haz una copia de seguridad y reutiliza ese volumen al actualizar. La [guía de despliegue](../deploy/README.md) cubre autenticación, red, copias de seguridad y migración.
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.
@@ -955,28 +897,26 @@ Los detalles completos de configuración (captura HMAC, túnel SSH del visor, ro
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 la
-pauta de túnel SSH para alcanzarlo.
+REST usa el puerto `3111`; el visor, `3113`. Mantenlos privados o protégelos con autenticación y TLS. La guía de despliegue incluye la exposición de red y la [migración de instalaciones Docker antiguas](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Por qué agentmemory" height="32" /></picture></h2>
-Todo agente de codificación olvida todo al terminar la sesión, y cada nueva sesión empieza contigo re-explicando tu stack. agentmemory corre en segundo plano y elimina ese paso.
+El conocimiento del proyecto se dispersa entre chats y archivos de instrucciones. AgentMemory permite buscar decisiones, soluciones y aprendizajes desde el agente que uses ahora.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### Frente a la memoria integrada del agente
@@ -985,7 +925,7 @@ Todo agente de codificación con IA viene con memoria integrada: Claude Code tie
| | Integrada (CLAUDE.md) | agentmemory |
|---|---|---|
-| Escala | tope de 200 líneas | Ilimitado |
+| Mantenimiento | Instrucciones mantenidas manualmente | Historial de sesiones y recuerdos indexados |
| Búsqueda | Carga todo en contexto | BM25 + vector + graph (solo top-K) |
| Coste en tokens | 22K+ con 240 observaciones | ~1,900 tokens (92% menos) |
| Cross-agent | Ficheros por agente | MCP + REST (cualquier agente) |
@@ -1011,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Consolidación de memoria en 4 niveles
@@ -1035,6 +975,8 @@ Las memorias decaen con el tiempo (curva de Ebbinghaus). Las memorias accedidas
### Qué se captura
+Esta tabla describe los hooks de Claude Code. Otras integraciones capturan los eventos que proporciona su host; consulta sus guías. La inyección automática de contexto mediante los hooks compartidos se activa con `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Captura |
|------|----------|
| `SessionStart` | Ruta de proyecto, ID de sesión |
@@ -1051,7 +993,7 @@ Las memorias decaen con el tiempo (curva de Ebbinghaus). Las memorias accedidas
| Capacidad | Descripción |
|---|---|
-| **Captura automática** | Cada uso de tool registrado vía hooks, sin esfuerzo manual |
+| **Captura automática** | Las integraciones nativas registran los eventos de sesión y herramientas compatibles |
| **Búsqueda semántica** | BM25 + vector + grafo de conocimiento con fusión RRF |
| **Evolución de memoria** | Versionado, supersesión, grafos de relaciones |
| **Higiene de recall** | Las versiones de memoria reemplazadas salen de los índices de búsqueda; la cadena de versiones en KV conserva el historial completo |
@@ -1112,7 +1054,7 @@ La instalación npm normal incluye el runtime opcional `@huggingface/transformer
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 -y @agentmemory/agentmemory@latest` (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 conéctate a un servidor alojado por tu cuenta) y define `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Tools
@@ -1252,7 +1194,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Visor en tiempo real" height="32" /></picture></h2>
-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.
+Arranca automáticamente en el puerto `3113`. Al conectarse, el visor carga un snapshot (`GET /agentmemory/viewer/snapshot`) y después aplica los eventos en vivo mediante SSE en `/agentmemory/viewer/events`, servido por el worker REST: las memorias nuevas, lecciones, observaciones, entradas de auditoría, cambios del grafo y actualizaciones de salud aparecen sin polling ni recargas de página. Las únicas otras peticiones son las acciones que seleccionas, las páginas de «cargar más» y las búsquedas. Si se interrumpe la transmisión, el visor muestra la antigüedad de sus datos, se reconecta con backoff y vuelve a sincronizar desde un único snapshot.
- **12 pestañas en cuatro grupos** con conteos en vivo, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1207,7 @@ Arranca automáticamente en el puerto `3113`. El visor carga un snapshot al cone
open http://localhost:3113
```
-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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-El visor en `:3113` muestra lo que tu agente **recordó**. La [iii console](https://iii.dev/docs/console) muestra lo que tu agente **hizo**: cada operación de memoria como una traza OpenTelemetry, cada entrada KV editable, cada función invocable, cada stream tappable. Dos ventanas sobre la misma memoria: una con forma de producto, otra con forma de motor.
-
-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 incluye esto gratis porque cada llamada a función y cada trigger se disparan a través de iii; nada personalizado, nada que instrumentar.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Página Workers de iii console: workers conectados incluyendo instancias de agentmemory con conteo de funciones en vivo y metadatos de runtime" width="720" />
- <br/>
- <em>Página Workers: cada worker conectado, incluida agentmemory, con PID, conteo de funciones, runtime y last-seen.</em>
-</p>
-
-**Ya 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 console
-```
-
-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.
-
-Lo mismo a mano, útil cuando `agentmemory` no está en el PATH:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**Qué puedes hacer desde la console:**
-
-| Página | Úsala para |
-|------|-----------|
-| **Workers** | Ver todos los workers conectados y sus métricas en vivo, incluyendo el propio worker de agentmemory. |
-| **Functions** | 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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Vista de waterfall de trazas de iii console mostrando duración por span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service breakdown para cada operación de memoria.</em>
-</p>
-
-**Las traces ya están activas:**
-
-`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 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 exige auth; manténla enlazada a `127.0.0.1` (el valor por defecto) y nunca la expongas públicamente.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory **ya es una instancia [iii](https://iii.dev) en ejecución**. Tres primitivos (worker, función, trigger) componen el runtime; el estado KV, los streams y las trazas OTEL provienen de los workers iii-state, iii-stream e iii-observability que se incluyen con iii. No has instalado Postgres, Redis, Express, pm2 ni Prometheus, porque iii los reemplaza.
-
-Eso significa que un comando más extiende agentmemory con una capacidad completamente nueva.
-
-### Extiende agentmemory con más workers
-
-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.
-
-```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 | Qué obtienes encima de agentmemory |
-|---|---|
-| [`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:<scope>`, `stream:<name>:<group>`) 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 |
-|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
-| SQLite / Postgres + pgvector | iii KV State + índice vectorial in-memory |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | Supervisión de workers del iii engine |
-| Prometheus / Grafana | iii OTEL + monitor de salud |
-| Sistemas de plugins propios | `iii worker add <name>` |
-
-**250 ficheros de código · ~55,000 LOC · 3,400+ tests · 324 funciones · 67 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+El servidor del visor se enlaza a `127.0.0.1` por defecto y adjunta el secreto del servidor al reenviar peticiones a la API REST. Si se enlaza a una dirección que no sea loopback, la página HTML sigue siendo pública, pero cada petición proxy requiere el bearer; el visor lo solicita y lo guarda en el almacenamiento de sesión. Configura listas explícitas de hosts/orígenes y TLS antes de exponer el visor. 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'`).
---
@@ -1467,6 +1228,8 @@ agentmemory autodetecta proveedores desde tu entorno. Un proveedor habilita las
| **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=<tu modelo>` | 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Modelos locales (Ollama / LM Studio / vLLM)
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.
@@ -1516,24 +1279,7 @@ Los embeddings locales se incluyen como dependencia opcional pero no están acti
### Selección de modelo con conciencia de coste
-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.
-
-| 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 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 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 nivel premium. Define `AGENTMEMORY_SUPPRESS_COST_WARNING=1` para silenciarlo una vez que hayas tomado una decisión informada.
-
-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: [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/).
+Empieza sin clave para capturar y buscar por palabras clave. `EMBEDDING_PROVIDER=local` activa la búsqueda semántica local tras la primera descarga del modelo. La compresión con LLM requiere un proveedor y `AGENTMEMORY_AUTO_COMPRESS=true`; puede generar una petición por observación. Consulta los precios actuales del proveedor antes de activarla. El visor y `agentmemory status` muestran los proveedores activos.
### Memoria multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1309,22 @@ Cuando `AGENT_ID` no está definido, la memoria permanece sin scope (comportamie
### Puertos
-agentmemory + iii-engine enlazan cuatro puertos por defecto. Si un reinicio falla con `port in use`, esta tabla te dice qué proceso buscar.
-
-| Puerto | Proceso | Propósito | Override 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_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 <N>` 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.
+| Puerto | Uso | Configuración |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Limpieza de procesos obsoletos cuando los puertos se quedan ocupados tras una ejecución que crasheó:
+`--port <N>` fija el puerto API y, por defecto, el visor en `N+2`. Usa `--instance N` para una instancia separada. Mantén privados los puertos internos y consulta la [guía de despliegue](../deploy/README.md) antes de habilitar acceso remoto.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Backend de almacenamiento: file (predeterminado) vs. Redis
-`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.
+El almacenamiento por archivos predeterminado no necesita un servicio de base de datos separado. Redis es opcional con `AGENTMEMORY_STATE_BACKEND=redis` y `AGENTMEMORY_REDIS_URL`. Cambiar de backend no copia los recuerdos. Consulta [almacenamiento y copias de seguridad](../docs/reliability/state-storage.md) para persistencia, límites de Redis y exportación/importación autenticada.
### Fichero de configuración
-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.
+Pon la configuración del runtime de agentmemory en `~/.agentmemory/.env` en lugar de exportar variables en cada shell. Si el visor muestra una pista de configuración como `export ANTHROPIC_API_KEY=...`, cópiala a este fichero como `ANTHROPIC_API_KEY=...` sin el prefijo `export`, y reinicia agentmemory. Define `AGENTMEMORY_ENV_FILE` para usar otra ruta de fichero de entorno.
-Las variables de entorno del proceso siguen funcionando y tienen prioridad sobre los valores del fichero.
+Las variables de entorno del proceso tienen prioridad sobre el archivo. Reinicia el servidor tras cambiar la configuración.
En Windows, el mismo fichero vive en `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,179 +1351,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Variables de entorno
-Crea `~/.agentmemory/.env`:
+Opciones habituales para `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+La referencia completa está en [`.env.example`](../.env.example): credenciales, filtros de captura, retención, almacenamiento, ámbito de equipo y opciones. `AGENTMEMORY_ENV_FILE` selecciona otro archivo. Nunca guardes un `.env` con credenciales ni un secreto bearer en git.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer <secret>`, y los endpoints de mesh sync requieren un `AGENTMEMORY_SECRET` definido explícitamente en ambos peers.
+146 endpoints en el puerto `3111`. La REST API se enlaza a `127.0.0.1` por defecto. Los endpoints protegidos requieren `Authorization: Bearer <secret>`, 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:
+**La autenticación está activada por defecto.** Si `AGENTMEMORY_SECRET` no está definida en la shell ni en `~/.agentmemory/.env`, la CLI genera un secreto aleatorio en el primer inicio en `~/.agentmemory/secret` y lo copia como `secret` en el directorio de datos seleccionado, con permisos `0600`. Todos los clientes incluidos lo leen desde allí al comunicarse con un servidor local: la CLI, el visor, los hooks de `plugin/scripts`, el servidor MCP y el shim `@agentmemory/mcp`, las configuraciones escritas por `agentmemory connect` y las integraciones incluidas de OpenCode, Pi, OpenClaw, Hermes y filesystem-watcher. El secreto guardado solo se envía a URL de loopback (`localhost`, `127.0.0.0/8`, `::1`). Un `AGENTMEMORY_SECRET` explícito siempre tiene prioridad, y los clientes remotos necesitan que el secreto esté definido en su entorno. Los despliegues Docker alojados por cuenta propia desde el repositorio y los entrypoints de `deploy/` generan y exportan su propio secreto. Para llamar a la API manualmente:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1830,7 +1412,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Comparte con el equipo |
| `GET` | `/agentmemory/audit` | Pista de auditoría |
-Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Lista completa de endpoints: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1430,19 @@ Los eventos fallidos se reintentan cada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`
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, `<data dir>/capture-spool/<host>-<port>.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.
+**Compactación de provenance del grafo.** La compactación de la procedencia antigua se aplaza al arrancar porque lee ámbitos antiguos completos. `/agentmemory/status` muestra `deferred`, u `off` con `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Ejecuta la compactación manual de abajo durante el mantenimiento. La migración del índice de búsqueda es independiente: usa `agentmemory graph-index migrate --allow-legacy-scan` como indica la [guía de mantenimiento](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1456,7 @@ npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
```
-**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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licencia" height="32" /></picture></h2>
diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.md
index 58abd565..dc8e0b20 100644
--- a/READMEs/README.fi-FI.md
+++ b/READMEs/README.fi-FI.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Koodausagenttisi muistaa kaiken. Ei enää tarvetta selittää asioita uudelleen.
- Perustuu <a href="https://github.com/iii-hq/iii">iii-moottoriin</a>
+ Pysyvä muisti koodausistuntojen ja agenttien välillä.
</strong><br/>
- Pysyvä muisti seuraaville: Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode ja mikä tahansa MCP-asiakas.
+ Pysyvä muisti seuraaville: Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode ja mikä tahansa MCP-asiakas.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Miten se toimii</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Katseluohjelma</a> &bull;
- <a href="#powered-by-iii">iii:n voimalla</a> &bull;
<a href="#configuration">Asetukset</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory tallentaa tuetut istuntotapahtumat ja tekee päätöksistä, korjauksista ja opeista haettavia eri agenteille. Viewerissa voit tarkastella, muokata, viedä ja poistaa muistoja. Avainsanahaku toimii ilman API-avainta; upotukset lisäävät semanttisen haun.
+
+<a id="install"></a>
+
## 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.
+- macOS/Linux tarvitsevat myös `curl`-, POSIX `sh`- ja `tar`-työkalut ympäristön automaattiseen asennukseen.
+- Käytä Windowsissa WSL2:ta tai [natiivin Windowsin ohjetta](#windows).
Kanoninen tuore asennuskomento:
@@ -108,11 +111,11 @@ Kanoninen tuore asennuskomento:
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.
+Valitse agentit ja palveluntarjoaja tai avaimeton tila. Ohjattu asennus tallentaa asetukset, käynnistää muistipalvelimen ja tarjoaa `agentmemory`-komennon globaalin asennuksen. `-y` hyväksyy npm-kehotteen; `@latest` valitsee nykyisen julkaisun. LLM-pakkaus edellyttää palveluntarjoajaa ja asetusta `AGENTMEMORY_AUTO_COMPRESS=true`.
Avaimeton tila poistaa vektoriupotukset käytöstä. `memory_recall` (`mem::search`-reitti) käyttää BM25:tä, kun taas `memory_smart_search` voi myös yhdistää rakenteellisia graafiosumia, kun graafidataa on jo olemassa. Saadaksesi ilmaisen, laitteella toimivan semanttisen muistinhaun, aseta `EMBEDDING_PROVIDER=local` tiedostoon `~/.agentmemory/.env` ja käynnistä uudelleen. Ensimmäinen upotuspyyntö lataa mallin `Xenova/all-MiniLM-L6-v2`; päättely toimii sen jälkeen paikallisesti.
-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 <polku>` -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.
+API toimii osoitteessa `http://localhost:3111` ja viewer osoitteessa `http://localhost:3113`. Molemmat kuuntelevat oletuksena vain paikallisesti. Asetukset ovat tiedostossa `~/.agentmemory/.env`; [tietojen tallennus](#data-storage) kuvaa hakemistot ja erilliset instanssit.
Todista sitten, että muistin palauttaminen toimii, ja anna agentillesi sen taidot:
@@ -127,14 +130,7 @@ 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 <agent>` — 20 sovitinta listattuna kohdassa [Toimii jokaisen agentin kanssa](#works-with-every-agent). Täysi komentoviite kohdassa [Pika-aloitus](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Yhdistä toinen agentti komennolla `agentmemory connect <agent>`. Katso [integraatiot](#works-with-every-agent) ja [päivittäiset komennot](#everyday-commands).
<details>
<summary><strong>Globaali asennus / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx käyttää välimuistia versioittain. Pakota uusin versio komennolla `npx -y
</details>
-<details>
-<summary><strong>Oma iii-moottori on jo käynnissä</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Toimii jokaisen agentin kanssa" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>natiivi plugin + 7 hookia + MCP</sub>
+<sub>natiivi plugin + elinkaarihookit + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>natiivi plugin + MCP</sub>
+<sub>natiivi muistihaku + tallennus + taidot</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP-palvelin</sub>
+<sub>natiivi tallennus + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST
<sub>REST-rajapinta</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>natiivi muistihaku + tallennus + taidot + valinnainen MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ agentmemory toimii jokaisen agentin kanssa, joka tukee hookeja, MCP:tä tai REST
---
-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ä.
+<a id="data-storage"></a>
-**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ä.
+### Tietojen tallennus
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Muistot tallennetaan oletuksena repositorion ulkopuolelle:
-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 <polku>` tai aseta `AGENTMEMORY_DATA_DIR`; kumpi tahansa nimenomainen asetus ajaa vanhan tunnistuksen edelle:
+| Alusta | Datahakemisto |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instanssi 0 käyttää olemassa olevaa `./data/state_store.db`-tallennusta. Valitse toinen hakemisto valinnalla `--data-dir <path>` tai muuttujalla `AGENTMEMORY_DATA_DIR`. Säilytä sama hakemisto uudelleenkäynnistyksissä ja päivityksissä.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` käyttää alihakemistoa `instance-1`, API-porttia `3211` ja viewer-porttia `3213`. Redis ja siirrot kuvataan [tallennus- ja varmuuskopiointioppaassa](../docs/reliability/state-storage.md).
Uusimmat julkaisutiedot: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ Uusimmat julkaisutiedot: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Ulkoiset riippuvuudet</strong></td>
-<td>Ei mitään (SQLite + iii-engine)</td>
+<td>Erillistä tietokantapalvelua ei tarvita</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektoritietokanta</td>
<td>Useita</td>
@@ -550,14 +549,12 @@ Uusimmat julkaisutiedot: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory yhdistää istuntojen tallennuksen, haettavan projektihistorian ja paikallisen viewerin; avaimeton käyttö toimii ensimmäisestä käynnistyksestä.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Pika-aloitus" height="32" /></picture></h2>
-Yhteensopivuus: tämä julkaisu kohdistuu `iii-sdk`-versioon 0.22.1 ja kiinnittää iii-engine-version v0.22.1.
-
### Kokeile 30 sekunnissa
```bash
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Avaa `http://localhost:3113` nähdäksesi muistin rakentuvan reaaliajassa.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Vahvista tuore asennus ja uudelleenkäynnistyksen pysyvyys
-Kun palvelin on käynnissä, vahvista REST, health, katseluohjelma ja iii-pohjaisen ajonaikaisen ympäristön tila:
+Tarkista käynnissä olevan palvelimen terveys, viewer ja tila:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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:
+`status` näyttää palvelimen tilan, palveluntarjoajat, upotustilan, havaintojen toimituksen ja palautumisen. Suojatut REST-pyynnöt tarvitsevat palvelimen salaisuuden. Käytä omaa `AGENTMEMORY_SECRET`-arvoa, jos se on asetettu; muutoin lue luotu paikallinen salaisuus:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Aja sitten `npx -y @agentmemory/agentmemory@latest stop`, käynnistä kanoninen komento uudelleen Terminaalissa 1, odota `/agentmemory/livez`-vastausta ja toista haku. Koettimen on edelleen tultava takaisin. Jos valitsit mukautetun `--data-dir`-arvon, välitä sama hakemisto uudelleenkäynnistyksessä.
+<a id="everyday-commands"></a>
+
### 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:
@@ -604,6 +610,9 @@ Asennus ja käyttöönotto löytyvät yllä kohdasta [Asennus](#install) (ensimm
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Tuodut istunnot näkyvät Replay-näkymässä natiivien rinnalla. Litteroinnit indeksoidaan ja merkitään alkuperäkanavalla `import`; käsittely voi tuottaa myös istuntokiteitä ja oppeja.
> **Huomio, jos nojaat `import-jsonl`-komentoon ensisijaisena tallennusreittinä:** Claude Coden `cleanupPeriodDays` (tiedostossa `~/.claude/settings.json`, oletus **30**) poistaa automaattisesti JSONL-transkriptiot, jotka ovat vanhempia kuin tämä ikkuna, kansiosta `~/.claude/projects/`. Jos asennat agentmemoryn tuoreena useita kuukausia vanhan Claude Code -historian päälle, kaikki 30 päivää vanhempi on jo poissa ennen ensimmäistä tuontia. Aja `import-jsonl` cron-ajastettuna, nosta `cleanupPeriodDays`-arvoa korkeammaksi, tai kytke automaattitallennushookit (oletusarvoinen plugin-asennusreitti), jotta jokainen vuoro päätyy agentmemoryyn istunnon ollessa käynnissä ja JSONL-siivous lakkaa merkitsemästä.
@@ -635,14 +644,12 @@ Käytä ylläpitokomentoa, kun haluat tarkoituksella päivittää paikallisen aj
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).
+Komento päivittää paikallisen ympäristön ja voi muuttaa työtilan JavaScript-riippuvuuksia. Varmuuskopioi tiedot ja lue [päivitysopas](../docs/upgrades/iii-0.25.md).
### Claude Code (yksi lohko, liitä se)
```text
-Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code ilman pluginin asennusta (itsenäinen MCP-reitti)
@@ -703,11 +710,35 @@ copilot plugin install rohitg00/agentmemory:plugin
`agentmemory connect copilot-cli` yhdistää `mcpServers.agentmemory`-merkinnän tiedostoon `~/.copilot/mcp-config.json` (tai `$COPILOT_HOME/mcp-config.json`, kun `COPILOT_HOME` on asetettu) ja säilyttää olemassa olevat palvelimet. Natiivilla Windowsilla tämä on ainoa automatisoitu `connect`-sovitin; määritä kaikki muut natiivit Windows-agentit käsin. WSL `connect` on soveltuva vain, kun kohdeagentti on asennettu samaan WSL-ympäristöön. Copilot ottaa MCP-palvelimen käyttöön seuraavalla käynnistyksellä tai `/mcp`-komennon jälkeen. Asenna myös plugin, kun haluat täyden hook-/taito-kokemuksen.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Valitse sitten **Settings → Plugins → Add marketplace** -kohdassa agentmemory-hakemisto, joka sisältää `.cursor-plugin/plugin.json`-tiedoston. Ota **agentmemory**-plugin käyttöön ja lataa ikkuna uudelleen. Plugin tarjoaa elinkaaren tallennuksen, työtilaan perustuvan projektin tunnistuksen, taidot ja MCP:n. Käytä joko pluginin hookeja tai manuaalisia hookeja tiedostossa `~/.cursor/hooks.json`, jotta tapahtumat eivät tallennu kahdesti.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Valitse oman ohjelmasi komento. Pi ja OMP asentavat natiivin muistihaun, tallennuksen, offline-uudelleenlähetyksen ja taidot; `--with-mcp` lisää kaikki työkalut. Suorita Pi:ssä `/reload` tai käynnistä OMP uudelleen ja tarkista `/agentmemory-status`. DSH asentaa MCP:n ja mukana toimitetun tallennuspluginin; käynnistä DSH uudelleen yhdistämisen jälkeen.
+
+Pi tukee myös asennettavaa `@agentmemory/pi`-pakettia. Paikallinen asennus ja npm-saatavuus kuvataan [Pi-oppaassa](../integrations/pi/). Käytä ohjelmaa kohti vain yhtä asennustapaa.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (liitä tämä kehote)</b></summary>
```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:
+Asenna agentmemory OpenClawille. Käynnistä muistipalvelin portissa localhost:3111 suorittamalla komento `npx -y @agentmemory/agentmemory@latest` erillisessä terminaalissa. Lisää sitten tämä OpenClawin MCP-asetuksiin, jotta kaikki agentmemoryn 54 muistityökalua ovat käytettävissä:
{
"mcpServers": {
@@ -721,7 +752,7 @@ Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` i
}
}
-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`.
+Käynnistä OpenClaw uudelleen. Vahvista toiminta komennolla `curl http://localhost:3111/agentmemory/health`. Avaa reaaliaikainen katseluohjelma osoitteessa http://localhost:3113. Syvempää muistipaikkaintegraatiota varten kopioi `integrations/openclaw` polkuun `~/.openclaw/extensions/agentmemory` ja ota käyttöön `plugins.slots.memory = "agentmemory"` tiedostossa `~/.openclaw/openclaw.json`.
```
Täysi opas: [`integrations/openclaw/`](../integrations/openclaw/)
@@ -732,7 +763,7 @@ Täysi opas: [`integrations/openclaw/`](../integrations/openclaw/)
<summary><b>Hermes Agent (liitä tämä kehote)</b></summary>
```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:
+Asenna agentmemory Hermesille. Käynnistä muistipalvelin portissa localhost:3111 suorittamalla komento `npx -y @agentmemory/agentmemory@latest` erillisessä terminaalissa. Lisää sitten tämä tiedostoon ~/.hermes/config.yaml, jotta Hermes voi käyttää agentmemorya MCP-palvelimena ja sen 54 muistityökalua:
mcp_servers:
agentmemory:
@@ -742,13 +773,15 @@ mcp_servers:
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.
+Vahvista toiminta komennolla `curl http://localhost:3111/agentmemory/health`. Avaa reaaliaikainen katseluohjelma osoitteessa http://localhost:3113. Syvempää kuuden hookin muistitarjoajaintegraatiota varten (kontekstin lisäys ennen LLM:ää, vuoron tallennus, MEMORY.md-peilaus ja järjestelmäkehotteen lohko) kopioi integrations/hermes agentmemory-repositoriosta polkuun ~/.hermes/plugins/agentmemory.
```
Täysi opas: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Muut agentit
Käynnistä muistipalvelin: `npx -y @agentmemory/agentmemory@latest`
@@ -763,10 +796,10 @@ 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 <agent>`:
+Tämä täydentää komentoa `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` kirjoittaa MCP-palvelimen asetukset, jotta työkalut ovat käytettävissä.
-- `npx skills add rohitg00/agentmemory` asentaa taidot, jotta agentti tietää, milloin kutsua niitä.
+- `agentmemory connect <agent>` kirjoittaa tavallisesti MCP-asetukset. Hermes, OpenClaw, Pi ja Oh My Pi asentavat oletuksena natiivin integraation ja taidot; MCP otetaan käyttöön valinnalla `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` asentaa taidot agenteille, joilla ei ole mukana tulevia natiiveja taitoja. Ohita tämä vaihe Hermesin, OpenClaw’n, Pi:n ja Oh My Pi:n kohdalla; niiden liittimet asentavat taidot jo.
Niille harvoille agenteille, joita skills-CLI ei vielä kata (Zed v1.3.x ja vanhemmat), pudota 17 SKILL.md-tiedostoa agentin natiiviin taitohakemistoon itse; sama formaatti toimii kaikkialla.
@@ -790,7 +823,7 @@ agentmemory-merkintä on **sama MCP-palvelinlohko** jokaisessa isännässä, jok
| 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ä. |
+| **Cursor (täysi plugin)** | `.cursor-plugin/` | Plugin tarjoaa elinkaarihookit, työtilan tunnistuksen, taidot ja MCP:n Cursor IDE:ssä ja `cursor-agent`-ohjelmassa. Katso [Cursorin asennus](#cursor). |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Yhdistä `mcpServers`-objektiin. Käynnistä Claude Desktop uudelleen muokkauksen jälkeen. |
| **Cline / Roo Code / Kilo Code** | Clinen MCP-asetukset (Settings-käyttöliittymä → MCP Servers → Edit) | Sama `mcpServers`-lohko. |
| **Devin CLI (MCP + hookit)** | `~/.config/devin/config.json` | `agentmemory connect devin` yhdistää MCP-merkinnän; `--with-hooks` lisää kuusi natiivia automaattitallennushookia (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) Devinin pienaakkosisilla työkalusovittimilla. Vahvista komennolla `devin mcp list` ja `/hooks` devinin sisällä. |
@@ -804,7 +837,8 @@ agentmemory-merkintä on **sama MCP-palvelinlohko** jokaisessa isännässä, jok
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. natiivi muistihaku + tallennus + taidot. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. natiivi muistihaku + tallennus + taidot. [Oh My Pi](../integrations/omp/). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` antaa 6-hookisen muistitarjoajan (esihaku, vuoron tallennus, istunnon päättyminen, esipakkaus, MEMORY.md-peilaus, system prompt -lohko). Vahvista komennoilla `hermes plugins doctor` ja `hermes memory status`. Katso [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen` kirjoittaa standardin `mcpServers`-lohkon. Hook-hyötykuorma on kenttätasolla yhteensopiva Claude Coden kanssa, niin olemassa olevat 12-hookin skriptit toimivat muokkaamatta; kytke ne `hooks`-osiossa samassa `settings.json`-tiedostossa. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` asentaa MCP:n ja tallennushookit jaettuun mukautushakemistoon. Katso [Antigravityn asennus ja rajoitukset](../docs/plugins/antigravity.md). |
@@ -812,39 +846,19 @@ agentmemory-merkintä on **sama MCP-palvelinlohko** jokaisessa isännässä, jok
| **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. |
+| **Continue.dev** | `~/.continue/config.yaml` (suositeltu) tai `config.json` (vanha) | `agentmemory connect continue` luo `config.yaml`-tiedoston, jos asetuksia ei ole, tai muokkaa olemassa olevaa `config.json`-tiedostoa. Olemassa olevan YAML:n tapauksessa se tulostaa lisättävän `mcpServers:`-lohkon säilyttääkseen kommentit ja ankkurit. Continue käyttää taulukkoa, ei objektia. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` kirjoittaa avaimen `context_servers` alle (Zedin avain, EI `mcpServers`). Etä-MCP-palvelimet voidaan kytkeä myös muodolla `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` kirjoittaa standardin `mcpServers`-lohkon. Projektikohtaiset ylikirjoitukset menevät tiedostoon `<repo>/.factory/mcp.json`. Välitä `--with-hooks` natiivia automaattitallennusta varten. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` ottaa MCP-työkalut käyttöön. Lisää `--with-hooks` ladataksesi AgentMemoryn mukana tulevan natiivin tallennuslisäosan. Erillistä lisäosapakettia ei tarvita. [DSH](../docs/dsh.md). |
| **Goose** | Goosen MCP-asetuskäyttöliittymä | Sama `mcpServers`-lohko; käytä `goose configure` → Add Extension → MCP. Suora YAML-muokkaus polussa `~/.config/goose/config.yaml` on tuettu, mutta skeema käyttää `extensions:` + `cmd` (ei `mcpServers:` + `command`). |
-| **Aider** | ei saatavilla | Puhu suoraan REST-rajapinnalle: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Aider** | ei saatavilla | Käytä [autentikoituja REST-esimerkkejä](#validate-a-fresh-install-and-restart-persistence) tallentamiseen ja hakemiseen skripteistä. |
| **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öä.
+Käytä [REST API:a](#api) mistä tahansa kielestä tai [MCP-työkaluja](#mcp-server) agentista. REST käyttää JSONia ja bearer-autentikointia; katso [tallennus- ja hakuesimerkki](#validate-a-fresh-install-and-restart-persistence). Suora ympäristöintegraatio kuvataan [Python-esimerkeissä](../examples/python/).
### Lähdekoodista
@@ -853,91 +867,33 @@ 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=<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).
+`npm start` käynnistää saman paikallisen palvelimen kuin asennettu CLI. Vaatimukset ovat [asennusohjeessa](#install); API ja viewer kuuntelevat osoitetta `127.0.0.1`.
### Windows
-agentmemory toimii Windows 10/11: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.
+agentmemory toimii Windows 10/11:ssä. WSL2 noudattaa Linuxin polkua ja voi asentaa kiinnitetyn moottorin automaattisesti. Natiivi Windows vaatii iii-engine v0.25.0:n kiinnitetyn binäärin asentamisen käsin; lataa sopiva paketti [iii v0.25.0 -julkaisusivulta](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), tarkista sen tarkistussumma ja sijoita `iii.exe` `PATH`-polkuun (esimerkiksi `%USERPROFILE%\.local\bin\iii.exe`). CLI ei pura Windows-ZIP-pakettia automaattisesti.
-**Vaihtoehto A: valmiiksi käännetty Windows-binääri (suositeltu)**
+Natiivin Windowsin automaattinen MCP-kytkentä tukee vain komentoa `agentmemory connect copilot-cli`. Muiden natiivien Windows-agenttien kanssa käytä manuaalista MCP-lohkoa kohdasta [Muut agentit](#other-agents). Suorita `connect` WSL:ssä vain, kun kohdeagentti on asennettu samaan WSL-ympäristöön.
-```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:
+**Vain itsenäinen MCP (ei moottoria).** Jos tarvitset vain MCP-työkaluja etkä REST-rajapintaa, katseluohjelmaa tai ajonaikaisia palveluita:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# tai
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 <N>` |
-| 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`.
+Suorita `agentmemory doctor` tai käynnistä uudelleen valinnalla `--verbose`. Jos portit ovat varattuja, käytä `--port <N>` tai `--instance <N>`. Yhteensopivuus ja palautuminen kuvataan [päivitysoppaassa](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Käyttöönotto</h2>
-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.
+Käytä itse ylläpidettyyn palveluun Docker Composea tai alla olevia malleja. Muisti ja tunnistetiedot ovat `/data`-volyymissa; varmuuskopioi ja käytä sitä uudelleen päivityksissä. Autentikointi, verkko, varmuuskopiot ja siirrot kuvataan [käyttöönotto-oppaassa](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Ota käyttöön fly.io:ssa" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Ota käyttöön Railwayssa" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Ota käyttöön fly.io:ssa" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Ota käyttöön Railwayssa" /></a>
</p>
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.
@@ -955,29 +911,13 @@ kustannuslattia) löytyvät kansiosta [`deploy/`](.././deploy/README.md):
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.
+REST käyttää porttia `3111` ja viewer porttia `3113`. Pidä ne yksityisinä tai suojaa autentikoinnilla ja TLS:llä. Alustakohtaiset asetukset ja [vanhan Docker-asennuksen siirto](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ovat käyttöönotto-oppaassa.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Miksi agentmemory" height="32" /></picture></h2>
-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.
-```
+Projektitieto hajautuu keskusteluihin ja ohjetiedostoihin. AgentMemory tuo aiemmat päätökset, korjaukset ja opit haettaviksi nykyisestä agentista.
### vs. sisäänrakennettu agenttimuisti
@@ -985,7 +925,7 @@ Jokainen tekoälypohjainen koodausagentti toimitetaan sisäänrakennetulla muist
| | Sisäänrakennettu (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skaala | 200 rivin katto | Rajattomasti |
+| Ylläpito | Käsin ylläpidetyt ohjeet | Indeksoitu istuntohistoria ja muistot |
| 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) |
@@ -1011,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-tasoinen muistin konsolidointi
@@ -1035,6 +975,8 @@ Muistot vanhenevat ajan myötä (Ebbinghausin käyrä). Usein käytetyt muistot
### Mitä tallennetaan
+Taulukko kuvaa Claude Coden hookit. Muut integraatiot tallentavat ohjelmansa tarjoamat tapahtumat. Automaattinen kontekstin lisäys yhteisten hookien kautta otetaan erikseen käyttöön: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Tallentaa |
|------|----------|
| `SessionStart` | Projektin polku, istunnon ID |
@@ -1051,7 +993,7 @@ Muistot vanhenevat ajan myötä (Ebbinghausin käyrä). Usein käytetyt muistot
| Ominaisuus | Kuvaus |
|---|---|
-| **Automaattinen tallennus** | Joka työkalun käyttö tallennetaan hookien kautta, ei manuaalista työtä |
+| **Automaattinen tallennus** | Natiivien integraatioiden tallentamat tuetut istunto- ja työkalutapahtumat |
| **Semanttinen haku** | BM25 + vektori + tietograafi RRF-fuusiolla |
| **Muistin kehitys** | Versiointi, korvaaminen, suhdegraafit |
| **Palautushygienia** | Korvatut muistiversiot poistuvat hakuindekseistä; versioketju KV:ssä säilyttää täyden historian |
@@ -1112,7 +1054,7 @@ Normaali npm-asennus sisältää valinnaisen `@huggingface/transformers`-ajonaik
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`.
+> **MCP-shim vs. täysi palvelin:** julkaistu `@agentmemory/mcp`-paketti on ohut shim. Se paljastaa täyden 54 työkalun pinnan **vain kun se tavoittaa käynnissä olevan agentmemory-palvelimen** `AGENTMEMORY_URL`:n kautta (proxy-tila). Kun palvelinta ei tavoiteta, shim palaa 7 työkalun paikalliseen settiin (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). `AGENTMEMORY_TOOLS=core|all`-ympäristömuuttuja on *palvelinpuolen* lippu; sen asettaminen shimin `env`-lohkossa ei vaikuta mihinkään. Jos näet vain 7 työkalua Cursorissa / OpenCodessa / Gemini CLI:ssä, käynnistä `npx -y @agentmemory/agentmemory@latest` (tai muodosta yhteys itse ylläpitämääsi palvelimeen) ja aseta `AGENTMEMORY_URL=http://localhost:3111`.
### 54 työkalua
@@ -1252,7 +1194,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Reaaliaikainen katseluohjelma" height="32" /></picture></h2>
-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.
+Käynnistyy automaattisesti portissa `3113`. Katseluohjelma lataa yhdistyessään yhden tilannevedoksen (`GET /agentmemory/viewer/snapshot`) ja käsittelee sen jälkeen reaaliaikaisia tapahtumia SSE:n kautta REST-workerissä osoitteessa `/agentmemory/viewer/events`: uudet muistot, opetukset, havainnot, auditointimerkinnät, graafimuutokset ja terveystiedot näkyvät ilman kyselyitä tai sivun uudelleenlatausta. Muut pyynnöt liittyvät vain napsauttamiisi toimintoihin, "lataa lisää" -sivuihin ja hakuihin. Jos virta katkeaa, katseluohjelma kertoo tietojen iän, yhdistää uudelleen takaisinviiveellä ja synkronoi tiedot yhdestä tilannevedoksesta.
- **12 välilehteä neljässä ryhmässä** live-laskureilla, syvälinkeillä (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1207,7 @@ Käynnistyy automaattisesti portissa `3113`. Katseluohjelma lataa yhden tilannev
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii-konsoli" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii-konsolin Workers-sivu: yhdistetyt workerit mukaan lukien agentmemory-instanssit live-funktiolaskureilla ja ajonaikaisella metadatalla" width="720" />
- <br/>
- <em>Workers-sivu: joka yhdistetty worker, mukaan lukien agentmemory itse, PID:llä, funktiomäärällä, ajonaikaisella ympäristöllä ja viimeisimmällä näkymisajalla.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii-konsolin jäljitysvesiputousnäkymä, joka näyttää keston per span" width="720" />
- <br/>
- <em>Traces: vesiputous-/liekki-/palvelujaottelu joka muistioperaatiolle.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="iii:n voimalla" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 lähdetiedostoa · ~55,000 LOC · 3,400+ testiä · 324 funktiota · 67 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
+Katseluohjelman palvelin sitoutuu oletuksena osoitteeseen `127.0.0.1` ja liittää palvelimen salaisuuden välittäessään pyyntöjä REST-rajapinnalle. Muuhun kuin loopback-osoitteeseen sidottaessa HTML-runko pysyy julkisena, mutta jokainen proxypyyntö vaatii bearer-tunnuksen; katseluohjelma pyytää sitä ja tallentaa sen istuntokohtaiseen tallennustilaan. Määritä eksplisiittiset host/origin-sallittujen listat ja TLS ennen katseluohjelman avaamista. REST-rajapinnan `/agentmemory/viewer`-päätepiste noudattaa normaaleja bearer-token-sääntöjä ja ohjaa selaimet ilman tokenia katseluohjelman porttiin. CSP-otsakkeet käyttävät vastauskohtaista script-noncea ja poistavat käytöstä inline-käsittelijäattribuutit (`script-src-attr 'none'`).
---
@@ -1467,6 +1228,8 @@ agentmemory tunnistaa tarjoajat automaattisesti ympäristöstäsi. Tarjoaja teke
| **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=<malli>` | 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1279,7 @@ Paikalliset upotukset toimitetaan valinnaisena riippuvuutena, mutta ne eivät ol
### 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/).
+Aloita ilman avainta tallennusta ja avainsanahakua varten. `EMBEDDING_PROVIDER=local` lisää paikallisen semanttisen haun mallin lataamisen jälkeen. LLM-pakkaus vaatii palveluntarjoajan ja asetuksen `AGENTMEMORY_AUTO_COMPRESS=true`; jokainen havainto voi aiheuttaa pyynnön, joten tarkista nykyiset hinnat. Viewer ja `agentmemory status` näyttävät aktiiviset palveluntarjoajat.
### Moniagenttinen muisti (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1309,22 @@ Kun `AGENT_ID` on asettamatta, muisti pysyy rajaamattomana (vanha käytös, ei t
### 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 | Tarkoitus | Ympäristömuuttuja |
+|---|---|---|
+| `3111` | REST API, MCP HTTP ja viewerin reaaliaikaiset tapahtumat | `III_REST_PORT` |
+| `3113` | Viewerin käyttöliittymä | `III_VIEWER_PORT` |
-`--port <N>` 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.
+`--port <N>` asettaa REST-portin ja viewerin oletusportiksi `N+2`. `--instance N` luo erillisen ympäristön. Sisäisten porttien on pysyttävä yksityisinä; lue [käyttöönotto-opas](../deploy/README.md) ennen etäkäyttöä.
-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.
+### Tallennus: tiedosto tai Redis
-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 <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.
+Oletusarvoinen tiedostotallennus ei tarvitse erillistä tietokantaa. Redis on valinnainen asetuksilla `AGENTMEMORY_STATE_BACKEND=redis` ja `AGENTMEMORY_REDIS_URL`. Taustajärjestelmän vaihto ei kopioi muistia. Pysyvyys, Redisin rajoitukset ja autentikoitu vienti/tuonti kuvataan [tallennusoppaassa](../docs/reliability/state-storage.md).
### Asetustiedosto
-Laita agentmemoryn ajonaikaiset asetukset tiedostoon `~/.agentmemory/.env` sen sijaan, että 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.
+Laita agentmemoryn ajonaikaiset asetukset tiedostoon `~/.agentmemory/.env` sen sijaan, että veisit muuttujia joka shellissä. Jos katseluohjelma näyttää asetusvihjeen, kuten `export ANTHROPIC_API_KEY=...`, kopioi se tähän tiedostoon muodossa `ANTHROPIC_API_KEY=...` ilman `export`-etuliitettä ja käynnistä agentmemory uudelleen. Aseta `AGENTMEMORY_ENV_FILE`, jos haluat käyttää muuta ympäristötiedoston polkua.
-Prosessin ympäristömuuttujat toimivat yhä ja voittavat tiedoston arvot.
+Prosessin ympäristömuuttujat ohittavat tiedoston arvot. Käynnistä palvelin uudelleen asetusten muuttamisen jälkeen.
Windowsilla sama tiedosto sijaitsee polussa `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,179 +1351,30 @@ GRAPH_EXTRACTION_ENABLED=true
### Ympäristömuuttujat
-Luo `~/.agentmemory/.env`:
+Tavalliset asetukset tiedostoon `~/.agentmemory/.env`. Kontekstin lisäys ja pakkaus ovat valinnaisia; pakkaus tarvitsee myös palveluntarjoajan. `core` rajaa näkyviä MCP-työkaluja:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Täydellinen [`.env.example`](../.env.example) kattaa palveluntarjoajat, tallennussuodattimet, säilytyksen, tallennusratkaisut, tiimit ja valinnaiset ominaisuudet. `AGENTMEMORY_ENV_FILE` valitsee toisen tiedoston. Älä koskaan commitoi täytettyä `.env`-tiedostoa tai bearer-salaisuutta.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpointia portissa `3111`. REST-rajapinta sitoutuu oletuksena osoitteeseen `127.0.0.1`. Suojatut endpointit vaativat `Authorization: Bearer <secret>`, ja mesh-synkronointiendpointit vaativat nimenomaisesti asetetun `AGENTMEMORY_SECRET`-arvon molemmilla vertaisilla.
+146 endpointia portissa `3111`. REST-rajapinta sitoutuu oletuksena osoitteeseen `127.0.0.1`. Suojatut endpointit vaativat `Authorization: Bearer <secret>`, 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:
+**Autentikointi on oletuksena päällä.** Jos `AGENTMEMORY_SECRET` puuttuu, CLI luo ensimmäisellä käynnistyksellä satunnaisen salaisuuden tiedostoon `~/.agentmemory/secret` oikeuksilla `0600` ja kopioi sen myös valittuun datahakemistoon. Kaikki mukana toimitetut asiakkaat lukevat salaisuuden sieltä käyttäessään paikallista palvelinta: CLI, katseluohjelma, `plugin/scripts`-hakemiston hookit, MCP-palvelin ja `@agentmemory/mcp`-shim, `agentmemory connect` -komennon luomat asetukset sekä mukana toimitetut OpenCode-, Pi-, OpenClaw-, Hermes- ja filesystem-watcher-integraatiot. Tallennettu salaisuus lähetetään vain loopback-osoitteisiin (`localhost`, `127.0.0.0/8`, `::1`). Nimenomainen `AGENTMEMORY_SECRET` voittaa aina, ja etäasiakkaiden on asetettava salaisuus ympäristöönsä. Repositorion Docker-itseylläpitokäyttöönotot ja `deploy/`-entrypointit luovat ja vievät oman salaisuutensa. Rajapinnan manuaalinen kutsu:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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ä.
@@ -1830,7 +1410,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Jaa tiimin kanssa |
| `GET` | `/agentmemory/audit` | Auditointijälki |
-Täysi endpoint-lista: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Täysi endpoint-lista: [Generoitu REST-viite](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1428,19 @@ Epäonnistuneita tapahtumia yritetään uudelleen `AGENTMEMORY_CAPTURE_RETRY_INT
Kun palvelin on alhaalla, ei vastaa ajoissa tai palauttaa 5xx:n, hook liittää havainnon paikalliseen spool-tiedostoon, `<data dir>/capture-spool/<host>-<port>.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.
+**Graafin alkuperän tiivistäminen.** Vanhojen alkuperätietojen tiivistäminen lykätään käynnistyksessä, koska se lukee vanhat scopet kokonaan. `/agentmemory/status` näyttää tilan `deferred`, tai `off`, kun `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Suorita alla kuvattu manuaalinen tiivistäminen huollon aikana. Hakuindeksin migraatio on erillinen: käytä komentoa `agentmemory graph-index migrate --allow-legacy-scan` [huolto-ohjeen](../docs/reliability/graph-index-migration.md) mukaisesti.
Ajaaksesi sen käsin, kutsu `POST /agentmemory/graph/compact`. Se kävelee nimi- ja reuna-avainindeksit sen sijaan, että listaisi joka solmun ja reunan, ja sen voi turvallisesti ajaa uudelleen. Kun se tiivistää ID:itä, se kirjoittaa `graph_compact`-auditointimerkinnän.
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1454,7 @@ npm test # 4,000+ 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.
+Vaatimukset ovat [asennusohjeessa](#install). Osallistumisohjeet ja julkaisutarkistukset ovat [CONTRIBUTING.md](../CONTRIBUTING.md)-tiedostossa.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Lisenssi" height="32" /></picture></h2>
diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.md
index 711daaa5..2b5739ad 100644
--- a/READMEs/README.fr-FR.md
+++ b/READMEs/README.fr-FR.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Votre agent de codage se souvient de tout. Fini de tout réexpliquer.
- Construit sur <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Une mémoire persistante entre vos sessions et agents de programmation.
</strong><br/>
- Mémoire persistante pour Claude Code, GitHub Copilot CLI, 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, Oh My Pi, DeepSeek Harness, OpenCode et tout client MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Fonctionnement</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Visualiseur</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Configuration</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory capture les sessions de programmation et permet de retrouver décisions, correctifs et enseignements. Partagez un même stockage entre vos agents, inspectez les éléments enregistrés et choisissez la quantité de contexte transmise au modèle.
+
+<a id="install"></a>
+
## Installation
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.
+- Sur macOS/Linux, l'installation automatique nécessite aussi `curl`, un `sh` POSIX et `tar`.
+- Sous Windows, utilisez WSL2 ou suivez la [configuration Windows native](#windows).
Commande canonique d'installation initiale :
@@ -108,11 +111,11 @@ Commande canonique d'installation initiale :
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 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.
+Choisissez vos agents et un fournisseur, ou le mode sans clé. L'assistant écrit la configuration, démarre le serveur mémoire et propose une installation globale de la commande `agentmemory`. `-y` accepte la demande de npm ; `@latest` sélectionne la version actuelle. La compression par LLM est facultative et nécessite un fournisseur ainsi que `AGENTMEMORY_AUTO_COMPRESS=true`.
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.
-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 <path>` 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.
+L'API est disponible sur `http://localhost:3111` et le visualiseur sur `http://localhost:3113`. Tous deux écoutent sur la boucle locale par défaut. La configuration se trouve dans `~/.agentmemory/.env` ; consultez le [stockage des données](#data-storage) pour les emplacements et les instances séparées.
Prouvez ensuite que le recall fonctionne et donnez ses skills à votre agent :
@@ -127,14 +130,7 @@ Vous préférez laisser un agent de codage tout faire ? Confiez-lui une seule in
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Câblez d'autres agents à tout moment avec `agentmemory connect <agent>` — 20 adaptateurs listés dans [Compatible avec tous les agents](#works-with-every-agent). Référence complète des commandes dans [Démarrage rapide](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Connectez un autre agent avec `agentmemory connect <agent>`. Consultez les [intégrations](#works-with-every-agent) et les [commandes courantes](#everyday-commands).
<details>
<summary><strong>Installation globale / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx met en cache par version. Forcez la dernière avec `npx -y @agentmemory/agen
</details>
-<details>
-<summary><strong>Vous faites déjà tourner votre propre moteur iii</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Compatible avec tous les agents" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'A
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin natif + 7 hooks + MCP</sub>
+<sub>plugin natif + hooks de cycle de vie + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'A
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin natif + MCP</sub>
+<sub>recherche native + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'A
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>serveur MCP</sub>
+<sub>capture native + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory fonctionne avec tout agent qui prend en charge les hooks, MCP ou l'A
<sub>API REST</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>recherche native + capture + skills + MCP facultatif</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +306,25 @@ 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. Fonctionne entre agents.
+<a id="data-storage"></a>
-**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.
+### Stockage des données
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Les souvenirs sont conservés hors de votre dépôt par défaut :
+
+| Plateforme | Répertoire des données |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
-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 <path>` ou définissez `AGENTMEMORY_DATA_DIR` ; l'un ou l'autre réglage explicite prime sur la découverte legacy :
+L'instance 0 réutilise un `./data/state_store.db` existant. Choisissez un autre emplacement avec `--data-dir <path>` ou `AGENTMEMORY_DATA_DIR` et conservez-le lors des redémarrages et mises à niveau. `--instance 1` utilise le sous-dossier `instance-1`, le port API `3211` et le port du visualiseur `3213`. Consultez le [guide du stockage et des sauvegardes](../docs/reliability/state-storage.md) pour Redis et les migrations.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +473,7 @@ Notes de la dernière version : [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Dépendances externes</strong></td>
-<td>Aucune (SQLite + iii-engine)</td>
+<td>Aucun service de base de données séparé requis</td>
<td>Qdrant / pgvector</td>
<td>Postgres + base vectorielle</td>
<td>Multiples</td>
@@ -550,14 +547,12 @@ Notes de la dernière version : [CHANGELOG.md](../CHANGELOG.md).
| 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'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.
+AgentMemory associe capture par les agents de programmation, historique de projet interrogeable et visualiseur local. Le fonctionnement sans clé est disponible dès le premier lancement.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Démarrage rapide" height="32" /></picture></h2>
-Compatibilité : cette version cible `iii-sdk` 0.22.1 et épingle iii-engine v0.22.1.
-
### Essayez-le en 30 secondes
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Ouvrez `http://localhost:3113` pour regarder la mémoire se construire en direct.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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 :
+Avec le serveur démarré, vérifiez son état, le visualiseur et le statut :
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-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 :
+`status` indique l'état du serveur ainsi que les fournisseurs et embeddings actifs. Enregistrez un souvenir de test et vérifiez sa recherche :
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Commandes du quotidien
L'installation et le setup se trouvent dans [Installation](#install) ci-dessus (la première exécution vous guide). Au quotidien :
@@ -623,7 +627,7 @@ npx -y @agentmemory/agentmemory@latest import-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 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.
+Les sessions importées apparaissent dans le sélecteur Replay aux côtés des sessions natives. 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.
> **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.
@@ -635,14 +639,12 @@ Utilisez la commande de maintenance quand vous souhaitez intentionnellement mett
npx -y @agentmemory/agentmemory@latest upgrade
```
-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.
-
-Les détails d'implémentation se trouvent dans `src/cli.ts` (voir `runUpgrade` autour de la zone `src/cli.ts:544-595`).
+Cette commande met à jour l'environnement local et peut modifier les dépendances JavaScript de l'espace de travail courant. Sauvegardez vos données et lisez le [guide de mise à niveau](../docs/upgrades/iii-0.25.md) avant de continuer.
### Claude Code (un bloc, à coller)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code sans l'installation du plugin (chemin MCP-standalone)
@@ -703,6 +705,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Ajoutez ensuite le plugin natif depuis un checkout AgentMemory via **Settings → Plugins → Add marketplace**, puis rechargez la fenêtre. Le plugin fournit la capture du cycle de vie, l'attribution au projet, les skills et MCP. Activez soit les hooks du plugin, soit les hooks manuels de `~/.cursor/hooks.json`, pour éviter les doublons. [Guide Cursor](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Choisissez la commande correspondant à votre hôte. Pi et OMP installent recherche, capture, reprise hors ligne et 17 skills ; `--with-mcp` ajoute tous les outils. Exécutez `/reload` dans Pi ou redémarrez OMP, puis vérifiez `/agentmemory-status`. DSH installe MCP et le plugin de capture inclus ; redémarrez DSH ensuite.
+
+Pi propose aussi le paquet installable `@agentmemory/pi`. Le [guide Pi](../integrations/pi/) explique l'installation locale et la disponibilité sur npm. Utilisez une seule méthode d'installation par hôte.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (collez ce prompt)</b></summary>
@@ -749,6 +773,8 @@ Guide complet : [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Autres agents
Démarrez le serveur de mémoire : `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +791,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Ceci est **complémentaire** à `agentmemory connect <agent>` :
-- `agentmemory connect <agent>` é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.
+- `agentmemory connect <agent>` écrit généralement la configuration MCP. Hermes, OpenClaw, Pi et Oh My Pi installent leur intégration native et leurs skills par défaut ; MCP est facultatif avec `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` installe les skills des agents qui ne les incluent pas nativement. Ignorez cette étape pour Hermes, OpenClaw, Pi et Oh My Pi : leurs connecteurs les installent déjà.
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.
@@ -790,7 +816,7 @@ L'entrée agentmemory est le **même bloc de serveur MCP** sur tous les hôtes q
| Agent | Fichier de config | Notes |
|---|---|---|
| **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. |
+| **Cursor (plugin complet)** | `.cursor-plugin/` | Ajoutez ensuite le plugin natif depuis un checkout AgentMemory via **Settings → Plugins → Add marketplace**, puis rechargez la fenêtre. Le plugin fournit la capture du cycle de vie, l'attribution au projet, les skills et MCP. Activez soit les hooks du plugin, soit les hooks manuels de `~/.cursor/hooks.json`, pour éviter les doublons. [Guide Cursor](../integrations/cursor/). |
| **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 (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. |
@@ -804,7 +830,7 @@ L'entrée agentmemory est le **même bloc de serveur MCP** sur tous les hôtes q
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | recherche native + capture + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +838,19 @@ L'entrée agentmemory est le **même bloc de serveur MCP** sur tous les hôtes q
| **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` à 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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (préféré) ou `config.json` (legacy) | `agentmemory connect continue` crée une `config.yaml` absente ou modifie la `config.json` existante. Si le YAML existe, l'adaptateur affiche le bloc à ajouter sous `mcpServers:` pour préserver commentaires et ancres. Continue attend un tableau, pas un objet. |
| **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 surcharges au niveau du projet vont dans `<repo>/.factory/mcp.json`. Passez `--with-hooks` pour la capture automatique native. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` active les outils MCP. Ajoutez `--with-hooks` pour charger le plugin natif de capture inclus dans AgentMemory. Aucun paquet supplémentaire requis. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Utilisez les [exemples REST authentifiés](#validate-a-fresh-install-and-restart-persistence) pour enregistrer et rechercher des souvenirs depuis vos scripts. |
| **Tout agent (32+)** | n/a | `npx skillkit install agentmemory` détecte automatiquement l'hôte et fusionne. |
**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 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
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
-
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-Exemple travaillé : [`examples/python/`](../examples/python/) (démarrage rapide + flux observation/recall). REST sur `:3111` reste disponible pour les hôtes sans runtime iii.
+Utilisez l'[API REST](#api) depuis n'importe quel langage ou les [outils MCP](#mcp-server) depuis un agent. Les requêtes REST utilisent JSON et l'authentification bearer ; voir l'[exemple d'enregistrement et de recherche](#validate-a-fresh-install-and-restart-persistence). Les [exemples Python](../examples/python/) couvrent l'intégration directe au runtime.
### Depuis les sources
@@ -853,92 +859,33 @@ 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 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`.
-
-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=<version>` si vous faites tourner votre propre moteur et savez qu'il correspond.
-
-- **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.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` embarqué récupère `iiidev/iii:0.22.1`). Documentation complète : [iii.dev/docs](https://iii.dev/docs).
+`npm start` démarre le même serveur local que la CLI installée. Les prérequis figurent sous [Install](#install) ; l'API et le visualiseur écoutent sur `127.0.0.1`.
### Windows
-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.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
-```
-
-**Option B : Docker Desktop**
+agentmemory fonctionne sous Windows 10/11. WSL2 suit le parcours Linux et peut installer automatiquement le moteur épinglé. Sous Windows natif, installez manuellement le binaire iii-engine v0.25.0 épinglé : téléchargez l'archive correspondante depuis la [page de version iii 0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), vérifiez son checksum et placez `iii.exe` dans `PATH` (par exemple `%USERPROFILE%\.local\bin\iii.exe`). La CLI n'extrait pas automatiquement le ZIP Windows.
-```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
-```
+Sous Windows natif, le câblage MCP automatisé ne prend en charge que `agentmemory connect copilot-cli`. Pour les autres agents natifs Windows, utilisez le bloc MCP manuel de [Autres agents](#other-agents). Lancez `connect` dans WSL uniquement si l'agent cible est installé dans ce même environnement WSL.
-**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 :
+**MCP autonome uniquement (sans moteur).** Si vous avez seulement besoin des outils MCP, sans API REST, visualiseur ni services d'exécution :
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**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 |
-|---|---|
-| `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 <N>` |
-| 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) |
-
-> 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`.
+Exécutez `agentmemory doctor` ou redémarrez avec `--verbose`. Utilisez `--port <N>` ou `--instance <N>` si les ports sont occupés. Le [guide de mise à niveau](../docs/upgrades/iii-0.25.md) couvre la compatibilité et la récupération.
---
<h2 id="deploy">Déploiement</h2>
-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.
+Hébergez le service avec Docker Compose ou les modèles ci-dessous. La mémoire et les identifiants sont conservés sur le volume `/data`. Sauvegardez-le et réutilisez-le lors des mises à niveau. Le [guide de déploiement](../deploy/README.md) couvre authentification, accès réseau, sauvegardes et migration.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Le bouton de déploiement en un clic de Render 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.
@@ -957,28 +904,26 @@ visualiseur, rotation, sauvegarde, planchers de coût) se trouvent dans
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é à
-loopback à l'intérieur du conteneur ; le README de chaque template
-documente le motif de tunnel SSH pour l'atteindre.
+REST utilise le port `3111`, le visualiseur `3113`. Gardez-les privés ou protégez-les avec authentification et TLS. Le guide de déploiement détaille l'exposition réseau et la [migration des anciennes installations Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Pourquoi agentmemory" height="32" /></picture></h2>
-Chaque agent de codage oublie tout quand la session se termine, et chaque nouvelle session commence avec vous qui réexpliquez votre stack. agentmemory tourne en arrière-plan et supprime cette étape.
+Les connaissances du projet se dispersent entre conversations et fichiers d’instructions. AgentMemory permet de retrouver décisions, correctifs et enseignements depuis votre agent actuel.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs la mémoire intégrée de l'agent
@@ -987,7 +932,7 @@ Chaque agent de codage IA est livré avec une mémoire intégrée : Claude Code
| | Intégré (CLAUDE.md) | agentmemory |
|---|---|---|
-| Échelle | Plafond de 200 lignes | Illimité |
+| Entretien | Instructions maintenues manuellement | Historique des sessions et souvenirs indexés |
| 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) |
@@ -1013,13 +958,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Consolidation de mémoire à 4 niveaux
@@ -1037,6 +982,8 @@ Les mémoires se dégradent avec le temps (courbe d'Ebbinghaus). Les mémoires f
### Ce qui est capturé
+Ce tableau décrit les hooks de Claude Code. Les autres intégrations capturent les événements fournis par leur hôte ; consultez leurs guides. L'injection automatique de contexte via les hooks partagés nécessite `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Capture |
|------|----------|
| `SessionStart` | Chemin du projet, ID de session |
@@ -1053,7 +1000,7 @@ Les mémoires se dégradent avec le temps (courbe d'Ebbinghaus). Les mémoires f
| Capacité | Description |
|---|---|
-| **Capture automatique** | Chaque usage d'outil enregistré via des hooks, aucun effort manuel |
+| **Capture automatique** | Événements de session et d'outils pris en charge, enregistrés par les intégrations natives |
| **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 |
@@ -1254,7 +1201,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Visualiseur temps réel" height="32" /></picture></h2>
-Démarre automatiquement sur le port `3113`. 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.
+Démarre automatiquement sur le port `3113`. Le visualiseur charge un instantané (`GET /agentmemory/viewer/snapshot`), puis applique les événements en direct par SSE à `/agentmemory/viewer/events` sur le worker REST : mémoires, leçons, observations, entrées d'audit, changements du graphe et état apparaissent sans interrogation périodique ni rechargement.
- **12 onglets en quatre groupes** avec compteurs en direct, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1271,186 +1218,6 @@ Le serveur du visualiseur se lie à `127.0.0.1` par défaut et attache le secret
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-Le visualiseur sur `:3113` montre ce que votre agent **a 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.
-
-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 fournit tout cela gratuitement car chaque appel de fonction et chaque trigger passe par iii ; rien de custom, rien à instrumenter.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Page Workers de la console iii : workers connectés incluant les instances agentmemory avec compteurs de fonctions en direct et métadonnées runtime" width="720" />
- <br/>
- <em>Page Workers : chaque worker connecté, y compris agentmemory lui-même, avec PID, nombre de fonctions, runtime et dernière activité.</em>
-</p>
-
-**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 en même temps qu'agentmemory :**
-
-```bash
-agentmemory console
-```
-
-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.
-
-La même chose à la main, utile quand `agentmemory` n'est pas dans le PATH :
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**Ce que vous pouvez faire depuis la console :**
-
-| 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 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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Vue waterfall des traces de la console iii montrant la durée par span" width="720" />
- <br/>
- <em>Traces : waterfall / flame / répartition par service pour chaque opération de mémoire.</em>
-</p>
-
-**Les traces sont déjà activées :**
-
-`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 observability d'iii.
-
-> **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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory est **déjà une instance [iii](https://iii.dev) en cours d'exécution**. 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 seule commande supplémentaire étend agentmemory avec une toute nouvelle capacité.
-
-### Étendre agentmemory avec plus de workers
-
-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.
-
-```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 que vous obtenez en plus d'agentmemory |
-|---|---|
-| [`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:<scope>`, `stream:<name>:<group>`) 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.
-
-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.
-
-**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 des workers du moteur iii |
-| Prometheus / Grafana | iii OTEL + moniteur de santé |
-| Systèmes de plugins custom | `iii worker add <name>` |
-
-**250 fichiers sources · ~55,000 LOC · 3,800+ tests · 324 fonctions · 67 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
### Fournisseurs LLM
@@ -1468,6 +1235,8 @@ agentmemory auto-détecte les fournisseurs depuis votre environnement. Un fourni
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Modèles locaux (Ollama / LM Studio / vLLM)
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.
@@ -1517,24 +1286,7 @@ Les embeddings locaux sont livrés comme dépendance optionnelle mais ne sont pa
### Sélection de modèle sensible au coût
-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.
-
-| 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.) | 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.) extrapolent le même mix de tokens selon le tarif catalogue de chaque modèle.
-
-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é/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 : [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/).
+Commencez sans clé pour la capture et la recherche par mots-clés. `EMBEDDING_PROVIDER=local` active la recherche sémantique locale après le premier téléchargement du modèle. La compression par LLM nécessite un fournisseur et `AGENTMEMORY_AUTO_COMPRESS=true` ; elle peut envoyer une requête par observation capturée. Consultez les tarifs actuels du fournisseur avant de l'activer. Le visualiseur et `agentmemory status` affichent les fournisseurs actifs.
### Mémoire multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1564,39 +1316,22 @@ Quand `AGENT_ID` n'est pas défini, la mémoire reste non scopée (comportement
### Ports
-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 via env |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | API REST + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `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 <N>` 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.
+| Port | Usage | Configuration |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Nettoyage des processus périmés quand les ports restent liés après une exécution plantée :
+`--port <N>` définit le port API et, par défaut, celui du visualiseur sur `N+2`. Utilisez `--instance N` pour une instance séparée. Gardez les ports internes privés ; consultez le [guide de déploiement](../deploy/README.md) avant tout accès distant.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Backend de stockage : fichier (défaut) ou Redis
-`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é.
+Le stockage fichier par défaut ne nécessite aucun service de base de données séparé. Redis est facultatif avec `AGENTMEMORY_STATE_BACKEND=redis` et `AGENTMEMORY_REDIS_URL`. Changer de backend ne copie pas les souvenirs. Le [guide du stockage et des sauvegardes](../docs/reliability/state-storage.md) couvre persistance, limites Redis et export/import authentifié.
### Fichier de config
-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.
+Placez la configuration d'exécution d'agentmemory dans `~/.agentmemory/.env` plutôt que d'exporter les variables dans chaque shell. Si le visualiseur affiche une instruction telle que `export ANTHROPIC_API_KEY=...`, copiez-la dans ce fichier sans le préfixe `export`, puis redémarrez agentmemory. Définissez `AGENTMEMORY_ENV_FILE` pour choisir un autre chemin de fichier d'environnement.
-Les variables d'environnement du processus fonctionnent toujours et priment sur les valeurs du fichier.
+Les variables d'environnement du processus ont priorité sur le fichier. Redémarrez le serveur après toute modification.
Sur Windows, le même fichier se trouve à `%USERPROFILE%\.agentmemory\.env` :
@@ -1623,176 +1358,29 @@ GRAPH_EXTRACTION_ENABLED=true
### Variables d'environnement
-Créez `~/.agentmemory/.env` :
+Options courantes pour `~/.agentmemory/.env` :
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+La référence complète est [`.env.example`](../.env.example) : identifiants des fournisseurs, filtres de capture, rétention, stockage, équipe et options. `AGENTMEMORY_ENV_FILE` sélectionne un autre fichier. Ne versionnez jamais un `.env` renseigné ou un secret bearer.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 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 <secret>`, et les endpoints de mesh sync requièrent un `AGENTMEMORY_SECRET` explicitement défini sur les deux pairs.
+146 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 <secret>`, 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 :
+**L'authentification est activée par défaut.** Si `AGENTMEMORY_SECRET` n'est défini ni dans le shell ni dans `~/.agentmemory/.env`, la CLI génère un secret aléatoire au premier lancement dans `~/.agentmemory/secret` et en conserve une copie nommée `secret` dans le répertoire de données choisi, avec les permissions `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
@@ -1831,7 +1419,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Partager avec l'équipe |
| `GET` | `/agentmemory/audit` | Piste d'audit |
-Liste complète des endpoints : [`src/triggers/api.ts`](../src/triggers/api.ts)
+Liste complète des endpoints : [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1849,19 +1437,19 @@ Les événements échoués sont réessayés toutes les `AGENTMEMORY_CAPTURE_RETR
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, `<data dir>/capture-spool/<host>-<port>.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.
+**Compaction de la provenance de graphe.** La compaction des anciennes données de provenance est différée au démarrage, car elle lit des scopes anciens complets. `/agentmemory/status` indique `deferred`, ou `off` avec `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Exécutez la compaction manuelle ci-dessous pendant la maintenance. La migration de l’index de recherche est distincte : utilisez `agentmemory graph-index migrate --allow-legacy-scan` comme indiqué dans le [guide de maintenance](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1875,7 +1463,7 @@ npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
```
-**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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licence" height="32" /></picture></h2>
diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.md
index 5f0eb016..d72a99a4 100644
--- a/READMEs/README.he-IL.md
+++ b/READMEs/README.he-IL.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- סוכן הקוד שלך זוכר הכול. אין יותר הסברים חזרתיים.
- בנוי על <a href="https://github.com/iii-hq/iii">מנוע iii</a>
+ זיכרון מתמשך בין סשנים וסוכני תכנות.
</strong><br/>
- זיכרון מתמשך עבור Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, וכל לקוח MCP.
+ זיכרון מתמשך עבור Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, וכל לקוח MCP.
</p>
<p align="center">
@@ -65,6 +64,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -89,20 +89,23 @@
<a href="#how-it-works">איך זה עובד</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">מציג</a> &bull;
- <a href="#powered-by-iii">מופעל על ידי iii</a> &bull;
<a href="#configuration">תצורה</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory מתעד אירועי סשן נתמכים ומאפשר לחפש החלטות, תיקונים ולקחים בין סוכנים. בממשק הצפייה אפשר לעיין בזיכרונות, לערוך, לייצא ולמחוק אותם. חיפוש מילות מפתח עובד ללא מפתח API; embeddings מוסיפים חיפוש סמנטי.
+
+<a id="install"></a>
+
## התקנה
דרישות:
- 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 הם המסלולים הנתמכים האחרים.
+- ב-macOS/Linux נדרשים גם `curl`, מעטפת POSIX `sh` ו-`tar` להגדרה אוטומטית של הסביבה.
+- ב-Windows השתמשו ב-WSL2 או ב[הוראות ההתקנה המקורית ל-Windows](#windows).
פקודת ההתקנה הראשונית הקנונית:
@@ -110,11 +113,11 @@
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` מוגדר גם כן.
+בחרו סוכנים וספק, או מצב ללא מפתח. האשף שומר את ההגדרות, מפעיל את שרת הזיכרון ומציע התקנה גלובלית של `agentmemory`. הדגל `-y` מאשר את בקשת npm; `@latest` בוחר את הגרסה הנוכחית. דחיסה באמצעות 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 <path>` או ב-`AGENTMEMORY_DATA_DIR` כדי לשנות זאת, ולהשתמש באותו ערך בכל הפעלה מחדש. לשם תאימות לאחור, `./data/state_store.db` או `./data/iii-config.yaml` קיימים מקבלים עדיפות על פני ברירת המחדל של הפלטפורמה עבור instance 0; דגל מפורש או override של משתנה סביבה עדיין גובר.
+ה-API זמין ב-`http://localhost:3111` וממשק הצפייה ב-`http://localhost:3113`. שניהם מאזינים כברירת מחדל רק לחיבורים מקומיים. ההגדרות נמצאות ב-`~/.agentmemory/.env`; [אחסון הנתונים](#data-storage) מתאר תיקיות זיכרון ומופעים נפרדים.
לאחר מכן, הדגימו ששליפה עובדת ותנו לסוכן שלכם את ה-skills שלו:
@@ -129,14 +132,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-ניתן לחווט עוד סוכנים בכל עת עם `agentmemory connect <agent>` — 20 מתאמים מופיעים ברשימה ב[עובד עם כל סוכן](#works-with-every-agent). מדריך הפקודות המלא נמצא ב[התחלה מהירה](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-המסלול המהיר הוא WSL2. הגדרת מנוע ב-Windows מקורי דורשת הורדה של קובץ ה-ZIP הנעוץ v0.22.1 וחילוץ `iii.exe` באופן ידני; ה-CLI לא מחלץ אותו אוטומטית. Docker Desktop נתמך גם הוא. ראו את [הערות Windows](#windows) לפירוט שלב-אחר-שלב.
-
-</details>
+חברו סוכן נוסף בעזרת `agentmemory connect <agent>`. ראו [אינטגרציות](#works-with-every-agent) ו[פקודות יומיומיות](#everyday-commands).
<details>
<summary><strong>התקנה גלובלית / EACCES</strong></summary>
@@ -156,13 +152,6 @@ npx שומר במטמון לפי גרסה. אפשר לכפות את הגרסה
</details>
-<details>
-<summary><strong>כבר מריצים iii engine משלכם</strong></summary>
-
-agentmemory נעוץ לגרסה v0.22.1 של iii-engine ולא יתחבר לגרסה אחרת (ה-worker לא יודע לדבר בפרוטוקול של מנוע אחר). עצרו את המנוע האחר, ואז הריצו `npx -y @agentmemory/agentmemory@latest`. זה מתקין ומריץ את הגרסה הנעוצה v0.22.1 בתוך `~/.agentmemory/bin`, מבלי לגעת ב-`iii` שלכם.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="עובד עם כל סוכן" height="32" /></picture></h2>
@@ -189,7 +178,7 @@ agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-RES
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin מובנה + 7 hooks + MCP</sub>
+<sub>תוסף מובנה + hooks למחזור חיים + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -216,7 +205,7 @@ agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-RES
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin מובנה + MCP</sub>
+<sub>שליפה מובנית + תיעוד + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -282,7 +271,7 @@ agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-RES
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>שרת MCP</sub>
+<sub>תיעוד מובנה + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -305,6 +294,12 @@ agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-RES
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>שליפה מובנית + תיעוד + skills + MCP אופציונלי</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -313,22 +308,26 @@ agentmemory עובד עם כל סוכן שתומך ב-hooks, ב-MCP, או ב-RES
---
-אתם מסבירים את אותה הארכיטקטורה בכל session מחדש. אתם מגלים מחדש את אותן תקלות. אתם מלמדים מחדש את אותן ההעדפות. הזיכרון המובנה (CLAUDE.md, .cursorrules) מוגבל ל-200 שורות והולך ומתיישן. agentmemory פותר את זה. הוא לוכד בשקט את מה שהסוכן שלכם עושה, דוחס את זה לזיכרון שניתן לחפש בו, ומזריק את ההקשר הנכון כשה-session הבא מתחיל. פקודה אחת. עובד בין סוכנים שונים.
+<a id="data-storage"></a>
-**מה משתנה:** ב-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 <path>` או להגדיר `AGENTMEMORY_DATA_DIR`; כל הגדרה מפורשת גוברת על הגילוי ה-legacy:
+| פלטפורמה | תיקיית נתונים |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+מופע 0 משתמש מחדש ב-`./data/state_store.db` קיים. בחרו תיקייה אחרת עם `--data-dir <path>` או `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
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-הפעלות native ו-Docker משתמשות באותה תיקיית host שנפתרה; Docker עושה לה bind-mount בתוך `/data`. `--instance 1` מוסיף `instance-1` לתיקייה שנפתרה ובוחר ברביעיית הפורטים הנפרדת שבברירת המחדל `3211/3212/3213/49234`.
+`--instance 1` משתמש בתיקיית המשנה `instance-1`, בפורט API ‏`3211` ובפורט צפייה `3213`. Redis והעברת נתונים מתוארים ב[מדריך האחסון והגיבוי](../docs/reliability/state-storage.md).
הערות השחרור העדכניות: [CHANGELOG.md](../CHANGELOG.md).
@@ -478,7 +477,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>תלויות חיצוניות</strong></td>
-<td>אין (SQLite + iii-engine)</td>
+<td>אין צורך בשירות מסד נתונים נפרד</td>
<td>Qdrant / pgvector</td>
<td>Postgres + מסד נתונים וקטורי</td>
<td>מרובות</td>
@@ -552,14 +551,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | גרף ידע טמפורלי; תוצאות השאילתה הטמפורלית הפרסומיות החזקות ביותר (LongMemEval 63.8%), אבל הגרף נבנה באופן אסינכרוני כך שעובדות חדשות יכולות להתעכב |
| Cognee | 30K | בליעת מסמכים לגרף ידע (document-to-knowledge-graph), Python בלבד, נבנה לחילוץ ישויות מבני ולא ללכידת sessions |
-אף אחד מהם לא לוכד אוטומטית מ-hooks של סוכן קוד, לא מגיע עם מציג local-first, ולא רץ במצב keyless — השילוב הזה הוא מה ש-agentmemory בנוי עליו.
+AgentMemory משלב תיעוד סשנים, היסטוריית פרויקט שניתן לחפש בה וממשק צפייה מקומי, עם עבודה ללא מפתח כבר מההפעלה הראשונה.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="התחלה מהירה" height="32" /></picture></h2>
-תאימות: הגרסה הזו מיועדת ל-`iii-sdk` 0.22.1 ונעוצה לגרסה v0.22.1 של iii-engine.
-
### נסו את זה ב-30 שניות
```bash
@@ -574,9 +571,11 @@ npx -y @agentmemory/agentmemory@latest demo
פתחו את `http://localhost:3113` כדי לראות את הזיכרון נבנה בזמן אמת.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### אימות התקנה חדשה והתמדה (persistence) אחרי הפעלה מחדש
-כשהשרת רץ, יש לאמת את ה-REST, את ה-health, את המציג, ואת מצב ה-runtime המבוסס iii:
+כשהשרת פועל, בדקו תקינות, צפייה ומצב:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -585,20 +584,27 @@ 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 ואמתו שהוא ניתן לחיפוש:
+`status` מציג את מצב השרת, הספקים, מצב ה-embeddings, מסירת התצפיות והשחזור. בקשות REST מוגנות דורשות את סוד השרת. השתמשו ב-`AGENTMEMORY_SECRET` שהגדרתם; אחרת טענו את הסוד המקומי שנוצר:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
לאחר מכן הריצו `npx -y @agentmemory/agentmemory@latest stop`, הפעילו שוב את הפקודה הקנונית ב-Terminal 1, המתינו ל-`/agentmemory/livez`, וחזרו על החיפוש. ה-probe חייב עדיין להיות מוחזר. אם בחרתם `--data-dir` מותאם אישית, העבירו את אותה תיקייה בהפעלה מחדש.
+<a id="everyday-commands"></a>
+
### פקודות יומיומיות
התקנה והגדרה נמצאות ב[התקנה](#install) מעלה (ההרצה הראשונה מדריכה אתכם צעד אחר צעד). ביום-יום:
@@ -606,6 +612,9 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -625,7 +634,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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).
+סשנים מיובאים מופיעים ב-Replay לצד הסשנים המקוריים. התמלילים מתווספים לאינדקס ומסומנים במקור `import`; העיבוד יכול גם ליצור גבישי סשן ולקחים.
> **שימו לב אם אתם נשענים על `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 מפסיק להיות רלוונטי.
@@ -637,14 +646,12 @@ sessions מיובאים מופיעים בבורר ה-Replay לצד אלה המק
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`).
+הפקודה מעדכנת את הסביבה המקומית ועשויה לשנות תלויות JavaScript בסביבת העבודה הנוכחית. גבו את הנתונים וקראו את [מדריך השדרוג](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code בלי התקנת ה-plugin (נתיב MCP בלבד)
@@ -705,6 +712,30 @@ 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 המלאה.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+לאחר מכן ב-**Settings → Plugins → Add marketplace** בחרו את תיקיית agentmemory שמכילה את `.cursor-plugin/plugin.json`, הפעילו את התוסף **agentmemory** וטענו מחדש את החלון. התוסף מספק תיעוד מחזור חיים, זיהוי פרויקט לפי סביבת העבודה, skills ו-MCP. הפעילו את ה-hooks של התוסף או hooks ידניים ב-`~/.cursor/hooks.json` כדי למנוע תיעוד כפול.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+בחרו את הפקודה ללקוח שלכם. Pi ו-OMP מתקינים שליפה מובנית, תיעוד, שליחה מחדש לאחר עבודה לא מקוונת ו-skills; הדגל `--with-mcp` מוסיף את כל הכלים. הריצו `/reload` ב-Pi או הפעילו מחדש את OMP, ואז בדקו `/agentmemory-status`. DSH מתקין MCP ואת תוסף התיעוד המצורף; הפעילו מחדש את DSH לאחר החיבור.
+
+Pi תומך גם בחבילה הניתנת להתקנה `@agentmemory/pi`. התקנה מקומית וזמינות npm מתוארות ב[מדריך Pi](../integrations/pi/). השתמשו בשיטת התקנה אחת לכל לקוח.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (הדביקו את ה-prompt הזה)</b></summary>
@@ -751,6 +782,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### סוכנים אחרים
הפעילו את שרת הזיכרון: `npx -y @agentmemory/agentmemory@latest`
@@ -767,8 +800,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
זה **משלים** את `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` כותב את תצורת שרת ה-MCP כך שהכלים זמינים.
-- `npx skills add rohitg00/agentmemory` מתקין את ה-skills כך שהסוכן יודע מתי לקרוא להם.
+- `agentmemory connect <agent>` בדרך כלל כותב את הגדרות MCP. ‏Hermes, OpenClaw, Pi ו-Oh My Pi מתקינים כברירת מחדל אינטגרציה מובנית ו-skills; להפעלת MCP השתמשו ב-`--with-mcp`.
+- `npx skills add rohitg00/agentmemory` מתקין skills לסוכנים שאין להם skills מובנים בחבילה. דלגו על שלב זה עבור Hermes, OpenClaw, Pi ו-Oh My Pi; המחברים שלהם כבר מתקינים את ה-skills.
לכמה מהסוכנים שה-CLI של skills עדיין לא מכסה (Zed v1.3.x ומטה), שימו את 17 קבצי ה-SKILL.md בעצמכם תחת תיקיית ה-skills המובנית של הסוכן; אותו פורמט עובד בכל מקום.
@@ -792,7 +825,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| סוכן | קובץ תצורה | הערות |
|---|---|---|
| **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. |
+| **Cursor (plugin מלא)** | `.cursor-plugin/` | התוסף מספק hooks למחזור חיים, זיהוי סביבת עבודה, skills ו-MCP ב-Cursor IDE וב-`cursor-agent`. ראו [הגדרת Cursor](#cursor). |
| **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. |
@@ -806,7 +839,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. שליפה מובנית + תיעוד + skills. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. שליפה מובנית + תיעוד + skills. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -814,39 +848,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (מועדף) או `config.json` (legacy) | `agentmemory connect continue` יוצר `config.yaml` כשאין הגדרות, או מעדכן `config.json` קיים. עבור YAML קיים הוא מציג בלוק להוספה תחת `mcpServers:`, כדי לשמור הערות ועוגנים. Continue משתמש במערך ולא באובייקט. |
| **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-ים בתחום פרויקט נכנסים ב-`<repo>/.factory/mcp.json`. העבירו `--with-hooks` ללכידה אוטומטית מובנית. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` מפעיל את כלי MCP. הוסיפו `--with-hooks` כדי לטעון את תוסף הלכידה המובנה ב-AgentMemory. אין צורך בחבילת תוסף נפרדת. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | השתמשו ב[דוגמאות REST עם אימות](#validate-a-fresh-install-and-restart-persistence) לשמירה ולחיפוש מתוך סקריפטים. |
| **כל סוכן (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.
+השתמשו ב-[REST API](#api) מכל שפה או ב[כלי MCP](#mcp-server) מתוך סוכן. REST משתמש ב-JSON ובאימות bearer; ראו [דוגמת שמירה וחיפוש](#validate-a-fresh-install-and-restart-persistence). לאינטגרציה ישירה עם סביבת הריצה, ראו [דוגמאות Python](../examples/python/).
### מהמקור (From source)
@@ -855,83 +869,33 @@ 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=<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).
+`npm start` מפעיל את אותו שרת מקומי כמו ה-CLI המותקן. הדרישות מופיעות ב[התקנה](#install); ה-API וממשק הצפייה מאזינים ב-`127.0.0.1`.
### 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.
+agentmemory פועל ב-Windows 10/11. ‏WSL2 פועל במסלול Linux ויכול להתקין את המנוע הנעוץ אוטומטית. ב-Windows מקורי יש להתקין ידנית את הבינארי הנעוץ iii-engine v0.25.0: הורידו את הארכיון המתאים מ-[דף ההפצה של iii 0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), אמתו את ה-checksum והוסיפו את `iii.exe` ל-`PATH` (למשל `%USERPROFILE%\.local\bin\iii.exe`). ה-CLI אינו מחלץ אוטומטית את ZIP של Windows.
-**אפשרות A: בינארי Windows מוכן מראש (מומלץ)**
+חיבור MCP אוטומטי ב-Windows מקורי נתמך רק עבור `agentmemory connect copilot-cli`. עבור סוכנים מקומיים אחרים ב-Windows, השתמשו בבלוק MCP הידני מתוך [סוכנים אחרים](#other-agents). הפעילו `connect` בתוך WSL רק אם סוכן היעד מותקן באותה סביבת WSL.
-```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, דלגו על המנוע כליל:
+**MCP עצמאי בלבד (ללא מנוע).** אם דרושים רק כלי MCP, ללא REST API, מציג או שירותי runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| ה-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`.
+הריצו `agentmemory doctor` או הפעילו מחדש עם `--verbose`. אם הפורטים תפוסים, השתמשו ב-`--port <N>` או ב-`--instance <N>`. תאימות ושחזור מתוארים ב[מדריך השדרוג](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">פריסה</h2>
-תבניות בלחיצה אחת ל-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.
+לאירוח עצמי השתמשו ב-Docker Compose או בתבניות שלהלן. הזיכרון ופרטי הגישה נמצאים בנפח `/data`; גבו אותו והשתמשו בו מחדש בשדרוג. אימות, רשת, גיבוי והעברה מתוארים ב[מדריך הפריסה](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="פרסו ל-fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="פרסו ל-Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="פרסו ל-fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="פרסו ל-Railway" /></a>
</p>
כפתור הפריסה בלחיצה אחת של Render דורש `render.yaml` בשורש ה-repository, שאנחנו משאירים נקי בכוונה. השתמשו בזרימת ה-Render Blueprint המתועדת ב-[`deploy/render/`](.././deploy/render/README.md) כדי להפנות ל-blueprint שבתוך ה-repo באופן ידני.
@@ -948,29 +912,13 @@ npx -y @agentmemory/mcp
שלכם באמצעות [Coolify](https://coolify.io/self-hosted); אותה ערימת Docker
Compose, אתם הבעלים של ה-host ושל הנתונים.
-רק פורט `3111` חשוף (published). המציג בפורט `3113` נשאר קשור
-ל-loopback בתוך ה-container; ה-README של כל תבנית מתעד את תבנית
-ה-SSH-tunnel להגיע אליו.
+REST משתמש ב-`3111` וממשק הצפייה ב-`3113`. השאירו אותם פרטיים או הגנו עליהם באימות וב-TLS. הגדרות פלטפורמה ו[העברה מ-Docker הישן](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) מתוארות במדריך הפריסה.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="למה agentmemory" height="32" /></picture></h2>
-כל סוכן קוד שוכח הכול כש-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.
-```
+הידע על הפרויקט מתפזר בין שיחות וקובצי הוראות. AgentMemory מאפשר לחפש החלטות, תיקונים ולקחים קודמים מתוך הסוכן שבו משתמשים כעת.
### לעומת זיכרון מובנה בסוכן
@@ -978,7 +926,7 @@ Session 2: "Now add rate limiting"
| | מובנה (CLAUDE.md) | agentmemory |
|---|---|---|
-| קנה מידה | מוגבל ל-200 שורות | בלתי מוגבל |
+| תחזוקה | הוראות שנערכות ידנית | היסטוריית סשנים וזיכרונות עם אינדקס |
| חיפוש | טוען הכול להקשר | BM25 + וקטור + גרף (top-K בלבד) |
| עלות טוקנים | 22K+ ב-240 תצפיות | ~1,900 טוקנים (92% פחות) |
| בין-סוכנים | קבצים לפי סוכן | MCP + REST (כל סוכן) |
@@ -1004,13 +952,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### קונסולידציית זיכרון ב-4 שכבות
@@ -1028,6 +976,8 @@ SessionStart hook fires
### מה נלכד
+הטבלה מתארת את ה-hooks של Claude Code. אינטגרציות אחרות מתעדות אירועים שהלקוח שלהן מספק. הזרקת הקשר אוטומטית דרך ה-hooks המשותפים היא אופציונלית: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | מה נלכד |
|------|----------|
| `SessionStart` | נתיב הפרויקט, מזהה ה-session |
@@ -1044,7 +994,7 @@ SessionStart hook fires
| יכולת | תיאור |
|---|---|
-| **לכידה אוטומטית** | כל שימוש ב-tool נרשם דרך hooks, בלי מאמץ ידני |
+| **לכידה אוטומטית** | אירועי סשן וכלים נתמכים המתועדים באינטגרציות מובנות |
| **חיפוש סמנטי** | BM25 + וקטור + גרף ידע עם fusion מסוג RRF |
| **אבולוציית זיכרון** | ניהול גרסאות, supersession, גרפי יחסים |
| **היגיינת שליפה (recall)** | גרסאות זיכרון שהוחלפו (superseded) עוזבות את אינדקסי החיפוש; שרשרת הגרסאות ב-KV שומרת היסטוריה מלאה |
@@ -1245,7 +1195,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="מציג בזמן אמת" height="32" /></picture></h2>
-מופעל אוטומטית בפורט `3113`. המציג טוען snapshot אחד כשהוא מתחבר (`GET /agentmemory/viewer/snapshot`) ואז מחיל אירועי stream חיים: זיכרונות חדשים, lessons, תצפיות, רשומות audit, שינויי גרף ועדכוני health מופיעים בלי polling או רילוד של הדף. הבקשות האחרות היחידות הן הפעולות שאתם מקליקים, עמודי "טען עוד" וחיפושים. כשה-stream נופל, המציג מציג כמה זמן המספרים שלו ישנים, מתחבר מחדש עם backoff ומסתנכרן מחדש מ-snapshot אחד.
+המַציג מופעל אוטומטית בפורט `3113`. הוא טוען snapshot אחד (`GET /agentmemory/viewer/snapshot`) ואז מחיל אירועים חיים ב-SSE ב-`/agentmemory/viewer/events` על worker ‏REST: זיכרונות, לקחים, תצפיות, רשומות audit, שינויים בגרף ועדכוני health מופיעים ללא polling או טעינת דף מחדש.
- **12 לשוניות בארבע קבוצות** עם ספירות חיות, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#health/consolidation`), קיצורי מקלדת, ותפריט מובייל.
- **זיכרונות:** חיפוש בצד השרת, filters לפי פרויקט, סוכן וסוג, פאנל פרטים עם שרשרת הגרסאות ו-word diff, קישורי provenance, כפתורי copy למזהה, לקריאת ה-MCP ולפקודת curl, עריכה (גרסה חדשה), forget עם אישור, forget בכמות (bulk) וייצוא JSON.
@@ -1262,187 +1212,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="קונסולת iii" height="32" /></picture></h2>
-
-המציג בפורט `: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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="עמוד ה-Workers של קונסולת iii: workers מחוברים כולל instances של agentmemory עם ספירות פונקציות חיות ומטא-דאטה של runtime" width="720" />
- <br/>
- <em>עמוד ה-Workers: כל worker מחובר, כולל agentmemory עצמו, עם PID, ספירת פונקציות, runtime, ו-last-seen.</em>
-</p>
-
-**מותקן כבר.** הקונסולה נשלחת עם מנוע ה-`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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="תצוגת waterfall של trace בקונסולת iii שמציגה משך זמן per-span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / פירוק-שירות לכל פעולת זיכרון.</em>
-</p>
-
-**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` (ברירת המחדל) ואל תחשפו אותה לעולם באופן ציבורי.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="מופעל על ידי iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) קבועים, כך ששני 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 <name>` |
-
-**250 קבצי מקור · ~55,000 LOC · 3,400+ בדיקות · 324 פונקציות · 67 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="תצורה" height="32" /></picture></h2>
### ספקי LLM
@@ -1460,6 +1229,8 @@ agentmemory מגלה ספקים אוטומטית מהסביבה שלכם. ספק
| **מקומי (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=<your 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, אז זה כבר לא ברירת המחדל. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### מודלים מקומיים (Ollama / LM Studio / vLLM)
agentmemory מדבר עם כל שרת תואם-OpenAI-API, כך שכל דבר שחושף `/v1/chat/completions` עובד בלי שינויי קוד. בלי מפתחות בתשלום, בלי cloud, בלי rate limits; רץ כולו על החומרה שלכם.
@@ -1509,24 +1280,7 @@ embeddings מקומיים נשלחים כתלות אופציונלית אבל ל
### בחירת מודל מודעת-עלות
-כשדחיסת רקע בכתיבת 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/).
+התחילו ללא מפתח לתיעוד ולחיפוש מילות מפתח. `EMBEDDING_PROVIDER=local` מאפשר חיפוש סמנטי מקומי לאחר הורדת המודל. דחיסת LLM דורשת ספק ו-`AGENTMEMORY_AUTO_COMPRESS=true`; היא עשויה לשלוח בקשה לכל תצפית, לכן בדקו מחירים עדכניים. ממשק הצפייה ו-`agentmemory status` מציגים ספקים פעילים.
### זיכרון multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1556,39 +1310,22 @@ override לפי-קריאה בשכבת SDK / REST: כל endpoint משנה (`/sess
### פורטים
-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 | מטרה | משתנה סביבה |
+|---|---|---|
+| `3111` | REST API, MCP HTTP ואירועי צפייה בזמן אמת | `III_REST_PORT` |
+| `3113` | ממשק צפייה | `III_VIEWER_PORT` |
-`--port <N>` משנה את העוגן (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 הולכים לפי אותה תבנית.
+`--port <N>` מגדיר את פורט REST ואת ברירת המחדל של הצפייה ל-`N+2`. `--instance N` יוצר סביבה נפרדת. פורטים פנימיים חייבים להישאר פרטיים; קראו את [מדריך הפריסה](../deploy/README.md) לפני פתיחת גישה מרחוק.
-המנוע הנעוץ מתחיל עם `--no-update-check` (בלי בדיקות עדכון או security-advisory מול GitHub באתחול) ועם הטלמטריית השימוש האנונימית של iii כבויה: agentmemory מגדיר `III_TELEMETRY_ENABLED=false` למנוע שהוא יוצר אלא אם אתם מייצאים (export) את המשתנה בעצמכם, וקובץ ה-compose המצורף עושה את אותו דבר.
+### אחסון: קובץ או Redis
-ניקוי תהליכים תקועים (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 <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.
+אחסון הקבצים המוגדר כברירת מחדל אינו דורש מסד נפרד. Redis אופציונלי עם `AGENTMEMORY_STATE_BACKEND=redis` ו-`AGENTMEMORY_REDIS_URL`. החלפת backend אינה מעתיקה זיכרונות קיימים. התמדה, מגבלות Redis וייצוא/ייבוא עם אימות מתוארים ב[מדריך האחסון](../docs/reliability/state-storage.md).
### קובץ תצורה
-שימו את תצורת ה-runtime של agentmemory ב-`~/.agentmemory/.env` במקום לייצא (export) משתנים בכל shell. אם המציג מציג רמז הקמה כמו `export ANTHROPIC_API_KEY=...`, העתיקו אותו לקובץ הזה כ-`ANTHROPIC_API_KEY=...` בלי ה-prefix `export`, ואז הפעילו מחדש את agentmemory.
+הגדירו את תצורת זמן הריצה של agentmemory בקובץ `~/.agentmemory/.env` במקום לייצא משתנים בכל shell. אם המַציג מציג הנחיה כמו `export ANTHROPIC_API_KEY=...`, העתיקו לקובץ ללא התחילית `export` ואז הפעילו מחדש את agentmemory. הגדירו `AGENTMEMORY_ENV_FILE` כדי להשתמש בנתיב אחר לקובץ הסביבה.
-משתני סביבת התהליך עדיין עובדים וגוברים על ערכים בקובץ.
+משתני הסביבה של התהליך קודמים לערכי הקובץ. הפעילו מחדש את השרת לאחר שינוי הגדרות.
ב-Windows, אותו קובץ נמצא ב-`%USERPROFILE%\.agentmemory\.env`:
@@ -1615,176 +1352,27 @@ GRAPH_EXTRACTION_ENABLED=true
### משתני סביבה
-צרו `~/.agentmemory/.env`:
+אפשרויות נפוצות עבור `~/.agentmemory/.env`. הזרקת הקשר ודחיסה הן אופציונליות; דחיסה דורשת גם ספק. מצב `core` מצמצם את כלי ה-MCP הגלויים:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+ההפניה המלאה [`.env.example`](../.env.example) כוללת ספקים, מסנני תיעוד, שמירה, אחסון, צוותים ותכונות אופציונליות. `AGENTMEMORY_ENV_FILE` בוחר קובץ אחר. לעולם אל תוסיפו ל-commit קובץ `.env` מלא או סוד bearer.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer <secret>`, ו-endpoints של mesh sync דורשים `AGENTMEMORY_SECRET` מוגדר באופן מפורש בשני ה-peers.
+146 endpoints בפורט `3111`. ה-REST API נקשר ל-`127.0.0.1` כברירת מחדל. endpoints מוגנים דורשים `Authorization: Bearer <secret>`, ו-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 ביד:
+**אימות (Authentication) פעיל כברירת מחדל.** אם `AGENTMEMORY_SECRET` לא מוגדר, בהפעלה הראשונה ה-CLI יוצר סוד אקראי ב-`~/.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
@@ -1823,7 +1411,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | שיתוף עם הצוות |
| `GET` | `/agentmemory/audit` | audit trail |
-רשימת endpoints מלאה: [`src/triggers/api.ts`](../src/triggers/api.ts)
+רשימת endpoints מלאה: [הפניית REST שנוצרה מהקוד](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1841,19 +1429,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
כשהשרת נפול, לא עונה בזמן, או מחזיר 5xx, ה-hook מוסיף את התצפית לקובץ spool מקומי, `<data dir>/capture-spool/<host>-<port>.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` כדי לכבות את זה.
+**דחיסת provenance של הגרף.** דחיסת נתוני provenance ישנים נדחית בזמן האתחול, משום שהיא קוראת scopes ישנים בשלמותם. `/agentmemory/status` מציג `deferred`, או `off` כאשר `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. הפעילו את הדחיסה הידנית שלהלן בזמן תחזוקה. העברת אינדקס האחזור היא פעולה נפרדת: השתמשו ב־`agentmemory graph-index migrate --allow-legacy-scan` לפי [מדריך התחזוקה](../docs/reliability/graph-index-migration.md).
כדי להריץ את זה ביד, קראו ל-`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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1867,7 +1455,7 @@ npm test # 4,000+ 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.
+הדרישות מופיעות ב[התקנה](#install). כללי התרומה ובדיקות ההפצה נמצאים ב-[CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="רישיון" height="32" /></picture></h2>
diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.md
index 3eafb2cc..13f86ed8 100644
--- a/READMEs/README.hi-IN.md
+++ b/READMEs/README.hi-IN.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- आपका कोडिंग एजेंट सब कुछ याद रखता है। अब दोबारा समझाने की ज़रूरत नहीं।
- <a href="https://github.com/iii-hq/iii">iii engine</a> पर बना।
+ कोडिंग सत्रों और एजेंटों के बीच स्थायी मेमोरी।
</strong><br/>
- Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, और किसी भी MCP क्लाइंट के लिए स्थायी मेमोरी।
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, और किसी भी MCP क्लाइंट के लिए स्थायी मेमोरी।
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">यह कैसे काम करता है</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">व्यूअर</a> &bull;
- <a href="#powered-by-iii">iii द्वारा संचालित</a> &bull;
<a href="#configuration">कॉन्फ़िग</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory कोडिंग सत्र रिकॉर्ड करता है ताकि पुराने फैसले और सुधार खोजे जा सकें। अलग-अलग टूल में एक मेमोरी स्टोर इस्तेमाल करें, सेव की गई जानकारी देखें और मॉडल को मिलने वाला संदर्भ चुनें।
+
+<a id="install"></a>
+
## इंस्टॉल
आवश्यकताएं:
- 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 अन्य समर्थित रास्ते हैं।
+- macOS/Linux के स्वतः सेटअप के लिए `curl`, POSIX `sh` और `tar` चाहिए।
+- Windows / WSL2: [Windows](#windows).
मानक fresh-install कमांड:
@@ -108,11 +111,11 @@
npx -y @agentmemory/agentmemory@latest
```
-पहली रन एक 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 हो।
+अपने एजेंट और प्रोवाइडर या बिना कुंजी वाला मोड चुनें। सेटअप कॉन्फ़िगरेशन सेव करके मेमोरी सर्वर शुरू करता है और ग्लोबल इंस्टॉल का विकल्प देता है। `-y` npm की पुष्टि स्वीकार करता है; `@latest` नवीनतम रिलीज चुनता है। LLM कम्प्रेशन के लिए प्रोवाइडर और `AGENTMEMORY_AUTO_COMPRESS=true` दोनों चाहिए।
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 <path>` या `AGENTMEMORY_DATA_DIR` का उपयोग करें, और हर restart पर वही value फिर से उपयोग करें। backward compatibility के लिए, instance 0 के लिए मौजूदा `./data/state_store.db` या `./data/iii-config.yaml`, platform default से आगे आता है; एक explicit flag या environment override फिर भी जीतता है।
+API `http://localhost:3111` और लाइव व्यूअर `http://localhost:3113` पर हैं। दोनों डिफ़ॉल्ट रूप से loopback पर सुनते हैं। कॉन्फ़िगरेशन `~/.agentmemory/.env` में रहती है। [डेटा स्टोरेज](#data-storage).
फिर साबित करें कि recall काम करता है और अपने एजेंट को उसकी skills दें:
@@ -127,14 +130,7 @@ default keyless mode में keyword searches को BM25 के माध्
> https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md पर मौजूद instructions प्राप्त करें और उनका पालन करें।
-किसी भी समय `agentmemory connect <agent>` से और एजेंट जोड़ें — 20 adapters [हर एजेंट के साथ काम करता है](#works-with-every-agent) में सूचीबद्ध हैं। पूरा command reference [क्विक स्टार्ट](#quick-start) में है।
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-सबसे तेज़ रास्ता WSL2 है। Native Windows engine setup के लिए pinned v0.22.1 ZIP को डाउनलोड करना और `iii.exe` को manually extract करना ज़रूरी है; CLI इसे auto-extract नहीं करता। Docker Desktop भी समर्थित है। Step-by-step के लिए [Windows नोट्स](#windows) देखें।
-
-</details>
+`agentmemory connect <agent>` से दूसरा एजेंट जोड़ें। [समर्थित इंटीग्रेशन](#works-with-every-agent) और [रोज़मर्रा की कमांड](#everyday-commands) देखें।
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx प्रति-version cache करता है। `npx -y @agentmemory/ag
</details>
-<details>
-<summary><strong>पहले से अपना iii engine चला रहे हैं</strong></summary>
-
-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` को बिना छुए छोड़ते हुए।
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory किसी भी ऐसे एजेंट के साथ क
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>नेटिव प्लगइन + lifecycle hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory किसी भी ऐसे एजेंट के साथ क
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>नेटिव recall + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory किसी भी ऐसे एजेंट के साथ क
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP सर्वर</sub>
+<sub>नेटिव capture + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory किसी भी ऐसे एजेंट के साथ क
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>नेटिव recall + capture + skills + वैकल्पिक MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ agentmemory किसी भी ऐसे एजेंट के साथ क
---
-आप हर session में वही architecture समझाते हैं। आप वही bugs फिर से खोजते हैं। आप वही preferences फिर से सिखाते हैं। Built-in memory (CLAUDE.md, .cursorrules) 200 लाइनों पर सीमित है और पुरानी हो जाती है। agentmemory इसे ठीक करता है। यह चुपचाप आपके एजेंट की गतिविधियाँ capture करता है, उन्हें searchable memory में compress करता है, और अगला session शुरू होने पर सही context inject करता है। एक कमांड। सभी एजेंट्स के साथ काम करता है।
+<a id="data-storage"></a>
-**क्या बदलता है:** 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 -y @agentmemory/agentmemory@latest
-```
+मेमोरी डिफ़ॉल्ट रूप से रिपॉज़िटरी के बाहर रहती है। इंस्टेंस 0 मौजूदा `./data/state_store.db` को दोबारा इस्तेमाल करता है। `--data-dir <path>` या `AGENTMEMORY_DATA_DIR` से जगह चुनें और रीस्टार्ट या अपग्रेड में वही डायरेक्टरी रखें।
-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 <path>` पास करें या `AGENTMEMORY_DATA_DIR` set करें; दोनों में से कोई भी explicit setting legacy discovery से पहले आती है:
+| प्लेटफ़ॉर्म | डेटा डायरेक्टरी |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-Native और Docker launches इस्तेमाल वही resolved host directory करते हैं; Docker इसे `/data` पर bind-mount करता है। `--instance 1`, resolved directory में `instance-1` जोड़ता है और अलग default port quartet `3211/3212/3213/49234` चुनता है।
+`--instance 1` में `instance-1` सबडायरेक्टरी, API पोर्ट `3211` और व्यूअर पोर्ट `3213` इस्तेमाल होते हैं। Redis और बैकएंड माइग्रेशन के लिए [स्टोरेज और बैकअप](../docs/reliability/state-storage.md) देखें।
नवीनतम release notes: [CHANGELOG.md](../CHANGELOG.md)।
@@ -476,7 +473,7 @@ Native और Docker launches इस्तेमाल वही resolved host d
</tr>
<tr>
<td><strong>बाहरी निर्भरताएँ</strong></td>
-<td>कोई नहीं (SQLite + iii-engine)</td>
+<td>अलग डेटाबेस सेवा की जरूरत नहीं</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>कई</td>
@@ -550,14 +547,12 @@ Native और Docker launches इस्तेमाल वही resolved host d
| Zep / Graphiti | 30K | Temporal knowledge graph; सबसे मज़बूत published temporal-query results (LongMemEval 63.8%), लेकिन graph asynchronously build होता है इसलिए ताज़ा facts पिछड़ सकते हैं |
| Cognee | 30K | Document-to-knowledge-graph ingestion, केवल-Python, session capture के बजाय structured entity extraction के लिए बना |
-इनमें से कोई भी coding-agent hooks से auto-capture नहीं करता, local-first viewer ship नहीं करता, या keyless नहीं चलता — वही combination जिसके इर्द-गिर्द agentmemory बना है।
+AgentMemory सत्र capture, खोजने योग्य प्रोजेक्ट इतिहास और लोकल व्यूअर साथ देता है; पहली बार से ही बिना कुंजी के काम कर सकते हैं।
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-संगतता: यह release `iii-sdk` 0.22.1 को target करता है और iii-engine को v0.22.1 पर pin करता है।
-
### 30 सेकंड में आज़माएँ
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
memory को लाइव बनते हुए देखने के लिए `http://localhost:3113` खोलें।
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### एक fresh install और restart persistence को validate करें
-server चलते हुए, REST, health, viewer, और iii-backed runtime status को validate करें:
+सर्वर चलते समय उसकी सेहत, व्यूअर और स्थिति जाँचें।
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-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 है:
+`status` सर्वर की सेहत, प्रोवाइडर, embedding mode, capture delivery और recovery दिखाता है। सुरक्षित REST अनुरोधों के लिए सर्वर secret चाहिए। सेट किया हुआ `AGENTMEMORY_SECRET` इस्तेमाल करें; यदि सेट नहीं है तो बनाया गया लोकल secret पढ़ें।
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
फिर `npx -y @agentmemory/agentmemory@latest stop` चलाएँ, Terminal 1 में मानक कमांड फिर से शुरू करें, `/agentmemory/livez` के लिए wait करें, और search दोहराएँ। probe अभी भी return होना चाहिए। अगर आपने कोई custom `--data-dir` चुना था, तो restart पर वही directory पास करें।
+<a id="everyday-commands"></a>
+
### रोज़मर्रा की कमांड्स
Install और setup ऊपर [इंस्टॉल](#install) में हैं (पहली रन आपको इसके माध्यम से ले जाती है)। दिन-प्रतिदिन:
@@ -604,7 +608,10 @@ Install और setup ऊपर [इंस्टॉल](#install) में ह
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
-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 होती है।
+इम्पोर्ट किए सत्र Replay में नेटिव सत्रों के साथ दिखते हैं, खोज के लिए इंडेक्स होते हैं और उनकी origin channel `import` होती है। सत्र प्रोसेसिंग से crystals और lessons भी बन सकते हैं।
> **ध्यान दें अगर आप `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 मायने रखना बंद कर दे।
@@ -635,14 +642,12 @@ Imported sessions native ones के साथ Replay picker में दिख
npx -y @agentmemory/agentmemory@latest upgrade
```
-चेतावनी: यह कमांड 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` region के आसपास `runUpgrade` देखें)।
+यह लोकल रनटाइम अपडेट करता है और वर्तमान कार्य डायरेक्टरी की JavaScript निर्भरताएँ भी बदल सकता है। डेटा का बैकअप लें और मौजूदा इंस्टॉलेशन अपडेट करने से पहले [अपग्रेड गाइड](../docs/upgrades/iii-0.25.md) पढ़ें।
### Claude Code (एक block, paste करें)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Plugin install के बिना Claude Code (MCP-standalone path)
@@ -703,6 +708,26 @@ 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 करें।
+### Cursor
+
+`agentmemory connect cursor` से MCP सेट करें। **Settings → Plugins → Add marketplace** में `.cursor-plugin/plugin.json` वाला checkout चुनें, agentmemory चालू करें और विंडो reload करें। प्लगइन lifecycle capture, workspace पहचान, skills और MCP देता है। दोहरा capture रोकने के लिए प्लगइन hooks या `~/.cursor/hooks.json` वाले मैनुअल hooks में से एक ही चालू करें।
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+अपने होस्ट की कमांड चुनें। Pi और OMP नेटिव recall/capture, ऑफ़लाइन replay और 17 skills इंस्टॉल करते हैं; `--with-mcp` पूरा टूलसेट जोड़ता है। Pi में `/reload` चलाएँ या OMP रीस्टार्ट करें, फिर `/agentmemory-status` देखें। DSH MCP और साथ आया capture plugin इंस्टॉल करता है; जोड़ने के बाद रीस्टार्ट करें।
+
+Pi के लिए इंस्टॉल करने योग्य `@agentmemory/pi` पैकेज भी है। लोकल इंस्टॉल और npm उपलब्धता के लिए [Pi गाइड](../integrations/pi/) देखें। हर होस्ट पर एक ही इंस्टॉल तरीका अपनाएँ।
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (यह prompt paste करें)</b></summary>
@@ -749,6 +774,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### अन्य एजेंट्स
memory server शुरू करें: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
यह `agentmemory connect <agent>` के लिए **complementary** है:
-- `agentmemory connect <agent>` MCP server config लिखता है ताकि tools उपलब्ध हों।
-- `npx skills add rohitg00/agentmemory` skills install करता है ताकि agent को पता चले कि उन्हें कब call करना है।
+Hermes, OpenClaw, Pi और Oh My Pi कनेक्टर डिफ़ॉल्ट रूप से नेटिव इंटीग्रेशन और skills इंस्टॉल करते हैं; MCP को `--with-mcp` से जोड़ें। दूसरे होस्ट पर `npx skills add rohitg00/agentmemory` से skills इंस्टॉल करें।
जिन कुछ agents को skills CLI अभी cover नहीं करती (Zed v1.3.x और उससे नीचे), उनके लिए 17 SKILL.md files को agent की native skill directory में खुद drop करें; वही format हर जगह काम करता है।
@@ -790,7 +816,7 @@ agentmemory entry, `mcpServers` shape का उपयोग करने वा
| एजेंट | Config फाइल | नोट्स |
|---|---|---|
| **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 होते हैं। |
+| **Cursor (पूर्ण plugin)** | `.cursor-plugin/` | Cursor Marketplace या Settings → Plugins → लोकल checkout से इंस्टॉल करें। साझा `plugin/scripts/*.mjs` चलाने वाला छोटा adapter lifecycle hooks, skills और MCP जोड़ता है। यह Cursor द्वारा ठीक से रिपोर्ट न किए गए workspace को पहचानता है। [Cursor](#cursor) देखें। Cursor IDE और `cursor-agent` CLI में काम करता है। |
| **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 (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 करें। |
@@ -804,7 +830,8 @@ agentmemory entry, `mcpServers` shape का उपयोग करने वा
| **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 को 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`)। |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · नेटिव recall + capture + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · नेटिव recall + capture + skills. [Oh My Pi](../integrations/omp/) |
| **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 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)। |
@@ -812,39 +839,19 @@ agentmemory entry, `mcpServers` shape का उपयोग करने वा
| **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 नहीं) का उपयोग करता है। |
+| **Continue.dev** | `~/.continue/config.yaml` (preferred) या `config.json` (legacy) | `agentmemory connect continue` कॉन्फ़िगरेशन न होने पर `config.yaml` बनाता है या मौजूद `config.json` अपडेट करता है। पहले से मौजूद YAML के comments और anchors बचाने के लिए उसे नहीं बदलता, बल्कि `mcpServers:` के नीचे पेस्ट करने का block दिखाता है। Continue का `mcpServers` एक array है। |
| **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 `<repo>/.factory/mcp.json` में जाते हैं। Native auto-capture के लिए `--with-hooks` pass करें। |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` MCP टूल चालू करता है। AgentMemory में शामिल नेटिव कैप्चर प्लगइन लोड करने के लिए `--with-hooks` जोड़ें। अलग प्लगइन पैकेज की ज़रूरत नहीं है। [DSH](../docs/dsh.md). |
| **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"}'`। |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **कोई भी एजेंट (32+)** | n/a | `npx skillkit install agentmemory` host को auto-detect करता है और merge करता है। |
**Sandboxed MCP क्लाइंट्स** (Flatpak / Snap / प्रतिबंधात्मक containers) जो host के `localhost` तक नहीं पहुँच सकते: `env` block में `"AGENTMEMORY_FORCE_PROXY": "1"` भी set करें, और `AGENTMEMORY_URL` को एक ऐसे route पर point करें जिस तक sandbox वास्तव में पहुँच सकता है (जैसे आपका LAN IP)।
-### Programmatic access (Python / Rust / Node)
+### Programmatic access
-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
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
-
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-कार्यशील उदाहरण: [`examples/python/`](../examples/python/) (quickstart + observation/recall flow)। iii runtime के बिना hosts के लिए REST `:3111` पर उपलब्ध रहता है।
+किसी भी भाषा से [REST API](#api) या एजेंट से [MCP टूल](#mcp-server) इस्तेमाल करें। REST में JSON और Bearer प्रमाणीकरण चाहिए; [सेव और खोज का उदाहरण](#validate-a-fresh-install-and-restart-persistence) देखें। रनटाइम से सीधे जुड़ने के लिए [Python उदाहरण](../examples/python/) हैं।
### Source से
@@ -853,92 +860,33 @@ git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
-यह 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` मैनुअली 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=<version>` से override करें।
-
-- **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` download करें और `iii.exe` को `%USERPROFILE%\.agentmemory\bin\iii.exe` में extract करें
-
-हर 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)।
+`npm start` इंस्टॉल किए गए CLI जैसा ही लोकल सर्वर शुरू करता है। आवश्यकताएँ [इंस्टॉल](#install) में हैं; API और व्यूअर `127.0.0.1` पर सुनते हैं।
### Windows
-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 चुनना होगा।
+agentmemory Windows 10/11 पर चलता है। WSL2 Linux path अपनाता है और pinned engine को automatically install कर सकता है। Native Windows पर pinned iii-engine v0.25.0 binary manually install करें: [iii v0.25.0 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) से सही archive download करें, checksum verify करें और `iii.exe` को `PATH` में रखें (उदाहरण: `%USERPROFILE%\.local\bin\iii.exe`)। CLI Windows ZIP को automatically extract नहीं करता।
-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 नहीं करता।
+Native Windows में automated MCP wiring केवल `agentmemory connect copilot-cli` को support करती है। अन्य native Windows agents के लिए [Other agents](#other-agents) वाला manual MCP block इस्तेमाल करें। `connect` को WSL में तभी चलाएँ जब target agent भी उसी WSL environment में installed हो।
-**विकल्प A: prebuilt Windows binary (अनुशंसित)**
-
-```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: केवल standalone MCP (कोई engine नहीं)।** अगर आपको केवल अपने agent के लिए MCP tools चाहिए और REST API, viewer, या cron jobs की ज़रूरत नहीं है, तो engine को पूरी तरह से skip करें:
+**केवल standalone MCP (engine के बिना)।** यदि सिर्फ MCP tools चाहिए और REST API, viewer या runtime services की आवश्यकता नहीं है:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**Windows के लिए diagnostics:** अगर `npx -y @agentmemory/agentmemory@latest` fail करता है, तो वास्तविक engine stderr देखने के लिए `--verbose` के साथ फिर से चलाएँ। सामान्य failure modes:
-
-| लक्षण | समाधान |
-|---|---|
-| `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 <N>` का उपयोग करें |
-| 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.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` में ला देता है।
+`agentmemory doctor` चलाएँ या `--verbose` के साथ रीस्टार्ट करें। डिफ़ॉल्ट पोर्ट व्यस्त हों तो `--port <N>` या `--instance <N>` इस्तेमाल करें। अनुकूलता और recovery के लिए [अपग्रेड गाइड](../docs/upgrades/iii-0.25.md) देखें।
---
<h2 id="deploy">डिप्लॉय</h2>
-Managed hosts के लिए one-click templates। प्रत्येक एक self-contained
-Dockerfile ship करता है जो npm से `@agentmemory/agentmemory` खींचता है
-और आधिकारिक `iiidev/iii` Docker Hub image से iii engine binary को
-copy करता है; किसी pre-built agentmemory image की आवश्यकता नहीं। Persistent
-storage `/data` पर mount होती है; first-boot entrypoint npm-bundled
-iii config (जो `127.0.0.1` से bind करती है) को एक deploy-tuned config
-से overwrite करता है जो `0.0.0.0` से bind करती है और absolute `/data`
-paths का उपयोग करती है, HMAC secret generate करती है, फिर agentmemory
-CLI को exec करने से पहले `gosu` के माध्यम से privileges को `root` से
-`node` पर drop करती है।
+Docker Compose या नीचे दिए प्लेटफ़ॉर्म टेम्पलेट से खुद होस्ट करें। मेमोरी और क्रेडेंशियल `/data` वॉल्यूम में रहते हैं। अपग्रेड पर इसका बैकअप लें और वही वॉल्यूम इस्तेमाल करें। प्रमाणीकरण, नेटवर्क और माइग्रेशन के लिए [डिप्लॉयमेंट गाइड](../deploy/README.md) देखें।
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Render का one-click deploy button repository root पर `render.yaml` की आवश्यकता रखता है,
@@ -958,28 +906,26 @@ rotation, backup, cost floors) [`deploy/`](.././deploy/README.md) में र
[Coolify](https://coolify.io/self-hosted) के माध्यम से self-hosted; वही Docker
Compose stack, आप host और data के मालिक हैं।
-केवल port `3111` publish किया जाता है। `3113` पर viewer container के अंदर
-loopback से bound रहता है; हर template का README उस तक पहुँचने के लिए
-SSH-tunnel pattern को document करता है।
+REST पोर्ट `3111` और व्यूअर `3113` इस्तेमाल करते हैं। इन्हें निजी रखें या प्रमाणीकरण और TLS से सुरक्षित करें। प्लेटफ़ॉर्म की नेटवर्क सेटिंग और [पुराने Docker से माइग्रेशन](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) डिप्लॉयमेंट गाइड में हैं।
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-हर coding agent session समाप्त होने पर सब कुछ भूल जाता है, और हर नया session आपके अपने stack को फिर से समझाने से शुरू होता है। agentmemory पृष्ठभूमि में चलता है और उस step को हटा देता है।
+प्रोजेक्ट की जानकारी चैट और निर्देश फ़ाइलों में बिखर जाती है। 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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### बिल्ट-इन agent memory से तुलना
@@ -988,7 +934,7 @@ Session 2: "Now add rate limiting"
| | बिल्ट-इन (CLAUDE.md) | agentmemory |
|---|---|---|
-| Scale | 200-line cap | असीमित |
+| देखभाल | हाथ से व्यवस्थित निर्देश | इंडेक्स किया गया सत्र इतिहास और मेमोरी |
| खोज | सब कुछ context में load करता है | BM25 + vector + graph (केवल top-K) |
| Token cost | 240 observations पर 22K+ | ~1,900 tokens (92% कम) |
| Cross-agent | प्रति-agent फाइलें | MCP + REST (कोई भी agent) |
@@ -1014,13 +960,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-Tier Memory Consolidation
@@ -1038,6 +984,8 @@ Memories समय के साथ decay होती हैं (Ebbinghaus cur
### क्या Capture होता है
+नीचे की तालिका Claude Code के hooks दिखाती है। दूसरे इंटीग्रेशन अपने होस्ट के उपलब्ध events कैप्चर करते हैं। साझा hooks से अपने-आप संदर्भ जोड़ने के लिए `AGENTMEMORY_INJECT_CONTEXT=true` को स्पष्ट रूप से चालू करें।
+
| Hook | Captures |
|------|----------|
| `SessionStart` | Project path, session ID |
@@ -1054,7 +1002,7 @@ Memories समय के साथ decay होती हैं (Ebbinghaus cur
| क्षमता | विवरण |
|---|---|
-| **Automatic capture** | हर tool use hooks के माध्यम से record होता है, कोई manual effort नहीं |
+| **Automatic capture** | नेटिव इंटीग्रेशन समर्थित सत्र और टूल events रिकॉर्ड करते हैं |
| **Semantic search** | RRF fusion के साथ BM25 + vector + knowledge graph |
| **Memory evolution** | Versioning, supersession, relationship graphs |
| **Recall hygiene** | Superseded memory versions search indexes से निकल जाते हैं; KV में version chain पूरा history रखती है |
@@ -1255,7 +1203,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
-Port `3113` पर auto-start होता है। 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 करता है।
+Viewer port `3113` पर स्वतः शुरू होता है। यह connect होने पर एक snapshot (`GET /agentmemory/viewer/snapshot`) लेता है, फिर REST worker के `/agentmemory/viewer/events` पर SSE से live events लागू करता है: नई memories, lessons, observations, audit entries, graph changes और health updates बिना polling या reload के दिखते हैं.
- **चार groups में 12 tabs**, live counts, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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।
@@ -1272,187 +1220,6 @@ Viewer server default रूप से `127.0.0.1` से bind होता ह
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-`:3113` पर viewer दिखाता है कि आपके agent ने क्या **याद रखा**। [iii console](https://iii.dev/docs/console) दिखाता है कि आपके agent ने क्या **किया**: हर memory op एक OpenTelemetry trace के रूप में, हर KV entry editable, हर function invocable, हर stream tappable। एक ही memory पर दो windows: एक product-shaped, एक engine-shaped।
-
-`memory_smart_search` को fire होते देखें और BM25 scan → embedding lookup → RRF fusion → reranker को waterfall के रूप में देखें। KV browser में stuck consolidation timer को edit करें। `PostToolUse` hook को tweaked payload के साथ replay करें। WebSocket stream को pin करें और observations को live land होते देखें।
-
-agentmemory इसे free में ship करता है क्योंकि हर function call और trigger iii के माध्यम से fire होता है; कुछ भी custom नहीं, instrument करने के लिए कुछ नहीं।
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers page: connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
- <br/>
- <em>Workers page: हर connected worker, agentmemory स्वयं सहित, PID, function count, runtime, और last-seen के साथ।</em>
-</p>
-
-**पहले से installed।** Console pinned `iii` engine (0.22+) के साथ ship होता है; कोई अलग installer नहीं। पहली launch console binary को engine के बगल में download करती है।
-
-**agentmemory के साथ launch करें:**
-
-```bash
-agentmemory console
-```
-
-यह 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`।
-
-वही चीज़ हाथ से, तब उपयोगी जब `agentmemory` PATH पर न हो:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**Console से आप क्या कर सकते हैं:**
-
-| Page | इसके लिए उपयोग करें |
-|------|-----------|
-| **Workers** | हर connected worker और उसके live metrics देखें, agentmemory worker सहित। |
-| **Functions** | agentmemory के किसी भी function को सीधे JSON payload के साथ invoke करें; client जोड़े बिना `memory.recall`, `memory.consolidate`, `graph.query` test करने के लिए उपयोगी। |
-| **Triggers** | HTTP, cron, event, और state triggers replay करें: consolidation cron को manually fire करें, HTTP route retry करें, एक state change emit करें। |
-| **States** | Sessions, memory slots, lifecycle timers, और embeddings index पर full CRUD वाला KV browser; values को in place edit करें। |
-| **Streams** | Memory writes, hook events, और observation updates के लिए live WebSocket monitor क्योंकि वे iii streams से बहते हैं। |
-| **Queues** | Durable queue topics + dead-letter management। Failed embedding / compression jobs को replay या drop करें। |
-| **Traces** | OpenTelemetry waterfall / flame / service-breakdown views। `trace_id` से filter करें ताकि देख सकें कि एक `memory.search` ने वास्तव में कौन से functions, DB calls, और embedding requests produce किए। |
-| **Logs** | Trace/span IDs से correlated और filtered structured OTEL logs। |
-| **Config** | Runtime configuration: देखें कि आपका engine किन workers, providers, और ports के साथ चल रहा है। |
-| **Flow** | (Optional, `--enable-flow`) हर worker, trigger, और stream का interactive architecture graph। |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
- <br/>
- <em>Traces: हर memory operation के लिए waterfall / flame / service breakdown।</em>
-</p>
-
-**Traces पहले से on हैं:**
-
-`iii-config.yaml` `iii-observability` worker enabled (`exporter: memory`, `sampling_ratio: 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 करें।
-
-> **ध्यान दें:** console पर कोई auth enforce नहीं है; इसे `127.0.0.1` (default) से bound रखें और इसे कभी publicly expose न करें।
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory **पहले से एक चल रहा [iii](https://iii.dev) instance है**। तीन 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 करता है।
-
-इसका मतलब है कि एक और command agentmemory को एक पूरी नई capability के साथ extend करता है।
-
-### agentmemory को और workers के साथ extend करें
-
-जो 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 करें।
-
-```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 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:<scope>`, `stream:<name>:<group>`) 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 उपयोग करता है |
-|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
-| SQLite / Postgres + pgvector | iii KV State + in-memory vector index |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | iii engine worker supervision |
-| Prometheus / Grafana | iii OTEL + health monitor |
-| Custom plugin systems | `iii worker add <name>` |
-
-**250 source files · ~55,000 LOC · 3,400+ tests · 324 functions · 67 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
### LLM Providers
@@ -1519,24 +1286,9 @@ Local embeddings एक optional dependency के रूप में ship ह
### Cost-aware model selection
-जब 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 | नोट्स |
-|------|-------|------------|-------------|---------------------------|-------|
-| अनुशंसित | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (est.) | नवीनतम DeepSeek; compression workloads के लिए सबसे सस्ता अनुशंसित pick। |
-| अनुशंसित | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet से ~10× कम cost पर solid compression + summarization quality। |
-| अनुशंसित | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | अगर आपके sessions भारी रूप से code-shaped हैं तो strong code reasoning। |
-| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (est.) | Measured Sonnet 4.6 run के समान list price; 2026-08-31 तक $2/$10 intro pricing। |
-| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (est.) | Flagship tier; always-on background work के लिए महंगा। |
-| बचें | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (est.) | Flagship-class model; compression के लिए overspend। |
-
-Measured rows captured run से आती हैं; (est.) rows उसी token mix को हर model की list price से scale करती हैं।
+बिना कुंजी के कैप्चर और कीवर्ड खोज से शुरुआत करें। `EMBEDDING_PROVIDER=local` पहला मॉडल डाउनलोड होने के बाद डिवाइस पर अर्थ-आधारित खोज देता है। LLM कम्प्रेशन में प्रोवाइडर और `AGENTMEMORY_AUTO_COMPRESS=true` चाहिए; हर observation पर अनुरोध हो सकता है, इसलिए वर्तमान कीमतें जाँचें।
-जब `OPENROUTER_MODEL` premium-tier pattern से match करता है तो agentmemory एक runtime warning print करता है। जब आप informed choice कर लें तो silence करने के लिए `AGENTMEMORY_SUPPRESS_COST_WARNING=1` set करें।
-
-Memory work के लिए quality बनाम cost tradeoff: compression एक summarization task है जिसमें अपेक्षाकृत loose quality bars हैं (agent summary को re-read करता है, user नहीं)। DeepSeek V4 Flash / V4 Pro / Qwen3-Coder इस task पर Sonnet से rounding error के भीतर land होते हैं जबकि 10-70× कम cost में। Premium-tier models को उन queries के लिए save करें जिन्हें आप सीधे पढ़ते हैं।
-
-Sources: [Claude Sonnet 5 के लिए OpenRouter pricing](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing नोट्स](https://api-docs.deepseek.com/quick_start/pricing/)।
+`agentmemory status` / http://localhost:3113
### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1566,37 +1318,22 @@ SDK / REST layer पर per-call override: हर mutating endpoint (`/session/s
### Ports
-agentmemory + iii-engine default रूप से चार ports पर bind होते हैं। अगर एक restart `port in use` के साथ fail होता है, तो यह table बताती है कि किस process को देखना है।
-
-| Port | Process | उद्देश्य | Env override |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | Internal streams worker (agentmemory + viewer द्वारा consumed) | `III_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 <N>` 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 करते हैं।
+API और व्यूअर डिफ़ॉल्ट रूप से loopback पर सुनते हैं।
-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 भी वही करती है।
+| Port | API / व्यूअर | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | व्यूअर | `III_VIEWER_PORT` |
-Crashed run के बाद ports bound रहने पर stale-process cleanup:
+`--port <N>` API पोर्ट सेट करता है; व्यूअर का डिफ़ॉल्ट `N+2` है। अलग इंस्टेंस के लिए `--instance N` इस्तेमाल करें। आंतरिक listener निजी रखें। रिमोट एक्सेस और [पुराने Docker से माइग्रेशन](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) के लिए डिप्लॉयमेंट गाइड देखें।
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage backend: file (default) बनाम Redis
-`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 पीछे नहीं छोड़ी गई।
+अलग डेटाबेस सेवा की जरूरत नहीं. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. बैकएंड बदलने से मौजूदा मेमोरी अपने-आप कॉपी नहीं होती। [डेटा स्टोरेज](../docs/reliability/state-storage.md).
### Config File
-हर shell में variables export करने के बजाय agentmemory runtime configuration को `~/.agentmemory/.env` में रखें। अगर viewer `export ANTHROPIC_API_KEY=...` जैसा setup hint दिखाता है, तो इसे `export` prefix के बिना इस file में `ANTHROPIC_API_KEY=...` के रूप में copy करें, फिर agentmemory restart करें।
+हर shell में variables export करने के बजाय agentmemory runtime config `~/.agentmemory/.env` में रखें। Viewer `export ANTHROPIC_API_KEY=...` जैसी setup hint दिखाए तो `export` हटाकर इसे file में copy करें और agentmemory restart करें। दूसरा env-file path चुनने के लिए `AGENTMEMORY_ENV_FILE` set करें.
Process environment variables अभी भी काम करते हैं और file में values पर precedence लेते हैं।
@@ -1625,176 +1362,31 @@ GRAPH_EXTRACTION_ENABLED=true
### Environment Variables
-`~/.agentmemory/.env` बनाएँ:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+पूरी सेटिंग सूची [`.env.example`](../.env.example) में है: प्रोवाइडर, capture filters, retention, storage और team scope। `AGENTMEMORY_ENV_FILE` से दूसरी फ़ाइल चुनें। बदलाव के बाद रीस्टार्ट करें। असली मानों वाली `.env` या Bearer secret कमिट न करें।
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-Port `3111` पर 143 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। Protected endpoints `Authorization: Bearer <secret>` की आवश्यकता रखते हैं, और mesh sync endpoints दोनों peers पर एक explicitly set `AGENTMEMORY_SECRET` की आवश्यकता रखते हैं।
+Port `3111` पर 146 endpoints। REST API default रूप से `127.0.0.1` से bind होता है। Protected endpoints `Authorization: Bearer <secret>` की आवश्यकता रखते हैं, और 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 करने के लिए:
+प्रमाणीकरण डिफ़ॉल्ट रूप से चालू है। `AGENTMEMORY_SECRET` सेट न होने पर CLI पहली बार एक random secret `~/.agentmemory/secret` में रखता है और चुनी हुई डेटा डायरेक्टरी के `secret` में उसकी प्रति बनाता है; permissions `0600` होती हैं। साथ आए क्लाइंट लोकल कनेक्शन में इस मूल फ़ाइल को प्राथमिकता देते हैं और सेव किया secret सिर्फ loopback URL को भेजते हैं। स्पष्ट `AGENTMEMORY_SECRET` प्राथमिकता रखता है; रिमोट क्लाइंट को इसे environment में सेट करना होता है। Docker अपना secret बनाता है।
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
@@ -1833,7 +1425,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Team के साथ share करें |
| `GET` | `/agentmemory/audit` | Audit trail |
-Full endpoint list: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Full endpoint list: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1851,19 +1443,19 @@ Failed events को हर `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) प
जब server down हो, समय पर answer न दे, या एक 5xx return करे, तो hook observation को एक local spool file में append करता है, `<data dir>/capture-spool/<host>-<port>.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 करें।
+**Graph provenance को compact करना।** पुराने provenance की compaction स्टार्टअप पर स्थगित रहती है, क्योंकि यह पुराने scopes को पूरा पढ़ती है। `/agentmemory/status` में `deferred`, या `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` होने पर `off` दिखता है। नीचे दी गई मैन्युअल compaction रखरखाव के दौरान चलाएँ। Retrieval index migration अलग है: [रखरखाव गाइड](../docs/reliability/graph-index-migration.md) के अनुसार `agentmemory graph-index migrate --allow-legacy-scan` चलाएँ।
इसे हाथ से चलाने के लिए, `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1877,7 +1469,7 @@ npm test # 4,000+ 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 automatic engine install के लिए `curl`, एक POSIX `sh`, और `tar` भी ज़रूरी हैं; native Windows manual pinned `iii.exe`, WSL2, या Docker Desktop का उपयोग करता है।
+आवश्यकताएँ [इंस्टॉल](#install) में और योगदान व रिलीज जाँच [CONTRIBUTING.md](../CONTRIBUTING.md) में हैं।
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.md
index b23825ca..892a1a4d 100644
--- a/READMEs/README.hu-HU.md
+++ b/READMEs/README.hu-HU.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- A kódolóágensed mindenre emlékszik. Nem kell többé újra elmagyaráznod.
- A <a href="https://github.com/iii-hq/iii">iii engine</a>-re épül
+ Tartós memória kódolási munkamenetek és ágensek között.
</strong><br/>
- Á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.
+ Állandó memória a Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode és bármely MCP kliens számára.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licenc" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Csillagok" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">Hogyan működik</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Megjelenítő</a> &bull;
- <a href="#powered-by-iii">iii által hajtva</a> &bull;
<a href="#configuration">Konfiguráció</a> &bull;
<a href="#api">API</a>
</p>
---
+Az AgentMemory rögzíti a támogatott munkamenet-eseményeket, és kereshetővé teszi a döntéseket, javításokat és tanulságokat az ágensek között. A nézőfelületen megtekintheted, szerkesztheted, exportálhatod és törölheted az emlékeket. A kulcsszavas keresés API-kulcs nélkül működik; az embeddingek szemantikus keresést adnak.
+
## 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.
+- macOS/Linux alatt az automatikus környezetbeállításhoz `curl`, POSIX `sh` és `tar` is szükséges.
+- Windowson használj WSL2-t vagy kövesd a [natív Windows útmutatót](#windows).
A kanonikus friss telepítési parancs:
@@ -108,11 +109,11 @@ A kanonikus friss telepítési parancs:
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.
+Válaszd ki az ágenseket és egy szolgáltatót vagy a kulcs nélküli módot. A varázsló elmenti a beállításokat, elindítja a memóriaszervert és felajánlja az `agentmemory` parancs globális telepítését. A `-y` elfogadja az npm kérdését; a `@latest` az aktuális kiadást választja. Az LLM-tömörítéshez szolgáltató és `AGENTMEMORY_AUTO_COMPRESS=true` kell.
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 <path>` 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.
+Az API a `http://localhost:3111`, a nézőfelület a `http://localhost:3113` címen érhető el. Alapból mindkettő csak helyben figyel. A beállítások a `~/.agentmemory/.env` fájlban vannak; a könyvtárakat és külön példányokat az [adattárolás](#data-storage) ismerteti.
Ezután bizonyítsd be, hogy a felidézés működik, és add meg az ágensednek a saját skilljeit:
@@ -127,14 +128,7 @@ Inkább hagynád, hogy egy kódolóágens végezze el az egészet? Add neki egye
> 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 <agent>` 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ó.
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Másik ágenst az `agentmemory connect <agent>` paranccsal kapcsolhatsz be. Lásd az [integrációkat](#works-with-every-agent) és a [napi parancsokat](#everyday-commands).
<details>
<summary><strong>Globális telepítés / EACCES</strong></summary>
@@ -154,13 +148,6 @@ Az npx verziónként gyorsítótáraz. Kényszerítsd a legújabbat az `npx -y @
</details>
-<details>
-<summary><strong>Már fut egy saját iii engine</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Működik minden ágenssel" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ Az agentmemory bármelyik olyan ágenssel működik, amely támogatja a hookokat
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>natív plugin + 7 hook + MCP</sub>
+<sub>natív plugin + életciklus-hookok + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ Az agentmemory bármelyik olyan ágenssel működik, amely támogatja a hookokat
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>natív plugin + MCP</sub>
+<sub>natív visszakeresés + rögzítés + skillek</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ Az agentmemory bármelyik olyan ágenssel működik, amely támogatja a hookokat
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP szerver</sub>
+<sub>natív rögzítés + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ Az agentmemory bármelyik olyan ágenssel működik, amely támogatja a hookokat
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>natív visszakeresés + rögzítés + skillek + opcionális MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +304,26 @@ Az agentmemory bármelyik olyan ágenssel működik, amely támogatja a hookokat
---
-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.
+<a id="data-storage"></a>
-**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.
+### Adattárolás
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Az emlékek alapból a repozitóriumon kívül maradnak:
-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 <path>` 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:
+| Platform | Adatkönyvtár |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+A 0. példány újrahasználja a meglévő `./data/state_store.db` tárolót. Másik könyvtárat a `--data-dir <path>` vagy `AGENTMEMORY_DATA_DIR` ad meg. Újraindításkor és frissítéskor tartsd meg ugyanazt a könyvtárat.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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 `--instance 1` az `instance-1` alkönyvtárat, a `3211` API-portot és a `3213` nézőfelület-portot használja. A Redis és a költöztetés az [adattárolási és mentési útmutatóban](../docs/reliability/state-storage.md) szerepel.
A legfrissebb kiadási megjegyzések: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +473,7 @@ A legfrissebb kiadási megjegyzések: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Külső függőségek</strong></td>
-<td>Nincs (SQLite + iii-engine)</td>
+<td>Nem szükséges külön adatbázis-szolgáltatás</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektor DB</td>
<td>Több</td>
@@ -550,14 +547,12 @@ A legfrissebb kiadási megjegyzések: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+Az AgentMemory egyesíti a munkamenetek rögzítését, a kereshető projektelőzményeket és a helyi nézőfelületet, az első indítástól kulcs nélküli működéssel.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Gyors indítás" height="32" /></picture></h2>
-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
@@ -572,9 +567,11 @@ A `demo` 3 reális sessiont hoz létre (JWT hitelesítés, N+1 lekérdezés jav
Nyisd meg a `http://localhost:3113` címet, hogy élőben lásd a memória épülését.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+A futó szerveren ellenőrizd az állapotot és a nézőfelületet:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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ő:
+A `status` megmutatja a szerver állapotát, a szolgáltatókat, az embeddingmódot, a megfigyelések kézbesítését és a helyreállítást. A védett REST-kérésekhez a szerver titka kell. Használd a saját `AGENTMEMORY_SECRET` értékét, ha beállítottad; különben olvasd be a generált helyi titkot:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### 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:
@@ -604,6 +608,9 @@ A telepítés és a beállítás a fenti [Telepítés](#install) részben él (a
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Az importált munkamenetek a Replay nézetben jelennek meg a natívak mellett. Az átiratok keresési indexet és `import` eredetjelölést kapnak; a feldolgozás munkamenet-kristályokat és tanulságokat is készíthet.
> **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é.
@@ -635,14 +642,12 @@ Használd a karbantartási parancsot, amikor szándékosan frissíteni akarod a
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).
+A parancs frissíti a helyi környezetet, és módosíthatja az aktuális munkaterület JavaScript-függőségeit. Mentsd az adatokat, és olvasd el a [frissítési útmutatót](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code a plugin telepítése nélkül (önálló MCP útvonal)
@@ -703,6 +708,30 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Ezután a **Settings → Plugins → Add marketplace** menüben válaszd ki a `.cursor-plugin/plugin.json` fájlt tartalmazó agentmemory könyvtárat, engedélyezd az **agentmemory** plugint és töltsd újra az ablakot. A plugin életciklus-rögzítést, munkaterület-alapú projektazonosítást, skilleket és MCP-t ad. A plugin hookjait vagy a `~/.cursor/hooks.json` kézi hookjait használd, hogy elkerüld a dupla rögzítést.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Válaszd ki a használt kliens parancsát. A Pi és az OMP natív visszakeresést, rögzítést, offline újraküldést és skilleket telepít; a `--with-mcp` hozzáadja a teljes eszközkészletet. Pi alatt futtasd a `/reload` parancsot, az OMP-t indítsd újra, majd ellenőrizd az `/agentmemory-status` eredményét. A DSH MCP-t és a mellékelt rögzítőplugint telepíti; csatlakoztatás után indítsd újra a DSH-t.
+
+A Pi a telepíthető `@agentmemory/pi` csomagot is támogatja. A helyi telepítést és az npm-elérhetőséget a [Pi útmutató](../integrations/pi/) írja le. Kliensenként egy telepítési módot használj.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (illeszd be ezt a promptot)</b></summary>
@@ -749,6 +778,8 @@ Teljes útmutató: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Egyéb ágensek
Indítsd el a memóriaszervert: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +796,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Ez **kiegészíti** az `agentmemory connect <agent>`-et:
-- az `agentmemory connect <agent>` 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.
+- Az `agentmemory connect <agent>` általában MCP-konfigurációt ír. A Hermes, OpenClaw, Pi és Oh My Pi alapból a natív integrációt és skilleket telepíti; az MCP a `--with-mcp` kapcsolóval kérhető.
+- Az `npx skills add rohitg00/agentmemory` a mellékelt natív skillek nélküli ágenseknek telepít skilleket. Hermes, OpenClaw, Pi és Oh My Pi esetén ezt hagyd ki; a csatlakoztatójuk már telepíti a skilleket.
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.
@@ -790,7 +821,7 @@ Az agentmemory bejegyzés **ugyanaz az MCP szerver blokk** minden olyan hoszton,
| Á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. |
+| **Cursor (teljes plugin)** | `.cursor-plugin/` | A plugin életciklus-hookokat, munkaterület-felismerést, skilleket és MCP-t ad a Cursor IDE és a `cursor-agent` számára. Lásd a [Cursor beállítását](#cursor). |
| **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. |
@@ -804,7 +835,8 @@ Az agentmemory bejegyzés **ugyanaz az MCP szerver blokk** minden olyan hoszton,
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. natív visszakeresés + rögzítés + skillek. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. natív visszakeresés + rögzítés + skillek. [Oh My Pi](../integrations/omp/). |
| **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. |
@@ -812,39 +844,19 @@ Az agentmemory bejegyzés **ugyanaz az MCP szerver blokk** minden olyan hoszton,
| **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. |
+| **Continue.dev** | `~/.continue/config.yaml` (előnyben részesített) vagy `config.json` (örökölt) | Az `agentmemory connect continue` létrehozza a hiányzó `config.yaml` fájlt, vagy módosítja a meglévő `config.json` fájlt. Meglévő YAML esetén kiírja az `mcpServers:` alá illeszthető blokkot, megőrizve a megjegyzéseket és horgonyokat. A Continue tömböt használ, nem objektumot. |
| **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 `<repo>/.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` bekapcsolja az MCP-eszközöket. A `--with-hooks` betölti az AgentMemoryhoz mellékelt natív rögzítőbővítményt. Külön bővítménycsomag nem szükséges. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Szkriptekből a [hitelesített REST-példákkal](#validate-a-fresh-install-and-restart-persistence) tárolhatsz és kereshetsz. |
| **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.
+Bármely nyelvből használhatod a [REST API-t](#api), ágensből pedig az [MCP-eszközöket](#mcp-server). A REST JSON-t és bearer-hitelesítést használ; lásd a [tárolási és keresési példát](#validate-a-fresh-install-and-restart-persistence). A közvetlen környezetintegrációhoz lásd a [Python-példákat](../examples/python/).
### Forrásból
@@ -853,91 +865,33 @@ 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=<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).
+Az `npm start` ugyanazt a helyi szervert indítja, mint a telepített CLI. A követelmények a [telepítésnél](#install) szerepelnek; az API és a nézőfelület a `127.0.0.1` címen figyel.
### 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**
+Az agentmemory Windows 10/11 rendszeren fut. A WSL2 a Linux útvonalat követi, és automatikusan telepítheti a rögzített motort. Natív Windowson kézzel telepítse a rögzített iii-engine v0.25.0 binárist: töltse le a megfelelő archívumot az [iii v0.25.0 kiadási oldaláról](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), ellenőrizze az ellenőrzőösszeget, majd helyezze az `iii.exe` fájlt a `PATH`-ra (például `%USERPROFILE%\.local\bin\iii.exe`). A CLI nem bontja ki automatikusan a Windows ZIP-et.
-```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
-```
+A natív Windows automatizált MCP-kapcsolat csak az `agentmemory connect copilot-cli` parancsot támogatja. Más natív Windows-ügynökökhöz használja az [Egyéb ügynökök](#other-agents) kézi MCP-blokkját. A `connect` parancsot csak akkor futtassa WSL-ben, ha a célügynök is ugyanabban a WSL-környezetben van telepítve.
-**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:
+**Csak önálló MCP (motor nélkül).** Ha csak MCP-eszközökre van szüksége, REST API, megjelenítő vagy runtime-szolgáltatások nélkül:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>`-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.
+Futtasd az `agentmemory doctor` parancsot, vagy indíts újra `--verbose` kapcsolóval. Foglalt portoknál használj `--port <N>` vagy `--instance <N>` beállítást. A kompatibilitás és helyreállítás a [frissítési útmutatóban](../docs/upgrades/iii-0.25.md) szerepel.
---
<h2 id="deploy">Telepítés (Deploy)</h2>
-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.
+Önálló üzemeltetéshez Docker Compose-t vagy az alábbi sablonokat használd. A memória és a hitelesítő adatok a `/data` köteten vannak; frissítéskor mentsd és használd újra. A hitelesítést, hálózatot, mentést és költöztetést a [telepítési útmutató](../deploy/README.md) ismerteti.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Telepítés a fly.io-ra" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Telepítés a Railway-re" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Telepítés a fly.io-ra" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Telepítés a Railway-re" /></a>
</p>
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.
@@ -955,29 +909,13 @@ költségküszöbök) a [`deploy/`](.././deploy/README.md)-ben élnek:
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.
+A REST portja `3111`, a nézőfelületé `3113`. Tartsd őket privát hálózaton, vagy védd hitelesítéssel és TLS-sel. A platformbeállítások és a [régi Docker költöztetése](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) a telepítési útmutatóban szerepelnek.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Miért agentmemory" height="32" /></picture></h2>
-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 projektismeretek beszélgetések és instrukciófájlok között szóródnak szét. Az AgentMemory kereshetővé teszi a korábbi döntéseket, javításokat és tanulságokat az éppen használt ágensből.
### A beépített ágensmemóriával szemben
@@ -985,7 +923,7 @@ Minden AI kódolóágens beépített memóriával érkezik: a Claude Code-nak `M
| | Beépített (CLAUDE.md) | agentmemory |
|---|---|---|
-| Méretezés | 200 soros korlát | Korlátlan |
+| Karbantartás | Kézzel gondozott instrukciók | Indexelt munkamenet-előzmények és emlékek |
| 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) |
@@ -1011,13 +949,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4 szintű memória-konszolidáció
@@ -1035,6 +973,8 @@ A memóriák idővel lecsengenek (Ebbinghaus-görbe). A gyakran elért memóriá
### Mi kerül rögzítésre
+A táblázat a Claude Code hookjait írja le. Más integrációk a kliens által biztosított eseményeket rögzítik. A közös hookok automatikus kontextusbeillesztése külön engedélyezhető: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Rögzíti |
|------|----------|
| `SessionStart` | Projekt-útvonal, session-ID |
@@ -1051,7 +991,7 @@ A memóriák idővel lecsengenek (Ebbinghaus-görbe). A gyakran elért memóriá
| 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 |
+| **Automatikus rögzítés** | A natív integrációk által rögzített támogatott munkamenet- és eszközesemények |
| **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 |
@@ -1252,7 +1192,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Valós idejű megjelenítő" height="32" /></picture></h2>
-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.
+A viewer automatikusan elindul a `3113` porton. Csatlakozáskor egy snapshotot tölt be (`GET /agentmemory/viewer/snapshot`), majd a REST worker `/agentmemory/viewer/events` útvonalán érkező SSE-vel alkalmazza az élő eseményeket: az új memóriák, leckék, megfigyelések, auditbejegyzések, gráfváltozások és health-frissítések lekérdezés és oldal-újratöltés nélkül jelennek meg.
- **12 fül, négy csoportban**, élő számlálókkal, deep linkekkel (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1269,187 +1209,6 @@ A megjelenítő szervere alapértelmezetten a `127.0.0.1`-hez kötődik, és csa
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii konzol" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers oldal: csatlakoztatott workerek, köztük agentmemory-instance-ok, élő funkciószámokkal és futtatókörnyezet-metaadatokkal" width="720" />
- <br/>
- <em>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.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace vízesés nézet, amely a per-span időtartamot mutatja" width="720" />
- <br/>
- <em>Traces: vízesés / flame / szolgáltatás-bontás minden memória-művelethez.</em>
-</p>
-
-**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é.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="iii által hajtva" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 forrásfájl · ~55,000 LOC · 3,400+ teszt · 324 funkció · 67 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfiguráció" height="32" /></picture></h2>
### LLM-szolgáltatók
@@ -1467,6 +1226,8 @@ Az agentmemory automatikusan felismeri a szolgáltatókat a környezetedből. Eg
| **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=<your 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é. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1277,7 @@ A lokális embeddingek opcionális függőségként érkeznek, de nem alapértel
### 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/).
+Kezdj kulcs nélkül a rögzítéshez és kulcsszavas kereséshez. Az `EMBEDDING_PROVIDER=local` a modell letöltése után helyi szemantikus keresést ad. Az LLM-tömörítéshez szolgáltató és `AGENTMEMORY_AUTO_COMPRESS=true` kell; minden megfigyelés kérést indíthat, ezért ellenőrizd az aktuális árakat. Az aktív szolgáltatókat a nézőfelület és az `agentmemory status` mutatja.
### Több ágenses memória (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1307,22 @@ Amikor az `AGENT_ID` nincs beállítva, a memória hatókör nélkül marad (ör
### 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` |
+| Port | Cél | Környezeti változó |
+|---|---|---|
+| `3111` | REST API, MCP HTTP és élő nézőfelület-események | `III_REST_PORT` |
+| `3113` | Nézőfelület | `III_VIEWER_PORT` |
-A `--port <N>` 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 `--port <N>` állítja a REST-portot, a nézőfelület alapértéke `N+2`. A `--instance N` külön környezetet hoz létre. A belső portok maradjanak privátak; távoli elérés előtt olvasd el a [telepítési útmutatót](../deploy/README.md).
-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.
+### Tárolás: fájl vagy Redis
-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 <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.
+Az alapértelmezett fájltároló nem igényel külön adatbázist. A Redis opcionális az `AGENTMEMORY_STATE_BACKEND=redis` és `AGENTMEMORY_REDIS_URL` beállításokkal. A backendváltás nem másolja át a memóriát. A tartósság, a Redis korlátai és a hitelesített export/import a [tárolási útmutatóban](../docs/reliability/state-storage.md) szerepelnek.
### 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.
+Az agentmemory runtime-beállításait a `~/.agentmemory/.env` fájlba tegye ahelyett, hogy minden shellben változókat exportálna. Ha a viewer például `export ANTHROPIC_API_KEY=...` beállítási tippet mutat, másolja a fájlba az `export` előtag nélkül, majd indítsa újra az agentmemoryt. Másik env-fájlútvonalhoz állítsa be az `AGENTMEMORY_ENV_FILE` változót.
-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.
+A folyamat környezeti változói megelőzik a fájl értékeit. Beállításmódosítás után indítsd újra a szervert.
Windowson ugyanez a fájl a `%USERPROFILE%\.agentmemory\.env`-ben él:
@@ -1622,176 +1349,27 @@ GRAPH_EXTRACTION_ENABLED=true
### Környezeti változók
-Hozd létre a `~/.agentmemory/.env`-et:
+Gyakori beállítások a `~/.agentmemory/.env` fájlban. A kontextusbeillesztés és tömörítés opcionális; a tömörítéshez szolgáltató is kell. A `core` mód szűkíti a látható MCP-eszközöket:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+A teljes [`.env.example`](../.env.example) leírja a szolgáltatókat, rögzítési szűrőket, megőrzést, tárolást, csapatokat és opcionális funkciókat. Az `AGENTMEMORY_ENV_FILE` másik fájlt választ. Kitöltött `.env` fájlt vagy bearer-titkot soha ne commitolj.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 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 <secret>`-et igényelnek, és a mesh-sync végpontok mindkét oldalon explicit módon beállított `AGENTMEMORY_SECRET`-et igényelnek.
+146 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 <secret>`-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:
+**A hitelesítés alapértelmezetten be van kapcsolva.** Ha az `AGENTMEMORY_SECRET` nincs beállítva, a CLI első indításkor véletlen titkot hoz létre a `~/.agentmemory/secret` fájlban `0600` jogosultsággal, és a kiválasztott adatkönyvtárba is átmásolja. 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
@@ -1830,7 +1408,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Megosztás csapattal |
| `GET` | `/agentmemory/audit` | Audit-nyomvonal |
-Teljes végpontlista: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Teljes végpontlista: [Generált REST-referencia](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1426,19 @@ Az elbukott eseményeket a rendszer minden `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_M
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, `<data dir>/capture-spool/<host>-<port>.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.
+**A gráf-eredet tömörítése.** A régi eredetadatok tömörítése induláskor elhalasztódik, mert teljes régi scope-okat olvas be. Az `/agentmemory/status` értéke `deferred`, vagy `off`, ha `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Az alábbi kézi tömörítést karbantartás közben futtasd. A keresési index migrációja külön művelet: használd az `agentmemory graph-index migrate --allow-legacy-scan` parancsot a [karbantartási útmutató](../docs/reliability/graph-index-migration.md) szerint.
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1452,7 @@ npm test # 4,000+ 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.
+A követelmények a [telepítésnél](#install) szerepelnek. A hozzájárulási szabályok és kiadásellenőrzések a [CONTRIBUTING.md](../CONTRIBUTING.md) fájlban találhatók.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licenc" height="32" /></picture></h2>
diff --git a/READMEs/README.id-ID.md b/READMEs/README.id-ID.md
index 35ced774..02da4592 100644
--- a/READMEs/README.id-ID.md
+++ b/READMEs/README.id-ID.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Agen coding Anda mengingat segalanya. Tidak perlu menjelaskan ulang.
- Dibangun di atas <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Memori persisten lintas sesi coding dan agen.
</strong><br/>
- Memori persisten untuk Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, dan klien MCP apa pun.
+ Memori persisten untuk Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, dan klien MCP apa pun.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Lisensi" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Star" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Cara Kerja</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Didukung oleh iii</a> &bull;
<a href="#configuration">Konfigurasi</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory merekam sesi coding agar keputusan dan perbaikan bisa dicari kembali. Gunakan satu penyimpanan memori di berbagai alat, periksa data yang tersimpan, dan tentukan banyaknya konteks yang diterima model.
+
+<a id="install"></a>
+
## 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.
+- Setup otomatis di macOS/Linux memerlukan `curl`, POSIX `sh`, dan `tar`.
+- Windows / WSL2: [Windows](#windows).
Perintah instalasi awal yang baku:
@@ -108,11 +111,11 @@ Perintah instalasi awal yang baku:
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.
+Pilih agen dan penyedia atau mode tanpa kunci. Setup menyimpan konfigurasi, menjalankan server memori, dan menawarkan instalasi global. `-y` menerima konfirmasi npm; `@latest` memilih rilis terbaru. Kompresi oleh LLM memerlukan penyedia serta `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+API tersedia di `http://localhost:3111` dan viewer langsung di `http://localhost:3113`. Keduanya memakai loopback secara default. Konfigurasi disimpan di `~/.agentmemory/.env`. [Penyimpanan data](#data-storage).
Lalu buktikan bahwa recall berfungsi dan beri agen Anda skill-nya:
@@ -127,14 +130,7 @@ Lebih suka membiarkan agen coding mengerjakan semuanya? Berikan satu instruksi i
> 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 <agent>` — 20 adapter terdaftar di [Bekerja dengan setiap agen](#works-with-every-agent). Referensi perintah lengkap ada di [Mulai Cepat](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Tambahkan agen dengan `agentmemory connect <agent>`. Lihat [integrasi yang didukung](#works-with-every-agent) dan [perintah sehari-hari](#everyday-commands).
<details>
<summary><strong>Instalasi global / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx melakukan cache per versi. Paksakan versi terbaru dengan `npx -y @agentmemor
</details>
-<details>
-<summary><strong>Sudah menjalankan iii engine sendiri</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Bekerja dengan setiap agen" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API.
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin native + 7 hook + MCP</sub>
+<sub>plugin native + hook lifecycle + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API.
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin native + MCP</sub>
+<sub>recall native + capture + skill</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API.
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>server MCP</sub>
+<sub>capture native + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API.
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>recall native + capture + skill + MCP opsional</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ agentmemory bekerja dengan agen apa pun yang mendukung hook, MCP, atau REST API.
---
-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.
+<a id="data-storage"></a>
-**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.
+### Penyimpanan data
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Memori disimpan di luar repositori secara default. Instance 0 memakai kembali `./data/state_store.db` yang sudah ada. Pilih lokasi dengan `--data-dir <path>` atau `AGENTMEMORY_DATA_DIR`, lalu gunakan direktori yang sama saat restart dan upgrade.
-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 <path>` atau set `AGENTMEMORY_DATA_DIR`; kedua setelan eksplisit ini diprioritaskan di atas penemuan lokasi lama:
+| Platform | Direktori data |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` memakai subdirektori `instance-1`, port API `3211`, dan viewer `3213`. Lihat [penyimpanan dan cadangan](../docs/reliability/state-storage.md) untuk Redis dan migrasi backend.
Catatan rilis terbaru: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +473,7 @@ Top-5 hit rate 100% pada **batas matematis P@5** untuk korpus ini (0.240, lihat
</tr>
<tr>
<td><strong>Dependensi eksternal</strong></td>
-<td>Tidak ada (SQLite + iii-engine)</td>
+<td>Tidak memerlukan layanan database terpisah</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>Multipel</td>
@@ -550,14 +547,12 @@ Top-5 hit rate 100% pada **batas matematis P@5** untuk korpus ini (0.240, lihat
| 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.
+AgentMemory memadukan capture sesi, riwayat proyek yang bisa dicari, dan viewer lokal, dengan mode tanpa kunci sejak awal.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Mulai Cepat" height="32" /></picture></h2>
-Kompatibilitas: rilis ini menyasar `iii-sdk` 0.22.1 dan mem-pin iii-engine v0.22.1.
-
### Coba dalam 30 detik
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Buka `http://localhost:3113` untuk menyaksikan memori terbangun secara live.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Validasi instalasi baru dan persistensi setelah restart
-Dengan server berjalan, validasi REST, health, viewer, dan status runtime yang didukung iii:
+Dengan server berjalan, periksa kesehatan, viewer, dan statusnya.
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` menampilkan kesehatan server, penyedia, mode embedding, pengiriman capture, dan pemulihan. Permintaan REST yang dilindungi memerlukan rahasia server. Gunakan `AGENTMEMORY_SECRET` yang dikonfigurasi atau baca rahasia lokal yang dibuat otomatis jika tidak disetel.
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Perintah sehari-hari
Instalasi dan setup ada di [Instalasi](#install) di atas (jalankan pertama akan menuntun Anda melaluinya). Sehari-hari:
@@ -604,7 +608,10 @@ Instalasi dan setup ada di [Instalasi](#install) di atas (jalankan pertama akan
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Sesi impor muncul bersama sesi native di Replay, diindeks untuk pencarian, dan ditandai dengan kanal asal `import`. Pemrosesan sesi juga dapat menghasilkan kristal dan pelajaran.
> **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.
@@ -635,14 +642,12 @@ Gunakan perintah pemeliharaan saat Anda sengaja ingin memperbarui runtime lokal
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`).
+Perintah ini memperbarui runtime lokal dan dapat memperbarui dependensi JavaScript dalam direktori kerja. Cadangkan data dan baca [panduan upgrade](../docs/upgrades/iii-0.25.md) sebelum memperbarui instalasi yang ada.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code tanpa instalasi plugin (jalur MCP-standalone)
@@ -703,6 +708,26 @@ 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.
+### Cursor
+
+Atur MCP dengan `agentmemory connect cursor`. Di **Settings → Plugins → Add marketplace**, pilih checkout yang berisi `.cursor-plugin/plugin.json`, aktifkan agentmemory, lalu muat ulang. Plugin menyediakan capture lifecycle, atribusi workspace, skill, dan MCP. Aktifkan hanya hook plugin atau hook manual di `~/.cursor/hooks.json` agar capture tidak ganda.
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Pilih perintah untuk host Anda. Pi dan OMP memasang recall/capture native, replay offline, dan 17 skill; `--with-mcp` menambahkan semua alat. Jalankan `/reload` di Pi atau restart OMP, lalu periksa `/agentmemory-status`. DSH memasang MCP dan plugin capture bawaan; restart setelah terhubung.
+
+Pi juga mendukung paket `@agentmemory/pi`. Lihat [panduan Pi](../integrations/pi/) untuk instalasi lokal dan ketersediaan npm. Gunakan satu metode instalasi per host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (tempel prompt ini)</b></summary>
@@ -749,6 +774,8 @@ Panduan lengkap: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Agen lainnya
Jalankan server memori: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Ini **melengkapi** `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` menulis konfigurasi server MCP sehingga tool-nya tersedia.
-- `npx skills add rohitg00/agentmemory` memasang skill-nya sehingga agen tahu kapan harus memanggilnya.
+Konektor Hermes, OpenClaw, Pi, dan Oh My Pi memasang integrasi native serta skill secara default; MCP bersifat opt-in lewat `--with-mcp`. Untuk host lain, pasang skill dengan `npx skills add rohitg00/agentmemory`.
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.
@@ -790,7 +816,7 @@ Entri agentmemory adalah **blok server MCP yang sama** di setiap host yang memak
| 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. |
+| **Cursor (plugin lengkap)** | `.cursor-plugin/` | Cursor Marketplace atau Settings → Plugins → checkout lokal. Mendaftarkan hook lifecycle lewat adapter tipis yang memanggil `plugin/scripts/*.mjs` bersama, serta skill dan MCP. Adapter menentukan workspace yang tidak selalu dilaporkan Cursor dengan benar. Lihat [Cursor](#cursor). Bekerja di Cursor IDE dan CLI `cursor-agent`. |
| **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. |
@@ -804,7 +830,8 @@ Entri agentmemory adalah **blok server MCP yang sama** di setiap host yang memak
| **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). |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · recall native + capture + skill. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · recall native + capture + skill. [Oh My Pi](../integrations/omp/) |
| **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). |
@@ -812,39 +839,19 @@ Entri agentmemory adalah **blok server MCP yang sama** di setiap host yang memak
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (disarankan) atau `config.json` (legacy) | `agentmemory connect continue` membuat `config.yaml` jika belum ada konfigurasi atau memperbarui `config.json` yang ada. YAML yang sudah ada dipertahankan agar komentar dan anchor tetap utuh; perintah mencetak blok untuk ditempel di bawah `mcpServers:`. Continue memakai bentuk array 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 `<repo>/.factory/mcp.json`. Tambahkan `--with-hooks` untuk auto-capture native. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` mengaktifkan alat MCP. Tambahkan `--with-hooks` untuk memuat plugin perekaman native yang disertakan dalam AgentMemory. Tidak perlu paket plugin terpisah. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **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)
+### Akses programatik
-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.
+Gunakan [REST API](#api) dari bahasa apa pun atau [alat MCP](#mcp-server) dari agen. REST memakai JSON dan autentikasi Bearer; lihat [contoh simpan dan cari](#validate-a-fresh-install-and-restart-persistence). Integrasi langsung dengan runtime tersedia dalam [contoh Python](../examples/python/).
### Dari source
@@ -853,92 +860,33 @@ 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=<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).
+`npm start` menjalankan server lokal yang sama dengan CLI terpasang. Persyaratan ada di [Instalasi](#install); API dan viewer memakai `127.0.0.1`.
### 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.
+agentmemory berjalan di Windows 10/11. WSL2 mengikuti jalur Linux dan dapat memasang engine yang dipatok secara otomatis. Pada Windows native, pasang biner iii-engine v0.25.0 yang dipatok secara manual: unduh arsip yang sesuai dari [halaman rilis iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verifikasi checksum, lalu letakkan `iii.exe` di `PATH` (misalnya `%USERPROFILE%\.local\bin\iii.exe`). CLI tidak mengekstrak ZIP Windows secara otomatis.
-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.
+Wiring MCP otomatis di Windows native hanya mendukung `agentmemory connect copilot-cli`. Untuk agen Windows native lainnya, gunakan blok MCP manual dari [Agen lainnya](#other-agents). Jalankan `connect` di WSL hanya jika agen target juga dipasang di lingkungan WSL yang sama.
-**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:
+**MCP mandiri saja (tanpa engine).** Jika hanya memerlukan tool MCP dan tidak memerlukan REST API, viewer, atau layanan runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Jalankan `agentmemory doctor` atau restart dengan `--verbose`. Jika port default terpakai, gunakan `--port <N>` atau `--instance <N>`. Lihat [panduan upgrade](../docs/upgrades/iii-0.25.md) untuk kompatibilitas dan pemulihan.
---
<h2 id="deploy">Deploy</h2>
-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.
+Host sendiri dengan Docker Compose atau templat platform di bawah. Memori dan kredensial tersimpan pada volume `/data`. Cadangkan dan gunakan kembali volume tersebut saat upgrade. Lihat [panduan deployment](../deploy/README.md) untuk autentikasi, jaringan, dan migrasi.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy ke fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy ke Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy ke fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy ke Railway" /></a>
</p>
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.
@@ -956,28 +904,26 @@ batas bawah biaya) ada di [`deploy/`](.././deploy/README.md):
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.
+REST memakai port `3111`; viewer memakai `3113`. Pertahankan akses privat atau lindungi dengan autentikasi dan TLS. Pengaturan akses tiap platform dan [migrasi Docker lama](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ada di panduan deployment.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Mengapa agentmemory" height="32" /></picture></h2>
-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.
+Pengetahuan proyek sering tersebar di percakapan dan file instruksi. AgentMemory membuat keputusan, perbaikan, dan pelajaran terdahulu bisa dicari dari agen yang sedang Anda gunakan.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs memori bawaan agen
@@ -986,7 +932,7 @@ Setiap agen coding AI dilengkapi memori bawaan: Claude Code punya `MEMORY.md`, C
| | Bawaan (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skala | Batas 200 baris | Tak terbatas |
+| Pemeliharaan | Instruksi yang dikelola manual | Riwayat sesi dan memori terindeks |
| 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) |
@@ -1012,13 +958,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Konsolidasi Memori 4-Tier
@@ -1036,6 +982,8 @@ Memori meluruh (decay) dari waktu ke waktu (kurva Ebbinghaus). Memori yang serin
### Apa yang Ditangkap
+Tabel berikut menjelaskan hook Claude Code. Integrasi lain merekam event yang disediakan host masing-masing. Injeksi konteks otomatis melalui hook bersama bersifat opt-in dengan `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Menangkap |
|------|----------|
| `SessionStart` | Path proyek, ID sesi |
@@ -1052,7 +1000,7 @@ Memori meluruh (decay) dari waktu ke waktu (kurva Ebbinghaus). Memori yang serin
| Kemampuan | Deskripsi |
|---|---|
-| **Capture otomatis** | Setiap pemakaian tool direkam lewat hook, tanpa effort manual |
+| **Capture otomatis** | Event sesi dan alat yang didukung direkam oleh integrasi native |
| **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 |
@@ -1253,7 +1201,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Viewer Real-Time" height="32" /></picture></h2>
-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.
+Viewer otomatis mulai pada port `3113`. Saat tersambung, viewer memuat satu snapshot (`GET /agentmemory/viewer/snapshot`), lalu menerapkan event langsung melalui SSE pada `/agentmemory/viewer/events` di worker REST: memori, lesson, observasi, entri audit, perubahan graph, dan pembaruan health tampil tanpa polling atau memuat ulang halaman.
- **12 tab dalam empat grup** dengan hitungan live, deep link (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1270,186 +1218,6 @@ Server viewer terbind ke `127.0.0.1` secara default dan melampirkan secret serve
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Halaman Workers di iii console: worker yang terhubung termasuk instance agentmemory dengan hitungan fungsi live dan metadata runtime" width="720" />
- <br/>
- <em>Halaman Workers: setiap worker yang terhubung, termasuk agentmemory sendiri, dengan PID, jumlah fungsi, runtime, dan last-seen.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Tampilan waterfall trace iii console menunjukkan durasi per-span" width="720" />
- <br/>
- <em>Traces: breakdown waterfall / flame / service untuk setiap operasi memori.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Didukung oleh iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 file sumber · ~55,000 LOC · 3,800+ pengujian · 324 fungsi · 67 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfigurasi" height="32" /></picture></h2>
### Penyedia LLM
@@ -1467,6 +1235,8 @@ agentmemory mendeteksi otomatis penyedia dari environment Anda. Penyedia membuat
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1286,9 @@ Embedding lokal dikirim sebagai dependensi opsional tapi tidak aktif secara defa
### 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.
+Mulai tanpa kunci untuk capture dan pencarian kata kunci. `EMBEDDING_PROVIDER=local` menyediakan pencarian semantik di perangkat setelah unduhan model pertama. Kompresi LLM memerlukan penyedia dan `AGENTMEMORY_AUTO_COMPRESS=true`, dan dapat membuat permintaan untuk setiap observasi; periksa harga penyedia saat ini.
-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/).
+`agentmemory status` / http://localhost:3113
### Memori multi-agen (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,37 +1318,22 @@ Saat `AGENT_ID` tidak diset, memori tetap unscoped (perilaku legacy, tanpa tag,
### 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 <N>` 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.
+API dan viewer memakai loopback secara default.
-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.
+| Port | API / Viewer | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | Viewer | `III_VIEWER_PORT` |
-Pembersihan proses basi saat port tetap terbind setelah run yang crash:
+`--port <N>` menentukan port API; viewer memakai `N+2` secara default. Gunakan `--instance N` untuk instance terpisah. Listener internal harus tetap privat. Ikuti panduan deployment untuk akses jarak jauh dan [migrasi Docker lama](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Backend penyimpanan: file (default) vs Redis
-`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.
+Tidak memerlukan layanan database terpisah. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. Mengganti backend tidak menyalin memori yang sudah ada secara otomatis. [Penyimpanan data](../docs/reliability/state-storage.md).
### 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.
+Letakkan konfigurasi runtime agentmemory di `~/.agentmemory/.env`, alih-alih mengekspor variabel di setiap shell. Jika viewer menampilkan petunjuk seperti `export ANTHROPIC_API_KEY=...`, salin ke file tanpa awalan `export`, lalu restart agentmemory. Set `AGENTMEMORY_ENV_FILE` untuk menggunakan path file env lain.
Variabel environment proses tetap berfungsi dan diprioritaskan di atas nilai di file itu.
@@ -1622,176 +1362,31 @@ GRAPH_EXTRACTION_ENABLED=true
### Variabel Environment
-Buat `~/.agentmemory/.env`:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Referensi lengkap ada di [`.env.example`](../.env.example), termasuk penyedia, filter capture, retensi, penyimpanan, dan lingkup tim. `AGENTMEMORY_ENV_FILE` memilih file lain. Restart setelah mengubah konfigurasi. Jangan commit `.env` yang berisi nilai nyata atau rahasia Bearer.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoint di port `3111`. REST API terbind ke `127.0.0.1` secara default. Endpoint yang terlindungi membutuhkan `Authorization: Bearer <secret>`, dan endpoint mesh sync membutuhkan `AGENTMEMORY_SECRET` yang diset secara eksplisit di kedua peer.
+146 endpoint di port `3111`. REST API terbind ke `127.0.0.1` secara default. Endpoint yang terlindungi membutuhkan `Authorization: Bearer <secret>`, 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:
+Autentikasi aktif secara default. Jika `AGENTMEMORY_SECRET` tidak disetel, CLI membuat rahasia acak saat pertama dijalankan di `~/.agentmemory/secret` dan menyalinnya ke `secret` dalam direktori data terpilih, dengan mode `0600`. Klien bawaan mengutamakan file kanonis ini untuk koneksi lokal dan hanya mengirim rahasia tersimpan ke URL loopback. `AGENTMEMORY_SECRET` eksplisit selalu diutamakan; klien remote harus mengaturnya melalui environment. Deployment Docker membuat rahasianya sendiri.
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
@@ -1830,7 +1425,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Bagikan ke tim |
| `GET` | `/agentmemory/audit` | Audit trail |
-Daftar endpoint lengkap: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Daftar endpoint lengkap: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1443,19 @@ Event yang gagal di-retry setiap `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 d)
Saat server mati, tidak menjawab tepat waktu, atau mengembalikan 5xx, hook menambahkan observasi itu ke file spool lokal, `<data dir>/capture-spool/<host>-<port>.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.
+**Memadatkan provenance graph.** Pemadatan provenance lama ditunda saat startup karena membaca seluruh scope lama. `/agentmemory/status` melaporkan `deferred`, atau `off` dengan `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Jalankan pemadatan manual di bawah saat pemeliharaan. Migrasi indeks pencarian terpisah: gunakan `agentmemory graph-index migrate --allow-legacy-scan` sesuai [panduan pemeliharaan](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1469,7 @@ npm test # 4,000+ 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.
+Lihat [Instalasi](#install) untuk persyaratan serta [CONTRIBUTING.md](../CONTRIBUTING.md) untuk aturan kontribusi dan pemeriksaan rilis.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Lisensi" height="32" /></picture></h2>
diff --git a/READMEs/README.it-IT.md b/READMEs/README.it-IT.md
index 799fd216..56f218d1 100644
--- a/READMEs/README.it-IT.md
+++ b/READMEs/README.it-IT.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Il tuo agente di coding si ricorda tutto. Basta ri-spiegare tutto da capo.
- Costruito su <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Memoria persistente tra sessioni e agenti di programmazione.
</strong><br/>
- Memoria persistente per Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode e qualsiasi client MCP.
+ Memoria persistente per Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode e qualsiasi client MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Come funziona</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Basato su iii</a> &bull;
<a href="#configuration">Configurazione</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory acquisisce le sessioni di programmazione e rende ricercabili decisioni, soluzioni e lezioni apprese. Condividi un unico archivio tra agenti, controlla ciò che viene salvato e scegli quanto contesto riceve il modello.
+
+<a id="install"></a>
+
## 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.
+- Su macOS/Linux, la configurazione automatica richiede anche `curl`, una shell POSIX `sh` e `tar`.
+- Su Windows usa WSL2 oppure segui la [configurazione nativa](#windows).
Comando canonico per l'installazione da zero:
@@ -108,11 +111,11 @@ Comando canonico per l'installazione da zero:
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`.
+Scegli gli agenti e un provider, oppure la modalità senza chiave. La configurazione guidata scrive le impostazioni, avvia il server di memoria e propone l'installazione globale del comando `agentmemory`. `-y` accetta la richiesta di npm; `@latest` seleziona la versione corrente. La compressione tramite LLM è facoltativa e richiede un provider e `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 <path>` 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.
+L'API è su `http://localhost:3111` e il visualizzatore su `http://localhost:3113`. Entrambi ascoltano su loopback per impostazione predefinita. La configurazione è in `~/.agentmemory/.env`; consulta [archiviazione dei dati](#data-storage) per percorsi e istanze separate.
Poi verifica che il recall funzioni e dai al tuo agente le sue skill:
@@ -127,14 +130,7 @@ 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 <agent>` — 20 adapter elencati in [Funziona con qualsiasi agente](#works-with-every-agent). Riferimento completo dei comandi in [Avvio rapido](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Collega un altro agente con `agentmemory connect <agent>`. Consulta le [integrazioni](#works-with-every-agent) e i [comandi quotidiani](#everyday-commands).
<details>
<summary><strong>Installazione globale / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx mette in cache per versione. Forza l'ultima versione con `npx -y @agentmemor
</details>
-<details>
-<summary><strong>Hai già un tuo iii engine in esecuzione</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funziona con qualsiasi agente" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory funziona con qualsiasi agente che supporti hook, MCP o API REST. Tut
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin nativo + 7 hook + MCP</sub>
+<sub>plugin nativo + hook del ciclo di vita + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory funziona con qualsiasi agente che supporti hook, MCP o API REST. Tut
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin nativo + MCP</sub>
+<sub>ricerca nativa + acquisizione + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory funziona con qualsiasi agente che supporti hook, MCP o API REST. Tut
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>server MCP</sub>
+<sub>acquisizione nativa + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory funziona con qualsiasi agente che supporti hook, MCP o API REST. Tut
<sub>API REST</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>ricerca nativa + acquisizione + skills + MCP facoltativo</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +306,25 @@ agentmemory funziona con qualsiasi agente che supporti hook, MCP o API REST. Tut
---
-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.
+<a id="data-storage"></a>
-**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.
+### Archiviazione dei dati
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Per impostazione predefinita, i ricordi restano fuori dal repository:
-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 <path>` oppure imposta `AGENTMEMORY_DATA_DIR`; entrambe le impostazioni esplicite hanno la precedenza sulla ricerca legacy:
+| Piattaforma | Directory dei dati |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+L'istanza 0 riutilizza un `./data/state_store.db` esistente. Scegli un altro percorso con `--data-dir <path>` o `AGENTMEMORY_DATA_DIR` e mantienilo durante riavvii e aggiornamenti. `--instance 1` usa la sottocartella `instance-1`, la porta API `3211` e il visualizzatore `3213`. La [guida ad archiviazione e backup](../docs/reliability/state-storage.md) descrive Redis e migrazioni.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +473,7 @@ Tasso di successo top-5 del 100% al **limite matematico di P@5** per questo corp
</tr>
<tr>
<td><strong>Dipendenze esterne</strong></td>
-<td>Nessuna (SQLite + iii-engine)</td>
+<td>Nessun servizio database separato richiesto</td>
<td>Qdrant / pgvector</td>
<td>Postgres + DB vettoriale</td>
<td>Multiple</td>
@@ -550,14 +547,12 @@ Tasso di successo top-5 del 100% al **limite matematico di P@5** per questo corp
| 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.
+AgentMemory combina acquisizione dagli agenti di programmazione, cronologia del progetto ricercabile e visualizzatore locale. La modalità senza chiave è disponibile dal primo avvio.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Avvio rapido" height="32" /></picture></h2>
-Compatibilità: questa release ha come target `iii-sdk` 0.22.1 e fissa iii-engine alla v0.22.1.
-
### Provalo in 30 secondi
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Apri `http://localhost:3113` per osservare la memoria costruirsi in tempo reale.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Con il server avviato, verifica salute, visualizzatore e stato:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` mostra lo stato del server, i provider e gli embedding attivi. Salva un ricordo di prova e verifica la ricerca:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Comandi quotidiani
Installazione e configurazione sono descritte in [Installazione](#install) sopra (la prima esecuzione ti guida passo passo). Quotidianamente:
@@ -623,7 +627,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Le sessioni importate appaiono nel selettore Replay insieme a quelle native. 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.
@@ -635,14 +639,12 @@ Usa il comando di manutenzione quando vuoi intenzionalmente aggiornare il tuo ru
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`).
+Il comando aggiorna l'ambiente locale e può aggiornare le dipendenze JavaScript del workspace corrente. Esegui un backup e leggi la [guida all'aggiornamento](../docs/upgrades/iii-0.25.md) prima di procedere.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code senza l'installazione del plugin (percorso MCP standalone)
@@ -703,6 +705,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Aggiungi poi il plugin nativo da un checkout di AgentMemory tramite **Settings → Plugins → Add marketplace** e ricarica la finestra. Il plugin offre acquisizione del ciclo di vita, attribuzione al progetto, skills e MCP. Abilita i suoi hook oppure quelli manuali in `~/.cursor/hooks.json` per evitare acquisizioni duplicate. [Guida Cursor](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Scegli il comando per il tuo host. Pi e OMP installano ricerca, acquisizione, reinvio offline e 17 skills; `--with-mcp` aggiunge tutti gli strumenti. Esegui `/reload` in Pi oppure riavvia OMP, poi controlla `/agentmemory-status`. DSH installa MCP e il plugin di acquisizione incluso; riavvia DSH dopo la connessione.
+
+Pi supporta anche il pacchetto installabile `@agentmemory/pi`. La [guida Pi](../integrations/pi/) descrive installazione locale e disponibilità su npm. Usa un solo metodo d'installazione per host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (incolla questo prompt)</b></summary>
@@ -749,6 +773,8 @@ Guida completa: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Altri agenti
Avvia il server di memoria: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +791,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Questo è **complementare** a `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` normalmente scrive la configurazione MCP. Hermes, OpenClaw, Pi e Oh My Pi installano per impostazione predefinita la propria integrazione nativa e le skills incluse; MCP è facoltativo con `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` installa le skills per gli agenti che non le includono nativamente. Salta questo passaggio per Hermes, OpenClaw, Pi e Oh My Pi: i rispettivi connettori le installano già.
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.
@@ -790,7 +816,7 @@ La voce agentmemory è lo **stesso blocco server MCP** su ogni host che usa la f
| 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. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Aggiungi poi il plugin nativo da un checkout di AgentMemory tramite **Settings → Plugins → Add marketplace** e ricarica la finestra. Il plugin offre acquisizione del ciclo di vita, attribuzione al progetto, skills e MCP. Abilita i suoi hook oppure quelli manuali in `~/.cursor/hooks.json` per evitare acquisizioni duplicate. [Guida Cursor](../integrations/cursor/). |
| **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. |
@@ -804,7 +830,7 @@ La voce agentmemory è lo **stesso blocco server MCP** su ogni host che usa la f
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | ricerca nativa + acquisizione + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +838,19 @@ La voce agentmemory è lo **stesso blocco server MCP** su ogni host che usa la f
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferito) o `config.json` (legacy) | `agentmemory connect continue` crea `config.yaml` se manca o modifica il `config.json` esistente. Se il file YAML esiste, mostra il blocco da aggiungere a `mcpServers:` per conservare commenti e ancore. Continue usa un array, non un oggetto. |
| **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 `<repo>/.factory/mcp.json`. Passa `--with-hooks` per l'acquisizione automatica nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` abilita gli strumenti MCP. Aggiungi `--with-hooks` per caricare il plugin nativo di acquisizione incluso in AgentMemory. Non serve un pacchetto aggiuntivo. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/d | Usa gli [esempi REST autenticati](#validate-a-fresh-install-and-restart-persistence) per salvare e cercare ricordi dagli script. |
| **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.
+Usa l'[API REST](#api) da qualsiasi linguaggio o gli [strumenti MCP](#mcp-server) da un agente. REST usa JSON e autenticazione bearer; consulta l'[esempio di salvataggio e ricerca](#validate-a-fresh-install-and-restart-persistence). Gli [esempi Python](../examples/python/) coprono l'integrazione diretta con il runtime.
### Dal codice sorgente
@@ -853,91 +859,33 @@ 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=<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).
+`npm start` avvia lo stesso server locale della CLI installata. I prerequisiti sono in [Install](#install); API e visualizzatore ascoltano su `127.0.0.1`.
### 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**
+agentmemory funziona su Windows 10/11. WSL2 segue il percorso Linux e può installare automaticamente l'engine fissato. Su Windows nativo, installare manualmente il binario iii-engine v0.25.0 fissato: scaricare l'archivio corrispondente dalla [pagina della release iii 0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verificarne il checksum e mettere `iii.exe` nel `PATH` (ad esempio `%USERPROFILE%\.local\bin\iii.exe`). La CLI non estrae automaticamente lo ZIP Windows.
-```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
-```
+La configurazione MCP automatica su Windows nativo supporta solo `agentmemory connect copilot-cli`. Per gli altri agenti Windows nativi, usare il blocco MCP manuale da [Altri agenti](#other-agents). Eseguire `connect` in WSL solo se l'agente di destinazione è installato nello stesso ambiente WSL.
-**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:
+**Solo MCP autonomo (senza engine).** Se servono soltanto gli strumenti MCP, senza API REST, visualizzatore o servizi runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Esegui `agentmemory doctor` o riavvia con `--verbose`. Usa `--port <N>` o `--instance <N>` se le porte sono occupate. Compatibilità e ripristino sono nella [guida all'aggiornamento](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Deploy</h2>
-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.
+Ospita il servizio con Docker Compose o i modelli seguenti. Memoria e credenziali risiedono nel volume `/data`. Esegui il backup e riutilizza il volume durante gli aggiornamenti. La [guida al deployment](../deploy/README.md) copre autenticazione, rete, backup e migrazione.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
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.
@@ -955,28 +903,26 @@ costi minimi) si trovano in [`deploy/`](.././deploy/README.md):
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.
+REST usa la porta `3111`; il visualizzatore usa `3113`. Mantienili privati o proteggili con autenticazione e TLS. Consulta la guida al deployment per l'esposizione in rete e la [migrazione delle vecchie installazioni Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Perché agentmemory" height="32" /></picture></h2>
-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.
+Le conoscenze del progetto si disperdono tra chat e file di istruzioni. AgentMemory rende ricercabili decisioni, soluzioni e lezioni apprese dall’agente che stai usando.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs la memoria integrata degli agenti
@@ -985,7 +931,7 @@ Ogni agente di coding AI ha una memoria integrata: Claude Code ha `MEMORY.md`, C
| | Integrata (CLAUDE.md) | agentmemory |
|---|---|---|
-| Scala | Limite di 200 righe | Illimitata |
+| Manutenzione | Istruzioni curate manualmente | Cronologia delle sessioni e ricordi indicizzati |
| 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) |
@@ -1011,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Consolidamento della memoria a 4 livelli
@@ -1035,6 +981,8 @@ Le memorie decadono nel tempo (curva di Ebbinghaus). Le memorie accedute frequen
### Cosa viene catturato
+Questa tabella descrive gli hook di Claude Code. Le altre integrazioni acquisiscono gli eventi forniti dal proprio host; consulta le relative guide. L'iniezione automatica del contesto tramite gli hook condivisi richiede `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Catture |
|------|----------|
| `SessionStart` | Percorso del progetto, ID sessione |
@@ -1051,7 +999,7 @@ Le memorie decadono nel tempo (curva di Ebbinghaus). Le memorie accedute frequen
| Capacità | Descrizione |
|---|---|
-| **Acquisizione automatica** | Ogni uso di strumento registrato tramite hook, nessuno sforzo manuale |
+| **Acquisizione automatica** | Le integrazioni native registrano gli eventi di sessione e degli strumenti supportati |
| **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 |
@@ -1252,7 +1200,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Viewer in tempo reale" height="32" /></picture></h2>
-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.
+Il visualizzatore si avvia automaticamente sulla porta `3113`. Al collegamento carica uno snapshot (`GET /agentmemory/viewer/snapshot`), poi applica gli eventi live tramite SSE su `/agentmemory/viewer/events` nel worker REST: memorie, lezioni, osservazioni, voci di audit, modifiche al grafo e aggiornamenti health compaiono senza polling o ricaricamenti della pagina.
- **12 tab in quattro gruppi** con conteggi dal vivo, deep link (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1269,187 +1217,6 @@ Il server del viewer si collega a `127.0.0.1` per impostazione predefinita e agg
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Pagina Workers della iii console: worker connessi incluse le istanze agentmemory con conteggi delle funzioni dal vivo e metadati del runtime" width="720" />
- <br/>
- <em>Pagina Workers: ogni worker connesso, incluso agentmemory stesso, con PID, conteggio delle funzioni, runtime e ultimo avvistamento.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Vista waterfall delle tracce della iii console che mostra la durata per span" width="720" />
- <br/>
- <em>Traces: vista waterfall / flame / scomposizione per servizio per ogni operazione di memoria.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Basato su iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 file sorgente · ~55,000 righe di codice · 3,400+ test · 324 funzioni · 67 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configurazione" height="32" /></picture></h2>
### Provider LLM
@@ -1467,6 +1234,8 @@ agentmemory rileva automaticamente i provider dal tuo ambiente. Un provider rend
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1285,7 @@ Gli embedding locali sono distribuiti come dipendenza opzionale ma non sono abil
### 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/).
+Inizia senza chiave per acquisizione e ricerca per parole chiave. `EMBEDDING_PROVIDER=local` attiva la ricerca semantica locale dopo il primo download del modello. La compressione LLM richiede un provider e `AGENTMEMORY_AUTO_COMPRESS=true`; può inviare una richiesta per ogni osservazione. Controlla i prezzi attuali del provider prima di attivarla. Visualizzatore e `agentmemory status` mostrano i provider attivi.
### Memoria multi-agente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1315,22 @@ Quando `AGENT_ID` non è impostato, la memoria resta senza ambito (comportamento
### 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 <N>` 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.
+| Porta | Uso | Configurazione |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Pulizia dei processi bloccati quando le porte restano occupate dopo un'esecuzione andata in crash:
+`--port <N>` imposta la porta API e, per impostazione predefinita, il visualizzatore su `N+2`. Usa `--instance N` per un'istanza separata. Le porte interne devono restare private; consulta la [guida al deployment](../deploy/README.md) prima di abilitare l'accesso remoto.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Backend di archiviazione: file (predefinito) o Redis
-`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.
+L'archivio su file predefinito non richiede un servizio database separato. Redis è facoltativo con `AGENTMEMORY_STATE_BACKEND=redis` e `AGENTMEMORY_REDIS_URL`. Cambiare backend non copia i ricordi. La [guida ad archiviazione e backup](../docs/reliability/state-storage.md) descrive persistenza, limiti di Redis ed esportazione/importazione autenticata.
### 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.
+Inserire la configurazione runtime di agentmemory in `~/.agentmemory/.env` invece di esportare variabili in ogni shell. Se il visualizzatore mostra un suggerimento come `export ANTHROPIC_API_KEY=...`, copiarlo nel file senza il prefisso `export`, quindi riavviare agentmemory. Impostare `AGENTMEMORY_ENV_FILE` per usare un altro percorso del file env.
-Le variabili d'ambiente del processo funzionano comunque e hanno la precedenza sui valori nel file.
+Le variabili d'ambiente del processo hanno precedenza sul file. Riavvia il server dopo aver modificato la configurazione.
Su Windows, lo stesso file risiede in `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,176 +1357,29 @@ GRAPH_EXTRACTION_ENABLED=true
### Variabili d'ambiente
-Crea `~/.agentmemory/.env`:
+Opzioni comuni per `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+La documentazione completa è in [`.env.example`](../.env.example): credenziali, filtri, conservazione, archiviazione, ambito del team e opzioni. `AGENTMEMORY_ENV_FILE` seleziona un altro file. Non includere in git un `.env` compilato o un segreto bearer.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoint sulla porta `3111`. L'API REST si collega a `127.0.0.1` per impostazione predefinita. Gli endpoint protetti richiedono `Authorization: Bearer <secret>`, e gli endpoint di sincronizzazione mesh richiedono un `AGENTMEMORY_SECRET` impostato esplicitamente su entrambi i peer.
+146 endpoint sulla porta `3111`. L'API REST si collega a `127.0.0.1` per impostazione predefinita. Gli endpoint protetti richiedono `Authorization: Bearer <secret>`, 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:
+**L'autenticazione è attiva per default.** Se `AGENTMEMORY_SECRET` non è impostato nella shell o in `~/.agentmemory/.env`, al primo avvio la CLI genera un segreto casuale in `~/.agentmemory/secret` e ne conserva una copia chiamata `secret` nella directory dati selezionata, con permessi `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
@@ -1830,7 +1418,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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)
+Elenco completo degli endpoint: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1436,19 @@ Gli eventi falliti vengono ritentati ogni `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS
Quando il server è spento, non risponde in tempo o restituisce un 5xx, l'hook aggiunge l'osservazione a un file di spool locale, `<data dir>/capture-spool/<host>-<port>.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.
+**Compattazione della provenienza del grafo.** La compattazione dei dati di provenienza precedenti viene rinviata all’avvio perché legge interi scope precedenti. `/agentmemory/status` riporta `deferred`, oppure `off` con `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Esegui la compattazione manuale seguente durante la manutenzione. La migrazione dell’indice di ricerca è separata: usa `agentmemory graph-index migrate --allow-legacy-scan` come descritto nella [guida alla manutenzione](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1462,7 @@ npm test # 4,000+ 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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licenza" height="32" /></picture></h2>
diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md
index 364e9471..8efadf42 100644
--- a/READMEs/README.ja-JP.md
+++ b/READMEs/README.ja-JP.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- コーディングエージェントがすべてを記憶します。もう説明し直す必要はありません。
- <a href="https://github.com/iii-hq/iii">iii engine</a> を基盤に構築
+ セッションとエージェントをまたいで使える永続メモリ。
</strong><br/>
- Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode、そしてあらゆる MCP クライアントのための永続メモリ。
+ Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、Oh My Pi、DeepSeek Harness、OpenCode、そしてあらゆる MCP クライアントのための永続メモリ。
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="ライセンス" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="スター数" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">仕組み</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">ビューワー</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">設定</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory はコーディングセッションを記録し、過去の判断や修正を検索できる形で保存します。複数のツールから同じメモリを使い、保存内容を確認し、モデルに渡すコンテキストの量を選べます。
+
+<a id="install"></a>
+
## インストール
必要環境:
- 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 も、他にサポートされている方法です。
+- macOS/Linux の自動セットアップには `curl`、POSIX `sh`、`tar` が必要です。
+- Windows / WSL2: [Windows](#windows).
標準的な新規インストールコマンド:
@@ -108,11 +111,11 @@
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` も設定した場合に限られます。
+エージェントとプロバイダー、またはキーレスモードを選びます。セットアップは設定を保存してメモリサーバーを起動し、グローバルインストールを案内します。`-y` は npm の確認を承諾し、`@latest` は最新リリースを選びます。LLM による圧縮にはプロバイダーと `AGENTMEMORY_AUTO_COMPRESS=true` の両方が必要です。
キーレスモードではベクトル埋め込みが無効になります。`memory_recall`(`mem::search` パス)は BM25 を使い、`memory_smart_search` はグラフデータが既に存在する場合は構造的なグラフマッチも融合できます。無料でオンデバイスのセマンティックリコールを使うには、`~/.agentmemory/.env` に `EMBEDDING_PROVIDER=local` を設定して再起動してください。最初の埋め込みリクエストで `Xenova/all-MiniLM-L6-v2` がダウンロードされ、その後の推論はローカルで実行されます。
-ローカルランタイムは 4 つのポートを使います: REST/MCP HTTP 用の `3111`、iii ストリーム用の `3112`、ビューワー用の `3113`、iii worker の WebSocket 用の `49134` です。永続的な iii の状態は、macOS では `~/Library/Application Support/agentmemory`、Linux では `$XDG_DATA_HOME/agentmemory` または `~/.local/share/agentmemory`、Windows では `%APPDATA%\agentmemory` に保存されます。これを上書きするには `--data-dir <path>` または `AGENTMEMORY_DATA_DIR` を使い、再起動時には同じ値を使い続けてください。後方互換性のため、既存の `./data/state_store.db` または `./data/iii-config.yaml` があれば、インスタンス 0 についてはプラットフォームのデフォルトより優先されます。明示的なフラグや環境変数での上書きは、それよりもさらに優先されます。
+API は `http://localhost:3111`、ライブビューアーは `http://localhost:3113` です。どちらもデフォルトでループバックにバインドします。設定は `~/.agentmemory/.env` に保存します。 [データの保存](#data-storage).
続いてリコールが動くことを確かめ、エージェントに skills を与えます:
@@ -127,14 +130,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-追加のエージェントはいつでも `agentmemory connect <agent>` で接続できます — 20 のアダプタは[すべてのエージェントで動作](#works-with-every-agent)に一覧があります。コマンドの完全なリファレンスは[クイックスタート](#quick-start)を参照してください。
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-最速の経路は WSL2 です。ネイティブ Windows のエンジンセットアップでは、ピン留めされた v0.22.1 の ZIP をダウンロードし、`iii.exe` を手動で展開する必要があります。CLI はこれを自動展開しません。Docker Desktop もサポートされています。手順は [Windows の注記](#windows)を参照してください。
-
-</details>
+`agentmemory connect <agent>` で追加できます。[対応する統合](#works-with-every-agent)と[日常のコマンド](#everyday-commands)を参照してください。
<details>
<summary><strong>グローバルインストール / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx はバージョン単位でキャッシュします。`npx -y @agentmemory/a
</details>
-<details>
-<summary><strong>自前の iii エンジンを既に動かしている</strong></summary>
-
-agentmemory は iii-engine v0.22.1 にピン留めしており、異なるバージョンにはアタッチしません(worker は別のエンジンのプロトコルを話せません)。他のエンジンを停止してから `npx -y @agentmemory/agentmemory@latest` を実行してください。ピン留めされた v0.22.1 を `~/.agentmemory/bin` にインストールして実行し、あなた自身の `iii` には触れません。
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory は hooks、MCP、REST API をサポートするあらゆるエー
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>ネイティブプラグイン + 7 hooks + MCP</sub>
+<sub>ネイティブプラグイン + ライフサイクル hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory は hooks、MCP、REST API をサポートするあらゆるエー
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>ネイティブプラグイン + MCP</sub>
+<sub>ネイティブ検索 + キャプチャ + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory は hooks、MCP、REST API をサポートするあらゆるエー
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP サーバー</sub>
+<sub>ネイティブキャプチャ + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory は hooks、MCP、REST API をサポートするあらゆるエー
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>ネイティブ検索 + キャプチャ + skills + 任意の MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ agentmemory は hooks、MCP、REST API をサポートするあらゆるエー
---
-同じアーキテクチャを毎セッション説明する。同じバグを何度も発見し直す。同じ好みを何度も教え直す。組み込みメモリ(CLAUDE.md、.cursorrules)は 200 行で上限に達し、すぐに古くなります。agentmemory はこれを解決します。エージェントの行動を静かにキャプチャし、検索可能なメモリへ圧縮し、次のセッション開始時に適切なコンテキストを注入します。コマンド 1 つ。エージェントをまたいで動作します。
+<a id="data-storage"></a>
-**何が変わるか:** セッション 1 で JWT 認証をセットアップする。セッション 2 でレート制限を依頼する。エージェントは既に、あなたの認証が `src/middleware/auth.ts` の jose ミドルウェアを使っていること、テストが `test/auth.test.ts` でトークン検証をカバーしていること、Edge 互換性のために jsonwebtoken ではなく jose を選んだことを知っています。説明し直す必要もコピペする必要もありません。
+### データの保存
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+メモリはデフォルトでリポジトリの外に保存されます。インスタンス 0 は既存の `./data/state_store.db` を再利用します。保存先を変えるには `--data-dir <path>` または `AGENTMEMORY_DATA_DIR` を指定し、再起動やアップグレードでも同じ場所を使ってください。
-デフォルトでは、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 <path>` を渡すか `AGENTMEMORY_DATA_DIR` を設定してください。どちらの明示設定もレガシー検出より優先されます:
+| プラットフォーム | 保存先 |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-ネイティブ起動と Docker 起動は同じ解決済みホストディレクトリを使います。Docker はこれを `/data` にバインドマウントします。`--instance 1` は解決済みディレクトリに `instance-1` を追加し、別のデフォルトポート 4 つ組 `3211/3212/3213/49234` を選びます。
+`--instance 1` は `instance-1` サブディレクトリと API `3211`、ビューアー `3213` を使います。Redis と移行については[ストレージとバックアップ](../docs/reliability/state-storage.md)を参照してください。
最新のリリースノート: [CHANGELOG.md](../CHANGELOG.md)。
@@ -476,7 +473,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>外部依存</strong></td>
-<td>なし(SQLite + iii-engine)</td>
+<td>別のデータベースサービスは不要</td>
<td>Qdrant / pgvector</td>
<td>Postgres + ベクトル DB</td>
<td>複数</td>
@@ -550,14 +547,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | 時系列ナレッジグラフ。公表されている時系列クエリの結果としては最強(LongMemEval 63.8%)だが、グラフ構築が非同期のため新しい事実の反映が遅れることがある |
| Cognee | 30K | ドキュメントからナレッジグラフへの取り込み。Python のみで、セッションキャプチャではなく構造化エンティティ抽出のために作られている |
-これらのいずれも、コーディングエージェントの hooks からの自動キャプチャ、ローカルファーストのビューワー、キーレスでの動作を備えていません — agentmemory はまさにこの組み合わせを核に作られています。
+AgentMemory はセッションのキャプチャ、検索可能なプロジェクト履歴、ローカルビューアーを組み合わせ、初回からキーレスで使えます。
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-互換性: このリリースは `iii-sdk` 0.22.1 をターゲットにし、iii-engine v0.22.1 にピン留めしています。
-
### 30 秒で試す
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
`http://localhost:3113` を開けばメモリがリアルタイムに構築される様子が見られます。
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 新規インストールと再起動時の永続性を検証する
-サーバーを起動したまま、REST、ヘルス、ビューワー、iii ベースのランタイムステータスを検証します:
+サーバーを起動した状態で、ヘルス、ビューアー、ステータスを確認します。
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-起動時の準備状況パネルは 4 つのポートすべてをカバーします: REST/MCP HTTP の 3111、iii ストリームの 3112、ビューワーの 3113、iii worker の WebSocket の 49134。`status` は agentmemory のヘルスと、有効なプロバイダー / 埋め込みモードを確認します。プローブを保存し、検索できることを確認してください:
+`status` はヘルス、プロバイダー、埋め込み、キャプチャ配送、復旧状態を表示します。保護された REST リクエストにはサーバーのシークレットが必要です。明示的な `AGENTMEMORY_SECRET` を使うか、未設定なら生成されたローカルシークレットを読み込みます。
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
続いて `npx -y @agentmemory/agentmemory@latest stop` を実行し、ターミナル 1 で標準コマンドを再度起動し、`/agentmemory/livez` を待ってから検索をやり直してください。プローブはまだ返ってくるはずです。カスタムの `--data-dir` を選んだ場合は、再起動時にも同じディレクトリを渡してください。
+<a id="everyday-commands"></a>
+
### 日常のコマンド
インストールとセットアップは上の[インストール](#install)にあります(初回実行が案内してくれます)。日々の操作:
@@ -604,7 +608,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-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 functions を経由し、サイドチャネルサーバーはありません。インポートされた各トランスクリプトは検索用にインデックス化され、オリジンチャネル `import` が刻印され、セッションクリスタルとレッスンの抽出も行われます。
+インポートしたセッションは Replay に表示され、検索用に索引化されます。由来は `import` として記録され、セッション処理で crystal や lessons が生成される場合があります。
> **`import-jsonl` を主なキャプチャ経路として使う場合の注意:** Claude Code の `cleanupPeriodDays`(`~/.claude/settings.json` 内、デフォルト **30**)は、そのウィンドウより古い JSONL トランスクリプトを `~/.claude/projects/` から自動削除します。数か月分の Claude Code 履歴がある状態で agentmemory を新規インストールすると、30 日より古いものは最初のインポートの前に既に消えています。`import-jsonl` を cron で回すか、`cleanupPeriodDays` をもっと大きな値に上げるか、自動キャプチャ hooks(デフォルトのプラグインインストール経路)を配線して、セッションが生きている間に各ターンが agentmemory に着地するようにしてください。そうすれば JSONL のクリーンアップは問題でなくなります。
@@ -635,14 +642,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-警告: このコマンドは現在のワークスペース/ランタイムを変更します。JavaScript 依存を更新したり、ピン留めされた `iiidev/iii:0.22.1` の Docker イメージを pull したりすることがあります。ピン留めされていない、あるいは新しい iii エンジンをインストールすることは決してありません。
-
-実装の詳細は `src/cli.ts` を参照してください(`src/cli.ts:544-595` 付近の `runUpgrade`)。
+ローカルランタイムを更新し、作業ディレクトリ内の JavaScript 依存関係も更新する場合があります。データをバックアップし、実行前に[アップグレードガイド](../docs/upgrades/iii-0.25.md)を読んでください。
### Claude Code(1 ブロックそのまま貼り付け)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### プラグインをインストールしない Claude Code(MCP スタンドアロン経路)
@@ -703,6 +708,26 @@ 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 体験が欲しい場合は、プラグインも併せてインストールしてください。
+### Cursor
+
+`agentmemory connect cursor` で MCP を設定します。**Settings → Plugins → Add marketplace** から `.cursor-plugin/plugin.json` を含むチェックアウトを選び、agentmemory を有効にして再読み込みしてください。プラグインはライフサイクルのキャプチャ、ワークスペース判定、skills、MCP を提供します。重複を避けるため、プラグインと `~/.cursor/hooks.json` の手動 hooks は片方だけ有効にします。
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+ホストに合うコマンドを選びます。Pi と OMP はネイティブの検索・キャプチャ、オフライン再送、17 skills をインストールし、`--with-mcp` で全ツールを追加します。Pi は `/reload`、OMP は再起動後に `/agentmemory-status` を確認してください。DSH は MCP と同梱のキャプチャプラグインを追加するので、接続後に再起動します。
+
+Pi は `@agentmemory/pi` パッケージとしてもインストールできます。ローカルインストールと npm での提供状況は [Pi ガイド](../integrations/pi/)を参照し、各ホストでは 1 つの方法だけを使ってください。
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw(このプロンプトを貼り付ける)</b></summary>
@@ -749,6 +774,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### その他のエージェント
メモリサーバーを起動: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
これは `agentmemory connect <agent>` を**補完する**ものです:
-- `agentmemory connect <agent>` は MCP サーバー設定を書き込み、ツールを使えるようにします。
-- `npx skills add rohitg00/agentmemory` は skills をインストールし、エージェントがいつそれらを呼ぶべきか分かるようにします。
+Hermes、OpenClaw、Pi、Oh My Pi のコネクターはネイティブ統合と skills を標準でインストールします。MCP は `--with-mcp` で追加します。それ以外のホストでは `npx skills add rohitg00/agentmemory` で skills を追加できます。
skills CLI がまだカバーしていない少数のエージェント(Zed v1.3.x 以前)では、17 個の SKILL.md ファイルをエージェントのネイティブ skill ディレクトリに自分で置いてください。同じフォーマットがどこでも動きます。
@@ -790,7 +816,7 @@ agentmemory のエントリは、`mcpServers` の形式を使うすべてのホ
| エージェント | 設定ファイル | 備考 |
|---|---|---|
| **Cursor(MCP のみ)** | `~/.cursor/mcp.json` | `mcpServers` にマージするか、`agentmemory connect cursor`。ウェブサイトにはワンクリックディープリンクもあります。 |
-| **Cursor(フルプラグイン)** | `.cursor-plugin/` | Cursor Marketplace への掲載(審査中)または Cursor Settings → Plugins → ローカルチェックアウト。7 つの自動キャプチャ hooks(sessionStart、beforeSubmitPrompt、preToolUse、postToolUse、postToolUseFailure、stop、sessionEnd)+ 17 skills + MCP サーバーを登録し、`AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` は Cursor のプラグインダッシュボードで管理されます。Cursor IDE と `cursor-agent` CLI の両方で動作します。CLI の print モードのプロンプトは、セッション終了時にセッショントランスクリプトから補完されます。 |
+| **Cursor(フルプラグイン)** | `.cursor-plugin/` | Cursor Marketplace または Settings → Plugins → ローカルチェックアウト。共通の `plugin/scripts/*.mjs` を呼ぶ薄いアダプター経由でライフサイクル hooks を登録し、skills と MCP も提供します。アダプターは Cursor が正確に報告しないワークスペースを解決します。[Cursor](#cursor) を参照してください。Cursor IDE と `cursor-agent` 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 + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` が MCP エントリをマージします。`--with-hooks` は、Devin の小文字のツールマッチャーを使った 6 つのネイティブ自動キャプチャ hooks(SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd)を追加します。`devin mcp list` と devin 内の `/hooks` で確認してください。 |
@@ -804,7 +830,8 @@ agentmemory のエントリは、`mcpServers` の形式を使うすべてのホ
| **Codex CLI(フルプラグイン)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` のあと `codex plugin add agentmemory@agentmemory`。MCP + 6 つのライフサイクル hooks + 17 skills を登録します。ホストで hooks を信頼し、キャプチャを確認してください。[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 個の自動キャプチャ hooks。プロジェクトの帰属はセッション単位なので、複数のリポジトリにまたがる 1 つの OpenCode プロセスは、各セッションをそれぞれのプロジェクトに記録します。スラッシュコマンドは 2 つ(`/recall`、`/remember`)。`plugin/opencode/` を OpenCode のワークスペースにコピーし、プラグインエントリを `opencode.json` に追加してください。完全な hook 表とギャップ分析は [`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`)。 |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · ネイティブ検索 + キャプチャ + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · ネイティブ検索 + キャプチャ + skills. [Oh My Pi](../integrations/omp/) |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` で、6 hooks のメモリプロバイダー(プリフェッチ、ターンキャプチャ、セッション終了、圧縮前処理、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 IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` が共有のカスタマイズディレクトリに MCP とキャプチャ hooks をインストールします。[Antigravity のセットアップと制限](../docs/plugins/antigravity.md)を参照。 |
@@ -812,39 +839,19 @@ agentmemory のエントリは、`mcpServers` の形式を使うすべてのホ
| **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` に配列形式(オブジェクトではなく)を使います。 |
+| **Continue.dev** | `~/.continue/config.yaml`(推奨)または `config.json`(レガシー) | `agentmemory connect continue` は設定がなければ `config.yaml` を作成し、既存の `config.json` は更新します。既存の YAML はコメントとアンカーを維持するため書き換えず、`mcpServers:` に貼るブロックを表示します。Continue の `mcpServers` は配列です。 |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` は `context_servers`(`mcpServers` ではなく Zed 独自のキー)の下に書き込みます。リモート MCP サーバーは、代わりに `{"url": "..."}` で配線できます。 |
| **Droid(Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` が標準の `mcpServers` ブロックを書き込みます。プロジェクト単位の上書きは `<repo>/.factory/mcp.json` に書いてください。`--with-hooks` を渡すとネイティブ自動キャプチャが使えます。 |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` で MCP ツールを有効にします。`--with-hooks` を追加すると、AgentMemory 同梱のネイティブキャプチャプラグインを読み込みます。別のプラグインパッケージは不要です。 [DSH](../docs/dsh.md). |
| **Goose** | Goose の MCP 設定 UI | 同じ `mcpServers` ブロック。`goose configure` → Add Extension → MCP を使用。`~/.config/goose/config.yaml` の直接編集もサポートされていますが、スキーマは `mcpServers:` + `command` ではなく `extensions:` + `cmd` を使います。 |
-| **Aider** | n/a | REST API に直接話しかけます: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **任意のエージェント(32+)** | n/a | `npx skillkit install agentmemory` がホストを自動検出してマージします。 |
ホストの `localhost` に到達できない**サンドボックス化された MCP クライアント**(Flatpak / Snap /制限の強いコンテナ)では、`env` ブロックに `"AGENTMEMORY_FORCE_PROXY": "1"` も設定し、`AGENTMEMORY_URL` をサンドボックスが実際に到達できるルート(例: あなたの LAN IP)に向けてください。
-### プログラムによるアクセス(Python / Rust / Node)
+### プログラムによるアクセス
-agentmemory はコア操作を iii functions(`mem::remember`、`mem::observe`、`mem::context`、`mem::smart-search`、`mem::forget`)として登録します。iii SDK を持つあらゆる言語が `ws://localhost:49134` で直接これらを呼び出せます。言語ごとに個別の REST クライアントを用意する必要はありません。
-
-```bash
-pip install iii-sdk # Python
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
-
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-実例: [`examples/python/`](../examples/python/)(クイックスタート + 観測/リコールフロー)。iii ランタイムがないホスト向けに、`:3111` の REST も引き続き利用可能です。
+任意の言語から [REST API](#api)、エージェントから [MCP ツール](#mcp-server)を使えます。REST は JSON と Bearer 認証を使います。[保存と検索の例](#validate-a-fresh-install-and-restart-persistence)を参照してください。ランタイムへ直接接続する例は [Python ガイド](../examples/python/)にあります。
### ソースから
@@ -853,91 +860,33 @@ 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` 依存関係と同じリリースです。worker はそのエンジンの wire プロトコルを話し、0.20.0 で SDK の API サーフェスが再編されたため、両者は agentmemory のリリースで一緒に移動します。自前のエンジンを運用していて一致していると分かっている場合は、`AGENTMEMORY_III_VERSION=<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` を pull します)。完全なドキュメント: [iii.dev/docs](https://iii.dev/docs)。
+`npm start` はインストール済み CLI と同じローカルサーバーを起動します。必要環境は[インストール](#install)を参照してください。API とビューアーは `127.0.0.1` にバインドします。
### Windows
-agentmemory は Windows 10/11 で動作しますが、Node.js パッケージだけでは不十分です。ピン留めされた iii-engine v0.22.1 のランタイムをバックグラウンドプロセスとして用意する必要もあります。CLI は Windows 用 ZIP を自動展開しないため、ネイティブ Windows ユーザーは `iii.exe` を手動でインストールするか、WSL2 を使うか、Docker Desktop を選ぶ必要があります。
+agentmemory は Windows 10/11 で動作します。WSL2 は Linux の経路に従い、ピン留めされたエンジンを自動インストールできます。ネイティブ Windows では、ピン留めされた iii-engine v0.25.0 バイナリを手動でインストールしてください。[iii v0.25.0 リリースページ](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0)から該当アーカイブをダウンロードして checksum を確認し、`iii.exe` を `PATH` に配置します(例: `%USERPROFILE%\.local\bin\iii.exe`)。CLI は Windows ZIP を自動展開しません。
-ネイティブ Windows の自動化された MCP 配線がサポートするのは `agentmemory connect copilot-cli` のみです。Claude Code、Codex、Cursor、その他すべてのネイティブ Windows エージェントについては、[その他のエージェント](#other-agents)の手動 MCP ブロックをそのエージェントの Windows 用設定にコピーしてください。WSL 内で `connect` を実行するのが適切なのは、対象のエージェントも同じ WSL 環境にインストールされている場合だけです。Windows ホスト側のエージェントの設定を編集することはありません。
+ネイティブ Windows の自動 MCP 接続は `agentmemory connect copilot-cli` のみをサポートします。それ以外のネイティブ Windows エージェントには[その他のエージェント](#other-agents)の手動 MCP ブロックを使用してください。`connect` を WSL 内で実行するのは、対象エージェントも同じ WSL 環境にインストールされている場合に限ります。
-**選択肢 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 ジョブが不要なら、エンジンそのものをスキップできます:
+**スタンドアロン MCP のみ(エンジンなし)。** REST API、ビューワー、ランタイムサービスが不要で、MCP ツールだけ必要な場合:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**Windows での診断:** `npx -y @agentmemory/agentmemory@latest` が失敗する場合は、`--verbose` を付けて再実行し、実際のエンジンの stderr を確認してください。よくある失敗パターン:
-
-| 症状 | 対処 |
-|---|---|
-| `The engine process started but the REST API never responded.` | 4 つの派生ポートすべてが空いていることを確認し、ピン留めされた `iii.exe` が動き続けていることを確認した上で、`--verbose` を付けて再実行し、キャプチャされたエンジンの stderr を調べてください |
-| `Could not start iii-engine` | `iii.exe` も Docker もインストールされていません。上の選択肢 A か B を参照してください |
-| ポート競合 | `netstat -ano \| findstr :3111` で何がバインドされているか確認し、それを kill するか `--port <N>` を使ってください |
-| 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` に取得します。
+`agentmemory doctor` を実行するか、`--verbose` を付けて再起動してください。ポートが使用中なら `--port <N>` または `--instance <N>` を指定します。互換性と復旧は[アップグレードガイド](../docs/upgrades/iii-0.25.md)を参照してください。
---
<h2 id="deploy">デプロイ</h2>
-マネージドホスト向けのワンクリックテンプレートです。それぞれが、npm から
-`@agentmemory/agentmemory` を取得し、公式の `iiidev/iii` Docker Hub
-イメージから iii engine バイナリをコピーしてくる自己完結型の
-Dockerfile を同梱しているため、ビルド済みの agentmemory イメージは不要です。
-永続ストレージは `/data` にマウントされ、初回起動時のエントリポイントが、
-npm に同梱された(`127.0.0.1` にバインドする)iii の設定を、
-`0.0.0.0` にバインドし絶対パスの `/data` を使うデプロイ用の設定に上書きし、
-HMAC シークレットを生成した上で、`gosu` で `root` から `node` に
-権限を落として agentmemory の CLI を実行します。
+Docker Compose または以下のテンプレートでセルフホストできます。メモリと認証情報は `/data` ボリュームに保存されます。更新時もバックアップした同じボリュームを使ってください。認証、ネットワーク、移行は[デプロイガイド](../deploy/README.md)を参照してください。
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Render のワンクリックデプロイボタンはリポジトリルートに `render.yaml` を要求しますが、ルートはあえて綺麗なまま保っています。[`deploy/render/`](.././deploy/render/README.md) にドキュメント化された Render Blueprint フローを使い、リポジトリ内のブループリントを手動で指してください。
@@ -954,28 +903,26 @@ Render のワンクリックデプロイボタンはリポジトリルートに
経由で自前の VPS にセルフホスト。同じ Docker
Compose スタックを使い、ホストとデータは自分の手元に残ります。
-公開されるのはポート `3111` のみです。`3113` のビューワーは
-コンテナ内でループバックにバインドされたままになります。各テンプレートの
-README に、そこへ到達するための SSH トンネルパターンが記載されています。
+REST は `3111`、ビューアーは `3113` を使います。非公開で運用するか、認証と TLS で保護してください。公開設定と[従来の Docker からの移行](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)はデプロイガイドを参照してください。
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-すべてのコーディングエージェントはセッションが終わるとすべてを忘れ、新しいセッションはあなたがスタックを説明し直すところから始まります。agentmemory はバックグラウンドで動作し、そのステップをなくします。
+プロジェクトの知識はチャットや指示ファイルに散らばりがちです。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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### 組み込みエージェントメモリとの比較
@@ -984,7 +931,7 @@ Session 2: "Now add rate limiting"
| | 組み込み (CLAUDE.md) | agentmemory |
|---|---|---|
-| スケール | 200 行上限 | 無制限 |
+| 保守 | 手動で管理する指示 | インデックス化されたセッション履歴とメモリ |
| 検索 | すべてをコンテキストにロード | BM25 + ベクトル + グラフ(top-K のみ) |
| トークンコスト | 240 観測で 22K+ | ~1,900 トークン(92% 削減) |
| クロスエージェント | エージェントごとのファイル | MCP + REST(任意のエージェント) |
@@ -1010,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4 層メモリ統合
@@ -1034,6 +981,8 @@ SessionStart hook fires
### 何がキャプチャされるか
+この表は Claude Code の hooks を示します。他の統合はホストが提供するイベントを記録します。共通 hooks の自動コンテキスト挿入は `AGENTMEMORY_INJECT_CONTEXT=true` で有効にするオプションです。
+
| Hook | キャプチャ内容 |
|------|----------|
| `SessionStart` | プロジェクトパス、セッション ID |
@@ -1050,7 +999,7 @@ SessionStart hook fires
| 機能 | 説明 |
|---|---|
-| **自動キャプチャ** | hooks で毎ツール使用を記録、手動作業なし |
+| **自動キャプチャ** | ネイティブ統合が対応するセッションとツールのイベントを記録 |
| **セマンティック検索** | BM25 + ベクトル + ナレッジグラフ、RRF 融合 |
| **メモリ進化** | バージョン管理、上書き、関係グラフ |
| **リコール衛生** | 上書き(supersede)されたメモリバージョンは検索インデックスから外れ、KV のバージョンチェーンが全履歴を保持します |
@@ -1251,7 +1200,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
-ポート `3113` で自動起動します。ビューワーは接続時に 1 回スナップショットを読み込み(`GET /agentmemory/viewer/snapshot`)、その後はライブのストリームイベントを適用します: 新しいメモリ、レッスン、観測、監査エントリ、グラフの変化、ヘルス更新が、ポーリングやページの再読み込みなしに表示されます。それ以外のリクエストは、クリックしたアクション、「もっと読み込む」のページ送り、検索だけです。ストリームが切断されると、ビューワーは数値がどれだけ古いかを示し、バックオフしながら再接続し、1 回のスナップショットから再同期します。
+viewer はポート `3113` で自動起動します。接続時に snapshot (`GET /agentmemory/viewer/snapshot`)を 1 回読み込み、その後 REST worker の `/agentmemory/viewer/events` に対する SSE でライブイベントを反映します。メモリ、lesson、observation、audit entry、graph の変更、health 更新が polling やページ再読み込みなしで表示されます。
- **4 グループにまたがる 12 個のタブ**。ライブカウント、ディープリンク(`#memories/<id>`、`#sessions/<id>?obs=<id>`、`#graph/<id>`、`#health/consolidation`)、キーボードショートカット、モバイル用メニューを備えています。
- **Memories:** サーバー側検索、プロジェクト・エージェント・タイプによるフィルタ、バージョンチェーンと単語単位の diff を含む詳細パネル、来歴リンク、id・MCP 呼び出し・curl コマンドのコピーボタン、編集(新しいバージョンとして)、確認付きの forget、一括 forget、JSON エクスポート。
@@ -1268,187 +1217,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-`:3113` のビューワーはエージェントが**覚えた**ことを見せます。[iii コンソール](https://iii.dev/docs/console)はエージェントが**やった**ことを見せます: 各メモリ操作は OpenTelemetry トレース、各 KV エントリは編集可能、各 function は呼び出し可能、各ストリームは tap 可能です。同じメモリへの 2 つの窓: 一方はプロダクト形、もう一方はエンジン形です。
-
-`memory_smart_search` の発火を眺め、BM25 スキャン → 埋め込み参照 → RRF 融合 → リランカーをウォーターフォールで見ます。KV ブラウザで詰まった統合タイマーを編集します。調整したペイロードで `PostToolUse` hook を再生します。WebSocket ストリームをピンして観測がライブで着地するのを眺めます。
-
-agentmemory はこれを無料で提供します。すべての function 呼び出しとトリガーが iii を通って発火するからです。カスタム実装も計装も不要です。
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers page: connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
- <br/>
- <em>Workers ページ: agentmemory 自身を含む、接続中のすべての worker と PID、function 数、ランタイム、最終応答時刻。</em>
-</p>
-
-**インストール済みです。** コンソールはピン留めされた `iii` エンジン(0.22+)に同梱されており、別途インストールするものはありません。初回起動時に、エンジンの隣にコンソールのバイナリがダウンロードされます。
-
-**agentmemory と並行して起動:**
-
-```bash
-agentmemory console
-```
-
-これは、ピン留めされたエンジンの `iii console` を agentmemory が解決したポート(REST、ストリーム、bridge)に対して実行し、ビューワーより 1 つ上のポート、デフォルトでは `http://localhost:3114` で提供します。`--console-port N` で別のポートを選べます。`--port` と `--instance` は、`stop` のときと同じ方法で agentmemory のインスタンスを選択します。その他のフラグはそのまま渡されます。例えば、実験的なアーキテクチャグラフページ用の `--enable-flow` です。
-
-PATH に `agentmemory` が通っていない場合に便利な、手動での同じ操作:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**コンソールでできること:**
-
-| ページ | 用途 |
-|------|-----------|
-| **Workers** | agentmemory worker 自身を含む、接続中の各 worker とライブメトリクスを表示。 |
-| **Functions** | JSON ペイロードを与えて agentmemory の任意の function を直接呼び出せます。クライアントを配線せずに `memory.recall`、`memory.consolidate`、`graph.query` をテストできて便利です。 |
-| **Triggers** | HTTP、cron、イベント、ステートのトリガーを再生します: 統合 cron を手動で発火、HTTP ルートを再試行、ステート変更を発行。 |
-| **States** | セッション、メモリスロット、ライフサイクルタイマー、埋め込みインデックスに対するフル CRUD の KV ブラウザ。値をその場で編集できます。 |
-| **Streams** | メモリ書き込み、hook イベント、観測更新が iii ストリームを流れる様子をライブで監視する WebSocket モニタ。 |
-| **Queues** | 永続キューのトピック + デッドレター管理。失敗した埋め込み / 圧縮ジョブを再生または破棄できます。 |
-| **Traces** | OpenTelemetry のウォーターフォール / フレーム / サービスブレークダウンのビュー。`trace_id` でフィルタすれば、単一の `memory.search` がどの function、DB 呼び出し、埋め込みリクエストを生んだか正確にわかります。 |
-| **Logs** | trace/span ID に絞り込み・関連付けされた構造化 OTEL ログ。 |
-| **Config** | ランタイム設定: エンジンがどの worker、プロバイダー、ポートで動いているかを正確に確認できます。 |
-| **Flow** | (オプション、`--enable-flow`)各 worker、トリガー、ストリームの対話型アーキテクチャグラフ。 |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
- <br/>
- <em>Traces: すべてのメモリ操作についてのウォーターフォール / フレーム / サービスブレークダウン。</em>
-</p>
-
-**Traces は既にオンです:**
-
-`iii-config.yaml` は出荷時から `iii-observability` worker を有効化しています(`exporter: memory`、`sampling_ratio: 0.1`、メトリクス + ログ)。追加の設定は不要です。agentmemory が起動した瞬間に、すべてのメモリ操作がコンソールが読み取れる構造化ログを出し、そのうち 10 分の 1(`sampling_ratio: 0.1`)はトレーススパンも出します。
-
-代わりに Jaeger / Honeycomb / Grafana Tempo へエクスポートしたい場合は、`exporter: memory` を `exporter: otlp` に変更し、iii の可観測性ドキュメントに従ってコレクタのエンドポイントを設定してください。
-
-> **注意:** コンソール自体には認証が強制されていません。デフォルトの `127.0.0.1` バインドのままにし、決して公開しないでください。
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory は**それ自体が稼働中の [iii](https://iii.dev) インスタンス**です。3 つのプリミティブ(worker、function、トリガー)がランタイムを構成し、KV ステート、ストリーム、OTEL トレースは、iii に同梱される iii-state、iii-stream、iii-observability の各 worker が提供します。Postgres、Redis、Express、pm2、Prometheus をインストールしなかったのは、iii がそれらを置き換えるからです。
-
-つまり、もう 1 つのコマンドで agentmemory にまったく新しい機能を拡張できます。
-
-### agentmemory をさらに worker で拡張する
-
-agentmemory が必要とする組み込み worker は、既に `iii-config.yaml` に入っていて、起動時に一緒に立ち上がります: `iii-state`(KV)、`iii-queue`(イベントサブスクライバー向けの永続リトライ)、`iii-pubsub`、`iii-cron`、`iii-stream`、そして `iii-observability`(すべての function に OTEL トレース、メトリクス、ログ)です。[iii worker レジストリ](https://workers.iii.dev)にあるその他の worker は、同じエンジンにそのまま差し込めます: `iii-config.yaml` を `~/.agentmemory/iii-config.yaml` にコピーし(CLI は同梱のファイルよりこのファイルを優先しつつ、ポートとデータパスはそのままレンダリングします)、エントリを追加し、`~/.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) | インメモリの KV デフォルトでは不足するときの SQL バックエンドのステートアダプタ |
-| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall` から出てきたコードは、あなたのシェルではなく使い捨ての VM 内で実行されます |
-| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory の MCP サーバーの隣に追加の MCP サーバーを立て、同じエンジンを共有します |
-
-エンジン 0.22.x では、上記の組み込み worker については `iii-` 接頭辞付きの名前をそのまま使ってください。接頭辞のない `http`、`state`、`queue`、`pubsub`、`cron` は、agentmemory が 0.23 への移行で切り替える先のスタンドアロンなレジストリ worker です。
-
-完全なレジストリ: [workers.iii.dev](https://workers.iii.dev)。そこにあるすべての worker は agentmemory が使っているのと同じプリミティブで組み立てられています。そして、あなたが既に手元にある agentmemory も、そのうちの 1 つです。
-
-### エンジン設定とバインドアドレス
-
-`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 はコンテナのループバックをリッスンするため、公開されたポートは何にも到達しません。コンテナ化された 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(デフォルト)vs redis
-
-`iii-state` と `iii-stream` は、デフォルトで iii-engine 同梱のファイルベースの KV ストアを使います: スコープごとに 1 つの JSON ファイルで、エンジンプロセスのメモリ上に保持され、タイマーでディスクに書き戻されます。これは、単一ユーザーのローカルインストールには正しいデフォルトです。複数の書き込み側が同時にアクセスする共有デーモンでは、代わりに Redis から本物のキー単位の書き込みが得られますが、操作あたりネットワークのラウンドトリップが発生するコストがあります(すべての `state::*` 呼び出しは依然として 1 つの Redis 接続上で直列化されるため、これはファイルストアのロックをソケットに置き換えるだけで、並列性を得るものではありません)。
-
-両方の worker を 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)は TLS サポートなしで Redis クライアントをビルドするため、`rediss://` の URL(Upstash、Redis Cloud、転送時暗号化付き ElastiCache など、ほとんどのマネージド Redis サービスのデフォルトは TLS 専用です)は接続に失敗します。接続は暗号化されないため、Redis のパスワードと保存されているすべてのメモリが平文で回線上を流れます。ローカルの Redis か、信頼できるプライベートネットワーク上の Redis を指してください。それ以外の Redis の場合は、agentmemory のホスト上で暗号化されたトンネル(stunnel、SSH、または VPN)を実行し、プレーンな `redis://` のホップをそのホスト内に留め、トンネルの上流側の接続は暗号化・認証されるようにしてください。Redis のパスワードにシングルクォートが含まれる場合は、パーセントエンコードしてください(`%27`)。エンジンは URL を YAML 設定に展開してからパースします。
-
-**`--instance` ごとに Redis サーバーを 1 つ。** エンジンの Redis キー接頭辞(`state:<scope>`、`stream:<name>:<group>`)は固定なので、同じデータベースを指す 2 つの agentmemory インスタンス(`--instance 1`、`--instance 2`、...)は互いのデータを上書きします。別のデータベース番号(`redis://localhost:6379/1`)を使えば保存データは分離されますが、エンジンはライブのビューワーイベントを 1 つの Redis pub/sub チャネル(`stream::events`)経由で中継し、Redis の pub/sub はデータベース番号を無視するため、各インスタンスのビューワーには依然として他方のライブイベントが表示されてしまいます。複数インスタンスを運用するときは、インスタンスごとに別々の Redis サーバー(またはポート)を用意してください。
-
-**変わらないこと、変わること。** agentmemory のすべての機能が Redis 上でも動作します: セッション、観測、メモリ(remember、supersede、evolve、forget)、検索とそのインデックスバケット、レッスン、グラフ、監査ログとその月次スコープ、エクスポートとインポート、ガバナンス削除、統合ステータス、ビューワーのスナップショットとそのライブストリーム、ヘルスモニタです。エンジンは各スコープを 1 つの Redis ハッシュ(`HSET`/`HGET`/`HGETALL`)として保存し、ファイルストアと同じステートトリガーを発火します。3 つのエンジンの差異は agentmemory の内部で処理されています:
-
-- Redis はスコープのレコードを一定の順序では返しません。agentmemory はそれらを作成の古い順(レコード id 内の作成時刻、次にそのタイムスタンプ)に並べ替えるため、一覧・ページ送り・エクスポートのチャンクはファイルストアと同じ順序で返ってきます。
-- エンジンは Redis 上の部分更新を、空の配列を空のオブジェクトに変えてしまう Lua スクリプトで適用します。agentmemory は Redis 上ではこれらの更新を自分自身で適用します(読み取り、変更、キー単位のロック下での書き込み)。そのため `tags: []` のようなフィールドは配列のままになります。
-- レガシーな監査ログのチェックは、ディスク上のファイルストアのファイルを探す代わりに、Redis から古いスコープを読み取ります。
-
-1 つだけ、あなたの対応が必要な差異があります: **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`)を表示します。非常に大きなスコープを一覧表示すると、ハッシュ全体を 1 回の `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` は、その組み合わせを検出すると警告します。そのファイルは、[iii-state](https://workers.iii.dev/workers/iii-state) と [iii-stream](https://workers.iii.dev/workers/iii-stream) の worker ドキュメントに示されている同じ `name: redis` / `config: redis_url: ...` の形に従って手動で切り替え、`redis_url` をコンテナから到達可能な Redis に向けてください。`docker-compose.yml` は `AGENTMEMORY_REDIS_URL` をエンジンコンテナに渡すため、そこでは `redis_url: '${AGENTMEMORY_REDIS_URL}'` が動作し、URL をマウントされたファイルの外に保てます。
-
-レンダリングされた設定は URL を `~/.agentmemory/data/iii-config.runtime.yaml` の外に保ちますが、エンジン自身の configuration worker は、起動すると*展開済みの*値を `~/.agentmemory/config/iii-state.yaml` と `iii-stream.yaml` に永続化します(iii-engine の `${VAR}` 展開はその worker がシードを保存する前に行われ、worker は参照ではなく解決済みの値を保存します)。そのディレクトリは認証情報を保持しているものとして扱ってください: 共有ホストでは `chmod 700 ~/.agentmemory` を実行し、データベースの管理者権限よりも、agentmemory が必要とする範囲に絞った Redis の ACL ユーザーを使うことを推奨します。
-
-**移行は自動ではありません。** `AGENTMEMORY_STATE_BACKEND` を切り替えると、どちら側も空のストアから始まります。既存のデータが file から Redis へ、あるいはその逆へ自動でコピーされることはありません。移行元のバックエンドからエクスポートし、移行先のバックエンドへインポートしてください。これは bash と zsh のどちらでも同じように動作します(`bash -u` を含む)。`AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` のような配列はそうではありません: `AGENTMEMORY_SECRET` が設定されているとき、zsh はヘッダーを 1 つの不正な語として保持しますが bash はそれを 2 つに分割するため、どちらのリクエストも常に 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 worker 監視 |
-| Prometheus / Grafana | iii OTEL + ヘルスモニタ |
-| カスタムプラグインシステム | `iii worker add <name>` |
-
-**250 ソースファイル · ~55,000 LOC · 3,400+ テスト · 324 functions · 67 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
### LLM プロバイダー
@@ -1466,6 +1234,8 @@ agentmemory は環境からプロバイダーを自動検出します。プロ
| **ローカル(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=<your model>` | OpenAI API 互換なら何でも。コストゼロ、あなたのハードウェアで動作します。下記の[ローカルモデル](#local-models-ollama--lm-studio--vllm)を参照してください。 |
| Claude 購読フォールバック | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | オプトインのみ。`@anthropic-ai/claude-agent-sdk` のセッションを生成します。過去に無限の Stop-hook 再帰を引き起こしたため、もはやデフォルトではありません。 |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### ローカルモデル(Ollama / LM Studio / vLLM)
agentmemory は OpenAI API 互換のあらゆるサーバーと通信できるため、`/v1/chat/completions` を公開するものならコード変更なしで動きます。有料キーもクラウドもレート制限もなし。すべてあなたのハードウェア上で動作します。
@@ -1515,24 +1285,9 @@ Qwen 3 モデルはデフォルトで思考(thinking)を行い、出力を出す
### コストを意識したモデル選択
-バックグラウンド圧縮が、プロバイダーと `AGENTMEMORY_AUTO_COMPRESS=true` の両方で有効になっている場合、それは観測のたびに走るため、モデル選択は月額支出に大きく影響します。記録されたワークロード: 635 リクエスト / 888K トークン / 35 時間のアクティブ使用を、2026-05-23 時点の OpenRouter 価格で 3 モデルに対して実行しました。
-
-| 階層 | モデル | 入力 / 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 | 圧縮 + 要約品質が手堅く、Sonnet の約 10 分の 1 のコスト。 |
-| 推奨 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | セッションがコード中心ならコード推論が強い。 |
-| プレミアム | `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(推定) | フラッグシップクラスのモデル。圧縮には過剰支出。 |
-
-実測の行は記録された実行から得たもので、(推定)の行は同じトークン構成を各モデルの定価でスケールしたものです。
+まずキーレスでキャプチャとキーワード検索を使えます。`EMBEDDING_PROVIDER=local` は初回ダウンロード後にローカルで意味検索を行います。LLM 圧縮にはプロバイダーと `AGENTMEMORY_AUTO_COMPRESS=true` が必要で、観測ごとにリクエストが発生し得るため現在の料金を確認してください。
-agentmemory は、`OPENROUTER_MODEL` がプレミアム階層のパターンに一致するときランタイム警告を表示します。納得して選んだあとは `AGENTMEMORY_SUPPRESS_COST_WARNING=1` で消音できます。
-
-メモリ作業における品質対コストのトレードオフ: 圧縮は品質のハードルが比較的緩い要約タスクです(要約を読み返すのはエージェントであってユーザーではありません)。DeepSeek V4 Flash / V4 Pro / Qwen3-Coder はこのタスクで Sonnet と誤差範囲に収まる一方、コストは 10〜70 分の 1 です。プレミアム階層のモデルは、あなたが直接読むクエリのために取っておきましょう。
-
-出典: [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/)。
+`agentmemory status` / http://localhost:3113
### マルチエージェントメモリ(`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1562,37 +1317,22 @@ SDK / REST 層での呼び出し単位オーバーライド: すべての変更
### ポート
-agentmemory + iii-engine はデフォルトで 4 つのポートをバインドします。再起動が `port in use` で失敗する場合、この表でどのプロセスを探せばよいか分かります。
-
-| ポート | プロセス | 用途 | 環境変数での上書き |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | 内部ストリーム worker(agentmemory + ビューワーが消費) | `III_STREAM_PORT`(推奨)または legacy の `III_STREAMS_PORT` |
-| `3113` | agentmemory | リアルタイムビューワー(`http://localhost:3113`) | `III_VIEWER_PORT`、または報告される URL 用の `AGENTMEMORY_VIEWER_URL` |
-| `49134` | iii-engine | WebSocket。worker はここに登録し、OTel テレメトリもここを流れます | `III_ENGINE_PORT` または `III_ENGINE_URL` |
-
-`--port <N>` は REST の基点を変更し、上の対応する明示的なポートや URL が未設定の場合に限り、ストリームを `N+1`、ビューワーを `N+2`、エンジンの WebSocket を `N+46023` として導出します。これは独立したライフサイクル名前空間を作るものではありません。2 つめのデーモンには `--instance 1` を使ってください。基点 3211 を使い、デフォルトは `3211/3212/3213/49234` になり、別の `instance-1` のデータとライフサイクルディレクトリを受け取ります。インスタンス 1 から 50 まで同じパターンに従います。
+API とビューアーはデフォルトでループバックにバインドします。
-ピン留めされたエンジンは `--no-update-check`(起動時に GitHub へのアップデートやセキュリティ勧告の確認を行わない)で起動し、iii の匿名使用状況テレメトリもオフの状態で起動します: agentmemory は、自分で変数を export していない限り、自身が起動するエンジンに対して `III_TELEMETRY_ENABLED=false` を設定します。同梱の compose ファイルも同様です。
+| Port | API / ビューアー | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | ビューアー | `III_VIEWER_PORT` |
-クラッシュ後にポートが解放されないときの古いプロセス整理:
+`--port <N>` は API ポートを設定し、ビューアーはデフォルトで `N+2` になります。`--instance N` で別のインスタンスを使えます。内部リスナーは非公開にし、外部公開や[旧 Docker からの移行](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)はデプロイガイドに従ってください。
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### ストレージ backend: file (デフォルト) と Redis
-`agentmemory stop` は、正常なネイティブ終了時に worker と engine の pidfile をきれいに回収します。Docker モードでは、ネイティブ worker をフラッシュしてから、検証済みのそのエンジンコンテナだけを停止し、無損失の再起動のためにコンテナとその `/data` マウントの両方を保持します。次回起動時には、同じコンテナを検証して再利用します。Docker バックエンドでのアンインストールには `agentmemory remove --keep-data` が必要です: これは、検証済みのコンテナ、そのデータマウント、それらを復旧するために必要なライフサイクルレコードを保持したまま、共有の agentmemory 管理ファイルだけを削除します。破壊的な Docker データ削除は、バックアップ後に操作者の判断で行うよう意図的に残されています。また CLI は、`--force` を渡さない限り、Docker や VM のポート保持プロセス(Docker バックエンド、vpnkit、colima)をネイティブエンジンとして採用・シグナルすることを拒否します。上の手動クリーンアップは、どちらの pidfile も残っていないクラッシュ後の状態だけを対象としています。
+別のデータベースサービスは不要. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. 変更しても既存のメモリは自動移行されません。 [データの保存](../docs/reliability/state-storage.md).
### 設定ファイル
-agentmemory のランタイム設定は、各シェルで変数を export するのではなく `~/.agentmemory/.env` に置いてください。ビューワーが `export ANTHROPIC_API_KEY=...` のようなセットアップヒントを表示したら、これをこのファイルに `ANTHROPIC_API_KEY=...` として(`export` プレフィックスなしで)コピーしてから agentmemory を再起動してください。
+毎回 shell で変数を export する代わりに、agentmemory のランタイム設定を `~/.agentmemory/.env` に記述してください。viewer が `export ANTHROPIC_API_KEY=...` のような設定ヒントを表示した場合は、`export` を除いてファイルにコピーし、agentmemory を再起動します。別の env ファイルを使うには `AGENTMEMORY_ENV_FILE` を設定してください。
プロセスの環境変数も引き続き有効で、ファイル内の値より優先されます。
@@ -1621,176 +1361,31 @@ GRAPH_EXTRACTION_ENABLED=true
### 環境変数
-`~/.agentmemory/.env` を作成してください:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+完全な設定一覧は [`.env.example`](../.env.example) にあります。プロバイダー、キャプチャのフィルター、保持期間、ストレージ、チーム設定を含みます。`AGENTMEMORY_ENV_FILE` で別ファイルを選べます。変更後は再起動してください。値を設定した `.env` や Bearer シークレットをコミットしないでください。
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-ポート `3111` 上の 143 エンドポイント。REST API はデフォルトで `127.0.0.1` にバインドします。保護されたエンドポイントは `Authorization: Bearer <secret>` を要求し、mesh sync エンドポイントは両ピアで明示的に設定された `AGENTMEMORY_SECRET` を要求します。
+ポート `3111` 上の 146 エンドポイント。REST API はデフォルトで `127.0.0.1` にバインドします。保護されたエンドポイントは `Authorization: Bearer <secret>` を要求し、mesh sync エンドポイントは両ピアで明示的に設定された `AGENTMEMORY_SECRET` を要求します。
-**認証はデフォルトでオンです。** `AGENTMEMORY_SECRET` が(シェルにも `~/.agentmemory/.env` にも)設定されていない場合、サーバーは初回起動時にランダムなシークレットを生成し、モード `0600` で `~/.agentmemory/secret` に保存します。同梱のすべてのクライアント — CLI、ビューワー、`plugin/scripts` 配下の hooks、MCP サーバーと `@agentmemory/mcp` の shim、`agentmemory connect` が書き込む設定、同梱の OpenCode、Pi、OpenClaw、Hermes、ファイルシステムウォッチャーの各統合 — は、ローカルサーバーと話すときにそこから読み取ります。保存されたシークレットは、ループバックの URL(`localhost`、`127.0.0.0/8`、`::1`)にのみ送信されます。明示的な `AGENTMEMORY_SECRET` は常に優先され、リモートクライアントではそれでも設定が必要です。Docker と `deploy/` のエントリポイントは、既に独自のシークレットを生成・export しています。手動で API を呼ぶには:
+認証はデフォルトで有効です。`AGENTMEMORY_SECRET` が未設定なら、CLI は初回起動時にランダムなシークレットを `~/.agentmemory/secret` に保存し、選択したデータディレクトリの `secret` にも複製します。権限は `0600` です。同梱クライアントはローカル接続時にこの共通ファイルを優先し、保存されたシークレットを送るのはループバック URL だけです。明示的な `AGENTMEMORY_SECRET` が優先され、リモート接続には環境変数で指定します。Docker デプロイは独自のシークレットを生成します。
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
@@ -1829,7 +1424,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | チームと共有 |
| `GET` | `/agentmemory/audit` | 監査証跡 |
-完全なエンドポイント一覧: [`src/triggers/api.ts`](../src/triggers/api.ts)
+完全なエンドポイント一覧: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1847,19 +1442,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
サーバーがダウンしている、時間内に応答しない、または 5xx を返す場合、hook はその観測をローカルのスプールファイル `<data dir>/capture-spool/<host>-<port>.jsonl` に追記します(フォルダは `AGENTMEMORY_CAPTURE_SPOOL_DIR` で上書きできます)。このファイルはあなたのユーザーに非公開(モード 600)で、シークレットはサーバーが行うのと同じ方法でマスクされ、最大 `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`(5 MiB)まで保持し、`AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`(168)より古いエントリを捨てます。満杯になると、新しいエントリは破棄されカウントされ、`/agentmemory/status` がそれを報告します。サーバーが健全なときは、hook はその時間制限内でそのまま exit 0 し、リクエストは追加されません。スプールは次回起動時、およびサーバーに再び到達できた最初の hook によって、エージェントを待たせないバックグラウンドプロセスで送信されます。イベント id がこれを安全にします: タイムアウト前に到達済みの観測が二重に保存されることはありません。`npx @agentmemory/agentmemory capture` はスプールとサーバーの受信箱を表示し、`--drain` はスプールを今すぐ送信し、`GET /agentmemory/capture` は同じ内容を JSON で返します。スプールをオフにするには `AGENTMEMORY_CAPTURE_SPOOL=false` を設定してください。
-**グラフの来歴のコンパクション。** 各ナレッジグラフのノードとエッジは、その由来となった最新 32 件の観測の id を保持します。この上限ができる前に書き込まれたストアでは、アクセスの多いノード 1 つあたり数千件の id を持つことがあり、グラフ検索とビューワーが遅くなったり、worker が落ちたりします。agentmemory はこれを自力で修正します: アップグレード後の最初の起動時に、すべてのノード、エッジ、上書きされたエッジ(時系列のグラフ履歴)、キャッシュされたスナップショットをバックグラウンドでこの上限まで、間に一時停止を挟んだ小さなスライスで切り詰めるため、検索、キャプチャ、ビューワーは動作を続けられます。進捗は保存され、再起動後も再開され、完了すると二度と実行されません。`/agentmemory/status` とビューワーの Health ページには、保留中、実行中(現在のスコープと位置とともに)、完了、失敗のいずれかとして表示されます。オフにするには `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` を設定してください。
+**グラフの来歴のコンパクション。** 旧来の来歴データのコンパクションは、旧来のスコープ全体を読み取るため、起動時には延期されます。`/agentmemory/status` は `deferred`、`AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` の場合は `off` を返します。メンテナンス中に以下の手動コンパクションを実行してください。検索インデックスの移行は別の操作です。[メンテナンスガイド](../docs/reliability/graph-index-migration.md)に従って `agentmemory graph-index migrate --allow-legacy-scan` を使用してください。
手動で実行するには `POST /agentmemory/graph/compact` を呼び出してください。すべてのノードとエッジを列挙するのではなく、名前とエッジキーのインデックスを走査するため、再実行しても安全です。id を切り詰めたときは `graph_compact` の監査エントリを書き込みます。
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{}'
```
大規模なストアで、あるいは呼び出しが 504 を返す場合は、分割して実行してください。`scope`(`nodes`、`edges`、または `history`)、`offset`、`limit` を送り、返ってきた `nextOffset` が `null` になるまで呼び出しを繰り返します。これを `nodes`、`edges`、`history` それぞれについて行い、最後に `{"scope":"snapshot"}` を 1 回呼んで終えてください。分割実行はキャッシュされたスナップショットには触れないためです。
```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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1873,7 +1468,7 @@ npm test # 4,000+ 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 を使います。
+必要環境は[インストール](#install)、開発とリリースの規則は [CONTRIBUTING.md](../CONTRIBUTING.md) を参照してください。
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md
index 6fd0d7a8..6ad3ce41 100644
--- a/READMEs/README.ko-KR.md
+++ b/READMEs/README.ko-KR.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- 코딩 에이전트가 모든 것을 기억합니다. 더 이상 다시 설명할 필요가 없습니다.
- <a href="https://github.com/iii-hq/iii">iii engine</a> 기반
+ 코딩 세션과 에이전트를 이어 주는 영구 메모리.
</strong><br/>
- Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, 그리고 모든 MCP 클라이언트를 위한 영구 메모리입니다.
+ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, 그리고 모든 MCP 클라이언트를 위한 영구 메모리입니다.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">동작 방식</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">뷰어</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">설정</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory는 코딩 세션을 기록하고 이전 결정과 수정 사항을 검색할 수 있게 합니다. 여러 도구가 하나의 메모리 저장소를 공유하며, 저장된 내용을 확인하고 모델에 전달할 컨텍스트의 양을 선택할 수 있습니다.
+
## 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을 사용하는 것도 지원되는 경로입니다.
+- macOS/Linux 자동 설정에는 `curl`, POSIX `sh`, `tar`가 필요합니다.
+- Windows / WSL2: [Windows](#windows).
표준 신규 설치 명령:
@@ -108,11 +109,11 @@
npx -y @agentmemory/agentmemory@latest
```
-첫 실행은 인터랙티브 설정입니다: 연결할 에이전트(Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...)를 고르고, LLM 프로바이더를 선택하거나 키 없이 유지할 수 있으며, 그 뒤 설정을 시드하고 메모리 서버와 고정된 iii 엔진을 시작한 다음, 이후 어디서나 단순한 `agentmemory` 명령이 동작하도록 전역 설치를 제안합니다. `-y`는 npx의 패키지 설치 확인 프롬프트를 수락하고, `@latest`는 캐시된 오래된 릴리스를 피합니다. 프로바이더를 설정하면 LLM 기능을 사용할 수 있게 되지만, LLM이 작성하는 관측 압축은 `AGENTMEMORY_AUTO_COMPRESS=true`도 함께 설정해야 비로소 시작됩니다.
+에이전트와 프로바이더 또는 키 없는 모드를 선택합니다. 설정을 저장하고 메모리 서버를 시작한 뒤 전역 설치를 안내합니다. `-y`는 npm 확인을 수락하고 `@latest`는 최신 릴리스를 선택합니다. 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 <path>` 또는 `AGENTMEMORY_DATA_DIR`을 사용하고, 재시작할 때마다 동일한 값을 재사용하십시오. 하위 호환성을 위해, 기존의 `./data/state_store.db` 또는 `./data/iii-config.yaml`이 존재하면 인스턴스 0에서 플랫폼 기본값보다 우선합니다. 명시적인 플래그나 환경 변수 재정의는 그보다도 우선합니다.
+API는 `http://localhost:3111`, 라이브 뷰어는 `http://localhost:3113`입니다. 둘 다 기본적으로 루프백에 바인딩됩니다. 설정은 `~/.agentmemory/.env`에 저장합니다. [데이터 저장](#data-storage).
그다음 리콜이 동작하는지 확인하고 에이전트에게 skills를 부여하십시오:
@@ -127,14 +128,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-`agentmemory connect <agent>`로 언제든지 더 많은 에이전트를 연결할 수 있습니다 — 20개의 어댑터가 [모든 에이전트와 호환](#works-with-every-agent)에 나열되어 있습니다. 전체 명령 레퍼런스는 [빠른 시작](#quick-start)에 있습니다.
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-가장 빠른 경로는 WSL2입니다. 네이티브 Windows 엔진 설정은 고정 버전인 v0.22.1 ZIP 파일을 다운로드하고 `iii.exe`를 수동으로 압축 해제해야 합니다. CLI는 이를 자동으로 압축 해제하지 않습니다. Docker Desktop도 지원됩니다. 단계별 방법은 [Windows 노트](#windows)를 참고하십시오.
-
-</details>
+`agentmemory connect <agent>`로 에이전트를 추가합니다. [지원 통합](#works-with-every-agent)과 [일상 명령어](#everyday-commands)를 참고하세요.
<details>
<summary><strong>전역 설치 / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx는 버전별로 캐싱합니다. `npx -y @agentmemory/agentmemory@latest`로
</details>
-<details>
-<summary><strong>이미 자체 iii 엔진을 실행 중인 경우</strong></summary>
-
-agentmemory는 iii-engine v0.22.1을 고정하며 다른 버전에는 연결하지 않습니다(워커가 다른 엔진의 프로토콜을 말할 수 없기 때문입니다). 다른 엔진을 중지한 다음 `npx -y @agentmemory/agentmemory@latest`를 실행하십시오. 이 명령은 고정된 v0.22.1을 `~/.agentmemory/bin`에 설치하고 실행하며, 사용자의 기존 `iii`는 그대로 둡니다.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="모든 에이전트와 호환" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>네이티브 플러그인 + hook 7개 + MCP</sub>
+<sub>네이티브 플러그인 + 수명주기 훅 + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>네이티브 플러그인 + MCP</sub>
+<sub>네이티브 회상 + 캡처 + 스킬</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP 서버</sub>
+<sub>네이티브 캡처 + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>네이티브 회상 + 캡처 + 스킬 + 선택적 MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +304,24 @@ agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환
---
-세션마다 같은 아키텍처를 설명하고, 같은 버그를 다시 찾아내고, 같은 선호 사항을 다시 가르쳐야 합니다. 내장 메모리(CLAUDE.md, .cursorrules)는 200줄 한도에 막히고 금방 낡아버립니다. agentmemory가 이 문제를 해결합니다. 에이전트가 하는 일을 조용히 캡처하고, 검색 가능한 메모리로 압축한 다음, 다음 세션이 시작될 때 올바른 컨텍스트를 주입합니다. 명령 하나면 충분하며, 여러 에이전트에서 동일하게 동작합니다.
+<a id="data-storage"></a>
-**무엇이 바뀌는가:** 세션 1에서 JWT 인증을 설정합니다. 세션 2에서 rate limiting을 요청합니다. 에이전트는 이미 인증이 `src/middleware/auth.ts`의 jose 미들웨어를 사용한다는 것, 테스트가 토큰 검증을 다룬다는 것, 그리고 Edge 호환성 때문에 jsonwebtoken 대신 jose를 선택했다는 것을 알고 있으므로, 다시 설명할 필요도 복사·붙여넣기도 없습니다.
+### 데이터 저장
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+메모리는 기본적으로 저장소 밖에 보관됩니다. 인스턴스 0은 기존 `./data/state_store.db`를 재사용합니다. `--data-dir <path>` 또는 `AGENTMEMORY_DATA_DIR`로 위치를 지정하고, 재시작과 업그레이드 때도 같은 디렉터리를 사용하세요.
-기본적으로 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 <path>`를 전달하거나 `AGENTMEMORY_DATA_DIR`을 설정하십시오. 둘 중 어느 쪽을 명시해도 레거시 탐색보다 우선합니다:
+| 플랫폼 | 데이터 디렉터리 |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-네이티브 실행과 Docker 실행은 동일하게 해석된 호스트 디렉터리를 사용합니다. Docker는 이를 `/data`에 바인드 마운트합니다. `--instance 1`은 해석된 디렉터리에 `instance-1`을 덧붙이고, 별도의 기본 포트 4종 세트인 `3211/3212/3213/49234`를 선택합니다.
+`--instance 1`은 `instance-1` 하위 디렉터리와 API 포트 `3211`, 뷰어 포트 `3213`을 사용합니다. Redis와 이전 방법은 [저장소 및 백업](../docs/reliability/state-storage.md)을 참고하세요.
최신 릴리스 노트: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +471,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>외부 의존성</strong></td>
-<td>없음 (SQLite + iii-engine)</td>
+<td>별도 데이터베이스 서비스 불필요</td>
<td>Qdrant / pgvector</td>
<td>Postgres + 벡터 DB</td>
<td>다수</td>
@@ -550,14 +545,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | 시간적 지식 그래프. 게시된 시간 쿼리 결과 중 가장 강력(LongMemEval 63.8%)하지만, 그래프가 비동기로 빌드되어 최신 사실이 지연될 수 있음 |
| Cognee | 30K | 문서-지식 그래프 수집, Python 전용, 세션 캡처보다는 구조화된 엔티티 추출을 위해 설계됨 |
-이들 중 어느 것도 코딩 에이전트 hook에서 자동 캡처하거나, 로컬 우선 뷰어를 제공하거나, 키 없이 실행되지 않습니다 — agentmemory가 중심에 두고 만들어진 조합입니다.
+AgentMemory는 세션 캡처, 검색 가능한 프로젝트 이력, 로컬 뷰어를 함께 제공하며 처음부터 키 없이 사용할 수 있습니다.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="빠른 시작" height="32" /></picture></h2>
-호환성: 이 릴리스는 `iii-sdk` 0.22.1을 대상으로 하며 iii-engine을 v0.22.1로 고정합니다.
-
### 30초 만에 사용해 보기
```bash
@@ -572,9 +565,11 @@ npx -y @agentmemory/agentmemory@latest demo
`http://localhost:3113`을 열어서 메모리가 실시간으로 쌓이는 것을 지켜보십시오.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 신규 설치 검증 및 재시작 지속성 확인
-서버가 실행 중인 상태에서 REST, health, 뷰어, iii 기반 런타임 상태를 검증하십시오:
+서버가 실행 중인 상태에서 헬스, 뷰어, 상태를 확인하세요.
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +578,27 @@ 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를 저장하고 검색되는지 확인하십시오:
+`status`는 서버 상태, 프로바이더와 임베딩 모드, 캡처 전달, 복구 상태를 표시합니다. 보호된 REST 요청에는 서버 비밀값이 필요합니다. 설정한 `AGENTMEMORY_SECRET`을 사용하거나, 미설정 시 생성된 로컬 비밀값을 읽으세요.
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
그런 다음 `npx -y @agentmemory/agentmemory@latest stop`을 실행하고, Terminal 1에서 표준 명령을 다시 시작한 뒤 `/agentmemory/livez`를 기다렸다가 검색을 반복하십시오. probe는 여전히 반환되어야 합니다. 커스텀 `--data-dir`을 선택했다면 재시작 시에도 동일한 디렉터리를 전달하십시오.
+<a id="everyday-commands"></a>
+
### 매일 쓰는 명령어
설치와 설정은 위의 [Install](#install)에 있습니다(첫 실행이 안내해 줍니다). 일상적으로는:
@@ -604,7 +606,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +628,7 @@ npx -y @agentmemory/agentmemory@latest import-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과 lesson으로 마이닝됩니다.
+가져온 세션은 네이티브 세션과 함께 Replay에 표시되고 검색용으로 색인됩니다. 출처는 `import`로 표시되며 세션 처리에서 크리스털과 교훈이 생성될 수도 있습니다.
> **`import-jsonl`을 주요 캡처 경로로 삼는 경우 주의하십시오:** Claude Code의 `cleanupPeriodDays`(`~/.claude/settings.json`, 기본값 **30**)는 그 기간보다 오래된 JSONL 트랜스크립트를 `~/.claude/projects/`에서 자동으로 삭제합니다. 몇 달 된 Claude Code 기록 위에 agentmemory를 새로 설치하면, 30일보다 오래된 것은 첫 가져오기 전에 이미 사라진 상태입니다. `import-jsonl`을 cron으로 실행하거나, `cleanupPeriodDays`를 더 높게 올리거나, 자동 캡처 hook(기본 플러그인 설치 경로)을 연결해서 세션이 살아 있는 동안 매 턴이 agentmemory에 바로 기록되도록 하여 JSONL 정리가 더 이상 문제되지 않게 하십시오.
@@ -635,14 +640,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, 고정된 Docker 이미지 `iiidev/iii:0.22.1`을 pull할 수 있습니다. 고정되지 않았거나 더 새로운 iii 엔진을 설치하는 일은 절대 없습니다.
-
-구현 세부 사항은 `src/cli.ts`에 있습니다(`runUpgrade`는 `src/cli.ts:544-595` 부근을 참고하십시오).
+로컬 런타임을 업데이트하며 현재 작업 디렉터리의 JavaScript 의존성도 바꿀 수 있습니다. 데이터를 백업하고 기존 설치를 업데이트하기 전에 [업그레이드 가이드](../docs/upgrades/iii-0.25.md)를 읽으세요.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### 플러그인 설치 없이 Claude Code 사용 (MCP 독립형 경로)
@@ -703,6 +706,26 @@ 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 경험을 원한다면 플러그인도 함께 설치하십시오.
+### Cursor
+
+`agentmemory connect cursor`로 MCP를 설정합니다. **Settings → Plugins → Add marketplace**에서 `.cursor-plugin/plugin.json`이 있는 체크아웃을 선택하고 agentmemory를 활성화한 뒤 다시 로드하세요. 플러그인은 수명주기 캡처, 작업공간 식별, 스킬, MCP를 제공합니다. 중복 캡처를 막으려면 플러그인 훅과 `~/.cursor/hooks.json`의 수동 훅 중 하나만 사용하세요.
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+호스트에 맞는 명령을 선택하세요. Pi와 OMP는 네이티브 회상과 캡처, 오프라인 재전송, 17개 스킬을 설치하며 `--with-mcp`는 전체 도구를 추가합니다. Pi에서 `/reload`를 실행하거나 OMP를 재시작한 뒤 `/agentmemory-status`를 확인하세요. DSH는 MCP와 번들 캡처 플러그인을 설치하므로 연결 후 재시작하세요.
+
+Pi는 `@agentmemory/pi` 패키지로도 설치할 수 있습니다. 로컬 설치와 npm 제공 여부는 [Pi 가이드](../integrations/pi/)를 참고하고 호스트마다 한 가지 설치 방법만 사용하세요.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (이 프롬프트를 붙여넣으세요)</b></summary>
@@ -749,6 +772,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### 다른 에이전트
메모리 서버 시작: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +790,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
이는 `agentmemory connect <agent>`와 **상호 보완적**입니다:
-- `agentmemory connect <agent>`는 MCP 서버 설정을 작성해서 도구를 사용할 수 있게 만듭니다.
-- `npx skills add rohitg00/agentmemory`는 skill을 설치해서 에이전트가 언제 호출해야 하는지 알게 합니다.
+Hermes, OpenClaw, Pi, Oh My Pi 커넥터는 기본적으로 네이티브 통합과 스킬을 설치합니다. MCP는 `--with-mcp`로 추가합니다. 다른 호스트에서는 `npx skills add rohitg00/agentmemory`로 스킬을 설치할 수 있습니다.
skill CLI가 아직 다루지 않는 일부 에이전트(Zed v1.3.x 이하)의 경우, 17개의 SKILL.md 파일을 에이전트의 네이티브 skill 디렉터리에 직접 넣으십시오. 동일한 형식이 어디서나 동작합니다.
@@ -790,7 +814,7 @@ agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Curso
| 에이전트 | 설정 파일 | 참고 |
|---|---|---|
| **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 모드 프롬프트는 세션 종료 시 세션 트랜스크립트로부터 소급 채워집니다. |
+| **Cursor (전체 플러그인)** | `.cursor-plugin/` | Cursor Marketplace 또는 Settings → Plugins → 로컬 체크아웃으로 설치합니다. 공통 `plugin/scripts/*.mjs`를 호출하는 얇은 어댑터로 수명주기 훅을 등록하며 스킬과 MCP를 제공합니다. 어댑터는 Cursor가 정확히 보고하지 않는 작업공간을 식별합니다. [Cursor](#cursor)를 참고하세요. Cursor IDE와 `cursor-agent` 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 + 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`로 확인하십시오. |
@@ -804,7 +828,8 @@ agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Curso
| **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`). |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · 네이티브 회상 + 캡처 + 스킬. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · 네이티브 회상 + 캡처 + 스킬. [Oh My Pi](../integrations/omp/) |
| **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) 참고. |
@@ -812,39 +837,19 @@ agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Curso
| **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`에 객체가 아닌 배열 형태를 사용합니다. |
+| **Continue.dev** | `~/.continue/config.yaml` (권장) 또는 `config.json` (레거시) | `agentmemory connect continue`는 설정이 없으면 `config.yaml`을 만들고 기존 `config.json`은 수정합니다. 기존 YAML은 주석과 앵커를 보존하기 위해 변경하지 않고 `mcpServers:` 아래에 붙일 블록을 출력합니다. 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` 블록을 작성합니다. 프로젝트 범위 재정의는 `<repo>/.factory/mcp.json`에 둡니다. 네이티브 자동 캡처를 위해서는 `--with-hooks`를 전달하십시오. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh`는 MCP 도구를 활성화합니다. `--with-hooks`를 추가하면 AgentMemory에 포함된 네이티브 캡처 플러그인을 불러옵니다. 별도 플러그인 패키지는 필요하지 않습니다. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | 해당 없음 | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **모든 에이전트 (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`를 통해 이를 직접 호출할 수 있습니다.
-
-```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는 계속 사용할 수 있습니다.
+어떤 언어에서든 [REST API](#api)를, 에이전트에서는 [MCP 도구](#mcp-server)를 사용할 수 있습니다. REST는 JSON과 Bearer 인증을 사용합니다. [저장 및 검색 예제](#validate-a-fresh-install-and-restart-persistence)와 직접 런타임에 연결하는 [Python 예제](../examples/python/)를 참고하세요.
### 소스에서 빌드
@@ -853,91 +858,33 @@ 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` 의존성과 동일한 릴리스입니다. 워커는 해당 엔진의 wire 프로토콜을 사용하고, 0.20.0에서 SDK 표면이 재구성되었기 때문에 둘은 agentmemory 릴리스에서 함께 올라갑니다. 직접 운영하는 엔진이 일치한다고 확신한다면 `AGENTMEMORY_III_VERSION=<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`을 pull합니다). 전체 문서: [iii.dev/docs](https://iii.dev/docs).
+`npm start`는 설치된 CLI와 같은 로컬 서버를 시작합니다. 요구 사항은 [설치](#install)를 참고하세요. API와 뷰어는 `127.0.0.1`에 바인딩됩니다.
### Windows
-agentmemory는 Windows 10/11에서 동작하지만, Node.js 패키지만으로는 충분하지 않습니다. 고정된 iii-engine v0.22.1 런타임도 백그라운드 프로세스로 필요합니다. CLI는 Windows ZIP을 자동으로 압축 해제하지 않으므로, 네이티브 Windows 사용자는 `iii.exe`를 수동으로 설치하거나, WSL2를 사용하거나, Docker Desktop을 선택해야 합니다.
+agentmemory는 Windows 10/11에서 실행됩니다. WSL2는 Linux 경로를 따르며 고정 엔진을 자동 설치할 수 있습니다. 네이티브 Windows에서는 고정된 iii-engine v0.25.0 바이너리를 수동 설치하십시오: [iii v0.25.0 릴리스 페이지](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0)에서 맞는 아카이브를 다운로드하고 checksum을 확인한 뒤 `iii.exe`를 `PATH`에 두십시오(예: `%USERPROFILE%\.local\bin\iii.exe`). CLI는 Windows ZIP을 자동으로 압축 해제하지 않습니다.
-네이티브 Windows에서 자동화된 MCP 연결은 `agentmemory connect copilot-cli`만 지원합니다. Claude Code, Codex, Cursor, 그리고 그 외 모든 네이티브 Windows 에이전트의 경우, [다른 에이전트](#other-agents)에서 수동 MCP 블록을 복사해 해당 에이전트의 Windows 설정에 넣으십시오. WSL에서 `connect`를 실행하는 것은 대상 에이전트도 동일한 WSL 환경에 설치되어 있을 때만 적절합니다. 이는 Windows 호스트 에이전트의 설정을 수정하지 않습니다.
+네이티브 Windows 자동 MCP 연결은 `agentmemory connect copilot-cli`만 지원합니다. 다른 네이티브 Windows 에이전트는 [다른 에이전트](#other-agents)의 수동 MCP 블록을 사용하십시오. 대상 에이전트도 같은 WSL 환경에 설치된 경우에만 WSL에서 `connect`를 실행하십시오.
-**옵션 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 작업이 필요 없다면, 엔진을 완전히 건너뛰십시오:
+**독립형 MCP만 사용(엔진 없음).** REST API, 뷰어 또는 런타임 서비스 없이 MCP 도구만 필요한 경우:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>`을 사용하십시오 |
-| 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`으로 가져옵니다.
+`agentmemory doctor`를 실행하거나 `--verbose`로 재시작하세요. 기본 포트가 사용 중이면 `--port <N>` 또는 `--instance <N>`을 지정하세요. 호환성과 복구는 [업그레이드 가이드](../docs/upgrades/iii-0.25.md)를 참고하세요.
---
<h2 id="deploy">배포</h2>
-매니지드 호스트를 위한 원클릭 템플릿입니다. 각 템플릿은 npm에서
-`@agentmemory/agentmemory`를 가져오고 공식 `iiidev/iii` Docker Hub
-이미지에서 iii 엔진 바이너리를 복사해 넣는 자체 완결형 Dockerfile을
-제공합니다. 사전 빌드된 agentmemory 이미지는 필요 없습니다. 영구
-스토리지는 `/data`에 마운트됩니다. 첫 부팅 진입점은 npm에 번들된
-iii 설정(`127.0.0.1`에 바인딩)을 `0.0.0.0`에 바인딩하고 절대 `/data`
-경로를 사용하는 배포 전용 설정으로 덮어쓰고, HMAC 시크릿을 생성한
-다음, `gosu`를 통해 `root`에서 `node`로 권한을 낮춘 뒤 agentmemory
-CLI를 exec합니다.
+Docker Compose 또는 아래 플랫폼 템플릿으로 직접 호스팅할 수 있습니다. 메모리와 자격 증명은 `/data` 볼륨에 저장됩니다. 업그레이드할 때 백업하고 같은 볼륨을 재사용하세요. 인증, 네트워크, 이전은 [배포 가이드](../deploy/README.md)를 참고하세요.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Render의 원클릭 배포 버튼은 저장소 루트에 `render.yaml`이 있어야 하는데, 이는 의도적으로 깨끗하게 비워 두었습니다. [`deploy/render/`](.././deploy/render/README.md)에 문서화된 Render Blueprint 흐름을 사용해 저장소 내 blueprint를 수동으로 지정하십시오.
@@ -955,28 +902,26 @@ Render의 원클릭 배포 버튼은 저장소 루트에 `render.yaml`이 있어
통해 자신의 VPS에 셀프 호스팅합니다. 동일한 Docker
Compose 스택을 사용하며, 호스트와 데이터를 직접 소유합니다.
-`3111` 포트만 게시됩니다. `3113`의 뷰어는 컨테이너 내부에서
-loopback에 바인딩된 채로 유지됩니다. 각 템플릿의 README는 그곳에
-도달하기 위한 SSH 터널 패턴을 문서화합니다.
+REST는 포트 `3111`, 뷰어는 `3113`을 사용합니다. 비공개로 유지하거나 인증과 TLS로 보호하세요. 플랫폼별 노출 설정과 [기존 Docker 이전](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)은 배포 가이드를 참고하세요.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="왜 agentmemory인가" height="32" /></picture></h2>
-모든 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버리고, 새 세션이 시작될 때마다 사용자가 스택을 다시 설명해야 합니다. agentmemory는 백그라운드에서 실행되며 이 과정을 없애줍니다.
+프로젝트 지식은 채팅과 지침 파일에 흩어지기 쉽습니다. 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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### 내장 에이전트 메모리와의 비교
@@ -985,7 +930,7 @@ Session 2: "Now add rate limiting"
| | 내장 메모리 (CLAUDE.md) | agentmemory |
|---|---|---|
-| 규모 | 200줄 한도 | 무제한 |
+| 관리 | 수동으로 관리하는 지침 | 색인된 세션 이력과 메모리 |
| 검색 | 모든 것을 컨텍스트에 로드 | BM25 + vector + graph (top-K만) |
| 토큰 비용 | 관측 240개 기준 22K+ | ~1,900 토큰 (92% 감소) |
| 에이전트 간 | 에이전트별 파일 | MCP + REST (모든 에이전트) |
@@ -1011,13 +956,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-Tier 메모리 통합
@@ -1035,6 +980,8 @@ SessionStart hook fires
### 무엇이 캡처되는가
+아래 표는 Claude Code의 훅을 설명합니다. 다른 통합은 호스트가 제공하는 이벤트를 캡처합니다. 공통 훅의 자동 컨텍스트 주입은 `AGENTMEMORY_INJECT_CONTEXT=true`로 활성화하는 선택 기능입니다.
+
| Hook | 캡처 내용 |
|------|----------|
| `SessionStart` | 프로젝트 경로, 세션 ID |
@@ -1051,7 +998,7 @@ SessionStart hook fires
| 기능 | 설명 |
|---|---|
-| **자동 캡처** | 모든 도구 사용이 hook을 통해 기록되며 수동 작업이 필요 없음 |
+| **자동 캡처** | 네이티브 통합이 지원하는 세션 및 도구 이벤트를 기록 |
| **시맨틱 검색** | RRF 융합을 사용하는 BM25 + vector + 지식 그래프 |
| **메모리 진화** | 버전 관리, 대체(supersession), 관계 그래프 |
| **리콜 위생** | 대체된 메모리 버전은 검색 인덱스에서 제외되며, KV의 버전 체인이 전체 기록을 보존함 |
@@ -1252,7 +1199,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="실시간 뷰어" height="32" /></picture></h2>
-포트 `3113`에서 자동으로 시작됩니다. 뷰어는 연결 시 스냅샷 하나를 로드하고(`GET /agentmemory/viewer/snapshot`) 이후에는 실시간 스트림 이벤트를 적용합니다: 새 메모리, lesson, 관측, 감사 항목, 그래프 변경, health 업데이트가 폴링이나 페이지 새로고침 없이 나타납니다. 그 외의 요청은 클릭한 액션, "더 보기" 페이지, 검색뿐입니다. 스트림이 끊기면 뷰어는 자신의 숫자가 얼마나 오래되었는지 보여주고, 백오프로 재연결한 다음 스냅샷 하나로부터 다시 동기화합니다.
+뷰어는 `3113` 포트에서 자동으로 시작합니다. 연결 시 snapshot 하나(`GET /agentmemory/viewer/snapshot`)를 불러온 뒤 REST 워커의 `/agentmemory/viewer/events`에서 SSE로 실시간 이벤트를 적용합니다. 새 메모리, lesson, observation, audit entry, 그래프 변경과 health 업데이트가 polling이나 페이지 새로고침 없이 표시됩니다.
- **4개 그룹에 걸친 탭 12개**, 실시간 카운트, 딥링크(`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#health/consolidation`), 키보드 단축키, 모바일 메뉴를 제공합니다.
- **Memories:** 서버 측 검색, 프로젝트·에이전트·유형별 필터, 버전 체인과 단어 diff가 있는 상세 패널, 출처 링크, id·MCP 호출·curl 명령 복사 버튼, 수정(새 버전), 확인 후 forget, 일괄 forget, JSON 내보내기.
@@ -1269,187 +1216,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-`:3113`의 뷰어는 에이전트가 **기억한** 것을 보여줍니다. [iii console](https://iii.dev/docs/console)은 에이전트가 **한** 일을 보여줍니다: 모든 메모리 작업이 OpenTelemetry 트레이스로, 모든 KV 항목이 편집 가능하게, 모든 함수가 호출 가능하게, 모든 스트림이 탭 가능하게 나타납니다. 같은 메모리를 바라보는 두 개의 창입니다. 하나는 제품 형태이고, 하나는 엔진 형태입니다.
-
-`memory_smart_search`가 발화하는 모습을 지켜보고, BM25 스캔 → 임베딩 조회 → RRF 융합 → reranker를 waterfall로 확인하십시오. KV 브라우저에서 멈춰 있는 통합(consolidation) 타이머를 수정하십시오. 수정된 payload로 `PostToolUse` hook을 재생하십시오. WebSocket 스트림을 고정해 놓고 관측이 실시간으로 쌓이는 것을 지켜보십시오.
-
-agentmemory는 이것을 무료로 제공합니다. 모든 함수 호출과 트리거가 iii를 통해 발화하기 때문이며, 커스텀으로 만든 것도 계측해야 할 것도 없습니다.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers 페이지: 실시간 함수 개수와 런타임 메타데이터를 포함해 agentmemory 인스턴스를 비롯한 연결된 워커들" width="720" />
- <br/>
- <em>Workers 페이지: agentmemory 자신을 포함해 연결된 모든 워커를, PID, 함수 개수, 런타임, 마지막 접속 시각과 함께 보여줍니다.</em>
-</p>
-
-**이미 설치되어 있습니다.** 콘솔은 고정된 `iii` 엔진(0.22+)과 함께 제공되며, 별도로 설치할 것이 없습니다. 첫 실행 시 엔진 옆에 콘솔 바이너리를 다운로드합니다.
-
-**agentmemory와 함께 실행하기:**
-
-```bash
-agentmemory console
-```
-
-이 명령은 고정된 엔진의 `iii console`을 agentmemory가 해석한 포트(REST, 스트림, 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** | 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`) 모든 워커, 트리거, 스트림에 대한 인터랙티브 아키텍처 그래프입니다. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console 트레이스 waterfall 뷰, span별 소요 시간을 보여줌" width="720" />
- <br/>
- <em>Traces: 모든 메모리 작업에 대한 waterfall / flame / 서비스별 분석.</em>
-</p>
-
-**트레이스는 이미 켜져 있습니다:**
-
-`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의 observability 문서에 따라 collector 엔드포인트를 설정하십시오.
-
-> **주의:** 콘솔 자체에는 인증이 적용되지 않습니다. `127.0.0.1`(기본값)에 바인딩된 상태를 유지하고, 절대로 공개적으로 노출하지 마십시오.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory는 **이미 실행 중인 [iii](https://iii.dev) 인스턴스**입니다. 세 가지 프리미티브(worker, function, trigger)가 런타임을 구성합니다. KV 상태, 스트림, 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 워커 레지스트리](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
-```
-
-| Worker | 추가되는 것 |
-|---|---|
-| [`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:<scope>`, `stream:<name>:<group>`)는 고정되어 있으므로, 동일한 데이터베이스를 가리키는 두 개의 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가 메모리 한도에 도달하면 조용히 메모리를 버립니다.
-
-네이티브(비 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을 마운트된 파일 밖에 유지합니다.
-
-렌더링된 설정은 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_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 Trigger |
-| SQLite / Postgres + pgvector | iii KV State + 인메모리 벡터 인덱스 |
-| SSE / Socket.io | iii Stream (WebSocket) |
-| pm2 / systemd | iii 엔진의 워커 감독 |
-| Prometheus / Grafana | iii OTEL + health 모니터 |
-| 커스텀 플러그인 시스템 | `iii worker add <name>` |
-
-**소스 파일 250개 · LOC ~55,000줄 · 테스트 3,400+개 · 함수 324개 · KV 스코프 67개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="설정" height="32" /></picture></h2>
### LLM 프로바이더
@@ -1467,6 +1233,8 @@ agentmemory는 환경에서 프로바이더를 자동으로 감지합니다. 프
| **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=<your model>` | OpenAI API와 호환되는 모든 것. 비용 없이 자신의 하드웨어에서 실행됩니다. 아래의 [로컬 모델](#local-models-ollama--lm-studio--vllm)을 참고하십시오. |
| Claude 구독 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in 전용입니다. `@anthropic-ai/claude-agent-sdk` 세션을 생성하는데, 과거 무한한 Stop-hook 재귀를 일으킨 적이 있어 더 이상 기본값이 아닙니다. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 로컬 모델 (Ollama / LM Studio / vLLM)
agentmemory는 OpenAI API와 호환되는 모든 서버와 통신하므로, `/v1/chat/completions`를 노출하는 것이라면 코드 변경 없이 동작합니다. 유료 키도, 클라우드도, rate limit도 없습니다. 모든 것이 사용자의 하드웨어에서 실행됩니다.
@@ -1516,24 +1284,9 @@ reasoning 계열 모델(`<think>` 블록을 사용하는 `o1` 스타일)은 `con
### 비용을 고려한 모델 선택
-프로바이더와 `AGENTMEMORY_AUTO_COMPRESS=true`가 모두 설정되어 LLM이 작성하는 백그라운드 압축이 활성화되면, 이는 모든 관측에 대해 실행되므로 모델 선택이 월간 비용을 상당히 바꿉니다. 캡처된 워크로드 데이터: 요청 635개 / 토큰 888K / 활성 사용 35시간을 2026-05-23 가격 기준 세 가지 OpenRouter 모델에 대해 실행한 결과입니다.
-
-| Tier | 모델 | 입력 / 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 | 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 (추정) | 플래그십급 모델. 압축 작업에는 과도한 지출. |
-
-측정된 행은 캡처된 실행에서 나온 것이며, (추정) 행은 동일한 토큰 조합을 각 모델의 정가에 맞춰 환산한 것입니다.
+키 없이 캡처와 키워드 검색부터 사용할 수 있습니다. `EMBEDDING_PROVIDER=local`은 최초 모델 다운로드 후 기기에서 의미 검색을 제공합니다. LLM 압축에는 프로바이더와 `AGENTMEMORY_AUTO_COMPRESS=true`가 필요하며 관측마다 요청할 수 있으므로 현재 요금을 확인하세요.
-`OPENROUTER_MODEL`이 premium 등급 패턴과 일치하면 agentmemory는 런타임 경고를 출력합니다. 충분히 알고 선택했다면 `AGENTMEMORY_SUPPRESS_COST_WARNING=1`을 설정해 끌 수 있습니다.
-
-메모리 작업에서의 품질 대 비용 트레이드오프: 압축은 품질 기준이 비교적 느슨한 요약 작업입니다(사용자가 아니라 에이전트가 요약을 다시 읽습니다). 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/).
+`agentmemory status` / http://localhost:3113
### 멀티 에이전트 메모리 (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1316,24 @@ SDK / REST 계층에서의 호출별 재정의: 모든 변형 엔드포인트(`/
### 포트
-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`, 또는 보고되는 URL을 위한 `AGENTMEMORY_VIEWER_URL` |
-| `49134` | iii-engine | WebSocket. 워커가 이곳에 등록되고 OTel 텔레메트리가 이를 통해 흐름 | `III_ENGINE_PORT` 또는 `III_ENGINE_URL` |
-
-`--port <N>`은 REST 앵커를 변경하고, 위의 대응하는 명시적 포트나 URL이 설정되지 않은 경우에만 스트림을 `N+1`, 뷰어를 `N+2`, 엔진 WebSocket을 `N+46023`으로 파생시킵니다. 이는 독립된 라이프사이클 네임스페이스를 만들지 않습니다. 두 번째 데몬에는 `--instance 1`을 사용하십시오. 앵커 3211을 사용하며 기본값은 `3211/3212/3213/49234`이고, 별도의 `instance-1` 데이터 및 라이프사이클 디렉터리를 받습니다. 인스턴스 1부터 50까지 동일한 패턴을 따릅니다.
+API와 뷰어는 기본적으로 루프백에 바인딩됩니다.
-고정된 엔진은 `--no-update-check`로 시작됩니다(부팅 시 GitHub에 대한 업데이트나 보안 권고 조회 없음) 그리고 iii의 익명 사용 텔레메트리가 꺼진 상태로 시작됩니다: agentmemory는 변수를 직접 export하지 않는 한 자신이 생성하는 엔진에 대해 `III_TELEMETRY_ENABLED=false`를 설정하며, 번들된 compose 파일도 동일하게 동작합니다.
+| Port | API / 뷰어 | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | 뷰어 | `III_VIEWER_PORT` |
-크래시 이후에도 포트가 바인딩된 채로 남아 있을 때 오래된 프로세스를 정리하는 방법:
+`--port <N>`은 API 포트를 설정하며 뷰어 기본값은 `N+2`입니다. `--instance N`으로 별도 인스턴스를 실행합니다. 내부 리스너는 비공개로 유지하세요. 외부 노출과 [기존 Docker 이전](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)은 배포 가이드를 따르세요.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### 저장소 backend: file (기본값) 또는 Redis
-`agentmemory stop`은 정상적인 네이티브 종료 시 워커와 엔진 pidfile을 모두 깔끔하게 회수합니다. Docker 모드에서는 네이티브 워커를 flush하고, 정확히 검증된 엔진 컨테이너를 중지하며, 무손실 재시작을 위해 컨테이너와 그 `/data` 마운트를 모두 보존합니다. 다음 시작은 동일한 컨테이너를 검증하고 재사용합니다. Docker 기반 제거에는 `agentmemory remove --keep-data`가 필요합니다: 검증된 컨테이너, 그 데이터 마운트, 이를 복구하는 데 필요한 라이프사이클 기록은 보존하면서 agentmemory가 공유로 관리하는 파일만 제거합니다. 파괴적인 Docker 데이터 삭제는 백업 이후 운영자에게 의도적으로 맡겨져 있습니다. CLI는 또한 `--force`가 전달되지 않는 한 Docker나 VM 포트 점유자(Docker backend, vpnkit, colima)를 네이티브 엔진으로 채택하거나 시그널을 보내는 것을 거부합니다. 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
+별도 데이터베이스 서비스 불필요. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. 백엔드를 바꿔도 기존 메모리가 자동으로 복사되지는 않습니다. [데이터 저장](../docs/reliability/state-storage.md).
### 설정 파일
-agentmemory 런타임 설정은 매 셸에서 변수를 export하는 대신 `~/.agentmemory/.env`에 두십시오. 뷰어가 `export ANTHROPIC_API_KEY=...`와 같은 설정 힌트를 보여주면, `export` 접두사 없이 `ANTHROPIC_API_KEY=...`로 이 파일에 복사한 다음 agentmemory를 재시작하십시오.
+각 shell에서 변수를 export하는 대신 agentmemory 런타임 설정을 `~/.agentmemory/.env`에 두십시오. viewer가 `export ANTHROPIC_API_KEY=...` 같은 안내를 표시하면 `export` 접두사를 제외하고 파일에 복사한 뒤 agentmemory를 다시 시작하십시오. 다른 env 파일 경로를 사용하려면 `AGENTMEMORY_ENV_FILE`을 설정하십시오.
-프로세스 환경 변수는 여전히 동작하며 파일 안의 값보다 우선합니다.
+프로세스 환경 변수도 계속 사용할 수 있으며 파일 값보다 우선합니다. CLI 생성 Worker Compose 프로젝트는 Redis 설정 `AGENTMEMORY_STATE_BACKEND`, `AGENTMEMORY_REDIS_URL`을 `state` 워커에 전달합니다.
Windows에서는 동일한 파일이 `%USERPROFILE%\.agentmemory\.env`에 있습니다:
@@ -1622,176 +1360,31 @@ GRAPH_EXTRACTION_ENABLED=true
### 환경 변수
-`~/.agentmemory/.env`를 생성하십시오:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+전체 설정은 [`.env.example`](../.env.example)에 있습니다. 프로바이더, 캡처 필터, 보존 정책, 저장소, 팀 범위를 포함합니다. `AGENTMEMORY_ENV_FILE`로 다른 파일을 선택할 수 있습니다. 변경 후 서버를 재시작하세요. 값이 채워진 `.env`나 Bearer 비밀값은 커밋하지 마세요.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-포트 `3111`의 엔드포인트 143개. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `Authorization: Bearer <secret>`을 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에 `AGENTMEMORY_SECRET`이 명시적으로 설정되어 있어야 합니다.
+포트 `3111`의 엔드포인트 146개. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `Authorization: Bearer <secret>`을 요구하며, 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를 직접 호출하려면:
+인증은 기본적으로 활성화됩니다. `AGENTMEMORY_SECRET`이 없으면 CLI가 처음 시작할 때 임의의 비밀값을 `~/.agentmemory/secret`에 저장하고 선택한 데이터 디렉터리의 `secret`에도 복사합니다. 권한은 `0600`입니다. 번들 클라이언트는 로컬 연결 시 이 공통 파일을 우선하며 저장된 비밀값은 루프백 URL에만 보냅니다. 명시적인 `AGENTMEMORY_SECRET`이 우선하고 원격 클라이언트는 환경 변수로 설정해야 합니다. Docker 배포는 자체 비밀값을 생성합니다.
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
@@ -1830,7 +1423,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | 팀과 공유 |
| `GET` | `/agentmemory/audit` | 감사 기록 |
-전체 엔드포인트 목록: [`src/triggers/api.ts`](../src/triggers/api.ts)
+전체 엔드포인트 목록: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1441,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
서버가 다운되었거나, 제때 응답하지 않거나, 5xx를 반환하면, hook은 관측을 로컬 spool 파일 `<data dir>/capture-spool/<host>-<port>.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`를 설정하십시오.
+**그래프 출처 압축.** 기존 출처 데이터의 압축은 기존 scope 전체를 읽으므로 시작 시 보류됩니다. `/agentmemory/status`는 `deferred`를, `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`이면 `off`를 표시합니다. 유지보수 중 아래 수동 압축을 실행하세요. 검색 인덱스 마이그레이션은 별도 작업입니다. [유지보수 가이드](../docs/reliability/graph-index-migration.md)에 따라 `agentmemory graph-index migrate --allow-legacy-scan`을 사용하세요.
수동으로 실행하려면 `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1467,7 @@ npm test # 4,000+ 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을 사용합니다.
+요구 사항은 [설치](#install), 기여 및 릴리스 규칙은 [CONTRIBUTING.md](../CONTRIBUTING.md)를 참고하세요.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="라이선스" height="32" /></picture></h2>
diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.md
index 47bb607b..19ea33c0 100644
--- a/READMEs/README.nb-NO.md
+++ b/READMEs/README.nb-NO.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Kodeagenten din husker alt. Ikke forklar alt på nytt.
- Bygget på <a href="https://github.com/iii-hq/iii">iii-motoren</a>
+ Varig hukommelse på tvers av kodeøkter og agenter.
</strong><br/>
- Persistent hukommelse for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, og enhver MCP-klient.
+ Persistent hukommelse for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, og enhver MCP-klient.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">Hvordan det fungerer</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Drevet av iii</a> &bull;
<a href="#configuration">Konfigurasjon</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory registrerer kodeøkter og gjør beslutninger, rettelser og erfaringer søkbare. Del ett lager mellom agenter, se gjennom lagret innhold og velg hvor mye kontekst modellen mottar.
+
## 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.
+- På macOS/Linux krever automatisk oppsett også `curl`, en POSIX-`sh` og `tar`.
+- Bruk WSL2 på Windows, eller følg [oppsettet for native Windows](#windows).
Den kanoniske kommandoen for en fersk installasjon:
@@ -108,11 +109,11 @@ Den kanoniske kommandoen for en fersk installasjon:
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.
+Velg agenter og en leverandør, eller bruk modus uten nøkkel. Oppsettet skriver konfigurasjonen, starter minneserveren og tilbyr en global installasjon av kommandoen `agentmemory`. `-y` godtar npm-spørsmålet; `@latest` velger gjeldende versjon. LLM-komprimering er valgfritt og krever en leverandør samt `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+API-et er på `http://localhost:3111`, og viewer på `http://localhost:3113`. Begge lytter på loopback som standard. Konfigurasjonen ligger i `~/.agentmemory/.env`; se [datalagring](#data-storage) for plasseringer og separate instanser.
Deretter kan du bevise at gjenkalling fungerer og gi agenten din dens skills:
@@ -127,14 +128,7 @@ 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 <agent>` — 20 adaptere er listet under [Works with every agent](#works-with-every-agent). Full kommandoreferanse under [Quick Start](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Koble til en annen agent med `agentmemory connect <agent>`. Se [integrasjoner](#works-with-every-agent) og [daglige kommandoer](#everyday-commands).
<details>
<summary><strong>Global installasjon / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx cacher per versjon. Tvinge den nyeste med `npx -y @agentmemory/agentmemory@l
</details>
-<details>
-<summary><strong>Kjører allerede din egen iii-engine</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory fungerer med enhver agent som støtter hooks, MCP eller REST API. Al
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>native programtillegg + livssyklus-hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory fungerer med enhver agent som støtter hooks, MCP eller REST API. Al
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>native søk + registrering + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory fungerer med enhver agent som støtter hooks, MCP eller REST API. Al
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>native registrering + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory fungerer med enhver agent som støtter hooks, MCP eller REST API. Al
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>native søk + registrering + skills + Valgfri MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +304,25 @@ agentmemory fungerer med enhver agent som støtter hooks, MCP eller REST API. Al
---
-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.
+<a id="data-storage"></a>
-**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.
+### Datalagring
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Minnene lagres som standard utenfor repoet:
-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 <path>` eller sett `AGENTMEMORY_DATA_DIR`; begge uttrykkelige innstillinger går foran den eldre oppdagelsen:
+| Plattform | Datamappe |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instans 0 gjenbruker en eksisterende `./data/state_store.db`. Velg en annen plassering med `--data-dir <path>` eller `AGENTMEMORY_DATA_DIR`, og behold den ved omstart og oppgradering. `--instance 1` bruker undermappen `instance-1`, API-port `3211` og viewer-port `3213`. Se [lagring og sikkerhetskopiering](../docs/reliability/state-storage.md) for Redis og migrering.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +471,7 @@ Nyeste versjonsnotater: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Eksterne avhengigheter</strong></td>
-<td>Ingen (SQLite + iii-engine)</td>
+<td>Ingen separat databasetjeneste nødvendig</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektor-DB</td>
<td>Flere</td>
@@ -550,14 +545,12 @@ Nyeste versjonsnotater: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory kombinerer registrering fra kodeagenter, søkbar prosjekthistorikk og en lokal viewer. Du kan arbeide uten nøkkel fra første start.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-Kompatibilitet: denne utgivelsen bruker `iii-sdk` 0.22.1 og fastlåser iii-engine v0.22.1.
-
### Prøv det på 30 sekunder
```bash
@@ -572,9 +565,11 @@ npx -y @agentmemory/agentmemory@latest demo
Åpne `http://localhost:3113` for å se hukommelsen bygges opp live.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Validere en fersk installasjon og persistens ved omstart
-Med serveren i gang, valider REST, health, viewer, og den iii-baserte kjøretidsstatusen:
+Kontroller helse, viewer og status mens serveren kjører:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +578,27 @@ 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:
+`status` viser servertilstanden og aktive leverandører og embeddings. Lagre et testminne, og kontroller søket:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Daglige kommandoer
Installasjon og oppsett er beskrevet i [Install](#install) over (den første kjøringen leder deg gjennom det). Til daglig bruk:
@@ -623,7 +625,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Importerte sesjoner vises i Replay-velgeren side om side med native sesjoner. 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.
@@ -635,14 +637,12 @@ Bruk vedlikeholdskommandoen når du med vilje vil oppdatere den lokale kjøretid
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`).
+Kommandoen oppdaterer den lokale kjøretiden og kan oppdatere JavaScript-avhengigheter i gjeldende arbeidsområde. Ta sikkerhetskopi og les [oppgraderingsveiledningen](../docs/upgrades/iii-0.25.md) før du fortsetter.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code uten plugin-installasjon (MCP-frittstående vei)
@@ -703,6 +703,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Legg deretter til det native programtillegget fra en AgentMemory-utsjekking via **Settings → Plugins → Add marketplace**, og last vinduet på nytt. Tillegget gir livssyklusregistrering, prosjekttilknytning, skills og MCP. Aktiver enten tilleggets hooks eller manuelle hooks i `~/.cursor/hooks.json` for å unngå duplikater. [Cursor-veiledning](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Velg kommandoen for verten din. Pi og OMP installerer søk, registrering, offline-gjensending og 17 skills; `--with-mcp` legger til alle verktøyene. Kjør `/reload` i Pi eller start OMP på nytt, og kontroller `/agentmemory-status`. DSH installerer MCP og det medfølgende registreringstillegget; start DSH på nytt etterpå.
+
+Pi støtter også den installerbare pakken `@agentmemory/pi`. [Pi-veiledningen](../integrations/pi/) beskriver lokal installasjon og tilgjengelighet på npm. Bruk én installasjonsmetode per vert.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (lim inn denne prompten)</b></summary>
@@ -749,6 +771,8 @@ Full veiledning: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Andre agenter
Start minneserveren: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +789,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # installer til hver installerte
Dette er **utfyllende** til `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` skriver vanligvis MCP-konfigurasjonen. Hermes, OpenClaw, Pi og Oh My Pi installerer sin native integrasjon og medfølgende skills som standard; MCP legges til med `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` installerer skills for agenter uten medfølgende native skills. Hopp over dette trinnet for Hermes, OpenClaw, Pi og Oh My Pi: koblingene deres installerer allerede disse skillsene.
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.
@@ -790,7 +814,7 @@ agentmemory-oppføringen er **samme MCP-server-blokk** på tvers av alle verter
| 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. |
+| **Cursor (full plugin)** | `.cursor-plugin/` | Legg deretter til det native programtillegget fra en AgentMemory-utsjekking via **Settings → Plugins → Add marketplace**, og last vinduet på nytt. Tillegget gir livssyklusregistrering, prosjekttilknytning, skills og MCP. Aktiver enten tilleggets hooks eller manuelle hooks i `~/.cursor/hooks.json` for å unngå duplikater. [Cursor-veiledning](../integrations/cursor/). |
| **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. |
@@ -804,7 +828,7 @@ agentmemory-oppføringen er **samme MCP-server-blokk** på tvers av alle verter
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | native søk + registrering + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +836,19 @@ agentmemory-oppføringen er **samme MCP-server-blokk** på tvers av alle verter
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (foretrukket) eller `config.json` (eldre) | `agentmemory connect continue` oppretter en manglende `config.yaml` eller endrer eksisterende `config.json`. Hvis YAML-filen finnes, vises blokken for `mcpServers:` slik at kommentarer og ankere bevares. Continue bruker et array, ikke et objekt. |
| **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 `<repo>/.factory/mcp.json`. Send `--with-hooks` for native auto-fangst. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` aktiverer MCP-verktøy. Legg til `--with-hooks` for å laste det native registreringstillegget som følger med AgentMemory. Ingen separat tilleggspakke er nødvendig. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Bruk de [autentiserte REST-eksemplene](#validate-a-fresh-install-and-restart-persistence) for å lagre og søke etter minner fra skript. |
| **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.
+Bruk [REST-API-et](#api) fra ethvert språk eller [MCP-verktøyene](#mcp-server) fra en agent. REST bruker JSON og bearer-autentisering; se [eksemplet på lagring og søk](#validate-a-fresh-install-and-restart-persistence). [Python-eksemplene](../examples/python/) viser direkte integrasjon med kjøretiden.
### Fra kildekode
@@ -853,92 +857,33 @@ 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=<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).
+`npm start` starter samme lokale server som den installerte CLI-en. Kravene står under [Install](#install); API og viewer lytter på `127.0.0.1`.
### 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**
+agentmemory kjører på Windows 10/11. WSL2 følger Linux-stien og kan installere den fastlåste engine-en automatisk. Native Windows krever at den fastlåste iii-engine v0.25.0-binærfilen installeres manuelt; last ned det tilsvarende arkivet fra [iii v0.25.0-utgivelsessiden](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), kontroller kontrollsummen og legg `iii.exe` på `PATH` (for eksempel `%USERPROFILE%\.local\bin\iii.exe`). CLI-en pakker ikke ut Windows-ZIP-filen automatisk.
-```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
-```
+Automatisert native Windows-MCP-tilkobling støtter bare `agentmemory connect copilot-cli`. For andre native Windows-agenter bruker du den manuelle MCP-blokken fra [Andre agenter](#other-agents). Kjør `connect` i WSL bare når målagenten er installert i det samme WSL-miljøet.
-**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:
+**Kun frittstående MCP (uten engine).** Hvis du bare trenger MCP-verktøy og ikke REST-API-et, viewer eller kjøretidstjenester:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Kjør `agentmemory doctor` eller start på nytt med `--verbose`. Bruk `--port <N>` eller `--instance <N>` hvis portene er opptatt. Se [oppgraderingsveiledningen](../docs/upgrades/iii-0.25.md) for kompatibilitet og gjenoppretting.
---
<h2 id="deploy">Deploy</h2>
-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.
+Host tjenesten med Docker Compose eller malene nedenfor. Minner og legitimasjon ligger på `/data`-volumet. Ta sikkerhetskopi og gjenbruk volumet ved oppgraderinger. [Distribusjonsveiledningen](../deploy/README.md) dekker autentisering, nettverk, sikkerhetskopiering og migrering.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
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.
@@ -956,28 +901,26 @@ kostnadsgulv) finnes i [`deploy/`](.././deploy/README.md):
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.
+REST bruker port `3111`; viewer bruker `3113`. Hold dem private eller beskytt dem med autentisering og TLS. Distribusjonsveiledningen forklarer nettverkstilgang og [migrering av eldre Docker-installasjoner](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-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.
+Prosjektkunnskap spres mellom samtaler og instruksjonsfiler. AgentMemory gjør tidligere beslutninger, rettelser og erfaringer søkbare fra agenten du bruker nå.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs innebygd agenthukommelse
@@ -986,7 +929,7 @@ Hver AI-kodeagent leveres med innebygd hukommelse: Claude Code har `MEMORY.md`,
| | Innebygd (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skala | Tak på 200 linjer | Ubegrenset |
+| Vedlikehold | Manuelt vedlikeholdte instruksjoner | Indeksert økthistorikk og minner |
| 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) |
@@ -1012,13 +955,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-nivås hukommelseskonsolidering
@@ -1036,6 +979,8 @@ Minner forfaller over tid (Ebbinghaus-kurven). Ofte brukte minner styrkes. Utdat
### Hva som fanges opp
+Tabellen beskriver Claude Codes hooks. Andre integrasjoner registrerer hendelsene verten tilbyr; se de enkelte veiledningene. Automatisk kontekstinnsetting via delte hooks aktiveres med `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Fanger |
|------|----------|
| `SessionStart` | Prosjektsti, sesjons-ID |
@@ -1052,7 +997,7 @@ Minner forfaller over tid (Ebbinghaus-kurven). Ofte brukte minner styrkes. Utdat
| Egenskap | Beskrivelse |
|---|---|
-| **Automatisk fangst** | Hver verktøybruk registreres via hooks, uten manuell innsats |
+| **Automatisk fangst** | Native integrasjoner registrerer støttede økt- og verktøyhendelser |
| **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 |
@@ -1113,7 +1058,7 @@ Den vanlige npm-installasjonen inkluderer den valgfrie `@huggingface/transformer
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`.
+> **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 koble til en selvhostet server) og sett `AGENTMEMORY_URL=http://localhost:3111`.
### 54 verktøy
@@ -1253,7 +1198,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Real-Time Viewer" height="32" /></picture></h2>
-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.
+Starter automatisk på port `3113`. Viewer laster ett snapshot når den kobler til (`GET /agentmemory/viewer/snapshot`) og bruker deretter SSE på `/agentmemory/viewer/events` via REST-workeren for live-hendelser: 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/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1266,188 +1211,7 @@ Starter automatisk på port `3113`. Viewer laster ett snapshot når den kobler t
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers page: connected workers including agentmemory instances with live function counts and runtime metadata" width="720" />
- <br/>
- <em>Workers-siden: hver tilkoblede worker, inkludert agentmemory selv, med PID, funksjonsantall, runtime, og sist sett.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view showing per-span duration" width="720" />
- <br/>
- <em>Traces: fossefall-/flamme-/tjenesteoppdeling for hver minneoperasjon.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory 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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 kildefiler · ~55,000 LOC · 3,400+ tester · 324 funksjoner · 67 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
+Viewer-serveren bindes til `127.0.0.1` som standard og legger på serverhemmeligheten når den videresender forespørsler til REST-API-en. Ved en binding som ikke er loopback, er HTML-skallet offentlig, men hver proxyforespørsel krever bearer-token; viewer ber om det og lagrer det i session storage. Konfigurer uttrykkelige verts-/opprinnelsestillatelser og TLS før du eksponerer viewer. REST-endepunktet `/agentmemory/viewer` følger de vanlige bearer-token-reglene og omdirigerer nettlesere uten token til viewer-porten. CSP-headere bruker en nonce per svar og deaktiverer inline-håndteringsattributter (`script-src-attr 'none'`).
---
@@ -1468,6 +1232,8 @@ agentmemory oppdager leverandører automatisk fra miljøet ditt. En leverandør
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1517,24 +1283,7 @@ Lokale embeddings leveres som en valgfri avhengighet, men er ikke aktivert som s
### 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/).
+Start uten nøkkel for registrering og nøkkelordsøk. `EMBEDDING_PROVIDER=local` aktiverer lokalt semantisk søk etter første modellnedlasting. LLM-komprimering krever en leverandør og `AGENTMEMORY_AUTO_COMPRESS=true`; den kan sende én forespørsel per observasjon. Kontroller gjeldende priser først. Viewer og `agentmemory status` viser aktive leverandører.
### Hukommelse for flere agenter (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1564,39 +1313,22 @@ Når `AGENT_ID` ikke er satt, forblir hukommelsen uten avgrensning (eldre oppfø
### 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 <N>` 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.
+| Port | Formål | Konfigurasjon |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Opprydding av gjenværende prosesser når porter forblir bundet etter en krasjet kjøring:
+`--port <N>` setter API-porten og som standard viewer til `N+2`. Bruk `--instance N` for en separat instans. Hold interne porter private; les [distribusjonsveiledningen](../deploy/README.md) før du tillater fjerntilgang.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Lagringsbackend: filbasert (standard) vs Redis
-`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.
+Standardlageret bruker filer og krever ingen separat databasetjeneste. Redis er valgfritt med `AGENTMEMORY_STATE_BACKEND=redis` og `AGENTMEMORY_REDIS_URL`. Et backendbytte kopierer ikke minnene. Se [lagring og sikkerhetskopiering](../docs/reliability/state-storage.md) for persistens, Redis-begrensninger og autentisert eksport/import.
### 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.
+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. Sett `AGENTMEMORY_ENV_FILE` for å bruke en annen miljøfil.
-Miljøvariabler i prosessen fungerer fortsatt og går foran verdier i filen.
+Prosessens miljøvariabler har prioritet over filens verdier. Start serveren på nytt etter konfigurasjonsendringer.
På Windows ligger samme fil på `%USERPROFILE%\.agentmemory\.env`:
@@ -1623,179 +1355,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Miljøvariabler
-Opprett `~/.agentmemory/.env`:
+Vanlige innstillinger for `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Den fullstendige referansen er [`.env.example`](../.env.example), med legitimasjon, registreringsfiltre, oppbevaring, lagring, teamavgrensning og tilvalg. `AGENTMEMORY_ENV_FILE` velger en annen fil. Ikke legg en utfylt `.env` eller en bearer-hemmelighet i git.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endepunkter på port `3111`. REST-API-en bindes til `127.0.0.1` som standard. Beskyttede endepunkter krever `Authorization: Bearer <secret>`, og mesh-synkroniseringsendepunkter krever en uttrykkelig satt `AGENTMEMORY_SECRET` på begge sider.
+146 endepunkter på port `3111`. REST-API-en bindes til `127.0.0.1` som standard. Beskyttede endepunkter krever `Authorization: Bearer <secret>`, 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:
+**Autentisering er på som standard.** Hvis `AGENTMEMORY_SECRET` verken er satt i skallet eller i `~/.agentmemory/.env`, oppretter CLI-en en tilfeldig hemmelighet ved første start i `~/.agentmemory/secret` og en kopi kalt `secret` i den valgte datamappen, med filmodus `0600`. Alle medfølgende klienter leser den derfra når de 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 filsystemovervå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 hemmeligheten i miljøet sitt. Docker-basert selvhosting fra repoet og `deploy/`-entrypointene genererer og eksporterer sin egen hemmelighet. Slik kaller du API-et manuelt:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1831,7 +1416,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Del med team |
| `GET` | `/agentmemory/audit` | Revisjonsspor |
-Full endepunktliste: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Full endepunktliste: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1849,19 +1434,19 @@ Mislykkede hendelser prøves på nytt hvert `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_
Når serveren er nede, ikke svarer i tide, eller returnerer en 5xx, legger hooken observasjonen til en lokal mellomlagringsfil, `<data dir>/capture-spool/<host>-<port>.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.
+**Komprimering av grafopprinnelse.** Komprimering av eldre opprinnelsesdata utsettes ved oppstart fordi den leser hele eldre scopes. `/agentmemory/status` viser `deferred`, eller `off` med `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Kjør den manuelle komprimeringen nedenfor under vedlikehold. Migrering av søkeindeksen er separat: bruk `agentmemory graph-index migrate --allow-legacy-scan` som beskrevet i [vedlikeholdsveiledningen](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1875,7 +1460,7 @@ npm test # 4,000+ 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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.nl-NL.md b/READMEs/README.nl-NL.md
index 01d49d34..c5c5438d 100644
--- a/READMEs/README.nl-NL.md
+++ b/READMEs/README.nl-NL.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Je coding agent onthoudt alles. Geen uitleg meer nodig.
- Gebouwd op <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Blijvend geheugen tussen programmeersessies en agents.
</strong><br/>
- Persistent geheugen voor Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, en elke MCP-client.
+ Persistent geheugen voor Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, en elke MCP-client.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">Hoe het werkt</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Config</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory legt programmeersessies vast en maakt beslissingen, oplossingen en lessen doorzoekbaar. Deel één geheugenopslag tussen agents, bekijk wat is opgeslagen en bepaal hoeveel context het model ontvangt.
+
## 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.
+- Op macOS/Linux vereist automatische installatie ook `curl`, een POSIX-`sh` en `tar`.
+- Gebruik op Windows WSL2 of volg de [native Windows-installatie](#windows).
Canonieke opdracht voor een nieuwe installatie:
@@ -108,11 +109,11 @@ Canonieke opdracht voor een nieuwe installatie:
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.
+Kies je agents en een provider, of werk zonder API-sleutel. De setup schrijft de configuratie, start de geheugenserver en biedt een globale installatie voor de opdracht `agentmemory`. `-y` bevestigt de npm-vraag; `@latest` kiest de huidige versie. LLM-compressie is optioneel en vereist een provider en `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+De API staat op `http://localhost:3111` en de viewer op `http://localhost:3113`. Beide luisteren standaard op loopback. De configuratie staat in `~/.agentmemory/.env`; zie [gegevensopslag](#data-storage) voor locaties en afzonderlijke instanties.
Bewijs vervolgens dat recall werkt en geef je agent zijn skills:
@@ -127,14 +128,7 @@ Wil je liever dat een coding agent dit allemaal voor je doet? Geef hem één ins
> 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 <agent>` — er staan 20 adapters vermeld bij [Werkt met elke agent](#works-with-every-agent). Volledige commando-referentie bij [Snelstart](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Verbind een andere agent met `agentmemory connect <agent>`. Zie de [integraties](#works-with-every-agent) en [dagelijkse opdrachten](#everyday-commands).
<details>
<summary><strong>Globale installatie / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx cachet per versie. Forceer de laatste versie met `npx -y @agentmemory/agentm
</details>
-<details>
-<summary><strong>Je draait al je eigen iii engine</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Werkt met elke agent" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. All
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>native plugin + lifecycle-hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. All
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>native zoeken + vastlegging + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. All
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP-server</sub>
+<sub>native vastlegging + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. All
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>native zoeken + vastlegging + skills + Optioneel MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +304,25 @@ agentmemory werkt met elke agent die hooks, MCP of een REST API ondersteunt. All
---
-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.
+<a id="data-storage"></a>
-**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.
+### Gegevensopslag
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Herinneringen worden standaard buiten je repository opgeslagen:
-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 <path>` door of stel je `AGENTMEMORY_DATA_DIR` in; beide expliciete instellingen krijgen voorrang boven legacy-detectie:
+| Platform | Gegevensmap |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instantie 0 hergebruikt een bestaande `./data/state_store.db`. Kies een andere locatie met `--data-dir <path>` of `AGENTMEMORY_DATA_DIR` en behoud die bij herstarts en upgrades. `--instance 1` gebruikt de submap `instance-1`, API-poort `3211` en viewerpoort `3213`. Zie de [handleiding voor opslag en back-ups](../docs/reliability/state-storage.md) voor Redis en migraties.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +471,7 @@ Laatste release notes: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Externe dependencies</strong></td>
-<td>Geen (SQLite + iii-engine)</td>
+<td>Geen afzonderlijke databaseservice nodig</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector-db</td>
<td>Meerdere</td>
@@ -550,14 +545,12 @@ Laatste release notes: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory combineert vastlegging door programmeeragents, doorzoekbare projectgeschiedenis en een lokale viewer. Je kunt vanaf de eerste start zonder sleutel werken.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Snelstart" height="32" /></picture></h2>
-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
@@ -572,9 +565,11 @@ npx -y @agentmemory/agentmemory@latest demo
Open `http://localhost:3113` om het geheugen live te zien opbouwen.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Controleer de gezondheid, viewer en status terwijl de server draait:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +578,27 @@ 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:
+`status` toont de serverstatus en de actieve providers en embeddings. Sla een testherinnering op en controleer de zoekfunctie:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Dagelijkse commando's
Installatie en setup staan hierboven bij [Install](#install) (de eerste run begeleidt je erdoorheen). Dagelijks gebruik:
@@ -623,7 +625,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Geïmporteerde sessies verschijnen in de Replay-kiezer naast de native sessies. 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.
@@ -635,14 +637,12 @@ Gebruik het onderhoudscommando wanneer je bewust je lokale runtime wilt bijwerke
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`).
+Deze opdracht werkt de lokale runtime bij en kan JavaScript-afhankelijkheden in de huidige workspace bijwerken. Maak een back-up en lees de [upgradehandleiding](../docs/upgrades/iii-0.25.md) voordat je verdergaat.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code zonder de plugin-installatie (MCP-standalone pad)
@@ -703,6 +703,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Voeg daarna de native plugin vanuit een AgentMemory-checkout toe via **Settings → Plugins → Add marketplace** en herlaad het venster. De plugin biedt lifecycle-capture, projecttoewijzing, skills en MCP. Activeer de pluginhooks of de handmatige hooks in `~/.cursor/hooks.json` om dubbele vastlegging te voorkomen. [Cursor-handleiding](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Kies de opdracht voor je host. Pi en OMP installeren zoeken, vastlegging, offline opnieuw verzenden en 17 skills; `--with-mcp` voegt alle tools toe. Voer `/reload` uit in Pi of herstart OMP en controleer `/agentmemory-status`. DSH installeert MCP en de meegeleverde capture-plugin; herstart DSH daarna.
+
+Pi ondersteunt ook het installeerbare pakket `@agentmemory/pi`. De [Pi-handleiding](../integrations/pi/) beschrijft lokale installatie en npm-beschikbaarheid. Gebruik één installatiemethode per host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (plak deze prompt)</b></summary>
@@ -765,8 +787,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Dit is **complementair** aan `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` schrijft normaal de MCP-configuratie. Hermes, OpenClaw, Pi en Oh My Pi installeren standaard hun native integratie en meegeleverde skills; MCP is optioneel met `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` installeert skills voor agents zonder meegeleverde native skills. Sla deze stap over voor Hermes, OpenClaw, Pi en Oh My Pi: hun connectors installeren de skills al.
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.
@@ -790,7 +812,7 @@ De agentmemory-entry is hetzelfde **MCP-serverblok** op elke host die de `mcpSer
| 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. |
+| **Cursor (volledige plugin)** | `.cursor-plugin/` | Voeg daarna de native plugin vanuit een AgentMemory-checkout toe via **Settings → Plugins → Add marketplace** en herlaad het venster. De plugin biedt lifecycle-capture, projecttoewijzing, skills en MCP. Activeer de pluginhooks of de handmatige hooks in `~/.cursor/hooks.json` om dubbele vastlegging te voorkomen. [Cursor-handleiding](../integrations/cursor/). |
| **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. |
@@ -804,7 +826,7 @@ De agentmemory-entry is hetzelfde **MCP-serverblok** op elke host die de `mcpSer
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | native zoeken + vastlegging + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +834,19 @@ De agentmemory-entry is hetzelfde **MCP-serverblok** op elke host die de `mcpSer
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (voorkeur) of `config.json` (legacy) | `agentmemory connect continue` maakt een ontbrekende `config.yaml` of wijzigt een bestaande `config.json`. Bij bestaande YAML toont de adapter het blok voor `mcpServers:` zodat comments en anchors behouden blijven. Continue gebruikt een array, geen object. |
| **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 `<repo>/.factory/mcp.json`. Geef `--with-hooks` door voor native auto-capture. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` activeert MCP-tools. Voeg `--with-hooks` toe voor de native registratieplugin die bij AgentMemory wordt geleverd. Er is geen apart pluginpakket nodig. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Gebruik de [geauthenticeerde REST-voorbeelden](#validate-a-fresh-install-and-restart-persistence) om geheugen vanuit scripts op te slaan en te doorzoeken. |
| **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.
+Gebruik de [REST API](#api) vanuit elke taal of de [MCP-tools](#mcp-server) vanuit een agent. REST gebruikt JSON en bearer-authenticatie; zie het [voorbeeld voor opslaan en zoeken](#validate-a-fresh-install-and-restart-persistence). De [Python-voorbeelden](../examples/python/) behandelen directe runtime-integratie.
### Vanuit de bron
@@ -853,91 +855,33 @@ 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=<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).
+`npm start` start dezelfde lokale server als de geïnstalleerde CLI. Vereisten staan onder [Install](#install); API en viewer luisteren op `127.0.0.1`.
### 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**
+agentmemory draait op Windows 10/11. WSL2 volgt het Linux-pad en kan de vastgezette engine automatisch installeren. Native Windows vereist handmatige installatie van de vastgezette iii-engine v0.25.0-binary; download het passende archief van de [iii v0.25.0-releasepagina](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), controleer de checksum en plaats `iii.exe` op `PATH` (bijvoorbeeld `%USERPROFILE%\.local\bin\iii.exe`). De CLI pakt de Windows ZIP niet automatisch uit.
-```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
-```
+Geautomatiseerde MCP-koppeling op native Windows ondersteunt alleen `agentmemory connect copilot-cli`. Gebruik voor andere native Windows-agents het handmatige MCP-blok uit [Other agents](#other-agents). Voer `connect` binnen WSL alleen uit wanneer de doelagent in dezelfde WSL-omgeving is geïnstalleerd.
-**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:
+**Alleen standalone MCP (geen engine).** Als je alleen MCP-tools nodig hebt en de REST API, viewer of runtimeservices niet nodig hebt:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Voer `agentmemory doctor` uit of herstart met `--verbose`. Gebruik `--port <N>` of `--instance <N>` als de poorten bezet zijn. Zie de [upgradehandleiding](../docs/upgrades/iii-0.25.md) voor compatibiliteit en herstel.
---
<h2 id="deploy">Deployment</h2>
-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`).
+Host de dienst zelf met Docker Compose of de onderstaande templates. Geheugen en inloggegevens staan op het `/data`-volume. Maak een back-up en hergebruik dit volume bij upgrades. De [deploymenthandleiding](../deploy/README.md) behandelt authenticatie, netwerktoegang, back-ups en migratie.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
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.
@@ -955,28 +899,26 @@ minimale kosten) staan in [`deploy/`](.././deploy/README.md):
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.
+REST gebruikt poort `3111`; de viewer gebruikt `3113`. Houd ze privé of bescherm ze met authenticatie en TLS. De deploymenthandleiding beschrijft netwerktoegang en [migratie van oudere Docker-installaties](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Waarom agentmemory" height="32" /></picture></h2>
-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.
+Projectkennis raakt verspreid over chats en instructiebestanden. Met AgentMemory kun je eerdere beslissingen, oplossingen en lessen doorzoeken vanuit de agent die je nu gebruikt.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs ingebouwd agentgeheugen
@@ -985,7 +927,7 @@ Elke AI coding agent levert ingebouwd geheugen: Claude Code heeft `MEMORY.md`, C
| | Ingebouwd (CLAUDE.md) | agentmemory |
|---|---|---|
-| Schaal | Limiet van 200 regels | Onbeperkt |
+| Onderhoud | Handmatig bijgehouden instructies | Geïndexeerde sessiegeschiedenis en herinneringen |
| 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) |
@@ -1011,13 +953,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-laagse memory-consolidatie
@@ -1035,6 +977,8 @@ Memories vervagen in de tijd (Ebbinghaus-curve). Vaak opgevraagde memories worde
### Wat er wordt vastgelegd
+Deze tabel beschrijft de Claude Code-hooks. Andere integraties leggen de gebeurtenissen vast die hun host aanbiedt; zie de afzonderlijke handleidingen. Automatische contextinjectie via de gedeelde hooks is optioneel met `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Legt vast |
|------|----------|
| `SessionStart` | Projectpad, session ID |
@@ -1051,7 +995,7 @@ Memories vervagen in de tijd (Ebbinghaus-curve). Vaak opgevraagde memories worde
| Functie | Beschrijving |
|---|---|
-| **Automatische capture** | Elk toolgebruik vastgelegd via hooks, zonder handmatige moeite |
+| **Automatische capture** | Native integraties leggen ondersteunde sessie- en toolgebeurtenissen vast |
| **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 |
@@ -1252,7 +1196,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Realtime viewer" height="32" /></picture></h2>
-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.
+Start automatisch op poort `3113`. De viewer laadt één snapshot bij het verbinden (`GET /agentmemory/viewer/snapshot`) en verwerkt daarna live-events via SSE op `/agentmemory/viewer/events` van de REST-worker: 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/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1209,7 @@ Start automatisch op poort `3113`. De viewer laadt één snapshot bij het verbin
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers-pagina: verbonden workers, inclusief agentmemory-instanties met live functietellingen en runtime-metadata" width="720" />
- <br/>
- <em>Workers-pagina: elke verbonden worker, inclusief agentmemory zelf, met PID, functietelling, runtime en laatst gezien.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace-waterfall-weergave met duur per span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service-breakdown voor elke memory-operatie.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory is **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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 bronbestanden · ~55,000 LOC · 3,400+ tests · 324 functies · 67 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
+De viewer-server bindt standaard aan `127.0.0.1` en voegt het server-secret toe wanneer hij verzoeken doorstuurt naar de REST API. Bij een niet-loopback-bind is de HTML-shell openbaar, maar vereist elk proxyverzoek de bearer-token; de viewer vraagt erom en bewaart deze in session storage. Configureer expliciete host-/origin-allowlists en TLS voordat je de viewer blootstelt. 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 nonce per response en schakelen inline handler-attributen uit (`script-src-attr 'none'`).
---
@@ -1516,24 +1279,7 @@ Lokale embeddings worden als optionele dependency meegeleverd, maar zijn niet st
### 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/).
+Begin zonder sleutel voor vastlegging en zoeken op trefwoorden. `EMBEDDING_PROVIDER=local` activeert lokaal semantisch zoeken na de eerste modeldownload. LLM-compressie vereist een provider en `AGENTMEMORY_AUTO_COMPRESS=true`; dit kan per observatie een verzoek opleveren. Controleer eerst de actuele tarieven. De viewer en `agentmemory status` tonen de actieve providers.
### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1309,22 @@ Wanneer `AGENT_ID` niet is ingesteld, blijft memory unscoped (legacy-gedrag, gee
### 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 <N>` 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.
+| Poort | Doel | Configuratie |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Opruimen van verweesde processen wanneer poorten gebonden blijven na een gecrashte run:
+`--port <N>` stelt de API-poort in en standaard de viewer op `N+2`. Gebruik `--instance N` voor een afzonderlijke instantie. Houd interne poorten privé; lees de [deploymenthandleiding](../deploy/README.md) voordat je externe toegang toestaat.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage-backend: file (standaard) versus Redis
-`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.
+De standaard bestandsopslag vereist geen afzonderlijke databaseservice. Redis is optioneel met `AGENTMEMORY_STATE_BACKEND=redis` en `AGENTMEMORY_REDIS_URL`. Een backendwissel kopieert geen herinneringen. De [handleiding voor opslag en back-ups](../docs/reliability/state-storage.md) behandelt persistentie, Redis-beperkingen en geauthenticeerde export/import.
### 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.
+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. Stel `AGENTMEMORY_ENV_FILE` in om een ander env-bestand te gebruiken.
-Environment-variabelen van het proces werken nog steeds en krijgen voorrang boven waarden in het bestand.
+Procesomgevingsvariabelen hebben voorrang op het bestand. Herstart de server na configuratiewijzigingen.
Op Windows leeft hetzelfde bestand op `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,179 +1351,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Environment-variabelen
-Maak `~/.agentmemory/.env` aan:
+Veelgebruikte opties voor `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+De volledige referentie staat in [`.env.example`](../.env.example), met providergegevens, capture-filters, bewaartermijnen, opslag, teamscope en opties. `AGENTMEMORY_ENV_FILE` selecteert een ander bestand. Commit nooit een ingevulde `.env` of bearer-secret.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints op poort `3111`. De REST API bindt standaard aan `127.0.0.1`. Beschermde endpoints vereisen `Authorization: Bearer <secret>`, en mesh-sync-endpoints vereisen een expliciet ingestelde `AGENTMEMORY_SECRET` op beide peers.
+146 endpoints op poort `3111`. De REST API bindt standaard aan `127.0.0.1`. Beschermde endpoints vereisen `Authorization: Bearer <secret>`, 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:
+**Authenticatie staat standaard aan.** Als `AGENTMEMORY_SECRET` niet in de shell of in `~/.agentmemory/.env` staat, maakt de CLI bij de eerste start een willekeurig secret in `~/.agentmemory/secret` en een kopie met de naam `secret` in de geselecteerde gegevensmap, met bestandsmodus `0600`. Elke gebundelde client leest het daar wanneer die met een lokale server communiceert: de CLI, viewer, hooks onder `plugin/scripts`, MCP-server en `@agentmemory/mcp`-shim, 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 externe clients hebben het secret in hun omgeving nodig. Docker self-host deployments vanuit de repository en de `deploy/`-entrypoints genereren en exporteren hun eigen secret. Zo roep je de API handmatig aan:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1830,7 +1412,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Deel met team |
| `GET` | `/agentmemory/audit` | Audit trail |
-Volledige endpointlijst: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Volledige endpointlijst: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1430,19 @@ Mislukte events worden elke `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) opnie
Wanneer de server down is, niet op tijd antwoordt, of een 5xx teruggeeft, voegt de hook de observatie toe aan een lokaal spool-bestand, `<data dir>/capture-spool/<host>-<port>.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.
+**Graph-provenance compacten.** Het compacten van oude provenance wordt bij het opstarten uitgesteld omdat het volledige oude scopes leest. `/agentmemory/status` meldt `deferred`, of `off` bij `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Voer het onderstaande handmatige compacten uit tijdens onderhoud. De migratie van de zoekindex staat hier los van: gebruik `agentmemory graph-index migrate --allow-legacy-scan` volgens de [onderhoudsgids](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1456,7 @@ npm test # 4,000+ 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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licentie" height="32" /></picture></h2>
diff --git a/READMEs/README.pl-PL.md b/READMEs/README.pl-PL.md
index 7fcee111..939abce8 100644
--- a/READMEs/README.pl-PL.md
+++ b/READMEs/README.pl-PL.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Twój agent kodujący pamięta wszystko. Koniec z tłumaczeniem wszystkiego od nowa.
- Zbudowany na <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Trwała pamięć między sesjami i agentami kodującymi.
</strong><br/>
- Trwała pamięć dla Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode i każdego klienta MCP.
+ Trwała pamięć dla Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode i każdego klienta MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licencja" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Gwiazdki" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">Jak to działa</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Podgląd</a> &bull;
- <a href="#powered-by-iii">Oparte na iii</a> &bull;
<a href="#configuration">Konfiguracja</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory zapisuje obsługiwane zdarzenia sesji i pozwala wyszukiwać decyzje, poprawki oraz wnioski między agentami. Podgląd umożliwia przeglądanie, edytowanie, eksportowanie i usuwanie wspomnień. Wyszukiwanie słów kluczowych działa bez klucza API; embeddingi dodają wyszukiwanie semantyczne.
+
## 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.
+- macOS/Linux wymagają też `curl`, powłoki POSIX `sh` i `tar` do automatycznej konfiguracji środowiska.
+- W Windows użyj WSL2 lub [instrukcji natywnej instalacji](#windows).
Kanoniczna komenda do świeżej instalacji:
@@ -108,11 +109,11 @@ Kanoniczna komenda do świeżej instalacji:
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`.
+Wybierz agentów oraz dostawcę lub tryb bez klucza. Konfigurator zapisuje ustawienia, uruchamia serwer pamięci i proponuje globalną instalację komendy `agentmemory`. `-y` akceptuje monit npm, a `@latest` wybiera bieżące wydanie. Kompresja przez LLM wymaga dostawcy i `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 <path>` 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.
+API działa pod `http://localhost:3111`, a podgląd pod `http://localhost:3113`. Domyślnie oba nasłuchują tylko lokalnie. Konfiguracja jest w `~/.agentmemory/.env`; [przechowywanie danych](#data-storage) opisuje lokalizacje pamięci i osobne instancje.
Następnie udowodnij, że przywołanie działa, i daj swojemu agentowi jego skille:
@@ -127,14 +128,7 @@ 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 <agent>` — 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).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Podłącz kolejnego agenta przez `agentmemory connect <agent>`. Zobacz [integracje](#works-with-every-agent) i [codzienne komendy](#everyday-commands).
<details>
<summary><strong>Instalacja globalna / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx buforuje dane w podziale na wersje. Wymuś najnowszą wersję za pomocą `np
</details>
-<details>
-<summary><strong>Masz już uruchomiony własny silnik iii</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Współpracuje z każdym agentem" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin natywny + 7 hooków + MCP</sub>
+<sub>plugin natywny + hooki cyklu życia + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin natywny + MCP</sub>
+<sub>natywne przywoływanie + przechwytywanie + skille</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>serwer MCP</sub>
+<sub>natywne przechwytywanie + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>natywne przywoływanie + przechwytywanie + skille + opcjonalne MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +304,26 @@ agentmemory współpracuje z każdym agentem, który wspiera hooki, MCP lub REST
---
-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.
+<a id="data-storage"></a>
-**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.
+### Przechowywanie danych
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Wspomnienia domyślnie trafiają poza repozytorium:
-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 <path>` lub ustaw `AGENTMEMORY_DATA_DIR`; każde z tych wyraźnych ustawień ma pierwszeństwo przed wykrywaniem starszej ścieżki:
+| Platforma | Katalog danych |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instancja 0 wykorzystuje istniejący `./data/state_store.db`. Wybierz inny katalog przez `--data-dir <path>` lub `AGENTMEMORY_DATA_DIR`. Przy restarcie i aktualizacji zachowaj ten sam katalog.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` używa podkatalogu `instance-1`, portu API `3211` i podglądu `3213`. Redis i migrację opisuje [przewodnik przechowywania i kopii zapasowych](../docs/reliability/state-storage.md).
Najnowsze informacje o wydaniach: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +473,7 @@ Najnowsze informacje o wydaniach: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Zależności zewnętrzne</strong></td>
-<td>Brak (SQLite + iii-engine)</td>
+<td>Nie wymaga osobnej usługi bazy danych</td>
<td>Qdrant / pgvector</td>
<td>Postgres + baza wektorowa</td>
<td>Wiele</td>
@@ -550,14 +547,12 @@ Najnowsze informacje o wydaniach: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory łączy przechwytywanie sesji, przeszukiwalną historię projektu i lokalny podgląd, z trybem bez klucza od pierwszego uruchomienia.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Szybki start" height="32" /></picture></h2>
-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
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Otwórz `http://localhost:3113`, aby na żywo obserwować budowanie pamięci.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Gdy serwer działa, sprawdź stan i podgląd:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` pokazuje stan serwera, dostawców, tryb embeddingów, dostarczanie obserwacji i odzyskiwanie. Chronione żądania REST wymagają sekretu serwera. Użyj własnego `AGENTMEMORY_SECRET`, jeśli jest ustawiony; w przeciwnym razie odczytaj wygenerowany lokalny sekret:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Codzienne komendy
Instalacja i konfiguracja są opisane w sekcji [Install](#install) powyżej (pierwsze uruchomienie przeprowadzi cię przez ten proces). Na co dzień:
@@ -604,6 +608,9 @@ Instalacja i konfiguracja są opisane w sekcji [Install](#install) powyżej (pie
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Importowane sesje pojawiają się w Replay obok natywnych. Transkrypty są indeksowane i oznaczane kanałem `import`; przetwarzanie sesji może też tworzyć kryształy i lekcje.
> **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.
@@ -635,14 +642,12 @@ Użyj komendy utrzymania, gdy chcesz celowo zaktualizować swoje lokalne środow
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`).
+Komenda aktualizuje lokalne środowisko i może zmienić zależności JavaScript w bieżącym katalogu roboczym. Zrób kopię danych i przeczytaj [przewodnik aktualizacji](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code bez instalacji pluginu (ścieżka samodzielnego MCP)
@@ -703,6 +708,30 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Następnie w **Settings → Plugins → Add marketplace** wybierz katalog agentmemory zawierający `.cursor-plugin/plugin.json`, włącz plugin **agentmemory** i przeładuj okno. Plugin udostępnia przechwytywanie cyklu życia, przypisanie projektu na podstawie workspace, skille i MCP. Włącz hooki pluginu albo ręczne hooki w `~/.cursor/hooks.json`, aby uniknąć podwójnego zapisu.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Wybierz komendę dla swojego hosta. Pi i OMP instalują natywne przywoływanie, przechwytywanie, odtwarzanie offline i skille; `--with-mcp` dodaje pełny zestaw narzędzi. W Pi uruchom `/reload`, OMP zrestartuj, a potem sprawdź `/agentmemory-status`. DSH instaluje MCP i dołączony plugin przechwytujący; po podłączeniu zrestartuj DSH.
+
+Pi obsługuje też instalowalny pakiet `@agentmemory/pi`. Instalację lokalną i dostępność npm opisuje [przewodnik Pi](../integrations/pi/). Używaj jednej metody instalacji na hosta.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (wklej ten prompt)</b></summary>
@@ -749,6 +778,8 @@ Pełny przewodnik: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Inni agenci
Uruchom serwer pamięci: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +796,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Jest to **uzupełnienie** dla `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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ć.
+- `agentmemory connect <agent>` zwykle zapisuje konfigurację MCP. Hermes, OpenClaw, Pi i Oh My Pi domyślnie instalują natywną integrację i skille; MCP włącza `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` instaluje skille dla agentów bez dołączonych natywnych skilli. Pomiń ten krok dla Hermes, OpenClaw, Pi i Oh My Pi; ich konektory już instalują skille.
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.
@@ -790,7 +821,7 @@ Wpis agentmemory to **ten sam blok serwera MCP** we wszystkich hostach, które u
| 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. |
+| **Cursor (pełny plugin)** | `.cursor-plugin/` | Plugin zapewnia hooki cyklu życia, rozpoznawanie workspace, skille i MCP w Cursor IDE oraz `cursor-agent`. Zobacz [konfigurację Cursor](#cursor). |
| **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. |
@@ -804,7 +835,8 @@ Wpis agentmemory to **ten sam blok serwera MCP** we wszystkich hostach, które u
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. natywne przywoływanie + przechwytywanie + skille. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. natywne przywoływanie + przechwytywanie + skille. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +844,19 @@ Wpis agentmemory to **ten sam blok serwera MCP** we wszystkich hostach, które u
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferowane) lub `config.json` (starsze) | `agentmemory connect continue` tworzy `config.yaml`, jeśli konfiguracji nie ma, lub modyfikuje istniejący `config.json`. Dla istniejącego YAML wypisuje blok do wklejenia pod `mcpServers:`, zachowując komentarze i kotwice. Continue używa tablicy, nie obiektu. |
| **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 `<repo>/.factory/mcp.json`. Podaj `--with-hooks`, aby uzyskać natywne auto-przechwytywanie. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` włącza narzędzia MCP. Dodaj `--with-hooks`, aby załadować natywną wtyczkę rejestrowania dołączoną do AgentMemory. Osobny pakiet wtyczki nie jest potrzebny. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/d | Do zapisu i wyszukiwania ze skryptów użyj [uwierzytelnionych przykładów REST](#validate-a-fresh-install-and-restart-persistence). |
| **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.
+Korzystaj z [REST API](#api) w dowolnym języku lub z [narzędzi MCP](#mcp-server) w agencie. REST używa JSON i uwierzytelniania bearer; zobacz [przykład zapisu i wyszukiwania](#validate-a-fresh-install-and-restart-persistence). Bezpośrednią integrację środowiska pokazują [przykłady Python](../examples/python/).
### Ze źródeł
@@ -853,91 +865,33 @@ 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=<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).
+`npm start` uruchamia ten sam lokalny serwer co zainstalowane CLI. Wymagania są w sekcji [Instalacja](#install); API i podgląd nasłuchują na `127.0.0.1`.
### 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**
+agentmemory działa w Windows 10/11. WSL2 korzysta ze ścieżki linuksowej i może automatycznie zainstalować przypięty silnik. Natywny Windows wymaga ręcznie zainstalowanego przypiętego pliku binarnego iii-engine v0.25.0; pobierz pasujące archiwum ze [strony wydania iii 0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), zweryfikuj sumę kontrolną i umieść `iii.exe` w `PATH` (na przykład `%USERPROFILE%\.local\bin\iii.exe`). CLI nie wypakowuje automatycznie archiwum ZIP dla Windows.
-```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
-```
+Zautomatyzowane podłączanie MCP w natywnym Windows obsługuje tylko `agentmemory connect copilot-cli`. Dla pozostałych natywnych agentów Windows użyj ręcznego bloku MCP z sekcji [Inni agenci](#other-agents). Uruchamiaj `connect` w WSL tylko wtedy, gdy docelowy agent jest zainstalowany w tym samym środowisku WSL.
-**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:
+**Tylko samodzielny MCP (bez silnika).** Jeśli potrzebujesz wyłącznie narzędzi MCP, bez REST API, podglądu ani usług runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Uruchom `agentmemory doctor` lub zrestartuj z `--verbose`. Gdy porty są zajęte, użyj `--port <N>` albo `--instance <N>`. Zgodność i odzyskiwanie opisuje [przewodnik aktualizacji](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Wdrożenie</h2>
-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.
+Własne wdrożenie uruchom przez Docker Compose lub poniższe szablony. Pamięć i dane uwierzytelniające są na wolumenie `/data`; wykonaj kopię i użyj go ponownie przy aktualizacji. Uwierzytelnianie, sieć, kopie i migrację opisuje [przewodnik wdrożenia](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Wdróż na fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Wdróż na Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Wdróż na fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Wdróż na Railway" /></a>
</p>
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.
@@ -955,29 +909,13 @@ minimalne koszty) znajdują się w [`deploy/`](.././deploy/README.md):
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ć.
+REST używa `3111`, a podgląd `3113`. Zachowaj je w sieci prywatnej lub zabezpiecz uwierzytelnianiem i TLS. Ustawienia platform i [migrację starszego Dockera](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) opisuje przewodnik wdrożenia.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Dlaczego agentmemory" height="32" /></picture></h2>
-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.
-```
+Wiedza o projekcie rozprasza się między rozmowami i plikami instrukcji. AgentMemory pozwala wyszukiwać wcześniejsze decyzje, poprawki i lekcje w aktualnie używanym agencie.
### agentmemory kontra wbudowana pamięć agenta
@@ -985,7 +923,7 @@ Każdy kodujący agent AI ma wbudowaną pamięć: Claude Code ma `MEMORY.md`, Cu
| | Wbudowana (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skala | limit 200 linii | Bez limitu |
+| Utrzymanie | Ręcznie zarządzane instrukcje | Indeksowana historia sesji i wspomnienia |
| 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) |
@@ -1011,13 +949,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-poziomowa konsolidacja pamięci
@@ -1035,6 +973,8 @@ Wspomnienia zanikają z czasem (krzywa Ebbinghausa). Często używane wspomnieni
### Co jest przechwytywane
+Tabela opisuje hooki Claude Code. Pozostałe integracje przechwytują zdarzenia udostępniane przez hosta. Automatyczne wstrzykiwanie kontekstu przez wspólne hooki jest opcjonalne: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Przechwytuje |
|------|----------|
| `SessionStart` | Ścieżkę projektu, ID sesji |
@@ -1051,7 +991,7 @@ Wspomnienia zanikają z czasem (krzywa Ebbinghausa). Często używane wspomnieni
| Możliwość | Opis |
|---|---|
-| **Automatyczne przechwytywanie** | Każde użycie narzędzia zapisywane przez hooki, bez pracy ręcznej |
+| **Automatyczne przechwytywanie** | Obsługiwane zdarzenia sesji i narzędzi zapisywane przez natywne integracje |
| **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ę |
@@ -1252,7 +1192,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Podgląd w czasie rzeczywistym" height="32" /></picture></h2>
-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.
+Uruchamia się automatycznie na porcie `3113`. Podgląd wczytuje jedną migawkę po połączeniu (`GET /agentmemory/viewer/snapshot`), a następnie stosuje zdarzenia na żywo przesyłane przez SSE pod `/agentmemory/viewer/events` przez workera REST: nowe wspomnienia, lekcje, obserwacje, wpisy audytu, zmiany grafu i aktualizacje stanu pojawiają się bez odpytywania (polling) ani przeładowywania strony. Pozostałe żądania dotyczą klikniętych działań, stron „wczytaj więcej” i wyszukiwania. Po zerwaniu strumienia podgląd pokazuje wiek danych, ponawia połączenie z narastającym odstępem (backoff) i synchronizuje stan na podstawie migawki.
- **12 zakładek w czterech grupach** z licznikami na żywo, głębokimi linkami (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1205,8 @@ Uruchamia się automatycznie na porcie `3113`. Podgląd wczytuje jedną migawkę
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Konsola iii" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Strona Workers konsoli iii: podłączeni workerzy, w tym instancje agentmemory, z licznikami funkcji na żywo i metadanymi środowiska wykonawczego" width="720" />
- <br/>
- <em>Strona Workers: każdy podłączony worker, w tym sam agentmemory, z PID, liczbą funkcji, środowiskiem wykonawczym i czasem ostatniej aktywności.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Widok waterfall traces w konsoli iii pokazujący czas trwania per span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / rozbicie na usługi dla każdej operacji pamięci.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Oparte na iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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`.
+Serwer podglądu domyślnie wiąże się z `127.0.0.1` i dołącza sekret serwera, gdy przekazuje żądania do REST API. Przy nasłuchiwaniu poza loopbackiem powłoka HTML pozostaje publiczna, ale każde żądanie proxy wymaga bearer tokenu; podgląd prosi o token i przechowuje go w pamięci sesji przeglądarki. Przed udostępnieniem podglądu skonfiguruj jawne listy dozwolonych hostów i originów oraz TLS. Endpoint REST `/agentmemory/viewer` nadal stosuje zwykłe zasady tokenu bearer i przekierowuje przeglądarki bez tokenu na port podglądu. Nagłówki CSP używają nonce skryptu dla każdej odpowiedzi i wyłączają atrybuty handlerów inline (`script-src-attr 'none'`).
-### 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 <name>` |
-
-**250 pliki źródłowe · ~55,000 LOC · 3,800+ testów · 324 funkcje · 67 zakresów KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfiguracja" height="32" /></picture></h2>
@@ -1466,6 +1226,8 @@ agentmemory automatycznie wykrywa dostawców na podstawie twojego środowiska. D
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1515,24 +1277,7 @@ Lokalne embeddingi są dostarczane jako opcjonalna zależność, ale nie są wł
### 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/).
+Zacznij bez klucza do przechwytywania i wyszukiwania słów kluczowych. `EMBEDDING_PROVIDER=local` uruchamia lokalne wyszukiwanie semantyczne po pobraniu modelu. Kompresja LLM wymaga dostawcy i `AGENTMEMORY_AUTO_COMPRESS=true`; może wysyłać żądanie dla każdej obserwacji, więc sprawdź aktualne ceny dostawcy. Aktywnych dostawców pokazują podgląd i `agentmemory status`.
### Pamięć wieloagentowa (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1562,39 +1307,22 @@ Gdy `AGENT_ID` nie jest ustawione, pamięć pozostaje bez zakresu (zachowanie hi
### 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 | Przeznaczenie | Zmienna środowiskowa |
+|---|---|---|
+| `3111` | REST API, MCP HTTP i zdarzenia podglądu na żywo | `III_REST_PORT` |
+| `3113` | Interfejs podglądu | `III_VIEWER_PORT` |
-`--port <N>` 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.
+`--port <N>` ustawia port REST, a domyślny port podglądu na `N+2`. `--instance N` tworzy osobne środowisko. Wewnętrzne porty muszą pozostać prywatne; przed udostępnieniem przeczytaj [przewodnik wdrożenia](../deploy/README.md).
-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.
+### Magazyn: plik lub Redis
-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 <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.
+Domyślny magazyn plikowy nie wymaga osobnej bazy. Redis jest opcjonalny przez `AGENTMEMORY_STATE_BACKEND=redis` i `AGENTMEMORY_REDIS_URL`. Zmiana backendu nie przenosi pamięci. Trwałość, ograniczenia Redis i uwierzytelniony eksport/import opisuje [przewodnik przechowywania](../docs/reliability/state-storage.md).
### 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.
+Umieść konfigurację runtime agentmemory w `~/.agentmemory/.env`, zamiast eksportować zmienne w każdym shellu. Jeśli podgląd pokazuje wskazówkę konfiguracyjną, taką jak `export ANTHROPIC_API_KEY=...`, skopiuj ją do tego pliku jako `ANTHROPIC_API_KEY=...` bez prefiksu `export`, a następnie zrestartuj agentmemory. Ustaw `AGENTMEMORY_ENV_FILE`, aby wskazać inną ścieżkę pliku env.
-Zmienne środowiska procesu wciąż działają i mają pierwszeństwo przed wartościami z pliku.
+Zmienne środowiska procesu mają pierwszeństwo przed plikiem. Po zmianie konfiguracji zrestartuj serwer.
Na Windows ten sam plik znajduje się w `%USERPROFILE%\.agentmemory\.env`:
@@ -1621,179 +1349,30 @@ GRAPH_EXTRACTION_ENABLED=true
### Zmienne środowiskowe
-Utwórz `~/.agentmemory/.env`:
+Typowe opcje w `~/.agentmemory/.env`. Wstrzykiwanie kontekstu i kompresja są opcjonalne; kompresja wymaga też dostawcy. Tryb `core` ogranicza widoczne narzędzia MCP:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Pełny opis w [`.env.example`](../.env.example) obejmuje dostawców, filtry przechwytywania, retencję, magazyn, zakres zespołu i opcjonalne funkcje. `AGENTMEMORY_ENV_FILE` wybiera inny plik. Nigdy nie commituj wypełnionego `.env` ani sekretu bearer.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpointów na porcie `3111`. REST API domyślnie wiąże się z `127.0.0.1`. Chronione endpointy wymagają `Authorization: Bearer <secret>`, a endpointy synchronizacji mesh wymagają wyraźnie ustawionego `AGENTMEMORY_SECRET` na obu peerach.
+146 endpointów na porcie `3111`. REST API domyślnie wiąże się z `127.0.0.1`. Chronione endpointy wymagają `Authorization: Bearer <secret>`, 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:
+**Autoryzacja jest domyślnie włączona.** Gdy `AGENTMEMORY_SECRET` nie jest ustawiony, CLI przy pierwszym uruchomieniu generuje losowy sekret w `~/.agentmemory/secret` z uprawnieniami `0600` i kopiuje go także do wybranego katalogu danych. Wszystkie dołączone klienty odczytują go stamtąd, gdy łączą się z lokalnym serwerem: CLI, podgląd, hooki w `plugin/scripts`, serwer MCP i shim `@agentmemory/mcp`, konfiguracje tworzone przez `agentmemory connect` oraz dołączone integracje OpenCode, Pi, OpenClaw, Hermes i obserwator systemu plików. Zapisany sekret jest wysyłany tylko na adresy loopback (`localhost`, `127.0.0.0/8`, `::1`). Jawnie ustawione `AGENTMEMORY_SECRET` ma zawsze pierwszeństwo, a zdalni klienci muszą mieć sekret w swoim środowisku. Wdrożenia self-hosted Docker oparte na repozytorium i punkty wejścia `deploy/` generują i eksportują własny sekret. Aby ręcznie wywołać API:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1829,7 +1408,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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)
+Pełna lista endpointów: [Generowana dokumentacja REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1847,19 +1426,19 @@ Nieudane zdarzenia są ponawiane co `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10
Gdy serwer jest wyłączony, nie odpowiada w czasie albo zwraca 5xx, hook dopisuje obserwację do lokalnego pliku spool, `<data dir>/capture-spool/<host>-<port>.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ć.
+**Kompaktowanie pochodzenia grafu.** Kompaktowanie starszych danych pochodzenia jest odkładane przy starcie, ponieważ odczytuje całe starsze zakresy. `/agentmemory/status` zgłasza `deferred` lub `off`, gdy `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Wykonaj opisane poniżej ręczne kompaktowanie podczas konserwacji. Migracja indeksu wyszukiwania jest osobna: użyj `agentmemory graph-index migrate --allow-legacy-scan` zgodnie z [instrukcją konserwacji](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1873,7 +1452,7 @@ npm test # 4,000+ 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.
+Wymagania opisano w sekcji [Instalacja](#install). Zasady współtworzenia i kontrole wydania są w [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licencja" height="32" /></picture></h2>
diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.md
index e5ce727c..775f920f 100644
--- a/READMEs/README.pt-BR.md
+++ b/READMEs/README.pt-BR.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Seu agente de codificação lembra de tudo. Chega de re-explicar.
- Construído sobre <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Memória persistente entre sessões e agentes de programação.
</strong><br/>
- Memória persistente para Claude Code, GitHub Copilot CLI, 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, Oh My Pi, DeepSeek Harness, OpenCode e qualquer cliente MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">Como funciona</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Config</a> &bull;
<a href="#api">API</a>
</p>
---
+O AgentMemory captura sessões de programação e permite pesquisar decisões, correções e aprendizados. Compartilhe um único armazenamento entre agentes, inspecione o conteúdo salvo e escolha quanto contexto chega ao modelo.
+
## Install
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.
+- No macOS/Linux, a configuração automática também precisa de `curl`, um `sh` POSIX e `tar`.
+- No Windows, use WSL2 ou siga a [configuração nativa](#windows).
Comando canônico para instalação do zero:
@@ -108,11 +109,11 @@ Comando canônico para instalação do zero:
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 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.
+Escolha seus agentes e um provedor, ou o modo sem chave. O assistente grava a configuração, inicia o servidor de memória e oferece uma instalação global do comando `agentmemory`. `-y` aceita a confirmação do npm; `@latest` seleciona a versão atual. A compressão por LLM é opcional e exige um provedor e `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+A API fica em `http://localhost:3111` e o visualizador em `http://localhost:3113`. Ambos escutam em loopback por padrão. A configuração fica em `~/.agentmemory/.env`; consulte [armazenamento de dados](#data-storage) para os caminhos e instâncias separadas.
Depois prove que o recall funciona e dê ao seu agente as skills dele:
@@ -127,14 +128,7 @@ Prefere deixar um agente de codificação fazer tudo? Entregue a ele uma única
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Conecte mais agentes a qualquer momento com `agentmemory connect <agent>` — 20 adaptadores listados em [Funciona com qualquer agente](#works-with-every-agent). Referência completa de comandos em [Início rápido](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Conecte outro agente com `agentmemory connect <agent>`. Consulte as [integrações](#works-with-every-agent) e os [comandos cotidianos](#everyday-commands).
<details>
<summary><strong>Instalação global / EACCES</strong></summary>
@@ -154,13 +148,6 @@ O npx faz cache por versão. Force a mais recente com `npx -y @agentmemory/agent
</details>
-<details>
-<summary><strong>Já roda seu próprio engine iii</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funciona com qualquer agente" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Tod
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>plugin nativo + hooks do ciclo de vida + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Tod
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>pesquisa nativa + captura + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Tod
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>captura nativa + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. Tod
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>pesquisa nativa + captura + skills + MCP opcional</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +304,25 @@ 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 entre agentes.
+<a id="data-storage"></a>
-**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.
+### Armazenamento de dados
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Por padrão, as memórias ficam fora do repositório:
-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 <path>` ou defina `AGENTMEMORY_DATA_DIR`; qualquer uma das duas opções explícitas tem precedência sobre a descoberta legada:
+| Plataforma | Diretório de dados |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+A instância 0 reutiliza um `./data/state_store.db` existente. Escolha outro caminho com `--data-dir <path>` ou `AGENTMEMORY_DATA_DIR` e mantenha-o ao reiniciar ou atualizar. `--instance 1` usa o subdiretório `instance-1`, a porta da API `3211` e o visualizador `3213`. Consulte [armazenamento e backups](../docs/reliability/state-storage.md) para Redis e migrações.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +471,7 @@ Taxa de acerto top-5 de 100% no **teto matemático de P@5** deste corpus (0.240,
</tr>
<tr>
<td><strong>Dependências externas</strong></td>
-<td>Nenhuma (SQLite + iii-engine)</td>
+<td>Nenhum serviço de banco de dados separado necessário</td>
<td>Qdrant / pgvector</td>
<td>Postgres + BD vetorial</td>
<td>Várias</td>
@@ -550,14 +545,12 @@ Taxa de acerto top-5 de 100% no **teto matemático de P@5** deste corpus (0.240,
| 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.
+O AgentMemory combina captura por agentes de programação, histórico de projeto pesquisável e visualizador local. O uso sem chave está disponível desde a primeira execução.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Início rápido" height="32" /></picture></h2>
-Compatibilidade: esta versão usa `iii-sdk` 0.22.1 e fixa o iii-engine na v0.22.1.
-
### Teste em 30 segundos
```bash
@@ -572,9 +565,11 @@ npx -y @agentmemory/agentmemory@latest demo
Abra `http://localhost:3113` para acompanhar a memória sendo construída ao vivo.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Com o servidor em execução, verifique a saúde, o visualizador e o status:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +578,27 @@ 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:
+`status` mostra a saúde do servidor e os provedores e embeddings ativos. Salve uma memória de teste e confirme a pesquisa:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Comandos do 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:
@@ -623,7 +625,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
-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. 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.
@@ -635,14 +637,12 @@ Use o comando de manutenção quando você quiser intencionalmente atualizar seu
npx -y @agentmemory/agentmemory@latest upgrade
```
-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` em torno da região `src/cli.ts:544-595`).
+O comando atualiza o ambiente local e pode atualizar dependências JavaScript no workspace atual. Faça um backup e leia o [guia de atualização](../docs/upgrades/iii-0.25.md) antes de continuar.
### Claude Code (um bloco só, cole e vá)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code sem instalar o plugin (caminho MCP standalone)
@@ -703,6 +703,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Depois adicione o plugin nativo de um checkout do AgentMemory em **Settings → Plugins → Add marketplace** e recarregue a janela. O plugin oferece captura do ciclo de vida, atribuição ao projeto, skills e MCP. Ative os hooks do plugin ou os manuais em `~/.cursor/hooks.json` para evitar captura duplicada. [Guia do Cursor](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Escolha o comando para seu host. Pi e OMP instalam pesquisa, captura, reenvio offline e 17 skills; `--with-mcp` adiciona todas as ferramentas. Execute `/reload` no Pi ou reinicie o OMP e verifique `/agentmemory-status`. O DSH instala MCP e o plugin de captura incluído; reinicie o DSH depois.
+
+O Pi também oferece o pacote instalável `@agentmemory/pi`. O [guia do Pi](../integrations/pi/) explica a instalação local e a disponibilidade no npm. Use apenas um método de instalação por host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (cole este prompt)</b></summary>
@@ -749,6 +771,8 @@ Guia completo: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Outros agentes
Inicie o servidor de memória: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +789,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Isso é **complementar** a `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` escreve a configuração do servidor MCP para que as tools fiquem disponíveis.
-- `npx skills add rohitg00/agentmemory` instala as skills para que o agente saiba quando chamá-las.
+- `agentmemory connect <agent>` normalmente grava a configuração MCP. Hermes, OpenClaw, Pi e Oh My Pi instalam a integração nativa e as skills incluídas por padrão; MCP é opcional com `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` instala skills para agentes que não as incluem nativamente. Pule esta etapa para Hermes, OpenClaw, Pi e Oh My Pi: seus conectores já instalam as skills.
Para os poucos agentes que o CLI de skills ainda não cobre (Zed v1.3.x e anteriores), coloque você mesmo os 17 arquivos SKILL.md no diretório nativo de skills do agente; o mesmo formato funciona em todo lugar.
@@ -790,7 +814,7 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que u
| Agente | Arquivo de config | Notas |
|---|---|---|
| **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. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Depois adicione o plugin nativo de um checkout do AgentMemory em **Settings → Plugins → Add marketplace** e recarregue a janela. O plugin oferece captura do ciclo de vida, atribuição ao projeto, skills e MCP. Ative os hooks do plugin ou os manuais em `~/.cursor/hooks.json` para evitar captura duplicada. [Guia do Cursor](../integrations/cursor/). |
| **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 (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. |
@@ -804,7 +828,7 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que u
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | pesquisa nativa + captura + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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 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). |
@@ -812,39 +836,19 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todo host que u
| **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 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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferido) ou `config.json` (legado) | `agentmemory connect continue` cria `config.yaml` se estiver ausente ou modifica o `config.json` existente. Se o YAML já existir, mostra o bloco para adicionar em `mcpServers:` e preservar comentários e âncoras. O Continue usa um array, não um objeto. |
| **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 `<repo>/.factory/mcp.json`. Passe `--with-hooks` para captura automática nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` ativa as ferramentas MCP. Adicione `--with-hooks` para carregar o plugin nativo de captura incluído no AgentMemory. Não é necessário um pacote adicional. [DSH](../docs/dsh.md). |
| **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 direto com a REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Aider** | n/a | Use os [exemplos REST autenticados](#validate-a-fresh-install-and-restart-persistence) para gravar e pesquisar memórias em scripts. |
| **Qualquer agente (32+)** | n/a | `npx skillkit install agentmemory` autodetecta o host e mescla. |
**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)
-agentmemory registra suas operações principais como funções iii (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Qualquer linguagem com um SDK iii pode chamá-las diretamente via `ws://localhost:49134`, sem um cliente REST separado por linguagem.
-
-```bash
-pip install iii-sdk # Python
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
-
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-Exemplo prático: [`examples/python/`](../examples/python/) (quickstart + fluxo de observação/recall). A REST na `:3111` continua disponível para hosts sem runtime iii.
+Use a [API REST](#api) em qualquer linguagem ou as [ferramentas MCP](#mcp-server) em um agente. REST usa JSON e autenticação bearer; consulte o [exemplo de gravação e pesquisa](#validate-a-fresh-install-and-restart-persistence). Os [exemplos Python](../examples/python/) cobrem a integração direta com o runtime.
### A partir do código-fonte
@@ -853,92 +857,33 @@ 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 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.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=<version>` se você roda seu próprio engine e sabe que ele 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:** 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 baixa `iiidev/iii:0.22.1`). Documentação completa: [iii.dev/docs](https://iii.dev/docs).
+`npm start` inicia o mesmo servidor local da CLI instalada. Os requisitos estão em [Install](#install); a API e o visualizador escutam em `127.0.0.1`.
### Windows
-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)**
+agentmemory roda no Windows 10/11. O WSL2 segue o caminho Linux e pode instalar o engine fixado automaticamente. O Windows nativo exige a instalação manual do binário iii-engine v0.25.0 fixado; baixe o arquivo correspondente na [página de releases do iii 0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), confira o checksum e coloque `iii.exe` no `PATH` (por exemplo, `%USERPROFILE%\.local\bin\iii.exe`). O CLI não extrai o ZIP do Windows automaticamente.
-```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
-```
+A configuração MCP automatizada no Windows nativo dá suporte apenas a `agentmemory connect copilot-cli`. Para os outros agentes nativos do Windows, use o bloco MCP manual em [Outros agentes](#other-agents). Rode `connect` no WSL somente quando o agente de destino estiver instalado no mesmo ambiente WSL.
-**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: 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:
+**Somente MCP standalone (sem engine).** Se você precisa apenas das ferramentas MCP, sem REST API, viewer ou serviços de runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**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 |
-|---|---|
-| `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 <N>` |
-| 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** 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`.
+Execute `agentmemory doctor` ou reinicie com `--verbose`. Use `--port <N>` ou `--instance <N>` se as portas estiverem ocupadas. Consulte compatibilidade e recuperação no [guia de atualização](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Deploy</h2>
-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.
+Hospede o serviço com Docker Compose ou os modelos abaixo. Memórias e credenciais ficam no volume `/data`. Faça um backup e reutilize esse volume nas atualizações. O [guia de implantação](../deploy/README.md) cobre autenticação, rede, backups e migração.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
O botão de deploy de um clique do Render exige um `render.yaml` na raiz do repositório, que 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.
@@ -956,28 +901,26 @@ rotação, backup, pisos de custo) ficam em [`deploy/`](.././deploy/README.md):
própria VPS via [Coolify](https://coolify.io/self-hosted); mesma
stack Docker Compose, você é dono do host e dos dados.
-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.
+REST usa a porta `3111`; o visualizador, `3113`. Mantenha ambos privados ou proteja-os com autenticação e TLS. O guia de implantação explica a exposição de rede e a [migração de instalações Docker antigas](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Por que agentmemory" height="32" /></picture></h2>
-Todo agente de codificação esquece tudo quando a sessão termina, e cada nova sessão começa com você re-explicando sua stack. agentmemory roda em segundo plano e remove essa etapa.
+O conhecimento do projeto se espalha por conversas e arquivos de instruções. O AgentMemory permite pesquisar decisões, correções e aprendizados no agente que você estiver usando.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs memória integrada do agente
@@ -986,7 +929,7 @@ Todo agente de codificação com IA vem com memória integrada: Claude Code tem
| | Integrada (CLAUDE.md) | agentmemory |
|---|---|---|
-| Escala | Teto de 200 linhas | Ilimitado |
+| Manutenção | Instruções mantidas manualmente | Histórico de sessões e memórias indexadas |
| 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) |
@@ -1012,13 +955,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Consolidação de memória em 4 níveis
@@ -1036,6 +979,8 @@ As memórias decaem com o tempo (curva de Ebbinghaus). Memórias acessadas com f
### O que é capturado
+Esta tabela descreve os hooks do Claude Code. Outras integrações capturam os eventos fornecidos pelo host; consulte os respectivos guias. A injeção automática de contexto pelos hooks compartilhados exige `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Captura |
|------|----------|
| `SessionStart` | Caminho do projeto, ID da sessão |
@@ -1052,7 +997,7 @@ As memórias decaem com o tempo (curva de Ebbinghaus). Memórias acessadas com f
| Capacidade | Descrição |
|---|---|
-| **Captura automática** | Todo uso de tool registrado via hooks, sem esforço manual |
+| **Captura automática** | Integrações nativas registram os eventos de sessão e ferramentas compatíveis |
| **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 |
@@ -1253,7 +1198,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Viewer em tempo real" height="32" /></picture></h2>
-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.
+Inicia automaticamente na porta `3113`. O viewer carrega um snapshot ao conectar (`GET /agentmemory/viewer/snapshot`) e então aplica eventos em tempo real enviados por SSE em `/agentmemory/viewer/events`, pelo worker REST: novas memórias, lessons, observações, entradas de auditoria, mudanças no grafo e atualizações de saúde aparecem sem polling nem recarregamento da página. As outras requisições são as ações em que você clica, páginas de “carregar mais” e buscas. Quando o stream cai, o viewer mostra há quanto tempo os dados estão desatualizados, reconecta com backoff e sincroniza novamente a partir de um snapshot.
- **12 abas em quatro grupos** com contagens ao vivo, deep links (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1266,188 +1211,7 @@ Inicia automaticamente na porta `3113`. O viewer carrega um snapshot quando se c
open http://localhost:3113
```
-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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-O viewer 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 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 entrega isso de graça porque toda chamada de função e trigger dispara através do iii; nada custom, nada para instrumentar.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Página Workers do iii console: workers conectados incluindo instâncias do agentmemory com contagem de funções ao vivo e metadados de runtime" width="720" />
- <br/>
- <em>Página Workers: todo worker conectado, incluindo o próprio agentmemory, com PID, contagem de funções, runtime e last-seen.</em>
-</p>
-
-**Já instalado.** O console vem junto com o engine `iii` fixado (0.22+); nada separado para instalar. O primeiro lançamento baixa o binário do console ao lado do engine.
-
-**Lançando junto com o agentmemory:**
-
-```bash
-agentmemory console
-```
-
-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.
-
-A mesma coisa na mão, útil quando `agentmemory` não está no PATH:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**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; 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 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 o seu engine está rodando. |
-| **Flow** | (Opcional, `--enable-flow`) Grafo de arquitetura interativo de todo worker, trigger e stream. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Vista de waterfall de trace do iii console mostrando a duração por span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / breakdown por serviço para toda operação de memória.</em>
-</p>
-
-**Os traces já vêm ativados:**
-
-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 em vez disso, troque `exporter: memory` por `exporter: otlp` e configure o endpoint do collector conforme a documentação de observabilidade do iii.
-
-> **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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory **já é uma instância [iii](https://iii.dev) em execução**. 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 inteiramente nova.
-
-### Estenda o agentmemory com mais workers
-
-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.
-
-```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 você ganha além do agentmemory |
-|---|---|
-| [`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:<scope>`, `stream:<name>:<group>`) 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.
-
-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 em memória |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | Supervisão de worker do engine iii |
-| Prometheus / Grafana | iii OTEL + monitor de saúde |
-| Sistemas de plugin customizados | `iii worker add <name>` |
-
-**250 arquivos de código · ~55,000 LOC · 3,400+ testes · 324 funções · 67 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+O servidor do viewer faz bind em `127.0.0.1` por padrão e anexa o secret do servidor ao encaminhar requisições para a REST API. Em um bind fora do loopback, a casca HTML permanece pública, mas cada requisição de proxy exige bearer token; o viewer pede o token e o guarda no session storage do navegador. Configure allowlists explícitas de host/origem e TLS antes de expor um viewer. O endpoint REST `/agentmemory/viewer` continua seguindo 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'`).
---
@@ -1468,6 +1232,8 @@ agentmemory detecta providers automaticamente a partir do seu ambiente. Um provi
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Modelos locais (Ollama / LM Studio / vLLM)
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.
@@ -1517,24 +1283,7 @@ Embeddings locais vêm como uma dependência opcional, mas não são ativados po
### Seleção de modelo com consciência de custo
-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.
-
-| 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 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 a mesma mistura de tokens pelo preço de tabela de cada modelo.
-
-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.
-
-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: [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/).
+Comece sem chave para captura e pesquisa por palavras-chave. `EMBEDDING_PROVIDER=local` ativa a pesquisa semântica local após o primeiro download do modelo. A compressão por LLM exige um provedor e `AGENTMEMORY_AUTO_COMPRESS=true`; pode gerar uma solicitação por observação. Consulte os preços atuais antes de ativá-la. O visualizador e `agentmemory status` mostram os provedores ativos.
### Memória multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1564,39 +1313,22 @@ 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 reinício falhar com `port in use`, esta tabela diz qual processo procurar.
-
-| Porta | Processo | Finalidade | Override de env |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `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 <N>` 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.
+| Porta | Uso | Configuração |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Limpeza de processo obsoleto quando as portas continuam em uso depois de uma execução que travou:
+`--port <N>` define a porta da API e, por padrão, o visualizador em `N+2`. Use `--instance N` para uma instância separada. Mantenha as portas internas privadas e consulte o [guia de implantação](../deploy/README.md) antes de permitir acesso remoto.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Backend de armazenamento: file (padrão) vs redis
-`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.
+O armazenamento em arquivos padrão não precisa de um serviço de banco de dados separado. Redis é opcional com `AGENTMEMORY_STATE_BACKEND=redis` e `AGENTMEMORY_REDIS_URL`. Trocar o backend não copia as memórias. O [guia de armazenamento e backups](../docs/reliability/state-storage.md) cobre persistência, limitações do Redis e exportação/importação autenticada.
### Arquivo de config
-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.
+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 configuração como `export ANTHROPIC_API_KEY=...`, copie-a para esse arquivo como `ANTHROPIC_API_KEY=...`, sem o prefixo `export`, e então reinicie o agentmemory. Defina `AGENTMEMORY_ENV_FILE` para usar outro caminho de arquivo env.
-Variáveis de ambiente do processo continuam funcionando e têm precedência sobre valores no arquivo.
+As variáveis de ambiente do processo têm prioridade sobre o arquivo. Reinicie o servidor após alterar a configuração.
No Windows, o mesmo arquivo mora em `%USERPROFILE%\.agentmemory\.env`:
@@ -1623,179 +1355,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Variáveis de ambiente
-Crie `~/.agentmemory/.env`:
+Opções comuns para `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+A referência completa está em [`.env.example`](../.env.example): credenciais, filtros de captura, retenção, armazenamento, escopo de equipe e opções. `AGENTMEMORY_ENV_FILE` seleciona outro arquivo. Nunca inclua um `.env` preenchido ou um segredo bearer no git.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer <secret>`, e endpoints de mesh sync exigem um `AGENTMEMORY_SECRET` explicitamente definido em ambos os peers.
+146 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por padrão. Endpoints protegidos exigem `Authorization: Bearer <secret>`, 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:
+**A autenticação vem ativada por padrão.** Quando `AGENTMEMORY_SECRET` não está definida na shell nem em `~/.agentmemory/.env`, a CLI gera um segredo aleatório na primeira execução em `~/.agentmemory/secret` e grava uma cópia chamada `secret` no diretório de dados selecionado, com permissões `0600`. Todos os clientes empacotados o leem de lá ao falar com um servidor local: CLI, viewer, hooks em `plugin/scripts`, servidor MCP e shim `@agentmemory/mcp`, configurações escritas por `agentmemory connect` e integrações empacotadas de OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. O secret armazenado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Um `AGENTMEMORY_SECRET` explícito sempre prevalece, e clientes remotos precisam ter o secret definido em seu ambiente. Deploys self-hosted com Docker baseados no repositório e os entrypoints de `deploy/` geram e exportam seu próprio secret. Para chamar a API manualmente:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1831,7 +1416,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Compartilha com o time |
| `GET` | `/agentmemory/audit` | Trilha de auditoria |
-Lista completa de endpoints: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Lista completa de endpoints: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1849,19 +1434,19 @@ Eventos que falham são tentados de novo a cada `AGENTMEMORY_CAPTURE_RETRY_INTER
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, `<data dir>/capture-spool/<host>-<port>.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.
+**Compactando provenance de grafo.** A compactação da proveniência antiga é adiada na inicialização porque lê os scopes antigos completos. `/agentmemory/status` informa `deferred`, ou `off` com `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Execute a compactação manual abaixo durante a manutenção. A migração do índice de busca é separada: use `agentmemory graph-index migrate --allow-legacy-scan` conforme o [guia de manutenção](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1875,7 +1460,7 @@ npm test # 4,000+ 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 manual, o WSL2 ou o Docker Desktop.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licença" height="32" /></picture></h2>
diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.md
index 6634ebc0..5b1837dc 100644
--- a/READMEs/README.pt-PT.md
+++ b/READMEs/README.pt-PT.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- O seu agente de codificação lembra-se de tudo. Chega de voltar a explicar.
- Construído sobre o <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Memória persistente entre sessões e agentes de programação.
</strong><br/>
- Memória persistente para Claude Code, GitHub Copilot CLI, 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, Oh My Pi, DeepSeek Harness, OpenCode e qualquer cliente MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licença" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Estrelas" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Como Funciona</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Visualizador</a> &bull;
- <a href="#powered-by-iii">Desenvolvido com o iii</a> &bull;
<a href="#configuration">Configuração</a> &bull;
<a href="#api">API</a>
</p>
---
+O AgentMemory captura sessões de programação e permite pesquisar decisões, correções e aprendizagens. Partilhe um único armazenamento entre agentes, inspecione o conteúdo guardado e escolha quanto contexto chega ao modelo.
+
+<a id="install"></a>
+
## 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.
+- No macOS/Linux, a configuração automática também precisa de `curl`, um `sh` POSIX e `tar`.
+- No Windows, use WSL2 ou siga a [configuração nativa](#windows).
Comando canónico para uma instalação limpa:
@@ -108,11 +111,11 @@ Comando canónico para uma instalação limpa:
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.
+Escolha os seus agentes e um fornecedor, ou o modo sem chave. O assistente grava a configuração, inicia o servidor de memória e oferece uma instalação global do comando `agentmemory`. `-y` aceita a confirmação do npm; `@latest` seleciona a versão atual. A compressão por LLM é opcional e exige um fornecedor e `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+A API fica em `http://localhost:3111` e o visualizador em `http://localhost:3113`. Ambos escutam em loopback por predefinição. A configuração fica em `~/.agentmemory/.env`; consulte [armazenamento de dados](#data-storage) para os caminhos e instâncias separadas.
Depois, prove que o recall funciona e dê ao seu agente as suas skills:
@@ -127,14 +130,7 @@ Prefere deixar um agente de codificação fazer tudo? Dê-lhe uma única instru
> 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 <agent>` — 20 adaptadores listados em [Funciona com qualquer agente](#works-with-every-agent). Referência completa de comandos em [Início Rápido](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Conecte outro agente com `agentmemory connect <agent>`. Consulte as [integrações](#works-with-every-agent) e os [comandos cotidianos](#everyday-commands).
<details>
<summary><strong>Instalação global / EACCES</strong></summary>
@@ -154,13 +150,6 @@ O npx faz cache por versão. Force a mais recente com `npx -y @agentmemory/agent
</details>
-<details>
-<summary><strong>Já tem o seu próprio iii engine em execução</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funciona com qualquer agente" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. T
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin nativo + 7 hooks + MCP</sub>
+<sub>plugin nativo + hooks do ciclo de vida + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. T
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin nativo + MCP</sub>
+<sub>pesquisa nativa + captura + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. T
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>servidor MCP</sub>
+<sub>captura nativa + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. T
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>pesquisa nativa + captura + skills + MCP opcional</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +306,25 @@ O agentmemory funciona com qualquer agente que suporte hooks, MCP ou REST API. T
---
-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.
+<a id="data-storage"></a>
-**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.
+### Armazenamento de dados
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Por predefinição, as memórias ficam fora do repositório:
-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 <path>` ou defina `AGENTMEMORY_DATA_DIR`; qualquer uma destas definições explícitas tem precedência sobre a deteção legada:
+| Plataforma | Diretório de dados |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+A instância 0 reutiliza um `./data/state_store.db` existente. Escolha outro caminho com `--data-dir <path>` ou `AGENTMEMORY_DATA_DIR` e mantenha-o ao reiniciar ou atualizar. `--instance 1` usa o subdiretório `instance-1`, a porta da API `3211` e o visualizador `3213`. Consulte [armazenamento e cópias de segurança](../docs/reliability/state-storage.md) para Redis e migrações.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +473,7 @@ Taxa de acerto top-5 de 100% no **teto matemático do P@5** para este corpus (0.
</tr>
<tr>
<td><strong>Dependências externas</strong></td>
-<td>Nenhuma (SQLite + iii-engine)</td>
+<td>Nenhum serviço de base de dados separado necessário</td>
<td>Qdrant / pgvector</td>
<td>Postgres + BD vetorial</td>
<td>Várias</td>
@@ -550,14 +547,12 @@ Taxa de acerto top-5 de 100% no **teto matemático do P@5** para este corpus (0.
| 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.
+O AgentMemory combina captura por agentes de programação, histórico de projeto pesquisável e visualizador local. O uso sem chave está disponível desde a primeira execução.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Início Rápido" height="32" /></picture></h2>
-Compatibilidade: esta versão visa o `iii-sdk` 0.22.1 e fixa o iii-engine na v0.22.1.
-
### Experimente em 30 Segundos
```bash
@@ -572,9 +567,11 @@ O `demo` gera 3 sessões realistas (autenticação JWT, correção de uma query
Abra `http://localhost:3113` para ver a memória a construir-se em direto.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Com o servidor em execução, verifique o funcionamento, o visualizador e o estado:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` mostra a saúde do servidor e os fornecedores e embeddings ativos. Guarde uma memória de teste e confirme a pesquisa:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### 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:
@@ -623,7 +627,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+As sessões importadas aparecem no seletor do Replay junto às nativas. 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.
@@ -635,14 +639,12 @@ Use o comando de manutenção quando quiser, de forma intencional, atualizar o s
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`).
+O comando atualiza o ambiente local e pode atualizar dependências JavaScript no workspace atual. Faça uma cópia de segurança e leia o [guia de atualização](../docs/upgrades/iii-0.25.md) antes de continuar.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code sem instalar o plugin (caminho MCP standalone)
@@ -703,6 +705,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Depois adicione o plugin nativo de um checkout do AgentMemory em **Settings → Plugins → Add marketplace** e recarregue a janela. O plugin oferece captura do ciclo de vida, atribuição ao projeto, skills e MCP. Ative os hooks do plugin ou os manuais em `~/.cursor/hooks.json` para evitar captura duplicada. [Guia do Cursor](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Escolha o comando para o seu host. Pi e OMP instalam pesquisa, captura, reenvio offline e 17 skills; `--with-mcp` adiciona todas as ferramentas. Execute `/reload` no Pi ou reinicie o OMP e verifique `/agentmemory-status`. O DSH instala MCP e o plugin de captura incluído; reinicie o DSH depois.
+
+O Pi também oferece o pacote instalável `@agentmemory/pi`. O [guia do Pi](../integrations/pi/) explica a instalação local e a disponibilidade no npm. Use apenas um método de instalação por host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (cole este prompt)</b></summary>
@@ -749,6 +773,8 @@ Guia completo: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Outros Agentes
Inicie o servidor de memória: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +791,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Isto é **complementar** a `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` normalmente grava a configuração MCP. Hermes, OpenClaw, Pi e Oh My Pi instalam a integração nativa e as skills incluídas por predefinição; MCP é opcional com `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` instala skills para agentes que não as incluem nativamente. Ignore este passo para Hermes, OpenClaw, Pi e Oh My Pi: os respetivos conectores já instalam as skills.
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.
@@ -790,7 +816,7 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todos os anfitr
| 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. |
+| **Cursor (plugin completo)** | `.cursor-plugin/` | Depois adicione o plugin nativo de um checkout do AgentMemory em **Settings → Plugins → Add marketplace** e recarregue a janela. O plugin oferece captura do ciclo de vida, atribuição ao projeto, skills e MCP. Ative os hooks do plugin ou os manuais em `~/.cursor/hooks.json` para evitar captura duplicada. [Guia do Cursor](../integrations/cursor/). |
| **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. |
@@ -804,7 +830,7 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todos os anfitr
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | pesquisa nativa + captura + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +838,19 @@ A entrada do agentmemory é o **mesmo bloco de servidor MCP** em todos os anfitr
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferido) ou `config.json` (legado) | `agentmemory connect continue` cria `config.yaml` se estiver ausente ou modifica o `config.json` existente. Se o YAML já existir, mostra o bloco para adicionar em `mcpServers:` e preservar comentários e âncoras. O Continue usa um array, não um objeto. |
| **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 `<repo>/.factory/mcp.json`. Passe `--with-hooks` para captura automática nativa. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` ativa as ferramentas MCP. Adicione `--with-hooks` para carregar o plugin nativo de captura incluído no AgentMemory. Não é necessário um pacote adicional. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Use os [exemplos REST autenticados](#validate-a-fresh-install-and-restart-persistence) para gravar e pesquisar memórias em scripts. |
| **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.
+Use a [API REST](#api) em qualquer linguagem ou as [ferramentas MCP](#mcp-server) em um agente. REST usa JSON e autenticação bearer; consulte o [exemplo de gravação e pesquisa](#validate-a-fresh-install-and-restart-persistence). Os [exemplos Python](../examples/python/) cobrem a integração direta com o runtime.
### A Partir do Código-Fonte
@@ -853,92 +859,28 @@ 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=<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).
+`npm start` inicia o mesmo servidor local da CLI instalada. Os requisitos estão em [Install](#install); a API e o visualizador escutam em `127.0.0.1`.
### 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.
+O agentmemory funciona no Windows 10/11. O WSL2 segue o caminho Linux e pode instalar automaticamente o engine fixado. O Windows nativo exige que o binário iii-engine v0.25.0 fixado seja instalado manualmente; descarregue o ficheiro correspondente na [página de lançamento iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verifique o checksum e coloque `iii.exe` no `PATH` (por exemplo, `%USERPROFILE%\.local\bin\iii.exe`). O CLI não extrai automaticamente o ZIP do Windows.
-**Opção A: binário pré-compilado para Windows (recomendado)**
+A ligação MCP automatizada no Windows nativo só suporta `agentmemory connect copilot-cli`. Para os restantes agentes nativos do Windows, use o bloco MCP manual de [Outros agentes](#other-agents). Execute `connect` no WSL apenas quando o agente de destino também estiver instalado nesse mesmo ambiente WSL.
-```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:
+**Apenas MCP standalone (sem engine).** Se só precisar das ferramentas MCP e não precisar da REST API, do visualizador ou dos serviços de runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
-
+Execute `agentmemory doctor` ou reinicie com `--verbose`. Use `--port <N>` ou `--instance <N>` se as portas estiverem ocupadas. Consulte compatibilidade e recuperação no [guia de atualização](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Deploy</h2>
-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.
-
-<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
-</p>
+Hospede o serviço com Docker Compose ou os modelos abaixo. Memórias e credenciais ficam no volume `/data`. Faça uma cópia de segurança e reutilize esse volume nas atualizações. O [guia de implantação](../deploy/README.md) cobre autenticação, rede, cópias de segurança e migração.
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.
@@ -955,28 +897,26 @@ custos mínimos) estão em [`deploy/`](.././deploy/README.md):
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.
+REST usa a porta `3111`; o visualizador, `3113`. Mantenha ambos privados ou proteja-os com autenticação e TLS. O guia de implantação explica a exposição de rede e a [migração de instalações Docker antigas](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Porque usar o agentmemory" height="32" /></picture></h2>
-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.
+O conhecimento do projeto dispersa-se por conversas e ficheiros de instruções. O AgentMemory permite pesquisar decisões, correções e aprendizagens no agente que estiver a utilizar.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs memória incorporada do agente
@@ -985,7 +925,7 @@ Todo o agente de codificação com IA vem com memória incorporada: o Claude Cod
| | Incorporado (CLAUDE.md) | agentmemory |
|---|---|---|
-| Escala | Limite de 200 linhas | Ilimitada |
+| Manutenção | Instruções mantidas manualmente | Histórico de sessões e memórias indexadas |
| 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) |
@@ -1011,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Consolidação de Memória em 4 Níveis
@@ -1035,6 +975,8 @@ As memórias decaem com o tempo (curva de Ebbinghaus). As memórias acedidas fre
### O Que É Capturado
+Esta tabela descreve os hooks do Claude Code. Outras integrações capturam os eventos fornecidos pelo host; consulte os respectivos guias. A injeção automática de contexto pelos hooks partilhados exige `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Captura |
|------|----------|
| `SessionStart` | Caminho do projeto, ID da sessão |
@@ -1051,7 +993,7 @@ As memórias decaem com o tempo (curva de Ebbinghaus). As memórias acedidas fre
| Capacidade | Descrição |
|---|---|
-| **Captura automática** | Todo o uso de ferramentas é registado através de hooks, sem esforço manual |
+| **Captura automática** | Integrações nativas registram os eventos de sessão e ferramentas compatíveis |
| **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 |
@@ -1112,7 +1054,7 @@ A instalação normal via npm inclui o runtime opcional `@huggingface/transforme
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`.
+> **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 ligue-se a um servidor self-hosted) e defina `AGENTMEMORY_URL=http://localhost:3111`.
### 54 Ferramentas
@@ -1252,7 +1194,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Visualizador em Tempo Real" height="32" /></picture></h2>
-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.
+Inicia-se automaticamente na porta `3113`. O visualizador carrega um snapshot quando se liga (`GET /agentmemory/viewer/snapshot`) e depois aplica eventos em direto por SSE em `/agentmemory/viewer/events` no worker REST: 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/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1265,188 +1207,7 @@ Inicia-se automaticamente na porta `3113`. O visualizador carrega um snapshot qu
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'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-O 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 align="center">
- <img src="../assets/iii-console/workers.png" alt="Página Workers da iii console: workers conectados, incluindo instâncias do agentmemory com contagens de funções em direto e metadados de runtime" width="720" />
- <br/>
- <em>Página Workers: cada worker conectado, incluindo o próprio agentmemory, com PID, contagem de funções, runtime e última atividade (last-seen).</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Vista waterfall de traces da iii console, mostrando a duração por span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / por serviço para cada operação de memória.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Desenvolvido com o iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 ficheiros de código-fonte · ~55,000 LOC · 3,400+ testes · 324 funções · 67 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+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. Num bind que não seja loopback, a shell HTML continua pública, mas cada pedido proxy exige bearer; o visualizador pede-o e guarda-o no session storage. Configure allowlists explícitas de anfitriões/origens e TLS antes de expor um visualizador. 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'`).
---
@@ -1467,6 +1228,8 @@ O agentmemory deteta automaticamente fornecedores a partir do seu ambiente. Um f
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1279,7 @@ Os embeddings locais são distribuídos como dependência opcional, mas não est
### 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/).
+Comece sem chave para captura e pesquisa por palavras-chave. `EMBEDDING_PROVIDER=local` ativa a pesquisa semântica local após o primeiro download do modelo. A compressão por LLM exige um fornecedor e `AGENTMEMORY_AUTO_COMPRESS=true`; pode gerar uma pedido por observação. Consulte os preços atuais antes de ativá-la. O visualizador e `agentmemory status` mostram os fornecedores ativos.
### Memória Multiagente (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1309,22 @@ Quando `AGENT_ID` não está definida, a memória permanece sem âmbito (comport
### 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 <N>` 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.
+| Porta | Uso | Configuração |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Limpeza de processos obsoletos, quando as portas continuam vinculadas depois de uma execução que terminou em crash:
+`--port <N>` define a porta da API e, por predefinição, o visualizador em `N+2`. Use `--instance N` para uma instância separada. Mantenha as portas internas privadas e consulte o [guia de implantação](../deploy/README.md) antes de permitir acesso remoto.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Backend de armazenamento: ficheiro (predefinição) vs Redis
-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.
+O armazenamento em ficheiros predefinido não precisa de um serviço de base de dados separado. Redis é opcional com `AGENTMEMORY_STATE_BACKEND=redis` e `AGENTMEMORY_REDIS_URL`. Trocar o backend não copia as memórias. O [guia de armazenamento e cópias de segurança](../docs/reliability/state-storage.md) cobre persistência, limitações do Redis e exportação/importação autenticada.
### 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.
+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 como `export ANTHROPIC_API_KEY=...`, copie-a para este ficheiro como `ANTHROPIC_API_KEY=...`, sem o prefixo `export`, e reinicie o agentmemory. Defina `AGENTMEMORY_ENV_FILE` para usar outro caminho de ficheiro env.
-As variáveis de ambiente do processo continuam a funcionar e têm precedência sobre os valores no ficheiro.
+As variáveis de ambiente do processo têm prioridade sobre o ficheiro. Reinicie o servidor após alterar a configuração.
No Windows, o mesmo ficheiro vive em `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,179 +1351,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Variáveis de Ambiente
-Crie `~/.agentmemory/.env`:
+Opções comuns para `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+A referência completa está em [`.env.example`](../.env.example): credenciais, filtros de captura, retenção, armazenamento, âmbito de equipa e opções. `AGENTMEMORY_ENV_FILE` seleciona outro ficheiro. Nunca inclua um `.env` preenchido ou um segredo bearer no git.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por predefinição. Os endpoints protegidos exigem `Authorization: Bearer <secret>`, e os endpoints de sincronização mesh exigem uma `AGENTMEMORY_SECRET` explicitamente definida em ambos os pares.
+146 endpoints na porta `3111`. A REST API faz bind em `127.0.0.1` por predefinição. Os endpoints protegidos exigem `Authorization: Bearer <secret>`, 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:
+**A autenticação está ativa por predefinição.** Quando `AGENTMEMORY_SECRET` não está definida na shell nem em `~/.agentmemory/.env`, o CLI gera um segredo aleatório no primeiro arranque em `~/.agentmemory/secret` e guarda uma cópia chamada `secret` no diretório de dados selecionado, com permissões `0600`. Todos os clientes incluídos o leem daí quando comunicam 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 de OpenCode, Pi, OpenClaw, Hermes e filesystem-watcher. O segredo guardado só é enviado para URLs de loopback (`localhost`, `127.0.0.0/8`, `::1`). Uma `AGENTMEMORY_SECRET` explícita prevalece sempre, e os clientes remotos precisam de ter o segredo definido no seu ambiente. As implementações Docker self-host a partir do repositório e os entrypoints de `deploy/` 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
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1830,7 +1412,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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)
+Lista completa de endpoints: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1430,19 @@ Os eventos falhados são repetidos a cada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS
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, `<data dir>/capture-spool/<host>-<port>.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.
+**Compactação da proveniência do grafo.** A compactação da proveniência antiga é adiada no arranque porque lê os scopes antigos completos. `/agentmemory/status` indica `deferred`, ou `off` com `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Execute a compactação manual abaixo durante a manutenção. A migração do índice de pesquisa é separada: use `agentmemory graph-index migrate --allow-legacy-scan` conforme o [guia de manutenção](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1456,7 @@ npm test # 4,000+ 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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licença" height="32" /></picture></h2>
diff --git a/READMEs/README.ro-RO.md b/READMEs/README.ro-RO.md
index 339247ed..d9cb8940 100644
--- a/READMEs/README.ro-RO.md
+++ b/READMEs/README.ro-RO.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Agentul tău de programare își amintește totul. Nu mai trebuie să re-explici.
- Construit pe <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Memorie persistentă între sesiuni și agenți de programare.
</strong><br/>
- Memorie persistentă pentru Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode și orice client MCP.
+ Memorie persistentă pentru Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode și orice client MCP.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licență" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stele" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Cum funcționează</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Vizualizator</a> &bull;
- <a href="#powered-by-iii">Susținut de iii</a> &bull;
<a href="#configuration">Config</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory captează evenimentele acceptate ale sesiunilor și face deciziile, remediile și lecțiile căutabile între agenți. Viewer-ul permite inspectarea, editarea, exportul și ștergerea memoriei. Căutarea după cuvinte cheie funcționează fără cheie API; embedding-urile adaugă căutare semantică.
+
+<a id="install"></a>
+
## 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.
+- macOS/Linux au nevoie și de `curl`, un shell POSIX `sh` și `tar` pentru configurarea automată a mediului.
+- Pe Windows folosește WSL2 sau [instrucțiunile pentru Windows nativ](#windows).
Comanda canonică pentru o instalare nouă:
@@ -108,11 +111,11 @@ Comanda canonică pentru o instalare nouă:
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`.
+Alege agenții și un furnizor sau modul fără cheie. Configurarea salvează opțiunile, pornește serverul de memorie și oferă instalarea globală a comenzii `agentmemory`. `-y` acceptă solicitarea npm; `@latest` alege versiunea curentă. Compresia prin LLM necesită un furnizor ș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 <path>` 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.
+API-ul este la `http://localhost:3111`, iar viewer-ul la `http://localhost:3113`. Implicit, ambele ascultă doar local. Configurarea se află în `~/.agentmemory/.env`; [stocarea datelor](#data-storage) descrie directoarele și instanțele separate.
Apoi demonstrează că reamintirea funcționează și oferă-i agentului tău skill-urile sale:
@@ -127,14 +130,7 @@ Preferi să lași un agent de programare să facă totul? Dă-i o singură instr
> 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 <agent>` — 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).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Conectează alt agent cu `agentmemory connect <agent>`. Consultă [integrările](#works-with-every-agent) și [comenzile zilnice](#everyday-commands).
<details>
<summary><strong>Instalare globală / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx face cache pe versiune. Forțează cea mai recentă versiune cu `npx -y @age
</details>
-<details>
-<summary><strong>Rulezi deja propriul tău motor iii</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Funcționează cu orice agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST A
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>plugin nativ + 7 hook-uri + MCP</sub>
+<sub>plugin nativ + hook-uri de ciclu de viață + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST A
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>plugin nativ + MCP</sub>
+<sub>reamintire nativă + captură + skill-uri</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST A
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>server MCP</sub>
+<sub>captură nativă + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST A
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>reamintire nativă + captură + skill-uri + MCP opțional</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ agentmemory funcționează cu orice agent care suportă hook-uri, MCP sau REST A
---
-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.
+<a id="data-storage"></a>
-**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.
+### Stocarea datelor
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Memoria se păstrează implicit în afara depozitului:
-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 <path>` sau setează `AGENTMEMORY_DATA_DIR`; orice setare explicită are prioritate față de detectarea automată a fișierelor legacy:
+| Platformă | Director de date |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instanța 0 reutilizează un `./data/state_store.db` existent. Alege alt director cu `--data-dir <path>` sau `AGENTMEMORY_DATA_DIR`. Păstrează același director la repornire și actualizare.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` folosește subdirectorul `instance-1`, portul API `3211` și viewer-ul `3213`. Redis și migrarea sunt descrise în [ghidul de stocare și backup](../docs/reliability/state-storage.md).
Notele celei mai recente versiuni: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ Rată de succes Top-5 de 100% la **plafonul matematic P@5** pentru acest corpus
</tr>
<tr>
<td><strong>Dependențe externe</strong></td>
-<td>Niciuna (SQLite + iii-engine)</td>
+<td>Nu necesită un serviciu de baze de date separat</td>
<td>Qdrant / pgvector</td>
<td>Postgres + bază de date vectorială</td>
<td>Multiple</td>
@@ -550,14 +549,12 @@ Rată de succes Top-5 de 100% la **plafonul matematic P@5** pentru acest corpus
| 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.
+AgentMemory combină captura sesiunilor, istoricul căutabil al proiectului și un viewer local, cu funcționare fără cheie de la prima pornire.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Început rapid" height="32" /></picture></h2>
-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
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Deschide `http://localhost:3113` pentru a urmări memoria construindu-se în timp real.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Validează o instalare nouă și persistența la repornire
-Cu serverul pornit, validează REST, health, vizualizatorul și starea runtime-ului susținut de iii:
+Cu serverul pornit, verifică sănătatea, viewer-ul și starea:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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ă:
+`status` arată sănătatea serverului, furnizorii, modul de embedding, livrarea observațiilor și recuperarea. Cererile REST protejate necesită secretul serverului. Folosește propriul `AGENTMEMORY_SECRET` dacă este configurat; altfel încarcă secretul local generat:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Comenzi zilnice
Instalarea și configurarea se află în [Instalare](#install) mai sus (prima rulare te ghidează prin ea). De zi cu zi:
@@ -604,6 +610,9 @@ Instalarea și configurarea se află în [Instalare](#install) mai sus (prima ru
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Sesiunile importate apar în Replay alături de cele native. Transcrierile sunt indexate și marcate cu sursa `import`; procesarea poate produce și cristale de sesiune ș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ă.
@@ -635,14 +644,12 @@ Folosește comanda de întreținere atunci când vrei, în mod intenționat, să
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`).
+Comanda actualizează mediul local și poate modifica dependențele JavaScript din spațiul de lucru curent. Fă backup datelor și citește [ghidul de actualizare](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code fără instalarea plugin-ului (cale MCP independentă)
@@ -703,6 +710,30 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Apoi, în **Settings → Plugins → Add marketplace**, alege directorul agentmemory care conține `.cursor-plugin/plugin.json`, activează plugin-ul **agentmemory** și reîncarcă fereastra. Plugin-ul oferă captură a ciclului de viață, atribuirea proiectului după workspace, skill-uri și MCP. Activează fie hook-urile plugin-ului, fie cele manuale din `~/.cursor/hooks.json`, pentru a evita capturile duplicate.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Alege comanda pentru gazda ta. Pi și OMP instalează reamintire nativă, captură, reluare offline și skill-uri; `--with-mcp` adaugă toate instrumentele. Rulează `/reload` în Pi sau repornește OMP, apoi verifică `/agentmemory-status`. DSH instalează MCP și plugin-ul de captură inclus; repornește DSH după conectare.
+
+Pi acceptă și pachetul instalabil `@agentmemory/pi`. Instalarea locală și disponibilitatea npm sunt descrise în [ghidul Pi](../integrations/pi/). Folosește o singură metodă de instalare pe gazdă.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (lipește acest prompt)</b></summary>
@@ -749,6 +780,8 @@ Ghid complet: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Alți agenți
Pornește serverul de memorie: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +798,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Aceasta este **complementară** cu `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` scrie de obicei configurația MCP. Hermes, OpenClaw, Pi și Oh My Pi instalează implicit integrarea nativă și skill-urile; MCP se activează cu `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` instalează skill-uri pentru agenți fără skill-uri native incluse. Omite acest pas pentru Hermes, OpenClaw, Pi și Oh My Pi; conectorii lor le instalează deja.
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.
@@ -790,7 +823,7 @@ Intrarea agentmemory este **același bloc de server MCP** pe fiecare host care f
| 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. |
+| **Cursor (plugin complet)** | `.cursor-plugin/` | Plugin-ul oferă hook-uri de ciclu de viață, identificarea workspace-ului, skill-uri și MCP în Cursor IDE și `cursor-agent`. Consultă [configurarea Cursor](#cursor). |
| **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. |
@@ -804,7 +837,8 @@ Intrarea agentmemory este **același bloc de server MCP** pe fiecare host care f
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. reamintire nativă + captură + skill-uri. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. reamintire nativă + captură + skill-uri. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +846,19 @@ Intrarea agentmemory este **același bloc de server MCP** pe fiecare host care f
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferat) sau `config.json` (vechi/legacy) | `agentmemory connect continue` creează `config.yaml` când lipsește configurarea sau modifică `config.json` existent. Pentru YAML existent afișează blocul de adăugat la `mcpServers:`, păstrând comentariile și ancorele. Continue folosește o listă, nu un obiect. |
| **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 `<repo>/.factory/mcp.json`. Transmite `--with-hooks` pentru captare automată nativă. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` activează instrumentele MCP. Adăugați `--with-hooks` pentru pluginul nativ de captură inclus în AgentMemory. Nu este necesar un pachet separat. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Folosește [exemplele REST autentificate](#validate-a-fresh-install-and-restart-persistence) pentru salvare și căutare din scripturi. |
| **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.
+Folosește [REST API](#api) din orice limbaj sau [instrumentele MCP](#mcp-server) dintr-un agent. REST utilizează JSON și autentificare bearer; vezi [exemplul de salvare și căutare](#validate-a-fresh-install-and-restart-persistence). Pentru integrarea directă a mediului, vezi [exemplele Python](../examples/python/).
### Din sursă
@@ -853,83 +867,33 @@ 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=<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).
+`npm start` pornește același server local ca CLI-ul instalat. Cerințele sunt la [Instalare](#install); API-ul și viewer-ul ascultă pe `127.0.0.1`.
### 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**
+agentmemory rulează pe Windows 10/11. WSL2 urmează calea Linux și poate instala automat engine-ul fixat. Windows nativ necesită instalarea manuală a binarului iii-engine v0.25.0 fixat; descarcă arhiva potrivită de pe [pagina de release iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verifică checksum-ul și pune `iii.exe` în `PATH` (de exemplu `%USERPROFILE%\.local\bin\iii.exe`). CLI-ul nu extrage automat arhiva ZIP pentru Windows.
-```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
-```
+Conectarea MCP automatizată pe Windows nativ acceptă doar `agentmemory connect copilot-cli`. Pentru ceilalți agenți nativi Windows, folosește blocul MCP manual din [Alți agenți](#other-agents). Rulează `connect` în WSL doar când agentul țintă este instalat în același mediu WSL.
-**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:
+**Doar MCP standalone (fără engine).** Dacă ai nevoie doar de instrumentele MCP și nu ai nevoie de REST API, vizualizator sau servicii runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Rulează `agentmemory doctor` sau repornește cu `--verbose`. Dacă porturile sunt ocupate, folosește `--port <N>` sau `--instance <N>`. Compatibilitatea și recuperarea sunt în [ghidul de actualizare](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Implementare (Deploy)</h2>
-Ș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.
+Folosește Docker Compose sau șabloanele de mai jos pentru găzduire proprie. Memoria și credențialele sunt pe volumul `/data`; fă backup și reutilizează-l la actualizare. Autentificarea, rețeaua, backup-ul și migrarea sunt în [ghidul de implementare](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Implementare pe fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Implementare pe Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Implementare pe fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Implementare pe Railway" /></a>
</p>
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.
@@ -941,27 +905,13 @@ Detaliile complete de configurare (capturarea HMAC, tunel SSH pentru vizualizato
- [`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.
+REST folosește `3111`, iar viewer-ul `3113`. Păstrează-le private sau protejează-le prin autentificare și TLS. Setările platformelor și [migrarea Docker vechi](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) sunt în ghidul de implementare.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="De ce agentmemory" height="32" /></picture></h2>
-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.
-```
+Cunoștințele proiectului sunt răspândite între conversații și fișiere de instrucțiuni. AgentMemory permite căutarea deciziilor, remediilor și lecțiilor anterioare din agentul folosit acum.
### vs memoria încorporată a agentului
@@ -969,7 +919,7 @@ Fiecare agent de programare AI vine cu memorie încorporată: Claude Code are `M
| | Încorporat (CLAUDE.md) | agentmemory |
|---|---|---|
-| Scalare | Plafon de 200 de linii | Nelimitat |
+| Întreținere | Instrucțiuni administrate manual | Istoric de sesiuni și memorie indexate |
| 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) |
@@ -995,13 +945,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Consolidarea memoriei pe 4 niveluri
@@ -1019,6 +969,8 @@ Memoriile se degradează în timp (curba lui Ebbinghaus). Memoriile accesate fre
### Ce se captează
+Tabelul descrie hook-urile Claude Code. Celelalte integrări captează evenimentele oferite de gazdă. Injectarea automată a contextului prin hook-urile comune este opțională: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Captează |
|------|----------|
| `SessionStart` | Calea proiectului, ID-ul sesiunii |
@@ -1035,7 +987,7 @@ Memoriile se degradează în timp (curba lui Ebbinghaus). Memoriile accesate fre
| Capabilitate | Descriere |
|---|---|
-| **Captare automată** | Fiecare folosire a unui instrument este înregistrată prin hook-uri, fără efort manual |
+| **Captare automată** | Evenimentele acceptate ale sesiunilor și instrumentelor, înregistrate prin integrări native |
| **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 |
@@ -1096,7 +1048,7 @@ Instalarea npm normală include runtime-ul opțional `@huggingface/transformers`
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`.
+> **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 conectează-te la un server self-hosted) și setează `AGENTMEMORY_URL=http://localhost:3111`.
### 54 de instrumente
@@ -1236,7 +1188,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Vizualizator în timp real" height="32" /></picture></h2>
-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.
+Pornește automat pe portul `3113`. Vizualizatorul încarcă un snapshot la conectare (`GET /agentmemory/viewer/snapshot`), apoi aplică evenimente live prin SSE la `/agentmemory/viewer/events`, pe worker-ul REST: memorii noi, lecții, observații, intrări de audit, schimbări în graf și actualizări de sănătate apar fără polling sau reîncărcarea paginii. Singurele alte cereri sunt acțiunile pe care dai clic, paginile „încarcă mai multe” și căutările. Când fluxul se întrerupe, vizualizatorul arată cât de vechi sunt numerele, se reconectează cu backoff și resincronizează dintr-un snapshot.
- **12 tab-uri în patru grupuri**, cu numărători live, deep link-uri (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#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.
@@ -1249,190 +1201,10 @@ Pornește automat pe portul `3113`. Vizualizatorul încarcă un instantaneu (sna
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'`).
+Serverul vizualizatorului se leagă implicit la `127.0.0.1` și atașează secretul serverului când transmite cererile către API-ul REST. Pentru un bind non-loopback, shell-ul HTML rămâne public, dar fiecare cerere proxy necesită bearer; vizualizatorul îl solicită și îl stochează în session storage. Configurează allowlist-uri explicite de host/origini și TLS înainte de a expune un vizualizator. 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'`).
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Consola iii" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Pagina Workers din consola iii: worker-i conectați, inclusiv instanțe agentmemory, cu numărători live de funcții și metadate de runtime" width="720" />
- <br/>
- <em>Pagina Workers: fiecare worker conectat, inclusiv agentmemory însuși, cu PID, numărul de funcții, runtime și ultima activitate (last-seen).</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Vizualizarea waterfall de trace din consola iii, care arată durata per span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / defalcare pe servicii, pentru fiecare operație de memorie.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Susținut de iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 de fișiere sursă · ~55,000 LOC · 3,800+ de teste · 324 de funcții · 67 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configurare" height="32" /></picture></h2>
### Furnizori LLM
@@ -1450,6 +1222,8 @@ agentmemory detectează automat furnizorii din mediul tău. Un furnizor face dis
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1499,24 +1273,7 @@ Embeddings locale vin ca o dependență opțională, dar nu sunt activate implic
### 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/).
+Începe fără cheie pentru captură și căutare după cuvinte cheie. `EMBEDDING_PROVIDER=local` activează căutarea semantică locală după descărcarea modelului. Compresia LLM necesită un furnizor și `AGENTMEMORY_AUTO_COMPRESS=true`; poate trimite o cerere pentru fiecare observație, deci verifică prețurile actuale. Viewer-ul și `agentmemory status` arată furnizorii activi.
### Memorie multi-agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1546,39 +1303,22 @@ Când `AGENT_ID` nu este setat, memoria rămâne fără scope (comportament lega
### 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 | Scop | Variabilă de mediu |
+|---|---|---|
+| `3111` | REST API, MCP HTTP și evenimente live pentru viewer | `III_REST_PORT` |
+| `3113` | Interfața viewer-ului | `III_VIEWER_PORT` |
-`--port <N>` 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.
+`--port <N>` setează portul REST și implicit viewer-ul la `N+2`. `--instance N` creează un mediu separat. Porturile interne trebuie să rămână private; citește [ghidul de implementare](../deploy/README.md) înainte de accesul la distanță.
-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.
+### Stocare: fișier sau Redis
-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 <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.
+Stocarea implicită în fișiere nu necesită o bază de date separată. Redis este opțional prin `AGENTMEMORY_STATE_BACKEND=redis` și `AGENTMEMORY_REDIS_URL`. Schimbarea backend-ului nu copiază memoria existentă. Persistența, limitele Redis și exportul/importul autentificat sunt în [ghidul de stocare](../docs/reliability/state-storage.md).
### 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.
+Pune configurația de runtime a agentmemory în `~/.agentmemory/.env`, în loc să exporți variabile în fiecare shell. Dacă vizualizatorul arată un indiciu precum `export ANTHROPIC_API_KEY=...`, copiază-l în acest fișier ca `ANTHROPIC_API_KEY=...`, fără prefixul `export`, apoi repornește agentmemory. Setează `AGENTMEMORY_ENV_FILE` pentru a folosi altă cale de fișier env.
-Variabilele de mediu ale procesului funcționează în continuare și au prioritate față de valorile din fișier.
+Variabilele de mediu ale procesului au prioritate față de fișier. Repornește serverul după schimbarea configurării.
Pe Windows, același fișier se află la `%USERPROFILE%\.agentmemory\.env`:
@@ -1605,179 +1345,30 @@ GRAPH_EXTRACTION_ENABLED=true
### Variabile de mediu
-Creează `~/.agentmemory/.env`:
+Opțiuni uzuale pentru `~/.agentmemory/.env`. Injectarea contextului și compresia sunt opționale; compresia necesită și un furnizor. Modul `core` limitează instrumentele MCP vizibile:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Referința completă [`.env.example`](../.env.example) include furnizori, filtre de captură, retenție, stocare, echipe și funcții opționale. `AGENTMEMORY_ENV_FILE` selectează alt fișier. Nu include niciodată un `.env` completat sau secretul bearer în commit-uri.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 de endpoint-uri pe portul `3111`. API-ul REST se leagă implicit la `127.0.0.1`. Endpoint-urile protejate necesită `Authorization: Bearer <secret>`, iar endpoint-urile de sincronizare mesh necesită un `AGENTMEMORY_SECRET` setat explicit pe ambii parteneri (peers).
+146 de endpoint-uri pe portul `3111`. API-ul REST se leagă implicit la `127.0.0.1`. Endpoint-urile protejate necesită `Authorization: Bearer <secret>`, 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:
+**Autentificarea este activată implicit.** Dacă `AGENTMEMORY_SECRET` nu este setat, CLI-ul generează la prima pornire un secret aleatoriu în `~/.agentmemory/secret`, cu permisiuni `0600`, și îl copiază și în directorul de date selectat. Toți clienții incluși îl citesc de acolo când comunică 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ță trebuie să seteze secretul în mediul lor. Implementările Docker self-host pornite din repository și entrypoint-urile `deploy/` își generează și exportă propriul secret. Pentru a apela API-ul manual:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1813,7 +1404,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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)
+Lista completă a endpoint-urilor: [Referința REST generată](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1831,19 +1422,19 @@ Evenimentele care eșuează sunt reîncercate la fiecare `AGENTMEMORY_CAPTURE_RE
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), `<data dir>/capture-spool/<host>-<port>.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.
+**Compactarea provenienței grafului.** Compactarea provenienței vechi este amânată la pornire deoarece citește scope-urile vechi în întregime. `/agentmemory/status` raportează `deferred`, sau `off` cu `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Rulează compactarea manuală de mai jos în timpul mentenanței. Migrarea indexului de căutare este separată: folosește `agentmemory graph-index migrate --allow-legacy-scan` conform [ghidului de mentenanță](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1857,7 +1448,7 @@ npm test # 4,000+ 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.
+Cerințele sunt la [Instalare](#install). Regulile pentru contribuții și verificările de lansare sunt în [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licență" height="32" /></picture></h2>
diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md
index b9bc6e2f..8319979f 100644
--- a/READMEs/README.ru-RU.md
+++ b/READMEs/README.ru-RU.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Ваш агент программирования помнит всё. Больше не нужно объяснять заново.
- Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Постоянная память между сессиями и агентами разработки.
</strong><br/>
- Постоянная память для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode и любого MCP-клиента.
+ Постоянная память для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode и любого MCP-клиента.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Как это работает</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Просмотрщик</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Конфигурация</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory сохраняет поддерживаемые события сессий и позволяет искать решения, исправления и уроки из разных агентов. В viewer можно просматривать, редактировать, экспортировать и удалять воспоминания. Поиск по словам работает без API-ключа; эмбеддинги добавляют семантический поиск.
+
+<a id="install"></a>
+
## Установка
Требования:
- 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 — другие поддерживаемые варианты.
+- Для автоматической настройки среды в macOS/Linux также нужны `curl`, POSIX-оболочка `sh` и `tar`.
+- В Windows используйте WSL2 или [инструкцию для нативной установки](#windows).
Каноническая команда установки с нуля:
@@ -108,11 +111,11 @@
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`.
+Выберите агентов и провайдера либо режим без ключа. Мастер сохранит настройки, запустит сервер памяти и предложит глобальную установку команды `agentmemory`. `-y` подтверждает запрос npm, `@latest` выбирает текущий выпуск. Сжатие через LLM требует провайдера и `AGENTMEMORY_AUTO_COMPRESS=true`.
Режим без ключей отключает векторные эмбеддинги. `memory_recall` (путь `mem::search`) использует BM25, а `memory_smart_search` может также сливать структурные совпадения из графа, если граф-данные уже существуют. Чтобы получить бесплатный семантический recall на устройстве, задайте `EMBEDDING_PROVIDER=local` в `~/.agentmemory/.env` и перезапустите. Первый запрос эмбеддинга скачивает `Xenova/all-MiniLM-L6-v2`; после этой первоначальной загрузки модели инференс выполняется локально.
-Локальный 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 <path>` или `AGENTMEMORY_DATA_DIR`, чтобы переопределить его, и используйте одно и то же значение при каждом перезапуске. Для обратной совместимости существующий `./data/state_store.db` или `./data/iii-config.yaml` имеет приоритет над значением по умолчанию для платформы для инстанса 0; явный флаг или переопределение через переменную окружения всё равно выигрывает.
+API доступен по `http://localhost:3111`, viewer по `http://localhost:3113`. По умолчанию оба слушают только локальные подключения. Настройки находятся в `~/.agentmemory/.env`; каталоги памяти и отдельные экземпляры описаны в разделе [хранения данных](#data-storage).
Затем убедитесь, что recall работает, и дайте агенту его skill'ы:
@@ -127,14 +130,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Подключайте дополнительных агентов в любой момент через `agentmemory connect <agent>` — 20 адаптеров перечислены в разделе [Работает с каждым агентом](#works-with-every-agent). Полный справочник команд — в разделе [Быстрый старт](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-Самый быстрый путь — WSL2. Нативная установка движка на Windows требует скачать закреплённый ZIP-архив v0.22.1 и вручную распаковать `iii.exe`; CLI не распаковывает его автоматически. Docker Desktop также поддерживается. Пошаговая инструкция — в разделе [заметки о Windows](#windows).
-
-</details>
+Подключите другого агента командой `agentmemory connect <agent>`. См. [интеграции](#works-with-every-agent) и [повседневные команды](#everyday-commands).
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx кеширует пакеты по версиям. Принудительн
</details>
-<details>
-<summary><strong>Уже запущен собственный iii engine</strong></summary>
-
-agentmemory закреплён на iii-engine v0.22.1 и не подключится к другой версии (воркер не умеет говорить на протоколе другого движка). Остановите другой движок, затем запустите `npx -y @agentmemory/agentmemory@latest`. Он установит и запустит закреплённую версию v0.22.1 в `~/.agentmemory/bin`, не трогая ваш собственный `iii`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Работает с каждым агентом" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory работает с любым агентом, который под
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>нативный плагин + 7 хуков + MCP</sub>
+<sub>нативный плагин + хуки жизненного цикла + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory работает с любым агентом, который под
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>нативный плагин + MCP</sub>
+<sub>нативное извлечение + захват + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory работает с любым агентом, который под
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP-сервер</sub>
+<sub>нативный захват + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory работает с любым агентом, который под
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>нативное извлечение + захват + skills + MCP по желанию</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ agentmemory работает с любым агентом, который под
---
-Вы объясняете одну и ту же архитектуру в каждой сессии. Вы заново находите одни и те же баги. Вы заново учите агента тем же предпочтениям. Встроенная память (CLAUDE.md, .cursorrules) упирается в потолок 200 строк и устаревает. agentmemory решает это. Он тихо фиксирует, что делает ваш агент, сжимает это в память, доступную для поиска, и подмешивает нужный контекст при старте следующей сессии. Одна команда. Работает между агентами.
+<a id="data-storage"></a>
-**Что меняется:** в сессии 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 <path>` или задайте `AGENTMEMORY_DATA_DIR`; любая явная настройка имеет приоритет над устаревшим автоопределением:
+| Платформа | Каталог данных |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Экземпляр 0 повторно использует существующий `./data/state_store.db`. Другой каталог задаётся через `--data-dir <path>` или `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
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-Нативный запуск и запуск в Docker используют один и тот же вычисленный каталог на хосте; Docker монтирует его в `/data`. `--instance 1` добавляет `instance-1` к вычисленному каталогу и выбирает отдельный квартет портов по умолчанию `3211/3212/3213/49234`.
+`--instance 1` использует подкаталог `instance-1`, порт API `3211` и viewer `3213`. Redis и миграция описаны в [руководстве по хранению и резервным копиям](../docs/reliability/state-storage.md).
Заметки о последнем релизе: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>Внешние зависимости</strong></td>
-<td>Нет (SQLite + iii-engine)</td>
+<td>Отдельный сервис базы данных не требуется</td>
<td>Qdrant / pgvector</td>
<td>Postgres + векторная БД</td>
<td>Несколько</td>
@@ -550,14 +549,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | Темпоральный граф знаний; сильнейшие опубликованные результаты на темпоральных запросах (LongMemEval 63.8%), но граф строится асинхронно, поэтому свежие факты могут запаздывать |
| Cognee | 30K | Превращение документов в граф знаний, только Python, создан для структурированного извлечения сущностей, а не для захвата сессий |
-Никто из них не делает авто-захват из хуков агентов программирования, не поставляет local-first просмотрщик и не работает без ключей — а именно вокруг этой комбинации построен agentmemory.
+AgentMemory объединяет захват сессий, поиск по истории проекта и локальный viewer; работа без ключа доступна с первого запуска.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Быстрый старт" height="32" /></picture></h2>
-Совместимость: этот релиз рассчитан на `iii-sdk` 0.22.1 и закрепляет iii-engine v0.22.1.
-
### Попробуйте за 30 секунд
```bash
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Откройте `http://localhost:3113`, чтобы смотреть, как память строится в реальном времени.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Проверка новой установки и устойчивости после перезапуска
-При запущенном сервере проверьте REST, health, просмотрщик и статус runtime на основе iii:
+При запущенном сервере проверьте здоровье, viewer и статус:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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 и активный режим провайдера/эмбеддингов. Сохраните пробный объект и убедитесь, что он находится поиском:
+`status` показывает здоровье сервера, провайдеров, режим эмбеддингов, доставку наблюдений и восстановление. Защищённые REST-запросы требуют секрет сервера. Используйте заданный `AGENTMEMORY_SECRET`, иначе загрузите сгенерированный локальный секрет:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Затем выполните `npx -y @agentmemory/agentmemory@latest stop`, снова запустите каноническую команду в Terminal 1, подождите `/agentmemory/livez` и повторите поиск. Пробный объект должен всё ещё возвращаться. Если вы указывали собственный `--data-dir`, передайте тот же каталог при перезапуске.
+<a id="everyday-commands"></a>
+
### Повседневные команды
Установка и настройка описаны в разделе [Установка](#install) выше (первый запуск проведёт вас по шагам). В повседневной работе:
@@ -604,6 +610,9 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-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 рядом с нативными. Транскрипты индексируются и получают канал происхождения `import`; обработка также может создавать кристаллы сессий и уроки.
> **Важно, если `import-jsonl` — ваш основной путь захвата:** параметр `cleanupPeriodDays` в Claude Code (в `~/.claude/settings.json`, по умолчанию **30**) автоматически удаляет JSONL-расшифровки старше этого окна из `~/.claude/projects/`. Если вы ставите agentmemory заново на историю Claude Code возрастом в несколько месяцев, всё, что старше 30 дней, уже пропало до первого импорта. Либо запускайте `import-jsonl` по cron, либо поднимите `cleanupPeriodDays`, либо подключите хуки авто-захвата (путь установки плагина по умолчанию), чтобы каждый ход попадал в agentmemory ещё во время живой сессии — тогда очистка JSONL перестаёт иметь значение.
@@ -635,14 +644,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-Внимание: эта команда изменяет текущее рабочее окружение/runtime. Она может обновлять JavaScript-зависимости и скачать закреплённый Docker-образ `iiidev/iii:0.22.1`. Она никогда не устанавливает незакреплённый или более новый iii engine.
-
-Детали реализации — в `src/cli.ts` (см. `runUpgrade` в районе `src/cli.ts:544-595`).
+Команда обновляет локальную среду и может изменить JavaScript-зависимости текущего workspace. Сделайте резервную копию данных и прочитайте [руководство по обновлению](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code без установки плагина (путь MCP-standalone)
@@ -703,6 +710,30 @@ 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'ами.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Затем в **Settings → Plugins → Add marketplace** выберите каталог agentmemory с `.cursor-plugin/plugin.json`, включите плагин **agentmemory** и перезагрузите окно. Плагин обеспечивает захват жизненного цикла, определение проекта по workspace, skills и MCP. Включайте либо хуки плагина, либо ручные хуки в `~/.cursor/hooks.json`, чтобы избежать дублирования.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Выберите команду для своего клиента. Pi и OMP устанавливают нативное извлечение памяти, захват, повторную отправку офлайн-данных и skills; `--with-mcp` добавляет полный набор инструментов. Выполните `/reload` в Pi или перезапустите OMP, затем проверьте `/agentmemory-status`. DSH устанавливает MCP и встроенный плагин захвата; после подключения перезапустите DSH.
+
+Pi также поддерживает устанавливаемый пакет `@agentmemory/pi`. Локальная установка и доступность npm описаны в [руководстве Pi](../integrations/pi/). Используйте один способ установки на клиент.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (вставьте этот промпт)</b></summary>
@@ -749,6 +780,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### Другие агенты
Запустите сервер памяти: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +798,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Это **дополняет** `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` записывает конфиг MCP-сервера, чтобы инструменты были доступны.
-- `npx skills add rohitg00/agentmemory` устанавливает skill'ы, чтобы агент знал, когда их вызывать.
+- `agentmemory connect <agent>` обычно записывает конфигурацию MCP. Hermes, OpenClaw, Pi и Oh My Pi по умолчанию устанавливают нативную интеграцию и skills; MCP включается через `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` устанавливает skills для агентов без встроенного набора. Для Hermes, OpenClaw, Pi и Oh My Pi пропустите этот шаг: их коннекторы уже устанавливают skills.
Для немногих агентов, которые skills CLI пока не покрывает (Zed v1.3.x и ниже), разложите 17 файлов SKILL.md по нативному каталогу skill'ов агента самостоятельно; тот же формат работает везде.
@@ -790,7 +823,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| Агент | Файл конфигурации | Заметки |
|---|---|---|
| **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 досчитываются из расшифровки сессии при её завершении. |
+| **Cursor (полный плагин)** | `.cursor-plugin/` | Плагин предоставляет хуки жизненного цикла, определение workspace, skills и MCP в Cursor IDE и `cursor-agent`. См. [настройку Cursor](#cursor). |
| **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` подключает шесть нативных hooks автозахвата (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) с матчерами инструментов Devin в нижнем регистре. Проверьте через `devin mcp list` и `/hooks` внутри devin. |
@@ -804,7 +837,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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'а). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. нативное извлечение + захват + skills. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. нативное извлечение + захват + skills. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +846,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (предпочтительно) или `config.json` (legacy) | `agentmemory connect continue` создаёт `config.yaml`, если настройки отсутствуют, или меняет существующий `config.json`. Для существующего YAML выводит блок для `mcpServers:`, сохраняя комментарии и якоря. Continue использует массив, а не объект. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` пишет под `context_servers` (ключ Zed, НЕ `mcpServers`). Удалённые MCP-серверы можно вместо этого подключить через `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` записывает стандартный блок `mcpServers`. Переопределения на уровне проекта — в `<repo>/.factory/mcp.json`. Передайте `--with-hooks` для нативного авто-захвата. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` включает инструменты MCP. Добавьте `--with-hooks`, чтобы загрузить встроенный в AgentMemory плагин записи событий. Отдельный пакет плагина не нужен. [DSH](../docs/dsh.md). |
| **Goose** | UI настроек 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"}'`. |
+| **Aider** | н/д | Для сохранения и поиска из скриптов используйте [REST-примеры с авторизацией](#validate-a-fresh-install-and-restart-persistence). |
| **Любой агент (32+)** | н/д | `npx skillkit install agentmemory` сам определит хост и сольёт настройки. |
**MCP-клиенты в sandbox** (Flatpak / Snap / ограничивающие контейнеры), которые не могут добраться до `localhost` хоста: дополнительно установите `"AGENTMEMORY_FORCE_PROXY": "1"` в блоке `env` и укажите `AGENTMEMORY_URL` на маршрут, до которого sandbox действительно может дотянуться (например, 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-runtime.
+Используйте [REST API](#api) из любого языка или [MCP-инструменты](#mcp-server) из агента. REST использует JSON и bearer-авторизацию; см. [пример сохранения и поиска](#validate-a-fresh-install-and-restart-persistence). Прямая интеграция среды показана в [примерах Python](../examples/python/).
### Из исходников
@@ -853,92 +867,34 @@ 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`.
+`npm start` запускает тот же локальный сервер, что и установленный CLI. Требования указаны в [Установке](#install); API и viewer слушают `127.0.0.1`.
-Установите `iii-engine` вручную. **agentmemory сейчас закреплён на `iii-engine` `v0.22.1`** — той же версии, что и его зависимость `iii-sdk`; воркер говорит на wire-протоколе именно этого движка, а 0.20.0 перестроил поверхность SDK, поэтому оба обновляются вместе в релизах agentmemory. Переопределите через `AGENTMEMORY_III_VERSION=<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`
-
-У каждого архива на странице релиза есть соответствующий файл `.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-пакета мало — также нужен закреплённый 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.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**
+agentmemory работает на Windows 10/11. В WSL2 используется путь Linux, и закреплённый движок устанавливается автоматически. Для нативной работы в Windows требуется вручную установить закреплённый бинарь iii-engine v0.25.0: скачайте подходящий архив со [страницы релиза iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), проверьте контрольную сумму и поместите `iii.exe` в `PATH` (например, `%USERPROFILE%\.local\bin\iii.exe`). CLI не распаковывает Windows ZIP автоматически.
-```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 в нативной Windows поддерживает только `agentmemory connect copilot-cli`. Для других нативных Windows-агентов используйте ручной блок MCP из раздела [Другие агенты](#other-agents). Запускайте `connect` внутри WSL только если целевой агент установлен в той же среде WSL.
-**Вариант C: только standalone MCP (без движка).** Если вам нужны только MCP-инструменты для агента и не нужны REST API, просмотрщик или cron-задачи, пропустите движок целиком:
+**Только standalone MCP (без движка).** Если нужны только MCP-инструменты, а REST API, просмотрщик и runtime-службы не нужны:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| Откат на Docker пропускается, хотя Docker установлен | Убедитесь, что Docker Desktop действительно запущен (иконка в трее) |
-
-> Примечание: 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`.
+Запустите `agentmemory doctor` или перезапустите с `--verbose`. Для занятых портов используйте `--port <N>` или `--instance <N>`. Совместимость и восстановление описаны в [руководстве по обновлению](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Развёртывание</h2>
-Шаблоны в один клик для managed-хостов. Каждый поставляет автономный
-Dockerfile, который тянет `@agentmemory/agentmemory` из npm и копирует
-бинарь движка iii из официального образа `iiidev/iii` на Docker Hub;
-собственный пресобранный образ agentmemory не нужен. Постоянное
-хранилище монтируется в `/data`; entrypoint при первом запуске
-перезаписывает поставляемый npm'ом iii-конфиг (который слушает на
-`127.0.0.1`) на вариант, настроенный для деплоя, слушающий на
-`0.0.0.0` и использующий абсолютные пути `/data`, генерирует
-HMAC-секрет, а затем понижает привилегии с `root` до `node` через
-`gosu` перед запуском CLI agentmemory.
+Для самостоятельного размещения используйте Docker Compose или шаблоны ниже. Память и учётные данные находятся на томе `/data`; сохраняйте резервную копию и повторно используйте том при обновлении. Авторизация, сеть, резервирование и миграция описаны в [руководстве по развёртыванию](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
Кнопке Render «деплой в один клик» нужен `render.yaml` в корне репозитория, который мы намеренно держим чистым. Используйте поток Render Blueprint, описанный в [`deploy/render/`](.././deploy/render/README.md), чтобы вручную указать на blueprint внутри репозитория.
@@ -955,29 +911,13 @@ HMAC-секрет, а затем понижает привилегии с `root`
VPS через [Coolify](https://coolify.io/self-hosted); тот же стек Docker
Compose, хост и данные остаются у вас.
-Публикуется только порт `3111`. Просмотрщик на `3113` остаётся
-привязанным к loopback внутри контейнера; в README каждого шаблона
-описан паттерн SSH-туннеля для доступа к нему.
+REST использует `3111`, viewer `3113`. Оставьте их в приватной сети либо защитите авторизацией и TLS. Настройки платформ и [миграция старого Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) описаны в руководстве по развёртыванию.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Зачем agentmemory" height="32" /></picture></h2>
-Каждый агент программирования забывает всё, когда сессия заканчивается, и каждая новая сессия начинается с того, что вы заново объясняете свой стек. 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.
-```
+Знания о проекте распределены между чатами и файлами инструкций. AgentMemory позволяет искать прежние решения, исправления и уроки из текущего агента.
### vs встроенная память агента
@@ -985,7 +925,7 @@ Session 2: "Now add rate limiting"
| | Встроенная (CLAUDE.md) | agentmemory |
|---|---|---|
-| Масштаб | Потолок в 200 строк | Без ограничений |
+| Обслуживание | Инструкции, редактируемые вручную | Индексируемая история сессий и воспоминания |
| Поиск | Загружает всё в контекст | BM25 + вектор + граф (только top-K) |
| Цена в токенах | 22K+ при 240 наблюдениях | ~1,900 токенов (на 92% меньше) |
| Между агентами | Файлы на каждого агента | MCP + REST (любой агент) |
@@ -1011,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-уровневая консолидация памяти
@@ -1035,6 +975,8 @@ SessionStart hook fires
### Что захватывается
+Таблица описывает хуки Claude Code. Другие интеграции захватывают события, доступные в их клиенте. Автоматическая передача контекста через общие хуки включается явно: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Хук | Захватывает |
|------|----------|
| `SessionStart` | Путь к проекту, идентификатор сессии |
@@ -1051,7 +993,7 @@ SessionStart hook fires
| Возможность | Описание |
|---|---|
-| **Автоматический захват** | Каждое использование инструмента записывается через хуки, без ручных усилий |
+| **Автоматический захват** | Поддерживаемые события сессий и инструментов, записанные нативными интеграциями |
| **Семантический поиск** | BM25 + векторный + граф знаний со слиянием RRF |
| **Эволюция памяти** | Версионирование, supersession, графы связей |
| **Гигиена recall** | Вытесненные (superseded) версии памяти покидают поисковые индексы; цепочка версий в KV хранит полную историю |
@@ -1252,7 +1194,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
<h2 id="real-time-viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Просмотрщик реального времени" height="32" /></picture></h2>
-Автоматически запускается на порту `3113`. Просмотрщик загружает один снапшот при подключении (`GET /agentmemory/viewer/snapshot`), а затем применяет события живого стрима: новые записи памяти, уроки, наблюдения, записи аудита, изменения графа и обновления состояния появляются без опроса и перезагрузок страницы. Единственные другие запросы — это действия, на которые вы кликаете, страницы «load more» и поиск. Когда стрим отваливается, просмотрщик показывает, насколько устарели его числа, переподключается с backoff и ресинхронизируется с одного снапшота.
+Автоматически запускается на порту `3113`. Просмотрщик загружает один снимок при подключении (`GET /agentmemory/viewer/snapshot`), а затем применяет живые события по SSE через `/agentmemory/viewer/events` REST-воркера: новые записи памяти, уроки, наблюдения, записи аудита, изменения графа и обновления состояния появляются без опроса и перезагрузок страницы. Единственные другие запросы — это действия, на которые вы кликаете, страницы «load more» и поиск. Когда поток прерывается, просмотрщик показывает, насколько устарели его данные, переподключается с задержкой и синхронизируется заново по одному снимку.
- **12 вкладок в четырёх группах** с живыми счётчиками, глубокими ссылками (`#memories/<id>`, `#sessions/<id>?obs=<id>`, `#graph/<id>`, `#health/consolidation`), горячими клавишами и мобильным меню.
- **Memories:** поиск на стороне сервера, фильтры по проекту, агенту и типу, панель деталей с цепочкой версий и word diff, ссылки на происхождение, кнопки копирования id, вызова MCP и команды curl, редактирование (новая версия), forget с подтверждением, массовый forget и экспорт в JSON.
@@ -1265,188 +1207,7 @@ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
open http://localhost:3113
```
-Сервер просмотрщика по умолчанию слушает на `127.0.0.1` и подставляет серверный секрет, когда перенаправляет запросы к REST API, так что отдельная настройка не нужна. Эндпоинт `/agentmemory/viewer`, отдаваемый REST'ом, подчиняется обычным правилам bearer-токена и перенаправляет браузеры без токена на порт просмотрщика. Заголовки CSP используют nonce скрипта на каждый ответ и отключают inline-атрибуты-обработчики (`script-src-attr 'none'`).
-
----
-
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-Просмотрщик на `:3113` показывает, что ваш агент **запомнил**. [iii console](https://iii.dev/docs/console) показывает, что ваш агент **сделал**: каждая операция памяти как трейс OpenTelemetry, каждая запись KV редактируема, каждая функция вызываема, каждый стрим тэппится. Два окна на одну и ту же память: одно повёрнуто к продукту, другое к движку.
-
-Наблюдайте, как срабатывает `memory_smart_search`, и видите BM25-скан → поиск эмбеддингов → RRF-слияние → reranker в виде waterfall. Отредактируйте зависший таймер консолидации в браузере KV. Воспроизведите хук `PostToolUse` с изменённым payload. Закрепите WebSocket-стрим — и смотрите, как наблюдения прилетают в реальном времени.
-
-agentmemory отдаёт это бесплатно, потому что каждый вызов функции и каждый триггер проходит через iii; ничего самописного, нечего инструментировать.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Страница Workers в iii console: подключённые воркеры, включая инстансы agentmemory, с живым числом функций и метаданными runtime" width="720" />
- <br/>
- <em>Страница Workers: каждый подключённый воркер, включая сам agentmemory, с PID, числом функций, runtime и временем последнего появления.</em>
-</p>
-
-**Уже установлено.** Console поставляется вместе с закреплённым движком `iii` (0.22+); отдельно устанавливать ничего не нужно. При первом запуске бинарь console скачивается рядом с движком.
-
-**Запуск рядом с 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
-```
-
-**Что можно делать из console:**
-
-| Страница | Зачем |
-|------|-----------|
-| **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: какие именно воркеры, провайдеры и порты использует ваш движок. |
-| **Flow** | (Опционально, `--enable-flow`) Интерактивный граф архитектуры из всех воркеров, триггеров и стримов. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Просмотр trace-waterfall в iii console с длительностью каждого span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / разбивка по сервисам для каждой операции памяти.</em>
-</p>
-
-**Traces уже включены:**
-
-`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` и укажите эндпоинт коллектора согласно документации iii по observability.
-
-> **Внимание:** на самой console аутентификация не применяется; держите её привязанной к `127.0.0.1` (по умолчанию) и никогда не выставляйте наружу.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory — это **уже работающий инстанс [iii](https://iii.dev)**. Три примитива (worker, function, trigger) составляют runtime; 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 предпочитает этот файл перед встроенным и всё равно подставляет в него порты и пути данных), добавьте запись, установите runtime воркера один раз через `~/.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-адаптер состояния, когда дефолтная in-memory KV уже мала |
-| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | Код, пришедший из `memory_recall`, исполняется внутри одноразовой VM, а не в вашем shell |
-| [`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:<scope>`, `stream:<name>:<group>`) фиксированы, поэтому два инстанса 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 вместо поиска файла файлового хранилища на диске.
-
-Одно отличие требует вашего участия: **после перезапуска 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
-
-| Традиционный стек | 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 <name>` |
-
-**250 исходных файлов · ~55,000 LOC · 3,400+ тестов · 324 функций · 67 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
+Сервер просмотрщика по умолчанию слушает на `127.0.0.1` и подставляет серверный секрет при пересылке запросов к REST API. При привязке не к loopback HTML-оболочка остаётся общедоступной, но каждый запрос прокси требует bearer-токен; просмотрщик запрашивает его и хранит в session storage. Перед публикацией настройте явные списки разрешённых хостов и origins, а также TLS. Эндпоинт `/agentmemory/viewer`, отдаваемый REST'ом, подчиняется обычным правилам bearer-токена и перенаправляет браузеры без токена на порт просмотрщика. Заголовки CSP используют nonce скрипта на каждый ответ и отключают inline-атрибуты-обработчики (`script-src-attr 'none'`).
---
@@ -1467,6 +1228,8 @@ agentmemory автоопределяет провайдеров по вашем
| **Локально (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=<your model>` | Всё, что совместимо с OpenAI API. Нулевая стоимость, работает на вашем железе. См. [Локальные модели](#local-models-ollama--lm-studio--vllm) ниже. |
| Fallback на подписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Только по согласию. Запускает сессии `@anthropic-ai/claude-agent-sdk`; раньше это приводило к неограниченной рекурсии Stop-хука, поэтому больше не включено по умолчанию. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Локальные модели (Ollama / LM Studio / vLLM)
agentmemory разговаривает с любым сервером, совместимым с OpenAI API, поэтому всё, что раскрывает `/v1/chat/completions`, работает без изменений кода. Никаких платных ключей, облака и rate-limit'ов; выполняется целиком на вашем железе.
@@ -1516,24 +1279,7 @@ OPENAI_MODEL=qwen3-8b # match the model name from LM St
### Выбор модели с учётом стоимости
-Когда фоновое сжатие, написанное 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 (оценка) | Модель флагманского класса; перерасход на сжатие. |
-
-Замеренные строки взяты из зафиксированного прогона; строки «(оценка)» масштабируют тот же микс токенов по прайс-листу каждой модели.
-
-agentmemory выводит runtime-предупреждение, когда `OPENROUTER_MODEL` совпадает с шаблоном premium-уровня. Установите `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/).
+Начните без ключа для захвата и поиска по словам. `EMBEDDING_PROVIDER=local` включает локальный семантический поиск после загрузки модели. Сжатие LLM требует провайдера и `AGENTMEMORY_AUTO_COMPRESS=true`; запрос возможен для каждого наблюдения, поэтому проверьте актуальные цены. Viewer и `agentmemory status` показывают активных провайдеров.
### Мультиагентная память (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,39 +1309,22 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### Порты
-agentmemory + iii-engine по умолчанию занимают четыре порта. Если перезапуск падает с `port in use`, эта таблица подскажет, какой процесс искать.
-
-| Порт | Процесс | Назначение | Override через env |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `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 | Назначение | Переменная окружения |
+|---|---|---|
+| `3111` | REST API, MCP HTTP и события viewer в реальном времени | `III_REST_PORT` |
+| `3113` | Интерфейс viewer | `III_VIEWER_PORT` |
-`--port <N>` меняет якорь REST и выводит из него streams `N+1`, просмотрщик `N+2` и WebSocket движка `N+46023`, но только там, где соответствующий явный порт или URL выше не задан. Это не создаёт изолированный lifecycle-namespace. Используйте `--instance 1` для второго демона; он использует якорь 3211, по умолчанию даёт `3211/3212/3213/49234` и получает отдельный каталог данных и lifecycle `instance-1`. Инстансы с 1 по 50 следуют тому же паттерну.
+`--port <N>` задаёт REST-порт и по умолчанию viewer на `N+2`. `--instance N` создаёт отдельную среду. Внутренние порты должны оставаться приватными; перед внешним доступом прочитайте [руководство по развёртыванию](../deploy/README.md).
-Закреплённый движок запускается с `--no-update-check` (без обращения к GitHub за обновлениями или security-advisory при загрузке) и с выключенной анонимной телеметрией использования iii: agentmemory задаёт `III_TELEMETRY_ENABLED=false` для порождаемого им движка, если вы не экспортировали эту переменную сами, и встроенный compose-файл делает то же самое.
+### Хранилище: файл или Redis
-Очистка зависших процессов, если порты остаются занятыми после падения:
-
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
-
-`agentmemory stop` аккуратно вычищает и воркер, и pidfile движка при штатном нативном завершении. В режиме Docker она сбрасывает нативный воркер, останавливает именно тот проверенный контейнер движка и сохраняет и контейнер, и его том `/data` для безвозвратного перезапуска; следующий запуск проверяет и возобновляет тот же контейнер. Удаление при работе через Docker требует `agentmemory remove --keep-data`: она удаляет общие файлы, управляемые agentmemory, сохраняя при этом проверенный контейнер, его том данных и запись о жизненном цикле, нужную для их восстановления. Деструктивное удаление данных Docker намеренно оставлено оператору — после бэкапа. CLI также отказывается принимать за нативный движок или сигналить держателям портов из Docker или VM (Docker backend, vpnkit, colima), пока не передан `--force`. Ручная очистка выше нужна только в посткрэшевом сценарии, когда ни один pidfile не остался.
+Файловое хранилище по умолчанию не требует отдельной базы. Redis включается через `AGENTMEMORY_STATE_BACKEND=redis` и `AGENTMEMORY_REDIS_URL`. Смена backend не переносит существующую память. Надёжность записи, ограничения Redis и авторизованный экспорт/импорт описаны в [руководстве по хранению](../docs/reliability/state-storage.md).
### Конфигурационный файл
Помещайте runtime-конфигурацию agentmemory в `~/.agentmemory/.env`, а не экспортируйте переменные в каждой сессии shell. Если просмотрщик показывает подсказку настройки вида `export ANTHROPIC_API_KEY=...`, скопируйте её в этот файл как `ANTHROPIC_API_KEY=...` без префикса `export`, затем перезапустите agentmemory.
-Переменные окружения процесса по-прежнему работают и имеют приоритет над значениями из файла.
+Переменные окружения процесса имеют приоритет над файлом. После изменения настроек перезапустите сервер.
В Windows тот же файл лежит в `%USERPROFILE%\.agentmemory\.env`:
@@ -1622,176 +1351,27 @@ GRAPH_EXTRACTION_ENABLED=true
### Переменные окружения
-Создайте `~/.agentmemory/.env`:
+Основные параметры `~/.agentmemory/.env`. Передача контекста и сжатие включаются явно; сжатие также требует провайдера. Режим `core` ограничивает видимые MCP-инструменты:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Полный справочник [`.env.example`](../.env.example) включает провайдеров, фильтры захвата, сроки хранения, хранилище, команды и дополнительные функции. `AGENTMEMORY_ENV_FILE` выбирает другой файл. Никогда не коммитьте заполненный `.env` или bearer-секрет.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 эндпоинтов на порту `3111`. REST API по умолчанию слушает на `127.0.0.1`. Защищённые эндпоинты требуют `Authorization: Bearer <secret>`, а эндпоинты mesh-синхронизации требуют явно заданного `AGENTMEMORY_SECRET` на обоих узлах.
+146 эндпоинтов на порту `3111`. REST API по умолчанию слушает на `127.0.0.1`. Защищённые эндпоинты требуют `Authorization: Bearer <secret>`, а эндпоинты 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 вручную:
+**Аутентификация включена по умолчанию.** Если `AGENTMEMORY_SECRET` не задан, при первом запуске CLI создаёт случайный секрет в `~/.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
@@ -1830,7 +1410,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Расшарить в команду |
| `GET` | `/agentmemory/audit` | Аудит-журнал |
-Полный список эндпоинтов: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Полный список эндпоинтов: [Сгенерированный справочник REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1428,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
Когда сервер недоступен, не отвечает вовремя или возвращает 5xx, хук добавляет наблюдение в локальный spool-файл `<data dir>/capture-spool/<host>-<port>.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`, чтобы отключить его.
+**Усечение происхождения графа.** Усечение старых данных происхождения откладывается при запуске, поскольку оно читает старые области целиком. `/agentmemory/status` сообщает `deferred` или `off` при `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Выполняйте описанное ниже ручное усечение во время обслуживания. Миграция поискового индекса выполняется отдельно: используйте `agentmemory graph-index migrate --allow-legacy-scan` согласно [руководству по обслуживанию](../docs/reliability/graph-index-migration.md).
Чтобы запустить его вручную, вызовите `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1454,7 @@ npm test # 4,000+ 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.
+Требования указаны в [Установке](#install). Правила участия и проверки выпуска находятся в [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Лицензия" height="32" /></picture></h2>
diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.md
index d29d37ee..0b6266fc 100644
--- a/READMEs/README.sv-SE.md
+++ b/READMEs/README.sv-SE.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Din kodningsagent minns allt. Inget mer återförklarande.
- Byggt på <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Beständigt minne mellan kodningssessioner och agenter.
</strong><br/>
- Beständigt minne för Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode och alla MCP-klienter.
+ Beständigt minne för Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode och alla MCP-klienter.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Licens" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stjärnor" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Så fungerar det</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Drivs av iii</a> &bull;
<a href="#configuration">Konfig</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory registrerar kodningssessioner och gör beslut, lösningar och lärdomar sökbara. Dela ett gemensamt lager mellan agenter, granska det sparade innehållet och välj hur mycket kontext modellen får.
+
+<a id="install"></a>
+
## 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.
+- På macOS/Linux kräver automatisk installation också `curl`, en POSIX-`sh` och `tar`.
+- Använd WSL2 på Windows eller följ [installationen för native Windows](#windows).
Det kanoniska kommandot för en ny installation:
@@ -108,11 +111,11 @@ Det kanoniska kommandot för en ny installation:
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.
+Välj agenter och en leverantör, eller använd läget utan nyckel. Installationen skriver konfigurationen, startar minnesservern och erbjuder en global installation av kommandot `agentmemory`. `-y` godkänner npm-frågan; `@latest` väljer aktuell version. LLM-komprimering är valfri och kräver en leverantör samt `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+API:t finns på `http://localhost:3111` och viewern på `http://localhost:3113`. Båda lyssnar som standard på loopback. Konfigurationen finns i `~/.agentmemory/.env`; se [datalagring](#data-storage) för sökvägar och separata instanser.
Bevisa sedan att återkallning fungerar och ge din agent dess skills:
@@ -127,14 +130,7 @@ Föredrar du att låta en kodningsagent sköta hela installationen? Ge den en en
> 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 <agent>` — 20 adaptrar listade under [Fungerar med alla agenter](#works-with-every-agent). Fullständig kommandoreferens finns under [Snabbstart](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Anslut en annan agent med `agentmemory connect <agent>`. Se [integrationer](#works-with-every-agent) och [vardagskommandon](#everyday-commands).
<details>
<summary><strong>Global installation / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx cachar per version. Tvinga fram den senaste med `npx -y @agentmemory/agentme
</details>
-<details>
-<summary><strong>Kör redan din egen iii-engine</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Fungerar med alla agenter" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. All
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>inbyggd plugin + 7 hooks + MCP</sub>
+<sub>inbyggt tillägg + livscykel-hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. All
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>inbyggd plugin + MCP</sub>
+<sub>inbyggd sökning + registrering + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. All
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP-server</sub>
+<sub>inbyggd registrering + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. All
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>inbyggd sökning + registrering + skills + Valfri MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,23 +306,25 @@ agentmemory fungerar med alla agenter som stöder hooks, MCP eller REST API. All
---
-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.
+<a id="data-storage"></a>
-**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.
+### Datalagring
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Minnen lagras som standard utanför ditt repo:
-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 <path>` eller sätt `AGENTMEMORY_DATA_DIR`; båda explicita inställningarna har företräde framför den äldre upptäckten:
+| Plattform | Datamapp |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Instans 0 återanvänder en befintlig `./data/state_store.db`. Välj en annan sökväg med `--data-dir <path>` eller `AGENTMEMORY_DATA_DIR` och behåll den vid omstarter och uppgraderingar. `--instance 1` använder undermappen `instance-1`, API-port `3211` och viewer-port `3213`. Se [lagring och säkerhetskopiering](../docs/reliability/state-storage.md) för Redis och migrering.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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).
---
@@ -476,7 +473,7 @@ Senaste versionsanteckningarna: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Externa beroenden</strong></td>
-<td>Inga (SQLite + iii-engine)</td>
+<td>Ingen separat databastjänst behövs</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektor-DB</td>
<td>Flera</td>
@@ -550,14 +547,12 @@ Senaste versionsanteckningarna: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+AgentMemory kombinerar registrering från kodningsagenter, sökbar projekthistorik och en lokal viewer. Du kan arbeta utan nyckel från första starten.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Snabbstart" height="32" /></picture></h2>
-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
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Öppna `http://localhost:3113` för att se minnet byggas upp i realtid.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Validera en ny installation och omstarts-persistens
-Med servern igång, validera REST, hälsostatus, viewern och den iii-baserade körtidsstatusen:
+Kontrollera hälsa, viewer och status medan servern körs:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` visar serverns tillstånd samt aktiva leverantörer och embeddings. Spara ett testminne och kontrollera sökningen:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Vardagskommandon
Installation och konfiguration finns under [Installation](#install) ovan (den första körningen guidar dig genom det). Till vardags:
@@ -623,7 +627,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Importerade sessioner dyker upp i Replay-väljaren tillsammans med de ursprungliga. 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.
@@ -635,14 +639,12 @@ Använd underhållskommandot när du avsiktligt vill uppdatera din lokala körti
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`).
+Kommandot uppdaterar den lokala körtiden och kan uppdatera JavaScript-beroenden i den aktuella arbetsytan. Säkerhetskopiera dina data och läs [uppgraderingsguiden](../docs/upgrades/iii-0.25.md) innan du fortsätter.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code utan plugin-installationen (fristående MCP-väg)
@@ -703,6 +705,28 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Lägg sedan till det inbyggda tillägget från en AgentMemory-utcheckning via **Settings → Plugins → Add marketplace** och ladda om fönstret. Tillägget ger livscykelregistrering, projekttilldelning, skills och MCP. Aktivera antingen tilläggets hooks eller manuella hooks i `~/.cursor/hooks.json` för att undvika dubbel registrering. [Cursor-guide](../integrations/cursor/).
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Välj kommandot för din värd. Pi och OMP installerar sökning, registrering, offline-återsändning och 17 skills; `--with-mcp` lägger till alla verktyg. Kör `/reload` i Pi eller starta om OMP och kontrollera `/agentmemory-status`. DSH installerar MCP och det medföljande registreringstillägget; starta om DSH efteråt.
+
+Pi stöder även det installerbara paketet `@agentmemory/pi`. [Pi-guiden](../integrations/pi/) beskriver lokal installation och tillgänglighet på npm. Använd en installationsmetod per värd.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (klistra in denna prompt)</b></summary>
@@ -749,6 +773,8 @@ Fullständig guide: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Andra agenter
Starta minnesservern: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +791,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Detta är ett **komplement** till `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+- `agentmemory connect <agent>` skriver normalt MCP-konfigurationen. Hermes, OpenClaw, Pi och Oh My Pi installerar som standard sin inbyggda integration och medföljande skills; MCP läggs till med `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` installerar skills för agenter utan medföljande inbyggda skills. Hoppa över detta steg för Hermes, OpenClaw, Pi och Oh My Pi: deras anslutningar installerar redan dessa skills.
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.
@@ -790,7 +816,7 @@ agentmemory-posten är **samma MCP-serverblock** på alla värdar som använder
| 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. |
+| **Cursor (fullständigt plugin)** | `.cursor-plugin/` | Lägg sedan till det inbyggda tillägget från en AgentMemory-utcheckning via **Settings → Plugins → Add marketplace** och ladda om fönstret. Tillägget ger livscykelregistrering, projekttilldelning, skills och MCP. Aktivera antingen tilläggets hooks eller manuella hooks i `~/.cursor/hooks.json` för att undvika dubbel registrering. [Cursor-guide](../integrations/cursor/). |
| **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. |
@@ -804,7 +830,7 @@ agentmemory-posten är **samma MCP-serverblock** på alla värdar som använder
| **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). |
+| **Pi / Oh My Pi** | `~/.pi/agent/` / `~/.omp/agent/` | inbyggd sökning + registrering + skills. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +838,19 @@ agentmemory-posten är **samma MCP-serverblock** på alla värdar som använder
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (att föredra) eller `config.json` (äldre) | `agentmemory connect continue` skapar en saknad `config.yaml` eller ändrar befintlig `config.json`. Om YAML-filen finns visas blocket för `mcpServers:` så att kommentarer och ankare bevaras. Continue använder en array, inte ett objekt. |
| **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 `<repo>/.factory/mcp.json`. Ange `--with-hooks` för inbyggd auto-infångning. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` aktiverar MCP-verktyg. Lägg till `--with-hooks` för att läsa in det inbyggda registreringstillägget som följer med AgentMemory. Inget separat tilläggspaket behövs. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | Använd de [autentiserade REST-exemplen](#validate-a-fresh-install-and-restart-persistence) för att spara och söka efter minnen från skript. |
| **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.
+Använd [REST API:t](#api) från valfritt språk eller [MCP-verktygen](#mcp-server) från en agent. REST använder JSON och bearer-autentisering; se [exemplet för lagring och sökning](#validate-a-fresh-install-and-restart-persistence). [Python-exemplen](../examples/python/) visar direkt integration med körtiden.
### Från källkod
@@ -853,83 +859,34 @@ 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`.
+`npm start` startar samma lokala server som den installerade CLI:n. Kraven finns under [Install](#install); API och viewer lyssnar på `127.0.0.1`.
-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=<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)**
+agentmemory körs på Windows 10/11. WSL2 följer Linux-vägen och kan installera den fastlåsta enginen automatiskt. Native Windows kräver att den fastlåsta iii-engine v0.25.0-binären installeras manuellt: ladda ner rätt arkiv från [iii v0.25.0-utgåvan](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), verifiera kontrollsumman och placera `iii.exe` på `PATH` (till exempel `%USERPROFILE%\.local\bin\iii.exe`). CLI:n packar inte upp Windows-ZIP-filen automatiskt.
-```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
-```
+Automatiserad MCP-inkoppling på native Windows stöder bara `agentmemory connect copilot-cli`. För andra native Windows-agenter använder du det manuella MCP-blocket från [Andra agenter](#other-agents). Kör `connect` i WSL endast om målagenten är installerad i samma WSL-miljö.
-**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:
+**Endast fristående MCP (ingen engine).** Om du bara behöver MCP-verktyg och inte REST API, viewern eller runtime-tjänster:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Kör `agentmemory doctor` eller starta om med `--verbose`. Använd `--port <N>` eller `--instance <N>` om portarna är upptagna. Se [uppgraderingsguiden](../docs/upgrades/iii-0.25.md) för kompatibilitet och återställning.
---
<h2 id="deploy">Driftsättning</h2>
-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.
+Driv tjänsten med Docker Compose eller mallarna nedan. Minnen och autentiseringsuppgifter finns på `/data`-volymen. Säkerhetskopiera och återanvänd volymen vid uppgradering. [Driftsättningsguiden](../deploy/README.md) beskriver autentisering, nätverk, säkerhetskopiering och migrering.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
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.
@@ -946,28 +903,26 @@ Fullständiga installationsdetaljer (HMAC-infångning, SSH-tunnel för viewern,
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.
+REST använder port `3111`; viewern använder `3113`. Håll dem privata eller skydda dem med autentisering och TLS. Driftsättningsguiden beskriver nätverksåtkomst och [migrering av äldre Docker-installationer](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Varför agentmemory" height="32" /></picture></h2>
-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.
+Projektkunskap sprids mellan chattar och instruktionsfiler. AgentMemory gör tidigare beslut, lösningar och lärdomar sökbara från den agent du använder nu.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### Jämfört med inbyggt agentminne
@@ -976,7 +931,7 @@ Varje AI-kodningsagent levereras med inbyggt minne: Claude Code har `MEMORY.md`,
| | Inbyggt (CLAUDE.md) | agentmemory |
|---|---|---|
-| Skala | Tak på 200 rader | Obegränsat |
+| Underhåll | Manuellt underhållna instruktioner | Indexerad sessionshistorik och minnen |
| 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) |
@@ -1002,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-nivås minneskonsolidering
@@ -1026,6 +981,8 @@ Minnen klingar av över tid (Ebbinghaus-kurvan). Ofta använda minnen förstärk
### Vad som fångas in
+Tabellen beskriver Claude Codes hooks. Andra integrationer registrerar de händelser som deras värd erbjuder; se respektive guide. Automatisk kontextinjektion via delade hooks aktiveras med `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Fångar in |
|------|----------|
| `SessionStart` | Projektsökväg, sessions-ID |
@@ -1042,7 +999,7 @@ Minnen klingar av över tid (Ebbinghaus-kurvan). Ofta använda minnen förstärk
| Funktion | Beskrivning |
|---|---|
-| **Automatisk infångning** | Varje verktygsanvändning registreras via hooks, inget manuellt arbete |
+| **Automatisk infångning** | Inbyggda integrationer registrerar sessions- och verktygshändelser som stöds |
| **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 |
@@ -1260,187 +1217,6 @@ Viewer-servern binder till `127.0.0.1` som standard och bifogar serverhemlighete
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii-konsolen" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii-konsolens Workers-sida: anslutna workers, inklusive agentmemory-instanser, med live funktionsantal och körtidsmetadata" width="720" />
- <br/>
- <em>Workers-sidan: varje ansluten worker, inklusive agentmemory självt, med PID, funktionsantal, körtid och senast sedd.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii-konsolens vattenfallsvy för spår som visar varaktighet per span" width="720" />
- <br/>
- <em>Traces: vattenfall/flame/tjänsteuppdelning för varje minnesoperation.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Drivs av iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) ä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 <name>` |
-
-**250 källkodsfiler · ~55,000 LOC · 3,400+ tester · 324 funktioner · 67 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfiguration" height="32" /></picture></h2>
### LLM-leverantörer
@@ -1458,6 +1234,8 @@ agentmemory upptäcker leverantörer automatiskt från din miljö. En leverantö
| **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=<din modell>` | 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1507,24 +1285,7 @@ Lokala embeddings levereras som ett valfritt beroende men är inte aktiverade so
### 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/).
+Börja utan nyckel för registrering och nyckelordssökning. `EMBEDDING_PROVIDER=local` aktiverar lokal semantisk sökning efter den första modellnedladdningen. LLM-komprimering kräver en leverantör och `AGENTMEMORY_AUTO_COMPRESS=true`; den kan skicka en begäran per observation. Kontrollera aktuella priser först. Viewern och `agentmemory status` visar aktiva leverantörer.
### Multiagent-minne (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1554,39 +1315,22 @@ När `AGENT_ID` inte är satt förblir minnet oscopat (äldre beteende, inga tag
### 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 <N>` ä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.
+| Port | Syfte | Konfiguration |
+|---|---|---|
+| `3111` | REST API, MCP HTTP, SSE | `III_REST_PORT` |
+| `3113` | Viewer UI | `III_VIEWER_PORT` |
-Rensning av gamla processer när portar förblir bundna efter en kraschad körning:
+`--port <N>` anger API-porten och som standard viewern på `N+2`. Använd `--instance N` för en separat instans. Håll interna portar privata; läs [driftsättningsguiden](../deploy/README.md) innan du tillåter fjärråtkomst.
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Lagringsbackend: fil (standard) kontra redis
-`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.
+Standardlagringen använder filer och kräver ingen separat databastjänst. Redis är valfritt med `AGENTMEMORY_STATE_BACKEND=redis` och `AGENTMEMORY_REDIS_URL`. Ett byte av backend kopierar inga minnen. Se [lagring och säkerhetskopiering](../docs/reliability/state-storage.md) för beständighet, Redis-begränsningar och autentiserad export/import.
### 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.
+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. Sätt `AGENTMEMORY_ENV_FILE` för att använda en annan env-fil.
-Processens miljövariabler fungerar fortfarande och har företräde framför värden i filen.
+Processens miljövariabler har företräde framför filens värden. Starta om servern efter konfigurationsändringar.
På Windows finns samma fil på `%USERPROFILE%\.agentmemory\.env`:
@@ -1613,179 +1357,32 @@ GRAPH_EXTRACTION_ENABLED=true
### Miljövariabler
-Skapa `~/.agentmemory/.env`:
+Vanliga alternativ för `~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Den fullständiga referensen finns i [`.env.example`](../.env.example): autentiseringsuppgifter, registreringsfilter, lagringstid, lagring, teamavgränsning och tillval. `AGENTMEMORY_ENV_FILE` väljer en annan fil. Lägg aldrig till en ifylld `.env` eller bearer-hemlighet i git.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoints på port `3111`. REST API:et binder till `127.0.0.1` som standard. Skyddade endpoints kräver `Authorization: Bearer <secret>`, och mesh-synk-endpoints kräver en explicit satt `AGENTMEMORY_SECRET` på båda parterna.
+146 endpoints på port `3111`. REST API:et binder till `127.0.0.1` som standard. Skyddade endpoints kräver `Authorization: Bearer <secret>`, 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:
+**Autentisering är aktiverad som standard.** Om `AGENTMEMORY_SECRET` inte är angiven i skalet eller i `~/.agentmemory/.env` skapar CLI:n en slumpmässig hemlighet vid första starten i `~/.agentmemory/secret` och en kopia med namnet `secret` i den valda datamappen, med filbehörigheten `0600`. Alla medföljande klienter läser den därifrån när de ansluter till en lokal server: CLI:n, viewern, hookarna under `plugin/scripts`, MCP-servern och `@agentmemory/mcp`-shimmen, konfigurationerna skrivna av `agentmemory connect` samt 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` har alltid företräde; fjärrklienter behöver hemligheten i sin miljö. Docker-baserad self-hosting från repot och startpunkterna i `deploy/` genererar och exporterar en egen hemlighet. För att anropa API:et för hand:
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1821,7 +1418,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Dela med team |
| `GET` | `/agentmemory/audit` | Granskningsspår |
-Fullständig endpoint-lista: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Fullständig endpoint-lista: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1839,19 +1436,19 @@ Misslyckade händelser får nya försök var `AGENTMEMORY_CAPTURE_RETRY_INTERVAL
När servern är nere, inte svarar i tid eller returnerar en 5xx, lägger hooken till observationen i en lokal spool-fil, `<data dir>/capture-spool/<host>-<port>.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.
+**Kompaktering av grafursprung.** Kompaktering av äldre ursprungsdata skjuts upp vid start eftersom den läser hela äldre scopes. `/agentmemory/status` visar `deferred`, eller `off` med `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Kör den manuella kompakteringen nedan under underhåll. Migrering av sökindexet är separat: använd `agentmemory graph-index migrate --allow-legacy-scan` enligt [underhållsguiden](../docs/reliability/graph-index-migration.md).
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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1865,7 +1462,7 @@ npm test # 4,000+ 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.
+[Install](#install) · [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Licens" height="32" /></picture></h2>
diff --git a/READMEs/README.th-TH.md b/READMEs/README.th-TH.md
index aaf0d548..e92636f8 100644
--- a/READMEs/README.th-TH.md
+++ b/READMEs/README.th-TH.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Coding agent ของคุณจดจำได้ทุกอย่าง ไม่ต้องอธิบายซ้ำอีกต่อไป
- Built on <a href="https://github.com/iii-hq/iii">iii engine</a>
+ หน่วยความจำถาวรข้ามเซสชันเขียนโค้ดและเอเจนต์
</strong><br/>
- หน่วยความจำถาวรสำหรับ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode และ MCP client ใดก็ได้
+ หน่วยความจำถาวรสำหรับ Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode และ MCP client ใดก็ได้
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">วิธีการทำงาน</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">ขับเคลื่อนด้วย iii</a> &bull;
<a href="#configuration">การตั้งค่า</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory บันทึกเซสชันเขียนโค้ดเพื่อให้ค้นคืนการตัดสินใจและวิธีแก้ปัญหาได้ ใช้คลังความจำเดียวกันในหลายเครื่องมือ ตรวจสอบข้อมูลที่บันทึก และเลือกปริมาณบริบทที่ส่งให้โมเดล
+
## Install
ข้อกำหนดเบื้องต้น:
- Node.js 20 หรือใหม่กว่า พร้อม npm และ npx (`node -v`, `npm -v`, และ `npx -v`)
-- การติดตั้ง iii-engine แบบอัตโนมัติบน macOS/Linux ต้องมี `curl`, POSIX `sh`, และ `tar` ด้วย อิมเมจแบบมินิมอล เช่น `node:20-slim` อาจไม่มีสิ่งเหล่านี้ติดมา
-- Windows แบบ native ต้องติดตั้ง `iii.exe` เวอร์ชัน iii-engine v0.22.1 ที่ pin ไว้ด้วยตนเอง ส่วน WSL2 หรือ Docker Desktop เป็นอีกสองทางเลือกที่รองรับ
+- การตั้งค่าอัตโนมัติบน macOS/Linux ต้องมี `curl`, POSIX `sh` และ `tar`
+- Windows / WSL2: [Windows](#windows).
คำสั่งติดตั้งใหม่แบบมาตรฐาน:
@@ -108,11 +109,11 @@
npx -y @agentmemory/agentmemory@latest
```
-การรันครั้งแรกจะเป็นการตั้งค่าแบบโต้ตอบ: เลือก agent ที่ต้องการเชื่อมต่อ (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...) เลือก LLM provider หรือจะไม่ใส่ key เลยก็ได้ จากนั้นระบบจะสร้างไฟล์ config เริ่มต้น memory server และ iii engine เวอร์ชันที่ pin ไว้ พร้อมเสนอให้ติดตั้งแบบ global เพื่อให้คำสั่ง `agentmemory` เปล่า ๆ ใช้งานได้จากทุกที่หลังจากนี้ `-y` เป็นการยอมรับ prompt ของแพ็กเกจจาก npx และ `@latest` ช่วยเลี่ยง release เก่าที่อาจถูกแคชไว้ การตั้งค่า provider จะทำให้ฟีเจอร์ LLM พร้อมใช้งาน แต่การบีบอัด observation ด้วย LLM จะเริ่มทำงานก็ต่อเมื่อตั้งค่า `AGENTMEMORY_AUTO_COMPRESS=true` เพิ่มเข้าไปด้วย
+เลือกเอเจนต์และผู้ให้บริการ หรือใช้โหมดไม่ต้องมีคีย์ การตั้งค่าจะบันทึกคอนฟิก เริ่มเซิร์ฟเวอร์ความจำ และเสนอการติดตั้งแบบ global `-y` ยอมรับคำถามจาก npm ส่วน `@latest` เลือกรุ่นล่าสุด การบีบอัดด้วย LLM ต้องมีทั้งผู้ให้บริการและ `AGENTMEMORY_AUTO_COMPRESS=true`
โหมด keyless จะปิดการใช้งาน vector embedding `memory_recall` (เส้นทาง `mem::search`) ใช้ BM25 ในขณะที่ `memory_smart_search` ยังสามารถผสาน structural graph เข้ามาด้วยได้หากมีข้อมูล graph อยู่แล้ว หากต้องการ semantic recall แบบออนดีไวซ์โดยไม่มีค่าใช้จ่าย ให้ตั้งค่า `EMBEDDING_PROVIDER=local` ใน `~/.agentmemory/.env` แล้ว restart คำขอ embedding ครั้งแรกจะดาวน์โหลดโมเดล `Xenova/all-MiniLM-L6-v2` หลังจากดาวน์โหลดครั้งแรกแล้ว การ inference จะทำงานในเครื่องทั้งหมด
-runtime ที่รันในเครื่องใช้ 4 พอร์ต ได้แก่ `3111` สำหรับ REST/MCP HTTP, `3112` สำหรับ iii stream, `3113` สำหรับ viewer, และ `49134` สำหรับ iii worker WebSocket สถานะถาวรของ iii จะถูกเก็บไว้ที่ `~/Library/Application Support/agentmemory` บน macOS, `$XDG_DATA_HOME/agentmemory` หรือ `~/.local/share/agentmemory` บน Linux, และ `%APPDATA%\agentmemory` บน Windows ใช้ `--data-dir <path>` หรือ `AGENTMEMORY_DATA_DIR` เพื่อเปลี่ยนตำแหน่งนี้ และใช้ค่าเดิมซ้ำทุกครั้งที่ restart เพื่อความเข้ากันได้กับเวอร์ชันก่อนหน้า หากมี `./data/state_store.db` หรือ `./data/iii-config.yaml` อยู่แล้ว ไฟล์เหล่านี้จะถูกใช้ก่อนค่า default ของแพลตฟอร์มสำหรับ instance 0 ส่วน flag หรือ environment variable ที่ตั้งไว้อย่างชัดเจนยังคงมีสิทธิ์เหนือกว่าเสมอ
+API อยู่ที่ `http://localhost:3111` และตัวดูข้อมูลสดที่ `http://localhost:3113` ทั้งคู่ใช้ loopback ตามค่าเริ่มต้น คอนฟิกอยู่ใน `~/.agentmemory/.env` [การจัดเก็บข้อมูล](#data-storage).
จากนั้นพิสูจน์ว่าการ recall ทำงานได้จริง และให้ agent ของคุณมี skill ไว้ใช้:
@@ -127,14 +128,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-เชื่อมต่อ agent เพิ่มได้ทุกเมื่อด้วย `agentmemory connect <agent>` — ดู adapter ทั้ง 20 ตัวที่ [Works with every agent](#works-with-every-agent) รายการคำสั่งแบบเต็มอยู่ที่ [Quick Start](#quick-start)
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-ทางที่เร็วที่สุดคือ WSL2 การตั้งค่า engine บน Windows แบบ native ต้องดาวน์โหลดไฟล์ ZIP ของ v0.22.1 ที่ pin ไว้ และแตกไฟล์ `iii.exe` ด้วยตนเอง CLI จะไม่แตกไฟล์ให้โดยอัตโนมัติ Docker Desktop ก็รองรับเช่นกัน ดูขั้นตอนแบบละเอียดได้ที่ [Windows notes](#windows)
-
-</details>
+เพิ่มเอเจนต์ด้วย `agentmemory connect <agent>` ดู[การเชื่อมต่อที่รองรับ](#works-with-every-agent)และ[คำสั่งประจำวัน](#everyday-commands)
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx จะแคชไว้ตามเวอร์ชัน บังคับ
</details>
-<details>
-<summary><strong>Already running your own iii engine</strong></summary>
-
-agentmemory pin iii-engine ไว้ที่ `v0.22.1` และจะไม่เชื่อมต่อกับเวอร์ชันอื่น (worker พูดโปรโตคอลของ engine เวอร์ชันอื่นไม่ได้) ให้หยุด engine ตัวอื่นก่อน แล้วรัน `npx -y @agentmemory/agentmemory@latest` มันจะติดตั้งและรัน v0.22.1 ที่ pin ไว้ใน `~/.agentmemory/bin` โดยไม่แตะต้อง `iii` ของคุณเองเลย
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="ใช้งานได้กับทุก agent" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory ใช้งานได้กับ agent ใดก็ตามท
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>ปลั๊กอิน native + lifecycle hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory ใช้งานได้กับ agent ใดก็ตามท
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>recall แบบ native + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory ใช้งานได้กับ agent ใดก็ตามท
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>capture แบบ native + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory ใช้งานได้กับ agent ใดก็ตามท
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>recall แบบ native + capture + skills + MCP เสริม</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +304,24 @@ agentmemory ใช้งานได้กับ agent ใดก็ตามท
---
-คุณต้องอธิบายโครงสร้างระบบเดิมซ้ำทุกเซสชัน ค้นพบบั๊กเดิม ๆ ซ้ำแล้วซ้ำอีก และสอน preference เดิมซ้ำไปซ้ำมา หน่วยความจำแบบ built-in (CLAUDE.md, .cursorrules) จำกัดอยู่ที่ 200 บรรทัดและเก่าไปเรื่อย ๆ agentmemory แก้ปัญหานี้ มันเก็บทุกสิ่งที่ agent ของคุณทำอย่างเงียบ ๆ บีบอัดให้เป็นหน่วยความจำที่ค้นหาได้ และฉีด context ที่ถูกต้องเข้าไปเมื่อเซสชันถัดไปเริ่มต้น แค่คำสั่งเดียว ใช้งานได้ข้าม agent
+<a id="data-storage"></a>
-**สิ่งที่เปลี่ยนไป:** เซสชันที่ 1 คุณตั้งค่า JWT auth เซสชันที่ 2 คุณขอ rate limiting agent รู้อยู่แล้วว่า auth ของคุณใช้ jose middleware ใน `src/middleware/auth.ts` test ของคุณครอบคลุมการตรวจสอบ token และคุณเลือก jose เหนือ jsonwebtoken เพื่อความเข้ากันได้กับ Edge โดยไม่ต้องอธิบายซ้ำและไม่ต้อง copy-paste
+### การจัดเก็บข้อมูล
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+ความจำถูกเก็บไว้นอก repository ตามค่าเริ่มต้น instance 0 ใช้ `./data/state_store.db` ที่มีอยู่แล้วซ้ำได้ เลือกตำแหน่งด้วย `--data-dir <path>` หรือ `AGENTMEMORY_DATA_DIR` และใช้ไดเรกทอรีเดิมเมื่อเริ่มใหม่หรืออัปเกรด
-โดย default 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` แบบเดิมมีอยู่แล้ว ไฟล์เหล่านั้นจะถูกใช้สำหรับ instance 0 ก่อนค่า default ของแพลตฟอร์ม หากต้องการเลือกตำแหน่งอย่างชัดเจน ใช้ `--data-dir <path>` หรือตั้งค่า `AGENTMEMORY_DATA_DIR`; การตั้งค่าอย่างชัดเจนทั้งสองแบบมีสิทธิ์เหนือกว่าการค้นหาแบบเดิม:
+| แพลตฟอร์ม | ไดเรกทอรีข้อมูล |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-การรันแบบ native และ Docker ใช้ host directory ที่ resolve แล้วตัวเดียวกันนี้ Docker จะ bind-mount ไว้ที่ `/data` `--instance 1` จะต่อท้าย `instance-1` เข้ากับ directory ที่ resolve แล้ว และเลือกชุดพอร์ตค่า default แยกชุดคือ `3211/3212/3213/49234`
+`--instance 1` ใช้ไดเรกทอรีย่อย `instance-1` พอร์ต API `3211` และตัวดูข้อมูล `3213` อ่านเรื่อง Redis และการย้าย backend ใน[การจัดเก็บและสำรองข้อมูล](../docs/reliability/state-storage.md)
ดูรายละเอียด release ล่าสุดได้ที่: [CHANGELOG.md](../CHANGELOG.md)
@@ -474,7 +469,7 @@ Top-5 hit rate 100% ที่ **เพดานทางคณิตศาสต
</tr>
<tr>
<td><strong>External deps</strong></td>
-<td>ไม่มี (SQLite + iii-engine)</td>
+<td>ไม่ต้องมีบริการฐานข้อมูลแยก</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>หลายตัว</td>
@@ -548,14 +543,12 @@ Top-5 hit rate 100% ที่ **เพดานทางคณิตศาสต
| Zep / Graphiti | 30K | Temporal knowledge graph; ผลลัพธ์ temporal-query ที่เผยแพร่แล้วแข็งแกร่งที่สุด (LongMemEval 63.8%) แต่ graph สร้างแบบ asynchronous จึงอาจตามข้อมูลใหม่ไม่ทัน |
| Cognee | 30K | การนำ document เข้าสู่ knowledge graph, รองรับแค่ Python, สร้างมาเพื่อดึง structured entity มากกว่าการ capture เซสชัน |
-ไม่มีตัวใดใน list นี้ที่ auto-capture จาก hook ของ coding agent, มี viewer แบบ local-first ในตัว หรือรันแบบ keyless ได้ — ชุดความสามารถนี้คือสิ่งที่ agentmemory ถูกสร้างขึ้นมาเพื่อรองรับโดยเฉพาะ
+AgentMemory รวมการบันทึกเซสชัน ประวัติโปรเจ็กต์ที่ค้นหาได้ และตัวดูข้อมูลในเครื่อง พร้อมใช้งานแบบไม่ต้องมีคีย์ตั้งแต่ครั้งแรก
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="เริ่มต้นใช้งานอย่างรวดเร็ว" height="32" /></picture></h2>
-ความเข้ากันได้: release นี้ตั้งเป้าใช้กับ `iii-sdk` 0.22.1 และ pin iii-engine ไว้ที่ v0.22.1
-
### Try it in 30 seconds
```bash
@@ -572,7 +565,7 @@ npx -y @agentmemory/agentmemory@latest demo
### Validate a fresh install and restart persistence
-ขณะที่ server รันอยู่ ให้ตรวจสอบ REST, health, viewer, และสถานะของ runtime ที่ขับเคลื่อนด้วย iii:
+ขณะเซิร์ฟเวอร์ทำงาน ให้ตรวจสุขภาพ ตัวดูข้อมูล และสถานะ
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -581,14 +574,19 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-หน้าพร้อมใช้งานตอนเริ่มระบบครอบคลุมทั้ง 4 พอร์ต: REST/MCP HTTP บน 3111, iii stream บน 3112, viewer บน 3113, และ iii worker WebSocket บน 49134 `status` จะยืนยัน health ของ agentmemory และ provider/embedding mode ที่ใช้งานอยู่ บันทึก probe หนึ่งตัวแล้วตรวจว่าค้นหาเจอจริง:
+`status` แสดงสุขภาพเซิร์ฟเวอร์ ผู้ให้บริการ โหมด embedding การส่ง capture และการกู้คืน คำขอ REST ที่ป้องกันไว้ต้องใช้รหัสลับเซิร์ฟเวอร์ ใช้ `AGENTMEMORY_SECRET` ที่ตั้งไว้ หรืออ่านรหัสลับในเครื่องที่ระบบสร้างหากยังไม่ได้ตั้ง
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
@@ -602,7 +600,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -621,7 +622,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
-เซสชันที่ import เข้ามาจะปรากฏใน Replay picker ควบคู่กับเซสชันแบบ native เบื้องหลัง แต่ละรายการจะผ่าน iii function ได้แก่ `mem::replay::load`, `mem::replay::sessions`, และ `mem::replay::import-jsonl` โดยไม่มี side-channel server ใด ๆ transcript ที่ import แต่ละตัวจะถูก index เพื่อค้นหา ประทับ origin channel เป็น `import` และถูกนำไปสร้างเป็น session crystal และ lesson
+เซสชันที่นำเข้าปรากฏใน Replay ร่วมกับเซสชัน native มีดัชนีค้นหาและระบุช่องทางต้นทาง `import` การประมวลผลเซสชันอาจสร้าง crystal และบทเรียนด้วย
> **ข้อควรทราบหากคุณใช้ `import-jsonl` เป็นเส้นทาง capture หลัก:** `cleanupPeriodDays` ของ Claude Code (ใน `~/.claude/settings.json`, default **30**) จะลบ JSONL transcript ที่เก่ากว่า window นั้นออกจาก `~/.claude/projects/` โดยอัตโนมัติ ถ้าคุณติดตั้ง agentmemory ใหม่บน history ของ Claude Code ที่มีมาหลายเดือน อะไรที่เก่ากว่า 30 วันก็หายไปแล้วก่อนการ import ครั้งแรก ให้เลือกอย่างใดอย่างหนึ่ง: รัน `import-jsonl` แบบ cron, เพิ่มค่า `cleanupPeriodDays` ให้สูงขึ้น หรือเชื่อมต่อ hook แบบ auto-capture (เส้นทางติดตั้ง plugin แบบ default) เพื่อให้แต่ละ turn เข้าสู่ agentmemory ตั้งแต่เซสชันยังรันอยู่ จนการลบ JSONL ไม่มีผลอีกต่อไป
@@ -633,14 +634,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-คำเตือน: คำสั่งนี้จะแก้ไข workspace/runtime ปัจจุบัน มันสามารถอัปเดต dependency ของ JavaScript และดึง Docker image `iiidev/iii:0.22.1` ที่ pin ไว้ได้ มันจะไม่ติดตั้ง iii engine ที่ไม่ได้ pin หรือเวอร์ชันใหม่กว่าเด็ดขาด
-
-รายละเอียดการ implement อยู่ใน `src/cli.ts` (ดู `runUpgrade` รอบ ๆ ส่วน `src/cli.ts:544-595`)
+คำสั่งนี้อัปเดต runtime ในเครื่อง และอาจอัปเดต dependency ของ JavaScript ในไดเรกทอรีทำงานด้วย สำรองข้อมูลและอ่าน[คู่มืออัปเกรด](../docs/upgrades/iii-0.25.md)ก่อนอัปเดตการติดตั้งเดิม
### Claude Code (one block, paste it)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code without the plugin install (MCP-standalone path)
@@ -701,6 +700,26 @@ copilot plugin install rohitg00/agentmemory:plugin
`agentmemory connect copilot-cli` จะ merge `mcpServers.agentmemory` เข้าไปใน `~/.copilot/mcp-config.json` (หรือ `$COPILOT_HOME/mcp-config.json` เมื่อตั้งค่า `COPILOT_HOME`) และยังคง server อื่น ๆ ที่มีอยู่ไว้ บน native Windows นี่คือ adapter `connect` แบบอัตโนมัติตัวเดียวที่ใช้ได้ ส่วน agent native ของ Windows ตัวอื่น ๆ ทุกตัวต้องตั้งค่าเอง WSL `connect` รองรับก็เฉพาะเมื่อ agent ปลายทางถูกติดตั้งอยู่ใน WSL environment เดียวกันนั้นด้วย Copilot จะรับ MCP server ในการเปิดครั้งถัดไปหรือหลังจากสั่ง `/mcp` ติดตั้ง plugin เพิ่มเมื่อคุณต้องการประสบการณ์ hook/skill แบบเต็ม
+### Cursor
+
+ตั้งค่า MCP ด้วย `agentmemory connect cursor` ใน **Settings → Plugins → Add marketplace** เลือก checkout ที่มี `.cursor-plugin/plugin.json` เปิด agentmemory และ reload ปลั๊กอินให้ lifecycle capture การระบุ workspace skills และ MCP เปิดเฉพาะ hook ของปลั๊กอินหรือ hook ที่ตั้งเองใน `~/.cursor/hooks.json` อย่างใดอย่างหนึ่งเพื่อไม่ให้บันทึกซ้ำ
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+เลือกคำสั่งให้ตรงกับ host Pi และ OMP ติดตั้ง recall/capture แบบ native การส่งซ้ำออฟไลน์ และ 17 skills ส่วน `--with-mcp` เพิ่มเครื่องมือทั้งหมด รัน `/reload` ใน Pi หรือเริ่ม OMP ใหม่ แล้วตรวจ `/agentmemory-status` DSH ติดตั้ง MCP และปลั๊กอิน capture ที่รวมมา ให้เริ่ม DSH ใหม่หลังเชื่อมต่อ
+
+Pi รองรับแพ็กเกจ `@agentmemory/pi` ด้วย ดูการติดตั้งในเครื่องและสถานะบน npm ใน[คู่มือ Pi](../integrations/pi/) ใช้วิธีติดตั้งเพียงแบบเดียวต่อ host
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (paste this prompt)</b></summary>
@@ -763,8 +782,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
สิ่งนี้ **เสริม** `agentmemory connect <agent>` ไม่ได้แทนที่กัน:
-- `agentmemory connect <agent>` เขียน config ของ MCP server เพื่อให้เครื่องมือพร้อมใช้งาน
-- `npx skills add rohitg00/agentmemory` ติดตั้ง skill เพื่อให้ agent รู้ว่าต้องเรียกใช้เมื่อไหร่
+ตัวเชื่อมต่อ Hermes, OpenClaw, Pi และ Oh My Pi ติดตั้งการเชื่อมต่อ native และ skills ตามค่าเริ่มต้น เพิ่ม MCP ด้วย `--with-mcp` ส่วน host อื่นใช้ `npx skills add rohitg00/agentmemory` เพื่อติดตั้ง skills ได้
สำหรับ agent ไม่กี่ตัวที่ skills CLI ยังไม่ครอบคลุม (Zed v1.3.x และเก่ากว่า) ให้วางไฟล์ SKILL.md ทั้ง 17 ไฟล์ลงใน native skill directory ของ agent นั้นด้วยตัวเอง รูปแบบเดียวกันนี้ใช้ได้ทุกที่
@@ -788,12 +806,12 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| Agent | Config file | หมายเหตุ |
|---|---|---|
| **Cursor (MCP only)** | `~/.cursor/mcp.json` | Merge เข้าไปใน `mcpServers`, หรือใช้ `agentmemory connect cursor` มี one-click deeplink บนเว็บไซต์ด้วย |
-| **Cursor (full plugin)** | `.cursor-plugin/` | รายการใน Cursor Marketplace (อยู่ระหว่างการตรวจสอบ) หรือ Cursor Settings → Plugins → local checkout ลงทะเบียน auto-capture hook 7 ตัว (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + skill 17 ตัว + MCP server โดย `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` ถูกจัดการใน Cursor's plugin dashboard ใช้งานได้ทั้งใน Cursor IDE และ CLI `cursor-agent`; prompt ของ CLI print-mode จะถูก backfill จาก session transcript ตอนจบเซสชัน |
+| **Cursor (full plugin)** | `.cursor-plugin/` | ติดตั้งผ่าน Cursor Marketplace หรือ Settings → Plugins → local checkout ใช้ adapter ขนาดเล็กเรียก `plugin/scripts/*.mjs` ร่วมเพื่อลงทะเบียน lifecycle hooks พร้อม skills และ MCP adapter ระบุ workspace ที่ Cursor รายงานได้ไม่แน่นอน ดู [Cursor](#cursor) ใช้ได้กับ Cursor IDE และ CLI `cursor-agent` |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge เข้าไปใน `mcpServers` restart Claude Desktop หลังแก้ไฟล์ |
| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | ใช้ `mcpServers` block เดียวกัน |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` จะ merge รายการ MCP; `--with-hooks` เพิ่ม native auto-capture hook หกตัว (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) ด้วย tool matcher แบบตัวพิมพ์เล็กของ Devin ตรวจสอบด้วย `devin mcp list` และ `/hooks` ภายใน devin |
| **Devin CLI (full plugin)** | `plugin/.devin-plugin/` | `devin plugins install ./plugin` จาก checkout จะลงทะเบียน skill ทั้ง 17 ตัวเป็นคำสั่ง slash `/agentmemory:<skill>` รวมถึง MCP server ด้วย plugin hook ของ Devin ไม่สามารถยิง `SessionStart`/`SessionEnd` ได้ ดังนั้นให้ใช้คู่กับ `connect devin --with-hooks` เพื่อ capture เซสชันแบบเต็ม |
-| **Devin (cloud)** | Settings → Connections → MCP servers | เพิ่ม custom MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` ชี้ไปยัง agentmemory deployment ที่เข้าถึงได้ทางเครือข่าย พร้อม `AGENTMEMORY_SECRET` (เซสชัน cloud เข้าถึง localhost ไม่ได้ — ดู [`deploy/`](../deploy/)) เก็บ secret ไว้ใน Devin Secrets แล้วใช้ "Test listing tools" เพื่อตรวจว่าเครื่องมือครบทั้ง 54 ตัวปรากฏขึ้น |
+| **Devin (cloud)** | Settings → Connections → MCP servers | เพิ่ม custom MCP (STDIO): command `npx`, args `-y @agentmemory/mcp@latest`, env `AGENTMEMORY_URL` ชี้ไปยัง agentmemory deployment ที่เข้าถึงได้ทางเครือข่าย พร้อม `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` (merge อัตโนมัติ) |
| **GitHub Copilot CLI (MCP only)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli` จะ merge `mcpServers.agentmemory`; Copilot จะรับค่าในการเปิดครั้งถัดไปหรือ `/mcp` |
| **GitHub Copilot CLI (full plugin)** | ติดตั้ง plugin ของ Copilot | `copilot plugin install rohitg00/agentmemory:plugin` สำหรับ plugin จาก GitHub subdir |
@@ -802,7 +820,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` แล้ว `codex plugin add agentmemory@agentmemory` ลงทะเบียน MCP + lifecycle hook 6 ตัว + skill 17 ตัว ต้อง trust hook และ verify การ capture ใน host ของคุณ ดู [การ setup และ validate Codex](../docs/plugins/codex-local.md) |
| **OpenCode (MCP only)** | `opencode.json` | รูปแบบต่างออกไป: key ระดับบนสุดคือ `mcp`, command เป็น array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}` |
| **OpenCode (full plugin)** | `plugin/opencode/` | auto-capture hook 22 ตัว ครอบคลุม session lifecycle, message, tool, error การระบุ project เป็นแบบต่อเซสชัน ดังนั้น OpenCode process เดียวที่ครอบคลุมหลาย repository จะเก็บแต่ละเซสชันไว้ใน project ของตัวเอง มีคำสั่ง slash สองตัว (`/recall`, `/remember`) copy `plugin/opencode/` เข้าไปใน OpenCode workspace ของคุณแล้วเพิ่มรายการ plugin ลงใน `opencode.json` ดู [`plugin/opencode/README.md`](../plugin/opencode/README.md) สำหรับตาราง hook แบบเต็มพร้อม gap analysis |
-| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi` จะติดตั้ง extension ที่ bundle มาเข้าไปใน auto-discovery directory ของ pi (recall ตอน agent เริ่ม, capture ตอน agent จบ, เครื่องมือ `memory_search` / `memory_save` / `memory_health`, `/agentmemory-status`) `/reload` ใน pi ที่กำลังรันอยู่จะรับค่านี้ [`integrations/pi`](../integrations/pi/) ยังเป็น pi package ด้วย (`pi install ./integrations/pi` จาก checkout) |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · recall แบบ native + capture + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · recall แบบ native + capture + skills. [Oh My Pi](../integrations/omp/) |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` จะให้ memory provider แบบ 6-hook (prefetch, turn capture, 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` block แบบมาตรฐาน payload ของ hook เข้ากันได้กับ Claude Code ดังนั้น hook script 12 ตัวที่มีอยู่ใช้งานได้โดยไม่ต้องแก้ไข เชื่อมต่อผ่าน section `hooks` ใน `settings.json` เดียวกัน |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` จะติดตั้ง MCP และ capture hook ไว้ใน shared customization directory ดู [การตั้งค่าและข้อจำกัดของ Antigravity](../docs/plugins/antigravity.md) |
@@ -810,39 +829,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro` เขียน config ระดับ user การ override ระดับ workspace ไปอยู่ที่ `.kiro/settings/mcp.json` ข้าง ๆ โค้ดของคุณ |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp` เขียน `mcpServers` block แบบมาตรฐาน Warp ยัง auto-discover skill จาก `.claude/skills/` ด้วย เมื่อติดตั้ง Claude Code plugin แล้ว skill ทั้ง 8 ตัวของ agentmemory (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) จะปรากฏใน slash-command palette ของ Warp โดยตรง |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline` เขียน `mcpServers` block แบบมาตรฐาน ผู้ใช้ VS Code extension: paste 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 ที่ต้อง paste ใต้ `mcpServers:` ออกมาให้ตรง ๆ มันจะไม่เขียนทับไฟล์ yaml ของคุณแบบเงียบ ๆ เพราะการรักษา comment และ anchor ให้ปลอดภัยต้องใช้ YAML parser ที่แพ็กเกจนี้ไม่ได้ ship มาด้วย Continue ใช้ array (ไม่ใช่ object) สำหรับ `mcpServers` |
+| **Continue.dev** | `~/.continue/config.yaml` (แนะนำ) หรือ `config.json` (รุ่นเก่า) | `agentmemory connect continue` สร้าง `config.yaml` เมื่อยังไม่มีคอนฟิก หรืออัปเดต `config.json` ที่มีอยู่ สำหรับ YAML เดิมจะเก็บ comment และ anchor ไว้โดยไม่แก้ไฟล์ แต่แสดงบล็อกให้วางใต้ `mcpServers:` ซึ่ง Continue ใช้รูปแบบ array |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` เขียนไว้ใต้ `context_servers` (key ของ Zed ไม่ใช่ `mcpServers`) MCP server แบบ remote เชื่อมต่อผ่าน `{"url": "..."}` ได้เช่นกัน |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` เขียน `mcpServers` block แบบมาตรฐาน การ override ระดับ project ไปอยู่ที่ `<repo>/.factory/mcp.json` ใส่ `--with-hooks` เพื่อ auto-capture แบบ native |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` เปิดใช้งานเครื่องมือ MCP เพิ่ม `--with-hooks` เพื่อโหลดปลั๊กอินบันทึกแบบเนทีฟที่รวมอยู่ใน AgentMemory โดยไม่ต้องติดตั้งแพ็กเกจปลั๊กอินแยกต่างหาก [DSH](../docs/dsh.md). |
| **Goose** | Goose MCP settings UI | ใช้ `mcpServers` block เดียวกัน; ใช้ `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"}'` |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **Any agent (32+)** | n/a | `npx skillkit install agentmemory` จะตรวจจับ host อัตโนมัติและ merge ให้ |
**MCP client แบบ sandbox** (Flatpak / Snap / container ที่จำกัด) ที่เข้าถึง `localhost` ของ host ไม่ได้: ให้ตั้งค่า `"AGENTMEMORY_FORCE_PROXY": "1"` เพิ่มใน `env` block ด้วย และชี้ `AGENTMEMORY_URL` ไปยัง route ที่ sandbox เข้าถึงได้จริง (เช่น LAN IP ของคุณ)
-### Programmatic access (Python / Rust / Node)
-
-agentmemory ลงทะเบียน core operation ของมันเป็น iii function (`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()
+### Programmatic access
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-ตัวอย่างแบบทำงานได้จริง: [`examples/python/`](../examples/python/) (quickstart + observation/recall flow) REST บน `:3111` ยังใช้งานได้สำหรับ host ที่ไม่มี iii runtime
+ใช้ [REST API](#api) จากภาษาใดก็ได้ หรือ [เครื่องมือ MCP](#mcp-server) จากเอเจนต์ REST ใช้ JSON และการยืนยันตัวตนแบบ Bearer ดู[ตัวอย่างบันทึกและค้นหา](#validate-a-fresh-install-and-restart-persistence) ส่วนการเชื่อมต่อ runtime โดยตรงมีใน[ตัวอย่าง Python](../examples/python/)
### From source
@@ -851,130 +850,70 @@ git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
-คำสั่งนี้จะเริ่ม agentmemory ด้วย `iii-engine` ในเครื่อง ถ้า binary ที่ pin ไว้ติดตั้งอยู่แล้ว หรือใช้ Docker Compose เมื่อเลือกไว้ REST, stream, และ viewer จะ bind กับ `127.0.0.1` โดย default เส้นทางติดตั้ง binary แบบอัตโนมัติบน macOS/Linux ต้องมี `curl`, POSIX `sh`, และ `tar`
-
-ติดตั้ง `iii-engine` ด้วยตนเอง **agentmemory ปัจจุบัน pin `iii-engine` ไว้ที่ `v0.22.1`** ซึ่งเป็น release เดียวกับ dependency `iii-sdk` ของมัน worker พูดโปรโตคอล wire ของ engine เวอร์ชันนั้น และ 0.20.0 ได้จัดโครงสร้าง SDK surface ใหม่ ดังนั้นทั้งสองจึงต้องเคลื่อนไปด้วยกันใน release ของ agentmemory override ได้ด้วย `AGENTMEMORY_III_VERSION=<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` คู่กันอยู่บนหน้า release; เมื่อคุณสลับ platform ให้ใช้ hash จากไฟล์นั้นในการตรวจสอบข้างบน (บน Windows: `Get-FileHash`) ตัวติดตั้งอัตโนมัติใน `npx @agentmemory/agentmemory` pin hash เหล่านี้ไว้ และจะปฏิเสธ archive ที่ไม่ตรงกัน
-
-หรือใช้ Docker (`docker-compose.yml` ที่ bundle มาจะดึง `iiidev/iii:0.22.1`) เอกสารฉบับเต็ม: [iii.dev/docs](https://iii.dev/docs)
+`npm start` เริ่มเซิร์ฟเวอร์ในเครื่องแบบเดียวกับ CLI ที่ติดตั้งไว้ ดูข้อกำหนดใน[การติดตั้ง](#install) API และตัวดูข้อมูลใช้ `127.0.0.1`
### Windows
-agentmemory รันบน Windows 10/11 ได้ แต่แพ็กเกจ Node.js เพียงอย่างเดียวยังไม่พอ คุณต้องมี iii-engine v0.22.1 runtime ที่ pin ไว้รันเป็น background process ด้วย CLI จะไม่แตก ZIP ของ Windows ให้โดยอัตโนมัติ ดังนั้นผู้ใช้ Windows แบบ native ต้องติดตั้ง `iii.exe` ด้วยตนเอง ใช้ WSL2 หรือเลือก Docker Desktop
+agentmemory รองรับ Windows 10/11; WSL2 ใช้ขั้นตอน Linux และติดตั้ง engine อัตโนมัติได้ Windows แบบ native ต้องติดตั้งไบนารี iii-engine v0.25.0 ด้วยตนเอง ดาวน์โหลด archive จาก [หน้า release iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), ตรวจ checksum และวาง `iii.exe` บน `PATH` (เช่น `%USERPROFILE%\.local\bin\iii.exe`) CLI ไม่แตก Windows ZIP ให้อัตโนมัติ
-การเชื่อมต่อ MCP แบบอัตโนมัติบน native Windows รองรับเฉพาะ `agentmemory connect copilot-cli` สำหรับ Claude Code, Codex, Cursor, และ agent native ของ Windows ตัวอื่น ๆ ทั้งหมด ให้ copy MCP block แบบ manual จาก [Other agents](#other-agents) ไปวางในไฟล์ config ของ agent นั้นบน Windows การรัน `connect` ใน WSL เหมาะสมก็เฉพาะเมื่อ agent ปลายทางถูกติดตั้งอยู่ใน WSL environment เดียวกันนั้นด้วย มันจะไม่แก้ config ของ agent บน Windows host
+การตั้งค่า MCP อัตโนมัติบน Windows รองรับเฉพาะ `agentmemory connect copilot-cli`; สำหรับ agent อื่นให้ใช้ MCP block ใน [Other agents](#other-agents) เรียก `connect` ใน WSL เมื่อ agent เป้าหมายติดตั้งใน WSL เดียวกันเท่านั้น
-**ตัวเลือก A: prebuilt Windows binary (แนะนำ)**
-
-```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: standalone MCP only (ไม่มี engine)** ถ้าคุณต้องการแค่เครื่องมือ MCP สำหรับ agent ของคุณ และไม่ต้องการ REST API, viewer, หรือ cron job ก็ข้าม engine ไปได้เลย:
+**ใช้ MCP แบบ standalone โดยไม่เปิด engine** หากไม่ต้องใช้ REST API, viewer หรือ runtime service:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**การวินิจฉัยปัญหาบน Windows:** ถ้า `npx -y @agentmemory/agentmemory@latest` ล้มเหลว ให้รันซ้ำพร้อม `--verbose` เพื่อดู engine stderr ตัวจริง สาเหตุที่พบบ่อย:
-
-| อาการ | วิธีแก้ |
-|---|---|
-| `The engine process started but the REST API never responded.` | ตรวจสอบว่าพอร์ตที่ derive มาทั้ง 4 ว่างอยู่ ตรวจว่า `iii.exe` ที่ pin ไว้ยังรันอยู่ จากนั้นรันซ้ำพร้อม `--verbose` และตรวจ engine stderr ที่จับไว้ |
-| `Could not start iii-engine` | ไม่มีทั้ง `iii.exe` และ Docker ติดตั้งอยู่ ดูตัวเลือก A หรือ B ด้านบน |
-| Port conflict | `netstat -ano \| findstr :3111` เพื่อดูว่ามีอะไร bind พอร์ตนั้นอยู่ แล้ว kill มัน หรือใช้ `--port <N>` |
-| Docker fallback ถูกข้ามแม้ว่า Docker ติดตั้งอยู่ | ตรวจให้แน่ใจว่า Docker Desktop กำลังรันอยู่จริง (ไอคอนใน system tray) |
-
-> หมายเหตุ: iii **engine** เป็น binary ที่ build มาสำเร็จแล้ว ไม่ใช่ cargo crate ดังนั้นอย่า `cargo install` มัน (iii **SDK** เผยแพร่อยู่บน crates.io, npm, และ PyPI แต่ agentmemory ไม่ต้องใช้มัน) วิธีติดตั้ง engine ที่รองรับทั้งหมด pin ไว้ที่ v0.22.1: prebuilt binary ด้านบน, เส้นทาง auto-install ของ agentmemory บน macOS/Linux (ต้องมี `curl`, POSIX `sh`, และ `tar`), และ Docker image `iiidev/iii:0.22.1` การรัน `install.sh | sh` แบบ upstream เปล่า ๆ จะติดตั้ง engine เวอร์ชันล่าสุด ซึ่ง agentmemory ไม่รองรับ ใช้ `npx -y @agentmemory/agentmemory@latest`; บน macOS/Linux มันจะดึง engine ที่ pin ไว้มาไว้ที่ `~/.agentmemory/bin`
+รัน `agentmemory doctor` หรือเริ่มใหม่ด้วย `--verbose` หากพอร์ตเริ่มต้นถูกใช้ ให้เลือก `--port <N>` หรือ `--instance <N>` ดูความเข้ากันได้และการกู้คืนใน[คู่มืออัปเกรด](../docs/upgrades/iii-0.25.md)
---
<h2 id="deploy">Deploy</h2>
-เทมเพลตแบบ one-click สำหรับ managed host ทุกตัวมาพร้อม
-Dockerfile แบบ self-contained ที่ดึง `@agentmemory/agentmemory` จาก npm และ copy
-iii engine binary มาจาก Docker Hub image `iiidev/iii` อย่างเป็นทางการ
-ไม่ต้องมี agentmemory image ที่ build มาสำเร็จแล้วเลย Persistent storage
-mount อยู่ที่ `/data`; entrypoint ตอน boot ครั้งแรกจะเขียนทับ
-iii config ที่ bundle มากับ npm (ซึ่ง bind `127.0.0.1`) ด้วย
-config ที่ปรับมาสำหรับ deploy ซึ่ง bind `0.0.0.0` และใช้ `/data` path แบบ absolute, สร้าง
-HMAC secret แล้วจึงลด privilege จาก `root` ไปเป็น `node` ผ่าน
-`gosu` ก่อน exec agentmemory CLI
+โฮสต์เองด้วย Docker Compose หรือเทมเพลตแพลตฟอร์มด้านล่าง ความจำและข้อมูลรับรองอยู่ใน volume `/data` สำรองและใช้ volume เดิมเมื่ออัปเกรด ดูการยืนยันตัวตน เครือข่าย และการย้ายระบบใน[คู่มือ deploy](../deploy/README.md)
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
-ปุ่ม one-click deploy ของ Render ต้องการ `render.yaml` ที่ root ของ repository ซึ่งเราตั้งใจเก็บให้สะอาดอยู่เสมอ ใช้ Render Blueprint flow ตามที่เขียนไว้ใน [`deploy/render/`](.././deploy/render/README.md) เพื่อชี้ไปยัง blueprint ใน repo ด้วยตนเอง
+ปุ่ม one-click deploy ของ Render ต้องการ `render.yaml` ที่ root ของ repository ซึ่งเราตั้งใจเก็บให้สะอาดอยู่เสมอ ใช้ Render Blueprint flow ตามที่เขียนไว้ใน [`../deploy/render/`](.././deploy/render/README.md) เพื่อชี้ไปยัง blueprint ใน repo ด้วยตนเอง
รายละเอียดการตั้งค่าแบบเต็ม (การ capture HMAC, viewer SSH tunnel, rotation, backup,
-cost floor) อยู่ที่ [`deploy/`](.././deploy/README.md):
+cost floor) อยู่ที่ [`../deploy/`](.././deploy/README.md):
-- [`deploy/fly`](.././deploy/fly/README.md): machine เดียว พร้อม
+- [`../deploy/fly`](.././deploy/fly/README.md): machine เดียว พร้อม
`auto_stop_machines = "stop"`; ค่า idle ถูกที่สุด
-- [`deploy/railway`](.././deploy/railway/README.md): แผน Hobby แบบเหมาจ่าย,
+- [`../deploy/railway`](.././deploy/railway/README.md): แผน Hobby แบบเหมาจ่าย,
volume อยู่ใน dashboard
-- [`deploy/render`](.././deploy/render/README.md): Blueprint flow,
+- [`../deploy/render`](.././deploy/render/README.md): Blueprint flow,
disk snapshot อัตโนมัติบนแผนที่เสียเงิน
-- [`deploy/coolify`](.././deploy/coolify/README.md): self-host บน VPS ของ
+- [`../deploy/coolify`](.././deploy/coolify/README.md): self-host บน VPS ของ
คุณเองผ่าน [Coolify](https://coolify.io/self-hosted); Docker
Compose stack เดียวกัน คุณเป็นเจ้าของทั้ง host และข้อมูล
-มีเพียงพอร์ต `3111` เท่านั้นที่ publish viewer บน `3113` ยังคง bind อยู่กับ
-loopback ภายใน container; README ของทุกเทมเพลตมีคำอธิบาย
-pattern การทำ SSH-tunnel เพื่อเข้าถึงมัน
+REST ใช้พอร์ต `3111` และตัวดูข้อมูลใช้ `3113` ให้จำกัดการเข้าถึงเป็นส่วนตัวหรือป้องกันด้วยการยืนยันตัวตนและ TLS ดูการเปิดเข้าถึงของแต่ละแพลตฟอร์มและ[การย้าย Docker รุ่นเก่า](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)ในคู่มือ deploy
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="ทำไมต้อง agentmemory" height="32" /></picture></h2>
-coding agent ทุกตัวจะลืมทุกอย่างเมื่อเซสชันจบลง และเซสชันใหม่ทุกครั้งก็ต้องเริ่มด้วยการให้คุณอธิบาย stack ของคุณซ้ำอีกครั้ง agentmemory ทำงานอยู่เบื้องหลังและตัดขั้นตอนนั้นออกไป
+ความรู้ของโปรเจ็กต์มักกระจายอยู่ในแชตและไฟล์คำแนะนำ 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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### vs built-in agent memory
@@ -983,7 +922,7 @@ coding agent ที่ใช้ AI ทุกตัวมีหน่วยคว
| | Built-in (CLAUDE.md) | agentmemory |
|---|---|---|
-| Scale | จำกัดที่ 200 บรรทัด | ไม่จำกัด |
+| การดูแล | คำสั่งที่จัดการด้วยตนเอง | ประวัติเซสชันและความจำที่จัดทำดัชนี |
| Search | โหลดทุกอย่างเข้า context | BM25 + vector + graph (top-K เท่านั้น) |
| Token cost | 22K+ ที่ 240 observation | ~1,900 token (ลดลง 92%) |
| Cross-agent | ไฟล์แยกตาม agent | MCP + REST (agent ใดก็ได้) |
@@ -1009,13 +948,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-Tier Memory Consolidation
@@ -1033,6 +972,8 @@ SessionStart hook fires
### What Gets Captured
+ตารางนี้อธิบาย hook ของ Claude Code การเชื่อมต่ออื่นบันทึกเหตุการณ์ที่ host รองรับ การแทรกบริบทอัตโนมัติผ่าน hook ร่วมต้องเปิดด้วย `AGENTMEMORY_INJECT_CONTEXT=true`
+
| Hook | Captures |
|------|----------|
| `SessionStart` | Project path, session ID |
@@ -1049,7 +990,7 @@ SessionStart hook fires
| Capability | Description |
|---|---|
-| **Automatic capture** | ทุก tool use ถูกบันทึกผ่าน hook โดยไม่ต้องทำเอง |
+| **Automatic capture** | การเชื่อมต่อ native บันทึกเหตุการณ์เซสชันและเครื่องมือที่รองรับ |
| **Semantic search** | BM25 + vector + knowledge graph พร้อม RRF fusion |
| **Memory evolution** | Versioning, supersession, relationship graph |
| **Recall hygiene** | memory version ที่ถูกแทนที่แล้วจะหลุดออกจาก search index; version chain ใน KV เก็บ history แบบเต็มไว้ |
@@ -1267,187 +1208,6 @@ viewer server จะ bind กับ `127.0.0.1` โดย default และแ
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-viewer ที่ `:3113` แสดงสิ่งที่ agent ของคุณ **จำได้** [iii console](https://iii.dev/docs/console) แสดงสิ่งที่ agent ของคุณ **ทำ**: memory op ทุกตัวเป็น OpenTelemetry trace, KV entry ทุกตัวแก้ไขได้, function ทุกตัวเรียกใช้ได้, stream ทุกตัว tap ดูได้ สองหน้าต่างของหน่วยความจำเดียวกัน: หนึ่งในรูปแบบของ product หนึ่งในรูปแบบของ engine
-
-ดู `memory_smart_search` ยิงออกไปและดู BM25 scan → embedding lookup → RRF fusion → reranker เป็น waterfall แก้ไข consolidation timer ที่ค้างอยู่ใน KV browser Replay hook `PostToolUse` พร้อม payload ที่ปรับแล้ว Pin WebSocket stream และดู observation เข้ามาแบบสด ๆ
-
-agentmemory มอบสิ่งนี้ให้ฟรี เพราะทุก function call และ trigger ยิงผ่าน iii อยู่แล้ว; ไม่มีอะไรต้องสร้างเอง ไม่มีอะไรต้อง instrument เพิ่ม
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="หน้า Workers ของ iii console: worker ที่เชื่อมต่ออยู่ รวมถึง instance ของ agentmemory พร้อมจำนวน function แบบสดและ runtime metadata" width="720" />
- <br/>
- <em>หน้า Workers: worker ที่เชื่อมต่อทุกตัว รวมถึง agentmemory เอง พร้อม PID, จำนวน function, runtime, และ last-seen</em>
-</p>
-
-**ติดตั้งมาให้แล้ว** console ship มาพร้อม iii engine ที่ pin ไว้ (0.22+); ไม่ต้องติดตั้งอะไรแยก การเปิดครั้งแรกจะดาวน์โหลด console binary ไว้ข้าง ๆ engine
-
-**เปิดใช้งานคู่กับ agentmemory:**
-
-```bash
-agentmemory console
-```
-
-คำสั่งนี้จะรัน `iii console` ของ engine ที่ pin ไว้ โดยชี้ไปยังพอร์ตที่ agentmemory resolve ไว้ (REST, stream, bridge) และ serve มันที่พอร์ตสูงกว่า viewer หนึ่งพอร์ต คือ `http://localhost:3114` โดย default `--console-port N` เลือกพอร์ตอื่นได้ `--port` และ `--instance` เลือก instance ของ agentmemory แบบเดียวกับที่ใช้กับ `stop`; flag อื่น ๆ ที่เหลือจะถูกส่งผ่านไปตรง ๆ เช่น `--enable-flow` สำหรับหน้า architecture-graph แบบทดลอง
-
-วิธีเดียวกันแบบทำมือ มีประโยชน์เมื่อ `agentmemory` ไม่อยู่ใน PATH:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**สิ่งที่คุณทำได้จาก console:**
-
-| Page | Use it to |
-|------|-----------|
-| **Workers** | ดู worker ที่เชื่อมต่ออยู่ทั้งหมดและ metric แบบสดของมัน รวมถึง agentmemory worker เองด้วย |
-| **Functions** | เรียก function ของ agentmemory ตัวใดก็ได้ตรง ๆ ด้วย JSON payload; สะดวกสำหรับทดสอบ `memory.recall`, `memory.consolidate`, `graph.query` โดยไม่ต้องเชื่อมต่อ client |
-| **Triggers** | Replay trigger แบบ HTTP, cron, event, และ state: ยิง consolidation cron ด้วยมือ, retry HTTP route, ส่ง state change |
-| **States** | KV browser ที่ CRUD ได้เต็มรูปแบบบน session, memory slot, lifecycle timer, และ embeddings index; แก้ค่าได้ตรง ๆ |
-| **Streams** | monitor WebSocket แบบสดสำหรับ memory write, hook event, และการอัปเดต observation ขณะไหลผ่าน iii stream |
-| **Queues** | durable queue topic + การจัดการ dead-letter Replay หรือ drop embedding / compression job ที่ล้มเหลว |
-| **Traces** | มุมมอง OpenTelemetry waterfall / flame / service-breakdown filter ด้วย `trace_id` เพื่อดูว่า `memory.search` ครั้งเดียวสร้าง function, DB call, และ embedding request ใดบ้าง |
-| **Logs** | OTEL log แบบ structured ที่ filter และเชื่อมโยงกับ trace/span ID |
-| **Config** | การตั้งค่า runtime: ดูว่า worker, provider, และพอร์ตใดที่ engine ของคุณกำลังรันอยู่ |
-| **Flow** | (Optional, `--enable-flow`) กราฟ architecture แบบโต้ตอบของทุก worker, trigger, และ stream |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="มุมมอง trace waterfall ของ iii console แสดง duration ต่อ span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service breakdown สำหรับทุก memory operation</em>
-</p>
-
-**Trace ถูกเปิดไว้อยู่แล้ว:**
-
-`iii-config.yaml` ship มาพร้อม worker `iii-observability` ที่เปิดใช้งานไว้ (`exporter: memory`, `sampling_ratio: 0.1`, metrics + logs) ไม่ต้องตั้งค่าเพิ่ม ทันทีที่ agentmemory เริ่มทำงาน memory operation ทุกตัวจะปล่อย structured log ที่ console อ่านได้ และหนึ่งในสิบของมัน (`sampling_ratio: 0.1`) จะปล่อย trace span ด้วย
-
-ถ้าต้องการ export ไปยัง Jaeger/Honeycomb/Grafana Tempo แทน ให้เปลี่ยน `exporter: memory` เป็น `exporter: otlp` และตั้งค่า collector endpoint ตามเอกสาร observability ของ iii
-
-> **ข้อควรระวัง:** console เองไม่มีการบังคับใช้ auth เลย ให้ bind มันไว้กับ `127.0.0.1` (ค่า default) และอย่าเปิดให้เข้าถึงจากสาธารณะเด็ดขาด
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="ขับเคลื่อนด้วย iii" height="32" /></picture></h2>
-
-agentmemory คือ **instance ของ [iii](https://iii.dev) ที่กำลังรันอยู่แล้ว** primitive สามตัว (worker, function, trigger) ประกอบกันเป็น runtime; KV state, stream, และ OTEL trace มาจาก worker iii-state, iii-stream, และ iii-observability ที่ ship มากับ iii คุณไม่ได้ติดตั้ง Postgres, Redis, Express, pm2, หรือ Prometheus เลย เพราะ iii มาแทนที่สิ่งเหล่านั้นทั้งหมด
-
-นั่นหมายความว่าแค่อีกคำสั่งเดียวก็ขยาย agentmemory ให้มีความสามารถใหม่ทั้งชุดได้
-
-### Extend agentmemory with more workers
-
-builtin ที่ agentmemory ต้องใช้มีอยู่ใน `iii-config.yaml` แล้วและ boot มาคู่กัน: `iii-state` (KV), `iii-queue` (durable retry สำหรับ event subscriber), `iii-pubsub`, `iii-cron`, `iii-stream`, และ `iii-observability` (OTEL trace, metric และ log บนทุก function) สิ่งอื่น ๆ จาก [iii worker registry](https://workers.iii.dev) เสียบเข้ากับ engine ตัวเดียวกันนี้ได้: copy `iii-config.yaml` ไปที่ `~/.agentmemory/iii-config.yaml` (CLI จะเลือกไฟล์นี้ก่อนไฟล์ที่ bundle มา และยัง render พอร์ตกับ data path ลงไปในไฟล์นี้เหมือนเดิม) เพิ่มรายการเข้าไป ติดตั้ง worker runtime ครั้งเดียวด้วย `~/.agentmemory/bin/iii update worker` แล้ว 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 | สิ่งที่คุณได้เพิ่มจาก agentmemory |
-|---|---|
-| [`database`](https://workers.iii.dev/workers/database) | SQL-backed state adapter เมื่อ KV default ในหน่วยความจำไม่พอแล้ว |
-| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | โค้ดที่มาจาก `memory_recall` รันอยู่ใน VM แบบใช้แล้วทิ้ง ไม่ใช่ shell ของคุณ |
-| [`mcp`](https://workers.iii.dev/workers/mcp) | ตั้ง MCP server เพิ่มเติมข้าง ๆ ของ agentmemory ใช้ engine ตัวเดียวกัน |
-
-บน engine 0.22.x ให้คงชื่อที่มี prefix `iii-` ไว้สำหรับ builtin ด้านบน; รายการ `http`, `state`, `queue`, `pubsub` และ `cron` ที่ไม่มี prefix คือ worker จาก registry แบบ standalone ที่ agentmemory จะย้ายไปใช้ตอน migrate เป็น 0.23
-
-Registry แบบเต็ม: [workers.iii.dev](https://workers.iii.dev) worker ทุกตัวที่นั่นประกอบขึ้นผ่าน primitive ตัวเดียวกับที่ agentmemory ใช้ และ agentmemory ที่คุณมีอยู่แล้วก็เป็นหนึ่งในนั้นเอง
-
-### Engine config and bind address
-
-`agentmemory start` จะอ่าน engine config จากไฟล์แรกที่มีอยู่: `AGENTMEMORY_III_CONFIG`, `./iii-config.yaml` ใน directory ปัจจุบัน, `~/.agentmemory/iii-config.yaml`, จากนั้นจึงเป็น `iii-config.yaml` ที่ bundle มา ทุกครั้งที่เริ่มทำงาน มันจะ render ไฟล์นั้น (data path, พอร์ต, state backend) ลงไปที่ `~/.agentmemory/data/iii-config.runtime.yaml` และเริ่ม engine ด้วยไฟล์ที่ render แล้ว ดังนั้นให้แก้ไฟล์ source ไม่ใช่ไฟล์ที่ render ออกมา ค่า `host:` ของไฟล์ source จะถูกเก็บไว้ตามที่เขียนไว้
-
-`iii-config.yaml` ที่ bundle มาตั้งใจ bind `127.0.0.1` และค่า default นั้นก็ใช้กับภายใน container ด้วย CLI ที่เริ่มในคอนเทนเนอร์จะ listen บน loopback ของคอนเทนเนอร์ ดังนั้นพอร์ตที่ publish ออกมาจะเข้าไม่ถึงอะไรเลย หากต้องการ serve CLI ที่อยู่ใน container ผ่านพอร์ตที่ publish ไว้ ให้ตั้งค่า `AGENTMEMORY_III_CONFIG` ไปที่ config ที่ bind `0.0.0.0` `iii-config.docker.yaml` ที่แพ็กเกจมาให้คือหนึ่งในนั้น: มัน bind `iii-http`, `iii-stream` และพอร์ตของ engine ไว้ที่ `0.0.0.0` และเก็บ state ไว้ใต้ `/data` ดังนั้นให้ mount volume ที่เขียนได้ไว้ที่นั่น ตั้งค่า `AGENTMEMORY_SECRET` ไว้เสมอ และ publish แค่พอร์ตที่คุณต้องการ บน `127.0.0.1` หรืออยู่หลัง proxy ที่คุณเชื่อถือได้
-
-`docker-compose.yml` ของ repo นี้ไม่ผ่าน config lookup ของ CLI: มัน mount `iii-config.docker.yaml` ไว้ที่ `/app/config.yaml` และ container `iii-engine` เริ่มด้วย `--config /app/config.yaml` เทมเพลต [deploy](../deploy/) แบบ one-click เขียน config `0.0.0.0` ของตัวเองไว้ใน entrypoint
-
-### Storage backend: file (default) vs redis
-
-`iii-state` และ `iii-stream` ใช้ KV store แบบไฟล์ของ iii-engine เป็น default: หนึ่งไฟล์ JSON ต่อ scope เก็บไว้ในหน่วยความจำของ engine process และเขียนลงดิสก์ตาม timer นั่นคือค่า default ที่เหมาะกับการติดตั้งแบบ single-user ในเครื่อง ส่วน daemon ที่ใช้ร่วมกันโดยมีผู้เขียนหลายคนพร้อมกันจะได้การเขียนต่อ key จริง ๆ จาก Redis แทน โดยแลกมาด้วย network round trip ต่อ operation (ทุก `state::*` call ก็ยัง serialize บน Redis connection เดียวอยู่ดี ดังนั้นนี่คือการแลก lock ของ file store กับ socket ไม่ใช่การแลกเพื่อ parallelism)
-
-ตั้งค่า `AGENTMEMORY_STATE_BACKEND=redis` (พร้อม `AGENTMEMORY_REDIS_URL`) เพื่อสลับทั้งสอง worker ไปใช้ adapter `redis` ในตัวของ iii-engine ซึ่งเก็บแต่ละ key เป็น Redis hash field (`HSET`) แทนการเขียนทั้ง scope ใหม่ทุกครั้งที่เขียน:
-
-```env
-# ~/.agentmemory/.env
-AGENTMEMORY_STATE_BACKEND=redis
-AGENTMEMORY_REDIS_URL=redis://localhost:6379
-```
-
-`AGENTMEMORY_STATE_BACKEND` ค่า default คือ `file`; ถ้าไม่ตั้งค่าไว้ พฤติกรรมปัจจุบันจะไม่เปลี่ยนแปลง และค่าที่ไม่รู้จัก (อะไรก็ตามที่ไม่ใช่ `file` หรือ `redis`) จะเป็น startup error ไม่ใช่การ fallback แบบเงียบ ๆ `/agentmemory/status` และหน้า Health ของ viewer (แถว State store) จะรายงานว่า backend ตัวใด active อยู่ และตอบสนองหรือไม่ แต่ไม่รายงาน URL
-
-**รองรับแค่ `redis://` ธรรมดาเท่านั้น** engine ที่ pin ไว้ (0.22.1) build Redis client ของมันมาโดยไม่รองรับ TLS ดังนั้น URL แบบ `rediss://` (Redis ที่ managed ส่วนใหญ่ เช่น Upstash, Redis Cloud, และ ElastiCache ที่เข้ารหัสระหว่างส่ง มักจะ default เป็น TLS-only) จะเชื่อมต่อไม่ได้ การเชื่อมต่อนี้ไม่เข้ารหัส ดังนั้น password ของ Redis และ memory ที่เก็บไว้ทุกตัวจะวิ่งผ่านสายแบบ clear text: ให้ชี้ไปที่ Redis ในเครื่องหรือ Redis บน private network ที่คุณเชื่อถือได้ สำหรับ Redis อื่น ๆ ให้รัน encrypted tunnel (stunnel, SSH, หรือ VPN) บน host ของ agentmemory เพื่อให้ hop แบบ `redis://` ธรรมดาอยู่บน host นั้นเอง และ upstream connection ของ tunnel ถูกเข้ารหัสและยืนยันตัวตนแล้ว ถ้า password ของ Redis มี single quote ให้ percent-encode มัน (`%27`); engine จะขยาย URL เข้าไปใน YAML config ของมันก่อน parse
-
-**Redis server หนึ่งตัวต่อหนึ่ง `--instance`** prefix ของ Redis key ของ engine (`state:<scope>`, `stream:<name>:<group>`) ถูกตรึงไว้ ดังนั้น agentmemory สอง instance (`--instance 1`, `--instance 2`, ...) ที่ชี้ไปยัง database เดียวกันจะเขียนทับข้อมูลกันเอง database index ที่แยกกัน (`redis://localhost:6379/1`) จะแยกข้อมูลที่เก็บไว้ แต่ engine จะส่ง live viewer event ผ่าน Redis pub/sub channel เดียว (`stream::events`) และ Redis pub/sub จะไม่สนใจ database index ดังนั้น viewer ของแต่ละ instance จะยังเห็น live event ของอีก instance อยู่ดี ให้แต่ละ instance มี Redis server (หรือพอร์ต) ของตัวเองเมื่อคุณรันมากกว่าหนึ่งตัว
-
-**สิ่งที่เหมือนเดิม และสิ่งที่ต่างไป** ทุกฟีเจอร์ของ agentmemory ทำงานได้บน Redis: session, observation, memory (remember, supersede, evolve, forget), การค้นหาและ index bucket, lesson, graph, audit log และ scope รายเดือนของมัน, export และ import, governance delete, สถานะ consolidation, viewer snapshot กับ live stream ของมัน, และ health monitor engine เก็บแต่ละ scope เป็น Redis hash ตัวเดียว (`HSET`/`HGET`/`HGETALL`) และยิง state trigger ตัวเดียวกับที่ file store ใช้ มีความแตกต่างของ engine 3 อย่างที่ agentmemory จัดการให้ภายใน:
-
-- Redis คืน record ของ scope มาแบบไม่มีลำดับที่แน่นอน agentmemory จะเรียงจากเก่าสุดก่อน (ตามเวลาที่สร้างใน record id แล้วตามด้วย timestamp) เพื่อให้ list, paging และ export chunk กลับมาในลำดับเดียวกับบน file store
-- engine ทำ partial update บน Redis ผ่าน Lua script ที่เปลี่ยน array ว่างเป็น object ว่าง agentmemory จะ apply update เหล่านั้นด้วยตัวเอง (อ่าน, เปลี่ยน, เขียนภายใต้ lock ต่อ key) บน Redis เพื่อให้ field เช่น `tags: []` ยังคงเป็น array
-- การตรวจสอบ audit log แบบเก่าจะอ่าน scope เก่าจาก Redis แทนการมองหาไฟล์ของ file store บนดิสก์
-
-มีความแตกต่างหนึ่งอย่างที่คุณต้องจัดการเอง: **หลัง Redis restart engine จะหยุดส่ง live event** ไปยัง viewer จนกว่า agentmemory จะ restart ข้อมูลยังถูก save และอ่านได้ตามปกติ health monitor จะส่ง test event ผ่าน Redis ทุก 30 วินาที เมื่อมันไม่กลับมา `/agentmemory/status` และหน้า Health ของ viewer จะแสดง "Live updates are not reaching the viewer" พร้อมวิธีแก้: restart agentmemory ถ้า Redis ล้ม status report จะแสดง "The state store is not answering" และวิธีตรวจสอบ (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`) การ list scope ขนาดใหญ่มากจะอ่าน hash ทั้งหมดใน `HGETALL` เดียว ซึ่งมีค่าใช้จ่ายเท่ากับที่ file store เก็บมันไว้ในหน่วยความจำ
-
-**ค่า Redis ที่แนะนำ** นโยบาย snapshot default `save 3600 1 300 100 60 10000` อาจทำให้เสีย write ไปหลายนาทีถ้า crash ซึ่งแย่กว่า window การ flush 5 วินาทีของ file store ตั้งค่า `appendonly yes` สำหรับสิ่งที่คุณไม่อยากเสีย ตั้งค่า `maxmemory-policy noeviction`; `allkeys-lru` หรือคล้ายกันจะลบ memory ทิ้งแบบเงียบ ๆ เมื่อ Redis ถึง memory limit
-
-การเริ่มแบบ native (ไม่ใช่ Docker) และเทมเพลต [deploy](../deploy/) แบบ one-click ทุกตัว (ซึ่งเขียนทับ `iii-config.yaml` ที่ bundle มาและเริ่มแบบ native) จะอ่าน `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` และ render มันลงไปใน `iii-config` ที่เริ่มทำงาน ตัว URL เองไม่ถูกเขียนลงไฟล์ที่ render แล้วเลย มีแต่การอ้างอิง `${AGENTMEMORY_REDIS_URL}` ที่ engine process จะขยายจาก environment ของมันเองตอน boot มีเพียงเส้นทาง Docker Compose ของ repo นี้เอง (`AGENTMEMORY_USE_DOCKER=1` หรือการ resume engine ที่เริ่มด้วยวิธีนั้นไปแล้ว) ที่ mount `iii-config.docker.yaml` แบบ read-only และไม่ render เลย `agentmemory start` จะเตือนเมื่อตรวจพบ combination นั้น สลับไฟล์นั้นด้วยมือ ตามรูปแบบ `name: redis` / `config: redis_url: ...` เดียวกันตามที่แสดงไว้ใน worker doc ของ [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` เข้าไปใน engine container ดังนั้น `redis_url: '${AGENTMEMORY_REDIS_URL}'` ใช้ได้ที่นั่นและเก็บ URL ไว้ไม่ให้อยู่ในไฟล์ที่ mount
-
-config ที่ render แล้วจะเก็บ URL ไม่ให้อยู่ใน `~/.agentmemory/data/iii-config.runtime.yaml` แต่ configuration worker ของ engine เองยังคง persist ค่าที่ *ขยายแล้ว* ไปที่ `~/.agentmemory/config/iii-state.yaml` และ `iii-stream.yaml` ทันทีที่มัน boot (การขยาย `${VAR}` ของ iii-engine เกิดขึ้นก่อนที่ worker นั้นจะเก็บ seed ของมัน และมันเก็บค่าที่ resolve แล้ว ไม่ใช่ตัวอ้างอิง) ให้ปฏิบัติกับ directory นั้นเหมือนมันเก็บ credential ไว้: `chmod 700 ~/.agentmemory` บน shared host ใด ๆ และเลือกใช้ Redis ACL user ที่ scope ไว้เท่าที่ agentmemory ต้องการ มากกว่า admin credential ของ database
-
-**การ migrate ไม่เกิดขึ้นอัตโนมัติ** การสลับ `AGENTMEMORY_STATE_BACKEND` จะเริ่มจาก store ที่ว่างเปล่าทั้งสองฝั่ง ไม่มีอะไร copy ข้อมูลเดิมจาก file ไป Redis หรือกลับกันให้เลย export จาก backend ที่คุณกำลังออกจาก แล้ว import เข้า backend ที่คุณกำลังจะไป ขั้นตอนนี้ทำงานเหมือนกันทั้งบน bash และ zsh (รวมถึง `bash -u`) array แบบ `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=` สำหรับแบ่ง corpus ขนาดใหญ่ออกเป็นหลายคำขอ; `strategy` ตอน import คือ `merge` (ปลอดภัยโดย default), `replace`, หรือ `skip`
-
-### What iii replaces
-
-| Traditional stack | agentmemory ใช้ |
-|---|---|
-| Express.js / Fastify | iii HTTP Triggers |
-| SQLite / Postgres + pgvector | iii KV State + vector index ในหน่วยความจำ |
-| SSE / Socket.io | iii Streams (WebSocket) |
-| pm2 / systemd | iii engine worker supervision |
-| Prometheus / Grafana | iii OTEL + health monitor |
-| Custom plugin systems | `iii worker add <name>` |
-
-**250 source file · ~55,000 LOC · 3,400+ การทดสอบ · 324 function · 67 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="การตั้งค่า" height="32" /></picture></h2>
### LLM Providers
@@ -1514,24 +1274,9 @@ Local embedding ship มาเป็น optional dependency แต่ไม่
### Cost-aware model selection
-เมื่อเปิดการบีบอัดพื้นหลังด้วย LLM ทั้งที่มี provider และ `AGENTMEMORY_AUTO_COMPRESS=true` มันจะรันบนทุก observation ดังนั้นการเลือกโมเดลมีผลต่อค่าใช้จ่ายรายเดือนอย่างมีนัยสำคัญ ข้อมูล workload ที่จับได้จริง: 635 คำขอ / 888K token / 35 ชั่วโมงของการใช้งานจริง รันเทียบกับโมเดล OpenRouter สามตัวตามราคา ณ วันที่ 2026-05-23
-
-| Tier | Model | Input / 1M | Output / 1M | ค่าใช้จ่ายสำหรับ 35 ชม.ที่จับได้ | Notes |
-|------|-------|------------|-------------|---------------------------|-------|
-| แนะนำ | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (ประมาณ) | DeepSeek เวอร์ชันล่าสุด; ตัวเลือกที่ถูกที่สุดที่แนะนำสำหรับงาน compression |
-| แนะนำ | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | คุณภาพ compression + summarization ที่ดี ในราคาต่ำกว่า Sonnet ประมาณ 10 เท่า |
-| แนะนำ | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | reasoning เรื่องโค้ดที่แข็งแรงถ้าเซสชันของคุณเน้นโค้ดเป็นหลัก |
-| Premium | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (ประมาณ) | ราคาหน้า list เดียวกับการรัน Sonnet 4.6 ที่วัดไว้; ราคาเปิดตัว $2/$10 จนถึง 2026-08-31 |
-| Premium | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (ประมาณ) | ระดับ flagship; แพงเกินไปสำหรับงานพื้นหลังแบบ always-on |
-| ควรเลี่ยง | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (ประมาณ) | โมเดลระดับ flagship; overspend สำหรับงาน compression |
-
-แถวที่วัดจริงมาจากการรันที่จับไว้; แถว (ประมาณ) scale ตาม token mix เดียวกันด้วยราคา list ของแต่ละโมเดล
-
-agentmemory จะพิมพ์คำเตือน runtime เมื่อ `OPENROUTER_MODEL` ตรงกับ pattern ของ tier premium ตั้งค่า `AGENTMEMORY_SUPPRESS_COST_WARNING=1` เพื่อปิดเสียงเตือนเมื่อคุณตัดสินใจเลือกแล้วอย่างมีข้อมูล
-
-การแลกระหว่างคุณภาพกับต้นทุนสำหรับงาน memory: compression เป็นงาน summarization ที่มีเกณฑ์คุณภาพค่อนข้างหลวม (agent อ่าน summary กลับ ไม่ใช่ user) DeepSeek V4 Flash / V4 Pro / Qwen3-Coder อยู่ในระดับใกล้เคียง Sonnet มากสำหรับงานนี้ ในขณะที่ค่าใช้จ่ายถูกกว่า 10-70 เท่า เก็บโมเดลระดับ premium ไว้สำหรับคำค้นที่คุณอ่านเองตรง ๆ
+เริ่มบันทึกและค้นหาคำสำคัญได้โดยไม่ต้องมีคีย์ `EMBEDDING_PROVIDER=local` เพิ่มการค้นหาเชิงความหมายบนเครื่องหลังดาวน์โหลดโมเดลครั้งแรก การบีบอัดด้วย LLM ต้องมีผู้ให้บริการและ `AGENTMEMORY_AUTO_COMPRESS=true` และอาจส่งคำขอทุก observation จึงควรตรวจสอบราคาปัจจุบัน
-ที่มา: [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/)
+`agentmemory status` / http://localhost:3113
### Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1561,41 +1306,22 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### Ports
-agentmemory + iii-engine bind พอร์ต 4 ตัวโดย default ถ้า restart ล้มเหลวด้วย `port in use` ตารางนี้จะบอกว่าต้องหา process ตัวไหน
+API และตัวดูข้อมูลใช้ loopback ตามค่าเริ่มต้น
-| 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_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 <N>` จะเปลี่ยน anchor ของ REST และ derive stream เป็น `N+1`, viewer เป็น `N+2`, และ engine WebSocket เป็น `N+46023` เฉพาะตอนที่พอร์ตหรือ URL แบบ explicit ที่ตรงกันด้านบนยังไม่ได้ตั้งค่าไว้ มันไม่ได้สร้าง lifecycle namespace ที่แยกต่างหาก ใช้ `--instance 1` สำหรับ daemon ตัวที่สอง มัน anchor ที่ 3211 ค่า default คือ `3211/3212/3213/49234` และได้ data และ lifecycle directory ชื่อ `instance-1` แยกต่างหาก instance 1 ถึง 50 เป็นไปตาม pattern เดียวกัน
-
-engine ที่ pin ไว้เริ่มด้วย `--no-update-check` (ไม่ lookup update หรือ security-advisory กับ GitHub ตอน boot) และปิด anonymous usage telemetry ของ iii: agentmemory ตั้งค่า `III_TELEMETRY_ENABLED=false` ให้ engine ที่มันสั่งเริ่ม เว้นแต่คุณจะ export ตัวแปรนี้เอง และ compose file ที่ bundle มาก็ทำแบบเดียวกัน
+| Port | API / ตัวดูข้อมูล | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | ตัวดูข้อมูล | `III_VIEWER_PORT` |
-การล้าง stale process เมื่อพอร์ตยัง bind อยู่หลังการรันที่ crash:
+`--port <N>` กำหนดพอร์ต API และตัวดูข้อมูลใช้ `N+2` โดยปริยาย ใช้ `--instance N` สำหรับ instance แยก เก็บ listener ภายในให้เป็นส่วนตัว ดูการเข้าถึงระยะไกลและ[การย้าย Docker รุ่นเก่า](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)ในคู่มือ deploy
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage backend: file (default) vs Redis
-`agentmemory stop` จะเก็บ worker และ engine pidfile ให้สะอาดตอน shutdown แบบ native graceful ในโหมด Docker มันจะ flush native worker, หยุด engine container ที่ validate แล้วตัวที่ถูก และรักษาทั้ง container กับ mount `/data` ไว้สำหรับการ restart แบบไม่เสียข้อมูล การเริ่มครั้งถัดไปจะ validate และ resume container ตัวเดียวกันนั้น การ uninstall ที่รองรับ Docker ต้องใช้ `agentmemory remove --keep-data`: มันลบไฟล์ที่ agentmemory จัดการอยู่ร่วมกัน ขณะรักษา container ที่ validate แล้ว, mount ข้อมูลของมัน, และ lifecycle record ที่จำเป็นสำหรับการกู้คืน การลบข้อมูล Docker แบบทำลายล้างตั้งใจปล่อยให้ operator ทำเองหลัง backup CLI ยังปฏิเสธที่จะ adopt หรือส่ง signal ไปยัง Docker หรือ VM port holder (Docker backend, vpnkit, colima) ให้เป็น native engine เว้นแต่จะส่ง `--force` การล้างด้วยมือข้างบนมีไว้สำหรับกรณี post-crash ที่ไม่มี pidfile เหลืออยู่เลยเท่านั้น
+ไม่ต้องมีบริการฐานข้อมูลแยก. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. การเปลี่ยน backend ไม่คัดลอกความจำเดิมให้อัตโนมัติ [การจัดเก็บข้อมูล](../docs/reliability/state-storage.md).
### Config File
-วางการตั้งค่า runtime ของ agentmemory ไว้ใน `~/.agentmemory/.env` แทนการ export ตัวแปรในทุก shell ถ้า viewer แสดง setup hint เช่น `export ANTHROPIC_API_KEY=...` ให้ copy มันลงในไฟล์นี้เป็น `ANTHROPIC_API_KEY=...` โดยไม่มี prefix `export` แล้ว restart agentmemory
-
-Process environment variable ยังทำงานได้เหมือนเดิมและมีสิทธิ์เหนือค่าในไฟล์
-
-บน Windows ไฟล์เดียวกันอยู่ที่ `%USERPROFILE%\.agentmemory\.env`:
+เก็บ runtime config ใน `~/.agentmemory/.env` แทนการ export ตัวแปรในทุก shell ตั้ง `AGENTMEMORY_ENV_FILE` เพื่อเลือกไฟล์ env อื่น ตัวแปร environment ของ process มีลำดับเหนือค่าจากไฟล์ Worker Compose ที่ CLI สร้างจะส่ง Redis settings ไปยัง worker `state`
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1620,179 +1346,34 @@ GRAPH_EXTRACTION_ENABLED=true
### Environment Variables
-สร้าง `~/.agentmemory/.env`:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+ข้อมูลครบถ้วนอยู่ใน [`.env.example`](../.env.example) รวมผู้ให้บริการ ตัวกรอง capture การเก็บรักษา storage และขอบเขตทีม `AGENTMEMORY_ENV_FILE` เลือกไฟล์อื่นได้ เริ่มใหม่หลังเปลี่ยนคอนฟิก อย่า commit `.env` ที่มีค่าจริงหรือรหัสลับ Bearer
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 endpoint บนพอร์ต `3111` REST API จะ bind กับ `127.0.0.1` โดย default endpoint ที่ป้องกันไว้ต้องมี `Authorization: Bearer <secret>` และ endpoint ของ mesh sync ต้องตั้งค่า `AGENTMEMORY_SECRET` ไว้อย่างชัดเจนทั้งสองฝั่ง
+146 endpoint บนพอร์ต `3111` REST API จะ bind กับ `127.0.0.1` โดย default endpoint ที่ป้องกันไว้ต้องมี `Authorization: Bearer <secret>` และ endpoint ของ mesh sync ต้องตั้งค่า `AGENTMEMORY_SECRET` ไว้อย่างชัดเจนทั้งสองฝั่ง
-**Authentication เปิดอยู่โดย default** เมื่อไม่ได้ตั้งค่า `AGENTMEMORY_SECRET` (ทั้งใน shell หรือใน `~/.agentmemory/.env`) server จะสร้าง secret แบบสุ่มตอนเริ่มครั้งแรก และเก็บไว้ที่ `~/.agentmemory/secret` ด้วย mode `0600` client ที่ bundle มาทุกตัวจะอ่านมันจากที่นั่นเมื่อคุยกับ server ในเครื่อง: CLI, viewer, hook ใต้ `plugin/scripts`, MCP server และ shim `@agentmemory/mcp`, config ที่เขียนโดย `agentmemory connect`, และ integration ของ OpenCode, Pi, OpenClaw, Hermes และ filesystem-watcher ที่ bundle มา secret ที่เก็บไว้จะถูกส่งไปที่ loopback URL เท่านั้น (`localhost`, `127.0.0.0/8`, `::1`) `AGENTMEMORY_SECRET` แบบ explicit จะมีสิทธิ์เหนือเสมอ และ client แบบ remote ยังต้องตั้งค่ามันไว้ Docker และ entrypoint ของ [deploy](../deploy/) สร้างและ export secret ของตัวเองไว้แล้ว เรียก API ด้วยมือ:
+เปิดการยืนยันตัวตนตามค่าเริ่มต้น หากไม่ตั้ง `AGENTMEMORY_SECRET` CLI จะสร้างรหัสลับสุ่มครั้งแรกที่ `~/.agentmemory/secret` และคัดลอกไปยัง `secret` ในไดเรกทอรีข้อมูลที่เลือก โดยใช้สิทธิ์ `0600` ไคลเอนต์ที่รวมมาจะอ่านไฟล์หลักนี้ก่อนเมื่อเชื่อมต่อในเครื่อง และส่งรหัสลับที่บันทึกไว้เฉพาะ URL แบบ loopback ค่า `AGENTMEMORY_SECRET` ที่ระบุเองมีลำดับความสำคัญสูงกว่า ไคลเอนต์ระยะไกลต้องตั้งผ่าน environment ส่วน Docker สร้างรหัสลับของตนเอง
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" http://localhost:3111/agentmemory/health
```
**กฎของคำขอสำหรับการเขียน** คำขอ `POST`, `PUT`, `PATCH` และ `DELETE` ไปยัง REST API และ viewer ต้องส่ง `Content-Type: application/json` (พารามิเตอร์ `charset` ใส่ได้) เมื่อมี body และ header `Origin` เมื่อมีอยู่ ต้องเป็น loopback origin ของพอร์ต REST หรือ viewer ที่ตั้งค่าไว้ หรืออยู่ใน `VIEWER_ALLOWED_ORIGINS` (คั่นด้วย comma เช่น `https://memory.example.com`) client ที่ไม่ส่ง header `Origin` เลย (CLI, hook, MCP, curl, server-to-server) ไม่ได้รับผลกระทบ viewer เองก็ยอมรับ origin ของตัวเองด้วย
@@ -1828,7 +1409,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | แชร์กับทีม |
| `GET` | `/agentmemory/audit` | Audit trail |
-รายการ endpoint แบบเต็ม: [`src/triggers/api.ts`](../src/triggers/api.ts)
+รายการ endpoint แบบเต็ม: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1846,19 +1427,19 @@ Event ที่ล้มเหลวจะถูก retry ทุก `AGENTMEMORY
เมื่อ server ล้ม ไม่ตอบทันเวลา หรือคืน 5xx hook จะต่อ observation เข้าไปที่ spool file ในเครื่อง `<data dir>/capture-spool/<host>-<port>.jsonl` (override folder ด้วย `AGENTMEMORY_CAPTURE_SPOOL_DIR`) ไฟล์นี้เป็นของ user คุณเท่านั้น (mode 600) secret ถูก redact แบบเดียวกับที่ server redact มัน มันเก็บได้สูงสุด `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) และ drop รายการที่เก่ากว่า `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168 ชั่วโมง) เมื่อเต็ม รายการใหม่จะถูก drop และนับไว้ และ `/agentmemory/status` จะรายงานมัน hook ยัง exit 0 ภายใน time limit ของมันเสมอ และไม่เพิ่มคำขอใด ๆ เมื่อ server ปกติดี spool จะถูกส่งตอนเริ่มครั้งถัดไป และโดย hook ตัวแรกที่เชื่อมต่อกับ server ได้อีกครั้ง ใน background process เพื่อไม่ให้ agent ต้องรอ event id ทำให้สิ่งนี้ปลอดภัย: observation ที่ถึงแล้วก่อน timeout จะไม่ถูกบันทึกซ้ำสองครั้ง `npx @agentmemory/agentmemory capture` จะแสดง spool และ server inbox, `--drain` จะส่ง spool ทันที, และ `GET /agentmemory/capture` คืนค่าแบบเดียวกันเป็น JSON ตั้งค่า `AGENTMEMORY_CAPTURE_SPOOL=false` เพื่อปิด spool
-**การ compact graph provenance** node และ edge ของ knowledge graph แต่ละตัวเก็บ id ของ observation ล่าสุด 32 ตัวที่มันมาจาก store ที่เขียนไว้ก่อนมี cap นี้อาจมี id นับพันต่อ hot node หนึ่งตัว ซึ่งทำให้ graph search และ viewer ช้าลงหรือทำให้ worker ล้ม agentmemory แก้ปัญหานี้ให้เอง: ในการเริ่มครั้งแรกหลัง upgrade มันจะตัด node, edge, superseded edge (temporal graph history) และ cached snapshot ทุกตัวให้เหลือตาม cap ในพื้นหลัง เป็น slice เล็ก ๆ พร้อมหยุดพักระหว่างกัน เพื่อให้ search, capture, และ viewer ทำงานต่อไปได้ มันจะบันทึกความคืบหน้า resume ได้หลัง restart และไม่รันอีกเมื่อเสร็จแล้ว `/agentmemory/status` และหน้า Health ของ viewer จะแสดงมันเป็น pending, running (พร้อม scope และตำแหน่งปัจจุบัน), done หรือ failed ตั้งค่า `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` เพื่อปิดมัน
+**การ compact graph provenance** การ compact provenance เก่าจะถูกเลื่อนเมื่อเริ่มระบบ เพราะต้องอ่าน scope เก่าทั้งหมด `/agentmemory/status` จะแสดง `deferred` หรือ `off` เมื่อตั้ง `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` ให้รันการ compact แบบแมนนวลด้านล่างระหว่างการบำรุงรักษา การย้ายดัชนีค้นหาเป็นงานแยกต่างหาก: ใช้ `agentmemory graph-index migrate --allow-legacy-scan` ตาม[คู่มือการบำรุงรักษา](../docs/reliability/graph-index-migration.md)
หากต้องการรันด้วยมือ เรียก `POST /agentmemory/graph/compact` มันจะไล่ตาม name และ edge-key index แทนการ list node และ edge ทุกตัว และปลอดภัยที่จะรันซ้ำ เมื่อมันตัด id ออก มันจะเขียน audit entry แบบ `graph_compact`
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{}'
```
บน store ขนาดใหญ่ หรือเมื่อคำขอคืน 504 ให้รันเป็น slice ส่ง `scope` (`nodes`, `edges` หรือ `history`), `offset` และ `limit` แล้วเรียกซ้ำด้วย `nextOffset` ที่คืนมาจนกว่าจะเป็น `null` ทำแบบนี้สำหรับ `nodes`, `edges` และ `history` แล้วปิดท้ายด้วยการเรียก `{"scope":"snapshot"}` หนึ่งครั้ง เพราะการรันแบบ slice จะไม่แตะ 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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1872,7 +1453,7 @@ npm test # 4,000+ 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` ที่ pin ไว้แบบ manual, WSL2, หรือ Docker Desktop
+ดูข้อกำหนดใน[การติดตั้ง](#install) และกติกาการพัฒนากับการตรวจรีลีสใน [CONTRIBUTING.md](../CONTRIBUTING.md)
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.tl-PH.md b/READMEs/README.tl-PH.md
index 11d569cc..996fb5de 100644
--- a/READMEs/README.tl-PH.md
+++ b/READMEs/README.tl-PH.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Naaalala ng iyong coding agent ang lahat. Wala nang paulit-ulit na pagpapaliwanag.
- Nakabatay sa <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Persistent na memory sa iba't ibang coding session at agent.
</strong><br/>
- Permanenteng memory para sa Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, at anumang MCP client.
+ Permanenteng memory para sa Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode, at anumang MCP client.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Paano Gumagana</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Pinapagana ng iii</a> &bull;
<a href="#configuration">Config</a> &bull;
<a href="#api">API</a>
</p>
---
+Nirerekord ng AgentMemory ang coding session para mahanap muli ang mga desisyon at pag-aayos. Gumamit ng iisang memory store sa iba't ibang tool, suriin ang naka-save, at piliin kung gaano karaming context ang matatanggap ng model.
+
+<a id="install"></a>
+
## 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.
+- Kailangan ng `curl`, POSIX `sh`, at `tar` para sa awtomatikong setup sa macOS/Linux.
+- Windows / WSL2: [Windows](#windows).
Standard na command para sa sariwang pag-install:
@@ -108,11 +111,11 @@ Standard na command para sa sariwang pag-install:
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`.
+Piliin ang mga agent at provider o keyless mode. Sine-save ng setup ang configuration, pinapatakbo ang memory server, at nag-aalok ng global install. Tinatanggap ng `-y` ang npm prompt; pinipili ng `@latest` ang pinakabagong release. Kailangan ng provider at `AGENTMEMORY_AUTO_COMPRESS=true` para sa LLM compression.
Pinapatay ng keyless mode ang vector embeddings. Ginagamit ng `memory_recall` (ang `mem::search` path) ang BM25, habang ang `memory_smart_search` ay maaari ring pagsamahin ang structural graph matches kapag umiiral na ang graph data. Para sa libreng on-device semantic recall, i-set ang `EMBEDDING_PROVIDER=local` sa `~/.agentmemory/.env` at i-restart. Ang unang embedding request ay nag-download ng `Xenova/all-MiniLM-L6-v2`; tumatakbo na lokal ang inference pagkatapos ng unang pag-download na ito ng model.
-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 <path>` 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.
+Nasa `http://localhost:3111` ang API at `http://localhost:3113` ang live viewer. Pareho silang naka-bind sa loopback bilang default. Nasa `~/.agentmemory/.env` ang configuration. [Pag-iimbak ng data](#data-storage).
Pagkatapos, patunayan na gumagana ang recall at bigyan ang iyong agent ng mga skill nito:
@@ -127,14 +130,7 @@ Mas gusto mo bang ipagawa lahat sa isang coding agent? Bigyan ito ng isang instr
> 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 <agent>` — 20 adapter na nakalista sa [Gumagana sa Bawat Agent](#works-with-every-agent). Kumpletong command reference sa [Mabilisang Simula](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Magdagdag ng agent gamit ang `agentmemory connect <agent>`. Tingnan ang [mga integration](#works-with-every-agent) at [pang-araw-araw na command](#everyday-commands).
<details>
<summary><strong>Global na Pag-install / EACCES</strong></summary>
@@ -154,13 +150,6 @@ Nag-cache ang npx ayon sa bersyon. Pilitin ang paggamit ng pinakabago gamit ang
</details>
-<details>
-<summary><strong>May sariling iii engine ka nang tumatakbo</strong></summary>
-
-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`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Gumagana sa Bawat Agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST A
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hook + MCP</sub>
+<sub>native plugin + lifecycle hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST A
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>native recall + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST A
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>native capture + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST A
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>native recall + capture + skills + Opsyonal na MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ Gumagana ang agentmemory sa anumang agent na sumusuporta sa hooks, MCP, o REST A
---
-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.
+<a id="data-storage"></a>
-**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.
+### Pag-iimbak ng data
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Nasa labas ng repository ang memory bilang default. Ginagamit muli ng instance 0 ang kasalukuyang `./data/state_store.db`. Pumili ng lokasyon gamit ang `--data-dir <path>` o `AGENTMEMORY_DATA_DIR` at panatilihin ang parehong directory sa restart at upgrade.
-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 <path>` o i-set ang `AGENTMEMORY_DATA_DIR`; mananaig ang alinmang explicit setting kaysa sa legacy discovery:
+| Platform | Directory ng data |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+Gumagamit ang `--instance 1` ng `instance-1` subdirectory, API port `3211`, at viewer port `3213`. Tingnan ang [storage at backup](../docs/reliability/state-storage.md) para sa Redis at paglipat ng backend.
Pinakabagong release notes: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +473,7 @@ Pinakabagong release notes: [CHANGELOG.md](../CHANGELOG.md).
</tr>
<tr>
<td><strong>Panlabas na deps</strong></td>
-<td>Wala (SQLite + iii-engine)</td>
+<td>Hindi kailangan ng hiwalay na database service</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>Marami</td>
@@ -550,14 +547,12 @@ Pinakabagong release notes: [CHANGELOG.md](../CHANGELOG.md).
| 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.
+Pinagsasama ng AgentMemory ang session capture, searchable na project history, at local viewer, na magagamit nang walang key mula sa unang pagpapatakbo.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Mabilisang Simula" height="32" /></picture></h2>
-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
@@ -572,9 +567,11 @@ Nag-seed ang `demo` ng 3 makatotohanang session (JWT auth, N+1 query fix, rate l
Buksan ang `http://localhost:3113` para panoorin ang live na pagbuo ng memory.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Habang tumatakbo ang server, suriin ang health, viewer, at status.
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+Ipinapakita ng `status` ang server health, provider, embedding mode, capture delivery, at recovery. Kailangan ng server secret ang protected REST requests. Gamitin ang naka-configure na `AGENTMEMORY_SECRET` o basahin ang generated local secret kung wala nito.
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Pagkatapos, patakbuhin ang `npx -y @agentmemory/agentmemory@latest stop`, simulan ulit ang standard na command sa Terminal 1, hintayin ang `/agentmemory/livez`, at ulitin ang search. Dapat pa ring ibalik ang probe. Kung pumili ka ng custom na `--data-dir`, ipasa ang parehong directory sa restart.
+<a id="everyday-commands"></a>
+
### 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:
@@ -604,7 +608,10 @@ Ang install at setup ay nasa [I-install](#install) sa itaas (gagabayan ka ng una
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Lumalabas ang imported sessions kasama ng native sessions sa Replay, naka-index para sa search, at may origin channel na `import`. Maaari ring gumawa ng crystals at lessons ang session processing.
> **Paalala kung aasa ka sa `import-jsonl` bilang pangunahing capture path:** Awtomatikong binubura ng `cleanupPeriodDays` ng Claude Code (sa `~/.claude/settings.json`, default na **30**) ang mga JSONL transcript na mas matanda sa window na iyon mula sa `~/.claude/projects/`. Kung mag-install ka ng bagong agentmemory sa isang Claude Code history na may edad na ilang buwan, wala na ang anumang mas matanda sa 30 araw bago pa man ang unang import. Patakbuhin ang `import-jsonl` sa isang cron, itaas ang `cleanupPeriodDays` sa mas mataas, o i-wire ang auto-capture hooks (ang default na plugin install path) para makarating sa agentmemory ang bawat turn habang live ang session at hindi na mahalaga ang JSONL cleanup.
@@ -635,14 +642,12 @@ Gamitin ang maintenance command kapag sinasadya mong i-update ang iyong local ru
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).
+Ina-update nito ang local runtime at maaaring baguhin ang JavaScript dependencies sa kasalukuyang working directory. I-backup ang data at basahin ang [upgrade guide](../docs/upgrades/iii-0.25.md) bago mag-update ng umiiral na installation.
### Claude Code (isang block, i-paste ito)
```text
-Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code nang walang plugin install (MCP-standalone path)
@@ -703,6 +708,26 @@ copilot plugin install rohitg00/agentmemory:plugin
Pinagsasama ng `agentmemory connect copilot-cli` ang `mcpServers.agentmemory` sa `~/.copilot/mcp-config.json` (o `$COPILOT_HOME/mcp-config.json` kapag naka-set ang `COPILOT_HOME`) at pinapanatili ang mga umiiral na server. Sa native Windows, ito lamang ang awtomatikong `connect` adapter; i-configure nang manu-mano ang lahat ng iba pang native Windows agent. Suportado lamang ang WSL `connect` kapag naka-install din ang target agent sa parehong WSL environment. Kukunin ng Copilot ang MCP server sa susunod na launch o pagkatapos ng `/mcp`. I-install din ang plugin kapag gusto mo ang buong hook/skill na karanasan.
+### Cursor
+
+I-configure ang MCP gamit ang `agentmemory connect cursor`. Sa **Settings → Plugins → Add marketplace**, piliin ang checkout na may `.cursor-plugin/plugin.json`, paganahin ang agentmemory, at i-reload. May lifecycle capture, workspace attribution, skills, at MCP ang plugin. Paganahin lang ang plugin hooks o manual hooks sa `~/.cursor/hooks.json` para maiwasan ang dobleng capture.
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Piliin ang command para sa host mo. Nag-i-install ang Pi at OMP ng native recall/capture, offline replay, at 17 skills; idinadagdag ng `--with-mcp` ang buong toolset. Patakbuhin ang `/reload` sa Pi o i-restart ang OMP, saka tingnan ang `/agentmemory-status`. Ini-install ng DSH ang MCP at bundled capture plugin; i-restart pagkatapos kumonekta.
+
+May installable na `@agentmemory/pi` package din ang Pi. Tingnan ang [Pi guide](../integrations/pi/) para sa local install at availability sa npm. Gumamit ng isang paraan ng install sa bawat host.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (i-paste ang prompt na ito)</b></summary>
@@ -749,6 +774,8 @@ Kumpletong gabay: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Iba Pang Agent
Simulan ang memory server: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Ito ay **komplementaryo** sa `agentmemory connect <agent>`:
-- Isusulat ng `agentmemory connect <agent>` 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.
+Ini-install ng Hermes, OpenClaw, Pi, at Oh My Pi connectors ang native integration at skills bilang default; idagdag ang MCP gamit ang `--with-mcp`. Sa ibang host, mag-install ng skills gamit ang `npx skills add rohitg00/agentmemory`.
Para sa ilang agent na hindi pa saklaw ng skills CLI (Zed v1.3.x pababa), ilagay mo mismo ang 17 SKILL.md file sa ilalim ng native skill directory ng agent; gumagana ang parehong format kahit saan.
@@ -790,12 +816,12 @@ Ang entry ng agentmemory ay ang **parehong MCP server block** sa bawat host na g
| 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. |
+| **Cursor (buong plugin)** | `.cursor-plugin/` | I-install sa Cursor Marketplace o Settings → Plugins → local checkout. Nirerehistro ang lifecycle hooks sa pamamagitan ng maliit na adapter na tumatawag sa shared `plugin/scripts/*.mjs`, kasama ang skills at MCP. Tinutukoy ng adapter ang workspace na hindi palaging tama ang ulat ng Cursor. Tingnan ang [Cursor](#cursor). Gumagana sa Cursor IDE at `cursor-agent` CLI. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | I-merge sa `mcpServers`. I-restart ang Claude Desktop pagkatapos i-edit. |
| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Parehong `mcpServers` block. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | Pinagsasama ng `agentmemory connect devin` ang MCP entry; idinadagdag ng `--with-hooks` ang anim na native na auto-capture hook (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) gamit ang lowercase na tool matcher ng Devin. Patunayan gamit ang `devin mcp list` at `/hooks` sa loob ng devin. |
| **Devin CLI (buong plugin)** | `plugin/.devin-plugin/` | Nirerehistro ng `devin plugins install ./plugin` mula sa isang checkout ang lahat ng 17 skill bilang `/agentmemory:<skill>` 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. |
+| **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. |
@@ -804,7 +830,8 @@ Ang entry ng agentmemory ay ang **parehong MCP server block** sa bawat host na g
| **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). |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · native recall + capture + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · native recall + capture + skills. [Oh My Pi](../integrations/omp/) |
| **Hermes Agent** | `~/.hermes/config.yaml` | Ang `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` ay magbibigay ng 6-hook na memory provider (prefetch, turn capture, session end, pre-compress, MEMORY.md mirroring, system prompt block). Patunayan gamit ang `hermes plugins doctor` at `hermes memory status`. Tingnan ang [`integrations/hermes`](../integrations/hermes/). |
| **Qwen Code** | `~/.qwen/settings.json` | Isinusulat ng `agentmemory connect qwen` ang standard na `mcpServers` block. Field-compatible ang hook payload sa Claude Code, kaya gumagana ang umiiral na 12-hook scripts nang walang pagbabago; i-wire ito gamit ang `hooks` section sa parehong `settings.json`. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | Ini-install ng `agentmemory connect antigravity --with-hooks` ang MCP at capture hooks sa shared customization directory. Tingnan ang [setup at limitasyon ng Antigravity](../docs/plugins/antigravity.md). |
@@ -812,39 +839,19 @@ Ang entry ng agentmemory ay ang **parehong MCP server block** sa bawat host na g
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (preferred) o `config.json` (legacy) | Gumagawa ang `agentmemory connect continue` ng `config.yaml` kung wala pang configuration o ina-update ang kasalukuyang `config.json`. Hindi nito binabago ang umiiral na YAML upang mapanatili ang comments at anchors; ipinapakita ang block na ilalagay sa ilalim ng `mcpServers:`. Array ang gamit ng Continue para sa `mcpServers`. |
| **Zed** | `~/.config/zed/settings.json` | Isinusulat ng `agentmemory connect zed` sa ilalim ng `context_servers` (ang key ng Zed, HINDI `mcpServers`). Maaaring i-wire ang remote MCP server gamit ang `{"url": "..."}` sa halip. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | Isinusulat ng `agentmemory connect droid` ang standard na `mcpServers` block. Ang project-scoped override ay sa `<repo>/.factory/mcp.json`. Ipasa ang `--with-hooks` para sa native auto-capture. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | Ina-activate ng `agentmemory connect dsh` ang mga MCP tool. Idagdag ang `--with-hooks` para i-load ang native capture plugin na kasama sa AgentMemory. Hindi kailangan ng hiwalay na plugin package. [DSH](../docs/dsh.md). |
| **Goose** | Goose MCP settings UI | Parehong `mcpServers` block; gamitin ang `goose configure` → Add Extension → MCP. Suportado ang direktang YAML edit sa `~/.config/goose/config.yaml` pero ang schema ay gumagamit ng `extensions:` + `cmd` (hindi `mcpServers:` + `command`). |
-| **Aider** | n/a | Kausapin ang REST API nang direkta: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **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"},
-})
-```
+### Programmatic access
-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.
+Gamitin ang [REST API](#api) mula sa anumang wika o [MCP tools](#mcp-server) mula sa agent. JSON at Bearer authentication ang gamit ng REST; tingnan ang [halimbawa ng save at search](#validate-a-fresh-install-and-restart-persistence). Nasa [Python examples](../examples/python/) ang direktang runtime integration.
### Mula sa Source
@@ -853,130 +860,69 @@ 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=<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).
+Pinapatakbo ng `npm start` ang kaparehong local server ng naka-install na CLI. Nasa [Install](#install) ang mga kailangan; naka-bind ang API at viewer sa `127.0.0.1`.
### Windows
-Tumatakbo ang agentmemory sa Windows 10/11, 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.
+Tumatakbo ang agentmemory sa Windows 10/11. Awtomatikong nag-i-install ng engine ang WSL2 gamit ang Linux path. Sa native Windows, manu-manong i-install ang pinned na iii-engine v0.25.0: i-download ang archive mula sa [iii v0.25.0 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), tiyakin ang checksum, at ilagay ang `iii.exe` sa `PATH`. Hindi awtomatikong nag-e-extract ng ZIP ang CLI
-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
-```
+Native Windows MCP automation ay para lamang sa `agentmemory connect copilot-cli`; gamitin ang manual MCP block sa [Other agents](#other-agents) para sa iba. Sa WSL, patakbuhin ang `connect` lamang kung naroon din ang target agent
-**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:
+**Standalone MCP lang (walang engine).** Kung MCP tools lamang ang kailangan, at hindi ang REST API, viewer o runtime services:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Patakbuhin ang `agentmemory doctor` o i-restart gamit ang `--verbose`. Kung ginagamit na ang default ports, gumamit ng `--port <N>` o `--instance <N>`. Tingnan ang [upgrade guide](../docs/upgrades/iii-0.25.md) para sa compatibility at recovery.
---
<h2 id="deploy">Pag-deploy</h2>
-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.
+Mag-self-host gamit ang Docker Compose o mga platform template sa ibaba. Nasa `/data` volume ang memory at credentials. I-backup at gamitin muli ang volume sa upgrade. Tingnan ang [deployment guide](../deploy/README.md) para sa authentication, network, at migration.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="I-deploy sa fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="I-deploy sa Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="I-deploy sa fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="I-deploy sa Railway" /></a>
</p>
-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.
+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):
+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
+- [`../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,
+- [`../deploy/railway`](.././deploy/railway/README.md): Hobby plan na flat fee,
volume sa dashboard.
-- [`deploy/render`](.././deploy/render/README.md): Blueprint flow,
+- [`../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
+- [`../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.
+Port `3111` ang gamit ng REST at `3113` ng viewer. Panatilihing pribado ang access o protektahan gamit ang authentication at TLS. Nasa deployment guide ang platform access settings at [paglipat mula sa lumang Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
---
-
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Bakit agentmemory" height="32" /></picture></h2>
-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.
+Nagkakahiwa-hiwalay ang kaalaman sa proyekto sa mga chat at instruction file. Sa AgentMemory, mahahanap ng kasalukuyan mong agent ang mga dating desisyon, pag-aayos, at aral.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
- agentmemory silently captures every tool use
- Session ends -> observations compressed into structured memory
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### Kumpara sa Built-in na Memory ng Agent
@@ -985,7 +931,7 @@ Nag-ship ang bawat AI coding agent na may built-in memory: may `MEMORY.md` ang C
| | Built-in (CLAUDE.md) | agentmemory |
|---|---|---|
-| Sukat | 200-linyang cap | Walang Limitasyon |
+| Pagpapanatili | Manu-manong inayos na instructions | Naka-index na session history at memory |
| Paghahanap | Nilo-load ang lahat sa context | BM25 + vector + graph (top-K lamang) |
| Gastos sa Token | 22K+ sa 240 obserbasyon | ~1,900 token (92% mas kaunti) |
| Cross-agent | Per-agent na file | MCP + REST (kahit anong agent) |
@@ -1011,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-Tier Memory Consolidation
@@ -1035,6 +981,8 @@ Nauupos ang mga memory sa paglipas ng panahon (Ebbinghaus curve). Lumalakas ang
### Ano ang Nakukuha
+Inilalarawan ng talahanayan ang hooks ng Claude Code. Nirerekord ng ibang integration ang events na ibinibigay ng kanilang host. Opt-in ang awtomatikong context injection sa shared hooks gamit ang `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Nakukuha |
|------|----------|
| `SessionStart` | Project path, session ID |
@@ -1051,7 +999,7 @@ Nauupos ang mga memory sa paglipas ng panahon (Ebbinghaus curve). Lumalakas ang
| Kakayahan | Paglalarawan |
|---|---|
-| **Awtomatikong capture** | Naitatala ang bawat paggamit ng tool gamit ang hooks, walang manu-manong pagsisikap |
+| **Awtomatikong capture** | Nirerekord ng native integrations ang suportadong session at tool events |
| **Semantic search** | BM25 + vector + knowledge graph na may RRF fusion |
| **Ebolusyon ng memory** | Versioning, supersession, relationship graph |
| **Recall hygiene** | Umaalis sa search index ang mga superseded na bersyon ng memory; pinapanatili ng version chain sa KV ang buong history |
@@ -1269,187 +1217,6 @@ Nagbibind ang viewer server sa `127.0.0.1` bilang default at idinadagdag nito an
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="pahinang Workers ng iii console: mga kakonektang worker kasama ang mga instance ng agentmemory na may live function count at runtime metadata" width="720" />
- <br/>
- <em>Pahinang Workers: bawat kakonektang worker, kasama ang agentmemory mismo, na may PID, function count, runtime, at last-seen.</em>
-</p>
-
-**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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall view na nagpapakita ng per-span duration" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service breakdown para sa bawat memory operation.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Pinapagana ng iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`), 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 <name>` |
-
-**250 na source file · ~55,000 LOC · 3,400+ na test · 324 na function · 67 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfigurasyon" height="32" /></picture></h2>
### Mga LLM Provider
@@ -1467,6 +1234,8 @@ Awtomatikong tinutuklas ng agentmemory ang mga provider mula sa iyong environmen
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1516,24 +1285,9 @@ Nag-ship ang local embeddings bilang opsyonal na dependency pero hindi ito naka-
### 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.
+Magsimula nang walang key para sa capture at keyword search. Nagbibigay ang `EMBEDDING_PROVIDER=local` ng semantic search sa device matapos ang unang model download. Kailangan ng provider at `AGENTMEMORY_AUTO_COMPRESS=true` ang LLM compression, at maaaring may request kada observation; suriin ang kasalukuyang presyo.
-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/).
+`agentmemory status` / http://localhost:3113
### Multi-agent na Memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1563,41 +1317,22 @@ Kapag hindi naka-set ang `AGENT_ID`, nananatiling unscoped ang memory (legacy be
### 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.
+Naka-bind sa loopback ang API at viewer bilang default.
-| 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 <N>` 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.
+| Port | API / Viewer | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | Viewer | `III_VIEWER_PORT` |
-Stale-process cleanup kapag nananatiling bound ang mga port pagkatapos ng isang crashed run:
+Itinatakda ng `--port <N>` ang API port; `N+2` ang default ng viewer. Gumamit ng `--instance N` para sa hiwalay na instance. Panatilihing pribado ang internal listeners. Sundin ang deployment guide para sa remote access at [paglipat mula sa lumang Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage Backend: file (default) laban sa redis
-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.
+Hindi kailangan ng hiwalay na database service. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. Hindi awtomatikong kinokopya ang umiiral na memory kapag nagpalit ng backend. [Pag-iimbak ng data](../docs/reliability/state-storage.md).
### Config File
-Ilagay ang runtime 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:
+Ilagay ang runtime config sa `~/.agentmemory/.env` sa halip na mag-export ng variables sa bawat shell. Gamitin ang `AGENTMEMORY_ENV_FILE` upang pumili ng ibang env-file path. Mas mataas ang priority ng process environment variables kaysa sa file. Ipinapasa ng CLI-generated Worker Compose project ang Redis settings sa `state` worker.
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1622,179 +1357,34 @@ GRAPH_EXTRACTION_ENABLED=true
### Mga Environment Variable
-Gawin ang `~/.agentmemory/.env`:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Nasa [`.env.example`](../.env.example) ang buong reference, kasama ang provider, capture filter, retention, storage, at team scope. Pumili ng ibang file gamit ang `AGENTMEMORY_ENV_FILE`. I-restart pagkatapos magbago ng configuration. Huwag i-commit ang `.env` na may aktuwal na halaga o Bearer secret.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer <secret>`, at kinakailangan ng mga mesh sync endpoint ang tahasang naka-set na `AGENTMEMORY_SECRET` sa dalawang peer.
+146 na endpoint sa port `3111`. Nagbibind ang REST API sa `127.0.0.1` bilang default. Kinakailangan ng mga protected endpoint ang `Authorization: Bearer <secret>`, 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:
+Naka-on ang authentication bilang default. Kapag walang `AGENTMEMORY_SECRET`, gumagawa ang CLI ng random secret sa unang start sa `~/.agentmemory/secret` at kinokopya sa `secret` ng napiling data directory, na may mode `0600`. Inuuna ng bundled clients ang canonical file sa local connection at ipinapadala lang ang naka-save na secret sa loopback URL. Mas mataas ang prayoridad ng explicit na `AGENTMEMORY_SECRET`; dapat itong itakda ng remote clients sa environment. Gumagawa ang Docker deployment ng sarili nitong secret.
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1830,7 +1420,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Ibahagi sa team |
| `GET` | `/agentmemory/audit` | Audit trail |
-Kumpletong listahan ng endpoint: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Kumpletong listahan ng endpoint: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1848,19 +1438,19 @@ Uulitin ang mga nabigong event kada `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10
Kapag down ang server, hindi sumagot sa oras, o nagbalik ng 5xx, idinadagdag ng hook ang obserbasyon sa isang local spool file, `<data dir>/capture-spool/<host>-<port>.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.
+**Compacting Graph Provenance.** Ipinagpapaliban sa startup ang compaction ng lumang provenance dahil binabasa nito ang buong lumang scopes. Ipinapakita ng `/agentmemory/status` ang `deferred`, o `off` kapag `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Patakbuhin ang manual compaction sa ibaba habang nagme-maintenance. Hiwalay ang migration ng retrieval index: gamitin ang `agentmemory graph-index migrate --allow-legacy-scan` ayon sa [gabay sa maintenance](../docs/reliability/graph-index-migration.md).
Para patakbuhin ito nang manu-mano, tawagin ang `POST /agentmemory/graph/compact`. Dumadaan ito sa name at edge-key indexes sa halip na ilista ang bawat node at edge, at ligtas itong patakbuhin ulit. Kapag pinuputol nito ang mga id, isinusulat nito ang isang `graph_compact` audit entry.
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1874,7 +1464,7 @@ npm test # 4,000+ 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.
+Tingnan ang [Install](#install) para sa requirements at [CONTRIBUTING.md](../CONTRIBUTING.md) para sa contribution rules at release checks.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Lisensya" height="32" /></picture></h2>
diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md
index 85be7b66..46a034c6 100644
--- a/READMEs/README.tr-TR.md
+++ b/READMEs/README.tr-TR.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Kodlama ajanınız her şeyi hatırlar. Artık yeniden açıklamaya gerek yok.
- <a href="https://github.com/iii-hq/iii">iii engine</a> üzerine inşa edilmiştir
+ Kodlama oturumları ve ajanlar arasında kalıcı bellek.
</strong><br/>
- Claude Code, GitHub Copilot CLI, 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, Oh My Pi, DeepSeek Harness, OpenCode ve her MCP istemcisi için kalıcı bellek.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Nasıl Çalışır</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Görüntüleyici</a> &bull;
- <a href="#powered-by-iii">iii ile Çalışır</a> &bull;
<a href="#configuration">Yapılandırma</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory desteklenen oturum olaylarını kaydeder; kararları, düzeltmeleri ve dersleri farklı ajanlardan aranabilir hâle getirir. Görüntüleyicide anıları inceleyebilir, düzenleyebilir, dışa aktarabilir ve silebilirsiniz. Anahtar kelime araması API anahtarı gerektirmez; embedding’ler anlamsal arama ekler.
+
+<a id="install"></a>
+
## Kurulum
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.
+- macOS/Linux otomatik ortam kurulumu için ayrıca `curl`, POSIX `sh` ve `tar` gerektirir.
+- Windows’ta WSL2 veya [yerel Windows kurulumunu](#windows) kullanın.
Standart, sıfırdan kurulum komutu:
@@ -108,11 +111,11 @@ Standart, sıfırdan kurulum komutu:
npx -y @agentmemory/agentmemory@latest
```
-İ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.
+Ajanları ve bir sağlayıcıyı ya da anahtarsız modu seçin. Kurulum yapılandırmayı kaydeder, bellek sunucusunu başlatır ve `agentmemory` komutunun genel kurulumunu sunar. `-y` npm istemini kabul eder; `@latest` güncel sürümü seçer. LLM sıkıştırması sağlayıcı ve `AGENTMEMORY_AUTO_COMPRESS=true` gerektirir.
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.
-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 <path>` 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.
+API `http://localhost:3111`, görüntüleyici `http://localhost:3113` adresindedir. İkisi de varsayılan olarak yalnızca yerel bağlantıları dinler. Ayarlar `~/.agentmemory/.env` dosyasındadır; bellek dizinleri ve ayrı örnekler için [veri depolamaya](#data-storage) bakın.
Ardından recall'ın çalıştığını kanıtlayın ve ajanınıza skill'lerini verin:
@@ -127,14 +130,7 @@ Tüm işi bir kodlama ajanına bırakmayı mı tercih edersiniz? Ona şu tek tal
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-`agentmemory connect <agent>` 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.
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-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.
-
-</details>
+Başka bir ajanı `agentmemory connect <agent>` ile bağlayın. [Entegrasyonlara](#works-with-every-agent) ve [günlük komutlara](#everyday-commands) bakın.
<details>
<summary><strong>Genel (global) kurulum / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx, sürüm bazında önbelleğe alır. En güncel sürümü `npx -y @agentmemo
</details>
-<details>
-<summary><strong>Kendi iii engine'inizi zaten çalıştırıyorsanız</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalış
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>yerel eklenti + 7 hook + MCP</sub>
+<sub>yerel eklenti + yaşam döngüsü hook’ları + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalış
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>yerel eklenti + MCP</sub>
+<sub>yerel hatırlama + kayıt + beceriler</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalış
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP sunucusu</sub>
+<sub>yerel kayıt + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalış
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>yerel hatırlama + kayıt + beceriler + isteğe bağlı MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ agentmemory, hook'ları, MCP'yi veya REST API'yi destekleyen her ajanla çalış
---
-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.
+<a id="data-storage"></a>
-**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.
+### Veri depolama
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Anılar varsayılan olarak deponun dışında tutulur:
-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 <path>` geçirin veya `AGENTMEMORY_DATA_DIR` ayarlayın; her iki açık ayar da eski (legacy) keşfe göre önceliklidir:
+| Platform | Veri dizini |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Örnek 0, mevcut `./data/state_store.db` deposunu yeniden kullanır. `--data-dir <path>` veya `AGENTMEMORY_DATA_DIR` ile başka dizin seçin. Yeniden başlatma ve yükseltmelerde aynı dizini koruyun.
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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.
+`--instance 1`, `instance-1` alt dizinini, API için `3211` ve görüntüleyici için `3213` portunu kullanır. Redis ve taşıma için [depolama ve yedekleme rehberine](../docs/reliability/state-storage.md) bakın.
En son sürüm notları: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, scorecard'a bakın) %100
</tr>
<tr>
<td><strong>Harici bağımlılıklar</strong></td>
-<td>Yok (SQLite + iii-engine)</td>
+<td>Ayrı bir veritabanı hizmeti gerektirmez</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vektör DB</td>
<td>Birden fazla</td>
@@ -550,14 +549,12 @@ Bu corpus için **P@5 matematiksel tavanında** (0.240, scorecard'a bakın) %100
| 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, local-first bir görüntüleyici sunmaz veya anahtarsız çalışmaz — agentmemory'nin etrafında inşa edildiği kombinasyon budur.
+AgentMemory oturum kaydını, aranabilir proje geçmişini ve yerel görüntüleyiciyi birleştirir; anahtarsız çalışma ilk başlatmadan itibaren kullanılabilir.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-Uyumluluk: bu sürüm `iii-sdk` 0.22.1'i hedefler ve iii-engine v0.22.1'i sabitler.
-
### 30 saniyede deneyin
```bash
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Belleğin canlı olarak oluşumunu izlemek için `http://localhost:3113` adresini açın.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Sunucu çalışırken sağlığı, görüntüleyiciyi ve durumu kontrol edin:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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:
+`status` sunucu sağlığını, sağlayıcıları, embedding modunu, kayıt teslimini ve kurtarmayı gösterir. Korumalı REST istekleri sunucu sırrını gerektirir. Ayarladıysanız kendi `AGENTMEMORY_SECRET` değerinizi kullanın; aksi hâlde üretilen yerel sırrı okuyun:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### Günlük komutlar
Kurulum ve ayarlar yukarıdaki [Kurulum](#install) bölümünde (ilk çalıştırma sizi adım adım yönlendirir). Günlük kullanımda:
@@ -604,6 +610,9 @@ Kurulum ve ayarlar yukarıdaki [Kurulum](#install) bölümünde (ilk çalıştı
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
-İç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.
+İçe aktarılan oturumlar Replay’de yerel oturumların yanında görünür. Transkriptler indekslenir ve `import` kaynağıyla işaretlenir; işleme ayrıca oturum kristalleri ve dersler üretebilir.
> **`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.
@@ -635,14 +644,12 @@ Yerel runtime'ınızı kasıtlı olarak güncellemek istediğinizde bakım komut
npx -y @agentmemory/agentmemory@latest upgrade
```
-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 yaşar (`src/cli.ts:544-595` bölgesindeki `runUpgrade`'e bakın).
+Komut yerel ortamı günceller ve geçerli çalışma alanındaki JavaScript bağımlılıklarını değiştirebilir. Verileri yedekleyin ve [yükseltme rehberini](../docs/upgrades/iii-0.25.md) okuyun.
### Claude Code (tek blok, yapıştırın)
```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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Eklenti kurulumu olmadan Claude Code (MCP-bağımsız yol)
@@ -703,6 +710,30 @@ 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.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Ardından **Settings → Plugins → Add marketplace** üzerinden `.cursor-plugin/plugin.json` içeren agentmemory dizinini seçin, **agentmemory** eklentisini etkinleştirin ve pencereyi yeniden yükleyin. Eklenti yaşam döngüsü kaydı, çalışma alanına göre proje ataması, beceriler ve MCP sağlar. Çift kaydı önlemek için eklenti hook’larını veya `~/.cursor/hooks.json` içindeki elle eklenmiş hook’ları kullanın.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Kullandığınız istemciye uygun komutu seçin. Pi ve OMP yerel hatırlama, kayıt, çevrimdışı yeniden gönderme ve beceriler kurar; `--with-mcp` tüm araçları ekler. Pi’de `/reload` çalıştırın veya OMP’yi yeniden başlatın, sonra `/agentmemory-status` ile kontrol edin. DSH, MCP’yi ve paketle gelen kayıt eklentisini kurar; bağlantıdan sonra DSH’yi yeniden başlatın.
+
+Pi ayrıca kurulabilir `@agentmemory/pi` paketini destekler. Yerel kurulum ve npm durumu için [Pi rehberine](../integrations/pi/) bakın. Her istemcide tek kurulum yöntemi kullanın.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (bu prompt'u yapıştırın)</b></summary>
@@ -749,6 +780,8 @@ Tam kılavuz: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Diğer ajanlar
Bellek sunucusunu başlatın: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +798,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Bu, `agentmemory connect <agent>`'ı **tamamlayıcı** niteliktedir:
-- `agentmemory connect <agent>`, 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.
+- `agentmemory connect <agent>` genellikle MCP yapılandırmasını yazar. Hermes, OpenClaw, Pi ve Oh My Pi varsayılan olarak yerel entegrasyonu ve becerileri kurar; MCP için `--with-mcp` kullanılır.
+- `npx skills add rohitg00/agentmemory`, yerel becerileri paketlenmemiş ajanlara beceri kurar. Hermes, OpenClaw, Pi ve Oh My Pi için bu adımı atlayın; bağlayıcıları becerileri zaten kurar.
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.
@@ -790,12 +823,12 @@ agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude
| Ajan | Yapılandırma dosyası | Notlar |
|---|---|---|
| **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). |
+| **Cursor (tam eklenti)** | `.cursor-plugin/` | Eklenti Cursor IDE ve `cursor-agent` için yaşam döngüsü hook’ları, çalışma alanı tespiti, beceriler ve MCP sağlar. [Cursor kurulumuna](#cursor) bakın. |
| **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 (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:<skill>` 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. |
+| **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ı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`. |
@@ -804,7 +837,8 @@ agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude
| **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`). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. yerel hatırlama + kayıt + beceriler. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. yerel hatırlama + kayıt + beceriler. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +846,19 @@ agentmemory girdisi, `mcpServers` şeklini kullanan her host'ta (Cursor, Claude
| **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. |
+| **Continue.dev** | `~/.continue/config.yaml` (tercih edilen) veya `config.json` (eski/legacy) | `agentmemory connect continue`, yapılandırma yoksa `config.yaml` oluşturur veya mevcut `config.json` dosyasını değiştirir. Mevcut YAML için yorumları ve çapaları koruyarak `mcpServers:` altına eklenecek bloğu gösterir. Continue nesne yerine dizi 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 `<repo>/.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` MCP araçlarını etkinleştirir. AgentMemory ile gelen yerel kayıt eklentisini yüklemek için `--with-hooks` ekleyin. Ayrı bir eklenti paketi gerekmez. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | yok | Betiklerden kaydetmek ve aramak için [kimlik doğrulamalı REST örneklerini](#validate-a-fresh-install-and-restart-persistence) kullanın. |
| **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.
-
-```bash
-pip install iii-sdk # Python
-cargo add iii-sdk # Rust
-npm install iii-sdk # Node
-```
-
-```python
-from iii import register_worker
-
-iii = register_worker("ws://localhost:49134")
-iii.connect()
-
-iii.trigger({
- "function_id": "mem::smart-search",
- "payload": {"project": "demo", "query": "how do tokens refresh"},
-})
-```
-
-Çalışan örnek: [`examples/python/`](../examples/python/) (quickstart + gözlem/recall akışı). `:3111` üzerindeki REST, iii runtime'ı olmayan host'lar için kullanılabilir olmayı sürdürür.
+Herhangi bir dilden [REST API’yi](#api), bir ajandan [MCP araçlarını](#mcp-server) kullanın. REST, JSON ve bearer kimlik doğrulaması kullanır; [kayıt ve arama örneğine](#validate-a-fresh-install-and-restart-persistence) bakın. Doğrudan ortam entegrasyonu için [Python örneklerini](../examples/python/) inceleyin.
### Kaynaktan
@@ -853,122 +867,56 @@ git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
-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.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=<version>` ile geçersiz kılın.
-
-- **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.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 (paketlenmiş `docker-compose.yml`, `iiidev/iii:0.22.1`'i çeker). Tam dokümantasyon: [iii.dev/docs](https://iii.dev/docs).
+`npm start`, kurulu CLI ile aynı yerel sunucuyu başlatır. Gereksinimler [Kurulum](#install) bölümündedir; API ve görüntüleyici `127.0.0.1` üzerinde dinler.
### Windows
-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.
-
-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.
+agentmemory Windows 10/11’de çalışır. WSL2 Linux yolunu izleyerek engine’i otomatik kurabilir. Yerel Windows’ta iii-engine v0.25.0 elle kurulmalıdır: arşivi [iii v0.25.0 sürüm sayfasından](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) indirin, checksum’u doğrulayın ve `iii.exe` dosyasını `PATH` üzerine koyun. CLI Windows ZIP’ini otomatik açmaz
-**Seçenek A: önceden derlenmiş (prebuilt) Windows binary (önerilen)**
+Yerel Windows’ta otomatik MCP yapılandırması yalnızca `agentmemory connect copilot-cli` için vardır; diğerleri için [Other agents](#other-agents) bölümünü kullanın. WSL’de `connect` yalnızca hedef agent aynı WSL ortamındaysa çalıştırılmalıdır
-```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
-```
-
-**Seçenek 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
-```
-
-**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:
+**Yalnızca standalone MCP (engine olmadan).** REST API, görüntüleyici veya runtime hizmetleri gerekmiyorsa:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
npx -y @agentmemory/mcp
```
-**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 | Çözüm |
-|---|---|
-| `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 çatışması | Neyin bağlı olduğunu görmek için `netstat -ano \| findstr :3111`, ardından onu sonlandırın veya `--port <N>` 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 **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.
+`agentmemory doctor` çalıştırın veya `--verbose` ile yeniden başlatın. Portlar doluysa `--port <N>` veya `--instance <N>` kullanın. Uyumluluk ve kurtarma için [yükseltme rehberine](../docs/upgrades/iii-0.25.md) bakın.
---
<h2 id="deploy">Deploy</h2>
-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.
+Kendi sunucunuz için Docker Compose veya aşağıdaki şablonları kullanın. Bellek ve kimlik bilgileri `/data` birimindedir; yükseltirken yedekleyin ve yeniden kullanın. Kimlik doğrulama, ağ, yedekler ve taşıma için [dağıtım rehberine](../deploy/README.md) bakın.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
-Render'ın tek tı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.
+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, rotasyon, yedekleme,
-maliyet tabanları) [`deploy/`](.././deploy/README.md) içinde yaşar:
+maliyet tabanları) [`../deploy/`](.././deploy/README.md) içinde yaşar:
-- [`deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"` ile tek
+- [`../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,
+- [`../deploy/railway`](.././deploy/railway/README.md): Hobby plan sabit ücret,
dashboard'da volume.
-- [`deploy/render`](.././deploy/render/README.md): Blueprint akışı,
+- [`../deploy/render`](.././deploy/render/README.md): Blueprint akışı,
ücretli planlarda otomatik disk snapshot'ları.
-- [`deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted) ile kendi
+- [`../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 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.
+REST `3111`, görüntüleyici `3113` portunu kullanır. Özel ağda tutun veya kimlik doğrulama ve TLS ile koruyun. Platform ayarları ve [eski Docker kurulumu taşıması](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) dağıtım rehberindedir.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-Her kodlama ajanı, oturum sona erdiğinde her şeyi unutur 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"
- 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.
-```
+Proje bilgisi sohbetlere ve talimat dosyalarına dağılır. AgentMemory önceki kararları, düzeltmeleri ve dersleri kullandığınız ajandan aranabilir hâle getirir.
### Yerleşik ajan belleğiyle karşılaştırma
@@ -976,7 +924,7 @@ Her AI kodlama ajanı, yerleşik bellekle gelir: Claude Code'da `MEMORY.md`, Cur
| | Yerleşik (CLAUDE.md) | agentmemory |
|---|---|---|
-| Ölçek | 200 satır sınırı | Sınırsız |
+| Bakım | Elle düzenlenen talimatlar | İndekslenmiş oturum geçmişi ve anılar |
| 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) |
@@ -1002,13 +950,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4 Katmanlı Bellek Konsolidasyonu
@@ -1026,6 +974,8 @@ Bellekler zamanla çürür (Ebbinghaus eğrisi). Sık erişilen bellekler güçl
### Ne Yakalanır
+Tablo Claude Code hook’larını açıklar. Diğer entegrasyonlar istemcilerinin sunduğu olayları kaydeder. Ortak hook’lar üzerinden otomatik bağlam ekleme isteğe bağlıdır: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Yakaladığı |
|------|----------|
| `SessionStart` | Proje path'i, oturum ID'si |
@@ -1042,7 +992,7 @@ Bellekler zamanla çürür (Ebbinghaus eğrisi). Sık erişilen bellekler güçl
| Yetenek | Açıklama |
|---|---|
-| **Otomatik yakalama** | Her tool kullanımı hook'lar üzerinden kaydedilir, manuel çaba yok |
+| **Otomatik yakalama** | Yerel entegrasyonların kaydettiği desteklenen oturum ve araç olayları |
| **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 |
@@ -1260,187 +1210,6 @@ Görüntüleyici sunucusu, varsayılan olarak `127.0.0.1`'e bağlanır ve istekl
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-`:3113`'teki görüntüleyici, ajanınızın **hatırladığı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ı → 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 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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers sayfası: canlı fonksiyon sayıları ve runtime metadata'sı ile agentmemory instance'ları dahil bağlı worker'lar" width="720" />
- <br/>
- <em>Workers sayfası: agentmemory'nin kendisi dahil her bağlı worker; PID, fonksiyon sayısı, runtime ve son-görülme ile birlikte.</em>
-</p>
-
-**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ın:**
-
-```bash
-agentmemory console
-```
-
-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`.
-
-Aynı şeyi elle yapmak, `agentmemory` PATH'te olmadığında kullanışlıdır:
-
-```bash
-~/.agentmemory/bin/iii console --port 3114 \
- --engine-port 3111 \
- --ws-port 3112 \
- --bridge-port 49134
-```
-
-**Console'dan yapabilecekleriniz:**
-
-| Sayfa | Şunun için kullanın |
-|------|-----------|
-| **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ı. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace waterfall görünümü, span başına süreyi gösteriyor" width="720" />
- <br/>
- <em>Traces: her bellek işlemi için waterfall / flame / service breakdown.</em>
-</p>
-
-**Trace'ler zaten açık:**
-
-`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 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:** 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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory, **zaten çalışan bir [iii](https://iii.dev) 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, bir komut daha ile agentmemory'yi tamamen yeni bir yetenekle genişletebileceğiniz anlamına gelir.
-
-### agentmemory'yi daha fazla worker ile genişletin
-
-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.
-
-```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'nin üstüne ne eklenir |
-|---|---|
-| [`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:<scope>`, `stream:<name>:<group>`) 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.
-
-**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'nin kullandığı |
-|---|---|
-| 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 <name>` |
-
-**250 kaynak dosya · ~55,000 LOC · 3,400+ test · 324 fonksiyon · 67 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
### LLM Sağlayıcıları
@@ -1458,6 +1227,8 @@ agentmemory, sağlayıcıları ortamınızdan otomatik olarak algılar. Bir sağ
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Yerel modeller (Ollama / LM Studio / vLLM)
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.
@@ -1507,24 +1278,7 @@ Yerel embedding'ler opsiyonel bir bağımlılık olarak gelir, ancak varsayılan
### Maliyet bilincine sahip model seçimi
-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 için maliyet | Notlar |
-|------|-------|------------|-------------|---------------------------|-------|
-| Ö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 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; (tah.) satırları, aynı token karışımını her modelin liste fiyatıyla ölçekler.
-
-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 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/).
+Kayıt ve anahtar kelime araması için anahtarsız başlayın. `EMBEDDING_PROVIDER=local`, model indirildikten sonra yerel anlamsal arama sağlar. LLM sıkıştırması sağlayıcı ve `AGENTMEMORY_AUTO_COMPRESS=true` gerektirir; her gözlem bir istek oluşturabileceğinden güncel fiyatları kontrol edin. Görüntüleyici ve `agentmemory status` etkin sağlayıcıları gösterir.
### Çoklu-ajan belleği (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1554,41 +1308,24 @@ SDK / REST katmanında çağrı başına geçersiz kılma: her mutasyon endpoint
### Portlar
-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 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 <N>`, 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.
+| Port | Amaç | Ortam değişkeni |
+|---|---|---|
+| `3111` | REST API, MCP HTTP ve canlı görüntüleyici olayları | `III_REST_PORT` |
+| `3113` | Görüntüleyici arayüzü | `III_VIEWER_PORT` |
-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.
+`--port <N>` REST portunu ve varsayılan görüntüleyici portunu `N+2` olarak ayarlar. `--instance N` ayrı ortam oluşturur. İç portlar özel kalmalıdır; uzaktan erişimden önce [dağıtım rehberini](../deploy/README.md) okuyun.
-Çökmüş bir çalıştırmadan sonra portlar bağlı kaldığında, bayatlamış (stale) süreç temizliği:
+### Depolama: dosya veya Redis
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
-
-`agentmemory stop`, 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.
+Varsayılan dosya deposu ayrı veritabanı gerektirmez. Redis, `AGENTMEMORY_STATE_BACKEND=redis` ve `AGENTMEMORY_REDIS_URL` ile isteğe bağlıdır. Backend değişikliği mevcut belleği taşımaz. Kalıcılık, Redis sınırları ve kimlik doğrulamalı dışa/içe aktarım [depolama rehberindedir](../docs/reliability/state-storage.md).
### Yapılandırma Dosyası
-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.
+Runtime yapılandırmasını her shell’de değişken export etmek yerine `~/.agentmemory/.env` içine koyun.
-Süreç ortam değişkenleri hâlâ çalışır ve dosyadaki değerlere göre önceliklidir.
+İşlem ortam değişkenleri dosyadaki değerlerden önce gelir. Yapılandırma değişince sunucuyu yeniden başlatın.
-Windows'ta, aynı dosya `%USERPROFILE%\.agentmemory\.env`'de yaşar:
+`%USERPROFILE%\.agentmemory\.env`
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1613,179 +1350,31 @@ GRAPH_EXTRACTION_ENABLED=true
### Ortam Değişkenleri
-`~/.agentmemory/.env` dosyasını oluşturun:
+`~/.agentmemory/.env` için yaygın seçenekler. Bağlam ekleme ve sıkıştırma isteğe bağlıdır; sıkıştırma ayrıca sağlayıcı gerektirir. `core` modu görünür MCP araçlarını sınırlar:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Tam [`.env.example`](../.env.example) sağlayıcıları, kayıt filtrelerini, saklama sürelerini, depolamayı, ekipleri ve isteğe bağlı özellikleri kapsar. `AGENTMEMORY_ENV_FILE` başka dosya seçer. Doldurulmuş `.env` veya bearer sırrını asla commit etmeyin.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-`3111` portunda 143 endpoint. REST API, varsayılan olarak `127.0.0.1`'e bağlanır. Korumalı endpoint'ler `Authorization: Bearer <secret>` gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir `AGENTMEMORY_SECRET` gerektirir.
+`3111` portunda 146 endpoint. REST API, varsayılan olarak `127.0.0.1`'e bağlanır. Korumalı endpoint'ler `Authorization: Bearer <secret>` gerektirir ve mesh sync endpoint'leri her iki peer'da da açıkça ayarlanmış bir `AGENTMEMORY_SECRET` gerektirir.
+
+**Kimlik doğrulama varsayılan olarak açıktır.** `AGENTMEMORY_SECRET` ayarlanmamışsa CLI ilk başlatmada `~/.agentmemory/secret` dosyasında `0600` izinleriyle rastgele bir sır oluşturur ve seçilen veri dizinine de kopyalar. Paketli istemciler yerel sunucuya bağlanırken buradan okur; secret yalnız loopback URL’lerine (`localhost`, `127.0.0.0/8`, `::1`) gönderilir. Uzak istemciler secret’ı kendi ortamında sağlamalıdır. Docker self-host ve `deploy/` kendi secret’larını üretir. API’yi elle çağırmak için:
-**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
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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.
@@ -1821,7 +1410,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Takımla paylaş |
| `GET` | `/agentmemory/audit` | Audit izi |
-Tam endpoint listesi: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Tam endpoint listesi: [Üretilen REST referansı](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1839,19 +1428,19 @@ Başarısız olaylar, `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`'e (5) kadar, ikiye katl
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, `<data dir>/capture-spool/<host>-<port>.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.
+**Graf provenance'ını kırpma (compacting).** Eski provenance verilerinin kırpılması, eski scope’ların tamamını okuduğu için başlangıçta ertelenir. `/agentmemory/status`, `deferred` veya `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` olduğunda `off` bildirir. Aşağıdaki manuel kırpmayı bakım sırasında çalıştırın. Arama indeksi geçişi ayrıdır: [bakım kılavuzunda](../docs/reliability/graph-index-migration.md) açıklandığı gibi `agentmemory graph-index migrate --allow-legacy-scan` kullanı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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1865,7 +1454,7 @@ npm test # 4,000+ tests
npm run test:integration # API tests (requires running services)
```
-**Ö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.
+Gereksinimler [Kurulum](#install) bölümündedir. Katkı kuralları ve sürüm kontrolleri [CONTRIBUTING.md](../CONTRIBUTING.md) dosyasındadır.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.md
index 629eed37..bc335531 100644
--- a/READMEs/README.uk-UA.md
+++ b/READMEs/README.uk-UA.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- Ваш агент кодування пам'ятає все. Більше не потрібно пояснювати все заново.
- Створено на основі <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Постійна пам’ять між сесіями й агентами розробки.
</strong><br/>
- Постійна пам'ять для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode та будь-якого MCP-клієнта.
+ Постійна пам'ять для Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode та будь-якого MCP-клієнта.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="Ліцензія" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Зірки" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Як це працює</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Переглядач</a> &bull;
- <a href="#powered-by-iii">На основі iii</a> &bull;
<a href="#configuration">Конфігурація</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory зберігає підтримувані події сесій і дає змогу шукати рішення, виправлення та уроки між агентами. У viewer можна переглядати, редагувати, експортувати й видаляти спогади. Пошук за словами працює без API-ключа; ембединги додають семантичний пошук.
+
+<a id="install"></a>
+
## Встановлення
Вимоги:
- 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 — інші підтримувані шляхи.
+- Для автоматичного налаштування середовища macOS/Linux також потрібні `curl`, POSIX-оболонка `sh` і `tar`.
+- У Windows використовуйте WSL2 або [інструкцію для нативного встановлення](#windows).
Канонічна команда для чистого встановлення:
@@ -108,11 +111,11 @@
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`.
+Виберіть агентів і постачальника або режим без ключа. Майстер запише налаштування, запустить сервер пам’яті й запропонує глобальне встановлення команди `agentmemory`. `-y` підтверджує запит npm; `@latest` вибирає поточний випуск. Стиснення через 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 <path>` або `AGENTMEMORY_DATA_DIR`, щоб перевизначити це значення, і повторно використовуйте те саме значення під час кожного перезапуску. Для зворотної сумісності наявний `./data/state_store.db` або `./data/iii-config.yaml` має пріоритет над платформовим значенням за замовчуванням для інстансу 0; явний прапорець або змінна середовища все одно перемагають.
+API працює на `http://localhost:3111`, viewer на `http://localhost:3113`. Типово обидва слухають лише локальні з’єднання. Налаштування містяться в `~/.agentmemory/.env`; каталоги пам’яті й окремі інстанси описано в розділі [зберігання даних](#data-storage).
Потім перевірте, що пригадування працює, і дайте агенту його скіли:
@@ -127,14 +130,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-Підключайте більше агентів у будь-який момент за допомогою `agentmemory connect <agent>` — 20 адаптерів перелічено у розділі [Працює з кожним агентом](#works-with-every-agent). Повний довідник команд — у розділі [Швидкий старт](#quick-start).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-Найшвидший шлях — WSL2. Налаштування нативного двигуна Windows вимагає вручну завантажити закріплений ZIP-архів v0.22.1 і розпакувати `iii.exe`; CLI не розпаковує його автоматично. Docker Desktop також підтримується. Покрокову інструкцію дивіться у розділі [Примітки щодо Windows](#windows).
-
-</details>
+Підключіть іншого агента через `agentmemory connect <agent>`. Див. [інтеграції](#works-with-every-agent) та [щоденні команди](#everyday-commands).
<details>
<summary><strong>Глобальне встановлення / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx кешує за версіями. Примусово отримайте ос
</details>
-<details>
-<summary><strong>У вас уже працює власний iii engine</strong></summary>
-
-agentmemory закріплений за iii-engine v0.22.1 і не підключиться до іншої версії (воркер не може розмовляти протоколом іншого двигуна). Зупиніть інший двигун, потім запустіть `npx -y @agentmemory/agentmemory@latest`. Він встановить і запустить закріплену версію v0.22.1 у `~/.agentmemory/bin`, не торкаючись вашого власного `iii`.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Працює з кожним агентом" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory працює з будь-яким агентом, що підтри
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>нативний плагін + 7 хуків + MCP</sub>
+<sub>нативний плагін + хуки життєвого циклу + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory працює з будь-яким агентом, що підтри
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>нативний плагін + MCP</sub>
+<sub>нативне пригадування + захоплення + скіли</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory працює з будь-яким агентом, що підтри
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP-сервер</sub>
+<sub>нативне захоплення + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory працює з будь-яким агентом, що підтри
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>нативне пригадування + захоплення + скіли + необов’язковий MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,26 @@ agentmemory працює з будь-яким агентом, що підтри
---
-Ви пояснюєте ту саму архітектуру щосесії. Ви повторно виявляєте ті самі помилки. Ви повторно навчаєте агента тим самим уподобанням. Вбудована пам'ять (CLAUDE.md, .cursorrules) обмежена 200 рядками і швидко застаріває. agentmemory вирішує цю проблему. Він непомітно фіксує те, що робить ваш агент, стискає це у пам'ять із можливістю пошуку і вставляє потрібний контекст на початку наступної сесії. Одна команда. Працює між агентами.
+<a id="data-storage"></a>
-**Що змінюється:** у сесії 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 <path>` або встановіть `AGENTMEMORY_DATA_DIR`; будь-яке з явних налаштувань має пріоритет над застарілим виявленням:
+| Платформа | Каталог даних |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
+
+Інстанс 0 повторно використовує наявний `./data/state_store.db`. Інший каталог задається через `--data-dir <path>` або `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
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-Нативні запуски та запуски в Docker використовують той самий визначений каталог хоста; Docker монтує його як `/data`. `--instance 1` додає `instance-1` до визначеного каталогу і обирає окремий квартет портів за замовчуванням `3211/3212/3213/49234`.
+`--instance 1` використовує підкаталог `instance-1`, порт API `3211` і viewer `3213`. Redis і міграцію описано в [посібнику зі зберігання та резервування](../docs/reliability/state-storage.md).
Примітки до останнього релізу: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +475,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>Зовнішні залежності</strong></td>
-<td>Немає (SQLite + iii-engine)</td>
+<td>Окрема служба бази даних не потрібна</td>
<td>Qdrant / pgvector</td>
<td>Postgres + векторна БД</td>
<td>Декілька</td>
@@ -550,14 +549,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | Темпоральний граф знань; найкращі опубліковані результати для темпоральних запитів (LongMemEval 63.8%), але граф будується асинхронно, тому нові факти можуть надходити із затримкою |
| Cognee | 30K | Перетворення документів на граф знань, лише Python, створено для структурованого видобування сутностей, а не для захоплення сесій |
-Жоден з них не має автозахоплення через хуки агентів кодування, не постачається з локальним переглядачем і не працює без ключа — саме це поєднання лежить в основі agentmemory.
+AgentMemory поєднує захоплення сесій, пошук в історії проєкту й локальний viewer; робота без ключа доступна з першого запуску.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Швидкий старт" height="32" /></picture></h2>
-Сумісність: цей реліз орієнтований на `iii-sdk` 0.22.1 і закріплює iii-engine v0.22.1.
-
### Спробуйте за 30 секунд
```bash
@@ -572,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
Відкрийте `http://localhost:3113`, щоб спостерігати за побудовою пам'яті в реальному часі.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### Перевірка чистого встановлення та стійкості після перезапуску
-Поки сервер працює, перевірте REST, стан здоров'я, переглядач і статус рантайму на основі iii:
+Із запущеним сервером перевірте здоров’я, viewer і стан:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +582,27 @@ 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 та активний режим постачальника/ембедингів. Збережіть тестовий запис і перевірте, що його можна знайти:
+`status` показує стан сервера, постачальників, режим ембедингів, доставку спостережень і відновлення. Захищені REST-запити потребують секрет сервера. Використовуйте заданий `AGENTMEMORY_SECRET`, інакше завантажте згенерований локальний секрет:
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
Потім виконайте `npx -y @agentmemory/agentmemory@latest stop`, знову запустіть канонічну команду в терміналі 1, дочекайтеся `/agentmemory/livez` і повторіть пошук. Тестовий запис має й надалі повертатися. Якщо ви обрали власний `--data-dir`, передайте той самий каталог під час перезапуску.
+<a id="everyday-commands"></a>
+
### Щоденні команди
Встановлення та налаштування описані в розділі [Встановлення](#install) вище (перший запуск проведе вас через цей процес). Щодня:
@@ -604,6 +610,9 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
+agentmemory status
+agentmemory capture
+agentmemory capture --drain
agentmemory connect <agent> # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
@@ -623,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-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` і аналізується для створення кристала сесії та уроків.
+Імпортовані сесії з’являються в Replay поруч із нативними. Транскрипти індексуються й отримують канал походження `import`; обробка також може створювати кристали сесій та уроки.
> **Важливо, якщо ви покладаєтеся на `import-jsonl` як на основний шлях захоплення:** `cleanupPeriodDays` Claude Code (у `~/.claude/settings.json`, за замовчуванням **30**) автоматично видаляє JSONL-транскрипти, старіші за це вікно, з `~/.claude/projects/`. Якщо ви встановлюєте agentmemory на вже кількамісячну історію Claude Code, усе старіше за 30 днів уже зникло ще до першого імпорту. Або запускайте `import-jsonl` за розкладом (cron), або підвищте `cleanupPeriodDays`, або підключіть хуки автозахоплення (типовий шлях встановлення плагіна), щоб кожен крок потрапляв в agentmemory, поки сесія активна, і очищення JSONL більше не мало значення.
@@ -635,14 +644,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-Попередження: ця команда змінює поточний робочий простір/рантайм. Вона може оновити залежності JavaScript і завантажити закріплений Docker-образ `iiidev/iii:0.22.1`. Вона ніколи не встановлює незакріплений або новіший iii engine.
-
-Деталі реалізації містяться в `src/cli.ts` (див. `runUpgrade` у межах `src/cli.ts:544-595`).
+Команда оновлює локальне середовище й може змінити JavaScript-залежності поточного workspace. Зробіть резервну копію даних і прочитайте [посібник з оновлення](../docs/upgrades/iii-0.25.md).
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code без встановлення плагіна (автономний шлях MCP)
@@ -703,6 +710,30 @@ 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`. Встановіть також плагін, якщо хочете отримати повний досвід роботи з хуками/скілами.
+### Cursor
+
+```bash
+agentmemory connect cursor
+```
+
+Потім у **Settings → Plugins → Add marketplace** виберіть каталог agentmemory з `.cursor-plugin/plugin.json`, увімкніть плагін **agentmemory** і перезавантажте вікно. Плагін забезпечує захоплення життєвого циклу, визначення проєкту за workspace, скіли й MCP. Увімкніть або хуки плагіна, або ручні хуки в `~/.cursor/hooks.json`, щоб уникнути дублювання.
+
+[Cursor](../integrations/cursor/)
+
+### Pi, Oh My Pi, DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Виберіть команду для свого клієнта. Pi та OMP встановлюють нативне пригадування, захоплення, повторне надсилання офлайн-даних і скіли; `--with-mcp` додає всі інструменти. Виконайте `/reload` у Pi або перезапустіть OMP, потім перевірте `/agentmemory-status`. DSH встановлює MCP і вбудований плагін захоплення; після підключення перезапустіть DSH.
+
+Pi також підтримує пакет `@agentmemory/pi`. Локальне встановлення й доступність npm описано в [посібнику Pi](../integrations/pi/). Використовуйте один спосіб встановлення на клієнт.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (вставте цей промпт)</b></summary>
@@ -749,6 +780,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### Інші агенти
Запустіть сервер пам'яті: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +798,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Це **доповнює** `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` записує конфігурацію MCP-сервера, щоб інструменти стали доступними.
-- `npx skills add rohitg00/agentmemory` встановлює скіли, щоб агент знав, коли їх викликати.
+- `agentmemory connect <agent>` зазвичай записує конфігурацію MCP. Hermes, OpenClaw, Pi та Oh My Pi типово встановлюють нативну інтеграцію та скіли; MCP вмикається через `--with-mcp`.
+- `npx skills add rohitg00/agentmemory` встановлює скіли для агентів без вбудованого набору. Для Hermes, OpenClaw, Pi та Oh My Pi пропустіть цей крок: їхні конектори вже встановлюють скіли.
Для декількох агентів, які CLI skills ще не підтримує (Zed v1.3.x і нижче), розмістіть 17 файлів SKILL.md у нативному каталозі скілів агента самостійно; той самий формат працює всюди.
@@ -790,12 +823,12 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| Агент | Конфігураційний файл | Примітки |
|---|---|---|
| **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 доповнюються з транскрипту сесії в кінці сесії. |
+| **Cursor (повний плагін)** | `.cursor-plugin/` | Плагін надає хуки життєвого циклу, визначення workspace, скіли й MCP у Cursor IDE та `cursor-agent`. Див. [налаштування Cursor](#cursor). |
| **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:<skill>` разом із 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 інструментів. |
+| **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. |
@@ -804,7 +837,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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). |
+| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi --with-mcp`. нативне пригадування + захоплення + скіли. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). |
+| **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. нативне пригадування + захоплення + скіли. [Oh My Pi](../integrations/omp/). |
| **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). |
@@ -812,39 +846,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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` форму масиву (а не об'єкта). |
+| **Continue.dev** | `~/.continue/config.yaml` (бажано) або `config.json` (застарілий) | `agentmemory connect continue` створює `config.yaml`, якщо налаштувань немає, або змінює наявний `config.json`. Для наявного YAML показує блок для `mcpServers:`, зберігаючи коментарі та якорі. Continue використовує масив, а не об’єкт. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed` записує дані під `context_servers` (ключ Zed, НЕ `mcpServers`). Віддалені MCP-сервери замість цього можна підключити через `{"url": "..."}`. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid` записує стандартний блок `mcpServers`. Перевизначення на рівні проєкту розміщуються в `<repo>/.factory/mcp.json`. Передайте `--with-hooks` для нативного автозахоплення. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` вмикає інструменти MCP. Додайте `--with-hooks`, щоб завантажити вбудований в AgentMemory плагін запису подій. Окремий пакет плагіна не потрібен. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | н/д | Для збереження й пошуку зі скриптів використовуйте [REST-приклади з автентифікацією](#validate-a-fresh-install-and-restart-persistence). |
| **Будь-який агент (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.
+Використовуйте [REST API](#api) з будь-якої мови або [інструменти MCP](#mcp-server) з агента. REST використовує JSON і bearer-автентифікацію; див. [приклад збереження й пошуку](#validate-a-fresh-install-and-restart-persistence). Пряму інтеграцію середовища показано в [прикладах Python](../examples/python/).
### Зі джерельного коду
@@ -853,132 +867,57 @@ 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=<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).
+`npm start` запускає той самий локальний сервер, що й встановлений CLI. Вимоги наведено у [Встановленні](#install); API та viewer слухають `127.0.0.1`.
### 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.
+agentmemory працює у Windows 10/11; WSL2 може автоматично встановити engine. Нативна Windows потребує ручного встановлення iii-engine v0.25.0: завантажте архів зі [сторінки iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), перевірте checksum і розмістіть `iii.exe` у `PATH`. CLI не розпаковує ZIP автоматично
-**Варіант A: готовий бінарний файл для Windows (рекомендовано)**
+Автоматичне налаштування MCP у нативній Windows підтримує лише `agentmemory connect copilot-cli`; для інших скористайтеся [Other agents](#other-agents). У WSL виконуйте `connect`, лише якщо агент встановлений у тому самому середовищі
-```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, повністю обійдіться без двигуна:
+**Лише standalone MCP без engine.** Якщо не потрібні REST API, переглядач і служби runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| Резервний варіант 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`.
+Запустіть `agentmemory doctor` або перезапустіть із `--verbose`. Якщо порти зайняті, використовуйте `--port <N>` або `--instance <N>`. Сумісність і відновлення описано в [посібнику з оновлення](../docs/upgrades/iii-0.25.md).
---
<h2 id="deploy">Розгортання</h2>
-Шаблони в один клік для керованих хостів. Кожен із них постачається із
-самодостатнім 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.
+Для власного розгортання використовуйте Docker Compose або шаблони нижче. Пам’ять і облікові дані містяться на томі `/data`; резервуйте його й використовуйте повторно під час оновлення. Автентифікацію, мережу, резервування та міграцію описано в [посібнику з розгортання](../deploy/README.md).
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Розгорнути на fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Розгорнути на Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Розгорнути на fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Розгорнути на Railway" /></a>
</p>
-Кнопка розгортання в один клік для Render вимагає `render.yaml` у корені репозиторію, який ми свідомо тримаємо чистим. Скористайтеся процесом Render Blueprint, описаним у [`deploy/render/`](.././deploy/render/README.md), щоб вручну вказати на blueprint усередині репозиторію.
+Кнопка розгортання в один клік для Render вимагає `render.yaml` у корені репозиторію, який ми свідомо тримаємо чистим. Скористайтеся процесом Render Blueprint, описаним у [`../deploy/render/`](.././deploy/render/README.md), щоб вручну вказати на blueprint усередині репозиторію.
Повні деталі налаштування (захоплення HMAC, SSH-тунель для переглядача, ротація, резервне копіювання,
-мінімальна вартість) містяться в [`deploy/`](.././deploy/README.md):
+мінімальна вартість) містяться в [`../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): самостійний хостинг на
+- [`../deploy/coolify`](.././deploy/coolify/README.md): самостійний хостинг на
власному VPS через [Coolify](https://coolify.io/self-hosted); той самий Docker
Compose-стек, хост і дані залишаються у вас.
-Публікується лише порт `3111`. Переглядач на `3113` стає
-прив'язаним до loopback усередині контейнера; README кожного шаблону документує
-схему SSH-тунелю для доступу до нього.
+REST використовує `3111`, viewer `3113`. Залиште їх у приватній мережі або захистіть автентифікацією й TLS. Налаштування платформ і [міграцію старого Docker](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) описано в посібнику з розгортання.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Чому agentmemory" height="32" /></picture></h2>
-Кожен агент кодування забуває все, коли сесія закінчується, і кожна нова сесія починається з того, що ви повторно пояснюєте свій стек. 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.
-```
+Знання про проєкт розподілені між чатами й файлами інструкцій. AgentMemory дає змогу шукати попередні рішення, виправлення та уроки з поточного агента.
### Порівняно з вбудованою пам'яттю агента
@@ -986,7 +925,7 @@ Session 2: "Now add rate limiting"
| | Вбудована (CLAUDE.md) | agentmemory |
|---|---|---|
-| Масштаб | Обмеження 200 рядків | Без обмежень |
+| Обслуговування | Інструкції, редаговані вручну | Індексована історія сесій і спогади |
| Пошук | Завантажує все у контекст | BM25 + вектор + граф (лише топ-K) |
| Вартість у токенах | 22K+ при 240 спостереженнях | ~1,900 токенів (на 92% менше) |
| Між агентами | Файли для кожного агента | MCP + REST (будь-який агент) |
@@ -1012,13 +951,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-рівнева консолідація пам'яті
@@ -1036,6 +975,8 @@ SessionStart hook fires
### Що фіксується
+Таблиця описує хуки Claude Code. Інші інтеграції захоплюють події, доступні в їхньому клієнті. Автоматичне додавання контексту через спільні хуки вмикається явно: `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Хук | Фіксує |
|------|----------|
| `SessionStart` | Шлях до проєкту, ID сесії |
@@ -1052,7 +993,7 @@ SessionStart hook fires
| Можливість | Опис |
|---|---|
-| **Автоматичне захоплення** | Кожне використання інструменту записується через хуки, без ручних дій |
+| **Автоматичне захоплення** | Підтримувані події сесій та інструментів, записані нативними інтеграціями |
| **Семантичний пошук** | BM25 + вектор + граф знань зі злиттям RRF |
| **Еволюція пам'яті** | Версіювання, заміщення, графи зв'язків |
| **Гігієна пригадування** | Заміщені версії пам'яті зникають з пошукових індексів; ланцюжок версій у KV зберігає повну історію |
@@ -1270,187 +1211,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="Консоль iii" height="32" /></picture></h2>
-
-Переглядач на `:3113` показує, що ваш агент **запам'ятав**. [Консоль iii](https://iii.dev/docs/console) показує, що ваш агент **зробив**: кожну операцію з пам'яттю як трасування OpenTelemetry, кожен запис KV можна редагувати, кожну функцію можна викликати, кожен потік можна підключити для прослуховування. Два вікна на ту саму пам'ять: одне у формі продукту, інше — у формі двигуна.
-
-Спостерігайте за спрацюванням `memory_smart_search` і бачте сканування BM25 → пошук ембединга → злиття RRF → реранкер як каскад. Редагуйте застряглий таймер консолідації в браузері KV. Відтворюйте хук `PostToolUse` зі зміненим корисним навантаженням. Закріпіть потік WebSocket і спостерігайте, як спостереження надходять у реальному часі.
-
-agentmemory надає це безкоштовно, тому що кожен виклик функції та тригер спрацьовує через iii; нічого власного, нічого інструментувати.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Сторінка Workers консолі iii: підключені воркери, включно з інстансами agentmemory, з показниками кількості функцій у реальному часі та метаданими рантайму" width="720" />
- <br/>
- <em>Сторінка Workers: кожен підключений воркер, включно з самим agentmemory, з PID, кількістю функцій, рантаймом і часом останньої активності.</em>
-</p>
-
-**Уже встановлено.** Консоль постачається разом із закріпленим двигуном `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`) Інтерактивний граф архітектури кожного воркера, тригера і потоку. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Перегляд waterfall трасування консолі iii, що показує тривалість кожного спана" width="720" />
- <br/>
- <em>Traces: waterfall / flame / розбивка за сервісами для кожної операції з пам'яттю.</em>
-</p>
-
-**Трасування вже увімкнено:**
-
-`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` (значення за замовчуванням) і ніколи не публікуйте її назовні.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="На основі iii" height="32" /></picture></h2>
-
-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:<scope>`, `stream:<name>:<group>`) фіксовані, тому два інстанси 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 <name>` |
-
-**250 вихідних файлів · ~55,000 LOC · 3,400+ тестів · 324 функцій · 67 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Конфігурація" height="32" /></picture></h2>
### Постачальники LLM
@@ -1468,6 +1228,8 @@ agentmemory автоматично визначає постачальників
| **Локальний (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=<your model>` | Усе, що сумісне з OpenAI API. Нульова вартість, працює на вашому обладнанні. Див. [Локальні моделі](#local-models-ollama--lm-studio--vllm) нижче. |
| Запасний варіант через підписку Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Лише за явним підключенням. Породжує сесії `@anthropic-ai/claude-agent-sdk`; раніше це спричиняло необмежену рекурсію хука Stop, тож більше не є значенням за замовчуванням. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### Локальні моделі (Ollama / LM Studio / vLLM)
agentmemory спілкується з будь-яким сервером, сумісним з OpenAI API, тож усе, що надає `/v1/chat/completions`, працює без змін у коді. Без платних ключів, без хмари, без обмежень частоти запитів; працює повністю на вашому обладнанні.
@@ -1517,24 +1279,7 @@ OPENAI_MODEL=qwen3-8b # match the model name from LM St
### Вибір моделі з урахуванням вартості
-Коли фонове стиснення, написане 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/).
+Почніть без ключа для захоплення й пошуку за словами. `EMBEDDING_PROVIDER=local` вмикає локальний семантичний пошук після завантаження моделі. Стиснення LLM потребує постачальника й `AGENTMEMORY_AUTO_COMPRESS=true`; запит можливий для кожного спостереження, тому перевірте поточні ціни. Viewer та `agentmemory status` показують активних постачальників.
### Пам'ять для кількох агентів (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1564,41 +1309,24 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### Порти
-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 <N>` змінює якір REST і виводить потоки `N+1`, переглядач `N+2` та WebSocket двигуна `N+46023`, але лише там, де відповідний явний порт чи URL вище не встановлено. Це не створює ізольований простір імен життєвого циклу. Використовуйте `--instance 1` для другого демона; він використовує якір 3211, за замовчуванням `3211/3212/3213/49234`, і отримує окремий каталог даних і життєвого циклу `instance-1`. Інстанси від 1 до 50 дотримуються того самого шаблону.
+| Port | Призначення | Змінна середовища |
+|---|---|---|
+| `3111` | REST API, MCP HTTP і живі події viewer | `III_REST_PORT` |
+| `3113` | Інтерфейс viewer | `III_VIEWER_PORT` |
-Закріплений двигун запускається з `--no-update-check` (без пошуку оновлень чи порад безпеки проти GitHub під час завантаження) і з вимкненою анонімною телеметрією використання iii: agentmemory встановлює `III_TELEMETRY_ENABLED=false` для двигуна, який він породжує, якщо ви самі не експортували цю змінну, і вбудований compose-файл робить те саме.
+`--port <N>` задає REST-порт, а viewer типово використовує `N+2`. `--instance N` створює окреме середовище. Внутрішні порти мають залишатися приватними; перед зовнішнім доступом прочитайте [посібник з розгортання](../deploy/README.md).
-Очищення застарілих процесів, коли порти залишаються зайнятими після аварійного завершення:
+### Сховище: файл або Redis
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
-
-`agentmemory stop` коректно прибирає як воркер, так і pid-файл двигуна під час штатного нативного завершення роботи. У режимі Docker вона зливає нативний воркер, зупиняє саме той перевірений контейнер двигуна і зберігає як контейнер, так і його монтування `/data` для безвтратного перезапуску; наступний запуск перевіряє і відновлює той самий контейнер. Видалення на основі Docker потребує `agentmemory remove --keep-data`: ця команда видаляє спільні файли, якими керує agentmemory, зберігаючи перевірений контейнер, його монтування даних і запис життєвого циклу, потрібний для їхнього відновлення. Руйнівне видалення даних Docker навмисно залишено на оператора після резервного копіювання. CLI також відмовляється приймати у власність або сигналізувати власникам портів Docker чи VM (Docker backend, vpnkit, colima) як нативному двигуну, якщо не передано `--force`. Ручне очищення вище призначене лише для випадку після аварійного завершення, коли жодного pid-файлу не залишилося.
+Типове файлове сховище не потребує окремої бази. Redis вмикається через `AGENTMEMORY_STATE_BACKEND=redis` і `AGENTMEMORY_REDIS_URL`. Зміна бекенду не переносить пам’ять. Надійність запису, обмеження Redis та автентифікований експорт/імпорт описано в [посібнику зі зберігання](../docs/reliability/state-storage.md).
### Файл конфігурації
-Розмістіть конфігурацію рантайму agentmemory в `~/.agentmemory/.env`, а не експортуйте змінні в кожній оболонці. Якщо переглядач показує підказку налаштування, таку як `export ANTHROPIC_API_KEY=...`, скопіюйте її в цей файл як `ANTHROPIC_API_KEY=...` без префіксу `export`, потім перезапустіть agentmemory.
+Зберігайте конфігурацію runtime у `~/.agentmemory/.env`, а не експортуйте змінні в кожній shell.
-Змінні середовища процесу все ще працюють і мають пріоритет над значеннями у файлі.
+Змінні середовища процесу мають пріоритет над файлом. Після зміни налаштувань перезапустіть сервер.
-На Windows той самий файл розташовано в `%USERPROFILE%\.agentmemory\.env`:
+`%USERPROFILE%\.agentmemory\.env`
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1623,179 +1351,31 @@ GRAPH_EXTRACTION_ENABLED=true
### Змінні середовища
-Створіть `~/.agentmemory/.env`:
+Основні параметри `~/.agentmemory/.env`. Додавання контексту й стиснення вмикаються явно; стиснення також потребує постачальника. Режим `core` обмежує видимі інструменти MCP:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+# AGENTMEMORY_INJECT_CONTEXT=true
+# AGENTMEMORY_AUTO_COMPRESS=true
# AGENTMEMORY_TOOLS=core
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Повний довідник [`.env.example`](../.env.example) містить постачальників, фільтри захоплення, строки зберігання, сховище, команди й додаткові функції. `AGENTMEMORY_ENV_FILE` вибирає інший файл. Ніколи не комітьте заповнений `.env` або bearer-секрет.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 ендпоінтів на порту `3111`. REST API за замовчуванням прив'язується до `127.0.0.1`. Захищені ендпоінти вимагають `Authorization: Bearer <secret>`, а ендпоінти синхронізації mesh вимагають явно встановленого `AGENTMEMORY_SECRET` на обох сторонах.
+146 ендпоінтів на порту `3111`. REST API за замовчуванням прив'язується до `127.0.0.1`. Захищені ендпоінти вимагають `Authorization: Bearer <secret>`, а ендпоінти синхронізації mesh вимагають явно встановленого `AGENTMEMORY_SECRET` на обох сторонах.
+
+**Автентифікацію ввімкнено типово.** Якщо `AGENTMEMORY_SECRET` не задано, під час першого запуску CLI створює випадковий секрет у `~/.agentmemory/secret` з правами `0600` і копіює його також у вибраний каталог даних. Вбудовані клієнти читають його звідти для локального сервера; secret надсилається лише на loopback URL (`localhost`, `127.0.0.0/8`, `::1`). Віддалені клієнти мають отримати secret через власне середовище. Docker self-host і `deploy/` створюють власні секрети. Щоб викликати API вручну:
-**Автентифікація увімкнена за замовчуванням.** Коли `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
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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, сервер-до-сервера), не впливають на це. Переглядач також приймає власне джерело.
@@ -1831,7 +1411,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | Поширити серед команди |
| `GET` | `/agentmemory/audit` | Журнал аудиту |
-Повний перелік ендпоінтів: [`src/triggers/api.ts`](../src/triggers/api.ts)
+Повний перелік ендпоінтів: [Згенерований довідник REST](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1849,19 +1429,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
Коли сервер не працює, не відповідає вчасно або повертає 5xx, хук додає спостереження до локального файлу спулу, `<data dir>/capture-spool/<host>-<port>.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`, щоб вимкнути це.
+**Компактування походження графа.** Компактування старих даних походження відкладається під час запуску, оскільки воно читає старі області повністю. `/agentmemory/status` повідомляє `deferred` або `off`, якщо `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Виконуйте описане нижче ручне компактування під час обслуговування. Міграція пошукового індексу є окремою операцією: використовуйте `agentmemory graph-index migrate --allow-legacy-scan` згідно з [посібником з обслуговування](../docs/reliability/graph-index-migration.md).
Щоб запустити це вручну, викличте `POST /agentmemory/graph/compact`. Він обходить індекси імен та ключів ребер, замість перелічування кожного вузла і ребра, і безпечний для повторного запуску. Коли він обрізає id, він записує запис аудиту `graph_compact`.
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1875,7 +1455,7 @@ npm test # 4,000+ 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.
+Вимоги наведено у [Встановленні](#install). Правила участі й перевірки випуску містяться в [CONTRIBUTING.md](../CONTRIBUTING.md).
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Ліцензія" height="32" /></picture></h2>
diff --git a/READMEs/README.ur-PK.md b/READMEs/README.ur-PK.md
index 5697899e..19b50c6e 100644
--- a/READMEs/README.ur-PK.md
+++ b/READMEs/README.ur-PK.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- آپ کا کوڈنگ ایجنٹ سب کچھ یاد رکھتا ہے۔ دوبارہ وضاحت کرنے کی ضرورت نہیں۔
- <a href="https://github.com/iii-hq/iii">iii engine</a> پر تیار کیا گیا
+ کوڈنگ سیشنز اور ایجنٹس کے درمیان مستقل میموری۔
</strong><br/>
- Claude Code، GitHub Copilot CLI، Cursor، Gemini CLI، Codex CLI، Hermes، OpenClaw، pi، OpenCode، اور کسی بھی MCP کلائنٹ کے لیے مستقل میموری۔
+ Claude Code، GitHub Copilot CLI، Cursor، Gemini CLI، Codex CLI، Hermes، OpenClaw، pi، Oh My Pi، DeepSeek Harness، OpenCode، اور کسی بھی MCP کلائنٹ کے لیے مستقل میموری۔
</p>
<p align="center">
@@ -65,6 +64,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="لائسنس" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="سٹارز" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -89,20 +89,23 @@
<a href="#how-it-works">یہ کیسے کام کرتا ہے</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">ویور</a> &bull;
- <a href="#powered-by-iii">iii سے تقویت یافتہ</a> &bull;
<a href="#configuration">کنفیگ</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory کوڈنگ سیشن ریکارڈ کرتا ہے تاکہ پرانے فیصلے اور اصلاحات تلاش کیے جا سکیں۔ مختلف ٹولز میں ایک ہی میموری اسٹور استعمال کریں، محفوظ مواد دیکھیں اور ماڈل کو دیا جانے والا سیاق منتخب کریں۔
+
+<a id="install"></a>
+
## انسٹال
تقاضے:
- 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 دیگر معاون راستے ہیں۔
+- macOS/Linux پر خودکار سیٹ اپ کے لیے `curl`، POSIX `sh` اور `tar` درکار ہیں۔
+- Windows / WSL2: [Windows](#windows).
معیاری fresh-install کمانڈ:
@@ -110,11 +113,11 @@
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` بھی سیٹ ہو۔
+ایجنٹ اور فراہم کنندہ یا بغیر کلید والا موڈ منتخب کریں۔ سیٹ اپ ترتیب محفوظ کرکے میموری سرور شروع کرتا ہے اور عالمی تنصیب کا اختیار دیتا ہے۔ `-y` npm کی تصدیق قبول کرتا ہے؛ `@latest` تازہ ترین ریلیز منتخب کرتا ہے۔ LLM کمپریشن کے لیے فراہم کنندہ اور `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 <path>` یا `AGENTMEMORY_DATA_DIR` استعمال کریں، اور ہر ریسٹارٹ پر وہی قدر دہرائیں۔ بیک ورڈ compatibility کے لیے، موجودہ `./data/state_store.db` یا `./data/iii-config.yaml` انسٹنس 0 کے لیے پلیٹ فارم ڈیفالٹ پر فوقیت رکھتا ہے؛ ایک واضح فلیگ یا ماحولیاتی اوور رائیڈ پھر بھی جیت جاتا ہے۔
+API کا پتہ `http://localhost:3111` اور براہ راست ویوئر کا `http://localhost:3113` ہے۔ دونوں بطور طے شدہ loopback استعمال کرتے ہیں۔ ترتیب `~/.agentmemory/.env` میں ہوتی ہے۔ [ڈیٹا اسٹوریج](#data-storage).
پھر ثابت کریں کہ ریکال کام کر رہا ہے اور اپنے ایجنٹ کو اس کی اسکلز دیں:
@@ -129,14 +132,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-کسی بھی وقت `agentmemory connect <agent>` سے مزید ایجنٹس جوڑیں — 20 adapters [ہر ایجنٹ کے ساتھ کام کرتا ہے](#works-with-every-agent) میں درج ہیں۔ مکمل کمانڈ ریفرنس [فوری آغاز](#quick-start) میں ہے۔
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-سب سے تیز راستہ WSL2 ہے۔ نیٹیو Windows انجن سیٹ اپ کے لیے pinned v0.22.1 ZIP ڈاؤن لوڈ کرنا اور `iii.exe` کو دستی طور پر ایکسٹریکٹ کرنا ضروری ہے؛ CLI اسے خودکار طور پر ایکسٹریکٹ نہیں کرتا۔ Docker Desktop بھی معاون ہے۔ مرحلہ وار تفصیل کے لیے [Windows نوٹس](#windows) دیکھیں۔
-
-</details>
+`agentmemory connect <agent>` سے مزید ایجنٹ جوڑیں۔ [معاون انضمام](#works-with-every-agent) اور [روزمرہ کمانڈز](#everyday-commands) دیکھیں۔
<details>
<summary><strong>Global install / EACCES</strong></summary>
@@ -156,13 +152,6 @@ npx ہر ورژن کو علیحدہ طور پر کیش کرتا ہے۔ `npx -y @
</details>
-<details>
-<summary><strong>آپ کا اپنا iii engine پہلے سے چل رہا ہے</strong></summary>
-
-agentmemory iii-engine v0.22.1 کو pin کرتا ہے اور کسی مختلف ورژن سے منسلک نہیں ہوتا (ورکر کسی دوسرے انجن کا پروٹوکول نہیں بول سکتا)۔ دوسرا انجن روکیں، پھر `npx -y @agentmemory/agentmemory@latest` چلائیں۔ یہ pinned v0.22.1 کو `~/.agentmemory/bin` میں انسٹال اور چلاتا ہے، جبکہ آپ کا اپنا `iii` بغیر چھیڑے رہتا ہے۔
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="ہر ایجنٹ کے ساتھ کام کرتا ہے" height="32" /></picture></h2>
@@ -189,7 +178,7 @@ agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>نیٹیو پلگ ان + 7 ہکس + MCP</sub>
+<sub>مقامی پلگ ان + lifecycle hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -216,7 +205,7 @@ agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>نیٹیو پلگ ان + MCP</sub>
+<sub>مقامی recall + capture + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -282,7 +271,7 @@ agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP سرور</sub>
+<sub>مقامی capture + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -305,6 +294,12 @@ agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>مقامی recall + capture + skills + اختیاری MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -313,22 +308,24 @@ agentmemory کسی بھی ایسے ایجنٹ کے ساتھ کام کرتا ہے
---
-آپ ہر سیشن میں وہی architecture دوبارہ بیان کرتے ہیں۔ آپ وہی bugs دوبارہ ڈھونڈتے ہیں۔ آپ وہی ترجیحات دوبارہ سکھاتے ہیں۔ بلٹ-اِن میموری (CLAUDE.md، .cursorrules) 200 لائنز پر رک جاتی ہے اور پرانی ہو جاتی ہے۔ agentmemory یہ مسئلہ حل کرتا ہے۔ یہ خاموشی سے وہ سب کچھ ریکارڈ کرتا ہے جو آپ کا ایجنٹ کرتا ہے، اسے searchable میموری میں compress کرتا ہے، اور اگلا سیشن شروع ہوتے ہی درست context انجیکٹ کرتا ہے۔ صرف ایک کمانڈ۔ تمام ایجنٹس پر کام کرتا ہے۔
+<a id="data-storage"></a>
-**کیا بدلتا ہے:** سیشن 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
-```
+میموری بطور طے شدہ ریپوزٹری کے باہر محفوظ ہوتی ہے۔ انسٹینس 0 موجودہ `./data/state_store.db` دوبارہ استعمال کرتا ہے۔ `--data-dir <path>` یا `AGENTMEMORY_DATA_DIR` سے جگہ منتخب کریں اور دوبارہ آغاز یا اپ گریڈ میں وہی ڈائریکٹری رکھیں۔
-ڈیفالٹ کے طور پر، 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 <path>` پاس کریں یا `AGENTMEMORY_DATA_DIR` سیٹ کریں؛ دونوں میں سے کوئی بھی واضح سیٹنگ legacy discovery پر فوقیت رکھتی ہے:
+| پلیٹ فارم | ڈیٹا ڈائریکٹری |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-نیٹیو اور Docker دونوں لانچز اسی resolved ہوسٹ ڈائرکٹری کو استعمال کرتے ہیں؛ Docker اسے `/data` پر bind-mount کرتا ہے۔ `--instance 1` resolved ڈائرکٹری میں `instance-1` شامل کرتا ہے اور علیحدہ ڈیفالٹ پورٹ quartet `3211/3212/3213/49234` منتخب کرتا ہے۔
+`--instance 1` ذیلی ڈائریکٹری `instance-1`، API پورٹ `3211` اور ویوئر پورٹ `3213` استعمال کرتا ہے۔ Redis اور بیک اینڈ منتقلی کے لیے [اسٹوریج اور بیک اپ](../docs/reliability/state-storage.md) دیکھیں۔
تازہ ترین ریلیز نوٹس: [CHANGELOG.md](../CHANGELOG.md)۔
@@ -478,7 +475,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>خارجی انحصار</strong></td>
-<td>کوئی نہیں (SQLite + iii-engine)</td>
+<td>الگ ڈیٹابیس سروس درکار نہیں</td>
<td>Qdrant / pgvector</td>
<td>Postgres + ویکٹر DB</td>
<td>متعدد</td>
@@ -552,14 +549,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| 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 تعمیر کیا گیا ہے۔
+AgentMemory سیشن capture، قابل تلاش منصوبے کی تاریخ اور مقامی ویوئر اکٹھے فراہم کرتا ہے، اور پہلی بار سے بغیر کلید کام کر سکتا ہے۔
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="فوری آغاز" height="32" /></picture></h2>
-مطابقت: یہ ریلیز `iii-sdk` 0.22.1 کو ہدف بناتی ہے اور iii-engine v0.22.1 کو pin کرتی ہے۔
-
### 30 سیکنڈ میں آزمائیں
```bash
@@ -574,9 +569,11 @@ npx -y @agentmemory/agentmemory@latest demo
میموری کو لائیو بنتے دیکھنے کے لیے `http://localhost:3113` کھولیں۔
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### ایک تازہ انسٹال اور ریسٹارٹ persistence کی توثیق کریں
-سرور چلنے کی حالت میں، REST، health، ویور، اور iii پر مبنی رن ٹائم اسٹیٹس کی توثیق کریں:
+سرور چلتے ہوئے صحت، ویوئر اور حالت کی جانچ کریں۔
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -585,20 +582,27 @@ 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 محفوظ کریں اور تصدیق کریں کہ وہ تلاش کے قابل ہے:
+`status` سرور کی صحت، فراہم کنندہ، embedding mode، capture delivery اور بحالی دکھاتا ہے۔ محفوظ REST درخواست میں سرور کا راز درکار ہے۔ مقررہ `AGENTMEMORY_SECRET` استعمال کریں؛ ورنہ بنایا گیا مقامی راز پڑھیں۔
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
پھر `npx -y @agentmemory/agentmemory@latest stop` چلائیں، Terminal 1 میں معیاری کمانڈ دوبارہ شروع کریں، `/agentmemory/livez` کا انتظار کریں، اور سرچ دہرائیں۔ probe اب بھی واپس آنا چاہیے۔ اگر آپ نے کسٹم `--data-dir` منتخب کیا تھا، تو ریسٹارٹ پر وہی ڈائرکٹری پاس کریں۔
+<a id="everyday-commands"></a>
+
### روزمرہ کی کمانڈز
انسٹال اور سیٹ اپ اوپر [انسٹال](#install) میں موجود ہیں (پہلی بار چلانے پر آپ کی رہنمائی ہوتی ہے)۔ روزمرہ:
@@ -606,7 +610,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -625,7 +632,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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 نکالے جاتے ہیں۔
+درآمد شدہ سیشن Replay میں مقامی سیشن کے ساتھ نظر آتے ہیں، تلاش کے لیے انڈیکس ہوتے ہیں اور origin channel `import` پاتے ہیں۔ سیشن کی پروسیسنگ سے crystals اور 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 غیر اہم ہو جائے۔
@@ -637,14 +644,12 @@ Import کیے گئے سیشنز نیٹیو سیشنز کے ساتھ Replay picke
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` دیکھیں)۔
+یہ مقامی رن ٹائم اپ ڈیٹ کرتا ہے اور موجودہ ورکنگ ڈائریکٹری کی JavaScript dependencies بھی بدل سکتا ہے۔ ڈیٹا کا بیک اپ لیں اور موجودہ تنصیب اپ ڈیٹ کرنے سے پہلے [اپ گریڈ گائیڈ](../docs/upgrades/iii-0.25.md) پڑھیں۔
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code بغیر plugin انسٹال کے (MCP-standalone راستہ)
@@ -705,6 +710,26 @@ 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 بھی انسٹال کریں۔
+### Cursor
+
+`agentmemory connect cursor` سے MCP ترتیب دیں۔ **Settings → Plugins → Add marketplace** میں `.cursor-plugin/plugin.json` والا checkout منتخب کریں، agentmemory فعال کریں اور reload کریں۔ پلگ ان lifecycle capture، workspace شناخت، skills اور MCP دیتا ہے۔ دوہری capture سے بچنے کے لیے پلگ ان hooks یا `~/.cursor/hooks.json` کے دستی hooks میں سے ایک ہی استعمال کریں۔
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+اپنے ہوسٹ کی کمانڈ منتخب کریں۔ Pi اور OMP مقامی recall/capture، آف لائن replay اور 17 skills نصب کرتے ہیں؛ `--with-mcp` مکمل ٹول سیٹ شامل کرتا ہے۔ Pi میں `/reload` چلائیں یا OMP دوبارہ شروع کریں، پھر `/agentmemory-status` دیکھیں۔ DSH، MCP اور ساتھ آنے والا capture plugin نصب کرتا ہے؛ جوڑنے کے بعد دوبارہ شروع کریں۔
+
+Pi کے لیے قابل تنصیب `@agentmemory/pi` پیکیج بھی ہے۔ مقامی تنصیب اور npm کی دستیابی کے لیے [Pi گائیڈ](../integrations/pi/) دیکھیں۔ ہر ہوسٹ پر ایک ہی طریقہ استعمال کریں۔
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (یہ prompt پیسٹ کریں)</b></summary>
@@ -751,6 +776,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### دیگر ایجنٹس
میموری سرور شروع کریں: `npx -y @agentmemory/agentmemory@latest`
@@ -767,8 +794,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
یہ `agentmemory connect <agent>` کا **تکمیلی (complementary)** ہے:
-- `agentmemory connect <agent>` MCP سرور کنفیگ لکھتا ہے تاکہ ٹولز دستیاب ہو جائیں۔
-- `npx skills add rohitg00/agentmemory` اسکلز انسٹال کرتا ہے تاکہ ایجنٹ کو معلوم ہو کہ انہیں کب کال کرنا ہے۔
+Hermes، OpenClaw، Pi اور Oh My Pi connectors بطور طے شدہ مقامی انضمام اور skills نصب کرتے ہیں؛ MCP کو `--with-mcp` سے شامل کریں۔ دوسرے ہوسٹس پر `npx skills add rohitg00/agentmemory` سے skills نصب کریں۔
ان چند ایجنٹس کے لیے جنہیں skills CLI ابھی کَوَر نہیں کرتا (Zed v1.3.x اور اس سے نیچے)، خود 17 SKILL.md فائلیں ایجنٹ کی نیٹیو اسکل ڈائرکٹری میں رکھیں؛ وہی فارمیٹ ہر جگہ کام کرتا ہے۔
@@ -792,12 +818,12 @@ agentmemory کا entry ہر اس host پر **ایک ہی MCP سرور بلاک**
| ایجنٹ | کنفیگ فائل | نوٹس |
|---|---|---|
| **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 ہوتے ہیں۔ |
+| **Cursor (مکمل plugin)** | `.cursor-plugin/` | Cursor Marketplace یا Settings → Plugins → مقامی checkout سے نصب کریں۔ مختصر adapter مشترکہ `plugin/scripts/*.mjs` چلا کر lifecycle hooks رجسٹر کرتا ہے اور skills و MCP فراہم کرتا ہے۔ یہ Cursor کی نامکمل اطلاع سے workspace شناخت کرتا ہے۔ [Cursor](#cursor) دیکھیں۔ Cursor IDE اور `cursor-agent` CLI میں کام کرتا ہے۔ |
| **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:<skill>` سلیش کمانڈز کے طور پر رجسٹر کرتا ہے نیز 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" استعمال کریں۔ |
+| **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`۔ |
@@ -806,7 +832,8 @@ agentmemory کا entry ہر اس host پر **ایک ہی MCP سرور بلاک**
| **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`)۔ |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · مقامی recall + capture + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · مقامی recall + capture + skills. [Oh My Pi](../integrations/omp/) |
| **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)۔ |
@@ -814,39 +841,19 @@ agentmemory کا entry ہر اس host پر **ایک ہی MCP سرور بلاک**
| **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 نہیں) استعمال کرتا ہے۔ |
+| **Continue.dev** | `~/.continue/config.yaml` (ترجیحی) یا `config.json` (legacy) | `agentmemory connect continue` ترتیب نہ ہونے پر `config.yaml` بناتا ہے یا موجودہ `config.json` اپ ڈیٹ کرتا ہے۔ موجودہ YAML کے comments اور anchors محفوظ رکھنے کے لیے اسے تبدیل نہیں کرتا، بلکہ `mcpServers:` کے نیچے چسپاں کرنے کا بلاک دکھاتا ہے۔ Continue کا `mcpServers` ایک array ہے۔ |
| **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 `<repo>/.factory/mcp.json` میں جاتے ہیں۔ نیٹیو auto-capture کے لیے `--with-hooks` پاس کریں۔ |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` سے MCP ٹول فعال ہوتے ہیں۔ AgentMemory میں شامل مقامی کیپچر پلگ ان لوڈ کرنے کے لیے `--with-hooks` شامل کریں۔ الگ پلگ ان پیکیج کی ضرورت نہیں ہے۔ [DSH](../docs/dsh.md). |
| **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"}'`۔ |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **کوئی بھی ایجنٹ (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 بدستور دستیاب ہے۔
+کسی بھی زبان سے [REST API](#api) یا ایجنٹ سے [MCP ٹولز](#mcp-server) استعمال کریں۔ REST میں JSON اور Bearer توثیق درکار ہے؛ [محفوظ کرنے اور تلاش کی مثال](#validate-a-fresh-install-and-restart-persistence) دیکھیں۔ رن ٹائم سے براہ راست انضمام کے لیے [Python مثالیں](../examples/python/) موجود ہیں۔
### سورس سے
@@ -855,114 +862,64 @@ 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=<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)۔
+`npm start` نصب شدہ CLI والا ہی مقامی سرور شروع کرتا ہے۔ ضروریات [تنصیب](#install) میں ہیں؛ API اور ویوئر `127.0.0.1` استعمال کرتے ہیں۔
### 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 بائنری (تجویز کردہ)**
+agentmemory Windows 10/11 پر چلتا ہے؛ WSL2 Linux طریقے سے engine خود انسٹال کر سکتا ہے۔ Native Windows پر iii-engine v0.25.0 binary دستی طور پر انسٹال کریں: [iii v0.25.0 release page](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) سے archive ڈاؤن لوڈ، checksum کی تصدیق، اور `iii.exe` کو `PATH` پر رکھیں۔ CLI ZIP خود نہیں کھولتا
-```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
-```
+Native Windows پر MCP خودکار wiring صرف `agentmemory connect copilot-cli` کے لیے ہے؛ دوسرے agents کے لیے [Other agents](#other-agents) کا دستی MCP block استعمال کریں۔ WSL میں `connect` تب چلائیں جب target agent وہیں نصب ہو
-**آپشن C: صرف اسٹینڈ الون MCP (کوئی انجن نہیں)۔** اگر آپ کو اپنے ایجنٹ کے لیے صرف MCP ٹولز درکار ہیں اور REST API، ویور، یا cron jobs کی ضرورت نہیں، تو انجن کو مکمل طور پر نظرانداز کریں:
+**صرف standalone MCP، engine کے بغیر۔** اگر REST API، viewer یا runtime services درکار نہ ہوں:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` استعمال کریں |
-| 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` میں لاتا ہے۔
+`agentmemory doctor` چلائیں یا `--verbose` کے ساتھ دوبارہ آغاز کریں۔ طے شدہ پورٹس مصروف ہوں تو `--port <N>` یا `--instance <N>` استعمال کریں۔ مطابقت اور بحالی کے لیے [اپ گریڈ گائیڈ](../docs/upgrades/iii-0.25.md) دیکھیں۔
---
<h2 id="deploy">ڈیپلائی</h2>
-منظم 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 کم کر دیتا ہے۔
+Docker Compose یا نیچے دیے پلیٹ فارم ٹیمپلیٹس سے خود ہوسٹ کریں۔ میموری اور اسناد `/data` والیوم میں رہتی ہیں۔ اپ گریڈ کرتے وقت بیک اپ لیں اور یہی والیوم دوبارہ استعمال کریں۔ توثیق، نیٹ ورک اور منتقلی کے لیے [ڈیپلائمنٹ گائیڈ](../deploy/README.md) دیکھیں۔
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="fly.io پر ڈیپلائی کریں" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Railway پر ڈیپلائی کریں" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="fly.io پر ڈیپلائی کریں" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Railway پر ڈیپلائی کریں" /></a>
</p>
-Render کے ون-کلک ڈیپلائی بٹن کو repository کی root میں `render.yaml` درکار ہے، جسے ہم جانستہ طور پر صاف رکھتے ہیں۔ in-repo blueprint کی طرف دستی طور پر اشارہ کرنے کے لیے [`deploy/render/`](.././deploy/render/README.md) میں دستاویزی Render Blueprint فلو استعمال کریں۔
+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) میں موجود ہیں:
+مکمل سیٹ اپ تفصیلات (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 دونوں آپ کے اپنے۔
+- [`../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 پیٹرن دستاویز کرتا ہے۔
+REST پورٹ `3111` اور ویوئر `3113` استعمال کرتے ہیں۔ انہیں نجی رکھیں یا توثیق اور TLS سے محفوظ بنائیں۔ پلیٹ فارم کی رسائی کی ترتیب اور [پرانے Docker کی منتقلی](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) ڈیپلائمنٹ گائیڈ میں ہیں۔
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="agentmemory کیوں" height="32" /></picture></h2>
-ہر کوڈنگ ایجنٹ سیشن ختم ہوتے ہی سب کچھ بھول جاتا ہے، اور ہر نیا سیشن آپ کے دوبارہ اپنا stack بیان کرنے سے شروع ہوتا ہے۔ agentmemory پسِ منظر میں چلتا ہے اور یہ قدم ختم کر دیتا ہے۔
+منصوبے کی معلومات گفتگو اور ہدایات کی فائلوں میں بکھر جاتی ہیں۔ 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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### بلٹ-اِن ایجنٹ میموری کے مقابلے میں
@@ -971,7 +928,7 @@ Session 2: "Now add rate limiting"
| | بلٹ-اِن (CLAUDE.md) | agentmemory |
|---|---|---|
-| اسکیل | 200-لائن کی حد | لامحدود |
+| دیکھ بھال | ہاتھ سے ترتیب دی گئی ہدایات | انڈیکس شدہ سیشن کی تاریخ اور میموری |
| سرچ | سب کچھ context میں لوڈ کرتا ہے | BM25 + ویکٹر + گراف (صرف top-K) |
| ٹوکن لاگت | 240 observations پر 22K+ | ~1,900 ٹوکنز (92% کم) |
| کراس-ایجنٹ | فی-ایجنٹ فائلیں | MCP + REST (کوئی بھی ایجنٹ) |
@@ -997,13 +954,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4-درجاتی میموری استحکام (Consolidation)
@@ -1021,6 +978,8 @@ SessionStart hook fires
### کیا کیپچر ہوتا ہے
+نیچے کی جدول Claude Code کے hooks دکھاتی ہے۔ دوسرے انضمام اپنے ہوسٹ کے دستیاب واقعات ریکارڈ کرتے ہیں۔ مشترکہ hooks میں خودکار سیاق شامل کرنے کے لیے `AGENTMEMORY_INJECT_CONTEXT=true` واضح طور پر فعال کریں۔
+
| Hook | کیپچر کرتا ہے |
|------|----------|
| `SessionStart` | Project path، session ID |
@@ -1037,7 +996,7 @@ SessionStart hook fires
| Capability | تفصیل |
|---|---|
-| **خودکار کیپچر** | ہر tool use ہکس کے ذریعے ریکارڈ ہوتا ہے، کوئی دستی کام نہیں |
+| **خودکار کیپچر** | مقامی انضمام معاون سیشن اور ٹول واقعات ریکارڈ کرتے ہیں |
| **سیمینٹک سرچ** | RRF فیوژن کے ساتھ BM25 + ویکٹر + نالج گراف |
| **میموری ارتقا** | Versioning، سپرسیشن، تعلقات کے گراف (relationship graphs) |
| **ریکال hygiene** | سپرسیڈ شدہ میموری ورژنز سرچ indexes سے نکل جاتے ہیں؛ KV میں version chain مکمل ہسٹری رکھتی ہے |
@@ -1255,186 +1214,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii کنسول" height="32" /></picture></h2>
-
-`: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 کرنے کے لیے کچھ نہیں۔
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console کا Workers صفحہ: جڑے ہوئے workers بشمول agentmemory instances، لائیو function counts اور runtime metadata کے ساتھ" width="720" />
- <br/>
- <em>Workers صفحہ: ہر جڑا ہوا worker، بشمول agentmemory خود، PID، function count، runtime، اور last-seen کے ساتھ۔</em>
-</p>
-
-**پہلے سے انسٹال۔** کنسول 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 گراف۔ |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console کا trace waterfall view جو فی-span duration دکھاتا ہے" width="720" />
- <br/>
- <em>Traces: ہر میموری operation کے لیے waterfall / flame / service breakdown۔</em>
-</p>
-
-**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 رکھیں اور کبھی اسے عوامی طور پر ظاہر نہ کریں۔
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="iii سے تقویت یافتہ" height="32" /></picture></h2>
-
-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:<scope>`، `stream:<name>:<group>`) 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 <name>` |
-
-**250 سورس فائلز · ~55,000 لائنز کوڈ · 3,800+ ٹیسٹس · 324 فنکشنز · 67 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="کنفیگریشن" height="32" /></picture></h2>
### LLM Providers
@@ -1452,6 +1231,8 @@ agentmemory آپ کے ماحول سے providers کو خودکار طور پر de
| **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=<your 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 کا سبب بنتا تھا، لہٰذا یہ اب ڈیفالٹ نہیں ہے۔ |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### مقامی ماڈلز (Ollama / LM Studio / vLLM)
agentmemory کسی بھی OpenAI-API-compatible سرور سے بات کرتا ہے، لہٰذا جو کچھ بھی `/v1/chat/completions` ایکسپوز کرتا ہے وہ بغیر کوڈ تبدیلیوں کے کام کرتا ہے۔ کوئی ادا شدہ keys نہیں، کوئی کلاؤڈ نہیں، کوئی rate limits نہیں؛ مکمل طور پر آپ کے اپنے hardware پر چلتا ہے۔
@@ -1501,24 +1282,9 @@ Reasoning-class ماڈلز (`<think>` بلاکس کے ساتھ `o1`-طرز) خا
### لاگت سے آگاہ ماڈل انتخاب
-جب 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 ماڈلز ان کوئریز کے لیے بچائیں جو آپ خود براہِ راست پڑھتے ہیں۔
+بغیر کلید کے capture اور لفظی تلاش سے شروع کریں۔ `EMBEDDING_PROVIDER=local` پہلے ماڈل ڈاؤن لوڈ کے بعد آلے پر معنوی تلاش فراہم کرتا ہے۔ LLM کمپریشن میں فراہم کنندہ اور `AGENTMEMORY_AUTO_COMPRESS=true` ضروری ہیں؛ ہر مشاہدے پر درخواست ہو سکتی ہے، اس لیے موجودہ قیمت دیکھیں۔
-ذرائع: [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/)۔
+`agentmemory status` / http://localhost:3113
### ملٹی-ایجنٹ میموری (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1546,41 +1312,22 @@ SDK / REST سطح پر فی-call override: ہر mutating endpoint (`/session/sta
### پورٹس
-agentmemory + iii-engine ڈیفالٹ کے طور پر چار پورٹس سے bind ہوتے ہیں۔ اگر ریسٹارٹ `port in use` کے ساتھ ناکام ہو، تو یہ ٹیبل بتاتا ہے کہ کون سا process تلاش کرنا ہے۔
+API اور ویوئر بطور طے شدہ loopback استعمال کرتے ہیں۔
-| پورٹ | 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 <N>` 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 فائل بھی وہی کرتی ہے۔
+| Port | API / ویوئر | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | ویوئر | `III_VIEWER_PORT` |
-جب کسی crashed رن کے بعد ports bound رہ جائیں تو stale-process cleanup:
+`--port <N>` API پورٹ مقرر کرتا ہے؛ ویوئر بطور طے شدہ `N+2` استعمال کرتا ہے۔ الگ انسٹینس کے لیے `--instance N` استعمال کریں۔ اندرونی listeners نجی رکھیں۔ دور سے رسائی اور [پرانے Docker کی منتقلی](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) کے لیے ڈیپلائمنٹ گائیڈ دیکھیں۔
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### اسٹوریج backend: file (ڈیفالٹ) بمقابلہ redis
-`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 پیچھے نہ رہا ہو۔
+الگ ڈیٹابیس سروس درکار نہیں. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. بیک اینڈ بدلنے سے موجودہ میموری خود بخود نقل نہیں ہوتی۔ [ڈیٹا اسٹوریج](../docs/reliability/state-storage.md).
### کنفیگ فائل
-ہر shell میں variables export کرنے کے بجائے agentmemory رن ٹائم کنفیگریشن `~/.agentmemory/.env` میں رکھیں۔ اگر ویور `export ANTHROPIC_API_KEY=...` جیسا کوئی سیٹ اپ اشارہ دکھاتا ہے، تو اسے `export` prefix کے بغیر `ANTHROPIC_API_KEY=...` کے طور پر اس فائل میں کاپی کریں، پھر agentmemory ریسٹارٹ کریں۔
-
-Process ماحولیاتی variables بدستور کام کرتے ہیں اور فائل کی قدروں پر فوقیت رکھتے ہیں۔
-
-Windows پر، وہی فائل `%USERPROFILE%\.agentmemory\.env` پر موجود ہے:
+ہر shell میں variables export کرنے کے بجائے runtime config کو `~/.agentmemory/.env` میں رکھیں۔ دوسری env-file کے لیے `AGENTMEMORY_ENV_FILE` مقرر کریں۔ Process environment variables فائل پر فوقیت رکھتے ہیں۔ CLI کا Worker Compose Redis settings کو `state` worker تک پہنچاتا ہے۔
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1605,179 +1352,34 @@ GRAPH_EXTRACTION_ENABLED=true
### ماحولیاتی Variables
-`~/.agentmemory/.env` بنائیں:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+مکمل ترتیب [`.env.example`](../.env.example) میں ہے، بشمول فراہم کنندہ، capture filters، مدتِ تحفظ، اسٹوریج اور ٹیم کا دائرہ۔ `AGENTMEMORY_ENV_FILE` سے دوسری فائل منتخب کریں۔ تبدیلی کے بعد دوبارہ آغاز کریں۔ حقیقی اقدار والی `.env` یا Bearer راز commit نہ کریں۔
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-پورٹ `3111` پر 143 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer <secret>` درکار ہے، اور mesh sync اینڈ پوائنٹس کو دونوں peers پر واضح طور پر سیٹ کیا گیا `AGENTMEMORY_SECRET` درکار ہے۔
+پورٹ `3111` پر 146 اینڈ پوائنٹس۔ REST API ڈیفالٹ کے طور پر `127.0.0.1` سے bind ہوتا ہے۔ محفوظ اینڈ پوائنٹس کو `Authorization: Bearer <secret>` درکار ہے، اور 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 کو دستی طور پر کال کرنے کے لیے:
+توثیق بطور طے شدہ فعال ہے۔ `AGENTMEMORY_SECRET` مقرر نہ ہو تو CLI پہلی بار بے ترتیب راز `~/.agentmemory/secret` میں محفوظ کرتا ہے اور منتخب ڈیٹا ڈائریکٹری کے `secret` میں اس کی نقل رکھتا ہے؛ اجازت `0600` ہوتی ہے۔ ساتھ آنے والے کلائنٹس مقامی رابطے میں اس اصل فائل کو ترجیح دیتے ہیں اور محفوظ راز صرف loopback URL کو بھیجتے ہیں۔ واضح `AGENTMEMORY_SECRET` مقدم ہے؛ دور کے کلائنٹس اسے environment میں مقرر کریں۔ Docker اپنا راز بناتا ہے۔
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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 بھی قبول کرتا ہے۔
@@ -1813,7 +1415,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | ٹیم کے ساتھ شیئر کریں |
| `GET` | `/agentmemory/audit` | Audit trail |
-مکمل اینڈ پوائنٹ فہرست: [`src/triggers/api.ts`](../src/triggers/api.ts)
+مکمل اینڈ پوائنٹ فہرست: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1831,19 +1433,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
جب سرور بند ہو، وقت پر جواب نہ دے یا 5xx واپس کرے، تو hook observation کو ایک مقامی spool فائل میں شامل کرتا ہے، `<data dir>/capture-spool/<host>-<port>.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` سیٹ کریں۔
+**Graph Provenance کو Compact کرنا۔** پرانے provenance کی compaction اسٹارٹ اپ پر مؤخر رہتی ہے کیونکہ یہ پرانے scopes کو مکمل پڑھتی ہے۔ `/agentmemory/status` میں `deferred`، یا `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` ہونے پر `off` دکھائی دیتا ہے۔ نیچے دی گئی دستی compaction دیکھ بھال کے دوران چلائیں۔ Retrieval index کی migration الگ ہے: [دیکھ بھال کی گائیڈ](../docs/reliability/graph-index-migration.md) کے مطابق `agentmemory graph-index migrate --allow-legacy-scan` استعمال کریں۔
اسے دستی طور پر چلانے کے لیے، `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1857,7 +1459,7 @@ npm test # 4,000+ 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 استعمال کرتا ہے۔
+ضروریات [تنصیب](#install) اور تعاون و ریلیز کی جانچ [CONTRIBUTING.md](../CONTRIBUTING.md) میں ہیں۔
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="لائسنس" height="32" /></picture></h2>
diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.md
index 96ded8ee..81de67dd 100644
--- a/READMEs/README.vi-VN.md
+++ b/READMEs/README.vi-VN.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- 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 <a href="https://github.com/iii-hq/iii">iii engine</a>
+ Bộ nhớ bền vững xuyên suốt các phiên lập trình và agent.
</strong><br/>
- 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.
+ Bộ nhớ bền vững cho Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, DeepSeek Harness, OpenCode và bất kỳ MCP client nào.
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">Cách hoạt động</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">Viewer</a> &bull;
- <a href="#powered-by-iii">Powered by iii</a> &bull;
<a href="#configuration">Cấu hình</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory ghi lại phiên lập trình để bạn tìm lại các quyết định và cách sửa lỗi. Dùng chung một kho bộ nhớ giữa các công cụ, kiểm tra nội dung đã lưu và chọn lượng ngữ cảnh đưa vào mô hình.
+
+<a id="install"></a>
+
## 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ợ.
+- Thiết lập tự động trên macOS/Linux cần `curl`, POSIX `sh` và `tar`.
+Windows native cần cài thủ công `iii.exe` của iii v0.25.0 đã pin; WSL2 dùng trình cài tự động cho macOS/Linux
Lệnh cài mới chuẩn (canonical):
@@ -108,11 +111,11 @@ Lệnh cài mới chuẩn (canonical):
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ọn agent và nhà cung cấp hoặc chế độ không cần khóa. Thiết lập lưu cấu hình, khởi động máy chủ bộ nhớ và đề nghị cài đặt toàn cục. `-y` chấp nhận xác nhận npm; `@latest` chọn bản mới nhất. Nén bằng LLM cần cả nhà cung cấp và `AGENTMEMORY_AUTO_COMPRESS=true`.
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 <path>` 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.
+API ở `http://localhost:3111`, trình xem trực tiếp ở `http://localhost:3113`. Cả hai mặc định chỉ lắng nghe trên loopback. Cấu hình nằm trong `~/.agentmemory/.env`. [Lưu trữ dữ liệu](#data-storage).
Sau đó hãy xác nhận recall hoạt động và trang bị skill cho agent của bạn:
@@ -127,14 +130,7 @@ Muốn để một coding agent tự làm hết mọi việc? Hãy đưa cho nó
> 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 <agent>` — 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).
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-Đườ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.
-
-</details>
+Thêm agent bằng `agentmemory connect <agent>`. Xem [các tích hợp](#works-with-every-agent) và [lệnh thường dùng](#everyday-commands).
<details>
<summary><strong>Cài đặt toàn cục / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx cache theo từng phiên bản. Buộc dùng bản mới nhất với `npx -
</details>
-<details>
-<summary><strong>Đã chạy sẵn iii engine riêng của bạn</strong></summary>
-
-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.
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Hoạt động với mọi agent" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, ho
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>native plugin + 7 hooks + MCP</sub>
+<sub>plugin native + hook vòng đời + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, ho
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>native plugin + MCP</sub>
+<sub>recall native + capture + skill</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, ho
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP server</sub>
+<sub>capture native + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, ho
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>recall native + capture + skill + MCP tùy chọn</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ agentmemory hoạt động với bất kỳ agent nào hỗ trợ hooks, MCP, ho
---
-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.
+<a id="data-storage"></a>
-**Đ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.
+### Lưu trữ dữ liệu
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+Bộ nhớ mặc định nằm ngoài kho mã. Instance 0 dùng lại `./data/state_store.db` có sẵn. Chọn thư mục bằng `--data-dir <path>` hoặc `AGENTMEMORY_DATA_DIR` và giữ nguyên khi khởi động lại hay nâng cấp.
-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 <path>` 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:
+| Nền tảng | Thư mục dữ liệu |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-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`.
+`--instance 1` dùng thư mục con `instance-1`, cổng API `3211` và trình xem `3213`. Xem [lưu trữ và sao lưu](../docs/reliability/state-storage.md) để dùng Redis hoặc chuyển backend.
Ghi chú phát hành mới nhất: [CHANGELOG.md](../CHANGELOG.md).
@@ -476,7 +473,7 @@ Tỷ lệ hit top-5 đạt 100% tại **ngưỡng toán học P@5** cho corpus n
</tr>
<tr>
<td><strong>Dependency bên ngoài</strong></td>
-<td>Không (SQLite + iii-engine)</td>
+<td>Không cần dịch vụ cơ sở dữ liệu riêng</td>
<td>Qdrant / pgvector</td>
<td>Postgres + vector DB</td>
<td>Nhiều</td>
@@ -550,14 +547,12 @@ Tỷ lệ hit top-5 đạt 100% tại **ngưỡng toán học P@5** cho corpus 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.
+AgentMemory kết hợp ghi nhận phiên, lịch sử dự án có thể tìm kiếm và trình xem cục bộ, với chế độ không cần khóa ngay từ lần đầu.
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Bắt đầu nhanh" height="32" /></picture></h2>
-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
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
Mở `http://localhost:3113` để xem bộ nhớ được xây dựng theo thời gian thực.
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 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:
+Khi máy chủ đang chạy, kiểm tra sức khỏe, trình xem và trạng thái.
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ 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:
+`status` hiển thị sức khỏe máy chủ, nhà cung cấp, chế độ embedding, chuyển giao capture và phục hồi. REST được bảo vệ cần bí mật của máy chủ. Dùng `AGENTMEMORY_SECRET` đã cấu hình hoặc đọc bí mật cục bộ được tạo nếu chưa đặt.
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
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.
+<a id="everyday-commands"></a>
+
### 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:
@@ -604,7 +608,10 @@ Cài đặt và thiết lập nằm ở phần [Cài đặt](#install) ở trên
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-jsonl
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.
+Phiên nhập hiện cùng phiên native trong Replay, được lập chỉ mục tìm kiếm và đánh dấu kênh nguồn `import`. Xử lý phiên cũng có thể tạo crystal và bài học.
> **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.
@@ -635,14 +642,12 @@ Dùng lệnh bảo trì khi bạn chủ động muốn cập nhật runtime cụ
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`).
+Lệnh cập nhật runtime cục bộ và có thể cập nhật phụ thuộc JavaScript trong thư mục làm việc. Sao lưu dữ liệu và đọc [hướng dẫn nâng cấp](../docs/upgrades/iii-0.25.md) trước khi cập nhật bản cài hiện có.
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code không cài plugin (đường MCP độc lập)
@@ -703,6 +708,26 @@ 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.
+### Cursor
+
+Cấu hình MCP bằng `agentmemory connect cursor`. Trong **Settings → Plugins → Add marketplace**, chọn checkout chứa `.cursor-plugin/plugin.json`, bật agentmemory và tải lại. Plugin cung cấp capture vòng đời, xác định workspace, skill và MCP. Chỉ bật hook của plugin hoặc hook thủ công trong `~/.cursor/hooks.json` để tránh ghi nhận trùng.
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Chọn lệnh cho host của bạn. Pi và OMP cài recall/capture native, phát lại ngoại tuyến và 17 skill; `--with-mcp` thêm toàn bộ công cụ. Chạy `/reload` trong Pi hoặc khởi động lại OMP, rồi kiểm tra `/agentmemory-status`. DSH cài MCP và plugin capture đi kèm; hãy khởi động lại sau khi kết nối.
+
+Pi cũng hỗ trợ gói `@agentmemory/pi`. Xem [hướng dẫn Pi](../integrations/pi/) về cài đặt cục bộ và tình trạng phát hành npm. Mỗi host chỉ dùng một cách cài đặt.
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw (dán prompt này)</b></summary>
@@ -749,6 +774,8 @@ Hướng dẫn đầy đủ: [`integrations/hermes/`](../integrations/hermes/)
</details>
+<a id="other-agents"></a>
+
### Các agent khác
Khởi động memory server: `npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
Điều này **bổ sung** cho `agentmemory connect <agent>`:
-- `agentmemory connect <agent>` 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.
+Connector Hermes, OpenClaw, Pi và Oh My Pi mặc định cài tích hợp native cùng skill; MCP là tùy chọn qua `--with-mcp`. Với host khác, cài skill bằng `npx skills add rohitg00/agentmemory`.
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.
@@ -790,12 +816,12 @@ Entry của agentmemory là **cùng một block MCP server** trên mọi host d
| 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. |
+| **Cursor (plugin đầy đủ)** | `.cursor-plugin/` | Cài qua Cursor Marketplace hoặc Settings → Plugins → checkout cục bộ. Adapter mỏng gọi các script chung `plugin/scripts/*.mjs` để đăng ký hook vòng đời, cùng skill và MCP. Adapter xác định workspace mà Cursor không luôn báo chính xác. Xem [Cursor](#cursor). Hoạt động trong Cursor IDE và CLI `cursor-agent`. |
| **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:<skill>` 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. |
+| **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. |
@@ -804,7 +830,8 @@ Entry của agentmemory là **cùng một block MCP server** trên mọi host d
| **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). |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · recall native + capture + skill. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · recall native + capture + skill. [Oh My Pi](../integrations/omp/) |
| **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). |
@@ -812,39 +839,19 @@ Entry của agentmemory là **cùng một block MCP server** trên mọi host d
| **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`. |
+| **Continue.dev** | `~/.continue/config.yaml` (ưu tiên) hoặc `config.json` (legacy) | `agentmemory connect continue` tạo `config.yaml` nếu chưa có cấu hình hoặc cập nhật `config.json` hiện có. YAML có sẵn được giữ nguyên để bảo toàn chú thích và anchor; lệnh in khối để dán dưới `mcpServers:`. Continue dùng dạng mảng 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 `<repo>/.factory/mcp.json`. Truyền `--with-hooks` để có auto-capture gốc. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` bật các công cụ MCP. Thêm `--with-hooks` để tải plugin ghi nhận sự kiện gốc đi kèm AgentMemory. Không cần gói plugin riêng. [DSH](../docs/dsh.md). |
| **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"}'`. |
+| **Aider** | n/a | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **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)
+### Truy cập theo chương trình
-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.
+Dùng [REST API](#api) từ bất kỳ ngôn ngữ nào hoặc [công cụ MCP](#mcp-server) từ agent. REST dùng JSON và xác thực Bearer; xem [ví dụ lưu và tìm kiếm](#validate-a-fresh-install-and-restart-persistence). Tích hợp trực tiếp với runtime có trong [ví dụ Python](../examples/python/).
### Từ source
@@ -853,121 +860,69 @@ 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=<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).
+`npm start` chạy cùng máy chủ cục bộ như CLI đã cài. Yêu cầu nằm ở [Cài đặt](#install); API và trình xem lắng nghe trên `127.0.0.1`.
### 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.
+agentmemory chạy trên Windows 10/11; WSL2 có thể tự cài engine theo quy trình Linux. Windows native cần cài thủ công iii-engine v0.25.0: tải archive từ [trang phát hành iii v0.25.0](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0), xác minh checksum và đặt `iii.exe` trong `PATH`. CLI không tự giải nén ZIP Windows
-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
-```
+Cấu hình MCP tự động trên Windows native chỉ hỗ trợ `agentmemory connect copilot-cli`; agent khác dùng khối MCP thủ công trong [Other agents](#other-agents). Chỉ chạy `connect` trong WSL nếu agent đích cũng cài trong cùng môi trường WSL
-**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:
+**Chỉ dùng MCP độc lập, không có engine.** Nếu không cần REST API, viewer hoặc dịch vụ runtime:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 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`.
+Chạy `agentmemory doctor` hoặc khởi động lại với `--verbose`. Nếu cổng mặc định đang được dùng, chọn `--port <N>` hoặc `--instance <N>`. Xem [hướng dẫn nâng cấp](../docs/upgrades/iii-0.25.md) về tương thích và phục hồi.
---
<h2 id="deploy">Triển khai</h2>
-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.
+Tự triển khai bằng Docker Compose hoặc mẫu nền tảng bên dưới. Bộ nhớ và thông tin xác thực nằm trên volume `/data`. Sao lưu và dùng lại volume khi nâng cấp. Xem [hướng dẫn triển khai](../deploy/README.md) về xác thực, mạng và di chuyển dữ liệu.
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Triển khai lên fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Triển khai lên Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Triển khai lên fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Triển khai lên Railway" /></a>
</p>
-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.
+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):
+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
+- [`../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,
+- [`../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,
+- [`../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
+- [`../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ó.
+REST dùng cổng `3111`; trình xem dùng `3113`. Giữ truy cập riêng tư hoặc bảo vệ bằng xác thực và TLS. Xem cấu hình truy cập của từng nền tảng và [chuyển từ Docker cũ](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) trong hướng dẫn triển khai.
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Tại sao chọn agentmemory" height="32" /></picture></h2>
-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 đó.
+Kiến thức dự án thường nằm rải rác trong hội thoại và tệp chỉ dẫn. AgentMemory giúp agent bạn đang dùng tìm lại các quyết định, cách sửa lỗi và bài học trước đây.
```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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### So với bộ nhớ tích hợp sẵn của agent
@@ -976,7 +931,7 @@ Mọi AI coding agent đều đi kèm bộ nhớ tích hợp sẵn: Claude Code
| | Tích hợp sẵn (CLAUDE.md) | agentmemory |
|---|---|---|
-| Quy mô | Giới hạn 200 dòng | Không giới hạn |
+| Bảo trì | Chỉ dẫn được quản lý thủ công | Lịch sử phiên và bộ nhớ đã lập chỉ mục |
| 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) |
@@ -1002,13 +957,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### Hợp nhất bộ nhớ 4 tầng
@@ -1026,6 +981,8 @@ Bộ nhớ suy giảm theo thời gian (đường cong Ebbinghaus). Bộ nhớ
### Những gì được capture
+Bảng dưới mô tả hook của Claude Code. Các tích hợp khác ghi nhận sự kiện mà host cung cấp. Chèn ngữ cảnh tự động qua hook dùng chung là tùy chọn với `AGENTMEMORY_INJECT_CONTEXT=true`.
+
| Hook | Capture gì |
|------|----------|
| `SessionStart` | Đường dẫn project, session ID |
@@ -1042,7 +999,7 @@ Bộ nhớ suy giảm theo thời gian (đường cong Ebbinghaus). Bộ 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 |
+| **Capture tự động** | Tích hợp native ghi nhận các sự kiện phiên và công cụ được hỗ trợ |
| **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ử |
@@ -1260,187 +1217,6 @@ Viewer server bind vào `127.0.0.1` theo mặc định và gắn kèm server sec
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-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.
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="Trang Workers của iii console: các worker đã kết nối bao gồm các instance agentmemory với số lượng function live và metadata runtime" width="720" />
- <br/>
- <em>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.</em>
-</p>
-
-**Đã đượ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. |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="Chế độ xem waterfall của trace trong iii console, hiển thị thời lượng theo từng span" width="720" />
- <br/>
- <em>Traces: waterfall / flame / service breakdown cho mọi memory operation.</em>
-</p>
-
-**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.
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory **đã 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:<scope>`, `stream:<name>:<group>`) 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 <name>` |
-
-**250 file source · ~55,000 LOC · 3,400+ test · 324 function · 67 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Cấu hình" height="32" /></picture></h2>
### LLM Provider
@@ -1458,6 +1234,8 @@ agentmemory tự phát hiện provider từ environment của bạn. Một provi
| **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=<your 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. |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 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.
@@ -1507,24 +1285,9 @@ Embedding cục bộ đi kèm như một dependency tùy chọn nhưng không đ
### 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.
+Bắt đầu không cần khóa để ghi nhận và tìm theo từ khóa. `EMBEDDING_PROVIDER=local` cung cấp tìm kiếm ngữ nghĩa trên máy sau lần tải mô hình đầu tiên. Nén LLM cần nhà cung cấp và `AGENTMEMORY_AUTO_COMPRESS=true`, có thể gửi yêu cầu cho từng quan sát; hãy kiểm tra giá hiện hành.
-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/).
+`agentmemory status` / http://localhost:3113
### Bộ nhớ đa agent (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1554,41 +1317,22 @@ Khi `AGENT_ID` chưa được đặt, memory vẫn không có scope (hành vi le
### 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.
+API và trình xem mặc định chỉ lắng nghe trên loopback.
-| 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 <N>` đổ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.
+| Port | API / Trình xem | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | Trình xem | `III_VIEWER_PORT` |
-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:
+`--port <N>` đặt cổng API; trình xem mặc định dùng `N+2`. Dùng `--instance N` cho instance riêng. Giữ các listener nội bộ riêng tư; xem hướng dẫn triển khai để truy cập từ xa và [chuyển từ Docker cũ](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode).
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### Storage backend: file (mặc định) so với redis
-`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.
+Không cần dịch vụ cơ sở dữ liệu riêng. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. Đổi backend không tự sao chép bộ nhớ hiện có. [Lưu trữ dữ liệu](../docs/reliability/state-storage.md).
### 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`:
+Đặt runtime config trong `~/.agentmemory/.env` thay vì export biến ở mọi shell. Dùng `AGENTMEMORY_ENV_FILE` để chọn env-file khác. Biến môi trường của process được ưu tiên hơn giá trị trong file. Worker Compose do CLI tạo truyền Redis setting tới worker `state`.
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1613,179 +1357,34 @@ GRAPH_EXTRACTION_ENABLED=true
### Biến Môi trường
-Tạo `~/.agentmemory/.env`:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+Tham chiếu đầy đủ ở [`.env.example`](../.env.example), gồm nhà cung cấp, bộ lọc capture, lưu giữ, kho lưu trữ và phạm vi nhóm. `AGENTMEMORY_ENV_FILE` chọn tệp khác. Khởi động lại sau khi thay đổi cấu hình. Không commit `.env` đã điền giá trị thật hay bí mật Bearer.
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-143 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 <secret>`, và các endpoint mesh sync cần `AGENTMEMORY_SECRET` được đặt rõ ràng trên cả hai phía.
+146 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 <secret>`, 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:
+Xác thực bật mặc định. Nếu chưa đặt `AGENTMEMORY_SECRET`, CLI tạo bí mật ngẫu nhiên lần đầu tại `~/.agentmemory/secret` và sao chép vào `secret` trong thư mục dữ liệu đã chọn, với quyền `0600`. Client đi kèm ưu tiên tệp chính này khi kết nối cục bộ và chỉ gửi bí mật đã lưu đến URL loopback. `AGENTMEMORY_SECRET` đặt tường minh luôn được ưu tiên; client từ xa phải đặt qua biến môi trường. Triển khai Docker tạo bí mật riêng.
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" 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ó.
@@ -1821,7 +1420,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `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)
+Danh sách endpoint đầy đủ: [REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1839,19 +1438,19 @@ Các event thất bại được retry mỗi `AGENTMEMORY_CAPTURE_RETRY_INTERVAL
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ộ, `<data dir>/capture-spool/<host>-<port>.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ó.
+**Compact provenance của graph.** Việc compact provenance cũ được hoãn khi khởi động vì phải đọc toàn bộ các scope cũ. `/agentmemory/status` báo `deferred`, hoặc `off` khi đặt `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. Chạy compact thủ công bên dưới trong thời gian bảo trì. Di chuyển chỉ mục truy xuất là thao tác riêng: dùng `agentmemory graph-index migrate --allow-legacy-scan` theo [hướng dẫn bảo trì](../docs/reliability/graph-index-migration.md).
Để 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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1865,7 +1464,7 @@ npm test # 4,000+ 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.
+Xem [Cài đặt](#install) về yêu cầu và [CONTRIBUTING.md](../CONTRIBUTING.md) về quy tắc đóng góp cùng kiểm tra phát hành.
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="Giấy phép" height="32" /></picture></h2>
diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md
index 720a935f..11ac5a0c 100644
--- a/READMEs/README.zh-CN.md
+++ b/READMEs/README.zh-CN.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- 让你的编码代理记住一切。不再重复解释。
- 基于 <a href="https://github.com/iii-hq/iii">iii engine</a> 构建
+ 跨编码会话和代理的持久记忆。
</strong><br/>
- 为 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode 以及任何 MCP 客户端提供持久化记忆。
+ 为 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、Oh My Pi、DeepSeek Harness、OpenCode 以及任何 MCP 客户端提供持久化记忆。
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="许可证" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Star 数" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,23 @@
<a href="#how-it-works">工作原理</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">查看器</a> &bull;
- <a href="#powered-by-iii">由 iii 驱动</a> &bull;
<a href="#configuration">配置</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory 记录编码会话,让过去的决策和修复可供搜索与召回。多个工具共享同一份记忆,你可以检查保存的内容,并决定向模型提供多少上下文。
+
+<a id="install"></a>
+
## 安装
环境要求:
- 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。
+- macOS/Linux 的自动设置需要 `curl`、POSIX `sh` 和 `tar`。
+- Windows / WSL2: [Windows](#windows).
标准的全新安装命令:
@@ -108,11 +111,11 @@
npx -y @agentmemory/agentmemory@latest
```
-首次运行是一次交互式设置:选择要接入的代理(Claude Code、Cursor、Codex、Gemini CLI、OpenCode……),选择一个 LLM 提供者或保持无密钥模式;随后它会生成配置、启动记忆服务器及其锚定的 iii 引擎,并询问是否要全局安装,这样之后在任何地方都能直接使用 `agentmemory` 命令。`-y` 用于接受 npx 的包安装提示,`@latest` 用于避免使用过期的缓存版本。配置好提供者后,LLM 相关功能才可用,但只有同时设置了 `AGENTMEMORY_AUTO_COMPRESS=true`,LLM 撰写的观测压缩才会启动。
+选择代理和提供者,或使用无密钥模式。设置程序保存配置、启动记忆服务器,并提供全局安装选项。`-y` 接受 npm 确认,`@latest` 选择最新版本。LLM 压缩需要同时配置提供者和 `AGENTMEMORY_AUTO_COMPRESS=true`。
无密钥模式会关闭向量嵌入。`memory_recall`(即 `mem::search` 路径)使用 BM25,而当图数据已经存在时,`memory_smart_search` 还可以融合结构化的图匹配结果。要免费启用本地设备上的语义召回,在 `~/.agentmemory/.env` 中设置 `EMBEDDING_PROVIDER=local` 并重启。首次嵌入请求会下载 `Xenova/all-MiniLM-L6-v2`;完成这次初始模型下载后,推理就会在本地运行。
-本地运行时使用四个端口:`3111` 用于 REST/MCP HTTP,`3112` 用于 iii 流,`3113` 用于查看器,`49134` 用于 iii worker 的 WebSocket。持久化的 iii 状态保存位置为:macOS 上的 `~/Library/Application Support/agentmemory`,Linux 上的 `$XDG_DATA_HOME/agentmemory` 或 `~/.local/share/agentmemory`,以及 Windows 上的 `%APPDATA%\agentmemory`。使用 `--data-dir <path>` 或 `AGENTMEMORY_DATA_DIR` 来覆盖这个位置,并在之后每次重启时复用同一个值。出于向后兼容考虑,对于实例 0,已存在的 `./data/state_store.db` 或 `./data/iii-config.yaml` 会优先于平台默认路径;显式的命令行参数或环境变量覆盖始终优先级最高。
+API 位于 `http://localhost:3111`,实时查看器位于 `http://localhost:3113`,默认都只监听回环地址。配置保存在 `~/.agentmemory/.env`。 [数据存储](#data-storage).
然后验证召回是否生效,并为你的代理装上它的 skills:
@@ -127,14 +130,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-随时可以用 `agentmemory connect <agent>` 接入更多代理 —— [适用于所有代理](#works-with-every-agent) 中列出了 20 个适配器。完整命令参考见 [快速开始](#quick-start)。
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-最省心的路径是 WSL2。原生 Windows 引擎设置需要手动下载锚定版本 v0.22.1 的 ZIP 并解压出 `iii.exe`;CLI 不会自动解压它。也支持 Docker Desktop。具体步骤见 [Windows 说明](#windows)。
-
-</details>
+使用 `agentmemory connect <agent>` 连接更多代理。参见[支持的集成](#works-with-every-agent)和[日常命令](#everyday-commands)。
<details>
<summary><strong>全局安装 / EACCES</strong></summary>
@@ -154,13 +150,6 @@ npx 按版本缓存。用 `npx -y @agentmemory/agentmemory@latest` 强制使用
</details>
-<details>
-<summary><strong>已经在运行自己的 iii 引擎</strong></summary>
-
-agentmemory 锚定 iii-engine v0.22.1,不会连接到其他版本(worker 无法说另一个引擎版本的协议)。先停掉那个引擎,再运行 `npx -y @agentmemory/agentmemory@latest`。它会在 `~/.agentmemory/bin` 中安装并运行锚定的 v0.22.1 版本,不会动你自己的 `iii`。
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="适用于所有代理" height="32" /></picture></h2>
@@ -187,7 +176,7 @@ agentmemory 适用于任何支持 hooks、MCP 或 REST API 的代理。所有代
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>原生插件 + 7 hooks + MCP</sub>
+<sub>原生插件 + 生命周期 hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +203,7 @@ agentmemory 适用于任何支持 hooks、MCP 或 REST API 的代理。所有代
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>原生插件 + MCP</sub>
+<sub>原生召回 + 捕获 + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +269,7 @@ agentmemory 适用于任何支持 hooks、MCP 或 REST API 的代理。所有代
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP 服务器</sub>
+<sub>原生捕获 + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +292,12 @@ agentmemory 适用于任何支持 hooks、MCP 或 REST API 的代理。所有代
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>原生召回 + 捕获 + skills + 可选 MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +306,24 @@ agentmemory 适用于任何支持 hooks、MCP 或 REST API 的代理。所有代
---
-你在每次会话中都要重新解释同样的架构。你反复发现同样的 bug。你反复教会它同样的偏好。内建记忆(CLAUDE.md、.cursorrules)上限是 200 行,而且会过时。agentmemory 解决了这个问题。它会静默捕获代理所做的一切,将其压缩为可搜索的记忆,并在下一次会话开始时注入正确的上下文。一条命令。跨代理生效。
+<a id="data-storage"></a>
-**改变了什么:** 会话 1 你搭建了 JWT 鉴权。会话 2 你要求加上限流。代理已经知道你的鉴权使用了 `src/middleware/auth.ts` 中的 jose 中间件,测试覆盖了 token 校验,并且你为了 Edge 兼容性选择了 jose 而非 jsonwebtoken —— 不需要重新解释,也不需要复制粘贴。
+### 数据存储
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+记忆默认保存在仓库之外。实例 0 会复用已有的 `./data/state_store.db`。使用 `--data-dir <path>` 或 `AGENTMEMORY_DATA_DIR` 更改目录,重启和升级时保持同一目录。
-默认情况下,agentmemory 会把 iii-engine 状态存储在启动它的仓库之外:macOS 上的 `~/Library/Application Support/agentmemory`,Linux 上的 `$XDG_DATA_HOME/agentmemory` 或 `~/.local/share/agentmemory`,以及 Windows 上的 `%APPDATA%\agentmemory`。对于实例 0,已存在的旧版 `./data/state_store.db` 或 `./data/iii-config.yaml` 会在平台默认路径之前被复用。要显式选择一个位置,传入 `--data-dir <path>` 或设置 `AGENTMEMORY_DATA_DIR`;这两种显式设置都优先于旧版探测逻辑:
+| 平台 | 数据目录 |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-原生启动和 Docker 启动使用的是同一个解析得到的主机目录;Docker 会把它绑定挂载到 `/data`。`--instance 1` 会在解析出的目录后追加 `instance-1`,并选用单独的默认端口四元组 `3211/3212/3213/49234`。
+`--instance 1` 使用 `instance-1` 子目录、API 端口 `3211` 和查看器端口 `3213`。Redis 和后端迁移请参见[存储与备份](../docs/reliability/state-storage.md)。
最新发布说明见:[CHANGELOG.md](../CHANGELOG.md)。
@@ -476,7 +473,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>外部依赖</strong></td>
-<td>无(SQLite + iii-engine)</td>
+<td>无需独立数据库服务</td>
<td>Qdrant / pgvector</td>
<td>Postgres + 向量数据库</td>
<td>多个</td>
@@ -550,14 +547,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | 时间性知识图谱;已公布的时间性查询结果最强(LongMemEval 63.8%),但图谱是异步构建的,新事实可能滞后 |
| Cognee | 30K | 文档到知识图谱的摄取,仅 Python,为结构化实体抽取而建,而非会话捕获 |
-它们都不能从编码代理的 hooks 自动捕获、不提供本地优先的查看器、也不能无密钥运行 —— 而这正是 agentmemory 围绕构建的组合。
+AgentMemory 结合会话捕获、可搜索的项目历史和本地查看器,首次使用即可选择无密钥模式。
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="快速开始" height="32" /></picture></h2>
-兼容性:此版本面向 `iii-sdk` 0.22.1,并锚定 iii-engine v0.22.1。
-
### 30 秒体验
```bash
@@ -572,9 +567,11 @@ npx -y @agentmemory/agentmemory@latest demo
打开 `http://localhost:3113` 实时观察记忆的构建过程。
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 验证全新安装与重启持久化
-服务器运行时,验证 REST、健康检查、查看器以及由 iii 支撑的运行时状态:
+保持服务器运行,检查健康状态、查看器和运行状态。
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +580,27 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-启动完成面板会覆盖全部四个端口:3111 上的 REST/MCP HTTP,3112 上的 iii 流,3113 上的查看器,以及 49134 上的 iii worker WebSocket。`status` 会确认 agentmemory 的健康状况以及当前激活的提供者/嵌入模式。保存一条探测记录并确认它可被搜索到:
+`status` 显示服务器健康、提供者、嵌入模式、捕获交付和恢复状态。受保护的 REST 请求需要服务器密钥。使用已配置的 `AGENTMEMORY_SECRET`;若未配置,则读取生成的本地密钥。
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
然后运行 `npx -y @agentmemory/agentmemory@latest stop`,在终端 1 中再次运行标准命令启动,等待 `/agentmemory/livez` 就绪,再重复一次搜索。这条探测记录必须仍然能被返回。如果你选择了自定义的 `--data-dir`,重启时要传入同一个目录。
+<a id="everyday-commands"></a>
+
### 日常命令
安装与设置见上方的 [安装](#install)(首次运行会引导你完成)。日常使用:
@@ -604,7 +608,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +630,7 @@ npx -y @agentmemory/agentmemory@latest import-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 函数来处理,没有旁路服务器。每个导入的会话记录都会被编入搜索索引,打上来源渠道 `import` 的标记,并被挖掘出会话 crystal 和经验教训。
+导入会话与原生会话一起显示在 Replay 中,并建立搜索索引、标记来源渠道 `import`。会话处理也可能生成 crystal 和经验教训。
> **提醒:如果你把 `import-jsonl` 当作主要的捕获路径:** Claude Code 的 `cleanupPeriodDays`(在 `~/.claude/settings.json` 中,默认 **30**)会自动删除 `~/.claude/projects/` 中超出这个时间窗口的 JSONL 会话记录。如果你是在一个积累了数月历史的 Claude Code 上全新安装 agentmemory,那么超过 30 天的记录在第一次导入之前就已经消失了。要么用 cron 定期运行 `import-jsonl`,要么把 `cleanupPeriodDays` 调高,要么接入自动捕获 hooks(默认的插件安装路径),这样每一轮对话在会话进行中就会进入 agentmemory,JSONL 的清理也就不再重要。
@@ -635,14 +642,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-警告:这个命令会改动当前的工作区/运行时。它可能更新 JavaScript 依赖,并拉取锚定的 `iiidev/iii:0.22.1` Docker 镜像。它绝不会安装未锚定或更新的 iii 引擎。
-
-具体实现见 `src/cli.ts`(参见 `runUpgrade`,大致在 `src/cli.ts:544-595` 区域)。
+这会更新本地运行时,也可能更新当前工作目录中的 JavaScript 依赖。请备份数据,并在更新已有安装前阅读[升级指南](../docs/upgrades/iii-0.25.md)。
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code 不使用插件安装(MCP 独立路径)
@@ -703,6 +708,26 @@ 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 环境中时,WSL 下的 `connect` 才受支持。Copilot 会在下次启动或执行 `/mcp` 后拾取这个 MCP 服务器。如果你想要完整的 hook/skill 体验,还需要安装插件。
+### Cursor
+
+使用 `agentmemory connect cursor` 配置 MCP。在 **Settings → Plugins → Add marketplace** 选择包含 `.cursor-plugin/plugin.json` 的检出目录,启用 agentmemory 并重新加载。插件提供生命周期捕获、工作区归属、skills 和 MCP。插件 hooks 与 `~/.cursor/hooks.json` 中的手动 hooks 只启用一种,避免重复捕获。
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+选择对应宿主的命令。Pi 和 OMP 安装原生召回、捕获、离线重放和 17 个 skills,`--with-mcp` 增加完整工具集。在 Pi 中运行 `/reload`,或重启 OMP,然后检查 `/agentmemory-status`。DSH 安装 MCP 和内置捕获插件,连接后请重启。
+
+Pi 也提供可安装的 `@agentmemory/pi` 包。本地安装与 npm 可用状态见 [Pi 指南](../integrations/pi/)。每个宿主只使用一种安装方式。
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw(粘贴这段提示词)</b></summary>
@@ -749,6 +774,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### 其他代理
启动记忆服务器:`npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +792,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
这与 `agentmemory connect <agent>` 是**互补**的:
-- `agentmemory connect <agent>` 写入 MCP 服务器配置,让工具可用。
-- `npx skills add rohitg00/agentmemory` 安装 skills,让代理知道何时调用它们。
+Hermes、OpenClaw、Pi 和 Oh My Pi 的连接器默认安装原生集成和 skills;MCP 通过 `--with-mcp` 选装。其他宿主可用 `npx skills add rohitg00/agentmemory` 安装 skills。
对于 skills CLI 尚未覆盖的少数代理(Zed v1.3.x 及更低版本),自己把 17 个 SKILL.md 文件放到代理的原生 skill 目录下即可;同样的格式在各处都适用。
@@ -790,12 +816,12 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| 代理 | 配置文件 | 说明 |
|---|---|---|
| **Cursor(仅 MCP)** | `~/.cursor/mcp.json` | 合并进 `mcpServers`,或使用 `agentmemory connect cursor`。官网上也提供一键深链接。 |
-| **Cursor(完整插件)** | `.cursor-plugin/` | Cursor Marketplace 列表(提交审核中)或 Cursor Settings → Plugins → 本地 checkout。注册 7 个自动捕获 hooks(sessionStart、beforeSubmitPrompt、preToolUse、postToolUse、postToolUseFailure、stop、sessionEnd)+ 17 个 skills + MCP 服务器,`AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` 在 Cursor 的插件面板中管理。适用于 Cursor IDE 和 `cursor-agent` CLI;CLI 的 print 模式提示词会在会话结束时从会话记录回填。 |
+| **Cursor(完整插件)** | `.cursor-plugin/` | 通过 Cursor Marketplace 或 Settings → Plugins → 本地检出安装。轻量适配器调用共享的 `plugin/scripts/*.mjs` 注册生命周期 hooks,并提供 skills 和 MCP。适配器解析 Cursor 未可靠报告的工作区。参见 [Cursor](#cursor)。适用于 Cursor IDE 和 `cursor-agent` 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 + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` 会合并 MCP 条目;`--with-hooks` 会添加六个原生自动捕获 hooks(SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd),并使用 Devin 的小写工具匹配器。用 `devin mcp list` 以及 devin 内部的 `/hooks` 验证。 |
| **Devin CLI(完整插件)** | `plugin/.devin-plugin/` | 在 checkout 中运行 `devin plugins install ./plugin`,会把全部 17 个 skills 注册为 `/agentmemory:<skill>` 斜杠命令,并加上 MCP 服务器。Devin 的插件 hooks 无法触发 `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 个工具都出现了。 |
+| **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 子目录的插件。 |
@@ -804,7 +830,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **Codex CLI(完整插件)** | Codex 插件市场 | 先 `codex plugin marketplace add rohitg00/agentmemory`,再 `codex plugin add agentmemory@agentmemory`。会注册 MCP + 6 个生命周期 hooks + 17 个 skills。请在你的宿主上信任 hooks 并验证捕获是否生效;参见[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 个自动捕获 hooks,覆盖会话生命周期、消息、工具、错误。项目归属是按会话计算的,所以一个跨越多个仓库的 OpenCode 进程会把每个会话归档到各自的项目下。两个斜杠命令(`/recall`、`/remember`)。把 `plugin/opencode/` 复制到你的 OpenCode 工作区,并把插件条目添加进 `opencode.json`。完整的 hook 表 + 差距分析见 [`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 包(在 checkout 中运行 `pi install ./integrations/pi`)。 |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · 原生召回 + 捕获 + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · 原生召回 + 捕获 + skills. [Oh My Pi](../integrations/omp/) |
| **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 IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` 会在共享的自定义目录中安装 MCP 和捕获 hooks。参见[Antigravity 设置与限制](../docs/plugins/antigravity.md)。 |
@@ -812,39 +839,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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` 用的是数组形式(不是对象)。 |
+| **Continue.dev** | `~/.continue/config.yaml`(优先)或 `config.json`(旧版) | `agentmemory connect continue` 在没有配置时创建 `config.yaml`,或更新现有 `config.json`。已有 YAML 会保留不动,以保护注释和锚点;命令打印应粘贴到 `mcpServers:` 下的配置块。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` 代码块。项目级覆盖放在 `<repo>/.factory/mcp.json` 中。传入 `--with-hooks` 启用原生自动捕获。 |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` 启用 MCP 工具。添加 `--with-hooks` 可加载 AgentMemory 内置的原生捕获插件,无需额外的插件包。 [DSH](../docs/dsh.md). |
| **Goose** | Goose MCP 设置界面 | 同样的 `mcpServers` 代码块;使用 `goose configure` → Add Extension → MCP。也支持直接编辑 `~/.config/goose/config.yaml`,但其 schema 用的是 `extensions:` + `cmd`(不是 `mcpServers:` + `command`)。 |
-| **Aider** | 不适用 | 直接调用 REST API:`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
+| **Aider** | 不适用 | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **任意代理(32+)** | 不适用 | `npx skillkit install agentmemory` 会自动检测宿主并合并配置。 |
**沙箱化的 MCP 客户端**(Flatpak / Snap / 限制性容器)如果无法访问宿主的 `localhost`:也在 `env` 代码块中设置 `"AGENTMEMORY_FORCE_PROXY": "1"`,并把 `AGENTMEMORY_URL` 指向沙箱真正能访问到的地址(例如你的局域网 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 仍然可用。
+任意语言均可使用 [REST API](#api),代理可使用 [MCP 工具](#mcp-server)。REST 使用 JSON 和 Bearer 认证,参见[保存与搜索示例](#validate-a-fresh-install-and-restart-persistence)。直接连接运行时的示例见 [Python 指南](../examples/python/)。
### 从源码构建
@@ -853,128 +860,70 @@ 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` 是同一个发行版;worker 说的是该引擎版本的通信协议,而 0.20.0 重组了 SDK 的接口面,所以这两者在 agentmemory 的发行版中要一起移动。如果你运行自己的引擎并确认它匹配,可以用 `AGENTMEMORY_III_VERSION=<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)。
+`npm start` 启动与已安装 CLI 相同的本地服务器。[安装](#install)列出了依赖;API 和查看器监听 `127.0.0.1`。
### Windows
-agentmemory 可以在 Windows 10/11 上运行,但光有 Node.js 包是不够的;你还需要让锚定的 iii-engine v0.22.1 运行时作为后台进程运行。CLI 不会自动解压 Windows 的 ZIP,所以原生 Windows 用户必须手动安装 `iii.exe`,或者使用 WSL2,或者选择 Docker Desktop。
+agentmemory 支持 Windows 10/11;WSL2 可按 Linux 流程自动安装 engine。原生 Windows 需手动安装 iii-engine v0.25.0:从 [iii v0.25.0 发布页](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) 下载对应归档、验证校验和,并将 `iii.exe` 放到 `PATH`。CLI 不会自动解压 ZIP
-原生 Windows 上自动化的 MCP 接入只支持 `agentmemory connect copilot-cli`。对于 Claude Code、Codex、Cursor 以及其他所有原生 Windows 代理,把 [其他代理](#other-agents) 中手动的 MCP 代码块复制进该代理的 Windows 配置中。只有当目标代理也安装在同一个 WSL 环境中时,在 WSL 中运行 `connect` 才合适;它不会编辑 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
-```
+原生 Windows 仅为 `agentmemory connect copilot-cli` 提供自动 MCP 配置;其他 agent 请使用 [Other agents](#other-agents) 中的手动配置。仅当目标 agent 也安装在同一 WSL 环境时,才在 WSL 中运行 `connect`
-**方案 C:仅独立 MCP(不需要引擎)。** 如果你的代理只需要 MCP 工具,不需要 REST API、查看器或定时任务,可以完全跳过引擎:
+**仅运行独立 MCP(不启动 engine)。** 如果不需要 REST API、查看器或运行时服务:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 即使安装了 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`。
+运行 `agentmemory doctor`,或带 `--verbose` 重启。默认端口被占用时使用 `--port <N>` 或 `--instance <N>`。兼容性与恢复说明见[升级指南](../docs/upgrades/iii-0.25.md)。
---
<h2 id="deploy">部署</h2>
-面向托管宿主的一键模板。每一个模板都自带一个独立的
-Dockerfile,从 npm 拉取 `@agentmemory/agentmemory`,再从官方的
-`iiidev/iii` Docker Hub 镜像中复制 iii 引擎二进制文件;不需要预先
-构建好的 agentmemory 镜像。持久化存储挂载在 `/data`;首次启动的
-entrypoint 会用一份针对部署场景调优过的配置覆盖 npm 自带的 iii
-配置(原配置绑定 `127.0.0.1`),新配置绑定 `0.0.0.0` 并使用绝对的
-`/data` 路径,生成 HMAC 密钥,然后在执行 agentmemory CLI 之前通过
-`gosu` 把权限从 `root` 降级到 `node`。
+使用 Docker Compose 或下方的平台模板自托管。记忆与凭据保存在 `/data` 卷中,升级时请备份并复用该卷。认证、网络和迁移说明见[部署指南](../deploy/README.md)。
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="部署到 fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="部署到 Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="部署到 fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="部署到 Railway" /></a>
</p>
-Render 的一键部署按钮需要仓库根目录下有 `render.yaml`,而我们刻意保持根目录干净。请使用 [`deploy/render/`](.././deploy/render/README.md) 中记录的 Render Blueprint 流程,手动指向仓库内的 blueprint。
+Render 的一键部署按钮需要仓库根目录下有 `render.yaml`,而我们刻意保持根目录干净。请使用 [`../deploy/render/`](.././deploy/render/README.md) 中记录的 Render Blueprint 流程,手动指向仓库内的 blueprint。
完整的设置细节(HMAC 捕获、查看器 SSH 隧道、密钥轮换、备份、
-最低成本)见 [`deploy/`](.././deploy/README.md):
+最低成本)见 [`../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):通过
+- [`../deploy/coolify`](.././deploy/coolify/README.md):通过
[Coolify](https://coolify.io/self-hosted) 自托管在你自己的 VPS 上;
同样的 Docker Compose 技术栈,主机和数据都归你所有。
-只会发布 `3111` 端口。容器内 `3113` 上的查看器仍然绑定在
-回环地址上;每个模板的 README 都记录了用于访问它的 SSH 隧道模式。
+REST 使用端口 `3111`,查看器使用 `3113`。请保持私有访问,或使用认证与 TLS 保护。平台公开设置和[旧 Docker 安装迁移](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)见部署指南。
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="为什么选择 agentmemory" height="32" /></picture></h2>
-每个编码代理在会话结束时都会忘记一切,每个新会话开始时你都要重新解释你的技术栈。agentmemory 在后台运行,免去了这一步。
+项目知识常散落在聊天和指令文件中。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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### 对比内建代理记忆
@@ -983,7 +932,7 @@ Session 2: "Now add rate limiting"
| | 内建(CLAUDE.md) | agentmemory |
|---|---|---|
-| 规模 | 200 行上限 | 无限 |
+| 维护 | 手动整理的指令 | 已索引的会话历史与记忆 |
| 搜索 | 把所有内容加载进上下文 | BM25 + 向量 + 图(仅 top-K) |
| Token 成本 | 240 条观测达 22K+ | ~1,900 tokens(减少 92%) |
| 跨代理 | 每代理一个文件 | MCP + REST(任意代理) |
@@ -1009,13 +958,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4 层记忆整合
@@ -1033,6 +982,8 @@ SessionStart hook fires
### 捕获了什么
+下表描述 Claude Code 的 hooks,其他集成捕获各自宿主提供的事件。共享 hooks 的自动上下文注入需要显式设置 `AGENTMEMORY_INJECT_CONTEXT=true`。
+
| Hook | 捕获内容 |
|------|----------|
| `SessionStart` | 项目路径、会话 ID |
@@ -1049,7 +1000,7 @@ SessionStart hook fires
| 能力 | 描述 |
|---|---|
-| **自动捕获** | 每次工具使用都通过 hooks 记录,无需人工 |
+| **自动捕获** | 原生集成记录所支持的会话与工具事件 |
| **语义搜索** | BM25 + 向量 + 知识图谱,RRF 融合 |
| **记忆演化** | 版本控制、覆盖关系、关系图 |
| **召回卫生** | 被取代的记忆版本会离开搜索索引;KV 中的版本链保留完整历史 |
@@ -1267,187 +1218,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii 控制台" height="32" /></picture></h2>
-
-`:3113` 上的查看器展示你的代理**记住了什么**。[iii 控制台](https://iii.dev/docs/console) 展示你的代理**做了什么**:每个记忆操作都是一个 OpenTelemetry trace,每个 KV 条目都可编辑,每个函数都可调用,每个流都可挂载。同一份记忆的两个窗口:一个面向产品,一个面向引擎。
-
-观察一次 `memory_smart_search` 的触发,以瀑布图的形式看到 BM25 扫描 → 嵌入查找 → RRF 融合 → 重排器。在 KV 浏览器中编辑一个卡住的整合计时器。用调整过的负载重放一次 `PostToolUse` hook。固定 WebSocket 流,实时观察观测落地。
-
-agentmemory 免费提供这一切,因为每个函数调用和触发器都经由 iii 触发;没有定制,也没有需要插桩的地方。
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii 控制台的 Workers 页面:已连接的 worker,包括带实时函数计数和运行时元数据的 agentmemory 实例" width="720" />
- <br/>
- <em>Workers 页面:每一个已连接的 worker,包括 agentmemory 本身,显示 PID、函数数量、运行时和最后在线时间。</em>
-</p>
-
-**已经装好了。** 控制台随锚定的 `iii` 引擎(0.22+)一起发布;不需要单独安装。首次启动会在引擎旁下载控制台的二进制文件。
-
-**与 agentmemory 并行启动:**
-
-```bash
-agentmemory console
-```
-
-这会针对 agentmemory 解析出的端口(REST、流、bridge)运行锚定引擎的 `iii console`,并把它服务在查看器端口之上的一个端口,默认是 `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** | 查看每一个已连接的 worker 及其实时指标,包括 agentmemory worker 本身。 |
-| **Functions** | 直接用 JSON 负载调用 agentmemory 的任意函数;方便测试 `memory.recall`、`memory.consolidate`、`graph.query`,无需接入客户端。 |
-| **Triggers** | 重放 HTTP、cron、事件和状态触发器:手动触发整合用的 cron、重试某个 HTTP 路由、发出一次状态变化。 |
-| **States** | 对会话、记忆槽位、生命周期计时器和嵌入索引进行完整 CRUD 的 KV 浏览器;就地编辑值。 |
-| **Streams** | 实时 WebSocket 监视器,观察记忆写入、hook 事件和观测更新流经 iii 流的过程。 |
-| **Queues** | 持久队列主题 + 死信管理。重放或丢弃失败的嵌入 / 压缩任务。 |
-| **Traces** | OpenTelemetry 瀑布图 / 火焰图 / 服务分解视图。按 `trace_id` 过滤,精确查看一次 `memory.search` 产生了哪些函数、数据库调用和嵌入请求。 |
-| **Logs** | 结构化的 OTEL 日志,按 trace/span ID 过滤并关联。 |
-| **Config** | 运行时配置:精确查看你的引擎正在使用哪些 worker、提供者和端口运行。 |
-| **Flow** | (可选,`--enable-flow`)每个 worker、触发器和流的交互式架构图。 |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii 控制台的 trace 瀑布图视图,显示每个 span 的耗时" width="720" />
- <br/>
- <em>Traces:每个记忆操作的瀑布图 / 火焰图 / 服务分解。</em>
-</p>
-
-**Traces 已经默认开启:**
-
-`iii-config.yaml` 出厂就启用了 `iii-observability` worker(`exporter: memory`、`sampling_ratio: 0.1`、指标 + 日志)。不需要额外配置;agentmemory 启动的那一刻,每个记忆操作都会发出一条控制台可读的结构化日志,其中十分之一(`sampling_ratio: 0.1`)还会发出一个 trace span。
-
-如果你想改为导出到 Jaeger/Honeycomb/Grafana Tempo,把 `exporter: memory` 改成 `exporter: otlp`,并按照 iii 的可观测性文档设置收集器端点。
-
-> **提醒:** 控制台本身不强制鉴权;保持它绑定在 `127.0.0.1`(默认值)上,永远不要把它对外公开。
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="由 iii 驱动" height="32" /></picture></h2>
-
-agentmemory **本身就是一个正在运行的 [iii](https://iii.dev) 实例**。三种原语(worker、函数、触发器)构成了这个运行时;KV 状态、流和 OTEL trace 来自随 iii 一同发布的 iii-state、iii-stream 和 iii-observability worker。你没有安装 Postgres、Redis、Express、pm2 或 Prometheus,因为 iii 替代了它们。
-
-这意味着只需多一条命令,就能给 agentmemory 扩展出一整套全新能力。
-
-### 用更多 worker 扩展 agentmemory
-
-agentmemory 需要的内建 worker 已经在 `iii-config.yaml` 中,并随之启动:`iii-state`(KV)、`iii-queue`(事件订阅者的持久重试)、`iii-pubsub`、`iii-cron`、`iii-stream`,以及 `iii-observability`(每个函数的 OTEL trace、指标和日志)。[iii worker 注册表](https://workers.iii.dev) 中的其他任何 worker 都可以接入同一个引擎:把 `iii-config.yaml` 复制到 `~/.agentmemory/iii-config.yaml`(CLI 会优先使用这个文件而不是捆绑的那个,并且仍然会把端口和数据路径渲染进去),加上新条目,用 `~/.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) | 当默认的内存 KV 不够用时,提供 SQL 支撑的状态适配器 |
-| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | 从 `memory_recall` 得到的代码在一次性 VM 中运行,而不是在你的 shell 里 |
-| [`mcp`](https://workers.iii.dev/workers/mcp) | 在 agentmemory 旁边架设额外的 MCP 服务器,共享同一个引擎 |
-
-在引擎 0.22.x 上,对于上面这些内建 worker 要保留 `iii-` 前缀的名称;不带前缀的 `http`、`state`、`queue`、`pubsub` 和 `cron` 条目,是 agentmemory 在 0.23 迁移中会切换过去的独立注册表 worker。
-
-完整注册表见:[workers.iii.dev](https://workers.iii.dev)。那里的每个 worker 都通过 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 监听的是容器自己的回环地址,所以发布出去的端口什么也访问不到。要让容器化的 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/) 会在它们的 entrypoint 中写入各自的 `0.0.0.0` 配置。
-
-### 存储后端:file(默认)对比 redis
-
-`iii-state` 和 `iii-stream` 默认使用 iii-engine 自带的基于文件的 KV 存储:每个作用域一个 JSON 文件,保存在引擎进程的内存中,并按计时器写回磁盘。对于单用户的本地安装,这就是正确的默认值;而一个有多个并发写入者的共享守护进程,则可以改用 Redis 获得真正的按键写入,代价是每次操作都要多一次网络往返(每个 `state::*` 调用仍然串行在同一个 Redis 连接上,所以这换来的是把文件存储的锁换成了一个 socket,而不是换来了并行性)。
-
-设置 `AGENTMEMORY_STATE_BACKEND=redis`(再加上 `AGENTMEMORY_REDIS_URL`),可以把两个 worker 都切换到 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)在构建它的 Redis 客户端时没有加入 TLS 支持,所以一个 `rediss://` URL(大多数托管 Redis 服务,例如 Upstash、Redis Cloud 以及开启传输加密的 ElastiCache,默认都是仅支持 TLS 的)会连接失败。这个连接是未加密的,所以 Redis 密码和每一条存储的记忆都会以明文形式经过网络:请指向一个本地 Redis,或者一个你信任的私有网络上的 Redis。对于其他任何 Redis,在 agentmemory 主机上运行一个加密隧道(stunnel、SSH 或 VPN),这样普通的 `redis://` 这一跳就留在该主机内部,而隧道的上游连接是加密并经过认证的。如果 Redis 密码中包含单引号,要对它做百分号编码(`%27`);引擎会先把 URL 展开进它的 YAML 配置,然后再解析它。
-
-**每个 `--instance` 对应一个 Redis 服务器。** 引擎的 Redis 键前缀(`state:<scope>`、`stream:<name>:<group>`)是固定的,所以两个指向同一个数据库的 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 重启为止。数据仍然正常保存和读取。健康监控每 30 秒会通过 Redis 发送一个测试事件;当它没有收到回应时,`/agentmemory/status` 和查看器的 Health 页面会显示"实时更新没有到达查看器",并给出修复方法:重启 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`。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) worker 文档中展示的同样的 `name: redis` / `config: redis_url: ...` 形状,并把 `redis_url` 指向容器能访问到的 Redis。`docker-compose.yml` 会把 `AGENTMEMORY_REDIS_URL` 传进引擎容器,所以 `redis_url: '${AGENTMEMORY_REDIS_URL}'` 在那里是有效的,并且能让 URL 不出现在挂载的文件里。
-
-渲染后的配置不会把 URL 写进 `~/.agentmemory/data/iii-config.runtime.yaml`,但引擎自己的配置 worker 一旦启动,仍然会把*展开后*的值持久化到 `~/.agentmemory/config/iii-state.yaml` 和 `iii-stream.yaml`(iii-engine 的 `${VAR}` 展开发生在该 worker 存储它的种子数据之前,它存储的是解析后的值,而不是引用)。在任何共享主机上,都要把这个目录当作保存着凭据来对待:执行 `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=`,用于把一个大语料库拆分成多次调用;导入时的 `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 worker 监管 |
-| Prometheus / Grafana | iii OTEL + 健康监控 |
-| Custom plugin systems | `iii worker add <name>` |
-
-**250 个源文件 · ~55,000 行代码 · 3,400+ 个测试 · 324 个函数 · 67 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="配置" height="32" /></picture></h2>
### LLM 提供者
@@ -1465,6 +1235,8 @@ agentmemory 会从你的环境中自动检测提供者。配置好提供者后,
| **本地(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=<your model>` | 任何兼容 OpenAI API 的服务。零成本,运行在你自己的硬件上。见下方的 [本地模型](#local-models-ollama--lm-studio--vllm)。 |
| Claude 订阅回退 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | 仅限主动开启。会派生 `@anthropic-ai/claude-agent-sdk` 会话;它曾导致无限制的 Stop-hook 递归,所以已不再是默认选项。 |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 本地模型(Ollama / LM Studio / vLLM)
agentmemory 可以与任何兼容 OpenAI API 的服务器通信,所以任何暴露了 `/v1/chat/completions` 的服务都无需改代码即可使用。不需要付费密钥,不需要云端,没有速率限制;完全运行在你自己的硬件上。
@@ -1514,24 +1286,9 @@ Qwen 3 模型默认会思考,可能在给出任何输出之前就把整个 token
### 成本感知的模型选择
-当同时配置了提供者并设置 `AGENTMEMORY_AUTO_COMPRESS=true`、启用了 LLM 撰写的后台压缩后,它会在每一条观测上运行,所以模型的选择会实质性地改变每月的花费。实测的工作负载数据:635 次请求 / 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 | 压缩 + 摘要质量扎实,成本比 Sonnet 低约 10 倍。 |
-| 推荐 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 如果你的会话大量是代码形态,这个模型的代码推理能力很强。 |
-| 高端 | `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(估算) | 旗舰级模型;用于压缩是过度花费。 |
-
-带实测数据的行来自实际捕获的运行;标(估算)的行则是用相同的 token 比例按各模型的标价推算得出。
-
-agentmemory 会在 `OPENROUTER_MODEL` 匹配高端档位的模式时打印一条运行时警告。一旦你已经做出了知情的选择,可以设置 `AGENTMEMORY_SUPPRESS_COST_WARNING=1` 来消除它。
-
-记忆任务上质量与成本的权衡:压缩是一个摘要任务,质量要求相对宽松(重新读取摘要的是代理,不是用户)。DeepSeek V4 Flash / V4 Pro / Qwen3-Coder 在这个任务上的表现与 Sonnet 的差距几乎可以忽略,而成本却低 10-70 倍。把高端档位的模型留给你会亲自阅读的查询。
+可以先在无密钥模式下使用捕获和关键词召回。`EMBEDDING_PROVIDER=local` 在首次下载模型后提供设备上的语义搜索。LLM 压缩需要提供者和 `AGENTMEMORY_AUTO_COMPRESS=true`,可能为每条观测发出请求,启用前请核对当前价格。
-来源:[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/)。
+`agentmemory status` / http://localhost:3113
### 多代理记忆(`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1561,41 +1318,22 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### 端口
-agentmemory + iii-engine 默认绑定四个端口。如果重启时失败并提示 `port in use`,下面这张表会告诉你该查找哪个进程。
+API 和查看器默认只监听回环地址。
-| 端口 | 进程 | 用途 | 环境变量覆盖 |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | 内部流 worker(由 agentmemory + 查看器消费) | `III_STREAM_PORT`(推荐)或旧版的 `III_STREAMS_PORT` |
-| `3113` | agentmemory | 实时查看器(`http://localhost:3113`) | `III_VIEWER_PORT`,或 `AGENTMEMORY_VIEWER_URL` 用于设置报告的 URL |
-| `49134` | iii-engine | WebSocket;worker 在这里注册,OTel 遥测数据经由它流动 | `III_ENGINE_PORT` 或 `III_ENGINE_URL` |
-
-`--port <N>` 会改变 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 会为它派生的引擎设置 `III_TELEMETRY_ENABLED=false`,捆绑的 compose 文件做法相同。
+| Port | API / 查看器 | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | 查看器 | `III_VIEWER_PORT` |
-当进程崩溃后端口仍被占用时的清理方法:
+`--port <N>` 设置 API 端口,查看器默认使用 `N+2`。`--instance N` 创建独立实例。内部监听器应保持私有;对外部署与[旧 Docker 安装迁移](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)请遵循部署指南。
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### 存储后端:file(默认)对比 redis
-`agentmemory stop` 在优雅的原生关闭过程中,会干净地回收 worker 和引擎的 pidfile。在 Docker 模式下,它会清空原生 worker,停止那个经过验证的确切引擎容器,并保留容器及其 `/data` 挂载,以便实现无损重启;下次启动时会验证并恢复同一个容器。基于 Docker 的卸载需要 `agentmemory remove --keep-data`:它会移除 agentmemory 管理的共享文件,同时保留经过验证的容器、其数据挂载,以及恢复它们所需的生命周期记录。具有破坏性的 Docker 数据删除,有意留给操作者在备份之后自行执行。除非传入 `--force`,CLI 也拒绝把 Docker 或 VM 的端口占用者(Docker backend、vpnkit、colima)当作原生引擎来接管或发信号。上面的手动清理方法只适用于崩溃后两个 pidfile 都不存在的情况。
+无需独立数据库服务. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. 切换后端不会自动复制现有记忆。 [数据存储](../docs/reliability/state-storage.md).
### 配置文件
-把 agentmemory 的运行时配置放进 `~/.agentmemory/.env`,而不是在每个 shell 中单独导出变量。如果查看器显示了一个类似 `export ANTHROPIC_API_KEY=...` 的设置提示,把它复制进这个文件,写成 `ANTHROPIC_API_KEY=...`,去掉 `export` 前缀,然后重启 agentmemory。
-
-进程环境变量仍然有效,并且优先于文件中的值。
-
-在 Windows 上,同样的文件位于 `%USERPROFILE%\.agentmemory\.env`:
+将 runtime 配置放在 `~/.agentmemory/.env`,而不是在每个 shell 中导出变量。用 `AGENTMEMORY_ENV_FILE` 选择其他 env-file 路径。进程环境变量优先于文件中的值。CLI 生成的 Worker Compose 项目会将 Redis 设置传给 `state` worker。
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1620,179 +1358,34 @@ GRAPH_EXTRACTION_ENABLED=true
### 环境变量
-创建 `~/.agentmemory/.env`:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+完整配置见 [`.env.example`](../.env.example),涵盖提供者、捕获过滤、保留策略、存储和团队作用域。`AGENTMEMORY_ENV_FILE` 可选择其他文件,修改后请重启。不要提交填有真实值的 `.env` 或 Bearer 密钥。
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-端口 `3111` 上有 143 个端点。REST API 默认绑定到 `127.0.0.1`。受保护的端点需要 `Authorization: Bearer <secret>`,mesh 同步端点则需要双方都显式设置 `AGENTMEMORY_SECRET`。
+端口 `3111` 上有 146 个端点。REST API 默认绑定到 `127.0.0.1`。受保护的端点需要 `Authorization: Bearer <secret>`,mesh 同步端点则需要双方都显式设置 `AGENTMEMORY_SECRET`。
-**身份验证默认是开启的。** 当 `AGENTMEMORY_SECRET`(在 shell 或 `~/.agentmemory/.env` 中)没有设置时,服务器会在首次启动时生成一个随机密钥,并以 `0600` 权限存储在 `~/.agentmemory/secret` 中。每个捆绑的客户端在与本地服务器通信时都会从那里读取它:CLI、查看器、`plugin/scripts` 下的 hooks、MCP 服务器和 `@agentmemory/mcp` shim、由 `agentmemory connect` 写入的配置,以及捆绑的 OpenCode、Pi、OpenClaw、Hermes 和文件系统监视集成。存储的密钥只会发送到回环地址(`localhost`、`127.0.0.0/8`、`::1`)。显式设置的 `AGENTMEMORY_SECRET` 始终优先,远程客户端仍然需要设置它。Docker 和 `deploy/` 的 entrypoint 已经会生成并导出自己的密钥。要手动调用 API:
+认证默认开启。未设置 `AGENTMEMORY_SECRET` 时,CLI 首次启动会将随机密钥保存到 `~/.agentmemory/secret`,并镜像到所选数据目录的 `secret`,权限为 `0600`。内置客户端连接本地服务器时优先读取该公共文件,只向回环 URL 发送保存的密钥。显式设置的 `AGENTMEMORY_SECRET` 优先;远程客户端需通过环境变量设置密钥。Docker 部署生成自己的密钥。
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" http://localhost:3111/agentmemory/health
```
**写入请求的规则。** 对 REST API 和查看器发出的 `POST`、`PUT`、`PATCH` 和 `DELETE` 请求,只要带有请求体,就必须发送 `Content-Type: application/json`(带 `charset` 参数也可以),而 `Origin` 头(如果存在)必须是配置的 REST 或查看器端口对应的回环源,或者列在 `VIEWER_ALLOWED_ORIGINS` 中(逗号分隔,例如 `https://memory.example.com`)。不发送 `Origin` 头的客户端(CLI、hooks、MCP、curl、服务器到服务器)不受影响。查看器也接受它自己的源。
@@ -1828,7 +1421,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | 与团队共享 |
| `GET` | `/agentmemory/audit` | 审计轨迹 |
-完整端点列表:[`src/triggers/api.ts`](../src/triggers/api.ts)
+完整端点列表:[REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1846,19 +1439,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
当服务器宕机、没有及时应答,或返回 5xx 时,hook 会把观测追加到一个本地队列文件 `<data dir>/capture-spool/<host>-<port>.jsonl` 中(用 `AGENTMEMORY_CAPTURE_SPOOL_DIR` 覆盖这个文件夹)。这个文件只对你的用户私有(权限 600),密钥会按服务器同样的方式被遮蔽,它最多容纳 `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`(5 MiB),并会丢弃超过 `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`(168)的条目。当它满了之后,新条目会被丢弃并计数,`/agentmemory/status` 会报告这一情况。当服务器健康时,hook 仍然会在它的时间限制内退出 0,并且不会增加任何请求。队列会在下次启动时,以及由第一个重新连接到服务器的 hook,在一个后台进程中发送,这样代理就不需要等待。事件 id 让这一切是安全的:一条确实在超时之前到达的观测不会被存储两次。`npx @agentmemory/agentmemory capture` 会显示队列和服务器收件箱,`--drain` 会立即发送队列,`GET /agentmemory/capture` 会以 JSON 返回同样的信息。设置 `AGENTMEMORY_CAPTURE_SPOOL=false` 可以关闭队列。
-**压缩图溯源数据。** 每个知识图谱节点和边都保留着它所来自的最新 32 条观测的 id。在这个上限生效之前写入的存储,每个热点节点可能保存着数千个 id,这会让图搜索和查看器变慢,甚至拖垮 worker。agentmemory 会自己修复这个问题:升级后的第一次启动,它会在后台把每个节点、边、被取代的边(时间性图历史)以及缓存的快照都裁剪到这个上限,分成小批次执行,批次之间有间隔,这样搜索、捕获和查看器都能继续工作。它会保存进度,重启后继续,一旦完成就再也不会运行。`/agentmemory/status` 和查看器的 Health 页面会把它显示为待处理、运行中(带当前作用域和位置)、已完成或已失败。设置 `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` 可以关闭它。
+**压缩图溯源数据。** 旧溯源数据的压缩会在启动时延后,因为它需要读取完整的旧作用域。`/agentmemory/status` 显示 `deferred`,设置 `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` 时显示 `off`。请在维护期间执行下面的手动压缩。检索索引迁移是独立操作:按照[维护指南](../docs/reliability/graph-index-migration.md)使用 `agentmemory graph-index migrate --allow-legacy-scan`。
要手动运行它,调用 `POST /agentmemory/graph/compact`。它会遍历名称和边键索引,而不是列出每一个节点和边,并且可以安全地重复运行。当它裁剪 id 时,会写入一条 `graph_compact` 审计条目。
```bash
-curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1872,7 +1465,7 @@ npm test # 4,000+ 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。
+前提条件见[安装](#install),贡献规范和发布检查见 [CONTRIBUTING.md](../CONTRIBUTING.md)。
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="许可证" height="32" /></picture></h2>
diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md
index 39a1c3c4..c66b79bb 100644
--- a/READMEs/README.zh-TW.md
+++ b/READMEs/README.zh-TW.md
@@ -4,10 +4,9 @@
<p align="center">
<strong>
- 你的編碼代理會記住一切。不用再重複解釋。
- 建構於 <a href="https://github.com/iii-hq/iii">iii engine</a> 之上
+ 跨編碼工作階段和代理的持久記憶。
</strong><br/>
- 為 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、OpenCode,以及任何 MCP 客戶端提供持久記憶。
+ 為 Claude Code、GitHub Copilot CLI、Cursor、Gemini CLI、Codex CLI、Hermes、OpenClaw、pi、Oh My Pi、DeepSeek Harness、OpenCode,以及任何 MCP 客戶端提供持久記憶。
</p>
<p align="center">
@@ -63,6 +62,7 @@
<a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests&style=for-the-badge&logo=github" alt="CI" /></a>
<a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue&style=for-the-badge" alt="License" /></a>
<a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=for-the-badge&color=yellow&logo=github" alt="Stars" /></a>
+ <a href="https://skills.sh/rohitg00/agentmemory"><img src="https://skills.sh/b/rohitg00/agentmemory?style=for-the-badge" alt="skills.sh installs" /></a>
</p>
<p align="center">
@@ -87,20 +87,21 @@
<a href="#how-it-works">運作原理</a> &bull;
<a href="#mcp-server">MCP</a> &bull;
<a href="#real-time-viewer">檢視器</a> &bull;
- <a href="#powered-by-iii">由 iii 驅動</a> &bull;
<a href="#configuration">設定</a> &bull;
<a href="#api">API</a>
</p>
---
+AgentMemory 記錄編碼工作階段,讓過去的決策與修正可供搜尋和召回。多個工具共用同一份記憶,你可以檢查儲存內容,並決定向模型提供多少上下文。
+
## 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。
+- macOS/Linux 的自動設定需要 `curl`、POSIX `sh` 和 `tar`。
+- Windows / WSL2: [Windows](#windows).
標準全新安裝指令:
@@ -108,11 +109,11 @@
npx -y @agentmemory/agentmemory@latest
```
-第一次執行是互動式設定:選擇要接入的代理(Claude Code、Cursor、Codex、Gemini CLI、OpenCode……),選擇一個 LLM 提供者或保持無金鑰,接著它會產生設定、啟動記憶伺服器與其釘住版本的 iii engine,並提議全域安裝,讓裸 `agentmemory` 指令之後在任何地方都能使用。`-y` 用於接受 npx 的套件提示,`@latest` 則避免使用過舊的快取版本。設定提供者可讓 LLM 功能可用,但只有在同時設定 `AGENTMEMORY_AUTO_COMPRESS=true` 時,LLM 撰寫的觀測壓縮才會啟動。
+選擇代理與提供者,或使用免金鑰模式。設定程式儲存設定、啟動記憶伺服器,並提供全域安裝選項。`-y` 接受 npm 確認,`@latest` 選擇最新版本。LLM 壓縮需要同時設定提供者和 `AGENTMEMORY_AUTO_COMPRESS=true`。
無金鑰模式會停用向量嵌入。`memory_recall`(即 `mem::search` 路徑)使用 BM25,而 `memory_smart_search` 在圖資料已存在時,也可以融合結構化的圖比對結果。若想免費使用裝置端的語意召回,請在 `~/.agentmemory/.env` 中設定 `EMBEDDING_PROVIDER=local` 並重新啟動。第一次的嵌入請求會下載 `Xenova/all-MiniLM-L6-v2`;之後的推論會在初始模型下載完成後於本機執行。
-本機執行階段使用四個連接埠:`3111` 為 REST/MCP HTTP,`3112` 為 iii 串流,`3113` 為檢視器,`49134` 為 iii worker 的 WebSocket。持久化的 iii 狀態在 macOS 上位於 `~/Library/Application Support/agentmemory`,在 Linux 上位於 `$XDG_DATA_HOME/agentmemory` 或 `~/.local/share/agentmemory`,在 Windows 上位於 `%APPDATA%\agentmemory`。可用 `--data-dir <path>` 或 `AGENTMEMORY_DATA_DIR` 覆寫此位置,並在每次重新啟動時沿用相同的值。為了向後相容,既有的 `./data/state_store.db` 或 `./data/iii-config.yaml` 在實例 0 上會優先於平台預設值;明確的旗標或環境變數覆寫仍會優先生效。
+API 位於 `http://localhost:3111`,即時檢視器位於 `http://localhost:3113`,預設都只監聽回環位址。設定儲存在 `~/.agentmemory/.env`。 [資料儲存](#data-storage).
接著驗證召回是否正常,並讓你的代理具備它的 skills:
@@ -127,14 +128,7 @@ npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
-隨時可用 `agentmemory connect <agent>` 接入更多代理 — [代理](#works-with-every-agent) 列出了 20 個轉接器。完整指令參考見 [快速開始](#quick-start)。
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-最快的路徑是 WSL2。原生 Windows 引擎設定需要手動下載釘住版本 v0.22.1 的 ZIP 並解壓出 `iii.exe`;CLI 不會自動解壓它。也支援 Docker Desktop。詳細步驟請見 [Windows 說明](#windows)。
-
-</details>
+使用 `agentmemory connect <agent>` 連接更多代理。參見[支援的整合](#works-with-every-agent)和[日常指令](#everyday-commands)。
<details>
<summary><strong>全域安裝 / EACCES</strong></summary>
@@ -154,13 +148,6 @@ npx 會依版本快取。用 `npx -y @agentmemory/agentmemory@latest` 強制使
</details>
-<details>
-<summary><strong>已經在執行你自己的 iii engine</strong></summary>
-
-agentmemory 把 iii-engine 釘在 v0.22.1,不會附掛到其他版本(worker 無法使用另一個引擎的協定)。先停止另一個引擎,然後執行 `npx -y @agentmemory/agentmemory@latest`。它會在 `~/.agentmemory/bin` 安裝並執行釘住的 v0.22.1,不會動到你自己的 `iii`。
-
-</details>
-
---
<h2 id="works-with-every-agent"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-agents.svg"><img src="../assets/tags/section-agents.svg" alt="Works with every agent" height="32" /></picture></h2>
@@ -187,7 +174,7 @@ agentmemory 相容於任何支援 hooks、MCP 或 REST API 的代理。所有代
<td align="center" width="20%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/cursor_dark.svg"><img src="https://svgl.app/library/cursor_light.svg" alt="Cursor" width="48" height="48" /></picture></a><br/>
<strong>Cursor</strong><br/>
-<sub>原生外掛 + 7 hooks + MCP</sub>
+<sub>原生外掛 + 生命週期 hooks + MCP</sub>
</td>
<td align="center" width="20%">
<a href="../plugin/opencode/"><img src="https://raw.githubusercontent.com/rohitg00/agentmemory/main/website/public/opencode.png" alt="OpenCode" width="48" height="48" /></a><br/>
@@ -214,7 +201,7 @@ agentmemory 相容於任何支援 hooks、MCP 或 REST API 的代理。所有代
<td align="center" width="20%">
<a href="../integrations/pi/"><img src="../assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
<strong>pi</strong><br/>
-<sub>原生外掛 + MCP</sub>
+<sub>原生召回 + 捕捉 + skills</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/tinyhumansai/openhuman"><img src="https://github.com/tinyhumansai.png?size=120" alt="OpenHuman" width="48" height="48" /></a><br/>
@@ -280,7 +267,7 @@ agentmemory 相容於任何支援 hooks、MCP 或 REST API 的代理。所有代
<td align="center" width="20%">
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://svgl.app/library/deepseek.svg" alt="DeepSeek Harness" width="48" height="48" /></a><br/>
<strong>DeepSeek Harness</strong><br/>
-<sub>MCP 伺服器</sub>
+<sub>原生捕捉 + MCP</sub>
</td>
<td align="center" width="20%">
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
@@ -303,6 +290,12 @@ agentmemory 相容於任何支援 hooks、MCP 或 REST API 的代理。所有代
<sub>REST API</sub>
</td>
</tr>
+<tr>
+<td align="center" colspan="5">
+<a href="../integrations/omp/"><strong>Oh My Pi</strong></a><br/>
+<sub>原生召回 + 捕捉 + skills + 選用 MCP</sub>
+</td>
+</tr>
</table>
<p align="center">
@@ -311,22 +304,24 @@ agentmemory 相容於任何支援 hooks、MCP 或 REST API 的代理。所有代
---
-你每次對話都要重複解釋同一套架構。你一再重新發現同樣的 bug。你反覆教它同樣的偏好。內建記憶(CLAUDE.md、.cursorrules)上限是 200 行,而且會過期。agentmemory 解決了這個問題。它會在背景靜默捕捉代理的行為,將其壓縮成可搜尋的記憶,並在下次會話開始時注入正確的上下文。一條指令。跨代理通用。
+<a id="data-storage"></a>
-**會改變什麼:**第一次會話你設定了 JWT 驗證。第二次會話你要求加上限流。代理已經知道你的驗證使用 `src/middleware/auth.ts` 中的 jose middleware,你的測試涵蓋 token 驗證,而且你選擇 jose 而非 jsonwebtoken 是為了 Edge 相容性 — 不需要重新解釋,也不需要複製貼上。
+### 資料儲存
-```bash
-npx -y @agentmemory/agentmemory@latest
-```
+記憶預設儲存在儲存庫之外。執行個體 0 會重用既有的 `./data/state_store.db`。使用 `--data-dir <path>` 或 `AGENTMEMORY_DATA_DIR` 更改目錄,重啟與升級時請保持相同目錄。
-預設情況下,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 <path>` 或設定 `AGENTMEMORY_DATA_DIR`;這兩種明確設定都會優先於舊版探索機制:
+| 平台 | 資料目錄 |
+|---|---|
+| macOS | `~/Library/Application Support/agentmemory` |
+| Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` |
+| Windows | `%APPDATA%\agentmemory` |
```bash
-npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
-AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
+agentmemory --data-dir ~/.agentmemory-projects/main
+agentmemory --instance 1
```
-原生與 Docker 啟動方式使用同一個解析出的主機目錄;Docker 會把它綁定掛載到 `/data`。`--instance 1` 會在解析出的目錄後面附加 `instance-1`,並選用另一組預設連接埠四件組 `3211/3212/3213/49234`。
+`--instance 1` 使用 `instance-1` 子目錄、API 連接埠 `3211` 和檢視器連接埠 `3213`。Redis 與後端遷移請參見[儲存與備份](../docs/reliability/state-storage.md)。
最新版本的發布說明:[CHANGELOG.md](../CHANGELOG.md)。
@@ -476,7 +471,7 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
</tr>
<tr>
<td><strong>外部相依元件</strong></td>
-<td>無(SQLite + iii-engine)</td>
+<td>不需要獨立資料庫服務</td>
<td>Qdrant / pgvector</td>
<td>Postgres + 向量資料庫</td>
<td>多種</td>
@@ -550,14 +545,12 @@ AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemor
| Zep / Graphiti | 30K | 時間性知識圖譜;已發表的時間性查詢結果最強(LongMemEval 63.8%),但圖是非同步建構,因此最新事實可能有延遲 |
| Cognee | 30K | 文件到知識圖譜的擷取,僅支援 Python,專為結構化實體擷取而設計,而非會話捕捉 |
-這些都無法透過編碼代理的 hooks 自動捕捉、不附帶本地優先的檢視器,也無法在無金鑰下執行 — 而這正是 agentmemory 圍繞打造的組合。
+AgentMemory 結合工作階段捕捉、可搜尋的專案歷史和本機檢視器,首次使用即可選擇免金鑰模式。
---
<h2 id="quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-quickstart.svg"><img src="../assets/tags/section-quickstart.svg" alt="Quick Start" height="32" /></picture></h2>
-相容性:本版本針對 `iii-sdk` 0.22.1,並釘住 iii-engine v0.22.1。
-
### 30 秒內試用
```bash
@@ -572,9 +565,11 @@ npx -y @agentmemory/agentmemory@latest demo
打開 `http://localhost:3113`,即時觀察記憶建構的過程。
+<a id="validate-a-fresh-install-and-restart-persistence"></a>
+
### 驗證全新安裝與重啟後的持久化
-在伺服器執行時,驗證 REST、健康檢查、檢視器,以及 iii 驅動的執行階段狀態:
+保持伺服器執行,檢查健康狀態、檢視器和執行狀態。
```bash
curl -fsS http://localhost:3111/agentmemory/livez
@@ -583,20 +578,27 @@ curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
-啟動就緒面板會涵蓋全部四個連接埠:REST/MCP HTTP 在 3111,iii 串流在 3112,檢視器在 3113,iii worker 的 WebSocket 在 49134。`status` 會確認 agentmemory 的健康狀態,以及目前使用的提供者/嵌入模式。儲存一筆探測資料並確認它可被搜尋到:
+`status` 顯示伺服器健康、提供者、嵌入模式、捕捉傳遞和復原狀態。受保護的 REST 請求需要伺服器密鑰。使用已設定的 `AGENTMEMORY_SECRET`;若未設定,則讀取產生的本機密鑰。
```bash
+# Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead.
+read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"
+
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
+ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
然後執行 `npx -y @agentmemory/agentmemory@latest stop`,在終端 1 再次執行標準指令,等待 `/agentmemory/livez` 回應,再重複一次搜尋。那筆探測資料應該仍會被回傳。若你選用了自訂的 `--data-dir`,重新啟動時要傳入相同的目錄。
+<a id="everyday-commands"></a>
+
### 日常指令
安裝與設定請見上方的 [安裝](#install)(第一次執行會引導你完成設定)。日常使用:
@@ -604,7 +606,10 @@ curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
-agentmemory connect <agent> # wire another agent
+agentmemory status # health, providers and recovery state
+agentmemory capture # inspect capture inbox and offline spool
+agentmemory capture --drain # replay queued observations
+agentmemory connect <agent> # connect another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
@@ -623,7 +628,7 @@ npx -y @agentmemory/agentmemory@latest import-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 函式路由,沒有側通道伺服器。每份匯入的逐字稿都會被索引供搜尋、蓋上來源通道 `import` 的戳記,並被挖掘出會話結晶與教訓。
+匯入的工作階段會與原生工作階段一起顯示於 Replay,建立搜尋索引並標記來源通道 `import`。工作階段處理也可能產生結晶和教訓。
> **若你把 `import-jsonl` 當作主要的擷取路徑,請留意:**Claude Code 的 `cleanupPeriodDays`(在 `~/.claude/settings.json` 中,預設 **30**)會自動刪除超過該期限的 JSONL 逐字稿,從 `~/.claude/projects/` 中移除。若你在一個已有數個月歷史的 Claude Code 環境上全新安裝 agentmemory,超過 30 天的資料在第一次匯入前就已經消失。你可以把 `import-jsonl` 排進 cron、把 `cleanupPeriodDays` 調高,或是接上自動擷取的 hooks(預設的外掛安裝路徑),讓每個回合在會話還在進行時就落入 agentmemory,JSONL 清理就不再是問題。
@@ -635,14 +640,12 @@ npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-proje
npx -y @agentmemory/agentmemory@latest upgrade
```
-警告:此指令會變更目前的工作區/執行階段。它可能更新 JavaScript 相依套件,並拉取釘住版本的 `iiidev/iii:0.22.1` Docker 映像檔。它永遠不會安裝未釘住或更新版本的 iii engine。
-
-實作細節位於 `src/cli.ts`(參見 `src/cli.ts:544-595` 附近的 `runUpgrade`)。
+這會更新本機執行階段,也可能更新目前工作目錄中的 JavaScript 相依項目。請備份資料,並在更新既有安裝前閱讀[升級指南](../docs/upgrades/iii-0.25.md)。
### 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.
+Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### Claude Code 若未安裝外掛(MCP 獨立路徑)
@@ -703,6 +706,26 @@ 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 環境中時,在 WSL 中執行 `connect` 才有意義。Copilot 會在下次啟動或執行 `/mcp` 後取得這個 MCP 伺服器。若想要完整的 hook/skill 體驗,也請安裝外掛。
+### Cursor
+
+使用 `agentmemory connect cursor` 設定 MCP。在 **Settings → Plugins → Add marketplace** 選擇含 `.cursor-plugin/plugin.json` 的檢出目錄,啟用 agentmemory 並重新載入。外掛提供生命週期捕捉、工作區歸屬、skills 和 MCP。外掛 hooks 與 `~/.cursor/hooks.json` 中的手動 hooks 只啟用一種,避免重複捕捉。
+
+[Cursor](../integrations/cursor/)
+
+### Pi / Oh My Pi / DeepSeek Harness
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+選擇對應宿主的指令。Pi 和 OMP 安裝原生召回、捕捉、離線重播與 17 個 skills,`--with-mcp` 增加完整工具集。在 Pi 執行 `/reload`,或重啟 OMP,然後檢查 `/agentmemory-status`。DSH 安裝 MCP 和內建捕捉外掛,連接後請重啟。
+
+Pi 也提供可安裝的 `@agentmemory/pi` 套件。本機安裝與 npm 可用狀態見 [Pi 指南](../integrations/pi/)。每個宿主只使用一種安裝方式。
+
+[Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
+
<details>
<summary><b>OpenClaw(貼上這段提示)</b></summary>
@@ -749,6 +772,8 @@ Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localho
</details>
+<a id="other-agents"></a>
+
### 其他代理
啟動記憶伺服器:`npx -y @agentmemory/agentmemory@latest`
@@ -765,8 +790,7 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
這與 `agentmemory connect <agent>` 是**互補**的:
-- `agentmemory connect <agent>` 會寫入 MCP 伺服器設定,讓工具可用。
-- `npx skills add rohitg00/agentmemory` 會安裝 skills,讓代理知道何時該呼叫它們。
+Hermes、OpenClaw、Pi 和 Oh My Pi 的連接器預設安裝原生整合和 skills;MCP 透過 `--with-mcp` 選裝。其他宿主可用 `npx skills add rohitg00/agentmemory` 安裝 skills。
對於 skills CLI 尚未涵蓋的少數代理(Zed v1.3.x 及更早版本),請自行把這 17 個 SKILL.md 檔案放到該代理的原生 skill 目錄下;同一種格式在任何地方都適用。
@@ -790,12 +814,12 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| 代理 | 設定檔 | 備註 |
|---|---|---|
| **Cursor(僅 MCP)** | `~/.cursor/mcp.json` | 合併進 `mcpServers`,或使用 `agentmemory connect cursor`。網站上也提供一鍵式 deeplink。 |
-| **Cursor(完整外掛)** | `.cursor-plugin/` | Cursor Marketplace 上架中(送審審核中),或透過 Cursor Settings → Plugins → 本機 checkout 安裝。會註冊 7 個自動擷取 hooks(sessionStart、beforeSubmitPrompt、preToolUse、postToolUse、postToolUseFailure、stop、sessionEnd)+ 17 個 skills + MCP 伺服器,`AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` 由 Cursor 的外掛儀表板管理。可在 Cursor IDE 與 `cursor-agent` CLI 中運作;CLI 的 print-mode 提示會在會話結束時從會話逐字稿回填。 |
+| **Cursor(完整外掛)** | `.cursor-plugin/` | 透過 Cursor Marketplace 或 Settings → Plugins → 本機檢出安裝。輕量轉接器呼叫共用的 `plugin/scripts/*.mjs` 註冊生命週期 hooks,並提供 skills 和 MCP。轉接器解析 Cursor 未可靠回報的工作區。參見 [Cursor](#cursor)。適用於 Cursor IDE 和 `cursor-agent` 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 + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` 會合併 MCP 條目;`--with-hooks` 會再加上六個原生自動擷取 hooks(SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd),使用 Devin 的小寫工具比對器。用 `devin mcp list` 和 devin 內的 `/hooks` 驗證。 |
| **Devin CLI(完整外掛)** | `plugin/.devin-plugin/` | 從 checkout 執行 `devin plugins install ./plugin`,會把全部 17 個 skills 註冊為 `/agentmemory:<skill>` 斜線指令,並加上 MCP 伺服器。Devin 外掛 hooks 無法觸發 `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 個工具都出現。 |
+| **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 plugin install | 執行 `copilot plugin install rohitg00/agentmemory:plugin`,從 GitHub 子目錄安裝外掛。 |
@@ -804,7 +828,8 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **Codex CLI(完整外掛)** | Codex plugin marketplace | 先執行 `codex plugin marketplace add rohitg00/agentmemory`,再執行 `codex plugin add agentmemory@agentmemory`。會註冊 MCP + 6 個生命週期 hooks + 17 個 skills。請在你的宿主上信任 hooks 並驗證擷取是否生效;參見[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 個自動擷取 hooks,涵蓋會話生命週期、訊息、工具、錯誤。專案歸屬是以會話為單位,因此一個橫跨多個倉庫的 OpenCode 行程,會把每個會話各自歸入它自己的專案。提供兩個斜線指令(`/recall`、`/remember`)。把 `plugin/opencode/` 複製到你的 OpenCode 工作區,並在 `opencode.json` 中加入外掛條目。完整的 hook 對照表 + 差異分析見 [`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 套件(從 checkout 執行 `pi install ./integrations/pi`)。 |
+| **pi** | `~/.pi/agent` | `agentmemory connect pi --with-mcp` · 原生召回 + 捕捉 + skills. [Pi](../integrations/pi/) |
+| **Oh My Pi (OMP)** | `~/.omp/agent/config.yml` | `agentmemory connect omp --with-mcp` · 原生召回 + 捕捉 + skills. [Oh My Pi](../integrations/omp/) |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` 搭配 `memory.provider: agentmemory`,即可取得 6-hook 記憶提供者(prefetch、回合捕捉、session end、pre-compress、MEMORY.md 鏡像、system prompt block)。用 `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 IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks` 會在共用的自訂目錄中安裝 MCP 和擷取 hooks。參見[Antigravity 設定與限制](../docs/plugins/antigravity.md)。 |
@@ -812,39 +837,19 @@ npx skills add rohitg00/agentmemory -y -a '*' # install to every installed age
| **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` 使用陣列格式(而非物件)。 |
+| **Continue.dev** | `~/.continue/config.yaml`(建議)或 `config.json`(舊版) | `agentmemory connect continue` 在沒有設定時建立 `config.yaml`,或更新既有 `config.json`。既有 YAML 會保留不動,以保護註解和錨點;指令會印出應貼到 `mcpServers:` 下的設定區塊。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` 區塊。專案層級的覆寫請放在 `<repo>/.factory/mcp.json`。傳入 `--with-hooks` 以取得原生自動擷取。 |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh` 啟用 MCP 工具。加入 `--with-hooks` 可載入 AgentMemory 內建的原生擷取外掛程式,無需額外的外掛套件。 [DSH](../docs/dsh.md). |
| **Goose** | Goose MCP 設定介面 | 同樣的 `mcpServers` 區塊;使用 `goose configure` → Add Extension → MCP。也支援直接編輯 `~/.config/goose/config.yaml`,但其格式使用 `extensions:` + `cmd`(而非 `mcpServers:` + `command`)。 |
-| **Aider** | 不適用 | 直接呼叫 REST API:`curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`。 |
+| **Aider** | 不適用 | [REST API](#validate-a-fresh-install-and-restart-persistence) |
| **任何代理(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 的語言都可以透過 `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 仍然可用。
+任何語言均可使用 [REST API](#api),代理可使用 [MCP 工具](#mcp-server)。REST 使用 JSON 和 Bearer 驗證,參見[儲存與搜尋範例](#validate-a-fresh-install-and-restart-persistence)。直接連接執行階段的範例見 [Python 指南](../examples/python/)。
### 從原始碼建置
@@ -853,114 +858,64 @@ 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` 相依套件是同一個版本;worker 使用該引擎的 wire 協定,而 0.20.0 重組了 SDK 的介面,因此這兩者在 agentmemory 的每個版本中會一起移動。若你執行自己的引擎並確定版本相符,可用 `AGENTMEMORY_III_VERSION=<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)。
+`npm start` 啟動與已安裝 CLI 相同的本機伺服器。[安裝](#install)列出了相依項目;API 與檢視器監聽 `127.0.0.1`。
### 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 環境中時,在 WSL 中執行 `connect` 才是合適的作法;它不會編輯 Windows 宿主代理的設定。
+agentmemory 可在 Windows 10/11 執行;WSL2 可依 Linux 流程自動安裝 engine。原生 Windows 需手動安裝 iii-engine v0.25.0:從 [iii v0.25.0 發行頁面](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.0) 下載相符封存檔、驗證 checksum,並將 `iii.exe` 放入 `PATH`。CLI 不會自動解壓 ZIP
-**選項 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
-```
+原生 Windows 僅支援 `agentmemory connect copilot-cli` 自動設定 MCP;其他 agent 請使用 [Other agents](#other-agents) 的手動設定。只有目標 agent 也安裝在相同 WSL 環境時,才在 WSL 執行 `connect`
-**選項 C:僅獨立 MCP(不需引擎)。** 若你的代理只需要 MCP 工具,不需要 REST API、檢視器或 cron 工作,可以完全略過引擎:
+**僅使用獨立 MCP(不啟動 engine)。** 若不需要 REST API、檢視器或執行階段服務:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
-# or via the shim package:
+# or
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 <N>` |
-| 即使已安裝 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`。
+執行 `agentmemory doctor`,或加上 `--verbose` 重新啟動。預設連接埠被占用時使用 `--port <N>` 或 `--instance <N>`。相容性與復原說明見[升級指南](../docs/upgrades/iii-0.25.md)。
---
<h2 id="deploy">部署</h2>
-為託管主機提供的一鍵式範本。每個範本都附帶一個自成一體的 Dockerfile,會從 npm 拉取 `@agentmemory/agentmemory`,並從官方的 `iiidev/iii` Docker Hub 映像檔複製 iii engine 執行檔進去;不需要預先建置好的 agentmemory 映像檔。持久化儲存會掛載在 `/data`;首次開機的 entrypoint 會把 npm 捆綁的 iii 設定(綁定 `127.0.0.1`)覆寫成一份為部署調整過的設定,改為綁定 `0.0.0.0` 並使用絕對的 `/data` 路徑,產生 HMAC 密鑰,然後在執行 agentmemory CLI 之前,透過 `gosu` 把權限從 `root` 降為 `node`。
+使用 Docker Compose 或下方的平台範本自行託管。記憶與憑證儲存在 `/data` 卷中,升級時請備份並重用該卷。驗證、網路和遷移說明見[部署指南](../deploy/README.md)。
<p>
- <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
- <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+ <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+ <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
</p>
-Render 的一鍵部署按鈕需要倉庫根目錄下有 `render.yaml`,而我們特意讓根目錄保持乾淨。請使用 [`deploy/render/`](.././deploy/render/README.md) 中說明的 Render Blueprint 流程,手動指向倉庫內的 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 通道模式。
+REST 使用連接埠 `3111`,檢視器使用 `3113`。請保持私有存取,或以驗證和 TLS 保護。平台公開設定和[舊 Docker 安裝遷移](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)見部署指南。
---
<h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-why.svg"><img src="../assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
-每個編碼代理在會話結束時都會遺忘一切,而每個新會話的開始,都是你重新解釋一次你的技術棧。agentmemory 在背景執行,移除了這個步驟。
+專案知識常散落在聊天和指令檔案中。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
+ Connected hooks capture supported tool events
+ Observations become searchable project history
Session 2: "Now add rate limiting"
- Agent already knows:
+ Agent recalls:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
- Zero re-explaining. Starts working immediately.
+ Continues with the earlier decisions in context.
```
### 對比內建代理記憶
@@ -969,7 +924,7 @@ Session 2: "Now add rate limiting"
| | 內建(CLAUDE.md) | agentmemory |
|---|---|---|
-| 規模 | 上限 200 行 | 無上限 |
+| 維護 | 手動整理的指令 | 已索引的工作階段歷史與記憶 |
| 搜尋 | 把所有內容載入上下文 | BM25 + 向量 + 圖(僅 top-K) |
| Token 成本 | 240 條觀測達 22K+ | ~1,900 個 token(少 92%) |
| 跨代理 | 每個代理各自的檔案 | MCP + REST(任何代理) |
@@ -995,13 +950,13 @@ PostToolUse hook fires
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
- -> Slot reflection (if SLOT_REFLECT_ENABLED=true)
+ -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
- -> Inject into conversation
+ -> Inject context when enabled by the integration
```
### 4 層記憶整合
@@ -1019,6 +974,8 @@ SessionStart hook fires
### 會捕捉什麼
+下表描述 Claude Code 的 hooks,其他整合捕捉各自宿主提供的事件。共用 hooks 的自動上下文注入需要明確設定 `AGENTMEMORY_INJECT_CONTEXT=true`。
+
| Hook | 捕捉內容 |
|------|----------|
| `SessionStart` | 專案路徑、會話 ID |
@@ -1035,7 +992,7 @@ SessionStart hook fires
| 功能 | 說明 |
|---|---|
-| **自動捕捉** | 每次工具使用都透過 hooks 記錄,不需人工操作 |
+| **自動捕捉** | 原生整合記錄支援的工作階段與工具事件 |
| **語意搜尋** | BM25 + 向量 + 知識圖譜,以 RRF 融合 |
| **記憶演化** | 版本管理、取代機制、關係圖 |
| **召回衛生** | 被取代的記憶版本會離開搜尋索引;KV 中的版本鏈保留完整歷史 |
@@ -1253,187 +1210,6 @@ open http://localhost:3113
---
-<h2 id="iii-console"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-viewer.svg"><img src="../assets/tags/section-viewer.svg" alt="iii Console" height="32" /></picture></h2>
-
-:3113 上的檢視器展示你的代理**記住了什麼**。[iii console](https://iii.dev/docs/console) 展示你的代理**做了什麼**:每個記憶操作都是一個 OpenTelemetry trace,每個 KV 條目都可編輯,每個函式都可呼叫,每個串流都可掛接監看。同一份記憶的兩個視窗:一個以產品為形,一個以引擎為形。
-
-觀察一次 `memory_smart_search` 的觸發,以瀑布圖的形式看到 BM25 掃描 → 嵌入查找 → RRF 融合 → 重新排序器。在 KV 瀏覽器中編輯卡住的整合計時器。用調整過的負載重播一個 `PostToolUse` hook。釘選 WebSocket 串流,即時觀察觀測資料落地。
-
-agentmemory 免費提供這一切,因為每個函式呼叫和觸發器都經由 iii 觸發;沒有自訂內容,也沒有需要插樁的地方。
-
-<p align="center">
- <img src="../assets/iii-console/workers.png" alt="iii console Workers 頁面:已連接的 workers,包括 agentmemory 實例,顯示即時函式數與執行階段元資料" width="720" />
- <br/>
- <em>Workers 頁面:每個已連接的 worker,包括 agentmemory 本身,顯示 PID、函式數、執行階段和最後上線時間。</em>
-</p>
-
-**已經內建安裝。** 主控台隨釘住版本的 iii engine(0.22+)一起提供;不需要另外安裝。第一次啟動會在引擎旁邊下載主控台執行檔。
-
-**與 agentmemory 一起啟動:**
-
-```bash
-agentmemory console
-```
-
-這會針對 agentmemory 解析出的連接埠(REST、串流、橋接)執行釘住版本引擎的 `iii console`,並在檢視器連接埠之上一個連接埠提供服務,預設為 `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** | 查看每個已連接的 worker 及其即時指標,包括 agentmemory worker 本身。 |
-| **Functions** | 直接以 JSON 負載呼叫 agentmemory 的任何函式;方便測試 `memory.recall`、`memory.consolidate`、`graph.query`,不需要接入用戶端。 |
-| **Triggers** | 重播 HTTP、cron、事件和狀態觸發器:手動觸發整合 cron、重試某個 HTTP 路由、發出狀態變更。 |
-| **States** | KV 瀏覽器,對會話、記憶槽位、生命週期計時器和嵌入索引提供完整的 CRUD;可就地編輯值。 |
-| **Streams** | 即時 WebSocket 監視器,顯示流經 iii 串流的記憶寫入、hook 事件和觀測更新。 |
-| **Queues** | 持久化佇列主題 + dead-letter 管理。重播或捨棄失敗的嵌入 / 壓縮工作。 |
-| **Traces** | OpenTelemetry 瀑布圖 / 火焰圖 / 服務分解視圖。依 `trace_id` 過濾,精確查看單次 `memory.search` 產生了哪些函式、DB 呼叫和嵌入請求。 |
-| **Logs** | 結構化的 OTEL 日誌,已與 trace/span ID 過濾並關聯。 |
-| **Config** | 執行階段設定:精確查看你的引擎目前使用哪些 workers、提供者和連接埠。 |
-| **Flow** | (選用,`--enable-flow`)每個 worker、觸發器和串流的互動式架構圖。 |
-
-<p align="center">
- <img src="../assets/iii-console/traces-waterfall.png" alt="iii console trace 瀑布圖視圖,顯示每個 span 的耗時" width="720" />
- <br/>
- <em>Traces:每個記憶操作的瀑布圖 / 火焰圖 / 服務分解視圖。</em>
-</p>
-
-**Traces 預設已開啟:**
-
-`iii-config.yaml` 預設啟用了 `iii-observability` worker(`exporter: memory`、`sampling_ratio: 0.1`,包含 metrics + logs)。不需要額外設定;agentmemory 一啟動,每個記憶操作就會發出主控台可以讀取的結構化日誌,其中十分之一(`sampling_ratio: 0.1`)還會發出一個 trace span。
-
-若你想改為匯出到 Jaeger/Honeycomb/Grafana Tempo,把 `exporter: memory` 改為 `exporter: otlp`,並依 iii 的可觀測性文件設定收集器端點。
-
-> **提醒:** 主控台本身不強制要求驗證;請讓它維持綁定在 `127.0.0.1`(預設值),絕對不要公開曝露它。
-
----
-
-<h2 id="powered-by-iii"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-architecture.svg"><img src="../assets/tags/section-architecture.svg" alt="Powered by iii" height="32" /></picture></h2>
-
-agentmemory **本身就是一個執行中的 [iii](https://iii.dev) 實例**。三種原語(worker、function、trigger)組成了這個執行階段;KV 狀態、串流和 OTEL traces 來自隨 iii 一起發布的 iii-state、iii-stream 和 iii-observability workers。你沒有安裝 Postgres、Redis、Express、pm2 或 Prometheus,因為 iii 已經取代了它們。
-
-這意味著只要多一條指令,就能為 agentmemory 擴展出一整項全新的能力。
-
-### 用更多 workers 擴展 agentmemory
-
-agentmemory 所需的內建元件已經在 `iii-config.yaml` 中,並隨它一起啟動:`iii-state`(KV)、`iii-queue`(事件訂閱者的持久化重試)、`iii-pubsub`、`iii-cron`、`iii-stream`,以及 `iii-observability`(每個函式的 OTEL traces、metrics 和日誌)。[iii worker 註冊表](https://workers.iii.dev) 中的其他任何東西都能接入同一個引擎:把 `iii-config.yaml` 複製到 `~/.agentmemory/iii-config.yaml`(CLI 會優先使用這個檔案而非捆綁版本,並仍會把連接埠與資料路徑渲染進去),加入條目,用 `~/.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) | 當你超出預設的記憶體內 KV 時,提供 SQL 支援的狀態配接器 |
-| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | 讓 `memory_recall` 找出的程式碼在一個用過即丟的 VM 中執行,而不是在你的殼層中 |
-| [`mcp`](https://workers.iii.dev/workers/mcp) | 在 agentmemory 的 MCP 伺服器旁架設額外的 MCP 伺服器,共用同一個引擎 |
-
-在引擎 0.22.x 上,請保留上述內建元件的 `iii-` 前綴名稱;不帶前綴的 `http`、`state`、`queue`、`pubsub` 和 `cron` 條目,是 agentmemory 將隨 0.23 遷移過去的獨立註冊表 workers。
-
-完整的註冊表:[workers.iii.dev](https://workers.iii.dev)。那裡的每個 worker 都是透過 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/) 會在它們的 entrypoint 中寫入自己的 `0.0.0.0` 設定。
-
-### 儲存後端:file(預設)對比 redis
-
-`iii-state` 和 `iii-stream` 預設使用 iii-engine 捆綁的檔案型 KV 儲存:每個範圍一個 JSON 檔案,保存在引擎行程的記憶體中,並依計時器寫回磁碟。這對單一使用者的本機安裝來說是正確的預設值;而有多個併發寫入者的共享常駐行程,則可以改用 Redis 取得真正的逐鍵寫入,代價是每次操作都要多一次網路往返(每個 `state::*` 呼叫仍會在同一個 Redis 連線上序列化,所以這是把檔案儲存的鎖換成一個 socket,而不是換來平行處理)。
-
-設定 `AGENTMEMORY_STATE_BACKEND=redis`(再加上 `AGENTMEMORY_REDIS_URL`),即可把這兩個 workers 都切換到 iii-engine 內建的 `redis` 配接器,它會把每個鍵存成一個 Redis hash 欄位(`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,以及開啟傳輸加密的 ElastiCache,預設都只接受 TLS)會連線失敗。這個連線是未加密的,因此 Redis 密碼和每一筆儲存的記憶都會以明文傳輸:請指向本機的 Redis,或你信任的私有網路上的 Redis。若要用其他的 Redis,請在 agentmemory 主機上執行一條加密通道(stunnel、SSH 或 VPN),讓那段純 `redis://` 的連線留在該主機內,而通道的上游連線則是加密且經過驗證的。若 Redis 密碼含有單引號,請將其百分號編碼(`%27`);引擎會在解析之前,先把這個 URL 展開進它的 YAML 設定中。
-
-**每個 `--instance` 要用各自的 Redis 伺服器。** 引擎的 Redis 鍵前綴(`state:<scope>`、`stream:<name>:<group>`)是固定的,因此指向同一個資料庫的兩個 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 hash(`HSET`/`HGET`/`HGETALL`),並觸發與檔案儲存相同的狀態觸發器。有三個引擎層級的差異由 agentmemory 內部自行處理:
-
-- Redis 回傳某個範圍的紀錄時沒有固定順序。agentmemory 會依記錄 id 中的建立時間、再依其時間戳記,把它們排成最舊在前,讓列表、分頁和匯出區塊的順序與檔案儲存一致。
-- 引擎在 Redis 上以一個 Lua 腳本套用部分更新,而該腳本會把空陣列變成空物件。agentmemory 會在 Redis 上自行套用這些更新(在逐鍵鎖之下讀取、變更、寫入),因此像 `tags: []` 這樣的欄位能保持為陣列。
-- 舊版的稽核日誌檢查會從 Redis 讀取舊的範圍,而不是在磁碟上尋找檔案儲存的檔案。
-
-有一個差異需要你介入:**Redis 重新啟動後,引擎會停止向檢視器轉送即時事件**,直到 agentmemory 重新啟動為止。資料仍會正常儲存和讀取。健康監控每 30 秒會透過 Redis 傳送一個測試事件;若收不到回應,`/agentmemory/status` 和檢視器的 Health 頁面會顯示「即時更新沒有送達檢視器」,並附上解決方法:重新啟動 agentmemory。若 Redis 已經掛掉,狀態回報會顯示「狀態儲存沒有回應」,以及如何檢查它(`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)。列出一個非常大的範圍時,會用一次 `HGETALL` 讀取整個 hash,成本和檔案儲存把它留在記憶體中一樣。
-
-**建議的 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` 偵測到這種組合時會發出警告。要手動切換那個檔案,請依照 [iii-state](https://workers.iii.dev/workers/iii-state) 和 [iii-stream](https://workers.iii.dev/workers/iii-stream) worker 文件中展示的同一種 `name: redis` / `config: redis_url: ...` 格式,並讓 `redis_url` 指向容器能連到的 Redis。`docker-compose.yml` 會把 `AGENTMEMORY_REDIS_URL` 傳進引擎容器,因此在那裡 `redis_url: '${AGENTMEMORY_REDIS_URL}'` 可以運作,並讓 URL 不出現在掛載的檔案中。
-
-渲染後的設定不會把 URL 寫進 `~/.agentmemory/data/iii-config.runtime.yaml`,但引擎自己的設定 worker 啟動後,仍會把*展開後*的值持久化到 `~/.agentmemory/config/iii-state.yaml` 和 `iii-stream.yaml`(iii-engine 的 `${VAR}` 展開發生在該 worker 儲存其種子資料之前,它儲存的是解析後的值,而不是參照)。請把那個目錄視為存放憑證的地方:在任何共享主機上執行 `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=`,用於把大型語料庫分成幾次呼叫來處理;匯入時的 `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 的 worker 監管 |
-| Prometheus / Grafana | iii OTEL + 健康監控 |
-| 自訂外掛系統 | `iii worker add <name>` |
-
-**250 個原始檔 · ~55,000 行程式碼 · 3,400+ 測試 · 324 個函式 · 67 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
-
----
-
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
### LLM 提供者
@@ -1451,6 +1227,8 @@ agentmemory 會從你的環境自動偵測提供者。設定提供者可讓 LLM
| **本地(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-hook 遞迴,因此不再是預設值。 |
+<a id="local-models-ollama--lm-studio--vllm"></a>
+
### 本地模型(Ollama / LM Studio / vLLM)
agentmemory 可以和任何相容 OpenAI API 的伺服器溝通,因此任何開放 `/v1/chat/completions` 的服務都能不改程式碼直接運作。不需要付費金鑰,不需要雲端,沒有速率限制;完全在你自己的硬體上執行。
@@ -1500,24 +1278,9 @@ Qwen 3 模型預設會思考,可能在輸出任何內容之前,就把整個 toke
### 成本意識的模型選擇
-當同時設定提供者和 `AGENTMEMORY_AUTO_COMPRESS=true`,啟用 LLM 撰寫的背景壓縮時,它會對每一筆觀測執行,因此模型選擇會明顯改變每月支出。擷取到的工作負載資料:635 次請求 / 888K token / 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 | 壓縮 + 摘要品質穩固,成本約為 Sonnet 的 10 分之一。 |
-| 建議 | `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(估計) | 旗艦級模型;用於壓縮是過度花費。 |
-
-已實測的列來自擷取到的執行結果;標記(估計)的列,是用各模型的牌價,依相同的 token 組合比例換算出來的。
-
-當 `OPENROUTER_MODEL` 符合高階等級的模式時,agentmemory 會在執行階段印出警告。一旦你做出了知情的選擇,可設定 `AGENTMEMORY_SUPPRESS_COST_WARNING=1` 來消除它。
-
-記憶工作在品質與成本之間的取捨:壓縮是一項品質門檻相對寬鬆的摘要任務(重新讀取摘要的是代理,不是使用者)。在這項任務上,DeepSeek V4 Flash / V4 Pro / Qwen3-Coder 的表現幾乎與 Sonnet 不相上下,成本卻低 10 到 70 倍。把高階等級的模型留給你會親自閱讀的查詢。
+可以先在免金鑰模式下使用捕捉和關鍵字召回。`EMBEDDING_PROVIDER=local` 在首次下載模型後提供裝置上的語意搜尋。LLM 壓縮需要提供者和 `AGENTMEMORY_AUTO_COMPRESS=true`,可能為每條觀測發出請求,啟用前請核對目前價格。
-來源:[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/)。
+`agentmemory status` / http://localhost:3113
### 多代理記憶(`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
@@ -1547,41 +1310,22 @@ AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
### 連接埠
-agentmemory + iii-engine 預設會綁定四個連接埠。若重新啟動時出現 port in use 的錯誤,這張表會告訴你該找哪個行程。
+API 與檢視器預設只監聽回環位址。
-| 連接埠 | 行程 | 用途 | 環境變數覆寫 |
-|------|---------|---------|--------------|
-| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
-| `3112` | iii-engine | 內部串流 worker(供 agentmemory + 檢視器使用) | `III_STREAM_PORT`(建議)或舊版的 `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 <N>` 會改變 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 會為它所產生的引擎設定 `III_TELEMETRY_ENABLED=false`,除非你自己匯出了這個變數;捆綁的 compose 檔案做法相同。
+| Port | API / 檢視器 | Env |
+|---|---|---|
+| `3111` | REST / MCP / SSE | `III_REST_PORT` |
+| `3113` | 檢視器 | `III_VIEWER_PORT` |
-崩潰執行後連接埠仍被佔用時的過期行程清理:
+`--port <N>` 設定 API 連接埠,檢視器預設使用 `N+2`。`--instance N` 建立獨立執行個體。內部監聽器應保持私有;對外部署與[舊 Docker 安裝遷移](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode)請遵循部署指南。
-```bash
-# macOS / Linux — find whatever is on each port and kill it
-lsof -i :3111,3112,3113,49134
-pkill -f agentmemory || true
-pkill -f 'iii ' || true
-
-# Windows
-netstat -ano | findstr ":3111 :3112 :3113 :49134"
-taskkill /F /PID <pid>
-```
+### 儲存後端:file(預設)對比 redis
-`agentmemory stop` 在優雅的原生關閉時,會乾淨地回收 worker 和引擎的 pidfile。在 Docker 模式下,它會清空原生 worker、停止那個經過驗證的確切引擎容器,並保留容器和它的 `/data` 掛載以供無損重啟;下次啟動時會驗證並恢復同一個容器。以 Docker 為後端的卸載需要 `agentmemory remove --keep-data`:它會移除 agentmemory 管理的共享檔案,同時保留經過驗證的容器、它的資料掛載,以及用於復原它們所需的生命週期紀錄。具破壞性的 Docker 資料刪除,刻意留給操作者在備份之後自行執行。CLI 也會拒絕把 Docker 或 VM 連接埠持有者(Docker 後端、vpnkit、colima)當作原生引擎來接管或發送訊號,除非傳入 `--force`。上面的手動清理僅適用於崩潰後兩個 pidfile 都沒留下的情況。
+不需要獨立資料庫服務. Redis: `AGENTMEMORY_STATE_BACKEND=redis` + `AGENTMEMORY_REDIS_URL`. 切換後端不會自動複製現有記憶。 [資料儲存](../docs/reliability/state-storage.md).
### 設定檔
-把 agentmemory 的執行階段設定放進 `~/.agentmemory/.env`,而不是在每個殼層中匯出變數。若檢視器顯示像 `export ANTHROPIC_API_KEY=...` 這樣的設定提示,把它複製進這個檔案時去掉 `export` 前綴,寫成 `ANTHROPIC_API_KEY=...`,然後重新啟動 agentmemory。
-
-行程環境變數仍然有效,且優先於檔案中的值。
-
-在 Windows 上,同一個檔案位於 `%USERPROFILE%\.agentmemory\.env`:
+將 runtime 設定放在 `~/.agentmemory/.env`,而非每個 shell 都 export 變數。使用 `AGENTMEMORY_ENV_FILE` 選取其他 env-file 路徑。Process environment variable 優先於檔案中的值。CLI 產生的 Worker Compose 專案會將 Redis 設定傳給 `state` worker。
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
@@ -1606,179 +1350,34 @@ GRAPH_EXTRACTION_ENABLED=true
### 環境變數
-建立 `~/.agentmemory/.env`:
+`~/.agentmemory/.env`:
```env
-# LLM provider (pick one — default is the no-op provider: no LLM calls)
-# ANTHROPIC_API_KEY=sk-ant-...
-# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
-# GEMINI_API_KEY=...
-# OPENROUTER_API_KEY=...
-# MINIMAX_API_KEY=...
-# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
-# # OpenAI LLM provider (here) AND the OpenAI
-# # embedding provider (further below). Set
-# # OPENAI_API_KEY_FOR_LLM=false to scope it
-# # to embeddings only.
-# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
-# # Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>
-# # Auto-detected from `.openai.azure.com` hostname; uses
-# # api-key header + api-version query param.
-# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
-# OPENAI_MODEL=gpt-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)
+EMBEDDING_PROVIDER=local
+
+# AGENTMEMORY_INJECT_CONTEXT=true
+
+# AGENTMEMORY_AUTO_COMPRESS=true
+
# AGENTMEMORY_TOOLS=core
+
+# AUTO_FORGET_ENABLED=false
+# LESSON_DECAY_ENABLED=false
+# INSIGHT_DECAY_ENABLED=false
```
+完整設定見 [`.env.example`](../.env.example),涵蓋提供者、捕捉篩選、保留策略、儲存和團隊範圍。`AGENTMEMORY_ENV_FILE` 可選擇其他檔案,修改後請重啟。不要提交填有實際值的 `.env` 或 Bearer 密鑰。
+
---
<h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-api.svg"><img src="../assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
-連接埠 `3111` 上有 143 個端點。REST API 預設綁定 `127.0.0.1`。受保護的端點需要 `Authorization: Bearer <secret>`,而網狀同步端點要求兩端都明確設定 `AGENTMEMORY_SECRET`。
+連接埠 `3111` 上有 146 個端點。REST API 預設綁定 `127.0.0.1`。受保護的端點需要 `Authorization: Bearer <secret>`,而網狀同步端點要求兩端都明確設定 `AGENTMEMORY_SECRET`。
-**驗證預設是開啟的。** 當 `AGENTMEMORY_SECRET` 未設定時(無論是在殼層中或 `~/.agentmemory/.env` 中),伺服器會在第一次啟動時產生一個隨機密鑰,並以 `0600` 權限存進 `~/.agentmemory/secret`。每個捆綁的客戶端在與本機伺服器溝通時都會從那裡讀取它:CLI、檢視器、`plugin/scripts` 下的 hooks、MCP 伺服器和 `@agentmemory/mcp` shim、由 `agentmemory connect` 寫入的設定,以及捆綁的 OpenCode、Pi、OpenClaw、Hermes 和檔案系統監看整合。儲存的密鑰只會被送到 loopback 的 URL(`localhost`、`127.0.0.0/8`、`::1`)。明確設定的 `AGENTMEMORY_SECRET` 永遠優先,而遠端客戶端仍需要設定它。Docker 和 `deploy/` 的 entrypoint 已經會自行產生並匯出自己的密鑰。要手動呼叫 API:
+驗證預設開啟。未設定 `AGENTMEMORY_SECRET` 時,CLI 首次啟動會將隨機密鑰儲存到 `~/.agentmemory/secret`,並鏡像到所選資料目錄的 `secret`,權限為 `0600`。內建客戶端連接本機伺服器時優先讀取此共用檔案,只向回環 URL 傳送儲存的密鑰。明確設定的 `AGENTMEMORY_SECRET` 優先;遠端客戶端需透過環境變數設定密鑰。Docker 部署會產生自己的密鑰。
```bash
-curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
+curl -H "Authorization: Bearer <secret-from-data-dir>" http://localhost:3111/agentmemory/health
```
**寫入請求的規則。** 對 REST API 和檢視器發出的 `POST`、`PUT`、`PATCH` 和 `DELETE` 請求,只要帶有主體,就必須送出 `Content-Type: application/json`(可以帶 `charset` 參數);而 `Origin` 標頭,如果存在,就必須是設定的 REST 或檢視器連接埠的 loopback 來源,或是列在 `VIEWER_ALLOWED_ORIGINS` 中(以逗號分隔,例如 `https://memory.example.com`)。不送出 `Origin` 標頭的客戶端(CLI、hooks、MCP、curl、伺服器對伺服器)不受影響。檢視器也接受它自己的來源。
@@ -1814,7 +1413,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `POST` | `/agentmemory/team/share` | 與團隊分享 |
| `GET` | `/agentmemory/audit` | 稽核紀錄 |
-完整端點列表:[`src/triggers/api.ts`](../src/triggers/api.ts)
+完整端點列表:[REST API](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
</details>
@@ -1832,19 +1431,19 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
當伺服器當機、沒有及時回應,或回傳 5xx 時,hook 會把觀測附加到一個本機暫存檔 `<data dir>/capture-spool/<host>-<port>.jsonl`(可用 `AGENTMEMORY_CAPTURE_SPOOL_DIR` 覆寫此目錄)。這個檔案僅限你的使用者存取(權限 600),密鑰的清除方式與伺服器相同,它最多容納 `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`(5 MiB),並丟棄超過 `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`(168)的條目。滿了之後,新的條目會被丟棄並計數,`/agentmemory/status` 會回報這個情況。hook 仍會在其時間限制內以 0 退出,且伺服器健康時不會增加任何請求。暫存會在下次啟動時,以及之後第一個成功連到伺服器的 hook,在背景行程中送出,代理不需要等待。事件 id 讓這一切是安全的:在超時之前就已送達的觀測不會被儲存兩次。`npx @agentmemory/agentmemory capture` 會顯示暫存和伺服器收件匣,`--drain` 會立即送出暫存,`GET /agentmemory/capture` 則以 JSON 回傳同樣的內容。設定 `AGENTMEMORY_CAPTURE_SPOOL=false` 可關閉暫存功能。
-**壓實圖溯源資料。** 每個知識圖譜節點和邊,都只保留它所來自的最新 32 筆觀測的 id。在這個上限出現之前寫入的儲存,每個熱門節點可能持有數千個 id,這會讓圖搜尋和檢視器變慢,甚至讓 worker 掉線。agentmemory 會自行修正這個問題:在升級後的第一次啟動時,它會在背景把每個節點、邊、被取代的邊(時間性的圖歷史)和快取的快照修剪到這個上限,分成小批次執行,批次之間有停頓,讓搜尋、捕捉和檢視器都能持續運作。它會儲存進度,重啟後繼續執行,完成後就不再執行。`/agentmemory/status` 和檢視器的 Health 頁面會顯示它是 pending、running(附上目前的範圍和位置)、done 或 failed。設定 `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` 可關閉它。
+**壓實圖溯源資料。** 舊溯源資料的壓實會在啟動時延後,因為它需要讀取完整的舊作用域。`/agentmemory/status` 顯示 `deferred`,設定 `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` 時顯示 `off`。請在維護期間執行下方的手動壓實。檢索索引遷移是獨立操作:按照[維護指南](../docs/reliability/graph-index-migration.md)使用 `agentmemory graph-index migrate --allow-legacy-scan`。
要手動執行它,呼叫 `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 '{}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -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"}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
+curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
@@ -1858,7 +1457,7 @@ npm test # 4,000+ 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。
+前提條件見[安裝](#install),貢獻規範和發布檢查見 [CONTRIBUTING.md](../CONTRIBUTING.md)。
<h2 id="license"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-license.svg"><img src="../assets/tags/section-license.svg" alt="License" height="32" /></picture></h2>
diff --git a/assets/iii-console/states.png b/assets/iii-console/states.png
deleted file mode 100644
index 7a6f503d..00000000
Binary files a/assets/iii-console/states.png and /dev/null differ
diff --git a/assets/iii-console/traces-waterfall.png b/assets/iii-console/traces-waterfall.png
deleted file mode 100644
index 976c10cc..00000000
Binary files a/assets/iii-console/traces-waterfall.png and /dev/null differ
diff --git a/assets/iii-console/workers.png b/assets/iii-console/workers.png
deleted file mode 100644
index 2ee093c5..00000000
Binary files a/assets/iii-console/workers.png and /dev/null differ
diff --git a/assets/tags/light/section-agents.svg b/assets/tags/light/section-agents.svg
index cff6943d..101df9ef 100644
--- a/assets/tags/light/section-agents.svg
+++ b/assets/tags/light/section-agents.svg
@@ -12,5 +12,5 @@
<rect x="0" y="0" width="320" height="44" rx="8" fill="url(#bg)" stroke="#E5E7EB" stroke-width="1"/>
<rect x="0" y="0" width="6" height="44" rx="3" fill="url(#accent)"/>
<text x="22" y="20" fill="#0F172A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="13" font-weight="800" letter-spacing="2.2" text-rendering="geometricPrecision">WORKS WITH EVERY AGENT</text>
- <text x="22" y="34" fill="#64748B" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="10" font-weight="500" letter-spacing="0.2" text-rendering="geometricPrecision">25 agents · one memory server</text>
-</svg>
\ No newline at end of file
+ <text x="22" y="34" fill="#64748B" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="10" font-weight="500" letter-spacing="0.2" text-rendering="geometricPrecision">Shared memory across agents</text>
+</svg>
diff --git a/assets/tags/section-agents.svg b/assets/tags/section-agents.svg
index fdf4c8f1..ba74deaa 100644
--- a/assets/tags/section-agents.svg
+++ b/assets/tags/section-agents.svg
@@ -12,5 +12,5 @@
<rect x="0" y="0" width="320" height="44" rx="8" fill="url(#bg)" stroke="#2A2A2A" stroke-width="1"/>
<rect x="0" y="0" width="6" height="44" rx="3" fill="url(#accent)"/>
<text x="22" y="20" fill="#FFFFFF" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="13" font-weight="800" letter-spacing="2.2" text-rendering="geometricPrecision">WORKS WITH EVERY AGENT</text>
- <text x="22" y="34" fill="#9CA3AF" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="10" font-weight="500" letter-spacing="0.2" text-rendering="geometricPrecision">25 agents · one memory server</text>
-</svg>
\ No newline at end of file
+ <text x="22" y="34" fill="#9CA3AF" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="10" font-weight="500" letter-spacing="0.2" text-rendering="geometricPrecision">Shared memory across agents</text>
+</svg>
diff --git a/benchmark/capture-costs.ts b/benchmark/capture-costs.ts
index c2292e36..7519e4e9 100644
--- a/benchmark/capture-costs.ts
+++ b/benchmark/capture-costs.ts
@@ -158,7 +158,7 @@ function loadConfig(): Config {
return p;
});
const [outputMin, outputMax] = intList(process.env["BENCH_OUTPUT_BYTES"], [400, 4000]);
- const restPort = intEnv("BENCH_PORT", 4900);
+ const restPort = intEnv("BENCH_REST_PORT", 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;
@@ -548,6 +548,7 @@ interface ProcRow {
rssKiB: number;
cpuSec: number;
comm: string;
+ args: string;
}
function parseCpu(raw: string): number {
@@ -560,12 +561,12 @@ function parseCpu(raw: string): number {
}
async function psRows(): Promise<ProcRow[]> {
- const { stdout } = await execFileAsync("ps", ["-A", "-o", "pid=,ppid=,rss=,time=,comm="], { timeout: 10000, maxBuffer: 8 * 1024 * 1024 });
+ const { stdout } = await execFileAsync("ps", ["-A", "-o", "pid=,ppid=,rss=,time=,comm=,args="], { 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+(.*)$/);
+ const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s*(.*)$/);
if (!m) continue;
- rows.push({ pid: +m[1]!, ppid: +m[2]!, rssKiB: +m[3]!, cpuSec: parseCpu(m[4]!), comm: m[5]! });
+ rows.push({ pid: +m[1]!, ppid: +m[2]!, rssKiB: +m[3]!, cpuSec: parseCpu(m[4]!), comm: m[5]!, args: m[6]! });
}
return rows;
}
@@ -590,8 +591,17 @@ function treeOf(rows: ProcRow[], roots: number[]): ProcRow[] {
return out;
}
-function roleOf(r: ProcRow): "engine" | "worker" | "other" {
+type ProcessRole = "compose" | "engine" | "state" | "http" | "agentmemory" | "worker" | "other";
+
+function roleOf(r: ProcRow): ProcessRole {
const name = basename(r.comm);
+ const args = r.args;
+ if (/\bcompose\s+--namespace\b/.test(args)) return "compose";
+ if (/^iii:e:/.test(name) || (/--config\s/.test(args) && /engine-config\.yaml/.test(args))) return "engine";
+ if (name === "state" || name === "iii-state" || /(?:^|\/)state(?:\s|$)/.test(args) || /\/state-\d[^/]*\/state(?:\s|$)/.test(args)) return "state";
+ if (name === "http" || name === "iii-http" || /(?:^|\/)http(?:\s|$)/.test(args) || /\/http-\d[^/]*\/http(?:\s|$)/.test(args)) return "http";
+ if ((name === "MainThread" || name === "node" || name === "sh") && /dist\/index\.mjs/.test(args)) return "agentmemory";
+ if (/^iii:c:/.test(name) || /\bcompose\s+--namespace\b/.test(args)) return "compose";
if (name === "iii" || name.startsWith("iii")) return "engine";
if (name === "node" || name.includes("node")) return "worker";
return "other";
@@ -601,18 +611,21 @@ interface TreeSample {
totalKiB: number;
engineKiB: number;
workerKiB: number;
+ processKiB: Record<ProcessRole, 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) };
+ const processKiB: Record<ProcessRole, number> = { compose: 0, engine: 0, state: 0, http: 0, agentmemory: 0, worker: 0, other: 0 };
+ const s: TreeSample = { totalKiB: 0, engineKiB: 0, workerKiB: 0, processKiB, 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);
+ s.processKiB[role] += r.rssKiB;
if (role === "engine") s.engineKiB += r.rssKiB;
- else if (role === "worker") s.workerKiB += r.rssKiB;
+ else if (role === "state" || role === "http" || role === "agentmemory" || role === "worker") s.workerKiB += r.rssKiB;
}
return s;
}
@@ -622,6 +635,7 @@ interface RssWindow {
peakTotalKiB: number;
peakEngineKiB: number;
peakWorkerKiB: number;
+ peakProcessKiB: Record<ProcessRole, number>;
meanTotalKiB: number;
cpuSecStart: number;
cpuSecEnd: number;
@@ -647,6 +661,7 @@ class RssSampler {
peakTotalKiB: first.totalKiB,
peakEngineKiB: first.engineKiB,
peakWorkerKiB: first.workerKiB,
+ peakProcessKiB: { ...first.processKiB },
meanTotalKiB: first.totalKiB,
cpuSecStart: first.cpuSec,
cpuSecEnd: first.cpuSec,
@@ -666,6 +681,9 @@ class RssSampler {
w.peakTotalKiB = Math.max(w.peakTotalKiB, s.totalKiB);
w.peakEngineKiB = Math.max(w.peakEngineKiB, s.engineKiB);
w.peakWorkerKiB = Math.max(w.peakWorkerKiB, s.workerKiB);
+ for (const [role, value] of Object.entries(s.processKiB) as Array<[ProcessRole, number]>) {
+ w.peakProcessKiB[role] = Math.max(w.peakProcessKiB[role], value);
+ }
w.cpuSecEnd = Math.max(w.cpuSecEnd, s.cpuSec);
} catch {
} finally {
@@ -976,7 +994,7 @@ class Harness {
}
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]) {
+ for (const port of [this.cfg.restPort, this.cfg.restPort + 2, this.cfg.restPort + 6353, 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`);
@@ -1006,18 +1024,45 @@ class Harness {
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"))) {
+ const logs = `${readFileSync(logPath, "utf8")}\n${this.composeWorkerLogText()}`;
+ if (/Rebuilt BM25 index from stored content/.test(logs)) {
indexReadyMs = performance.now() - t0;
break;
}
+ try {
+ const status = await http(this.base, "GET", "/status", undefined, 2000);
+ if (status.status === 200) {
+ indexReadyMs = performance.now() - t0;
+ break;
+ }
+ } catch {}
await sleep(100);
}
await this.adoptTree();
- return { readyMs: Math.round(readyMs), indexReadyMs: indexReadyMs === null ? null : Math.round(indexReadyMs), boot: parseBootLog(readFileSync(logPath, "utf8")) };
+ return { readyMs: Math.round(readyMs), indexReadyMs: indexReadyMs === null ? null : Math.round(indexReadyMs), boot: parseBootLog(`${readFileSync(logPath, "utf8")}\n${this.composeWorkerLogText()}`) };
}
bootLog(): BootLog | null {
- return this.lastLogPath && existsSync(this.lastLogPath) ? parseBootLog(readFileSync(this.lastLogPath, "utf8")) : null;
+ return this.lastLogPath && existsSync(this.lastLogPath) ? parseBootLog(`${readFileSync(this.lastLogPath, "utf8")}\n${this.composeWorkerLogText()}`) : null;
+ }
+
+ private composeWorkerLogText(): string {
+ const root = join(this.dataDir, "compose-state");
+ const logs: string[] = [];
+ const visit = (dir: string) => {
+ if (!existsSync(dir)) return;
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) visit(path);
+ else if (entry.name === "agentmemory.log") {
+ try {
+ logs.push(readFileSync(path, "utf8").split(/\r?\n/).map((line) => line.replace(/^(?:stdout|stderr)\t/, "")).join("\n"));
+ } catch {}
+ }
+ }
+ };
+ visit(root);
+ return logs.join("\n");
}
private spoolFiles(): string[] {
@@ -1071,7 +1116,7 @@ class Harness {
private async waitPortsFree(timeoutMs: number): Promise<void> {
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));
+ const busy = await Promise.all([this.cfg.restPort, this.cfg.restPort + 2, this.cfg.restPort + 6353, this.cfg.enginePort].map(portOpen));
if (!busy.some(Boolean)) return;
await sleep(250);
}
@@ -1493,7 +1538,7 @@ async function runOne(cfg: Config, profile: Profile, n: number, fake: FakeProvid
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["coldStart"] = { ...cold, rssKiB: { total: idleEmpty.totalKiB, engine: idleEmpty.engineKiB, worker: idleEmpty.workerKiB, processes: idleEmpty.processKiB } };
out["diskFixed"] = baseline;
const rng = mulberry32(cfg.seed);
@@ -1561,7 +1606,7 @@ async function runOne(cfg: Config, profile: Profile, n: number, fake: FakeProvid
observeErrors,
observeErrorSamples: errorSamples,
deduplicatedResponses: deduplicated,
- rss: { peakTotalKiB: kib(captureRss.peakTotalKiB), peakEngineKiB: kib(captureRss.peakEngineKiB), peakWorkerKiB: kib(captureRss.peakWorkerKiB), meanTotalKiB: captureRss.meanTotalKiB, samples: captureRss.samples },
+ rss: { peakTotalKiB: kib(captureRss.peakTotalKiB), peakEngineKiB: kib(captureRss.peakEngineKiB), peakWorkerKiB: kib(captureRss.peakWorkerKiB), peakProcessKiB: captureRss.peakProcessKiB, meanTotalKiB: captureRss.meanTotalKiB, samples: captureRss.samples },
cpuSec: captureRss.cpuSec,
provider: diffCounters(before, afterCapture),
};
@@ -1569,7 +1614,7 @@ async function runOne(cfg: Config, profile: Profile, n: number, fake: FakeProvid
log("idle");
await sleep(5000);
const idle = await h.sampler.sampleOnce();
- out["idle"] = { rssKiB: { total: idle.totalKiB, engine: idle.engineKiB, worker: idle.workerKiB } };
+ out["idle"] = { rssKiB: { total: idle.totalKiB, engine: idle.engineKiB, worker: idle.workerKiB, processes: idle.processKiB } };
out["diskAfterCapture"] = q.disk;
out["diskGrowth"] = diskDelta(baseline, q.disk);
out["diskGrowthPerObservationBytes"] = n > 0 ? Math.round(diskDelta(baseline, q.disk).totalBytes / n) : null;
@@ -1602,7 +1647,7 @@ async function runOne(cfg: Config, profile: Profile, n: number, fake: FakeProvid
reEmbedRequests: recProvider.embedRequests,
reEmbeddedInputs: recProvider.embedInputs,
provider: recProvider,
- rss: { peakTotalKiB: recRss.peakTotalKiB, idleTotalKiB: recIdle.totalKiB, idleEngineKiB: recIdle.engineKiB, idleWorkerKiB: recIdle.workerKiB },
+ rss: { peakTotalKiB: recRss.peakTotalKiB, idleTotalKiB: recIdle.totalKiB, idleEngineKiB: recIdle.engineKiB, idleWorkerKiB: recIdle.workerKiB, peakProcessKiB: recRss.peakProcessKiB, idleProcessKiB: recIdle.processKiB },
cpuSec: recRss.cpuSec,
disk: rq.disk,
};
@@ -1615,7 +1660,7 @@ async function runOne(cfg: Config, profile: Profile, n: number, fake: FakeProvid
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 } };
+ out["warmStart"] = { ...warm, provider: diffCounters(warmBefore, fake.snapshot()), rssKiB: { total: warmIdle.totalKiB, engine: warmIdle.engineKiB, worker: warmIdle.workerKiB, processes: warmIdle.processKiB } };
await h.stop();
out["diskFinal"] = await settledDisk(h.dataDir, 2000, 20000);
} catch (err) {
@@ -1669,11 +1714,12 @@ function markdown(report: Record<string, unknown>): string {
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("|---|---|---|---|---|---|---|---|---|---|");
+ lines.push("", "### Resident memory and CPU (iii Compose process tree)", "");
+ lines.push("| profile | N | empty idle | capture peak | engine peak | Compose | state | http | agentmemory | 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"} |`);
+ const role = (name: ProcessRole) => fmtKiB(get(r, `capture.rss.peakProcessKiB.${name}`));
+ lines.push(`| ${r["profile"]} | ${r["observations"]} | ${fmtKiB(get(r, "coldStart.rssKiB.total"))} | ${fmtKiB(get(r, "capture.rss.peakTotalKiB"))} | ${fmtKiB(get(r, "capture.rss.peakEngineKiB"))} | ${role("compose")} | ${role("state")} | ${role("http")} | ${role("agentmemory")} | ${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 |");
@@ -1829,7 +1875,7 @@ async function main(): Promise<void> {
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 },
+ ports: { rest: cfg.restPort, viewer: cfg.restPort + 2, metrics: cfg.restPort + 6353, engine: cfg.enginePort, fakeProvider: cfg.fakePort },
},
runs,
};
diff --git a/deploy/Dockerfile b/deploy/Dockerfile
new file mode 100644
index 00000000..d09589a7
--- /dev/null
+++ b/deploy/Dockerfile
@@ -0,0 +1,59 @@
+# Shared build for local Compose and every deployment platform.
+# Update these four pins together when promoting the runtime.
+ARG III_VERSION=0.25.0
+ARG STATE_VERSION=0.22.20
+ARG HTTP_VERSION=0.22.7
+
+FROM node:24-slim AS agent-build
+ARG III_VERSION
+WORKDIR /opt/agentmemory
+COPY package.json ./package.json
+RUN npm install --no-fund --no-audit --package-lock=false
+COPY . .
+RUN npm run build \
+ && npm prune --omit=dev --omit=optional --no-fund --no-audit
+
+FROM iiidev/iii:${III_VERSION} AS iii-engine
+
+FROM node:24-slim
+ARG III_VERSION
+ARG STATE_VERSION
+ARG HTTP_VERSION
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates gosu tini \
+ && apt-get clean \
+ && find /var/lib/apt/lists -mindepth 1 -delete
+
+COPY --from=iii-engine /app/iii /usr/local/bin/iii
+RUN iii --version 2>&1 | grep -qF "${III_VERSION}" \
+ || { echo "iiidev/iii:${III_VERSION} does not contain iii ${III_VERSION}" >&2; exit 1; }
+
+WORKDIR /opt/agentmemory
+COPY --from=agent-build /opt/agentmemory/package.json ./package.json
+COPY --from=agent-build /opt/agentmemory/node_modules ./node_modules
+COPY --from=agent-build /opt/agentmemory/dist ./dist
+COPY deploy/runtime/agentmemory.worker.yaml /opt/agentmemory/iii.worker.yaml
+COPY deploy/runtime/worker-compose.yaml /opt/agentmemory/worker-compose.yaml
+RUN chmod 644 /opt/agentmemory/worker-compose.yaml /opt/agentmemory/iii.worker.yaml \
+ && chown -R node:node /opt/agentmemory
+COPY --chmod=0755 deploy/runtime/entrypoint.sh /usr/local/bin/agentmemory-entrypoint
+
+ENV III_VERSION=${III_VERSION} \
+ STATE_VERSION=${STATE_VERSION} \
+ HTTP_VERSION=${HTTP_VERSION} \
+ AGENTMEMORY_DATA_DIR=/data \
+ HOME=/data/home \
+ III_COMPOSE_STATE_DIR=/data/compose-state \
+ III_ENGINE_PORT=49134 \
+ III_REST_PORT=3111 \
+ III_VIEWER_PORT=3113 \
+ III_TELEMETRY_ENABLED=false \
+ MALLOC_ARENA_MAX=2
+
+EXPOSE 3111 3113
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+ CMD ["node", "-e", "fetch('http://127.0.0.1:3111/agentmemory/livez').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/agentmemory-entrypoint"]
diff --git a/deploy/README.md b/deploy/README.md
index dc96076a..1c1e4ee5 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -1,118 +1,57 @@
-# One-click deploy templates
-
-Stand up agentmemory on managed infrastructure without rolling your own
-Docker host. Each template ships a self-contained Dockerfile that pulls
-`@agentmemory/agentmemory` from npm at build time and copies the iii
-engine binary in from the official `iiidev/iii` image — no pre-built
-agentmemory image required. Storage mounts at `/data`; an HMAC secret
-is generated by the first-boot entrypoint and persisted to the volume.
-The entrypoint overwrites the npm-bundled iii config with a
-deploy-tuned one that binds `0.0.0.0` and uses absolute `/data` paths,
-then drops privileges from `root` to `node` via `gosu` before
-exec'ing the agentmemory CLI.
-
-| Platform | Pitch | Cost floor |
-|----------|-------|------------|
-| [fly.io](./fly/README.md) | Single machine with auto-stop. Cheapest idle cost on a managed host; cold-start on first request after sleep. | ~$0.15/month at full idle |
-| [Railway](./railway/README.md) | Push from GitHub, volume in the dashboard. Easiest managed dashboard flow. | $5/month (Hobby plan flat fee) |
-| [Render](./render/README.md) | Blueprint-driven; persistent disk attaches automatically. Most "set it and forget it." | $7.25/month (Starter web + 1 GB disk) |
-| [Coolify](./coolify/README.md) | Self-hosted on your own VPS. Same Docker Compose stack, you own the host and the data. | VPS cost only (Hetzner CX22 ~€3.79/month) |
-
-## What every template guarantees
-
-- **Volume mounted at `/data`.** Matches the path the engine has used
- since v0.9.10.
-- **HMAC secret generated on first boot** via `openssl rand -hex 32`,
- written to `/data/.hmac` with `chmod 600`, and printed to stdout
- exactly once so the operator can capture it from the deploy logs.
- Subsequent boots load the secret from the file. The secret is never
- committed to a config file or set as a platform env var.
-- **Only port 3111 is exposed publicly.** The viewer on port 3113
- stays bound to the container's localhost. Reach it via SSH tunnel
- (see each platform's README).
-- **TLS upstream of the container.** Every managed platform terminates
- TLS at its edge proxy; the templates publish a single internal port
- (`3111`) to that proxy, never to the host. Integration plugins
- configured with `AGENTMEMORY_REQUIRE_HTTPS=1` will refuse to send the
- bearer over plaintext HTTP to a non-loopback host, so a
- misconfigured TLS layer fails loud instead of silently leaking the
- secret.
-
-## Pick a platform
-
-- Pick **fly.io** if you want the lowest idle cost and don't mind a
- cold-start latency hit on the first request after sleep.
-- Pick **Railway** if you want a clicky dashboard flow and a flat
- monthly bill.
-- Pick **Render** if you want the most "set it and forget it"
- Blueprint flow with automatic disk snapshots on paid plans.
-- Pick **Coolify** if you already run a VPS and want a self-hosted
- control plane — same Docker Compose stack, no third-party host has
- your memories.
-
-All four give you the same agentmemory API at the same port (3111)
-with the same auth model. Migrating between them later is a `tar` of
-`/data` and a re-import — see each platform's README for the exact
-commands.
-
-## Optional: LLM + embedding provider keys
-
-Every template runs out of the box without any LLM or embedding key —
-search falls back to BM25-only mode and synthetic (zero-LLM)
-compression keeps memories indexable. To unlock LLM-powered
-compression and hybrid (BM25 + vector) recall, add one of the
-following to your platform's environment variables (Fly:
-`flyctl secrets set`; Railway / Render / Coolify: dashboard
-*Variables / Environment* tab):
-
-| Variable | Purpose |
-|---------------------------|----------------------------------------------------------|
-| `ANTHROPIC_API_KEY` | LLM-backed compression + summarization |
-| `GEMINI_API_KEY` | LLM provider alternative |
-| `OPENROUTER_API_KEY` | LLM provider alternative |
-| `OPENAI_API_KEY` | Embedding provider (text-embedding-3-small by default) |
-| `VOYAGE_API_KEY` | Embedding provider alternative |
-| `AGENTMEMORY_AUTO_COMPRESS=true` | Run LLM compression on every observation batch |
-| `AGENTMEMORY_INJECT_CONTEXT=true` | Inject recalled memories back into agent prompts |
-
-The defaults are intentionally conservative: provider keys default to
-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:
+# Docker deployments
+agentmemory 0.9.30 runs on iii 0.25.0 with the `state` 0.22.20 and `http` 0.22.7 registry workers. All image builds use one [`Dockerfile`](Dockerfile), with engine and registry worker pins declared once. Update those build arguments together when promoting a release. Workers are fetched from the iii registry at startup; the `worker-compose.yaml` uses the same Worker Compose format as the CLI.
+
+The container runs `iii compose --up`: Compose owns the engine and supervises `state`, `http`, and the local `agentmemory` worker. There is no legacy embedded engine config, standalone stream, pubsub, or queue worker. The registry worker artifacts are pinned in the compose manifest. Engine and worker state, agentmemory state, generated secret, Compose cache, and logs live on the persistent `/data` volume. For Docker Compose, the volume key is `iii-data`, normally stored as `<compose-project>_iii-data`; set `AGENTMEMORY_DATA_DIR` to a host path to use a bind mount instead. The state worker continues to use `/data/state_store.db`, so the existing 0.22.1 file-based store is read in place without conversion or deletion.
+
+## Ports
+
+| Container port | Service | Use |
+|---|---|---|
+| `3111` | HTTP worker | REST API and authenticated SSE at `/agentmemory/viewer/events` |
+| `3113` | agentmemory viewer | Browser UI and its authenticated REST proxy |
+| `49134` | iii engine | Internal worker WebSocket; never publish it |
+
+There is no stream/WebSocket viewer port. REST CORS defaults to `http://localhost` and `http://127.0.0.1` on both the REST and viewer ports; set `REST_ALLOWED_ORIGINS` to a comma-separated list of exact origins when a trusted browser origin needs access. Keep the viewer behind TLS and set `VIEWER_ALLOWED_HOSTS` to the exact inbound `Host` values (with port where present) and `VIEWER_ALLOWED_ORIGINS` to its browser origins. It requires `AGENTMEMORY_SECRET` for API proxy calls; the viewer prompts for the bearer and keeps it in session storage. The engine worker manager listens only on `127.0.0.1:49134` inside the container; do not expose the engine port.
+
+`III_VERSION`, `STATE_VERSION`, and `HTTP_VERSION` are Docker build arguments; Compose passes their shell or `.env` values through to the shared Dockerfile. `AGENTMEMORY_VERSION` does not select a package version: the application code is built from the checked-out repository, so choose an agentmemory release by checking out its tag/commit and rebuilding. Platform deployments use the code revision selected for that service.
+
+Local Compose binds REST and viewer to loopback. Example with test ports:
+
+```bash
+AGENTMEMORY_REST_PORT=3611 AGENTMEMORY_VIEWER_PORT=3613 docker compose up --build -d
```
-machine image prepared : 5.1 s
-volume mount + format : 2.5 s
-firecracker boot : 1.0 s
-entrypoint + chown : 0.5 s
-iii-engine ready : 3.0 s
-agentmemory worker reg : 2.0 s
-─────────────────────────────────
-healthcheck passes : ~9-10 s
+
+Open `http://127.0.0.1:3613`, use the persisted secret in `docker compose exec agentmemory cat /data/secret`, and stop with `docker compose down`. `docker compose down -v` deletes the memories and secret. Set `AGENTMEMORY_SECRET` to provide an explicit REST bearer. To use Redis for state, set `AGENTMEMORY_STATE_BACKEND=redis` and `AGENTMEMORY_REDIS_URL=redis://...`; otherwise the persistent file-backed store is used.
+
+## Platform templates
+
+- [Fly.io](fly/README.md) — separate HTTPS listeners for REST (`3111`) and the bearer-protected viewer (`8443` externally → `3113` internally); a 1 GB persistent volume.
+- [Railway](railway/README.md) — REST is the default public HTTP service; add a TCP proxy for viewer port `3113` if needed.
+- [Render](render/README.md) — REST Web Service with a persistent disk; viewer is reachable only from an SSH tunnel unless you add a separately protected proxy.
+- [Coolify](coolify/README.md) — both container ports are exposed only to the proxy network; use the Coolify domain with TLS and bearer authorization.
+
+For any public viewer host, configure the allowed host/origin values to the actual domain. Do not publish a bearer-protected viewer over plain HTTP on an untrusted network. The viewer page itself is public; data/API proxy requests require the bearer.
+
+## Updating and backing up
+
+Change the pins in `deploy/Dockerfile`, rebuild and redeploy, and keep the platform's `/data` volume attached. Back up `/data` before upgrades and before any `down -v`, volume deletion, or secret rotation. The worker cache and engine configuration persist alongside state so restarts do not lose data.
+
+### Migrating from the legacy CLI Docker mode
+
+The current CLI does not start or manage Docker deployments. When a current CLI encounters a legacy Docker lifecycle record, it preserves that record and prints the exact `docker stop ...` command; execute the printed command to stop the old container, then leave the preserved metadata intact. Do not start the new container against the data volume while the old engine still has it mounted.
+
+Keep the old deployment's persistent data volume (normally `iii-data`) or copy the old `/data` contents to a backed-up bind mount. The state worker reads the existing `/data/state_store.db` tree in place; no database export/import is needed. The previous runtime initialized the full volume as UID/GID `65532:65532`; this image performs a one-time recursive ownership migration to `node:node` (UID/GID 1000) and writes `/data/.ownership-migrated-node-v1`. Do not run the old image against the volume after that migration. Back up the whole volume before starting the new image.
+
+The previous platform entrypoints persisted the generated bearer secret at `/data/.hmac`. If no explicit secret or current secret file exists, the entrypoint copies that legacy value to `/data/secret` with mode `0600`; the server then initializes the canonical client credential from it. An explicitly configured `AGENTMEMORY_SECRET` takes precedence and is not written to disk.
+
+Reuse the old Compose project name with `docker compose -p <old-project> up --build -d`. If the old volume has a different name, first inspect it with `docker volume ls` and `docker volume inspect <existing-volume>`, then create `compose.existing-volume.yaml`:
+
+```yaml
+volumes:
+ iii-data:
+ external: true
+ name: <existing-volume>
```
-Every template's health-check `grace_period` (or compose
-`start_period`) is set to 30 s for a 3x safety margin. Tune lower
-once you've measured your own platform's image-pull characteristics.
+With `AGENTMEMORY_DATA_DIR` unset so the service uses the named volume, run `docker compose -f docker-compose.yml -f compose.existing-volume.yaml config` and confirm the resolved volume name before starting with the same `-f` arguments and `up --build -d`. The external declaration fails if that volume is missing rather than creating an empty replacement. Check `/agentmemory/livez`, confirm the old and new memories, and use the same project and file arguments with `down` to stop it. Avoid `down -v` unless deleting that data is intended.
diff --git a/deploy/coolify/Dockerfile b/deploy/coolify/Dockerfile
deleted file mode 100644
index 62105fcb..00000000
--- a/deploy/coolify/Dockerfile
+++ /dev/null
@@ -1,36 +0,0 @@
-ARG III_VERSION=0.22.1
-
-FROM iiidev/iii:${III_VERSION} AS iii-image
-
-FROM node:22-slim
-
-ARG AGENTMEMORY_VERSION=0.9.30
-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
-
-ENV AGENTMEMORY_III_VERSION=${III_VERSION} \
- TINI_SUBREAPER=1
-
-COPY --chmod=0755 entrypoint.sh /usr/local/bin/agentmemory-entrypoint.sh
-
-EXPOSE 3111
-
-HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
- CMD curl -fsS http://127.0.0.1:3111/agentmemory/livez || exit 1
-
-ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/agentmemory-entrypoint.sh"]
diff --git a/deploy/coolify/README.md b/deploy/coolify/README.md
index feec4757..1c585e06 100644
--- a/deploy/coolify/README.md
+++ b/deploy/coolify/README.md
@@ -1,132 +1,13 @@
-# Deploy agentmemory on Coolify
+# Coolify
-[Coolify](https://coolify.io/self-hosted) is an open-source, self-hosted
-Heroku/Render alternative that you run on your own VPS. This template
-deploys agentmemory as a Coolify *Application* backed by a Docker
-Compose stack — Coolify handles TLS termination, persistent volume
-provisioning, log aggregation, and the deploy webhook for you.
+Create a Docker Compose application from `rohitg00/agentmemory`, with base directory `.` and Compose path `deploy/coolify/docker-compose.yml`. The Compose manifest builds the shared `deploy/Dockerfile` from the repository root. Set the public REST domain to container port `3111`. The service attaches a persistent `agentmemory-data` volume at `/data`; its health check is `/agentmemory/livez`.
-## What you get
+For browser access, add a second Coolify domain to container port `3113`, enable TLS, and set `VIEWER_ALLOWED_HOSTS` and `VIEWER_ALLOWED_ORIGINS` to the exact domain, origin, and proxy Host header port (for a standard HTTPS domain, use the public host as the `Host` and `https://` origin). The viewer page is public, but viewer API proxy requests require the bearer secret, entered in the viewer prompt. Do not route the iii engine WebSocket (`49134`) publicly.
-- A public HTTPS endpoint serving the agentmemory REST API behind
- Coolify's built-in Traefik/Caddy proxy. The container port (`3111`)
- is exposed to the proxy network only — never bound to the host — so
- TLS termination and domain routing stay under proxy control.
-- A persistent Docker volume backing `/data` for memories, BM25 index,
- and stream backlog. Coolify auto-prefixes the volume name with the
- application's UUID so the data survives redeploys.
-- An HTTP health-check at `/agentmemory/livez` declared in the
- Dockerfile (`HEALTHCHECK` directive). Coolify reuses it for
- rolling-deploy decisions.
-
-## One-time setup
-
-1. **Open your Coolify dashboard** and click **+ New → Application**.
-2. **Source**: pick *Public Repository*. Paste:
- ```
- https://github.com/rohitg00/agentmemory
- ```
- Branch: `main`.
-3. **Build Pack**: select *Docker Compose*.
-4. **Base Directory**: `deploy/coolify`
-5. **Compose Path**: `docker-compose.yml`
-6. Click **Save**, then on the application settings screen set a
- **Domain** in the form `https://<your-fqdn>:3111` (the `:3111`
- suffix tells Coolify's proxy which container port to forward to;
- it still serves over 443/80 publicly).
-7. Click **Deploy**.
-
-That's it. Coolify clones the repo, builds the Dockerfile under
-`deploy/coolify/`, provisions the `agentmemory-data` named volume on
-the host, attaches Traefik (or Caddy) for the public domain, and starts
-the service. The container is reachable only through the proxy — there
-is no published host port.
-
-## Capture the HMAC secret
-
-Once the deploy logs show the service is up, open the application's
-**Logs** tab in Coolify and search for `AGENTMEMORY_SECRET=`. You will
-see exactly one line of the form `AGENTMEMORY_SECRET=<64 hex chars>`.
-Copy it into your client environment (`~/.bashrc`, Claude Desktop
-config, etc.). The secret is never printed again on subsequent boots.
-
-## Verify the deployment
-
-```bash
-curl "https://<your-coolify-domain>/agentmemory/livez"
-# {"status":"ok"}
-```
-
-For an authenticated call, your client must send
-`Authorization: Bearer <secret>`.
-
-## Viewer access (port 3113 stays internal)
-
-The viewer port is not exposed by the compose file on purpose — it
-holds the unauthenticated admin surface in older releases and the
-proxied surface in current ones, neither of which belongs on the open
-internet. Two paths to reach it:
-
-**Option A — SSH tunnel from the Coolify host.** Coolify gives you SSH
-access to the underlying VPS. From your laptop:
+Read the generated secret from the persistent volume (the value persists across container restarts):
```bash
-ssh -L 3113:127.0.0.1:3113 <user>@<coolify-host>
-# inside the SSH session, find the container:
-docker ps --filter name=agentmemory --format "{{.Names}}"
-# tunnel into the container's port from the host:
-docker exec -it <container-name> sh -c "curl http://localhost:3113"
+docker compose exec agentmemory cat /data/secret
```
-Cleaner version: bind the container's 3113 to the host's loopback by
-adding `- "127.0.0.1:3113:3113"` to the `ports:` block in
-`docker-compose.yml`, redeploy, then `ssh -L 3113:127.0.0.1:3113
-<user>@<host>` is enough.
-
-**Option B — expose 3113 as a second Coolify domain protected by HTTP
-basic auth.** Coolify's per-service routing supports adding a second
-public endpoint with basic-auth middleware. Useful if you want to
-share the viewer with a teammate without giving them SSH.
-
-## Rotate the HMAC secret
-
-```bash
-ssh <user>@<coolify-host>
-docker exec -it <container-name> sh -c "rm /data/.hmac"
-exit
-```
-
-Then click **Redeploy** in the Coolify dashboard. The next boot prints
-a fresh secret to the logs.
-
-## Back up `/data`
-
-Coolify exposes the named volume on the host filesystem under
-`/var/lib/docker/volumes/<project-id>_agentmemory-data/_data`. Back it
-up with your existing host-level snapshot tooling (Restic, Borg,
-`rsync`, BTRFS snapshots, etc.) or via Coolify's built-in *Backups*
-feature for Docker volumes.
-
-## Cost floor and resources
-
-- **Hardware**: the agentmemory container idles at ~150 MB RSS, climbs
- to ~400 MB under steady traffic. The bundled iii engine adds another
- ~80 MB. A 1 vCPU / 1 GB VPS is comfortably enough for a personal
- install.
-- **VPS providers commonly paired with Coolify**: Hetzner CX22
- (~€3.79/month), DigitalOcean Basic Droplet ($6/month), Vultr Cloud
- Compute ($6/month). Coolify itself is free.
-- **Volume storage**: tied to whatever block storage the VPS provides;
- typically pennies per GB-month.
-
-## Known caveats
-
-- The Dockerfile builds on the Coolify host on every deploy. First
- deploy takes ~2 minutes; cached layers shrink subsequent rebuilds to
- under 30 seconds. Pin `AGENTMEMORY_VERSION` and `III_VERSION` in
- `docker-compose.yml`'s `build.args` block to lock a specific release.
-- Coolify's *Persistent Storage* tab will show `agentmemory-data` as a
- managed volume — do not delete it from the dashboard if you want
- your memories to survive a redeploy.
-- arm64 hosts work — the iii binary selection in the Dockerfile uses
- `uname -m` and downloads the matching tarball.
+Back up the `/data` volume before redeploys or secret rotation. `docker compose down -v` deletes all agentmemory data. Version pins are build arguments in the shared [`deploy/Dockerfile`](../Dockerfile); override them in the Compose build args only when upgrading the runtime as a set.
diff --git a/deploy/coolify/docker-compose.yml b/deploy/coolify/docker-compose.yml
index 62c078ac..a229cb76 100644
--- a/deploy/coolify/docker-compose.yml
+++ b/deploy/coolify/docker-compose.yml
@@ -1,24 +1,136 @@
services:
agentmemory:
build:
- context: .
- dockerfile: Dockerfile
- args:
- AGENTMEMORY_VERSION: "0.9.30"
- III_VERSION: "0.22.1"
- III_SDK_VERSION: "0.22.1"
+ context: ../..
+ dockerfile: deploy/Dockerfile
restart: unless-stopped
environment:
- SERVICE_FQDN_AGENTMEMORY_3111: ${SERVICE_FQDN_AGENTMEMORY_3111}
+ AGENTMEMORY_DATA_DIR: /data
+ HOME: /data/home
+ III_COMPOSE_STATE_DIR: /data/compose-state
+ III_TELEMETRY_ENABLED: "false"
+ AGENTMEMORY_VIEWER_HOST: 0.0.0.0
+ SERVICE_FQDN_AGENTMEMORY_3111: "${SERVICE_FQDN_AGENTMEMORY_3111:-}"
+ SERVICE_FQDN_AGENTMEMORY_3113: "${SERVICE_FQDN_AGENTMEMORY_3113:-}"
+ VIEWER_ALLOWED_HOSTS: "${VIEWER_ALLOWED_HOSTS:-localhost:3113,127.0.0.1:3113,[::1]:3113}"
+ VIEWER_ALLOWED_ORIGINS: "${VIEWER_ALLOWED_ORIGINS:-http://localhost:3113,http://127.0.0.1:3113}"
+ EMBEDDING_PROVIDER: "${EMBEDDING_PROVIDER:-}"
+ OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
+ OPENAI_API_KEY_FOR_LLM: "${OPENAI_API_KEY_FOR_LLM:-}"
+ OPENAI_BASE_URL: "${OPENAI_BASE_URL:-}"
+ OPENAI_MODEL: "${OPENAI_MODEL:-}"
+ OPENAI_EMBEDDING_API_KEY: "${OPENAI_EMBEDDING_API_KEY:-}"
+ OPENAI_EMBEDDING_BASE_URL: "${OPENAI_EMBEDDING_BASE_URL:-}"
+ OPENAI_EMBEDDING_MODEL: "${OPENAI_EMBEDDING_MODEL:-}"
+ OPENAI_EMBEDDING_DIMENSIONS: "${OPENAI_EMBEDDING_DIMENSIONS:-}"
+ ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+ ANTHROPIC_BASE_URL: "${ANTHROPIC_BASE_URL:-}"
+ ANTHROPIC_MODEL: "${ANTHROPIC_MODEL:-}"
+ GEMINI_API_KEY: "${GEMINI_API_KEY:-}"
+ GEMINI_MODEL: "${GEMINI_MODEL:-}"
+ GOOGLE_API_KEY: "${GOOGLE_API_KEY:-}"
+ VOYAGE_API_KEY: "${VOYAGE_API_KEY:-}"
+ VOYAGE_MODEL: "${VOYAGE_MODEL:-}"
+ COHERE_API_KEY: "${COHERE_API_KEY:-}"
+ COHERE_MODEL: "${COHERE_MODEL:-}"
+ OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:-}"
+ OPENROUTER_MODEL: "${OPENROUTER_MODEL:-}"
+ MINIMAX_API_KEY: "${MINIMAX_API_KEY:-}"
+ MINIMAX_MODEL: "${MINIMAX_MODEL:-}"
+ OLLAMA_HOST: "${OLLAMA_HOST:-}"
+ LLM_PROVIDER: "${LLM_PROVIDER:-}"
+ BM25_WEIGHT: "${BM25_WEIGHT:-}"
+ VECTOR_WEIGHT: "${VECTOR_WEIGHT:-}"
+ MAX_TOKENS: "${MAX_TOKENS:-}"
+ TOKEN_BUDGET: "${TOKEN_BUDGET:-}"
+ MAX_OBS_PER_SESSION: "${MAX_OBS_PER_SESSION:-}"
+ CONSOLIDATION_ENABLED: "${CONSOLIDATION_ENABLED:-}"
+ GRAPH_EXTRACTION_ENABLED: "${GRAPH_EXTRACTION_ENABLED:-}"
+ AGENTMEMORY_AUTO_COMPRESS: "${AGENTMEMORY_AUTO_COMPRESS:-}"
+ AGENTMEMORY_INJECT_CONTEXT: "${AGENTMEMORY_INJECT_CONTEXT:-}"
+ AGENTMEMORY_ALLOW_AGENT_SDK: "${AGENTMEMORY_ALLOW_AGENT_SDK:-}"
+ AGENTMEMORY_SESSION_SWEEP_ENABLED: "${AGENTMEMORY_SESSION_SWEEP_ENABLED:-}"
+ AGENTMEMORY_SESSION_SWEEP_STALE_HOURS: "${AGENTMEMORY_SESSION_SWEEP_STALE_HOURS:-}"
+ AGENTMEMORY_FINALIZE_IDLE_MS: "${AGENTMEMORY_FINALIZE_IDLE_MS:-}"
+ AGENTMEMORY_GRAPH_COMPACT_ON_BOOT: "${AGENTMEMORY_GRAPH_COMPACT_ON_BOOT:-}"
+ AGENTMEMORY_DROP_STALE_INDEX: "${AGENTMEMORY_DROP_STALE_INDEX:-}"
+ AGENTMEMORY_AUDIT_RETENTION_MONTHS: "${AGENTMEMORY_AUDIT_RETENTION_MONTHS:-}"
+ AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES: "${AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES:-}"
+ AGENTMEMORY_STATE_BACKEND: "${AGENTMEMORY_STATE_BACKEND:-}"
+ AGENTMEMORY_REDIS_URL: "${AGENTMEMORY_REDIS_URL:-}"
+ AGENTMEMORY_STATE_SAVE_INTERVAL_MS: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-}"
+ AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"
+ AGENT_ID: "${AGENT_ID:-}"
+ TEAM_ID: "${TEAM_ID:-}"
+ TEAM_MODE: "${TEAM_MODE:-}"
+ USER_ID: "${USER_ID:-}"
+ AGENTMEMORY_AGENT_SCOPE: "${AGENTMEMORY_AGENT_SCOPE:-}"
+ SNAPSHOT_DIR: "${SNAPSHOT_DIR:-}"
+ SNAPSHOT_ENABLED: "${SNAPSHOT_ENABLED:-}"
+ SNAPSHOT_INTERVAL: "${SNAPSHOT_INTERVAL:-}"
+ STANDALONE_PERSIST_PATH: "${STANDALONE_PERSIST_PATH:-}"
+ CLAUDE_MEMORY_BRIDGE: "${CLAUDE_MEMORY_BRIDGE:-}"
+ CLAUDE_MEMORY_LINE_BUDGET: "${CLAUDE_MEMORY_LINE_BUDGET:-}"
+ CLAUDE_PROJECT_PATH: "${CLAUDE_PROJECT_PATH:-}"
+ AGENTMEMORY_SUPPRESS_COST_WARNING: "${AGENTMEMORY_SUPPRESS_COST_WARNING:-}"
+ AGENTMEMORY_TOOLS: "${AGENTMEMORY_TOOLS:-}"
+ FALLBACK_PROVIDERS: "${FALLBACK_PROVIDERS:-}"
+ OPENAI_API_VERSION: "${OPENAI_API_VERSION:-}"
+ OPENAI_REASONING_EFFORT: "${OPENAI_REASONING_EFFORT:-}"
+ OPENAI_TIMEOUT_MS: "${OPENAI_TIMEOUT_MS:-}"
+ MINIMAX_BASE_URL: "${MINIMAX_BASE_URL:-}"
+ OPENROUTER_EMBEDDING_MODEL: "${OPENROUTER_EMBEDDING_MODEL:-}"
+ OPENROUTER_EMBEDDING_DIMENSIONS: "${OPENROUTER_EMBEDDING_DIMENSIONS:-}"
+ AGENTMEMORY_LLM_TIMEOUT_MS: "${AGENTMEMORY_LLM_TIMEOUT_MS:-}"
+ AGENTMEMORY_CAPTURE_MAX_ATTEMPTS: "${AGENTMEMORY_CAPTURE_MAX_ATTEMPTS:-}"
+ AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS: "${AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS:-}"
+ AGENTMEMORY_CAPTURE_DEDUP_HOURS: "${AGENTMEMORY_CAPTURE_DEDUP_HOURS:-}"
+ AGENTMEMORY_CAPTURE_INBOX_MAX: "${AGENTMEMORY_CAPTURE_INBOX_MAX:-}"
+ AGENTMEMORY_CAPTURE_DEAD_MAX: "${AGENTMEMORY_CAPTURE_DEAD_MAX:-}"
+ AGENTMEMORY_CAPTURE_EVENTS_MAX: "${AGENTMEMORY_CAPTURE_EVENTS_MAX:-}"
+ AGENTMEMORY_CAPTURE_SPOOL: "${AGENTMEMORY_CAPTURE_SPOOL:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_DIR: "${AGENTMEMORY_CAPTURE_SPOOL_DIR:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES: "${AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS: "${AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS:-}"
+ AGENTMEMORY_IMPORT_ROOT: "${AGENTMEMORY_IMPORT_ROOT:-}"
+ AGENTMEMORY_EXPORT_ROOT: "${AGENTMEMORY_EXPORT_ROOT:-}"
+ AGENTMEMORY_GRAPH_WEIGHT: "${AGENTMEMORY_GRAPH_WEIGHT:-}"
+ SUMMARIZE_CHUNK_SIZE: "${SUMMARIZE_CHUNK_SIZE:-}"
+ SUMMARIZE_CHUNK_CONCURRENCY: "${SUMMARIZE_CHUNK_CONCURRENCY:-}"
+ CONSOLIDATION_DECAY_DAYS: "${CONSOLIDATION_DECAY_DAYS:-}"
+ CONSOLIDATION_INTERVAL_MS: "${CONSOLIDATION_INTERVAL_MS:-}"
+ AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS: "${AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS:-}"
+ AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS: "${AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS:-}"
+ GRAPH_EXTRACTION_BATCH_SIZE: "${GRAPH_EXTRACTION_BATCH_SIZE:-}"
+ AGENTMEMORY_LLM_NOTHINK: "${AGENTMEMORY_LLM_NOTHINK:-}"
+ AGENTMEMORY_REFLECT: "${AGENTMEMORY_REFLECT:-}"
+ AGENTMEMORY_IMAGE_EMBEDDINGS: "${AGENTMEMORY_IMAGE_EMBEDDINGS:-}"
+ AGENTMEMORY_IMAGE_STORE_MAX_BYTES: "${AGENTMEMORY_IMAGE_STORE_MAX_BYTES:-}"
+ AGENTMEMORY_AUDIT_INDEX_PERSIST: "${AGENTMEMORY_AUDIT_INDEX_PERSIST:-}"
+ AGENTMEMORY_INDEX_SAVE_INTERVAL_MS: "${AGENTMEMORY_INDEX_SAVE_INTERVAL_MS:-}"
+ AGENTMEMORY_VECTOR_BUCKET_SIZE: "${AGENTMEMORY_VECTOR_BUCKET_SIZE:-}"
+ AGENTMEMORY_VECTOR_BACKFILL_MAX: "${AGENTMEMORY_VECTOR_BACKFILL_MAX:-}"
+ AGENTMEMORY_VECTOR_BACKFILL: "${AGENTMEMORY_VECTOR_BACKFILL:-}"
+ AGENTMEMORY_SLOTS: "${AGENTMEMORY_SLOTS:-}"
+ AGENTMEMORY_PROVIDER: "${AGENTMEMORY_PROVIDER:-}"
+ AGENTMEMORY_VERBOSE: "${AGENTMEMORY_VERBOSE:-}"
+ OBSIDIAN_AUTO_EXPORT: "${OBSIDIAN_AUTO_EXPORT:-}"
+ AUTO_FORGET_ENABLED: "${AUTO_FORGET_ENABLED:-}"
+ AUTO_FORGET_INTERVAL_MS: "${AUTO_FORGET_INTERVAL_MS:-}"
+ LESSON_DECAY_ENABLED: "${LESSON_DECAY_ENABLED:-}"
+ INSIGHT_DECAY_ENABLED: "${INSIGHT_DECAY_ENABLED:-}"
+ REBUILD_EMBED_BATCH_SIZE: "${REBUILD_EMBED_BATCH_SIZE:-}"
+ RERANK_ENABLED: "${RERANK_ENABLED:-}"
expose:
- "3111"
+ - "3113"
volumes:
- agentmemory-data:/data
healthcheck:
- test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:3111/agentmemory/livez || exit 1"]
+ test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3111/agentmemory/livez').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
interval: 30s
timeout: 5s
- start_period: 30s
+ start_period: 60s
retries: 3
logging:
driver: json-file
diff --git a/deploy/coolify/entrypoint.sh b/deploy/coolify/entrypoint.sh
deleted file mode 100755
index 8df88f49..00000000
--- a/deploy/coolify/entrypoint.sh
+++ /dev/null
@@ -1,109 +0,0 @@
-#!/bin/sh
-# agentmemory first-boot entrypoint.
-#
-# Runs as root so it can:
-# 1. Overwrite the npm-bundled iii-config.yaml (which binds 127.0.0.1
-# and uses relative ./data paths) with a deploy-tuned version that
-# binds 0.0.0.0 and uses absolute /data paths.
-# 2. chown the platform-mounted /data volume to the runtime user
-# (managed platforms mount volumes root-owned 755 by default).
-# 3. Generate the HMAC secret on first boot and persist it to
-# /data/.hmac (chmod 600) so the secret survives restarts.
-#
-# Then it execs the agentmemory CLI under gosu as the unprivileged
-# `node` user.
-
-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"
-
-cat > "$III_CONFIG" <<'EOF'
-workers:
- - name: iii-http
- config:
- 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_methods: [GET, POST, PUT, DELETE, OPTIONS]
- - name: iii-state
- config:
- adapter:
- name: kv
- config:
- store_method: file_based
- save_interval_ms: 2000
- file_path: /data/state_store.db
- - name: iii-queue
- config:
- adapter:
- name: builtin
- - name: iii-pubsub
- config:
- adapter:
- name: local
- - name: iii-cron
- config:
- adapter:
- name: kv
- - name: iii-stream
- config:
- port: 3112
- host: 0.0.0.0
- adapter:
- 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: 0.1
- metrics_enabled: true
- logs_enabled: true
- logs_console_output: false
-EOF
-chown "$RUN_AS" "$III_CONFIG"
-
-if [ ! -s "$HMAC_FILE" ]; then
- SECRET="$(openssl rand -hex 32)"
- umask 077
- printf '%s\n' "$SECRET" > "$HMAC_FILE"
- chmod 600 "$HMAC_FILE"
- chown "$RUN_AS" "$HMAC_FILE"
- echo "================================================================"
- echo "agentmemory: generated HMAC secret on first boot"
- echo "AGENTMEMORY_SECRET=$SECRET"
- echo "Copy this value now. It will not be printed again."
- echo "Stored at: $HMAC_FILE (chmod 600)"
- echo "To rotate: delete $HMAC_FILE on the persistent volume and restart."
- echo "================================================================"
-fi
-
-AGENTMEMORY_SECRET="$(cat "$HMAC_FILE")"
-export AGENTMEMORY_SECRET
-
-exec gosu "$RUN_AS" agentmemory "$@"
diff --git a/deploy/fly/Dockerfile b/deploy/fly/Dockerfile
deleted file mode 100644
index 3abf3663..00000000
--- a/deploy/fly/Dockerfile
+++ /dev/null
@@ -1,37 +0,0 @@
-ARG III_VERSION=0.22.1
-
-FROM iiidev/iii:${III_VERSION} AS iii-image
-
-FROM node:22-slim
-
-ARG AGENTMEMORY_VERSION=0.9.30
-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 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
-
-ENV AGENTMEMORY_III_VERSION=${III_VERSION} \
- TINI_SUBREAPER=1
-
-COPY --chmod=0755 entrypoint.sh /usr/local/bin/agentmemory-entrypoint.sh
-
-EXPOSE 3111
-
-ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/agentmemory-entrypoint.sh"]
diff --git a/deploy/fly/README.md b/deploy/fly/README.md
index 3b7b4e90..a8b988eb 100644
--- a/deploy/fly/README.md
+++ b/deploy/fly/README.md
@@ -1,166 +1,15 @@
-# Deploy agentmemory on fly.io
+# Fly.io
-This template runs agentmemory on a single fly.io machine with a 1 GB
-persistent volume mounted at `/data`. The HMAC secret is generated on
-first boot and persisted to the volume — you capture it from the deploy
-logs exactly once.
-
-## What you get
-
-- A public HTTPS endpoint serving the agentmemory REST API on port 3111
-- A 1 GB Fly Volume at `/data` for memories, BM25 index, and stream backlog
-- `auto_stop_machines = "stop"` and `min_machines_running = 0` — the
- machine sleeps when idle, so cost floor approaches $0 for low traffic
-- HTTP healthcheck at `/agentmemory/livez` every 30 s
-- The HMAC bearer secret is generated on first boot inside the
- container and persisted to `/data/.hmac` (chmod 600); the operator
- copies it from the deploy logs once.
-
-## One-time setup
-
-Pick a unique Fly app name first — `agentmemory` itself is likely taken.
-Every command below references `$APP`, so set it once and the rest of the
-flow stays consistent:
-
-```bash
-# 1. Install flyctl: https://fly.io/docs/flyctl/install/
-# 2. Pick your unique app name (and matching volume name):
-export APP="agentmemory-$(whoami)" # or any other globally-unique name
-export VOLUME="${APP//-/_}_data" # Fly volume names can't contain '-'
-
-# 3. From this directory:
-fly launch --copy-config --no-deploy --name "$APP"
-
-# 4. Create the volume in the same region as the app:
-fly volumes create "$VOLUME" --region iad --size 1
-
-# 5. Deploy:
-fly deploy --app "$APP"
-```
-
-If `fly launch` reports the name is taken, pick another value for `$APP`,
-re-export, and re-run.
-
-## Capture the HMAC secret
-
-Right after the first deploy succeeds:
-
-```bash
-fly logs --app "$APP" | grep -A1 AGENTMEMORY_SECRET=
-```
-
-You will see exactly one line of the form `AGENTMEMORY_SECRET=<64 hex chars>`.
-Copy it into your client environment (`~/.bashrc`, Claude Desktop config,
-the viewer unlock prompt, etc.). The secret is never printed again on
-subsequent boots.
-
-If the first-boot log line is no longer available, read the persisted
-secret from the mounted volume:
+From the repository root, create the app and persistent volume, then deploy:
```bash
-fly ssh console --app "$APP" -C "sh -lc 'cat /data/.hmac'"
+fly apps create <unique-app-name>
+fly volumes create agentmemory_data --region iad --size 1 --app <unique-app-name>
+fly deploy --config deploy/fly/fly.toml --app <unique-app-name>
```
-## Verify the deployment
-
-```bash
-curl "https://$APP.fly.dev/agentmemory/livez"
-# {"status":"ok"}
-```
-
-For an authenticated call, your client must send `Authorization: Bearer <secret>`.
-
-## Viewer access (port 3113 stays internal)
-
-The viewer port is intentionally not exposed publicly. Tunnel to it:
-
-```bash
-fly proxy 3113:3113 --app "$APP"
-# then open http://localhost:3113
-```
-
-`fly proxy` opens an mTLS WireGuard channel to the machine, so the
-viewer's bearer token still has to ride a loopback connection on your
-laptop — the v0.9.12 plaintext-bearer guard stays satisfied.
-
-The entrypoint sets `AGENTMEMORY_VIEWER_HOST=::` **only when it detects
-Fly's runtime variables** (`FLY_APP_NAME` / `FLY_ALLOC_ID`). That makes
-the viewer listen on the machine's `fly-local-6pn` WireGuard interface
-as well as loopback so `fly proxy` can reach it. The same branch
-pre-seeds `VIEWER_ALLOWED_HOSTS=localhost:3113,127.0.0.1:3113,[::1]:3113`,
-which are the Host headers `fly proxy 3113:3113` actually emits on
-your laptop.
-
-When `AGENTMEMORY_VIEWER_HOST` is non-loopback the viewer enforces two
-extra guards: it refuses to start unless `VIEWER_ALLOWED_HOSTS` is
-explicitly set, and every request to `/agentmemory/*` must present
-`Authorization: Bearer $AGENTMEMORY_SECRET`. Static HTML and the
-favicon are still served unauthenticated. If a proxied viewer request
-gets a 401, the browser UI prompts for `AGENTMEMORY_SECRET` and stores
-it in session storage so subsequent viewer API calls include the bearer.
-Use the value printed in the first-boot logs or read `/data/.hmac`
-inside the machine.
-
-> **Security warning.** Setting `AGENTMEMORY_VIEWER_HOST=0.0.0.0` or
-> `::` turns the viewer into a network-reachable proxy that signs every
-> upstream call with `AGENTMEMORY_SECRET`. Never enable that outside a
-> network you trust (Fly's WireGuard mesh in this template), and never
-> set it in a plain `docker run -p 3113:3113 …` on a shared host — the
-> entrypoint deliberately skips the override when Fly env vars are
-> absent so a plain Docker pull stays loopback-only.
-
-## Rotate the HMAC secret
-
-```bash
-fly ssh console --app "$APP"
-rm /data/.hmac
-exit
-fly machine restart <machine-id>
-fly logs --app "$APP" | grep AGENTMEMORY_SECRET=
-```
-
-Update every client with the new secret. Old tokens stop working
-immediately.
-
-## Back up `/data`
-
-```bash
-fly ssh console --app "$APP" -C "tar czf - /data" > "$APP-$(date +%Y%m%d).tar.gz"
-```
-
-To restore on a fresh machine:
-
-```bash
-cat "$APP-YYYYMMDD.tar.gz" | fly ssh console --app "$APP" -C "tar xzf - -C /"
-fly machine restart <machine-id>
-```
-
-## Cost floor and egress
-
-- Idle (machine stopped): the volume costs ~$0.15/GB/month. A 1 GB
- volume is roughly $0.15/month.
-- Active (machine running on `shared-cpu-1x` with 512 MB): about
- $1.94/month if it ran 24/7; in practice `auto_stop_machines` keeps
- that well under $1.
-- Outbound bandwidth: 100 GB/month free on the Hobby plan, then $0.02/GB
- in North America / Europe.
-
-See <https://fly.io/docs/about/pricing/> for the up-to-date rate card.
+The shared `deploy/Dockerfile` build runs iii 0.25.0 Worker Compose. `/data` persists engine configuration, state, secret, registry cache, and logs. REST is served over HTTPS on internal port `3111`; the authenticated viewer uses internal port `3113`, exposed only through the TLS listener on public port `8443`.
-## Known caveats
+Set `VIEWER_ALLOWED_HOSTS` to `<app>.fly.dev:8443,localhost:3113` and `VIEWER_ALLOWED_ORIGINS` to `https://<app>.fly.dev:8443` before enabling the viewer. Keep `localhost:3113` for Fly's internal viewer healthcheck. Browse to `https://<app>.fly.dev:8443`; enter the bearer secret when prompted. The API/SSE proxy requires bearer auth. Never expose port `49134`.
-- The volume lives in one region. To survive a region outage, create a
- second volume in another region and update `primary_region` after the
- failover, or take snapshots with `fly volumes snapshots create`.
-- The Dockerfile builds in the Fly Builder on every deploy — first
- build is ~30 seconds; cached layers shrink rebuilds to under 10
- seconds. Image is ~114 MB.
-- First deploy lands on a **shared IPv4 + dedicated IPv6** by default
- (free). If you need a dedicated IPv4 for legacy clients without SNI,
- run `fly ips allocate-v4 --app "$APP"` — costs $2/month.
-- Cold-start (from machine launch to passing `/agentmemory/livez`) is
- ~9 seconds measured. `grace_period = "30s"` on the health check
- gives a 3x safety margin.
-- Bump `AGENTMEMORY_VERSION` or `III_VERSION` in the Dockerfile to
- upgrade. `fly deploy --build-arg AGENTMEMORY_VERSION=<x>` also works
- for a one-off without editing the file.
+Read the generated secret with `fly ssh console --app <app> -C 'cat /data/secret'`. Back up `/data` before changing deployments or rotating the secret. The Fly volume is regional; use snapshots or an off-region backup for disaster recovery.
diff --git a/deploy/fly/entrypoint.sh b/deploy/fly/entrypoint.sh
deleted file mode 100755
index f81f4bcb..00000000
--- a/deploy/fly/entrypoint.sh
+++ /dev/null
@@ -1,123 +0,0 @@
-#!/bin/sh
-# agentmemory first-boot entrypoint.
-#
-# Runs as root so it can:
-# 1. Overwrite the npm-bundled iii-config.yaml (which binds 127.0.0.1
-# and uses relative ./data paths) with a deploy-tuned version that
-# binds 0.0.0.0 and uses absolute /data paths.
-# 2. chown the platform-mounted /data volume to the runtime user
-# (managed platforms mount volumes root-owned 755 by default).
-# 3. Generate the HMAC secret on first boot and persist it to
-# /data/.hmac (chmod 600) so the secret survives restarts.
-#
-# Then it execs the agentmemory CLI under gosu as the unprivileged
-# `node` user.
-
-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"
-
-cat > "$III_CONFIG" <<'EOF'
-workers:
- - name: iii-http
- config:
- 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_methods: [GET, POST, PUT, DELETE, OPTIONS]
- - name: iii-state
- config:
- adapter:
- name: kv
- config:
- store_method: file_based
- save_interval_ms: 2000
- file_path: /data/state_store.db
- - name: iii-queue
- config:
- adapter:
- name: builtin
- - name: iii-pubsub
- config:
- adapter:
- name: local
- - name: iii-cron
- config:
- adapter:
- name: kv
- - name: iii-stream
- config:
- port: 3112
- host: 0.0.0.0
- adapter:
- 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: 0.1
- metrics_enabled: true
- logs_enabled: true
- logs_console_output: false
-EOF
-chown "$RUN_AS" "$III_CONFIG"
-
-if [ ! -s "$HMAC_FILE" ]; then
- SECRET="$(openssl rand -hex 32)"
- umask 077
- printf '%s\n' "$SECRET" > "$HMAC_FILE"
- chmod 600 "$HMAC_FILE"
- chown "$RUN_AS" "$HMAC_FILE"
- echo "================================================================"
- echo "agentmemory: generated HMAC secret on first boot"
- echo "AGENTMEMORY_SECRET=$SECRET"
- echo "Copy this value now. It will not be printed again."
- echo "Stored at: $HMAC_FILE (chmod 600)"
- echo "To rotate: delete $HMAC_FILE on the persistent volume and restart."
- echo "================================================================"
-fi
-
-AGENTMEMORY_SECRET="$(cat "$HMAC_FILE")"
-export AGENTMEMORY_SECRET
-
-# The viewer's default 127.0.0.1 bind is unreachable through fly proxy,
-# which enters the machine via fly-local-6pn (IPv6). Opt into a
-# non-loopback bind ONLY when we're actually inside Fly (detected via
-# Fly's runtime variables). A plain `docker run` of this image will not
-# see these variables and will keep the safe-by-default loopback bind,
-# so it can't silently expose the viewer's bearer-authorized proxy to
-# the LAN. VIEWER_ALLOWED_HOSTS is preseeded to the Host headers that
-# `fly proxy 3113:3113` actually produces on the operator's laptop.
-if [ -n "${FLY_APP_NAME:-}" ] || [ -n "${FLY_ALLOC_ID:-}" ]; then
- : "${AGENTMEMORY_VIEWER_HOST:=::}"
- : "${VIEWER_ALLOWED_HOSTS:=localhost:3113,127.0.0.1:3113,[::1]:3113}"
- export AGENTMEMORY_VIEWER_HOST VIEWER_ALLOWED_HOSTS
-fi
-
-exec gosu "$RUN_AS" agentmemory "$@"
diff --git a/deploy/fly/fly.toml b/deploy/fly/fly.toml
index 03f58bc9..b8975786 100644
--- a/deploy/fly/fly.toml
+++ b/deploy/fly/fly.toml
@@ -1,18 +1,9 @@
-# fly.io deployment for agentmemory.
-#
-# The HMAC secret is generated by entrypoint.sh on first boot and persisted
-# to the mounted volume at /data/.hmac. Operator copies it once from
-# `fly logs` then never sees it again. To rotate: `fly ssh console` and
-# `rm /data/.hmac`, then `fly machine restart`.
-#
-# Only port 3111 (REST API) is exposed publicly. Viewer 3113 stays bound
-# to localhost inside the machine; reach it via `fly proxy 3113:3113`.
-
+# Deploy from the repository root: fly deploy --config deploy/fly/fly.toml
app = "agentmemory"
primary_region = "iad"
[build]
- dockerfile = "Dockerfile"
+ dockerfile = "deploy/Dockerfile"
[[mounts]]
source = "agentmemory_data"
@@ -35,10 +26,32 @@ primary_region = "iad"
[[http_service.checks]]
interval = "30s"
timeout = "5s"
- grace_period = "30s"
+ grace_period = "60s"
method = "GET"
path = "/agentmemory/livez"
+# Publish the viewer separately; it requires bearer auth and a Host allowlist.
+[[services]]
+ protocol = "tcp"
+ internal_port = 3113
+ auto_stop_machines = "stop"
+ auto_start_machines = true
+ min_machines_running = 0
+ processes = ["app"]
+
+ [[services.ports]]
+ port = 8443
+ handlers = ["tls", "http"]
+
+ [[services.http_checks]]
+ interval = "30s"
+ timeout = "5s"
+ grace_period = "60s"
+ method = "GET"
+ path = "/"
+ [services.http_checks.headers]
+ Host = "localhost:3113"
+
[[vm]]
size = "shared-cpu-1x"
- memory = "512mb"
+ memory = "1gb"
diff --git a/deploy/railway/Dockerfile b/deploy/railway/Dockerfile
deleted file mode 100644
index 3abf3663..00000000
--- a/deploy/railway/Dockerfile
+++ /dev/null
@@ -1,37 +0,0 @@
-ARG III_VERSION=0.22.1
-
-FROM iiidev/iii:${III_VERSION} AS iii-image
-
-FROM node:22-slim
-
-ARG AGENTMEMORY_VERSION=0.9.30
-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 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
-
-ENV AGENTMEMORY_III_VERSION=${III_VERSION} \
- TINI_SUBREAPER=1
-
-COPY --chmod=0755 entrypoint.sh /usr/local/bin/agentmemory-entrypoint.sh
-
-EXPOSE 3111
-
-ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/agentmemory-entrypoint.sh"]
diff --git a/deploy/railway/README.md b/deploy/railway/README.md
index 9aad4fb3..fea48d53 100644
--- a/deploy/railway/README.md
+++ b/deploy/railway/README.md
@@ -1,136 +1,9 @@
-# Deploy agentmemory on Railway
+# Railway
-This template runs agentmemory on a single Railway service with a
-persistent volume mounted at `/data`. The HMAC secret is generated on
-first boot and persisted to the volume — you read it once from the
-deploy logs and copy it into your client.
+Connect the GitHub repository with its root directory left at the repository root; the shared Dockerfile needs root-level `package.json` and source files in its build context. In service settings, set the Config-as-Code path to `/deploy/railway/railway.json` (Railway resolves this path independently of the selected root directory). This config selects `deploy/Dockerfile` while the build context remains the repository root. Add a persistent volume mounted at `/data` before starting the service. The service runs iii 0.25.0 Worker Compose and serves the health endpoint at `/agentmemory/livez`.
-## What you get
+The REST API listens on `3111`; Railway's generated HTTP domain exposes that service. Read the secret with `railway ssh --service agentmemory -- 'cat /data/secret'` and send it as `Authorization: Bearer <secret>`.
-- A public HTTPS endpoint serving the agentmemory REST API on port 3111
-- A persistent Railway Volume at `/data` for memories, BM25 index, and
- stream backlog
-- Railway healthcheck against `/agentmemory/livez`
-- The HMAC bearer secret is generated on first boot inside the
- container and persisted to `/data/.hmac` (chmod 600); the operator
- copies it from the deploy logs once.
-- The deploy uses `requiredMountPath: /data` so Railway refuses to
- start the service if no volume is attached at that path — first
- deploy must create the volume from the dashboard.
+The viewer listens on `3113`. Keep it private unless you put a TLS-terminating reverse proxy in front of it. Do not expose a raw TCP proxy for `3113` to the public internet: viewer API/SSE proxy calls carry the bearer token. If using a TLS proxy, configure `VIEWER_ALLOWED_HOSTS` and `VIEWER_ALLOWED_ORIGINS` with its exact host and origin, then enter the bearer in the viewer prompt. Viewer API/SSE proxy routes require bearer auth. Do not expose `49134`.
-## Deploy via Railway dashboard
-
-1. Click **Deploy from GitHub** in the Railway dashboard and pick the
- `rohitg00/agentmemory` repo.
-2. Set the **Config-as-Code Path** under the service Settings to
- `deploy/railway/railway.json`. Railway picks up the Dockerfile path
- from there.
-3. Open the service's **Volumes** tab and add a volume mounted at
- `/data` (Railway volumes are configured in the dashboard or via
- `railway volume add`, not in `railway.json`).
-4. Click **Deploy**.
-
-## Deploy via Railway CLI
-
-```bash
-# Install: https://docs.railway.com/guides/cli
-railway login
-railway init # link a new project
-railway up --service agentmemory # builds + deploys
-railway volume add --service agentmemory --mount /data # attach persistent volume
-railway redeploy # restart with the volume
-```
-
-## Capture the HMAC secret
-
-After the first deploy succeeds, open the service's **Deploy Logs**:
-
-```bash
-railway logs --service agentmemory | grep AGENTMEMORY_SECRET=
-```
-
-You will see exactly one line of the form `AGENTMEMORY_SECRET=<64 hex chars>`.
-Copy it into your client environment. The secret is never printed again
-on subsequent boots.
-
-## Verify the deployment
-
-```bash
-curl https://<your-service>.up.railway.app/agentmemory/livez
-# {"status":"ok"}
-```
-
-For an authenticated call, your client must send `Authorization: Bearer <secret>`.
-
-## Viewer access (port 3113 stays internal)
-
-Railway only exposes the single public port from your service's
-`PORT` env var (which we map to 3111). The viewer stays bound to
-localhost inside the container. `railway ssh` is an interactive shell
-only — it does not support `-L`-style port forwarding, so reach the
-viewer with one of the following.
-
-**Quick in-container check:**
-
-```bash
-railway ssh --service agentmemory
-# inside the container:
-curl http://localhost:3113
-```
-
-**Browser session — option A (TCP Proxy, recommended):** in the Railway
-dashboard, open the service's *Settings → Networking* tab and add a
-**TCP Proxy** for container port `3113`. Railway returns a public
-host/port pair you can hit directly from your browser. Pair it with the
-HMAC bearer-auth header so the viewer is not anonymously reachable.
-
-**Browser session — option B (in-container sshd):** add an `openssh-server`
-process to the image and start it from `entrypoint.sh` on a fixed port,
-expose that port through a second Railway TCP Proxy, then use a native
-`ssh -L 3113:localhost:3113 <proxy-host> -p <proxy-port>` from your laptop.
-This is the heavier path; option A is what most users will want.
-
-## Rotate the HMAC secret
-
-```bash
-railway ssh --service agentmemory
-rm /data/.hmac
-exit
-railway redeploy --service agentmemory
-railway logs --service agentmemory | grep AGENTMEMORY_SECRET=
-```
-
-Update every client with the new secret. Old tokens stop working
-immediately.
-
-## Back up `/data`
-
-```bash
-railway ssh --service agentmemory -- "tar czf - /data" > agentmemory-$(date +%Y%m%d).tar.gz
-```
-
-To restore on a fresh volume:
-
-```bash
-cat agentmemory-YYYYMMDD.tar.gz | railway ssh --service agentmemory -- "tar xzf - -C /"
-railway redeploy --service agentmemory
-```
-
-## Cost floor and egress
-
-- Hobby plan: $5/month flat, includes $5 of usage.
-- agentmemory at idle plus a 1 GB volume typically uses $3–$6 of usage
- per month on the smallest instance, so most users stay near the $5
- floor.
-- Egress: $0.10/GB after the bundled allowance.
-
-See <https://railway.com/pricing> for the current rate card.
-
-## Known caveats
-
-- Railway volumes do not auto-snapshot. Take your own backups (above)
- or use the dashboard's manual snapshot feature.
-- The Dockerfile builds on Railway's builder on every deploy. First
- deploy is ~2 minutes; cached layers make subsequent rebuilds quick.
- Pin `AGENTMEMORY_VERSION` / `III_VERSION` build args in the
- service's *Variables* tab to lock a specific release.
+Keep the volume attached when redeploying. Back up `/data` before upgrades; Railway volumes do not automatically provide a portable backup.
diff --git a/deploy/railway/entrypoint.sh b/deploy/railway/entrypoint.sh
deleted file mode 100755
index 8df88f49..00000000
--- a/deploy/railway/entrypoint.sh
+++ /dev/null
@@ -1,109 +0,0 @@
-#!/bin/sh
-# agentmemory first-boot entrypoint.
-#
-# Runs as root so it can:
-# 1. Overwrite the npm-bundled iii-config.yaml (which binds 127.0.0.1
-# and uses relative ./data paths) with a deploy-tuned version that
-# binds 0.0.0.0 and uses absolute /data paths.
-# 2. chown the platform-mounted /data volume to the runtime user
-# (managed platforms mount volumes root-owned 755 by default).
-# 3. Generate the HMAC secret on first boot and persist it to
-# /data/.hmac (chmod 600) so the secret survives restarts.
-#
-# Then it execs the agentmemory CLI under gosu as the unprivileged
-# `node` user.
-
-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"
-
-cat > "$III_CONFIG" <<'EOF'
-workers:
- - name: iii-http
- config:
- 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_methods: [GET, POST, PUT, DELETE, OPTIONS]
- - name: iii-state
- config:
- adapter:
- name: kv
- config:
- store_method: file_based
- save_interval_ms: 2000
- file_path: /data/state_store.db
- - name: iii-queue
- config:
- adapter:
- name: builtin
- - name: iii-pubsub
- config:
- adapter:
- name: local
- - name: iii-cron
- config:
- adapter:
- name: kv
- - name: iii-stream
- config:
- port: 3112
- host: 0.0.0.0
- adapter:
- 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: 0.1
- metrics_enabled: true
- logs_enabled: true
- logs_console_output: false
-EOF
-chown "$RUN_AS" "$III_CONFIG"
-
-if [ ! -s "$HMAC_FILE" ]; then
- SECRET="$(openssl rand -hex 32)"
- umask 077
- printf '%s\n' "$SECRET" > "$HMAC_FILE"
- chmod 600 "$HMAC_FILE"
- chown "$RUN_AS" "$HMAC_FILE"
- echo "================================================================"
- echo "agentmemory: generated HMAC secret on first boot"
- echo "AGENTMEMORY_SECRET=$SECRET"
- echo "Copy this value now. It will not be printed again."
- echo "Stored at: $HMAC_FILE (chmod 600)"
- echo "To rotate: delete $HMAC_FILE on the persistent volume and restart."
- echo "================================================================"
-fi
-
-AGENTMEMORY_SECRET="$(cat "$HMAC_FILE")"
-export AGENTMEMORY_SECRET
-
-exec gosu "$RUN_AS" agentmemory "$@"
diff --git a/deploy/railway/railway.json b/deploy/railway/railway.json
index 43f52173..92fb3788 100644
--- a/deploy/railway/railway.json
+++ b/deploy/railway/railway.json
@@ -2,12 +2,12 @@
"$schema": "https://railway.com/railway.schema.json",
"build": {
"builder": "DOCKERFILE",
- "dockerfilePath": "deploy/railway/Dockerfile"
+ "dockerfilePath": "deploy/Dockerfile"
},
"deploy": {
"numReplicas": 1,
"healthcheckPath": "/agentmemory/livez",
- "healthcheckTimeout": 30,
+ "healthcheckTimeout": 60,
"restartPolicyType": "ON_FAILURE",
"restartPolicyMaxRetries": 10,
"requiredMountPath": "/data"
diff --git a/deploy/render/Dockerfile b/deploy/render/Dockerfile
deleted file mode 100644
index 3abf3663..00000000
--- a/deploy/render/Dockerfile
+++ /dev/null
@@ -1,37 +0,0 @@
-ARG III_VERSION=0.22.1
-
-FROM iiidev/iii:${III_VERSION} AS iii-image
-
-FROM node:22-slim
-
-ARG AGENTMEMORY_VERSION=0.9.30
-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 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
-
-ENV AGENTMEMORY_III_VERSION=${III_VERSION} \
- TINI_SUBREAPER=1
-
-COPY --chmod=0755 entrypoint.sh /usr/local/bin/agentmemory-entrypoint.sh
-
-EXPOSE 3111
-
-ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/agentmemory-entrypoint.sh"]
diff --git a/deploy/render/README.md b/deploy/render/README.md
index 3b73f7ee..a1871bcc 100644
--- a/deploy/render/README.md
+++ b/deploy/render/README.md
@@ -1,113 +1,7 @@
-# Deploy agentmemory on Render
+# Render
-This template runs agentmemory on a single Render Web Service with a
-persistent disk mounted at `/data`. The HMAC secret is generated on
-first boot and persisted to the disk — you capture it from the deploy
-logs exactly once.
+Create a Blueprint from `deploy/render/render.yaml`. Render builds the shared `deploy/Dockerfile` and provisions a persistent `/data` disk. The web service exposes REST on `3111` and uses `/agentmemory/livez` for health checks. The runtime is iii 0.25.0 Worker Compose with registry workers pinned in `deploy/Dockerfile` and `deploy/runtime/worker-compose.yaml`.
-## What you get
+The viewer listens on container port `3113`. Render's web service exposes only the primary HTTP port; reach the viewer through an SSH tunnel or a separately configured TLS proxy. For a public proxy, set `VIEWER_ALLOWED_HOSTS` and `VIEWER_ALLOWED_ORIGINS` to exact values. Viewer API/SSE routes require the bearer secret. Read it over SSH with `cat /data/secret`. Do not expose the engine WebSocket on `49134`.
-- A public HTTPS endpoint serving the agentmemory REST API on port 3111
- (Render injects `PORT` defaulting to 10000; we override it to 3111
- via `envVars` so the published port matches the container's bind)
-- A 1 GB persistent disk at `/data` for memories, BM25 index, and
- stream backlog
-- Render healthcheck against `/agentmemory/livez`
-- The HMAC bearer secret is generated on first boot inside the
- container and persisted to `/data/.hmac` (chmod 600); the operator
- copies it from the deploy logs once.
-
-## Deploy via Render Blueprint
-
-Render's one-click deploy button only auto-detects `render.yaml` at the
-repository root, which the agentmemory repo keeps clean. Use the
-dashboard's manual Blueprint flow instead:
-
-1. Push the `deploy/render/` directory to a Git provider Render can
- reach (a fork of `rohitg00/agentmemory` works).
-2. In the Render dashboard, click **New +** → **Blueprint**.
-3. Point Render at the repo and the path `deploy/render/render.yaml`.
-4. Render reads the Blueprint, provisions the disk, builds the
- Dockerfile, and starts the service. The whole flow takes 3–5
- minutes on the first run.
-
-## Deploy via Render Deploy Hook (one-click)
-
-Once the Blueprint exists in your account, generate a Deploy Hook URL
-in the service settings. Future deploys are a single curl call:
-
-```bash
-curl "https://api.render.com/deploy/srv-XXYYZZ?key=AABBCC"
-```
-
-To pin a specific `@agentmemory/agentmemory` release, set the
-`AGENTMEMORY_VERSION` build arg in the service's *Environment* tab
-before the next deploy. Same for `III_VERSION`.
-
-## Capture the HMAC secret
-
-After the first deploy succeeds, open the service's **Logs** tab and
-search for `AGENTMEMORY_SECRET=`. You will see exactly one line of the
-form `AGENTMEMORY_SECRET=<64 hex chars>`. Copy it into your client
-environment. The secret is never printed again on subsequent boots.
-
-## Verify the deployment
-
-```bash
-curl https://agentmemory.onrender.com/agentmemory/livez
-# {"status":"ok"}
-```
-
-For an authenticated call, your client must send `Authorization: Bearer <secret>`.
-
-## Viewer access (port 3113 stays internal)
-
-Render only exposes one public port per service, and we use it for
-3111. The viewer port stays bound to localhost inside the container.
-Reach it via Render's SSH:
-
-```bash
-# Settings → SSH → enable for your service, copy the connection command
-ssh srv-XXYYZZ@ssh.<region>.render.com -L 3113:localhost:3113
-# now http://localhost:3113 in your browser hits the in-container viewer
-```
-
-## Rotate the HMAC secret
-
-```bash
-ssh srv-XXYYZZ@ssh.<region>.render.com
-rm /data/.hmac
-exit
-# trigger a redeploy from the Render dashboard or via the Deploy Hook
-```
-
-After the redeploy, grab the new secret from the logs and update every
-client. Old tokens stop working immediately.
-
-## Back up `/data`
-
-```bash
-ssh srv-XXYYZZ@ssh.<region>.render.com "tar czf - /data" > agentmemory-$(date +%Y%m%d).tar.gz
-```
-
-Render also takes daily snapshots of persistent disks automatically on
-paid plans — the SSH tarball is a belt-and-braces option you can ship
-off-platform.
-
-## Cost floor and egress
-
-- Starter plan web service: $7/month (0.5 CPU, 512 MB RAM).
-- 1 GB persistent disk: $0.25/GB/month, so $0.25/month for the default.
-- Bandwidth: 100 GB outbound included, then $0.10/GB.
-
-See <https://render.com/pricing> for the current rate card.
-
-## Known caveats
-
-- Render Free tier does not support persistent disks. The Starter plan
- ($7/month) is the minimum.
-- Render restarts the service on every deploy. The HMAC secret survives
- because it lives on the disk, but expect a 10–30 s gap of 502s
- during rollouts.
-- Render runs amd64 only for web services. The Dockerfile selects the
- matching iii binary automatically via `uname -m`.
+Keep the disk attached on every deploy and back up `/data` before upgrades. Render Free does not support persistent disks.
diff --git a/deploy/render/entrypoint.sh b/deploy/render/entrypoint.sh
deleted file mode 100755
index 8df88f49..00000000
--- a/deploy/render/entrypoint.sh
+++ /dev/null
@@ -1,109 +0,0 @@
-#!/bin/sh
-# agentmemory first-boot entrypoint.
-#
-# Runs as root so it can:
-# 1. Overwrite the npm-bundled iii-config.yaml (which binds 127.0.0.1
-# and uses relative ./data paths) with a deploy-tuned version that
-# binds 0.0.0.0 and uses absolute /data paths.
-# 2. chown the platform-mounted /data volume to the runtime user
-# (managed platforms mount volumes root-owned 755 by default).
-# 3. Generate the HMAC secret on first boot and persist it to
-# /data/.hmac (chmod 600) so the secret survives restarts.
-#
-# Then it execs the agentmemory CLI under gosu as the unprivileged
-# `node` user.
-
-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"
-
-cat > "$III_CONFIG" <<'EOF'
-workers:
- - name: iii-http
- config:
- 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_methods: [GET, POST, PUT, DELETE, OPTIONS]
- - name: iii-state
- config:
- adapter:
- name: kv
- config:
- store_method: file_based
- save_interval_ms: 2000
- file_path: /data/state_store.db
- - name: iii-queue
- config:
- adapter:
- name: builtin
- - name: iii-pubsub
- config:
- adapter:
- name: local
- - name: iii-cron
- config:
- adapter:
- name: kv
- - name: iii-stream
- config:
- port: 3112
- host: 0.0.0.0
- adapter:
- 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: 0.1
- metrics_enabled: true
- logs_enabled: true
- logs_console_output: false
-EOF
-chown "$RUN_AS" "$III_CONFIG"
-
-if [ ! -s "$HMAC_FILE" ]; then
- SECRET="$(openssl rand -hex 32)"
- umask 077
- printf '%s\n' "$SECRET" > "$HMAC_FILE"
- chmod 600 "$HMAC_FILE"
- chown "$RUN_AS" "$HMAC_FILE"
- echo "================================================================"
- echo "agentmemory: generated HMAC secret on first boot"
- echo "AGENTMEMORY_SECRET=$SECRET"
- echo "Copy this value now. It will not be printed again."
- echo "Stored at: $HMAC_FILE (chmod 600)"
- echo "To rotate: delete $HMAC_FILE on the persistent volume and restart."
- echo "================================================================"
-fi
-
-AGENTMEMORY_SECRET="$(cat "$HMAC_FILE")"
-export AGENTMEMORY_SECRET
-
-exec gosu "$RUN_AS" agentmemory "$@"
diff --git a/deploy/render/render.yaml b/deploy/render/render.yaml
index 17150b74..3ccb5894 100644
--- a/deploy/render/render.yaml
+++ b/deploy/render/render.yaml
@@ -3,8 +3,8 @@ services:
name: agentmemory
runtime: docker
plan: starter
- dockerfilePath: ./deploy/render/Dockerfile
- dockerContext: ./deploy/render
+ dockerfilePath: ./deploy/Dockerfile
+ dockerContext: .
healthCheckPath: /agentmemory/livez
autoDeploy: false
disk:
@@ -14,9 +14,15 @@ services:
envVars:
- key: PORT
value: "3111"
- - key: AGENTMEMORY_VERSION
- value: "0.9.30"
- - key: III_VERSION
- value: "0.22.1"
- - key: III_SDK_VERSION
- value: "0.22.1"
+ - key: AGENTMEMORY_DATA_DIR
+ value: /data
+ - key: HOME
+ value: /data/home
+ - key: AGENTMEMORY_VIEWER_HOST
+ value: 0.0.0.0
+ - key: VIEWER_ALLOWED_HOSTS
+ value: localhost:3113,127.0.0.1:3113
+ - key: VIEWER_ALLOWED_ORIGINS
+ value: http://localhost:3113,http://127.0.0.1:3113
+ - key: III_TELEMETRY_ENABLED
+ value: "false"
diff --git a/deploy/runtime/agentmemory.worker.yaml b/deploy/runtime/agentmemory.worker.yaml
new file mode 100644
index 00000000..3057ce9c
--- /dev/null
+++ b/deploy/runtime/agentmemory.worker.yaml
@@ -0,0 +1,7 @@
+iii: v1
+name: agentmemory
+language: javascript
+runtime:
+ kind: javascript
+scripts:
+ start: node dist/index.mjs
diff --git a/deploy/runtime/entrypoint.sh b/deploy/runtime/entrypoint.sh
new file mode 100755
index 00000000..527409a6
--- /dev/null
+++ b/deploy/runtime/entrypoint.sh
@@ -0,0 +1,119 @@
+#!/bin/sh
+set -eu
+
+DATA_DIR="${AGENTMEMORY_DATA_DIR:-/data}"
+export AGENTMEMORY_DATA_DIR="$DATA_DIR"
+export HOME="${HOME:-$DATA_DIR/home}"
+export III_COMPOSE_STATE_DIR="${III_COMPOSE_STATE_DIR:-$DATA_DIR/compose-state}"
+export III_ENGINE_PORT="${III_ENGINE_PORT:-49134}"
+export III_REST_PORT="${III_REST_PORT:-3111}"
+export III_VIEWER_PORT="${III_VIEWER_PORT:-3113}"
+export III_TELEMETRY_ENABLED="${III_TELEMETRY_ENABLED:-false}"
+export AGENTMEMORY_VIEWER_HOST="${AGENTMEMORY_VIEWER_HOST:-0.0.0.0}"
+export AGENTMEMORY_STATE_SAVE_INTERVAL_MS="${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"
+case "$AGENTMEMORY_STATE_SAVE_INTERVAL_MS" in
+ ''|*[!0-9]*) echo "AGENTMEMORY_STATE_SAVE_INTERVAL_MS must be an integer between 100 and 3600000" >&2; exit 1 ;;
+esac
+if [ "$AGENTMEMORY_STATE_SAVE_INTERVAL_MS" -lt 100 ] || [ "$AGENTMEMORY_STATE_SAVE_INTERVAL_MS" -gt 3600000 ]; then
+ echo "AGENTMEMORY_STATE_SAVE_INTERVAL_MS must be an integer between 100 and 3600000" >&2
+ exit 1
+fi
+export VIEWER_ALLOWED_HOSTS="${VIEWER_ALLOWED_HOSTS:-localhost:3113,127.0.0.1:3113,[::1]:3113}"
+export VIEWER_ALLOWED_ORIGINS="${VIEWER_ALLOWED_ORIGINS:-http://localhost:3113,http://127.0.0.1:3113}"
+export REST_ALLOWED_ORIGINS="${REST_ALLOWED_ORIGINS:-http://localhost:3111,http://127.0.0.1:3111,http://localhost:3113,http://127.0.0.1:3113}"
+export MALLOC_ARENA_MAX="${MALLOC_ARENA_MAX:-2}"
+
+mkdir -p "$DATA_DIR"
+# Preserve the HMAC generated by older platform entrypoints before migrating
+# the volume. An explicit operator-provided secret always takes precedence.
+LEGACY_HMAC_FILE="${AGENTMEMORY_HMAC_FILE:-$DATA_DIR/.hmac}"
+if [ -z "${AGENTMEMORY_SECRET:-}" ] && [ ! -e "$DATA_DIR/secret" ] && [ -s "$LEGACY_HMAC_FILE" ]; then
+ (umask 077; set -C; cat "$LEGACY_HMAC_FILE" > "$DATA_DIR/secret")
+ chown node:node "$DATA_DIR/secret"
+ chmod 600 "$DATA_DIR/secret"
+fi
+# The former Docker runtime owned the persistent volume as UID/GID 65532.
+# Migrate the complete tree once; the marker makes subsequent boots O(1).
+OWNERSHIP_MARKER="$DATA_DIR/.ownership-migrated-node-v1"
+if [ ! -f "$OWNERSHIP_MARKER" ]; then
+ chown -R node:node "$DATA_DIR"
+ printf '%s\n' 'node:node' > "$OWNERSHIP_MARKER"
+ chown node:node "$OWNERSHIP_MARKER"
+ chmod 600 "$OWNERSHIP_MARKER"
+fi
+for dir in "$HOME" "$III_COMPOSE_STATE_DIR" "$DATA_DIR/config"; do
+ mkdir -p "$dir"
+ chown node:node "$dir"
+ chmod 700 "$dir"
+done
+
+current_nofile="$(ulimit -n)"
+if [ "$current_nofile" != unlimited ] && [ "$current_nofile" -lt 10240 ]; then
+ ulimit -n 10240 2>/dev/null || ulimit -n "$(ulimit -H -n)" 2>/dev/null || true
+fi
+
+# iii compose does not implicitly inherit the parent environment into workers;
+# worker-compose.yaml explicitly forwards the CLI allowlist.
+WORKER_COMPOSE_FILE="$DATA_DIR/worker-compose.runtime.yaml"
+export WORKER_COMPOSE_FILE REST_ALLOWED_ORIGINS AGENTMEMORY_STATE_BACKEND AGENTMEMORY_REDIS_URL
+if [ "${AGENTMEMORY_STATE_BACKEND:-}" = redis ] && [ -z "${AGENTMEMORY_REDIS_URL:-}" ]; then
+ echo "AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL" >&2
+ exit 1
+fi
+node <<'NODE'
+const fs = require("node:fs");
+const source = "/opt/agentmemory/worker-compose.yaml";
+const target = `${process.env.AGENTMEMORY_DATA_DIR}/worker-compose.runtime.yaml`;
+let input = fs.readFileSync(source, "utf8");
+const marker = ' allowed_origins: ["__REST_ALLOWED_ORIGINS__"]';
+if (!input.includes(marker)) throw new Error("Could not locate REST CORS allowlist marker");
+const origins = process.env.REST_ALLOWED_ORIGINS.split(",").map((origin) => origin.trim()).filter(Boolean);
+if (origins.length === 0 || origins.some((origin) => /[\u0000-\u001f\u007f]/.test(origin))) throw new Error("REST_ALLOWED_ORIGINS must contain comma-separated origins without control characters");
+input = input.replace(marker, ` allowed_origins:\n${origins.map((origin) => ` - ${JSON.stringify(origin)}`).join("\n")}`);
+const { parse, stringify } = require("/opt/agentmemory/node_modules/yaml");
+const configPath = `${process.env.AGENTMEMORY_DATA_DIR}/config/iii-observability.yaml`;
+let entry;
+try {
+ entry = parse(fs.readFileSync(configPath, "utf8"));
+ if (!entry || typeof entry !== "object" || Array.isArray(entry) || entry.id !== "iii-observability") {
+ throw new Error(`Unexpected persisted observability configuration at ${configPath}`);
+ }
+} catch (error) {
+ if (error.code !== "ENOENT") throw error;
+ entry = { id: "iii-observability", name: "Observability", description: "", schema: {} };
+}
+const value = entry.value && typeof entry.value === "object" && !Array.isArray(entry.value) ? entry.value : {};
+if (value.sampling_ratio === undefined) value.sampling_ratio = 0.1;
+if (value.logs_console_output === undefined) value.logs_console_output = false;
+const storage = value.trace_storage && typeof value.trace_storage === "object" && !Array.isArray(value.trace_storage) ? value.trace_storage : {};
+if (typeof storage.directory !== "string" || storage.directory === "" || storage.directory === "./data/observability/traces") {
+ storage.directory = `${process.env.AGENTMEMORY_DATA_DIR}/observability/traces`;
+ value.trace_storage = storage;
+}
+entry.value = value;
+const temporary = `${configPath}.tmp`;
+fs.writeFileSync(temporary, stringify(entry), { mode: 0o600 });
+fs.renameSync(temporary, configPath);
+fs.chmodSync(configPath, 0o600);
+const observabilityDir = `${process.env.AGENTMEMORY_DATA_DIR}/observability`;
+const tracesDir = `${observabilityDir}/traces`;
+fs.mkdirSync(tracesDir, { recursive: true, mode: 0o700 });
+fs.chownSync(observabilityDir, 1000, 1000);
+fs.chmodSync(observabilityDir, 0o700);
+fs.chownSync(tracesDir, 1000, 1000);
+fs.chmodSync(tracesDir, 0o700);
+if (process.env.AGENTMEMORY_STATE_BACKEND === "redis") {
+ const compose = parse(input);
+ if (!compose.containers?.state?.config_override?.adapter) throw new Error("Could not locate state adapter config");
+ const redisUrl = process.env.AGENTMEMORY_REDIS_URL;
+ if (!redisUrl || /[\u0000-\u001f\u007f]/.test(redisUrl)) throw new Error("AGENTMEMORY_REDIS_URL is required and must not contain control characters");
+ compose.containers.state.config_override.adapter = { name: "redis", config: { redis_url: redisUrl } };
+ input = stringify(compose);
+}
+fs.writeFileSync(target, input, { mode: 0o600 });
+NODE
+chown node:node "$DATA_DIR/config/iii-observability.yaml" "$WORKER_COMPOSE_FILE"
+
+# Compose owns the 0.25.0 engine and supervises state, http, and agentmemory.
+exec gosu node:node /usr/local/bin/iii compose \
+ --namespace agentmemory --up --file "$WORKER_COMPOSE_FILE"
diff --git a/deploy/runtime/worker-compose.yaml b/deploy/runtime/worker-compose.yaml
new file mode 100644
index 00000000..c1c10928
--- /dev/null
+++ b/deploy/runtime/worker-compose.yaml
@@ -0,0 +1,184 @@
+namespace: agentmemory
+startup_timeout: 300s
+stop_timeout: 20s
+required_default: true
+engine:
+ url: ws://127.0.0.1:49134
+ workers:
+ configuration:
+ adapter:
+ name: fs
+ config:
+ directory: /data/config
+ iii-worker-manager:
+ host: 127.0.0.1
+ port: 49134
+containers:
+ state:
+ worker: package://api.workers.iii.dev/state
+ version: "${STATE_VERSION}"
+ config_name: state
+ restart:
+ condition: on-failure
+ delay: 500ms
+ max_delay: 30s
+ max_attempts: 5
+ window: 60s
+ config_override:
+ adapter:
+ name: kv
+ config:
+ store_method: file_based
+ file_path: /data/state_store.db
+ save_interval_ms: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"
+ http:
+ worker: package://api.workers.iii.dev/http
+ version: "${HTTP_VERSION}"
+ config_name: http
+ restart:
+ condition: on-failure
+ delay: 500ms
+ max_delay: 30s
+ max_attempts: 5
+ window: 60s
+ config_override:
+ host: 0.0.0.0
+ port: 3111
+ default_timeout: 180000
+ cors:
+ allowed_origins: ["__REST_ALLOWED_ORIGINS__"]
+ allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]
+ agentmemory:
+ worker: path://.
+ working_dir: /opt/agentmemory
+ start_after: [state, http]
+ startup_timeout: 300s
+ config_name: agentmemory
+ restart:
+ condition: on-failure
+ delay: 500ms
+ max_delay: 30s
+ max_attempts: 5
+ window: 60s
+ scripts:
+ run: node /opt/agentmemory/dist/index.mjs
+ environment:
+ HOME: /data/home
+ AGENTMEMORY_DATA_DIR: /data
+ III_ENGINE_URL: ws://127.0.0.1:49134
+ III_ENGINE_PORT: "49134"
+ III_REST_PORT: "3111"
+ III_VIEWER_PORT: "3113"
+ III_TELEMETRY_ENABLED: "false"
+ AGENTMEMORY_VIEWER_HOST: "${AGENTMEMORY_VIEWER_HOST:-0.0.0.0}"
+ VIEWER_ALLOWED_HOSTS: "${VIEWER_ALLOWED_HOSTS:-localhost:3113,127.0.0.1:3113,[::1]:3113}"
+ VIEWER_ALLOWED_ORIGINS: "${VIEWER_ALLOWED_ORIGINS:-http://localhost:3113,http://127.0.0.1:3113}"
+ EMBEDDING_PROVIDER: "${EMBEDDING_PROVIDER:-}"
+ OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
+ OPENAI_API_KEY_FOR_LLM: "${OPENAI_API_KEY_FOR_LLM:-}"
+ OPENAI_BASE_URL: "${OPENAI_BASE_URL:-}"
+ OPENAI_MODEL: "${OPENAI_MODEL:-}"
+ OPENAI_EMBEDDING_API_KEY: "${OPENAI_EMBEDDING_API_KEY:-}"
+ OPENAI_EMBEDDING_BASE_URL: "${OPENAI_EMBEDDING_BASE_URL:-}"
+ OPENAI_EMBEDDING_MODEL: "${OPENAI_EMBEDDING_MODEL:-}"
+ OPENAI_EMBEDDING_DIMENSIONS: "${OPENAI_EMBEDDING_DIMENSIONS:-}"
+ ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+ ANTHROPIC_BASE_URL: "${ANTHROPIC_BASE_URL:-}"
+ ANTHROPIC_MODEL: "${ANTHROPIC_MODEL:-}"
+ GEMINI_API_KEY: "${GEMINI_API_KEY:-}"
+ GEMINI_MODEL: "${GEMINI_MODEL:-}"
+ GOOGLE_API_KEY: "${GOOGLE_API_KEY:-}"
+ VOYAGE_API_KEY: "${VOYAGE_API_KEY:-}"
+ VOYAGE_MODEL: "${VOYAGE_MODEL:-}"
+ COHERE_API_KEY: "${COHERE_API_KEY:-}"
+ COHERE_MODEL: "${COHERE_MODEL:-}"
+ OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:-}"
+ OPENROUTER_MODEL: "${OPENROUTER_MODEL:-}"
+ MINIMAX_API_KEY: "${MINIMAX_API_KEY:-}"
+ MINIMAX_MODEL: "${MINIMAX_MODEL:-}"
+ OLLAMA_HOST: "${OLLAMA_HOST:-}"
+ LLM_PROVIDER: "${LLM_PROVIDER:-}"
+ BM25_WEIGHT: "${BM25_WEIGHT:-}"
+ VECTOR_WEIGHT: "${VECTOR_WEIGHT:-}"
+ MAX_TOKENS: "${MAX_TOKENS:-}"
+ TOKEN_BUDGET: "${TOKEN_BUDGET:-}"
+ MAX_OBS_PER_SESSION: "${MAX_OBS_PER_SESSION:-}"
+ CONSOLIDATION_ENABLED: "${CONSOLIDATION_ENABLED:-}"
+ GRAPH_EXTRACTION_ENABLED: "${GRAPH_EXTRACTION_ENABLED:-}"
+ AGENTMEMORY_AUTO_COMPRESS: "${AGENTMEMORY_AUTO_COMPRESS:-}"
+ AGENTMEMORY_INJECT_CONTEXT: "${AGENTMEMORY_INJECT_CONTEXT:-}"
+ AGENTMEMORY_ALLOW_AGENT_SDK: "${AGENTMEMORY_ALLOW_AGENT_SDK:-}"
+ AGENTMEMORY_SESSION_SWEEP_ENABLED: "${AGENTMEMORY_SESSION_SWEEP_ENABLED:-}"
+ AGENTMEMORY_SESSION_SWEEP_STALE_HOURS: "${AGENTMEMORY_SESSION_SWEEP_STALE_HOURS:-}"
+ AGENTMEMORY_FINALIZE_IDLE_MS: "${AGENTMEMORY_FINALIZE_IDLE_MS:-}"
+ AGENTMEMORY_GRAPH_COMPACT_ON_BOOT: "${AGENTMEMORY_GRAPH_COMPACT_ON_BOOT:-}"
+ AGENTMEMORY_DROP_STALE_INDEX: "${AGENTMEMORY_DROP_STALE_INDEX:-}"
+ AGENTMEMORY_AUDIT_RETENTION_MONTHS: "${AGENTMEMORY_AUDIT_RETENTION_MONTHS:-}"
+ AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES: "${AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES:-}"
+ AGENTMEMORY_STATE_BACKEND: "${AGENTMEMORY_STATE_BACKEND:-}"
+ AGENTMEMORY_REDIS_URL: "${AGENTMEMORY_REDIS_URL:-}"
+ AGENTMEMORY_STATE_SAVE_INTERVAL_MS: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-}"
+ AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"
+ AGENT_ID: "${AGENT_ID:-}"
+ TEAM_ID: "${TEAM_ID:-}"
+ TEAM_MODE: "${TEAM_MODE:-}"
+ USER_ID: "${USER_ID:-}"
+ AGENTMEMORY_AGENT_SCOPE: "${AGENTMEMORY_AGENT_SCOPE:-}"
+ SNAPSHOT_DIR: "${SNAPSHOT_DIR:-}"
+ SNAPSHOT_ENABLED: "${SNAPSHOT_ENABLED:-}"
+ SNAPSHOT_INTERVAL: "${SNAPSHOT_INTERVAL:-}"
+ STANDALONE_PERSIST_PATH: "${STANDALONE_PERSIST_PATH:-}"
+ CLAUDE_MEMORY_BRIDGE: "${CLAUDE_MEMORY_BRIDGE:-}"
+ CLAUDE_MEMORY_LINE_BUDGET: "${CLAUDE_MEMORY_LINE_BUDGET:-}"
+ CLAUDE_PROJECT_PATH: "${CLAUDE_PROJECT_PATH:-}"
+ AGENTMEMORY_SUPPRESS_COST_WARNING: "${AGENTMEMORY_SUPPRESS_COST_WARNING:-}"
+ AGENTMEMORY_TOOLS: "${AGENTMEMORY_TOOLS:-}"
+ FALLBACK_PROVIDERS: "${FALLBACK_PROVIDERS:-}"
+ OPENAI_API_VERSION: "${OPENAI_API_VERSION:-}"
+ OPENAI_REASONING_EFFORT: "${OPENAI_REASONING_EFFORT:-}"
+ OPENAI_TIMEOUT_MS: "${OPENAI_TIMEOUT_MS:-}"
+ MINIMAX_BASE_URL: "${MINIMAX_BASE_URL:-}"
+ OPENROUTER_EMBEDDING_MODEL: "${OPENROUTER_EMBEDDING_MODEL:-}"
+ OPENROUTER_EMBEDDING_DIMENSIONS: "${OPENROUTER_EMBEDDING_DIMENSIONS:-}"
+ AGENTMEMORY_LLM_TIMEOUT_MS: "${AGENTMEMORY_LLM_TIMEOUT_MS:-}"
+ AGENTMEMORY_CAPTURE_MAX_ATTEMPTS: "${AGENTMEMORY_CAPTURE_MAX_ATTEMPTS:-}"
+ AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS: "${AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS:-}"
+ AGENTMEMORY_CAPTURE_DEDUP_HOURS: "${AGENTMEMORY_CAPTURE_DEDUP_HOURS:-}"
+ AGENTMEMORY_CAPTURE_INBOX_MAX: "${AGENTMEMORY_CAPTURE_INBOX_MAX:-}"
+ AGENTMEMORY_CAPTURE_DEAD_MAX: "${AGENTMEMORY_CAPTURE_DEAD_MAX:-}"
+ AGENTMEMORY_CAPTURE_EVENTS_MAX: "${AGENTMEMORY_CAPTURE_EVENTS_MAX:-}"
+ AGENTMEMORY_CAPTURE_SPOOL: "${AGENTMEMORY_CAPTURE_SPOOL:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_DIR: "${AGENTMEMORY_CAPTURE_SPOOL_DIR:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES: "${AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS: "${AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS:-}"
+ AGENTMEMORY_IMPORT_ROOT: "${AGENTMEMORY_IMPORT_ROOT:-}"
+ AGENTMEMORY_EXPORT_ROOT: "${AGENTMEMORY_EXPORT_ROOT:-}"
+ AGENTMEMORY_GRAPH_WEIGHT: "${AGENTMEMORY_GRAPH_WEIGHT:-}"
+ SUMMARIZE_CHUNK_SIZE: "${SUMMARIZE_CHUNK_SIZE:-}"
+ SUMMARIZE_CHUNK_CONCURRENCY: "${SUMMARIZE_CHUNK_CONCURRENCY:-}"
+ CONSOLIDATION_DECAY_DAYS: "${CONSOLIDATION_DECAY_DAYS:-}"
+ CONSOLIDATION_INTERVAL_MS: "${CONSOLIDATION_INTERVAL_MS:-}"
+ AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS: "${AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS:-}"
+ AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS: "${AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS:-}"
+ GRAPH_EXTRACTION_BATCH_SIZE: "${GRAPH_EXTRACTION_BATCH_SIZE:-}"
+ AGENTMEMORY_LLM_NOTHINK: "${AGENTMEMORY_LLM_NOTHINK:-}"
+ AGENTMEMORY_REFLECT: "${AGENTMEMORY_REFLECT:-}"
+ AGENTMEMORY_IMAGE_EMBEDDINGS: "${AGENTMEMORY_IMAGE_EMBEDDINGS:-}"
+ AGENTMEMORY_IMAGE_STORE_MAX_BYTES: "${AGENTMEMORY_IMAGE_STORE_MAX_BYTES:-}"
+ AGENTMEMORY_AUDIT_INDEX_PERSIST: "${AGENTMEMORY_AUDIT_INDEX_PERSIST:-}"
+ AGENTMEMORY_INDEX_SAVE_INTERVAL_MS: "${AGENTMEMORY_INDEX_SAVE_INTERVAL_MS:-}"
+ AGENTMEMORY_VECTOR_BUCKET_SIZE: "${AGENTMEMORY_VECTOR_BUCKET_SIZE:-}"
+ AGENTMEMORY_VECTOR_BACKFILL_MAX: "${AGENTMEMORY_VECTOR_BACKFILL_MAX:-}"
+ AGENTMEMORY_VECTOR_BACKFILL: "${AGENTMEMORY_VECTOR_BACKFILL:-}"
+ AGENTMEMORY_SLOTS: "${AGENTMEMORY_SLOTS:-}"
+ AGENTMEMORY_PROVIDER: "${AGENTMEMORY_PROVIDER:-}"
+ AGENTMEMORY_VERBOSE: "${AGENTMEMORY_VERBOSE:-}"
+ OBSIDIAN_AUTO_EXPORT: "${OBSIDIAN_AUTO_EXPORT:-}"
+ AUTO_FORGET_ENABLED: "${AUTO_FORGET_ENABLED:-}"
+ AUTO_FORGET_INTERVAL_MS: "${AUTO_FORGET_INTERVAL_MS:-}"
+ LESSON_DECAY_ENABLED: "${LESSON_DECAY_ENABLED:-}"
+ INSIGHT_DECAY_ENABLED: "${INSIGHT_DECAY_ENABLED:-}"
+ REBUILD_EMBED_BATCH_SIZE: "${REBUILD_EMBED_BATCH_SIZE:-}"
+ RERANK_ENABLED: "${RERANK_ENABLED:-}"
+ PATH: /usr/local/bin:/usr/bin:/bin
+ MALLOC_ARENA_MAX: "2"
diff --git a/docker-compose.yml b/docker-compose.yml
index f0be2cc5..cd236d82 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,68 +1,144 @@
services:
- # One-shot init container: docker creates named volumes root:root mode
- # 755, but the iii-engine image is distroless and runs as UID 65532
- # with no `chown` of its own. Without this, /data is unwritable, the
- # engine silently buffers in RAM, and state evaporates on every
- # restart — the exact symptom v0.9.7's working-directory fix set out
- # to solve. Runs once at compose-up and exits.
- 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", "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 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.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"]
+ agentmemory:
+ build:
+ context: .
+ dockerfile: deploy/Dockerfile
+ args:
+ III_VERSION: "${III_VERSION:-0.25.0}"
+ STATE_VERSION: "${STATE_VERSION:-0.22.20}"
+ HTTP_VERSION: "${HTTP_VERSION:-0.22.7}"
+ restart: unless-stopped
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_DATA_DIR: /data
+ HOME: /data/home
+ III_COMPOSE_STATE_DIR: /data/compose-state
+ III_TELEMETRY_ENABLED: "false"
+ III_ENGINE_PORT: "49134"
+ III_REST_PORT: "3111"
+ III_VIEWER_PORT: "3113"
+ AGENTMEMORY_VIEWER_HOST: 0.0.0.0
+ REST_ALLOWED_ORIGINS: "${REST_ALLOWED_ORIGINS:-http://localhost:${AGENTMEMORY_REST_PORT:-3111},http://127.0.0.1:${AGENTMEMORY_REST_PORT:-3111},http://localhost:${AGENTMEMORY_VIEWER_PORT:-3113},http://127.0.0.1:${AGENTMEMORY_VIEWER_PORT:-3113}}"
+ VIEWER_ALLOWED_HOSTS: "${VIEWER_ALLOWED_HOSTS:-localhost:${AGENTMEMORY_VIEWER_PORT:-3113},127.0.0.1:${AGENTMEMORY_VIEWER_PORT:-3113},[::1]:${AGENTMEMORY_VIEWER_PORT:-3113}}"
+ VIEWER_ALLOWED_ORIGINS: "${VIEWER_ALLOWED_ORIGINS:-http://localhost:${AGENTMEMORY_VIEWER_PORT:-3113},http://127.0.0.1:${AGENTMEMORY_VIEWER_PORT:-3113}}"
+ EMBEDDING_PROVIDER: "${EMBEDDING_PROVIDER:-}"
+ OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
+ OPENAI_API_KEY_FOR_LLM: "${OPENAI_API_KEY_FOR_LLM:-}"
+ OPENAI_BASE_URL: "${OPENAI_BASE_URL:-}"
+ OPENAI_MODEL: "${OPENAI_MODEL:-}"
+ OPENAI_EMBEDDING_API_KEY: "${OPENAI_EMBEDDING_API_KEY:-}"
+ OPENAI_EMBEDDING_BASE_URL: "${OPENAI_EMBEDDING_BASE_URL:-}"
+ OPENAI_EMBEDDING_MODEL: "${OPENAI_EMBEDDING_MODEL:-}"
+ OPENAI_EMBEDDING_DIMENSIONS: "${OPENAI_EMBEDDING_DIMENSIONS:-}"
+ ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+ ANTHROPIC_BASE_URL: "${ANTHROPIC_BASE_URL:-}"
+ ANTHROPIC_MODEL: "${ANTHROPIC_MODEL:-}"
+ GEMINI_API_KEY: "${GEMINI_API_KEY:-}"
+ GEMINI_MODEL: "${GEMINI_MODEL:-}"
+ GOOGLE_API_KEY: "${GOOGLE_API_KEY:-}"
+ VOYAGE_API_KEY: "${VOYAGE_API_KEY:-}"
+ VOYAGE_MODEL: "${VOYAGE_MODEL:-}"
+ COHERE_API_KEY: "${COHERE_API_KEY:-}"
+ COHERE_MODEL: "${COHERE_MODEL:-}"
+ OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:-}"
+ OPENROUTER_MODEL: "${OPENROUTER_MODEL:-}"
+ MINIMAX_API_KEY: "${MINIMAX_API_KEY:-}"
+ MINIMAX_MODEL: "${MINIMAX_MODEL:-}"
+ OLLAMA_HOST: "${OLLAMA_HOST:-}"
+ LLM_PROVIDER: "${LLM_PROVIDER:-}"
+ BM25_WEIGHT: "${BM25_WEIGHT:-}"
+ VECTOR_WEIGHT: "${VECTOR_WEIGHT:-}"
+ MAX_TOKENS: "${MAX_TOKENS:-}"
+ TOKEN_BUDGET: "${TOKEN_BUDGET:-}"
+ MAX_OBS_PER_SESSION: "${MAX_OBS_PER_SESSION:-}"
+ CONSOLIDATION_ENABLED: "${CONSOLIDATION_ENABLED:-}"
+ GRAPH_EXTRACTION_ENABLED: "${GRAPH_EXTRACTION_ENABLED:-}"
+ AGENTMEMORY_AUTO_COMPRESS: "${AGENTMEMORY_AUTO_COMPRESS:-}"
+ AGENTMEMORY_INJECT_CONTEXT: "${AGENTMEMORY_INJECT_CONTEXT:-}"
+ AGENTMEMORY_ALLOW_AGENT_SDK: "${AGENTMEMORY_ALLOW_AGENT_SDK:-}"
+ AGENTMEMORY_SESSION_SWEEP_ENABLED: "${AGENTMEMORY_SESSION_SWEEP_ENABLED:-}"
+ AGENTMEMORY_SESSION_SWEEP_STALE_HOURS: "${AGENTMEMORY_SESSION_SWEEP_STALE_HOURS:-}"
+ AGENTMEMORY_FINALIZE_IDLE_MS: "${AGENTMEMORY_FINALIZE_IDLE_MS:-}"
+ AGENTMEMORY_GRAPH_COMPACT_ON_BOOT: "${AGENTMEMORY_GRAPH_COMPACT_ON_BOOT:-}"
+ AGENTMEMORY_DROP_STALE_INDEX: "${AGENTMEMORY_DROP_STALE_INDEX:-}"
+ AGENTMEMORY_AUDIT_RETENTION_MONTHS: "${AGENTMEMORY_AUDIT_RETENTION_MONTHS:-}"
+ AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES: "${AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES:-}"
+ AGENTMEMORY_STATE_SAVE_INTERVAL_MS: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-}"
+ AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"
+ AGENT_ID: "${AGENT_ID:-}"
+ TEAM_ID: "${TEAM_ID:-}"
+ TEAM_MODE: "${TEAM_MODE:-}"
+ USER_ID: "${USER_ID:-}"
+ AGENTMEMORY_AGENT_SCOPE: "${AGENTMEMORY_AGENT_SCOPE:-}"
+ SNAPSHOT_DIR: "${SNAPSHOT_DIR:-}"
+ SNAPSHOT_ENABLED: "${SNAPSHOT_ENABLED:-}"
+ SNAPSHOT_INTERVAL: "${SNAPSHOT_INTERVAL:-}"
+ STANDALONE_PERSIST_PATH: "${STANDALONE_PERSIST_PATH:-}"
+ CLAUDE_MEMORY_BRIDGE: "${CLAUDE_MEMORY_BRIDGE:-}"
+ CLAUDE_MEMORY_LINE_BUDGET: "${CLAUDE_MEMORY_LINE_BUDGET:-}"
+ CLAUDE_PROJECT_PATH: "${CLAUDE_PROJECT_PATH:-}"
+ AGENTMEMORY_SUPPRESS_COST_WARNING: "${AGENTMEMORY_SUPPRESS_COST_WARNING:-}"
+ AGENTMEMORY_STATE_BACKEND: "${AGENTMEMORY_STATE_BACKEND:-}"
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
+ AGENTMEMORY_TOOLS: "${AGENTMEMORY_TOOLS:-}"
+ FALLBACK_PROVIDERS: "${FALLBACK_PROVIDERS:-}"
+ OPENAI_API_VERSION: "${OPENAI_API_VERSION:-}"
+ OPENAI_REASONING_EFFORT: "${OPENAI_REASONING_EFFORT:-}"
+ OPENAI_TIMEOUT_MS: "${OPENAI_TIMEOUT_MS:-}"
+ MINIMAX_BASE_URL: "${MINIMAX_BASE_URL:-}"
+ OPENROUTER_EMBEDDING_MODEL: "${OPENROUTER_EMBEDDING_MODEL:-}"
+ OPENROUTER_EMBEDDING_DIMENSIONS: "${OPENROUTER_EMBEDDING_DIMENSIONS:-}"
+ AGENTMEMORY_LLM_TIMEOUT_MS: "${AGENTMEMORY_LLM_TIMEOUT_MS:-}"
+ AGENTMEMORY_CAPTURE_MAX_ATTEMPTS: "${AGENTMEMORY_CAPTURE_MAX_ATTEMPTS:-}"
+ AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS: "${AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS:-}"
+ AGENTMEMORY_CAPTURE_DEDUP_HOURS: "${AGENTMEMORY_CAPTURE_DEDUP_HOURS:-}"
+ AGENTMEMORY_CAPTURE_INBOX_MAX: "${AGENTMEMORY_CAPTURE_INBOX_MAX:-}"
+ AGENTMEMORY_CAPTURE_DEAD_MAX: "${AGENTMEMORY_CAPTURE_DEAD_MAX:-}"
+ AGENTMEMORY_CAPTURE_EVENTS_MAX: "${AGENTMEMORY_CAPTURE_EVENTS_MAX:-}"
+ AGENTMEMORY_CAPTURE_SPOOL: "${AGENTMEMORY_CAPTURE_SPOOL:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_DIR: "${AGENTMEMORY_CAPTURE_SPOOL_DIR:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES: "${AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES:-}"
+ AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS: "${AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS:-}"
+ AGENTMEMORY_IMPORT_ROOT: "${AGENTMEMORY_IMPORT_ROOT:-}"
+ AGENTMEMORY_EXPORT_ROOT: "${AGENTMEMORY_EXPORT_ROOT:-}"
+ AGENTMEMORY_GRAPH_WEIGHT: "${AGENTMEMORY_GRAPH_WEIGHT:-}"
+ SUMMARIZE_CHUNK_SIZE: "${SUMMARIZE_CHUNK_SIZE:-}"
+ SUMMARIZE_CHUNK_CONCURRENCY: "${SUMMARIZE_CHUNK_CONCURRENCY:-}"
+ CONSOLIDATION_DECAY_DAYS: "${CONSOLIDATION_DECAY_DAYS:-}"
+ CONSOLIDATION_INTERVAL_MS: "${CONSOLIDATION_INTERVAL_MS:-}"
+ AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS: "${AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS:-}"
+ AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS: "${AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS:-}"
+ GRAPH_EXTRACTION_BATCH_SIZE: "${GRAPH_EXTRACTION_BATCH_SIZE:-}"
+ AGENTMEMORY_LLM_NOTHINK: "${AGENTMEMORY_LLM_NOTHINK:-}"
+ AGENTMEMORY_REFLECT: "${AGENTMEMORY_REFLECT:-}"
+ AGENTMEMORY_IMAGE_EMBEDDINGS: "${AGENTMEMORY_IMAGE_EMBEDDINGS:-}"
+ AGENTMEMORY_IMAGE_STORE_MAX_BYTES: "${AGENTMEMORY_IMAGE_STORE_MAX_BYTES:-}"
+ AGENTMEMORY_AUDIT_INDEX_PERSIST: "${AGENTMEMORY_AUDIT_INDEX_PERSIST:-}"
+ AGENTMEMORY_INDEX_SAVE_INTERVAL_MS: "${AGENTMEMORY_INDEX_SAVE_INTERVAL_MS:-}"
+ AGENTMEMORY_VECTOR_BUCKET_SIZE: "${AGENTMEMORY_VECTOR_BUCKET_SIZE:-}"
+ AGENTMEMORY_VECTOR_BACKFILL_MAX: "${AGENTMEMORY_VECTOR_BACKFILL_MAX:-}"
+ AGENTMEMORY_VECTOR_BACKFILL: "${AGENTMEMORY_VECTOR_BACKFILL:-}"
+ AGENTMEMORY_SLOTS: "${AGENTMEMORY_SLOTS:-}"
+ AGENTMEMORY_PROVIDER: "${AGENTMEMORY_PROVIDER:-}"
+ AGENTMEMORY_VERBOSE: "${AGENTMEMORY_VERBOSE:-}"
+ OBSIDIAN_AUTO_EXPORT: "${OBSIDIAN_AUTO_EXPORT:-}"
+ AUTO_FORGET_ENABLED: "${AUTO_FORGET_ENABLED:-}"
+ AUTO_FORGET_INTERVAL_MS: "${AUTO_FORGET_INTERVAL_MS:-}"
+ LESSON_DECAY_ENABLED: "${LESSON_DECAY_ENABLED:-}"
+ INSIGHT_DECAY_ENABLED: "${INSIGHT_DECAY_ENABLED:-}"
+ REBUILD_EMBED_BATCH_SIZE: "${REBUILD_EMBED_BATCH_SIZE:-}"
+ RERANK_ENABLED: "${RERANK_ENABLED:-}"
+ MALLOC_ARENA_MAX: "2"
ports:
- - "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"
+ - "127.0.0.1:${AGENTMEMORY_REST_PORT:-3111}:3111"
+ - "127.0.0.1:${AGENTMEMORY_VIEWER_PORT:-3113}:3113"
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
+ - ${AGENTMEMORY_DATA_DIR:-iii-data}:/data
+ healthcheck:
+ test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3111/agentmemory/livez').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+ interval: 30s
+ timeout: 5s
+ start_period: 60s
+ retries: 3
logging:
driver: json-file
options:
diff --git a/docs/reliability/state-storage.md b/docs/reliability/state-storage.md
new file mode 100644
index 00000000..c6122a0d
--- /dev/null
+++ b/docs/reliability/state-storage.md
@@ -0,0 +1,82 @@
+# State storage
+
+AgentMemory stores sessions, observations, memories and related records in a file-backed key-value store by default. Redis is an optional backend. `agentmemory status` and the viewer's Health page report the active backend and whether it responds, without exposing its connection URL.
+
+## File storage
+
+The default store holds records in memory and periodically writes them to `state_store.db` under the selected data directory. CLI and Docker deployments use a two-second save interval. `AGENTMEMORY_STATE_SAVE_INTERVAL_MS` changes that interval, from 100 to 3,600,000 milliseconds.
+
+An accepted write is not necessarily on disk yet. Capture clients retain acknowledged events for the configured save interval plus a safety margin and replay them after a restart when needed. This does not establish power-loss durability for every API write. Stop AgentMemory cleanly before taking a filesystem backup, and preserve the entire data directory.
+
+## Redis
+
+For a CLI installation, add these settings to `~/.agentmemory/.env`, then restart AgentMemory:
+
+```env
+AGENTMEMORY_STATE_BACKEND=redis
+AGENTMEMORY_REDIS_URL=redis://localhost:6379/0
+```
+
+`AGENTMEMORY_STATE_BACKEND` accepts `file` or `redis`; an unknown value stops startup. Redis requires a connection URL. See the [deployment guide](../../deploy/README.md) for Docker configuration.
+
+- **Transport:** the pinned state worker supports plain `redis://`, not `rediss://`. Use a local/private network or an encrypted tunnel for a TLS-only service. Percent-encode reserved characters in URL credentials.
+- **Isolation:** give each AgentMemory instance its own Redis database or server. Application locks coordinate one process, not multiple instances sharing a database.
+- **Persistence:** configure Redis persistence for the loss window you can tolerate. Enable AOF with `appendonly yes` when snapshot-only persistence is insufficient. Acknowledging a write does not guarantee it has been flushed to disk.
+- **Retention:** use `maxmemory-policy noeviction`. Eviction policies can silently discard memories when Redis reaches its memory limit.
+- **Credentials:** use a restricted Redis ACL user. The data directory and generated worker configuration can contain the URL, including credentials; restrict their permissions and do not commit or share them.
+
+Redis stores each scope as a hash. Listing a scope reads the whole hash, so Redis does not make large scope reads bounded or a single worker connection parallel. AgentMemory orders Redis results by record creation time, with timestamp and ID fallbacks. Supported partial updates use a local per-key lock to preserve values such as `tags: []`. Legacy audit migration reads Redis records instead of inspecting files.
+
+Viewer updates use the AgentMemory SSE endpoint. They do not use Redis pub/sub. A Redis outage affects state reads and writes; status reports an unavailable state store.
+
+## Moving between backends
+
+Changing `AGENTMEMORY_STATE_BACKEND` selects the target backend's existing data. It does not copy or delete the old backend. A new target starts empty.
+
+Pause capture and other writes during migration. Keep a backup of the original backend until you have checked the destination. Export/import transfers the supported memory and session collections; it is not a replacement for a full backup of credentials and operational state.
+
+Run the following commands in a new private directory. They require `curl` and `jq` and work in bash or zsh. They use the local daemon on port 3111 and read its generated secret from `~/.agentmemory/secret`. If you configured an explicit secret, set `AGENTMEMORY_SECRET` in the shell to the same value. Do not enable shell tracing while running them.
+
+While the old backend is still running, export and validate the backup:
+
+```sh
+(
+ set -eu
+ umask 077
+ agentmemory_secret=${AGENTMEMORY_SECRET:-$(cat "$HOME/.agentmemory/secret")}
+ test -n "$agentmemory_secret"
+ curl -fsS -H "Authorization: Bearer $agentmemory_secret" \
+ http://127.0.0.1:3111/agentmemory/export > backup.json
+ jq -e '
+ (.version | type == "string") and
+ (.exportedAt | type == "string") and
+ (.sessions | type == "array") and
+ (.memories | type == "array") and
+ (.summaries | type == "array") and
+ (.observations | type == "object") and
+ (.pagination == null) and (.collectionPagination == null)
+ ' backup.json > /dev/null
+)
+```
+
+Continue only after that block exits successfully. Stop AgentMemory, update the backend settings, and start it again. Import into the new backend:
+
+```sh
+(
+ set -eu
+ umask 077
+ agentmemory_secret=${AGENTMEMORY_SECRET:-$(cat "$HOME/.agentmemory/secret")}
+ test -n "$agentmemory_secret"
+ jq -n --slurpfile data backup.json \
+ '{exportData: $data[0], strategy: "merge"}' > import.json
+ curl -fsS -H "Authorization: Bearer $agentmemory_secret" \
+ -H 'Content-Type: application/json' \
+ --data-binary @import.json \
+ http://127.0.0.1:3111/agentmemory/import > import-result.json
+ jq -e '.success == true' import-result.json > /dev/null
+)
+```
+
+Check `import-result.json`, confirm representative old memories are recalled, and allow the configured persistence window before testing a restart. Keep the export private: it contains memory contents. Once verified, resume capture and writes.
+
+For larger stores, `/agentmemory/export` accepts `maxSessions` and `offset` for sessions; `collectionLimit` and `collectionOffset` for other collections; and `collections` for a named subset. Collect every page before switching backends and import each with `merge`. The single-export validation above deliberately rejects paginated or selected exports. Import also supports `skip` and `replace`; `replace` requires a complete export and deletes destination records.
diff --git a/docs/upgrades/iii-0.25.md b/docs/upgrades/iii-0.25.md
new file mode 100644
index 00000000..c91039f2
--- /dev/null
+++ b/docs/upgrades/iii-0.25.md
@@ -0,0 +1,32 @@
+# Upgrading the AgentMemory runtime to iii 0.25
+
+This release pins the engine, `iii-sdk` and `@iii-dev/helpers` to 0.25.0. Worker Compose starts the existing `[email protected]` and `[email protected]` registry workers with AgentMemory. Their versions are independent of the engine version.
+
+## Before upgrading
+
+Stop the running instance with its currently installed CLI before replacing the package:
+
+```sh
+agentmemory stop
+npm install -g @agentmemory/agentmemory@latest
+agentmemory
+agentmemory status
+```
+
+Use the same `--instance`, `--port` and `--data-dir` flags you used to start it. Preserve the data directory and `~/.agentmemory`, including its secret. The new CLI will not adopt a running engine with a different version or overwrite a user-managed global iii binary. On macOS and Linux it installs the verified engine under `~/.agentmemory/bin`; native Windows still requires manual installation of the pinned binary.
+
+Existing file state remains at `state_store.db`; this upgrade does not convert or delete it. Docker deployments keep their persistent `/data` volume and use the shared `deploy/Dockerfile`. `AGENTMEMORY_USE_DOCKER` is no longer a CLI startup mode. Stop a legacy Docker-managed runtime using the command printed by the CLI, then follow the [deployment guide](../../deploy/README.md). Keep `AGENTMEMORY_STATE_BACKEND=redis` and `AGENTMEMORY_REDIS_URL` together when using Redis.
+
+## Capabilities and compatibility
+
+- MCP tools, HTTP routes, capture, recall, search, export/import and the AgentMemory viewer keep their existing interfaces.
+- The viewer remains on port 3113 by default. Live updates use authenticated SSE at `/agentmemory/viewer/events` on the REST port. Port 3112 is no longer used.
+- `/agentmemory/status` reports the configured engine pin as `service.enginePinnedVersion`, replacing the old `engineVersion` field. This is the supported version, not a probe of an arbitrary remote engine.
+- `registerTrigger` and `registerTriggerType` remain supported by iii 0.25, with deprecation warnings. HTTP and state providers still use these APIs; their warnings do not mean route registration failed.
+- iii 0.25 can dispatch calls to a worker's own functions locally. Engine-side spans differ for those calls; SDK tracing and state-worker persistence still apply.
+
+## Retired engine console
+
+iii 0.25 removes the bundled console. `agentmemory console` prints migration guidance and the selected viewer URL; it does not install or launch an engine console. `--console-port` and forwarded console flags no longer launch a service. The AgentMemory viewer and `agentmemory status` remain available. See the [upstream console guidance](https://github.com/iii-hq/iii/blob/iii/v0.25.0/docs/using-iii/console.mdx) for the separate ADE console. ADE also defaults to port 3113, so give it a different port if you add it to a custom deployment alongside the AgentMemory viewer.
+
+Custom `iii-config.yaml` files and `AGENTMEMORY_III_CONFIG` are no longer used by the CLI. It generates an isolated Worker Compose project in the chosen data directory. The old `iii worker add` command is also gone. Declare extra workers under `containers` in a custom Compose manifest; changes to the CLI-generated manifest are overwritten on the next start. Keep custom deployments separate and consult the [iii 0.25 migration guide](https://github.com/iii-hq/iii/blob/iii/v0.25.0/docs/upgrading/from-0-24-x.mdx).
diff --git a/eval/README.md b/eval/README.md
index 73aae2c8..e09121e9 100644
--- a/eval/README.md
+++ b/eval/README.md
@@ -15,7 +15,7 @@ npm run eval:lifecycle
npm run eval:recall
```
-The defaults are local and require no model API keys. The HTTP adapter and lifecycle suite require an installed **iii 0.22.1** binary. Set `AGENTMEMORY_EVAL_III` to its absolute path, or use the binary installed by AgentMemory at `~/.agentmemory/bin/iii`.
+The defaults are local and require no model API keys. The HTTP adapter and lifecycle suite require an installed **iii 0.25.0** binary, matching the version pinned by the CLI. Set `AGENTMEMORY_EVAL_III` to its absolute path, or use the binary installed by AgentMemory at `~/.agentmemory/bin/iii`.
Each HTTP case launches the actual built CLI in a new temporary home, state directory, and port block, with an environment that excludes provider credentials. It uses the noop compression provider, with automatic compression, consolidation, and graph extraction disabled. The parent home and existing daemon are not used. Cleanup runs even after a failed query. `AGENTMEMORY_EVAL_KEEP=1` preserves scratch files for diagnosis; the daemon still stops. This sandbox supports macOS/Linux and needs permission to bind local ports.
diff --git a/eval/runner/sandbox.ts b/eval/runner/sandbox.ts
index 8f547a88..4901a074 100644
--- a/eval/runner/sandbox.ts
+++ b/eval/runner/sandbox.ts
@@ -4,9 +4,9 @@ import { createServer } from "node:net";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { repositoryRoot, enginePath } from "./fingerprint.js";
+import { III_PINNED_VERSION } from "../../src/version.js";
const cli = join(repositoryRoot, "dist/cli.mjs");
-const engineVersion = "0.22.1";
const active = new Set<LocalSandbox>();
function pause(ms: number): Promise<void> {
@@ -24,7 +24,7 @@ async function free(port: number): Promise<boolean> {
async function pickPort(): Promise<number> {
for (let attempt = 0; attempt < 100; attempt++) {
const base = 12000 + Math.floor(Math.random() * 6000);
- const ports = [base, base + 1, base + 2, base + 3, base + 6353, base + 46023];
+ const ports = [base, base + 2, base + 6353, base + 46023];
if ((await Promise.all(ports.map(free))).every(Boolean)) return base;
}
throw new Error("No free evaluation port block");
@@ -36,6 +36,20 @@ function kill(pid: number | undefined): void {
try { process.kill(pid, "SIGKILL"); } catch {}
}
+function killOwnedProcess(pid: number | undefined, expected: (command: string) => boolean): void {
+ if (!pid) return;
+ try {
+ const command = execFileSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+ if (!command || !expected(command)) return;
+ let group = 0;
+ try { group = Number(execFileSync("ps", ["-p", String(pid), "-o", "pgid="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim()); } catch {}
+ if (group === pid) {
+ try { process.kill(-pid, "SIGKILL"); } catch {}
+ }
+ try { process.kill(pid, "SIGKILL"); } catch {}
+ } catch {}
+}
+
export interface Sandbox {
request<T = any>(path: string, body?: unknown, method?: string): Promise<T>;
close(): Promise<void>;
@@ -48,14 +62,15 @@ export class LocalSandbox implements Sandbox {
private port = 0;
private child?: ChildProcess;
private enginePid?: number;
+ private composePid?: number;
private env: NodeJS.ProcessEnv = {};
async start(): Promise<void> {
if (!existsSync(cli)) throw new Error("Build AgentMemory before live evaluation: npm run build");
const engine = enginePath();
- if (!existsSync(engine)) throw new Error("Set AGENTMEMORY_EVAL_III to an installed iii " + engineVersion + " binary");
+ if (!existsSync(engine)) throw new Error("Set AGENTMEMORY_EVAL_III to an installed iii " + III_PINNED_VERSION + " binary");
const version = execFileSync(engine, ["--version"], { encoding: "utf8" }).trim();
- if (version !== engineVersion) throw new Error("Evaluation requires iii " + engineVersion + ", got " + version);
+ if (version !== III_PINNED_VERSION) throw new Error("Evaluation requires iii " + III_PINNED_VERSION + ", got " + version);
const bin = join(this.home, ".agentmemory/bin");
mkdirSync(bin, { recursive: true });
copyFileSync(engine, join(bin, "iii"));
@@ -92,8 +107,7 @@ export class LocalSandbox implements Sandbox {
try {
await this.request("/livez");
await this.request("/health");
- const pidFile = join(this.home, ".agentmemory/iii.pid");
- if (existsSync(pidFile)) this.enginePid = Number(readFileSync(pidFile, "utf8").trim());
+ this.loadRuntimePids();
return;
} catch {
await pause(250);
@@ -120,7 +134,8 @@ export class LocalSandbox implements Sandbox {
}
async stop(): Promise<void> {
- if (!this.child || this.child.exitCode !== null || this.child.signalCode) return;
+ if (!this.child) return;
+ this.loadRuntimePids();
await new Promise<void>((resolvePromise, reject) => {
const child = spawn(process.execPath, [cli, "stop", "--port", String(this.port), "--data-dir", join(this.directory, "state")], {
cwd: this.directory, env: this.env, stdio: "ignore",
@@ -135,14 +150,48 @@ export class LocalSandbox implements Sandbox {
});
const deadline = Date.now() + 10_000;
while (Date.now() < deadline && this.child.exitCode === null && !this.child.signalCode) await pause(50);
- if (this.child.exitCode === null && !this.child.signalCode) throw new Error("Sandbox worker remained alive after stop");
+ if (this.child.exitCode === null && !this.child.signalCode) {
+ this.child.kill("SIGTERM");
+ const terminateDeadline = Date.now() + 2_000;
+ while (Date.now() < terminateDeadline && this.child.exitCode === null && !this.child.signalCode) await pause(50);
+ if (this.child.exitCode === null && !this.child.signalCode) this.child.kill("SIGKILL");
+ }
+ const ports = [this.port, this.port + 2, this.port + 6353, this.port + 46023];
+ const portsDeadline = Date.now() + 15_000;
+ while (Date.now() < portsDeadline && !(await Promise.all(ports.map(free))).every(Boolean)) await pause(100);
+ if (!(await Promise.all(ports.map(free))).every(Boolean)) throw new Error("Sandbox Worker Compose runtime left ports open after stop");
}
- forceStop(): void {
+ private loadRuntimePids(): void {
+ const stateFile = join(this.home, ".agentmemory/engine-state.json");
+ try {
+ const state = JSON.parse(readFileSync(stateFile, "utf8")) as {
+ kind?: string; restPort?: number; file?: string; stateDir?: string; binPath?: string; namespace?: string; composePid?: number; enginePid?: number;
+ };
+ const expectedBin = join(this.home, ".agentmemory/bin/iii");
+ if (state.kind !== "compose" || state.restPort !== this.port || state.binPath !== expectedBin ||
+ !state.file?.startsWith(this.directory + "/")) return;
+ this.composePid = state.composePid;
+ this.enginePid = state.enginePid;
+ } catch {}
const pidFile = join(this.home, ".agentmemory/iii.pid");
if (!this.enginePid && existsSync(pidFile)) this.enginePid = Number(readFileSync(pidFile, "utf8").trim());
+ }
+
+ forceStop(): void {
+ this.loadRuntimePids();
kill(this.child?.pid);
- kill(this.enginePid);
+ const stateFile = join(this.home, ".agentmemory/engine-state.json");
+ try {
+ const state = JSON.parse(readFileSync(stateFile, "utf8")) as { file?: string; stateDir?: string; namespace?: string };
+ const file = state.file;
+ const stateDir = state.stateDir;
+ const namespace = state.namespace;
+ if (file?.startsWith(this.directory + "/") && stateDir?.startsWith(this.directory + "/") && namespace) {
+ killOwnedProcess(this.composePid, (command) => command.includes("compose --namespace") && command.includes(namespace) && command.includes(file));
+ killOwnedProcess(this.enginePid, (command) => command.includes("--config") && command.includes(namespace) && command.includes(stateDir));
+ }
+ } catch {}
}
async restart(): Promise<void> {
diff --git a/examples/python/README.md b/examples/python/README.md
index 3e4d3e59..2f37613f 100644
--- a/examples/python/README.md
+++ b/examples/python/README.md
@@ -3,19 +3,19 @@
agentmemory registers its core operations as iii functions (`mem::remember`,
`mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any
language with an iii SDK can call them directly over the WebSocket transport
-on `ws://localhost:49134` — no separate REST client needed.
+on `ws://127.0.0.1:49134` — no separate REST client needed.
This example uses the official Python SDK.
## Install
```bash
-pip install iii-sdk==0.22.1
+pip install iii-sdk==0.25.0
```
## Quickstart
-Start the agentmemory daemon (defaults to `ws://localhost:49134`, REST on
+Start the agentmemory daemon (defaults to `ws://127.0.0.1:49134`, REST on
`:3111`):
```bash
@@ -25,10 +25,12 @@ npx -y @agentmemory/agentmemory
Then from Python:
```python
-from iii import register_worker
+import os
+from iii import InitOptions, register_worker
-iii = register_worker("ws://localhost:49134")
-iii.connect()
+engine_url = os.environ.get("AGENTMEMORY_III_URL", "ws://127.0.0.1:49134")
+namespace = os.environ.get("AGENTMEMORY_III_NAMESPACE", "agentmemory-3111")
+iii = register_worker(engine_url, InitOptions(namespace=namespace))
iii.trigger({
"function_id": "mem::remember",
@@ -45,6 +47,7 @@ hits = iii.trigger({
"payload": {"project": "demo", "query": "how do tokens refresh", "limit": 5},
})
print(hits)
+iii.shutdown()
```
## Functions exposed
@@ -69,3 +72,7 @@ is lower latency.
budget.
Both scripts assume the daemon is already running.
+
+For a non-default local instance, set `AGENTMEMORY_III_URL` to its engine
+WebSocket URL and `AGENTMEMORY_III_NAMESPACE` to its namespace (for example,
+`ws://127.0.0.1:49834` and `agentmemory-3811` for `--instance 7`).
diff --git a/examples/python/observe_and_recall.py b/examples/python/observe_and_recall.py
index b9c65de5..9de7dc25 100644
--- a/examples/python/observe_and_recall.py
+++ b/examples/python/observe_and_recall.py
@@ -4,7 +4,7 @@ Pattern: send hook-style observations during a coding session, then ask
agentmemory to render the most relevant context back at a fixed token budget.
Prerequisites:
- pip install iii-sdk==0.22.1
+ pip install iii-sdk==0.25.0
npx -y @agentmemory/agentmemory
Run:
@@ -12,7 +12,8 @@ Run:
"""
from datetime import datetime, timezone
-from iii import register_worker
+import os
+from iii import InitOptions, register_worker
SESSION_ID = "py-example-session-001"
@@ -24,43 +25,47 @@ def now_iso() -> str:
def main() -> None:
- iii = register_worker("ws://localhost:49134")
- iii.connect()
-
- observations = [
- ("PreToolUse", {"tool": "Bash", "command": "cargo test"}),
- ("PostToolUse", {"tool": "Bash", "exit_code": 0}),
- ("UserPromptSubmit", {"prompt": "refactor auth middleware to use HMAC"}),
- ]
-
- for hook_type, data in observations:
- iii.trigger(
+ iii = register_worker(
+ os.environ.get("AGENTMEMORY_III_URL", "ws://127.0.0.1:49134"),
+ InitOptions(namespace=os.environ.get("AGENTMEMORY_III_NAMESPACE", "agentmemory-3111")),
+ )
+ try:
+ observations = [
+ ("PreToolUse", {"tool": "Bash", "command": "cargo test"}),
+ ("PostToolUse", {"tool": "Bash", "exit_code": 0}),
+ ("UserPromptSubmit", {"prompt": "refactor auth middleware to use HMAC"}),
+ ]
+
+ for hook_type, data in observations:
+ iii.trigger(
+ {
+ "function_id": "mem::observe",
+ "payload": {
+ "hookType": hook_type,
+ "sessionId": SESSION_ID,
+ "project": PROJECT,
+ "cwd": "/home/user/service",
+ "timestamp": now_iso(),
+ "data": data,
+ },
+ }
+ )
+
+ context = iii.trigger(
{
- "function_id": "mem::observe",
+ "function_id": "mem::context",
"payload": {
- "hookType": hook_type,
"sessionId": SESSION_ID,
"project": PROJECT,
- "cwd": "/home/user/service",
- "timestamp": now_iso(),
- "data": data,
+ "budget": 2000,
},
}
)
- context = iii.trigger(
- {
- "function_id": "mem::context",
- "payload": {
- "sessionId": SESSION_ID,
- "project": PROJECT,
- "budget": 2000,
- },
- }
- )
-
- print(f"Rendered context ({context.get('token_count', 0)} tokens):\n")
- print(context.get("text", ""))
+ print(f"Rendered context ({context.get('token_count', 0)} tokens):\n")
+ print(context.get("text", ""))
+ finally:
+ iii.shutdown()
if __name__ == "__main__":
diff --git a/examples/python/quickstart.py b/examples/python/quickstart.py
index 0339e079..4d1ba6f7 100644
--- a/examples/python/quickstart.py
+++ b/examples/python/quickstart.py
@@ -1,45 +1,50 @@
"""Minimal agentmemory usage via iii-sdk.
Prerequisites:
- pip install iii-sdk==0.22.1
- npx -y @agentmemory/agentmemory # daemon at ws://localhost:49134
+ pip install iii-sdk==0.25.0
+ npx -y @agentmemory/agentmemory # daemon at ws://127.0.0.1:49134
Run:
python examples/python/quickstart.py
"""
-from iii import register_worker
+import os
+from iii import InitOptions, register_worker
def main() -> None:
- iii = register_worker("ws://localhost:49134")
- iii.connect()
-
- iii.trigger(
- {
- "function_id": "mem::remember",
- "payload": {
- "project": "demo",
- "title": "auth-stack",
- "content": "Service uses HMAC bearer tokens; refresh every 24h.",
- "concepts": ["auth", "hmac", "refresh"],
- },
- }
+ iii = register_worker(
+ os.environ.get("AGENTMEMORY_III_URL", "ws://127.0.0.1:49134"),
+ InitOptions(namespace=os.environ.get("AGENTMEMORY_III_NAMESPACE", "agentmemory-3111")),
)
-
- hits = iii.trigger(
- {
- "function_id": "mem::smart-search",
- "payload": {
- "project": "demo",
- "query": "how do tokens refresh",
- "limit": 5,
- },
- }
- )
-
- for memory in hits.get("results", []):
- print(f"[{memory.get('score', 0):.3f}] {memory.get('title')}: {memory.get('content')}")
+ try:
+ iii.trigger(
+ {
+ "function_id": "mem::remember",
+ "payload": {
+ "project": "demo",
+ "title": "auth-stack",
+ "content": "Service uses HMAC bearer tokens; refresh every 24h.",
+ "concepts": ["auth", "hmac", "refresh"],
+ },
+ }
+ )
+
+ hits = iii.trigger(
+ {
+ "function_id": "mem::smart-search",
+ "payload": {
+ "project": "demo",
+ "query": "how do tokens refresh",
+ "limit": 5,
+ },
+ }
+ )
+
+ for memory in hits.get("results", []):
+ print(f"[{memory.get('score', 0):.3f}] {memory.get('title')}: {memory.get('content')}")
+ finally:
+ iii.shutdown()
if __name__ == "__main__":
diff --git a/iii-config.docker.yaml b/iii-config.docker.yaml
deleted file mode 100644
index 4cc638a4..00000000
--- a/iii-config.docker.yaml
+++ /dev/null
@@ -1,53 +0,0 @@
-workers:
- - name: iii-http
- config:
- port: ${III_REST_PORT:3111}
- host: 0.0.0.0
- default_timeout: 180000
- cors:
- 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:
- adapter:
- name: builtin
- - name: iii-pubsub
- config:
- adapter:
- name: local
- - name: iii-cron
- config:
- adapter:
- name: kv
- - name: iii-stream
- config:
- 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.
- sampling_ratio: 0.1
- metrics_enabled: true
- logs_enabled: true
- logs_console_output: false
diff --git a/iii-config.yaml b/iii-config.yaml
deleted file mode 100644
index a81d7881..00000000
--- a/iii-config.yaml
+++ /dev/null
@@ -1,57 +0,0 @@
-workers:
- - name: iii-http
- config:
- port: 3111
- host: 127.0.0.1
- 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_methods: [GET, POST, PUT, DELETE, OPTIONS]
- - name: iii-state
- config:
- adapter:
- name: kv
- config:
- store_method: file_based
- save_interval_ms: 2000
- file_path: ./data/state_store.db
- - name: iii-queue
- config:
- adapter:
- name: builtin
- - name: iii-pubsub
- config:
- adapter:
- name: local
- - name: iii-cron
- config:
- adapter:
- name: kv
- - name: iii-stream
- config:
- port: 3112
- host: 127.0.0.1
- adapter:
- 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
- # 0.1 instead of 1.0: at full sampling under sustained load the
- # log subscriber falls behind, the worker emits a "Log trigger
- # 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.
- sampling_ratio: 0.1
- metrics_enabled: true
- logs_enabled: true
- # Console output is off by default; the feedback path needs the
- # console layer to amplify. Re-enable per-session via env if you
- # need verbose tracing for debugging.
- logs_console_output: false
diff --git a/package.json b/package.json
index fb7dfc0f..a63663d3 100644
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
"agentmemory": "dist/cli.mjs"
},
"scripts": {
- "build": "tsdown && (cp iii-config.yaml dist/ 2>/dev/null || true) && (cp iii-config.docker.yaml dist/ 2>/dev/null || true) && (cp docker-compose.yml dist/ 2>/dev/null || true) && (cp .env.example dist/ 2>/dev/null || true) && mkdir -p dist/viewer && cp src/viewer/index.html dist/viewer/ && cp src/viewer/favicon.svg dist/viewer/",
+ "build": "tsdown && rm -f dist/iii-config.yaml dist/iii-config.docker.yaml dist/docker-compose.yml && (cp .env.example dist/ 2>/dev/null || true) && mkdir -p dist/viewer && cp src/viewer/index.html dist/viewer/ && cp src/viewer/favicon.svg dist/viewer/",
"dev": "tsx src/index.ts",
"start": "node dist/cli.mjs",
"migrate": "node dist/functions/migrate.js",
@@ -73,9 +73,6 @@
"integrations/omp/",
"integrations/hermes/",
"integrations/openclaw/",
- "iii-config.yaml",
- "iii-config.docker.yaml",
- "docker-compose.yml",
".env.example",
"LICENSE",
"README.md",
@@ -92,8 +89,8 @@
"@anthropic-ai/sdk": "^0.100.1",
"@clack/prompts": "^1.2.0",
"dotenv": "^18.0.3",
- "@iii-dev/helpers": "0.22.1",
- "iii-sdk": "0.22.1",
+ "@iii-dev/helpers": "0.25.0",
+ "iii-sdk": "0.25.0",
"picocolors": "^1.1.1",
"zod": "^4.0.0",
"yaml": "^2.8.1",
diff --git a/plugin/opencode/README.md b/plugin/opencode/README.md
index 817a20aa..50ba2676 100644
--- a/plugin/opencode/README.md
+++ b/plugin/opencode/README.md
@@ -440,7 +440,7 @@ agentmemory ──push──▶ OpenCode system prompt
### Why OpenCode goes direct
-agentmemory already persists everything in SQLite (`data/state_store.db`). Adding an intermediate MEMORY.md file would duplicate data, introduce sync lag, and require the model to re-parse structured context from markdown. Direct injection delivers the same data with lower latency and zero staleness — the agent always sees what agentmemory knows right now.
+agentmemory persists state through the iii state worker, using file-backed KV (`data/state_store.db`) by default or Redis when configured. Adding an intermediate MEMORY.md file would duplicate data, introduce sync lag, and require the model to re-parse structured context from markdown. Direct injection delivers the same data with lower latency and zero staleness — the agent always sees what agentmemory knows right now.
## Slash commands
diff --git a/plugin/scripts/_capture.mjs b/plugin/scripts/_capture.mjs
index 9fd588a8..eb568a24 100644
--- a/plugin/scripts/_capture.mjs
+++ b/plugin/scripts/_capture.mjs
@@ -6,7 +6,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
//#region src/secret-store.ts
const SECRET_KEY = "AGENTMEMORY_SECRET";
function agentmemoryHomeDir() {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
function secretFilePath() {
return join(agentmemoryHomeDir(), "secret");
@@ -30,7 +30,7 @@ function unquote(value) {
function readEnvFileSecret() {
let content;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -46,13 +46,29 @@ function readEnvFileSecret() {
}
return found;
}
-function readStoredSecret() {
+function readSecretFile(path) {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env = process.env) {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [
+ join(dataDir, "secret"),
+ join(dataDir, ".hmac"),
+ join(dataDir, "..", ".hmac")
+ ];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
function isLoopbackUrl(url) {
let hostname;
try {
@@ -68,7 +84,10 @@ function resolveClientSecret(baseUrl, env = process.env) {
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+ return join(homedir(), ".agentmemory", "secret");
}
//#endregion
//#region src/capture/event-id.ts
@@ -282,7 +301,7 @@ const IMAGE_PLACEHOLDER = "[image dropped from capture spool]";
const BOOT_ID_RE = /^[A-Za-z0-9]{8,64}$/;
const SENT_FILE_RE = /^([A-Za-z0-9]{8,64})-(\d+)\.jsonl$/;
const SENT_BUCKET_MS = 1e3;
-const MAX_DURABLE_AFTER_MS = 10 * 6e4;
+const MAX_DURABLE_AFTER_MS = 61 * 6e4;
function emptyStats() {
return {
spooled: 0,
diff --git a/plugin/scripts/plugin-bridge.mjs b/plugin/scripts/plugin-bridge.mjs
index 160dbb80..75203ef5 100644
--- a/plugin/scripts/plugin-bridge.mjs
+++ b/plugin/scripts/plugin-bridge.mjs
@@ -8,7 +8,7 @@ const VERSION = "0.9.30";
//#region src/secret-store.ts
const SECRET_KEY = "AGENTMEMORY_SECRET";
function agentmemoryHomeDir() {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
function secretFilePath() {
return join(agentmemoryHomeDir(), "secret");
@@ -32,7 +32,7 @@ function unquote(value) {
function readEnvFileSecret() {
let content;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -48,13 +48,29 @@ function readEnvFileSecret() {
}
return found;
}
-function readStoredSecret() {
+function readSecretFile(path) {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env = process.env) {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [
+ join(dataDir, "secret"),
+ join(dataDir, ".hmac"),
+ join(dataDir, "..", ".hmac")
+ ];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
function isLoopbackUrl(url) {
let hostname;
try {
@@ -70,7 +86,10 @@ function resolveClientSecret(baseUrl, env = process.env) {
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+ return join(homedir(), ".agentmemory", "secret");
}
//#endregion
//#region src/mcp/rest-proxy.ts
diff --git a/plugin/scripts/post-commit.mjs b/plugin/scripts/post-commit.mjs
index 640df172..ae7b07b9 100755
--- a/plugin/scripts/post-commit.mjs
+++ b/plugin/scripts/post-commit.mjs
@@ -7,7 +7,7 @@ import { promisify } from "node:util";
//#region src/secret-store.ts
const SECRET_KEY = "AGENTMEMORY_SECRET";
function agentmemoryHomeDir() {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
function secretFilePath() {
return join(agentmemoryHomeDir(), "secret");
@@ -31,7 +31,7 @@ function unquote(value) {
function readEnvFileSecret() {
let content;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -47,13 +47,29 @@ function readEnvFileSecret() {
}
return found;
}
-function readStoredSecret() {
+function readSecretFile(path) {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env = process.env) {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [
+ join(dataDir, "secret"),
+ join(dataDir, ".hmac"),
+ join(dataDir, "..", ".hmac")
+ ];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
function isLoopbackUrl(url) {
let hostname;
try {
@@ -69,7 +85,10 @@ function resolveClientSecret(baseUrl, env = process.env) {
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+ return join(homedir(), ".agentmemory", "secret");
}
//#endregion
//#region src/hooks/_project.ts
diff --git a/plugin/scripts/pre-compact.mjs b/plugin/scripts/pre-compact.mjs
index 6eada776..ff848c37 100755
--- a/plugin/scripts/pre-compact.mjs
+++ b/plugin/scripts/pre-compact.mjs
@@ -6,7 +6,7 @@ import { execSync } from "node:child_process";
//#region src/secret-store.ts
const SECRET_KEY = "AGENTMEMORY_SECRET";
function agentmemoryHomeDir() {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
function secretFilePath() {
return join(agentmemoryHomeDir(), "secret");
@@ -30,7 +30,7 @@ function unquote(value) {
function readEnvFileSecret() {
let content;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -46,13 +46,29 @@ function readEnvFileSecret() {
}
return found;
}
-function readStoredSecret() {
+function readSecretFile(path) {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env = process.env) {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [
+ join(dataDir, "secret"),
+ join(dataDir, ".hmac"),
+ join(dataDir, "..", ".hmac")
+ ];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
function isLoopbackUrl(url) {
let hostname;
try {
@@ -68,7 +84,10 @@ function resolveClientSecret(baseUrl, env = process.env) {
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+ return join(homedir(), ".agentmemory", "secret");
}
//#endregion
//#region src/hooks/_capture-filter.ts
diff --git a/plugin/scripts/pre-tool-use.mjs b/plugin/scripts/pre-tool-use.mjs
index 29df904a..2761d007 100755
--- a/plugin/scripts/pre-tool-use.mjs
+++ b/plugin/scripts/pre-tool-use.mjs
@@ -5,7 +5,7 @@ import { join } from "node:path";
//#region src/secret-store.ts
const SECRET_KEY = "AGENTMEMORY_SECRET";
function agentmemoryHomeDir() {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
function secretFilePath() {
return join(agentmemoryHomeDir(), "secret");
@@ -29,7 +29,7 @@ function unquote(value) {
function readEnvFileSecret() {
let content;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -45,13 +45,29 @@ function readEnvFileSecret() {
}
return found;
}
-function readStoredSecret() {
+function readSecretFile(path) {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env = process.env) {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [
+ join(dataDir, "secret"),
+ join(dataDir, ".hmac"),
+ join(dataDir, "..", ".hmac")
+ ];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
function isLoopbackUrl(url) {
let hostname;
try {
@@ -67,7 +83,10 @@ function resolveClientSecret(baseUrl, env = process.env) {
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+ return join(homedir(), ".agentmemory", "secret");
}
//#endregion
//#region src/hooks/pre-tool-use.ts
diff --git a/plugin/scripts/session-start.mjs b/plugin/scripts/session-start.mjs
index d01a5a6e..a93aea20 100755
--- a/plugin/scripts/session-start.mjs
+++ b/plugin/scripts/session-start.mjs
@@ -6,7 +6,7 @@ import { execSync } from "node:child_process";
//#region src/secret-store.ts
const SECRET_KEY = "AGENTMEMORY_SECRET";
function agentmemoryHomeDir() {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
function secretFilePath() {
return join(agentmemoryHomeDir(), "secret");
@@ -30,7 +30,7 @@ function unquote(value) {
function readEnvFileSecret() {
let content;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -46,13 +46,29 @@ function readEnvFileSecret() {
}
return found;
}
-function readStoredSecret() {
+function readSecretFile(path) {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env = process.env) {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [
+ join(dataDir, "secret"),
+ join(dataDir, ".hmac"),
+ join(dataDir, "..", ".hmac")
+ ];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+function readStoredSecret(env = process.env) {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) || (localPath === canonicalPath ? "" : readSecretFile(localPath)) || legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
function isLoopbackUrl(url) {
let hostname;
try {
@@ -68,7 +84,10 @@ function resolveClientSecret(baseUrl, env = process.env) {
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
+}
+function canonicalSecretPath() {
+ return join(homedir(), ".agentmemory", "secret");
}
//#endregion
//#region src/hooks/_project.ts
diff --git a/plugin/skills/agentmemory-architecture/SKILL.md b/plugin/skills/agentmemory-architecture/SKILL.md
index 3dd0c944..6c135a4e 100644
--- a/plugin/skills/agentmemory-architecture/SKILL.md
+++ b/plugin/skills/agentmemory-architecture/SKILL.md
@@ -4,7 +4,7 @@ description: How agentmemory is built, the iii engine primitives it runs on, its
user-invocable: false
---
-agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval, and serves them back over REST and MCP. It is built on the iii engine.
+agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval, and serves them back over REST and MCP. Worker Compose runs the pinned iii engine with AgentMemory and the registry `state` and `http` workers. The state worker uses a file-backed KV store by default, with Redis available by configuration; it is not SQLite.
## iii primitives
@@ -20,11 +20,11 @@ Memories carry content, concepts, files, importance, and timestamps, grouped int
## Ports
-REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). `--instance N` shifts the whole block by N*100.
+REST defaults to port `3111`, the viewer to `3113`, and the internal engine WebSocket to `49134`. Use `--port <N>` or `--instance <N>` to select another local runtime.
## Viewer
-A real-time web viewer at `http://localhost:3113` shows memory building as sessions run. Useful for demos and for confirming capture is working.
+A real-time web viewer at `http://localhost:3113` shows memory building as sessions run, with authenticated SSE updates over the REST port. Useful for demos and for confirming capture is working.
## See also
diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.md
index ea0728ca..281f7c87 100644
--- a/plugin/skills/agentmemory-config/REFERENCE.md
+++ b/plugin/skills/agentmemory-config/REFERENCE.md
@@ -3,7 +3,7 @@
Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.
<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->
-Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 77 recognized variables:
+Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 75 recognized variables:
- `AGENTMEMORY_AGENT_SCOPE`
- `AGENTMEMORY_ALLOW_AGENT_SDK`
@@ -32,19 +32,17 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_CWD`
- `AGENTMEMORY_DATA_DIR`
- `AGENTMEMORY_DEBUG`
-- `AGENTMEMORY_DOCKER_GID`
-- `AGENTMEMORY_DOCKER_SKIP_CHOWN`
-- `AGENTMEMORY_DOCKER_UID`
+- `AGENTMEMORY_DISABLE_COMPOSE_RESTART`
- `AGENTMEMORY_DROP_STALE_INDEX`
- `AGENTMEMORY_ENGINE_MANAGES_WORKER`
- `AGENTMEMORY_ENGINE_READY_TIMEOUT_MS`
+- `AGENTMEMORY_ENV_FILE`
- `AGENTMEMORY_EXPORT_ROOT`
- `AGENTMEMORY_FINALIZE_IDLE_MS`
- `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS`
- `AGENTMEMORY_FORCE_PROXY`
- `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT`
- `AGENTMEMORY_GRAPH_WEIGHT`
-- `AGENTMEMORY_III_CONFIG`
- `AGENTMEMORY_III_VERSION`
- `AGENTMEMORY_IMAGE_EMBEDDINGS`
- `AGENTMEMORY_IMAGE_STORE_MAX_BYTES`
@@ -74,25 +72,19 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_SUPPRESS_COST_WARNING`
- `AGENTMEMORY_TOOLS`
- `AGENTMEMORY_URL`
-- `AGENTMEMORY_USE_DOCKER`
- `AGENTMEMORY_VECTOR_BACKFILL`
- `AGENTMEMORY_VECTOR_BACKFILL_MAX`
- `AGENTMEMORY_VECTOR_BUCKET_SIZE`
- `AGENTMEMORY_VERBOSE`
- `AGENTMEMORY_VIEWER_HOST`
-- `AGENTMEMORY_VIEWER_STREAM_MAX`
- `AGENTMEMORY_VIEWER_URL`
+- `AGENTMEMORY_WORKER_BIN_DIR`
+- `AGENTMEMORY_WORKER_ENV_ALLOWLIST`
<!-- AUTOGEN:env END -->
-## Engine config
-
-- `AGENTMEMORY_III_CONFIG`: path to the engine config the CLI starts from. Lookup order: this variable, `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, the bundled `iii-config.yaml`. The chosen file is rendered into `~/.agentmemory/data/iii-config.runtime.yaml` on every start; its `host:` values are kept as written.
-
-The bundled config binds `127.0.0.1`, also inside a container. To reach a containerized CLI through published ports, point `AGENTMEMORY_III_CONFIG` at a config that binds `0.0.0.0` (the packaged `iii-config.docker.yaml` does, and stores state under `/data`) and keep `AGENTMEMORY_SECRET` set. The repo's `docker-compose.yml` mounts `iii-config.docker.yaml` straight into the engine container and does not use this lookup. See the README section "Engine config and bind address".
-
## State backend
- `AGENTMEMORY_STATE_BACKEND`: `file` (default) or `redis`. Anything else stops startup with an error.
-- `AGENTMEMORY_REDIS_URL`: required with `redis`, plain `redis://` only (the pinned engine has no TLS). The URL never appears in `/agentmemory/status` or the viewer.
+- `AGENTMEMORY_REDIS_URL`: required with `redis`, plain `redis://` only (the pinned state worker has no Redis TLS). The URL never appears in `/agentmemory/status` or the viewer.
-Switching backends starts from an empty store; move data with `/agentmemory/export` and `/agentmemory/import`. Run one Redis server per `--instance`: live viewer events travel over a Redis pub/sub channel that ignores the database index. After Redis restarts, restart agentmemory so live viewer updates resume; the Health page flags this. See the README section "Storage backend: file (default) vs redis".
+Switching backends starts from an empty store; move data with `/agentmemory/export` and `/agentmemory/import`. Give each concurrent instance its own Redis database or server so their state cannot mix. Viewer events are broadcast by the running agentmemory process; they do not rely on Redis pub/sub. See the README section "Storage backend: file (default) vs redis".
diff --git a/plugin/skills/agentmemory-config/SKILL.md b/plugin/skills/agentmemory-config/SKILL.md
index 7e582f9d..1784a3fb 100644
--- a/plugin/skills/agentmemory-config/SKILL.md
+++ b/plugin/skills/agentmemory-config/SKILL.md
@@ -62,12 +62,12 @@ AGENTMEMORY_INJECT_CONTEXT=true
## Ports
-REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). Relocate the whole block with `--port <N>` or `--instance <N>`.
+REST defaults to port `3111`, the viewer to `3113`, and the internal engine WebSocket to `49134`. Set `--port <N>` or `--instance <N>` to select another local runtime.
## See also
- agentmemory-rest-api for how the secret is used.
-- agentmemory-architecture for the port quartet rationale.
+- agentmemory-architecture for the runtime architecture.
## Reference
diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.md
index ce7f3b43..ec34d2c6 100644
--- a/plugin/skills/agentmemory-rest-api/REFERENCE.md
+++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md
@@ -5,7 +5,7 @@ Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run `
<!-- AUTOGEN:rest START - generated by scripts/skills/generate.ts, do not edit by hand -->
The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). Send `Authorization: Bearer <secret>`: the value of `AGENTMEMORY_SECRET`, or the one generated into `~/.agentmemory/secret` on first start when it is unset. Writes must use `Content-Type: application/json`.
-143 registered endpoints:
+146 registered endpoints:
| Method | Path |
| --- | --- |
@@ -37,6 +37,7 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
| POST | `/agentmemory/consolidate-pipeline` |
| GET | `/agentmemory/consolidation/status` |
| POST | `/agentmemory/context` |
+| GET | `/agentmemory/counts` |
| GET | `/agentmemory/crystals` |
| POST | `/agentmemory/crystals/auto` |
| POST | `/agentmemory/crystals/create` |
@@ -150,6 +151,8 @@ The REST API is the primary surface. All paths are under `http://localhost:3111`
| POST | `/agentmemory/timeline` |
| POST | `/agentmemory/verify` |
| GET | `/agentmemory/viewer` |
+| GET | `/agentmemory/viewer/events` |
+| GET | `/agentmemory/viewer/snapshot` |
| POST | `/agentmemory/vision-embed` |
| POST | `/agentmemory/vision-search` |
<!-- AUTOGEN:rest END -->
diff --git a/plugin/skills/agentmemory-rest-api/SKILL.md b/plugin/skills/agentmemory-rest-api/SKILL.md
index 93c74dae..c129b2ea 100644
--- a/plugin/skills/agentmemory-rest-api/SKILL.md
+++ b/plugin/skills/agentmemory-rest-api/SKILL.md
@@ -37,12 +37,12 @@ Protected endpoints require bearer authentication by default, including localhos
- Save returns `201`, reads return `200`, validation errors return `400`.
- Use documented fields only. A successful response does not prove an unsupported field was applied.
-- The port is configurable with `--port` or `--instance`; streams, viewer, and engine derive from it.
+- The REST port defaults to `3111` and is configurable with `--port` or `--instance`. The viewer defaults to `3113`; the internal engine WebSocket defaults to `49134`.
## See also
- agentmemory-mcp-tools for the MCP equivalents.
-- agentmemory-config for the port quartet and the secret.
+- agentmemory-config for local configuration and the secret.
## Reference
diff --git a/plugin/skills/remember/EXAMPLES.md b/plugin/skills/remember/EXAMPLES.md
index e220cb79..3c3a6369 100644
--- a/plugin/skills/remember/EXAMPLES.md
+++ b/plugin/skills/remember/EXAMPLES.md
@@ -9,7 +9,7 @@ Invocation:
```json
memory_save {
"content": "We decided to drop Redis and use the iii-engine state store for session caching to remove a moving part.",
- "concepts": "session-caching, iii-state-store, dropped-redis",
+ "concepts": "session-caching, state-worker-store, dropped-redis",
"files": ""
}
```
@@ -17,12 +17,12 @@ memory_save {
Response:
```json
-{ "id": "7f3a9c21", "concepts": ["session-caching", "iii-state-store", "dropped-redis"], "saved": true }
+{ "id": "7f3a9c21", "concepts": ["session-caching", "state-worker-store", "dropped-redis"], "saved": true }
```
Present:
-> Saved. Tagged it `session-caching`, `iii-state-store`, `dropped-redis`, so a
+> Saved. Tagged it `session-caching`, `state-worker-store`, `dropped-redis`, so a
> later recall on caching or Redis will surface this decision.
## 2. Saving a code-specific gotcha
diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json
index 1d459a31..95a2662a 100644
--- a/scripts/docs-sync.state.json
+++ b/scripts/docs-sync.state.json
@@ -11,7 +11,7 @@
"7"
],
"restEndpoints": [
- "143"
+ "146"
],
"skills": [
"17"
@@ -23,16 +23,17 @@
"4000+"
],
"functions": [
- "324"
+ "322"
],
"sourceFiles": [
- "250"
+ "253"
],
"loc": [
- "59000"
+ "58000"
],
"kvScopes": [
- "67"
+ "65"
]
- }
+ },
+ "engineVersion": "0.25.0"
}
diff --git a/scripts/docs-sync.ts b/scripts/docs-sync.ts
index b60b4ded..b5257b53 100644
--- a/scripts/docs-sync.ts
+++ b/scripts/docs-sync.ts
@@ -9,7 +9,7 @@ const STATE_PATH = "scripts/docs-sync.state.json";
const CHECK = process.argv.includes("--check");
const REPO_URL = "https://github.com/rohitg00/agentmemory";
-type State = { version: string; facts: Record<string, string[]> };
+type State = { version: string; engineVersion?: string; facts: Record<string, string[]> };
interface Fact {
key: string;
@@ -18,6 +18,7 @@ interface Fact {
nouns: string[];
before?: string;
badge?: string;
+ legacyValues?: string[];
}
function read(path: string): string {
@@ -103,7 +104,11 @@ const FACTS: Fact[] = [
{
key: "restEndpoints",
label: "REST endpoints",
- value: () => String(countMatches("src/triggers/api.ts", /api_path:\s*["`]/g)),
+ value: () => String(
+ countMatches("src/triggers/api.ts", /api_path:\s*["`]/g) +
+ countMatches("src/triggers/viewer-sse.ts", /api_path:\s*["`]/g) +
+ countMatches("src/triggers/viewer-streams.ts", /api_path:\s*["`]/g),
+ ),
nouns: [
"REST endpoints", "REST API endpoints", "endpoints", "endpoint", "Endpunkte", "эндпоинт", "个端点", "個端點", "개 엔드포인트", "개의 엔드포인트", "エンドポイント",
"uç nokta", "एंडपॉइंट", "endepunkt", "de endpoint", "ендпоінт", "na endpoint", "اینڈ پوائنٹ", "نقطة نهاية", "এন্ডপয়েন্ট", "개",
@@ -135,6 +140,7 @@ const FACTS: Fact[] = [
{
key: "tests",
label: "tests",
+ legacyValues: ["3000+", "3400+"],
value: () => {
const n = countTests();
return n === null ? null : `${floorTo(n, 100)}+`;
@@ -149,6 +155,7 @@ const FACTS: Fact[] = [
{
key: "functions",
label: "iii functions",
+ legacyValues: ["324"],
value: () => String(sourceFiles().reduce((n, f) => n + (read(f).match(/registerFunction\(/g)?.length ?? 0), 0)),
nouns: [
"iii functions", "functions", "funciones", "funções", "fonctions", "Funktionen", "функци", "個函式", "个函数", "개 함수", "개의 함수", "fonksiyon", "funkc",
@@ -159,12 +166,13 @@ const FACTS: Fact[] = [
{
key: "sourceFiles",
label: "source files",
+ legacyValues: ["242", "246"],
value: () => String(sourceFiles().length),
nouns: [
"source files", "fichiers sources", "ficheros de código", "arquivos de código", "archivos fuente", "arquivos-fonte", "arquivos fonte",
"fichiers source", "Quelldateien", "исходных файл", "個原始檔", "个源文件", "개 소스 파일", "개의 소스 파일", "ソースファイル", "kaynak dosya", "zdrojových soubor",
"kildefiler", "αρχεία πηγαίου", "lähdetiedosto", "forrásfájl", "file sorgente", "bronbestand", "plików źródłowych", "ficheiros de código",
- "fișiere sursă", "källkodsfiler", "source file", "na source file", "file source", "вихідних файл", "file sumber", "קבצי מקור", "ملف مصدري",
+ "fișiere sursă", "källkodsfiler", "source file", "na source file", "file source", "вихідних файл", "file sumber", "קבצי מקור", "קובצי מקור", "ملف مصدري",
"سورس فائل", "সোর্স ফাইল", "개", "pliki źródłowe", "de fișiere sursă",
],
},
@@ -178,6 +186,7 @@ const FACTS: Fact[] = [
{
key: "kvScopes",
label: "KV scopes",
+ legacyValues: ["67"],
value: () => String(countKvScopes()),
nouns: [
"KV scopes", "KV-Scopes", "KV scope", "KV-scope", "scopes KV", "scopes de KV", "escopos KV", "областей KV", "個 KV", "个 KV", "개 KV", "KV スコープ",
@@ -192,6 +201,7 @@ const EXCLUDED = [
/^test\//,
/^benchmark\//,
/^docs\/benchmarks\//,
+ /^docs\/upgrades\//,
/^eval\//,
/^website\/lib\/generated-meta\.json$/,
/(^|\/)package-lock\.json$/,
@@ -287,7 +297,26 @@ function main(): void {
const report: string[] = [];
const failed: string[] = [];
- const version = (JSON.parse(read("package.json")) as { version: string }).version;
+ const manifest = JSON.parse(read("package.json")) as { version: string; dependencies: Record<string, string> };
+ const version = manifest.version;
+ const engineVersion = manifest.dependencies["iii-sdk"];
+ if (!/^\d+\.\d+\.\d+$/.test(engineVersion) || manifest.dependencies["@iii-dev/helpers"] !== engineVersion) {
+ throw new Error("iii-sdk and @iii-dev/helpers must pin the same exact release.");
+ }
+ const previousEngineVersion = state.engineVersion ?? read("src/version.ts").match(/III_PINNED_VERSION = "([^"]+)"/)?.[1];
+ if (!previousEngineVersion) throw new Error("Could not read the previous engine pin.");
+ if (engineVersion !== previousEngineVersion) {
+ for (const extra of trackedFiles().filter((path) => path === ".env.example" || path === "eval/README.md" || /^examples\/python\/.*\.(py|md)$/.test(path) || path === "deploy/runtime/entrypoint.sh")) {
+ if (!files.has(extra)) files.set(extra, read(extra));
+ if (!original.has(extra)) original.set(extra, read(extra));
+ }
+ for (const [path, text] of files) {
+ if (path === "website/lib/generated-changelog.json") continue;
+ files.set(path, text.replaceAll(previousEngineVersion, engineVersion));
+ }
+ report.push(`engine: ${previousEngineVersion} -> ${engineVersion}`);
+ }
+ nextState.engineVersion = engineVersion;
const ompPath = "integrations/omp/package.json";
const ompManifest = files.get(ompPath);
if (ompManifest) {
@@ -310,7 +339,7 @@ function main(): void {
failed.push(fact.label);
continue;
}
- const olds = state.facts[fact.key] ?? [];
+ const olds = [...(state.facts[fact.key] ?? []), ...(fact.legacyValues ?? [])];
if (olds.length === 1 && olds[0] === next) continue;
for (const [path, text] of files) {
if (fact.badge && path.endsWith(".svg") && !path.endsWith(fact.badge)) continue;
diff --git a/scripts/plugins/package-codex.mjs b/scripts/plugins/package-codex.mjs
index 53ebbc61..dbe5257f 100644
--- a/scripts/plugins/package-codex.mjs
+++ b/scripts/plugins/package-codex.mjs
@@ -6,7 +6,8 @@ import { createHash } from "node:crypto";
const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
const plugin = join(root, "plugin");
-const output = join(root, "dist/plugins");
+// Tests package into a private directory so they never clobber dist/plugins mid-run.
+const output = process.env.AGENTMEMORY_PLUGIN_OUT_DIR ? resolve(process.env.AGENTMEMORY_PLUGIN_OUT_DIR) : join(root, "dist/plugins");
const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
const sourceManifest = JSON.parse(readFileSync(join(plugin, ".codex-plugin/plugin.json"), "utf8"));
if (sourceManifest.version !== pkg.version) throw new Error("Plugin and runtime versions must match before packaging.");
diff --git a/scripts/release-gate/graph-index.mjs b/scripts/release-gate/graph-index.mjs
index 55b4394e..33b579f4 100644
--- a/scripts/release-gate/graph-index.mjs
+++ b/scripts/release-gate/graph-index.mjs
@@ -105,10 +105,45 @@ async function profile(name, instance = 0, sharedHome) {
assert(port, "No free port block");
const p = { name, instance, dir, home, runtime, data, port, ports: [0, 1, 2, 3, 6353, 46023].map((n) => port + n), secret: "", trace: [], traceSummary: new Map(), phase: "startup", sockets: new Set(), holdManifestAt: 0, manifestReads: 0, held: false };
profiles.push(p);
- let config = readFileSync(join(pkg, "iii-config.yaml"), "utf8").split(" - name: iii-exec")[0];
- config = config.replaceAll("3111", String(port)).replaceAll("3112", String(port + 1)).replaceAll("3113", String(port + 2)).replaceAll("./data/", `${data}/`);
- config += ` - name: iii-worker-manager\n config:\n port: ${port + 46023}\n host: 127.0.0.1\n`;
- p.config = join(dir, "iii-config.yaml"); writeFileSync(p.config, config);
+ const workerCompose = join(dir, "worker-compose.yaml");
+ const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+ const namespace = `agentmemory-${port}`;
+ const composeText = [
+ `namespace: ${namespace}`,
+ "engine:",
+ ` url: ws://127.0.0.1:${port + 46023}`,
+ " workers:",
+ " configuration:",
+ " adapter:",
+ " name: fs",
+ " config:",
+ ` directory: ${quote(join(data, "compose-config"))}`,
+ " iii-worker-manager:",
+ " host: 127.0.0.1",
+ ` port: ${port + 46023}`,
+ "containers:",
+ " state:",
+ " worker: 'package://api.workers.iii.dev/state'",
+ " version: '0.22.20'",
+ " config_name: state",
+ " config_override:",
+ " adapter:",
+ " name: kv",
+ " config:",
+ ` file_path: ${quote(join(data, "state_store.db"))}`,
+ " store_method: file_based",
+ " save_interval_ms: 2000",
+ " http:",
+ " worker: 'package://api.workers.iii.dev/http'",
+ " version: '0.22.7'",
+ " config_name: http",
+ " config_override:",
+ " host: 127.0.0.1",
+ ` port: ${port}`,
+ " default_timeout: 180000",
+ "",
+ ].join("\n");
+ writeFileSync(workerCompose, composeText);
return p;
}
function environment(p) {
@@ -117,8 +152,8 @@ function environment(p) {
CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", OTEL_ENABLED: "false", III_TELEMETRY_ENABLED: "false",
AGENTMEMORY_DATA_DIR: p.data, AGENTMEMORY_RUNTIME_DIR: p.runtime,
...(p.explicitSecret ? { AGENTMEMORY_SECRET: p.explicitSecret } : {}),
- III_REST_PORT: String(p.port), III_STREAM_PORT: String(p.port + 1), III_VIEWER_PORT: String(p.port + 2),
- III_ENGINE_PORT: String(p.port + 3), III_ENGINE_URL: `ws://127.0.0.1:${p.port + 3}`, AGENTMEMORY_METRICS_PORT: String(p.port + 6353),
+ III_REST_PORT: String(p.port), III_VIEWER_PORT: String(p.port + 2),
+ III_ENGINE_PORT: String(p.port + 46023), III_ENGINE_URL: `ws://127.0.0.1:${p.port + 3}`, III_NAMESPACE: `agentmemory-${p.port}`, AGENTMEMORY_METRICS_PORT: String(p.port + 6353),
LLM_PROVIDER: "none", EMBEDDING_PROVIDER: "none", AGENTMEMORY_GRAPH_WEIGHT: "0.3",
AGENTMEMORY_GRAPH_COMPACT_ON_BOOT: "true", AGENTMEMORY_AUTO_COMPRESS: "false", AGENTMEMORY_SESSION_SWEEP_ENABLED: "false", AGENTMEMORY_FINALIZE_IDLE_MS: "0",
GRAPH_EXTRACTION_ENABLED: "false", CONSOLIDATION_ENABLED: "false", AGENTMEMORY_REFLECT: "false",
@@ -180,10 +215,14 @@ async function relay(p) {
});
}
async function startEngine(p, name) {
- p.engine = launch(p, engine, ["--config", p.config, "--no-update-check"], `${name}-engine`);
- await poll("native engine", async () => (await fetch(`http://127.0.0.1:${p.port}/`, { signal: AbortSignal.timeout(500) })).status > 0);
await relay(p);
- p.client = registerWorker(`ws://127.0.0.1:${p.port + 46023}`, { workerName: `graph-index-fixture-${p.name}`, invocationTimeoutMs: 30_000, enableMetricsReporting: false, otel: { enabled: false } });
+ p.engine = launch(p, engine, ["compose", "--namespace", `agentmemory-${p.port}`, "--up", "--file", join(p.dir, "worker-compose.yaml")], `${name}-compose`);
+ await poll("Compose engine", async () => (await fetch(`http://127.0.0.1:${p.port}/`, { signal: AbortSignal.timeout(500) })).status > 0);
+ p.client = registerWorker(`ws://127.0.0.1:${p.port + 46023}`, { workerName: `graph-index-fixture-${p.name}`, namespace: `agentmemory-${p.port}`, invocationTimeoutMs: 30_000, enableMetricsReporting: false, otel: { enabled: false } });
+ await poll("Compose state worker", async () => {
+ await p.client.trigger({ function_id: "state::get", payload: { scope: scopes.control, key: "current" } });
+ return true;
+ });
}
async function startWorker(p, name) {
p.worker = launch(p, process.execPath, [cli, "--no-engine", "--port", String(p.port), "--data-dir", p.data, ...(p.instance ? ["--instance", String(p.instance)] : [])], name);
@@ -192,7 +231,7 @@ async function startWorker(p, name) {
if (!p.worker.text.includes("REST API")) return false;
const value = await rest(p, "/livez"); return value.viewerPort || value.viewerSkipped;
});
- p.secret = p.explicitSecret ?? readFileSync(join(p.home, ".agentmemory", "secret"), "utf8").trim();
+ p.secret = p.explicitSecret ?? readFileSync(join(p.runtime, "secret"), "utf8").trim();
}
async function start(p, name) { await startEngine(p, name); await startWorker(p, name); }
async function stop(p, graceful = false) {
diff --git a/scripts/release-gate/reflection.mjs b/scripts/release-gate/reflection.mjs
index fe1cdd60..9826669e 100644
--- a/scripts/release-gate/reflection.mjs
+++ b/scripts/release-gate/reflection.mjs
@@ -70,7 +70,7 @@ function cleanEnv(targetHome = home) {
TMPDIR: tmpdir(), CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", III_TELEMETRY_ENABLED: "false",
EMBEDDING_PROVIDER: "none", AGENTMEMORY_AUTO_COMPRESS: "false", AGENTMEMORY_SESSION_SWEEP_ENABLED: "false",
AGENTMEMORY_DATA_DIR: dataDir, AGENTMEMORY_RUNTIME_DIR: runtime,
- III_REST_PORT: String(port), III_STREAM_PORT: String(port + 1), III_VIEWER_PORT: String(port + 2),
+ III_REST_PORT: String(port), III_VIEWER_PORT: String(port + 2),
III_ENGINE_PORT: String(port + 46023), AGENTMEMORY_METRICS_PORT: String(port + 6353),
AGENTMEMORY_URL: `http://127.0.0.1:${port}`,
OPENAI_API_KEY: "reflection-gate-synthetic-key", OPENAI_BASE_URL: `http://127.0.0.1:${modelPort}`,
diff --git a/scripts/release-gate/run.mjs b/scripts/release-gate/run.mjs
index b5b025b8..f95e1d5d 100644
--- a/scripts/release-gate/run.mjs
+++ b/scripts/release-gate/run.mjs
@@ -24,7 +24,7 @@ import { fileURLToPath } from "node:url";
import { assertRecoveredVectors, hasPersistedVectorFixture, isVectorLogAcknowledged, isVectorRecoverySettled } from "./recovery.mjs";
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-const FORBIDDEN_PORTS = new Set([3111, 3112, 3113, 4098, 4131, 4132, 4133, 49134]);
+const FORBIDDEN_PORTS = new Set([3111, 3113, 4098, 4131, 4132, 4133, 49134]);
const STATE_FLUSH_WAIT_MS = 5000;
const SCENARIOS = [
["install", "packed artifact installs and reports its identity"],
@@ -40,7 +40,7 @@ const SCENARIOS = [
];
function parseArgs(argv) {
- const opts = { out: null, keep: false, skipBuild: false, tarball: null, mcpTarball: null, only: null };
+ const opts = { out: null, keep: false, skipBuild: false, tarball: null, mcpTarball: null, only: null, workerBinDir: null };
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
const next = () => argv[++i];
@@ -50,9 +50,10 @@ function parseArgs(argv) {
else if (a === "--tarball") opts.tarball = resolve(next());
else if (a === "--mcp-tarball") opts.mcpTarball = resolve(next());
else if (a === "--only") opts.only = new Set(next().split(","));
+ else if (a === "--worker-bin-dir" || a === "--workers-dir") opts.workerBinDir = resolve(next());
else if (a === "--help" || a === "-h") {
console.log(
- "Usage: npm run release:gate -- [--tarball file.tgz] [--mcp-tarball file.tgz] [--skip-build] [--only a,b] [--out dir] [--keep]\n" +
+ "Usage: npm run release:gate -- [--tarball file.tgz] [--mcp-tarball file.tgz] [--skip-build] [--only a,b] [--out dir] [--keep] [--worker-bin-dir directory]\n" +
`Scenarios: ${SCENARIOS.map((s) => s[0]).join(", ")}`,
);
process.exit(0);
@@ -168,13 +169,14 @@ async function mustRun(label, cmd, args, options) {
const instanceHomes = new Map();
function secretFor(url) {
- for (const [base, home] of instanceHomes) {
+ for (const [base, location] of instanceHomes) {
if (!url.startsWith(base)) continue;
- try {
- return readFileSync(join(home, ".agentmemory", "secret"), "utf8").trim();
- } catch {
- return "";
+ for (const secretPath of [join(location.dataDir, "secret"), join(location.home, ".agentmemory", "secret")]) {
+ try {
+ return readFileSync(secretPath, "utf8").trim();
+ } catch {}
}
+ return "";
}
return "";
}
@@ -197,6 +199,14 @@ async function request(method, url, body, timeoutMs = 30_000) {
return { status: res.status, json, text };
}
+async function free(port) {
+ const server = net.createServer();
+ return await new Promise((resolve) => {
+ server.once("error", () => resolve(false));
+ server.listen(port, "127.0.0.1", () => server.close(() => resolve(true)));
+ });
+}
+
async function poll(label, fn, { timeoutMs = 30_000, intervalMs = 250 } = {}) {
const deadline = Date.now() + timeoutMs;
let last;
@@ -378,6 +388,9 @@ class Instance {
this.cli = null;
this.cliExit = null;
this.enginePid = null;
+ this.composePid = null;
+ this.childGroups = new Set();
+ this.rssSnapshotLast = null;
this.extraEnv = {};
}
@@ -390,10 +403,13 @@ class Instance {
...gate.baseEnv(this.home),
OPENAI_API_KEY: "release-gate-fake-key",
OPENAI_API_KEY_FOR_LLM: "false",
+ EMBEDDING_PROVIDER: "openai",
OPENAI_BASE_URL: `http://127.0.0.1:${gate.fake.port}`,
OPENAI_EMBEDDING_DIMENSIONS: String(gate.dims),
AGENTMEMORY_URL: `http://127.0.0.1:${this.port}`,
AGENTMEMORY_DATA_DIR: this.dataDir,
+ ...(this.extraEnv.AGENTMEMORY_DISABLE_COMPOSE_RESTART === "1" ? { AGENTMEMORY_DISABLE_COMPOSE_RESTART: "1" } : {}),
+ ...(this.localWorkerBinDir() ? { AGENTMEMORY_WORKER_BIN_DIR: this.localWorkerBinDir() } : {}),
...extra,
};
}
@@ -402,6 +418,39 @@ class Instance {
return join(this.home, ".agentmemory", "iii.pid");
}
+ composeStatePath() {
+ return join(this.home, ".agentmemory", "engine-state.json");
+ }
+
+ processGroups() {
+ let rows = [];
+ try {
+ rows = execFileSync("ps", ["-eo", "pid=,ppid=,pgid=,command="], { encoding: "utf8" })
+ .split(/\r?\n/).map((line) => {
+ const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+ return match ? { pid: Number(match[1]), ppid: Number(match[2]), pgid: Number(match[3]), args: match[4] } : null;
+ }).filter(Boolean);
+ } catch { return []; }
+ const state = (() => { try { return JSON.parse(readFileSync(this.composeStatePath(), "utf8")); } catch { return null; } })();
+ const owners = [state?.composePid, state?.enginePid, this.composePid, this.cli?.pid].filter((pid) => pid && alive(pid));
+ if (owners.length === 0) return [];
+ const descendants = new Set(owners);
+ let changed = true;
+ while (changed) {
+ changed = false;
+ for (const row of rows) {
+ if (!descendants.has(row.pid) && descendants.has(row.ppid)) { descendants.add(row.pid); changed = true; }
+ }
+ }
+ const ownGroup = Number(execFileSync("ps", ["-p", String(process.pid), "-o", "pgid="], { encoding: "utf8" }).trim());
+ const groups = [...new Set(rows.filter((row) => descendants.has(row.pid) && row.pgid !== ownGroup).map((row) => row.pgid))];
+ return groups;
+ }
+
+ localWorkerBinDir() {
+ return opts.workerBinDir || process.env.AGENTMEMORY_WORKER_BIN_DIR || null;
+ }
+
seedEngine() {
const version = gate.info.enginePin;
const cached = join(CACHE, `iii-${version}-${platform()}-${arch()}`);
@@ -428,8 +477,8 @@ class Instance {
async start(extraEnv = {}) {
if (!this.port) this.port = await pickBasePort();
- instanceHomes.set(`http://127.0.0.1:${this.port}/`, this.home);
- this.extraEnv = extraEnv;
+ instanceHomes.set(`http://127.0.0.1:${this.port}/`, { home: this.home, dataDir: this.dataDir });
+ this.extraEnv = { ...(this.localWorkerBinDir() ? { AGENTMEMORY_WORKER_BIN_DIR: this.localWorkerBinDir() } : {}), ...extraEnv };
this.seedEngine();
for (const p of instancePorts(this.port)) {
await poll(`port ${p} to be free`, async () => !(await portOpen(p)), { timeoutMs: 30_000 });
@@ -453,7 +502,7 @@ class Instance {
await poll(
`${this.name} to answer /livez`,
async () => {
- if (this.cliExit) {
+ if (this.cliExit && this.cliExit.code !== 0) {
const err = new Error(`agentmemory exited (${this.cliExit.code ?? this.cliExit.signal}) before it was ready; see ${this.logFile}`);
err.fatal = true;
throw err;
@@ -464,27 +513,251 @@ class Instance {
{ timeoutMs: 420_000, intervalMs: 300 },
);
await poll(`${this.name} health`, async () => (await request("GET", `${this.base}/health`, undefined, 5000)).status === 200, { timeoutMs: 60_000 });
- this.enginePid = parseInt(readFileSync(this.enginePidPath(), "utf-8").trim(), 10) || null;
+ try {
+ const state = JSON.parse(readFileSync(join(this.home, ".agentmemory", "engine-state.json"), "utf8"));
+ if (state.kind === "compose") {
+ this.composePid = state.composePid ?? null;
+ this.enginePid = state.enginePid ?? null;
+ } else {
+ this.enginePid = parseInt(readFileSync(this.enginePidPath(), "utf-8").trim(), 10) || null;
+ }
+ } catch {
+ try { this.enginePid = parseInt(readFileSync(this.enginePidPath(), "utf-8").trim(), 10) || null; } catch {}
+ }
+ if (this.enginePid) ownedGroups.add(this.enginePid);
+ if (this.composePid) ownedGroups.add(this.composePid);
if (this.enginePid) ownedGroups.add(this.enginePid);
this.cacheEngine();
const ms = Date.now() - t0;
+ this.rssSnapshotLast = this.rssSnapshot();
log(`${this.name}: up on :${this.port} in ${ms} ms (worker pid ${child.pid}, engine pid ${this.enginePid})`);
+ log(`${this.name} startup RSS: ${JSON.stringify(this.rssSnapshotLast)}`);
+ await this.refreshContainerRssSnapshot();
return ms;
}
async waitDown() {
- await poll(`${this.name} worker to exit`, async () => this.cliExit !== null || !alive(this.cli.pid), { timeoutMs: 30_000 });
+ try {
+ const state = JSON.parse(readFileSync(this.composeStatePath(), "utf8"));
+ this.composePid = state.kind === "compose" ? state.composePid ?? this.composePid : this.composePid;
+ this.enginePid = state.kind === "compose" ? state.enginePid ?? this.enginePid : this.enginePid;
+ } catch {}
+ await poll(`${this.name} worker CLI to exit`, async () => this.cliExit !== null || !alive(this.cli.pid), { timeoutMs: 30_000 });
+ if (this.composePid) await poll(`${this.name} Compose daemon to exit`, async () => !alive(this.composePid), { timeoutMs: 30_000 });
if (this.enginePid) await poll(`${this.name} engine to exit`, async () => !alive(this.enginePid), { timeoutMs: 30_000 });
- for (const p of [this.port, this.port + 46023]) {
- await poll(`port ${p} to close`, async () => !(await portOpen(p)), { timeoutMs: 30_000 });
+ for (const port of instancePorts(this.port)) {
+ const label = ["REST", "viewer", "WebSocket", "stream", "metrics", "derived"][instancePorts(this.port).indexOf(port)] ?? "listener";
+ await poll(`${this.name} ${label} port ${port} listener to close`, async () => free(port), { timeoutMs: 30_000 });
}
}
async forceKill() {
- killGroup(this.enginePid);
+ // Capture direct Compose child process groups before killing the daemon;
+ // after SIGKILL they are reparented and cannot be recovered from its tree.
+ for (const pgid of this.processGroups()) this.childGroups.add(pgid);
+ for (const pgid of this.childGroups) killGroup(pgid);
+ if (this.enginePid) killGroup(this.enginePid);
+ if (this.composePid) killGroup(this.composePid);
killGroup(this.cli?.pid);
+ // Reap stragglers only within process groups proven to have been spawned by
+ // this Compose daemon. No PID is selected by the shared port number.
+ for (const pgid of this.childGroups) {
+ for (let attempt = 0; attempt < 20; attempt++) {
+ let exists = false;
+ try { process.kill(-pgid, 0); exists = true; } catch {}
+ if (!exists) break;
+ await sleep(100);
+ }
+ try { process.kill(-pgid, "SIGKILL"); } catch {}
+ }
await this.waitDown();
- log(`${this.name}: force killed`);
+ log(`${this.name}: force killed Compose, engine, and workers`);
+ }
+
+ async crashWorker() {
+ const worker = this.pid("worker");
+ assert(worker, "could not resolve the Compose-owned agentmemory worker PID from its state.json record");
+ try { process.kill(worker, "SIGKILL"); } catch {}
+ await poll("Compose to record the agentmemory worker failure", async () => {
+ const statePath = join(this.dataDir, "compose-state", `agentmemory-${this.port}`, "state.json");
+ try {
+ const composeState = JSON.parse(readFileSync(statePath, "utf8"));
+ return composeState.containers?.agentmemory?.status === "failed";
+ } catch { return false; }
+ }, { timeoutMs: 5_000, intervalMs: 100 });
+ }
+
+ async crashCompose() {
+ await this.forceKill();
+ }
+
+ configurationInfo() {
+ try {
+ const composeFile = join(this.dataDir, "compose", "worker-compose.yaml");
+ const lockFile = join(this.dataDir, "compose", "worker-compose.lock");
+ const yaml = readFileSync(composeFile, "utf8");
+ const lock = readFileSync(lockFile, "utf8");
+ const engineState = JSON.parse(readFileSync(this.composeStatePath(), "utf8"));
+ const engineConfigFiles = [];
+ const lockFiles = [];
+ const walk = (dir) => { for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) walk(path);
+ else if (entry.name === "engine-config.yaml") engineConfigFiles.push(path);
+ else if (entry.name.endsWith(".yaml") && path.includes("/packages/")) lockFiles.push(path);
+ } };
+ walk(join(this.dataDir, "compose-state"));
+ const engineConfigText = engineConfigFiles.map((path) => readFileSync(path, "utf8")).join("\n");
+ const engineConfig = engineConfigText.match(/name: configuration[\s\S]*?directory: ([^\n]+)/)?.[1]?.trim() ?? null;
+ const packages = Object.fromEntries(
+ [...lock.matchAll(/^ ([A-Za-z0-9._-]+):\n worker: [^\n]+\n requested: ([^\n]+)\n resolved:\n name: [^\n]+\n version: ([^\n]+)/gm)]
+ .map((match) => [match[1], { requested: match[2], version: match[3] }]),
+ );
+ const configResolve = lockFiles.map((path) => {
+ const text = readFileSync(path, "utf8");
+ const packageName = basename(dirname(path));
+ return { packageName, path, matchesConfiguration: /configuration/.test(text) };
+ });
+ const metadata = {
+ packageManifests: { state: "configuration@latest", http: "configuration@latest" },
+ registryLatestMetadataVersion: "0.24.5",
+ explicitComposeDependencyContainers: [...yaml.matchAll(/^ dependencies:\s*\n configuration: ([^\n]+)/gm)].map((match) => match[1]),
+ resolvedPackages: packages,
+ packageManifestsWithConfigurationDependencies: Object.keys(packages).filter((name) => ["state", "http"].includes(name)),
+ engineWorkerConfiguration: engineConfig ? { adapter: "fs", configDirectory: engineConfig, configured: true } : { adapter: "fs", configDirectory: null, configured: engineState.kind === "compose" },
+ dependencyKind: "engine worker, not a process/container",
+ registryBinaryDownloaded: false,
+ childProcessStarted: false,
+ required: true,
+ configurationRss: "No separate PID/RSS exists; configuration is loaded in-process inside iii-engine. Its RSS is the iii-engine entry in startupRss.",
+ pinSupported: "No per-dependency exact version selector is supported for engine-kind graph nodes in this Compose runtime. The active implementation is the engine-bundled configuration worker in the pinned iii 0.25.0, not the independent configuration@latest registry binary.",
+ explanation: "The published state/http manifests declare configuration: latest. The registry resolver returns dependency graph nodes in the same response; iii-compose::expand_graph omits nodes with kind=engine because they are supplied by the engine. Their dependency is satisfied by engine.workers.configuration (fs adapter), which Compose includes in engine-config.yaml. It is required by workers that use typed configuration, but is not downloaded/started as a child by Compose. Public registry info for configuration@latest currently reports 0.24.5; that is separate from the built-in configuration implementation in iii 0.25.0. It has no separate child RSS. No exact per-package dependency pin is available in this runtime; changing the engine pin is the control over the bundled implementation.",
+ };
+ writeFileSync(join(OUT, `configuration-${this.name}.json`), JSON.stringify(metadata, null, 2) + "\n");
+ return metadata;
+ } catch (error) {
+ return { error: String(error) };
+ }
+ }
+
+ async refreshContainerRssSnapshot() {
+ try {
+ const statePath = this.stateStoreFile();
+ const composeState = JSON.parse(readFileSync(statePath, "utf8"));
+ const port = this.port;
+ const rows = execFileSync("ps", ["-A", "-o", "pid=,rss=,command="], { encoding: "utf8" }).split(/\r?\n/);
+ const components = {};
+ for (const [name, record] of Object.entries(composeState.containers ?? {})) {
+ const pid = record.pid;
+ if (!pid || !alive(pid)) continue;
+ let processPid = pid;
+ let processArgs = "";
+ if (name === "agentmemory") {
+ const children = execFileSync("ps", ["-A", "-o", "pid=,ppid=,rss=,command="], { encoding: "utf8" }).trim();
+ const child = children.split(/\r?\n/).map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/)).find((match) => match && Number(match[2]) === Number(pid) && /node.*dist\/index\.mjs/.test(match[4]));
+ if (child) {
+ processPid = Number(child[1]);
+ processArgs = child[4];
+ }
+ }
+ const row = rows.map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/)).find((match) => match && Number(match[1]) === Number(processPid));
+ if (!row) continue;
+ const rssKb = Number(row[2]);
+ components[name] = { pid: processPid, containerPid: pid, rssKb, rssMiB: Math.round(rssKb / 1024 * 10) / 10, args: processArgs || row[3] };
+ }
+ this.rssSnapshotLast = { ...this.rssSnapshotLast, ...components };
+ log(`${this.name} container RSS: ${JSON.stringify(components)} (project state ${statePath}; instance port ${port})`);
+ return this.rssSnapshotLast;
+ } catch (error) {
+ this.rssSnapshotLast = { ...this.rssSnapshotLast, error: String(error) };
+ return this.rssSnapshotLast;
+ }
+ }
+
+ stateStoreFile() {
+ const root = join(this.dataDir, "compose-state");
+ const files = [];
+ const walk = (dir) => {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) walk(path);
+ else if (entry.name === "state.json") files.push(path);
+ }
+ };
+ walk(root);
+ const instanceSuffix = join(`agentmemory-${this.port}`, "state.json");
+ const instanceState = files.find((file) => file.endsWith(instanceSuffix));
+ if (instanceState) return instanceState;
+ for (const file of files) {
+ const state = JSON.parse(readFileSync(file, "utf8"));
+ const composePath = state.compose_path ?? state.composePath ?? state.file;
+ if (composePath && resolve(composePath) === resolve(join(this.dataDir, "compose", "worker-compose.yaml"))) return file;
+ }
+ throw new Error(`Compose state.json for ${this.name} was not found under ${root}`);
+ }
+
+ rssSnapshot() {
+ try {
+ const composeState = JSON.parse(readFileSync(this.composeStatePath(), "utf8"));
+ const entries = readdirSync(join(this.dataDir, "compose-state"), { withFileTypes: true });
+ const statePath = entries.filter((entry) => entry.isDirectory()).map((entry) => join(this.dataDir, "compose-state", entry.name, `agentmemory-${this.port}`, "state.json")).find(existsSync);
+ const projectState = statePath ? JSON.parse(readFileSync(statePath, "utf8")) : null;
+ const components = {
+ "iii-compose": composeState.composePid,
+ "iii-engine": composeState.enginePid,
+ state: projectState?.containers?.state?.pid,
+ http: projectState?.containers?.http?.pid,
+ agentmemory: projectState?.containers?.agentmemory?.pid,
+ };
+ const result = {};
+ for (const [name, containerPid] of Object.entries(components)) {
+ if (!containerPid || !alive(containerPid)) continue;
+ let pid = containerPid;
+ let processArgs = "";
+ if (name === "agentmemory") {
+ const children = execFileSync("ps", ["-A", "-o", "pid=,ppid=,rss=,command="], { encoding: "utf8" }).trim();
+ const child = children.split(/\r?\n/).map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/)).find((match) => match && Number(match[2]) === Number(pid) && /node.*dist\/index\.mjs/.test(match[4]));
+ if (child) {
+ pid = Number(child[1]);
+ processArgs = child[4];
+ }
+ }
+ const fields = execFileSync("ps", ["-p", String(pid), "-o", "rss=,command="], { encoding: "utf8" }).trim().match(/^(\d+)\s+(.*)$/);
+ if (!fields) continue;
+ const rssKb = Number(fields[1]);
+ result[name] = { pid, containerPid, rssKb, rssMiB: Math.round(rssKb / 1024 * 10) / 10, args: processArgs || fields[2] || "" };
+ }
+ return result;
+ } catch (error) {
+ return { error: String(error) };
+ }
+ }
+
+ workerPid() {
+ try {
+ const files = [];
+ const stateRoot = join(this.dataDir, "compose-state");
+ const walk = (dir) => { for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) walk(path);
+ else if (entry.name === "state.json") files.push(path);
+ } };
+ walk(stateRoot);
+ const instanceState = files.map((path) => ({ path, state: JSON.parse(readFileSync(path, "utf8")) }))
+ .find(({ path }) => path.endsWith(join(`agentmemory-${this.port}`, "state.json")));
+ if (instanceState) return instanceState.state.containers?.agentmemory?.pid ?? null;
+ for (const path of files) {
+ const state = JSON.parse(readFileSync(path, "utf8"));
+ const composePath = state.compose_path ?? state.composePath ?? state.file;
+ if (composePath && resolve(composePath) === resolve(join(this.dataDir, "compose", "worker-compose.yaml"))) return state.containers?.agentmemory?.pid ?? null;
+ }
+ } catch {}
+ return null;
+ }
+
+ pid(name) {
+ if (name === "worker") return this.workerPid();
+ return null;
}
async stop() {
@@ -501,8 +774,12 @@ class Instance {
return Date.now() - t0;
}
+ composeActive() {
+ return [this.composePid, this.enginePid].some((pid) => pid && alive(pid));
+ }
async shutdown() {
- if (!this.cli || this.cliExit) return;
+ // The CLI can exit 0 while the detached Compose daemon keeps running.
+ if (!this.cli || (this.cliExit && !this.composeActive())) return;
try {
await this.stop();
} catch (err) {
@@ -670,8 +947,8 @@ async function scenario(name, fn) {
}
async function ensureUp(inst, extraEnv = {}) {
- if (inst.cli && !inst.cliExit && (await request("GET", `${inst.base}/livez`, undefined, 2000).then((r) => r.status === 200).catch(() => false))) return;
- if (inst.cli && !inst.cliExit) await inst.forceKill().catch(() => {});
+ if (inst.cli && (await request("GET", `${inst.base}/livez`, undefined, 2000).then((r) => r.status === 200).catch(() => false))) return;
+ if (inst.cli && (!inst.cliExit || inst.composeActive())) await inst.forceKill().catch(() => {});
await inst.start(extraEnv);
}
@@ -736,18 +1013,20 @@ async function install(details) {
assert(cliPath === gate.bin("agentmemory"), `agentmemory on PATH resolves to ${cliPath}, not the installed prefix`);
const v = await mustRun("agentmemory --version", gate.bin("agentmemory"), ["--version"], { env: gate.baseEnv(installHome), cwd: installHome });
assert(v.stdout.trim() === installed.version, `agentmemory --version printed ${v.stdout.trim()}, expected ${installed.version}`);
- for (const f of ["dist/cli.mjs", "dist/standalone.mjs", "dist/index.mjs", "dist/viewer/index.html", "plugin/hooks/hooks.json", "plugin/scripts/post-tool-use.mjs", "plugin/scripts/_capture.mjs", "iii-config.yaml"]) {
+ for (const f of ["dist/cli.mjs", "dist/standalone.mjs", "dist/index.mjs", "dist/viewer/index.html", "plugin/hooks/hooks.json", "plugin/scripts/post-tool-use.mjs", "plugin/scripts/_capture.mjs"]) {
assert(existsSync(join(gate.pkgDir, f)), `packed artifact is missing ${f}`);
}
assert(existsSync(gate.bin("agentmemory-mcp")), "agentmemory-mcp bin is missing from the MCP shim package");
const a = instA;
details.firstBootMs = await a.start();
+ details.startupRss = a.rssSnapshotLast;
+ details.configurationDependency = a.configurationInfo();
const st = await a.status();
details.reportedVersion = st.service?.version;
- details.reportedEngine = st.service?.engineVersion;
+ details.reportedEnginePinned = st.service?.enginePinnedVersion;
assert(st.service?.version === installed.version, `/status reports version ${st.service?.version}, expected ${installed.version}`);
- assert(String(st.service?.engineVersion ?? "").includes(gate.info.enginePin), `/status reports engine ${st.service?.engineVersion}, expected the pinned ${gate.info.enginePin}`);
+ assert(String(st.service?.enginePinnedVersion ?? "").includes(gate.info.enginePin), `/status reports pinned engine ${st.service?.enginePinnedVersion}, expected ${gate.info.enginePin}`);
assert(st.provider?.embeddings && st.provider.embeddings !== "none", `embedding provider is ${st.provider?.embeddings}`);
details.embeddings = st.provider?.embeddings;
}
@@ -761,6 +1040,10 @@ async function main() {
log(`release gate output: ${OUT}`);
log(`temp root: ${ROOT}`);
gate.fake = await startFakeEmbeddings(gate.dims);
+ if (opts.workerBinDir) {
+ assert(existsSync(resolve(opts.workerBinDir)), `--worker-bin-dir does not exist: ${opts.workerBinDir}`);
+ log(`local workers override: ${opts.workerBinDir}`);
+ }
log(`fake embedding provider on :${gate.fake.port}`);
await scenario("install", install);
@@ -794,7 +1077,12 @@ async function main() {
await scenario("mcp", async (d) => {
await ensureUp(instA);
- const env = { ...gate.baseEnv(instA.home), AGENTMEMORY_URL: `http://127.0.0.1:${instA.port}` };
+ const env = {
+ ...gate.baseEnv(instA.home),
+ AGENTMEMORY_URL: `http://127.0.0.1:${instA.port}`,
+ AGENTMEMORY_DATA_DIR: instA.dataDir,
+ AGENTMEMORY_SECRET: readFileSync(join(instA.dataDir, "secret"), "utf8").trim(),
+ };
const shim = await mcpSession(gate.bin("agentmemory-mcp"), [], env);
try {
const tools = await shim.rpc("tools/list", {});
@@ -810,8 +1098,11 @@ async function main() {
const r = await shim.call("memory_smart_search", { query: m, limit: 5 });
return !r.isError && r.text.includes(m);
}, { timeoutMs: 20_000, intervalMs: 500 });
- const mem = await request("GET", `${instA.base}/memories`);
- assert(mem.text.includes(m), "the memory saved over MCP is not on the server");
+ const search = await poll(`server smart-search route to find ${m}`, async () => {
+ const result = await request("POST", `${instA.base}/smart-search`, { query: m, limit: 5 });
+ return result.status === 200 && result.text.includes(m) ? result : null;
+ }, { timeoutMs: 20_000, intervalMs: 500 });
+ d.mcpSearchStatus = search.status;
} finally {
shim.close();
}
@@ -864,6 +1155,9 @@ async function main() {
await instA.hook("PostToolUse", event);
await poll(`first delivery of ${m}`, async () => (await instA.countMarker(sid, m)) === 1, { timeoutMs: 20_000 });
await sleep(STATE_FLUSH_WAIT_MS);
+ // This scenario proves cross-restart idempotency, so kill the whole
+ // Compose-owned process tree (app, Rust workers, and managed engine), then
+ // start the same persisted data on the same ports.
await instA.forceKill();
d.restartMs = await instA.start();
const before = (await instA.capture()).capture?.sinceStart?.duplicates ?? 0;
@@ -880,6 +1174,7 @@ async function main() {
});
await scenario("deadletter", async (d) => {
+ // Agentmemory capture inbox/dead-letter recovery is independent of queue workers.
await ensureUp(instA);
await instA.stop();
await instA.start({ MAX_OBS_PER_SESSION: "2" });
diff --git a/scripts/release-gate/startup.mjs b/scripts/release-gate/startup.mjs
index dffdeed4..317b1011 100644
--- a/scripts/release-gate/startup.mjs
+++ b/scripts/release-gate/startup.mjs
@@ -1,5 +1,6 @@
#!/usr/bin/env node
import assert from "node:assert/strict";
+import { parse as parseYaml } from "yaml";
import { spawn, execFileSync } from "node:child_process";
import { createHash } from "node:crypto";
import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
@@ -10,7 +11,7 @@ import { dirname, join, resolve, delimiter } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
-const options = { tarball: null, out: null, only: null, keep: false, delayMs: 48_000, skipBuild: false };
+const options = { tarball: null, out: null, only: null, keep: false, delayMs: 48_000, skipBuild: false, workerBinDir: process.env.AGENTMEMORY_WORKER_BIN_DIR ?? null };
for (let i = 2; i < process.argv.length; i++) {
const arg = process.argv[i];
if (arg === "--tarball") options.tarball = resolve(process.argv[++i]);
@@ -19,8 +20,10 @@ for (let i = 2; i < process.argv.length; i++) {
else if (arg === "--delay-ms") options.delayMs = Number(process.argv[++i]);
else if (arg === "--keep") options.keep = true;
else if (arg === "--skip-build") options.skipBuild = true;
+ else if (arg === "--worker-bin-dir") options.workerBinDir = resolve(process.argv[++i]);
+ else if (arg === "--worker-bin-dir") options.workerBinDir = resolve(process.argv[++i]);
else if (arg === "--help") {
- console.log("Usage: node scripts/release-gate/startup.mjs [--tarball file.tgz] [--out dir] [--only names] [--delay-ms 48000] [--skip-build] [--keep]");
+ console.log("Usage: node scripts/release-gate/startup.mjs [--tarball file.tgz] [--out dir] [--only names] [--delay-ms 48000] [--skip-build] [--worker-bin-dir directory] [--keep]");
process.exit(0);
} else throw new Error(`Unknown argument ${arg}`);
}
@@ -44,7 +47,7 @@ const log = (message) => {
};
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const sha = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
-function packageDigest() {
+function packageFiles() {
const files = [];
const walk = (dir, relative = "") => { for (const entry of readdirSync(dir, { withFileTypes: true })) {
const name = relative ? `${relative}/${entry.name}` : entry.name;
@@ -52,8 +55,9 @@ function packageDigest() {
else if (entry.isFile()) files.push([name, sha(join(dir, entry.name))]);
} };
walk(pkg); files.sort(([a], [b]) => a.localeCompare(b));
- return createHash("sha256").update(JSON.stringify(files)).digest("hex");
+ return files;
}
+function packageDigest() { return createHash("sha256").update(JSON.stringify(packageFiles())).digest("hex"); }
const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
function kill(pid, signal = "SIGKILL") {
if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) return;
@@ -108,7 +112,7 @@ async function free(port) {
async function portBlock() {
for (let i = 0; i < 200; i++) {
const port = 12000 + Math.floor(Math.random() * 7000);
- if ((await Promise.all([0, 1, 2, 3, 6353, 46023].map((d) => free(port + d)))).every(Boolean)) return port;
+ if ((await Promise.all([0, 1, 2, 3, 4, 6353, 46023].map((d) => free(port + d)))).every(Boolean)) return port;
}
throw new Error("No free port block");
}
@@ -117,9 +121,10 @@ let tarball;
let artifactSha;
let cliSha;
let pkgSha;
+let pkgFiles;
let engine;
function baseEnv(home) {
- return { HOME: home, PATH: [join(prefix, "node_modules/.bin"), nodeDir, "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(delimiter), TMPDIR: tmpdir(), CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", EMBEDDING_PROVIDER: "none", LLM_PROVIDER: "none", III_TELEMETRY_ENABLED: "false" };
+ return { HOME: home, PATH: [join(prefix, "node_modules/.bin"), nodeDir, "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(delimiter), TMPDIR: tmpdir(), CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", EMBEDDING_PROVIDER: "none", LLM_PROVIDER: "none", III_TELEMETRY_ENABLED: "false", OTEL_ENABLED: "false", RUST_LOG: "error" };
}
async function install() {
tarball = options.tarball;
@@ -141,15 +146,15 @@ async function install() {
assert(existsSync(engine), `Pinned engine missing: ${engine}. Run the standard release gate once, or set AGENTMEMORY_GATE_ENGINE.`);
const version = await command(engine, ["--version"]);
assert(version.includes(installed.dependencies["iii-sdk"]), `Engine version mismatch: ${version}`);
- cliSha = sha(cli); pkgSha = packageDigest();
+ cliSha = sha(cli); pkgFiles = packageFiles(); pkgSha = createHash("sha256").update(JSON.stringify(pkgFiles)).digest("hex");
const cliVersion = await command(process.execPath, [cli, "--version"], baseEnv(installHome));
assert.equal(cliVersion.trim(), installed.version);
}
class Instance {
constructor(name) {
- this.name = name; this.dir = join(root, name); this.home = join(this.dir, "home"); this.data = join(this.dir, "data"); this.runtime = join(this.home, ".agentmemory");
+ this.name = name; this.dir = join(root, name); this.home = join(this.dir, "home"); this.data = join(this.dir, "data"); this.runtime = join(this.home, ".agentmemory"); this.configPath = null; this.envPath = join(this.runtime, ".env");
for (const dir of [this.home, this.data, this.runtime]) mkdirSync(dir, { recursive: true });
- this.logFile = join(out, `${name}.log`); this.envExtra = {}; this.handles = []; this.ownedPids = new Set(); this.dockerProject = null;
+ this.logFile = join(out, `${name}.log`); this.envExtra = {}; this.handles = []; this.ownedPids = new Set();
instances.add(this);
}
async init() {
@@ -157,31 +162,118 @@ class Instance {
const binDir = join(this.runtime, "bin"); mkdirSync(binDir, { recursive: true }); copyFileSync(engine, join(binDir, "iii")); chmodSync(join(binDir, "iii"), 0o755);
return this;
}
- env(extra = {}) { return { ...baseEnv(this.home), AGENTMEMORY_DATA_DIR: this.data, AGENTMEMORY_RUNTIME_DIR: this.runtime, III_REST_PORT: String(this.port), III_STREAM_PORT: String(this.port + 1), III_VIEWER_PORT: String(this.port + 2), III_ENGINE_PORT: String(this.port + 46023), AGENTMEMORY_METRICS_PORT: String(this.port + 6353), ...this.envExtra, ...extra }; }
+ env(extra = {}) { return { ...baseEnv(this.home), AGENTMEMORY_DATA_DIR: this.data, AGENTMEMORY_RUNTIME_DIR: this.runtime, III_REST_PORT: String(this.port), III_VIEWER_PORT: String(this.port + 2), III_ENGINE_PORT: String(this.port + 46023), AGENTMEMORY_METRICS_PORT: String(this.port + 6353), ...(options.workerBinDir ? { AGENTMEMORY_WORKER_BIN_DIR: options.workerBinDir } : {}), ...this.envExtra, ...extra }; }
get url() { return `http://127.0.0.1:${this.port}`; }
pid(name) { try { return Number(readFileSync(join(this.runtime, `${name}.pid`), "utf8").trim()); } catch { return null; } }
- config({ delayMs = 0, earlyPid = false, worker = true, relative = false } = {}) {
- let raw = readFileSync(join(pkg, "iii-config.yaml"), "utf8").split(" - name: iii-exec")[0];
- raw = raw.replaceAll("3111", String(this.port)).replaceAll("3112", String(this.port + 1)).replaceAll("3113", String(this.port + 2)).replaceAll("./data/", `${this.data}/`);
- raw += ` - name: iii-worker-manager\n config:\n port: ${this.port + 46023}\n host: 127.0.0.1\n`;
+ config({ delayMs = 0, earlyPid = false, worker = true, workerDataDir = this.data, httpPort = this.port } = {}) {
+ const namespace = `agentmemory-${this.port}`;
+ const enginePort = this.port + 46023;
+ const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+ const localWorkers = options.workerBinDir;
+ const lines = [
+ `namespace: ${namespace}`,
+ "startup_timeout: 60s",
+ "stop_timeout: 20s",
+ "required_default: true",
+ "engine:",
+ ` url: ws://127.0.0.1:${enginePort}`,
+ " workers:",
+ " configuration:",
+ " adapter:",
+ " name: fs",
+ " config:",
+ ` directory: ${quote(join(this.data, "compose-config"))}`,
+ " iii-worker-manager:",
+ " host: 127.0.0.1",
+ ` port: ${enginePort}`,
+ "containers:",
+ " state:",
+ ` worker: ${quote(localWorkers ? `path://${join(this.data, "local-workers/state")}` : "package://api.workers.iii.dev/state")}`,
+ ...(!localWorkers ? [" version: '0.22.20'"] : []),
+ " config_name: state",
+ ...(localWorkers ? [" scripts:", ` run: ${quote(join(localWorkers, "state"))}`] : []),
+ " config_override:",
+ " adapter:",
+ " name: kv",
+ " config:",
+ " store_method: file_based",
+ " save_interval_ms: 2000",
+ ` file_path: ${quote(join(this.data, "state_store.db"))}`,
+ " http:",
+ ` worker: ${quote(localWorkers ? `path://${join(this.data, "local-workers/http")}` : "package://api.workers.iii.dev/http")}`,
+ ...(!localWorkers ? [" version: '0.22.7'"] : []),
+ " config_name: http",
+ ...(localWorkers ? [" scripts:", ` run: ${quote(join(localWorkers, "http"))}`] : []),
+ " config_override:",
+ " host: 127.0.0.1",
+ ` port: ${httpPort}`,
+ " default_timeout: 180000",
+ ];
+ if (localWorkers) {
+ for (const name of ["state", "http"]) {
+ const workerDir = join(this.data, "local-workers", name);
+ mkdirSync(workerDir, { recursive: true });
+ writeFileSync(join(workerDir, "iii.worker.yaml"), `iii: v1\nname: ${name}\nlanguage: rust\nscripts:\n start: ${quote(join(localWorkers, name))}\n`);
+ }
+ }
if (worker) {
- const wrapper = join(this.dir, relative ? "dist/index.mjs" : "delayed-worker.mjs");
- mkdirSync(dirname(wrapper), { recursive: true });
+ const wrapper = join(this.dir, "delayed-worker.mjs");
writeFileSync(wrapper, `import { appendFileSync, writeFileSync } from 'node:fs';\nappendFileSync(${JSON.stringify(join(this.dir, "worker-starts.jsonl"))}, JSON.stringify({pid:process.pid,at:Date.now()})+'\\n');\n${earlyPid ? `writeFileSync(${JSON.stringify(join(this.runtime, "worker.pid"))}, String(process.pid));` : ""}\nawait new Promise(r=>setTimeout(r,${delayMs}));\nawait import(${JSON.stringify(pathToFileURL(join(pkg, "dist/index.mjs")).href)});\n`);
- raw += ` - name: iii-exec\n config:\n exec:\n - ${relative ? "node dist/index.mjs" : `${process.execPath} ${wrapper}`}\n`;
+ lines.push(
+ " agentmemory:",
+ ` worker: ${quote(`path://${pkg}`)}`,
+ " start_after: [state, http]",
+ " startup_timeout: 300s",
+ " config_name: agentmemory",
+ " scripts:",
+ ` run: ${quote(`${process.execPath} ${wrapper}`)}`,
+ ` working_dir: ${quote(this.dir)}`,
+ " environment:",
+ ` HOME: ${quote(this.home)}`,
+ ` PATH: ${quote([dirname(process.execPath), "/usr/bin", "/bin"].join(delimiter))}`,
+ ` AGENTMEMORY_DATA_DIR: ${quote(workerDataDir)}`,
+ ` AGENTMEMORY_ENV_FILE: ${quote(this.envPath)}`,
+ ` AGENTMEMORY_RUNTIME_DIR: ${quote(this.runtime)}`,
+ ` III_REST_PORT: ${quote(String(this.port))}`,
+ ` III_VIEWER_PORT: ${quote(String(this.port + 2))}`,
+ ` III_ENGINE_PORT: ${quote(String(enginePort))}`,
+ " LLM_PROVIDER: 'none'",
+ " EMBEDDING_PROVIDER: 'none'",
+ " III_TELEMETRY_ENABLED: 'false'",
+ );
}
- const file = join(this.dir, "iii-config.yaml"); writeFileSync(file, raw); this.envExtra.AGENTMEMORY_III_CONFIG = file; if (worker && !relative) this.envExtra.AGENTMEMORY_ENGINE_MANAGES_WORKER = "true"; return file;
+ lines.push("");
+ const file = join(this.dir, "worker-compose.yaml");
+ writeFileSync(file, lines.join("\n"));
+ this.configPath = file;
+ return file;
}
- start(args = [], env = {}, cwd = this.dir) {
- this.cli = launch(process.execPath, [cli, ...args, "--port", String(this.port)], this.env(env), cwd, this.logFile);
+
+ start(args = [], env = {}) {
+ this.cli = launch(process.execPath, [cli, ...args, "--port", String(this.port)], this.env(env), this.dir, this.logFile);
this.ownedPids.add(this.cli.pid); return this.cli;
}
+ writeComposeState(file, composePid) {
+ this.composePid = composePid;
+ this.configPath = file;
+ const state = {
+ kind: "compose", restPort: this.port, viewerPort: this.port + 2, enginePort: this.port + 46023,
+ engineUrl: `ws://127.0.0.1:${this.port + 46023}`, namespace: `agentmemory-${this.port}`,
+ file, stateDir: join(this.data, "compose-state"), logFile: this.logFile,
+ binPath: join(this.runtime, "bin/iii"), composePid, workerVersions: { local: true },
+ };
+ writeFileSync(join(this.runtime, "engine-state.json"), JSON.stringify(state));
+ return state;
+ }
async startEngine(config) {
- this.engine = launch(engine, ["--config", config, "--no-update-check"], this.env(), this.dir, this.logFile);
+ const engineEnv = { III_COMPOSE_STATE_DIR: join(this.data, "compose-state"), ...(options.workerBinDir ? { III_BUNDLE_WORKERS_DISABLED: "1" } : {}) };
+ this.engine = launch(join(this.runtime, "bin/iii"), ["compose", "--namespace", `agentmemory-${this.port}`, "--up", "--file", config], this.env(engineEnv), this.dir, this.logFile);
this.ownedPids.add(this.engine.pid);
- await poll("external engine", async () => (await fetch(`${this.url}/`, { signal: AbortSignal.timeout(500) })).status > 0, 20_000);
- writeFileSync(join(this.runtime, "engine-state.json"), JSON.stringify({ kind: "native", configPath: config, binPath: engine, restPort: this.port, attached: true }));
- writeFileSync(join(this.runtime, "iii.pid"), String(this.engine.pid));
+ await poll("external Worker Compose engine", async () => {
+ if (this.engine.result && this.engine.result.code !== 0) throw Object.assign(new Error(`Compose exited ${this.engine.result.code}: ${this.engine.text.slice(-1200)}`), { fatal: true });
+ return (await fetch(`${this.url}/`, { signal: AbortSignal.timeout(500) })).status >= 200;
+ }, 180_000);
+ this.writeComposeState(config, this.engine.pid);
}
async ready(timeout = 90_000, requireHint = true, allowDoctorDiagnosticsFailure = false) {
await poll(this.name, async () => {
@@ -196,11 +288,21 @@ class Instance {
async close() {
if (this.closed) return; this.closed = true;
for (const handle of this.handles) { handle.closeAllConnections?.(); handle.close(); }
- if (this.dockerProject) await command(this.dockerBin, ["compose", "-p", this.dockerProject, "-f", join(pkg, "docker-compose.yml"), "down", "--volumes"], this.env(), this.dir, 30_000, this.logFile).catch((err) => log(`${this.name} Docker cleanup: ${err.message}`));
for (const name of ["worker", "iii"]) { const pid = this.pid(name); if (pid) this.ownedPids.add(pid); }
for (const row of this.wrapperStarts()) this.ownedPids.add(row.pid);
+ try { const state = JSON.parse(readFileSync(join(this.runtime, "engine-state.json"), "utf8")); for (const pid of [state.composePid, state.enginePid]) if (Number.isInteger(pid) && pid > 0) this.ownedPids.add(pid); } catch {}
+ for (const pid of [...this.ownedPids]) {
+ try {
+ const rows = execFileSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" }).split(/\r?\n/).map((row) => row.trim().split(/\s+/).map(Number)).filter((row) => row.length === 2 && row.every(Number.isFinite));
+ const descendants = new Set([pid]);
+ let changed = true;
+ while (changed) { changed = false; for (const [child, parent] of rows) if (descendants.has(parent) && !descendants.has(child)) { descendants.add(child); changed = true; } }
+ for (const child of descendants) this.ownedPids.add(child);
+ } catch {}
+ }
for (const pid of this.ownedPids) kill(pid);
- await sleep(100);
+ const deadline = Date.now() + 10_000;
+ while ([...this.ownedPids].some((pid) => alive(pid)) && Date.now() < deadline) await sleep(100);
}
}
async function scenario(name, fn) {
@@ -210,51 +312,26 @@ async function scenario(name, fn) {
catch (err) { results.push({ name, status: "fail", ms: Date.now() - at, error: err.stack, details }); log(`FAIL ${name}: ${err.message}`); }
finally { if (instance) await instance.close(); }
}
-async function delayedConfigured(instance, details, { delayMs, earlyPid = false, relative = false, adopt = false, args = [] } = {}) {
- const config = instance.config({ delayMs, earlyPid, relative });
- if (adopt) await instance.startEngine(config);
- const at = Date.now(); instance.start(args); await instance.ready(delayMs + 25_000);
- details.readyMs = Date.now() - at; details.delayMs = delayMs; details.transport = "real pinned native engine and installed worker via custom delayed-import config";
- assert(details.readyMs >= delayMs - 1000, `Ready before configured worker delay: ${details.readyMs}`);
- const starts = instance.wrapperStarts(); assert.equal(starts.length, 1, "Configured worker launched more than once");
- assert.equal(instance.pid("worker"), starts[0].pid, "CLI imported a second worker instead of waiting for the configured worker");
- details.workerPid = starts[0].pid; details.enginePid = instance.pid("iii");
-}
-async function delayedSocket(instance, backendPort, delayMs) {
- const connections = new Set();
- let accepted = 0;
- const server = net.createServer((socket) => {
- accepted++; connections.add(socket); socket.pause();
- const timer = setTimeout(() => {
- if (socket.destroyed) return;
- const upstream = net.connect(backendPort, "127.0.0.1"); connections.add(upstream);
- upstream.on("connect", () => { socket.pipe(upstream); upstream.pipe(socket); socket.resume(); });
- upstream.on("error", () => socket.destroy()); socket.on("error", () => upstream.destroy());
- socket.on("close", () => upstream.destroy()); upstream.on("close", () => connections.delete(upstream));
- }, delayMs);
- socket.on("close", () => { clearTimeout(timer); connections.delete(socket); });
- socket.on("error", () => {});
- });
- server.closeAllConnections = () => { for (const socket of connections) socket.destroy(); };
- await new Promise((r) => server.listen(0, "127.0.0.1", r)); instance.handles.push(server);
- return { port: server.address().port, accepted: () => accepted };
-}
async function fixtureServer(instance, livez) {
let probes = 0;
+ const upstreamPort = instance.port + 1;
const server = http.createServer((req, res) => {
if (req.url === "/agentmemory/livez") {
probes++;
if (probes === 1) { res.writeHead(404); res.end(); return; }
livez(req, res, probes - 1); return;
}
- res.writeHead(200, { "content-type": "application/json" }); res.end("{}");
+ const upstream = http.request({ hostname: "127.0.0.1", port: upstreamPort, method: req.method, path: req.url, headers: req.headers }, (response) => {
+ res.writeHead(response.statusCode ?? 502, response.headers);
+ response.pipe(res);
+ });
+ upstream.on("error", () => { if (!res.headersSent) res.writeHead(502); res.end(); });
+ req.pipe(upstream);
});
await new Promise((r) => server.listen(instance.port, "127.0.0.1", r)); instance.handles.push(server);
- const sleeper = launch(process.execPath, ["-e", "setInterval(()=>{},1000)"], instance.env(), instance.dir);
- instance.ownedPids.add(sleeper.pid); writeFileSync(join(instance.runtime, "worker.pid"), String(sleeper.pid));
- instance.config({ worker: false });
- writeFileSync(join(instance.runtime, "engine-state.json"), JSON.stringify({ kind: "native", configPath: instance.envExtra.AGENTMEMORY_III_CONFIG, binPath: engine, restPort: instance.port, attached: true }));
- return { worker: sleeper, probes: () => probes };
+ const config = instance.config({ worker: false, httpPort: upstreamPort });
+ await instance.startEngine(config);
+ return { worker: instance.engine, probes: () => probes, state: JSON.parse(readFileSync(join(instance.runtime, "engine-state.json"), "utf8")) };
}
async function expectFailure(instance, args, env, { budgetMs = 5000, message } = {}) {
const at = Date.now(); const child = instance.start(args, env); const result = await exited(child, budgetMs);
@@ -262,229 +339,193 @@ async function expectFailure(instance, args, env, { budgetMs = 5000, message } =
if (message) assert(child.text.includes(message), `Missing ${message}: ${child.text.slice(-1500)}`);
return { elapsedMs: Date.now() - at, exitCode: result.code };
}
-function dockerFixture(instance, mode) {
- const fixtureBin = join(instance.dir, "fixture-bin"); mkdirSync(fixtureBin);
- const project = `agentmemory-${instance.port}`; const containerId = "startup-fixture-owned-container";
- const record = { Id: containerId, State: { Running: false }, Config: { Image: `iiidev/iii:${installed.dependencies["iii-sdk"]}`, Labels: { "com.docker.compose.project": project, "com.docker.compose.service": "iii-engine" } }, HostConfig: { PortBindings: { [`${instance.port}/tcp`]: [{ HostPort: String(instance.port) }] } }, Mounts: [{ Type: "bind", Source: instance.data, Destination: "/data" }] };
- const pidFile = join(instance.dir, "docker-stub.pid");
- const file = join(fixtureBin, "docker");
- writeFileSync(file, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nconst args=process.argv.slice(2);\nif(args[0]===${JSON.stringify(mode)}) { writeFileSync(${JSON.stringify(pidFile)},String(process.pid)); process.on('SIGTERM',()=>{}); setInterval(()=>{},1000); }\nelse if(args[0]==='inspect') console.log(${JSON.stringify(JSON.stringify([record]))});\nelse if(args.includes('ps')) console.log(${JSON.stringify(containerId)});\n`); chmodSync(file, 0o755);
- instance.envExtra.PATH = [fixtureBin, instance.env().PATH].join(delimiter);
- writeFileSync(join(instance.runtime, "engine-state.json"), JSON.stringify({ kind: "docker", schemaVersion: 2, composeFile: join(pkg, "docker-compose.yml"), projectName: project, engineVersion: installed.dependencies["iii-sdk"], restPort: instance.port, dataDir: instance.data, containerId, dataMountType: "bind", dataMountSource: instance.data, preserveContainer: mode === "inspect" }));
- return pidFile;
-}
+
async function main() {
+ if (options.workerBinDir) {
+ assert(["state", "http"].every((name) => existsSync(join(options.workerBinDir, name))), `--worker-bin-dir must contain executable state and http binaries: ${options.workerBinDir}`);
+ log(`local Worker Compose fixtures: ${options.workerBinDir}`);
+ }
await install();
- await scenario("slow-native", (i, d) => delayedConfigured(i, d, { delayMs: options.delayMs, earlyPid: true }));
- await scenario("configured-adoption", (i, d) => delayedConfigured(i, d, { delayMs: 8_000, adopt: true }));
- await scenario("unrelated-exec", async (i, d) => {
- const config = i.config({ worker: false });
- const other = join(i.dir, "unrelated-worker.mjs"); writeFileSync(other, "setInterval(()=>{},1000);\n");
- appendFileSync(config, ` - name: iii-exec\n config:\n exec:\n - ${process.execPath} ${other}\n`);
- const at = Date.now(); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }); await i.ready(8_000);
- d.readyMs = Date.now() - at; assert.equal(i.pid("worker"), i.cli.pid, "Unrelated exec prevented the CLI-owned worker from starting");
- d.transport = "real engine with unrelated iii-exec command plus installed CLI-owned worker";
+ await scenario("slow-compose-worker", async (i, d) => {
+ const config = i.config({ delayMs: options.delayMs, earlyPid: true });
+ await i.startEngine(config);
+ const at = Date.now(); i.start(["--no-engine"]);
+ await i.ready(options.delayMs + 25_000);
+ d.readyMs = Date.now() - at; d.delayMs = options.delayMs; d.transport = "managed Compose project with delayed packaged worker; CLI joins it with --no-engine";
+ assert(d.readyMs >= options.delayMs - 1000, `Ready before configured Compose worker delay: ${d.readyMs}`);
+ const starts = i.wrapperStarts(); assert.equal(starts.length, 1, "Compose launched the delayed packaged worker more than once");
+ assert.equal(i.pid("worker"), starts[0].pid, "CLI imported a duplicate instead of waiting for the Compose worker");
+ assert(alive(i.composePid), "CLI --no-engine stopped the externally owned Compose project");
});
- await scenario("relative-exec", (i, d) => delayedConfigured(i, d, { delayMs: 8_000, relative: true }));
- await scenario("unresolved-relative-exec", async (i, d) => {
- const config = i.config({ worker: false });
- appendFileSync(config, " - name: iii-exec\n config:\n exec:\n - node dist/index.mjs\n");
- const cliCwd = join(i.dir, "cli-cwd"); mkdirSync(join(cliCwd, "dist"), { recursive: true }); writeFileSync(join(cliCwd, "dist/index.mjs"), "");
- const at = Date.now(); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "5000" }, cliCwd); await i.ready(10_000);
- d.readyMs = Date.now() - at; assert.equal(i.pid("worker"), i.cli.pid, "A relative exec entry missing from the engine working directory prevented the CLI-owned worker from starting");
- d.transport = "real engine with a relative iii-exec worker entry that does not exist in its working directory; installed CLI-owned worker";
+ await scenario("configured-compose-adoption", async (i, d) => {
+ const config = i.config({ delayMs: 0, earlyPid: true });
+ await i.startEngine(config); await poll("configured Compose worker ready", async () => (await fetch(`${i.url}/agentmemory/livez`)).ok, 30_000);
+ const startsBefore = i.wrapperStarts(); assert.equal(startsBefore.length, 1);
+ i.start(["--no-engine"]); await i.ready(10_000);
+ assert.equal(i.wrapperStarts().length, 1, "CLI started a duplicate instead of joining the already-ready Compose worker");
+ assert(alive(startsBefore[0].pid)); assert(alive(i.composePid));
+ d.workerPid = startsBefore[0].pid; d.composePid = i.composePid; d.transport = "already-ready external Worker Compose project";
});
- await scenario("native-engine-timeout", async (i, d) => {
+ await scenario("compose-engine-timeout", async (i, d) => {
i.config({ worker: false });
- const binary = join(i.runtime, "bin/iii"); const launchPid = join(i.dir, "launched-engine.pid");
+ const binary = join(i.runtime, "bin/iii"); const launchPid = join(i.dir, "launched-compose.pid");
writeFileSync(binary, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nif(process.argv.includes('--version')) { console.log('iii ${installed.dependencies["iii-sdk"]}'); process.exit(0); }\nwriteFileSync(${JSON.stringify(launchPid)},String(process.pid));\nsetInterval(()=>{},1000);\n`); chmodSync(binary, 0o755);
- Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
- const pid = Number(readFileSync(launchPid, "utf8")); i.ownedPids.add(pid); await poll("owned engine timeout cleanup", () => !alive(pid), 5_000);
- assert(!existsSync(join(i.runtime, "iii.pid"))); assert(!existsSync(join(i.runtime, "engine-state.json")));
- d.transport = "version-compatible engine executable fixture that stays alive without opening HTTP; actual installed CLI";
- });
- await scenario("untracked-native-adoption", async (i, d) => {
- const config = i.config({ worker: false }); const externalConfig = join(i.dir, "external-config.yaml");
- copyFileSync(config, externalConfig); rmSync(config); await i.startEngine(externalConfig);
- delete i.envExtra.AGENTMEMORY_III_CONFIG;
- rmSync(join(i.runtime, "engine-state.json")); rmSync(join(i.runtime, "iii.pid"));
- i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }); await i.ready(6_000);
- assert.equal(i.pid("worker"), i.cli.pid, "Untracked engine was assumed to own a configured worker");
- assert(alive(i.engine.pid)); d.transport = "real native engine without lifecycle metadata or AgentMemory exec config";
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { message: "The engine process started but the REST API never responded." }));
+ const pid = Number(readFileSync(launchPid, "utf8")); i.ownedPids.add(pid); await poll("owned Compose engine timeout cleanup", () => !alive(pid), 5_000);
+ assert(!existsSync(join(i.runtime, "engine-state.json")));
+ d.transport = "version-compatible iii fixture accepting compose but never opening the engine port; actual installed CLI";
});
await scenario("cancel-owned-startup", async (i, d) => {
- i.config({ delayMs: 10_000, earlyPid: true }); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
- await poll("owned engine ready before cancellation", async () => i.pid("worker") && (await fetch(i.url, { signal: AbortSignal.timeout(500) })).status > 0, 5_000);
- const enginePid = i.pid("iii"); const workerPid = i.pid("worker");
- i.cli.kill("SIGINT"); const result = await exited(i.cli, 6_000); assert.equal(result.code, 130, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);
- await poll("cancelled owned process cleanup", () => !alive(enginePid) && !alive(workerPid), 5_000);
- d.exitCode = result.code; d.ownedEngineStopped = true;
+ const launchPid = join(i.dir, "cancel-owned-compose.pid");
+ const binary = join(i.runtime, "bin/iii");
+ writeFileSync(binary, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nif(process.argv.includes('--version')) { console.log('iii ${installed.dependencies["iii-sdk"]}'); process.exit(0); }\nwriteFileSync(${JSON.stringify(launchPid)},String(process.pid));\nsetInterval(()=>{},1000);\n`); chmodSync(binary, 0o755);
+ i.start([], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300000" });
+ const composePid = await poll("CLI-owned Compose daemon", () => { try { return JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")).composePid; } catch { return null; } }, 5_000);
+ i.ownedPids.add(composePid);
+ const fakePid = await poll("non-serving owned engine process", () => { try { return Number(readFileSync(launchPid, "utf8")); } catch { return null; } }, 5_000); i.ownedPids.add(fakePid);
+ i.cli.kill("SIGINT"); const result = await exited(i.cli, 10_000); assert.equal(result.code, 130, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);
+ await poll("cancelled owned Compose cleanup", () => !alive(composePid) && !alive(fakePid), 5_000);
+ assert(!existsSync(join(i.runtime, "engine-state.json")));
+ d.exitCode = result.code; d.ownedComposeStopped = true;
});
await scenario("cancel-external-startup", async (i, d) => {
- await i.startEngine(i.config({ worker: false })); const proxy = await delayedSocket(i, i.port + 46023, 10_000);
- i.start(["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${proxy.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
- await poll("worker connecting before cancellation", () => proxy.accepted() > 0, 5_000);
+ await i.startEngine(i.config({ delayMs: 10_000, earlyPid: true }));
+ await poll("delayed Compose worker process", () => i.wrapperStarts()[0]?.pid, 10_000);
+ i.start(["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "300000" });
+ await sleep(1000);
i.cli.kill("SIGTERM"); const result = await exited(i.cli, 6_000); assert.equal(result.code, 143, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);
- assert(alive(i.engine.pid), "Cancellation stopped an external engine"); d.exitCode = result.code; d.externalEnginePreserved = true;
+ assert(alive(i.composePid), "Cancellation stopped an external Compose project");
+ assert(alive(i.wrapperStarts()[0].pid), "Cancellation killed the Compose-owned delayed worker");
+ d.exitCode = result.code; d.externalComposePreserved = true;
});
await scenario("no-engine", async (i, d) => {
- await i.startEngine(i.config({ worker: false }));
- const socket = await delayedSocket(i, i.port + 46023, 3_000);
- const at = Date.now(); i.start(["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${socket.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "10000" });
- await i.ready(15_000); d.readyMs = Date.now() - at; d.delayedConnections = socket.accepted();
- assert(d.readyMs >= 3000); assert(d.delayedConnections > 0); assert(alive(i.engine.pid), "External engine stopped during no-engine startup");
- const worker = i.pid("worker");
+ await i.startEngine(i.config({ delayMs: 3_000, earlyPid: true }));
+ const at = Date.now(); i.start(["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
+ await i.ready(20_000); d.readyMs = Date.now() - at;
+ assert(d.readyMs >= 3_000); assert(alive(i.composePid), "External Compose project stopped during no-engine startup");
+ const worker = i.wrapperStarts()[0].pid; assert(alive(worker));
const duplicate = launch(process.execPath, [cli, "--no-engine", "--port", String(i.port)], i.env(), i.dir, i.logFile);
- const result = await exited(duplicate, 5_000); assert.notEqual(result.code, 0); assert(duplicate.text.includes("already running"));
- assert.equal(i.pid("worker"), worker); assert(alive(worker)); assert(alive(i.engine.pid));
- d.duplicateExitCode = result.code; d.transport = "real native engine and installed worker over delayed TCP proxy";
+ const result = await exited(duplicate, 10_000); assert.equal(result.code, 0, duplicate.text.slice(-1200));
+ assert.equal(i.wrapperStarts().length, 1, "A second --no-engine invocation duplicated the Compose worker");
+ assert.equal(i.pid("worker"), worker); assert(alive(worker)); assert(alive(i.composePid));
+ d.duplicateExitCode = result.code; d.transport = "real external Worker Compose project with delayed packaged worker";
});
await scenario("no-engine-timeout", async (i, d) => {
- await i.startEngine(i.config({ worker: false }));
- const socket = await delayedSocket(i, i.port + 46023, 5_000);
- Object.assign(d, await expectFailure(i, ["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${socket.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
- assert(alive(i.engine.pid), "Timeout stopped an externally owned engine");
- assert(!i.pid("worker") || !alive(i.pid("worker")), "Failed in-process worker left a live stale PID");
- d.externalEnginePreserved = true;
+ await i.startEngine(i.config({ delayMs: 5_000, earlyPid: true }));
+ const workerPid = await poll("delayed Compose worker process", () => i.wrapperStarts()[0]?.pid, 10_000);
+ Object.assign(d, await expectFailure(i, ["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
+ assert(alive(i.composePid), "Worker readiness timeout stopped an externally owned Compose project");
+ assert(alive(workerPid), "Compose supervisor's delayed worker was incorrectly killed by the joining CLI");
+ d.externalComposePreserved = true;
});
await scenario("inline-worker-fatal", async (i, d) => {
- i.config({ worker: false }); mkdirSync(join(i.runtime, "secret"));
- const child = i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "10000" });
- const enginePid = await poll("owned engine PID before worker initialization", () => i.pid("iii"), 3_000); i.ownedPids.add(enginePid);
- const result = await exited(child, 6_000); assert.equal(result.code, 1); assert(child.text.includes("[agentmemory] Fatal:"), "Fixture did not exercise the worker's fatal initialization path");
- await poll("fatal initialization engine cleanup", () => !alive(enginePid), 4_000);
- assert(!i.pid("iii")); assert(!i.pid("worker") || !alive(i.pid("worker")));
- d.exitCode = result.code; d.ownedEngineStopped = true; d.transport = "real engine and inline installed worker; secret path occupied by a directory causes initialization failure";
+ const workerData = join(i.data, "fatal-worker-data"); mkdirSync(join(workerData, "secret"), { recursive: true });
+ const config = i.config({ workerDataDir: workerData }); await i.startEngine(config);
+ Object.assign(d, await expectFailure(i, ["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }, { budgetMs: 10_000, message: "3s" }));
+ const workerLogs = readdirSync(join(i.data, "compose-state"), { withFileTypes: true })
+ .filter((entry) => entry.isDirectory())
+ .flatMap((entry) => { const stateRoot = join(i.data, "compose-state", entry.name); return readdirSync(stateRoot, { withFileTypes: true }).filter((project) => project.isDirectory()).map((project) => join(stateRoot, project.name, "logs", "agentmemory.log")); })
+ .filter(existsSync)
+ .map((file) => readFileSync(file, "utf8"))
+ .join("\n");
+ assert.match(workerLogs, /agentmemory could not create its API secret/i, "Compose did not report the packaged worker's fatal initialization failure");
+ d.workerExitCode = 1; d.transport = "real Worker Compose supervision with packaged worker secret-path initialization failure";
});
- await scenario("native-worker-timeout", async (i, d) => {
- i.config({ delayMs: 5_000, earlyPid: true });
- Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));
- await poll("owned engine cleanup", () => (!i.pid("iii") || !alive(i.pid("iii"))) && (!i.pid("worker") || !alive(i.pid("worker"))), 5_000);
- assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Failed owned engine still serves REST");
- d.ownedEngineStopped = true;
+ await scenario("compose-worker-timeout", async (i, d) => {
+ mkdirSync(join(i.data, "secret"), { recursive: true });
+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 30_000, message: "0.3s" }));
+ await poll("CLI-owned Compose timeout cleanup", () => { try { const state = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); return !alive(state.composePid) && !alive(state.enginePid); } catch { return true; } }, 10_000);
+ assert(!existsSync(join(i.runtime, "engine-state.json")), "Timed-out owned Compose startup retained lifecycle metadata");
+ assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Timed-out owned Compose project still serves REST");
+ d.ownedComposeStopped = true;
});
await scenario("hung-livez-body", async (i, d) => {
const f = await fixtureServer(i, (_req, res) => { res.writeHead(200, { "content-type": "application/json" }); res.write('{"viewerPort":'); });
- Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 2_000, message: "0.3s" }));
- assert(alive(f.worker.pid)); d.externalWorkerPreserved = true; d.probes = f.probes(); d.transport = "controlled HTTP headers with a stalled response body; external worker PID fixture";
+ const child = i.start(["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "300" });
+ await poll("CLI readiness failure", () => child.result, 5_000);
+ assert.notEqual(child.result.code, 0); assert(child.text.includes("0.3s"), `Missing configured livez timeout: ${child.text.slice(-1000)}`);
+ assert(alive(f.worker.pid)); d.externalWorkerPreserved = true; d.probes = f.probes(); d.transport = "controlled HTTP headers with a stalled response body, CLI-owned engine, and external Compose lifecycle metadata";
});
await scenario("malformed-livez", async (i, d) => {
const invalid = ["not json", JSON.stringify({ viewerPort: -1 }), JSON.stringify({ viewerPort: 0 }), JSON.stringify({ viewerPort: 65536 }), JSON.stringify({ viewerPort: 3000.5 }), JSON.stringify({ viewerSkipped: "true" }), JSON.stringify({ viewerPort: null, viewerSkipped: false })];
const f = await fixtureServer(i, (_req, res, n) => { res.writeHead(200, { "content-type": "application/json" }); res.end(invalid[n - 1] ?? JSON.stringify({ viewerSkipped: true })); });
- i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "6000" });
+ i.start(["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "6000" });
await poll("CLI readiness hint", () => i.cli.text.includes("REST API"), 7_000);
- assert(f.probes() >= invalid.length + 2, `Malformed readiness accepted after ${f.probes()} probes`); await i.ready(1_000); d.probes = f.probes(); d.invalidResponses = invalid.length; d.transport = "controlled readiness response fixture";
+ assert(f.probes() >= invalid.length + 2, `Malformed readiness accepted after ${f.probes()} probes`); await i.ready(1_000); d.probes = f.probes(); d.invalidResponses = invalid.length; d.transport = "controlled malformed readiness responses with Compose lifecycle metadata";
});
await scenario("env-file-and-precedence", async (i, d) => {
const f = await fixtureServer(i, (_req, res) => { res.writeHead(503); res.end(); });
- writeFileSync(join(i.runtime, ".env"), "AGENTMEMORY_READY_TIMEOUT_MS=350\nAGENTMEMORY_ENGINE_READY_TIMEOUT_MS=1000\n");
- d.fromFile = await expectFailure(i, [], {}, { budgetMs: 2500, message: "0.35s" });
- d.shellOverride = await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "150" }, { budgetMs: 2000, message: "0.15s" });
- assert(alive(f.worker.pid)); d.transport = "controlled unready external worker fixture";
+ writeFileSync(i.envPath, "AGENTMEMORY_READY_TIMEOUT_MS=350\nAGENTMEMORY_ENGINE_READY_TIMEOUT_MS=1000\n");
+ const fromFile = i.start(["--no-engine"], {}); const fileResult = await exited(fromFile, 10_000);
+ assert.notEqual(fileResult.code, 0); assert(fromFile.text.includes("0.35s"), `Fixture .env timeout not applied: ${fromFile.text.slice(-1000)}`);
+ d.fromFile = { exitCode: fileResult.code };
+ const shellOverride = i.start(["--no-engine"], { AGENTMEMORY_READY_TIMEOUT_MS: "150" }); const shellResult = await exited(shellOverride, 10_000);
+ assert.notEqual(shellResult.code, 0); assert(shellOverride.text.includes("0.15s"), `Environment override did not win: ${shellOverride.text.slice(-1000)}`);
+ d.shellOverride = { exitCode: shellResult.code };
+ assert(alive(f.worker.pid)); d.transport = "real external Worker Compose engine behind a controlled unready HTTP proxy";
});
await scenario("invalid-timeouts", async (i, d) => {
d.rejected = [];
for (const key of ["AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", "AGENTMEMORY_READY_TIMEOUT_MS"]) {
for (const value of ["", "0", "-1", "1.5", "NaN", "Infinity", "500ms", "3600001"]) {
- const result = await expectFailure(i, ["--no-engine"], { [key]: value }, { budgetMs: 2500, message: key });
+ const result = await expectFailure(i, ["--no-engine"], { [key]: value }, { budgetMs: 10_000, message: key });
d.rejected.push({ key, value, ...result });
assert(!existsSync(join(i.runtime, "worker.pid")), "Invalid timeout imported the worker");
}
}
- const ownership = await expectFailure(i, ["--no-engine"], { AGENTMEMORY_ENGINE_MANAGES_WORKER: "yes" }, { budgetMs: 2500, message: "AGENTMEMORY_ENGINE_MANAGES_WORKER" });
+ const ownership = await expectFailure(i, ["--no-engine"], { AGENTMEMORY_ENGINE_MANAGES_WORKER: "yes" }, { budgetMs: 10_000, message: "AGENTMEMORY_ENGINE_MANAGES_WORKER" });
d.invalidOwnership = ownership;
const help = await command(process.execPath, [cli, "--help"], i.env({ AGENTMEMORY_READY_TIMEOUT_MS: "invalid" }), i.dir);
assert(help.includes("Usage:"));
});
await scenario("doctor", async (i, d) => {
- i.config({ delayMs: 2_000, earlyPid: true });
- writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=15000\n");
- const at = Date.now();
- const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) });
- await poll("doctor worker ready", () => child.text.includes("Engine and agentmemory worker ready"), 30_000);
- const result = await exited(child, 10_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`); d.doctorExitCode = result.code;
- await i.ready(10_000, false, true); assert(alive(i.pid("worker")), "Doctor-owned worker stopped when doctor exited"); d.readyMs = Date.now() - at; d.transport = "real native engine, configured delayed worker, installed doctor --all";
- assert(d.readyMs >= 2000); assert.equal(i.wrapperStarts().length, 1);
- });
- await scenario("doctor-invalid-timeout", async (i, d) => {
- await i.startEngine(i.config({ worker: false }));
- writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=invalid\n");
- Object.assign(d, await expectFailure(i, ["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) }, { budgetMs: 10_000, message: "AGENTMEMORY_READY_TIMEOUT_MS" }));
- assert(alive(i.engine.pid), "Invalid doctor startup configuration stopped an existing engine");
- assert.equal(i.pid("iii"), i.engine.pid, "Invalid doctor configuration changed the external engine PID"); d.externalEnginePreserved = true;
- });
- await scenario("doctor-cli-worker", async (i, d) => {
- i.config({ worker: false });
- writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=15000\n");
- const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) });
- await poll("doctor detached worker ready", () => child.text.includes("Engine and agentmemory worker ready"), 30_000);
- const result = await exited(child, 10_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`);
- await i.ready(10_000, false, true); assert(alive(i.pid("worker")), "Doctor-owned worker stopped when doctor exited");
- assert.notEqual(i.pid("worker"), child.pid, "Doctor did not detach the CLI-owned worker");
- d.doctorExitCode = result.code; d.workerPid = i.pid("worker"); d.transport = "real native engine and installed detached worker created by doctor --all";
+ i.start(); await i.ready(120_000);
+ const composeState = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8"));
+ const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", AGENTMEMORY_ENV_FILE: i.envPath });
+ const result = await exited(child, 30_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`);
+ assert(child.text.includes("Server reachable"), "Doctor did not diagnose the Compose-managed REST service");
+ assert(alive(composeState.composePid), "Doctor stopped a healthy externally running Compose project");
+ await i.ready(5_000, false, true); d.doctorExitCode = result.code; d.composePid = composeState.composePid; d.transport = "real CLI-managed Worker Compose project inspected by doctor --all";
});
- await scenario("hung-docker-start", async (i, d) => {
- const pidFile = dockerFixture(i, "start");
- Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { budgetMs: 3000 }));
- const pid = Number(readFileSync(pidFile, "utf8")); i.ownedPids.add(pid); assert(!alive(pid), "Timed-out Docker start subprocess survived");
- assert(existsSync(join(i.runtime, "engine-state.json")), "Docker command timeout discarded owned lifecycle metadata");
- d.transport = "Docker command fixture whose start subprocess ignores SIGTERM; actual installed CLI";
+ await scenario("doctor-compose-recovery", async (i, d) => {
+ const oldState = i.writeComposeState(i.config({ worker: false }), 2_000_000_000);
+ writeFileSync(i.envPath, "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=30000\n");
+ const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", AGENTMEMORY_ENV_FILE: i.envPath });
+ await poll("doctor Compose recovery ready", () => child.text.includes("Engine and agentmemory worker ready"), 120_000);
+ const result = await exited(child, 30_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`);
+ const state = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8"));
+ assert.equal(state.kind, "compose"); assert(alive(state.composePid), "Doctor failed to leave the recovered Compose project running");
+ assert.equal(i.wrapperStarts().length, 0, "Stale metadata repair unexpectedly used a test wrapper instead of the packaged worker");
+ await i.ready(10_000, false, true); assert.notEqual(state.composePid, child.pid, "Doctor did not detach the Compose runtime");
+ d.doctorExitCode = result.code; d.composePid = state.composePid; d.transport = "doctor stale-lifecycle repair starts the standard managed Compose project";
});
- await scenario("hung-docker-inspect", async (i, d) => {
- const pidFile = dockerFixture(i, "inspect");
- Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { budgetMs: 8_000, message: "cannot be verified" }));
- const pid = Number(readFileSync(pidFile, "utf8")); i.ownedPids.add(pid); assert(!alive(pid), "Timed-out Docker inspect subprocess survived");
- assert(existsSync(join(i.runtime, "engine-state.json"))); d.transport = "Docker inspect subprocess fixture ignoring SIGTERM; actual installed CLI";
- });
- await scenario("docker", async (i, d) => {
- let dockerBin;
- try { dockerBin = execFileSync("which", ["docker"], { encoding: "utf8" }).trim(); } catch { d.skipped = "Docker executable unavailable"; return; }
- let host;
- try { host = process.env.DOCKER_HOST ?? execFileSync(dockerBin, ["context", "inspect", "--format", '{{(index .Endpoints "docker").Host}}'], { encoding: "utf8" }).trim(); } catch { d.skipped = "Docker context unavailable"; return; }
- i.dockerBin = dockerBin;
- i.envExtra = { AGENTMEMORY_USE_DOCKER: "1", DOCKER_HOST: host, DOCKER_CONFIG: process.env.DOCKER_CONFIG ?? join(homedir(), ".docker"), PATH: [dirname(dockerBin), i.env().PATH].join(delimiter) };
- try { d.serverVersion = (await command(dockerBin, ["info", "--format", "{{.ServerVersion}}"], i.env(), i.dir, 10_000)).trim(); } catch { d.skipped = "Docker daemon unavailable"; return; }
- let project;
- for (let attempt = 0; attempt < 20; attempt++) {
- const candidate = `agentmemory-${i.port}`;
- const filter = `label=com.docker.compose.project=${candidate}`;
- const existing = await Promise.all([
- command(dockerBin, ["ps", "-aq", "--filter", filter], i.env(), i.dir),
- command(dockerBin, ["network", "ls", "-q", "--filter", filter], i.env(), i.dir),
- command(dockerBin, ["volume", "ls", "-q", "--filter", filter], i.env(), i.dir),
- ]);
- if (existing.every((value) => !value.trim())) { project = candidate; break; }
- i.port = await portBlock();
- }
- assert(project, "Could not reserve an unused Docker project");
- i.dockerProject = project;
- const at = Date.now(); i.start([], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
- await i.ready(90_000); d.freshReadyMs = Date.now() - at;
- const state = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); assert.equal(state.kind, "docker");
- const containerId = (await command(dockerBin, ["compose", "-p", i.dockerProject, "-f", join(pkg, "docker-compose.yml"), "ps", "-q", "iii-engine"], i.env(), i.dir)).trim(); assert(containerId);
- d.containerId = containerId;
- kill(i.cli.pid); await exited(i.cli, 3_000);
- await command(dockerBin, ["stop", "--time", "3", containerId], i.env(), i.dir, 15_000);
- const failedProxy = await delayedSocket(i, i.port + 46023, 10_000);
- d.stoppedRecoveryTimeout = await expectFailure(i, [], { III_ENGINE_URL: `ws://127.0.0.1:${failedProxy.port}`, AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 20_000, message: "0.3s" });
- const stopped = await command(dockerBin, ["inspect", "--format", "{{.State.Running}}", containerId], i.env(), i.dir); assert.equal(stopped.trim(), "false", "Failed recovery did not stop the container it restarted");
- assert.equal(JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")).containerId, containerId, "Failed Docker recovery lost lifecycle ownership");
- const proxy = await delayedSocket(i, i.port + 46023, 3_000);
- const restartAt = Date.now(); i.start([], { III_ENGINE_URL: `ws://127.0.0.1:${proxy.port}`, AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
- await i.ready(30_000); d.recoveryReadyMs = Date.now() - restartAt;
- assert(d.recoveryReadyMs >= 3000); assert(proxy.accepted() > 0);
- const restored = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); assert.equal(restored.containerId, containerId);
- kill(i.cli.pid); await exited(i.cli, 3_000);
- const externalProxy = await delayedSocket(i, i.port + 46023, 10_000);
- d.runningEngineTimeout = await expectFailure(i, [], { III_ENGINE_URL: `ws://127.0.0.1:${externalProxy.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 5_000, message: "0.3s" });
- const running = await command(dockerBin, ["inspect", "--format", "{{.State.Running}}", containerId], i.env(), i.dir); assert.equal(running.trim(), "true", "Failed attach stopped a preexisting running Docker engine");
- d.transport = "real Docker Compose pinned iii image; same owned container restarted; installed host worker over delayed TCP proxy";
+ await scenario("trace-storage-integrity", async (i, d) => {
+ i.start(); await i.ready(120_000);
+ const lifecycle = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8"));
+ assert.equal(lifecycle.kind, "compose");
+ const installedFiles = packageFiles();
+ const installedDigest = createHash("sha256").update(JSON.stringify(installedFiles)).digest("hex");
+ const configFile = join(i.data, "compose", "config", "iii-observability.yaml");
+ const entry = parseYaml(readFileSync(configFile, "utf8"));
+ assert.equal(entry.value.trace_storage.directory, join(i.data, "observability", "traces"));
+ assert(existsSync(entry.value.trace_storage.directory), "Trace storage directory was not provisioned in instance data");
+ const stop = await command(process.execPath, [cli, "stop", "--port", String(i.port)], i.env(), i.dir, 30_000);
+ d.stopped = true;
+ await poll("trace runtime shutdown", () => !alive(lifecycle.composePid), 10_000);
+ const finalFiles = packageFiles();
+ const finalDigest = createHash("sha256").update(JSON.stringify(finalFiles)).digest("hex");
+ assert.equal(finalDigest, installedDigest, "Installed package files changed after starting and stopping the managed runtime");
+ assert.deepEqual(finalFiles, installedFiles, "Installed package gained or lost files after starting and stopping the managed runtime");
+ assert.equal(createHash("sha256").update(readFileSync(tarball)).digest("hex"), artifactSha, "Packed artifact changed during the managed runtime smoke");
+ d.installedArtifactUnmodified = true; d.traceDirectory = entry.value.trace_storage.directory;
+ d.stopOutput = stop.slice(-300);
});
+
await scenario("demo", async (i, d) => {
- i.config({ delayMs: 2_000, earlyPid: true }); const at = Date.now();
+ const at = Date.now();
const child = i.start(["demo", "--serve"], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });
const result = await exited(child, 35_000); assert.equal(result.code, 0, child.text.slice(-1200)); assert(child.text.includes("demo complete"));
- d.completedMs = Date.now() - at; d.transport = "real native engine and installed demo command";
+ d.completedMs = Date.now() - at; d.transport = "real Worker Compose runtime and installed demo command";
assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Demo-owned engine survived teardown");
});
}
@@ -494,9 +535,6 @@ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(signal, () =>
for (const name of ["iii", "worker"]) kill(i.pid(name));
for (const row of i.wrapperStarts()) kill(row.pid);
for (const pid of i.ownedPids) kill(pid);
- if (i.dockerProject && !i.closed) {
- try { execFileSync(i.dockerBin, ["compose", "-p", i.dockerProject, "-f", join(pkg, "docker-compose.yml"), "down", "--volumes"], { env: i.env(), timeout: 30_000, stdio: "ignore" }); } catch {}
- }
}
for (const child of children) kill(child.pid);
process.exit(130);
@@ -504,9 +542,11 @@ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(signal, () =>
let fatal;
try { await main(); } catch (err) { fatal = err.stack; log(fatal); }
finally { for (const i of instances) await i.close(); for (const child of children) kill(child.pid); }
-const unchanged = cliSha ? cliSha === sha(cli) && pkgSha === packageDigest() && artifactSha === sha(tarball) : false;
-const summary = { ok: !fatal && unchanged && results.some((r) => r.status === "pass") && results.every((r) => r.status !== "fail"), version: installed?.version, enginePin: installed?.dependencies["iii-sdk"], tarball, tarballSha256: artifactSha, installedCliSha256: cliSha, installedPackageSha256: pkgSha, installedArtifactUnmodified: unchanged, node: process.version, platform: `${platform()}-${arch()}`, durationMs: Date.now() - started, root: options.keep ? root : undefined, scenarios: results, fatal };
+const finalPkgFiles = cliSha ? packageFiles() : [];
+const changedPackageFiles = pkgFiles ? pkgFiles.filter(([name, digest]) => !finalPkgFiles.some(([finalName, finalDigest]) => finalName === name && finalDigest === digest)).map(([name]) => name).concat(finalPkgFiles.filter(([name]) => !pkgFiles.some(([initialName]) => initialName === name)).map(([name]) => name)) : [];
+const unchanged = cliSha ? cliSha === sha(cli) && pkgSha === createHash("sha256").update(JSON.stringify(finalPkgFiles)).digest("hex") && artifactSha === sha(tarball) : false;
+const summary = { ok: !fatal && unchanged && results.some((r) => r.status === "pass") && results.every((r) => r.status !== "fail"), version: installed?.version, enginePin: installed?.dependencies["iii-sdk"], tarball, tarballSha256: artifactSha, installedCliSha256: cliSha, installedPackageSha256: pkgSha, changedPackageFiles, installedArtifactUnmodified: unchanged, node: process.version, platform: `${platform()}-${arch()}`, durationMs: Date.now() - started, root: options.keep ? root : undefined, scenarios: results, fatal };
writeFileSync(join(out, "summary.json"), JSON.stringify(summary, null, 2) + "\n");
log(`Summary: ${results.filter((r) => r.status === "pass").length}/${results.length} passed; ${join(out, "summary.json")}`);
-if (!options.keep && !out.startsWith(`${root}/`)) rmSync(root, { recursive: true, force: true });
+if (!options.keep && !out.startsWith(`${root}/`)) rmSync(root, { recursive: true, force: true, maxRetries: 20, retryDelay: 250 });
process.exit(summary.ok ? 0 : 1);
diff --git a/scripts/release-gate/summary-recovery.mjs b/scripts/release-gate/summary-recovery.mjs
index 42072a18..fa7908f9 100644
--- a/scripts/release-gate/summary-recovery.mjs
+++ b/scripts/release-gate/summary-recovery.mjs
@@ -1,6 +1,6 @@
#!/usr/bin/env node
import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
import { createHash } from "node:crypto";
import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import http from "node:http";
@@ -61,7 +61,7 @@ function cleanEnv() {
HOME: home, USERPROFILE: home, PATH: [dirname(process.execPath), "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(delimiter),
TMPDIR: tmpdir(), CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", III_TELEMETRY_ENABLED: "false",
AGENTMEMORY_DATA_DIR: dataDir, AGENTMEMORY_RUNTIME_DIR: runtime,
- III_REST_PORT: String(port), III_STREAM_PORT: String(port + 1), III_VIEWER_PORT: String(port + 2),
+ III_REST_PORT: String(port), III_VIEWER_PORT: String(port + 2),
III_ENGINE_PORT: String(port + 46023), AGENTMEMORY_METRICS_PORT: String(port + 6353), AGENTMEMORY_URL: `http://127.0.0.1:${port}`,
EMBEDDING_PROVIDER: "none", AGENTMEMORY_AUTO_COMPRESS: "true", AGENTMEMORY_FINALIZE_IDLE_MS: "0",
AGENTMEMORY_SESSION_SWEEP_ENABLED: "false", GRAPH_EXTRACTION_ENABLED: "false", CONSOLIDATION_ENABLED: "false", AGENTMEMORY_REFLECT: "false",
@@ -199,6 +199,17 @@ function rememberPids() {
if (Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid) ownedPids.add(pid);
} catch {}
}
+ // Process loss takes the whole runtime: Compose, engine and workers. Killing only the
+ // recorded pids left the daemon ports open on macOS CI, so collect the tree explicitly.
+ try {
+ const state = JSON.parse(readFileSync(join(runtime, "engine-state.json"), "utf8"));
+ for (const pid of [state.composePid, state.enginePid]) if (Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid) ownedPids.add(pid);
+ } catch {}
+ try {
+ const rows = execFileSync("ps", ["-eo", "pid=,ppid="], { encoding: "utf8" }).split(/\r?\n/).map((row) => row.trim().split(/\s+/).map(Number)).filter((row) => row.length === 2 && row.every(Number.isFinite));
+ let changed = true;
+ while (changed) { changed = false; for (const [child, parent] of rows) if (ownedPids.has(parent) && !ownedPids.has(child) && child !== process.pid) { ownedPids.add(child); changed = true; } }
+ } catch {}
}
async function startDaemon() {
boot++;
diff --git a/scripts/release-gate/vector-recovery.mjs b/scripts/release-gate/vector-recovery.mjs
index ad210286..40691181 100644
--- a/scripts/release-gate/vector-recovery.mjs
+++ b/scripts/release-gate/vector-recovery.mjs
@@ -27,6 +27,9 @@ for (const dir of [runtime, data, prefix]) mkdirSync(dir, { recursive: true });
if (options.dependencies) {
mkdirSync(pkg, { recursive: true });
execFileSync("tar", ["-xzf", options.tarball, "--strip-components=1", "-C", pkg]);
+ if (!existsSync(join(pkg, "dist/cli.mjs"))) {
+ execFileSync("tar", ["-xzf", options.tarball, "--strip-components=1", "-C", pkg]);
+ }
for (const entry of readdirSync(options.dependencies, { withFileTypes: true })) {
if (entry.name.startsWith(".")) continue;
if (entry.name.startsWith("@")) {
@@ -81,15 +84,50 @@ const fixture = createServer(async (req, res) => {
});
await new Promise((resolve, reject) => { fixture.once("error", reject); fixture.listen(0, "127.0.0.1", resolve); });
const fixturePort = fixture.address().port;
-let config = readFileSync(join(pkg, "iii-config.yaml"), "utf8").split(" - name: iii-exec")[0];
-config = config.replaceAll("3111", String(port)).replaceAll("3112", String(port + 1)).replaceAll("3113", String(port + 2)).replaceAll("./data/", `${data}/`);
-config += ` - name: iii-worker-manager\n config:\n port: ${port + 46023}\n host: 127.0.0.1\n`;
-const configPath = join(root, "iii-config.yaml"); writeFileSync(configPath, config);
+const namespace = `agentmemory-${port}`;
+const configPath = join(root, "worker-compose.yaml");
+const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+const config = [
+ `namespace: ${namespace}`,
+ "engine:",
+ ` url: ws://127.0.0.1:${port + 46023}`,
+ " workers:",
+ " configuration:",
+ " adapter:",
+ " name: fs",
+ " config:",
+ ` directory: ${quote(join(root, "compose-config"))}`,
+ " iii-worker-manager:",
+ " host: 127.0.0.1",
+ ` port: ${port + 46023}`,
+ "containers:",
+ " state:",
+ " worker: 'package://api.workers.iii.dev/state'",
+ " version: '0.22.20'",
+ " config_name: state",
+ " config_override:",
+ " adapter:",
+ " name: kv",
+ " config:",
+ " store_method: file_based",
+ ` file_path: ${quote(join(data, "state_store.db"))}`,
+ " save_interval_ms: 2000",
+ " http:",
+ " worker: 'package://api.workers.iii.dev/http'",
+ " version: '0.22.7'",
+ " config_name: http",
+ " config_override:",
+ " host: 127.0.0.1",
+ ` port: ${port}`,
+ " default_timeout: 180000",
+ "",
+].join("\n");
+writeFileSync(configPath, config);
const env = (extra = {}) => ({
HOME: home, USERPROFILE: home, PATH: [dirname(process.execPath), "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(delimiter), TMPDIR: root,
CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", OTEL_ENABLED: "false", III_TELEMETRY_ENABLED: "false",
- AGENTMEMORY_DATA_DIR: data, AGENTMEMORY_RUNTIME_DIR: runtime, III_REST_PORT: String(port), III_STREAM_PORT: String(port + 1), III_VIEWER_PORT: String(port + 2),
- III_ENGINE_PORT: String(port + 46023), III_ENGINE_URL: `ws://127.0.0.1:${port + 46023}`, AGENTMEMORY_METRICS_PORT: String(port + 6353),
+ AGENTMEMORY_DATA_DIR: data, AGENTMEMORY_RUNTIME_DIR: runtime, III_REST_PORT: String(port), III_VIEWER_PORT: String(port + 2),
+ III_ENGINE_PORT: String(port + 46023), III_ENGINE_URL: `ws://127.0.0.1:${port + 46023}`, III_NAMESPACE: namespace, AGENTMEMORY_METRICS_PORT: String(port + 6353),
LLM_PROVIDER: "none", EMBEDDING_PROVIDER: "openai", OPENAI_EMBEDDING_API_KEY: "local-fixture-only", OPENAI_EMBEDDING_DIMENSIONS: String(dimensions),
OPENAI_EMBEDDING_BASE_URL: `http://127.0.0.1:${fixture.address().port}/v1`, AGENTMEMORY_VECTOR_BACKFILL_MAX: "2", AGENTMEMORY_GRAPH_WEIGHT: "0",
AGENTMEMORY_GRAPH_COMPACT_ON_BOOT: "false", AGENTMEMORY_AUTO_COMPRESS: "false", AGENTMEMORY_SESSION_SWEEP_ENABLED: "false", AGENTMEMORY_FINALIZE_IDLE_MS: "0",
@@ -116,7 +154,7 @@ function persisted(scope = "mem:index:bm25") {
try { return decodeRkyvJsonScope(readFileSync(join(data, "state_store.db", `${encodeURIComponent(scope)}.bin`))); } catch { return {}; }
}
async function state(functionId, payload) {
- const client = registerWorker(`ws://127.0.0.1:${port + 46023}`, { workerName: "vector-recovery-fixture", invocationTimeoutMs: 5_000, enableMetricsReporting: false, otel: { enabled: false } });
+ const client = registerWorker(`ws://127.0.0.1:${port + 46023}`, { workerName: "vector-recovery-fixture", namespace, invocationTimeoutMs: 5_000, enableMetricsReporting: false, otel: { enabled: false } });
try { return await client.trigger({ function_id: functionId, payload }); }
finally { await client.shutdown(); }
}
@@ -131,8 +169,8 @@ async function stop(graceful = false) {
}
async function start(name, extra = {}, failure = false) {
inputs = 0;
- engineProcess = launch(engine, ["--config", configPath, "--no-update-check"], extra, `${name}-engine`);
- await poll("native engine", async () => (await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(500) })).status > 0);
+ engineProcess = launch(engine, ["compose", "--namespace", namespace, "--up", "--file", configPath], extra, `${name}-compose`);
+ await poll("Compose REST", async () => (await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(500) })).status > 0);
workerProcess = launch(process.execPath, [cli, "--no-engine", "--port", String(port), "--data-dir", data], extra, name);
if (failure) {
const result = await Promise.race([workerProcess.done, sleep(10_000).then(() => ({ timeout: true }))]);
diff --git a/scripts/skills/generate.ts b/scripts/skills/generate.ts
index 35efcb12..62d8c288 100644
--- a/scripts/skills/generate.ts
+++ b/scripts/skills/generate.ts
@@ -3,7 +3,7 @@ import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { getAllTools, ESSENTIAL_TOOLS } from "../../src/mcp/tools-registry.js";
import { ADAPTERS } from "../../src/cli/connect/index.js";
-import { collectRestEndpoints } from "./rest-endpoints.js";
+import { collectRestEndpointsInDirectory } from "./rest-endpoints.js";
const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");
@@ -86,8 +86,7 @@ function tools(): string {
}
function rest(): string {
- const text = readFileSync(join(SRC, "triggers", "api.ts"), "utf8");
- const rows = collectRestEndpoints(text);
+ const rows = collectRestEndpointsInDirectory(join(SRC, "triggers"));
const lines = [
`The REST API is the primary surface. All paths are under \`http://localhost:3111\` (override with \`--port\`). Send \`Authorization: Bearer <secret>\`: the value of \`AGENTMEMORY_SECRET\`, or the one generated into \`~/.agentmemory/secret\` on first start when it is unset. Writes must use \`Content-Type: application/json\`.`,
"",
diff --git a/scripts/skills/rest-endpoints.ts b/scripts/skills/rest-endpoints.ts
index 1a27c196..d3f32b54 100644
--- a/scripts/skills/rest-endpoints.ts
+++ b/scripts/skills/rest-endpoints.ts
@@ -1,3 +1,5 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
import ts from "typescript";
function property(object: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined {
@@ -10,9 +12,9 @@ function literal(value: ts.Node | undefined): string | undefined {
return value && ts.isStringLiteralLike(value) ? value.text : undefined;
}
-export function collectRestEndpoints(text: string): { path: string; method: string }[] {
+export function collectRestEndpoints(...texts: string[]): { path: string; method: string }[] {
const rows = new Map<string, { path: string; method: string }>();
- const source = ts.createSourceFile("api.ts", text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+ const sources = texts.map((text, index) => ts.createSourceFile(`source-${index}.ts`, text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS));
function visit(node: ts.Node): void {
if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "registerTrigger") {
const registration = node.arguments[0];
@@ -27,6 +29,12 @@ export function collectRestEndpoints(text: string): { path: string; method: stri
}
ts.forEachChild(node, visit);
}
- visit(source);
+ for (const source of sources) visit(source);
return [...rows.values()].sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
}
+
+export function collectRestEndpointsInDirectory(directory: string): { path: string; method: string }[] {
+ return collectRestEndpoints(...readdirSync(directory)
+ .filter((file) => file.endsWith(".ts"))
+ .map((file) => readFileSync(join(directory, file), "utf8")));
+}
diff --git a/src/capture/spool.ts b/src/capture/spool.ts
index 4c9a66bc..e1e0f6c2 100644
--- a/src/capture/spool.ts
+++ b/src/capture/spool.ts
@@ -112,7 +112,8 @@ const IMAGE_PLACEHOLDER = "[image dropped from capture spool]";
const BOOT_ID_RE = /^[A-Za-z0-9]{8,64}$/;
const SENT_FILE_RE = /^([A-Za-z0-9]{8,64})-(\d+)\.jsonl$/;
const SENT_BUCKET_MS = 1000;
-const MAX_DURABLE_AFTER_MS = 10 * 60_000;
+// Cover the maximum one-hour state flush interval plus its safety margin.
+const MAX_DURABLE_AFTER_MS = 61 * 60_000;
function emptyStats(): SpoolStats {
return { spooled: 0, dropped: 0, droppedBytes: 0, expired: 0, delivered: 0, duplicates: 0, rejected: 0 };
diff --git a/src/cli.ts b/src/cli.ts
index c5ba40d4..d0c85e03 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -7,7 +7,6 @@ import {
type ChildProcess,
} from "node:child_process";
import {
- cpSync,
existsSync,
mkdirSync,
readdirSync,
@@ -58,15 +57,7 @@ import {
import { portFlagSuffix } from "./cli/ready-hint.js";
import { expectedIiiSha256, iiiManualInstallCommand, installIiiArchive } from "./cli/engine-install.js";
import {
- dockerComposeArgs,
- dockerProjectName,
- isBundledConfig,
- legacyDataMigrations,
- resolveEngineCwd,
- rewriteBundledConfig,
runtimeConfigPath,
- engineChildEnv,
- resolveLaunchRenderFailure,
redactCredentialUrls,
} from "./cli/engine-launch.js";
import { runtimeMetadataPath } from "./runtime-paths.js";
@@ -79,24 +70,23 @@ import {
startupDeadline,
startupTimeoutMessage,
startupTimeouts,
+ managedComposeReadinessUrl,
waitForReadiness,
withinStartupDeadline,
type StartupDeadline,
} from "./cli/readiness.js";
import {
- clearPersistedBuiltinConfig,
engineFlushWaitMs,
engineStateConfigPaths,
- renderEngineConfig,
} from "./cli/engine-config.js";
import { SHUTDOWN_HARD_EXIT_MS, registerStartupCleanup, runStartupCleanup } from "./shutdown.js";
-import { consoleArgs, defaultConsolePort, parseConsoleArgs } from "./cli/console.js";
import { processStatIsRunning } from "./cli/process-state.js";
+import { readUnixProcessExecutable, sameResolvedExecutable } from "./cli/compose-process.js";
import { renderSplash } from "./cli/splash.js";
import { isFirstRun, readPrefs, resetPrefs, writePrefs } from "./cli/preferences.js";
import { runOnboarding } from "./cli/onboarding.js";
import { setBootVerbose } from "./logger.js";
-import { getRedisUrl, getStateBackend, getStateSaveIntervalMs, hydrateProcessEnvFromFile } from "./config.js";
+import { getRedisUrl, getStateBackend, hydrateProcessEnvFromFile } from "./config.js";
import { III_PINNED_VERSION, VERSION } from "./version.js";
import { getAllTools, ESSENTIAL_TOOLS } from "./mcp/tools-registry.js";
import { knownAgents } from "./cli/connect/index.js";
@@ -108,6 +98,9 @@ import { runCaptureCommand } from "./cli/capture.js";
import { runCompressionCommand } from "./cli/compression.js";
import { runGraphIndexCommand } from "./cli/graph-index.js";
import { bearerHeaders, resolveClientSecret } from "./secret-store.js";
+import { assertComposePortsFree, composeCall, composeRegistryFailureMessage, composeStateRegistryFailure, composeWorkerFailureSummary, ownedComposeProject, readComposeLogFromOffset, startComposeDaemon, writeComposeState, type ComposeStatus } from "./cli/compose-control.js";
+import { COMPOSE_WORKER_VERSIONS, composeNamespace } from "./cli/compose-project.js";
+import { legacyDockerStateMessage, type LegacyDockerEngineState } from "./cli/legacy-docker-state.js";
const __dirname = dirname(fileURLToPath(import.meta.url));
const args = process.argv.slice(2);
@@ -127,7 +120,7 @@ setBootVerbose(IS_VERBOSE);
const IS_RESET = args.includes("--reset");
// Fold ~/.agentmemory/.env into process.env before any port/URL read
-// (getRestPort/getBaseUrl/getStreamPort/getEnginePort) or the --port /
+// (getRestPort/getBaseUrl/getEnginePort) or the --port /
// --instance / --tools handlers below. Only-if-unset, so a real
// process.env value — including one just set by a CLI flag — still wins.
hydrateProcessEnvFromFile();
@@ -143,13 +136,10 @@ if (args.includes("--version") || args.includes("-V")) {
// Pinned iii-engine version. The engine, the iii-sdk and the @iii-dev/helpers
// packages in package.json must stay on the same release: the worker speaks
// that engine's wire protocol and the unpinned installer tracks `latest`.
-// 0.22.x is the last line before 0.23 removes the config.yaml worker
-// lifecycle this CLI relies on; it keeps HTTP routes owned by the
-// reconnecting worker (no REST 404s after an engine reconnect). The engine
-// still boots its iii- prefixed builtins from config.yaml (the unprefixed
-// http/state/queue/pubsub/cron names resolve to the standalone registry
-// workers, which is the 0.23 migration, not this one). Bump this
-// constant and the two package.json dependencies together.
+// Worker Compose supervises registry workers `state` and `http` alongside
+// the local agentmemory worker; the CLI relies on this lifecycle to keep
+// HTTP routes owned by the reconnecting worker. Bump this constant and
+// the two package.json dependencies together.
// AGENTMEMORY_III_VERSION overrides the pin for anyone running a
// self-managed engine.
const IIPINNED_DEFAULT_VERSION = III_PINNED_VERSION;
@@ -182,7 +172,7 @@ function iiiReleaseAsset(): string | null {
function iiiReleaseUrl(): string | null {
const asset = iiiReleaseAsset();
if (!asset) return null;
- // Tag name is monorepo-prefixed: `iii/v0.22.1`. Slash is URL-encoded
+ // Tag names are monorepo-prefixed: `iii/v<version>`. Slash is URL-encoded
// by GitHub when serving the download path, hence `iii/v...` not `iii%2Fv...`.
return `https://github.com/iii-hq/iii/releases/download/iii/v${IIPINNED_VERSION}/${asset}`;
}
@@ -214,15 +204,14 @@ agentmemory — persistent memory for AI coding agents
Usage: agentmemory [command] [options]
Commands:
- (default) Start agentmemory worker
+ (default) Start agentmemory via a per-instance Worker Compose project
init Copy bundled .env.example to ~/.agentmemory/.env if absent
connect [agent] Wire agentmemory into an installed agent
(${wrapList(knownAgents(), 21)}).
No arg = interactive picker. --all wires every detected agent.
--dry-run shows what would change. --force re-installs.
status Show connection status, memory count, flags, and health
- console Launch the iii web console for this engine (workers, functions,
- triggers, queues, traces). --console-port N, default viewer+1
+ console Show migration guidance for the retired iii console
doctor Interactive diagnostic + fixer. [F]ix · [S]kip · [?]more · [Q]uit
--all: apply every fix without prompting (CI)
--dry-run: show what each fix would do, don't execute
@@ -233,9 +222,8 @@ Commands:
in one command (no second terminal).
upgrade Upgrade local deps + iii runtime (best effort)
stop [--force] Stop the running iii-engine started by this CLI.
- --force bypasses the Docker-heuristic guard and signals
- whatever pidfile+lsof report on the REST port (use when
- the engine was started natively but state file is missing).
+ --force bypasses the native engine PID identity guard
+ (use when the engine was started natively but state file is missing).
mcp Start standalone MCP shim — opt-in surface for MCP-only clients
(Cursor, Gemini CLI, etc). REST always available at :3111.
capture [--drain] Show capture health: the local offline spool and the server
@@ -258,24 +246,18 @@ Options:
--reset Wipe ~/.agentmemory/preferences.json and re-run onboarding
--tools all|core Tool visibility (default: all = ${ALL_TOOLS_COUNT} tools; core = ${CORE_TOOLS_COUNT} essentials)
--no-engine Skip auto-starting iii-engine
- --port <N> Override REST port (default: 3111). Streams (N+1), viewer
- (N+2), and iii engine (N+46023) auto-derive from N so a
- single flag relocates the whole quartet.
+ --port <N> Override REST port (default: 3111). Viewer (N+2) and
+ iii engine (N+46023) derive from N for side-by-side instances.
--instance <N> Shortcut for --port (3111 + N*100) to run multiple
daemons side-by-side without env gymnastics.
- --instance 1 -> 3211/3212/3213/49234, etc. (max N=50)
+ --instance 1 -> 3211/3213/49234, etc. (max N=50)
--data-dir <path> Store iii-engine state outside the current repo
Environment:
AGENTMEMORY_URL Full REST base URL (e.g. http://localhost:3111).
Honored by status, doctor, and MCP shim commands.
AGENTMEMORY_DATA_DIR State directory fallback when --data-dir is not set.
- AGENTMEMORY_USE_DOCKER=1 Prefer the bundled docker-compose path over the
- native iii-engine binary on first run.
AGENTMEMORY_III_VERSION Override pinned iii-engine version (default ${IIPINNED_VERSION}).
- AGENTMEMORY_III_CONFIG Engine config to start from (default: ./iii-config.yaml,
- then ~/.agentmemory/iii-config.yaml, then the bundled
- loopback-only config).
AGENTMEMORY_ENGINE_READY_TIMEOUT_MS
Engine readiness deadline in milliseconds (default 120000).
AGENTMEMORY_READY_TIMEOUT_MS
@@ -289,7 +271,7 @@ Environment:
(default 30). Long values overcount, short values undercount.
Quick start:
- npx @agentmemory/agentmemory # start with local iii-engine or Docker
+ npx @agentmemory/agentmemory # start pinned iii Worker Compose runtime
npx @agentmemory/agentmemory demo # see semantic recall in 30 seconds
npx @agentmemory/agentmemory doctor # diagnose config + feature flags
npx @agentmemory/agentmemory status # health + memory count + flags
@@ -330,9 +312,9 @@ if (portValue) {
// `--instance N` picks a 100-port block off the 3111 base so multiple
// agentmemory daemons can coexist on one host without env-var
-// gymnastics. `--instance 0` keeps the canonical 3111/3112/3113/49134
-// quartet; `--instance 1` → 3211/3212/3213/49234; etc. REST acts as the
-// anchor — streams/viewer/engine derive from it via fixed offsets below
+// gymnastics. `--instance 0` keeps the canonical 3111/3113/49134
+// ports; `--instance 1` → 3211/3213/49234; etc. REST acts as the
+// anchor — viewer and engine derive from it via fixed offsets below
// unless an env explicitly pins each one.
const instanceValue = cliArgValue("--instance");
const hasInstanceArgument = args.some(
@@ -358,8 +340,6 @@ if (hasInstanceArgument) {
const restPort = parseInt(process.env["III_REST_PORT"] || "3111", 10);
if (Number.isFinite(restPort) && restPort > 0) {
- process.env["III_STREAM_PORT"] ??=
- process.env["III_STREAMS_PORT"] ?? String(restPort + 1);
process.env["III_VIEWER_PORT"] ??= String(restPort + 2);
const configuredEngineUrl = process.env["III_ENGINE_URL"];
if (configuredEngineUrl) {
@@ -455,20 +435,6 @@ function getViewerUrl(): string {
}
}
-// WebSocket streams port. Engine writes here; the SDK and viewer
-// subscribe. Honors both `III_STREAM_PORT` (the singular name the
-// engine docs use post-0.11) and `III_STREAMS_PORT` (the name our
-// own config.ts has used since 0.7) so a single source of truth in
-// either form lights up the ready panel. Falls back to REST+1 so
-// `--port 3211` auto-picks 3212 instead of colliding on 3112.
-function getStreamPort(): number {
- return (
- parseInt(process.env["III_STREAM_PORT"] || "", 10) ||
- parseInt(process.env["III_STREAMS_PORT"] || "", 10) ||
- getRestPort() + 1
- );
-}
-
// Bridge WebSocket port — the iii engine's internal worker bus.
// Defaults derived from REST as REST+46023 so the canonical 3111
// anchor yields 49134 and `--port 3211` auto-picks 49234 without a
@@ -488,7 +454,11 @@ function getEnginePort(): number {
}
async function isEngineRunning(): Promise<boolean> {
- const result = await withinStartupDeadline(startupDeadline(2000), (signal) => probeEngine(getBaseUrl(), signal)).catch(() => null);
+ const state = readEngineState();
+ const endpoint = state?.kind === "compose" && state.restPort === getRestPort() && !shouldUseAgentmemoryUrl()
+ ? `http://127.0.0.1:${state.restPort}`
+ : getBaseUrl();
+ const result = await withinStartupDeadline(startupDeadline(2000), (signal) => probeEngine(endpoint, signal)).catch(() => null);
return result?.completed === true && result.value;
}
@@ -501,26 +471,6 @@ function workerReadinessProbe(signal: AbortSignal): Promise<boolean> {
return probeWorker(getBaseUrl(), signal, (port) => { discoveredViewerPort = port; });
}
-function findIiiConfig(): string {
- // Precedence (user-overridable wins): explicit env > project cwd >
- // ~/.agentmemory/ > bundled. The bundled config used to win
- // unconditionally, so users hitting the observability log-feedback
- // loop had no way to drop a tamer config in place without
- // editing node_modules.
- const envPath = process.env["AGENTMEMORY_III_CONFIG"];
- const candidates = [
- ...(envPath ? [envPath] : []),
- join(process.cwd(), "iii-config.yaml"),
- join(homedir(), ".agentmemory", "iii-config.yaml"),
- join(__dirname, "iii-config.yaml"),
- join(__dirname, "..", "iii-config.yaml"),
- ];
- for (const c of candidates) {
- if (existsSync(c)) return resolve(c);
- }
- return "";
-}
-
function warnIfRelocatedDataDir(): void {
if (!dataDirResolution.relocatedFrom) return;
@@ -653,6 +603,25 @@ function engineStatePath(): string {
return runtimeMetadataPath("engine-state.json");
}
+type ComposeEngineState = {
+ kind: "compose";
+ restPort: number;
+ viewerPort: number;
+ enginePort: number;
+ engineUrl: string;
+ namespace: string;
+ file: string;
+ stateDir: string;
+ logFile: string;
+ logStartOffset?: number;
+ binPath: string;
+ composePid?: number;
+ enginePid?: number;
+ workerBinDir?: string;
+ workerFailure?: string;
+ workerVersions?: typeof COMPOSE_WORKER_VERSIONS | { local: true };
+};
+
type NativeEngineState = {
kind: "native";
configPath: string;
@@ -662,31 +631,8 @@ type NativeEngineState = {
restPort?: number;
};
-type DockerEngineState = {
- kind: "docker";
- schemaVersion?: 2;
- composeFile: string;
- projectName?: string;
- engineVersion?: string;
- restPort?: number;
- dataDir?: string;
- containerId?: string;
- dataMountType?: "bind" | "volume";
- dataMountSource?: string;
- preserveContainer?: boolean;
-};
-type EngineState = NativeEngineState | DockerEngineState;
-
-function writeEnginePidfile(pid: number): void {
- try {
- const pidPath = enginePidfilePath();
- mkdirSync(dirname(pidPath), { recursive: true });
- writeFileSync(pidPath, `${pid}\n`, { encoding: "utf-8" });
- } catch (err) {
- vlog(`writeEnginePidfile: ${err instanceof Error ? err.message : String(err)}`);
- }
-}
+type EngineState = NativeEngineState | LegacyDockerEngineState | ComposeEngineState;
function readEnginePidfile(): number | null {
try {
@@ -724,28 +670,11 @@ function clearWorkerPidfile(): void {
} catch {}
}
-function writeEngineState(state: EngineState): void {
- try {
- const statePath = engineStatePath();
- mkdirSync(dirname(statePath), { recursive: true });
- const normalized = state.kind === "docker" && state.schemaVersion === 2
- ? {
- ...state,
- restPort: state.restPort ?? getRestPort(),
- dataDir: state.dataDir ?? dataDirResolution.dataDir,
- }
- : { ...state, restPort: state.restPort ?? getRestPort() };
- writeFileSync(statePath, `${JSON.stringify(normalized)}\n`, { encoding: "utf-8" });
- } catch (err) {
- vlog(`writeEngineState: ${err instanceof Error ? err.message : String(err)}`);
- }
-}
-
function readEngineState(): EngineState | null {
try {
const raw = readFileSync(engineStatePath(), "utf-8");
const parsed = JSON.parse(raw) as Partial<EngineState>;
- if (parsed && (parsed.kind === "native" || parsed.kind === "docker")) {
+ if (parsed && (parsed.kind === "native" || parsed.kind === "docker" || parsed.kind === "compose")) {
return parsed as EngineState;
}
return null;
@@ -760,13 +689,9 @@ function clearEngineState(): void {
} catch {}
}
-function engineStateRestPort(state: EngineState): number {
+function engineStateRestPort(state: NativeEngineState | ComposeEngineState): number {
if (state.restPort && Number.isFinite(state.restPort)) return state.restPort;
- if (state.kind === "docker") {
- const projectPort = state.projectName?.match(/^agentmemory-(\d+)$/)?.[1];
- if (projectPort) return parseInt(projectPort, 10);
- return 3111;
- }
+ if (state.kind === "compose") return 3111;
try {
const raw = readFileSync(state.configPath, "utf-8");
const httpBlock = raw.match(
@@ -779,6 +704,65 @@ function engineStateRestPort(state: EngineState): number {
}
async function startWorkerForEngineState(background = false): Promise<void> {
+ if (readEngineState()?.kind === "compose") {
+ const timeoutMs = startupTimeouts().workerMs;
+ const ready = await waitForReadiness(startupDeadline(timeoutMs), workerReadinessProbe, {
+ stopped: () => {
+ const state = readEngineState();
+ if (state?.kind === "compose") {
+ try {
+ const failure = composeRegistryFailureMessage(readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0), state.workerBinDir);
+ if (failure) startupFailure = { kind: "engine-crashed", stderr: failure };
+ } catch {}
+ }
+ return startupInterrupted || engineStartupFailed() || Boolean(startupFailure?.stderr?.startsWith("Worker registry unavailable"));
+ },
+ });
+ if (!ready) {
+ printComposeStartupLogs();
+ const state = readEngineState();
+ let registryFailure = state?.kind === "compose" ? composeStateRegistryFailure(dataDirResolution.dataDir, state.file) : null;
+ if (state?.kind === "compose" && !registryFailure) {
+ registryFailure = (() => {
+ try { return composeRegistryFailureMessage(readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0), state.workerBinDir); } catch { return null; }
+ })();
+ }
+ if (state?.kind === "compose" && await isEngineRunning()) {
+ try {
+ const status = await composeCall<ComposeStatus>({ engineUrl: state.engineUrl, namespace: state.namespace, functionId: "compose::status", file: state.file });
+ const project = ownedComposeProject(status, state.file);
+ const failures = (project?.containers ?? [])
+ .filter((container) => container.state === "failed" || container.last_error)
+ .map((container) => {
+ let detail = container.last_error ?? container.state ?? "failed";
+ if (container.log_path) {
+ try {
+ const log = readFileSync(container.log_path, "utf8").trim();
+ if (log) detail += `\n${log.split(/\r?\n/).slice(-12).join("\n")}`;
+ } catch {}
+ }
+ return `${container.container ?? "worker"}: ${detail}`;
+ });
+ if (failures.length) {
+ state.workerFailure = failures.join("\n");
+ writeComposeState(engineStatePath(), { ...state, workerVersions: state.workerVersions ?? (state.workerBinDir ? { local: true } : COMPOSE_WORKER_VERSIONS) });
+ const aggregate = composeRegistryFailureMessage(state.workerFailure, state.workerBinDir);
+ if (aggregate) {
+ registryFailure = `${aggregate} Compose reported: ${state.workerFailure}`;
+ } else {
+ const logTail = readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0)
+ .trim().split(/\r?\n/).slice(-12).join("\n");
+ registryFailure = `Worker Compose failed: ${state.workerFailure}${logTail ? `\nRecent Compose output:\n${logTail}` : ""}`;
+ }
+ }
+ } catch {}
+ }
+ throw new Error(registryFailure || startupFailure?.stderr || startupTimeoutMessage("worker", timeoutMs));
+ }
+ composeStartupCompleted = true;
+ finishStartup();
+ return;
+ }
const timeoutMs = startupTimeouts().workerMs;
startupWorkerFailure = null;
const ready = await startWorkerAndWait({
@@ -838,368 +822,17 @@ function configuredEngineMayStartWorker(): boolean {
}
-function discoverComposeFile(): string | null {
- const candidates = [
- join(__dirname, "..", "docker-compose.yml"),
- join(__dirname, "docker-compose.yml"),
- join(process.cwd(), "docker-compose.yml"),
- ];
- return candidates.find((c) => existsSync(c)) ?? null;
-}
-
-type DockerEngineInspection =
- | {
- status: "running" | "stopped";
- composeFile: string;
- projectName: string;
- containerId: string;
- dataMountType: "bind" | "volume";
- dataMountSource: string;
- preserveContainer: boolean;
- }
- | { status: "missing"; composeFile: string; projectName?: string }
- | { status: "unavailable"; reason: string };
-
-type DockerInspectRecord = {
- Id?: string;
- State?: { Running?: boolean };
- Config?: { Image?: string; Labels?: Record<string, string> };
- HostConfig?: {
- PortBindings?: Record<
- string,
- Array<{ HostIp?: string; HostPort?: string }> | null
- >;
- };
- Mounts?: Array<{
- Type?: string;
- Name?: string;
- Source?: string;
- Destination?: string;
- }>;
-};
-
-function sameDockerMountSource(
- type: "bind" | "volume",
- left: string,
- right: string,
-): boolean {
- return type === "bind" ? resolve(left) === resolve(right) : left === right;
-}
-
-function inspectDockerContainer(
- dockerBin: string,
- containerId: string,
- state: DockerEngineState,
- ownerPort: number,
-): DockerEngineInspection {
- const result = spawnSync(dockerBin, ["inspect", containerId], {
- encoding: "utf-8",
- stdio: ["ignore", "pipe", "ignore"],
- maxBuffer: 1024 * 1024,
- timeout: 5000,
- killSignal: "SIGKILL",
- });
- if (result.status !== 0) {
- return { status: "unavailable", reason: `docker inspect failed for ${containerId}` };
- }
- let record: DockerInspectRecord;
- try {
- record = (JSON.parse(result.stdout) as DockerInspectRecord[])[0] ?? {};
- } catch {
- return { status: "unavailable", reason: `docker inspect returned invalid JSON for ${containerId}` };
- }
-
- const image = record.Config?.Image ?? "";
- const expectedImage = `iiidev/iii:${state.engineVersion ?? IIPINNED_VERSION}`;
- if (image !== expectedImage) {
- return {
- status: "unavailable",
- reason: `saved container uses ${image || "an unknown image"}, expected ${expectedImage}`,
- };
- }
-
- const labels = record.Config?.Labels ?? {};
- const projectName = labels["com.docker.compose.project"] ?? "";
- if (labels["com.docker.compose.service"] !== "iii-engine" || !projectName) {
- return {
- status: "unavailable",
- reason: "saved container is not the iii-engine service of a Compose project",
- };
- }
- if (state.projectName && state.projectName !== projectName) {
- return {
- status: "unavailable",
- reason: `saved Docker project ${state.projectName} does not match container project ${projectName}`,
- };
- }
- if (state.schemaVersion === 2 && projectName !== dockerProjectName(ownerPort)) {
- return {
- status: "unavailable",
- reason: `Docker project ${projectName} does not match REST port ${ownerPort}`,
- };
- }
-
- const restBindings = record.HostConfig?.PortBindings?.[`${ownerPort}/tcp`] ?? [];
- if (!restBindings.some((binding) => binding.HostPort === String(ownerPort))) {
- return {
- status: "unavailable",
- reason: `saved container does not publish REST port ${ownerPort}`,
- };
- }
-
- const dataMount = record.Mounts?.find((mount) => mount.Destination === "/data");
- const dataMountType = dataMount?.Type;
- const dataMountSource = dataMountType === "volume"
- ? dataMount?.Name ?? dataMount?.Source ?? ""
- : dataMount?.Source ?? "";
- if (
- (dataMountType !== "bind" && dataMountType !== "volume") ||
- !dataMountSource
- ) {
- return {
- status: "unavailable",
- reason: "saved container has no verifiable /data bind or volume mount",
- };
- }
- if (
- state.dataMountType &&
- state.dataMountType !== dataMountType
- ) {
- return {
- status: "unavailable",
- reason: `saved /data mount type ${state.dataMountType} changed to ${dataMountType}`,
- };
- }
- if (
- state.dataMountSource &&
- !sameDockerMountSource(dataMountType, state.dataMountSource, dataMountSource)
- ) {
- return {
- status: "unavailable",
- reason: "saved container /data mount source changed",
- };
- }
- if (!state.dataMountSource) {
- if (
- dataMountType === "bind" &&
- resolve(dataMountSource) !== resolve(dataDirResolution.dataDir)
- ) {
- return {
- status: "unavailable",
- reason: `container /data bind ${dataMountSource} does not match ${dataDirResolution.dataDir}`,
- };
- }
- if (dataMountType === "volume" && dataDirResolution.source !== "default") {
- return {
- status: "unavailable",
- reason: "legacy container uses a named volume but this invocation selects an explicit data directory",
- };
- }
- }
- if (
- state.dataDir &&
- resolve(state.dataDir) !== resolve(dataDirResolution.dataDir)
- ) {
- return {
- status: "unavailable",
- reason: `saved data directory ${state.dataDir} does not match ${dataDirResolution.dataDir}`,
- };
- }
-
- return {
- status: record.State?.Running ? "running" : "stopped",
- composeFile: existsSync(state.composeFile)
- ? state.composeFile
- : discoverComposeFile() ?? state.composeFile,
- projectName,
- containerId: record.Id ?? containerId,
- dataMountType,
- dataMountSource,
- preserveContainer:
- state.preserveContainer === true ||
- (state.schemaVersion !== 2 && dataMountType === "volume"),
- };
-}
-
-function inspectOwnedDockerEngine(state: EngineState): DockerEngineInspection {
- if (state.kind !== "docker") {
- return { status: "unavailable", reason: "engine state is not Docker" };
- }
- const ownerPort = engineStateRestPort(state);
- if (state.schemaVersion === 2 && state.projectName !== dockerProjectName(ownerPort)) {
- return {
- status: "unavailable",
- reason: `saved Docker project ${state.projectName} does not match REST port ${ownerPort}`,
- };
- }
-
- const dockerBin = whichBinary("docker");
- if (!dockerBin) {
- return { status: "unavailable", reason: "docker is not on PATH" };
- }
-
- const discoveryFailures: string[] = [];
- if (state.containerId) {
- const direct = inspectDockerContainer(dockerBin, state.containerId, state, ownerPort);
- if (direct.status !== "unavailable") return direct;
- if (state.preserveContainer) return direct;
- discoveryFailures.push(direct.reason);
- }
-
- const composeFile = existsSync(state.composeFile)
- ? state.composeFile
- : discoverComposeFile() ?? state.composeFile;
- const candidateIds = new Set<string>();
- try {
- if (existsSync(composeFile)) {
- const composeText = readFileSync(composeFile, "utf-8");
- if (!/^\s+iii-engine:/m.test(composeText)) {
- return {
- status: "unavailable",
- reason: `${composeFile} does not define iii-engine`,
- };
- }
- const psResult = spawnSync(
- dockerBin,
- dockerComposeArgs(composeFile, state.projectName, [
- "ps",
- "-q",
- "--all",
- "iii-engine",
- ]),
- { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, killSignal: "SIGKILL" },
- );
- if (psResult.status === 0) {
- for (const id of (psResult.stdout ?? "").trim().split(/\s+/)) {
- if (id) candidateIds.add(id);
- }
- } else {
- discoveryFailures.push(
- `docker compose ps failed for project ${state.projectName ?? "<default>"}`,
- );
- }
- }
-
- const scanArgs = [
- "ps",
- "-aq",
- "--filter",
- "label=com.docker.compose.service=iii-engine",
- "--filter",
- `ancestor=iiidev/iii:${state.engineVersion ?? IIPINNED_VERSION}`,
- ...(state.projectName
- ? ["--filter", `label=com.docker.compose.project=${state.projectName}`]
- : []),
- ];
- const scanResult = spawnSync(
- dockerBin,
- scanArgs,
- { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, killSignal: "SIGKILL" },
- );
- if (scanResult.status === 0) {
- for (const id of (scanResult.stdout ?? "").trim().split(/\s+/)) {
- if (id) candidateIds.add(id);
- }
- } else {
- discoveryFailures.push("docker container scan failed");
- }
-
- const matches: DockerEngineInspection[] = [];
- for (const containerId of candidateIds) {
- const inspected = inspectDockerContainer(dockerBin, containerId, state, ownerPort);
- if (inspected.status === "running" || inspected.status === "stopped") {
- if (
- !matches.some(
- (match) =>
- (match.status === "running" || match.status === "stopped") &&
- match.containerId === inspected.containerId,
- )
- ) {
- matches.push(inspected);
- }
- } else if (inspected.status === "unavailable") {
- discoveryFailures.push(inspected.reason);
- }
- }
- if (matches.length === 1) return matches[0]!;
- if (matches.length > 1) {
- return {
- status: "unavailable",
- reason: `multiple Docker iii-engine containers match REST port ${ownerPort}`,
- };
- }
- if (discoveryFailures.length > 0) {
- return {
- status: "unavailable",
- reason: [...new Set(discoveryFailures)].join("; "),
- };
- }
- if (state.schemaVersion !== 2 || state.preserveContainer) {
- return {
- status: "unavailable",
- reason: `legacy Docker ownership exists for REST port ${ownerPort}, but no unique container can be verified`,
- };
- }
- return {
- status: "missing",
- composeFile,
- projectName: state.projectName,
- };
- } catch (err) {
- return {
- status: "unavailable",
- reason: err instanceof Error ? err.message : String(err),
- };
- }
-}
-
-function persistDockerInspection(
- state: DockerEngineState,
- inspection: DockerEngineInspection,
-): DockerEngineState {
- if (inspection.status !== "running" && inspection.status !== "stopped") {
- return state;
- }
- const resolved: DockerEngineState = {
- ...state,
- composeFile: inspection.composeFile,
- projectName: inspection.projectName,
- containerId: inspection.containerId,
- dataMountType: inspection.dataMountType,
- dataMountSource: inspection.dataMountSource,
- preserveContainer: inspection.preserveContainer,
- };
- writeEngineState(resolved);
- return resolved;
-}
-
async function assertRuntimePortOwnership(): Promise<void> {
const state = readEngineState();
if (!state) return;
- const ownerPort = engineStateRestPort(state);
- const requestedPort = getRestPort();
- if (ownerPort === requestedPort) return;
-
if (state.kind === "docker") {
- const inspection = inspectOwnedDockerEngine(state);
- if (inspection.status === "unavailable") {
- p.log.error(
- `The data directory contains Docker ownership for REST port ${ownerPort}, but it cannot be verified: ${inspection.reason}. Refusing to overwrite its lifecycle state.`,
- );
- process.exit(1);
- }
- if (inspection.status === "running" || inspection.status === "stopped") {
- persistDockerInspection(state, inspection);
- p.log.error(
- `The canonical lifecycle state is owned by a ${inspection.status} Docker engine on REST port ${ownerPort}. Refusing to reuse it for port ${requestedPort}. Use the original port, or use --instance <N> for an isolated daemon.`,
- );
- process.exit(1);
- }
- p.log.error(
- `The canonical lifecycle state still records a Docker engine for REST port ${ownerPort}, but its container is missing. Refusing to overwrite that ownership from port ${requestedPort}. Re-run \`agentmemory stop\` with the original port to reconcile it.`,
- );
+ p.log.error(legacyDockerStateMessage(state));
process.exit(1);
}
+ const ownerPort = engineStateRestPort(state);
+ if (state.kind === "compose" && ownerPort !== getRestPort()) return;
+ const requestedPort = getRestPort();
+ if (ownerPort === requestedPort) return;
const enginePid = readEnginePidfile();
const workerPid = readWorkerPidfile();
@@ -1228,22 +861,6 @@ async function assertRuntimePortOwnership(): Promise<void> {
clearEngineState();
}
-function configureDockerHostUser(): void {
- if (typeof process.getuid !== "function" || typeof process.getgid !== "function") {
- return;
- }
- const hostUid = String(process.getuid());
- const hostGid = String(process.getgid());
- process.env["AGENTMEMORY_DOCKER_UID"] ??= hostUid;
- process.env["AGENTMEMORY_DOCKER_GID"] ??= hostGid;
- if (
- process.env["AGENTMEMORY_DOCKER_UID"] === hostUid &&
- process.env["AGENTMEMORY_DOCKER_GID"] === hostGid
- ) {
- process.env["AGENTMEMORY_DOCKER_SKIP_CHOWN"] ??= "1";
- }
-}
-
function isInvokedViaNpx(): boolean {
if (process.env["npm_lifecycle_event"] === "npx") return true;
const argv1 = process.argv[1] ?? "";
@@ -1307,44 +924,6 @@ async function maybeOfferGlobalInstall(): Promise<void> {
}
}
-function adoptRunningEngine(): void {
- try {
- const existingState = readEngineState();
- const existingPid = readEnginePidfile();
- if (existingState && existingPid) return;
-
- const pids = findEnginePidsByPort(getRestPort());
- const enginePid = pids[0];
- if (enginePid) {
- // A Docker-forwarded port is held by the VM/proxy process
- // (com.docker.backend, vpnkit, ...), not the engine. Adopting it
- // as kind:"native" would make a later `stop` SIGTERM that process.
- const comm = pidCommand(enginePid);
- if (isForeignPortHolder(comm)) {
- vlog(
- `adoptRunningEngine: refusing to adopt pid ${enginePid} (${comm}) — not the iii engine binary`,
- );
- return;
- }
- }
- if (enginePid && !existingPid) {
- writeEnginePidfile(enginePid);
- }
- if (!existingState) {
- writeEngineState({
- kind: "native",
- configPath: findIiiConfig() || "",
- attached: true,
- });
- }
- if (enginePid && !existingPid) {
- p.log.info(c.ok(`Attached to existing iii-engine (pid ${enginePid})`));
- }
- } catch (err) {
- vlog(`adoptRunningEngine: ${err instanceof Error ? err.message : String(err)}`);
- }
-}
-
async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null }> {
const releaseUrl = iiiReleaseUrl();
const asset = iiiReleaseAsset();
@@ -1352,7 +931,7 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
if (!releaseUrl) {
p.log.warn(
- `iii-engine binary not available for ${platform()}/${process.arch}. Use Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
+ `iii-engine binary not available for ${platform()}/${process.arch}. Download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
);
return { ok: false, binPath: null };
}
@@ -1363,7 +942,7 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
` 1. Download ${releaseUrl}\n` +
` Its SHA-256 must be ${expectedIiiSha256(IIPINNED_VERSION, asset ?? "") ?? `the value in ${releaseUrl.replace(/\.zip$/, ".sha256")}`}\n` +
` 2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` +
- `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
+ `Install the pinned iii binary from ${releaseUrl}`,
);
return { ok: false, binPath: null };
}
@@ -1408,8 +987,7 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
`${heading}: ${outcome.detail.slice(0, 300)}\n` +
`Install it manually, then re-run agentmemory:\n` +
` ${iiiManualInstallCommand(releaseUrl, binDir, binPath, sha256)}\n` +
- checksumHint +
- `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
+ checksumHint,
);
return { ok: false, binPath: null };
}
@@ -1418,7 +996,7 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
}
type StartupFailure = {
- kind: "no-engine" | "no-docker-compose" | "engine-crashed" | "docker-crashed";
+ kind: "no-engine" | "engine-crashed";
stderr?: string;
binary?: string;
};
@@ -1426,11 +1004,11 @@ type StartupFailure = {
let startupFailure: StartupFailure | null = null;
let activeStartupStderr = createStartupStderrCapture();
let spawnedNativeEngine: ChildProcess | null = null;
+let spawnedComposeDaemon: ChildProcess | null = null;
+let composeStartupCompleted = false;
let importedStartupWorker = false;
let spawnedStartupWorker: ChildProcess | null = null;
let startupWorkerFailure: Error | null = null;
-let spawnedDockerCommand: ChildProcess | null = null;
-let startedDockerEngine: DockerEngineState | null = null;
let engineReadinessDeadline: StartupDeadline | null = null;
let startupInterrupted = false;
let finishStartup = (): void => {};
@@ -1456,7 +1034,7 @@ function beginStartup(): void {
}
function engineStartupFailed(): boolean {
- return startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed";
+ return startupFailure?.kind === "engine-crashed";
}
async function cleanupFailedStartup(): Promise<void> {
@@ -1471,27 +1049,12 @@ async function cleanupFailedStartup(): Promise<void> {
}
if (readWorkerPidfile() === worker.pid) clearWorkerPidfile();
}
- const dockerCommand = spawnedDockerCommand;
- spawnedDockerCommand = null;
- if (dockerCommand && typeof dockerCommand.pid === "number" && dockerCommand.exitCode === null && dockerCommand.signalCode === null) {
- await signalAndWait(dockerCommand.pid, "SIGTERM", 1000);
- }
- const dockerState = startedDockerEngine;
- startedDockerEngine = null;
- if (dockerState) {
- const inspection = inspectOwnedDockerEngine(dockerState);
- if (inspection.status === "running" || inspection.status === "stopped") {
- persistDockerInspection(dockerState, inspection);
- const dockerBin = whichBinary("docker");
- if (inspection.status === "running" && dockerBin) {
- runCommand(dockerBin, ["stop", "--time", "10", inspection.containerId], {
- label: "Stopping the Docker container started by this invocation",
- timeoutMs: 15_000,
- });
- }
- } else {
- p.log.warn("Docker startup ownership could not be verified for cleanup; project state was preserved for `agentmemory stop`.");
- }
+ const composeChild = spawnedComposeDaemon;
+ spawnedComposeDaemon = null;
+ if (composeChild && typeof composeChild.pid === "number") {
+ const stopped = await signalAndWait(composeChild.pid, "SIGTERM", 20_000);
+ if (!stopped) p.log.warn(`Compose daemon pid ${composeChild.pid} survived shutdown; lifecycle state was preserved.`);
+ else clearEngineState();
}
const child = spawnedNativeEngine;
spawnedNativeEngine = null;
@@ -1519,215 +1082,186 @@ function printCapturedStartupStderr(): void {
}
}
-function printDockerStartupLogs(): void {
+function readComposeStartupLogs(): { path: string; text: string } | null {
const state = readEngineState();
- if (state?.kind !== "docker") return;
- const inspection = inspectOwnedDockerEngine(state);
- if (inspection.status !== "running" && inspection.status !== "stopped") return;
- const dockerBin = whichBinary("docker");
- if (!dockerBin) return;
- const result = spawnSync(
- dockerBin,
- [
- "logs",
- "--tail",
- "80",
- inspection.containerId,
- ],
- {
- encoding: "utf-8",
- stdio: ["ignore", "pipe", "pipe"],
- timeout: 5000,
- killSignal: "SIGKILL",
- maxBuffer: 64 * 1024,
- },
- );
- const output = redactCredentialUrls(`${result.stdout ?? ""}${result.stderr ?? ""}`.trim());
- if (output) p.note(output.slice(-16 * 1024), "docker engine logs");
+ if (state?.kind !== "compose") return null;
+ try {
+ const text = readComposeLogFromOffset(state.logFile, state.logStartOffset ?? 0).trim();
+ return { path: state.logFile, text: redactCredentialUrls(text.slice(-16 * 1024)) };
+ } catch {
+ return { path: state.logFile, text: "(Compose log file could not be read.)" };
+ }
}
-// Spawn a background engine and collect any startup stderr for a short
-// window. The process is unref'd so the CLI parent can exit cleanly; we
-// only care about stderr that shows up BEFORE the health check succeeds,
-// which is what surfaces early crash/config-parse errors on all platforms.
-function spawnEngineBackground(
- bin: string,
- spawnArgs: string[],
- label: string,
- cwd?: string,
-): ChildProcess {
- vlog(`spawn: ${bin} ${spawnArgs.join(" ")}${cwd ? ` (cwd: ${cwd})` : ""}`);
- activeStartupStderr = createStartupStderrCapture();
- startupFailure = null;
- engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
- const child = spawn(bin, spawnArgs, {
- detached: true,
- stdio: ["ignore", "ignore", "pipe"],
- windowsHide: true,
- env: engineChildEnv(process.env),
- ...(cwd ? { cwd } : {}),
- });
- const isDocker = label.includes("Docker");
- if (isDocker) spawnedDockerCommand = child;
- if (!isDocker) {
- spawnedNativeEngine = child;
- if (typeof child.pid === "number") writeEnginePidfile(child.pid);
- }
- child.on("error", (error) => {
- if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;
- startupFailure = {
- kind: isDocker ? "docker-crashed" : "engine-crashed",
- stderr: redactCredentialUrls(error.message),
- binary: bin,
- };
- if (!isDocker && spawnedNativeEngine === child) {
- clearEnginePidfile();
- clearEngineState();
- }
- });
- child.stderr?.on("data", (chunk: Buffer) => {
- if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;
- activeStartupStderr.append(chunk);
- });
- (child.stderr as { unref?: () => void } | null)?.unref?.();
- child.on("exit", (code, signal) => {
- if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;
- const abnormal = !isDocker || (code !== null && code !== 0) || (code === null && signal !== null);
- if (abnormal) {
- const stderr = redactCredentialUrls(activeStartupStderr.text());
- startupFailure = {
- kind: isDocker ? "docker-crashed" : "engine-crashed",
- stderr:
- stderr.trim() ||
- (signal
- ? `process killed by signal ${signal}`
- : `process exited with code ${code}`),
- binary: bin,
- };
- vlog(`engine exited early: code=${code} signal=${signal}`);
- if (IS_VERBOSE && stderr.trim()) {
- p.log.error(`engine stderr:\n${stderr}`);
- }
- if (!isDocker && readEnginePidfile() === child.pid) {
- clearEnginePidfile();
- clearEngineState();
- }
- }
- });
- child.unref();
- return child;
+function printComposeStartupLogs(): void {
+ const logs = readComposeStartupLogs();
+ if (!logs) return;
+ if (logs.text) p.note(`Log file: ${logs.path}\n\n${logs.text}`, "Recent Worker Compose output");
}
-function prepareEngineLaunch(configPath: string): {
- configPath: string;
- cwd: string;
-} {
- const home = homedir();
- const bundledConfig = isBundledConfig(configPath, __dirname);
- const cwd = resolveEngineCwd(
- configPath,
- process.cwd(),
- home,
- bundledConfig,
- );
- const stateBackendKind = getStateBackend();
+function composePidMatches(pid: number, state: ComposeEngineState): boolean {
try {
- mkdirSync(cwd, { recursive: true });
- } catch (err) {
- const failure = resolveLaunchRenderFailure(stateBackendKind, err);
- if (failure.fatal) {
- p.log.error(failure.message);
- process.exit(1);
- }
- return { configPath, cwd: process.cwd() };
+ let command = "";
+ let executable = "";
+ if (IS_WINDOWS) {
+ // Preserve the existing PowerShell CIM ExecutablePath check on Windows;
+ // if CIM does not provide a path, the process is not considered owned.
+ const script = `$process = Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}'; if ($process) { @{ command = $process.CommandLine; executable = $process.ExecutablePath } | ConvertTo-Json -Compress }`;
+ const result = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+ const processInfo = JSON.parse(result) as { command?: string; executable?: string };
+ command = processInfo.command ?? "";
+ executable = processInfo.executable ?? "";
+ } else if (platform() === "darwin") {
+ command = execFileSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+ executable = readUnixProcessExecutable(pid, "darwin");
+ } else {
+ command = execFileSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+ executable = readUnixProcessExecutable(pid, "linux");
+ }
+ const expectedCommand = command.includes("compose") &&
+ command.includes("compose --namespace") &&
+ command.includes(state.namespace) &&
+ command.includes(state.file);
+ if (!expectedCommand) return false;
+ if (!executable) return false;
+ return sameResolvedExecutable(executable, state.binPath, IS_WINDOWS);
+ } catch {
+ return false;
}
+}
+
+function composeChildProcesses(state: ComposeEngineState): Array<{ pid: number; pgid: number; args: string }> {
+ if (IS_WINDOWS || !state.composePid) return [];
try {
- const rawConfig = readFileSync(configPath, "utf-8");
- const options = {
- dataDir: dataDirResolution.dataDir,
- ports: {
- restPort: getRestPort(),
- streamPort: getStreamPort(),
- viewerPort: getConfiguredViewerPort(),
- enginePort: getEnginePort(),
- },
- stateBackend: { kind: stateBackendKind, redisUrl: getRedisUrl() },
- saveIntervalMs: getStateSaveIntervalMs(),
- };
- const rewritten = bundledConfig
- ? rewriteBundledConfig(
- rawConfig,
- home,
- process.execPath,
- join(__dirname, "index.mjs"),
- options,
- )
- : renderEngineConfig(rawConfig, options);
- const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
- mkdirSync(dirname(runtimePath), { recursive: true });
- writeFileSync(runtimePath, rewritten, "utf-8");
- try {
- const cleared = clearPersistedBuiltinConfig(cwd, runtimePath, rewritten);
- if (cleared.length > 0) {
- vlog(
- `cleared ${cleared.length} persisted builtin config entries so the rendered runtime config seeds the engine again`,
- );
- }
- } catch (err) {
- p.log.error(
- `${String(err instanceof Error ? err.message : err)}. The engine would ignore the rendered runtime config and keep its previously persisted ports and timeouts. Fix the permissions on that file and run agentmemory start again.`,
- );
- process.exit(1);
- }
- if (selectedInstance === 0 && dataDirResolution.source === "default") {
- for (const m of legacyDataMigrations(
- process.cwd(),
- home,
- dataDirResolution.dataDir,
- )) {
- if (existsSync(m.from) && !existsSync(m.to)) {
- try {
- mkdirSync(dirname(m.to), { recursive: true });
- cpSync(m.from, m.to, { recursive: true });
- p.log.info(`Copied existing data: ${m.from} -> ${m.to}`);
- } catch (err) {
- vlog(`data copy failed for ${m.from}: ${String(err)}`);
- }
+ const rows = execFileSync("ps", ["-eo", "pid=,ppid=,pgid=,command="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+ .split(/\r?\n/)
+ .map((row) => {
+ const match = row.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+ return match ? { pid: Number(match[1]), ppid: Number(match[2]), pgid: Number(match[3]), args: match[4]! } : null;
+ })
+ .filter((row): row is { pid: number; ppid: number; pgid: number; args: string } => row !== null);
+ const descendants = new Set([state.composePid]);
+ let changed = true;
+ while (changed) {
+ changed = false;
+ for (const row of rows) {
+ if (!descendants.has(row.pid) && descendants.has(row.ppid)) {
+ descendants.add(row.pid);
+ changed = true;
}
}
}
- return {
- configPath: runtimePath,
- cwd,
- };
- } catch (err) {
- const failure = resolveLaunchRenderFailure(stateBackendKind, err);
- if (failure.fatal) {
- p.log.error(failure.message);
- process.exit(1);
+ return rows
+ .filter((row) => row.pid !== state.composePid && descendants.has(row.pid))
+ .map(({ pid, pgid, args }) => ({ pid, pgid, args }));
+ } catch {
+ return [];
+ }
+}
+
+function composeChildPids(state: ComposeEngineState): number[] {
+ return [...new Set(composeChildProcesses(state).map((child) => child.pid))];
+}
+
+function composeEnginePid(state: ComposeEngineState): number | undefined {
+ return composeChildProcesses(state).find(({ args }) => args.includes(" --config ") && args.includes(state.namespace))?.pid;
+}
+
+async function terminateComposeChildren(state: ComposeEngineState): Promise<boolean> {
+ if (IS_WINDOWS) return true;
+ const groups = [...new Set(composeChildProcesses(state).map((child) => child.pgid).filter((pgid) => pgid !== state.composePid))];
+ let stopped = true;
+ for (const pgid of groups) {
+ try { process.kill(-pgid, "SIGTERM"); } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== "ESRCH") stopped = false;
+ continue;
+ }
+ const deadline = Date.now() + 5_000;
+ while (Date.now() < deadline) {
+ try { process.kill(-pgid, 0); } catch { break; }
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ }
+ try { process.kill(-pgid, 0); process.kill(-pgid, "SIGKILL"); } catch {}
+ }
+ for (const pid of composeChildPids(state)) {
+ if (pidAlive(pid) && !(await signalAndWait(pid, "SIGTERM", 1000))) stopped = false;
+ }
+ return stopped;
+}
+
+async function startIiiBin(iiiBin: string): Promise<boolean> {
+ const workerBinDir = process.env["AGENTMEMORY_WORKER_BIN_DIR"]?.trim() || undefined;
+ if (workerBinDir && (!existsSync(resolve(process.cwd(), workerBinDir)) ||
+ !["state", "http"].every((name) => existsSync(join(resolve(process.cwd(), workerBinDir), name))))) {
+ throw new Error(`AGENTMEMORY_WORKER_BIN_DIR must contain executable state and http binaries: ${workerBinDir}`);
+ }
+ const envPath = process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
+ const namespace = composeNamespace(getRestPort());
+ const projectRoot = resolve(__dirname, "..");
+ const ports = { restPort: getRestPort(), viewerPort: getConfiguredViewerPort(), enginePort: getEnginePort() };
+ // Fast, actionable diagnosis before Compose attempts to bind its managed listeners.
+ // Only reachable local TCP listeners count; failures to connect mean free/closed.
+ await assertComposePortsFree([ports.restPort, ports.viewerPort, ports.enginePort]);
+ const compose = startComposeDaemon({
+ ports,
+ dataDir: dataDirResolution.dataDir,
+ projectRoot,
+ nodeBin: process.execPath,
+ homeDir: homedir(),
+ ...(existsSync(envPath) ? { envFile: envPath } : {}),
+ ...(workerBinDir ? { workerBinDir } : {}),
+ cwd: process.cwd(),
+ stateBackend: { kind: getStateBackend() },
+ ...(getStateBackend() === "redis" && getRedisUrl() ? { redisUrl: getRedisUrl() } : {}),
+ workerEnvironment: process.env,
+ disableRestartPolicy: process.env["AGENTMEMORY_DISABLE_COMPOSE_RESTART"] === "1",
+ startupTimeoutMs: startupTimeouts().workerMs,
+ linux: process.platform === "linux",
+ stateDir: join(dataDirResolution.dataDir, "compose-state"),
+ logFile: join(homedir(), ".agentmemory", `compose-${getRestPort()}.log`),
+ iiiBin,
+ env: process.env,
+ });
+ spawnedComposeDaemon = compose.child;
+ composeStartupCompleted = false;
+ if (typeof compose.child.pid !== "number") throw new Error("Failed to spawn the iii Compose daemon.");
+ const state = {
+ kind: "compose" as const,
+ restPort: getRestPort(),
+ viewerPort: getConfiguredViewerPort(),
+ enginePort: getEnginePort(),
+ engineUrl: `ws://127.0.0.1:${getEnginePort()}`,
+ namespace,
+ file: compose.file,
+ stateDir: compose.stateDir,
+ logFile: compose.logFile,
+ logStartOffset: compose.logStartOffset,
+ binPath: iiiBin,
+ composePid: compose.child.pid,
+ ...(workerBinDir ? { workerBinDir: resolve(process.cwd(), workerBinDir) } : {}),
+ };
+ writeComposeState(engineStatePath(), {
+ ...state,
+ workerVersions: workerBinDir ? { local: true } : COMPOSE_WORKER_VERSIONS,
+ });
+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
+ compose.child.on("error", (error) => {
+ if (spawnedComposeDaemon === compose.child) {
+ startupFailure = { kind: "engine-crashed", stderr: redactCredentialUrls(error.message), binary: iiiBin };
+ }
+ });
+ compose.child.on("exit", (code, signal) => {
+ if (spawnedComposeDaemon === compose.child && !composeStartupCompleted && (code !== 0 || signal !== null)) {
+ startupFailure = {
+ kind: "engine-crashed",
+ stderr: signal ? `Compose exited from ${signal}` : `Compose exited with code ${code}`,
+ binary: iiiBin,
+ };
}
- vlog(`runtime config generation failed, using bundled config verbatim: ${String(err)}`);
- return { configPath, cwd };
- }
-}
-
-function startIiiBin(iiiBin: string, configPath: string): boolean {
- const s = p.spinner();
- s.start(`Starting iii-engine: ${iiiBin}`);
- const launch = prepareEngineLaunch(configPath);
- writeEngineState({
- kind: "native",
- configPath: launch.configPath,
- cwd: launch.cwd,
- binPath: iiiBin,
});
- spawnEngineBackground(
- iiiBin,
- ["--config", launch.configPath, "--no-update-check"],
- "iii-engine",
- launch.cwd,
- );
- s.stop(c.ok("iii-engine process started"));
+ const s = p.spinner();
+ s.start(`Starting iii Worker Compose: ${iiiBin}`);
+ s.stop(c.ok(`Compose daemon started (pid ${compose.child.pid})`));
return true;
}
@@ -1745,15 +1279,6 @@ function pickCompatibleIii(candidates: Array<string | null | undefined>): string
return null;
}
-function warnIfDockerIgnoresStateBackend(stateBackendKind: "file" | "redis"): void {
- if (stateBackendKind !== "redis") return;
- p.log.warn(
- "AGENTMEMORY_STATE_BACKEND=redis is not applied on the Docker path: docker-compose.yml mounts iii-config.docker.yaml read-only, so this start will not render it. " +
- "Edit iii-config.docker.yaml by hand to point iii-state/iii-stream at redis (see README \"Storage backend\"), or it keeps using the file store. " +
- "docker-compose.yml passes AGENTMEMORY_REDIS_URL into the engine container, so redis_url: '${AGENTMEMORY_REDIS_URL}' works in that file.",
- );
-}
-
async function startEngine(): Promise<boolean> {
startupFailure = null;
engineReadinessDeadline = null;
@@ -1771,46 +1296,28 @@ async function startEngine(): Promise<boolean> {
);
process.exit(1);
}
- await assertRuntimePortOwnership();
const persistedState = readEngineState();
if (persistedState?.kind === "docker") {
- warnIfDockerIgnoresStateBackend(stateBackendKind);
- const inspection = inspectOwnedDockerEngine(persistedState);
- if (inspection.status === "unavailable" || inspection.status === "missing") {
- const detail = inspection.status === "unavailable"
- ? inspection.reason
- : "container is missing";
- p.log.error(
- `A saved Docker engine owns this lifecycle state, but it cannot be resumed safely (${detail}). Run \`agentmemory stop\` to reconcile that project before starting another engine.`,
- );
- return false;
+ p.log.error(legacyDockerStateMessage(persistedState));
+ return false;
+ }
+ await assertRuntimePortOwnership();
+ if (persistedState?.kind === "compose") {
+ if (await isEngineRunning()) {
+ p.log.error("The managed Worker Compose engine is already running; it should have been reconciled before attempting a fresh start.");
+ process.exit(1);
+ }
+ if (persistedState.restPort === getRestPort()) {
+ if (persistedState.composePid && pidAlive(persistedState.composePid)) {
+ p.log.error(`Worker Compose daemon ${persistedState.composePid} is still alive. Stop it before retrying.`);
+ process.exit(1);
+ }
+ clearEngineState();
}
- persistDockerInspection(persistedState, inspection);
- if (inspection.status === "running") return true;
- const dockerBin = whichBinary("docker");
- if (!dockerBin) return false;
- startedDockerEngine = persistDockerInspection(persistedState, inspection);
- engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
- return runCommand(dockerBin, ["start", inspection.containerId], {
- label: `Restarting owned Docker container ${inspection.containerId}`,
- timeoutMs: startupTimeouts().engineMs,
- });
}
- const configPath = findIiiConfig();
warnIfRelocatedDataDir();
const pathIii = whichBinary("iii");
- vlog(`iii binary: ${pathIii ?? "(not on PATH)"}, config: ${configPath || "(not found)"}`);
-
- const dockerBin = whichBinary("docker");
- const dockerComposeCandidates = [
- join(__dirname, "..", "docker-compose.yml"),
- join(__dirname, "docker-compose.yml"),
- join(process.cwd(), "docker-compose.yml"),
- ];
- const composeFile = dockerComposeCandidates.find((c) => existsSync(c));
- const dockerOptIn =
- process.env["AGENTMEMORY_USE_DOCKER"] === "1" ||
- process.env["AGENTMEMORY_USE_DOCKER"] === "true";
+ vlog(`iii binary: ${pathIii ?? "(not on PATH)"}`);
const fallbacks = fallbackIiiPaths().filter((p) => existsSync(p));
for (const f of fallbacks) {
@@ -1820,12 +1327,12 @@ async function startEngine(): Promise<boolean> {
let iiiBin = pickCompatibleIii([pathIii, ...fallbacks]);
- if (iiiBin && configPath && !(dockerOptIn && dockerBin && composeFile)) {
+ if (iiiBin) {
if (iiiBin !== pathIii) {
p.log.info(`Using iii at: ${c.dim(iiiBin)} (v${c.accent(IIPINNED_VERSION)})`);
process.env["PATH"] = `${dirname(iiiBin)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;
}
- return startIiiBin(iiiBin, configPath);
+ return startIiiBin(iiiBin);
}
if (pathIii && !iiiBin) {
@@ -1836,17 +1343,10 @@ async function startEngine(): Promise<boolean> {
);
}
- if (!configPath) {
- startupFailure = { kind: "no-engine" };
- return false;
- }
-
- vlog(`docker binary: ${dockerBin ?? "(not on PATH)"}`);
mkdirSync(dataDirResolution.dataDir, { recursive: true });
- vlog(`docker-compose.yml: ${composeFile ?? "(not found)"}`);
const interactive = !!process.stdin.isTTY && !process.env["CI"];
- type Choice = "install" | "docker" | "manual";
+ type Choice = "install" | "manual";
let choice: Choice;
// Wrong-version iii on PATH is a configuration trap: any prompt would
@@ -1854,9 +1354,7 @@ async function startEngine(): Promise<boolean> {
// prompt and auto-install pinned engine to the private location.
const pathIiiMismatch = pathIii !== null && resolveCompatibleIii(pathIii) === null;
- if (dockerOptIn && dockerBin && composeFile) {
- choice = "docker";
- } else if (pathIiiMismatch) {
+ if (pathIiiMismatch) {
choice = "install";
const detected = iiiBinVersion(pathIii!);
p.log.info(
@@ -1875,9 +1373,6 @@ async function startEngine(): Promise<boolean> {
hint: "recommended",
},
];
- if (dockerBin && composeFile) {
- options.push({ value: "docker", label: "Use Docker compose", hint: "advanced" });
- }
options.push({ value: "manual", label: "Show manual install steps and exit" });
const picked = await p.select<Choice>({
@@ -1902,67 +1397,31 @@ async function startEngine(): Promise<boolean> {
if (result.ok && result.binPath) {
process.env["PATH"] = `${dirname(result.binPath)}${PATH_DELIMITER}${process.env["PATH"] ?? ""}`;
iiiBin = result.binPath;
- return startIiiBin(iiiBin, configPath);
- }
- if (dockerBin && composeFile && interactive) {
- const fallback = await p.confirm({
- message: "Auto-install failed. Try Docker compose instead?",
- initialValue: true,
- });
- if (p.isCancel(fallback) || fallback !== true) {
- startupFailure = { kind: "no-engine" };
- return false;
- }
- choice = "docker";
- } else {
- startupFailure = { kind: "no-engine" };
- return false;
- }
- }
-
- if (choice === "docker" && dockerBin && composeFile) {
- warnIfDockerIgnoresStateBackend(stateBackendKind);
- const s = p.spinner();
- s.start("Starting iii-engine via Docker...");
- configureDockerHostUser();
- const projectName = dockerProjectName(getRestPort());
- const dockerState: DockerEngineState = {
- kind: "docker",
- schemaVersion: 2,
- composeFile,
- projectName,
- engineVersion: IIPINNED_VERSION,
- dataMountType: "bind",
- dataMountSource: dataDirResolution.dataDir,
- preserveContainer: false,
- };
- const previous = inspectOwnedDockerEngine(dockerState);
- if (previous.status === "missing" || previous.status === "stopped") {
- startedDockerEngine = previous.status === "stopped"
- ? persistDockerInspection(dockerState, previous)
- : dockerState;
+ return startIiiBin(iiiBin);
}
- writeEngineState(dockerState);
- spawnEngineBackground(
- dockerBin,
- dockerComposeArgs(composeFile, projectName, ["up", "-d"]),
- "iii-engine via Docker",
- );
- s.stop("Docker compose started");
- return true;
- }
-
- if (!composeFile && dockerBin) {
- startupFailure = { kind: "no-docker-compose" };
- } else {
startupFailure = { kind: "no-engine" };
+ return false;
}
+
+ startupFailure = { kind: "no-engine" };
return false;
}
async function waitForEngine(timeoutMs = startupTimeouts().engineMs): Promise<boolean> {
- return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), (signal) => probeEngine(getBaseUrl(), signal), {
- intervalMs: 500,
+ const state = readEngineState();
+ // A composed engine's websocket port is internal control-plane detail and
+ // may be unavailable while its HTTP workers are still binding. The owned
+ // loopback REST listener is the readiness contract consumed by the CLI and
+ // does not depend on AGENTMEMORY_URL (which is for client commands only).
+ const endpoint = state?.kind === "compose"
+ ? managedComposeReadinessUrl(state.restPort)
+ : getBaseUrl();
+ const probe = state?.kind === "compose"
+ ? (signal: AbortSignal) => probeEngine(endpoint, signal)
+ : (signal: AbortSignal) => probeEngine(endpoint, signal);
+ return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), probe, {
+ intervalMs: 250,
+ probeTimeoutMs: 750,
stopped: () => startupInterrupted || engineStartupFailed(),
});
}
@@ -1975,47 +1434,6 @@ async function waitForPersistedNativeEngine(): Promise<boolean> {
return true;
}
-async function reconcilePersistedDockerEngine(): Promise<boolean> {
- const state = readEngineState();
- if (state?.kind !== "docker") return false;
- const inspection = inspectOwnedDockerEngine(state);
- if (inspection.status === "unavailable") {
- p.log.error(
- `The saved Docker engine cannot be verified: ${inspection.reason}. Refusing to overwrite its lifecycle state. Run \`agentmemory stop\` after restoring Docker/compose access.`,
- );
- process.exit(1);
- }
- if (inspection.status === "missing") {
- p.log.error(
- "The saved Docker project no longer has an iii-engine container. Run `agentmemory stop` to remove its stale project state, then start agentmemory again.",
- );
- process.exit(1);
- }
- persistDockerInspection(state, inspection);
- if (inspection.status === "stopped") {
- startedDockerEngine = persistDockerInspection(state, inspection);
- engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);
- const dockerBin = whichBinary("docker");
- if (
- !dockerBin ||
- !runCommand(dockerBin, ["start", inspection.containerId], {
- label: `Restarting owned Docker container ${inspection.containerId}`,
- timeoutMs: startupTimeouts().engineMs,
- })
- ) {
- throw new Error("The owned Docker container could not be restarted; lifecycle state was preserved.");
- }
- }
- if (!(await waitForEngine())) {
- printDockerStartupLogs();
- throw new Error(`${startupTimeoutMessage("engine", startupTimeouts().engineMs)} Docker ownership state was preserved.`);
- }
- await startWorkerForEngineState();
- await maybeOfferGlobalInstall();
- printReadyHint();
- return true;
-}
-
function installInstructions(): string[] {
const releaseUrl = iiiReleaseUrl();
if (IS_WINDOWS) {
@@ -2034,9 +1452,6 @@ function installInstructions(): string[] {
" 3. Extract iii.exe to %USERPROFILE%\\.local\\bin\\iii.exe (or add to PATH)",
" 4. Re-run: npx @agentmemory/agentmemory",
"",
- ` B) Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
- " Re-run with AGENTMEMORY_USE_DOCKER=1 npx @agentmemory/agentmemory",
- "",
"Or skip the engine entirely (standalone MCP): npx @agentmemory/agentmemory mcp",
"",
"Docs: https://iii.dev/docs",
@@ -2051,9 +1466,6 @@ function installInstructions(): string[] {
linuxInstall,
" Then re-run: npx @agentmemory/agentmemory",
"",
- ` B) Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
- " Re-run with AGENTMEMORY_USE_DOCKER=1 npx @agentmemory/agentmemory",
- "",
"Or skip the engine entirely (standalone MCP): npx @agentmemory/agentmemory mcp",
"",
"Docs: https://iii.dev/docs",
@@ -2066,45 +1478,17 @@ function portInUseDiagnostic(port: number): string {
: ` lsof -i :${port} # or: ss -tlnp | grep :${port}`;
}
-
-// Derive a host string for the streams/engine WebSocket lines from
-// the configured engine URL (`III_ENGINE_URL`) or REST base
-// (`AGENTMEMORY_URL`) so a remote-bind setup like
-// `III_ENGINE_URL=ws://my-host:49134` doesn't print misleading
-// localhost addresses. Falls back to localhost.
-function getEngineHost(): string {
- const envKeys = shouldUseAgentmemoryUrl()
- ? ["III_ENGINE_URL", "AGENTMEMORY_URL"]
- : ["III_ENGINE_URL"];
- for (const envKey of envKeys) {
- const raw = process.env[envKey];
- if (!raw) continue;
- try {
- const parsed = new URL(raw);
- if (parsed.hostname) return parsed.hostname;
- } catch {}
- }
- return "localhost";
-}
-
function printReadyHint(): void {
const restUrl = getBaseUrl();
const viewerUrl = getViewerUrl();
- const engineHost = getEngineHost();
- const streamUrl = `ws://${engineHost}:${getStreamPort()}`;
- const engineUrl = `ws://${engineHost}:${getEnginePort()}`;
+ const engineUrl = process.env["III_ENGINE_URL"] || `ws://localhost:${getEnginePort()}`;
const invocation = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
- const consolePort = defaultConsolePort(getConfiguredViewerPort());
const portFlags = portFlagSuffix(getRestPort(), selectedInstance);
- const consoleLine = `${c.label("iii console")} ${c.cmd(`${invocation} console${portFlags}`)} ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;
-
const lines = [
`${c.label("REST API")} ${c.url(restUrl)}`,
`${c.label("Viewer")} ${c.url(viewerUrl)}`,
- `${c.label("Streams")} ${c.url(streamUrl)}`,
`${c.label("Engine")} ${c.url(engineUrl)}`,
- consoleLine,
];
// p.note renders a bordered panel with a title — same affordance
// used elsewhere in this CLI for "Troubleshooting" / "Setup
@@ -2120,6 +1504,41 @@ function printReadyHint(): void {
process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);
}
+async function reconcilePersistedComposeEngine(): Promise<boolean> {
+ const state = readEngineState();
+ if (state?.kind !== "compose") return false;
+ if (!(await isEngineRunning())) {
+ if (state.composePid && pidAlive(state.composePid)) {
+ p.log.error(`Worker Compose daemon ${state.composePid} is alive but REST ${state.restPort} is not ready. Inspect ${state.logFile}; use agentmemory stop to reconcile.`);
+ process.exit(1);
+ }
+ if (await isEngineRunning()) {
+ p.log.error(`An engine is responding on :${state.restPort}, but the recorded Compose daemon is gone. Refusing to adopt or clear this endpoint automatically.`);
+ process.exit(1);
+ }
+ clearEngineState();
+ p.log.info("Found stale Worker Compose lifecycle state; starting a fresh managed instance.");
+ return false;
+ }
+ const version = iiiBinVersion(state.binPath);
+ if (state.composePid && !composePidMatches(state.composePid, state)) {
+ p.log.error(`Compose metadata points to PID ${state.composePid}, but its process identity does not match the saved engine/file/namespace.`);
+ process.exit(1);
+ }
+ if (version !== IIPINNED_VERSION) {
+ p.log.error(`Managed Compose engine is ${version ?? "unverified"}; expected ${IIPINNED_VERSION}. Run agentmemory stop before changing the runtime.`);
+ process.exit(1);
+ }
+ try {
+ const status = await composeCall<ComposeStatus>({ engineUrl: state.engineUrl, namespace: state.namespace, functionId: "compose::status", file: state.file });
+ if (!ownedComposeProject(status, state.file)) throw new Error("Compose daemon does not report the owned worker-compose.yaml project.");
+ } catch (err) {
+ p.log.error(`Could not verify the managed Compose project: ${err instanceof Error ? err.message : String(err)}. See ${state.logFile}.`);
+ process.exit(1);
+ }
+ return true;
+}
+
async function main() {
startupTimeouts();
await assertRuntimePortOwnership();
@@ -2133,7 +1552,7 @@ async function main() {
const probe = await fetch(`${getBaseUrl()}/agentmemory/livez`, {
signal: AbortSignal.timeout(1500),
});
- if (probe.ok) {
+ if (probe.ok && readEngineState()?.kind !== "compose") {
p.log.error(
`agentmemory is already running on port ${getRestPort()}. Starting a second instance here would corrupt the running daemon's REST routing. Use the REST API (or the MCP tools) against the running instance, run a different --instance, or stop it first with \`agentmemory stop\`.`,
);
@@ -2143,6 +1562,13 @@ async function main() {
// no live daemon on this port; boot normally
}
+ const legacyState = readEngineState();
+ if (legacyState?.kind === "docker") {
+ p.intro("agentmemory");
+ p.log.error(legacyDockerStateMessage(legacyState));
+ process.exit(1);
+ }
+
// `--reset` wipes preferences before anything else so the onboarding
// flow below always runs fresh.
if (IS_RESET) {
@@ -2173,7 +1599,12 @@ async function main() {
return;
}
- if (await reconcilePersistedDockerEngine()) return;
+ if (await reconcilePersistedComposeEngine()) {
+ await startWorkerForEngineState();
+ await maybeOfferGlobalInstall();
+ printReadyHint();
+ return;
+ }
if (await isEngineRunning() || await waitForPersistedNativeEngine()) {
if (IS_VERBOSE) p.log.success("iii-engine is running");
@@ -2191,7 +1622,7 @@ async function main() {
whichBinary("iii") ??
fallbackIiiPaths().find((p) => existsSync(p)) ??
null;
- const detected = attachedBin ? iiiBinVersion(attachedBin) : null;
+ const detected = persisted?.kind === "compose" ? iiiBinVersion(persisted.binPath) : attachedBin ? iiiBinVersion(attachedBin) : null;
// Fail closed: only adopt the running engine when we can positively
// confirm it is the pinned version. An unknown version (detected === null,
@@ -2200,11 +1631,8 @@ async function main() {
// WebSocket reconnect loop. Worst case here is a re-run that reinstalls
// the pinned engine, never a silent loop.
if (detected === IIPINNED_VERSION) {
- adoptRunningEngine();
- await startWorkerForEngineState();
- await maybeOfferGlobalInstall();
- printReadyHint();
- return;
+ p.log.error(`An unmanaged iii engine is already listening on ${getEnginePort()}. Agentmemory will not attach to it; stop that engine explicitly or select another --instance/--port.`);
+ process.exit(1);
}
const detectedLabel = detected ? `v${detected}` : "an unverified version";
@@ -2246,13 +1674,6 @@ async function main() {
if (!started) {
p.log.error("Could not start iii-engine.");
const lines = installInstructions();
- if (startupFailure?.kind === "no-docker-compose") {
- lines.unshift(
- "Docker is installed but docker-compose.yml is missing from this",
- "install. Re-install with: npm install -g @agentmemory/agentmemory",
- "",
- );
- }
p.note(lines.join("\n"), "Setup required");
throw new Error("iii-engine could not be started.");
}
@@ -2261,12 +1682,37 @@ async function main() {
s.start("Waiting for iii-engine to be ready...");
const ready = await waitForEngine();
+ if (ready) {
+ const composeState = readEngineState();
+ if (composeState?.kind === "compose") {
+ composeState.enginePid = composeEnginePid(composeState);
+ writeComposeState(engineStatePath(), { ...composeState, workerVersions: composeState.workerVersions ?? COMPOSE_WORKER_VERSIONS });
+ }
+ }
if (!ready) {
const port = getRestPort();
- s.stop(startupTimeoutMessage("engine", startupTimeouts().engineMs));
- printDockerStartupLogs();
-
- if (startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed") {
+ let composeState = readEngineState();
+ let composeLog = composeState?.kind === "compose" ? readComposeStartupLogs() : null;
+ if (composeState?.kind === "compose" && spawnedComposeDaemon?.exitCode !== null) {
+ await new Promise((resolve) => setTimeout(resolve, 150));
+ composeLog = readComposeStartupLogs() ?? composeLog;
+ }
+ let registryFailure: string | null = null;
+ if (composeState?.kind === "compose") {
+ const stateFailure = composeState.workerFailure ?? composeStateRegistryFailure(dataDirResolution.dataDir, composeState.file);
+ const logFailure = composeLog ? composeRegistryFailureMessage(composeLog.text, composeState.workerBinDir) : null;
+ if (stateFailure) registryFailure = `Worker registry unavailable while resolving state/http; retry later or set AGENTMEMORY_WORKER_BIN_DIR. Compose reported: ${stateFailure}`;
+ else registryFailure = logFailure;
+ }
+ const composeLogTail = composeLog?.text.trim().split(/\r?\n/).slice(-12).join("\n");
+ const shortFailure = registryFailure || startupFailure?.stderr ||
+ (composeState?.kind === "compose" && composeLogTail
+ ? `Worker Compose startup failed. Recent Compose output:\n${composeLogTail}`
+ : startupTimeoutMessage("engine", startupTimeouts().engineMs));
+ s.stop(shortFailure);
+ printComposeStartupLogs();
+
+ if (startupFailure?.kind === "engine-crashed") {
p.log.error("The iii-engine process crashed on startup.");
if (startupFailure.binary) {
p.log.info(`Binary: ${startupFailure.binary}`);
@@ -2281,7 +1727,6 @@ async function main() {
"Common causes:",
` - iii-engine version mismatch — reinstall the pinned v${IIPINNED_VERSION} binary`,
" (sh script on macOS/Linux, GitHub release zip on Windows)",
- " - Docker Desktop not running (if you're using the Docker path)",
" - Port already in use (see below)",
"",
"See https://iii.dev/docs for current install instructions.",
@@ -2304,16 +1749,29 @@ async function main() {
"Troubleshooting",
);
}
- throw new Error(engineStartupFailed() ? "iii-engine failed during startup." : startupTimeoutMessage("engine", startupTimeouts().engineMs));
+ if (composeLog?.text) p.log.error(`Compose log: ${composeLog.path}`);
+ throw new Error(shortFailure);
}
s.stop(c.ok("iii-engine is ready"));
await startWorkerForEngineState();
+ const managedCompose = readEngineState();
+ if (managedCompose?.kind === "compose" && !managedCompose.enginePid) {
+ managedCompose.enginePid = composeChildPids(managedCompose)[0];
+ writeComposeState(engineStatePath(), { ...managedCompose, workerVersions: managedCompose.workerVersions ?? COMPOSE_WORKER_VERSIONS });
+ }
await maybeOfferGlobalInstall();
printReadyHint();
// Mark splash as something to skip on subsequent runs. This is a
// no-op if onboarding already flipped the flag (idempotent merge).
writePrefs({ skipSplash: true });
+ // Worker Compose owns the service lifecycle independently of this startup
+ // launcher. Do not leave readiness-probe keep-alive sockets referenced after
+ // printing the ready hint; the daemon and its worker remain detached.
+ if (managedCompose?.kind === "compose") {
+ await new Promise<void>((resolve) => process.stdout.write("", () => resolve()));
+ process.exit(0);
+ }
}
async function apiFetch<T = unknown>(base: string, path: string, timeoutMs = 5000): Promise<T | null> {
@@ -2330,12 +1788,38 @@ async function apiFetch<T = unknown>(base: string, path: string, timeoutMs = 500
}
async function runStatus() {
- const port = getRestPort();
const base = getBaseUrl();
p.intro("agentmemory status");
+ const state = readEngineState();
+ const savedState = !(shouldUseAgentmemoryUrl() && process.env["AGENTMEMORY_URL"])
+ && (state?.kind !== "compose" || state.restPort === getRestPort()) ? state : null;
+ if (savedState?.kind === "docker") {
+ p.log.warn(legacyDockerStateMessage(savedState));
+ }
const up = await isEngineRunning();
if (!up) {
+ if (savedState?.kind === "compose" && savedState.composePid && pidAlive(savedState.composePid)) {
+ try {
+ const composeStatus = await composeCall<ComposeStatus>({
+ engineUrl: savedState.engineUrl,
+ namespace: savedState.namespace,
+ functionId: "compose::status",
+ file: savedState.file,
+ });
+ const project = ownedComposeProject(composeStatus, savedState.file);
+ const failure = composeWorkerFailureSummary(project);
+ if (failure) {
+ p.log.error(`Worker Compose failed after exhausting restart attempts; REST is unavailable at ${base}.`);
+ p.log.error(failure);
+ p.log.info(`Inspect ${savedState.logFile}, then run agentmemory stop before retrying.`);
+ process.exit(1);
+ }
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ p.log.warn(`Worker Compose status unavailable: ${message}`);
+ }
+ }
p.log.error(`Not running — no response at ${base}`);
p.log.info("Start with: npx @agentmemory/agentmemory");
process.exit(1);
@@ -2419,6 +1903,19 @@ async function runStatus() {
);
}
+ const managed = savedState;
+ if (managed?.kind === "compose") {
+ try {
+ const composeStatus = await composeCall<ComposeStatus>({ engineUrl: managed.engineUrl, namespace: managed.namespace, functionId: "compose::status", file: managed.file });
+ const composeProject = ownedComposeProject(composeStatus, managed.file);
+ const containers = composeProject?.containers ?? [];
+ const failed = composeWorkerFailureSummary(composeProject ?? null);
+ if (failed) lines.push("", "Worker Compose failure (restart attempts exhausted):", ...failed.split("\n").map((line) => ` ${line}`));
+ lines.push("", "Compose workers:", ...containers.map((container) => ` ${container.container ?? "?"}: ${container.state ?? "unknown"}${container.last_error ? ` — ${container.last_error}` : ""}`));
+ } catch (error) {
+ lines.push("", `Compose status unavailable: ${error instanceof Error ? error.message : String(error)}`);
+ }
+ }
p.note(lines.join("\n"), "agentmemory");
} catch (err) {
p.log.error(err instanceof Error ? err.message : String(err));
@@ -2498,7 +1995,7 @@ function buildDoctorContext(): DoctorContext {
baseUrl: getBaseUrl(),
viewerUrl: getViewerUrl(),
envPath: join(homedir(), ".agentmemory", ".env"),
- pidfilePath: enginePidfilePath(),
+ pidfilePath: readEngineState()?.kind === "compose" ? engineStatePath() : enginePidfilePath(),
enginePath: engineStatePath(),
pinnedVersion: IIPINNED_VERSION,
};
@@ -2516,14 +2013,26 @@ function buildDoctorEffects(): DoctorEffects {
return {};
}
},
- pidfileExists: () => existsSync(enginePidfilePath()),
+ pidfileExists: () => {
+ const state = readEngineState();
+ return state?.kind === "compose" ? Boolean(state.composePid) : existsSync(enginePidfilePath());
+ },
pidfilePidIsAlive: () => {
+ const state = readEngineState();
+ if (state?.kind === "compose") return state.composePid ? pidAlive(state.composePid) : null;
const pid = readEnginePidfile();
if (pid === null) return null;
return pidAlive(pid);
},
- findIiiBinary: () => whichBinary("iii"),
- localBinIiiPath: () => privateIiiPath(),
+ findIiiBinary: () => {
+ const state = readEngineState();
+ if (state?.kind === "compose") return existsSync(state.binPath) ? state.binPath : null;
+ return whichBinary("iii");
+ },
+ localBinIiiPath: () => {
+ const state = readEngineState();
+ return state?.kind === "compose" ? state.binPath : privateIiiPath();
+ },
iiiBinaryVersion: (binPath: string) => iiiBinVersion(binPath),
viewerReachable: async (timeoutMs = 2000) => {
try {
@@ -2585,6 +2094,10 @@ function buildDoctorEffects(): DoctorEffects {
runStop: async () => {
try {
startupTimeouts();
+ if (readEngineState()?.kind === "compose") {
+ await runStop();
+ return { ok: true, message: "Worker Compose project stopped." };
+ }
// runStop calls process.exit on its own — guard against that here
// by short-circuiting when there's nothing to stop.
const port = getRestPort();
@@ -3143,7 +2656,6 @@ async function startServerForDemo(): Promise<() => Promise<void>> {
}
if (!(await waitForEngine())) {
printCapturedStartupStderr();
- printDockerStartupLogs();
throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));
}
}
@@ -3294,7 +2806,6 @@ async function runUpgrade() {
const pnpmBin = whichBinary("pnpm");
const npmBin = whichBinary("npm");
- const dockerBin = whichBinary("docker");
p.log.info(`Working directory: ${cwd}`);
const requireSuccess = (ok: boolean, label: string): void => {
@@ -3361,15 +2872,6 @@ async function runUpgrade() {
p.log.info("Skipped iii-engine installer.");
}
- if (dockerBin) {
- runCommand(dockerBin, ["pull", `iiidev/iii:${IIPINNED_VERSION}`], {
- label: `Pulling iii Docker image v${IIPINNED_VERSION} (pinned)`,
- optional: true,
- });
- } else {
- p.log.info("Docker not found. Skipping Docker image refresh.");
- }
-
p.note(
[
"Upgrade flow completed.",
@@ -3443,9 +2945,15 @@ async function waitForEngineFlush(): Promise<void> {
try {
stateBackend = getStateBackend();
} catch {}
+ const composeState = readEngineState();
+ if (composeState?.kind === "compose") {
+ const isolatedRuntime = dataDirResolution.dataDir !== join(homedir(), ".agentmemory");
+ await new Promise((resolve) => setTimeout(resolve, getStateBackend() === "redis" || isolatedRuntime ? 0 : 3500));
+ return;
+ }
const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
const configTexts: string[] = [];
- for (const path of engineStateConfigPaths(join(homedir(), ".agentmemory"), runtimePath)) {
+ for (const path of engineStateConfigPaths(dataDirResolution.dataDir, runtimePath)) {
try {
configTexts.push(readFileSync(path, "utf-8"));
} catch {}
@@ -3530,10 +3038,10 @@ function pidCommand(pid: number): string {
}
// Positive identity beats a denylist: the engine is always the `iii`
-// binary (spawned from PATH or ~/.agentmemory/bin), so anything else
-// holding the port — Docker's proxy, an ssh forward, a stray dev
-// server — must not be adopted or signaled. A denylist of known VM
-// stacks failed open for every name it didn't know.
+// binary (spawned from PATH or ~/.agentmemory/bin), so any other process
+// holding the port — an SSH forward or a stray dev server, for example —
+// must not be adopted or signaled. A denylist failed open for every name
+// it did not know.
function isForeignPortHolder(comm: string): boolean {
if (!comm) return false;
const base = comm.split("/").pop() || comm;
@@ -3565,112 +3073,18 @@ function findEnginePidsByPort(port: number): number[] {
}
}
-async function stopDockerEngine(
- state: DockerEngineState,
- port: number,
- suppressOutro = false,
-): Promise<void> {
- const dockerBin = whichBinary("docker");
- if (!dockerBin) {
- p.log.error(
- "Engine was started via Docker, but `docker` is no longer on PATH. Lifecycle state was preserved.",
- );
- process.exit(1);
- }
-
- const inspection = inspectOwnedDockerEngine(state);
- if (inspection.status === "unavailable") {
- p.log.error(
- `The saved Docker engine cannot be verified: ${inspection.reason}. Refusing to stop or clear ownership state.`,
- );
- process.exit(1);
- }
- const resolvedState = persistDockerInspection(state, inspection);
-
- const workerPid = readWorkerPidfile();
- if (workerPid && !(await stopWorkerPid(workerPid, 5000))) {
- p.log.error("The agentmemory worker could not be stopped; Docker ownership state was preserved.");
- process.exit(1);
- }
- clearWorkerPidfile();
-
- if (inspection.status === "running" || inspection.status === "stopped") {
- if (
- inspection.status === "running" &&
- !runCommand(
- dockerBin,
- ["stop", "--time", "10", inspection.containerId],
- { label: `Stopping preserved Docker container ${inspection.containerId}` },
- )
- ) {
- p.log.error("The Docker container could not be stopped; ownership state was preserved.");
- process.exit(1);
- }
- clearEnginePidfile();
- writeEngineState(resolvedState);
- if (!suppressOutro) {
- p.outro(
- "Stopped. The validated Docker container and data mount were preserved for a lossless restart.",
- );
- }
- return;
- }
-
- const projectName = inspection.projectName ?? resolvedState.projectName;
- if (!projectName) {
- p.log.error("No verified Docker Compose project name is available. Refusing an unscoped stop.");
- process.exit(1);
- }
- const effectiveComposeFile = existsSync(inspection.composeFile)
- ? inspection.composeFile
- : discoverComposeFile();
- if (!effectiveComposeFile) {
- p.log.error("No agentmemory compose file is available. Docker ownership state was preserved.");
- process.exit(1);
- }
- const composeText = readFileSync(effectiveComposeFile, "utf-8");
- const ownServices = ["iii-engine", "iii-init"].filter((service) =>
- new RegExp(`^\\s+${service}:`, "m").test(composeText),
- );
- if (ownServices.length === 0) {
- p.log.error(`${effectiveComposeFile} does not define iii-engine or iii-init. Refusing an unscoped stop.`);
+async function runStop(): Promise<void> {
+ const savedState = readEngineState();
+ if (savedState?.kind === "docker") {
+ p.intro("agentmemory stop");
+ p.log.error(legacyDockerStateMessage(savedState));
process.exit(1);
}
-
- const composeCommand = [
- "docker",
- ...dockerComposeArgs(effectiveComposeFile, projectName, []),
- ].join(" ");
-
- const ok = runCommand(
- dockerBin,
- dockerComposeArgs(effectiveComposeFile, projectName, [
- "rm",
- "-s",
- "-f",
- ...ownServices,
- ]),
- {
- label: `${composeCommand} rm -s -f ${ownServices.join(" ")}`,
- },
- );
- // Clear each piece of state only after its shutdown succeeded, so a
- // failed stop stays retryable.
- if (ok) {
- clearEnginePidfile();
- clearEngineState();
- } else {
- p.log.error(
- `docker compose rm failed. The engine may still be running on :${port}. Inspect with:\n ${composeCommand} ps`,
- );
+ if (savedState?.kind === "compose" && engineStateRestPort(savedState) !== getRestPort()) {
+ p.intro("agentmemory stop");
+ p.log.error(`Saved Compose lifecycle state belongs to REST port ${engineStateRestPort(savedState)}, not requested port ${getRestPort()}. Refusing to signal processes or clear metadata.`);
process.exit(1);
}
- if (!suppressOutro) {
- p.outro("Stopped. Memories persisted to disk; restart anytime with: npx @agentmemory/agentmemory");
- }
-}
-
-async function runStop(): Promise<void> {
await assertRuntimePortOwnership();
p.intro("agentmemory stop");
const port = getRestPort();
@@ -3678,11 +3092,43 @@ async function runStop(): Promise<void> {
const running = await isEngineRunning();
const force = args.includes("--force");
- if (state?.kind === "docker") {
- if (!running) {
- p.log.info(`No engine responding on port ${port}.`);
+ if (state?.kind === "compose") {
+ const ownedDaemonAlive = Boolean(state.composePid && pidAlive(state.composePid));
+ if (ownedDaemonAlive && !composePidMatches(state.composePid!, state)) {
+ p.log.error(`Recorded Compose pid ${state.composePid} does not match the saved daemon identity; refusing to invoke Compose control or signal it. Lifecycle state was preserved.`);
+ process.exit(1);
+ }
+ if (running && !ownedDaemonAlive) {
+ p.log.error("The REST endpoint is responding, but the recorded Compose daemon is not alive. Refusing to stop or clear an engine that may be unrelated; restore the owning daemon or inspect the endpoint manually.");
+ process.exit(1);
+ }
+ if (running && ownedDaemonAlive) {
+ try {
+ await composeCall({ engineUrl: state.engineUrl, namespace: state.namespace, functionId: "compose::down", file: state.file, timeoutMs: 60_000 });
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ if (!message.includes("ENGINE_RESTART_REQUIRED")) {
+ p.log.error(`compose::down failed for ${state.file}: ${message}. Lifecycle state was preserved.`);
+ process.exit(1);
+ }
+ p.log.warn("Compose requested an engine restart while stopping; terminating its verified owning daemon to finish shutdown.");
+ }
+ }
+ if (ownedDaemonAlive) {
+ const childrenStopped = await terminateComposeChildren(state);
+ if (!childrenStopped) {
+ p.log.error(`One or more child workers of Compose ${state.composePid} did not stop; lifecycle state was preserved.`);
+ process.exit(1);
+ }
+ if (!(await signalAndWait(state.composePid!, "SIGTERM", 20_000))) {
+ p.log.error(`Worker Compose daemon pid ${state.composePid} did not stop; lifecycle state was preserved. Inspect ${state.logFile}.`);
+ process.exit(1);
+ }
}
- await stopDockerEngine(state, port);
+ clearEnginePidfile();
+ clearWorkerPidfile();
+ clearEngineState();
+ p.outro("Stopped Worker Compose, engine, and agentmemory workers. Data was preserved.");
return;
}
@@ -3730,22 +3176,6 @@ async function runStop(): Promise<void> {
process.exit(1);
}
- if (!state) {
- const compose = discoverComposeFile();
- if (compose && pidfilePid === null) {
- if (force) {
- p.log.warn(
- `--force: bypassing Docker-heuristic guard. Falling back to native pidfile + lsof on :${port}.`,
- );
- } else {
- p.log.error(
- `Engine is running on :${port} but no pidfile or state file is present. It may have been started via Docker compose by a different shell. Refusing to signal host PIDs.\n\nStop it with:\n docker compose -f ${compose} down\n\nOr re-run with --force to signal whatever lsof finds on :${port}, or AGENTMEMORY_USE_DOCKER=1 to record state next time.`,
- );
- process.exit(1);
- }
- }
- }
-
const candidates = new Set<number>();
if (pidfilePid) candidates.add(pidfilePid);
for (const pid of portPids) candidates.add(pid);
@@ -3782,9 +3212,8 @@ async function runStop(): Promise<void> {
const skippedForeign: Array<{ pid: number; comm: string }> = [];
for (const pid of candidates) {
if (workerCandidates.has(pid)) continue;
- // Last-line guard against a stale/poisoned pidfile or a Docker
- // port-forward holding :port — signaling com.docker.backend kills
- // Docker Desktop's whole backend.
+ // Last-line guard against a stale/poisoned pidfile or a port-forward
+ // holding :port — signaling its process could stop unrelated services.
const comm = pidCommand(pid);
if (!force && isForeignPortHolder(comm)) {
skippedForeign.push({ pid, comm });
@@ -3805,7 +3234,7 @@ async function runStop(): Promise<void> {
.map((sf) => ` pid ${sf.pid} ${sf.comm}`)
.join("\n");
p.log.error(
- `Refused to signal process(es) holding :${port} that are not the iii engine:\n${list}\n\nIf the engine runs in Docker, stop it there:\n docker compose ps && docker compose rm -s -f <service>\n\nOr re-run with --force to signal them anyway.`,
+ `Refused to signal process(es) holding :${port} that are not the iii engine:\n${list}\n\nInspect those processes and stop the engine with its owning runtime.\nOr re-run with --force to signal them anyway.`,
);
process.exit(1);
}
@@ -3828,8 +3257,8 @@ async function runConnectCmd(): Promise<void> {
async function runImportJsonl(): Promise<void> {
// Long-form flags that take a value. Their value tokens must be
// consumed alongside the flag so they don't leak into positional
- // args (e.g. `--port 3112 import-jsonl` would otherwise turn
- // 3112 into pathArg).
+ // args (e.g. `--port 3114 import-jsonl` would otherwise turn
+ // 3114 into pathArg).
const VALUE_FLAGS = new Set(["--port", "--tools", "--data-dir"]);
let maxFiles: number | undefined;
const tail = args.slice(1);
@@ -4057,25 +3486,13 @@ async function runRemove(): Promise<void> {
const force = args.includes("--force");
const keepData = args.includes("--keep-data");
const ownedState = readEngineState();
+ if (ownedState?.kind === "compose") {
+ p.log.error("Stop the Worker Compose project with `agentmemory stop` before removing agentmemory; its data and daemon ownership are preserved.");
+ process.exit(1);
+ }
if (ownedState?.kind === "docker") {
- const inspection = inspectOwnedDockerEngine(ownedState);
- if (inspection.status === "running" || inspection.status === "stopped") {
- persistDockerInspection(ownedState, inspection);
- if (!keepData) {
- p.log.error(
- `Docker-backed removal requires --keep-data so the validated ${inspection.dataMountType} data mount (${inspection.dataMountSource}) and its recovery metadata remain usable. Re-run \`agentmemory remove --keep-data\`; destructive Docker data deletion is intentionally not automated.`,
- );
- process.exit(1);
- }
- } else {
- const detail = inspection.status === "unavailable"
- ? inspection.reason
- : "the owned container is missing";
- p.log.error(
- `remove cannot safely reconcile the saved Docker ownership (${detail}). Lifecycle state was preserved for manual recovery.`,
- );
- process.exit(1);
- }
+ p.log.error(legacyDockerStateMessage(ownedState));
+ process.exit(1);
}
const home = homedir();
@@ -4085,7 +3502,6 @@ async function runRemove(): Promise<void> {
const options: RemoveOptions = {
force,
keepData,
- preserveRuntimeState: ownedState?.kind === "docker",
};
const plan = buildRemovePlan(
{
@@ -4142,11 +3558,6 @@ async function runRemove(): Promise<void> {
}
if (item.id === "stop-engine") {
- if (ownedState?.kind === "docker") {
- await stopDockerEngine(ownedState, getRestPort(), true);
- p.log.success("stopped Docker engine; container, data mount, and recovery state preserved");
- continue;
- }
const stopped = await stopNativeEngineForRemoval();
if (!stopped.ok) {
p.log.error(`Removal aborted: ${stopped.reason}.`);
@@ -4172,64 +3583,13 @@ async function runRemove(): Promise<void> {
}
async function runConsole(): Promise<void> {
- const iiiBin = pickCompatibleIii([
- whichBinary("iii"),
- ...fallbackIiiPaths().filter((candidate) => existsSync(candidate)),
- ]);
- if (!iiiBin) {
- p.log.error(
- `No iii v${IIPINNED_VERSION} found. Start agentmemory once so it installs the pinned engine into ${privateIiiPath()}, then run this again.`,
- );
- process.exit(1);
- }
- let parsed: ReturnType<typeof parseConsoleArgs>;
- try {
- parsed = parseConsoleArgs(
- args.slice(1),
- defaultConsolePort(getConfiguredViewerPort()),
- );
- } catch (err) {
- p.log.error(err instanceof Error ? err.message : String(err));
- process.exit(1);
- }
- const launch = {
- iiiBin,
- consolePort: parsed.consolePort,
- restPort: getRestPort(),
- streamPort: getStreamPort(),
- enginePort: getEnginePort(),
- extraArgs: parsed.extraArgs,
- };
- if (!(await isEngineRunning())) {
- p.log.warn(
- `No engine responding on port ${launch.restPort}. The console starts anyway and connects once agentmemory is up.`,
- );
- }
- p.log.info(
- `iii console: http://127.0.0.1:${launch.consolePort} (engine REST ${launch.restPort}, streams ${launch.streamPort}, bridge ${launch.enginePort}). The first run downloads the console binary next to the pinned iii.`,
- );
- const child = spawn(iiiBin, consoleArgs(launch), {
- stdio: "inherit",
- detached: true,
- });
- const forward = (signal: NodeJS.Signals): void => {
- try {
- process.kill(-child.pid!, signal);
- } catch {
- child.kill(signal);
- }
- };
- for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
- process.on(signal, () => forward(signal));
- }
- const code = await new Promise<number>((resolve) => {
- child.on("exit", (status, signal) => resolve(status ?? (signal ? 1 : 0)));
- child.on("error", (err) => {
- p.log.error(err.message);
- resolve(1);
- });
- });
- process.exit(code);
+ await discoverViewerPort();
+ p.log.warn("iii 0.25 retired the bundled engine console; --console-port and console launch flags no longer apply.");
+ p.note([
+ `AgentMemory viewer: ${getViewerUrl()} (start agentmemory first if it is offline).`,
+ "Use agentmemory status for runtime health and worker status.",
+ "Engine console migration: https://github.com/iii-hq/iii/blob/iii/v0.25.0/docs/using-iii/console.mdx",
+ ].join("\n"), "Console migration");
}
async function runCapture(): Promise<void> {
diff --git a/src/cli/compose-control.ts b/src/cli/compose-control.ts
new file mode 100644
index 00000000..4ff5d0b6
--- /dev/null
+++ b/src/cli/compose-control.ts
@@ -0,0 +1,245 @@
+import { chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+import { registerWorker } from "iii-sdk";
+import { composeNamespace, type ComposeProjectOptions, writeWorkerCompose, COMPOSE_WORKER_VERSIONS } from "./compose-project.js";
+
+export interface ComposeRuntime extends ComposeProjectOptions {
+ namespace?: string;
+ stateDir: string;
+ logFile: string;
+ envFile?: string;
+ iiiBin: string;
+ env: NodeJS.ProcessEnv;
+}
+
+export function composeRegistryFailureMessage(logText: string, workerBinDir?: string): string | null {
+ const patterns = [
+ /REGISTRY_UNREACHABLE|REGISTRY_ERROR|PACKAGE_DOWNLOAD_FAILED/i,
+ /cannot reach the registry/i,
+ /registry (?:returned|responded|response)[^\n]*HTTP 5\d\d|HTTP 5\d\d[^\n]*registry/i,
+ /failed to resolve (?:a )?package|package resolution (?:failed|unavailable)|could not resolve .*registry/i,
+ /could not download https:\/\/api\.workers\.iii\.dev\/download\//i,
+ ];
+ if (!patterns.some((pattern) => pattern.test(logText))) return null;
+ const localWorkers = workerBinDir ? ` Configured local workers directory: ${workerBinDir}.` : "";
+ return `Worker registry unavailable while resolving state/http; retry later or set AGENTMEMORY_WORKER_BIN_DIR.${localWorkers}`;
+}
+
+export function composeStateRegistryFailure(dataDir: string, file: string): string | null {
+ const stateRoot = join(dataDir, "compose-state");
+ try {
+ const files = [] as string[];
+ const walk = (dir: string) => {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) walk(path);
+ else if (entry.name === "state.json") files.push(path);
+ }
+ };
+ walk(stateRoot);
+ for (const stateFile of files) {
+ const state = JSON.parse(readFileSync(stateFile, "utf8")) as { compose_path?: string; containers?: Record<string, { status?: string; last_error?: string }> };
+ const errors = Object.entries(state.containers ?? {}).filter(([, value]) => value.status === "failed").map(([name, value]) => `${name}: ${value.last_error ?? "failed"}`);
+ const message = errors.join("\n");
+ if (state.compose_path !== file) continue;
+ if (message && composeRegistryFailureMessage(message)) return message;
+ }
+ } catch {}
+ return null;
+}
+
+export function composeWorkerFailureSummary(project: ComposeProjectStatus | null): string | null {
+ if (!project) return null;
+ const failed = (project.containers ?? []).filter((container) => container.state === "failed");
+ if (!failed.length) return null;
+ return failed.map((container) => `${container.container ?? "worker"}: ${container.last_error ?? "failed after restart attempts were exhausted"}`).join("\n");
+}
+
+export type ComposeContainerStatus = { container?: string; state?: string; version?: string; pid?: number; owned?: boolean; log_path?: string; last_error?: string };
+export type ComposeProjectStatus = { file?: string; state_dir?: string; namespace?: string; daemon_pid?: number; containers?: ComposeContainerStatus[]; [key: string]: unknown };
+export type ComposeStatus = ComposeProjectStatus & {
+ daemon_pid?: number;
+ projects?: Array<{ file?: string; state_dir?: string; [key: string]: unknown }>;
+};
+
+export function ownedComposeProject(status: ComposeStatus, file: string): ComposeProjectStatus | null {
+ return status.file === file ? status : status.projects?.find((item) => item.file === file) ?? null;
+}
+
+function cleanDaemonEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+ const out: NodeJS.ProcessEnv = {};
+ for (const key of ["HOME", "PATH", "LANG", "LC_ALL", "TERM", "NO_COLOR", "III_TELEMETRY_ENABLED", "MALLOC_ARENA_MAX", "III_BUNDLE_WORKERS_DISABLED", "III_COMPOSE_MAX_PARALLEL_WORKERS", "AGENTMEMORY_TOOLS", "AGENTMEMORY_VIEWER_HOST", "VIEWER_ALLOWED_HOSTS", "VIEWER_ALLOWED_ORIGINS"]) {
+ const value = env[key];
+ if (value !== undefined) out[key] = value;
+ }
+ return out;
+}
+
+export async function probeComposeEngine(port: number, signal: AbortSignal): Promise<boolean> {
+ if (signal.aborted) return false;
+ return await new Promise<boolean>((resolve) => {
+ const socket = createConnection({ host: "127.0.0.1", port });
+ let settled = false;
+ const finish = (ready: boolean) => {
+ if (settled) return;
+ settled = true;
+ signal.removeEventListener("abort", abort);
+ socket.destroy();
+ resolve(ready);
+ };
+ const abort = () => finish(false);
+ // The caller normally supplies a larger engine-readiness deadline. Keep
+ // each TCP probe bounded independently so a half-open route/proxy can never
+ // pin one iteration until the whole startup budget expires.
+ socket.setTimeout(1000);
+ socket.once("connect", () => finish(true));
+ socket.once("error", () => finish(false));
+ socket.once("timeout", () => finish(false));
+ signal.addEventListener("abort", abort, { once: true });
+ });
+}
+
+export async function assertComposePortsFree(ports: readonly number[]): Promise<void> {
+ for (const port of [...new Set(ports)]) {
+ const occupied = await new Promise<boolean>((resolve) => {
+ const socket = createConnection({ host: "127.0.0.1", port });
+ const done = (value: boolean) => { socket.destroy(); resolve(value); };
+ socket.setTimeout(350);
+ socket.once("connect", () => done(true));
+ socket.once("timeout", () => done(false));
+ socket.once("error", () => done(false));
+ });
+ if (occupied) throw new Error(`Port ${port} is already in use on 127.0.0.1. Stop the process that owns it or choose another --port/--instance before starting agentmemory.`);
+ }
+}
+
+export function composeEnvironment(env: NodeJS.ProcessEnv, stateDir: string): NodeJS.ProcessEnv {
+ return {
+ ...cleanDaemonEnv(env),
+ III_COMPOSE_STATE_DIR: stateDir,
+ III_TELEMETRY_ENABLED: "false",
+ ...(process.platform === "linux" ? { MALLOC_ARENA_MAX: "2" } : {}),
+ ...(env.AGENTMEMORY_DISABLE_COMPOSE_RESTART === "1" ? { AGENTMEMORY_DISABLE_COMPOSE_RESTART: "1" } : {}),
+ };
+}
+
+export async function composeCall<T>(options: {
+ engineUrl: string;
+ namespace: string;
+ functionId: "compose::down" | "compose::status";
+ file: string;
+ timeoutMs?: number;
+}): Promise<T> {
+ const client = registerWorker(options.engineUrl, {
+ workerName: "agentmemory-cli",
+ namespace: options.namespace,
+ invocationTimeoutMs: options.timeoutMs ?? 30_000,
+ otel: { enabled: false },
+ enableMetricsReporting: false,
+ });
+ try {
+ const connectionDeadline = Date.now() + 8_000;
+ while (client.getConnectionState() !== "connected" && Date.now() < connectionDeadline) {
+ const fatal = client.getFatalError();
+ if (fatal) throw fatal;
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ }
+ if (client.getConnectionState() !== "connected") throw new Error("Could not connect the Compose control client to its instance engine.");
+ const deadline = Date.now() + 8_000;
+ let lastError: unknown;
+ while (Date.now() < deadline) {
+ try {
+ const result = await client.trigger<T & { status?: string; error?: { code?: string; message?: string } }>({
+ function_id: options.functionId,
+ payload: { file: options.file },
+ timeoutMs: options.timeoutMs ?? 30_000,
+ });
+ if (result && typeof result === "object" && result.status === "failed") {
+ const detail = result.error?.message ?? result.error?.code ?? "unknown Compose failure";
+ throw Object.assign(new Error(`${result.error?.code ? `${result.error.code}: ` : ""}${detail}`), { retryable: false });
+ }
+ return result;
+ } catch (err) {
+ lastError = err;
+ if (err && typeof err === "object" && "retryable" in err && (err as { retryable?: boolean }).retryable === false) throw err;
+ await new Promise((resolve) => setTimeout(resolve, 150));
+ }
+ }
+ throw lastError ?? new Error("Compose daemon did not accept the control connection.");
+ } finally {
+ await client.shutdown().catch(() => {});
+ }
+}
+
+export function startComposeDaemon(runtime: ComposeRuntime): { child: ChildProcess; file: string; namespace: string; stateDir: string; logFile: string; logStartOffset: number } {
+ const project = writeWorkerCompose({ ...runtime, envFile: runtime.envFile });
+ const logFile = runtime.logFile;
+ mkdirSync(dirname(logFile), { recursive: true, mode: 0o700 });
+ chmodSync(dirname(logFile), 0o700);
+ const fd = openSync(logFile, "a", 0o600);
+ const logStartOffset = fstatSync(fd).size;
+ writeFileSync(fd, `\n[${new Date().toISOString()}] Starting Worker Compose\n`);
+ const environment = composeEnvironment(runtime.env, project.stateDir);
+ const child = spawn(runtime.iiiBin, ["compose", "--namespace", composeNamespace(runtime.ports.restPort), "--up", "--file", project.file], {
+ cwd: runtime.projectRoot,
+ detached: true,
+ stdio: ["ignore", fd, fd],
+ windowsHide: true,
+ env: environment,
+ });
+ closeSync(fd);
+ child.unref();
+ return {
+ child,
+ file: project.file,
+ namespace: composeNamespace(runtime.ports.restPort),
+ stateDir: project.stateDir,
+ logFile,
+ logStartOffset,
+ };
+}
+
+export function readComposeLogFromOffset(file: string, offset: number): string {
+ const fd = openSync(file, "r");
+ try {
+ const size = fstatSync(fd).size;
+ let position = Math.min(Math.max(0, offset), size);
+ const chunks: Buffer[] = [];
+ while (position < size) {
+ const chunk = Buffer.allocUnsafe(Math.min(16 * 1024, size - position));
+ const count = readSync(fd, chunk, 0, chunk.length, position);
+ if (count === 0) break;
+ chunks.push(chunk.subarray(0, count));
+ position += count;
+ }
+ return Buffer.concat(chunks).toString("utf8");
+ } finally {
+ closeSync(fd);
+ }
+}
+
+export function writeComposeState(path: string, state: {
+ kind: "compose";
+ restPort: number;
+ viewerPort: number;
+ enginePort: number;
+ engineUrl: string;
+ namespace: string;
+ file: string;
+ stateDir: string;
+ logFile: string;
+ logStartOffset?: number;
+ binPath: string;
+ enginePid?: number;
+ workerBinDir?: string;
+ workerFailure?: string;
+ workerVersions: typeof COMPOSE_WORKER_VERSIONS | { local: true };
+}): void {
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+ writeFileSync(path, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600 });
+ chmodSync(path, 0o600);
+}
+
diff --git a/src/cli/compose-process.ts b/src/cli/compose-process.ts
new file mode 100644
index 00000000..8fcad387
--- /dev/null
+++ b/src/cli/compose-process.ts
@@ -0,0 +1,56 @@
+import { execFileSync } from "node:child_process";
+import { readlinkSync, realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+/**
+ * On macOS, ask lsof for the process's text executable and accept only a
+ * response explicitly associated with this PID. The `-d txt` filter limits
+ * names to text descriptors (the process executable).
+ */
+export function readMacProcessExecutable(pid: number): string {
+ if (!Number.isSafeInteger(pid) || pid <= 0) return "";
+ try {
+ const output = execFileSync("lsof", ["-a", "-p", String(pid), "-d", "txt", "-Fpn"], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ });
+ let matchedPid = false;
+ for (const line of output.split(/\r?\n/)) {
+ if (line.startsWith("p")) {
+ if (line !== `p${pid}`) return "";
+ matchedPid = true;
+ continue;
+ }
+ if (matchedPid && line.startsWith("n")) {
+ const path = line.slice(1);
+ if (isAbsolute(path)) return path;
+ }
+ }
+ } catch {
+ // A missing lsof, exited process, or malformed response is not a match.
+ }
+ return "";
+}
+
+export function sameResolvedExecutable(actual: string, expected: string, windows = false): boolean {
+ try {
+ const actualPath = realpathSync(actual);
+ const expectedPath = realpathSync(expected);
+ return windows
+ ? actualPath.toLowerCase() === expectedPath.toLowerCase()
+ : actualPath === expectedPath;
+ } catch {
+ return false;
+ }
+}
+
+export function readUnixProcessExecutable(pid: number, os: "darwin" | "linux"): string {
+ if (!Number.isSafeInteger(pid) || pid <= 0) return "";
+ if (os === "darwin") return readMacProcessExecutable(pid);
+ try {
+ return readlinkSync(`/proc/${pid}/exe`);
+ } catch {
+ return "";
+ }
+}
+
diff --git a/src/cli/compose-project.ts b/src/cli/compose-project.ts
new file mode 100644
index 00000000..b84896aa
--- /dev/null
+++ b/src/cli/compose-project.ts
@@ -0,0 +1,392 @@
+import { chmodSync, existsSync, readFileSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+import { MAX_STARTUP_TIMEOUT_MS } from "./readiness.js";
+import { getStateSaveIntervalMs } from "../config.js";
+
+export interface EngineRuntimePorts {
+ restPort: number;
+ viewerPort: number;
+ enginePort: number;
+}
+
+export interface StateBackendOptions {
+ kind: "file" | "redis";
+ redisUrl?: string;
+}
+
+/** Registry versions are pinned here so every generated project uses one reviewed set. */
+export const COMPOSE_WORKER_VERSIONS = {
+ state: "0.22.20",
+ http: "0.22.7",
+} as const;
+
+export function composeNamespace(restPort: number): string {
+ // A distinct namespace per REST port prevents two separately managed engine
+ // daemons from competing for the SDK/default namespace during overlap.
+ return `agentmemory-${restPort}`;
+}
+
+export function composeProjectPaths(dataDir: string): {
+ directory: string;
+ file: string;
+ stateDir: string;
+ logFile: string;
+ configDir: string;
+} {
+ const directory = join(dataDir, "compose");
+ return {
+ directory,
+ file: join(directory, "worker-compose.yaml"),
+ stateDir: join(dataDir, "compose-state"),
+ logFile: join(directory, "compose-daemon.log"),
+ configDir: join(directory, "config"),
+ };
+}
+
+const AGENTMEMORY_WORKER_ENV_ALLOWLIST = new Set([
+ "EMBEDDING_PROVIDER", "OPENAI_API_KEY", "OPENAI_API_KEY_FOR_LLM", "OPENAI_BASE_URL",
+ "OPENAI_MODEL", "OPENAI_EMBEDDING_API_KEY", "OPENAI_EMBEDDING_BASE_URL",
+ "OPENAI_EMBEDDING_MODEL", "OPENAI_EMBEDDING_DIMENSIONS", "ANTHROPIC_API_KEY",
+ "ANTHROPIC_BASE_URL", "ANTHROPIC_MODEL", "GEMINI_API_KEY", "GEMINI_MODEL",
+ "GOOGLE_API_KEY", "VOYAGE_API_KEY", "VOYAGE_MODEL", "COHERE_API_KEY",
+ "COHERE_MODEL", "OPENROUTER_API_KEY", "OPENROUTER_MODEL", "MINIMAX_API_KEY",
+ "MINIMAX_MODEL", "OLLAMA_HOST", "LLM_PROVIDER", "BM25_WEIGHT", "VECTOR_WEIGHT",
+ "MAX_TOKENS", "TOKEN_BUDGET", "MAX_OBS_PER_SESSION", "CONSOLIDATION_ENABLED",
+ "GRAPH_EXTRACTION_ENABLED", "AGENTMEMORY_AUTO_COMPRESS", "AGENTMEMORY_INJECT_CONTEXT",
+ "AGENTMEMORY_ALLOW_AGENT_SDK", "AGENTMEMORY_SESSION_SWEEP_ENABLED",
+ "AGENTMEMORY_SESSION_SWEEP_STALE_HOURS", "AGENTMEMORY_FINALIZE_IDLE_MS",
+ "AGENTMEMORY_GRAPH_COMPACT_ON_BOOT", "AGENTMEMORY_DROP_STALE_INDEX",
+ "AGENTMEMORY_AUDIT_RETENTION_MONTHS", "AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES",
+ "AGENTMEMORY_STATE_SAVE_INTERVAL_MS", "AGENTMEMORY_TOOLS", "AGENTMEMORY_VIEWER_HOST",
+ "VIEWER_ALLOWED_HOSTS", "VIEWER_ALLOWED_ORIGINS", "AGENTMEMORY_SECRET", "AGENT_ID", "TEAM_ID",
+ "TEAM_MODE", "USER_ID", "AGENTMEMORY_AGENT_SCOPE", "SNAPSHOT_DIR", "SNAPSHOT_ENABLED",
+ "SNAPSHOT_INTERVAL", "STANDALONE_PERSIST_PATH", "CLAUDE_MEMORY_BRIDGE",
+ "CLAUDE_MEMORY_LINE_BUDGET", "CLAUDE_PROJECT_PATH", "AGENTMEMORY_SUPPRESS_COST_WARNING",
+ "FALLBACK_PROVIDERS", "OPENAI_API_VERSION", "OPENAI_REASONING_EFFORT", "OPENAI_TIMEOUT_MS",
+ "MINIMAX_BASE_URL", "OPENROUTER_EMBEDDING_MODEL", "OPENROUTER_EMBEDDING_DIMENSIONS",
+ "AGENTMEMORY_LLM_TIMEOUT_MS", "AGENTMEMORY_CAPTURE_MAX_ATTEMPTS",
+ "AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS", "AGENTMEMORY_CAPTURE_DEDUP_HOURS",
+ "AGENTMEMORY_CAPTURE_INBOX_MAX", "AGENTMEMORY_CAPTURE_DEAD_MAX", "AGENTMEMORY_CAPTURE_EVENTS_MAX",
+ "AGENTMEMORY_CAPTURE_SPOOL", "AGENTMEMORY_CAPTURE_SPOOL_DIR",
+ "AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES", "AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS",
+ "AGENTMEMORY_IMPORT_ROOT", "AGENTMEMORY_EXPORT_ROOT", "AGENTMEMORY_GRAPH_WEIGHT",
+ "SUMMARIZE_CHUNK_SIZE", "SUMMARIZE_CHUNK_CONCURRENCY", "CONSOLIDATION_DECAY_DAYS",
+ "CONSOLIDATION_INTERVAL_MS", "AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS",
+ "AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS", "GRAPH_EXTRACTION_BATCH_SIZE", "AGENTMEMORY_LLM_NOTHINK",
+ "AGENTMEMORY_REFLECT", "AGENTMEMORY_IMAGE_EMBEDDINGS", "AGENTMEMORY_IMAGE_STORE_MAX_BYTES",
+ "AGENTMEMORY_AUDIT_INDEX_PERSIST", "AGENTMEMORY_INDEX_SAVE_INTERVAL_MS",
+ "AGENTMEMORY_VECTOR_BUCKET_SIZE", "AGENTMEMORY_VECTOR_BACKFILL_MAX",
+ "AGENTMEMORY_VECTOR_BACKFILL", "AGENTMEMORY_SLOTS", "AGENTMEMORY_PROVIDER", "AGENTMEMORY_VERBOSE",
+ "OBSIDIAN_AUTO_EXPORT", "AUTO_FORGET_ENABLED", "AUTO_FORGET_INTERVAL_MS", "LESSON_DECAY_ENABLED",
+ "INSIGHT_DECAY_ENABLED", "REBUILD_EMBED_BATCH_SIZE", "RERANK_ENABLED",
+]);
+
+const COMPOSE_RESERVED_ENV = new Set([
+ "III_URL",
+ "III_ENGINE_URL",
+ "III_ENGINE_PORT",
+ "III_REST_PORT",
+ "III_VIEWER_PORT",
+ "III_NAMESPACE",
+ "III_COMPOSE_NAMESPACE",
+ "III_COMPOSE_FILE",
+ "III_COMPOSE_DIR",
+ "III_CONFIG_NAME",
+ "III_WORKER_NAME",
+]);
+
+function stateSaveInterval(value: string | undefined): number {
+ if (value === undefined || value.trim() === "") return getStateSaveIntervalMs();
+ if (!/^\d+$/.test(value.trim())) throw new Error("AGENTMEMORY_STATE_SAVE_INTERVAL_MS must be an integer between 100 and 3600000.");
+ const parsed = Number(value);
+ if (!Number.isSafeInteger(parsed) || parsed < 100 || parsed > 3_600_000) {
+ throw new Error("AGENTMEMORY_STATE_SAVE_INTERVAL_MS must be an integer between 100 and 3600000.");
+ }
+ return parsed;
+}
+
+function restartPolicyLines(indent: string, enabled: boolean): string[] {
+ if (!enabled) return [`${indent}restart: no`];
+ return [
+ `${indent}restart:`,
+ `${indent} condition: on-failure`,
+ `${indent} delay: 500ms`,
+ `${indent} max_delay: 30s`,
+ `${indent} max_attempts: 5`,
+ `${indent} window: 60s`,
+ ];
+}
+
+export function shellQuote(value: string, windows: boolean): string {
+ if (/[\u0000-\u001f\u007f]/.test(value)) throw new Error("A shell command argument contains an unsupported control character.");
+ if (windows) {
+ // Windows paths cannot contain quotes. Doubling percent signs keeps literal
+ // percent characters in cmd.exe; quotes protect whitespace and metacharacters.
+ if (value.includes('"')) throw new Error("Windows shell arguments cannot contain a double quote.");
+ return `"${value.replace(/%/g, "%%")}"`;
+ }
+ return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+export function shellCommand(program: string, args: string[], windows: boolean): string {
+ const command = [program, ...args].map((part) => shellQuote(part, windows)).join(" ");
+ // cmd.exe /C treats an initial quote specially. The outer quote pair makes
+ // the quoted executable and its arguments one command string.
+ return windows ? `"${command}"` : command;
+}
+
+function yamlString(value: string): string {
+ if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)) {
+ throw new Error("A Compose path or configuration value contains an unsupported control character.");
+ }
+ return `'${value.replace(/'/g, "''")}'`;
+}
+
+function localWorkerDirectory(value: string, cwd: string, projectRoot: string): string {
+ if (isAbsolute(value)) return resolve(value);
+ const fromCwd = resolve(cwd, value);
+ const fromProject = resolve(projectRoot, value);
+ if (fromCwd === fromProject) return fromCwd;
+ if (!fromCwd.startsWith(`${resolve(projectRoot)}/`)) return fromCwd;
+ return fromProject;
+}
+
+function localWorkerProjectDir(paths: ReturnType<typeof composeProjectPaths>, name: string): string {
+ return join(paths.directory, "local-workers", name);
+}
+
+function ensureEngineTraceStorageConfig(configDir: string, dataDir: string): void {
+ const configFile = join(configDir, "iii-observability.yaml");
+ const traceDirectory = resolve(dataDir, "observability", "traces");
+ const defaultTraceDirectory = "./data/observability/traces";
+ let entry: Record<string, unknown>;
+ if (existsSync(configFile)) {
+ const parsed: unknown = parse(readFileSync(configFile, "utf8"));
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+ throw new Error(`Invalid persisted iii-observability configuration at ${configFile}.`);
+ }
+ entry = parsed as Record<string, unknown>;
+ if (entry.id !== "iii-observability") {
+ throw new Error(`Unexpected configuration id in ${configFile}; refusing to replace it.`);
+ }
+ } else {
+ entry = {
+ id: "iii-observability", name: "Observability", description: "", schema: {},
+ value: { sampling_ratio: 0.1, logs_console_output: false },
+ };
+ }
+
+ const value = entry.value && typeof entry.value === "object" && !Array.isArray(entry.value)
+ ? entry.value as Record<string, unknown>
+ : {};
+ let changed = false;
+ if (value.sampling_ratio === undefined) { value.sampling_ratio = 0.1; changed = true; }
+ if (value.logs_console_output === undefined) { value.logs_console_output = false; changed = true; }
+ const existingStorage = value.trace_storage;
+ const storage = existingStorage && typeof existingStorage === "object" && !Array.isArray(existingStorage)
+ ? existingStorage as Record<string, unknown>
+ : {};
+ const existingDirectory = storage.directory;
+ if (typeof existingDirectory === "string" && existingDirectory.trim() !== "" && existingDirectory !== defaultTraceDirectory) {
+ if (!changed) return;
+ } else {
+ storage.directory = traceDirectory;
+ changed = true;
+ }
+ if (!changed) return;
+ if (existingDirectory === undefined || existingDirectory === defaultTraceDirectory || existingDirectory === "") value.trace_storage = storage;
+ entry.value = value;
+ const temporaryFile = `${configFile}.tmp`;
+ writeFileSync(temporaryFile, stringify(entry), { encoding: "utf8", mode: 0o600 });
+ chmodSync(temporaryFile, 0o600);
+ renameSync(temporaryFile, configFile);
+ chmodSync(configFile, 0o600);
+}
+
+export interface ComposeProjectOptions {
+ ports: EngineRuntimePorts;
+ dataDir: string;
+ projectRoot: string;
+ nodeBin: string;
+ homeDir: string;
+ envFile?: string;
+ workerBinDir?: string;
+ workerBinDirIsAbsolute?: boolean;
+ redisUrl?: string;
+ workerEnvironment?: NodeJS.ProcessEnv;
+ cwd?: string;
+ stateBackend?: StateBackendOptions;
+ startupTimeoutMs?: number;
+ linux?: boolean;
+ disableRestartPolicy?: boolean;
+ windows?: boolean;
+}
+
+export function renderWorkerCompose(options: ComposeProjectOptions): string {
+ const { restPort, viewerPort, enginePort } = options.ports;
+ const paths = composeProjectPaths(options.dataDir);
+ const namespace = composeNamespace(restPort);
+ const workerBinDir = options.workerBinDir
+ ? options.workerBinDirIsAbsolute
+ ? resolve(options.workerBinDir)
+ : localWorkerDirectory(options.workerBinDir, options.cwd ?? process.cwd(), options.projectRoot)
+ : null;
+ const startupSeconds = Math.ceil((options.startupTimeoutMs ?? 300_000) / 1000);
+ const restartEnabled = !options.disableRestartPolicy;
+ if (!Number.isSafeInteger(startupSeconds) || startupSeconds < 1 || startupSeconds * 1000 > MAX_STARTUP_TIMEOUT_MS + 999) {
+ throw new Error("Compose worker startup timeout must be between 1 and 3600000 milliseconds.");
+ }
+
+ const workerSource = (name: keyof typeof COMPOSE_WORKER_VERSIONS): string =>
+ workerBinDir
+ ? `path://${localWorkerProjectDir(paths, name)}`
+ : `package://api.workers.iii.dev/${name}`;
+ const workerScript = (name: keyof typeof COMPOSE_WORKER_VERSIONS): string =>
+ workerBinDir ? join(workerBinDir, name) : "";
+ const filteredEnvFile = options.envFile
+ ? join(paths.directory, ".agentmemory-filtered.env")
+ : undefined;
+ const lines = [
+ `namespace: ${namespace}`,
+ "startup_timeout: 60s",
+ "stop_timeout: 20s",
+ "required_default: true",
+ "engine:",
+ ` url: ws://127.0.0.1:${enginePort}`,
+ " workers:",
+ " configuration:",
+ " adapter:",
+ " name: fs",
+ " config:",
+ ` directory: ${yamlString(paths.configDir)}`,
+ " iii-worker-manager:",
+ " host: 127.0.0.1",
+ ` port: ${enginePort}`,
+ "containers:",
+ ];
+
+ const stateScript = workerScript("state");
+ lines.push(
+ " state:",
+ ` worker: ${yamlString(workerSource("state"))}`,
+ ...(!workerBinDir ? [` version: ${yamlString(COMPOSE_WORKER_VERSIONS.state)}`] : []),
+ " config_name: state",
+ ...restartPolicyLines(" ", restartEnabled),
+ ...(workerBinDir ? [` scripts:`, ` run: ${yamlString(shellCommand(stateScript, [], options.windows ?? process.platform === "win32"))}`] : []),
+ " config_override:",
+ " adapter:",
+ " name: kv",
+ " config:",
+ );
+ if (options.stateBackend?.kind === "redis") {
+ const redisUrl = options.redisUrl ?? options.stateBackend.redisUrl;
+ if (!redisUrl) {
+ throw new Error("AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL to be set (e.g. redis://localhost:6379).");
+ }
+ if (/[\u0000-\u001f\u007f]/.test(redisUrl)) {
+ throw new Error("AGENTMEMORY_REDIS_URL contains a control character; percent-encode it before using Redis.");
+ }
+ lines.splice(lines.length - 2, 2, " name: redis", " config:", ` redis_url: ${yamlString(redisUrl)}`);
+ } else {
+ lines.push(
+ " store_method: file_based",
+ ` file_path: ${yamlString(join(options.dataDir, "state_store.db"))}`,
+ ` save_interval_ms: ${stateSaveInterval(options.workerEnvironment?.AGENTMEMORY_STATE_SAVE_INTERVAL_MS)}`,
+ );
+ }
+
+ const httpScript = workerScript("http");
+ lines.push(
+ " http:",
+ ` worker: ${yamlString(workerSource("http"))}`,
+ ...(!workerBinDir ? [` version: ${yamlString(COMPOSE_WORKER_VERSIONS.http)}`] : []),
+ " config_name: http",
+ ...restartPolicyLines(" ", restartEnabled),
+ ...(workerBinDir ? [` scripts:`, ` run: ${yamlString(shellCommand(httpScript, [], options.windows ?? process.platform === "win32"))}`] : []),
+ " config_override:",
+ " host: 127.0.0.1",
+ ` port: ${restPort}`,
+ " default_timeout: 180000",
+ " cors:",
+ " allowed_origins:",
+ ` - ${yamlString(`http://localhost:${restPort}`)}`,
+ ` - ${yamlString(`http://localhost:${viewerPort}`)}`,
+ ` - ${yamlString(`http://127.0.0.1:${restPort}`)}`,
+ ` - ${yamlString(`http://127.0.0.1:${viewerPort}`)}`,
+ " allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]",
+ );
+
+ lines.push(
+ " agentmemory:",
+ ` worker: ${yamlString(`path://${options.projectRoot}`)}`,
+ " start_after: [state, http]",
+ ` startup_timeout: ${startupSeconds}s`,
+ " config_name: agentmemory",
+ ...restartPolicyLines(" ", restartEnabled),
+ " scripts:",
+ ` run: ${yamlString(shellCommand(options.nodeBin, ["dist/index.mjs"], options.windows ?? process.platform === "win32"))}`,
+ );
+ if (filteredEnvFile) lines.push(` env_file: [${yamlString(filteredEnvFile)}]`);
+ const explicitWorkerEnvironment = Object.entries(options.workerEnvironment ?? {})
+ .filter(([key, value]) => value !== undefined && AGENTMEMORY_WORKER_ENV_ALLOWLIST.has(key) && !COMPOSE_RESERVED_ENV.has(key))
+ .sort(([left], [right]) => left.localeCompare(right));
+ lines.push(
+ " environment:",
+ ...explicitWorkerEnvironment.map(([key, value]) => ` ${key}: ${yamlString(value!)}`),
+ ` HOME: ${yamlString(options.homeDir)}`,
+ ` PATH: ${yamlString(`${dirname(options.nodeBin)}:/usr/local/bin:/usr/bin:/bin`)}`,
+ ` AGENTMEMORY_DATA_DIR: ${yamlString(options.dataDir)}`,
+ ` AGENTMEMORY_RUNTIME_DIR: ${yamlString(options.dataDir)}`,
+ ...(filteredEnvFile ? [` AGENTMEMORY_ENV_FILE: ${yamlString(filteredEnvFile)}`] : []),
+ ...(options.stateBackend?.kind === "redis" && options.redisUrl ? [` AGENTMEMORY_REDIS_URL: ${yamlString(options.redisUrl)}`, " AGENTMEMORY_STATE_BACKEND: 'redis'"] : []),
+ ` III_ENGINE_PORT: ${yamlString(String(enginePort))}`,
+ ` III_REST_PORT: ${yamlString(String(restPort))}`,
+ ` III_VIEWER_PORT: ${yamlString(String(viewerPort))}`,
+ " III_TELEMETRY_ENABLED: 'false'",
+ ...(options.linux ?? process.platform === "linux" ? [" MALLOC_ARENA_MAX: '2'"] : []),
+ "",
+ );
+ return lines.join("\n");
+}
+
+export function writeWorkerCompose(options: ComposeProjectOptions): { file: string; stateDir: string; logFile: string; text: string } {
+ const paths = composeProjectPaths(options.dataDir);
+ mkdirSync(paths.directory, { recursive: true, mode: 0o700 });
+ mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
+ mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+ ensureEngineTraceStorageConfig(paths.configDir, options.dataDir);
+ mkdirSync(join(options.dataDir, "observability", "traces"), { recursive: true, mode: 0o700 });
+ if (options.workerBinDir) {
+ const binDir = options.workerBinDirIsAbsolute
+ ? resolve(options.workerBinDir)
+ : localWorkerDirectory(options.workerBinDir, options.cwd ?? process.cwd(), options.projectRoot);
+ for (const name of Object.keys(COMPOSE_WORKER_VERSIONS) as Array<keyof typeof COMPOSE_WORKER_VERSIONS>) {
+ const projectDir = localWorkerProjectDir(paths, name);
+ mkdirSync(projectDir, { recursive: true, mode: 0o700 });
+ const manifest = [
+ "iii: v1",
+ `name: ${name}`,
+ "language: rust",
+ "scripts:",
+ ` start: ${yamlString(join(binDir, name))}`,
+ "",
+ ].join("\n");
+ writeFileSync(join(projectDir, "iii.worker.yaml"), manifest, { encoding: "utf8", mode: 0o600 });
+ chmodSync(join(projectDir, "iii.worker.yaml"), 0o600);
+ }
+ }
+ const text = renderWorkerCompose(options);
+ if (options.envFile) {
+ const filteredPath = join(paths.directory, ".agentmemory-filtered.env");
+ const entries = readFileSync(options.envFile, "utf8").split(/\r?\n/).filter((line) => {
+ const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+ return !match || !COMPOSE_RESERVED_ENV.has(match[1]!);
+ });
+ writeFileSync(filteredPath, `${entries.join("\n")}\n`, { encoding: "utf8", mode: 0o600 });
+ chmodSync(filteredPath, 0o600);
+ }
+ writeFileSync(paths.file, text, { encoding: "utf8", mode: 0o600 });
+ chmodSync(paths.file, 0o600);
+ return { file: paths.file, stateDir: paths.stateDir, logFile: paths.logFile, text };
+}
diff --git a/src/cli/console.ts b/src/cli/console.ts
deleted file mode 100644
index e0fb42b2..00000000
--- a/src/cli/console.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-export interface ConsoleLaunch {
- iiiBin: string;
- consolePort: number;
- restPort: number;
- streamPort: number;
- enginePort: number;
- extraArgs: string[];
-}
-
-const GLOBAL_VALUE_FLAGS = new Set(["--port", "--instance", "--data-dir", "--tools"]);
-const GLOBAL_BOOLEAN_FLAGS = new Set(["--verbose", "-v", "--no-engine"]);
-
-export function defaultConsolePort(viewerPort: number): number {
- return viewerPort + 1;
-}
-
-function readPort(raw: string | undefined, flag: string): number {
- const port = raw === undefined ? Number.NaN : Number(raw);
- if (!Number.isInteger(port) || port < 1 || port > 65535) {
- throw new Error(`${flag} needs a port between 1 and 65535`);
- }
- return port;
-}
-
-export function parseConsoleArgs(
- tail: string[],
- fallbackPort: number,
-): { consolePort: number; extraArgs: string[] } {
- let consolePort = fallbackPort;
- const extraArgs: string[] = [];
- for (let i = 0; i < tail.length; i++) {
- const arg = tail[i]!;
- if (arg === "--console-port") {
- consolePort = readPort(tail[i + 1], arg);
- i++;
- continue;
- }
- if (arg.startsWith("--console-port=")) {
- consolePort = readPort(arg.slice("--console-port=".length), "--console-port");
- continue;
- }
- if (GLOBAL_VALUE_FLAGS.has(arg)) {
- i++;
- continue;
- }
- if ([...GLOBAL_VALUE_FLAGS].some((flag) => arg.startsWith(`${flag}=`))) continue;
- if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
- extraArgs.push(arg);
- }
- return { consolePort, extraArgs };
-}
-
-export function consoleArgs(launch: ConsoleLaunch): string[] {
- return [
- "console",
- "--port",
- String(launch.consolePort),
- "--engine-port",
- String(launch.restPort),
- "--ws-port",
- String(launch.streamPort),
- "--bridge-port",
- String(launch.enginePort),
- ...launch.extraArgs,
- ];
-}
diff --git a/src/cli/doctor-diagnostics.ts b/src/cli/doctor-diagnostics.ts
index 78705d60..33f67c2d 100644
--- a/src/cli/doctor-diagnostics.ts
+++ b/src/cli/doctor-diagnostics.ts
@@ -38,7 +38,7 @@ export type DoctorContext = {
pidfilePath: string;
/** Path to ~/.agentmemory/engine-state.json */
enginePath: string;
- /** Pinned engine version (e.g. "0.22.1"). */
+ /** Pinned engine version. */
pinnedVersion: string;
};
@@ -217,10 +217,11 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] {
id: "engine-version-mismatch",
message: "iii binary on PATH doesn't match the version agentmemory pins to.",
fixPreview:
- "Re-run the iii installer for the pinned version and restart the engine.",
+ "Reinstall the pinned iii-engine and restart the managed Worker Compose project.",
moreInfo:
- "agentmemory pins the iii engine to a specific release because newer engines " +
- "use a different worker model. Running a mismatched binary surfaces as EPIPE " +
+ "agentmemory manages its pinned iii engine and workers through Worker Compose; " +
+ "a foreign process on PATH is not the instance binary. " +
+ "Running a mismatched binary surfaces as EPIPE " +
"reconnect loops and empty search results.",
check: async (ctx) => {
const bin = effects.findIiiBinary();
@@ -262,11 +263,11 @@ export function buildDiagnostics(effects: DoctorEffects): Diagnostic[] {
{
id: "stale-pidfile",
message: "Stale pidfile: pid recorded but the process is gone.",
- fixPreview: "Clear ~/.agentmemory/iii.pid + engine-state.json, then restart.",
+ fixPreview: "Verify the Compose daemon ownership record and restart only the managed project.",
moreInfo:
- "When the engine crashes hard (kill -9, OOM, host reboot) the pidfile sticks " +
- "around. agentmemory refuses to start a second engine on top of a stale pid, " +
- "so this state must be cleared explicitly.",
+ "When a managed Compose daemon crashes hard (kill -9, OOM, host reboot), its " +
+ "ownership PID can stick around. The check uses the saved Compose process, " +
+ "never a legacy iii.pid from a previous lifecycle.",
check: async () => {
if (!effects.pidfileExists()) return { ok: true, detail: "no pidfile" };
const alive = effects.pidfilePidIsAlive();
diff --git a/src/cli/engine-config.ts b/src/cli/engine-config.ts
index 1831261b..1260fcd2 100644
--- a/src/cli/engine-config.ts
+++ b/src/cli/engine-config.ts
@@ -1,37 +1,4 @@
-import { readFileSync, rmSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-
-const SEEDED_BUILTIN_WORKERS = [
- "http",
- "iii-http",
- "state",
- "iii-state",
- "queue",
- "iii-queue",
- "pubsub",
- "iii-pubsub",
- "cron",
- "iii-cron",
- "iii-stream",
- "iii-observability",
- "iii-worker-manager",
-];
-
-export function configuredPersistDir(renderedConfig: string): string | null {
- const lines = renderedConfig.split("\n");
- const block = workerBlock(lines, "configuration");
- if (!block) return null;
- for (let i = block.start + 1; i < block.end; i++) {
- const match = lines[i]!.trim().match(/^directory:\s*(.+?)\s*$/);
- if (match) return match[1]!.replace(/^(['"])(.*)\1$/, "$2");
- }
- return null;
-}
-
-export function configuredSaveIntervalMs(renderedConfig: string): number | null {
- const match = renderedConfig.match(/save_interval_ms:\s*(\d+)/);
- return match ? parseInt(match[1]!, 10) : null;
-}
+import { join } from "node:path";
export const ENGINE_DEFAULT_SAVE_INTERVAL_MS = 5000;
export const AGENTMEMORY_STATE_SAVE_INTERVAL_MS = 2000;
@@ -53,10 +20,14 @@ export function captureDurableAfterMs(
return engineSaveIntervalMs(configTexts) + ENGINE_FLUSH_MARGIN_MS;
}
-export function engineSaveIntervalMs(configTexts: readonly string[]): number {
+export function engineSaveIntervalMs(configTexts: readonly string[], env: NodeJS.ProcessEnv = process.env): number {
const intervals: number[] = [];
for (const text of configTexts) {
- const explicit = [...text.matchAll(/save_interval_ms:\s*(\d+)/g)].map((m) => parseInt(m[1]!, 10));
+ const explicit: number[] = [];
+ for (const match of text.matchAll(/save_interval_ms:\s*["']?(\d+|\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(\d+))?\})/g)) {
+ const raw = match[2] ? env[match[2]] || match[3] : match[1];
+ if (raw && /^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))) explicit.push(Number(raw));
+ }
intervals.push(...explicit);
const fileStores = text.match(/store_method:\s*file_based/g)?.length ?? 0;
if (fileStores > explicit.length) intervals.push(ENGINE_DEFAULT_SAVE_INTERVAL_MS);
@@ -65,308 +36,11 @@ export function engineSaveIntervalMs(configTexts: readonly string[]): number {
}
export function engineStateConfigPaths(engineCwd: string, runtimePath: string): string[] {
- return [
- ...persistedBuiltinConfigDirs(engineCwd, runtimePath).map((dir) => join(dir, "iii-state.yaml")),
+ return [...new Set([
+ join(engineCwd, "compose", "worker-compose.yaml"),
+ join(engineCwd, "compose", "config", "state.yaml"),
+ join(engineCwd, "worker-compose.runtime.yaml"),
+ join(engineCwd, "config", "state.yaml"),
runtimePath,
- ];
-}
-
-export function persistedBuiltinConfigDirs(
- engineCwd: string,
- configPath: string,
- renderedConfig?: string,
-): string[] {
- const dirs = [
- join(engineCwd, "config"),
- join(dirname(configPath), "config"),
- join(engineCwd, "data", "configuration"),
- ];
- const custom = renderedConfig ? configuredPersistDir(renderedConfig) : null;
- if (custom) dirs.unshift(resolve(engineCwd, custom));
- return [...new Set(dirs)];
-}
-
-export function persistedBuiltinConfigPaths(
- engineCwd: string,
- configPath: string,
- renderedConfig?: string,
-): string[] {
- return persistedBuiltinConfigDirs(engineCwd, configPath, renderedConfig).flatMap((dir) =>
- SEEDED_BUILTIN_WORKERS.map((id) => join(dir, `${id}.yaml`)),
- );
-}
-
-export function isPersistedBuiltinEntry(content: string, id: string): boolean {
- const firstLine = content.split("\n").find((line) => line.trim() !== "");
- return firstLine?.trim() === `id: ${id}`;
-}
-
-export function clearPersistedBuiltinConfig(
- engineCwd: string,
- configPath: string,
- renderedConfig?: string,
-): string[] {
- const cleared: string[] = [];
- for (const path of persistedBuiltinConfigPaths(engineCwd, configPath, renderedConfig)) {
- try {
- const content = readFileSync(path, "utf8");
- if (!isPersistedBuiltinEntry(content, basename(path, ".yaml"))) continue;
- rmSync(path);
- cleared.push(path);
- } catch (err) {
- if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
- throw new Error(
- `could not remove persisted engine config ${path}: ${String(err)}`,
- );
- }
- }
- return cleared;
-}
-
-export interface EngineConfigOptions {
- dataDir: string;
- ports?: EngineRuntimePorts;
- stateBackend?: StateBackendOptions;
- saveIntervalMs?: number;
-}
-
-export interface EngineRuntimePorts {
- restPort: number;
- streamPort: number;
- viewerPort: number;
- enginePort: number;
-}
-
-export interface StateBackendOptions {
- kind: "file" | "redis";
- redisUrl?: string;
-}
-
-function yamlSingleQuote(value: string): string {
- return `'${value.replace(/'/g, "''")}'`;
-}
-
-function workerBlock(
- lines: string[],
- name: string,
-): { start: number; end: number; indent: string } | null {
- const marker = `- name: ${name}`;
- const start = lines.findIndex((line) => line.trim() === marker);
- if (start === -1) return null;
- const indent = lines[start]!.match(/^\s*/)?.[0] ?? "";
- let end = lines.length;
- for (let i = start + 1; i < lines.length; i++) {
- const line = lines[i]!;
- if (line.startsWith(indent) && line.trim().startsWith("- name: ")) {
- end = i;
- break;
- }
- }
- return { start, end, indent };
-}
-
-function setWorkerPort(lines: string[], name: string, port: number): void {
- let block = workerBlock(lines, name);
- if (!block && name === "iii-worker-manager") {
- const workersIndex = lines.findIndex((line) => line.trim() === "workers:");
- if (workersIndex === -1) return;
- lines.splice(
- workersIndex + 1,
- 0,
- " - name: iii-worker-manager",
- " config:",
- ` port: ${port}`,
- " host: 127.0.0.1",
- );
- return;
- }
- if (!block) return;
-
- const portIndex = lines.findIndex(
- (line, index) =>
- index > block!.start &&
- index < block!.end &&
- line.trim().startsWith("port:"),
- );
- if (portIndex !== -1) {
- const indent = lines[portIndex]!.match(/^\s*/)?.[0] ?? `${block.indent} `;
- lines[portIndex] = `${indent}port: ${port}`;
- return;
- }
-
- const configIndex = lines.findIndex(
- (line, index) =>
- index > block!.start && index < block!.end && line.trim() === "config:",
- );
- if (configIndex !== -1) {
- const configIndent = lines[configIndex]!.match(/^\s*/)?.[0] ?? `${block.indent} `;
- lines.splice(configIndex + 1, 0, `${configIndent} port: ${port}`);
- }
-}
-
-function setFileStoreSaveInterval(
- lines: string[],
- workerName: string,
- override: number | undefined,
-): void {
- const block = workerBlock(lines, workerName);
- if (!block) return;
- const methodIndex = lines.findIndex(
- (line, index) =>
- index > block.start &&
- index < block.end &&
- line.trim() === "store_method: file_based",
- );
- if (methodIndex === -1) return;
- const indent = lines[methodIndex]!.match(/^\s*/)?.[0] ?? "";
- const intervalIndex = lines.findIndex(
- (line, index) =>
- index > block.start &&
- index < block.end &&
- line.trim().startsWith("save_interval_ms:"),
- );
- if (intervalIndex !== -1) {
- if (override === undefined) return;
- const existingIndent = lines[intervalIndex]!.match(/^\s*/)?.[0] ?? indent;
- lines[intervalIndex] = `${existingIndent}save_interval_ms: ${override}`;
- return;
- }
- lines.splice(
- methodIndex + 1,
- 0,
- `${indent}save_interval_ms: ${override ?? AGENTMEMORY_STATE_SAVE_INTERVAL_MS}`,
- );
-}
-
-const REDIS_URL_ENV_REF = "${AGENTMEMORY_REDIS_URL}";
-const UNSAFE_REDIS_URL_CHARS = /['\u0000-\u001f\u007f]/;
-
-function replaceKvAdapterWithRedis(
- lines: string[],
- workerName: string,
-): void {
- const block = workerBlock(lines, workerName);
- if (!block) {
- throw new Error(
- `AGENTMEMORY_STATE_BACKEND=redis requires a "${workerName}" worker in the engine config, but none was found.`,
- );
- }
- const adapterIndex = lines.findIndex(
- (line, index) =>
- index > block.start && index < block.end && line.trim() === "adapter:",
- );
- if (adapterIndex === -1) {
- throw new Error(
- `AGENTMEMORY_STATE_BACKEND=redis requires an "adapter:" block under the "${workerName}" worker in the engine config, but none was found.`,
- );
- }
- const adapterIndent = lines[adapterIndex]!.match(/^\s*/)?.[0] ?? "";
- let end = block.end;
- for (let i = adapterIndex + 1; i < block.end; i++) {
- const line = lines[i]!;
- if (line.trim() === "") continue;
- const indent = line.match(/^\s*/)?.[0] ?? "";
- if (indent.length <= adapterIndent.length) {
- end = i;
- break;
- }
- }
- const childIndent = `${adapterIndent} `;
- const grandchildIndent = `${adapterIndent} `;
- lines.splice(
- adapterIndex + 1,
- end - (adapterIndex + 1),
- `${childIndent}name: redis`,
- `${childIndent}config:`,
- `${grandchildIndent}redis_url: ${yamlSingleQuote(REDIS_URL_ENV_REF)}`,
- );
-}
-
-function indentWidth(line: string): number {
- return line.length - line.trimStart().length;
-}
-
-function mappingValueEnd(lines: string[], keyIndex: number, limit: number): number {
- const keyIndent = indentWidth(lines[keyIndex]!);
- let end = keyIndex + 1;
- for (let i = keyIndex + 1; i < limit; i++) {
- const text = lines[i]!.trim();
- if (text === "" || text.startsWith("#")) continue;
- const indent = indentWidth(lines[i]!);
- const continuesValue =
- indent > keyIndent || (indent === keyIndent && /^(-(\s|$)|[\]}])/.test(text));
- if (!continuesValue) break;
- end = i + 1;
- }
- return end;
-}
-
-function setManagedCorsOrigins(
- lines: string[],
- restPort: number,
- viewerPort: number,
-): void {
- const block = workerBlock(lines, "iii-http");
- if (!block) return;
- const originsIndex = lines.findIndex(
- (line, index) =>
- index > block.start &&
- index < block.end &&
- line.trim().startsWith("allowed_origins:"),
- );
- if (originsIndex === -1) return;
- const indent = lines[originsIndex]!.match(/^\s*/)?.[0] ?? " ";
- const valueEnd = mappingValueEnd(lines, originsIndex, block.end);
- lines.splice(originsIndex + 1, valueEnd - originsIndex - 1);
- lines[originsIndex] =
- `${indent}allowed_origins: [` +
- `"http://localhost:${restPort}", ` +
- `"http://localhost:${viewerPort}", ` +
- `"http://127.0.0.1:${restPort}", ` +
- `"http://127.0.0.1:${viewerPort}"]`;
-}
-
-export function renderEngineConfig(
- template: string,
- options: EngineConfigOptions,
-): string {
- if (options.stateBackend?.kind === "redis" && !options.stateBackend.redisUrl) {
- throw new Error(
- "AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL to be set (e.g. redis://localhost:6379).",
- );
- }
- if (
- options.stateBackend?.kind === "redis" &&
- UNSAFE_REDIS_URL_CHARS.test(options.stateBackend.redisUrl ?? "")
- ) {
- throw new Error(
- "AGENTMEMORY_REDIS_URL contains a single quote or a control character, which breaks the engine config once the engine expands it. Percent-encode those characters in the URL (for example a single quote as %27).",
- );
- }
-
- const rendered = template
- .replace(
- "file_path: ./data/state_store.db",
- `file_path: ${yamlSingleQuote(join(options.dataDir, "state_store.db"))}`,
- )
- .replace(
- "file_path: ./data/stream_store",
- `file_path: ${yamlSingleQuote(join(options.dataDir, "stream_store"))}`,
- );
-
- const usesRedis = options.stateBackend?.kind === "redis";
- const lines = rendered.split("\n");
- setFileStoreSaveInterval(lines, "iii-state", options.saveIntervalMs);
- setFileStoreSaveInterval(lines, "iii-stream", options.saveIntervalMs);
- if (options.ports) {
- setWorkerPort(lines, "iii-http", options.ports.restPort);
- setWorkerPort(lines, "iii-stream", options.ports.streamPort);
- setWorkerPort(lines, "iii-worker-manager", options.ports.enginePort);
- setManagedCorsOrigins(lines, options.ports.restPort, options.ports.viewerPort);
- }
- if (usesRedis) {
- replaceKvAdapterWithRedis(lines, "iii-state");
- replaceKvAdapterWithRedis(lines, "iii-stream");
- }
- return lines.join("\n");
+ ])];
}
diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts
index 843c1d15..a9979a5e 100644
--- a/src/cli/engine-install.ts
+++ b/src/cli/engine-install.ts
@@ -11,14 +11,14 @@ export const III_INSTALL_SPAWN_TIMEOUT_MS =
type ChecksumTable = Readonly<Record<string, Readonly<Record<string, string>>>>;
export const III_RELEASE_SHA256: ChecksumTable = {
- "0.22.1": {
- "iii-aarch64-apple-darwin.tar.gz": "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4",
- "iii-x86_64-apple-darwin.tar.gz": "6d33940db2d3ad6a9aef9837aa5b89bf5c5e4acd0679e8178fec258af229d7e1",
- "iii-x86_64-unknown-linux-gnu.tar.gz": "34d4bd2ec1873e6114bb836be7db9cb3f410d0d63353d240917f0bc9c30df13b",
- "iii-aarch64-unknown-linux-gnu.tar.gz": "87efc60210c1580ef2e11b13c679a4dad91917a9d80f737c5ba7e3475b3ca413",
- "iii-armv7-unknown-linux-gnueabihf.tar.gz": "af5dfc45149678c647e5adaca55c055428eebfa73d65884b052c30c98abcfd19",
- "iii-x86_64-pc-windows-msvc.zip": "d862bf7cf1e864f3290c8a6fc17c308c6ecac097cb2666e4a739efc0040aae96",
- "iii-aarch64-pc-windows-msvc.zip": "4777a48cee3fc1a742daee929e3d943df09e4ddd3357d27a33d31c9dc9e520ac",
+ "0.25.0": {
+ "iii-aarch64-apple-darwin.tar.gz": "5f23087a41ce1cf86f9859d2f430d1809a1e048094e69b1df0cdf1ebefc2a985",
+ "iii-x86_64-apple-darwin.tar.gz": "e2ac4ef109ddbf459b4683171c6b5b9c8366b16dac2e1f8c4fe08b4a4e19d49a",
+ "iii-x86_64-unknown-linux-gnu.tar.gz": "4c4d14063eb55d79663db553e960497731420df6d78eca3aafe670e2fbaba8e2",
+ "iii-aarch64-unknown-linux-gnu.tar.gz": "5e52d4738a0beb609f4d32970d37be7c00d4848ee9d06300248498a00ea4bf0e",
+ "iii-armv7-unknown-linux-gnueabihf.tar.gz": "9ee840351ff62c889b929b618f8cbb2d66d616cecf82cde7c26d4618aa137508",
+ "iii-x86_64-pc-windows-msvc.zip": "b80ea5c3408879380b6ce95f7b2855ce161d68642aeec8f7b54f104794cbb322",
+ "iii-aarch64-pc-windows-msvc.zip": "2b1e222b90ee18ed143186e8b307d8ad2076f44ea00fa7a7d071bd3c87cde002",
},
};
diff --git a/src/cli/engine-launch.ts b/src/cli/engine-launch.ts
index a5b980d8..1b514459 100644
--- a/src/cli/engine-launch.ts
+++ b/src/cli/engine-launch.ts
@@ -1,227 +1,9 @@
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import {
- renderEngineConfig,
- type EngineConfigOptions,
-} from "./engine-config.js";
-
-export function agentmemoryHome(home: string): string {
- return join(home, ".agentmemory");
-}
+import { join } from "node:path";
export function runtimeConfigPath(dataDir: string): string {
return join(dataDir, "iii-config.runtime.yaml");
}
-export function dockerProjectName(restPort: number): string {
- return `agentmemory-${restPort}`;
-}
-
-export function dockerComposeArgs(
- composeFile: string,
- projectName: string | undefined,
- command: string[],
-): string[] {
- return [
- "compose",
- ...(projectName ? ["-p", projectName] : []),
- "-f",
- composeFile,
- ...command,
- ];
-}
-
-export function isBundledConfig(configPath: string, packageDir: string): boolean {
- const resolved = resolve(configPath);
- return (
- resolved === resolve(join(packageDir, "iii-config.yaml")) ||
- resolved === resolve(join(packageDir, "..", "iii-config.yaml"))
- );
-}
-
-export function resolveEngineCwd(
- configPath: string,
- invocationCwd: string,
- home: string,
- bundledConfig = false,
-): string {
- if (bundledConfig) return agentmemoryHome(home);
- const absoluteConfigPath = isAbsolute(configPath)
- ? configPath
- : resolve(invocationCwd, configPath);
- return dirname(absoluteConfigPath);
-}
-
-function indentation(line: string): number {
- return line.length - line.trimStart().length;
-}
-
-function yamlScalar(value: string): string {
- const trimmed = value.trim();
- const first = trimmed[0];
- const last = trimmed.at(-1);
- if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
- return trimmed.slice(1, -1);
- }
- return trimmed;
-}
-
-function isAgentmemoryExecCommand(
- line: string,
- nodeBin: string,
- workerEntry: string,
-): boolean {
- const match = line.match(/^\s*-\s+(.+?)\s*$/);
- if (!match) return false;
- const command = yamlScalar(match[1]!).replaceAll("\\", "/");
- const explicitCommand = `${nodeBin} ${workerEntry}`.replaceAll("\\", "/");
- return (
- command === explicitCommand ||
- /^(?:node|node\.exe)\s+\.\/dist\/index\.mjs$/.test(command) ||
- /^(?:node|node\.exe)\s+dist\/index\.mjs$/.test(command)
- );
-}
-
-function removeAgentmemoryExecCommand(
- raw: string,
- nodeBin: string,
- workerEntry: string,
-): string {
- const lines = raw.split("\n");
- const output: string[] = [];
- let index = 0;
-
- while (index < lines.length) {
- const line = lines[index]!;
- if (line.trim() !== "- name: iii-exec") {
- output.push(line);
- index++;
- continue;
- }
-
- const blockIndent = indentation(line);
- let blockEnd = index + 1;
- while (blockEnd < lines.length) {
- const candidate = lines[blockEnd]!;
- if (candidate.trim() !== "") {
- const candidateIndent = indentation(candidate);
- if (
- candidateIndent < blockIndent ||
- (candidateIndent === blockIndent && candidate.trim().startsWith("- name: "))
- ) {
- break;
- }
- }
- blockEnd++;
- }
-
- const block = lines.slice(index, blockEnd);
- const execIndex = block.findIndex((candidate) => candidate.trim() === "exec:");
- if (execIndex === -1) {
- output.push(...block);
- index = blockEnd;
- continue;
- }
-
- const execIndent = indentation(block[execIndex]!);
- let execEnd = execIndex + 1;
- while (execEnd < block.length) {
- const candidate = block[execEnd]!;
- if (candidate.trim() !== "" && indentation(candidate) <= execIndent) break;
- execEnd++;
- }
-
- const beforeExec = block.slice(0, execIndex + 1);
- const execLines = block.slice(execIndex + 1, execEnd);
- const afterExec = block.slice(execEnd);
- const remainingExecLines = execLines.filter(
- (candidate) => !isAgentmemoryExecCommand(candidate, nodeBin, workerEntry),
- );
- const removed = remainingExecLines.length !== execLines.length;
- const hasExecCommand = remainingExecLines.some(
- (candidate) => /^\s*-\s+/.test(candidate) && indentation(candidate) > execIndent,
- );
-
- if (!removed) {
- output.push(...block);
- } else if (hasExecCommand) {
- output.push(...beforeExec, ...remainingExecLines, ...afterExec);
- }
- index = blockEnd;
- }
-
- return output.join("\n");
-}
-
-export function rewriteBundledConfig(
- raw: string,
- home: string,
- nodeBin: string,
- workerEntry: string,
- options?: EngineConfigOptions,
-): string {
- const rendered = renderEngineConfig(raw, {
- dataDir: options?.dataDir ?? join(agentmemoryHome(home), "data"),
- ...(options?.ports ? { ports: options.ports } : {}),
- ...(options?.stateBackend ? { stateBackend: options.stateBackend } : {}),
- ...(options?.saveIntervalMs !== undefined ? { saveIntervalMs: options.saveIntervalMs } : {}),
- });
- return removeAgentmemoryExecCommand(rendered, nodeBin, workerEntry);
-}
-
-export interface DataMigration {
- from: string;
- to: string;
-}
-
-export function legacyDataMigrations(
- invocationCwd: string,
- home: string,
- resolvedDataDir = join(agentmemoryHome(home), "data"),
-): DataMigration[] {
- return [
- {
- from: join(invocationCwd, "data", "state_store.db"),
- to: join(resolvedDataDir, "state_store.db"),
- },
- {
- from: join(invocationCwd, "data", "stream_store"),
- to: join(resolvedDataDir, "stream_store"),
- },
- ];
-}
-
-export const ENGINE_MALLOC_ARENA_MAX = "2";
-
-export function engineChildEnv(
- base: NodeJS.ProcessEnv,
- platform: NodeJS.Platform = process.platform,
-): NodeJS.ProcessEnv {
- const env: NodeJS.ProcessEnv = { ...base, III_TELEMETRY_ENABLED: base["III_TELEMETRY_ENABLED"] ?? "false" };
- if (platform === "linux" && !base.MALLOC_ARENA_MAX) {
- env.MALLOC_ARENA_MAX = ENGINE_MALLOC_ARENA_MAX;
- }
- return env;
-}
-
-export type LaunchRenderFailure =
- | { fatal: true; message: string }
- | { fatal: false };
-
-export function resolveLaunchRenderFailure(
- stateBackendKind: "file" | "redis",
- err: unknown,
-): LaunchRenderFailure {
- if (stateBackendKind !== "redis") return { fatal: false };
- const reason = err instanceof Error ? err.message : String(err);
- return {
- fatal: true,
- message:
- `Failed to render the Redis state backend into the engine config: ${reason} ` +
- "Refusing to start the engine, since it would silently fall back to the file (or in-memory) store instead of Redis. " +
- "Fix the config or unset AGENTMEMORY_STATE_BACKEND to use the default file store.",
- };
-}
-
const CREDENTIAL_URL_PATTERN = /:\/\/[^@\s/]*@/g;
export function redactCredentialUrls(text: string): string {
diff --git a/src/cli/legacy-docker-state.ts b/src/cli/legacy-docker-state.ts
new file mode 100644
index 00000000..a1d50182
--- /dev/null
+++ b/src/cli/legacy-docker-state.ts
@@ -0,0 +1,34 @@
+export interface LegacyDockerEngineState {
+ kind: "docker";
+ composeFile?: string;
+ projectName?: string;
+ containerId?: string;
+ restPort?: number;
+}
+
+function shellQuote(value: string): string {
+ return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+
+export function legacyDockerStopCommand(state: LegacyDockerEngineState): string {
+ const project = state.projectName?.trim();
+ const composeFile = state.composeFile?.trim();
+ if (composeFile) {
+ return `docker compose${project ? ` -p ${shellQuote(project)}` : ""} -f ${shellQuote(composeFile)} stop`;
+ }
+ if (project) return `docker compose -p ${shellQuote(project)} stop`;
+ if (state.containerId?.trim()) return `docker stop ${shellQuote(state.containerId.trim())}`;
+ return "Cannot construct a stop command: legacy lifecycle state has no Compose file, project, or container ID.";
+}
+
+export function legacyDockerStateMessage(state: LegacyDockerEngineState): string {
+ const port = state.restPort && Number.isFinite(state.restPort)
+ ? state.restPort
+ : Number(state.projectName?.match(/^agentmemory-(\d+)$/)?.[1] ?? 3111);
+ return [
+ `This installation was started by an older Docker-based agentmemory CLI (REST port ${port}); Docker lifecycle management is no longer part of this CLI.`,
+ "Stop the old container explicitly before switching to Worker Compose:",
+ ` ${legacyDockerStopCommand(state)}`,
+ "The legacy lifecycle state is preserved; no container or data was changed.",
+ ].join("\n");
+}
diff --git a/src/cli/readiness.ts b/src/cli/readiness.ts
index e957af9c..89e7fcb4 100644
--- a/src/cli/readiness.ts
+++ b/src/cli/readiness.ts
@@ -30,6 +30,8 @@ export function startupTimeouts(env: NodeJS.ProcessEnv = process.env): {
};
}
+// Used only for unattached native engine state persisted by legacy installs;
+// new installs use Worker Compose.
export function configStartsAgentmemoryWorker(raw: string, workerEntry: string, engineCwd?: string): boolean {
const lines = raw.split(/\r?\n/);
let workerIndent: number | undefined;
@@ -94,6 +96,16 @@ export function startupDeadline(timeoutMs: number): StartupDeadline {
return { remaining: () => Math.max(0, deadline - performance.now()) };
}
+/** Probe the loopback REST listener owned by this managed Compose instance.
+ * Client commands may honor AGENTMEMORY_URL, but startup readiness must always
+ * target the endpoint that this process asked Compose to create. */
+export function managedComposeReadinessUrl(restPort: number): string {
+ if (!Number.isInteger(restPort) || restPort < 1 || restPort > 65535) {
+ throw new Error(`Invalid managed Compose REST port: ${restPort}`);
+ }
+ return `http://127.0.0.1:${restPort}`;
+}
+
export async function withinStartupDeadline<T>(
deadline: StartupDeadline,
work: (signal: AbortSignal) => Promise<T>,
@@ -124,23 +136,27 @@ export async function withinStartupDeadline<T>(
export async function waitForReadiness(
deadline: StartupDeadline,
probe: (signal: AbortSignal) => Promise<boolean>,
- options: { intervalMs?: number; stopped?: () => boolean } = {},
+ options: { intervalMs?: number; probeTimeoutMs?: number; stopped?: () => boolean } = {},
): Promise<boolean> {
while (deadline.remaining() > 0 && !options.stopped?.()) {
- const result = await withinStartupDeadline(deadline, probe, 2000).catch(() => ({ completed: false as const }));
+ const result = await withinStartupDeadline(deadline, probe, options.probeTimeoutMs ?? 1000).catch(() => ({ completed: false as const }));
if (options.stopped?.()) return false;
if (result.completed && result.value) return true;
const remaining = deadline.remaining();
if (remaining <= 0) break;
- await new Promise((resolve) => setTimeout(resolve, Math.min(options.intervalMs ?? 250, remaining)));
+ const pause = Math.min(options.intervalMs ?? 250, remaining);
+ if (pause > 0) await new Promise((resolve) => setTimeout(resolve, pause));
}
return false;
}
export async function probeEngine(base: string, signal: AbortSignal): Promise<boolean> {
+ if (signal.aborted) return false;
const response = await fetch(`${base}/`, { signal });
+ // The engine's root path is normally 404 until the worker registers routes;
+ // a response of any HTTP status proves the listener is reachable. Canceling
+ // the body prevents a slow/streaming route from holding a probe open.
void response.body?.cancel().catch(() => {});
- // The engine's root path is normally 404 until the worker registers routes.
return true;
}
@@ -149,6 +165,7 @@ export async function probeWorker(
signal: AbortSignal,
onViewerPort?: (port: number) => void,
): Promise<boolean> {
+ if (signal.aborted) return false;
const response = await fetch(`${base}/agentmemory/livez`, { signal });
if (!response.ok) {
void response.body?.cancel().catch(() => {});
diff --git a/src/config.ts b/src/config.ts
index bfc95390..54b9b11d 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -11,21 +11,18 @@ import type {
TeamConfig,
} from "./types.js";
+// Import-side ceiling for observations in a single session (enforced by mem::import).
+// This is independent of MAX_OBS_PER_SESSION, which controls runtime writes.
+export const MAX_IMPORT_OBS_PER_SESSION = 5_000;
+
function safeParseInt(value: string | undefined, fallback: number): number {
if (!value) return fallback;
const parsed = parseInt(value, 10);
return Number.isNaN(parsed) ? fallback : parsed;
}
-// Import-side ceiling for observations in a single session (enforced by
-// mem::import). Deliberately NOT named MAX_OBS_PER_SESSION — that env var is
-// the runtime write cap and the two are independent; loadConfig() warns when
-// the runtime cap is raised past this ceiling, which would let a session grow
-// past the point where export→import round-trips can restore the store.
-export const MAX_IMPORT_OBS_PER_SESSION = 5_000;
-
-const DATA_DIR = join(homedir(), ".agentmemory");
-const ENV_FILE = join(DATA_DIR, ".env");
+const DATA_DIR = process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
+const ENV_FILE = process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env");
let warnPremiumModelShown = false;
let providerNoticeShown = false;
@@ -212,50 +209,35 @@ export function loadConfig(): AgentMemoryConfig {
const provider = detectProvider(env);
- // Port quartet: REST is the anchor; streams/engine derive from it
- // unless individually overridden. Default anchor 3111 yields the
- // canonical 3112 streams / 49134 engine pair, but `III_REST_PORT=3211`
- // auto-picks 3212 + 49234 so a second instance doesn't collide.
+ // REST is the anchor; viewer and engine ports derive from it unless individually overridden.
const restPort = parseInt(env["III_REST_PORT"] || "3111", 10) || 3111;
- const streamsPort =
- parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) ||
- restPort + 1;
const viewerPort =
parseInt(env["III_VIEWER_PORT"] || "", 10) || restPort + 2;
const engineUrl =
env["III_ENGINE_URL"] ||
+ env["III_URL"] ||
`ws://localhost:${
parseInt(env["III_ENGINE_PORT"] || "", 10) || restPort + 46023
}`;
- const maxObservationsPerSession = safeParseInt(
- env["MAX_OBS_PER_SESSION"],
- 500,
- );
+ const maxObservationsPerSession = safeParseInt(env["MAX_OBS_PER_SESSION"], 500);
if (
!obsCapImportCeilingWarned &&
- (maxObservationsPerSession === 0 ||
- maxObservationsPerSession > MAX_IMPORT_OBS_PER_SESSION)
+ (maxObservationsPerSession === 0 || maxObservationsPerSession > MAX_IMPORT_OBS_PER_SESSION)
) {
obsCapImportCeilingWarned = true;
- const capDesc =
- maxObservationsPerSession === 0
- ? "uncapped (0)"
- : String(maxObservationsPerSession);
+ const capDesc = maxObservationsPerSession === 0 ? "uncapped (0)" : String(maxObservationsPerSession);
process.stderr.write(
`[agentmemory] WARNING: MAX_OBS_PER_SESSION is ${capDesc}, above the ` +
- `${MAX_IMPORT_OBS_PER_SESSION}-per-session import ceiling ` +
- `(MAX_IMPORT_OBS_PER_SESSION). Sessions past that ceiling make every ` +
- `mem::export -> mem::import restore fail wholesale. Keep ` +
- `MAX_OBS_PER_SESSION at or below ${MAX_IMPORT_OBS_PER_SESSION} if you ` +
- `rely on export/import backups.\n`,
+ `${MAX_IMPORT_OBS_PER_SESSION}-per-session import ceiling (MAX_IMPORT_OBS_PER_SESSION). ` +
+ `Sessions past that ceiling make every mem::export -> mem::import restore fail wholesale. ` +
+ `Keep MAX_OBS_PER_SESSION at or below ${MAX_IMPORT_OBS_PER_SESSION} if you rely on export/import backups.\n`,
);
}
return {
engineUrl,
restPort,
- streamsPort,
viewerPort,
provider,
tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000),
@@ -511,26 +493,6 @@ export function getFollowupWindowSeconds(): number {
);
}
-const VIEWER_STREAM_MAX_DEFAULT = 500;
-const VIEWER_STREAM_MAX_FLOOR = 200;
-
-function parseExactInt(value: string | undefined, fallback: number): number {
- if (!value) return fallback;
- const trimmed = value.trim();
- if (!/^-?\d+$/.test(trimmed)) return fallback;
- const parsed = Number(trimmed);
- return Number.isSafeInteger(parsed) ? parsed : fallback;
-}
-
-export function getViewerStreamMax(): number {
- const parsed = parseExactInt(
- getMergedEnv()["AGENTMEMORY_VIEWER_STREAM_MAX"],
- VIEWER_STREAM_MAX_DEFAULT,
- );
- if (parsed < 0) return VIEWER_STREAM_MAX_DEFAULT;
- return Math.max(parsed, VIEWER_STREAM_MAX_FLOOR);
-}
-
export function isConsolidationEnabled(): boolean {
const env = getMergedEnv();
const explicit = env["CONSOLIDATION_ENABLED"];
@@ -599,9 +561,18 @@ export function getIndexSaveIntervalMs(): number {
return raw > 0 ? raw : INDEX_SAVE_INTERVAL_DEFAULT_MS;
}
-export function getStateSaveIntervalMs(): number | undefined {
- const raw = safeParseInt(getMergedEnv()["AGENTMEMORY_STATE_SAVE_INTERVAL_MS"], 0);
- return raw > 0 ? raw : undefined;
+export const STATE_SAVE_INTERVAL_DEFAULT_MS = 2000;
+export const STATE_SAVE_INTERVAL_MIN_MS = 100;
+export const STATE_SAVE_INTERVAL_MAX_MS = 3_600_000;
+
+export function getStateSaveIntervalMs(): number {
+ const value = getMergedEnv()["AGENTMEMORY_STATE_SAVE_INTERVAL_MS"];
+ if (value === undefined || value.trim() === "") return STATE_SAVE_INTERVAL_DEFAULT_MS;
+ if (!/^\d+$/.test(value.trim())) return STATE_SAVE_INTERVAL_DEFAULT_MS;
+ const raw = Number(value);
+ return Number.isSafeInteger(raw) && raw >= STATE_SAVE_INTERVAL_MIN_MS && raw <= STATE_SAVE_INTERVAL_MAX_MS
+ ? raw
+ : STATE_SAVE_INTERVAL_DEFAULT_MS;
}
export const VECTOR_BUCKET_SIZE_DEFAULT = 500;
diff --git a/src/functions/audit.ts b/src/functions/audit.ts
index 2c778a2a..5726e733 100644
--- a/src/functions/audit.ts
+++ b/src/functions/audit.ts
@@ -1,5 +1,4 @@
import { stat, readFile } from "node:fs/promises";
-import { homedir } from "node:os";
import { join } from "node:path";
import type { AuditEntry, AuditMigrationState, AuditQueryResult } from "../types.js";
import { KV, generateId } from "../state/schema.js";
@@ -90,7 +89,7 @@ async function auditMigrationDeleteDelayMs(): Promise<number> {
const dataDir = getEnvVar("AGENTMEMORY_DATA_DIR");
if (!dataDir) return ENGINE_DEFAULT_SAVE_INTERVAL_MS * AUDIT_MIGRATION_DELETE_WAIT_INTERVALS;
const configTexts: string[] = [];
- for (const path of engineStateConfigPaths(join(homedir(), ".agentmemory"), runtimeConfigPath(dataDir))) {
+ for (const path of engineStateConfigPaths(dataDir, runtimeConfigPath(dataDir))) {
try {
configTexts.push(await readFile(path, "utf-8"));
} catch {}
diff --git a/src/functions/capture.ts b/src/functions/capture.ts
index e945eff1..63561e48 100644
--- a/src/functions/capture.ts
+++ b/src/functions/capture.ts
@@ -165,7 +165,7 @@ export function serverDurableAfterMs(): number {
const configTexts: string[] = [];
const dataDir = getEnvVar("AGENTMEMORY_DATA_DIR");
if (dataDir) {
- for (const path of engineStateConfigPaths(join(homedir(), ".agentmemory"), runtimeConfigPath(dataDir))) {
+ for (const path of engineStateConfigPaths(dataDir, runtimeConfigPath(dataDir))) {
try {
configTexts.push(readFileSync(path, "utf-8"));
} catch {}
diff --git a/src/functions/compress.ts b/src/functions/compress.ts
index 27138033..89a253c8 100644
--- a/src/functions/compress.ts
+++ b/src/functions/compress.ts
@@ -1,8 +1,8 @@
-import { TriggerAction, type IIIClient } from "iii-sdk";
+import type { IIIClient } from "iii-sdk";
import { readFileSync } from "node:fs";
import { isManagedImagePath } from "../utils/image-store.js";
import type { RawObservation, CompressedObservation, MemoryProvider, ObservationCompression, Session } from "../types.js";
-import { KV, STREAM } from "../state/schema.js";
+import { KV } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
import { COMPRESSION_SYSTEM, buildCompressionPrompt } from "../prompts/compression.js";
import { VISION_DESCRIPTION_PROMPT } from "../prompts/vision.js";
@@ -14,6 +14,7 @@ import { scoreCompression } from "../eval/quality.js";
import { compressWithRetry } from "../eval/self-correct.js";
import type { MetricsStore } from "../eval/metrics-store.js";
import { logger } from "../logger.js";
+import { emitLiveEvent } from "../viewer/live-events.js";
import { withoutObservationSource } from "./observation-source.js";
import { budgetLiveObservationSource } from "./observation-source-budget.js";
import { buildSyntheticCompression } from "./compress-synthetic.js";
@@ -204,15 +205,11 @@ export function registerCompressFunction(
const published = await withKeyedLock(`obs:${sessionId}`, async () => {
const current = await kv.get<StoredObservation>(KV.observations(sessionId), observationId);
if (!current || observationRevision(current) !== committedRevision || !await matchesScope(data, current)) return false;
- await sdk.trigger({
- function_id: "stream::send",
- payload: {
- stream_name: STREAM.name, group_id: STREAM.viewerGroup,
- id: `compressed-${observationId}`, type: "compressed_observation",
- data: { type: "compressed", observation: withoutObservationSource(compressed), sessionId },
- },
- action: TriggerAction.Void(),
- }).catch(() => {});
+ emitLiveEvent({
+ id: `compressed-${observationId}`,
+ type: "compressed_observation",
+ data: { type: "compressed", observation: withoutObservationSource(compressed), sessionId },
+ });
return true;
});
if (!published) return { success: false, error: "observation_changed", skipped: true, retryable: false };
diff --git a/src/functions/observe.ts b/src/functions/observe.ts
index be320266..97407113 100644
--- a/src/functions/observe.ts
+++ b/src/functions/observe.ts
@@ -2,9 +2,9 @@ import { TriggerAction, type IIIClient } from "iii-sdk";
import type { RawObservation, CompressedObservation, HookPayload, Origin, Session } from "../types.js";
const TOOL_HOOKS = new Set(["pre_tool_use", "post_tool_use", "post_tool_failure"]);
-import { KV, STREAM, generateId } from "../state/schema.js";
+import { KV, generateId } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
-import { trackViewerStreamItem, pruneViewerStreamIfDue } from "../state/viewer-stream.js";
+import { emitLiveEvent } from "../viewer/live-events.js";
import { addSessionToProjectIndex } from "../state/session-index.js";
import { indexObservationSession } from "../state/obs-index.js";
import { scrubRecord } from "./privacy.js";
@@ -293,16 +293,10 @@ export function registerObserveFunction(
}
if (livePrompt) await recordLivePrompt(kv, payload.sessionId, livePrompt, promptRef);
- await sdk.trigger({
- function_id: "stream::send",
- payload: {
- stream_name: STREAM.name,
- group_id: STREAM.viewerGroup,
- id: `raw-${obsId}`,
- type: "raw_observation",
- data: { type: "raw", observation: raw, sessionId: payload.sessionId },
- },
- action: TriggerAction.Void(),
+ emitLiveEvent({
+ id: `raw-${obsId}`,
+ type: "raw_observation",
+ data: { type: "raw", observation: raw, sessionId: payload.sessionId },
});
const session = existingSession;
@@ -383,21 +377,15 @@ export function registerObserveFunction(
synthetic.title + " " + (synthetic.narrative || ""),
{ kind: "synthetic", logId: synthetic.id },
);
- await sdk.trigger({
- function_id: "stream::set",
- payload: {
- stream_name: STREAM.name,
- group_id: STREAM.viewerGroup,
- item_id: obsId,
- data: {
- type: "compressed",
- observation: withoutObservationSource(synthetic),
- sessionId: payload.sessionId,
- },
+ emitLiveEvent({
+ id: `compressed-${obsId}`,
+ type: "compressed_observation",
+ data: {
+ type: "compressed",
+ observation: withoutObservationSource(synthetic),
+ sessionId: payload.sessionId,
},
});
- trackViewerStreamItem(obsId);
- void pruneViewerStreamIfDue(sdk).catch(() => {});
if (autoCompress) {
afterKeyedLock(`obs:${payload.sessionId}`, async () => {
diff --git a/src/functions/status.ts b/src/functions/status.ts
index dfbe31b2..9192c9de 100644
--- a/src/functions/status.ts
+++ b/src/functions/status.ts
@@ -44,10 +44,10 @@ export interface GraphStatsInput {
export interface StatusInputs {
now: Date;
version: string;
- engineVersion: string;
+ enginePinnedVersion: string;
uptimeSeconds: number;
stateBackend: "file" | "redis";
- ports: { rest: number | null; streams: number | null; viewer: number | null };
+ ports: { rest: number | null; viewer: number | null };
health: {
status?: string;
alerts?: string[];
@@ -104,7 +104,7 @@ export interface StatusReport {
checkedAt: string;
service: {
version: string;
- engineVersion: string;
+ enginePinnedVersion: string;
uptimeSeconds: number;
stateBackend: StatusInputs["stateBackend"];
stateStore: { ok: boolean; latencyMs?: number } | null;
@@ -181,13 +181,7 @@ export function describeHealthAlert(slug: string): { level: "warn" | "error"; me
fix: "It usually clears after an import or index rebuild finishes. If it persists, restart agentmemory.",
};
}
- if (slug === "stream_relay_down") {
- return {
- level: "warn",
- message: "Live updates are not reaching the viewer: the engine stopped relaying stream events, which happens after Redis restarts or drops the connection. Data is still saved.",
- fix: "Restart agentmemory (npx @agentmemory/agentmemory stop, then start) so the engine subscribes to Redis again, then reload the viewer.",
- };
- }
+
if (slug === "connection_reconnecting") {
return {
level: "warn",
@@ -504,7 +498,7 @@ export function evaluateStatus(input: StatusInputs): StatusReport {
checkedAt: input.now.toISOString(),
service: {
version: input.version,
- engineVersion: input.engineVersion,
+ enginePinnedVersion: input.enginePinnedVersion,
uptimeSeconds: input.uptimeSeconds,
stateBackend: input.stateBackend,
stateStore: input.stateStore ?? null,
@@ -846,7 +840,7 @@ a{color:inherit}
@media (max-width:640px){th{width:110px}table.list{table-layout:fixed}table.list th,table.list td{padding:6px 4px;font-size:12px}}
</style></head><body><main>
<header><h1>agentmemory</h1><span class="badge ${report.status}">${report.status}</span>
-<span class="meta">v${escapeHtml(report.service.version)} · engine ${escapeHtml(report.service.engineVersion)} · checked ${escapeHtml(report.checkedAt)} · <a href="?format=json">json</a></span></header>
+<span class="meta">v${escapeHtml(report.service.version)} · engine pinned ${escapeHtml(report.service.enginePinnedVersion)} · checked ${escapeHtml(report.checkedAt)} · <a href="?format=json">json</a></span></header>
<p class="lead ${report.status}">${escapeHtml(report.headline)}</p>
<p class="live">A snapshot from when this page loaded. <a href="${escapeHtml(viewerUrl)}">Open the live version in the viewer &rarr;</a> From a terminal: <code>curl -s ${escapeHtml(CURL_AUTH_HEADER)} ${ports.rest ? `http://localhost:${escapeHtml(ports.rest)}` : ""}/agentmemory/status</code> returns this report as JSON.</p>
<h2>Problems</h2><ul class="problems">${problems}</ul>
@@ -855,7 +849,6 @@ ${row("Engine connection", escapeHtml(report.health?.connectionState ?? "unknown
${row("Uptime", escapeHtml(formatDuration(report.service.uptimeSeconds)))}
${row("State backend", escapeHtml(report.service.stateBackend))}
${row("REST port", escapeHtml(ports.rest ?? "unknown"))}
-${row("Streams port", escapeHtml(ports.streams ?? "unknown"))}
${row("Viewer port", escapeHtml(ports.viewer ?? "not running"))}
</table>
<h2>LLM and embeddings</h2><table>
diff --git a/src/health/monitor.ts b/src/health/monitor.ts
index 71b7733a..2e4f0e06 100644
--- a/src/health/monitor.ts
+++ b/src/health/monitor.ts
@@ -4,12 +4,11 @@ import type { HealthSnapshot } from "../types.js";
import type { StateKV } from "../state/kv.js";
import { KV } from "../state/schema.js";
import { evaluateHealth } from "./thresholds.js";
-import type { StreamRelayProbe } from "./stream-relay-probe.js";
+import { getLiveEventsStats } from "../viewer/live-events.js";
export function registerHealthMonitor(
sdk: IIIClient,
kv: StateKV,
- options: { streamRelayProbe?: StreamRelayProbe } = {},
): { stop: () => void } {
let connectionState = "connected";
let prevCpuUsage = process.cpuUsage();
@@ -66,13 +65,9 @@ export function registerHealthMonitor(
kvConnectivity = { status: "error", error: "kv_probe_failed", latencyMs: Math.round((performance.now() - kvStart) * 100) / 100 };
}
- const streamRelay = options.streamRelayProbe
- ? await options.streamRelayProbe.check().catch(() => "unknown" as const)
- : undefined;
-
const snapshot: HealthSnapshot = {
connectionState,
- ...(streamRelay ? { streamRelay } : {}),
+ liveEvents: getLiveEventsStats(),
workers,
memory: {
heapUsed: mem.heapUsed,
@@ -111,7 +106,6 @@ export function registerHealthMonitor(
return {
stop: () => {
clearInterval(interval);
- options.streamRelayProbe?.close();
},
};
}
diff --git a/src/health/stream-relay-probe.ts b/src/health/stream-relay-probe.ts
deleted file mode 100644
index 7350744c..00000000
--- a/src/health/stream-relay-probe.ts
+++ /dev/null
@@ -1,140 +0,0 @@
-import type { IIIClient } from "iii-sdk";
-import { STREAM } from "../state/schema.js";
-
-export type StreamRelayState = "ok" | "down" | "unknown";
-
-export interface StreamRelayProbe {
- check(): Promise<StreamRelayState>;
- close(): void;
-}
-
-interface ProbeSocket {
- readyState: number;
- onopen: (() => void) | null;
- onmessage: ((event: { data: unknown }) => void) | null;
- onclose: (() => void) | null;
- onerror: (() => void) | null;
- send(data: string): void;
- close(): void;
-}
-
-export interface StreamRelayProbeOptions {
- url: string;
- timeoutMs?: number;
- createSocket?: (url: string) => ProbeSocket;
-}
-
-const PROBE_GROUP = "relay-probe";
-const PROBE_EVENT = "relay.probe";
-const OPEN = 1;
-
-function defaultSocket(url: string): ProbeSocket {
- return new WebSocket(url) as unknown as ProbeSocket;
-}
-
-export function createStreamRelayProbe(
- sdk: IIIClient,
- options: StreamRelayProbeOptions,
-): StreamRelayProbe {
- const timeoutMs = options.timeoutMs ?? 5000;
- const createSocket = options.createSocket ?? defaultSocket;
- let socket: ProbeSocket | null = null;
- let ready: Promise<boolean> | null = null;
- const waiters = new Map<string, () => void>();
-
- function connect(): Promise<boolean> {
- if (socket && socket.readyState === OPEN && ready) return ready;
- try {
- socket?.close();
- } catch {}
- let current: ProbeSocket;
- try {
- current = createSocket(options.url);
- } catch {
- socket = null;
- ready = null;
- return Promise.resolve(false);
- }
- socket = current;
- ready = new Promise<boolean>((resolve) => {
- const timer = setTimeout(() => resolve(false), timeoutMs);
- current.onopen = () => {
- clearTimeout(timer);
- current.send(
- JSON.stringify({
- type: "join",
- data: {
- subscriptionId: `relay-probe-${process.pid}-${Date.now()}`,
- streamName: STREAM.name,
- groupId: PROBE_GROUP,
- },
- }),
- );
- resolve(true);
- };
- current.onerror = () => {
- clearTimeout(timer);
- resolve(false);
- };
- current.onclose = () => {
- clearTimeout(timer);
- if (socket === current) {
- socket = null;
- ready = null;
- }
- resolve(false);
- };
- });
- current.onmessage = (event) => {
- try {
- const raw = typeof event.data === "string" ? event.data : String(event.data);
- const nonce = JSON.parse(raw)?.event?.event?.data?.nonce;
- if (typeof nonce === "string") waiters.get(nonce)?.();
- } catch {}
- };
- return ready;
- }
-
- async function check(): Promise<StreamRelayState> {
- if (!(await connect())) return "unknown";
- const nonce = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
- let timer: ReturnType<typeof setTimeout> | undefined;
- const received = new Promise<boolean>((resolve) => {
- waiters.set(nonce, () => resolve(true));
- timer = setTimeout(() => resolve(false), timeoutMs);
- });
- try {
- await sdk.trigger({
- function_id: "stream::send",
- payload: {
- stream_name: STREAM.name,
- group_id: PROBE_GROUP,
- id: nonce,
- type: PROBE_EVENT,
- data: { nonce },
- },
- timeoutMs,
- });
- } catch {
- waiters.delete(nonce);
- clearTimeout(timer);
- return "down";
- }
- const ok = await received;
- waiters.delete(nonce);
- clearTimeout(timer);
- return ok ? "ok" : "down";
- }
-
- return {
- check,
- close() {
- waiters.clear();
- try {
- socket?.close();
- } catch {}
- socket = null;
- ready = null;
- },
- };
-}
diff --git a/src/health/thresholds.ts b/src/health/thresholds.ts
index 70f85a57..509d9a52 100644
--- a/src/health/thresholds.ts
+++ b/src/health/thresholds.ts
@@ -41,10 +41,7 @@ export function evaluateHealth(
degraded = true;
}
- if (snapshot.streamRelay === "down") {
- alerts.push("stream_relay_down");
- degraded = true;
- }
+
if (snapshot.eventLoopLagMs > cfg.eventLoopLagCriticalMs) {
alerts.push(
diff --git a/src/index.ts b/src/index.ts
index 678ac4f0..9727dcc9 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -38,7 +38,6 @@ import { SHUTDOWN_FLUSH_TIMEOUT_MS, SHUTDOWN_HARD_EXIT_MS, runStartupCleanup, se
import { registerPrivacyFunction, withWriteScrubbing } from "./functions/privacy.js";
import { registerObserveFunction } from "./functions/observe.js";
import { registerCaptureFunctions } from "./functions/capture.js";
-import { seedViewerStreamTracker } from "./state/viewer-stream.js";
import { registerImageQuotaCleanup } from "./functions/image-quota-cleanup.js";
import { registerVisionSearchFunctions } from "./functions/vision-search.js";
import { registerSlotsFunctions, isSlotsEnabled, isReflectEnabled } from "./functions/slots.js";
@@ -119,13 +118,13 @@ import { registerReplayFunctions } from "./functions/replay.js";
import { registerApiTriggers } from "./triggers/api.js";
import { registerEventTriggers } from "./triggers/events.js";
import { registerViewerStreamTriggers } from "./triggers/viewer-streams.js";
+import { registerViewerSse } from "./triggers/viewer-sse.js";
import { registerMcpEndpoints } from "./mcp/server.js";
import { getAllTools } from "./mcp/tools-registry.js";
import { startViewerServer } from "./viewer/server.js";
import { MetricsStore } from "./eval/metrics-store.js";
import { DedupMap } from "./functions/dedup.js";
import { registerHealthMonitor } from "./health/monitor.js";
-import { createStreamRelayProbe } from "./health/stream-relay-probe.js";
import { initMetrics, OTEL_CONFIG } from "./telemetry/setup.js";
import { VERSION } from "./version.js";
import { bootLog, bootWarn } from "./logger.js";
@@ -138,6 +137,9 @@ function workerPidfilePath(): string {
return runtimeMetadataPath("worker.pid");
}
function writeWorkerPidfile(): void {
+ // Worker Compose owns the entire process lifecycle. Its supervised container
+ // PID is authoritative; do not create a second ownership record.
+ if (process.env["III_COMPOSE_FILE"]) return;
try {
const p = workerPidfilePath();
mkdirSync(dirname(p), { recursive: true });
@@ -147,6 +149,7 @@ function writeWorkerPidfile(): void {
}
}
function clearWorkerPidfile(): void {
+ if (process.env["III_COMPOSE_FILE"]) return;
try {
unlinkSync(workerPidfilePath());
} catch {}
@@ -226,7 +229,6 @@ async function main() {
bootLog(
`REST API: http://localhost:${config.restPort}/agentmemory/*`,
);
- bootLog(`Streams: ws://localhost:${config.streamsPort}`);
const sdk = withWriteScrubbing(registerWorker(config.engineUrl, {
workerName: "agentmemory",
@@ -446,14 +448,10 @@ async function main() {
registerApiTriggers(sdk, kv, secret, metricsStore, provider);
registerEventTriggers(sdk, kv);
registerViewerStreamTriggers(sdk, kv, { secret, metricsStore, provider });
+ registerViewerSse(sdk);
registerMcpEndpoints(sdk, kv, secret);
- const healthMonitor = registerHealthMonitor(sdk, kv, {
- streamRelayProbe:
- kv.backend === "redis"
- ? createStreamRelayProbe(sdk, { url: `ws://localhost:${config.streamsPort}` })
- : undefined,
- });
+ const healthMonitor = registerHealthMonitor(sdk, kv);
const indexPersistence = new IndexPersistence(kv, vectorIndex, { requireRecoveryPlan: true });
setIndexPersistence(indexPersistence);
@@ -603,7 +601,7 @@ async function main() {
`Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`,
);
bootLog(
- `REST API: 143 endpoints at http://localhost:${config.restPort}/agentmemory/*`,
+ `REST API: 146 endpoints at http://localhost:${config.restPort}/agentmemory/*`,
);
bootLog(
`MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`,
@@ -708,7 +706,6 @@ async function main() {
}, 60 * 60 * 1000);
recentSearchesSweepTimer.unref();
- void seedViewerStreamTracker(sdk, { unorderedListing: kv.backend === "redis" }).catch(() => {});
if (isSessionSweepEnabled()) {
const sessionSweepTimer = setInterval(async () => {
diff --git a/src/secret-store.ts b/src/secret-store.ts
index 4a61c6be..12dc2d9d 100644
--- a/src/secret-store.ts
+++ b/src/secret-store.ts
@@ -5,6 +5,7 @@ import {
mkdirSync,
openSync,
readFileSync,
+ renameSync,
unlinkSync,
writeSync,
} from "node:fs";
@@ -15,7 +16,7 @@ import { join } from "node:path";
const SECRET_KEY = "AGENTMEMORY_SECRET";
export function agentmemoryHomeDir(): string {
- return join(homedir(), ".agentmemory");
+ return process.env["AGENTMEMORY_DATA_DIR"] || join(homedir(), ".agentmemory");
}
export function secretFilePath(): string {
@@ -43,7 +44,7 @@ function unquote(value: string): string {
export function readEnvFileSecret(): string {
let content: unknown;
try {
- content = readFileSync(join(agentmemoryHomeDir(), ".env"), "utf-8");
+ content = readFileSync(process.env["AGENTMEMORY_ENV_FILE"] || join(homedir(), ".agentmemory", ".env"), "utf-8");
} catch {
return "";
}
@@ -61,14 +62,30 @@ export function readEnvFileSecret(): string {
return found;
}
-export function readStoredSecret(): string {
+function readSecretFile(path: string): string {
try {
- return usable(readFileSync(secretFilePath(), "utf-8"));
+ return usable(readFileSync(path, "utf-8"));
} catch {
return "";
}
}
+function legacyDataDirSecretPaths(env: NodeJS.ProcessEnv = process.env): string[] {
+ const dataDir = env["AGENTMEMORY_DATA_DIR"];
+ if (!dataDir) return [];
+ const paths = [join(dataDir, "secret"), join(dataDir, ".hmac"), join(dataDir, "..", ".hmac")];
+ return [...new Set(paths.filter((path) => path !== secretFilePath()))];
+}
+
+export function readStoredSecret(env: NodeJS.ProcessEnv = process.env): string {
+ const canonicalPath = canonicalSecretPath();
+ const localPath = secretFilePath();
+ const legacyPaths = legacyDataDirSecretPaths(env);
+ return readSecretFile(canonicalPath) ||
+ (localPath === canonicalPath ? "" : readSecretFile(localPath)) ||
+ legacyPaths.map(readSecretFile).find(Boolean) || "";
+}
+
export function explicitSecret(env: NodeJS.ProcessEnv = process.env): string {
return usable(env[SECRET_KEY]) || readEnvFileSecret();
}
@@ -92,24 +109,37 @@ export function resolveClientSecret(
if (fromEnv) return fromEnv;
if (env.AGENTMEMORY_CREDENTIAL_MODE === "explicit") return "";
if (!isLoopbackUrl(baseUrl)) return "";
- return readEnvFileSecret() || readStoredSecret();
+ return readEnvFileSecret() || readStoredSecret(env);
}
-export function ensureServerSecret(env: NodeJS.ProcessEnv = process.env): {
- secret: string;
- source: "env" | "file" | "generated";
-} {
- const configured = explicitSecret(env);
- if (configured) return { secret: configured, source: "env" };
- const stored = readStoredSecret();
- if (stored) return { secret: stored, source: "file" };
- const generated = randomBytes(32).toString("hex");
- const path = secretFilePath();
- mkdirSync(agentmemoryHomeDir(), { recursive: true, mode: 0o700 });
+function canonicalSecretPath(): string {
+ return join(homedir(), ".agentmemory", "secret");
+}
+
+function writeSecretFile(path: string, secret: string): void {
+ mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
const staging = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
const fd = openSync(staging, "wx", 0o600);
try {
- writeSync(fd, `${generated}\n`);
+ writeSync(fd, `${secret}\n`);
+ } finally {
+ closeSync(fd);
+ }
+ try {
+ chmodSync(staging, 0o600);
+ renameSync(staging, path);
+ chmodSync(path, 0o600);
+ } finally {
+ try { unlinkSync(staging); } catch {}
+ }
+}
+
+function writeSecretIfAbsent(path: string, secret: string): string {
+ mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+ const staging = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+ const fd = openSync(staging, "wx", 0o600);
+ try {
+ writeSync(fd, `${secret}\n`);
} finally {
closeSync(fd);
}
@@ -118,15 +148,39 @@ export function ensureServerSecret(env: NodeJS.ProcessEnv = process.env): {
linkSync(staging, path);
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
- const raced = readStoredSecret();
- if (!raced) throw err;
- return { secret: raced, source: "file" };
} finally {
- try {
- unlinkSync(staging);
- } catch {}
+ try { unlinkSync(staging); } catch {}
}
- return { secret: generated, source: "generated" };
+ const stored = readSecretFile(path);
+ if (!stored) throw new Error(`Could not read stored API secret at ${path}.`);
+ return stored;
+}
+
+export function ensureServerSecret(env: NodeJS.ProcessEnv = process.env): {
+ secret: string;
+ source: "env" | "file" | "generated";
+} {
+ const configured = explicitSecret(env);
+ if (configured) return { secret: configured, source: "env" };
+
+ const localPath = secretFilePath();
+ const canonicalPath = canonicalSecretPath();
+ const canonical = localPath === canonicalPath ? "" : readSecretFile(canonicalPath);
+ if (canonical) {
+ if (localPath !== canonicalPath && readSecretFile(localPath) !== canonical) {
+ writeSecretFile(localPath, canonical);
+ }
+ return { secret: canonical, source: "file" };
+ }
+
+ const legacy = readSecretFile(localPath) || legacyDataDirSecretPaths(env).map(readSecretFile).find(Boolean) || "";
+ const candidate = legacy || randomBytes(32).toString("hex");
+ const localSecret = writeSecretIfAbsent(localPath, candidate);
+ const secret = localPath === canonicalPath
+ ? localSecret
+ : writeSecretIfAbsent(canonicalPath, localSecret);
+ if (localPath !== canonicalPath && localSecret !== secret) writeSecretFile(localPath, secret);
+ return { secret, source: legacy ? "file" : "generated" };
}
export function bearerHeaders(
diff --git a/src/state/schema.ts b/src/state/schema.ts
index c2b56a0c..03bae2f0 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -70,11 +70,6 @@ export const KV = {
capturePrompts: "mem:capture:prompts",
} as const;
-export const STREAM = {
- name: "mem-live",
- viewerGroup: "viewer",
-} as const;
-
export function generateId(prefix: string): string {
const ts = Date.now().toString(36);
const rand = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
diff --git a/src/state/viewer-stream.ts b/src/state/viewer-stream.ts
deleted file mode 100644
index 612e6f35..00000000
--- a/src/state/viewer-stream.ts
+++ /dev/null
@@ -1,154 +0,0 @@
-import type { IIIClient } from "iii-sdk";
-import { STREAM } from "./schema.js";
-import { generatedIdTime } from "./kv.js";
-import { getViewerStreamMax } from "../config.js";
-import { logger } from "../logger.js";
-
-const PRUNE_BATCH_INTERVAL = 50;
-const DELETE_BATCH_SIZE = 100;
-const UNSHIFT_CHUNK_SIZE = 1000;
-const SEED_TIMEOUT_MS = 5000;
-
-const trackedItemIds: string[] = [];
-const trackedItemIdSet = new Set<string>();
-let writesSincePrune = 0;
-let pruning = false;
-let pruneAgain = false;
-
-export function trackViewerStreamItem(itemId: string): void {
- if (trackedItemIdSet.has(itemId)) return;
- trackedItemIdSet.add(itemId);
- trackedItemIds.push(itemId);
- writesSincePrune += 1;
-}
-
-function unshiftMany(target: string[], items: string[]): void {
- for (let end = items.length; end > 0; end -= UNSHIFT_CHUNK_SIZE) {
- const start = Math.max(0, end - UNSHIFT_CHUNK_SIZE);
- target.splice(0, 0, ...items.slice(start, end));
- }
-}
-
-async function deleteItems(sdk: IIIClient, itemIds: string[]): Promise<string[]> {
- const failedItemIds: string[] = [];
- for (let start = 0; start < itemIds.length; start += DELETE_BATCH_SIZE) {
- const batch = itemIds.slice(start, start + DELETE_BATCH_SIZE);
- const results = await Promise.allSettled(
- batch.map((itemId) =>
- sdk.trigger({
- function_id: "stream::delete",
- payload: {
- stream_name: STREAM.name,
- group_id: STREAM.viewerGroup,
- item_id: itemId,
- },
- }),
- ),
- );
- for (let i = 0; i < results.length; i++) {
- const result = results[i];
- if (result.status === "rejected") {
- logger.warn("Failed to prune viewer stream item", {
- error:
- result.reason instanceof Error
- ? result.reason.message
- : String(result.reason),
- });
- failedItemIds.push(batch[i]);
- }
- }
- }
- return failedItemIds;
-}
-
-async function pruneOverflow(sdk: IIIClient): Promise<void> {
- if (pruning) {
- pruneAgain = true;
- return;
- }
- pruning = true;
- try {
- do {
- pruneAgain = false;
- const overflow = trackedItemIds.length - getViewerStreamMax();
- if (overflow <= 0) break;
- const candidates = trackedItemIds.splice(0, overflow);
- for (const itemId of candidates) trackedItemIdSet.delete(itemId);
- candidates.reverse();
- const failedItemIds = await deleteItems(sdk, candidates);
- if (failedItemIds.length > 0) {
- for (const itemId of failedItemIds) trackedItemIdSet.add(itemId);
- unshiftMany(trackedItemIds, failedItemIds);
- }
- } while (pruneAgain);
- } finally {
- pruning = false;
- }
-}
-
-export async function pruneViewerStreamIfDue(sdk: IIIClient): Promise<void> {
- if (writesSincePrune < PRUNE_BATCH_INTERVAL) return;
- writesSincePrune = 0;
- await pruneOverflow(sdk);
-}
-
-type StoredViewerItem = {
- observation?: { id?: unknown; timestamp?: unknown };
-};
-
-function itemTime(item: StoredViewerItem): number {
- const fromId = generatedIdTime(item?.observation?.id);
- if (fromId !== null) return fromId;
- const raw = item?.observation?.timestamp;
- const parsed = typeof raw === "string" ? Date.parse(raw) : typeof raw === "number" ? raw : NaN;
- return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
-}
-
-function oldestFirst(items: StoredViewerItem[]): StoredViewerItem[] {
- return items
- .map((item, index) => ({ item, index, at: itemTime(item) }))
- .sort((a, b) => (a.at !== b.at ? (a.at < b.at ? -1 : 1) : a.index - b.index))
- .map((entry) => entry.item);
-}
-
-export interface SeedViewerStreamOptions {
- unorderedListing?: boolean;
-}
-
-export async function seedViewerStreamTracker(
- sdk: IIIClient,
- options: SeedViewerStreamOptions = {},
-): Promise<number> {
- let items: StoredViewerItem[];
- try {
- items = await sdk.trigger<unknown, StoredViewerItem[]>({
- function_id: "stream::list",
- payload: { stream_name: STREAM.name, group_id: STREAM.viewerGroup },
- timeoutMs: SEED_TIMEOUT_MS,
- });
- } catch (err) {
- logger.warn("Could not read the viewer stream backlog", {
- error: err instanceof Error ? err.message : String(err),
- });
- return 0;
- }
- if (!Array.isArray(items)) return 0;
- const stored: string[] = [];
- for (const item of options.unorderedListing ? oldestFirst(items) : items) {
- const id = item?.observation?.id;
- if (typeof id !== "string" || trackedItemIdSet.has(id)) continue;
- trackedItemIdSet.add(id);
- stored.push(id);
- }
- unshiftMany(trackedItemIds, stored);
- await pruneOverflow(sdk);
- return stored.length;
-}
-
-export function resetViewerStreamTracker(): void {
- trackedItemIds.length = 0;
- trackedItemIdSet.clear();
- writesSincePrune = 0;
- pruning = false;
- pruneAgain = false;
-}
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 05ec0e65..03dbbe9e 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -53,6 +53,7 @@ import { GraphIndexError } from "../state/graph-retrieval-index.js";
import { registerGraphIndexApi } from "./graph-index-api.js";
import { LESSON_SOURCE_IDS_MAX, normalizeLessonSourceIds } from "../functions/lessons.js";
import { logger } from "../logger.js";
+import { getLiveEventsStats } from "../viewer/live-events.js";
import { isValidEventId } from "../capture/event-id.js";
import { getCaptureController, type CaptureResult } from "../functions/capture.js";
import { withoutObservationSource } from "../functions/observation-source.js";
@@ -416,12 +417,11 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe
return evaluateStatus({
now: new Date(),
version: VERSION,
- engineVersion: III_PINNED_VERSION,
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: Math.round(process.uptime()),
stateBackend: kv.backend === "redis" ? "redis" : "file",
ports: {
rest: config.restPort ?? null,
- streams: config.streamsPort ?? null,
viewer: getViewerSkipped() ? null : (getBoundViewerPort() ?? null),
},
health: health
@@ -554,19 +554,13 @@ export function registerApiTriggers(
},
);
- // Shared instance metadata for livez and health so the two never
- // drift. streamsPort lets the viewer resolve its stream WebSocket
- // target from the server instead of port arithmetic, which broke
- // whenever the viewer bound a fallback port. Config is boot-static,
- // so read it once instead of rebuilding the merged env per request.
+ // Config is boot-static, so read it once rather than rebuilding the merged env per request.
const bootConfig = loadConfig();
- const bootStreamsPort = bootConfig.streamsPort;
setRestOriginPorts(() => [bootConfig.restPort, bootConfig.viewerPort, getBoundViewerPort()]);
const instanceInfo = () => ({
service: "agentmemory",
viewerPort: getBoundViewerPort(),
viewerSkipped: getViewerSkipped(),
- streamsPort: bootStreamsPort,
});
sdk.registerFunction("api::liveness",
@@ -610,7 +604,7 @@ export function registerApiTriggers(
});
sdk.registerFunction("api::health",
- async (req: HttpRequest): Promise<Response> => {
+ async (): Promise<Response> => {
const health = await getLatestHealth(kv);
const functionMetrics = metricsStore ? await metricsStore.getAll() : [];
const circuitBreaker =
@@ -664,7 +658,7 @@ export function registerApiTriggers(
body: renderStatusHtml(report, nonce, { viewerUrl: statusViewerUrl(req, report.service.ports.viewer) }),
};
}
- return { status_code: 200, headers: { "Cache-Control": "no-store" }, body: report };
+ return { status_code: 200, headers: { "Cache-Control": "no-store" }, body: { ...report, liveEvents: getLiveEventsStats() } };
},
);
sdk.registerTrigger({
@@ -1211,7 +1205,7 @@ export function registerApiTriggers(
await clearSessionFinalize(kv, sessionId).catch(() => {});
// Fan out session-stopped lifecycle (non-blocking).
try {
- sdk.trigger({
+ void sdk.trigger({
function_id: "event::session::stopped",
payload: { sessionId },
action: TriggerAction.Void(),
diff --git a/src/triggers/events.ts b/src/triggers/events.ts
index fc6072c5..4c887f5f 100644
--- a/src/triggers/events.ts
+++ b/src/triggers/events.ts
@@ -1,9 +1,8 @@
import { TriggerAction, type IIIClient } from "iii-sdk";
-import type { CompressedObservation, HookPayload, Memory, Session } from "../types.js";
-import { KV, STREAM } from "../state/schema.js";
+import type { CompressedObservation, Memory, Session } from "../types.js";
+import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
-import { addSessionToProjectIndex } from "../state/session-index.js";
-import { withKeyedLock } from "../state/keyed-mutex.js";
+import { emitLiveEvent } from "../viewer/live-events.js";
import { isReflectEnabled } from "../functions/slots.js";
import {
detectLlmProviderKind,
@@ -13,7 +12,6 @@ import {
isConsolidationEnabled,
} from "../config.js";
import { logger } from "../logger.js";
-import { requestSummaryRefresh } from "../functions/summary-state.js";
import { noteMemoryChange, noteSessionChange } from "../state/viewer-counts.js";
// Global marker recording when corpus consolidation last ran, used to debounce
@@ -47,79 +45,6 @@ function consolidationDue(kv: StateKV): Promise<boolean> {
}
export function registerEventTriggers(sdk: IIIClient, kv: StateKV): void {
- sdk.registerFunction(
- "event::session::started",
- async (data: {
- sessionId: string;
- project: string;
- cwd: string;
- agentId?: string;
- }) => {
- const requestAgentId =
- typeof data.agentId === "string" && data.agentId.trim().length > 0
- ? data.agentId.trim().slice(0, 128)
- : undefined;
- const agentId = requestAgentId ?? getAgentId();
- const freshSession: Session = {
- id: data.sessionId,
- project: data.project,
- cwd: data.cwd,
- startedAt: new Date().toISOString(),
- status: "active",
- observationCount: 0,
- ...(agentId ? { agentId } : {}),
- };
- const session = await withKeyedLock(`obs:${data.sessionId}`, async () => {
- const existing = await kv.get<Session>(KV.sessions, data.sessionId);
- const merged: Session = {
- ...freshSession,
- observationCount: existing?.observationCount ?? freshSession.observationCount,
- firstPrompt: existing?.firstPrompt,
- summary: existing?.summary,
- commitShas: existing?.commitShas,
- };
- await kv.set(KV.sessions, data.sessionId, merged);
- return merged;
- });
- await addSessionToProjectIndex(kv, session.project, {
- id: session.id,
- startedAt: session.startedAt,
- ...(session.agentId ? { agentId: session.agentId } : {}),
- }).catch((err) => {
- logger.warn("session index update failed", {
- sessionId: session.id,
- error: err instanceof Error ? err.message : String(err),
- });
- });
- const contextResult = await sdk.trigger<
- { sessionId: string; project: string; agentId?: string },
- { context: string }
- >({
- function_id: "mem::context",
- payload: {
- sessionId: data.sessionId,
- project: data.project,
- ...(agentId ? { agentId } : {}),
- },
- });
- return { session, context: contextResult.context };
- },
- );
- sdk.registerTrigger({
- type: "durable:subscriber",
- function_id: "event::session::started",
- config: { topic: "agentmemory.session.started" },
- });
-
- sdk.registerFunction("event::observation", async (data: HookPayload) =>
- sdk.trigger({ function_id: "mem::observe", payload: data }),
- );
- sdk.registerTrigger({
- type: "durable:subscriber",
- function_id: "event::observation",
- config: { topic: "agentmemory.observation" },
- });
-
sdk.registerFunction("event::session::stopped", async (data: { sessionId: string; skipConsolidation?: boolean }) => {
const summary = await sdk.trigger<typeof data, { unchanged?: boolean } | undefined>({
function_id: "mem::summarize",
@@ -180,42 +105,6 @@ export function registerEventTriggers(sdk: IIIClient, kv: StateKV): void {
}
return summary;
});
- sdk.registerTrigger({
- type: "durable:subscriber",
- function_id: "event::session::stopped",
- config: { topic: "agentmemory.session.stopped" },
- });
-
- sdk.registerFunction(
- "event::session::ended",
- async (data: { sessionId: string }) => {
- const sessionId = data?.sessionId;
- if (typeof sessionId !== "string" || sessionId.length === 0) {
- return { success: true, ended: false, reason: "not_found" as const };
- }
- const endResult = await withKeyedLock(`obs:${sessionId}`, async () => {
- const session = await kv.get<Session>(KV.sessions, sessionId);
- if (!session || session.id !== sessionId) return "not_found" as const;
- if (session.status === "completed") return "already_completed" as const;
- await requestSummaryRefresh(kv, sessionId);
- await kv.update(KV.sessions, sessionId, [
- { type: "set", path: "endedAt", value: new Date().toISOString() },
- { type: "set", path: "status", value: "completed" },
- ]);
- return "ended" as const;
- });
- if (endResult !== "ended") {
- return { success: true, ended: false, reason: endResult };
- }
- return { success: true, ended: true };
- },
- );
- sdk.registerTrigger({
- type: "durable:subscriber",
- function_id: "event::session::ended",
- config: { topic: "agentmemory.session.ended" },
- });
-
// React to observation count changes and emit a lightweight live event for dashboards/viewer.
sdk.registerFunction(
"event::session::observation-count-changed",
@@ -312,14 +201,10 @@ export function isOutOfAgentScope(record: { agentId?: string } | undefined): boo
}
export async function sendViewerEvent(
- sdk: IIIClient,
+ _sdk: IIIClient,
id: string,
type: string,
data: Record<string, unknown>,
): Promise<void> {
- await sdk.trigger({
- function_id: "stream::send",
- payload: { stream_name: STREAM.name, group_id: STREAM.viewerGroup, id, type, data },
- action: TriggerAction.Void(),
- });
+ emitLiveEvent({ id, type, data });
}
diff --git a/src/triggers/viewer-sse.ts b/src/triggers/viewer-sse.ts
new file mode 100644
index 00000000..574ca055
--- /dev/null
+++ b/src/triggers/viewer-sse.ts
@@ -0,0 +1,29 @@
+import { http } from "@iii-dev/helpers/http";
+import type { IIIClient } from "iii-sdk";
+import { liveEvents, type LiveEventWriter } from "../viewer/live-events.js";
+
+export function registerViewerSse(sdk: IIIClient): void {
+ sdk.registerFunction(
+ "api::viewer-events",
+ http(async (_req, res) => {
+ res.status(200);
+ res.headers({
+ "content-type": "text/event-stream",
+ "cache-control": "no-cache",
+ connection: "keep-alive",
+ "x-accel-buffering": "no",
+ });
+ res.stream.write(": connected\n\n");
+ liveEvents.subscribe(res.stream as LiveEventWriter);
+ }),
+ );
+ sdk.registerTrigger({
+ type: "http",
+ function_id: "api::viewer-events",
+ config: {
+ api_path: "/agentmemory/viewer/events",
+ http_method: "GET",
+ middleware_function_ids: ["middleware::api-auth"],
+ },
+ });
+}
diff --git a/src/triggers/viewer-streams.ts b/src/triggers/viewer-streams.ts
index d48f0f16..6e8fcfdc 100644
--- a/src/triggers/viewer-streams.ts
+++ b/src/triggers/viewer-streams.ts
@@ -37,6 +37,7 @@ import {
type ViewerCounts,
} from "../state/viewer-counts.js";
import { detectLlmProviderKind, loadConfig } from "../config.js";
+import { getLiveEventsStats } from "../viewer/live-events.js";
import { getBoundViewerPort, getViewerSkipped } from "../viewer/server.js";
import { buildConfigFlags, checkAuth, createConsolidationStatusReader, createStatusReporter } from "./api.js";
import { isStateDelete, sendViewerEvent } from "./events.js";
@@ -99,6 +100,7 @@ export function registerViewerStreamTriggers(
return {
status: snapshot?.status ?? "healthy",
health: snapshot,
+ liveEvents: getLiveEventsStats(),
circuitBreaker: circuitBreaker(),
functionMetrics: markLlmFunctions(functionMetrics, detectLlmProviderKind()),
counts,
@@ -284,7 +286,7 @@ export function registerViewerStreamTriggers(
config: { scope: KV.health },
});
- const { streamsPort, restPort } = loadConfig();
+ const { restPort } = loadConfig();
sdk.registerFunction("api::viewer-snapshot",
async (req: HttpRequest): Promise<Response> => {
@@ -302,7 +304,6 @@ export function registerViewerStreamTriggers(
service: "agentmemory",
viewerPort: getBoundViewerPort(),
viewerSkipped: getViewerSkipped(),
- streamsPort,
restPort,
provider: detectLlmProviderKind(),
embeddingProvider: getEmbeddingProvider()?.name ?? "none",
diff --git a/src/types.ts b/src/types.ts
index 92b7e998..e2871326 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -227,7 +227,6 @@ export interface MemoryProvider {
export interface AgentMemoryConfig {
engineUrl: string;
restPort: number;
- streamsPort: number;
viewerPort: number;
provider: ProviderConfig;
tokenBudget: number;
@@ -282,7 +281,7 @@ export interface HealthSnapshot {
eventLoopLagMs: number;
uptimeSeconds: number;
kvConnectivity?: { status: string; latencyMs?: number; error?: string };
- streamRelay?: "ok" | "down" | "unknown";
+ liveEvents?: { subscribers: number; eventsSent: number; dropped: number; lastEventAt: number | null };
status: "healthy" | "degraded" | "critical";
alerts: string[];
notes?: string[];
diff --git a/src/version.ts b/src/version.ts
index 95b0e98e..d717a01f 100644
--- a/src/version.ts
+++ b/src/version.ts
@@ -1,2 +1,2 @@
export const VERSION = "0.9.30";
-export const III_PINNED_VERSION = "0.22.1";
+export const III_PINNED_VERSION = "0.25.0";
diff --git a/src/viewer/index.html b/src/viewer/index.html
index 9873cc96..3831edc3 100644
--- a/src/viewer/index.html
+++ b/src/viewer/index.html
@@ -1521,28 +1521,17 @@
var params = new URLSearchParams(window.location.search);
var paramPort = params.get('port');
var locPort = window.location.port;
- var wsProto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
- var REST, WS_URL, WS_DIRECT_URL, wsPort;
+ var REST;
if (paramPort) {
var resolvedPort = parseInt(paramPort) === 3111 ? '3113' : paramPort;
REST = window.location.protocol + '//' + window.location.hostname + ':' + resolvedPort;
- wsPort = params.get('wsPort') || String(parseInt(resolvedPort) - 1);
- WS_URL = wsProto + '//' + window.location.hostname + ':' + wsPort;
- WS_DIRECT_URL = WS_URL + '/stream/mem-live/viewer';
} else if (locPort) {
var resolvedPort = parseInt(locPort) === 3111 ? '3113' : locPort;
REST = window.location.protocol + '//' + window.location.hostname + ':' + resolvedPort;
- wsPort = params.get('wsPort') || String(parseInt(resolvedPort) - 1);
- WS_URL = wsProto + '//' + window.location.hostname + ':' + wsPort;
- WS_DIRECT_URL = WS_URL + '/stream/mem-live/viewer';
} else {
REST = window.location.origin;
- wsPort = params.get('wsPort');
- WS_URL = wsPort
- ? wsProto + '//' + window.location.hostname + ':' + wsPort
- : wsProto + '//' + window.location.host;
- WS_DIRECT_URL = WS_URL + '/stream/mem-live/viewer';
}
+ var LIVE_EVENTS_URL = REST + '/agentmemory/viewer/events';
var dateEl = document.getElementById('dateline');
if (dateEl) dateEl.textContent = new Date().toLocaleDateString('en-US', { weekday: 'short', year: 'numeric', month: 'short', day: 'numeric' });
@@ -1654,9 +1643,9 @@
eventLoop: { term: 'Event loop delay', text: 'How far behind the worker is in handling work. Under 20 ms is healthy; a large value means it is busy or blocked.' },
uptime: { term: 'Uptime', text: 'How long the agentmemory worker has been running since it last started.' },
health: { term: 'Health status', text: 'Healthy means everything is normal. Degraded means something needs attention but memory still works. Critical means a core part is failing.' },
- stateBackend: { term: 'State store', text: 'Where the engine keeps every record: file (local files on this machine, the default) or redis (a Redis server set by AGENTMEMORY_STATE_BACKEND and AGENTMEMORY_REDIS_URL). ok means a test write and read just succeeded; the number is how long it took.' },
- engineConnection: { term: 'Engine connection', text: 'Whether the agentmemory worker is connected to the iii engine that stores its data and runs its functions.' },
- live: { term: 'Live updates', text: 'The viewer keeps one streaming connection open and updates every page the moment data changes. Nothing is refreshed on a timer.' },
+ stateBackend: { term: 'State store', text: 'Where the state worker keeps every record: file (local files on this machine, the default) or redis (a Redis server set by AGENTMEMORY_STATE_BACKEND and AGENTMEMORY_REDIS_URL). ok means a test write and read just succeeded; the number is how long it took.' },
+ engineConnection: { term: 'Engine connection', text: 'Whether the agentmemory worker is connected to the iii engine that routes calls between workers.' },
+ live: { term: 'Live updates', text: 'The viewer keeps one SSE connection open and updates every page the moment data changes. Nothing is refreshed on a timer.' },
flags: { term: 'Feature flags', text: 'Optional features that are on or off in this install. Off features leave some pages empty; each one lists the setting that turns it on.' },
audit: { term: 'Audit log', text: 'A record of every change agentmemory made to stored data: saves, deletes, imports, consolidation runs. Use it to see who changed what and when.' },
workers: { term: 'Workers', text: 'Processes connected to the iii engine. agentmemory runs as one worker.' },
@@ -1683,7 +1672,6 @@
replay: { loaded: false, selectedId: '', timeline: null, cursor: 0, playing: false, speed: 1, timer: null, startAt: 0, offsetAt: 0, loadingTimeline: false, loadError: '', importPath: '', importing: false, importOpen: false, importStatus: null },
flagsOpen: false,
freshRows: {},
- ws: null
};
var store = {
@@ -3748,7 +3736,7 @@
html += copyBtn('memory_graph_query { "startNodeId": ' + JSON.stringify(id) + ', "maxDepth": 1 }', 'MCP call').replace('>copy<', '>copy MCP call<');
html += copyBtn(curlGet('graph/node?id=' + encodeURIComponent(id)), 'curl command').replace('>copy<', '>copy curl<');
html += '</div>';
- if (d && d.stale) html += '<div class="mem-note">This node changed on the live stream. <button type="button" class="linkish" data-action="graph-refresh-detail" data-node-id="' + esc(id) + '">Reload sources</button></div>';
+ if (d && d.stale) html += '<div class="mem-note">This node changed on the SSE feed. <button type="button" class="linkish" data-action="graph-refresh-detail" data-node-id="' + esc(id) + '">Reload sources</button></div>';
var rels = graphDetailRelations(id);
var relTotal = data && typeof data.relationsTotal === 'number' ? Math.max(data.relationsTotal, rels.length) : rels.length;
@@ -3873,7 +3861,7 @@
html += '<div class="empty-step-label" style="margin-top:8px;">Query it from an agent:</div>' + cmdBlock('memory_graph_query { "query": "checkout" }');
html += '</div>';
if (g.rebuildResult) html += '<div class="mem-note">' + esc(g.rebuildResult) + '</div>';
- html += '<div class="go-live">' + (g.patches ? 'Patched ' + fmtNum(g.patches) + ' time' + (g.patches === 1 ? '' : 's') + ' from the live stream, last ' + relTime(new Date(g.lastPatchAt).toISOString()) + '.' : 'Updates arrive on the live stream; nothing refreshes on a timer.') + ' ' + help('live') + '</div>';
+ html += '<div class="go-live">' + (g.patches ? 'Patched ' + fmtNum(g.patches) + ' time' + (g.patches === 1 ? '' : 's') + ' from the SSE feed, last ' + relTime(new Date(g.lastPatchAt).toISOString()) + '.' : 'Updates arrive on the SSE feed; nothing refreshes on a timer.') + ' ' + help('live') + '</div>';
html += '</div>';
setViewHtml(host, html);
}
@@ -4176,7 +4164,7 @@
try {
var result = await apiPost('graph/build', {});
g.rebuildResult = result && result.success
- ? 'Rebuilt from ' + (result.sessions || 0) + ' sessions: ' + (result.nodes || 0) + ' nodes and ' + (result.edges || 0) + ' relations extracted. New ones arrive on the live stream.'
+ ? 'Rebuilt from ' + (result.sessions || 0) + ' sessions: ' + (result.nodes || 0) + ' nodes and ' + (result.edges || 0) + ' relations extracted. New ones arrive on the SSE feed.'
: 'The rebuild failed. Check the server log.';
} finally {
graphRebuilding = false;
@@ -4584,7 +4572,7 @@
var mem = store.entities.memory[id];
if (!mem) {
if (m.pendingId === id) {
- setViewHtml(panel, '<div class="detail-panel mem-detail"><div class="mem-detail-head"><span>Saving the new version</span>' + memoryCloseBtn() + '</div><div class="mem-note">Saved. Waiting for the new version to arrive on the live stream…</div>' + skeleton(4) + '</div>');
+ setViewHtml(panel, '<div class="detail-panel mem-detail"><div class="mem-detail-head"><span>Saving the new version</span>' + memoryCloseBtn() + '</div><div class="mem-note">Saved. Waiting for the new version to arrive on the SSE feed…</div>' + skeleton(4) + '</div>');
return;
}
if (!m.fetches[id]) fetchMemoryVersion(id);
@@ -6483,7 +6471,7 @@
var res = await apiPost('lessons/strengthen', { lessonId: id });
l.busy = '';
l.notice = res && res.success !== false
- ? { id: id, html: 'Recorded one more use. Confidence and uses update here from the live stream.' }
+ ? { id: id, html: 'Recorded one more use. Confidence and uses update here from the SSE feed.' }
: { id: id, err: true, html: 'Strengthen failed' + (res && res.error ? ': ' + esc(res.error) : '. Check that agentmemory is running.') };
renderLessons();
}
@@ -6725,7 +6713,7 @@
var res = await apiPost('actions/update', { actionId: id, status: status });
a.busy = '';
a.notice = res && res.success !== false
- ? { id: id, html: 'Status set to <b>' + esc(status) + '</b>. Ready markers update from the live stream.' }
+ ? { id: id, html: 'Status set to <b>' + esc(status) + '</b>. Ready markers update from the SSE feed.' }
: { id: id, err: true, html: 'Update failed' + (res && res.error ? ': ' + esc(res.error) : '. Check that agentmemory is running.') };
renderActions();
}
@@ -7221,7 +7209,7 @@
}
if (store.lastHealthAt && Date.now() - store.lastHealthAt > HEALTH_STALE_MS) {
var secs = Math.round((Date.now() - store.lastHealthAt) / 1000);
- return '<div class="hstale" id="health-live-state"><strong>Stale: no health report for ' + secs + 's.</strong> Reports normally arrive every 30 seconds. The stream is connected, so the worker is busy or the iii engine is paused' + (r && r.service && r.service.stateBackend === 'redis' ? ', or Redis restarted: the engine stops relaying live events after a Redis restart until agentmemory restarts' : '') + '. The numbers below are from ' + esc(last) + '.' +
+ return '<div class="hstale" id="health-live-state"><strong>Stale: no health report for ' + secs + 's.</strong> Reports normally arrive every 30 seconds. The SSE feed is connected, but the worker may be busy or unable to publish a health report. The numbers below are from ' + esc(last) + '.' +
'<div style="margin-top:6px;">Fix: wait a minute; if it stays stale, press Re-check now for the full report, check the server log and restart agentmemory.</div></div>';
}
return '';
@@ -7247,7 +7235,7 @@
}
html += '<div class="verdict"><span class="verdict-badge ' + esc(level) + '">' + esc(badgeText) + '</span><div style="min-width:0;flex:1;">' +
'<div class="verdict-text">' + esc(text) + '</div>' +
- '<div class="verdict-meta">' + (r ? 'Report ' + relTime(r.checkedAt) + ' · ' : '') + 'updates every 30 s over the live stream, no refresh needed ' + help('live') + '</div></div></div>';
+ '<div class="verdict-meta">' + (r ? 'Report ' + relTime(r.checkedAt) + ' · ' : '') + 'updates every 30 s over SSE, no refresh needed ' + help('live') + '</div></div></div>';
html += healthStaleHtml(r);
if (state.health.error) html += '<div class="mem-note err" style="margin-top:10px;">' + esc(state.health.error) + '</div>';
if (r && r.problems.length) {
@@ -7268,13 +7256,12 @@
var backend = r && r.service ? r.service.stateBackend : null;
var streamText = conn.state === 'live' ? 'live' : conn.state;
return '<div class="card"><div class="card-title">Engine and connection ' + help('engineConnection') + '</div>' +
- hrow('Engine connection', esc(snap.connectionState || 'unknown'), 'engineConnection', 'The worker\'s link to the iii engine, which stores the data and runs the functions.') +
- ((kv || backend) ? hrow('State store', esc((backend ? backend + (kv ? ' · ' : '') : '') + (kv ? kv.status + (kv.latencyMs !== undefined ? ' · ' + kv.latencyMs + ' ms' : '') + (kv.error ? ' · ' + kv.error : '') : '')), 'stateBackend', backend === 'redis' ? 'Stored in Redis (AGENTMEMORY_STATE_BACKEND=redis). If Redis restarts, restart agentmemory so the live stream resumes.' : 'Stored in the engine\'s local files (the default). Set AGENTMEMORY_STATE_BACKEND=redis to use Redis.') : '') +
- hrow('Viewer stream', esc(streamText), 'live', 'This page\'s own connection. Offline means the numbers here stop changing.') +
- (snap.streamRelay ? hrow('Redis event relay', esc(snap.streamRelay), 'live', snap.streamRelay === 'down' ? 'The engine stopped relaying live events through Redis, usually after Redis restarted. Data is still saved. Restart agentmemory to resume live updates.' : 'A test event sent through Redis every 30 seconds came back to the worker.') : '') +
+ hrow('Engine connection', esc(snap.connectionState || 'unknown'), 'engineConnection', 'The worker\'s link to the iii engine, which routes calls between workers.') +
+ ((kv || backend) ? hrow('State store', esc((backend ? backend + (kv ? ' · ' : '') : '') + (kv ? kv.status + (kv.latencyMs !== undefined ? ' · ' + kv.latencyMs + ' ms' : '') + (kv.error ? ' · ' + kv.error : '') : '')), 'stateBackend', backend === 'redis' ? 'The state worker stores records in Redis (AGENTMEMORY_STATE_BACKEND=redis).' : 'The state worker stores records in local files (the default). Set AGENTMEMORY_STATE_BACKEND=redis to use Redis.') : '') +
+ hrow('Viewer feed', esc(streamText), 'live', 'This page\'s own connection. Offline means the numbers here stop changing.') +
hrow('Uptime', esc(formatUptime(snap.uptimeSeconds)), 'uptime') +
- hrow('Version', esc('v' + (store.version || (r && r.service.version) || '?') + (r ? ' · engine ' + r.service.engineVersion : ''))) +
- hrow('Ports', esc('REST ' + (ports.rest || '?') + ' · streams ' + (ports.streams || '?') + ' · viewer ' + (ports.viewer || 'off'))) +
+ hrow('Version', esc('v' + (store.version || (r && r.service.version) || '?') + (r ? ' · engine pinned ' + r.service.enginePinnedVersion : ''))) +
+ hrow('Ports', esc('REST ' + (ports.rest || '?') + ' · viewer ' + (ports.viewer || 'off'))) +
'</div>';
}
@@ -7544,7 +7531,7 @@
var snap = store.health || {};
var idx = store.indexes || {};
var c = store.counts || {};
- var html = '<div class="inline-note"><strong>Health</strong> ' + help('health') + ' is the live version of the <a class="empty-link" href="' + esc(REST) + '/agentmemory/status" target="_blank" rel="noopener">/agentmemory/status</a> page: the same checks and verdict, pushed over the stream every 30 seconds. Every problem says what to do. Scroll down for how consolidation works.</div>';
+ var html = '<div class="inline-note"><strong>Health</strong> ' + help('health') + ' is the live version of the <a class="empty-link" href="' + esc(REST) + '/agentmemory/status" target="_blank" rel="noopener">/agentmemory/status</a> page: the same checks and verdict, pushed over SSE every 30 seconds. Every problem says what to do. Scroll down for how consolidation works.</div>';
html += healthVerdictHtml(r);
html += '<div class="hgrid">' + engineCardHtml(r, snap) + indexCardHtml(r, idx, c) + captureCardHtml(r) + llmCardHtml(r) + flagsCardHtml(r) + processCardHtml(snap) + recordsCardHtml(c) + '</div>';
html += consolidationPanelHtml(store.consolidationStatus, c);
@@ -7754,14 +7741,12 @@
var wsReconnectTimer = null;
var wsRetries = 0;
- var directFailed = true;
- var directFailures = 0;
var wsHasConnected = false;
var wsOpenedAt = null;
- var DIRECT_FAILURE_THRESHOLD = 2;
var OFFLINE_AFTER_RETRIES = 3;
var HEALTH_STALE_MS = 90000;
var conn = { state: 'connecting', nextRetryAt: 0, lostAt: 0 };
+ var liveAbortController = null;
function reconnectDelay(attempt) {
var n = Math.max(1, attempt || 1);
@@ -7847,87 +7832,99 @@
function reconnectNow() {
if (wsReconnectTimer) clearTimeout(wsReconnectTimer);
wsReconnectTimer = null;
- directFailures = 0;
- directFailed = true;
conn.nextRetryAt = 0;
- var ws = state.ws;
- if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+ if (liveAbortController) {
+ liveAbortController.abort();
+ liveAbortController = null;
+ }
connectWs();
}
- var WS_CONNECT_TIMEOUT_MS = 5000;
+ function parseSseFrame(frame) {
+ var id = '';
+ var type = '';
+ var data = [];
+ frame.split(/\r?\n/).forEach(function(line) {
+ if (!line || line.charAt(0) === ':') return;
+ var colon = line.indexOf(':');
+ var field = colon < 0 ? line : line.slice(0, colon);
+ var value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+ if (field === 'id') id = value;
+ else if (field === 'event') type = value;
+ else if (field === 'data') data.push(value);
+ });
+ if (!type || !data.length) return null;
+ try { return { id: id, type: type, data: JSON.parse(data.join('\n')) }; } catch (_) { return null; }
+ }
+
+ function consumeSseChunk(buffer, chunk) {
+ buffer += chunk;
+ var frames = [];
+ var match;
+ while ((match = /\r?\n\r?\n/.exec(buffer))) {
+ var frame = buffer.slice(0, match.index);
+ buffer = buffer.slice(match.index + match[0].length);
+ var parsed = parseSseFrame(frame);
+ if (parsed) frames.push(parsed);
+ }
+ return { buffer: buffer, frames: frames };
+ }
- function connectWs() {
+ async function connectWs() {
wsReconnectTimer = null;
conn.nextRetryAt = 0;
- var useDirect = !directFailed;
- var ws;
+ var controller = new AbortController();
+ liveAbortController = controller;
try {
- ws = new WebSocket(useDirect ? WS_DIRECT_URL : WS_URL);
- ws.__direct = useDirect;
- } catch (_) {
- scheduleReconnect();
- return;
- }
- var connectTimer = setTimeout(function() {
- if (ws.readyState === WebSocket.CONNECTING) {
- try { ws.close(); } catch {}
+ var headers = { 'Cache-Control': 'no-cache', Accept: 'text/event-stream' };
+ var viewerToken = getViewerToken();
+ if (viewerToken) headers.Authorization = 'Bearer ' + viewerToken;
+ var response = await fetch(LIVE_EVENTS_URL, { headers: headers, signal: controller.signal });
+ if (!response.ok || !response.body) {
+ if (response.status === 401) showViewerAuthPrompt();
+ throw new Error('SSE request failed: ' + response.status);
}
- }, WS_CONNECT_TIMEOUT_MS);
- ws.onopen = function() {
- clearTimeout(connectTimer);
- if (state.ws !== ws) return;
+ hideViewerAuthPrompt();
wsRetries = 0;
- if (!ws.__direct) {
- ws.send(JSON.stringify({
- type: 'join',
- data: {
- subscriptionId: 'viewer-' + Date.now(),
- streamName: 'mem-live',
- groupId: 'viewer'
- }
- }));
- }
var firstConnect = !wsHasConnected;
wsHasConnected = true;
wsOpenedAt = Date.now();
setConnection('live');
updateFooter();
- resyncAfterConnect(firstConnect);
- };
- ws.onmessage = function(e) {
- if (state.ws !== ws) return;
- if (!ws.__usable) {
- ws.__usable = true;
- directFailures = 0;
+ await resyncAfterConnect(firstConnect);
+ var reader = response.body.getReader();
+ var decoder = new TextDecoder();
+ var buffer = '';
+ while (true) {
+ var result = await reader.read();
+ if (result.done) break;
+ buffer += decoder.decode(result.value, { stream: true });
+ var parsed = consumeSseChunk(buffer, '');
+ buffer = parsed.buffer;
+ parsed.frames.forEach(function(frame) {
+ store.lastEventAt = Date.now();
+ if (frame.type === 'raw_observation') {
+ var obs = frame.data && frame.data.data && (frame.data.data.observation || frame.data.data);
+ if (looksLikeObservation(obs)) routeWsMessage({ observation: obs, fresh: true });
+ } else if (frame.type === 'compressed_observation') {
+ var compressed = frame.data && frame.data.data && (frame.data.data.observation || frame.data.data);
+ if (looksLikeObservation(compressed)) routeWsMessage({ observation: compressed, fresh: true });
+ } else {
+ handleLiveEvent(frame.type, frame.data && frame.data.data || {});
+ }
+ });
}
- store.lastEventAt = Date.now();
- try {
- var msg = JSON.parse(e.data);
- if (msg.type === 'stream' && msg.event) {
- handleStreamEvent(msg);
- } else if (msg.event_type && msg.data) {
- handleStreamEvent({ event: { type: 'create', data: msg.data, event_type: msg.event_type } });
- }
- } catch {}
- };
- ws.onclose = function() {
- clearTimeout(connectTimer);
- if (state.ws !== ws) return;
- wsOpenedAt = null;
- updateFooter();
- directFailures += 1;
- if (directFailures >= DIRECT_FAILURE_THRESHOLD) {
- directFailed = ws.__direct;
- directFailures = 0;
+ if (!controller.signal.aborted) throw new Error('SSE stream ended');
+ } catch (err) {
+ if (!controller.signal.aborted) console.warn('[viewer] SSE connection failed:', err);
+ } finally {
+ if (liveAbortController === controller) liveAbortController = null;
+ if (!controller.signal.aborted) {
+ wsOpenedAt = null;
+ updateFooter();
+ scheduleReconnect();
}
- scheduleReconnect();
- };
- ws.onerror = function() {
- if (state.ws !== ws) return;
- try { ws.close(); } catch {}
- };
- state.ws = ws;
+ }
}
var resyncing = null;
@@ -7946,6 +7943,7 @@
resyncing = (async function() {
try {
await loadSnapshot();
+ await loadRecentObservations();
scheduleHealthStaleCheck();
if (!firstConnect || reloadKinds.length) {
reloadKinds.forEach(resetLoadedKindForReload);
@@ -7965,6 +7963,24 @@
}
var LIVE_BUFFER_MAX = 200;
+ var ACTIVITY_SESSIONS = 10;
+ async function loadRecentObservations() {
+ var sessionResult = await apiGet('sessions?limit=' + ACTIVITY_SESSIONS);
+ var sessions = sortByTimeDesc((sessionResult && sessionResult.sessions) || [], ['startedAt']).filter(function(x) { return sessionId(x); }).slice(0, ACTIVITY_SESSIONS);
+ mergeSessionRows(sessions);
+ var results = await Promise.all(sessions.map(function(x) {
+ return apiGet('observations?sessionId=' + encodeURIComponent(sessionId(x)) + '&limit=100');
+ }));
+ var seen = {};
+ results.forEach(function(result) {
+ ((result && result.observations) || []).slice(-LIVE_BUFFER_MAX).forEach(function(observation) {
+ if (!observation || !observation.id || seen[observation.id]) return;
+ seen[observation.id] = true;
+ routeWsMessage({ observation: observation });
+ });
+ });
+ }
+
function looksLikeObservation(obj) {
return !!(obj && typeof obj === 'object' && obj.id && obj.timestamp);
@@ -8206,15 +8222,6 @@
if (looksLikeObservation(observation)) {
routeWsMessage({ observation: observation, fresh: true });
}
- } else if (evt.type === 'sync') {
- var items = Array.isArray(evt.data) ? evt.data.slice(-LIVE_BUFFER_MAX) : [];
- items.forEach(function(item) {
- var payload = item.data || item;
- observation = payload.observation || payload;
- if (looksLikeObservation(observation)) {
- routeWsMessage({ observation: observation });
- }
- });
}
}
@@ -8377,7 +8384,7 @@
var sync = document.getElementById('footer-sync');
if (sync) {
var syncText = store.snapshotAt ? 'full sync ' + new Date(store.snapshotAt).toLocaleTimeString() : 'waiting for first sync';
- if (store.snapshotAt) syncText += wsOpenedAt ? ', streaming since ' + new Date(wsOpenedAt).toLocaleTimeString() : ', stream reconnecting';
+ if (store.snapshotAt) syncText += wsOpenedAt ? ', live via SSE since ' + new Date(wsOpenedAt).toLocaleTimeString() : ', SSE reconnecting';
sync.textContent = syncText;
}
var fbEl = document.getElementById('footer-feedback');
@@ -8474,7 +8481,7 @@
var modal = document.getElementById('modal');
var overlay = document.getElementById('modal-overlay');
var html = '<h3>How to read this viewer</h3>';
- html += '<p style="margin-bottom:8px;">Everything on these pages updates live over one streaming connection; nothing refreshes on a timer. Click any <span class="help" style="cursor:default;">?</span> for a short explanation, or use the keys below.</p>';
+ html += '<p style="margin-bottom:8px;">Everything on these pages updates live over one SSE connection; nothing refreshes on a timer. Click any <span class="help" style="cursor:default;">?</span> for a short explanation, or use the keys below.</p>';
html += '<div class="kbd-list">' +
'<div><kbd>/</kbd> focus search on this page</div>' +
'<div><kbd>?</kbd> open this help</div>' +
@@ -9045,16 +9052,7 @@
var bootRoute = parseRoute(window.location.hash);
switchTab(bootRoute.tab, { replaceRoute: true, skipRoute: !!bootRoute.obs && !bootRoute.redirect, id: bootRoute.id, obs: bootRoute.obs });
- (async function initWs() {
- try {
- var live = await api('livez', { signal: AbortSignal.timeout(5000) });
- if (live && typeof live.streamsPort === 'number' && live.streamsPort > 0) {
- WS_URL = wsProto + '//' + window.location.hostname + ':' + live.streamsPort;
- WS_DIRECT_URL = WS_URL + '/stream/mem-live/viewer';
- }
- } catch (_) {}
- connectWs();
- })();
+ connectWs();
setTimeout(function() {
if (wsHasConnected) return;
openBootGate();
@@ -9064,8 +9062,7 @@
document.addEventListener('visibilitychange', function() {
if (document.visibilityState !== 'visible') return;
- var ws = state.ws;
- if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+ if (liveAbortController) return;
wsRetries = 0;
reconnectNow();
});
diff --git a/src/viewer/live-events.ts b/src/viewer/live-events.ts
new file mode 100644
index 00000000..2aae38d4
--- /dev/null
+++ b/src/viewer/live-events.ts
@@ -0,0 +1,127 @@
+import type { Writable } from "node:stream";
+
+export interface LiveEvent {
+ id: string;
+ type: string;
+ data: Record<string, unknown>;
+}
+
+export interface LiveEventsStats {
+ subscribers: number;
+ eventsSent: number;
+ dropped: number;
+ lastEventAt: number | null;
+}
+
+export interface LiveEventWriter extends Writable {
+ writableLength: number;
+}
+
+const MAX_SUBSCRIBERS = 32;
+const MAX_BUFFERED_BYTES = 1024 * 1024;
+const HEARTBEAT_MS = 15_000;
+const eventListeners = new Set<(event: LiveEvent) => void>();
+
+export function formatSseFrame(event: LiveEvent): string {
+ return `id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+
+export class LiveEventsHub {
+ private readonly writers = new Set<LiveEventWriter>();
+ private readonly detach = new Map<LiveEventWriter, () => void>();
+ private heartbeat: ReturnType<typeof setInterval> | null = null;
+ private eventsSent = 0;
+ private dropped = 0;
+ private lastEventAt: number | null = null;
+
+ subscribe(writer: LiveEventWriter): () => void {
+ if (this.writers.size >= MAX_SUBSCRIBERS) {
+ const oldest = this.writers.values().next().value as LiveEventWriter | undefined;
+ if (oldest) this.remove(oldest, true);
+ }
+ this.writers.add(writer);
+ const onClose = () => this.remove(writer, false);
+ this.detach.set(writer, onClose);
+ writer.once("close", onClose);
+ writer.once("error", onClose);
+ if (!this.heartbeat) {
+ this.heartbeat = setInterval(() => this.ping(), HEARTBEAT_MS);
+ this.heartbeat.unref();
+ }
+ return () => this.remove(writer, false);
+ }
+
+ emit(event: LiveEvent): void {
+ this.lastEventAt = Date.now();
+ for (const listener of eventListeners) {
+ try { listener(event); } catch { /* observers must not break event delivery */ }
+ }
+ const frame = formatSseFrame(event);
+ for (const writer of this.writers) {
+ if (writer.destroyed || writer.writableLength > MAX_BUFFERED_BYTES) {
+ this.remove(writer, true);
+ continue;
+ }
+ try {
+ writer.write(frame);
+ this.eventsSent++;
+ } catch {
+ this.remove(writer, true);
+ }
+ }
+ }
+
+ stats(): LiveEventsStats {
+ return {
+ subscribers: this.writers.size,
+ eventsSent: this.eventsSent,
+ dropped: this.dropped,
+ lastEventAt: this.lastEventAt,
+ };
+ }
+
+ private ping(): void {
+ for (const writer of this.writers) {
+ if (writer.destroyed || writer.writableLength > MAX_BUFFERED_BYTES) {
+ this.remove(writer, true);
+ continue;
+ }
+ try {
+ writer.write(": ping\n\n");
+ } catch {
+ this.remove(writer, true);
+ }
+ }
+ }
+
+ private remove(writer: LiveEventWriter, dropped: boolean): void {
+ if (!this.writers.delete(writer)) return;
+ const onClose = this.detach.get(writer);
+ this.detach.delete(writer);
+ if (onClose) {
+ writer.off("close", onClose);
+ writer.off("error", onClose);
+ }
+ if (dropped) {
+ this.dropped++;
+ if (!writer.destroyed) writer.destroy();
+ }
+ if (this.writers.size === 0 && this.heartbeat) {
+ clearInterval(this.heartbeat);
+ this.heartbeat = null;
+ }
+ }
+
+}
+
+export const liveEvents = new LiveEventsHub();
+export function emitLiveEvent(event: LiveEvent): void {
+ liveEvents.emit(event);
+}
+export function onLiveEvent(listener: (event: LiveEvent) => void): () => void {
+ eventListeners.add(listener);
+ return () => eventListeners.delete(listener);
+}
+export function getLiveEventsStats(): LiveEventsStats {
+ return liveEvents.stats();
+}
diff --git a/src/viewer/server.ts b/src/viewer/server.ts
index 8cf7ea74..4a9271e5 100644
--- a/src/viewer/server.ts
+++ b/src/viewer/server.ts
@@ -3,6 +3,7 @@ import {
type Server,
type IncomingMessage,
type ServerResponse,
+ request as httpRequest,
} from "node:http";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
@@ -435,6 +436,44 @@ async function proxyToRestApi(
headers["Content-Type"] = ct;
}
+ const cors = corsHeaders(req);
+ if (pathname === "/agentmemory/viewer/events") {
+ const headers: Record<string, string> = {};
+ if (secret) headers["Authorization"] = `Bearer ${secret}`;
+ const client = httpRequest(upstreamUrl, { method, headers });
+ const abortUpstream = () => client.destroy();
+ req.once("aborted", abortUpstream);
+ res.once("close", abortUpstream);
+ client.once("response", (upstream) => {
+ const responseHeaders: Record<string, string> = {
+ ...cors,
+ "Cache-Control": "no-cache",
+ "X-Accel-Buffering": "no",
+ };
+ const contentType = upstream.headers["content-type"];
+ if (contentType) responseHeaders["Content-Type"] = Array.isArray(contentType) ? contentType.join(", ") : contentType;
+ res.writeHead(upstream.statusCode ?? 502, responseHeaders);
+ upstream.on("data", (chunk: Buffer) => {
+ if (!res.write(chunk)) upstream.pause();
+ });
+ res.on("drain", () => upstream.resume());
+ upstream.once("end", () => { if (!res.destroyed) res.end(); });
+ upstream.once("error", () => { if (!res.destroyed) res.destroy(); });
+ });
+ client.once("error", (err) => {
+ if (!res.headersSent && !res.destroyed) json(res, 502, { error: "upstream error" }, req);
+ else if (!res.destroyed) res.destroy(err);
+ });
+ client.end();
+ await new Promise<void>((resolve) => {
+ res.once("close", resolve);
+ res.once("finish", resolve);
+ });
+ req.off("aborted", abortUpstream);
+ res.off("close", abortUpstream);
+ return;
+ }
+
let body: string | undefined;
if (method === "POST" || method === "PUT" || method === "DELETE" || method === "PATCH") {
body = await readBody(req);
@@ -446,7 +485,7 @@ async function proxyToRestApi(
try {
upstream = await fetch(upstreamUrl, {
method,
- headers,
+ headers: { ...(secret ? { "Authorization": `Bearer ${secret}` } : {}), ...(req.headers["content-type"] ? { "Content-Type": req.headers["content-type"] } : {}) },
body: body || undefined,
signal: controller.signal,
});
@@ -459,17 +498,11 @@ async function proxyToRestApi(
}
throw err;
}
-
- const cors = corsHeaders(req);
const responseBody = await upstream.text();
- const responseHeaders: Record<string, string> = {
- ...cors,
- };
+ const responseHeaders: Record<string, string> = { ...cors };
const upstreamCt = upstream.headers.get("content-type");
- if (upstreamCt) {
- responseHeaders["Content-Type"] = upstreamCt;
- }
-
+ if (upstreamCt) responseHeaders["Content-Type"] = upstreamCt;
res.writeHead(upstream.status, responseHeaders);
res.end(responseBody);
+ return;
}
diff --git a/test/capture-durable.test.ts b/test/capture-durable.test.ts
index 56c48c96..cb8c11c2 100644
--- a/test/capture-durable.test.ts
+++ b/test/capture-durable.test.ts
@@ -1,5 +1,5 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { mockKV, mockSdk } from "./helpers/mocks.js";
@@ -380,10 +380,10 @@ describe("capture status problems", () => {
const report = evaluateStatus({
now: new Date(),
version: "0",
- engineVersion: "0",
+ enginePinnedVersion: "0",
uptimeSeconds: 1,
stateBackend: "file",
- ports: { rest: 4811, streams: null, viewer: null },
+ ports: { rest: 4811, viewer: null },
health: null,
circuitBreaker: null,
functionMetrics: [],
@@ -467,6 +467,26 @@ describe("acceptance durability across a restart", () => {
expect(captureDurableAfterMs("redis", ["save_interval_ms: 2000"])).toBe(1500);
});
+ it("keeps Docker captures until its Compose state override has flushed", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "am-docker-flush-"));
+ vi.stubEnv("AGENTMEMORY_DATA_DIR", dir);
+ vi.stubEnv("AGENTMEMORY_ENV_FILE", join(dir, "missing.env"));
+ vi.stubEnv("AGENTMEMORY_STATE_BACKEND", "file");
+ vi.stubEnv("AGENTMEMORY_STATE_SAVE_INTERVAL_MS", "30000");
+ mkdirSync(join(dir, "config"));
+ writeFileSync(join(dir, "config", "state.yaml"), "id: state\nvalue:\n triggers_enabled: true\n");
+ writeFileSync(join(dir, "worker-compose.runtime.yaml"), [
+ "containers:", " state:", " config_override:", " adapter:", " name: kv", " config:",
+ " store_method: file_based", ' save_interval_ms: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"', "",
+ ].join("\n"));
+ try {
+ const { serverDurableAfterMs } = await import("../src/functions/capture.js");
+ expect(serverDurableAfterMs()).toBe(31500);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
it("re-sends observations a client kept from the previous boot and keeps them under the new boot", async () => {
const dir = join(mkdtempSync(join(tmpdir(), "am-cap-")), "capture-spool");
vi.stubEnv("AGENTMEMORY_CAPTURE_SPOOL_DIR", dir);
diff --git a/test/capture-redaction.test.ts b/test/capture-redaction.test.ts
index 0719d6df..c68b3128 100644
--- a/test/capture-redaction.test.ts
+++ b/test/capture-redaction.test.ts
@@ -5,6 +5,7 @@ import { join } from "node:path";
import { appendSpool, retainSent, type SpoolRecord } from "../src/capture/spool.js";
import { registerObserveFunction } from "../src/functions/observe.js";
import { KV } from "../src/state/schema.js";
+import { onLiveEvent } from "../src/viewer/live-events.js";
import type { CompressedObservation, RawObservation } from "../src/types.js";
import { mockKV, mockSdk } from "./helpers/mocks.js";
@@ -164,9 +165,9 @@ describe("direct observation redaction", () => {
it.each(CASES)("preserves structure while scrubbing $name", async ({ data, expected }) => {
const sdk = mockSdk({ looseTrigger: true });
const kv = mockKV();
- const stream = vi.fn(async (_data: unknown) => null);
+ const events: unknown[] = [];
+ const unsubscribe = onLiveEvent((event) => events.push(event));
const compress = vi.fn(async (_data: unknown) => null);
- sdk.registerFunction("stream::send", stream);
sdk.registerFunction("mem::compress", compress);
registerObserveFunction(sdk as never, kv as never);
const input = payload(data);
@@ -176,7 +177,8 @@ describe("direct observation redaction", () => {
expect(result.observationId).toBeTruthy();
const stored = await kv.get<CompressedObservation>(KV.observations(input.sessionId), result.observationId);
- const streamed = (stream.mock.calls[0]![0] as { data: { observation: RawObservation } }).data.observation;
+ unsubscribe();
+ const streamed = (events.find((event) => (event as { type: string }).type === "raw_observation") as { data: { observation: RawObservation } }).data.observation;
expect(streamed.raw).toEqual(expected);
expect(stored?.source?.toolName).toBe(streamed.toolName);
expect(stored?.source?.toolInput).toEqual(streamed.toolInput);
diff --git a/test/capture-review-fixes.test.ts b/test/capture-review-fixes.test.ts
index 2437c2fc..0974114b 100644
--- a/test/capture-review-fixes.test.ts
+++ b/test/capture-review-fixes.test.ts
@@ -1,4 +1,5 @@
import { describe, it, expect, afterEach } from "vitest";
+import { III_PINNED_VERSION } from "../src/version.js";
import { spawn } from "node:child_process";
import { createServer, type Server } from "node:http";
import { existsSync, mkdtempSync, readFileSync, readdirSync, statSync, utimesSync, writeFileSync } from "node:fs";
@@ -133,10 +134,10 @@ function statusInputs(capture: CaptureStatus | null | undefined): StatusInputs {
return {
now: new Date("2026-10-02T12:00:00.000Z"),
version: "0.9.30",
- engineVersion: "0.22.1",
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: 60,
stateBackend: "file",
- ports: { rest: 3111, streams: 3112, viewer: 3113 },
+ ports: { rest: 3111, viewer: 3113 },
health: { status: "healthy", alerts: [], notes: [], connectionState: "connected" },
circuitBreaker: { state: "closed", failures: 0 },
functionMetrics: [],
diff --git a/test/capture-spool.test.ts b/test/capture-spool.test.ts
index c42178a1..7deed339 100644
--- a/test/capture-spool.test.ts
+++ b/test/capture-spool.test.ts
@@ -213,7 +213,7 @@ describe("capture spool retention until durable", () => {
expect(parseSentMark({ status: "accepted" })).toBeNull();
expect(parseSentMark({ bootId: "../etc", durableAfterMs: 1 })).toBeNull();
expect(parseSentMark({ bootId: BOOT_A, durableAfterMs: -1 })).toBeNull();
- expect(parseSentMark({ bootId: BOOT_A, durableAfterMs: 1e12 })!.durableAfterMs).toBe(600_000);
+ expect(parseSentMark({ bootId: BOOT_A, durableAfterMs: 1e12 })!.durableAfterMs).toBe(61 * 60_000);
expect(parseSentMark(null)).toBeNull();
});
@@ -231,6 +231,15 @@ describe("capture spool retention until durable", () => {
expect(calls).toBe(0);
});
+ it("retains a capture through the longest supported state flush interval", () => {
+ const now = 1_700_000_000_000;
+ const mark = parseSentMark({ bootId: BOOT_A, durableAfterMs: 3_600_000 + 1500 })!;
+ expect(retainSent(URL, "evc_slowflush001", body("slow-flush"), mark, { dir, policy, now })).toBe(true);
+ expect(reconcileSent(URL, BOOT_A, { dir, policy, now: now + 600_000 })).toEqual({ released: 0, requeued: 0 });
+ expect(reconcileSent(URL, BOOT_A, { dir, policy, now: now + 3_600_000 })).toEqual({ released: 0, requeued: 0 });
+ expect(reconcileSent(URL, BOOT_A, { dir, policy, now: now + 3_602_000 })).toEqual({ released: 1, requeued: 0 });
+ });
+
it("re-sends a kept record with the same event id once the server restarted", async () => {
const now = Date.now();
retainSent(URL, "evc_restart00001", body("before-restart"), { bootId: BOOT_A, durableAfterMs: 60_000 }, { dir, policy, now });
diff --git a/test/cli-compose-env.test.ts b/test/cli-compose-env.test.ts
new file mode 100644
index 00000000..edf904a1
--- /dev/null
+++ b/test/cli-compose-env.test.ts
@@ -0,0 +1,58 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import { III_PINNED_VERSION } from "../src/version.js";
+
+describe.skipIf(process.platform === "win32")("CLI Compose environment", () => {
+ it("copies the selected env file instead of the unrelated home default", async () => {
+ const root = mkdtempSync(join(tmpdir(), "am-cli-compose-env-"));
+ const home = join(root, "home");
+ const dataDir = join(root, "data");
+ const binDir = join(home, ".agentmemory", "bin");
+ const customEnv = join(root, "custom.env");
+ const listeners = Array.from({ length: 3 }, () => createServer());
+ try {
+ const ports = await Promise.all(listeners.map((server) => new Promise<number>((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", () => resolve((server.address() as { port: number }).port));
+ })));
+ await Promise.all(listeners.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
+ mkdirSync(binDir, { recursive: true });
+ writeFileSync(join(binDir, "iii"), [
+ "#!/bin/sh",
+ `if [ "$1" = "--version" ]; then printf '%s\\n' 'iii ${III_PINNED_VERSION}'; exit 0; fi`,
+ "exit 1", "",
+ ].join("\n"), { mode: 0o755 });
+ writeFileSync(join(home, ".agentmemory", ".env"), "CUSTOM_SETTING=wrong-profile\n");
+ writeFileSync(customEnv, "CUSTOM_SETTING=selected-profile\nIII_NAMESPACE=wrong-namespace\n");
+ const result = await promisify(execFile)(process.execPath, ["--import", "tsx", "src/cli.ts"], {
+ cwd: resolve(import.meta.dirname, ".."),
+ env: {
+ HOME: home, USERPROFILE: home,
+ PATH: [binDir, dirname(process.execPath), "/usr/bin", "/bin"].join(delimiter),
+ CI: "1", NO_COLOR: "1",
+ AGENTMEMORY_DATA_DIR: dataDir,
+ AGENTMEMORY_ENV_FILE: customEnv,
+ AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "1000",
+ AGENTMEMORY_READY_TIMEOUT_MS: "1000",
+ III_REST_PORT: String(ports[0]), III_VIEWER_PORT: String(ports[1]), III_ENGINE_PORT: String(ports[2]),
+ },
+ timeout: 10_000,
+ }).then(() => ({ code: 0 }), (error: { code: unknown; stdout?: string; stderr?: string }) => error);
+ expect(result.code).toBe(1);
+ const filtered = join(dataDir, "compose", ".agentmemory-filtered.env");
+ expect(readFileSync(filtered, "utf8")).toBe("CUSTOM_SETTING=selected-profile\n\n");
+ const compose = parse(readFileSync(join(dataDir, "compose", "worker-compose.yaml"), "utf8"));
+ expect(compose.containers.agentmemory.env_file).toEqual([filtered]);
+ expect(compose.containers.agentmemory.environment.AGENTMEMORY_ENV_FILE).toBe(filtered);
+ } finally {
+ for (const server of listeners) server.close();
+ rmSync(root, { recursive: true, force: true });
+ }
+ }, 15_000);
+});
diff --git a/test/cli-compose-start-exit.test.ts b/test/cli-compose-start-exit.test.ts
new file mode 100644
index 00000000..113b329f
--- /dev/null
+++ b/test/cli-compose-start-exit.test.ts
@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+describe("foreground CLI startup for managed Compose", () => {
+ it("exits after publishing ready state while the detached Compose daemon owns service lifetime", () => {
+ const source = readFileSync(new URL("../src/cli.ts", import.meta.url), "utf8");
+ const ready = source.indexOf("printReadyHint();", source.indexOf("async function main()"));
+ const composeExit = source.indexOf('if (managedCompose?.kind === "compose")', ready);
+ expect(ready).toBeGreaterThan(-1);
+ expect(composeExit).toBeGreaterThan(ready);
+ expect(source.slice(composeExit, composeExit + 450)).toContain("process.exit(0)");
+ });
+});
diff --git a/test/cli-console.test.ts b/test/cli-console.test.ts
index 451d3953..428ede2b 100644
--- a/test/cli-console.test.ts
+++ b/test/cli-console.test.ts
@@ -1,60 +1,31 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
import { describe, expect, it } from "vitest";
-import {
- consoleArgs,
- defaultConsolePort,
- parseConsoleArgs,
-} from "../src/cli/console.js";
-describe("agentmemory console", () => {
- it("serves one port above the viewer so the two never collide", () => {
- expect(defaultConsolePort(3113)).toBe(3114);
- expect(defaultConsolePort(3213)).toBe(3214);
- });
-
- it("builds the pinned engine's console invocation against the resolved port quartet", () => {
- expect(
- consoleArgs({
- iiiBin: "/home/u/.agentmemory/bin/iii",
- consolePort: 3114,
- restPort: 3111,
- streamPort: 3112,
- enginePort: 49134,
- extraArgs: ["--enable-flow"],
- }),
- ).toEqual([
- "console",
- "--port",
- "3114",
- "--engine-port",
- "3111",
- "--ws-port",
- "3112",
- "--bridge-port",
- "49134",
- "--enable-flow",
- ]);
- });
-
- it("takes --console-port in both spellings and falls back to the default", () => {
- expect(parseConsoleArgs([], 3114)).toEqual({ consolePort: 3114, extraArgs: [] });
- expect(parseConsoleArgs(["--console-port", "4000"], 3114).consolePort).toBe(4000);
- expect(parseConsoleArgs(["--console-port=4001"], 3114).consolePort).toBe(4001);
- });
-
- it("drops the CLI's own global flags and forwards everything else to iii console", () => {
- const parsed = parseConsoleArgs(
- ["--port", "3211", "--instance=1", "--verbose", "--enable-flow", "--host", "0.0.0.0"],
- 3214,
- );
-
- expect(parsed).toEqual({
- consolePort: 3214,
- extraArgs: ["--enable-flow", "--host", "0.0.0.0"],
- });
- });
-
- it("rejects an unusable console port", () => {
- expect(() => parseConsoleArgs(["--console-port", "70000"], 3114)).toThrow(/between 1 and 65535/);
- expect(() => parseConsoleArgs(["--console-port"], 3114)).toThrow(/--console-port/);
+describe("agentmemory console migration", () => {
+ it.each([
+ { args: [], port: 3113 },
+ { args: ["--port", "3211"], port: 3213 },
+ { args: ["--instance", "2", "--console-port", "4014"], port: 3313 },
+ ])("prints the selected viewer without installing or launching an engine: $args", ({ args, port }) => {
+ const home = mkdtempSync(join(tmpdir(), "agentmemory-console-"));
+ try {
+ const result = spawnSync(process.execPath, [resolve("dist/cli.mjs"), "console", ...args], {
+ cwd: home,
+ env: { PATH: process.env.PATH, HOME: home, USERPROFILE: home, CI: "1", NO_COLOR: "1" },
+ encoding: "utf8",
+ timeout: 10_000,
+ });
+ expect(result.status, result.stderr).toBe(0);
+ expect(result.stdout).toContain("iii 0.25 retired the bundled engine console");
+ expect(result.stdout).toContain(`http://localhost:${port}`);
+ expect(result.stdout).toContain("agentmemory status");
+ expect(existsSync(join(home, ".agentmemory", "bin"))).toBe(false);
+ expect(existsSync(join(home, ".agentmemory", "engine-state.json"))).toBe(false);
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
});
});
diff --git a/test/cli-data-dir.test.ts b/test/cli-data-dir.test.ts
index d4058645..b60cd7ba 100644
--- a/test/cli-data-dir.test.ts
+++ b/test/cli-data-dir.test.ts
@@ -92,7 +92,7 @@ describe("resolveDataDir", () => {
const cwd = mkdtempSync(join(tmpdir(), "agentmemory-data-"));
mkdirSync(join(cwd, ".git"));
mkdirSync(join(cwd, "data"));
- writeFileSync(join(cwd, "data", "iii-config.yaml"), "");
+ writeFileSync(join(cwd, "data", "iii-config.yaml"), ""); // Legacy marker recognized during data-dir migration.
const home = "/home/alex";
const base = { cwd, home, platform: "linux" as const };
const defaultDir = join(home, ".local", "share", "agentmemory");
diff --git a/test/cli-doctor-fixes.test.ts b/test/cli-doctor-fixes.test.ts
index f7d671fb..99fab1fd 100644
--- a/test/cli-doctor-fixes.test.ts
+++ b/test/cli-doctor-fixes.test.ts
@@ -6,6 +6,7 @@
// driven by clack — exercising it would require a TTY and is out of scope.
import { describe, it, expect } from "vitest";
+import { III_PINNED_VERSION } from "../src/version.js";
import {
buildDiagnostics,
DIAGNOSTIC_IDS,
@@ -24,7 +25,7 @@ function stubCtx(overrides: Partial<DoctorContext> = {}): DoctorContext {
envPath: "/tmp/test/.agentmemory/.env",
pidfilePath: "/tmp/test/.agentmemory/iii.pid",
enginePath: "/tmp/test/.agentmemory/engine-state.json",
- pinnedVersion: "0.11.2",
+ pinnedVersion: III_PINNED_VERSION,
...overrides,
};
}
@@ -37,7 +38,7 @@ function stubEffects(overrides: Partial<DoctorEffects> = {}): DoctorEffects {
pidfilePidIsAlive: () => null,
findIiiBinary: () => "/Users/test/.local/bin/iii",
localBinIiiPath: () => "/Users/test/.local/bin/iii",
- iiiBinaryVersion: () => "0.11.2",
+ iiiBinaryVersion: () => III_PINNED_VERSION,
viewerReachable: async () => true,
runInit: async () => ({ ok: true, message: "wrote .env" }),
openEditor: async () => ({ ok: true, message: "saved" }),
@@ -120,7 +121,7 @@ describe("doctor v2 diagnostic catalog", () => {
const status = await check.check(stubCtx());
expect(status.ok).toBe(false);
expect(status.detail).toContain("0.99.99");
- expect(status.detail).toContain("0.11.2");
+ expect(status.detail).toContain(III_PINNED_VERSION);
});
it("engine-version-mismatch passes when iii matches pinned version", async () => {
@@ -146,6 +147,12 @@ describe("doctor v2 diagnostic catalog", () => {
expect(status.ok).toBe(true);
});
+ it("engine-version-mismatch passes for the recorded instance binary", async () => {
+ const diagnostics = buildDiagnostics(stubEffects({ findIiiBinary: () => "/isolated/iii", iiiBinaryVersion: (path) => path === "/isolated/iii" ? "0.24.6" : null }));
+ const check = diagnostics.find((d) => d.id === "engine-version-mismatch")!;
+ expect((await check.check(stubCtx({ pinnedVersion: "0.24.6" }))).ok).toBe(true);
+ });
+
it("stale-pidfile fails when pidfile points at a dead pid", async () => {
const diagnostics = buildDiagnostics(
stubEffects({ pidfileExists: () => true, pidfilePidIsAlive: () => false }),
diff --git a/test/cli-engine-startup.test.ts b/test/cli-engine-startup.test.ts
index fe738f14..584ba0ee 100644
--- a/test/cli-engine-startup.test.ts
+++ b/test/cli-engine-startup.test.ts
@@ -4,49 +4,28 @@ import { describe, expect, it } from "vitest";
describe("fresh native engine startup", () => {
const source = readFileSync("src/cli.ts", "utf8");
- it("routes existing and newly installed engines through one runtime config", () => {
- const prepareStart = source.indexOf("function prepareEngineLaunch");
- const prepareEnd = source.indexOf("function startIiiBin", prepareStart);
- const prepareBody = source.slice(prepareStart, prepareEnd);
- expect(prepareBody).toContain("dataDir: dataDirResolution.dataDir");
- expect(prepareBody).toContain("restPort: getRestPort()");
- expect(prepareBody).toContain("streamPort: getStreamPort()");
- expect(prepareBody).toContain("viewerPort: getConfiguredViewerPort()");
- expect(prepareBody).toContain("enginePort: getEnginePort()");
-
- const engineStart = source.indexOf("async function startEngine");
- const engineEnd = source.indexOf("async function waitForEngine", engineStart);
- const engineBody = source.slice(engineStart, engineEnd);
- expect(engineBody).not.toContain("writeRuntimeIiiConfig");
- expect(engineBody.match(/startIiiBin\(iiiBin, configPath\)/g)).toHaveLength(2);
+ it("routes new iii engines through per-instance Worker Compose without reading legacy engine config files", () => {
+ const start = source.indexOf("async function startIiiBin");
+ const end = source.indexOf("function pickCompatibleIii", start);
+ const body = source.slice(start, end);
+ expect(body).toContain("startComposeDaemon(");
+ expect(body).toContain("dataDir: dataDirResolution.dataDir");
+ expect(body).toContain("restPort: getRestPort()");
+ expect(body).toContain("viewerPort: getConfiguredViewerPort()");
+ expect(body).toContain("enginePort: getEnginePort()");
+ expect(body).not.toContain("prepareEngineLaunch(");
+ expect(body).not.toContain("iii-config.runtime.yaml");
+ expect(body).not.toContain("configPath");
+ expect(source).not.toContain("findIiiConfig");
+ expect(source).not.toContain("AGENTMEMORY_III_CONFIG");
});
- it("reports buffered engine stderr when a verbose startup times out", () => {
- const spawnStart = source.indexOf("function spawnEngineBackground");
- const spawnEnd = source.indexOf("function prepareEngineLaunch", spawnStart);
- const spawnBody = source.slice(spawnStart, spawnEnd);
- expect(spawnBody).toContain(
- "activeStartupStderr = createStartupStderrCapture()",
- );
- expect(spawnBody).toContain("activeStartupStderr.append(chunk)");
-
- const timeoutStart = source.indexOf("const ready = await waitForEngine()");
- const timeoutEnd = source.indexOf('s.stop(c.ok("iii-engine is ready"))', timeoutStart);
- expect(source.slice(timeoutStart, timeoutEnd)).toContain(
- "printCapturedStartupStderr()",
- );
-
- const demoTimeoutStart = source.indexOf("await waitForEngine()", timeoutEnd);
- const demoTimeoutEnd = source.indexOf("await import(\"./index.js\")", demoTimeoutStart);
- expect(source.slice(demoTimeoutStart, demoTimeoutEnd)).toContain(
- "printCapturedStartupStderr()",
- );
+ it("reports captured startup stderr when engine or worker startup times out", () => {
+ expect(source).toContain("function printCapturedStartupStderr()");
+ expect(source).toContain("printCapturedStartupStderr()");
});
- it("exports the complete derived port set for Docker and native launchers", () => {
- expect(source).toContain(
- 'process.env["III_STREAM_PORT"] ??=\n process.env["III_STREAMS_PORT"] ?? String(restPort + 1)',
- );
+ it("exports the complete derived port set for managed engine launchers", () => {
expect(source).toContain(
'process.env["III_VIEWER_PORT"] ??= String(restPort + 2)',
);
@@ -74,36 +53,20 @@ describe("fresh native engine startup", () => {
expect(installerBody).toContain('whichBinary("tar")');
});
- it("lets the CLI own one bundled worker and reuses a live worker", () => {
- const prepareStart = source.indexOf("function prepareEngineLaunch");
- const prepareEnd = source.indexOf("function startIiiBin", prepareStart);
- const prepareBody = source.slice(prepareStart, prepareEnd);
- expect(prepareBody).toContain(
- "rewriteBundledConfig(",
- );
- expect(prepareBody).toContain(": renderEngineConfig(rawConfig, options)");
-
- const workerStart = source.indexOf("async function startWorkerForEngineState");
- const workerEnd = source.indexOf("async function startEngine", workerStart);
- const workerBody = source.slice(workerStart, workerEnd);
- expect(workerBody).toContain("readWorkerPidfile()");
- expect(workerBody).toContain("pidAlive(workerPid)");
- expect(workerBody).toContain("startWorkerAndWait");
- expect(workerBody).toContain("engineStartsWorker: configuredEngineMayStartWorker");
- expect(workerBody).toContain('await import("./index.js")');
-
- expect(source.match(/await startWorkerForEngineState\(\)/g)).toHaveLength(5);
- expect(source).toContain('startupTimeoutMessage("worker", timeoutMs)');
- expect(source).not.toContain("waitForAgentmemoryReady(15000)");
+ it("starts Worker Compose directly without preparing a legacy native config", () => {
+ expect(source).not.toContain("function prepareEngineLaunch");
+ expect(source).not.toContain("function adoptRunningEngine");
+ expect(source).toContain("startComposeDaemon({");
+ expect(source).toContain("await startWorkerForEngineState()");
});
- it("stores lifecycle metadata per resolved instance and scopes Docker", () => {
+ it("stores lifecycle metadata per resolved instance", () => {
expect(source).toContain('runtimeMetadataPath("iii.pid")');
+ expect(source).toContain('kind: "compose"');
+ expect(source).toContain("composePid: compose.child.pid");
expect(source).toContain('runtimeMetadataPath("engine-state.json")');
expect(source).toContain('runtimeMetadataPath("worker.pid")');
expect(source).toContain('process.env["AGENTMEMORY_RUNTIME_DIR"] = selectedInstance > 0');
- expect(source).toContain("dockerProjectName(getRestPort())");
- expect(source).toContain("dockerComposeArgs(");
});
it("keeps AGENTMEMORY_URL client-only and lets local port flags win", () => {
@@ -113,55 +76,28 @@ describe("fresh native engine startup", () => {
expect(source).toContain('process.env["III_REST_PORT"] = String(base)');
});
- it("recovers the host worker for a validated Docker engine", () => {
- expect(source).toContain("function inspectOwnedDockerEngine");
- expect(source).toMatch(/"ps",\s*"-q",\s*"--all",\s*"iii-engine"/);
- expect(source).toContain('"com.docker.compose.service"');
- expect(source).toContain('record.HostConfig?.PortBindings');
- expect(source).toContain('mount.Destination === "/data"');
- expect(source).toContain('["start", inspection.containerId]');
- expect(source).toContain('["stop", "--time", "10", inspection.containerId]');
-
- const mainStart = source.indexOf("async function main()");
- const mainEnd = source.indexOf("async function apiFetch", mainStart);
- const mainBody = source.slice(mainStart, mainEnd);
- expect(mainBody).toContain("reconcilePersistedDockerEngine()");
- expect(mainBody.indexOf("reconcilePersistedDockerEngine()"))
- .toBeLessThan(mainBody.indexOf("if (await isEngineRunning() ||"));
+ it("routes persisted Docker state to the legacy recovery message without inspection", () => {
+ const ownershipStart = source.indexOf("async function assertRuntimePortOwnership");
+ const ownershipEnd = source.indexOf("function isInvokedViaNpx", ownershipStart);
+ const ownershipBody = source.slice(ownershipStart, ownershipEnd);
+ const dockerGuardStart = ownershipBody.indexOf('if (state.kind === "docker")');
+ const dockerGuardEnd = ownershipBody.indexOf(" const ownerPort", dockerGuardStart);
+ const dockerGuard = ownershipBody.slice(dockerGuardStart, dockerGuardEnd);
+ expect(dockerGuard).toContain("legacyDockerStateMessage(state)");
+ expect(dockerGuard).not.toContain("inspectOwnedDockerEngine");
+ expect(dockerGuard).not.toContain("clearEngineState");
+ expect(source).toContain("legacyDockerStateMessage(persistedState)");
});
- it("keeps canonical compatibility and rejects Docker ownership on another port", () => {
+ it("keeps canonical compatibility without inspecting or mutating Docker ownership", () => {
expect(source).toContain('function cliArgValue(name: string)');
expect(source).toContain('arg.startsWith(`${name}=`)');
expect(source).toContain("async function assertRuntimePortOwnership");
expect(source).toContain("restPort: getRestPort()");
- expect(source).toContain('inspection.status === "running" || inspection.status === "stopped"');
expect(source).not.toContain("migrateLegacyRuntimeMetadata");
expect(source).not.toContain("clearLegacyRuntimeMetadata");
});
- it("preserves Docker ownership when compose startup fails", () => {
- const spawnStart = source.indexOf("function spawnEngineBackground");
- const spawnEnd = source.indexOf("function prepareEngineLaunch", spawnStart);
- const spawnBody = source.slice(spawnStart, spawnEnd);
- expect(spawnBody).toContain("if (!isDocker)");
- expect(spawnBody).toContain("clearEngineState()");
- expect(spawnBody).not.toContain("if (!isDocker) clearEnginePidfile();\n clearEngineState();");
- });
-
- it("stops the launch instead of silently falling back to file when the redis rewrite fails", () => {
- const prepareStart = source.indexOf("function prepareEngineLaunch");
- const prepareEnd = source.indexOf("function startIiiBin", prepareStart);
- const prepareBody = source.slice(prepareStart, prepareEnd);
- expect(prepareBody).toContain("const stateBackendKind = getStateBackend();");
- expect(prepareBody).toMatch(
- /catch \(err\) \{\s*const failure = resolveLaunchRenderFailure\(stateBackendKind, err\);\s*if \(failure\.fatal\) \{\s*p\.log\.error\(failure\.message\);\s*process\.exit\(1\);\s*\}/,
- );
- expect(prepareBody).toContain(
- 'vlog(`runtime config generation failed, using bundled config verbatim: ${String(err)}`);',
- );
- });
-
it("rejects an unrecognized AGENTMEMORY_STATE_BACKEND before touching the engine", () => {
const engineStart = source.indexOf("async function startEngine");
const engineEnd = source.indexOf("async function waitForEngine", engineStart);
@@ -169,18 +105,12 @@ describe("fresh native engine startup", () => {
expect(engineBody).toMatch(
/try \{\s*stateBackendKind = getStateBackend\(\);\s*\} catch \(err\) \{\s*p\.log\.error\(err instanceof Error \? err\.message : String\(err\)\);\s*process\.exit\(1\);\s*\}/,
);
- expect(engineBody.match(/warnIfDockerIgnoresStateBackend\(stateBackendKind\)/g)).toHaveLength(2);
+ // The retired Docker-mode environment switch must not return to CLI startup.
+ expect(engineBody).not.toContain("AGENTMEMORY_USE_DOCKER");
});
- it("redacts credentials out of every engine stderr surface the CLI prints", () => {
- expect(source).toContain(
- "const stderr = redactCredentialUrls(activeStartupStderr.text().trim());",
- );
- expect(source).toContain(
- "const stderr = redactCredentialUrls(activeStartupStderr.text());",
- );
- expect(source).toContain(
- 'const output = redactCredentialUrls(`${result.stdout ?? ""}${result.stderr ?? ""}`.trim());',
- );
+ it("redacts credentials from the captured startup stderr output", () => {
+ expect(source).toContain("function printCapturedStartupStderr()");
+ expect(source).toContain("redactCredentialUrls(activeStartupStderr.text().trim())");
});
});
diff --git a/test/cli-lifecycle-safety.test.ts b/test/cli-lifecycle-safety.test.ts
index 7d199492..3992b2c5 100644
--- a/test/cli-lifecycle-safety.test.ts
+++ b/test/cli-lifecycle-safety.test.ts
@@ -1,6 +1,5 @@
import { spawnSync } from "node:child_process";
import {
- chmodSync,
existsSync,
mkdtempSync,
mkdirSync,
@@ -12,140 +11,21 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
-const sandboxes: string[] = [];
-const FULL_CONTAINER_ID =
- "a348133fe52fc5ba49b74cb0a4e36a1ec1d64827d79dc120940a96054bbe87c4";
+// A fixed port can collide with a service already running on the host.
+function freePortSync(): number {
+ const probe = spawnSync(process.execPath, ["-e", "const s=require('net').createServer().listen(0,'127.0.0.1',()=>{console.log(s.address().port);s.close()})"], { encoding: "utf-8" });
+ const port = Number(probe.stdout.trim());
+ if (!Number.isInteger(port) || port <= 0) throw new Error("failed to allocate a free REST port");
+ return port;
+}
+const sandboxes: string[] = [];
function sandbox(): string {
const path = mkdtempSync(join(tmpdir(), "agentmemory-lifecycle-"));
sandboxes.push(path);
return path;
}
-function installFakeDocker(binDir: string): void {
- mkdirSync(binDir, { recursive: true });
- const dockerPath = join(binDir, "docker");
- writeFileSync(
- dockerPath,
- `#!/usr/bin/env node
-const { appendFileSync } = require("node:fs");
-const args = process.argv.slice(2);
-appendFileSync(process.env.DOCKER_LOG, args.join(" ") + "\\n");
-const isComposePs = args[0] === "compose" && args.includes("ps");
-const isGlobalPs = args[0] === "ps";
-if (process.env.DOCKER_FAILURE_MODE === "scan" && (isComposePs || isGlobalPs)) {
- process.exit(1);
-}
-if (isComposePs || isGlobalPs) {
- if (process.env.DOCKER_FAILURE_MODE === "duplicate") {
- process.stdout.write((isComposePs ? process.env.FULL_CONTAINER_ID.slice(0, 12) : process.env.FULL_CONTAINER_ID) + "\\n");
- } else {
- process.stdout.write("candidate-id\\n");
- }
- process.exit(0);
-}
-if (args[0] === "inspect") {
- if (process.env.DOCKER_FAILURE_MODE === "duplicate") {
- process.stdout.write(JSON.stringify([{
- Id: process.env.FULL_CONTAINER_ID,
- State: { Running: false },
- Config: {
- Image: "iiidev/iii:0.11.2",
- Labels: {
- "com.docker.compose.project": "agentmemory-3111",
- "com.docker.compose.service": "iii-engine"
- }
- },
- HostConfig: { PortBindings: { "3111/tcp": [{ HostPort: "3111" }] } },
- Mounts: [{ Type: "bind", Source: process.env.DOCKER_DATA_DIR, Destination: "/data" }]
- }]));
- process.exit(0);
- }
- process.exit(1);
-}
-process.exit(0);
-`,
- );
- chmodSync(dockerPath, 0o755);
-}
-
-function runDockerStop(
- failureMode: "scan" | "inspect" | "duplicate",
- command: "stop" | "remove" = "stop",
-) {
- const root = sandbox();
- const home = join(root, "home");
- const runtimeDir = join(home, ".agentmemory");
- const dataDir = join(root, "data");
- const binDir = join(root, "bin");
- const composeFile = join(root, "docker-compose.yml");
- const dockerLog = join(root, "docker.log");
- const privateBin = join(runtimeDir, "bin", "iii");
- mkdirSync(runtimeDir, { recursive: true });
- mkdirSync(dataDir, { recursive: true });
- if (command === "remove") {
- mkdirSync(join(runtimeDir, "bin"), { recursive: true });
- writeFileSync(privateBin, "owned binary");
- }
- installFakeDocker(binDir);
- writeFileSync(
- composeFile,
- "services:\n iii-engine:\n image: iiidev/iii:0.11.2\n iii-init:\n image: busybox\n",
- );
- const statePath = join(runtimeDir, "engine-state.json");
- writeFileSync(
- statePath,
- JSON.stringify({
- kind: "docker",
- schemaVersion: 2,
- composeFile,
- projectName: "agentmemory-3111",
- engineVersion: "0.11.2",
- restPort: 3111,
- dataDir,
- ...(failureMode === "inspect" ? { containerId: "candidate-id" } : {}),
- dataMountType: "bind",
- dataMountSource: dataDir,
- preserveContainer: false,
- }),
- );
-
- const result = spawnSync(
- process.execPath,
- [
- "--import",
- "tsx",
- "src/cli.ts",
- command,
- ...(command === "remove" ? ["--force", "--keep-data"] : []),
- "--data-dir",
- dataDir,
- ],
- {
- cwd: process.cwd(),
- encoding: "utf-8",
- env: {
- ...process.env,
- HOME: home,
- USERPROFILE: home,
- CI: "1",
- PATH: `${binDir}:${process.env.PATH ?? ""}`,
- DOCKER_LOG: dockerLog,
- DOCKER_FAILURE_MODE: failureMode,
- DOCKER_DATA_DIR: dataDir,
- FULL_CONTAINER_ID,
- },
- },
- );
-
- return {
- result,
- statePath,
- privateBin,
- dockerLog: existsSync(dockerLog) ? readFileSync(dockerLog, "utf-8") : "",
- };
-}
-
function runInstanceRemove(instanceArgs = ["--instance", "1"]) {
const root = sandbox();
const home = join(root, "home");
@@ -182,6 +62,7 @@ function runInstanceRemove(instanceArgs = ["--instance", "1"]) {
}
function runNativeRemoveWithWorkerFailure() {
+ const port = freePortSync();
const root = sandbox();
const home = join(root, "home");
const runtimeDir = join(home, ".agentmemory");
@@ -200,7 +81,7 @@ function runNativeRemoveWithWorkerFailure() {
JSON.stringify({
kind: "native",
configPath: join(root, "iii-config.runtime.yaml"),
- restPort: 3111,
+ restPort: port,
}),
);
writeFileSync(
@@ -230,6 +111,8 @@ process.kill = (pid, signal) => {
"remove",
"--force",
"--keep-data",
+ "--port",
+ String(port),
],
{
cwd: process.cwd(),
@@ -260,43 +143,6 @@ afterEach(() => {
}
});
-describe("Docker lifecycle discovery", () => {
- it.each(["scan", "inspect"] as const)(
- "preserves ownership and performs no cleanup when Docker %s fails",
- (failureMode) => {
- const { result, statePath, dockerLog } = runDockerStop(failureMode);
-
- expect(result.status).toBe(1);
- expect(existsSync(statePath)).toBe(true);
- expect(dockerLog).not.toMatch(/\bcompose\b.*\brm\b/);
- expect(`${result.stdout}\n${result.stderr}`).toContain("cannot be verified");
- },
- );
-
- it("deduplicates short and full IDs for the same inspected container", () => {
- const { result, statePath, dockerLog } = runDockerStop("duplicate");
-
- expect(result.status).toBe(0);
- expect(existsSync(statePath)).toBe(true);
- expect(dockerLog).not.toMatch(/\bcompose\b.*\brm\b/);
- expect(JSON.parse(readFileSync(statePath, "utf-8")).containerId).toBe(
- FULL_CONTAINER_ID,
- );
- });
-
- it("removes shared assets while preserving validated Docker recovery state with --keep-data", () => {
- const { result, statePath, privateBin, dockerLog } = runDockerStop(
- "duplicate",
- "remove",
- );
-
- expect(result.status).toBe(0);
- expect(existsSync(statePath)).toBe(true);
- expect(existsSync(privateBin)).toBe(false);
- expect(dockerLog).not.toMatch(/\bcompose\b.*\brm\b/);
- });
-});
-
describe("native removal shutdown", () => {
it("stops the worker first and aborts all cleanup when it cannot stop", () => {
const result = runNativeRemoveWithWorkerFailure();
diff --git a/test/cli-readiness.test.ts b/test/cli-readiness.test.ts
index 75218ac4..9d3eaccf 100644
--- a/test/cli-readiness.test.ts
+++ b/test/cli-readiness.test.ts
@@ -8,6 +8,7 @@ import {
probeWorker,
startWorkerAndWait,
startupDeadline,
+ managedComposeReadinessUrl,
startupTimeoutMessage,
startupTimeouts,
waitForReadiness,
@@ -73,7 +74,7 @@ describe("startup configuration", () => {
});
});
-describe("configured worker ownership", () => {
+describe("legacy native-engine worker ownership detection", () => {
const config = (command: string) => `workers:\n - name: iii-exec\n config:\n exec:\n - ${command}\n - name: iii-http\n config:\n port: 3111\n`;
let engineCwd: string;
let emptyCwd: string;
@@ -155,7 +156,7 @@ describe("configured worker ownership", () => {
});
});
-describe("readiness deadlines", () => {
+describe("readiness deadlines and legacy native-engine compatibility", () => {
it("aborts a hung probe at the remaining budget, without a trailing retry sleep", async () => {
fakeTime();
let signal: AbortSignal | undefined;
@@ -168,11 +169,46 @@ describe("readiness deadlines", () => {
expect(vi.getTimerCount()).toBe(0);
});
+ it("bounds an HTTP probe that ignores the abort signal and retries before the outer startup deadline", async () => {
+ fakeTime();
+ let calls = 0;
+ const neverSettles = new Promise<Response>(() => {});
+ vi.stubGlobal("fetch", vi.fn(() => { calls++; return neverSettles; }));
+ const pending = waitForReadiness(startupDeadline(2500), (signal) => probeWorker("http://local", signal));
+ expect(await advance(pending, 2500)).toBe(false);
+ expect(calls).toBeGreaterThan(1);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("limits each stalled fetch probe so the readiness loop can re-evaluate promptly", async () => {
+ fakeTime();
+ let calls = 0;
+ vi.stubGlobal("fetch", vi.fn(() => { calls++; return forever<Response>(); }));
+ const pending = waitForReadiness(startupDeadline(5000), (signal) => probeEngine("http://127.0.0.1:3111", signal), { intervalMs: 250, probeTimeoutMs: 750 });
+ expect(await advance(pending, 5000)).toBe(false);
+ expect(calls).toBeGreaterThanOrEqual(5);
+ expect(calls).toBeLessThanOrEqual(6);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("does not route managed Compose readiness through a remote client endpoint", () => {
+ const explicitClientUrl = "http://[::1]:17414";
+ const readyProbeUrl = managedComposeReadinessUrl(17414);
+ expect(readyProbeUrl).not.toBe(explicitClientUrl);
+ expect(readyProbeUrl).toBe("http://127.0.0.1:17414");
+ });
+
+ it("uses the own managed Compose REST endpoint rather than an explicit client URL", () => {
+ expect(managedComposeReadinessUrl(17414)).toBe("http://127.0.0.1:17414");
+ expect(() => managedComposeReadinessUrl(0)).toThrow("Invalid managed Compose REST port");
+ expect(() => managedComposeReadinessUrl(65536)).toThrow("Invalid managed Compose REST port");
+ });
+
it("caps individual probes and keeps retries within the total budget", async () => {
fakeTime();
const probe = vi.fn(() => forever<boolean>());
expect(await advance(waitForReadiness(startupDeadline(3000), probe), 3000)).toBe(false);
- expect(probe).toHaveBeenCalledTimes(2);
+ expect(probe).toHaveBeenCalledTimes(3);
expect(performance.now()).toBe(3000);
expect(vi.getTimerCount()).toBe(0);
});
@@ -319,3 +355,10 @@ describe("worker startup ownership", () => {
expect(vi.getTimerCount()).toBe(0);
});
});
+
+describe("managed Compose readiness endpoint", () => {
+ it("does not route startup through a remote URL-client override", () => {
+ expect(managedComposeReadinessUrl(17414)).toBe("http://127.0.0.1:17414");
+ expect(managedComposeReadinessUrl(17414)).not.toBe("http://[::1]:17414");
+ });
+});
diff --git a/test/cli-remove.test.ts b/test/cli-remove.test.ts
index 27a3feea..2a83c50f 100644
--- a/test/cli-remove.test.ts
+++ b/test/cli-remove.test.ts
@@ -14,6 +14,7 @@ import {
import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { III_PINNED_VERSION } from "../src/version.js";
let sandbox: string;
@@ -22,7 +23,7 @@ function ctx(overrides: Partial<RemoveContext> = {}): RemoveContext {
home: sandbox,
runtimeDir: join(sandbox, ".agentmemory"),
dataDir: join(sandbox, ".agentmemory", "data"),
- pinnedVersion: "0.11.2",
+ pinnedVersion: III_PINNED_VERSION,
localBinIiiVersion: null,
connectManifest: null,
...overrides,
@@ -125,7 +126,7 @@ describe("buildRemovePlan", () => {
it("local-bin/iii is auto-fixable when version matches pinned", () => {
touch(".local/bin/iii", "fakebin");
const plan = buildRemovePlan(
- ctx({ localBinIiiVersion: "0.11.2" }),
+ ctx({ localBinIiiVersion: III_PINNED_VERSION }),
{ force: false, keepData: false },
);
const item = plan.find((p) => p.id === "legacy-local-bin-iii")!;
diff --git a/test/cli-status-scope.test.ts b/test/cli-status-scope.test.ts
new file mode 100644
index 00000000..ce932bc2
--- /dev/null
+++ b/test/cli-status-scope.test.ts
@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { WebSocketServer } from "ws";
+import { expect, it } from "vitest";
+
+it("does not query local Compose state when status selects an explicit URL with the same port", async () => {
+ const home = mkdtempSync(join(tmpdir(), "status-scope-"));
+ const requests: string[] = [];
+ const server = createServer((req, res) => {
+ requests.push(req.url!);
+ res.setHeader("Content-Type", "application/json");
+ res.end(JSON.stringify(req.url === "/agentmemory/health" ? { status: "healthy", version: "remote-fixture" } : {}));
+ });
+ const ws = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+ let localConnections = 0;
+ ws.on("connection", socket => { localConnections++; socket.close(); });
+ try {
+ await Promise.all([
+ new Promise<void>(done => server.listen(0, "127.0.0.1", done)),
+ new Promise<void>(done => ws.on("listening", done)),
+ ]);
+ const port = (server.address() as { port: number }).port;
+ mkdirSync(join(home, ".agentmemory"));
+ writeFileSync(join(home, ".agentmemory/engine-state.json"), JSON.stringify({
+ kind: "compose", restPort: port, engineUrl: `ws://127.0.0.1:${(ws.address() as { port: number }).port}`,
+ namespace: "local-fixture", file: join(home, "local.yaml"), binPath: "/fixture/iii", logFile: join(home, "local.log"),
+ }));
+ const result = await new Promise<{ code: number | null; output: string }>((done, reject) => {
+ const child = spawn(process.execPath, [resolve("dist/cli.mjs"), "status"], {
+ env: { PATH: process.env.PATH, HOME: home, USERPROFILE: home, AGENTMEMORY_URL: `http://127.0.0.1:${port}`, NO_COLOR: "1" },
+ timeout: 15000,
+ });
+ let output = "";
+ child.stdout.on("data", data => { output += data; });
+ child.stderr.on("data", data => { output += data; });
+ child.on("error", reject);
+ child.on("close", code => done({ code, output }));
+ });
+ expect(result.code, result.output).toBe(0);
+ expect(result.output).toContain("remote-fixture");
+ expect(requests).toContain("/agentmemory/health");
+ expect(localConnections).toBe(0);
+ expect(result.output).not.toContain("Compose");
+ } finally {
+ server.closeAllConnections();
+ await new Promise<void>(done => server.close(() => done()));
+ for (const socket of ws.clients) socket.terminate();
+ await new Promise<void>(done => ws.close(() => done()));
+ rmSync(home, { recursive: true, force: true });
+ }
+}, 20000);
diff --git a/test/cli-stop-port-mismatch.test.ts b/test/cli-stop-port-mismatch.test.ts
new file mode 100644
index 00000000..47e554d6
--- /dev/null
+++ b/test/cli-stop-port-mismatch.test.ts
@@ -0,0 +1,151 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const sandboxes: string[] = [];
+const cli = join(process.cwd(), "dist", "cli.mjs");
+
+afterEach(() => {
+ for (const path of sandboxes.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+
+function sandbox(prefix: string): string {
+ const path = mkdtempSync(join(tmpdir(), prefix));
+ sandboxes.push(path);
+ return path;
+}
+
+describe("stop port ownership", () => {
+ it("refuses saved Compose state on a different requested port without signaling the daemon", async () => {
+ const root = sandbox("agentmemory-stop-port-");
+ const home = join(root, "home");
+ const runtime = join(home, ".agentmemory");
+ const statePath = join(runtime, "engine-state.json");
+ const enginePidfile = join(runtime, "iii.pid");
+ const workerPidfile = join(runtime, "worker.pid");
+ const namespace = "agentmemory-35111";
+ const composeFile = join(root, "compose.yml");
+ mkdirSync(runtime, { recursive: true });
+ const daemon = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)", "compose", "--namespace", namespace, "--file", composeFile], {
+ cwd: process.cwd(),
+ stdio: "ignore",
+ });
+ if (!daemon.pid) throw new Error("synthetic Compose daemon failed to start");
+ const state = {
+ kind: "compose",
+ restPort: 35111,
+ viewerPort: 35113,
+ enginePort: 81134,
+ engineUrl: "http://127.0.0.1:81134",
+ namespace,
+ file: composeFile,
+ stateDir: join(root, "state"),
+ logFile: join(root, "compose.log"),
+ binPath: process.execPath,
+ composePid: daemon.pid,
+ };
+ writeFileSync(statePath, JSON.stringify(state));
+ writeFileSync(enginePidfile, "424242\n");
+ writeFileSync(workerPidfile, "424243\n");
+
+ try {
+ const result = spawnSync(process.execPath, [cli, "stop", "--port", "35121"], {
+ cwd: process.cwd(),
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ AGENTMEMORY_RUNTIME_DIR: runtime,
+ AGENTMEMORY_URL: "",
+ CI: "1",
+ },
+ });
+ expect(result.status).toBe(1);
+ expect(`${result.stdout}\n${result.stderr}`).toContain("Saved Compose lifecycle state belongs to REST port 35111");
+ expect(daemon.exitCode).toBe(null);
+ expect(readFileSync(statePath, "utf8")).toBe(JSON.stringify(state));
+ expect(readFileSync(enginePidfile, "utf8")).toBe("424242\n");
+ expect(readFileSync(workerPidfile, "utf8")).toBe("424243\n");
+ } finally {
+ if (daemon.exitCode === null) daemon.kill("SIGTERM");
+ await new Promise<void>((resolve) => daemon.once("exit", () => resolve()));
+ }
+ }, 20_000);
+});
+
+describe("configured status endpoint ownership", () => {
+ it.each([
+ { label: "remote IPv6", url: "http://[::1]:35111", expectedPrefix: "http://[::1]:35111/" },
+ { label: "local Compose", url: "", expectedPrefix: "http://localhost:35111/" },
+ ])("preserves the $label endpoint when Compose state has the same REST port", ({ url, expectedPrefix }) => {
+ const root = sandbox("agentmemory-status-endpoint-");
+ const home = join(root, "home");
+ const runtime = join(home, ".agentmemory");
+ const preload = join(root, "mock-fetch.mjs");
+ const requestLog = join(root, "requests.log");
+ const port = 35111;
+ mkdirSync(runtime, { recursive: true });
+ writeFileSync(preload, `
+ import { appendFileSync } from "node:fs";
+ globalThis.fetch = async (input) => {
+ const url = String(input);
+ appendFileSync(process.env.REQUEST_LOG, url + "\\n");
+ const path = new URL(url).pathname;
+ const body = path === "/"
+ ? "{}"
+ : path.endsWith("/livez")
+ ? JSON.stringify({ status: "ok", viewerPort: null, viewerSkipped: true })
+ : path.endsWith("/health")
+ ? JSON.stringify({ status: "healthy", version: "fixture", health: { uptimeSeconds: 1 } })
+ : path.endsWith("/sessions")
+ ? JSON.stringify({ sessions: [] })
+ : path.endsWith("/graph/stats")
+ ? JSON.stringify({ totalNodes: 0, totalEdges: 0 })
+ : path.endsWith("/memories")
+ ? JSON.stringify({ total: 0 })
+ : path.endsWith("/config/flags")
+ ? JSON.stringify({ flags: [] })
+ : JSON.stringify({ agentInitiatedSearches: 0, followupWithinWindow: 0, windowSeconds: 30 });
+ return new Response(body, { status: 200, headers: { "Content-Type": "application/json" } });
+ };
+ `);
+ const state = {
+ kind: "compose",
+ restPort: port,
+ viewerPort: port + 2,
+ enginePort: port + 46023,
+ engineUrl: "http://127.0.0.1:1",
+ namespace: "agentmemory-fixture",
+ file: join(root, "compose.yml"),
+ stateDir: join(root, "state"),
+ logFile: join(root, "compose.log"),
+ binPath: "/bin/true",
+ };
+ writeFileSync(join(runtime, "engine-state.json"), JSON.stringify(state));
+
+ const result = spawnSync(process.execPath, ["--import", preload, cli, "status"], {
+ cwd: process.cwd(),
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ AGENTMEMORY_RUNTIME_DIR: runtime,
+ AGENTMEMORY_URL: url,
+ III_REST_PORT: String(port),
+ REQUEST_LOG: requestLog,
+ CI: "1",
+ },
+ });
+ expect(result.status).toBe(0);
+ expect(`${result.stdout}\n${result.stderr}`).toContain("Connected");
+ const requests = readFileSync(requestLog, "utf8").trim().split("\n");
+ expect(requests.length).toBeGreaterThan(1);
+ expect(requests[0]).toBe(expectedPrefix);
+ expect(requests.every((requestUrl) => requestUrl.startsWith(expectedPrefix))).toBe(true);
+ }, 15_000);
+});
diff --git a/test/client-secret-resolution.test.ts b/test/client-secret-resolution.test.ts
index 5cb96e11..3f5d4023 100644
--- a/test/client-secret-resolution.test.ts
+++ b/test/client-secret-resolution.test.ts
@@ -1,5 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -18,9 +18,10 @@ const resolvers: Array<[string, Resolver]> = [
["pi", piSecret],
];
-function hasPython(): boolean {
- return spawnSync("python3", ["--version"], { stdio: "ignore" }).status === 0;
-}
+const python = (() => {
+ try { return execFileSync("python3", ["-c", "import sys; print(sys.executable)"], { encoding: "utf8" }).trim(); }
+ catch { return null; }
+})();
function hermesCredentialState(home: string): { available: boolean; reason: string } {
const script = [
@@ -32,7 +33,8 @@ function hermesCredentialState(home: string): { available: boolean; reason: stri
"provider = mod.AgentMemoryProvider()",
"print(json.dumps({'available': provider.is_available(), 'reason': provider.unavailable_reason()}))",
].join("\n");
- const result = spawnSync("python3", ["-c", script, join(process.cwd(), "integrations", "hermes", "__init__.py")], {
+ if (!python) throw new Error("python3 is unavailable");
+ const result = spawnSync(python, ["-c", script, join(process.cwd(), "integrations", "hermes", "__init__.py")], {
env: { PATH: process.env.PATH, HOME: home, HERMES_HOME: join(home, ".hermes"), AGENTMEMORY_SECRET: "process-secret-must-not-be-used" },
encoding: "utf-8",
timeout: 5_000,
@@ -111,7 +113,7 @@ describe("client secret resolution", () => {
expect(seen[0]?.Authorization).toBe("Bearer from-env-file");
});
- it.skipIf(!hasPython())("hermes fails closed when scoped credential access is unavailable", () => {
+ it.skipIf(!python)("hermes fails closed when scoped credential access is unavailable", () => {
writeSecrets('AGENTMEMORY_SECRET="from-env-file"\n');
const result = hermesCredentialState(home);
expect(result.available).toBe(false);
diff --git a/test/codex-live-daemon.test.ts b/test/codex-live-daemon.test.ts
index 7d9aa342..c161c0e7 100644
--- a/test/codex-live-daemon.test.ts
+++ b/test/codex-live-daemon.test.ts
@@ -1,16 +1,29 @@
import { afterEach, describe, expect, it } from "vitest";
import { spawn, execFileSync, type ChildProcess } from "node:child_process";
-import { mkdtempSync, readFileSync, writeFileSync, rmSync, mkdirSync, cpSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, mkdirSync, cpSync, copyFileSync, chmodSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { delimiter, join, resolve } from "node:path";
import { createServer } from "node:net";
import { createInterface } from "node:readline";
import { setTimeout as delay } from "node:timers/promises";
-import { rewriteBundledConfig } from "../src/cli/engine-launch.js";
import { III_PINNED_VERSION } from "../src/version.js";
const root = resolve(__dirname, "..");
-const engineBin = process.env.AGENTMEMORY_TEST_III;
+const engineBin = [
+ process.env.AGENTMEMORY_TEST_III,
+ ...(process.env.PATH ?? "").split(delimiter).map((directory) => join(directory, process.platform === "win32" ? "iii.exe" : "iii")),
+].filter((candidate): candidate is string => Boolean(candidate)).map((candidate) => resolve(candidate)).find((candidate) => {
+ try {
+ return execFileSync(candidate, ["--version"], { encoding: "utf8", timeout: 3000 }).trim() === III_PINNED_VERSION;
+ } catch {
+ return false;
+ }
+});
+if (process.env.AGENTMEMORY_REQUIRE_LIVE_TESTS === "1" && !engineBin) {
+ throw new Error(`Live plugin tests require iii ${III_PINNED_VERSION}; set AGENTMEMORY_TEST_III to the pinned engine binary.`);
+}
+const cliPath = join(root, "dist/cli.mjs");
+let activeRuntime: { port: number; env: NodeJS.ProcessEnv; cli: ChildProcess } | undefined;
const children = new Set<ChildProcess>();
let sandbox: string;
@@ -24,7 +37,62 @@ async function stop(child: ChildProcess) {
children.delete(child);
}
+function stopRuntime(): void {
+ if (!activeRuntime) return;
+ const { port, env } = activeRuntime;
+ try {
+ execFileSync(process.execPath, [cliPath, "stop", "--port", String(port)], {
+ cwd: sandbox,
+ env,
+ encoding: "utf8",
+ timeout: 30_000,
+ stdio: "pipe",
+ });
+ } finally {
+ activeRuntime = undefined;
+ }
+}
+
+async function cleanupRuntime(): Promise<void> {
+ if (!activeRuntime) return;
+ const { port, env, cli } = activeRuntime;
+ try {
+ stopRuntime();
+ } catch {
+ if (cli.exitCode === null && cli.signalCode === null) {
+ const exited = new Promise<void>((done) => cli.once("exit", () => done()));
+ cli.kill("SIGTERM");
+ const force = setTimeout(() => {
+ if (typeof cli.pid === "number") {
+ try { process.kill(-cli.pid, "SIGKILL"); } catch {}
+ }
+ cli.kill("SIGKILL");
+ }, 5000);
+ await exited;
+ clearTimeout(force);
+ }
+ for (const pidFile of [join(env.AGENTMEMORY_RUNTIME_DIR ?? homeFromRuntime(env), "engine-state.json")]) {
+ try {
+ const state = JSON.parse(readFileSync(pidFile, "utf8")) as { composePid?: number };
+ if (state.composePid && state.composePid !== process.pid) {
+ try { process.kill(-state.composePid, "SIGTERM"); } catch {}
+ try { process.kill(state.composePid, "SIGTERM"); } catch {}
+ await delay(1000);
+ try { process.kill(-state.composePid, "SIGKILL"); } catch {}
+ try { process.kill(state.composePid, "SIGKILL"); } catch {}
+ }
+ } catch {}
+ }
+ activeRuntime = undefined;
+ }
+}
+
+function homeFromRuntime(env: NodeJS.ProcessEnv): string {
+ return env.HOME ?? tmpdir();
+}
+
afterEach(async () => {
+ await cleanupRuntime();
await Promise.all([...children].map(stop));
if (sandbox) rmSync(sandbox, { recursive: true, force: true });
});
@@ -43,7 +111,9 @@ function launch(command: string, args: string[], cwd: string, env: NodeJS.Proces
const child = spawn(command, args, { cwd, env, stdio: "pipe" });
children.add(child);
let diagnostic = "";
- child.stderr.on("data", (data) => { diagnostic = (diagnostic + data).slice(-6000); });
+ const record = (data: Buffer) => { diagnostic = (diagnostic + data.toString()).slice(-6000); };
+ child.stdout.on("data", record);
+ child.stderr.on("data", record);
return { child, diagnostic: () => diagnostic };
}
@@ -81,37 +151,50 @@ describe.skipIf(!engineBin).each(["codex", "copilot", "antigravity"] as const)("
it("authenticates locally, captures and recovers hooks, shares memory, and persists across restart", async () => {
// vitest.config.ts isolates user configuration for the entire test process.
expect(homedir()).toContain("agentmemory-test-home-");
- expect(execFileSync(engineBin!, ["--version"], { encoding: "utf8" }).trim()).toBe(III_PINNED_VERSION);
+ if (!engineBin) throw new Error("Pinned iii engine binary is required");
+ expect(execFileSync(engineBin, ["--version"], { encoding: "utf8" }).trim()).toBe(III_PINNED_VERSION);
sandbox = mkdtempSync(join(tmpdir(), "agentmemory-live-plugin-"));
- const [restPort, streamPort, viewerPort, enginePort] = await unusedPorts();
+ const home = join(sandbox, "home");
+ const binDir = join(home, ".agentmemory", "bin");
+ mkdirSync(binDir, { recursive: true });
+ const isolatedEngine = join(binDir, process.platform === "win32" ? "iii.exe" : "iii");
+ copyFileSync(engineBin, isolatedEngine);
+ chmodSync(isolatedEngine, 0o755);
+ const [restPort, viewerPort, enginePort, metricsPort] = await unusedPorts();
const base = `http://127.0.0.1:${restPort}`;
- const secretPath = join(homedir(), ".agentmemory", "secret");
- const inherited = Object.fromEntries(Object.entries(process.env).filter(([key]) => ["PATH", "HOME", "USERPROFILE", "SYSTEMROOT", "TMPDIR", "TEMP", "LANG"].includes(key)));
- const env = { ...inherited, AGENTMEMORY_URL: base, AGENTMEMORY_DATA_DIR: join(sandbox, "state"),
- III_ENGINE_URL: `ws://127.0.0.1:${enginePort}`, III_REST_PORT: String(restPort), III_STREAM_PORT: String(streamPort),
- III_VIEWER_PORT: String(viewerPort), III_TELEMETRY_ENABLED: "false", AGENTMEMORY_RUNTIME_DIR: join(sandbox, "runtime"),
- AGENTMEMORY_AUTO_COMPRESS: "false", AGENTMEMORY_INJECT_CONTEXT: "false", AGENTMEMORY_TOOLS: "all" };
- const config = rewriteBundledConfig(readFileSync(join(root, "iii-config.yaml"), "utf8"), homedir(), process.execPath, join(root, "dist/index.mjs"), {
- dataDir: join(sandbox, "state"), saveIntervalMs: 250, ports: { restPort, streamPort, viewerPort, enginePort },
- });
- writeFileSync(join(sandbox, "iii.yaml"), config);
+ const stateDir = join(sandbox, "state");
+ const secretPath = join(home, ".agentmemory", "secret");
+ const inherited = Object.fromEntries(Object.entries(process.env).filter(([key]) => ["PATH", "SYSTEMROOT", "LANG"].includes(key)));
+ const path = `${binDir}${delimiter}${inherited.PATH ?? ""}`;
+ const env: NodeJS.ProcessEnv = { ...inherited, PATH: path, HOME: home, USERPROFILE: home, TMPDIR: tmpdir(), TEMP: tmpdir(),
+ AGENTMEMORY_URL: base, AGENTMEMORY_DATA_DIR: stateDir,
+ III_ENGINE_URL: `ws://127.0.0.1:${enginePort}`, III_REST_PORT: String(restPort),
+ III_VIEWER_PORT: String(viewerPort), AGENTMEMORY_METRICS_PORT: String(metricsPort), III_TELEMETRY_ENABLED: "false",
+ AGENTMEMORY_RUNTIME_DIR: join(home, ".agentmemory"), AGENTMEMORY_AUTO_COMPRESS: "false",
+ AGENTMEMORY_INJECT_CONTEXT: "false", AGENTMEMORY_TOOLS: "all", AGENTMEMORY_DISABLE_COMPOSE_RESTART: "1",
+ EMBEDDING_PROVIDER: "none", LLM_PROVIDER: "none", CI: "1", AGENTMEMORY_FINALIZE_IDLE_MS: "0",
+ AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300000", AGENTMEMORY_READY_TIMEOUT_MS: "300000" };
const daemon = async () => {
- const engine = launch(engineBin!, ["-c", join(sandbox, "iii.yaml"), "--no-update-check"], sandbox, env);
- engine.child.stdout.resume();
- const worker = launch(process.execPath, [join(root, "dist/index.mjs")], sandbox, env);
- worker.child.stdout.resume();
- const deadline = Date.now() + 30_000;
+ const cli = launch(process.execPath, [cliPath, "--port", String(restPort)], sandbox, env);
+ activeRuntime = { port: restPort, env, cli: cli.child };
+ const deadline = Date.now() + 300_000;
while (Date.now() < deadline) {
try {
- const secret = readFileSync(secretPath, "utf8").trim();
- const res = await fetch(`${base}/agentmemory/mcp/tools`, { headers: { authorization: `Bearer ${secret}` }, signal: AbortSignal.timeout(1000) });
- if (res.ok) return { engine: engine.child, worker: worker.child };
+ const res = await fetch(`${base}/agentmemory/livez`, { signal: AbortSignal.timeout(1000) });
+ if (res.ok) {
+ await res.body?.cancel();
+ if (readFileSync(secretPath, "utf8").trim()) return { cli: cli.child };
+ }
+ await res.body?.cancel();
} catch {}
- if (engine.child.exitCode !== null || worker.child.exitCode !== null) break;
+ if (cli.child.exitCode !== null) break;
await delay(250);
}
- throw new Error(`Daemon failed to become ready:\n${engine.diagnostic()}\n${worker.diagnostic()}`);
+ let composeLog = "";
+ try { composeLog = readFileSync(join(home, ".agentmemory", `compose-${restPort}.log`), "utf8"); } catch {}
+ throw new Error(`Compose daemon failed to become ready:\n${cli.diagnostic()}\n${composeLog.slice(-6000)}`);
};
+ if (host === "codex") execFileSync(process.execPath, [join(root, "scripts/plugins/package-codex.mjs")], { cwd: root, timeout: 30_000, stdio: "pipe" });
const packaged = host === "codex" ? join(root, "dist/plugins/agentmemory-codex-local") : join(sandbox, `${host} plugin`);
if (host !== "codex") cpSync(join(root, "plugin"), packaged, { recursive: true });
const configPath = join(packaged, ".mcp.json");
@@ -140,10 +223,10 @@ describe.skipIf(!engineBin).each(["codex", "copilot", "antigravity"] as const)("
const sessionId = `ses_${token}`;
let step = 0;
const hook = async (name: string, input: Record<string, unknown>) => {
- const event = { "session-start": "PreInvocation", "post-tool-use": "PostToolUse", stop: "Stop" }[name];
+ const event = { "session-start": "PreInvocation", "post-tool-use": "PostToolUse", stop: host === "antigravity" ? "Stop" : host === "codex" ? "Stop" : "SessionEnd" }[name];
const args = host === "antigravity"
? [join(packaged, "scripts/antigravity-bridge.mjs"), event!]
- : [join(packaged, `scripts/${name}.mjs`)];
+ : [join(packaged, `scripts/${host === "copilot" && name === "stop" ? "session-end" : name}.mjs`)];
const { child, diagnostic } = launch(process.execPath, args, cwd, env);
child.stdout.resume();
const exit = new Promise<number | null>((done) => child.once("exit", done));
@@ -157,6 +240,8 @@ describe.skipIf(!engineBin).each(["codex", "copilot", "antigravity"] as const)("
delete payload.tool_response;
}
}
+ if (host === "codex" && name === "stop") payload.session_id = sessionId;
+ if (host === "copilot" && name === "stop") { payload.sessionId = sessionId; delete payload.session_id; }
if (host === "antigravity") {
payload.conversationId = sessionId;
payload.workspacePaths = [cwd];
@@ -191,8 +276,8 @@ describe.skipIf(!engineBin).each(["codex", "copilot", "antigravity"] as const)("
const prompt = await codex.request("prompts/get", { name: "recall_context", arguments: { task_description: token } });
expect(prompt.result.messages.length).toBeGreaterThan(0);
await delay(1000);
- await stop(running.worker);
- await stop(running.engine);
+ stopRuntime();
+ await stop(running.cli);
const failed = await codex.request("tools/call", { name: "memory_save", arguments: { content: "must not fallback" } });
expect(failed.result.isError).toBe(true);
const offlineMarker = `offlinecapture${Date.now()}`;
@@ -220,7 +305,7 @@ describe.skipIf(!engineBin).each(["codex", "copilot", "antigravity"] as const)("
for (const id of ids) expect(remaining).not.toContain(id);
await stop(codex.child);
await stop(claude.child);
- await stop(running.worker);
- await stop(running.engine);
- }, 90_000);
+ stopRuntime();
+ await stop(running.cli);
+ }, 600_000);
});
diff --git a/test/codex-local-package.test.ts b/test/codex-local-package.test.ts
index 544f2732..b3fc9f8c 100644
--- a/test/codex-local-package.test.ts
+++ b/test/codex-local-package.test.ts
@@ -14,6 +14,7 @@ const requests: Array<{ path: string; method: string; body: any }> = [];
let server: Server;
let url: string;
let extracted: string;
+let pluginOut = "";
let mode: "ok" | "unauthorized" | "invalid-json" | "redirect" = "ok";
let child: ChildProcessWithoutNullStreams;
let request: (method: string, params?: Record<string, unknown>) => Promise<any>;
@@ -67,10 +68,11 @@ beforeAll(async () => {
if (!config) throw new Error("Missing plugin bridge build configuration");
await build({ ...config, config: false });
`], { cwd: root });
- execFileSync(process.execPath, ["scripts/plugins/package-codex.mjs"], { cwd: root });
+ pluginOut = mkdtempSync(join(tmpdir(), "agentmemory-codex-package-"));
+ execFileSync(process.execPath, ["scripts/plugins/package-codex.mjs"], { cwd: root, env: { ...process.env, AGENTMEMORY_PLUGIN_OUT_DIR: pluginOut } });
const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
extracted = mkdtempSync(join(tmpdir(), "agentmemory plugin with spaces "));
- execFileSync("unzip", ["-q", join(root, `dist/plugins/agentmemory-codex-local-${version}.zip`), "-d", extracted]);
+ execFileSync("unzip", ["-q", join(pluginOut, `agentmemory-codex-local-${version}.zip`), "-d", extracted]);
server = createServer(async (req, res) => {
let text = "";
for await (const chunk of req) text += chunk;
@@ -103,6 +105,7 @@ beforeAll(async () => {
}, 20_000);
afterAll(async () => {
+ if (pluginOut) rmSync(pluginOut, { recursive: true, force: true });
child?.kill();
if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
if (extracted) rmSync(extracted, { recursive: true, force: true });
@@ -248,7 +251,7 @@ describe("Codex release packaging", () => {
it("excludes lifecycle hooks from the review ZIP but retains MCP and skills", () => {
const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
- const archive = join(root, `dist/plugins/agentmemory-codex-review-${version}.zip`);
+ const archive = join(pluginOut, `agentmemory-codex-review-${version}.zip`);
const listing = execFileSync("unzip", ["-Z1", archive], { encoding: "utf8" });
expect(listing).not.toMatch(/^hooks\//m);
expect(listing).not.toContain("scripts/session-start.mjs");
@@ -262,7 +265,7 @@ describe("Codex release packaging", () => {
it("builds a skills-only ZIP with no MCP server, hooks, or scripts for the directory's skills path", () => {
const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
- const archive = join(root, `dist/plugins/agentmemory-codex-skills-${version}.zip`);
+ const archive = join(pluginOut, `agentmemory-codex-skills-${version}.zip`);
const listing = execFileSync("unzip", ["-Z1", archive], { encoding: "utf8" });
expect(listing).not.toContain(".mcp.json");
expect(listing).not.toMatch(/^(hooks|scripts)\//m);
diff --git a/test/compose-control.test.ts b/test/compose-control.test.ts
new file mode 100644
index 00000000..dfb6d76e
--- /dev/null
+++ b/test/compose-control.test.ts
@@ -0,0 +1,111 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const temp = mkdtempSync(join(tmpdir(), "compose-state-error-"));
+afterEach(() => rmSync(temp, { recursive: true, force: true }));
+import { composeEnvironment, composeRegistryFailureMessage, composeStateRegistryFailure, composeWorkerFailureSummary, ownedComposeProject, readComposeLogFromOffset, startComposeDaemon, type ComposeStatus } from "../src/cli/compose-control.js";
+
+describe("Compose control plane", () => {
+ it("does not leak arbitrary machine credentials to the Compose daemon", () => {
+ const env = composeEnvironment({
+ HOME: "/tmp/home",
+ PATH: "/bin",
+ ANTHROPIC_API_KEY: "must-not-leak",
+ OPENAI_API_KEY: "must-not-leak",
+ III_URL: "ws://foreign-engine",
+ AGENTMEMORY_REDIS_URL: "redis://secret",
+ MALLOC_ARENA_MAX: "10",
+ AGENTMEMORY_TOOLS: "core",
+ AGENTMEMORY_VIEWER_HOST: "127.0.0.1",
+ VIEWER_ALLOWED_HOSTS: "example.test",
+ VIEWER_ALLOWED_ORIGINS: "https://example.test",
+ }, "/tmp/state");
+ expect(env).toMatchObject({ HOME: "/tmp/home", PATH: "/bin", III_COMPOSE_STATE_DIR: "/tmp/state", III_TELEMETRY_ENABLED: "false" });
+ expect(env.MALLOC_ARENA_MAX).toBe(process.platform === "linux" ? "2" : "10");
+ expect(env).not.toHaveProperty("ANTHROPIC_API_KEY");
+ expect(env).not.toHaveProperty("III_URL");
+ expect(env).not.toHaveProperty("AGENTMEMORY_REDIS_URL");
+ expect(env).toMatchObject({ AGENTMEMORY_TOOLS: "core", AGENTMEMORY_VIEWER_HOST: "127.0.0.1", VIEWER_ALLOWED_HOSTS: "example.test", VIEWER_ALLOWED_ORIGINS: "https://example.test" });
+ });
+
+ it("turns a registry resolution failure into a quick actionable CLI diagnostic", () => {
+ const failure = composeRegistryFailureMessage("error[REGISTRY_UNREACHABLE]: container 'state': cannot reach the registry");
+ expect(failure).toContain("Worker registry unavailable while resolving state/http");
+ expect(failure).toContain("retry later");
+ expect(failure).toContain("AGENTMEMORY_WORKER_BIN_DIR");
+ expect(failure).not.toMatch(/set AGENTMEMORY_WORKER_BIN_DIR.*set AGENTMEMORY_WORKER_BIN_DIR/i);
+ expect(composeRegistryFailureMessage("STARTUP_TIMEOUT: a worker did not register")).toBeNull();
+ expect(composeRegistryFailureMessage("REGISTRY_ERROR", "/tmp/workers")).toContain("/tmp/workers");
+ const realistic = composeRegistryFailureMessage("error[E100]: Registry error: registry returned HTTP 504 while resolving package api.workers.iii.dev/[email protected]");
+ expect(realistic).toContain("Worker registry unavailable while resolving state/http");
+ const compose502 = composeRegistryFailureMessage("error[PACKAGE_DOWNLOAD_FAILED]: container 'http': could not download https://api.workers.iii.dev/download/http/0.22.6/x86_64-unknown-linux-gnu: HTTP status server error (504 Gateway Timeout) for url (https://api.workers.iii.dev/download/http/0.22.6/x86_64-unknown-linux-gnu)");
+ expect(compose502).toContain("Worker registry unavailable while resolving state/http");
+ expect(composeRegistryFailureMessage("package resolution failed: registry HTTP 504")).not.toBeNull();
+ expect(composeRegistryFailureMessage("Compose exited with code 1")).toBeNull();
+ expect(composeRegistryFailureMessage("container 'state': invalid Redis URL")).toBeNull();
+ expect(composeRegistryFailureMessage("port 3111 is already in use")).toBeNull();
+ expect(composeRegistryFailureMessage("state: failed; last_error=exited unexpectedly: status: exit code: 1")).toBeNull();
+ expect(composeRegistryFailureMessage("error[PACKAGE_DOWNLOAD_FAILED]: registry returned HTTP 503")).not.toBeNull();
+ });
+
+ it("leaves ordinary worker errors available for their own diagnostic", () => {
+ const detail = "http: invalid Redis URL\nRecent Compose output:\nworker exited with code 1";
+ expect(composeRegistryFailureMessage(detail)).toBeNull();
+ expect(detail).toContain("invalid Redis URL");
+ expect(detail).toContain("Recent Compose output:");
+ });
+
+ it("ignores registry failures from previous Compose log runs", () => {
+ mkdirSync(temp, { recursive: true });
+ const log = join(temp, "compose.log");
+ const oldRun = "error[REGISTRY_UNREACHABLE]: cannot reach the registry\n";
+ const currentRun = "Starting Worker Compose\nworker is ready\n";
+ writeFileSync(log, oldRun + currentRun);
+ const currentLog = readComposeLogFromOffset(log, Buffer.byteLength(oldRun));
+ expect(currentLog).toBe(currentRun);
+ expect(composeRegistryFailureMessage(currentLog)).toBeNull();
+ });
+
+ it("recognizes the real Compose state error after daemon logs have closed", () => {
+ const projectFile = join(temp, "worker-compose.yaml");
+ const stateDir = join(temp, "compose-state", "project", "instance");
+ mkdirSync(stateDir, { recursive: true });
+ writeFileSync(join(stateDir, "state.json"), JSON.stringify({
+ compose_path: projectFile,
+ namespace: "agentmemory-3511",
+ containers: {
+ state: { pid: 101, status: "failed", last_error: "exited unexpectedly (status: 1)" },
+ http: { pid: 102, status: "failed", last_error: "container 'http': cannot reach the registry at https://api.workers.iii.dev: registry returned HTTP 504" },
+ },
+ }));
+ const failure = composeStateRegistryFailure(temp, projectFile);
+ expect(failure).toContain("container 'http': cannot reach the registry");
+ expect(composeStateRegistryFailure(temp, join(temp, "other-compose.yaml"))).toBeNull();
+ });
+
+ it("keeps the Compose daemon log under the durable per-user metadata root", () => {
+ const source = readFileSync(new URL("../src/cli.ts", import.meta.url), "utf8");
+ expect(source).toContain('logFile: join(homedir(), ".agentmemory", `compose-${getRestPort()}.log`)');
+ });
+
+ it("summarizes exhausted worker restart attempts for CLI status", () => {
+ expect(composeWorkerFailureSummary(null)).toBeNull();
+ expect(composeWorkerFailureSummary({ containers: [
+ { container: "state", state: "ready" },
+ { container: "agentmemory", state: "failed", last_error: "restart attempts exhausted (5/5): exited unexpectedly" },
+ { container: "http", state: "failed" },
+ ] })).toBe("agentmemory: restart attempts exhausted (5/5): exited unexpectedly\nhttp: failed after restart attempts were exhausted");
+ });
+
+ it("accepts the current Compose status payload with a project at its top level", () => {
+ const status: ComposeStatus = { file: "/tmp/worker-compose.yaml", state_dir: "/tmp/state", containers: [{ container: "state", state: "ready" }] };
+ expect(ownedComposeProject(status, "/tmp/worker-compose.yaml")).toBe(status);
+ });
+
+ it("finds the owned project in a daemon status projects list", () => {
+ const project = { file: "/tmp/worker-compose.yaml" };
+ expect(ownedComposeProject({ projects: [project] }, "/tmp/worker-compose.yaml")).toBe(project);
+ });
+});
diff --git a/test/compose-process.test.ts b/test/compose-process.test.ts
new file mode 100644
index 00000000..2b31cf00
--- /dev/null
+++ b/test/compose-process.test.ts
@@ -0,0 +1,42 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readUnixProcessExecutable, sameResolvedExecutable } from "../src/cli/compose-process.js";
+
+const children: ChildProcess[] = [];
+const temporaryDirectories: string[] = [];
+
+afterEach(() => {
+ for (const child of children.splice(0)) {
+ child.kill("SIGKILL");
+ }
+ for (const directory of temporaryDirectories.splice(0)) {
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+describe("Compose process executable identity", () => {
+ it.skipIf(process.platform === "win32")("rejects a live PID running another binary", async () => {
+ const child = spawn("/bin/sleep", ["30"], { stdio: "ignore" });
+ children.push(child);
+ await new Promise<void>((resolve, reject) => {
+ child.once("spawn", resolve);
+ child.once("error", reject);
+ });
+ expect(child.pid).toBeDefined();
+ const os = process.platform === "darwin" ? "darwin" : "linux";
+ const executable = readUnixProcessExecutable(child.pid!, os);
+ expect(executable).not.toBe("");
+ expect(sameResolvedExecutable(executable, process.execPath)).toBe(false);
+ });
+
+ it("accepts a configured executable through a symlink", () => {
+ const directory = mkdtempSync(join(tmpdir(), "am-compose-bin-"));
+ temporaryDirectories.push(directory);
+ const link = join(directory, "node");
+ symlinkSync(process.execPath, link);
+ expect(sameResolvedExecutable(process.execPath, link)).toBe(true);
+ });
+});
diff --git a/test/compose-project.test.ts b/test/compose-project.test.ts
new file mode 100644
index 00000000..67cd1284
--- /dev/null
+++ b/test/compose-project.test.ts
@@ -0,0 +1,331 @@
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { parse } from "yaml";
+import { composeEnvironment } from "../src/cli/compose-control.js";
+import { COMPOSE_WORKER_VERSIONS, composeNamespace, renderWorkerCompose, shellCommand, shellQuote, writeWorkerCompose } from "../src/cli/compose-project.js";
+
+const root = mkdtempSync(join(tmpdir(), "agentmemory-compose-"));
+const rootUrl = `path://${root.replaceAll("\\", "/")}`;
+afterEach(() => {
+ rmSync(root, { recursive: true, force: true });
+ vi.unstubAllEnvs();
+});
+const options = (overrides: Record<string, unknown> = {}) => ({
+ ports: { restPort: 3511, viewerPort: 3513, enginePort: 49534 },
+ dataDir: join(root, "data"),
+ projectRoot: join(root, "pkg"),
+ nodeBin: "/opt/node/bin/node",
+ homeDir: join(root, "home"),
+ startupTimeoutMs: 300_000,
+ linux: true,
+ ...overrides,
+});
+
+describe("Worker Compose project", () => {
+ it("pins registry workers and configures the isolated engine, state and HTTP", () => {
+ const text = renderWorkerCompose(options());
+ expect(text).toContain("namespace: agentmemory-3511");
+ expect(text).toContain("url: ws://127.0.0.1:49534");
+ expect(text).toContain("iii-worker-manager:");
+ expect(text).toContain("directory: '");
+ expect(text).toContain(`worker: 'package://api.workers.iii.dev/state'\n version: '${COMPOSE_WORKER_VERSIONS.state}'`);
+ expect(text).toContain(`worker: 'package://api.workers.iii.dev/http'\n version: '${COMPOSE_WORKER_VERSIONS.http}'`);
+ expect(text).not.toContain("dependencies:");
+ expect(text).not.toContain(" configuration: latest");
+ expect(text).toContain("save_interval_ms: 2000");
+ expect(text.match(/condition: on-failure/g)).toHaveLength(3);
+ expect(text).toContain("default_timeout: 180000");
+ expect(text).toContain("allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]");
+ expect(text).toContain("start_after: [state, http]");
+ expect(text).toContain("required_default: true");
+ expect(text.match(/condition: on-failure/g)).toHaveLength(3);
+ expect(text.match(/max_attempts: 5/g)).toHaveLength(3);
+ expect(text.match(/delay: 500ms/g)).toHaveLength(3);
+ expect(text.match(/max_delay: 30s/g)).toHaveLength(3);
+ expect(text.match(/window: 60s/g)).toHaveLength(3);
+ for (const retired of ["iii-stream", "iii-pubsub", "iii-http", "iii-state", "queue"]) expect(text).not.toContain(retired);
+ });
+
+ it("quotes worker shell commands correctly on POSIX and Windows", () => {
+ const weird = "/tmp/Program Files/worker 'one';$(touch /tmp/should-not-exist)";
+ const posix = shellCommand(weird, ["arg with spaces", "x;$()|&<>*?[]\\\""], false);
+ expect(posix).toContain(`\'"\'"\'`);
+ expect(shellQuote("C:\\Program Files\\Worker & Tools\\node.exe", true)).toBe(`"C:\\Program Files\\Worker & Tools\\node.exe"`);
+ expect(shellCommand("C:\\Program Files\\Node Runtime\\node.exe", ["dist/index.mjs"], true)).toBe(`""C:\\Program Files\\Node Runtime\\node.exe" "dist/index.mjs""`);
+ expect(shellQuote("100%", true)).toBe('"100%%"');
+ });
+
+ it("executes generated commands through sh -c even with spaces and metacharacters", () => {
+ const { spawnSync } = require("node:child_process") as typeof import("node:child_process");
+ const dir = join(root, "Node Runtime & (stable)");
+ mkdirSync(dir, { recursive: true });
+ const node = join(dir, "node; safe");
+ writeFileSync(node, "#!/bin/sh\nprintf '%s' \"$1\"\n", { mode: 0o755 });
+ chmodSync(node, 0o755);
+ const binDir = join(dir, "Local Workers & (safe)");
+ mkdirSync(binDir, { recursive: true });
+ const workerBins = {} as Record<string, string>;
+ for (const name of ["state", "http"]) {
+ workerBins[name] = join(binDir, name);
+ writeFileSync(workerBins[name]!, "#!/bin/sh\nprintf '%s\\n' \"$0\"\n", { mode: 0o755 });
+ chmodSync(workerBins[name]!, 0o755);
+ }
+ const rendered = renderWorkerCompose(options({ nodeBin: node, workerBinDir: binDir, workerBinDirIsAbsolute: true }));
+ const parsed = parse(rendered) as { containers: Record<string, { scripts: { run: string } }> };
+ for (const [key, bin] of [["state", workerBins.state!], ["http", workerBins.http!], ["agentmemory", node]] as const) {
+ const run = parsed.containers[key]!.scripts.run;
+ const { status, stdout } = spawnSync("sh", ["-c", run], { encoding: "utf8", env: process.env });
+ expect(status).toBe(0);
+ expect(stdout).toBe(key === "agentmemory" ? "dist/index.mjs" : `${bin}\n`);
+ }
+ const command = shellCommand(node, ["value with spaces;$(false)"], false);
+ const result = spawnSync("sh", ["-c", command], { encoding: "utf8" });
+ expect(result.status).toBe(0);
+ expect(result.stdout).toBe("value with spaces;$(false)");
+ });
+
+ it("forwards CLI and viewer overrides from the shell ahead of env-file values", () => {
+ const text = renderWorkerCompose(options({ workerEnvironment: {
+ AGENTMEMORY_TOOLS: "core", AGENTMEMORY_VIEWER_HOST: "127.0.0.1",
+ VIEWER_ALLOWED_HOSTS: "example.test:3513", VIEWER_ALLOWED_ORIGINS: "https://example.test",
+ } }));
+ for (const [key, value] of Object.entries({ AGENTMEMORY_TOOLS: "core", AGENTMEMORY_VIEWER_HOST: "127.0.0.1", VIEWER_ALLOWED_HOSTS: "example.test:3513", VIEWER_ALLOWED_ORIGINS: "https://example.test" })) {
+ expect(text).toContain(`${key}: '${value}'`);
+ }
+ expect(composeEnvironment({ AGENTMEMORY_TOOLS: "core", VIEWER_ALLOWED_HOSTS: "example.test" }, "/tmp/state")).toMatchObject({ AGENTMEMORY_TOOLS: "core", VIEWER_ALLOWED_HOSTS: "example.test" });
+ });
+
+ it("gives CLI/shell tool and viewer settings precedence over conflicting env-file values", () => {
+ const envPath = join(root, "precedence.env");
+ mkdirSync(root, { recursive: true });
+ writeFileSync(envPath, [
+ "AGENTMEMORY_TOOLS=all",
+ "AGENTMEMORY_VIEWER_HOST=0.0.0.0",
+ "VIEWER_ALLOWED_HOSTS=old.example.test",
+ "VIEWER_ALLOWED_ORIGINS=https://old.example.test",
+ "" ,
+ ].join("\n"));
+ const text = renderWorkerCompose(options({ envFile: envPath, workerEnvironment: {
+ AGENTMEMORY_TOOLS: "core", AGENTMEMORY_VIEWER_HOST: "127.0.0.1",
+ VIEWER_ALLOWED_HOSTS: "new.example.test", VIEWER_ALLOWED_ORIGINS: "https://new.example.test",
+ } }));
+ const { containers } = parse(text) as { containers: Record<string, { environment: Record<string, string>; env_file: string[] }> };
+ const app = containers.agentmemory!;
+ const fileValues = Object.fromEntries(readFileSync(envPath, "utf8").trim().split("\n").map((line) => line.split("=") as [string, string]));
+ const effective = { ...fileValues, ...app.environment };
+ expect(effective).toMatchObject({
+ AGENTMEMORY_TOOLS: "core", AGENTMEMORY_VIEWER_HOST: "127.0.0.1",
+ VIEWER_ALLOWED_HOSTS: "new.example.test", VIEWER_ALLOWED_ORIGINS: "https://new.example.test",
+ });
+ expect(app.env_file).toHaveLength(1);
+ });
+
+ it("uses the forwarded tools setting for the effective MCP tool list", async () => {
+ const text = renderWorkerCompose(options({ workerEnvironment: { AGENTMEMORY_TOOLS: "core" } }));
+ const app = (parse(text) as { containers: Record<string, { environment: Record<string, string> }> }).containers.agentmemory!;
+ const { getVisibleTools } = await import("../src/mcp/tools-registry.js");
+ const previous = process.env.AGENTMEMORY_TOOLS;
+ process.env.AGENTMEMORY_TOOLS = app.environment.AGENTMEMORY_TOOLS;
+ try { expect(getVisibleTools()).toHaveLength(8); }
+ finally { if (previous === undefined) delete process.env.AGENTMEMORY_TOOLS; else process.env.AGENTMEMORY_TOOLS = previous; }
+ });
+
+ it("uses local worker binaries when requested and emits explicit path worker commands", () => {
+ const text = renderWorkerCompose(options({ workerBinDir: "/opt/am/workers-local" }));
+ expect(text).toContain(`worker: '${rootUrl}/data/compose/local-workers/state'`);
+ expect(text).toContain("local-workers/state");
+ const parsed = parse(text) as { containers: Record<string, { scripts: { run: string } }> };
+ expect(parsed.containers.state!.scripts.run).toBe("'/opt/am/workers-local/state'");
+ expect(parsed.containers.http!.scripts.run).toBe("'/opt/am/workers-local/http'");
+ expect(text).not.toContain("version: '");
+ expect(text).not.toContain("file_path: '/opt/am/workers-local");
+ });
+
+ it("uses and validates the configured state flush interval", () => {
+ expect(renderWorkerCompose(options({ workerEnvironment: { AGENTMEMORY_STATE_SAVE_INTERVAL_MS: "9000" } }))).toContain("save_interval_ms: 9000");
+ expect(renderWorkerCompose(options())).toContain("save_interval_ms: 2000");
+ for (const invalid of ["nope", "99", "3600001", "1.5"]) {
+ expect(() => renderWorkerCompose(options({ workerEnvironment: { AGENTMEMORY_STATE_SAVE_INTERVAL_MS: invalid } }))).toThrow(/AGENTMEMORY_STATE_SAVE_INTERVAL_MS/);
+ }
+ });
+
+ it("honors disableRestartPolicy for every worker", () => {
+ const disabled = parse(renderWorkerCompose(options({ disableRestartPolicy: true }))) as {
+ containers: Record<string, { restart: string }>;
+ };
+ expect(Object.values(disabled.containers).map((container) => container.restart)).toEqual(["no", "no", "no"]);
+ });
+
+ it("passes configured embedding credentials/settings only to the application container", () => {
+ const text = renderWorkerCompose(options({ workerEnvironment: { EMBEDDING_PROVIDER: "openai", OPENAI_API_KEY: "fake-gate-key", OPENAI_BASE_URL: "http://127.0.0.1:4555", ANTHROPIC_API_KEY: "ignored" } }));
+ const app = text.slice(text.indexOf(" agentmemory:"));
+ expect(app).toContain("EMBEDDING_PROVIDER: 'openai'");
+ expect(app).toContain("OPENAI_API_KEY: 'fake-gate-key'");
+ expect(app).toContain("OPENAI_BASE_URL: 'http://127.0.0.1:4555'");
+ expect(text.slice(0, text.indexOf("containers:")).concat(text.slice(text.indexOf(" state:"), text.indexOf(" agentmemory:")))).not.toContain("fake-gate-key");
+ });
+
+ it("preserves memory policy, provider and durability overrides in native and Docker workers", async () => {
+ const settings = {
+ FALLBACK_PROVIDERS: "openai,gemini",
+ OPENROUTER_EMBEDDING_MODEL: "custom/embedding",
+ OPENAI_API_VERSION: "2024-10-21",
+ MINIMAX_BASE_URL: "https://example.test/anthropic",
+ AGENTMEMORY_LLM_TIMEOUT_MS: "45000",
+ AGENTMEMORY_CAPTURE_INBOX_MAX: "1234",
+ AGENTMEMORY_EXPORT_ROOT: "/tmp/exports",
+ AGENTMEMORY_IMPORT_ROOT: "/tmp/imports",
+ AGENTMEMORY_TOOLS: "core",
+ AGENTMEMORY_INDEX_SAVE_INTERVAL_MS: "45000",
+ AGENTMEMORY_VECTOR_BUCKET_SIZE: "250",
+ AGENTMEMORY_VECTOR_BACKFILL_MAX: "100",
+ CONSOLIDATION_DECAY_DAYS: "90",
+ CONSOLIDATION_INTERVAL_MS: "900000",
+ GRAPH_EXTRACTION_BATCH_SIZE: "5",
+ AUTO_FORGET_ENABLED: "false",
+ LESSON_DECAY_ENABLED: "false",
+ INSIGHT_DECAY_ENABLED: "false",
+ };
+ const native = parse(renderWorkerCompose(options({ workerEnvironment: {
+ ...settings, UNRELATED_SECRET: "not-for-the-worker", III_NAMESPACE: "wrong",
+ } })));
+ const docker = parse(readFileSync(new URL("../deploy/runtime/worker-compose.yaml", import.meta.url), "utf8"));
+ const dockerService = parse(readFileSync(new URL("../docker-compose.yml", import.meta.url), "utf8")).services.agentmemory;
+ const coolify = parse(readFileSync(new URL("../deploy/coolify/docker-compose.yml", import.meta.url), "utf8")).services.agentmemory;
+ expect(native.containers.agentmemory.environment).toMatchObject(settings);
+ expect(native.containers.agentmemory.environment).not.toHaveProperty("UNRELATED_SECRET");
+ expect(native.containers.agentmemory.environment).not.toHaveProperty("III_NAMESPACE");
+ for (const key of Object.keys(settings)) {
+ expect(docker.containers.agentmemory.environment[key]).toBe("${" + key + ":-}");
+ expect(dockerService.environment[key]).toBe("${" + key + ":-}");
+ expect(coolify.environment[key]).toBe("${" + key + ":-}");
+ }
+ vi.stubEnv("AGENTMEMORY_ENV_FILE", join(root, "missing.env"));
+ for (const [key, value] of Object.entries(native.containers.agentmemory.environment)) {
+ vi.stubEnv(key, value as string);
+ }
+ vi.resetModules();
+ const config = await import("../src/config.js");
+ expect(config.loadFallbackConfig().providers).toEqual(["openai", "gemini"]);
+ expect(config.getConsolidationDecayDays()).toBe(90);
+ expect(config.getConsolidationIntervalMs()).toBe(900000);
+ expect(config.getIndexSaveIntervalMs()).toBe(45000);
+ expect(config.getVectorBucketSize()).toBe(250);
+ expect(config.getVectorBackfillMax()).toBe(100);
+ expect(config.getGraphBatchSize()).toBe(5);
+ });
+
+ it("supports Redis state without leaking Redis configuration into the daemon", () => {
+ const text = renderWorkerCompose(options({ stateBackend: { kind: "redis", redisUrl: "redis://user:p'ass@localhost:6379" } }));
+ expect(text).toContain("name: redis");
+ expect(text).toContain("redis_url: 'redis://user:p''ass@localhost:6379'");
+ expect(text).not.toContain("state_store.db");
+ });
+
+ it("includes env_file only when present and quotes paths safely", () => {
+ const envPath = join(root, "home", ".env");
+ mkdirSync(join(root, "home"), { recursive: true });
+ writeFileSync(envPath, "ANTHROPIC_API_KEY=fixture-secret\nIII_URL=ws://wrong\nIII_NAMESPACE=wrong\n");
+ const written = writeWorkerCompose(options({ envFile: envPath }));
+ expect(written.text).toContain(`env_file: ['${join(root, "data", "compose", ".agentmemory-filtered.env")}']`);
+ expect(written.text).toContain(".agentmemory-filtered.env");
+ expect(written.text).toContain(`AGENTMEMORY_ENV_FILE: '${join(root, "data", "compose", ".agentmemory-filtered.env")}'`);
+ expect(written.text).not.toContain("III_URL:");
+ expect(readFileSync(join(root, "data", "compose", ".agentmemory-filtered.env"), "utf8")).toContain("ANTHROPIC_API_KEY=fixture-secret");
+ expect(readFileSync(join(root, "data", "compose", ".agentmemory-filtered.env"), "utf8")).not.toContain("III_URL");
+ expect(readFileSync(join(root, "data", "compose", ".agentmemory-filtered.env"), "utf8")).not.toContain("III_ENGINE_URL");
+ expect(written.text).toContain("HOME: '");
+ });
+
+ it("writes generated local worker manifests with the pinned worker commands", () => {
+ const binDir = join(root, "workers-local");
+ const { mkdirSync } = require("node:fs") as typeof import("node:fs");
+ mkdirSync(binDir, { recursive: true });
+ for (const name of ["state", "http"]) {
+ writeFileSync(join(binDir, name), "#!/bin/sh\nexit 0\n");
+ chmodSync(join(binDir, name), 0o755);
+ }
+ const written = writeWorkerCompose(options({ workerBinDir: binDir, workerBinDirIsAbsolute: true }));
+ for (const name of ["state", "http"]) {
+ const manifestPath = join(root, "data", "compose", "local-workers", name, "iii.worker.yaml");
+ const manifest = readFileSync(manifestPath, "utf8");
+ expect(manifest).toContain(`name: ${name}`);
+ expect(manifest).toContain("start: '");
+ expect(manifest).toContain(`/workers-local/${name}'`);
+ }
+ expect(written.text).toContain(`worker: '${rootUrl}/data/compose/local-workers/state'`);
+ });
+
+ it("seeds persistent engine trace storage in the data directory", () => {
+ writeWorkerCompose(options());
+ const configFile = join(root, "data", "compose", "config", "iii-observability.yaml");
+ const entry = parse(readFileSync(configFile, "utf8")) as {
+ id: string;
+ value: { trace_storage: { directory: string }; sampling_ratio: number; logs_console_output: boolean };
+ };
+ expect(entry.id).toBe("iii-observability");
+ expect(entry.value.trace_storage.directory).toBe(join(root, "data", "observability", "traces"));
+ expect(entry.value.sampling_ratio).toBe(0.1);
+ expect(entry.value.logs_console_output).toBe(false);
+ expect(statSync(configFile).mode & 0o777).toBe(0o600);
+ });
+
+ it("stores engine traces under the instance data dir and preserves user observability settings", () => {
+ const configDir = join(root, "data", "compose", "config");
+ mkdirSync(configDir, { recursive: true });
+ writeFileSync(join(configDir, "iii-observability.yaml"), [
+ "id: iii-observability",
+ "name: Observability",
+ "description: custom settings",
+ "schema: {}",
+ "value:",
+ " service_name: agentmemory-test",
+ " sampling_ratio: 0.75",
+ " logs_console_output: true",
+ " trace_storage:",
+ " directory: ./data/observability/traces",
+ " max_disk_bytes: 67108864",
+ "",
+ ].join("\n"));
+
+ writeWorkerCompose(options());
+ const entry = parse(readFileSync(join(configDir, "iii-observability.yaml"), "utf8")) as {
+ value: { service_name: string; sampling_ratio: number; logs_console_output: boolean; trace_storage: { directory: string; max_disk_bytes: number } };
+ };
+ expect(entry.value.service_name).toBe("agentmemory-test");
+ expect(entry.value.sampling_ratio).toBe(0.75);
+ expect(entry.value.logs_console_output).toBe(true);
+ expect(entry.value.trace_storage).toEqual({
+ directory: join(root, "data", "observability", "traces"),
+ max_disk_bytes: 67108864,
+ });
+ });
+
+ it("leaves a deliberately customized engine trace directory alone", () => {
+ const configDir = join(root, "data", "compose", "config");
+ mkdirSync(configDir, { recursive: true });
+ writeFileSync(join(configDir, "iii-observability.yaml"), [
+ "id: iii-observability",
+ "value:",
+ " trace_storage:",
+ " directory: /mnt/traces",
+ "",
+ ].join("\n"));
+
+ writeWorkerCompose(options());
+ const entry = parse(readFileSync(join(configDir, "iii-observability.yaml"), "utf8")) as {
+ value: { trace_storage: { directory: string }; sampling_ratio: number; logs_console_output: boolean };
+ };
+ expect(entry.value.trace_storage.directory).toBe("/mnt/traces");
+ });
+
+ it("writes the project and runtime state only inside the data dir with owner-only file permissions", () => {
+ const written = writeWorkerCompose(options());
+ expect(written.file).toBe(join(root, "data", "compose", "worker-compose.yaml"));
+ expect(written.stateDir).toBe(join(root, "data", "compose-state"));
+ expect(readFileSync(written.file, "utf8")).toBe(written.text);
+ expect(statSync(written.file).mode & 0o777).toBe(0o600);
+ });
+});
diff --git a/test/compose-supervision-integration.test.ts b/test/compose-supervision-integration.test.ts
new file mode 100644
index 00000000..0ae71411
--- /dev/null
+++ b/test/compose-supervision-integration.test.ts
@@ -0,0 +1,151 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { III_PINNED_VERSION } from "../src/version.js";
+import { COMPOSE_WORKER_VERSIONS } from "../src/cli/compose-project.js";
+import { afterAll, describe, expect, it } from "vitest";
+
+const engine = [
+ process.env.AGENTMEMORY_TEST_III,
+ ...(process.env.PATH ?? "").split(delimiter).filter(Boolean).map((directory) => join(directory, process.platform === "win32" ? "iii.exe" : "iii")),
+ join(homedir(), ".agentmemory", "bin", process.platform === "win32" ? "iii.exe" : "iii"),
+].filter((candidate): candidate is string => Boolean(candidate)).map((candidate) => resolve(candidate)).find((candidate) => {
+ try {
+ const result = spawnSync(candidate, ["--version"], { encoding: "utf8", timeout: 3000 });
+ return result.status === 0 && result.stdout.trim() === III_PINNED_VERSION;
+ } catch { return false; }
+});
+if (process.env.AGENTMEMORY_REQUIRE_LIVE_TESTS === "1" && (!engine || process.platform !== "linux" || process.env.AGENTMEMORY_SKIP_LIVE_TESTS === "1")) {
+ throw new Error("Live supervision tests require Linux, the pinned engine, and live tests enabled");
+}
+const workerBinDir = process.env.AGENTMEMORY_TEST_LOCAL_WORKER_DIR;
+const roots: string[] = [];
+const children: ChildProcess[] = [];
+const childLogs = new WeakMap<ChildProcess, string>();
+const cleanEnv = () => {
+ const env = { ...process.env, RUST_LOG: "error" };
+ for (const key of ["III_URL", "III_ENGINE_URL", "III_NAMESPACE", "III_COMPOSE_STATE_DIR", "AGENTMEMORY_DATA_DIR", "AGENTMEMORY_RUNTIME_DIR", "AGENTMEMORY_DISABLE_COMPOSE_RESTART"]) delete env[key];
+ return env;
+};
+function freePort(): number {
+ const result = spawnSync("node", ["-e", 'const n=require("node:net").createServer();n.listen(0,"127.0.0.1",()=>{console.log(n.address().port);n.close()})'], { encoding: "utf8" });
+ if (result.status !== 0) throw new Error(result.stderr);
+ return Number(result.stdout.trim());
+}
+const quote = (value: string) => `'${value.replaceAll("'", "''")}'`;
+function prepare(stateRestart: string, appRestart = "{ condition: on-failure, delay: 500ms, max_delay: 1s, max_attempts: 5, window: 60s }") {
+ const rest = freePort(); const http = rest; const enginePort = freePort();
+ const root = mkdtempSync(join(tmpdir(), "agentmemory-supervision-")); roots.push(root);
+ const data = join(root, "data"); mkdirSync(join(data, "config"), { recursive: true });
+ const namespace = `amsupervision${rest}`; const compose = join(root, "worker-compose.yaml");
+ const workerSource = (name: keyof typeof COMPOSE_WORKER_VERSIONS) => workerBinDir
+ ? `path://${join(data, "local-workers", name)}`
+ : `package://api.workers.iii.dev/${name}`;
+ for (const name of ["state", "http"] as const) {
+ const workerDir = join(data, "local-workers", name); mkdirSync(workerDir, { recursive: true });
+ if (workerBinDir) {
+ const bin = join(workerBinDir, name);
+ writeFileSync(join(workerDir, "iii.worker.yaml"), `iii: v1\nname: ${name}\nlanguage: rust\nscripts:\n start: ${quote(bin)}\n`);
+ }
+ }
+ writeFileSync(compose, `namespace: ${namespace}\nstartup_timeout: 60s\nrequired_default: true\nengine:\n url: ws://127.0.0.1:${enginePort}\n workers:\n configuration:\n adapter:\n name: fs\n config:\n directory: ${quote(join(data, "config"))}\n iii-worker-manager:\n host: 127.0.0.1\n port: ${enginePort}\ncontainers:\n state:\n worker: ${quote(workerSource("state"))}\n${workerBinDir ? "" : ` version: ${COMPOSE_WORKER_VERSIONS.state}\n`} config_name: state\n restart: ${stateRestart}\n config_override:\n adapter:\n name: kv\n config: { store_method: file_based, file_path: ${quote(join(data, "state_store.db"))}, save_interval_ms: 100 }\n http:\n worker: ${quote(workerSource("http"))}\n${workerBinDir ? "" : ` version: ${COMPOSE_WORKER_VERSIONS.http}\n`} config_name: http\n restart: { condition: on-failure, delay: 500ms, max_delay: 1s, max_attempts: 5, window: 60s }\n config_override: { host: 127.0.0.1, port: ${http} }\n agentmemory:\n worker: ${quote("path://.")}\n working_dir: ${quote(process.cwd())}\n start_after: [state, http]\n startup_timeout: 90s\n config_name: agentmemory\n restart: ${appRestart}\n scripts:\n run: ${quote(`${process.execPath} ${join(process.cwd(), "dist/index.mjs")}`)}\n environment:\n HOME: ${quote(join(root, "home"))}\n AGENTMEMORY_RUNTIME_DIR: ${quote(join(root, "home", ".agentmemory"))}\n AGENTMEMORY_DATA_DIR: ${quote(data)}\n III_ENGINE_PORT: ${quote(String(enginePort))}\n III_REST_PORT: ${quote(String(rest))}\n III_VIEWER_PORT: ${quote(String(freePort()))}\n EMBEDDING_PROVIDER: 'none'\n LLM_PROVIDER: 'none'\n III_TELEMETRY_ENABLED: 'false'\n RUST_LOG: 'error'\n`);
+ const result = { root, data, compose, namespace }; return { ...result, rest, http, enginePort };
+}
+function stateFile(project: { data: string; namespace: string }): string | null {
+ const root = join(project.data, "compose-state");
+ const queue = [root];
+ while (queue.length) {
+ const dir = queue.pop()!; let entries;
+ try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+ for (const entry of entries) {
+ const path = join(dir, entry.name);
+ if (entry.isDirectory()) queue.push(path);
+ else if (entry.name === "state.json") {
+ try { if (JSON.parse(readFileSync(path, "utf8")).namespace === project.namespace) return path; } catch {}
+ }
+ }
+ }
+ return null;
+}
+async function waitFor(project: { data: string; namespace: string }, predicate: (state: any) => boolean, timeout = 90_000): Promise<any> {
+ const deadline = Date.now() + timeout;
+ while (Date.now() < deadline) {
+ const child = children.at(-1);
+ if (child?.exitCode !== null && child?.exitCode !== undefined) throw new Error(`compose exited ${child.exitCode}: ${childLogs.get(child) ?? ""}`);
+ const path = stateFile(project);
+ if (path) { const state = JSON.parse(readFileSync(path, "utf8")); if (predicate(state)) return state; }
+ await sleep(100);
+ }
+ throw new Error(`timed out waiting for compose state for ${project.namespace}: ${childLogs.get(children.at(-1)!) ?? ""}`);
+}
+function start(project: { compose: string; namespace: string; data: string }): ChildProcess {
+ if (!engine) throw new Error(`iii ${III_PINNED_VERSION} is not available`);
+ const child = spawn(engine, ["compose", "--namespace", project.namespace, "--up", "--file", project.compose], { env: { ...cleanEnv(), III_COMPOSE_STATE_DIR: join(project.data, "compose-state"), III_BUNDLE_WORKERS_DISABLED: "1", HOME: join(project.root, "home") }, stdio: ["ignore", "ignore", "pipe"], detached: true });
+ children.push(child); childLogs.set(child, ""); child.stderr?.on("data", (chunk) => childLogs.set(child, `${childLogs.get(child) ?? ""}${chunk}`)); return child;
+}
+function killTree(pid: number): void {
+ try { process.kill(-pid, "SIGKILL"); } catch {}
+ try { process.kill(pid, "SIGKILL"); } catch {}
+}
+afterAll(() => { for (const child of children) if (child.pid) killTree(child.pid); for (const root of roots) rmSync(root, { recursive: true, force: true }); });
+
+describe.skipIf(!engine || process.platform !== "linux" || process.env.AGENTMEMORY_SKIP_LIVE_TESTS === "1")(`iii-compose v${III_PINNED_VERSION} worker supervision`, () => {
+ it("marks a worker failed after bounded restarts and reports the exhausted budget", async () => {
+ const project = prepare("{ condition: on-failure, delay: 500ms, max_delay: 500ms, max_attempts: 1, window: 60s }");
+ const child = start(project);
+ try {
+ const ready = await waitFor(project, (s) => s.containers?.agentmemory?.status === "ready" && s.containers?.state?.status === "ready");
+ const pid = ready.containers.state.pid;
+ process.kill(pid, "SIGKILL");
+ const firstRecovery = await waitFor(project, (s) => s.containers?.state?.status === "ready" && s.containers.state.pid !== pid, 15_000);
+ process.kill(firstRecovery.containers.state.pid, "SIGKILL");
+ const exhausted = await waitFor(project, (s) => s.containers?.state?.status === "failed", 30_000);
+ expect(exhausted.containers.state.last_error).toMatch(/did not stay up after 1 restart attempts/);
+ const supervisorLog = childLogs.get(child) ?? "";
+ expect(supervisorLog).toMatch(/state did not stay up after 1 restart attempts: giving up/);
+ const runtime = join(project.root, "home", ".agentmemory"); mkdirSync(runtime, { recursive: true });
+ const projectState = JSON.parse(readFileSync(stateFile(project)!, "utf8"));
+ writeFileSync(join(runtime, "engine-state.json"), JSON.stringify({
+ kind: "compose", restPort: project.rest, viewerPort: project.rest + 2, enginePort: project.enginePort,
+ engineUrl: `ws://127.0.0.1:${project.enginePort}`, namespace: project.namespace, file: project.compose,
+ stateDir: join(project.data, "compose-state"), logFile: join(project.data, "compose-daemon.log"), binPath: engine,
+ composePid: child.pid, enginePid: projectState.owner?.pid, workerVersions: { local: true },
+ }));
+ const status = spawnSync(process.execPath, [join(process.cwd(), "dist/cli.mjs"), "status", "--port", String(project.rest)], { env: { ...cleanEnv(), HOME: join(project.root, "home"), AGENTMEMORY_DATA_DIR: project.data, III_REST_PORT: String(project.rest), III_ENGINE_PORT: String(project.enginePort), III_VIEWER_PORT: String(project.rest + 2) }, encoding: "utf8", timeout: 20_000 });
+ expect(status.status).toBe(0);
+ expect(status.stdout + status.stderr).toMatch(/state did not stay up after 1 restart attempts|restart attempts exhausted|Worker Compose failure/i);
+ } finally { if (child.pid) killTree(child.pid); }
+ }, 120_000);
+
+ it("retains and recalls a saved memory after a real state worker SIGKILL and restart", async () => {
+ const project = prepare("{ condition: on-failure, delay: 500ms, max_delay: 1s, max_attempts: 5, window: 60s }");
+ const child = start(project);
+ let app;
+ try {
+ await waitFor(project, (s) => s.containers?.agentmemory?.status === "ready" && s.containers?.state?.status === "ready");
+ const secret = readFileSync(join(project.data, "secret"), "utf8").trim();
+ const base = `http://127.0.0.1:${project.rest}`;
+ const marker = `supervision-state-memory-${Date.now()}`;
+ const saved = await fetch(`${base}/agentmemory/remember`, { method: "POST", headers: { authorization: `Bearer ${secret}`, "content-type": "application/json" }, body: JSON.stringify({ content: `${marker}: keep this after the state worker restarts`, type: "fact", project: "compose-supervision-test" }) });
+ expect(saved.status).toBe(201);
+ // Let the file-backed state adapter flush the acknowledged write before
+ // simulating abrupt loss of the state process.
+ await sleep(500);
+ const initial = JSON.parse(readFileSync(stateFile(project)!, "utf8")); const oldPid = initial.containers.state.pid;
+ process.kill(oldPid, "SIGKILL");
+ const recovered = await waitFor(project, (s) => s.containers?.state?.status === "ready" && s.containers.state.pid !== oldPid, 30_000);
+ expect(recovered.containers.state.pid).not.toBe(oldPid);
+ for (let i = 0; i < 20; i++) {
+ const response = await fetch(`${base}/agentmemory/memories?latest=true&project=compose-supervision-test`, { headers: { authorization: `Bearer ${secret}` } });
+ const body = await response.json();
+ if (response.ok && JSON.stringify(body).includes(marker)) { expect(body.memories?.some((memory: { content?: string }) => memory.content?.includes(marker))).toBe(true); return; }
+ if (!response.ok) throw new Error(`memory list failed ${response.status}: ${JSON.stringify(body)}`);
+ await sleep(250);
+ }
+ const response = await fetch(`${base}/agentmemory/memories?project=compose-supervision-test`, { headers: { authorization: `Bearer ${secret}` } });
+ throw new Error(`saved memory was not recallable after state worker recovery (HTTP ${response.status}): ${JSON.stringify(await response.json())}`);
+ } finally { if (child.pid) killTree(child.pid); }
+ }, 120_000);
+});
diff --git a/test/compress-viewer-stream.test.ts b/test/compress-viewer-stream.test.ts
index 5c0660e7..e8e4d707 100644
--- a/test/compress-viewer-stream.test.ts
+++ b/test/compress-viewer-stream.test.ts
@@ -11,7 +11,8 @@ vi.mock("../src/functions/search.js", () => ({
}));
import { registerCompressFunction } from "../src/functions/compress.js";
-import { KV, STREAM } from "../src/state/schema.js";
+import { KV } from "../src/state/schema.js";
+import { onLiveEvent } from "../src/viewer/live-events.js";
import type { MemoryProvider, RawObservation } from "../src/types.js";
const VALID_COMPRESS_XML = `<observation><type>command_run</type>
@@ -36,8 +37,8 @@ function mockKV() {
};
}
-describe("compress no longer writes a per-session mem-live group", () => {
- it("only targets the viewer group on stream:: calls", async () => {
+describe("compress emits updates over the worker-owned SSE hub", () => {
+ it("broadcasts the compressed observation without a legacy stream worker", async () => {
const trigger = vi.fn(async () => undefined);
const kv = mockKV();
@@ -79,6 +80,8 @@ describe("compress no longer writes a per-session mem-live group", () => {
raw: {},
};
+ const events: unknown[] = [];
+ const unsubscribe = onLiveEvent((event) => events.push(event));
await kv.set(KV.observations(sessionId), raw.id, raw);
await compressCallback!({
observationId: "obs_1",
@@ -86,14 +89,12 @@ describe("compress no longer writes a per-session mem-live group", () => {
raw,
});
- const streamCalls = trigger.mock.calls
- .map((c) => c[0] as { function_id: string; payload: { group_id?: string } })
- .filter((c) => c.function_id.startsWith("stream::"));
-
- expect(streamCalls.length).toBeGreaterThan(0);
- for (const call of streamCalls) {
- expect(call.payload.group_id).not.toBe(sessionId);
- expect(call.payload.group_id).toBe(STREAM.viewerGroup);
- }
+ unsubscribe();
+ expect(events).toContainEqual(expect.objectContaining({
+ id: "compressed-obs_1",
+ type: "compressed_observation",
+ data: expect.objectContaining({ type: "compressed", sessionId }),
+ }));
+ expect(trigger.mock.calls.some(([call]) => (call as { function_id: string }).function_id.startsWith("stream::"))).toBe(false);
});
});
diff --git a/test/compression-validation.test.ts b/test/compression-validation.test.ts
index 0a17d898..f9e11b61 100644
--- a/test/compression-validation.test.ts
+++ b/test/compression-validation.test.ts
@@ -3,6 +3,7 @@ import { parseCompressionXml } from "../src/prompts/compression-output.js";
import { compressWithRetry } from "../src/eval/self-correct.js";
import { CompressOutputSchema } from "../src/eval/schemas.js";
import { registerCompressFunction } from "../src/functions/compress.js";
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { buildSyntheticCompression } from "../src/functions/compress-synthetic.js";
import { NoopProvider } from "../src/providers/noop.js";
import type { CompressedObservation, MemoryProvider, RawObservation } from "../src/types.js";
@@ -135,7 +136,9 @@ describe("compression validation and retry", () => {
it("persists only a successful retry and preserves the original evidence", async () => {
const provider = providerReturning(xml.replace("Updated configuration", "x".repeat(900)), xml);
const r = rig(provider, buildSyntheticCompression(raw));
+ const unsubscribe = onLiveEvent((event) => { if (event.type === "compressed_observation") r.trigger(event); });
expect(await r.call()).toMatchObject({ success: true, compressed: { title: "Updated configuration" } });
+ unsubscribe();
expect(provider.compress).toHaveBeenCalledTimes(2);
expect((r.stored() as CompressedObservation).compression?.status).toBe("complete");
expect((r.stored() as CompressedObservation).source?.toolOutput).toBe(raw.toolOutput);
diff --git a/test/consistency.test.ts b/test/consistency.test.ts
index a8a6b119..77802ea1 100644
--- a/test/consistency.test.ts
+++ b/test/consistency.test.ts
@@ -8,6 +8,7 @@ vi.mock("../src/logger.js", () => ({
import { getAllTools } from "../src/mcp/tools-registry.js";
import { VERSION } from "../src/version.js";
+import { collectRestEndpointsInDirectory } from "../scripts/skills/rest-endpoints.js";
const ROOT = join(import.meta.dirname, "..");
@@ -16,8 +17,7 @@ function readText(relativePath: string): string {
}
function countRestApiEndpoints(): number {
- const src = readText("src/triggers/api.ts");
- return Array.from(src.matchAll(/api_path:\s*["`]/g)).length;
+ return collectRestEndpointsInDirectory(join(ROOT, "src/triggers")).length;
}
describe("Consistency checks", () => {
@@ -63,7 +63,7 @@ describe("Consistency checks", () => {
const index = readText("src/index.ts");
expect(restEndpointCount).toBeGreaterThan(0);
- expect(readme).toContain(`${restEndpointCount} endpoints on port`);
+ if (readme.includes("endpoints on port")) expect(readme).toContain(`${restEndpointCount} endpoints on port`);
expect(agents).toContain(`${restEndpointCount} REST endpoints`);
expect(index).toContain(`REST API: ${restEndpointCount} endpoints`);
});
@@ -83,32 +83,14 @@ describe("Consistency checks", () => {
}
});
- it("every host-path bind mount in docker-compose.yml is in the published files list", () => {
+ it("keeps the repository self-host Docker Compose file out of the npm package", () => {
const compose = readText("docker-compose.yml");
const pkg = JSON.parse(readText("package.json"));
const files: string[] = pkg.files ?? [];
-
- // Match `./<path>:<container-path>` style bind mounts. We only care
- // about files that live in the repo root (so they'd be shipped via
- // the `files` field). `iii-data:/data` (a named volume) has no `./`
- // prefix and is correctly skipped.
- const bindRe = /^\s*-\s+\.\/([^\s:]+):[^\s]+/gm;
- const sources: string[] = [];
- for (const m of compose.matchAll(bindRe)) sources.push(m[1]!);
-
- expect(sources.length).toBeGreaterThan(0);
- for (const src of sources) {
- // Any nested path would need a directory entry in `files` (e.g.
- // `dist/`); for top-level files, the exact name must be listed.
- const topLevel = src.split("/")[0]!;
- const covered =
- files.includes(src) ||
- files.includes(topLevel) ||
- files.includes(`${topLevel}/`);
- expect(
- covered,
- `docker-compose.yml mounts ./${src} but package.json "files" does not ship it — ${topLevel} would be auto-created as an empty dir on install, breaking \`npx @agentmemory/agentmemory\``,
- ).toBe(true);
- }
+ expect(compose).toContain("- ${AGENTMEMORY_DATA_DIR:-iii-data}:/data");
+ expect(files).not.toContain("docker-compose.yml");
+ // Neither removed legacy config template is part of the published package.
+ expect(files).not.toContain("iii-config.yaml");
+ expect(files).not.toContain("iii-config.docker.yaml");
});
});
diff --git a/test/deploy-runtime.test.ts b/test/deploy-runtime.test.ts
new file mode 100644
index 00000000..d3468a45
--- /dev/null
+++ b/test/deploy-runtime.test.ts
@@ -0,0 +1,61 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { afterEach, describe, expect, it } from "vitest";
+import { parse } from "yaml";
+
+const require = createRequire(import.meta.url);
+const entrypoint = readFileSync("deploy/runtime/entrypoint.sh", "utf8");
+const roots: string[] = [];
+function fixture() {
+ const root = mkdtempSync(join(tmpdir(), "deploy-runtime-"));
+ roots.push(root);
+ mkdirSync(join(root, "config"));
+ return root;
+}
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+describe("deployment entrypoint", () => {
+ it.each(["2000", "500"])("generates file and Redis configurations with save interval %s", (interval) => {
+ const root = fixture();
+ const program = entrypoint.split("node <<'NODE'\n")[1].split("\nNODE")[0]
+ .replace('"/opt/agentmemory/worker-compose.yaml"', JSON.stringify(resolve("deploy/runtime/worker-compose.yaml")))
+ .replace('"/opt/agentmemory/node_modules/yaml"', JSON.stringify(require.resolve("yaml")))
+ .replaceAll(/fs\.chownSync\([^;]+\);/g, "");
+ for (const backend of ["", "redis"]) {
+ execFileSync(process.execPath, ["-e", program], { env: {
+ PATH: process.env.PATH, AGENTMEMORY_DATA_DIR: root,
+ AGENTMEMORY_STATE_SAVE_INTERVAL_MS: interval,
+ REST_ALLOWED_ORIGINS: "https://viewer.example,https://other.example",
+ AGENTMEMORY_STATE_BACKEND: backend, AGENTMEMORY_REDIS_URL: "redis://127.0.0.1:6379/2",
+ } });
+ const text = readFileSync(join(root, "worker-compose.runtime.yaml"), "utf8")
+ .replaceAll("${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}", interval);
+ const compose = parse(text);
+ expect(compose.containers.state.config_override.adapter).toEqual(backend === "redis"
+ ? { name: "redis", config: { redis_url: "redis://127.0.0.1:6379/2" } }
+ : { name: "kv", config: { store_method: "file_based", file_path: "/data/state_store.db", save_interval_ms: interval } });
+ expect(compose.containers.http.config_override.cors.allowed_origins).toEqual(["https://viewer.example", "https://other.example"]);
+ expect(compose.containers.state.version).toBe("${STATE_VERSION}");
+ }
+ });
+
+ it.each([false, true])("migrates the legacy file without overriding an explicit secret (%s)", (explicit) => {
+ const root = fixture();
+ writeFileSync(join(root, ".hmac"), "legacy-fixture\n");
+ const prefix = entrypoint.split("# The former Docker runtime")[0];
+ const script = `chown() { :; }\n${prefix}\nexec node --import tsx --input-type=module -e 'import { ensureServerSecret } from "./src/secret-store.ts"; const result = ensureServerSecret(); if(result.secret !== process.env.EXPECTED_SECRET) process.exit(1);'`;
+ execFileSync("sh", ["-c", script], { env: {
+ PATH: process.env.PATH, HOME: join(root, "home"), USERPROFILE: join(root, "home"),
+ AGENTMEMORY_DATA_DIR: root, AGENTMEMORY_SECRET: explicit ? "operator-fixture" : "",
+ EXPECTED_SECRET: explicit ? "operator-fixture" : "legacy-fixture",
+ } });
+ if (!explicit) {
+ expect(readFileSync(join(root, "secret"), "utf8").trim()).toBe("legacy-fixture");
+ expect(readFileSync(join(root, "home/.agentmemory/secret"), "utf8").trim()).toBe("legacy-fixture");
+ expect(statSync(join(root, "secret")).mode & 0o777).toBe(0o600);
+ }
+ });
+});
diff --git a/test/docker-port-config.test.ts b/test/docker-port-config.test.ts
index f5e87b81..7c69e962 100644
--- a/test/docker-port-config.test.ts
+++ b/test/docker-port-config.test.ts
@@ -4,71 +4,79 @@ import { describe, expect, it } from "vitest";
const root = join(import.meta.dirname, "..");
const compose = readFileSync(join(root, "docker-compose.yml"), "utf8");
-const engineConfig = readFileSync(join(root, "iii-config.docker.yaml"), "utf8");
+const workerCompose = readFileSync(
+ join(root, "deploy/runtime/worker-compose.yaml"),
+ "utf8",
+);
+const entrypoint = readFileSync(
+ join(root, "deploy/runtime/entrypoint.sh"),
+ "utf8",
+);
-function workerBlock(name: string): string {
- const start = engineConfig.indexOf(` - name: ${name}`);
- if (start === -1) return "";
- const next = engineConfig.indexOf("\n - name:", start + 1);
- return engineConfig.slice(start, next === -1 ? undefined : next);
-}
-
-describe("Docker engine port configuration", () => {
- it("passes the resolved port quartet into the engine container", () => {
- expect(compose).toContain('III_REST_PORT: "${III_REST_PORT:-3111}"');
- expect(compose).toContain('III_STREAM_PORT: "${III_STREAM_PORT:-3112}"');
- expect(compose).toContain('III_VIEWER_PORT: "${III_VIEWER_PORT:-3113}"');
- expect(compose).toContain('III_ENGINE_PORT: "${III_ENGINE_PORT:-49134}"');
- });
-
- it("publishes the configured host and container ports", () => {
- expect(compose).toContain(
- '"127.0.0.1:${III_REST_PORT:-3111}:${III_REST_PORT:-3111}"',
- );
- expect(compose).toContain(
- '"127.0.0.1:${III_STREAM_PORT:-3112}:${III_STREAM_PORT:-3112}"',
- );
- expect(compose).toContain(
- '"127.0.0.1:${III_ENGINE_PORT:-49134}:${III_ENGINE_PORT:-49134}"',
- );
- expect(compose).toContain(
- '"127.0.0.1:${AGENTMEMORY_METRICS_PORT:-9464}:9464"',
- );
+describe("Docker Worker Compose runtime", () => {
+ it("publishes REST and viewer ports but not the retired stream port 3112", () => {
+ expect(compose).toContain('"127.0.0.1:${AGENTMEMORY_REST_PORT:-3111}:3111"');
+ expect(compose).toContain('"127.0.0.1:${AGENTMEMORY_VIEWER_PORT:-3113}:3113"');
+ expect(compose).not.toContain("49134:");
+ expect(compose).not.toContain("3112:");
});
- it("runs CLI-managed bind mounts as the host user without recursive chown", () => {
- expect(compose).toContain(
- 'user: "${AGENTMEMORY_DOCKER_UID:-65532}:${AGENTMEMORY_DOCKER_GID:-65532}"',
- );
- expect(compose).toContain("AGENTMEMORY_DOCKER_SKIP_CHOWN");
- expect(compose).toContain("target: /app/config");
+ it("keeps engine and service listeners on the private Compose network", () => {
+ expect(workerCompose).toContain("url: ws://127.0.0.1:49134");
+ expect(workerCompose).toContain("port: 49134");
+ expect(workerCompose).toContain(" host: 127.0.0.1\n port: 49134");
+ expect(workerCompose).toContain('III_REST_PORT: "3111"');
+ expect(workerCompose).toContain('III_VIEWER_PORT: "3113"');
+ expect(workerCompose).toContain("port: 3111");
+ expect(workerCompose).toContain('allowed_origins: ["__REST_ALLOWED_ORIGINS__"]');
+ expect(entrypoint).toContain("REST_ALLOWED_ORIGINS must contain comma-separated origins");
+ expect(workerCompose).toContain("state:");
+ expect(workerCompose).toContain("http:");
+ expect(workerCompose).toContain("agentmemory:");
+ expect(workerCompose.match(/condition: on-failure/g)).toHaveLength(3);
+ expect(workerCompose.match(/max_attempts: 5/g)).toHaveLength(3);
+ expect(workerCompose.match(/delay: 500ms/g)).toHaveLength(3);
+ expect(workerCompose.match(/max_delay: 30s/g)).toHaveLength(3);
+ expect(workerCompose.match(/window: 60s/g)).toHaveLength(3);
+ expect(workerCompose).not.toMatch(/^ (?:queue|cron|pubsub|stream):/m);
});
- it("configures every iii listener from the same environment", () => {
- expect(workerBlock("iii-http")).toContain("port: ${III_REST_PORT:3111}");
- expect(workerBlock("iii-stream")).toContain("port: ${III_STREAM_PORT:3112}");
-
- const manager = workerBlock("iii-worker-manager");
- expect(manager).toContain("port: ${III_ENGINE_PORT:49134}");
- expect(manager).toContain("host: 0.0.0.0");
- expect(engineConfig).not.toMatch(/- name: (http|state|pubsub|cron|queue)$/m);
+ it("persists application state in a named volume and uses the shared image build", () => {
+ expect(compose).toContain("dockerfile: deploy/Dockerfile");
+ expect(compose).toContain("- ${AGENTMEMORY_DATA_DIR:-iii-data}:/data");
+ expect(compose).toContain("iii-data:");
+ expect(compose).not.toMatch(/^\s+- \.\//m);
});
- it("starts the pinned engine without update checks and with usage telemetry off by default", () => {
- expect(compose).toContain('command: ["--config", "/app/config.yaml", "--no-update-check"]');
- expect(compose).toContain('III_TELEMETRY_ENABLED: "${III_TELEMETRY_ENABLED:-false}"');
+ it("starts the pinned runtime through the shared entrypoint with telemetry disabled", () => {
+ expect(compose).toContain('III_TELEMETRY_ENABLED: "false"');
+ expect(entrypoint).toContain("/usr/local/bin/iii compose");
+ expect(entrypoint).toContain("--namespace agentmemory --up --file");
+ expect(workerCompose).toContain("configuration:");
+ expect(workerCompose).toContain('save_interval_ms: "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"');
+ expect(entrypoint).toContain('AGENTMEMORY_STATE_SAVE_INTERVAL_MS="${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"');
+ expect(entrypoint).toContain("-lt 100");
+ expect(entrypoint).toContain("-gt 3600000");
+ expect(entrypoint).toContain("*[!0-9]*");
+ expect(workerCompose).toContain("file_path: /data/state_store.db");
+ expect(compose).toContain('AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"');
+ expect(compose).toContain('AGENTMEMORY_STATE_BACKEND: "${AGENTMEMORY_STATE_BACKEND:-}"');
+ expect(compose).toContain('AGENTMEMORY_REDIS_URL: "${AGENTMEMORY_REDIS_URL:-}"');
+ expect(workerCompose).toContain('AGENTMEMORY_SECRET: "${AGENTMEMORY_SECRET:-}"');
+ expect(workerCompose).toContain('OPENAI_API_KEY: "${OPENAI_API_KEY:-}"');
+ expect(entrypoint).toContain("AGENTMEMORY_STATE_BACKEND=redis requires AGENTMEMORY_REDIS_URL");
+ expect(entrypoint).toContain('name: "redis"');
});
- it("leaves worker ownership to the host CLI", () => {
- expect(engineConfig).not.toContain("- name: iii-exec");
- expect(engineConfig).not.toContain("node dist/index.mjs");
+ it("seeds observability defaults while retaining explicit persisted values", () => {
+ expect(entrypoint).toContain("value.sampling_ratio = 0.1");
+ expect(entrypoint).toContain("value.logs_console_output = false");
+ expect(entrypoint).toContain("entry.value = value");
});
- it("keeps REST and viewer CORS aligned with overridden ports", () => {
- const http = workerBlock("iii-http");
- expect(http).toContain("http://localhost:${III_REST_PORT:3111}");
- expect(http).toContain("http://127.0.0.1:${III_REST_PORT:3111}");
- expect(http).toContain("http://localhost:${III_VIEWER_PORT:3113}");
- expect(http).toContain("http://127.0.0.1:${III_VIEWER_PORT:3113}");
+ it("sets host and viewer allowlists from runtime environment", () => {
+ expect(workerCompose).toContain('AGENTMEMORY_VIEWER_HOST: "${AGENTMEMORY_VIEWER_HOST:-0.0.0.0}"');
+ expect(workerCompose).toContain("VIEWER_ALLOWED_HOSTS:");
+ expect(workerCompose).toContain("VIEWER_ALLOWED_ORIGINS:");
});
});
diff --git a/test/engine-child-env.test.ts b/test/engine-child-env.test.ts
deleted file mode 100644
index 11088389..00000000
--- a/test/engine-child-env.test.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { engineChildEnv } from "../src/cli/engine-launch.js";
-
-describe("engineChildEnv", () => {
- it("turns the engine's anonymous usage telemetry off when the user has not chosen", () => {
- const env = engineChildEnv({ PATH: "/usr/bin" });
-
- expect(env["III_TELEMETRY_ENABLED"]).toBe("false");
- expect(env["PATH"]).toBe("/usr/bin");
- });
-
- it("keeps an explicit opt-in or opt-out", () => {
- expect(engineChildEnv({ III_TELEMETRY_ENABLED: "true" })["III_TELEMETRY_ENABLED"]).toBe("true");
- expect(engineChildEnv({ III_TELEMETRY_ENABLED: "false" })["III_TELEMETRY_ENABLED"]).toBe("false");
- });
-
- it("passes AGENTMEMORY_REDIS_URL through so the engine can expand ${AGENTMEMORY_REDIS_URL} itself", () => {
- const env = engineChildEnv({ AGENTMEMORY_REDIS_URL: "redis://user:pass@localhost:6379" });
- expect(env["AGENTMEMORY_REDIS_URL"]).toBe("redis://user:pass@localhost:6379");
- });
-});
diff --git a/test/engine-config.test.ts b/test/engine-config.test.ts
index c8cf20a0..c1dd680b 100644
--- a/test/engine-config.test.ts
+++ b/test/engine-config.test.ts
@@ -1,443 +1,45 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
import { describe, expect, it } from "vitest";
-import {
- clearPersistedBuiltinConfig,
- persistedBuiltinConfigDirs,
- persistedBuiltinConfigPaths,
- renderEngineConfig,
-} from "../src/cli/engine-config.js";
+import { COMPOSE_WORKER_VERSIONS, renderWorkerCompose } from "../src/cli/compose-project.js";
-const customDirConfig = [
- "workers:",
- " - name: iii-http",
- " config:",
- " port: 3111",
- " - name: configuration",
- " config:",
- " adapter:",
- " name: fs",
- " config:",
- " directory: ./custom-cfg",
- " - name: iii-state",
- " config: {}",
-].join("\n");
-
-describe("renderEngineConfig", () => {
- it("stores engine state in the resolved data directory", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
- const dataDir = join("/var", "lib", "agentmemory");
-
- const rendered = renderEngineConfig(source, { dataDir });
-
- expect(rendered).toContain(
- `file_path: '${join(dataDir, "state_store.db")}'`,
- );
- expect(rendered).toContain(
- `file_path: '${join(dataDir, "stream_store")}'`,
- );
- expect(rendered).not.toContain("./data/");
+describe("native Worker Compose runtime configuration", () => {
+ it("pins state/http workers at the reviewed registry versions", () => {
+ expect(COMPOSE_WORKER_VERSIONS).toEqual({ state: "0.22.20", http: "0.22.7" });
});
- it("moves the complete native port quartet from one REST override", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
-
- const rendered = renderEngineConfig(source, {
+ it("renders instance-specific worker ports and persistent state storage", () => {
+ const rendered = renderWorkerCompose({
+ ports: { restPort: 3211, viewerPort: 3213, enginePort: 49234 },
dataDir: "/tmp/agentmemory",
- ports: {
- restPort: 3211,
- streamPort: 3212,
- viewerPort: 3213,
- enginePort: 49234,
- },
+ projectRoot: "/opt/agentmemory",
+ nodeBin: "/usr/bin/node",
+ homeDir: "/home/user",
+ linux: false,
});
-
- expect(rendered).toMatch(
- /- name: iii-http\n\s+config:\n\s+port: 3211/,
- );
- expect(rendered).toMatch(
- /- name: iii-stream\n\s+config:\n\s+port: 3212/,
- );
- expect(rendered).toContain(
- 'allowed_origins: ["http://localhost:3211", "http://localhost:3213", "http://127.0.0.1:3211", "http://127.0.0.1:3213"]',
- );
- expect(rendered).toMatch(
- /- name: iii-worker-manager\n\s+config:\n\s+port: 49234\n\s+host: 127\.0\.0\.1/,
- );
- });
-
- it("is byte-identical to the file-default render when stateBackend is omitted or 'file'", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
- const dataDir = "/tmp/agentmemory-fixture";
-
- const withoutOption = renderEngineConfig(source, { dataDir });
- const withFileKind = renderEngineConfig(source, {
- dataDir,
- stateBackend: { kind: "file" },
+ expect(rendered).toContain("worker: 'package://api.workers.iii.dev/state'");
+ expect(rendered).toContain("version: '0.22.20'");
+ expect(rendered).toContain("worker: 'package://api.workers.iii.dev/http'");
+ expect(rendered).toContain("version: '0.22.7'");
+ expect(rendered).toContain("port: 3211");
+ expect(rendered).toContain("port: 49234");
+ expect(rendered).toContain("file_path: '/tmp/agentmemory/state_store.db'");
+ expect(rendered).toContain("namespace: agentmemory-3211");
+ // The generated Compose project no longer emits the legacy engine config.
+ expect(rendered).not.toContain("iii-config.yaml");
+ });
+
+ it("supports Redis state via Worker Compose", () => {
+ const rendered = renderWorkerCompose({
+ ports: { restPort: 3111, viewerPort: 3113, enginePort: 49134 },
+ dataDir: "/tmp/am",
+ projectRoot: "/opt/am",
+ nodeBin: "node",
+ homeDir: "/home/u",
+ stateBackend: { kind: "redis", redisUrl: "redis://localhost:6379" },
+ redisUrl: "redis://localhost:6379",
+ linux: false,
});
-
- expect(withFileKind).toBe(withoutOption);
- expect(withFileKind).toContain("name: kv");
- expect(withFileKind).not.toContain("name: redis");
- });
-
- it("switches both iii-state and iii-stream to the redis adapter", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
-
- const rendered = renderEngineConfig(source, {
- dataDir: "/tmp/agentmemory-fixture",
- stateBackend: { kind: "redis", redisUrl: "redis://localhost:6390" },
- });
-
- expect(rendered).toMatch(
- /- name: iii-state\n {4}config:\n {6}adapter:\n {8}name: redis\n {8}config:\n {10}redis_url: '\$\{AGENTMEMORY_REDIS_URL\}'/,
- );
- expect(rendered).toMatch(
- /- name: iii-stream\n {4}config:\n {6}port: 3112\n {6}host: 127\.0\.0\.1\n {6}adapter:\n {8}name: redis\n {8}config:\n {10}redis_url: '\$\{AGENTMEMORY_REDIS_URL\}'/,
- );
- expect(rendered).not.toContain("redis://localhost:6390");
+ expect(rendered).toContain("name: redis");
+ expect(rendered).toContain("redis://localhost:6379");
expect(rendered).not.toContain("store_method: file_based");
- expect(rendered).not.toContain("state_store.db");
- expect(rendered).not.toContain("stream_store");
- });
-
- it("throws a clear error when redis is selected without a URL", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
-
- expect(() =>
- renderEngineConfig(source, {
- dataDir: "/tmp/agentmemory-fixture",
- stateBackend: { kind: "redis" },
- }),
- ).toThrow(/AGENTMEMORY_REDIS_URL/);
- });
-
- it.each(["redis://:pa'ss@localhost:6379", "redis://localhost:6379/0\n", "redis://:a\tb@localhost:6379"])(
- "rejects a redis URL the engine could not load after expansion: %j",
- (redisUrl) => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
-
- expect(() =>
- renderEngineConfig(source, {
- dataDir: "/tmp/agentmemory-fixture",
- stateBackend: { kind: "redis", redisUrl },
- }),
- ).toThrow(/percent-encode/i);
- },
- );
-
- it("accepts a percent-encoded single quote in the redis password", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
-
- expect(() =>
- renderEngineConfig(source, {
- dataDir: "/tmp/agentmemory-fixture",
- stateBackend: { kind: "redis", redisUrl: "redis://:pa%27ss@localhost:6379" },
- }),
- ).not.toThrow();
- });
-
- it("throws when redis is selected but the iii-state worker block is missing", () => {
- const source = ["workers:", " - name: iii-http", " config:", " port: 3111"].join(
- "\n",
- );
-
- expect(() =>
- renderEngineConfig(source, {
- dataDir: "/tmp/agentmemory-fixture",
- stateBackend: { kind: "redis", redisUrl: "redis://localhost:6390" },
- }),
- ).toThrow(/iii-state/);
- });
-
- it("throws when redis is selected but iii-state has no adapter block to replace", () => {
- const source = [
- "workers:",
- " - name: iii-state",
- " config: {}",
- " - name: iii-stream",
- " config:",
- " adapter:",
- " name: kv",
- " config: {}",
- ].join("\n");
-
- expect(() =>
- renderEngineConfig(source, {
- dataDir: "/tmp/agentmemory-fixture",
- stateBackend: { kind: "redis", redisUrl: "redis://localhost:6390" },
- }),
- ).toThrow(/adapter/);
- });
-
- it("keeps the iii- prefixed builtin names: on 0.22.1 the unprefixed names resolve to registry workers", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.yaml"),
- "utf8",
- );
- const names = [...source.matchAll(/^\s*- name: (\S+)$/gm)].map((m) => m[1]);
-
- expect(names).toEqual(
- expect.arrayContaining([
- "iii-http",
- "iii-state",
- "iii-pubsub",
- "iii-cron",
- "iii-queue",
- "iii-stream",
- "iii-observability",
- ]),
- );
- for (const bare of ["http", "state", "pubsub", "cron", "queue"]) {
- expect(names).not.toContain(bare);
- }
- });
-});
-
-describe("renderEngineConfig bind hosts", () => {
- const ports = { restPort: 3111, streamPort: 3112, viewerPort: 3113, enginePort: 49134 };
- const hostsOf = (text: string) =>
- [...text.matchAll(/^\s*host:\s*(\S+)\s*$/gm)].map((m) => m[1]);
-
- it("keeps the bundled config on loopback", () => {
- const source = readFileSync(join(import.meta.dirname, "..", "iii-config.yaml"), "utf8");
- const hosts = hostsOf(renderEngineConfig(source, { dataDir: "/tmp/am", ports }));
- expect(hosts.length).toBeGreaterThan(0);
- expect(new Set(hosts)).toEqual(new Set(["127.0.0.1"]));
- });
-
- it("keeps the 0.0.0.0 binds of a config chosen through AGENTMEMORY_III_CONFIG", () => {
- const source = readFileSync(
- join(import.meta.dirname, "..", "iii-config.docker.yaml"),
- "utf8",
- );
- const rendered = renderEngineConfig(source, { dataDir: "/tmp/am", ports });
- expect(hostsOf(rendered)).toEqual(["0.0.0.0", "0.0.0.0", "0.0.0.0"]);
- expect(rendered).toContain("port: 3111");
- expect(rendered).toContain("port: 3112");
- expect(rendered).toContain("port: 49134");
- });
-});
-
-describe("renderEngineConfig CORS origins", () => {
- const ports = { restPort: 3211, streamPort: 3212, viewerPort: 3213, enginePort: 49234 };
- const managedOrigins =
- ' allowed_origins: ["http://localhost:3211", "http://localhost:3213", "http://127.0.0.1:3211", "http://127.0.0.1:3213"]';
- const httpWorker = (corsLines: string[]) =>
- [
- "workers:",
- " - name: iii-worker-manager",
- " config:",
- " port: 49234",
- " host: 127.0.0.1",
- " - name: iii-http",
- " config:",
- " port: 3211",
- " cors:",
- ...corsLines,
- " allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]",
- " - name: iii-state",
- " config: {}",
- ].join("\n");
-
- it.each([
- {
- shape: "an indented block list",
- origins: [
- " allowed_origins:",
- ' - "http://localhost:3111"',
- ' - "http://localhost:3113"',
- ],
- },
- {
- shape: "a compact block list",
- origins: [
- " allowed_origins:",
- ' - "http://localhost:3111"',
- ' - "http://localhost:3113"',
- ],
- },
- {
- shape: "a commented block list",
- origins: [
- " allowed_origins: # local only",
- ' - "http://localhost:3111"',
- "",
- " # viewer",
- ' - "http://localhost:3113"',
- ],
- },
- {
- shape: "a one-line flow list",
- origins: [' allowed_origins: ["http://localhost:3111", "http://localhost:3113"]'],
- },
- {
- shape: "a multi-line flow list",
- origins: [
- " allowed_origins: [",
- ' "http://localhost:3111",',
- ' "http://localhost:3113",',
- " ]",
- ],
- },
- {
- shape: "a scalar",
- origins: [' allowed_origins: "*"'],
- },
- ])("replaces $shape with the managed origins", ({ origins }) => {
- const rendered = renderEngineConfig(httpWorker(origins), { dataDir: "/tmp/am", ports });
-
- expect(rendered).toBe(httpWorker([managedOrigins]));
- });
-
- it("keeps the comment that introduces the next key", () => {
- const source = httpWorker([
- " allowed_origins:",
- ' - "http://localhost:3111"',
- "",
- " # the viewer needs OPTIONS",
- ]);
-
- const rendered = renderEngineConfig(source, { dataDir: "/tmp/am", ports });
-
- expect(rendered).toBe(
- httpWorker([managedOrigins, "", " # the viewer needs OPTIONS"]),
- );
- });
-});
-
-describe("clearPersistedBuiltinConfig", () => {
- const configPath = join("/srv", "state", "iii-config.runtime.yaml");
-
- it("covers the engine cwd, the config file directory and the legacy 0.19 location", () => {
- expect(persistedBuiltinConfigDirs("/srv/engine", configPath)).toEqual([
- join("/srv", "engine", "config"),
- join("/srv", "state", "config"),
- join("/srv", "engine", "data", "configuration"),
- ]);
- });
-
- it("lists both the unprefixed and the legacy entry name for every seeded builtin", () => {
- const paths = persistedBuiltinConfigPaths("/srv/engine", configPath);
-
- expect(paths).toContain(join("/srv", "state", "config", "http.yaml"));
- expect(paths).toContain(join("/srv", "state", "config", "iii-http.yaml"));
- expect(paths).toContain(join("/srv", "state", "config", "iii-worker-manager.yaml"));
- expect(paths).toContain(
- join("/srv", "engine", "data", "configuration", "iii-http.yaml"),
- );
- expect(paths.every((p) => p.endsWith(".yaml"))).toBe(true);
- });
-
- it("adds the directory a configuration worker entry names, resolved against the engine cwd", () => {
- expect(persistedBuiltinConfigDirs("/srv/engine", configPath, customDirConfig)).toEqual([
- join("/srv", "engine", "custom-cfg"),
- join("/srv", "engine", "config"),
- join("/srv", "state", "config"),
- join("/srv", "engine", "data", "configuration"),
- ]);
- expect(
- persistedBuiltinConfigDirs(
- "/srv/engine",
- configPath,
- customDirConfig.replace("./custom-cfg", "'/var/lib/iii-cfg'"),
- )[0],
- ).toBe(join("/var", "lib", "iii-cfg"));
- expect(
- persistedBuiltinConfigDirs("/srv/engine", configPath, "workers:\n - name: iii-http\n"),
- ).toEqual(persistedBuiltinConfigDirs("/srv/engine", configPath));
- });
-
- it("removes persisted builtin entries from both locations and leaves everything else in place", () => {
- const cwd = mkdtempSync(join(tmpdir(), "agentmemory-engine-"));
- const dataDir = mkdtempSync(join(tmpdir(), "agentmemory-data-"));
- const runtimeConfig = join(dataDir, "iii-config.runtime.yaml");
- const current = join(dataDir, "config");
- const legacy = join(cwd, "data", "configuration");
- mkdirSync(current, { recursive: true });
- mkdirSync(legacy, { recursive: true });
- writeFileSync(join(current, "http.yaml"), "id: http\nvalue:\n port: 3111\n");
- writeFileSync(join(current, "iii-state.yaml"), "id: iii-state\nvalue: {}\n");
- writeFileSync(join(current, "agentmemory.yaml"), "id: agentmemory\nvalue: {}\n");
- writeFileSync(join(legacy, "iii-http.yaml"), "id: iii-http\nvalue:\n port: 3111\n");
-
- const cleared = clearPersistedBuiltinConfig(cwd, runtimeConfig);
-
- expect(cleared).toHaveLength(3);
- expect(existsSync(join(current, "http.yaml"))).toBe(false);
- expect(existsSync(join(current, "iii-state.yaml"))).toBe(false);
- expect(existsSync(join(legacy, "iii-http.yaml"))).toBe(false);
- expect(existsSync(join(current, "agentmemory.yaml"))).toBe(true);
- });
-
- it("removes the entries the engine persisted under a custom configuration directory", () => {
- const cwd = mkdtempSync(join(tmpdir(), "agentmemory-engine-"));
- const dir = join(cwd, "custom-cfg");
- mkdirSync(dir, { recursive: true });
- writeFileSync(join(dir, "iii-http.yaml"), "id: iii-http\nvalue:\n port: 3111\n");
- writeFileSync(join(dir, "agentmemory.yaml"), "id: agentmemory\nvalue: {}\n");
-
- const cleared = clearPersistedBuiltinConfig(
- cwd,
- join(cwd, "iii-config.runtime.yaml"),
- customDirConfig,
- );
-
- expect(cleared).toEqual([join(dir, "iii-http.yaml")]);
- expect(existsSync(join(dir, "agentmemory.yaml"))).toBe(true);
- });
-
- it("leaves files that are not engine entries alone, even under a seeded builtin name", () => {
- const cwd = mkdtempSync(join(tmpdir(), "agentmemory-engine-"));
- const dir = join(cwd, "config");
- mkdirSync(dir, { recursive: true });
- writeFileSync(join(dir, "http.yaml"), "host: 0.0.0.0\nport: 8080\n");
- writeFileSync(join(dir, "state.yaml"), "id: something-else\nvalue: {}\n");
- writeFileSync(join(dir, "iii-http.yaml"), "\nid: iii-http\nname: HTTP\nvalue:\n port: 3111\n");
-
- const cleared = clearPersistedBuiltinConfig(cwd, join(cwd, "iii-config.runtime.yaml"));
-
- expect(cleared).toEqual([join(dir, "iii-http.yaml")]);
- expect(existsSync(join(dir, "http.yaml"))).toBe(true);
- expect(existsSync(join(dir, "state.yaml"))).toBe(true);
- });
-
- it("is a no-op when the engine has never persisted anything", () => {
- const cwd = mkdtempSync(join(tmpdir(), "agentmemory-engine-"));
-
- expect(
- clearPersistedBuiltinConfig(cwd, join(cwd, "iii-config.runtime.yaml")),
- ).toEqual([]);
- });
-
- it("fails loudly when a persisted entry exists but cannot be removed", () => {
- const cwd = mkdtempSync(join(tmpdir(), "agentmemory-engine-"));
- mkdirSync(join(cwd, "config", "http.yaml"), { recursive: true });
-
- expect(() =>
- clearPersistedBuiltinConfig(cwd, join(cwd, "iii-config.runtime.yaml")),
- ).toThrow(/http\.yaml/);
});
});
diff --git a/test/engine-flush-wait.test.ts b/test/engine-flush-wait.test.ts
index 23edcf8b..0f1ab9e6 100644
--- a/test/engine-flush-wait.test.ts
+++ b/test/engine-flush-wait.test.ts
@@ -30,15 +30,28 @@ describe("engine flush wait on stop", () => {
expect(engineFlushWaitMs("file", [custom, "save_interval_ms: 9000"])).toBe(10500);
});
+ it.each(["30000", '"30000"', "'30000'"])("reads the numeric interval %s", (value) => {
+ expect(engineSaveIntervalMs([`${persistedState}\n save_interval_ms: ${value}`])).toBe(30000);
+ });
+
+ it.each([
+ ["30000", 30000],
+ [undefined, 2000],
+ ["", 2000],
+ ["invalid", 5000],
+ ["9007199254740992", 5000],
+ ])("resolves a Compose save interval with environment value %s", (value, expected) => {
+ const compose = `${persistedState}\n save_interval_ms: "\${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:-2000}"`;
+ expect(engineSaveIntervalMs([compose], { AGENTMEMORY_STATE_SAVE_INTERVAL_MS: value })).toBe(expected);
+ expect(engineSaveIntervalMs([compose, "save_interval_ms: 90000"], { AGENTMEMORY_STATE_SAVE_INTERVAL_MS: value })).toBe(90000);
+ });
+
it("counts a file store without an explicit interval at the engine default", () => {
- const stateAndStream = [
+ const stateStore = [
" - name: iii-state",
" store_method: file_based",
- " save_interval_ms: 2000",
- " - name: iii-stream",
- " store_method: file_based",
].join("\n");
- expect(engineSaveIntervalMs([stateAndStream])).toBe(5000);
+ expect(engineSaveIntervalMs([stateStore])).toBe(5000);
});
it("does not cut a long configured interval short", () => {
diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts
index c02e4158..0186a288 100644
--- a/test/engine-install.test.ts
+++ b/test/engine-install.test.ts
@@ -1,5 +1,5 @@
import { spawnSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
@@ -72,6 +72,14 @@ function runInstall(dir: string, bin: string, sha256: string | null, asset = ASS
}
describe("iii engine auto-installer", () => {
+ it("keeps the SDK, helper and deployment defaults aligned with the installed engine", () => {
+ const manifest = JSON.parse(readFileSync("package.json", "utf8"));
+ expect(manifest.dependencies["iii-sdk"]).toBe(III_PINNED_VERSION);
+ expect(manifest.dependencies["@iii-dev/helpers"]).toBe(III_PINNED_VERSION);
+ expect(readFileSync("deploy/Dockerfile", "utf8")).toContain(`ARG III_VERSION=${III_PINNED_VERSION}\n`);
+ expect(readFileSync("docker-compose.yml", "utf8")).toContain(`III_VERSION: "\${III_VERSION:-${III_PINNED_VERSION}}"`);
+ });
+
it("passes connect and overall timeouts to curl", () => {
const cmd = iiiDownloadShellCommand();
expect(cmd).toContain(`--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S}`);
diff --git a/test/engine-launch-hardening.test.ts b/test/engine-launch-hardening.test.ts
index ce3c4a75..fd4e56e4 100644
--- a/test/engine-launch-hardening.test.ts
+++ b/test/engine-launch-hardening.test.ts
@@ -1,165 +1,49 @@
-import { spawnSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
import { join } from "node:path";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import {
- AGENTMEMORY_STATE_SAVE_INTERVAL_MS,
- configuredSaveIntervalMs,
- engineFlushWaitMs,
- engineSaveIntervalMs,
- engineStateConfigPaths,
- renderEngineConfig,
-} from "../src/cli/engine-config.js";
-import {
- engineChildEnv,
- rewriteBundledConfig,
-} from "../src/cli/engine-launch.js";
-import { getStateSaveIntervalMs } from "../src/config.js";
+import { engineFlushWaitMs, engineSaveIntervalMs, engineStateConfigPaths } from "../src/cli/engine-config.js";
+import { renderWorkerCompose } from "../src/cli/compose-project.js";
-const root = join(import.meta.dirname, "..");
-const read = (path: string) => readFileSync(join(root, path), "utf-8");
+const read = (path: string) => readFileSync(join(import.meta.dirname, "..", path), "utf-8");
-function intervals(text: string): string[] {
- return [...text.matchAll(/save_interval_ms:\s*(\S+)/g)].map((m) => m[1]!);
-}
-
-const customConfig = [
- "workers:",
- " - name: iii-state",
- " config:",
- " adapter:",
- " name: kv",
- " config:",
- " store_method: file_based",
- " file_path: /srv/state",
- " - name: iii-stream",
- " config:",
- " adapter:",
- " name: kv",
- " config:",
- " store_method: in_memory",
-].join("\n");
-
-describe("engine file-store save interval", () => {
- afterEach(() => {
- vi.unstubAllEnvs();
- });
-
- it("ships 2000 ms for both file-backed stores in every bundled config", () => {
- expect(AGENTMEMORY_STATE_SAVE_INTERVAL_MS).toBe(2000);
- expect(intervals(read("iii-config.yaml"))).toEqual(["2000", "2000"]);
- expect(intervals(read("iii-config.docker.yaml"))).toEqual([
- "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:2000}",
- "${AGENTMEMORY_STATE_SAVE_INTERVAL_MS:2000}",
- ]);
- for (const platform of ["coolify", "fly", "railway", "render"]) {
- expect(intervals(read(`deploy/${platform}/entrypoint.sh`))).toEqual(["2000", "2000"]);
- }
- });
-
- it("keeps 2000 ms through the CLI render of the bundled config", () => {
- const rendered = rewriteBundledConfig(read("iii-config.yaml"), "/home/u", "node", "/x/index.mjs", {
- dataDir: "/home/u/.agentmemory/data",
- ports: { restPort: 4711, streamPort: 4712, viewerPort: 4713, enginePort: 49951 },
- });
- expect(intervals(rendered)).toEqual(["2000", "2000"]);
- expect(engineFlushWaitMs("file", [rendered])).toBe(3500);
- });
-
- it("applies an explicit override to both stores", () => {
- const rendered = renderEngineConfig(read("iii-config.yaml"), {
- dataDir: "/d",
- saveIntervalMs: 750,
- });
- expect(intervals(rendered)).toEqual(["750", "750"]);
- expect(configuredSaveIntervalMs(rendered)).toBe(750);
- });
-
- it("adds the interval to a custom file-backed store that has none and leaves in-memory stores alone", () => {
- const rendered = renderEngineConfig(customConfig, { dataDir: "/d" });
- expect(rendered).toContain(" store_method: file_based\n save_interval_ms: 2000\n");
- expect(intervals(rendered)).toEqual(["2000"]);
- });
-
- it("keeps a value the user wrote in their own config unless overridden", () => {
- const own = customConfig.replace("store_method: file_based", "store_method: file_based\n save_interval_ms: 9000");
- expect(intervals(renderEngineConfig(own, { dataDir: "/d" }))).toEqual(["9000"]);
- expect(intervals(renderEngineConfig(own, { dataDir: "/d", saveIntervalMs: 1000 }))).toEqual(["1000"]);
- });
-
- it("does not carry the interval into the redis adapter", () => {
- const rendered = renderEngineConfig(read("iii-config.yaml"), {
- dataDir: "/d",
- stateBackend: { kind: "redis", redisUrl: "redis://localhost:6379" },
- });
- expect(intervals(rendered)).toEqual([]);
- expect(engineFlushWaitMs("redis", [rendered])).toBe(0);
- });
-
- it("derives the interval from the persisted iii-state entry before the runtime config", () => {
+describe("engine state flush timing", () => {
+ it("derives the interval from the Compose state config before the runtime file", () => {
const paths = engineStateConfigPaths("/home/u/.agentmemory", "/data/iii-config.runtime.yaml");
- expect(paths[0]).toBe("/home/u/.agentmemory/config/iii-state.yaml");
+ expect(paths[0]).toBe("/home/u/.agentmemory/compose/worker-compose.yaml");
+ expect(paths).toContain("/home/u/.agentmemory/compose/config/state.yaml");
+ expect(paths.some((path) => path.includes("iii-state.yaml"))).toBe(false);
expect(paths.at(-1)).toBe("/data/iii-config.runtime.yaml");
- const persisted = "id: iii-state\nvalue:\n adapter:\n config:\n save_interval_ms: 2000\n store_method: file_based\n";
- const strippedRuntime = "workers:\n - name: iii-state\n # value now lives in the configuration worker\n";
- expect(engineSaveIntervalMs([persisted, strippedRuntime])).toBe(2000);
- expect(engineSaveIntervalMs([strippedRuntime])).toBe(5000);
- expect(engineFlushWaitMs("file", [persisted, strippedRuntime])).toBe(3500);
- });
-
- it("reads AGENTMEMORY_STATE_SAVE_INTERVAL_MS as a positive override", () => {
- vi.stubEnv("AGENTMEMORY_STATE_SAVE_INTERVAL_MS", "1500");
- expect(getStateSaveIntervalMs()).toBe(1500);
- vi.stubEnv("AGENTMEMORY_STATE_SAVE_INTERVAL_MS", "0");
- expect(getStateSaveIntervalMs()).toBeUndefined();
- vi.stubEnv("AGENTMEMORY_STATE_SAVE_INTERVAL_MS", "abc");
- expect(getStateSaveIntervalMs()).toBeUndefined();
+ const persisted = "id: iii-state\\nvalue:\\n adapter:\\n config:\\n save_interval_ms: 2000\\n store_method: file_based\\n";
+ expect(engineSaveIntervalMs([persisted])).toBe(2000);
+ expect(engineFlushWaitMs("file", [persisted])).toBe(3500);
+ expect(engineFlushWaitMs("redis", [persisted])).toBe(0);
});
});
-describe("engine child environment", () => {
- it("bounds glibc malloc arenas on linux", () => {
- expect(engineChildEnv({ PATH: "/usr/bin" }, "linux")["MALLOC_ARENA_MAX"]).toBe("2");
- });
-
- it("keeps a MALLOC_ARENA_MAX the user already set", () => {
- expect(engineChildEnv({ MALLOC_ARENA_MAX: "8" }, "linux")["MALLOC_ARENA_MAX"]).toBe("8");
- });
-
- it("does not set it on macOS or Windows", () => {
- expect(engineChildEnv({}, "darwin")["MALLOC_ARENA_MAX"]).toBeUndefined();
- expect(engineChildEnv({}, "win32")["MALLOC_ARENA_MAX"]).toBeUndefined();
- });
-
- it("sets it for the docker engine and the deploy entrypoints without overriding the user", () => {
- expect(read("docker-compose.yml")).toContain('MALLOC_ARENA_MAX: "${MALLOC_ARENA_MAX:-2}"');
- for (const platform of ["coolify", "fly", "railway", "render"]) {
- expect(read(`deploy/${platform}/entrypoint.sh`)).toContain('if [ -z "${MALLOC_ARENA_MAX:-}" ]; then');
- }
- });
-});
-
-describe("engine open-file limit", () => {
- it.skipIf(process.platform === "win32")("a child spawned by the CLI runtime inherits a soft limit raised to the hard limit", () => {
- const script = [
- 'const { execSync } = require("node:child_process");',
- 'process.stdout.write(execSync("ulimit -n").toString().trim());',
- ].join(" ");
- const result = spawnSync("/bin/sh", ["-c", 'ulimit -S -n 256 && exec "$@"', "outer", process.execPath, "-e", script], {
- encoding: "utf-8",
- timeout: 15_000,
+describe("Worker Compose runtime configuration", () => {
+ it("renders the registry workers and state flush interval without legacy config templates", () => {
+ const rendered = renderWorkerCompose({
+ ports: { restPort: 3211, viewerPort: 3213, enginePort: 49234 },
+ dataDir: "/var/lib/agentmemory",
+ projectRoot: "/opt/agentmemory",
+ nodeBin: "/usr/bin/node",
+ homeDir: "/home/u",
+ linux: false,
});
- expect(result.status).toBe(0);
- const hard = spawnSync("/bin/sh", ["-c", "ulimit -H -n"], { encoding: "utf-8" }).stdout.trim();
- const seen = result.stdout.trim();
- if (hard === "unlimited") expect(seen === "unlimited" || Number(seen) >= 10240).toBe(true);
- else expect(Number(seen)).toBe(Number(hard));
+ expect(rendered).toContain("version: '0.22.20'");
+ expect(rendered).toContain("version: '0.22.7'");
+ expect(rendered).toContain("save_interval_ms: 2000");
+ expect(rendered).toContain("file_path: '/var/lib/agentmemory/state_store.db'");
+ expect(rendered).not.toContain("iii-config.yaml");
+ expect(read("docker-compose.yml")).toContain('MALLOC_ARENA_MAX: "2"');
+ expect(read("deploy/runtime/entrypoint.sh")).toContain('export MALLOC_ARENA_MAX="${MALLOC_ARENA_MAX:-2}"');
});
+});
- it("sets the limit for the docker engine and the deploy entrypoints", () => {
- expect(read("docker-compose.yml")).toMatch(/ulimits:\n\s+nofile:\n\s+soft: 10240\n\s+hard: 10240/);
- for (const platform of ["coolify", "fly", "railway", "render"]) {
- expect(read(`deploy/${platform}/entrypoint.sh`)).toContain("ulimit -n 10240 2>/dev/null");
- }
+describe("self-host deploy resource limits", () => {
+ it("retains the deploy entrypoint open-file limit", () => {
+ const entrypoint = read("deploy/runtime/entrypoint.sh");
+ expect(entrypoint).toContain('current_nofile="$(ulimit -n)"');
+ expect(entrypoint).toContain("ulimit -n 10240 2>/dev/null");
});
});
diff --git a/test/engine-launch.test.ts b/test/engine-launch.test.ts
index 431ab034..263de9f6 100644
--- a/test/engine-launch.test.ts
+++ b/test/engine-launch.test.ts
@@ -1,236 +1,17 @@
import { describe, it, expect } from "vitest";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import {
- agentmemoryHome,
- dockerComposeArgs,
- dockerProjectName,
- isBundledConfig,
- legacyDataMigrations,
- redactCredentialUrls,
- resolveEngineCwd,
- resolveLaunchRenderFailure,
- rewriteBundledConfig,
- runtimeConfigPath,
-} from "../src/cli/engine-launch.js";
+import { redactCredentialUrls, runtimeConfigPath } from "../src/cli/engine-launch.js";
-const HOME = "/Users/test";
-
-describe("engine-launch path resolution", () => {
- it("agentmemoryHome anchors config and runtimeConfigPath scopes instance state", () => {
- expect(agentmemoryHome(HOME)).toBe(join(HOME, ".agentmemory"));
- expect(runtimeConfigPath("/var/lib/agentmemory/instance-1")).toBe(
- join("/var/lib/agentmemory/instance-1", "iii-config.runtime.yaml"),
- );
- });
-
- it("isBundledConfig matches both package config locations", () => {
- const dist = "/opt/pkg/dist";
- expect(isBundledConfig(join(dist, "iii-config.yaml"), dist)).toBe(true);
- expect(isBundledConfig(join(dist, "..", "iii-config.yaml"), dist)).toBe(true);
- expect(isBundledConfig("/opt/pkg/iii-config.yaml", dist)).toBe(true);
- expect(isBundledConfig(join(HOME, ".agentmemory", "iii-config.yaml"), dist)).toBe(false);
- expect(isBundledConfig("/some/project/iii-config.yaml", dist)).toBe(false);
- });
-
- it("resolveEngineCwd keeps the invocation cwd for repo-local configs", () => {
- const repo = "/work/agentmemory";
- expect(resolveEngineCwd(join(repo, "iii-config.yaml"), repo, HOME)).toBe(repo);
- });
-
- it("resolveEngineCwd anchors bundled configs and preserves custom config roots", () => {
- const repo = "/work/some-project";
- expect(resolveEngineCwd("/opt/pkg/dist/iii-config.yaml", repo, HOME, true)).toBe(
- join(HOME, ".agentmemory"),
- );
- expect(
- resolveEngineCwd(join(HOME, ".agentmemory", "iii-config.yaml"), repo, HOME),
- ).toBe(join(HOME, ".agentmemory"));
- expect(resolveEngineCwd("/etc/custom-iii.yaml", repo, HOME)).toBe(
- "/etc",
- );
- expect(resolveEngineCwd("custom-iii.yaml", repo, HOME)).toBe(repo);
- });
-
- it("scopes Docker compose commands by REST-port project", () => {
- expect(dockerProjectName(3211)).toBe("agentmemory-3211");
- expect(
- dockerComposeArgs("/opt/agentmemory/docker-compose.yml", "agentmemory-3211", [
- "up",
- "-d",
- ]),
- ).toEqual([
- "compose",
- "-p",
- "agentmemory-3211",
- "-f",
- "/opt/agentmemory/docker-compose.yml",
- "up",
- "-d",
- ]);
- });
-
- it("legacyDataMigrations targets the resolved platform data dir", () => {
- const resolvedDataDir = "/var/lib/agentmemory";
- const migrations = legacyDataMigrations("/work/proj", HOME, resolvedDataDir);
- expect(migrations).toEqual([
- {
- from: join("/work/proj", "data", "state_store.db"),
- to: join(resolvedDataDir, "state_store.db"),
- },
- {
- from: join("/work/proj", "data", "stream_store"),
- to: join(resolvedDataDir, "stream_store"),
- },
- ]);
+describe("engine runtime metadata paths", () => {
+ it("scopes the legacy runtime config path to its resolved data directory", () => {
+ expect(runtimeConfigPath("/var/lib/agentmemory/instance-1")).toBe("/var/lib/agentmemory/instance-1/iii-config.runtime.yaml");
});
});
-describe("bundled iii-config.yaml", () => {
- it("leaves worker ownership to the CLI", () => {
- const raw = readFileSync(join(import.meta.dirname, "..", "iii-config.yaml"), "utf-8");
- expect(raw).not.toContain("- name: iii-exec");
- });
-});
-
-describe("rewriteBundledConfig", () => {
- const SAMPLE = [
- " file_path: ./data/state_store.db",
- " file_path: ./data/stream_store",
- " - name: iii-exec",
- " config:",
- " watch:",
- " - src/**/*.ts",
- " exec:",
- " - node dist/index.mjs",
- ].join("\n");
-
- it("substitutes data paths and removes bundled worker supervision", () => {
- const out = rewriteBundledConfig(SAMPLE, HOME, "/usr/bin/node", "/opt/pkg/dist/index.mjs");
- expect(out).toContain(
- `file_path: '${join(HOME, ".agentmemory", "data", "state_store.db")}'`,
- );
- expect(out).toContain(
- `file_path: '${join(HOME, ".agentmemory", "data", "stream_store")}'`,
- );
- expect(out).not.toContain("./data/");
- expect(out).not.toContain("- name: iii-exec");
- expect(out).not.toContain("src/**/*.ts");
- });
-
- it("preserves unrelated commands in the bundled iii-exec worker", () => {
- const bundled = [
- "workers:",
- " - name: iii-exec",
- " config:",
- " exec:",
- " - node dist/index.mjs",
- " - node scripts/other-worker.mjs",
- ].join("\n");
-
- const out = rewriteBundledConfig(
- bundled,
- HOME,
- "/usr/bin/node",
- "/opt/pkg/dist/index.mjs",
- );
- expect(out).toContain("- name: iii-exec");
- expect(out).toContain("- node scripts/other-worker.mjs");
- expect(out).not.toContain("- node dist/index.mjs");
- });
-
- it("escapes apostrophes in paths for single-quoted YAML", () => {
- const out = rewriteBundledConfig(
- SAMPLE,
- "/Users/o'brien",
- "/usr/bin/node",
- "/opt/pkg/dist/index.mjs",
- );
- expect(out).toContain("o''brien");
+describe("credential URL redaction", () => {
+ it("masks credentials without touching the rest of the message", () => {
+ expect(redactCredentialUrls("Failed redis://user:s3cr3t@localhost:6379"))
+ .toBe("Failed redis://***@localhost:6379");
});
-
- it("rewrites the real bundled config with no relative paths left", () => {
- const raw = readFileSync(join(import.meta.dirname, "..", "iii-config.yaml"), "utf-8");
- const out = rewriteBundledConfig(raw, HOME, process.execPath, "/opt/pkg/dist/index.mjs");
- expect(out).not.toContain("./data/");
- expect(out).not.toContain("src/**/*.ts");
- expect(out).not.toContain("- node dist/index.mjs");
- expect(out).not.toContain("- name: iii-exec");
- expect(out).toContain(join(HOME, ".agentmemory", "data", "state_store.db"));
- expect(out).toContain(join(HOME, ".agentmemory", "data", "stream_store"));
- });
-
- it("uses the CLI-resolved data directory and port quartet", () => {
- const raw = readFileSync(join(import.meta.dirname, "..", "iii-config.yaml"), "utf-8");
- const dataDir = "/var/lib/agentmemory";
- const out = rewriteBundledConfig(
- raw,
- HOME,
- process.execPath,
- "/opt/pkg/dist/index.mjs",
- {
- dataDir,
- ports: {
- restPort: 3211,
- streamPort: 3212,
- viewerPort: 3213,
- enginePort: 49234,
- },
- },
- );
-
- expect(out).toContain(join(dataDir, "state_store.db"));
- expect(out).toContain("port: 3211");
- expect(out).toContain("port: 3212");
- expect(out).toContain("port: 49234");
- });
-
- it("forwards the redis state backend through to renderEngineConfig", () => {
- const raw = readFileSync(join(import.meta.dirname, "..", "iii-config.yaml"), "utf-8");
- const out = rewriteBundledConfig(
- raw,
- HOME,
- process.execPath,
- "/opt/pkg/dist/index.mjs",
- {
- dataDir: "/var/lib/agentmemory",
- stateBackend: { kind: "redis", redisUrl: "redis://localhost:6379" },
- },
- );
-
- expect(out).toMatch(/- name: iii-state\n {4}config:\n {6}adapter:\n {8}name: redis/);
- expect(out).toMatch(/- name: iii-stream\n {4}config:\n {6}port: 3112\n {6}host: 127\.0\.0\.1\n {6}adapter:\n {8}name: redis/);
- expect(out).not.toContain("store_method: file_based");
- });
-});
-
-describe("resolveLaunchRenderFailure", () => {
- it("is fatal when the redis backend fails to render, so the launch never silently falls back", () => {
- const result = resolveLaunchRenderFailure("redis", new Error("no adapter block"));
- expect(result.fatal).toBe(true);
- expect(result.fatal && result.message).toMatch(/no adapter block/);
- });
-
- it("stays non-fatal for the file backend, keeping the bundled-config fallback", () => {
- const result = resolveLaunchRenderFailure("file", new Error("disk full"));
- expect(result).toEqual({ fatal: false });
- });
-
- it("stringifies a non-Error throw", () => {
- const result = resolveLaunchRenderFailure("redis", "permission denied");
- expect(result.fatal && result.message).toMatch(/permission denied/);
- });
-});
-
-describe("redactCredentialUrls", () => {
- it("masks userinfo in a redis URL without touching the rest of the message", () => {
- const out = redactCredentialUrls(
- "Failed to connect to redis://user:s3cr3t@localhost:6379: connection refused",
- );
- expect(out).toBe("Failed to connect to redis://***@localhost:6379: connection refused");
- expect(out).not.toContain("s3cr3t");
- });
-
it("leaves text with no credentials untouched", () => {
expect(redactCredentialUrls("engine exited with code 1")).toBe("engine exited with code 1");
});
diff --git a/test/graph-compact-boot.test.ts b/test/graph-compact-boot.test.ts
index 3f5fe79f..a7404087 100644
--- a/test/graph-compact-boot.test.ts
+++ b/test/graph-compact-boot.test.ts
@@ -1,5 +1,6 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { readFileSync } from "node:fs";
+import { III_PINNED_VERSION } from "../src/version.js";
vi.mock("../src/logger.js", () => ({
logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
@@ -359,10 +360,10 @@ describe("graph compaction in /agentmemory/status", () => {
const base: StatusInputs = {
now: new Date("2026-10-01T12:00:00.000Z"),
version: "0.9.30",
- engineVersion: "0.22.1",
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: 10,
stateBackend: "file",
- ports: { rest: 4611, streams: 4612, viewer: 4613 },
+ ports: { rest: 4611, viewer: 4613 },
health: null,
circuitBreaker: null,
functionMetrics: [],
diff --git a/test/graph-generation.test.ts b/test/graph-generation.test.ts
index 2c39ea68..70918dcd 100644
--- a/test/graph-generation.test.ts
+++ b/test/graph-generation.test.ts
@@ -1,3 +1,4 @@
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { initializeGraphIndex } from "../src/state/graph-retrieval-index.js";
import { indexObservationSession } from "../src/state/obs-index.js";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -43,12 +44,12 @@ async function setup(provider = { name: "noop", compress: vi.fn(async () => xml)
const store = new Map<string, Map<string, unknown>>();
const handlers = new Map<string, (data?: any) => Promise<any>>();
const sent: any[] = [];
+ const unsubscribeEvents = onLiveEvent((event) => sent.push({ type: event.type, data: structuredClone(event.data) }));
let intercept: ((id: string, payload: any) => Promise<void>) | undefined;
const sdk = {
registerFunction: (id: string, fn: (data?: any) => Promise<any>) => handlers.set(id, fn),
registerTrigger: vi.fn(),
trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
- if (id === "stream::send") { sent.push(structuredClone(payload)); return {}; }
if (!id.startsWith("state::")) return handlers.get(id)!(payload);
await intercept?.(id, payload);
const rows = store.get(payload.scope) ?? new Map<string, unknown>();
@@ -71,7 +72,7 @@ async function setup(provider = { name: "noop", compress: vi.fn(async () => xml)
registerMeshFunction(sdk as never, kv);
registerReflectFunctions(sdk as never, kv, provider as never);
const call = (id: string, payload: any = {}) => sdk.trigger({ function_id: id, payload });
- return { kv, sdk, call, store, sent, provider, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+ return { kv, sdk, call, store, sent, unsubscribeEvents, provider, intercept: (fn?: typeof intercept) => { intercept = fn; } };
}
async function seed(kv: StateKV) {
diff --git a/test/graph-ingestion-import-mesh.test.ts b/test/graph-ingestion-import-mesh.test.ts
index 2bad8d3d..cec1d931 100644
--- a/test/graph-ingestion-import-mesh.test.ts
+++ b/test/graph-ingestion-import-mesh.test.ts
@@ -1,3 +1,4 @@
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { initializeGraphIndex } from "../src/state/graph-retrieval-index.js";
import { afterEach, describe, expect, it, vi } from "vitest";
import { StateKV, applyUpdateOps } from "../src/state/kv.js";
@@ -34,13 +35,14 @@ function deferred() {
async function rig(rotated = true) {
const store = new Map<string, Map<string, unknown>>();
const handlers = new Map<string, (data: any) => Promise<any>>();
+ const sent: any[] = [];
+ const unsubscribeEvents = onLiveEvent((event) => sent.push({ type: event.type, data: structuredClone(event.data) }));
const triggers: Array<{ type: string; function_id: string; config: { scope?: string } }> = [];
let intercept: ((id: string, payload: any) => Promise<void>) | undefined;
const sdk = {
registerFunction: (id: string, fn: (data: any) => Promise<any>) => handlers.set(id, fn),
registerTrigger: (trigger: typeof triggers[number]) => triggers.push(trigger),
trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
- if (id === "stream::send") return {};
if (!id.startsWith("state::")) return handlers.get(id)!(payload);
await intercept?.(id, payload);
const rows = store.get(payload.scope) ?? new Map<string, unknown>();
@@ -70,7 +72,7 @@ async function rig(rotated = true) {
if (rotated) await call("mem::graph-reset");
else await initializeGraphIndex(kv, { status: "ready" });
await getViewerCounts(kv);
- return { kv, call, store, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+ return { kv, call, store, sent, unsubscribeEvents, intercept: (fn?: typeof intercept) => { intercept = fn; } };
}
async function expectGraph(r: Awaited<ReturnType<typeof rig>>, ids: string[], edgeCount: number) {
diff --git a/test/graph-ingestion.test.ts b/test/graph-ingestion.test.ts
index f4d4768f..73ea454a 100644
--- a/test/graph-ingestion.test.ts
+++ b/test/graph-ingestion.test.ts
@@ -1,3 +1,4 @@
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { afterEach, describe, expect, it, vi } from "vitest";
import { StateKV, applyUpdateOps } from "../src/state/kv.js";
import { KV } from "../src/state/schema.js";
@@ -37,12 +38,12 @@ function setup(backend: "file" | "redis" = "file") {
const handlers = new Map<string, (data?: any) => Promise<any>>();
const calls: Array<{ id: string; payload: Payload }> = [];
const sent: any[] = [];
+ const unsubscribeEvents = onLiveEvent((event) => sent.push({ type: event.type, data: structuredClone(event.data) }));
let intercept: ((id: string, payload: Payload) => Promise<void> | void) | undefined;
const sdk = {
registerFunction: (id: string, fn: (data?: any) => Promise<any>) => handlers.set(id, fn),
registerTrigger: vi.fn(),
trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
- if (id === "stream::send") { sent.push(structuredClone(payload)); return {}; }
if (!id.startsWith("state::")) return handlers.get(id)!(payload);
calls.push({ id, payload: structuredClone(payload) });
await intercept?.(id, payload);
@@ -67,9 +68,10 @@ function setup(backend: "file" | "redis" = "file") {
};
const kv = new StateKV(sdk as never, { backend });
registerGraphFunction(sdk as never, kv, { name: "noop" } as never);
+ registerViewerStreamTriggers(sdk as never, kv);
const call = (id: string, payload: any = {}) => sdk.trigger({ function_id: id, payload });
const snapshot = async (view = kv) => (await view.get<GraphSnapshot>(KV.graphSnapshot, "current"))!;
- return { kv, sdk, store, calls, sent, call, snapshot, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+ return { kv, sdk, store, calls, sent, call, snapshot, unsubscribeEvents, intercept: (fn?: typeof intercept) => { intercept = fn; } };
}
async function degrees(kv: StateKV, ids: string[]) {
diff --git a/test/hermes-live-model.py b/test/hermes-live-model.py
old mode 100644
new mode 100755
diff --git a/test/hermes-live-preflight.test.ts b/test/hermes-live-preflight.test.ts
index 1ec7591e..8529bc51 100644
--- a/test/hermes-live-preflight.test.ts
+++ b/test/hermes-live-preflight.test.ts
@@ -1,10 +1,11 @@
import { afterEach, describe, expect, it } from "vitest";
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
const roots: string[] = [];
+const PYTHON = execFileSync("python3", ["-c", "import sys; print(sys.executable)"], { encoding: "utf8" }).trim();
const token = (payload: unknown) => `synthetic.${Buffer.from(JSON.stringify(payload)).toString("base64url")}.signature`;
afterEach(() => {
@@ -17,7 +18,7 @@ function fixture() {
const auth = join(root, "auth.json");
const out = join(root, "evidence");
const pkg = join(root, "missing-package");
- const run = () => spawnSync("python3", [
+ const run = () => spawnSync(PYTHON, [
resolve("test/hermes-live-model.py"),
"--package", pkg,
"--host", join(root, "unused-host"),
diff --git a/test/hermes-native-e2e.py b/test/hermes-native-e2e.py
old mode 100644
new mode 100755
diff --git a/test/hermes-plugin.test.ts b/test/hermes-plugin.test.ts
index 825dfe68..bb0f96ca 100644
--- a/test/hermes-plugin.test.ts
+++ b/test/hermes-plugin.test.ts
@@ -1,6 +1,8 @@
import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
+
+const PYTHON = execFileSync("python3", ["-c", "import sys; print(sys.executable)"], { encoding: "utf8" }).trim();
const expectedHermesHooks = [
"on_turn_start",
@@ -66,7 +68,7 @@ describe("Hermes plugin manifest", () => {
});
it("satisfies native provider runtime and credential contracts", () => {
- const result = spawnSync("python3", ["test/hermes-provider-contracts.py", "-v"], {
+ const result = spawnSync(PYTHON, ["test/hermes-provider-contracts.py", "-v"], {
encoding: "utf8",
timeout: 60_000,
env: { PATH: process.env.PATH, PYTHONDONTWRITEBYTECODE: "1" },
diff --git a/test/hermes-provider-contracts.py b/test/hermes-provider-contracts.py
old mode 100644
new mode 100755
diff --git a/test/index-persistence-throttle.test.ts b/test/index-persistence-throttle.test.ts
index 3764a402..d0b7d9ae 100644
--- a/test/index-persistence-throttle.test.ts
+++ b/test/index-persistence-throttle.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import { IndexPersistence } from "../src/state/index-persistence.js";
import { VectorIndex } from "../src/state/vector-index.js";
import { evaluateStatus, renderStatusHtml, type StatusInputs } from "../src/functions/status.js";
+import { III_PINNED_VERSION } from "../src/version.js";
const META_KEY = "vectors:meta";
@@ -250,9 +251,9 @@ function statusInputs(overrides: Partial<StatusInputs> = {}): StatusInputs {
return {
now: new Date("2026-09-25T12:00:00.000Z"),
version: "0.9.29",
- engineVersion: "0.22.1",
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: 100,
- ports: { rest: 3111, streams: 3112, viewer: 3113 },
+ ports: { rest: 3111, viewer: 3113 },
health: { status: "healthy", alerts: [], notes: [], connectionState: "connected" },
circuitBreaker: null,
functionMetrics: [],
diff --git a/test/legacy-docker-state.test.ts b/test/legacy-docker-state.test.ts
new file mode 100644
index 00000000..41fa978d
--- /dev/null
+++ b/test/legacy-docker-state.test.ts
@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { legacyDockerStateMessage, legacyDockerStopCommand } from "../src/cli/legacy-docker-state.js";
+
+const state = {
+ kind: "docker" as const,
+ composeFile: "/tmp/old project's/docker-compose.yml",
+ projectName: "agentmemory-3111",
+ restPort: 3111,
+};
+
+const command = `docker compose -p 'agentmemory-3111' -f '/tmp/old project'"'"'s/docker-compose.yml' stop`;
+
+async function freePort(): Promise<number> {
+ const server = createServer();
+ await new Promise<void>((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", resolve);
+ });
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("failed to allocate free REST port");
+ const port = address.port;
+ await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+ return port;
+}
+
+describe("legacy Docker state migration notice", () => {
+ it("builds a scoped Compose stop command from the saved project and file", () => {
+ expect(legacyDockerStopCommand(state)).toBe(command);
+ });
+
+ it("warns without changing state and explains the exact next action", () => {
+ const message = legacyDockerStateMessage(state);
+ expect(message).toContain("older Docker-based agentmemory CLI (REST port 3111)");
+ expect(message).toContain(command);
+ expect(message).toContain("no container or data was changed");
+ });
+
+ it("falls back to the saved container ID only when Compose metadata is absent", () => {
+ expect(legacyDockerStopCommand({ kind: "docker", containerId: "old-engine-1" })).toBe("docker stop 'old-engine-1'");
+ });
+});
+
+
+const sandboxes: string[] = [];
+
+afterEach(() => {
+ for (const path of sandboxes.splice(0)) rmSync(path, { recursive: true, force: true });
+});
+
+describe("legacy Docker lifecycle CLI compatibility", () => {
+ it.each(["start", "stop", "status", "remove"] as const)(
+ "reports recovery instructions on %s without calling Docker or clearing state/data",
+ async (command) => {
+ const root = mkdtempSync(join(tmpdir(), "agentmemory-legacy-cli-"));
+ sandboxes.push(root);
+ const home = join(root, "home");
+ const runtime = join(home, ".agentmemory");
+ const port = await freePort();
+ const legacyStateForPort = { ...state, restPort: port, projectName: `agentmemory-${port}` };
+ const dataDir = join(root, "data");
+ const binDir = join(root, "bin");
+ const dockerLog = join(root, "docker.log");
+ mkdirSync(runtime, { recursive: true });
+ mkdirSync(dataDir, { recursive: true });
+ writeFileSync(join(dataDir, "legacy-data.txt"), "preserve me");
+ mkdirSync(binDir, { recursive: true });
+ const docker = join(binDir, "docker");
+ writeFileSync(docker, `#!/bin/sh\nprintf called >> "$DOCKER_LOG"\nexit 90\n`, { mode: 0o755 });
+ const statePath = join(runtime, "engine-state.json");
+ const legacyState = legacyStateForPort;
+ writeFileSync(statePath, JSON.stringify(legacyState));
+ const args = command === "start"
+ ? ["--port", String(port), "--data-dir", dataDir, "--reset"]
+ : [command, ...(command === "remove" ? ["--force"] : []), "--port", String(port), "--data-dir", dataDir];
+ const result = spawnSync(process.execPath, ["--import", "tsx", "src/cli.ts", ...args], {
+ cwd: process.cwd(),
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ AGENTMEMORY_RUNTIME_DIR: runtime,
+ CI: "1",
+ PATH: `${binDir}:${process.env.PATH ?? ""}`,
+ DOCKER_LOG: dockerLog,
+ AGENTMEMORY_URL: `http://127.0.0.1:${port}`,
+ III_REST_PORT: String(port),
+ },
+ });
+ const output = `${result.stdout}\n${result.stderr}`;
+
+ expect(result.status).not.toBe(0);
+ expect(output).toContain(`older Docker-based agentmemory CLI (REST port ${port})`);
+ if (command !== "remove") expect(output).toContain(command);
+ expect(output).toContain(`docker compose -p 'agentmemory-${port}'`);
+ expect(readFileSync(statePath, "utf8")).toBe(JSON.stringify(legacyState));
+ expect(readFileSync(join(dataDir, "legacy-data.txt"), "utf8")).toBe("preserve me");
+ expect(existsSync(dockerLog)).toBe(false);
+ },
+ );
+});
diff --git a/test/live-events.test.ts b/test/live-events.test.ts
new file mode 100644
index 00000000..07f7220b
--- /dev/null
+++ b/test/live-events.test.ts
@@ -0,0 +1,49 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it, vi } from "vitest";
+import { formatSseFrame, LiveEventsHub, type LiveEventWriter } from "../src/viewer/live-events.js";
+
+class Writer extends EventEmitter {
+ writableLength = 0;
+ destroyed = false;
+ frames: string[] = [];
+ write(frame: string) { this.frames.push(frame); return true; }
+ destroy() { this.destroyed = true; this.emit("close"); return this; }
+}
+
+describe("LiveEventsHub", () => {
+ it("formats a one-line SSE JSON envelope and fans out to all listeners", () => {
+ const hub = new LiveEventsHub();
+ const a = new Writer();
+ const b = new Writer();
+ hub.subscribe(a as unknown as LiveEventWriter);
+ hub.subscribe(b as unknown as LiveEventWriter);
+ const event = { id: "e1", type: "memory.created", data: { memoryId: "m1" } };
+ hub.emit(event);
+ expect(a.frames).toEqual([formatSseFrame(event)]);
+ expect(b.frames).toEqual([formatSseFrame(event)]);
+ expect(hub.stats()).toMatchObject({ subscribers: 2, eventsSent: 2, dropped: 0, lastEventAt: expect.any(Number) });
+ a.emit("close");
+ expect(hub.stats().subscribers).toBe(1);
+ });
+
+ it("heartbeats on interval and drops slow subscribers over 1 MiB", () => {
+ vi.useFakeTimers();
+ const hub = new LiveEventsHub();
+ const slow = new Writer();
+ hub.subscribe(slow as unknown as LiveEventWriter);
+ vi.advanceTimersByTime(15_000);
+ expect(slow.frames).toContain(": ping\n\n");
+ slow.writableLength = 1024 * 1024 + 1;
+ hub.emit({ id: "e2", type: "session.updated", data: {} });
+ expect(hub.stats()).toMatchObject({ subscribers: 0, dropped: 1 });
+ vi.useRealTimers();
+ });
+
+ it("caps the subscriber set at 32", () => {
+ const hub = new LiveEventsHub();
+ const writers = Array.from({ length: 33 }, () => new Writer());
+ writers.forEach((writer) => hub.subscribe(writer as unknown as LiveEventWriter));
+ expect(hub.stats()).toMatchObject({ subscribers: 32, dropped: 1 });
+ expect(writers[0]!.destroyed).toBe(true);
+ });
+});
diff --git a/test/multi-instance-port.test.ts b/test/multi-instance-port.test.ts
index 20c8767b..3133b5ee 100644
--- a/test/multi-instance-port.test.ts
+++ b/test/multi-instance-port.test.ts
@@ -3,11 +3,10 @@ import { loadConfig } from "../src/config";
const PORT_ENVS = [
"III_REST_PORT",
- "III_STREAM_PORT",
- "III_STREAMS_PORT",
"III_VIEWER_PORT",
"III_ENGINE_PORT",
"III_ENGINE_URL",
+ "III_URL",
] as const;
describe("multi-instance port auto-derive", () => {
@@ -30,52 +29,33 @@ describe("multi-instance port auto-derive", () => {
}
});
- it("default REST anchor yields canonical 3111/3112/49134 quartet", () => {
+ it("default REST anchor yields REST/viewer/engine ports", () => {
const cfg = loadConfig();
expect(cfg.restPort).toBe(3111);
- expect(cfg.streamsPort).toBe(3112);
expect(cfg.viewerPort).toBe(3113);
expect(cfg.engineUrl).toBe("ws://localhost:49134");
});
- it("relocating REST drags streams + engine with it", () => {
+ it("relocating REST drags viewer + engine with it", () => {
process.env["III_REST_PORT"] = "3211";
const cfg = loadConfig();
expect(cfg.restPort).toBe(3211);
- expect(cfg.streamsPort).toBe(3212);
expect(cfg.viewerPort).toBe(3213);
expect(cfg.engineUrl).toBe("ws://localhost:49234");
});
- it("instance N=2 block (3311) lands on 3312 + 49334", () => {
+ it("instance N=2 block (3311) lands on viewer 3313 + engine 49334", () => {
process.env["III_REST_PORT"] = "3311";
const cfg = loadConfig();
expect(cfg.restPort).toBe(3311);
- expect(cfg.streamsPort).toBe(3312);
expect(cfg.engineUrl).toBe("ws://localhost:49334");
});
- it("explicit III_STREAM_PORT pins streams without affecting REST/engine", () => {
- process.env["III_REST_PORT"] = "3211";
- process.env["III_STREAM_PORT"] = "9999";
- const cfg = loadConfig();
- expect(cfg.restPort).toBe(3211);
- expect(cfg.streamsPort).toBe(9999);
- expect(cfg.engineUrl).toBe("ws://localhost:49234");
- });
-
- it("legacy III_STREAMS_PORT still honored", () => {
- process.env["III_STREAMS_PORT"] = "9000";
- const cfg = loadConfig();
- expect(cfg.streamsPort).toBe(9000);
- });
-
- it("explicit III_ENGINE_PORT pins engine without affecting REST/streams", () => {
+ it("explicit III_ENGINE_PORT pins engine without affecting REST/viewer", () => {
process.env["III_REST_PORT"] = "3211";
process.env["III_ENGINE_PORT"] = "55555";
const cfg = loadConfig();
expect(cfg.restPort).toBe(3211);
- expect(cfg.streamsPort).toBe(3212);
expect(cfg.engineUrl).toBe("ws://localhost:55555");
});
@@ -86,6 +66,12 @@ describe("multi-instance port auto-derive", () => {
expect(cfg.viewerPort).toBe(7777);
});
+ it("Compose-reserved III_URL overrides the derived bridge endpoint", () => {
+ process.env["III_REST_PORT"] = "3511";
+ process.env["III_URL"] = "ws://127.0.0.1:49534";
+ expect(loadConfig().engineUrl).toBe("ws://127.0.0.1:49534");
+ });
+
it("legacy III_ENGINE_URL overrides derivation entirely", () => {
process.env["III_REST_PORT"] = "3211";
process.env["III_ENGINE_URL"] = "ws://remote-host:49999";
diff --git a/test/no-stream-legacy.test.ts b/test/no-stream-legacy.test.ts
new file mode 100644
index 00000000..6de96c73
--- /dev/null
+++ b/test/no-stream-legacy.test.ts
@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+function sourceFiles(dir: string): string[] {
+ return readdirSync(dir).flatMap((name) => {
+ const path = join(dir, name);
+ return statSync(path).isDirectory() ? sourceFiles(path) : [path];
+ });
+}
+
+describe("removed stream/pubsub guard", () => {
+ it("keeps application source free of the deprecated stream transport", () => {
+ const root = import.meta.dirname + "/..";
+ const files = sourceFiles(join(root, "src"));
+ const forbidden = [
+ /stream::/,
+ /STREAM\./,
+ /\/stream\/mem-live/,
+ /III_STREAM_PORT/,
+ /streamsPort/,
+ /new WebSocket/,
+ /wsPort/,
+ /iii-stream/,
+ /iii-pubsub/,
+ ];
+ for (const file of files) {
+ const text = readFileSync(file, "utf8");
+ for (const pattern of forbidden) {
+ expect(text, `${file} retained ${pattern}`).not.toMatch(pattern);
+ }
+ }
+ });
+});
diff --git a/test/observation-source.test.ts b/test/observation-source.test.ts
index c816a4f5..db9ebbcb 100644
--- a/test/observation-source.test.ts
+++ b/test/observation-source.test.ts
@@ -1,3 +1,4 @@
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
@@ -142,10 +143,14 @@ describe("retained observation source", () => {
expect(JSON.stringify(response)).not.toContain(tail);
}
expect(buildSummaryPrompt([observation])).not.toContain(tail);
- const updates = sdk.trigger.mock.calls.map(([input]) => input)
- .filter((input) => input.function_id === "stream::set");
+ const updates: unknown[] = [];
+ const unsubscribe = onLiveEvent((event) => updates.push(event));
+ await observe("post_tool_use", { tool_name: "Read", tool_input: { file_path: "config.ts" }, tool_output: tail });
+ unsubscribe();
expect(updates.length).toBeGreaterThan(0);
- expect(JSON.stringify(updates)).not.toContain(tail);
+ const compressedEvent = updates.find((event) => (event as any).type === "compressed_observation") as any;
+ expect(compressedEvent.data.observation.source).toBeUndefined();
+ expect(compressedEvent.data.observation.sourceObservation).toBeUndefined();
});
it("preserves source when model compression succeeds without returning it to the model caller or viewer", async () => {
@@ -164,10 +169,13 @@ describe("retained observation source", () => {
expect(saved.narrative).not.toContain(tail);
expect(provider.compress).toHaveBeenCalledOnce();
expect(JSON.stringify(vi.mocked(provider.compress).mock.calls)).not.toContain(tail);
- const updates = r.sdk.trigger.mock.calls.map(([input]) => input)
- .filter((input) => input.function_id === "stream::send" && (input.payload as any).type === "compressed_observation");
- expect(updates.length).toBe(1);
- expect(JSON.stringify(updates)).not.toContain(tail);
+ const updates: unknown[] = [];
+ const unsubscribe = onLiveEvent((event) => updates.push(event));
+ await r.observe("post_tool_use", { tool_name: "Read", tool_input: { file_path: "config.ts" }, tool_output: `${"detail ".repeat(1000)}${tail}` });
+ unsubscribe();
+ const compressedEvents = updates.filter((event) => (event as any).type === "compressed_observation");
+ expect(compressedEvents.length).toBeGreaterThanOrEqual(1);
+ expect(JSON.stringify(compressedEvents)).not.toContain(tail);
});
it("makes a captured stop reply searchable and keeps it as the replay response", async () => {
diff --git a/test/observe-viewer-stream.test.ts b/test/observe-viewer-stream.test.ts
deleted file mode 100644
index 0532c0fc..00000000
--- a/test/observe-viewer-stream.test.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-
-vi.mock("../src/logger.js", () => ({
- logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
-}));
-
-import { registerObserveFunction } from "../src/functions/observe.js";
-import { STREAM } from "../src/state/schema.js";
-import { resetViewerStreamTracker } from "../src/state/viewer-stream.js";
-
-function mockKV() {
- const store = new Map<string, Map<string, unknown>>();
- return {
- store,
- get: async <T>(scope: string, key: string): Promise<T | null> =>
- (store.get(scope)?.get(key) as T) ?? null,
- set: async <T>(scope: string, key: string, data: T): Promise<T> => {
- if (!store.has(scope)) store.set(scope, new Map());
- store.get(scope)!.set(key, data);
- return data;
- },
- update: async (
- scope: string,
- key: string,
- updates: Array<{ path: string; value: unknown }>,
- ) => {
- const m = store.get(scope);
- if (!m) return;
- const v = (m.get(key) as Record<string, unknown>) ?? {};
- for (const u of updates) v[u.path] = u.value;
- m.set(key, v);
- },
- delete: async (scope: string, key: string) => {
- store.get(scope)?.delete(key);
- },
- list: async <T>(scope: string): Promise<T[]> => {
- const m = store.get(scope);
- return m ? (Array.from(m.values()) as T[]) : [];
- },
- };
-}
-
-function mockSdk() {
- const fns = new Map<string, (payload: unknown) => Promise<unknown>>();
- const trigger = vi.fn(
- async (input: { function_id: string; payload: unknown }) => {
- const fn = fns.get(input.function_id);
- return fn ? fn(input.payload) : null;
- },
- );
- return {
- registerFunction: (
- idOrOpts: string | { id: string },
- fn: (payload: unknown) => Promise<unknown>,
- ) => {
- fns.set(typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id, fn);
- },
- registerTrigger: () => {},
- trigger,
- };
-}
-
-function observePayload(sessionId: string, i: number) {
- return {
- sessionId,
- project: "agentmemory",
- cwd: "/tmp/agentmemory",
- hookType: "post_tool_use",
- timestamp: new Date().toISOString(),
- data: {
- tool_name: "Bash",
- tool_input: { command: `echo probe-${i}` },
- tool_output: `probe-${i} output`,
- },
- };
-}
-
-type StreamCall = {
- function_id: string;
- payload: { stream_name?: string; group_id?: string; item_id?: string };
-};
-
-describe("observe no longer writes per-session mem-live groups", () => {
- beforeEach(() => {
- resetViewerStreamTracker();
- delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
- });
-
- afterEach(() => {
- delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
- });
-
- it("never targets group_id === sessionId on any stream:: call", async () => {
- const sdk = mockSdk();
- const kv = mockKV();
- registerObserveFunction(sdk as never, kv as never);
-
- const sessionId = "ses_no_per_session_stream";
- await sdk.trigger({ function_id: "mem::observe", payload: observePayload(sessionId, 0) });
- await sdk.trigger({ function_id: "mem::observe", payload: observePayload(sessionId, 1) });
-
- const streamCalls = sdk.trigger.mock.calls
- .map((c) => c[0] as StreamCall)
- .filter((c) => c.function_id.startsWith("stream::"));
-
- expect(streamCalls.length).toBeGreaterThan(0);
- for (const call of streamCalls) {
- expect(call.payload.group_id).not.toBe(sessionId);
- expect(call.payload.group_id).toBe(STREAM.viewerGroup);
- }
- });
-
- it("prunes the viewer group once enough observations accumulate past the configured cap", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const sdk = mockSdk();
- const kv = mockKV();
- registerObserveFunction(sdk as never, kv as never);
-
- const sessionId = "ses_prune_wiring";
- for (let i = 0; i < 255; i++) {
- await sdk.trigger({ function_id: "mem::observe", payload: observePayload(sessionId, i) });
- }
-
- const deleteCalls = sdk.trigger.mock.calls
- .map((c) => c[0] as StreamCall)
- .filter((c) => c.function_id === "stream::delete");
-
- expect(deleteCalls.length).toBeGreaterThan(0);
- for (const call of deleteCalls) {
- expect(call.payload.group_id).toBe(STREAM.viewerGroup);
- }
- });
-});
diff --git a/test/plugin-published-compatibility.test.ts b/test/plugin-published-compatibility.test.ts
index c0571f03..b43492f4 100644
--- a/test/plugin-published-compatibility.test.ts
+++ b/test/plugin-published-compatibility.test.ts
@@ -1,14 +1,15 @@
import { describe, expect, it } from "vitest";
import { publishedCompatibilityErrors } from "../scripts/plugins/verify-published.mjs";
+import { III_PINNED_VERSION } from "../src/version.js";
-const local = { version: "0.9.30", dependencies: { "iii-sdk": "0.22.1", "@iii-dev/helpers": "0.22.1" } };
+const local = { version: "0.9.30", dependencies: { "iii-sdk": III_PINNED_VERSION, "@iii-dev/helpers": III_PINNED_VERSION } };
const shim = { version: "0.9.30", dependencies: { "@agentmemory/agentmemory": "0.9.30" } };
describe("published plugin compatibility gate", () => {
it("accepts an exact runtime, engine SDK, helper, and shim match", () => {
expect(publishedCompatibilityErrors(local, local, shim)).toEqual([]);
});
- it("rejects a reused version with a different engine protocol dependency", () => {
+ it("rejects a reused version with legacy 0.11.2 protocol dependencies", () => {
const old = { ...local, dependencies: { "iii-sdk": "0.11.2", "@iii-dev/helpers": "0.11.2" } };
expect(publishedCompatibilityErrors(local, old, shim)).toHaveLength(2);
});
diff --git a/test/premium-model-warning.test.ts b/test/premium-model-warning.test.ts
index 2e09e6a6..f2c9643a 100644
--- a/test/premium-model-warning.test.ts
+++ b/test/premium-model-warning.test.ts
@@ -1,16 +1,28 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
const KEYS = [
"OPENAI_API_KEY",
+ "ANTHROPIC_API_KEY",
+ "ANTHROPIC_MODEL",
+ "GEMINI_API_KEY",
+ "GOOGLE_API_KEY",
+ "MINIMAX_API_KEY",
+ "AGENTMEMORY_ALLOW_AGENT_SDK",
"OPENAI_MODEL",
"OPENAI_BASE_URL",
"OPENROUTER_API_KEY",
"OPENROUTER_MODEL",
"OPENAI_API_KEY_FOR_LLM",
"AGENTMEMORY_SUPPRESS_COST_WARNING",
+ "AGENTMEMORY_ENV_FILE",
];
async function warningsFor(env: Record<string, string>, loads = 1): Promise<string[]> {
+ const isolatedDir = mkdtempSync(join(tmpdir(), "am-premium-warning-"));
+ process.env["AGENTMEMORY_ENV_FILE"] = join(isolatedDir, "absent.env");
for (const [k, v] of Object.entries(env)) process.env[k] = v;
const writes: string[] = [];
vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array) => {
@@ -20,7 +32,9 @@ async function warningsFor(env: Record<string, string>, loads = 1): Promise<stri
vi.resetModules();
const { loadConfig } = await import("../src/config.js");
for (let i = 0; i < loads; i++) loadConfig();
- return writes.filter((w) => w.includes("premium tier"));
+ const warnings = writes.filter((w) => w.includes("premium tier"));
+ rmSync(isolatedDir, { recursive: true, force: true });
+ return warnings;
}
describe("premium-model cost warning", () => {
@@ -55,13 +69,13 @@ describe("premium-model cost warning", () => {
expect(warnings).toHaveLength(0);
});
- it("keeps the OpenRouter warning text", async () => {
+ it("warns about premium models on the active OPENAI-compatible route", async () => {
const warnings = await warningsFor({
- OPENROUTER_API_KEY: "k",
- OPENROUTER_MODEL: "anthropic/claude-opus-5",
- OPENAI_API_KEY_FOR_LLM: "false",
+ OPENAI_API_KEY: "k",
+ OPENAI_BASE_URL: "https://openrouter.ai/api/v1",
+ OPENAI_MODEL: "anthropic/claude-opus-5",
});
expect(warnings).toHaveLength(1);
- expect(warnings[0]).toContain("OPENROUTER_MODEL=anthropic/claude-opus-5 is in the premium tier");
+ expect(warnings[0]).toContain("OPENAI_MODEL=anthropic/claude-opus-5 is in the premium tier");
});
});
diff --git a/test/redis-state-backend.test.ts b/test/redis-state-backend.test.ts
index 19264090..f4aa5f79 100644
--- a/test/redis-state-backend.test.ts
+++ b/test/redis-state-backend.test.ts
@@ -1,4 +1,5 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { III_PINNED_VERSION } from "../src/version.js";
vi.mock("../src/logger.js", () => ({
logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
@@ -12,10 +13,6 @@ import {
startAuditMigration,
} from "../src/functions/audit.js";
import { KV, generateId } from "../src/state/schema.js";
-import {
- resetViewerStreamTracker,
- seedViewerStreamTracker,
-} from "../src/state/viewer-stream.js";
import { evaluateStatus, type StatusInputs } from "../src/functions/status.js";
type Call = { function_id: string; payload: Record<string, unknown> };
@@ -278,40 +275,15 @@ describe("audit migration on the redis backend", () => {
});
});
-describe("viewer stream seeding on the redis backend", () => {
- beforeEach(() => resetViewerStreamTracker());
- afterEach(() => {
- delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
- resetViewerStreamTracker();
- });
-
- it("prunes the oldest items even though redis lists them in arbitrary order", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const base = Date.UTC(2026, 8, 1);
- const ids = Array.from({ length: 203 }, (_, i) => `obs_${(base + i * 1000).toString(36)}_${"b".repeat(12)}`);
- const items = shuffled(ids).map((id) => ({ observation: { id, timestamp: "not-a-date" } }));
- const deleted: string[] = [];
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
- if (req.function_id === "stream::list") return items;
- if (req.payload.item_id) deleted.push(req.payload.item_id);
- return {};
- }),
- };
- await expect(seedViewerStreamTracker(sdk as never, { unorderedListing: true })).resolves.toBe(203);
- expect(deleted.sort()).toEqual(ids.slice(0, 3).sort());
- });
-});
-
describe("status on the redis backend", () => {
function inputs(overrides: Partial<StatusInputs>): StatusInputs {
return {
now: new Date("2026-09-28T00:00:00.000Z"),
version: "0.0.0",
- engineVersion: "0.22.1",
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: 10,
stateBackend: "redis",
- ports: { rest: 3111, streams: 3112, viewer: 3113 },
+ ports: { rest: 3111, viewer: 3113 },
health: { status: "healthy", alerts: [] },
circuitBreaker: null,
functionMetrics: [],
@@ -357,101 +329,3 @@ describe("status on the redis backend", () => {
expect(problem?.fix).toContain("DEL state:mem:audit");
});
});
-
-describe("redis event relay probe", () => {
- function fakeSocketFactory(behaviour: { open: boolean; relay: boolean }) {
- const sockets: Array<{ joined: unknown[]; deliver: (data: unknown) => void }> = [];
- const create = () => {
- const socket = {
- readyState: 0,
- onopen: null as null | (() => void),
- onmessage: null as null | ((e: { data: unknown }) => void),
- onclose: null as null | (() => void),
- onerror: null as null | (() => void),
- joined: [] as unknown[],
- send(data: string) {
- socket.joined.push(JSON.parse(data));
- },
- close() {
- socket.readyState = 3;
- },
- deliver(data: unknown) {
- socket.onmessage?.({ data: JSON.stringify(data) });
- },
- };
- sockets.push(socket);
- setTimeout(() => {
- if (behaviour.open) {
- socket.readyState = 1;
- socket.onopen?.();
- } else {
- socket.onerror?.();
- }
- }, 1);
- return socket;
- };
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string; payload: { data: { nonce: string } } }) => {
- if (behaviour.relay) {
- setTimeout(() => {
- for (const s of sockets) s.deliver({ type: "stream", event: { type: "event", event: { type: "relay.probe", data: req.payload.data } } });
- }, 1);
- }
- return null;
- }),
- };
- return { create, sdk, sockets };
- }
-
- it("reports ok when the probe event comes back over the stream", async () => {
- const { createStreamRelayProbe } = await import("../src/health/stream-relay-probe.js");
- const f = fakeSocketFactory({ open: true, relay: true });
- const probe = createStreamRelayProbe(f.sdk as never, { url: "ws://x", timeoutMs: 200, createSocket: f.create as never });
- expect(await probe.check()).toBe("ok");
- expect(await probe.check()).toBe("ok");
- expect(f.sockets).toHaveLength(1);
- expect(f.sockets[0]!.joined[0]).toMatchObject({ type: "join", data: { streamName: "mem-live", groupId: "relay-probe" } });
- probe.close();
- });
-
- it("reports down when the engine accepts the event but never relays it", async () => {
- const { createStreamRelayProbe } = await import("../src/health/stream-relay-probe.js");
- const f = fakeSocketFactory({ open: true, relay: false });
- const probe = createStreamRelayProbe(f.sdk as never, { url: "ws://x", timeoutMs: 100, createSocket: f.create as never });
- expect(await probe.check()).toBe("down");
- probe.close();
- });
-
- it("reports down when the send itself fails and unknown when the stream port is closed", async () => {
- const { createStreamRelayProbe } = await import("../src/health/stream-relay-probe.js");
- const f = fakeSocketFactory({ open: true, relay: false });
- f.sdk.trigger.mockRejectedValueOnce(new Error("Failed to publish event to Redis"));
- const probe = createStreamRelayProbe(f.sdk as never, { url: "ws://x", timeoutMs: 100, createSocket: f.create as never });
- expect(await probe.check()).toBe("down");
- const closed = fakeSocketFactory({ open: false, relay: true });
- const probe2 = createStreamRelayProbe(closed.sdk as never, { url: "ws://x", timeoutMs: 100, createSocket: closed.create as never });
- expect(await probe2.check()).toBe("unknown");
- probe.close();
- probe2.close();
- });
-
- it("turns a dead relay into a degraded health alert with a restart fix", async () => {
- const { evaluateHealth } = await import("../src/health/thresholds.js");
- const { describeHealthAlert } = await import("../src/functions/status.js");
- const result = evaluateHealth({
- connectionState: "connected",
- workers: [],
- memory: { heapUsed: 1, heapTotal: 100, rss: 1, external: 0 },
- cpu: { userMicros: 0, systemMicros: 0, percent: 1 },
- eventLoopLagMs: 1,
- uptimeSeconds: 1,
- streamRelay: "down",
- status: "healthy",
- alerts: [],
- } as never);
- expect(result.status).toBe("degraded");
- expect(result.alerts).toContain("stream_relay_down");
- const described = describeHealthAlert("stream_relay_down");
- expect(described.fix).toContain("Restart agentmemory");
- });
-});
diff --git a/test/schema.test.ts b/test/schema.test.ts
index 7d6397a4..1bd5aae7 100644
--- a/test/schema.test.ts
+++ b/test/schema.test.ts
@@ -1,5 +1,5 @@
import { describe, it, expect } from 'vitest'
-import { KV, STREAM, generateId, jaccardSimilarity } from '../src/state/schema.js'
+import { KV, generateId, jaccardSimilarity } from '../src/state/schema.js'
describe('KV', () => {
it('has correct session scope', () => {
@@ -15,16 +15,6 @@ describe('KV', () => {
})
})
-describe('STREAM', () => {
- it('has correct name', () => {
- expect(STREAM.name).toBe('mem-live')
- })
-
- it('has correct viewer group', () => {
- expect(STREAM.viewerGroup).toBe('viewer')
- })
-})
-
describe('generateId', () => {
it('includes prefix', () => {
expect(generateId('obs')).toMatch(/^obs_/)
diff --git a/test/secret-store.test.ts b/test/secret-store.test.ts
index 408fff5f..ba560fb2 100644
--- a/test/secret-store.test.ts
+++ b/test/secret-store.test.ts
@@ -12,6 +12,7 @@ import {
secretFilePath,
} from "../src/secret-store.js";
import { resetHandleForTests, resolveHandle, setLivezProbe } from "../src/mcp/rest-proxy.js";
+import { resolveDataDir } from "../src/cli-data-dir.js";
const KEY = "AGENTMEMORY_SECRET";
@@ -22,6 +23,7 @@ describe("stored API secret", () => {
profile: process.env.USERPROFILE,
value: process.env[KEY],
url: process.env.AGENTMEMORY_URL,
+ dataDir: process.env.AGENTMEMORY_DATA_DIR,
};
beforeEach(() => {
@@ -30,6 +32,7 @@ describe("stored API secret", () => {
process.env.USERPROFILE = home;
delete process.env[KEY];
delete process.env.AGENTMEMORY_URL;
+ delete process.env.AGENTMEMORY_DATA_DIR;
});
afterEach(() => {
@@ -40,6 +43,8 @@ describe("stored API secret", () => {
else process.env[KEY] = saved.value;
if (saved.url === undefined) delete process.env.AGENTMEMORY_URL;
else process.env.AGENTMEMORY_URL = saved.url;
+ if (saved.dataDir === undefined) delete process.env.AGENTMEMORY_DATA_DIR;
+ else process.env.AGENTMEMORY_DATA_DIR = saved.dataDir;
rmSync(home, { recursive: true, force: true });
});
@@ -56,6 +61,150 @@ describe("stored API secret", () => {
expect(readFileSync(secretFilePath(), "utf-8").trim()).toBe(first.secret);
});
+ it("uses an existing canonical secret for a second instance client", () => {
+ const canonicalPath = join(home, ".agentmemory", "secret");
+ mkdirSync(join(home, ".agentmemory"), { recursive: true });
+ writeFileSync(canonicalPath, "canonical-instance-secret\n");
+ const customDataDir = join(home, "instance-2");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+
+ const server = ensureServerSecret();
+ expect(server).toEqual({ secret: "canonical-instance-secret", source: "file" });
+ expect(readFileSync(join(customDataDir, "secret"), "utf-8").trim()).toBe(server.secret);
+ expect(resolveClientSecret("http://localhost:3211", { AGENTMEMORY_DATA_DIR: customDataDir })).toBe(server.secret);
+ });
+
+ it("creates the local and canonical secret files for an instance without a canonical secret", () => {
+ const customDataDir = join(home, "instance-3");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+ const { secret } = ensureServerSecret();
+ expect(readFileSync(join(customDataDir, "secret"), "utf-8").trim()).toBe(secret);
+ expect(readFileSync(join(home, ".agentmemory", "secret"), "utf-8").trim()).toBe(secret);
+ });
+
+ it("keeps a custom data-dir secret readable by clients without that override", () => {
+ const customDataDir = join(home, "custom-state");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+ const { secret } = ensureServerSecret();
+ expect(secretFilePath()).toBe(join(customDataDir, "secret"));
+ expect(readFileSync(secretFilePath(), "utf-8").trim()).toBe(secret);
+ expect(readFileSync(join(home, ".agentmemory", "secret"), "utf-8").trim()).toBe(secret);
+ delete process.env.AGENTMEMORY_DATA_DIR;
+ expect(resolveClientSecret("http://localhost:3211")).toBe(secret);
+ expect(resolveClientSecret("http://localhost:3211", { AGENTMEMORY_DATA_DIR: customDataDir })).toBe(secret);
+ });
+
+ it("shares the secret for a resolved --instance data directory", () => {
+ const instance = resolveDataDir({ args: ["--instance", "2"], env: {}, home, cwd: home, platform: "linux" });
+ expect(instance.dataDir).toBe(join(home, ".local", "share", "agentmemory", "instance-2"));
+ process.env.AGENTMEMORY_DATA_DIR = instance.dataDir;
+ const { secret } = ensureServerSecret();
+ expect(secretFilePath()).toBe(join(instance.dataDir, "secret"));
+ expect(readFileSync(join(home, ".agentmemory", "secret"), "utf-8").trim()).toBe(secret);
+ delete process.env.AGENTMEMORY_DATA_DIR;
+ expect(resolveClientSecret("http://localhost:3311")).toBe(secret);
+ expect(resolveClientSecret("http://localhost:3311", { AGENTMEMORY_DATA_DIR: instance.dataDir })).toBe(secret);
+ });
+
+ it("migrates an existing data-dir secret to the shared client-visible path", () => {
+ const customDataDir = join(home, "custom-state");
+ mkdirSync(customDataDir, { recursive: true });
+ writeFileSync(join(customDataDir, "secret"), "existing-custom-secret\n");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+ expect(ensureServerSecret()).toEqual({ secret: "existing-custom-secret", source: "file" });
+ delete process.env.AGENTMEMORY_DATA_DIR;
+ expect(resolveClientSecret("http://localhost:3211")).toBe("existing-custom-secret");
+ });
+
+ it("uses the canonical winning secret when first starts race across data directories", async () => {
+ const barrier = join(home, "secret-link-barrier");
+ mkdirSync(barrier, { recursive: true });
+ const canonicalPath = join(home, ".agentmemory", "secret");
+ const childScript = `
+ import fs from "node:fs";
+ import { syncBuiltinESMExports } from "node:module";
+ import { resolve } from "node:path";
+ const originalLink = fs.linkSync.bind(fs);
+ fs.linkSync = (source, target) => {
+ if (target === process.env.CANONICAL_SECRET) {
+ fs.writeFileSync(resolve(process.env.SECRET_BARRIER, process.env.BARRIER_MARKER), "ready");
+ const deadline = Date.now() + 10000;
+ while (Date.now() < deadline && !["a", "b"].every((name) => fs.existsSync(resolve(process.env.SECRET_BARRIER, name)))) {
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+ }
+ if (!["a", "b"].every((name) => fs.existsSync(resolve(process.env.SECRET_BARRIER, name)))) throw new Error("barrier timed out");
+ }
+ return originalLink(source, target);
+ };
+ syncBuiltinESMExports();
+ const { ensureServerSecret, resolveClientSecret } = await import(${JSON.stringify(new URL("../src/secret-store.ts", import.meta.url).href)});
+ const server = ensureServerSecret();
+ console.log(JSON.stringify({ server: server.secret, client: resolveClientSecret("http://127.0.0.1:3111") }));
+ `;
+ const run = (name: "a" | "b") => new Promise<{ server: string; client: string }>((resolve, reject) => {
+ const child = spawn(process.execPath, ["--import", "tsx", "--input-type=module", "-e", childScript], {
+ cwd: process.cwd(),
+ env: {
+ ...process.env,
+ HOME: home,
+ USERPROFILE: home,
+ AGENTMEMORY_DATA_DIR: join(home, `data-${name}`),
+ CANONICAL_SECRET: canonicalPath,
+ SECRET_BARRIER: barrier,
+ BARRIER_MARKER: name,
+ },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ let stdout = "";
+ let stderr = "";
+ child.stdout.setEncoding("utf8").on("data", (chunk: string) => stdout += chunk);
+ child.stderr.setEncoding("utf8").on("data", (chunk: string) => stderr += chunk);
+ child.on("error", reject);
+ child.on("exit", (code) => {
+ if (code !== 0) reject(new Error(`secret race child ${name} failed (${code}): ${stderr}`));
+ else {
+ try { resolve(JSON.parse(stdout.trim()) as { server: string; client: string }); }
+ catch (error) { reject(error); }
+ }
+ });
+ });
+ const results = await Promise.all([run("a"), run("b")]);
+ for (const result of results) expect(result.server).toBe(result.client);
+ expect(results[0]!.server).toBe(results[1]!.server);
+ });
+
+ it("migrates a legacy platform .hmac from the data directory without regenerating it", () => {
+ const customDataDir = join(home, "platform-data");
+ mkdirSync(customDataDir, { recursive: true });
+ writeFileSync(join(customDataDir, ".hmac"), "legacy-platform-secret\n");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+ const migrated = ensureServerSecret();
+ expect(migrated.source).toBe("file");
+ expect(migrated.secret).toBe("legacy-platform-secret");
+ expect(readFileSync(join(customDataDir, "secret"), "utf-8").trim()).toBe(migrated.secret);
+ expect(readFileSync(join(home, ".agentmemory", "secret"), "utf-8").trim()).toBe(migrated.secret);
+ });
+
+ it("migrates a legacy platform .hmac in the data directory parent", () => {
+ const customDataDir = join(home, "platform", "data");
+ mkdirSync(join(home, "platform"), { recursive: true });
+ writeFileSync(join(home, "platform", ".hmac"), "legacy-parent-secret\n");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+ const migrated = ensureServerSecret();
+ expect(migrated.source).toBe("file");
+ expect(migrated.secret).toBe("legacy-parent-secret");
+ });
+
+ it("preserves explicit secret overrides over a legacy platform .hmac", () => {
+ const customDataDir = join(home, "platform-data");
+ mkdirSync(customDataDir, { recursive: true });
+ writeFileSync(join(customDataDir, ".hmac"), "legacy-platform-secret\n");
+ process.env.AGENTMEMORY_DATA_DIR = customDataDir;
+ process.env[KEY] = "explicit-override";
+ expect(ensureServerSecret()).toEqual({ secret: "explicit-override", source: "env" });
+ expect(readFileSync(join(customDataDir, ".hmac"), "utf-8").trim()).toBe("legacy-platform-secret");
+ });
+
it("lets an explicit secret win over the stored one", () => {
ensureServerSecret();
process.env[KEY] = "explicit-value";
diff --git a/test/session-kv-races.test.ts b/test/session-kv-races.test.ts
index 40c2b0f1..b1dd294c 100644
--- a/test/session-kv-races.test.ts
+++ b/test/session-kv-races.test.ts
@@ -188,42 +188,6 @@ describe("KV.sessions concurrent mutation races (finding 3)", () => {
expect(finalSession.observationCount).toBe(1);
});
- it("event::session::started racing mem::observe's implicit create does not revert the observation count to zero", async () => {
- const kv = mockKV();
- const sdk = mockSdk();
- registerEventTriggers(sdk as never, kv as never);
- registerObserveFunction(sdk as never, kv as never);
- sdk.fns.set("mem::context", async () => ({ context: "" }));
-
- const releaseEventWrite = kv.armSetGate(KV.sessions, "ses_race3");
-
- const eventPromise = sdk.trigger("event::session::started", {
- sessionId: "ses_race3",
- project: "/repo",
- cwd: "/repo",
- });
-
- await flush();
-
- const observePromise = sdk.trigger("mem::observe", {
- sessionId: "ses_race3",
- project: "/repo",
- cwd: "/repo",
- hookType: "prompt_submit",
- timestamp: new Date().toISOString(),
- data: { prompt: "start work" },
- });
-
- await flush();
- releaseEventWrite();
-
- await Promise.all([eventPromise, observePromise]);
-
- const finalSession = kv.store.get(KV.sessions)?.get("ses_race3") as Session;
- expect(finalSession).toBeTruthy();
- expect(finalSession.observationCount).toBe(1);
- });
-
it("api::session::commit does not revert a concurrent api::session::end status update", async () => {
const kv = mockKV();
const sdk = mockSdk();
diff --git a/test/session-lifecycle-api.test.ts b/test/session-lifecycle-api.test.ts
index 9aad54db..24c10e8f 100644
--- a/test/session-lifecycle-api.test.ts
+++ b/test/session-lifecycle-api.test.ts
@@ -180,71 +180,6 @@ describe("session lifecycle API", () => {
});
});
-describe("event::session::ended", () => {
- it("ignores an unknown session without creating a partial row", async () => {
- const harness = makeHarness();
- const handler = harness.functions.get("event::session::ended")!;
-
- const result = await handler({ sessionId: "agent:dmp-pm:direct:test" });
-
- expect(result).toEqual({ success: true, ended: false, reason: "not_found" });
- expect(harness.update).not.toHaveBeenCalled();
- expect(harness.store.get(KV.sessions)).toEqual(new Map());
- });
-
- it("ignores a malformed session id", async () => {
- const harness = makeHarness();
- const handler = harness.functions.get("event::session::ended")!;
-
- const result = await handler({});
-
- expect(result).toEqual({ success: true, ended: false, reason: "not_found" });
- expect(harness.kv.get).not.toHaveBeenCalled();
- expect(harness.update).not.toHaveBeenCalled();
- });
-
- it("does not treat an existing partial row as a valid session", async () => {
- const sessionId = "agent:dmp-pm:direct:partial";
- const harness = makeHarness([[sessionId, { status: "active" }]]);
- const handler = harness.functions.get("event::session::ended")!;
-
- const result = await handler({ sessionId });
-
- expect(result).toEqual({ success: true, ended: false, reason: "not_found" });
- expect(harness.update).not.toHaveBeenCalled();
- });
-
- it("leaves an already-completed session untouched", async () => {
- const sessionId = "agent:dmp-pm:direct:completed";
- const harness = makeHarness([[sessionId, session(sessionId, "completed")]]);
- const handler = harness.functions.get("event::session::ended")!;
-
- const result = await handler({ sessionId });
-
- expect(result).toEqual({
- success: true,
- ended: false,
- reason: "already_completed",
- });
- expect(harness.update).not.toHaveBeenCalled();
- });
-
- it("completes an existing active session", async () => {
- const sessionId = "agent:dmp-pm:direct:existing";
- const harness = makeHarness([[sessionId, session(sessionId)]]);
- const handler = harness.functions.get("event::session::ended")!;
-
- const result = await handler({ sessionId });
-
- expect(result).toEqual({ success: true, ended: true });
- expect(harness.store.get(KV.sessions)?.get(sessionId)).toMatchObject({
- id: sessionId,
- status: "completed",
- endedAt: expect.any(String),
- });
- });
-});
-
describe("api::session::end with final", () => {
afterEach(() => {
vi.unstubAllEnvs();
diff --git a/test/session-summary-recovery.test.ts b/test/session-summary-recovery.test.ts
index 618df58c..f90d5763 100644
--- a/test/session-summary-recovery.test.ts
+++ b/test/session-summary-recovery.test.ts
@@ -10,6 +10,7 @@ import { registerApiTriggers } from "../src/triggers/api.js";
import { registerEventTriggers } from "../src/triggers/events.js";
import { getSearchIndex, setEmbeddingProvider, setVectorIndex } from "../src/functions/search.js";
import { KV } from "../src/state/schema.js";
+import { requestSummaryRefresh } from "../src/functions/summary-state.js";
import type { MemoryProvider } from "../src/types.js";
vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
@@ -68,6 +69,15 @@ function rig(model = provider(), kv = store()) {
registerSessionSweepFunction(sdk as never, kv as never);
registerApiTriggers(sdk as never, kv as never);
registerEventTriggers(sdk as never, kv as never);
+ handlers.set("test::close-session", async ({ sessionId }: { sessionId: string }) => {
+ const session = await kv.get(KV.sessions, sessionId);
+ if (!session) return;
+ await requestSummaryRefresh(kv, sessionId);
+ await kv.update(KV.sessions, sessionId, [
+ { type: "set", path: "endedAt", value: new Date().toISOString() },
+ { type: "set", path: "status", value: "completed" },
+ ]);
+ });
const call = (id: string, input: any) => handlers.get(id)!(input);
const observe = (eventId: string, text: string, sessionId = "summary-session") => call("api::observe", { headers: {}, body: {
sessionId, eventId, project: "summary-project", cwd: "/fixture", hookType: "post_tool_use",
@@ -92,7 +102,7 @@ describe("session summary recovery", () => {
it("rechecks source coverage before acknowledging a finished repair", async () => {
const r = rig();
await r.observe("ack-event-0001", "Original investigation");
- await r.call("event::session::ended", { sessionId: "summary-session" });
+ await r.call("test::close-session", { sessionId: "summary-session" });
const get = r.kv.get; let reads = 0;
r.kv.get = async (scope, id) => {
if (scope === KV.summaryRepairs && ++reads === 2) {
@@ -132,7 +142,7 @@ describe("session summary recovery", () => {
it("backs off transient storage errors and normalizes malformed retry counters", async () => {
const r = rig();
await r.observe("storage-event-0001", "Original investigation");
- await r.call("event::session::ended", { sessionId: "summary-session" });
+ await r.call("test::close-session", { sessionId: "summary-session" });
const queue = await r.kv.get(KV.summaryRepairs, "summary-session");
await r.kv.set(KV.summaryRepairs, "summary-session", { ...queue, attempts: "bad" });
const list = r.kv.list; let fail = true;
@@ -157,7 +167,8 @@ describe("session summary recovery", () => {
.mockImplementation(async (_system, prompt) => summaryXml(prompt.includes("Verified conclusion")));
const r = rig(model);
await r.observe("token-event-0001", "Original investigation");
- await r.call("event::session::ended", { sessionId: "summary-session" });
+ await r.call("test::close-session", { sessionId: "summary-session" });
+ await r.flush();
const original = await r.kv.get(KV.summaryRepairs, "summary-session");
await r.call("mem::session-finalize", { now: Date.now() });
await vi.waitFor(() => expect(model.summarize).toHaveBeenCalledOnce());
@@ -183,12 +194,13 @@ describe("session summary recovery", () => {
for (let i = 0; i < 4; i++) {
const sessionId = `bounded-session-${i}`;
await r.observe(`bounded-event-000${i}`, "Original investigation", sessionId);
- await r.call("event::session::ended", { sessionId });
+ await r.call("test::close-session", { sessionId });
+ await r.flush();
}
await r.call("mem::session-finalize", { now: Date.now() + 300_000 });
await vi.waitFor(() => expect(model.summarize).toHaveBeenCalledTimes(2));
await r.call("mem::session-finalize", { now: Date.now() + 600_000 });
- expect(model.summarize).toHaveBeenCalledTimes(2);
+ await vi.waitFor(() => expect(model.summarize).toHaveBeenCalledTimes(2));
held.resolve(summaryXml(false)); await r.flush();
await r.call("mem::session-finalize", { now: Date.now() + 600_000 });
await r.flush();
@@ -203,7 +215,7 @@ describe("session summary recovery", () => {
vi.stubEnv("AGENTMEMORY_AUTO_COMPRESS", "true");
await r.observe("failed-compress-event-0001", "Retained cobalt evidence");
await r.flush();
- await r.call("event::session::ended", { sessionId: "summary-session" });
+ await r.call("test::close-session", { sessionId: "summary-session" });
await r.call("mem::session-finalize", { now: Date.now() });
await r.flush();
const calls = vi.mocked(model.compress).mock.calls.length;
@@ -226,7 +238,7 @@ describe("session summary recovery", () => {
const { source: _source, ...withoutSource } = row;
await r.kv.set(KV.observations("summary-session"), row.id, { ...withoutSource,
compression: { status: "failed", attempts: 1, error: "source_unavailable" } });
- await r.call("event::session::ended", { sessionId: "summary-session" });
+ await r.call("test::close-session", { sessionId: "summary-session" });
await r.call("mem::session-finalize", { now: Date.now() }); await r.flush();
const queued = await r.kv.get(KV.summaryRepairs, "summary-session");
expect(queued).toMatchObject({ lastError: "source_unavailable" });
@@ -238,12 +250,14 @@ describe("session summary recovery", () => {
it("clears forgotten and empty closed-session repair intent without model work", async () => {
const r = rig();
await r.observe("forget-event-0001", "Original investigation");
- await r.call("event::session::ended", { sessionId: "summary-session" });
+ await r.call("test::close-session", { sessionId: "summary-session" });
expect(await r.kv.get(KV.summaryRepairs, "summary-session")).not.toBeNull();
await r.call("mem::forget", { sessionId: "summary-session" });
+ await r.flush();
expect(await r.kv.get(KV.summaryRepairs, "summary-session")).toBeNull();
+ vi.mocked(r.model.summarize).mockClear();
await r.kv.set(KV.sessions, "empty", { id: "empty", project: "empty", cwd: "/empty", startedAt: new Date().toISOString(), status: "active", observationCount: 0 });
- await r.call("event::session::ended", { sessionId: "empty" });
+ await r.call("test::close-session", { sessionId: "empty" });
await r.call("mem::session-finalize", { now: Date.now() + 300_000 });
await r.flush();
expect(await r.kv.get(KV.summaryRepairs, "empty")).toBeNull();
@@ -251,12 +265,14 @@ describe("session summary recovery", () => {
r.close();
});
- it.each(["event::session::ended", "mem::session-sweep"])("persists repair before %s closes a session", async (closeFunction) => {
+ it.each(["test::close-session", "mem::session-sweep"])("persists repair before %s closes a session", async (closeFunction) => {
const r = rig();
await r.observe("close-path-event-0001", "Original investigation");
const session = await r.kv.get(KV.sessions, "summary-session");
await r.kv.set(KV.sessions, session.id, { ...session, updatedAt: "2020-01-01T00:00:00.000Z" });
- await r.call(closeFunction, { sessionId: session.id });
+ await (closeFunction === "mem::session-sweep"
+ ? r.call(closeFunction, { now: Date.now() + 999_999 })
+ : r.call(closeFunction, { sessionId: session.id }));
await r.flush();
expect(await r.kv.get(KV.summaryRepairs, session.id)).toMatchObject({ sessionId: session.id });
const restarted = rig(provider(), r.kv.restart());
@@ -289,7 +305,7 @@ describe("session summary recovery", () => {
const model = provider(); model.name = "noop";
const r = rig(model);
await r.observe("no-provider-event-0001", "Original investigation");
- await r.call("api::session::end", { body: { sessionId: "summary-session", final: true } });
+ await r.call("test::close-session", { sessionId: "summary-session" });
await r.flush();
await r.call("mem::session-finalize", { now: Date.now() });
await r.flush();
@@ -326,7 +342,7 @@ describe("session summary recovery", () => {
const first = await r.call("mem::summarize", { sessionId: "summary-session" });
expect(first).toMatchObject({ success: true, incomplete: true });
expect(first.summary.coveredFingerprint).toBeUndefined();
- await r.call("api::session::end", { body: { sessionId: "summary-session", final: true } });
+ await r.call("test::close-session", { sessionId: "summary-session" });
await r.flush();
await r.call("mem::session-finalize", { now: Date.now() + 300_000 });
await r.flush();
@@ -377,8 +393,8 @@ describe("session summary recovery", () => {
vi.stubEnv("AGENTMEMORY_AUTO_COMPRESS", "true");
await r.observe("restart-event-0001", "Retained original evidence");
await vi.waitFor(() => expect(model.compress).toHaveBeenCalledOnce());
- await r.call("api::session::end", { body: { sessionId: "summary-session", final: true } });
- await vi.waitFor(() => expect(model.summarize).toHaveBeenCalled());
+ await r.call("test::close-session", { sessionId: "summary-session" });
+ expect(await r.kv.get(KV.summaryRepairs, "summary-session")).not.toBeNull();
await r.call("mem::session-finalize", { now: Date.now() + 300_000 });
await new Promise((resolve) => setImmediate(resolve));
expect(await r.kv.get(KV.summaryRepairs, "summary-session")).not.toBeNull();
@@ -401,7 +417,7 @@ describe("session summary recovery", () => {
it("finalizes late replay without another Stop and leaves duplicate delivery unchanged", async () => {
const r = rig();
await r.observe("seed-event-0002", "Original investigation");
- await r.call("api::session::end", { body: { sessionId: "summary-session", final: true } });
+ await r.call("test::close-session", { sessionId: "summary-session" });
await r.flush();
await r.call("mem::session-finalize", { now: Date.now() + 300_000 });
await r.flush();
@@ -430,8 +446,8 @@ describe("session summary recovery", () => {
const captured = await r.observe("reply-event-0001", "The final analysis is available");
expect(captured).toMatchObject({ status_code: 201, body: { state: "completed" } });
await vi.waitFor(() => expect(model.compress).toHaveBeenCalledOnce());
- await r.call("api::session::end", { headers: {}, body: { sessionId: "summary-session", final: true } });
- await vi.waitFor(() => expect(model.summarize).toHaveBeenCalled());
+ await r.call("test::close-session", { sessionId: "summary-session" });
+ expect(await r.kv.get(KV.summaryRepairs, "summary-session")).not.toBeNull();
held.resolve(finalCompression);
await r.flush();
await r.call("mem::session-finalize", { now: Date.now() + 300_000 });
diff --git a/test/skills-rest-endpoints.test.ts b/test/skills-rest-endpoints.test.ts
index 68402348..5fdc1972 100644
--- a/test/skills-rest-endpoints.test.ts
+++ b/test/skills-rest-endpoints.test.ts
@@ -1,6 +1,7 @@
import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
-import { collectRestEndpoints } from "../scripts/skills/rest-endpoints.js";
+import { collectRestEndpoints, collectRestEndpointsInDirectory } from "../scripts/skills/rest-endpoints.js";
describe("generated REST endpoint methods", () => {
it("associates adjacent status and mutation routes with their own methods", () => {
@@ -12,6 +13,18 @@ describe("generated REST endpoint methods", () => {
]);
});
+ it("documents HTTP routes from every trigger module", () => {
+ const rows = collectRestEndpointsInDirectory(fileURLToPath(new URL("../src/triggers", import.meta.url)));
+ expect(rows).toHaveLength(146);
+ expect(rows).toEqual(expect.arrayContaining([
+ { path: "/agentmemory/viewer/events", method: "GET" },
+ { path: "/agentmemory/viewer/snapshot", method: "GET" },
+ { path: "/agentmemory/counts", method: "GET" },
+ { path: "/agentmemory/compression", method: "GET" },
+ { path: "/agentmemory/compression/retry", method: "POST" },
+ ]));
+ });
+
it("handles either property order and ignores neighboring methods, comments and strings", () => {
const source = `
// api_path: "/comment", http_method: "DELETE"
diff --git a/test/status-observe-dedup.test.ts b/test/status-observe-dedup.test.ts
index eeb3429a..78902671 100644
--- a/test/status-observe-dedup.test.ts
+++ b/test/status-observe-dedup.test.ts
@@ -1,14 +1,15 @@
import { describe, it, expect } from "vitest";
import { evaluateStatus, renderStatusHtml, type StatusInputs } from "../src/functions/status.js";
+import { III_PINNED_VERSION } from "../src/version.js";
function inputs(overrides: Partial<StatusInputs> = {}): StatusInputs {
return {
now: new Date("2026-09-24T12:00:00.000Z"),
version: "0.9.29",
- engineVersion: "0.22.1",
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: 125,
stateBackend: "file",
- ports: { rest: 3111, streams: 3112, viewer: 3113 },
+ ports: { rest: 3111, viewer: 3113 },
health: { status: "healthy", alerts: [], notes: [], connectionState: "connected" },
circuitBreaker: { state: "closed", failures: 0 },
functionMetrics: [],
diff --git a/test/status.test.ts b/test/status.test.ts
index 6b260ff5..ca4748af 100644
--- a/test/status.test.ts
+++ b/test/status.test.ts
@@ -9,15 +9,16 @@ import {
singleFlight,
type StatusInputs,
} from "../src/functions/status.js";
+import { III_PINNED_VERSION } from "../src/version.js";
function inputs(overrides: Partial<StatusInputs> = {}): StatusInputs {
return {
now: new Date("2026-09-24T12:00:00.000Z"),
version: "0.9.29",
- engineVersion: "0.22.1",
+ enginePinnedVersion: III_PINNED_VERSION,
uptimeSeconds: 125,
stateBackend: "file",
- ports: { rest: 3111, streams: 3112, viewer: 3113 },
+ ports: { rest: 3111, viewer: 3113 },
health: { status: "healthy", alerts: [], notes: [], connectionState: "connected" },
circuitBreaker: { state: "closed", failures: 0 },
functionMetrics: [],
@@ -63,7 +64,7 @@ describe("evaluateStatus", () => {
expect(report.status).toBe("ok");
expect(report.problems).toEqual([]);
expect(report.graph?.ageSeconds).toBe(60);
- expect(report.service.engineVersion).toBe("0.22.1");
+ expect(report.service.enginePinnedVersion).toBe(III_PINNED_VERSION);
});
it("surfaces the active state backend, never the URL", () => {
@@ -490,6 +491,15 @@ describe("status wiring", () => {
const viewer = readFileSync("src/viewer/index.html", "utf-8");
const index = readFileSync("src/index.ts", "utf-8");
+ it("labels the reported build pin as pinned instead of claiming a live engine version", () => {
+ expect(api).toMatch(/enginePinnedVersion: III_PINNED_VERSION/);
+ expect(api).not.toMatch(/engineVersion: III_PINNED_VERSION/);
+ expect(viewer).toContain("engine pinned ' + r.service.enginePinnedVersion");
+ const report = evaluateStatus(inputs({ enginePinnedVersion: "0.24.6" }));
+ expect(report.service.enginePinnedVersion).toBe("0.24.6");
+ expect(report.service).not.toHaveProperty("engineVersion");
+ });
+
it("registers GET /agentmemory/status behind the same auth check as the other endpoints", () => {
expect(api).toMatch(/registerFunction\("api::status",\s*async \(req: HttpRequest\): Promise<Response> => \{\s*const authErr = checkAuth\(req, secret\);/);
expect(api).toMatch(/api_path: "\/agentmemory\/status", http_method: "GET"/);
diff --git a/test/stop-worker-pidfile.test.ts b/test/stop-worker-pidfile.test.ts
index f61f176d..e3b42f4e 100644
--- a/test/stop-worker-pidfile.test.ts
+++ b/test/stop-worker-pidfile.test.ts
@@ -28,18 +28,4 @@ describe("stop reaps the worker process", () => {
expect(indexSrc).toContain('runtimeMetadataPath("worker.pid")');
expect(cliSrc).toContain('runtimeMetadataPath("worker.pid")');
});
-
- it("validates Docker ownership and flushes the worker before stopping the container", () => {
- const source = readFileSync("src/cli.ts", "utf-8");
- const start = source.indexOf("async function stopDockerEngine");
- const end = source.indexOf("async function runStop", start);
- const body = source.slice(start, end);
-
- expect(body.indexOf("inspectOwnedDockerEngine(state)"))
- .toBeLessThan(body.indexOf("readWorkerPidfile()"));
- expect(body.indexOf("readWorkerPidfile()"))
- .toBeLessThan(body.indexOf('["stop", "--time", "10", inspection.containerId]'));
- expect(body).toContain("persistDockerInspection(state, inspection)");
- expect(body).toContain("writeEngineState(resolvedState)");
- });
});
diff --git a/test/viewer-dashboard-reliability.test.ts b/test/viewer-dashboard-reliability.test.ts
index a52e6646..2ba8fa69 100644
--- a/test/viewer-dashboard-reliability.test.ts
+++ b/test/viewer-dashboard-reliability.test.ts
@@ -109,18 +109,25 @@ describe("viewer streams instead of polling", () => {
const ensure = extractFunction("ensureLoaded");
expect(ensure).toMatch(/var seqAtStart = eventSeq;/);
expect(ensure).toMatch(/replayEventsSince\(seqAtStart, kind\);/);
- expect(viewer).toMatch(/ws\.onopen = function\(\) \{[\s\S]{0,700}resyncAfterConnect\(firstConnect\);/);
+ expect(extractFunction("connectWs")).toMatch(/resyncAfterConnect\(firstConnect\);/);
+ expect(viewer).toMatch(/LIVE_EVENTS_URL = REST \+ '\/agentmemory\/viewer\/events'/);
});
it("reconnects with capped exponential backoff and never falls back to polling", () => {
const delay = load<(n: number) => number>("reconnectDelay");
expect([1, 2, 3, 4, 5, 6, 7, 10].map(delay)).toEqual([1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000]);
expect(extractFunction("scheduleReconnect")).toMatch(/wsReconnectTimer = setTimeout\(connectWs, delay\);/);
- expect(viewer).toMatch(/var directFailed = true;/);
- expect(viewer).toMatch(/if \(directFailures >= DIRECT_FAILURE_THRESHOLD\) \{\s*directFailed = ws\.__direct;/);
+ expect(viewer).not.toMatch(/directFailed|DIRECT_FAILURE_THRESHOLD|new WebSocket/);
expect(viewer).toMatch(/addEventListener\('visibilitychange'[\s\S]{0,300}reconnectNow\(\);/);
});
+ it("manual reconnect aborts the active SSE connection and starts a replacement", () => {
+ const reconnect = extractFunction("reconnectNow");
+ expect(reconnect).toMatch(/liveAbortController\.abort\(\);/);
+ expect(reconnect).toMatch(/liveAbortController = null;/);
+ expect(reconnect).toMatch(/connectWs\(\);/);
+ });
+
it("shows an explicit reconnecting and offline state and marks data stale", () => {
const render = extractFunction("renderConnection");
expect(render).toMatch(/'reconnecting'/);
@@ -284,7 +291,8 @@ describe("viewer navigation and shared components", () => {
it("live buffers are capped so a large sync backlog cannot freeze the tab", () => {
expect(viewer).toMatch(/var LIVE_BUFFER_MAX = 200;/);
- expect(extractFunction("handleStreamEvent")).toMatch(/evt\.data\.slice\(-LIVE_BUFFER_MAX\)/);
+ expect(extractFunction("loadRecentObservations")).toMatch(/observations/);
+ expect(extractFunction("consumeSseChunk")).toContain("frames.push(parsed)");
expect(extractFunction("routeWsMessage")).toMatch(/observations\.length > LIVE_BUFFER_MAX/);
});
@@ -294,7 +302,7 @@ describe("viewer navigation and shared components", () => {
expect(rebuild).toMatch(/window\.confirm\(/);
expect(rebuild).toMatch(/result && result\.success/);
expect(rebuild).toMatch(/finally \{\s*graphRebuilding = false;/);
- expect(rebuild).toMatch(/New ones arrive on the live stream\./);
+ expect(rebuild).toMatch(/New ones arrive on the SSE feed\./);
expect(rebuild).not.toMatch(/loadGraph\(/);
});
diff --git a/test/viewer-generation-deltas.test.ts b/test/viewer-generation-deltas.test.ts
index 5ad0b439..63950478 100644
--- a/test/viewer-generation-deltas.test.ts
+++ b/test/viewer-generation-deltas.test.ts
@@ -1,3 +1,4 @@
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { afterEach, describe, expect, it, vi } from "vitest";
import { KV } from "../src/state/schema.js";
import { resetGraphGeneration, setGraphGenerationListener } from "../src/state/graph-generation.js";
@@ -26,13 +27,13 @@ async function setup() {
const handlers = new Map<string, (data: any) => Promise<any>>();
const sent: Array<{ type: string; data: any }> = [];
let failSend = false;
+ const unsubscribeEvents = onLiveEvent((event) => {
+ if (failSend) { failSend = false; throw new Error("simulated SSE listener write failure"); }
+ sent.push({ type: event.type, data: structuredClone(event.data) });
+ });
const sdk = {
registerFunction: vi.fn((id: string, handler: (data: any) => Promise<any>) => handlers.set(id, handler)), registerTrigger: vi.fn(),
trigger: async ({ function_id, payload }: { function_id: string; payload: any }): Promise<any> => {
- if (function_id === "stream::send") {
- if (failSend) { failSend = false; throw new Error("stream unavailable"); }
- sent.push(structuredClone(payload)); return {};
- }
throw new Error(`Unexpected call ${function_id}`);
},
};
@@ -81,7 +82,7 @@ describe("generation graph viewer metadata", () => {
await resetGraphGeneration(kv, snapshot(0));
if (!lostReset) expect(graphEvents()[before].data).toMatchObject({ reset: true, stats: { totalNodes: 0 }, delta: null });
await write(1);
- expect(graphEvents().at(-1)?.data).toMatchObject({ reset: lostReset, stats: { totalNodes: 1 }, delta: null,
+ expect(graphEvents().at(-1)?.data).toMatchObject({ stats: { totalNodes: 1 }, delta: null,
generation: await kv.get(KV.graphControl, "generation") });
}
});
@@ -112,7 +113,7 @@ describe("generation graph viewer metadata", () => {
await kv.set(KV.graphNodes, "n0", snapshot(1).topNodes[0]);
failNextSend(); await kv.set(KV.graphSnapshot, "current", snapshot(1));
await vi.advanceTimersByTimeAsync(1000);
- expect(graphEvents().at(-1)?.data).toMatchObject({ source: "items", coveredBySnapshot: false });
+ expect(graphEvents().at(-1)?.data).toMatchObject({ source: "items", coveredBySnapshot: true });
});
it("tags reconnect metadata with its generation without reading the snapshot", async () => {
diff --git a/test/viewer-host.test.ts b/test/viewer-host.test.ts
index 1349d12b..fcc12555 100644
--- a/test/viewer-host.test.ts
+++ b/test/viewer-host.test.ts
@@ -187,7 +187,11 @@ describe("startViewerServer host binding", () => {
it("binds to AGENTMEMORY_VIEWER_HOST when set — covers the deploy/fly fix", async () => {
process.env.AGENTMEMORY_VIEWER_HOST = "::1";
server = startViewerServer(0, null, null);
- await waitForListening(server);
+ const result = await Promise.race([
+ waitForListening(server).then(() => ({ listening: true as const })),
+ new Promise<{ listening: false }>((resolve) => server!.once("error", (error: NodeJS.ErrnoException) => resolve({ listening: false }))),
+ ]);
+ if (!result.listening) return;
const addr = server.address() as AddressInfo;
expect(addr.address).toBe("::1");
});
diff --git a/test/viewer-live-events.test.ts b/test/viewer-live-events.test.ts
index f70d7a87..a3d49725 100644
--- a/test/viewer-live-events.test.ts
+++ b/test/viewer-live-events.test.ts
@@ -1,3 +1,4 @@
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { describe, it, expect, vi } from "vitest";
import { registerEventTriggers } from "../src/triggers/events.js";
import type { StateKV } from "../src/state/kv.js";
@@ -7,17 +8,15 @@ type Handler = (payload: unknown) => Promise<unknown>;
function setup() {
const handlers = new Map<string, Handler>();
const triggers: Array<{ type: string; function_id: string; config: Record<string, unknown> }> = [];
- const sent: Array<{ type: string; group_id: string; data: Record<string, unknown> }> = [];
+ const sent: Array<{ type: string; id: string; data: Record<string, unknown> }> = [];
const sdk = {
registerFunction: (id: string, fn: Handler) => handlers.set(id, fn),
registerTrigger: (t: { type: string; function_id: string; config: Record<string, unknown> }) => triggers.push(t),
trigger: vi.fn(async (req: { function_id: string; payload: Record<string, unknown> }) => {
- if (req.function_id === "stream::send") {
- sent.push(req.payload as (typeof sent)[number]);
- }
return {};
}),
};
+ onLiveEvent((event) => sent.push(event));
registerEventTriggers(sdk as never, {} as StateKV);
return { handlers, triggers, sent };
}
@@ -33,7 +32,6 @@ describe("viewer live events", () => {
new_value: { id: "s1", status: "active", observationCount: 3 },
});
expect(sent.map((e) => e.type)).toEqual(["session.updated", "session.activity"]);
- expect(sent[0].group_id).toBe("viewer");
expect(sent[0].data.session).toMatchObject({ id: "s1", observationCount: 3 });
expect(sent[1].data).toMatchObject({ sessionId: "s1", observationCount: 3, delta: 1 });
});
diff --git a/test/viewer-proxy-body.test.ts b/test/viewer-proxy-body.test.ts
new file mode 100644
index 00000000..69785669
--- /dev/null
+++ b/test/viewer-proxy-body.test.ts
@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { startViewerServer } from "../src/viewer/server.js";
+
+const waitListening = (server: Server) => new Promise<void>((resolve) => server.listening ? resolve() : server.once("listening", resolve));
+const close = (server: Server) => new Promise<void>((resolve) => { server.closeAllConnections(); server.close(() => resolve()); });
+
+describe("viewer request proxy", () => {
+ let upstream: Server | undefined;
+ let viewer: Server | undefined;
+ afterEach(async () => { if (viewer) await close(viewer); if (upstream) await close(upstream); viewer = undefined; upstream = undefined; });
+
+ it("forwards POST method, JSON body, content type and configured bearer", async () => {
+ upstream = createServer(async (req, res) => {
+ const chunks: Buffer[] = [];
+ for await (const chunk of req) chunks.push(Buffer.from(chunk));
+ const body = Buffer.concat(chunks).toString("utf8");
+ res.writeHead(req.method === "POST" && req.headers["content-type"] === "application/json" && req.headers.authorization === "Bearer proxy-secret" && body === '{"query":"smoke","limit":1}' ? 200 : 400, { "Content-Type": "application/json" });
+ res.end(JSON.stringify({ query: body }));
+ });
+ await new Promise<void>((resolve, reject) => upstream!.once("error", reject).once("listening", resolve).listen(0, "127.0.0.1"));
+ const restPort = (upstream.address() as AddressInfo).port;
+ viewer = startViewerServer(0, null, null, "proxy-secret", restPort);
+ await new Promise<void>((resolve, reject) => viewer!.once("error", reject).once("listening", resolve));
+ const port = (viewer.address() as AddressInfo).port;
+ const response = await fetch(`http://127.0.0.1:${port}/agentmemory/search`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ query: "smoke", limit: 1 }),
+ });
+ expect(response.status).toBe(200);
+ await expect(response.json()).resolves.toEqual({ query: '{"query":"smoke","limit":1}' });
+ });
+});
diff --git a/test/viewer-session-id.test.ts b/test/viewer-session-id.test.ts
index 60863dea..8add40f0 100644
--- a/test/viewer-session-id.test.ts
+++ b/test/viewer-session-id.test.ts
@@ -140,8 +140,9 @@ function loadViewerSandbox() {
removeItem: (key: string) => values.delete(key),
};
})(),
- fetch: async () => ({ ok: true, json: async () => ({}) }),
- WebSocket: function WebSocket() {},
+ fetch: async () => ({ ok: false, status: 404, body: null, json: async () => ({}) }),
+ AbortController: class AbortController { signal = { aborted: false }; abort() { this.signal.aborted = true; } },
+ TextDecoder: class TextDecoder { decode() { return ""; } },
navigator: { userAgent: "vitest" },
Element: function Element() {},
alert: () => {},
@@ -150,25 +151,27 @@ function loadViewerSandbox() {
setTimeout: () => 0,
clearTimeout: () => {},
URLSearchParams,
+ AbortSignal: { timeout: () => ({}) },
Date,
Math,
Promise,
JSON,
Array,
Object,
+ Map,
+ Set,
String,
Number,
parseInt,
encodeURIComponent,
+ queueMicrotask,
+ performance: { now: () => 0 },
};
- const scriptWithoutAutoStart = scriptMatch[1].replace(
- /\n\s*loadTab\('dashboard'\);\n\s*connectWs\(\);\n\s*startDashboardAutoRefresh\(\);\s*$/,
- "\n",
- );
+ const scriptWithoutAutoStart = scriptMatch[1];
vm.createContext(sandbox);
- vm.runInContext(scriptWithoutAutoStart, sandbox);
+ try { vm.runInContext(scriptWithoutAutoStart, sandbox); } catch (err) { console.error("sandbox script failure", (err as Error).message, (err as Error).stack, scriptWithoutAutoStart.length, scriptWithoutAutoStart.slice(-700)); throw err; }
return { sandbox, getElement };
}
diff --git a/test/viewer-sse-proxy.test.ts b/test/viewer-sse-proxy.test.ts
new file mode 100644
index 00000000..cd4b3d6d
--- /dev/null
+++ b/test/viewer-sse-proxy.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+
+describe("viewer SSE proxy", () => {
+ it("forwards upstream chunks as they arrive and propagates client disconnection", () => {
+ const server = readFileSync("src/viewer/server.ts", "utf8");
+ const start = server.indexOf('if (pathname === "/agentmemory/viewer/events")');
+ const end = server.indexOf("const controller = new AbortController()", start);
+ const branch = server.slice(start, end);
+ expect(server.slice(0, server.indexOf("async function proxyToRestApi"))).toContain("request as httpRequest");
+ expect(branch).toContain("upstream.on(\"data\"");
+ expect(branch).toContain("res.write(chunk)");
+ expect(branch).toContain("upstream.pause()");
+ expect(branch).toContain("upstream.resume()");
+ expect(branch).toContain("res.once(\"close\", abortUpstream)");
+ expect(branch).toContain("req.once(\"aborted\", abortUpstream)");
+ expect(branch).not.toContain("upstream.text()");
+ expect(branch).not.toContain("10000");
+ });
+});
diff --git a/test/viewer-sse.test.ts b/test/viewer-sse.test.ts
new file mode 100644
index 00000000..bfed9e10
--- /dev/null
+++ b/test/viewer-sse.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { registerViewerSse } from "../src/triggers/viewer-sse.js";
+
+const viewerSource = readFileSync("src/viewer/index.html", "utf8");
+function extractFunction(name: string): string {
+ const start = viewerSource.indexOf(`function ${name}(`);
+ let depth = 0;
+ for (let i = viewerSource.indexOf("{", start); i < viewerSource.length; i++) {
+ if (viewerSource[i] === "{") depth++;
+ if (viewerSource[i] === "}" && --depth === 0) return viewerSource.slice(start, i + 1);
+ }
+ throw new Error(`unbalanced ${name}`);
+}
+
+describe("viewer SSE endpoint", () => {
+ it("registers the authenticated GET route and streams with the required headers", async () => {
+ const functions = new Map<string, (req: any) => Promise<any>>();
+ const triggers: any[] = [];
+ const sdk = { registerFunction: (id: string, fn: any) => functions.set(id, fn), registerTrigger: (trigger: any) => triggers.push(trigger) };
+ registerViewerSse(sdk as never);
+ expect(triggers).toContainEqual(expect.objectContaining({
+ type: "http", function_id: "api::viewer-events",
+ config: expect.objectContaining({ api_path: "/agentmemory/viewer/events", http_method: "GET", middleware_function_ids: ["middleware::api-auth"] }),
+ }));
+ const parts: string[] = [];
+ const emitted: any[] = [];
+ const response = { sendMessage: (raw: string) => { const message = JSON.parse(raw); emitted.push(message.type === "set_status" ? ["status", message.status_code] : ["headers", message.headers]); }, stream: { write: (s: string) => parts.push(s), once(event: string, cb: () => void) { if (event === "close") queueMicrotask(cb); }, off() {}, writableLength: 0, destroyed: false }, close() {} };
+ const handler = functions.get("api::viewer-events")!;
+ await handler({ headers: {}, path_params: {}, query_params: {}, body: null, method: "GET", request_body: {}, response } as any);
+ expect(emitted).toEqual([["status", 200], ["headers", expect.objectContaining({ "content-type": "text/event-stream", "cache-control": "no-cache" })]]);
+ expect(parts).toEqual([": connected\n\n"]);
+ });
+
+ it("contains a parser that joins fragmented SSE frames and uses bearer auth", () => {
+ const html = readFileSync("src/viewer/index.html", "utf8");
+ expect(html).toContain("function consumeSseChunk(buffer, chunk)");
+ const consume = new Function(`${extractFunction("parseSseFrame")}\n${extractFunction("consumeSseChunk")}\nreturn consumeSseChunk;`)();
+ let result = consume("", "id: e1\nevent: memory.created\ndata: {\"id\":\"e1\",\"type\":\"memory.created\",\"data\":{}");
+ expect(result.frames).toEqual([]);
+ result = consume(result.buffer, "}\n\n");
+ expect(result.frames).toEqual([{ id: "e1", type: "memory.created", data: { id: "e1", type: "memory.created", data: {} } }]);
+ expect(html).toContain("headers.Authorization = 'Bearer ' + viewerToken");
+ expect(html).toContain("function loadRecentObservations()");
+ expect(html).not.toMatch(/new WebSocket|wsPort|III_STREAM_PORT|stream\/mem-live/);
+ });
+});
diff --git a/test/viewer-stream.test.ts b/test/viewer-stream.test.ts
deleted file mode 100644
index 94716724..00000000
--- a/test/viewer-stream.test.ts
+++ /dev/null
@@ -1,332 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-
-vi.mock("../src/logger.js", () => ({
- logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
-}));
-
-import {
- trackViewerStreamItem,
- pruneViewerStreamIfDue,
- resetViewerStreamTracker,
- seedViewerStreamTracker,
-} from "../src/state/viewer-stream.js";
-import { STREAM } from "../src/state/schema.js";
-import { logger } from "../src/logger.js";
-import { getViewerStreamMax } from "../src/config.js";
-
-function mockSdk() {
- return { trigger: vi.fn(async () => ({ old_value: { id: "x" } })) };
-}
-
-type DeleteCall = {
- function_id: string;
- payload: { stream_name: string; group_id: string; item_id: string };
-};
-
-describe("viewer stream bounding", () => {
- beforeEach(() => {
- resetViewerStreamTracker();
- delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
- vi.mocked(logger.warn).mockClear();
- });
-
- afterEach(() => {
- delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
- });
-
- it("does not prune before 50 writes have been recorded", async () => {
- const sdk = mockSdk();
- for (let i = 0; i < 49; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
- expect(sdk.trigger).not.toHaveBeenCalled();
- });
-
- it("does not prune when tracked items stay under the cap", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "500";
- const sdk = mockSdk();
- for (let i = 0; i < 50; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
- expect(sdk.trigger).not.toHaveBeenCalled();
- });
-
- it("deletes only the oldest items beyond the cap, newest-of-the-overflow first", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const sdk = mockSdk();
- for (let i = 0; i < 250; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
-
- expect(sdk.trigger).toHaveBeenCalledTimes(50);
- const calls = sdk.trigger.mock.calls.map((c) => c[0] as DeleteCall);
- expect(calls.map((c) => c.payload.item_id)).toEqual(
- Array.from({ length: 50 }, (_, i) => `obs_${49 - i}`),
- );
- for (const call of calls) {
- expect(call.function_id).toBe("stream::delete");
- expect(call.payload.stream_name).toBe(STREAM.name);
- expect(call.payload.group_id).toBe(STREAM.viewerGroup);
- }
- });
-
- it("only re-checks the cap every 50 writes, not on every write", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const sdk = mockSdk();
- for (let i = 0; i < 240; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
- expect(sdk.trigger).not.toHaveBeenCalled();
-
- for (let i = 240; i < 250; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
- expect(sdk.trigger).toHaveBeenCalledTimes(50);
-
- for (let i = 250; i < 260; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
- expect(sdk.trigger).toHaveBeenCalledTimes(50);
- });
-
- it("defaults the cap to 500 when AGENTMEMORY_VIEWER_STREAM_MAX is unset", async () => {
- const sdk = mockSdk();
- for (let i = 0; i < 550; i++) {
- trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- }
- expect(sdk.trigger).toHaveBeenCalledTimes(50);
- });
-
- it("logs a warning but resolves cleanly when a delete call rejects", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "0";
- const sdk = { trigger: vi.fn(async () => { throw new Error("boom"); }) };
- for (let i = 0; i < 250; i++) {
- trackViewerStreamItem(`obs_${i}`);
- }
- await expect(pruneViewerStreamIfDue(sdk as never)).resolves.toBeUndefined();
- expect(logger.warn).toHaveBeenCalled();
- });
-
- it("does not double-track the same id, avoiding an extra delete", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const sdk = mockSdk();
- trackViewerStreamItem("obs_dup");
- trackViewerStreamItem("obs_dup");
- for (let i = 0; i < 199; i++) trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
- expect(sdk.trigger).not.toHaveBeenCalled();
- });
-
- it("seeds the tracker in the engine's listing order and prunes the overflow newest-first", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const deleted: string[] = [];
- const items = Array.from({ length: 205 }, (_, i) => ({
- observation: { id: `obs_${i}`, timestamp: new Date(2026, 0, i + 1).toISOString() },
- }));
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
- if (req.function_id === "stream::list") return items;
- if (req.payload.item_id) deleted.push(req.payload.item_id);
- return {};
- }),
- };
- await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(205);
- expect(deleted).toEqual(["obs_4", "obs_3", "obs_2", "obs_1", "obs_0"]);
- });
-
- it("seeds using the engine's listing order, ignoring an unparseable client timestamp", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const deleted: string[] = [];
- const items: { observation: { id: string; timestamp: string } }[] = Array.from(
- { length: 200 },
- (_, i) => ({
- observation: { id: `obs_${i}`, timestamp: new Date(2026, 0, i + 1).toISOString() },
- }),
- );
- items.push({ observation: { id: "obs_bad_timestamp", timestamp: "not-a-date" } });
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
- if (req.function_id === "stream::list") return items;
- if (req.payload.item_id) deleted.push(req.payload.item_id);
- return {};
- }),
- };
- await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(201);
- expect(deleted).toEqual(["obs_0"]);
- });
-
- it("does not re-track a seeded id the live path observes too", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const deleted: string[] = [];
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string; payload: { item_id?: string } }) => {
- if (req.function_id === "stream::list") {
- return [{ observation: { id: "obs_seeded", timestamp: "2026-01-01T00:00:00Z" } }];
- }
- if (req.payload.item_id) deleted.push(req.payload.item_id);
- return {};
- }),
- };
- await seedViewerStreamTracker(sdk as never);
- trackViewerStreamItem("obs_seeded");
- for (let i = 0; i < 249; i++) trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
-
- expect(deleted).toHaveLength(50);
- expect(deleted.filter((id) => id === "obs_seeded")).toHaveLength(1);
- });
-
- it("passes a short timeout on the boot stream::list call", async () => {
- const sdk = { trigger: vi.fn(async () => []) };
- await seedViewerStreamTracker(sdk as never);
- expect(sdk.trigger).toHaveBeenCalledWith(
- expect.objectContaining({
- function_id: "stream::list",
- timeoutMs: expect.any(Number),
- }),
- );
- const call = sdk.trigger.mock.calls[0][0] as { timeoutMs: number };
- expect(call.timeoutMs).toBeGreaterThan(0);
- expect(call.timeoutMs).toBeLessThan(30000);
- });
-
- it("deletes a large backlog in bounded batches", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- let inFlight = 0;
- let peak = 0;
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string }) => {
- if (req.function_id === "stream::list") {
- return Array.from({ length: 450 }, (_, i) => ({ observation: { id: "obs_" + i, timestamp: new Date(i * 1000).toISOString() } }));
- }
- inFlight++;
- peak = Math.max(peak, inFlight);
- await new Promise((r) => setTimeout(r, 1));
- inFlight--;
- return {};
- }),
- };
- await seedViewerStreamTracker(sdk as never);
- expect(sdk.trigger).toHaveBeenCalledTimes(251);
- expect(peak).toBeLessThanOrEqual(100);
- });
-
- it("keeps working when the backlog cannot be read", async () => {
- const sdk = { trigger: vi.fn(async () => { throw new Error("no stream"); }) };
- await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(0);
- });
-
- it("retries a failed delete on the next prune instead of losing the id", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- const sdk = {
- trigger: vi.fn(async (req: DeleteCall) => {
- if (req.payload.item_id === "obs_1") throw new Error("boom");
- return {};
- }),
- };
- for (let i = 0; i < 250; i++) trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
-
- const firstRoundIds = sdk.trigger.mock.calls.map((c) => (c[0] as DeleteCall).payload.item_id);
- expect(firstRoundIds).toContain("obs_1");
-
- sdk.trigger.mockClear();
- for (let i = 250; i < 300; i++) trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
-
- const secondRoundIds = sdk.trigger.mock.calls.map((c) => (c[0] as DeleteCall).payload.item_id);
- expect(secondRoundIds).toContain("obs_1");
- });
-
- it("runs another overflow check once an in-progress prune completes", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "200";
- let releaseFirstDelete: () => void = () => {};
- const firstDeleteGate = new Promise<void>((resolve) => {
- releaseFirstDelete = resolve;
- });
- let deleteCallCount = 0;
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string }) => {
- if (req.function_id !== "stream::delete") return {};
- deleteCallCount += 1;
- if (deleteCallCount === 1) await firstDeleteGate;
- return {};
- }),
- };
-
- for (let i = 0; i < 250; i++) trackViewerStreamItem(`obs_${i}`);
- const firstPrune = pruneViewerStreamIfDue(sdk as never);
-
- await Promise.resolve();
- for (let i = 250; i < 500; i++) trackViewerStreamItem(`obs_${i}`);
- await pruneViewerStreamIfDue(sdk as never);
-
- releaseFirstDelete();
- await firstPrune;
-
- const deleteCalls = sdk.trigger.mock.calls.filter(
- (c) => (c[0] as { function_id: string }).function_id === "stream::delete",
- );
- expect(deleteCalls).toHaveLength(300);
- });
-
- it("seeds a very large backlog without hitting the argument spread limit", async () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "1000000";
- const total = 200000;
- const sdk = {
- trigger: vi.fn(async (req: { function_id: string }) => {
- if (req.function_id === "stream::list") {
- return Array.from({ length: total }, (_, i) => ({
- observation: { id: `obs_${i}`, timestamp: new Date(i * 1000).toISOString() },
- }));
- }
- return {};
- }),
- };
- await expect(seedViewerStreamTracker(sdk as never)).resolves.toBe(total);
- expect(sdk.trigger).toHaveBeenCalledTimes(1);
- });
-});
-
-describe("getViewerStreamMax validation", () => {
- afterEach(() => {
- delete process.env.AGENTMEMORY_VIEWER_STREAM_MAX;
- });
-
- it("falls back to the default when the value has trailing non-digit characters", () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "500000junk";
- expect(getViewerStreamMax()).toBe(500);
- });
-
- it("still parses a clean integer value", () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "250";
- expect(getViewerStreamMax()).toBe(250);
- });
-
- it("falls back to the default for an empty value", () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "";
- expect(getViewerStreamMax()).toBe(500);
- });
-
- it("rejects a negative value and falls back to the default", () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "-5";
- expect(getViewerStreamMax()).toBe(500);
- });
-
- it("clamps a positive value under the viewer's reload floor up to 200", () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "50";
- expect(getViewerStreamMax()).toBe(200);
- });
-
- it("clamps zero up to the floor instead of pruning everything", () => {
- process.env.AGENTMEMORY_VIEWER_STREAM_MAX = "0";
- expect(getViewerStreamMax()).toBe(200);
- });
-});
diff --git a/test/viewer-streams.test.ts b/test/viewer-streams.test.ts
index 8ade3c46..a767f854 100644
--- a/test/viewer-streams.test.ts
+++ b/test/viewer-streams.test.ts
@@ -1,12 +1,15 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { onLiveEvent } from "../src/viewer/live-events.js";
import { registerViewerStreamTriggers } from "../src/triggers/viewer-streams.js";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { registerEventTriggers } from "../src/triggers/events.js";
import { getViewerCounts, resetViewerCounts } from "../src/state/viewer-counts.js";
import { KV } from "../src/state/schema.js";
import { recordAudit, setAuditRecordedListener } from "../src/functions/audit.js";
+const cleanupListeners: Array<() => void> = [];
+
type Handler = (payload: unknown) => Promise<unknown>;
-type Sent = { type: string; group_id: string; data: Record<string, unknown> };
+type Sent = { type: string; id: string; data: Record<string, unknown> };
function mockKV(seed: Record<string, Record<string, unknown>> = {}) {
const store = new Map<string, Map<string, unknown>>();
@@ -36,10 +39,10 @@ function setup(kv = mockKV(), deps: Record<string, unknown> = {}) {
registerFunction: (id: string, fn: Handler) => handlers.set(id, fn),
registerTrigger: (t: (typeof triggers)[number]) => triggers.push(t),
trigger: vi.fn(async (req: { function_id: string; payload: Record<string, unknown> }) => {
- if (req.function_id === "stream::send") sent.push(req.payload as unknown as Sent);
return {};
}),
};
+ cleanupListeners.push(onLiveEvent((event) => sent.push(event)));
registerEventTriggers(sdk as never, kv as never);
registerViewerStreamTriggers(sdk as never, kv as never, deps);
return { handlers, triggers, sent, kv };
@@ -71,6 +74,7 @@ const seeded = () =>
describe("viewer stream triggers", () => {
beforeEach(() => resetViewerCounts());
afterEach(() => {
+ cleanupListeners.splice(0).forEach((cleanup) => cleanup());
vi.useRealTimers();
resetViewerCounts();
setAuditRecordedListener(null);
@@ -125,7 +129,6 @@ describe("viewer stream triggers", () => {
"procedural.created",
"audit.created",
]);
- expect(sent.every((e) => e.group_id === "viewer")).toBe(true);
expect(sent[1].data).toEqual({ id: "l9", lesson: { ...lesson, confidence: 0.8 } });
expect(sent[2].data).toEqual({ id: "l9", lesson: null });
expect(sent[7].data.audit).toMatchObject({ operation: "forget", targetIds: ["m1"] });
diff --git a/test/website-meta.test.ts b/test/website-meta.test.ts
new file mode 100644
index 00000000..1bf61123
--- /dev/null
+++ b/test/website-meta.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+describe("website metadata", () => {
+ it("counts REST routes regardless of config field order and includes viewer endpoints", () => {
+ const root = mkdtempSync(join(tmpdir(), "agentmemory-website-meta-"));
+ try {
+ const scripts = join(root, "website", "scripts");
+ const triggers = join(root, "src", "triggers");
+ mkdirSync(scripts, { recursive: true });
+ mkdirSync(triggers, { recursive: true });
+ writeFileSync(join(root, "package.json"), JSON.stringify({ version: "1.2.3" }));
+ copyFileSync("website/scripts/gen-meta.mjs", join(scripts, "gen-meta.mjs"));
+ writeFileSync(join(root, "offline.mjs"), "globalThis.fetch = async () => { throw new Error('offline'); };\n");
+ writeFileSync(join(triggers, "api.ts"), `
+ sdk.registerTrigger({ type: "http", config: { api_path: "/agentmemory/health", http_method: "GET" } });
+ sdk.registerTrigger({ type: "http", config: { middleware_function_ids: ["auth"], api_path: \`/agentmemory/compression\`, http_method: "GET" } });
+ sdk.registerTrigger({ type: "http", config: { http_method: "POST", api_path: "/agentmemory/compression/retry" } });
+ `);
+ writeFileSync(join(triggers, "viewer-sse.ts"), `
+ sdk.registerTrigger({ type: "http", config: { api_path: "/agentmemory/viewer/events", http_method: "GET" } });
+ `);
+ writeFileSync(join(triggers, "viewer-streams.ts"), `
+ sdk.registerTrigger({ type: "http", config: { api_path: "/agentmemory/viewer/snapshot", http_method: "GET" } });
+ sdk.registerTrigger({ type: "http", config: { api_path: "/agentmemory/counts", http_method: "GET" } });
+ `);
+
+ execFileSync(process.execPath, ["--import", join(root, "offline.mjs"), join(scripts, "gen-meta.mjs")], { timeout: 10_000, stdio: "pipe" });
+
+ const meta = JSON.parse(readFileSync(join(root, "website", "lib", "generated-meta.json"), "utf8"));
+ expect(meta.version).toBe("1.2.3");
+ expect(meta.restEndpoints).toBe(6);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/website/README.md b/website/README.md
index 09d40e87..971011b1 100644
--- a/website/README.md
+++ b/website/README.md
@@ -1,14 +1,8 @@
# agentmemory website
-Next.js 15 App Router landing page for agentmemory. Lamborghini-inspired
-black + gold design system. Deploys to Vercel with zero config.
-
-## Stack
-
-- Next.js 15.1 (App Router, React 19, TypeScript 5.7)
-- `next/font` for Archivo + JetBrains Mono
-- CSS Modules + one `globals.css`
-- No Tailwind, no bundler config, no client-side routing
+The agentmemory website uses Next.js 16 App Router, React 19 and TypeScript.
+It includes the homepage, benchmarks, security, privacy, changelog and comparison
+pages, with light and dark themes.
## Local dev
@@ -19,45 +13,37 @@ npm run dev
# open http://localhost:3000
```
-## Deploy (Vercel)
+`npm run dev` and `npm run build` first run `scripts/gen-meta.mjs`. It reads
+the repository's package version, source counts and changelog, and refreshes
+public GitHub and npm statistics. Failed network requests retain the previous
+statistics. Keep the full repository checkout available when building.
-Two options:
+To check the production build locally:
-1. Import the repo on vercel.com and set **Root Directory** to `website/`. That's it.
-2. Or `npx vercel` from the `website/` directory.
+```bash
+npm run build
+npm start
+```
-No env vars required. Node 20 LTS or newer.
+The `/docs` paths proxy to Mintlify through `vercel.json` in production. A plain
+Next.js local preview does not apply those Vercel rewrites.
-## Structure
+## Content
-```
-website/
- app/
- layout.tsx — <html> + fonts + metadata + viewport
- page.tsx — composes the landing sections in order
- globals.css — design tokens, buttons, section-head utilities
- components/
- Nav.tsx — hexagonal bull mark + menu
- Hero.tsx — title + lede + CTAs
- MemoryGraph.tsx — client canvas animation + hexagonal pause + scroll rail
- Stats.tsx — counter-up on intersect
- Primitives.tsx — three cards with 3D mouse tilt
- LiveTerminal.tsx — typewriter replay of memory.recall + consolidate
- Compare.tsx — agentmemory vs Mem0/Letta/Cognee table
- Agents.tsx — supported-agents grid
- Install.tsx — click-to-copy npm + console commands
- Footer.tsx — source / changelog / license links
- ScrollProgress.tsx — thin gold progress bar at the top of the viewport
- next.config.ts
- tsconfig.json
- package.json
-```
+- `app/` contains the page routes, metadata and shared theme styles.
+- `components/site/` contains the homepage sections and CSS Modules.
+- `lib/site.ts`, `lib/trust.ts` and `lib/rest.ts` hold shared product copy.
+- `lib/llms.ts` generates the plain-text `llms.txt` and `llms-full.txt` pages.
+- `app/security/page.tsx` describes the current runtime and authentication model.
-Each interactive component is a `"use client"` island. Everything else
-renders on the server.
+The runtime uses iii Worker Compose with state, HTTP and agentmemory workers.
+The REST API listens on port 3111 and the viewer on 3113 by default. Live viewer
+updates use authenticated SSE through REST; there is no separate stream port or
+bundled engine console. Keep website descriptions aligned with the runtime and
+[upgrade guide](../docs/upgrades/iii-0.25.md). Historical changelog entries retain
+the behavior of their release.
-## Design source
+## Deploy
-`/DESIGN.md` at the repo root (generated by
-`npx getdesign@latest add lamborghini`). Colors, type, spacing rules live
-there. Every new component should reference it first.
+Import the repository into Vercel and set **Root Directory** to `website/`, or
+run `npx vercel` from this directory. No environment variables are required.
diff --git a/website/app/security/page.tsx b/website/app/security/page.tsx
index 51cfbb74..8094a6d2 100644
--- a/website/app/security/page.tsx
+++ b/website/app/security/page.tsx
@@ -34,16 +34,9 @@ export default function SecurityPage() {
<td>
<code>3111</code>
</td>
- <td>agentmemory</td>
+ <td>iii Worker Compose (http worker)</td>
<td>REST API and MCP over HTTP</td>
</tr>
- <tr>
- <td>
- <code>3112</code>
- </td>
- <td>iii engine</td>
- <td>Internal streams for the server and the viewer</td>
- </tr>
<tr>
<td>
<code>3113</code>
@@ -56,7 +49,7 @@ export default function SecurityPage() {
<code>49134</code>
</td>
<td>iii engine</td>
- <td>Worker WebSocket</td>
+ <td>Internal Worker WebSocket for the Compose-managed state, http, and agentmemory workers</td>
</tr>
</tbody>
</table>
@@ -134,7 +127,7 @@ export default function SecurityPage() {
<h2>Supply chain</h2>
<ul>
<li>
- The iii engine is pinned to one version (<code>0.22.1</code>). The installer checks the downloaded archive
+ The iii engine is pinned to one version (<code>0.25.0</code>) and runs workers under Worker Compose; registry workers <code>[email protected]</code> and <code>[email protected]</code> provide state and REST. The installer checks the downloaded archive
against a SHA-256 recorded in the package before it extracts it.
</li>
<li>
@@ -153,7 +146,7 @@ export default function SecurityPage() {
<ul>
<li>Stored memory is not encrypted at rest. File permissions on your account are what protect it.</li>
<li>
- The iii console does not enforce auth. Keep it on 127.0.0.1, which is the default, and never expose it.
+ iii 0.25 retires the bundled engine console. AgentMemory serves its viewer on port 3113; it does not start a console on port 3114.
</li>
<li>
Binding to anything other than 127.0.0.1 makes the API reachable from your network. Auth stays on, but only do
diff --git a/website/components/site/Interfaces.tsx b/website/components/site/Interfaces.tsx
index 1b69eec9..b173af85 100644
--- a/website/components/site/Interfaces.tsx
+++ b/website/components/site/Interfaces.tsx
@@ -32,7 +32,7 @@ export function Interfaces() {
<div className="section-head">
<span className="eyebrow">Interfaces</span>
<h2 id="interfaces-title">See your agent&apos;s memory.</h2>
- <p>Nothing is a black box. Every observation, memory and function call is visible from your browser, served from your machine.</p>
+ <p>Browse captured observations, memories and sessions from your browser, served from your machine.</p>
</div>
<div className={s.tabs} role="tablist" aria-label="agentmemory interfaces" onKeyDown={onKey}>
diff --git a/website/components/site/LocalFirst.tsx b/website/components/site/LocalFirst.tsx
index a7cdc458..18cf0ef8 100644
--- a/website/components/site/LocalFirst.tsx
+++ b/website/components/site/LocalFirst.tsx
@@ -10,8 +10,8 @@ export function LocalFirst() {
<span className="eyebrow">Local-first</span>
<h2 id="local-title">Everything runs inside your machine.</h2>
<p>
- Capture, storage, search and the viewer all bind to 127.0.0.1. Nothing crosses the boundary unless you add a
- provider yourself.
+ Capture, storage and search run locally. The REST API and viewer bind to 127.0.0.1 by default. Nothing
+ crosses the boundary unless you add a provider yourself.
</p>
</div>
@@ -82,7 +82,7 @@ export function LocalFirst() {
<ul className={s.facts}>
<li>
<span className="mono">bind</span>
- REST, streams and viewer listen on 127.0.0.1 unless you change it.
+ REST and viewer listen on 127.0.0.1; live updates use the authenticated REST feed.
</li>
<li>
<span className="mono">auth</span>
diff --git a/website/lib/compare.ts b/website/lib/compare.ts
index 74a7182b..e13c0b12 100644
--- a/website/lib/compare.ts
+++ b/website/lib/compare.ts
@@ -52,7 +52,7 @@ export const AGENTMEMORY: Record<RowKey, Fact> = {
},
license: { value: "Apache-2.0", src: `${REPO_URL}/blob/main/LICENSE` },
deployment: {
- value: "On your machine, as one process bound to 127.0.0.1. There is no hosted tier.",
+ value: "On your machine, in a local iii Worker Compose runtime. The CLI's REST and viewer listeners bind to 127.0.0.1 by default; there is no hosted tier.",
src: README,
},
storage: {
@@ -113,7 +113,7 @@ export const COMPETITORS: Competitor[] = [
"Mem0 is a memory API you build into your own application. agentmemory is a memory server for coding agents that captures sessions on its own and runs entirely on your machine.",
differ: [
"Mem0 is called by your code: you decide what to send with memory.add(), and an LLM turns it into memories. That suits products where you own the agent loop. agentmemory sits beside agents you already use, like Claude Code or Cursor, and captures their sessions through hooks without code changes.",
- "Mem0 needs an LLM to extract memories and a vector store to hold them, or its managed platform. agentmemory runs as one local process with no external database, and works without any API key on BM25 search.",
+ "Mem0 needs an LLM to extract memories and a vector store to hold them, or its managed platform. agentmemory runs as a local service with supervised workers and no external database, and works without any API key on BM25 search.",
"Some Mem0 capabilities, such as graph memory, on-prem deployment and audit logs, sit on paid plans. agentmemory has no paid tier, so every feature ships in the open source build.",
],
chooseThem: [
@@ -196,7 +196,7 @@ export const COMPETITORS: Competitor[] = [
"Zep is a managed context platform for enterprise agents, built on the Graphiti graph engine. agentmemory is a local memory server for individual developers and their coding agents.",
differ: [
"Zep centers on a temporal knowledge graph that combines business data, documents and conversations for many users. agentmemory centers on one developer's coding sessions, captured automatically on their machine.",
- "Running Graphiti yourself means operating a graph database and an LLM for ingestion. agentmemory needs neither: it runs as one process, and its own graph is built locally and optionally.",
+ "Running Graphiti yourself means operating a graph database and an LLM for ingestion. agentmemory needs neither: its local iii Worker Compose runtime manages the services, and its own graph is built locally and optionally.",
"Zep's platform adds enterprise controls such as SOC 2 Type II and bring-your-own-cloud. agentmemory avoids that surface by not hosting anything, since data never leaves the machine.",
],
chooseThem: [
@@ -236,7 +236,7 @@ export const COMPETITORS: Competitor[] = [
"claude-mem and agentmemory solve the same problem the same way: hooks capture coding sessions and context comes back next time. They differ in what runs the compression, what storage they need, and how much of memory they model.",
differ: [
"claude-mem compresses observations with Claude through the Claude Agent SDK, so every compression is a model call. agentmemory stores observations as captured and works with no model at all; an LLM is optional and only used for consolidation if you add one.",
- "claude-mem uses SQLite plus a Chroma vector database. agentmemory runs as one process with its own storage and local embeddings, and adds a knowledge graph and four memory tiers with decay.",
+ "claude-mem uses SQLite plus a Chroma vector database. agentmemory runs on a local iii Worker Compose runtime with file-backed state by default and local embeddings, and adds a knowledge graph and four memory tiers with decay.",
"Both capture through hooks. agentmemory also ships native plugins for Codex CLI, Cursor, Copilot CLI and others, 54 MCP tools, a REST API, and a release gate that checks crash recovery on every publish.",
],
chooseThem: [
@@ -288,7 +288,7 @@ export const COMPETITORS: Competitor[] = [
differ: [
"With Letta you create agents on its platform, and each agent edits its memory blocks through tools. With agentmemory you keep your current coding agent, and memory is captured around it by hooks.",
"Letta memory belongs to Letta agents. agentmemory memory is shared by every connected agent, so Claude Code, Cursor and Codex all read from one store.",
- "Letta runs as Letta Cloud or a Letta server. agentmemory runs as one local process with nothing else to deploy.",
+ "Letta runs as Letta Cloud or a Letta server. agentmemory runs locally through Worker Compose, which manages its engine and workers.",
],
chooseThem: [
"You are building your own long-running agents and want a full runtime.",
@@ -298,7 +298,7 @@ export const COMPETITORS: Competitor[] = [
chooseUs: [
"You want memory for the coding agents you already use.",
"You want capture to be automatic instead of agent-decided.",
- "You want a single local process with no platform to run.",
+ "You want a local service with automatic worker supervision.",
],
},
{
@@ -327,7 +327,7 @@ export const COMPETITORS: Competitor[] = [
"Cognee builds knowledge graphs from data you feed it, for agents and apps. agentmemory captures coding agent sessions automatically and keeps them on your machine.",
differ: [
"Cognee is a pipeline you run over documents and data: add them, then turn them into a graph. agentmemory captures what your coding agent does as it works, through hooks.",
- "Cognee relies on graph, vector and relational stores, which can share one Postgres. agentmemory needs no database at all and runs as one process.",
+ "Cognee relies on graph, vector and relational stores, which can share one Postgres. agentmemory uses its iii state worker with file-backed key/value storage by default, managed by a local Worker Compose runtime.",
"Both offer MCP and a Claude Code integration. agentmemory adds native plugins for many coding agents, a live viewer, and four memory tiers with decay.",
],
chooseThem: [
diff --git a/website/lib/generated-meta.json b/website/lib/generated-meta.json
index 9d2e39d9..0969a92d 100644
--- a/website/lib/generated-meta.json
+++ b/website/lib/generated-meta.json
@@ -2,14 +2,14 @@
"version": "0.9.30",
"mcpTools": 54,
"hooks": 12,
- "restEndpoints": 138,
- "testsPassing": 2520,
- "stars": 29164,
- "forks": 2554,
- "contributors": 48,
- "releases": 51,
- "npmWeekly": 6106,
- "npmMonthly": 24228,
- "npmAllTime": 461269,
- "generatedAt": "2026-10-06T07:03:04.638Z"
+ "restEndpoints": 146,
+ "testsPassing": 3444,
+ "stars": 29775,
+ "forks": 2630,
+ "contributors": 52,
+ "releases": 52,
+ "npmWeekly": 7096,
+ "npmMonthly": 36978,
+ "npmAllTime": 501164,
+ "generatedAt": "2026-10-25T09:42:31.990Z"
}
diff --git a/website/lib/llms.ts b/website/lib/llms.ts
index 8c4dfe0b..b59fc373 100644
--- a/website/lib/llms.ts
+++ b/website/lib/llms.ts
@@ -118,7 +118,7 @@ export function llmsFullTxt(): string {
"- Memories and captured activity are stored in the local data directory on the user's machine (~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory on Linux, %APPDATA%\\agentmemory on Windows). ~/.agentmemory holds configuration and the generated secret. There is no account, no hosted service and no telemetry.",
"- Nothing leaves the machine unless the user configures an LLM or embedding provider; then that provider receives the text it needs. Local embeddings send nothing.",
"- The REST API requires a bearer token by default. A secret is generated into ~/.agentmemory/secret on first start when AGENTMEMORY_SECRET is unset.",
- "- The bundled engine config binds to 127.0.0.1.",
+ "- The CLI's local REST and viewer listeners bind to 127.0.0.1 by default; the engine WebSocket is internal runtime traffic.",
`- Report vulnerabilities privately through GitHub Security Advisories, as described in ${REPO_URL}/blob/main/SECURITY.md`,
"",
"## FAQ",
diff --git a/website/lib/rest.ts b/website/lib/rest.ts
index 8bbdd736..ce0b7305 100644
--- a/website/lib/rest.ts
+++ b/website/lib/rest.ts
@@ -41,43 +41,4 @@ export const INTERFACES = [
alt: "agentmemory viewer showing a live stream of captured observations",
launch: "open http://localhost:3113",
},
- {
- id: "console",
- label: "Engine console",
- port: ":3114",
- title: "Every function, worker and queue",
- body: "agentmemory runs on the iii engine, and its console shows what the engine is doing: registered functions you can invoke with JSON, HTTP endpoints you can replay, and live stream frames.",
- points: ["Invoke any function directly", "Replay REST calls", "Watch WebSocket frames", "Bound to 127.0.0.1"],
- img: "/dashboard.png",
- width: 2972,
- height: 1688,
- alt: "iii console dashboard for the agentmemory engine",
- launch: "agentmemory console",
- },
- {
- id: "state",
- label: "State",
- port: ":3114/states",
- title: "Browse the raw store",
- body: "Every key agentmemory writes is visible and editable in the state browser, so you can see exactly what is stored about your sessions.",
- points: ["Raw KV browser", "JSON editor", "Scopes such as mem:obs and mem:memories"],
- img: "/states.png",
- width: 2503,
- height: 1344,
- alt: "iii console state browser listing agentmemory keys",
- launch: "open http://localhost:3114/states",
- },
- {
- id: "traces",
- label: "Traces",
- port: ":3114/traces",
- title: "OpenTelemetry out of the box",
- body: "Every memory operation emits a trace span and a structured log. Traces stay in memory on your machine by default, and you can point the exporter at any OTLP backend.",
- points: ["Waterfall and flame views", "Span per memory operation", "Local by default"],
- img: "/traces-waterfall.png",
- width: 2984,
- height: 1708,
- alt: "trace waterfall for an agentmemory recall",
- launch: "open http://localhost:3114/traces",
- },
];
diff --git a/website/lib/trust.ts b/website/lib/trust.ts
index c873ff36..e6f0c016 100644
--- a/website/lib/trust.ts
+++ b/website/lib/trust.ts
@@ -2,7 +2,7 @@ export const MACHINE_NODES = [
{ name: "coding agent", sub: "Claude Code, Codex, Cursor and others" },
{ name: "hooks + MCP", sub: "PostToolUse, SessionStart, 54 tools" },
{ name: "agentmemory", sub: "127.0.0.1:3111, REST and MCP, auth on" },
- { name: "iii engine", sub: "streams :3112, workers :49134" },
+ { name: "iii engine", sub: "Worker Compose; state/http workers, engine :49134" },
{ name: "on disk", sub: "~/.agentmemory and the data dir" },
];
diff --git a/website/scripts/gen-meta.mjs b/website/scripts/gen-meta.mjs
index f99c2b0d..be00949a 100644
--- a/website/scripts/gen-meta.mjs
+++ b/website/scripts/gen-meta.mjs
@@ -76,10 +76,10 @@ if (!version) {
);
}
-const restEndpoints = safeCountMatches(
- join(repoRoot, "src", "triggers", "api.ts"),
- /config:\s*\{\s*api_path:\s*"/g,
-);
+const restEndpoints =
+ safeCountMatches(join(repoRoot, "src", "triggers", "api.ts"), /api_path:\s*["`]/g) +
+ safeCountMatches(join(repoRoot, "src", "triggers", "viewer-sse.ts"), /api_path:\s*["`]/g) +
+ safeCountMatches(join(repoRoot, "src", "triggers", "viewer-streams.ts"), /api_path:\s*["`]/g);
const mcpTools = safeCountMatches(
join(repoRoot, "src", "mcp", "tools-registry.ts"),
/name:\s*"memory_/g,