Linksee Memory

Your agent forgets everything when a session ends. Worse — it silently drifts from what you decided last week.

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. Hard contradictions get blocked.

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.

npm license mcp-registry glama-score

🌐 Landing page: linksee-site.vercel.app (includes non-developer onboarding for Claude Desktop / Cursor / Claude Code / OpenAI Codex / Gemini CLI)

📣 As featured on

• Zenn: あなたの Claude Code、 実は前回のセッションを完全に忘れている — 73 ♡ on Zenn, 165+ users on Hatena Bookmark, picked up by tech blogs + YouTube shorts (May 2026)
• Zenn: あなたの MCP server、 実は Tools しか使ってない (5 blocks 全実装 / v0.3.0) — the 1% of MCP servers that implement all 5 blocks
• Zenn: あなたの Claude memory、 実は Claude にしか残らない (5 LLM 横断する方法) — cross-LLM memory pattern (May 12, 2026)
• Zenn: Glama listing で 3 週間止まった話 (5 つの罠と解決策) — npm + Glama deployment retrospective

「Cordex/Cursor/Code/Gemini 全部につなげられるから、 横断的にできてる MCP ってところがこれのすごいところ」 — Hatena Bookmark, May 2026 (165+ users)

🎬 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:

You:    We deployed last week but it crashed. How did we fix it?
Claude: I don't have access to previous sessions. Can you describe
        what happened and walk me through the problem?

[30 minutes of log-spelunking and re-explanation]

With linksee-memory — Same question, different outcome:

You:    We deployed last week but it crashed. How did we fix it?
Claude: Let me check my caveats...

        🧠 [caveat] NextAuth sessions invalidate when JWT_SECRET
           rotates — redeploy all affected projects in parallel.
           (from session 2026-04-13, importance: 0.9)

        Is this the deploy you're asking about? We hit it when
        we rotated secrets mid-flow.

You:    Yes, exactly. Let's not repeat that.

That single caveat memory is what separates "flat fact storage" from "the agent actually remembers the WHY". linksee-memory stores it across six explicit layers so retrieval stays explainable.

🔍 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.

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

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:

🛡 Re-injection Guard — enforce decisions before the action

Drift detection (above) is post-hoc — it tells you reality diverged after the change lands. The re-injection guard is the pre-action half: it re-surfaces the decision you locked before the agent runs the tool that would break it.

It exists for one specific, infuriating failure mode (anthropics/claude-code#15443): "Claude read the rule, understood it, and still used cp." Having the rule in context isn't enough — so the guard runs outside the agent's volition, as a Claude Code hook:

It is fail-open by construction: any parse / DB / logic error surfaces nothing and lets the action through. The only thing that ever blocks is an explicit hard contradiction on a decision you declared.

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:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|compact",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 15 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 8 }
        ]
      }
    ]
  }
}

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.

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 10 tools that gives any AI agent structured memory + drift detection:

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

npx linksee-memory-setup

This does everything:

1. Registers the MCP server with Claude Code
2. Installs the agent skill (teaches the agent when to recall/remember)
3. Configures auto-capture (every session saved to your local brain)
4. Offers to wire the re-injection guard into this project (pre-action decision enforcement)

Restart Claude Code, then just chat normally. Add "Use Linksee" to any prompt to trigger memory recall.

Manual setup (if you prefer step-by-step)

claude mcp add -s user linksee -- npx -y linksee-memory

npx -y linksee-memory-install-skill

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}

Other editors / CLIs

Linksee Memory is a standard MCP server (stdio). Any tool that speaks MCP can connect:

{
  "mcpServers": {
    "linksee": {
      "command": "npx",
      "args": ["-y", "linksee-memory"]
    }
  }
}

{
  "mcpServers": {
    "linksee": {
      "command": "npx",
      "args": ["-y", "linksee-memory"]
    }
  }
}

codex --mcp-server "npx -y linksee-memory"

{
  "mcpServers": {
    "linksee": {
      "command": "npx",
      "args": ["-y", "linksee-memory"]
    }
  }
}

{
  "mcpServers": {
    "linksee": {
      "command": "npx",
      "args": ["-y", "linksee-memory"]
    }
  }
}

All editors share the same ~/.linksee-memory/memory.db. A decision made in Claude Code is recalled in Cursor. A caveat recorded in Windsurf prevents the same mistake in Codex.

Database location

Default: ~/.linksee-memory/memory.db. Override with LINKSEE_MEMORY_DIR env var.

What's new in v0.9

What's new in v0.8

10 Tools (v0.10)

Memory tools

Drift tools (v0.8.0)

Fork-point tools (v0.10)

Previous versions exposed 3 tools — v0.8.0 added 4 drift tools that let agents query and act on product-level intent ↔ reality divergence; v0.10 added the fork-point trio for orphaned-proposal triage. The memory tools are unchanged.

CLI utilities

The 6 memory layers

Each entity (person / company / project / file / concept) can have memories across six layers. Since v0.4, each memory uses the 3-axis structured format (altitude × type × state):

{
  "title": "freee OAuth token expires in 24h",
  "altitude": "implementation",
  "type": "outcome",
  "state": "done",
  "what": "freee OAuth token expires in 24 hours. Must refresh proactively.",
  "why": "freee uses short-lived tokens unlike most SaaS (usually 30-90 day expiry)",
  "affects": ["src/integrations/freee/auth.ts"],
  "next_action": null
}

• caveat memories are auto-protected from forgetting (pain lessons, never lost).
• goal memories bypass decay while the goal is active.
• state tracks lifecycle: open → decided → in_progress → done / stalled / superseded.

Architecture

A single SQLite file (better-sqlite3 + FTS5 trigram tokenizer for JP/EN) contains five layers:

• Layer 1 — entities (facts: people / companies / projects / concepts / files)
• Layer 2 — edges (associations, graph adjacency)
• Layer 3 — memories (6-layer structured meanings per entity)
• 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({ 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

• Local-first — your conversation history is private. Nothing leaves your machine.
• Single file — memory.db is one portable artifact. Backup = file copy.
• MCP stdio — works with every agent that speaks MCP, no plugins per host.
• Reuses proven schemas — heat_score / momentum_score ported from a production sales-intelligence codebase. Rule-based, no LLM dependency in the hot path.

Roadmap

• ✅ 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)
• ✅ Cross-LLM: Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI
• ✅ Landing page (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)

Comparison with Claude Code auto-memory

Claude Code ships a built-in memory feature at ~/.claude/projects/<path>/memory/*.md — flat markdown notes for user preferences. linksee-memory complements it:

• auto-memory = your scrapbook of "remember I prefer X"
• linksee-memory = structured cross-agent brain with file diff cache and per-edit WHY

Use both.

Telemetry (opt-in, off by default)

linksee-memory ships with opt-in anonymous telemetry that helps us understand which MCP servers and workflows actually work in the wild. Nothing is sent unless you explicitly enable it. No conversation content, no file content, no entity names, no project paths — ever.

Enable

export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)

Exactly what gets sent (Level 1 contract)

After each Claude Code session ends, the Stop hook sends one POST to https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee containing only these fields:

What is NEVER sent:

• ❌ Conversation messages (user or assistant)
• ❌ File contents
• ❌ Entity names, project names, file paths, URLs
• ❌ Memory-layer text (goal / context / emotion / impl / caveat / learning)
• ❌ Authentication tokens, API keys, secrets
• ❌ Your IP address (only a one-way hash for abuse detection)

Why we ask

Aggregated MCP-usage data helps the KanseiLink project rank which agent integrations actually work for real developers. If you're happy to contribute, LINKSEE_TELEMETRY=basic takes 1 second to set and helps the entire MCP ecosystem improve.

The full payload schema and validation logic is open-source — read src/lib/telemetry.ts if you want to verify exactly what leaves your machine.

Pricing

Free forever.

linksee-memory is local-first and runs entirely on your machine. There is no hosted component you need to pay for. The SQLite DB lives in your home directory; backup = file copy.

No account, no credit card, no API key. Just install and use.

Troubleshooting

npx linksee-memory-import --all

recall({ query: "...", max_tokens: 800 })   // default is 2000

recall({ query: "...", entity_name: "my-project", layer: "caveat" })

rm -rf ~/.linksee-memory   # nuke everything; next run creates a fresh DB

FAQ

Support

• Issues & bug reports: github.com/michielinksee/linksee-memory/issues
• Feature requests: open an issue with the enhancement label
• Security concerns: see SECURITY.md if present, or file a private advisory on GitHub
• Company: Synapse Arrows PTE. LTD. (Singapore)

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:

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.

• Bilingualized SKILL.md (auto-invocation skill). The bundled skill that linksee-memory-install-skill copies into ~/.claude/skills/linksee-memory/SKILL.md was Japanese-first; it is now English-primary with Japanese trigger phrases preserved inline. English speakers now get the skill firing on natural English phrases ("how did we solve this before?", "same error again", "remember this") in addition to the existing JP triggers.
• Install-skill CLI output is bilingual: example test phrases shown after installation include both English and Japanese.
• Session-extractor EN coverage (linksee-memory-import): expanded regex patterns for decisions, failures, and caveats so English Claude Code session logs get auto-tagged correctly. Additions include let's go, pivot, switch to, settled on, approved, doesn't work, stuck, same error again, hit an error, debug, broke, revert.
• Clearer caveat-forget error hint: the previous message said "lower importance below 0.9 first, then forget" which was misleading — caveat-layer memories are permanently protected regardless of importance. The hint now correctly distinguishes layer-protection from pin-protection.
• README rework for launch readiness: added a "See it in action" before/after scenario, ASCII 6-layer diagram, MCP Official Registry + Glama score badges, landing-page link, and an 8-item FAQ covering questions that surface during public launches.
• Internal: SKILL.md now documents pairing with KanseiLink skill as an English workflow example.

No code changes to the MCP protocol surface; all existing MCP clients continue to work unchanged.

v0.1.1 — Pin threshold tweak (2026-04-19)

Based on real-world feedback that importance=0.95 memories were not being treated as pinned despite intent.

• Pin threshold lowered from >= 1.0 to >= 0.9. Memories with importance >= 0.9 are now exempt from the auto-forget sweep and surface pinned: true in recall and remember responses. This matches the natural mental model ("0.9 = high importance = should survive cleanup") without requiring exact 1.0.
• All existing memories with importance >= 0.9 (including older ones set to 0.9 or 0.95) become pinned automatically — no migration needed.
• Updated tool descriptions and error messages to reflect the new threshold.

v0.1.0 — Major UX update (2026-04-18)

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.

recall enhancements

• match_reasons array on each memory: e.g. ["content_match_fts", "heat:hot", "pinned"].
• score_breakdown with per-dimension scores (relevance / heat / momentum / importance).
• Pagination via offset / has_more / stopped_by.
• limit parameter (hard cap, complements max_tokens budget).
• band filter to request only hot/warm/cold/frozen memories.
• mark_accessed=false for preview queries that shouldn't bump heat.
• Layer aliases: decisions → learning, warnings → caveat, how → implementation, etc.
• Fix: opportunistic refresh of stale entity momentum scores. Entities recalled >1 h after last remember() no longer return stale momentum.

remember enhancements

• Quality check: rejects pasted assistant output / CI logs / stack traces unless force=true.
• importance=1.0 now implicitly pins the memory (survives auto-forget).
• Layer aliases accepted.

forget changes

• Pinned memories (importance=1.0) now preserved alongside caveat-layer memories.
• Clear error response when attempting to delete a protected or missing memory.
• dry-run now includes sample_ids_to_drop.

consolidate changes

• dry_run: true preview mode — reports cluster count + candidates without writing.

Infra

• Fixed fresh-DB migration bug (was querying meta table before it existed).
• Bumped to Node 20+ for structured language feature usage.

All changes are backward compatible — existing integrations continue to work. Server.ts version banner now reports v0.1.0.

Older versions

See GitHub Releases.

License

MIT — Synapse Arrows PTE. LTD.