Skip to main content
Glama
io.github.Umarjaum/repo-memory-mcp

io.github.Umarjaum/repo-memory-mcp

by Umarjaum

repo-memory-mcp

mcp-name: io.github.Umarjaum/repo-memory-mcp

Persistent memory for AI coding agents

AI coding agents are powerful, but they forget repository-specific corrections, conventions, constraints, and architectural decisions. repo-memory-mcp gives MCP-compatible coding agents a persistent, local, repository-aware memory layer.

Teach your coding agent once. Let your repository remember.

Tests PyPI License

Related MCP server: context-ledger

What it does

MCP hosts decide when tools are called; MCP does not automatically intercept every conversation. This project exposes explicit tools that let an agent load important context at session startup, search relevant memories, store corrections and decisions, update stale guidance, and archive obsolete memories.

The memory database lives in .repo-memory/memory.db inside the detected repository. It uses SQLite, deterministic local ranking, and no cloud service.

Why developers use it

  • Persistent project memory: corrections, rules, conventions, constraints, decisions, and bug-fix lessons survive sessions.

  • Repository-aware isolation: unrelated repositories do not share memory.

  • Local-first privacy: no API keys, remote database, external embeddings, telemetry, or background upload.

  • Explicit MCP workflow: the agent chooses when to remember and recall; there is no claim of automatic conversation interception.

  • Fast and inspectable: SQLite storage, JSON export, CLI diagnostics, and human-readable records.

  • Security-minded: likely API keys, bearer tokens, passwords, cloud credentials, and private keys are rejected by default.

Install and use in two minutes

The public PyPI distribution is named repo-memory-mcp-ai because the shorter repo-memory-mcp name is already owned by another project. The MCP server and GitHub project identity remain repo-memory-mcp.

pip install repo-memory-mcp-ai
repo-memory doctor

Start the MCP server directly:

repo-memory-mcp

Or run it without a permanent installation:

uvx --from repo-memory-mcp-ai repo-memory-mcp

The server is local and communicates over stdio. It does not need an API key.

Configure an MCP client

The common stdio configuration is:

{
  "mcpServers": {
    "repo-memory": {
      "command": "uvx",
      "args": ["--from", "repo-memory-mcp-ai", "repo-memory-mcp"]
    }
  }
}

Use the client-specific configuration location and format documented by your MCP host. Ready-to-copy examples are in examples/:

The project is vendor-neutral and is intended for Claude Code, Cursor, Cline, Windsurf, and other MCP-compatible coding agents. Compatibility depends on the host’s MCP support and configuration format.

At the beginning of a coding session, call get_startup_context(). When the developer corrects a repeated mistake, call remember_correction(topic, lesson). When a relevant question arises, call recall_memory(query). When guidance becomes stale, call update_memory() or archive it with forget_memory().

Example instruction to an agent:

At the start of this session, call get_startup_context. If I correct a repeated mistake or establish a durable project rule, store it with the appropriate repo-memory tool. Do not store credentials or transient chat context.

Available MCP tools

Tool

Use it for

get_startup_context

Load concise, high-value repository guidance at session start

remember_correction

Store a lesson learned from a correction or bug fix

remember_rule

Store a durable project rule or convention

remember_decision

Store an architectural decision and rationale

recall_memory

Search active memory with deterministic local scoring

list_project_rules

List active project rules

list_memories

Filter memories by type or status

update_memory

Correct an existing memory without creating a replacement

forget_memory

Archive obsolete memory for audit-friendly retention

export_memory / import_memory

Move validated memory between safe copies of the same repository

CLI

repo-memory init
repo-memory list
repo-memory rules
repo-memory search "database migrations"
repo-memory export ./memory-backup.json
repo-memory import ./memory-backup.json
repo-memory doctor

Privacy and security boundaries

Memories stay on the machine running the server. This implementation does not require API keys, cloud accounts, remote databases, external embeddings, or telemetry. It only inspects text explicitly submitted to memory tools. Your operating system, package manager, backups, and MCP host may have separate behavior.

Likely secrets are rejected by default. Do not submit passwords, tokens, private keys, or credentials to memory tools. The .repo-memory/ directory is ignored by Git so private memory is not accidentally committed.

Development

git clone https://github.com/Umarjaum/repo-memory-mcp.git
cd repo-memory-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
pytest

Discovery and publishing

Developer

Muhammad Umar Jabbar — Khanewal, Punjab, Pakistan. Personal website: umarjaum.netlify.app.

Roadmap

Future work may improve ranking, add confidence feedback, provide optional local embeddings, generate project context, add a memory inspection UI, and publish the companion extensions to official marketplaces. Team/shared memory remains explicitly opt-in.

Companion extensions

  • extensions/vscode provides local setup commands for VS Code.

  • extensions/bing provides a privacy-safe Manifest V3 context-menu helper for turning selected Bing research into a repo-memory prompt.

The browser companion intentionally does not invoke the local stdio MCP process. Direct browser-to-MCP integration would require a separately reviewed native-messaging bridge.

License

MIT. See LICENSE.

Available Tools

11 tools
export_memoryC

Export all active and archived memories as portable JSON to a user-specified path.

Inputs: output_path (required). Returns: object

forget_memoryA

Archive a memory so it is retained for auditability but excluded from normal recall and startup context.

Inputs: memory_id (required). Returns: object

get_startup_contextC

Return a concise startup context prioritizing critical and high-importance rules, conventions, decisions, and recent corrections.

Inputs: limit. Returns: result

import_memoryA

Import a JSON export without overwriting existing memories; malformed records are rejected and duplicates are reported.

Inputs: input_path (required). Returns: object

list_memoriesB

List repository memories with optional type and status filters.

Inputs: limit, status, memory_type. Returns: result

list_project_rulesA

List all active durable project rules for the current repository.

Inputs: no named parameters. Returns: result

recall_memoryA

Search active repository memories using deterministic local relevance scoring across topic, content, tags, context, and type.

Inputs: query (required), limit. Returns: result

remember_correctionB

Store a correction or lesson learned during development. Use for durable guidance that should prevent repeated mistakes; do not store credentials, secrets, or transient chat context.

Inputs: topic (required), lesson (required), tags, importance, +1 more. Returns: object

remember_decisionB

Store an architectural or implementation decision together with its rationale.

Inputs: decision (required), rationale (required), tags, context_file. Returns: object

remember_ruleA

Store a durable repository-specific rule or convention. Use when the agent should follow a project constraint in future sessions.

Inputs: rule (required), tags, importance, context_file. Returns: object

update_memoryA

Update an existing memory by ID. This changes the existing record and timestamp; it never silently creates a replacement.

Inputs: memory_id (required), tags, topic, status, +3 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have clearly distinct roles, but the remember_correction / remember_rule / remember_decision trio and list_project_rules overlapping list_memories create minor ambiguity. The descriptions explain the differences well enough for an agent to choose correctly.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: list_, update_, forget_, remember_, recall_, get_, export_, import_. The memory-themed vocabulary is coherent and predictable.

    Tool Count5/5

    11 tools is well-scoped for a repository memory system: create variants, read/search, update, archive, export/import, and startup context. Each tool earns its place and the set does not feel bloated.

    Completeness4/5

    The surface covers create, read, search, update, archive, export, import, and startup context. The main gap is no explicit restore/unarchive operation for archived memories, but this can likely be worked around via update_memory or export data.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a persistent, local-first memory for coding agents over MCP, enabling automatic recall and recording of past work, failures, and decisions to reduce repetition and token usage.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a local-first persistent memory layer for coding assistants, enabling cross-project user preferences, per-project durable and working memory, session archives, and reflective recommendations through MCP tools.
      43 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory across coding projects and machines, letting agents record and retrieve projects, reusable assets, sessions, decisions, commits, and handoffs via MCP.
      3
      Apache 2.0