linksee-memory 0.7.1 → 0.8.0

package/README.md

@@ -1,8 +1,10 @@
 # linksee-memory
 
-> **Your agent forgets everything when a session ends. Linksee Memory is the fix.**
+> **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 that surfaces the right context at the right moment.
+> 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**.
+>
+> Memory is the entry point. Drift detection is the real value.
 >
 > `npx linksee-memory-setup` — one command, done.
 
@@ -79,7 +81,7 @@ That single `caveat` memory is what separates "flat fact storage" from "the agen
                   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 get compressed into `learning` entries via `consolidate()`.
+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.
 
 ---
 
@@ -87,21 +89,69 @@ Every memory is tagged with **exactly one layer**. `caveat`-layer entries are pr
 
 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 that gives any AI agent four superpowers:
+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 | ❌ | ✅ | ✅ |
 
-## Three pillars
+## 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.
+```
+
+### How it works
+
+1. **Declare** decisions as anchors: `declare_anchor({ kind: "decision", statement: "We use FTS5, not vector search", violation_signal: ["pgvector", "embedding"] })`
+2. **The engine detects** when committed code reality diverges from these anchors
+3. **State derivation** classifies each anchor:
+   - 🔴 **Drift** — reality diverges with no recorded resolution
+   - 🟡 **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`
+
+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.
+
+### 4-species taxonomy
+
+Anchors are classified into four species with different display formats:
+
+| Species | Icon | Display Format | Example |
+|---|---|---|---|
+| Hypothesis | 🧪 | Decision Card (journal format) | "We'll launch English-first on HN" |
+| Constraint | 🔒 | Rule (pass/fail checklist) | "All writes go through remember()" |
+| Commitment | 🔁 | Heartbeat (alive/dead) | "Ship a new version every week" |
+| Source of Truth | 📍 | Reference (stable anchor) | "MCP server runs on stdio, single SQLite" |
+
+---
 
 ## Quick Start — One Command
 
@@ -127,7 +177,7 @@ Restart Claude Code, then just chat normally. Add **"Use Linksee"** to any promp
 claude mcp add -s user linksee -- npx -y linksee-memory
 ```
 
-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__read_smart`.
 
 **Install the skill (auto-invocation):**
 
@@ -248,28 +298,60 @@ All editors share the same `~/.linksee-memory/memory.db`. A decision made in Cla
 
 Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env var.
 
-## What's new in v0.4
+## What's new in v0.8
+
+| Feature | Detail |
+|---|---|
+| **4 drift detection tools** | `drift_status`, `check_decision`, `declare_anchor`, `resolve_drift` — agents can now query and act on intent ↔ reality divergence. The biggest gap in agent memory (decisions are forgotten across sessions) is now closed. |
+| **Truth engine** | State derivation logic (drift/review/held/aligned) now lives in the MCP engine, not just the dashboard. Any MCP client can query drift status. |
+| **4-species taxonomy** | Anchors classified as hypothesis/constraint/commitment/source_of_truth with species-appropriate display formats. |
+| **Resolution priority** | When multiple resolutions exist for an anchor, the most recent one wins (prevents stale acknowledge from shadowing a newer fix). |
+
+<details>
+<summary>What's new in v0.7</summary>
+
+| Feature | Detail |
+|---|---|
+| **3-tool unified surface** | 8 tools → 3: `remember` (create + update + delete), `recall` (search + file history + overview), `read_smart` (token-saving reads). Fewer tools = better cross-LLM consistency. Follows Context7's proven pattern. |
+| **Auto-consolidate** | Consolidation runs automatically on server startup (non-blocking, 7-day threshold). No manual `consolidate()` calls needed. |
+| **Deprecation guidance** | Old tool names (`forget`, `recall_file`, etc.) return specific migration examples instead of silent failures. |
+| **"Use Linksee Memory" trigger** | Add "Use Linksee Memory" to any prompt to force memory recall — same adoption pattern as Context7. |
+| **Claude Code Plugin** | `claude plugin add -- linksee-memory` — ships MCP server + auto-invocation skill in one install. |
+
+</details>
+
+<details>
+<summary>What's new in v0.4</summary>
 
 | Feature | Detail |
 |---|---|
 | **One-command setup** | `npx 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. |
-| **"Use Linksee" trigger** | Add "Use Linksee" to any prompt to force memory recall — same adoption pattern as Context7. |
-| **Five MCP Blocks** | Tools + Resources + Prompts + Sampling + Roots + Elicitation. Most MCP servers expose only Tools; linksee-memory implements all six primitives. |
+| **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)
+
+### Memory tools
+
+| Tool | What it does |
+|---|---|
+| `remember` | **Save / update / delete** memories. Auto-classifies into 6 layers. Modes: create (default), update (`memory_id` + fields), delete (`forget: true` + `memory_id`). |
+| `recall` | **Search / file history / overview.** Modes: search (`query`), file history (`path`), entity overview (no params). FTS5 + heat × momentum ranking with `match_reasons`. |
+| `read_smart` | **Token-saving file reader** with AST diff caching. First read = full content. Re-read unchanged = ~50 tokens. Re-read modified = changed chunks only. |
 
-## Tools
+### Drift tools (v0.8.0)
 
-| Tool | Purpose |
+| Tool | What it does |
 |---|---|
-| `remember` | Store memory in 1 of 6 layers for an entity. Rejects pasted assistant output / CI logs unless `force=true`. Set `importance=1.0` to pin (survives auto-forget). |
-| `recall` | FTS5 + heat × momentum × importance composite ranking with `match_reasons` explaining WHY each row matched. Supports pagination (`offset`/`has_more`), `band` filter, layer aliases (`decisions`/`warnings`/`how`/...), and `mark_accessed=false` for passive previews. |
-| `recall_file` | Complete edit history of a file across all sessions, with per-edit user-intent context. **v0.3.0** `scope_to_roots` flag filters by client roots. |
-| `update_memory` | **v0.1.0** Atomic edit of an existing memory. Preserves `memory_id` (session_file_edits links stay intact). Prefer over forget+remember. |
-| `list_entities` | **v0.1.0** List what the memory knows about — cheapest "what do I know?" primitive. Filter by `kind`/`min_memories`; returns layer breakdown per entity. |
-| `read_smart` | Diff-only file read. Returns full content on first read, ~50 tokens on unchanged re-reads, only changed chunks on real edits. |
-| `forget` | Explicit delete OR auto-sweep based on `forgettingRisk`. Pinned (`importance>=1.0`) and caveat-layer memories are always preserved. **v0.3.0** `interactive` flag asks the user via Elicitation before deleting a specific memory_id. |
-| `consolidate` | Sleep-mode compression: cluster cold low-importance memories → protected learning-layer summary. Supports `dry_run` preview. **v0.3.0** `use_llm` flag asks the client LLM (Sampling) to rewrite cluster summaries into prose. |
+| `drift_status` | **"What's drifting right now?"** Returns the truth map with 4-species classification (hypothesis/constraint/commitment/source_of_truth) and per-node state (🔴 drift / 🟡 review / ⚪ held / 🔵 aligned). |
+| `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). |
+
+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.
 
 ### CLI utilities
 
@@ -313,7 +395,7 @@ A single SQLite file (`better-sqlite3` + FTS5 trigram tokenizer for JP/EN) conta
 - **Layer 4** — `events` (time-series log for heat / momentum computation)
 - **Layer 5** — `file_snapshots` + `session_file_edits` (diff cache + conversation↔file linkage)
 
-The conversation↔file linkage is the key. Every file edit captured by the Stop hook is stored alongside the **user message that drove the edit**. So `recall_file("server.ts")` returns "this file was edited 30 times across 3 days, and here are the actual user instructions that motivated each change".
+The conversation↔file linkage is the key. Every file edit captured by the Stop hook is stored alongside the **user message that drove the edit**. So `recall({ path: "server.ts" })` returns "this file was edited 30 times across 3 days, and here are the actual user instructions that motivated each change".
 
 ## Why the design choices
 
@@ -324,17 +406,22 @@ The conversation↔file linkage is the key. Every file edit captured by the Stop
 
 ## Roadmap
 
-- ✅ Core 8 MCP tools + Five Blocks (Tools + Resources + Prompts + Sampling + Roots + Elicitation)
+- ✅ 3-tool unified surface (remember / recall / read_smart) — v0.7.0
+- ✅ Auto-consolidate on server startup — v0.7.0
+- ✅ Claude Code Plugin (`claude plugin add -- linksee-memory`)
+- ✅ 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`)
 - ✅ Structured memory v2 (3-axis classification: altitude × type × state)
-- ✅ Precision recall guide + proactive caveat surfacing
 - ✅ Cross-LLM: Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI
-- 🚧 Landing page + SEO
+- ✅ Landing page ([linksee-site.vercel.app](https://linksee-site.vercel.app))
+- ✅ Drift detection engine + 4 MCP drift tools — v0.8.0
+- ✅ 4-species truth map (hypothesis/constraint/commitment/source_of_truth) — v0.8.0
+- ✅ Dashboard with Decision Register visualization
+- 🔮 Obsidian plugin (read truth map in your vault)
 - 🔮 Vector search via `sqlite-vec` (already in deps, embedding backend pending)
 - 🔮 Cross-device cloud sync (Pro tier)
-- 🔮 Optional anonymized telemetry → MCP-quality intelligence layer
 
 ## Comparison with Claude Code auto-memory
 
@@ -454,21 +541,29 @@ recall({ query: "...", entity_name: "my-project", layer: "caveat" })
 rm -rf ~/.linksee-memory   # nuke everything; next run creates a fresh DB
 ```
 
-Or delete individual memories via the `forget` tool with a specific `memory_id`.
+Or delete individual memories via `remember({ forget: true, memory_id: <id> })`.
 </details>
 
 <details>
 <summary><b>DB is getting large (>100 MB). How do I trim it?</b></summary>
 
-Run consolidate — it clusters old cold memories into compressed learning-layer summaries:
-```
-consolidate({ scope: "all", min_age_days: 7 })
-```
-Caveat and active-goal layers are always preserved. Consider scheduling a weekly run via cron / Task Scheduler.
+Consolidation runs automatically on server startup (7-day threshold). It clusters old cold memories into compressed learning-layer summaries. Caveat and active-goal layers are always preserved.
+
+If you want to force a manual consolidation, restart the MCP server — auto-consolidate triggers on every startup.
 </details>
 
 ## FAQ
 
+<details>
+<summary><strong>What is drift detection and why do I need it?</strong></summary>
+
+Drift = when your code reality silently diverges from what you decided. Example: Last week you decided "FTS5, not vector search" but this week a new agent session installs pgvector without knowing the history.
+
+Linksee Memory tracks this by letting you declare decisions as "anchors" and then automatically checking committed code against them. The make-or-break rule: **intentional evolution (recorded as fix/supersede) stays quiet, while unaccounted gaps get flagged.** It's like Datadog but for product decisions instead of server metrics.
+
+You don't need to use drift detection to benefit from linksee-memory — the 3 memory tools (remember/recall/read_smart) work independently. Drift tools are an additional layer for teams and solo devs managing multiple projects.
+</details>
+
 <details>
 <summary><strong>How is this different from Mem0 / Letta / Zep?</strong></summary>
 
@@ -484,7 +579,7 @@ Three axes:
 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
+- Auto-consolidation compresses cold memories on startup; caveats are permanently protected
 </details>
 
 <details>
@@ -509,7 +604,7 @@ The default is no sync — the SQLite file lives at `~/.linksee-memory/memory.db
 
 Two mechanisms:
 1. **Ebbinghaus forgetting**: cold low-importance memories decay naturally, eligible for auto-forget sweeps. `caveat` layer and memories with `importance ≥ 0.9` are always protected.
-2. **`consolidate()`**: compresses clusters of cold low-importance memories by entity into a single `learning`-layer summary, then deletes the originals. Run via `linksee-memory-consolidate` CLI (or schedule weekly).
+2. **Auto-consolidation**: runs on every server startup (7-day threshold). Compresses clusters of cold low-importance memories by entity into a single `learning`-layer summary, then deletes the originals. No manual scheduling needed.
 
 In practice a solo developer hits ~100MB after 6 months of heavy use. A year-old DB I tested with 80K memories still recalls in <10ms.
 </details>
@@ -523,7 +618,7 @@ Yes — any MCP-compatible client works:
 - **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.
+- **ChatGPT (web/mobile app)**: stdio MCP not supported by the consumer app — requires Remote MCP server over HTTPS (not yet available).
 - **Custom agent**: the MCP stdio protocol is documented at modelcontextprotocol.io
 </details>
 
@@ -536,7 +631,7 @@ Yes — any MCP-compatible client works:
 <details>
 <summary><strong>How do I verify it's actually working?</strong></summary>
 
-After install, in a new Claude session ask: *"Can you remember that I prefer TypeScript over JavaScript?"* Claude should confirm it called `mcp__linksee__remember` and stored this. Then in a **different session** ask: *"What languages do I prefer?"* It should recall via `mcp__linksee__recall` and return the preference with `match_reasons` showing why.
+After install, in a new Claude session ask: *"Can you remember that I prefer TypeScript over JavaScript? Use Linksee Memory."* Claude should confirm it called `mcp__linksee__remember` and stored this. Then in a **different session** ask: *"What languages do I prefer? Use Linksee Memory."* It should recall via `mcp__linksee__recall` and return the preference with `match_reasons` showing why.
 </details>
 
 ## Support
@@ -548,6 +643,70 @@ After install, in a new Claude session ask: *"Can you remember that I prefer Typ
 
 ## Changelog
 
+### 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.
+
+**New tools:**
+- **`drift_status`** — returns the truth map with 4-species classification and per-node drift state
+- **`check_decision`** — deep-dive into a single anchor: state, edges, pending candidates
+- **`declare_anchor`** — record a decision/constraint/prohibition as a truth-map node (with v9 ProjectCoreNode fields)
+- **`resolve_drift`** — close the feedback loop: fix / supersede / acknowledge / dismiss
+
+**New engine module:**
+- **`truth-engine.ts`** — state derivation logic migrated from the dashboard into the MCP engine. Any MCP client can now query drift status without a dashboard.
+- **Resolution priority fix**: when multiple resolutions reference the same anchor, the most recent one wins (by `resolved_at` timestamp). Prevents a stale acknowledge from shadowing a newer fix.
+- **4-species classification**: nodes classified by `decision_mode` into hypothesis / constraint / commitment / source_of_truth with display format guidance.
+
+No breaking changes to existing memory tools. All 3 memory tools (remember, recall, read_smart) are unchanged.
+
+### v0.7.2 — Recall ergonomics + auto-edge detection + classifier precision (2026-05-30)
+
+Quality pass on v0.7.0 / v0.7.1 — sharper day-to-day agent UX and cleaner data for the dashboard:
+
+- **`recall` token discipline**: drops the redundant `content_raw` from the response (parsed `content` was already there — it was a 2× duplicate), and actually enforces `max_tokens` by greedy assembly that measures real serialized size (was a flat ~100 tok/memory estimate). Adds `approx_tokens` to the response so the agent can see its budget usage. The same query that previously returned ~15,800 tokens for a 1200 budget now stays inside it.
+- **`recall` precision**: near-duplicate memories — same entity + near-identical core text, e.g. the same message captured under both `goal` and `learning` — collapse to one in the result set. Composite weights adapt to query specificity: multi-term queries weight relevance higher so off-topic-but-pinned memories don't crowd narrow recalls.
+- **Capture dedup (write side)**: `session-extractor` now produces AT MOST one memory per user turn, with priority `goal[first_intent] > caveat > decision > context`. A first-intent message containing decision words (e.g. "決めた" / "これで進めよう") is no longer double-saved as both `goal` and `learning`.
+- **`memory_edges` auto-detection**: the previously-empty `memory_edges` table is now populated during the sleep-mode consolidation sweep. `detectMemoryEdges()` links a later DECISION memory to the most-recent earlier same-topic decision within an entity (chain, not clique) so the dashboard can render Pivot Chains. The default relation is `extends` — a same-topic later decision builds on, but does NOT deactivate, the earlier one. Explicit reversal markers (やめる / revert / instead of) produce `contradicts`; explicit replacement markers (の代わり / replaces / deprecate) produce `supersedes`. Prevents silent deactivation of still-valid decisions.
+- **`inferType` / `inferState` precision**: chitchat acknowledgements ("そうだね" / "ありがとう"), pasted terminal/git/email content, and meta-noise no longer classify as `decision` — they return `note` / `open` before pattern matching. The learning-layer default → `decision` is gated by this guard. Real decisions (採用 / 決めた, even after an acknowledgement opener) survive.
+
+No schema migration, no breaking API changes. Existing rows keep their stored content; the classifier improvements apply to new captures going forward.
+
+### v0.7.1 — Review fixes (2026-05-29)
+
+Based on Opus 4.7 design review of v0.7.0:
+
+- **P0 — Required params guidance**: `remember` tool description now includes "REQUIRED PARAMS BY MODE" section so LLMs know exactly which fields are needed for create vs update vs delete.
+- **P0 — Migration guidance**: Deprecated tool names (`forget`, `recall_file`, etc.) now return specific migration examples instead of generic errors.
+- **P1 — recall path+query merge**: When both `path` and `query` are provided to `recall`, results from file history and memory search are merged into a single response.
+- **P2 — Auto-consolidate safety**: Table existence check via `sqlite_master` before querying `consolidations` table, preventing errors on fresh databases.
+
+### v0.7.0 — 3-Tool Unified Surface (2026-05-29)
+
+**8 tools → 3 tools.** Following Context7's proven pattern of fewer tools = better cross-LLM consistency.
+
+**Breaking change**: The following tools are removed from the MCP surface. Calling them returns a migration guide:
+
+| Old tool | New equivalent |
+|---|---|
+| `forget` | `remember({ forget: true, memory_id: <id> })` |
+| `update_memory` | `remember({ memory_id: <id>, content: "..." })` |
+| `recall_file` | `recall({ path: "server.ts" })` |
+| `list_entities` | `recall({})` (no params = entity overview) |
+| `consolidate` | Auto-runs on server startup (7-day threshold) |
+
+**New unified tools:**
+- **`remember`** — create + update + delete in one tool. Mode is inferred from params.
+- **`recall`** — search + file history + overview in one tool. Mode is inferred from params.
+- **`read_smart`** — unchanged.
+
+**Other changes:**
+- Auto-consolidate on server startup (non-blocking `setTimeout`, 7-day threshold, `sqlite_master` safety check)
+- Claude Code Plugin bundle (`claude plugin add -- linksee-memory`)
+- Deprecation errors include specific migration examples
+
+All internal handler functions are preserved — this is a surface change, not a logic rewrite.
+
 ### v0.2.0 — English-first launch readiness (2026-04-20)
 
 Prepares the package for a broader (primarily English-speaking) audience on Reddit, Hacker News, and Anthropic Discord. No breaking API changes.

package/dist/bin/declare-anchor.d.ts

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

package/dist/bin/declare-anchor.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// linksee-memory-declare — declare / list / retire drift anchors (v8).
+//
+// The explicit write path for drift observability. Anchors declared here are clean
+// by construction (declare-don't-mine): a human typed them. The bulk seeding script
+// (curate the existing candidate pool) reuses curateAnchorFromMemory() from the lib.
+//
+// Usage:
+//   linksee-memory-declare list [--status active|retired] [--kind prohibition|decision|constraint]
+//   linksee-memory-declare add --kind <k> --statement "<text>" [--rationale "<text>"]
+//        [--affects "glob1,glob2"] [--terms "t1,t2"] [--violation "v1,v2"] [--tier human|explicit]
+//   linksee-memory-declare retire --id <n>
+import { openDb, runMigrations } from '../db/migrate.js';
+import { declareAnchor, listAnchors, retireAnchor, setNodeFields, getCurrentTruth, getAlertPolicy, setAlertPolicy, } from '../lib/drift-anchors.js';
+function parseFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                out[key] = 'true';
+            }
+            else {
+                out[key] = next;
+                i++;
+            }
+        }
+    }
+    return out;
+}
+function splitList(v) {
+    if (!v)
+        return [];
+    return v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function print(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+function main() {
+    const [, , sub, ...rest] = process.argv;
+    const flags = parseFlags(rest);
+    const db = openDb();
+    runMigrations(db); // ensure drift tables exist when run standalone
+    try {
+        switch (sub) {
+            case 'add': {
+                const anchor = declareAnchor(db, {
+                    kind: flags.kind,
+                    statement: flags.statement ?? '',
+                    rationale: flags.rationale,
+                    affects: splitList(flags.affects),
+                    detect_terms: splitList(flags.terms),
+                    violation_signal: splitList(flags.violation),
+                    tier: flags.tier || undefined,
+                });
+                // v9 ProjectCoreNode fields (minimal input — only what's given):
+                //   --node-type --domain --mode --confidence --cadence --stale-days --applies --not-applies
+                const nf = {};
+                if (flags['node-type'])
+                    nf.node_type = flags['node-type'];
+                if (flags.domain)
+                    nf.domain = flags.domain;
+                if (flags.mode)
+                    nf.decision_mode = flags.mode;
+                if (flags.confidence)
+                    nf.confidence = Number(flags.confidence);
+                if (flags.cadence || flags['stale-days']) {
+                    const cp = { enabled: true };
+                    if (flags.cadence)
+                        cp.cadence_days = Number(flags.cadence);
+                    if (flags['stale-days'])
+                        cp.stale_threshold_days = Number(flags['stale-days']);
+                    nf.card_policy = cp;
+                }
+                if (flags.applies || flags['not-applies']) {
+                    const vs = {};
+                    if (flags.applies)
+                        vs.applies_to = splitList(flags.applies);
+                    if (flags['not-applies'])
+                        vs.does_not_apply_to = splitList(flags['not-applies']);
+                    nf.validity_scope = vs;
+                }
+                if (Object.keys(nf).length)
+                    setNodeFields(db, anchor.id, nf);
+                print({ ok: true, declared: anchor, node_fields: Object.keys(nf).length ? nf : null });
+                break;
+            }
+            case 'retire': {
+                const id = Number(flags.id);
+                if (!Number.isFinite(id))
+                    throw new Error('--id <n> required');
+                const ok = retireAnchor(db, id);
+                print({ ok, retired: ok ? id : null });
+                break;
+            }
+            case 'list':
+            case undefined: {
+                const anchors = listAnchors(db, {
+                    status: flags.status,
+                    kind: flags.kind,
+                });
+                print({ ok: true, count: anchors.length, anchors });
+                break;
+            }
+            case 'truth': {
+                // ⑧ read_smart-style scoped read: active Current-Truth slice only.
+                const nodes = getCurrentTruth(db, { domain: flags.domain, decision_mode: flags.mode });
+                print({ ok: true, scope: { domain: flags.domain ?? 'all', decision_mode: flags.mode ?? 'all' }, count: nodes.length, current_truth: nodes });
+                break;
+            }
+            case 'policy': {
+                const p = {};
+                if (flags['max-cards-per-day'])
+                    p.max_cards_per_day = Number(flags['max-cards-per-day']);
+                if (flags['max-soft-per-week'])
+                    p.max_soft_cards_per_week = Number(flags['max-soft-per-week']);
+                if (flags['min-soft-confidence'])
+                    p.min_confidence_for_soft_card = Number(flags['min-soft-confidence']);
+                if (flags['two-sided'])
+                    p.require_two_sided_evidence = flags['two-sided'] !== 'false';
+                const policy = Object.keys(p).length ? setAlertPolicy(db, p) : getAlertPolicy(db);
+                print({ ok: true, alert_policy: policy });
+                break;
+            }
+            default:
+                throw new Error(`unknown subcommand "${sub}" — use: add | list | retire | truth | policy`);
+        }
+    }
+    catch (err) {
+        print({ ok: false, error: err?.message ?? String(err) });
+        db.close();
+        process.exit(1);
+    }
+    db.close();
+}
+if (import.meta.url === `file://${process.argv[1]}` ||
+    process.argv[1]?.endsWith('declare-anchor.ts') ||
+    process.argv[1]?.endsWith('declare-anchor.js')) {
+    main();
+}
+//# sourceMappingURL=declare-anchor.js.map

package/dist/bin/detect-drift.d.ts

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

package/dist/bin/detect-drift.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// linksee-memory-detect — run the drift detector (照合: declared intent vs. actual reality).
+//
+// The manual-trigger entry point for drift detection (the cadence question). Mirrors
+// declare-anchor.ts; purely additive — touches only drift_edges (the feature's own table) and
+// ONLY when --persist is passed. SAFE BY DEFAULT: a bare run is a dry-run (reads only, no
+// writes), so you can preview drift before committing it to the view. Pass --persist to write
+// the edges that /drift renders. No embedding layer: matching is lexical/glob/trigram-FTS only.
+//
+// Usage:
+//   linksee-memory-detect                  # dry-run — preview drift, writes NOTHING (default)
+//   linksee-memory-detect --persist         # write contradicts/absent edges into drift_edges
+//   linksee-memory-detect --stale-days 30   # override absence staleness gate (default 14)
+//   linksee-memory-detect --threshold 0.5   # override emit threshold (default 0.5)
+import { openDb, runMigrations } from '../db/migrate.js';
+import { detectDrift, detectFileViolations } from '../lib/drift-detection.js';
+function parseFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                out[key] = 'true';
+            }
+            else {
+                out[key] = next;
+                i++;
+            }
+        }
+    }
+    return out;
+}
+function print(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+function main() {
+    const [, , ...rest] = process.argv;
+    const flags = parseFlags(rest);
+    const persist = flags.persist === 'true';
+    const staleDays = flags['stale-days'] !== undefined ? Number(flags['stale-days']) : undefined;
+    const emitThreshold = flags.threshold !== undefined ? Number(flags.threshold) : undefined;
+    if (staleDays !== undefined && !Number.isFinite(staleDays))
+        throw new Error('--stale-days <n> must be a number');
+    if (emitThreshold !== undefined && !Number.isFinite(emitThreshold))
+        throw new Error('--threshold <n> must be a number');
+    const db = openDb();
+    runMigrations(db); // ensure drift tables exist when run standalone
+    try {
+        const res = detectDrift(db, { dryRun: !persist, staleDays, emitThreshold });
+        const fres = detectFileViolations(db, { dryRun: !persist, emitThreshold });
+        print({
+            ok: true,
+            mode: persist ? 'PERSISTED' : 'DRY RUN (no writes — pass --persist to write)',
+            persisted: res.persisted,
+            anchorsScanned: res.anchorsScanned,
+            editsScanned: res.editsScanned,
+            // v1 — edit-snippet scan (what a captured edit's snippet contained)
+            editSnippetScan: {
+                contradicts: res.contradicts,
+                absent: res.absent,
+                edgesEmitted: res.edgesEmitted,
+                byAnchorHits: res.byAnchor.filter((b) => b.contradicts > 0 || b.absent > 0),
+                samples: res.samples.slice(0, 6),
+            },
+            // v2 — current-file scan (live file:line against violation_signal)
+            currentFileScan: {
+                filesScanned: fres.filesScanned,
+                anchorsCapped: fres.anchorsCapped,
+                contradicts: fres.contradicts,
+                edgesEmitted: fres.edgesEmitted,
+                byAnchorHits: fres.byAnchor,
+                samples: fres.samples.slice(0, 14),
+            },
+            totalEdgesEmitted: res.edgesEmitted + fres.edgesEmitted,
+        });
+    }
+    catch (err) {
+        print({ ok: false, error: err?.message ?? String(err) });
+        db.close();
+        process.exit(1);
+    }
+    db.close();
+}
+if (import.meta.url === `file://${process.argv[1]}` ||
+    process.argv[1]?.endsWith('detect-drift.ts') ||
+    process.argv[1]?.endsWith('detect-drift.js')) {
+    main();
+}
+//# sourceMappingURL=detect-drift.js.map