Axi Series

AxiContext

Open Source

Project context controller for AI coding agents. Generates and maintains PROJECT_CONTEXT.md and a SQLite Context Graph.

Quick start

Start with the primary command, then continue with the full workflow below.

pnpm install

Problem

AI coding agents re-read the same files every session, burning context tokens on repeated scans of the whole repo instead of recalling what they already know. A flat CONTEXT.md loses the connections between modules, APIs, tests, and configs, and it silently goes stale as the codebase changes - agents keep acting on outdated context until it causes bugs. Agents have no cheap way to ask a targeted question (what does the auth module do?) without parsing a huge context document or grepping source files. The result: incoherent agents across sessions, wasted context budget, and stale-context errors that are hard to trace to a root cause.

Solution

AxiContext generates and maintains PROJECT_CONTEXT.md, a SQLite Context Graph under .axicontext/, and a local Agent Read API so agents query structured project memory with provenance - instead of re-reading the entire repo every time. The architectural choice is a graph, not a flat file: a SQLite Context Graph preserves relationships between modules, APIs, tests, and configs, with every excerpt provenance-tracked (source file, last sync timestamp, drift status). A git source adapter ingests project structure from git metadata with zero manual config, axictx sync ingests sources, updates the graph, and regenerates the markdown in one command, and axictx drift compares declared state against the live filesystem. It is OSS-first, MIT-licensed, with zero external dependencies and no Docker.

How it works

Install and build the pnpm monorepo: pnpm install then pnpm build.

In any git repository, scaffold the setup: pnpm --filter @latticeag/axicontext start -- init - creates .axicontext/ and PROJECT_CONTEXT.md (config at .axicontext/config.toml, managed by axictx init --overwrite-config).

Ingest sources and build the graph: pnpm --filter @latticeag/axicontext start -- sync - the Git Source Adapter reads git metadata, builds the SQLite Context Graph, and regenerates PROJECT_CONTEXT.md in a single command (flags include --repo-root, --max-chars, --max-files, --max-lines-per-file, --fail-on-drift).

Check for staleness: pnpm --filter @latticeag/axicontext start -- drift - compares the graph manifest against the live filesystem; --format json|md, --ci for GitHub Actions annotations, --fail-on-drift to exit with code 2.

Validate the setup: axictx doctor (Node.js 22+ required).

Start the Agent Read API: pnpm --filter @latticeag/axicontext start -- serve - a Hono server on http://127.0.0.1:8787 with --port and --host flags and optional API token auth via Authorization or x-api-token.

Query the graph: axictx query "auth middleware" (FTS5 ranked excerpts, --max-tokens budget, --json), or hit the HTTP API: GET http://127.0.0.1:8787/v1/context/slice?topic=authentication&max_tokens=2000.

Point Cursor, Claude Code, or Copilot at PROJECT_CONTEXT.md or the local API - any agent that can read a file or hit an HTTP endpoint.

Technical architecture

Each handoff carries structured context through the product's execution path. Hover a node to inspect its role.

Init

Step 1: Init receives structured context from the prior stage and prepares it for the next handoff.

Sync

Step 2: Sync receives structured context from the prior stage and prepares it for the next handoff.

Build Graph

Step 3: Build Graph receives structured context from the prior stage and prepares it for the next handoff.

Generate Document

Step 4: Generate Document receives structured context from the prior stage and prepares it for the next handoff.

Detect Drift

Step 5: Detect Drift receives structured context from the prior stage and prepares it for the next handoff.

Serve API

Step 6: Serve API receives structured context from the prior stage and prepares it for the next handoff.

Query Context

Step 7: Query Context receives structured context from the prior stage and prepares it for the next handoff.

When to use

Your coding agents re-scan the same files every session and you want them to start each session already informed.
You want live drift detection that surfaces context inconsistency before it causes bugs.
You want agents to query structured project memory (what does the auth module do?) instead of parsing a huge markdown string or grepping source.
You want provenance-tracked project context - you know which file every excerpt came from and whether it's stale.
You're working in any git repo, with any agent (Cursor, Claude Code, Copilot), and want a local, zero-dependency context layer.

Not for

Non-git projects - the source adapter is git-based and understands structure from git metadata.
Teams that need a hosted/cloud context service - AxiContext is local-first; everything runs on 127.0.0.1.
A substitute for agent memory - it's a project knowledge store with provenance, not a session memory system.
Running sync and serve concurrently on the same graph (SQLite locking can cause SQLITE_BUSY); first sync on huge monorepos can take 30-60s.

Features

SQLite Context Graph - preserves module relationships, API contracts, and config structure (not a flat file)

PROJECT_CONTEXT.md - auto-generated markdown summary for agents that prefer static file intake

Drift detection - axictx drift compares the graph manifest against the live filesystem, flags stale or missing entries

Full-text search - ranked FTS5 search over all context excerpts via axictx query

Git Source Adapter - understands project structure from git metadata, no manual config

Agent Read API - local Hono HTTP server at 127.0.0.1:8787 with topic filtering and max_tokens budgeting

Provenance tracking - every excerpt knows its source file, sync timestamp, and drift status

Incremental sync - only re-processes changed files since the last sync

Zero dependencies - self-contained SQLite-backed CLI, no Docker, no external services

Full CLI - axictx init, doctor, sync, drift, query, serve, status

Framework-agnostic - integrates with Cursor, Claude Code, Copilot, or any agent that can read a file or hit an HTTP endpoint

CI-ready drift - GitHub Actions annotations (--ci) and --fail-on-drift exit code 2 for pipelines

OpenAPI spec - GET /v1/openapi.json documents the full Agent Read API

Optional token auth - apiToken / x-api-token gate on /v1/* routes when configured

HTTP endpoints - GET /healthz, GET /v1/manifest, GET /v1/context (cursor/limit paging), GET /v1/context/slice (topic, depth, max_tokens), POST /v1/context/query, GET /v1/drift

Install and usage

usage.sh

# Install and build
pnpm install
pnpm build

# In any git repository:
pnpm --filter @latticeag/axicontext start -- init
pnpm --filter @latticeag/axicontext start -- sync
pnpm --filter @latticeag/axicontext start -- drift
pnpm --filter @latticeag/axicontext start -- serve

# Validate setup (Node.js 22+)
axictx doctor

# Query the graph from the CLI
axictx query "auth middleware" --max-tokens 2000

# Or query the local Agent Read API
curl "http://127.0.0.1:8787/v1/context/slice?topic=authentication&max_tokens=2000"

# Point Cursor or Claude Code at PROJECT_CONTEXT.md, or the local API

Architecture explorer

Problem

Solution

View on GitHub