Storage, search & the knowledge graph

Memory is three layers, not one bucket: durable storage, ranked search, and a knowledge-graph layer that turns turns into entities and facts. Each is pluggable, and the right backend is chosen by your install profile.

Storage

The bottom layer just durably holds entries. The backend depends on the profile: an in-memory or SQLite store for local and Desktop, a Postgres-backed store for durable clusters (with a shadow mode that dual-writes while you migrate). The layer above never cares which — it's an interface.

Two kinds of recall: query vs. search

Recall comes in two flavors, and they answer different questions:

query is boolean filtering — "everything tagged incident, written in the last day." Exact, structured, no scoring.
search is scoring — "what's most relevant to this?" It fuses structured filters, full-text search, and vector similarity, then re-ranks the merged results.

Search fans out to every configured provider concurrently, merges their results with reciprocal-rank fusion, and post-filters through the same authorization graph as everything else — so a result you're not allowed to see never makes it back.

The knowledge graph

On top of storage and search sits an optional knowledge-graph layer. As turns complete, it extracts entities and facts, deduplicates them, and notices contradictions — building a graph you can traverse ("what facts do we know about this entity? what's related?") rather than just a pile of text.

Reaching it

Agents get three tools — query_memory, search_memory, and query_knowledge — and you get matching CLI commands:

oap memory search <session> --text "…"    # ranked retrieval
oap memory query  <session> [filters]      # structured recall
oap kg search      <session> --text "…"    # graph-aware facts
oap kg related     <session> --entity <id> # neighbors in the graph