本地首选MCP工具

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

<details> <summary>Click to expand manual installation</summary>

Install & register:

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.

Install the skill (auto-invocation):

npx -y linksee-memory-install-skill

Copies SKILL.md to ~/.claude/skills/linksee-memory/. Agent auto-fires on phrases like "前に…", "また同じエラー", "覚えておいて", new task starts, file edits, etc.

Configure auto-capture (Stop hook):

Add to ~/.claude/settings.json:

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

Each turn end takes ~100 ms. Failures are silent. Logs at ~/.linksee-memory/hook.log.

</details>

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)

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

CLI utilities

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.

Troubleshooting

<details> <summary><b>The skill isn't firing — Claude Code doesn't call <code>recall</code> when I ask about past work.</b></summary>

1. Verify the skill was installed:

   ls ~/.claude/skills/linksee-memory/SKILL.md
   

   claude mcp list | grep linksee
   

<details> <summary><b>Stop hook isn't recording my sessions.</b></summary>

1. Check the hook log: cat ~/.linksee-memory/hook.log 2. Run a manual test:

   echo '{"session_id":"test","transcript_path":"/path/to/some.jsonl"}' | npx linksee-memory-sync
   

<details> <summary><b>Upgrading from v0.0.5 or earlier — my recalls are mostly tagged "Card_Navi" or my project-dir name.</b></summary>

v0.0.6+ fixed the entity detection bug that collapsed all memories into the session's starting cwd. To re-index existing history with correct project attribution, run:

npx linksee-memory-import --all

The importer is idempotent (wipes existing session data before re-inserting). Typical runtime: a few minutes for hundreds of sessions. Expect a dramatic improvement in recall precision afterward. </details>

<details> <summary><b><code>recall</code> returns too much — the context window fills up fast.</b></summary>

Reduce max_tokens:

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

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

<details> <summary><b>How do I reset / delete all memory?</b></summary>

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. </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 })

FAQ

<details> <summary><strong>How is this different from Mem0 / Letta / Zep?</strong></summary>

Three axes: 1. Local-first: those tools require cloud accounts and send your data to their servers. linksee-memory runs entirely on your machine — one SQLite file, no network calls by default. 2. WHY-layered: they store flat facts or knowledge-graph nodes. linksee-memory has 6 explicit layers (goal/context/emotion/implementation/caveat/learning) so retrieval returns structured reasoning, not just data. 3. File diff cache: read_smart tool saves 86–99% of tokens on file re-reads via AST-aware chunking. None of the memory services do this — it's a feature usually shipped in IDEs. </details>

<details> <summary><strong>Why not just use Claude's built-in auto-memory?</strong></summary>

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 </details>

<details> <summary><strong>Is 86% token savings real? Where does it come from?</strong></summary>

Yes — see tools/bench-read-smart.ts in the repo. The read_smart tool: 1. Hashes file content on first read, returns full content + chunk metadata (AST/heading/indent boundaries). 2. On re-read with unchanged mtime+sha256, returns ~50 tokens of "unchanged" confirmation instead of re-sending the file. 3. On real edits, returns only the changed chunks as full content + unchanged chunks as metadata-only references.

For a typical TypeScript file edit in an agentic loop, this cuts round-trip token costs by ~86%. On pure re-reads (user navigating back to a previously-read file), savings exceed 99%. </details>

<details> <summary><strong>Does "local-first" mean no way to sync across my machines?</strong></summary>

The default is no sync — the SQLite file lives at ~/.linksee-memory/memory.db and stays there. If you want multi-machine sync, put that directory under Syncthing / iCloud Drive / Dropbox / Google Drive — it's a single file, so any file-sync tool works. (Avoid simultaneous edits from two machines while the MCP server is running on both; SQLite's WAL mode handles single-writer well but multi-writer conflicts can corrupt.) </details>

<details> <summary><strong>What happens when the DB gets huge?</strong></summary>

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

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>

<details> <summary><strong>Can I use this without Claude Code?</strong></summary>

Yes — any MCP-compatible client works: - Claude Code: claude mcp add -s user linksee -- npx -y linksee-memory - Claude Desktop: add to claude_desktop_config.json (see onboarding on the LP) - 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. - Custom agent: the MCP stdio protocol is documented at modelcontextprotocol.io </details>

<details> <summary><strong>What telemetry does it send?</strong></summary>

By default: zero network calls, zero telemetry. There's an optional Level-1 telemetry mode you can enable that sends anonymized aggregate metrics (tool call counts, error rates, latency percentiles — never memory content, never file paths, never queries). The exact payload schema is documented in the Telemetry section and you see every byte before opting in. </details>

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