Obsidian × Codex Knowledge Base Starter

Start with the distinction

This is not another notes app. It is a workflow for an AI-maintained local knowledge base

Obsidian is an optional interface for reading, navigation and backlinks. The durable asset is still a folder of ordinary local files. Codex or Claude Code follows the packaged rules to ingest sources, organise knowledge, create justified relationships and answer questions. Multi-format import is only the entry point; the result is traceable raw evidence, reusable wiki pages, meaningful two-way links and cited answers.

What is included

The decisions needed to run the knowledge base are already packaged

This is not an empty Obsidian vault. Folder responsibilities, source records, duplicate checks, wiki formats, relationship rules and completion criteria are included.

First-use guide: START-HERE.md explains how to open the folder, add the first source and ask the first question.
Agent instructions: AGENTS.md and CLAUDE.md give Codex and Claude Code the same maintenance contract.
Data layers: inbox preserves added files, raw stores traceable text and wiki stores reusable knowledge.
Automated checks: The package includes format conversion, SHA-256 duplicate detection, index checks and two-way link validation.

Requirements

What you need before adding the first file

Codex or Claude Code and Python 3.11 or later are required. Obsidian is recommended as a visual reading interface, but it is not the database and is not required for the workflow to operate.

Windows: Windows 10 and 11 are supported, with a PowerShell launcher included.
macOS: Current macOS versions are supported, with a shell launcher included.
First run: Fixed parser dependencies may be downloaded into the local .vault-runtime directory. Source files are not uploaded for conversion.

Ingestion rules

What the agent must complete after a one-sentence request

The agent should only reply ‘Added to the knowledge base.’ after the complete workflow passes. It does not need to spend tokens producing a separate work report.

1
Preserve the original file. Only process material placed in inbox or explicitly named, and never overwrite the source.
2
Create traceable evidence. Convert supported formats into a standard Markdown raw record with the relative path, format, SHA-256 and conversion limits.
3
Check duplicates and existing knowledge. Reuse or update an existing wiki page when appropriate instead of creating a second copy.
4
Create justified two-way relationships. A shared keyword is not enough; the relationship must have a type such as supporting evidence, applicable condition or counterexample.
5
Update the index and validate the source citation, destination, link existence and reciprocity. A failed check means the ingestion is not complete.

Start here

From download to the first cited answer

Start with one supported document and one sentence: ‘Add this file to the knowledge base.’ You do not need to perfect the note, choose its filename or decide where the knowledge page belongs.

1
Download and extract v2.0.0, then confirm Python 3.11 or later is available.
2
Open the folder in Codex or Claude Code. Add Obsidian only if you want visual browsing.
3
Place one supported file in inbox and give the one-sentence ingestion request.
4
Let the agent preserve, convert, connect and validate the material.
5
Ask a question and require citations to the wiki page and raw source.

Sources and validation

The durable result is not a single AI summary

Every ingestion retains the evidence baseline and a readable knowledge page. New material must also be checked against existing knowledge. A meaningful relationship becomes a two-way link; a weak match stays unlinked instead of making the graph look artificially busy.

raw: Stores extracted content, date, format, hash and source path without being overwritten by later synthesis.
wiki: Stores reusable conclusions with citations and an explanation of how they relate to other knowledge.
related: Requires a relationship type, an existing destination and a reciprocal link. Shared vocabulary alone is not evidence.
query: Answers from vault material and cites both wiki and raw. If evidence is missing, the answer states what is unavailable.

Limits

Formats that can be added directly, and formats that need preparation

The starter contains no one else’s knowledge. You still decide whether a source is appropriate to process with your current AI tool, and structural validation cannot guarantee identical semantic judgement on every run.

Directly supported: Markdown, TXT, JSON, YAML, CSV, text-based PDF, DOCX, PPTX, XLSX and XLSM.
Not currently supported: Scanned PDFs, images, audio, video and legacy DOC, PPT or XLS files. These require OCR, transcription or conversion first.

Use cases

Start with material you will need to question again

Do not begin by moving an entire drive. Choose a small, recurring subject for which you can ask a useful question immediately: project decisions and retrospectives, study and research notes, content evidence, or tool and experiment records. This makes it possible to verify the ingestion and retrieval behaviour before expanding the scope.

Access and version

The fixed v2.0.0 ZIP is available under the MIT License and has passed automated checks on Windows and macOS. Its SHA-256 is 35fc47cf84bb929a66c07000f1f605a9d3f0daa1d33a1f7ddf8ad5fcdfd27b82. The first end-to-end usability record from a non-owner is still pending and is not claimed as complete.