The Problem

Managing a personal knowledge base that also records and evaluates future‑looking claims is cumbersome. Existing note apps expose the note count but not the accuracy of the insights they contain. Users need a lightweight way to embed, track, and settle bets inside markdown files without a separate database or external service.

What This Does

yoink turns a markdown vault into a self‑contained second brain that tracks the truth of each claim. The core logic lives in src/yoink:

  • capture.py gathers context and writes note frontmatter.
  • claim.py defines the Claim data model, including test expressions and settlement logic.
  • ledger.py aggregates outcomes and computes scores (confidence, Brier, gap).
  • tui/app.py provides a terminal UI that lists, searches, and settles notes with keyboard navigation.

All state is stored in the vault itself; no external DB is required. The CLI in src/yoink/cli.py exposes commands such as yoink demo, yoink settle, yoink score, and yoink tui.

How It Is Wired

Entry points

  • src/yoink/__main__.py imports cli.run and passes sys.argv.
  • src/yoink/cli.py uses click to dispatch subcommands to functions in modules such as claim, ledger, vault, and tui.

Control flow

  1. CLI dispatch (cli.run) → specific command handler (e.g., settle).
  2. Command handler calls yoink.claim.read_claims(vault_path) → src/yoink/claim.py.
  3. Settlement reads external data via src/yoink/chain.py or src/yoink/pulse.py, applies the test, and writes back to the markdown file.
  4. Score (ledger.score) aggregates all files in the vault, reads the outcome fields, and prints statistics.

Side effects

  • File I/O: reading/writing markdown in the vault (src/yoink/links.py for link resolution).
  • Network I/O: optional chain or pulse data sources (e.g., chain.py calls external APIs).
  • Terminal UI rendering (src/yoink/tui/app.py uses urwid to draw panes).

Responsibilities

  • cli.py – command routing.
  • claim.py – data model, parsing, settlement.
  • ledger.py – scoring, aggregate metrics.
  • tui/app.py – interactive interface.
  • links.py – link extraction and graph building.

The graph is a simple acyclic dependency chain; only cli.py is a hub. Modifying claim logic will ripple through all commands that read claims, but the UI and score functions remain insulated.

How To Use It

# Clone the original source
git clone https://github.com/DefiLeoo/YOINK && cd YOINK

# Install editable in a venv
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Create a demo vault
yoink demo          # creates ~/yoink-vault with sample notes

# Open the TUI
yoink tui           # launch the four‑pane terminal UI

# Settle claims that are due
yoink settle

# View aggregated score
yoink score

No configuration files or env variables are required; all settings are embedded in the vault’s markdown files.

Real‑World Use

A researcher keeps a vault of experiment ideas. Each idea is written as a claim with a test expression. Every week, yoink settle pulls the latest data from a public API, evaluates the test, and writes the outcome back into the note. The researcher can then run yoink score to see how often their predictions were correct, guiding future hypothesis formulation.

---
title: "New algorithm improves accuracy by 10%"
claim: accuracy > 0.90
settles: 2026-10-15
reads: model/eval.json
test: gte 0.90
confidence: 0.8
---

Code Health & Issues

  • Low – Dependencies declared without a lockfile – pyproject.toml (non‑reproducible builds).
  • Low – No explicit version pins in pyproject.toml – potential dependency drift.
  • Low – Missing CI/CD for linting or type checking (only test workflow).

The repository contains a LICENSE file, a .github/workflows/test.yml for unit tests, and a docs/ directory, but lacks a Dockerfile or Makefile. The pyproject.toml uses Poetry‑style syntax but does not specify a [tool.poetry.lock] file.

The Bottom Line

yoink is a compact, zero‑dependency tool that embeds prediction tracking directly into an Obsidian‑style vault. Its clear separation of concerns and minimal runtime footprint make it easy to adopt. The main trade‑off is the lack of a lockfile, which can affect reproducibility in larger teams. It is best suited for individual knowledge workers who value self‑contained, audit‑ready note management.