Context Service

Persistent state management for AI agents. Working memory, blob storage, RAG queries, chat history, and tool orchestration — everything your agents need to maintain context across sessions.

Why It Matters

AI agents need to remember things between sessions. They need to store files, search knowledge bases, maintain structured state, and share information with other agents. Without persistent context, every conversation starts from zero — users repeat themselves, agents lose track of preferences, and multi-step workflows fall apart.

The Context Service provides all of this through a unified API. Working memory stores structured key-value records scoped by entity. Blob storage handles files of any size with cloud-agnostic backends. RAG queries search indexed content. Chat history is automatic with configurable retention. And every operation is available as an MCP tool, so any compatible client can use the full context layer without custom integration.

The Context Service works with multiple cloud storage backends — including Azure Blob Storage and Google Cloud Storage, with more coming. Your agent code uses the SDK or MCP tools; the service handles serialization, storage routing, and lifecycle management automatically.

Key Capabilities

• Working Memory: Structured key-value storage scoped per entity — store and retrieve JSON records with metadata, types, and descriptions
• Blob Storage: Upload and manage files (documents, images, data) with cloud-agnostic backends supporting Azure Blob Storage and Google Cloud Storage
• RAG Queries: Execute retrieval-augmented generation queries against indexed content to ground agent responses in real data
• Chat History: Automatic conversation history with configurable retention and per-node retrieval
• Token Management: Smart truncation and summarization to stay within context window limits as conversations grow
• Session Persistence: Resume conversations days or weeks later with full context — no state lost between sessions
• Multi-Agent Sharing: Share context between agents in a workflow — handoffs, escalations, and collaborative tasks preserve full state
• MCP Integration: All context operations available as MCP tools for any compatible client, with resource templates for blob access
• Tool Orchestration: List and execute registered tools through the context layer, enabling dynamic tool discovery and invocation

Working Memory

Working memory provides structured key-value storage scoped by entity. Each record is a JSON document with a typed memory category (e.g., code/typescript, data/json), a human-readable name and description, and optional entity association. Records support insert, fetch by ID, fetch by entity, and delete operations.

Use working memory for: agent state between sessions, user preferences and learned behaviors, workflow checkpoints and intermediate results, configuration that agents discover at runtime, and structured data that needs to survive across conversation boundaries.

The optional reasoning field lets agents record why they created or updated a record, providing an audit trail for debugging and understanding agent decision-making over time.

import { Bot, context } from '@firefoundry/agent-sdk';

@Bot({ name: 'assistant' })
class Assistant {
  async rememberPreference(userId: string, key: string, value: any) {
    // Store structured data in working memory
    await context.workingMemory.insert({
      entityId: userId,
      key: key,
      data: value,
      metadata: { source: 'user-input', timestamp: Date.now() }
    });
  }

  async getContext(userId: string) {
    // Retrieve all records for this user
    const records = await context.workingMemory.fetchByEntity(userId);
    return records;
  }
}

Blob Storage

Blob storage provides cloud-agnostic file management for AI agents. Upload documents, images, generated reports, data exports, or any binary content. The Context Service routes to Azure Blob Storage or Google Cloud Storage depending on deployment configuration — your agent code never needs to know which provider is in use.

Operations include upload (with MIME type and metadata), get (by key, with optional metadata), delete, and list (by entity). Blobs are also available as MCP resources via the context://blobs/{blob_key} URI template, so MCP clients can read blob content directly through the resource protocol.

The Document Processing Service integrates with blob storage for input and output — process a document from blob storage and store the result back without any intermediate file handling.

RAG Queries and Chat History

RAG queries let your agents search indexed content using SQL-based retrieval, returning relevant passages that ground responses in real data. Chat history is persisted automatically per node with configurable retention, so multi-turn conversations survive across sessions without any manual state management.

Combine both capabilities to build knowledge assistants that remember what was discussed previously and can search organizational knowledge to answer new questions with grounded, accurate responses.

@Bot({
  name: 'knowledge-assistant',
  context: {
    maxTokens: 8000,
    retentionDays: 30,
    shareContext: ['helper']
  }
})
class KnowledgeAssistant {
  async answer(question: string) {
    // RAG: search indexed knowledge
    const relevant = await context.rag.query({
      query: question,
      limit: 5
    });

    // Chat history is automatic
    const history = await context.chatHistory.get({ limit: 20 });

    return this.generateAnswer(question, relevant, history);
  }
}

MCP Tools

Every Context Service operation is exposed as an MCP tool through the MCP Gateway. This means any MCP-compatible client — Claude Desktop, VS Code extensions, custom agents — can use the full context layer without the FireFoundry SDK. The gateway handles authentication, schema validation, and serialization automatically.

The following tools are registered in the context adapter:

Use Cases