Memory

In shortReference for memory store methods in the 10xGraph TypeScript client: store, search, retrieve, update and delete memories with type-based filtering and vector similarity.

  • 7 min read
  • 12 sections
  • Updated
  • v0.10.0
  • Markdown

The memory methods on TenxGraphClient store, search, read, update, delete and bulk-forget long-term memories on the server’s configured store. Each memory has a type, a category and optional metadata, and you retrieve memories by similarity, time, relevance or a hybrid strategy. For a task-oriented walkthrough, see Use the memory API.

All endpoints live under the base path /v1/store. Every method also accepts store-level config and options objects that the server forwards to the store backend.


Imported enums

TypeScript
import {
  MemoryType,
  RetrievalStrategy,
  DistanceMetric,
} from '10xgraph-client';

MemoryType

Value Enum key Use case
'episodic' EPISODIC Conversation memories and session events.
'semantic' SEMANTIC Facts, knowledge, and world-model information.
'procedural' PROCEDURAL How-to knowledge, workflows, and procedures.
'entity' ENTITY Information about specific entities (people, places, products).
'relationship' RELATIONSHIP Relationships between entities.
'declarative' DECLARATIVE Explicit facts and events recorded verbatim.
'custom' CUSTOM Custom memory types specific to your application.

RetrievalStrategy

Value Description
'similarity' Vector similarity search. Default for most use cases.
'temporal' Retrieve memories in chronological order.
'relevance' Score memories by relevance to the query using the store’s own model.
'hybrid' Combination of similarity and relevance.
'graph_traversal' Knowledge graph traversal for entity/relationship memories.

DistanceMetric

Value Description
'cosine' Cosine similarity. Default. Best for semantic similarity in high-dimensional spaces.
'euclidean' Euclidean distance.
'dot_product' Dot product similarity.
'manhattan' Manhattan (L1) distance.

storeMemory(request)

Store a new memory entry.

Endpoint: POST /v1/store/memories

TypeScript
const response = await client.storeMemory({
  content: 'User prefers dark mode and monospace fonts.',
  memory_type: MemoryType.SEMANTIC,
  category: 'preferences',
  metadata: { source: 'user_settings', importance: 'high' },
});

console.log('Stored memory ID:', response.data.memory_id);

StoreMemoryRequest

Field Type Required Description
content string Yes The text content to store as a memory.
memory_type MemoryType Yes The type of memory. Controls how the store indexes and retrieves it.
category string Yes Arbitrary category string for grouping related memories.
metadata Record<string, any> No Optional key-value metadata stored alongside the memory.
config Record<string, any> No Optional store-level config (backend-specific).
options Record<string, any> No Optional store-level options (backend-specific).

StoreMemoryResponse

TypeScript
interface StoreMemoryResponse {
  data: {
    memory_id: string;
  };
  metadata: ResponseMetadata;
}

Save the memory_id to update or delete the memory later.


searchMemory(request)

Search for memories using vector similarity, temporal ordering, or a hybrid strategy.

Endpoint: POST /v1/store/search

TypeScript
const response = await client.searchMemory({
  query: 'What are the user\'s display preferences?',
  memory_type: MemoryType.SEMANTIC,
  category: 'preferences',
  limit: 5,
  retrieval_strategy: RetrievalStrategy.SIMILARITY,
  distance_metric: DistanceMetric.COSINE,
  score_threshold: 0.7,
});

for (const result of response.data.results) {
  console.log(`Score: ${result.score.toFixed(3)}, ${result.content}`);
}

SearchMemoryRequest

Field Type Default Description
query string - The search query. Converted to a vector embedding by the store backend.
memory_type MemoryType EPISODIC Filter by memory type.
category string '' Filter by category. Empty string returns all categories.
limit number 10 Maximum number of results to return.
score_threshold number 0 Minimum similarity score (0 to 1). Results below this threshold are excluded.
filters Record<string, any> {} Additional key-value filters matched against memory metadata.
retrieval_strategy RetrievalStrategy SIMILARITY Which retrieval algorithm to use.
distance_metric DistanceMetric COSINE Which distance metric to use for vector search.
max_tokens number 4000 Maximum total tokens to return across all results.
config Record<string, any> {} Store-level config.
options Record<string, any> {} Store-level options.

SearchMemoryResponse

TypeScript
interface SearchMemoryResponse {
  data: {
    results: MemoryResult[];
  };
  metadata: ResponseMetadata;
}

interface MemoryResult {
  id: string;
  content: string;
  score: number;              // Similarity score (0 to 1, higher is more similar)
  memory_type: string;
  metadata: Record<string, any>;
  vector: number[];           // The embedding vector (may be empty in some backends)
  user_id: string;
  thread_id: string;
  timestamp: string;          // ISO 8601 timestamp
}

getMemory(memoryId, options?)

Fetch a single memory by its ID. It returns the memory as a MemoryResult (the same shape search returns).

Endpoint: POST /v1/store/memories/{memoryId}

TypeScript
const response = await client.getMemory('mem-abc123');
console.log(response.data.memory.content);
console.log(response.data.memory.score);

Parameters

Parameter Type Description
memoryId string The memory ID returned by storeMemory().
options.config Record<string, any> Optional store-level config.
options.options Record<string, any> Optional store-level options.

updateMemory(memoryId, content, options?)

Replace the content of an existing memory. You can pass new metadata through options.metadata; the memory’s type and category cannot be changed with this method.

Endpoint: PUT /v1/store/memories/{memoryId}

TypeScript
await client.updateMemory(
  'mem-abc123',
  'User prefers dark mode, monospace fonts, and large text size.',
  {
    metadata: { tags: ['display', 'accessibility'], revised: true },
  }
);

Parameters

Parameter Type Description
memoryId string The memory ID.
content string The new text content. Replaces the previous content.
options.config Record<string, any> Optional store-level config.
options.options Record<string, any> Optional store-level options.
options.metadata Record<string, any> Updated metadata. Sent as {} when omitted. Whether it merges with or replaces existing metadata depends on the store backend.

UpdateMemoryResponse

TypeScript
interface UpdateMemoryResponse {
  data: {
    success: boolean;
    data: Record<string, any>;
  };
  metadata: ResponseMetadata;
}

deleteMemory(memoryId, options?)

Delete a memory by ID.

Endpoint: DELETE /v1/store/memories/{memoryId}

TypeScript
const response = await client.deleteMemory('mem-abc123');
console.log('Deleted:', response.data.success);

Parameters

Parameter Type Description
memoryId string The memory ID.
options.config Record<string, any> Optional store-level config.
options.options Record<string, any> Optional store-level options.

DeleteMemoryResponse

TypeScript
interface DeleteMemoryResponse {
  data: {
    success: boolean;
    data: string;
  };
  metadata: ResponseMetadata;
}

listMemories(options?)

List stored memories, up to a limit that defaults to 100. It returns response.data.memories, an array of MemoryResult.

Endpoint: POST /v1/store/memories/list

TypeScript
const response = await client.listMemories({ limit: 100 });

console.log(`Found ${response.data.memories.length} memories`);
for (const mem of response.data.memories) {
  console.log(`[${mem.memory_type}] ${mem.content.slice(0, 80)}`);
}

Parameters

Parameter Type Description
options.limit number Maximum number of memories to return. Default 100.
options.config Record<string, any> Optional store-level config.
options.options Record<string, any> Optional store-level options.

forgetMemories(options?)

Bulk-delete memories matching a type, category or metadata filter. It is one request instead of a deleteMemory() call per memory. Only the fields you pass are sent.

Endpoint: POST /v1/store/memories/forget

TypeScript
// Delete all episodic memories in the 'session_temp' category
await client.forgetMemories({
  memory_type: MemoryType.EPISODIC,
  category: 'session_temp',
});

// Delete memories matching custom filters
await client.forgetMemories({
  filters: { expired: true },
});

Parameters

Parameter Type Description
options.memory_type MemoryType Filter by memory type.
options.category string Filter by category.
options.filters Record<string, any> Additional key-value filters matched against memory metadata.
options.config Record<string, any> Optional store-level config.
options.options Record<string, any> Optional store-level options.

ForgetMemoriesResponse

TypeScript
interface ForgetMemoriesResponse {
  data: {
    success: boolean;
    data: Record<string, any>;
  };
  metadata: ResponseMetadata;
}

Complete example: memory-enhanced agent

This example searches memory before each call, passes the hits to the agent as a system message, then stores the question as an episodic memory. It assumes a running server with a configured store.

memory-agent.ts
import {
  TenxGraphClient,
  Message,
  MemoryType,
  RetrievalStrategy,
} from '10xgraph-client';

const client = new TenxGraphClient({ baseUrl: 'http://localhost:8000' });

// Before invoking the agent, retrieve relevant past memories
async function invokeWithMemory(userInput: string) {
  // 1. Search for relevant context
  const memories = await client.searchMemory({
    query: userInput,
    memory_type: MemoryType.SEMANTIC,
    limit: 3,
    score_threshold: 0.6,
    retrieval_strategy: RetrievalStrategy.SIMILARITY,
  });

  // 2. Build a system prompt with context
  const context = memories.data.results
    .map(r => `- ${r.content}`)
    .join('\n');

  const systemMsg = Message.text_message(
    `You are a helpful assistant. Relevant context from memory:\n${context}`,
    'system'
  );

  // 3. Invoke the agent
  const result = await client.invoke([
    systemMsg,
    Message.text_message(userInput),
  ]);

  // 4. Store the interaction as an episodic memory
  await client.storeMemory({
    content: `User asked: "${userInput}"`,
    memory_type: MemoryType.EPISODIC,
    category: 'conversations',
  });

  return result;
}

const result = await invokeWithMemory('What theme should the dashboard use?');
console.log(result.messages);

Common errors

Failed requests from every method except forgetMemories() throw TenxGraphError with a statusCode. forgetMemories() throws a plain Error with the message Forget memories failed: <status> <statusText>. See Client errors for the full error class.

Error Cause Fix
status 404 Memory not found (wrong ID or already deleted). Check the ID returned by storeMemory().
status 422 searchMemory() was called with an empty query. Pass a non-empty query string.
status 503 Store not configured or unavailable. Check the store field in 10xgraph.json and the store backend status.

What you learned

  • Use MemoryType to categorize memories and filter on it when searching.
  • searchMemory() with RetrievalStrategy.SIMILARITY performs vector search, so the store must support embeddings.
  • listMemories() returns up to limit memories (default 100); it has no offset.
  • forgetMemories() bulk-deletes by type, category or filter.

Next step

See Files to learn how to upload and reference media files in multimodal messages.

Last updated for v0.10.0Edit this page on GitHubReport an issue