Worktree-Only Closeouts & Carryover Coverage

Agents Remember 2.9.0

Closeout is now worktree-only, branch-memory carryover covers every artifact kind, and the README's Status section now states where the project is and where it is going — with release history living here, in GitHub Releases.

⚠️ Breaking change — deliberate Stability exception

• The direct_closeout_preview and direct_closeout_apply MCP tools are removed (GitHub #62). Worktree-only closeout was the original design intent of the session lifecycle: every change to a managed repo — chat builds included — runs through a code + memory worktree, keeping external memory consistent and auditable. The direct path was a leftover from an incomplete cleanup. Migration: worktree_start → work → worktree_closeout_preview / worktree_closeout_apply.
• Under the Stability promise, tool removals belong to a major bump. This ships in a minor release as a recorded, deliberate exception: 3.0 is reserved for the dashboard/observability architecture named in the README's new Status section.

Highlights

• Worktree-only closeout doctrine (#62): tools, skills (l-01-session-job-lifecycle, c-12-closeout), docs, and tests aligned; the MCP tool surface goes 37 → 36.
• Carryover artifact coverage: memory_carryover_plan / memory_carryover_apply now also carry the repo entity catalog and memory-only doc updates between memory branches.
• Repository rename sweep: stale agents-remember-md references swept across docs and onboarding after the GitHub rename to agents-remember.

Docs And Public Surface

• The README Status section is rewritten from the per-release narrative chain (a de-facto changelog) into a two-paragraph current state + direction statement; per-release history now lives in GitHub Releases — this page is the canonical changelog.
• system/git-workflow.md / system/tools.md (memory layer): the version-bump location count corrected to three (pyproject, SERVER_VERSION, README Status).

Lifecycle-Long Stale-Base Prevention & Mid-Task Worktree Sync

Agents Remember 2.8.0

Base-currency becomes a lifecycle-long guarantee (GitHub #54): every stage of a task — session start, worktree start, and mid-task — can now see when its view of the official line went stale, and pull the official line in safely instead of silently building on old code and memory.

Highlights

• Stale-base preflight: worktree_start refuses to base a new worktree on a source branch that is behind or diverged from its remote — with stale_base_choice="fast-forward" (the tool fast-forwards and proceeds) or "proceed-stale" recoveries. A stale base doesn't just produce wrong code: it silently defeated the provider seed fast-path into a multi-minute reindex.
• New worktree_sync tool: pull a moved official line into a live worktree atomically — the new code tip must be ledger-mapped at the official memory tip, the code work branch merges (conflicts abort cleanly), parked memory fast-forwards, and the contract's recorded base pair advances with a durable sync_log. Sync early — before memories are written — and end-of-series integration stays ff-only with no carryover reconciliation.
• Memory main keeps up: memory_carryover_apply now fast-forwards memory main to the official checkout tip (memory_main_advance), so cycles run on non-main source branches no longer leave memory main behind indefinitely.

Freshness Checkpoints

• context_packet gains an opt-in include_freshness section: upstream ahead/behind for the code and memory checkouts plus ledgerMapsCodeHead, forming the lifecycle-start trust checkpoint (the l-01 skill opts in).
• worktree_status carries a fetch-free freshness block (recorded base pair vs local source tips) with a syncHint recommending worktree_sync — network-free, so the background provider-setup polling loop stays fast.
• A missing external-memory source branch is auto-created at the official memory tip using the code source branch name as template — one less manual step before worktree_start.

Onboarding And Memory

• Runtime skills (l-01, c-09, c-11) teach the three checkpoints and the sync-early-before-memories doctrine.
• The providers.context facade import-order fix (landed with 2.7.0) is now pinned by fresh-interpreter regression tests on Python 3.11.
• Change-notification ping transport for the freshness payload is tracked as follow-up #60.

Background Provider Setup Visibility & Windows Seed Fix

Agents Remember 2.7.0

Worktree provider setup is now observable instead of silent, and the seed-copy rapid-deploy path finally works on Windows. A healthy six-minute setup and a wedge no longer look identical — and on Windows, that six-minute setup mostly stops happening at all.

Highlights

• worktree_start returns within seconds: the provider chain runs in the background and writes a durable, heartbeat-stamped setup-progress.json you (or a dashboard) can watch.
• The seed-refused → full-reindex transition — the moment expected duration jumps from ~1 minute to N minutes — is flagged as seedFallback the instant it happens, with the refusal reason.
• CGC seed export/load argv is rendered in container form: Windows hosts stop failing every seed export on a C:/ path the Linux runner can't see, and stop silently paying the full reindex on every worktree start.

Worktree Provider Setup (GitHub #53)

• Background daemon-thread setup with a durable phase-progress file under the worktree group (provider-runtime/setup-progress.json): schema ar-provider-setup-progress/v1 with identity fields (repoName, taskName, worktreeGroup), per-phase records, a 15s heartbeat, and a reserved currentPhase.metrics shape (itemsDone/itemsTotal/percent/unit) for future per-item indexing progress.
• worktree_status is the poll surface: running (current phase, elapsed, heartbeat age, seedFallback), then ok / ready-with-failed-phases / failed — or stale when the heartbeat dies (server killed mid-setup).
• worktree_start(retry_provider_setup=true) relaunches a failed or stale setup on the existing contract; it refuses while a live setup is running.
• worktree_cleanup / worktree_abandon refuse to tear down a worktree whose background setup is still alive (force overrides on abandon).
• Dry runs stay fully synchronous; config-level preflight failures (settings unreadable, providers disabled) still block the start fast.
• The temp lifecycle settings file's lifetime transfers to the setup thread, and worktree provider setup is now bounded by the documented timeoutCaps.providerSetupSeconds cap (default 1800) instead of a hardcoded 120s.

CodeGraphContext Seeding (GitHub #58)

• Everything after -- in a seed export/load command executes inside the Linux runner container; those paths (bundle files, export --repo root) are now rendered via to_container_path (drive letter stripped on Windows, identity on POSIX).
• Shared context helpers moved to providers/context_common.py: importing them from inside the providers/context facade package could leave the facade permanently missing every CGC name (an import-order-dependent ImportError), discovered while wiring the fix.

Quality

• 26 new tests: progress-file lifecycle/heartbeat/staleness projections, phase announcement order including the seedFallback transition, launcher thread behavior, contract-before-launch ordering, retry refusal/relaunch, controller settings-file ownership, teardown guards, and a Windows drive-letter argv guard.
• The Docker-gated provider workflow integration test now polls the progress file to a terminal state, matching the async contract.

Memory Integrity: Carryover Overview Coverage & Body-Staleness Gates

Agents Remember 2.6.0

Closes #56: everything closeout writes into task memory now has a carryover
path home, and verification metadata can no longer advance over stale
onboarding bodies.

Highlights

• Branch-memory carryover now plans route-overview candidates beside file
  sidecars and regenerates official-side route indexes after a carry.
• Closeout gains body/history gates: header-only or unmarked history-only
  onboarding refreshes fail for changed sources and their nearest-governing
  route overviews.
• New in-band attestation convention: explicit No content impact: /
  No route impact: Update History markers record reviewed-no-impact
  decisions and are surfaced in closeout tool responses.

Onboarding And Memory

• Carryover candidates are kind-tagged (file-sidecar / route-overview);
  overview candidates are keyed by the normalized code route (. for the repo
  root) and selected via the existing include_review_required.
• Identical branch/official overview content auto-carries for metadata
  re-verification only — closing the post-merge gap where overview
  verification stayed pinned at the pre-merge commit. Differing content is
  always review-required: overview bodies are model-authored aggregates.
• overview.index.json files are derived artifacts: regenerated on the
  official side after a carry (never copied), guarded on a clean checkout of
  the official ref, and reported as route_index_refresh.

Closeout Gates

• The sidecar content gate became a four-case body/history classification:
  body+history passes; a body edit without an Update History entry fails
  (traceability); a history-only edit passes only with the
  No content impact: marker; metadata-only refreshes fail.
• Route overviews get the same gate scoped by domain evidence: only the
  nearest-governing overview of a changed path gates closeout; overviews
  matched as ancestors are reported as stamped_without_body_review instead.
• Closeout previews expose the full gate classifications
  (sidecar_body_gate, route_overview_body_gate); apply payloads surface
  every attested document so marker use stays reviewable at the commit gate.
• The c-05 onboarding skill documents the body-before-metadata doctrine and
  both marker conventions (packaged + all harness starter mirrors).

Internals

• New kernel/onboarding_doc.py owns shared onboarding-document parsing,
  route-overview discovery, and the meaningful-body/history classification;
  worktrees/modules/onboarding.py re-exports the moved helpers (facade).

MCP 2.5.2 — compact carryover tool responses

Small patch finishing the response-budget work from 2.5.1: the carryover pair was the last tool surface still returning fat responses.

Changed

• memory_carryover_plan / memory_carryover_apply responses compacted (#52): measured live at 3,915 / 7,745 tokens for a 28-file carryover — the apply response contained every candidate record twice, and each record repeated derivable onboarding paths plus an identical per-path reason. Both tools now file the full records under temp/tool-reports/memory_carryover_*/ (keep-last-5 / 7-day retention, secret-redacted) and return per-decision source_path digests (capped at 25 per group with an overflow marker), carriedPaths on apply, and an inline reportPath. Commits, intent note, and counts stay inline. Backward-compatible: the slimmed arrays are flexible envelope detail, same semver posture as 2.5.1.

Known issues under investigation from this release cycle: #53 (worktree_start provider setup is silent for minutes — async visibility planned) and #54 (worktree_start can branch from stale local bases; also silently converts the fast index-copy seed into a full reindex).

Full changes: #55

MCP 2.5.1 — tool reliability and response token budgets

Patch release on the 2.5.0 readiness work, fixing the two remaining classes of tool misbehavior: hangs and oversized responses.

Fixed

• Carryover/tool hang on stdio transport (#49): subprocess children inherited the MCP server's stdin — which on stdio transport is the JSON-RPC pipe — wedging tool calls while the work completed server-side. Subprocesses now get stdin=DEVNULL unless input is piped, proven by a before/after stdio regression harness (120s hang → 3.4s). A package-wide AST hygiene test prevents reintroduction.
• Runner image tag drift on upgrade (#50): providers/settings.py derived the CGC runner image independently and dropped the layer revision, so upgrading hosts kept a cached guard-less image. The tag now comes from the single cgc_runner_image() derivation, with a regression test.
• Crash-looping watchers reported ready: restarting containers no longer count toward readiness.

Changed

• Stall watchdogs instead of total-time caps for seed/clone: GrepAI index clones are killed only after 300s of zero progress (GREPAI_CLONE_STALL_SECONDS), never for size — copying index data instead of re-indexing is what makes rapid worktree provider deployment viable, and it scales with index size by design.
• GrepAI indexing-state parity: initial-scan log markers now map to indexing/indexed instead of unknown, feeding the context-packet indexing busy list.
• Response token budgets: bulk passthrough fields (raw status trees, rebind transcripts, watcher step results) move to temp/tool-reports/<tool>/ files referenced by an inline reportPath. Inline payloads stay compact under budget tests; reports are pruned at write time (keep last 5, max 7 days) and password-redacted.

Full changes: #51

Durable Code Graphs & Honest Provider Readiness

Agents Remember 2.5.0

The CodeGraphContext provider becomes durable and honest about readiness, and the toolchain stops fearing Windows long paths. Born from a real incident: a context packet reported green over a 0-node code graph for three days.

Highlights

• FalkorDB graph data now survives container recreates (configurable dataDestination mount fix)
• Provider status probes actual graph content: indexed / indexing / empty / backend-unreachable
• Empty-graph targets degrade the global context packet (ok: false) with per-repo restart recovery actions
• New additive ProviderSummary.indexing list tells agents a provider is healthy but mid-scan
• Watcher self-heal entrypoint guard clears poisoned empty graphs at startup (runner image 0.4.10-ar1)
• Crash-safe, long-path-proof skill/runtime sync and a worktree_start long-path preflight for native Windows

CGC Provider Durability And Readiness

• FalkorDB data volume binds the backend dataDestination (default /var/lib/falkordb/data, where FalkorDB v4 actually writes) instead of /data; mount verification follows the setting and mismatched containers are recreated on the next backend start.
• The backend healthcheck requires a genuine PONG, so dataset-LOADING replies no longer count as healthy.
• cgc_status derives indexingState from a read-only GRAPH.RO_QUERY content probe plus watcher scan markers; indexing stays green at every level while busy targets surface in the compact providers summary and the l-01 trust checkpoint doctrine.
• All watcher compose runs pass --remove-orphans, cleaning up watchers of de-configured repos.

Windows Long-Path Hardening

• sync-skills.py / sync-runtime.py use a staged copy-then-swap with \\?\ extended-length path support - a mid-sync crash can no longer gut package_data.
• worktree_start blocks up front with projected path lengths and remedies when a Windows host without LongPathsEnabled cannot represent the worktree's deepest tracked files.
• The install guide documents the one-time Windows long-path setup; WSL is unaffected.

All changes are backward-compatible. Fixes #47.

Consolidated L-01 Lifecycle Skill

Agents Remember 2.4.2

This patch release packages the consolidated L-01 session lifecycle skill so agents get the complete request-to-close doctrine from SKILL.md itself. The release is backward-compatible and keeps MCP tool contracts unchanged.

Highlights

• Consolidates the detailed l-01-session-job-lifecycle phase spine into SKILL.md, removing the skipped lifecycle.md companion file.
• Syncs the updated lifecycle skill into MCP package data and all harness starter packages.
• Refreshes lifecycle onboarding so memory points at the new single entry contract and removes the orphaned lifecycle.md sidecar.

Lifecycle Skill

• SKILL.md now carries request intake, trust checkpoint, reframe/research, decide, build, and close phase behavior inline.
• The remaining companions are limited to job-variants.md and deep-research-report-template.md.
• Generated skill copies no longer include lifecycle.md, preventing agents from missing required phase doctrine after reading the skill entry file.

Release Notes

• No MCP tool input/output contracts changed.
• No CHANGELOG.md was added; GitHub Releases remain the canonical changelog.

Runtime Asset Sync & Provider Validation

Agents Remember 2.4.1

Agents Remember 2.4.1 makes runtime package assets visible and editable from
canonical root folders, then syncs them into MCP package data through one checked
script. It also preserves provider validation when compact context_packet
calls skip provider details, so small managed-repo confirmation calls do not
silently bypass provider health checks.

Highlights

• Added canonical root runtime asset folders for agents-md-files/,
  benchmarks/, providers/, and system/.
• Added scripts/sync-runtime.py to copy those runtime assets into MCP package
  data only; harness starter packages are intentionally not targets.
• Added generated-copy gates so pre-commit and pre-push checks verify both
  scripts/sync-skills.py --check and scripts/sync-runtime.py --check.
• Preserved provider validation for skipped-provider context_packet responses,
  keeping compact packet calls small without dropping provider result checks.
• Refined lifecycle/coordinator instructions for session starts, managed-repo
  jobs, and boundary transitions, then refreshed generated skill copies.
• Made the linked-worktree pre-push quality gate load the current checkout's
  source while reusing the primary checkout virtualenv for tools.
• Bumped agents-remember-mcp to 2.4.1.

Setup Notes

• Edit runtime package assets at the root folders listed above, then run
  python3 scripts/sync-runtime.py before committing.
• Use python3 scripts/sync-runtime.py --check to confirm MCP package data is
  current.
• Root runtime assets sync only into MCP package data. They do not copy into
  harness starter packages.

Compatibility

• Backward compatible with existing MCP tool contracts and the memory model.
• Release tag: mcp-v2.4.1 after the release branch lands on main.

Harness starter rendering and hook cleanup

Agents Remember 2.4.0

Agents Remember 2.4.0 makes the harness starter packages easier to copy into a real workspace and render safely. It also removes the outdated Claude Code jq requirement from the setup guidance: hooks can be configured with direct Python command arguments instead.

Highlights

• Added harness-local render-starter helpers for the starter packages that need path, repository, and hook-command placeholder rendering.
• Simplified renderer usage to a copied-package workflow with one --repo list, while keeping manual placeholder replacement documented as a supported alternative.
• Updated Codex, Claude Code, Cursor, GitHub Copilot, Hermes, OpenClaw, Pi.dev, and Antigravity setup docs to reflect the package-local render flow.
• Rendered hook commands through Python entrypoints where the harness supports it, avoiding shell quoting and removing the legacy jq misconception for Claude Code hooks.
• Bumped agents-remember-mcp to 2.4.0 and refreshed the README Status line for the release.

Setup Notes

• Copy the harness starter package into the workspace root, then either run the copied render-starter helper with --repo <repo-a> <repo-b> or replace the placeholders manually.
• Restart the harness once after rendering or manual replacement so it loads the updated package files and MCP configuration.

Compatibility

• Backward compatible with the existing MCP tool contracts and memory model.
• Release tag: mcp-v2.4.0.