.png)
1 month ago
6
Persistent, versioned memory system for AI agents via Model Context Protocol (MCP)
BuildAutomata Memory is an MCP server that gives AI agents (like Claude) persistent, searchable memory that survives across conversations. Think of it as giving your AI a long-term memory system with:
- 🧠 Semantic Search - Find memories by meaning, not just keywords
- 📚 Temporal Versioning - Complete history of how memories evolve
- 🏷️ Smart Organization - Categories, tags, importance scoring
- 🔄 Cross-Tool Sync - Share memories between Claude Desktop, Claude Code, Cursor AI
- 💾 Persistent Storage - SQLite + optional Qdrant vector DB
- Python 3.10+
- Claude Desktop (for MCP integration) OR any MCP-compatible client
- Optional: Qdrant for enhanced semantic search
- Clone this repository
git clone https://github.com/brucepro/buildautomata_memory_mcp_dev.git
cd buildautomata_memory_mcp_dev
- Install dependencies
pip install mcp qdrant-client sentence-transformers
- Configure Claude Desktop
Edit your Claude Desktop config (AppData/Roaming/Claude/claude_desktop_config.json on Windows):
{
"mcpServers": {
"buildautomata-memory": {
"command": "python",
"args": ["C:/path/to/buildautomata_memory_mcp_dev/buildautomata_memory_mcp.py"]
}
}
}
- Restart Claude Desktop
That's it! The memory system will auto-create its database on first run.
In addition to the MCP server, this repo includes interactive_memory.py - a CLI for direct memory access:
# Search memories
python interactive_memory.py search "consciousness research" --limit 5
# Store a new memory
python interactive_memory.py store "Important discovery..." --category research --importance 0.9 --tags "ai,insight"
# View memory evolution
python interactive_memory.py timeline --query "project updates" --limit 10
# Get statistics
python interactive_memory.py stats
See README_CLI.md for complete CLI documentation.
Windows:
memory.bat search "query"
memory.bat store "content" --importance 0.8
Linux/Mac:
./memory.sh search "query"
./memory.sh store "content" --importance 0.8
- Hybrid Search: Combines vector similarity (Qdrant) + full-text search (SQLite FTS5)
- Temporal Versioning: Every memory update creates a new version - full audit trail
- Smart Decay: Importance scores decay over time based on access patterns
- Rich Metadata: Categories, tags, importance, custom metadata
- LRU Caching: Fast repeated access with automatic cache management
- Thread-Safe: Concurrent operations with proper locking
When running as an MCP server, provides these tools to Claude:
- store_memory - Create new memory
- update_memory - Modify existing memory (creates new version)
- search_memories - Semantic + full-text search with filters
- get_memory_timeline - View complete version history
- get_memory_stats - System statistics
- prune_old_memories - Cleanup old/low-importance memories
- run_maintenance - Database optimization
┌─────────────────┐
│ Claude Desktop │
│ (MCP Client) │
└────────┬────────┘
│
┌────▼─────────────────────┐
│ MCP Server │
│ buildautomata_memory │
└────┬─────────────────────┘
│
┌────▼──────────┐
│ MemoryStore │
└────┬──────────┘
│
┌────┴────┬─────────────┬──────────────┐
▼ ▼ ▼ ▼
┌───────┐ ┌────────┐ ┌──────────┐ ┌─────────────┐
│SQLite │ │Qdrant │ │Sentence │ │ LRU Cache │
│ FTS5 │ │Vector │ │Transform │ │ (in-memory) │
└───────┘ └────────┘ └──────────┘ └─────────────┘
User: "Remember that I prefer detailed technical explanations"
[Memory stored with category: user_preference]
Next session...
Claude: *Automatically recalls preference and provides detailed response*
Session 1: Work on project A, store progress
Session 2: Claude recalls project state, continues where you left off
Session 3: View timeline of all project decisions
- Store research findings as you discover them
- Tag by topic, importance, source
- Search semantically: "What did I learn about neural networks?"
- View how understanding evolved over time
Claude Desktop → Stores insight via MCP
Claude Code → Retrieves via CLI
Cursor AI → Accesses same memory database
= Unified AI persona across all tools
The Gumroad version includes:
- ✅ Pre-compiled Qdrant server (Windows .exe, no Docker needed)
- ✅ One-click startup script (start_qdrant.bat)
- ✅ Step-by-step setup guide (instructions.txt)
- ✅ Commercial license for business use
- ✅ Priority support via email
Perfect for:
- Non-technical users who want easy setup
- Windows users wanting the full-stack bundle
- Commercial/business users needing licensing clarity
- Anyone who values their time over DIY setup
This open-source version:
- ✅ Free for personal/educational/small business use (<$100k revenue)
- ✅ Full source code access
- ✅ DIY Qdrant setup (you install from qdrant.io)
- ✅ Community support via GitHub issues
Both versions use the exact same core code - you're just choosing between convenience (Gumroad) vs DIY (GitHub).
# User/Agent Identity
BA_USERNAME=buildautomata_ai_v012 # Default user ID
BA_AGENT_NAME=claude_assistant # Default agent ID
# Qdrant (Vector Search)
QDRANT_HOST=localhost # Qdrant server host
QDRANT_PORT=6333 # Qdrant server port
# System Limits
MAX_MEMORIES=10000 # Max memories before pruning
CACHE_MAXSIZE=1000 # LRU cache size
QDRANT_MAX_RETRIES=3 # Retry attempts
MAINTENANCE_INTERVAL_HOURS=24 # Auto-maintenance interval
Memories are stored at:
<script_dir>/memory_repos/<username>_<agent_name>/memoryv012.db
For enhanced semantic search (highly recommended):
docker run -p 6333:6333 qdrant/qdrant
Download from Qdrant Releases
Includes pre-compiled Windows executable + startup script
Without Qdrant: System still works with SQLite FTS5 full-text search (less semantic understanding)
# Search test
python interactive_memory.py search "test" --limit 5
# Store test
python interactive_memory.py store "Test memory" --category test
# Stats
python interactive_memory.py stats
buildautomata_memory_mcp_dev/
├── buildautomata_memory_mcp.py # MCP server
├── interactive_memory.py # CLI interface
├── memory.bat / memory.sh # Helper scripts
├── CLAUDE.md # Architecture docs
├── README_CLI.md # CLI documentation
├── CLAUDE_CODE_INTEGRATION.md # Integration guide
└── README.md # This file
- Normal if running without Qdrant - falls back to SQLite FTS5
- To enable: Start Qdrant server and restart MCP server
- Check memory_repos/ directory permissions
- On Windows: Run as administrator if needed
- Check claude_desktop_config.json path is correct
- Verify Python is in system PATH
- Restart Claude Desktop completely
- Check logs in Claude Desktop → Help → View Logs
pip install --upgrade mcp qdrant-client sentence-transformers
Open Source (This GitHub Version):
- Free for personal, educational, and small business use (<$100k annual revenue)
- Must attribute original author (Jurden Bruce)
- See LICENSE file for full terms
Commercial License:
- Companies with >$100k revenue: $200/user or $20,000/company (whichever is lower)
- Contact: [email protected]
- GitHub Issues: Report bugs or request features
- Discussions: Ask questions, share tips
- Email: [email protected]
- Faster response times
- Setup assistance
- Custom configuration help
- Memory relationship graphs
- Batch import/export
- Web UI for memory management
- Multi-modal memory (images, audio)
- Collaborative memory (multi-user)
- Memory consolidation/summarization
- Smart auto-tagging
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
Author: Jurden Bruce Project: BuildAutomata Year: 2025
Built with:
- MCP - Model Context Protocol
- Qdrant - Vector database
- Sentence Transformers - Embeddings
- SQLite - Persistent storage
- Model Context Protocol Docs
- Qdrant Documentation
- Gumroad Bundle - Easy setup version
Star this repo ⭐ if you find it useful! Consider the Gumroad bundle if you want to support development and get the easy-install version.
