Tinydb: Local Memory Storage for Chatbots, JSON Support

Tinydb Emcipi

An MCP server based on TinyDB that provides localized long-term memory storage for chatbots, supporting the storage, search, and validation of JSON records

Database Knowledge management and memory #Local Storage #JSON Database #Memory Management #MCP Tools .Python

rating : 2 points

downloads : 5.2K

update time : 2025-10-16

Open Site

What is TinyDB-Emcipi?

TinyDB-Emcipi is a Model Context Protocol (MCP) server that uses TinyDB as the backend storage to provide long-term memory capabilities for AI assistants and chatbots. Through simple tool calls, AI can store, search, and update records in JSON format, loading relevant data only when needed.

How to use TinyDB-Emcipi?

You can use it in two ways: install Python dependencies locally and run, or use Docker for one-click deployment. After the server starts, the AI assistant can call various database operation tools through the MCP protocol.

Applicable Scenarios

Suitable for AI application scenarios that require persistent storage of structured data, such as user preference memory, conversation history records, knowledge base management, and configuration storage for small projects. It is particularly suitable for personal use and small projects.

Main Features

Docker-Friendly Deployment

Provides complete Docker support. You can start the service with just one command without configuring complex environment dependencies.

Schema Data Validation

All stored records will be validated according to the predefined JSON Schema to ensure data consistency and integrity.

Complete CRUD Operations

Provides complete database operation tools such as create, read, update, and delete to meet various data management needs.

Multi-Database Support

Supports creating and managing multiple databases. You can switch between different data storages according to different uses.

Flexible Search Function

Supports query search based on field values to quickly locate the required records and improve data retrieval efficiency.

Advantages

Zero external dependencies - Implemented in pure Python, easy to deploy

Lightweight design - Low resource consumption, fast startup

Local storage - Data is completely stored locally, ensuring privacy and security

Schema-first - Standardized data structure, easy to maintain

Docker support - Containerized deployment, consistent environment

Limitations

Single-machine deployment - Does not support distributed clusters

Performance limitations - Suitable for small to medium-scale data volumes

Relatively basic functions - Lacks advanced database features

Limited concurrent processing - Not suitable for high-concurrency scenarios

How to Use

Environment Preparation

Ensure that your system has Python 3.8+ or Docker environment installed.

Choose a Deployment Method

Choose local operation or Docker deployment according to your needs.

Local Operation (Optional)

If you choose to run locally, install the dependencies and start the service.

Docker Operation (Optional)

If you choose Docker deployment, use docker compose to start the service.

Connect the AI Assistant

Configure your AI assistant to connect to the MCP server endpoint: http://localhost:8000/mcp.

Usage Examples

User Preference Memory

The AI assistant can remember the user's personal preference settings, such as language preferences, theme settings, and commonly used commands.

Conversation History Management

Store important conversation histories to help the AI maintain context coherence in subsequent conversations.

Knowledge Base Construction

Gradually build a personal or project knowledge base to store important information and reference materials.

Frequently Asked Questions

Is TinyDB-Emcipi suitable for storing large amounts of data?

Where is the data stored? Is it secure?

Is an internet connection required?

How do I back up my data?

Which types of AI assistants are supported?

Related Resources

MCP Protocol Documentation

Understand the official documentation and specifications of the Model Context Protocol.

TinyDB Documentation

Complete usage documentation and API reference for the TinyDB database.

GitHub Repository

The project's source code and latest updates.

Docker Documentation

Official documentation and usage guide for Docker container technology.

🚀 tinydb-emcipi

A Tiny MCP server backed by TinyDB, offering long - term memory for chatbots and small - context LLM apps without leaving your laptop.

This repo is docker - friendly – an MCP wrapper around TinyDB that gives chatbots long - term memory without leaving your laptop.

🚀 Quick Start

Native

pip install -r requirements.txt
python -m main           # MCP endpoint on http://localhost:8000/mcp

Docker Compose

docker compose up        # builds dependencies at first run

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

✨ Features

Keeping structured facts in the prompt is wasteful. With tinydb - emcipi an agent can store, search and mutate JSON records through MCP tool calls, loading only what it needs.

Zero dependencies – TinyDB stores JSON on disk.
Schema - first – every record validated; the schema itself is queryable.
Opinionated tools – list DBs, switch DB, introspect schema, CRUD, search.
Docker - friendly – run locally or in CI with a single docker compose up.

📚 Documentation

Available MCP Tools (summary)

Category	Tool	Purpose
Discovery	`create_database_tool`	create new DB (optionally with initial schema)
	`list_databases_tool`	see all TinyDB files
	`switch_active_db_tool`	set the DB every other tool will use
	`get_database_info_tool`	schema, sample records, field list
Records	`search_records_tool`	field - value query, returns schema too
	`get_all_records_tool`	dump every record
	`add_record_tool` / `update_record_tool`	create / modify validated records
Schema	`set_schema_tool`	create / update JSON Schema for a DB

Project Structure (top - level)

config/        configuration & sample
logs/          runtime logs
sandbox/db/    TinyDB JSON databases
utils/         code modules (db, schema, mcp wrappers)
main.py        entry - point
docker - compose.yml
requirements.txt

Example MCP Prompt

A ready - to - use JSON request lives at showing how to invoke these tools from an MCP client.

🔧 Contributing

Pull requests are welcome! Please:

Follow PEP 8 and keep imports sorted.
Add or update unit tests.
Keep the README and doc - strings concise and useful.

📄 License

list_databases_tool

When the user asks questions like 'What data do we have?', 'Show the databases', 'Do you have any assets?' or similar, call this tool to list all available TinyDB databases. Use this tool first to discover existing databases before making any specific queries.

get_database_info_tool

Call this tool when the user says 'Describe the database', 'Tell me the current database information', 'What fields are there inside?' etc. Returns the schema, sample records, and available fields of the active database.

get_all_records_tool

When the user requests 'Show all contents', 'Give me all records', 'Dump the database', call this tool to return the complete contents of the current active database. If no active database is selected, use switch_active_db to set it first.

search_records_tool

Call this tool when the user says 'Search', 'Find', 'Filter' or provides conditions like Status=Licensed. Pass a JSON object containing field-value pairs, e.g., {'Status':'Licensed'}. Use the active database.

Parameters

query : dict*

Description

JSON object containing search conditions

set_schema_tool

Call this tool when the user wants to define or change the allowed fields/types of the active database (e.g., 'Add the serial_number field'). Always request confirmation before running, as it can overwrite validation rules.

Parameters

field_schema : dict*

Description

Dictionary containing field schema definition

add_record_tool

Call this tool immediately when the user requests to add/create/insert an asset or record to the active database. Provide fields that match the schema; then report success so that the user can make adjustments if needed.

Parameters

record : dict*

Description

Record data to be added

update_record_tool

Use this tool with the record_id and updated fields when the user asks to modify or correct an existing record in the active database. First, use get_all_records_tool to locate the ID, then perform the update.

Parameters

record_id : int*

Description

ID of the record to be updated

Parameters

record : dict*

Description

Dictionary containing updated fields

switch_active_db_tool

Call this tool first to select the TinyDB database that subsequent tools should operate on. Pass the database name (without .json). After a successful switch, you can use tools like get_all_records_tool, search_records_tool, etc.

Parameters

db_name : str*

Description

Database name (without .json extension)

create_database_tool

Proactively call this tool when the user needs a brand - new TinyDB database or when no potentially relevant database already exists. Provide the database name (without .json). Optionally, provide an initial JSON schema in the same call; if provided, it will be saved atomically. If not provided, the next logical prompt should be to define and set the schema. After that, the database can use the add_record_tool.

Parameters

db_name : str*

Description

Database name (without .json extension)

Parameters

field_schema : dict | None*

Description

Optional initial field schema definition