aria-knowledge

ARIA — Applied Reasoning and Insight Architecture

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 knowledge-and-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/), and Cursor (plugin-cursor-template/) — all living in this repo and 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.

Both ports installed? When plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare slash commands (/handoff, /wrapup, /extract, etc.) deterministically resolve to plugin-claude-code (the Code-side canonical). For the Cowork variant of any skill, use the namespaced form: /aria-cowork:handoff, /aria-cowork:wrapup, etc. Each colliding skill carries a Runtime Gate that surfaces a notification if invoked from the wrong runtime. See ADR 094 for the full design. ARIA manages a complete knowledge lifecycle — capturing insights, decisions, and feedback during sessions, staging them in backlogs for human review, and promoting what matters into a searchable, tag-indexed knowledge base. Session hooks prevent knowledge loss during context compaction, surface relevant knowledge when tasks are created, and enforce a change decision framework at every file edit, requiring visible impact assessment and scope verification before and after changes. Each session builds on the last instead of starting from scratch.

Beyond capture, ARIA provides active tooling: /codemap generates feature-organized maps that trace full-stack flows; /stitch builds cross-repo binding tables for product groups; /distill turns raw ticket text into tiered executable task specs that cite real files. /ask researches questions and saves answers as knowledge docs. /intake bulk-imports from files, URLs, or directories. /audit-config and /audit-knowledge detect drift, staleness, and gaps on configurable cadences. /wrapup (gated or auto) closes out a session cleanly when you're done — no passoff intended; /handoff (combined-go, auto, or brief) generates a passoff package — paste-ready next-session opener for future-you in a new session, or 80–150 word coworker prose brief. An optional project-specific tier (v2.8.0+) organizes architecture decisions and patterns by project, with cross-project promotion when patterns validate across multiple projects. Everything is plain markdown, works as an Obsidian vault, and follows the core philosophy: the AI captures, the human promotes, trusted knowledge acts.

The problem

AI coding sessions generate valuable knowledge every day. Architecture decisions. Debugging discoveries. Product constraints. Team conventions. Reviewer feedback. Lessons learned the hard way.

Then the session ends. Context gets compacted. Decisions disappear into transcripts. The next session repeats old questions, misses known constraints, or reopens choices already settled.

Most memory tools solve this by helping the assistant remember more. ARIA goes further: it asks what knowledge is worth trusting, how should it be reviewed, and how should that trusted knowledge 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.