Obsidian Codex Librarian

Obsidian Codex Librarian helps Codex keep an Obsidian vault organized, searchable, and useful.

The plugin uses the Zettelkasten method and it means “slip box” in German. It’s a note-taking method where you build knowledge from small, linked notes instead of storing everything in big documents or folders. In simple terms: Source notes: what you read, watched, heard, or copied from somewhere. Literature notes: your summary of that source in your own words. Permanent notes: one clear idea, written so future-you can understand it. Index/map notes: pages that connect related notes around a topic.

Write notes wherever they naturally happen. Paste rough meeting notes. Save links. Drop half-formed ideas in the vault root. Keep drafts in old folders. The Librarian scans the vault, turns messy notes into a linked wiki layer, preserves originals, and lets you ask natural questions later.

No required inbox. No folder ritual. No cloud database. Just Markdown files you own.

The Basic Idea

You write this anywhere in your vault:

Met with Sam about the office lease.
Rent review is due on 1/8/2026.
Need to check the lease terms before then.

Then ask Codex:

Organize my notes.

The Librarian can split and file the note into the right wiki/ pages, add links, preserve the original, update the search index, and tell you what changed.

Later you can ask:

What did I write about the office lease?

Codex searches your vault and answers with the note path, relevant quote, and wiki citations.

What It Can Do Today

• Set up a ready-to-open Obsidian wiki structure.
• Organize loose Markdown notes from anywhere in the vault.
• Preserve processed originals in wiki/archive/originals/.
• Create source, concept, entity, literature, permanent, question, and index pages.
• Search the whole vault and answer with cited note paths.
• Keep wiki/hot.md as a compact working-memory page.
• Save useful Codex conversations back into the wiki.
• Create Obsidian canvas files and dashboard notes.
• Lint the wiki for dead links, weak attribution, missing frontmatter, duplicate titles, and stale context.
• Work directly on local files. No Obsidian community plugin is required.

The Librarian Direction

This project is moving toward a simple "personal librarian" workflow:

• organize or tidy my notes
• find what I wrote about a topic
• save this conversation to my wiki
• relate these ideas
• notice action-like notes and ask before doing anything outward-facing

Calendar, reminder, email, and task directives are being designed carefully because they need confirmation, date parsing, and safety rules. The current public plugin focuses on local vault maintenance and retrieval first.

Installation

You need three things:

1. Obsidian
2. Codex
3. This plugin

1. Install Obsidian

Download Obsidian from:

https://obsidian.md

Create or open a vault. A vault is just a folder of Markdown files.

2. Install Codex

Install Codex using the current OpenAI instructions for your computer. After installing, open a terminal and check that Codex works:

codex --version

If that prints a version number, you are ready for the plugin.

3. Download The Plugin

Open a terminal in a folder where you keep projects.

On Windows PowerShell:

git clone https://github.com/vlasvar/Obsidian_Codex_Plugin.git
cd Obsidian_Codex_Plugin

On macOS or Linux:

git clone https://github.com/vlasvar/Obsidian_Codex_Plugin.git
cd Obsidian_Codex_Plugin

4. Add The Plugin To Codex

Run this from inside the Obsidian_Codex_Plugin folder:

codex plugin add obsidian-codex-plugin@personal

Then start a new Codex thread so the plugin skills are loaded.

5. Point Codex At Your Vault

Use a fake example path like this as a pattern, but replace it with your own vault folder:

Set up an Obsidian wiki vault at C:\Users\Alex\Documents\MyVault using zettelkasten mode.

On macOS or Linux, the same idea looks like:

Set up an Obsidian wiki vault at /Users/alex/Documents/MyVault using zettelkasten mode.

The setup keeps your existing notes. It adds the folders and files the Librarian needs.

Good First Prompts

Set up an Obsidian wiki vault at C:\Users\Alex\Documents\MyVault.

Organize my Obsidian vault at C:\Users\Alex\Documents\MyVault.

Find what I wrote about property valuation in my Obsidian wiki.

Save this conversation to my Obsidian wiki as "Project Notes".

Lint my Obsidian wiki and tell me what needs cleanup.

Create a canvas called Knowledge Map with my main finance and research notes.

What Gets Added To Your Vault

The plugin creates a wiki/ layer inside your vault:

vault/
|-- .raw/
|   `-- .manifest.json
|-- .vault-meta/
|   |-- mode.json
|   |-- retrieval-index.json
|   `-- transport.json
|-- wiki/
|   |-- index.md
|   |-- log.md
|   |-- hot.md
|   |-- overview.md
|   |-- sources/
|   |-- literature/
|   |-- permanent/
|   |-- indexes/
|   |-- entities/
|   |-- concepts/
|   |-- questions/
|   |-- canvases/
|   |-- meta/
|   `-- archive/
|       `-- originals/
|-- _templates/
`-- .obsidian/

You do not have to browse these folders by hand. They exist so Codex and Obsidian have a durable structure to work with.

How Organization Works

When you ask Codex to organize the vault, it looks for Markdown notes outside maintained/generated areas. It skips internal folders such as .git/, .obsidian/, .raw/, .vault-meta/, _templates/, attachment folders, and archived originals.

For each loose or mixed note, Codex can:

• read the note
• split mixed material into smaller wiki pages
• preserve a path back to the original
• create or update wiki links
• update wiki/index.md, wiki/log.md, and wiki/hot.md
• rebuild the retrieval index
• preserve the original note after it has been represented elsewhere

Helper Commands

Most people can use natural prompts in Codex. If you want to run the helper scripts directly, these are the main ones:

python scripts\setup_vault.py C:\Users\Alex\Documents\MyVault --mode zettelkasten
python scripts\detect_vault.py C:\Users\Alex\Documents\MyVault --create
python scripts\ingest_source.py C:\Users\Alex\Documents\MyVault C:\Users\Alex\Downloads\example.md
python scripts\retrieve.py C:\Users\Alex\Documents\MyVault --query "lease terms" --json
python scripts\lint_wiki.py C:\Users\Alex\Documents\MyVault --json
python scripts\save_note.py C:\Users\Alex\Documents\MyVault "Thread title" --content "Useful context"
python scripts\canvas.py C:\Users\Alex\Documents\MyVault --name main --add-text "Welcome"

On macOS or Linux, use normal Unix-style paths:

python scripts/setup_vault.py /Users/alex/Documents/MyVault --mode zettelkasten
python scripts/retrieve.py /Users/alex/Documents/MyVault --query "lease terms" --json

Safety

• The plugin works on local Markdown files.
• It does not require an Obsidian community plugin.
• It does not silently delete your notes.
• Processed originals are preserved in wiki/archive/originals/.
• Generated wiki notes are drafts. Review important material before relying on it.
• This is not financial, legal, medical, travel, or professional advice.
• Optional REST, MCP, and Obsidian CLI transport detection is metadata only unless explicitly used.
• The plugin is not a backup system. Keep your own backups.

Project Status

Current local verification includes:

19 unit tests passing
plugin validation passing
installed-cache smoke test passing
50-file sample ingest passing
vault lint clean after ingest

Run tests locally:

python -m unittest discover -s tests -v

Inspiration And Attribution

This project is inspired by local-first note-taking, LLM wiki workflows, and the MIT-licensed AgriciDaniel/claude-obsidian project.

This repository is a clean-room Codex-native implementation:

• It does not copy upstream GPL CSS snippets.
• It does not bundle Obsidian community plugin binaries.
• It uses filesystem-first helpers designed for Codex plugin workflows.

License

Apache License 2.0. See LICENSE.