Metadata-Version: 2.3
Name: tikuu-memory
Version: 0.2.0
Summary: Tikuu memory SDK: HTTP client and LangGraph snapshot checkpointer
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` (`TikuuMemorySaver`).

## Requirements

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

## Install

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

## Env (required)

| Variable | Meaning |
| --- | --- |
| `TIKUU_MEMORY_SERVICE_URL` | Memory service base URL (no trailing slash) |
| `TIKUU_AGENT_ID` | Agent UUID used as the storage partition |
| `TIKUU_SESSION_TOKEN` | Session JWT (platform) or developer JWT (`tikuu run`) |

`TikuuMemorySaver.from_env()` / `TikuuMemoryClient.from_env()` raise
`MemoryConfigurationError` if any required value is missing or blank.

Inside Docker agent containers, tikuu-api-gateway injects all three. For local
`tikuu run`, the CLI injects `TIKUU_SESSION_TOKEN` from `~/.tikuu/credentials.json`.
The client sends it as `X-Tikuu-Session-Token` on every request.

## Usage

```python
from tikuu_memory import TikuuMemorySaver

checkpointer = TikuuMemorySaver.from_env()
# pass checkpointer into create_agent(..., checkpointer=checkpointer)

config = {"configurable": {"thread_id": session_id}}
```

The CLI template sets `thread_id` to the Tikuu `X-Session-Id`. The saver
never forces that mapping; any `thread_id` string is accepted.

Storage key: `(agent_id, thread_id, checkpoint_ns)`.

## 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 user code.

## V1 limitations

- **Snapshot-only** storage (intentional).
- **`put_writes` is a no-op** so LangGraph does not crash; interrupt/resume
  and mid-step crash recovery are not supported yet.
- Metadata `filter` on `list` is ignored.

## Deferred work

- **TODO(writes):** Persist pending writes for interrupt/resume.
- **TODO(actor_id):** Optional end-user / tenant key.
- **TODO(legacy):** Non-snapshot event-log formats.
- **TODO(serde):** Prefer JSON-only serde if pickle via JsonPlus is undesirable.

## Docs

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