Agent-scoped memory
Store durable memories with tenant, namespace, user, session, agent, type, content, metadata JSON, token count, importance, TTL, pinned status, access count, and timestamps.
Features
ZeptoDB has two cooperating layers: a microsecond time-series engine for live operational facts, and an Agent Memory layer for the context agents need to decide, reuse, and explain.
Agent Memory layer
Section titled “Agent Memory layer”Client-supplied embeddings
Applications provide float32 embeddings. ZeptoDB stores, validates, filters, and ranks them without calling embedding providers or LLMs from the server.
Context assembly
Retrieve top-K memories under a token budget, deduplicate repeated content, and rank by semantic similarity, importance, pinned boost, recency, and access count.
Exact + semantic cache
Check normalized prompt matches and embedding-similar responses before calling an external model provider. Useful for repeated operational questions.
Sidecar snapshots
Persist memory records and vectors to records.bin and vectors.bin, with WAL replay, snapshot latency/failure metrics, sidecar byte gauges, and stop-time force flush.
AgentOps telemetry
Track agent runs, retrieval events, cache events, LLM calls, LLM errors, tool calls, context traces, and replay events in ordinary ZeptoDB time-series tables.
Cluster-aware memory
Routed writes, point reads, fan-out search/context, semantic-cache fan-out, replica WAL policy, failover status, and cluster-scoped stats are available for multi-node deployments.
Retention controls
Tenant quotas, TTL/capacity eviction, pinned-memory protection, eviction tombstones, and rollback of failed durability side effects keep memory shards bounded and replayable.
ANN options
Exact scan remains the default. Optional sparse projection, HNSW, and dependency-free IVF candidate indexes expose rebuild, fallback, memory, and tombstone metrics.
Time-series engine
Section titled “Time-series engine”5.52M events/sec
Lock-free MPMC ring buffer with Highway SIMD batch copy. Zero allocation on the hot path for telemetry, ticks, traces, tool calls, and sensor streams.
272μs query on 1M rows
LLVM JIT compiled execution and SIMD aggregation for live facts the agent must retrieve before acting.
ASOF JOIN
Point-in-time correct joins across heterogeneous streams. Foundational for sensor fusion, market data, incidents, and agent action replay.
Window JOIN
Join within a time window for sensor clock drift, event correlation, tool-call timelines, and trade/quote alignment.
Temporal analytics
EMA, VWAP, xbar, mavg, percentile, spatial distance predicates, GROUP BY, window functions, CTEs, and subqueries in standard SQL.
Standard SQL
Analysts, quants, ML engineers, and platform teams can query the live timeline without learning a proprietary DSL.
Ingestion and connectors
Section titled “Ingestion and connectors”ROS 2 bridge
Optional Ros2Consumer support for live scalar topics, standard profiles, typed profile tables, connector metrics, typed-row cluster forwarding, and rosbag2 import/replay.
Arrow IPC ingest
POST /insert/arrow ingests Arrow RecordBatchStream payloads through the table-aware tick path for DataFrame, Polars, PyArrow, and batched clients.
MessagePack ingest
POST /insert/msgpack provides a compact binary map-of-column-arrays format for embedded and Telegraf-style clients.
Telegraf / Kinesis
Telegraf outputs.execd and optional AWS Kinesis consumer support broaden pipeline ingestion without adding a bespoke source per sensor or stream.
Kafka and market feeds
Kafka batch ingestion plus native FIX, ITCH, and Binance feed handlers for high-throughput event streams.
MQTT / OPC-UA
Lightweight robot telemetry plus OPC-UA scalar, array, string, structured, history, alarms, browse, and server-mode surfaces.
Arrow and Parquet
Arrow Flight for batch transfer and Parquet HDB on S3, GCS, or NFS for replayable historical data.
How the layers work together
Section titled “How the layers work together”| Need | Time-series core | Agent Memory layer |
|---|---|---|
| Live observations | Ingest sensors, ticks, traces, logs, tool calls | Store what the agent learned from them |
| Temporal recall | Query by timestamp, entity, window, ASOF relation | Retrieve prior episodes, summaries, and decisions |
| Grounding | Keep raw evidence and exact event order | Assemble relevant context under a token budget |
| Provider cost control | Store cache telemetry as events | Exact and semantic prompt cache lookup |
| Debugging | Replay the event timeline | Replay retrieved context, model calls, and agent decisions |
Storage
Section titled “Storage”| Feature | Description |
|---|---|
| In-memory column store | Columnar layout optimized for SIMD scan and aggregation |
| Arena allocator | Custom memory management with no malloc on the hot path |
| Partition manager | Symbol and table scoped partitioning for locality and parallelism |
| Parquet HDB | Historical database on S3 / GCS / NFS. Hot + cold in one query |
| Agent Memory sidecar | records.bin for scalar metadata and vectors.bin for row-major float32 embeddings |
| Compression | LZ4 for WAL, Parquet columnar compression for HDB |
Client APIs
Section titled “Client APIs”| API | Typical use |
|---|---|
| Python zero-copy | ML pipelines, notebooks, agent loops, quant research |
Python connection.memory | Put/search memories and assemble context |
Python connection.cache | Store and lookup exact/semantic prompt cache entries |
| HTTP REST | SQL queries plus /api/ai/* memory and cache endpoints |
| HTTP Arrow IPC ingest | Batched DataFrame / Arrow RecordBatchStream ingestion via POST /insert/arrow |
| HTTP MessagePack ingest | Dependency-light binary columnar ingestion via POST /insert/msgpack |
| C++ API | Embedded low-latency applications and custom services |
C++ Ros2Consumer | ROS 2 scalar, standard-profile, typed-profile, and rosbag2 ingest |
C++ OpcUaConsumer / OpcUaServer | Industrial OPC-UA ingestion, history reads, alarm events, browse discovery, and server publication |
C++ KinesisConsumer | AWS Kinesis stream polling, decoding, and table-aware routing |
Telegraf outputs.execd | Influx line protocol to ZeptoDB HTTP batches |
| Arrow Flight | Batch data transfer and distributed training |
| SQL CLI | Ad-hoc queries, operations, debugging |
Security and isolation
Section titled “Security and isolation”- Tenant, namespace, quota, TTL, and pinned-retention controls on memory and cache entries
- Optional
X-Zepto-Tenant-Idrequest header with conflict rejection - Memory content, prompts, responses, and metadata omitted from aggregate stats
- TLS 1.3 with optional mTLS on endpoints and cluster RPC
- RBAC with 5 built-in roles: admin, writer, reader, analyst, monitor
- JWT / OIDC authentication and API key management
- Audit logging for auth events, queries, and admin actions
Operations note: Agent Memory exposes local and cluster-scoped stats. Multi-node memory routing is available for routed writes, point reads, fan-out search/context, semantic-cache fallback, replica WAL durability, and owner-failover status. Shard migration dual-write/catch-up remains future work.
See the Security Operations Guide for configuration.
Clustering
Section titled “Clustering”- Multi-node time-series storage with automatic sharding by symbol
- Consistent hashing for partition placement
- Health monitoring and automatic failover
- Rolling upgrades with zero downtime
- Cross-node time-series query routing and aggregation
- Cluster-scoped Agent Memory stats and routed memory/cache operations
Multi-node time-series clustering and multi-node Agent Memory guidance are advanced deployment surfaces. Validate them against your durability, failover, and operator-review policy before relying on them.
See Multi-Node Cluster for setup.
Deployment
Section titled “Deployment”- Docker for local development, CI, and Agent Memory pilots
- Kubernetes / Helm for clustered time-series deployments
- Agent Memory cluster stats, routed operations, and deterministic owner-failover validation for multi-node pilots
- ROS 2 Jazzy smoke path and edge deployment guide for connector validation on development hosts, CI workers, and robot-lab edge nodes
- Bare metal with NUMA / CPU pinning optimization
- ARM Graviton for cost-efficient edge and cloud
- Parquet HDB on S3, GCS, or local NFS
See Production Deployment for reference architectures.