Read tools

Read tools query the intelligence that accumulates as agents write events. Results are ranked by confidence, recency and relevance — not raw dumps.

All read responses are cached for 30 seconds to deduplicate concurrent identical queries within the same session.

context

The flagship tool. Returns ranked institutional knowledge for a topic.

context(topic, repo?, file_patterns?, limit?, min_confidence?)

Param	Type	Required	Description
topic	string	yes	What you need context on (e.g., “auth”, “billing webhook”)
repo	string	no	Filter to a specific repository
file_patterns	string	no	Comma-separated globs to boost matching (e.g., src/auth/**)
limit	number	no	Max results (default 10)
min_confidence	number	no	Minimum confidence threshold (default 0.3)

Response: Ranked learnings with confidence scores, evidence counts, suggested actions, and matching strategy metadata.

How it works: context tries a three-stage fallback chain:

1. Hybrid search — semantic embeddings + BM25 lexical matching, fused via reciprocal rank fusion (RRF)
2. Legacy context — tag and summary token matching
3. Raw events — recent events matching the topic

This means context always returns something useful, even before consolidation has run.

When to use: At the start of any task. Before writing code, before making architectural decisions, before debugging — ask what the organization already knows.

context("JWT refresh race condition")
→ 3 learnings (confidence 0.72–0.91), 2 from last week's auth sprint
→ "Team discovered a race condition when multiple tabs refresh simultaneously.
   Fix: mutex on refresh endpoint. Confidence: 0.91 (4 sessions confirm)"

learnings

Browse institutional knowledge with rich filtering. Unlike context (which ranks by relevance to a topic), learnings supports structured filtering by category, status, and confidence range.

learnings(category?, status?, min_confidence?, max_confidence?, tags?, limit?)

Param	Type	Required	Description
category	string	no	architecture, bug_pattern, convention, domain_knowledge, pattern, decision
status	string	no	active, reinforced, contradicted, obsolete
min_confidence	number	no	Lower bound (0.0–1.0)
max_confidence	number	no	Upper bound (0.0–1.0)
tags	string	no	Comma-separated tag filter
limit	number	no	Max results (default 50)

When to use: When you want to explore what the organization knows about a specific category (e.g., “show me all high-confidence architecture learnings”) rather than asking about a specific topic.

decisions

Query the organizational decision log — every architectural choice, library selection, and approach decision recorded via the decision write tool and distilled by consolidation.

decisions(module?, timeframe?, limit?)

Param	Type	Required	Description
module	string	no	Filter by module/area
timeframe	string	no	7d, 30d, or ISO timestamp
limit	number	no	Max results (default 50)

When to use: Before making a decision that might already have been made. “Has anyone decided on an approach for X?” prevents re-litigating settled questions.

patterns

Surface recurring behaviors across sessions and teams. Patterns are high-confidence learnings that have been reinforced by multiple independent sources.

patterns(category?, limit?)

Param	Type	Required	Description
category	string	no	Filter by pattern category
limit	number	no	Max results (default 50)

When to use: To understand systemic issues. “What keeps breaking?” or “Where does the team keep running into friction?“

semantic_search

Free-text vector search over all learnings. Uses pgvector embeddings with cosine similarity, falling back to hybrid search if the embedding provider is unavailable.

semantic_search(query, limit?, min_similarity?)

Param	Type	Required	Description
query	string	yes	Natural language search query
limit	number	no	Max results (default 10)
min_similarity	number	no	Cosine similarity threshold (default 0.4)

When to use: When you’re looking for something specific but don’t know the exact tags or categories. Semantic search finds conceptually related learnings even if the exact words differ.

semantic_search("webhook delivery failures under load")
→ Finds learnings about Stripe webhook handler, even if they used
  different terminology like "event processing timeout"

suggest

Rank backlog items by relevance to accumulated organizational intelligence. Returns evidence-ranked product backlog items (PBIs) that consolidation has generated from friction patterns.

suggest(tags?, limit?)

Param	Type	Required	Description
tags	string	no	Filter by area tags
limit	number	no	Max results

When to use: When planning work. “What should we work on next, based on what agents have actually struggled with?“

backlog

Browse the auto-generated product backlog — PBIs created by consolidation from high-confidence friction patterns.

backlog(status?, priority?, tags?, limit?)

Param	Type	Required	Description
status	string	no	draft, approved, assigned, in_progress, done, rejected
priority	string	no	CRITICAL, HIGH, MEDIUM, LOW
tags	string	no	Comma-separated tag filter
limit	number	no	Max results

When to use: To see what Oka recommends fixing, ranked by evidence from actual agent friction — not gut feel.

priorities

Get approved high-confidence PBIs — the subset of the backlog that has been validated and is ready for work.

priorities(limit?)

When to use: Quick check: “What’s the most important thing to work on right now?“

consolidate

Trigger a consolidation run manually. Consolidation normally runs automatically on a schedule, but you can trigger it on demand.

consolidate(repo?, max_events?)

Param	Type	Required	Description
repo	string	no	Scope to a specific repository
max_events	number	no	Max events to process

When to use: After a burst of activity (e.g., end of a sprint) when you want learnings distilled immediately rather than waiting for the next scheduled run.

entities

Query the typed ontology — named entities (people, systems, patterns, decisions, conventions) extracted from reasoning events, with graph expansion.

entities(entity_type?, query?, limit?, depth?)

Param	Type	Required	Description
entity_type	string	no	Filter by type (person, system, pattern, convention, decision, etc.)
query	string	no	Full-text search within entities
limit	number	no	Max results (default 20)
depth	number	no	Graph expansion depth for relationships

When to use: When you want to understand relationships — “What systems depend on auth?” or “What conventions apply to this area?”

Best practices

1. Start every task with context. It takes seconds and often saves hours. Even if it returns nothing, you’ve confirmed this is new ground.

2. Use feedback after context. When context returns learnings, tell Oka which ones were useful. This trains the ranking model and makes future results better for everyone.

3. Check decisions before making one. The most expensive decision is one that was already made and forgotten — it wastes time and creates contradictions.

4. Review patterns periodically. Patterns reveal systemic friction that no single agent session can see. They’re the organizational intelligence that justifies Oka’s existence.