Skip to content

Getting Started

This walkthrough follows Waymark's core loop end to end: capture a memory, find it again, ask a grounded question, and reflect.

1. Install

py -m pip install --user pipx
py -m pipx ensurepath
py -m pipx install waymark-memory

brew install pipx
pipx ensurepath
pipx install waymark-memory

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install waymark-memory

The Installation & Updates guide also includes direct GitHub Release wheel commands.

2. Pick where your data lives

By default Waymark stores everything in a per-user home directory. For experiments, point it somewhere disposable:

$env:WAYMARK_HOME = "$PWD\.waymark-runtime"

export WAYMARK_HOME="$PWD/.waymark-runtime"

Run waymark doctor to see the resolved home, your local capability profile, and whether Ollama is detected.

3. See today's loop

waymark today

This shows captures from today, reflection windows that need attention, decision review items, and copyable next commands.

4. Capture a memory

waymark capture --type project "Decided to build the CLI before the desktop app."

Waymark drafts a structured memory card — a title, a summary, a type, and tags — and saves it. Want to see the draft before committing?

waymark capture --preview "Draft this card without saving it yet."

The guided interface (waymark) uses a two-step Draft → Save / Edit / Discard flow for the same capture.

5. Browse the timeline

waymark timeline

Each row includes a memory ID. Open one in detail:

waymark memory show 1

6. Ask a grounded question

waymark ask "CLI first"

Answers are composed only from your saved memories and always cite the sources they used. If nothing matches, Waymark says so instead of inventing an answer. Add --semantic to include vector matches once you've generated embeddings (see Local AI).

7. Reflect

waymark reflect --period week
waymark reflect --period week --save

Reflections are app-only and source-grounded: they summarize counts, types, tags, and recent titles rather than inventing patterns. Saved reflections build a history you can list, compare, and trend over time.

8. Track a decision

waymark decision add "Adopt local embeddings?" \
  --context "Hybrid search would help retrieval." --memory 1
waymark decision finalize 1 --choice "Yes, opt-in" --confidence 4
waymark decision outcome 1 --outcome "Retrieval noticeably improved."

Where to go next