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

Install dependencies
pip install mcp arc-memory
Authenticate with GitHub
arc auth gh
This will guide you through authenticating with GitHub. You'll see a success message when complete.
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.
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).
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:

Linear Issue ABC-123 (Feature Request)
    ↓ DECIDES
Architecture Decision Record (ADR-42)
    ↓ IMPLEMENTS
GitHub Pull Request #456
    ↓ CONTAINS
Commit abc123
    ↓ MODIFIES
File: src/auth/middleware.js

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:

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

Example Questions

Architectural Reasoning & Decision Archaeology

"What were the security considerations that led to our current authentication architecture?"
"Why did we migrate from monolith to microservices in Q3 2022, and what were the tradeoffs?"
"What performance issues drove the switch from Redis to our custom caching solution?"
"How did our API design evolve after the major outage last year?"

Cross-System Impact Analysis

"Which backend services were affected by the payment processing refactoring?"
"What downstream components depend on the authentication middleware we're planning to change?"
"How many different teams' code would be impacted if we deprecate the legacy API?"
"What parts of our infrastructure were modified to address the rate limiting issues?"

Technical Debt & Regression Prevention

"What previous attempts have we made to fix the intermittent test failures in the CI pipeline?"
"Which PRs have touched this fragile payment processing code in the last 6 months?"
"What was the root cause analysis of our last three production incidents?"
"Which architectural decisions have we revisited multiple times, suggesting design instability?"

Knowledge Transfer & Onboarding

"What's the complete history of our authentication system from initial design to current implementation?"
"Who are the domain experts for each component of our data processing pipeline?"
"What were the key design decisions made before I joined the team that explain our current architecture?"
"What's the context behind this complex caching logic that no one seems to understand anymore?"

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

# Install dependencies
pip install mcp arc-memory

# Clone the repository
git clone https://github.com/Arc-Computer/arc-mcp-server.git
cd arc-mcp-server

# Install the server
pip install -e .

Setup

Authenticate with GitHub (if you have GitHub OAuth credentials)
arc auth gh
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

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

VS Code Agent Mode

Install the VS Code Agent Mode extension
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

Open Cursor settings and navigate to the AI settings
Configure the MCP server (similar to VS Code configuration)
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:

{
  "path": [
    {"id": "pr:42", "type": "pr", "title": "Add new feature", "depth": 0},
    {"id": "adr:123", "type": "adr", "title": "Architecture decision", "depth": 1},
    {"id": "issue:456", "type": "issue", "title": "Feature request", "depth": 2}
  ],
  "meta": {
    "query_depth": 3,
    "sql": "/* The SQL query used for debugging */"
  }
}

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:
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.
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.
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

Arc Memory MCP Server

Integrations