Why I Use Obsidian for the Codex

The Codex is not a platform. It is folders and markdown files. The tool you use to work with them is entirely your choice — and REALM is designed that way on purpose. This is why I chose Obsidian, and what it gives me that a blank file explorer does not.

What the Codex Actually Is

Before talking about Obsidian, it is worth being precise about what the Codex is — because the tool choice only makes sense once you understand what you are working with.

The Codex is the living memory of the Realm. Every decision, every completed Task, every piece of context that matters gets written there. Characters read from it and write back to it. When a new Character joins the crew, they read the Codex and immediately understand the company. When the Player is offline, Characters continue because everything they need is written down.

At a technical level, the Codex is a folder structure with markdown files inside. There is no database, no platform dependency, no proprietary format. The root structure has folders for WORLD, PLAYERS, CHARACTERS, SAGAS, SESSIONS, INTELLIGENCE, GUILDS, and the QUEST-BOARD. Inside each folder are markdown files — the Oath, the Destiny, the Zone Overviews, the Character Cards, the SOUL files, the completed Quests.

Plain text. Plain folders. That is the whole thing.

The Codex is technology-agnostic by design. Obsidian, Notion, Google Drive, a folder on your desktop — the tool does not matter. The structure and the discipline to always write back do.

So Why Obsidian

When I started building the Codex for Niflheim Records, I needed a way to work with it that felt comfortable — not just functional. I was going to be in this thing every day, reading files, writing new ones, navigating between a Character Card and a SOUL file and a Zone Overview all in the same session. A file explorer and a text editor technically do the job. But the experience matters when the tool is this central to how you operate.

Obsidian sits on top of your local files. It does not move them, does not convert them, does not lock them into anything. You point it at your Codex folder and it becomes a comfortable visual environment for everything inside. The files stay as markdown. The folders stay as folders. If you close Obsidian tomorrow and open the same folder in any other editor, everything is exactly as you left it.

That matters a lot for REALM. The Codex has to be readable by AI agents as system context, parseable by tools, accessible from the command line if needed. A proprietary format breaks all of that. Obsidian adds comfort on top of plain files without touching what is underneath.

What It Actually Gives Me

The most useful thing Obsidian does for my Codex is make navigation fast. When I am in a Character Card and I want to jump to the Zone Overview that Character owns, or from a Quest file to the Saga it belongs to, I can link between files and follow those links instantly. The Codex has a lot of files. Being able to move through them without hunting through nested folders every time is the difference between a system that flows and one that creates friction.

The second thing is visibility. Obsidian shows the folder structure in a sidebar while you are editing a file. I can see the whole Codex at a glance — which Sagas are active, which Quests are open, which Zones have recent updates — without switching contexts. When I sit down for a Session Start, I can scan the Codex in seconds and know where I am.

The third thing is that it is local and offline. My Codex lives on my machine. Obsidian reads it there. Nothing is stored in someone else's cloud by default, nothing requires a subscription to access, and nothing stops working if a service goes down. For a system this central to how I run my business, I wanted it to be mine.

Fast navigation between linked files. A clear view of the full folder structure while editing. Local, offline, and entirely yours. That is what Obsidian adds on top of folders and markdown.

What It Does Not Change

Obsidian does not change how the Codex works. The structure is the same whether you open it in Obsidian, Notion, VS Code, or a plain text editor. The markdown files your Characters read as context are the same files you edit in Obsidian. There is no Obsidian-specific format, no export step, no conversion. It is a window into the same folder.

It also does not replace the discipline the Codex requires. Obsidian can make it easier to write back to the Codex after a Session — but if you do not write back, the Codex does not grow. The first principle of REALM is that if it is not written, it does not exist. A beautiful interface does not enforce that. You do.

You Do Not Have to Use It

I want to be direct about this because it matters. Obsidian is not part of REALM. It is not recommended over any other tool. It is simply what I use, and I use it because it makes me comfortable working with a folder full of markdown files every day.

If you already live in Notion, your Codex can live there — the structure translates directly into nested pages. If you prefer Google Drive, a shared folder with markdown files works. If you are a developer and you prefer VS Code with a file tree, that is a completely valid setup. The REALM Starter Kit is a folder structure and a set of markdown templates precisely because we did not want the framework to depend on any one tool.

What matters is that you pick something and stay consistent with it. The Codex only works if it is the single place where everything gets written. Splitting it across two tools — or switching platforms every few months — is the thing that breaks the system. The tool is secondary. The discipline is primary.

Use whatever makes you comfortable working with folders and markdown files every day. Obsidian is what works for me. The Codex does not care what opens it — only that you write back to it every time.

My Full Setup for Context

For anyone curious about how the pieces fit together in my live Realm: I run OpenClaw via Slack for the agents, Obsidian for the Codex, Trello as the visual Quest Board, and Google Calendar for scheduling. Each tool does one thing. None of them try to replace the others.

Obsidian is the only one that touches the Codex directly. Everything else references it — agents read from it as system context, the Quest Board tracks what is in motion — but Obsidian is where I write, edit, and navigate the files that make the Realm what it is.

That separation is intentional. The Codex is the source of truth. The other tools serve it. Obsidian just makes the source of truth comfortable to work with.