ClaudeCodeMod

All shelves / MCP servers

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

  • Dockerdocker.io/marcellm01/tinycontext:v0.5.4stdio
  • PyPItinysuite-contextstdio

From the server's entry in the official MCP Registry.

Open the repo

Configuration

NameSet asWhat it is
MCP_TRANSPORTOptionalEnv varMCP transport to serve: stdio (default), sse, or streamable-http.
TINYCONTEXT_CONFIG_PATHOptionalEnv varPath to a context_config.json inside the container.
TINYCONTEXT_MEMORY_DB_PATHOptionalEnv varPath to the TinyContext SQLite database.
TINYCONTEXT_MODELS_DIROptionalEnv varDirectory used for downloaded ONNX embedding bundles.
OTEL_SERVICE_NAMEOptionalEnv varOpenTelemetry service name; defaults to tinycontext when telemetry is enabled.
OTEL_EXPORTER_OTLP_ENDPOINTOptionalEnv varOTLP collector endpoint for optional OpenTelemetry traces and metrics.
OTEL_EXPORTER_OTLP_PROTOCOLOptionalEnv varOTLP protocol: http/protobuf or grpc.
OTEL_EXPORTER_OTLP_HEADERSOptional · SecretEnv varOptional OTLP collector headers.

Files

README.md

TinyContext

TinyContext

Context that fits your local LLMs.

Part of TinySuite. Comes built in to TinyWebUI, and works with any MCP client.

Website PyPI version PyPI Downloads CI License: MIT Python Release Last Commit Docker Pulls Discord MCP Server FastAPI

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-vec handles 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.

MIT. See LICENSE and NOTICE.

Facts

Kind
MCP server
Repo
TinySuiteHQ/TinyContext
Group
Uncategorized
Stars
10
License
MIT
Language
Python
Last push
2026-11-12
Forks
3
MCP Registry
io.github.TinySuiteHQ/tinycontext
Homepage
tinysuite.dev

From the same owner

  1. 924io.github.TinySuiteHQ/tinysearchio.github.TinySuiteHQ/tinysearchFast discovery search and self-hosted web research for MCP agents.236