Skip to content

Memory

Orqest provides a pluggable memory subsystem for agents to store and recall knowledge across interactions. The MemoryStore protocol defines the interface; LocalMemoryStore provides a SQLite backend with FTS5 full-text search.

Memory Types

Type Purpose Example
semantic Facts and knowledge "Python uses indentation for blocks"
episodic Experiences and events "User asked about quantum computing on 2025-01-15"

MemoryStore Protocol

All memory backends implement this protocol:

from orqest.memory import MemoryStore

# The protocol requires these async methods:
# store(entry) -> str            # persist entry, return id
# recall(query, k, filters) -> list[MemoryEntry]  # retrieve top-k matches
# forget(entry_id) -> None       # remove by id
# update_reliability(entry_id, success) -> None  # adjust reliability
# count() -> int                 # total entries

LocalMemoryStore (SQLite + FTS5)

The default backend uses SQLite with optional FTS5 full-text search:

import asyncio
from orqest.memory import LocalMemoryStore, MemoryEntry, MemoryFilter


async def main():
    store = LocalMemoryStore("~/.orqest/memory.db")

    # Store a memory
    entry = MemoryEntry(
        content="Quantum computers use qubits instead of classical bits",
        memory_type="semantic",
        source_agent="research_agent",
        confidence=0.95,
    )
    entry_id = await store.store(entry)

    # Recall memories matching a query
    results = await store.recall("quantum computing", k=5)
    for r in results:
        print(f"[{r.memory_type}] {r.content} (confidence: {r.confidence})")

    # Filter by type, source, or confidence
    filtered = await store.recall(
        "quantum",
        k=3,
        filters=MemoryFilter(
            memory_type="semantic",
            source_agent="research_agent",
            min_confidence=0.8,
        ),
    )

    # Forget a memory
    await store.forget(entry_id)

    # Clean up
    await store.close()


asyncio.run(main())

LocalMemoryStore attempts to create FTS5 virtual tables on initialization. If FTS5 is unavailable (some SQLite builds omit it), it falls back to LIKE queries. This is transparent -- the API is identical either way.

FTS5 triggers keep the search index in sync with the main table on insert, update, and delete.

Self-Healing Reliability

Memories have a reliability_score (0.0 to 1.0) that decays on failure:

# Mark a memory as unreliable (e.g., agent used it and got wrong answer)
await store.update_reliability(entry_id, success=False)
# reliability_score *= 0.7

# Entries below 0.1 are automatically pruned

Each failure multiplies the score by 0.7. Entries that drop below 0.1 are automatically deleted. Successful usage is a no-op (the score stays where it is).

Best-Effort Operations

All LocalMemoryStore operations are best-effort: errors are logged via loguru at WARNING level and never raised to the caller. This prevents memory subsystem failures from disrupting agent execution.

MemoryEntry

A single unit of stored knowledge:

Field Type Default Description
id str Auto UUID Unique identifier
content str required The memory content
memory_type "semantic", "episodic", or "procedural" "semantic" Classification
source_agent str "unknown" Which agent created this
confidence float 1.0 How confident the agent was (0-1)
embedding list[float] \| None None Vector embedding — computed by the store's embedder if one is configured
metadata dict {} Arbitrary key-value pairs
created_at datetime now Creation timestamp
last_accessed datetime now Last recall timestamp
access_count int 0 Number of times recalled
reliability_score float 1.0 Self-healing reliability (0-1)

Corrigible memory

Entries carry a provenance (user_stated, inferred, observed, verified; default inferred), a superseded_by link and last_verified_at. An inference never overwrites something the user stated, a correction keeps the old version in a chain, and forgetting removes the whole chain.

import asyncio
from orqest.memory import LocalMemoryStore, MemoryEntry, ProvenanceConflict


async def main() -> None:
    store = LocalMemoryStore("/tmp/corrigible-demo.db")
    stated = await store.store(MemoryEntry(content="prefers tea", provenance="user_stated"))
    try:
        await store.supersede(stated, MemoryEntry(content="prefers coffee"))  # inferred
    except ProvenanceConflict:
        print("an inference cannot overwrite a stated fact")
    fixed = await store.supersede(
        stated, MemoryEntry(content="prefers coffee now", provenance="user_stated")
    )
    print([e.content for e in await store.history(fixed)])  # oldest first
    print(await store.forget_all_versions(fixed))  # 2: both versions are gone
    await store.close()


asyncio.run(main())

recall and list_recent hide superseded entries unless MemoryFilter(include_superseded=True) / include_superseded=True is passed, and MemoryFilter(provenance=...) narrows by source. supersede and forget_all_versions raise on failure (KeyError for an unknown id; supersede also raises ValueError when the new entry's id already exists or equals the old one, when it arrives with superseded_by set, or when the old entry is already superseded) instead of the store's usual best-effort logging, since a silently failed correction would break its promise. store() with an existing user-stated id logs a warning and keeps the stated content unless the new entry is user_stated or verified; a rewrite keeps the stored superseded_by. All writes are serialised by a lock, so concurrent coroutines cannot interleave. forget_all_versions removes every version connected to the id, branches included, and takes the words out of the file: the store runs with secure_delete on, so the deleted rows' bytes are zeroed, then the full-text index is rewritten, because its segments would otherwise keep each deleted word until a later merge, and any write-ahead log is truncated. The rewrite takes time in proportion to the index. If it or the truncation fails, the rows stay deleted and a warning says the words may remain. forget, pruning and reliability decay zero the rows but don't rewrite the index, so use forget_all_versions when the words must go. Pruning (prune_expired, reliability decay, forget) respects chains: removing a superseded version repoints its predecessor at its successor, and removing a live head removes its older versions too. CorrigibleMemory is the Protocol for these three methods; MemoryStore is unchanged. Assistant run summaries are stored with provenance="observed".

Opening a database re-creates the full-text triggers (older ones omitted the row id, so deletes never reached the search index) and rebuilds the index once.

MemoryConfig

Configuration for the memory subsystem. PerKindConfig carries the per-kind policy — decay_on_failure / prune_below (reliability), ttl_days (retention), version_on_edit (skill audit trail):

from orqest.memory import LocalMemoryStore, MemoryConfig, PerKindConfig

config = MemoryConfig(
    backend="local",                    # "local" or "supabase"
    local_db_path="~/.orqest/memory.db",
    semantic=PerKindConfig(decay_on_failure=0.7, prune_below=0.1),
    episodic=PerKindConfig(ttl_days=90),          # auto-expire old sessions
    procedural=PerKindConfig(version_on_edit=True),  # keep a skill history
)

store = LocalMemoryStore(config=config)

Embedding-based retrieval

Pass an embedder and semantic recall ranks by cosine similarity over stored vectors instead of FTS5 keyword match. Orqest stays embedding-model-neutral — the consumer brings the embedder (a local sentence-transformers model, an embeddings API, anything):

def embed(text: str) -> list[float]:
    ...  # your embedding model — sync or async

store = LocalMemoryStore(config=config, embedder=embed)

With no embedder, recall falls back to FTS5 / LIKE — unchanged.

Maintenance

await store.prune_expired() deletes entries older than their per-kind ttl_days and returns the count — a manual maintenance call (schedule it yourself; it is not auto-run).

Preview — non-local backend

backend="supabase" and supabase_url / supabase_key are designed seams for a future pgvector backend — accepted but not yet wired. The local backend, per-kind policy, and embedding retrieval are wired.

What's Happening Under the Hood

  1. LocalMemoryStore lazily opens the SQLite database on first operation
  2. Tables and FTS5 indexes are created if they don't exist
  3. recall() uses FTS5 MATCH (or LIKE fallback) and applies filter conditions as SQL WHERE clauses
  4. Each recall updates last_accessed and increments access_count for accessed entries
  5. update_reliability(success=False) multiplies the score by the per-kind decay_on_failure factor (default 0.7) and prunes entries below the per-kind prune_below floor (default 0.1)

Runnable demos