🌐 English | 繁體中文 | 简体中文 | 日本語 | 한국어 | Português | Français | Deutsch | Tiếng Việt | Español | ภาษาไทย

MeMesh LLM Memory

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

[!IMPORTANT] Actively developed project — features evolve and may change between releases. If you hit a bug or have a feature request, please open an issue.

The Problem

Your coding agent forgets what happened 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.

This package is the local memory layer of the MeMesh product family. It is intentionally small and open-source: install it with npm, keep your memory in ~/.memesh/knowledge-graph.db, and connect it to Claude Code or any MCP-compatible client. Hosted workspace and enterprise operating-system products should stay separate from this package's README and roadmap.

Proof — 95.40% R@5 on LongMemEval-S

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

Reproduction commands, dataset SHA256, raw per-question results, and known-failure analysis are all in benchmarks/longmemeval/. Re-runnable in ~10 seconds.

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<br/>(chat + agent)"]:::client
      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
    end

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

    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db

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

Which one do you need?

⚠️ 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 <command> 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?

Designed For Coding Agents First

memesh-mcp

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

memesh export-schema \
  --format openai

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

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:

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.

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 <ver> is DEPRECATED banner and memesh update-status surfaces the same line until you upgrade. The check is cached at ~/.memesh/update-check.<version>.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.

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 (15%) + confidence (15%) + recall impact (10%) + temporal validity (5%).

🔄 Knowledge Evolution — Decisions change. forget archives old memories (never deletes). supersedes relations link old → new. Your AI always sees the latest version.

⚠️ Conflict Detection — If you have two memories that contradict each other, MeMesh warns you.

🕸️ Knowledge Graph Connectivity — memesh kg backfill-relations --all-rules links orphan entities using tag co-occurrence, project clustering, session context, and name similarity — no LLM required. Reduces orphan rate from 89% to under 12% on a representative knowledge base.

📦 Team Sharing — memesh export > team-knowledge.json → share with your team → memesh import team-knowledge.json Imported bundles stay searchable, but MeMesh does not auto-inject imported memories into Claude hooks until you review or re-store them locally.

Example Usage

"MeMesh remembered that we chose PKCE over implicit flow three weeks ago. When I asked Claude about auth again, it already knew — no re-explaining needed." — Solo developer, building a SaaS

"We export our team's memory every Friday and import it Monday. Everyone's Claude starts the week knowing what the team learned last week." — 3-person startup, shared knowledge base

"The dashboard showed me that 90% of my memories were auto-generated session logs. I started using remember deliberately for architecture decisions. Game changer." — Developer who discovered the Analytics tab

Unlock Smart Mode (Optional)

MeMesh works offline by default — recall stays strictly LLM-free (95.40% R@5 on LongMemEval-S out of the box). Add an LLM API key only if you want LLM-augmented analysis flows on top: smarter session extraction, auto-tagging of new memories, lesson generation from failures, and consolidate / dream compression:

memesh config set llm.provider anthropic
memesh config set llm.api-key sk-ant-...

Or use the dashboard Settings tab (visual setup):

memesh  # opens dashboard → Settings tab

All 9 Memory Tools

Architecture

                    ┌─────────────────┐
                    │   Core Engine   │
                    │  (8 operations) │
                    └────────┬────────┘
           ┌─────────────────┼─────────────────┐
           │                 │                 │
     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
           │                 │                 │
           └─────────────────┼─────────────────┘
                             │
                    SQLite + FTS5 + sqlite-vec
                    (~/.memesh/knowledge-graph.db)

Core is framework-agnostic. Same logic runs from terminal, HTTP, or MCP.

Upgrading

Claude Code's plugin marketplace pins versions at install time and does not auto-update. To pick up a new release:

Option A — /plugin UI: uninstall memesh@pcircle-memesh, then reinstall. Claude Code fetches the latest marketplace version.

Option B — one-line script (no UI clicking, idempotent):

# If your plugin install is v4.2.5 or newer, the script ships inside it:
bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh

# If you installed before v4.2.5 (i.e. you're on v4.2.4 or v4.2.3),
# the script isn't in your plugin yet. Use the npm-global copy instead:
bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"

# (That assumes you've also run `npm install -g @pcircle/memesh`. If you
# haven't, this is also a good moment to — see the "Install paths at a
# glance" section above for why most users want both paths.)

The script fast-forwards the marketplace cache, stages the new version under ~/.claude/plugins/cache/, installs runtime deps, and re-points installed_plugins.json. Restart Claude Code afterwards so the MCP server reconnects.

npm-global installs (npm install -g @pcircle/memesh) can self-update via memesh update. Source checkouts: git pull && npm install && npm run build.

Session start surfaces a one-line banner (throttled to once per 24h per version) when a newer release is available, and memesh doctor reports the upgrade target with the channel-specific command.

Contributing

git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
cd memesh-llm-memory && npm install && npm run build
npm test             # 630 tests
npm run test:e2e-dashboard

Dashboard: cd dashboard && npm install && npm run dev

MIT — Made by PCIRCLE AI