Memory and sessions

Agents that “forget” every HTTP request feel broken. Agents that paste the entire company wiki into every prompt feel slow and leaky. Shirube splits this chat from lasting knowledge.

See also Concepts and Graph memory.

Sessions — this conversation

What: Ordered user/assistant messages for one thread.

Use for: Chat UIs, Slack threads, “as I said two messages ago”.

import { Agent, FileSession, getSession } from "shirube-ai";

const agent = Agent.builder()
  .name("support")
  .instructions("You remember this thread only via session history.")
  .apiKey(key)
  .session(new FileSession("chat_9", "./.shirube/chat_9.json"))
  .build();

await agent.run("My name is Ada.");
await agent.run("What is my name?");

await agent.run("Hello", { sessionId: "chat_9" });

FileSession writes JSON to disk (survives process restart). InMemorySession / getSession(id) is process-local — fine for tests and a single Node process.

Implement Session (id, getHistory, append) for Redis or your DB.

Long-term memory — this user over time

What: A MemoryProvider that searches relevant notes before the model call and adds the new turn afterward.

Use for: “Ada prefers email”, “they already tried a factory reset”, not for the last three chat bubbles (that is the session).

.memory({ provider: "in-memory" })
.memory({ provider: "mem0", apiKey: process.env.MEM0_API_KEY })

await agent.run("I prefer sci-fi movies.", { userId: "ada" });
await agent.run("What genre should I recommend?", { userId: "ada" });

Always pass userId (or your tenant id) so users do not share memories.

Custom backend:

.memory({
  provider: "custom",
  instance: {
    async search({ query, userId, limit }) {
      return [];
    },
    async add({ messages, userId, agentId, runId }) {},
  },
})

Hits are injected as a Relevant memory: block in the system prompt. Writes emit memory.updated and a memory.add trace.

What not to do

• Do not put secrets in memory. Guardrails redact PII on the way in/out, but memory is still a database.
• Do not use only memory if you need relationships (Ada WORKS_ON Shirube). Use the graph.