Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
oboete provides a lightweight, single-binary memory system for coding agents. It captures interactions between developers and AI agents, processes these interactions into structured knowledge, and serves that knowledge back to agents in future sessions.
The system uses a two-tier storage model. The "Raw" tier (raw.db) stores immutable hook events and an operation log. The "Knowledge" tier (knowledge.db) stores derived data such as claims, digests, and manifests. Consumers process the raw events in sequence to update the knowledge tier.
Sources: src/main.rs:1-10, src/consumer.rs:1-5
Component Architecture
The system consists of several primary components that handle data lifecycle from capture to retrieval.
Hook Capture System
The capture system receives JSON payloads from agent hooks (e.g., SessionStart, UserPromptSubmit). It cleans text by removing <private> blocks and replacing binary data with markers. It then appends these as events to raw.db.
Sources: src/capture.rs:80-150, src/main.rs:60-70
Worker and Consumers
The Worker runs Design B consumers over raw.db. Each consumer (Claims, Manifest, FTS) maintains a checkpoint in knowledge.db. Consumers read new records in batches and update their respective derived views.
Sources: src/consumer.rs:1-10, src/consumer/manifest.rs:90-110
Curation Phase
The curation phase processes events into "Windows" of text. It sends these windows to a Curator (an LLM provider) to extract claims. The system applies code gates to validate the status and speaker of these claims before storing them.
Sources: src/curate.rs:460-500, src/gates.rs:65-100
Access Interfaces
oboete serves memory through three primary interfaces:
- MCP Server: Provides
search,get, andtimelinetools over stdio for agents. - Injection: Injects context (manifests) into new agent sessions.
- Web Viewer: A browser-based UI for browsing sessions and stats.
Sources: src/mcp.rs:1-15, src/main.rs:115-130, src/view.rs:1-15
Data Flow
The following diagram illustrates how data flows from an agent hook through processing to eventual retrieval.
This diagram shows the path from initial capture to processed knowledge and retrieval.
Sources: src/main.rs:1-40, src/capture.rs:126-150, src/curate.rs:460-480, src/consumer/manifest.rs:125-150
Hook System Integration
oboete wires itself into multiple AI agents by modifying their configuration files. It supports the following agents:
| Agent | Wiring Method | Primary Hook Points |
|---|---|---|
| Claude Code | settings.json | SessionStart, UserPromptSubmit, Stop |
| Codex | hooks.json & config.toml | SessionStart, UserPromptSubmit, Stop |
| Grok | ~/.grok/hooks/*.json | SessionStart, PreToolUse, Stop |
| Cursor | hooks.json & mcp.json | sessionStart, beforeSubmitPrompt |
| OpenCode | plugins/oboete.js | JavaScript Plugin System |
Sources: src/setup.rs:15-40, src/setup.rs:430-450
Storage Schema and Logic
Raw Tier (raw.db)
Stores the truth of what happened. It is used for auditing and as the source for all derived data.
- Events: Serialized agent interactions.
- Ops: Curation outcomes, claims, and digests.
- Tombstones: Marks records as removed or masked for consumers.
Sources: src/raw.rs, src/consumer/manifest.rs:130-145
Knowledge Tier (knowledge.db)
Stores structured data for fast retrieval.
- Manifests: Pre-built context for each (repo, branch, device).
- Claims: Validated facts (decisions, preferences, open items).
- FTS: Full-text search index for observations and prompts.
Sources: src/consumer/manifest.rs:45-75, src/mcp.rs:110-130
Claim Validation (Code Gates)
When a curator proposes claims, they must pass through code gates. These gates ensure the user actually agreed to the decision and that tool output did not "taint" the claim.
The Gates process ensures that claims marked as 'decided' reflect actual user intent.
Sources: src/gates.rs:65-100, src/gates.rs:200-220
Conclusion
oboete's architecture separates the high-volume capture of raw logs from the computationally expensive curation of knowledge. By utilizing a local SQLite-based processing pipeline, it provides agents with persistent, searchable memory while maintaining user privacy through local redaction and <private> block stripping.
Sources: src/main.rs:1-10, src/capture.rs:1-15