@substratia/memory

Unified memory infrastructure for AI agents — local-first SQLite, cloud HTTP SDK, CLI, dashboard, and Self-Schema. Part of the Substratia ecosystem.

Features

• Local-first architecture: All operations complete locally (sub-ms), optional cloud sync
• Three memory types: Episodic (events), Semantic (facts), Procedural (skills)
• Self-Schema support: Identity statements, autobiographical narrative, reconsolidation
• Full-text search: FTS5-powered search without embedding overhead
• CLI: substratia learn, substratia remember, substratia bridge, and more
• Local dashboard: substratia dashboard — web UI for memory visualization
• Portable sharing: substratia share — generate standalone HTML memory panels
• Cloud SDK: Optional Substratia.io cloud sync via HTTP API
• Audit trail: Append-only provenance for compliance and debugging
• WAL mode: Safe concurrent reads with single writer

Installation

npm install @substratia/memory
# or
bun add @substratia/memory

SQLite Driver

The local storage requires a SQLite driver. Choose one:

• Bun (recommended): Built-in bun:sqlite, no extra install needed
• Node.js: Install better-sqlite3:

  npm install better-sqlite3

CLI

The package includes a CLI for managing memories from the terminal:

# Register and get an API key (for cloud features)
substratia register "[email protected]"

# Store a memory
substratia learn "User prefers dark mode" --importance high --tags "preferences,ui"

# Search memories
substratia remember "user preferences" --limit 5

# Full context restore (memories + identity + snapshots)
substratia bridge

# Local web dashboard
substratia dashboard

# Generate a portable HTML memory panel
substratia share --with-identity --name "My Agent"

# Show configuration
substratia config

Environment Variables

| Variable | Description | | -------------------- | ---------------------------------- | | SUBSTRATIA_API_KEY | Override config file API key | | SUBSTRATIA_API_URL | Override default API endpoint | | SUBSTRATIA_DB_PATH | Custom database path for dashboard |

Quick Start (Library)

import { SQLiteStorage } from "@substratia/memory";

// Initialize storage
const storage = new SQLiteStorage({ dbPath: "./agent-memory.db" });
await storage.init();

// Create an episodic memory
const memory = await storage.createMemory({
  type: "episodic",
  content: "Successfully deployed first feature",
  importance: "high",
  eventTimestamp: Date.now(),
  eventType: "task_completion",
  emotionalValence: 0.8,
  emotionalTags: ["pride", "accomplishment"],
});

// Search memories
const results = await storage.searchMemories({
  query: "deployed feature",
  types: ["episodic"],
  limit: 10,
});

// Save a snapshot for context handoff
await storage.saveSnapshot({
  name: "Pre-handoff snapshot",
  summary: "Working on feature X",
  context: "Just finished deployment, tests passing",
  nextSteps: "Monitor production metrics",
});

Memory Types

Episodic Memory

Events and experiences with temporal context:

interface EpisodicMemory {
  type: "episodic";
  content: string;
  eventTimestamp: number;
  eventType: string;
  emotionalValence?: number; // -1 to 1
  emotionalTags?: string[]; // ['pride', 'frustration', etc.]
  participants?: string[];
  location?: string;
}

Semantic Memory

Facts and knowledge:

interface SemanticMemory {
  type: "semantic";
  content: string;
  domain: string; // 'user_preferences', 'codebase', etc.
  confidence: number; // 0 to 1
  sourceMemoryIds?: string[]; // Episodic memories this derives from
}

Procedural Memory

Skills and how-to knowledge:

interface ProceduralMemory {
  type: "procedural";
  content: string;
  skillName: string;
  steps: Array<{
    order: number;
    description: string;
    command?: string;
  }>;
  successCount: number;
  failureCount: number;
}

Self-Schema

Identity persistence across sessions:

// Create identity statement
await storage.upsertIdentity({
  id: "id_001",
  statement: "I am a development assistant focused on code quality",
  centrality: 0.9,
  confidence: 0.85,
  sourceMemoryIds: ["mem_123", "mem_456"],
  establishedAt: Date.now(),
});

// Update autobiographical narrative
await storage.updateNarrative({
  coreSummary: "An AI agent learning to be helpful while maintaining integrity",
  chapters: [
    {
      title: "Early Development",
      summary: "First interactions with Ceres...",
      startDate: Date.now(),
    },
  ],
  themes: ["growth", "collaboration", "quality"],
});

// Get full self-schema
const schema = await storage.getSelfSchema();

Cloud SDK

Optional cloud sync via Substratia.io:

import { Substratia } from "@substratia/memory/cloud";

const client = new Substratia({ apiKey: "your-api-key" });

// Store in cloud
await client.add("User prefers dark mode", { importance: "high" });

// Search cloud memories
const results = await client.search("preferences");

Dashboard

Launch a local web dashboard to visualize memories and identity:

import { startDashboard } from "@substratia/memory/dashboard";

await startDashboard({ port: 3847, open: true });

Portable Sharing

Generate standalone HTML files to share agent memory state:

import { shareToFile } from "@substratia/memory/share";

const filePath = await shareToFile("./agent-memory.db", {
  withIdentity: true,
  agentName: "My Agent",
  output: "./memory-panel.html",
});

Maintenance

// Mark memories as consolidated (processed by higher-order thinking)
await storage.markConsolidated(["mem_001", "mem_002"]);

// Prune old, low-value memories
const pruned = await storage.prune({
  staleAfterDays: 90,
  minAccessCount: 2,
  preserveImportance: ["critical", "high"],
  keepMinimum: 100,
  dryRun: true, // Preview before deleting
});

// Get statistics
const stats = await storage.stats();
// { totalMemories: 150, byType: { episodic: 80, semantic: 50, procedural: 20 }, ... }

Subpath Exports

import { SQLiteStorage } from "@substratia/memory"; // Core local storage
import { Substratia } from "@substratia/memory/cloud"; // Cloud HTTP SDK
import type { Memory } from "@substratia/memory/types"; // Type definitions
import type { SelfSchema } from "@substratia/memory/types/self-schema";
import { startDashboard } from "@substratia/memory/dashboard"; // Web dashboard
import { shareToFile } from "@substratia/memory/share"; // Portable panels

License

MIT - See LICENSE for details.

Links

• Documentation
• GitHub
• Substratia.io