@memoryai/core

Shared core library for MemoryAI packages - config resolution, offline cache, and API client.

Features

• Unified Config System: Resolves config from multiple sources with priority: Per-IDE > Server > Shared Local > Env Vars > Defaults
• Offline Cache: SQLite-based cache for memories, works without network
• API Client: Robust client with retry logic, exponential backoff, and timeout handling
• Type Safety: Full TypeScript types and interfaces

Installation

npm install @memoryai/core

Usage

Basic Usage

import { MemoryClient } from '@memoryai/core';

const client = new MemoryClient({
  config: {
    endpoint: 'https://memoryai.dev',
    apiKey: 'hm_sk_...',
  }
});

// Recall memories
const result = await client.recall({
  query: 'user preferences',
  limit: 5
});

// Store memory
await client.store({
  content: 'User prefers concise responses',
  memory_type: 'preference'
});

// Compact context
await client.compact({
  summary: 'Session summary...'
});

Config Resolution

Config is resolved from multiple sources with priority:

1. Per-IDE config (passed to constructor)
2. Server overrides (fetched from API)
3. Shared local config (~/.memoryai/config.json)
4. Environment variables (HM_ENDPOINT, HM_API_KEY, etc.)
5. Hardcoded defaults

// Shared config file: ~/.memoryai/config.json
{
  "endpoint": "https://memoryai.dev",
  "apiKey": "hm_sk_...",
  "contextCap": 1000000,
  "compactAt": 20,
  "criticalAt": 30
}

Offline Mode

The client automatically caches recall results in SQLite. If the server is unreachable, cached results are returned:

const client = new MemoryClient({ enableCache: true });

// First call - hits server and caches result
const result1 = await client.recall({ query: 'test' });
console.log(result1.cached); // false

// Second call - returns cached result
const result2 = await client.recall({ query: 'test' });
console.log(result2.cached); // true

// Clean old cache entries (older than 24h)
client.cleanCache(86400000);

Health Check

const health = await client.health();
console.log(health.online); // true/false
console.log(health.latency_ms); // 123

API

MemoryClient

Main client class.

Constructor:

new MemoryClient(options?: MemoryClientOptions)

Methods:

• recall(options: RecallOptions): Promise<RecallResult>
• store(options: StoreOptions): Promise<{ id: string }>
• compact(options: CompactOptions): Promise<void>
• health(): Promise<HealthStatus>
• updateConfig(updates: Partial<MemoryAIConfig>): void
• getConfig(): MemoryAIConfig
• cleanCache(maxAgeMs?: number): number
• getCacheStats(): { memories: number; queries: number; size_bytes: number } | null
• clearCache(): void
• close(): void

Config Utilities

import { resolveConfig, readSharedConfig, writeSharedConfig, validateConfig } from '@memoryai/core';

// Read shared config
const config = readSharedConfig();

// Write shared config
writeSharedConfig({
  endpoint: 'https://memoryai.dev',
  apiKey: 'hm_sk_...'
});

// Validate config
const errors = validateConfig(config);

Architecture

Used by:

• memoryai-mcp - MCP server for Claude Desktop, VS Code, etc.
• memoryai-claude - HTTP hooks for Claude Code CLI

License

MIT