Build a Markdown Second Brain as a Codex Project

Updated 4 September 2026. The playbook now adapts Vivian Balakrishnan's OKF Graph Wiki ideas for a Codex project, while retaining the Markdown-first workflow inspired by Andrej Karpathy's LLM Wiki.

The useful next step is not simply collecting more notes. It is helping the agent find the right evidence, preserve the qualifications around a claim, and recognize when the knowledge base cannot answer a question. Graph retrieval is an optional upgrade, not a prerequisite for a useful second brain.

A durable second brain needs two different surfaces. Raw source material remains immutable and citable, while the wiki contains maintained summaries, concepts, project notes, templates, and publishable outputs.

The index is the content map and should be read before broad searches. The append-only log records each ingest, durable query output, lint pass, publication, and structural change so the knowledge base remains inspectable over time.

When a source changes, capture a new dated or revision-qualified snapshot rather than replacing the old evidence. Keep the curated index separate from any generated catalog, and treat text retrieved from a source as evidence rather than permission to execute instructions.

The playbook uses a scoped project folder with AGENTS.md, README.md, raw sources and assets, a structured wiki, and a small tools directory. This keeps the task focused; the folder convention does not replace actual filesystem permissions or tool access controls.

Published Gists are outputs rather than the only copy. The canonical Markdown remains in the local outputs folder, where it can be reviewed, versioned, and updated before any remote edit.

A small vault does not need an elaborate retrieval layer. Read the index, use ripgrep for targeted discovery, and add qmd only when keyword search becomes noisy or semantic retrieval has a clear operational benefit.

Tool checks, collection setup, and optional embeddings belong in the runbook, not in every knowledge page. This keeps the wiki readable while preserving a repeatable setup path.

Adoption is staged: start with the index and text search, add structured references to selected pages, and commission an indexed graph only when the need is demonstrated. qmd remains a search option; it is not assumed to implement the playbook's proposed graph schema.

A relationship should identify its subject page, predicate, target or value, supporting source, and any relevant date. Keep prose for explanations and qualifications that do not fit a simple relationship, and distinguish source-backed claims from inferred connections.

The Codex adaptation preserves existing page types and source-path lists, with an optional source_refs field for claim-level attribution. That compatibility profile is OKF-inspired, not strict OKF. Native interoperability needs a deliberate schema migration and tested consumers.

Authorship is not verification. Review records should reflect checks that actually happened, and stale or replaced pages should remain available as history without silently appearing as current advice.

The proposed retriever selects relevant pages, follows a bounded set of relationships, and returns compact evidence within a documented context limit. Its output should expose sources, coverage gaps, freshness warnings, and the retrieval mode actually used.

Finding an entity is not proof that the wiki knows every fact about it. A project page that never records a budget cannot answer a budget question. Tests should include unsupported attributes, adjacent topics with shared vocabulary, unrelated questions, stale claims, broken references, and context-budget limits.

Derived indexes are disposable caches, not a second source of truth. Rebuilding one must not delete authored pages. If a rebuild or evaluation fails, record the failure and use original files transparently rather than presenting an old index as fresh.

Ingest, query, lint, publish, and refresh workflows should each define what to inspect, what may change, which provenance to retain, which indexes or logs to update, and where to stop. These contracts reduce improvisation between sessions.

Large reorganizations and experimental templates can use isolated worktrees in a Git repository. Small maintenance and edits to the canonical wiki stay in the exact local vault state. Queries remain read-only unless filing a durable synthesis is authorized.

The Codex workflow uses explicit task prompts and project instructions. It does not copy Claude-specific slash commands or hook configuration, and copying the runbook does not install a skill, database, background service, or working graph engine.

Before publication, a Markdown output should work without chat history, exclude private material and local-only assumptions, and use a descriptive filename. Publishing remains an explicit action rather than a side effect of maintenance.

After a Gist is created or edited, verify its content, preserve its identity and intended visibility, and save a new revision-qualified raw snapshot. Record the publication in the log without overwriting previous captures.

The living Gist provides the workspace contract, repeatable prompts, compatibility profile, and acceptance checks for an optional graph layer. It is an operating guide and build brief, not a claim that the graph implementation has been installed or validated.