Zouroboros Memory

Production-grade persistent memory for AI agents. Hybrid SQLite + vector search, decay classes, episodic memory, cognitive profiles, and MCP server.

Security Scan

The package's code, CLI, and MCP server match the skill description (a local SQLite + vector memory for agents); minor metadata omissions and expected network/native risks warrant user caution.

Purpose & Capability

Name/description align with the code and files: a Node.js package that provides persistent memory (SQLite schema, embeddings, episodic memory, graph, MCP server, CLI). Required binary (node) and npm install are appropriate for this functionality.

Instruction Scope

SKILL.md and README show normal, scoped runtime instructions (npx CLI, start MCP server, init DB, store/search facts). The runtime code will call external services only when vectorEnabled or reranker features are enabled (calls to Ollama endpoints and OpenAI API). The skill also reads/writes a local DB path (~/.zouroboros/memory.db) and can read files for batch import — these are expected for a persistent memory tool but should be noted.

Install Mechanism

Install spec is an npm package (zouroboros-memory) that creates two binaries — expected. It depends on better-sqlite3 (native addon compiled on install), which raises the usual native-build/supply-chain considerations but is proportionate to embedding a local SQLite storage engine.

Credentials

Registry metadata declared no required env vars, but the code/README use several optional env vars (ZO_MEMORY_DB / ZOUROBOROS_MEMORY_DB, OLLAMA_URL, OLLAMA_MODEL, OPENAI_API_KEY, ZO_OPENAI_API_KEY). Those are functionally justified (DB override, enabling embeddings via Ollama, enabling OpenAI reranker) but the metadata omission is an inconsistency. Enabling vector or reranker features will send content to external endpoints (ollama host or api.openai.com), which can leak sensitive data if unintentionally enabled.

Persistence & Privilege

always:false (normal). The package will create and persist a database under the user's file system (default ~/.zouroboros/memory.db) and write migration tables, indices, and embeddings; this is expected and required for a memory skill but is a persistent local footprint the user should accept explicitly.

Assessment

This skill appears to implement what it claims: a local hybrid SQLite + vector memory with CLI and an MCP server. Before installing, consider: - If you enable vector search or reranking, the skill will send text to external services (OLLAMA_URL or OpenAI). Only set these env vars if you trust the destination (prefer a local Ollama instance). - The package writes a database by default to ~/.zouroboros/memory.db — pick and review the DB path if you don't want persistent data in your home directory. - The npm package depends on better-sqlite3 (native addon) which compiles on install — review/build in a controlled environment if you have supply-chain concerns. - Registry metadata did not declare env vars or the config path; this is likely an oversight. Verify the upstream repository and package integrity (check GitHub releases, package contents, and package checksum) before installing into a production agent. - For minimal risk, run the package in a sandboxed environment, avoid setting OPENAI_API_KEY or OLLAMA_URL to public endpoints, and audit network activity the first time the skill runs.

Usage

Install: npm install zouroboros-memory

CLI

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:

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

Programmatic API

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

Tool	Description
memory_store	Store a fact with optional decay class
memory_search	Keyword or hybrid search
memory_episodes	Create/search episodic memories
cognitive_profile	Get/update entity cognitive profiles
memory_graph	Query entity relationship graph
memory_procedures	Query stored workflow procedures
memory_stats	Database statistics
memory_delete	Delete a fact by ID
memory_prune	Remove expired facts

Decay Classes

Class	TTL
permanent	Never expires
long	365 days
medium	90 days (default)
short	30 days