initialize_memoryLABSCO SUMMARY
Memory that maintains itself.
The hard part of agent memory is not writing facts down, it is what happens on the hundredth conflicting one. Here deduplication and contradiction resolution happen inside the same LLM call that does extraction, and a scheduled fsck sweeps for the duplicates, contradictions and injected content that got through anyway. Everything runs on your infrastructure, which is the other half of the pitch.
What it is
An MCP memory server you run yourself. Storing a message is a single LLM call that extracts individual facts, classifies each one, and checks them against what is already stored for duplicates and contradictions. Retrieval runs several generated queries in parallel and reranks, with enough temporal awareness to answer "what did I decide last week".
What you get
- Facts extracted, classified and deduplicated on the way in, with contradictions resolved as updates rather than added as new memories —
add_memory,add_memories - Three levels of search: filtered semantic search, an AI search that generates multiple queries and reranks them, and a question that returns a written answer synthesised from the matches —
search_memories,find_memories,ask_memories - A session-start payload of pinned core memories plus recent context, in one call —
get_core_memories,initialize_memory,get_recent_memories - Two-tier storage: searchable summaries in the vector store, with full artifacts — reports, code, research — fetched only when needed, including a signed download URL for large ones —
save_artifact,get_artifact,get_artifact_url,list_artifacts - Full editing of what is remembered, not just adding —
update_memory,delete_memory,delete_all_memories,list_memories,list_categories - A three-phase consistency checker (fsck) that finds duplicates, contradictions, quality problems and prompt injection, runnable on a schedule with auto-fix
- Configurable TTL so context expires and frequently accessed memories are reinforced rather than the store growing without bound
- A built-in management UI with a dashboard, semantic search, full CRUD over memories, a relationship graph and the health-check interface
- A
/metricsendpoint in Prometheus format with operation counters and memory gauges, and a Grafana dashboard to go with it
Requirements
An OpenAI-compatible API key for the LLM and embeddings — OPENAI_API_KEY is picked up from the environment automatically, and LLM_API_KEY overrides it. uvx mnemory starts it on http://localhost:8050/mcp with data under ~/.mnemory/; clients connect over streamable-http. A production setup adds Qdrant for vectors and S3 or MinIO for artifacts, with API key or Cognis JWT authentication (MNEMORY_JWT_PUBLIC_KEY or MNEMORY_JWKS_URL) and REDIS_URL for session persistence across instances. Licensed Apache 2.0.
Setup effort
One command plus a key — uvx mnemory, then supply credentials
USE CASES
Keeping preferences and decisions across separate chats
Connect it and let extraction run on what you say; at the next session start, pinned core memories and recent context arrive in one call.
Asking a question of your own history
Use the AI search when you want the matching memories and the synthesised answer when you want prose — the second costs more calls, and the docs say so.
Keeping big documents out of the context window
Store a short searchable summary as the memory and attach the full report or code as an artifact, fetched or downloaded only when it is actually needed.
Cleaning up a store that has drifted
Run the consistency checker to surface duplicates, contradictions and quality problems, then fix them from the management UI or let auto-fix handle it.
Running it for a team
Back it with Qdrant and S3, put API key or JWT auth in front with per-user isolation, and watch the Prometheus metrics on the Grafana dashboard.
18 tools
Listed in project docs. Your client may show a different list.
add_memoryadd_memoriessearch_memoriesfind_memoriesask_memoriesget_core_memoriesget_recent_memorieslist_memoriesupdate_memorydelete_memorydelete_all_memorieslist_categoriessave_artifactget_artifactget_artifact_urllist_artifactsdelete_artifactBEFORE YOU INSTALL
What to know first
Tools you get
18 tools named in the project's documentation. Parts of the documentation say 16 or 17; the tool tables list 18.
Requires
- uvx on PATH
- OPENAI_API_KEY in your environment
INSTALLATION
Connect your client
Server setup
uvx mnemoryMCP Clients
Open WebUI
Admin Settings > External Tools > Add Server; type MCP (Streamable HTTP); URL http://mnemory:8050/mcp; header X-Agent-Id: open-webui
ChatGPT
ChatGPT cannot reach a server on your own machine: mnemory has to be deployed at a public HTTPS address, with an API key set in MCP_API_KEYS. Then Settings > Apps & Connectors > Advanced > Developer Mode > Create Connector; MCP Server URL <YOUR_MEM_URL>/mcp, where <YOUR_MEM_URL> is your server's address; Authentication: Bearer token with your API key. Needs ChatGPT Plus, Pro, Business, Enterprise or Edu.
Cursor
{
"mcpServers": {
"mnemory": {
"type": "streamable-http",
"url": "http://localhost:8050/mcp",
"headers": {
"Authorization": "Bearer <YOUR_MNEMORY_API_KEY>",
"X-Agent-Id": "cursor"
}
}
}
}Cline
{
"mcpServers": {
"mnemory": {
"type": "streamableHttp",
"url": "http://localhost:8050/mcp",
"headers": {
"Authorization": "Bearer <YOUR_MNEMORY_API_KEY>",
"X-Agent-Id": "cline"
}
}
}
}Continue
{
"mcpServers": [
{
"name": "mnemory",
"transport": {
"type": "streamable-http",
"url": "http://localhost:8050/mcp",
"headers": {
"Authorization": "Bearer <YOUR_MNEMORY_API_KEY>",
"X-Agent-Id": "continue"
}
}
}
]
}Hermes Agent
Install the mnemory plugin:
pip install hermes-mnemoryPoint it at your running mnemory server by adding these two lines to ~/.hermes/.env:
MNEMORY_URL=http://localhost:8050
MNEMORY_API_KEY=<YOUR_MNEMORY_API_KEY>OpenClaw
Install the mnemory plugin:
openclaw plugins install @fpytloun/openclaw-mnemoryAdd it to your openclaw.json as the memory plugin, pointed at your running mnemory server:
{
"plugins": {
"slots": {
"memory": "mnemory"
},
"entries": {
"mnemory": {
"enabled": true,
"config": {
"url": "http://localhost:8050",
"apiKey": "${MNEMORY_API_KEY}"
}
}
}
}
}Self-host — Docker Compose
Get the code — the compose file builds the image from it: git clone https://github.com/fpytloun/mnemory.git, then cd mnemory
Set your OpenAI-compatible key and start it; mnemory then serves http://localhost:8050/mcp. The commands:
export OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
docker-compose up -dSelf-host — pip
pip install mnemory && mnemory