How do I use repo-memory-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@repo-memory-mcp load context for current repo" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

repo-memory-mcp

by andyast

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

repo-memory-mcp

Local-first, repo-scoped memory for engineering agents.

repo-memory-mcp is an early MCP prototype for sharing source-backed engineering memory across AI coding clients like Cursor, VS Code, Claude Code, Gemini CLI, Codex CLI, and other MCP-capable tools.

Engineering memory should follow the repo across AI clients, not be trapped inside one application.

This is not a generic personal-memory bot. It is a project memory layer for software work: decisions, gotchas, commands, artifacts, task checkpoints, and stale warnings tied back to repo evidence.

Related MCP server: lxDIG MCP

Why this exists

AI coding tools are useful, but each one tends to start from a blank slate. Repo docs get stale, prior debugging context disappears, and decisions are scattered across chats, commits, and terminal output.

Repo memory is designed to answer questions like:

What did we do last time in this repo?
What did we decide about this subsystem?
What test command worked?
What failure did we already investigate?
Which memories might be stale after a git pull?
What should the agent know before touching this code?

Quick start

Clone, install, build, and test:

git clone https://github.com/pinchworth-ops/repo-memory-mcp.git
cd repo-memory-mcp
npm install
npm run build
npm test
npm run demo

Run the MCP server directly:

node /absolute/path/to/repo-memory-mcp/dist/server.js

Run the CLI directly:

node /absolute/path/to/repo-memory-mcp/dist/cli.js --help

Optional local link for nicer CLI usage:

npm link
repo-memory --help

See Installation for tarball/npm install and MCP client config.

Initialize a test repo:

cd /path/to/test-repo
repo-memory init --update-gitignore
repo-memory context --task "understand this repo"

Recommended MCP server config shape:

{
  "mcpServers": {
    "repo-memory": {
      "command": "node",
      "args": ["/absolute/path/to/repo-memory-mcp/dist/server.js"],
      "env": {
        "REPO_MEMORY_ALLOWED_ROOT": "/absolute/path/to/test-repo"
      }
    }
  }
}

See MCP and CLI reference for per-client setup.

Core workflow

Typical agent loop:

load_project_context
→ search_project_memory / get_memory if needed
→ store_artifact for important raw evidence
→ checkpoint_task after meaningful progress on multi-step work
→ run tests / validation
→ finish_task with summary and optional proposedMemories

The important distinction:

Context at task start — load relevant memories, active checkpoints, commands, gotchas, and stale warnings.
Checkpoints during work — preserve temporary work-in-progress state for long tasks, crashes, or context-window overflow.
Memories at task end — propose durable lessons only when they will help future agents.

Read the full workflow in Agent workflow.

Docs

Doc	What it covers
Installation	Local clone, npm/tarball install, MCP config, smoke test
Design notes	Design principles, features, roadmap, MVP snapshot
MCP and CLI reference	CLI commands, MCP tools, client configuration, cross-client test plan
Agent workflow	Context loading, checkpoints, `finish_task`, proposed memories, statuses
Setup and troubleshooting	Repo initialization, hooks, env vars, path mismatch, SQLite busy
Dogfood and evaluation	Alternating Claude/Cursor suite, checkpoint recovery dogfood, checklists

Development

npm install
npm run build
npm test
npm run demo

Additional checks:

npm run stress
scripts/run-memory-dogfood-suite.sh /path/to/memory-test
scripts/run-checkpoint-dogfood.sh /path/to/memory-checkpoint-test

The smoke test creates a fake git repo and verifies storage/search, artifact paging, command capture, context packs, git revalidation, listing/deletion, audit trail, deduplication, and lifecycle operations.

Dashboard

Start the local dashboard to review memories, audit history, and useful project stats:

repo-memory dashboard

The dashboard includes a Needs attention review queue for proposed, needs-revalidation, and stale memories. It supports the same audited review actions as the CLI: accept/verify, reject, mark stale/historical, or delete.

Safety notes

Do not point early versions at sensitive work repos until tested on disposable repos.
Use REPO_MEMORY_ALLOWED_ROOT during early dogfooding.
Do not store secrets, credentials, tokens, personal data, or trivial churn.
Treat memories as claims with provenance, not absolute truth.
Re-check code before acting on stale or probably-active memories.

Current status

Prototype. Useful enough to test, not production-ready.

Current implementation is intentionally boring:

TypeScript / Node
SQLite via better-sqlite3
SQLite FTS5 search
local files only
no cloud calls
no embeddings yet
no LLM dependency

The deterministic storage/retrieval/staleness layer comes first. LLM-assisted extraction or summarization can come later.

License

MIT. See LICENSE.

Available Tools

30 tools

active_checkpointsB

List active checkpoint memories for this repo so agents can resume interrupted multi-step tasks.

Inputs: cwd, limit.

checkpoint_taskB

Store lightweight crash/context recovery state for a multi-step coding task. Call after meaningful steps or before risky/long operations.

Inputs: task (required), cwd, tags, status, +9 more.

delete_memoryA

[compatibility] Prefer manage_memory action=delete. Delete one memory with audit trail.

Inputs: id (required), cwd, reason.

finish_taskA

Call before the final response on non-trivial tasks. Summarize work and propose 0-3 durable memories only: decisions, root causes, gotchas, reusable commands, architecture/config constraints, failed approaches. Do not propose secrets, personal data, temporary edits, or trivial churn.

Inputs: summary (required), cwd, outcome, testsRun, +2 more.

get_artifactC

Retrieve an artifact by ID with offset/limit paging.

Inputs: id (required), cwd, limit, offset.

get_memoryC

Get one memory by id with provenance metadata and linked evidence.

Inputs: id (required), cwd.

get_memory_with_evidenceA

Get one memory by id with linked source artifacts, quotes, and provenance.

Inputs: id (required), cwd.

init_repo_memoryC

Initialize repo-memory-mcp in this repo: create config, agent instructions, and optional bootstrap memory/hooks.

Inputs: cwd, seed, overwrite, installGitHooks, +1 more.

install_git_hooksC

Install best-effort git hooks to revalidate memory after checkout/merge/rewrite.

Inputs: cwd, command.

link_memoriesC

Create a typed relationship between two memories.

Inputs: toId (required), fromId (required), relation (required), cwd.

link_memory_evidenceB

Attach a source artifact and optional quote to an existing memory claim.

Inputs: memoryId (required), artifactId (required), cwd, quote, +1 more.

list_memoriesC

List project memories with optional filters.

Inputs: cwd, tags, limit, types, +2 more.

load_project_contextC

Start here for non-trivial tasks. Returns a task-specific readable repo context briefing with relevant memories, decisions, commands, and stale warnings.

Inputs: task (required), cwd, limit, format.

manage_memoryB

Manage memory lifecycle: verify, mark, delete, link, or supersede. Prefer this over individual lifecycle tools.

Inputs: action (required), id, cwd, toId, +7 more.

memory_statusB

Show memory counts and stale/needs-revalidation memories for current repo.

Inputs: cwd.

propose_memoryA

Propose a repo memory for later human review. Use this at the end of non-trivial tasks when durable lessons emerged: decisions made, root causes found, gotchas, reusable commands, architecture/config constraints, failed approaches, or important evidence-backed facts. Prefer 1-3 high-signal proposals; do not store secrets, credentials, personal data, or trivial churn.

Inputs: claim (required), title (required), cwd, tags, +9 more.

recent_activityB

Show compact recent repo-memory events, artifacts, and memories. Use near task end to decide whether any durable proposed memories are worth creating.

Inputs: cwd, limit.

remember_project_noteA

[compatibility] Prefer store_memory. Store a repo-scoped source-backed memory note.

Inputs: claim (required), title (required), cwd, tags, +4 more.

repo_identityB

Detect current repo/project identity from cwd.

Inputs: cwd.

revalidate_memoriesC

Scan git diff staleness between two refs and flag affected memories for human review; this does not prove truth.

Inputs: fromSha (required), cwd, toSha.

review_memoriesB

List stale and needs-revalidation memories with suggested review commands.

Inputs: cwd, limit.

run_command_captureB

Run a command, store stdout/stderr as an artifact, and create a searchable source-backed memory of the result.

Inputs: command (required), cwd, title, remember.

search_evidenceB

Search raw source artifacts/evidence. Use before trusting or creating claims.

Inputs: query (required), cwd, limit.

search_project_memoryC

Search current repo memory. Exact/BM25 first. Re-check code memories if status is not active.

Inputs: query (required), cwd, limit, statuses.

store_artifactB

Store a large artifact such as logs, command output, diffs, or transcripts. Returns preview and stable ID.

Inputs: body (required), title (required), cwd, type, +2 more.

store_decisionC

[compatibility] Prefer store_memory with type=decision. Store a repo-scoped engineering decision.

Inputs: claim (required), title (required), cwd, tags, +4 more.

store_memoryB

Store a repo-scoped source-backed memory. Use for durable decisions, gotchas, commands, failures, or facts. Defaults to active unless status=proposed is supplied.

Inputs: claim (required), title (required), cwd, tags, +9 more.

supersede_memoryC

Mark an old memory superseded by a newer memory and link them.

Inputs: newId (required), oldId (required), cwd.

update_memory_statusC

Update memory lifecycle status.

Inputs: id (required), status (required), cwd, confidence.

verify_memoryB

[compatibility] Prefer manage_memory action=verify. Mark a memory active and verified against current HEAD.

Inputs: id (required), cwd, confidence.

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

C2.6/5.0

Scored 2026-07-30 11:55 across 30 tools

Disambiguation2/5

Multiple tools for storing memories (store_memory, propose_memory, remember_project_note, store_decision) and retrieving memories (get_memory, get_memory_with_evidence, search_project_memory, list_memories) have overlapping purposes. Compatibility tools like 'prefer store_memory' add confusion.

Naming Consistency3/5

Naming is mostly snake_case with verb_noun pattern, but there are inconsistencies: 'remember_project_note' vs 'store_memory', 'checkpoint_task' vs 'active_checkpoints', and generic 'manage_memory'. The pattern is not fully uniform.

Tool Count2/5

30 tools is quite high for a repo memory system. Many are compatibility wrappers or redundant (e.g., delete_memory vs manage_memory). The core functionality could be covered with fewer tools, making the count feel bloated.

Completeness3/5

Covers CRUD for memories, search, evidence linking, and checkpoints, but lacks an artifact listing tool. Some lifecycle operations are duplicated. There are notable gaps, but core workflows are supported.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

SubstrateB
co.trysubstrate
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Developer Tools Knowledge & Memory
131
https://app.trysubstrate.co/mcp
MemmoA
dev.memmo
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Knowledge & Memory Code Analysis Developer Tools
61
https://api.memmo.dev/mcp
Agentage Memory
io.agentage
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge & Memory File Systems
2
https://memory.agentage.io/mcp
khive
ai.khive
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Knowledge & Memory Project Management
1
https://khive.ai/v1/mcp

Related MCP Servers

memory-mcp
Knowledge & Memory Vector Databases AI & Machine Learning
vinnyho
F
license
Not graded
quality
D
maintenance
A persistent, conflict-aware memory MCP server for AI coding assistants (Cursor, Claude Code).
Updated 5 months ago (2026-06-14 04:56 UTC)
-
lxDIG MCP
Code Analysis Knowledge & Memory Agent Orchestration
lexCoder2
A
license
B
quality
D
maintenance
MCP server that gives AI coding assistants persistent memory, structural code graph analysis, and safe multi-agent coordination, enabling them to answer architectural questions, track decisions across sessions, and coordinate safely in multi-agent workflows.
Updated 8 months ago (2026-03-03 05:56 UTC)
39
4
MIT
memnant
Knowledge & Memory Vector Databases Search
peureka
A
license
Not graded
quality
B
maintenance
Persistent memory MCP server that remembers decisions and context across coding sessions, automatically logging and surfacing relevant knowledge as you work.
Updated 2 months ago (2026-09-11 16:55 UTC)
51 npm
MIT
cba
Code Analysis RAG Systems
davidgeorgehope
F
license
Not graded
quality
C
maintenance
MCP server for semantic code search and explanation. Allows AI agents to search, ask questions, and manage memory about a codebase with local embeddings and LLM integration.
Updated 13 days ago (2026-10-29 17:27 UTC)
-

repo-memory-mcp

Contents

Why this exists

Quick start

Core workflow

Docs

Development

Dashboard

Safety notes

Current status

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

memory-mcp

lxDIG MCP

memnant

cba