SimpleMem

1# SimpleMem
2 
3A vibe-coded memory management system with RAG capabilities for Claude via the Model Context Protocol (MCP).
4 
5> ⚠️ **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.
6 
7## What is SimpleMem?
8 
9SimpleMem 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.
10 
11Think of it as Claude's personal notebook that never forgets and can find connections between ideas automatically.
12 
13## Features
14 
15- 📝 **Persistent Memory Storage**: Store and retrieve memories with rich metadata
16- 🔍 **Semantic Search**: Find memories using natural language queries
17- 🔗 **Automatic Relationship Discovery**: Semantic backlinks connect related memories
18- 🏷️ **Tag System**: Organize memories with flexible tagging
19- 🎯 **Vector Embeddings**: Powered by Voyage AI for high-quality semantic understanding
20- 📊 **DuckDB Backend**: Fast, efficient storage with vector similarity search
21- 🔧 **MCP Protocol**: Seamless integration with Claude and other MCP clients
22 
23## Quick Start
24 
25### Prerequisites
26 
27- Go 1.21+
28- A Voyage AI API key (see Configuration section below)
29 
30### Installation
31 
32#### Option 1: Download Pre-built Binaries
33 
34Download the latest release for your platform from [GitHub Releases](https://github.com/jcdickinson/simplemem/releases):
35 
36- **Linux AMD64**: `simplemem-vX.X.X-linux-amd64.tar.gz`
37 
38Extract and place the binary in your PATH.
39 
40#### Option 2: Build from Source
41 
42```bash
43# Clone the repository
44git clone https://github.com/jcdickinson/simplemem
45cd simplemem
46 
47# Install dependencies
48just deps
49 
50# Build the binary
51just build
52```
53 
54#### Option 3: Nix
55 
56If you have Nix with flakes enabled:
57 
58```bash
59# Run directly from GitHub
60nix run github:jcdickinson/simplemem
61 
62# Or clone and run locally
63git clone https://github.com/jcdickinson/simplemem
64cd simplemem
65nix run
66 
67# Install to profile
68nix profile install github:jcdickinson/simplemem
69 
70# Run in development shell
71nix develop
72```
73 
74### Configuration
75 
76SimpleMem uses TOML-based configuration with flexible options for API keys and settings.
77 
78#### Configuration File
79 
80Create a `config.toml` file (see `config.toml.example` for reference):
81 
82```toml
83[voyage_ai]
84model = "voyage-3.5"
85rerank_model = "rerank-lite-1"
86 
87api_key = { "path" = "~/.config/simplemem/voyage_api_key.txt" }
88# OR
89api_key = "api-key-here"
90```
91 
92#### Environment Variables
93 
94You can also configure using environment variables:
95 
96```bash
97export SIMPLEMEM_VOYAGE_AI_API_KEY="your-api-key"
98export SIMPLEMEM_VOYAGE_AI_MODEL="voyage-3.5"
99export SIMPLEMEM_VOYAGE_AI_RERANK_MODEL="rerank-lite-1"
100```
101 
102#### Configuration Options
103 
104- **Custom config file**: Use `--config path/to/config.toml`
105- **Database path**: Use `--db path/to/database.db` (can also be set in config)
106- **API key sources**: File path (recommended) or direct value
107- **Multiple configs**: Different configs for different projects
108 
109### Usage
110 
111#### As an MCP Server
112 
113Add to your MCP client configuration:
114 
115```json
116{
117  "mcpServers": {
118    "simplemem": {
119      "command": "./simplemem",
120      "args": [
121        "--db",
122        "path/to/your/database.db",
123        "--config",
124        "path/to/config.toml"
125      ]
126    }
127  }
128}
129```
130 
131#### Command Line Testing
132 
133```bash
134# Create a memory
135just 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}'
136 
137# Search memories (primary discovery method)
138just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_memories","arguments":{"query":"hello world"}},"id":1}'
139 
140# Read a specific memory
141just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read_memory","arguments":{"name":"my-memory"}},"id":1}'
142```
143 
144#### Testing Semantic Backlinks
145 
146```bash
147# Run comprehensive semantic backlinks test
148just test-backlinks
149 
150# Verify backlinks are working
151just test-json '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_backlinks","arguments":{"name":"my-memory"}},"id":1}'
152```
153 
154## Available Tools (MCP)
155 
156- **`create_memory`**: Create a new memory with metadata object and markdown content
157- **`read_memory`**: Read a specific memory by name
158- **`update_memory`**: Update existing memory metadata and content
159- **`delete_memory`**: Remove a memory and all related data
160- **`search_memories`**: Semantic search with optional tag filtering (primary discovery method)
161- **`get_backlinks`**: Get memories related to a specific memory
162- **`change_tag`**: Modify tags on memories
163 
164> **Note**: `list_memories` has been temporarily removed to encourage efficient semantic search usage instead of token-heavy full listings.
165 
166## Memory Format
167 
168### API Structure (for create_memory/update_memory)
169 
170```json
171{
172  "name": "my-memory-name",
173  "metadata": {
174    "title": "A Human-Readable Title",
175    "description": "Brief description of the memory",
176    "tags": {
177      "category": "personal",
178      "priority": "high",
179      "status": "active"
180    },
181    "custom_field": "any_value",
182    "version": "1.0"
183  },
184  "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!"
185}
186```
187 
188### On-Disk Storage
189 
190Memories are stored as YAML frontmatter + Markdown:
191 
192```markdown
193---
194title: A Human-Readable Title
195description: Brief description of the memory
196tags:
197  category: personal
198  priority: high
199  status: active
200custom_field: any_value
201version: "1.0"
202created: 2025-01-24T12:00:00Z
203modified: 2025-01-24T12:00:00Z
204---
205 
206# Memory Content
207 
208Your memory content in **Markdown** format.
209 
210- Clean markdown without frontmatter
211- Links to [[other-memories]]
212- Whatever you need!
213```
214 
215## Development
216 
217### Prerequisites
218 
219- [Just](https://github.com/casey/just) command runner
220 
221### Common Commands
222 
223```bash
224# Show available commands
225just
226 
227# Run tests (when they exist)
228just test
229 
230# Format code
231just fmt
232 
233# Run with verbose logging
234just run-verbose
235 
236# Test semantic backlinks functionality
237just test-backlinks
238 
239# Clean up build artifacts
240just clean
241```
242 
243### Debug Testing
244 
245For rapid development iteration:
246 
247```bash
248# Test any JSON-RPC call with custom database
249just test-json '<json>' /tmp/test.db
250 
251# Quick minimal test
252just test-clean /tmp/debug.db
253 
254# Build and test in one command
255just build-test
256```
257 
258## Architecture
259 
260- **Frontend**: MCP JSON-RPC 2.0 protocol server
261- **Storage**: File-based memory storage with DuckDB backend
262- **Search**: Voyage AI embeddings + vector similarity
263- **Relationships**: Automatic semantic backlink discovery
264- **Memory**: YAML frontmatter + Markdown content
265 
266## Known Issues
267 
268- No proper test suite (it's vibe-coded, remember?)
269- Error handling could be more robust
270- Some edge cases might crash things
271- Documentation is whatever this README covers
272- Database migrations? What are those?
273 
274## Contributing
275 
276This is a vibe-coded project, so contributions should match the energy:
277 
2781. Make it work first
2792. Make it work well second
2803. Make it pretty... maybe later?
2814. Tests are aspirational
2825. If it breaks, fix it with more vibes
283 
284## License
285 
286LGPL 3.0 - Use it, modify it, vibe with it (but share improvements back to the community).
287 
288## Credits
289 
290- Built with love and caffeine
291- Powered by [Voyage AI](https://voyageai.com) embeddings
292- Uses [DuckDB](https://duckdb.org) for storage
293- MCP integration via [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go)
294 
295---
296 
297_"It works on my machine, and that machine has good vibes."_ ✨
298