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

# Recommended: Chroma + an embedding model for semantic memory
pip install "personatrace[vector]"

# Minimal install: lexical/time fallback only
pip install personatrace

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.

Recommended Chroma episode index

SQLite owns the episode rows and all state. Chroma is the recommended candidate index for semantic retrospective search; install it unless you explicitly want the lexical/time-only fallback. The embedding model is what makes semantic recall work; Chroma is the index, not the source of truth.

from personatrace.chroma_index import ChromaEpisodeIndex

index = ChromaEpisodeIndex(
    path="./persona_data/chroma",
    embed_fn=embed_fn,          # list[str] -> list[list[float]]
)
memory = MergedMemory(
    user_id="alice",
    sqlite_path="./personatrace.db",
    vector_index=index,
)

If Chroma is unavailable, EpisodeStore falls back to lexical + time search. That fallback is intentionally usable, but it is weaker for paraphrases and larger episode archives. The v1 persona_items collection is separate; episodes use episode_turns.

Quick start: structured memory

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

from personatrace import MergedMemory

memory = MergedMemory(
    user_id="alice",
    sqlite_path="./personatrace.db",   # one file for the whole memory
)
# Omitting sqlite_path is also durable now: beliefs, intentions, episodes and
# routines all follow the default backend path.

memory.write(
    beliefs=[{
        "category": "identity",
        "label": "Name is Mo",
        "confidence": 0.9,
        "reasoning": "user introduced themselves",
    }],
    intentions=[{
        "action": "attend class",
        "due": "2026-10-25",
        "importance": 0.9,
        "confidence": 0.8,
    }],
    source="direct",
)

context = memory.build_context("When is my deadline?")
print(context.agenda_lines)
print(memory.inject("When is my 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.

Turn and routine

turn = memory.record_turn("I have class every Tuesday at 19:00", session_id="s1")
memory.label_routine(
    "attend class",
    time="19:00",
    weekdays=[2],              # Monday=1 ... Sunday=7
    anchor_date="2026-10-20",
    valid_until="2026-12-20",  # semester end
    status="candidate",
)
pack = memory.build_context("Are we talking?")
print(pack.routine_probes)     # hints only; the host decides whether to ask

A routine is weekly, not daily. One observation creates a candidate; explicit label_routine or a confirmation makes it weekly. skipped_today, denied and silence are separate states.

MCP

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

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

Every tool call runs in one isolated worker process with an 8s deadline. A timeout kills the worker, so a slow call cannot keep writing behind the error result or exhaust a shared thread pool; the next call starts a fresh worker. In-memory mode (PERSONA_DB=off) runs in-process and is tests-only. JSON-RPC batch arrays are accepted, and malformed messages return an error instead of crashing the stdio loop. Both tool families use one PERSONA_USER_ID and one store, so memory_observe is visible to memory_context.

See MCP.md.

Evaluation

A 200-belief, 50-query fixture is included. It is a directional gate, not a benchmark. The earlier 12/10 fixture scored 90.0%; it was too easy.

method                      recall@3     MRR
v2 native (query, no pinned)    66.0%   0.707
v2 native (pinned)              52.0%   0.290
outer lex                       61.0%   0.637
outer + bge                     74.0%   0.770
outer + bge + time facet        76.0%   0.760

v2 native (query) is the kernel's own lexical channel with no outer layer. pinned is capped at half the budget (max(1, k // 2)), so constraints and boundaries cannot consume the whole query budget. The useful comparison is outer + bge → + time facet: +2.0 recall but -0.010 MRR. The time bucket can promote a due item above an equally correct semantic item. The larger fixture is the number to quote; CI gates the deterministic outer lex channel at 60%.

python scripts/eval_recall.py
python scripts/eval_recall.py --no-embed
# CI gate (deterministic, no embedding model required)
python scripts/eval_recall.py --no-embed --fail-under 0.60 --gate-method "outer lex"

LongMemEval temporal-reasoning subset

First external run, not the full benchmark and not GPT-4o:

133 questions (temporal-reasoning)     101 correct   75.9%
20 questions (first run)                 17 correct   85.0%
20 questions (timed run)                 16 correct   80.0%
retrieval hybrid+rerank (133)           recall@3 86.8%, MRR 0.935
build 32,930 episodes                   1,259.9 s; reuse 2.5 s

Answerer and judge are both deepseek-flash at temperature 0, so self-judge bias applies. The bilingual episode hook opens on 132/133 questions (20/20 on the smoke set). The merged-context gate and the retrieval numbers are explained in LONGMEMEVAL.md.

Design notes

The full failure analysis, measurements, tradeoffs and pitfalls are in DESIGN_NOTES.md. The temporal kernel is described in MEMORY_V2.md. The routine/vector research note is ROUTINE_MEMORY_RESEARCH.md. Release history is in CHANGELOG.md; the v1 → 2.x import/behavior changes are in UPGRADING.md.

What is shipped

Known limits:

• single user; no multi-tenant or auth;
• no UI, persona, or proactive messaging;
• dedup is lexical and conservative; numbers/months must match, and a low-overlap paraphrase can still create a second record;
• 50 queries are still a small evaluation set;
• routines are weekly fields, not a full RFC 5545 RRULE parser yet;
• episode retrieval falls back to lexical/time when Chroma is unavailable; Chroma requires an embedding function
• routine probes are hints; the host must ask and must report feedback;
• there is no background scheduler and no automatic proactive message;
• old Chroma profiles must be migrated with scripts/migrate_v1.py; the runtime v1 pipeline is no longer shipped.

License

MIT