Skip to main content
Glama

Verified Repo Memory Banner

Verified Repo Memory MCP v0.1.0

CI TypeScript License: MIT

Stale-proof repository memory with citations + just-in-time verification + TTL (repo-scoped).

An 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.

Quickstart

Run via npx:

npx -y vrm-local --repo /path/to/repo

Tools

  • vrm_store: Store a new memory with file citations.

  • vrm_search: Search for candidate memories by keywords.

  • vrm_retrieve: JIT-verify candidates and return only valid memories. (Main tool for agents)

  • vrm_list: List memories by status (valid, stale, missing).

  • vrm_forget: Manually delete a memory.

Example I/O

Store: Input:

{
  "subject": "API version sync",
  "fact": "When changing API version, update client/server/docs together.",
  "citations": [{ "path": "src/api.ts", "startLine": 10, "endLine": 15 }]
}

Output:

{
  "stored": true,
  "memoryId": "uuid-...",
  "expiresAt": "2026-03-21T00:00:00Z"
}

Retrieve: Input:

{ "query": "API version" }

Output:

{
  "query": "API version",
  "valid": [ ... ],
  "stats": { "verified": 1, "validCount": 1 }
}

How it works

graph TD
    A[Agent] -->|Store Fact + Citation| B(Verified Repo Memory)
    B --> C{Save to Disk}
    C -->|Hash Code Snippet| D[(memories.json)]
    
    A -->|Retrieve Fact| B
    B --> E{JIT Verification}
    E -->|Check File Hash| F{Unchanged or Relocated?}
    F -->|Yes| G[Return VALID Memory]
    F -->|No| H[Return STALE/MISSING]
  1. Citations: Every fact is linked to a file path and a line range. The exact code snippet is hashed and saved.

  2. 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.

  3. TTL (Time-To-Live): Memories expire automatically (default 28 days) unless they are successfully retrieved and utilized, which extends their life.

Data location

Data is strictly repo-scoped and saved in: <repoRoot>/.verified-repo-memory/

This includes memories.json and a fingerprint/metadata file to prevent accidental cross-repo pollution. Add this directory to your .gitignore.

Security

  • No Network Transmissions: This is a stdio local-only server without HTTP calls.

  • Path Security: Disallows any path traversal (../) out of the repository root, as well as accessing .git/ or .verified-repo-memory/.

  • No Stdout Pollution: Strict logging only to stderr.

  • Secret Scan: Built-in heuristic secret scanning to reject memories that look like API keys/private keys (can be disabled via --no-secret-scan).

Usage with Claude

Claude Desktop

To add this server to the Claude Desktop app, edit your configuration file:

  • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "verified-repo-memory": {
      "command": "npx",
      "args": [
        "-y",
        "vrm-local",
        "--repo",
        "/absolute/path/to/your/repo"
      ]
    }
  }
}

Claude Code

To add this server to Claude Code using stdio transport:

claude mcp add mcp-verified-repo-memory --transport stdio -- npx -y vrm-local

Note for Windows users: You may need to prepend cmd /c to the command:

claude mcp add mcp-verified-repo-memory --transport stdio -- cmd /c npx -y vrm-local

Publishing to MCP Registry

To publish this server to the official registry:

  1. Initialize publisher: npx @modelcontextprotocol/publisher init

  2. Login: npx @modelcontextprotocol/publisher login github

  3. Publish: npx @modelcontextprotocol/publisher publish

Note: Once published, the version in server.json is immutable and cannot be changed for that release.

Available Tools

5 tools
vrm_forgetA

Manually delete a memory by ID.

Inputs: memoryId (required), hardDelete.

vrm_listC

List memories by status.

Inputs: status, limit, verify.

vrm_retrieveC

JIT-verify candidates and return valid memories.

Inputs: query (required), limit, includeStale, touch.

vrm_storeB

Store a memory with file citations. Snippets are auto-extracted.

Inputs: subject (required), fact (required), citations (required), reason, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: forget deletes, list enumerates, retrieve verifies and returns, search finds candidates, and store creates. The descriptions explicitly differentiate them, such as distinguishing retrieve (with JIT verification) from search (fast, no verification).

    Naming Consistency5/5

    All tools follow a consistent 'vrm_' prefix and verb_noun pattern (e.g., vrm_forget, vrm_list, vrm_retrieve, vrm_search, vrm_store). This predictable naming makes it easy for agents to understand and select tools without confusion.

    Tool Count5/5

    With 5 tools, the set is well-scoped for a memory management server, covering core operations like store, retrieve, search, list, and forget. Each tool earns its place, providing a complete yet manageable surface without bloat or thinness.

    Completeness5/5

    The tool surface offers complete CRUD/lifecycle coverage for memory management: store (create), retrieve/read (with verification), search (find), list (enumerate), and forget (delete). There are no obvious gaps, enabling agents to handle all typical workflows without dead ends.

    Related MCP Connectors