linksee-memory 0.0.9 → 0.1.0

package/README.md

@@ -1,6 +1,8 @@
 # linksee-memory
 
 > 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).
 
 [![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)
@@ -85,12 +87,24 @@ Each turn end takes ~100 ms. Failures are silent (Claude Code never blocks). Log
 
 | Tool | Purpose |
 |---|---|
-| `remember` | Store memory in 1 of 6 layers for an entity |
-| `recall` | FTS5 + heat-score + momentum composite ranking, JP/EN trigram search |
-| `recall_file` | Get the COMPLETE edit history of a file across all sessions, with per-edit user-intent context |
-| `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 (importance × heat × age) |
-| `consolidate` | Sleep-mode compression: cluster cold low-importance memories → protected learning-layer summary |
+| `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. |
+| `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. |
+
+### CLI utilities
+
+| Command | Purpose |
+|---|---|
+| `npx linksee-memory` | MCP server (stdio) |
+| `npx linksee-memory-sync` | Claude Code Stop-hook entry point |
+| `npx linksee-memory-import` | Batch-import Claude Code session JSONL history |
+| `npx linksee-memory-install-skill` | Install the Claude Code Skill that teaches the agent when to call recall/remember/read_smart |
+| `npx linksee-memory-stats` | **v0.1.0** Summary of the local DB (entity count / layer breakdown / top entities / top edited files). Add `--json` for machine-readable output. |
 
 ## The 6 memory layers
 
@@ -280,6 +294,49 @@ Caveat and active-goal layers are always preserved. Consider scheduling a weekly
 - **Security concerns**: see [SECURITY.md](./SECURITY.md) if present, or file a private advisory on GitHub
 - **Company**: Synapse Arrows PTE. LTD. (Singapore)
 
+## Changelog
+
+### v0.1.0 — Major UX update (2026-04-18)
+
+Based on one week of dogfooding, here's what changed:
+
+**New tools**
+- `update_memory` — atomic edit with preserved `memory_id`. Solves the "forget+remember breaks session_file_edits links" bug.
+- `list_entities` — fast "what do I know about?" primitive for session init. Supports `kind`/`min_memories` filters and returns layer breakdown.
+- `npx linksee-memory-stats` — local DB summary CLI.
+
+**`recall` enhancements**
+- `match_reasons` array on each memory: e.g. `["content_match_fts", "heat:hot", "pinned"]`.
+- `score_breakdown` with per-dimension scores (relevance / heat / momentum / importance).
+- Pagination via `offset` / `has_more` / `stopped_by`.
+- `limit` parameter (hard cap, complements `max_tokens` budget).
+- `band` filter to request only hot/warm/cold/frozen memories.
+- `mark_accessed=false` for preview queries that shouldn't bump heat.
+- **Layer aliases**: `decisions` → `learning`, `warnings` → `caveat`, `how` → `implementation`, etc.
+- **Fix**: opportunistic refresh of stale entity momentum scores. Entities recalled >1 h after last remember() no longer return stale momentum.
+
+**`remember` enhancements**
+- Quality check: rejects pasted assistant output / CI logs / stack traces unless `force=true`.
+- `importance=1.0` now implicitly pins the memory (survives auto-forget).
+- Layer aliases accepted.
+
+**`forget` changes**
+- Pinned memories (importance=1.0) now preserved alongside caveat-layer memories.
+- Clear error response when attempting to delete a protected or missing memory.
+- dry-run now includes `sample_ids_to_drop`.
+
+**`consolidate` changes**
+- `dry_run: true` preview mode — reports cluster count + candidates without writing.
+
+**Infra**
+- Fixed fresh-DB migration bug (was querying `meta` table before it existed).
+- Bumped to Node 20+ for structured language feature usage.
+
+All changes are **backward compatible** — existing integrations continue to work. Server.ts version banner now reports `v0.1.0`.
+
+### Older versions
+See [GitHub Releases](https://github.com/michielinksee/linksee-memory/releases).
+
 ## License
 
 MIT — Synapse Arrows PTE. LTD.

package/dist/bin/stats.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/stats.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// linksee-memory-stats — summary of the local memory DB.
+// Usage:
+//   npx linksee-memory-stats
+//   npx linksee-memory-stats --json
+//   npx linksee-memory-stats --per-entity 10
+//
+// Safe to run anytime (read-only).
+import { statSync } from 'node:fs';
+import { openDb, getDbPath } from '../db/migrate.js';
+function parseArgs() {
+    const argv = process.argv.slice(2);
+    const a = { json: false, perEntity: 5, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const v = argv[i];
+        if (v === '--json')
+            a.json = true;
+        else if (v === '--per-entity')
+            a.perEntity = Math.max(0, Number(argv[++i] || 5));
+        else if (v === '-h' || v === '--help')
+            a.help = true;
+    }
+    return a;
+}
+function humanBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(2)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+function humanDate(unix) {
+    if (!unix)
+        return '-';
+    return new Date(unix * 1000).toISOString().slice(0, 16).replace('T', ' ');
+}
+function humanAge(unix) {
+    if (!unix)
+        return '-';
+    const diff = Math.floor(Date.now() / 1000) - unix;
+    if (diff < 60)
+        return 'just now';
+    if (diff < 3600)
+        return `${Math.floor(diff / 60)}m ago`;
+    if (diff < 86400)
+        return `${Math.floor(diff / 3600)}h ago`;
+    if (diff < 86400 * 30)
+        return `${Math.floor(diff / 86400)}d ago`;
+    return `${Math.floor(diff / 86400 / 30)}mo ago`;
+}
+function main() {
+    const args = parseArgs();
+    if (args.help) {
+        console.log(`linksee-memory-stats — summary of the local memory DB
+
+  --json             Output machine-readable JSON
+  --per-entity N     Show top N entities (default 5, 0 to skip)
+  -h, --help         This message
+`);
+        return;
+    }
+    const dbPath = getDbPath();
+    let sizeBytes = 0;
+    try {
+        sizeBytes = statSync(dbPath).size;
+    }
+    catch { /* no db yet */ }
+    const db = openDb();
+    const counts = {
+        entities: db.prepare('SELECT COUNT(*) as c FROM entities').get().c,
+        memories: db.prepare('SELECT COUNT(*) as c FROM memories').get().c,
+        file_edits: db.prepare('SELECT COUNT(*) as c FROM session_file_edits').get().c,
+        unique_files: db.prepare('SELECT COUNT(DISTINCT file_path) as c FROM session_file_edits').get().c,
+        sessions_seen: db.prepare('SELECT COUNT(DISTINCT session_id) as c FROM session_file_edits').get().c,
+        consolidations: db.prepare('SELECT COUNT(*) as c FROM consolidations').get().c,
+        events: db.prepare('SELECT COUNT(*) as c FROM events').get().c,
+    };
+    const layerBreakdown = db
+        .prepare("SELECT layer, COUNT(*) as c FROM memories GROUP BY layer ORDER BY c DESC")
+        .all();
+    const entityKinds = db
+        .prepare("SELECT kind, COUNT(*) as c FROM entities GROUP BY kind ORDER BY c DESC")
+        .all();
+    const pinned = db.prepare('SELECT COUNT(*) as c FROM memories WHERE importance >= 1.0').get().c;
+    const protectedCount = db.prepare('SELECT COUNT(*) as c FROM memories WHERE protected = 1').get().c;
+    const oldest = db.prepare('SELECT MIN(created_at) as t FROM memories').get().t;
+    const newest = db.prepare('SELECT MAX(created_at) as t FROM memories').get().t;
+    const topEntities = args.perEntity > 0
+        ? db.prepare(`
+        SELECT e.name, e.kind, e.momentum_score, COUNT(m.id) as memory_count,
+               MAX(m.last_accessed_at) as last_access
+        FROM entities e
+        LEFT JOIN memories m ON m.entity_id = e.id
+        GROUP BY e.id
+        ORDER BY memory_count DESC, e.momentum_score DESC
+        LIMIT ?
+      `).all(args.perEntity)
+        : [];
+    const topFiles = db.prepare(`
+    SELECT file_path, COUNT(*) as edits, COUNT(DISTINCT session_id) as in_sessions
+    FROM session_file_edits
+    WHERE operation IN ('edit', 'write')
+    GROUP BY file_path
+    ORDER BY edits DESC
+    LIMIT 5
+  `).all();
+    const result = {
+        db_path: dbPath,
+        db_size: sizeBytes,
+        db_size_human: humanBytes(sizeBytes),
+        counts,
+        pinned,
+        caveat_protected: protectedCount,
+        layer_breakdown: layerBreakdown,
+        entity_kinds: entityKinds,
+        date_range: {
+            oldest: oldest ? new Date(oldest * 1000).toISOString() : null,
+            newest: newest ? new Date(newest * 1000).toISOString() : null,
+        },
+        top_entities: topEntities.map((e) => ({
+            name: e.name,
+            kind: e.kind,
+            momentum: Number((e.momentum_score ?? 0).toFixed(2)),
+            memory_count: e.memory_count,
+            last_access: e.last_access ? new Date(e.last_access * 1000).toISOString() : null,
+        })),
+        top_files: topFiles.map((f) => ({
+            path: f.file_path,
+            edits: f.edits,
+            in_sessions: f.in_sessions,
+        })),
+    };
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        db.close();
+        return;
+    }
+    // Human-readable output
+    console.log('');
+    console.log('  linksee-memory — local brain status');
+    console.log('  ' + '═'.repeat(55));
+    console.log(`  DB:            ${dbPath}`);
+    console.log(`  Size:          ${humanBytes(sizeBytes)}`);
+    console.log(`  Oldest memory: ${humanAge(oldest)}`);
+    console.log(`  Newest memory: ${humanAge(newest)}`);
+    console.log('');
+    console.log('  Counts');
+    console.log(`    entities:       ${counts.entities}`);
+    console.log(`    memories:       ${counts.memories}  (${pinned} pinned, ${protectedCount} caveat-protected)`);
+    console.log(`    file edits:     ${counts.file_edits}  across ${counts.unique_files} unique files`);
+    console.log(`    sessions seen:  ${counts.sessions_seen}`);
+    console.log(`    consolidations: ${counts.consolidations}`);
+    console.log('');
+    if (layerBreakdown.length > 0) {
+        console.log('  Memories by layer');
+        for (const r of layerBreakdown) {
+            const bar = '█'.repeat(Math.min(40, Math.round((r.c / counts.memories) * 40)));
+            console.log(`    ${r.layer.padEnd(15)} ${String(r.c).padStart(5)}  ${bar}`);
+        }
+        console.log('');
+    }
+    if (entityKinds.length > 0) {
+        console.log('  Entities by kind');
+        for (const r of entityKinds) {
+            console.log(`    ${r.kind.padEnd(15)} ${r.c}`);
+        }
+        console.log('');
+    }
+    if (topEntities.length > 0) {
+        console.log(`  Top ${topEntities.length} entities by memory count`);
+        for (const e of topEntities) {
+            console.log(`    ${String(e.memory_count).padStart(4)}  ${e.name.padEnd(30)} [${e.kind}]  momentum ${Number(e.momentum_score ?? 0).toFixed(1)}  last ${humanAge(e.last_access)}`);
+        }
+        console.log('');
+    }
+    if (topFiles.length > 0) {
+        console.log('  Top 5 most-edited files');
+        for (const f of topFiles) {
+            const p = f.file_path || '';
+            const shortPath = p.length > 65 ? '…' + p.slice(-64) : p;
+            console.log(`    ${String(f.edits).padStart(4)} edits  ${shortPath}`);
+        }
+        console.log('');
+    }
+    console.log('  Run with --json for machine-readable output.');
+    console.log('');
+    db.close();
+}
+main();
+//# sourceMappingURL=stats.js.map

package/dist/db/migrate.js

@@ -20,10 +20,18 @@ export function runMigrations(db) {
     const __filename = fileURLToPath(import.meta.url);
     const schemaPath = join(dirname(__filename), 'schema.sql');
     const sql = readFileSync(schemaPath, 'utf8');
-    // v3 → v4: rebuild memories_fts with trigram tokenizer for JP/CJK support
-    const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
-    if (versionRow && Number(versionRow.value) < 4) {
-        // Drop old triggers + table; CREATE statements below will recreate them
+    // Safely read current schema version. On a fresh DB the meta table doesn't
+    // exist yet, which is fine — treat that as "version 0, full schema apply".
+    let currentVersion = 0;
+    const metaTable = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();
+    if (metaTable?.name) {
+        const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+        if (versionRow)
+            currentVersion = Number(versionRow.value) || 0;
+    }
+    // v3 → v4: rebuild memories_fts with trigram tokenizer for JP/CJK support.
+    // Only runs when upgrading an existing DB from schema v1-3.
+    if (currentVersion > 0 && currentVersion < 4) {
         db.exec(`
       DROP TRIGGER IF EXISTS trg_memories_fts_ai;
       DROP TRIGGER IF EXISTS trg_memories_fts_ad;
@@ -32,8 +40,7 @@ export function runMigrations(db) {
     `);
     }
     db.exec(sql);
-    // After v4 schema is applied, repopulate FTS index from existing memories
-    if (versionRow && Number(versionRow.value) < 4) {
+    if (currentVersion > 0 && currentVersion < 4) {
         db.exec(`INSERT INTO memories_fts(rowid, content) SELECT id, content FROM memories;`);
     }
 }

package/dist/mcp/server.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // linksee-memory MCP server (stdio transport).
-// 5 tools: remember / recall / forget / consolidate / read_smart
+// Tools: remember / recall / recall_file / update_memory / list_entities /
+//        forget / consolidate / read_smart
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -9,33 +10,62 @@ import { computeHeat } from '../lib/heat-index.js';
 import { decideForgetting } from '../lib/forgetting.js';
 import { refreshMomentumForEntity } from '../lib/momentum.js';
 import { consolidate as runConsolidate } from '../lib/consolidate.js';
+import { isPastedExternalContent } from '../lib/session-parser.js';
 import { handleReadSmart as handleReadSmartImpl } from './read-smart.js';
+const SERVER_VERSION = '0.1.0';
 const db = openDb();
 runMigrations(db);
-const server = new Server({ name: 'linksee-memory', version: '0.0.2' }, { capabilities: { tools: {} } });
+const server = new Server({ name: 'linksee-memory', version: SERVER_VERSION }, { capabilities: { tools: {} } });
+// ============================================================
+// Layer alias map — natural language → canonical layer
+// (agents can say layer="decisions" and we resolve to "learning")
+// ============================================================
+const LAYER_ALIASES = {
+    // canonical — identity
+    goal: 'goal', context: 'context', emotion: 'emotion',
+    implementation: 'implementation', caveat: 'caveat', learning: 'learning',
+    // natural-language aliases
+    why: 'goal', goals: 'goal', target: 'goal', targets: 'goal', intent: 'goal',
+    background: 'context', reason: 'context', situation: 'context', timing: 'context',
+    tone: 'emotion', feelings: 'emotion', mood: 'emotion',
+    impl: 'implementation', success: 'implementation', failure: 'implementation',
+    how: 'implementation', tried: 'implementation', attempts: 'implementation',
+    warning: 'caveat', warnings: 'caveat', pain: 'caveat', rule: 'caveat',
+    rules: 'caveat', pitfall: 'caveat', pitfalls: 'caveat', dont: 'caveat',
+    decision: 'learning', decisions: 'learning', learned: 'learning',
+    insight: 'learning', insights: 'learning', growth: 'learning',
+};
+function resolveLayer(input) {
+    if (!input)
+        return undefined;
+    const k = String(input).toLowerCase().trim();
+    return LAYER_ALIASES[k] ?? k;
+}
+const LAYER_ENUM = ['goal', 'context', 'emotion', 'implementation', 'caveat', 'learning'];
 // ============================================================
 // Tool schema declarations
 // ============================================================
 const TOOLS = [
     {
         name: 'remember',
-        description: 'Store a memory about an entity (person/company/project/concept/file) in one of 6 layers: goal (WHY), context (WHY-THIS-NOW), emotion (USER tone), implementation (HOW — success/failure), caveat (PAIN lesson, never forgotten), learning (GROWTH log). Use this when you discover non-obvious goals, unexpected failures, user preferences, or decisions worth preserving.',
+        description: 'Store a memory about an entity (person/company/project/concept/file) in one of 6 layers: goal (WHY), context (WHY-THIS-NOW), emotion (USER tone), implementation (HOW — success/failure), caveat (PAIN lesson, never forgotten), learning (GROWTH log). Use this when you discover non-obvious goals, unexpected failures, user preferences, or decisions worth preserving. Pasted assistant output or CI logs are rejected (use force=true only if you are sure).',
         inputSchema: {
             type: 'object',
             properties: {
                 entity_name: { type: 'string', description: 'Name of the entity this memory is about' },
                 entity_kind: { type: 'string', enum: ['person', 'company', 'project', 'concept', 'file', 'other'] },
                 entity_key: { type: 'string', description: 'Optional canonical key (email, domain, file path)' },
-                layer: { type: 'string', enum: ['goal', 'context', 'emotion', 'implementation', 'caveat', 'learning'] },
+                layer: { type: 'string', description: 'One of: goal / context / emotion / implementation / caveat / learning. Common aliases (why, decisions, warnings, how, ...) are accepted.' },
                 content: { type: 'string', description: 'The memory content (plain text or JSON)' },
-                importance: { type: 'number', minimum: 0, maximum: 1 },
+                importance: { type: 'number', minimum: 0, maximum: 1, description: '0.0-1.0. Use 1.0 to "pin" a memory (protects from forgetting even outside caveat layer).' },
+                force: { type: 'boolean', default: false, description: 'Bypass the paste-back/CI-log quality check. Only set when you are sure the content is original user or agent thought.' },
             },
             required: ['entity_name', 'entity_kind', 'layer', 'content'],
         },
     },
     {
         name: 'recall',
-        description: 'Retrieve memories relevant to the current context using full-text search (BM25), re-ranked by a composite score of semantic_relevance * heat_score * momentum. Returns only what fits in the token budget. Use at the start of a task to check existing context about the entities involved.',
+        description: 'Retrieve memories relevant to the current context using full-text search (BM25) + entity-name match, re-ranked by a composite score (relevance × heat × momentum × importance). Returns only what fits in the token budget, with match_reasons explaining WHY each memory was returned. Opportunistically refreshes stale momentum scores for entities in the result set. Supports pagination via offset/has_more. Layer aliases accepted. Use at the start of any task that might involve prior work.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -43,32 +73,64 @@ const TOOLS = [
                 entity_name: { type: 'string', description: 'Optional — narrow to a specific entity' },
                 layer: {
                     type: 'string',
-                    enum: ['goal', 'context', 'emotion', 'implementation', 'caveat', 'learning'],
+                    description: 'Optional layer filter. Accepts aliases (decisions/warnings/how/etc.) as well as canonical names.',
                 },
-                max_tokens: { type: 'number', description: 'Approx token budget. Default 2000.', default: 2000 },
+                band: { type: 'string', enum: ['hot', 'warm', 'cold', 'frozen'], description: 'Optional — only return memories whose heat_band matches.' },
+                max_tokens: { type: 'number', description: 'Approx token budget. Default 2000. Either max_tokens or limit stops iteration (whichever fires first).', default: 2000 },
+                limit: { type: 'number', description: 'Optional hard cap on number of memories. Stops at min(max_tokens-budget, limit).' },
+                offset: { type: 'number', description: 'Skip this many top results (pagination). Use has_more from prior response to decide next offset.', default: 0 },
+                mark_accessed: { type: 'boolean', default: true, description: 'Set false for preview / listing queries that should not bump heat.' },
             },
             required: ['query'],
         },
     },
+    {
+        name: 'update_memory',
+        description: 'Atomically edit an existing memory in-place. Preferred over forget+remember because it preserves memory_id, which matters for session_file_edits links and referential integrity. Use to correct facts, update deadlines in goal entries, refine caveats, or re-score importance. Caveat-layer memories can be updated but cannot have their protected flag removed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                memory_id: { type: 'number', description: 'The memory.id to update' },
+                content: { type: 'string', description: 'New content (plain text or JSON). If omitted, content is kept.' },
+                layer: { type: 'string', description: 'Move to a different layer (aliases accepted). If omitted, layer is kept.' },
+                importance: { type: 'number', minimum: 0, maximum: 1, description: 'New importance 0-1. Set to 1.0 to pin.' },
+            },
+            required: ['memory_id'],
+        },
+    },
+    {
+        name: 'list_entities',
+        description: 'List the entities currently known to this memory store, sorted by recent activity. Use at the start of a new session ("what do I know about?") before issuing specific recall queries. Cheaper than recall for the "give me an overview" question.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['person', 'company', 'project', 'concept', 'file', 'other'], description: 'Filter by entity kind.' },
+                min_memories: { type: 'number', description: 'Only include entities with at least N memories. Default 1.', default: 1 },
+                limit: { type: 'number', description: 'Max entities to return. Default 30.', default: 30 },
+                offset: { type: 'number', default: 0 },
+            },
+        },
+    },
     {
         name: 'forget',
-        description: 'Explicitly delete a memory by id, OR run auto-forgetting across all memories based on forgettingRisk (importance + heat + age). Caveat and goal layer are always preserved.',
+        description: 'Explicitly delete a memory by id, OR run auto-forgetting across all memories based on forgettingRisk (importance + heat + age). Caveat-layer, goal-layer, and importance=1.0 (pinned) memories are always preserved. Prefer update_memory for corrections — forget is destructive.',
         inputSchema: {
             type: 'object',
             properties: {
                 memory_id: { type: 'number' },
-                dry_run: { type: 'boolean', default: false },
+                dry_run: { type: 'boolean', default: false, description: 'Report what would be deleted without actually deleting.' },
             },
         },
     },
     {
         name: 'consolidate',
-        description: 'Sleep-mode compression. Clusters cold low-importance memories by (entity, layer), summarizes each cluster into a single protected learning-layer entry, deletes originals, and runs a forget-sweep. Run at session end or on demand. Returns a summary of what was compressed.',
+        description: 'Sleep-mode compression. Clusters cold low-importance memories by (entity, layer), summarizes each cluster into a single protected learning-layer entry, deletes originals, and runs a forget-sweep. Run at session end or on demand. Set dry_run=true to preview without writing.',
         inputSchema: {
             type: 'object',
             properties: {
                 scope: { type: 'string', enum: ['all', 'session'], default: 'session' },
                 min_age_days: { type: 'number', description: 'Override the default 7-day minimum age for clustering (set to 0 to consolidate everything immediately, useful right after a bulk import).', default: 7 },
+                dry_run: { type: 'boolean', default: false, description: 'Preview what would be compressed without modifying the DB.' },
             },
         },
     },
@@ -121,19 +183,37 @@ function upsertEntity(args) {
     return Number(result.lastInsertRowid);
 }
 function handleRemember(args) {
+    // Layer alias → canonical
+    const layer = resolveLayer(args.layer);
+    if (!layer || !LAYER_ENUM.includes(layer)) {
+        return JSON.stringify({
+            ok: false,
+            error: `unknown layer "${args.layer}". Known: ${LAYER_ENUM.join(', ')} (aliases: decisions, warnings, how, why, ...)`,
+        });
+    }
+    // Quality check — reject pasted external content unless force=true
+    const rawContent = String(args.content ?? '');
+    if (!args.force && isPastedExternalContent(rawContent)) {
+        return JSON.stringify({
+            ok: false,
+            rejected: 'quality_check',
+            reason: 'Content looks like pasted assistant output, CI log, or external paste. Pass force:true if this really is original thought worth keeping.',
+            hint: 'If you meant to save an extracted insight from that paste, summarize it in your own words first.',
+        });
+    }
     const entityId = upsertEntity({ name: args.entity_name, kind: args.entity_kind, key: args.entity_key });
-    const importance = args.importance ?? 0.5;
+    const importance = Math.min(1, Math.max(0, Number(args.importance ?? 0.5)));
     const result = db
-        .prepare('INSERT INTO memories (entity_id, layer, content, importance) VALUES (?, ?, ?, ?)')
-        .run(entityId, args.layer, args.content, importance);
-    db.prepare('INSERT INTO events (entity_id, kind, payload) VALUES (?, ?, ?)').run(entityId, 'memory_stored', JSON.stringify({ layer: args.layer, memory_id: result.lastInsertRowid }));
-    // Refresh momentum — Day 2 addition. Cheap per-call since it's one entity.
+        .prepare('INSERT INTO memories (entity_id, layer, content, importance, protected) VALUES (?, ?, ?, ?, ?)')
+        .run(entityId, layer, rawContent, importance, importance >= 1.0 ? 1 : 0);
+    db.prepare('INSERT INTO events (entity_id, kind, payload) VALUES (?, ?, ?)').run(entityId, 'memory_stored', JSON.stringify({ layer, memory_id: result.lastInsertRowid }));
     const mom = refreshMomentumForEntity(db, entityId);
     return JSON.stringify({
         ok: true,
         memory_id: Number(result.lastInsertRowid),
         entity_id: entityId,
-        layer: args.layer,
+        layer,
+        pinned: importance >= 1.0,
         momentum: { score: mom.score, band: mom.band },
     });
 }
@@ -197,28 +277,58 @@ function runLikeQuery(query, entityName, layer, limit) {
     params.push(limit);
     return db.prepare(sql).all(...params);
 }
+// Opportunistically refresh momentum_score cache for entities in a result set.
+// Momentum is computed from events but stored in the entities row; without this,
+// a row can become stale (e.g. no new remember() for weeks while events decay).
+// Only refreshes entries older than MOMENTUM_STALE_SECS to avoid per-call cost.
+const MOMENTUM_STALE_SECS = 3600; // 1 hour
+function refreshStaleMomentum(entityIds) {
+    if (entityIds.length === 0)
+        return;
+    const unique = Array.from(new Set(entityIds));
+    const now = Math.floor(Date.now() / 1000);
+    const cutoff = now - MOMENTUM_STALE_SECS;
+    const placeholders = unique.map(() => '?').join(',');
+    const rows = db
+        .prepare(`SELECT id FROM entities WHERE id IN (${placeholders}) AND (momentum_at IS NULL OR momentum_at < ?)`)
+        .all(...unique, cutoff);
+    for (const r of rows) {
+        try {
+            refreshMomentumForEntity(db, r.id);
+        }
+        catch { /* non-fatal */ }
+    }
+}
 function handleRecall(args) {
-    const maxTokens = args.max_tokens ?? 2000;
+    const maxTokens = Math.max(100, Number(args.max_tokens ?? 2000));
     const approxTokensPerMemory = 100;
-    const limit = Math.max(1, Math.floor(maxTokens / approxTokensPerMemory));
-    const fetchLimit = limit * 2; // extra for composite re-rank
+    const tokenBudgetLimit = Math.max(1, Math.floor(maxTokens / approxTokensPerMemory));
+    const hardLimit = Number.isFinite(args.limit) ? Math.max(1, Math.min(200, args.limit)) : tokenBudgetLimit;
+    const returnLimit = Math.min(tokenBudgetLimit, hardLimit);
+    const offset = Math.max(0, Number(args.offset ?? 0));
+    const markAccessed = args.mark_accessed !== false;
+    const layer = resolveLayer(args.layer);
+    const band = args.band;
+    // Fetch extra rows for composite re-rank, pagination, and band filtering
+    const fetchLimit = Math.max(returnLimit * 3, 30) + offset;
     let rows = [];
     let searchMethod = 'like';
     const ftsQuery = toFtsQuery(args.query ?? '');
     const canUseFts = !!ftsQuery && !args.entity_name;
     if (canUseFts) {
-        // 1st pass: FTS5 over content
-        const ftsRows = runFtsQuery(ftsQuery, args.layer, fetchLimit);
-        // 2nd pass: entity-name LIKE — catches queries that ARE entity names
-        //   (FTS only indexes memory content, not entity names)
-        const likeRows = runLikeQuery(args.query, undefined, args.layer, fetchLimit);
-        // merge, dedup by memory id (prefer the FTS row for its bm25_score)
+        const ftsRows = runFtsQuery(ftsQuery, layer, fetchLimit);
+        const likeRows = runLikeQuery(args.query, undefined, layer, fetchLimit);
         const seen = new Map();
         for (const r of ftsRows)
-            seen.set(r.id, r);
-        for (const r of likeRows)
-            if (!seen.has(r.id))
-                seen.set(r.id, r);
+            seen.set(r.id, { ...r, _via: 'fts' });
+        for (const r of likeRows) {
+            if (seen.has(r.id)) {
+                seen.get(r.id)._via = 'fts+like'; // both matched
+            }
+            else {
+                seen.set(r.id, { ...r, _via: 'like' });
+            }
+        }
         rows = Array.from(seen.values());
         if (ftsRows.length > 0 && likeRows.length > 0)
             searchMethod = 'fts5+like';
@@ -228,13 +338,22 @@ function handleRecall(args) {
             searchMethod = 'like';
     }
     else {
-        rows = runLikeQuery(args.query, args.entity_name, args.layer, fetchLimit);
+        rows = runLikeQuery(args.query, args.entity_name, layer, fetchLimit).map((r) => ({ ...r, _via: 'like' }));
         searchMethod = 'like';
     }
     const useFts = searchMethod !== 'like';
     const now = Math.floor(Date.now() / 1000);
-    // Composite score: 0.5 * relevance + 0.3 * heat + 0.2 * momentum
-    // relevance: if FTS used, normalize bm25 (lower = better → invert). Otherwise 0.5 baseline.
+    // Opportunistically refresh momentum for entities about to be surfaced
+    refreshStaleMomentum(rows.map((r) => r.entity_id));
+    // Re-fetch momentum after refresh (cheap single-pass update)
+    if (rows.length > 0) {
+        const ids = Array.from(new Set(rows.map((r) => r.entity_id)));
+        const ph = ids.map(() => '?').join(',');
+        const fresh = db.prepare(`SELECT id, momentum_score FROM entities WHERE id IN (${ph})`).all(...ids);
+        const byId = new Map(fresh.map((f) => [f.id, f.momentum_score]));
+        for (const r of rows)
+            r.momentum_score = byId.get(r.entity_id) ?? r.momentum_score;
+    }
     const bm25Values = rows.map((r) => r.bm25_score);
     const minBm = Math.min(...bm25Values, 0);
     const maxBm = Math.max(...bm25Values, 1);
@@ -248,53 +367,133 @@ function handleRecall(args) {
             totalAccesses: r.access_count,
             baseImportance: r.importance,
         });
-        // Normalize BM25: lower = more relevant. Map to 0..1 (1 = most relevant).
-        const relevance = useFts ? 1 - (r.bm25_score - minBm) / bmSpan : 0.5;
+        // Individual weight contributions (for transparency)
+        const relevance = useFts && r._via !== 'like' ? 1 - (r.bm25_score - minBm) / bmSpan : 0.5;
         const heatNorm = heat.score / 100;
         const momNorm = Math.min(1, (r.momentum_score ?? 0) / 10);
-        const composite = 0.5 * relevance + 0.3 * heatNorm + 0.2 * momNorm;
+        const importanceBoost = r.importance; // 0-1
+        // Composite: give a bit to importance so pinned (1.0) memories always rank high
+        const w_rel = 0.45, w_heat = 0.25, w_mom = 0.15, w_imp = 0.15;
+        const composite = w_rel * relevance + w_heat * heatNorm + w_mom * momNorm + w_imp * importanceBoost;
+        // match_reasons: human-readable WHY this row is here
+        const reasons = [];
+        if (r._via === 'fts' || r._via === 'fts+like')
+            reasons.push(`content_match_${r._via === 'fts+like' ? 'dual' : 'fts'}`);
+        if (r._via === 'like' || r._via === 'fts+like') {
+            if (args.entity_name || (args.query && String(r.entity_name || '').toLowerCase().includes(String(args.query).toLowerCase()))) {
+                reasons.push('entity_name_match');
+            }
+            else {
+                reasons.push('content_substring');
+            }
+        }
+        if (heat.band === 'hot')
+            reasons.push('heat:hot');
+        else if (heat.band === 'warm')
+            reasons.push('heat:warm');
+        if (r.momentum_score >= 5)
+            reasons.push('entity_active');
+        if (r.importance >= 1.0)
+            reasons.push('pinned');
+        else if (r.importance >= 0.8)
+            reasons.push('high_importance');
+        if (r.protected === 1 && r.layer === 'caveat')
+            reasons.push('caveat_protected');
         return {
             ...r,
             heat_score: heat.score,
             heat_band: heat.band,
             composite_score: composite,
             relevance_score: relevance,
+            _reasons: reasons,
+            _breakdown: {
+                relevance: Number(relevance.toFixed(3)),
+                heat: Number(heatNorm.toFixed(3)),
+                momentum: Number(momNorm.toFixed(3)),
+                importance: Number(importanceBoost.toFixed(3)),
+            },
         };
     });
-    scored.sort((a, b) => b.composite_score - a.composite_score);
-    const top = scored.slice(0, limit);
-    // Mark accessed
-    if (top.length > 0) {
-        const markAccessed = db.prepare('UPDATE memories SET last_accessed_at = ?, access_count = access_count + 1 WHERE id = ?');
-        const tx = db.transaction((ids) => {
-            for (const id of ids)
-                markAccessed.run(now, id);
-        });
-        tx(top.map((r) => r.id));
+    // Apply band filter AFTER scoring (needs heat.band)
+    const filtered = band ? scored.filter((s) => s.heat_band === band) : scored;
+    // Sort by composite
+    filtered.sort((a, b) => b.composite_score - a.composite_score);
+    // Pagination: skip offset, take returnLimit
+    const total = filtered.length;
+    const windowed = filtered.slice(offset, offset + returnLimit);
+    const hasMore = total > offset + windowed.length;
+    // Mark accessed (only for the returned window, and only if asked)
+    if (markAccessed && windowed.length > 0) {
+        const mark = db.prepare('UPDATE memories SET last_accessed_at = ?, access_count = access_count + 1 WHERE id = ?');
+        const tx = db.transaction((ids) => { for (const id of ids)
+            mark.run(now, id); });
+        tx(windowed.map((r) => r.id));
+    }
+    // Determine what stopped iteration — max_tokens vs limit vs offset+n=total
+    let stoppedBy = 'end';
+    if (windowed.length === returnLimit && total > offset + returnLimit) {
+        stoppedBy = hardLimit <= tokenBudgetLimit ? 'limit' : 'tokens';
     }
     return JSON.stringify({
         ok: true,
-        count: top.length,
+        count: windowed.length,
+        total_candidates: total,
+        offset,
+        has_more: hasMore,
+        stopped_by: stoppedBy,
         search: searchMethod,
-        memories: top.map((r) => ({
-            id: r.id,
-            entity: { name: r.entity_name, kind: r.entity_kind, momentum: r.momentum_score },
-            layer: r.layer,
-            content: r.content,
-            importance: r.importance,
-            heat: Number(r.heat_score.toFixed(1)),
-            band: r.heat_band,
-            composite: Number(r.composite_score.toFixed(3)),
-        })),
+        resolved_layer: layer ?? null,
+        memories: windowed.map((r) => {
+            let parsedContent = r.content;
+            try {
+                parsedContent = JSON.parse(r.content);
+            }
+            catch { /* leave as string */ }
+            return {
+                id: r.id,
+                entity: {
+                    id: r.entity_id,
+                    name: r.entity_name,
+                    kind: r.entity_kind,
+                    momentum: Number((r.momentum_score ?? 0).toFixed(2)),
+                },
+                layer: r.layer,
+                content: parsedContent,
+                content_raw: r.content,
+                importance: r.importance,
+                pinned: r.importance >= 1.0,
+                heat: Number(r.heat_score.toFixed(1)),
+                band: r.heat_band,
+                composite: Number(r.composite_score.toFixed(3)),
+                match_reasons: r._reasons,
+                score_breakdown: r._breakdown,
+            };
+        }),
     });
 }
 function handleForget(args) {
     if (args.memory_id) {
-        const res = db.prepare('DELETE FROM memories WHERE id = ? AND protected = 0').run(args.memory_id);
-        return JSON.stringify({ ok: true, deleted: res.changes });
+        // Explicit delete by id — respect protected AND pinned (importance >= 1.0)
+        const target = db.prepare('SELECT id, layer, importance, protected FROM memories WHERE id = ?').get(args.memory_id);
+        if (!target) {
+            return JSON.stringify({ ok: false, error: `memory_id ${args.memory_id} not found` });
+        }
+        if (target.protected === 1 || target.importance >= 1.0) {
+            return JSON.stringify({
+                ok: false,
+                preserved: true,
+                reason: target.protected === 1 ? `${target.layer}-layer is auto-protected` : 'pinned (importance=1.0)',
+                hint: 'Use update_memory to lower importance below 1.0 first, then forget.',
+            });
+        }
+        const res = db.prepare('DELETE FROM memories WHERE id = ?').run(args.memory_id);
+        return JSON.stringify({ ok: true, deleted: res.changes, memory_id: args.memory_id });
     }
+    // Auto-sweep — also respect importance=1.0 as protection
     const rows = db
-        .prepare(`SELECT id, layer, importance, access_count, last_accessed_at, protected FROM memories WHERE protected = 0`)
+        .prepare(`SELECT id, layer, importance, access_count, last_accessed_at, protected
+              FROM memories
+              WHERE protected = 0 AND importance < 1.0`)
         .all();
     const now = Math.floor(Date.now() / 1000);
     const actions = [];
@@ -317,30 +516,168 @@ function handleForget(args) {
         if (action !== 'keep')
             actions.push({ id: r.id, action });
     }
+    const toDropIds = actions.filter((a) => a.action === 'drop').map((a) => a.id);
     if (!args.dry_run) {
         const del = db.prepare('DELETE FROM memories WHERE id = ?');
-        const tx = db.transaction((items) => {
-            for (const a of items)
-                if (a.action === 'drop')
-                    del.run(a.id);
-        });
-        tx(actions);
+        const tx = db.transaction((ids) => { for (const id of ids)
+            del.run(id); });
+        tx(toDropIds);
     }
     return JSON.stringify({
         ok: true,
         dry_run: !!args.dry_run,
         scanned: rows.length,
-        to_drop: actions.filter((a) => a.action === 'drop').length,
+        to_drop: toDropIds.length,
         to_compress: actions.filter((a) => a.action === 'compress').length,
+        sample_ids_to_drop: toDropIds.slice(0, 10),
     });
 }
 function handleConsolidate(args) {
+    const dryRun = !!args?.dry_run;
+    if (dryRun) {
+        // Preview: simulate by running against a transaction we roll back
+        // We don't have a clean "preview" path in lib/consolidate, so do a best-effort
+        // read-only audit: count candidates using the same rules.
+        const now = Math.floor(Date.now() / 1000);
+        const ageCutoff = now - (args.min_age_days ?? 7) * 86400;
+        const candidates = db.prepare(`
+      SELECT m.entity_id, e.name as entity_name, m.layer, COUNT(*) as c
+      FROM memories m
+      JOIN entities e ON e.id = m.entity_id
+      WHERE m.protected = 0
+        AND m.importance < 1.0
+        AND m.layer IN ('context', 'emotion', 'implementation')
+        AND m.created_at <= ?
+      GROUP BY m.entity_id, m.layer
+      HAVING c >= 2
+      ORDER BY c DESC
+    `).all(ageCutoff);
+        const totalReplaced = candidates.reduce((s, c) => s + c.c, 0);
+        return JSON.stringify({
+            ok: true,
+            dry_run: true,
+            clusters: candidates.length,
+            memories_replaced_if_run: totalReplaced,
+            preview: candidates.slice(0, 20).map((c) => ({
+                entity: c.entity_name,
+                layer: c.layer,
+                count: c.c,
+            })),
+            hint: 'Set dry_run=false to actually consolidate.',
+        });
+    }
     const result = runConsolidate(db, {
         scope: args?.scope ?? 'session',
         min_age_days: typeof args?.min_age_days === 'number' ? args.min_age_days : undefined,
     });
     return JSON.stringify({ ok: true, ...result });
 }
+function handleUpdateMemory(args) {
+    const memoryId = Number(args.memory_id);
+    if (!Number.isFinite(memoryId)) {
+        return JSON.stringify({ ok: false, error: 'memory_id (number) required' });
+    }
+    const existing = db.prepare('SELECT id, entity_id, layer, content, importance, protected FROM memories WHERE id = ?').get(memoryId);
+    if (!existing) {
+        return JSON.stringify({ ok: false, error: `memory_id ${memoryId} not found` });
+    }
+    const patch = {};
+    if (typeof args.content === 'string')
+        patch.content = args.content;
+    if (typeof args.layer === 'string') {
+        const resolved = resolveLayer(args.layer);
+        if (!resolved || !LAYER_ENUM.includes(resolved)) {
+            return JSON.stringify({ ok: false, error: `unknown layer "${args.layer}"` });
+        }
+        // Cannot demote a caveat out of caveat (caveat is auto-protected by trigger)
+        if (existing.layer === 'caveat' && resolved !== 'caveat' && existing.protected === 1) {
+            return JSON.stringify({
+                ok: false,
+                error: 'Cannot move a protected caveat memory to another layer. Create a new memory in the target layer instead.',
+            });
+        }
+        patch.layer = resolved;
+    }
+    if (args.importance !== undefined) {
+        const imp = Math.min(1, Math.max(0, Number(args.importance)));
+        patch.importance = imp;
+        patch.protected = imp >= 1.0 || existing.protected === 1 ? 1 : 0;
+    }
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+        return JSON.stringify({ ok: false, error: 'no fields to update (provide content, layer, or importance)' });
+    }
+    const setClause = keys.map((k) => `${k} = ?`).join(', ');
+    const values = keys.map((k) => patch[k]);
+    db.prepare(`UPDATE memories SET ${setClause} WHERE id = ?`).run(...values, memoryId);
+    // Record the update as an event for audit trail
+    db.prepare('INSERT INTO events (entity_id, kind, payload) VALUES (?, ?, ?)').run(existing.entity_id, 'memory_updated', JSON.stringify({ memory_id: memoryId, changed: keys }));
+    return JSON.stringify({
+        ok: true,
+        memory_id: memoryId,
+        updated_fields: keys,
+        pinned: (patch.importance ?? existing.importance) >= 1.0,
+    });
+}
+function handleListEntities(args) {
+    const kind = args?.kind;
+    const minMemories = Math.max(1, Number(args?.min_memories ?? 1));
+    const limit = Math.max(1, Math.min(200, Number(args?.limit ?? 30)));
+    const offset = Math.max(0, Number(args?.offset ?? 0));
+    let sql = `
+    SELECT e.id, e.name, e.kind, e.canonical_key, e.momentum_score,
+           e.updated_at, e.created_at,
+           COUNT(m.id) as memory_count,
+           MAX(m.last_accessed_at) as last_memory_access,
+           SUM(CASE WHEN m.layer = 'goal' THEN 1 ELSE 0 END) as goal_count,
+           SUM(CASE WHEN m.layer = 'caveat' THEN 1 ELSE 0 END) as caveat_count,
+           SUM(CASE WHEN m.layer = 'learning' THEN 1 ELSE 0 END) as learning_count,
+           SUM(CASE WHEN m.layer = 'implementation' THEN 1 ELSE 0 END) as impl_count,
+           SUM(CASE WHEN m.importance >= 1.0 THEN 1 ELSE 0 END) as pinned_count
+    FROM entities e
+    LEFT JOIN memories m ON m.entity_id = e.id
+    WHERE 1=1
+  `;
+    const params = [];
+    if (kind) {
+        sql += ' AND e.kind = ?';
+        params.push(kind);
+    }
+    sql += ' GROUP BY e.id';
+    if (minMemories > 1)
+        sql += ' HAVING memory_count >= ?';
+    if (minMemories > 1)
+        params.push(minMemories);
+    // Sort: active (high momentum) first, then most memories, then most recent
+    sql += ' ORDER BY (COALESCE(e.momentum_score,0) * 10 + memory_count * 0.5 + (last_memory_access / 86400.0 / 365) * 2) DESC';
+    sql += ' LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+    const rows = db.prepare(sql).all(...params);
+    const totalRow = db.prepare(kind ? 'SELECT COUNT(*) as c FROM entities WHERE kind = ?' : 'SELECT COUNT(*) as c FROM entities').get(...(kind ? [kind] : []));
+    return JSON.stringify({
+        ok: true,
+        total: totalRow.c,
+        returned: rows.length,
+        offset,
+        has_more: offset + rows.length < totalRow.c,
+        entities: rows.map((r) => ({
+            id: r.id,
+            name: r.name,
+            kind: r.kind,
+            canonical_key: r.canonical_key,
+            momentum: Number((r.momentum_score ?? 0).toFixed(2)),
+            memory_count: r.memory_count,
+            last_memory_access: r.last_memory_access ? new Date(r.last_memory_access * 1000).toISOString() : null,
+            layer_breakdown: {
+                goal: r.goal_count,
+                caveat: r.caveat_count,
+                learning: r.learning_count,
+                implementation: r.impl_count,
+            },
+            pinned_count: r.pinned_count,
+        })),
+    });
+}
 function handleRecallFile(args) {
     const sub = String(args.path_substring ?? '').trim();
     if (!sub)
@@ -420,6 +757,12 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             case 'recall':
                 text = handleRecall(args);
                 break;
+            case 'update_memory':
+                text = handleUpdateMemory(args);
+                break;
+            case 'list_entities':
+                text = handleListEntities(args);
+                break;
             case 'forget':
                 text = handleForget(args);
                 break;
@@ -445,5 +788,5 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-process.stderr.write('[linksee-memory] MCP server ready on stdio (v0.0.2)\n');
+process.stderr.write(`[linksee-memory] MCP server ready on stdio (v${SERVER_VERSION})\n`);
 //# sourceMappingURL=server.js.map

package/dist/skill/SKILL.md

@@ -43,6 +43,27 @@ Claude Code は session が終わると全部忘れる。Michieさんが昨日
 
 **重要:** `caveat` は自動で忘却保護される。痛みの記録は絶対消えない。
 
+**v0.1.0: 別のpin方法** — `importance: 1.0` で remember すれば、caveat層じゃなくても auto-forget から保護される。「絶対忘れさせたくない goal」「重要な判断」等で使う:
+
+```
+remember({
+  entity_name: "KanseiLink", entity_kind: "project",
+  layer: "goal", content: "Plugin Marketplace 申請中",
+  importance: 1.0  // pin
+})
+```
+
+**Layer alias 対応** — canonical layer 名覚えなくても、自然な言い方で呼べる:
+
+| 自然語 | → canonical |
+|---|---|
+| `decisions` / `insights` / `learned` | `learning` |
+| `warnings` / `rules` / `pitfalls` / `dont` | `caveat` |
+| `how` / `tried` / `attempts` / `success` / `failure` | `implementation` |
+| `why` / `intent` / `goals` / `targets` | `goal` |
+| `background` / `reason` / `situation` / `timing` | `context` |
+| `tone` / `feelings` / `mood` | `emotion` |
+
 ---
 
 ## 🔄 実行フロー（5つのタイミング）
@@ -51,6 +72,18 @@ Claude Code は session が終わると全部忘れる。Michieさんが昨日
 
 新しい作業を始める**前**に、過去のコンテキストを注入する。
 
+**v0.1.0 新フロー: 超-セッション冒頭は `list_entities` から**
+
+会話の一番最初（ユーザーが最初の発話をしてきた時点）で、「自分が何を知ってるか」を把握する:
+
+```
+mcp__linksee__list_entities({ min_memories: 5, limit: 10 })
+```
+
+これで返ってくる "momentum 高い entity" = 今まさに話題に上りそうなプロジェクト。各entityの `layer_breakdown` を見れば「このprojectはcaveatが多い」「goalが未完」等が分かる。
+
+その後、具体的な作業が始まったら recall:
+
 ```
 mcp__linksee__recall({
   query: "<現タスクのキーワード。プロジェクト名 + 技術名>",
@@ -106,6 +139,20 @@ mcp__linksee__read_smart({
 
 特に大きなファイル（1000行超えるもの）で効果絶大。
 
+### ③.5 Updating existing memory — v0.1.0 新: forget+remember の代わりに update_memory
+
+事実が変わった / 目標が更新された / caveat の細部を修正したい場合、**forget して remember すると memory_id が変わって session_file_edits のリンクが切れる**。代わりに `update_memory`:
+
+```
+update_memory({
+  memory_id: 1234,
+  content: '{"primary": "Plugin Marketplace 申請中(審査7日目)", "deadline": "2026-04-25"}',
+  importance: 1.0  // pin 強化
+})
+```
+
+`layer` も変更可能だが、caveat → 他への demotion は不可(auto-protectedのため)。
+
 ### ④ Failure — エラー発生時に caveat 記録
 
 エラー・失敗・「うまくいかない」が発生した瞬間、すぐ記録する：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "mcpName": "io.github.michielinksee/linksee-memory",
   "description": "Local-first agent memory MCP — cross-agent brain with 6-layer structured memory + token-saving file diff cache",
   "type": "module",
@@ -8,7 +8,8 @@
     "linksee-memory": "./dist/mcp/server.js",
     "linksee-memory-import": "./dist/bin/import-sessions.js",
     "linksee-memory-sync": "./dist/bin/sync-session.js",
-    "linksee-memory-install-skill": "./dist/bin/install-skill.js"
+    "linksee-memory-install-skill": "./dist/bin/install-skill.js",
+    "linksee-memory-stats": "./dist/bin/stats.js"
   },
   "main": "./dist/mcp/server.js",
   "files": [