Memory maintenance: a read-only index guard reading the client's own limits; auto-dream detection; auto-memory row - #1149

Scope

• What this PR changes, in one or two sentences: Memory maintenance, from the owner direction of 2026-10-15 00:34 ET (paraphrased by the command center: memories should consolidate automatically; resolve the harness with current maintenance practice). It adds a read-only guard for every project memory index. The guard reads the limits from the installed client binary, alerts at 90%, and detects Claude Code's auto-dream consolidation runs. The auto-memory slot row records the consolidation setting and the ai-memory maintenance facts.
• Base commit: 0f4ee075b
• Lane: lane:foundation
• Owned paths touched:
  • tools/memory-index-guard/ (new: the guard, README, service and timer);
  • tests/test_memory_index_guard.py and tests/test_native_practice_memory_maintenance.py (new);
  • the practice skill's slots.json, native-clients.md and slots.md, plus the slot manifest;
  • evidence/artifacts/memory-maintenance-20261015/ (new);
  • manifests/evidence.json.

The guard (tools/memory-index-guard/memory_index_guard.py, stdlib, python3 -I):

• Limits: read from the installed binary. A user-visible warning template binds the minified identifiers to the "MEMORY.md",X=<int>,Y=<int> declaration, so nothing is hard-coded, and anything unbound is "unknown". Measured: 200 lines and 25,000 code units, on 2.1.296, 2.1.299 and 2.1.300.
• Indexes: it measures each one as the client does (UTF-16 code units of the trimmed text, plus UTF-8 bytes) and reports ok, warn (80%, the client's own write-time reminder) or alert (90%).
• Auto-dream:
  • It reports autoDreamEnabled and the server flag's enabled and available fields, reading only that key.
  • It detects a consolidation from each memory directory's .consolidate-lock mtime; the client stores lastConsolidatedAt there (2.1.300 binary offset in sources.json).
  • On a new consolidation it writes a names-and-counts diff against the guard's own snapshot, with no content, and alerts. This is the paired check in the slot's overturn_when.
• Exit codes: 1 alerts through the unit's OnFailure=stack-alert@%n.service. 0 when limits or the flag are unknown (fail-open). 2 when the guard's own state is unusable.
• Install: the command center's act, with the steps and inverse in the tool's README. Nothing is installed by this PR.

Slot row auto-memory:

• Consolidation: autoDreamEnabled: true in user settings, applied by the command center 2026-10-15 00:45 ET after the owner asked. It is inert while the server flag is off (measured: enabled false, no available).
• Index limits: memory.md:546 and the binary, plus the guard.
• ai-memory 2.6.3 maintenance:
  • There is no consolidate CLI; consolidation is the MCP memory_consolidate, dry run first.
  • lint --dry-run --no-llm and forget-sweep --dry-run are HTTP clients of the running single-writer server.
  • Scheduled maintenance is the server's built-in [maintenance] block, which this host already runs, so no extra timer is added.
  • The CLI's default port differs from this host's server.
• overturn_when: the flag becoming available triggers the paired check of the first dream run.
• Correction (guide-screen item 29): the rejection said a repository-supplied autoMemoryDirectory is inert. memory.md:516,526 says it is honoured from project settings once the folder is trusted.

Measured on this host (06:25:55Z):

• Five indexes, all ok. native-agent-stack is at 79.97% of the size limit, 7 code units under the client's 80% reminder.
• 890 memory directories, no consolidation lock.

SOTA sources

• https://code.claude.com/docs/en/memory.md (fetched 2026-10-15T04:39:50Z, sha256 1ebf1bdc…), lines 31, 516, 526, 546, 548.
• https://code.claude.com/docs/en/errors.md (04:40:18Z, sha256 d28fbfce…), lines 4275, 4278.
• https://code.claude.com/docs/en/settings-reference.md (04:39:50Z, sha256 8ba90434…), lines 617-618 and 1644.
• anthropics/claude-code@94506ff0 CHANGELOG.md (sha256 8c6fdbbd…): L1392, L2555, L4098, L4139, L4580, L6619, L6844.
• The Claude Code 2.1.300 binary (sha256 674deba0…): byte offsets are in evidence/artifacts/memory-maintenance-20261015/sources.json, with 59 quotes, each checked byte for byte against its source.
• akitaonrails/[email protected] (tag e40a3678, commit 385b81ea):
  • docs/ARCHITECTURE.md:721-722, 828-833;
  • docs/install.md:2457-2469;
  • crates/ai-memory-cli/src/config.rs:37, 705;
  • commands/lint.rs:1,10 and commands/forget_sweep.rs:1,10;
  • crates/ai-memory-mcp/src/server.rs:320-329, 1160-1162.
• String.prototype.trim code points, measured in Bun 1.4.2 and Node v24.21.0 (js-trim-set.json).

Evidence-class table

Local commands run

$ python3 -m unittest tests.test_memory_index_guard tests.test_native_practice_memory_maintenance   # at base
ImportError (no tool) / FAILED (failures=41, errors=1)
$ python3 -m unittest tests.test_memory_index_guard tests.test_native_practice_*  (and related modules)
248 OK
$ python3 scripts/validate.py
rc 0; {"components": 71, "hashed_files": 12049, "profiles": 4, "receipts": 240, "status": "passed"}

Notes for the reads

• No durable-memory slot row exists; it is a foundation layer. The ai-memory facts sit in the auto-memory row next to its durable-memory route.
• Every open practice-row PR rewrites the slot manifest's sha256_when_labeled, so later ones need a manifest rebase.

Checklist

• No GitHub Actions changed.
• No workflows changed.
• No secrets are printed, logged or committed. Memory content never enters reports; snapshots stay in the guard's 0700 state directory.
• No new paid hosting, subscription or billing surface.
• Peer-owned untracked files and worktrees were preserved.

🤖 Generated with Claude Code