getting started

install

git clone https://github.com/999cleo/bowerbird
cd bowerbird
make build                          # -> ./build/bower

put bower on your PATH:

sudo cp build/bower /usr/local/bin/
# or
ln -s "$PWD/build/bower" ~/.local/bin/bower

an api key

bower works fully offline using the ONNX all-MiniLM-L6-v2 fallback embedder. for higher-quality embeddings and the LLM curation pipeline, set a free Gemini key:

export GEMINI_API_KEY="..."         # https://aistudio.google.com/apikey

first steps

# add a memory
bower curate "We use JWT tokens with 24-hour expiry for API auth"

# ask later
bower query "how does authentication work"

# inspect what's stored
bower status
bower tree

memories live as markdown files under ~/.bowerbird/tree/, one file per memory, organized into a category tree. you can cat, vim, mv, rm, or git add them; bower will reconcile on the next query.

dream mode

bower dream runs offline analysis on your memory corpus: linking related notes, deduplicating near-duplicates, promoting frequently-accessed notes from draft to validated to core, and surfacing contradictions for review.

bower dream-scan      # dry run, prints candidate changes as JSON
bower dream           # apply high-confidence changes
bower dream-apply     # apply *only* high-confidence (skip review queue)

every dream run snapshots the prior state, so bower dream-undo rolls back.

as a daemon

if you want a persistent HTTP API instead of invoking the CLI each time:

bower serve --port 8787

see http api for endpoints.