TinyDB Emcipi

TinyDB Emcipi is a compact MCP server that adds long-term memory to your chatbots by storing, searching, and mutating JSON records on disk. It validates records with a schema and provides a simple, zero-dependency path to persistent memory that you can use locally or in CI.

How to use

You interact with the server through an MCP client to store and retrieve memory. Use the discovery and record tools to create databases, define schemas, add and query records, and switch the active database as needed. The server exposes a memory-backed JSON store that your chatbot can read and update over time, enabling more cohesive long-term conversations.

How to install

Prerequisites: you need Python and a working network environment. You will also need Docker if you prefer containerized deployment.

pip install -r requirements.txt
python -m main

This starts the MCP endpoint at http://localhost:8000/mcp and runs directly on your machine without containerization.

If you prefer a Docker-based setup, you can run the service with Docker Compose. This is docker-friendly and suitable for local development or CI pipelines.

docker compose up

The compose file mounts the repository into /app inside a python:3.12-slim container and starts the same startup command as above.

Notes and tips

Available tools let you manage databases and records, inspect schemas, and perform searches. You can create a new database with an initial schema, list existing databases, switch the active database, and access schema information and sample records. For records, you can search by field values, retrieve all records, and add or update records with validation against the current schema.

Security and maintenance

Since memory is stored on disk, ensure your environment has appropriate file-system permissions and consider backing up the TinyDB JSON files regularly. When working in shared or CI environments, keep the memory data isolated to avoid cross-job contamination.

Available tools

create_database_tool

Create a new TinyDB database with an optional initial schema, establishing the storage backend for future records.

list_databases_tool

List all available TinyDB JSON databases so you know what memory stores exist on disk.

switch_active_db_tool

Set which database is currently active for subsequent operations, enabling separation of memories per context.

get_database_info_tool

Fetch schema, sample records, and the list of fields for the active database to help you design queries.

search_records_tool

Query records by field values and retrieve matching results, with schema information included.

get_all_records_tool

Dump every record from the active database for quick inspection or export.

add_record_tool

Create a new validated record in the active database.

update_record_tool

Modify an existing validated record while ensuring the schema remains intact.

set_schema_tool

Create or update the JSON Schema for the active database to enforce structure and validation.