tessera-memory 0.1.2

Long-term memory for LLM agents: the typed, sync and async Python client for the Tessera memory service.

tessera-memory

Long-term memory for LLM agents.

Your agent forgets everything between sessions. Tessera remembers. Write conversational turns, then recall ranked hits or a prompt-ready context block. Sync and async, fully typed.

Getting started · Concepts · API reference · Use with MCP

What you get

🧠 Memory	Extracts facts and episodes from conversation turns. Handles corrections, pinning, and forgetting.
🔍 Search	Ranked, typed retrieval over your memory. No LLM in the loop, so it stays cheap and deterministic.
💬 Query	Composes retrieved memory into a prompt-ready context block for your model.
📚 Procedures	Store reusable lessons (trigger, steps, outcome) and recall them by task.
⚡ Sync + async	The same typed API on Tessera and AsyncTessera.
🔌 MCP built in	Give Claude Code, Codex, and Cursor memory with one server.

Install

pip install tessera-memory   # or: uv add tessera-memory

Requires Python 3.10+.

Quickstart

from tessera_memory import Tessera

client = Tessera()  # reads TESSERA_API_KEY, or Tessera(api_key="tsk_live_...")

# Write what happened.
client.memories.add(content="Ada prefers dark roast coffee.", role="user", user_id="ada")

# Get ranked hits (no LLM)...
hits = client.search(query="what coffee does Ada like?", user_id="ada")

# ...or a prompt-ready context block (may call an LLM server-side).
answer = client.query(query="what coffee does Ada like?", mode="chat", user_id="ada")
print(answer.context)

That is the whole loop: add to remember, search to retrieve, query to get context for a model.

Async

Every method exists on AsyncTessera with await:

import asyncio
from tessera_memory import AsyncTessera


async def main() -> None:
    async with AsyncTessera() as client:
        await client.memories.add(content="Ada prefers dark roast coffee.", role="user", user_id="ada")
        async for item in client.memories.list(user_id="ada"):
            print(item.text)


asyncio.run(main())

Use with MCP (Claude Code, Codex, Cursor)

Give your coding agent memory with the tessera-mcp server. uvx fetches it (and the SDK) on first run, so there's nothing to install. Your key lives in the MCP config, not your shell, so it persists across sessions with no export to re-run.

Claude Code. Register it once with your key:

claude mcp add --env TESSERA_API_KEY=tsk_live_... --env TESSERA_REPO=repo:my-app \
  --scope user tessera -- uvx --from tessera-mcp tessera-mcp

Cursor / Claude Desktop. Add to the MCP config:

{
  "mcpServers": {
    "tessera": {
      "command": "uvx",
      "args": ["--from", "tessera-mcp", "tessera-mcp"],
      "env": { "TESSERA_API_KEY": "tsk_live_...", "TESSERA_REPO": "repo:my-app" }
    }
  }
}

Codex. Add to ~/.codex/config.toml:

[mcp_servers.tessera_memory]
command = "uvx"
args = ["--from", "tessera-mcp", "tessera-mcp"]

[mcp_servers.tessera_memory.env]
TESSERA_API_KEY = "tsk_live_..."
TESSERA_REPO = "repo:my-app"

Want auto-recall hooks and the skill too? Use with MCP covers the all-in-one Claude Code plugin, Cursor, and the privacy notes on transcript consolidation.

Configuration

The client reads TESSERA_API_KEY from the environment, or you pass it directly. Auth goes out as a bearer token. For timeouts, retries, logging, raw responses, and a custom HTTP client, see Configuration.

Documentation

• Getting started: install, connect, first reads and writes.
• Concepts: turns, episodes, facts, procedures, resources.
• Configuration: clients, retries, timeouts, logging, transport.
• Guides: memories · search and query · procedures and resources · error handling
• API reference: the full method surface.

Development

make sync-spec    # copy openapi.json from the server checkout
make generate     # regenerate src/tessera_memory/models.py from openapi.json
make lint         # ruff check + format --check
make typecheck    # mypy --strict
make test         # pytest (respx-mocked)

License

Apache 2.0. See LICENSE.