linksee-memory 0.3.0 → 0.4.1

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,47 +98,46 @@ 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
+## Quick Start — One Command
 
 ```bash
-npm install -g linksee-memory
-linksee-memory-import --help   # bundled importer for Claude Code session history
+npx linksee-memory-setup
 ```
 
-Or use `npx` ad hoc:
+This does everything:
+1. Registers the MCP server with Claude Code
+2. Installs the agent skill (teaches the agent when to recall/remember)
+3. Configures auto-capture (every session saved to your local brain)
 
-```bash
-npx linksee-memory             # starts the MCP server on stdio
-```
+Restart Claude Code, then just chat normally. Add **"Use Linksee"** to any prompt to trigger memory recall.
+
+### Manual setup (if you prefer step-by-step)
 
-The default database lives at `~/.linksee-memory/memory.db`. Override with the `LINKSEE_MEMORY_DIR` environment variable.
+<details>
+<summary>Click to expand manual installation</summary>
 
-## Register with Claude Code
+**Install & register:**
 
 ```bash
 claude mcp add -s user linksee -- npx -y linksee-memory
 ```
 
-Restart Claude Code. Tools appear as `mcp__linksee__remember`, `mcp__linksee__recall`, `mcp__linksee__recall_file`, `mcp__linksee__read_smart`, `mcp__linksee__forget`, `mcp__linksee__consolidate`.
+Tools appear as `mcp__linksee__remember`, `mcp__linksee__recall`, `mcp__linksee__recall_file`, `mcp__linksee__read_smart`, `mcp__linksee__forget`, `mcp__linksee__consolidate`.
 
-### Recommended: install the skill (auto-invocation)
-
-Installing the MCP alone doesn't teach Claude Code *when* to call `recall` / `remember`. The bundled skill fixes that:
+**Install the skill (auto-invocation):**
 
 ```bash
 npx -y linksee-memory-install-skill
 ```
 
-This copies a `SKILL.md` to `~/.claude/skills/linksee-memory/`. Claude Code auto-discovers it and fires the skill on phrases like "前に…", "また同じエラー", "覚えておいて", new task starts, file edits, and so on — no need to say "use linksee-memory".
-
-Flags: `--dry-run`, `--force`, `--help`.
+Copies `SKILL.md` to `~/.claude/skills/linksee-memory/`. Agent auto-fires on phrases like "前に…", "また同じエラー", "覚えておいて", new task starts, file edits, etc.
 
-### Optional: auto-capture every session (Stop hook)
+**Configure auto-capture (Stop hook):**
 
-Add to `~/.claude/settings.json` to record every Claude Code session to your local brain automatically:
+Add to `~/.claude/settings.json`:
 
 ```json
 {
@@ -145,7 +154,13 @@ Add to `~/.claude/settings.json` to record every Claude Code session to your loc
 }
 ```
 
-Each turn end takes ~100 ms. Failures are silent (Claude Code never blocks). Logs at `~/.linksee-memory/hook.log`.
+Each turn end takes ~100 ms. Failures are silent. Logs at `~/.linksee-memory/hook.log`.
+
+</details>
+
+### Database location
+
+Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env var.
 
 ## v0.3.0 — Five Blocks at a glance
 
@@ -226,9 +241,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 +394,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 +433,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/bin/setup.d.ts

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

package/dist/bin/setup.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// setup: One-command setup for Linksee Memory — the "Use Linksee" installer.
+//
+// Usage:
+//   npx linksee-memory-setup          (interactive setup)
+//   npx linksee-memory-setup --yes    (accept all defaults, no prompts)
+//   npx linksee-memory-setup --dry-run
+//
+// Does three things:
+//   1. Registers the MCP server with Claude Code
+//   2. Installs the SKILL.md (agent trigger phrases)
+//   3. Configures the Stop hook (auto-capture sessions)
+//
+// After setup, every Claude Code session:
+//   - Auto-captures decisions, learnings, caveats to local memory
+//   - Agent auto-recalls past context at task start (via SKILL.md triggers)
+//   - "Use Linksee" in any prompt forces a recall
+//
+// Why: Competing memory tools (claude-mem, etc.) are one-install-and-done.
+// Our MCP approach gives more precision, but the setup was 3 manual steps.
+// This command eliminates that friction entirely.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const autoYes = args.includes('--yes') || args.includes('-y');
+const showHelp = args.includes('--help') || args.includes('-h');
+if (showHelp) {
+    console.log(`linksee-memory-setup — One-command setup for Linksee Memory
+
+Usage:
+  npx linksee-memory-setup          Interactive setup
+  npx linksee-memory-setup --yes    Accept all defaults, no prompts
+  npx linksee-memory-setup --dry-run Show what would happen
+
+What it does:
+  1. Registers linksee-memory MCP server with Claude Code
+  2. Installs SKILL.md (teaches the agent when to recall/remember)
+  3. Configures Stop hook (auto-captures every session)
+
+After setup, just chat with Claude Code normally.
+Add "Use Linksee" to any prompt to trigger memory recall.`);
+    process.exit(0);
+}
+// ── Constants ────────────────────────────────────────────
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, '.claude');
+const SETTINGS_PATH = join(CLAUDE_DIR, 'settings.json');
+const SKILL_DIR = join(CLAUDE_DIR, 'skills', 'linksee-memory');
+const SKILL_TARGET = join(SKILL_DIR, 'SKILL.md');
+const __filename = fileURLToPath(import.meta.url);
+const SKILL_SRC = join(dirname(__filename), '..', 'skill', 'SKILL.md');
+const SERVER_NAME = 'linksee';
+const MCP_COMMAND = `claude mcp add -s user ${SERVER_NAME} -- npx -y linksee-memory`;
+const HOOK_COMMAND = 'npx -y linksee-memory-sync';
+const CHECK = '\x1b[32m✓\x1b[0m';
+const SKIP = '\x1b[33m○\x1b[0m';
+const FAIL = '\x1b[31m✗\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+console.log('');
+console.log(`${BOLD}Linksee Memory Setup${RESET}`);
+console.log(`${DIM}Local-first cross-LLM memory · precision recall${RESET}`);
+console.log('');
+// ── Step 1: Register MCP server ──────────────────────────
+console.log(`${BOLD}[1/3]${RESET} Registering MCP server...`);
+let mcpAlreadyRegistered = false;
+try {
+    // Check if already registered by looking at settings.json or .claude.json
+    for (const confFile of [SETTINGS_PATH, join(HOME, '.claude.json')]) {
+        if (!existsSync(confFile))
+            continue;
+        try {
+            const conf = JSON.parse(readFileSync(confFile, 'utf8'));
+            if (conf?.mcpServers?.[SERVER_NAME]) {
+                mcpAlreadyRegistered = true;
+                break;
+            }
+        }
+        catch { /* ignore parse errors */ }
+    }
+}
+catch { /* ignore */ }
+if (mcpAlreadyRegistered) {
+    console.log(`  ${SKIP} MCP server '${SERVER_NAME}' already registered`);
+}
+else if (dryRun) {
+    console.log(`  ${DIM}[dry-run] Would run: ${MCP_COMMAND}${RESET}`);
+}
+else {
+    try {
+        // Check if 'claude' CLI is available
+        const which = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['claude'], {
+            encoding: 'utf8',
+            timeout: 5000,
+        });
+        if (which.status !== 0) {
+            console.log(`  ${FAIL} 'claude' CLI not found. Install Claude Code first:`);
+            console.log(`    https://docs.anthropic.com/en/docs/claude-code`);
+            console.log(`  ${DIM}Then run this setup again.${RESET}`);
+        }
+        else {
+            const r = spawnSync('claude', ['mcp', 'add', '-s', 'user', SERVER_NAME, '--', 'npx', '-y', 'linksee-memory'], {
+                encoding: 'utf8',
+                timeout: 15000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            if (r.status === 0) {
+                console.log(`  ${CHECK} MCP server registered as '${SERVER_NAME}'`);
+            }
+            else {
+                // May fail if already exists with different config
+                const stderr = (r.stderr || '').trim();
+                if (stderr.includes('already exists') || stderr.includes('already registered')) {
+                    console.log(`  ${SKIP} MCP server '${SERVER_NAME}' already registered`);
+                }
+                else {
+                    console.log(`  ${FAIL} Registration failed: ${stderr || 'unknown error'}`);
+                    console.log(`  ${DIM}Manual: ${MCP_COMMAND}${RESET}`);
+                }
+            }
+        }
+    }
+    catch (e) {
+        console.log(`  ${FAIL} Error: ${e?.message ?? e}`);
+        console.log(`  ${DIM}Manual: ${MCP_COMMAND}${RESET}`);
+    }
+}
+console.log('');
+// ── Step 2: Install SKILL.md ─────────────────────────────
+console.log(`${BOLD}[2/3]${RESET} Installing agent skill...`);
+if (!existsSync(SKILL_SRC)) {
+    console.log(`  ${FAIL} Bundled SKILL.md not found (packaging bug)`);
+    console.log(`  ${DIM}Expected at: ${SKILL_SRC}${RESET}`);
+}
+else if (dryRun) {
+    console.log(`  ${DIM}[dry-run] Would copy to: ${SKILL_TARGET}${RESET}`);
+}
+else {
+    mkdirSync(SKILL_DIR, { recursive: true });
+    let shouldWrite = true;
+    if (existsSync(SKILL_TARGET)) {
+        try {
+            const existing = readFileSync(SKILL_TARGET, 'utf8');
+            const bundled = readFileSync(SKILL_SRC, 'utf8');
+            if (existing === bundled) {
+                console.log(`  ${SKIP} Skill already installed and up to date`);
+                shouldWrite = false;
+            }
+            else {
+                // Newer version — overwrite
+                console.log(`  ${DIM}Updating to latest version...${RESET}`);
+            }
+        }
+        catch { /* fallthrough to write */ }
+    }
+    if (shouldWrite) {
+        copyFileSync(SKILL_SRC, SKILL_TARGET);
+        console.log(`  ${CHECK} Skill installed → ${SKILL_TARGET}`);
+    }
+}
+console.log('');
+// ── Step 3: Configure Stop hook ──────────────────────────
+console.log(`${BOLD}[3/3]${RESET} Configuring auto-capture hook...`);
+let settings = {};
+if (existsSync(SETTINGS_PATH)) {
+    try {
+        settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
+    }
+    catch {
+        console.log(`  ${FAIL} Could not parse ${SETTINGS_PATH}`);
+        settings = {};
+    }
+}
+// Check if hook already exists
+const stopHooks = settings?.hooks?.Stop ?? [];
+const alreadyHooked = stopHooks.some((entry) => entry.hooks?.some((h) => h.command?.includes('linksee-memory-sync')));
+if (alreadyHooked) {
+    console.log(`  ${SKIP} Stop hook already configured`);
+}
+else if (dryRun) {
+    console.log(`  ${DIM}[dry-run] Would add Stop hook to ${SETTINGS_PATH}${RESET}`);
+}
+else {
+    // Add hook
+    if (!settings.hooks)
+        settings.hooks = {};
+    if (!settings.hooks.Stop)
+        settings.hooks.Stop = [];
+    settings.hooks.Stop.push({
+        matcher: '',
+        hooks: [{ type: 'command', command: HOOK_COMMAND }],
+    });
+    mkdirSync(CLAUDE_DIR, { recursive: true });
+    writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf8');
+    console.log(`  ${CHECK} Stop hook added → ${SETTINGS_PATH}`);
+}
+console.log('');
+// ── Summary ──────────────────────────────────────────────
+console.log(`${BOLD}Setup complete!${RESET}`);
+console.log('');
+console.log('How it works:');
+console.log(`  ${DIM}• Every session is auto-captured (decisions, caveats, learnings)${RESET}`);
+console.log(`  ${DIM}• Agent auto-recalls past context when starting a task${RESET}`);
+console.log(`  ${DIM}• Memory is local-first (nothing leaves your machine)${RESET}`);
+console.log(`  ${DIM}• Works across Claude Code, Cursor, ChatGPT (cross-LLM)${RESET}`);
+console.log('');
+console.log('Test by asking:');
+console.log(`  ${BOLD}"How did we solve this before?"${RESET}`);
+console.log(`  ${BOLD}"Same error again"${RESET}`);
+console.log(`  ${BOLD}"Remember: I prefer TypeScript over JavaScript"${RESET}`);
+console.log(`  ${BOLD}「前にこの問題どう解決したっけ」${RESET}`);
+console.log('');
+console.log(`Or add ${BOLD}"Use Linksee"${RESET} to any prompt to trigger memory recall.`);
+console.log('');
+//# sourceMappingURL=setup.js.map

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