Metadata-Version: 2.3
Name: tikuu-memory
Version: 0.3.0
Summary: Tikuu memory SDK with LangGraph checkpoint integration
Author: Utkarsh Tiwari
Author-email: Utkarsh Tiwari <tiwariutkarsh66@gmail.com>
Requires-Dist: httpx>=0.28.0
Requires-Dist: langgraph>=1.0.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# tikuu-memory

Python SDK for Tikuu short-term memory: HTTP client for
[`tikuu-memory-service`](../tikuu-memory-service/) and a LangGraph
`BaseCheckpointSaver` (`TikuuCheckpointSaver`).

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/)
- A running `tikuu-memory-service`

## Install

```bash
uv add tikuu-memory
```

## Env

| Variable | Required | Meaning |
| --- | --- | --- |
| `TIKUU_MEMORY_ID` | yes* | Memory resource id used in checkpoint URLs |
| `TIKUU_MEMORY_API_KEY` | yes* | Memory resource API key (`tmk_…`) |
| `TIKUU_MEMORY_SERVICE_URL` | no | Memory service base URL (no trailing slash); defaults to `http://127.0.0.1:8092` |

\*Required unless passed to the `TikuuCheckpointSaver` constructor. Missing
required values raise `MemoryConfigurationError`.

Auth on checkpoint requests: `Authorization: Bearer <api_key>` plus
`X-Session-Id` (LangGraph `thread_id`) and `X-Actor-Id`.

`actor_id` is always `configurable["actor_id"]` on the saver. There is no
env default — actor is per end user / request.

## Usage

```python
from tikuu_memory.integrations.langgraph import TikuuCheckpointSaver

# Reads TIKUU_MEMORY_ID / TIKUU_MEMORY_API_KEY from the environment
# (optional TIKUU_MEMORY_SERVICE_URL, else http://127.0.0.1:8092).
checkpointer = TikuuCheckpointSaver()
# or: TikuuCheckpointSaver(memory_id=..., api_key=..., base_url=...)
# pass checkpointer into create_agent(..., checkpointer=checkpointer)

config = {
    "configurable": {
        "thread_id": session_id,  # from context["session_id"]
        "actor_id": actor_id,     # from context["actor_id"]
    }
}
```

The runner exposes both values on every invoke. The saver requires
`configurable.actor_id` and fails loudly if it is missing.

Storage key (service): `(agent_id, actor_id, session_id, checkpoint_ns)` where
`session_id` is the JWT claim (production) or `X-Session-Id` / LangGraph
`thread_id` (local), and `actor_id` is soft-partitioned so reused session ids
cannot cross-read another actor's checkpoints.

`TikuuCheckpointSaver.delete_thread` / `adelete_thread` raise
`NotImplementedError` (thread deletion is not supported).

## Session-id-as-thread-id caveats

When using the Tikuu session UUID as `thread_id`:

- Omitting `X-Session-Id` on a later call mints a new session → new empty thread.
- One session ⇒ one LangGraph thread ⇒ one container `{agent_id}--{session_id}`.
- Concurrent invokes on the same session race (last snapshot wins); use one
  in-flight invoke per session.
- Custom `thread_id` values are allowed in local developer mode; production
  storage uses the session JWT `session_id` claim plus header `actor_id`.

## V1 limitations

- **Snapshot-only** checkpoint storage (intentional); pending writes are a separate table keyed by checkpoint.
- Metadata `filter` on `list` is ignored.

## Human-in-the-loop

`put_writes` persists LangGraph pending writes (including `__interrupt__` / `__resume__`). Resume with the same `thread_id` and `actor_id`:

```python
from langgraph.types import Command

graph.invoke(Command(resume="approve"), config)
```

Writes made inside a node *before* `interrupt()` are discarded by LangGraph
(the node re-runs on resume). Persist needed state in a prior completed node.

## Deferred work

- **TODO(legacy):** Non-snapshot event-log formats.
- **TODO(serde):** Prefer JSON-only serde if pickle via JsonPlus is undesirable.
- **TODO(batch-flush):** Optional single-request checkpoint+writes put.

## Docs

- [Usage](docs/USAGE.md)
- [Architecture](docs/ARCHITECTURE.md)
- [End-to-end smoke path](../docs/MEMORY_SMOKE.md)
