# Sovereign Universal Memory MCP

[![License](https://img.shields.io/badge/License-MIT%20OR%20Apache--2.0-blue.svg)](./LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)

**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)

```bash
# 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

```bash
# 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

```bash
# 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`:

```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:

```json
→ 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:**

```json
{
  "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:

```json
→ 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:

```json
{
  "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:

```json
→ 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:

```json
→ 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:

```json
→ 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:

```json
→ 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:

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

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

```json
{
  "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](./ARCHITECTURE.md) for the full architecture documentation including the provider abstraction layer, interface specifications, and implementation guide.

## Configuration

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

```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.