gonzalo
Gonzalo is the persistence layer for the caliban-ai
stack. It stores versioned records behind one generic Store trait, surfaces
concurrent edits as conflicts rather than losing them, and lets the backing
substrate be the local filesystem, a git repository, an S3-compatible object store,
or a remote gonzalod daemon, as a matter of configuration.
On top of that core sit capability layers: typed domain views (memory tiers, topics, sessions, checkpoints), a normalized ticket layer, the fleet access-control records, vector search — in memory or durable — a knowledge store, and a tree-sitter code graph that agents query through an MCP server.
Where gonzalo fits
| project | role |
|---|---|
| caliban | the agent. Gonzalo started as a shareable home for its local-first state. |
| prospero | runs the caliban agent fleet |
| ariel | the chat bridge for the fleet: Discord today, Slack and Teams later. Shipping at v0.3.0. Its people, identity bindings, role grants, channel configuration, link tokens and audit trail are gonzalo records, and ariel stores nothing of its own: it reads and writes them over gonzalod as the fleet access-control records that shipped in 0.7.0 (ADR 0022, ADR 0023). It is the first consumer of those kinds, and the reason they look the way they do. |
| gonzalo | persistence: records, stores, capability layers, the daemon, and the code-graph MCP server |
Rust consumers depend on the gonzalo facade crate. Everything else talks to the
daemon over HTTP/JSON or gRPC (ADR 0020).
What you get
| binary / crate | what it is | guide |
|---|---|---|
gonzalo (crate gonzalo-cli) | admin CLI: inspect and import records, sync stores, index code graphs, sync tickets | The CLI |
gonzalod (crate gonzalo-server) | the daemon: a store served over HTTP/JSON and gRPC, with namespace-scoped auth | Running gonzalod |
gonzalo-mcp | MCP server that answers code-graph and record queries for agents | The MCP server |
gonzalo (library) | facade over the core, substrates and layers, selected by Cargo feature | Storage backends |
Where to go next
- New to the code graph? Start with The MCP server. It covers install, indexing and registration end to end.
- Deploying the daemon: Running gonzalod.
- Talking to a daemon from something other than Rust: Generating a client.
- Picking a substrate, or embedding gonzalo in a Rust program: Storage backends.
- Deleting records so the delete survives a sync: Deletion, reset & collection.
- Why things are the way they are: Guiding Principles & Invariants and the architecture decisions.
- Crate docs: the API reference.