Standalone repository — This is the standalone version for use with Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, and any other MCP client (registration table). If you are a ClotoCore user, install CPersona from the in-app marketplace (ClotoHub) instead — it distributes this same repository.

Project status — 2.4.x is Stable; 2.5.x is Current, an internal stabilization line where all fixes land, pending production-soak certification. The DB schema is preserved across the line. Additive, rollback-safe features may land here as well (lifecycle standard §2.6); a change that cannot be rolled back waits for 2.6. Which version to run, and how long each line keeps receiving fixes: SUPPORT.md. Where the lines are heading: the roadmap.

Upgrading from 2.5.2 or earlier? Two things need a decision from you. v2.5.3 will not start the HTTP transport without CPERSONA_AUTH_TOKEN, wherever it binds — set one, or opt out with CPERSONA_ALLOW_UNAUTHENTICATED_HTTP=true (why; stdio is unaffected). v2.5.2 changed tool response shapes — branch on ok is false, and treat any response carrying error as a failure whether or not ok is present (contract §10).

The Problem

Claude forgets everything between sessions. Every conversation starts from zero — no context about your project, your preferences, or what you discussed yesterday.

cpersona fixes this. It's an MCP server that stores memories in a local SQLite file and retrieves them through hybrid search. Claude remembers you. It runs against any MCP-compatible host — Claude Desktop, Claude Code, ClotoCore (the AI agent platform where cpersona originated, and whose memory layer it is), or a client of your own.

Quick Start

Setting this up as an AI agent? Read the Agent Skill — skills/cpersona-memory/SKILL.md in a clone of this repository — and follow it end to end. It is the complete procedure: install, embedding server, registration, and the two steps a quick start tends to skip — verifying from a new session, and persisting the memory policy so the next session knows which agent_id holds the memories.

Using Claude Code yourself? The same skill ships inside the wheel. Once cpersona is installed, copy it in and say "Set up CPersona."

server.ts

Copy

python -c "import cpersona,pathlib,shutil; s=pathlib.Path(cpersona.__file__).parent/'skills'/'cpersona-memory'; shutil.copytree(s, pathlib.Path.home()/'.claude/skills/cpersona-memory', dirs_exist_ok=True)"

1. Install — Python 3.11+, and uv for the one-command path.

uvx cpersona          # run directly, no install step
pip install cpersona  # or install it

2. Run an embedding server — strongly recommended; it powers the vector layer

uvx --from "cembedding[onnx]" cembedding-download-model --model jina-v5-nano
EMBEDDING_PROVIDER=onnx_jina_v5_nano uvx --from "cembedding[onnx]" cembedding   # serves http://127.0.0.1:8401/embed

The reference server's lifetime is bound to its stdin. Started with stdin closed — by a service manager, by nohup … </dev/null, or from an agent's background shell — it binds the port and exits within the same second with status 0. Give it a stdin that stays open (sleep infinity | cembedding); Getting Started has the details.

Any endpoint implementing the embedding contract works and is equally recommended; CEmbedding is the reference implementation. The choice of backend is yours — the recommendation is to connect one, not to connect that one.

Without a backend, cpersona still runs — FTS5 + keyword search, and it says on every recall that it is degraded rather than quietly returning less. That is a supported fallback, not a recommended way to run: recall then matches on shared words, so a memory phrased differently from your question can be missed, and so can an older one.

3. Register it with your MCP client

claude mcp add-json cpersona '{"type":"stdio","command":"uvx","args":["cpersona"],"env":{"CPERSONA_DB_PATH":"/home/you/.claude/cpersona.db","EMBEDDING_MODE":"http","EMBEDDING_HTTP_URL":"http://127.0.0.1:8401/embed"}}' -s user

4. Verify from a new session — ask the agent to store something, then recall it in a fresh session. Surviving the session boundary is the whole point.

5. Make it stick — registration gives the agent the tools. It does not tell the next session to use them, or which agent_id holds the memories: recall is scoped to an exact agent_id, so a session that guesses the wrong one gets nothing back. Persist the short policy block into the file your client loads every session (~/.claude/CLAUDE.md, AGENTS.md, …) — Getting Started §5.

At startup the server asks pypi.org whether a newer release exists and tells the calling agent through recall; set CPERSONA_UPDATE_CHECK=false to turn that off. Updating is never automatic.

Claude Desktop config, Windows paths, installing from source and the full walkthrough: Getting Started.

What You Get

• Hybrid search — vector (the layer an embedding server powers), FTS5 (trigram, so it works on Japanese and other space-less scripts) and keyword, fused by rank or relative score. The FTS and keyword layers rescue what vectors miss: identifiers, error strings, exact names.
• Three memory types — facts, session summaries and an accumulated profile.
• Zero LLM dependency — cpersona never calls a generative model; your agent summarizes and hands over the result. Recall is deterministic given a calibrated gate, but the gate is sampled, so two installs on identical data can settle differently.
• Single-file SQLite — no external database; sqlite3 .backup copies the corpus (the calibration sidecar beside it needs copying too).
• Operable — auto-calibrated thresholds, a health check with auto-repair, an advisory when the embedding layer dies, JSONL export/import, agent-to-agent merge.
• Isolation — agent_id, project_id and channel let several agents and projects share one database without bleeding into each other.

How it fits together: Architecture · what the tools do: Tools · what you may rely on: Behavior Contracts.

Benchmarks

Measured on LMEB (Long-horizon Memory Embedding Benchmark, arXiv:2603.12572) — 22 datasets subsuming LoCoMo and LongMemEval, measured here as 22 retrieval tasks. The metric is Mean NDCG@10 across all 22 tasks. Track A is the raw embedding model alone; Track B routes the same embeddings through cpersona's real store/recall code paths (SQLite + FTS5 + RRF fusion + per-agent auto-calibration).

Track B lands at or above Track A on both models: the fusion layers add signal rather than merely persisting vectors, and a weaker embedding gains more because the FTS5/keyword layers rescue what its vectors miss. How to read the deltas, the noise envelope, the measurement harness and the reproduction regime: benchmarks/.

Documentation