![Verified Repo Memory Banner](assets/banner.png)

# Verified Repo Memory MCP v0.1.0

[![CI](https://github.com/cognitivemyriad/verified-repo-memory-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cognitivemyriad/verified-repo-memory-mcp/actions/workflows/ci.yml)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7.0-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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`:

```bash
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:
```json
{
  "subject": "API version sync",
  "fact": "When changing API version, update client/server/docs together.",
  "citations": [{ "path": "src/api.ts", "startLine": 10, "endLine": 15 }]
}
```
Output:
```json
{
  "stored": true,
  "memoryId": "uuid-...",
  "expiresAt": "2026-03-21T00:00:00Z"
}
```

**Retrieve:**
Input:
```json
{ "query": "API version" }
```
Output:
```json
{
  "query": "API version",
  "valid": [ ... ],
  "stats": { "verified": 1, "validCount": 1 }
}
```

## How it works

```mermaid
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:
```json
{
  "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:

```bash
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:
```bash
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.*