Tellodb Python SDK

The official Python client for Tellodb, the cognitive memory engine for AI agents with fact supersession, knowledge graphs, and temporal truth retrieval.

This SDK wraps both the local-first Rust memory engine sidecar and the hosted/remote HTTP API under the exact same interface, ensuring a seamless development loop from local testing to cloud deployment.

---

Core Features

• Fact Supersession & Conflict Resolution: Automatically manages evolving facts. When a new memory conflicts with an old one (e.g. "I moved to Seattle" superseding "I live in Austin"), the engine invalidates the old memory, resolving conflict and preventing hallucinations.
• Hybrid Vector & Lexical Retrieval: Unifies HNSW semantic vector embeddings, BM25 full-text keyword matching, and neural rerankers for high-precision recall.
• Temporal Querying & Decay: Apply time-aware relevance decay (freshness biasing) or query specific time windows to answer what was true at a specific moment.
• Knowledge Graph Memories: Store memories alongside entity relations (subject ➔ relation ➔ object) and run walking traversals to fetch context networks.
• Zero-Dependency Local Engine: The SDK can download, resolve, run, and manage a local Rust memory engine sidecar binary. Run memory completely privately on your local machine.

---

Installation

pip install tellodb

---

Client Connection

Initialize one client per process and reuse it across requests to optimize connection pooling.

1. Local-First Development Flow

In local-first mode, the SDK handles the lifecycle of the Rust sidecar engine binary.

from tellodb import TellodbClient

# Automatically resolves, downloads, and runs the Rust engine binary on startup
client = TellodbClient.from_local(
    auto_start=True,
    port=3000,
    data_dir="~/.tellodb/data",
)

2. Cloud Flow

Connect to the hosted Tellodb cloud platform or a self-hosted remote instance.

from tellodb import TellodbClient

client = TellodbClient.from_cloud(
    base_url="https://engine.tellodb.com",
    api_key="your_tellodb_api_key",
)

---

Usage Guide & Code Examples

1. Ingestion & Semantic Query

Store a natural language observation and search it semantically.

# Ingest memory
client.ingest(
    entity_id="user-123",
    text="I prefer pour-over coffee to espresso.",
)

# Retrieve context with semantic query
hits = client.query(
    query="What kind of coffee do I like?",
    entity_id="user-123",
    top_k=5,
    rerank=True,
)

for hit in hits:
    print(f"[{hit.similarity:.3f}] {hit.textual_content} (ID: {hit.memory_id})")

2. Knowledge Graph & Relation Mapping

Store facts associated with semantic relations and traverse the memory graph.

# Ingest memory with explicit graph relations
client.ingest(
    entity_id="user-123",
    text="Alice works at Tellodb.",
    relations=[("Alice", "works_at", "Tellodb")]
)

# Query immediate relations of a subject node
graph_res = client.graph_query(
    subject="Alice",
    edge_type="works_at",
)
print("Relations:", graph_res)

# Traverse the memory graph with a deep walk
walk_res = client.graph_walk(
    node="Alice",
    direction="out",
    depth=2,
    limit=20,
)
print("Walk Path:", walk_res)

# Export subgraph for custom visualizations
subgraph = client.export_graph(
    seed="Alice",
    max_nodes=50,
)

3. Temporal Queries

Enforce strict Unix millisecond boundaries to retrieve memories from a specific time window.

# Find what was discussed during a specific time interval
window_hits = client.temporal_query(
    entity_id="user-123",
    textual_query="Where did I work?",
    window_start_ms=1700000000000,  # Nov 2023
    window_end_ms=1760000000000,    # Oct 2025
)
print("Windowed memories:", window_hits)

4. Batch Ingestion

For high-throughput data loads, ingest items in batch chunks.

from tellodb import IngestItem

items = [
    IngestItem(
        entity_id="user-123",
        text="I am learning Rust.",
        kind="Skill",
    ),
    IngestItem(
        entity_id="user-123",
        text="I want to build web apps.",
        kind="Goal",
    ),
]

client.ingest_many(items, batch_size=64)

5. Memory Inspection & Self-Repair Deletion

Inspect raw memory state and safely delete nodes while triggering automatic predecessor recovery.

memory_id = "user-123::sdk::example_id"

# Inspect memory details and surrounding context turn-window
details = client.inspect_memory(
    memory_id=memory_id,
    include_turn_window=True,
    turn_window_radius=3,
)
print("Memory detail:", details)

# Delete memory (safely updates slots and heals invalidated facts)
client.delete_memory(
    memory_id=memory_id,
    reason="User requested removal",
)

6. Analytics Querying

Perform deterministic aggregate analytics on metric tags.

analytics = client.analytics_query(
    entity_id="user-123",
    label="coffee_intake",
    start_timestamp_ms=1700000000000,
)
print("Analytics trend:", analytics)

---

Engine Binary Resolution

When calling TellodbClient.from_local(), the engine resolves the path to the local Rust sidecar binary in the following priority order:

1. Explicitly provided binary_path argument.
2. TELLODB_ENGINE_BINARY or TEMPORAL_MEMORY_ENGINE_BINARY environment variables.
3. Repo-local builds: target/release/temporal_memory or target/debug/temporal_memory.
4. Cached binaries in TELLODB_ENGINE_CACHE_DIR.
5. Automatic download from TELLODB_ENGINE_MANIFEST_URL.

---

Environment Configuration

The SDK configures the Rust engine binary using the following variables:

• TEMPORAL_MEMORY_HOST: Network interface host (default: 127.0.0.1).
• TEMPORAL_MEMORY_PORT: Network interface port (default: 3000).
• TEMPORAL_MEMORY_DATA_DIR: Directory where data files are persisted.
• TEMPORAL_MEMORY_API_KEY: API credential key for the local instance.
• TELLODB_API_KEY: API credential key for the remote/cloud client.