@aeriondyseti/vector-memory-mcp 0.8.0 → 0.9.0-dev.1

package/README.md

@@ -1,453 +1,129 @@
 # Vector Memory MCP Server
 
-> Replace static markdown context files with intelligent, semantically-searchable memories that understand what you're working on.
+> Semantic memory storage for AI assistants. Store decisions, patterns, and context that persists across sessions.
 
-A 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.
-
-**Perfect for:** Software teams maintaining architectural knowledge, developers juggling multiple projects, and anyone building with MCP-compatible AI assistants.
+A local-first MCP server that provides vector-based memory storage. Uses local embeddings and LanceDB for fast, private semantic search.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![Bun](https://img.shields.io/badge/Bun-Required-black.svg)](https://bun.sh/)
-[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
+[![npm version](https://img.shields.io/npm/v/@aeriondyseti/vector-memory-mcp.svg)](https://www.npmjs.com/package/@aeriondyseti/vector-memory-mcp)
 
 ---
 
-## ✨ Features
-
-### 🔒 **Local-First & Private**
-- All embeddings generated locally (no cloud APIs)
-- Data stored in local LanceDB databases
-- Complete privacy and control over your memories
-
-### 🎯 **Intelligent Semantic Search**
-- Vector similarity with multi-factor scoring
-- Considers relevance, recency, priority, and usage frequency
-- Context-aware retrieval based on conversation flow
-
-### 📊 **Smart Memory Storage**
-- Stores memories in `~/.local/share/vector-memory-mcp/memories.db`
-- Fast LanceDB-based storage with vector search capabilities
-- Memories persist across sessions and projects
-
-### ⚡ **High Performance**
-- Sub-100ms search latency for 1000+ memories
-- Efficient storage (<10MB per 1000 memories)
-- CPU-optimized local embeddings (no GPU required)
+## Features
 
-### 🔌 **MCP Native Integration**
-- Standard MCP protocol (compatible with any client)
-
-### 🛠️ **Developer-Friendly**
-- Zero-configuration setup
-- Built with Bun for maximum performance
-- Simple MCP tools for storing and searching
-- TypeScript for type safety
+- **Local & Private** - All embeddings generated locally, data stored in local LanceDB
+- **Semantic Search** - Vector similarity search with configurable scoring
+- **Batch Operations** - Store, update, delete, and retrieve multiple memories at once
+- **Session Handoffs** - Save and restore project context between sessions
+- **MCP Native** - Standard protocol, works with any MCP-compatible client
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Prerequisites
 
 - [Bun](https://bun.sh/) 1.0+
-- An MCP-compatible client
-
-> **Note:** This server requires Bun to run.
+- An MCP-compatible client (Claude Code, Claude Desktop, etc.)
 
-### Installation & Configuration
+### Install
 
-#### Option 1: Global Install (Recommended)
-
-**Install:**
 ```bash
 bun install -g @aeriondyseti/vector-memory-mcp
 ```
 
-> **Note:** The installation automatically downloads ML models (~90MB) and verifies native dependencies. This may take a minute on first install.
-
-**Configure your MCP client** (example config for clients that use `~/.claude/config.json`):
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "type": "stdio",
-      "command": "bunx",
-      "args": [
-        "--bun",
-        "@aeriondyseti/vector-memory-mcp"
-      ],
-      "env": {}
-    }
-  }
-}
-```
+> First install downloads ML models (~90MB). This may take a minute.
 
-#### Option 2: Local Development
+### Configure
 
-**Install:**
-```bash
-git clone https://github.com/AerionDyseti/vector-memory-mcp.git
-cd vector-memory-mcp
-bun install
-```
+Add to your MCP client config (e.g., `~/.claude/settings.json`):
 
-**Configure your MCP client** (example config for clients that use `~/.claude/config.json`):
 ```json
 {
   "mcpServers": {
-    "memory": {
-      "command": "bun",
-      "args": ["run", "/absolute/path/to/vector-memory-mcp/src/index.ts"]
+    "vector-memory": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["--bun", "@aeriondyseti/vector-memory-mcp"]
     }
   }
 }
 ```
-*Replace `/absolute/path/to/` with your actual installation path.*
 
----
+### Use
 
-**What gets installed:**
-- The vector-memory-mcp package and all dependencies
-- Native binaries for ONNX Runtime (~32MB) and image processing (~10MB)
-- ML model files automatically downloaded during installation (~90MB, cached in `~/.cache/huggingface/`)
-- **Total first-time setup:** ~130MB of downloads
+Restart your MCP client. You now have access to:
 
-> 💡 **Tip:** If you need to re-download models or verify dependencies, run: `vector-memory-mcp warmup`
-
-### Start Using It
-
-That's it! Restart your MCP client and you'll have access to memory tools:
-- `store_memories` - Save memories for later recall (always pass array)
-- `search_memories` - Find relevant memories semantically
-- `get_memories` - Retrieve memories by ID (always pass array)
-- `update_memories` - Update existing memories in place
-- `delete_memories` - Remove memories (always pass array of IDs)
-- `store_handoff` - Store a handoff-style project snapshot
-- `get_handoff` - Retrieve the latest handoff (includes referenced memories)
+| Tool | Description |
+|------|-------------|
+| `store_memories` | Save memories (accepts array) |
+| `search_memories` | Find relevant memories semantically |
+| `get_memories` | Retrieve memories by ID (accepts array) |
+| `update_memories` | Update existing memories |
+| `delete_memories` | Remove memories (accepts array) |
+| `store_handoff` | Save session context for later |
+| `get_handoff` | Restore session context |
 
 ---
 
-## 📖 Usage
-
-### Storing Memories
-
-Ask your MCP client/agent to remember things for you:
+## Usage
 
+**Store a memory:**
 ```
 You: "Remember that we use Drizzle ORM for database access"
-Claude: [calls store_memories tool]
-```
-
-Or your MCP client/agent can store memories directly:
-```json
-{
-  "content": "Use Drizzle ORM for type-safe database access",
-  "metadata": {
-    "tags": ["architecture", "database"],
-    "category": "tooling"
-  }
-}
+Assistant: [calls store_memories]
 ```
 
-### Searching Memories
-
-Your MCP client/agent can automatically search memories when relevant, or you can ask:
-
+**Search memories:**
 ```
 You: "What did we decide about the database?"
-Claude: [calls search_memories with query about database decisions]
-```
-
-Search parameters:
-```json
-{
-  "query": "authentication strategy",
-  "limit": 10
-}
-```
-
-### Managing Memories
-
-Retrieve a specific memory:
-```json
-{
-  "id": "memory-id-here"
-}
-```
-
-Delete a memory:
-```json
-{
-  "id": "memory-id-here"
-}
-```
-
----
-
-## 🏗️ Architecture
-
-```
-vector-memory-mcp/
-├── src/
-│   ├── index.ts            # Entry point
-│   ├── config/             # Configuration management
-│   ├── db/                 # Database layer (LanceDB)
-│   ├── services/
-│   │   ├── embeddings.service.ts  # Embeddings via @huggingface/transformers
-│   │   └── memory.service.ts      # Core memory operations
-│   └── mcp/
-│       ├── server.ts       # MCP server setup
-│       ├── tools.ts        # MCP tool definitions
-│       └── handlers.ts     # Tool request handlers
-├── tests/
-│   ├── memory.test.ts
-│   └── embeddings.test.ts
-├── bin/
-│   └── vector-memory-mcp.js # Executable entry point
-└── package.json
-```
-
-### Technology Stack
-
-- **MCP Framework**: @modelcontextprotocol/sdk (official SDK)
-- **Vector Database**: LanceDB (fast, local, vector search)
-- **Embeddings**: [@huggingface/transformers](https://huggingface.co/docs/transformers.js) (Xenova/all-MiniLM-L6-v2, 384 dimensions)
-- **Language**: TypeScript 5.0+
-- **Runtime**: Bun 1.0+
-- **Testing**: Bun test
-
----
-
-## 🎨 How It Works
-
-### 1. Memory Storage
-
+Assistant: [calls search_memories with relevant query]
 ```
-An MCP client calls store_memories tool
-         ↓
-Content → @huggingface/transformers → 384d vector
-         ↓
-Store in LanceDB with metadata
-         ↓
-~/.local/share/vector-memory-mcp/memories.db
-```
-
-### 2. Memory Retrieval
 
+**Session handoffs:**
 ```
-An MCP client calls search_memories
-         ↓
-Query → @huggingface/transformers → 384d vector
-         ↓
-Vector search in LanceDB
-         ↓
-Vector similarity scoring
-         ↓
-Return top N relevant memories
+You: "Save context for next session"
+Assistant: [calls store_handoff with summary, completed items, next steps]
 ```
 
 ---
 
-## 🔧 Configuration
-
-The server uses environment variables for configuration:
+## Configuration
 
-- `VECTOR_MEMORY_DB_PATH` - Custom database path (default: `./.claude/vector-memories.db`)
+Environment variables:
 
-> Note: if you point multiple projects at the same DB path, `store_handoff` uses UUID.ZERO and will overwrite the previous handoff (by design).
-- `VECTOR_MEMORY_MODEL` - Embedding model to use (default: `Xenova/all-MiniLM-L6-v2`)
-
-Example:
-```bash
-export VECTOR_MEMORY_DB_PATH="/path/to/custom/memories.db"
-export VECTOR_MEMORY_MODEL="Xenova/all-MiniLM-L6-v2"
-```
-
-Or in your MCP client config:
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "vector-memory-mcp",
-      "env": {
-        "VECTOR_MEMORY_DB_PATH": "/custom/path/memories.db"
-      }
-    }
-  }
-}
-```
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VECTOR_MEMORY_DB_PATH` | `.vector-memory/memories.db` | Database location |
+| `VECTOR_MEMORY_MODEL` | `Xenova/all-MiniLM-L6-v2` | Embedding model |
+| `VECTOR_MEMORY_HTTP_PORT` | `3271` | HTTP server port |
 
 ---
 
-## 🧪 Development
-
-### Running Tests
-
-```bash
-# Run all tests (recommended - includes model preload)
-bun run test
-
-# Run tests directly (skips 19 embedding tests, faster)
-bun test
-
-# Run with coverage
-bun test --coverage
-
-# Type checking
-bun run typecheck
-```
-
-> **Note:** `bun run test` uses a wrapper that preloads the embedding model, running all 98 tests. `bun test` directly is faster but skips embedding-specific tests.
-
-### Development Mode
+## Development
 
 ```bash
-# Watch mode - auto-restart on file changes
-bun run dev
-
-# Run directly without building
-bun run src/index.ts
-```
-
-### Building
-
-```bash
-# Build for production
-bun run build
+git clone https://github.com/AerionDyseti/vector-memory-mcp.git
+cd vector-memory-mcp
+bun install
 
-# Output will be in dist/
+bun run test      # Run all tests
+bun run dev       # Watch mode
+bun run typecheck # Type checking
 ```
 
----
-
-## 🗺️ Roadmap
-
-### ✅ Phase 1: Foundation (Current)
-- ✅ Core database with LanceDB
-- ✅ Embedding generation with @huggingface/transformers
-- ✅ Basic MCP tools (store, search, get, delete)
-- ✅ TypeScript implementation with Drizzle ORM
-
-### 🚧 Phase 2: Enhanced Search & Scoring
-- Multi-factor scoring algorithm (similarity, recency, priority, usage frequency)
-- Configurable scoring weights
-- Priority levels for memories
-- Usage tracking and frequency-based ranking
-- Metadata filtering and advanced tagging
-
-### 📋 Phase 3: Dual-Level Memory System
-- Project-specific memories (`.memory/db` in repo)
-- Global memories (`~/.local/share/vector-memory-mcp/`)
-- Automatic precedence handling (project overrides global)
-- Project detection and context switching
-
-### 🎯 Phase 4: Smart Automation
-- Auto-detect architectural decisions
-- Capture bug fixes and solutions automatically
-- Generate session-end summaries
-- Natural language trigger detection (85%+ accuracy)
-- Continuous conversation monitoring
-
-### 🔮 Phase 5: Advanced Features
-- Memory deduplication with similarity threshold
-- Batch operations (import/export)
-- Markdown import/export
-- Memory clustering and visualization
-- Cross-project insights
-- Multi-modal memories (images, diagrams)
-- Session hooks for automatic context injection
-- Multi-CLI support (Cursor, Windsurf, etc.)
-- Smart priority suggestions
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome! This project is in active development.
-
-### Areas We'd Love Help With:
-- Testing and bug reports
-- Documentation improvements
-- Performance optimizations
-- New feature ideas
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines *(coming soon)*.
-
----
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) for details.
-
----
-
-## 🙏 Acknowledgments
-
-- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - Official MCP TypeScript SDK
-- Uses [LanceDB](https://lancedb.com/) for fast, local vector search
-- Powered by [@huggingface/transformers](https://huggingface.co/docs/transformers.js) for local embeddings
-- Database layer via [Drizzle ORM](https://orm.drizzle.team/)
-- Inspired by [doobidoo's mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)
-
----
-
-## 🔗 Related Projects
-
-- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification
-- Any MCP-compatible client
-- [LanceDB](https://lancedb.com/) - Fast, local vector search
-- [Transformers.js](https://huggingface.co/docs/transformers.js) - Run transformers in JavaScript
+See [CHANGELOG.md](CHANGELOG.md) for release history and [ROADMAP.md](ROADMAP.md) for planned features.
 
 ---
 
-## 💬 Support
+## Contributing
 
-- **Issues**: [GitHub Issues](https://github.com/AerionDyseti/vector-memory-mcp/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/AerionDyseti/vector-memory-mcp/discussions)
-- **Documentation**: Check the `docs/` directory
+Contributions welcome! See [issues](https://github.com/AerionDyseti/vector-memory-mcp/issues) for areas we'd love help with.
 
----
-
-## ⚡ Quick Examples
-
-### Example 1: Storing a Decision
+## License
 
-```
-You: "Remember that we decided to use Drizzle ORM for type-safe database access"
-Claude: I'll store that for you.
-  [Calls store_memories tool with content and metadata]
-  ✓ Memory stored successfully
-```
-
-### Example 2: Searching Memories
-
-```
-You: "What did we decide about database tooling?"
-Claude: Let me search for that...
-  [Calls search_memories with query about database]
-  Found: "Use Drizzle ORM for type-safe database access"
-
-Based on our previous decision, we're using Drizzle ORM...
-```
-
-### Example 3: Managing Memories
-
-```
-You: "Show me what you remember about authentication"
-Claude: [Searches for authentication-related memories]
-  Found 3 memories:
-  1. "Use JWT tokens for API authentication"
-  2. "Store refresh tokens in httpOnly cookies"
-  3. "Implement rate limiting on auth endpoints"
-```
+MIT - see [LICENSE](LICENSE)
 
 ---
 
-<div align="center">
-
-**[⬆ Back to Top](#vector-memory-mcp-server)**
-
-Made with ❤️ for developers who value context continuity
-
-</div>
+Built with [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk), [LanceDB](https://lancedb.com/), and [Transformers.js](https://huggingface.co/docs/transformers.js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0-dev.1",
   "description": "A zero-configuration RAG memory server for MCP clients",
   "type": "module",
   "main": "src/index.ts",
@@ -36,7 +36,8 @@
     "warmup": "bun run scripts/warmup.ts",
     "postinstall": "bun run scripts/warmup.ts",
     "publish:check": "bun run scripts/publish.ts --dry-run",
-    "publish:npm": "bun run scripts/publish.ts"
+    "publish:npm": "bun run scripts/publish.ts",
+    "publish:dev": "npm publish --access public --tag dev"
   },
   "keywords": [
     "mcp",

package/src/mcp/tools.ts

@@ -2,10 +2,28 @@ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 
 export const storeMemoriesTool: Tool = {
   name: "store_memories",
-  description:
-    "Build persistent memory across conversations. Store decisions, solutions, user preferences, " +
-    "patterns, or anything worth remembering. Batch related items in one call. " +
-    "For long content (>1000 chars), provide embedding_text with a searchable summary.",
+  description: `Store memories that persist across conversations. Use after making decisions or learning something worth remembering.
+
+RULES:
+- 1 concept per memory, 1-3 sentences (20-75 words)
+- Self-contained with explicit subjects (no "it", "this", "the project")
+- Include dates/versions when relevant
+- Be concrete, not vague
+
+MEMORY TYPES (use as metadata.type):
+- decision: what was chosen + why ("Chose libSQL over PostgreSQL for vector support and simpler deployment")
+- implementation: what was built + where + patterns used
+- insight: learning + why it matters
+- blocker: problem encountered + resolution
+- next-step: TODO item + suggested approach
+- context: background info + constraints
+
+DON'T STORE: machine-specific paths, local env details, ephemeral states, pleasantries
+
+GOOD: "Aerion chose libSQL over PostgreSQL for Resonance (Dec 2024) because of native vector support and simpler deployment."
+BAD: "Uses SQLite" (no context, no subject, no reasoning)
+
+For long content (>1000 chars), provide embedding_text with a searchable summary.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -61,9 +79,13 @@ export const deleteMemoriesTool: Tool = {
 
 const updateMemoriesTool: Tool = {
   name: "update_memories",
-  description:
-    "Update existing memories in place. Use to correct content, refine embedding text, or replace metadata " +
-    "without changing the memory ID. Prefer over delete+create when updating the same conceptual item.",
+  description: `Update existing memories in place. Prefer over delete+create when updating the same conceptual item.
+
+BEHAVIOR:
+- Fields omitted/null: left untouched
+- Fields provided: completely overwrite existing value (no merge)
+
+Use to correct content, refine embedding text, or replace metadata without changing the memory ID.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -101,12 +123,22 @@ const updateMemoriesTool: Tool = {
 
 export const searchMemoriesTool: Tool = {
   name: "search_memories",
-  description:
-    "Search stored memories semantically. Use PROACTIVELY—don't wait to be asked. " +
-    "Triggers: references to past decisions ('what did we decide', 'as discussed'), " +
-    "questions about prior work, returning to a project, debugging something potentially solved before, " +
-    "or questions about established patterns/preferences. " +
-    "When uncertain, search—missing relevant memories is costlier than an extra query.",
+  description: `Search stored memories semantically. Use PROACTIVELY—don't wait to be asked.
+
+WHEN TO SEARCH:
+- At conversation start / returning to a project
+- Before making decisions (check for prior decisions on same topic)
+- When user references past work ("what did we decide", "as discussed", "remember when")
+- Before suggesting solutions (check if problem was solved before)
+- When debugging (check for prior blockers/resolutions)
+- When uncertain about patterns or preferences
+
+When in doubt, search. Missing relevant context is costlier than an extra query.
+
+QUERY TIPS:
+- Include project name, technical terms, or domain keywords
+- Search for concepts, not exact phrases
+- Try multiple queries if first doesn't return useful results`,
   inputSchema: {
     type: "object",
     properties: {
@@ -149,9 +181,17 @@ export const getMemoriesTool: Tool = {
 
 export const storeHandoffTool: Tool = {
   name: "store_handoff",
-  description:
-    "Capture structured project state for handoff: summary, completed work, blockers, key decisions, next steps. " +
-    "Retrievable via get_handoff.",
+  description: `Save session state for seamless resumption later. Use at end of work sessions or before context switches.
+
+Creates a structured snapshot with:
+- summary: 2-3 sentences on goal and current status
+- completed: what got done (include file paths)
+- in_progress_blocked: work in flight or stuck
+- key_decisions: choices made and WHY (crucial for future context)
+- next_steps: concrete, actionable items
+- memory_ids: link to related memories stored this session
+
+Retrievable via get_handoff. Only one handoff per project—new handoffs overwrite previous.`,
   inputSchema: {
     type: "object",
     properties: {