Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

CPersona

Long-term memory for AI agents, in one SQLite file you own.

CPersona is an MCP server that lets Claude Code, Codex, Claude Desktop, Cursor, VS Code or any other MCP client remember what you decided, why, and what happened last time — across sessions.

PyPI CI Python License: MIT

Documentation · Getting Started · Tools · Discussions

The CPersona dashboard's memory network: each point is a memory, lines join the most similar ones, grouped by agent

The built-in dashboard, showing a made-up store of 72 memories.

Why CPersona

Every new session with a coding agent starts from zero. CPersona gives the agent a memory it can write to as it works and read from before it acts.

  • Yours, on your machine. Everything lives in a single SQLite file. No account, no cloud, no external database; sqlite3 .backup copies it.
  • No language model inside. CPersona never calls a generative model to store or recall. Your agent writes the summary; CPersona keeps it and finds it again.
  • Answers you can trace. reconstruct, the recommended way to answer from memory, quotes the stored records behind each item, so you can see where an answer came from.
  • Search that catches what vectors miss. Vector search runs beside full-text and keyword search, so exact names, identifiers and error strings are found too, in Japanese and other scripts without spaces as well.
  • See what it remembers. cpersona dashboard opens a read-only page of the store: what was stored last, what is recalled most, every memory in full, and the network above.
  • Honest when it degrades. Without an embedding server it still runs on keyword search, and says so on every recall instead of quietly returning less.

Quick start

With Claude Code or Codex, install the agent plugin and let the agent do the rest:

/plugin install cpersona --marketplace Cloto-dev/cpersona

Then say "Set up CPersona." The plugin carries the setup skill and the hooks that remind the agent to recall before it acts and to store as it goes. (Claude Code 2.1.275 or later. In Codex: codex plugin marketplace add Cloto-dev/cpersona, then codex plugin add cpersona@cpersona.)

By hand, in three steps:

# 1. Run an embedding server (recommended; it powers vector search)
uvx --from "cembedding[onnx]" cembedding-download-model --model bge-m3
EMBEDDING_PROVIDER=onnx_bge_m3 uvx --from "cembedding[onnx]" cembedding

# 2. Register CPersona with your client (Claude Code shown)
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

# 3. In a new session, ask the agent to store something, then recall it in another new session

# 4. See what it remembers, in the browser
cpersona dashboard

Getting Started covers the other clients, Windows, containers, and the short policy block that makes every future session use the memory.

Upgrading an existing install? Read the When you upgrade section of the release notes and SUPPORT.md first.

A look inside

Overview A memory, opened
The dashboard overview: the memories stored last and recalled most A memory opened in the dashboard, its text first

Memories are kept per agent, and project_id and channel let several agents and projects share one database without mixing.

Benchmarks

On OmniMemEval's LongMemEval-S pipeline (500 questions, answered by gpt-4.1-mini, judged by gpt-4o-mini), in this project's own run. Overall is the share of questions judged correct; Context Tokens is the average sent to the answer model per question:

Backend Deployment SS-User SS-Asst SS-Pref Temp. Reas Multi-S Know. Upd Overall Context Tokens
CPersona 2.6.11 (pro mode) local 97.14 94.64 96.67 86.47 85.71 88.46 89.60 4,262.5
CPersona 2.6.11 (lite mode) local 95.71 83.93 90.00 80.45 74.44 82.05 82.20 993.3
MemOS cloud 100.00 100.00 100.00 89.47 78.95 84.62 89.20 4,151

Pro mode is level with MemOS within sampling error, and on LoCoMo it answers 84.03%. Setups, the registered rules and every departure from a clean run are in the results.

Documentation

cloto-dev.github.io/CPersona is the full reference, also in Japanese:

Guide What it covers
Getting Started Install, embedding server, client registration, verification
Behavior Contracts What you may rely on: recall ordering, dedup, scan window, response shapes
Tools Every tool, grouped by what you reach for it for
Architecture Storage, the retrieval pipeline, isolation axes
Roadmap What each release line is for and may break; planned retrieval features and the scale ladder
Operations Runbook Backup, degradation detection, tuning, CJK guidance, corpus sync
Configuration Every environment variable and its default
Quality Assurance How a release is gated: audits, the bug ledger, structural and mutation gates
FAQ Short answers to the questions operators actually ask

Contributing

Bug fixes, tests and documentation can be sent as a pull request straight away. For changes to the database schema, the tool contracts or the tool list, open an issue first. CONTRIBUTING.md has the setup — no embedding server is needed to run the ~4,150 test functions — and the three checks CI runs.

Questions and ideas are welcome in Discussions. A sentence in the docs that confused you is worth reporting too: it is a defect of its own.

Support

If CPersona has earned a place in your workflow, you can sponsor the work on GitHub. It buys no feature and no place in the issue queue; starring the repository, filing a clear issue or fixing a sentence in the docs helps too.

License

MIT — see LICENSE.

Metadata

Release files for cpersona 2.6.17a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cpersona 2.6.17a1
File Size Uploaded Provenance Actions
cpersona-2.6.17a1.tar.gz 1.7 MB With provenance Details for cpersona-2.6.17a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cpersona 2.6.17a1
File Interpreter ABI Platform Actions
cpersona-2.6.17a1-py3-none-any.whl Python 3 none any Details for cpersona-2.6.17a1-py3-none-any.whl

Total release size: 3.5 MB

Release files / cpersona-2.6.17a1.tar.gz

Download URL cpersona-2.6.17a1.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
a49ba008616fece7d2719960fd39ddb519d381d6cde3fb42c021b41a95cbc88a
BLAKE2b-256 checksum
How to use checksums
8ba740bfc8b0d1d14244c06734983ed92a3d26fe2a389d832070b634e3622a70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / cpersona-2.6.17a1-py3-none-any.whl

Download URL cpersona-2.6.17a1-py3-none-any.whl
Size 1.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
67775acd503037d2b3b329017758dc4dfe6aed9d10c032f3b975582b652d0581
BLAKE2b-256 checksum
How to use checksums
c885a2c1ef5059dc946170aa2b9ec7d4d74c14d96c1b292bb0f7a4283b0c6b1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for cpersona 2.6.17a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cpersona-2.6.17a1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page