I have been working with Claude and Claude Code and Obsidian and like many have found it a powerful combination. The real magic is in building your own "Second Brain" in plain old text (Markdown) files. Text files are easy for Claude Code or any other command-line agentic AI tool to search, read, and write to. And Obsidian is designed to help you manage all that text with beautiful two-directional links, inspired by the zettelkasten method of academic scholarship.
In Obsidian the folder all your files are in is called a 'Vault.' I've been using Claude to research, brainstorm, and design a product idea. I have it research for me online, write reports, add them to the vault, and then it and I chat and I direct it to create followup action items, reminders, implementation plans, etc.
Basically, I'm creating both Product Specs and Architecture / Technical Specs for a lightweight spec-driven development workflow. And the best part is - I ask Claude to research best practices for me!
Now, you can do this with any AI, it doesn't have to be Claude, and, you don't have to use Obsidian either. Some people like Logseq, others like Notion, others might just use VS Code.
For me, the combination of Claude Code (command-line AI Agent), Claude Desktop (beautiful UI, searches the web, remembers conversations, drafts markdown reports I can read and give feedback on right there) and Claude Cowork (I can schedule online research tasks, create 3 different Cowork agents doing 3 different tasks in my vault at once) is very powerful.
And the vault is the 'source of truth.' Because AI is not good at remembering stuff. Everything goes in the vault. When its doing a big research task, I have a protocol for it to make "checkpoint" messages to itself in a file.
I won't put my CLAUDE.md in this post, but it (or if you're using Gemini or ChatGPT, it would be AGENT.md is where I put all the prompts (or "context engineering") telling Claude how to behave, giving it the context it needs at the beginning of every session, and, telling it how to use the vault.
And when Claude does something goofy, I tell it to update it's CLAUDE.md with instructions on how to avoid repeating it's error!.
So this whole system is one of human-AI collaboration.
There's a lot of people doing things like this right now - I stole from the best - so nothing here is novel, but I do think my vault "setup" strikes a nice balance between full-on supoer-powered engineer running 10 agents in parallel and basically managing a whole team of AI devs versus a dramatically simpler "hello world" approach to human-ai work.
This particular setup is for researching and designing a software product idea, but, it really can be used for any sort of sophisticated knowledge work. Or, if you're writing code, it could be used in your codebase.
Now - I am paying out the wazoo for Claude Max. It is not cheap. But it gets me Claude Desktop (which is my 'command center' for MCP servers and connectors, because there are tons of them now that are just one-click installs in the Claude Desktop App), Claude Cowork (so I can have multiple research/planning agents run in parallel) and Claude Code (for command-line agentic coding).
And - I get a LOT of tokens.
So, if you're doing professional knowledge work, the acceleration you get from this is extremely valuable and arguably worth the cost.
But - the good news is - Google's Gemini Code Assist command line agent has an incredible free tier (like all things Google), an absolutely massive 1 Million token Context Window (meaning it can slurp up all your docs in one go, and have room to spare), and a killer VS Code Extension.
In fact I've been using Gemini and Claude in combination (especially Gemini's "Deep Research" mode), but, that is a topic for another time (if you're brave google "Claude GaaB" and see what comes up).
OK! Here it is.
This document explains how and why the Chameleon vault is organized. It's a human reference — read this when you need to understand the vault's architecture, not just use it.
Created: 2026-03-04 (session 4). Inspired by evaluation of Ars Contexta and Zettelkasten evidence management practices.
The vault is the project's institutional memory for humans and AI. Every AI session starts fresh. Without the vault, each LLM session would repeat the same questions, lose track of rejected alternatives, and drift from standing decisions.
The vault makes markdown documents the AI memory and its source of truth. [[CLAUDE]].md is the entry point: it tells a fresh AI session what the project is, what's been decided, what's off-limits, and where to find everything. Sessions are disposable and checkpoints are created in the vault over the course of a session in case it's interrupted.
Each important decision has its own doc (usually either ADR - Architecture Decision Record, or PDR - Product Decision Record) with context, rationale, alternatives considered, and consequences. This matters because:
- Future sessions can check why something was decided, not just what was decided
- Rejected alternatives are documented so they don't get relitigated
- When new information arrives, the [[Reweave Protocol|reweave protocol]] can assess whether a decision's rationale still holds
Research docs aren't background reading — they're the evidence base for both technical and product decisions. The [[Research Traceability|research traceability]] norm requires that empirical claims in ADRs and PDRs link back to specific vault research docs. Claims without sources get flagged [unsourced]. Research quality is tagged by maturity level ([established], [supported], [emerging], [theoretical]) so readers can calibrate confidence. This is important because Chameleon is a complex technical product which is at its core productionizing and commercializing both established and leading-edge research in the Learning Science and AI Education / ITL space.
Two complementary protocols keep the vault consistent:
- [[Decision Propagation Protocol]]: When a new decision is made, push it forward into the implementation plan, CONSTITUTION, and CLAUDE.md as needed. A decision that only exists in its ADR is an orphaned decision.
- [[Reweave Protocol]]: When new information arrives, look backward — ask what existing documents it strengthens, weakens, or invalidates. New research docs include a
## Reweave Triggerssection listing affected existing docs.
[[CLAUDE]].md should be as small as possible while still orienting a fresh session. It contains: hard constraints, current phase, standing decisions, architectural concepts, and pointers to everything else. Details belong in the documents themselves — CLAUDE.md points to them via [[wikilinks]].
Things that were moved out of CLAUDE.md to keep it lean:
- Session history → [[session-history]] (grows linearly, rarely relevant to current session)
- Vault design rationale → this document (reference material, not session orientation)
The [[wikilink]] discipline (a [[Hard Constraints|hard constraint]]) requires that vault edits connect references to their canonical locations. This is a compounding investment: every link makes the vault more traversable for both humans browsing in Obsidian and AI agents searching for context. A well-linked vault can be navigated by following connections; a poorly-linked vault requires full-text search for everything.
/ ← CLAUDE.md (entry point), session-history.md
├── strategy/ ← What Chameleon is and who it's for
├── decisions/ ← Why we chose what we chose
│ ├── technical/ ← Stack, architecture (ADR-T series)
│ └── product/ ← Pedagogy, UX, business model (PDR-P series)
├── architecture/ ← How the system is designed (CONSTITUTION, specs)
├── research/ ← Evidence base for decisions
│ ├── learning-science/ ← Primary research literature
│ ├── market/ ← Labor market, policy landscape
│ ├── competitive/ ← Competitor analysis
│ ├── synthesis/ ← Session syntheses, cross-cutting analysis
│ └── dev-workflow/ ← AI coding practices, tooling research
├── business/ ← GTM, revenue, partnerships, funding
├── prototype/ ← Implementation plan, specs, stories
├── vault-guide/ ← This directory: how the vault itself works
└── journal/ ← Daily notes
Why this structure:
- strategy/ and decisions/ are separate because strategy is aspirational (what we want to be) while decisions are committal (what we chose and why). Strategy can evolve fluidly; decisions require ADRs to change.
- research/ is separate from decisions/ because research is evidence, not commitment. Multiple decisions can cite the same research doc. Research docs get reweave triggers; decisions get propagation updates.
- architecture/ contains the CONSTITUTION (invariants) and system design docs. These are downstream of decisions — they describe the system that results from the decisions.
- prototype/ contains implementation artifacts (plan, specs, stories). These are downstream of architecture — they describe what to build next.
- vault-guide/ (this directory) is meta — it describes the vault itself, not the product.
The flow: Research → Decisions → Architecture → Implementation. New information enters at the research level and propagates forward through decisions into architecture and implementation. The reweave protocol checks backward when new research arrives.
| Protocol | Direction | Trigger | Purpose |
|---|---|---|---|
| [[Decision Propagation Protocol]] | Forward | New ADR/PDR | Push decision into plan, CONSTITUTION, CLAUDE.md |
| [[Reweave Protocol]] | Backward | New research, competitive intel, external event | Check if existing decisions still hold |
| [[Research Traceability]] | Linking | Writing/editing any decision doc | Ensure empirical claims cite vault sources |
| [[Wikilink discipline]] | Linking | Any vault edit | Connect references to canonical locations |
Research quality matters. A 30-year replicated finding and a single new study both deserve different confidence levels. The vault uses four tags on research citations:
| Tag | Meaning | Example |
|---|---|---|
[established] |
10+ years, extensively replicated, foundational | BKT (Corbett & Anderson 1994) |
[supported] |
Multiple studies, strong grounding, <10 years replication | Affective state transitions (D'Mello & Graesser 2012) |
[emerging] |
Single study or very recent, promising but unreplicated | Computational laboratory approach |
[theoretical] |
Conceptual framework, no direct empirical validation in this context | Freire's praxis applied to software |
Docs that are AI-generated syntheses or literature reviews (not primary sources) get [secondary] in frontmatter. Claims traced only to secondary sources are weaker — future sessions should look for the primary.
Tags appear inline with citations: claim ([[source]] [established]). They also go in the research doc's frontmatter (evidence-maturity: established) for vault-wide querying.
Current:
- Obsidian — vault editor, graph view, search
- Obsidian Bases (core plugin, enabled 2026-03-07) — queryable vault layer over YAML frontmatter. All 30 decision docs (ADRs/PDRs) have structured frontmatter per [[decisions/_BASES_SCHEMA]]. Index views: [[decisions/ADR-index.base]], [[decisions/PDR-index.base]]. AI sessions: use
obsidian_global_searchwith frontmatter field text to find relevant decisions without cold-loading all 30 files — see [[CLAUDE]].md "Decision Frontmatter Schema" section for query patterns. - Obsidian MCP — gives Claude Desktop/Cowork read/write access to the vault
- Claude Code — filesystem access to vault for coding sessions
- claude-mem ([[decisions/technical/ADR-T008-claude-mem-session-memory|ADR-T008]]) — session memory capture via PostToolUse hook (Claude Code only)
- claude-diary ([[decisions/technical/ADR-T008-claude-mem-session-memory|ADR-T008]]) — structured reflections via PreCompact hook (Claude Code only, not yet set up)
Planned:
- Zotero + Better BibTeX — bibliographic management, PDF storage, reading and annotation. Feeds into Obsidian via the Zotero Integration plugin. See [[vault-guide/research-paper-workflow]] for full three-layer architecture.
- Obsidian Zotero Integration plugin (mgmeyers) — pulls annotations and metadata from Zotero into vault literature notes. Nunjucks-based templates generate structured notes with frontmatter, highlights, and synthesis sections.
- MinerU / Marker — PDF-to-markdown conversion for select papers where Claude needs full-text reasoning. MinerU preferred for academic papers (better equation/table handling). Deferred until specific reweave or synthesis need arises.
Evaluated and deferred:
- qmd (tobi/qmd) — semantic search over markdown vaults via local embeddings + MCP server. Deferred: vault is small enough that keyword search + wikilink discipline covers current needs. Revisit when vault grows or claude-mem generates enough session data that keyword search becomes noisy.
- Ars Contexta — AI-powered vault generator. Evaluated 2026-03-04; cherry-picked three practices (wikilink discipline, reweave protocol, research traceability) rather than adopting wholesale. Our vault is already more purposeful than what it generates.
Update this document when:
- A new protocol is added to the vault workflow
- The directory structure changes
- A new tool is adopted or evaluated and deferred
- The design philosophy shifts in a way that affects how the vault should be used
This is a reference doc, not an operational doc. It doesn't need to be loaded at session start — it's for when you (Adam) want to remember why things are the way they are.