feat(harness): P1+P2+P3 harness optimization complete (VERSION 1.4.0)
Task 5 one-line registry descriptions on the 8 biggest skills (remediation-tool,
gc-audit, packetdial, memory-dream, human-flow, self-check, impeccable,
mailprotector); skill-description injection ~3320 -> ~2123 tokens (~36%),
keyword triggers preserved, frontmatter valid.
Task 7 thinned /save + /sync bodies to point at sync.sh (single source) instead of
re-documenting internals; Phase 0 save-vs-sync, cross-user notes, exit-75
reporting kept verbatim; mechanical sync never depends on an LLM step.
Task 10 session-logs/YYYY-MM/ forward convention for new logs (scoped-grep recall,
no monolithic index); existing flat logs untouched (grep covers both).
Bash now-phoenix.sh helper (fixed UTC-7 epoch math; replaces unreliable
TZ=America/Phoenix date that silently returns UTC on Git-Bash).
P0 (1.2.0) + Task 6 CLAUDE split + Task 9 delegation (1.3.0) already shipped.
Spec: specs/claudetools-harness-optimization/plan.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,142 +1,130 @@
|
||||
---
|
||||
name: memory-dream
|
||||
description: >-
|
||||
Memory lint + consolidation analyzer for the ClaudeTools REPO memory store
|
||||
(.claude/memory/). Audits the index, backlinks, referenced file paths,
|
||||
duplicate/overlap clusters, stale dated facts, and drift against the
|
||||
machine-local harness profile memory store. Default run is read-only.
|
||||
--apply-safe performs the low-risk fixes (append missing index lines, copy
|
||||
any profile-only files into the repo for indexing). Cluster merges, dedup
|
||||
deletes, and stale-fact removal are surfaced as PROPOSED actions for a
|
||||
human to apply -- they're judgment calls, not automation candidates. (Repo
|
||||
is the source of truth as of 2026-06-02; sync-memory.sh mirrors repo to
|
||||
profile, so PROFILE-side cleanup is handled by that script, not here. See
|
||||
feedback_memory_sync_destructive_ok.md.) Invoke for: "memory dream",
|
||||
"consolidate memory", "memory lint", "clean up memory", "memory errors",
|
||||
"dedupe memory".
|
||||
---
|
||||
|
||||
# Memory Dream
|
||||
|
||||
A read-only-by-default analyzer that flags issues in the shared memory store.
|
||||
Mutating ops are gated behind `--apply-safe` (for low-risk fixes) or the
|
||||
PROPOSED section (for judgment calls a human resolves by hand).
|
||||
|
||||
## The two-store model (important)
|
||||
|
||||
There are TWO separate memory stores on every machine:
|
||||
|
||||
- REPO store -- `.claude/memory/` (88+ `*.md` files + `MEMORY.md` index).
|
||||
Tracked in git, syncs to all machines via Gitea. **This is the source of
|
||||
truth.** `CLAUDE.md` mandates writing here.
|
||||
- HARNESS PROFILE store -- `$HOME/.claude/projects/<slug>/memory/`. Machine
|
||||
local, NOT in git, NOT synced. This is the store the Claude Code harness
|
||||
auto-injects into the system prompt at session start.
|
||||
|
||||
The two drift over time. `memory-dream` reports that drift in its report
|
||||
section. The companion script `.claude/scripts/sync-memory.sh` is what
|
||||
actually reconciles them: it runs in **mirror mode** (since 2026-06-02) —
|
||||
repo is authoritative, profile is synced to match (deletions propagate;
|
||||
repo content wins on conflict). PROFILE-side hygiene lives in
|
||||
`sync-memory.sh`, not here.
|
||||
|
||||
## What it checks
|
||||
|
||||
`scripts/memory_dream.py` runs six READ-ONLY analyses over the REPO store:
|
||||
|
||||
1. INDEX RECONCILE -- orphan files (no `MEMORY.md` line), index lines whose
|
||||
target file is missing, and frontmatter `name:` vs filename signals.
|
||||
2. BACKLINKS -- `[[name]]` references in bodies whose target slug has no file.
|
||||
3. REFERENCED-ARTIFACT VALIDITY -- conservatively extracts repo-relative file
|
||||
paths / script names from each body (backtick-wrapped single tokens only)
|
||||
and flags ones not found in the repo. Reported as **verify**, never delete
|
||||
(many are legitimately server-side or in sibling repos).
|
||||
4. DUPLICATE / OVERLAP CLUSTERS -- groups memories by type + token-overlap /
|
||||
shared slug-prefix and lists candidate mergeable clusters (e.g. the many
|
||||
`feedback_syncro_*` files). **Proposes** merges; never performs them.
|
||||
5. STALE DATED FACTS -- flags `project`-type memories with an "as of <date>"
|
||||
style claim older than ~6 months for re-verification.
|
||||
6. DRIFT vs PROFILE STORE -- locates the harness profile memory dir for this
|
||||
project and reports profile-only files (candidates to migrate INTO the repo)
|
||||
and repo-only files (candidates to push OUT to profile). Report only.
|
||||
|
||||
The report ends with a `## PROPOSED (needs human approval)` section that is
|
||||
NEVER auto-applied.
|
||||
|
||||
## Modes
|
||||
|
||||
- Default (no flag) -- **REPORT ONLY. Mutates nothing.** Writes a timestamped
|
||||
report to `.claude/memory/_reports/YYYY-MM-DD-HHMM-dream.md` (created if
|
||||
missing) and prints it to stdout.
|
||||
- `--apply-safe` -- performs ONLY additive, non-destructive fixes and prints
|
||||
each action:
|
||||
- (a) append missing index lines to `MEMORY.md` for orphan files, under the
|
||||
correct `## <Type>` header, never reordering or removing existing lines;
|
||||
- (b) copy profile-only memory files INTO the repo store (additive
|
||||
migration). If a same-named repo file already exists it is SKIPPED and the
|
||||
conflict is reported -- it is never overwritten.
|
||||
- `--no-file` -- print to stdout only; skip writing the `_reports/` file.
|
||||
- `--report-file <path>` -- write the report to an explicit path.
|
||||
|
||||
### What dream does NOT auto-do
|
||||
|
||||
`memory-dream` does NOT, even with `--apply-safe`:
|
||||
|
||||
- delete a repo memory file (cluster dedup is a judgment call — pick which file becomes canonical, fold the others' content, retire the originals deliberately);
|
||||
- remove or reorder index lines (index cleanups are also surfaced as proposals);
|
||||
- overwrite a file whose content differs;
|
||||
- perform a proposed merge.
|
||||
|
||||
These stay in the report's `## PROPOSED` section. The rationale isn't "never delete" any more (the fleet-wide additive safety net was dropped 2026-06-02; see `feedback_memory_sync_destructive_ok.md`) — it's that merges and dedups require human judgment about which file is canonical and how to combine content. Profile-side deletion DOES happen automatically — but in `sync-memory.sh`, not here.
|
||||
|
||||
## Running it
|
||||
|
||||
This machine's Python launcher is `py` (per identity.json); the script also
|
||||
runs under `python` / `python3`. Stdlib only -- no pip deps.
|
||||
|
||||
```bash
|
||||
# REPORT ONLY (default) -- writes _reports/<stamp>-dream.md and prints it
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py"
|
||||
|
||||
# report to stdout only, write nothing
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py" --no-file
|
||||
|
||||
# additive-only fixes (append orphan index lines, migrate profile-only files)
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py" --apply-safe
|
||||
```
|
||||
|
||||
`CLAUDETOOLS_ROOT` resolves from the env var, else `claudetools_root` in
|
||||
`.claude/identity.json`, else the repo root derived from the script's own
|
||||
location -- no hardcoded drive letters.
|
||||
|
||||
## Cleanup / approve workflow
|
||||
|
||||
1. Run with no flag. Read the report (stdout or `_reports/<stamp>-dream.md`).
|
||||
2. Run `--apply-safe` to take the safe additive wins: orphan index lines get
|
||||
added, profile-only memories get migrated into the repo (conflicts skipped
|
||||
and reported).
|
||||
3. Work the `## PROPOSED` section by hand:
|
||||
- `[MERGE?]` -- decide whether to consolidate a cluster. If yes, author a new
|
||||
combined memory (or set of files for a rule/history split), retire the
|
||||
originals via `git rm`, update `MEMORY.md`. Deletions are now first-class
|
||||
— `sync-memory.sh` mirror mode will propagate them to every profile store
|
||||
on the next run.
|
||||
- `[REVERIFY?]` -- confirm the dated fact still holds; update the body and
|
||||
its date if it changed.
|
||||
- `[STALE-REF?]` -- confirm the referenced path moved/renamed; repoint or
|
||||
annotate. Many are legitimately server-side (`.service` units, `/opt/...`).
|
||||
- `[INDEX-CLEANUP?]` / `[DRIFT-RESOLVE?]` -- human picks the winner.
|
||||
4. Commit the repo store changes so they sync to the fleet via Gitea.
|
||||
|
||||
## Self-test
|
||||
|
||||
`scripts/selftest.py` runs the analyzer against a synthetic fixture memory
|
||||
store in a temp dir and asserts each detector fires (orphan, missing target,
|
||||
broken backlink, stale path, cluster, profile drift) and that `--apply-safe`
|
||||
only touches the things it's supposed to (index appends + profile→repo copy
|
||||
of new files; no deletions, no merges, no overwrites of differing content).
|
||||
Run:
|
||||
|
||||
```bash
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/selftest.py"
|
||||
```
|
||||
---
|
||||
name: memory-dream
|
||||
description: "Lint + consolidate the ClaudeTools repo memory store (.claude/memory/): audits index, backlinks, file paths, duplicate clusters, stale facts. Read-only default; --apply-safe does low-risk fixes; merges/deletes surfaced as proposals. Triggers: memory dream, consolidate/lint/clean up/dedupe memory."
|
||||
|
||||
---
|
||||
|
||||
# Memory Dream
|
||||
|
||||
A read-only-by-default analyzer that flags issues in the shared memory store.
|
||||
Mutating ops are gated behind `--apply-safe` (for low-risk fixes) or the
|
||||
PROPOSED section (for judgment calls a human resolves by hand).
|
||||
|
||||
## The two-store model (important)
|
||||
|
||||
There are TWO separate memory stores on every machine:
|
||||
|
||||
- REPO store -- `.claude/memory/` (88+ `*.md` files + `MEMORY.md` index).
|
||||
Tracked in git, syncs to all machines via Gitea. **This is the source of
|
||||
truth.** `CLAUDE.md` mandates writing here.
|
||||
- HARNESS PROFILE store -- `$HOME/.claude/projects/<slug>/memory/`. Machine
|
||||
local, NOT in git, NOT synced. This is the store the Claude Code harness
|
||||
auto-injects into the system prompt at session start.
|
||||
|
||||
The two drift over time. `memory-dream` reports that drift in its report
|
||||
section. The companion script `.claude/scripts/sync-memory.sh` is what
|
||||
actually reconciles them: it runs in **mirror mode** (since 2026-06-02) —
|
||||
repo is authoritative, profile is synced to match (deletions propagate;
|
||||
repo content wins on conflict). PROFILE-side hygiene lives in
|
||||
`sync-memory.sh`, not here.
|
||||
|
||||
## What it checks
|
||||
|
||||
`scripts/memory_dream.py` runs six READ-ONLY analyses over the REPO store:
|
||||
|
||||
1. INDEX RECONCILE -- orphan files (no `MEMORY.md` line), index lines whose
|
||||
target file is missing, and frontmatter `name:` vs filename signals.
|
||||
2. BACKLINKS -- `[[name]]` references in bodies whose target slug has no file.
|
||||
3. REFERENCED-ARTIFACT VALIDITY -- conservatively extracts repo-relative file
|
||||
paths / script names from each body (backtick-wrapped single tokens only)
|
||||
and flags ones not found in the repo. Reported as **verify**, never delete
|
||||
(many are legitimately server-side or in sibling repos).
|
||||
4. DUPLICATE / OVERLAP CLUSTERS -- groups memories by type + token-overlap /
|
||||
shared slug-prefix and lists candidate mergeable clusters (e.g. the many
|
||||
`feedback_syncro_*` files). **Proposes** merges; never performs them.
|
||||
5. STALE DATED FACTS -- flags `project`-type memories with an "as of <date>"
|
||||
style claim older than ~6 months for re-verification.
|
||||
6. DRIFT vs PROFILE STORE -- locates the harness profile memory dir for this
|
||||
project and reports profile-only files (candidates to migrate INTO the repo)
|
||||
and repo-only files (candidates to push OUT to profile). Report only.
|
||||
|
||||
The report ends with a `## PROPOSED (needs human approval)` section that is
|
||||
NEVER auto-applied.
|
||||
|
||||
## Modes
|
||||
|
||||
- Default (no flag) -- **REPORT ONLY. Mutates nothing.** Writes a timestamped
|
||||
report to `.claude/memory/_reports/YYYY-MM-DD-HHMM-dream.md` (created if
|
||||
missing) and prints it to stdout.
|
||||
- `--apply-safe` -- performs ONLY additive, non-destructive fixes and prints
|
||||
each action:
|
||||
- (a) append missing index lines to `MEMORY.md` for orphan files, under the
|
||||
correct `## <Type>` header, never reordering or removing existing lines;
|
||||
- (b) copy profile-only memory files INTO the repo store (additive
|
||||
migration). If a same-named repo file already exists it is SKIPPED and the
|
||||
conflict is reported -- it is never overwritten.
|
||||
- `--no-file` -- print to stdout only; skip writing the `_reports/` file.
|
||||
- `--report-file <path>` -- write the report to an explicit path.
|
||||
|
||||
### What dream does NOT auto-do
|
||||
|
||||
`memory-dream` does NOT, even with `--apply-safe`:
|
||||
|
||||
- delete a repo memory file (cluster dedup is a judgment call — pick which file becomes canonical, fold the others' content, retire the originals deliberately);
|
||||
- remove or reorder index lines (index cleanups are also surfaced as proposals);
|
||||
- overwrite a file whose content differs;
|
||||
- perform a proposed merge.
|
||||
|
||||
These stay in the report's `## PROPOSED` section. The rationale isn't "never delete" any more (the fleet-wide additive safety net was dropped 2026-06-02; see `feedback_memory_sync_destructive_ok.md`) — it's that merges and dedups require human judgment about which file is canonical and how to combine content. Profile-side deletion DOES happen automatically — but in `sync-memory.sh`, not here.
|
||||
|
||||
## Running it
|
||||
|
||||
This machine's Python launcher is `py` (per identity.json); the script also
|
||||
runs under `python` / `python3`. Stdlib only -- no pip deps.
|
||||
|
||||
```bash
|
||||
# REPORT ONLY (default) -- writes _reports/<stamp>-dream.md and prints it
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py"
|
||||
|
||||
# report to stdout only, write nothing
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py" --no-file
|
||||
|
||||
# additive-only fixes (append orphan index lines, migrate profile-only files)
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/memory_dream.py" --apply-safe
|
||||
```
|
||||
|
||||
`CLAUDETOOLS_ROOT` resolves from the env var, else `claudetools_root` in
|
||||
`.claude/identity.json`, else the repo root derived from the script's own
|
||||
location -- no hardcoded drive letters.
|
||||
|
||||
## Cleanup / approve workflow
|
||||
|
||||
1. Run with no flag. Read the report (stdout or `_reports/<stamp>-dream.md`).
|
||||
2. Run `--apply-safe` to take the safe additive wins: orphan index lines get
|
||||
added, profile-only memories get migrated into the repo (conflicts skipped
|
||||
and reported).
|
||||
3. Work the `## PROPOSED` section by hand:
|
||||
- `[MERGE?]` -- decide whether to consolidate a cluster. If yes, author a new
|
||||
combined memory (or set of files for a rule/history split), retire the
|
||||
originals via `git rm`, update `MEMORY.md`. Deletions are now first-class
|
||||
— `sync-memory.sh` mirror mode will propagate them to every profile store
|
||||
on the next run.
|
||||
- `[REVERIFY?]` -- confirm the dated fact still holds; update the body and
|
||||
its date if it changed.
|
||||
- `[STALE-REF?]` -- confirm the referenced path moved/renamed; repoint or
|
||||
annotate. Many are legitimately server-side (`.service` units, `/opt/...`).
|
||||
- `[INDEX-CLEANUP?]` / `[DRIFT-RESOLVE?]` -- human picks the winner.
|
||||
4. Commit the repo store changes so they sync to the fleet via Gitea.
|
||||
|
||||
## Self-test
|
||||
|
||||
`scripts/selftest.py` runs the analyzer against a synthetic fixture memory
|
||||
store in a temp dir and asserts each detector fires (orphan, missing target,
|
||||
broken backlink, stale path, cluster, profile drift) and that `--apply-safe`
|
||||
only touches the things it's supposed to (index appends + profile→repo copy
|
||||
of new files; no deletions, no merges, no overwrites of differing content).
|
||||
Run:
|
||||
|
||||
```bash
|
||||
py "$CLAUDETOOLS_ROOT/.claude/skills/memory-dream/scripts/selftest.py"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user