Zouroboros Memory

Usage#

Install: npm install zouroboros-memory

CLI#

bash

npx zouroboros-memory --help
npx zouroboros-memory init
npx zouroboros-memory store --entity user --key name --value "Alice" --decay permanent
npx zouroboros-memory search "project preferences" --limit 5
npx zouroboros-memory stats

MCP Server#

Add to your .mcp.json:

json

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": ["zouroboros-memory-mcp", "--db-path", "~/.zouroboros/memory.db"]
    }
  }
}

Programmatic API#

typescript

import { init, storeFact, searchFacts, searchFactsHybrid, getStats } from 'zouroboros-memory';
import type { MemoryConfig } from 'zouroboros-memory';

const config: MemoryConfig = {
  enabled: true,
  dbPath: '~/.zouroboros/memory.db',
  vectorEnabled: false,
  ollamaUrl: 'http://localhost:11434',
  ollamaModel: 'nomic-embed-text',
  autoCapture: false,
  captureIntervalMinutes: 30,
  graphBoost: true,
  hydeExpansion: false,
  decayConfig: { permanent: Infinity, long: 365, medium: 90, short: 30 },
};

init(config);

// Store a fact
await storeFact({ entity: 'user', key: 'preference', value: 'dark mode' }, config);

// Keyword search
const results = searchFacts('dark mode', { limit: 5 });

// Hybrid search (RRF fusion of keyword + vector)
const hybridResults = await searchFactsHybrid('user preferences', config, { limit: 10 });

MCP Tools#

ToolDescriptionmemory_storeStore a fact with optional decay classmemory_searchKeyword or hybrid searchmemory_episodesCreate/search episodic memoriescognitive_profileGet/update entity cognitive profilesmemory_graphQuery entity relationship graphmemory_proceduresQuery stored workflow proceduresmemory_statsDatabase statisticsmemory_deleteDelete a fact by IDmemory_pruneRemove expired facts

Decay Classes#

ClassTTLpermanentNever expireslong365 daysmedium90 days (default)short30 days