io.github.TinySuiteHQ/tinycontext
io.github.TinySuiteHQ/tinycontext · 10 stars · Python · MIT
MCP server Token-light local memory with SQLite hybrid retrieval for MCP agents.
Install
The repo has no one-line install. Follow its README.
Published as
- Docker
docker.io/marcellm01/tinycontext:v0.5.4stdio - PyPI
tinysuite-contextstdio
From the server's entry in the official MCP Registry.
Configuration
| Name | Set as | What it is |
|---|---|---|
MCP_TRANSPORTOptional | Env var | MCP transport to serve: stdio (default), sse, or streamable-http. |
TINYCONTEXT_CONFIG_PATHOptional | Env var | Path to a context_config.json inside the container. |
TINYCONTEXT_MEMORY_DB_PATHOptional | Env var | Path to the TinyContext SQLite database. |
TINYCONTEXT_MODELS_DIROptional | Env var | Directory used for downloaded ONNX embedding bundles. |
OTEL_SERVICE_NAMEOptional | Env var | OpenTelemetry service name; defaults to tinycontext when telemetry is enabled. |
OTEL_EXPORTER_OTLP_ENDPOINTOptional | Env var | OTLP collector endpoint for optional OpenTelemetry traces and metrics. |
OTEL_EXPORTER_OTLP_PROTOCOLOptional | Env var | OTLP protocol: http/protobuf or grpc. |
OTEL_EXPORTER_OTLP_HEADERSOptional · Secret | Env var | Optional OTLP collector headers. |
Files
TinyContext
Context that fits your local LLMs.
Part of TinySuite. Comes built in to TinyWebUI, and works with any MCP client.
Read the documentation → tinysuite.dev/docs/tinycontext
TinyContext is the memory layer of TinySuite, a set of small, local-first tools that make agents spend tokens on useful work rather than overhead. It stores concise memories and their embeddings in SQLite, ranks them with hybrid BM25 and dense retrieval, and returns only the context that fits the requested token budget, so an agent recalls a small, ranked set of memories instead of resending its history.
No hosted account. No giant context dumps. No required vector database. Against an agent that resends every stored memory, recall used 96.7% fewer tokens, with p95 latency around 12 ms at 20,000 memories (docs/benchmarks.md).
Highlights
- No vendor in the loop. No account, no required API key, no per-request billing, no hosted memory service. Memories stay in a SQLite file you own.
- Recall that fits the budget. Ranking and token trimming happen locally, so only the memories that fit reach the model.
- No required vector database. Embeddings and BM25 live in the same SQLite row;
sqlite-vechandles similarity. - Profile memories. Durable facts such as what to call the user ride along with every recall, under their own small budget.
- Six small MCP tools. Save, recall (by meaning or most recent first), list, get, update and delete, with short stable
refs for corrections. - Self-maintaining. Near-duplicates are skipped at save time, and changing the embedding model re-embeds the store in the background.
- Multi-user when hosted. Behind a trusted proxy, each user gets a separate SQLite store, checked on every message.
- Works where agents already work. MCP over stdio or Streamable HTTP, Python, FastAPI, or Docker. Local ONNX embeddings are the default.
Quick start
| Tier | Use it when | Entry point |
|---|---|---|
| Python library | You are building an agent or Python application | pip install tinysuite-context |
| One-command MCP | An MCP client should launch TinyContext for you | uvx --python 3.12 --from "tinysuite-context[server]" tinycontext |
| Docker | You want persistent self-hosted storage and HTTP MCP | docker compose ... up -d (Docker) |
With uv installed, add TinyContext to any stdio MCP client:
{
"mcpServers": {
"tinycontext": {
"command": "uvx",
"args": ["--python", "3.12", "--from", "tinysuite-context[server]", "tinycontext"]
}
}
}
The no-argument tinycontext command runs stdio MCP. On its first launch, TinyContext downloads the selected ONNX embedding bundle into its per-user data directory. The database is created lazily on the first save or recall. Later launches reuse both local assets.
Check the resolved configuration and storage readiness with:
uvx --python 3.12 --from "tinysuite-context[server]" tinycontext doctor
From Python, pip install tinysuite-context and call save_memories and recall_memories directly (Python library). MCP, FastAPI and Docker are adapters around that same engine.
Documentation
The full reference lives at tinysuite.dev/docs/tinycontext:
| Topic | Covers |
|---|---|
| Quick start | MCP over stdio |
| Installation | Python, uvx, Docker |
| Docker and HTTP MCP | The published image, local builds, the FastAPI profile |
| Hosted multi-user | The trusted proxy and per-user stores |
| Management views | Browsing and editing memories from a client UI |
| Python library | The engine, its config and results |
| MCP tools | The six tools, profile memories, what recall returns |
| How recall works | Hybrid ranking and the token budget |
| FastAPI | The HTTP API and its error codes |
| OpenTelemetry | Traces and metrics |
| Configuration | Every setting and environment variable |
| Benchmarks | Speed, token savings and accuracy |
| Troubleshooting | tinycontext doctor and common problems |
| Development and security | Working from a checkout, entrypoints, release signing |
In this repository: docs/benchmarks.md is the full benchmark write-up, with how it compares to published Mem0 and Zep numbers and the scripts to rerun every figure, and configs/context_config.json is an example configuration.
Development
git clone https://github.com/TinySuiteHQ/TinyContext cd TinyContext python -m venv .venv source .venv/bin/activate pip install -e ".[server]" python -m unittest discover tests python scripts/smoke_mcp_stdio.py
TinyContext supports Python 3.12 and newer. CI tests Python 3.12, 3.13, and 3.14 across Linux, macOS, and Windows.
Release images are scanned with Trivy, run as a non-root user, and signed with Cosign. SECURITY.md has the details and how to report a vulnerability; SUPPORT.md is the support policy.
Questions, ideas, and bug reports are welcome on Discord or in GitHub issues.
License
TinyContext is built and maintained from Vienna, Austria: useful software, small enough to understand, and maintained long enough to rely on. Release history is on the Releases page.
Facts
- Kind
- MCP server
- Group
- Uncategorized
- Stars
- 10
- License
- MIT
- Language
- Python
- Last push
- 2026-11-12
- Forks
- 3
- MCP Registry
- io.github.TinySuiteHQ/tinycontext
- Homepage
- tinysuite.dev