Introduction to Contextia

AI coding agents are powerful, but they have a fundamental limitation: they operate without structured knowledge of your project. They can read files, grep through code, and guess at conventions, but they have no reliable way to understand why your system is designed the way it is, what contracts govern its behavior, or which decisions constrain implementation choices.

Contextia solves this by providing a structured, deterministic context layer for AI-assisted software development.

The problem: AI agents lack architectural memory

When you ask an AI agent to implement a feature, it faces a cold-start problem. It does not know:

• What your system’s behavioral contracts are (specs)
• What architectural decisions have been made and why (decisions)
• What coding norms your team follows (norms)
• What the current task requires and what specs it touches (tasks)

Most approaches to this problem rely on semantic search or RAG pipelines — embedding your documentation and hoping the right chunks surface at query time. This is probabilistic. It works sometimes. It fails silently when it does not.

Contextia takes a different approach: deterministic context assembly. Instead of searching for relevant context, you declare it. Specs link to decisions. Tasks link to specs. Code annotations link back to specs. When an agent starts a task, Contextia follows these explicit links and assembles exactly the context that task requires — no embeddings, no similarity scores, no guessing.

What Contextia is

Contextia is three things:

1. An information architecture — a structured way to organize project knowledge into typed Markdown artifacts with YAML frontmatter
2. A CLI tool (contextia) — for humans to bootstrap, maintain, and validate that architecture
3. An MCP server (contextia-mcp) — for AI agents to query and navigate that architecture directly via the Model Context Protocol

All three operate on the same .contextia/ directory in your project root. Everything is plain Markdown, version-controlled alongside your code.

The two-layer model

Contextia organizes project knowledge into two layers with different lifecycles:

System knowledge (durable)

System knowledge persists across tasks and evolves slowly. It represents the accumulated understanding of your project:

• Identity — what the project is, its purpose, its constraints
• Specs — behavioral contracts that define what the system should do
• Decisions — architectural choices with rationale, constraints, and alternatives considered
• Norms — coding conventions, style rules, and team agreements

.contextia/system/
├── identity.md
├── specs/
│   ├── SPEC-001-user-authentication.md
│   ├── SPEC-002-payment-processing.md
│   └── SPEC-003-notification-service.md
├── rationale/
│   ├── DEC-001-database-choice.md
│   └── DEC-002-api-versioning.md
└── norms/
    ├── error-handling.md
    └── testing-conventions.md

Operational work (transient)

Operational work has a lifecycle tied to specific work items. It is created, executed, and eventually archived:

• Tasks — work orders that reference specs, track status, and accumulate session logs
• Plans — step-by-step execution plans generated for a task
• Session logs — timestamped records of what an agent did during a work session
• Proposals — spec changes suggested by an agent, staged for human review

.contextia/work/
├── tasks/
│   ├── TASK-042-add-email-verification.md
│   └── TASK-043-fix-rate-limiting-bug.md
└── active/
    └── TASK-042/
        ├── plan.md
        ├── session-2026-03-01.md
        └── proposals/
            └── SPEC-001-add-email-field.md

The separation is deliberate. Specs survive long after the tasks that created them are archived. A decision made six months ago still constrains today’s implementation. The two-layer model ensures durable knowledge is never entangled with transient work state.

The dual interface

Contextia provides two interfaces on the same core logic:

CLI — for humans

The CLI is the primary tool for bootstrapping and maintaining your context architecture. You use it to initialize projects, create new artifacts, validate link integrity, and inspect traceability:

contextia init                    # Bootstrap .contextia/ directory
contextia new spec                # Create a new spec from template
contextia find "authentication"   # Search across all artifacts
contextia check                   # Validate links, schemas, coverage
contextia trace src/auth/         # Show full traceability for a path

The CLI outputs human-friendly, colorized text by default, with --format json and --format context for machine and LLM consumption respectively.

MCP server — for AI agents

The MCP server exposes the same core functions as tools that AI agents call directly through the Model Context Protocol. No copy-paste, no manual context injection:

• find_spec — search for specs by title, tag, or path
• load_context — assemble full context for a task (follows all links)
• read_spec — load a spec at a chosen depth (meta, summary, or full)
• write_session_log — record agent actions for continuity
• propose_spec_change — stage a spec modification for human review
• check — validate the project’s context architecture

The MCP server inherits its working directory from the client (Claude Code, Cursor, VS Code) and automatically discovers the project root by walking up the directory tree looking for .contextia/config.yaml — exactly like git finds .git/.

Note

The CLI and MCP server share the same core library. They never duplicate logic. The CLI formats output for terminal display; the MCP server formats output for LLM consumption. Both call the same underlying functions.

Key principles

Contextia is built on a set of design principles that distinguish it from other approaches to AI-assisted development:

Deterministic over probabilistic

Context assembly follows explicit links, not similarity scores. When you run contextia context TASK-042, it resolves the task’s spec references, follows each spec’s decision links, includes applicable norms, and returns exactly that set. The result is the same every time, regardless of embedding quality or chunk size.

Markdown over custom formats

Every artifact is a Markdown file with YAML frontmatter. You can read and edit them in any text editor. They render natively on GitHub. They diff cleanly in pull requests. Contextia adds automation and validation on top of a format you already know — it never locks you in.

Explicit links over semantic search

A task declares which specs it implements. A spec declares which decisions constrain it. Code annotations declare which spec a function fulfills. These links are typed, directional, and verifiable. contextia check can tell you when a link is broken, when a spec has no implementing code, or when code references a spec that does not exist.

Specs separate from tasks

Behavioral contracts (specs) live in system/ and persist independently from work orders (tasks) in work/. A spec may be referenced by dozens of tasks over its lifetime. This separation ensures that your system’s behavioral documentation is never lost when a task is archived.

Human review of AI changes

When an AI agent working on a task discovers that a spec needs to change, it does not modify the spec directly. Instead, it writes a proposal to work/active/{task}/proposals/. A human reviews and promotes the change. This preserves human authority over system-level contracts.

Tip

Contextia is not a replacement for documentation, issue trackers, or ADR tools. It is a structured bridge between those human artifacts and the AI agents that need to understand them. Use it alongside your existing workflow, not instead of it.

How it fits together

Here is the flow for a typical task:

1. A developer creates a task (contextia new task) that references one or more specs
2. An AI agent receives the task and calls load_context via MCP to get the full context: the task, its linked specs, their constraining decisions, and applicable norms
3. The agent generates a plan and begins implementation, logging its actions via write_session_log
4. If the agent discovers a spec needs updating, it calls propose_spec_change to stage a proposal
5. The developer reviews proposals, promotes approved changes, and runs contextia check to verify everything is consistent
6. The task is marked complete. The specs, decisions, and norms persist for the next task

This cycle keeps the AI agent informed, the human in control, and the project’s knowledge growing with every completed task.

Next steps

Ready to get started? Head to the Installation guide to set up Contextia, then follow the Quickstart tutorial to initialize your first project.