{
  "markdown": "![Verified Repo Memory Banner](assets/banner.png)\n\n# Verified Repo Memory MCP v0.1.2\n\n[![CI](https://github.com/cognitivemyriad/mcp-verified-repo-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/cognitivemyriad/mcp-verified-repo-memory/actions/workflows/ci.yml)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7.0-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nStale-proof repository memory with citations + just-in-time verification + TTL (repo-scoped).\n\nAn MCP server providing \"safe memory\" for AI coding agents. Memories are scoped per repository, backed by code citations, and verified just-in-time so an agent never receives stale information when the underlying code has changed.\n\n## Quickstart\n\nRun via `npx`:\n\n```bash\nnpx -y @cognitivemyriad/vrm-local --repo /path/to/repo\n```\n\n*(Alternatively, run from source: `npm ci && npm run build && node build/index.js --repo /path/to/repo`)*\n\n## Tools\n\n* **`vrm_store`**: Store a new memory with file citations.\n* **`vrm_search`**: Search for candidate memories by keywords.\n* **`vrm_retrieve`**: JIT-verify candidates and return only valid memories. (Main tool for agents)\n* **`vrm_list`**: List memories by status (valid, stale, missing).\n* **`vrm_forget`**: Manually delete a memory.\n\n### Example I/O\n\n**Store:**\nInput:\n```json\n{\n  \"subject\": \"API version sync\",\n  \"fact\": \"When changing API version, update client/server/docs together.\",\n  \"citations\": [{ \"path\": \"src/api.ts\", \"startLine\": 10, \"endLine\": 15 }]\n}\n```\nOutput:\n```json\n{\n  \"stored\": true,\n  \"memoryId\": \"uuid-...\",\n  \"expiresAt\": \"2026-03-21T00:00:00Z\"\n}\n```\n\n**Retrieve:**\nInput:\n```json\n{ \"query\": \"API version\" }\n```\nOutput:\n```json\n{\n  \"query\": \"API version\",\n  \"valid\": [ ... ],\n  \"stats\": { \"verified\": 1, \"validCount\": 1 }\n}\n```\n\n## How it works\n\n```mermaid\ngraph TD\n    A[Agent] -->|Store Fact + Citation| B(Verified Repo Memory)\n    B --> C{Save to Disk}\n    C -->|Hash Code Snippet| D[(memories.json)]\n    \n    A -->|Retrieve Fact| B\n    B --> E{JIT Verification}\n    E -->|Check File Hash| F{Unchanged or Relocated?}\n    F -->|Yes| G[Return VALID Memory]\n    F -->|No| H[Return STALE/MISSING]\n```\n\n1. **Citations:** Every fact is linked to a file path and a line range. The exact code snippet is hashed and saved.\n2. **JIT Verification:** Before returning a memory to the agent in `vrm_retrieve`, the server checks the physical file. If the snippet has moved, it relocates the citation. If it has been changed or deleted, the memory is marked STALE/MISSING and omitted from the results.\n3. **TTL (Time-To-Live):** Memories expire automatically (default 28 days) unless they are successfully retrieved and utilized, which extends their life.\n\n## Data location\n\nData is strictly repo-scoped and saved in:\n`<repoRoot>/.verified-repo-memory`\n\nThis includes `memories.json` and a fingerprint/metadata file to prevent accidental cross-repo pollution. Add this directory to your `.gitignore`.\n\n## Security\n\n* **No Network Transmissions:** This is a `stdio` local-only server without HTTP calls.\n* **Path Security:** Disallows any path traversal (`../`) out of the repository root, as well as accessing `.git/` or `.verified-repo-memory/`.\n* **No Stdout Pollution:** Strict logging only to `stderr`.\n* **Secret Scan:** Built-in heuristic secret scanning to reject memories that look like API keys/private keys (can be disabled via `--no-secret-scan`).\n\n## Usage with Claude\n\n### Claude Desktop\nTo add this server to the Claude Desktop app, edit your configuration file:\n- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- On Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd the following configuration:\n```json\n{\n  \"mcpServers\": {\n    \"verified-repo-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@cognitivemyriad/vrm-local\",\n        \"--repo\",\n        \"/absolute/path/to/your/repo\"\n      ]\n    }\n  }\n}\n```\n\n### Claude Code\nTo add this server to Claude Code using `stdio` transport:\n\n```bash\nclaude mcp add mcp-verified-repo-memory --transport stdio -- npx -y @cognitivemyriad/vrm-local\n```\n\n*Note for Windows users:* You may need to prepend `cmd /c` to the command:\n```bash\nclaude mcp add mcp-verified-repo-memory --transport stdio -- cmd /c npx -y @cognitivemyriad/vrm-local\n```\n\n---\n\n## Publishing Guide\n\nThis section explains how to publish the package to **NPM** and register it with the **Anthropic MCP Registry** so that it becomes publicly available.\n\n### Step 1: Publish to NPM\n\nNPM (Node Package Manager) is the package distribution platform. Publishing here allows anyone to install your tool with a single command.\n\n#### Prerequisites\n\n- An [NPM account](https://www.npmjs.com/signup) (free)\n- Two-factor authentication (2FA) enabled on your NPM account\n- Node.js installed on your machine\n\n#### Procedure\n\n**1. Log in to NPM from the terminal:**\n\n```bash\nnpm login\n```\n\nA browser window will open. Sign in with your NPM account. When prompted, enter your 2FA code from your authenticator app.\n\n**2. Publish the package:**\n\n```bash\nnpm publish --access public\n```\n\nThis command does the following:\n- Compiles TypeScript → JavaScript (`npm run build`)\n- Creates a `.tgz` archive of the compiled files\n- Uploads the archive to `https://registry.npmjs.org/`\n\n**3. Verify the publication:**\n\nVisit `https://www.npmjs.com/package/@cognitivemyriad/vrm-local` in your browser. Your package page should appear.\n\n> **Note:** If you need to re-publish, you must increment the version number in `package.json` and `server.json` first (`npm version patch`). NPM does not allow overwriting existing versions.\n\n---\n\n### Step 2: Register with Anthropic MCP Registry\n\nThe [MCP Registry](https://registry.modelcontextprotocol.io) is Anthropic's official directory of MCP servers. Registering here allows Claude Desktop, Claude Code, and other MCP clients to discover and install your server.\n\n> **Important:** The NPM package **must be published first** (Step 1). The MCP Registry validates that the NPM package exists before accepting the registration.\n\n#### Prerequisites\n\n- A [GitHub account](https://github.com) (used for authentication only)\n- The `mcp-publisher` CLI tool\n\n#### Installing mcp-publisher\n\n```bash\n# macOS (Homebrew)\nbrew install nicholasgriffintn/tap/mcp-publisher\n\n# Or via npx (no install required)\nnpx @anthropic-ai/mcp-publisher\n```\n\n#### Procedure\n\n**1. Log in to the MCP Registry via GitHub:**\n\n```bash\nmcp-publisher login github\n```\n\nA browser window will open. Authorize the application with your GitHub account.\n\n**2. Publish to the MCP Registry:**\n\n```bash\nmcp-publisher publish\n```\n\nThis command reads `server.json` in the current directory and registers the server with the MCP Registry. The registry will:\n- Validate the `server.json` schema\n- Check that the NPM package exists and is accessible\n- Register the server metadata (name, description, version, environment variables)\n\n**3. Verify the registration:**\n\nVisit `https://registry.modelcontextprotocol.io` and search for your server name.\n\n> **Note:** Once a version is published to the MCP Registry, it is **immutable** and cannot be changed. To publish updates, increment the version in both `package.json` and `server.json`, publish to NPM first, then run `mcp-publisher publish` again.\n\n---\n\n### Version Management\n\nWhen releasing a new version, always update the version number in **all three locations**:\n\n```bash\n# 1. Bump version in package.json\nnpm version patch  # 0.1.2 → 0.1.3\n\n# 2. Update server.json (both top-level and packages[].version)\n# Edit server.json manually to match the new version\n\n# 3. Publish\nnpm publish --access public\nmcp-publisher publish\n```\n\n| File | Field | Must Match |\n|------|-------|-----------|\n| `package.json` | `version` | ✅ |\n| `server.json` | `version` (top-level) | ✅ |\n| `server.json` | `packages[0].version` | ✅ |\n",
  "bytes": 7964,
  "sha": "4dc42fa7501fc12b23d15963bf3fde0bed67deb5d5a3067a396a357b51caf37d",
  "repo_slug": "cognitivemyriad/mcp-verified-repo-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cognitivemyriad_verified_repo__55338b88/readme"
}