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)

Build:
```
docker build -t memory-mcp .
```

Run (persist data on host):

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

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

Option 2: Native Python

Create and activate a virtual env:

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

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

Memory MCP