lodestar-brain 0.2.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 lodestar-brain
lodestar demo            # see it work on a bundled sample vault — zero setup

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
L9 — improve	grades whether you acted on past agendas, and self-tunes the weights toward what you do	lodestar run → lodestar tune

(The retrieval substrate L1–L3 is bring-your-own — a zero-dependency BM25 ships as the default. A typed-relationship layer, for contradiction/supersession insights, is the main rung still deferred.)

Self-improving (L9)

Each lodestar run snapshots the agenda it proposed. The next run compares the new graph to that snapshot and tells you which goals you acted on — did that domain grow? did that bridge get built? Over a few runs, lodestar tune reads this revealed preference and proposes bounded, gated adjustments to the category weights, so the agenda leans toward the kind of work you actually do.

lodestar run         # …prints "since last run: acted on 3/5 prior goals · ✓ grew ml (+4 notes)"
lodestar tune        # propose weight changes from what you act on (gated)
lodestar tune --apply

Install

pip install lodestar-brain

Pure-Python; the only runtime dependency is PyYAML.

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.