Claude Code Buddy (CCB)

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

MeMesh— open-sourceagentic memoryfor 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.

In Claude Code— type these in the chat (hooks, memory tools and the/memeshskill are wired automatically):

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

Restart Claude Code. A◉ MeMeshstatus line at the top of your next session means it is capturing.

In a terminal— thememeshCLI, the dashboard, and thememesh-mcpserver for Codex / Gemini / Cursor (needsNode 22.13+):

npm install -g @pcircle/memesh memesh doctor # verifies this install end to end

Most Claude Code users eventually wantboth— they share one database and never conflict. Details, other agents, and upgrades:Get Started.

Installing via an AI agent?Point it atllms-install.md— deterministic steps with per-step verification. Once installed,AGENTS.mdtells it how to use memesh well.

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

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

⚠️ 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-memeshfrom inside Claude Code → installsPath A only. Gives you MCP tools, hooks, the/memeshskill. DoesNOTputmemeshon your shellPATH.
- memesh reindex/memesh update/memesh doctortyped in a normal terminal → needsPath B(npm-global). Without it:zsh: command not found: memesh.
- Recommended setup for Claude Code users: installboth. 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 typememeshin a terminal), Path A alone is enough. Everyone else: install both.

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/memeshskill (remember / recall / learn / forget) inside the Claude Code conversation, andremember/recall/forget/learnavailable as MCP tools to the agent.

Verify it:restart Claude Code and start any session. A status line like◉ MeMesh ready · no memories for "your-project" yetappears at the top — that line IS the plugin working; no separate command needed. (Once you have memories, it shows counts instead.)

The MCP server runs directly from the plugin's bundled compiled output — nonpxlookup, no build step, and nothing to compile. memesh stores its data throughnode: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 vianpx @pcircle/memesh <command>if you absolutely don't want a global install, but typing plainmemeshin a terminal will reportcommand not found. To get a real shellmemeshcommand, also runOption Bbelow — 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 shellPATH(so plainmemesh,memesh-mcp, etc. work in any terminal without the per-callnpxlookup), or you want to exposememesh-mcpas a fixed-path stdio command tonon-Claude-Code MCP clients(Codex CLI, Gemini CLI, Cursor, Cline, terminal-only flows):

- No compiler needed— the database engine is Node's ownnode: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, sonpm install --ignore-scriptsinstalls 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: runOllamalocally, or configure a cloud embedder (see "Bring-your-own embeddings" below). Without one, memesh uses keyword search only.

memesh setup # detects Claude Code / Codex / Gemini, offers to wire each, verifies

memesh install-hooks # adds memesh's hooks to ~/.claude/settings.json memesh setup --check # machine-level verification: reads the hosts' own config, changes nothing

# 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 therecalltool, or from a terminal:

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

Usememesh-mcp, notnpx -p @pcircle/memesh, as the configured command.npx -presolves to thelocalpackage 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.

Hermes Agent(NousResearch) has a first-partyMemoryProviderplugin system — MeMesh integrates at the same tier as Hermes's own built-in memory backends (honcho, mem0, hindsight), not as an HTTP bridge. Unlike MCP mode where you manually call tools, Hermes's provider system runsrecall/rememberautomatically on every turn.

The integration maps Hermes'sprefetch()andsync_turn()hooks directly onto MeMesh's HTTP API. Complete guide with provider code structure, config, and four real pitfalls from a live deployment:docs/platforms/hermes-agent.md

Key difference from Hermes: OpenClaw's auto-capture is threshold-gated (max 3 memories/turn when triggered), not every-turn. The integration maps onto MeMesh's HTTP API (/v1/recall,/v1/remember,/v1/forget). Full TypeScript plugin contract, config shape, and pitfalls:docs/platforms/openclaw.md

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

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

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

Where "your-project" was left off (today): - Goal: Ship the payment retry logic - Next: Open the PR once CI is green Decisions and direction for "your-project": - [decision] Use FTS5 as the retrieval baseline

This same block is what Claude Code receives automatically at session start, and what any other MCP client gets from thebriefingtool — the agent starts oriented instead of re-reading the repository, and you stop re-explaining last week. The dashboard (memesh serve) is the full visual view.

- One local file.Everything lives in~/.memesh/knowledge-graph.db— SQLite, on your disk. No cloud account; nothing leaves your machine unless you configure a cloud embedder or LLM yourself.
- Back up = copy that one file.Restore = copy it back.
- Pause capture anytime:export MEMESH_AUTO_CAPTURE=false.
- Delete everything: remove~/.memesh/.

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

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 isFTS5 alone— no LLM, no embeddings on the hot path. Measured against the publicLongMemEval-Sbenchmark (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.

Fallback LLM providers (Smart Mode).In the dashboardSettings → "Fallback providers"you can set an ordered failover chain — memesh tries each provider in turn when your primary is down. Add a localOllamafallback, 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.

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