Sovereign Universal Memory MCP

User-sovereign, vendor-neutral memory layer for AI tools and agents.

Sovereign Universal Memory MCP is an MCP (Model Context Protocol) server that gives any AI client — Claude, Cursor, custom agents — access to a persistent, cross-tool memory system that you fully own and control.

Why This Exists

AI memory is fragmented and vendor-locked. Every AI tool maintains its own siloed memory. You cannot carry context across tools, export your accumulated knowledge, or control what each tool can access. Sovereign Universal Memory MCP solves this by providing a single memory layer that:

• You own — data lives on your machine, not a vendor's cloud
• Works everywhere — any MCP-compatible client connects instantly
• Runs locally — zero external API dependencies by default
• Stays private — encryption at rest, scoped access, full audit trail
• Exports freely — JSON, JSONL, Markdown — no lock-in

Quick Start

Option 1: npm (recommended)

# Install globally
npm install -g sovereign-universal-memory-mcp

# Run setup (configures hooks for Claude Code, Cursor, etc.)
sovereign-universal-memory-setup

# Verify the server starts
sovereign-universal-memory-mcp

Option 2: From Source

# Clone and install
git clone https://github.com/nnaveenraju/sovereign-universal-memory-mcp.git
cd sovereign-universal-memory-mcp
npm install

# Build and run
npm run build
node dist/index.js

Option 3: Docker

# Production
docker compose -f docker/docker-compose.yml up

# Development (hot-reload)
docker compose -f docker/docker-compose.yml --profile dev up

Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "universal-memory": {
      "command": "node",
      "args": ["/path/to/sovereign-universal-memory-mcp/dist/index.js"]
    }
  }
}

MCP Tools

Tool	Description
memory.store	Store a new memory with category, tags, and confidence
memory.recall	Hybrid semantic + keyword search across all memory
memory.update	Update an existing memory (auto-bumps version)
memory.forget	Soft-delete memories with full audit trail
memory.context	Assemble relevant context for a task (the killer feature)
memory.export	Export memories as JSON, JSONL, or Markdown

Example: A Day with Universal Memory

This walkthrough follows a real scenario — a morning session in Claude Code, an afternoon in Cursor, and a quick Gemini CLI check the next day. Memories build naturally, carry full provenance, link to each other, and flow seamlessly across tools.

---

Morning — Claude Code session, setting up the backend

You: "Remember that this project uses a microservices architecture on AWS EKS,
      the API gateway is Kong, and the primary database is Aurora PostgreSQL 15"

The hook captures this as an explicit store with high confidence:

→ memory.store({
    content: "Project uses a microservices architecture on AWS EKS. API gateway is Kong. Primary database is Aurora PostgreSQL 15.",
    category: "domain",
    tags: ["architecture", "aws", "eks", "kong", "aurora-postgresql"],
    confidence: 0.9,
    source: { tool: "claude-code", context: "UserPrompt:explicit" }
  })

What actually gets stored — the full entry:

{
  "id": "019577a2-8c3f-7d01-b542-3e8f1a9d0c47",
  "version": 1,
  "category": "domain",
  "tags": ["architecture", "aws", "eks", "kong", "aurora-postgresql"],
  "content": "Project uses a microservices architecture on AWS EKS. API gateway is Kong. Primary database is Aurora PostgreSQL 15.",
  "source": {
    "tool": "claude-code",
    "context": "UserPrompt:explicit",
    "conversationId": "session_20260319_091542"
  },
  "confidence": 0.9,
  "createdAt": "2026-03-19T09:15:42Z",
  "updatedAt": "2026-03-19T09:15:42Z",
  "accessedAt": "2026-03-19T09:15:42Z",
  "createdBy": "claude-code",
  "scopes": ["*:read", "domain:write"],
  "pin": false,
  "decayRate": 0.05,
  "accessCount": 0,
  "isDeleted": false
}

Later in the same session, you hit a build error and Claude fixes it. The PostToolUse hook auto-captures the error→fix pattern:

→ memory.store({
    content: "Error: Kong Ingress Controller v3.1 requires annotation 'konghq.com/strip-path' instead of deprecated 'strip.path'. Fix: update all Ingress manifests to use new annotation format.",
    category: "process",
    tags: ["error-fix", "kong", "kubernetes", "ingress", "auto-captured"],
    confidence: 0.8,
    source: { tool: "claude-code", context: "PostToolUse:fix-detection" }
  })

The system detects this relates to the earlier architecture entry and creates a link between them:

{
  "id": "link_019577b1-...",
  "sourceId": "019577a2-8c3f-...",   ← project architecture
  "targetId": "019577b1-4e2a-...",   ← Kong annotation fix
  "relation": "related_to",
  "strength": 0.75
}

You also mention: "I prefer Helm charts over raw manifests for Kubernetes deployments"

The preference detector fires automatically — no explicit "remember" needed:

→ memory.store({
    content: "User preference: I prefer Helm charts over raw manifests for Kubernetes deployments",
    category: "identity",
    tags: ["preference", "kubernetes", "helm", "auto-captured"],
    confidence: 0.6,
    source: { tool: "claude-code", context: "UserPrompt:preference" }
  })

At session end, the Stop hook records a summary:

→ memory.store({
    content: "Claude Code session completed at 2026-03-19T12:30:00Z in project payments-api. Set up Kong ingress, fixed v3.1 annotation migration, configured Helm chart templates for 3 microservices.",
    category: "episodic",
    tags: ["session-summary", "project:payments-api", "tool:claude-code", "auto-captured"],
    confidence: 0.8,
    source: { tool: "claude-code", context: "Stop:session-summary" }
  })

---

Afternoon — switching to Cursor for the dashboard

You open Cursor on the same project. The Universal Memory rule in .cursor/rules/universal-memory.mdc instructs Cursor to call memory.recall at session start:

→ memory.recall({ query: "payments-api project architecture preferences" })

Cursor's context is automatically populated:

## Your Memory — Project Knowledge
• Microservices on AWS EKS, Kong gateway, Aurora PostgreSQL 15
• Kong Ingress Controller v3.1: use 'konghq.com/strip-path' (not deprecated 'strip.path')

## Your Memory — Identity
• Prefers Helm charts over raw K8s manifests

## Your Memory — Recent Activity
• Morning session: set up Kong ingress, fixed annotation migration, configured Helm charts for 3 services

You type in Cursor: "/remember The go-live date is Q3 2026 — deployment freeze starts June 15"

The /remember custom command stores it:

→ memory.store({
    content: "Go-live date is Q3 2026. Deployment freeze starts June 15, 2026.",
    category: "domain",
    tags: ["timeline", "go-live", "deployment-freeze", "user-explicit"],
    confidence: 0.9,
    source: { tool: "cursor", context: "Command:remember" }
  })

---

Next morning — quick check in Gemini CLI

You: "What's the deployment situation for this project?"

Gemini calls the memory MCP server:

→ memory.recall({
    query: "deployment timeline architecture",
    limit: 10
  })

Response — ranked by hybrid search (semantic similarity × keyword × recency):

{
  "results": [
    {
      "entry": {
        "id": "019577c4-...",
        "content": "Go-live date is Q3 2026. Deployment freeze starts June 15, 2026.",
        "category": "domain",
        "tags": ["timeline", "go-live", "deployment-freeze"],
        "source": { "tool": "cursor", "context": "Command:remember" },
        "confidence": 0.9,
        "accessCount": 1
      },
      "score": 0.94,
      "matchType": "hybrid"
    },
    {
      "entry": {
        "id": "019577a2-...",
        "content": "Project uses a microservices architecture on AWS EKS. API gateway is Kong. Primary database is Aurora PostgreSQL 15.",
        "category": "domain",
        "source": { "tool": "claude-code", "context": "UserPrompt:explicit" },
        "confidence": 0.9,
        "accessCount": 3
      },
      "score": 0.87,
      "matchType": "hybrid"
    },
    {
      "entry": {
        "id": "019577b1-...",
        "content": "Error: Kong Ingress Controller v3.1 requires annotation 'konghq.com/strip-path' instead of deprecated 'strip.path'. Fix: update all Ingress manifests to use new annotation format.",
        "category": "process",
        "source": { "tool": "claude-code", "context": "PostToolUse:fix-detection" },
        "confidence": 0.8,
        "accessCount": 2
      },
      "score": 0.71,
      "matchType": "semantic"
    }
  ],
  "totalMatches": 5,
  "searchStrategy": "hybrid:rrf"
}

Gemini responds:

Go-live is Q3 2026, with a deployment freeze starting June 15. The stack is microservices on AWS EKS with Kong as the API gateway and Aurora PostgreSQL 15. One thing to watch — the Kong Ingress Controller v3.1 requires the new konghq.com/strip-path annotation format, which was flagged and fixed in a previous session.

Note: the timeline was stored in Cursor, the architecture in Claude Code, the Kong fix was auto-captured — and Gemini assembled all of it from a single recall.

---

What makes this different

• Cross-tool continuity — memories stored in Claude are recalled in Cursor and answered in Gemini. No copy-paste, no re-explaining.
• Full provenance — every entry records which tool created it, when, and why (explicit command vs. auto-captured from a tool event).
• Memory links — related entries connect to each other. The Kong fix links to the architecture entry, so related context surfaces together.
• Smart decay — episodic memories (session summaries) decay at 0.15/day, domain knowledge (architecture, timelines) at 0.05. Identity preferences never decay.
• Confidence ranking — explicit "remember" commands score 0.9, auto-detected preferences 0.6, tool outcomes 0.5. Higher confidence surfaces first in search.
• You own everything — memory.export({ format: "json" }) gives you a full dump. Local SQLite, no cloud, no vendor lock-in.

Architecture

See ARCHITECTURE.md for the full architecture documentation including the provider abstraction layer, interface specifications, and implementation guide.

Configuration

Create ~/.universal-memory/config.toml:

[server]
transport = "stdio"        # "stdio" for Claude Desktop, "sse" for Docker

[database]
provider = "sqlite"        # Pluggable: "sqlite", "redis", "postgres"...
path = "~/.universal-memory/memory.db"

[vector]
provider = "sqlite-vec"    # Pluggable: "sqlite-vec", "pinecone", "qdrant"...
dimensions = 384

[embeddings]
provider = "local"         # Pluggable: "local", "openai", "cohere"...
model = "Xenova/all-MiniLM-L6-v2"

[search]
provider = "hybrid"
fts_weight = 0.4
vector_weight = 0.6

All settings can also be set via environment variables (see docker/.env.example).

License

MIT — use it however you want.