Metadata-Version: 2.4
Name: kizuna-mem
Version: 0.2.0
Summary: Python SDK for Kizuna-Mem temporal graph memory engine
License: MIT
Project-URL: Homepage, https://github.com/jaikoo/kizuna-dream
Project-URL: Repository, https://github.com/jaikoo/kizuna-dream
Project-URL: Documentation, https://github.com/jaikoo/kizuna-dream#readme
Project-URL: Issues, https://github.com/jaikoo/kizuna-dream/issues
Keywords: ai,memory,agent,temporal-graph,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# kizuna-mem

Python SDK for [Kizuna-Mem](https://github.com/kizuna/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

```bash
pip install kizuna-mem
```

## Quick Start

```python
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

```python
# 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](https://github.com/kizuna/kizuna-mem)
- [Architecture Docs](https://github.com/kizuna/kizuna-mem/blob/main/docs/kizuna_mem_architecture.md)
- [License: MIT](https://github.com/kizuna/kizuna-mem/blob/main/LICENSE)
