How agustinvalencia/cuaderno works
Cuaderno is a local-first vault manager for the Research Logbook Method: Markdown and Typst notes are the source of truth, while SQLite is a rebuildable index. The main user workflow starts in the CLI or through an MCP client, invokes domain operations for capture, projects, actions, commitments, and orientation, then reads or updates vault files. The domain crate sits between both interfaces and the reusable core. Major supporting capabilities include templates, validation, search, and file watching. Relationships between crates follow the README; unsampled implementation details are represented only where documented.
Main entry points: mod.rs Vault API · index.rs SQLite index · store.rs Vault file access · transaction.rs Atomic updates
Components 22
User Interfaces
- CLI commands
crates/cdno-cli/src/commands - CLI entry
crates/cdno-cli/src/main.rs - MCP server
crates/cdno-mcp/src/server.rs - MCP operations
crates/cdno-mcp/src/operations.rs
Logbook Domain
- Vault API
crates/cdno-domain/src/vault/mod.rs - Projects and actions
crates/cdno-domain/src/vault/projects/actions.rs - Context queries
crates/cdno-domain/src/vault/context.rs - Commitments
crates/cdno-domain/src/vault/commitments.rs - Log and capture
crates/cdno-domain/src/vault/log.rs - Templates
crates/cdno-domain/src/vault/templating.rs - Note rules
crates/cdno-domain/src/lint.rs - Vault search
crates/cdno-domain/src/vault/search.rs
Vault Infrastructure
- Vault file access
crates/cdno-core/src/store.rs - Atomic updates
crates/cdno-core/src/transaction.rs - SQLite index
crates/cdno-core/src/index.rs - Note extraction
crates/cdno-core/src/extractors.rs - File watching
crates/cdno-core/src/watcher.rs
Note Formats
- Note types
crates/cdno-domain/src/note_type.rs - Structured metadata
crates/cdno-domain/src/frontmatter/mod.rs - Typst support
crates/cdno-core/src/typst/mod.rs
Other components
- Vault user
- MCP client
Connections 23
- Vault user → CLI entry: runs
- CLI entry → CLI commands: dispatches
- CLI commands → Vault API: invokes domain
- MCP client → MCP server: sends MCP tools
- MCP server → MCP operations: dispatches tools
crates/cdno-mcp/src/server.rs - MCP operations → Vault API: invokes domain
- Vault API → Vault file access: uses store
crates/cdno-domain/src/vault/mod.rs - Vault API → SQLite index: uses index
crates/cdno-domain/src/vault/mod.rs - Vault API → Projects and actions: exposes operations
crates/cdno-domain/src/vault/projects/actions.rs - Vault API → Context queries: exposes queries
crates/cdno-domain/src/vault/mod.rs - Vault API → Commitments: exposes queries
crates/cdno-domain/src/vault/mod.rs - Vault API → Log and capture: exposes operations
crates/cdno-domain/src/vault/mod.rs - Vault API → Templates: exposes operations
crates/cdno-domain/src/vault/templating.rs - Vault API → Note rules: exposes rules
- Vault API → Vault search: exposes queries
crates/cdno-domain/src/vault/mod.rs - Projects and actions → Atomic updates: stages updates
- Vault file access → Atomic updates: used by
crates/cdno-core/src/transaction.rs - Atomic updates → SQLite index: updates index
crates/cdno-core/src/transaction.rs - SQLite index → Note extraction: uses extraction
crates/cdno-core/src/index.rs - File watching → SQLite index: keeps current
- Templates → Note types: uses type rules
crates/cdno-domain/src/vault/templating.rs - Note rules → Structured metadata: validates metadata
- Vault file access → Typst support: handles notes