Memesh Llm Memory

🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)

MeMesh LLM Memory

Local memory for Claude Code and MCP coding agents. One SQLite file. No Docker. No cloud required.

---

MeMesh — the open-source memory layer for Claude Code & MCP agents. One SQLite file. No cloud. Plugs into any LLM.

95.60% R@5 on LongMemEval-S — beats Mem0 by 46 points

MeMesh's retrieval is FTS5 alone — no LLM, no embeddings on the hot path. Measured against the public LongMemEval-S benchmark (500 questions, MIT-licensed):

| System | R@5 | Source | |---|---|---| | MeMesh (Mode A, via recallEnhanced()) | 95.60% | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) | | MemPalace | 96.6% | Vendor self-report | | Supermemory | ~82% | Vendor estimate | | Zep | 63.8% | LongMemEval paper | | Mem0 | 49.0% | LongMemEval paper |

Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question results, and known-failure analysis: [benchmarks/longmemeval/REPRODUCE.md](benchmarks/longmemeval/REPRODUCE.md).

---

The Problem

Your coding agent forgets between sessions. Every architecture decision, bug fix, failed test, and hard-won lesson has to be re-explained. Claude Code starts fresh, re-discovers old constraints, and burns context on things it should already know.

MeMesh gives coding agents persistent, searchable, evolving local memory. Install with npm, memory lives in ~/.memesh/knowledge-graph.db, plug into Claude Code or any MCP-compatible client.

> [!IMPORTANT] > Actively developed — features may change between releases. Open an issue for bugs or feature requests.

---

Install paths at a glance

MeMesh has two install paths that coexist. Most users want both. They write to the same memory database (~/.memesh/knowledge-graph.db), so memories captured in Claude Code chat appear in your shell, and vice versa.

flowchart TB
    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px

    subgraph clients["Where you use memesh from"]
      direction LR
      CC["Claude Code(chat + agent)"]:::client
      TERM["Terminal / otherMCP clients(Cursor, Cline...)"]:::client
    end

    subgraph paths["Two install paths"]
      direction LR
      A["Path A — /plugin install───────────────Lives in ~/.claude/plugins/• MCP tools in chat• Auto-capture hooks• /memesh skill• Session-start banner"]:::pathA
      B["Path B — npm install -g───────────────Lives in $(npm prefix -g)/bin/• memesh shell command• memesh-mcp, -http, -view bins• For Cursor / Cline / other MCP"]:::pathB
    end

    DB[("Shared memory DB~/.memesh/knowledge-graph.dbSame data, both paths see it")]:::db

    CC -->|uses| A
    TERM -->|uses| B
    A --> DB
    B --> DB

Which one do you need?

| What you want to do | Install path | |---|---| | Use the /memesh skill inside a Claude Code conversation | Path A (plugin) | | Get auto-capture (sessions → lessons → recall) in Claude Code | Path A (plugin) | | Run memesh remember / memesh recall / memesh doctor in any terminal | Path B (npm-global) | | Open the local dashboard via memesh (no npx lookup delay) | Path B (npm-global) | | Plug memesh-mcp into Cursor, Cline, or another MCP client | Path B (npm-global) | | All of the above | Install both — they don't conflict |

⚠️ Installing the plugin does NOT install the CLI

This is the most common confusion. Read this once and you'll save yourself the loop:

• /plugin install memesh@pcircle-memesh from inside Claude Code → installs Path A only. Gives you MCP tools, hooks, the /memesh skill. Does NOT put memesh on your shell PATH.
• memesh reindex / memesh update / memesh doctor typed in a normal terminal → needs Path B (npm-global). Without it: zsh: command not found: memesh.
• Recommended setup for Claude Code users: install both. They coexist, share the same database, never conflict.

# After /plugin install ..., also run this:
npm install -g @pcircle/memesh

If you only use memesh through Claude Code chat (never type memesh in a terminal), Path A alone is enough. Everyone else: install both.

---

Get Started in 60 Seconds

Option A — Claude Code plugin (one-line install)

If you use Claude Code, install MeMesh as a plugin from inside the CLI:

/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
/plugin install memesh@pcircle-memesh

Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the /memesh skill (remember / recall / learn / forget) inside the Claude Code conversation, and remember / recall / forget / learn available as MCP tools to the agent.

The MCP server runs directly from the plugin's bundled compiled output — no npx lookup, no build step needed. If the native better-sqlite3 binding is missing on first start (e.g. after a Node major upgrade), the launcher self-heals by rebuilding it in-process.

> This installs the plugin only. You can run CLI commands via npx @pcircle/memesh if you absolutely don't want a global install, but typing plain memesh in a terminal will report command not found. To get a real shell memesh command, also run Option B below — both paths coexist and share the same memory database. The "Install paths at a glance" diagram above covers this.

Option B — npm global (optional optimisation)

If you want the binary directly on your shell PATH (so plain memesh, memesh-mcp, etc. work in any terminal without the per-call npx lookup), or you want to expose memesh-mcp as a fixed-path stdio command to non-Claude-Code MCP clients (Cursor, Cline, terminal-only flows):

npm install -g @pcircle/memesh

> First-install notes (one-time): > - Native modules — better-sqlite3 and sqlite-vec install via prebuilt binaries on macOS (arm64/x64), Linux (x64/arm64), and Windows x64. On uncommon platforms or when prebuilds fail, you'll need a working C/C++ toolchain. > - Embedding model — the first call that triggers a local embedding (e.g. recall with semantic mode) downloads Xenova/all-MiniLM-L6-v2 (~80 MB) into ~/.memesh/models/. Subsequent calls are instant. The default retrieval path (FTS5) does not require this download.

Step 1.5: Wire MeMesh into Claude Code (npm path only)

If you installed via Option A (/plugin install memesh@pcircle-memesh), skip this step — Claude Code wires plugin hooks automatically.

If you installed via Option B (npm install -g), the CLI is on your PATH and the MCP server is registered, but the Claude Code session hooks are not auto-wired. Without them you can still use memesh remember / recall manually, but the auto-capture loop (sessions → lessons → recall on next session) is silent.

memesh install-hooks         # adds memesh's hooks to ~/.claude/settings.json
memesh doctor                # verifies "Hooks wired into Claude Code" passes

The hooks coexist with any custom hooks you already have under ~/.claude/hooks/ — install-hooks writes additive entries and never overwrites yours. To remove later: memesh uninstall-hooks.

Step 2: Store a decision

> The bash examples below assume memesh is on your PATH (Option B). Option A (plugin-only) users have two equivalent paths: ask in the Claude Code conversation (the /memesh skill + MCP tools cover the same flows), or replace memesh with npx @pcircle/memesh in any shell — same flags, no global install needed.

memesh remember "Use OAuth 2.0 with PKCE for the new auth"

Or use the explicit form when you want a stable name and type for later filtering:

memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"

Step 3: Recall it later

memesh recall "login security"
# → Finds "OAuth 2.0 with PKCE" even though you searched different words

That's it. MeMesh is now remembering and recalling across sessions.

If you want to verify the install and local wiring end to end:

memesh doctor

Open the dashboard to explore your memory:

memesh

---

Who Is This For?

| If you are... | MeMesh helps you... | |---------------|---------------------| | A developer using Claude Code | Auto-recall project decisions, file-specific lessons, and past failures as you work | | A coding-agent power user | Share one local memory layer across MCP-compatible tools | | A team experimenting with AI coding workflows | Export/import project knowledge without introducing hosted infrastructure | | An agent developer | Add local memory through MCP, HTTP, CLI, or the Python SDK |

---

Designed For Coding Agents First

Claude Code / Desktop

memesh-mcp

MCP tools + Claude Code hooks

Any HTTP Client

curl localhost:3737/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"query":"auth"}'

memesh serve (REST API)

Any LLM (OpenAI format)

memesh export-schema \
  --format openai

Paste tools into any API call

---

Why Not OpenMemory, Cursor Memories, Mem0, Or Zep?

| | MeMesh | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti | |---|---|---|---|---|---| | Best fit | Local memory for coding agents | Local/cross-client MCP memory | Cursor-native project memory | Managed app/agent memory | Temporal knowledge graphs | | Install shape | npm install -g @pcircle/memesh | Local app/server flow | Built into Cursor | Cloud API / SDK / MCP | Service/framework setup | | Storage | One local SQLite file | Local memory stack | Cursor-managed rules/memories | Hosted or self-hosted stack | Graph database | | Cloud required | No | No for local mode | Depends on Cursor account/settings | Yes for platform | Usually yes/self-hosted | | Claude Code hooks | First-class | MCP tools | No | MCP tools | Not Claude Code-specific | | Dashboard | Built in | Built in | Cursor settings | Platform dashboard | Platform/graph tooling | | Tradeoff | Simple local wedge, not enterprise scale | Broader local app footprint | Locked to Cursor | Strong managed platform, less local-first | Strong graph model, heavier setup |

MeMesh trades enterprise-scale managed infrastructure for instant local setup, inspectable storage, and coding-agent workflow hooks.

---

What Happens Automatically In Claude Code

You don't need to manually remember everything. MeMesh has 7 hooks that capture and inject knowledge while you work:

| When | What MeMesh does | |------|------------------| | Every session start | Loads your most relevant memories + proactive warnings from past lessons | | Before editing files | Recalls memories tied to the file or project before Claude writes code | | Before bash commands | (Opt-in) Nudges Claude to dispatch high-verifiability commands (test, build, lint, migrate, deploy, benchmark) as background agents | | When you ask to remember | Detects "remember this" / "guardar en memesh" / "sauvegarder dans memesh" / "記下來" intent (5 languages) and reminds Claude to use memesh | | After every git commit | Records what you changed, with diff stats | | When Claude stops | Captures files edited, errors fixed, and auto-generates structured lessons from failures | | Before context compaction | Saves knowledge before it's lost to context limits |

> Opt out anytime: export MEMESH_AUTO_CAPTURE=false

---

Configuration

All configuration is via environment variables. Defaults are local-only and zero-network — you don't need to set anything to get a working system.

| Variable | Default | What it does | |---|---|---| | MEMESH_DB_PATH | ~/.memesh/knowledge-graph.db | Override the SQLite database location. | | MEMESH_AUTO_CAPTURE | true | Disable the auto-capture hooks (Stop, PreCompact) entirely. | | MEMESH_AUTO_DETECT_LLM | unset (auto-detect on) | Set to 0 to stop memesh using an API key it finds in your shell env. By default, if ANTHROPIC_API_KEY / OPENAI_API_KEY / OLLAMA_HOST is set and you have not configured a provider in ~/.memesh/config.json, memesh uses it for write-side LLM features (consolidation, lesson extraction, auto-tagging, dream). Embeddings are unaffected — they stay local ONNX (384-dim) unless you explicitly set embedder.provider. | | MEMESH_ENABLE_AGENTIC_ORCHESTRATION | unset | Set to 1 to enable an experimental working-model protocol (CTO / Orchestrator / Agents framing). Adds a session-start banner, a Bash command nudge, and verify_agent_work telemetry. The protocol's effectiveness is being instrumented, not yet proven — opt in if you want to participate. Default is OFF: the core memory features work without this flag. | | MEMESH_AUTO_UPDATE | off | Auto-update policy. off (default) never auto-updates; patch allows X.Y.Z → X.Y.Z+N; minor adds X.Y.Z → X.Y+1.0; major allows any bump. When permitted, a detached npm install -g fires at session end (Stop hook) so it never blocks your work — outcomes land in ~/.memesh/auto-update.log. Also settable as autoUpdate in ~/.memesh/config.json (env wins). When the installed version is deprecated by maintainers (security advisory), patch is force-allowed even on off — minor / major bumps still stay manual to avoid silent behaviour drift. | | OPENAI_API_KEY | unset | Your OpenAI key. Used automatically for LLM features unless you set MEMESH_AUTO_DETECT_LLM=0 or configure a provider explicitly. | | OLLAMA_HOST | http://localhost:11434 | Override the Ollama endpoint when using a local Ollama provider. |

memesh doctor prints the resolved configuration so you can see what's active.

When npm flags an installed version as deprecated (typically a security advisory), the next session-start prepends a strong ⚠️ MeMesh is DEPRECATED banner and memesh update-status surfaces the same line until you upgrade. The check is cached at ~/.memesh/update-check..json so a transient network failure can't dim the warning.

---

Dashboard

8 tabs, 11 languages, zero external dependencies. Access at http://localhost:3737/dashboard when the server is running.

| Tab | What you see | |-----|-------------| | Insights | Memory insights — weekly recaps and pattern proposals from the dreamer engine; one-click accept/reject | | Search | Full-text + vector similarity search across all memories | | Browse | Paginated list of all entities with archive/restore | | Analytics | Memory Health Score, 30-day timeline, PM velocity + KG connectivity metrics, work patterns, cleanup suggestions | | Graph | Interactive force-directed knowledge graph with type filters, search, ego mode, recency heatmap | | Lessons | Structured lessons from past failures (error, root cause, fix, prevention) | | Manage | Archive and restore entities | | Settings | LLM provider config, instant language selector |

---

Smart Features

🧠 Smart Search — Search "login security" and find memories about "OAuth PKCE". MeMesh expands queries with related terms using your configured LLM.

📊 Scored Ranking — Results ranked by relevance (30%) + recency (25%) + frequency (18%) + confidence (17%) + recall impact (10%).

🔄 Knowledge Evolution — Decisions c

…

Source & license

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

• Author: PCIRCLE-AI
• Source: PCIRCLE-AI/memesh-llm-memory
• License: MIT
• Homepage: https://pcircle.ai/memesh-llm-memory

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