seizn-memory 0.1.0

Memory middleware for AI NPCs - Python SDK for Seizn

Seizn Python SDK

Python SDK for Seizn, the memory middleware layer for AI NPCs.

Use Seizn to persist what NPCs remember across sessions, shard world state by namespace, and retrieve the right context before each response.

Installation

pip install seizn-memory

Quick Start

from seizn import MemoryType, SeizinClient

client = SeizinClient(api_key="szn_your_api_key")
village = client.namespace("smallgod-village-404")

village.add(
    content="NPC Mira remembers the god flooded the riverbank last spring.",
    memory_type=MemoryType.EXPERIENCE,
    importance=0.9,
    tags=["npc:mira", "event:flood", "faction:river-clan"],
)

village.add(
    content="River Clan distrusts lightning blessings after losing two elders.",
    memory_type=MemoryType.RELATIONSHIP,
    importance=0.8,
    tags=["faction:river-clan", "belief:storm", "god:fear"],
)

results = village.search(
    "Who still fears the flood?",
    tags=["event:flood"],
    limit=5,
)

for result in results:
    print(f"{result.score:.2f} :: {result.memory.content}")

client.close()

What This SDK Covers Today

• add, update, list, search, and delete memories
• namespace-scoped memory flows per game, shard, save slot, or faction
• sync and async clients with typed models
• memory types for facts, preferences, experiences, relationships, and instructions

Suggested NPC Modeling Pattern

Use namespaces to isolate game titles or environments:

• smallgod-prod
• smallgod-staging
• npc-sim-seed-404

Use tags to keep retrieval cheap and precise:

• npc:<npc-id>
• faction:<faction-id>
• event:<event-id>
• family:<lineage-id>
• region:<zone-id>

Recommended memory types:

• fact: stable world facts, roles, biographies
• experience: witnessed events, battles, disasters, blessings
• relationship: trust, fear, grudges, kinship
• instruction: behavior constraints, quest rules, taboo knowledge

Async Usage

import asyncio

from seizn import AsyncSeizinClient, MemoryType


async def main() -> None:
    async with AsyncSeizinClient(api_key="szn_your_api_key") as client:
        sim = client.namespace("npc-sim-seed-404")
        await sim.add(
            content="Blacksmith Toma trusts Mira after she shared food during the winter shortage.",
            memory_type=MemoryType.RELATIONSHIP,
            tags=["npc:toma", "npc:mira", "season:winter"],
        )

        results = await sim.search("Who does Toma trust?", tags=["npc:toma"])
        for result in results:
            print(result.memory.content)


asyncio.run(main())

Environment Variables

Set your API key once:

export SEIZN_API_KEY=szn_your_api_key

Then initialize without passing it directly:

from seizn import SeizinClient

client = SeizinClient()

API Surface

SeizinClient

SeizinClient(
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float = 30.0,
)

Methods:

• add(content, **options)
• search(query, **options)
• get(memory_id)
• update(memory_id, **options)
• delete(memory_id)
• list(**options)
• namespace(name)
• close()

AsyncSeizinClient

The async client mirrors the same methods with await.

Error Handling

from seizn import AuthenticationError, NotFoundError, RateLimitError, SeizinClient

client = SeizinClient(api_key="szn_your_api_key")

try:
    client.get("mem_missing")
except AuthenticationError as exc:
    print(f"Auth failed: {exc.message}")
except NotFoundError as exc:
    print(f"Missing memory: {exc.message}")
except RateLimitError as exc:
    print(f"Retry after {exc.retry_after}s")

Development

pip install -e ".[dev]"
pytest
mypy src/seizn
ruff check src tests

Links

• Homepage: https://www.seizn.com
• Documentation: https://www.seizn.com/docs
• API reference: https://www.seizn.com/docs/api-reference
• Seizn app: https://www.seizn.com

License

MIT License. See LICENSE.