import { createBucketClient } from '@cosmicjs/sdk'
const cosmic = createBucketClient({
bucketSlug: process.env.COSMIC_BUCKET_SLUG!,
readKey: process.env.COSMIC_READ_KEY!,
writeKey: process.env.COSMIC_WRITE_KEY!,
})
async function storeAgentFinding({
topic,
summary,
sourceUrl,
confidenceScore,
}: {
topic: string
summary: string
sourceUrl: string
confidenceScore: number
}) {
const result = await cosmic.objects.insertOne({
title: topic,
type: 'agent-findings',
status: 'draft', // human review before publishing
metadata: {
summary,
source_url: sourceUrl,
confidence_score: confidenceScore,
reviewed: false,
},
})
return result.object
}
The output is immediately visible in the dashboard. A team member can review the summary, edit it, toggle reviewed to true, and publish, all without touching code.
Storing Prompts, Context, and Conversation Memory
Agent outputs are only part of the picture. The other half is what goes in to the agent: system prompts, conversation history, and session context.
System Prompts as Objects
Instead of hardcoding system prompts in your codebase, store them as Objects. This gives you version control for prompts (draft a new version, test it, publish when ready, roll back if behavior degrades), non-engineer editable wording without a deploy, and environment-aware prompts per environment with zero code changes.
// Fetch the active system prompt for an agent
const { object: promptObject } = await cosmic.objects
.findOne({
type: 'agent-prompts',
slug: 'content-research-agent',
status: 'published',
})
.props('title,metadata.prompt_text,metadata.version')
const systemPrompt = promptObject.metadata.prompt_text
When you want to update the prompt, you edit it in the dashboard, save a new version, and publish. The agent picks it up on the next run with no deployment required.
Conversation Context and Message History
For agents that need to maintain state across sessions, store the conversation history as structured Objects:
async function storeMessage({
sessionId,
role,
content,
agentName,
}: {
sessionId: string
role: 'user' | 'assistant' | 'system'
content: string
agentName: string
}) {
await cosmic.objects.insertOne({
title: `${agentName} / ${sessionId} / ${role}`,
type: 'agent-messages',
status: 'published',
metadata: {
session_id: sessionId,
role,
content,
agent_name: agentName,
},
})
}
// Retrieve full conversation context for a session
const { objects: messages } = await cosmic.objects
.find({
type: 'agent-messages',
'metadata.session_id': sessionId,
})
.props('metadata.role,metadata.content,created_at')
.sort('created_at')
The agent can reconstruct its full conversation history on every run. The history is human-readable in the dashboard, editable when needed, and queryable across sessions.
Querying Agent Memory
The real power is in retrieval. Because each agent output is a structured Object with typed metafields, you can query across your entire agent history:
// Get all unreviewed findings from the last 7 days
const { objects } = await cosmic.objects
.find({
type: 'agent-findings',
'metadata.reviewed': false,
})
.props('id,title,metadata,created_at')
.sort('-created_at')
.limit(50)
// Get high-confidence findings on a specific topic
const { objects: topFindings } = await cosmic.objects
.find({
type: 'agent-findings',
'metadata.confidence_score': { $gte: 0.85 },
})
.props('id,title,metadata')
.sort('-metadata.confidence_score')
You are filtering by structured properties, sorting by custom scores, and scoping by review status. The agent's memory is queryable the same way any other content in your system is queryable.
Versioning: Know What the Agent Said When
A full revision history for every Object matters for auditability. If an agent's output informed a business decision, you need to know exactly what it said at the time of that decision, not just the current state. The same applies to prompts. When a prompt change shifts agent behavior, you can trace exactly which version was active and when. That's the kind of audit trail that matters as agents take on more consequential tasks.
Using the MCP Server
Cosmic ships a native MCP Server, which means any agent running in Claude, Cursor, Windsurf, or any MCP-compatible runtime can read and write Objects directly, with no custom API wrapper needed. The MCP Server exposes all 18 Cosmic tools to your agent: create objects, update objects, query by type, filter by metadata, manage media, and more.
Schema Design for Agent Context and Memory
The key to making this work well is defining clean Object types upfront. Three schemas cover most agent context and memory use cases:
agent-findings: summary (textarea), source_url (text), confidence_score (number 0-1), agent_name (text), session_id (text), reviewed (switch), tags (references)
agent-messages: role (select: user/assistant/system), content (textarea), agent_name (text), session_id (text)
agent-prompts: prompt_text (textarea), version (number), notes (textarea)
What You Get Out of the Box
You could build this with Postgres and a custom schema. A headless CMS includes a dashboard UI for every agent output with no custom admin to build, built-in revision history with no extra tables, a REST API ready to consume from any runtime, a draft/published workflow, media handling, and model agnosticism across any framework or language.
Read the full post on the Cosmic blog for the complete walkthrough, including the copy-paste schema setup and getting-started steps.