WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

Capsule Memory is an AI-ready long-term memory service built with Modelence. It provides semantic memory storage and retrieval capabilities for AI agents, with both a React web UI and an MCP (Model Context Protocol) bridge for local agent integration.

Architecture

Tech Stack

• Framework: TypeScript + Modelence (Express + MongoDB server, React/Vite client)
• Database: MongoDB with vector embeddings storage
• Embeddings: Voyage AI voyage-3.5 model (1024-dimensional vectors) with deterministic fallback
• Frontend: React + React Router + TanStack Query + Tailwind CSS
• MCP Integration: Node.js bridge exposing memory operations as MCP tools

Core Components

Backend (packages/core/src/server/):

• app.ts - Main Modelence application entry point that registers the memory module
• memory/index.ts - Core memory module with RPC methods (queries and mutations)
• memory/db.ts - MongoDB store definition with schema and indexes for memory documents
• memory/voyage.ts - Voyage AI embedding client with deterministic fallback

Frontend (src/client/):

• router.ts - React Router configuration with lazy loading
• pages/HomePage.tsx - Landing page with navigation to memory interface
• pages/MemoryPage.tsx - Main memory management UI with forms and search
• Uses @tanstack/react-query for server state management

MCP Bridge (tools/capsule-memory-mcp.mjs):

• Standalone Node.js script that exposes memory operations as MCP tools
• Proxies requests to the running Modelence server via HTTP API
• Provides 5 MCP tools: store, search, list, pin, forget

Data Model

Memory documents stored in MongoDB contain:

• content (string) - The memory text content
• embedding (number[]) - Normalized 1024-dimensional embedding vector
• embeddingNorm (number) - Original embedding magnitude for cosine similarity scoring
• createdAt (Date) - Creation timestamp
• pinned (boolean) - Protection flag preventing auto-deletion
• explanation (string, optional) - Audit trail for memory creation

Memory Management Logic

Retention Policy: Maintains a rolling limit of 100 memories maximum. When exceeded, automatically removes the oldest unpinned memory and reports the action.

Search Algorithm: Uses in-memory cosine similarity scoring rather than MongoDB vector search for simplicity and portability. Fetches up to 500 recent memories, scores them against query embedding, and returns top results.

Common Development Commands

# Install dependencies
pnpm install

# Start development server (both backend and frontend)
pnpm dev

# Build all packages
pnpm build

# Run MCP bridge (for local agents like Claude Desktop)
pnpm run mcp

Environment Configuration

Create .env or .modelence.env with:

MONGO_URL="mongodb+srv://..."    # Required for Atlas/production
VOYAGE_API_KEY="sk-..."          # Optional - enables true Voyage embeddings

Without VOYAGE_API_KEY, the system uses a deterministic fallback embedding for development.

Development Guidelines

Working with Memory Module

• All memory operations go through the Modelence module system in packages/core/src/server/memory/index.ts
• Queries: getMemories (recent/pinned), searchMemory (semantic search)
• Mutations: addMemory, pinMemory, deleteMemory
• All operations return explanatory messages for transparency

Frontend Development

• Memory UI is at /memory route
• Uses TanStack Query for caching and optimistic updates
• Forms provide immediate feedback via toast notifications
• All server communication uses Modelence's RPC client

MCP Integration

• MCP bridge runs independently via pnpm run mcp
• Connects to running Modelence server (default: http://localhost:3000)
• Override server URL with CAPSULE_MEMORY_URL environment variable
• Provides structured and text-based responses for agent consumption

Embedding System

• Production uses Voyage AI voyage-3.5 model
• Development fallback creates deterministic embeddings from text hash
• All embeddings are L2-normalized for consistent cosine similarity scoring
• Vector dimensions are fixed at 1024 (constant in db.ts)

Database Considerations

• Uses Modelence's MongoDB Store abstraction
• Indexes on createdAt and pinned, createdAt for efficient queries
• No MongoDB Atlas Vector Search dependency (pure Node.js scoring)
• Vector search can be upgraded to Atlas when provisioned

Testing the System

Manual QA Checklist:

1. Memory creation persists and displays correctly
2. Pinned memories survive auto-forget policy
3. Memory limit triggers oldest unpinned deletion with explanation
4. Semantic search returns relevant results with scores
5. Pin/unpin toggles work correctly
6. Delete operations remove memories permanently
7. MCP bridge tools work with local agents

Key URLs:

• Web UI: http://localhost:5173/memory (development)
• API Health: Check Modelence server logs for startup confirmation

Debugging Tips

• No embeddings: Check VOYAGE_API_KEY configuration or confirm fallback embedding is working
• Database errors: Verify MONGO_URL connection and MongoDB Atlas provisioning
• MCP bridge issues: Confirm Modelence server is running and accessible on expected port
• Memory not persisting: Check MongoDB connection and Modelence Store initialization
• Search returning no results: Verify embedding generation and normalization logic