Memory - Complete API Reference

Store and recall user preferences, facts, and notes across conversations. Semantic search powered by vector embeddings.

---

Chat Commands

Store Memories

/remember preference risk=conservative      Save trading preference
/remember fact BTC halving is in April 2028 Store a fact
/remember note Check ETH before market open Save a note
/remember rule Never trade during FOMC      Store trading rule

Recall Memories

/memory                                     View all memories
/memory preferences                         View preferences only
/memory facts                               View facts only
/memory notes                               View notes only
/memory rules                               View trading rules
/memory search "bitcoin"                    Search memories

Forget Memories

/forget <key>                               Delete specific memory
/forget all preferences                     Clear all preferences
/forget all                                 Clear everything (careful!)

---

TypeScript API Reference

Create Memory Service

import { createMemoryService } from 'clodds/memory';

const memory = createMemoryService({
  // Storage backend
  backend: 'lancedb',  // 'lancedb' | 'sqlite' | 'postgres'

  // Embedding model
  embeddings: {
    provider: 'openai',
    model: 'text-embedding-3-small',
  },

  // Options
  encryptionKey: process.env.MEMORY_ENCRYPTION_KEY,
});

Remember (Store)

// Store a preference
await memory.remember({
  userId: 'user-123',
  type: 'preference',
  key: 'risk_tolerance',
  value: 'conservative',
});

// Store a fact
await memory.remember({
  userId: 'user-123',
  type: 'fact',
  content: 'BTC halving occurs approximately every 4 years',
  metadata: { topic: 'crypto', confidence: 0.95 },
});

// Store a note
await memory.remember({
  userId: 'user-123',
  type: 'note',
  content: 'Check Polymarket for election markets before Tuesday',
  metadata: { priority: 'high' },
});

// Store a trading rule
await memory.remember({
  userId: 'user-123',
  type: 'rule',
  content: 'Never trade more than 5% of portfolio on single position',
});

Recall (Retrieve)

// Get all memories for user
const all = await memory.recall({ userId: 'user-123' });

// Get by type
const preferences = await memory.recall({
  userId: 'user-123',
  type: 'preference',
});

// Get specific key
const risk = await memory.recall({
  userId: 'user-123',
  type: 'preference',
  key: 'risk_tolerance',
});

Semantic Search

// Search by meaning (not just keywords)
const results = await memory.semanticSearch({
  userId: 'user-123',
  query: 'what is my risk appetite?',
  limit: 5,
  threshold: 0.7,  // Similarity threshold
});

for (const result of results) {
  console.log(`${result.type}: ${result.content}`);
  console.log(`  Similarity: ${result.score}`);
}

Forget (Delete)

// Delete specific memory
await memory.forget({
  userId: 'user-123',
  type: 'preference',
  key: 'risk_tolerance',
});

// Delete all of a type
await memory.forgetByType({
  userId: 'user-123',
  type: 'note',
});

// Delete all memories
await memory.forgetAll({ userId: 'user-123' });

Daily Journal

// Log daily activity
await memory.logDaily({
  userId: 'user-123',
  date: new Date(),
  trades: 5,
  pnl: 123.45,
  notes: 'Good day, caught BTC rally',
});

// Get journal entries
const journal = await memory.getDailyLogs({
  userId: 'user-123',
  from: '2024-01-01',
  to: '2024-01-31',
});

---

Memory Types

Type	Purpose	Example
preference	User settings	risk=conservative
fact	Stored knowledge	"ETH gas is cheaper on weekends"
note	Reminders/todos	"Check election markets"
rule	Trading rules	"Max 5% per position"
context	Conversation context	Auto-saved by system

---

Storage Backends

Backend	Description	Best For
LanceDB	Vector DB with hybrid search	Production, semantic search
SQLite	Local file-based	Development, single user
PostgreSQL	Distributed with pgvector	Multi-user, production

---

Best Practices

1. Be specific with keys — max_position_size not just size
2. Use types correctly — Preferences for settings, rules for constraints
3. Semantic search — Ask questions naturally, embeddings will match
4. Regular cleanup — Delete outdated notes and facts
5. Backup memories — Export before major changes