These are instructions for an AI coding agent to build an OpenVault-style Obsidian memory system for the user. Complete all of the following steps yourself by creating folders and Markdown files directly. Do not ask the user to create files, copy templates, or organize notes manually. Bootstrap mode is auto-write. Ongoing mode is approval-first: after setup is complete, future OpenVault edits should happen only when the user explicitly asks for them or approves them. The target system is plain Markdown on disk. Obsidian is a required tool for this workflow, but it is not the source of truth. The vault should remain usable without plugins or MCP, but bootstrap is not fully complete until Obsidian is installed and the vault is ready to be opened there. --- ## Goal Create a local Obsidian vault backed by plain Markdown files on disk that gives the user's coding agent persistent memory across projects. The final system must include: - one global home/index note - one global memory note - one living project note per repository - one historical sessions folder for dated handoffs - dedicated folders for decisions, tasks, and prompts - reusable instructions that tell future agents how to read and maintain the vault The operating model should mirror this structure: ```text / 00_Home.md 01_Memory.md 02_Projects/ 03_Sessions/ 05_Decisions/ 06_Tasks/ 09_Prompts/ ``` Do not create OpenVault-style notes inside project repositories. The vault lives outside repos. Obsidian is required for the final workflow. Markdown on disk is the durable format, but the intended operating interface is an Obsidian vault. --- ## Operating Rules - During bootstrap, you may create and edit vault files automatically. - After bootstrap, switch to approval-first behavior for OpenVault writes. - Reading the vault should always be automatic. - Writing to the vault after bootstrap should require an explicit user request or approval. - Obsidian is required for the finished setup. If it is not installed yet, continue building the vault on disk and report the setup as pending final Obsidian installation and first open. - Preserve exact repository name and casing when naming `02_Projects/.md` and `03_Sessions//`. - Prefer repository identity from `git remote origin` when available. If unavailable, fall back to the repository directory name. - Treat each `02_Projects/.md` note as a living engineering handoff, not a lightweight summary. - Treat `03_Sessions//` as dated historical handoffs, not the place for ongoing edits. - Do not invent commands, APIs, env vars, data models, or architecture details. If something is missing, write `not found` or state the uncertainty clearly. - Do not commit, push, or modify repository code during OpenVault bootstrap unless the user explicitly asks. --- ## Preflight Perform these checks first. ### 1. Choose the vault path - Use a user-provided vault path if one was supplied. - Otherwise, default to `~/OpenVault`. - If the user explicitly wants sync across machines, prefer a synced folder path only when they provided it or clearly use one already. - Do not guess a cloud-sync location unless there is strong evidence and the path already exists. ### 2. Choose the project roots - Use any project root paths the user provided. - Otherwise, scan these common roots and use the ones that exist: - `~/projy` - `~/projects` - `~/code` - `~/dev` - `~/workspace` - `~/src` - If none of those exist, ask one concise question asking for the primary projects root. ### 3. Check Obsidian availability - Detect whether Obsidian is installed on the machine. - If Obsidian is installed, continue bootstrap normally. - If Obsidian is not installed, still create the vault and prompt files on disk first. - Treat missing Obsidian as a practical setup gap: do not block vault creation, but do not report full setup complete until installation guidance has been provided and the vault path is ready to be opened in Obsidian. - If the environment allows safe automated installation, you may install Obsidian. Otherwise, provide explicit installation instructions in the final report. ### 4. Define repo discovery rules - Discover top-level git repositories under the chosen project roots. - Ignore nested repos inside obvious dependency or build folders such as `node_modules`, `.git`, `.venv`, `venv`, `dist`, `build`, `.next`, `vendor`, and cache folders. - For monorepos, create one project note for the top-level git repo unless the user explicitly wants notes for internal packages too. ### 5. Decide how to install ongoing agent rules - If the current agent environment has a known writable instructions or rules location, install the ongoing OpenVault rules there. - If not, create ready-to-paste instruction files under `09_Prompts/` and report their paths clearly. - Never guess an agent config path. If you do not know it, generate the snippet instead of forcing an edit. --- ## Build The Vault Create the vault folder and this exact directory structure if it does not already exist: ```text / 02_Projects/ 03_Sessions/ 05_Decisions/ 06_Tasks/ 09_Prompts/ ``` Then create or update these core files. ### `00_Home.md` Create this file with frontmatter and a project index. ```md --- title: Home tags: - home --- # Home ## Projects Index - [[02_Projects/|]] - . . ``` Rules: - Keep the project list flat and easy to scan. - Sort alphabetically unless the user clearly prefers a custom ordering. - Use `active`, `tracked`, `paused`, or another plain-English status only when you have evidence. - Default to `Tracked.` when unsure. ### `01_Memory.md` Create this file as the baseline onboarding note for every future agent session. ```md --- title: Memory tags: - memory --- # Memory ## Who I am - Name: - Role: - Company or primary work: - Main goals: ## How I work - Preferred tools: - Preferred writing style: - Decision principles: - Collaboration preferences: ## Current systems - Main machines: - Project roots: - Core apps and services: - Version control and hosting: - Repeated workflows: ## Active context - Current focus: - Near-term priorities: - Known constraints: ``` How to populate it: - Infer only safe basics automatically, such as existing project root paths. - If the user has already revealed personal preferences or work style, include them. - If key fields are unknown, leave concise placeholders instead of inventing content. - After bootstrap, ask one grouped follow-up question set to improve this note, but do not block vault creation on that answer. - If Obsidian is not yet installed, do not invent Obsidian-specific preferences. Record only what is known and report the missing installation as a setup gap. ### Reserved folders Create these folders even if they start empty: - `02_Projects/` - `03_Sessions/` - `05_Decisions/` - `06_Tasks/` - `09_Prompts/` --- ## Create Reusable Prompt Files Create these reusable files under `09_Prompts/`. ### `09_Prompts/OpenVault-Agent-Rules.md` This file is the portable rules snippet for any future coding agent. ```md # OpenVault Agent Rules Before answering, search the OpenVault for relevant context. Use `01_Memory.md` as baseline context. When working inside a tracked repository, inspect `02_Projects/.md` if it exists. Use `00_Home.md` when project summaries or statuses need updates. Do not create OpenVault-style notes inside project repositories. Keep AI memory, handoffs, planning, and operational tracking inside the OpenVault. Treat `02_Projects/.md` as the living per-repo note. Preserve exact repository name and casing. Treat each project note as an engineering handoff. Maintain its `Purpose`, `Architecture map`, `File and folder guide`, `Execution commands`, `Environment and secrets`, `Data model`, `API surface`, `Current focus`, `Recent changes`, and `Next actions` sections when relevant. Treat `03_Sessions//` as the location for dated session summaries, not active ongoing updates. Do not edit the OpenVault after bootstrap unless the user explicitly asks or approves. If you learn durable project knowledge during work, propose where it belongs in `02_Projects/`, `03_Sessions/`, `05_Decisions/`, or `06_Tasks/`. Obsidian is required for the intended workflow. If it is missing, treat the vault as prepared but not fully activated. ``` ### `09_Prompts/Project-Note-Template.md` ```md --- title: tags: - project status: tracked --- # ## Summary <2-4 sentence summary> ## Status ## Links - GitHub: ## Purpose
## Architecture map ## File and folder guide ## Execution commands ## Environment and secrets ## Data model
## API surface ## Current focus ## Recent changes ## Next actions ``` ### `09_Prompts/Session-Handoff-Template.md` ```md # Session Handoff ## What changed - ... ## Files touched - ... ## Commands run - ... ## Decisions made - ... ## Open questions - ... ## Next actions - ... ## Suggested updates to .md - ... ## Suggested updates to Decisions - ... ## Suggested updates to Tasks - ... ``` ### `09_Prompts/Decision-Note-Template.md` ```md # ## Status - proposed | accepted | superseded ## Context - ... ## Decision - ... ## Consequences - ... ## Related projects - [[02_Projects/|]] ``` ### `09_Prompts/Task-Note-Template.md` ```md # ## Status - pending | in progress | blocked | complete ## Scope - ... ## Related projects - [[02_Projects/|]] ## Next actions - ... ``` ### `09_Prompts/Handoff-Update-Prompt.md` Create a reusable handoff instruction file that future agents can follow. ```md Create an end-of-day or end-of-session handoff for the current repository. Requirements: - Confirm the current working directory is a git repo under one of the tracked project roots. - Infer the exact repository name and GitHub casing from `origin` when possible. If unavailable, fall back to the directory name. - Read `01_Memory.md` and `02_Projects/.md` before writing anything. - Use relevant notes under `05_Decisions/` and `06_Tasks/` when useful. - Inspect repo state using git status, recent commits, and meaningful changed files. - Create or update the session note at `03_Sessions//-.md`. - Preserve exact repository casing for filenames and folders. - Update the living project note when durable understanding changed. - Do not commit or push anything. The session note should include: - `# Session Handoff` - `## What changed` - `## Files touched` - `## Commands run` - `## Decisions made` - `## Open questions` - `## Next actions` - `## Suggested updates to .md` - `## Suggested updates to Decisions` - `## Suggested updates to Tasks` ``` --- ## Discover Repositories And Create Project Notes For each discovered git repository under the chosen project roots, create one note at: ```text 02_Projects/.md ``` Use this workflow for each repo. ### 1. Determine the canonical project name - First choice: parse the repo name from `git remote get-url origin`. - Preserve exact casing from the remote when possible. - If the remote is missing or ambiguous, use the repository directory name. Examples: - remote `git@github.com:someone/VErgo.git` -> `VErgo.md` - remote `https://github.com/acme/my-service.git` -> `my-service.md` - no remote and directory `local-tools` -> `local-tools.md` ### 2. Gather repo context without changing code Inspect only what you need. Prefer fast, non-destructive inspection. Useful sources: - `README*` - `package.json` - `pyproject.toml` - `requirements.txt` - `Cargo.toml` - `go.mod` - `wrangler.toml` or `wrangler.jsonc` - `docker-compose*` - root app directories such as `src/`, `app/`, `server/`, `web/`, `tests/`, `docs/`, `services/` - `git status --short` - `git log --oneline -5` ### 3. Write a durable engineering handoff Each project note must include these sections exactly: - `## Summary` - `## Status` - `## Links` - `## Purpose` - `## Architecture map` - `## File and folder guide` - `## Execution commands` - `## Environment and secrets` - `## Data model` - `## API surface` - `## Current focus` - `## Recent changes` - `## Next actions` Quality rules: - Prefer concrete facts over vague summaries. - Record the repo's real runtime model, not a guessed one. - Use `not found` where necessary instead of inventing content. - Mention generated files when they are important and should not be hand-edited. - If there are no tests, say so clearly. - When relevant, note what must never break. - If a repo appears personal, internal, or experimental, say that plainly. ### 4. Choose an initial status - Use `active` for the current working repo or repos the user clearly identified as active. - Use `tracked` for everything else unless there is strong evidence for another label. - Reflect the same status in both the frontmatter and the one-line home index entry. ### 5. Update `00_Home.md` Add one line per project using this format: ```md - [[02_Projects/|]] - Tracked. . ``` Use `Active.` when justified. --- ## Ongoing Memory Workflow Once the vault exists, install the operating model for future sessions. ### Required behavior for future agents - Before answering repo-specific questions, read `01_Memory.md`. - If working in a tracked repo, read `02_Projects/.md` if it exists. - When durable knowledge changes, propose updating the living project note. - When a meaningful work session ends, propose creating a dated session handoff at `03_Sessions//-.md`. - Use `05_Decisions/` for durable cross-session decisions. - Use `06_Tasks/` for standalone or cross-repo work tracking. - Do not write to the vault automatically after bootstrap unless the user asked or approved. ### Agent integration strategy Install these rules in the current agent environment only if you know exactly where they belong and can edit that location safely. Examples: - OpenCode: global rules or `AGENTS.md` style files in `~/.config/opencode/` - Claude or other IDE agents: custom instructions, global rules, or project instructions if the environment exposes them safely If you cannot safely install them, do this instead: - create the rules snippet in `09_Prompts/OpenVault-Agent-Rules.md` - create the handoff workflow prompt in `09_Prompts/Handoff-Update-Prompt.md` - tell the user exactly which file to paste into their preferred tool Do not fail the bootstrap just because an agent-specific config file was unavailable. Do not treat missing agent integration as a blocker for OpenVault setup. Missing Obsidian, however, should be reported as a remaining setup requirement. --- ## Optional Extensions Only do these if the user asked for them or the environment already supports them safely. - Connect an Obsidian MCP server to the vault path for agents that support MCP. - Add cloud-sync placement if the user explicitly wants multi-machine sync. - Add automation for transcripts, decisions, or daily summaries. - Add repo-local `AGENTS.md` files only if the user explicitly wants repo-local agent behavior. These are optional. Obsidian itself is required; these extensions are not. --- ## Completion Checklist Before finishing, verify that: - the vault folder exists - Obsidian is installed, or the final report clearly marks setup as pending Obsidian installation - `00_Home.md` exists - `01_Memory.md` exists - `02_Projects/` contains one note per discovered repo - `03_Sessions/`, `05_Decisions/`, `06_Tasks/`, and `09_Prompts/` exist - `09_Prompts/OpenVault-Agent-Rules.md` exists - the home index links to every created project note - filenames preserve exact repository casing when available from `origin` - ongoing behavior is approval-first after bootstrap --- ## Final Report Format When done, report completion in this format: ```text OpenVault Setup Complete - Vault: - Project roots scanned: - Project notes created: - Home note: - Memory note: - Rules snippet: - Handoff prompt: - Obsidian: - Ongoing write mode: approval-first ``` Then include: - any fields in `01_Memory.md` that still need user input - any agent-specific integration you could not install automatically - any repositories you intentionally skipped and why Ask one grouped follow-up question set only if it would materially improve `01_Memory.md` or clarify skipped project roots.