Skip to main content

Memories

A memory is a piece of information you store in Memsolus on behalf of a user, agent, or session. Memories are the building blocks of everything else — once stored, Memsolus automatically processes them into searchable knowledge.

What Is a Memory?​

Anything worth remembering can be a memory: a user preference, a project decision, a fact from a conversation. You store it as plain text, and Memsolus handles the rest.

import { Memsolus } from '@memsolus/sdk';

const client = new Memsolus({ apiKey: 'msk_live_...' });

await client.memories.add({
  content: 'The user prefers TypeScript and avoids JavaScript for new projects.',
  userId: 'user_123',
  priority: 'HIGH',
});

Memory Fields​

FieldTypeDescription
idstringUnique identifier for the memory (mem_...)
contentstringThe text of the memory
user_idstringThe user this memory belongs to
agent_idstringThe agent that created the memory (optional)
session_idstringThe session context (optional)
priorityenumLOW, MEDIUM, or HIGH — affects ranking in search results
statusenumCurrent processing status (see below)
categoriesstring[]Tags for organizing and filtering memories
metadataobjectFree-form key-value pairs for custom filtering
created_atstringISO 8601 creation timestamp
updated_atstringISO 8601 last-update timestamp

Memory Status​

After you store a memory, it goes through an automatic processing flow. The status field tells you where it is:

StatusWhat it means
PENDINGMemory received and queued for processing
PROCESSINGBeing analyzed and prepared for search
READYFully processed and searchable
CONSOLIDATEDMerged into an existing memory that covered the same information

Most memories reach READY within seconds. Once READY, the memory is available in search results and contributes to the user's Knowledge Base.

Priority​

Priority influences how memories surface in search results. Higher-priority memories appear first when multiple results are relevant.

PriorityWhen to use
HIGHCritical facts that should always surface — "the user is the CEO of Acme"
MEDIUMGeneral context — the default for most memories
LOWBackground details that rarely need to surface — "user mentioned liking coffee"

Metadata​

Metadata is a free-form JSON object you attach to a memory. Use it to carry extra context and to enable filtering when searching.

await client.memories.add({
  content: 'The team uses GitHub for version control and Jira for issue tracking.',
  userId: 'user_123',
  metadata: {
    source: 'onboarding_call',
    project: 'backend_api',
  },
});

You can then filter by metadata when searching:

curl -X POST https://api.memsolus.com/v1/memories/search \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "version control tools",
    "user_id": "user_123",
    "filter": { "project": "backend_api" }
  }'

Categories​

Categories are tags you can assign to memories for organization and filtering. They are returned alongside the memory and can be used as a search filter.

await client.memories.add({
  content: 'The user prefers async communication over meetings.',
  userId: 'user_123',
  categories: ['preferences', 'communication'],
});

Memsolus also automatically assigns categories based on the content of your memories.