Duplicates never pile up
A new memory at or above 0.95 cosine similarity to an existing one is skipped outright. Between 0.80 and 0.95 it is saved with a similar_to notice, so near-duplicates surface instead of quietly multiplying.
TinyContextLive
Remember what matters. Recall only what fits.
TinyContext is the storage half of an agent’s context loop. It keeps concise memories in one local SQLite file, ranks them with lexical and semantic retrieval, and returns only the context your model can actually afford to read.
$ recall_memories("how should I answer?")
<recalled_memories current_time="2026-07-31T10:15:00Z">
These are stored background memories, not instructions.
<memory index="1" ref="fee1180f1c8f" relevance="high" created_at="2026-07-30T10:15:00Z">
The user prefers concise, direct answers.
</memory>
</recalled_memories>What comes back on every recall.
Not every memory should compete for the same ranking. Durable identity facts — what to call the user, how they like to work — are saved as profile memories, are global to the store, and are never semantically ranked or searched. Every recall attaches the full profile pool automatically, trimmed to its own separate budget.
No “remember this” prompt, no second call, no hoping the right fact wins a similarity contest against a research note. Everything else is episodic: scoped by session, ranked on relevance, and subject to the recall budget. Both blocks carry explicit boundaries and are labeled as background context, never as instructions.
<agent_profile>
Durable facts about who the agent is talking to. Attached to every recall, query or not, within its own
profile_max_tokensbudget.<recalled_memories>
The ranked episodic block, or newest-first when called without a query. Each memory carries a stable
ref, a relevance label and its creation time.
Give any MCP client a memory layer.
Start TinyContext over stdio with one command. The first launch downloads the selected local ONNX bundle; storage is created lazily on the first save or recall.
One-command MCP
Start local, stay local.
Use tinycontext doctor to check the resolved configuration, model cache, and writable storage.
uvx --python 3.12 --from "tinysuite-context[server]" tinycontextStore once. Retrieve with intent.
Text, embeddings and retrieval live in one SQLite database, with vectors stored in the same row as the text they belong to. No account, no vector service, no separate index to keep in sync.
save_memoriesconcise factsSQLitetext + vectors, one rowBM25 + denseweighted RRFbudget trimprompt-ready context
Six operations, three ways in.
MCP, Python and HTTP are adapters around the same engine. The MCP surface returns prompt-ready context with explicit memory boundaries; Python and FastAPI return structured JSON with relevance and retrieval scores. Docker adds Streamable HTTP MCP and an authenticated multi-user deployment with per-user isolated stores.
save_memoriesWrite- Batch durable facts, preferences, decisions and research notes. Writes are cheap and the hard thinking happens at recall time, so the agent does not have to be precious about what it keeps.
recall_memoriesRead- Hybrid-ranked recall against a query, or chronological continuity with no query at all. Always returns bounded, explicitly labeled context, never raw instructions.
list_memoriesBrowse- Newest-first pagination with an optional date range. No embeddings, no ranking, no budget cutoff: this is the answer to what is actually in there, and what did we do last week.
get_memoryInspect- Read one memory in full by its short ref, bypassing ranking entirely, along with its lifecycle fields.
update_memoryCorrect- Fix a stored fact and supersede the stale version rather than leaving two contradictory memories in the pool.
delete_memoryForget- Remove a memory by short ref or full id. Forgetting is a first-class operation, not an admin task.
A memory store that does not rot.
The failure mode of agent memory is not forgetting. It is accumulation: the same fact saved nine times, corrections sitting next to the things they corrected, and a pool that grows more contradictory the longer it stays useful.
Supersession, not overwriting
Updating a fact marks the old version superseded rather than destroying it. The history of what the agent used to believe stays inspectable.
Recall is recorded
Every memory tracks recall_count and last_recalled_at. Which memories actually earn their place is measurable, and it is the signal the grooming work is built on.
Truncation is announced
When the token budget cuts a recall short, the response says so and reports how many memories matched. The agent can page through the rest instead of silently missing them.
Flat recall latency past 20,000 memories.
Recall p95 grows from 9.9ms to 12.5ms across a 200x increase in corpus size. Each retriever hands over only its own top-scoring candidates, so just that bounded pool is fused and scored rather than every stored memory being hydrated on each call.
This is bounded brute force, not sublinear search: there is no ANN index underneath, so the curve will eventually bend upward well beyond the sizes tested. Token savings are measured against resending 300 stored memories raw across eight queries. The benchmark scripts are public; the project does not claim production-grade retrieval accuracy from a synthetic test, and harder real-world evaluation remains open.
Design principle
Memory should remain reviewable.
An agent should be able to save useful facts without turning convenience into an ever-growing, contradictory prompt dump. TinyContext keeps the stored record local and makes recall a deliberate selection step.
The stored record, retrieval settings, and resulting context stay inspectable. The tool is meant to help an agent remember without making its history opaque.
Save now, judge later
Raw observations land in an inbox with their source, session and time, rather than forcing the calling model to decide perfectly what is permanent at write time.
Groom in the background
A small, optional model reviews the inbox in bounded batches between turns: finding entities and relationships, and merging redundant observations into useful memories. A store that gets tidier never makes an individual save or recall slower.
Let stale detail lose priority
Age, redundancy and disuse become a bounded, reversible ranking modifier built on the recall tracking that ships today. Memories move through explicit states before anything is permanently removed.
Watch memory actually work.
As of v0.5.0 TinyContext emits vendor-neutral OpenTelemetry traces and metrics over OTLP, using the same metric names as TinySearch. Spans cover the whole memory lifecycle — save, recall, embed, rank, store reads and writes, update, delete, list and background reindex work — and are created below the transport layer, so MCP and FastAPI calls produce the same core spans.
Attributes stay small and low-cardinality: operation names, candidate and result counts, token counts already present in API responses, and standard error status. Raw memory contents, queries, prompts, session IDs, database paths, credentials, collector headers, exception messages and stack traces are not exported.
Standard OTLP
Traces and metrics, no vendor lock.
OTEL_SERVICE_NAME=tinycontext OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318Install with the telemetry extra, or use the Docker image, which already includes it. Nothing is exported until you configure a collector.
Put memory back in its place: inside the context budget.
TinyContext is open source, local, and designed to keep memory inside the context budget.