Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Merge upstream/main into feat/nix-service
Test0a50bb155497
diff --cc CHANGELOG.mdindex 79b48135,439e4426..f1f00538--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -7,47 -7,729 +7,766 @@@ and this project adheres to [Semantic V## [Unreleased]+### Added+- A NixOS module (`nix/nixos-module.nix`, exposed as `nixosModules.default`)+ so NixOS hosts can run `services.ai-memory.enable = true` as a hardened+ systemd service — dedicated `ai-memory` system user (`nologin`, gated by+ `createUser`) plus a shared systemd sandbox applied to both NixOS and the+ packaged FHS units (`nix/systemd-sandbox.nix`). Typed+ `services.ai-memory.settings` renders declarative `config.toml`; secrets use+ `ageSecret`, `sopsSecret`, or `environmentFile` (required for non-loopback+ binds). The web UI defaults off (`enableWeb = false`, matching the CLI+ flag's own default rather than the packaged unit's hardcoded+ `--enable-web`). `flake.nix` adds eval checks for sandbox keys, settings →+ `--config`, agenix/sops wiring, refusal contracts (age+sops mutex, secrets+ in `settings.auth`, forbidden `settings.bind`), `ExecStart`+ (`--data-dir` / `serve` / `--transport http`), default `StateDirectory` vs+ custom `dataDir` tmpfiles/`ReadWritePaths`, and cheap+ network-online / `openFirewall` / `MemoryMax` / `TasksMax` round-trips.+ `packages.x86_64-linux.nixos-ai-memory-docker` builds one NixOS+ `system.build.toplevel` (via the docker-image rootfs tarball) and+ `scripts/test-nixos-systemd-container.sh` runs a privileged systemd+ container smoke (`systemctl` + in-container `/healthz` + dataDir+ restart/volume persistence) on the Linux `nix.yml` leg. The existing- `flake.nix` package/devShell/CLI build is unchanged. (#NNN)++ `flake.nix` package/devShell/CLI build is unchanged. (#989)++### Changed+- `.github/workflows/nix.yml` now builds the flake on `x86_64-linux` and+ `aarch64-darwin` with `scripts/check-nix-packaging.sh` artifact smoke tests+ (binary, hooks, config template, `nix run`); NixOS module eval and the- NixOS systemd container smoke stay on the Linux leg only. (#NNN)- - Documented API Route as an endpoint for the existing `openai-compat`- provider. (#997)++ NixOS systemd container smoke stay on the Linux leg only. (#989)++### Fixed+- NixOS systemd container smoke probes `/healthz` via in-container `curl`+ (and ships `curl` in the smoke image). The module's default+ `127.0.0.1` bind is unreachable through Docker published ports, so the+ previous host-side probe timed out after the unit was already active.+ Also invokes `systemctl`/`journalctl` via absolute NixOS profile paths+ because `docker import` leaves no image `PATH`. (#989)- - Kimi Code no longer receives a bare `{}` when a `UserPromptSubmit` is- dropped by capture policy: the hook now writes an empty success response- Kimi accepts instead of a JSON object it rejects. (#996)+++ ## [2.5.0] - 2026-09-30++ ### Added+ - `ai-memory run --yolo` now warns before disarming an agent's safety prompts+ and, on Linux/macOS, offers to re-run the session inside+ [ai-jail](https://github.com/akitaonrails/ai-jail) when it is installed.+ The warning and offer are TTY-gated (stdin and stderr must both be real+ terminals) and skipped entirely when already running inside ai-jail+ (detected via the Linux `ai-sandbox` hostname or the macOS `(jail) ` `PS1`+ prefix), so hook, CI, detached, and piped runs are unaffected. Accepting+ the ai-jail offer re-execs the original invocation under `ai-jail+ --network --agent-state <harness> --env <NAME>...` (only already-set+ credential/config env vars are forwarded); declining `--yolo` itself+ aborts before the agent spawns. A new opt-in `--true-yolo` flag /+ `claude_true_yolo` config key additionally silences Claude Code's+ residual `--dangerously-skip-permissions` prompts (the `rm` timeout and+ confirmation, and the PowerShell `rm` deny) and forces+ `--settings '{"permissions":{"defaultMode":"bypassPermissions","ask":[]}}'`;+ it is a no-op for every other harness. See+ `docs/design-yolo-safety-ai-jail.md`. (#994)+ - `ai-memory repair-backfill-timestamps [--project] [--workspace] [--confirm]+ [--json]` and `POST /admin/repair-session-times` correct+ `sessions.started_at`/`ended_at` for sessions an older `backfill` imported+ before it carried the transcript's own event time, which flattened every+ imported session onto the import day. Only rewrites a row whose+ `started_at` actually postdates the candidate's own transcript end (a+ correctly hook-captured session, or a re-run, is a no-op); refuses+ out-of-scope, unchanged, negative, inverted, or future-dated candidates;+ never closes a still-open session; and records an `audit_log` row on+ apply. Dry-run by default. (#921)+ - Native tool output resolution for Antigravity CLI lifecycle hooks+ (`post-tool-use`). Command stdout (`run_command`), file views (`view_file`),+ search results (`find_by_name`, `grep_search`, `search_web`), and task+ management outputs are now read directly from+ `.system_generated/steps/<stepIdx>/output.txt` and populated into observation+ excerpts. Code modification capture via `write_to_file` and+ `replace_file_content` remains preserved from invocation arguments. (#966)+ - The watcher's reconcile pass can now optionally tombstone a wiki page whose+ file has disappeared from disk, closing part of the gap left by #929 (the+ watcher only reconciled create/modify events, so a deleted file stayed+ indexed until `ai-memory delete-page` ran explicitly). Opt-in and default+ `false` (`[maintenance] reconcile_tombstones_deleted_pages`), so existing+ installs see no behavior change unless they turn it on. When enabled, a+ page's file must be observed missing on two consecutive 30s reconcile+ passes, re-verified against the live filesystem immediately before acting;+ a circuit breaker refuses to act on a whole scope when more than `max(3,+ 50%)` of its candidate pages look missing in one pass, or when a+ non-partial walk finds nothing at all (either shape is far more likely a+ walk/mount problem than genuine mass deletion); and reserved/indexed-but-+ unwalked paths (`bootstrap.md`, `_meta.md`, `_pending/` sidecars, and+ `sessions/*.md` — excluded because a same-workspace `move-session` re-home+ can leave one with a correct row and no file, a separate pre-existing bug)+ are never candidates. The action is a soft tombstone (`is_latest = 0` ++ `superseded_at`, the same shape decay eviction already uses), picked up by+ the SAME aged-tombstone hard-delete sweep decay eviction uses — it is not+ exempt from it. What actually protects it: it is never destroyed while its+ chain has no successor; if the file returns, the new version re-links onto+ the tombstoned chain instead of starting a fresh, disconnected one, so+ nothing is left orphaned for that sweep to destroy. It never runs the+ blocking admission gate (nothing can refuse it), but does fire-and-forget+ any non-blocking observer/mirror webhook on success. `restore-page` and+ version history remain intact. See `docs/okf.md` for the full design.+ (#964)+ - `ai-memory run` now finalizes the session when a harness without a native+ session-end hook exits (Command Code, Kiro CLI v2 and v3, Antigravity CLI),+ so the summary, handoff and opt-in SessionEnd consolidation no longer wait+ for a manual `ai-memory finalize-session`. Only a session the run can tie to+ itself (named, chosen before the spawn, or linked during the run) is closed,+ including again after it was resumed; if finalizing fails, the run prints+ the exact command to run and keeps the harness's exit code. (#941)+ - `[consolidation] input_token_safety_margin` (float, default `0.8`, validated+ to `(0.0, 1.0]`) scales the approximate char-count input budget. The+ `max_input_tokens` budget uses a flat chars-per-token heuristic that+ under-budgets denser corpora — pt-BR text and source code tokenize at fewer+ chars per token than English and could overshoot a provider's real input+ limit by ~40%. The default tightens the common case modestly while leaving+ such corpora headroom; lower it further for a mostly non-English or code+ corpus. `max_input_tokens` is now documented as an approximate heuristic in+ the config reference. (#884)+ - `install-skills --agent hermes` (and the `hermes` entry in+ `memory_install_self_routing`'s `target_hints`) installs the managed routing+ skills into Hermes Agent's `.hermes/skills` (project) or `~/.hermes/skills`+ (global) family, completing Hermes routing support alongside its lifecycle+ hooks (#933). (#942)+ - `[search.fts] stopwords` (env `AI_MEMORY_SEARCH_FTS_STOPWORDS`, CSV) makes+ the stopword filter for bare natural-language FTS queries configurable,+ so a non-English install can list its own function words (e.g. Portuguese+ `de`, `que`, `em`) instead of having them match nearly every page and skew+ the FTS side of hybrid ranking. Absent keeps today's English list, so+ nothing changes on upgrade; `[]` disables the filter. Entries match+ queries case-insensitively (Unicode) but keep diacritics, so list both+ `nao` and `não` if users type both. Option A from #953, proposed by+ @rntjr. (#956)+ - `docs/jev-reranker-adapter.md` gains a choice-contrastive variant of the+ Jev reranker adapter+ (`docs/examples/jev-reranker-adapter/jev_rerank_shim_choice.py`): one+ `choice` question over the whole candidate list instead of one rubric+ `score` per candidate, choice probability mapped to `relevance`. The+ example asks for the specific page that contains the answer, and not to+ pick an index, catalog, or summary when a more specific page answers.+ On the same live golden set and 35B backend the choice shape measured+ hit@1 0.778 / NDCG@10 0.893 at 0.75 s mean rerank latency versus 0.636 /+ 0.833 at 2.2 s for the rubric adapter, and it is the shape in which+ replay-trained small judges hold their quality (4B: 0.808 vs 0.596).+ Safe because the reranker leg is sort-only; the rubric-adapter caveat+ on absolute relevance semantics is scoped to consumers that read+ absolute values.+ - `ai-memory reclaim-ledger-versions` drops the superseded versions of the raw+ hook event ledger that the pre-2.1.1 indexer left behind (#660), and nothing+ else. It reports what it would remove and changes nothing unless+ `--confirm`; `--drop-latest` also removes each ledger's live row, and+ `--compact` rebuilds the FTS index and `VACUUM`s to return the freed bytes.+ A path is only a candidate when its *content* is a hook ledger, so a real+ page named `log-2026-09.md` keeps its whole version chain, and only+ `is_latest=0 AND superseded_at IS NULL` rows are eligible, so decay-owned+ rows stay with `forget-sweep`. Derived FTS/entity/vector/link rows go with+ the page through the existing cascades, and the FTS delete trigger is stood+ down for the bulk delete and restored from its own `sqlite_master` DDL+ afterwards, so the cleanup does not re-tokenize tens of gigabytes of ledger+ body one row at a time. (#914)+ - `identity = "…"` in `.ai-memory.toml` pins the repository identity a+ checkout's captures route by, outranking `project` and the git remote — see+ [marker-file.md](docs/marker-file.md#repository-identity). (#708)+ - The builtin web UI has a root-only `/web/pending` page to triage pending+ auto-improvement proposals. It lists the proposals of all projects, with a+ project filter and a sort, and shows the rationale and the proposed body.+ Approve and reject post to the existing+ `/admin/pending-writes/{id}/approve|reject` routes with the session cookie+ and the CSRF header, so admission, audit, and attribution stay the same.+ `ai-memory-web` adds no write route. (#855)+ - Native `ai-memory upgrade` for GitHub-release installs (Linux/macOS+ tarballs and Windows x86_64 zip): downloads the matching release archive,+ verifies the `.sha256` sidecar, replaces the on-disk binary (and a sibling+ `hooks/` tree when present), then re-runs `install-hooks --apply` for staged+ agents. Windows uses rename-aside self-replace (running `.exe` → `.old`,+ promote `.new`) because the mapped image cannot be overwritten in place.+ Refuses package-managed paths (Homebrew/AUR/`/usr`), containers, and+ unwritable prefixes; the Docker wrapper's `upgrade` path is unchanged. Pin+ with `--version` / force a re-download with `--force`. Optional+ `AI_MEMORY_RELEASE_BASE_URL` / `release_base_url` overrides the Releases+ base for mirrors and hermetic tests (loaded via `Config`, not ad-hoc env).+ Downloads refuse bodies over 128 MiB (Content-Length and streamed cap).+ (#801, #802)+ - `ai-memory run` accepts a repeatable `--env KEY=VALUE` and an `--env-file+ <path>` (blank lines and `#` comments skipped) to pass extra environment+ into the spawned harness — e.g. a per-account `CLAUDE_CONFIG_DIR` for+ callers who previously had to wrap the launch in `env KEY=VAL harness`.+ Both flags are wrapper-owned like `--yolo`/`--executable` and must precede+ the harness name; a `--env` entry overrides a same-key `--env-file` line.+ The resolved environment reaches the spawned process, ai-memory's own+ native-session resolution, first-launch auto-wire and the global Crush+ config the managed context packet is layered onto, so the session store,+ hooks and MCP all follow a `CLAUDE_CONFIG_DIR`-style override, and+ auto-wire warns when the override puts Pi and OMP in one extensions+ directory. See `docs/managed-workstreams.md`. (#820)+ - `contradiction_band_min` / `contradiction_band_max` config keys (env:+ `AI_MEMORY_CONTRADICTION_BAND_MIN` / `AI_MEMORY_CONTRADICTION_BAND_MAX`)+ make `memory_lint`'s A5 zero-LLM contradiction-detection cosine-similarity+ band configurable, defaulting to the historical fixed `0.4`–`0.75`. The+ band is a fixed absolute cosine value, but background similarity is+ corpus-dependent: on a single-language or single-domain store, unrelated+ pages already sit above the general-purpose floor, so the default band+ measures domain proximity more than conflict and produces noisy findings.+ Raising `contradiction_band_min` trims that noise. Rejected at config load+ unless `0.0 <= contradiction_band_min < contradiction_band_max <= 1.0` and+ both are finite. (#853)+ - Fedora users can install prebuilt x86_64 and aarch64 RPMs from GitHub+ Releases, with the existing native systemd service assets. (#858)+ - `embedding_query_prefix` / `embedding_document_prefix` config keys (env:+ `AI_MEMORY_EMBEDDING_QUERY_PREFIX` / `AI_MEMORY_EMBEDDING_DOCUMENT_PREFIX`)+ for the `openai` and `openai-compat` embedders: an optional string+ prepended to query / document text before the existing truncation, so+ truncation still bounds the whole input. Asymmetric embedding models need+ a query-side instruction their publisher specifies; the OpenAI-compatible+ `/v1/embeddings` wire format has no field for it.+ `nvidia/Nemotron-3-Embed-1B-BF16` and base E5 models use a simple+ `"query: "` / `"passage: "` pair; instruction-tuned E5 variants and+ Qwen3-Embedding instead need a task-instruction string on the query side+ only (documents stay plain). Empty by default — no behaviour change when+ unset, and not trimmed (nor is a present-but-empty env-var override, which+ now clears a `config.toml` value), so a publisher's trailing space is+ preserved. A non-empty `embedding_document_prefix` is folded into the+ stored embedding identity (`Embedder::model_identity`), so a document+ prefix change makes retrieval, backfill, and cleanup treat existing pages+ as stale and re-embed them automatically — an empty prefix keeps the+ pre-existing identity, so upgrading installs need no migration, and a+ query-only prefix change never needs a rebuild. See+ `docs/llm-providers.md`. (#859)+ - Added the optional `ai-memory-relay` companion for external lifecycle events.+ It queues events locally and sends ordered batches through the public hook API,+ using stable event identities for retries. The package has its own workspace+ and does not change the server's capture or storage defaults. (#823)+ - `auto_improve.patchable_page_prefixes` makes the folders whose page bodies the+ reviewer reads configurable, defaulting to the historical `_rules/` and+ `procedures/`. Only those two folders' contents were ever sent; every other+ page reached the model as a single title line, so a project keeping its+ durable knowledge in `decisions/` or `gotchas/` — with no `_rules/` pages at+ all — sent no page bodies, and the reviewer re-proposed invariants that were+ already written down, at high confidence, indefinitely. Existing configs are+ unchanged. (#834)+ - `ai-memory finalize-session --reopen --session-id <uuid>` re-finalizes a+ session that already ended, for agents without a true session-end event+ (Antigravity CLI, Kiro, ZCode, Pool) whose conversation continued after a+ first manual finalize: the discovery step now accepts `include_ended=true`+ on `GET /admin/open-sessions` for an exact session id (rejected without+ one, so reopening stays exact-id-only and never a bulk operation), and the+ server's normal session-end path re-runs over the new observations+ (updated summary page via supersession, new handoff, opt-in+ consolidation). Re-running with nothing new since the first end remains a+ harmless no-op. The default finalize behavior is unchanged: ended sessions+ stay invisible unless `--reopen` is passed. (#836)+ - Added per-execution `AI_MEMORY_CAPTURE_OWNER` context for external lifecycle+ producers. Updated native hooks, script bundles and generated integrations+ suppress capture while preserving supported handoff delivery and MCP recall.+ Documented producer provenance and stable retries through the existing hook+ ingestion API, without changing its schema or standalone defaults. (#821)+ - Builtin `/web` login and change-password pages for human password sessions:+ unauthenticated browser GETs to the wiki redirect to `{web_slug}/login`+ (not bare JSON 401), forms call existing `POST /auth/login` /+ `/auth/password` / `/auth/logout`, and `--web-ui-dir` custom SPAs stay+ unchanged. (#811)+ - `docs/jev-reranker-adapter.md` documents a stdlib-only adapter+ (`docs/examples/jev-reranker-adapter/jev_rerank_shim.py`) that serves the+ `AI_MEMORY_RERANKER=llm` request leg from a Jev `/v1/systemone` judge+ endpoint while reverse-proxying consolidation/lint/bootstrap traffic to+ the configured provider unchanged. In the contributor's own 102-query+ golden-set benchmark the judge matched the hosted reranker's+ hit@1/MRR/NDCG@10 (0.778/0.838/0.873 vs 0.778/0.840/0.875) at 0.205 s+ mean latency instead of 20.2 s — in that run the hosted mean sat on the+ server's 20 s completion timeout, which made the reranker stall every+ query before falling back. (#873)+ - MCP tool calls from OpenCode 2 (2.0.4+) are routed by the native session id+ the client sends in `params._meta["ai.opencode/sessionID"]`, ahead of the+ `Mcp-Session-Id` transport header, which OpenCode shares across every+ session in a directory. Concurrent OpenCode sessions in different projects+ no longer read each other's active project; explicit `workspace`/`project`+ arguments still win and `X-Memory-Actor-Session-Id` keeps precedence. (#864)+ - OpenCode 2 turn checkpoints: every completed root turn+ (`session.execution.succeeded`, `.failed` or `.interrupted`, OpenCode+ 2.0.10+) now refreshes `sessions/<id>.md` and the session's automatic+ handoff without ending the native session, because OpenCode 2's shared+ service outlives the CLI and closing a terminal is not a session end. The+ checkpoint is deterministic (no LLM call), is written in the session's own+ scope, keeps one open baton per live session (refreshed in place, audited as+ `refresh_handoff`), and never touches a session that already ended. Child+ sessions neither claim startup context nor publish batons. (#865)+ - `docs/llm-providers.md` now has a dedicated OpenRouter subsection and a+ matching row in the recommended-defaults table. The wiring+ (`openai-compat` + `AI_MEMORY_LLM_BASE_URL=https://openrouter.ai/api/v1`)+ and the `HTTP-Referer` / `X-Title` app-attribution headers were already+ shipped, and `docker/.env.production.example` already ships an OpenRouter+ default, but the provider-facing doc mentioned OpenRouter only inside the+ generic `openai-compat` row. The new subsection covers a full working+ env-file, the `openai-compat` embedder path (with a note to verify any+ provider's `/v1/embeddings` endpoint before relying on it), a pointer to+ `docs/llm-provider-comparison.md` for model selection, and a security /+ gotchas block (auth-token requirement for non-loopback binds, env-file+ hygiene, cheap-model consolidation drift, `:free`-tier shared-pool+ limits, reasoning-model incompatibility). (#949)+ - `docs/backup.md` documents the remote-git-mirror backup pattern for a+ single-user install: what to include, what to exclude (derived SQLite index,+ models cache, logs, secrets), how to schedule with a `systemd --user` timer,+ how to restore, and the security posture per `SECURITY.md`, including a+ "what ends up in your wiki" section that names the exposure (sanitized+ prompts, tool I/O, page bodies) and lists encrypted-archive alternatives+ (`age`, `restic`, `borg`, `git-crypt`) for cases where a private mirror+ repo is not enough. A worked example ships under `docs/examples/backup/`+ (snapshot script, `.service` and `.timer` unit files, `.gitignore` for+ the mirror repo). Pointers added from `docs/deploy.md#backups`,+ `docs/airgapped-install.md`, and the README docs table. The on-box+ `ai-memory backup --to <tarball>` command+ (`docs/lifecycle-ops.md#backup`) is unchanged. (#950)+ - `memory_handoff_accept` returns a `status` next to `handoff`: `claimed` when+ the call took the handoff, `consumed_by_hook` when the calling session's own+ SessionStart already claimed it (so it is in that session's context), and+ `none_pending` when nothing is left to claim. A bare `{"handoff": null}` used+ to cover both of the last two. `consumed_by_hook` needs the session id the+ hook claimed under, which Claude Code's `install-mcp --session-aware` bridge+ and OpenCode 2 forward; the answer stays inside the caller's project and+ handoff ownership, so a forwarded id cannot report another operator's or+ another session's claim. The `handoff` field is unchanged. (#988, #920)++ - Hook capture can be routed to a different ai-memory server per repository.+ `ai-memory server add|list|remove` registers named server profiles locally,+ in `<data_dir>/servers.toml`, with each token in its own owner-only file+ under `<data_dir>/auth-tokens/`. A repository's `.ai-memory.toml` then+ selects one with `server = "<name>"`. The marker carries only the name,+ never a URL or token. When several profiles are registered, each must+ declare `--root` directories, and a marker outside them cannot select it.+ An unknown, tokenless, out-of-roots or unrooted profile, or a malformed+ `servers.toml`, makes the hook emit nothing, never fall back to the install+ default.+ - Native hooks route the spooled event, the session-start handoff fetch,+ later drains and the one-time boot backfill.+ - Generated TypeScript integrations and the `.sh`/`.ps1` script hooks+ cannot route yet, so they drop a routed repository's events and handoff+ fetch.+ - Clients older than this release ignore the key, so upgrade every client+ before adding `server` to a shared marker.+ - Re-running `server add` keeps a profile's roots when `--root` is omitted,+ and changing its URL without a new token discards the old token.+ - `uninstall` removes the stored profile tokens together with the hook+ token; the registry of URLs stays.+ - `hook --check-capture` reports `server_profile` and `server_resolution`.++ See `docs/marker-file.md`. (#992)+++ ### Changed+ - `ai-memory purge-session` without `--confirm` now previews what a confirmed+ purge would delete before refusing, the same way `purge-project` does (#945):+ `Would purge session from <ws>/<proj>: N observations, N handoffs, N pages,+ N auto-improve runs.` (the session id itself is never printed). The server+ takes a new `dry_run` field on `POST /admin/purge-session` that always wins+ over `confirm`. It only counts; no delete, wiki file removal, webhook,+ audit row or checkpoint runs. `POST /admin/purge-session`'s confirmed+ report also gains two new fields, always present on both the preview and+ the confirmed response: `collateral_observations_deleted` and+ `collateral_handoffs_denulled`, counting what the purge cascades into+ *other* projects through this session's own id. The CLI still exits+ non-zero without `--confirm`; against an older server, or if the preview+ times out, it prints only the existing refusal. (#957)+ - `POST /admin/delete-workspace` takes a `dry_run` field that always wins+ over `force` and previews what a confirmed delete would remove, with the+ same 404/409 a confirmed delete gives. It only counts: no admission call,+ directory removal, mirror dispatch or checkpoint. The preview and the+ confirmed response now also report `sessions_deleted`,+ `observations_deleted`, `handoffs_deleted` and `embeddings_deleted`+ (previously only projects, pages, workstreams and managed runs), plus+ `collateral_observations_deleted` and `collateral_handoffs_denulled` for+ rows in *other* workspaces reached through this workspace's sessions.+ `merge-workspace` is unaffected. There is no CLI subcommand, so this is+ HTTP-only. (#963)+ - Captures from a checkout with no declared `project` and a git remote now route+ by the repository's identity — the normalised `upstream` remote, else `origin`+ — instead of the folder name (`projects.identity`, V70). Two unrelated+ repositories sharing a folder name now get two projects (the second named+ after its owner, e.g. `orgb-api`); one repository cloned into differently+ named folders converges on one project, the first to claim the identity —+ an existing second project keeps its history but stops receiving captures.+ Existing projects are claimed in place, so upgrading moves no memory, and a+ user who may not write to a project cannot claim its identity. Checkouts+ that declare `project` in their marker route by name exactly as before. Every+ hook client (native, shell, PowerShell, TypeScript) resolves the identity+ host-side and sends it as `identity` / `identity_src`; credentials in a remote+ URL never leave the machine. (#708)+ - Grok Build CLI shows a pending handoff, and an opted-in `[briefing]`, as+ `PostToolUse` `additionalContext` on the first tool of a session.+ `SessionStart` and `UserPromptSubmit` still do not accept the handoff (Grok+ discards that stdout); a session that never calls a tool leaves the handoff+ open for `memory_handoff_accept`. The note is clipped to 10,000 characters+ (Grok's own cap). Because Grok reuses one session id across a+ SessionEnd→restart, `memory_handoff_accept` now reopens an already-ended+ receiver session (clears `ended_at`) instead of rejecting it — but only for+ agents that reuse their session id across a restart (Grok); for every other+ agent an ended session stays final, so a lifecycle-only receiver still cannot+ reclaim after it released and ended. The reopen also only happens after the+ exactly-once claim guard, so a session that already took a baton still cannot+ take another (the multi-session claim-once invariant is preserved).+ Delivery of this PostToolUse handoff is exempt from `AI_MEMORY_CAPTURE_OWNER`+ capture suppression, like the other context-delivery events. (#840)+ - The generated OpenCode 2 plugin binds to the OpenCode 2.0.10+ event and hook+ API (`session.execution.*`, `session.text.ended`, `session.moved`, the+ `context` hook). Startup context is claimed once per root session and+ retained on every later model request; content-only tool results are+ captured; each location instance owns its own queue, spool state and+ cleanup; an explicit `session.moved` rebinds the live session to its new+ directory so its later end lands there. Checked against OpenCode 2.0.14. (#865)+ - Quieted the default server log: the reconciliation-pass summary that fired+ every 30 s regardless of activity dropped from `info` to `debug`, and the+ default log filter now pins the external `rmcp` MCP SDK to `warn` (its+ per-request lifecycle logging at `info` was the other half of a near-empty+ server's log). Both are restorable through `log_level` (e.g.+ `"info,rmcp=info"` or `"debug"`) or `RUST_LOG`; the `tracing_appender=warn`+ feedback-loop guard stays non-overridable. (#894)++ - Documented Cheaper Inference as an endpoint for the existing `openai-compat`+ provider. (#981)++++ - Documented API Route as an endpoint for the existing `openai-compat`+ provider. (#997)+++ ### Fixed+ - A Kiro v3 resume that falls back to the default session store drops+ `KIRO_HOME` from the child, but auto-wire still installed hooks and MCP+ under `KIRO_HOME`; it now wires the default home that resume reads. (#820)+ - Native `ai-memory upgrade` no longer refuses every Linux install by probing+ the running executable for write (Linux `ETXTBSY`); it only requires the+ parent directory to be writable for rename-based replace. (#802)+ - Parallel OpenCode 2 sessions in one directory no longer receive each+ other's context. Each completed turn's checkpoint retired the automatic+ handoffs of every other live session there, and the next session to start+ was handed the handoff of a session still in use (mid-turn, or seconds after+ its last turn). A checkpoint now spares other live sessions' handoffs; a+ starting session receives a live session's handoff only once that session+ has captured nothing for ten minutes, re-checked inside the claim; and the+ claim retires older handoffs of quiet sessions but not of one in use.+ (#883)+ - `memory_query`'s vector stream called the generic `Embedder::embed`+ instead of `embed_query` on the configured embedder, so a+ query/document-asymmetric embedder (Google's task-typed embeddings, or+ the new query/document prefixes above) embedded the search query on the+ document side instead of the query side. Indexed writes are unchanged;+ only the query-side helper moves onto the query task. (#859, #861)+ - A manual `memory_consolidate` now reconciles the session's durable+ consolidation job row. The MCP handler wrote the page directly through the+ consolidator without touching `session_consolidation_jobs`, so a session+ whose automatic SessionEnd job had reached the terminal `failed` state (that+ the worker never re-claims) kept showing `failed` even though the operator+ had just consolidated it. After a successful, non-dry consolidate the handler+ flips a `failed`/`pending`/`superseded` row for the session to `completed`; a+ live `running` lease is never touched, so a concurrent automatic worker+ attempt is left to settle its own row. (#890)+ - Tool-family labels no longer leak into automatic handoffs and session-page+ titles, and the file-activity handoff warning fires again. Every closed-tool+ agent stores a call's title as `tool file` / `tool non-file` / … (a partition+ of the calls, not a tool name); these were surfacing verbatim as `Tools used:+ tool file, tool non-file` in handoffs and, for a session whose only non-prompt+ observation was such a call, as the page title. The same spelling meant the+ "session ended without a normal stop while working with files" heuristic —+ which only matched the bare `file` spelling of the minority reserved-protocol+ path — never fired for a real session. A shared recognizer now maps both+ spellings, drops the labels from the handoff tool list and the title fallback,+ and drives the file-activity warning from either. (#895)+ - Generated rule slugs (`_rules/<slug>.md`) now fold Latin diacritics to ASCII+ instead of turning each accented letter into a hyphen: `estável` slugs as+ `estavel` (was `est-vel`) and `retenção` as `retencao` (was `reten-o`). Long+ titles are also truncated at a word boundary (the last hyphen inside the+ 60-char budget) rather than mid-word. Uses the icu_normalizer NFD+ decomposition ai-memory-core already depends on; no new dependency. (#886)+ - Multi-page consolidation now stores page paths with a `.md` extension.+ The LLM returns a bare path for a non-rule page (`decisions/smart-model-luna`),+ and the shared path sanitizer passed it through verbatim, so the page landed+ extensionless and read back as a non-portable wiki path. The sanitizer now+ appends `.md` to the filename component when it is missing (idempotent,+ case-insensitive), fixing the non-rule consolidation, bootstrap, and+ auto-improve front doors at once. (#885)+ - `ai-memory run`'s auto-wire no longer overwrites an installed session-aware+ Claude Code MCP bridge with the static HTTP registration. The auto-wire+ sentinel is keyed by client version, so the MCP step re-ran on every upgrade+ and replaced the `ai-memory` entry wholesale; a user who had run `install-mcp+ --client claude-code --session-aware` lost the bridge on the next `ai-memory+ run` after an upgrade, silently disabling `[auto_scope] per_session` for their+ MCP calls. Auto-wire now detects an existing session-aware bridge and keeps+ it. (#888)+ - On Windows, OpenCode 1 and 2 sessions are found again from their checkout:+ OpenCode records a session's directory with forward slashes+ (`C:/Users/me/repo`), so matching only the backslash checkout path found+ none. `ai-memory doctor` reported `0 local` for OpenCode while it captured+ sessions there, and `ai-memory run` / `show` could neither discover nor list+ a native OpenCode session to resume. (#882)+ - Grok Build CLI hooks capture on Windows again. Grok evaluates+ `~/.grok/hooks/*.json` commands with PowerShell, as Codex does (#515), so+ the double-quoted executable path in command position parsed as a string+ expression and every hook exited 1 with a ParserError: sessions ran with+ the hook installed and nothing was captured. The Windows command now+ carries PowerShell's `&` call operator for Grok too; re-run+ `ai-memory install-hooks --agent grok --apply` to rewrite an existing+ install. (#887)+ - The Linux/macOS Docker wrapper now keeps its native host client in+ `${XDG_DATA_HOME:-~/.local/share}/ai-memory/native-runner` instead of+ `~/.cache/ai-memory/native-runner`. `ai-memory run` auto-wires hooks whose+ command is that client's path (Claude Code, Codex, Kimi Code, Command Code,+ Kiro CLI v3, Grok, Antigravity CLI), so flushing `~/.cache` left every hook of+ those harnesses pointing at a missing binary. The wrapper also keeps the+ release's `hooks/` bundle beside the client, so auto-wire no longer fails+ with "could not locate hooks directory" for script-based harnesses on a host+ where `install-hooks` never ran. (#874)+ - Fixed pre-push installation from linked worktrees and preserved the managed+ block's position during reinstallation. Configured `core.hooksPath` overrides+ and ambiguous markers are rejected without replacing the existing hook. The+ block now keeps its shell options and `SSL_CERT_FILE` inside its subshell and+ propagates a failure explicitly, so user hook commands after it keep their+ own semantics and a failing test run still blocks the push. (#824)+ - A Windows service running as `LocalSystem` over a user-owned data+ directory no longer breaks the wiki git history silently. libgit2's+ dubious-ownership guard (CVE-2022-24765) fails every wiki commit with+ `code=Owner` when the process account does not own the repository, but+ the failure was WARN-only, so capture and search kept working while no+ wiki checkpoint was ever committed. The startup baseline checkpoint now+ surfaces an owner-check failure at ERROR with the remedy (run the+ service as the owning user), and `docs/windows.md` Scenario E documents+ running the service under a `<serviceaccount>`, corrects the claim that+ only the data directory is account-sensitive, and notes the WinSW+ error-1069 / stale-password gotcha for Microsoft-account / PIN / Hello+ users. The owner check itself is deliberately left enabled. (#872)+ - A Windows folder no longer splits into two projects. The hook router+ derived a project's *name* from the cwd after+ `normalize_project_path_key` had ASCII-lowercased the whole+ drive-letter/UNC path — basename included — so a session in+ `D:\...\Default Project` was captured under `default project` while the+ CLI (which keeps the raw basename) used `Default Project`. Because+ `get_or_create_project` matches names case-sensitively, one folder+ minted two projects. The router now takes the name from the raw cwd; the+ cache key and cwd-prefix match keep the case-folded path, so #806 handoff+ stickiness is unaffected. (#871)+ - Auto-improve review no longer stages a proposal whose LLM-produced page+ path contains a Windows-illegal character (e.g. a `:` copied from a+ conventional-commit subject). That path passed the deliberately tolerant+ `PagePath::new` and only failed later at `ensure_portable` when the+ proposal was approved, so the learning loop queued work that could not+ be applied. Paths are now sanitized the same way bootstrap (#847) and+ per-session consolidation (#848) already sanitize theirs, before+ validation; a path that is still unportable after sanitizing is rejected+ instead of staged. (#850)+ - Omitted `temperature` for `gpt-6-*` models in the `codex`,+ `openai-oauth`, `copilot` and `openai` providers. Codex answered GPT-6+ requests that carried `temperature` with `400 Unsupported parameter:+ temperature`, which broke consolidation, lint and bootstrap on a+ provider or fallback configured with `gpt-6-luna`, `gpt-6-sol` or+ `gpt-6-astra`. The `openai` provider now also sends+ `max_completion_tokens` for GPT-6 and no longer applies its local+ 16,384-token cap to it, matching `gpt-5*`. (#851)+ - `memory_message_pop` and `memory_message_list` no longer return a silent+ empty result when the inbox scope was *inferred* rather than named. A caller+ with no explicit `workspace`/`project` and no forwarded hook-session id+ resolves the shared active-project slot (whichever project published last),+ so two same-operator agents can have a no-scope pop land on a different inbox+ than the on-start notice / `memory_briefing` counted — "you have mail"+ followed by an empty fetch, with no way to tell it was the wrong inbox. An+ empty read from an inferred scope now reports the `resolved_scope`+ (workspace + project), the `scope_source`, and a hint to re-run with explicit+ scope; an explicitly-scoped or session-bound empty read is unchanged. No+ message is lost — the mis-scoped pop consumes nothing. (#854)+ - `companions/ai-memory-macos/build.sh` no longer fails on machines whose+ active developer directory is Command Line Tools only: SwiftUI `@State`+ needs the `SwiftUIMacros` plugin shipped with full Xcode, so the script+ now exports `DEVELOPER_DIR` to Xcode (or a caller-set path) before+ `swift build`, with a clear error when no macOS platform is present. (#849)+ - `ai-memory serve` no longer leaked file descriptors from half-open HTTP+ connections until `EMFILE`, breaking the healthcheck (an unauthenticated+ availability/DoS). A hook or MCP client whose peer died without sending FIN+ (laptop sleep, a VPN/Tailscale flap, an abrupt kill) left its accepted+ socket `ESTABLISHED` forever, since the OS default has TCP keepalive off —+ each dead peer leaked one fd, exhausting the 1024-fd default in roughly 2-3+ days of normal churn. Accepted connections now get TCP keepalive via+ `socket2`, tunable with the new `tcp_keepalive_secs` config key (default+ 60s; `AI_MEMORY_TCP_KEEPALIVE_SECS=0` disables keepalive). This closes the+ half-open-socket half of the fd leak; the rmcp session-table half was+ already fixed in 2.4.0 by the rmcp 2.x bump. (#792)+ - The Windows release checksum (`ai-memory-windows-x86_64.zip.sha256`) is now+ written with a LF terminator instead of CRLF. `Out-File`'s Windows line+ ending made `sha256sum -c` fail with `No such file or directory` — the CR+ is read as part of the filename — on the WSL2 and Git Bash paths where that+ is the natural command, and placed a stray byte in the release body's+ checksum block, which concatenates every platform's file. The zip's smoke+ test now requires LF rather than tolerating either, so the format the+ release claims is the format it ships. (#838)+ - `purge-session` now removes every page version the session owns at+ `sessions/<id>.md` (including versions written before OKF sources existed+ and summaries of sessions that never recorded a summary pointer), while a+ manual page at the same path survives. (#862)+ - Shell hooks no longer pin a CPU core for minutes on a large payload. The+ `hooks/_lib.sh` extractors for `cwd`/`workspacePaths`/`workspace_roots`,+ the session id, and Antigravity's `invocationNum` located each key with+ `${payload#*"key"}`, which is quadratic in the payload size under dash and+ bash: a 200 KB Cursor `postToolUse` event spent minutes in+ `ai_memory_extract_cwd`, and concurrent hooks stayed at 100% CPU before+ ever reaching the POST. A shared `ai_memory_after_key` helper now finds the+ first occurrence with one linear `awk` pass (about 50 ms at 200 KB) and+ feeds the unchanged `sed` parsing, so the extracted values are the same as+ before. (#870)+ - The generated TypeScript integrations (OpenCode 1 and 2, OMP, Pi,+ OpenClaw) no longer flash a console window on Windows for every captured+ event: their `git` lookups set `windowsHide`. The repo-root project lookup+ behind those spawns is memoized per cwd instead of running two synchronous+ `git` processes on every event. (#863)+ - A `SessionEnd` whose resolved scope drifted from its session (a+ `.ai-memory.toml` appeared under the running session) was refused as a+ foreign-scope end and stranded the session open forever. It now ends the+ session when owner and agent match and the event comes from the session's+ own (normalized) cwd; a different cwd, operator or agent is still refused. (#865)+ - Shell hooks on macOS no longer corrupt non-ASCII characters in the query+ string. `/bin/sh` there is bash 3.2, which sign-extends bytes >= 0x80, so+ `ai_memory_url_encode` sent `é` as `%FFFFFFFFFFFFFFC3%FFFFFFFFFFFFFFA9`+ instead of `%C3%A9`. An accented cwd reached the server as a different+ path, and Cursor events and the session-start handoff lookup both use the+ query `cwd`. (#877)+ - `memory_query` now returns `global_scope_hits` (standing `_global` user/team+ preferences) for a single-project query whose project is named explicitly+ with `workspace`+`project`, not only when scope is omitted. The routing+ doctrine tells static MCP clients to pass `workspace`+`project` on every call,+ which set the old gate's "no named scope" condition to false, so those clients+ never received global preferences despite the documented contract. The union+ now keys on single-project resolution (`scopes` empty); only an explicit+ multi-`scopes` set opts out, and `global=true`/`as_of` are unaffected. The+ reserved-scope union is still keyed strictly to `_global` and never leaks+ another project's pages. (#930)+ - A page file rewritten under `wiki/<ws>/<project>/` (the OKF import path)+ now gets its new version embedded the same way a brand-new file does.+ The watcher's `reindex_page` upserted the new version and stopped —+ embedding only ever ran on the `write_page` API path — so a rewrite left+ hybrid search silently degraded to FTS-only ranking for that page until+ someone ran `ai-memory embed` by hand. (#958)+ - `[capture] ignore_paths` now covers shell commands. Shell tools (`Bash`,+ `shell`, `execute_bash`, `terminal`, …) were classified as non-file and always+ kept, so `cat docs/adr/*.md` stored the ignored file's full text in the+ observation body. The native `ai-memory hook` now splits the command line+ lexically and drops the event when an argument, resolved from the event's+ `cwd`, matches an ignored pattern or is a glob that can reach one. Variables,+ command substitution and commands that name no path are not followed. The+ marker-file reference also documents excluding large tool results that Claude+ Code saves and re-reads from `~/.claude/projects/**/tool-results/**`. (#946)+ - The generated OpenCode, OMP, Pi and OpenClaw integrations now apply the same+ lexical shell-command `ignore_paths` matching as the native hook, so a `bash`+ call such as `cat docs/adr/0001.md` is dropped there too instead of being+ captured. Both matchers now also recognize OpenClaw's and Devin's `exec` shell+ tool, resolve relative arguments from a shell tool's `workdir` (OpenCode+ `bash`, OpenClaw `exec`, Codex `shell`) instead of the event cwd, and treat+ `dir/**` as covering `dir` itself when `dir` holds a glob (`docs/a?r/**`), as+ the generated plugins already did. Refresh or reinstall generated plugins to+ pick it up. (#948)+ - Grok Build CLI tool observations are no longer stored with an empty body.+ Grok posts Claude Code's snake_case tool fields (`tool_name` / `tool_input` /+ `tool_use_id`), but it was missing from both `closed_tool_agent` and the+ tool-metadata agent match, so every `PostToolUse` body extraction returned+ nothing while the observation itself was still captured. Grok now shares the+ Claude Code tool mapping, so tool family, outcome and output land in the+ body. (#931)+ - `ai-memory bootstrap` on a repository small enough for one chunk no longer+ asks the provider for 64K output tokens. The output cap was keyed on the+ number of chunks, so the only chunk of a small repo got the one-shot cap+ meant for `--chunk-input-tokens 0`, and every such run failed on a+ 64K-context model. Under chunking (the default) every call now asks for up+ to 16K; only `--chunk-input-tokens 0` keeps 64K. The `--max-input-tokens`+ help no longer claims its 150K default leaves room for 64K of output in a+ 200K window. (#928)+ - `ai-memory bootstrap` now leaves headroom for its own token estimate. It+ counts bytes ÷ 4, which undercounts non-English text and source code (about+ 40% on Portuguese mixed with code, as measured for consolidation), and it+ filled `--max-input-tokens` and `--chunk-input-tokens` to the last estimated+ token, so a chunk sized to fit a model's window could overflow it on input+ alone. Prunes and chunks now fill 80% of each budget by the estimate, the+ same default consolidation uses; a run may plan more chunks than before.+ (#937)+ - The `bootstrap.md` manifest no longer shows bare `---` separators when a+ chunk returns no rationale. Empty rationales are dropped before the+ per-chunk ones are joined, and a run where no chunk returned one says so.+ (#939)+ - Multi-page consolidation (`memory_consolidate` with `multi_page=true`) no+ longer overwrites a pinned page. The batch's page paths are chosen by the+ model, and an update that named an existing pinned page replaced its body+ and wrote the new version unpinned, despite pinned pages being documented as+ immutable to automation. Such updates are now skipped with a warning; the+ rest of the batch is written. `_slots/` pages, which are pinned+ automatically, keep their state/invariant rules. (#934)+ - Session consolidation no longer writes a page title that already exists+ in the project. A colliding session title gets a deterministic+ `(session <8-char-id>)` suffix (stable for the same session, distinct+ across sessions) and a matching leading H1 is retitled with it. The+ consolidator prompt tells the model to name THIS session rather than a+ generic harness-run phrase and not to reuse listed titles; that wording+ is compact enough that the advertised 6000-token input floor still+ projects observation bodies instead of dropping them. (#926)+ - The web page view now links a `[[wikilink]]` on a line indented four+ spaces that is not code. A nested list item written with four spaces+ (`- Decisions:` then ` - see [[decisions/auth]]`) or a paragraph's+ continuation line showed the wikilink as literal text, although the+ engine indexed it and listed the page in the target's backlinks. The+ preprocessor now skips exactly the code blocks and inline code the+ renderer's parser reads as code. (#955)++ - `observations.title` is now sanitized before it is truncated, not after.+ `title_hint` used to be cut to 80 chars in `ai-memory-hooks::payload`+ *before* the sanitizer ever ran, so a secret straddling that cutoff was+ often left as a fragment too short to match a built-in or `[sanitize]+ extra_patterns` rule — landing in the title, its FTS index, and every+ surface that renders titles (session pages, briefings, handoffs, search)+ unredacted, even though the same observation's body was correctly scrubbed+ first. `title_hint` extraction now keeps the full first line untruncated;+ `Sanitized::new` scrubs the title and only then applies the 80-char display+ cap (`ai_memory_core::sanitize::truncate_for_title`), mirroring the order+ the body already used. (#982)+ - The `/web` page view keeps a leading H1 that is not the page title. It+ dropped the body's first H1 whatever it said, as a duplicate of the title+ in the header, but a frontmatter `title:` outranks the H1 and a setext H1+ never names the page, so a heading like `# Token refresh after sleep`+ under `title: Auth decisions` vanished from the rendered page. An H1 that+ repeats the title is still dropped. (#967)+ - Shell-command `ignore_paths` matching no longer joins an argument vector+ before splitting it, which broke a path with spaces (`["cat", "private+ notes/x.md"]`) apart and let one element's stray quote hide the elements+ after it; each element now counts whole and is split on its own. An invalid+ `.ai-memory.toml` now makes a shell command metadata-only, like a file tool,+ instead of keeping its command and output, including one whose command is+ missing or unparseable (`web_search` runs nothing and is still kept), and the+ server now does the same when it cannot parse the client's capture marker. A+ long `bash -lc "<script>"` element is read only as words, not also as one+ path, so it can no longer exhaust the match budget and drop an innocuous+ event. Applies to the native hook and the generated plugins; the server+ accepts the new metadata-only shell form, so upgrade it together with them+ (an older server drops such an event). (#973)+ - `ai-memory-importer omc-wiki` now reads the frontmatter of a page saved+ with CRLF line endings or a UTF-8 BOM, as a wiki checked out on Windows+ with `core.autocrlf=true` is. It missed the fence, so the page's kind,+ tier, tags and pin were dropped and the YAML block was imported as the+ top of the body; the fence check now matches the wiki's own parser.+ (#970)+ - `ai-memory serve --web-ui-dir` no longer panics at startup when the+ custom SPA's `index.html` starts with a UTF-8 BOM, or has any other+ non-ASCII text before `<head>`. The `<base href>` injection scanned the+ page a byte at a time and sliced inside the multi-byte character+ ("byte index 1 is not a char boundary"); it now steps a whole+ character. (#969)+ - The `/api/v1` single-page route's `ETag` now covers the whole JSON it+ returns. It hashed only the markdown body and author, so pinning a page,+ a frontmatter edit, or a new backlink changed the response without+ changing the tag, and a client revalidating with `If-None-Match` got+ `304` and kept the stale page. (#971)+ - A wikilink or markdown link written inside an inline code span is no+ longer indexed as a link. The engine skipped only fenced blocks, so a+ page showing the syntax as code (`` `[[other-project:notes/x]]` ``) got a+ lint `broken_link` finding for a dependency it does not have, and a+ local example listed the page in the target's backlinks, while the web+ page rendered neither as a link. A link whose label is code+ (`` [`foo`](foo.md) ``) is still indexed. (#968)+ - `export-okf`'s generated `index.md` no longer has a prose sentence outside+ its list structure. Some strict OKF v0.2 validators read §11.3 as+ rejecting it. (#979)+- `install-hooks --apply --as-user <user> --auth-token <key>` no longer failswith `--as-user '<user>' requires --auth-token` when the token was supplied.The guard was handed the *rendered* credential, which is deliberately `None`diff --cc README.mdindex aea767c0,7326c1df..b7093e76--- a/README.md+++ b/README.md@@@ -346,63 -364,11 +364,65 @@@ Auto-wiring is on by default; opt out w`ai-memory run`).`ai-memory uninstall --apply` removes everything ai-memory installed,- and only what it installed. Install commands are idempotent and write+ and only what it installed. It also clears `ai-memory run`'s auto-wire+ record, so the next managed launch wires that harness again; to keep it+ unwired, launch with `--no-autowire` or set `AI_MEMORY_RUN_AUTOWIRE=false`. Install commands are idempotent and writetimestamped backups next to any file they touch.+### NixOS++This flake ships a NixOS module (`nixosModules.default`) with a+`systemd.services.ai-memory` unit. Isolation matches the packaged FHS unit:+a dedicated `ai-memory` system user (`nologin`, no linger) plus the same+systemd sandbox (`ProtectSystem = "strict"`, empty capability sets,+`MemoryDenyWriteExecute`, `RestrictAddressFamilies`, and the rest — see+[`nix/systemd-sandbox.nix`](nix/systemd-sandbox.nix)).++```nix+{+ inputs.ai-memory.url = "github:akitaonrails/ai-memory";++ outputs = { nixpkgs, ai-memory, ... }: {+ nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {+ system = "x86_64-linux";+ modules = [+ ai-memory.nixosModules.default+ {+ services.ai-memory = {+ enable = true;+ # enableWeb = true; # off by default — the web UI is opt-in+ settings = {+ allowed_hosts = [ "localhost" "127.0.0.1" "::1" "homelab.example" ];+ log_level = "info";+ };+ # Loopback (default): secrets optional; missing env file is tolerated.+ # Non-loopback: set one of ageSecret, sopsSecret, or environmentFile.+ # ageSecret = "ai-memory-env"; # config.age.secrets.<name> (agenix)+ # sopsSecret = "ai-memory/env"; # config.sops.secrets.<name> (sops-nix)+ };+ }+ ];+ };+ };+}+```++Declarative non-secret config lives in `services.ai-memory.settings` (typed+options mirroring `config.toml`, plus `freeformType` for forward-compat keys).+The module renders a generated TOML file and passes `--config`. Top-level+`bind`, `port`, and `enableWeb` win over duplicate settings keys.++Secrets such as `AI_MEMORY_AUTH_TOKEN` never go in `settings` or the Nix+store. Use `ageSecret` / `sopsSecret` (consume `config.age` / `config.sops`+when the host imports agenix or sops-nix) or `environmentFile` as an escape+hatch. Non-loopback binds require one of those sources; loopback may omit+them and tolerates a missing env file (systemd `EnvironmentFile=-…`). Put TLS+in front of a LAN/WAN bind — see [`docs/https-via-proxy.md`](docs/https-via-proxy.md).++All options and defaults are in [`nix/nixos-module.nix`](nix/nixos-module.nix).+Entirely opt-in — `nix build`, `nix run`, `nix develop`, and the CLI are+unchanged if you don't import it.+## Everyday useDay to day, you mostly do not think about ai-memory. Hooks capturediff --cc docs/install.mdindex e0818f71,2362caee..e330b764--- a/docs/install.md+++ b/docs/install.md@@@ -7,10 -7,10 +7,12 @@@ page covers everything else- [Server on a different machine](#server-on-a-different-machine)(homelab, LAN box, remote server)- [Configuring the CLI URL and auth](#configuring-the-cli-url-and-auth)+ - [Fedora native package (RPM)](#fedora-rpm)+ (systemd system service or user service)- [Arch Linux native packages (AUR)](#arch-linux-native-packages-aur)(systemd system service or user service)+- [Nix / NixOS](#nix--nixos)+ (flake package, NixOS module, maintainer test ladder)- [macOS menu bar app](#macos-menu-bar-app)(self-contained `.app` + LaunchAgent)- [Configuring other agent CLIs](#configuring-other-agent-clis)