<p align="center"><img src="docs/stack/thread-workshop/renders/tambo.png" width="704" alt="Tambo: a toolkit connects the components, in the shared Thread Workshop illustration style"/></p>
# Tambo
Install the Quipu stack from a plan you can review, then prove the selected tools
work. Give an agent durable memory and code context, without assembling every tool
by hand. Tambo is a CLI and [agent skill](skills/tambo/SKILL.md).
The compatibility command `caboodle` remains available.
## Why you would want it
Choose the parts that solve your problem; you do not need every tool.
- **Keep knowledge you can explain:** Quipu stores facts, provenance and history;
Camayoc checks incoming knowledge, using shared vocabulary and shapes from Quechua.
Write enforcement depends on your configured rules.
- **Give a coding assistant useful context:** Bobbin searches your code and supplies
context; Yupana follows code structure and can check actions against policy.
- **Track work across people and agents:** Seeds keeps work items in Quipu;
Shantytown runs agent crews against that work.
- **Connect events to action:** Chaski delivers reactions and notifications, Shuttle
records signed workflow transitions, and Rikuy presents a live brief.
- **Learn from failed tool calls:** Desire Path collects failures into signposts and
feature requests, and can also run on its own.
Tambo composes a reviewable installation plan and verifies the selected tools.
Installing them does not automatically connect every workflow or enable every
policy. [Choose tools for your use case](https://intigraph.github.io/tambo/personas.html),
then [choose an installation profile](https://intigraph.github.io/tambo/profiles.html).
## Install
```bash
Downloads the latest release, verifies its SHA-256 and version, and installs
`tambo` and `caboodle` in `${CARGO_HOME:-$HOME/.cargo}/bin`. Requires `curl`,
`tar`, Python 3 and `sha256sum` or `shasum`. Add that directory to `PATH`.
Published archives support Linux x86_64 and macOS arm64/x86_64; **Linux arm64
has no published archive**. Source builds, pinned versions, removal and the
Homebrew alternative are in the [installation reference](https://intigraph.github.io/tambo/installation-reference.html).
**Debian and Ubuntu (amd64):** install from the signed apt repository, which
republishes each checksum-verified release. The package puts `tambo` and the
compatibility `caboodle` command in `/usr/bin`. Check the signing key's
fingerprint before trusting it; the commands stop if it does not match:
```bash
curl -fsSL https://scbrown.github.io/apt/key.gpg -o scbrown-stack.gpg \
&& gpg --show-keys --with-colons scbrown-stack.gpg \
| grep -qx 'fpr:::::::::AB5625C5612F643BF76464DF0DC99924994EC959:' \
&& sudo install -D -m 0644 scbrown-stack.gpg /etc/apt/keyrings/scbrown-stack.gpg \
&& echo "deb [signed-by=/etc/apt/keyrings/scbrown-stack.gpg] https://scbrown.github.io/apt stable main" \
| sudo tee /etc/apt/sources.list.d/scbrown-stack.list \
&& sudo apt update && sudo apt install tambo
```
`apt upgrade` then picks up new releases. unattended-upgrades only installs
from origins it allows, so to have it upgrade tambo too, add
`"origin=scbrown,codename=stable";` to `Unattended-Upgrade::Origins-Pattern`.
A host with the older `caboodle 0.3.4` package moves over with
`sudo apt install tambo` (or `apt full-upgrade`): `caboodle 0.3.4-1` is a
transitional package that depends on `tambo`.
Channels, pinning and rollback:
[scbrown/apt](https://github.com/scbrown/apt#channels-and-pinning).
## First success in three commands
The 21-second recording shows a real interview, plan review and verification
in a private fixture. Setup finishes before recording; agent-hook registration
is not verified. [Read the transcript](docs/demos/terminal/transcript.txt) or
[reproduce the demo](docs/demos/terminal.md).
Run in an empty directory you intend to keep:
```bash
tambo quickstart
```
This saves a reviewed retrieval plan, installs Quipu, Camayoc and Bobbin, and
checks each tool. Success is exit 0 and `quipu: verified`, `camayoc: verified`,
`bobbin: verified`. Keep `caboodle-plan.toml` and `.caboodle/` to resume.
See the [compatibility contracts](docs/book/src/compatibility.md) for retained aliases and state paths.
Recheck the same install:
```bash
tambo verify
```
### Advanced: use your own projects and agents
The following sections cover existing projects and shared-service setup.
## On your own code
Run Tambo in a directory where you can keep its plan and installation state.
| Choose tools and review an installation plan | `tambo init --guided` |
| Check prerequisites before installing | `tambo doctor --plan caboodle-plan.toml` |
| Recheck the selected tools | `tambo verify --plan caboodle-plan.toml` |
Flags and plan fields: [command reference](https://intigraph.github.io/tambo/reference.html).
## Wire it into your agent
`tambo quickstart` also adds query-first hooks to Claude Code and Codex, so
each session starts by checking the knowledge graph. `tambo hooks verify` checks
them; `tambo hooks uninstall` restores your settings. Codex asks you to trust
the hooks on its next start. See [query-first hooks](https://intigraph.github.io/tambo/agents.html#query-first-hooks).
For issued credentials, remote stores and registering Bobbin with your agent,
use the [agent and installation reference](https://intigraph.github.io/tambo/installation-reference.html).
The default quickstart is local and needs no account or remote server.
From the code repository you want searchable, initialize and index it before
registering the server by absolute path:
```bash
bobbin init
bobbin index
claude mcp add bobbin -- "$(command -v bobbin)" serve "$PWD"
```
## Before you start
The local quickstart needs no account or remote server. Keep its plan and state
in a writable directory. The release installer needs `curl`, `tar`, Python 3
and a SHA-256 utility; source builds need Rust. Linux x86_64 and macOS
arm64/x86_64 have release archives; Linux arm64 requires a source build.
Remote stores need their own endpoint and issued credentials.
## What's next
- [The Tambo book](https://intigraph.github.io/tambo/): installation, verification and profiles.
- [Docs map](https://intigraph.github.io/tambo/docs-map.html): find the detailed guides.
- [Getting started](https://intigraph.github.io/tambo/getting-started.html): review your first plan.
### Profiles and repository knowledge
- [Choose a profile](https://intigraph.github.io/tambo/profiles.html) or use `tambo init --guided`.
- [Camayoc](https://github.com/intigraph/camayoc): vocabulary, shapes and governed agent memory.
- [Getting started](https://intigraph.github.io/tambo/getting-started.html) and [command reference](https://intigraph.github.io/tambo/reference.html).
- **Load this repository's graph:** repository-pendant publication is pending.
When a release provides the archive, checksum and provenance, follow Quipu's
[verified import workflow](https://intigraph.github.io/quipu/sharing/index.html).
Import stages knowledge; it does not promote it into ROOT automatically.
### Delivery events and DORA
After installing Quipu and Camayoc, bring deployment outcomes and change history
into the same governed memory. Camayoc supports CDEvents on CloudEvents from
Actions, Ansible, Terraform and native producers; see the
[delivery emitter catalog](https://github.com/intigraph/camayoc/blob/main/catalog/README.md).
Adapter setup and event coverage are separate from installing the stack.
Tambo does not enable deployment emitters or prove DORA coverage.
The four metrics need recorded deployment and change history for the selected
service and time window; missing history is not a measured zero.
## 🧺 The stack
The Quipu stack is built around a governed, bitemporal knowledge store: shared
facts, decisions and work history your agents can query. Quipu can check writes
against your rules, records where each fact came from, and answers what was true
when.
| [tambo](https://github.com/intigraph/tambo) | 🧰 Agent Platform Toolkit - installs and configures the quipu stack |
| [quipu](https://github.com/scbrown/quipu) | stores shared facts with provenance and history; can check writes against your rules |
| [camayoc](https://github.com/scbrown/camayoc) | prepares knowledge and vocabulary for Quipu, with checks before it is admitted |
| [quechua](https://github.com/scbrown/quechua) | shared vocabulary and shapes for interoperable knowledge |
| [chaski](https://github.com/scbrown/chaski) | reacts to graph changes and delivers governed notifications |
| [bobbin](https://github.com/scbrown/bobbin) | indexes your codebase and injects context from that index and Quipu knowledge |
| [yupana](https://github.com/scbrown/yupana) | shows code impact and can read policies from Quipu to govern agent actions |
| [desire-path](https://github.com/scbrown/desire-path) | turns agent mistakes into feature requests; works on its own without Quipu |
| [seeds](https://github.com/scbrown/seeds) | a work item tracker backed by the Quipu knowledge base |
| [shantytown](https://github.com/scbrown/shantytown) | runs crews of AI agents on work items, triggered by hand, on a schedule or by events; can share work and memory through Quipu |
| [rikuy](https://github.com/scbrown/rikuy) | live brief: status, graphs, watches and signed decisions over Quipu |
| [shuttle](https://github.com/scbrown/shuttle) | runs signed agent workflows and keeps their records in Quipu |
## Contributing
Run `just check`, `just book` and `just docs-check`.
## 📜 License
[Apache-2.0 license](LICENSE).
### Repository pendant provider
Repository pendant builders require explicitly pinned model and tokenizer bytes
and an embedding dimension. The input contract is in
[`repository_share_embedding.py`](scripts/repository_share_embedding.py). This
source plumbing does not enable publication or qualify a provider.