Home
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 developer interactions with AI agents, processes them through a summarizer chain, and injects relevant history back into new agent sessions.
Sources: CLAUDE.md:1-5, src/main.rs:3-6
System Overview
Oboete operates as a background service and CLI tool that manages two distinct SQLite databases: raw.db for immutable hook events and knowledge.db for derived memory documents like claims and manifests. The system uses a "fail-open" strategy for agent hooks to ensure Oboete issues never interrupt the developer's primary workflow.
Sources: src/main.rs:188-190, src/main.rs:219-221, src/capture.rs:1-8
Core Components
| Component | Description |
|---|---|
| Hook | Receives events from supported agents (Claude, Codex, etc.) and appends them to raw.db. |
| Worker | Background process that drains raw.db, runs the curation phase, and updates knowledge.db. |
| Curator | Uses an AI provider chain to extract claims, decisions, and bugfixes from recorded session windows. |
| MCP Server | Provides an interface for agents to search and retrieve full text from memory during active sessions. |
| Manifest | Built-in logic to inject risky git state and historical context into new agent sessions. |
Sources: src/main.rs:194-206, src/curate.rs:1-12, src/mcp.rs:1-6, src/manifest.rs:1-5
Data Flow Architecture
The Oboete architecture follows a unidirectional data pipeline where raw interaction data is captured, analyzed by LLMs, and transformed into structured knowledge.
Oboete captures data from agent hooks and stores it in raw.db. The worker process reads this data in batches, partitions it into windows, and sends it to the AI Curator. Validated claims are then committed to knowledge.db.
Sources: src/main.rs:194-210, src/curate.rs:596-610, src/capture.rs:1-8
Curation System
The curation system partitions records into windows of approximately 5,000 estimated tokens. It uses an AI provider chain to identify "claims" worth remembering, categorized into specific kinds like decisions, bugfixes, and features.
Sources: src/curate.rs:20-22, src/curate.rs:434-441
Claim Categories
| Kind | Description |
|---|---|
| Decision | Explicit technical or architectural choices made by the developer. |
| Bugfix | Documented solutions to identified issues or panics. |
| Feature | New capabilities or functional requirements added to the project. |
| Discovery | Relevant technical facts or external API details learned during a session. |
| Preference | Developer-specific coding styles or operational requirements. |
Sources: src/curate.rs:434-441, src/curate.rs:661-667
Curation Sequence
The Worker selects records based on the curation checkpoint in raw.db. The AI Curator processes the text and returns a JSON object. Oboete applies "Code Gates" to verify that quotes exist verbatim in the source text and that the speaker is correctly identified before storing the knowledge.
Sources: src/curate.rs:596-610, src/gates.rs:105-115
Provider Chain and Resilience
Oboete manages multiple LLM providers (e.g., OpenAI, Claude CLI, Codex CLI) in a fallback chain. The system tracks daily budgets and applies cooldown periods to providers that return errors or trigger rate limits.
Sources: src/provider.rs:1-12, src/provider.rs:188-200
Provider Error Handling
| Scenario | System Response |
|---|---|
| Rate Limit (429) | Waits up to 60s if reset is near, otherwise applies a backoff cooldown. |
| Outage (5xx) | Immediately switches to the next provider and applies a 600s cooldown. |
| Budget Spent | Skips the provider until the daily or monthly budget resets. |
| Isolation Failure | Curator CLIs (like Claude) are skipped if they are not proven isolated. |
Sources: src/provider.rs:16-25, src/provider.rs:340-350, src/provider.rs:370-380
Setup and Integration
The oboete setup command wires agent hooks to the binary. It supports several agents, including claude, codex, grok, agy, opencode, pi, and cursor. Setup typically modifies agent configuration files (like settings.json for Claude) to run Oboete hooks on specific events.
Sources: src/setup.rs:18-20, src/setup.rs:45-55
Hook Events
Agents notify Oboete during the following lifecycle events:
- SessionStart: Triggers context injection and manifest building.
- UserPromptSubmit: Captures the developer's input.
- PostToolUse: Records tool inputs and outputs (like shell results).
- Stop: Captures the assistant's final response for the turn.
- SessionEnd: Finalizes session processing.
Sources: src/setup.rs:25-33, src/setup.rs:219-230
Oboete uses these hooks to maintain a continuous record of activity while providing relevant memory to the agent in real-time.
Summary: Oboete provides a robust, fail-safe memory architecture for coding agents by separating raw data capture from AI-driven curation and ensuring resilience through a sophisticated provider fallback system.
Sources: src/main.rs:1-10, src/provider.rs:1-12