Durable HTTP memory
This page describes the legacy memory routes. Since Rust version 0.2.0, the platform router is the default; legacy routes require explicit configuration and retain their known authorization limitations.
The HTTP episode routes now use the existing RocksDB memory backend through
PersistentAgentMemory. One shared store lives at <data-directory>/agent-memory;
agent IDs are database key components, never filesystem paths. Blocking storage
calls run through Tokio's blocking pool. The default HTTP path does not evict
records through an implicit business quota; retention is separate policy work.
WAL and synchronous writes are enabled for HTTP episode mutations. Startup
returns an error if the memory store cannot open; it does not fall back to RAM.
http_server::create_legacy_router therefore returns qilbee_core::Result<Router>.
Applications embedding the router must handle that error before serving traffic.
Existing endpoint behavior#
POST /memory/{agent}/episodespersists the episode. The bodyagentIdmust match the path. Context, structuredcontent.data, supported property metadata and a valideventTimeare retained. An out-of-range timestamp is rejected.GET /memory/{agent}/episodes/{id}parses a UUID and uses the durable ID index. It can retrieve records older than the most recent 100 episodes. Invalid UUIDs return 400; absent or invalidated records return 404.- Recent reads, existing text queries, statistics and maintenance access the same persistent backend after reopening. Empty namespaces return empty lists or zero statistics without requiring a process-local registry.
DELETE /memory/{agent}removes that agent's stored episodes durably.
For authenticated tenant scopes, conditional updates and stable retry receipts, use the versioned memory API. The legacy POST assigns a new episode ID on each call; do not retry it as though it were idempotent. Data held only in a terminated process's RAM cannot be recovered by enabling durable storage afterward.
Recovery limits#
Persistence does not by itself guarantee recovery from host power loss, filesystem corruption or disk exhaustion. Maintain backups and validate recovery with the storage and deployment configuration you operate. See backup and recovery.