simple-rick: Instructions file for Claude Code

CLAUDE.md

Guidance for AI agents working on this repository.

What this is

Simple Rick is a local MCP server that gives coding agents persistent memory. It records sessions, normalizes them into embedded chunks, wires those into a graph, and serves the relevant context back at the start of the next session. See README.md for the user-facing documentation.

Tech stack

• Runtime: Node.js 20+, TypeScript (ESM, "type": "module" — imports need the .js extension)
• Interface: MCP over stdio (@modelcontextprotocol/sdk)
• Database: SQLite via better-sqlite3, vectors via sqlite-vec
• AI providers: auto-detected — OpenAI, Google, Mistral, or Anthropic + Voyage (services/ai-providers.ts)
• File watching: chokidar
• Tests: Vitest

Critical constraints

Never write to stdout. MCP speaks JSON-RPC over stdout; a single console.log corrupts the protocol. src/server/index.ts reassigns console.log = console.error on its first line, above all imports. Keep that line where it is, and route logging through log.ts (see below).

Schema changes go through the migration runner. src/server/db/sqlite.ts applies schema.sql, then db/migrate.ts applies anything newer than the version recorded in schema_migrations. To change the schema, append an entry to MIGRATIONS — never edit or reorder an existing one, its version is already recorded in databases in the wild.

LLM output is never trusted directly. Parse it through services/ai-json.ts (extractObject, extractArray, asString, asInt, asEnum, asStringArray, filterValid). Those helpers coerce and log rather than throw, because one malformed model response must not take down the pipeline. Do not reintroduce bare JSON.parse(raw) ?? {}.

Errors get logged. Use log.ts (logError/logWarn/logInfo/logDebug) instead of console.error, and do not write a bare catch {} — pick a level: expected-and-noisy is debug, unexpected is warn or error.