tikuu-memory

Python SDK for Tikuu short-term memory: HTTP client for tikuu-memory-service and a LangGraph BaseCheckpointSaver (TikuuMemorySaver).

Requirements

• Python 3.13+
• uv
• A running tikuu-memory-service

Install

uv add tikuu-memory

Env (required)

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

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
• Architecture
• End-to-end smoke path