conventions-mcp
This server is a personal, local memory store for durable coding conventions and standing rules, shared across any MCP-compatible AI client.
Capture rules —
capture_thoughtsaves conventions, standing instructions, corrections, and preferences, each classified bytype(convention/instruction/correction/preference/other),scope(language/framework/topic or global), 1–3topics, andprojectSpecific; multiple distinct rules in one message are captured separately and echoed back verbatim for verification.Correct in place —
update_thoughtrefines an existing thought by id, re-embedding and re-tagging it while keeping the same id and capture date.Remove —
delete_thoughtpermanently deletes a thought by id (only on explicit user request, with confirmation).Hybrid search —
search_thoughtsfinds stored rules by meaning plus exact keyword match (semantic + FTS5 with reciprocal rank fusion).Browse and filter —
list_thoughtslists recent captures, optionally filtered bytypeand recency in days.Deterministic rule loading —
list_rulesreturns every applicable global plus current-project rule in one ordered call, with no embeddings or ranking, so nothing is missed; this is what the Codex/Claude Code hooks enforce before other tools.Stats —
thought_statssummarizes totals, type breakdown, top topics, and per-project/scope counts.Scoped retrieval — project-specific rules stay out of other projects' retrieval, with project identity derived from working directory, MCP roots, or an
X-Conventions-Projectheader rather than guessed by an LLM.Fully local runtime — SQLite storage with local embeddings, no API key, no hosted service; usable over stdio or a localhost-only HTTP service.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@conventions-mcp capture convention: always use 2-space indentation for JavaScript"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Superseded — No Longer Maintained
This project has been superseded by the Cloudflare Worker version of Conventions MCP and its companion client. Use those repositories for new installations and follow their setup guides to deploy your own server. This original version is no longer maintained.
conventions-mcp
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.
Why this one
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:
Narrow taxonomy, not a general note-taking store. Every capture must be a durable rule for future work and gets classified into one of five purpose-built types — convention, instruction, correction, preference, other — plus a project field and topic tags. Task-specific procedures and work history are excluded so retrieval stays precise instead of noisy.
Deterministic retrieval, not best-effort. Most memory MCPs rely entirely on the calling model noticing a tool description is relevant and deciding to call it — which fails silently and inconsistently. Codex and Claude Code hooks force the agent to call
list_rules:SessionStartsupplies the instruction, whilePreToolUsedenies every other tool until the call has happened.Transparent by default, not silent. Every capture and update echoes the verbatim stored content and whether it's global or project-scoped back immediately, so a misheard or misclassified rule is visible and correctable on the spot — not something you discover three sessions later via search.
Fully local at runtime. SQLite + local embeddings, no hosted service, no per-token costs, no API key. The embedding model is downloaded once on first use (or explicitly with
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.Project-scoped without fuzzy matching. A rule can be global (the default) or tied to one specific codebase. Stdio clients derive the project from their working directory; HTTP clients provide an MCP root or an
X-Conventions-Projectheader. 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.
Related MCP server: project-brain-mcp
What it's tuned to store
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 |
| A specific coding style/pattern rule (e.g. "always use 2-space indent") |
| A standing directive on how to work/behave (e.g. "never force-push to main") |
| A lasting correction to future behavior |
| A long-lived softer preference, not a hard rule |
| 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.
Storage: SQLite (
better-sqlite3) +sqlite-vecfor native vector search, FTS5 for keyword search, combined via reciprocal rank fusion. One file, no server, no daemon.Embeddings: local, via
Xenova/bge-small-en-v1.5(384-dim, quantized, ~130MB). Downloads once to~/.conventions-mcp/models, loads lazily, and needs no GPU.Classification: done by the calling agent (Claude Code, or any MCP client) at capture time, guided by the tool description — no network call, no external model, no API key.
Transport: MCP over stdio by default, with an optional localhost-only Streamable HTTP mode for running it as a persistent service.
Proactive retrieval: Codex and Claude Code hooks (see below) load or enforce standing rules at every context boundary — no project instruction file to keep in sync, no dependence on the model happening to notice a tool description is relevant.
Scoped retrieval:
list_rulesand semantic search return global rules plus the current project's rules; project-specific rules from other codebases stay out of normal retrieval.list_thoughtsremains the explicit all-records management view.
Setup
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 install
npm run init-db # creates data/memory.dbnpm package:
npm install -g conventions-mcp --onnxruntime-node-install-cuda=skip
conventions-mcp init-db # creates ~/.conventions-mcp/memory.db
conventions-mcp warmup # downloads and verifies the embedding modelNo 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.
Persistent local service
Use Streamable HTTP when the MCP client should connect to one boot-managed server instead of launching a stdio child for every session:
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=47123 conventions-mcpRun 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:
[mcp_servers.conventions]
url = "http://127.0.0.1:47123/mcp"
http_headers_helper = "conventions-mcp codex-project-header"Codex runs the helper in the active workspace. The server normalizes that
absolute path and prefixes it with path: for its project identifier.
Register with Claude Code
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:
# Git checkout — an absolute path, since Claude Code may spawn this from an
# arbitrary working directory:
claude mcp add --scope user conventions -- node /absolute/path/to/conventions-mcp/src/server.js
# npm package — already on PATH:
claude mcp add --scope user conventions -- conventions-mcpEither 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.
Codex standing-rule hook
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.
Claude Code standing-rule hooks
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:
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/session-rules.js", "timeout": 15 }] }
],
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/prompt-reminder.js", "timeout": 5 }] }
],
"PreToolUse": [
{ "matcher": "*", "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/pre-tool-check.js", "timeout": 5 }] }
]
}
}bin/session-rules.jsfires at session start and emits a short reminder to calllist_rulesfirst — 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.jsfires 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.jsfires before every tool call and denies it outright untillist_ruleshas 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.
Tools
Tool | Description |
| Save a convention, instruction, correction, or preference. Embeds locally; classification is provided by the calling agent. |
| Correct/refine an existing thought in place — same id, re-embedded and re-tagged from the new content. |
| Hybrid semantic + keyword search. |
| List all captures, optionally filtered by type. |
| Every global + current-project rule in one deterministic call — no embeddings, no ranking, ordered by id. What the hooks use under the hood. |
| Totals, type breakdown, top topics, and per-project counts. |
| Permanently delete a thought by id. |
Notes
Follow
docs/upgrading.mdfor backup-first upgrades, legacy vector migration, guarded restore, and rollback.If a single message states several distinct rules,
capture_thoughtgets called once per rule, each relayed individually — not merged into one capture or summarized together.The database lives at
data/memory.dbin a git checkout, or~/.conventions-mcp/memory.dbfor the npm package (override either withMEMORY_DB_PATH). It's gitignored and created with private permissions. Useconventions-mcp backup <absolute-destination>for a live-safe, integrity-checked backup.docs/shared-service.mdshows 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.
Available Tools
4 toolscapture_thoughtCapture Convention or InstructionA
Save a coding convention, standing instruction, correction, or workflow preference for future reference — e.g. style rules ('always use 2-space indent'), standing directives ('never force-push to main'), a correction after getting something wrong, or a stated preference for how work should be done. Call this whenever the user states a rule or preference for how you should work, corrects your approach, or explicitly asks you to remember something — don't wait to be asked to 'save' it. Occasional non-coding notes are fine too, but this store is primarily for conventions and instructions that should carry across future sessions and projects. Classify it yourself using the type/scope/topics/projectSpecific fields below, based on the conversation the thought came from. If a single message states multiple distinct rules, call this once per rule — don't merge them into one capture — and relay each one individually the same as a single capture, not summarized together. After every successful call, state the captured content verbatim and its scope back to the user (the response text already contains both) — this is how they catch a misinterpreted rule and correct or delete it immediately, rather than discovering it wrong much later.
Inputs: type (required), scope (required), topics (required), content (required), +1 more.
delete_thoughtDelete a Captured ThoughtA
Permanently delete a specific captured thought by its ID. This is destructive and irreversible — no undo, no trash. Only call this when the user explicitly asks to delete, remove, or forget a specific thought. Never call it proactively, as a side effect of another action, or on a guess at which ID they mean — if the ID isn't already known from context, use search_thoughts or list_thoughts first and confirm with the user which one before deleting.
Inputs: id (required).
search_thoughtsSearch Conventions and InstructionsA
Look up previously stored coding conventions, standing instructions, and preferences, by meaning and by exact keyword match (hybrid search). Call this proactively before starting unfamiliar coding work, or when uncertain about a style/convention choice in a project — don't wait for the user to ask. Also call it when the user references a past preference or rule ('like we discussed', 'the usual way', 'you know how I like it').
Inputs: query (required), limit.
thought_statsThought StatisticsA
Get a summary of everything captured: totals, types, top topics, and scopes (which languages/projects/contexts have the most stored conventions).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: capture saves new thoughts, deletes removes by ID, search retrieves by meaning/keyword, and stats provides an overview. No overlap in functionality.
Three tools use verb_noun pattern (capture_thought, delete_thought, search_thoughts) while thought_stats uses noun_verb, but all consistently include 'thought' as the base noun, making them readable.
Four tools is a reasonable count for a convention management server. It covers creation, deletion, search, and statistics without being excessive.
Missing update functionality for existing thoughts; users can only delete and recapture. Also lacks a 'list all' tool, though search can approximate it. The gaps may force agents to work around them.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
An MCP memory server. One memory your agents share — across models, devices and apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that provides persistent memory and contextual awareness to language models, enabling project onboarding, recall of architectural rules, and code consistency across sessions.32MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides CLI coding agents with persistent decision memory, codebase dependency-graph awareness, plan validation against architectural constraints, and a self-bootstrapping constraints.md file.MIT
- AlicenseBqualityBmaintenanceA stateful MCP server that provides persistent memory, deterministic static analysis, and evolving conventions for AI coding assistants.14MIT
- FlicenseNot gradedqualityBmaintenanceA local, cross-editor MCP server that provides persistent memory for coding agents, capturing and recalling decisions, conventions, and fixes across sessions without API keys.-