linksee-memory 0.10.0 → 0.11.1

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,11 +2,11 @@
 
 > **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.
+> `npx -y linksee-memory setup` — one command, done.
 
 [![npm](https://img.shields.io/npm/v/linksee-memory.svg)](https://www.npmjs.com/package/linksee-memory)
 [![license](https://img.shields.io/npm/l/linksee-memory.svg)](./LICENSE)
@@ -14,6 +14,33 @@
 [![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 / OpenAI Codex / Gemini CLI)
+📖 **Docs**: [docs.linksee.app](https://docs.linksee.app) — full reference: the product map & drift, install, and all 11 tools
+
+## 🪄 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`.
+
+## 🗺️ Not just memory — a product map
+
+Memory is the entry point. Tie it to a `map.yaml` of how your product fits together, and the `linksee-memory map` CLI catches drift with file:line evidence:
+
+![linksee-memory-map catching doc/code drift in 30 seconds](demo/where-demo.gif)
+
+**The 30-second demo above:** the README says `--export`. The code doesn't. Linksee catches it — and shows what else a change would touch.
+
+```bash
+npx -y linksee-memory map where README.md   # this file belongs to the README node — and what it touches
+npx -y linksee-memory map explain readme    # README promises --export; the code doesn't implement it — drift, with evidence
+npx -y linksee-memory map affects readme    # changing the README also touches docs, the CLI help, and the npm listing
+```
+
+→ see [The Map](#the-map) for the full flow.
 
 ## 📣 As featured on
 
@@ -29,6 +56,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 +104,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 +119,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 +136,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):
+
+```
+$ npx -y 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:
+
+```
+$ npx -y 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:** `npx -y 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
@@ -170,7 +204,7 @@ It is **fail-open by construction**: any parse / DB / logic error surfaces nothi
 
 ### Enable it
 
-`npx linksee-memory-setup` offers to wire this into your **project's** `.claude/settings.json` (Step 4). To do it by hand, drop this block into `.claude/settings.json` at your project root — it points at the globally-installed `linksee-memory-guard` bin, so no build step is needed:
+`npx -y linksee-memory setup` offers to wire this into your **project's** `.claude/settings.json` (Step 4). To do it by hand, drop this block into `.claude/settings.json` at your project root — it points at the globally-installed `linksee-memory-guard` bin, so no build step is needed:
 
 ```json
 {
@@ -179,7 +213,7 @@ It is **fail-open by construction**: any parse / DB / logic error surfaces nothi
       {
         "matcher": "startup|resume|compact",
         "hooks": [
-          { "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 15 }
+          { "type": "command", "command": "npx -y linksee-memory guard", "timeout": 15 }
         ]
       }
     ],
@@ -187,7 +221,7 @@ It is **fail-open by construction**: any parse / DB / logic error surfaces nothi
       {
         "matcher": "Edit|Write|Bash",
         "hooks": [
-          { "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 8 }
+          { "type": "command", "command": "npx -y linksee-memory guard", "timeout": 8 }
         ]
       }
     ]
@@ -197,14 +231,63 @@ It is **fail-open by construction**: any parse / DB / logic error surfaces nothi
 
 It's **project-scoped on purpose** — the guard enforces *this* repo's decisions, and you opt in per project rather than letting it deny tool calls everywhere (the Stop hook from setup, by contrast, is user-global). Declare what it should watch with `declare_anchor(...)`; set `card_policy.gate_mode:'hard'` on an anchor to make a contradiction **block** instead of just warn (the soft default only re-injects). Anchors that are stale (`at_risk`), superseded, or card-disabled never gate.
 
-> Developing linksee-memory itself? The repo dogfoods the guard via a (gitignored) `.claude/settings.json` that points at the local build (`node ${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js`) so it runs against your uncommitted changes. End-user projects should use the published `npx -y linksee-memory-guard` form above.
+> Developing linksee-memory itself? The repo dogfoods the guard via a (gitignored) `.claude/settings.json` that points at the local build (`node ${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js`) so it runs against your uncommitted changes. End-user projects should use the published `npx -y linksee-memory guard` form above.
 
 ---
 
+## 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
-npx linksee-memory-setup
+npx -y linksee-memory setup
 ```
 
 This does everything:
@@ -231,7 +314,7 @@ Tools appear as `mcp__linksee__remember`, `mcp__linksee__recall`, `mcp__linksee_
 **Install the skill (auto-invocation):**
 
 ```bash
-npx -y linksee-memory-install-skill
+npx -y linksee-memory install-skill
 ```
 
 Copies `SKILL.md` to `~/.claude/skills/linksee-memory/`. Agent auto-fires on phrases like "前に…", "また同じエラー", "覚えておいて", new task starts, file edits, etc.
@@ -247,7 +330,7 @@ Add to `~/.claude/settings.json`:
       {
         "matcher": "",
         "hooks": [
-          { "type": "command", "command": "npx -y linksee-memory-sync" }
+          { "type": "command", "command": "npx -y linksee-memory sync" }
         ]
       }
     ]
@@ -305,20 +388,15 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 <summary><strong>OpenAI Codex CLI</strong></summary>
 
 ```bash
-codex --mcp-server "npx -y linksee-memory"
+codex mcp add linksee -- npx -y linksee-memory
 ```
 
-Or add to `~/.codex/config.json`:
+Or add to `~/.codex/config.toml`:
 
-```json
-{
-  "mcpServers": {
-    "linksee": {
-      "command": "npx",
-      "args": ["-y", "linksee-memory"]
-    }
-  }
-}
+```toml
+[mcp_servers.linksee]
+command = "npx"
+args = ["-y", "linksee-memory"]
 ```
 
 </details>
@@ -381,14 +459,14 @@ Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env v
 
 | Feature | Detail |
 |---|---|
-| **One-command setup** | `npx linksee-memory-setup` — registers MCP server, installs skill, configures auto-capture hook. One command instead of three. |
+| **One-command setup** | `npx -y linksee-memory setup` — registers MCP server, installs skill, configures auto-capture hook. One command instead of three. |
 | **Structured memory v2** | 3-axis classification (altitude × type × state) for every memory. Auto-extraction from sessions produces machine-scannable JSON, not raw chat dumps. |
 | **Precision recall guide** | SKILL.md now teaches agents HOW to write effective queries, WHEN to recall vs skip, and WHEN to proactively surface caveats before risky actions. |
 | **Five MCP Blocks** | Tools + Resources + Prompts + Sampling + Roots + Elicitation. Most MCP servers expose only Tools; linksee-memory implements all five primitives. |
 
 </details>
 
-## 7 Tools (v0.8)
+## 11 Tools
 
 ### Memory tools
 
@@ -406,20 +484,29 @@ 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)
+
+| 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. The memory tools are unchanged.
+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
 
 | Command | Purpose |
 |---|---|
-| `npx linksee-memory-setup` | One-command setup: MCP server + skill + Stop hook, then offers to wire the re-injection guard into this project. Idempotent — skips what's already done. |
+| `npx -y linksee-memory setup` | One-command setup: MCP server + skill + Stop hook, then offers to wire the re-injection guard into this project. Idempotent — skips what's already done. |
 | `npx linksee-memory` | MCP server (stdio) |
-| `npx linksee-memory-sync` | Claude Code Stop-hook entry point |
-| `npx linksee-memory-guard` | Re-injection guard hook: `PreToolUse` gate (`Edit`/`Write`/`Bash`) + `SessionStart` boot digest. Wired per-project (see [Re-injection Guard](#reinjection-guard)); fail-open. |
-| `npx linksee-memory-import` | Batch-import Claude Code session JSONL history |
-| `npx linksee-memory-install-skill` | Install the Claude Code Skill that teaches the agent when to call recall/remember/read_smart |
-| `npx linksee-memory-stats` | Summary of the local DB (entity count / layer breakdown / top entities / top edited files). Add `--json` for machine-readable output. |
+| `npx -y linksee-memory sync` | Claude Code Stop-hook entry point |
+| `npx -y linksee-memory guard` | Re-injection guard hook: `PreToolUse` gate (`Edit`/`Write`/`Bash`) + `SessionStart` boot digest. Wired per-project (see [Re-injection Guard](#reinjection-guard)); fail-open. |
+| `npx -y linksee-memory import` | Batch-import Claude Code session JSONL history |
+| `npx -y linksee-memory install-skill` | Install the Claude Code Skill that teaches the agent when to call recall/remember/read_smart |
+| `npx -y linksee-memory stats` | Summary of the local DB (entity count / layer breakdown / top entities / top edited files). Add `--json` for machine-readable output. |
 
 ## The 6 memory layers
 
@@ -469,7 +556,7 @@ The conversation↔file linkage is the key. Every file edit captured by the Stop
 - ✅ Five MCP Blocks (Tools + Resources + Prompts + Sampling + Roots + Elicitation)
 - ✅ Stop-hook auto-capture for Claude Code
 - ✅ JP/EN trigram FTS5
-- ✅ One-command setup (`npx linksee-memory-setup`)
+- ✅ One-command setup (`npx -y linksee-memory setup`)
 - ✅ Structured memory v2 (3-axis classification: altitude × type × state)
 - ✅ Cross-LLM: Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI
 - ✅ Landing page ([linksee-site.vercel.app](https://linksee-site.vercel.app))
@@ -546,7 +633,7 @@ No account, no credit card, no API key. Just install and use.
    ```bash
    ls ~/.claude/skills/linksee-memory/SKILL.md
    ```
-   If absent, run `npx -y linksee-memory-install-skill`.
+   If absent, run `npx -y linksee-memory install-skill`.
 2. Restart Claude Code. Skills are indexed on session start.
 3. Check that the MCP is registered under the name `linksee` (the skill expects `mcp__linksee__*` tool names):
    ```bash
@@ -561,9 +648,9 @@ No account, no credit card, no API key. Just install and use.
 1. Check the hook log: `cat ~/.linksee-memory/hook.log`
 2. Run a manual test:
    ```bash
-   echo '{"session_id":"test","transcript_path":"/path/to/some.jsonl"}' | npx linksee-memory-sync
+   echo '{"session_id":"test","transcript_path":"/path/to/some.jsonl"}' | npx -y linksee-memory sync
    ```
-3. Make sure the `Stop` hook in `~/.claude/settings.json` points to `npx -y linksee-memory-sync` (not the old `-import`).
+3. Make sure the `Stop` hook in `~/.claude/settings.json` points to `npx -y linksee-memory sync` (not the old `-import`).
 </details>
 
 <details>
@@ -572,7 +659,7 @@ No account, no credit card, no API key. Just install and use.
 v0.0.6+ fixed the entity detection bug that collapsed all memories into the session's starting cwd. To re-index existing history with correct project attribution, run:
 
 ```bash
-npx linksee-memory-import --all
+npx -y linksee-memory import --all
 ```
 
 The importer is idempotent (wipes existing session data before re-inserting). Typical runtime: a few minutes for hundreds of sessions. Expect a dramatic improvement in `recall` precision afterward.
@@ -700,6 +787,21 @@ After install, in a new Claude session ask: *"Can you remember that I prefer Typ
 
 ## Changelog
 
+### 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.
+- **`map` exits gracefully** with a next-step message when there's no `map.yaml` yet (was a raw stack trace — the exact state of a first-time user).
+- **serverInfo** now reports the real package version (was pinned to an old string).
+
+### 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.
@@ -800,7 +902,7 @@ Based on one week of dogfooding, here's what changed:
 **New tools**
 - `update_memory` — atomic edit with preserved `memory_id`. Solves the "forget+remember breaks session_file_edits links" bug.
 - `list_entities` — fast "what do I know about?" primitive for session init. Supports `kind`/`min_memories` filters and returns layer breakdown.
-- `npx linksee-memory-stats` — local DB summary CLI.
+- `npx -y linksee-memory stats` — local DB summary CLI.
 
 **`recall` enhancements**
 - `match_reasons` array on each memory: e.g. `["content_match_fts", "heat:hot", "pinned"]`.

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 {};