{
  "markdown": "# conventions-mcp\n\nPersonal 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.\n\n## Why this one\n\nThere'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:\n\n- **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.\n- **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`: `SessionStart` supplies the instruction, while `PreToolUse` denies every other tool until the call has happened.\n- **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.\n- **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.\n- **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-Project` header. The project identifier is never guessed by an LLM from free text.\n\nIf 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.\n\n## What it's tuned to store\n\nEvery capture is classified into one of five types by the calling agent, guided by `capture_thought`'s tool description (`src/server.js`):\n\n| Type | What it means |\n|---|---|\n| `convention` | A specific coding style/pattern rule (e.g. \"always use 2-space indent\") |\n| `instruction` | A standing directive on how to work/behave (e.g. \"never force-push to main\") |\n| `correction` | A lasting correction to future behavior |\n| `preference` | A long-lived softer preference, not a hard rule |\n| `other` | Another durable, future-facing rule that does not fit the four specific types |\n\nEach 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.\n\nSeparately, every thought gets a **project** field — `null` by default (applies everywhere), or a specific project id if it's scoped to the current codebase. The calling agent only judges *whether* it's project-scoped (`projectScoped`); the actual project id is derived deterministically from the working directory — the absolute path with separators turned into dashes, e.g. `/var/www/html` → `-var-www-html`, matching the per-project directory name Claude Code itself uses under `~/.claude/projects/`. The model never names the project, so retrieval can do an exact match instead of fuzzy text comparison.\n\n- **Storage:** SQLite (`better-sqlite3`) + `sqlite-vec` for native vector search, FTS5 for keyword search, combined via reciprocal rank fusion. One file, no server, no daemon.\n- **Embeddings:** local, via `Xenova/bge-small-en-v1.5` (384-dim, quantized, ~130MB). Downloads once, loads lazily, and needs no GPU.\n- **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.\n- **Transport:** MCP over stdio by default, with an optional localhost-only Streamable HTTP mode for running it as a persistent service.\n- **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.\n- **Scoped retrieval:** `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.\n\n## Setup\n\nTwo 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).\n\n**Git checkout:**\n```bash\nnpm install\nnpm run init-db        # creates data/memory.db\n```\n\n**npm package:**\n```bash\nnpm install -g conventions-mcp\nconventions-mcp init-db    # creates ~/.conventions-mcp/memory.db\nconventions-mcp warmup     # downloads and verifies the embedding model\n```\n\nNothing to configure — there's no API key and no external service. `MEMORY_DB_PATH` is the only environment variable this reads, and it's optional (see `.env.example`).\n\n### Persistent local service\n\nUse Streamable HTTP when the MCP client should connect to one boot-managed\nserver instead of launching a stdio child for every session:\n\n```bash\nMCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=47123 conventions-mcp\n```\n\nRun that command under the operating system's service manager and configure\nthe MCP client with `http://127.0.0.1:47123/mcp`. See\n[`docs/shared-service.md`](docs/shared-service.md) for complete systemd,\nlaunchd, and Windows setup and verification instructions. The server rejects\nnon-local host headers when bound to localhost. `MCP_HTTP_HOST` defaults to\n`127.0.0.1` and `MCP_HTTP_PORT` defaults to `47123`.\n\nHTTP clients that support MCP roots need no additional project configuration.\nFor clients that do not, set `X-Conventions-Project` to the absolute project\npath in project-local MCP configuration. An HTTP session without either value\nreceives global rules only and cannot create a project-scoped capture, which\nprevents one project's rules from leaking into another project.\n\nCodex can supply the active workspace to a shared HTTP server dynamically:\n\n```toml\n[mcp_servers.conventions]\nurl = \"http://127.0.0.1:47123/mcp\"\nhttp_headers_helper = \"conventions-mcp codex-project-header\"\n```\n\nCodex runs the helper in the active workspace. The server converts that\nabsolute path to its project identifier, so `/var/www/html` becomes\n`-var-www-html`.\n\n## Register with Claude Code\n\nRegister 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:\n\n```bash\n# Git checkout — an absolute path, since Claude Code may spawn this from an\n# arbitrary working directory:\nclaude mcp add --scope user conventions -- node /absolute/path/to/conventions-mcp/src/server.js\n\n# npm package — already on PATH:\nclaude mcp add --scope user conventions -- conventions-mcp\n```\n\nEither 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.\n\n## Codex standing-rule hook\n\n`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 after `/clear` and compaction, when the loaded rules leave context. 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.\n\nInstall 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.\n\n## Claude Code standing-rule hooks\n\nThree hooks in `~/.claude/settings.json` enforce `list_rules` before tool use — the first two provide reminders, the third actually enforces it:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"node /absolute/path/to/conventions-mcp/bin/session-rules.js\", \"timeout\": 15 }] }\n    ],\n    \"UserPromptSubmit\": [\n      { \"hooks\": [{ \"type\": \"command\", \"command\": \"node /absolute/path/to/conventions-mcp/bin/prompt-reminder.js\", \"timeout\": 5 }] }\n    ],\n    \"PreToolUse\": [\n      { \"matcher\": \"*\", \"hooks\": [{ \"type\": \"command\", \"command\": \"node /absolute/path/to/conventions-mcp/bin/pre-tool-check.js\", \"timeout\": 5 }] }\n    ]\n  }\n}\n```\n\n- `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). It also re-arms the enforcement gate after a compaction or `/clear` (the two events that drop the already-loaded rules from context), so a reload is forced then too.\n- `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.\n- `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.\n\nNone 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.\n\n**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.\n\n**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.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `capture_thought` | Save a convention, instruction, correction, or preference. Embeds locally; classification is provided by the calling agent. |\n| `update_thought` | Correct/refine an existing thought in place — same id, re-embedded and re-tagged from the new content. |\n| `search_thoughts` | Hybrid semantic + keyword search. |\n| `list_thoughts` | List all captures, optionally filtered by type. |\n| `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. |\n| `thought_stats` | Totals, type breakdown, top topics, and per-project counts. |\n| `delete_thought` | Permanently delete a thought by id. |\n\n## Notes\n\n- 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.\n- 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`](docs/shared-service.md) shows a scheduled setup.\n- To upgrade embedding quality later without re-architecting, swap `MODEL_NAME` in `src/embeddings.js` — but re-embed existing thoughts if the new model's vector space isn't compatible with the old one (different models' embeddings aren't comparable, even at the same dimension).\n",
  "bytes": 13972,
  "sha": "50710ff24253db405ed5d60074c11d46c74e935c65fbaf2b39d4f5461037dcc0",
  "repo_slug": "fedgeno/conventions-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fedgeno_conventions_mcp_366fc188/readme"
}