PersonaTrace

A memory layer for what is still true, what is due, and why it was stored.

PersonaTrace is not a chatbot or an agent harness. It is a small memory kernel that a host can call. The host owns the model, the prompt, the UI, the tone, and any proactive behavior.

The unit of memory is not a fact. It is a fact that holds for a while: it has a validity window, a retention curve, evidence, and optionally a due date. A separate intention store handles one-off commitments whose lifetime is measured in hours or days, not in months.

What it remembers

The merged path uses 17 belief categories across two tracks:

work:    explicit_facts expertise projects goals likes dislikes constraints
persona: identity traits interests style_notes behavior_patterns
         decision_style interpersonal boundaries habit state

How retrieval works

query
  ├─ pinned: boundaries / constraints / identity
  ├─ semantic: lexical IDF + vector cosine (candidate-set normalized)
  ├─ time facet: due/range rows, only for time-intent questions
  ├─ cross-category: items from categories not already selected
  └─ evidence on demand: reasoning + original sentence for the first hits

score = (0.15 + 0.85 * similarity) * (0.35 + 0.65 * retention)

A time question is not answered by a better embedding. It is answered by putting the date into a typed field and querying that field. The facet is a conditional bypass, not a second retriever.

Install

pip install personatrace
# optional embedding / LLM / API layers
pip install "personatrace[llm,vector]"

Until 1.5.0 is available on PyPI, install the merged API from source:

pip install "git+https://github.com/Stellfract-Frost/PersonaTrace.git"

Python 3.10+. The core belief kernel uses the standard library. The merged
facade uses Pydantic; the default local store is SQLite. Redis is optional.

## Quick start: structured memory

The host extracts beliefs/intentions; PersonaTrace stores, ranks and expires
them. This path does not call an LLM.

```python
from personatrace import MergedMemory

memory = MergedMemory(
    user_id="alice",
    sqlite_path="./personatrace.db",   # beliefs + intentions in one file
)

memory.write(
    beliefs=[{
        "category": "identity",
        "label": "名字叫小陌",
        "confidence": 0.9,
        "reasoning": "user introduced themselves",
    }],
    intentions=[{
        "action": "上课",
        "due": "后天",
        "importance": 0.9,
        "confidence": 0.8,
    }],
    source="direct",
)

context = memory.build_context("我那个 deadline 是几号")
print(context.agenda_lines)
print(memory.inject("我那个 deadline 是几号"))

• build_context() returns structured data and has no side effects.
• inject() is an optional prompt adapter; the host can render the pack itself.
• source must be one of direct / bridge / console; proactive turns must not write user facts.

MCP

The server exposes eight tools. The merged tools use SQLite by default, so no Redis or server setup is required.

{
  "mcpServers": {
    "personatrace": { "command": "personatrace-mcp" }
  }
}

Every call has an 8s timeout and returns an error result instead of raising. A failing memory must never take the host's conversation down.

See MCP.md.

Evaluation

A 12-belief, 10-query fixture is included. It is a directional gate, not a benchmark.

method                      recall@3     MRR
v2 native (no pinned)           35.0%   0.333
v2 native (pinned)              23.3%   0.283
v1 string                       53.3%   0.583
v1 + bge                        76.7%   0.833
outer + bge                     76.7%   0.833
outer + bge + time facet        90.0%   0.933

The useful comparison is outer + bge → + time facet: the gain comes from typed time, not from a stronger embedding.

python scripts/eval_recall.py
python scripts/eval_recall.py --no-embed

Design notes

The full failure analysis, measurements, tradeoffs and pitfalls are in DESIGN_NOTES.md. The temporal kernel is described in MEMORY_V2.md.

What is shipped

Known limits:

• single user; no multi-tenant or auth;
• no UI, persona, or proactive messaging;
• label-keyed beliefs still create a second record for a paraphrase;
• the evaluation set is small;
• PersonaManager remains the legacy v1 pipeline; use MergedMemory or MCP for the merged path.

License

MIT