The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Conventions MCP listing page.
Personal memory for durable coding conventions and standing instructions — one store, any MCP-compatible AI client, available in every project. It holds rules like "always use 2-space indent in this language," "never force-push to main," lasting corrections, and long-lived workflow preferences that should carry across future sessions rather than get re-explained every time. It is deliberately not a history of individual jobs or a place for task-specific directions, temporary decisions, current status, or one-off commands.
There's no shortage of memory MCP servers — several well-established ones (mem0/OpenMemory, Zep/Graphiti, the official reference memory server, plus a long tail of smaller projects) already do "remember things across sessions." What's different here:
list_rules: SessionStart supplies the instruction, while PreToolUse denies every other tool until the call has happened.conventions-mcp warmup) and then runs locally. Classification (type/topics/projectScoped) is done by the calling agent at capture time, guided by the tool description — it already has the full conversation the thought came from, richer context than an isolated content string would give a separate extractor model.X-Conventions-Project header. The project identifier is never guessed by an LLM from free text.If what you want is a general-purpose "remember everything" store, or you're not on Claude Code and don't need the hook-driven determinism, one of the more general options above may fit better. This one is for someone who specifically wants a tight, coding-convention-focused memory that stays accurate and doesn't require trusting the model to remember to check it.
Every capture is classified into one of five types by the calling agent, guided by capture_thought's tool description (src/server.js):
| Type | What it means |
|---|---|
convention | A specific coding style/pattern rule (e.g. "always use 2-space indent") |
instruction | A standing directive on how to work/behave (e.g. "never force-push to main") |
correction | A lasting correction to future behavior |
preference | A long-lived softer preference, not a hard rule |
other | Another durable, future-facing rule that does not fit the four specific types |
Each thought also gets 1–3 topic tags for filtering. This is deliberately narrow — it's not a general note-taking store — but the taxonomy isn't hardcoded logic, it's just the wording of the tool description and its zod schema in src/server.js. Retuning what counts as a convention vs. an instruction, or adding a new type, is a matter of editing that description text, not restructuring the code. The one wrinkle: the five type names are also referenced in the type filter's enum in list_thoughts (src/server.js) — if you rename or add a type, update that enum too or the new type will get rejected as a filter value. Everything's stored as a JSON blob column, so none of this needs a schema migration.
Every thought gets a project field: null applies everywhere; otherwise it
is the normalized absolute path prefixed by path:. Separators are preserved,
so /work/a-b and /work/a/b identify different projects. The calling agent
only decides whether a rule is project-scoped. Existing hyphen-based IDs
require the explicit, backup-first project migration in upgrading.md.
better-sqlite3) + sqlite-vec for native vector search, FTS5 for keyword search, combined via reciprocal rank fusion. One file, no server, no daemon.Xenova/bge-small-en-v1.5 (384-dim, quantized, ~130MB). Downloads once to ~/.conventions-mcp/models, loads lazily, and needs no GPU.list_rules and semantic search return global rules plus the current project's rules; project-specific rules from other codebases stay out of normal retrieval. list_thoughts remains the explicit all-records management view.Installing with an AI coding agent? Give it this repository and ask it to follow the canonical installation and client-integration runbook. The runbook requires path discovery, config merging rather than overwriting, a real capture/list/delete acceptance test, and cleanup of the test record.
Two ways to get this: a git checkout (if you want to read/modify the source) or the npm package (if you just want it running).
Git checkout:
npm package:
No API key or external service is required. Optional database, model-cache,
transport, and timeout settings are listed in .env.example.
Use conventions-mcp --help to inspect the installed commands and
conventions-mcp --version to confirm which release is on PATH. See
SECURITY.md for the local trust model and private reporting
instructions.
Run conventions-mcp doctor for a non-downloading runtime, database, permission,
vector-extension, and model-cache readiness report.
Legacy databases without format metadata require the backup-first
conventions-mcp migrate-storage <absolute-backup-path> command; declared
incompatible formats are rejected rather than guessed.
Use Streamable HTTP when the MCP client should connect to one boot-managed server instead of launching a stdio child for every session:
Run that command under the operating system's service manager and configure
the MCP client with http://127.0.0.1:47123/mcp. See
docs/shared-service.md for complete systemd,
launchd, and Windows setup and verification instructions. The server rejects
non-local host headers when bound to localhost. MCP_HTTP_HOST defaults to
127.0.0.1 and MCP_HTTP_PORT defaults to 47123.
The service exposes GET /healthz for loopback readiness checks and bounds
retained sessions with MCP_HTTP_MAX_SESSIONS (default 100) and
MCP_HTTP_SESSION_IDLE_MS (default 30 minutes).
HTTP clients that support MCP roots need no additional project configuration.
For clients that do not, set X-Conventions-Project to the absolute project
path in project-local MCP configuration. An HTTP session without either value
receives global rules only and cannot create a project-scoped capture, which
prevents one project's rules from leaking into another project.
Codex can supply the active workspace to a shared HTTP server dynamically:
Codex runs the helper in the active workspace. The server normalizes that
absolute path and prefixes it with path: for its project identifier.
Register at user scope so it's available in every project, not just one repo — use the claude mcp add CLI, not a hand-edited config file:
Either way, this writes to ~/.claude.json's mcpServers key, which is what the CLI actually reads; a mcpServers entry placed directly in ~/.claude/settings.json is silently inert. Verify with claude mcp list. A new Claude Code session is required to pick up a newly-registered server.
hooks/hooks.json contains user-scoped Codex SessionStart and PreToolUse hooks. The first tells the agent to call list_rules; the second denies every other tool until that call happens. The gate is re-armed on every start, resume, /clear, and compaction, even if the restored conversation contains an earlier rule load. The rules themselves are not placed in hook output, so a large rule set cannot be truncated before the agent receives it from the MCP tool.
Install it as ~/.codex/hooks.json. If that file already contains hooks, merge this file's SessionStart and PreToolUse entries instead of replacing the existing configuration. The hook expects the MCP server to be registered as conventions, matching the setup command above, and the installed conventions-mcp command to be on PATH. Open /hooks once in Codex to review and trust the newly installed hooks; a new session is required before a startup hook can fire.
Checkout users can invoke the absolute Node executable and bin/cli.js path
for Codex hooks too; see installation. A global npm copy is
not required. Hook gates unlock on an attempted list_rules call, including a
failed call; the calling agent must still handle failures and obtain the rules.
Three hooks in ~/.claude/settings.json enforce list_rules before tool use — the first two provide reminders, the third actually enforces it:
bin/session-rules.js fires at session start and emits a short reminder to call list_rules first — rather than embedding rule content in the hook output directly, which doesn't scale (a large enough stored rule set gets silently truncated to a small preview before it ever reaches the model). Every invocation re-arms the enforcement gate, including resume, compaction, and /clear, so an earlier load cannot bypass the new instruction.bin/prompt-reminder.js fires on every turn with a static reminder to follow the loaded conventions and to capture only genuinely durable rules intended for future sessions or repeated work. It explicitly excludes task-specific directions, temporary choices, current status, incident history, one-job commands, and records of how an individual job was completed.bin/pre-tool-check.js fires before every tool call and denies it outright until list_rules has run this session — the first two hooks are advisory (reminders only), so this is the layer that actually enforces the requirement. It's forced once per session, not once per turn.None of the three touch the database directly. list_rules resolves the current project from the stdio working directory, an MCP root, or the HTTP project's X-Conventions-Project header.
npm package: the scripts live inside the global install rather than a known clone path — resolve it first with npm root -g, then point the hook at $(npm root -g)/conventions-mcp/bin/session-rules.js the same way.
Windows: point the command at the .cmd wrapper instead of the .js file directly (no node prefix — the batch file invokes it) — bin\session-rules.cmd / bin\prompt-reminder.cmd / bin\pre-tool-check.cmd for a git checkout, or the equivalent path under npm root -g for the npm package.
| Tool | Description |
|---|---|
capture_thought | Save a convention, instruction, correction, or preference. Embeds locally; classification is provided by the calling agent. |
update_thought | Correct/refine an existing thought in place — same id, re-embedded and re-tagged from the new content. |
search_thoughts | Hybrid semantic + keyword search. |
list_thoughts | List all captures, optionally filtered by type. |
list_rules | Every global + current-project rule in one deterministic call — no embeddings, no ranking, ordered by id. What the hooks use under the hood. |
thought_stats | Totals, type breakdown, top topics, and per-project counts. |
delete_thought | Permanently delete a thought by id. |
Follow docs/upgrading.md for backup-first upgrades,
legacy vector migration, guarded restore, and rollback.
If a single message states several distinct rules, capture_thought gets called once per rule, each relayed individually — not merged into one capture or summarized together.
The database lives at data/memory.db in a git checkout, or ~/.conventions-mcp/memory.db for the npm package (override either with MEMORY_DB_PATH). It's gitignored and created with private permissions. Use conventions-mcp backup <absolute-destination> for a live-safe, integrity-checked backup. docs/shared-service.md shows a scheduled setup.
The embedding model and dimension are declared in src/storage-format.js.
A model change requires an explicit storage migration that re-embeds existing
rules; changing the constant alone makes existing stores incompatible.