memory-mcp
Disclaimer: This codebase was generated with Codex assistance.
Disclaimer: This project was created for personal use; you may use, modify, and distribute it as you like (MIT), but no support is provided.
Local Memory MCP server with:
- SQLite +
sqlite-vecfor embedded storage/search - OpenAI embeddings (configurable model)
- Queue maintenance flow (
take_memory_log+ack_memory_log)
What This Is
memory-mcp is a local-first MCP server for agent memory. It separates:
- Fast capture (
log_memory) - Runtime retrieval (
search_memory) - Maintenance curation (
take_memory_log+ack_memory_log+ CRUD tools)
The intended flow is:
- Agents log candidate memory during normal work.
- A maintenance process takes one log item at a time.
- It converts relevant items into persistent searchable facts.
- It acknowledges the processed log item and continues.
Use With MCP Clients
Codex```toml
[mcp_servers.memory]
startup_timeout_sec = 60
command = "uv"
args = ["run", "memory-mcp"]
[mcp_servers.memory.env]
MEMORY_DB_PATH = "/full/path/to/memory/file"
OPENAI_API_KEY = "your-openai-key"
### Claude Desktop```json
{
"mcpServers": {
"memory": {
"command": "uv",
"args": ["run", "memory-mcp"],
"env": {
"MEMORY_DB_PATH": "/full/path/to/memory/file",
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Environment
Supported env vars:
MEMORY_DB_PATH(default./data/memory.db)OPENAI_API_KEY(required)OPENAI_BASE_URL(optional)MEMORY_EMBEDDING_MODEL(defaulttext-embedding-3-small)MEMORY_MAX_SEARCH_K(default50)
Install
Option A: Fast local install (recommended)```bash
uv venv .venv
source .venv/bin/activate
uv pip install -e .
### Option B: Build and install wheel```bash
uv build
pip install dist/memory_mcp-0.1.1-py3-none-any.whl
Fast Startup (Recommended)
Install once, run many times:```bash
uv venv .venv
source .venv/bin/activate
uv pip install -e .
memory-mcp
Why this is faster:
- Avoids repeated `uv run` environment resolution overhead on each boot.
- Startup time is mostly server init instead of wrapper/setup work.
## Run```bash
export OPENAI_API_KEY=your_key_here
memory-mcp
Optional:```bash
export MEMORY_DB_PATH=./data/memory.db
export OPENAI_BASE_URL=https://api.openai.com/v1
export MEMORY_EMBEDDING_MODEL=text-embedding-3-small
export MEMORY_MAX_SEARCH_K=50
## `uv run` Mode (convenient, usually slower)```bash
OPENAI_API_KEY=... uv run --no-sync memory-mcp
MCP Tools
Primary:
log_memorysearch_memory
Maintenance:
take_memory_logack_memory_logcreate_memoryupdate_memorydelete_memory
Notes
tagsaccepts either["a","b"]or"a,b"on relevant tools.- Queue semantics enforce a single
in_flightlog item at a time. - Embedding model support is currently constrained to configured OpenAI embedding models in code.
License
MIT. See LICENSE.
