CPERSONA_DB_PATH — 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.
CPERSONA_EMBEDDING_MODE — Embedding mode: 'http' to use an embedding server for vector search, 'none' for lexical layers only.
CPERSONA_EMBEDDING_URL — Embedding server endpoint, e.g. http://127.0.0.1:8401/embed. Required when CPERSONA_EMBEDDING_MODE=http.
CPERSONA_RECALL_MODE — Recall fusion strategy: 'rrf' (default), 'rsf', or 'cascade'.
Claude Code में लोकल कमांड के लिए इंस्टॉल लिंक नहीं है। नीचे दी गई कमांड कॉपी करें और टर्मिनल में चलाएँ।
Persistent memory for AI agents, over MCP.
One SQLite file you own. No LLM in the loop. Honest when recall degrades.
Ask your agent to save a project's design decisions and their reasons, then recall them in a later coding session (setup and verification).
Use to read recalled items with quotes from the stored records ().
On OmniMemEval's shared pipeline: 89.6% on LongMemEval-S, tied for first with MemOS, and 84.0% on LoCoMo ().
Persistent AI memory in one SQLite file: 3-layer hybrid search, confidence scoring, 29 tools.
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.6.x is Current, where all
fixes land, pending production-soak certification. Its first final, 2.6.0,
migrates the schema from version 13 to 17 on its first start and changes some
tool behaviour, so take a 2.5 store across with
Upgrading from 2.5 to 2.6.
2.5.x is Candidate: no longer the newest line and not yet certified,
reachable by exact version. 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."
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
For Codex, Cursor, VS Code, or Claude Desktop, follow the
client registration table.
The command below is for Claude Code.
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.
Evidence you can trace — reconstruct, the recommended way to answer from
memory, returns items that quote the stored rows behind them, within a
character budget. Text past a long record's embedding window stays reachable
(block reach, on by default).
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, and so does the
alias ledger when an ACL row sets per_subject).
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.
Measured on OmniMemEval's LongMemEval-S
pipeline: the 500 questions of the cleaned LongMemEval-S, answered by gpt-4.1-mini
and judged by gpt-4o-mini, through the same harness, prompts and models as the
memory backends OmniMemEval reproduces. Accuracy is the share of questions judged
correct; Context Tokens is the average number of tokens sent to the answer model per
question, its prompt included.
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
MemOS
cloud
100.00
100.00
100.00
89.47
78.95
84.62
89.20
4,151
Tied for first: 89.60% at 4,262.5 tokens a question. Of the 12 backends
OmniMemEval reproduces through the same pipeline, MemOS is level with it (89.20% at
4,151 tokens; the 0.4-point gap is inside one run's sampling error) and every other
one scores at least 9 points lower. On LoCoMo (1,540 questions, same models)
CPersona answers 84.03% at 4,441 tokens, second to MemOS (88.83% at 5,400).
CPersona stores each conversation as it is and calls no model to store or recall.
Against OpenViking 0.5.0, run by this
project: 84.03% against 59.09% on LoCoMo, and on the
Open Agent Memory Benchmark's
60-question LongMemEval screen, 52 against 51 correct with a quarter of the evidence
tokens and none generated at write time (OpenViking: 37 million). Not every cost
favours CPersona: on LoCoMo it searched slower, and its context was 0.58 of
OpenViking's.
One run each, by this project, at the 2.6.11 release. Setups, registered rules and
every departure from a clean run: results;
earlier runs: 2.6.3a1 and 2.6.4a1; retrieval-only
measurements on LMEB: benchmarks/.
Short answers to the questions operators actually ask
Japanese translations are in the language selector (English is canonical) and
agents can read llms.txt.
Longer reads in Japanese: a book
on the design and setup, and an article
on the token economics of session-end → /clear → recall.
Quality Assurance
Every release is gated by a machine-verifiable process: multi-agent audit rounds with adversarial verification, a bug ledger 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.
Behind 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.
Support
Three tiers — Stable (production-certified, critical fixes only), Current
(newest line, all fixes land here) and Experimental (opt-in pre-releases). A
superseded line keeps critical-fix support for 30 more days. Read
SUPPORT.md § Known issues
before pinning a version — some of them change what you should run.
Found a bug, or something the docs do not explain? Open a
bug report
or feature request,
even when you are not certain — a configuration problem mistaken for a bug means
the documentation was unclear, which is a defect of its own. Report security
vulnerabilities privately via
SECURITY.md.
Sponsorship
CPersona is MIT-licensed and stays fully usable whether or not anyone sponsors
it. Sponsorship buys no feature, no release tier and no position in the issue
queue — issues are triaged by impact, reproducibility and safety, and that does
not change for anyone.
If CPersona has earned a place in your workflow and you would like the work to
continue, you can sponsor Cloto-dev on GitHub.
The same page covers CPersona, ClotoCore and the other projects published
under that account; sponsorship goes toward development time, testing
and infrastructure, documentation and maintenance.
Money is not the only thing that helps, and it is not the thing this project
needs most. Starring the repository, saying which part of the setup was
confusing, filing a reproducible issue, or correcting a sentence in the
documentation all move it forward.
License
MIT — free to use from any MCP host without restriction.
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
CPersona कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या CPersona के लिए API key चाहिए?
पब्लिशर ने ये एनवायरनमेंट वेरिएबल बताए हैं: CPERSONA_DB_PATH, CPERSONA_EMBEDDING_MODE, CPERSONA_EMBEDDING_URL, CPERSONA_RECALL_MODE।
CPersona कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
CPersona stdio पर लोकल चलता है।
CPersona की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-11-09 को हुई। Persistent AI memory in one SQLite file: 3-layer hybrid search, confidence scoring, 29 tools.