Skip to content

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.yml
index 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.md
index 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.0
very duplicate-load the split exists to prevent, since each agent loads
every `*.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 timeout
every 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.0
the working tree; and a mid-task exit (Stop without SessionEnd) is flagged
so 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.0
sentinel. Large Claude Code hook packets can be file-backed, so acceptance no
longer 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 Claude
Code transcript import excludes a tool result only when its content begins
with 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.0
ledger 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.0
rejecting the empty actor. The automatic session-end / compaction
consolidation in the hook router is system-initiated and deliberately
stays 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 as
the 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 skill
payloads, target hints, and overwrite guidance for agents that install
routing 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.0
roots after marker validation; custom `--target-dir` skill roots remain a
manual 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.0
metadata from frontmatter instead of forcing every reindexed page back to
semantic/unpinned. Wiki writes now serialize canonical tier/pinned metadata so
later 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.0
alongside `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
### Fixed
diff --git a/scripts/check-changelog-sections.sh b/scripts/check-changelog-sections.sh
new file mode 100755
index 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."