conventions-mcp: Instructions file for Claude Code

conventions-mcp

A personal memory MCP server: local SQLite storage, local embeddings, hybrid (vector + keyword) search, MCP over stdio. See README.md for the pitch and setup steps — this file is guidance for Claude Code (or any agent) working on the server's own code, plus how to wire the finished server into a client.

Architecture

• src/db.js — SQLite (better-sqlite3) + sqlite-vec (vector search) + FTS5 (keyword search). One thoughts table; FTS5 stays in sync via triggers; sqlite-vec does not, so deleteThought deletes both rows explicitly in one transaction. hybridSearch merges vector + FTS results with reciprocal rank fusion (1 / (k + rank)), not a raw score blend. DB_PATH (exported) resolves via MEMORY_DB_PATH, else defaultDbPath(): ./data/memory.db in a git checkout (detected by a sibling .git directory — npm never publishes one), or ~/.conventions-mcp/memory.db otherwise, since an npm/npx install's own directory usually isn't user-writable and gets wiped on upgrade. getDb() creates that directory if missing, so nothing upstream needs to mkdir first. The DB runs in WAL mode with synchronous=FULL, a bounded autocheckpoint, and a busy timeout. The WAL is part of the durable database state; writes do not force a checkpoint after commit because that can fail after a successful write or interfere with concurrent readers. Graceful shutdown checkpoints and closes the database. The database directory and files are private to the user on POSIX systems. backupDatabase uses SQLite's online backup API, verifies the snapshot, and publishes it atomically without overwriting an existing file.
• src/load-env.js — side-effect module loading ~/.conventions-mcp/.env into process.env (without overriding anything already set), for entry points invoked without Node's own --env-file flag — the installed conventions-mcp bin and the hook scripts run standalone. Import it FIRST in any file that reads process.env at module-load time, before importing db.js; ES module static imports evaluate in file order, so a leading import guarantees this runs before those reads. Nothing in this codebase requires an env var — MEMORY_DB_PATH is the only one read, and it's optional.
• src/embeddings.js — local embedding model (Xenova/bge-small-en-v1.5, quantized), downloaded once, loaded lazily on first call, and held resident for the server process's lifetime. No GPU or hosted inference service.
• Classification (type/topics/projectScoped) happens in the calling agent, not the server — capture_thought/update_thought's zod inputSchema in server.js (CLASSIFICATION_FIELDS) carries the taxonomy via field descriptions, and the tool description instructs the caller to fill them in from the conversation the thought came from. The caller only judges whether a thought is scoped to the current project (projectScoped, defaulting to false/global unless the rule is specific to the current working directory) — it never has to name the project itself; see withProjectStamp in server.js. There is no server-side classification step and no network call anywhere in the capture pipeline.
• db.js's listRules({ project }) — a plain deterministic SQL filter (project IS NULL OR project = ?), no embeddings, no LLM call. Backs the list_rules MCP tool — cheap enough to call on every turn.
• hooks/hooks.json — Codex SessionStart and PreToolUse lifecycle configuration. The first runs the same fixed-size instruction used by Claude Code; the second denies every other tool until the agent calls list_rules. This avoids placing a potentially truncated rule set in hook output and reuses the same marker state on both clients.
• bin/session-rules.js (SessionStart hook), bin/prompt-reminder.js (UserPromptSubmit hook), and bin/pre-tool-check.js (PreToolUse hook, matcher *) — see "Standing-rule hooks" below. None touch the database directly. session-rules.js emits a short, fixed-size instruction telling the model to call the list_rules MCP tool itself; embedding the rule content directly in hook output doesn't scale — a large enough stored rule set gets silently truncated to a small preview before it ever reaches the model. pre-tool-check.js is the enforcement layer: advisory instructions turned out to be ignorable in practice, so it denies any other tool call until list_rules has run this session, tracked by a marker file. The gate fires once per session, not once per turn — session-rules.js re-arms it (clears the marker) only after a compaction or /clear, the two events that drop the loaded rules from context. prompt-reminder.js no longer touches the gate at all; it just re-anchors, every turn, "follow the loaded conventions, and capture only durable rules intended to govern future sessions or repeated work." Task-specific directions, temporary choices, status/history, one-job commands, and descriptions of how an individual job was completed remain in conversation context. Each script has a .cmd sibling (session-rules.cmd, prompt-reminder.cmd, pre-tool-check.cmd) that Windows settings.json entries point at — see "Platform support" below.
• src/server.js — registers the seven MCP tools (capture_thought, update_thought, delete_thought, search_thoughts, list_thoughts, list_rules, thought_stats) and connects over stdio by default or localhost-only Streamable HTTP when MCP_TRANSPORT=http. update_thought is a real SQL UPDATE (preserves the row's id), not delete-then- reinsert — it re-embeds against the new content and takes fresh classification fields from the caller, then replaces the row's thoughts_vec entry in the same transaction (vec0 has no in-place UPDATE, so that part is delete+insert internally, unlike the thoughts/FTS side which is a real UPDATE synced by the existing trigger). withProjectStamp converts the caller's projectScoped boolean into a deterministic project field before storage — see src/project.js below for why that split exists. list_rules and list_thoughts render each row by its #id (list_rules ordered by id ascending), so the ids the user sees are exactly the ones they pass back to update_thought/delete_thought.
• src/project.js — getCurrentProject(cwd) derives a stable project id from the working directory: the absolute path with / turned into - (e.g. /var/www/html → -var-www-html), the same string Claude Code uses for the per-project transcript directory under ~/.claude/projects/. Used to stamp captures and to filter list_rules, so "which project" is a deterministic lookup rather than free-text matching against whatever string an LLM happened to write.
• bin/cli.js — the npm "bin" entry (package.json's "bin": { "conventions-mcp": "bin/cli.js" }), so an installed copy resolves on PATH with no path management needed. Dispatches by subcommand (init-db, backup, warmup, the two hook commands, or nothing → starts the MCP server) via dynamic import() of the same modules the npm run scripts already use — each does its work as a top-level side effect on import, so no refactor into exported functions was needed just for this. No config bootstrap step — nothing here requires a .env to exist.