An Obsidian vault for collecting useful work, thinking through it honestly, and turning it into reusable understanding and writing. Papers, repositories, blogs, websites, datasets, videos, and other works all follow the same basic model.
Markdown is the source of truth. You and AI agents work on the same files.
Start Codex from this repository—not from a parent directory containing it:
cd /path/to/obsidian_notes
codexIn the Codex app or IDE extension, open obsidian_notes as the workspace folder. Starting inside a subdirectory of this repository also works.
At startup, Codex automatically:
- reads
AGENTS.mdfor the vault-wide rules; - discovers the repo-local skills under
.agents/skills/; - learns each skill's name and purpose, then loads its full instructions when needed.
You do not install or paste the skills into each new session. Use /skills to confirm that add-source, develop-topic, and cite-source are available. Then invoke one explicitly with $add-source, $develop-topic, or $cite-source, or let Codex select it from your request.
For a quick startup check, ask:
Read AGENTS.md, list the repo-local skills available here, and briefly summarize the vault rules before making changes.
If the skills are missing, confirm that the Codex workspace is this repository or one of its subdirectories, then restart Codex. Codex searches for .agents/skills/ from its starting directory upward to the repository root; it does not search downward into a nested repository. See the Codex skills documentation.
Open this repository as an Obsidian vault, then open [[00 Home/Research Hub]]. No community plugin is required.
The common agent commands are:
Use $add-source to add <link> with tags: <tags I chose>.
Use $develop-topic to start or continue a scratch board about <idea>.
Use $cite-source to cite <title, link, DOI, or source note> in <draft and location>.
Find and compare my sources about <question>. Separate source claims from my thoughts.
You can also do everything manually with the templates and native Obsidian features.
- Sources are collected external works. One collected work equals one Markdown note in
01 Sources/. - Tags are retrieval handles chosen by you. [[System/Tag Pool]] keeps their spelling consistent.
- Topics are optional, flexible scratch boards where you and agents develop an idea together.
- Writing contains reviews, blogs, and other drafts built from the vault.
- Reflections are optional notes for deciding what deserves attention again.
00 Home/ dashboards and Obsidian Bases
01 Sources/ one note per collected work
02 Topics/ shared scratch boards
03 Writing/ reviews and blog drafts
04 Reflections/ optional periodic reflection
90 Templates/ note templates
99 Attachments/ pasted files and images
System/ schema, tag pool, and generated index
.agents/skills/ repository-local agent workflows
To add a source manually, create a note in 01 Sources/, insert [[90 Templates/Source]], fill its metadata, choose tags from [[System/Tag Pool]], and use the filename described in [[System/Vault Schema]].
To let an agent add one, always provide both the work and your tags:
Use $add-source to add https://arxiv.org/abs/... with tags: llm, agents.
Agents may normalize the tags you supplied, but may never infer tags from a title, link, abstract, README, or content. New user-supplied tags are registered in the tag pool.
Source status stays deliberately small:
saved → active → done
The source template is a comprehension grill, not a decorative summary. It asks what the work actually did, what evidence supports it, where it fails, and what you believe after reading it. Only you answer that grill, check the Done gate, or mark a source done.
A topic is a shared, evolving scratch board around a question, theme, possible blog, review, or unfinished idea. It is not part of the tag taxonomy and has no required workflow.
Use it for source links, rough notes, questions, comparisons, disagreements, tentative claims, evidence gaps, outlines, or draft fragments. Add and remove sections freely. Agents can gather sources, compare ideas, organize material, critique an argument, or clean up a section when asked while preserving your writing and judgment.
Create one manually from [[90 Templates/Topic]], or ask:
Use $develop-topic to start a scratch board about agentic reinforcement learning and gather relevant vault sources.
Find existing topics in [[00 Home/Topic Board.base]].
Create drafts in 03 Writing/ from [[90 Templates/Writing]]. Organize evidence around claims and keep source claims, your interpretation, and agent inference distinguishable.
To cite a vault source or an unseen work:
Use $cite-source to cite https://example.com/work in my draft after the sentence ending “...”.
The first citation in a note prompts for APA 7—the default—IEEE, Chicago author-date, or MLA 9. The choice is stored in citation_style and reused. The agent verifies metadata, deduplicates references, inserts an inline marker only at a clear location, and updates the References section.
An unseen work may remain citation-only. Citing it does not create a source note or trigger a tags prompt.
Find drafts in [[00 Home/Writing Board.base]].
Use [[00 Home/Source Library.base]], the Tags pane, Search, Backlinks, and Properties. Useful searches include:
tag:#llm
tag:#agents tag:#tool-use
[type:source] [status:active]
[type:source] [source_type:repository]
[type:source] [metadata_status:unverified]
Agents begin with System/Indexes/sources.jsonl for retrieval, then read the relevant source notes before making claims.
After changing sources or topic metadata, rebuild and validate:
python3 .agents/skills/add-source/scripts/build_source_index.py
python3 .agents/skills/add-source/scripts/validate_vault.pySystem/Indexes/sources.jsonl is generated output and should not be edited manually.
The detailed contracts live in [[AGENTS]], [[System/Vault Schema]], [[System/Tag Pool]], the templates, and the repo-local skills. Those files keep different AI assistants aligned without making this README a second rulebook.