| name | code-dreaming |
| description | Nightly (or on-demand) memory hygiene for AI coding agents — the thing native auto-memory does NOT do. Runs a "dream" pass over project memory to deduplicate entries, validate that every referenced file path still exists (so the agent never acts on "confidently wrong" stale references), compress survivors into a compact index, and detect when a new finding conflicts with an approved rule or CLAUDE.md — emitting a review-required conflict candidate and a proposed CLAUDE.md patch (never auto-applied). Use when memory has grown noisy/stale, on a nightly schedule, or whenever the user asks to dream/consolidate/clean up project memory, distill repeated workflows, or recall approved context. |
code-dreaming
Memory dreaming and garbage-collection for AI coding agents, plus a
project knowledge engine that indexes source code and git history. Native
auto-memory only ever grows; this skill periodically summarizes, consolidates,
and cleans. Invoke it as a skill on demand, or run it every night (see
Scheduling).
When to use
- Nightly, unattended — keep project memory deduped, path-valid, and consolidated.
- On demand — "dream / consolidate / summarize my memory", "did anything I
learned conflict with our rules?", or before relying on memory for a big task.
- Reset — when the user says
/code-dreaming clear, clear only the current
project's local memory after a dry-run/apply guard and backup.
- Directory scan — when the user asks to scan a folder and produce a dream file,
generate a bounded Markdown dream source and feed it to the LLM dream leg.
Default /code-dreaming behavior
The default /code-dreaming invocation must produce a dreaming summary
report, not a reset/clear report. Do not spawn a nested LLM from the default
skill path. The host agent that loaded this skill is the LLM entry. First write
a bounded report scaffold:
python3 BASE/scripts/dream_agent_report.py --repo-root REPO
Replace BASE with this skill's base directory and REPO with the user's
current project directory or explicit target directory. Then read the printed
report path and use the current host-agent turn to summarize durable findings or
state that no durable memory candidates were justified.
If the user adds free text after /code-dreaming (for example
/code-dreaming focus on coding-style preferences; ignore one-off debug notes),
forward it verbatim as --instructions "<free text>". This mirrors the official
Anthropic Dreams instructions field: it is bounded to 4096 chars,
secret-redacted, and rendered as a ## Steering Instructions section the host
agent must apply when deciding what to merge, drop, or surface.
The report also includes a deterministic ## Signal Scan section: a cheap,
bounded classification of the trajectory evidence into corrections
(highest priority), preferences, decisions, and recurring pain.
Signal Scan supports human, user, and assistant roles for cross-platform
trajectory compatibility (Claude Code uses user, the original design used
human).
Treat it as review-only evidence (no memory is written) that tells you where the
durable signals are — start there before scanning the raw preview.
Auto-index on first run: When no code-index database exists but source files
are present, the report auto-triggers code_index.py to build the initial
index before generating the report. This ensures even a brand-new session gets
useful project structure data.
Code-index enhanced report sections: When a code-index database exists
(.code-dreaming/code-index.db), the dream report includes these additional
sections:
| Section | Source | Content |
|---|
| Project Overview | CodeQueries.overview() | File count, language breakdown, symbol count, commit count, last indexed |
| Key Symbols | edges table | Top 15 symbols by caller+callee count (requires edges > 0) |
| Frequently Co-Changed Files | CodeQueries.coupling() | File pairs with Jaccard similarity >= 0.4 from git co-change history |
| Recent Activity | CodeQueries.changes_since() | Commits and file changes in the last 7 days |
Use --db PATH to override the default code-index DB location.
Use the user's current project directory or explicit target directory as
REPO. Do not replace it with git rev-parse --show-toplevel in multi-project
repositories. dream_agent_report.py writes inbox/dream-agent-*.report.md
under the project's native memory root and prints the report path. It may create the
default native memory/ directory when the project only has Claude Code
transcript .jsonl files.
Only invoke scripts/reset_memory.py when the user explicitly asks for
/code-dreaming clear, reset, or memory deletion.
Cold Start (first run on a new project)
When no trajectory evidence AND no code-index database exist, the dream report
returns a Cold Start guidance document instead of a normal report:
- Status: "No trajectory evidence and no code-index database were found"
- Steering Instructions: (only if
--instructions provided)
- How to Get Started: instructions to index the project or start a session
- Next Steps: concrete commands to run
If source files exist but no DB, the report auto-triggers code_index.py to
build the initial index before generating the report.
Code Index & Queries
Building the Index
python3 scripts/code_index.py --repo-root . --db .code-dreaming/code-index.db
First run: full tree-sitter parse + git log. Subsequent runs: incremental
(only changed files re-parsed). Typical: 500 files in 2-5s first run, <200ms
incremental.
Supported languages: Python, JavaScript, TypeScript (P0, bundled grammars).
Go, Rust, Java, C, C++ (P1, install additional grammars).
Graceful degradation: missing grammar -> file indexed as text-only (path +
size + hash, no symbols/edges).
Edge extraction: Tree-sitter extracts symbols (functions, classes, methods)
and relationships: calls, imports, extends, implements, references.
The callers()/callees() API and Key Symbols report section require edges.
Python and JavaScript/TypeScript edge extraction is implemented.
Querying the Index (Python API)
from scripts.code_queries import CodeQueries
with CodeQueries(".code-dreaming/code-index.db") as cq:
cq.overview()
cq.search("dream")
cq.file_symbols(path)
cq.callers("func")
cq.callees("func")
cq.coupling(path)
cq.changes_since(date)
Git History Adapter
python3 scripts/git_adapter.py --repo-root . --db .code-dreaming/code-index.db
Parses git log --numstat into commits + commit_files tables, computes
file-coupling Jaccard scores. When no session trajectory exists, git history
serves as a fallback evidence source for the dream report.
Team Sharing (artifact export/import)
python3 -m mce.cli artifact export --db .code-dreaming/code-index.db
python3 -m mce.cli artifact import --input code-index.db.zst
What deterministic maintenance does (scripts/dream.py)
- Dedup near-identical episodes (task + decisions signature).
- Validate stale paths — every
files_touched[] is checked against the real
repo; missing ones are annotated # STALE (or dropped) so the agent stops
acting on deleted files ("confidently wrong").
- Compress survivors into
semantic/dream-index.md (the compact index).
- Detect conflicts — a new decision that contradicts an approved rule or
a
CLAUDE.md rule → writes a conflict-candidate to inbox/ and a
proposed CLAUDE.md patch. It never edits CLAUDE.md; a human reviews and
git applys.
- Optionally verify symbols + health —
--verify-symbols checks explicit
symbols: / symbols_touched: references; every run reports the memory
size budget.
The explicit external LLM leg (bin/dream-llm.sh) uses a vendored dream prompt
and adapts the source-of-truth input to the local trajectory source when one is
available. If no trajectory is available, proposed promotions are marked
[unverified]. Use it only when explicitly requested or from automation that
intentionally wants a separate LLM process; it is not the default skill entry.
Deterministic maintenance is dry-run by default; pass --apply to rewrite
L2 memory/index artifacts.
Operations (agent-invokable)
| Op | Command |
|---|
dream-report (default /code-dreaming) | python3 BASE/scripts/dream_agent_report.py --repo-root REPO [--memory-dir DIR] [--trajectory PATH] [--instructions TEXT] [--output-mode native|project-root] [--out-dir DIR] [--keep N] [--db PATH] |
| code-index (build/update) | python3 BASE/scripts/code_index.py --repo-root REPO [--db PATH] [--languages PY,JS,...] [--max-files N] |
| git-history (parse & store) | python3 BASE/scripts/git_adapter.py --repo-root REPO [--db PATH] [--max-commits N] [--since DATE] |
| artifact export | python3 -m mce.cli artifact export [--db PATH] [--output PATH.zst] |
| artifact import | python3 -m mce.cli artifact import [--input PATH.zst] [--db PATH] |
| dream-maintenance (deterministic cleanup) | `python3 scripts/dream.py --memory-dir DIR --repo-root REPO [--apply] [--verify-symbols] [--scope-filter auto |
| clear/reset current memory | python3 scripts/reset_memory.py --repo-root REPO [--memory-dir DIR] [--apply] [--allow-parent] |
| scan-dir (make dream source) | python3 scripts/scan_to_dream.py DIR --output OUT.md |
| dream-llm (explicit external LLM runner) | bin/dream-llm.sh --repo-root REPO --claude-bin CMD [--memory-dir DIR] [--trajectory PATH] |
| writeback (verified candidates → Mem0) | `python3 -m mce.cli writeback --memory-dir DIR --repo-root REPO --org ORG --mode review |
| run plan (unified executor) | `python3 -m mce.cli run --plan dream-writeback --memory-dir DIR --repo-root REPO --org ORG --mode review |
| distill (mine SOPs) | python3 scripts/distill.py --memory-dir DIR --min-support 2 [--apply] |
| retrieve (recall) | python3 -m mce.cli retrieve --query "<task>" --max-items 5 --max-tokens 2000 |
| capture (write to L2) | python3 -m mce.cli capture --text "<fact>" --org acme |
--memory-dir defaults to the native Claude Code project memory
(~/.claude/projects/<key>/memory). --repo-root/--repo-claude locate the
files and CLAUDE.md to validate against.
If native Claude memory resolves to a parent workspace, --scope-filter auto
skips sibling-project memories that do not mention the current repo identity
(for example code-dreaming). Use --scope-filter off only when intentionally
dreaming the whole parent memory root.
For deterministic maintenance, use the user's current project directory or
explicit target directory as --repo-root; do not replace it with
git rev-parse --show-toplevel in multi-project repositories, because that
maintains the parent workspace instead of the current project. Prefer running
scripts by absolute skill path from the user cwd instead of cd-ing into the
skill directory.
When the user invokes /code-dreaming clear, run scripts/reset_memory.py
against the user's current project directory. Default is dry-run and prints the
memory artifacts that would be removed. Only pass --apply when the user
explicitly asks to apply/confirm the clear. If native Claude memory resolves to
a parent workspace, the script refuses by default; use --allow-parent only
when the user explicitly wants to clear that parent workspace memory. Every
apply run writes a backup beside the active memory directory before deleting.
After an allowed parent clear, apply mode creates the exact current-project
native memory directory so the next code-dreaming run resolves to the current
project instead of falling back to the parent empty memory root. Use
--no-init-exact only when intentionally preserving parent-root resolution.
For folder-to-dream requests, run:
python3 scripts/scan_to_dream.py /path/to/dir --output /tmp/dir.dream.md
python3 BASE/scripts/dream_agent_report.py --memory-dir DIR --repo-root /path/to/dir --trajectory /tmp/dir.dream.md
The scanner is deterministic glue: it redacts obvious secrets, skips common
heavy folders (.git, node_modules, vendor, build caches), bounds file
content, and emits Markdown that the existing dream trajectory adapter reads.
For repeated runs, use a manifest so only changes are sent to the LLM:
python3 scripts/scan_to_dream.py /path/to/dir --output /tmp/full.dream.md --write-manifest /tmp/dream-manifest.json
python3 scripts/scan_to_dream.py /path/to/dir --output /tmp/delta.dream.md --since-manifest /tmp/dream-manifest.json --write-manifest /tmp/dream-manifest.next.json
This mirrors the reconcile fingerprint idea: walk the tree for correctness,
but skip unchanged file content in delta dream input.
Installing this skill
Build and install the loadable skill bundle:
bin/install-skill.sh --target both --mode copy
This writes:
- Codex:
${CODEX_HOME:-$HOME/.codex}/skills/code-dreaming
- Claude Code:
$HOME/.claude/skills/code-dreaming
For project-local Claude Code use, copy or symlink the built bundle to
.claude/skills/code-dreaming.
Scheduling (nightly)
Run bin/dream-nightly.sh from cron / the schedule skill / loop. See
runbook.md. It uses smart skip gates: too-young projects and
recently dreamed projects are skipped unless MCE_FORCE=1. Start in dry-run for
a week, read the reports, then enable MCE_APPLY=1. Set MCE_LLM=1 to add the
review-only LLM leg after deterministic dream.
Output location & team sharing
By default the report goes to the native Claude memory root
(~/.claude/projects/<key>/memory/inbox/) — private to one developer and not
auto-discoverable. For multi-member teams that want to commit and share dream
findings, switch the artifact base:
| Mode | Flag | Base dir | Use |
|---|
| native (default) | (none) | ~/.claude/.../memory | private, per-developer |
| project-root | --output-mode project-root | <repo>/.code-dreaming/ | git-shareable across the team |
| explicit | --out-dir ./memory | ./memory/ | any path you choose |
Every mode writes inbox/dream-agent-*.report.md plus a skill-owned
DREAMS.md index (newest-first, with signal-count summaries) and applies
--keep N retention (default 20; 0 = unlimited) so reports never pile up.
Trajectory evidence is always read from the native memory root, so dedup/recall
stay coherent regardless of where the report is written.
In project-root/--out-dir mode the skill also writes
POINTER.suggested.md: the one line a human pastes into the repo CLAUDE.md
(reviewed via PR) so every teammate's next session auto-discovers the shared
index. The skill never edits CLAUDE.md itself.
Team flow: run /code-dreaming with --output-mode project-root → commit
.code-dreaming/ → once, add the suggested CLAUDE.md pointer via PR. After
that, every member's sessions auto-load the shared, review-only dream index.
Interactive auto-trigger (opt-in, no nested LLM)
For interactive users who do not run cron, an optional Stop hook can flag a due
dream that the next real session's host agent then runs — no LLM is spawned
from the hook. Two opt-in steps:
- Register the Stop hook in
~/.claude/settings.json (the skill never edits
settings for you):
"hooks": { "Stop": [{ "type": "command",
"command": "bash $HOME/.claude/skills/code-dreaming/bin/dream-stop-hook.sh" }] }
On session end it runs should_run.py pending for the current project: if the
schedule gate (same interval as cron, MCE_DREAM_INTERVAL_DAYS, default 7
days) is eligible, it writes a project-scoped .dream-pending flag under the
native memory dir. It always exits 0 and never calls an LLM.
- Add a session-start directive to your project (or global)
CLAUDE.md:
Auto Dream (code-dreaming): At session start, run
python3 $HOME/.claude/skills/code-dreaming/scripts/should_run.py pending-status --repo-root ..
If it exits 0, run /code-dreaming, then run the same script with
clear-pending to remove the flag and reset the timer.
This keeps the host-agent-only principle intact: the hook only schedules; the
actual dream is executed by a real host-agent turn.
Governance (always on)
dedup/stale repair touch only L2 episode files · CLAUDE.md/AGENTS.md are
never auto-edited (conflicts → inbox/ + proposed patch) · capture is
ADD-only, scoped, secret-filtered · recall is top-k under a token budget.
LLM dream also writes only review artifacts (memory-md.<stamp>.proposed.patch
plus latest alias memory-md.proposed.patch,
memory-md.cumulative.proposed.patch for multi-run review, optional
global-memory.proposed.patch, report files).
Automatic Mem0 writeback is explicit and audited: --mode review only writes
inbox/writeback-<stamp>.jsonl; --mode apply writes only verified or
repo-verified candidates through Mem0, relying on Mem0 entity linking for
graph-like memory rather than custom graph writes.
Not in scope
Instruction layering and the tier/index format are delegated
to native Claude Code and intentionally not part of this skill.
Files
scripts/code_index.py (tree-sitter indexer + SQLite graph) ·
scripts/git_adapter.py (git history adapter) ·
scripts/code_queries.py (query API over code-index.db) ·
scripts/dream_agent_report.py (enhanced dream report) ·
scripts/dream.py (deterministic maintenance) · scripts/reset_memory.py ·
scripts/distill.py · mce/ glue (backbone/retrieve/cli) ·
assets/tree-sitter/ grammar installer ·
upstream/maas-code/ upstream mirror · prompts/ fallback prompt copies ·
assets/ config + schemas · vendor/ upstreams · demo/ runnable demo ·
runbook.md.
