Linksee Memory

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. Rules you've explicitly hardened 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 -y linksee-memory setup — one command, done.

[](https://www.npmjs.com/package/linksee-memory) [](./LICENSE) [](https://registry.modelcontextprotocol.io/) [](https://glama.ai/mcp/servers/michielinksee/linksee-memory)

🌐 Landing page: linksee-site.vercel.app (includes non-developer onboarding for Claude Desktop / Cursor / Claude Code / OpenAI Codex / Gemini CLI) 📖 Docs: docs.linksee.app — full reference: the product map & drift, install, and all 11 tools

🪄 Three spells to remember

| Say this | What happens | |---|---| | "use linksee" | Recalls relevant memories before acting | | "linksee this" | Saves the decision / lesson right now | | "what's drifting?" | Reconciles reality against your locked decisions |

> Make it automatic: add "Use Linksee Memory" to your system prompt / CLAUDE.md.

🗺️ Not just memory — a product map

Memory is the entry point. Tie it to a map.yaml of how your product fits together, and the linksee-memory map CLI catches drift with file:line evidence:

The 30-second demo above: the README says --export. The code doesn't. Linksee catches it — and shows what else a change would touch.

npx -y linksee-memory map where README.md   # this file belongs to the README node — and what it touches
npx -y linksee-memory map explain readme    # README promises --export; the code doesn't implement it — drift, with evidence
npx -y linksee-memory map affects readme    # changing the README also touches docs, the CLI help, and the npm listing

→ see [The Map](#the-map) for the full flow.

📣 As featured on

• 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

1. Resolve with fix, supersede, acknowledge, or dismiss — plus two gates: harden (PreToolUse will block) and soften (back to a warning)

The make-or-break rule: a divergence accounted for by a recorded resolution (supersede/fix/acknowledge) is NOT drift. Only unaccounted gaps are flagged. This means intentional evolution stays quiet while silent abandonment gets caught.

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" |

---

🗺️ The Map — linksee-memory map

Drift detection (above) checks individual anchors. The Map lifts it to the whole product: a map.yaml describing how value reaches your user (discover → understand → try → adopt → retain → monetize → expand), with typed dependencies between the pieces — README, npm listing, onboarding, the engine that powers them. The reconciler checks that map against your real code, and the CLI answers the question an engineer actually has:

> I'm touching this file — where is it on the map, and what else must move?

1. Where am I? — locate a file (or, with no argument, infer from your recent edits):

$ npx -y linksee-memory map where README.md
"README.md" belongs to this Map node:

  readme  [understand]  convergence
    changes ripple to:
      must fix together (hard):  lp, docs-site
      should align (soft):       onboarding, client-configs
      fyi (may ripple):          telemetry-contract

The blast radius is graded — must fix together vs should align vs fyi — so a wide ripple isn't flat noise.

2. Why is it in this state? — the diagnosis, with file:line evidence:

$ npx -y linksee-memory map explain readme

STATUS
  declared: healthy (active)
  reality:  implemented / matches
  verdict:  declared and reality agree (verified)

EVIDENCE
  ✓ README's Tools section lists where_am_i
      README.md:424 — found "where_am_i" in section "Tools"

Declared state and the reality verdict are shown separately — a hand-declared suspect the scanner refutes reads as "declared suspect, refuted by reality (→ convergence)", not a confusing mix.

3. Whole-project triage: npx -y linksee-memory map status — a health %, what is fixable now in code vs external checks, and any deferral with no expiry (so "accounted-for" can't quietly become a drift graveyard).

How it works

• map.yaml (repo root) is the desired-state source of truth: a journey spine × surface/implementation layers × typed edges (must-stay-consistent-with / should-align-with / realizes).
• reconcile checks each node's declared reality against the code (signal / regex / section_contains / file checks) and overlays a verdict — reality overrides what you hand-declared, with evidence.
• where_am_i is also an MCP tool, so a coding agent can re-anchor itself mid-task.

Commands: where · affects · explain · status · next · reconcile · inspect --json · blueprint. Add --lang ja for Japanese labels.

---

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

| Hook event | Fires on | What it does | |---|---|---| | PreToolUse | Edit / Write / Bash | Checks the pending action against your accepted anchors. A gate_mode:'hard' contradiction is denied; a softer match re-injects the decision as a reminder; no match → nothing happens. | | SessionStart | startup / resume / compact | Replays your locked decisions + open forks into the fresh session — killing the "groundhog day" amnesia where a new agent repeats last week's call. |

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 -y linksee-memory setup offers to wire this into your project's .claude/settings.json (Step 4). To do it by hand, drop this block into .claude/settings.json at your project root — it points at the globally-installed linksee-memory-guard bin, so no build step is needed:

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

| | Mem0 / Letta / Zep | Claude Code auto-memory | linksee-memory | |---|---|---|---| | Drift detection | ❌ | ❌ | ✅ intent ↔ reality divergence tracking | | Cross-agent | △ (cloud) | ❌ Claude only | ✅ single SQLite file | | 6-layer WHY structure | ❌ flat | ❌ flat markdown | ✅ goal / context / emotion / impl / caveat / learning | | File diff cache | ❌ | ❌ | ✅ AST-aware, 50-99% token savings on re-reads | | Active forgetting | △ | ❌ | ✅ Ebbinghaus curve, caveat layer protected | | Local-first / private | ❌ | ✅ | ✅ |

Four pillars

1. Drift detection — declare decisions as anchors, then the engine automatically detects when committed reality diverges from stated intent. Think "Datadog for product decisions" — unaccounted divergences surface as drift, intentional evolution (recorded as supersede/fix) stays quiet.
2. Cross-agent portability — single SQLite file at ~/.linksee-memory/memory.db. Same brain for Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI.
3. WHY-first structured memory — six explicit layers (goal / context / emotion / implementation / caveat / learning). Solves "flat fact memory is useless without goals".
4. Token savings via read_smart — sha256 + AST/heading/indent chunking. Re-reads return only diffs. Measured 86% saved on a typical TS file edit, 99% saved on unchanged re-reads.

🧠 The 6-layer structure

┌─────────────────────────────────────────────────────────────┐
│ 🎯 goal           ← what the user is working toward         │
├─────────────────────────────────────────────────────────────┤
│ 🧭 context        ← why this, why now — constraints, people │
├─────────────────────────────────────────────────────────────┤
│ 💗 emotion        ← user tone signals (frustration, etc.)   │
├─────────────────────────────────────────────────────────────┤
│ 🛠  implementation ← how it was done (+ what failed)         │
├─────────────────────────────────────────────────────────────┤
│ ⚠️  caveat         ← "never do this again" · auto-protected │
├─────────────────────────────────────────────────────────────┤
│ 🌱 learning       ← patterns distilled from cold memories   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
           Ranked recall via relevance × heat × momentum × importance
                  Returns match_reasons explaining each hit

Every memory is tagged with exactly one layer. caveat-layer entries are protected from auto-forgetting. Cold low-importance memories are auto-consolidated into learning entries on server startup.

---

Quick Start — One Command

npx -y 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-inje

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: michielinksee
• Source: michielinksee/linksee-memory
• License: MIT
• Homepage: https://linksee.app

Install and usage instructions live in the source repository linked above.