npm package: @safetnsr/broth
Description: slurp your knowledge base. local knowledge engine for devs and agents.
Author: safetnsr
Latest version: 0.4.0

# broth

**slurp your knowledge base.**

local knowledge engine for devs and agents. throw your markdown folders in, get semantic search, wikilink graphs, task tracking, and vault health — all from the terminal. no cloud, no electron.

powered by [qmd](https://github.com/tobi/qmd) (bundled, no separate install needed).

```bash
npx @safetnsr/broth slurp ./my-notes
broth recall "what did we decide about auth?"
```

## install

```bash
npm i -g @safetnsr/broth
```

that's it. qmd ships as a dependency — no extra setup.

## commands

broth follows the same command patterns as [Obsidian CLI](https://help.obsidian.md/cli) — familiar if you use Obsidian, intuitive if you don't. all commands support `--json` for structured output and `--copy` to send output to clipboard.

### vault setup
| command | what it does |
|---|---|
| `broth slurp [path]` | ingest a markdown folder — index, link, auto-embed |
| `broth simmer` | rebuild everything — re-index, re-link, re-embed |

### notes
| command | aliases | what it does |
|---|---|---|
| `broth pour <name>` | `new` | create a new note (`--overwrite`, `--silent`) |
| `broth taste <note>` | `cat`, `read` | read a note (`--raw` for frontmatter) |
| `broth stir <note>` | `append` | append to a note |
| `broth dump <note>` | `rm` | remove a note |
| `broth move <src> <dest>` | `mv` | move/rename (auto-updates wikilinks) |

### search
| command | aliases | what it does |
|---|---|---|
| `broth sip <query>` | `search` | full-text search (BM25) |
| `broth deep-sip <query>` | | semantic vector search |
| `broth recall <query>` | `query` | hybrid search with reranking, agent-optimized |
| `broth find <pattern>` | | find notes by name or title (`--exact`, `--total`) |

### daily notes
| command | aliases | what it does |
|---|---|---|
| `broth daily` | `journal` | create or read today's daily note |
| `broth daily:taste` | `daily:read` | read today's daily note |
| `broth daily:stir` | `daily:append` | append to today's daily note |

all daily commands accept `--date YYYY-MM-DD` for a specific date.

### properties (frontmatter)
| command | aliases | what it does |
|---|---|---|
| `broth meta <note>` | | view all frontmatter |
| `broth meta:get <note>` | `property:get` | get a property value |
| `broth meta:set <note>` | `property:set` | set a property value |
| `broth meta:rm <note>` | `property:rm` | remove a property |

```bash
broth meta:set meeting-notes --name status --value done
broth meta:get meeting-notes --name status
```

### vault navigation
| command | aliases | what it does |
|---|---|---|
| `broth stock [path]` | `ls` | list all notes (`--total` for count) |
| `broth tags` | | all tags with counts (`--sort name\|count`, `--total`) |
| `broth tasks` | | all tasks (`--todo`, `--done`, `--daily`, `--total`) |

### graph & health
| command | aliases | what it does |
|---|---|---|
| `broth bones <note>` | | outgoing wikilinks |
| `broth backbones <note>` | `backlinks` | incoming wikilinks |
| `broth spoil` | | find orphans + broken links |
| `broth recipe` | `info` | vault health score + stats |

## why broth

your agent's memory is a cold folder of markdown files. broth makes it a warm, searchable knowledge base. you slurp it in, let it simmer, and sip back exactly what you need.

works with any markdown folder — openclaw memory/, obsidian vaults, roam exports, plain notes.

```bash
# index openclaw's memory
broth slurp ~/.openclaw/workspace/memory

# ask it something
broth recall "what tools have we shipped?"

# manage daily notes
broth daily:stir --content "- [x] shipped broth v0.4"
broth daily:taste

# find what's rotting
broth spoil

# manage notes
broth pour "meeting-notes" --content "# Standup" -t meeting
broth meta:set meeting-notes --name status --value active
broth move meeting-notes archive/2026-03-meeting
```

## config

broth writes a `.broth.json` to your vault root and uses `.broth.db` for the link graph. both are local, no network calls.

## license

MIT