API reference

Memory class

Constructor

config

MemoryConfig | None

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

agent_id

str

default:"default-agent"

Unique agent identifier. Memory is namespaced by agent_id.

session_id

str | None

default:"None"

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

embedder

Embedder | None

default:"None"

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

vectors

VectorBackend | None

default:"None"

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

store

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"}
)

content

str

required

Memory content (1–8000 characters).

importance

float

default:"0.5"

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

source

str | None

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

event

EpisodeEvent

default:"EpisodeEvent.AGENT_RESPONSE"

Event type for episodic record.

tool_name

str | None

Tool name if this memory came from a tool call.

metadata

dict[str, Any] | None

Custom metadata dictionary.

return

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})")

query

str

required

Search query (1–500 characters).

top_k

int

default:"10"

Maximum results to return (1–100).

layers

list[MemoryLayer] | None

Filter to specific layers. Defaults to all three.

return

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: ..."

query

str

required

Search query.

token_budget

int | None

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

layers

list[MemoryLayer] | None

Filter to specific layers.

return

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]

return

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.

agent_id

str

required

Agent that stored this fact.

subject

str

required

Subject (1–500 characters).

predicate

FactRelation

required

Relationship type.

object

str

required

Object (1–2000 characters).

confidence

float

default:"0.8"

Confidence score (0.0–1.0).

importance

float

default:"0.5"

Importance score (0.0–1.0).

user_id

str | None

Optional user identifier for multi-user agents.

metadata

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.

embed_model

str

default:"all-MiniLM-L6-v2"

Embedding model name (from sentence-transformers).

embed_dim

int

default:"384"

Embedding dimensionality.

store_url

str

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

SQLite database path. Expands ~ to home directory.

vectors_url

str

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

ChromaDB vectors path.

default_token_budget

int

default:"2048"

Default token budget for context_for().

default_similarity_weight

float

default:"0.5"

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

default_recency_weight

float

default:"0.3"

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

default_importance_weight

float

default:"0.2"

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

cache_enabled

bool

default:"true"

Enable semantic cache for recall results.

cache_similarity_threshold

float

default:"0.92"

Similarity threshold for cache hits (0.0–1.0).

cache_max_size

int

default:"1000"

Maximum cached queries.

summarize_enabled

bool

default:"true"

Enable episodic summarization.

promotion_check_enabled

bool

default:"true"

Enable automatic fact promotion from episodic to semantic.

groq_api_key

str | None

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

anthropic_api_key

str | None

Anthropic API key for LLM-based fact extraction.

openai_api_key

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

Getting started

Core concepts

Integrations

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