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.

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.