How It Works

One directory. All agents. Knowledge that grows.

The .agents/ directory

.agents/
  config.yaml          # project name, stack, description
  rules/
    _capture.md        # how agents should capture knowledge
    *.md               # team conventions, constraints
  knowledge/
    _index.md          # knowledge index (loaded on session start)
    architecture/      # structural decisions with alternatives
    patterns/          # repeating implementation patterns
    lessons/           # bugs where symptom misled the cause
    conventions/       # team conventions not obvious from code
    dependencies/      # non-obvious package choices
    pending/           # auto-captured items awaiting review
  skills/
    _index.md          # skill index
    <name>/SKILL.md    # multi-step workflows
  mcp/
    config.yaml        # MCP server definitions

Session lifecycle

1. Session start

Agent reads AGENTS.md (or CLAUDE.md / .cursorrules), which points to .agents/. It loads config, rules, and the knowledge index. Hooks inject a context digest with accumulated knowledge.

2. During work

The agent works normally. postToolUse hooks log file changes (fast path, <10ms). No LLM calls, no overhead.

3. Session end

The stop hook fires. It collects the session diff (committed + uncommitted + untracked), sends it to a lightweight LLM (Haiku), and extracts knowledge items worth saving. Items land in knowledge/pending/ for human review.

4. Review

agents capture list              # see pending items
agents capture accept <name>     # move to knowledge
agents capture accept --all      # accept all
agents capture reject <name>     # discard

Cross-platform sync

agents sync generates entrypoints optimized for each agent:

AGENTS.md — universal, works with any agent
CLAUDE.md — XML tags, parallel read hints (Claude Code native patterns)
.cursorrules — flat, imperative (Cursor native format)
GEMINI.md — clean markdown for Gemini agents
MCP configs — synced to .claude/, .cursor/, .codex/, .github/

One .agents/ is the source of truth. Everything else is generated.

Knowledge types

Type	When to capture	Example
`architecture`	Chose between alternatives, structural decision	"We use PGLite in dev instead of Postgres because X"
`pattern`	Repeating implementation across multiple files	"To add a new operation, copy skeleton from operations.ts:L50"
`lesson`	Bug where the symptom misled the cause	"contentHash mismatch: utils.ts and import-file.ts use different algorithms"
`convention`	Team convention not obvious from code	"Always use CopilotClientAdapter subclass for new editor MCP targets"
`dependency`	Non-obvious package choice or known workaround	"gray-matter parses YAML dates as Date objects, schema handles it"