Memories

Memories are how your backend mirrors application data into Fency. Create and update them from your server with a secret key. Agent tasks can then use those memories as context - for search, chat, or exploration.

Each memory belongs to a memory type that defines its metadata schema. You decide which memories a session can see when you create that session with guardrails.

Source types

A memory is created with one of four source types. TEXT, URL, and FILE are for semantic search: Fency chunks the content and indexes it in a vector store so an agent can search it. METADATA is for typed fields only, with no chunking or vector index.

TEXT

Use TEXT when you already have the text. Send it in the create request. Fency chunks and indexes it so an agent can perform semantic search.

URL

Use URL when the content lives at a downloadable file URL. The url must point to a file Fency can download. Fency downloads it, then chunks and indexes it the same way as text. The link can for example be a presigned URL from Amazon S3 or a similar object store.

FILE

Use FILE when you have the file on your server instead of a downloadable URL. Create an empty memory and upload the bytes. Fency then chunks and indexes it the same way as text. See Uploading files for memories.

METADATA

Use METADATA when semantic search does not matter. There is no text body to chunk. The agent only gets typed fields such as STRING, STRING_LIST, INTEGER, DECIMAL, and BOOLEAN. This is the easiest source type to create: memories are ready immediately, and you can upsert large amounts at once with Memory bulk jobs.

Memory types

Memory types are schemas: a name, optional description, and metadata fields (STRING, STRING_LIST, BOOLEAN, INTEGER, DECIMAL). Create a memory type first, then create memories under its memoryTypeId.

A memory type is either SEMANTIC or METADATA. That kind decides which source types you can create under it:

METADATA types require identityKeyName and updatedAtKeyName on create (the upsert identity and updated-at keys). Do not send those on a SEMANTIC type.

Create a SEMANTIC type for TEXT, URL, and FILE memories:

const semanticType = await fetch('https://api.fency.ai/v1/memory-types', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.FENCY_SECRET_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: 'Contracts',
        description: 'Customer contracts and related files.',
        type: 'SEMANTIC',
    }),
})

Create a METADATA type for typed-field memories. identityKeyName and updatedAtKeyName are required:

const metadataType = await fetch('https://api.fency.ai/v1/memory-types', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.FENCY_SECRET_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: 'Products',
        description: 'Catalog products with typed fields.',
        type: 'METADATA',
        identityKeyName: 'sku',
        updatedAtKeyName: 'last_modified',
    }),
})

For the full request fields, see Create memory type.

Creating a memory

Call POST /v1/memories from your server. For request fields per source type, see Memories.

This example creates a URL memory under the Contracts type. Fency downloads the file at url, then chunks and indexes it.

const response = await fetch('https://api.fency.ai/v1/memories', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.FENCY_SECRET_KEY}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        memoryTypeId: 'mty_...',
        sourceType: 'URL',
        title: 'Acme MSA',
        url: 'https://example.com/contracts/acme-msa.pdf',
        metadata: {
            organization_id: 'org_1234567890',
        },
    }),
})

Fency processes the download asynchronously. A memory.updated webhook tells you when the memory is ready. See Events.

Using memories

Give an agent access to memories for a task by setting guardRails when you create the session. The webapp then starts an agent task with the returned clientToken. See Guardrails for the guardRails.memoryTypes shape.