lodestar-brain 0.1.0

A self-directing second brain for your markdown notes: builds a knowledge graph and hands you a ranked agenda of what to grow, bridge, and fix next.

lodestar-brain

A self-directing second brain for your markdown notes.

Point it at any folder of Markdown (an Obsidian vault, a Zettelkasten, a docs tree) and lodestar-brain builds a knowledge graph and hands you a ranked agenda of what to grow, bridge, and fix next — the sparse-but-important topics, the structural holes between clusters, the near-orphan notes. You (or your own LLM) act on the agenda; lodestar tells you where to point your attention.

Status: v0.1. The self-thinking core — graph (L4), insights (L6), and the self-directing roadmap (L8) — is complete and runs over any folder of Markdown.

pip install git+https://github.com/Trashpanda62/lodestar-brain
lodestar demo            # see it work on a bundled sample vault — zero setup

(Not on PyPI yet — install from source as above. A PyPI release is planned.)

What it is (and isn't)

• It is a self-directing brain: it derives its own knowledge agenda from the shape of your notes (graph centrality, cross-domain gaps, orphans) plus optional priority topics you declare.
• It is not an autonomous executor. lodestar proposes an agenda; it never edits your notes, runs tasks, or "maintains your vault" on its own. Execution is bring-your-own — a human, or an agent you wire up.
• Retrieval is bring-your-own too: a pure-Python BM25 backend ships by default (zero extra dependencies). Plug in your own (embeddings, a reranker, a vector DB) by implementing the small Retriever protocol.

The ladder

lodestar-brain ships the self-thinking layers of a knowledge graph:

Rung	Does	Command
L4 — relate	builds the link graph: hubs, clusters, orphans, cross-domain bridge gaps	lodestar graph
L6 — notice	surfaces emergent observations (synthesis candidates, aging hubs, stalled questions)	lodestar insights
L8 — direct	derives + ranks its own agenda of what to grow/connect/fix next	lodestar roadmap

(The retrieval substrate L1–L3 is bring-your-own — a zero-dependency BM25 ships as the default. The outcome-calibrated self-tuning rung L9 is deferred to a later release: it needs weeks of real usage data before it does anything.)

Install

pip install git+https://github.com/Trashpanda62/lodestar-brain

Pure-Python; the only runtime dependency is PyYAML. (PyPI release planned.)

Quickstart

See it work first — zero config:

lodestar demo            # runs the whole chain over a bundled sample vault

Then point it at your own notes:

# 1. create a config
cp lodestar.example.yaml lodestar.yaml

# 2. edit lodestar.yaml so corpus_dir points at your notes folder
#    corpus_dir: /path/to/your/vault

# 3. run the whole chain → AGENDA.md in ./.lodestar/
lodestar run

# lodestar.yaml — minimal
corpus_dir: /path/to/your/notes
priority_topics:                 # optional — omit for pure curiosity mode
  - name: "My current focus"
    domains: [project-x]         # a folder name in your vault

Commands

Command	What it does
lodestar demo	run the whole chain over a bundled sample vault (zero setup)
lodestar info	summarize what lodestar sees in your corpus
lodestar graph	compute the knowledge graph → brain-map.md
lodestar insights	surface emergent observations → insights.md
lodestar roadmap	derive the ranked agenda → AGENDA.md
lodestar run	all of the above in one pass
lodestar search <q>	BM25 search over the corpus

Outputs go to your state_dir (default ./.lodestar) — never into your notes. The headline deliverable is AGENDA.md: a ranked, actionable list of what to grow, connect, and fix next, with a by-hand checklist per item. You (or your own agent) act on it — lodestar proposes, it never edits your notes.

Configuration

See lodestar.example.yaml for the full annotated config. Notes need no special frontmatter — titles fall back to filenames, domains to the top folder. If you do use YAML frontmatter (title, domain, aliases), lodestar reads it.

License

Apache-2.0. See NOTICE.