API reference

Memory class

Constructor

MemoryConfig | None

A MemoryConfig Pydantic model. If None, uses MemoryConfig() defaults.

str

default:"default-agent"

Unique agent identifier. Memory is namespaced by agent_id.

str | None

default:"None"

Session ID. If None, generates a new UUID. Used to track session-level memory.

Embedder | None

default:"None"

Custom embedder (for advanced use — usually auto-configured).

VectorBackend | None

default:"None"

Custom vector backend (for advanced use — usually auto-configured).

StorageBackend | None

default:"None"

Custom storage backend (for advanced use — usually auto-configured).

remember()

Write to all three memory layers in one call.

result = await mem.remember(
    "User prefers async Python",
    importance=0.7,
    source="conversation",
    event=EpisodeEvent.USER_MESSAGE,
    metadata={"context": "debugging session"}
)

str

required

Memory content (1–8000 characters).

float

default:"0.5"

Importance score (0.0–1.0). Higher = more likely to be recalled.

str | None

Optional source identifier (e.g., “user_input”, “tool_output”).

EpisodeEvent

default:"EpisodeEvent.AGENT_RESPONSE"

Event type for episodic record.

str | None

Tool name if this memory came from a tool call.

dict[str, Any] | None

Custom metadata dictionary.

dict

{
  "working": WorkingEntry,
  "working_entry": WorkingEntry,  # alias
  "episodic": Episode,
  "episode": Episode,  # alias
  "facts": []  # empty — extracted asynchronously
}

recall()

Search across all three layers and return ranked results.

result = await mem.recall("Python frameworks", top_k=10)
for r in result.results:
    print(f"{r.layer.value}: {r.content} (score: {r.score:.2f})")

str

required

Search query (1–500 characters).

int

default:"10"

Maximum results to return (1–100).

list[MemoryLayer] | None

Filter to specific layers. Defaults to all three.

RecallResult

Results object with:

results: list of RankedMemory ranked by composite score
total_found: total matches before ranking
cache_hit: whether result came from semantic cache
latency_ms: query time in milliseconds

context_for()

Build a token-budgeted context string for prompt injection.

ctx = await mem.context_for("user preferences", token_budget=500)
prompt = f"Context:\n{ctx.content}\n\nQuestion: ..."

str

required

Search query.

int | None

Maximum tokens (default from config: 2048). Memories are included until budget is reached.

list[MemoryLayer] | None

Filter to specific layers.

ContextResult

content: Formatted string ready for injection
token_count: Actual tokens used
token_budget: Budget provided
memories_used: Number of results included
cache_hit: Whether result came from cache

flush()

End current session and flush working memory to episodic.

episodes = await mem.flush()  # Returns list[Episode]

list[Episode]

Episodic records created from flushed working entries.

close()

Close database connections and cleanup.

await mem.close()

Layer access

All three layers are available as direct attributes:

await mem.working.add(entry)
await mem.episodic.record(episode)
await mem.semantic.learn(fact)

working

Direct access to working memory layer.

entries = await mem.working.get_entries(session_id=mem.session_id)
for e in entries:
    print(e.content, e.importance)

episodic

Direct access to episodic memory layer.

episodes = await mem.episodic.search("LangGraph", limit=10)

semantic

Direct access to semantic memory (knowledge graph).

facts = await mem.semantic.find(
    subject="user",
    predicates=[FactRelation.PREFERS]
)

Fact

Semantic memory triple: subject–predicate–object.

str

required

Agent that stored this fact.

str

required

Subject (1–500 characters).

FactRelation

required

Relationship type.

str

required

Object (1–2000 characters).

float

default:"0.8"

Confidence score (0.0–1.0).

float

default:"0.5"

Importance score (0.0–1.0).

str | None

Optional user identifier for multi-user agents.

dict[str, Any]

Custom metadata.

FactRelation enum

See Memory layers for complete list and descriptions. Values: PREFERS, DISLIKES, IS, IS_A, HAS, HAS_PROPERTY, KNOWS, USES, WORKS_ON, LOCATED_IN, BELONGS_TO, RELATED_TO, REQUIRES, LEARNED_FROM, CUSTOM

MemoryConfig

Configuration class (Pydantic BaseSettings). All fields support PLYRA_* environment variables.

str

default:"all-MiniLM-L6-v2"

Embedding model name (from sentence-transformers).

int

default:"384"

Embedding dimensionality.

str

default:"~/.plyra/memory.db"

SQLite database path. Expands ~ to home directory.

str

default:"~/.plyra/memory.index"

ChromaDB vectors path.

int

default:"2048"

Default token budget for context_for().

float

default:"0.5"

Weight for similarity in composite score (0.0–1.0).

float

default:"0.3"

Weight for recency in composite score (0.0–1.0).

float

default:"0.2"

Weight for importance in composite score (0.0–1.0).

bool

default:"true"

Enable semantic cache for recall results.

float

default:"0.92"

Similarity threshold for cache hits (0.0–1.0).

int

default:"1000"

Maximum cached queries.

bool

default:"true"

Enable episodic summarization.

bool

default:"true"

Enable automatic fact promotion from episodic to semantic.

str | None

Groq API key for LLM-based fact extraction (preferred).

str | None

Anthropic API key for LLM-based fact extraction.

str | None

OpenAI API key for LLM-based fact extraction.

MemoryLayer enum

Values: WORKING, EPISODIC, SEMANTIC

Environment variables

All configuration can be set via PLYRA_* env vars:

Variable	Type	Default
`PLYRA_EMBED_MODEL`	str	all-MiniLM-L6-v2
`PLYRA_EMBED_DIM`	int	384
`PLYRA_STORE_URL`	str	~/.plyra/memory.db
`PLYRA_VECTORS_URL`	str	~/.plyra/memory.index
`PLYRA_DEFAULT_TOKEN_BUDGET`	int	2048
`PLYRA_SIMILARITY_WEIGHT`	float	0.5
`PLYRA_RECENCY_WEIGHT`	float	0.3
`PLYRA_IMPORTANCE_WEIGHT`	float	0.2
`PLYRA_CACHE_ENABLED`	bool	true
`PLYRA_CACHE_SIMILARITY_THRESHOLD`	float	0.92
`PLYRA_SUMMARIZE_ENABLED`	bool	true
`PLYRA_GROQ_API_KEY`	str	—
`PLYRA_ANTHROPIC_API_KEY`	str	—
`PLYRA_OPENAI_API_KEY`	str	—
`PLYRA_SERVER_URL`	str	—
`PLYRA_API_KEY`	str	—

Getting started

Core concepts

Integrations

Reference

API reference

Memory class

Constructor

remember()

recall()

context_for()

flush()

close()

Layer access

working

episodic

semantic

Fact

FactRelation enum

MemoryConfig

MemoryLayer enum

Environment variables

​Memory class

​Constructor

​remember()

​recall()

​context_for()

​flush()

​close()

​Layer access

​working

​episodic

​semantic

​Fact

​FactRelation enum

​MemoryConfig

​MemoryLayer enum

​Environment variables

Memory class

Constructor

remember()

recall()

context_for()

flush()

close()

Layer access

working

episodic

semantic

Fact

FactRelation enum

MemoryConfig

MemoryLayer enum

Environment variables