# 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

- LongMemEval-S session retrieval: ContextFit token-native reaches 96.20% R@5 across 500 questions with no embeddings, no vector DB, and no LLM in retrieval.
- Optional ContextFit + OpenAI fusion reaches 99.00% R@5 on the same LongMemEval-S retrieval metric, above gbrain-hybrid's published 97.60% and MemPalace raw's published 96.60%.
- The 499-case agent-memory eval is an engineering diagnostic, not the primary homepage leaderboard claim. It shows behavior-level strengths: preference recommendation 85.5% R@1 vs OpenAI embed-3-small 77.4%, open-loop retrieval 80.3% vs 63.9%, temporal supersession 49.2% vs 47.6%, and multi-session synthesis 82.1% vs 87.5%.
- The product claim is that ContextFit adds routing, source aggregation, temporal handling, provenance handles, abstention, and local deployment controls around retrieval, rather than only optimizing raw embedding Recall@1.

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