memory

name	memory
description	File-based, agent-curated permanent memory layer that lives inside the user's existing Obsidian vault. Captures durable preferences / workflows / fixes via a reflection sidecar; recalls relevant entries automatically into every new prompt via SessionStart + UserPromptSubmit hooks; adapts the agent's behavior over time without explicit configuration. The goal is compound learning — each conversation makes the next one better, because the agent never forgets what already happened.
kind	skill
supported_hosts	["claude-code","antigravity"]
version	0.1.0
install_scope	project

memory — permanent agent memory via Obsidian-vault-folder + reflection sidecar

The first toolkit skill that integrates with the user's own personal note-taking surface (Obsidian) rather than maintaining a separate agent-only vault. The skill exposes four sub-commands (save / evolve / reflect / search); recall is hook-driven rather than user-invoked (SessionStart + UserPromptSubmit hooks shipped alongside in the recall-loop part).

Position vs. built-in agent memory (Claude memories, vendor-specific context features): built-in memory is per-platform, opaque, lossy, and not composable across tools. MemoryVault is file-based + version-control-friendly + human-inspectable. The user can open Obsidian + read or edit any captured entry directly; the agent's memory + the user's notes coexist in the same place.

Position vs. session transcripts: Claude Code transcripts capture everything that happened. MemoryVault captures what's worth keeping forever — the durable preferences / workflows / fixes that make Day 2 better than Day 1.

When to reach for which sub-command

You want to...	Reach for
Capture a specific preference / workflow / fix manually right now	/memory save
Stage a casual thought, link, or idea for later triage — not yet reviewed	/memory capture
Read a web page or file into memory as a full document plus retrieval chunks	/memory ingest
Replace an existing entry with a corrected version (preserving audit trail)	/memory evolve
Run reflection over the current session transcript on demand (or a specified transcript path)	/memory reflect
Mine the full historical transcript backlog (~/.claude/projects/*/) with dry-run preview + resume-safe batching	/memory reflect corpus
Search the vault for entries matching a query (when auto-recall via UserPromptSubmit hook didn't pull what you wanted)	/memory search
Refresh the auto-indexed personal-skills/ pointers (after a SKILL.md change, or on a fresh install)	/memory index-skills
Manually trigger the internet skill-discovery scan (cadence-checked by default via the idle hook)	/memory discover-skills
Run the adapt-don't-import workflow over discovered patterns (Python rubric → enriched JSONs → LLM sub-agent judgment → watchlist entries)	/memory adapt-skills
Review pending entries in _skill-watchlist/ — promote / dismiss / defer	/memory watchlist
Bulk-triage the _inbox/ backlog — promote (reinforced) / merge (near-duplicate) / expire (stale)	/memory inbox --bulk-review
See what the heat-based always-load policy would demote or promote (never applies without --apply)	/memory heat-policy
Check the vault for orphans, broken links, contradictions, and a per-note quality score — on demand (the weekly dreaming cycle also runs this automatically)	/memory lint

Auto-recall happens via the SessionStart + UserPromptSubmit hooks — operators don't invoke a recall command directly. Reflection happens automatically via Stop + idle hooks too; the manual /memory reflect is for one-off runs against arbitrary transcripts.

Sub-commands

/memory save

Synchronously writes a markdown entry to MemoryVault. File write returns immediately (<50ms target); embedding + vec-index update are async and deferred (the actual embedding integration lands in task 4 of plan #7a part 1; until then the embedding step is a no-op stub that logs "embedding queued (deferred to task 4)").

Invocation

/memory save <kind> <slug> [--group <group>] [--always-load] [--vault-path <path>]
                            [--tags <tag1,tag2,...>] [--supersedes <old-path>]

Arg	Required	Default	Meaning
<kind>	yes	—	Entry kind (preference / workflow / fix / domain-reference / idea / etc.). Subdir name under the chosen group.
<slug>	yes	—	Kebab-case identifier; filename stem. Validated as ^[a-z0-9-]+$.
--group <group>	no	personal-private	Memory group: personal-private / personal-skills / projects/<project-slug>.
--always-load	no	false	Routes to MemoryVault/personal-private/_always-load/<slug>.md and sets always_load: true frontmatter — entry gets injected at SessionStart per the recall-loop part. Overrides --group (always lands in _always-load).
--vault-path <path>	no	from config	Absolute path to the MemoryVault folder. Resolution order: --vault-path arg > MEMORY_VAULT_PATH env var > ~/.config/crickets/memory.yml vault_path: key > error.
--tags <tag1,tag2>	no	empty list	Comma-separated tags; written to tags: frontmatter list.
--supersedes <old-path>	no	empty	Path to an existing entry this new entry supersedes. Sets supersedes: frontmatter; does NOT archive the old entry — that's /memory evolve's job (task 3). --supersedes is for cross-link-without-archive cases.

The entry body (free-form markdown after the YAML frontmatter) comes from stdin OR an interactive prompt. The agent following the skill body asks for the body content if not piped.

Step-by-step flow

Step 1 — Resolve vault path. Walk the resolution order: --vault-path arg → MEMORY_VAULT_PATH env var → ~/.config/crickets/memory.yml (vault_path: key). If none found, halt with "No vault path resolved. Set --vault-path, MEMORY_VAULT_PATH, or ~/.config/crickets/memory.yml vault_path: <path>.". Verify the resolved path exists and is a directory; halt otherwise with a clear error.

Step 2 — Validate inputs. <kind> and <slug> must match ^[a-z0-9-]+$ (kebab-case). --group (if provided) must match ^[a-z0-9-]+(/[a-z0-9-]+)?$ (kebab-case; one optional /<project-slug> segment for projects/<slug>). Tags (if provided) each must match ^[a-z0-9-]+$. Halt on any validation failure with a clear error pointing at the offending arg.

Step 3 — Compute target path. Two cases:

• --always-load set: <vault-path>/personal-private/_always-load/<slug>.md
• --always-load not set: <vault-path>/<group>/<kind>/<slug>.md (with <group> defaulting to personal-private)

Create parent directories if they don't exist (via Write tool's implicit dir creation, or explicit Glob + Write for clarity).

Step 4 — Collision check. If the target path already exists, halt with "Entry already exists at <path>. Use /memory evolve to supersede the existing entry, or pick a different slug.". Never overwrite an existing entry from /memory save — that's /memory evolve's job.

Step 5 — Build frontmatter. Construct YAML frontmatter with these fields:

---
kind: <kind>
status: active
created: <today UTC, YYYY-MM-DD>
updated: <today UTC, YYYY-MM-DD>
tags: [<tag1>, <tag2>, ...]   # empty list [] if no --tags
group: <group-or-personal-private>
slug: <slug>
always_load: <true-if-flag-set-else-false>
supersedes: <old-path-if-flag-set>   # omit field entirely if no --supersedes
---

Frontmatter field order is locked above for deterministic diffs. The always_load field is always present (true or false) so the recall hooks can grep for it without ambiguity.

Step 6 — Compose entry content. Prepend the frontmatter to the body content. Final shape:

---
<frontmatter>
---

<body markdown>

Trailing newline at EOF.

Step 7 — Write file. Use the Write tool to create the file at the computed target path. Verify the write succeeded (Write tool returns success/error). File write is synchronous; on success, the file is on disk before the next step.

Step 8 — Queue async embedding + vec-index update. Until task 4 of this plan lands (embedding integration), this step is a no-op stub: log "embedding queued (deferred to task 4)" and continue. After task 4 ships, this step kicks off an async embedding call to the configured provider (Anthropic API default; local sentence-transformers fallback per memory.use_api_embeddings) and writes the embedding to MemoryVault/_meta/vec-index.db via sqlite-vec. The async-ness ensures file write is never blocked by network or vec-index latency.

Step 9 — Return confirmation. Report success to the operator with:

Saved entry to <relative-path-from-vault-root>/<slug>.md
  kind:  <kind>
  group: <group>
  tags:  <tags-or-(none)>
  flags: <always-load-and-supersedes-if-set>

Plus the deferred-embedding note: "(Embedding deferred to plan #7a part 1 task 4; index will populate on next reindex.)".

Tool allowlist

Read, Write, Edit, Glob, Grep — no Bash. The skill body never invokes shell commands directly. The agent following this body uses Write to create the entry file; Read to check config files for vault-path resolution; Glob to discover existing parent directories. Python scripts under skills/memory/scripts/ (added in this task + tasks 3 + 4) handle the heavy lifting when invoked from Claude Code hooks (which run as standalone scripts, not as skill bodies) — see Tool allowlist section below for the skill-vs-script split.

Hard gates

• Collision check is non-negotiable — /memory save never overwrites. Operators wanting to replace an entry use /memory evolve (task 3).
• Vault path must resolve — no implicit fallback to cwd or ~; explicit error if no resolution path succeeds. Prevents accidental writes to wrong directories.
• Kind / slug / group validation is strict — kebab-case only. Catches typos before they create unparseable directory structures.

Worked example

Saving a dev-flow convention as an _always-load entry:

Invocation:

/memory save preferences paragraph-long-status-narratives \
  --always-load \
  --tags dev-flow,status-reports,locked-design-call \
  --vault-path ~/Library/CloudStorage/GoogleDrive-<account>/My\ Drive/Obsidian/MemoryVault

(With the entry body provided via stdin or the agent prompting interactively.)

Step 1 — --vault-path provided → resolved to the synced Obsidian vault root. Exists + is a directory. ✓

Step 2 — kind=preferences ✓; slug=paragraph-long-status-narratives ✓; --always-load set → group ignored. Tags [dev-flow, status-reports, locked-design-call] each match ^[a-z0-9-]+$ ✓.

Step 3 — --always-load set → target path: <vault>/personal-private/_always-load/paragraph-long-status-narratives.md. Parent dir created if absent.

Step 4 — Collision check: path does not exist → proceed.

Step 5 — Build frontmatter:

---
kind: preferences
status: active
created: 2026-05-17
updated: 2026-05-17
tags: [dev-flow, status-reports, locked-design-call]
group: personal-private
slug: paragraph-long-status-narratives
always_load: true
---

Step 6 — Compose with body:

---
<frontmatter>
---

Status:[x] task closeouts in the active plan file (`.harness/PLAN.md` or `PLAN-<name>.md`) must be paragraph-long narratives,
not just checkmarks. The next session's context is whatever the closeout captures —
so capture everything that matters: files changed, design calls, scope adjustments,
CI per-OS times, manual verification scenarios, negative-test results when relevant.

Step 7 — Write file at the target path. ✓

Step 8 — Log "embedding queued (deferred to task 4)".

Step 9 — Report:

Saved entry to personal-private/_always-load/paragraph-long-status-narratives.md
  kind:  preferences
  group: personal-private (overridden by --always-load → _always-load)
  tags:  dev-flow, status-reports, locked-design-call
  flags: always_load

(Embedding deferred to plan #7a part 1 task 4; index will populate on next reindex.)

Failure modes

• Missing vault path — all 3 resolution paths fail → halt with clear next-step text pointing at the 3 resolution options.
• Vault path exists but is not a directory — halt with "<path>: not a directory." and exit; never write to a file path treated as a vault root.
• Invalid kind / slug / group / tags — halt with the specific arg + the expected kebab-case shape; never coerce or silently lowercase.
• Target file exists — halt with the /memory evolve recommendation; never overwrite from /memory save.
• Write tool fails (disk full, permission denied, etc.) — surface the Write tool's error verbatim + a hint that the entry was NOT saved.

Anti-patterns

/memory save must NOT:

• Overwrite an existing entry — Step 4 collision check is the hard gate.
• Block on embedding — Step 8 is async-deferred; file write must complete before any network call.
• Coerce slugs — operator provides exact slug; validator rejects, never auto-lowercases or strips characters.
• Default vault path to cwd or ~ — explicit resolution chain; no implicit defaults that could write to wrong directories.
• Modify Document History or other special files in the vault — /memory save is a single-file-write primitive; cross-file ops are for /memory evolve (task 3) + the reflection sidecar (plan #7a part 3).

Python-side script (scripts/save.py)

In parallel with the agent-driven skill body, this part also ships a standalone Python script at crickets/skills/memory/scripts/save.py that implements the same save logic for hooks (which run as standalone Python scripts, not as skill bodies) + operator-debug (manual python3 ... invocation) + testing (deterministic fixture tests that don't require an agent).

The script exposes:

• Function: save_entry(vault_path, kind, slug, body, *, group="personal-private", always_load=False, tags=None, supersedes=None) -> pathlib.Path — the canonical save primitive. Returns the absolute path written. Raises FileExistsError on collision; ValueError on validation failure; FileNotFoundError if vault path doesn't exist.
• CLI entry point: python3 save.py <kind> <slug> --vault-path <path> [--group <g>] [--always-load] [--tags <t1,t2>] [--supersedes <p>] [--body-file <path-or-->] — same flag semantics as the skill body's /memory save invocation. --body-file - reads from stdin.

Both paths (skill-body Write + script-CLI Python) produce byte-identical entry files for the same inputs. Future hooks (plan #7a part 3's reflection sidecar) import + call save_entry() directly. The skill body's documented flow is operator-facing; the script is hook-facing; they don't compete.

/memory capture

The second front door beside /memory save — designs/friday/agentm-capture.md's capture-from-anywhere front door. /memory save writes straight to permanent memory; /memory capture stages a candidate to <vault>/personal/_inbox/ instead, for the automated triage system to promote, merge, or expire later. Use save for an explicit, deliberate write you already know the destination for; use capture for a casual thought, a link, or an idea that hasn't been reviewed yet.

Canonical implementation: scripts/capture.py's capture() function, writing via vault_lock.atomic_write directly (genuinely atomic, unlike reflect.py's own inbox writer) — never through save_entry, since _inbox fails save_entry's kebab-case kind validation by design (the standing convention that keeps staged items structurally distinct from validated permanent-memory destinations).

Invocation

python3 skills/memory/scripts/capture.py "<content>" \
  [--vault-path <path>] [--kind capture|idea] [--slug <slug>] \
  [--source <transport>] [--surface <device>] [--tags <t1> <t2> ...] \
  [--instructions <text>] [--source-url <url>]

Flag	Use case
content (positional)	The captured text — a thought, or a link plus a note.
--kind	capture (default — a thought, link, or note) or idea (routes toward the ideas ledger once that fold exists).
--slug	Override the default timestamp-based slug (capture-YYYYMMDDTHHMMSS). A collision on either the default or an explicit slug appends a numeric suffix (-1, -2, …) rather than overwriting — the inbox is a raw-capture surface where a resend landing twice is an accepted, designed-for case.
--source	The transport, e.g. cli, clipper. Defaults to cli when invoked from the command line.
--surface	The device, e.g. phone, desktop.
--tags	Zero or more kebab-case tags.
--instructions	An operator-typed action to run after the candidate is absorbed, e.g. "add to my ideas ledger". Security invariant, mechanically enforced: this field carries only the literal text passed to this flag — never text parsed or inferred from content. A captured article whose body contains something that reads like an instruction ("ignore previous instructions...") never gains authority; that text is inert data.
--source-url	The link this capture is about, if any — marks the candidate for the ingest sweep's full processing once that sweep exists (capture design part 3).

The candidate shape

A capture's frontmatter carries kind, status: inbox, created, captured (both full ISO8601 timestamps — created mirrors save.py's convention, captured is the exact capture moment; a chat-surface caller's estimate of captured gets corrected later by the ingest sweep's re-stamp), slug, and optionally source, surface, tags, source_url, instructions. The staging folder is excluded from ordinary recall by default — a captured note becomes recallable only after the triage system promotes it.

The memory_capture MCP tool

The same door, callable by any connected MCP host: memory_capture(content, kind="capture", title=None, tags=None, instructions=None, source_url=None) -> {success, id, slug} or {success: false, error} on failure — a capture is never silently dropped. Registered alongside memory_search / memory_append / memory_forget in scripts/memory_mcp_tools.py.

Failure modes (graceful)

• Unknown kind → returns success: false with the specific error; nothing written.
• Empty content → returns success: false; nothing written.
• Vault not resolved → the CLI exits 2 with a clear remedy (--vault-path or $MEMORY_VAULT_PATH); the MCP tool raises via the shared _require_vault() path every other tool uses.
• Write failure (disk full, permissions) → returns success: false with the underlying error message — never a silent drop.

Anti-patterns

• Don't populate instructions from anything other than this call's own explicit argument. A caller that derives it from content (or any fetched/untrusted text) breaks the capture design's trust-boundary invariant at the call site.
• Don't choose a destination. /memory capture has no --group/project parameter by design — every write lands in _inbox/; only the triage/ingestion machinery (a later capture part) ever promotes it elsewhere.

/memory ingest

Capture part 2 — designs/friday/agentm-capture.md's article-ingestion door, sibling to /memory capture. Where capture stages a candidate for later triage, ingest reads a web page or file right now and writes it straight into permanent memory as two forms that always ship together: one intact full-document note (the complete original text, unmodified) and a set of small, reading-order-linked chunk notes for retrieval. Neither form replaces the other — this is the only capture-family door that produces more than one note per item.

Canonical implementation: scripts/ingest.py's ingest() function. Both the document note and every chunk go through save_entry() (unlike /memory capture's direct _inbox/-only write) — these are permanent-memory writes from the start, each individually validated and queued for search indexing.

Invocation

python3 skills/memory/scripts/ingest.py <url-or-file> \
  [--vault-path <path>] [--topic <slug>]

Flag	Use case
<url-or-file> (positional)	A URL (fetched via a single stdlib urllib GET, no HTTP dependency) or a local file path.
--topic	The topic slug (kebab-case) notes for this ingest are tagged and slug-prefixed with. Omit it to get a suggestion first — the command extracts a title-based slug and stops without writing anything; re-run with --topic <suggested-or-your-own> to actually ingest. This is a real confirmation step, not an auto-accept.
--vault-path	Same resolution chain as /memory save: arg > MEMORY_VAULT_PATH env > error.

What gets written

• The full-document note (kind: domain-reference, group: personal) — the complete extracted text, verbatim. HTML content is tag-stripped (a lightweight <title>/paragraph extractor, not a readability algorithm — scripts and styles are dropped, everything else becomes plain text); a local plain-text or markdown file passes through unmodified.
• The chunk notes (same kind/group) — one per chunking.py's chunk_text() output, each carrying a footer that links back to the full document and to its immediate reading-order neighbors (previous/next only — the first chunk has no "previous," the last has no "next," so the chain never cycles).
• Every note carries source_url/source_fetched when the source was a URL (omitted for local files), and a tags: [<topic>] entry. Slugs are <topic>-<title-slug> for the document and <topic>-<title-slug>-chunk-N for each chunk, so same-topic ingests sort together even though they share the flat group: personal every other kind in this vault uses (the design's own "filed under personal/domains/<topic>/" phrasing describes the intent — discoverable by topic — which this achieves through slug-prefixing and tagging rather than a new per-topic directory layer save_entry's group/kind/slug path formula has no clean way to produce without breaking the flat-group-per-kind convention every other entry follows).

Failure modes (graceful)

• Fetch/read failure (bad URL, network error, missing file) → returns success: false with the underlying error; nothing written. No retry, no paywall handling — that resilience is the ingest sweep's job (capture part 3), not this command's.
• Empty content → returns success: false; nothing written.
• Vault not resolved → the CLI exits 2 with a clear remedy.

Anti-patterns

• Don't skip the topic-confirmation step in scripted/agent use. A caller that always guesses --topic up front without surfacing the suggestion defeats the design's "the agent suggests a title-based slug for you to confirm" intent — treat the no---topic suggestion as a real prompt, not dead code.
• Don't retune chunk_text()'s parameters here. This command calls the existing chunking function unmodified; chunk-size tuning is out of this door's scope.

/memory evolve

Atomic archive-and-replace primitive that prevents memory rot when preferences change. The old entry gets archived with status: superseded; the new entry takes the old entry's place (in-place by default; renamed slot via --new-slug for evolutions that also rename). Both files cross-link via supersedes / superseded_by frontmatter so the supersession graph is queryable. Recall filters skip status: superseded entries by default (documented contract — implemented in the recall engine, plan #7a part 2).

Invocation

/memory evolve <old-path> <reason> [--new-slug <slug>] [--body-file <path-or-->]
                                    [--vault-path <path>]

Arg	Required	Default	Meaning
<old-path>	yes	—	Relative path from vault root to the entry being superseded (e.g. personal-private/preferences/foo.md).
<reason>	yes	—	Free-text rationale recorded in the archive's superseded_reason frontmatter. Captures WHY this evolution happened — important for audit-trail review.
--new-slug <slug>	no	(same slug as old)	If set, the new entry lands at <old-parent-dir>/<new-slug>.md (renamed evolution). If absent, the new entry takes the old entry's slot (in-place evolution; same slug). Validated as ^[a-z0-9-]+$.
--body-file <path-or-->	no	- (stdin)	Path to file with the new entry body, or - to read from stdin.
--vault-path <path>	no	from config	Same resolution chain as /memory save: --vault-path arg > MEMORY_VAULT_PATH env > config (deferred) > error.

Step-by-step flow

Step 1 — Resolve vault path + validate. Same resolution chain as /memory save. <old-path> must exist relative to vault root + be a file. <reason> must be non-empty. --new-slug (if provided) must be kebab-case.

Step 2 — Read old entry. Parse YAML frontmatter + body from <old-path>. The old frontmatter must have status: active — refuse to evolve already-superseded or resolved entries (escape hatch: operator can edit status manually if they really want to evolve a superseded entry, but the skill doesn't do it).

Step 3 — Compute target paths.

• Archive path: MemoryVault/personal-private/_archive/<original-relative-path>.<YYYYMMDD>.md. Example: personal-private/preferences/foo.md → personal-private/_archive/personal-private/preferences/foo.md.20260517.md. (The double-personal-private reflects preserving the original path structure under the archive prefix so the relationship is reconstructable.)
• New entry path: if --new-slug set → <old-parent-dir>/<new-slug>.md; else → same as <old-path> (in-place).

Step 4 — Build archive content. Take the old entry's frontmatter + body, then update the archive's frontmatter:

• status: active → status: superseded
• Add superseded_by: <relative-path-from-vault-to-new-entry>
• Add superseded_at: <ISO-8601 UTC timestamp> (YYYY-MM-DDThh:mm:ssZ)
• Add superseded_reason: <reason> (escaped for YAML safety)
• Preserve all other fields verbatim (kind, created, tags, group, etc.)

The body stays unchanged in the archive — the archive is a point-in-time snapshot.

Step 5 — Build new entry content. Frontmatter inherits relevant fields from old (kind, group, tags) but resets:

• status: active
• created: <today UTC> (today; the new entry's creation date is the evolution date)
• updated: <today UTC>
• slug: <new-slug-or-old-slug>
• supersedes: <relative-path-from-vault-to-archive> ← cross-link back
• always_load: inherited from old (operator can override by re-running with explicit args if they want to change it; default is "inherit").

The new entry's body comes from --body-file (or stdin via -).

Step 6 — Atomic-ish write sequence. Two-phase write:

1. Write archive at <archive-path> (create + content via Write tool). This is purely additive — no state change to existing files yet.
2. Replace old entry:
   • In-place case (<new-path> == <old-path>): Write tool overwrites <old-path> with new content. Filesystem-atomic at the syscall level on APFS / ext4 / NTFS-same-volume.
   • Renamed case (<new-path> != <old-path>): Write tool creates <new-path> with new content + Glob/Read-confirms old still there + delete old via a future filesystem op (skill body uses Write to create new + leaves the old in place as a transitional state — until the recall filter starts skipping _archive/-rooted paths, leaving the old entry temporarily doesn't pollute recall). Operator can clean up the old entry's location manually after verifying the new entry.

The Python-side script (scripts/evolve.py) does both write + unlink atomically via os.rename + temp-file pattern — see the Python-side script section below.

Step 7 — Queue async vec-index update for both files. Until task 4 lands, this step is a no-op stub: log "vec-index update queued for: <new-path>, <archive-path> (deferred to task 4)". After task 4, both files get re-indexed: archive is marked status:superseded (so recall filters skip it) + new entry is freshly indexed.

Step 8 — Return confirmation.

Evolved entry:
  old: <relative-old-path> → archived to <relative-archive-path>
  new: <relative-new-path>
  reason: <reason>
  status: old=superseded, new=active

Tool allowlist

Read, Write, Edit, Glob, Grep — no Bash. The skill body uses Read for the old entry, Write for both archive + new entry, Glob for confirming paths. The atomic-rename guarantee in the Python-side script comes from os.rename() (called within scripts/evolve.py, which is dispatched from hooks but not from the skill body).

Hard gates

• Old entry must exist + have status: active — refuse to evolve missing entries or already-superseded entries (escape hatch is manual frontmatter edit).
• <reason> is non-empty + non-trivial — single-word reasons like "updated" accepted but flagged in the confirmation output ("consider a more descriptive reason for the audit trail").
• Archive path collision check — if <archive-path> already exists (rare; would happen if you evolved the same entry twice on the same day), append -N suffix until unique.
• Slug rename validation — --new-slug must be kebab-case; matches /memory save's slug discipline.
• No evolve on _always-load/ entries via slug rename — --new-slug doesn't apply to entries in _always-load/; those evolve in place only (operator can manually move + edit if they really want to rename an always-load entry). Skill body refuses with a clear error.

Worked example

In-place evolution of a stale preference:

Invocation:

/memory evolve personal-private/preferences/paragraph-long-status-narratives.md \
  "Switched preference: now want short bullet lists per task closeout, not paragraphs" \
  --body-file -

(With the new body piped via stdin.)

Step 1 — vault path resolved; old path exists + readable; reason non-empty. ✓

Step 2 — Read old entry, parse frontmatter:

kind: preferences
status: active
created: 2026-05-17
updated: 2026-05-17
tags: [dev-flow, status-reports, locked-design-call]
group: personal-private
slug: paragraph-long-status-narratives
always_load: true

Status is active ✓ → can evolve.

Step 3 — Compute paths:

• Archive: personal-private/_archive/personal-private/preferences/paragraph-long-status-narratives.md.20260517.md
• New entry: personal-private/preferences/paragraph-long-status-narratives.md (in-place; same slug)

Step 4 — Build archive content. Old frontmatter updated:

kind: preferences
status: superseded
created: 2026-05-17
updated: 2026-05-17
tags: [dev-flow, status-reports, locked-design-call]
group: personal-private
slug: paragraph-long-status-narratives
always_load: true
superseded_by: personal-private/preferences/paragraph-long-status-narratives.md
superseded_at: 2026-05-17T23:45:00Z
superseded_reason: 'Switched preference: now want short bullet lists per task closeout, not paragraphs'

Body unchanged in archive.

Step 5 — Build new entry content:

kind: preferences
status: active
created: 2026-05-17
updated: 2026-05-17
tags: [dev-flow, status-reports, locked-design-call]
group: personal-private
slug: paragraph-long-status-narratives
always_load: true
supersedes: personal-private/_archive/personal-private/preferences/paragraph-long-status-narratives.md.20260517.md

New body (from stdin).

Step 6 — Write archive → overwrite old path with new content.

Step 7 — Log "vec-index update queued for: ... (deferred to task 4)".

Step 8 — Confirm:

Evolved entry:
  old: personal-private/preferences/paragraph-long-status-narratives.md
       → archived to personal-private/_archive/personal-private/preferences/paragraph-long-status-narratives.md.20260517.md
  new: personal-private/preferences/paragraph-long-status-narratives.md (in-place)
  reason: Switched preference: now want short bullet lists per task closeout, not paragraphs
  status: old=superseded, new=active

Failure modes

• Old path missing — halt with "<old-path>: not found relative to vault root.".
• Old path is not a file — halt with type error.
• Old entry frontmatter unparseable — halt with "<old-path>: frontmatter invalid; manual fix needed before evolve.". Don't try to auto-repair.
• Old status not active — halt with "<old-path>: status is <status>, not active. Cannot evolve a non-active entry. Manual fix path: edit status field if you really want to evolve it.".
• Archive collision (same-day re-evolve) — append -N suffix until unique (.20260517.md → .20260517-2.md); continue without halting.
• --new-slug on _always-load/ entry — halt with "Cannot rename _always-load/ entries via --new-slug; evolve in place only.".
• Partial-failure recovery: if step 6 fails between archive-write and new-entry-write, the operator sees both files present (archive with superseded frontmatter + old at its original path still with active frontmatter). Recovery: read the archive, decide whether to commit or revert; manual fix path documented in troubleshooting.

Anti-patterns

/memory evolve must NOT:

• Modify the old entry's body — only frontmatter additions; body is the point-in-time snapshot.
• Skip the archive — never replace old with new directly; the archive is the audit trail.
• Coerce or auto-rename slugs — --new-slug is explicit operator intent.
• Evolve status: superseded entries silently — refuse with clear error; the supersession graph must be traversable from the active state outward, not the other way.
• Inherit created from old — the new entry's created date is the evolution date (the new entry didn't exist before).

Python-side script (scripts/evolve.py)

Canonical implementation at crickets/skills/memory/scripts/evolve.py. Same patterns as save.py:

• Function: evolve_entry(vault_path, old_path, new_body, reason, *, new_slug=None) -> tuple[Path, Path] — returns (new_entry_path, archive_path). Raises FileNotFoundError (old missing), ValueError (validation, status≠active, frontmatter unparseable), FileExistsError (archive collision after max retries).
• CLI entry point: python3 evolve.py <old-path> <reason> [--new-slug <slug>] [--body-file <p-or-->] [--vault-path <p>].
• Atomic-ish write sequence: writes archive first (additive); writes new entry second; both via write_bytes() for LF-only output. Best-effort atomicity at the syscall level for individual file ops; multi-file consistency relies on the operator detecting + recovering from partial failures (documented in failure modes above).
• Frontmatter parsing: uses yaml.safe_load (PyYAML required — already a toolkit dep via validate-manifests.py).
• LF-only output: same convention as save.py — target.write_bytes(content.encode("utf-8")) to bypass platform-specific line-ending translation. Critical for cross-platform Obsidian-synced markdown.

Both paths (skill-body Write + script-CLI Python) produce byte-identical files for the same inputs.

/memory reflect

User-invokable trigger for the reflection sidecar — mines a Claude Code session transcript for durable candidate entries + surfaces them for triage. Two parallel mining passes: the 3-category mine (Successful Workflows / User Preferences / Fixes & Workarounds) produces MemoryVault candidates; the idea-candidate mine (follow-ups / future projects / research candidates) produces ideas for the future idea-ledger (plan #7a part 4 will subscribe + persist these).

The same mining logic runs automatically via the Stop-event hook (after every session, lands in plan #7a part 3 task 3) + the idle-time hook (after N minutes idle, also recovers crashed sessions, lands in task 4). /memory reflect is the manual trigger for on-demand runs against arbitrary transcripts (re-running over an old session, testing the mining heuristic, dogfooding new patterns before they land in reflect.py).

Invocation shape

/memory reflect [--session <path>] [--memory-only | --idea-only] [--summary]

Arg	Required	Default	Meaning
--session <path>	no	current Claude Code session transcript at ~/.claude/projects/<repo>/<session-id>.jsonl	Absolute path to the JSONL transcript to mine.
--memory-only	no	false	Emit only the 3-category memory candidates (skip idea pass). Mutually exclusive with --idea-only.
--idea-only	no	false	Emit only the idea candidates (skip memory pass).
--summary	no	false	Prepend a 1-line summary (messages processed + candidate counts per pass) before the per-candidate output.

Step-by-step flow

Step 1 — Resolve transcript path. If --session is set, use it directly. Otherwise look up the current Claude Code session transcript at ~/.claude/projects/<repo-dir-as-slug>/<session-id>.jsonl where <repo-dir-as-slug> is the current working directory's path with / replaced by - and a leading -. Verify the resolved path exists; halt with "Transcript not found: <path>" if missing.

Step 2 — Call the canonical mining module. The deterministic implementation lives at skills/memory/scripts/reflect.py. Invoke via the dispatched Python script (operator path) or follow the agent-driven flow below (Claude Code in-session path). Both produce the same set of categorized candidates — the Python script's regex catalog is intentionally simple + tunable (Tech Debt #7); agent-driven runs can apply semantic judgment beyond what regex catches.

Step 3 — 3-category mine. Scan user + assistant messages for:

• Successful Workflows — tool-use sequences repeated 3+ times, multi-step procedures the user approved of. Look for: agent ran command sequence → user said "good" / "ship it" / no correction → same sequence reappears later.
• User Preferences — explicit user statements: "always X" / "never Y" / "I prefer Z" / "use X not Y" / "don't include Y". HIGH-confidence (explicit user signal). Also: user corrected the agent ("no, that's wrong" / "you should have X") → MEDIUM-confidence.
• Fixes & Workarounds — error/bug + nearby resolution: "fixed by X" / "resolved by Y" / "workaround: Z" / "the bug was caused by W". MEDIUM-confidence.

Step 4 — Idea-candidate mine. Scan for forward-looking statements: "we should also" / "later we could" / "follow-up:" / "could be its own project" / "as a follow-up". Each candidate gets a 2-sentence summary. Idea-ledger persistence is deferred to plan #7a part 4; this part just surfaces the candidates as in-memory objects.

Step 5 — Score each candidate (instrumentation per Tech Debt #7). For every candidate produced in steps 3-4, attach:

• category: preferences / workflow / fix / idea
• confidence: HIGH / MEDIUM / LOW
• slug suggestion (kebab-case)
• title (1-line)
• body (markdown ready for /memory save)
• rationale (1 sentence — which pattern matched, why it surfaced)
• excerpts (verbatim transcript snippets supporting the candidate)
• occurrences (match count)

The rationale + excerpts + occurrences fields are the load-bearing surface for Use-The-Memory-Skill troubleshooting + the future /memory inspect command — they let the operator audit "why did this candidate get categorized this way?".

Step 6 — Tri-modal routing (lands in plan #7a part 3 task 5 — for now, this step displays candidates grouped by confidence without auto-saving anything).

• HIGH candidates → auto-save via /memory save <category> <slug> (task 5 wires the actual save call).
• MEDIUM candidates → interactive review prompt with options: approve (save as-is) / edit (modify body or slug, then save) / reject (drop) / skip (defer to next session) / supersede-existing-X (call /memory evolve against the named existing entry). Task 5 builds this prompt UX.
• LOW candidates → save to MemoryVault/personal-private/_inbox/<slug>.md for batch triage later (task 5 wires the _inbox/ write).

memory.review_mode: silent toggle (lands with task 5) auto-approves MEDIUM candidates without prompting — useful for non-interactive sessions or operators who trust the heuristic.

Step 7 — Return confirmation. Display a summary:

Reflection complete. Mined <N> memory candidates + <M> idea candidates:
  preferences: <high-count> HIGH / <medium-count> MEDIUM / <low-count> LOW
  workflow:    <high-count> HIGH / <medium-count> MEDIUM / <low-count> LOW
  fix:         <high-count> HIGH / <medium-count> MEDIUM / <low-count> LOW
  ideas:       <total>

Routed:
  <H> saved automatically (HIGH)
  <M> sent to interactive review (MEDIUM)
  <L> queued in _inbox/ (LOW)

(Until task 5 ships, the "Routed" section reads <deferred to plan #7a part 3 task 5> and no actual save happens — the candidates print to stdout for review only.)

/memory reflect corpus — historical-pass mode (plan #7b task 2)

Batched paced walk over all historical transcripts at ~/.claude/projects/*/<session>.jsonl (or $MEMORY_TRANSCRIPT_ROOT). Wraps the same mining + tri-modal-routing pipeline as the single-transcript path, plus skip-resume state-file management for safe interruption.

Invocation shape

python3 ~/Antigravity/crickets/skills/memory/scripts/reflect.py corpus \
  [--projects-root <dir>] [--vault-path <path>] \
  [--batch-size N] [--max-batches M] \
  [--execute] [--reset] [--route-mode auto|silent|interactive]

Arg	Required	Default	Meaning
--projects-root <dir>	no	$MEMORY_TRANSCRIPT_ROOT or ~/.claude/projects	Recursive walk root.
--vault-path <path>	yes¹	$MEMORY_VAULT_PATH env	MemoryVault root — state file + inbox writes land here. ¹Required via flag or env.
--batch-size N	no	10	Sessions per batch (state saved each session; summary line printed every N sessions).
--max-batches M	no	unlimited	Stop after M batches — scout mode. State preserved for resume.
--execute	no	off (dry-run default)	Actually write entries + update state file. Without this flag, runs in dry-run mode (counts + estimates only).
--reset	no	off	Ignore existing state file (re-process everything). Combine with --execute to actually re-write.
--route-mode <m>	no	auto	MEDIUM-confidence routing. Default auto (→ _inbox/) is appropriate for historical-pass volume — interactive prompting per-candidate isn't practical at scale.

Why dry-run by default

The first historical pass over hundreds of sessions can emit thousands of LOW-confidence candidates → most land in _inbox/. Dry-run lets the operator see scope first (counts + estimates) before committing to writes. Pattern: corpus → review summary → corpus --execute → bulk-triage _inbox/. Mitigates the firehose risk flagged in plan #7b PLAN.md Risks.

State file shape

<vault>/_meta/transcript-reflection-state.json:

{
  "schema_version": 1,
  "sessions": {
    "<repo-slug>/<session-id>": {
      "processed_at": "2026-05-20T17:30:00+00:00",
      "message_count": 47,
      "memory_count": 3,
      "idea_count": 1,
      "status": "done",
      "transcript_path": "/absolute/path/to/session.jsonl"
    }
  }
}

Atomic writes via tempfile + rename — Ctrl-C mid-write can't leave a half-written state. State writes happen after every session (not every batch), so resume granularity is single-session.

Resume + interruption

• Re-running without --reset skips sessions with status: "done" in the state file.
• Ctrl-C at any time is safe — the in-progress session may have partial inbox entries from successful sub-writes, but the session itself is not marked done so it'll be re-processed on next run (potential for inbox-entry duplication; operator can dedupe during bulk-review).
• --reset clears the in-memory skip list but does not delete the state file — the next save_state call overwrites it with the new run's progress. To fully wipe, delete the file manually before re-running.

Anti-patterns

• Don't run corpus --execute without first running dry-run. First-pass scope is unpredictable; the dry-run estimate keeps the operator in control of how much _inbox/ churn they're committing to.
• Don't run corpus against ~/.claude/projects/ without setting --max-batches for the first execute run. Even with the dry-run preview, scout-mode (e.g. --max-batches 1 --batch-size 5) is the safer escalation — process 5 sessions, eyeball the inbox output, decide whether to continue.
• Don't combine corpus with interactive route-mode. Historical-pass volume means hundreds of prompts. The hook-style auto mode (default) routes MEDIUM → _inbox/ for later batch triage via /memory inbox --bulk-review (see its own section below).

Canonical Python implementation

The agent's in-context mining (steps 3-4 above) follows the same heuristic as skills/memory/scripts/reflect.py. Operators can invoke the Python script directly for scripting / dogfooding / hook execution:

python3 ~/Antigravity/crickets/skills/memory/scripts/reflect.py \
  ~/.claude/projects/<repo>/<session-id>.jsonl \
  --summary

Output: one JSON record per line ({"pass": "memory", "category": ..., "confidence": ..., "slug": ..., ...} or {"pass": "idea", ...}). The Stop-event hook (task 3) + idle-time hook (task 4) invoke this script — the skill body's in-session path is for interactive review surfaces where agent semantic judgment adds value beyond regex.

Failure modes (graceful)

• Transcript not found → halt step 1 with clear next-step ("set --session to a valid path, or run inside a Claude Code session for default-path resolution").
• Malformed JSONL lines in transcript (Claude Code crashed mid-write, partial JSON line) → skipped silently; mining continues on the remaining lines.
• Empty transcript → exit 0 with Reflection complete. Mined 0 memory candidates + 0 idea candidates. summary; no-op.
• No candidates found → emit summary line with all-zero counts; no per-candidate output; exit 0.
• reflect.py not installed at expected path (agent has Bash but the script is missing) → fall back to the in-context agent-driven flow above. The skill body is self-contained; the Python script is an optimization.

Anti-patterns

• Don't auto-save HIGH-confidence candidates without showing them first. Even HIGH-confidence patterns can be false positives (e.g., user said "always X" but meant only in this specific context). Display before saving.
• Don't save candidates to _inbox/ without the rationale + excerpts. The whole point of _inbox/ is batch triage later; without the supporting context the operator can't decide.
• Don't dedup aggressively across reflections. If the same pattern appears in two sessions, count it as 2 occurrences (not 1 with seen=true). The aggregate-occurrences count drives confidence routing.
• Don't write to the idea-ledger directly from this skill. Idea-candidate persistence is plan #7a part 4's scope. This skill emits candidates as in-memory objects + lets the future /memory ideas skill subscribe.

[!NOTE] Tri-modal routing implementation status: plan #7a part 3 task 5 wires the actual HIGH→auto-save / MEDIUM→interactive-review / LOW→_inbox/ branches. Tasks 1-2 (this commit) ship the mining + skill body; tasks 3-4 add Stop + idle triggers; task 5 closes the routing loop; task 6 adds crash-recovery markers; task 7 documents the full surface.

/memory promote

Graduates an _idea-incubator/<slug>/ entry to a real project at projects/<slug>/ + annotates the corresponding Ideas.md section + recalculates vec-index entries. Plan #7a part 4 ships this body + the canonical Python implementation at skills/memory/scripts/ideas_promote.py.

Invocation shape

/memory promote idea <slug> [--ideas-path <path>] [--mode <silent|interactive|auto>]

Arg	Required	Default	Meaning
<slug>	yes	—	Existing incubator slug under personal-private/_idea-incubator/<slug>/.
--ideas-path <path>	no	$IDEAS_SURFACE_PATH env or ~/Obsidian/Ideas.md	Override Ideas.md location.
--mode <m>	no	interactive (or $MEMORY_REVIEW_MODE)	Permeable-boundary mode for the Ideas.md annotation write. silent pre-approves; explicit user-typed promotion typically passes silent since the user already requested the operation.

Step-by-step flow

Step 1 — Resolve vault path via the chain --vault-path arg → MEMORY_VAULT_PATH env. Halt with clear next-step on failure.

Step 2 — Verify incubator entry exists at <vault>/personal-private/_idea-incubator/<slug>/. If missing, halt with "incubator entry not found: <path> (check slug; list with ls _idea-incubator/)". If a projects/<slug>/ already exists, halt to avoid clobber — operator picks a new slug or removes the existing.

Step 3 — Move the directory. shutil.move(_idea-incubator/<slug>, projects/<slug>). Cross-filesystem-safe (uses copy + delete fallback). Atomic at the OS level for same-FS moves.

Step 4 — Recalculate vec-index entries. For each .md file under the new projects/<slug>/ location: enqueue op: delete for the old path (personal-private/_idea-incubator/<slug>/...) + op: upsert for the new path with re-embedded text. Operator runs python3 vec_index.py drain --vault-path <vault> (or future idle-hook drain) to actually process. Graceful-skip if vec_index module missing.

Step 5 — Annotate Ideas.md section. Find the section whose wikilink references _idea-incubator/<slug>/_index.md; append → promoted YYYY-MM-DD to personal-private/projects/<slug>/ annotation right after the wikilink line. Permeable-boundary check fires here (Ideas.md is outside MemoryVault — the A3 helper confirm_write_outside_memoryvault() confirms via --mode resolution). If denied, the move + vec-index recalc already happened — the operator can manually annotate; the return value indicates "ideas_annotation: denied".

Step 6 — Return confirmation. Display:

Promoted <slug> to personal-private/projects/<slug>/
  incubator_dir → moved
  vec_index: <stats>
  ideas_annotation: written | denied | section_not_found

If section_not_found: the operator can manually annotate (the auto-search assumed the wikilink format from the original _idea-incubator/<slug>/_index.md reference; if the operator edited the section format, the regex won't find it).

/memory promote gc — garbage collection

Variant subcommand for the 6-month GC sweep:

python3 ~/Antigravity/crickets/skills/memory/scripts/ideas_promote.py gc \
  --vault-path <vault> [--gc-months 6]

Walks _idea-incubator/<slug>/ dirs, computes age from _index.md updated: frontmatter (falls back to file mtime if absent). Entries older than gc_months × 30 days get an interactive Keep / Archive / Delete prompt:

────────────────────────────────────────────────────────────────────────
Incubator entry idle: <slug> (<N> days since last update)
────────────────────────────────────────────────────────────────────────
Action: [k]eep (defer) / [a]rchive / [d]elete (default: k):

• Keep: _index.md mtime touched (entry exits the GC window; re-evaluated in 6 months).
• Archive: moves to _idea-incubator/_archive/<slug>/ (preserves history, excludes from active recall).
• Delete: rm -rf the dir (irreversible — vec-index entries pointing at deleted paths become orphans on next drain).
• Default (non-TTY or empty input): Keep — locked design call B1.i is never silent deletion; without operator confirmation the entry stays.

Failure modes (graceful)

• Slug not found → halt step 2 with the actual path that was checked.
• Target collision (projects/<slug>/ exists) → halt with operator next-step.
• Cross-filesystem move → falls back to copy+delete via shutil.move; slow but correct.
• vec-index unavailable → recalc step is no-op + returns {"skipped": -1} stat; operator runs reindex later.
• Ideas.md missing → ideas_annotation = "no_ideas_file"; promotion otherwise succeeds.
• A3 boundary denied for Ideas.md write → ideas_annotation = "denied"; promotion otherwise succeeds (operator can manually annotate).

Anti-patterns

• Don't pick the same slug as an existing projects//. Pre-check would help here but the operator typed the slug; we halt rather than guess.
• Don't run GC in batch / non-interactive contexts without --mode silent. Default GC behavior defaults every prompt to Keep when stdin isn't a TTY, which is correct (never silent deletion), but means non-TTY runs do nothing. For batch GC with explicit pre-approval, the operator runs the gc subcommand interactively.

/memory index-skills

Walks SKILL.md files across configured source paths (crickets/skills/, agentm/.claude/skills/, any extra repos the operator adds) and writes one kind: skill-pointer entry per skill to MemoryVault/personal-skills/<repo>/<skill-name>.md. The agent then picks these up via the normal recall hooks — surfacing "we have a /design author skill" without the operator re-mentioning it. Plan #7b task 1 ships this body + the canonical Python implementation at skills/memory/scripts/index_skills.py.

Invocation shape

/memory index-skills [--skill-path <dir>...] [--vault-path <path>] [--repo-name <slug>]

Arg	Required	Default	Meaning
--skill-path <dir>	yes¹	—	Skill source directory to walk. Repeatable. ¹Required unless MEMORY_SKILL_PATHS env var (colon-separated) supplies at least one path.
--vault-path <path>	no	$MEMORY_VAULT_PATH env	MemoryVault root. Halts if neither arg nor env resolves.
--repo-name <slug>	no	auto-detected	Explicit repo-slug for ALL discovered skills. Overrides the auto-detection walk (which finds the first ancestor containing .git/ or AGENTS.md). Useful when sources don't sit under a git repo. Kebab-normalized regardless of input.

Step-by-step flow

Step 1 — Resolve vault path via --vault-path arg → MEMORY_VAULT_PATH env. Halt with clear next-step on failure.

Step 2 — Resolve skill paths via --skill-path args + MEMORY_SKILL_PATHS env (colon-separated, deduplicated). Halt with "no skill paths configured" if neither produced any path.

Step 3 — Discover SKILL.md files. For each skill path: accept either <root>/SKILL.md (root is a skill dir) or <root>/<skill-name>/SKILL.md (canonical toolkit layout). Recursion depth is exactly one level — SKILL.md is a top-of-skill-dir convention, not a free-floating marker; deeper recursion would surface false positives.

Step 4 — For each SKILL.md, parse frontmatter (locked fields: name, description, version, supported_hosts). Halt the single skill (not the whole run) if name is missing or non-kebab.

Step 5 — Extract a body summary. First paragraph after the H1 (skipping leading blanks); falls back to empty if no body paragraph. Capped at 600 chars to keep pointer entries small.

Step 6 — Resolve repo-name. Either: (a) explicit --repo-name (normalized to kebab); (b) walk up from the SKILL.md path until an ancestor with .git/ or AGENTS.md matches → use that basename, normalized to kebab; (c) unknown-repo fallback.

Step 7 — Idempotency check. Target path is <vault>/personal-skills/<repo>/<skill-name>.md. If it already exists AND its skill_version + description body match the current SKILL.md → record as skipped. Otherwise → proceed to write.

Step 8 — Write the entry. Locked frontmatter shape:

---
kind: skill-pointer
status: active
created: <today UTC>
updated: <today UTC>
tags: [skill, personal-skills, auto-indexed]
group: personal-skills/<repo>
slug: <skill-name>
always_load: false
source_path: <absolute path to source SKILL.md>
source_repo: <repo>
skill_version: <version from source frontmatter>
last_indexed: <today UTC>
---

Body shape: title # <skill-name> (skill pointer) + an "auto-indexed; do not edit by hand" note + a metadata block (repo / version / hosts) + the description from frontmatter + the extracted summary.

Step 9 — Enqueue vec-index upsert with embed text <slug> skill (from <repo>)\n\n<description>\n\n<summary[:300]>. Graceful-skip on any enqueue failure — the file write is the contract; embedding is best-effort.

Failure modes (graceful)

• No --skill-path + no env → exit 1 with the actionable next-step.
• Vault path unresolved or not a directory → exit 1.
• A single SKILL.md fails to parse → that skill is recorded as action: error in the per-skill results dict, but the rest of the run continues. Overall exit is 2 if any skill errored, 0 otherwise.
• Auto-detected repo name has non-kebab characters → normalized via lowercasing + non-alnum → -. My_Cool-Repo → my-cool-repo.

Output shape

The CLI prints a JSON summary to stdout (suitable for piping into jq):

{
  "written": 3,
  "skipped": 5,
  "errors": 0,
  "results": [
    {"action": "written", "target": "...", "repo": "crickets", "skill": "memory", "reason": ""},
    {"action": "skipped", "target": "...", "repo": "crickets", "skill": "design", "reason": "unchanged (same skill_version + description)"}
  ]
}

Anti-patterns

• Don't hand-edit personal-skills/<repo>/<skill>.md entries — the next index run overwrites your changes if skill_version or description shifted. Hand-curate at the source SKILL.md instead.
• Don't add personal-skills entries via /memory save — the layout is reserved for the indexer's output. Operator-curated skill notes go in personal-private/ with a [[skill-pointer:<skill>]] cross-link to the auto-indexed pointer.
• Don't use /memory evolve against an auto-indexed entry — evolve is for human-curated entries. The indexer is the source of truth for skill-pointer entries; just re-run /memory index-skills after a SKILL.md change.

/memory discover-skills

Internet skill-discovery scan (plan #7b task 3). Fetches a curated set of "skill-shaped pattern" sources from the internet on a configurable cadence; caches each fetch as a dated snapshot; diffs against the previous snapshot; emits "new content since last scan" candidate signals for the adapt-don't-import workflow (task 4) to evaluate. Never writes to crickets/skills/ — adoption decisions are gated by the watchlist review pattern in task 5.

Auto-fires from the idle-time hook (memory-reflect-idle) with --cadence-check so the scan self-throttles to the configured cadence (default 7 days). Manual invocation is also supported.

Invocation shape

python3 ~/Antigravity/crickets/skills/memory/scripts/discover_skills.py \
  [--vault-path <path>] [--cadence-days N] [--cadence-check] \
  [--dry-run] [--max-sources N]

Arg	Required	Default	Meaning
--vault-path <path>	yes¹	$MEMORY_VAULT_PATH env	MemoryVault root — whitelist + cache + state land here. ¹Required via flag or env.
--cadence-days N	no	7 (or $MEMORY_SKILL_DISCOVERY_CADENCE_DAYS)	Minimum days between scans. Used with --cadence-check.
--cadence-check	no	off	Skip the fetch entirely if last_scan was within the cadence window. Used by the idle-hook to avoid hammering URLs on every idle fire.
--dry-run	no	off	List sources that would be scanned without actually fetching.
--max-sources N	no	unlimited	Limit to first N sources from the whitelist (scout / testing mode).

Source whitelist

Lives at <vault>/personal-private/skill-discovery-sources.md — operator-editable markdown. Format: #-prefixed comment lines, blank lines ignored, one URL per non-comment line. Order matters (sources scanned top-to-bottom; --max-sources truncates against this order).

First-ever scan auto-seeds the file with the operator's confirmed v1 set in exactly this order:

1. Anthropic Cookbook — https://raw.githubusercontent.com/anthropics/anthropic-cookbook/main/README.md
2. awesome-claude-code — https://raw.githubusercontent.com/hesreallyhim/awesome-claude-code/main/README.md
3. awesome-mcp-servers — https://raw.githubusercontent.com/punkpeye/awesome-mcp-servers/main/README.md
4. awesome-llm-apps — https://raw.githubusercontent.com/Shubhamsaboo/awesome-llm-apps/main/README.md

Operator edits the file in Obsidian to add, remove, or reorder sources. Auto-seed only happens once; subsequent runs read the file as-is.

Cache layout

Per-source cache lives under <vault>/_meta/skill-discovery-cache/:

<vault>/_meta/skill-discovery-cache/
├── state.json                                # last_scan + per-source last_fetch/status
├── <source-slug>/
│   ├── 2026-05-21.md                        # full snapshot of the URL response on this date
│   ├── diff-2026-05-21.md                   # added lines vs. previous snapshot (task 4 consumes this)
│   └── ...

<source-slug> is derived from the URL: <owner>-<repo> for GitHub raw URLs (kebab-normalized), or url-<8-char-hex> for non-GitHub sources.

Step-by-step flow

Step 1 — Resolve vault path via --vault-path arg → MEMORY_VAULT_PATH env. Halt with clear error on failure.

Step 2 — Resolve cadence via --cadence-days arg → $MEMORY_SKILL_DISCOVERY_CADENCE_DAYS env → default 7.

Step 3 — Load (or auto-seed) the source whitelist. If <vault>/personal-private/skill-discovery-sources.md is missing, write the default 4-URL seed (operator-confirmed v1 order) + log whitelist_seeded: true in the summary. Otherwise read URLs in file order.

Step 4 — Cadence check (when --cadence-check is set). Load state.json; if last_scan is within cadence_days × 86400 seconds, skip the fetch entirely + return cadence_skipped: true in summary.

Step 5 — Per-source fetch loop. For each URL (in whitelist file order, truncated to --max-sources if given):

a. urllib.request GET with 10s timeout + User-Agent: crickets-skill-discovery/0.1. b. On 200: write <source-slug>/<YYYY-MM-DD>.md snapshot; compute diff against most-recent prior-day snapshot; write diff-<YYYY-MM-DD>.md if diff non-empty; update state.json with {url, last_fetch, last_status: 200, last_snapshot, last_diff_chars}. c. On 4xx/5xx/timeout/DNS-failure: log to state.json ({last_attempt, last_status, last_error}) but don't overwrite snapshot/diff. Continue to next source. d. First-ever fetch of a source: prev snapshot doesn't exist, so diff = full content (everything is "new").

Step 6 — Save state + return summary. Atomic state.json write (tempfile + rename). Summary JSON to stdout: {vault, whitelist, whitelist_seeded, total_sources, cadence_days, dry_run, cadence_skipped, sources: [...], fetched, errors, skipped_dry_run}.

Idle-hook integration

memory-reflect-idle (the existing orphan-recovery hook from plan #7a part 3 task 4) extends to call discover_skills.py --cadence-check at the end of its run. Graceful-skip when MEMORY_VAULT_PATH is unset or discover_skills.py is absent. The cadence-check means the hook can fire frequently (every SessionStart) without hammering URLs.

Failure modes (graceful)

• Vault path unresolved → exit 1 with actionable error.
• Whitelist file missing → auto-seed with v1 defaults; first scan proceeds with the seeded URLs.
• Whitelist empty (all comments) → total_sources: 0; no fetches; no state update.
• Network failure (timeout / DNS / 5xx) → per-source recorded as action: error; other sources continue; summary exit code 2 (any errors).
• 4xx HTTP → per-source action: error with status_code: <4xx>; no snapshot overwrite.
• State.json corrupted → silently reset to empty state (next save overwrites with clean JSON).
• Same-day re-run → snapshot for today gets overwritten; diff compares to most-recent prior-day snapshot (excluding today). Same-day re-runs without a prior-day baseline treat everything as new.

Anti-patterns

• Don't run discover-skills without --cadence-check in idle-hook contexts. Hooks fire frequently; without the cadence guard the same URLs get fetched many times per day.
• Don't add to the whitelist URLs that aren't the markdown content you want to scan. The fetcher does no HTML parsing — it expects markdown-shaped sources (READMEs, awesome-lists, raw .md files). HTML pages get cached as raw HTML; the diff still works but downstream consumers (task 4) assume markdown content.
• Don't shipping-pipe discover-skills output to /memory save. The cache + diff are intermediate artifacts — task 4 (adapt-don't-import) is the authorized consumer; auto-saving the raw diffs would defeat the whole adapt-don't-import design.

[!NOTE] Adapt-don't-import workflow status: plan #7b task 4 (this sibling sub-command /memory adapt-skills) wires the actual evaluation of these cached diffs into _skill-watchlist/ entries; task 5 ships the /memory watchlist review command.

/memory adapt-skills

Adapt-don't-import workflow (plan #7b task 4). Two-pass architecture: Pass 1 (deterministic Python) walks the diff files from /memory discover-skills, parses candidate patterns, applies a 6-rule rubric, enriches with GitHub metadata + trustworthiness signals; Pass 2 (LLM sub-agent — adapt-evaluator) reads each enriched candidate + cross-references the operator's vault + renders the final HIGH/MEDIUM/LOW judgment + writes the watchlist entry. Never forks into crickets/skills/. Operator reviews via /memory watchlist (task 5).

Two-pass invocation shape

Pass 1 — Python pipeline (deterministic; safe to run repeatedly):

python3 ~/Antigravity/crickets/skills/memory/scripts/adapt_skills.py \
  [--vault-path <path>] [--source <slug>] [--skip-network] [--dry-run]

Arg	Required	Default	Meaning
--vault-path <path>	yes¹	$MEMORY_VAULT_PATH env	MemoryVault root. ¹Required via flag or env.
--source <slug>	no	all sources	Limit Pass 1 to a single source-slug (e.g. anthropics-anthropic-cookbook).
--skip-network	no	off	Skip GitHub API enrichment (offline / rate-limited contexts).
--dry-run	no	off	Evaluate without writing JSON files or updating state.

Pass 2 — sub-agent dispatch (one-shot judgment per candidate):

The Claude Code agent following this skill body dispatches the adapt-evaluator sub-agent with the caller-supplies-inline-rubric prompt documented in agents/adapt-evaluator.md. The sub-agent walks each enriched JSON, judges, and writes the watchlist entry. Operator-side, both passes typically chain: adapt-skills.py then sub-agent dispatch.

Pass 1: 6-rule rubric

Cumulative scoring against each candidate's text:

Rule	Signal	Score
R1	Names a tool/skill the operator doesn't already have (cross-checks personal-skills/ index)	+1
R2	Keyword-matches existing _always-load/ content (complements a convention)	+1
R3	Section context is agent-building / dev-env / meta-improvement	+1
R4	Names an MCP server / hook / skill primitive (high-relevance for this dev-env)	+1
R5	Flagged as experimental / WIP / hack / deprecated / abandoned	–1
R6	Cross-vendor proprietary (cursor / windsurf / codex / etc.)	–2

Thresholds: 3+ = HIGH (passed to Pass 2 for judgment), 1-2 = MEDIUM (also passed), ≤0 = LOW (dropped before Pass 2 unless --include-low future flag added).

Pass 1: enrichment payload

For each candidate that clears the rubric, Pass 1 enriches with:

1. GitHub metadata (unauthenticated API; graceful-skip on rate-limit or no-github-link):
   • github_owner, github_repo, github_stars, github_archived, github_last_commit_iso, github_license (SPDX), github_html_url
2. Trustworthiness signals:
   • from_trusted_org: matches against operator-editable whitelist at <vault>/personal-private/trusted-sources.md (auto-seeded with curated defaults: anthropics / google / microsoft / hashicorp / etc.)
   • cross_citation_count: how many of the 4 discovery sources reference this candidate (independent-validation signal)
   • high_stars (≥500) / low_stars (<50) / archived_warning / activity_recent (committed in last 365d) / permissive_license (MIT / Apache-2.0 / BSD / ISC / MPL)
3. Rubric verdict: rubric_score, rubric_rules_fired, rubric_confidence

Output: one JSON per candidate at <vault>/_meta/skill-discovery-cache/adapt-state/<source-slug>/<pattern-slug>.json. State file at adapt-state/evaluated.json tracks (source, pattern, diff-date) tuples for idempotent re-runs.

Pass 2: sub-agent judgment

Caller dispatches adapt-evaluator (see agents/adapt-evaluator.md). The sub-agent:

1. Reads each enriched candidate JSON.
2. Cross-references the operator's vault (personal-skills/ / personal-private/_always-load/ / projects/<repo>/conventions.md) for fit.
3. Classifies with semantic judgment (HIGH / MEDIUM / LOW) — overrides Pass 1's rubric verdict when context warrants.
4. Writes the watchlist entry to <vault>/personal-private/_skill-watchlist/<source-slug>/<pattern-slug>.md (HIGH + MEDIUM only; LOW dropped silently).

Watchlist entry shape locked in agents/adapt-evaluator.md under "Watchlist entry shape".

Trusted-sources whitelist

<vault>/personal-private/trusted-sources.md — operator-editable in Obsidian. Auto-seeds on first Pass 1 run with: anthropics, anthropic, google, googleworkspace, googlecloudplatform, microsoft, vercel, hashicorp, openai, cloudflare, github, supabase, redis, kubernetes, docker, pytorch, huggingface, modelcontextprotocol. Operator edits freely; one org-slug per non-comment line; case-insensitive match against GitHub URL owner.

Failure modes (graceful)

• No diff files in cache → diff_files_scanned: 0; exit 0; no-op.
• All candidates already evaluated → written_count: 0 + skipped_count: N; exit 0.
• GitHub API rate-limited or down → per-candidate github_* fields = null; rubric + trustworthiness signals still compute; sub-agent has reduced enrichment but still functions.
• Diff file unreadable → errors += 1; other candidates continue.
• Sub-agent dispatch fails (e.g. Claude Code unavailable) → enriched JSONs stay on disk; operator can re-dispatch later.

Anti-patterns

• Don't run Pass 2 (sub-agent) without first inspecting Pass 1's JSON output in unfamiliar territory. The JSON is the operator's verification surface for "is the rubric scoring sensibly?" — if R1/R5/R6 are firing on the wrong candidates, tune the rule constants in adapt_skills.py before paying the LLM cost.
• Don't promote a watchlist entry directly to crickets/skills/. Use /memory watchlist promote (task 5) → operator decides; the workflow's whole point is that adoption is operator-explicit, not agent-driven.
• Don't bypass the rubric by setting --include-low or hand-editing the evaluated.json state — the rubric is the deterministic gate that bounds the surface the sub-agent has to judge. Bypassing it makes Pass 2 expensive without value.

[!NOTE] Sub-agent budget: Pass 2 has no hard token cap (operator dispatch is one-shot, bounded by operator attention). For batch dispatch (idle-hook in a future task), a --limit N flag caps how many candidates each idle pass evaluates — default 5.

/memory watchlist

Review pending entries in <vault>/personal-private/_skill-watchlist/ — the output of /memory adapt-skills. Three actions per entry: promote (mark ready for operator's manual fork to crickets/skills/<x>/), dismiss (archive to _skill-watchlist/_archive/), defer (snooze with a deferred_until date). Plan #7b task 5 ships the body + the canonical Python implementation at skills/memory/scripts/watchlist_review.py.

Adapt-don't-import contract enforcement: this sub-command never writes to crickets/skills/<x>/. Promote is annotation-only — it marks the entry status: promoted + adds a promoted_at timestamp; the operator then manually authors the actual skill in a separate session. Adoption-by-agent is architecturally prevented.

Invocation shape

python3 ~/Antigravity/crickets/skills/memory/scripts/watchlist_review.py \
  [list | review | promote <source-slug> <pattern-slug> | \
   dismiss <source-slug> <pattern-slug> | \
   defer <source-slug> <pattern-slug> --until YYYY-MM-DD [--reason "<text>"]] \
  [--vault-path <path>]

Sub-command	Use case
list	JSON list of pending entries (source-slug + pattern-slug + status + classification). Useful for piping into other tools or just eyeballing the backlog.
review (default)	Interactive walk-through — prompts per entry with [p]romote / [d]ismiss / [f]efer / (default skip). Non-TTY stdin defaults all prompts to skip (never silent action — same contract as ideas_promote.py gc).
promote <source> <pattern>	Mark a specific entry promoted. Operator-typed slugs (autocomplete via list first).
dismiss <source> <pattern>	Archive a specific entry to _archive/.
defer <source> <pattern>	Snooze with --until YYYY-MM-DD + optional --reason.

Action semantics (locked)

• promote → frontmatter status: promoted + promoted_at: <iso ts> + updated: <today>; removes deferred_until / defer_reason / dismissed_at if present. Entry stays in place — the operator's manual fork happens outside this script.
• dismiss → frontmatter annotated with status: dismissed + dismissed_at: <iso ts>; then moved to <vault>/personal-private/_skill-watchlist/_archive/<source-slug>/<pattern-slug>.md (collision-safe -N suffix if needed). Preserves the audit trail; future passes can re-surface via direct file access.
• defer → frontmatter status: deferred + deferred_until: <iso date> + optional defer_reason; removes dismissed_at / promoted_at. Entry stays in place; future list operations can filter deferred_until to surface only re-eligible entries.
• skip (default for non-TTY + unrecognized input) → no change; entry stays in pending-review state for next pass.

Interactive flow

────────────────────────────────────────────────────────────────────────
Watchlist entry: anthropics-anthropic-cookbook/some-pattern
  status:        pending-review
  classification: HIGH
  source_url:    https://github.com/anthropics/some-pattern
  github_stars:  1247
  trusted_org:   true
  rubric_score:  4
────────────────────────────────────────────────────────────────────────
Action: [p]romote / [d]ismiss / [f] defer (default: skip)

On f (defer): a secondary prompt asks for defer until (YYYY-MM-DD; blank = default <today+30d>). Blank input or invalid date falls back to the 30-day default.

Failure modes (graceful)

• No entries in _skill-watchlist/ → [watchlist] no pending entries to stderr; exit 0.
• Non-TTY stdin → defaults every prompt to skip; emits interactive mode requested but stdin is not a TTY; defaulting all prompts to skip (never silent action); exit 0.
• Entry not found for promote/dismiss/defer specific-slug commands → exit 1 with the actual path that was checked.
• Invalid --until date for defer → exit 1 with --until must be ISO date YYYY-MM-DD.
• Archive collision on dismiss → file goes to <pattern-slug>-1.md, -2.md, etc.

Anti-patterns

• Don't run review in batch / non-interactive contexts. Default-to-skip is the safety net; if you actually want batch action, use the specific-slug subcommands (promote / dismiss / defer) which are deterministic + scriptable.
• Don't auto-promote based on rubric_score alone. The whole point of the watchlist is the operator's judgment on top of the rubric — auto-promotion bypasses the adapt-don't-import architectural guarantee.
• Don't rm -rf the _archive/ directory. It's the audit trail for "we considered this and dismissed it" — useful when the same pattern resurfaces from a different source later (cross-citation count goes up).

/memory inbox

Bulk-triage <vault>/personal/_inbox/ — the long-promised follow-up named as far back as the original MemoryVault design docs, never built until now. Reflection routes MEDIUM/LOW-confidence candidates here and stops; nothing moves them out of status: inbox on its own. /memory inbox --bulk-review scans every still-untriaged entry and proposes exactly one of three dispositions per entry, canonical implementation at skills/memory/scripts/inbox_triage.py:

• promote — an entry reinforced by repeated occurrence (mining_occurrences at or above a threshold) or a real content match across 3+ inbox entries graduates to the same canonical destination reflect.py's own HIGH-confidence path writes to (<vault>/personal/<kind>/<slug>.md).
• merge — a near-duplicate PAIR (similarity above threshold, not part of a larger reinforcing cluster) is proposed for merge — reuses dream.py's own difflib-based dedup stage against the inbox pool, not a second similarity implementation.
• expire — stale and unreinforced past a TTL (default 90 days since the entry's own created timestamp) is proposed for in-place archival (status: expired — never a physical delete or move).

Every proposal stages through the exact _dream-staging/<run_id>/ contract dreaming already built (dream_confirm.py's list_pending / confirm / auto_apply_batch run unmodified against an inbox-triage run).

Auto-apply is now the default (operator ruling, 2026-07-11, second pass). The first-ever run shipped confirm-gated: every disposition proposed against the pre-existing backlog — 1,565 notes across 635 proposals — stayed pending for an explicit human confirm, regardless of kind. The operator personally reviewed and confirmed that entire first-run backlog with zero errors, then directed that confirm-gating retire going forward. Every disposition — promote, merge, and expire alike — now auto-applies by default, regardless of whether the source entry predates or postdates the first-run cutover marker (_meta/inbox-triage-cutover.json, stamped once, never overwritten). The cutover marker still exists and still labels which era an expire proposal's source entry belongs to (inbox_expire vs inbox_expire_backlog), but that label is now informational only — it no longer gates whether a proposal applies. Pass --no-auto-apply to fall back to propose-only (nothing applies until an explicit --confirm).

Invocation shape

python3 ~/Antigravity/crickets/skills/memory/scripts/inbox_triage.py \
  --vault-path <path> \
  [--bulk-review | --list | --confirm <index> --run-id <id> | --reject <index> --run-id <id>] \
  [--run-id <id>] [--non-interactive] [--no-auto-apply] \
  [--batch-cap <n>] [--expire-ttl-days <n>] [--promote-occurrence-threshold <n>]

Flag	Use case
--bulk-review (default)	Scan (+ auto-apply every eligible proposal — promote/merge/expire alike), then interactively review whatever's still pending (only ever the batch-cap remainder) — [c]onfirm / [r]eject / [s]kip per proposal. Non-TTY stdin defaults every prompt to skip (never silent action — same contract watchlist_review.py already established).
--list	JSON dump of pending proposals for the most recent run (or --run-id) — index/stage/kind/paths/summary/status.