conventions-mcp: Instructions file for Claude Code

AGENTS.md — 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 any coding agent working on the server's own code, plus client-specific instructions for wiring the finished server into supported clients.

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. Existing database parents must already be private; never chmod a caller's shared directory automatically. Backup and restore staging files are created exclusively with mode 0600 before SQLite writes any records. app_metadata records the storage schema, embedding model, and dimension. Unknown non-empty legacy stores are rejected until migrate-storage creates a verified backup and re-embeds every row; declared incompatible formats are never silently adopted. restoreDatabase requires a stopped service (no WAL/SHM sidecars), validates the source and current-format metadata, makes a non-overwriting online rollback backup, stages the source beside the live database, and uses same-filesystem renames with rollback on publication failure. Source staging uses SQLite's backup API so committed source WAL records are included. Initialization caches a connection only after schema/format checks succeed, and closes failed connections on every error path.
• 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; optional database, model-cache, transport, and timeout settings are listed in .env.example.
• 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. Its cache is persistent at ~/.conventions-mcp/models unless MEMORY_MODEL_CACHE_PATH overrides it, rather than living inside an npm installation that upgrades may replace. No GPU or hosted inference service. Concurrent callers share initialization; a rejected initialization is cleared so a later call can retry without restarting the process. The tracked .npmrc sets onnxruntime-node-install-cuda=skip; do not remove it unless GPU inference is deliberately implemented and tested, because ONNX Runtime otherwise downloads an unused CUDA artifact on Linux x64.
• 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 start, not once per turn — session-rules.js re-arms it on every start, resume, compaction, or /clear, including when a resumed conversation retains an earlier rule load. 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. HTTP exposes a database-backed /healthz readiness check and bounds retained sessions with MCP_HTTP_MAX_SESSIONS and MCP_HTTP_SESSION_IDLE_MS. Both transports use src/shutdown.js to bound graceful cleanup with MCP_SHUTDOWN_TIMEOUT_MS; failures are logged and set a failing process status while database cleanup is still attempted. 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. createConventionsServer and runHTTPServer accept an optional embedding function for deterministic tests; production entry points always use the real local model. HTTP integration tests must inject a 384-value embedding rather than downloading the model, so the suite is reproducible offline. HTTP startup must reject listener errors rather than reporting success. Unknown or expired session IDs return HTTP 404 to signal reinitialization; missing required session IDs return HTTP 400. Active tool calls suspend idle expiry. Shutdown drains both handlers and HTTP responses before closing transports; forced closure cancels pending writes. Roots resolution has a one-second deadline and caches the scope until a roots-change notification, or for 30 seconds after a failed lookup.
• src/project.js — getCurrentProject(cwd) derives a stable project id from the normalized absolute path prefixed by path:, preserving separators. Legacy hyphen-based IDs require explicit migrate-project ownership assignment with a verified backup; never infer ownership of a colliding ID. 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, doctor, codex-project-header, the two hook commands, --help, --version, 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. codex-project-header prints the current working directory as the X-Conventions-Project JSON header expected by Codex's http_headers_helper. No config bootstrap step — nothing here requires a .env to exist.
• src/doctor.js — non-downloading operational diagnostics used by the doctor CLI command. It checks the supported Node.js floor, opens and quick-checks SQLite, verifies the vec0 table and data permissions, and reports whether the configured model cache looks complete. A missing model is a warning; runtime/storage failures make the command exit nonzero.