ARIA — Applied Reasoning and Insight Architecture

ARIA — Applied Reasoning and Insight Architecture

Agent Memory · Context Engineering · Planning & Reasoning · Human-in-the-Loop Governance

ARIA is the missing infrastructure layer for production AI coding agents: persistent memory that survives context compaction, deliberate context engineering that loads the right knowledge before action, human-governed trust gates that keep AI from acting on noise, and structured session discipline that gives agents the continuity needed for long-horizon reasoning.

The AI captures. The human promotes. Trusted knowledge acts.

New to ARIA? See QUICKSTART.md — 5-minute setup + best practices by session phase.

ARIA is a local-first knowledge and execution-discipline layer for AI coding sessions. It ships as a family of ports — Claude Code (plugin-claude-code/), Claude Cowork (plugin-claude-cowork/), OpenAI Codex (plugin-openai-codex/), Antigravity (plugin-antigravity/), and Cursor (plugin-cursor-template/) — all sharing the same ~/Projects/knowledge/ folder. Insights captured in one tool flow into another. The folder itself is plain markdown — readable by any AI, any human, any editor, with or without ARIA installed.

ARIA manages a complete knowledge lifecycle: it captures insights, decisions, and feedback during sessions; stages them in backlogs for human review; promotes what matters into a searchable, tag-indexed knowledge base; and applies that trusted knowledge back into future tasks, edits, and handoffs. Session hooks prevent knowledge loss during context compaction, surface relevant knowledge when tasks are created, and enforce a visible change decision framework at every file edit.

Why ARIA

Production AI coding agents do not usually fail because the model is incapable. They fail because the working system around the model is incomplete. ARIA addresses four failure modes that repeatedly break agentic work in practice.

Agent Memory

Every session starts from zero. Context compaction erases decisions. Debugging discoveries disappear into transcripts. The next session reopens questions that were already settled.

ARIA gives your agent persistent, structured memory across sessions and across tools. It captures insights during work, stages them for review, and builds a durable knowledge base that survives session boundaries.

Context Engineering

What the model sees determines what it does. Most teams still treat this as an ad hoc prompt-writing problem.

ARIA engineers context deliberately. It surfaces relevant knowledge at task creation time, loads project-specific rules and patterns before edits, and grounds work with artifacts like code maps, cross-repo stitch tables, and repository-aware task specs — so the model always acts on current, accurate context rather than assumptions.

Planning & Reasoning

Long-horizon work fails when the agent loses continuity between decisions, constraints, and active workstreams.

ARIA does not implement planning algorithms. It solves the continuity layer planning depends on: /distill turns tickets into grounded task specs that cite real files, /codemap gives structural codebase awareness, /stitch builds cross-repo bindings, and /handoff preserves full session state so reasoning chains do not break at session boundaries.

Human-in-the-Loop Governance

Auto-memory tools drift. They accumulate noise alongside signal, and the model eventually acts on unreviewed assumptions.

ARIA keeps humans in the loop. The AI captures candidate knowledge, but humans review and promote what becomes trusted. Audit logs and disposition history live in your own repo under git — not a vendor dashboard. Every promotion is explicit and traceable.

The Core Idea

Most memory tools help an assistant remember more. ARIA goes further: it asks what knowledge is worth trusting, how it should be reviewed, and how trusted knowledge should actively shape the next decision, task, and code change.

That is the difference between passive memory and applied operational knowledge.

How It Works

Knowledge moves through a five-phase lifecycle: Capture → Govern → Promote → Apply → Refresh.

Capture

Preserve session knowledge before context evaporates.

• /extract — Scan conversations for uncaptured insights, decisions, feedback, references, and ideas. Deduplicates against existing entries.
• /ask — Research a question, check existing knowledge first, save the answer directly as a knowledge doc.
• /intake — Capture knowledge from outside the conversation. A single URL or text snippet clips whole to intake/clippings/; files/dirs/globs bulk-scan into the backlogs; /intake extract <source> decomposes a source (incl. a Notion/Confluence/Google Doc via a connected ~~docs MCP) into backlog entries; /intake doc <url-or-title> (v2.17.0+) captures one structured 5-section artifact + user reaction; /intake thread <id> (v2.33.0+) pulls a chat/email thread via a connected ~~chat/~~email MCP. (v2.33.0 consolidated three former standalone capture skills — quick-clip, thread-capture, and doc-extract — into these /intake modes.)
• /interview <mode> (v2.31.0+) — Elicit knowledge through dialogue rather than harvesting it. Three modes: project (scope a new build), knowledge (get a topic out of your head into the KB), deep-dive (extract the rationale behind something you already built — requires a basis via --ground). Cadence (one-at-a-time socratic vs research-then-batch battery) is chosen in-session. Stages to intake/projects|interviews/ for manual review.

Govern

Convert raw capture into reviewable candidates.

• All captured knowledge stages in a backlog — nothing enters the trusted layer automatically.
• Human review is the gate between capture and promotion.
• Provenance is preserved so every piece of knowledge is inspectable and auditable.

Promote

Move reviewed knowledge into the trusted layer.

• /audit-knowledge (alias /knowledge-audit) — Review staged backlog entries and promote the ones worth trusting into the indexed knowledge base. Promotion happens inside the audit — there is no standalone /promote command.
• Organize by tag, project tier, and cross-project patterns.
• Optional project-specific tier (v2.8.0+) for architecture decisions and patterns.
• Optional non-blocking SessionStart project picker (v2.26.0+) — for multi-project parent dirs, suggests a project menu generated from projects_list and reads the chosen project's CLAUDE.md/PROGRESS.md.

Apply

Make trusted knowledge shape real work.

• TaskCreated hook — Surfaces relevant knowledge files when tasks are created (tag index matching).
• Rule 22 — Change decision framework enforced at every file edit. Requires visible impact assessment and scope verification before and after changes.
• /context — Load relevant knowledge into the current session for immediate use.
• /rules — Surface working rules that apply to the current task.

Codebase and task mapping turn ambiguous surface area into structured artifacts the agent can ground decisions against.

• /codemap — Feature-organized reference for any repository. Scans repos, detects frameworks, traces full-stack flows (routes → hooks → state → views → models → integrations). Four modes: create (full generation), inventory (quick index), update (incremental via git diff), section (rebuild one section).
• /stitch — Cross-repo binding artifact for product groups (backend + frontends). Tables for group identity, auth path, endpoint stitch, entity stitch, integration stitch, and a drift log.
• /distill — Turns raw ticket text into an executable task spec following a TASK.schema.md contract. Auto-tiers by complexity (micro / standard / full). Optional --group flag loads CODEMAP + STITCH context for cited-path specs.
• /auto — Entry point for an autonomous execution arc. A single invocation drives the full chain (brainstorm → spec → /prospect → plan → /prospect → TDD → /retrospect) under the Rule 35 posture, deciding objectively-validatable forks itself and stopping only on a load-bearing fork or an ungranted approval. Modes: /auto [goal] [continue|stop], /auto execute <plan|spec|linear-id>, /auto config (guided one-knob-at-a-time picker). An explicit override of the standing autonomy config (never writes it); three fan-out stopgaps (Workflow opt-in, budget-fraction pre-flight, cumulative subagent cap) guard usage.
• /prospect — Forward-looking pre-mortem on a plan before execution. Per-step actions: PROCEED / SHRINK / SPLIT / DEFER / KILL. Output saved to logs/prospect/.
• /retrospect — Structured retrospective on a shipped commit range, single commit, PR, release, or session. Enforces per-fix validation, surfaces simpler alternatives, runs failure-mode pattern checks. Output saved to logs/retrospect/.
• /recap [arc|commit|push|pull] — Read-only orientation: a scannable What / Where / Status table of recent work — this session by default, or the last arc / commit / push / pull. Summarizes to situate you; never validates (that's /retrospect) and never writes to disk.
• /roadmap [<name>|refresh] — Per-project feature roadmap: a Feature / Band / Status grid (Shipped / Current / Next / Later × done / in-progress / blocked / buildable) synthesized from CLAUDE.md + PROGRESS.md and persisted to a committed ROADMAP.md with source-stamp staleness-aware refresh (renders the persisted grid, then offers a refresh when stale). "Buildable" is the one inference — a Next-band feature with no blocker found, evidence shown, overridable. Writes only ROADMAP.md, never auto-commits.
• /foundational-review — The foundational review chain, run before an irreversible decision (version freeze, format/spec tag, public flip, major re-scope): verdict + named premises + sections A–F → design spec → cold-executable plan with owner routing → composed /prospect (amendments applied in place) → paste-ready executor kickoff. Requires a named irreversible decision (else redirects to /prospect or /readiness-audit). --extend adds the system-design assessment + roadmap chain.
• /readiness-audit — The recurring sibling: a checklist-against-a-surface audit answering "is it clean/legal/consistent to ship for THIS event?" Controller re-verifies every load-bearing agent claim (correction trail), read-only probes only with a mandatory artifact diff-check, tiered evidence-celled findings, phased remediation. No decision anchor needed.

Hooks make application continuous in the background.

• PreToolUse hook on Glob/Grep — Reminds to read CODEMAP.md before exploring a codebase directly. Fires once per project per session.
• PreCompact hook — Saves transcript snapshot before context compaction.
• PostCompact hook — Prompts to review captured snapshot after compaction.
• auto_capture toggle gates all automatic features.

Refresh

Knowledge bases rot when nothing forces review. ARIA treats freshness as a first-class concern.

• Last updated frontmatter on every knowledge file enables mechanical staleness checks.
• Configurable staleness thresholds — ideas_staleness_threshold_days (default 7) for intake/ideas/ entries; staleness_threshold_months for promoted knowledge files.
• Audit cadences enforce periodic review. SessionStart hook prompts when /audit-knowledge is due.
• /audit-config and /audit-knowledge detect drift, staleness, and gaps on configurable cadences.

Ideas Lifecycle (since v2.12)

Ideas — feature proposals, bug reports, design suggestions — flow into intake/ideas/ during /extract. They have a distinct lifecycle from the four knowledge backlogs because they describe what should be different, not what is.

1. Capture — /extract writes one file per idea to intake/ideas/, with YAML frontmatter and a Proposal/Motivation/Source body.
2. Stale-first surfacing — /audit-knowledge sorts stale ideas above fresh ones (default 7 days) and forces explicit disposition on stale entries.
3. Seven-destination Accept submenu — each accepted idea routes to one of: tracker | roadmap | todo | adr | backlog | bundle | rule.
4. Detection-aware routing — roadmap and todo only appear when ROADMAP.md / TODO.md exists; the submenu shrinks per idea.
5. Bundle clustering — when 2+ ideas in the same project share ≥2 significant title words, the audit offers to merge them.
6. ticketing_plugins config — declare your ticket-drafting plugin per project tag and /audit-knowledge prints a one-line hint at Accept → tracker time. Hint only — never auto-invokes another plugin.

Ideas never promote directly into approaches/, decisions/, or rules/. The adr and rule destinations route through their respective backlogs for normal audit-cycle review.

Shared Knowledge Tier (since v2.13)

Personal knowledge captures stay on one developer's laptop. The Shared Knowledge tier adds a third level alongside personal (~/Projects/knowledge/) and project-specific (projects/{tag}/): selected items can be promoted to per-repo _project-knowledge/ folders so teammates working in the same code repo can find and read them. Independent records, not a sync layer — personal copies stay where they are; team copies get committed through normal git/PR review.

1. Per-project opt-in — the projects_shared_knowledge config field is a comma-separated tag list; empty/missing means feature disabled.
2. /audit-share (alias /share-audit) — batch-review surface. Walks personal knowledge folders + IDEAS-BACKLOG.md entries, filters by enabled-project list, recommends destinations grouped by action. Public-repo targets get a sanitization warn-prompt before each write.
3. Folder + filename convention — <project-root>/_project-knowledge/{YYYY-MM-DD}-{author}-{slug}.md; cross-cutting items live in _project-knowledge/cross/. Tool-agnostic so non-ARIA teammates can read/write directly.
4. Frontmatter back-pointers — personal copies gain a shared: array; team copies carry origin:, shared_by:, shared_at:. Provenance both directions.
5. CLAUDE.md reference offer at first-write — /audit-share offers to append a "Team-Shared Knowledge" section so teammates not using ARIA can discover the convention. Three warning tiers based on git-tracked + remote-visibility detection.
6. Read-side via /index + /context — tag-based discovery composes naturally; /context api surfaces team-shared, project, and cross-project files together.

How ARIA Differs

ARIA solves the same high-level problem as markdown wikis, graph-based memory systems, and MCP memory servers — persistent context across sessions — but optimizes for a different outcome: trusted operational knowledge that actively shapes code and decisions.

The shared instinct with Karpathy is strong: markdown as source of truth, human-readable, diffable, no vendor lock-in. ARIA diverges on the central question — who decides what becomes durable knowledge? Karpathy's answer is the LLM, compiling and linting autonomously. ARIA's answer is the human, reviewing LLM-captured candidates during audit.

Basic Memory + MCP memory servers give assistants persistent memory across sessions, often as entities/relations or local markdown notes. They optimize for general-purpose recall and broad compatibility. ARIA is more opinionated and developer-workflow specific: structured backlogs, promotion workflows, audits, codebase maps, cross-repo stitching, task distillation, and Rule 22 edit-time discipline. They can sit alongside ARIA — ARIA curates the trusted-decision tier, generic memory layers handle general recall.

Context Efficiency Over Time

ARIA is designed to improve context efficiency over time, not guarantee lower token usage in any single session. It adds structure in the moment — Rule 22 checks, hooks, extraction, audits, and context surfacing all consume tokens. The benefit appears across repeated work: ARIA reduces context waste by replacing repeated rediscovery with compact, reviewed, task-relevant knowledge.

The goal is not fewer tokens overall — it is fewer tokens spent re-learning the same things, and more tokens applying trusted knowledge to the next task, decision, and code change.

Recommended Setup

/setup runs ARIA with safe defaults. Below is the maintainer's own setup — the low-effort, high-outcome way ARIA is meant to be used day to day. All settings live in ~/.claude/aria-knowledge.local.md and can change any time.

Folder layout

Keep a single Projects/ folder with your knowledge/ folder inside it and every project as a sibling underneath:

Projects/
├── knowledge/          ← ARIA's corpus (back this up / version-control it)
├── project-a/
├── project-b/
└── ...

Run /setup with projects enabled and map each project in projects_list. This one-time layout is what makes /context <tag>, project-scoped knowledge, and CODEMAP/STITCH surfacing "just work" — knowledge is routed to the right project automatically instead of pooling into one undifferentiated heap.

A session, start to finish

1. Start at the Projects/ folder level, naming the project: project-name — or project-name handoff if you're continuing from a previous session (ARIA resumes from the SESSION.md it wrote last time).
2. Spec & plan with Superpowers, then /prospect the plan before executing. Superpowers brings the planning discipline; ARIA's pre-mortem catches the ~3-in-4 plans that need a correction before any code lands.
3. Execute. Rule 22 runs on every edit automatically — no action needed.
4. /retrospect after big or critical executions (auth, migrations, releases, anything with asymmetric cost