arc-memory 0.1.0

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

Arc Memory SDK

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. Our mission is to bridge the gap between human decisions and machine understanding, becoming the temporal source-of-truth for every engineering team and their agents.

Overview

Arc Memory is a comprehensive SDK (Software Development Kit) 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.

Features

• Extensible Plugin Architecture - Easily add new data sources beyond Git, GitHub, and ADRs
• Comprehensive Knowledge Graph - Build a local graph from Git commits, GitHub PRs, issues, and ADRs
• Trace History Algorithm - Fast BFS algorithm to trace history from file+line to related entities
• High Performance - Trace history queries complete in under 200ms (typically ~100μs)
• Incremental Builds - Efficiently update the graph with only new data
• Rich CLI - Command-line interface for building graphs and tracing history
• Privacy-First - All data stays on your machine; no code or IP leaves your repo
• 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

# Trace history for a specific file and line
arc trace file path/to/file.py 42

# Trace with more hops in the graph
arc trace file path/to/file.py 42 --max-hops 3

Documentation

CLI Commands

• Authentication - GitHub authentication commands
• Build - Building the knowledge graph
• Trace - Tracing history for files and lines
• Doctor - Checking graph status and diagnostics

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 SDK) - Python SDK and CLI for graph building and querying

   • Plugin Architecture - Extensible system for adding new data sources
   • Trace History Algorithm - BFS-based algorithm for traversing the knowledge graph
   • CLI Commands - Interface for building graphs and tracing history

2. arc-memory-mcp - Local daemon exposing API endpoints (future milestone)

   • Will provide HTTP API for VS Code extension and other tools
   • Will be implemented as a static binary in Go

3. vscode-arc-hover - VS Code extension for displaying decision trails (future milestone)

   • Will integrate with the MCP server to display trace history
   • Will provide hover cards with decision trails

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 unittest discover

# Run integration tests
python -m unittest discover tests/integration

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

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

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

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"

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.

Publishing to PyPI

To publish the package to PyPI:

# Build the package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Users can then install the package with:

# Using pip
pip install arc-memory

# Using uv
uv pip install arc-memory

License

MIT