@kizuna-mem/sdk

TypeScript SDK for Kizuna-Mem -- a temporal graph-based memory engine for AI agents.

Kizuna-Mem replaces stateless per-request context with an evolving knowledge graph that remembers, consolidates, and retrieves relevant context using spreading activation rather than naive vector similarity.

Installation

npm install @kizuna-mem/sdk
# or
bun add @kizuna-mem/sdk

Quick Start

import { KizunaMem } from "@kizuna-mem/sdk";

const mem = new KizunaMem({
  endpoint: "http://localhost:8080",
  apiKey: "your-api-key",
  tenantId: 1,
});

// Observe a conversation turn
const episodeId = await mem.observe({
  speaker: "user",
  text: "I just moved to Tokyo for the new job at Anthropic.",
});
console.log(`Stored episode: ${episodeId}`);

// Retrieve relevant context for a query
const result = await mem.retrieve({
  query: "Where does the user live?",
  topK: 5,
});

if (result.contextFound) {
  console.log(`Context: ${result.assembledContext}`);
  for (const node of result.nodes) {
    console.log(`  [${node.kind}] ${node.text} (score: ${node.score.toFixed(3)})`);
  }
}

Features

• Observe conversations and events into a temporal knowledge graph
• Retrieve context using spreading activation or static fusion
• Profiles -- access consolidated user traits and preferences
• Multi-tenant isolation with withTenant()
• GDPR -- forgetEntity() and forgetTenant() for right-to-erasure compliance
• Export/Import -- full data portability in JSON-LD format
• ESM-first -- native ES modules with full TypeScript types

Retrieval Modes

// Default: static fusion (BM25 + vector + temporal)
const result = await mem.retrieve({ query: "billing issues" });

// Spreading activation: multi-hop graph traversal
const result = await mem.retrieve({
  query: "billing issues",
  retrievalMode: "spreading_activation",
});

Requirements

• Node.js 18+ or Bun
• A running Kizuna-Mem server

Links

• Main Repository
• Architecture Docs
• License: MIT