Skip to main content
Glama
cognitivemyriad

Verified Repo Memory MCP

by cognitivemyriad
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
memoryIdYes
hardDeleteNo

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full behavioral burden. It only states 'delete' without disclosing implications such as whether deletion is permanent, what 'hardDelete' means, whether deletion is reversible, or what happens to associated memory. This is a significant transparency gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the core action and target resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and an unexplained 'hardDelete' parameter, the description is too brief to fully prepare an agent. It does not mention return values, deletion permanence, or any side effects, leaving important gaps for a deletion tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains 'memoryId' via 'by ID' but completely ignores the 'hardDelete' parameter, which is crucial for understanding whether deletion is soft or permanent. Half the parameters are semantically unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly uses the specific verb 'delete' with the resource 'memory' and identifies the key mechanism ('by ID'). It effectively distinguishes this tool from its siblings (store, search, retrieve, list) by centering on deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'Manually' provides context that this tool is for user-initiated deletion, likely contrasting with automatic memory management. However, it does not explicitly mention when not to use this tool or alternatives, so it lacks full exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vrm_listC

List memories by status.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNoall
limitNo
verifyNo

TDQS

C2.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It provides none: no mention of side effects, read-only nature, required permissions, pagination behavior, or the effect of the 'verify' parameter. The description adds no behavioral context beyond the action itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is front-loaded and free of fluff. However, it is under-specified, omitting essential information about parameters and behavior. It reads as a vague label rather than a concise, complete description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters (limit, status, verify), no annotations, and no output schema, the description is severely inadequate. It does not explain the meaning of statuses, the behavior of 'verify', or default limits. An AI agent would lack enough context to invoke the tool accurately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the lack of parameter explanations. It only mentions 'status' without explaining its enum values (all, valid, stale, missing) or the purpose of 'limit' and 'verify'. The description adds minimal meaning beyond the schema field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List memories by status' clearly identifies the action (list) and resource (memories), with status as a filter. It is not a tautology and distinguishes from siblings like vrm_retrieve (which likely fetches a single memory) and vrm_search (which likely searches by content), though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. The description does not mention contexts in which listing by status is appropriate, nor does it contrast with vrm_search or vrm_retrieve. No exclusions or prerequisites are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vrm_retrieveC

JIT-verify candidates and return valid memories.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
limitNo
includeStaleNo
touchNo

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits. It mentions 'JIT-verify' and 'valid memories' but does not state whether the operation is read-only, whether it has side effects (e.g., the 'touch' parameter suggests updating last access time), or what happens to invalid candidates. This is a significant transparency gap for a tool that may mutate state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. However, it is under-specified, sacrificing necessary context for brevity. It could be expanded with relevant behavioral details while still remaining concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has four parameters, no annotations, and no output schema, the description is insufficiently complete. It does not cover return value format, error behavior, side effects, or the meaning of key terms like 'candidates' and 'valid'. It leaves the agent with significant uncertainty.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no information about any of the four parameters (query, limit, touch, includeStale). It does not explain what 'candidates' refers to or how parameters influence the JIT verification. The description is entirely unhelpful for parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'verify' and resource 'memories', suggesting a retrieval/validation operation. However, 'candidates' is undefined and the purpose is vague, lacking clarity on what inputs are expected or how verification works. It does not clearly distinguish from siblings like vrm_search or vrm_list, as 'retrieve' with 'verify' is ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There are no exclusions, prerequisites, or mentions of sibling tools. The context is entirely implied by the tool name, which is insufficient for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vrm_storeB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
subjectYes
factYes
reasonNo
tagsNo
ttlDaysNo
citationsYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose all behavioral traits. It adds one useful detail (snippets are auto-extracted) but does not mention permissions, irreversibility, TTL behavior, conflict handling, or what the function returns. For a mutation tool with 6 parameters, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and key feature. No wasted words; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 6 parameters, no annotations, and no output schema, yet the description provides almost no context about what a memory is, how citations work, what snippet extraction means, or what the caller should expect. This level of sparsity is inadequate for an agent to invoke the tool intelligently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter meanings. It only vaguely references 'file citations' but does not explain subject, fact, tags, reason, or ttlDays. The raw schema provides types and constraints but no semantic guidance, leaving a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (store), the resource (a memory), and the key differentiator (file citations with auto-extracted snippets). It stands apart from sibling tools like vrm_search and vrm_list which are read operations, and vrm_forget which is a delete operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The verb 'store' and the context of sibling tools imply that this is the write operation vs. read/search operations, but the description does not explicitly state when to use this tool or when to prefer alternatives. There are no exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 5 tool updatesv0.1.0
    • First observedvrm_forget
    • First observedvrm_list
    • First observedvrm_retrieve
    • First observedvrm_search
    • First observedvrm_store
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Resources

Related MCP Connectors