Concepts: what lives where

Mixing “this chat”, “this customer”, and “this agent’s personality” into one prompt is how agents get expensive and wrong. Shirube keeps five layers separate.

Agent configuration

Built once with Agent.builder() / Agent.create(). Frozen after .build().

Includes: name, instructions, tools, model, guardrails, MCP, handoffs, output schema.

Current run

One call to agent.run() or runStream(). Has a runId, message list, turn counter, token usage, handoff hop list.

Use for: debugging a single request. Timeouts and maxTurns apply here so a bad tool loop cannot run forever.

Session (short-term conversation)

sessionId on run(), or .session(new FileSession(...)) / InMemorySession.

The next user message sees prior user/assistant turns in that session.

Use for: a chat window, a Slack thread, a ticket’s back-and-forth. Not for “who is Ada’s employer” six months later.

Long-term memory

MemoryProvider: search before the model call, add after. Built-in: in-memory token overlap, optional Mem0. userId scopes records.

Use for: preferences and facts as prose (“prefers email over phone”). Good for retrieval; weak for “Ada WORKS_ON Shirube” as a first-class edge.

Knowledge graph

Property graph (typed nodes and edges). Three background workers update it. The agent reads a subgraph into the system prompt; writes are queued and must not block the HTTP response.

Use for: relationships you will query later — people, projects, tools, PREFERS, USES. See Graph memory.

How context is assembled

User message
    │
    ├─ session history (this chat)
    ├─ memory.search (similar notes)
    └─ graph.contextFor (entities + edges)
         │
         ▼
       model + tools
         │
    ├─ session.append
    ├─ memory.add
    └─ graph.ingest  →  extract / relate / maintain (async)