linksee-memory

Local-first agent memory MCP. A cross-agent brain for Claude Code, Cursor, and ChatGPT Desktop — with a token-saving file diff cache that nobody else does.

v0.2.0 makes the package English-first for global launch: the bundled auto-invocation skill is now bilingual (EN + JP), session-extractor patterns cover common English keywords (let's go, pivot, doesn't work, same error again, etc.), and the install CLI shows test examples in both languages. No API changes. See CHANGELOG.

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

🎬 See it in action

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.

🧠 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 get compressed into learning entries via consolidate().

What it does

Most "agent memory" services (Mem0, Letta, Zep) save a flat list of facts. Then the agent looks at "edited file X 30 times" and has no idea why. linksee-memory keeps the WHY.

It is a Model Context Protocol (MCP) server that gives any AI agent four superpowers:

Three pillars

1. Token savings via read_smart — sha256 + AST/heading/indent chunking. Re-reads return only diffs. Measured 86% saved on a typical TS file edit, 99% saved on unchanged re-reads.
2. Cross-agent portability — single SQLite file at ~/.linksee-memory/memory.db. Same brain for Claude Code, Cursor, ChatGPT Desktop.
3. WHY-first structured memory — six explicit layers (goal / context / emotion / implementation / caveat / learning). Solves "flat fact memory is useless without goals".

Install

npm install -g linksee-memory
linksee-memory-import --help   # bundled importer for Claude Code session history

Or use npx ad hoc:

npx linksee-memory             # starts the MCP server on stdio

The default database lives at ~/.linksee-memory/memory.db. Override with the LINKSEE_MEMORY_DIR environment variable.

Register with Claude Code

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

Restart Claude Code. Tools appear as mcp__linksee__remember, mcp__linksee__recall, mcp__linksee__recall_file, mcp__linksee__read_smart, mcp__linksee__forget, mcp__linksee__consolidate.

Recommended: install the skill (auto-invocation)

Installing the MCP alone doesn't teach Claude Code when to call recall / remember. The bundled skill fixes that:

npx -y linksee-memory-install-skill

This copies a SKILL.md to ~/.claude/skills/linksee-memory/. Claude Code auto-discovers it and fires the skill on phrases like "前に…", "また同じエラー", "覚えておいて", new task starts, file edits, and so on — no need to say "use linksee-memory".

Flags: --dry-run, --force, --help.

Optional: auto-capture every session (Stop hook)

Add to ~/.claude/settings.json to record every Claude Code session to your local brain automatically:

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

Each turn end takes ~100 ms. Failures are silent (Claude Code never blocks). Logs at ~/.linksee-memory/hook.log.

Tools

CLI utilities

The 6 memory layers

Each entity (person / company / project / file / concept) can have memories across six layers. The layer encodes meaning, not category:

{
  "goal":    { "primary": "...", "sub_tasks": [], "deadline": "..." },
  "context": { "why_now": "...", "triggering_event": "...", "when": "..." },
  "emotion": { "temperature": "hot|warm|cold", "user_tone": "..." },
  "implementation": {
    "success": [{ "what": "...", "evidence": "..." }],
    "failure": [{ "what": "...", "why_failed": "..." }]
  },
  "caveat":  [{ "rule": "...", "reason": "...", "from_incident": "..." }],
  "learning":[{ "at": "...", "learned": "...", "prior_belief": "..." }]
}

• caveat memories are auto-protected from forgetting (pain lessons, never lost).
• goal memories bypass decay while the goal is active.

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

• ✅ Core 6 MCP tools (remember / recall / recall_file / forget / consolidate / read_smart)
• ✅ Stop-hook auto-capture for Claude Code
• ✅ JP/EN trigram FTS5
• 🚧 PreToolUse hook to auto-intercept Read (zero-config token savings)
• 🚧 Cursor + ChatGPT Desktop adapters
• 🔮 Vector search via sqlite-vec once an embedding backend is chosen (Ollama / API / etc.)
• 🔮 Optional anonymized telemetry → MCP-quality intelligence layer

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

consolidate({ scope: "all", min_age_days: 7 })

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