Universal Memory Service

Self-hosted service providing unified memory search and write operations across file-based memory, vector embeddings, and the Graphiti temporal knowledge graph. Platform-agnostic — works with any client via HTTP API or MCP stdio transport.

Features

• Unified search — One query searches vector embeddings (Gemini), BM25 full-text, and Graphiti temporal facts, merged and reranked

• Unified write — One call persists to markdown files and Graphiti simultaneously

• 6-stage retrieval pipeline — Query expansion → vector → BM25 → Graphiti → merge & rank → cross-encoder rerank

• Local models — Reranker and query expander run locally via GGUF (no API dependency for search)

• Platform sync — Canonical files auto-sync to OpenClaw, Hermes, and other platforms

• MCP server — Stdio transport for Claude Desktop, Cursor, and any MCP client

• Graceful degradation — Every component fails independently; the service never fully breaks

Related MCP server: Agent Memory

Architecture

┌───────────┐  ┌───────────┐  ┌───────────────┐  ┌───────────┐
│  OpenClaw │  │  Hermes   │  │Claude Desktop │  │  Any MCP  │
│  (skill)  │  │  (skill)  │  │  (MCP client) │  │  Client   │
└─────┬─────┘  └─────┬─────┘  └──────┬────────┘  └─────┬─────┘
      │              │               │                  │
      └──────────────┴───── HTTP ────┴──── MCP stdio ───┘
                             │
                ┌────────────▼────────────┐
                │  Universal Memory Svc   │
                │  FastAPI :8002 + MCP    │
                ├─────────────────────────┤
                │  Retrieval Pipeline     │
                │  File Writer + Sync     │
                │  Indexer + Watcher      │
                │  Local GGUF Models      │
                └──────┬──────────┬───────┘
                       │          │
                ┌──────▼──┐  ┌───▼────────┐
                │ SQLite  │  │ Graphiti   │
                │ vec+FTS │  │ API :8001  │
                └─────────┘  └────────────┘

Quick Start

Prerequisites

• Python 3.11+

• Graphiti API running on port 8001 (optional)

• Gemini API key for embeddings (optional — falls back to OpenAI, then BM25-only)

Install

git clone <repo-url> && cd universal-memory-service
pip install -e ".[dev]"

Configure

cp config/config.example.yaml ~/.memory-service/config.yaml
# Edit to set your data_dir, API keys, agent mappings

# Required for vector embeddings:
export GEMINI_API_KEY=your-key-here
# Without this key, the service falls back to BM25-only search (no vector embeddings).

Run

# HTTP server
python -m universal_memory.main

# MCP server (for Claude Desktop / Cursor)
python -m universal_memory.mcp_server

API

Base URL: http://localhost:8002/api/v1

Search

curl -s localhost:8002/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "deployment process", "author": "alice"}' | jq

Write

curl -s localhost:8002/api/v1/write \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployed v2.3 to staging", "author": "bob"}'

MCP Server

The MCP server exposes 6 tools over stdio transport:

Claude Desktop config

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-m", "universal_memory.mcp_server"],
      "env": { "MEMORY_AUTHOR": "alice" }
    }
  }
}

Retrieval Pipeline

Every search runs through a 6-stage pipeline:

1. Query Expansion — Local LLM rewrites the query into 2-3 semantic variants

2. Vector Search — Embed all variants via Gemini, cosine similarity against SQLite-vec

3. BM25 Search — Full-text search via SQLite FTS5

4. Graphiti Search — Temporal fact retrieval from the knowledge graph

5. Merge & Rank — Normalize scores, weighted merge (vector 0.40, BM25 0.20, Graphiti 0.25), temporal decay, MMR dedup

6. Rerank — Local cross-encoder re-scores top-N candidates for precision

File Namespaces

~/.memory-service/data/
├── shared/              # Cross-agent knowledge (MEMORY.md, USER.md)
├── agents/{name}/logs/  # Per-agent daily logs
├── departments/{dept}/  # Department-level knowledge
├── projects/            # Cross-cutting project docs
├── guides/              # How-to docs
└── system/              # Internal state

Agents write using author and target fields — the service resolves file paths automatically.

Configuration

See config/config.example.yaml for all options:

• Service — Host, port, auth token

• Memory — Data directory, file extensions

• Agents — Name-to-department mapping

• Index — Chunk size (400 tokens), overlap (80 tokens), DB path

• Embedding — Provider (Gemini/OpenAI), model, batch size

• Models — Reranker and query expander GGUF paths

• Search — Weights, temporal decay, MMR lambda

• Graphiti — URL, timeout

• Sync — Platform sync targets

Local Models

Both are optional — the service degrades gracefully without them.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Lint
ruff check src/ tests/

License

MIT