Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -180,12 +180,12 @@
# 8. iii engine pin
# -----------------------------------------------------------------------------
#
# agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
# new sandbox-everything-via-`iii worker add` model that agentmemory
# hasn't been refactored for yet. Override with AGENTMEMORY_III_VERSION
# only after migrating to the sandbox model manually.
# agentmemory pins iii-engine to the same release as its iii-sdk dependency
# (v0.19.7). 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.11.2
# AGENTMEMORY_III_VERSION=0.19.7

# -----------------------------------------------------------------------------
# 9. Claude Code bridge (opt-in)
Expand Down
2 changes: 2 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ updates:
commit-message:
prefix: deps
include: scope
ignore:
- dependency-name: iii-sdk
groups:
minor-and-patch:
update-types:
Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,20 @@ All notable changes to agentmemory will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Changed

- **iii engine and `iii-sdk` move from 0.11.2 to 0.19.7.** Same release on both sides, as before; the CLI downloads the pinned engine into `~/.agentmemory/bin`, the bundled `docker-compose.yml` pulls `iiidev/iii:0.19.7`, and `agentmemory upgrade` pins the SDK to the version this package was built against. The deploy templates under `deploy/` install the published npm package, so their engine pair moves together with `AGENTMEMORY_VERSION` at release time. 0.19.7 is the last engine before the 0.20 SDK reorganization and carries the upstream fix that keeps HTTP routes owned by the reconnecting worker, so `/agentmemory/*` no longer answers 404 after the engine reconnects (#1013). Existing state stores load unchanged.
- **Runtime config is re-seeded on every start.** Engines from 0.19.4 on persist each builtin worker's `config:` block into `data/configuration/<worker>.yaml` on first boot and treat that copy as the source of truth afterwards, which would have made `--port`, `--instance` and data-dir changes silently ineffective after the first run. The CLI now clears those persisted builtin entries right before it spawns the engine, so the runtime config it renders from your environment is the seed every time. If one of them cannot be removed, `agentmemory start` stops with the path instead of launching an engine that would ignore the requested ports. The bundled `docker-compose.yml` keeps the same directory on a tmpfs so container starts behave the same way.
- Dependabot no longer proposes `iii-sdk` bumps; the engine pin and the SDK version are updated together by hand.
- The deploy Dockerfiles (`deploy/fly`, `railway`, `render`, `coolify`) refuse to build when `III_VERSION` and `III_SDK_VERSION` differ, so overriding the engine tag alone can no longer produce a worker that speaks the wrong wire protocol.

### Fixed

- **The search index snapshot is written continuously, not only on clean shutdown.** Every observation, compression result and memory save now schedules the debounced snapshot write, and bulk indexing (import, replay, rebuild) does the same. Before, the BM25/vector snapshot was written only by a graceful shutdown; after a crash, `kill -9` or power loss the worker booted the stale snapshot, skipped the rebuild because the snapshot was not empty, and every observation captured since the last clean stop stayed invisible to search for good. On boot the worker now also compares the loaded snapshot against each session's observation count and re-indexes whatever is missing. Re-adding an observation under an id that is already indexed (compression replacing the synthetic entry) now replaces the index document instead of stacking postings on top of the old ones.
- **Worker shutdown no longer hangs when the engine is already gone.** The SIGTERM handler waited on a state write that can never land while the SDK is reconnecting, so `agentmemory stop` had to SIGKILL an orphaned worker after its grace period. The final index flush and the SDK shutdown are now time-boxed at 4 s each, with a hard exit at 8 s, and open viewer connections are closed instead of awaited. `agentmemory stop` gives an orphaned worker that full budget before escalating to SIGKILL.

## [0.9.29] — 2026-08-16

Release wave in two parts. Recall quality: hybrid ranking reaches the primary recall path, lessons get a real index, every record learns where it came from, the knowledge graph populates keyless, and agent scoping threads through all save paths — plus connector parity for pi and Codex, a new DeepSeek Harness connector, current provider model defaults, and a viewer clarity pass. Foundation: the `.env` file now applies everywhere, imports become searchable, consolidation runs on session stop, twelve MCP-only agents get activated on connect, and every capture surface agrees on what "project" means. No breaking changes; read the upgrade notes for behavior changes you will notice.
Expand Down
16 changes: 8 additions & 8 deletions INSTALL_FOR_AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ 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.11.2 binary under `~/.agentmemory/bin` on macOS/Linux or `%USERPROFILE%\.agentmemory\bin` on Windows.
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.19.7 binary under `~/.agentmemory/bin` on macOS/Linux or `%USERPROFILE%\.agentmemory\bin` on Windows.

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.

Expand All @@ -14,7 +14,7 @@ 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.11.2 `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.
- Windows: WSL2 follows the Linux path above. Native Windows requires a manually downloaded, pinned iii-engine v0.19.7 `iii.exe`, or Docker Desktop; the CLI does not auto-extract the Windows ZIP. Native automated `connect` supports only `copilot-cli`. Other Windows agents need manual MCP configuration; WSL `connect` applies only to agents installed in that same WSL environment.
- Ports 3111 (REST), 3112 (streams), 3113 (viewer), and 49134 (engine) free. If any are taken, stop whatever is using them before starting (see Troubleshooting).

## Running non-interactively
Expand All @@ -38,12 +38,12 @@ 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.11.2
# https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.19.7
# Extract iii.exe to $HOME\.agentmemory\bin\iii.exe, then verify the pin:
& "$HOME\.agentmemory\bin\iii.exe" --version
```

Expect: exactly `0.11.2`. 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.19.7`. Do not install the latest unpinned iii release. Alternatively, use WSL2 or start Docker Desktop and choose the Docker path when agentmemory starts.

## 2. Start the server

Expand All @@ -61,7 +61,7 @@ npx -y @agentmemory/agentmemory@latest --data-dir /absolute/path/to/agentmemory-

Docker bind-mounts that same resolved host directory at `/data`. For a second isolated daemon, add `--instance 1`; it stores data and lifecycle metadata under `instance-1` and defaults to ports 3211, 3212, 3213, and 49234. Do not use `--port` alone for concurrent daemons: it changes the ports but keeps instance 0's canonical lifecycle ownership. Use `--instance` for isolation.

Expect: iii-engine v0.11.2 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-engine v0.19.7 starts, the agentmemory worker registers with iii, and the ready panel lists REST, viewer, streams, and engine addresses. First boot can take longer while the engine binary is downloaded.

## 3. Validate the server and all four ports

Expand Down Expand Up @@ -202,17 +202,17 @@ The MCP server exposes 54 tools by default (`--tools all`). Use `--tools core` (
- 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.11.2 binary does not replace a user-managed `iii` on `PATH`.
- "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.19.7 binary does not replace a user-managed `iii` on `PATH`.
- Only 7 tools visible in the agent: the MCP shim is in local fallback because it could not reach a server. Start `npx -y @agentmemory/agentmemory@latest`, ensure `AGENTMEMORY_URL` points at it (default `http://localhost:3111`), then reload MCP.
- Native Windows: the CLI does not auto-extract the ZIP. Install the pinned v0.11.2 `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: the CLI does not auto-extract the ZIP. Install the pinned v0.19.7 `iii.exe` manually, use WSL2, or run with Docker Desktop and `AGENTMEMORY_USE_DOCKER=1`. Automated `connect` supports only `copilot-cli`; configure other native agents manually.
- Semantic demo query returns zero hits: this is expected with vectors disabled in default keyless mode. Set `EMBEDDING_PROVIDER=local`, restart, allow the first model download to complete, and rerun the demo.

## Report success

Report back to the user:

- agentmemory installed, version, and the server running on port 3111
- iii-engine v0.11.2 running, the selected platform data directory, and all four ports accounted for
- iii-engine v0.19.7 running, the selected platform data directory, and all four ports accounted for
- which agent was wired via `agentmemory connect`, and the tool count the agent now sees
- the save and recall round-trip returned the probe memory after a full stop/start
- the viewer is available at `http://localhost:3113`
Expand Down
Loading
Loading