kizuna-mem

Python 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

pip install kizuna-mem

Quick Start

import asyncio
from kizuna_mem import KizunaMem

async def main():
    async with KizunaMem(
        endpoint="http://localhost:8080",
        api_key="your-api-key",
        tenant_id=1,
    ) as mem:
        # Observe a conversation turn
        episode_id = await mem.observe(
            speaker="user",
            text="I just moved to Tokyo for the new job at Anthropic.",
        )
        print(f"Stored episode: {episode_id}")

        # Retrieve relevant context for a query
        result = await mem.retrieve(
            query="Where does the user live?",
            top_k=5,
        )

        if result.context_found:
            print(f"Context: {result.assembled_context}")
            for node in result.nodes:
                print(f"  [{node.kind}] {node.text} (score: {node.score:.3f})")

asyncio.run(main())

Features

• Observe conversations and events into a temporal knowledge graph
• Retrieve context using spreading activation (multi-hop graph traversal) or static fusion
• Profiles -- access consolidated user traits and preferences
• Multi-tenant isolation with with_tenant()
• GDPR -- forget_entity() and forget_tenant() for right-to-erasure compliance
• Export/Import -- full data portability in JSON-LD format
• Async-first -- built on httpx with native async/await

Retrieval Modes

# Default: static fusion (BM25 + vector + temporal)
result = await mem.retrieve(query="billing issues")

# Spreading activation: multi-hop graph traversal
result = await mem.retrieve(
    query="billing issues",
    retrieval_mode="spreading_activation",
)

Requirements

• Python 3.10+
• A running Kizuna-Mem server

Links

• Main Repository
• Architecture Docs
• License: MIT