Single-Binary Design
Relevant source files
The following files were used as context for generating this wiki page:
Oboete operates as a lightweight, single-binary memory system for coding agents. This architecture consolidates all functionality—configuration, data capture, processing, and retrieval—into a single executable written in Rust. The design eliminates external service dependencies by utilizing local SQLite databases for persistent storage.
Sources: CLAUDE.md:3, src/db.rs:1
Architectural Overview
The Oboete binary serves multiple roles depending on the command-line arguments provided. It integrates directly with developer workflows by acting as a hook processor, a background worker, and an MCP (Model Context Protocol) server.
Core Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| Hook Processor | Captures events from agents (Claude, Codex, etc.) and writes them to the raw store. | src/setup.rs, src/capture.rs |
| MCP Server | Provides an interface for agents to search and retrieve memories during sessions. | src/mcp.rs |
| Worker/Curator | Processes raw events into structured claims using LLM providers. | src/curate.rs, src/gates.rs |
| Storage Engine | Manages multiple SQLite databases for raw events, knowledge, and settings. | src/db.rs, src/knowledge.rs |
System Architecture Flow
The following diagram illustrates how the single binary interacts with external agents and internal storage.
The diagram shows the Oboete binary acting as the central hub between agents, LLM providers, and various SQLite stores.
Sources: src/mcp.rs:163-176, src/setup.rs:172-180, src/db.rs:107-120
Hook-Based Integration
Oboete integrates with various coding agents by registering itself as a command-line hook. The setup command identifies the absolute path of the current binary and writes it into agent-specific configuration files.
Self-Referential Execution
The binary uses its own canonicalized executable path to ensure that hooks remain functional even when the agent runs from different working directories. If you provide a custom home directory using --home, the binary includes this flag in all registered hook commands.
// src/setup.rs:172-180
struct HookCommand {
exe: String,
home: Option<String>,
}
impl HookCommand {
fn current(home: &Path) -> Result<Self> {
let exe = std::env::current_exe()?.canonicalize()?;
// Hooks run from the agent's working directory: a custom home is stored absolute.
// ...
Ok(Self {
exe: exe.to_string_lossy().into_owned(),
home,
})
}
}
Sources: src/setup.rs:172-195
Supported Agents
The system supports several agents, including claude, codex, grok, agy, opencode, pi, and cursor. For each agent, the binary manages JSON or TOML configuration files to insert event listeners for lifecycle events like SessionStart and Stop.
Sources: src/setup.rs:12-65
Embedded MCP Server
The binary includes a complete implementation of the Model Context Protocol (MCP). When you run the binary with the mcp command, it starts a server over Stdio. This allows agents to call memory-related tools directly.
Provided Tools
The server exposes three primary tools:
search: Finds observations, summaries, and prompts using trigram-based search.get: Retrieves the full text of a specific document by its ID.timeline: Lists earlier coding sessions and their summaries.
Sources: src/mcp.rs:95-156
Server Lifecycle
Before starting the Stdio server, the binary performs a rekey operation. If a repository has gained a Git origin since the last run, the binary updates all associated records to use the new repository key.
The sequence shows the internal initialization and tool handling within the single process.
Sources: src/mcp.rs:163-176, src/mcp.rs:179-187
Data Sovereignty and Persistence
The single-binary design centralizes data management within the user's home directory (usually ~/.oboete). All data remains local to the machine, gated by the binary's internal redaction and egress rules.
Database Architecture
Oboete utilizes several distinct SQLite files to segregate data based on its lifecycle and processing state:
raw.db: Holds the append-only log of raw agent interactions and hook payloads.knowledge.db: Contains the processed, indexed, and curated claims and summaries.oboete.db: Stores session metadata, provider call history, and cross-device document UIDs.providers.db: Tracks provider quotas, budgets, and pending curation windows.
Sources: src/db.rs:1-105, src/curate.rs:723-745
Automated Migrations
The binary manages its own schema evolution. Upon opening a database, the system checks for existing tables and columns. It applies necessary ALTER TABLE statements and builds virtual FTS5 tables automatically if they are missing.
Sources: src/db.rs:122-140, src/db.rs:327-347
Summary
The Oboete single-binary design provides a portable and self-contained memory system for coding agents. By handling its own setup, hook management, storage, and tool serving, the binary ensures a low-friction deployment for developers while maintaining full control over the captured data.