feat(skill-memory): per-skill cross-session recall + historian auto-extraction

[iceteaSA]

Summary

Adds skill-memory — per-skill "motor memory" that gives a skill cross-session recall of its own hard-won lessons (gotchas, discoveries, fixes, workflow steps). When a skill's SKILL.md declares skill-memory: { enabled: true }, accumulated notes for that skill surface automatically in a <skill-memory> block appended to the skill tool's result on every load — and, with the historian extension, the historian writes those notes automatically during compaction (no agent action required).

It's fully opt-in per skill and cache-safe by construction: the block rides the tool-result tail (conversation), never the cached system/m[0] prefix, so it can't bust the prompt cache.

How it works

• Transparent recall — three-hook augmentation: tool.definition advertises an intent param; tool.execute.before stashes the intent (bounded TTL); the after-hook parses the skill's Base directory, reads its SKILL.md frontmatter, and formats the recall block. Lands in the tool RESULT (cache-safe).
• Write paths — ctx_skill_note (agent-authored) and the historian (auto-extracted). Both dedup on a normalized hash.
• Intent-scoped ranking — a recall cascade: model-matched embeddings → cosine blend over intent_embedding + delta_embedding (relevance/recency/hit weights tunable per skill via ranking_* frontmatter); FTS5 fallback over a content-linked skill_memory_fts vtable; flat recency×hit fallback.
• Historian auto-extraction — the historian sees TC: skill(<name>) markers in its chunk and emits a <skill_observations> block; both the OpenCode and Pi runners promote those post-commit as global notes (project_identity='*', source_type='historian'), recallable from any project.

Review units (4 commits)

The branch is organized into four coherent, reviewable phases:

1. P1 — transparent per-skill recall: skill_memory table migration, the three-hook augmentation, flat recall + storage, ctx_skill_note/ctx_skill_recall tools, opt-in distill-skill-memory dreamer task, TUI/ctx-status stats, docs.
2. P2 — embeddings + intent-scoped recall: delta_embedding + recall_count columns + skill_memory_fts FTS5 vtable; embed-on-write; the cosine/FTS recall cascade; a programmatic (no-LLM) reembed pre-step.
3. P3a — historian-extraction foundation: the TC: skill(<name>) marker keystone; origin_project + source_type columns; global-tier notes unified under project_identity='*' (collision-merge); partitionKey routing.
4. P3b — historian auto-extraction pipeline: prompt emits <skill_observations>, parser, validated-result threading, both runners promote via the shared promoteSkillObservations helper, plus an initializeDatabase self-heal net (re-creates skill_memory + ensureColumn so an upgraded DB recovers even if a migration row is lost).

Schema / migrations

Three migrations (numbered after the current master ceiling): skill_memory table, then delta_embedding/recall_count/FTS, then origin_project/source_type/* unification. LATEST_SUPPORTED_VERSION bumped in lockstep (the schema-version-fence test enforces it). Migration bodies are ensureColumn/IF NOT EXISTS idempotent.

Testing

Full plugin + Pi suites pass (one unrelated pre-existing full-suite ordering flake in tui-config.test.ts that passes in isolation), tsc clean both packages, lint clean, build produces all bundles. Dedicated coverage for the migrations (coexistence + fence), recall rungs, the tools, FTS triggers/backfill, the '*' collision-merge, and the historian promotion path on both runners. Verified working live: the historian auto-extraction writes genuine source_type='historian' notes, embeddings populate, and the read-side recall_count increments on surfacing.

Notes for reviewers

• Migration version numbers are placeholders relative to this fork's base — happy to renumber to whatever slots are free at merge time.
• The four commits are independently meaningful; if you'd prefer this as stacked PRs (P1 / P2 / historian), I can split it.

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

---

Summary by cubic

Adds per-skill cross-session memory with embedding + FTS ranking and historian auto-extraction. Each skill result now appends a <skill-memory> block; ctx_skill_note/ctx_skill_recall manage notes, and the distill-skill-memory task pre-embeds and emits a read-only corpus health report (TUI/ctx-status show per-project stats).

• New Features

  • Transparent, opt‑in per‑skill recall: the skill tool advertises optional intent; before/after hooks stash intent and inject recall; enable via SKILL.md (skill-memory: { enabled: true }). Prompt guidance added.
  • Intent‑scoped ranking: cosine over intent_embedding + delta_embedding with FTS5 fallback; recall_count tracked; a pre‑step re‑embeds NULL/stale vectors before distill-skill-memory.
  • Historian auto‑extraction: TC: skill(<name>) markers → <skill_observations>; both OpenCode and Pi promote as global '*' notes (source_type='historian').
  • Distill task: distill-skill-memory (off by default) added to config/CLI/dashboard; runs the re‑embed pre‑step and outputs a health summary; TUI/ctx-status display totals/skills/pinned.
  • Schema/self‑heal: migrations v51–v53 add skill_memory + FTS and origin_project/source_type; initializeDatabase can create/repair tables and rebuild skill_memory_fts.

• Bug Fixes

  • Cross‑partition recall: union a skill’s project partition with global '*' so project‑local skills surface historian notes; writes/dedup remain exact‑partition.
  • Frontmatter/provenance: accept inline { enabled: true }; start‑of‑file anchored with BOM/whitespace tolerance and # handling; accept plain paths and file://; take the last, line‑anchored “Base directory” match; normalize Windows paths.
  • Stability/observability/budget: avoid init crash when plugin is disabled; session‑scoped intent stash (sessionId:callId, TTL + bounded size); log recall errors; escape apostrophes in SQL; count per‑note XML framing and clamp pinned budget.
  • Tools/tests: reject ctx_skill_note when disabled; ctx_skill_recall cold‑start search and tier derivation fixed; injected intent schema for skill; compiled TUI refreshed; embedding tests use the provider‑factory seam to prevent cross‑file bleed.

^{Written for commit bc53e1d. Summary will update on new commits.}

Greptile Summary

This PR introduces skill-memory — a fully opt-in, per-skill cross-session recall system. When a skill's SKILL.md declares skill-memory: { enabled: true }, accumulated lessons are recalled automatically as a <skill-memory> block appended to the skill tool result. The historian extension auto-extracts observations during compaction without requiring any agent action.

• Storage + recall (P1–P2): Three migrations (v51–v53) create the skill_memory table, FTS5 virtual table with triggers, and historian provenance columns. Recall uses a 4-rung cascade (cosine embedding → FTS5 → flat recency×hit) with a cross-partition recallPartitionPredicate union ensuring historian notes surface for project-local skills. All issues from prior review threads are addressed.
• Historian auto-extraction (P3a–P3b): promoteSkillObservations writes historian-extracted lessons as global tier='global'/project_identity='*' notes; both OpenCode and Pi runners promote via the shared helper with the same promotionActive && !discardedLast guard used for facts and primers.
• New tools: ctx_skill_note records agent-authored notes with exact-hash and semantic dedup; ctx_skill_recall provides explicit recall with registry-first resolution and disk-fallback for cold sessions.

Confidence Score: 5/5

Safe to merge. All four prior review threads were properly addressed and remaining findings are minor design trade-offs or style nits that do not affect correctness.

The prior review identified four concrete defects (session-scoped intent stash, FTS rebuild on self-heal, historian cross-partition recall, disabled-skill note guard) — all confirmed fixed. New findings are a redundant function call (style), a known cross-partition dedup trade-off, and a multi-model embedding consistency gap for global historian notes. None cause data loss or incorrect behavior in single-model deployments, and all have graceful fallbacks.

packages/plugin/src/features/magic-context/skill-memory/reembed.ts — global-note re-embed using the calling project's model version is worth revisiting if per-project embedding model configuration is ever adopted. packages/plugin/src/features/magic-context/skill-memory/storage.ts — cross-partition dedup blind spot in findExistingNote warrants a follow-up if duplicate lesson surfacing is reported by users.

Important Files Changed

Filename	Overview
packages/plugin/src/features/magic-context/skill-memory/storage.ts	New file: core storage layer for skill-memory. Well-structured with recallPartitionPredicate union logic for cross-partition recall. Minor: searchSkillMemoryFts calls recallPartitionPredicate twice unnecessarily. Write/dedup paths intentionally stay exact-partition.
packages/plugin/src/features/magic-context/skill-memory/recall.ts	New file: 4-rung recall cascade (cosine embedding → FTS5 → flat recency×hit). budgetFill correctly clamps pinned sub-budget against total tokens. Error handling now uses log() as noted in prior review.
packages/plugin/src/features/magic-context/skill-memory/promote.ts	New file: historian extraction promotion path. Correctly writes global-tier '*' partition notes with best-effort per-item error handling. Hash-dedup is exact-partition only (intentional design choice).
packages/plugin/src/features/magic-context/migrations.ts	Three new migrations (v51–v53) adding skill_memory table, FTS5 vtable + triggers, and historian provenance columns. All use ensureColumn/IF NOT EXISTS for idempotency. LATEST_SUPPORTED_VERSION bumped to 53.
packages/plugin/src/hooks/magic-context/hook-handlers.ts	Adds tool.execute.before hook (stashes intent keyed sessionId:callId), extends tool.execute.after to populate skillLoadRegistry and inject the <skill-memory> recall block. Intent map uses composite session-scoped keys as fixed in prior review.
packages/plugin/src/tools/ctx-skill-note/tools.ts	New ctx_skill_note tool with correct enabled guard (added per prior review), exact-hash and semantic dedup, embedding on write. Registry-lookup gated on frontmatterConfig.enabled before any DB write.
packages/plugin/src/features/magic-context/storage-db.ts	Self-heal initializeDatabase path adds skill_memory table + FTS vtable + triggers, includes the guarded FTS rebuild (fixed per prior review), and ensureColumn calls for P2/P3 columns. LATEST_SUPPORTED_VERSION bumped to 53.
packages/plugin/src/features/magic-context/skill-memory/reembed.ts	New programmatic re-embed pre-step for the distill task. Correctly identifies stale/NULL embeddings with NULL-safe IS NOT ?. Includes global '*' partition rows using the calling project's embedding provider, which may cause model-version mismatches across multi-model deployments.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent
    participant skill tool
    participant tool.execute.before
    participant tool.execute.after
    participant SkillLoadRegistry
    participant recallSkillMemoryBlock
    participant DB as SQLite DB

    Agent->>skill tool: skill(name, intent?)
    skill tool->>tool.execute.before: fires pre-validation
    tool.execute.before->>tool.execute.before: stashIntent(sessionId:callId, intent)

    skill tool-->>Agent: skill result (Base directory: ...)
    skill tool->>tool.execute.after: fires post-execution
    tool.execute.after->>tool.execute.after: parseSkillProvenance(output)
    tool.execute.after->>tool.execute.after: parseFrontmatterConfig(SKILL.md)
    tool.execute.after->>SkillLoadRegistry: set(sessionId:skillId, provenance+config)
    tool.execute.after->>tool.execute.after: getAndDeleteIntent(sessionId:callId)
    tool.execute.after->>recallSkillMemoryBlock: recall(skill, intent, tier, projectIdentity)
    recallSkillMemoryBlock->>DB: embedTextForProject(intent)
    recallSkillMemoryBlock->>DB: getRankingCandidates (cosine rung)
    alt embeddings match
        recallSkillMemoryBlock->>DB: rankRung1 + budgetFill
    else FTS fallback
        recallSkillMemoryBlock->>DB: searchSkillMemoryFts
    else flat fallback
        recallSkillMemoryBlock->>DB: getSkillMemoryNotes
    end
    recallSkillMemoryBlock->>DB: bumpRecallCountByIds
    recallSkillMemoryBlock-->>tool.execute.after: skill-memory block
    tool.execute.after->>tool.execute.after: append block to output.output

    Note over Agent,DB: Historian auto-extraction
    Historian->>promoteSkillObservations: skillObservations[]
    promoteSkillObservations->>DB: "INSERT tier=global project_identity=*"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent
    participant skill tool
    participant tool.execute.before
    participant tool.execute.after
    participant SkillLoadRegistry
    participant recallSkillMemoryBlock
    participant DB as SQLite DB

    Agent->>skill tool: skill(name, intent?)
    skill tool->>tool.execute.before: fires pre-validation
    tool.execute.before->>tool.execute.before: stashIntent(sessionId:callId, intent)

    skill tool-->>Agent: skill result (Base directory: ...)
    skill tool->>tool.execute.after: fires post-execution
    tool.execute.after->>tool.execute.after: parseSkillProvenance(output)
    tool.execute.after->>tool.execute.after: parseFrontmatterConfig(SKILL.md)
    tool.execute.after->>SkillLoadRegistry: set(sessionId:skillId, provenance+config)
    tool.execute.after->>tool.execute.after: getAndDeleteIntent(sessionId:callId)
    tool.execute.after->>recallSkillMemoryBlock: recall(skill, intent, tier, projectIdentity)
    recallSkillMemoryBlock->>DB: embedTextForProject(intent)
    recallSkillMemoryBlock->>DB: getRankingCandidates (cosine rung)
    alt embeddings match
        recallSkillMemoryBlock->>DB: rankRung1 + budgetFill
    else FTS fallback
        recallSkillMemoryBlock->>DB: searchSkillMemoryFts
    else flat fallback
        recallSkillMemoryBlock->>DB: getSkillMemoryNotes
    end
    recallSkillMemoryBlock->>DB: bumpRecallCountByIds
    recallSkillMemoryBlock-->>tool.execute.after: skill-memory block
    tool.execute.after->>tool.execute.after: append block to output.output

    Note over Agent,DB: Historian auto-extraction
    Historian->>promoteSkillObservations: skillObservations[]
    promoteSkillObservations->>DB: "INSERT tier=global project_identity=*"

Loading

Comments Outside Diff (1)

1. packages/plugin/src/features/magic-context/skill-memory/recall.ts, line 481-484 (link)

   Bare catch {} makes recall errors invisible

   Any exception thrown inside recallSkillMemoryBlock — a SQLite error, embedding provider crash, or a coding mistake — is silently swallowed and returns an empty string. From the caller's perspective this is indistinguishable from "no notes exist" or "skill-memory disabled". At minimum a sessionLog or console.warn call here would let a developer diagnose why the recall block is absent without attaching a debugger.

_{Reviews (16): Last reviewed commit: "fix(test): stop global embedding mock.mo..." | Re-trigger Greptile}

[cubic-dev-ai]

11 issues found across 78 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/plugin/src/features/magic-context/dreamer/task-executor.ts">

<violation number="1" location="packages/plugin/src/features/magic-context/dreamer/task-executor.ts:419">
P2: Re-embed pre-step errors are suppressed, allowing successful task completion reporting despite a failed prerequisite data maintenance step.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 40 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.

Re-trigger cubic</sub>

[cubic-dev-ai]

4 issues found across 15 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/plugin/src/features/magic-context/dreamer/task-executor.ts">

<violation number="1" location="packages/plugin/src/features/magic-context/dreamer/task-executor.ts:419">
P2: Re-embed pre-step errors are suppressed, allowing successful task completion reporting despite a failed prerequisite data maintenance step.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

4 issues found across 78 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/plugin/src/features/magic-context/dreamer/task-executor.ts">

<violation number="1" location="packages/plugin/src/features/magic-context/dreamer/task-executor.ts:419">
P2: Re-embed pre-step errors are suppressed, allowing successful task completion reporting despite a failed prerequisite data maintenance step.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 40 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/plugin/src/features/magic-context/skill-memory/reembed.test.ts">

<violation number="1" location="packages/plugin/src/features/magic-context/skill-memory/reembed.test.ts:53">
P3: Redundant `_setTestProviderFactoryForProject(null)` call before `installReembedTestProvider()` -- the `installReembedTestProvider()` lambda immediately overwrites the factory anyway. The `_resetProjectEmbeddingRegistryForTests()` already clears the factory to null, so this extra call is a no-op. Looks like a fragment from an earlier refactor; consider dropping the middle call to keep the setup intent clear.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Redundant _setTestProviderFactoryForProject(null) call before installReembedTestProvider() -- the installReembedTestProvider() lambda immediately overwrites the factory anyway. The _resetProjectEmbeddingRegistryForTests() already clears the factory to null, so this extra call is a no-op. Looks like a fragment from an earlier refactor; consider dropping the middle call to keep the setup intent clear.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/plugin/src/features/magic-context/skill-memory/reembed.test.ts, line 53:

<comment>Redundant `_setTestProviderFactoryForProject(null)` call before `installReembedTestProvider()` -- the `installReembedTestProvider()` lambda immediately overwrites the factory anyway. The `_resetProjectEmbeddingRegistryForTests()` already clears the factory to null, so this extra call is a no-op. Looks like a fragment from an earlier refactor; consider dropping the middle call to keep the setup intent clear.</comment>

<file context>
@@ -1,71 +1,116 @@
+describe("reembed", () => {
+    test("reembedStaleSkillNotes fills NULL embeddings (bounded, idempotent)", async () => {
+        _resetProjectEmbeddingRegistryForTests();
+        _setTestProviderFactoryForProject(null);
+        installReembedTestProvider();
+
</file context>