Skip to content
Raindrop Developer Hub

Smart Memory

The Smart Memory service provides comprehensive memory management capabilities for AI agents. It enables agents to store, retrieve, search, and manage memories in a timeline-based system with working-, semantic-, episodic-, procedural-, memory storage capabilities. The service supports semantic search, temporal queries, and intelligent summarization.

POST /v1/put_memory

Stores a new memory entry in the agent’s working memory. Memories are organized by timeline and can include contextual information like the agent responsible and triggering events.

The system will:

  • Store the memory with automatic timestamping
  • Generate embeddings for semantic search
  • Associate the memory with the specified timeline
  • Enable future retrieval and search operations

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Unique session identifier for the working memory instance

Example
01jxanr45haeswhay4n0q8340y

timeline (string(nullable))

Details
Description

Timeline identifier for organizing related memories

Example
user-conversation-2024

key (string(nullable))

Details
Description

Optional key for direct memory retrieval

Example
user-preference-theme

content (string) Required

Details
Description

The actual memory content to store

Example
User prefers dark theme for the interface

agent (string(nullable))

Details
Description

Agent identifier responsible for this memory

Example
assistant-v1
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const putMemory = await client.putMemory.create({
  content: 'User prefers dark theme for the interface',
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(putMemory.memoryId);

Response Examples

{
  "memoryId": "01jxanr45haeswhay4n0q8340y"
}

POST /v1/get_memory

Retrieves memories based on timeline, key, or temporal criteria. Supports filtering by specific timelines, time ranges, and limiting results to the most recent entries.

Query capabilities:

  • Timeline-specific retrieval
  • Key-based lookup
  • Temporal range queries
  • Most recent N entries

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Unique session identifier for the working memory instance

Example
01jxanr45haeswhay4n0q8340y

timeline (string(nullable))

Details
Description

Timeline to filter memories

Example
user-conversation-2024

key (string(nullable))

Details
Description

Specific key to retrieve

Example
user-preference-theme

nMostRecent (integer(nullable))

Details
Description

Maximum number of most recent memories to return

Example
10

startTime (object(nullable))

Details
Description

Start time for temporal filtering

endTime (object(nullable))

Details
Description

End time for temporal filtering

 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const getMemory = await client.getMemory.retrieve({
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(getMemory.memories);

Response Examples

{
  "memories": [
    {
      "id": "01jxanr45haeswhay4n0q8340y",
      "sessionId": "01jxanr45haeswhay4n0q8340y",
      "timeline": "user-conversation-2024",
      "by": "assistant-v1",
      "dueTo": "user-input",
      "content": "User prefers dark theme for the interface",
      "at": "2025-05-05T18:36:43.029Z",
      "key": "user-preference-theme",
      "agent": "assistant-v1"
    }
  ]
}

POST /v1/search_memory

Performs semantic search across stored memories using natural language queries. The system uses vector embeddings to find semantically similar content regardless of exact keyword matches.

Search features:

  • Semantic similarity matching
  • Timeline-specific search
  • Temporal filtering
  • Relevance-based ranking

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Unique session identifier for the working memory instance

Example
01jxanr45haeswhay4n0q8340y

timeline (string(nullable))

Details
Description

Timeline to filter search results

Example
user-conversation-2024

terms (string) Required

Details
Description

Natural language search query

Example
user interface preferences

nMostRecent (integer(nullable))

Details
Description

Maximum number of most recent results to return

Example
10

startTime (object(nullable))

Details
Description

Start time for temporal filtering

endTime (object(nullable))

Details
Description

End time for temporal filtering

 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.memory.search({
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
  terms: 'user interface preferences',
});


console.log(response.memories);

Response Examples

{
  "memories": [
    {
      "id": "01jxanr45haeswhay4n0q8340y",
      "sessionId": "01jxanr45haeswhay4n0q8340y",
      "timeline": "user-conversation-2024",
      "by": "assistant-v1",
      "dueTo": "user-input",
      "content": "User prefers dark theme for the interface",
      "at": "2025-05-05T18:36:43.029Z",
      "key": "user-preference-theme",
      "agent": "assistant-v1"
    }
  ]
}

POST /v1/delete_memory

Removes a specific memory entry from storage. This operation is permanent and cannot be undone.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Unique session identifier for the working memory instance

Example
01jxanr45haeswhay4n0q8340y

memoryId (string) Required

Details
Description

Unique identifier of the memory entry to delete

Example
01jxanr45haeswhay4n0q8340y
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const deleteMemory = await client.deleteMemory.create({
  memoryId: '01jxanr45haeswhay4n0q8340y',
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(deleteMemory.success);

Response Examples

{
  "success": true
}

POST /v1/summarize_memory

Generates intelligent summaries of a collection of memories using AI. Can optionally accept custom system prompts to guide the summarization style.

The summarization system:

  • Identifies key themes and patterns
  • Extracts important events and decisions
  • Maintains temporal context
  • Supports custom summarization instructions

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Unique session identifier for the working memory instance

Example
01jxanr45haeswhay4n0q8340y

memoryIds (array) Required

Details
Description

List of memory IDs to summarize

Example
[
  "01jxanr45haeswhay4n0q8340y",
  "01jxanr45haeswhay4n0q8341z"
]

systemPrompt (string(nullable))

Details
Description

Optional custom system prompt for summarization

Example
Summarize the key decisions and action items
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const summarizeMemory = await client.summarizeMemory.create({
  memoryIds: ['01jxanr45haeswhay4n0q8340y', '01jxanr45haeswhay4n0q8341z'],
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(summarizeMemory.summarizedMemoryIds);

Response Examples

{
  "summary": "The conversation focused on user interface preferences...",
  "summarizedMemoryIds": [
    "example"
  ]
}

POST /v1/start_session

Starts a new working memory session for an agent. Each session provides isolated memory operations and automatic cleanup capabilities.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const startSession = await client.startSession.create({
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(startSession.sessionId);

Response Examples

{
  "sessionId": "01jxanr45haeswhay4n0q8340y"
}

POST /v1/end_session

Ends a working memory session, optionally flushing working memory to long-term storage. When flush is enabled, important memories are processed and stored for future retrieval.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Unique session identifier to end

Example
01jxanr45haeswhay4n0q8340y

flush (boolean(nullable))

Details
Description

Whether to flush working memory to long-term storage

Example
true

systemPrompt (string(nullable))

Details
Description

Optional custom system prompt for memory summarization during flush

Example
Summarize the key decisions and action items from this session
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const endSession = await client.endSession.create({
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(endSession.success);

Response Examples

{
  "success": true
}

POST /v1/rehydrate_session

Rehydrates a previous session from episodic memory storage. Allows resuming work from where a previous session left off by restoring either all memories or just a summary of the previous session.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

sessionId (string) Required

Details
Description

Session identifier to restore from episodic memory

Example
01jxanr45haeswhay4n0q8340y

summaryOnly (boolean(nullable))

Details
Description

If true, only restore a summary. If false, restore all memories

Example
false
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.rehydrateSession.rehydrate({
  sessionId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(response.operation);

Response Examples

{
  "success": true,
  "operation": "example",
  "statusKey": "example"
}

POST /v1/search_episodic_memory

Searches across episodic memory documents stored in the SmartBucket. Allows finding relevant past sessions based on natural language queries. Returns summaries and metadata from stored episodic memory sessions.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

terms (string) Required

Details
Description

Natural language search query to find relevant episodic memory sessions

Example
sessions about user interface preferences

nMostRecent (integer(nullable))

Details
Description

Maximum number of most recent results to return

Example
10

startTime (object(nullable))

Details
Description

Start time for temporal filtering

endTime (object(nullable))

Details
Description

End time for temporal filtering

 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.episodicMemory.search({
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
  terms: 'sessions about user interface preferences',
});


console.log(response.entries);

Response Examples

{
  "entries": [
    {
      "sessionId": "01jxanr45haeswhay4n0q8340y",
      "summary": "User discussed interface preferences and requested dark theme support",
      "agent": "assistant-v1",
      "entryCount": 25,
      "timelineCount": 3,
      "duration": 1800000,
      "createdAt": "2025-05-05T18:36:43.029Z",
      "score": 0.85
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "pageSize": 123,
    "totalPages": 123,
    "hasMore": true
  }
}

POST /v1/put_procedure

Stores a new procedure in the agent’s procedural memory. Procedures are reusable knowledge artifacts like system prompts, templates, workflows, or instructions that can be retrieved and applied across different sessions and contexts.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

key (string) Required

Details
Description

Unique key to identify this procedure

Example
TechnicalReportSystemPrompt

value (string) Required

Details
Description

The procedure content (prompt, template, instructions, etc.)

Example
You are a technical documentation assistant...

proceduralMemoryId (string(nullable))

Details
Description

Optional procedural memory ID to use for actor isolation

Example
demo-smartmemory
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const putProcedure = await client.putProcedure.create({
  key: 'TechnicalReportSystemPrompt',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
  value: 'You are a technical documentation assistant...',
});


console.log(putProcedure.success);

Response Examples

{
  "success": true
}

POST /v1/get_procedure

Retrieves a specific procedure by key from procedural memory. Procedures are persistent knowledge artifacts that remain available across all sessions and can be shared between different agent instances.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

key (string) Required

Details
Description

Unique key of the procedure to retrieve

Example
TechnicalReportSystemPrompt

proceduralMemoryId (string(nullable))

Details
Description

Optional procedural memory ID to use for actor isolation

Example
demo-smartmemory
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const getProcedure = await client.getProcedure.create({
  key: 'TechnicalReportSystemPrompt',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(getProcedure.found);

Response Examples

{
  "value": "You are a technical documentation assistant...",
  "found": true
}

POST /v1/delete_procedure

Removes a specific procedure from procedural memory. This operation is permanent and affects all future sessions.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

key (string) Required

Details
Description

Unique key of the procedure to delete

Example
TechnicalReportSystemPrompt

proceduralMemoryId (string(nullable))

Details
Description

Optional procedural memory ID to use for actor isolation

Example
demo-smartmemory
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const deleteProcedure = await client.deleteProcedure.create({
  key: 'TechnicalReportSystemPrompt',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(deleteProcedure.success);

Response Examples

{
  "success": true
}

POST /v1/list_procedures

Lists all procedures stored in procedural memory. Returns metadata about each procedure including creation and modification times.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

proceduralMemoryId (string(nullable))

Details
Description

Optional procedural memory ID to use for actor isolation

Example
demo-smartmemory
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const listProcedure = await client.listProcedures.create({
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(listProcedure.procedures);

Response Examples

{
  "procedures": [
    {
      "key": "TechnicalReportSystemPrompt",
      "value": "You are a technical documentation assistant...",
      "createdAt": "2025-05-05T18:36:43.029Z",
      "updatedAt": "2025-05-05T18:36:43.029Z"
    }
  ]
}

POST /v1/search_procedures

Searches procedures using text matching across keys and values. Supports filtering by procedure keys, values, or both with fuzzy matching and relevance scoring.

TODO: Future enhancement will include vector search for semantic similarity.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

terms (string) Required

Details
Description

Search terms to match against procedure keys and values

Example
system prompt

nMostRecent (integer(nullable))

Details
Description

Maximum number of results to return

Example
10

searchKeys (boolean(nullable))

Details
Description

Whether to search in procedure keys

Example
true

searchValues (boolean(nullable))

Details
Description

Whether to search in procedure values

Example
true

proceduralMemoryId (string(nullable))

Details
Description

Optional procedural memory ID to use for actor isolation

Example
demo-smartmemory
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.procedures.search({
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
  terms: 'system prompt',
});


console.log(response.procedures);

Response Examples

{
  "procedures": [
    {
      "key": "TechnicalReportSystemPrompt",
      "value": "You are a technical documentation assistant...",
      "createdAt": "2025-05-05T18:36:43.029Z",
      "updatedAt": "2025-05-05T18:36:43.029Z"
    }
  ]
}

POST /v1/put_semantic_memory

Stores a semantic memory document for long-term knowledge retrieval. Semantic memory is used for storing structured knowledge, facts, and information that can be searched and retrieved across different sessions.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

document (string) Required

Details
Description

JSON-encoded document content to store in semantic memory

Example
{
  "title": "AI Best Practices",
  "content": "...",
  "category": "development"
}
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const putSemanticMemory = await client.putSemanticMemory.create({
  document: 'document',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(putSemanticMemory.error);

Response Examples

{
  "success": true,
  "objectId": "01jxanr45haeswhay4n0q8340y",
  "error": "example"
}

POST /v1/get_semantic_memory

Retrieves a specific semantic memory document by its object ID. Returns the complete document with all its stored properties and metadata.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

objectId (string) Required

Details
Description

Unique object identifier of the document to retrieve

Example
01jxanr45haeswhay4n0q8340y
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const getSemanticMemory = await client.getSemanticMemory.create({
  objectId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(getSemanticMemory.document);

Response Examples

{
  "success": true,
  "document": {
    "title": "AI Best Practices",
    "content": "...",
    "category": "development"
  },
  "error": "example"
}

POST /v1/search_semantic_memory

Searches across semantic memory documents using natural language queries. Uses vector embeddings and semantic similarity to find relevant knowledge documents regardless of exact keyword matches.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

needle (string) Required

Details
Description

Natural language search query to find relevant documents

Example
AI development best practices
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.query.semanticMemory.search({
  needle: 'AI development best practices',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(response.documentSearchResponse);

Response Examples

{
  "success": true,
  "documentSearchResponse": {
    "results": [
      {
        "chunkSignature": "example",
        "text": "example",
        "source": "example",
        "payloadSignature": "example",
        "score": 0.85,
        "embed": "example",
        "type": "example"
      }
    ]
  },
  "error": "example"
}

POST /v1/delete_semantic_memory

Removes a specific semantic memory document by its object ID. This operation permanently deletes the document and is irreversible.

Schema Reference

Request Body

smartMemoryLocation (object) Required

Details
Description

Smart memory locator for targeting the correct smart memory instance

Example
{
  "smart_memory": {
    "name": "memory-name",
    "application_name": "demo",
    "version": "1234"
  }
}

objectId (string) Required

Details
Description

Unique object identifier of the document to delete

Example
01jxanr45haeswhay4n0q8340y
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const deleteSemanticMemory = await client.deleteSemanticMemory.delete({
  objectId: '01jxanr45haeswhay4n0q8340y',
  smartMemoryLocation: { smart_memory: { name: 'memory-name', application_name: 'demo', version: '1234' } },
});


console.log(deleteSemanticMemory.error);

Response Examples

{
  "success": true,
  "error": "example"
}