mor CLAUDE.md

CLAUDE.md

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

Commands

pnpm build          # Compile TypeScript to dist/
pnpm test           # Run all tests (vitest)
pnpm test -- -t "test name"  # Run a single test by name
pnpm lint           # ESLint
pnpm format         # Prettier --write
pnpm format:check   # Check formatting without writing
pnpm dev            # Run CLI via tsx without building

Architecture

A memory bank for AI assistants. Stores knowledge as markdown files with YAML frontmatter, indexed by SQLite (FTS5 + optional vector embeddings).

Operations Interface

The central abstraction is Operations in operations.ts with two implementations:

• LocalOperations — filesystem + SQLite, used by CLI in local mode and by the HTTP server
• RemoteOperations (operations-client.ts) — HTTP client that wraps a remote server

All three access surfaces use this interface:

1. CLI (cli.ts) — Commander-based, calls getOps(config) to get local or remote ops
2. MCP Server (mcp.ts) — Stdio and HTTP transports, calls getOps(config) to get local or remote ops
3. HTTP Server (operations-server.ts) — Hono-based, creates LocalOperations

Search & Query Resolution

resolveQuery in LocalOperations resolves a user query by trying in order: full UUID → UUID prefix (8+ chars) → filename → FTS search. search() does FTS5 search, optionally merged with vector similarity via hybrid fusion. When embeddings are enabled, scores combine a normalized FTS rank component (RRF-style with k=60) and raw cosine similarity, averaged to a 0–1 scale. Without embeddings, raw BM25 scores are used. search() returns a SearchPage with a scoring field ('fts' or 'hybrid') so consumers can apply context-dependent thresholds. Frequently accessed memories get a small ranking boost.

syncIndex walks the memory directory and upserts changed files by content hash. syncIndexIfNeeded is a debounced wrapper (200ms) used on read paths to avoid redundant scans.