Qipu

Local-first knowledge graph CLI for humans and AI agents.

Sometimes it's ok to give your LLM a graph knowledgebase, as a treat.

Qipu is a local-first CLI for building a persistent knowledge graph that both you and your AI coding agents can query. Think Zettelkasten meets man pages meets "please stop re-researching this every session."

The problem: Your LLM agent is brilliant at searching the current codebase but has the long-term memory of a goldfish. Every session, it rediscovers the same APIs, re-reads the same docs, and forgets that clever pattern you found last week.

The fix: A git-backed knowledge store where research actually accumulates. Typed notes, semantic links, value scoring—all queryable by humans and agents alike.

Quick Start

# Install
cargo install --path .

# Initialize a store
qipu init

# Tell your agent
echo "Use 'qipu' for knowledge management. Run 'qipu prime' at session start." >> AGENTS.md

# Capture knowledge
echo "TIL: Rust's ? operator works with Option too" | qipu capture --title "Rust question mark"

# Link notes to build the graph
qipu link add <new-id> <existing-id> --type derived-from

# Search and prime your agent
qipu search "rust error handling"
qipu prime

Example: Building connections

# Capture two related notes
echo "anyhow provides context chains for errors" | qipu capture --title "anyhow basics"
# Created note qp-01J5A...

echo "thiserror is better for library error types" | qipu capture --title "thiserror vs anyhow"
# Created note qp-01J5B...

# Link them with semantic relationship
qipu link add qp-01J5B qp-01J5A --type refines

# See the graph
qipu link tree qp-01J5A

Essential Commands

Run qipu help or qipu <command> --help for full usage details.

Features

• Git-Backed Storage: Notes stored as files in .qipu/. Version, branch, merge with your code.
• Agent-Optimized Output: --format json/records designed for LLM context injection.
• Typed Knowledge: Fleeting notes evolve to permanent; explicit link semantics (derived-from, supports, contradicts).
• Value Scoring: Surface high-quality notes, deprecate stale ones. Filter by --min-value.
• Cross-Session Memory: Research accumulates instead of being rediscovered every session.
• Health Checks: qipu doctor catches broken links, orphan notes, duplicates.

CLI Reference

Core Commands

qipu init                 # Create a new store
qipu create               # Create a new note (opens editor)
qipu capture              # Quick capture from stdin or args
qipu list                 # List notes (--type, --tag, --since, --min-value filters)
qipu show <id>            # Display a note (--links for connections)
qipu search <query>       # Full-text search with ranking (--min-value, --sort value)
qipu inbox                # Show unlinked fleeting notes

Value Management

qipu value set <id> <score>    # Set note value (0-100, default: 50)
qipu value show <id>           # Display current value

The value field represents note quality/importance:

• 0-20: Deprioritized (superseded drafts, duplicates)
• 21-80: Standard (general research, work-in-progress)
• 81-100: High-value (canonical definitions, MOCs, gems)

Link Management

qipu link add <from> <to> --type <t>   # Create typed link
qipu link remove <from> <to>           # Remove link
qipu link list <id>                    # List note's links
qipu link tree <id>                    # Show link tree (--min-value, --ignore-value)
qipu link path <from> <to>             # Find path between notes (--min-value, --ignore-value)

LLM Integration

qipu prime                 # Primer for agent session start
qipu context --moc <id>    # Context bundle from a map of content
qipu context --query <q>   # Context bundle from search
qipu context --tag <t>     # Context bundle by tag

Note: context command supports --min-value to filter by note quality.

Maintenance

qipu index --rebuild       # Rebuild search index
qipu sync                  # Update indexes (--commit, --push)
qipu doctor                # Check store health (--fix, --duplicates)
qipu verify <id>           # Mark note as human-verified

Project Structure

crates/
  qipu-core/        # Core library (domain logic, persistence, indexing)
src/
  main.rs           # Entry point, CLI parsing, dispatch
  cli/              # CLI argument definitions (Clap derive)
  commands/         # Command implementations (depend on qipu-core)
tests/              # Integration tests and benchmarks
specs/              # Implementable specifications

External Tools:

• llm-tool-test - Standalone testing framework for validating qipu with LLM agents (sibling project)

The qipu-core crate is a reusable library that can be used independently of the CLI.

Why Not Just Markdown Files?

You could dump everything in docs/ and grep your way through. We've tried it. Here's what breaks:

The graph structure isn't academic—it's how you answer "what do I know about X?" without reading everything.

Qipu is also inspired by beads—a similar project focused on moving tasks out of progress.md files and enabling context sharing between multiple LLMs.

Development

cargo build                 # Debug build
cargo build --release       # Release build
cargo test                  # Run all tests
cargo clippy                # Lint

Testing with LLM Agents

To validate qipu works correctly with LLM coding agents, install the standalone llm-tool-test testing framework:

# Install llm-tool-test from crates.io (when published)
cargo install llm-tool-test

# Or install from source
git clone https://github.com/mwaldstein/llm-tool-test
cd llm-tool-test
cargo install --path .

# Run qipu validation scenarios (from your qipu project directory)
llm-tool-test run --all --tool opencode

See docs/llm-testing.md for detailed usage instructions.

Documentation

Specs | Agent Guide | Usage Patterns | Building on Qipu | AI Skills Integration