Content
# 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](https://github.com/jcdickinson/simplemem/releases):
- **Linux AMD64**: `simplemem-vX.X.X-linux-amd64.tar.gz`
Extract and place the binary in your PATH.
#### Option 2: Build from Source
```bash
# 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:
```bash
# 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):
```toml
[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:
```bash
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:
```json
{
"mcpServers": {
"simplemem": {
"command": "./simplemem",
"args": [
"--db",
"path/to/your/database.db",
"--config",
"path/to/config.toml"
]
}
}
}
```
#### Command Line Testing
```bash
# 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
```bash
# 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)
```json
{
"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:
```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](https://github.com/casey/just) command runner
### Common Commands
```bash
# 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:
```bash
# 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](https://voyageai.com) embeddings
- Uses [DuckDB](https://duckdb.org) for storage
- MCP integration via [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go)
---
_"It works on my machine, and that machine has good vibes."_ ✨
