Metadata-Version: 2.3
Name: tikuu-memory
Version: 0.1.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 |

`TikuuMemorySaver.from_env()` / `TikuuMemoryClient.from_env()` raise
`MemoryConfigurationError` if either is missing or blank.

Inside Docker agent containers, tikuu-api-server injects both. For host-local
runs use e.g. `http://127.0.0.1:8100`.

## 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.
- No auth headers.

## Deferred work

- **TODO(auth):** Send session token header when API server injects one.
- **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)
