Skip to main content

​
Write memories

Write text entries into a namespace. Each entry is embedded and indexed for semantic search. You can attach optional metadata for filtering or display.

​
SDK

import { Foundry } from '@withfoundry/sdk';

const foundry = new Foundry({ apiKey: process.env.FOUNDRY_API_KEY });

// Single entry
const { data } = await foundry.memory.write({
  namespace: 'my-app',
  entries: [
    {
      content: 'User preferences: theme=dark, timezone=UTC.',
      metadata: { type: 'preferences', userId: 'u_123' },
    },
  ],
});
// data.ids = ['mem_abc123...']

​
Batch write

Send multiple entries in one request: 
const { data } = await foundry.memory.write({
  namespace: 'my-app',
  entries: [
    { content: 'First fact.', metadata: { source: 'doc' } },
    { content: 'Second fact.', metadata: { source: 'doc' } },
    { content: 'Third fact.', metadata: { source: 'chat' } },
  ],
});
// data.ids = ['mem_...', 'mem_...', 'mem_...']

​
REST API

POST /v1/memory/entries Headers: Authorization: Bearer key_...
Body: 
{
  "namespace": "my-app",
  "entries": [
    {
      "content": "Your text here.",
      "metadata": { "key": "value" }
    }
  ]
}
Response (envelope): 
{
  "success": true,
  "data": {
    "ids": ["mem_abc123", "mem_def456"]
  },
  "meta": { "requestId": "req_xyz" }
}

​
Metadata

  • Optional. Use for filtering (e.g. metadata.source, metadata.userId) or for display in your UI.
  • Stored as JSON; avoid huge objects to keep responses and indexes lean.

​
Idempotency and updates

  • Each write creates new entries and new IDs. To “update,” write a new entry and optionally delete or deprecate the old one via your own logic or future delete API.
  • For idempotent writes, include a stable metadata.id and deduplicate in your app before calling write.
Next: Search to query these entries by meaning.