Intents

A fact tells you what happened. An intent tells you why it mattered.

Breeth's intent layer is the optional, deeper annotation pass on top of every edge. When you set extract_intent: true on a write, Breeth attaches:

• edge_kind — action, state, preference, decision, or observation.
• cognitive_pattern — a short label naming the reasoning style (e.g. trait-based selection, cost-vs-quality tradeoff).
• why_connected — one-sentence reasoning the agent can quote.
• director_vision — what the actor was trying to achieve, expressed as a goal.

Why it matters

A vector store keeps facts. Breeth keeps the structure those facts came from — so when your agent retrieves "Sridhar picked Rust over Go", it doesn't just see the choice; it sees that the choice was a cost-vs-quality tradeoff favoring tail latency. That's what lets the agent reason like the user, not just recall what the user said.

Opt-in per call

Intent extraction is always client-opt-in. We never run it on writes that don't pass extract_intent: true. Two reasons:

1. It costs an intents credit on your tier.
2. Not every write deserves it. Logging "the build passed" doesn't need intent. A decision to advance a candidate does.

Fair billing

You're only charged for intent when the annotation actually attached to at least one edge. If Breeth extracted entities but no edges from your content (so there's nothing to annotate), no intents credit is deducted.

Example

Write:

{
  "content": "After 12 interviews I chose Nandini over Mira for the staff role. Nandini's kabaddi background showed grit; weighting team-fit > pure tech depth for this round.",
  "extract_intent": true
}

Resulting edge in the graph:

Nandini Kulkarni -[chose over]-> Mira Vasquez
fact: "Nandini was advanced to the final round over Mira based on grit and team-fit weighting"
intent_meta:
  edge_kind: "decision"
  cognitive_pattern: "trait-based selection"
  why_connected: "The director chose Nandini over Mira based on observed grit and tooling preferences."
  director_vision: "Hire someone whose traits align with team-fit over pure technical depth."

That's what your agent reads back during retrieval. Not just "Nandini was hired" — but the reasoning that led there.

What it's good for

• Personalization — your agent learns the user's decision-making style, not just their decisions.
• Coaching — surface cognitive patterns across many decisions to spot biases or trends.
• Continuity — six months later, your agent still knows why a hire was made, not just that one happened.

What it isn't

• It's not a free LLM call. It costs an intents credit.
• It's not magic. Garbage content in → garbage intent out. Write prose that contains a decision or preference.
• It's not for system logs. Use extract_intent: false (the default) for operational writes.