jjtolton/slopnesia

Slopnesia

Minimal MCP memory server with optional embeddings - under 300MB total (vs 900MB+ for PyTorch-based alternatives).

Features

• Interface-based design - swap embedding providers easily
• Auto-fallback - tries ONNX/GPU → ONNX/CPU → OpenAI API → text search
• SQLite storage - single file database at ~/.claude/memories.db
• Minimal dependencies - 28 packages for base, 48 total with ONNX
• Multi-agent safe - CouchDB-style optimistic concurrency control with version vectors
• Single-writer queue - Serialized writes prevent race conditions

Installation

Prerequisites

• Python 3.11 or higher
• uv package manager (install here)

1. Clone the Repository

cd ~/programs  # or wherever you want to install it
git clone https://github.com/jjtolton/slopnesia
cd slopnesia

2. Choose Your Installation

Base Install (Text Search Only)

uv pip install -e .

Size: ~10MB

ONNX Embeddings (Local, GPU-accelerated)

uv pip install -e '.[onnx]'

Size: ~300MB total (ONNX Runtime GPU + model)

OpenAI Embeddings (API-based)

uv pip install -e '.[api]'

Size: ~15MB

Configuration

Set environment variables:

# Embedding mode (auto, onnx, openai, none)
MEMORY_EMBEDDING_MODE=auto

# ONNX settings
MEMORY_ONNX_MODEL=all-MiniLM-L6-v2
MEMORY_ONNX_USE_GPU=true

# OpenAI settings
MEMORY_OPENAI_API_KEY=sk-...
MEMORY_OPENAI_MODEL=text-embedding-3-small

# Database location
MEMORY_DB_PATH=~/.claude/memories.db

MCP Configuration

To enable Claude to use slopnesia for memory storage, add this MCP server to your configuration:

For Claude Code CLI

Use the claude mcp command to install globally:

claude mcp add --scope user simple-memory uv --directory /path/to/slopnesia run python -m src.server

Replace /path/to/slopnesia with your actual installation path (e.g., ~/programs/slopnesia).

Verify the installation:

claude mcp list

Manual Configuration

Alternatively, edit your ~/.claude/mcp.json:

{
  "mcpServers": {
    "simple-memory": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/slopnesia",
        "run",
        "python",
        "-m",
        "src.server"
      ],
      "env": {
        "MEMORY_EMBEDDING_MODE": "auto",
        "MEMORY_ONNX_USE_GPU": "true"
      }
    }
  }
}

After adding the configuration, restart Claude Code.

MCP Tools

The server exposes these tools to Claude:

• store_memory(content, tags?, context?) - Store a new memory (returns version & hash)
• search_memory(query, limit?, threshold?) - Search using text or semantic similarity
• list_recent(limit?) - Get recent memories
• get_memory(id) - Get specific memory by ID with version info
• update_memory(id, content, expected_version, expected_hash?, tags?, context?) - Update with conflict detection
• delete_memory(id) - Delete a memory
• get_stats() - Get database statistics
• restart_server() - Gracefully restart the MCP server

Architecture

┌─────────────────────────────────┐
│   EmbeddingProvider Interface   │
└────────────┬────────────────────┘
             │
     ┌───────┴───────┬────────────┬──────────┐
     │               │            │          │
┌────▼────┐   ┌─────▼─────┐  ┌──▼────┐  ┌──▼─────┐
│ NoOp    │   │ ONNX      │  │OpenAI │  │ Future │
│(text)   │   │(local GPU)│  │(API)  │  │providers│
└─────────┘   └───────────┘  └───────┘  └────────┘

Current Status

✓ Installed and connected to Claude Code

Embedding Provider: Auto-detecting (ONNX with GPU fallback) Database: ~/.claude/memories.db Total Size: ~300MB (ONNX) vs 900MB+ (PyTorch alternatives)

Comparison

Multi-Agent Concurrency

Slopnesia supports safe concurrent access from multiple agents. See for details on:

• Version vectors and content hashing
• Optimistic locking with conflict detection
• Single-writer queue architecture
• Conflict resolution workflows

Test the implementation:

uv run python test_concurrency.py

Development

See implementation files:

• src/embeddings.py - Embedding interface and implementations
• src/database.py - SQLite storage with FTS5 + version control
• src/config.py - Configuration and auto-detection
• src/server.py - MCP server implementation
• test_concurrency.py - Test suite for concurrency control