arc-memory 0.3.0

Arc Memory - Local bi-temporal knowledge graph for code repositories

Arc Memory CLI

At Arc, we're building the foundational memory layer for modern software engineering. Our mission is simple but powerful: ensure engineering teams never lose the critical "why" behind their code. We bridge the gap between human decisions and machine understanding, becoming the temporal source-of-truth for every engineering team and their AI agents.

Overview

Arc Memory is a comprehensive CLI tool that embeds a local, bi-temporal knowledge graph (TKG) in every developer's workspace. It surfaces verifiable decision trails during code-review and exposes the same provenance to any LLM-powered agent through VS Code's Agent Mode.

Arc Memory Ecosystem

The Arc Memory CLI is part of a broader ecosystem that connects your team's collective history to AI assistants:

How It Works

• Data Sources (G-Suite, Slack, Notion, GitHub, Jira) seamlessly feed into the Arc Memory CLI, which captures organizational decisions in a local-first Temporal Knowledge Graph (TKG).

• The Arc MCP Server provides persistent, cross-repository decision context, enabling memory-aware multi-step reasoning for integrated tooling.

• Through the VS Code Extension, developers interact directly with decision trails embedded into code reviews, and leverage verifiable citations and team-wide search across organizational decisions.

Together, these components form the foundation for organizational intelligence, empowering sophisticated reasoning and enabling AI agents to build robust world models from your team's collective history.

Arc Memory Features

• Comprehensive Knowledge Graph - Build a local graph from Git commits, GitHub PRs, issues, and ADRs
• Decision Trail Visualization - Understand the "why" behind code with arc why command
• Relationship Exploration - Discover connections between entities with arc relate command
• High Performance - Queries complete in under 200ms (typically ~100μs)
• Incremental Builds - Efficiently update the graph with only new data
• MCP Integration - Connect to AI assistants via Anthropic's Model Context Protocol
• Privacy-First - All data stays on your machine; no code or IP leaves your repo
• Extensible Plugin Architecture - Easily add new data sources beyond Git, GitHub, and ADRs
• CI Integration - Team-wide graph updates through CI workflows

Installation

Arc Memory requires Python 3.10 or higher and is compatible with Python 3.10, 3.11, and 3.12.

pip install arc-memory

Or using UV:

uv pip install arc-memory

Quick Start

# Authenticate with GitHub
arc auth gh

# Build the full knowledge graph
arc build

# Or update incrementally
arc build --incremental

# Check the graph status
arc doctor

# Show decision trail for a specific file and line
arc why file path/to/file.py 42

# Show related nodes for a specific entity
arc relate node commit:abc123

# Serve the knowledge graph via MCP
arc serve start

Telemetry

Arc Memory includes optional, privacy-respecting telemetry to help us improve the product:

• Anonymous: No personally identifiable information is collected
• Opt-in: Disabled by default, enable with arc config telemetry on
• Transparent: All collected data is documented and visible
• Focused: Only collects command usage and session metrics for MTTR measurement

Telemetry is disabled by default. To enable it: arc config telemetry on To disable telemetry: arc config telemetry off

Documentation

CLI Commands

Building & Setup

• Authentication - GitHub authentication commands (arc auth)
• Build - Building the knowledge graph (arc build)
• Doctor - Checking graph status and diagnostics (arc doctor)

Querying & Exploration

• Why - Show decision trail for a file line (arc why)
• Relate - Show related nodes for an entity (arc relate)
• Trace - Legacy tracing history for files and lines (arc trace)

Integration & Serving

• Serve - Serve the knowledge graph via MCP (arc serve)

Usage Examples

• Building Graphs - Examples of building knowledge graphs
• Tracing History - Examples of tracing history
• Custom Plugins - Creating custom data source plugins

API Documentation

• Build API - Build process API
• Trace API - Trace history API
• Models - Data models
• Plugins - Plugin architecture API

For additional documentation, visit arc.computer.

Architecture

Arc Memory consists of three components:

1. arc-memory (this CLI) - Command-line interface and underlying SDK for graph building and querying

   • CLI Commands - User-friendly interface for building graphs and exploring history
   • Local SQLite Database - Stores the knowledge graph with direct access for CLI commands
   • Plugin Architecture - Extensible system for adding new data sources
   • Trace History Algorithm - BFS-based algorithm for traversing the knowledge graph

2. arc-mcp-server - MCP server exposing the knowledge graph to AI assistants

   • Available at github.com/Arc-Computer/arc-mcp-server
   • Implements Anthropic's Model Context Protocol (MCP) for standardized AI tool access
   • Provides tools like arc_trace_history, arc_get_entity_details, and more
   • Can be started directly from the CLI with arc serve start

3. vscode-arc-hover - VS Code extension for displaying decision trails (in development)

   • Will integrate with the MCP server to display trace history
   • Will provide hover cards with decision trails
   • Will be available as a separate extension

See our Architecture Decision Records for more details on design decisions, including:

• ADR-001: Knowledge Graph Schema
• ADR-002: Data Model Refinements
• ADR-003: Plugin Architecture

Development

Setup

# Clone the repository
git clone https://github.com/arc-computer/arc-memory.git
cd arc-memory

# Create a virtual environment with UV
uv venv

# Activate the environment
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Testing

# Run unit tests
python -m pytest

# Run integration tests
python -m pytest tests/integration

# Run performance benchmarks
python tests/benchmark/benchmark.py --repo-size small

CLI Development

The Arc Memory CLI is built using Typer, a modern library for building command-line interfaces in Python. The CLI commands are organized in the arc_memory/cli/ directory:

arc_memory/cli/
├── __init__.py     # Main CLI entry point
├── auth.py         # Authentication commands
├── build.py        # Build commands
├── doctor.py       # Diagnostic commands
├── relate.py       # Relationship exploration commands
├── serve.py        # MCP server commands
├── trace.py        # Legacy trace commands
└── why.py          # Decision trail commands

To add a new command, create a new file in the arc_memory/cli/ directory and register it in __init__.py.

Creating a Plugin

Arc Memory uses a plugin architecture to support additional data sources. To create a new plugin:

1. Create a class that implements the IngestorPlugin protocol
2. Register your plugin using entry points
3. Package and distribute your plugin

Basic example:

from arc_memory.plugins import IngestorPlugin
from arc_memory.schema.models import Node, Edge, NodeType, EdgeRel

class MyCustomPlugin(IngestorPlugin):
    def get_name(self) -> str:
        return "my-custom-source"

    def get_node_types(self) -> List[str]:
        return ["custom_node"]

    def get_edge_types(self) -> List[str]:
        return [EdgeRel.MENTIONS]

    def ingest(self, last_processed=None):
        # Your implementation here
        return nodes, edges, metadata

Register in pyproject.toml:

[project.entry-points."arc_memory.plugins"]
my-custom-source = "my_package.my_module:MyCustomPlugin"

For detailed instructions and examples, see:

• Custom Plugins Guide - Step-by-step guide with examples
• Plugin Architecture - Technical details of the plugin system
• Plugins API - API reference for plugin development

Performance

Arc Memory is designed for high performance, with trace history queries completing in under 200ms (typically ~100μs). See our performance benchmarks for more details.

License

MIT