Repomemory

You set up and run an MCP server that gives AI agents persistent context across sessions, auto-summarizes interactions, and provides hybrid search to quickly locate relevant knowledge within and across your repositories. This server-enabled memory helps agents orient themselves faster, write consistently to a shared knowledge base, and reduce repeated discussions about architecture, decisions, and regressions.

How to use

To use the MCP server, start the server in your development environment and connect your preferred AI coding tool. The server exposes a memory-capable interface that tools can query for context, write findings, and read back the most relevant facts, decisions, and preferences. Begin by launching the MCP server, then configure your AI tool to connect to it. Once connected, your agents can orient themselves at session start, search for context with intelligent routing, and automatically capture session activity for future reference.

How to install

Prerequisites: You need Node.js and npm installed on your machine. You should have a working command line environment and access to the internet to install dependencies.

# 1. Install the package globally or run via npx in your project
# If you want to install globally (optional):
npm install -g repomemory

# Alternatively, run the core commands via npx in your project
npx repomemory go

Configuration and usage notes

Configure the MCP server for your environment to control how the knowledge base is built, what stores are used, and how agents search. Key configuration options include selecting the provider, model, context directory, embedding provider, and global context settings. You can also adjust scope routing so some data lives globally while more sensitive data remains repo-local.

Additional setup steps

1. Initialize the context directory and profile. 2. Analyze your repository to build the initial knowledge base. 3. Connect your preferred AI tools to the MCP server so they can query, write, and read context.

Starting the MCP server

npx repomemory serve

Usage with an MCP client

After starting the server, configure your MCP client (such as Claude Code, Cursor, Copilot, or Windsurf) to connect to the running MCP server. The client can request orientation data, perform context searches, and write discoveries and decisions back to the knowledge base during your session.

Tools and capabilities

The MCP server provides several tools that enable search, orientation, read, write, list, and delete operations on knowledge context. These tools support hybrid keyword and semantic search, intelligent routing to categories, and auto-purge of outdated entries.

What’s included in the memory

Facts capture the current state of the project. Decisions prevent re-debate. Regressions help avoid repeating past bugs. Preferences teach agents coding style and tool choices. Sessions summarize activity for future reference.

Post-setup capabilities

You can inspect and edit the knowledge base through a local web dashboard, search from the terminal, and sync changes to a changelog. The system also supports auto-capture of sessions and consistent updates across sessions.

Security and best practices

Keep your API keys and credentials in environment variables, and use the global context only for non-sensitive preferences if your team requires stricter separation. Regularly review and prune stale context to maintain fast searches and accurate routing.

Examples

Example: orient an agent in a project, search for authentication flow context, and write a note about a race condition discovered during token refresh. The agent persists this in the regressions category and makes it available to future sessions.

Available tools

context_search

Hybrid keyword + semantic search across repo and global context with intelligent routing to categories.

context_auto_orient

One-call orientation to gather project overview, preferences, and recent activity.

context_write

Write entries with scope-aware routing and auto-purge detection to keep knowledge up to date.

context_read

Read full content with repo-first priority and global fallback.

context_list

Browse entries from both repo and global stores with provenance tagging.

context_delete

Remove stale knowledge, preferring repo scope and then global when necessary.