Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
ci: reject duplicate CHANGELOG section headings
AkitaOnRails4c87a32fdaa0
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex c6c6e629..88c5da1b 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -145,6 +145,17 @@ jobs:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1- run: scripts/check-native-packaging.sh+ # `bin/release` copies `## [Unreleased]` into the new version section+ # verbatim, so a repeated `### ` heading there ships release notes with the+ # entries split across two identical headings. Valid Markdown, invisible in+ # review, and it has happened repeatedly.+ changelog:+ name: changelog sections+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ - run: scripts/check-changelog-sections.sh+# End-to-end docker smoke: packages the release-build binary and confirms# the image runs. Catches Dockerfile drift (missing COPY, bad ENTRYPOINT)# before it lands in production without recompiling Rust in Docker.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 330e9066..2173dcd6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,8 +15,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0very duplicate-load the split exists to prevent, since each agent loadsevery `*.ts` in its extensions directory. Documented `--profile` /`OMP_PROFILE` and the `PI_CODING_AGENT_DIR` precedence alongside them.+- The lint `stale` threshold is now derived from the operator's `[decay]+ lambda` instead of a hard-coded 30 days (#426). The rule only fires on+ episodic pages with zero accesses, and for those the decay score reduces+ exactly to `salience * exp(-lambda * age)` — the reinforcement term carries+ `ln(1 + access_count)`, which is zero — so the lint was already measuring+ decay, just against a constant rather than against `lambda`. Slowing decay+ made the two diverge: at `lambda = 0.008` real eviction lands near day 201+ while the lint still called a page stale on day 31, and because a report+ page is written whenever any finding exists, one page nobody intended to+ read produced a new `_lint/<date>.md` every day, forever. The threshold is+ now `0.6 / lambda`, which is **exactly 30 days at the default+ `lambda = 0.02`** — unchanged for anyone who never tuned decay — and 75+ days at `0.008`. An invalid or non-positive lambda falls back to the+ historical constant rather than silencing the rule.+- `bin/deploy` now refuses to push a single-architecture build over a tag that+ already resolves to a multi-architecture manifest (#427). It builds for the+ architecture of the machine it runs on, so deploying a homelab from an x86+ workstation to `IMAGE=akitaonrails/ai-memory:latest` replaced the+ amd64+arm64 manifest CI had published with an amd64-only image, and every+ arm64 host pulling `:latest` failed with `exec format error`. The shipped+ `bin/deploy.env.example` also defaulted `IMAGE` to `:latest`, so following+ the documented setup led straight into it; it now defaults to a private+ `:homelab` tag and explains that release tags are published by CI only.+- `install-hooks` now writes agent-distinct extension filenames+ (`ai-memory-pi.ts`, `ai-memory-omp.ts`) instead of both agents sharing+ `ai-memory.ts`, so a Pi install and an OMP install no longer overwrite each+ other when `PI_CODING_AGENT_DIR` points them at one home. A superseded+ `ai-memory.ts` is removed only when it carries this tool's generated marker+ *for that same agent* — a file you wrote yourself, or the other agent's, is+ left alone and reported. OMP profiles are supported via `--profile` or+ `OMP_PROFILE`; `PI_CODING_AGENT_DIR` takes precedence over a profile, since+ it names the agent directory outright.++ Note distinct filenames stop the overwrite but do **not** make a shared+ directory safe: each agent loads every `*.ts` it finds there, so installing+ both into one home captures every event twice, once per agent identity.+ That collision is upstream — both agents read the same environment+ variable — so `install-hooks` now warns when it detects one and points at+ the two ways out. (#421)+- `install-hooks --agent pi`, `--agent omp`, and `uninstall` now honor+ `PI_CODING_AGENT_DIR`, instead of always writing to `~/.pi/agent/extensions/`+ and `~/.omp/agent/extensions/`. Both agents relocate their whole agent+ config home (`~/.pi/agent` / `~/.omp/agent`) through that variable, so on an+ install with it set the extensions landed where the agent never loads them:+ the install reported success and capture silently did nothing. ai-memory+ already honored the variable when resolving Pi/OMP transcripts, so the two+ halves of one install disagreed about where that home was. Installs without+ `PI_CODING_AGENT_DIR` set are unaffected. The manual (non-`--apply`)+ instructions now name the resolved path too, instead of always printing the+ `~/.pi/agent` / `~/.omp/agent` default. (#411)### Added+- CI now rejects a CHANGELOG version section that repeats a `### ` heading+ (`scripts/check-changelog-sections.sh`). `bin/release` copies+ `[Unreleased]` into the new version verbatim, so a duplicated heading ships+ release notes with the entries split across two identical headings — valid+ Markdown, invisible in review. The same defect was found in four already+ released sections (1.19.0, 1.13.0, 1.4.0, 1.1.1) and folded in the same+ commit; no entry text was changed.- New `llm_timeout_secs` config key (env `AI_MEMORY_LLM_TIMEOUT_SECS`, or`llm_timeout_secs = 900` in config.toml) overrides the per-request timeoutevery chat provider applies to its HTTP calls — previously hardcoded at@@ -73,58 +130,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0the working tree; and a mid-task exit (Stop without SessionEnd) is flaggedso the receiver knows the previous session did not finish cleanly. (#425)-### Fixed-- The lint `stale` threshold is now derived from the operator's `[decay]- lambda` instead of a hard-coded 30 days (#426). The rule only fires on- episodic pages with zero accesses, and for those the decay score reduces- exactly to `salience * exp(-lambda * age)` — the reinforcement term carries- `ln(1 + access_count)`, which is zero — so the lint was already measuring- decay, just against a constant rather than against `lambda`. Slowing decay- made the two diverge: at `lambda = 0.008` real eviction lands near day 201- while the lint still called a page stale on day 31, and because a report- page is written whenever any finding exists, one page nobody intended to- read produced a new `_lint/<date>.md` every day, forever. The threshold is- now `0.6 / lambda`, which is **exactly 30 days at the default- `lambda = 0.02`** — unchanged for anyone who never tuned decay — and 75- days at `0.008`. An invalid or non-positive lambda falls back to the- historical constant rather than silencing the rule.-- `bin/deploy` now refuses to push a single-architecture build over a tag that- already resolves to a multi-architecture manifest (#427). It builds for the- architecture of the machine it runs on, so deploying a homelab from an x86- workstation to `IMAGE=akitaonrails/ai-memory:latest` replaced the- amd64+arm64 manifest CI had published with an amd64-only image, and every- arm64 host pulling `:latest` failed with `exec format error`. The shipped- `bin/deploy.env.example` also defaulted `IMAGE` to `:latest`, so following- the documented setup led straight into it; it now defaults to a private- `:homelab` tag and explains that release tags are published by CI only.-- `install-hooks` now writes agent-distinct extension filenames- (`ai-memory-pi.ts`, `ai-memory-omp.ts`) instead of both agents sharing- `ai-memory.ts`, so a Pi install and an OMP install no longer overwrite each- other when `PI_CODING_AGENT_DIR` points them at one home. A superseded- `ai-memory.ts` is removed only when it carries this tool's generated marker- *for that same agent* — a file you wrote yourself, or the other agent's, is- left alone and reported. OMP profiles are supported via `--profile` or- `OMP_PROFILE`; `PI_CODING_AGENT_DIR` takes precedence over a profile, since- it names the agent directory outright.-- Note distinct filenames stop the overwrite but do **not** make a shared- directory safe: each agent loads every `*.ts` it finds there, so installing- both into one home captures every event twice, once per agent identity.- That collision is upstream — both agents read the same environment- variable — so `install-hooks` now warns when it detects one and points at- the two ways out. (#421)-- `install-hooks --agent pi`, `--agent omp`, and `uninstall` now honor- `PI_CODING_AGENT_DIR`, instead of always writing to `~/.pi/agent/extensions/`- and `~/.omp/agent/extensions/`. Both agents relocate their whole agent- config home (`~/.pi/agent` / `~/.omp/agent`) through that variable, so on an- install with it set the extensions landed where the agent never loads them:- the install reported success and capture silently did nothing. ai-memory- already honored the variable when resolving Pi/OMP transcripts, so the two- halves of one install disagreed about where that home was. Installs without- `PI_CODING_AGENT_DIR` set are unaffected. The manual (non-`--apply`)- instructions now name the resolved path too, instead of always printing the- `~/.pi/agent` / `~/.omp/agent` default. (#411)-## [1.28.1] - 2026-08-18### Security@@ -1078,55 +1083,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0sentinel. Large Claude Code hook packets can be file-backed, so acceptance nolonger passes or fails based on whether the model chooses to use `Read`.The deterministic fake Grok leg covers the same assertion path. (#242)--### Added-- `install-mcp --client claude-code --session-aware` now registers an- ai-memory-owned stdio bridge that forwards Claude Code's- `CLAUDE_CODE_SESSION_ID` as `X-Memory-Actor-Session-Id` on every upstream- HTTP MCP request. This makes `[auto_scope] mode = "per_session"` effective- for concurrent Claude Code sessions against local or remote servers while- leaving the existing static HTTP registration as the default. The bridge- preserves bearer auth, stateless/stateful HTTP compatibility, and uninstall- ownership; both Docker wrappers forward the Claude session variable into- the helper container. (#244)-- `GET /admin/open-sessions` lists open (not yet ended) sessions for one- workspace/project/agent, newest first (`all=true` returns every match).- `ai-memory finalize-session` now uses this endpoint instead of opening- the local SQLite index directly, so every CLI command is a thin HTTP- client of the running server; the command now requires a reachable- server and no longer works against an offline data directory. (#236)-- Managed workstream support for Grok Build CLI: `ai-memory run grok` (alias- `grok-build`) creates fresh sessions with a wrapper-generated `--session-id`,- resumes linked sessions with `--resume`, maps wrapper `--yolo` onto Grok's- native `--yolo`/`--always-approve`, and delivers the bounded workstream- context packet through Grok's native `--rules` flag (system-prompt append,- acknowledged only after the child spawns). Transcript import reads- `$GROK_HOME/sessions/*/*/chat_history.jsonl` read-only with a- prefix-validated cursor and content-hash event ids so rewind-driven journal- rewrites cannot duplicate history; system prompts and encrypted reasoning- are excluded as loss annotations, as are the harness-injected `<user_info>`- and `<system-reminder>` blocks Grok stores inside `user` records (project- instructions, the skills catalogue, and connected MCP servers), which would- otherwise leak harness internals into the portable ledger and evict real- conversation from the startup packet budget. Discovery- matches checkouts through `summary.json`'s recorded `info.cwd` and honors- `GROK_HOME`. Grok stays out of the bare-mode automatic pool. Verified- against Grok Build CLI v0.2.111 ([#237]).--### Changed-- Single-page, batch, and bootstrap consolidation prompts now ask the model- to connect related wiki pages with path-based wikilinks and to mirror the- dominant natural language of the source material while preserving code,- identifiers, paths, commands, error strings, and JSON field names. (#238)-- The M8 access-counter reinforcement now bumps a page's `access_count` and- `last_accessed_at` at most once per minute instead of on every search that- returns it. A first sighting still bumps immediately, and a continuously hot- page remains eligible once per window, while the cooldown map self-prunes to- the pages searched within the window. This reduces redundant single-writer- work under bursty or overlapping searches while intentionally making- `access_count` a coarser retention signal. (#239)--### Fixed- Managed workstream packets now carry a versioned origin marker, and ClaudeCode transcript import excludes a tool result only when its content beginswith that marker (or the legacy rendered packet header). This prevents a@@ -1176,6 +1132,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0ledger claim cannot consume the handoff or suppress retry delivery.(#235)+### Added+- `install-mcp --client claude-code --session-aware` now registers an+ ai-memory-owned stdio bridge that forwards Claude Code's+ `CLAUDE_CODE_SESSION_ID` as `X-Memory-Actor-Session-Id` on every upstream+ HTTP MCP request. This makes `[auto_scope] mode = "per_session"` effective+ for concurrent Claude Code sessions against local or remote servers while+ leaving the existing static HTTP registration as the default. The bridge+ preserves bearer auth, stateless/stateful HTTP compatibility, and uninstall+ ownership; both Docker wrappers forward the Claude session variable into+ the helper container. (#244)+- `GET /admin/open-sessions` lists open (not yet ended) sessions for one+ workspace/project/agent, newest first (`all=true` returns every match).+ `ai-memory finalize-session` now uses this endpoint instead of opening+ the local SQLite index directly, so every CLI command is a thin HTTP+ client of the running server; the command now requires a reachable+ server and no longer works against an offline data directory. (#236)+- Managed workstream support for Grok Build CLI: `ai-memory run grok` (alias+ `grok-build`) creates fresh sessions with a wrapper-generated `--session-id`,+ resumes linked sessions with `--resume`, maps wrapper `--yolo` onto Grok's+ native `--yolo`/`--always-approve`, and delivers the bounded workstream+ context packet through Grok's native `--rules` flag (system-prompt append,+ acknowledged only after the child spawns). Transcript import reads+ `$GROK_HOME/sessions/*/*/chat_history.jsonl` read-only with a+ prefix-validated cursor and content-hash event ids so rewind-driven journal+ rewrites cannot duplicate history; system prompts and encrypted reasoning+ are excluded as loss annotations, as are the harness-injected `<user_info>`+ and `<system-reminder>` blocks Grok stores inside `user` records (project+ instructions, the skills catalogue, and connected MCP servers), which would+ otherwise leak harness internals into the portable ledger and evict real+ conversation from the startup packet budget. Discovery+ matches checkouts through `summary.json`'s recorded `info.cwd` and honors+ `GROK_HOME`. Grok stays out of the bare-mode automatic pool. Verified+ against Grok Build CLI v0.2.111 ([#237]).++### Changed+- Single-page, batch, and bootstrap consolidation prompts now ask the model+ to connect related wiki pages with path-based wikilinks and to mirror the+ dominant natural language of the source material while preserving code,+ identifiers, paths, commands, error strings, and JSON field names. (#238)+- The M8 access-counter reinforcement now bumps a page's `access_count` and+ `last_accessed_at` at most once per minute instead of on every search that+ returns it. A first sighting still bumps immediately, and a continuously hot+ page remains eligible once per window, while the cooldown map self-prunes to+ the pages searched within the window. This reduces redundant single-writer+ work under bursty or overlapping searches while intentionally making+ `access_count` a coarser retention signal. (#239)+## [1.18.0] - 2026-07-23### Added@@ -1598,6 +1601,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0rejecting the empty actor. The automatic session-end / compactionconsolidation in the hook router is system-initiated and deliberatelystays anonymous ([#183]).+- `install-mcp` and `install-hooks` now honor an explicit `--server-url` even+ when it matches the compiled default. Previously that value was+ indistinguishable from "flag omitted" and could be overridden by+ `AI_MEMORY_SERVER_URL`, which could write config for the wrong local server+ ([#178]).+- Devin hook capture now derives `cwd` when the native payload omits it:+ payload `cwd` still wins, followed by `DEVIN_PROJECT_DIR`, then the hook+ process working directory. This keeps real Devin `SessionStart` /+ `PostToolUse` fixtures routable without inventing a payload field.+ Payloads without a `session_id` are bridged the same way: a per-host id is+ minted at `SessionStart`, reused for later events, and cleared at+ `SessionEnd`; set `AI_MEMORY_SESSION_ID` in the hook environment to pin an+ externally managed run id. A payload-supplied id always wins ([#178]).### Changed- `audit-contamination` no longer flags an observation whose project differs@@ -1648,21 +1664,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`sessions.agent_kind`, preserving the same workspace/project invariants asthe other supported agents ([#178]).-### Fixed-- `install-mcp` and `install-hooks` now honor an explicit `--server-url` even- when it matches the compiled default. Previously that value was- indistinguishable from "flag omitted" and could be overridden by- `AI_MEMORY_SERVER_URL`, which could write config for the wrong local server- ([#178]).-- Devin hook capture now derives `cwd` when the native payload omits it:- payload `cwd` still wins, followed by `DEVIN_PROJECT_DIR`, then the hook- process working directory. This keeps real Devin `SessionStart` /- `PostToolUse` fixtures routable without inventing a payload field.- Payloads without a `session_id` are bridged the same way: a per-host id is- minted at `SessionStart`, reused for later events, and cleared at- `SessionEnd`; set `AI_MEMORY_SESSION_ID` in the hook environment to pin an- externally managed run id. A payload-supplied id always wins ([#178]).-## [1.12.0] - 2026-07-12### Added@@ -2052,6 +2053,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`memory_install_self_routing` now returns the slim block, managed skillpayloads, target hints, and overwrite guidance for agents that installrouting through MCP.+- Agent-facing routing prompts and auto-scope docs now call out that static MCP+ clients running parallel sessions need explicit scope arguments or a+ session-aware bridge that forwards the real lifecycle-hook session id.### Added- The native `session-end` hook now emits a one-line stderr note when the spool@@ -2066,11 +2070,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0roots after marker validation; custom `--target-dir` skill roots remain amanual cleanup path.-### Changed-- Agent-facing routing prompts and auto-scope docs now call out that static MCP- clients running parallel sessions need explicit scope arguments or a- session-aware bridge that forwards the real lifecycle-hook session id.-### Fixed- Thin-client HTTP CLI commands (`status`, `search`, `read-page`, `write-page`,`delete-page`, `backup`, `embed`, and related admin commands) now fall back to@@ -2282,6 +2281,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0metadata from frontmatter instead of forcing every reindexed page back tosemantic/unpinned. Wiki writes now serialize canonical tier/pinned metadata solater watcher reconciliation remains idempotent for episodic and pinned pages.+- Bounded heuristic session-page raw observation dumps and single-page+ consolidation prompts so very large sessions cannot re-include unbounded+ `## Raw observations` history (issue #102).+- Hook spool no longer counts a server `429` (saturation / `hook queue full`)+ against a spooled event's `MAX_ATTEMPTS` retry budget: transient backpressure+ keeps the event queued without burning an attempt (`MAX_AGE_MS` still bounds+ it), so a saturation burst no longer silently discards real observations.### Added- `GET /admin/audit-contamination` (and `ai-memory audit-contamination`) — a@@ -2306,15 +2312,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0alongside `docs/install.md` (mirroring how the Windows zip ships`docs/windows.md`).-### Fixed-- Bounded heuristic session-page raw observation dumps and single-page- consolidation prompts so very large sessions cannot re-include unbounded- `## Raw observations` history (issue #102).-- Hook spool no longer counts a server `429` (saturation / `hook queue full`)- against a spooled event's `MAX_ATTEMPTS` retry budget: transient backpressure- keeps the event queued without burning an attempt (`MAX_AGE_MS` still bounds- it), so a saturation burst no longer silently discards real observations.-## [1.1.0] - 2026-06-16### Fixeddiff --git a/scripts/check-changelog-sections.sh b/scripts/check-changelog-sections.shnew file mode 100755index 00000000..d9da79d2--- /dev/null+++ b/scripts/check-changelog-sections.sh@@ -0,0 +1,64 @@+#!/usr/bin/env bash+# Fail if any CHANGELOG version section repeats a `### ` heading.+#+# `bin/release` copies `## [Unreleased]` into the new version section+# verbatim. A duplicated heading there ships release notes with, say, two+# separate "Fixed" lists and the entries split between them — and nothing+# else catches it, because a duplicate heading is valid Markdown.+#+# This is not hypothetical: it happened twice in one day, both times from+# a maintainer adding a section at the top of `[Unreleased]` while an+# equivalent one already sat further down after an earlier merge.+#+# Merging on merge, rather than rejecting, would hide the conflict from+# whoever wrote the second entry; failing loudly keeps the choice with a+# human.++set -euo pipefail++REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"+CHANGELOG="${1:-$REPO_ROOT/CHANGELOG.md}"++if [[ ! -f "$CHANGELOG" ]]; then+ echo "check-changelog-sections: $CHANGELOG not found" >&2+ exit 2+fi++status=0+current=""++while IFS= read -r line; do+ case "$line" in+ '## ['*)+ current="${line#\#\# }"+ seen=" "+ ;;+ '### '*)+ [[ -n "$current" ]] || continue+ heading="${line#\#\#\# }"+ # Trailing whitespace should not create a distinct heading.+ heading="${heading%"${heading##*[![:space:]]}"}"+ if [[ "$seen" == *" ${heading} "* ]]; then+ echo "error: ${current} repeats the '### ${heading}' heading." >&2+ status=1+ else+ seen="${seen}${heading} "+ fi+ ;;+ esac+done < "$CHANGELOG"++if [[ $status -ne 0 ]]; then+ cat >&2 <<'EOF'++Each version section may use a given heading only once. Merge the entries+under a single heading, in Keep a Changelog order:++ Added, Changed, Deprecated, Removed, Fixed, Security++(this project also uses Improved, placed after Changed).+EOF+ exit 1+fi++echo "CHANGELOG section headings are unique within every version."