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

package/README.md

@@ -1,445 +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 AI assistants like Claude Code.
+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**
-- Works seamlessly with Claude Code
-- Session hooks for automatic context injection
-- Standard MCP protocol (compatible with future clients)
-
-### 🛠️ **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+
-- Claude Code or another 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 Claude Code** - Add to `~/.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 Claude Code** - Add to `~/.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 Claude Code and you'll have access to memory tools:
-- `store_memory` - Save information for later recall
-- `search_memories` - Find relevant memories semantically
-- `get_memory` - Retrieve a specific memory by ID
-- `delete_memory` - Remove a memory
+| 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 Claude Code to remember things for you:
+## Usage
 
+**Store a memory:**
 ```
 You: "Remember that we use Drizzle ORM for database access"
-Claude: [calls store_memory tool]
+Assistant: [calls store_memories]
 ```
 
-Or Claude Code can store memories directly:
-```json
-{
-  "content": "Use Drizzle ORM for type-safe database access",
-  "metadata": {
-    "tags": ["architecture", "database"],
-    "category": "tooling"
-  }
-}
-```
-
-### Searching Memories
-
-Claude Code automatically searches 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]
+Assistant: [calls search_memories with relevant query]
 ```
 
-Search parameters:
-```json
-{
-  "query": "authentication strategy",
-  "limit": 10
-}
+**Session handoffs:**
 ```
-
-### Managing Memories
-
-Retrieve a specific memory:
-```json
-{
-  "id": "memory-id-here"
-}
-```
-
-Delete a memory:
-```json
-{
-  "id": "memory-id-here"
-}
+You: "Save context for next session"
+Assistant: [calls store_handoff with summary, completed items, next steps]
 ```
 
 ---
 
-## 🏗️ Architecture
+## Configuration
 
-```
-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
+Environment variables:
 
-```
-Claude Code calls store_memory tool
-         ↓
-Content → @huggingface/transformers → 384d vector
-         ↓
-Store in LanceDB with metadata
-         ↓
-~/.local/share/vector-memory-mcp/memories.db
-```
-
-### 2. Memory Retrieval
-
-```
-Claude Code calls search_memories
-         ↓
-Query → @huggingface/transformers → 384d vector
-         ↓
-Vector search in LanceDB
-         ↓
-Vector similarity scoring
-         ↓
-Return top N relevant memories
-```
+| 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 |
 
 ---
 
-## 🔧 Configuration
-
-The server uses environment variables for configuration:
-
-- `VECTOR_MEMORY_DB_PATH` - Custom database path (default: `~/.local/share/vector-memory-mcp/memories.db`)
-- `VECTOR_MEMORY_MODEL` - Embedding model to use (default: `Xenova/all-MiniLM-L6-v2`)
+## Development
 
-Example:
 ```bash
-export VECTOR_MEMORY_DB_PATH="/path/to/custom/memories.db"
-export VECTOR_MEMORY_MODEL="Xenova/all-MiniLM-L6-v2"
-```
-
-Or in your Claude Code config:
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "vector-memory-mcp",
-      "env": {
-        "VECTOR_MEMORY_DB_PATH": "/custom/path/memories.db"
-      }
-    }
-  }
-}
-```
-
----
-
-## 🧪 Development
-
-### Running Tests
-
-```bash
-# Run all tests
-bun test
-
-# Run with coverage
-bun test --coverage
-
-# Type checking
-bun run typecheck
-```
-
-### Development Mode
-
-```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)*.
+See [CHANGELOG.md](CHANGELOG.md) for release history and [ROADMAP.md](ROADMAP.md) for planned features.
 
 ---
 
-## 📄 License
+## Contributing
 
-MIT License - see [LICENSE](LICENSE) for details.
+Contributions welcome! See [issues](https://github.com/AerionDyseti/vector-memory-mcp/issues) for areas we'd love help with.
 
----
+## License
 
-## 🙏 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)
+MIT - see [LICENSE](LICENSE)
 
 ---
 
-## 🔗 Related Projects
-
-- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification
-- [Claude Code](https://claude.ai/code) - AI coding assistant from Anthropic
-- [LanceDB](https://lancedb.com/) - Fast, local vector search
-- [Transformers.js](https://huggingface.co/docs/transformers.js) - Run transformers in JavaScript
-
----
-
-## 💬 Support
-
-- **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
-
----
-
-## ⚡ Quick Examples
-
-### Example 1: Storing a Decision
-
-```
-You: "Remember that we decided to use Drizzle ORM for type-safe database access"
-Claude: I'll store that for you.
-  [Calls store_memory 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"
-```
-
----
-
-<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/hooks/session-start.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+/**
+ * SessionStart hook for Claude Code
+ *
+ * Fetches config from the running vector-memory server's /health endpoint,
+ * then retrieves and outputs the latest handoff.
+ *
+ * Requires the server to be running with HTTP enabled.
+ *
+ * Usage in ~/.claude/settings.json:
+ * {
+ *   "hooks": {
+ *     "SessionStart": [{
+ *       "hooks": [{
+ *         "type": "command",
+ *         "command": "bun /path/to/vector-memory-mcp/hooks/session-start.ts"
+ *       }]
+ *     }]
+ *   }
+ * }
+ */
+
+import { existsSync } from "fs";
+import { connectToDatabase } from "../src/db/connection.js";
+import { MemoryRepository } from "../src/db/memory.repository.js";
+import { EmbeddingsService } from "../src/services/embeddings.service.js";
+import { MemoryService } from "../src/services/memory.service.js";
+
+const VECTOR_MEMORY_URL = process.env.VECTOR_MEMORY_URL ?? "http://127.0.0.1:3271";
+
+interface HealthResponse {
+  status: string;
+  config: {
+    dbPath: string;
+    embeddingModel: string;
+    embeddingDimension: number;
+  };
+}
+
+async function main() {
+  // Get config from running server
+  let health: HealthResponse;
+  try {
+    const response = await fetch(`${VECTOR_MEMORY_URL}/health`);
+    if (!response.ok) {
+      throw new Error(`Server returned ${response.status}`);
+    }
+    health = await response.json();
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("ECONNREFUSED")) {
+      console.log("Vector memory server not running. Starting fresh session.");
+      return;
+    }
+    throw error;
+  }
+
+  const { dbPath, embeddingModel, embeddingDimension } = health.config;
+
+  // Check if DB exists
+  if (!existsSync(dbPath)) {
+    console.log("Vector memory database not found. Starting fresh session.");
+    return;
+  }
+
+  const db = await connectToDatabase(dbPath);
+  const repository = new MemoryRepository(db);
+  const embeddings = new EmbeddingsService(embeddingModel, embeddingDimension);
+  const service = new MemoryService(repository, embeddings);
+
+  const handoff = await service.getLatestHandoff();
+
+  if (!handoff) {
+    console.log("No handoff found. Starting fresh session.");
+    return;
+  }
+
+  // Fetch referenced memories if any
+  const memoryIds = (handoff.metadata.memory_ids as string[] | undefined) ?? [];
+  let memoriesSection = "";
+
+  if (memoryIds.length > 0) {
+    const memories: string[] = [];
+    for (const id of memoryIds) {
+      const memory = await service.get(id);
+      if (memory) {
+        memories.push(`### Memory: ${id}\n${memory.content}`);
+      }
+    }
+    if (memories.length > 0) {
+      memoriesSection = `\n\n## Referenced Memories\n\n${memories.join("\n\n")}`;
+    }
+  }
+
+  console.log(handoff.content + memoriesSection);
+}
+
+main().catch((err) => {
+  console.error("Error loading handoff:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeriondyseti/vector-memory-mcp",
-  "version": "0.5.0",
+  "version": "0.9.0-dev.1",
   "description": "A zero-configuration RAG memory server for MCP clients",
   "type": "module",
   "main": "src/index.ts",
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "scripts",
+    "hooks",
     "README.md",
     "LICENSE"
   ],
@@ -25,6 +26,7 @@
   "scripts": {
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
+    "build": "bun run typecheck",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun run scripts/test-runner.ts",
     "test:raw": "bun test --preload ./tests/preload.ts",
@@ -32,14 +34,24 @@
     "test:coverage": "bun test --preload ./tests/preload.ts --coverage",
     "test:preload": "bun run tests/preload.ts",
     "warmup": "bun run scripts/warmup.ts",
-    "postinstall": "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:dev": "npm publish --access public --tag dev"
   },
-  "keywords": ["mcp", "memory", "rag", "embeddings", "lancedb"],
+  "keywords": [
+    "mcp",
+    "memory",
+    "rag",
+    "embeddings",
+    "lancedb"
+  ],
   "license": "MIT",
   "dependencies": {
     "@huggingface/transformers": "^3.8.0",
     "@lancedb/lancedb": "^0.22.3",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "arg": "^5.0.2",
     "hono": "^4.11.3"
   },
   "devDependencies": {