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 includes a <skill-memory> block; ctx_skill_note/ctx_skill_recall manage notes, and the distill-skill-memory task pre-embeds and reports corpus health (TUI/ctx-status show stats).

• New Features

  • Transparent, opt-in per-skill recall: the skill tool accepts optional intent; before/after hooks stash intent and inject recall; enable via SKILL.md frontmatter (skill-memory: { enabled: true }). Status/TUI/ctx-status show per-project totals and pinned counts.
  • Intent-scoped ranking: cosine blend over intent_embedding + delta_embedding with FTS5 fallback; recall_count tracked; a pre-step re-embeds NULL/stale vectors before the distill run.
  • Historian auto-extraction: TC: skill(<name>) markers → <skill_observations>; OpenCode and Pi promote via promoteSkillObservations as global '*' notes (source_type='historian').
  • Distill task: distill-skill-memory (off by default) runs the re-embed pre-step and emits a read-only corpus health report.
  • Schema/self-heal: migrations v51–v53 add skill_memory + FTS and origin_project/source_type; initializeDatabase can rebuild skill_memory_fts; global '*' partition helpers and project-scoped stats added.

• Bug Fixes

  • Cross-partition recall: union the skill’s project partition with global '*' so project-local skills surface historian notes; writes/dedup stay exact-partition.
  • Frontmatter/provenance: reject ctx_skill_note when disabled; accept inline { enabled: true }; start-of-file anchored with BOM/whitespace tolerance and inline # handling; accept plain paths and file://; normalize Windows paths; correct global vs project tiering; keep the last, line-anchored “Base directory” match.
  • Guidance/observability/budget: drop ctx_memory cross-ref when memory is off; log recall errors; count per-note XML framing and clamp pinned budget.
  • Safety + misc: avoid init crash when the plugin is disabled; session-scoped intent stash (sessionId:callId); escape apostrophes in SQL; compiled TUI regenerated to match source so the Skill Memory section renders.
  • Tests: replace global embedding mock.module with the provider-factory seam (_setTestProviderFactoryForProject + registerProjectEmbedding) to stop cross-file bleed and timeouts; stabilize embedding-related tests.

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

Greptile Summary

This PR introduces skill-memory — opt-in per-skill cross-session recall that appends a <skill-memory> block to each skill tool result, backed by SQLite with embedding + FTS5 ranking and historian auto-extraction. All previously-flagged blocking issues have been addressed in follow-up commits.

• Transparent recall pipeline: three-hook augmentation (tool.definition injects intent param; tool.execute.before stashes it; tool.execute.after reads SKILL.md frontmatter from disk and appends the <skill-memory> block) lands in the tool result — cache-safe by construction.
• Ranking cascade: cosine blend over intent_embedding + delta_embedding (rung 1) → FTS5 BM25 fallback (rung 3) → flat recency×hit (rungs 2/4); pinned notes always surface first within the token budget; recall_count tracked separately from write-side hit_count.
• Historian auto-extraction: TC: skill(<name>) markers → <skill_observations> output → promoteSkillObservations writes global-tier '*' partition notes via both OpenCode and Pi runners; three new migrations (v51–v53) add the table, FTS vtable, and origin_project/source_type columns with idempotent ensureColumn guards.

Confidence Score: 5/5

Safe to merge. All previously-identified bugs have been corrected in follow-up commits and the new code is well-guarded throughout.

All previously-identified bugs have been corrected: session-scoped intent keying, the redundant dynamic import hoist, the FTS rebuild self-heal gap, the project-local skill historian orphan, and the disabled-skill orphan write. The remaining findings are two style-level naming/duplication nits that carry no runtime risk. Migrations are idempotent, the recall cascade degrades gracefully at every rung, and the historian promotion path is gated correctly behind promotionActive && !discardedLast.

No files require special attention. storage.ts and hook-handlers.ts have minor style suggestions but no blocking issues.

Important Files Changed

Filename	Overview
packages/plugin/src/features/magic-context/skill-memory/storage.ts	New file: core DB layer for skill_memory — insert, dedup, recall, FTS, and stats helpers. searchSkillMemoryFts calls recallPartitionPredicate twice unnecessarily (P2 suggestion posted).
packages/plugin/src/features/magic-context/skill-memory/recall.ts	New file: three-rung recall cascade (embeddings → FTS5 → flat recency×hit). budgetFill correctness holds throughout; errors are now logged via log(), addressing the previously-flagged bare-catch concern.
packages/plugin/src/hooks/magic-context/hook-handlers.ts	Adds intent stash before-hook and skill-memory injection into the after-hook. Previously-flagged session-bleed and redundant import are fixed. stashIntent parameter named callId but always receives a composite key (P2 suggestion posted).
packages/plugin/src/hooks/magic-context/hook.ts	Wires intentByCallId, skillLoadRegistry, and sessionDirectoryBySession; registers tool.execute.before; prunes both maps in onSessionDeleted by session prefix. Session cleanup logic is correct.
packages/plugin/src/features/magic-context/migrations.ts	Adds migrations v51–v53: skill_memory table, FTS5 + embeddings columns, and origin_project/source_type with global-* unification. Idempotent throughout; v53 collision-merge runs inside a transaction.
packages/plugin/src/features/magic-context/storage-db.ts	Adds skill_memory table + FTS triggers to initializeDatabase; guarded FTS rebuild self-heal addresses previously-flagged gap. All ensureColumn calls are present.
packages/plugin/src/tools/ctx-skill-note/tools.ts	New agent-callable tool. Enabled-guard added (addresses orphan-write issue). Hash-dedup + semantic cosine dedup before insert; race-condition dedup on null return.
packages/plugin/src/tools/ctx-skill-recall/tools.ts	New agent-callable explicit recall tool. Registry-first with disk-fallback for cold-start; hardcoded candidate dirs cover all documented opencode discovery paths.
packages/plugin/src/hooks/magic-context/compartment-runner-incremental.ts	Skill-observation promotion behind same promotionActive && !discardedLast gate as facts/primers. Uses resolved project identity consistently.
packages/pi-plugin/src/pi-historian-runner.ts	Pi-runner mirror of historian promotion. projectPath is resolveProjectIdentity(directory) — same resolved form as the OpenCode runner, so origin_project values are consistent.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Model
    participant Hook as tool.execute hooks
    participant Registry as SkillLoadRegistry
    participant DB as skill_memory (SQLite)
    participant Historian

    Model->>Hook: tool.execute.before (skill, intent)
    Hook->>Hook: stashIntent(sessionId:callId, intent)

    Model->>Hook: tool.execute.after (skill result)
    Hook->>Hook: parseSkillProvenance(output)
    Hook->>Hook: parseFrontmatterConfig(SKILL.md)
    Hook->>Registry: set(sessionId:skillId, provenance + config)
    Hook->>DB: recallSkillMemoryBlock()
    Note over DB: Rung 1: cosine(intent+delta embeddings)<br/>Rung 3: FTS5 BM25<br/>Rung 4: flat recency x hit_count
    DB-->>Hook: skill-memory block
    Hook->>Model: appended to output.output

    Model->>Hook: ctx_skill_note(skill, kind, delta)
    Hook->>Registry: getSkillLoad(sessionId, skill)
    Hook->>DB: findExistingNote / insertSkillMemoryNote
    DB-->>Hook: id or null (dedup)

    Historian->>DB: promoteSkillObservations(global tier)
    Note over DB: source_type=historian<br/>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 Model
    participant Hook as tool.execute hooks
    participant Registry as SkillLoadRegistry
    participant DB as skill_memory (SQLite)
    participant Historian

    Model->>Hook: tool.execute.before (skill, intent)
    Hook->>Hook: stashIntent(sessionId:callId, intent)

    Model->>Hook: tool.execute.after (skill result)
    Hook->>Hook: parseSkillProvenance(output)
    Hook->>Hook: parseFrontmatterConfig(SKILL.md)
    Hook->>Registry: set(sessionId:skillId, provenance + config)
    Hook->>DB: recallSkillMemoryBlock()
    Note over DB: Rung 1: cosine(intent+delta embeddings)<br/>Rung 3: FTS5 BM25<br/>Rung 4: flat recency x hit_count
    DB-->>Hook: skill-memory block
    Hook->>Model: appended to output.output

    Model->>Hook: ctx_skill_note(skill, kind, delta)
    Hook->>Registry: getSkillLoad(sessionId, skill)
    Hook->>DB: findExistingNote / insertSkillMemoryNote
    DB-->>Hook: id or null (dedup)

    Historian->>DB: promoteSkillObservations(global tier)
    Note over DB: source_type=historian<br/>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 (14): 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>