Project Process & Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• src/curate.rs
• src/setup.rs
• src/provider.rs
• src/manifest.rs
• src/capture.rs

The Oboete project provides a lightweight single-binary memory system for coding agents. It manages the lifecycle of agent interactions by capturing hooks, curating records through AI providers, and maintaining a knowledge base of decisions and facts. These guidelines define the development workflow, implementation standards, and operational constraints for the project.

Sources: CLAUDE.md:1-5, src/capture.rs:1-8

Development Workflow

Development follows a strict review and merge process to ensure reliability and alignment with the architectural specification.

Pull Request and Review Process

The project uses a specific review lane for each Pull Request (PR):

1. Automated Review: The Codex GitHub app reviews PRs upon opening and after subsequent pushes.
2. Verification: You must verify that the review summary comment names the new head SHA after every push. If it does not, you must comment @codex review.
3. Iteration: You must address every review round by either adopting the finding or replying with a rationale for rejection.
4. Merging: You merge the PR when the automated review on the final head SHA produces no new findings.
5. Design Docs: Design-doc PRs stop when two consecutive rounds yield only mechanism findings with no changes to owner decisions. Remaining findings move to issues as acceptance tests.

Sources: CLAUDE.md:21-30

Continuous Integration (CI)

The project utilizes specific tools for code quality and testing:

• Formatting: cargo fmt --check
• Linting: cargo clippy
• Testing: cargo test
• Security: CodeQL is the primary security bot. GitLeaks or GitGuardian hits on redaction test fixtures are treated as test credentials.

Sources: CLAUDE.md:25-28

Implementation Standards

Oboete relies on a "Measure, don't assume" philosophy for performance and reliability.

Core and Extensions

Claude Code writes the core system directly. Delegation to Codex or Grok occurs only for independent, parallelizable components like agent adapters or donor-module ports.

Sources: CLAUDE.md:31-33

Performance Measurement

You must use the oboete replay command to verify system behavior:

oboete replay <fixture> --home <tmp>

This command measures hook latency, peak memory usage (VmHWM), and provider outcomes. The standard fixture for testing is events-1000.jsonl.

Sources: CLAUDE.md:37-38

Security and Redaction

Oboete enforces strict security regarding API keys and sensitive data:

• API Keys: Keys reside in ~/<NAME>_KEY.md. You must never print them or pass them to subprocess environments.
• Redaction: Every stored string passes an outbound gate. Rules apply to text during capture and on the way out to agents.
• Isolation: Curator CLIs run in a private scratch directory with a restricted environment.

Sources: CLAUDE.md:34-36, src/capture.rs:175-180, src/provider.rs:945-950

Curation Process & Windowing

Curation transforms raw agent events into structured knowledge. This process is bounded by token budgets and time-based triggers.

Window Cutting Logic

A curation window covers a specific range of records. The system cuts windows based on:

1. Token Budget: Currently estimated at 5,000 tokens.
2. Turn Boundaries: Windows attempt to end before the last turn boundary (typed prompt).
3. Tool Calls: If no turn boundary exists, windows end after the last tool call.
4. Record Limits: A window covers at most 2,000 records.

Sources: src/curate.rs:25-35, src/curate.rs:218-225

Curation Flow Diagram

The following diagram illustrates how raw events move through the curation phase to become claims.

This diagram shows the decision logic for processing a device's next window of records.

Sources: src/curate.rs:480-530, src/curate.rs:600-650

AI Provider Guidelines

Providers are organized into a fallback chain to ensure high availability and cost control.

Provider Chain Behavior

The chain iterates through configured providers in order. A provider is skipped if:

• It is cooling down after a failure.
• Its daily or monthly budget is spent.
• The request exceeds its token ceiling.
• The owner has explicitly stopped it (oboete resume required).

Sources: src/provider.rs:135-160

Cooldown and Backoff

Providers implement different cooldown periods based on failure types:

Failure Type	Cooldown Duration	Backoff Logic
HTTP 429 (Rate Limit)	45s or Retry-After	Doubles up to 1 hour if no reset provided
Outage (5xx, Timeout)	10 minutes	None
Rejected API Key	10 minutes	Doubles up to 24 hours
Breaker (3 schema fails)	30 minutes	Resets on successful answer

Sources: src/provider.rs:20-40, src/provider.rs:205-230

Agent Integration (Setup)

The oboete setup <agent> command wires agent hooks to the Oboete binary.

Supported Agents

The system currently supports the following agents: claude, codex, grok, agy, opencode, pi, and cursor.

Sources: src/setup.rs:21

Hook Installation Process

1. Backup: The system creates a .oboete.bak file before the first modification of a developer-owned config.
2. Atomicity: Writes are atomic (temp file then rename) to prevent config truncation if an agent is running.
3. Idempotency: Setup only touches Oboete-specific entries and is safe to run multiple times.
4. Trust (Codex): For the Codex agent, setup writes trusted hashes into config.toml to allow hook execution.

Sources: src/setup.rs:2-10, src/setup.rs:460-480

Conclusion

These guidelines ensure that Oboete remains a reliable, secure, and predictable memory extension for coding agents. Developers must adhere to the automated review cycles, performance measurement standards, and strict redaction rules to maintain the integrity of the knowledge base. Project health is monitored via oboete doctor, which reports on the state of wiring, storage, and provider availability.

Sources: CLAUDE.md:21-25, src/setup.rs:1140-1160