Claude Code Buddy (CCB)

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

MeMesh

Agentic memory for coding agents.
One SQLite file. No Docker. No cloud required.

MeMesh — open-source agentic memory for Claude Code & MCP coding agents: captured from the agent's real work, injected at the moment it acts, kept honest when it contradicts itself. One SQLite file. No cloud.

The Problem

Your coding agent doesn't just forget facts between sessions — it repeats work. It re-proposes the approach you rejected last month, trips over the same failing test, re-discovers the constraint that broke production in March, and asks you to re-explain the architecture it helped design.

That's not a chat-history problem; it's an agent-memory problem. What needs to survive between sessions is the work: decisions with their reasons, failures with their fixes, and the links between them.

MeMesh is that memory. Hooks capture it from what the agent actually does (sessions, commits, failures — not manual notes), recall injects it at the moment the agent acts (session start, before file edits), and the knowledge-graph layer keeps it honest over time (supersession, LLM-judged conflict detection). 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<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
/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, and nothing to compile. memesh stores its data through node:sqlite, which is part of Node itself (22.13+), so a Node upgrade cannot leave it with a binary built for the wrong runtime.

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 (Codex CLI, Gemini CLI, Cursor, Cline, terminal-only flows):

npm install -g @pcircle/memesh

First-install notes (one-time):

• No compiler needed — the database engine is Node's own node:sqlite. sqlite-vec, which adds meaning-based search, ships as a prebuilt file for macOS (arm64/x64), Linux (x64/arm64) and Windows x64; on any other platform it is simply absent and recall stays on keyword search. Nothing here runs an install script, so npm install --ignore-scripts installs a fully working memesh.
• Semantic (meaning-based) search is optional — the default recall path is FTS5 keyword search, which needs no model and no download. Meaning-based search needs an embedder: run Ollama locally, or configure a cloud embedder (see "Bring-your-own embeddings" below). Without one, memesh uses keyword search only.

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.

Same memory from Codex CLI and Gemini CLI

memesh-mcp is a plain stdio MCP server, so any MCP-capable host can talk to it — not just Claude Code. With Option B installed (memesh-mcp on your PATH), register it once per host:

# OpenAI Codex CLI — writes [mcp_servers.memesh] into ~/.codex/config.toml
codex mcp add memesh -- memesh-mcp

# Google Gemini CLI — user scope, so it works in every folder
gemini mcp add -s user memesh memesh-mcp

Every host reads and writes the same ~/.memesh/knowledge-graph.db, so a memory stored from a Claude Code session is recallable from Codex or Gemini, and the other way around. Verify from either host by asking it to call the recall tool, or from a terminal:

codex mcp list       # memesh should be listed as enabled
gemini mcp list      # memesh should show "Connected"

Use memesh-mcp, not npx -p @pcircle/memesh, as the configured command. npx -p resolves to the local package whenever the host's working directory is inside a checkout of this repository, silently running whatever state that working tree is in instead of the installed release.

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 serve

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.

Benchmarks — 95.60% R@5 on LongMemEval-S

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

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

What Happens Automatically In Claude Code

You don't need to manually remember everything. MeMesh has 6 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.

Fallback LLM providers (Smart Mode). In the dashboard Settings → "Fallback providers" you can set an ordered failover chain — memesh tries each provider in turn when your primary is down. Add a local Ollama fallback, or a cloud one (OpenAI / Anthropic, with an API key). Privacy tradeoff: when a cloud fallback is used, memory text — which can be private — is sent to that provider, so it matters if you run local-only for privacy.

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 uses FTS5 + sqlite-vec on the hot path, LLM-free, and the vector supplement still reaches across related wording.

🌏 Search in scripts that don't use spaces — Chinese, Japanese, Korean, Thai, Lao, Khmer and half-width katakana are indexed as overlapping character pairs, so a memory written as 「資料庫遷移前一定要先備份」 is found by searching 「備份」 — not only by its exact full text. Text is normalised (NFC) on both the write and the query side, so memories typed on macOS or with a Korean or Vietnamese IME are found in either spelling.

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

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

⚠️ Conflict Detection — memesh dream conflicts has the LLM judge your semantically-closest memory pairs for contradiction, supersession or duplication, and stages what it finds as proposals. Nothing applies itself: you review with dream list / dream show, and only an accepted proposal creates the relation — after which every recall touching either memory carries the warning. Causality is never inferred from timestamps; verdicts come from what the memories actually say.

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

📦 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

Recipes

Catch a contradiction before it bites

Two decisions, made weeks apart, that cannot both be true — the failure mode a memory layer exists to catch:

memesh remember --name retry-policy --type decision \
  --obs "All HTTP clients retry failed requests up to 5 times with exponential backoff."
# ...weeks later, someone decides the opposite...
memesh remember --name retry-policy-v2 --type decision \
  --obs "HTTP clients must never retry automatically — fail fast and surface the error."

memesh dream conflicts        # the judge flags the pair, with its reasoning
memesh dream show 1           # read the verdict, the excerpts, what accepting creates
memesh dream accept 1         # YOU decide — nothing is ever linked automatically
memesh recall "retry policy"  # → Warning: Conflicts detected

From then on, any assistant that recalls either decision is told they conflict — instead of confidently quoting whichever one it found first.

One memory, three assistants

MeMesh is an MCP server, so the same SQLite file serves every MCP client on the machine. Register it once per tool (exact commands in Get Started) and a decision recorded in Claude Code is recalled by Codex or Gemini CLI mid-session — no re-explaining, no copy-pasting context between vendors.

Record decisions so they stay findable

Auto-capture keeps session history, but the memories that pay rent are the deliberate ones:

memesh remember --name auth-approach --type decision \
  --obs "JWT with RS256; PKCE over implicit flow because the client is public." \
  --tags "project:myapp" "topic:auth"

Then link consequences to their causes as they happen — from any MCP client, in plain words: "remember this incident as a lesson, influenced by auth-approach". The remember tool takes free-form relations, and caused / influenced are the documented causal vocabulary (cause → effect, stated explicitly — MeMesh never infers causality from timestamps). Weeks later, memesh recall "why did we pick PKCE" returns the decision with its recorded consequences attached — reasoning you can follow, not just text that matched.

Unlock Smart Mode (Optional)

MeMesh works offline by default — recall stays strictly LLM-free (95.60% 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 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 serve  # opens dashboard → Settings tab

Mine your past sessions into memory. memesh dream run --from-transcripts reads this project's Claude Code session transcripts, asks the LLM for the decisions and lessons buried in the conversation, and stages them as proposals — nothing enters your graph automatically. Review each with memesh dream show <id> and accept the ones worth keeping. To run it on a schedule, enable memesh config set transcriptMining true and point a cron/launchd entry at memesh dream run --from-transcripts --if-due — it self-throttles (default once every 24h per project) and stays staging-only. See API_REFERENCE.

Semantic search / embeddings (optional)

By default MeMesh does keyword-only recall (FTS5) — no API key, no model download, nothing leaves your machine. Semantic (meaning-based) search is opt-in and needs an embedder. Point one of these at it:

memesh config set embedder.provider ollama          # local, needs `ollama serve`
memesh config set embedder.model nomic-embed-text
# or, for a hosted embedder:
memesh config set embedder.provider openai
memesh config set embedder.model text-embedding-3-small

The embedder is configured independently of the chat LLM — changing llm.provider never silently changes your embeddings. If you switch to an embedder with a different dimension (e.g. 768 → 1536), MeMesh rebuilds the vector index automatically on the next write. Supported embedder.provider values: ollama (local), openai (hosted). With none set, recall stays on keyword search.

All 7 Memory Tools

Architecture

                    ┌─────────────────┐
                    │   Core Engine   │
                    │  (7 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
cd memesh && npm install && npm run build
npm test
npm run test:e2e-dashboard

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

MIT — Made by PCIRCLE AI