MEMORY MCP

Memory MCP is a small, self-contained Model Context Protocol (MCP) server for persistent AI agent memory. It uses a local vector database (ChromaDB) + offline/supervised embeddings (SentenceTransformers), enabling low-latency memory operations without external cloud dependencies.

🚀 What it supports

• Long-term semantic memory (add_memory, search_memory, update_memory, remove_memory)
• Short-term scratchpad memory per session (add_to_scratchpad, read_scratchpad, clear_scratchpad)
• Bulk + lifecycle tools (export_memories, import_memories, clear_all_memory, get_memory_stats)
• Local persistence via directory/mounted volume (works with Docker or native Python)

📦 Components

• src/memory_mcp/server.py - MCP tool gateway exposing REST-style calls to clients
• src/memory_mcp/db.py - vector storage logic (Chroma, SQLite gateway)
• mcp_client.py - example client for quickly testing call patterns
• check_db.py/final_check.py - sanity checks for DB state
• tests/ - existing and future test coverage tasks

🛠️ Endpoint methods (MCP tools)

Short-Term Scratchpad

• `add_to_scratchpad(note, session_id)
• `read_scratchpad(session_id)
• clear_scratchpad(session_id)

Long-Term Memory

• add_memory(content, tags, context)
• search_memory(query, session_id, tags, context, limit)
• update_memory(memory_id, content, tags, context)
• remove_memory(memory_id)

Administration

• get_memory_stats()
• export_memories()
• import_memories(markdown_content)
• clear_all_memory(confirmation)

🧩 Install

Option 1: Docker (Recommended)

1. Build:

   docker build -t memory-mcp .
   

2. Run (persist data on host):

   docker run -it --rm -v memory_data:/data -p 8000:8000 memory-mcp
   

3. Configure your MCP client to call the server command as appropriate.

Option 2: Native Python

1. Create and activate a virtual env:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -e .
   

2. Start server directly:

   python -m memory_mcp.server
   

Tip: MEMORY_MCP_STORAGE can override the default data path from ./memory_data.

🧪 Test

Run tests with:

python -m pytest -q

Validate basic memory API quickly:

python mcp_client.py # (if implemented as interactive example)

🗂️ Data layout

• memory_data/ - persistent SQLite/Chroma state for native mode
• memory_data/vector_db/ - vector DB data
• memory_data/chroma.sqlite3 - metadata database

🧰 Usage samples

Add memory

client.add_memory('Your fact', tags=['fact'], context='user')

Search memory

client.search_memory('fact about sky', limit=5)

Export & restore

md = client.export_memories()
client.import_memories(md)

✅ Keeping this README up to date

• Always reflect actual available methods in src/memory_mcp/server.py
• Add new methods in Features + Usage sections
• Ensure install section includes the latest dependency/runtime directives from pyproject.toml