CPersona

<!-- mcp-name: io.github.Cloto-dev/cpersona -->

<div align="center">

# CPersona

### MCP Memory Server

Give Claude persistent memory across sessions.
Single SQLite file. 29 tools. Zero LLM dependency.

[![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)

[Quick Start](#quick-start) · [Features](#features) · [Architecture](#architecture) · [All Tools](#all-tools) · [PyPI](https://pypi.org/project/cpersona/) · [Zenn Book (JP)](https://zenn.dev/cloto/books/claude-memory-mcp-server)

</div>

---

> **Standalone repository** — This is the standalone version for use with Claude Desktop, Claude Code, and any MCP client.
> 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.

> **Project status (July 2026)** — The 2.4 series is the **Stable** line (latest: v2.4.40, gated by three comprehensive audit rounds — see [Quality Assurance](#quality-assurance)). The 2.5 series is the **Current** line (latest: v2.5.2) — an internal stabilization line that has passed the full release gate and is where all fixes land, pending production-soak certification; the DB schema is preserved across the line, and feature development resumes in 2.6. **v2.5.2 changes three things about MCP tool responses** — `store` reports its outcome in `result` (stored / skipped / rejected) instead of an always-true `ok`, `check_health` reports the single `status` verdict without the `healthy` boolean, and every tool-level failure a handler returns now carries `ok: false` (most used to return `error` alone, with no `ok` to branch on; the explanation still travels in `error`, except on `store`, which puts it in `reason`). Two shapes stay outside that rule and always did: the outermost MCP dispatch answers an unknown tool name, or an exception escaping a handler, with a bare `error` and no `ok` — that layer is vendored from a library shared with the other Cloto servers, so correcting it is an upstream change rather than a local edit — and a successful read (`get_contents`, `list_memories`, `list_episodes`, `get_profile`) returns its payload with no `ok` either. Branch on `ok is false`, and treat a response carrying `error` as a failure whether or not `ok` is present. Tiers and support windows: [Release Channels & Support](#release-channels--support).

## 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](https://modelcontextprotocol.io/) server that stores memories in a local SQLite file and retrieves them through hybrid search. Claude remembers you.

## Quick Start

**Prerequisites:** Python 3.11+ (and [uv](https://docs.astral.sh/uv/) for the one-command path).

> **Claude Code? Let the agent do the setup.** This repo ships an [Agent Skill](https://github.com/Cloto-dev/cpersona/blob/master/skills/cpersona-memory/SKILL.md) that walks Claude through the whole installation — cpersona, the embedding server, MCP registration, and a store/recall smoke test — and, more importantly, teaches it *when* to store, recall, and archive memories afterwards:
>
> ```bash
> # Installed from PyPI? The skill ships inside the wheel — no clone needed:
> 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)"
>
> # Running via uvx (isolated environment), or not installed yet:
> git clone --depth 1 https://github.com/Cloto-dev/cpersona.git /tmp/cpersona
> mkdir -p ~/.claude/skills && cp -r /tmp/cpersona/skills/cpersona-memory ~/.claude/skills/
> ```
>
> Then just tell Claude Code: *"Set up CPersona — I want persistent memory."* The manual steps below are for Claude Desktop users and anyone who prefers to configure things by hand.

### 1. Install cpersona

```bash
uvx cpersona          # run directly, no install step
# or
pip install cpersona  # then the `cpersona` command is on your PATH
```

<details>
<summary>From source (for development)</summary>

```bash
git clone https://github.com/Cloto-dev/cpersona.git
cd cpersona
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install .
```
Run it with `python -m cpersona` (or `python server.py`).
</details>

### 2. Set up Embedding Server (Recommended)

cpersona's hybrid search works best with an embedding server for vector similarity. cpersona is embedding-server-agnostic: point `CPERSONA_EMBEDDING_URL` (see step 3) at any HTTP endpoint that implements the following minimal contract.

```
POST /embed
Request:  { "texts": ["string", ...] }        # non-empty array, max 100 per batch
Response: { "embeddings": [[float, ...], ...], "dimensions": <int> }
```

Contract requirements (2.5.0b1 clarifications):

- **Embeddings MUST be L2-normalized.** cpersona computes similarity as a raw
  dot product; a backend returning unnormalized vectors biases ranking by
  vector magnitude. Every supported backend (the client's `api` mode and all
  CEmbedding providers) already normalizes.
- **The contract is role-less** — queries and documents are embedded through
  the same call. Prompt-prefix models (e5-style, prompted bge) will
  underperform behind it; symmetric or retrieval-merged models (jina-v5-nano,
  bge-m3, MiniLM) are the intended fit.
- **Swapping models behind the same URL:** cpersona fingerprints the backend
  by embedding *dimension* only (the contract carries no model identity). A
  same-dimension model swap silently invalidates the stored corpus — after
  one, re-embed (`check_health(fix=true)` repairs NULLed rows) and
  `calibrate_threshold`.

The reference server is [CEmbedding](https://github.com/Cloto-dev/CEmbedding) (MIT) — it runs jina-v5-nano on-device (CPU) and exposes exactly this endpoint:

```bash
git clone https://github.com/Cloto-dev/CEmbedding.git && cd CEmbedding
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install ".[onnx]"
python download_model.py --model jina-v5-nano
EMBEDDING_PROVIDER=onnx_jina_v5_nano python server.py   # serves http://127.0.0.1:8401/embed
```

cpersona ships with defaults tuned against jina-v5-nano (768d). Any other server that satisfies the contract above works too — see [Benchmarks](#benchmarks) for models with published measurements.

> Without an embedding server, cpersona falls back to FTS5 + keyword search only. Vector search (the strongest retrieval layer) will be disabled.

### 3. Configure your MCP client

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cpersona": {
      "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"
      }
    }
  }
}
```

The embedding server from step 2 is a plain HTTP process, not an MCP server —
run it however you run background services (a terminal, launchd/systemd, etc.);
cpersona only needs its URL.

> **Windows:** use `C:/Users/you/.claude/cpersona.db` for the DB path.
> **No embedding server yet?** Drop the two `EMBEDDING_*` lines (or set `EMBEDDING_MODE=none`) — cpersona runs on FTS5 + keyword and tells you when it's degraded.

**Claude Code:**

```bash
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
```

That's it. Claude now has persistent memory. Ask it to `store` something and `recall` it in a later session.

## Features

**Hybrid Search** — Three independent retrieval strategies run in parallel and merge results via Reciprocal Rank Fusion (RRF):

| Layer | Method | Strength |
|-------|--------|----------|
| Vector | Cosine similarity (jina-v5-nano, 768d) | Semantic meaning |
| FTS5 | SQLite full-text search with trigram tokenizer | Exact terms, names, IDs |
| Keyword | Fallback pattern matching | Edge cases, partial matches |

**Memory Types:**

- **Declarative memory** — Individual facts, decisions, instructions stored via `store`
- **Episodic memory** — Conversation summaries archived via `archive_episode`
- **Profile memory** — Accumulated user/project attributes via `update_profile`

**Confidence Scoring** — Each recalled memory gets a confidence score combining:

- Cosine similarity (semantic relevance)
- Dynamic time decay (adapts to corpus time range — a 1-year-old corpus and a 1-day-old corpus use different decay curves)
- Recall boost (frequently useful memories surface more easily, with natural fade-out)
- Completion factor (resolved topics decay faster)

**Zero LLM Dependency** — cpersona is a pure data server. It never calls an LLM internally. All summarization and extraction is performed by the calling agent. This means zero API costs from cpersona itself, deterministic behavior, and no hidden latency.

**Additional capabilities:**

- Agent namespace isolation — multiple agents share one DB without interference
- Background task queue — DB-persisted, crash-recoverable async processing
- JSONL export/import — full memory portability between environments
- Agent-to-agent memory merge — atomic copy/move with deduplication
- Auto-calibration — statistical threshold tuning via null d