linksee-memory 0.7.0 → 0.7.2

package/README.md

@@ -79,7 +79,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,7 +87,7 @@ 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 **3 tools** that gives any AI agent structured memory:
 
 | | Mem0 / Letta / Zep | Claude Code auto-memory | linksee-memory |
 |---|---|---|---|
@@ -127,7 +127,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 +248,37 @@ 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.7
+
+| 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>
+<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>
 
-## Tools
+## 3 Tools (v0.7)
 
-| 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. |
+| `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. |
+
+Previous versions exposed 8 tools — v0.7.0 unified them into 3 for cross-LLM consistency. The server handles routing internally. Old tool names return migration guidance.
 
 ### CLI utilities
 
@@ -313,7 +322,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 +333,18 @@ 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))
 - 🔮 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,17 +464,15 @@ 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
@@ -484,7 +492,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 +517,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 +531,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 +544,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 +556,53 @@ After install, in a new Claude session ask: *"Can you remember that I prefer Typ
 
 ## Changelog
 
+### 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/lib/consolidate.d.ts

@@ -6,6 +6,8 @@ export interface ConsolidateResult {
     memoriesDropped: number;
     learningIdsCreated: number[];
     stalledTransitions: number;
+    memoryEdgesCreated: number;
+    decisionsSuperseded: number;
 }
 export declare function consolidate(db: Database.Database, opts?: {
     scope?: 'all' | 'session';

package/dist/lib/consolidate.js

@@ -11,6 +11,7 @@
 //   4. Per-run forget-sweep drops expired memories that didn't cluster.
 import { computeHeat } from './heat-index.js';
 import { decideForgetting } from './forgetting.js';
+import { detectMemoryEdges } from './edge-detection.js';
 const CLUSTER_LAYERS = ['context', 'emotion', 'implementation'];
 const DEFAULT_MIN_AGE_DAYS = 7;
 const MAX_HEAT = 30;
@@ -64,6 +65,8 @@ export function consolidate(db, opts = {}) {
         memoriesDropped: 0,
         learningIdsCreated: [],
         stalledTransitions: 0,
+        memoryEdgesCreated: 0,
+        decisionsSuperseded: 0,
     };
     const insertLearning = db.prepare(`INSERT INTO memories (entity_id, layer, content, importance, protected, source)
      VALUES (?, 'learning', ?, ?, 1, ?)`);
@@ -142,6 +145,11 @@ export function consolidate(db, opts = {}) {
       AND protected = 0
   `).run(stalledCutoff);
     result.stalledTransitions = stalledResult.changes;
+    // Memory→memory edge detection: link superseding/contradicting decisions so the
+    // dashboard can render Pivot Chains and recall can surface superseded decisions.
+    const edgeRes = detectMemoryEdges(db);
+    result.memoryEdgesCreated = edgeRes.edgesCreated;
+    result.decisionsSuperseded = edgeRes.supersededMarked;
     // Post-consolidate: forget-sweep remaining non-clustered cold memories
     const remaining = db
         .prepare('SELECT id, layer, importance, access_count, last_accessed_at, protected, altitude FROM memories WHERE protected = 0')

package/dist/lib/edge-detection.d.ts

@@ -0,0 +1,22 @@
+import type Database from 'better-sqlite3';
+export interface EdgeSample {
+    from_id: number;
+    to_id: number;
+    relation: string;
+    from_title: string;
+    to_title: string;
+    shared: string[];
+}
+export interface EdgeDetectionResult {
+    decisionsScanned: number;
+    edgesCreated: number;
+    supersedes: number;
+    contradicts: number;
+    extends: number;
+    supersededMarked: number;
+    samples: EdgeSample[];
+}
+export declare function detectMemoryEdges(db: Database.Database, opts?: {
+    dryRun?: boolean;
+    lookback?: number;
+}): EdgeDetectionResult;

package/dist/lib/edge-detection.js

@@ -0,0 +1,178 @@
+// Memory→memory edge detection (precision-first, no LLM required).
+//
+// Populates the `memory_edges` table with supersedes/contradicts links between
+// DECISION memories, so the dashboard can render Pivot Chains and recall can
+// surface superseded decisions. Runs inside the sleep-mode consolidation sweep.
+// Idempotent (UNIQUE constraint on memory_edges).
+//
+// Heuristic: within one entity, a later decision that shares strong topical terms
+// with an earlier decision *supersedes* it (→ *contradicts* if it carries reversal
+// markers like やめる / 撤回 / revert / instead of). The earlier decision's state
+// is flipped to 'superseded'. We link to the MOST RECENT same-topic decision so
+// chains form (A → B → C) rather than cliques.
+import { isMetaOrNoise, isPastedExternalContent } from './session-parser.js';
+// A later decision either REVERSES an earlier one (→ contradicts) or REPLACES it
+// (→ supersedes). A same-topic decision with NEITHER marker only EXTENDS the earlier
+// one and must NOT deactivate it — marking a still-valid decision 'superseded' is
+// silent data loss (e.g. "v2 format" extends, it does not kill, the "2-layer arch" decision).
+const CONTRADICT_MARKERS = /やめ|撤回|取り消|ではなく|じゃなく|見直|revert|rollback|instead of|no longer|abandon|\bdon'?t\b/i;
+const SUPERSEDE_MARKERS = /の代わり|に変更|に切り替|乗り換|を置き換|に置換|廃止|replaces?\b|supersed|deprecat|switch(?:ing|ed)?\s+(?:to|from|away)/i;
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'your', 'our', 'their',
+    'about', 'what', 'when', 'will', 'have', 'has', 'was', 'were', 'are', 'not', 'use', 'using',
+    'memory', 'linksee', 'session', 'decision', 'project', 'やった', 'する', 'した', 'して',
+    'こと', 'ため', 'よう', 'という', 'です', 'ます', 'など', 'その', 'この', 'これ', 'それ',
+    // conversational fillers — must never count as a shared "topic" term
+    'そうだね', 'そうね', 'ありがとう', 'なるほど', 'やろう', 'いいね', 'おおいね', 'これでいい',
+    'これでいいと思う', 'これでいいかな', 'わかった', '了解', 'おはよう', 'おつかれ',
+]);
+// Both endpoints must have substantive core text — kills "そうだね"/"ありがとう"
+// turns that the upstream classifier over-labels as decisions.
+const MIN_CORE_LEN = 40;
+// Decisions whose body opens with an acknowledgement are almost always chitchat
+// the upstream classifier mis-typed — never use them as edge endpoints.
+const CHITCHAT_OPENER = /^\s*(?:そう(?:だ?ね|だよね)?|うん|ありがと|なるほど|おお|へえ|了解|わかった|はい|おはよう|おつかれ|いいね|まあ|ええ|あー)/;
+// Terminal output, git/npm logs, and pasted emails also get mis-typed as decisions.
+// isPastedExternalContent misses these shapes, so guard them explicitly.
+const LOOKS_LIKE_PASTE = /PS [A-Za-z]:\\|[A-Za-z]:\\Users\\|create mode \d{6}|\bgit (?:commit|push|add|status|log|diff|branch|checkout|merge)\b|commit -m|\bnpm (?:run|install|ci)\b|Upon further review|resubmission|Thank you for your/i;
+function significantTerms(text) {
+    const out = new Set();
+    const lower = text.toLowerCase();
+    const asciiRe = /[a-z][a-z0-9_+.-]{2,}/g;
+    let m;
+    while ((m = asciiRe.exec(lower)) !== null) {
+        const w = m[0];
+        if (w.length >= 3 && !STOPWORDS.has(w))
+            out.add(w);
+    }
+    // CJK runs (hiragana / katakana / kanji / half-width kana), length 2..12.
+    const cjkRe = /[぀-ヿ㐀-鿿ｦ-ﾟ]{2,12}/g;
+    while ((m = cjkRe.exec(text)) !== null) {
+        const w = m[0];
+        if (!STOPWORDS.has(w))
+            out.add(w);
+    }
+    return out;
+}
+function coreText(content) {
+    try {
+        const o = JSON.parse(content);
+        return {
+            title: String(o.title ?? ''),
+            body: String(o.what ?? o.decision ?? o.intent ?? o.learned ?? ''),
+        };
+    }
+    catch {
+        return { title: '', body: content };
+    }
+}
+export function detectMemoryEdges(db, opts = {}) {
+    const lookback = opts.lookback ?? 25;
+    const res = {
+        decisionsScanned: 0, edgesCreated: 0, supersedes: 0, contradicts: 0, extends: 0, supersededMarked: 0, samples: [],
+    };
+    const rows = db.prepare(`
+    SELECT id, entity_id, content, created_at
+    FROM memories
+    WHERE mem_type = 'decision' AND json_valid(content)
+    ORDER BY entity_id ASC, created_at ASC, id ASC
+  `).all();
+    res.decisionsScanned = rows.length;
+    if (rows.length < 2)
+        return res;
+    const byEntity = new Map();
+    for (const r of rows) {
+        const arr = byEntity.get(r.entity_id);
+        if (arr)
+            arr.push(r);
+        else
+            byEntity.set(r.entity_id, [r]);
+    }
+    // Prepare write statements only when actually writing — keeps dryRun safe on a
+    // readonly connection (preview / verification path).
+    const insEdge = opts.dryRun ? null : db.prepare(`INSERT OR IGNORE INTO memory_edges (from_memory_id, to_memory_id, relation) VALUES (?, ?, ?)`);
+    const markSuperseded = opts.dryRun ? null : db.prepare(`
+    UPDATE memories SET content = json_set(content, '$.state', 'superseded')
+    WHERE id = ? AND json_valid(content) AND json_extract(content, '$.state') <> 'superseded'
+  `);
+    const apply = () => {
+        for (const decisions of byEntity.values()) {
+            if (decisions.length < 2)
+                continue;
+            const meta = decisions.map((d) => {
+                const { title, body } = coreText(d.content);
+                const text = `${title} ${body}`;
+                // Defend against the polluted 'decision' input set: drop pasted external
+                // content (emails / terminal logs), meta-noise, chitchat, and too-short bodies.
+                const usable = text.trim().length >= MIN_CORE_LEN
+                    && !CHITCHAT_OPENER.test(body)
+                    && !isMetaOrNoise(body)
+                    && !isPastedExternalContent(body)
+                    && !LOOKS_LIKE_PASTE.test(text);
+                return { id: d.id, title: (title || body).slice(0, 60), text, len: text.trim().length, terms: significantTerms(text), usable };
+            }).filter((m) => m.usable && m.terms.size >= 3);
+            for (let i = 1; i < meta.length; i++) {
+                if (meta[i].terms.size < 3 || meta[i].len < MIN_CORE_LEN)
+                    continue;
+                let linked = -1;
+                let linkedShared = [];
+                for (let j = i - 1; j >= 0 && i - j <= lookback; j--) {
+                    if (meta[j].terms.size < 3 || meta[j].len < MIN_CORE_LEN)
+                        continue;
+                    const shared = [];
+                    for (const t of meta[i].terms)
+                        if (meta[j].terms.has(t))
+                            shared.push(t);
+                    if (shared.length < 3)
+                        continue; // require >= 3 shared topic terms (precision-first)
+                    const overlap = shared.length / Math.min(meta[i].terms.size, meta[j].terms.size);
+                    if (overlap > 0.85)
+                        continue; // near-identical memories = a duplicate, not a supersession
+                    if (overlap >= 0.25) {
+                        linked = j;
+                        linkedShared = shared;
+                        break;
+                    } // most-recent same-topic → chain
+                }
+                if (linked < 0)
+                    continue;
+                const reversing = CONTRADICT_MARKERS.test(meta[i].text);
+                const replacing = SUPERSEDE_MARKERS.test(meta[i].text);
+                const relation = reversing ? 'contradicts' : replacing ? 'supersedes' : 'extends';
+                const deactivatesOlder = reversing || replacing; // 'extends' leaves the older decision valid
+                let counted = true;
+                if (!opts.dryRun) {
+                    const r = insEdge.run(meta[i].id, meta[linked].id, relation);
+                    if (r.changes > 0) {
+                        if (deactivatesOlder && markSuperseded.run(meta[linked].id).changes > 0)
+                            res.supersededMarked++;
+                    }
+                    else {
+                        counted = false; // edge already existed
+                    }
+                }
+                if (counted) {
+                    res.edgesCreated++;
+                    if (relation === 'contradicts')
+                        res.contradicts++;
+                    else if (relation === 'supersedes')
+                        res.supersedes++;
+                    else
+                        res.extends++;
+                    if (res.samples.length < 25) {
+                        res.samples.push({
+                            from_id: meta[i].id, to_id: meta[linked].id, relation,
+                            from_title: meta[i].title, to_title: meta[linked].title, shared: linkedShared.slice(0, 6),
+                        });
+                    }
+                }
+            }
+        }
+    };
+    if (opts.dryRun)
+        apply();
+    else
+        db.transaction(apply)();
+    return res;
+}
+//# sourceMappingURL=edge-detection.js.map

package/dist/lib/session-extractor.js

@@ -25,7 +25,35 @@ const TYPE_PATTERNS = [
     [/学び|教訓|分かった|判明|発見|learn|realize|discover|find\s+out|turns?\s+out|takeaway|insight/i, 'learning'],
     [/結果|完了|成功|失敗|outcome|result|shipped|deployed|launched|finished|accomplished/i, 'outcome'],
 ];
+// Pasted terminal/git/npm output and forwarded emails get mis-typed as decisions.
+// isPastedExternalContent misses these shapes, so guard them explicitly.
+const LOOKS_LIKE_PASTE = /PS [A-Za-z]:\\|[A-Za-z]:\\Users\\|create mode \d{6}|\bgit (?:commit|push|add|status|log|diff|branch|checkout|merge)\b|commit -m|\bnpm (?:run|install|ci)\b|Upon further review|resubmission|Thank you for your/i;
+// A turn that is ENTIRELY an acknowledgement carries no cognitive content. This only
+// fires on short, wholly-filler messages — anything with substance after the opener
+// (e.g. "そうだね、Reactを採用しよう") still flows to the patterns below.
+const PURE_ACK = /^(?:そう(?:だ?ね|だよね)?|うん+|ありがと[うー]?|なるほど|了解(?:です)?|わかった|おはよう|おつかれ(?:さま)?|はい+|おお+|へえ+|いいね|まあ|ええ|あー|ok|okay|thanks?|got it|sounds good)[。、,.!！?？\s~〜ねよ]*$/i;
+// Whether a memory's text carries enough signal to assign a meaningful cognitive type.
+// Junk (pasted logs/emails, meta-noise, pure acknowledgements) must NOT become a
+// 'decision'/'comparison' — that pollution caps memory_edges + dashboard quality.
+function isClassifiableContent(text) {
+    const t = text.trim();
+    if (t.length === 0)
+        return false;
+    if (PURE_ACK.test(t))
+        return false;
+    if (LOOKS_LIKE_PASTE.test(text))
+        return false;
+    if (isPastedExternalContent(text))
+        return false;
+    if (isMetaOrNoise(text))
+        return false;
+    return true;
+}
 export function inferType(text, layer) {
+    // Precision guard: junk content has no meaningful type — fall back to 'note'
+    // BEFORE pattern matching / layer defaults so it can never become a 'decision'.
+    if (!isClassifiableContent(text))
+        return 'note';
     for (const [pattern, type] of TYPE_PATTERNS) {
         if (pattern.test(text))
             return type;
@@ -54,6 +82,9 @@ const STATE_PATTERNS = [
     [/取り替え|代わりに|置き換え|replaced|superseded|deprecated|obsolete|旧版|old\s+approach/i, 'superseded'],
 ];
 export function inferState(text, layer) {
+    // Junk content gets a neutral 'open' state rather than a confident 'decided'/'done'.
+    if (!isClassifiableContent(text))
+        return 'open';
     for (const [pattern, state] of STATE_PATTERNS) {
         if (pattern.test(text))
             return state;
@@ -205,6 +236,10 @@ function dedupeEdits(edits) {
 export function extractSession(session, projectName) {
     const memories = [];
     const file_edits = [];
+    // Turn-level dedup: a single user turn should yield at most ONE memory.
+    // Priority: goal(first_intent) > caveat > decision > context. capturedTurns
+    // tracks caveat-claimed turns so the decision pass skips them.
+    const capturedTurns = new Set();
     // Detect fully-automated sessions (e.g. scheduled cron tasks) — no user intent to extract
     const firstRawUserText = session.turns.find((t) => t.role === 'user' && !t.tool_results)?.text ?? '';
     const automated = isAutomatedSession(firstRawUserText);
@@ -265,6 +300,12 @@ export function extractSession(session, projectName) {
             continue;
         if (t.text.trim().length < 40)
             continue;
+        // Defer to the caveat/decision passes when they WOULD capture this turn,
+        // so a clarification that is really a warning/decision isn't double-saved as context.
+        const wouldBeCaveat = matchesAny(t.text, CAVEAT_PATTERNS) && t.text.length > 20 && !isChitchatWithBuriedDecision(t.text, CAVEAT_PATTERNS);
+        const wouldBeDecision = matchesAny(t.text, DECISION_PATTERNS) && t.text.length > 15 && !isChitchatWithBuriedDecision(t.text, DECISION_PATTERNS);
+        if (wouldBeCaveat || wouldBeDecision)
+            continue;
         clarifyCount++;
         const msgText = t.text.slice(0, 600);
         memories.push({
@@ -340,6 +381,8 @@ export function extractSession(session, projectName) {
     for (const t of session.turns) {
         if (t.role !== 'user' || isMetaOrNoise(t.text))
             continue;
+        if (t === firstIntent)
+            continue; // already captured as the goal/first-intent memory
         if (t.tool_results && t.tool_results.length > 0)
             continue;
         if (isPastedExternalContent(t.text))
@@ -364,6 +407,8 @@ export function extractSession(session, projectName) {
                 thread_id: session.session_id,
                 source: { session_id: session.session_id, turn_uuid: t.uuid, kind: 'caveat' },
             });
+            if (t.uuid)
+                capturedTurns.add(t.uuid); // claim this turn so the decision pass skips it
         }
     }
     // 5) Learning layer — messages matching decision patterns
@@ -374,6 +419,10 @@ export function extractSession(session, projectName) {
     for (const t of session.turns) {
         if (t.role !== 'user' || isMetaOrNoise(t.text))
             continue;
+        if (t === firstIntent)
+            continue; // already captured as the goal/first-intent memory
+        if (t.uuid && capturedTurns.has(t.uuid))
+            continue; // already captured as a caveat
         if (t.tool_results && t.tool_results.length > 0)
             continue;
         if (isPastedExternalContent(t.text))

package/dist/mcp/server.js

@@ -27,11 +27,17 @@ setTimeout(() => {
     try {
         let shouldRun = true;
         try {
-            const lastRow = db.prepare('SELECT MAX(created_at) as ts FROM consolidations').get();
-            if (lastRow?.ts && (Date.now() / 1000 - lastRow.ts) / 86400 < 7)
-                shouldRun = false;
+            // Check if consolidations table exists before querying
+            const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='consolidations'").get();
+            if (tableExists) {
+                const lastRow = db.prepare('SELECT MAX(created_at) as ts FROM consolidations').get();
+                if (lastRow?.ts && (Date.now() / 1000 - lastRow.ts) / 86400 < 7)
+                    shouldRun = false;
+            }
+        }
+        catch {
+            shouldRun = false; /* genuinely unexpected — skip to be safe */
         }
-        catch { /* table may not exist yet */ }
         if (shouldRun) {
             runConsolidate(db, { scope: 'all', min_age_days: 7 });
             process.stderr.write('[linksee-memory] auto-consolidate complete\n');
@@ -81,7 +87,7 @@ const LAYER_ENUM = ['goal', 'context', 'emotion', 'implementation', 'caveat', 'l
 const TOOLS = [
     {
         name: 'remember',
-        description: 'Persist knowledge across sessions and AI tools (Claude, GPT, Cursor, Codex, Gemini). The only cross-agent memory that survives session boundaries.\n\nWHEN TO CALL:\n• The moment an error or failure occurs → layer: "caveat" (auto-protected, never forgotten)\n• When a decision is made or approved → layer: "learning"\n• When a goal is set or updated → layer: "goal"\n• When something new is learned → layer: "learning"\n• When the user says "remember this" / "覚えておいて"\n• At session end, to preserve key outcomes\n\nMODES:\n• Create (default): provide entity_name + entity_kind + layer + content\n• Update: provide memory_id + fields to change (preserves links and history)\n• Delete: set forget: true + memory_id\n\nImportance ≥ 0.9 pins the memory (protected from auto-forgetting). Supports Japanese (日本語) and English.',
+        description: 'Persist knowledge across sessions and AI tools (Claude, GPT, Cursor, Codex, Gemini). The only cross-agent memory that survives session boundaries.\n\nWHEN TO CALL:\n• The moment an error or failure occurs → layer: "caveat" (auto-protected, never forgotten)\n• When a decision is made or approved → layer: "learning"\n• When a goal is set or updated → layer: "goal"\n• When something new is learned → layer: "learning"\n• When the user says "remember this" / "覚えておいて"\n• After completing a task or receiving user approval\n\nREQUIRED PARAMS BY MODE:\n• Create (default): entity_name + entity_kind + layer + content\n• Update: memory_id (+ optional content, layer, importance)\n• Delete: memory_id + forget: true\n\nImportance ≥ 0.9 pins the memory (protected from auto-forgetting). Supports Japanese (日本語) and English.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -100,7 +106,7 @@ const TOOLS = [
     },
     {
         name: 'recall',
-        description: 'Your persistent memory across all AI tools. CALL THIS BEFORE STARTING ANY TASK to check for past caveats (pain records), decisions, and learnings — prevents repeating mistakes across sessions.\n\nWHEN TO CALL:\n• Before starting any new task or touching a file\n• When the user mentions "before" / "前に" / "last time" / "remember when"\n• When an error occurs — check if you\'ve seen it before\n• When making a decision — check for prior decisions on the same topic\n\nTHREE MODES (auto-detected):\n• Search (default): provide query → returns memories ranked by relevance + heat\n• File history: provide path → returns complete edit history with user-intent context\n• Overview: omit all params → returns entity list sorted by momentum\n\nTip: Add "Use Linksee Memory" to your system prompt for automatic cross-session memory.\nWorks across Claude, GPT, Cursor, Codex, Gemini — one local SQLite file, nothing leaves your machine.',
+        description: 'Your persistent memory across all AI tools. CALL THIS BEFORE STARTING ANY TASK to check for past caveats (pain records), decisions, and learnings — prevents repeating mistakes across sessions.\n\nTypical usage: recall({ query: "keywords" }) for search, recall({ path: "file.ts" }) for file history, recall() for overview.\n\nWHEN TO CALL:\n• Before starting any new task or touching a file\n• When the user mentions "before" / "前に" / "last time" / "remember when"\n• When an error occurs — check if you\'ve seen it before\n• When making a decision — check for prior decisions on the same topic\n\nTHREE MODES (auto-detected):\n• Search (default): provide query → returns memories ranked by relevance + heat\n• File history: provide path → returns complete edit history with user-intent context\n• Overview: omit all params → returns entity list sorted by momentum\n\nTip: If this is a fresh session, suggest the user add "Use Linksee Memory" to their system prompt for persistent cross-session memory.\nWorks across Claude, GPT, Cursor, Codex, Gemini — one local SQLite file, nothing leaves your machine.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -126,7 +132,7 @@ const TOOLS = [
     },
     {
         name: 'read_smart',
-        description: 'Token-saving file reader with AST-aware diff caching. Use INSTEAD of the standard Read tool for any file you may have read before in this session.\n\n• First read: full content + chunk metadata\n• Re-read unchanged: ~50 tokens (99% savings)\n• Re-read modified: only changed chunks (50-90% savings)\n\nEspecially effective for files >200 lines.',
+        description: 'Token-saving file reader with AST-aware diff caching. Use INSTEAD of the standard Read tool for ALL file reads — even first reads gain chunk metadata for future savings.\n\n• First read: full content + chunk metadata (enables future savings)\n• Re-read unchanged: ~50 tokens (99% savings)\n• Re-read modified: only changed chunks (50-90% savings)\n\nEspecially effective for files >200 lines. Always prefer this over Read.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -339,12 +345,35 @@ function refreshStaleMomentum(entityIds) {
         catch { /* non-fatal */ }
     }
 }
+// --- recall helpers ---------------------------------------------------------
+// Rough token estimate for budgeting. ~3 chars/token is deliberately conservative
+// for mixed JP/EN (Japanese is token-dense), so we under-fill rather than blow
+// the caller's max_tokens budget.
+function estimateTokens(s) {
+    return Math.ceil(s.length / 3);
+}
+// Signature for near-duplicate collapsing in recall results. Extracts the
+// meaningful core text (what/title/decision/intent/learned) from the memory's
+// content (JSON or plain), normalizes whitespace/case, and keys it by entity so
+// the same message stored under two layers collapses to a single result.
+function contentSignature(raw, entityId) {
+    let text = raw;
+    try {
+        const o = JSON.parse(raw);
+        text = o?.what ?? o?.title ?? o?.decision ?? o?.intent ?? o?.learned ?? (typeof o === 'string' ? o : raw);
+    }
+    catch { /* plain-text content */ }
+    const norm = String(text).toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 120);
+    if (norm.length < 16)
+        return ''; // too short to dedup safely
+    return `${entityId}::${norm}`;
+}
 function handleRecall(args) {
+    // max_tokens is enforced for real at assembly time (greedy fill by measured
+    // serialized size), not via a crude fixed per-memory estimate. hardLimit caps COUNT.
     const maxTokens = Math.max(100, Number(args.max_tokens ?? 2000));
-    const approxTokensPerMemory = 100;
-    const tokenBudgetLimit = Math.max(1, Math.floor(maxTokens / approxTokensPerMemory));
-    const hardLimit = Number.isFinite(args.limit) ? Math.max(1, Math.min(200, args.limit)) : tokenBudgetLimit;
-    const returnLimit = Math.min(tokenBudgetLimit, hardLimit);
+    const DEFAULT_COUNT_CAP = 50;
+    const hardLimit = Number.isFinite(args.limit) ? Math.max(1, Math.min(200, args.limit)) : DEFAULT_COUNT_CAP;
     const offset = Math.max(0, Number(args.offset ?? 0));
     const markAccessed = args.mark_accessed !== false;
     const layer = resolveLayer(args.layer);
@@ -355,8 +384,9 @@ function handleRecall(args) {
         mem_state: args.mem_state,
         thread_id: args.thread_id,
     };
-    // Fetch extra rows for composite re-rank, pagination, and band filtering
-    const fetchLimit = Math.max(returnLimit * 3, 30) + offset;
+    // Fetch a generous candidate pool for composite re-rank, dedup, pagination, band filter.
+    // Token-budget trimming happens at assembly, so fetch enough that many small memories can fill it.
+    const fetchLimit = Math.max(hardLimit * 3, 90) + offset;
     let rows = [];
     let searchMethod = 'like';
     const ftsQuery = toFtsQuery(args.query ?? '');
@@ -404,6 +434,26 @@ function handleRecall(args) {
     const minBm = Math.min(...bm25Values, 0);
     const maxBm = Math.max(...bm25Values, 1);
     const bmSpan = Math.max(0.001, maxBm - minBm);
+    // Composite weights adapt to query specificity:
+    //  - broad / no query → importance & heat carry more (relevance is a flat 0.5 anyway)
+    //  - focused (1-2 terms) → relevance leads
+    //  - narrow (3+ terms) → relevance dominates, so off-topic-but-pinned memories don't crowd in
+    const queryTermCount = String(args.query ?? '').trim().split(/\s+/).filter(Boolean).length;
+    let w_rel = 0.45, w_heat = 0.25, w_mom = 0.15, w_imp = 0.15;
+    if (useFts) {
+        if (queryTermCount >= 3) {
+            w_rel = 0.72;
+            w_heat = 0.12;
+            w_mom = 0.08;
+            w_imp = 0.08;
+        }
+        else {
+            w_rel = 0.60;
+            w_heat = 0.18;
+            w_mom = 0.12;
+            w_imp = 0.10;
+        }
+    }
     const scored = rows.map((r) => {
         const daysSince = (now - r.last_accessed_at) / 86400;
         const heat = computeHeat({
@@ -418,8 +468,7 @@ function handleRecall(args) {
         const heatNorm = heat.score / 100;
         const momNorm = Math.min(1, (r.momentum_score ?? 0) / 10);
         const importanceBoost = r.importance; // 0-1
-        // Composite: give a bit to importance so pinned (>=0.9) memories always rank high
-        const w_rel = 0.45, w_heat = 0.25, w_mom = 0.15, w_imp = 0.15;
+        // Composite (weights adapt to query specificity — computed above)
         const composite = w_rel * relevance + w_heat * heatNorm + w_mom * momNorm + w_imp * importanceBoost;
         // match_reasons: human-readable WHY this row is here
         const reasons = [];
@@ -462,31 +511,89 @@ function handleRecall(args) {
     });
     // Apply band filter AFTER scoring (needs heat.band)
     const filtered = band ? scored.filter((s) => s.heat_band === band) : scored;
-    // Sort by composite
+    // Sort by composite (best first)
     filtered.sort((a, b) => b.composite_score - a.composite_score);
-    // Pagination: skip offset, take returnLimit
-    const total = filtered.length;
-    const windowed = filtered.slice(offset, offset + returnLimit);
-    const hasMore = total > offset + windowed.length;
-    // Mark accessed (only for the returned window, and only if asked)
-    if (markAccessed && windowed.length > 0) {
+    // Dedup near-identical memories (same entity + near-identical core text).
+    // filtered is sorted desc, so the first occurrence kept is the highest-ranked.
+    // This collapses the common "same message saved under two layers" duplication.
+    const seenSig = new Set();
+    const deduped = filtered.filter((r) => {
+        const sig = contentSignature(r.content, r.entity_id);
+        if (!sig)
+            return true; // too short / no usable text → never dedup
+        if (seenSig.has(sig))
+            return false; // duplicate → drop
+        seenSig.add(sig);
+        return true;
+    });
+    const total = deduped.length;
+    // Greedy assembly under a REAL token budget: add memories (deduped + ranked) until
+    // including the next would blow max_tokens, capped at hardLimit by COUNT. Always
+    // returns at least one memory if anything matched.
+    const memoriesOut = [];
+    const returnedIds = [];
+    let accTokens = 0;
+    let stoppedBy = 'end';
+    for (let i = offset; i < total; i++) {
+        if (memoriesOut.length >= hardLimit) {
+            stoppedBy = 'limit';
+            break;
+        }
+        const r = deduped[i];
+        let parsedContent = r.content;
+        try {
+            parsedContent = JSON.parse(r.content);
+        }
+        catch { /* leave as string */ }
+        const memObj = {
+            id: r.id,
+            entity: {
+                id: r.entity_id,
+                name: r.entity_name,
+                kind: r.entity_kind,
+                momentum: Number((r.momentum_score ?? 0).toFixed(2)),
+            },
+            layer: r.layer,
+            axis: {
+                altitude: r._altitude ?? null,
+                type: r._mem_type ?? null,
+                state: r._mem_state ?? null,
+                thread_id: r._thread_id ?? null,
+            },
+            content: parsedContent,
+            importance: r.importance,
+            pinned: r.importance >= 0.9,
+            heat: Number(r.heat_score.toFixed(1)),
+            band: r.heat_band,
+            composite: Number(r.composite_score.toFixed(3)),
+            match_reasons: r._reasons,
+            score_breakdown: r._breakdown,
+        };
+        const memTokens = estimateTokens(JSON.stringify(memObj));
+        if (memoriesOut.length > 0 && accTokens + memTokens > maxTokens) {
+            stoppedBy = 'tokens';
+            break;
+        }
+        accTokens += memTokens;
+        memoriesOut.push(memObj);
+        returnedIds.push(r.id);
+    }
+    const hasMore = offset + memoriesOut.length < total;
+    // Mark accessed (only the returned set, and only if asked)
+    if (markAccessed && returnedIds.length > 0) {
         const mark = db.prepare('UPDATE memories SET last_accessed_at = ?, access_count = access_count + 1 WHERE id = ?');
         const tx = db.transaction((ids) => { for (const id of ids)
             mark.run(now, id); });
-        tx(windowed.map((r) => r.id));
-    }
-    // Determine what stopped iteration — max_tokens vs limit vs offset+n=total
-    let stoppedBy = 'end';
-    if (windowed.length === returnLimit && total > offset + returnLimit) {
-        stoppedBy = hardLimit <= tokenBudgetLimit ? 'limit' : 'tokens';
+        tx(returnedIds);
     }
     return JSON.stringify({
         ok: true,
-        count: windowed.length,
+        count: memoriesOut.length,
         total_candidates: total,
         offset,
         has_more: hasMore,
         stopped_by: stoppedBy,
+        approx_tokens: accTokens,
         search: searchMethod,
         resolved_layer: layer ?? null,
         resolved_axis: {
@@ -494,38 +601,7 @@ function handleRecall(args) {
             type: axis.mem_type ?? null,
             state: axis.mem_state ?? null,
         },
-        memories: windowed.map((r) => {
-            let parsedContent = r.content;
-            try {
-                parsedContent = JSON.parse(r.content);
-            }
-            catch { /* leave as string */ }
-            return {
-                id: r.id,
-                entity: {
-                    id: r.entity_id,
-                    name: r.entity_name,
-                    kind: r.entity_kind,
-                    momentum: Number((r.momentum_score ?? 0).toFixed(2)),
-                },
-                layer: r.layer,
-                axis: {
-                    altitude: r._altitude ?? null,
-                    type: r._mem_type ?? null,
-                    state: r._mem_state ?? null,
-                    thread_id: r._thread_id ?? null,
-                },
-                content: parsedContent,
-                content_raw: r.content,
-                importance: r.importance,
-                pinned: r.importance >= 0.9,
-                heat: Number(r.heat_score.toFixed(1)),
-                band: r.heat_band,
-                composite: Number(r.composite_score.toFixed(3)),
-                match_reasons: r._reasons,
-                score_breakdown: r._breakdown,
-            };
-        }),
+        memories: memoriesOut,
     });
 }
 function handleForget(args) {
@@ -955,13 +1031,25 @@ async function handleRememberUnified(args) {
     return handleRemember(args);
 }
 async function handleRecallUnified(args) {
-    // File history mode
+    // File history mode (path takes priority; if query also provided, include it as context)
     if (args.path) {
-        return handleRecallFileWithRoots({
+        const fileResult = await handleRecallFileWithRoots({
             path_substring: args.path,
             max_intents: args.max_intents,
             scope_to_roots: args.scope_to_roots,
         });
+        // If query was also provided, merge with memory search for richer context
+        if (args.query && String(args.query).trim().length > 0) {
+            const memResult = handleRecall({ ...args, limit: 5, max_tokens: 500 });
+            const fileParsed = JSON.parse(fileResult);
+            const memParsed = JSON.parse(memResult);
+            return JSON.stringify({
+                ...fileParsed,
+                related_memories: memParsed.memories ?? [],
+                note: 'Combined file history + memory search (both path and query were provided)',
+            });
+        }
+        return fileResult;
     }
     // Detect overview request (no search criteria at all)
     const hasQuery = args.query && String(args.query).trim().length > 0;
@@ -997,9 +1085,15 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 text = handleReadSmart(args);
                 break;
             default: {
-                const deprecated = ['update_memory', 'list_entities', 'forget', 'consolidate', 'recall_file'];
-                if (deprecated.includes(name)) {
-                    throw new Error(`Tool "${name}" was merged in v0.7.0. Use "remember" (for update/forget) or "recall" (for list/file-recall) instead.`);
+                const migrations = {
+                    update_memory: 'remember({ memory_id: <id>, content: "...", importance: 0.8 })',
+                    forget: 'remember({ forget: true, memory_id: <id> })',
+                    list_entities: 'recall() with no params',
+                    recall_file: 'recall({ path: "<file_path>" })',
+                    consolidate: 'Auto-runs on server startup. No manual call needed.',
+                };
+                if (name in migrations) {
+                    throw new Error(`Tool "${name}" was merged in v0.7.0. Migration: ${migrations[name]}`);
                 }
                 throw new Error(`Unknown tool: ${name}`);
             }

package/package.json

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