linksee-memory 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+> Local-first agent memory MCP. A cross-agent brain for **Claude Code, Cursor, OpenAI Codex, and Gemini CLI** — with a token-saving file diff cache that nobody else does. One SQLite file, all your LLMs read the same memory.
 >
 > **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).
 
@@ -9,7 +9,17 @@
 [![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)
+🌐 **Landing page**: [linksee-site.vercel.app](https://linksee-site.vercel.app) (includes non-developer onboarding for Claude Desktop / Cursor / Claude Code / OpenAI Codex / Gemini CLI)
+
+## 📣 As featured on
+
+- **Zenn**: [あなたの Claude Code、 実は前回のセッションを完全に忘れている](https://zenn.dev/kanseilink/articles/linksee-memory-claude-code-recall-20260508) — 73 ♡ on Zenn, **165+ users on Hatena Bookmark**, picked up by tech blogs + YouTube shorts (May 2026)
+- **Zenn**: [あなたの MCP server、 実は Tools しか使ってない (5 blocks 全実装 / v0.3.0)](https://zenn.dev/kanseilink/articles/linksee-memory-mcp-five-blocks-20260507) — the 1% of MCP servers that implement all 5 blocks
+- **Zenn**: [あなたの Claude memory、 実は Claude にしか残らない (5 LLM 横断する方法)](https://zenn.dev/kanseilink/articles/linksee-memory-claude-cross-llm-20260511) — cross-LLM memory pattern (May 12, 2026)
+- **Zenn**: [Glama listing で 3 週間止まった話 (5 つの罠と解決策)](https://zenn.dev/michielinksee/articles/linksee-memory-mcp-publish-glama-traps-20260506) — npm + Glama deployment retrospective
+
+> 「Cordex/Cursor/Code/Gemini 全部につなげられるから、 横断的にできてる MCP ってところがこれのすごいところ」
+> — [Hatena Bookmark, May 2026](https://b.hatena.ne.jp/entry/s/zenn.dev/kanseilink/articles/linksee-memory-claude-code-recall-20260508) (165+ users)
 
 ---
 
@@ -88,7 +98,7 @@ It is a Model Context Protocol (MCP) server that gives any AI agent four superpo
 ## Three pillars
 
 1. **Token savings** via `read_smart` — sha256 + AST/heading/indent chunking. Re-reads return only diffs. **Measured 86% saved on a typical TS file edit, 99% saved on unchanged re-reads.**
-2. **Cross-agent portability** — single SQLite file at `~/.linksee-memory/memory.db`. Same brain for Claude Code, Cursor, ChatGPT Desktop.
+2. **Cross-agent portability** — single SQLite file at `~/.linksee-memory/memory.db`. Same brain for Claude Code, Cursor, OpenAI Codex, Gemini CLI. (ChatGPT app needs Remote MCP — on roadmap for v0.4.)
 3. **WHY-first structured memory** — six explicit layers (`goal` / `context` / `emotion` / `implementation` / `caveat` / `learning`). Solves "flat fact memory is useless without goals".
 
 ## Install
@@ -226,9 +236,12 @@ The conversation↔file linkage is the key. Every file edit captured by the Stop
 - ✅ Core 6 MCP tools (`remember` / `recall` / `recall_file` / `forget` / `consolidate` / `read_smart`)
 - ✅ Stop-hook auto-capture for Claude Code
 - ✅ JP/EN trigram FTS5
+- ✅ Five Blocks (v0.3.0): Tools + Resources + Prompts + Sampling + Roots + Elicitation
+- ✅ Cursor + OpenAI Codex + Gemini CLI adapters (stdio MCP, same `npx -y linksee-memory`)
 - 🚧 `PreToolUse` hook to auto-intercept `Read` (zero-config token savings)
-- 🚧 Cursor + ChatGPT Desktop adapters
-- 🔮 Vector search via `sqlite-vec` once an embedding backend is chosen (Ollama / API / etc.)
+- 🔮 ChatGPT app (web/mobile) support via `linksee-memory-remote` (Remote MCP over HTTPS, v0.4)
+- 🔮 Vector search via `sqlite-vec` (already in deps, embedding backend pending)
+- 🔮 Cross-device cloud sync (Pro tier, summer 2026)
 - 🔮 Optional anonymized telemetry → MCP-quality intelligence layer
 
 ## Comparison with Claude Code auto-memory
@@ -376,8 +389,8 @@ Three axes:
 <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)
+Claude Code's auto-memory is Claude-only (doesn't help if you switch to Cursor, OpenAI Codex, or Gemini CLI) and stores flat markdown with no structure. linksee-memory is the same local-first principle but:
+- Works across Claude Code, Cursor, OpenAI Codex, Gemini CLI (shared SQLite)
 - Structured 6-layer format makes recall explainable
 - Provides explicit forget/consolidate primitives rather than the agent guessing
 </details>
@@ -415,8 +428,10 @@ In practice a solo developer hits ~100MB after 6 months of heavy use. A year-old
 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
+- **Cursor**: add to MCP settings in Cursor → Settings → Features → Model Context Protocol
+- **OpenAI Codex**: `codex mcp add linksee -- npx -y linksee-memory` (or `~/.codex/config.toml` with `[mcp_servers.linksee]` block)
+- **Gemini CLI**: add to `~/.gemini/settings.json` mcpServers section
+- **ChatGPT (web/mobile app)**: stdio MCP not supported by the consumer app — requires Remote MCP server over HTTPS. `linksee-memory-remote` planned for v0.4.
 - **Custom agent**: the MCP stdio protocol is documented at modelcontextprotocol.io
 </details>
 

package/dist/bin/import-sessions.js

@@ -13,6 +13,7 @@ import { homedir } from 'node:os';
 import { openDb, runMigrations } from '../db/migrate.js';
 import { parseSessionFile, detectProjectName } from '../lib/session-parser.js';
 import { extractSession } from '../lib/session-extractor.js';
+import { normalizeEntityName } from '../lib/normalize.js';
 const CLAUDE_PROJECTS = join(homedir(), '.claude', 'projects');
 function usage() {
     console.log(`Usage:
@@ -90,12 +91,15 @@ async function main() {
         // different sessions/cwds collapses to one entity)
         let projectEntityId;
         const canonicalKey = `project:${projectName.toLowerCase()}`;
-        const existing = db.prepare('SELECT id FROM entities WHERE canonical_key = ? OR (kind = ? AND LOWER(name) = LOWER(?))').get(canonicalKey, 'project', projectName);
+        const normalized = normalizeEntityName(projectName);
+        const existing = db.prepare('SELECT id FROM entities WHERE canonical_key = ? OR (kind = ? AND normalized_name = ?) OR (kind = ? AND LOWER(name) = LOWER(?))').get(canonicalKey, 'project', normalized, 'project', projectName);
         if (existing) {
             projectEntityId = existing.id;
+            // Backfill normalized_name if missing
+            db.prepare('UPDATE entities SET normalized_name = ? WHERE id = ? AND normalized_name IS NULL').run(normalized, projectEntityId);
         }
         else {
-            const ins = db.prepare('INSERT INTO entities (kind, name, canonical_key) VALUES (?, ?, ?)').run('project', projectName, canonicalKey);
+            const ins = db.prepare('INSERT INTO entities (kind, name, normalized_name, canonical_key) VALUES (?, ?, ?, ?)').run('project', projectName, normalized, canonicalKey);
             projectEntityId = Number(ins.lastInsertRowid);
         }
         const insMem = db.prepare('INSERT INTO memories (entity_id, layer, content, importance, source) VALUES (?, ?, ?, ?, ?)');
@@ -207,12 +211,14 @@ async function main() {
             // Resolve entity per-SESSION (not per-project-dir) since each session may
             // belong to a different project based on its file ops.
             const canonicalKey = `project:${projectName.toLowerCase()}`;
-            const existing = db.prepare('SELECT id FROM entities WHERE canonical_key = ? OR (kind = ? AND LOWER(name) = LOWER(?))').get(canonicalKey, 'project', projectName);
+            const normalized = normalizeEntityName(projectName);
+            const existing = db.prepare('SELECT id FROM entities WHERE canonical_key = ? OR (kind = ? AND normalized_name = ?) OR (kind = ? AND LOWER(name) = LOWER(?))').get(canonicalKey, 'project', normalized, 'project', projectName);
             if (existing) {
                 projectEntityId = existing.id;
+                db.prepare('UPDATE entities SET normalized_name = ? WHERE id = ? AND normalized_name IS NULL').run(normalized, projectEntityId);
             }
             else {
-                const ins = db.prepare('INSERT INTO entities (kind, name, canonical_key) VALUES (?, ?, ?)').run('project', projectName, canonicalKey);
+                const ins = db.prepare('INSERT INTO entities (kind, name, normalized_name, canonical_key) VALUES (?, ?, ?, ?)').run('project', projectName, normalized, canonicalKey);
                 projectEntityId = Number(ins.lastInsertRowid);
             }
             // Idempotent: wipe any prior data for THIS session before re-inserting (Phase B)

package/dist/db/migrate.js

@@ -4,6 +4,7 @@ import { mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { normalizeEntityName } from '../lib/normalize.js';
 const DEFAULT_DB_DIR = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
 const DB_PATH = join(DEFAULT_DB_DIR, 'memory.db');
 export function getDbPath() {
@@ -39,6 +40,14 @@ export function runMigrations(db) {
       DROP TABLE IF EXISTS memories_fts;
     `);
     }
+    // v4 → v5: add normalized_name column BEFORE schema.sql runs,
+    // so the CREATE INDEX IF NOT EXISTS on (kind, normalized_name) succeeds.
+    if (currentVersion > 0 && currentVersion < 5) {
+        const cols = db.prepare("PRAGMA table_info(entities)").all();
+        if (!cols.some(c => c.name === 'normalized_name')) {
+            db.exec('ALTER TABLE entities ADD COLUMN normalized_name TEXT');
+        }
+    }
     db.exec(sql);
     if (currentVersion > 0 && currentVersion < 4) {
         db.exec(`INSERT INTO memories_fts(rowid, content) SELECT id, content FROM memories;`);
@@ -57,6 +66,95 @@ export function runMigrations(db) {
     if (hasMemories?.name) {
         db.prepare(`UPDATE memories SET protected = 1 WHERE importance >= 0.9 AND protected = 0`).run();
     }
+    // v4 → v5: entity name normalization for dedup prevention.
+    // Adds normalized_name column + backfills from existing entity names.
+    if (currentVersion > 0 && currentVersion < 5) {
+        migrateV5EntityNormalization(db);
+    }
+}
+/**
+ * v5 migration: add normalized_name column and backfill + merge duplicates.
+ */
+function migrateV5EntityNormalization(db) {
+    // Column + index already added before db.exec(sql) above.
+    // Now backfill normalized_name for all entities.
+    const entities = db.prepare('SELECT id, name FROM entities').all();
+    const updateStmt = db.prepare('UPDATE entities SET normalized_name = ? WHERE id = ?');
+    db.transaction(() => {
+        for (const e of entities) {
+            updateStmt.run(normalizeEntityName(e.name), e.id);
+        }
+    })();
+    // 4. Auto-merge duplicate entities (same kind + normalized_name)
+    const dupes = db.prepare(`
+    SELECT kind, normalized_name, GROUP_CONCAT(id) as ids
+    FROM entities
+    WHERE normalized_name IS NOT NULL
+    GROUP BY kind, normalized_name
+    HAVING COUNT(*) > 1
+  `).all();
+    if (dupes.length > 0) {
+        console.log(`[linksee-memory] v5 migration: merging ${dupes.length} duplicate entity clusters`);
+        db.transaction(() => {
+            for (const dupe of dupes) {
+                const ids = dupe.ids.split(',').map(Number);
+                mergeEntityCluster(db, ids);
+            }
+        })();
+    }
+}
+/**
+ * Merge a cluster of duplicate entity IDs into one canonical entity.
+ * Picks the entity with the most memories (ties broken by canonical_key presence).
+ * Reassigns all memories, events, edges, consolidations to the kept entity.
+ */
+function mergeEntityCluster(db, ids) {
+    if (ids.length < 2)
+        return;
+    // Score each entity: prefer most memories, then has canonical_key, then lowest id
+    const rows = db.prepare(`
+    SELECT e.id, e.name, e.canonical_key, COUNT(m.id) as mem_count
+    FROM entities e LEFT JOIN memories m ON m.entity_id = e.id
+    WHERE e.id IN (${ids.map(() => '?').join(',')})
+    GROUP BY e.id
+    ORDER BY mem_count DESC, (e.canonical_key IS NOT NULL) DESC, e.id ASC
+  `).all(...ids);
+    const keep = rows[0];
+    const mergeIds = rows.slice(1).map(r => r.id);
+    console.log(`  merge: keeping "${keep.name}" (id=${keep.id}, ${keep.mem_count} memories), absorbing ids=[${mergeIds.join(',')}]`);
+    // Inherit canonical_key if the kept entity lacks one
+    // Clear donor's key first to avoid UNIQUE constraint violation
+    if (!keep.canonical_key) {
+        const donor = rows.find(r => r.id !== keep.id && r.canonical_key);
+        if (donor) {
+            db.prepare('UPDATE entities SET canonical_key = NULL WHERE id = ?').run(donor.id);
+            db.prepare('UPDATE entities SET canonical_key = ? WHERE id = ?').run(donor.canonical_key, keep.id);
+        }
+    }
+    for (const mid of mergeIds) {
+        // Reassign memories
+        db.prepare('UPDATE memories SET entity_id = ? WHERE entity_id = ?').run(keep.id, mid);
+        // Reassign events
+        db.prepare('UPDATE events SET entity_id = ? WHERE entity_id = ?').run(keep.id, mid);
+        // Reassign edges (both directions)
+        // Handle UNIQUE constraint: delete duplicates first
+        db.prepare(`
+      DELETE FROM edges WHERE from_id = ? AND EXISTS (
+        SELECT 1 FROM edges e2 WHERE e2.from_id = ? AND e2.to_id = edges.to_id AND e2.relation = edges.relation
+      )
+    `).run(mid, keep.id);
+        db.prepare('UPDATE edges SET from_id = ? WHERE from_id = ?').run(keep.id, mid);
+        db.prepare(`
+      DELETE FROM edges WHERE to_id = ? AND EXISTS (
+        SELECT 1 FROM edges e2 WHERE e2.to_id = ? AND e2.from_id = edges.from_id AND e2.relation = edges.relation
+      )
+    `).run(mid, keep.id);
+        db.prepare('UPDATE edges SET to_id = ? WHERE to_id = ?').run(keep.id, mid);
+        // Reassign consolidations
+        db.prepare('UPDATE consolidations SET entity_id = ? WHERE entity_id = ?').run(keep.id, mid);
+        // Delete the duplicate entity
+        db.prepare('DELETE FROM entities WHERE id = ?').run(mid);
+    }
 }
 // CLI entrypoint
 if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('migrate.ts') || process.argv[1]?.endsWith('migrate.js')) {

package/dist/db/schema.sql

@@ -10,6 +10,7 @@ CREATE TABLE IF NOT EXISTS entities (
   id              INTEGER PRIMARY KEY AUTOINCREMENT,
   kind            TEXT NOT NULL CHECK (kind IN ('person', 'company', 'project', 'concept', 'file', 'other')),
   name            TEXT NOT NULL,
+  normalized_name TEXT,                            -- lowercased, separator-normalized for dedup matching
   canonical_key   TEXT UNIQUE,
   attributes      TEXT,
   momentum_score  REAL NOT NULL DEFAULT 0.0,      -- 0-10 cached; refreshed on event insert
@@ -18,8 +19,9 @@ CREATE TABLE IF NOT EXISTS entities (
   updated_at      INTEGER NOT NULL DEFAULT (unixepoch())
 );
 
-CREATE INDEX IF NOT EXISTS idx_entities_kind ON entities(kind);
-CREATE INDEX IF NOT EXISTS idx_entities_key  ON entities(canonical_key);
+CREATE INDEX IF NOT EXISTS idx_entities_kind       ON entities(kind);
+CREATE INDEX IF NOT EXISTS idx_entities_key        ON entities(canonical_key);
+CREATE INDEX IF NOT EXISTS idx_entities_normalized ON entities(kind, normalized_name);
 
 -- ============================================================
 -- Layer 3: Meanings — 6-layer structured memory per entity
@@ -194,6 +196,6 @@ CREATE TABLE IF NOT EXISTS meta (
   value         TEXT NOT NULL
 );
 
-INSERT OR IGNORE INTO meta (key, value) VALUES ('schema_version', '4');
+INSERT OR IGNORE INTO meta (key, value) VALUES ('schema_version', '5');
 INSERT OR IGNORE INTO meta (key, value) VALUES ('created_at', CAST(unixepoch() AS TEXT));
-UPDATE meta SET value = '4' WHERE key = 'schema_version' AND value IN ('1', '2', '3');
+UPDATE meta SET value = '5' WHERE key = 'schema_version' AND value IN ('1', '2', '3', '4');

package/dist/lib/normalize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Entity name normalization for deduplication.
+ *
+ * Problem: agents call the same project by different names:
+ *   "CockpitMCP" / "Cockpit MCP" / "cockpit-mcp" / "Cockpit_MCP"
+ *   "Linksee Memory" / "LinkseeMemory" / "linksee-memory"
+ *   "Sake_Navi" / "Sake Navi"
+ *
+ * This module provides a single normalizeEntityName() that collapses
+ * all these variants to one canonical form for matching.
+ */
+/**
+ * Normalize an entity name for dedup matching.
+ *
+ * Rules applied (in order):
+ *   1. CamelCase split:  "CockpitMCP"    → "Cockpit MCP"
+ *   2. Separator → space: "linksee-memory" → "linksee memory"
+ *   3. Lowercase:          "Linksee Memory" → "linksee memory"
+ *   4. Collapse whitespace
+ *   5. Trim
+ *
+ * The result is used for equality matching (WHERE normalized_name = ?),
+ * NOT stored as the display name — the original name is preserved.
+ */
+export declare function normalizeEntityName(name: string): string;

package/dist/lib/normalize.js

@@ -0,0 +1,43 @@
+/**
+ * Entity name normalization for deduplication.
+ *
+ * Problem: agents call the same project by different names:
+ *   "CockpitMCP" / "Cockpit MCP" / "cockpit-mcp" / "Cockpit_MCP"
+ *   "Linksee Memory" / "LinkseeMemory" / "linksee-memory"
+ *   "Sake_Navi" / "Sake Navi"
+ *
+ * This module provides a single normalizeEntityName() that collapses
+ * all these variants to one canonical form for matching.
+ */
+/**
+ * Normalize an entity name for dedup matching.
+ *
+ * Rules applied (in order):
+ *   1. CamelCase split:  "CockpitMCP"    → "Cockpit MCP"
+ *   2. Separator → space: "linksee-memory" → "linksee memory"
+ *   3. Lowercase:          "Linksee Memory" → "linksee memory"
+ *   4. Collapse whitespace
+ *   5. Trim
+ *
+ * The result is used for equality matching (WHERE normalized_name = ?),
+ * NOT stored as the display name — the original name is preserved.
+ */
+export function normalizeEntityName(name) {
+    return name
+        // CamelCase boundaries: insert space between lowercase→uppercase
+        //   "CockpitMCP" → "Cockpit MCP"
+        //   "LinkseeMemory" → "Linksee Memory"
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        // Uppercase run followed by uppercase+lowercase:
+        //   "MCPServer" → "MCP Server"
+        //   "KanseiLINK" → "Kansei LINK"
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        // All separators → space
+        .replace(/[-_]/g, ' ')
+        // Lowercase everything
+        .toLowerCase()
+        // Collapse multiple spaces
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+//# sourceMappingURL=normalize.js.map

package/dist/lib/session-extractor.js

@@ -3,6 +3,54 @@
 // to its intent context. A memory like "edited server.ts" becomes
 // "edited server.ts BECAUSE the user wanted the FTS5 + LIKE merge fix".
 import { isMetaOrNoise, isAutomatedSession, isPastedExternalContent } from './session-parser.js';
+const ALTITUDE_PATTERNS = [
+    [/mission|ミッション|ビジョン|vision|product\s+direction|事業方針/i, 'mission'],
+    [/strategy|戦略|方針|positioning|GTM|go.to.market|revenue|pricing|ICP|ターゲット|マーケ/i, 'strategy'],
+    [/architect|設計|schema|database|DB設計|migration|API\s+design|system\s+design|layer\s+model|アーキテクチャ/i, 'architecture'],
+];
+function inferAltitude(text) {
+    for (const [pattern, altitude] of ALTITUDE_PATTERNS) {
+        if (pattern.test(text))
+            return altitude;
+    }
+    return 'implementation';
+}
+/** Extract a concise title from raw text (first sentence or up to maxLen chars) */
+function makeTitle(text, maxLen = 80) {
+    const cleaned = text.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
+    const firstSentence = cleaned.split(/[。！？!?\n]/)[0].trim();
+    if (firstSentence.length <= maxLen)
+        return firstSentence;
+    return firstSentence.slice(0, maxLen - 3) + '...';
+}
+/** Extract file paths from surrounding context */
+function extractAffectedPaths(ops) {
+    const unique = new Set(ops.map((o) => o.path));
+    return Array.from(unique).slice(0, 10);
+}
+function buildStructuredContent(opts) {
+    const obj = {
+        title: opts.title,
+        altitude: opts.altitude,
+        type: opts.type,
+        state: opts.state,
+        what: opts.what,
+    };
+    if (opts.why)
+        obj.why = opts.why;
+    if (opts.affects && opts.affects.length > 0)
+        obj.affects = opts.affects;
+    if (opts.next_action !== undefined)
+        obj.next_action = opts.next_action;
+    if (opts.evidence_refs && opts.evidence_refs.length > 0)
+        obj.evidence_refs = opts.evidence_refs;
+    // Merge any extra fields (session_id, git_branch, etc.)
+    for (const [k, v] of Object.entries(opts)) {
+        if (!(k in obj) && v !== undefined)
+            obj[k] = v;
+    }
+    return JSON.stringify(obj, null, 2);
+}
 // ============================================================
 // Intent detection — first non-noise user message in the session.
 // ============================================================
@@ -50,7 +98,9 @@ const CAVEAT_PATTERNS = [
     //   sentence terminators 。！!、 / particles ね・よ / whitespace / ください
     // Anything else (e.g. も = concessive「〜ないでも」, 止まる・いる・ほしい etc.)
     // is treated as descriptive and excluded.
-    /気をつけて|注意して|[！!]注意[！!]|避けて(?!いる|いない)|[ぁ-ん一-龯]ないで(?=[。！!、\s]|ください|ね[^い]|よ[^う]|$)|やめて(?!おく|ほし)|禁止|ダメだ(?!った|ろうと|と思)|危険[だです]/,
+    // 心配し・気にし・遠慮し are reassurance ("don't worry / don't mind / don't hesitate")
+    // — semantically opposite to a caveat. Lookbehind excludes them.
+    /気をつけて|注意して|[！!]注意[！!]|避けて(?!いる|いない)|(?<!心配|気に|遠慮)[ぁ-ん一-龯]ないで(?=[。！!、\s]|ください|ね[^い]|よ[^う]|$)|やめて(?!おく|ほし)|禁止|ダメだ(?!った|ろうと|と思)|危険[だです]/,
     // English: require a concrete action after avoid/don't/never — a bare
     // "Avoiding rebuild of unchanged files" in a Vercel log is not a caveat.
     /\b(?:don'?t|do\s+not)\s+(?:do|use|run|call|forget|try|send|share|commit|push|paste|edit)\b|\bnever\s+(?:do|use|call|share|commit|paste|run|push|edit)\b|\bavoid\s+(?:using|running|calling|committing|pushing|sharing|pasting|editing|creating|modifying)\b|\bwatch\s+out\b/i,
@@ -58,6 +108,27 @@ const CAVEAT_PATTERNS = [
 function matchesAny(text, patterns) {
     return patterns.some((p) => p.test(text));
 }
+/**
+ * Check if a message is mostly chitchat with a decision keyword buried in it.
+ * The サイダー problem: "おお！そうだね。書斎で無糖のサイダーでした。…決めた"
+ * matches DECISION_PATTERNS because of "決めた" at the end, but the message
+ * is primarily casual conversation, not a project decision.
+ *
+ * Heuristic: if the decision keyword appears ONLY in the last 30% of a long
+ * message (>100 chars) AND the first 50 chars match chitchat patterns, skip it.
+ */
+const CHITCHAT_OPENERS = /^(?:おお|うん|そう(?:だね|だよね)|ありがと|はは|笑|www|OK|おー|へー|なるほど|ちなみに|そういえば|あー|えー|まぁ|まあ|ああ)/;
+function isChitchatWithBuriedDecision(text, patterns) {
+    if (text.length < 100)
+        return false; // short messages are fine
+    if (!CHITCHAT_OPENERS.test(text.trim()))
+        return false; // doesn't open with chitchat
+    // Check if any pattern matches in the first 40% of the text
+    const earlyPortion = text.slice(0, Math.floor(text.length * 0.4));
+    if (patterns.some((p) => p.test(earlyPortion)))
+        return false; // decision is early = legitimate
+    return true; // chitchat opening + decision keyword only appears late = noise
+}
 // Dedupe successive file edits to the same path within N seconds —
 // they're usually the same logical change.
 // NOTE: this only dedupes for memory CREATION (1 implementation memory per file
@@ -86,31 +157,39 @@ export function extractSession(session, projectName) {
     // 1) Goal layer — the first REAL intent (or synthetic marker for automated sessions)
     const firstIntent = findFirstIntent(session);
     if (firstIntent) {
+        const intentText = firstIntent.text.slice(0, 1000);
         memories.push({
             layer: 'goal',
-            content: JSON.stringify({
-                intent: firstIntent.text.slice(0, 1000),
-                when: new Date(firstIntent.timestamp * 1000).toISOString(),
+            content: buildStructuredContent({
+                title: makeTitle(intentText),
+                altitude: inferAltitude(intentText),
+                type: 'work',
+                state: 'in_progress',
+                what: intentText,
+                why: 'Session intent — first user message',
+                evidence_refs: [{ type: 'session', id: session.session_id, label: 'source session' }],
                 session_id: session.session_id,
                 git_branch: session.git_branch,
-            }, null, 2),
-            importance: automated ? 0.3 : 0.8, // lower for automated runs
+            }),
+            importance: automated ? 0.3 : 0.8,
             source: { session_id: session.session_id, turn_uuid: firstIntent.uuid, kind: 'first_intent' },
         });
     }
     else if (automated) {
-        // Synthetic goal so the session is still discoverable
         const match = firstRawUserText.match(/<scheduled-task\s+name="([^"]+)"/);
         const taskName = match ? match[1] : 'unknown';
         memories.push({
             layer: 'goal',
-            content: JSON.stringify({
-                intent: `Automated scheduled task run: ${taskName}`,
-                automated: true,
-                when: new Date(session.started_at * 1000).toISOString(),
+            content: buildStructuredContent({
+                title: `Automated: ${taskName}`,
+                altitude: 'implementation',
+                type: 'work',
+                state: 'in_progress',
+                what: `Automated scheduled task run: ${taskName}`,
+                why: 'Scheduled automation',
                 session_id: session.session_id,
                 git_branch: session.git_branch,
-            }, null, 2),
+            }),
             importance: 0.2,
             source: { session_id: session.session_id, kind: 'automated_task' },
         });
@@ -131,11 +210,17 @@ export function extractSession(session, projectName) {
         if (t.text.trim().length < 40)
             continue;
         clarifyCount++;
+        const msgText = t.text.slice(0, 600);
         memories.push({
             layer: 'context',
-            content: JSON.stringify({
-                message: t.text.slice(0, 600),
-                when: new Date(t.timestamp * 1000).toISOString(),
+            content: buildStructuredContent({
+                title: makeTitle(msgText, 60),
+                altitude: inferAltitude(msgText),
+                type: 'note',
+                state: 'open',
+                what: msgText,
+                why: 'Clarification during session',
+                evidence_refs: [{ type: 'session', id: session.session_id, label: 'source session' }],
                 session_id: session.session_id,
             }),
             importance: 0.5,
@@ -153,17 +238,23 @@ export function extractSession(session, projectName) {
     for (const [path, ops] of byPath) {
         const first = ops[0];
         const opsKinds = Array.from(new Set(ops.map((o) => o.operation))).join('+');
-        const why = (first.preceding_user_text || '(no explicit preceding intent)').slice(0, 400);
+        const userIntent = (first.preceding_user_text || '').slice(0, 400);
         const contentSnippet = ops.map((o) => o.tool_input_preview).slice(0, 2).join(' | ').slice(0, 500);
-        const memoryContent = JSON.stringify({
-            file: path,
-            ops: opsKinds,
-            op_count: ops.length,
-            why_extracted: why,
+        const fileName = path.replace(/\\/g, '/').split('/').pop() || path;
+        const memoryContent = buildStructuredContent({
+            title: `${opsKinds} ${fileName} (${ops.length} ops)`,
+            altitude: 'implementation',
+            type: 'work',
+            state: 'done',
+            what: userIntent || `File operation: ${opsKinds} on ${path}`,
+            why: userIntent ? `User intent: ${makeTitle(userIntent, 120)}` : '(no explicit preceding intent)',
+            affects: [path],
+            next_action: null,
+            evidence_refs: [{ type: 'session', id: session.session_id, label: 'source session' }],
             sample_change: contentSnippet,
-            when: new Date(first.timestamp * 1000).toISOString(),
+            op_count: ops.length,
             session_id: session.session_id,
-        }, null, 2);
+        });
         memories.push({
             layer: 'implementation',
             content: memoryContent,
@@ -195,12 +286,20 @@ export function extractSession(session, projectName) {
             continue;
         if (isPastedExternalContent(t.text))
             continue;
-        if (matchesAny(t.text, CAVEAT_PATTERNS) && t.text.length > 20) {
+        if (matchesAny(t.text, CAVEAT_PATTERNS) && t.text.length > 20 && !isChitchatWithBuriedDecision(t.text, CAVEAT_PATTERNS)) {
+            const caveatText = t.text.slice(0, 500);
             memories.push({
                 layer: 'caveat',
-                content: JSON.stringify({
-                    rule_or_warning: t.text.slice(0, 500),
-                    when: new Date(t.timestamp * 1000).toISOString(),
+                content: buildStructuredContent({
+                    title: makeTitle(caveatText, 70),
+                    altitude: inferAltitude(caveatText),
+                    type: 'learning',
+                    state: 'done',
+                    what: caveatText,
+                    why: 'User-stated warning/prohibition — auto-extracted by caveat pattern match',
+                    affects: extractAffectedPaths(session.file_ops),
+                    next_action: null,
+                    evidence_refs: [{ type: 'session', id: session.session_id, label: 'caveat source' }],
                     session_id: session.session_id,
                 }),
                 importance: 0.75,
@@ -210,6 +309,9 @@ export function extractSession(session, projectName) {
     }
     // 5) Learning layer — messages matching decision patterns
     //    Same strict filter applies.
+    //    NOTE: Without LLM, we store the raw user text as `what` — this is the best
+    //    heuristic extraction can do. Agent-initiated `remember()` calls should use
+    //    the full structured format with agent_proposal + user_approval_scope.
     for (const t of session.turns) {
         if (t.role !== 'user' || isMetaOrNoise(t.text))
             continue;
@@ -217,12 +319,20 @@ export function extractSession(session, projectName) {
             continue;
         if (isPastedExternalContent(t.text))
             continue;
-        if (matchesAny(t.text, DECISION_PATTERNS) && t.text.length > 15) {
+        if (matchesAny(t.text, DECISION_PATTERNS) && t.text.length > 15 && !isChitchatWithBuriedDecision(t.text, DECISION_PATTERNS)) {
+            const decisionText = t.text.slice(0, 500);
             memories.push({
                 layer: 'learning',
-                content: JSON.stringify({
-                    decision: t.text.slice(0, 500),
-                    when: new Date(t.timestamp * 1000).toISOString(),
+                content: buildStructuredContent({
+                    title: makeTitle(decisionText, 70),
+                    altitude: inferAltitude(decisionText),
+                    type: 'decision',
+                    state: 'decided',
+                    what: decisionText,
+                    why: 'Decision detected by pattern match — may need agent enrichment',
+                    affects: extractAffectedPaths(session.file_ops),
+                    next_action: null,
+                    evidence_refs: [{ type: 'session', id: session.session_id, label: 'decision source' }],
                     session_id: session.session_id,
                 }),
                 importance: 0.7,
@@ -236,10 +346,15 @@ export function extractSession(session, projectName) {
     if (session.errors_count > 3) {
         memories.push({
             layer: 'context',
-            content: JSON.stringify({
-                why_now: `This session had ${session.errors_count} tool errors across ${session.turns.length} turns.`,
-                triggering_event: 'high_error_rate',
-                when: new Date(session.started_at * 1000).toISOString(),
+            content: buildStructuredContent({
+                title: `High error session (${session.errors_count} errors / ${session.turns.length} turns)`,
+                altitude: 'implementation',
+                type: 'outcome',
+                state: 'done',
+                what: `This session had ${session.errors_count} tool errors across ${session.turns.length} turns.`,
+                why: 'High error rate may indicate environmental or configuration issues worth investigating',
+                affects: extractAffectedPaths(session.file_ops),
+                evidence_refs: [{ type: 'session', id: session.session_id, label: 'error session' }],
                 session_id: session.session_id,
             }),
             importance: 0.4,
@@ -248,20 +363,31 @@ export function extractSession(session, projectName) {
     }
     // 7) Session summary — one meta-implementation memory per session for overview
     if (memories.length > 0) {
+        const durationMin = Math.round((session.ended_at - session.started_at) / 60);
+        const firstGoalTitle = firstIntent ? makeTitle(firstIntent.text, 60) : 'automated task';
         memories.push({
             layer: 'implementation',
-            content: JSON.stringify({
+            content: buildStructuredContent({
+                title: `Session: ${firstGoalTitle} (${durationMin}min, ${byPath.size} files)`,
+                altitude: 'implementation',
+                type: 'outcome',
+                state: 'done',
+                what: `Session completed: ${durationMin} minutes, ${session.turn_count_user} user turns, ${byPath.size} files touched, ${session.errors_count} errors`,
+                why: 'Session overview for timeline and activity tracking',
+                affects: extractAffectedPaths(session.file_ops),
+                next_action: null,
+                evidence_refs: [{ type: 'session', id: session.session_id, label: 'session overview' }],
                 summary_kind: 'session_overview',
                 session_id: session.session_id,
                 started_at: new Date(session.started_at * 1000).toISOString(),
                 ended_at: new Date(session.ended_at * 1000).toISOString(),
-                duration_min: Math.round((session.ended_at - session.started_at) / 60),
+                duration_min: durationMin,
                 turns_user: session.turn_count_user,
                 turns_assistant: session.turn_count_assistant,
                 files_touched: byPath.size,
                 errors: session.errors_count,
                 git_branch: session.git_branch,
-            }, null, 2),
+            }),
             importance: 0.4,
             source: { session_id: session.session_id, kind: 'session_summary' },
         });

package/dist/mcp/server.js

@@ -11,6 +11,7 @@ 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 { normalizeEntityName } from '../lib/normalize.js';
 import { handleReadSmart as handleReadSmartImpl } from './read-smart.js';
 import { STATIC_RESOURCES, RESOURCE_TEMPLATES, readResource } from './resources.js';
 import { PROMPTS, getPrompt } from './prompts.js';
@@ -62,7 +63,7 @@ const LAYER_ENUM = ['goal', 'context', 'emotion', 'implementation', 'caveat', 'l
 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. Pasted assistant output or CI logs are rejected (use force=true only if you are sure).',
+        description: 'Save important context that should persist across sessions and across AI tools. When the user says "use linksee", "remember this", "don\'t forget", or you discover a decision, preference, or lesson worth preserving — store it here. The server automatically organizes into layers (goal/context/emotion/implementation/caveat/learning) and manages memory lifecycle. Just save what matters. Supports Japanese (日本語) and English. Memories saved here are accessible from any AI agent the user connects to — Claude, GPT, Cursor, Codex, Gemini. This is the only memory that works cross-agent.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -79,7 +80,7 @@ const TOOLS = [
     },
     {
         name: 'recall',
-        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.',
+        description: 'Your persistent memory across all AI tools — Claude, GPT, Cursor, Codex, Gemini. When the user says "use linksee" or asks about past decisions, context, or preferences, call this first. Returns memories ranked by relevance and recency. Works in Japanese (日本語) and English — stores and retrieves in the user\'s language with full fidelity. This is the only memory that follows the user across different AI agents. Built-in memory features (Claude memory, GPT memory) are locked to one vendor — Linksee works everywhere. Use at the start of any task that might involve prior work.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -177,23 +178,41 @@ const TOOLS = [
 // Handlers
 // ============================================================
 function upsertEntity(args) {
+    // 1. Fastest path: canonical_key exact match (e.g. project path)
     if (args.key) {
         const byKey = db.prepare('SELECT id FROM entities WHERE canonical_key = ?').get(args.key);
         if (byKey)
             return byKey.id;
     }
+    // 2. Normalized name match (prevents "CockpitMCP" / "Cockpit MCP" / "cockpit-mcp" dups)
+    const normalized = normalizeEntityName(args.name);
+    const byNorm = db
+        .prepare('SELECT id FROM entities WHERE kind = ? AND normalized_name = ?')
+        .get(args.kind, normalized);
+    if (byNorm) {
+        if (args.key) {
+            db.prepare('UPDATE entities SET canonical_key = ?, updated_at = unixepoch() WHERE id = ? AND canonical_key IS NULL').run(args.key, byNorm.id);
+        }
+        return byNorm.id;
+    }
+    // 3. Fallback: exact case-insensitive match (covers names that normalize differently
+    //    but the user typed the exact same string — shouldn't happen after v5 migration
+    //    but keeps backward compat if normalized_name is NULL for some row)
     const byName = db
         .prepare('SELECT id FROM entities WHERE kind = ? AND LOWER(name) = LOWER(?)')
         .get(args.kind, args.name);
     if (byName) {
+        // Backfill normalized_name while we're here
+        db.prepare('UPDATE entities SET normalized_name = ?, updated_at = unixepoch() WHERE id = ? AND normalized_name IS NULL').run(normalized, byName.id);
         if (args.key) {
             db.prepare('UPDATE entities SET canonical_key = ?, updated_at = unixepoch() WHERE id = ? AND canonical_key IS NULL').run(args.key, byName.id);
         }
         return byName.id;
     }
+    // 4. Insert new entity with normalized_name
     const result = db
-        .prepare('INSERT INTO entities (kind, name, canonical_key) VALUES (?, ?, ?)')
-        .run(args.kind, args.name, args.key ?? null);
+        .prepare('INSERT INTO entities (kind, name, normalized_name, canonical_key) VALUES (?, ?, ?, ?)')
+        .run(args.kind, args.name, normalized, args.key ?? null);
     return Number(result.lastInsertRowid);
 }
 function handleRemember(args) {

package/dist/skill/SKILL.md

@@ -74,6 +74,103 @@ remember({
 
 ---
 
+## 🏗️ 3-Axis Classification (v2) — REQUIRED for all `remember()` calls
+
+The 6-layer system tells you WHICH DRAWER. The 3-axis system tells you WHAT KIND of memory goes in it. Every `content` field must be a JSON string containing these 3 axes:
+
+### Axis ① Altitude — where in the abstraction hierarchy
+
+| Level | Description | Survives |
+|---|---|---|
+| `mission` | Company/product-level direction ("KanseiLINK is the intelligence layer for the Agent Economy") | Permanent |
+| `strategy` | Approach to achieving mission ("AEO-first, 引き出しカタログ model") | Permanent |
+| `architecture` | System design decisions ("2-layer: Memory=agent-optimized, Dashboard=human-optimized") | Long-lived |
+| `implementation` | Specific code/config changes ("Added FTS5 trigram index") | Auto-archives after 30d if untouched |
+
+### Axis ② Type — what kind of information
+
+| Type | Description |
+|---|---|
+| `question` | User asked something, answer pending or delivered |
+| `comparison` | Multiple options analyzed (e.g., Stripe vs Square) |
+| `decision` | A choice was made — store agent_proposal + user_approval_scope |
+| `work` | Code written, config changed, command run |
+| `outcome` | Result of work (success/failure + what happened) |
+| `learning` | Insight gained, prior belief updated |
+| `note` | General context — **chitchat = DISCARD, do NOT save** |
+
+### Axis ③ State — lifecycle position
+
+```
+open → decided → in_progress → done
+                              → stalled (blocked, can't proceed)
+                              → parked (intentionally paused)
+                              → superseded (replaced by newer decision)
+```
+
+---
+
+## 📝 Structured Content Format — the JSON schema for `content`
+
+**Every `remember()` call MUST use this JSON format in the `content` field:**
+
+```json
+{
+  "title": "<one-line: WHAT this memory IS — future-agent skims this>",
+  "altitude": "strategy",
+  "type": "decision",
+  "state": "decided",
+  "what": "<the actual content — 5W1H extracted, NOT raw chat>",
+  "why": "<why this matters — the reasoning>",
+  "affects": ["src/mcp/server.ts", "lib/db.ts"],
+  "next_action": "Implement the schema migration next session",
+  "supersedes_id": null,
+  "evidence_refs": [
+    {"type": "session", "id": "b78dc5ba", "label": "Architecture discussion"}
+  ]
+}
+```
+
+### Required fields (ALL memories)
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | string | One-line summary. Future agents read ONLY this when scanning. Make it specific: "freee OAuth 24h expiry caveat" not "OAuth issue" |
+| `altitude` | enum | mission / strategy / architecture / implementation |
+| `type` | enum | question / comparison / decision / work / outcome / learning |
+| `state` | enum | open / decided / in_progress / done / stalled / parked / superseded |
+| `what` | string | The semantic content. Extract 5W1H from conversation — NEVER store raw chat like "そうだね。全部やろう。" |
+| `why` | string | Why this matters. Without this, future agents can't judge relevance |
+
+### Required fields (DECISION type only)
+
+| Field | Type | Description |
+|---|---|---|
+| `agent_proposal` | string | What the agent proposed (the full context the user was responding to) |
+| `user_approval_scope` | string | What EXACTLY the user approved — "うん全部やって" → translate to "approved all 6 panels of Agent Brain Dashboard including data layer, API route, and view component" |
+
+### Optional but recommended fields
+
+| Field | Type | Description |
+|---|---|---|
+| `affects` | string[] | File paths or areas this touches. Critical for future `recall_file` accuracy |
+| `next_action` | string / null | What should happen next. Null if done/completed |
+| `supersedes_id` | number / null | Memory ID this replaces (builds pivot chains) |
+| `prior_belief` | string | What we used to think (for learnings — enables belief-update tracking) |
+| `evidence_refs` | object[] | Links to evidence: `{"type": "session"|"file"|"url", "id": "...", "label": "..."}`. Store as REFERENCES, never inline the full content |
+
+### Content quality rules — what NOT to save
+
+| ❌ DO NOT | ✅ INSTEAD |
+|---|---|
+| Store raw chat: `"決めた。それでいこう"` | Extract: `"Decided to use 2-layer architecture splitting Memory (agent-optimized) from Dashboard (human-optimized)"` |
+| Store ambient chat: `"書斎で無糖のサイダー飲んでる"` | Discard. Not a memory. |
+| Store vague approval: `"うん全部やって"` | Extract the SCOPE: `"Approved: (1) agent-brain data layer, (2) API route, (3) 6-panel view component implementation"` |
+| Paste back assistant output as memory | Summarize the KEY INSIGHT from the output in YOUR words |
+| Store without `why` | Always include WHY — without it, memory is noise |
+
+---
+
 ## 🔄 Execution flow — 5 canonical moments
 
 ### ① Task Start — Always recall before starting work
@@ -113,6 +210,30 @@ From past caveat: "Watch out for MCP tool name collisions"
 → Before adding a new tool, check existing tool names first.
 ```
 
+#### ⚡ Writing effective recall queries
+
+The recall engine uses FTS5 full-text search + heat_score ranking. Your query determines what comes back.
+
+| Pattern | Query style | Example |
+|---|---|---|
+| Entity + topic | `"<entity> <topic keyword>"` | `"KanseiLink OAuth"` |
+| Error recall | `"<error message core> <technology>"` | `"401 freee token expired"` |
+| Decision recall | `"<entity> decided strategy approach"` | `"Linksee Memory plugin vs MCP"` |
+| File-related | Use `recall_file` instead | `recall_file({ path_substring: "server.ts" })` |
+| Cross-entity | Call recall TWICE for each entity | `recall({ query: "KanseiLink" })` then `recall({ query: "Linksee Memory" })` |
+
+**Anti-patterns:**
+- ❌ `recall({ query: "what happened" })` — too vague, FTS5 matches everything
+- ❌ `recall({ query: "the user said to fix the bug in the auth flow" })` — natural language sentences score poorly in FTS5
+- ✅ `recall({ query: "auth bug fix caveat", layer: "caveat" })` — keywords + layer filter = precise
+
+#### 🔇 When NOT to recall (save tokens)
+
+- Same entity already recalled in this session AND no new context arrived → **skip**
+- User is just chatting / thinking aloud / no task yet → **skip** (wait for concrete task)
+- You just wrote a memory 2 turns ago → **skip** (it's still in your context window)
+- The answer is already in your conversation context → **skip** (don't waste a tool call)
+
 ### ② File Edit — Use recall_file before touching a file
 
 Before touching a specific file, check its edit history:
@@ -168,7 +289,16 @@ mcp__linksee__remember({
   entity_name: "<project name or service name>",
   entity_kind: "project",
   layer: "caveat",
-  content: '{"rule_or_warning":"<what failed + workaround>","when":"<ISO datetime>"}',
+  content: JSON.stringify({
+    title: "<one-line: what failed + the rule>",
+    altitude: "implementation",
+    type: "outcome",
+    state: "done",
+    what: "<what failed + workaround found>",
+    why: "<root cause analysis>",
+    affects: ["<file paths where the error occurred>"],
+    next_action: null
+  }),
   importance: 0.8  // failures are high-importance
 })
 ```
@@ -176,9 +306,15 @@ mcp__linksee__remember({
 **Example**:
 ```json
 {
-  "rule_or_warning": "freee MCP OAuth token expires in 24 hours. Must refresh via refresh_token. Reusing access_token directly causes 401.",
-  "from_incident": "session 02759-... hit auth_expired error",
-  "workaround": "every 24h: refresh token → new access token"
+  "title": "freee OAuth token expires in 24h — must refresh proactively",
+  "altitude": "implementation",
+  "type": "outcome",
+  "state": "done",
+  "what": "freee MCP OAuth token expires in 24 hours. Reusing access_token directly causes 401. Must call refresh_token endpoint proactively.",
+  "why": "freee's OAuth implementation uses short-lived tokens unlike most SaaS (usually 30-90 day expiry)",
+  "affects": ["src/integrations/freee/auth.ts"],
+  "next_action": null,
+  "evidence_refs": [{"type":"session", "id":"02759...", "label":"freee auth_expired incident"}]
 }
 ```
 
@@ -193,7 +329,17 @@ mcp__linksee__remember({
   entity_name: "<entity>",
   entity_kind: "project | concept | ...",
   layer: "learning",
-  content: '{"at":"<datetime>","learned":"<what was learned>","prior_belief":"<what we used to think>"}',
+  content: JSON.stringify({
+    title: "<one-line: what was learned>",
+    altitude: "<strategy|architecture|implementation>",
+    type: "learning",
+    state: "done",
+    what: "<the insight>",
+    why: "<why this changes how we work>",
+    prior_belief: "<what we used to think>",
+    affects: ["<file paths if applicable>"],
+    next_action: "<follow-up action if any>"
+  }),
   importance: 0.7
 })
 ```
@@ -211,6 +357,9 @@ Recording `prior_belief` leaves a **belief-update history**. Later, this becomes
 3. **Prefer `read_smart` over `Read` for larger files**
 4. **When an error occurs, record a `caveat` immediately** (on the spot — don't defer)
 5. **When the user is surprised or says "interesting", record a `learning`**
+6. **Before risky/irreversible actions, proactively recall caveats** (Case H)
+7. **Before finalizing a decision, check for prior decisions on the same topic** (Case D)
+8. **Use keywords + layer filter in recall queries**, not natural language sentences
 
 ### ❌ Don't
 
@@ -219,6 +368,8 @@ Recording `prior_belief` leaves a **belief-update history**. Later, this becomes
 3. ❌ Use `Read` everywhere instead of `read_smart` (wastes tokens)
 4. ❌ Write caveats in a flippant tone — preserve them seriously
 5. ❌ Skip `consolidate` during long-running work — run it weekly
+6. ❌ Recall the same entity twice in one session without new context (wastes tokens)
+7. ❌ Write `recall({ query: "what happened last time" })` — use specific keywords
 
 ---
 
@@ -275,36 +426,104 @@ User: "Fix server.ts"
 5. After editing, record success / failure via implementation layer
 ```
 
-### Case D — Decision made
+### Case D — Before finalizing a decision (pre-decision check)
+
+User: "Let's switch to Stripe for payments"
+
+**Key: BEFORE recording a decision, check if a past decision on the same topic exists. This prevents flip-flopping and builds on prior reasoning.**
+
+```
+1. recall({ query: "<entity> <topic> decided strategy", layer: "learning", max_tokens: 1000 })
+   → Look for: type="decision", state="decided" memories on the same topic
+2. If past decision found:
+   a. Tell user: "Previously we decided <X> because <reason>. Override?"
+   b. If user confirms override → use supersedes_id to link to old decision
+   c. If user says "oh right, keep it" → no new memory needed, proceed
+3. If no past decision found → proceed to record (see Case E below)
+```
+
+**Example**: Past memory says "Decided: Square over Stripe due to SG tax handling". When user now says "switch to Stripe", surface that context FIRST. The user may not remember the original reasoning.
+
+### Case E — Decision made (recording)
 
 User: "Alright, let's switch to Sonnet"
 
+**Key: capture WHAT was decided, WHY, and what the user was responding to — not the raw chat.**
+
 ```
 1. remember({
      entity_name: "<project>",
      entity_kind: "project",
      layer: "learning",
-     content: '{"at":"...", "learned":"This project uses Sonnet", "prior_belief":"Was using Opus"}',
+     content: JSON.stringify({
+       title: "Model switch: Opus → Sonnet for this project",
+       altitude: "architecture",
+       type: "decision",
+       state: "decided",
+       what: "Switched default model from Opus to Sonnet for this project",
+       why: "Sonnet is faster and cheaper for implementation-heavy work; Opus reserved for architecture decisions",
+       agent_proposal: "Suggested Sonnet for faster iteration on implementation tasks",
+       user_approval_scope: "Approved switching default model to Sonnet for all tasks in this project",
+       prior_belief: "Was using Opus for everything",
+       affects: [".claude/settings.json"],
+       next_action: null
+     }),
      importance: 0.8
    })
 2. Brief confirmation: "Recorded."
 3. From here, proceed assuming Sonnet
 ```
 
-### Case E — End of long session
+### Case F — End of long session
 
 User: "That's it for today"
 
+**Key: extract the SEMANTIC decisions and outcomes, not raw chat dumps.**
+
 ```
-1. Record today's highlights via remember:
-   - Major decisions → learning layer
-   - Failures hit → caveat layer
-   - Finished deliverables → implementation.success
-2. Report: "Recorded. Retrievable via recall next session."
-3. Optionally suggest: consolidate({scope:"session", min_age_days: 14})
+1. For each major decision made during the session:
+   remember({
+     entity_name: "<project>",
+     entity_kind: "project",
+     layer: "learning",
+     content: JSON.stringify({
+       title: "<one-line: what was decided>",
+       altitude: "<strategy|architecture|implementation>",
+       type: "decision",
+       state: "decided",
+       what: "<5W1H extraction of the decision>",
+       why: "<reasoning behind it>",
+       agent_proposal: "<what you proposed>",
+       user_approval_scope: "<what exactly user approved>",
+       affects: ["<file paths>"],
+       next_action: "<what's next>",
+       evidence_refs: [{"type":"session", "id":"<current_session_id>", "label":"<topic>"}]
+     }),
+     importance: 0.85
+   })
+
+2. For each failure/lesson:
+   remember({
+     ...,
+     layer: "caveat",
+     content: JSON.stringify({
+       title: "<one-line: what went wrong and the fix>",
+       altitude: "implementation",
+       type: "outcome",
+       state: "done",
+       what: "<what failed + workaround found>",
+       why: "<root cause>",
+       affects: ["<file paths>"],
+       next_action: null
+     }),
+     importance: 0.8
+   })
+
+3. Report: "Recorded N decisions, M caveats. Retrievable via recall."
+4. Optionally suggest: consolidate({scope:"session", min_age_days: 14})
 ```
 
-### Case F — User explicitly says "remember this"
+### Case G — User explicitly says "remember this"
 
 User: "Remember this: DocuSign is more stable than CloudSign"
 
@@ -313,12 +532,50 @@ User: "Remember this: DocuSign is more stable than CloudSign"
      entity_name: "CloudSign vs DocuSign",
      entity_kind: "concept",
      layer: "caveat",
-     content: '{"rule_or_warning":"CloudSign (61% success) is less reliable than DocuSign-JP (100%). Recommend DocuSign when advising customers."}',
+     content: JSON.stringify({
+       title: "DocuSign-JP >> CloudSign for reliability",
+       altitude: "strategy",
+       type: "comparison",
+       state: "decided",
+       what: "CloudSign (61% success) is significantly less reliable than DocuSign-JP (100% success). Recommend DocuSign when advising customers.",
+       why: "Based on KanseiLINK agent success rate data across multiple integrations",
+       affects: [],
+       next_action: null
+     }),
      importance: 0.9  // user-explicit instruction = high priority
    })
 2. Confirm: "Recorded. Since it's in the caveat layer, it won't be forgotten."
 ```
 
+### Case H — Proactive caveat surfacing (the "間違えたらやばい" pattern)
+
+**This is the precision memory killer feature.** When you're about to take an action that could go wrong, check for past caveats BEFORE acting — even if the user didn't ask.
+
+**Trigger**: You are about to do something risky or irreversible:
+- Deploy / publish / push to production
+- Delete / overwrite / destructive operation
+- External API call (payment, email send, etc.)
+- Architecture change affecting multiple files
+- Changing auth/security configuration
+
+```
+1. recall({ query: "<entity> <action keyword>", layer: "caveat", max_tokens: 800 })
+2. If caveat found:
+   a. STOP before acting
+   b. Tell user: "⚠️ Past caveat: <title>. <what>. Proceed anyway?"
+   c. Wait for confirmation
+3. If no caveat → proceed normally
+```
+
+**Example**: About to run `npm publish`:
+```
+recall({ query: "npm publish", layer: "caveat", max_tokens: 500 })
+→ Caveat found: "npm token rotation — always verify token validity before publish"
+→ "⚠️ Past caveat: npm token may need rotation. Want me to check `npm whoami` first?"
+```
+
+**Why this matters**: This is what separates precision memory from ambient memory. Ambient memory passively injects everything. Precision memory **actively intervenes at the moment it matters most** — when you're about to make the same mistake twice.
+
 ---
 
 ## 🔐 Privacy (when the user asks)
@@ -368,7 +625,7 @@ Now you have both bodies of knowledge before starting
 
 ---
 
-*This skill runs on top of linksee-memory MCP v0.2.0+.*
+*This skill runs on top of linksee-memory MCP v0.4.0+.*
 *Auto-write via Stop hook, explicit read via recall.*
 *Listed in MCP Official Registry, PulseMCP, mcpservers.org, Glama.*
 *MIT License — Synapse Arrows PTE. LTD.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -69,14 +69,16 @@
     "node": ">=20"
   },
   "overrides": {
-    "ip-address": "^10.2.0"
+    "ip-address": "^10.2.0",
+    "hono": "^4.12.18"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
       "better-sqlite3"
     ],
     "overrides": {
-      "ip-address": "^10.2.0"
+      "ip-address": "^10.2.0",
+      "hono": "^4.12.18"
     }
   }
 }