agent-notes 2.16.0__tar.gz → 2.18.0__tar.gz

{agent_notes-2.16.0 → agent_notes-2.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-notes
-Version: 2.16.0
+Version: 2.18.0
 Summary: AI agent configuration manager for Claude Code, OpenCode, and Copilot
 Author-email: Eugene Naumov <min.verkligheten@gmail.com>
 License-Expression: MIT
@@ -32,7 +32,7 @@ Dynamic: license-file
 
 AI agent configuration manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://github.com/opencode-ai/opencode).
 
-Configures a Lead agent (Opus) that orchestrates a team of 18 specialized subagents across three model tiers — so Opus plans and reasons, Sonnet executes, and Haiku explores.
+Configures a Lead agent (Opus) that orchestrates a team of 19 specialized subagents across three model tiers — so Opus 4.6 plans and reasons, Sonnet 4.6 executes, and Haiku 4.5 explores.
 
 ## Quick Start
 
@@ -46,8 +46,8 @@ agent-notes doctor
 
 | Component | Description |
 |-----------|-------------|
-| **Skills** | 42 on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
-| **Agents** | 18 specialized AI subagents with hierarchical model strategy |
+| **Skills** | 42+ on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
+| **Agents** | 19 specialized AI subagents with hierarchical model strategy |
 | **Rules** | Global instructions, code quality, and safety guardrails |
 | **Config** | Global instructions for Claude Code, OpenCode, and GitHub Copilot |
 
@@ -86,8 +86,8 @@ Iteration loop: edit source → `python -m build` → `pipx reinstall dist/*.whl
 
 ### 3. Plugin — limited functionality
 
-- **Claude Code**: install via the Claude Code plugin marketplace.
-- **OpenCode**: copy or symlink `.opencode-plugin/` into `~/.config/opencode/plugins/agent-notes/` and add `"plugin": ["agent-notes"]` to `opencode.json`.
+- **Claude Code**: install via the Claude Code plugin marketplace or copy/symlink `.claude-plugin/` into `~/.claude/plugins/agent-notes/`.
+- **OpenCode**: copy or symlink `.claude-plugin/` into `~/.config/opencode/plugins/agent-notes/` and add `"plugin": ["agent-notes"]` to `opencode.json`.
 
 The plugin runs a `session.start` hook that surfaces agent-notes context to the CLI session. It does **not** include the full `agent-notes` CLI (wizard, doctor, config, memory, etc.). For those, use install method 1 or 2.
 
@@ -113,8 +113,8 @@ agent-notes <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `install [--local] [--copy]` | Interactive wizard or direct install |
-| `uninstall [--local]` | Remove installed components |
+| `install [--local] [--copy] [--reconfigure]` | Interactive wizard or direct install |
+| `uninstall [--local \| --global]` | Remove installed components (both scopes by default) |
 | `doctor [--local] [--fix]` | Check installation health |
 | `info` | Show status and component counts |
 | `list [clis\|models\|roles\|agents\|skills\|rules\|all]` | List engine components or installed |
@@ -122,6 +122,7 @@ agent-notes <command> [options]
 | `regenerate [--cli <cli>]` | Rebuild files from state.json (Phase 10+) |
 | `validate` | Lint source configuration files |
 | `memory [list\|size\|show\|reset\|export\|import] [name]` | Manage agent memory |
+| `cost-report` | Show session cost breakdown by agent and model |
 
 ### Supported platforms
 
@@ -152,37 +153,39 @@ agent-notes memory add "Rails enum prefix" \
 
 ## Agent Team
 
-Specialized subagents with hierarchical model strategy: **Opus 4.7 decides, Sonnet 4 executes, Haiku 4.5 explores.**
-
-| Agent | Model | Role |
-|-------|-------|------|
-| **lead** | Opus 4.7 | Plans, delegates, reviews. Orchestrator. |
-| **architect** | Opus 4.7 | System architecture, module boundaries, domain models. Read-only. |
-| **debugger** | Opus 4.7 | Bug investigation: reproduces, isolates, identifies root cause. Read-only. |
-| **coder** | Sonnet 4 | Implements features, fixes bugs, edits files. |
-| **reviewer** | Sonnet 4 | Code quality review. Read-only. |
-| **security-auditor** | Sonnet 4 | Security vulnerability analysis. Read-only. |
-| **test-writer** | Sonnet 4 | Writes tests for any framework. |
-| **test-runner** | Sonnet 4 | Diagnoses and fixes failing tests. |
-| **system-auditor** | Sonnet 4 | Codebase health: duplication, N+1, coupling. Read-only. |
-| **database-specialist** | Sonnet 4 | Schema design, indexes, query performance, migrations. Read-only. |
-| **performance-profiler** | Sonnet 4 | Response times, memory, caching, bundle size. Read-only. |
-| **devops** | Sonnet 4 | Docker, CI/CD, deployment configs. |
-| **devil** | Sonnet 4 | Challenges plans to surface hidden risks. Read-only. |
-| **integrations** | Sonnet 4 | Third-party integrations: OAuth, webhooks, payments. |
-| **refactorer** | Sonnet 4 | Improves code structure without changing behavior. |
-| **analyst** | Haiku 4.5 | Requirements analysis: surfaces missing or contradictory requirements. Read-only. |
-| **api-reviewer** | Haiku 4.5 | API design, versioning, error handling, backward compatibility. Read-only. |
-| **tech-writer** | Haiku 4.5 | Documentation: READMEs, API docs, changelogs. |
-| **explorer** | Haiku 4.5 | Fast file discovery and pattern search. Read-only. |
+Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.**
+
+| Agent | Role | Model Tier | Purpose |
+|---|---|---|---|
+| lead | orchestrator | opus | Plans, coordinates, verifies — the team lead |
+| architect | reasoner | opus | System design, module boundaries, refactor planning |
+| debugger | reasoner | opus | Complex bug investigation, root-cause analysis |
+| coder | worker | sonnet | Implementation, file edits, bug fixes |
+| reviewer | worker | sonnet | Code quality, readability, correctness |
+| security-auditor | worker | sonnet | Auth, injection, XSS, secrets exposure |
+| test-writer | worker | sonnet | Creates tests for any framework |
+| test-runner | worker | sonnet | Diagnoses and fixes failing tests |
+| system-auditor | worker | sonnet | Duplication, dead code, coupling, complexity |
+| database-specialist | worker | sonnet | Schema design, indexes, query performance |
+| performance-profiler | worker | sonnet | Response times, memory, bundle size |
+| api-reviewer | worker | sonnet | REST conventions, versioning, backward compatibility |
+| devops | worker | sonnet | Docker, CI/CD, deployment, infrastructure |
+| devil | worker | sonnet | Devil's advocate — challenges plans and assumptions |
+| integrations | worker | sonnet | OAuth, webhooks, API clients, SSO |
+| refactorer | worker | sonnet | Extracts methods, reduces duplication, improves naming |
+| explorer | scout | haiku | Fast file discovery, pattern search |
+| analyst | scout | haiku | Requirements translation, acceptance criteria |
+| tech-writer | scout | haiku | READMEs, API docs, changelogs |
+
+**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).
 
 ## Architecture
 
-agent-notes is a 4-layer engine (domain / registries / services / commands). All extensible content (CLIs, models, roles, agents, skills, rules) lives in `agent_notes/data/` as YAML — adding a new CLI/model/role is a YAML drop, no Python changes. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ADD_CLI.md](docs/ADD_CLI.md), [docs/ADD_MODEL.md](docs/ADD_MODEL.md), [docs/ADD_ROLE.md](docs/ADD_ROLE.md).
+agent-notes is a 4-layer engine (domain / registries / services / commands). All extensible content (CLIs, models, roles, agents, skills, rules) lives in `agent_notes/data/` as YAML — adding a new CLI/model/role is a YAML drop, no Python changes. Context is loaded in tiers: always-loaded (CLAUDE.md, rules, skill catalog), lazy-loaded (full skill content, agent prompts), and pull-based (memory notes). See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ADD_CLI.md](docs/ADD_CLI.md), [docs/ADD_MODEL.md](docs/ADD_MODEL.md), [docs/ADD_ROLE.md](docs/ADD_ROLE.md).
 
 ## Improved Claude Code workflows
 
-Four failure modes that derail AI-assisted development, and the skills that address them. Inspired by [Matt Pocock's skills repo](https://github.com/mattpocock/skills).
+Four failure modes that derail AI-assisted development, and the skills that address them.
 
 | Failure mode | What goes wrong | Skills that help |
 |---|---|---|
@@ -202,7 +205,9 @@ Four failure modes that derail AI-assisted development, and the skills that addr
 
 ## Skills
 
-42 on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+42+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+
+The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
 ### Using skills in Claude Code / OpenCode
 
@@ -213,7 +218,7 @@ Load the docker-compose skill for multi-service setup
 
 ## Agent Memory
 
-Agents accumulate knowledge across sessions using one of three backends, chosen during `agent-notes install`.
+Agents accumulate knowledge across sessions using one of four backends, chosen during `agent-notes install`.
 
 ### Backends
 
@@ -221,8 +226,27 @@ Agents accumulate knowledge across sessions using one of three backends, chosen
 |---------|---------|----------|
 | **Local** | `~/.claude/agent-memory/<agent>/` — plain markdown per agent | Simple setup, no extra tools |
 | **Obsidian** | Category vault with YAML frontmatter and `[[wikilinks]]` | Visual browsing, backlinks, Dataview queries |
+| **Wiki** | Structured wiki with page types and versioning | Team knowledge bases, compounding knowledge |
 | **None** | Disabled — no files written | Stateless or shared machines |
 
+### Session tracking by backend
+
+| Feature | Local | Obsidian | Wiki |
+|---|---|---|---|
+| Storage location | `~/.claude/agent-memory/<agent>/` | Obsidian vault with categories | Structured wiki with page types |
+| Note types | Flat markdown per agent | `pattern`, `decision`, `mistake`, `context`, `session` | `source`, `concept`, `entity`, `synthesis`, `session` |
+| Session tracking | None | Auto-created session notes with `## Linked notes` | Session pages in `wiki/sessions/` |
+| Cross-referencing | None | `[[wikilinks]]` auto-appended to session notes | Markdown links maintained by LLM |
+| Key operations | read/write | add, list, show, reset, export, import | ingest, query, lint + add, list, show |
+| Best for | Simple setup, no extra tools | Visual browsing, backlinks, Dataview queries | Team knowledge bases, compounding knowledge |
+
+**Obsidian backend** — Uses category directories (`Patterns/`, `Decisions/`, `Mistakes/`, `Context/`, `Sessions/`). When you write a non-session note during an active session, the CLI auto-links it to the session note via `[[wikilinks]]`. Plans are mirrored as Decision notes.
+
+**Wiki backend** — Implements Karpathy's LLM Wiki pattern (v1). Structure: `raw/` for immutable source material, `wiki/` for LLM-maintained pages organized into `sources/`, `concepts/`, `entities/`, `synthesis/`, `sessions/`. Three key operations:
+- **ingest** — Process source material, extract key info, update entity/concept pages, append to log
+- **query** — Search wiki pages, synthesize answers with citations, optionally file answers back as new pages
+- **lint** — Health-check for contradictions, stale claims, orphan pages, missing cross-references
+
 ### Obsidian setup
 
 Run `agent-notes install` and pick Obsidian when prompted. The wizard auto-detects existing vaults under `~/Documents`, `~/Desktop`, and `~`. To initialize the vault structure:
@@ -266,9 +290,14 @@ tags: [rails, models]
 Always use `_prefix: true` with Rails enums to avoid method name collisions.
 ```
 
+## Inspired by
+
+- [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
+- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, verbosity, broken code, architectural degradation), and several core skills (tdd, grill-me, grill-with-docs, improve-codebase-architecture, zoom-out, caveman)
+
 ## Development
 
-Python 3.9+ required. Build from source and run tests:
+Python 3.10+ required. Build from source and run tests:
 
 ```bash
 python -m build && pipx install dist/*.whl

{agent_notes-2.16.0 → agent_notes-2.18.0}/README.md

@@ -2,7 +2,7 @@
 
 AI agent configuration manager for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenCode](https://github.com/opencode-ai/opencode).
 
-Configures a Lead agent (Opus) that orchestrates a team of 18 specialized subagents across three model tiers — so Opus plans and reasons, Sonnet executes, and Haiku explores.
+Configures a Lead agent (Opus) that orchestrates a team of 19 specialized subagents across three model tiers — so Opus 4.6 plans and reasons, Sonnet 4.6 executes, and Haiku 4.5 explores.
 
 ## Quick Start
 
@@ -16,8 +16,8 @@ agent-notes doctor
 
 | Component | Description |
 |-----------|-------------|
-| **Skills** | 42 on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
-| **Agents** | 18 specialized AI subagents with hierarchical model strategy |
+| **Skills** | 42+ on-demand knowledge modules (Rails, Docker, Git, Kamal, Process) |
+| **Agents** | 19 specialized AI subagents with hierarchical model strategy |
 | **Rules** | Global instructions, code quality, and safety guardrails |
 | **Config** | Global instructions for Claude Code, OpenCode, and GitHub Copilot |
 
@@ -56,8 +56,8 @@ Iteration loop: edit source → `python -m build` → `pipx reinstall dist/*.whl
 
 ### 3. Plugin — limited functionality
 
-- **Claude Code**: install via the Claude Code plugin marketplace.
-- **OpenCode**: copy or symlink `.opencode-plugin/` into `~/.config/opencode/plugins/agent-notes/` and add `"plugin": ["agent-notes"]` to `opencode.json`.
+- **Claude Code**: install via the Claude Code plugin marketplace or copy/symlink `.claude-plugin/` into `~/.claude/plugins/agent-notes/`.
+- **OpenCode**: copy or symlink `.claude-plugin/` into `~/.config/opencode/plugins/agent-notes/` and add `"plugin": ["agent-notes"]` to `opencode.json`.
 
 The plugin runs a `session.start` hook that surfaces agent-notes context to the CLI session. It does **not** include the full `agent-notes` CLI (wizard, doctor, config, memory, etc.). For those, use install method 1 or 2.
 
@@ -83,8 +83,8 @@ agent-notes <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `install [--local] [--copy]` | Interactive wizard or direct install |
-| `uninstall [--local]` | Remove installed components |
+| `install [--local] [--copy] [--reconfigure]` | Interactive wizard or direct install |
+| `uninstall [--local \| --global]` | Remove installed components (both scopes by default) |
 | `doctor [--local] [--fix]` | Check installation health |
 | `info` | Show status and component counts |
 | `list [clis\|models\|roles\|agents\|skills\|rules\|all]` | List engine components or installed |
@@ -92,6 +92,7 @@ agent-notes <command> [options]
 | `regenerate [--cli <cli>]` | Rebuild files from state.json (Phase 10+) |
 | `validate` | Lint source configuration files |
 | `memory [list\|size\|show\|reset\|export\|import] [name]` | Manage agent memory |
+| `cost-report` | Show session cost breakdown by agent and model |
 
 ### Supported platforms
 
@@ -122,37 +123,39 @@ agent-notes memory add "Rails enum prefix" \
 
 ## Agent Team
 
-Specialized subagents with hierarchical model strategy: **Opus 4.7 decides, Sonnet 4 executes, Haiku 4.5 explores.**
-
-| Agent | Model | Role |
-|-------|-------|------|
-| **lead** | Opus 4.7 | Plans, delegates, reviews. Orchestrator. |
-| **architect** | Opus 4.7 | System architecture, module boundaries, domain models. Read-only. |
-| **debugger** | Opus 4.7 | Bug investigation: reproduces, isolates, identifies root cause. Read-only. |
-| **coder** | Sonnet 4 | Implements features, fixes bugs, edits files. |
-| **reviewer** | Sonnet 4 | Code quality review. Read-only. |
-| **security-auditor** | Sonnet 4 | Security vulnerability analysis. Read-only. |
-| **test-writer** | Sonnet 4 | Writes tests for any framework. |
-| **test-runner** | Sonnet 4 | Diagnoses and fixes failing tests. |
-| **system-auditor** | Sonnet 4 | Codebase health: duplication, N+1, coupling. Read-only. |
-| **database-specialist** | Sonnet 4 | Schema design, indexes, query performance, migrations. Read-only. |
-| **performance-profiler** | Sonnet 4 | Response times, memory, caching, bundle size. Read-only. |
-| **devops** | Sonnet 4 | Docker, CI/CD, deployment configs. |
-| **devil** | Sonnet 4 | Challenges plans to surface hidden risks. Read-only. |
-| **integrations** | Sonnet 4 | Third-party integrations: OAuth, webhooks, payments. |
-| **refactorer** | Sonnet 4 | Improves code structure without changing behavior. |
-| **analyst** | Haiku 4.5 | Requirements analysis: surfaces missing or contradictory requirements. Read-only. |
-| **api-reviewer** | Haiku 4.5 | API design, versioning, error handling, backward compatibility. Read-only. |
-| **tech-writer** | Haiku 4.5 | Documentation: READMEs, API docs, changelogs. |
-| **explorer** | Haiku 4.5 | Fast file discovery and pattern search. Read-only. |
+Specialized subagents with hierarchical model strategy: **Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.**
+
+| Agent | Role | Model Tier | Purpose |
+|---|---|---|---|
+| lead | orchestrator | opus | Plans, coordinates, verifies — the team lead |
+| architect | reasoner | opus | System design, module boundaries, refactor planning |
+| debugger | reasoner | opus | Complex bug investigation, root-cause analysis |
+| coder | worker | sonnet | Implementation, file edits, bug fixes |
+| reviewer | worker | sonnet | Code quality, readability, correctness |
+| security-auditor | worker | sonnet | Auth, injection, XSS, secrets exposure |
+| test-writer | worker | sonnet | Creates tests for any framework |
+| test-runner | worker | sonnet | Diagnoses and fixes failing tests |
+| system-auditor | worker | sonnet | Duplication, dead code, coupling, complexity |
+| database-specialist | worker | sonnet | Schema design, indexes, query performance |
+| performance-profiler | worker | sonnet | Response times, memory, bundle size |
+| api-reviewer | worker | sonnet | REST conventions, versioning, backward compatibility |
+| devops | worker | sonnet | Docker, CI/CD, deployment, infrastructure |
+| devil | worker | sonnet | Devil's advocate — challenges plans and assumptions |
+| integrations | worker | sonnet | OAuth, webhooks, API clients, SSO |
+| refactorer | worker | sonnet | Extracts methods, reduces duplication, improves naming |
+| explorer | scout | haiku | Fast file discovery, pattern search |
+| analyst | scout | haiku | Requirements translation, acceptance criteria |
+| tech-writer | scout | haiku | READMEs, API docs, changelogs |
+
+**4 roles, 19 agents, 3 model tiers.** The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).
 
 ## Architecture
 
-agent-notes is a 4-layer engine (domain / registries / services / commands). All extensible content (CLIs, models, roles, agents, skills, rules) lives in `agent_notes/data/` as YAML — adding a new CLI/model/role is a YAML drop, no Python changes. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ADD_CLI.md](docs/ADD_CLI.md), [docs/ADD_MODEL.md](docs/ADD_MODEL.md), [docs/ADD_ROLE.md](docs/ADD_ROLE.md).
+agent-notes is a 4-layer engine (domain / registries / services / commands). All extensible content (CLIs, models, roles, agents, skills, rules) lives in `agent_notes/data/` as YAML — adding a new CLI/model/role is a YAML drop, no Python changes. Context is loaded in tiers: always-loaded (CLAUDE.md, rules, skill catalog), lazy-loaded (full skill content, agent prompts), and pull-based (memory notes). See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ADD_CLI.md](docs/ADD_CLI.md), [docs/ADD_MODEL.md](docs/ADD_MODEL.md), [docs/ADD_ROLE.md](docs/ADD_ROLE.md).
 
 ## Improved Claude Code workflows
 
-Four failure modes that derail AI-assisted development, and the skills that address them. Inspired by [Matt Pocock's skills repo](https://github.com/mattpocock/skills).
+Four failure modes that derail AI-assisted development, and the skills that address them.
 
 | Failure mode | What goes wrong | Skills that help |
 |---|---|---|
@@ -172,7 +175,9 @@ Four failure modes that derail AI-assisted development, and the skills that addr
 
 ## Skills
 
-42 on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+42+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run `agent-notes list skills` for the current list, or browse `agent_notes/data/skills/`.
+
+The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.
 
 ### Using skills in Claude Code / OpenCode
 
@@ -183,7 +188,7 @@ Load the docker-compose skill for multi-service setup
 
 ## Agent Memory
 
-Agents accumulate knowledge across sessions using one of three backends, chosen during `agent-notes install`.
+Agents accumulate knowledge across sessions using one of four backends, chosen during `agent-notes install`.
 
 ### Backends
 
@@ -191,8 +196,27 @@ Agents accumulate knowledge across sessions using one of three backends, chosen
 |---------|---------|----------|
 | **Local** | `~/.claude/agent-memory/<agent>/` — plain markdown per agent | Simple setup, no extra tools |
 | **Obsidian** | Category vault with YAML frontmatter and `[[wikilinks]]` | Visual browsing, backlinks, Dataview queries |
+| **Wiki** | Structured wiki with page types and versioning | Team knowledge bases, compounding knowledge |
 | **None** | Disabled — no files written | Stateless or shared machines |
 
+### Session tracking by backend
+
+| Feature | Local | Obsidian | Wiki |
+|---|---|---|---|
+| Storage location | `~/.claude/agent-memory/<agent>/` | Obsidian vault with categories | Structured wiki with page types |
+| Note types | Flat markdown per agent | `pattern`, `decision`, `mistake`, `context`, `session` | `source`, `concept`, `entity`, `synthesis`, `session` |
+| Session tracking | None | Auto-created session notes with `## Linked notes` | Session pages in `wiki/sessions/` |
+| Cross-referencing | None | `[[wikilinks]]` auto-appended to session notes | Markdown links maintained by LLM |
+| Key operations | read/write | add, list, show, reset, export, import | ingest, query, lint + add, list, show |
+| Best for | Simple setup, no extra tools | Visual browsing, backlinks, Dataview queries | Team knowledge bases, compounding knowledge |
+
+**Obsidian backend** — Uses category directories (`Patterns/`, `Decisions/`, `Mistakes/`, `Context/`, `Sessions/`). When you write a non-session note during an active session, the CLI auto-links it to the session note via `[[wikilinks]]`. Plans are mirrored as Decision notes.
+
+**Wiki backend** — Implements Karpathy's LLM Wiki pattern (v1). Structure: `raw/` for immutable source material, `wiki/` for LLM-maintained pages organized into `sources/`, `concepts/`, `entities/`, `synthesis/`, `sessions/`. Three key operations:
+- **ingest** — Process source material, extract key info, update entity/concept pages, append to log
+- **query** — Search wiki pages, synthesize answers with citations, optionally file answers back as new pages
+- **lint** — Health-check for contradictions, stale claims, orphan pages, missing cross-references
+
 ### Obsidian setup
 
 Run `agent-notes install` and pick Obsidian when prompted. The wizard auto-detects existing vaults under `~/Documents`, `~/Desktop`, and `~`. To initialize the vault structure:
@@ -236,9 +260,14 @@ tags: [rails, models]
 Always use `_prefix: true` with Rails enums to avoid method name collisions.
 ```
 
+## Inspired by
+
+- [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
+- [Matt Pocock's skills repo](https://github.com/mattpocock/skills) — Skill format (SKILL.md per directory), failure-mode table (misalignment, verbosity, broken code, architectural degradation), and several core skills (tdd, grill-me, grill-with-docs, improve-codebase-architecture, zoom-out, caveman)
+
 ## Development
 
-Python 3.9+ required. Build from source and run tests:
+Python 3.10+ required. Build from source and run tests:
 
 ```bash
 python -m build && pipx install dist/*.whl

agent_notes-2.18.0/agent_notes/VERSION

@@ -0,0 +1 @@
+2.18.0

{agent_notes-2.16.0 → agent_notes-2.18.0}/agent_notes/commands/memory.py

@@ -250,6 +250,30 @@ def do_show(name: str) -> None:
             print("")
         return
 
+    elif backend == "wiki":
+        if path is None:
+            print("Memory path not configured.")
+            return
+        from ..services.wiki_backend import WIKI_PAGE_TYPES
+        wiki_dir = path / "wiki"
+        if name not in WIKI_PAGE_TYPES:
+            print(f"Page type '{name}' not found. Available types: {', '.join(WIKI_PAGE_TYPES)}")
+            return
+        type_dir = wiki_dir / name
+        if not type_dir.exists():
+            print(f"No pages found for type '{name}' in wiki {path}")
+            return
+        print(f"Wiki pages in '{name}':")
+        print("")
+        for f in sorted(type_dir.glob("*.md")):
+            print(f"{Color.CYAN}--- {f.name} ---{Color.NC}")
+            try:
+                print(f.read_text())
+            except (UnicodeDecodeError, OSError):
+                print("(binary file or read error)")
+            print("")
+        return
+
     # local backend
     if path is None:
         path = MEMORY_DIR
@@ -283,6 +307,41 @@ def do_reset(name: Optional[str] = None) -> None:
         print("Memory is disabled.")
         return
 
+    if backend == "wiki":
+        if path is None or not path.exists():
+            print("No wiki found to reset.")
+            return
+        target = f"wiki at {path}" if name is None else f"wiki page type '{name}' at {path}"
+        print(f"{Color.RED}Warning: this will permanently delete the {target}.{Color.NC}")
+        confirm = input("Type 'yes' to confirm: ")
+        if confirm == "yes":
+            import shutil as _shutil
+            from ..services.wiki_backend import WIKI_PAGE_TYPES
+            if name is None:
+                wiki_dir = path / "wiki"
+                for page_type in WIKI_PAGE_TYPES:
+                    type_dir = wiki_dir / page_type
+                    if type_dir.exists():
+                        _shutil.rmtree(type_dir)
+                        type_dir.mkdir()
+                print(f"{Color.GREEN}Wiki at {path} cleared.{Color.NC}")
+            else:
+                from ..services.wiki_backend import WIKI_PAGE_TYPES
+                wiki_dir = path / "wiki"
+                if name not in WIKI_PAGE_TYPES:
+                    print(f"Page type '{name}' not found. Available types: {', '.join(WIKI_PAGE_TYPES)}")
+                    return
+                type_dir = wiki_dir / name
+                if not type_dir.exists():
+                    print(f"No pages found for type '{name}'.")
+                    return
+                _shutil.rmtree(type_dir)
+                type_dir.mkdir()
+                print(f"{Color.GREEN}Wiki pages for type '{name}' cleared.{Color.NC}")
+        else:
+            print("Cancelled.")
+        return
+
     if path is None:
         path = MEMORY_DIR
 
@@ -666,7 +725,7 @@ Commands:
   list             List all agent memories with sizes (default)
   vault            Show current backend and memory path
   index            Regenerate Index.md for the current backend
-  add <title> <body>  Add a note (obsidian backend)
+  add <title> <body>  Add a note (obsidian and wiki backends)
   migrate          Migrate old per-project layout to new shared flat layout
   size             Total disk usage
   show <name>      Show memory contents for one agent/category
@@ -674,6 +733,9 @@ Commands:
   reset <name>     Clear one agent's memory
   export           Back up memories to agent-notes/memory-backup/
   import           Restore from agent-notes/memory-backup/
+  ingest <title> <body>  Ingest source material and fan-out to concepts/entities (wiki backend)
+  query <keyword>  Search wiki pages by keyword (wiki backend)
+  lint             Check wiki health: orphans, broken links, stale index (wiki backend)
 
 Examples:
   agent-notes memory                    List all memories

{agent_notes-2.16.0 → agent_notes-2.18.0}/agent_notes/data/agents/agents.yaml

@@ -178,7 +178,7 @@ agents:
 
   api-reviewer:
     description: "Reviews API design for consistency, versioning, error handling, and backward compatibility. Read-only analysis. Triggers: API, REST, endpoint, versioning, backward compatible, HTTP, OpenAPI."
-    role: scout
+    role: worker
     mode: subagent
     color: cyan
     effort: medium

agent_notes-2.18.0/agent_notes/data/agents/lead.md

@@ -0,0 +1,47 @@
+You are a team lead that plans and coordinates work across specialized agents.
+
+<!-- include: phase0 -->
+
+<!-- include: hard_limits -->
+
+### Credentials handling (HARD RULE)
+
+The lead MUST NEVER read, print, log, or include API keys / credentials / secrets in any output, even if the user asks. The credentials file at `~/.agent-notes/credentials.toml` is opaque — your only legitimate operations are:
+
+- Confirm a provider is configured: `agent-notes config provider <name>` (returns yes/no, never the value)
+- Trigger a re-prompt: `agent-notes config providers` (the wizard handles entry; values never leave it)
+
+If the user asks "what's my OpenRouter API key", refuse and offer to verify presence/absence only. This rule applies even in error messages, debug output, log files, and stack traces. If a function in `agent_notes.services.credentials` raises, the error message MUST NOT contain the value — only structural information (which provider, missing field name).
+
+## Memory protocol (HARD RULE)
+
+The session memory note is the durable cross-session record of work done. It MUST be updated on every state change, not just at the end. The plan-mode file is per-session and disposable; it does NOT replace the session note.
+
+### When to write
+
+1. **First non-trivial turn of a session** — create or open the session note:
+   `agent-notes memory add "<session description>" "<scope summary>" session lead`
+   Filename is `<session-id>.md` per the obsidian-memory SKILL. Subsequent calls in the SAME session append `## Update <UTC ISO>` blocks to the same file.
+
+2. **At every phase / dispatched-agent completion** — before reporting that phase done:
+   `agent-notes memory add "<session description>" "Phase N — <what shipped, files touched, test delta, deferrals>" session lead`
+
+3. **When a decision, pattern, mistake, or context worth preserving across sessions surfaces** — write a SEPARATE note:
+   `agent-notes memory add "<title>" "<body>" decision|pattern|mistake|context <agent>`
+   These land in `Decisions/`, `Patterns/`, etc. — independent of the session note.
+
+**Auto-linking**: when a non-session note (Decision / Pattern / Mistake / Context) is written while a session is active, the CLI automatically appends a wikilink to that session note's `## Linked notes` section. No second `memory add` call is required — the linking is handled by the backend. Obsidian backend only — no-op on local.
+
+**Plan-mirror rule**: after every ExitPlanMode, mirror the plan content as a Decision note in Obsidian. See `obsidian-memory` SKILL "Plan-mirror rule" section. Obsidian backend only — no-op on local.
+
+<!-- include: pipelines -->
+
+<!-- include: execution -->
+
+<!-- include: review -->
+
+<!-- include: verification -->
+
+<!-- include: guardrails -->
+
+<!-- include: cost_reporting -->

agent_notes-2.18.0/agent_notes/data/agents/shared/execution.md

@@ -0,0 +1,89 @@
+## Phase 1: Prompt analysis (do this first, before any action)
+
+Stop and think. Do NOT touch any tool until you complete this analysis internally.
+
+### 1. Understand intent
+
+- What is the user actually asking for? Restate it in your own words.
+- Is this a question, a bug fix, a feature, a refactor, an audit, or something else?
+- Only ask a clarifying question if you genuinely cannot proceed without information only the user can provide. If you can make a reasonable assumption, state it in the plan and proceed.
+- What does "done" look like? Define the acceptance criteria before you start.
+
+### 2. Assess scope
+
+- **Trivial** (answer a question, single grep, one-line fix): do it yourself, no agents.
+- **Small** (1-3 files, single concern): one agent, maybe two sequential.
+- **Medium** (multiple files, cross-cutting concern): plan needed, 2-4 agents.
+- **Large** (whole codebase, multiple domains): full plan, parallel agents.
+
+### 3. Decompose into subtasks
+
+- Break the request into discrete, independently verifiable units of work.
+- For each subtask define: what needs to happen, what files are involved, what the output is.
+- Identify hidden subtasks the user didn't mention but the work requires (e.g., user asks for a feature → you also need tests if the project has them, migration if DB changes).
+
+### 4. Map dependencies and execution order
+
+- Which subtasks are independent? → run in parallel.
+- Which subtasks depend on others? → run sequentially, in correct order.
+- Draw the dependency graph mentally: `explore → implement → test → review`.
+
+### 5. Assign agents (cheapest that can do the job)
+
+For each subtask, pick the cheapest capable agent:
+- **Free** (do it yourself): one Read/Grep/Glob answers it.
+- **Cheap** (`explorer`, Haiku): read-only discovery, structure mapping, pattern search. One `explorer` call beats multiple self-reads.
+- **Medium** (`reviewer`, `security-auditor`, `system-auditor`, `database-specialist`, `performance-profiler`, `api-reviewer`): focused analysis of known files.
+- **Reasoner** (`architect`, `debugger`, Opus): deep system design, complex root-cause analysis. Use only when the problem requires multi-step reasoning that Sonnet cannot handle.
+- **Expensive** (`coder`, `test-writer`, `test-runner`): writes files, open-ended work.
+
+Rules:
+- Never use `coder` for read-only analysis. Never use Sonnet for a Haiku job.
+- Batch related edits: one `coder` call with 5 file edits beats 5 `coder` calls with 1 edit each.
+- Never spawn one agent per bullet point. Combine related subtasks into one agent call.
+
+Verify the target agent has required tools — read-only agents cannot write files. Route edits to `coder` / `test-writer` / `refactorer` / `tech-writer` / `devops`.
+
+### 6. Write the plan
+
+Before delegating, output a brief plan to the user:
+```
+Plan:
+1. [subtask] → [agent] (parallel group A)
+2. [subtask] → [agent] (parallel group A)
+3. [subtask] → [agent] (after group A)
+4. Verify → lead reviews all results
+```
+This keeps the user informed and lets them course-correct before work starts.
+
+## Phase 2: Execution
+
+### Execution order
+
+**Broad tasks** (whole codebase, multiple domains, full audits): skip self-exploration — delegate immediately to specialized agents in parallel. Your job is to synthesize, not explore. If the project is already known from prior sessions or vault context, skip serial discovery and delegate immediately. If the project is new or unfamiliar, dispatch one `explorer` for structure mapping before parallel specialist dispatch.
+
+**Narrow tasks** (known files, specific questions):
+1. Do free tasks yourself first (one or two reads/greps)
+2. One consolidated `explorer` call for remaining read-only work
+3. Parallel medium/expensive agents for what's left
+
+Never spawn one agent per bullet point from the user's prompt. Combine related subtasks into one agent call.
+
+### Delegation rules
+
+- `explorer` — file discovery, structure mapping, pattern search (Haiku, cheap)
+- `coder` — all file edits and implementation work
+- `reviewer` — code quality checks after implementation
+- `architect` — system design, module boundaries, refactor planning (Opus, expensive — use sparingly)
+- `debugger` — complex bug investigation, root-cause analysis (Opus, expensive — hand fix to `coder`)
+- `security-auditor` — auth, input handling, data access
+- `test-writer` — create tests, `test-runner` — fix failing tests
+- `system-auditor` — codebase health: N+1, duplication, dead code
+- `database-specialist` — schema design, indexes, query performance, migrations
+- `performance-profiler` — response times, memory, caching, bundle size
+- `api-reviewer` — REST conventions, versioning, error handling, backward compatibility
+- `tech-writer` — documentation, `devops` — infrastructure
+
+Skip agents for: simple questions (answer directly), single-file edits (coder alone), or two-grep lookups (do it yourself).
+
+Give each agent a specific task with all context (paths, criteria). Always include the cost report at the end of every response.