Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

Merge remote-tracking branch 'origin/main' into merge/2.6.7-into-3.0

AkitaOnRailsd841ee1017d1
diff --cc CHANGELOG.md
index 02ce1eaf,efbd8bbc..5c3060f3
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -11,620 -11,35 +11,632 @@@ and [0.x](docs/changelog/0.x.md)
## [Unreleased]
+### Added
+- Added backlinks, outgoing links and an outline to the web page view. A page
+ in `/web` now has a side column (below the text on narrow screens) with "On
+ this page", the h2 and h3 headings linked to their anchors (shown from two
+ headings up); "Cited by", the pages that link to it, with an empty state;
+ and "Cites", the pages it links to. Each group lists ten pages and then "and
+ N more", and a page in another project carries its `workspace/project`. A
+ link from a project the viewer cannot read is left out, as in the
+ `/api/v1` page response. (#1246)
+- Added ai-memory as a marketplace plugin for Claude Code and Codex. The
+ repository is now a plugin marketplace: `claude plugin marketplace add
+ akitaonrails/ai-memory` then `claude plugin install ai-memory@ai-memory`,
+ or `codex plugin marketplace add akitaonrails/ai-memory` then `codex plugin
+ add ai-memory@ai-memory` (Codex runs the hooks only after you trust them in
+ `/hooks`; trust survives plugin upgrades). Each plugin carries the
+ lifecycle hooks, the MCP tools through `ai-memory mcp-bridge`, the routing
+ skills and a `status` skill that runs `ai-memory doctor`. The hooks call
+ one short POSIX launcher that hands every event to the installed binary's
+ native `ai-memory hook`, so `ignore_paths`, allowlist mode, marker scope
+ and server profiles apply exactly as for `install-hooks`; without the
+ binary the plugin captures nothing, says so once at session start and
+ never blocks the agent. The binary is still installed separately. Catalogs
+ pin each plugin to the release tag, and `plugins/` is generated by the
+ hidden `ai-memory render-plugins`, with a test that fails when the
+ committed files drift from it. When Claude settings-file hooks and the
+ plugin are both installed, the settings hooks win and the plugin skips the
+ events they deliver, but only a settings hook with a catch-all matcher
+ (empty, `*` or absent) counts; sessions with no project folder are not
+ captured through the plugin. Droid running the Claude Code plugin gets the
+ same treatment: the plugin skips folderless sessions and the events
+ `install-hooks --agent droid` already delivers. The Claude Code hooks start
+ the launcher with `sh`, a relative `ai_memory_bin` option is ignored, and
+ the plugin trees and every `*.sh` are pinned to LF line endings. With no
+ server URL set, the launcher omits `--server-url`; a binary older than 3.0
+ rejects that, so the launcher retries it once against
+ `http://127.0.0.1:49374` and prints an upgrade hint. The plugins need
+ ai-memory 3.0 or later. On Windows, Codex calls `ai-memory hook` directly
+ without the launcher, so folderless sessions are captured there and a
+ missing binary goes unreported; `docs/install.md` records this. `setup` and `ai-memory run` no longer write settings
+ hooks, MCP entries or skills for an agent whose plugin is enabled;
+ `doctor` reports each plugin, version skew, double wiring and Codex plugin
+ hooks Codex skips; `upgrade` also updates the Claude Code plugin;
+ `uninstall` removes the plugins. `ai-memory hook --server-url` and
+ `ai-memory mcp-bridge --server-url` now treat an empty value as unset and
+ use the configured server, and `hook --server-url` may be omitted. Each
+ release attaches `ai-memory-claude-plugin.zip` for the Claude desktop app's
+ plugin upload. See `docs/install.md#marketplace-plugins`. (#1166)
+- Added a recall trace to web search. A project page has its own search box,
+ and a search with `workspace` and `project`
+ (`/web/search?q=…&workspace=…&project=…`) now ranks with the same hybrid
+ ranker as `memory_query` for that project: FTS5, entity, vector, graph and
+ observation streams, the authority adjustment, and the reranker when one is
+ configured. The server now hands its configured embedder and reranker to the
+ web UI, and the reranker's four-call concurrency limit is shared with
+ `memory_query`. With "Explain ranking" (`explain=1`) each hit shows its rank,
+ raw score and RRF contribution in every stream, the fused score, the
+ authority multiplier, and the intent boost and rerank score when present;
+ the page also lists the streams that ran, the embedder and reranker in use,
+ and each stream's time in milliseconds. A web search without a scope is
+ still the cross-project FTS5 search, as `memory_query(global=true)` is.
+ Project search follows the per-project read rule: a viewer without a
+ grant on a restricted project gets a 403 and no trace, and an unknown project
+ is a 404.
+- Added a root-only server health page at `/web/health`, linked from the web UI
+ header. It shows the hook counters since the server started (accepted, shed
+ with 429 by saturation or rate limit, stored, failed, dropped), the writer
+ queue depth, the hook spool and recovery journal in the server's data
+ directory, the consolidation queue (last completion, pending, running,
+ completed and failed jobs), the configured embedder, both providers' status
+ and the stored vector identities. Failing checks are listed with the command
+ that fixes them, the same lines `ai-memory status` prints: `ai-memory
+ recover` for a backed-up spool or journal, `ai-memory compact --confirm` for
+ reclaimable space, `ai-memory embed` for pages without vectors, `ai-memory
+ embed --force` for vectors made under another model, and the LLM provider's
+ retry command. The page is read-only and is gated like `/web/pending`: on a
+ multi-user server anonymous requests get a 401 and database users a 403. It
+ never shows provider error text, page content or project names.
+- Added a two-command native install for Linux and macOS:
+ `curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh`,
+ then `ai-memory setup`. `install.sh` is a new release asset with its own
+ `install.sh.sha256`. It downloads the release tarball for the machine, checks
+ it against the published `.sha256` file and refuses to install when that file
+ is missing, names another asset or does not match, or when the archive holds
+ an absolute or `..` path or a symlink or hard-link member. Its `wget`
+ fallback for the default GitHub URL runs only with `--https-only` and
+ refuses a `wget` that lacks the flag. It unpacks under
+ `~/.local/lib/ai-memory` without restoring file ownership, links
+ `~/.local/bin/ai-memory`, needs no root, leaves an existing non-link
+ `ai-memory` (such as the Docker wrapper) alone, and runs nothing when the
+ download is cut short. The new `ai-memory setup [--yes] [--agent <name>]...
+ [--no-service]` runs `init` (a fresh data dir gets the root bearer token),
+ installs and starts a per-user service rendered from the packaged systemd
+ user unit or launchd LaunchAgent with this install's binary, data dir and
+ config, wires MCP, hooks and global Agent Skills for each named or detected
+ agent, and ends with a read-only check of `/healthz`, `memory_status` and
+ `doctor`. The unit names a stable path to the binary (the invoked path, an
+ `ai-memory` on `PATH`, or Homebrew's `opt/bin` link) when the resolved
+ binary sits in a versioned Homebrew Cellar or `/nix/store` path, so the
+ service survives an upgrade or garbage collection. It shows the plan and
+ asks first; without a terminal it changes nothing unless given `--yes`. A
+ second run changes nothing. Windows has no service step. `ai-memory
+ uninstall --apply` stops and removes that service, but only a unit `setup`
+ wrote and nobody edited since; any other unit at that path is left alone
+ and reported. With `--purge-data`, uninstall refuses a live ai-memory
+ process before it stops the service. `INSTALL_FOR_AGENTS.md` tells an AI agent how to install
+ ai-memory for its user, and `scripts/onboarding-acceptance.sh` measures the
+ path from a clean home to the first returned memory.
+- Added page history and session replay to the read-only web UI. Each page
+ links to its history (`/web/w/<ws>/<proj>/h/<path>`): every stored version,
+ newest first, superseded ones included, so a version a concurrent write
+ replaced stays visible, with timestamps and the author of attributed writes,
+ plus a server-side unified diff between any two versions (by default the
+ latest against the version it replaced). Expired versions are hidden, and a
+ page whose TTL has passed shows no history. The same data is available as JSON
+ at `GET /api/v1/workspaces/{ws}/projects/{proj}/history/{*path}`. The version
+ list is capped at 200 per request, and the diff refuses inputs over 512 KiB,
+ 10,000 lines or 1,000 changed lines and stops at 2,000 output lines. The
+ project page lists recent sessions, and each opens a timeline
+ (`/web/w/<ws>/<proj>/s/<session-id>`) that pages through its observations in
+ capture order with first/prev/next/last links and a jump field; with
+ JavaScript, a slider and `j`/`k` keys step one observation at a time. It uses
+ the same readers, owner filter and caps as the `/api/v1` session routes, and
+ observations render as escaped text. Both views follow the per-project read
+ rule: a non-grantee of a restricted project gets a 403, and a version id or
+ session id from another project or workspace reads as not found. The
+ `ai-memory-web` crate now has a `clippy.toml` that forbids the `Wiki` write
+ and destructive methods, so a write path in the web UI or `/api/v1` fails
+ `cargo clippy -D warnings`.
+- Added an observation stream to `memory_query` ranking, on by default
+ because it raised hit@5 on the retrieval eval for both zero-LLM and
+ local-embedding search while staying inside its latency and context-token
+ budgets. To keep the previous ranking, set `[retrieval]
+ observation_stream = false` (or
+ `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`); ranking is then identical
+ to before. A zero-LLM
+ session page keeps only a short excerpt of each turn, so the detail a
+ question asks about often lives only in the session's observations. With the
+ flag on, project and `scopes` searches also run full-text search over
+ observations in the same project, and each matching session votes once,
+ through its best-matching observation, for its own latest
+ `sessions/<id>.md` page as one more RRF stream. A page the stream voted for
+ takes its lexical evidence from the stream alone: page FTS over its
+ title-only body still reports a rank but adds nothing, so a session that
+ only shares topic words in its titles cannot outvote the session holding
+ the answer. When page search did not
+ match the page itself, the matching excerpt becomes the hit's snippet, and
+ `explain=true` lists `observation` in `streams_active` whenever the stream
+ runs and reports the matched observation ids. The excerpt and the ids are
+ shown only when the caller may read that session's timeline; another
+ operator's observations still vote for the shared session page. The stream
+ finds the project's observation range with an index seek. Hits are still
+ pages and nothing is written; sessions without a page
+ keep the `raw_hits` fallback, and `global=true` search is unchanged.
+- Added a root-only `GET /admin/metrics` endpoint in Prometheus text format.
+ It exposes the hook admission and delivery counters, MCP tool calls split
+ into reads and writes, and fixed-bucket latency histograms for `POST /hook`
+ and `memory_query`. Every label comes from a fixed set: no query text, page
+ body, prompt, client or project name, scope or token appears in the output.
+ On a multi-user server only root can read it, like every `/admin/*` route.
+- Added a `timings` object to `memory_query` responses with `explain=true`:
+ each retrieval stream's wall time in milliseconds (`fts_ms`, `entity_ms`,
+ `vector_ms`, `graph_ms`, `observation_ms`, `rerank_ms`), summed over `scopes`.
+ Streams that did not run are left out, and a query without `explain` reads
+ no clock for them.
+- Added a Grok Build CLI first-turn handoff rule. `install-hooks --agent grok
+ --apply` and `install-skills --scope global --agent grok` write
+ `$GROK_HOME/rules/ai-memory-handoff.md` (into the Grok home the hook file
+ was written to), which has the model call `memory_handoff_list` as its first
+ tool, through `use_tool` with the qualified key
+ `ai-memory__memory_handoff_list`, before reading any file. Grok discards
+ SessionStart stdout, so that call is what lets the first PostToolUse claim
+ the baton through GET `/handoff`. The rule corrects `workspace` and
+ `project` from the marker or git remote when the first list is empty or
+ answers with a scope error, and treats the handoff PostToolUse claimed as
+ authoritative. A same-name file without the managed marker is kept unless
+ `--force`; `uninstall --only hooks` or `--only skills` removes the managed
+ rule. (#1228)
+- Added the end reason to session-end observations. When a harness's
+ `SessionEnd` payload carries a `reason` (Claude Code sends `clear`,
+ `logout`, `prompt_input_exit` or `other`), its first line is stored,
+ sanitized, as the observation body, so consolidation can tell a normal
+ quit from anything else, and the zero-LLM session page closes its summary
+ with `ended (<reason>)`. Payloads without a reason are stored as before.
+ (#1225)
+- Added pending cross-project mail to the web UI. Project cards carry an amber
+ `N inbox` badge when messages are waiting for an agent in that project, the
+ home page summarises the total and links the projects holding mail, and the
+ project page gains a read-only Mailbox section listing up to five of them
+ (subject, sender, a snippet, age; "5 of N" when more are waiting), with an
+ empty state when there are none. A sender the viewer may not read is shown as
+ "a project you cannot read", and the page never pops or cancels a message.
+ (#1202)
+- Added `install-mcp --client prime-agent`, which registers ai-memory with
+ Prime Agent (PrimeIntellect-ai/prime-agent), merging an HTTP entry into the `mcpServers`
+ map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default
+ `~/.prime/agent/settings.json`) and preserving other settings and servers.
+ With a token the entry names `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`
+ and the token is not written; Prime Agent 0.10 counts a user HTTP server as
+ connected, and lists it to the model, only with that variable set (or an
+ OAuth grant), so export it where you launch `prime-agent`. Without a token
+ the server is still callable through `mcp.call_tool("ai-memory", ...)` but is
+ not listed. MCP-only: Prime Agent 0.10 has no lifecycle hooks. (#1163)
+- Added `expected_page_id` (write only if that is still the page's latest
+ version) and `create_only` (write only if the page does not exist) to
+ `memory_write_page`, and `expected_page_id` to `memory_delete_page`. A precondition
+ that no longer holds fails with `reason: "precondition_failed"` and the
+ current version, and changes nothing. `memory_read_page` returns the version
+ as `page_id` and `/api/v1` pages as `id`. This is the compare-and-write the
+ team-wiki sync needed (#986).
+- The `ai-memory-wikisync` companion gained CI and post-merge integration
+ (#986, slice 5): `sync --check` writes nothing and exits 0 in sync, 3 on
+ drift and 4 on conflicts or refusals (a clone without sync state compares
+ the repository with the server directly), and `install-hook` /
+ `uninstall-hook` manage a marked git `post-merge` block that runs `sync`
+ after each merge: a dry-run report unless `--on-merge apply`, never with
+ `--prefer`, and never with a stored token. The cookbook has a GitHub
+ Actions recipe. (#986)
+- Added delete propagation to the `ai-memory-wikisync` companion with
+ `sync --propagate-deletes` (#986, slice 4): a file deleted in the repository
+ deletes its server page through `memory_delete_page`, and a page deleted on
+ the server deletes its file, when the other side is unchanged since the last
+ sync. A delete against an edit is a conflict that `--prefer` resolves, more
+ than `--max-deletes` (default 10) refuses the run, and a pinned page is
+ deleted only with `--prefer repo`. Every sync write and delete now carries
+ the page version it was planned against, so a page changed during the run is
+ reported and left alone while the rest apply, and `sync --apply` refuses a
+ server older than 3.0. Without the flag deletes are still only reported.
+ (#986)
+- Changed `ai-memory doctor` to report three silent capture failures: an
+ unreachable server (reported instead of aborting the check), a hook spool that is full and
+ evicting undelivered events, and installed ai-memory Codex hooks that Codex
+ skips because they are untrusted or changed since they were trusted (asked
+ of Codex itself through `codex app-server`). `ai-memory status` no longer says
+ queued events will be delivered once the spool has started evicting them.
+- Added two-way sync to the `ai-memory-wikisync` companion (#986, slice 3):
+ `sync` imports repository edits and new pages through the public
+ `memory_write_page` MCP tool and exports server edits, comparing each
+ page with the last sync. A page changed on both sides is a conflict until
+ `--prefer repo` or `--prefer server`; deletes are reported, not synced.
+ It is a dry-run without `--apply`, refuses files without frontmatter,
+ refuses to overwrite server pages whose metadata a write would clear, and
+ re-reads each page right before writing it. An export, or an import's
+ rewrite of the repository file, is skipped and reported when that file
+ changed during the run, and the run exits non-zero. (#1164)
+- Changed `finalize-session --agent antigravity-cli` to replay the session's
+ typed prompts from `agy`'s `history.jsonl` before its synthetic session-end, so
+ live Antigravity sessions, whose hooks carry no prompt event, get a summary
+ page titled by the first prompt, a handoff with "Started/Last", and prompts
+ that `memory_query` and `memory_recent` can find. Only lines whose
+ conversation and workspace match the session are read; each prompt carries
+ the key `backfill` mints for it, so a repeated `--reopen` stores it once and a
+ prompt typed after the first finalize arrives with the next one. A checkout
+ the capture allowlist does not admit and `--all-owners` runs replay nothing,
+ and a missing `history.jsonl` only warns. (#1160)
+- Added `copilot` (alias `copilot-cli`) to `ai-memory run`, which manages
+ GitHub Copilot CLI as a workstream harness: a fresh session gets a generated
+ `--session-id`, a returning one is resumed with `--resume=<id>`, user
+ selectors (`--resume`, `--continue`, `--session-id`, `--connect`) win,
+ utility subcommands pass through, and `--yolo` maps to Copilot's native
+ `--yolo`. Visible messages, tool calls and results, and compaction summaries
+ are imported read-only from `$COPILOT_HOME/session-state/<uuid>/events.jsonl`
+ (system prompts, hidden reasoning, hook output, and telemetry are excluded),
+ and the existing SessionStart hook delivers the workstream context. The
+ first managed launch auto-wires Copilot's hooks and MCP, and `doctor` now
+ counts its local sessions. Verified against Copilot CLI 1.0.92. (#1040)
+- Made GitHub Copilot CLI a first-class routing target:
+ `install-skills --agent copilot-cli` (and `install-instructions
+ --skills-agent copilot-cli`) writes the managed Agent Skills to the
+ repository's `.github/skills` or, globally, to `$COPILOT_HOME/skills`
+ (default `~/.copilot/skills`); `memory_install_self_routing` returns
+ `copilot_cli` filename and skill-root hints; the routing snippet, the
+ routing-install skill, and the MCP instructions name Copilot CLI with
+ `AGENTS.md`; and `uninstall` sweeps both Copilot roots, removing only
+ marker-bearing ai-memory skills. (#1040)
+- Added `ai-memory recover` and a bounded local recovery journal for server
+ outages. Offline managed launches now record only uniquely correlated native
+ session locators; recovery quarantines overlapping spool entries before exact
+ `/hook/batch` transcript replay, journals harnesses without transcript export
+ as spool-only without calling their exporter, retains bounded recovery dedup
+ keys with their sessions,
+ fails closed on terminal drops, and lets only the original owner finish an
+ expired unsuperseded managed run through exact idempotent replay. Backfill
+ and recovery replay now use reserved `recovery_*` idempotency keys, so
+ re-running `backfill --force` over sessions imported by ai-memory ≤2.6.0 (or
+ plain-backfilling a recovery-replayed session) can duplicate those older
+ observations. Every spool drain path deletes an event the server answered
+ `dropped_*` or `resumed` instead of re-sending it each pass, and a hook
+ that finds the spool's capacity lock busy waits up to 50 ms and then spools
+ the event anyway. (#1125)
+- Added `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING` for the `openai-compat`
+ provider (opt-in, off by default, ignored by every other provider): when
+ set, every chat request carries
+ `chat_template_kwargs: {"enable_thinking": false}`, so thinking-capable
+ local engines (vLLM / SGLang serving Qwen3-class models) spend the output
+ budget on the structured payload instead of a reasoning pass. (#1130)
+- Added the `cursor` LLM provider. Consolidation calls the logged-in Cursor
+ Agent CLI (`agent --print --mode ask`) so a Cursor subscription can drive
+ summaries without an API key. The default model is `cursor-grok-4.6-high`
+ ("Grok 4.6"). `AI_MEMORY_CURSOR_AGENT` overrides the binary. The provider never passes
+ `--yolo` or `--force`, because the prompt is captured session text, and
+ runs `agent` with an allowlisted environment, so it never inherits
+ `AI_MEMORY_AUTH_TOKEN` or provider keys. (#1127)
+- Added `applies_to` and `enforced_by` arguments to `memory_write_page`, and
+ `--applies-to` / `--enforced-by` to `ai-memory write-page`, for profile
+ entries. Both fields were documented as profile-entry frontmatter, but no
+ tool could set them, so scoping an entry to a stack or keeping it out of the
+ digest meant editing the wiki file by hand, and the next tool rewrite of the
+ entry dropped the value. A tag the profile cannot detect in any project
+ (`typscript`) is refused instead of silently hiding the entry, and both
+ arguments are refused on any page the digest does not read: one outside
+ `profile/`, or a `profile/` path in an ordinary project. (#1178)
+- Added the server version to the footer of every signed-in `/web` page (the
+ public login and change-password pages leave it out), on the right
+ side opposite "ai-memory · read-only", so you can tell which build a browser
+ tab is talking to without running `ai-memory status`. (#1171)
+- Added `install-mcp --client dsh` for the DeepSeek Harness (aliases
+ `deepseek-harness` and `deepseek_harness`). DSH keeps its MCP client in
+ a Cordis profile patch rather than a fixed config file, so the command prints a
+ ready-to-merge `- insert:` fragment for `@deepseek-ai/dsh-mcp-client` and
+ refuses `--apply`. (#1193)
+- Added agentmemory import to the `ai-memory-importer` companion.
+ `agentmemory-vault` reads its Obsidian vault export; `agentmemory-export` reads its `ExportData`
+ JSON file, from disk only, and needs a mapping file from agentmemory's
+ project names (or exact session working directories) to ai-memory
+ workspaces and projects. `--apply` refuses to run while any record is
+ unmapped. Pages land under `imported/agentmemory/` (`--dest-prefix`), never
+ under `sessions/` or another reserved family, and links to pages that were
+ not imported become plain text. Every write goes through `memory_write_page`
+ with `create_only` or `expected_page_id`, and the importer refuses servers
+ older than 3.0. A memory's versions are written oldest first so ai-memory
+ keeps the supersession chain, and `forgetAfter` becomes `expires_at`. Each
+ page carries a stable UUIDv5 ingest key, so an interrupted import resumes
+ without duplicates and a rerun writes nothing. Text is redacted before
+ anything is planned or sent. Observations are dropped unless
+ `--replay-observations` replays them as `external-import` sessions through
+ `/hook/batch`, and records with no ai-memory counterpart are counted in the
+ manifest. The cookbook has a "Coming from agentmemory" section.
+- Added an agentmemory residue check to `ai-memory doctor`. It reports
+ agentmemory configuration left behind after a migration: an MCP server entry in any harness config `install-mcp` knows (or
+ in a project's `.mcp.json`, `.cursor/mcp.json`, `.gemini/settings.json` or
+ `.vscode/mcp.json`), and agentmemory guideline blocks in rules files such as
+ `AGENTS.md`, `GEMINI.md`, `.cursor/rules/` and `.kiro/steering/`. It names
+ each file and the key or lines, prints the fix, and warns when a block names
+ `memory_consolidate`, which ai-memory also has with different arguments. The
+ check only reads; it never edits or deletes another tool's files. `doctor
+ --json` carries the findings as `agentmemory_residue`.
+- Added `ai-memory auth enable`, which turns on bearer auth for an install
+ created without it. It reuses or creates an owner-only token at
+ `<data_dir>/auth-tokens/default`, records it in `config.toml`, gives the
+ installed hooks the token when they hold no other credential, and
+ re-registers every MCP client whose `ai-memory` entry points at this server
+ the way `install-mcp` now wires a token-file install. It lists each client
+ it changed, each entry for another server it left alone, and anything that
+ needs a manual change. Running it again changes nothing, and the token is
+ never printed or written into a harness config. Restart the server
+ afterwards.
+- Added `ai-memory mcp-bridge --no-session-id`, a plain stdio-to-HTTP MCP
+ bridge for any client that runs local commands. It authenticates with the
+ token from config (`AI_MEMORY_AUTH_TOKEN`, `[auth] bearer_token`, or the
+ file `[auth] bearer_token_file` names), forwards no session identity (the
+ client passes `workspace` and `project` like any static MCP client, and an
+ inherited `CLAUDE_CODE_SESSION_ID` is ignored), and exits at once with
+ `401 Unauthorized` when the server refuses it. Without the flag the bridge
+ keeps Claude Code's session forwarding and still refuses to start without
+ `CLAUDE_CODE_SESSION_ID`.
+- Added the `[auth] bearer_token_file` config key (env
+ `AI_MEMORY_AUTH__BEARER_TOKEN_FILE`): a file holding the root bearer token,
+ read once at startup. A relative path resolves against the data dir.
+ `AI_MEMORY_AUTH_TOKEN` still takes precedence; setting the key together with
+ `[auth] bearer_token` is a startup error, and a server whose configured file
+ is missing or empty refuses to start. A token read from the file is never
+ written into a harness config: `install-mcp` registers Claude Code through
+ the session-aware `ai-memory mcp-bridge` (Muse Code always gets the bridge,
+ as `mcp-bridge --agent muse`), gives Codex and Prime Agent a
+ reference to `$AI_MEMORY_AUTH_TOKEN`, and writes every other client a stdio
+ entry for `ai-memory mcp-bridge --no-session-id` in that client's own config
+ format (OpenCode, OpenCode 2, Cursor, Claude Desktop, Gemini CLI, OpenClaw,
+ OMP, Antigravity CLI, Zero, Devin, Grok, Kimi Code, Kiro CLI, Command Code,
+ Copilot CLI, Swival, VS Code, Zed; DeepSeek Harness's printed
+ patch too). Only ZCode, whose config keeps HTTP entries only, is refused with
+ the manual option. `uninstall` recognises these entries.
+ `install-hooks --apply` stores the token in the hook credential files only.
+- Changed `ai-memory status` and `ai-memory doctor` to show the server's auth
+ posture, and for an unauthenticated loopback server print
+ `auth: none (loopback)` with the fix, `ai-memory auth enable`.
+- Added a server-side drop list for tool events: `[ingest]
+ drop_tool_use_id_prefixes` and `drop_tool_names` (both empty by default, at
+ most 64 entries of 128 characters). A PreToolUse or PostToolUse event whose
+ tool-call id starts with a listed prefix, or whose tool name matches
+ exactly, is answered with 202 and counted as a policy drop in `/hook` and
+ `/hook/batch`, before it is sanitized, rate-limited or stored. The id and
+ name are read from each harness's own fields (Claude Code's `tool_use_id`,
+ OpenCode's `callID`, Hermes's `extra.tool_call_id`, and so on). The lists
+ apply to every project on the server. (#1241, #1244)
+- Added `--project-id` to `purge-project`, `rename-project` and
+ `move-project` (and `project_id` to their admin endpoints), as an
+ alternative to the project name. A legacy twin row whose name collides with
+ another project's `legacy_name` (the empty leftover an older migration
+ leaves behind) was refused as ambiguous by name, so it could not be purged
+ or renamed. The id is looked up inside the named workspace: sending both or
+ neither is a 400, a malformed UUID is a 400, and an id that names no project
+ in that workspace is a 404. `list-projects` now prints each project's id so
+ an operator can copy it, and `GET /api/v1/projects` rows carry
+ `workspace_id` and `project_id` (hidden with the row for a restricted
+ project). (#1208, #1226)
+- Added `ai-memory project init`, which creates a `.ai-memory.toml` marker at
+ the current worktree root (or the current directory outside Git) after
+ asking for `workspace` and `project`. The defaults are the scope the CLI and
+ hooks already resolve for the checkout, so accepting them keeps the memory
+ where it is. It writes only those two keys, needs an interactive terminal,
+ and never overwrites an existing marker. (#1227)
+- Added first-class Factory Droid CLI support. `install-mcp --client droid`
+ (alias `factory-droid`) merges an HTTP entry into `~/.factory/mcp.json`,
+ with the URL written literally and a bearer referenced as
+ `Bearer ${AI_MEMORY_AUTH_TOKEN}`: Droid expands variables in headers but
+ never in the URL.
+ `install-hooks --agent droid` merges native
+ `ai-memory hook --event … --agent droid` commands for seven events into
+ `~/.factory/hooks.json`, keeps your own entries, changes nothing on a
+ re-run, and refuses to create that file while `~/.factory/settings.json`
+ holds hooks, which Droid would then stop reading. Sessions are recorded as
+ agent `droid` (migration V78). The `SessionStart` hook delivers the pending
+ handoff, and Droid's own `SessionEnd` closes the session. Droid's `Read`,
+ `Create`, `Edit`, `ApplyPatch`, `LS`, `Grep`, `Glob` and `Execute` tools
+ map to the file, search and shell families, so `[capture] ignore_paths`
+ applies to them: verified against the Droid 0.240.0 tool schemas; no
+ tool-call id in Droid payloads. `setup-agent --agent droid` prints the
+ hook config and `uninstall` removes both entries. (#1240)
+- Added first-class Meta Muse Code support. `install-hooks --agent muse`
+ (aliases `muse-code`, `musecode`) merges native
+ `ai-memory hook --event … --agent muse` commands for eight events
+ (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
+ `PostToolUseFailure`, `PreCompact`, `Stop`, `SessionEnd`) into the `hooks`
+ key of `${XDG_CONFIG_HOME:-~/.config}/muse/settings.json`, with an empty
+ matcher, a 30-second timeout and the server URL and data dir baked in,
+ since Muse runs hooks with a cleared environment. It keeps
+ `"schema_version": 1`, every other key and your own hooks, writes a backup
+ when it changes the file, and changes nothing on a re-run. Sessions are
+ recorded as agent `muse` under Muse's own session id (migration V80). The
+ `SessionStart` hook delivers the pending handoff through
+ `hookSpecificOutput.additionalContext`, the `SessionStart` and
+ `UserPromptSubmit` hooks print nothing when there is nothing to deliver
+ (Muse adds that stdout to the model's context), and Muse's own `SessionEnd`
+ closes the session. Muse's `read_file`, `write_file`, `edit_file`,
+ `apply_patch`, `search`, `bash`, `monitor`, `web_fetch` and memory tools map
+ to the file, search and shell families, with a relative `path` resolved
+ lexically against `cwd`, so `[capture] ignore_paths` and the server drop
+ list apply; Muse's `tool_use_id` is kept as the call id. `SubagentStart` and
+ `SubagentStop` are not wired, because Muse fires them every turn for its
+ built-in reminder observers. `install-mcp --client muse` now writes a stdio
+ `ai-memory mcp-bridge --agent muse` entry with `"mode": "optional"` and the
+ install's `--data-dir`, replacing the streamable-HTTP entry, so Muse is a
+ session-aware client: the new `mcp-bridge --agent muse` forwards
+ `MUSE_SESSION_ID` and reads no other harness's variable (`--agent
+ claude-code`, the default, reads only `CLAUDE_CODE_SESSION_ID`). The entry
+ goes under `mcpServers`, or under the legacy `mcp_servers` when the file
+ already uses it, never both; a file holding both maps, which makes Muse
+ ignore every MCP server, is refused and reported by `doctor`. The settings
+ path follows `XDG_CONFIG_HOME`. The Claude Code plugin launcher records an
+ event as `muse` when Muse runs it (`MUSE_PLUGIN_ID` with `MUSE_SESSION_ID`),
+ skipping the events the Muse settings hooks deliver, its subagent events and
+ folderless sessions. `setup` detects Muse by its config or data directory,
+ `setup-agent --agent muse` prints the hook config, `doctor` reports the Muse
+ wiring, `uninstall` removes the hooks and the entry from either map, the
+ Docker wrapper forwards `MUSE_SESSION_ID`, and the routing snippet lists
+ Muse Code among the `AGENTS.md` harnesses. Verified offline against Muse
+ Code 1.4.7 hook payloads, and end to end with the real Muse binary in an
+ isolated network namespace against a stand-in model provider: capture of
+ all eight events, exclusions on relative and absolute paths, MCP calls
+ routed by session, handoff injection and the timeout unit. Not verified:
+ interactive `SessionStart` sources and `SessionEnd` reasons, `PreCompact`
+ payloads, `apply_patch` and `monitor` input shapes, macOS and Windows paths,
+ and the plugin from the marketplace, which Muse Code 1.4.7 refuses to
+ install because its `.mcp.json` uses `${user_config.*}` placeholders.
+- Added an optional TypeScript client SDK in `companions/ai-memory-ts` for
+ programs that are not coding-agent harnesses: custom agents, bots, editor
+ and app extensions, scripts and CI jobs. `AiMemoryClient` wraps the page,
+ query, status, recent, handoff, message, briefing, explore,
+ session-observation and feedback tools, the read-only `/api/v1` routes (with
+ cursor paging and `ETag` revalidation) and `GET /identity`, with typed
+ results, a typed error taxonomy and scope checks before any request.
+ `pages.update` reads a page, applies a change and writes it back guarded by
+ `expectedPageId`, keeping the page's metadata. A separate
+ `ai-memory-ts/admin` entry point covers checkpoints, page restore and
+ session or project purges, which default to a dry run and need both
+ `dryRun: false` and `confirm: true` to delete. The SDK has no runtime
+ dependencies, needs Node 22 and a 3.0.0 server, and is built from a checkout
+ for now; it is not published to npm and is never part of the server's
+ tarballs, Docker image, Homebrew, AUR, RPM or Nix packages, which
+ `scripts/check-native-packaging.sh` now enforces. CI runs it against the
+ server built from the same commit, including a schema drift test that fails
+ when an MCP tool changes without an SDK update. See
+ `companions/ai-memory-ts/README.md` and `docs/design-client-sdk.md`. (#1165)
+
+### Changed
+- Documented the 2.x to 3.0 upgrade in `docs/upgrading-to-3.0.md`: what
+ changes, what replaces the removed token commands, the backup, upgrade and
+ check steps, and how to roll back by restoring the backup with the 2.x
+ binary. README, `docs/install.md` and `docs/MIGRATION-2.0.md` link to it.
+- Changed the web UI's project sidebar to link each folder to its namespace
+ listing with a page count, and to show only its five most recently updated
+ pages with a "View all N" link. The namespace listing now sorts by recent
+ update or by title and shows 25 pages at a time with previous and next links
+ (`?sort=title&page=2`). (#1247)
+- Changed scoped `/api/v1/search` (a single `workspace` + `project`, or
+ `scopes`) to rank with the same hybrid ranker as `memory_query` instead of
+ FTS5 alone, so it returns the same order as `memory_query`, and `rank` is
+ now the fused rank. Cross-project search without a scope is unchanged.
+- Documented hand-written MCP recipes for Warp, Cline, Kilo Code, Goose,
+ Qwen Code and OpenHuman in `docs/install.md`, and listed them in `docs/support-matrix.md` as `MCP-only (documented)`: each recipe follows
+ the client's own documentation at a named version and has not yet been run
+ end to end. Aider is not listed because it has no MCP support.
+- Published `docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md`, which
+ splits the LongMemEval-S retrieval number into capture cost, ranking quality
+ and harness artifacts, and records what the observation stream recovered
+ (zero-LLM FTS `hit@5` 0.662 → 0.951 and local embeddings 0.796 → 0.936 on
+ all 470 questions). The benchmark,
+ evals and comparison docs no longer blame the 2 KB excerpt cap for the gap
+ (pages holding exactly the captured text score 0.968 against 0.972 for whole
+ sessions) and no longer attribute agentmemory's 0.967 to LongMemEval-S: it is
+ the grep baseline on agentmemory's in-house corpus, and its LongMemEval-S
+ figure is 95.2% from a component harness with the reranker disabled, not
+ like-for-like with ai-memory's pipeline numbers. `docs/comparison.md` gains a
+ "From agentmemory" migration note.
+- Changed `ai-memory init` on a fresh data dir (no config file and no
+ database yet) to create a root bearer token at
+ `<data_dir>/auth-tokens/default` and record `[auth] bearer_token_file`, so
+ a new install's server requires the token on every route except `/healthz`.
+ The hooks, the CLI and `ai-memory mcp-bridge` read it from the data dir;
+ client commands of a packaged install, whose config lives outside the data
+ dir, find it there too when they read no config file and target a loopback
+ server. Existing installs are unchanged and keep running without auth until
+ `ai-memory auth enable`; so is an `init` that finds a database or a bearer
+ supplied another way. `uninstall` keeps this token, since it is the
+ server's credential. The Docker wrapper hands a host command (`install-hooks`,
+ `mcp-bridge`, `run`) the token of a server initialized on its volume as an
+ owner-only file that `install-hooks` copies from the volume, never on a
+ command line. The wrapper deletes that host copy when `install-hooks` finds
+ no token in the volume and after a successful `uninstall --apply`. With no human accounts the built-in web UI answers a browser
+ with a Basic sign-in prompt instead of redirecting to a login form that
+ could not succeed: any username, and the token file's contents as the
+ password. `ai-memory setup` prints that URL and the file to read, never the
+ token. The macOS menu bar app reads the token from its data dir when none is
+ saved in Settings, so an install it initialized turns green without pasting
+ anything.
+- Changed `ai-memory-wikisync` files to carry a small frontmatter (`title`,
+ plus `tags`, `pinned` and a non-default `tier` when set) above the body,
+ so metadata survives a round trip. The first run after upgrading rewrites
+ unedited files of an earlier export in place. (#1164)
+- Changed the header search box in `/web` to search the project you are
+ viewing. On a project, page, namespace or history view it now sends
+ `workspace` and `project` with the query, and its label and placeholder name
+ the project. The search page gained a "Search in" selector (`scope=<workspace>/<project>`)
+ that lists only the projects the viewer may read, an "in workspace/project ×"
+ chip that clears the scope, a breadcrumb, and a "Search all projects" button
+ when a scoped search finds nothing. (#1245)
+
+### Removed
+- Removed the 1.x compatibility-token commands `ai-memory user add`,
+ `user expire`, `user revive` and `user rotate-token`, and their admin
+ endpoints `POST /admin/users` and `POST
+ /admin/users/{name}/expire`, `/revive` and `/rotate-token`. They were
+ deprecated in 2.0. Tokens they issued keep authenticating after the upgrade
+ as ordinary API keys with the label `legacy-user-token`: list them with
+ `ai-memory api-key list`, replace one with `api-key rotate <id>` and retire
+ one with `api-key revoke <id>`. A token expired before the upgrade stays
+ refused. Add people with `user add-human` and machine credentials with
+ `api-key add`. Migration V79 drops the unused `users.token_hash` and
+ `users.token_expired_at` columns and the triggers that mirrored them into
+ `api_credentials`, so user records from `/admin/users` and `ai-memory user
+ list --json` no longer carry `token_expired_at`, and `user list` no longer
+ shows an `expired` status.
+- Removed the `OPENCODE_ZEN_BASE_URL` constant from the `ai-memory-llm`
+ crate, deprecated since 2.1.0; use `OPENCODE_GO_BASE_URL`, which holds the
+ same URL. The `opencode-zen` provider alias is unchanged.
+
+### Fixed
- - Fixed the companion relay refusing to open its queue on Windows when another
- relay process was committing to the same queue. SQLite deletes its rollback
- journal at each commit, and Windows answers "access denied" for a file
- that is being deleted, so the queue-file guard failed with `inspect
- relay.sqlite-journal: Access is denied`. The guard now retries that answer
- for up to about 100 ms; a file that stays unreadable is still refused.
+- Fixed SessionEnd consolidation repeating the same expensive prompt on the
+ durable queue when the structured LLM response fails deterministically: a
+ truncated or empty response, malformed JSON, or an unexpected response
+ shape now ends the queue on the first attempt, keeping the heuristic page
+ the hook already wrote; pre-send connection and capacity (`503`) failures
+ retain the bounded backoff. (#1131)
+- Fixed structured LLM responses stopped at the output budget
+ (`finish_reason = "length"`) or returned without usable content: they now
+ fail with redacted terminal errors, without copying the response. (#1130)
- - Fixed `ai-memory hook` running inside a helper container on Docker-wrapper
- installs (Linux/macOS). A hook config or plugin that called the wrapper paid
- about 280 ms per event, over the 200 ms hook budget, and its default
- `127.0.0.1` server URL pointed at the container instead of the host server.
- The wrapper now runs `hook` and `hook-drain` through the same
- checksum-verified native host client as `mcp-bridge` and `install-hooks`.
- A hook only reuses the installed client, with no update check or download
- on the hook path. When no client is installed yet, the wrapper says to run
- `ai-memory install-hooks` once, skips the event and exits 0, so the agent
- is never blocked.
-
+### Security
+- Fixed HTTP Basic sign-in to the web UI minting a 30-day `ai_memory_auth`
+ cookie that held the root bearer token. Basic sign-in sets no cookie now;
+ a cookie set by an older build keeps working until human auth is enabled.
+- Fixed `memory_query`, `/web/search` and `/api/v1/search` showing another
+ operator's captured observations on a multi-user server. Observation
+ excerpts, the observation ids in `explain`, and raw-observation fallback
+ hits now come only from sessions the caller may read under the
+ session-timeline owner rule. Another operator's observations still rank
+ shared session pages.
+
+ ## [2.6.7] - 2026-10-13
+
+ ### Deprecated
+
+ - The 1.x compatibility-token commands `user add`, `user expire`,
+ `user revive` and `user rotate-token`, and their admin endpoints, will be
+ removed in 3.0.0. Tokens they issued keep working after the upgrade as
+ ordinary API keys; manage them with `api-key list|rotate|revoke`, and add
+ people with `user add-human`.
+
+ ### Fixed
+
+ - Fixed the companion relay refusing to open its queue on Windows when another
+ relay process was committing to the same queue. SQLite deletes its rollback
+ journal at each commit, and Windows answers "access denied" for a file
+ that is being deleted, so the queue-file guard failed with `inspect
+ relay.sqlite-journal: Access is denied`. The guard now retries that answer
+ for up to about 100 ms; a file that stays unreadable is still refused.
+ - Fixed `ai-memory hook` running inside a helper container on Docker-wrapper
+ installs (Linux/macOS). A hook config or plugin that called the wrapper paid
+ about 280 ms per event, over the 200 ms hook budget, and its default
+ `127.0.0.1` server URL pointed at the container instead of the host server.
+ The wrapper now runs `hook` and `hook-drain` through the same
+ checksum-verified native host client as `mcp-bridge` and `install-hooks`.
+ A hook only reuses the installed client, with no update check or download
+ on the hook path. When no client is installed yet, the wrapper says to run
+ `ai-memory install-hooks` once, skips the event and exits 0, so the agent
+ is never blocked.
+
## [2.6.6] - 2026-10-13
### Fixed
diff --cc Cargo.lock
index 0869127c,84382577..b33344f4
--- a/Cargo.lock
+++ b/Cargo.lock
@@@ -274,10 -271,9 +274,10 @@@ version = "2.6.7
[[package]]
name = "ai-memory-web"
- version = "2.6.6"
+ version = "2.6.7"
dependencies = [
"ai-memory-core",
+ "ai-memory-llm",
"ai-memory-store",
"ai-memory-wiki",
"anyhow",