# CPersona

> MCP memory server: persistent, searchable memory for Claude and any MCP
> host. Single local SQLite file, 3-layer hybrid retrieval (vector + FTS5 +
> keyword), zero LLM dependency — the server never calls a generative model.
> This site is the canonical documentation for the 2.5.x line; when another
> surface (README, bundled skill) disagrees, the site wins.

Key facts an agent should not guess wrong: recall responses are ordered
ascending by score (the LAST element is the best match); `store` dedup is
skip-not-upsert (changed content under a reused msg_id is NOT updated — use
update_memory); autocut is inert under the default rsf/rrf fusion modes
(set_recall_precision is the effective gate knob); profile rows carry no
score and can be cut by limit unless confidence scoring is enabled;
CPERSONA_MAX_MEMORIES is the vector scan window, not a storage cap.

## Docs

- [Getting Started](https://cloto-dev.github.io/CPersona/getting-started/): install, the embedding-server contract and its reference implementation, MCP client registration, verification
- [Roadmap](https://cloto-dev.github.io/CPersona/roadmap/): what each release line is for and may break, the planned 2.6 retrieval features and the measured problem each answers, what remains of the earlier 3.0 graph plan, and the runtime/scale ladder towards a Go index service — descriptive, not a commitment
- [Reliable Recall (2.6)](https://cloto-dev.github.io/CPersona/2.6/RELIABLE_RECALL_2_6/): the canonical account of the 2.6 line — Deliberative Recall (a bounded deterministic loop inside one call that spends none of the agent's tokens), Cued Recall (cues as priors, never filters), one prior function, depth separated from count, adaptive fusion, associations and overflow chains as cues, Reconstructive Recall and its Reconstruction Window, the recall trace and failure taxonomy, how the line is measured, and what "done" means
- [Progress of 2.6](https://cloto-dev.github.io/CPersona/2.6/PROGRESS_2_6/): where the 2.6 line stands against each of its completion conditions, in four states (released / in development / in research / withdrawn or reworked), every row with the pull request, release or measurement record that supports it
- [Memory Intelligence (2.7)](https://cloto-dev.github.io/CPersona/2.6/MEMORY_INTELLIGENCE_2_7/): the canonical account of the 2.7 line, design only and unmeasured — correction and contradiction (declared relations; the corrected side returns as a ref unless asked for), temporal state and history (agent-asserted validity intervals, the bi-temporal model), evidence-weighted confidence returned with its grounds and never used to reorder, forgetting and retention policy (retire is not delete; the server lists, an explicit operation applies), feedback on what a recall was used for (never an automatic ranking change), the open questions in each, and what "done" means
- [Architecture](https://cloto-dev.github.io/CPersona/architecture/): component layout, SQLite/FTS5 storage, the three retrieval channels and the fusion → gate → reverse pipeline, isolation axes, zero-LLM rationale
- [Tools](https://cloto-dev.github.io/CPersona/tools/): every tool grouped by purpose, each linked to the contract it can surprise you with
- [Configuration](https://cloto-dev.github.io/CPersona/configuration/): every environment variable with defaults; HTTP transport and its authentication requirements
- [Behavior Contracts](https://cloto-dev.github.io/CPersona/behavior-contracts/): the behaviors callers may rely on — recall ordering, confidence×fusion interaction, episode boundary penalty, scan window, dedup, autocut, profile scoring, gate_fallback, lock semantics
- [FAQ](https://cloto-dev.github.io/CPersona/faq/): question-shaped index into the pages above
- [Operations Runbook](https://cloto-dev.github.io/CPersona/operations/): WAL-safe backup, degradation detection, recall tuning order, Japanese/CJK guidance, corpus indexing patterns, maintenance cadence
- [Upgrading to 2.6](https://cloto-dev.github.io/CPersona/2.6/upgrading-to-2.6/): one-pass upgrade from a 2.5.x store to the current 2.6 pre-release: backup, what the first start migrates, the node backfill, recalibration, behaviour changes, and how to go back
- [Quality Assurance](https://cloto-dev.github.io/CPersona/quality-assurance/): how a release is gated — audit rounds, the bug ledger, structural CI gates, mutation proof, and the gates that check the docs themselves

## Project standards

Normative documents. They state what a release, an audit report or a generated
policy block MUST look like, and they are written to be adopted by projects
other than this one.

- [Release lifecycle standard](https://cloto-dev.github.io/CPersona/RELEASE_LIFECYCLE_STANDARD/): tier definitions (Stable / Current), the risk-triggered pre-release ladder, support windows
- [SuperAuditor standard](https://cloto-dev.github.io/CPersona/SUPERAUDITOR_STANDARD/): the pull contract for reporting findings — severity vocabulary, cap semantics, and the deliberate silence on what a server detects
- [CLAUDE.md policy standard](https://cloto-dev.github.io/CPersona/CLAUDE_MD_POLICY_STANDARD/): how a project's skill generates a marker-wrapped policy block into always-loaded agent memory, and why a skill alone cannot carry that guarantee

## Design notes

Point-in-time records of how one behavior was decided, including the routes
that were rejected. They are not the current-state reference — where a design
note and the pages above disagree, the pages above win.

- [Per-client capabilities (ACL)](https://cloto-dev.github.io/CPersona/ACL_DESIGN/): named bearer tokens, per-agent read/write grants, deny-by-default
- [OAuth support](https://cloto-dev.github.io/CPersona/OAUTH_DESIGN/): resource-server metadata and token verification, the three routes weighed and why issuance is delegated to an external provider, the per-subject boundary
- [Server-served operating context](https://cloto-dev.github.io/CPersona/OPERATING_CONTEXT_DESIGN/): distributing operator instructions to all connected MCP clients
- [Declared session identity](https://cloto-dev.github.io/CPersona/SESSION_IDENTITY_DESIGN/): the declared `session_key`, why one process is not one session under streamable-HTTP, and which process-global state it re-partitions
- [Recorded access origin](https://cloto-dev.github.io/CPersona/MEMORY_ORIGIN_DESIGN/): recording the observed caller on each stored row, for the paths where `agent_id` names nobody
- [Recall preview tier](https://cloto-dev.github.io/CPersona/RECALL_PREVIEW_TIER_DESIGN/): preview truncation and the get_contents expansion path
- [Contiguous embedding index](https://cloto-dev.github.io/CPersona/CONTIGUOUS_INDEX_DESIGN/): moving the vector scan's read off SQLite rows onto a contiguous sidecar, with bit-identical answers
- [Reach and recency in the scan window](https://cloto-dev.github.io/CPersona/SCAN_WINDOW_REACH_DESIGN/): why widening the vector scan window loses recent answers, and the second ranked list that lets reach move without removing the recency prior
- [Reach, recency and the far vote](https://cloto-dev.github.io/CPersona/2.6/REACH_AND_RECENCY_PLAN/): three measurements of the scan window, the reach and the far list's length in one account, and the plan for pricing the far vote in the 2.6 line
- [One prior function](https://cloto-dev.github.io/CPersona/2.6/PRIOR_FUNCTION_DESIGN/): every position and age weight as one function p(row) that decides the order of a recall and never which rows pass the quality gate, the confidence score returned beside each row instead of re-sorting the list, and what is measured before any default moves
- [The recall process, v0](https://cloto-dev.github.io/CPersona/2.6/RECALL_PROCESS_DESIGN/): a recall trace that returns, on request, which rows each stage kept, dropped and reordered and why, with suspected and confirmed failure codes kept apart; and a time cue whose period is searched as one more arm and whose rows move up by at most L places after the quality gate, with one reserved seat and one widening revision
- [Adaptive fusion](https://cloto-dev.github.io/CPersona/2.6/ADAPTIVE_FUSION_DESIGN/): a reservation invariant across the recall path, the pool-size gate's rank cut removed, a measured lexical-weight constant now and a conditional-evidence fusion mode later, and the pre-registered comparison that decides between them
- [Block reach](https://cloto-dev.github.io/CPersona/2.6/BLOCK_REACH_DESIGN/): clause-sized blocks of a long record, quantised to one bit per dimension and ranked by Hamming distance, collapsed to their parent and admitted by a held reservation rather than through the quality gate, so a tail the embedding window never read becomes reachable without moving the quantity that gate is calibrated on
- [Binary coarse search](https://cloto-dev.github.io/CPersona/2.6/BINARY_COARSE_SEARCH_DESIGN/): a one-bit index of every record, scanned by Hamming distance and re-ranked by the stored vectors, so records past the scan window are held beside the answer and a time cue's period is searched whole
- [Overflow tree](https://cloto-dev.github.io/CPersona/2.6/OVERFLOW_TREE_DESIGN/): dividing a long record into spans that each fit the embedding window, stored as offsets in their own table, so a returned record can be quoted by its most relevant part while recall results stay unchanged
- [Associative memory](https://cloto-dev.github.io/CPersona/2.6/ASSOCIATIVE_MEMORY_DESIGN/): a declared graph of entities, aliases and subject–predicate–object relations, stored verbatim and walked deterministically, that reconstructive recall reads as cues, bundling keys, evidence and roles; with nothing declared the output is byte-identical
- [Embedding degradation advisory](https://cloto-dev.github.io/CPersona/DEGRADED_ADVISORY_DESIGN/): how recall reports a dead embedding layer instead of silently degrading

## Research notes

What the design pages rest on: derivations, measurements and refutations, each
with its assumptions and the observation that would refute it. Not behaviour.

- [Research notes overview](https://cloto-dev.github.io/CPersona/2.6/research/): the status vocabulary (derivation / measurement / refuted / superseded) and how a note is written
- [Adaptive fusion, a derivation](https://cloto-dev.github.io/CPersona/2.6/research/adaptive-fusion-derivation/): combining retrieval arms through null exceedance probabilities; a mixture rule with closed-form per-row influence whose limit is reciprocal rank fusion; the measurements that must precede implementation
- [Calibration and the admission floor](https://cloto-dev.github.io/CPersona/2.6/research/calibration-admission-floor-2026-09/): three calibration methods on seven losing tasks — the floor is not the cause, the null came from the wrong pair population, small corpora starve the dense arm
- [Where the loss is, a frozen-stage replay](https://cloto-dev.github.io/CPersona/2.6/research/frozen-stage-replay-2026-09/): every stage of the Track B path scored on frozen embeddings and lexical scores, three models, pinned to the live pipeline — the pure-ranking losses are the fusion step, Gorilla's is admission, EPBench's is the pool-size gate, QASPER's positive fusion delta is replenishment
- [Two arms, one decision](https://cloto-dev.github.io/CPersona/2.6/research/adaptive-fusion-identifiability/): no rule that sees only per-arm scores and null exceedance probabilities can decide when lexical evidence should override dense evidence; the deciding quantity is the lexical evidence conditional on the dense score; a joint density ratio over a reference panel supplies it without a fitted weight

## Optional

- [Sponsorship](https://cloto-dev.github.io/CPersona/sponsorship/): what sponsoring does and does not buy, where it goes, and the ways to help that cost nothing
- [Repository](https://github.com/Cloto-dev/cpersona): source, README quick start, issues
- [PyPI](https://pypi.org/project/cpersona/): pip / uvx installation
- [Bundled agent skill](https://github.com/Cloto-dev/cpersona/tree/master/skills/cpersona-memory): teaches an MCP agent the store / recall / archive workflow and the CLAUDE.md policy block