{"id":"135d6586-9226-4acf-93f5-3e8f6f7064b6","slug":"cpersona","kind":"mcp","name":"CPersona","summary":"CPersona — persistent memory for AI agents over MCP. One SQLite file you own, hybrid vector + full-text + keyword search, no LLM in the loop, and honest reporting when recall degrades. MIT licensed.","owner":"Cloto-dev","repoUrl":"https://github.com/Cloto-dev/CPersona","license":"MIT","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-04-05T01:22:04.000Z","addedAt":"2026-10-14T05:10:10.297Z","logoUrl":"https://avatars.githubusercontent.com/u/261657510?u=5b2aa4aa26bf36f012eea5019245bd317958bc97&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","memory-knowledge","databases"],"tags":["ai-agent","claude","llm","memory","persistent-memory","python","rag","semantic-search"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T13:13:49.935Z","sample":false,"url":"https://conduits.dev/tools/cpersona","language":"Python","transports":["stdio"],"install":{"pypi":"cpersona"},"requirements":{"env":[{"name":"CPERSONA_DB_PATH","secret":false,"required":false,"description":"SQLite database path. Defaults to data/cpersona.db, which follows the client's working directory — set it to an absolute path to keep one memory across sessions."},{"name":"CPERSONA_EMBEDDING_MODE","secret":false,"required":false,"description":"Embedding mode: 'http' to use an embedding server for vector search, 'none' for lexical layers only."},{"name":"CPERSONA_EMBEDDING_URL","secret":false,"required":false,"description":"Embedding server endpoint, e.g. http://127.0.0.1:8401/embed. Required when CPERSONA_EMBEDDING_MODE=http."},{"name":"CPERSONA_RECALL_MODE","secret":false,"required":false,"description":"Recall fusion strategy: 'rrf' (default), 'rsf', or 'cascade'."}],"upstreamMayCharge":false},"tools":null,"readme":"<!-- mcp-name: io.github.Cloto-dev/cpersona -->\n\n<div align=\"center\">\n\n# CPersona\n\n### MCP Memory Server\n\nPersistent memory for AI agents, over MCP.\nOne SQLite file you own. No LLM in the loop. Honest when recall degrades.\nAsk your agent to save a project's design decisions and their reasons, then recall them in a later coding session ([setup and verification](https://cloto-dev.github.io/CPersona/getting-started/#4-verify-it-works)).\nUse `reconstruct` to read recalled items with quotes from the stored records ([traceable recall](https://cloto-dev.github.io/CPersona/tools/#everyday-memory)).\n\n[![PyPI](https://img.shields.io/pypi/v/cpersona)](https://pypi.org/project/cpersona/) [![CI](https://github.com/Cloto-dev/cpersona/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Cloto-dev/cpersona/actions/workflows/ci.yml) [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://github.com/Cloto-dev/cpersona/blob/master/pyproject.toml) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Cloto-dev/cpersona/blob/master/LICENSE) [![Sponsor](https://img.shields.io/badge/sponsor-Cloto--dev-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/Cloto-dev)\n\n[Documentation](https://cloto-dev.github.io/CPersona/) · [Getting Started](https://cloto-dev.github.io/CPersona/getting-started/) · [Architecture](https://cloto-dev.github.io/CPersona/architecture/) · [Tools](https://cloto-dev.github.io/CPersona/tools/) · [PyPI](https://pypi.org/project/cpersona/) · [Zenn Book (JP)](https://zenn.dev/cloto/books/claude-memory-mcp-server)\n\n</div>\n\n---\n\n> **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](https://cloto-dev.github.io/CPersona/getting-started/#3-register-cpersona-with-your-mcp-client)).\n> If you are a [ClotoCore](https://github.com/Cloto-dev/ClotoCore) user, install CPersona from the in-app marketplace ([ClotoHub](https://hub.cloto.dev)) instead — it distributes this same repository.\n\n> **Project status** — **2.4.x is Stable**; **2.6.x is Current**, where all\n> fixes land, pending production-soak certification. Its first final, 2.6.0,\n> migrates the schema from version 13 to 17 on its first start and changes some\n> tool behaviour, so take a 2.5 store across with\n> [Upgrading from 2.5 to 2.6](https://cloto-dev.github.io/CPersona/upgrading-to-2.6/).\n> **2.5.x is Candidate**: no longer the newest line and not yet certified,\n> reachable by exact version. Which version to run, and how long each line\n> keeps receiving fixes:\n> [SUPPORT.md](https://github.com/Cloto-dev/cpersona/blob/master/SUPPORT.md).\n> Where the lines are heading: the [roadmap](https://cloto-dev.github.io/CPersona/roadmap/).\n\n> **Upgrading from 2.5.2 or earlier?** Two things need a decision from you.\n> **v2.5.3 will not start the HTTP transport without `CPERSONA_AUTH_TOKEN`**,\n> wherever it binds — set one, or opt out with\n> `CPERSONA_ALLOW_UNAUTHENTICATED_HTTP=true` ([why](https://github.com/Cloto-dev/cpersona/blob/master/SUPPORT.md#known-issues); stdio is unaffected).\n> **v2.5.2 changed tool response shapes** — branch on `ok is false`, and treat any\n> response carrying `error` as a failure whether or not `ok` is present\n> ([contract §10](https://cloto-dev.github.io/CPersona/behavior-contracts/#10-response-shapes-how-to-tell-success-from-failure)).\n\n## The Problem\n\nClaude forgets everything between sessions. Every conversation starts from zero — no context about your project, your preferences, or what you discussed yesterday.\n\ncpersona fixes this. It's an [MCP](https://modelcontextprotocol.io/) 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](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [ClotoCore](https://github.com/Cloto-dev/ClotoCore) (the AI agent platform where cpersona originated, and whose memory layer it is), or a client of your own.\n\n## Quick Start\n\n> **Setting this up as an AI agent?** Read the\n> [Agent Skill](https://github.com/Cloto-dev/cpersona/blob/master/skills/cpersona-memory/SKILL.md)\n> — `skills/cpersona-memory/SKILL.md` in a clone of this repository — and follow\n> it end to end. It is the complete procedure: install, embedding server,\n> registration, **and the two steps a quick start tends to skip** — verifying\n> from a *new* session, and persisting the memory policy so the next session\n> knows which `agent_id` holds the memories.\n>\n> **Using Claude Code yourself?** The same skill ships inside the wheel. Once\n> `cpersona` is installed, copy it in and say *\"Set up CPersona.\"*\n>\n> ```bash\n> 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)\"\n> ```\n\n**1. Install** — Python 3.11+, and [uv](https://docs.astral.sh/uv/) for the one-command path.\n\n```bash\nuvx cpersona          # run directly, no install step\npip install cpersona  # or install it\n```\n\n**2. Run an embedding server** — strongly recommended; it powers the vector layer\n\n```bash\nuvx --from \"cembedding[onnx]\" cembedding-download-model --model jina-v5-nano\nEMBEDDING_PROVIDER=onnx_jina_v5_nano uvx --from \"cembedding[onnx]\" cembedding   # serves http://127.0.0.1:8401/embed\n```\n\nThe 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](https://cloto-dev.github.io/CPersona/getting-started/#the-reference-server) has the details.\n\nAny endpoint implementing the [embedding contract](https://cloto-dev.github.io/CPersona/getting-started/#the-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.\n\n**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.\n\n**3. Register it with your MCP client**\n\nFor Codex, Cursor, VS Code, or Claude Desktop, follow the\n[client registration table](https://cloto-dev.github.io/CPersona/getting-started/#3-register-cpersona-with-your-mcp-client).\nThe command below is for Claude Code.\n\n```bash\nclaude 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\n```\n\n**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.\n\n**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](https://cloto-dev.github.io/CPersona/getting-started/#5-make-the-memory-triggers-fire-in-every-session).\n\nAt startup the server asks pypi.org whether a newer release exists and tells the\ncalling agent through `recall`; set `CPERSONA_UPDATE_CHECK=false` to turn that\noff. Updating is never automatic.\n\nClaude Desktop config, Windows paths, installing from source and the full\nwalkthrough: [Getting Started](https://cloto-dev.github.io/CPersona/getting-started/).\n\n## What You Get\n\n- **Hybrid search** — vector (the layer an embedding server powers), FTS5\n  (trigram, so it works on Japanese and other space-less scripts) and keyword,\n  fused by rank or relative score. The FTS and keyword layers rescue what vectors\n  miss: identifiers, error strings, exact names.\n- **Evidence you can trace** — `reconstruct`, the recommended way to answer from\n  memory, returns items that quote the stored rows behind them, within a\n  character budget. Text past a long record's embedding window stays reachable\n  (block reach, on by default).\n- **Three memory types** — facts, session summaries and an accumulated profile.\n- **Zero LLM dependency** — cpersona never calls a generative model; your agent\n  summarizes and hands over the result. Recall is deterministic given a calibrated\n  gate, but the gate is sampled, so two installs on identical data can settle\n  differently.\n- **Single-file SQLite** — no external database; `sqlite3 .backup` copies the\n  corpus (the calibration sidecar beside it needs copying too, and so does the\n  alias ledger when an ACL row sets `per_subject`).\n- **Operable** — auto-calibrated thresholds, a health check with auto-repair, an\n  advisory when the embedding layer dies, JSONL export/import, agent-to-agent merge.\n- **Isolation** — `agent_id`, `project_id` and `channel` let several agents and\n  projects share one database without bleeding into each other.\n\nHow it fits together: [Architecture](https://cloto-dev.github.io/CPersona/architecture/) ·\nwhat the tools do: [Tools](https://cloto-dev.github.io/CPersona/tools/) ·\nwhat you may rely on: [Behavior Contracts](https://cloto-dev.github.io/CPersona/behavior-contracts/).\n\n## Benchmarks\n\nMeasured on [OmniMemEval](https://github.com/MemTensor/OmniMemEval)'s LongMemEval-S\npipeline: the 500 questions of the cleaned LongMemEval-S, answered by `gpt-4.1-mini`\nand judged by `gpt-4o-mini`, through the same harness, prompts and models as the\nmemory backends OmniMemEval reproduces. Accuracy is the share of questions judged\ncorrect; Context Tokens is the average number of tokens sent to the answer model per\nquestion, its prompt included.\n\n| Backend | Deployment | SS-User | SS-Asst | SS-Pref | Temp. Reas | Multi-S | Know. Upd | Overall | Context Tokens |\n| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |\n| CPersona 2.6.3a1 | local | 90.00 | 78.57 | 86.67 | 85.71 | 67.67 | 85.90 | 80.80 | 2,354.6 |\n| CPersona v1.2 (2.6.4a1) | local | 91.43 | 80.36 | 90.00 | 83.46 | 71.43 | 84.62 | 81.60 | 1,786.7 |\n\n**81.60% at 1,786.7 tokens a question.** Of the 12 backends OmniMemEval reproduces\nthrough the same pipeline, MemOS answers more questions (89.20%, at 4,151 tokens) and\nMem0's cloud service sends fewer tokens (856, at 56.00%); 2.6.4a1 scored higher with\nfewer tokens than each of the other ten, the closest of them within one run's sampling\nerror. CPersona stores each conversation as it is and calls no model to store or\nrecall.\n\n2.6.3a1 is the code of the 2.6.3 release, and 2.6.4a1 is a pre-release of\n2.6.4. Each was run once, by this project. The comparison rows, the registered\nrules and every departure from a clean run are in the\n[results](https://github.com/Cloto-dev/cpersona/blob/master/benchmarks/measurements/results-omnimemeval-lme.md).\nRetrieval-only measurements on LMEB (22 tasks) and the harness behind them:\n[`benchmarks/`](https://github.com/Cloto-dev/cpersona/blob/master/benchmarks/README.md).\n\n## Documentation\n\n[**cloto-dev.github.io/CPersona**](https://cloto-dev.github.io/CPersona/) is canonical — when this README disagrees with it, the site wins.\n\n| | |\n|---|---|\n| [Getting Started](https://cloto-dev.github.io/CPersona/getting-started/) | Install, embedding server, client registration, verification |\n| [Behavior Contracts](https://cloto-dev.github.io/CPersona/behavior-contracts/) | What you may rely on: recall ordering, dedup, scan window, response shapes |\n| [Tools](https://cloto-dev.github.io/CPersona/tools/) | Every tool, grouped by what you reach for it for |\n| [Architecture](https://cloto-dev.github.io/CPersona/architecture/) | Storage, the retrieval pipeline, isolation axes |\n| [Roadmap](https://cloto-dev.github.io/CPersona/roadmap/) | What each release line is for and may break; planned retrieval features and the scale ladder |\n| [Operations Runbook](https://cloto-dev.github.io/CPersona/operations/) | Backup, degradation detection, tuning, CJK guidance, corpus sync |\n| [Configuration](https://cloto-dev.github.io/CPersona/configuration/) | Every environment variable and its default |\n| [Quality Assurance](https://cloto-dev.github.io/CPersona/quality-assurance/) | How a release is gated: audits, the bug ledger, structural and mutation gates |\n| [FAQ](https://cloto-dev.github.io/CPersona/faq/) | Short answers to the questions operators actually ask |\n\nJapanese translations are in the language selector (English is canonical) and\nagents can read [`llms.txt`](https://cloto-dev.github.io/CPersona/llms.txt).\nLonger reads in Japanese: a [book](https://zenn.dev/cloto/books/claude-memory-mcp-server)\non the design and setup, and an [article](https://zenn.dev/cloto/articles/claude-code-compact-external-memory)\non the token economics of session-end → `/clear` → `recall`.\n\n## Quality Assurance\n\nEvery release is gated by a machine-verifiable process: multi-agent audit rounds with adversarial verification, a [bug ledger](https://github.com/Cloto-dev/cpersona/blob/master/qa/issue-registry.json) that fails CI if a fix marker disappears or a removed defect returns, structural gates for invariants a plain test cannot express, a mutation proof that those gates go red when the invariant is broken, and gates holding the documented counts, defaults and version claims to the source that defines them.\n\nBehind it: **~3,865 test functions** across ~297 test modules (~5,413 cases parametrised, more test code than server code), on **Schema v20** — [how a release is gated](https://cloto-dev.github.io/CPersona/quality-assurance/).\n\n## Support\n\nThree tiers — **Stable** (production-certified, critical fixes only), **Current**\n(newest line, all fixes land here) and **Experimental** (opt-in pre-releases). A\nsuperseded line keeps critical-fix support for 30 more days. **Read\n[SUPPORT.md § Known issues](https://github.com/Cloto-dev/cpersona/blob/master/SUPPORT.md#known-issues)\nbefore pinning a version** — some of them change what you should run.\n\nFound a bug, or something the docs do not explain? Open a\n[bug report](https://github.com/Cloto-dev/cpersona/issues/new?template=bug_report.yml)\nor [feature request](https://github.com/Cloto-dev/cpersona/issues/new?template=feature_request.yml),\neven when you are not certain — a configuration problem mistaken for a bug means\nthe documentation was unclear, which is a defect of its own. Report security\nvulnerabilities privately via\n[SECURITY.md](https://github.com/Cloto-dev/cpersona/blob/master/SECURITY.md).\n\n## Sponsorship\n\nCPersona is MIT-licensed and stays fully usable whether or not anyone sponsors\nit. Sponsorship buys no feature, no release tier and no position in the issue\nqueue — issues are triaged by impact, reproducibility and safety, and that does\nnot change for anyone.\n\nIf CPersona has earned a place in your workflow and you would like the work to\ncontinue, you can [sponsor Cloto-dev on GitHub](https://github.com/sponsors/Cloto-dev).\nThe same page covers CPersona, ClotoCore and the other projects published\nunder that account; sponsorship goes toward development time, testing\nand infrastructure, documentation and maintenance.\n\nMoney is not the only thing that helps, and it is not the thing this project\nneeds most. Starring the repository, saying which part of the setup was\nconfusing, filing a reproducible issue, or correcting a sentence in the\ndocumentation all move it forward.\n\n## License\n\nMIT — free to use from any MCP host without restriction.\n"}