MCP adapter

The MCP adapter (@plur-ai/mcp) is the most common way to use PLUR. It exposes the engine as a Model Context Protocol server — any MCP-aware agent can call its tools. For Claude Code specifically it also installs lifecycle hooks for fully automatic memory.

Install

Claude Code

npx @plur-ai/mcp init

init does three things:

1. Creates ~/.plur/ for engram storage.
2. Adds PLUR to your ~/.mcp.json (or .claude/mcp.json if you’re project-scoped).
3. Installs Claude Code hooks in ~/.claude/settings.json for automatic injection on session start and learning capture on UserPromptSubmit.

The hook system means you don’t have to ask Claude Code to use PLUR — it just does. Restart Claude Code and it’s wired.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
  }
}

Cursor doesn’t have a public hook system equivalent to Claude Code’s, so injection requires the agent to call plur_session_start on its own. Most Cursor users add a one-line system prompt: “At the start of each task, call plur_session_start with the task description.”

Windsurf

Same pattern as Cursor — add to the Windsurf MCP config:

{
  "mcpServers": {
    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
  }
}

Codex (any MCP client)

Any MCP client works. The command is always:

npx -y @plur-ai/mcp

Or, if installed globally:

npm install -g @plur-ai/mcp
# then call: plur-mcp

What you get

The MCP server exposes 18 tools. The most-used ones:

Tool	What it does
plur_session_start	Start a session, inject relevant engrams for the task.
plur_session_end	End a session, capture summary and new learnings.
plur_learn	Save a correction, preference, or pattern.
plur_recall_hybrid	Default search: BM25 + embeddings + RRF. Local, free.
plur_recall	BM25 only — instant, no embeddings.
plur_inject / plur_inject_hybrid	Load relevant memories for the current task.
plur_feedback	Rate an engram (positive / negative). Trains recall.
plur_forget	Retire an engram. History preserved.
plur_status	Health check.
plur_sync	Sync across machines via git.
plur_packs_install / _list / _uninstall	Manage Knowledge Packs.
plur_stores_add / _list	Connect to a remote store (Enterprise).

Full list and signatures: MCP tools reference.

Claude Code hook lifecycle

When you run npx @plur-ai/mcp init against Claude Code, PLUR installs these hooks:

Hook	What PLUR does
SessionStart	Calls plur_session_start with the session task, injects top-N engrams into the system prompt.
UserPromptSubmit	Scans for correction patterns (“no, actually…”, “from now on…”). Auto-stages an engram candidate.
Stop (session end)	Calls plur_session_end to write the episode and commit candidate engrams.

You can see what got injected:

plur timeline --channel session --limit 1

To disable a hook, edit ~/.claude/settings.json and remove the line. To re-enable later, re-run plur init.

Project vs global

PLUR is a single global store at ~/.plur/. There is one engram database per machine. Per-project isolation is done with scope, not separate stores.

To set the current scope for a project:

cd ~/projects/my-app
npx @plur-ai/cli init --domain myapp --scope project:my-app

This writes .plur.yaml. Hooks read it on session start; engrams learned in this project get tagged with scope: project:my-app. Recall in this project always includes global engrams, but excludes project:other-app.

See Multi-project setup for the full pattern.

Connecting to PLUR Enterprise

The MCP adapter can also point at a remote PLUR store running PLUR Enterprise. Local memory keeps working; team scopes show up alongside personal ones.

plur stores add \
  --name acme \
  --url https://plur.acme.com \
  --token sk_acme_...

After this, engrams under group:acme/* are read from and written to the Enterprise server with permission enforcement. Personal engrams (global, project:*) stay local. See Migrating local → Enterprise.

Note

The MCP server speaks stdio by default. For network-accessible MCP (multi-user, HTTP/SSE transport), see PLUR Enterprise architecture — the Enterprise server is the same protocol with auth and permissions added.

Troubleshooting

• Agent says it has no plur_* tools — MCP config didn’t load. Restart the editor and check ~/.mcp.json.
• Hooks not firing in Claude Code — re-run plur init and confirm ~/.claude/settings.json has the SessionStart/UserPromptSubmit entries.
• bge-m3 embedder model not downloading — first run downloads ~500 MB; on a slow link give it five minutes. plur doctor reports embedder status.
• MCP timeout on first call — increase the client’s MCP timeout to 30 s for the first session (model load).

Next: OpenClaw plugin →