simplemem

SimpleMem

A vibe-coded memory management system with RAG capabilities for Claude via the Model Context Protocol (MCP).

⚠️ Warning: This project is completely vibe-coded. It works, but don't look too closely at the implementation details. The code was written by an AI having a good time, not by someone following best practices.

What is SimpleMem?

SimpleMem is an MCP server that provides persistent memory storage and retrieval for Claude and other MCP clients. It combines traditional file-based storage with modern RAG (Retrieval-Augmented Generation) capabilities, including semantic search and automatic relationship discovery.

Think of it as Claude's personal notebook that never forgets and can find connections between ideas automatically.

Features

• 📝 Persistent Memory Storage: Store and retrieve memories with rich metadata
• 🔍 Semantic Search: Find memories using natural language queries
• 🔗 Automatic Relationship Discovery: Semantic backlinks connect related memories
• 🏷️ Tag System: Organize memories with flexible tagging
• 🎯 Vector Embeddings: Powered by Voyage AI for high-quality semantic understanding
• 📊 DuckDB Backend: Fast, efficient storage with vector similarity search
• 🔧 MCP Protocol: Seamless integration with Claude and other MCP clients

Quick Start

Prerequisites

• Go 1.21+
• A Voyage AI API key (see Configuration section below)

Installation

Option 1: Download Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

• Linux AMD64: simplemem-vX.X.X-linux-amd64.tar.gz

Extract and place the binary in your PATH.

Option 2: Build from Source

# Clone the repository
git clone https://github.com/jcdickinson/simplemem
cd simplemem

# Install dependencies
just deps

# Build the binary
just build

Option 3: Nix

If you have Nix with flakes enabled:

# Run directly from GitHub
nix run github:jcdickinson/simplemem

# Or clone and run locally
git clone https://github.com/jcdickinson/simplemem
cd simplemem
nix run

# Install to profile
nix profile install github:jcdickinson/simplemem

# Run in development shell
nix develop

Configuration

SimpleMem uses TOML-based configuration with flexible options for API keys and settings.

Configuration File

Create a config.toml file (see config.toml.example for reference):

[voyage_ai]
model = "voyage-3.5"
rerank_model = "rerank-lite-1"

api_key = { "path" = "~/.config/simplemem/voyage_api_key.txt" }
# OR
api_key = "api-key-here"

Environment Variables

You can also configure using environment variables:

export SIMPLEMEM_VOYAGE_AI_API_KEY="your-api-key"
export SIMPLEMEM_VOYAGE_AI_MODEL="voyage-3.5"
export SIMPLEMEM_VOYAGE_AI_RERANK_MODEL="rerank-lite-1"

Configuration Options

• Custom config file: Use --config path/to/config.toml
• Database path: Use --db path/to/database.db (can also be set in config)
• API key sources: File path (recommended) or direct value
• Multiple configs: Different configs for different projects

Usage

As an MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "simplemem": {
      "command": "./simplemem",
      "args": [
        "--db",
        "path/to/your/database.db",
        "--config",
        "path/to/config.toml"
      ]
    }
  }
}

Command Line Testing

# Create a memory
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"create_memory","arguments":{"name":"my-memory","metadata":{"title":"My First Memory","description":"A test memory","tags":{"category":"test","priority":"low"}},"content":"# Hello World\n\nThis is my first memory!"}},"id":1}'

# Search memories (primary discovery method)
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_memories","arguments":{"query":"hello world"}},"id":1}'

# Read a specific memory
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read_memory","arguments":{"name":"my-memory"}},"id":1}'

Testing Semantic Backlinks

# Run comprehensive semantic backlinks test
just test-backlinks

# Verify backlinks are working
just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_backlinks","arguments":{"name":"my-memory"}},"id":1}'

Available Tools (MCP)

• create_memory: Create a new memory with metadata object and markdown content
• read_memory: Read a specific memory by name
• update_memory: Update existing memory metadata and content
• delete_memory: Remove a memory and all related data
• search_memories: Semantic search with optional tag filtering (primary discovery method)
• get_backlinks: Get memories related to a specific memory
• change_tag: Modify tags on memories

Note: list_memories has been temporarily removed to encourage efficient semantic search usage instead of token-heavy full listings.

Memory Format

API Structure (for create_memory/update_memory)

{
  "name": "my-memory-name",
  "metadata": {
    "title": "A Human-Readable Title",
    "description": "Brief description of the memory",
    "tags": {
      "category": "personal",
      "priority": "high",
      "status": "active"
    },
    "custom_field": "any_value",
    "version": "1.0"
  },
  "content": "# Memory Content\n\nYour memory content in **Markdown** format.\n\n- Clean markdown without frontmatter\n- Links to [[other-memories]]\n- Whatever you need!"
}

On-Disk Storage

Memories are stored as YAML frontmatter + Markdown:

---
title: A Human-Readable Title
description: Brief description of the memory
tags:
  category: personal
  priority: high
  status: active
custom_field: any_value
version: "1.0"
created: 2025-01-24T12:00:00Z
modified: 2025-01-24T12:00:00Z
---

# Memory Content

Your memory content in **Markdown** format.

- Clean markdown without frontmatter
- Links to [[other-memories]]
- Whatever you need!

Development

Prerequisites

• Just command runner

Common Commands

# Show available commands
just

# Run tests (when they exist)
just test

# Format code
just fmt

# Run with verbose logging
just run-verbose

# Test semantic backlinks functionality
just test-backlinks

# Clean up build artifacts
just clean

Debug Testing

For rapid development iteration:

# Test any JSON-RPC call with custom database
just test-json '<json>' /tmp/test.db

# Quick minimal test
just test-clean /tmp/debug.db

# Build and test in one command
just build-test

Architecture

• Frontend: MCP JSON-RPC 2.0 protocol server
• Storage: File-based memory storage with DuckDB backend
• Search: Voyage AI embeddings + vector similarity
• Relationships: Automatic semantic backlink discovery
• Memory: YAML frontmatter + Markdown content

Known Issues

• No proper test suite (it's vibe-coded, remember?)
• Error handling could be more robust
• Some edge cases might crash things
• Documentation is whatever this README covers
• Database migrations? What are those?

Contributing

This is a vibe-coded project, so contributions should match the energy:

1. Make it work first
2. Make it work well second
3. Make it pretty... maybe later?
4. Tests are aspirational
5. If it breaks, fix it with more vibes

License

LGPL 3.0 - Use it, modify it, vibe with it (but share improvements back to the community).

Credits

• Built with love and caffeine
• Powered by Voyage AI embeddings
• Uses DuckDB for storage
• MCP integration via mark3labs/mcp-go

---

_"It works on my machine, and that machine has good vibes."_ ✨