Memory

import { Agent, openai, InMemoryStorage } from "@agentium/core";

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  memory: {
    storage: new InMemoryStorage(),
  },
});

// First conversation
await agent.run("My name is Alex", { sessionId: "s1", userId: "u1" });

// Later — the agent remembers
const result = await agent.run("What's my name?", { sessionId: "s1", userId: "u1" });
// "Your name is Alex."

        ┌──────────────────────────────────────────────────┐
        │                     Agent                          │
        │   beforeRun → buildContext() → LLM ⇄ tools        │
        │   afterRun  → appendMessages + background extract  │
        └────────────────────────┬───────────────────────────┘
                                 │
                                 ▼
        ┌──────────────────────────────────────────────────┐
        │                 MemoryManager                      │
        │  buildContext() · appendMessages() · afterRun()    │
        │  recall() · remember() · forget() · curator        │
        └───┬──────┬──────┬──────┬──────┬──────┬──────┬─────┘
            ▼      ▼      ▼      ▼      ▼      ▼      ▼
        Sessions Summary Facts Profile Entity Decision …
            │      │      │      │      │      │
            ▼      ▼      ▼      ▼      ▼      ▼
        ┌──────────────────────────────────────────────────┐
        │              StorageDriver interface               │
        │     MongoDB · Postgres · Redis · SQLite · …         │
        └──────────────────────────────────────────────────┘

        Learnings ──► VectorStore (Qdrant · Pinecone · …)
        Graph     ──► GraphStore  (Neo4j · InMemory)

// Conceptually, every run looks like this:
const ctx = await memory.buildContext(sessionId, userId, input, agentName);  // phase 1
const output = await llmLoop.run([systemPrompt + ctx, ...history, input]);
memory.afterRun(sessionId, userId, recentTurns, extractModel, agentName);     // phase 2 (async)

memory: {
  storage: new SqliteStorage("app.db"),
  maxMessages: 30,    // Keep last 30 messages (15 turns)
}

memory: {
  storage,
  maxTokens: 8000,   // Keep history within ~8K tokens
}

// Default behavior (summaries ON)
memory: { storage }

// Smaller footprint — fewer, shorter summaries (cheaper)
memory: {
  storage,
  summaries: { maxCount: 5, maxTokens: 1000 },
}

// Disable summaries entirely
memory: {
  storage,
  summaries: false,
}

memory: {
  storage,
  userFacts: true,            // Enable with defaults (max 100 facts)
}

// Lean setup — keep only the most important 30 facts
memory: {
  storage,
  userFacts: { maxFacts: 30 },
}

memory: {
  storage,
  userProfile: true,  // Track only the built-ins: name, role, timezone, language
}

// Add product-specific fields
memory: {
  storage,
  userProfile: { customFields: ["company", "department", "plan"] },
}

// Default — one shared entity space
memory: { storage, entities: true }

// Per-team workspace
memory: { storage, entities: { namespace: "acme/engineering" } }

memory: {
  storage,
  decisions: true,                      // remind the agent of its last 5 decisions
}

// High-continuity agent — remember more recent rulings
memory: {
  storage,
  decisions: { maxContextDecisions: 10 },
}

import { InMemoryVectorStore, OpenAIEmbedding } from "@agentium/core";

memory: {
  storage,
  learnings: {
    vectorStore: new InMemoryVectorStore(new OpenAIEmbedding()),
    topK: 5,   // pull the 5 most relevant insights each run
  },
}

import { InMemoryGraphStore } from "@agentium/core";

memory: {
  storage,
  graph: {
    store: new InMemoryGraphStore(),
    maxContextNodes: 15,   // surface up to 15 connected entities
  },
}

memory: {
  storage,
  procedures: true,                    // keep up to 50 playbooks
}

// Broad ops agent with many distinct workflows
memory: {
  storage,
  procedures: { maxProcedures: 200 },
}

global       ← rarely used; built-in defaults, visible to everyone
  ↑
tenant       ← organization-wide (requires memory.tenantId)
  ↑
agent        ← workflow / role knowledge, shared across all users of this agent
  ↑
user         ← personal (default)

// The agent's save_learning tool call:
save_learning({
  title: "Vendor X line-item drift",
  content: "Vendor X invoices consistently show $0.10–$0.50 drift per line.",
  context: "invoice reconciliation",
  scope: "agent",   // ← share with everyone using the invoice-recon agent
})

const agent = new Agent({
  name: "invoice-recon",
  model: openai("gpt-4o"),
  memory: {
    storage,
    learnings: { vectorStore },
    tenantId: "acme-corp",   // required for tenant-scoped reads
  },
});

const learnings = agent.memory!.getLearnedKnowledge()!;

// Org-wide policy — every user/agent in acme-corp sees it
await learnings.saveLearning({
  title: "Refund approval policy",
  content: "Refunds above $500 require VP approval.",
  context: "refunds",
  tags: ["policy"],
  namespace: "default",
  scope: "tenant",
  tenantId: "acme-corp",
});

// A union read returns user + agent + tenant + global learnings
const results = await learnings.searchLearnings("refund policy", {
  userId: "alice",
  agentName: "invoice-recon",
  tenantId: "acme-corp",
  topK: 5,
});

memory: {
  storage,
  userFacts: true,
  entities: true,
  summaries: true,
  contextBudget: {
    maxTokens: 4000,            // cap total memory at ~4K tokens
    priorities: {
      summaries: 3,             // gets the largest share
      userFacts: 2,
      entities: 1,              // trimmed first if space runs out
    },
  },
}

memory: {
  storage,
  summaries: true,
  userFacts: true,
  entities: true,
  model: openai("gpt-4o-mini"), // 10x cheaper for background work
}

import {
  Agent, openai, MongoDBStorage,
  InMemoryVectorStore, OpenAIEmbedding, InMemoryGraphStore,
} from "@agentium/core";

const storage = new MongoDBStorage("mongodb://localhost:27017/myapp");
await storage.initialize();

const agent = new Agent({
  name: "full-memory-agent",
  model: openai("gpt-4o"),
  memory: {
    storage,
    maxMessages: 30,
    summaries: { maxCount: 10, maxTokens: 2000 },
    userFacts: { maxFacts: 100 },
    userProfile: { customFields: ["company", "plan"] },
    entities: { namespace: "global" },
    decisions: { maxContextDecisions: 5 },
    learnings: {
      vectorStore: new InMemoryVectorStore(new OpenAIEmbedding()),
      topK: 3,
    },
    graph: {
      store: new InMemoryGraphStore(),
      maxContextNodes: 10,
    },
    procedures: { maxProcedures: 50 },
    contextBudget: {
      maxTokens: 5000,
      priorities: { summaries: 3, userFacts: 2, entities: 1 },
    },
    model: openai("gpt-4o-mini"),   // cheap model for background extraction
    timezone: "Asia/Kolkata",       // anchor date-relative extraction
    tenantId: "acme-corp",          // enable tenant-scoped learnings/procedures
    // eventBus is auto-injected from the Agent — no need to set it here
  },
});

// Surface silent extraction failures
agent.eventBus.on("memory.error", ({ store, error, agentName }) => {
  console.error(`[${agentName}] ${store} extraction failed:`, error.message);
  // forward to Sentry / Datadog / Langfuse
});

// Track how big the injected memory context is per run
agent.eventBus.on("memory.context.built", ({ totalTokens, sections }) => {
  metrics.histogram("memory_context_tokens", totalTokens);
});

// React to fact mutations
agent.eventBus.on("memory.fact.added", ({ userId, fact, source }) => {
  console.log(`[${userId}] learned (${source}): ${fact}`);
});

import { Agent, openai, MongoDBStorage, InMemoryVectorStore, OpenAIEmbedding } from "@agentium/core";

function agentForTenant(tenantId: string) {
  return new Agent({
    name: "support",
    model: openai("gpt-4o"),
    memory: {
      storage: new MongoDBStorage(`mongodb://localhost/acme`),
      userFacts: true,
      learnings: { vectorStore: new InMemoryVectorStore(new OpenAIEmbedding()) },
      tenantId,                       // scopes tenant-level learnings
      timezone: "America/New_York",
      model: openai("gpt-4o-mini"),
    },
  });
}

const acme = agentForTenant("acme-corp");
const meridian = agentForTenant("meridian-llc");

// Alice's personal facts are private to Alice within acme-corp
await acme.run("I prefer email over phone", { userId: "alice", sessionId: "s1" });

// A tenant-wide policy saved once, visible to every acme-corp user/agent
await acme.memory!.getLearnedKnowledge()!.saveLearning({
  title: "Escalation policy",
  content: "Tier-2 issues escalate to a human after 2 failed attempts.",
  context: "support escalation",
  tags: ["policy"],
  namespace: "default",
  scope: "tenant",
  tenantId: "acme-corp",
});

// meridian-llc users never see acme-corp's policy or Alice's facts
await meridian.run("How do escalations work?", { userId: "bob", sessionId: "s2" });

const mm = agent.memory!;
const ctx = await mm.buildContext(
  "session-abc",        // sessionId
  "user-42",            // userId
  "what's my order?",   // currentInput (drives relevance ranking)
  "support",            // agentName (drives agent-scoped reads)
);
console.log(ctx);

<memory section="userFacts" scope="current_user">
What you know about this user:
- User's name is Akash.
- Akash is based in Mumbai.
</memory>

<memory section="summaries" scope="current_user">
Previous conversation context (most recent first):
...
</memory>

import { SqliteStorage } from "@agentium/core";
memory: { storage: new SqliteStorage("app.db") }

import { PostgresStorage } from "@agentium/core";
const storage = new PostgresStorage("postgresql://user:pass@localhost/db");
await storage.initialize();
memory: { storage }

import { MongoDBStorage } from "@agentium/core";
const storage = new MongoDBStorage("mongodb://localhost:27017/myapp");
await storage.initialize();
memory: { storage }