# ACO — Agent Context OS

A continuous engineering knowledge compiler and MCP runtime.

ACO ingests your existing engineering docs — ADRs, OpenAPI specs, AI-generated analyses, Markdown, PDFs, Word docs, Notion pages, GitHub Wikis, Confluence spaces, Obsidian vaults — compiles them into typed, code-anchored **Knowledge Objects**, detects when your code drifts away from documented decisions, and serves structured context to AI coding agents via MCP.

```
docs/adr/*.md  ──┐
openapi.yaml   ──┤
notion pages   ──┤
confluence     ──┤  aco compile  ──►  Knowledge Graph  ──►  AI Agent context
obsidian vault ──┤                    (typed, anchored,      (via MCP or CLI)
pdf/docx       ──┤                     drift-detected,
ai-exports/    ──┘                     semantically indexed)
```

---

## Table of Contents

- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Standalone Usage](#standalone-usage)
- [LLM-based Extraction](#llm-based-extraction)
- [Vector Embeddings + Semantic Search](#vector-embeddings--semantic-search)
- [Usage with Claude Code (MCP)](#usage-with-claude-code-mcp)
- [Migrating to a New Machine](#migrating-to-a-new-machine)
- [Core Concepts](#core-concepts)

---

## Requirements

- Python 3.12+
- [`uv`](https://docs.astral.sh/uv/) — `brew install uv` or `pip install uv`

---

## Installation

### Option A — uv tool (recommended, global install)

```bash
git clone https://github.com/<your-username>/aco.git
cd aco
uv tool install .
aco --help
```

### Option B — editable install in virtualenv

```bash
git clone https://github.com/<your-username>/aco.git
cd aco
uv sync
uv run aco --help
```

### Option C — pipx

```bash
git clone https://github.com/<your-username>/aco.git
pipx install ./aco
aco --help
```

---

## Quick Start

```bash
# 1. Initialize a workspace pointing at your project
aco workspace init /path/to/your/project --name "My Project"
# → Workspace created: ws_abc123...

# 2. Add a knowledge source
aco source add --workspace ws_abc123 \
  --connector builtin/local-fs \
  --name "ADRs" \
  --root /path/to/your/project/docs/adr \
  --globs "**/*.md"

# 3. Compile
aco compile run --workspace ws_abc123

# 4. See what was found
aco knowledge list --workspace ws_abc123

# 5. Get a context pack
aco assembly compose --workspace ws_abc123 \
  --role coder \
  --goal "implement the payment service" \
  --path src/payments/handler.py
```

---

## Standalone Usage

### Workspace management

```bash
aco workspace init /path/to/project --name "My Project"
aco workspace list
aco workspace info --workspace ws_<id>
aco workspace remove ws_<id> --confirm
```

### Sources

ACO supports six built-in connectors and two additional file parsers:

| Connector | Use case |
|---|---|
| `builtin/local-fs` | Local Markdown, ADRs, OpenAPI specs, PDFs, Word docs |
| `builtin/ai-export` | Exported ChatGPT / Claude / Cursor conversations |
| `builtin/notion` | Notion workspace pages and databases |
| `builtin/github-wiki` | GitHub Wiki pages |
| `builtin/confluence` | Confluence space pages (Cloud or Server) |
| `builtin/obsidian` | Obsidian vault — resolves wiki links, tags, backlinks |

**Supported file types:** `.md`, `.yaml`/`.json` (OpenAPI), `.pdf`, `.docx`

```bash
# Local filesystem (auto-detects PDF/docx by MIME type)
aco source add --workspace ws_<id> \
  --connector builtin/local-fs \
  --name "Docs" \
  --root docs/ \
  --globs "**/*.md" "**/*.pdf" "**/*.docx"

# AI export archive
aco source add --workspace ws_<id> \
  --connector builtin/ai-export \
  --name "AI Exports" \
  --archive-path /path/to/exports.tar.gz

# Notion workspace
aco source add --workspace ws_<id> \
  --connector builtin/notion \
  --name "Notion Docs" \
  --token secret_xxx \
  --database-id db_id_1

# GitHub Wiki
aco source add --workspace ws_<id> \
  --connector builtin/github-wiki \
  --name "Wiki" \
  --token ghp_xxx \
  --repo owner/repo-name

# Confluence (API token)
aco source add --workspace ws_<id> \
  --connector builtin/confluence \
  --name "Confluence" \
  --base-url https://company.atlassian.net \
  --token base64token \
  --space-key TEAM

# Confluence (cookie file — e.g. from sap-auth-mcp)
aco source add --workspace ws_<id> \
  --connector builtin/confluence \
  --name "SAP Wiki" \
  --base-url https://wiki.company.com \
  --cookie-file ~/.cookies/wiki.json \
  --space-key ENG

# Obsidian vault
aco source add --workspace ws_<id> \
  --connector builtin/obsidian \
  --name "My Vault" \
  --vault-path /path/to/obsidian-vault

aco source list --workspace ws_<id>
aco source fetch --workspace ws_<id>   # re-fetch without full compile
```

### Compiling

```bash
aco compile run --workspace ws_<id>              # full pipeline (includes embed)
aco compile run --workspace ws_<id> --stage fetch  # single stage
aco compile run --workspace ws_<id> --stage embed  # re-embed only
aco compile status --workspace ws_<id>
aco compile logs <job_id>
```

### Knowledge objects

ACO extracts 10 object types: `ArchitectureDecision`, `Requirement`, `Constraint`, `APISpec`, `Runbook`, `GlossaryTerm`, `Risk`, `QualityAttribute`, `TechDependency`, `DesignInsight`.

```bash
aco knowledge list --workspace ws_<id>
aco knowledge list --workspace ws_<id> --type ArchitectureDecision --status ACTIVE
aco knowledge show <object_id>
aco knowledge approve <object_id>   # promote REVIEW_REQUIRED → ACTIVE
aco knowledge reject <object_id>
aco knowledge verify --workspace ws_<id>   # manual drift check
```

### Review queue

AI-generated objects (`DesignInsight`) always land in `REVIEW_REQUIRED` before becoming active:

```bash
aco review list --workspace ws_<id>
aco review show <review_id>
aco review approve <review_id>
aco review reject <review_id> --reason "outdated"
aco review approve-all --workspace ws_<id> --type DesignInsight --confirm
```

### Assembly — context packs for agents

```bash
aco assembly compose --workspace ws_<id> \
  --role coder \
  --goal "refactor the auth module" \
  --path src/auth/handler.py \
  --path src/auth/models.py \
  --budget 8000 \
  --format markdown   # or json, xml
```

**Roles:** `coder` · `reviewer` · `architect` · `debugger` · `security`

Each role shapes the same Knowledge Objects differently — a `coder` pack emphasises implementation anchors and constraints; a `reviewer` pack emphasises decision rationale and risks.

### Continuous compilation via git hooks

```bash
# Install — writes a post-commit hook into your project's .git
aco hooks install --workspace ws_<id> --git-dir /path/to/project/.git

# Every commit now auto-runs drift detection.
# Objects whose anchored code has changed move to DRIFTED.

# Remove
aco hooks remove --git-dir /path/to/project/.git
```

### Portability

```bash
# Export full workspace state to a portable archive
aco pack export --workspace ws_<id> --out ~/backups/my-project.acopack.tar.gz

# Import on any machine
aco pack import ~/backups/my-project.acopack.tar.gz
```

---

## Usage with Claude Code (MCP)

ACO exposes a full MCP server over stdio, giving Claude Code access to your Knowledge Graph as tools.

### 1. Configure Claude Code

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aco": {
      "command": "aco",
      "args": ["mcp-serve", "--workspace", "ws_<your-workspace-id>"]
    }
  }
}
```

If you installed via `uv` without global install:

```json
{
  "mcpServers": {
    "aco": {
      "command": "uv",
      "args": ["run", "aco", "mcp-serve", "--workspace", "ws_<id>"],
      "cwd": "/path/to/aco"
    }
  }
}
```

Restart Claude Code — the ACO tools appear under `/mcp`.

### 2. Available MCP tools

| Tool | What it does |
|---|---|
| `assembly.compose` | Get a token-budgeted context pack for the current task |
| `knowledge.list` | List Knowledge Objects by type / status |
| `knowledge.get` | Full object detail with provenance |
| `knowledge.approve` / `reject` | Review AI-generated objects |
| `knowledge.verify` | Trigger drift detection |
| `review.list` / `approve` / `reject` | Manage the review queue |
| `compiler.run` | Trigger a compile job |
| `compiler.status` | Check job progress |
| `task.create` / `session.start` / `artifact.save` | Track agent work |
| `workspace.info` / `source.list` | Inspect workspace state |

### 3. Typical session flow

**Before starting work:**
> "Use `assembly.compose` with role=coder, goal='implement rate limiting', focal_paths=['src/api/middleware.py'] to get relevant context."

Claude receives a structured pack of Architecture Decisions, Constraints, and API Specs anchored to that file — injected as context for the session.

**After committing:**

The git hook auto-detects drift. Claude can check:
> "Run `knowledge.verify` to see if any Knowledge Objects drifted."

**Reviewing AI insights:**
> "Show me the review queue and approve the DesignInsight objects."

---

## Migrating to a New Machine

ACO state lives entirely in `~/.aco/` — the workspace directory itself is not touched. Migration is straightforward.

### Method 1: Pack export/import (recommended)

```bash
# On the old machine — export each workspace
aco workspace list   # note workspace IDs
aco pack export --workspace ws_<id> --out ~/ws-myproject.tar.gz

# Copy to new machine
scp ~/ws-myproject.tar.gz newmachine:~/

# On the new machine — install ACO, then import
aco pack import ~/ws-myproject.tar.gz

# Re-register the workspace path (the registry stores the absolute path to your project)
aco workspace list   # verify it imported
```

> **Note:** After import, if your project lives at a different path on the new machine, update the registry:
> ```bash
> # Edit ~/.aco/registry.json — change the "path" value for your workspace ID
> ```

### Method 2: Copy state root directly

```bash
# On the old machine
tar -czf aco-state.tar.gz ~/.aco/

# Copy and restore on new machine
scp aco-state.tar.gz newmachine:~/
ssh newmachine "tar -xzf ~/aco-state.tar.gz -C ~/"
```

Then update any absolute paths in `~/.aco/registry.json` if your project directory differs.

### What state is preserved

| Preserved | Not preserved |
|---|---|
| All Knowledge Objects + versions | Git hooks (re-install with `aco hooks install`) |
| Provenance records | Virtual environments / uv cache |
| Review queue | |
| Compiler job history | |
| Context items + projections | |
| Workspace manifest + config | |

### Re-installing ACO on the new machine

```bash
git clone https://github.com/<your-username>/aco.git
cd aco
uv tool install .
aco workspace list   # your workspaces are back
```

---

## Core Concepts

| Concept | Description |
|---|---|
| **Knowledge Source** | Registered origin — a local directory, OpenAPI file, or AI export archive |
| **Document** | Original file fetched from a source, versioned by SHA-256 |
| **Knowledge Object** | Typed, structured fact extracted from documents (Decision, Constraint, API, etc.) |
| **Object Anchor** | Link from a Knowledge Object to a code location; drives drift detection |
| **Context Item** | Assembly-ready prompt fragment projected from a Knowledge Object |
| **Assembly Pack** | Token-budgeted bundle of Context Items composed for a specific agent role and task |
| **Drift** | An Object Anchor's code SHA changed — the object moves to `DRIFTED` until reviewed |
| **State root** | `~/.aco/` — all ACO state; zero files written to your project repo |

### Object lifecycle

```
DRAFT → ACTIVE          (rule/human-extracted, passes validation)
DRAFT → REVIEW_REQUIRED (AI-extracted — always requires human approval)
ACTIVE → DRIFTED        (anchored code changed)
DRIFTED → REFRESHING    (refresh triggered)
REFRESHING → ACTIVE     (human approves updated version)
```

---

## LLM-based Extraction

Use an LLM (Claude or OpenAI) to extract Knowledge Objects from unstructured documents — meeting notes, Notion pages, Confluence articles — where there's no MADR or OpenAPI structure to parse.

**Install the LLM extras:**

```bash
uv sync --extra anthropic   # Claude
uv sync --extra openai      # OpenAI
uv sync --extra llm         # both
```

**Configure a source to use LLM extraction:**

```bash
aco source add --workspace ws_<id> \
  --connector builtin/local-fs \
  --name "Meeting Notes" \
  --root docs/meetings \
  --globs "**/*.md"
```

Then edit the source config in `~/.aco/workspaces/<ws_id>/metadata.sqlite` to add the `extractor` key, or use `aco source add --config-json`:

```json
{
  "root": "docs/meetings",
  "globs": ["**/*.md"],
  "exclude": [],
  "extractor": "builtin/llm",
  "provider": "anthropic",
  "model": "claude-sonnet-5",
  "api_key_env": "ANTHROPIC_API_KEY",
  "object_types": ["Requirement", "Constraint", "Risk", "GlossaryTerm"],
  "max_objects_per_doc": 20
}
```

All LLM-extracted objects land in `REVIEW_REQUIRED` automatically — they require human approval before entering the Knowledge Graph.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
aco compile run --workspace ws_<id>
aco review list --workspace ws_<id>
aco review approve-all --type Constraint --confirm
```

---

## Vector Embeddings + Semantic Search

Enable semantic similarity search so `assembly compose` can find relevant Knowledge Objects even when they don't share code anchors with the files you're working on.

**Add to your `~/.aco/workspaces/<ws_id>/manifest.toml`:**

```toml
[embeddings]
enabled = true
provider = "anthropic"           # or "openai"
model = "voyage-3"               # text-embedding-3-small for OpenAI
api_key_env = "ANTHROPIC_API_KEY"
dimensions = 1024
similarity_threshold = 0.75
max_semantic_candidates = 10
```

**Compute embeddings:**

```bash
aco compile run --workspace ws_<id> --stage embed
# or included automatically in a full compile:
aco compile run --workspace ws_<id>
```

Once indexed, `assembly compose` automatically uses semantic retrieval when `goal` is provided and the manifest has embeddings enabled — no extra flags needed:

```bash
aco assembly compose --workspace ws_<id> \
  --role coder \
  --goal "implement rate limiting for the auth service"
# → finds relevant Constraints, Risks, and Architecture Decisions
#   even if they're not anchored to the exact file you're editing
```

---


## Core Concepts

| Concept | Description |
|---|---|
| **Knowledge Source** | Registered origin — local directory, Notion workspace, GitHub Wiki, Confluence space, AI export |
| **Document** | Original file fetched from a source, versioned by SHA-256 |
| **Knowledge Object** | Typed, structured fact extracted from documents (Decision, Constraint, API, etc.) |
| **Object Anchor** | Link from a Knowledge Object to a code location; drives drift detection |
| **Context Item** | Assembly-ready prompt fragment projected from a Knowledge Object |
| **Assembly Pack** | Token-budgeted bundle of Context Items composed for a specific agent role and task |
| **Drift** | An Object Anchor's code SHA changed — the object moves to `DRIFTED` until reviewed |
| **State root** | `~/.aco/` — all ACO state; zero files written to your project repo |

### Object lifecycle

```
DRAFT → ACTIVE          (rule/human-extracted, passes validation)
DRAFT → REVIEW_REQUIRED (AI-extracted — always requires human approval)
ACTIVE → DRIFTED        (anchored code changed)
DRIFTED → REFRESHING    (refresh triggered)
REFRESHING → ACTIVE     (human approves updated version)
```

---

## Deferred (v0.12+)

- Cross-workspace federation
- Vector store backend for workspaces with >10k objects
- PDF/docx image extraction
- Obsidian Canvas files (`.canvas`)
- Notion/GitHub Wiki/Confluence/Obsidian watch mode (real-time sync)
- OpenTelemetry