Obs Memory

Session Start — Orientation

At the start of every session, orient yourself with at most 2 operations:

Step 1: Read TODOs

CLI-first:

obsidian vault=$VAULT_NAME tasks path="todos" todo verbose

Fallback: Read the file at $VAULT/todos/Active TODOs.md.

Know what's pending, in-progress, and recently completed.

Step 2: Detect current project and read its overview

Auto-detect the project from the current working directory:

basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null || basename $(pwd)

Then check if a matching project exists by listing files in $VAULT/projects/*/. Match the git repo name (or directory name) against project folder names. If a match is found, read the project overview at $VAULT/projects/{matched-name}/{matched-name}.md.

This project overview contains wikilinks to all components, patterns, architecture decisions, and domains. Do not read those linked notes yet — follow them on demand when the current task requires that context.

What NOT to read at session start

• Home.md (only if you're lost and can't find the project)
• sessions/ (only if the user references prior work)
• Domain indexes (only if you need cross-project knowledge)
• Component notes (only when working on that component)

Automatic Behaviors

These behaviors apply to any agent using this skill. They do not require explicit commands.

On session start

Auto-orient (TODOs + project overview) without being asked, following the Session Start procedure above. If the vault doesn't exist at the resolved path, inform the user and suggest running init.

On session end signals

When the user says "done", "wrapping up", "that's it", "let's stop", or similar end-of-session language — offer to write a session summary. Don't auto-run; ask first: "Want me to write a session summary to the vault before we wrap up?"

On component discovery

When you deeply analyze a component that has no vault note — and the project has an active vault — offer to create a component note and infer relationships from imports and dependencies. Example: "I noticed there's no vault note for the AuthMiddleware component. Want me to create one and map its dependencies?"

On first run

When the vault doesn't exist at any resolved path, guide the user through init, then auto-scaffold the current project if inside a git repo.

During Work — Graph Navigation

Principle: Use CLI queries first, file reads second. The Obsidian CLI provides structured access to properties, links, backlinks, tags, and search — prefer these over reading entire files.

CLI-first lookups (preferred)

Use these CLI commands for targeted queries without consuming file-read tokens:

# Query a component's dependencies
obsidian vault=$VAULT_NAME property:read file="Component Name" name="depends-on"

# Find what depends on a component
obsidian vault=$VAULT_NAME property:read file="Component Name" name="depended-on-by"
obsidian vault=$VAULT_NAME backlinks file="Component Name"

# Find all outgoing links from a note
obsidian vault=$VAULT_NAME links file="Component Name"

# Find all notes of a type
obsidian vault=$VAULT_NAME tag verbose name="component"

# Search vault content
obsidian vault=$VAULT_NAME search format=json query="search term" matches limit=10

# Get note structure without full read
obsidian vault=$VAULT_NAME outline file="Component Name"

# Read a specific property
obsidian vault=$VAULT_NAME property:read file="Component Name" name="key-files"

Where $VAULT_NAME is the vault folder name (basename of $VAULT).

File-read fallback (when CLI unavailable)

Fall back to file reads when the Obsidian CLI is not available:

• Need to understand a component? The project overview links to it. Read that one note.
• Need an architecture decision? The component note or project overview links to it. Follow the link.
• Need cross-project knowledge? Component/pattern notes link to domain notes. Follow the link.
• Need session history? Only read if you're stuck or the user references prior work.

Frontmatter-first scanning

When you need to scan multiple notes to find the right one, read just the first ~10 lines of each file. The tags, project, type, and status fields in the frontmatter tell you if the note is relevant before reading the full body.

Directory listing before reading

List directory contents before reading files — know what exists without consuming tokens:

• $VAULT/projects/{name}/**/*.md — all notes for a project
• $VAULT/domains/{tech}/*.md — domain knowledge files

Writing to the Vault

Write concisely. Notes are for your future context, not human documentation. Prefer:

• Bullet points over prose
• Wikilinks over repeated explanations (link to it, don't re-state it)
• Frontmatter tags for discoverability over verbose descriptions

When to write

• New component discovered: Create a component note when you deeply understand a part of the codebase
• Architecture decision made: Record ADRs when significant design choices are made
• Pattern identified: Document recurring patterns that future sessions should follow
• Domain knowledge learned: Write to domain notes when you discover cross-project knowledge

Scoping rules

Frontmatter conventions

Always include in new notes:

---