Compendium

Agent Conventions

6 min read

Agent Conventions

This document is the operating manual for any agent (Claude Code, sub-agents, Codex workers, Cursor, etc.) running on this machine. Read it before doing research; follow it when finishing.

Scope note (2026-05-23). This describes the private vault workflow (d:\Vault\AI Vault\ — the working-memory layer). Paths like Research/Topics/, Research/Sessions/, Agents/ live in that vault, not in this Compendium repo. Compendium is the read-mostly reference library produced from that workflow; it doesn’t itself get appended to via these commands. Anyone reading this on github.com is seeing how the originating machine is organized — not a transplantable workflow without the same vault + REST API setup.

Cross-project rule (locked 2026-05-25)

The Compendium is a reference library, not an operator over other projects. Agents working inside Compendium operate under a strict read/write asymmetry:

  • READ — anywhere on the machine is fair game. Other project repos (d:\Projects\Suits\, d:\Projects\TaxProfessional\, d:\Projects\IncomeProject\, future projects), the private vault (d:\Vault\AI Vault\), runtime config (~/.claude/), system state, MCP servers — all readable for context, learning, and synthesis.
  • WRITE — only inside d:\Vault\Compendium\ itself, plus the user’s private vault under the exception clause below. Nothing else.

Specifically, Compendium agents may not:

  • Modify files in d:\Projects\<any-project>\ without that project’s own agent expressly approving the change;
  • Run git commit / git push in any other project’s repo;
  • Trigger deploys, scheduled tasks, or background processes that affect any other project.

Cross-project changes go through the relevant project’s own agents. If you find yourself wanting to write outside d:\Vault\Compendium\ and outside the private vault, stop. Either route the task to the relevant project’s own agent (e.g., dispatch into d:\Projects\Suits\ and let its agents handle it), or surface a clear “needs cross-project review” note for the user to dispatch.

Exception — private vault. The user’s vault at d:\Vault\AI Vault\ is treated as user-personal storage, not a “project” in the project-agent sense. Compendium agents may write to the vault (e.g., save lesson notes per agents-learning-protocol) without triggering this rule.

The canonical statement of this rule lives in Conventions; this section restates it for any agent that lands on the operating manual first.

Deploy posture (2026-05-25)

Compendium has two synchronized publication targets, neither of them publicly accessible:

  • Backup / source-of-truth mirror — the private GitHub repo adamhudson777/Compendium. Every commit pushed here. This is the durable backup and the canonical history.
  • Browseable site — Cloudflare Pages deployment, gated behind Cloudflare Access (email/SSO login). It is not on the public internet; only authenticated identities the user has whitelisted can reach it. Useful when the user wants the rendered/searchable view from a device that doesn’t have the vault mounted.

This is a deliberate posture: Compendium content is allowed to be opinionated, in-progress, or partially wrong without a public-release bar. If a note someday needs to be made truly public, it gets promoted to a separate publication surface — not by removing the Access gate on the live site.

Vendor sub-libraries

Compendium hosts vendor-specific deep-dive sub-libraries when a single product ecosystem is large enough to warrant its own flat folder. Current sub-libraries:

  • _index — Claude product ecosystem (17 notes, 6,756 lines). Canonical reference for Anthropic’s models, Messages API + SDKs, Claude Code (CLI / IDE / web / desktop), the Claude Agent SDK, the Model Context Protocol, and all auxiliary APIs (Batches, Files, Citations, Vision, Tool Use, Memory, Web Search, Code Execution, Computer Use). Every non-obvious claim cites docs.claude.com / platform.claude.com / code.claude.com / modelcontextprotocol.io / an anthropics/* repo, with “Undocumented as of 2026-05-25 — observed behavior” tags where the official docs are silent.

When adding a new vendor sub-library, follow the same flat-folder + _index.md pattern and add an entry here.

Onboarding for new agents

New to this Compendium? Start at agent-quickstart — a single-page primer that links to the relevant sections of this operating manual, the Conventions, agents-learning-protocol, and the canonical-tag table. It’s the path of least resistance for an agent landing in this repo for the first time.

The contract

  1. Query before researching. Before any web search or deep investigation, query the vault. Default to hybrid — it combines full-text and semantic so you don’t miss concept matches that lack the exact words:

    node ~/.claude/bin/obsidian-research.mjs query "your question" --hybrid --k 8

    Other modes:

    • default (no flag) — full-text via Obsidian REST (fast, exact-token match)
    • --semantic — vector search via local embeddings (concept-level recall)
    • --hybrid — reciprocal-rank fusion of both (recommended)

    If a relevant note already exists, build on it rather than re-searching.

  2. Save what you learn. When research yields a non-obvious finding, save it:

    node ~/.claude/bin/obsidian-research.mjs save \
  --title "Concise title" \
  --topic "kebab-case-topic" \
  --tags "tag1,tag2" \
  --source "https://..." \
  --agent "your-agent-name" \
  --body "What you learned, in markdown."

    Or stream from stdin: echo "..." | node ~/.claude/bin/obsidian-research.mjs save --title "..." --stdin

    Optional flags: --folder <subpath> to place the note outside the default Research/Topics/ (e.g. --folder AgentCreator/Decisions).

  3. Log session activity. At natural breakpoints, append a one-line entry to today’s session log:

    node ~/.claude/bin/obsidian-research.mjs log "what I just figured out / decided"

  4. Re-index after batch saves. Semantic and hybrid search rely on a local embedding index. The auto-capture hook covers WebFetch/WebSearch automatically; for everything else (manual save calls, direct file edits) refresh after a batch:

    node ~/.claude/bin/obsidian-research.mjs index            # incremental — only re-embeds changed notes
node ~/.claude/bin/obsidian-research.mjs index --rebuild  # force re-embed everything

  5. Link aggressively. Use [[Topic Name]] syntax to link related concepts. The graph is the value.

  6. Don’t duplicate. If a topic note exists, append/refine rather than creating a sibling. Use query first.

Other subcommands

  • read --path "Research/Topics/foo.md" — fetch a single note’s content
  • list [--path subfolder] — list vault files (root or under a subfolder)
  • init — create the vault scaffold (idempotent)
  • status — connectivity check against the Local REST API plugin

What counts as research worth saving

Save it if:

  • It took non-trivial work to discover (web search, reading docs, debugging)
  • It’s likely useful to a future agent
  • It contains a finding, decision, or non-obvious fact — not just status

Skip it if:

  • It’s already obvious from the code / git log
  • It’s ephemeral (a transient bug fix, a one-off command output)
  • It’s already in CLAUDE.md or a more authoritative doc

Frontmatter schema

Every note should have:

---
title: "..."           # human-readable
created: ISO-8601
agent: "..."           # which agent wrote it
source: "..."          # url or origin (optional)
tags: [t1, t2]
topic: kebab-case      # canonical topic slug (optional)
session: id            # session id if applicable
---

Adapting from past research

Before answering or deciding, consider running:

node ~/.claude/bin/obsidian-research.mjs query "phrase"

The output is JSON; feed relevant notes into your context. Treat past notes as time-stamped claims, not ground truth — verify against current code/sources before acting.

Graph View

Backlinks