Arc Memory MCP Server

Arc Memory MCP Server

Arc helps engineering teams understand the context and history behind their code. This MCP server lets AI assistants query your codebase's history and relationships using natural language.

"Why did we choose MongoDB over PostgreSQL?" "How did the authentication system evolve over time?" "What was the rationale behind the microservices architecture?"

Quick Start Workflow

1. Install dependencies
   pip install mcp arc-memory
2. Authenticate with GitHub
   arc auth gh
   This will guide you through authenticating with GitHub. You'll see a success message when complete.
3. Authenticate with Linear (Optional)
   arc auth linear
   This will guide you through authenticating with Linear using OAuth 2.0. A browser window will open for you to authorize Arc Memory to access your Linear data. This step is optional but recommended if you want to include Linear issues in your knowledge graph.
4. Build your knowledge graph
   arc build
   This will analyze your repository and build a local knowledge graph. You'll see progress indicators and a summary of ingested entities when complete.To include Linear issues in your knowledge graph:
   arc build --linear
   This requires Linear authentication (step 3).
5. Configure in Claude Desktop, VS Code Agent Mode, or CursorSee the "Integration" section below for detailed instructions.

How Arc Works

Arc builds a graph of your codebase's history, connecting structured data from different sources. Instead of using vector similarity like typical RAG systems, Arc focuses on the actual relationships between commits, PRs, issues, and architectural decisions.

The arc_search_story tool converts natural language questions into graph queries that can follow multiple connections, helping AI assistants provide answers based on your project's actual history.

Knowledge Graph Structure

Arc builds a rich knowledge graph with:

• Entities: PRs, commits, issues (GitHub & Linear), ADRs, files, and more
• Relationships: MODIFIES, MENTIONS, MERGES, DECIDES, IMPLEMENTS
• Temporal context: When changes happened and in what sequence
• Provenance: Why changes were made and who made them
• Cross-system connections: Links between GitHub PRs and Linear issues

This interconnected structure enables tracing the complete story behind any line of code—from the initial issue, through architectural decisions, to implementation PRs and commits.

For example, a typical path might look like:

When you ask "Why was the authentication middleware implemented this way?", Arc can traverse this path backward to provide the complete context.

Connecting Different Systems

Using GitHub and Linear MCPs separately works for basic queries, but Arc connects them together:

1. Connected Data: Links information from GitHub, Linear, Git, and ADRs in one graph
2. Cross-system Connections: Shows relationships between Linear issues and GitHub PRs
3. Multi-step Paths: Follows chains of connections that separate API calls would miss
4. Time-based Context: Maintains when things happened across different systems
5. Structured Results: Returns paths that AI assistants can use to explain relationships

Example Questions

Architectural Reasoning & Decision Archaeology

Cross-System Impact Analysis

Technical Debt & Regression Prevention

Knowledge Transfer & Onboarding

Available Tools

• arc_search_story: Natural-language graph query for multi-hop questions
• arc_trace_history: Traces the decision history for a specific line in a file
• arc_get_entity_details: Retrieves detailed information about a specific entity
• arc_find_related_entities: Finds entities directly connected to a given entity
• arc_blame_line: Gets the specific commit SHA, author, and date for a line

Installation

Setup

1. Authenticate with GitHub (if you have GitHub OAuth credentials)
   arc auth gh
2. Build your knowledge graph
   arc build
   This builds a graph from your local Git repository, including commits, files, PRs, issues, and their relationships. The database is stored at ~/.arc/graph.db.

Integration

Claude Desktop

1. Open your configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the server configuration:
   { "mcpServers": { "arc-memory": { "command": "python", "args": ["/absolute/path/to/src/arc_mcp_server.py"] } } }
3. Restart Claude Desktop

VS Code Agent Mode

1. Install the VS Code Agent Mode extension
2. Configure the MCP server in your VS Code settings:
   "anthropic.agent-mode.mcp.servers": { "arc-memory": { "command": "python", "args": ["/absolute/path/to/src/arc_mcp_server.py"] } }

Cursor

1. Open Cursor settings and navigate to the AI settings
2. Configure the MCP server (similar to VS Code configuration)
3. Restart Cursor

Tool Documentation

arc_search_story

Natural-language graph query for multi-hop questions.

Parameters:

• question: The natural language question to ask
• max_depth (optional): Maximum depth for graph traversal (default: 3)
• max_results (optional): Maximum number of results to return (default: 100)

Returns:

How AI Assistants Use This Data

When a developer asks "Why did we migrate from Redis to our custom caching solution?", the AI assistant can use the structured path data to create a response like:

"The migration from Redis to our custom caching solution in July 2023 was driven by three key factors:

1. Performance bottlenecks: Linear issue PERF-387 documented Redis connection pooling problems during peak traffic, causing 30% of the latency spikes observed in Q2 2023. This was prioritized as P0 by the Platform team after the June outage.
2. Architectural limitations: ADR-29 (authored by Sarah Chen) details how Redis's single-threaded model couldn't efficiently handle our growing concurrent write patterns, particularly for the product catalog service. This ADR references Linear issue ARCH-42 where the initial concerns were raised.
3. Cost considerations: GitHub PR #1204 included benchmark results showing the custom solution reduced infrastructure costs by 42% while improving p99 latency by 150ms. This PR was linked to Linear issue COST-56 from the Q3 cost optimization initiative.

The migration was implemented across 7 GitHub PRs, primarily by the Infrastructure team, with the most significant changes in the inventory and checkout services. There were initial concerns about data consistency (raised by Alex Kim in PR #1209), which were addressed by adding the two-phase commit protocol documented in ADR-31.

The custom solution has been stable since deployment, with only two minor incidents (tracked in Linear as INC-45 and INC-52) related to cache invalidation edge cases, both resolved in follow-up GitHub PR #1567."

The response includes:

• Information from different sources (Linear issues, GitHub PRs, ADRs, incidents)
• Specific metrics and measurements
• Names of people involved and their roles
• The sequence of events and technical details
• Problems that came up and their solutions
• What happened afterward

This works because Arc connects information across different systems that would normally be separate.

Common Use Cases

1. Onboarding New Team Members

When new developers join a team, they can ask questions about unfamiliar code and systems to understand the context and reasoning behind implementations.

2. Preventing Regressions

Before making changes to complex or critical systems, developers can explore the history of previous issues, approaches that didn't work, and the reasoning behind the current implementation.

3. Making Architectural Decisions

When considering changes to the architecture, teams can look at the history of related decisions, understanding what was tried before and why certain approaches were chosen.

4. Refactoring Legacy Code

When working with older code that lacks documentation, developers can trace its origins, understand its purpose, and identify its dependencies before making changes.

Future Development

Future plans for Arc include:

• Running lightweight simulations on PRs to identify potential issues
• Detecting security vulnerabilities and technical debt risks
• Building a causal model of system behavior over time
• Adding the simulation results back into the knowledge graph

License

MIT License

Need Help?

• GitHub Issues
• Documentation
• Discord Community