Memory That Can Be Retrieved—and Changed

Ruflo’s memory layer answers a deceptively difficult question: what should survive after a model finishes a task, and how should that residue influence the next task? This chapter follows information from storage to retrieval, then through auto-memory files, scoped sharing, trajectories, and learned patterns. The practical judgment is not whether Ruflo can remember something, but whether the remembered context is relevant, bounded, inspectable, and still worthy of trust.

Memory is a data plane, not a single database

A useful memory system serves at least two different questions. The first is exact: “Which record has this key, namespace, tag, owner, or date?” The second is semantic: “Which earlier finding is most related to this request, even if the wording differs?” Treating both questions as one search problem either makes exact operations awkward or makes meaning-based retrieval too shallow.

Ruflo’s hybrid design assigns these jobs to different paths. Structured queries such as exact keys, prefixes, and filters are routed toward SQLite. Semantic queries use AgentDB and vector similarity. A hybrid query can run both paths and combine the results. With dual-write enabled, a memory entry is placed in both backends so the system can use structured durability and semantic retrieval without asking one index to perform the other’s job.

That split has a direct consequence for an operator. “Stored” does not mean “searchable in every mode.” An entry may exist in the structured store but lack an embedding. A vector search may return a relevant candidate that fails a namespace or tag filter. A hybrid result may prefer semantic matches and then add structured matches that were not already present. Health reporting can say whether storage or indexing is degraded, but it cannot decide whether the content itself is accurate.

The public API tries to hide unnecessary backend differences. The canonical memory service exposes store, query, search, semantic search, persistence, and consolidation operations; the older unified service name remains as an alias for compatibility. The factory can create a service backed by a real hybrid configuration, while lower-level factories and older package generations may choose AgentDB, RVF, SQLite, sql.js, or JSON. In current code, the automatic provider selector can choose the always-available pure-TypeScript RVF path before native alternatives. The phrase “Ruflo memory” therefore identifies a family of contracts, not one invariant storage engine.

That flexibility is valuable across machines and installations. A native database may offer throughput where its dependency is available; sql.js or JSON can keep an installation usable where native compilation is unavailable; RVF can provide a portable binary representation. The trade-off is that portability can change performance and retrieval behavior. A fallback that preserves the ability to store and search is not automatically equivalent to the fastest or most feature-rich path.

Retrieval is a pipeline of compromises

Vector search begins with an embedding: a numerical representation of content. Ruflo’s HNSW index organizes vectors into layers so a query can navigate a small neighborhood rather than compare every stored item.