tinycontext — Claude Code MCP server: local agent memory
Keeps an agent's notes and facts in SQLite and hands back only what fits a set token budget. Useful when old conversations keep bloating the context.
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env TINYCONTEXT_CONFIG_PATH=<TINYCONTEXT_CONFIG_PATH> --env TINYCONTEXT_MEMORY_DB_PATH=<TINYCONTEXT_MEMORY_DB_PATH> --env TINYCONTEXT_MODELS_DIR=<TINYCONTEXT_MODELS_DIR> --env OTEL_SERVICE_NAME=<OTEL_SERVICE_NAME> --transport stdio tinycontext -- uvx tinysuite-contextWhat tinycontext does
TinyContext is a local memory layer for AI agents. Entries and their embeddings live in SQLite, and retrieval is hybrid: BM25 alongside dense ranking. Only the portion that fits the requested token budget leaves the store. There is no hosted account, and no separate vector database is required.
Six tools are exposed: save_memories, recall_memories, list_memories, get_memory, update_memory, delete_memory. Saved entries carry a kind of episodic (the default) or profile — the latter holds durable facts about the user and is attached in full to every recall, capped by its own profile_max_tokens budget. Deduplication and token accounting happen at recall time, so saving often costs little.
Python 3.12 and uvx are required. On first launch the bare tinycontext command starts stdio MCP and pulls the chosen ONNX embedding set into the per-user data directory; the database appears on the first save or recall. Run tinycontext doctor to check the resolved configuration and storage readiness.
What it helps with
- carry agent memory across sessions without a cloud service
- fit a recall result inside a token limit
- find a stored entry by meaning rather than exact wording
- browse what has actually accumulated in the store
- correct or drop an outdated fact about the user
Example prompts for the agent
- Save to memory that this project builds with
uvand Python 3.12. - Recall everything we decided about the database schema.
- List the memories saved this week.
How to install tinycontext
Platform CLI
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env TINYCONTEXT_CONFIG_PATH=<TINYCONTEXT_CONFIG_PATH> --env TINYCONTEXT_MEMORY_DB_PATH=<TINYCONTEXT_MEMORY_DB_PATH> --env TINYCONTEXT_MODELS_DIR=<TINYCONTEXT_MODELS_DIR> --env OTEL_SERVICE_NAME=<OTEL_SERVICE_NAME> --transport stdio tinycontext -- uvx tinysuite-contextReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-context <command>
Platform CLI
codex mcp add tinycontext --env MCP_TRANSPORT=<MCP_TRANSPORT> --env TINYCONTEXT_CONFIG_PATH=<TINYCONTEXT_CONFIG_PATH> --env TINYCONTEXT_MEMORY_DB_PATH=<TINYCONTEXT_MEMORY_DB_PATH> --env TINYCONTEXT_MODELS_DIR=<TINYCONTEXT_MODELS_DIR> --env OTEL_SERVICE_NAME=<OTEL_SERVICE_NAME> -- uvx tinysuite-contextReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-context <command>
Config file
{
"mcpServers": {
"tinycontext": {
"command": "uvx",
"args": [
"tinysuite-context"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"TINYCONTEXT_CONFIG_PATH": "<TINYCONTEXT_CONFIG_PATH>",
"TINYCONTEXT_MEMORY_DB_PATH": "<TINYCONTEXT_MEMORY_DB_PATH>",
"TINYCONTEXT_MODELS_DIR": "<TINYCONTEXT_MODELS_DIR>",
"OTEL_SERVICE_NAME": "<OTEL_SERVICE_NAME>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-context <command>
Config file
{
"servers": {
"tinycontext": {
"type": "stdio",
"command": "uvx",
"args": [
"tinysuite-context"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"TINYCONTEXT_CONFIG_PATH": "<TINYCONTEXT_CONFIG_PATH>",
"TINYCONTEXT_MEMORY_DB_PATH": "<TINYCONTEXT_MEMORY_DB_PATH>",
"TINYCONTEXT_MODELS_DIR": "<TINYCONTEXT_MODELS_DIR>",
"OTEL_SERVICE_NAME": "<OTEL_SERVICE_NAME>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-context <command>
Platform CLI
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> -e TINYCONTEXT_CONFIG_PATH=<TINYCONTEXT_CONFIG_PATH> -e TINYCONTEXT_MEMORY_DB_PATH=<TINYCONTEXT_MEMORY_DB_PATH> -e TINYCONTEXT_MODELS_DIR=<TINYCONTEXT_MODELS_DIR> -e OTEL_SERVICE_NAME=<OTEL_SERVICE_NAME> tinycontext uvx tinysuite-contextReplace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-context <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about tinycontext
How do I install tinycontext in Claude Code?
Run claude mcp add tinycontext -- uvx tinysuite-context. A variant with --env flags and --transport stdio is available when environment variables are needed.
What does tinycontext do?
It keeps agent memory locally in SQLite and returns relevant entries on request, trimmed to a token budget. Retrieval combines BM25 with dense ranking.
What does tinycontext need to run?
Python 3.12 and uvx. The first launch downloads the ONNX embedding set into the per-user data directory, and the database is created on the first save or recall.
