Smara: Sovereign Universal Memory MCP

Smara (स्मर) — from the Sanskrit root smṛ, meaning "to remember." In Vedic tradition, smaraṇa is the act of remembrance that preserves knowledge across time. Smara is memory that endures.

A Vendor-Neutral, User-Sovereign Memory Layer for AI Agents and Tools

Your mind. Your tools. Your memory.

Smara 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. Smara 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 smara-mcp

# Run setup (configures hooks for Claude Code, Cursor, etc.)
smara-setup

# Verify the server starts
smara-mcp

Option 2: From Source

# Clone and install
git clone https://github.com/nnaveenraju/smara-mcp.git
cd smara-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": {
    "smara": {
      "command": "node",
      "args": ["/path/to/smara-mcp/dist/index.js"]
    }
  }
}

MCP Tools

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

Example: A Day with Smara

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:

→ smara.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:

→ smara.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:

→ smara.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:

→ smara.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 Smara rule in .cursor/rules/smara-memory.mdc instructs Cursor to call smara.recall at session start:

→ smara.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:

→ smara.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:

→ smara.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 — smara.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 ~/.smara/config.toml:

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

[database]
provider = "sqlite"        # Pluggable: "sqlite", "redis", "postgres"...
path = "~/.smara/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

Dual-licensed under MIT or Apache 2.0, at your option.

Copyright 2026 Naveen Nadimpalli. See NOTICE for attribution details.