Skip to main content
plyra-memory organises storage into three cognitive layers. Each serves a different purpose and uses different retrieval mechanics.

​
Working memory

The current session scratchpad. Entries live in-memory and are written to SQLite for durability. Fast writes, no vector indexing overhead. 
# Working memory is written automatically by remember()
await mem.remember("User asked about Q3 report")

# Access the layer directly
entries = await mem.working.get_entries(session_id=mem.session_id)
Working memory is flushed to episodic at session end: 
episodes = await mem.flush()  # Returns list[Episode] — one per flushed working entry

​
Episodic memory

The event timeline. Every working memory entry becomes an episodic record when flushed. Stored in SQLite with a ChromaDB vector index for semantic search. Episodic records carry:
  • content — the original text
  • agent_id — which agent stored it
  • session_id — which session it came from
  • timestamp — when it was stored
  • importance — float score (0.0–1.0), influences retrieval ranking
Learn explicit facts directly into episodic: 
from plyra_memory import Episode, EpisodeEvent

await mem.episodic.record(Episode(
    agent_id=mem.agent_id,
    session_id=mem.session_id,
    event=EpisodeEvent.USER_MESSAGE,
    content="User asked about scaling strategies"
))

​
Semantic memory

The knowledge graph. Facts stored as subject–predicate–object triples. Deduplicated automatically — storing the same fact twice has no effect. 
from plyra_memory import Fact, FactRelation

await mem.semantic.learn(Fact(
    agent_id=mem.agent_id,
    subject="user",
    predicate=FactRelation.PREFERS,
    object="async Python"
))

​
FactRelation values

RelationDescription
PREFERSSubject has a preference for the object
DISLIKESSubject dislikes the object
ISSubject is the object (identity)
IS_ASubject is a member of class object (taxonomy)
HASSubject has the object as a property or possession
HAS_PROPERTYSubject has a specific property or attribute
KNOWSSubject is familiar with the object
USESSubject uses or employs the object
WORKS_ONSubject is working on or assigned to the object
LOCATED_INSubject is located at or in the object
BELONGS_TOSubject is a member or part of the object
RELATED_TOSubject is related to the object (general)
REQUIRESSubject requires the object as a dependency
LEARNED_FROMSubject learned something from the object
CUSTOMCustom user-defined relation

​
Layer storage

LayerStructured storeVector index
WorkingSQLite (in-memory first)None
EpisodicSQLiteChromaDB
SemanticSQLiteChromaDB

​
Default paths

~/.plyra/memory.db      # SQLite
~/.plyra/memory.index   # ChromaDB

​
Override via env vars

export PLYRA_STORE_URL=~/.plyra/memory.db
export PLYRA_VECTORS_URL=~/.plyra/memory.index