From 5b57b674f8e604c58672d405fb798a5f234a2f3c Mon Sep 17 00:00:00 2001 From: ScriptedAlchemy Date: Tue, 23 Jun 2026 00:19:15 +0000 Subject: [PATCH] Document autonomous memory curation workflow --- .../skills/architecture-overview/SKILL.md | 1 + .../skills/assessing-test-coverage/SKILL.md | 1 + .../skills/code-health-report/SKILL.md | 1 + .../skills/curating-project-memory/SKILL.md | 62 +++- .../exploring-types-and-traits/SKILL.md | 1 + .../skills/finding-impacted-areas/SKILL.md | 1 + .../skills/recalling-project-memory/SKILL.md | 3 + .../skills/recalling-session-context/SKILL.md | 1 + codex-plugin/skills/reviewing-a-diff/SKILL.md | 1 + .../skills/searching-for-code/SKILL.md | 3 + .../skills/tracing-functions/SKILL.md | 1 + .../skills/architecture-overview/SKILL.md | 1 + .../skills/assessing-test-coverage/SKILL.md | 1 + .../skills/code-health-report/SKILL.md | 1 + .../exploring-types-and-traits/SKILL.md | 1 + .../skills/finding-impacted-areas/SKILL.md | 1 + .../skills/recalling-project-memory/SKILL.md | 3 + .../skills/recalling-session-context/SKILL.md | 1 + .../skills/reviewing-a-diff/SKILL.md | 1 + .../skills/searching-for-code/SKILL.md | 3 + .../skills/tracing-functions/SKILL.md | 1 + docs/MEMORY-CURATION-AUTONOMY.md | 293 ++++++++++++++++++ docs/MULTIPROJECT.md | 3 + 23 files changed, 375 insertions(+), 11 deletions(-) create mode 100644 docs/MEMORY-CURATION-AUTONOMY.md diff --git a/codex-plugin/skills/architecture-overview/SKILL.md b/codex-plugin/skills/architecture-overview/SKILL.md index e4b5798caf..f4d014bfdd 100644 --- a/codex-plugin/skills/architecture-overview/SKILL.md +++ b/codex-plugin/skills/architecture-overview/SKILL.md @@ -17,6 +17,7 @@ This skill **maps structure**. Its companion `tracedecay:code-health-report` **s ## Guardrails - All tools here are read-only and parallel-safe. This skill maps and explains; it does not edit and it does not rank tech debt. +- For broad repo maps, dispatch scoped read-only subagents by top-level directory, layer, or dependency question. Each subagent reports only cited TraceDecay findings; the parent agent owns the final architecture synthesis. ## Output diff --git a/codex-plugin/skills/assessing-test-coverage/SKILL.md b/codex-plugin/skills/assessing-test-coverage/SKILL.md index 1cb8ba0b28..3502f3294c 100644 --- a/codex-plugin/skills/assessing-test-coverage/SKILL.md +++ b/codex-plugin/skills/assessing-test-coverage/SKILL.md @@ -17,6 +17,7 @@ Read-only coverage intelligence from the graph (structural test↔source edges, ## Guardrails - All read-only and parallel-safe; nothing here executes tests. Coverage is structural (call/use edges), so integration tests that reach code indirectly (through a binary, fixture, or IO boundary) can be missed — an empty `test_map` is strong but not absolute evidence of "untested". +- For many targets or changed paths, use scoped read-only subagents per file group, package, or risk bucket. Require each subagent to return the exact target, TraceDecay coverage tools used, affected tests, and uncertainty; the parent agent chooses the final recommendation. ## Output diff --git a/codex-plugin/skills/code-health-report/SKILL.md b/codex-plugin/skills/code-health-report/SKILL.md index 32315eac6f..69e6f8b421 100644 --- a/codex-plugin/skills/code-health-report/SKILL.md +++ b/codex-plugin/skills/code-health-report/SKILL.md @@ -23,6 +23,7 @@ Quality-scorecard companion to `tracedecay:architecture-overview` (which maps st ## Guardrails - Discovery/analysis tools are read-only and parallel-safe. `tracedecay_session_start` / `tracedecay_session_end` write/remove `.tracedecay/session_baseline.json`; use them only when a before/after delta is relevant and respect Cursor approval/run-mode. +- For large audits, use scoped read-only subagents by path, weak health dimension, or requested scan. Keep any `tracedecay_session_start` / `tracedecay_session_end` calls in the parent agent; subagents only gather cited analysis. - `tracedecay_redundancy` is computed lazily and cached; the first call on a fresh index can be slow on large repos — keep `path`/`max_pairs` tight. - This skill reports and prioritizes; it does not edit. To fix findings, hand off to `tracedecay:atomic-code-edits` / `tracedecay:cleaning-up-dead-code`; to verify, `tracedecay:running-impacted-tests`. For a focused ship-readiness sweep (panic sites, risk markers, dead code, untested high-risk symbols) use `tracedecay:auditing-code-safety` instead of the full scorecard. diff --git a/codex-plugin/skills/curating-project-memory/SKILL.md b/codex-plugin/skills/curating-project-memory/SKILL.md index 33091f51bd..8a93b0563a 100644 --- a/codex-plugin/skills/curating-project-memory/SKILL.md +++ b/codex-plugin/skills/curating-project-memory/SKILL.md @@ -5,27 +5,67 @@ description: 'Use when reviewing, updating, merging, deleting, pruning, or repai # Curating project memory -This skill owns memory lifecycle changes. For read-only recall, start with `tracedecay:recalling-project-memory`. To add a researched subject from scratch, use the research-then-`add` flow in the Handoff section. +Destructive curation is a parent-agent responsibility. Use subagents only for scoped inspection or recommendation work, with explicit project selectors and non-overlapping ownership; do not delegate delete/apply/merge/retention actions to subagents. TraceDecay should progressively expose registered-project selectors in its own MCP and CLI surfaces, so this skill documents the workflow rather than being the sole routing mechanism. + +This skill owns memory lifecycle changes. For read-only recall, start with `tracedecay:recalling-project-memory`. For autonomous curation, begin read-only, gather evidence, propose a mutation plan, then write only narrow durable changes. The installed Codex plugin ships this skill as the required operator runbook, so follow the workflow below without depending on external `docs/` files. ## Workflow -1. **Start read-only:** `tracedecay_fact_store` with `action: "search"`, `"list"`, `"probe"`, `"related"`, `"reason"`, or `"contradict"`; use `tracedecay_memory_status` when the user asks for memory counts/health; use `tracedecay_dashboard` (`action: "start"`) when they want visual curation. -2. **Classify the change:** update stale content/trust/tags, remove confirmed duplicates or wrong facts, or record `tracedecay_fact_feedback` only when the user rates a fact that was actually used. -3. **Confirm destructive actions:** before `action: "remove"`, show the fact id, content/source, and reason, unless the user already named the exact fact to delete. -4. **Apply narrowly:** `tracedecay_fact_store` `action: "update"` / `"remove"` / `"add"` only for the approved fact set. Re-run a read-only search/list to verify the final state. +1. **Resolve scope:** confirm the active project root/store before touching memory. Project-bound profiles use the user-level TraceDecay store scoped to the current project by default. +2. **Start read-mostly:** use TraceDecay MCP context/search first for code/session orientation, then `tracedecay_fact_store` with `action: "get"`, `"contradict"`, `"search"`, `"list"`, `"probe"`, `"related"`, or `"reason"`; note that search/list/probe/related/reason may update retrieval/access metadata. Use `tracedecay_memory_status` only when the user asks for memory counts/health because it may repair vectors/banks. Use `tracedecay_dashboard` (`action: "start"`) only when they want visual curation. +3. **Run native dry-run:** prefer `tracedecay memory curate` or `POST /api/plugins/holographic/curate` with `{"dry_run": true}`. Dry-run is the default and returns `actions`, `hygiene_candidates`, `counts`, `coverage`, `provider`, and `mode`. +4. **Inventory candidates:** group facts into add, update, merge/dedupe, stale, contradiction, secret-like, transient, supersession, and possible hard-delete buckets. Keep fact ids, source/provenance, trust, tags, entities, evidence links, and counterevidence with each candidate. +5. **Research gaps:** use TraceDecay graph/search plus LCM/session/message tools to mine past sessions, raw messages, summary DAGs, branch/PR context, docs, and tests. For multi-step evidence gathering, scoped subagents may research bounded read-only questions only; the parent agent is the sole memory writer and must review raw findings before trusting them. +6. **Propose changes:** summarize durable additions, stale-fact updates, trust/tag/source changes, dedupe merges, and delete candidates. Prefer update/merge over removal when useful provenance should survive. +7. **Apply narrowly:** add/update only facts supported by evidence. Use `/curate/apply` or `tracedecay memory curate --llm-ops --apply` only for reviewed operations. Require explicit approval immediately before every `action: "remove"`, dashboard hard delete, or merge loser removal, showing fact id, content/source summary, reason, and permanent-delete warning. +8. **Verify read-only:** re-run search/list/probe/related/contradict/get as appropriate, inspect apply results/oplog when used, and report final facts changed, skipped, or still needing human judgment. ## Guardrails -- Search/list/probe/related/reason/contradict are read-only. Add/update/remove, feedback, memory status repair, and dashboard start/stop mutate state or launch a local process; respect Cursor approval/run-mode. -- Deletion is permanent: there is no archive, soft-delete, restore, or undo path. Prefer update/merge when useful provenance should survive; delete only confirmed stale, duplicate, wrong, secret-like, or user-requested facts. +- `get` and `contradict` are non-destructive recall. Search/list/probe/related/reason are read-mostly but can update access/retrieval counters. Add/update/remove, feedback, memory status repair, and dashboard start/stop mutate state or launch a local process; respect host approval/run-mode. +- Deletion is permanent: there is no archive, soft-delete, restore, or undo path. Prefer update/merge when useful provenance should survive; delete only approved stale, duplicate, wrong, secret-like, or user-requested facts. - Never store secrets, credentials, API keys, or PII. Do not lower trust merely because a fact is old; cite the newer evidence or contradiction. -- Dashboard curation can apply hard deletes. Use preview/dry-run first when available and surface high-risk delete/merge operations before applying them. +- Dashboard curation can apply hard deletes. Use preview/dry-run first when available and surface high-risk delete/merge operations before applying them. `POST /api/plugins/holographic/curate` with `dry_run=false` applies deterministic duplicate deletion; `/curate/apply` applies explicit delete/merge ops. +- Do not let subagents call add/update/remove/feedback tools, apply curation ops, start dashboard mutation flows, or run memory health repair. Ask them for cited evidence, candidate facts, suspected duplicates, and stale/conflicting claims, then perform parent-agent validation before writing. +- Default autonomous grooming output is report-only. If a tool or dashboard action mutates unexpectedly, disclose it and verify state before continuing. +- Hygiene candidates (`secret_like`, `transient`, `supersession`) are review evidence, not deterministic apply operations. +- External LLM plans must use strict JSON `{"ops": [...]}` and pass through the TraceDecay evidence guard; rejected low-confidence or out-of-scope ops must stay skipped. + +## Dry-run report + +Before any mutation, produce a compact report with these sections: + +- `scope`: project root/store, tool/API used, dry-run timestamp, and whether memory health repair or dashboard start/stop was invoked. +- `native_plan`: `mode`, `provider`, `coverage`, `counts`, action count, and hygiene-candidate counts from `tracedecay memory curate` or `/curate`. +- `adds`: candidate durable facts with source spans, category, entities, trust, and duplicate-search result. +- `updates`: fact ids, old/new summary, evidence, confidence, and why update beats add. +- `merges`: winner/loser ids, similarity evidence, retained provenance, optional `merged_content`, and why separate facts are redundant. +- `deletes`: fact ids, content/source summary, permanent-delete reason, risk, surviving fact if any, and explicit approval status. +- `skipped`: rejected transient, secret-like, unsupported, stale-but-uncertain, or duplicate candidates. +- `verification_plan`: exact read-only checks to run after apply. + +Map native curation fields into those sections as follows: + +- `actions`: deterministic similarity-dedup delete proposals; list them under `deletes` unless operator review converts them into a safer `merge`. +- `hygiene_candidates`: review-only evidence; list confirmed candidates under `deletes`, `updates`, or `merges`, and unconfirmed candidates under `skipped`. +- `llm_review`: bounded external-review request; use `clusters`, `hygiene_candidates`, `allowed_fact_ids`, and `min_confidence` as evidence constraints. +- `llm_apply`: validated external ops and rejected ops; list valid dry-run ops under `merges`/`deletes`, and rejected ops under `skipped`. + +## Memorize a subject + +Use only when the user explicitly asks to memorize or remember a subject, code area, branch, PR, or decision set. + +1. **Research read-only:** use TraceDecay graph/search, LCM/session/message tools, docs, existing fact searches, and relevant branch/PR context. Scoped research agents may gather evidence but the parent agent is the only memory writer. +2. **Filter:** keep durable, scoped facts with citations. Reject secrets, credentials, PII, large code blobs, transient branch state, unsupported claims, and uncited speculation. +3. **Calibrate trust:** use `0.85+` for independently verified decisions/observations, about `0.7` for ordinary well-sourced facts, and about `0.5` for plausible but uncertain facts. Do not ask for approval solely because trust is low. +4. **Dedupe before writing:** search `tracedecay_fact_store` with the subject plus candidate, matching category, `limit: 10`, and `min_trust: 0.5`; skip near-duplicates and ask before replacing contradictory facts. +5. **Store accepted facts:** propose the candidate set, then call `tracedecay_fact_store` `action: "add"` with content, category, source, tags, entities, trust, and metadata containing subject/confidence/citations. +6. **Read add diffs:** act on `near_duplicate`, `possible_conflict`, and `rejected_secret_like`; never rephrase a rejected secret to bypass filtering. ## Handoff -- Need to remember a new subject with research fan-out → research read-only first, dedupe via `tracedecay_fact_store` `action: "search"`, then store durable, cited facts with `action: "add"`; reject secrets, credentials, and PII. -- Need raw session messages or summary-DAG replay → `tracedecay:recalling-session-context`. -- Need only index/server status, not memory mutation → `tracedecay:project-status`. +- Need raw session messages or summary-DAG replay -> `tracedecay:recalling-session-context`. +- Need only index/server status, not memory mutation -> `tracedecay:project-status`. ## Output diff --git a/codex-plugin/skills/exploring-types-and-traits/SKILL.md b/codex-plugin/skills/exploring-types-and-traits/SKILL.md index c503fb3041..67cb47ff41 100644 --- a/codex-plugin/skills/exploring-types-and-traits/SKILL.md +++ b/codex-plugin/skills/exploring-types-and-traits/SKILL.md @@ -20,6 +20,7 @@ Call-graph questions ("who calls X") belong in `tracedecay:tracing-functions`; t ## Guardrails - All read-only and parallel-safe. `tracedecay_constructors` is best-effort for Rust (ignores `match` arms and `if let` patterns); `tracedecay_field_sites` pattern-matches `.` references, so same-named fields on other types can appear — prefer the `Struct::field` form to narrow. Unknown proc-macro derives surface with `well_known: false` (name only, no synthesized-method info). +- For several independent type/trait questions, use scoped read-only subagents per type, trait, field, or implementor cluster. Require exact symbol ids/qualified names and tool evidence; the parent agent synthesizes the type-level answer. - This skill maps types; it does not edit. Hand renames/edits to `tracedecay:refactoring-safely` / `tracedecay:atomic-code-edits`. ## Output diff --git a/codex-plugin/skills/finding-impacted-areas/SKILL.md b/codex-plugin/skills/finding-impacted-areas/SKILL.md index 6bf216a6b4..db7d7b582b 100644 --- a/codex-plugin/skills/finding-impacted-areas/SKILL.md +++ b/codex-plugin/skills/finding-impacted-areas/SKILL.md @@ -21,6 +21,7 @@ description: 'Use when estimating blast radius: what depends on a symbol or file - Read-only analysis. This skill identifies impact and the test set; it does **not** run tests. - Start with a shallow `max_depth` and widen only when the picture is incomplete. +- For broad changes, use scoped read-only subagents per changed file group, target symbol, or subsystem. Subagents should return cited dependents, affected tests, and depth/tool parameters; the parent agent owns the final blast-radius and test-set synthesis. ## Handoff diff --git a/codex-plugin/skills/recalling-project-memory/SKILL.md b/codex-plugin/skills/recalling-project-memory/SKILL.md index e10e684c2a..b475962027 100644 --- a/codex-plugin/skills/recalling-project-memory/SKILL.md +++ b/codex-plugin/skills/recalling-project-memory/SKILL.md @@ -5,6 +5,9 @@ description: 'Use when recalling prior decisions, durable facts, user/project pr # Recalling project memory +Prefer TraceDecay-native registered-project selectors whenever a recall spans or targets a project other than the active checkout. Codex skill guidance may describe how to choose selectors, but selector support should live progressively in TraceDecay MCP and CLI tools themselves. + + Recall memory **before** reaching for external or web search — prior sessions often already answered the question, and a memory hit is cheaper and project-specific. ## Workflow diff --git a/codex-plugin/skills/recalling-session-context/SKILL.md b/codex-plugin/skills/recalling-session-context/SKILL.md index 7fd6e6387d..43236ddb89 100644 --- a/codex-plugin/skills/recalling-session-context/SKILL.md +++ b/codex-plugin/skills/recalling-session-context/SKILL.md @@ -18,6 +18,7 @@ Climb this ladder cheapest-first; stop as soon as the question is answered. For ## Guardrails - Steps 1–5 are read-only. `tracedecay_lcm_compress`, `tracedecay_lcm_preflight`, and `tracedecay_lcm_session_boundary` are **lifecycle-integration tools for host agents** — never invoke them casually during recall. +- For multi-step recall, dispatch scoped read-only subagents by session id, time window, provider, role, or query variant. Subagents must not call lifecycle or repair tools; the parent agent validates cited messages/summaries and produces the final timeline. - If the LCM store itself looks wrong (missing sessions, broken FTS, stale counts) → `tracedecay_lcm_doctor` (`mode: "diagnose"` first; `repair`/`clean` mutate and need explicit user intent). - All LCM tools default to `storage_scope: "project_local"`; only pass `hermes_profile` (with an absolute `hermes_home`) when the user asks about a Hermes profile store. diff --git a/codex-plugin/skills/reviewing-a-diff/SKILL.md b/codex-plugin/skills/reviewing-a-diff/SKILL.md index 2ca57e5128..fc4bf354e9 100644 --- a/codex-plugin/skills/reviewing-a-diff/SKILL.md +++ b/codex-plugin/skills/reviewing-a-diff/SKILL.md @@ -18,6 +18,7 @@ description: 'Use when reviewing a PR, branch diff, or working-tree diff for imp ## Guardrails - Read-only review. Do not edit or run tests from this skill; to verify behavior, hand off to the `tracedecay:running-impacted-tests` skill. +- For large diffs, use scoped read-only subagents by file group, subsystem, or risk category. Require cited TraceDecay findings and changed paths; the parent agent owns severity, deduplication, and the final review call. - If diff context is truncated and includes a `handle`, narrow by file/symbol first when possible; call `tracedecay_retrieve` with that `handle` only when the omitted risk detail is needed. ## Output diff --git a/codex-plugin/skills/searching-for-code/SKILL.md b/codex-plugin/skills/searching-for-code/SKILL.md index b0b6086fce..2ddc2aa0fd 100644 --- a/codex-plugin/skills/searching-for-code/SKILL.md +++ b/codex-plugin/skills/searching-for-code/SKILL.md @@ -7,6 +7,8 @@ description: 'Find code by concept, symbol, signature, or qualified name in this Use the TraceDecay code graph before Grep/Glob/file reads. Pick the cheapest tool that answers the question. +For multi-step context gathering, use scoped read-only subagents when separate questions can run independently. Give each subagent one bounded target (symbol, path, feature, session, or branch), the TraceDecay tools it may use, and a strict "no writes / no edits / no memory mutations" instruction; the parent agent synthesizes findings and performs any follow-up actions. + ## Workflow 1. **Conceptual / "how does X work" / names unknown → `tracedecay_context`.** @@ -26,6 +28,7 @@ Use the TraceDecay code graph before Grep/Glob/file reads. Pick the cheapest too - All tools above are read-only and parallel-safe. Do not call mutating/editing tools from this skill. - Only fall back to Grep/Glob/Read for non-indexed content (string literals, comments, config the graph does not cover) or after TraceDecay pinpoints exact files. - Prefer one well-formed `tracedecay_context` call over many narrow searches. +- When using subagents, ask for cited file/symbol/session ids, tool names used, gaps/uncertainties, and any `tracedecay_metrics:` lines; do not accept uncited conclusions as evidence. - If a response is truncated and includes a `handle`, narrow the query/result set first when possible; call `tracedecay_retrieve` with that `handle` only when the omitted details are needed. - About to write a new helper because the search came up empty? Run the `tracedecay:finding-duplicate-logic` pre-write probe first. diff --git a/codex-plugin/skills/tracing-functions/SKILL.md b/codex-plugin/skills/tracing-functions/SKILL.md index 270454ad7a..b540348b93 100644 --- a/codex-plugin/skills/tracing-functions/SKILL.md +++ b/codex-plugin/skills/tracing-functions/SKILL.md @@ -18,6 +18,7 @@ description: 'Use when tracing call relationships: who calls a function, what it ## Guardrails - Read-only and parallel-safe. Keep `max_depth` small (1–2) first; widen only when the chain is not yet clear. `tracedecay_rename_preview` only previews references — it does not rename. +- For several independent symbols or call paths, use scoped read-only subagents per symbol, direction, or path hypothesis. Require node ids, depth/tool parameters, and dispatch notes; the parent agent owns the final trace. - If a trace response is truncated and includes a `handle`, narrow depth or target set first when possible; call `tracedecay_retrieve` with that `handle` when the omitted chain details are needed. ## Output diff --git a/cursor-plugin/skills/architecture-overview/SKILL.md b/cursor-plugin/skills/architecture-overview/SKILL.md index e4b5798caf..f4d014bfdd 100644 --- a/cursor-plugin/skills/architecture-overview/SKILL.md +++ b/cursor-plugin/skills/architecture-overview/SKILL.md @@ -17,6 +17,7 @@ This skill **maps structure**. Its companion `tracedecay:code-health-report` **s ## Guardrails - All tools here are read-only and parallel-safe. This skill maps and explains; it does not edit and it does not rank tech debt. +- For broad repo maps, dispatch scoped read-only subagents by top-level directory, layer, or dependency question. Each subagent reports only cited TraceDecay findings; the parent agent owns the final architecture synthesis. ## Output diff --git a/cursor-plugin/skills/assessing-test-coverage/SKILL.md b/cursor-plugin/skills/assessing-test-coverage/SKILL.md index 1cb8ba0b28..3502f3294c 100644 --- a/cursor-plugin/skills/assessing-test-coverage/SKILL.md +++ b/cursor-plugin/skills/assessing-test-coverage/SKILL.md @@ -17,6 +17,7 @@ Read-only coverage intelligence from the graph (structural test↔source edges, ## Guardrails - All read-only and parallel-safe; nothing here executes tests. Coverage is structural (call/use edges), so integration tests that reach code indirectly (through a binary, fixture, or IO boundary) can be missed — an empty `test_map` is strong but not absolute evidence of "untested". +- For many targets or changed paths, use scoped read-only subagents per file group, package, or risk bucket. Require each subagent to return the exact target, TraceDecay coverage tools used, affected tests, and uncertainty; the parent agent chooses the final recommendation. ## Output diff --git a/cursor-plugin/skills/code-health-report/SKILL.md b/cursor-plugin/skills/code-health-report/SKILL.md index 32315eac6f..69e6f8b421 100644 --- a/cursor-plugin/skills/code-health-report/SKILL.md +++ b/cursor-plugin/skills/code-health-report/SKILL.md @@ -23,6 +23,7 @@ Quality-scorecard companion to `tracedecay:architecture-overview` (which maps st ## Guardrails - Discovery/analysis tools are read-only and parallel-safe. `tracedecay_session_start` / `tracedecay_session_end` write/remove `.tracedecay/session_baseline.json`; use them only when a before/after delta is relevant and respect Cursor approval/run-mode. +- For large audits, use scoped read-only subagents by path, weak health dimension, or requested scan. Keep any `tracedecay_session_start` / `tracedecay_session_end` calls in the parent agent; subagents only gather cited analysis. - `tracedecay_redundancy` is computed lazily and cached; the first call on a fresh index can be slow on large repos — keep `path`/`max_pairs` tight. - This skill reports and prioritizes; it does not edit. To fix findings, hand off to `tracedecay:atomic-code-edits` / `tracedecay:cleaning-up-dead-code`; to verify, `tracedecay:running-impacted-tests`. For a focused ship-readiness sweep (panic sites, risk markers, dead code, untested high-risk symbols) use `tracedecay:auditing-code-safety` instead of the full scorecard. diff --git a/cursor-plugin/skills/exploring-types-and-traits/SKILL.md b/cursor-plugin/skills/exploring-types-and-traits/SKILL.md index c503fb3041..67cb47ff41 100644 --- a/cursor-plugin/skills/exploring-types-and-traits/SKILL.md +++ b/cursor-plugin/skills/exploring-types-and-traits/SKILL.md @@ -20,6 +20,7 @@ Call-graph questions ("who calls X") belong in `tracedecay:tracing-functions`; t ## Guardrails - All read-only and parallel-safe. `tracedecay_constructors` is best-effort for Rust (ignores `match` arms and `if let` patterns); `tracedecay_field_sites` pattern-matches `.` references, so same-named fields on other types can appear — prefer the `Struct::field` form to narrow. Unknown proc-macro derives surface with `well_known: false` (name only, no synthesized-method info). +- For several independent type/trait questions, use scoped read-only subagents per type, trait, field, or implementor cluster. Require exact symbol ids/qualified names and tool evidence; the parent agent synthesizes the type-level answer. - This skill maps types; it does not edit. Hand renames/edits to `tracedecay:refactoring-safely` / `tracedecay:atomic-code-edits`. ## Output diff --git a/cursor-plugin/skills/finding-impacted-areas/SKILL.md b/cursor-plugin/skills/finding-impacted-areas/SKILL.md index 6bf216a6b4..db7d7b582b 100644 --- a/cursor-plugin/skills/finding-impacted-areas/SKILL.md +++ b/cursor-plugin/skills/finding-impacted-areas/SKILL.md @@ -21,6 +21,7 @@ description: 'Use when estimating blast radius: what depends on a symbol or file - Read-only analysis. This skill identifies impact and the test set; it does **not** run tests. - Start with a shallow `max_depth` and widen only when the picture is incomplete. +- For broad changes, use scoped read-only subagents per changed file group, target symbol, or subsystem. Subagents should return cited dependents, affected tests, and depth/tool parameters; the parent agent owns the final blast-radius and test-set synthesis. ## Handoff diff --git a/cursor-plugin/skills/recalling-project-memory/SKILL.md b/cursor-plugin/skills/recalling-project-memory/SKILL.md index e10e684c2a..b475962027 100644 --- a/cursor-plugin/skills/recalling-project-memory/SKILL.md +++ b/cursor-plugin/skills/recalling-project-memory/SKILL.md @@ -5,6 +5,9 @@ description: 'Use when recalling prior decisions, durable facts, user/project pr # Recalling project memory +Prefer TraceDecay-native registered-project selectors whenever a recall spans or targets a project other than the active checkout. Codex skill guidance may describe how to choose selectors, but selector support should live progressively in TraceDecay MCP and CLI tools themselves. + + Recall memory **before** reaching for external or web search — prior sessions often already answered the question, and a memory hit is cheaper and project-specific. ## Workflow diff --git a/cursor-plugin/skills/recalling-session-context/SKILL.md b/cursor-plugin/skills/recalling-session-context/SKILL.md index 7fd6e6387d..43236ddb89 100644 --- a/cursor-plugin/skills/recalling-session-context/SKILL.md +++ b/cursor-plugin/skills/recalling-session-context/SKILL.md @@ -18,6 +18,7 @@ Climb this ladder cheapest-first; stop as soon as the question is answered. For ## Guardrails - Steps 1–5 are read-only. `tracedecay_lcm_compress`, `tracedecay_lcm_preflight`, and `tracedecay_lcm_session_boundary` are **lifecycle-integration tools for host agents** — never invoke them casually during recall. +- For multi-step recall, dispatch scoped read-only subagents by session id, time window, provider, role, or query variant. Subagents must not call lifecycle or repair tools; the parent agent validates cited messages/summaries and produces the final timeline. - If the LCM store itself looks wrong (missing sessions, broken FTS, stale counts) → `tracedecay_lcm_doctor` (`mode: "diagnose"` first; `repair`/`clean` mutate and need explicit user intent). - All LCM tools default to `storage_scope: "project_local"`; only pass `hermes_profile` (with an absolute `hermes_home`) when the user asks about a Hermes profile store. diff --git a/cursor-plugin/skills/reviewing-a-diff/SKILL.md b/cursor-plugin/skills/reviewing-a-diff/SKILL.md index 2ca57e5128..fc4bf354e9 100644 --- a/cursor-plugin/skills/reviewing-a-diff/SKILL.md +++ b/cursor-plugin/skills/reviewing-a-diff/SKILL.md @@ -18,6 +18,7 @@ description: 'Use when reviewing a PR, branch diff, or working-tree diff for imp ## Guardrails - Read-only review. Do not edit or run tests from this skill; to verify behavior, hand off to the `tracedecay:running-impacted-tests` skill. +- For large diffs, use scoped read-only subagents by file group, subsystem, or risk category. Require cited TraceDecay findings and changed paths; the parent agent owns severity, deduplication, and the final review call. - If diff context is truncated and includes a `handle`, narrow by file/symbol first when possible; call `tracedecay_retrieve` with that `handle` only when the omitted risk detail is needed. ## Output diff --git a/cursor-plugin/skills/searching-for-code/SKILL.md b/cursor-plugin/skills/searching-for-code/SKILL.md index b0b6086fce..2ddc2aa0fd 100644 --- a/cursor-plugin/skills/searching-for-code/SKILL.md +++ b/cursor-plugin/skills/searching-for-code/SKILL.md @@ -7,6 +7,8 @@ description: 'Find code by concept, symbol, signature, or qualified name in this Use the TraceDecay code graph before Grep/Glob/file reads. Pick the cheapest tool that answers the question. +For multi-step context gathering, use scoped read-only subagents when separate questions can run independently. Give each subagent one bounded target (symbol, path, feature, session, or branch), the TraceDecay tools it may use, and a strict "no writes / no edits / no memory mutations" instruction; the parent agent synthesizes findings and performs any follow-up actions. + ## Workflow 1. **Conceptual / "how does X work" / names unknown → `tracedecay_context`.** @@ -26,6 +28,7 @@ Use the TraceDecay code graph before Grep/Glob/file reads. Pick the cheapest too - All tools above are read-only and parallel-safe. Do not call mutating/editing tools from this skill. - Only fall back to Grep/Glob/Read for non-indexed content (string literals, comments, config the graph does not cover) or after TraceDecay pinpoints exact files. - Prefer one well-formed `tracedecay_context` call over many narrow searches. +- When using subagents, ask for cited file/symbol/session ids, tool names used, gaps/uncertainties, and any `tracedecay_metrics:` lines; do not accept uncited conclusions as evidence. - If a response is truncated and includes a `handle`, narrow the query/result set first when possible; call `tracedecay_retrieve` with that `handle` only when the omitted details are needed. - About to write a new helper because the search came up empty? Run the `tracedecay:finding-duplicate-logic` pre-write probe first. diff --git a/cursor-plugin/skills/tracing-functions/SKILL.md b/cursor-plugin/skills/tracing-functions/SKILL.md index 270454ad7a..b540348b93 100644 --- a/cursor-plugin/skills/tracing-functions/SKILL.md +++ b/cursor-plugin/skills/tracing-functions/SKILL.md @@ -18,6 +18,7 @@ description: 'Use when tracing call relationships: who calls a function, what it ## Guardrails - Read-only and parallel-safe. Keep `max_depth` small (1–2) first; widen only when the chain is not yet clear. `tracedecay_rename_preview` only previews references — it does not rename. +- For several independent symbols or call paths, use scoped read-only subagents per symbol, direction, or path hypothesis. Require node ids, depth/tool parameters, and dispatch notes; the parent agent owns the final trace. - If a trace response is truncated and includes a `handle`, narrow depth or target set first when possible; call `tracedecay_retrieve` with that `handle` when the omitted chain details are needed. ## Output diff --git a/docs/MEMORY-CURATION-AUTONOMY.md b/docs/MEMORY-CURATION-AUTONOMY.md new file mode 100644 index 0000000000..43df95c8c1 --- /dev/null +++ b/docs/MEMORY-CURATION-AUTONOMY.md @@ -0,0 +1,293 @@ +# Autonomous Memory Curation Operator Guide + +## Purpose + +This guide turns the autonomous memory curation design into an operator runbook. +It applies to TraceDecay project memory, the standalone dashboard curation UI, +the `tracedecay memory curate` CLI, and wrappers such as Hermes that layer LLM +planning on top of the TraceDecay curation contracts. + +The operating principle is conservative: agents may mine, explain, cluster, +score, and draft curation operations. Durable mutation remains gated by +evidence, risk tier, policy, and review. Memory deletion is permanent by +design. There is no archive, soft-delete state, restore flow, undo flow, or +recycle-bin behavior. + +## Current Curation Surfaces + +Destructive memory curation is parent-agent only. Subagents may inspect, classify, and draft proposed actions within their assigned scope, but they must not apply deletes, merges, retention sweeps, or other irreversible memory mutations. The parent agent owns the final review, tool invocation, and post-action verification. + + +Use existing TraceDecay surfaces before inventing a new plan format: + +- `tracedecay_fact_store`: direct fact get/search/list/probe/related/reason, + add, update, remove, and contradiction checks. +- `tracedecay_memory_status`: memory health and vector/bank repair; use only + when health/counts are part of the task because it may mutate derived state. +- Dashboard preview: + `POST /api/plugins/holographic/curate` with `{"dry_run": true}`. Dry-run is + the default. It returns a report and persists the latest preview to + `.tracedecay/dashboard/curation_preview.json`. +- Dashboard apply: + `POST /api/plugins/holographic/curate` with `{"dry_run": false}` applies the + deterministic similarity-dedup plan by hard-deleting duplicate loser facts. +- Generic apply: + `POST /api/plugins/holographic/curate/apply` with `{"ops": [...]}` applies + explicit `delete` and `merge` operations and reports per-op results. +- CLI dry-run: + `tracedecay memory curate` prints the same deterministic dry-run plan without + requiring the dashboard server. +- CLI LLM review request: + `tracedecay memory curate --llm` emits bounded clusters, hygiene candidates, + allowed fact ids, confidence floor, and chat messages for an external LLM + owner. +- CLI validated LLM ops: + `tracedecay memory curate --llm-ops ` validates external + `{"ops": [...]}` against freshly recomputed evidence and remains dry-run + unless `--apply` is also passed. + +## Native Dry-Run Report Shape + +The deterministic dry-run report is the baseline input for any autonomous +curation workflow: + +```json +{ + "ran": true, + "dry_run": true, + "actions": [ + { + "op": "delete", + "fact_id": 102, + "duplicate_of": 101 + } + ], + "hygiene_candidates": { + "secret_like": [], + "transient": [], + "supersession": [] + }, + "counts": { + "delete": 1 + }, + "applied_counts": null, + "llm_calls": 0, + "coverage": { + "scanned": 3, + "active_total": 3, + "due_remaining": 0 + }, + "provider": "tracedecay", + "mode": "similarity_dedup" +} +``` + +Operator notes: + +- `actions` are executable deterministic similarity-dedup operations. Today + they are delete plans for likely duplicate loser facts. +- `hygiene_candidates` are review evidence only. They may flag `secret_like`, + `transient`, and `supersession` facts, but they are not deterministic apply + operations. +- `counts` describes the proposed plan. `applied_counts` is `null` in dry-run + mode and populated only after apply. +- `coverage.scanned` and `coverage.active_total` give the active fact count + considered by the plan. +- `provider` stays `tracedecay` for standalone deterministic curation. +- `mode` is currently `similarity_dedup`. + +For `tracedecay memory curate --llm`, the report may additionally include +`llm_review`: + +```json +{ + "llm_review": { + "status": "needs_llm_review", + "clusters_reviewed": 2, + "clusters": [], + "hygiene_candidates": {}, + "allowed_fact_ids": [101, 102], + "min_confidence": 0.5, + "messages": [ + { "role": "system", "content": "..." }, + { "role": "user", "content": "..." } + ], + "next_step": "run the messages through an LLM and pass its {\"ops\": [...]} JSON back via: tracedecay memory curate --llm-ops [--apply]" + } +} +``` + +External LLM output must be strict JSON with an `ops` array. Each op includes +`op`, `confidence`, `reason`, and the required ids for that operation. The +TraceDecay validator rejects ops below the confidence floor or referencing fact +ids outside the recomputed clusters and hygiene candidates. + +## Apply Contract + +Use the generic apply contract only after review: + +```json +{ + "ops": [ + { + "op": "delete", + "fact_id": 102, + "reason": "near-exact duplicate of fact 101" + }, + { + "op": "merge", + "winner_id": 101, + "loser_ids": [102], + "merged_content": "Optional consolidated durable fact." + } + ] +} +``` + +Apply responses return per-op results plus aggregate counts. Per-op failures do +not make the whole request fail; malformed bodies are the whole-request failure +case. Merge may rewrite the winner content and then hard-delete losers. Delete +hard-deletes the target fact. Both paths write oplog entries, and delete oplog +details carry hashes rather than deleted content. + +## Operator Workflow + +1. **Resolve scope.** Confirm the active project root and memory store. Project + profiles use user-level TraceDecay storage scoped to the project by default. +2. **Start read-mostly.** Prefer TraceDecay MCP graph/context tools, then + fact-store `get`, `contradict`, `search`, `list`, `probe`, `related`, or + `reason`. Note that some recall-style tools may update access metadata. +3. **Run a native dry-run.** Use dashboard preview or `tracedecay memory + curate`. Save the report, preview timestamp, command/API shape, and project + scope in your notes. +4. **Inventory candidates.** Split findings into `adds`, `updates`, `merges`, + `deletes`, and `skipped`. Preserve fact ids, source/provenance, trust, tags, + entities, similarity evidence, source spans, and counterevidence. +5. **Use subagents for evidence only.** Assign disjoint read-only research + scopes such as session mining, duplicate review, or skeptic review. + Subagents must not call add/update/remove/feedback tools or dashboard apply. +6. **Run the skeptic pass.** Reject unsupported, secret-like, local-only, + transient, stale-but-uncertain, and ambiguous same-topic findings. Do not + lower trust solely because a fact is old. +7. **Produce a dry-run curation report.** Include every proposed operation, + every skipped candidate, and the approval state for any destructive action. +8. **Gate mutation by risk tier.** Add/update/merge require review-first + approval. Delete requires manual approval immediately before apply, showing + fact id, content/source summary, reason, and permanent-delete warning. +9. **Apply narrowly.** Use fact-store add/update only for directly supported + facts. Use `--llm-ops --apply` or `/curate/apply` only for reviewed + ops. Avoid `POST /curate {"dry_run": false}` unless the operator explicitly + approved the deterministic duplicate-deletion plan. +10. **Verify read-only.** Re-run targeted get/search/list/contradict checks and + inspect apply results/oplog. Report changed, skipped, rejected, and still + ambiguous facts. + +## Required Operator Report + +Before any mutation, produce this compact report: + +- `scope`: project root, store/scope, tool/API used, dry-run timestamp, and + whether memory health repair or dashboard start/stop was invoked. +- `native_plan`: `mode`, `provider`, `coverage`, `counts`, `actions` count, and + hygiene-candidate counts. +- `adds`: durable candidate facts with source spans, category, entities, trust, + duplicate-search result, and why they should be stored. +- `updates`: fact ids, old summary, new summary, evidence, confidence, and why + update beats add. +- `merges`: winner id, loser ids, similarity evidence, retained provenance, + optional `merged_content`, and why separate facts are redundant. +- `deletes`: fact ids, content/source summary, permanent-delete reason, risk, + surviving fact if any, and explicit approval status. +- `skipped`: rejected transient, secret-like, unsupported, stale-but-uncertain, + same-topic-not-duplicate, out-of-scope, or duplicate candidates. +- `verification_plan`: exact read-only checks to run after apply. + +## Risk Tiers + +| Tier | Operations | Default | +| --- | --- | --- | +| Read-mostly | MCP context/search, fact get/contradict/search/list/probe/related/reason, dry-run preview | allowed | +| Draft | propose add, update, merge, delete, retag-like notes, LLM review request | allowed | +| Low-risk apply | add clearly durable facts with source links | review-first | +| Medium-risk apply | update or merge facts with retained source evidence | review-first | +| High-risk apply | hard-delete facts or merge losers | manual approval only | + +Deletion and merge loser removal remain high risk because they remove rows from +`memory_facts`; entity links cascade and FTS rows drop. There is no recovery +path other than independently reconstructing a fact from outside evidence. + +## Subagent Roles + +When subagents participate, give each one an explicit project selector and a non-overlapping ownership boundary such as a path set, memory namespace, report section, or review category. Subagents should return evidence-backed recommendations and exact target identifiers, leaving cross-scope reconciliation and destructive curation to the parent agent. + + +- **Session Scout**: mines bounded recent sessions and summaries for durable + facts, explicit "remember" language, superseded facts, repeated pain points, + and source spans. +- **Memory Curator**: clusters candidates against existing facts, similarity + pairs, hygiene candidates, trust/access signals, and recall evidence. +- **Skeptic Reviewer**: tries to disprove each candidate by checking scope, + contradictions, secret exposure, transient state, and same-topic false + positives. +- **Telemetry Analyst**: measures hint uptake, accepted/rejected candidates, + false positives, and audited net token deltas from real transcript data. +- **Apply Operator**: the parent/operator role only. It invokes mutating APIs + after policy and approval gates pass. + +For multi-agent runs, each role owns separate notes or database rows. Writers +do not share editable artifacts. The apply role consumes finalized plans only. + +## Standalone And Wrapper Boundaries + +- Standalone TraceDecay must remain deterministic and useful without Hermes or + any LLM dependency. +- Hermes or another wrapper may own the LLM call, but it must build against the + TraceDecay plan/apply contract and pass reviewed ids only. +- Wrapper planners operate on bounded clusters and hygiene candidates, never on + the full unfiltered session corpus. +- Strict JSON is required for external ops. Unknown operations, low-confidence + operations, and ids outside the evidence guard are rejected. +- Stock TraceDecay contracts must stay usable by the Hermes plugin; wrapper-only + extras cannot become required server behavior. + +## Permanent-Delete Guardrails + +- Never promise archive, restore, undo, recycle-bin, or soft-delete behavior. +- Prefer update or merge-with-retained-provenance over delete when the old fact + still carries useful history. +- Treat hygiene candidates as evidence for review, not as automatic deletes. +- Show content/source summaries before delete approval; avoid copying secrets + verbatim into reports. +- Require explicit manual approval immediately before every hard delete or merge + loser removal unless a future documented policy narrows a lower-risk case. +- Record partial failures and do not retry in a way that hides uncertainty. +- After apply, verify the resulting fact set and report any failed or skipped + operation. + +## Telemetry To Capture + +Telemetry should measure usefulness without overstating savings: + +- Hint emitted/followed/ignored, category match, latency, and dedupe status. +- Candidate lifecycle: mined, clustered, rejected, reviewed, accepted, applied, + failed, or manually overridden. +- Operation risk: add, update, merge, delete, hygiene-only, or + needs-human-review. +- Outcome quality: later recall helpful/unhelpful feedback, duplicate + recurrence, manual corrections, and rejected-candidate reasons. +- Token accounting: audited net token delta using real transcript and usage + data, not gross avoided-read estimates. + +## Verification Targets + +Existing code already covers core dry-run/apply behavior. When curation logic +changes, run the focused tests that match the touched surface: + +- `cargo test curation_delete_lifecycle` +- `cargo test curation_preview_persists_across_dashboard_restarts` +- `cargo test curate_apply_merge_with_missing_loser_is_atomic` +- `cargo test validate_llm_ops_allows_delete_and_merge_with_candidate_evidence` + +For docs-only changes, at minimum inspect the scoped diff and run a Markdown or +spell/style check if the project has one. Do not skip flaky tests to make CI +green; fix them or report the failure honestly. diff --git a/docs/MULTIPROJECT.md b/docs/MULTIPROJECT.md index bb2e59572a..c98796ae7d 100644 --- a/docs/MULTIPROJECT.md +++ b/docs/MULTIPROJECT.md @@ -82,6 +82,9 @@ The query signature churn is mechanical -- every `path_prefix: Option<&str>` met ## Cross-Project Query Ideas +Registered-project selector support belongs in TraceDecay itself, not only in host-specific Codex plugin skills. Add selectors progressively to TraceDecay MCP tools and CLI surfaces as each operation can honor project boundaries safely; plugin skills may document usage, but they should not be the only enforcement or routing layer. + + These are new queries enabled by having `project` as a column: - **Project summary**: node/file/edge counts per project