selfmemory

TypeScript SDK for the SelfMemory API — universal memory layer for AI apps.

Installation

npm install selfmemory

Quick Start

import { SelfMemory } from 'selfmemory'

const memory = new SelfMemory({
  apiKey: process.env.SELFMEMORY_API_KEY!,
})

// Store a memory
await memory.add('User prefers dark mode and uses TypeScript', {
  tags: 'preferences,tech',
  topic_category: 'settings',
  user_id: 'user_123',
})

// Search memories
const results = await memory.search('what does the user prefer?', {
  user_id: 'user_123',
  limit: 5,
})

console.log(results.results)

Configuration

const memory = new SelfMemory({
  apiKey: 'sk_im_...',             // Required — project-scoped API key
  host: 'https://api.selfmemory.com', // Optional — defaults to managed API
})

Option	Type	Required	Default	Description
apiKey	string	Yes	—	Project-scoped API key from the SelfMemory dashboard
host	string	No	https://api.selfmemory.com	API base URL

API Reference

add(content, options?)

Store a memory.

const result = await memory.add('Meeting with Sarah about Q4 roadmap', {
  tags: 'work,meeting',
  people_mentioned: 'Sarah',
  topic_category: 'business',
  user_id: 'user_123',
})
// { success: true, memory_id: '...', message: '...' }

Option	Type	Description
tags	string	Comma-separated tags
people_mentioned	string	Comma-separated names
topic_category	string	Topic classification
metadata	Record<string, unknown>	Additional metadata
user_id	string	Scope to a specific end-user

search(query, options?)

Semantic search across memories.

const results = await memory.search('project discussions', {
  limit: 10,
  tags: ['work', 'meeting'],
  temporal_filter: 'this_week',
  threshold: 0.7,
  user_id: 'user_123',
})

Option	Type	Description
limit	number	Max results (default: 10)
tags	string[]	Filter by tags
people_mentioned	string[]	Filter by people
topic_category	string	Filter by topic
temporal_filter	string	Time filter (today, this_week, this_month)
threshold	number	Min similarity score (0-1)
match_all_tags	boolean	Require all tags to match
user_id	string	Scope to a specific end-user

getAll(options?)

List all memories with pagination.

const all = await memory.getAll({ limit: 50, offset: 0 })

get(memoryId)

Get a single memory by ID.

const mem = await memory.get('memory-uuid-here')

update(memoryId, data)

Update a memory.

await memory.update('memory-uuid', {
  text: 'Updated content',
  metadata: { tags: 'updated' },
})

delete(memoryId)

Delete a single memory.

await memory.delete('memory-uuid')

deleteAll(options?)

Delete all memories.

await memory.deleteAll({ user_id: 'user_123' })

searchByTags(tags, options?)

Search by tags with optional semantic query.

const results = await memory.searchByTags(['work', 'important'], {
  semantic_query: 'deadlines',
  match_all: true,
  limit: 10,
})

searchByPeople(people, options?)

Search by people mentioned.

const results = await memory.searchByPeople(['Sarah', 'Mike'], {
  semantic_query: 'project updates',
})

temporalSearch(temporalQuery, options?)

Search by time range.

const results = await memory.temporalSearch('yesterday', {
  semantic_query: 'meetings',
})

getStats(projectId?)

Get memory statistics.

const stats = await memory.getStats()
// { total: 150, this_week: 12, tag_count: 25 }

health()

Health check.

const status = await memory.health()

Error Handling

import { SelfMemory, SelfMemoryError } from 'selfmemory'

try {
  await memory.get('nonexistent-id')
} catch (err) {
  if (err instanceof SelfMemoryError) {
    console.error(err.status)  // 404
    console.error(err.detail)  // "Memory not found"
  }
}

TypeScript

All types are exported:

import type { Memory, SearchOptions, AddResponse } from 'selfmemory'

Requirements

• Node.js 18+ (uses native fetch)
• Works in modern browsers

License

MIT