Metadata-Version: 2.4
Name: lodestar-brain
Version: 0.1.0
Summary: 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.
Project-URL: Homepage, https://github.com/Trashpanda62/lodestar-brain
Project-URL: Repository, https://github.com/Trashpanda62/lodestar-brain
Project-URL: Issues, https://github.com/Trashpanda62/lodestar-brain/issues
Author: Trashpanda62
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: knowledge-graph,markdown,note-taking,obsidian,pkm,second-brain,zettelkasten
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.9
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

```bash
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

```bash
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:**

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

**Then point it at your own notes:**

```bash
# 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
```

```yaml
# 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`](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](LICENSE). See [NOTICE](NOTICE).
