# 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, and multi-session evidence coverage.
- 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: 62.3% R@1 / 93.0% R@3 with routed rerankers.
- 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%; optional OpenAI fusion reaches 96.0% Any@5 and still leads on full multi-session coverage at 72.7%.

## 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
- 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.
