Unifying Knowledge and Code
A methodology for developers who think and build in the same place.
Your Tools Don't Talk to Each Other
Developers switch between knowledge tools (Notion, Confluence) and execution tools (IDE, terminal) dozens of times per day.
The rationale behind an architectural choice lives in a Confluence page nobody reads.
That hard-won debugging insight stays in Slack, then disappears forever.
Pointing new engineers to 5+ disconnected systems, each with its own mental model.
Every new conversation with an AI agent starts from zero.
Co-locate Knowledge and Code in a Single Directory Tree
Knowledge and code live together in the same tree.
Daily notes, project docs, commits and configs link to each other.
Agents traverse the same tree humans do from day one.
Projects keep independent git history; the root is intentionally not a repo.
Two Trees, One Workspace
Knowledge, decisions, context and people — the "why" of what you build.
Execution and implementation — the "what" and "how."
Deliberate: prevents accidental commits and keeps workspace history clean.
Two trees, one workspace — OX as metaphor and directory structure.
Organized by Who, What, When, Where
The o/ vault uses a PERM-like taxonomy — four top-level dimensions that map to every type of knowledge a developer needs. Exhaustive by design.
Team members, clients, contacts, stakeholders. Every person gets a note. Every interaction is linked.
Organizations, projects, skills, tools, technologies. The substance of your work.
Daily notes, weekly reviews, monthly cycles, project timelines. The audit trail of decisions.
Offices, servers, cloud environments, deployment targets. The geography of your infrastructure.
Team Members
Clients & Stakeholders
External Contacts
Vendors
Projects & Repos
Organizations
Tools & Tech Stack
Skills & Concepts
Daily Notes
Weekly Reviews
Sprint Cycles
Milestones
Cloud Environments
Physical Servers
Deployment Targets
Office Locations
An Unbroken Audit Trail of Every Decision
Structured notes each day: interactions and tasks.
Links to people, projects, and code.
Trace why choices were made and what code they touched.
Human-readable and parseable by agents.
# 2026.March.16.Monday
## Interactions
- [[Alice]] — discussed auth migration
## Work Done
- Fixed JWT expiry bug in...
- Updated [[infrastructure.yaml]] (staging)
## Decisions
- Chose RS256 over HS256 — see [[auth-decisions]]
## Tasks
- [ ] Write migration guide
Every Repo Independent, Every Repo Accessible
Mirrors remote repos: x/code/remote/{host}/{org}/{repo}/
Each repo keeps its own .git for isolated history.
Predictable files: CLAUDE.md, docker-compose.yml, apps/
16+ repos accessible from the same workspace root.
Turning Isolated Notes into a Living Knowledge Graph
The power of OX is not in any single file — it is in the links between files.
A daily note references a project doc, which references a code repo.
Links to the project doc, the person who reported it, and the infra it touches.
This creates a traversable graph — for humans and AI agents alike.
Not in a Separate Ops Silo
infrastructure.yaml lists servers, containers, DNS and secrets in the o/ vault — not a separate repo.
Deployment maps and env configs are cross-referenced from project and daily notes.
The location is one Obsidian link away — no Slack ping needed.
YAML plus notes makes infrastructure readable and versioned with design rationale.
AI Agents Are First-Class Citizens of the Workspace
The .agents/ directory sits at the workspace root — universal rules and context for every AI agent (Claude, Cursor, Copilot).
workspace-structure.md, infrastructure.yaml, philosophy.md.
SOUL.md and IDENTITY.md encode team values, preventing AI suggestions that violate architecture.
Agents get the same context humans get. The workspace IS the AI's context window.
CLAUDE.md in Every Repo Means Instant Productivity
CLAUDE.md lets an agent read one file and grasp purpose, architecture, and constraints.
Agents can follow context across notes, docs, code, and infra references.
A memory layer preserves key context across conversations so agents don't start from zero.
Philosophy docs enforce project values and discourage risky rewrites.
# CLAUDE.md — CRM API
## Purpose
CRM API for web and mobile clients.
## Architecture
Node.js 22 + Fastify. PostgreSQL (Supabase). Auth: JWT (RS256).
## Conventions
routes in apps/routes/, migrations in supabase/migrations/, no secrets in repo.
## Cross-References
Project doc: [[o/what/projects/crm]] — Infra: [[o/where/infrastructure.yaml]]
Documented in the Knowledge Base — Not Stored There
Manages secrets across all projects. Each repository links to its secret project via .infisical.json.
Dev, staging, and prod with RBAC. Developers get dev secrets, CI/CD gets staging, production is locked down.
The knowledge base documents what each secret is for and when it rotates — but never its raw value.
Any developer can understand the secret architecture without ever seeing a raw credential.
## Secrets: crm-api
| Secret | Purpose |
|---|---|
| DATABASE_URL | Supabase |
| JWT_SECRET | RS256 |
| SMTP_KEY | Transactional |
From Morning Stand-Up to End-of-Day Commit
What was decided yesterday? What's in progress? What's blocked? Start with context.
What are the constraints and decisions for today's task? Review the architecture.
The repo is one directory away in the same workspace, not a separate window.
End of day: link what you touched, what you decided, what you deferred.
Agents have full context automatically. Open Cursor or Claude; they already know the project.
Config is one directory away. No Slack message needed to find where it runs.
Concrete Gains from Unified Context and Zero Switching
Switching between Notion, Jira, GitHub and the IDE breaks flow.
Zero Switching. Everything lives in one directory — you never leave your editor to find docs or infra.
Decisions are buried in old Slack threads.
Decision Archaeology. Daily notes capture the "why" and link to the code that implements the "what".
Docs rot when disconnected from the codebase they describe.
Co-located Reality. Docs live next to code; update the markdown in the same commit.
AI suggests architectures without the project's context.
Unified Agent Context. .agents/ and CLAUDE.md give AI the same context map developers use.
Scalable, Offline-First, and Completely Tool-Agnostic
Start as a personal productivity system. Scale to an engineering team by putting the o/ vault in a shared Git repository. Collective memory grows organically.
No cloud dependencies for your daily workflow. Everything lives on your local disk. Work on an airplane, in a cabin, or during a major cloud provider outage.
It's just Markdown files and Git repositories. If your current tools disappear tomorrow, open the folder in any text editor. Your knowledge outlives the tools.
OX Outperforms Both Traditional Setups and Monorepos
| DIMENSION | TRADITIONAL MULTI-TOOL | MONOREPO | OX WORKSPACE |
|---|---|---|---|
| Knowledge Location | Notion, Confluence, Google Docs (Cloud) | Scattered README files | Obsidian Vault (Local, o/ dir) |
| Code Location | Multiple disconnected repositories | Single massive repository | Multi-repo, unified under x/ dir |
| AI Context | Separate & Manual | Limited to code only | Unified (.agents/ & CLAUDE.md) |
| Cross-References | Manual URLs, easily broken | In-repo relative links only | Bidirectional across code & docs |
From Zero to OX in Six Steps
Create the root directory. Do not run git init here. The root is just a container.
Create the .agents/ directory and add the workspace structure map for AI tools.
Create the o/ directory and initialize it as an Obsidian vault with a PERM taxonomy.
Begin your daily log. Link everything you touch: people, projects, and code repositories.
Clone your projects into the x/code/ tree, mirroring their remote paths.
Add a CLAUDE.md file to each repository to provide instant context for AI agents.
What Makes OX a Methodology, Not Just a Folder Structure
Elegance over speed. Writing code is easy; crafting a maintainable system requires deliberate thought, documentation, and care.
Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away.
Each fact lives in exactly one place. If a decision changes, you update one markdown file, not five disconnected systems.
Read only what you need. The workspace is structured so you can dive deep into a specific component without being overwhelmed by the whole.
The methodology works for any AI tool. Whether you use Claude, Cursor, Copilot, or the next big model, the context structure remains valid.
OX Is Growing Into a Full Developer Platform
Ready-to-use workspace scaffolds. Clone a starter repository that includes the directory structure, Obsidian settings, and default agent prompts.
A blazingly fast Terminal User Interface built in Rust for navigating the vault, creating daily notes, and querying the knowledge graph without leaving the command line.
Native Model Context Protocol (MCP) servers that allow Claude and Cursor to dynamically query the Obsidian vault and understand cross-references in real-time.
Standardized patterns for multi-player sync, resolving knowledge graph conflicts, and merging daily notes across distributed engineering teams.
One Binary. Every Platform. Zero Dependencies.
No runtime dependencies. Ships as a single self-contained executable.
macOS (Intel + ARM), Linux (x86 + ARM), Windows — one install command everywhere.
curl -fsSL https://iamox.ai/install.sh | bash
init, clone, index, search, serve, status, version
Safe to re-run at any time. Git-backed revert safety on every operation.
ox init Bootstraps EverythingCreates the full workspace tree from scratch in a single 9-step sequence.
290x Faster Than Obsidian CLI Search
BM25 full-text (Bleve) + vector similarity (Ollama embeddings) — ranked together in a single query.
Nodes (notes, tags) + edges (LINKS_TO, HAS_TAG). Zero cloud dependencies.
GraphStore, VectorStore, TextSearchStore, Embedder interfaces. Default: SQLite + Bleve + Ollama.
Neo4j, Qdrant, Pinecone, OpenAI embeddings — swap without changing your workflow.
SHA-256 change detection. Full index: 12.4s. Incremental re-index: 0.8s. Read-only — no file locks.
Your Notes AND Your Repos, in One Graph
ox indexes repos in x/code/ alongside vault notes in o/o/ — one unified graph.
File trees, symbols, git metadata, and dependencies — all indexed as graph nodes.
A note about "auth migration" links to the actual auth code file. The graph spans both trees.
ox search returns both knowledge AND code results, ranked together by relevance.
When your agent searches, it finds decisions AND implementations in a single traversal.
Your Vault Becomes a Tool for AI Agents
ox serve — Stdio MCP ServerStarts a Model Context Protocol server on stdio. No ports, no daemons, no config.
search_vault, find_related, get_backlinks, vault_stats — the full graph, queryable by any agent.
Claude Code, Cursor, Windsurf, and any MCP-compatible agent connects with two lines of config.
The agent traverses the same directory structure humans do — no special API, no wrapper layer.
.agents/AGENTS.md provides universal instructions for all AI agents. The workspace is agent-navigable by construction.
The workspace IS the documentation.
The documentation IS the workspace.