Obsidian × Codex Knowledge Base Starter

Turn PDF, Word, PowerPoint, Excel and text files into a source-traceable local knowledge base that Codex or Claude Code can connect and query.

Who this is for

For people who want an AI-maintained knowledge base without first designing the folders, source records, linking rules and validation checks themselves.

Result

A local knowledge base that preserves original files, converts them into traceable evidence, connects related knowledge and answers with citations.

Start here

Download and extract v2.0.0, then confirm that Python 3.11 or later is installed.
Open the folder in Codex or Claude Code. Open the same folder in Obsidian only if you want a visual reading and link-browsing interface.
Put one supported file in inbox and say: ‘Add this file to the knowledge base.’
The agent preserves the original, creates a traceable raw record, checks existing knowledge, updates the wiki, adds justified two-way links and validates the result.
Ask a question and require the answer to cite both the wiki page and the raw source.

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.

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.

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.

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.

Preserve the original file. Only process material placed in inbox or explicitly named, and never overwrite the source.
Create traceable evidence. Convert supported formats into a standard Markdown raw record with the relative path, format, SHA-256 and conversion limits.
Check duplicates and existing knowledge. Reuse or update an existing wiki page when appropriate instead of creating a second copy.
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.
Update the index and validate the source citation, destination, link existence and reciprocity. A failed check means the ingestion is not complete.

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.

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

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.

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.

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.

Limits

The workflow only processes files deliberately added or explicitly named by the user. It does not scan other folders or upload sources to an online conversion service. Scanned PDFs, images, audio, video and legacy Office formats are not currently supported. Missing evidence must be reported as missing, not replaced with unverified web content.