{"_id":"@aeriondyseti/mcp-memory","_rev":"2-d08788f04eed02c989101de212cb481c","name":"@aeriondyseti/mcp-memory","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@aeriondyseti/mcp-memory","version":"0.1.0","keywords":["mcp","memory","rag","embeddings","sqlite"],"author":"AerionDyseti","license":"MIT","_id":"@aeriondyseti/mcp-memory@0.1.0","maintainers":[{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"}],"homepage":"https://github.com/AerionDyseti/mcp-memory-server#readme","bugs":{"url":"https://github.com/AerionDyseti/mcp-memory-server/issues"},"bin":{"mcp-memory":"src/index.ts"},"dist":{"shasum":"43073696b8501a7ed7161ca95770fd6995e2719b","tarball":"https://registry.npmjs.org/@aeriondyseti/mcp-memory/-/mcp-memory-0.1.0.tgz","fileCount":14,"integrity":"sha512-osQMhf8xIw4fXL+Q4IoSfSIYDeVvytP7DPaQWoVeN4MaxBYLHCrlcumhnDp6O0xzzoMh3h1JFhURV83QpGotkQ==","signatures":[{"sig":"MEQCIC0kIbkcQpZyfe9Ub1QXuXHzoKKAofcXDKK5esoXnPK1AiBt8Po3nKBu1TlgEMsFHqyP37ATh1C/mSSYRu4KukdOtg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29550},"main":"src/index.ts","type":"module","shasum":"43073696b8501a7ed7161ca95770fd6995e2719b","scripts":{"dev":"bun --watch run src/index.ts","test":"bun test","start":"bun run src/index.ts","typecheck":"tsc --noEmit","test:coverage":"bun test --coverage"},"_npmUser":{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"},"_integrity":"sha512-osQMhf8xIw4fXL+Q4IoSfSIYDeVvytP7DPaQWoVeN4MaxBYLHCrlcumhnDp6O0xzzoMh3h1JFhURV83QpGotkQ==","repository":{"url":"git+https://github.com/AerionDyseti/mcp-memory-server.git","type":"git"},"_npmVersion":"10.8.3","description":"A zero-configuration RAG memory server for MCP clients","directories":{},"_nodeVersion":"24.3.0","dependencies":{"sqlite-vec":"^0.1.0","drizzle-orm":"^0.44.7","@xenova/transformers":"^2.17.0","@modelcontextprotocol/sdk":"^1.0.0","@aeriondyseti/drizzle-sqlite-vec":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0","drizzle-kit":"^0.31.7"},"_npmOperationalInternal":{"tmp":"tmp/mcp-memory_0.1.0_1764280298315_0.10290565592601442","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aeriondyseti/mcp-memory","version":"0.2.0","description":"A zero-configuration RAG memory server for MCP clients","type":"module","main":"src/index.ts","bin":{"mcp-memory":"src/index.ts"},"repository":{"type":"git","url":"git+https://github.com/AerionDyseti/mcp-memory-server.git"},"author":{"name":"AerionDyseti"},"bugs":{"url":"https://github.com/AerionDyseti/mcp-memory-server/issues"},"homepage":"https://github.com/AerionDyseti/mcp-memory-server#readme","scripts":{"start":"bun run src/index.ts","dev":"bun --watch run src/index.ts","typecheck":"tsc --noEmit","test":"bun test","test:coverage":"bun test --coverage"},"keywords":["mcp","memory","rag","embeddings","sqlite"],"license":"MIT","dependencies":{"@lancedb/lancedb":"^0.22.3","@modelcontextprotocol/sdk":"^1.0.0","@xenova/transformers":"^2.17.0","apache-arrow":"^21.1.0"},"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"gitHead":"bfbe86b49763f07edbaad5f33fce6592d52ed0d2","_id":"@aeriondyseti/mcp-memory@0.2.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-X4XmN++XJSZM7eOsnE+HUXvzXTc5cjwQEhJLr/+nWieBTyjN70KES9WOjSTTGIKsRhG90PXAcdVwmkSR4qkUyg==","shasum":"2ca20beb6cb340ff7b3ee5f3baac6988d53f53f9","tarball":"https://registry.npmjs.org/@aeriondyseti/mcp-memory/-/mcp-memory-0.2.0.tgz","fileCount":14,"unpackedSize":28737,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCNFoY3Zu6bVoy/oyhjQsupbMPSjA+UkjGV5ec2FUkVHgIhAIManDkqTAr5hZlfAAK6UHyYbWxbL0DDAGQpmwiEZNF6"}]},"_npmUser":{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"},"directories":{},"maintainers":[{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-memory_0.2.0_1764309073748_0.6483100886742517"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-27T21:51:38.219Z","modified":"2025-11-28T05:51:14.168Z","0.1.0":"2025-11-27T21:51:38.505Z","0.2.0":"2025-11-28T05:51:13.961Z"},"bugs":{"url":"https://github.com/AerionDyseti/mcp-memory-server/issues"},"author":{"name":"AerionDyseti"},"license":"MIT","homepage":"https://github.com/AerionDyseti/mcp-memory-server#readme","keywords":["mcp","memory","rag","embeddings","sqlite"],"repository":{"type":"git","url":"git+https://github.com/AerionDyseti/mcp-memory-server.git"},"description":"A zero-configuration RAG memory server for MCP clients","maintainers":[{"name":"aeriondyseti","email":"inblessedsilencewaiting@gmail.com"}],"readme":"# MCP Memory Server\n\n> Replace static markdown context files with intelligent, semantically-searchable memories that understand what you're working on.\n\nA production-ready MCP (Model Context Protocol) server that provides semantic memory storage for AI assistants. Uses local embeddings and vector search to automatically retrieve relevant context without cloud dependencies.\n\n**Perfect for:** Software teams maintaining architectural knowledge, developers juggling multiple projects, and anyone building with AI assistants like Claude Code.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-Required-black.svg)](https://bun.sh/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)\n\n---\n\n## ✨ Features\n\n### 🔒 **Local-First & Private**\n- All embeddings generated locally (no cloud APIs)\n- Data stored in local sqlite-vec databases\n- Complete privacy and control over your memories\n\n### 🎯 **Intelligent Semantic Search**\n- Vector similarity with multi-factor scoring\n- Considers relevance, recency, priority, and usage frequency\n- Context-aware retrieval based on conversation flow\n\n### 📊 **Smart Memory Storage**\n- Stores memories in `~/.local/share/mcp-memory/memories.db`\n- Fast SQLite-based storage with vector search capabilities\n- Memories persist across sessions and projects\n\n### ⚡ **High Performance**\n- Sub-100ms search latency for 1000+ memories\n- Efficient storage (<10MB per 1000 memories)\n- CPU-optimized local embeddings (no GPU required)\n\n### 🔌 **MCP Native Integration**\n- Works seamlessly with Claude Code\n- Session hooks for automatic context injection\n- Standard MCP protocol (compatible with future clients)\n\n### 🛠️ **Developer-Friendly**\n- Zero-configuration setup\n- Built with Bun for maximum performance\n- Simple MCP tools for storing and searching\n- TypeScript for type safety\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) 1.0+\n- Claude Code or another MCP-compatible client\n\n> **Note:** This server uses Bun-specific APIs (`bun:sqlite`) and requires Bun to run.\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/AerionDyseti/mcp-memory-server.git\ncd mcp-memory-server\n\n# Install dependencies\nbun install\n```\n\n### Configure Claude Code\n\nAdd to your `~/.claude/config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"bun\",\n      \"args\": [\"run\", \"/absolute/path/to/mcp-memory-server/src/index.ts\"]\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/` with your actual installation path.\n\n### Start Using It\n\nThat's it! Restart Claude Code and you'll have access to memory tools:\n- `store_memory` - Save information for later recall\n- `search_memories` - Find relevant memories semantically\n- `get_memory` - Retrieve a specific memory by ID\n- `delete_memory` - Remove a memory\n\n---\n\n## 📖 Usage\n\n### Storing Memories\n\nAsk Claude Code to remember things for you:\n\n```\nYou: \"Remember that we use Drizzle ORM for database access\"\nClaude: [calls store_memory tool]\n```\n\nOr Claude Code can store memories directly:\n```json\n{\n  \"content\": \"Use Drizzle ORM for type-safe database access\",\n  \"metadata\": {\n    \"tags\": [\"architecture\", \"database\"],\n    \"category\": \"tooling\"\n  }\n}\n```\n\n### Searching Memories\n\nClaude Code automatically searches memories when relevant, or you can ask:\n\n```\nYou: \"What did we decide about the database?\"\nClaude: [calls search_memories with query about database decisions]\n```\n\nSearch parameters:\n```json\n{\n  \"query\": \"authentication strategy\",\n  \"limit\": 10\n}\n```\n\n### Managing Memories\n\nRetrieve a specific memory:\n```json\n{\n  \"id\": \"memory-id-here\"\n}\n```\n\nDelete a memory:\n```json\n{\n  \"id\": \"memory-id-here\"\n}\n```\n\n---\n\n## 🏗️ Architecture\n\n```\nmcp-memory-server/\n├── src/\n│   ├── index.ts            # Entry point\n│   ├── config/             # Configuration management\n│   ├── db/                 # Database layer (Drizzle ORM + sqlite-vec)\n│   ├── services/\n│   │   ├── embeddings.service.ts  # Embeddings via @xenova/transformers\n│   │   └── memory.service.ts      # Core memory operations\n│   └── mcp/\n│       ├── server.ts       # MCP server setup\n│       ├── tools.ts        # MCP tool definitions\n│       └── handlers.ts     # Tool request handlers\n├── tests/\n│   ├── memory.test.ts\n│   └── embeddings.test.ts\n├── bin/\n│   └── mcp-memory.js       # Executable entry point\n└── package.json\n```\n\n### Technology Stack\n\n- **MCP Framework**: @modelcontextprotocol/sdk (official SDK)\n- **Vector Database**: sqlite-vec (fast, local, SQLite-based)\n- **ORM**: Drizzle ORM with @aeriondyseti/drizzle-sqlite-vec\n- **Embeddings**: @xenova/transformers (Xenova/all-MiniLM-L6-v2, 384 dimensions)\n- **Language**: TypeScript 5.0+\n- **Runtime**: Bun 1.0+ (required for bun:sqlite)\n- **Testing**: Bun test\n\n---\n\n## 🎨 How It Works\n\n### 1. Memory Storage\n\n```\nClaude Code calls store_memory tool\n         ↓\nContent → @xenova/transformers → 384d vector\n         ↓\nStore in sqlite-vec with metadata\n         ↓\n~/.local/share/mcp-memory/memories.db\n```\n\n### 2. Memory Retrieval\n\n```\nClaude Code calls search_memories\n         ↓\nQuery → @xenova/transformers → 384d vector\n         ↓\nKNN search in sqlite-vec\n         ↓\nVector similarity scoring\n         ↓\nReturn top N relevant memories\n```\n\n---\n\n## 🔧 Configuration\n\nThe server uses environment variables for configuration:\n\n- `MCP_MEMORY_DB_PATH` - Custom database path (default: `~/.local/share/mcp-memory/memories.db`)\n- `MCP_MEMORY_MODEL` - Embedding model to use (default: `Xenova/all-MiniLM-L6-v2`)\n\nExample:\n```bash\nexport MCP_MEMORY_DB_PATH=\"/path/to/custom/memories.db\"\nexport MCP_MEMORY_MODEL=\"Xenova/all-MiniLM-L6-v2\"\n```\n\nOr in your Claude Code config:\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"mcp-memory\",\n      \"env\": {\n        \"MCP_MEMORY_DB_PATH\": \"/custom/path/memories.db\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 🧪 Development\n\n### Running Tests\n\n```bash\n# Run all tests\nbun test\n\n# Run with coverage\nbun test --coverage\n\n# Type checking\nbun run typecheck\n```\n\n### Development Mode\n\n```bash\n# Watch mode - auto-restart on file changes\nbun run dev\n\n# Run directly without building\nbun run src/index.ts\n```\n\n### Building\n\n```bash\n# Build for production\nbun run build\n\n# Output will be in dist/\n```\n\n---\n\n## 🗺️ Roadmap\n\n### ✅ Phase 1: Foundation (Current)\n- ✅ Core database with sqlite-vec\n- ✅ Embedding generation with @xenova/transformers\n- ✅ Basic MCP tools (store, search, get, delete)\n- ✅ TypeScript implementation with Drizzle ORM\n\n### 🚧 Phase 2: Enhanced Search & Scoring\n- Multi-factor scoring algorithm (similarity, recency, priority, usage frequency)\n- Configurable scoring weights\n- Priority levels for memories\n- Usage tracking and frequency-based ranking\n- Metadata filtering and advanced tagging\n\n### 📋 Phase 3: Dual-Level Memory System\n- Project-specific memories (`.memory/db` in repo)\n- Global memories (`~/.local/share/mcp-memory/`)\n- Automatic precedence handling (project overrides global)\n- Project detection and context switching\n\n### 🎯 Phase 4: Smart Automation\n- Auto-detect architectural decisions\n- Capture bug fixes and solutions automatically\n- Generate session-end summaries\n- Natural language trigger detection (85%+ accuracy)\n- Continuous conversation monitoring\n\n### 🔮 Phase 5: Advanced Features\n- Memory deduplication with similarity threshold\n- Batch operations (import/export)\n- Markdown import/export\n- Memory clustering and visualization\n- Cross-project insights\n- Multi-modal memories (images, diagrams)\n- Session hooks for automatic context injection\n- Multi-CLI support (Cursor, Windsurf, etc.)\n- Smart priority suggestions\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! This project is in active development.\n\n### Areas We'd Love Help With:\n- Testing and bug reports\n- Documentation improvements\n- Performance optimizations\n- New feature ideas\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines *(coming soon)*.\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - Official MCP TypeScript SDK\n- Uses [sqlite-vec](https://github.com/asg017/sqlite-vec) by Alex Garcia for fast vector search\n- Powered by [@xenova/transformers](https://github.com/xenova/transformers.js) for local embeddings\n- Database layer via [Drizzle ORM](https://orm.drizzle.team/)\n- Inspired by [doobidoo's mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)\n\n---\n\n## 🔗 Related Projects\n\n- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification\n- [Claude Code](https://claude.ai/code) - AI coding assistant from Anthropic\n- [sqlite-vec](https://github.com/asg017/sqlite-vec) - Vector search for SQLite\n- [Transformers.js](https://huggingface.co/docs/transformers.js) - Run transformers in JavaScript\n\n---\n\n## 💬 Support\n\n- **Issues**: [GitHub Issues](https://github.com/AerionDyseti/mcp-memory-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/AerionDyseti/mcp-memory-server/discussions)\n- **Documentation**: Check the `docs/` directory\n\n---\n\n## ⚡ Quick Examples\n\n### Example 1: Storing a Decision\n\n```\nYou: \"Remember that we decided to use Drizzle ORM for type-safe database access\"\nClaude: I'll store that for you.\n  [Calls store_memory tool with content and metadata]\n  ✓ Memory stored successfully\n```\n\n### Example 2: Searching Memories\n\n```\nYou: \"What did we decide about database tooling?\"\nClaude: Let me search for that...\n  [Calls search_memories with query about database]\n  Found: \"Use Drizzle ORM for type-safe database access\"\n\nBased on our previous decision, we're using Drizzle ORM...\n```\n\n### Example 3: Managing Memories\n\n```\nYou: \"Show me what you remember about authentication\"\nClaude: [Searches for authentication-related memories]\n  Found 3 memories:\n  1. \"Use JWT tokens for API authentication\"\n  2. \"Store refresh tokens in httpOnly cookies\"\n  3. \"Implement rate limiting on auth endpoints\"\n```\n\n---\n\n<div align=\"center\">\n\n**[⬆ Back to Top](#mcp-memory-server)**\n\nMade with ❤️ for developers who value context continuity\n\n</div>\n","readmeFilename":"README.md"}