koi-quipu 0.1.0

Quipu — a human-first synthesis brain that any of your agents can read from and write to. Part of the KOI suite.

Quipu

A human-first synthesis brain that any of your AI agents can read from and write to.

Part of the KOI ("Kernel of Intelligence") suite.

Quipu is a personal knowledge-management system whose primary job is synthesis — linking atomic ideas so understanding compounds over time — exposed to every AI you use through one gateway. Markdown files in git are the source of truth; everything else (the search index, the optional Postgres mirror) is a derived, disposable cache you can rebuild from the files at any time.

• Design & rationale: DESIGN.md
• Feature status: ROADMAP.md
• Run on Supabase: docs/SETUP-supabase.md

Why

• You own your data. Plain Markdown in your own git repo — no lock-in, diff-able, yours forever.
• One brain, every agent. A single MCP gateway, so Claude Code (or any MCP client) reads and writes the same notes you edit by hand.
• Synthesis over storage. Typed links make a graph, not a folder — retrieval follows relationships, not just keywords.
• Two halves. Curated notes (durable truth) and a raw Capture lake (a firehose that decays); a nightly "dream" mines the lake into notes and forgets the rest.
• Pluggable + degrades gracefully. Swap the embedder, reranker, and storage engine by env var; with no extras installed it still runs on keyword search.

Quickstart

pip install -e '.[mcp]'          # add ,local for bge-m3; ,hosted for Supabase; ,dev for tests
quipu init --demo               # scaffold ~/quipu with demo notes + write ~/.quipu/config.toml
quipu reindex
quipu search "atomic notes"

The vault defaults to ~/quipu/ (pure Markdown). Its disposable index lives inside at ~/quipu/.quipu/; user config is ~/.quipu/config.toml; secrets are env vars (QUIPU_*).

The vault has four tiers, each with a _template.md:

• fleeting/ — quick captures, processed later
• sources/ — one note per paper / url / video / conversation
• permanent/ — atomic ideas in your own words, richly linked
• structure/ — MOCs: curated entry points into clusters

Link freely with [[wikilinks]]; add typed links: (supports / contradicts / refines / example-of / derived-from / part-of / relates-to) for relationships the synthesis engine reasons over.

CLI

quipu init --demo                               # scaffold + seed demo notes + write config
quipu capture "a stray thought"                 # fleeting note
quipu create "An atomic idea" --type permanent  # fleeting|source|permanent|structure
quipu link <src-id> <target-id> refines         # typed edge
quipu search "atomic notes"                     # hybrid (keyword + semantic), reranked
quipu get <id>                                  # note + typed neighborhood
quipu reindex                                   # rebuild the disposable index
quipu recall                                    # auto-recall hook (pull relevant notes + working memory)
quipu config get/set <key>                      # get/set vault|embed|rerank|backend
quipu stats
quipu stash "a raw thought from a chat"         # land it in the Capture lake
quipu search-lake "what was I working on"       # hybrid search over raw captures
quipu discover                                  # suggest latent links: related, unlinked notes
quipu confirm <id> / reject <id>                # triage a provisional draft (reversible)
quipu db check / init / hydrate                 # storage backend: SQLite or Supabase

How it works

Two halves, one engine. Synthesis is the curated note graph (the .md files = truth). Capture is a disposable raw lake — stashed snippets and agent chats in vault/.quipu/capture.db (gitignored). Capture is not truth and never becomes files; the dream mines it into notes and the rest decays. Both run on the same keyword (FTS5/tsvector) + vector + cross-encoder rerank pipeline behind one gateway — no separate graph server.

The nightly dream (consolidation). "Every night we dream and forget." The intelligence — clustering raw captures and drafting notes — is an agent skill (skills/nightly-dream/), not Python: the agent in the loop is the LLM, working through the MCP gateway (recent_captures → cluster → create_note → supersede_capture → forget → review_queue). Only the deterministic bits are code (Forget = salience decay/archive; the review-queue writer). Run it by connecting the MCP server and invoking the nightly-dream skill (cron or on demand).

The decision stream (vault/.quipu/decisions/, gitignored) is an append-only, observer-only log of every agent draft and inbound edge — day-zero training data for a future curation model. It never gates a write; delete it and the vault is unchanged. QUIPU_DECISIONS=0 turns it off.

Every write is validated, provenance-stamped, indexed, and auto-committed to git. The index lives in vault/.quipu/ (gitignored, rebuildable via quipu reindex).

Embeddings & reranking

The default QUIPU_EMBED=hash is a dependency-free bootstrap so everything runs immediately — keyword search is real; only the semantic half is a placeholder. For real semantics:

pip install -e '.[local]'
export QUIPU_EMBED=bge-m3        # or st:<any-sentence-transformers-model>
export QUIPU_RERANK=bge          # cross-encoder rerank — the biggest accuracy lever
quipu reindex

Needs ~5 GB free for the two models (BGE-M3 + bge-reranker-v2-m3). Both are pluggable and degrade gracefully: without the local extra, embeddings fall back to the hash bootstrap and rerank to no-op (with a stderr notice) — the system still runs.

Storage: SQLite (default) or Supabase

SQLite is the default — zero setup, offline, private (brute-force vector search, fine to ~10k notes). To run on Supabase Postgres + pgvector (multi-machine, HNSW-indexed) set QUIPU_POSTGRES_DSN (the secret) then quipu db use postgres — one command that persists the choice, creates the tables, and rebuilds notes from the vault. Switch back anytime with quipu db use sqlite. The two are interchangeable (notes rebuild from the Markdown truth either way); the vector column auto-sizes to your embedder. Full walkthrough: docs/SETUP-supabase.md.

Connect an agent (MCP gateway)

The server exposes the brain's tools over stdio:

claude mcp add quipu -- quipu serve

Then any MCP client (e.g. Claude Code) reads and writes the same brain you author by hand. The quipu recall hook auto-recalls relevant notes + working memory into every turn.

Distribution

The PyPI package is koi-quipu. The CLI command is quipu.

Contributing

Small, dependency-light Python — see CONTRIBUTING.md. Tests are hermetic: pip install -e '.[dev]' && pytest -q.

License

MIT.