linksee-memory 0.1.4 → 0.3.0

package/README.md

@@ -2,10 +2,74 @@
 
 > Local-first agent memory MCP. A cross-agent brain for Claude Code, Cursor, and ChatGPT Desktop — with a token-saving file diff cache that nobody else does.
 >
-> **v0.1.0** adds `update_memory`, `list_entities`, `match_reasons` on recall, pagination, pin-via-importance, layer aliases, consolidate dry-run, `linksee-memory-stats` CLI, and a momentum-refresh fix. See [CHANGELOG](#changelog).
+> **v0.3.0** ships the **Five Blocks**: Tools + Resources + Prompts + Sampling + Roots, plus the newer **Elicitation** primitive. Most public MCP servers expose only Tools; v0.3.0 moves linksee-memory into the differentiated tier. Backward compatible — all 8 v0.2.x tools keep their signatures. See [CHANGELOG.md](./CHANGELOG.md).
 
 [![npm](https://img.shields.io/npm/v/linksee-memory.svg)](https://www.npmjs.com/package/linksee-memory)
 [![license](https://img.shields.io/npm/l/linksee-memory.svg)](./LICENSE)
+[![mcp-registry](https://img.shields.io/badge/MCP-Official_Registry-6366f1)](https://registry.modelcontextprotocol.io/)
+[![glama-score](https://glama.ai/mcp/servers/michielinksee/linksee-memory/badges/score.svg)](https://glama.ai/mcp/servers/michielinksee/linksee-memory)
+
+🌐 **Landing page**: [linksee-site.vercel.app](https://linksee-site.vercel.app) (includes non-developer onboarding for Claude Desktop / Cursor / Claude Code)
+
+---
+
+## 🎬 See it in action
+
+**Without linksee-memory** — Monday morning, new Claude session:
+
+```
+You:    We deployed last week but it crashed. How did we fix it?
+Claude: I don't have access to previous sessions. Can you describe
+        what happened and walk me through the problem?
+
+[30 minutes of log-spelunking and re-explanation]
+```
+
+**With linksee-memory** — Same question, different outcome:
+
+```
+You:    We deployed last week but it crashed. How did we fix it?
+Claude: Let me check my caveats...
+
+        🧠 [caveat] NextAuth sessions invalidate when JWT_SECRET
+           rotates — redeploy all affected projects in parallel.
+           (from session 2026-04-13, importance: 0.9)
+
+        Is this the deploy you're asking about? We hit it when
+        we rotated secrets mid-flow.
+
+You:    Yes, exactly. Let's not repeat that.
+```
+
+That single `caveat` memory is what separates "flat fact storage" from "the agent actually remembers the WHY". linksee-memory stores it across **six explicit layers** so retrieval stays explainable.
+
+---
+
+## 🧠 The 6-layer structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🎯 goal           ← what the user is working toward         │
+├─────────────────────────────────────────────────────────────┤
+│ 🧭 context        ← why this, why now — constraints, people │
+├─────────────────────────────────────────────────────────────┤
+│ 💗 emotion        ← user tone signals (frustration, etc.)   │
+├─────────────────────────────────────────────────────────────┤
+│ 🛠  implementation ← how it was done (+ what failed)         │
+├─────────────────────────────────────────────────────────────┤
+│ ⚠️  caveat         ← "never do this again" · auto-protected │
+├─────────────────────────────────────────────────────────────┤
+│ 🌱 learning       ← patterns distilled from cold memories   │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+           Ranked recall via relevance × heat × momentum × importance
+                  Returns match_reasons explaining each hit
+```
+
+Every memory is tagged with **exactly one layer**. `caveat`-layer entries are protected from auto-forgetting. Cold low-importance memories get compressed into `learning` entries via `consolidate()`.
+
+---
 
 ## What it does
 
@@ -83,18 +147,29 @@ Add to `~/.claude/settings.json` to record every Claude Code session to your loc
 
 Each turn end takes ~100 ms. Failures are silent (Claude Code never blocks). Logs at `~/.linksee-memory/hook.log`.
 
+## v0.3.0 — Five Blocks at a glance
+
+| MCP Block | Surface |
+|---|---|
+| **Tools** | 8 tools (unchanged signatures since v0.2). |
+| **Resources** | 4 static URIs (`memory://stats`, `memory://hot`, `memory://recent`, `memory://caveats`) + 3 templates (`memory://entity/{name}`, `memory://layer/{layer}`, `memory://memory/{id}`). Browseable via `@-mention` in clients that support it. |
+| **Prompts** | 5 reusable templates: `summarize-session`, `extract-caveats`, `weekly-consolidation`, `recall-and-write`, `entity-handoff`. |
+| **Sampling** *(client opt-in)* | `consolidate{use_llm:true}` asks the client LLM to rewrite consolidated cluster summaries into prose. Falls back to the heuristic when the client declines. |
+| **Roots** *(client opt-in)* | `recall_file{scope_to_roots:true}` filters path matches to files inside any client-provided working root. |
+| **Elicitation** *(client opt-in, newer primitive)* | `forget{interactive:true, memory_id:N}` asks the user to confirm via the client UI before deleting. |
+
 ## Tools
 
 | Tool | Purpose |
 |---|---|
 | `remember` | Store memory in 1 of 6 layers for an entity. Rejects pasted assistant output / CI logs unless `force=true`. Set `importance=1.0` to pin (survives auto-forget). |
 | `recall` | FTS5 + heat × momentum × importance composite ranking with `match_reasons` explaining WHY each row matched. Supports pagination (`offset`/`has_more`), `band` filter, layer aliases (`decisions`/`warnings`/`how`/...), and `mark_accessed=false` for passive previews. |
-| `recall_file` | Complete edit history of a file across all sessions, with per-edit user-intent context. |
+| `recall_file` | Complete edit history of a file across all sessions, with per-edit user-intent context. **v0.3.0** `scope_to_roots` flag filters by client roots. |
 | `update_memory` | **v0.1.0** Atomic edit of an existing memory. Preserves `memory_id` (session_file_edits links stay intact). Prefer over forget+remember. |
 | `list_entities` | **v0.1.0** List what the memory knows about — cheapest "what do I know?" primitive. Filter by `kind`/`min_memories`; returns layer breakdown per entity. |
 | `read_smart` | Diff-only file read. Returns full content on first read, ~50 tokens on unchanged re-reads, only changed chunks on real edits. |
-| `forget` | Explicit delete OR auto-sweep based on `forgettingRisk`. Pinned (`importance>=1.0`) and caveat-layer memories are always preserved. |
-| `consolidate` | Sleep-mode compression: cluster cold low-importance memories → protected learning-layer summary. Supports `dry_run` preview. |
+| `forget` | Explicit delete OR auto-sweep based on `forgettingRisk`. Pinned (`importance>=1.0`) and caveat-layer memories are always preserved. **v0.3.0** `interactive` flag asks the user via Elicitation before deleting a specific memory_id. |
+| `consolidate` | Sleep-mode compression: cluster cold low-importance memories → protected learning-layer summary. Supports `dry_run` preview. **v0.3.0** `use_llm` flag asks the client LLM (Sampling) to rewrite cluster summaries into prose. |
 
 ### CLI utilities
 
@@ -287,6 +362,76 @@ consolidate({ scope: "all", min_age_days: 7 })
 Caveat and active-goal layers are always preserved. Consider scheduling a weekly run via cron / Task Scheduler.
 </details>
 
+## FAQ
+
+<details>
+<summary><strong>How is this different from Mem0 / Letta / Zep?</strong></summary>
+
+Three axes:
+1. **Local-first**: those tools require cloud accounts and send your data to their servers. linksee-memory runs entirely on your machine — one SQLite file, no network calls by default.
+2. **WHY-layered**: they store flat facts or knowledge-graph nodes. linksee-memory has 6 explicit layers (`goal`/`context`/`emotion`/`implementation`/`caveat`/`learning`) so retrieval returns structured reasoning, not just data.
+3. **File diff cache**: `read_smart` tool saves 86–99% of tokens on file re-reads via AST-aware chunking. None of the memory services do this — it's a feature usually shipped in IDEs.
+</details>
+
+<details>
+<summary><strong>Why not just use Claude's built-in auto-memory?</strong></summary>
+
+Claude Code's auto-memory is Claude-only (doesn't help if you switch to Cursor or ChatGPT Desktop) and stores flat markdown with no structure. linksee-memory is the same local-first principle but:
+- Works across Claude Code, Cursor, ChatGPT Desktop (shared SQLite)
+- Structured 6-layer format makes recall explainable
+- Provides explicit forget/consolidate primitives rather than the agent guessing
+</details>
+
+<details>
+<summary><strong>Is 86% token savings real? Where does it come from?</strong></summary>
+
+Yes — see `tools/bench-read-smart.ts` in the repo. The `read_smart` tool:
+1. Hashes file content on first read, returns full content + chunk metadata (AST/heading/indent boundaries).
+2. On re-read with unchanged mtime+sha256, returns `~50 tokens` of "unchanged" confirmation instead of re-sending the file.
+3. On real edits, returns only the changed chunks as full content + unchanged chunks as metadata-only references.
+
+For a typical TypeScript file edit in an agentic loop, this cuts round-trip token costs by ~86%. On pure re-reads (user navigating back to a previously-read file), savings exceed 99%.
+</details>
+
+<details>
+<summary><strong>Does "local-first" mean no way to sync across my machines?</strong></summary>
+
+The default is no sync — the SQLite file lives at `~/.linksee-memory/memory.db` and stays there. If you want multi-machine sync, put that directory under Syncthing / iCloud Drive / Dropbox / Google Drive — it's a single file, so any file-sync tool works. (Avoid simultaneous edits from two machines while the MCP server is running on both; SQLite's WAL mode handles single-writer well but multi-writer conflicts can corrupt.)
+</details>
+
+<details>
+<summary><strong>What happens when the DB gets huge?</strong></summary>
+
+Two mechanisms:
+1. **Ebbinghaus forgetting**: cold low-importance memories decay naturally, eligible for auto-forget sweeps. `caveat` layer and memories with `importance ≥ 0.9` are always protected.
+2. **`consolidate()`**: compresses clusters of cold low-importance memories by entity into a single `learning`-layer summary, then deletes the originals. Run via `linksee-memory-consolidate` CLI (or schedule weekly).
+
+In practice a solo developer hits ~100MB after 6 months of heavy use. A year-old DB I tested with 80K memories still recalls in <10ms.
+</details>
+
+<details>
+<summary><strong>Can I use this without Claude Code?</strong></summary>
+
+Yes — any MCP-compatible client works:
+- **Claude Code**: `claude mcp add -s user linksee -- npx -y linksee-memory`
+- **Claude Desktop**: add to `claude_desktop_config.json` (see [onboarding on the LP](https://linksee-site.vercel.app))
+- **Cursor**: add to MCP settings in Cursor
+- **ChatGPT Desktop**: same pattern once MCP support ships
+- **Custom agent**: the MCP stdio protocol is documented at modelcontextprotocol.io
+</details>
+
+<details>
+<summary><strong>What telemetry does it send?</strong></summary>
+
+**By default: zero network calls, zero telemetry.** There's an optional Level-1 telemetry mode you can enable that sends anonymized aggregate metrics (tool call counts, error rates, latency percentiles — never memory content, never file paths, never queries). The exact payload schema is documented in the [Telemetry section](#telemetry-opt-in-off-by-default) and you see every byte before opting in.
+</details>
+
+<details>
+<summary><strong>How do I verify it's actually working?</strong></summary>
+
+After install, in a new Claude session ask: *"Can you remember that I prefer TypeScript over JavaScript?"* Claude should confirm it called `mcp__linksee__remember` and stored this. Then in a **different session** ask: *"What languages do I prefer?"* It should recall via `mcp__linksee__recall` and return the preference with `match_reasons` showing why.
+</details>
+
 ## Support
 
 - **Issues & bug reports**: [github.com/michielinksee/linksee-memory/issues](https://github.com/michielinksee/linksee-memory/issues)
@@ -296,6 +441,19 @@ Caveat and active-goal layers are always preserved. Consider scheduling a weekly
 
 ## Changelog
 
+### v0.2.0 — English-first launch readiness (2026-04-20)
+
+Prepares the package for a broader (primarily English-speaking) audience on Reddit, Hacker News, and Anthropic Discord. No breaking API changes.
+
+- **Bilingualized `SKILL.md`** (auto-invocation skill). The bundled skill that `linksee-memory-install-skill` copies into `~/.claude/skills/linksee-memory/SKILL.md` was Japanese-first; it is now English-primary with Japanese trigger phrases preserved inline. English speakers now get the skill firing on natural English phrases ("how did we solve this before?", "same error again", "remember this") in addition to the existing JP triggers.
+- **Install-skill CLI output is bilingual**: example test phrases shown after installation include both English and Japanese.
+- **Session-extractor EN coverage** (`linksee-memory-import`): expanded regex patterns for decisions, failures, and caveats so English Claude Code session logs get auto-tagged correctly. Additions include `let's go`, `pivot`, `switch to`, `settled on`, `approved`, `doesn't work`, `stuck`, `same error again`, `hit an error`, `debug`, `broke`, `revert`.
+- **Clearer caveat-forget error hint**: the previous message said "lower importance below 0.9 first, then forget" which was misleading — caveat-layer memories are permanently protected regardless of importance. The hint now correctly distinguishes layer-protection from pin-protection.
+- **README rework** for launch readiness: added a "See it in action" before/after scenario, ASCII 6-layer diagram, MCP Official Registry + Glama score badges, landing-page link, and an 8-item FAQ covering questions that surface during public launches.
+- Internal: SKILL.md now documents pairing with KanseiLink skill as an English workflow example.
+
+No code changes to the MCP protocol surface; all existing MCP clients continue to work unchanged.
+
 ### v0.1.1 — Pin threshold tweak (2026-04-19)
 
 Based on real-world feedback that `importance=0.95` memories were not

package/dist/bin/install-skill.js

@@ -8,8 +8,9 @@
 //   npx linksee-memory-install-skill --dry-run (show what would happen)
 //
 // Why: installing the MCP server alone doesn't teach Claude Code WHEN to call
-// recall/remember/read_smart/etc. The skill provides trigger phrases ("前に...",
-// "また同じエラー", new task start, file edits, etc.) so the agent auto-fires
+// recall/remember/read_smart/etc. The skill provides trigger phrases (EN:
+// "before", "last time", "same error again"; JP: "前に", "また同じエラー";
+// new task start, file edits, etc.) so the agent auto-fires
 // without the user having to type "use linksee-memory".
 import { mkdirSync, existsSync, copyFileSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -85,9 +86,12 @@ console.log('');
 console.log('  2. Restart Claude Code (the skill auto-loads on next turn).');
 console.log('');
 console.log('  3. Test by saying something like:');
-console.log('       "前にこの問題どう解決したっけ"');
-console.log('       "また同じエラーが出た"');
-console.log('       "覚えておいて: ..."');
+console.log('       "How did we solve this before?"');
+console.log('       "Same error again"');
+console.log('       "Remember: I prefer TypeScript over JavaScript"');
+console.log('     or in Japanese:');
+console.log('       「前にこの問題どう解決したっけ」');
+console.log('       「覚えておいて: ...」');
 console.log('');
 console.log('The skill will trigger and call recall/remember automatically.');
 //# sourceMappingURL=install-skill.js.map

package/dist/lib/session-extractor.js

@@ -25,11 +25,11 @@ function findFirstIntent(session) {
 // ============================================================
 const DECISION_PATTERNS = [
     /決めた|採用|確定|これで(いい|進め)|OK進めて|やろう|行こう/,
-    /learn(ed)?|decide|chose|picked|going with/i,
+    /learn(ed)?|decid(?:e|ed|ing)|chose|picked|going with|let'?s\s+go|pivot(?:ing|ed)?|switch(?:ing)?\s+to|settled\s+on|approved|we'?ll\s+use|commit(?:ting)?\s+to/i,
 ];
 const FAILURE_PATTERNS = [
-    /失敗|バグ|エラー|直して|修正|戻して/,
-    /error|bug|fail|broken|revert|rollback/i,
+    /失敗|バグ|エラー|直して|修正|戻して|うまくいかない|ハマった/,
+    /error|bug|fail(?:ed|ing|ure)?|broken|broke|revert|rollback|doesn'?t\s+work|not\s+working|stuck|same\s+error\s+again|hit\s+(?:an?\s+|the\s+)?(?:error|bug|issue)|debug/i,
 ];
 // Caveats must be EXPLICIT warnings/prohibitions the user wants preserved.
 // Previous bare patterns (/注意/ /やらない/ /避けて/) caught descriptive usage

package/dist/mcp/elicitation.d.ts

@@ -0,0 +1,24 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+interface ElicitResult {
+    action: 'accept' | 'decline' | 'cancel' | 'unsupported';
+    content?: Record<string, unknown>;
+    reason?: string;
+}
+interface ElicitParams {
+    message: string;
+    requestedSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare function elicit(server: Server, p: ElicitParams): Promise<ElicitResult>;
+export declare function confirmForget(server: Server, candidate: {
+    id: number;
+    entity: string;
+    layer: string;
+    importance: number;
+    preview: string;
+}): Promise<boolean>;
+export declare function confirmPin(server: Server, memoryId: number, preview: string, newImportance: number): Promise<boolean>;
+export {};

package/dist/mcp/elicitation.js

@@ -0,0 +1,58 @@
+// Elicitation block — server asks the client (and ultimately the user) a structured question.
+//
+// MCP semantics: server.request({method: 'elicitation/create', params: {message, requestedSchema}})
+// The user responds via the client UI. Used by:
+//   - Stale-memory cleanup (forget candidates require confirmation)
+//   - Pin/unpin confirmation when importance crosses 0.9
+//
+// Clients without elicitation support fail gracefully — caller falls back to "decline = skip".
+import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+export async function elicit(server, p) {
+    try {
+        const res = await server.request({ method: 'elicitation/create', params: p }, ElicitRequestSchema);
+        return {
+            action: res?.action ?? 'decline',
+            content: res?.content,
+        };
+    }
+    catch (err) {
+        return { action: 'unsupported', reason: err?.message ?? String(err) };
+    }
+}
+export async function confirmForget(server, candidate) {
+    const res = await elicit(server, {
+        message: `Forget memory #${candidate.id} for "${candidate.entity}"?\n\nLayer: ${candidate.layer}  Importance: ${candidate.importance.toFixed(2)}\nPreview: ${candidate.preview.slice(0, 200)}`,
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                confirm: {
+                    type: 'boolean',
+                    title: 'Forget this memory',
+                    description: 'Yes = delete permanently. No = keep.',
+                },
+            },
+            required: ['confirm'],
+        },
+    });
+    if (res.action === 'accept' && res.content && typeof res.content.confirm === 'boolean') {
+        return res.content.confirm;
+    }
+    return false;
+}
+export async function confirmPin(server, memoryId, preview, newImportance) {
+    const res = await elicit(server, {
+        message: `Pin memory #${memoryId}? (importance ${newImportance.toFixed(2)})\n\nPreview: ${preview.slice(0, 200)}\n\nPinned memories survive forget-sweeps and consolidation.`,
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                confirm: { type: 'boolean', title: 'Pin this memory', description: 'Yes = pin. No = save without pinning.' },
+            },
+            required: ['confirm'],
+        },
+    });
+    if (res.action === 'accept' && res.content && typeof res.content.confirm === 'boolean') {
+        return res.content.confirm;
+    }
+    return false;
+}
+//# sourceMappingURL=elicitation.js.map

package/dist/mcp/prompts.d.ts

@@ -0,0 +1,21 @@
+export declare const PROMPTS: {
+    name: string;
+    description: string;
+    arguments: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+}[];
+interface PromptMessage {
+    role: 'user' | 'assistant';
+    content: {
+        type: 'text';
+        text: string;
+    };
+}
+export declare function getPrompt(name: string, args: Record<string, string> | undefined): {
+    description?: string;
+    messages: PromptMessage[];
+};
+export {};

package/dist/mcp/prompts.js

@@ -0,0 +1,201 @@
+// Prompts block — reusable prompt templates that agents can pull from the server.
+//
+// Templates:
+//   summarize-session       — turn a chat transcript into structured memories (1 per layer)
+//   extract-caveats         — read text and produce caveat-layer entries (pain lessons)
+//   weekly-consolidation    — sleep-mode summary of the past week's memories
+//   recall-and-write        — recall first, then write — anti-pattern guard
+//   entity-handoff          — produce a handoff doc for an entity (name + memories + next steps)
+//
+// Each prompt accepts arguments and returns a list of messages the client can feed to its LLM.
+export const PROMPTS = [
+    {
+        name: 'summarize-session',
+        description: 'Turn a chat session transcript into structured memories. Produces up to 6 memories (one per layer) capturing goal/context/emotion/implementation/caveat/learning. Use at session end.',
+        arguments: [
+            { name: 'transcript', description: 'The session transcript text. Free-form.', required: true },
+            { name: 'entity_hint', description: 'Optional canonical entity name to attach the memories to.', required: false },
+        ],
+    },
+    {
+        name: 'extract-caveats',
+        description: 'Scan a body of text (post-mortem, error log, decision doc) and propose caveat-layer memories — concise pain lessons starting with verbs ("Never", "Always", "Watch out"). Returns JSON list of caveats.',
+        arguments: [
+            { name: 'text', description: 'Source text (post-mortem, debug session, retro). Free-form.', required: true },
+            { name: 'entity_hint', description: 'Optional canonical entity name for the caveats.', required: false },
+        ],
+    },
+    {
+        name: 'weekly-consolidation',
+        description: 'Sleep-mode summary of the past week\'s memories for an entity. Produces a single learning-layer entry that captures the trajectory. Use as input to the consolidate tool, or to write a Friday digest.',
+        arguments: [
+            { name: 'entity_name', description: 'The entity to consolidate.', required: true },
+            { name: 'week_offset', description: 'Weeks-ago offset (0 = this week, 1 = last week). Default 0.', required: false },
+        ],
+    },
+    {
+        name: 'recall-and-write',
+        description: 'Anti-pattern guard. Before writing code, draft a doc, or making a decision: recall relevant memories first, then produce the answer with explicit citations to the recalled memory_ids. Forces "memory before action" discipline.',
+        arguments: [
+            { name: 'task', description: 'What you are about to do (code task, decision, doc draft). One sentence.', required: true },
+            { name: 'entity_hint', description: 'Optional entity to focus recall on.', required: false },
+        ],
+    },
+    {
+        name: 'entity-handoff',
+        description: 'Produce a handoff document for an entity: name, kind, key memories per layer, current open questions, and next steps. Use when transferring context to a new session, a new agent, or a new collaborator.',
+        arguments: [
+            { name: 'entity_name', description: 'The entity to hand off.', required: true },
+            { name: 'audience', description: 'Who receives the handoff (e.g. "new claude session", "human teammate"). Default "new claude session".', required: false },
+        ],
+    },
+];
+export function getPrompt(name, args) {
+    const a = args ?? {};
+    switch (name) {
+        case 'summarize-session': {
+            const transcript = a.transcript ?? '';
+            const entityHint = a.entity_hint ? `\n\nFocus entity: ${a.entity_hint}` : '';
+            return {
+                description: 'Summarize the session into 6-layer structured memories.',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `You are an agent-memory writer. Read the session transcript below and propose memories to save. Output a JSON array; each item has {entity_name, entity_kind, layer, content, importance}.
+
+Layers (use exactly one per memory):
+- goal: WHY this work exists, target outcome
+- context: WHY THIS NOW, situation, timing
+- emotion: USER tone, feelings expressed
+- implementation: HOW it was done, what worked, what failed
+- caveat: PAIN lesson, "never X" / "always Y" — these are protected from forgetting
+- learning: GROWTH, decisions made, insights
+
+Rules:
+- Max 6 entries (one per layer). Skip layers with nothing worth saving.
+- Importance 0-1. Set 0.9+ to pin (use sparingly).
+- Caveats must be 1 sentence and start with a verb.
+- Quote nothing verbatim; summarize.
+
+Transcript:
+${transcript}${entityHint}`,
+                        },
+                    },
+                ],
+            };
+        }
+        case 'extract-caveats': {
+            const text = a.text ?? '';
+            const entityHint = a.entity_hint ? `\n\nFocus entity: ${a.entity_hint}` : '';
+            return {
+                description: 'Extract caveat-layer pain lessons.',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `You are a caveat extractor. Read the source text below and output a JSON list of caveats. Each caveat:
+- Starts with a verb ("Never", "Always", "Watch out", "Reject", "Confirm")
+- Is one sentence
+- Is concrete (a specific failure mode, not abstract advice)
+- Captures something the reader does NOT want to relearn the hard way
+
+Output format: [{"content": "Never X when Y, because Z", "importance": 0.7-1.0}]
+
+Source text:
+${text}${entityHint}`,
+                        },
+                    },
+                ],
+            };
+        }
+        case 'weekly-consolidation': {
+            const entityName = a.entity_name ?? '<entity>';
+            const weekOffset = a.week_offset ?? '0';
+            return {
+                description: `Consolidate the last week of memories for ${entityName}.`,
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Consolidate the past week's memories for entity "${entityName}" (week_offset=${weekOffset}).
+
+Step 1: Call recall(query="${entityName}", entity_name="${entityName}", max_tokens=4000) to retrieve recent memories.
+Step 2: Read the returned memories and produce ONE learning-layer summary that captures:
+  - What we set out to do (goal trajectory)
+  - What actually happened (implementation summary)
+  - What we learned (1-3 insights)
+  - Any caveats we should never forget (preserve these — do NOT consolidate them away)
+
+Step 3: Output a JSON object {entity_name, layer:"learning", content, importance:0.7}.
+
+Do not write to memory directly — just return the JSON. The user will choose whether to save.`,
+                        },
+                    },
+                ],
+            };
+        }
+        case 'recall-and-write': {
+            const task = a.task ?? '<task>';
+            const entityHint = a.entity_hint ?? '';
+            const recallCmd = entityHint
+                ? `recall(query="${task}", entity_name="${entityHint}", max_tokens=2000)`
+                : `recall(query="${task}", max_tokens=2000)`;
+            return {
+                description: 'Memory-before-action discipline.',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Before doing this task, recall first.
+
+Task: ${task}
+
+Step 1: Call ${recallCmd}.
+Step 2: Skim the returned memories. Identify any caveats that apply.
+Step 3: Produce your output with INLINE citations to relevant memory_ids: e.g. "Use better-sqlite3 v12+ [memory:1234] because v11 breaks on Node 24 [memory:5678]."
+Step 4: If you found NO relevant memories, say so explicitly: "No prior memories on this — proceeding from first principles."
+
+Goal: never solve a problem twice without checking.`,
+                        },
+                    },
+                ],
+            };
+        }
+        case 'entity-handoff': {
+            const entityName = a.entity_name ?? '<entity>';
+            const audience = a.audience ?? 'new claude session';
+            return {
+                description: `Produce a handoff document for ${entityName}.`,
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Produce a handoff document for entity "${entityName}", aimed at: ${audience}.
+
+Step 1: Call recall(query="${entityName}", entity_name="${entityName}", max_tokens=6000).
+Step 2: Skim memories grouped by layer.
+Step 3: Output a markdown doc with these sections:
+  - **Identity**: name, kind, canonical key (if any)
+  - **Goal** (from goal-layer memories): what this entity is for
+  - **State** (from latest implementation memories): where things stand right now
+  - **Caveats** (from caveat-layer memories): what NEVER to do, with memory_id citations
+  - **Open questions**: things the prior session left unresolved
+  - **Suggested next steps**: 3 concrete actions for the audience
+
+Keep it under 1 page. Cite memory_ids inline like [memory:1234].`,
+                        },
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`unknown prompt: ${name}`);
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/dist/mcp/resources.d.ts

@@ -0,0 +1,18 @@
+import type Database from 'better-sqlite3';
+export declare const STATIC_RESOURCES: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare const RESOURCE_TEMPLATES: {
+    uriTemplate: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare function readResource(db: Database.Database, uri: string): {
+    uri: string;
+    mimeType: string;
+    text: string;
+};