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
• Installation
• Quick Start
• Standalone Usage
• LLM-based Extraction
• Vector Embeddings + Semantic Search
• Usage with Claude Code (MCP)
• Migrating to a New Machine
• Core Concepts

---

Requirements

• Python 3.12+
• uv — brew install uv or pip install uv

---

Installation

Option A — uv tool (recommended, global install)

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

Option B — editable install in virtualenv

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

Option C — pipx

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

---

Quick Start

# 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

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

# 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

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.

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:

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

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

# 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

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

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

If you installed via uv without global install:

{
  "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)

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

# Edit ~/.aco/registry.json — change the "path" value for your workspace ID

Method 2: Copy state root directly

# 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

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:

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

Configure a source to use LLM extraction:

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:

{
  "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.

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:

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

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:

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