Obs Memory

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

Step 1: Read TODOs

Read $VAULT/todos/Active TODOs.md directly.

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 (git repo name preferred, folder name as fallback):

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 working directory name (git repo preferred, folder name as fallback) 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 file tools (Read, Glob, Grep) as the primary method. The Obsidian CLI is not typically available; file tools are always available.

File-based lookups (primary)

• 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.
• Need to search? Use Grep across $VAULT/**/*.md.

Obsidian CLI (optional — only if installed)

If the Obsidian CLI is available, you can use it for targeted queries:

obsidian vault=$VAULT_NAME property:read file="Component Name" name="depends-on"
obsidian vault=$VAULT_NAME backlinks file="Component Name"
obsidian vault=$VAULT_NAME search format=json query="search term" matches limit=10

Where $VAULT_NAME is basename "$VAULT". Do not assume the CLI is present; verify first.

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:

---