linksee-memory 0.10.0 → 0.11.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Synapse Arrows PTE. LTD.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Synapse Arrows PTE. LTD.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,9 +2,9 @@
 
 > **Your agent forgets everything when a session ends. Worse — it silently drifts from what you decided last week.**
 >
-> Local-first cross-LLM memory MCP — one SQLite file that **Claude Code, Cursor, Windsurf, OpenAI Codex, and Gemini CLI** all read from. Not just "what happened" but **WHY** it happened: 6-layer structured memory with precision recall, **plus drift detection that catches when reality diverges from your decisions**.
+> **Linksee Memory catches when your project drifts from its own decisions** — the option abandoned at a fork, the pipeline that quietly stalled, the code that contradicts what you agreed — and a re-injection guard re-surfaces the locked decision **before** the agent acts. Rules you've explicitly hardened get blocked.
 >
-> Memory is the entry point. Drift detection is the real value.
+> Underneath sits a local-first cross-LLM memory MCP — one SQLite file that **Claude Code, Cursor, Windsurf, OpenAI Codex, and Gemini CLI** all read from. Not just "what happened" but **WHY**: 6-layer structured memory with precision recall and an AST-aware diff cache (50–99% token savings on re-reads).
 >
 > `npx linksee-memory-setup` — one command, done.
 
@@ -15,6 +15,16 @@
 
 🌐 **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)
 
+## 🪄 Three spells to remember
+
+| Say this | What happens |
+|---|---|
+| **"use linksee"** ・「リンクシーして」 | Recalls relevant memories before acting |
+| **"linksee this"** ・「これ覚えて」 | Saves the decision / lesson right now |
+| **"what's drifting?"** ・「ズレてない？」 | Reconciles reality against your locked decisions |
+
+> Make it automatic: add **"Use Linksee Memory"** to your system prompt / `CLAUDE.md`.
+
 ## 📣 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)
@@ -29,6 +39,24 @@
 
 ## 🎬 See it in action
 
+**Drift, caught.** Decisions don't survive session boundaries — but their consequences do. Ask any session:
+
+```
+You:    What's drifting right now?
+Agent:  [calls drift_status]
+
+        28 anchors: ⚪ 1 held · 🔵 27 aligned
+
+        Needs attention:
+        ⚪ HELD — "Focus on 4 areas: Recipe layer, agent-native API,
+           Japanese market, Agent Insights"
+           ↻ Reopens 2026-07-04
+
+        Everything else is aligned — no unaccounted divergence.
+```
+
+**The memory underneath.** Drift detection only works because the *why* survives the session boundary:
+
 **Without linksee-memory** — Monday morning, new Claude session:
 
 ```
@@ -59,73 +87,11 @@ That single `caveat` memory is what separates "flat fact storage" from "the agen
 
 ---
 
-## 🧠 The 6-layer structure
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 🎯 goal           ← what the user is working toward         │
-├─────────────────────────────────────────────────────────────┤
-│ 🧭 context        ← why this, why now — constraints, people │
-├─────────────────────────────────────────────────────────────┤
-│ 💗 emotion        ← user tone signals (frustration, etc.)   │
-├─────────────────────────────────────────────────────────────┤
-│ 🛠  implementation ← how it was done (+ what failed)         │
-├─────────────────────────────────────────────────────────────┤
-│ ⚠️  caveat         ← "never do this again" · auto-protected │
-├─────────────────────────────────────────────────────────────┤
-│ 🌱 learning       ← patterns distilled from cold memories   │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-           Ranked recall via relevance × heat × momentum × importance
-                  Returns match_reasons explaining each hit
-```
-
-Every memory is tagged with **exactly one layer**. `caveat`-layer entries are protected from auto-forgetting. Cold low-importance memories are auto-consolidated into `learning` entries on server startup.
-
----
-
-## What it does
-
-Most "agent memory" services (Mem0, Letta, Zep) save a flat list of facts. Then the agent looks at "edited file X 30 times" and has no idea why. **linksee-memory keeps the WHY.**
-
-It is a Model Context Protocol (MCP) server with **7 tools** that gives any AI agent structured memory + drift detection:
-
-| | Mem0 / Letta / Zep | Claude Code auto-memory | linksee-memory |
-|---|---|---|---|
-| Cross-agent | △ (cloud) | ❌ Claude only | ✅ single SQLite file |
-| 6-layer WHY structure | ❌ flat | ❌ flat markdown | ✅ goal / context / emotion / impl / caveat / learning |
-| **Drift detection** | ❌ | ❌ | ✅ intent ↔ reality divergence tracking |
-| File diff cache | ❌ | ❌ | ✅ AST-aware, 50-99% token savings on re-reads |
-| Active forgetting | △ | ❌ | ✅ Ebbinghaus curve, caveat layer protected |
-| Local-first / private | ❌ | ✅ | ✅ |
-
-## Four 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, Windsurf, OpenAI Codex, Gemini CLI.
-3. **WHY-first structured memory** — six explicit layers (`goal` / `context` / `emotion` / `implementation` / `caveat` / `learning`). Solves "flat fact memory is useless without goals".
-4. **Drift detection** — declare decisions as anchors, then the engine automatically detects when committed reality diverges from stated intent. Think "Datadog for product decisions" — unaccounted divergences surface as drift, intentional evolution (recorded as supersede/fix) stays quiet.
-
 ## 🔍 Drift Detection — "Intent Datadog"
 
 Most teams make decisions, then forget them. The agent from last week decided "we'll use FTS5 instead of vector search" — but this week a new session installs `pgvector` without knowing why that was rejected. **That's drift.** Not a bug. Not malice. Just forgotten context.
 
-Linksee Memory's drift detection catches this:
-
-```
-You:    What's drifting right now?
-Agent:  [calls drift_status]
-
-        28 anchors: ⚪ 1 held · 🔵 27 aligned
-
-        Needs attention:
-        ⚪ HELD — "Focus on 4 areas: Recipe layer, agent-native API,
-           Japanese market, Agent Insights"
-           ↻ Reopens 2026-07-04
-
-        Everything else is aligned — no unaccounted divergence.
-```
+Memory tools remember what you did. Nothing notices when you drift from what you decided — that's the layer Linksee Memory adds. Think **"Datadog for product decisions"**: unaccounted divergences surface as drift, intentional evolution (recorded as supersede/fix) stays quiet.
 
 ### How it works
 
@@ -136,7 +102,7 @@ Agent:  [calls drift_status]
    - 🟡 **Review** — a soft signal awaits your decision
    - ⚪ **Held** — you acknowledged the gap, parked it with a review date
    - 🔵 **Aligned** — reality matches intent, or a recorded resolution explains the change
-4. **Resolve** with `fix`, `supersede`, `acknowledge`, or `dismiss`
+4. **Resolve** with `fix`, `supersede`, `acknowledge`, or `dismiss` — plus two gates: `harden` (PreToolUse will block) and `soften` (back to a warning)
 
 The **make-or-break rule**: a divergence accounted for by a recorded resolution (supersede/fix/acknowledge) is NOT drift. Only unaccounted gaps are flagged. This means intentional evolution stays quiet while silent abandonment gets caught.
 
@@ -153,6 +119,57 @@ Anchors are classified into four species with different display formats:
 
 ---
 
+<a id="the-map"></a>
+
+## 🗺️ The Map — `linksee-memory-map`
+
+Drift detection (above) checks individual anchors. The **Map** lifts it to the whole product: a `map.yaml` describing how value reaches your user (`discover → understand → try → adopt → retain → monetize → expand`), with typed dependencies between the pieces — README, npm listing, onboarding, the engine that powers them. The reconciler checks that map against your real code, and the CLI answers the question an engineer actually has:
+
+> *I'm touching this file — where is it on the map, and what else must move?*
+
+**1. Where am I?** — locate a file (or, with no argument, infer from your recent edits):
+
+```
+$ linksee-memory-map where README.md
+"README.md" belongs to this Map node:
+
+  readme  [understand]  convergence
+    changes ripple to:
+      must fix together (hard):  lp, docs-site
+      should align (soft):       onboarding, client-configs
+      fyi (may ripple):          telemetry-contract
+```
+
+The blast radius is **graded** — `must fix together` vs `should align` vs `fyi` — so a wide ripple isn't flat noise.
+
+**2. Why is it in this state?** — the diagnosis, with file:line evidence:
+
+```
+$ linksee-memory-map explain readme
+
+STATUS
+  declared: healthy (active)
+  reality:  implemented / matches
+  verdict:  declared and reality agree (verified)
+
+EVIDENCE
+  ✓ README's Tools section lists where_am_i
+      README.md:424 — found "where_am_i" in section "Tools"
+```
+
+Declared state and the reality verdict are shown **separately** — a hand-declared `suspect` the scanner refutes reads as *"declared suspect, refuted by reality (→ convergence)"*, not a confusing mix.
+
+**3. Whole-project triage:** `linksee-memory-map status` — a health %, what is *fixable now in code* vs *external checks*, and any deferral with no expiry (so "accounted-for" can't quietly become a drift graveyard).
+
+**How it works**
+- **`map.yaml`** (repo root) is the desired-state source of truth: a journey spine × surface/implementation layers × typed edges (`must-stay-consistent-with` / `should-align-with` / `realizes`).
+- **`reconcile`** checks each node's declared `reality` against the code (`signal` / `regex` / `section_contains` / file checks) and overlays a verdict — reality overrides what you hand-declared, with evidence.
+- `where_am_i` is also an **MCP tool**, so a coding agent can re-anchor itself mid-task.
+
+Commands: `where` · `affects` · `explain` · `status` · `next` · `reconcile` · `inspect --json` · `blueprint`. Add `--lang ja` for Japanese labels.
+
+---
+
 <a id="reinjection-guard"></a>
 
 ## 🛡 Re-injection Guard — enforce decisions *before* the action
@@ -201,6 +218,55 @@ It's **project-scoped on purpose** — the guard enforces *this* repo's decision
 
 ---
 
+## What it does
+
+Most "agent memory" services (Mem0, Letta, Zep) save a flat list of facts. Then the agent looks at "edited file X 30 times" and has no idea why. And none of them notice when this week's work contradicts last week's decision. **linksee-memory keeps the WHY — and watches the drift.**
+
+It is a Model Context Protocol (MCP) server with **11 tools** that gives any AI agent structured memory + drift detection:
+
+| | Mem0 / Letta / Zep | Claude Code auto-memory | linksee-memory |
+|---|---|---|---|
+| **Drift detection** | ❌ | ❌ | ✅ intent ↔ reality divergence tracking |
+| Cross-agent | △ (cloud) | ❌ Claude only | ✅ single SQLite file |
+| 6-layer WHY structure | ❌ flat | ❌ flat markdown | ✅ goal / context / emotion / impl / caveat / learning |
+| File diff cache | ❌ | ❌ | ✅ AST-aware, 50-99% token savings on re-reads |
+| Active forgetting | △ | ❌ | ✅ Ebbinghaus curve, caveat layer protected |
+| Local-first / private | ❌ | ✅ | ✅ |
+
+## Four pillars
+
+1. **Drift detection** — declare decisions as anchors, then the engine automatically detects when committed reality diverges from stated intent. Think "Datadog for product decisions" — unaccounted divergences surface as drift, intentional evolution (recorded as supersede/fix) stays quiet.
+2. **Cross-agent portability** — single SQLite file at `~/.linksee-memory/memory.db`. Same brain for Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI.
+3. **WHY-first structured memory** — six explicit layers (`goal` / `context` / `emotion` / `implementation` / `caveat` / `learning`). Solves "flat fact memory is useless without goals".
+4. **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.**
+
+## 🧠 The 6-layer structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🎯 goal           ← what the user is working toward         │
+├─────────────────────────────────────────────────────────────┤
+│ 🧭 context        ← why this, why now — constraints, people │
+├─────────────────────────────────────────────────────────────┤
+│ 💗 emotion        ← user tone signals (frustration, etc.)   │
+├─────────────────────────────────────────────────────────────┤
+│ 🛠  implementation ← how it was done (+ what failed)         │
+├─────────────────────────────────────────────────────────────┤
+│ ⚠️  caveat         ← "never do this again" · auto-protected │
+├─────────────────────────────────────────────────────────────┤
+│ 🌱 learning       ← patterns distilled from cold memories   │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+           Ranked recall via relevance × heat × momentum × importance
+                  Returns match_reasons explaining each hit
+```
+
+Every memory is tagged with **exactly one layer**. `caveat`-layer entries are protected from auto-forgetting. Cold low-importance memories are auto-consolidated into `learning` entries on server startup.
+
+---
+
+
 ## Quick Start — One Command
 
 ```bash
@@ -388,7 +454,7 @@ Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env v
 
 </details>
 
-## 7 Tools (v0.8)
+## 11 Tools
 
 ### Memory tools
 
@@ -406,8 +472,17 @@ Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env v
 | `check_decision` | **Deep-dive into a specific decision.** Returns the full context: what was decided, why, what reality says, pending candidates, and drift edges. |
 | `declare_anchor` | **Record a decision as a truth-map anchor.** The drift detector checks these against committed reality. Supports v9 fields (domain, confidence, lifecycle, review_after). |
 | `resolve_drift` | **Close the loop.** Record a resolution: `fix` (reality now matches), `supersede` (intent evolved), `acknowledge` (parking with review date), or `dismiss` (false positive). |
+| `where_am_i` | **"Where on the Map am I, and what else does this touch?"** Locates the current topic/file on the Current Truth Map and returns its journey stage + blast radius (the `must-stay-consistent-with` / `should-align-with` dependents) + the decision behind it. The per-turn re-anchor that stops you optimizing one node while silently breaking its neighbors. |
+
+### Fork-point tools (v0.10)
 
-Previous versions exposed 3 tools — v0.8.0 added 4 drift tools that let agents query and act on product-level intent ↔ reality divergence. The memory tools are unchanged.
+| Tool | What it does |
+|---|---|
+| `flag_proposals` | **Record orphaned proposals** — options you presented that the user never addressed. Conversations are tree-shaped but experienced linearly; the branches nobody engaged with become unresolved fork points that both you and the user lose track of. |
+| `dream` | **Consolidate orphaned proposals against the North Star.** Returns the project's direction/goals/ICP alongside unresolved proposals; the evaluating agent decides per candidate: surface (genuinely important fork) or dismiss (outdated / irrelevant / implicitly resolved). |
+| `resolve_proposal` | **Record the verdict** for each dreamed proposal: `surface` (keep visible on the dashboard for human decision) or `dismiss` (remove from the dashboard). |
+
+Previous versions exposed 3 tools — v0.8.0 added 4 drift tools that let agents query and act on product-level intent ↔ reality divergence; v0.10 added the fork-point trio for orphaned-proposal triage; `where_am_i` adds the Current Truth Map's per-turn positional re-anchor. The memory tools are unchanged.
 
 ### CLI utilities
 
@@ -700,6 +775,15 @@ After install, in a new Claude session ask: *"Can you remember that I prefer Typ
 
 ## Changelog
 
+### v0.11.0 — The Map: `where_am_i` + `linksee-memory-map` (2026-06-15)
+
+**Memory is the entry point; the product map is the new surface.** Drift detection grows up from individual anchors into a whole-product map you navigate from the CLI.
+
+- **`where_am_i`** (11th MCP tool) — locate the current topic/file on the Current Truth Map and get its blast radius. Call it with no args to auto-locate from your recent edits.
+- **`linksee-memory-map`** CLI — `where` · `affects` · `explain` · `status` · `next` · `reconcile` · `inspect --json` · `blueprint`. A `map.yaml` (git source of truth) describes how value reaches your user; the reconciler checks it against your code with file:line evidence. Bilingual: add `--lang ja`.
+- Graded blast radius (`must fix together` / `should align` / `fyi`), declared-vs-reality verdicts, and an anti-graveyard guard for accounted-for drift.
+- Per-project keys so the Map handles many projects at once.
+
 ### v0.8.0 — Drift Detection MCP Tools (2026-06-08)
 
 **3 tools → 7 tools.** The biggest update since launch — agents can now detect, query, and resolve intent ↔ reality drift.

package/dist/bin/import-sessions.js

@@ -16,10 +16,10 @@ 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:
-  node dist/bin/import-sessions.js [--dry-run] [--all | <projectDir> [<projectDir> ...]]
-    --all         : scan every project under ~/.claude/projects/*
-    --dry-run     : parse + extract but do not write to DB
+    console.log(`Usage:
+  node dist/bin/import-sessions.js [--dry-run] [--all | <projectDir> [<projectDir> ...]]
+    --all         : scan every project under ~/.claude/projects/*
+    --dry-run     : parse + extract but do not write to DB
     projectDir    : absolute path to a project dir (must contain *.jsonl files)`);
 }
 function collectJsonlFiles(projectDir) {
@@ -48,7 +48,7 @@ function collectJsonlFiles(projectDir) {
 function wipeSession(db, sessionId) {
     const sidNeedle = `%"session_id":"${sessionId}"%`;
     const editDel = db.prepare('DELETE FROM session_file_edits WHERE session_id = ?').run(sessionId);
-    const memDel = db.prepare(`DELETE FROM memories WHERE source LIKE ?
+    const memDel = db.prepare(`DELETE FROM memories WHERE source LIKE ?
        AND (NOT json_valid(content) OR COALESCE(json_extract(content, '$.distilled'), 0) != 1)`).run(sidNeedle);
     const evtDel = db.prepare('DELETE FROM events WHERE payload LIKE ?').run(sidNeedle);
     return { memories: memDel.changes, edits: editDel.changes, events: evtDel.changes };
@@ -56,7 +56,7 @@ function wipeSession(db, sessionId) {
 // A re-extracted memory must NOT be re-inserted if its source turn already has a surviving
 // distilled rewrite (matched by turn_uuid — the stable key shared by raw and rewrite).
 function makeDistilledTurnSet(db, sessionId) {
-    const rows = db.prepare(`SELECT source FROM memories
+    const rows = db.prepare(`SELECT source FROM memories
       WHERE source LIKE ? AND json_valid(content) AND json_extract(content, '$.distilled') = 1`).all(`%"session_id":"${sessionId}"%`);
     const set = new Set();
     for (const r of rows) {

package/dist/bin/install-skill.js

@@ -21,20 +21,20 @@ const force = args.includes('--force') || args.includes('-f');
 const dryRun = args.includes('--dry-run');
 const showHelp = args.includes('--help') || args.includes('-h');
 if (showHelp) {
-    console.log(`linksee-memory-install-skill
-
-Install the linksee-memory Claude Code skill into ~/.claude/skills/linksee-memory/.
-
-Options:
-  --force, -f    Overwrite an existing skill file
-  --dry-run      Show what would happen without writing
-  --help, -h     This message
-
-After installation, ensure the MCP server is registered in Claude Code:
-  claude mcp add -s user linksee -- npx -y linksee-memory
-
-The skill expects tool names of the form mcp__linksee__*. If you register the
-server under a different name (e.g. "linksee-memory"), edit the skill file
+    console.log(`linksee-memory-install-skill
+
+Install the linksee-memory Claude Code skill into ~/.claude/skills/linksee-memory/.
+
+Options:
+  --force, -f    Overwrite an existing skill file
+  --dry-run      Show what would happen without writing
+  --help, -h     This message
+
+After installation, ensure the MCP server is registered in Claude Code:
+  claude mcp add -s user linksee -- npx -y linksee-memory
+
+The skill expects tool names of the form mcp__linksee__*. If you register the
+server under a different name (e.g. "linksee-memory"), edit the skill file
 afterwards.`);
     process.exit(0);
 }

package/dist/bin/map-import.d.ts

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