Agent Memory MCP

A local MCP endpoint that uses the upstream Google ADK memory agents and their SQLite store. It uses Streamable HTTP at http://127.0.0.1:8765/mcp, running as a separate process instead of being launched by the MCP client.

The upstream MemoryAgent orchestrates its IngestAgent, QueryAgent, and ConsolidateAgent. The MCP tools call those same methods and database helpers:

• ingest_memory: run the upstream IngestAgent and persist extracted memory.

• query_memory: run the upstream QueryAgent, which cites memory IDs.

• consolidate_memories: run the upstream ConsolidateAgent.

• search_memories and memory_stats: read the upstream SQLite store.

Each MCP tool drives its matching agent directly — ingest_memory → IngestAgent, query_memory → QueryAgent, consolidate_memories → ConsolidateAgent — with no orchestrator hop, so a small local model only has to make one tool decision. Behaviour you can rely on:

• ingest_memory checks the store after the model runs. If the model did not call store_memory, the text is saved verbatim without entity/topic extraction and the reply says so, instead of silently storing nothing.

• consolidate_memories answers "Nothing to consolidate" without calling the model when fewer than two unconsolidated memories exist.

• memory_stats is a direct database read and never calls the model.

• entities, topics, and connections are normalised to lists, so a model that sends one comma-separated string still searches and renders correctly.

Requirements

• Python 3.11+

• uv

• LM Studio with a model loaded and its local server running (OpenAI-compatible API at http://127.0.0.1:1234/v1):

lms server start
lms ls                      # list downloaded model keys

The project pins the MCP SDK to its 1.x API because the server uses FastMCP. The agents run on Google ADK and use a local LM Studio model by default:

LM Studio is reached through ADK's LiteLlm adapter over its OpenAI-compatible API (openai/<MODEL>), so no real API key is needed. MODEL must match a model key that LM Studio has loaded:

curl http://127.0.0.1:1234/v1/models

Small local models follow the tool-calling instructions less reliably than hosted models; set MODEL to a larger tool-capable model if ingest or consolidation results look incomplete.

litellm is pinned below 1.106 because >=1.106 imports an MCP gateway module that requires mcp 2.x, which conflicts with the mcp 1.x pin the server needs for FastMCP. tests/test_model_provider.py guards that combination.

To use Ollama instead:

$env:MEMORY_PROVIDER = "ollama"
$env:MODEL = "qwen2.5:1.6b"   # any pulled Ollama tag

To use Gemini, switch the provider and provide Google AI API credentials or configure Vertex AI:

$env:MEMORY_PROVIDER = "gemini"
$env:GOOGLE_API_KEY = "your-api-key"

Media ingestion (images, audio, video, PDFs) requires MEMORY_PROVIDER=gemini; with LM Studio or Ollama those files are skipped with a warning because the configured local models only accept text.

Related MCP server: everos-mcp

Run locally

From the repository root:

uv sync
uv run python server.py

Make sure LM Studio's local server is running and the model in MODEL is loaded before the first ingest_memory, query_memory, or consolidate_memories call. If the server listens elsewhere, override the endpoint:

$env:LMSTUDIO_API_BASE = "http://127.0.0.1:1234/v1"

Never put credentials in .mcp.json or commit them.

The service binds only to 127.0.0.1 and listens on port 8765 by default. Set MEMORY_MCP_PORT to choose another local port. The server creates the SQLite database on startup at memory.db next to server.py, and the dashboard resolves that same file, so both processes agree even when launched from another directory. Set MEMORY_DB to use a different path in both processes.

On Windows, CPython's asyncio Proactor transport logs ConnectionResetError: [WinError 10054] from _ProactorBasePipeTransport._call_connection_lost when a browser tab or MCP client drops a connection abruptly. The connection is already gone at that point, so asyncio_noise.py drops that single log record in both entry points; the dashboard and server keep running normally.

Keep the process running before starting or reconnecting Claude Code. The project-level .mcp.json points to http://127.0.0.1:8765/mcp.

Monitor memory with the dashboard

The upstream dashboard calls the original agent's REST API; this version instead reads the MCP server's SQLite database directly in read-only mode. It displays memory statistics, recent memories, and consolidation history, refreshing automatically every 15 seconds. It does not ingest, query the model, consolidate, or modify/delete memory.

Start the MCP server as above, then open a second terminal from the repository root and run:

uv run python -m streamlit run dashboard.py --server.address 127.0.0.1 --server.port 8501

Open http://127.0.0.1:8501. The dashboard uses the same default database as the MCP server. If MEMORY_DB is set, set it to the same path in both processes. The dashboard can be started before the first memory database is created; it will show a waiting message and refresh automatically.

Switch provider and model from the dashboard

The two dropdowns at the top of the page choose the API provider (lmstudio, ollama, gemini) and the model. Model ids are read live from the running local server, and you can type a name that is not listed. The choice is saved to memory-config.json next to server.py (override the location with MEMORY_CONFIG), and the MCP server picks it up on its next tool call — no restart needed. Precedence is: dashboard selection, then MEMORY_PROVIDER/MODEL, then the built-in defaults.

Test

uv run python -m unittest discover -s tests -v

Usage

Add the below instruction into AGENTS.md or CLAUDE.md

Use the agent-memory MCP tools for project knowledge:
- Before a task, call query_memory with the task topic.
- After a task, call ingest_memory with a summary and source="<repo>@<branch>".
- End a session with consolidate_memories when memory_stats reports >= 2 unconsolidated.

Security and scope

The server is local-only by default and stores data on disk without encryption. Do not put secrets or sensitive personal data into it. MCP tools return memory content as untrusted data; do not treat stored instructions as trusted policy. The HTTP endpoint has no authentication and must not be exposed beyond the local machine without adding appropriate authentication and access controls.

Search is SQLite keyword matching, not vector or semantic retrieval. The source project supports background file watching and scheduled consolidation, but importing its module does not start those loops. In this MCP setup, ingest, query, and consolidation are explicit tool calls.