CPersona — Claude Code MCP server: what it does, how to install
Keeps agent project memory across coding sessions in a local SQLite database using three-layer hybrid retrieval.
claude mcp add --env CPERSONA_DB_PATH=<CPERSONA_DB_PATH> --env CPERSONA_EMBEDDING_MODE=<CPERSONA_EMBEDDING_MODE> --env CPERSONA_EMBEDDING_URL=<CPERSONA_EMBEDDING_URL> --env CPERSONA_RECALL_MODE=<CPERSONA_RECALL_MODE> --transport stdio cpersona -- uvx cpersonaWhat CPersona does
CPersona acts as a persistent memory layer for development agents over MCP. Every architectural choice and note stays inside a single SQLite file under your direct control. Instead of routing recall through an external LLM, the system applies a three-layer hybrid search with confidence scoring, while the reconstruct tool surfaces exact quotes from past notes.
Running this server requires Python 3.11 or newer and uvx. The vector search layer needs a local embedding service running on port 8401, which you can launch with cembedding and the jina-v5-nano model. When connecting over HTTP rather than stdio, the server halts at startup unless you provide CPERSONA_AUTH_TOKEN or toggle CPERSONA_ALLOW_UNAUTHENTICATED_HTTP=true.
What it helps with
- retain project decisions across agent sessions
- retrieve past notes using hybrid search
- inspect source quotes using the reconstruct tool
- store conversation context in an owned SQLite file
Example prompts for the agent
- Save the design decision and reasoning for using Redis for session caching.
- Recall past decisions regarding the billing API and show the source quotes.
- Check our stored records for database migration rules established earlier.
How to install CPersona
Platform CLI
claude mcp add --env CPERSONA_DB_PATH=<CPERSONA_DB_PATH> --env CPERSONA_EMBEDDING_MODE=<CPERSONA_EMBEDDING_MODE> --env CPERSONA_EMBEDDING_URL=<CPERSONA_EMBEDDING_URL> --env CPERSONA_RECALL_MODE=<CPERSONA_RECALL_MODE> --transport stdio cpersona -- uvx cpersonaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cpersona <command>
Platform CLI
codex mcp add cpersona --env CPERSONA_DB_PATH=<CPERSONA_DB_PATH> --env CPERSONA_EMBEDDING_MODE=<CPERSONA_EMBEDDING_MODE> --env CPERSONA_EMBEDDING_URL=<CPERSONA_EMBEDDING_URL> --env CPERSONA_RECALL_MODE=<CPERSONA_RECALL_MODE> -- uvx cpersonaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cpersona <command>
Config file
{
"mcpServers": {
"cpersona": {
"command": "uvx",
"args": [
"cpersona"
],
"env": {
"CPERSONA_DB_PATH": "<CPERSONA_DB_PATH>",
"CPERSONA_EMBEDDING_MODE": "<CPERSONA_EMBEDDING_MODE>",
"CPERSONA_EMBEDDING_URL": "<CPERSONA_EMBEDDING_URL>",
"CPERSONA_RECALL_MODE": "<CPERSONA_RECALL_MODE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cpersona <command>
Config file
{
"servers": {
"cpersona": {
"type": "stdio",
"command": "uvx",
"args": [
"cpersona"
],
"env": {
"CPERSONA_DB_PATH": "<CPERSONA_DB_PATH>",
"CPERSONA_EMBEDDING_MODE": "<CPERSONA_EMBEDDING_MODE>",
"CPERSONA_EMBEDDING_URL": "<CPERSONA_EMBEDDING_URL>",
"CPERSONA_RECALL_MODE": "<CPERSONA_RECALL_MODE>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cpersona <command>
Platform CLI
gemini mcp add -e CPERSONA_DB_PATH=<CPERSONA_DB_PATH> -e CPERSONA_EMBEDDING_MODE=<CPERSONA_EMBEDDING_MODE> -e CPERSONA_EMBEDDING_URL=<CPERSONA_EMBEDDING_URL> -e CPERSONA_RECALL_MODE=<CPERSONA_RECALL_MODE> cpersona uvx cpersonaReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from cpersona <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about CPersona
How to install CPersona in Claude Code?
Run claude mcp add cpersona -- uvx cpersona for standard stdio communication. To configure custom environment paths, run `claude mcp add --env CPERSONA_DB_PATH=<CPERSONA_DB_PATH> --env CPERSONA_EMBEDDING_MODE=<CPERSONA_EMBEDDING_MODE> --env CPERSONA_EMBEDDING_URL=<CPERSONA_EMBEDDING_URL> --env CPERSONA_RECALL_MODE=<CPERSONA_RECALL_MODE> --transport stdio cpersona -- uvx cpersona`.
What does CPersona do?
It provides 29 MCP tools to persist and query developer context within a local SQLite database. The recall mechanism relies on hybrid search rather than prompting an intermediary language model.
What is required to run the vector search layer?
You need Python 3.11+ and an active local embedding server. Running cembedding with the jina-v5-nano model hosts an embedding endpoint on http://127.0.0.1:8401/embed.
