Metadata-Version: 2.4
Name: koi-quipu
Version: 0.1.0
Summary: Quipu — a human-first synthesis brain that any of your agents can read from and write to. Part of the KOI suite.
Author: Gia Khanh Nguyen
License: MIT License
        
        Copyright (c) 2026 Gia Khanh Nguyen
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/kernel-of-inteligence/quipu
Project-URL: Repository, https://github.com/kernel-of-inteligence/quipu
Project-URL: Issues, https://github.com/kernel-of-inteligence/quipu/issues
Keywords: memory,rag,retrieval,knowledge-management,agents,mcp,embeddings,zettelkasten,pgvector
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.23
Requires-Dist: click>=8.1
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Provides-Extra: local
Requires-Dist: sentence-transformers>=2.7; extra == "local"
Provides-Extra: hosted
Requires-Dist: psycopg[binary]>=3.1; extra == "hosted"
Provides-Extra: watch
Requires-Dist: watchdog>=4.0; extra == "watch"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# 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](./DESIGN.md)
- **Feature status:** [ROADMAP.md](./ROADMAP.md)
- **Run on Supabase:** [docs/SETUP-supabase.md](./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

```bash
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

```bash
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:

```bash
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](./docs/SETUP-supabase.md)**.

## Connect an agent (MCP gateway)

The server exposes the brain's tools over stdio:

```bash
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](./CONTRIBUTING.md). Tests are hermetic:
`pip install -e '.[dev]' && pytest -q`.

## License

[MIT](./LICENSE).
