tellodb

The official Node.js / JavaScript client SDK 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

npm 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.

import { TellodbClient } from "tellodb";

// Automatically resolves, downloads, and runs the Rust engine binary on startup
const client = await TellodbClient.fromLocal({
  autoStart: true,
  port: 3000,
  dataDir: "~/.tellodb/data",
});

2. Cloud Flow

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

import { TellodbClient } from "tellodb";

const client = TellodbClient.fromCloud(
  "https://engine.tellodb.com",
  "your_tellodb_api_key"
);

Usage Guide & Code Examples

1. Ingestion & Semantic Query

Store a natural language observation and search it semantically.

// Ingest memory
await client.ingest({
  entityId: "user-123",
  text: "I prefer pour-over coffee to espresso.",
});

// Retrieve context with semantic query
const hits = await client.query("What kind of coffee do I like?", {
  entityId: "user-123",
  topK: 5,
  rerank: true,
});

for (const hit of hits) {
  console.log(`[${hit.similarity.toFixed(3)}] ${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
await client.ingest({
  entityId: "user-123",
  text: "Alice works at Tellodb.",
  relations: [["Alice", "works_at", "Tellodb"]]
});

// Query immediate relations of a subject node
const graphRes = await client.graphQuery({
  subject: "Alice",
  edgeType: "works_at",
});
console.log("Relations:", graphRes);

// Traverse the memory graph with a deep walk
const walkRes = await client.graphWalk({
  node: "Alice",
  direction: "out",
  depth: 2,
  limit: 20,
});
console.log("Walk Path:", walkRes);

// Export subgraph for custom visualizations
const subgraph = await client.exportGraph({
  seed: "Alice",
  maxNodes: 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
const windowHits = await client.temporalQuery({
  entityId: "user-123",
  textual_query: "Where did I work?",
  window_start_ms: 1700000000000,  // Nov 2023
  window_end_ms: 1760000000000,    // Oct 2025
});
console.log("Windowed memories:", windowHits);

4. Batch Ingestion

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

const items = [
  {
    entityId: "user-123",
    text: "I am learning Rust.",
    kind: "Skill",
  },
  {
    entityId: "user-123",
    text: "I want to build web apps.",
    kind: "Goal",
  },
];

await client.ingestMany(items, { batchSize: 64 });

5. Memory Inspection & Self-Repair Deletion

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

const memoryId = "user-123::sdk::example_id";

// Inspect memory details and surrounding context turn-window
const details = await client.inspectMemory({
  memoryId: memoryId,
  includeTurnWindow: true,
  turnWindowRadius: 3,
});
console.log("Memory detail:", details);

// Delete memory (safely updates slots and heals invalidated facts)
await client.deleteMemory({
  memoryId: memoryId,
  reason: "User requested removal",
});

6. Analytics Querying

Perform deterministic aggregate analytics on metric tags.

const analytics = await client.analyticsQuery({
  entityId: "user-123",
  label: "coffee_intake",
  startTimestampMs: 1700000000000,
});
console.log("Analytics trend:", analytics);

Engine Binary Resolution

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

1. Explicitly provided binaryPath option.
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.