forge-me-notes 0.1.0

Build and maintain Obsidian knowledge bases with LLM assistance

forge-me-notes

🇩🇪 Deutsche Version

fmn is a command-line tool for building and maintaining structured Obsidian vaults with LLM assistance.

Use it for anything you want to develop as structured, connected knowledge: business planning, research, civic data projects, hobby projects, home renovation. You describe what you want in plain English — fmn handles the context, the LLM call, and the note writing.

The LLM doesn't write the knowledge. It writes the YAML. The knowledge comes from you.

Works with any consistently structured Obsidian vault. The OpenMash vault is one example — a civic open data toolkit built with fmn.

---

How it works

Your vault → fmn pack → context snapshot
context snapshot + your request → fmn generate → input/notes.yaml
review input/notes.yaml → fmn write → new notes in your vault

Or all at once:

fmn run "Add 3 use cases for air quality monitoring" --provider anthropic

The LLM never writes directly to your vault. fmn generate produces an intermediate input/notes.yaml that you review before fmn write touches anything.

---

Who is this for?

• Anyone who maintains a structured Obsidian vault and wants LLM help expanding it
• Civic technologists and researchers building open data knowledge bases
• NGOs and community groups mapping datasets, user groups, or use cases
• Developers who want a scriptable vault generation pipeline

You do not need to be a programmer. If you can run a terminal command, you can use fmn.

---

Installation

pipx install forge-me-notes

No pipx? Run pip install pipx && pipx ensurepath first, or see pipx.pypa.io. Alternatively: pip install forge-me-notes

Set your vault path:

export VAULT_PATH=/path/to/your/vault
# or pass it per command:
fmn --vault /path/to/your/vault pack

---

Quick start

fmn pack                                                          # snapshot your vault
fmn generate "Add 3 notes about Nordic city cycling policy"      # LLM → input/notes.yaml
fmn write                                                         # review passed → write notes

# Or all at once:
fmn run "Add 3 notes about Nordic city cycling policy" --provider anthropic

# Check vault health:
fmn audit

---

Commands

Command	What it does
fmn pack	Scans your vault → exports context snapshot to context/
fmn write	Reads input/notes.yaml → writes notes into the vault
fmn generate "request"	Context + request → LLM → produces input/notes.yaml
fmn run "request"	Pack + generate + confirm + write in one step
fmn audit	Checks vault health: broken links, orphans, missing properties

---

LLM providers

No API key? Use --provider manual — fmn prints the full prompt and you paste it into any chat interface yourself.

Provider	Flag	Requires
Anthropic (Claude)	--provider anthropic	ANTHROPIC_API_KEY
OpenAI (GPT-4o)	--provider openai	OPENAI_API_KEY
Ollama (local)	--provider ollama	Ollama running locally — free
Manual (any chat UI)	--provider manual	Nothing

---

Command reference

fmn pack

fmn pack           # snapshot index + metadata
fmn pack --notes   # also include full note bodies

fmn generate "request"

fmn generate "Add a user group note for Roma communities" --provider ollama --model mistral
fmn generate "Add 3 inspiration notes about Nordic cities" --provider manual

fmn write

fmn write           # write notes from input/notes.yaml
fmn write --force   # overwrite existing notes

fmn run "request"

fmn run "Update all use cases to reference my new Vienna datasets" --force

fmn audit

fmn audit             # summary (capped at 5 per category)
fmn audit --verbose   # show all issues
fmn audit --fix       # auto-repair broken links with near-matches
fmn audit --report    # save report as a timestamped vault note
fmn audit --trend     # show audit history from .fmn/history.yaml

---

Project structure

forge-me-notes/
├── fmn/
│   ├── cli.py        # entry point
│   ├── pack.py       # vault scanner
│   ├── generate.py   # LLM interface
│   ├── write.py      # note writer
│   ├── audit.py      # vault health checker
│   └── run.py        # orchestrator
├── input/notes.yaml  # generated note specs — review before fmn write
├── context/all.md    # vault context snapshot
├── prompts/system_prompt.md
└── tests/

---

Example vault: OpenMash

OpenMash is a civic open data toolkit built with fmn — a structured Obsidian vault for mapping datasets, user groups, barriers, and use cases for any city. It ships with a Karlsruhe example and a full workshop facilitation kit.

git clone https://codeberg.org/DenvaDude/openmash
cd openmash/openmash-vault
export VAULT_PATH=$(pwd)
fmn audit
fmn run "Add 3 use cases for cycling infrastructure" --provider anthropic

---

Contributing

See CONTRIBUTING.md. See DECISIONS.md for the reasoning behind key design choices.

---

Changelog

See CHANGELOG.md.

---

License

MIT © 2026 OpenMash contributors