linksee-memory 0.11.1 → 0.11.3

package/README.md

@@ -419,12 +419,49 @@ Add to `~/.gemini/settings.json`:
 
 </details>
 
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add the same stdio command to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "linksee": {
+      "command": "npx",
+      "args": ["-y", "linksee-memory"]
+    }
+  }
+}
+```
+
+Config file: macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`. Restart Claude Desktop.
+
+</details>
+
 All editors share the same `~/.linksee-memory/memory.db`. A decision made in Claude Code is recalled in Cursor. A caveat recorded in Windsurf prevents the same mistake in Codex.
 
 ### Database location
 
 Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env var.
 
+### Uninstall
+
+```bash
+# 1. Remove the MCP server registration
+claude mcp remove linksee
+
+# 2. Remove the hooks from settings.json (edit the file, delete the linksee entries):
+#    ~/.claude/settings.json          → the Stop hook running "npx -y linksee-memory sync"
+#    <project>/.claude/settings.json  → the SessionStart/PreToolUse hooks running "npx -y linksee-memory guard"
+
+# 3. Remove the installed skill and all local memory (optional)
+rm -rf ~/.claude/skills/linksee-memory
+rm -rf ~/.linksee-memory   # deletes all stored memory — nothing is kept anywhere else
+```
+
+Nothing ever leaves your machine, so step 3 fully erases everything Linksee stored.
+
 ## What's new in v0.9
 
 | Feature | Detail |
@@ -576,6 +613,20 @@ Claude Code ships a built-in memory feature at `~/.claude/projects/<path>/memory
 
 Use both.
 
+## Security & privacy
+
+linksee-memory runs locally and is built to read — and send — as little as possible.
+
+- **Local-first.** Memory is one SQLite file at `~/.linksee-memory/memory.db`. No account, no cloud, no API key.
+- **Telemetry is opt-in and OFF by default.** Nothing is sent unless you set `LINKSEE_TELEMETRY=basic`. Even then it never sends your source code, file contents, prompts, conversation, entity/project names, or the memory DB — only anonymous counters ([details](#telemetry-opt-in-off-by-default)).
+- **No automatic repo crawling.** linksee reads: memory you explicitly save, your `map.yaml`, the specific files a map reality-check points at, the local SQLite DB, and — when the Stop hook fires — your Claude Code session transcript (locally, to capture what happened). It does **not** crawl your repo, read `.env`/secrets/`node_modules`, or touch your home directory on its own.
+- **Clean MCP transport.** The server writes only JSON-RPC to stdout; all logs go to stderr.
+- **Hooks are documented and removable.** `setup` adds a Stop hook (session capture) and an optional guard hook. They make no network calls by default, are time-bounded, fail-open (a hook error never breaks your session), and are listed under [Uninstall](#uninstall).
+- **No shell-injection surface.** Subcommands run via `spawn` with array args and `shell: false`, from a fixed allowlist; `map.yaml` is parsed with the safe `yaml` parser (no arbitrary tag execution).
+- **Supply chain.** MIT, published from a single owner. `npx -y linksee-memory` runs the published package — pin a version in CI if you need reproducibility.
+
+Found a security issue? See [SECURITY.md](SECURITY.md).
+
 ## Telemetry (opt-in, off by default)
 
 linksee-memory ships with **opt-in** anonymous telemetry that helps us understand which MCP servers and workflows actually work in the wild. **Nothing is sent unless you explicitly enable it.** No conversation content, no file content, no entity names, no project paths — ever.
@@ -787,6 +838,16 @@ After install, in a new Claude session ask: *"Can you remember that I prefer Typ
 
 ## Changelog
 
+### v0.11.3 — Robustness + MCP hygiene (2026-06-16)
+
+- **Corrupt-database recovery:** if `~/.linksee-memory/memory.db` is unreadable, linksee preserves it as `memory.db.corrupt-<timestamp>` and starts a fresh one (with a clear message) instead of crashing with a raw SQLite error. Old memories stay recoverable in the backup.
+- **`recall` tool description** no longer suggests editing your system prompt — cleaner MCP citizenship.
+
+### v0.11.2 — More cold-start hardening (2026-06-16)
+
+- **`stats` works on a fresh database** instead of crashing with `no such table` — it ensures the schema exists first (it may be the first command a new user runs).
+- **`map --help`** prints usage instead of trying to import a map.
+
 ### v0.11.1 — Cold-start fixes (2026-06-16)
 
 - **Run any CLI through the package name:** `npx -y linksee-memory setup` (and `map`, `sync`, `guard`, `stats`, `import`, `install-skill`). A fresh user couldn't reach the standalone bins (`linksee-memory-setup`, …) via `npx` — npx resolves package names, not sibling bin names — so the one-command install 404'd. The main bin now dispatches subcommands; the standalone bins remain as aliases.

package/dist/bin/map-import.js

@@ -39,6 +39,20 @@ for (let i = 0; i < argv.length; i++) {
 const sub = positionals[0] ?? 'import';
 const arg1 = positionals[1]; // the node-id / file / topic for explain|blast|affects|where
 const mapPath = flagValue(argv, 'file', join(process.cwd(), 'map.yaml'));
+if (argv.includes('--help') || argv.includes('-h') || sub === 'help') {
+    process.stdout.write(`linksee-memory map — navigate your product map (map.yaml) and catch drift\n\n` +
+        `Usage: npx -y linksee-memory map <command> [args]\n\n` +
+        `  where [<file>]    where am I? (no arg = infer from recent edits) → node + what it affects\n` +
+        `  explain <node>    why this status? — declared vs reality + file:line evidence + fix\n` +
+        `  affects <node>    what to change together if you touch this node\n` +
+        `  status            whole-project health % + what needs attention\n` +
+        `  next              the prioritized next fix candidate(s)\n` +
+        `  reconcile         re-check the map against the real code/files\n` +
+        `  inspect --json    machine-readable dump (CI / tooling)\n` +
+        `  blueprint         stage x node board (colors = live verdict)\n\n` +
+        `Flags: --file <map.yaml>  --root <repo>  --lang ja\n`);
+    process.exit(0);
+}
 const db = openDb();
 runMigrations(db);
 // Graceful exit when there's no map yet (the cold-user state) — never a raw stack trace.

package/dist/bin/stats.js

@@ -1,13 +1,13 @@
 #!/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
+//   npx -y linksee-memory stats
+//   npx -y linksee-memory stats --json
+//   npx -y linksee-memory stats --per-entity 10
 //
 // Safe to run anytime (read-only).
 import { statSync } from 'node:fs';
-import { openDb, getDbPath } from '../db/migrate.js';
+import { openDb, runMigrations, getDbPath } from '../db/migrate.js';
 function parseArgs() {
     const argv = process.argv.slice(2);
     const a = { json: false, perEntity: 5, help: false };
@@ -68,6 +68,7 @@ function main() {
     }
     catch { /* no db yet */ }
     const db = openDb();
+    runMigrations(db); // ensure schema exists — `stats` may be the first command a fresh user runs
     const counts = {
         entities: db.prepare('SELECT COUNT(*) as c FROM entities').get().c,
         memories: db.prepare('SELECT COUNT(*) as c FROM memories').get().c,

package/dist/db/migrate.js

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
 import { readFileSync } from 'node:fs';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, renameSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -10,12 +10,49 @@ const DB_PATH = join(DEFAULT_DB_DIR, 'memory.db');
 export function getDbPath() {
     return DB_PATH;
 }
+function openAt(path) {
+    const db = new Database(path);
+    try {
+        db.pragma('journal_mode = WAL'); // first real read of the file header — throws if it isn't a DB
+        db.pragma('foreign_keys = ON');
+        return db;
+    }
+    catch (e) {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ } // release the handle so a corrupt file can be renamed (Windows locks it otherwise)
+        throw e;
+    }
+}
 export function openDb() {
     mkdirSync(DEFAULT_DB_DIR, { recursive: true });
-    const db = new Database(DB_PATH);
-    db.pragma('journal_mode = WAL');
-    db.pragma('foreign_keys = ON');
-    return db;
+    try {
+        return openAt(DB_PATH);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // A corrupt / non-database file throws on the first pragma. Don't crash with a raw
+        // stack trace: preserve the bad file (so it can be recovered) and start a fresh DB.
+        if (/not a database|file is encrypted|malformed|disk image/i.test(msg) && existsSync(DB_PATH)) {
+            const backup = `${DB_PATH}.corrupt-${Date.now()}`;
+            try {
+                renameSync(DB_PATH, backup);
+            }
+            catch { /* best effort */ }
+            for (const ext of ['-wal', '-shm']) {
+                try {
+                    if (existsSync(DB_PATH + ext))
+                        renameSync(DB_PATH + ext, backup + ext);
+                }
+                catch { /* ignore */ }
+            }
+            process.stderr.write(`[linksee-memory] the memory database was unreadable (${msg}). ` +
+                `Moved it to ${backup} and started a fresh one — your old memories are preserved there for recovery.\n`);
+            return openAt(DB_PATH);
+        }
+        throw err; // not a corruption we recognize — surface it
+    }
 }
 export function runMigrations(db) {
     const __filename = fileURLToPath(import.meta.url);

package/dist/mcp/server.js

@@ -153,7 +153,7 @@ const TOOLS = [
     },
     {
         name: 'recall',
-        description: 'Your persistent memory across all AI tools. CALL THIS BEFORE STARTING ANY TASK to check for past caveats (pain records), decisions, and learnings — prevents repeating mistakes across sessions.\n\nTypical usage: recall({ query: "keywords" }) for search, recall({ path: "file.ts" }) for file history, recall() for overview.\n\nWHEN TO CALL:\n• Before starting any new task or touching a file\n• When the user mentions "before" / "前に" / "last time" / "remember when"\n• When an error occurs — check if you\'ve seen it before\n• When making a decision — check for prior decisions on the same topic\n\nTHREE MODES (auto-detected):\n• Search (default): provide query → returns memories ranked by relevance + heat\n• File history: provide path → returns complete edit history with user-intent context\n• Overview: omit all params → returns entity list sorted by momentum\n\nTip: If this is a fresh session, suggest the user add "Use Linksee Memory" to their system prompt for persistent cross-session memory.\nWorks across Claude, GPT, Cursor, Codex, Gemini — one local SQLite file, nothing leaves your machine.',
+        description: 'Your persistent memory across all AI tools. CALL THIS BEFORE STARTING ANY TASK to check for past caveats (pain records), decisions, and learnings — prevents repeating mistakes across sessions.\n\nTypical usage: recall({ query: "keywords" }) for search, recall({ path: "file.ts" }) for file history, recall() for overview.\n\nWHEN TO CALL:\n• Before starting any new task or touching a file\n• When the user mentions "before" / "前に" / "last time" / "remember when"\n• When an error occurs — check if you\'ve seen it before\n• When making a decision — check for prior decisions on the same topic\n\nTHREE MODES (auto-detected):\n• Search (default): provide query → returns memories ranked by relevance + heat\n• File history: provide path → returns complete edit history with user-intent context\n• Overview: omit all params → returns entity list sorted by momentum\n\nWorks across Claude, GPT, Cursor, Codex, Gemini — one local SQLite file, nothing leaves your machine.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "mcpName": "io.github.michielinksee/linksee-memory",
   "description": "Local-first agent memory MCP — cross-agent brain with drift detection, 6-layer structured memory + token-saving file diff cache",
   "type": "module",