code-recall: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

code-recall is an MCP (Model Context Protocol) server that provides semantic memory for AI coding agents. It stores observations, decisions, and learnings in a local SQLite database with vector search capabilities.

Commands

# Development
bun run dev          # Watch mode with auto-reload
bun run start        # Run server directly

# Testing
bun test             # Run all tests
bun test tests/memory/search.test.ts  # Run specific test file

# Linting
bun run lint         # Check code with Biome
bun run lint:fix     # Fix lint issues

Architecture

Core Components

src/
├── index.ts           # Entry point, starts MCP server via stdio
├── server.ts          # MCP server setup, registers all 8 tools
├── database/          # SQLite + sqlite-vec operations
│   └── index.ts       # DatabaseManager - all DB operations
├── memory/            # Semantic memory system
│   ├── index.ts       # MemoryManager - high-level memory API
│   ├── embeddings.ts  # Local embeddings via @xenova/transformers
│   └── search.ts      # Hybrid search (vector + FTS + recency)
├── rules/             # Guardrail rules engine
│   └── index.ts       # RulesEngine - semantic rule matching
└── code/              # Code analysis via tree-sitter
    ├── index.ts       # analyzeFile() entry point
    ├── parser.ts      # tree-sitter WASM loader
    └── extractors/    # Language-specific entity extraction

Data Flow

1. MCP Server (server.ts) exposes 8 tools via stdio transport
2. MemoryManager handles storing/searching memories with embeddings
3. DatabaseManager persists to SQLite with sqlite-vec for vector search
4. RulesEngine matches actions against rules using cosine similarity
5. CodeAnalyzer extracts entities (classes, functions) via tree-sitter

Search Algorithm

Hybrid search in memory/search.ts combines:

• Vector similarity (50%) - cosine similarity via sqlite-vec
• Full-text search (30%) - SQLite FTS5 BM25 ranking
• Recency (15%) - exponential decay over 7 days
• Failure boost (5%) - failed decisions rank 1.5x higher