# ContextFit

> Token-native agent memory: retrieval that thinks in tokens, not vectors.

ContextFit is a filesystem-native Python memory retrieval engine for AI agents. It is built for people who want memory that is fast, inspectable, cheap to run, and emotionally trustworthy: no hidden vector database, no required embedding API, no GPU dependency, and no black-box preprocessing step between a user's history and the assistant trying to remember it.

## What matters

- ContextFit retrieves directly over tokenized conversation/session text.
- The core path is local, deterministic, CPU-only, and zero API cost.
- It uses interpretable primitives: memory atoms, episode relevance scoring, query routing, structural reranking, preference reranking, multi-session evidence coverage, and auditable evidence certificates.
- It supports compact citation handles: the model can see short `@r1` references while exact provenance, scores, and expiration live in a sidecar map for runtime/UI resolution.
- It is designed for agent memory: preferences, decisions, goals, constraints, temporal updates, open loops, and synthesis across sessions.
- It is not just a benchmark trick; it is a deployment simplification. The index is files on disk.

## Current headline results

- 499-case agent-memory eval, re-run on current code: 62.7% R@1 / 94.0% R@3 with routed rerankers plus evidence certificates. This beats Cohere and Mem0 on aggregate R@1, but still trails OpenAI text-embedding-3-small on the aggregate 499-case benchmark.
- Preference recommendation: 85.5% R@1, ahead of OpenAI embed-3-small on that behavior.
- Multi-session synthesis: 82.1% R@1, narrowing the embedding gap substantially.
- LongMemEval-S: 95.1% Any@5 pure token-native ContextFit with conversation-aware parent/child chunks. It matches OpenAI fusion on preference Any@5 (83.3%) and narrows multi-session Any@5 to within ~0.8 pts. A token-only companion-evidence coverage reranker preserves 95.1% Any@5 while improving overall All@5 from 77.9% to 80.4% and multi-session All@5 from 55.4% to 65.3%; adding token-native evidence certificates and typed rescue lifts the same non-fusion path to 96.8% Any@5 and 84.3% All@5 with paired top-5 movement +8 / 0. A fresh optional OpenAI fusion artifact reaches 96.6% Any@5 and 98.7% Any@10 evidence retrieval with no vector database required; evidence certificates lift that path to 98.3% Any@5 and 99.2% Any@10, and route-gated turn-aware chunk-vector fusion lifts it again to 98.94% Any@5, 99.57% Any@10, and 87.45% All@5. The selective chunk-vector run had zero paired Any@5 losses versus the full-session fusion certificate baseline, while complete-evidence All@5 moved +6 / -2. Current end-to-end QA progress reports 85.2% overall with a GPT-4o-only selective-fusion run, and 87.2% overall / 87.6% task-averaged with a GPT-5-mini answerer/extractor plus GPT-4o judging. These are local LongMemEval-style evaluations, not official leaderboard submissions.

## Install

```bash
pip install contextfit
```

## Minimal use

```python
from contextfit import RetrievalEngine

engine = RetrievalEngine()
engine.ingest_sessions(sessions)
engine.save("./memory_index")

result = engine.query_auto(
    "what should I cook for dinner tonight?",
    top_k=5,
)

print(result["route"])
print(result["session_ids"])
```

## Links

- Human site: https://context.fit/
- LLM-readable site brief: https://context.fit/site.md
- Whitepaper markdown: https://context.fit/token-native-agent-memory.md
- Whitepaper HTML: https://context.fit/whitepaper.html
- LongMemEval-S retrieval artifact: https://context.fit/longmemeval-fusion-20260519.html
- LongMemEval-S end-to-end QA artifact: https://context.fit/longmemeval-fusion-qa-20260519.html
- GitHub: https://github.com/ContextFit/cf
- Creator: Christophe Ponsart — https://x.com/cponsart

## Suggested citation

ContextFit: Token-Native Agent Memory. Christophe Ponsart, 2026. https://context.fit/


## Structure-aware ingestion

- File ingestion routes TMD ledger `.tmd` files to row-aware chunks, `.md` to heading/block-aware chunks, `.txt` to paragraph-aware chunks, `.json`/`.jsonl` to object/event records, `.csv`/`.tsv` to row-aware records, `.eml` to email-message chunks, `.ics` to calendar-event chunks, and common code files to symbol/import-aware chunks.
- Markdown chunks carry `heading_path`, `section_level`, `chunk_ordinal`, and `chunk_type=markdown_section`.
- The token-native storage/indexing path is unchanged: structure only selects better chunk boundaries before encoding.

- Demo page: https://context.fit/demo.html shows four agent-memory scenarios comparing nearest-text retrieval with ContextFit evidence retrieval.

- TMD ledger is a new ContextFit-proposed Tabular Markdown file format for row-addressable, human-readable ledgers that bridge Markdown notes and structured data.