Memory API Reference¶

MemoryManager¶

The unified interface to all four memory types. This is what AgentRunner interacts with — you rarely need to call individual memory stores directly.

`grampus.memory.manager.MemoryManager` ¶

Single facade over working, episodic, semantic, and procedural memory.

All dependencies are injected — no instantiation occurs internally. This is what the orchestration layer talks to.

Parameters:

Name	Type	Description	Default
`working_memory`	`WorkingMemory`	In-session message buffer with auto-summarization.	required
`episodic_memory`	`EpisodicMemory`	Cross-session episodic record store.	required
`semantic_memory`	`SemanticMemory`	Structured fact store with deduplication.	required
`procedural_memory`	`ProceduralMemory`	Learned workflow store.	required
`episodic_retriever`	`EpisodicRetriever`	Hybrid retriever for episodic records.	required
`semantic_retriever`	`SemanticRetriever`	Similarity-based retriever for semantic facts.	required
`consolidation_pipeline`	`ConsolidationPipeline`	LLM-based fact extractor from episodic records.	required
`agent_id`	`str`	Scopes operations to this agent.	required
`provenance_tracker`	`ProvenanceTracker \| None`	Optional tracker that annotates every write with provenance. When `None`, provenance metadata is not attached.	`None`
`memory_validator`	`MemoryValidator \| None`	Optional validator that gates writes through injection detection, size limits, and rate limiting. When `None`, validation is skipped.	`None`
`graph_consolidator`	`SemanticConsolidator \| None`	Optional F3 SemanticConsolidator. When set, the agent's knowledge graph is available for graph-based retrieval.	`None`
`lifecycle_manager`	`LifecycleTierManager \| None`	Optional F3 LifecycleTierManager for access tracking.	`None`
`adaptive_router`	`AdaptiveRetriever \| None`	Optional F3 AdaptiveRetriever. When set, `recall()` routes queries through it instead of calling retrievers directly.	`None`

`remember(content, *, session_id, memory_types=None, source_type=SourceType.LLM_GENERATED, source_id='unknown', **kwargs)` `async` ¶

Persist content into the requested memory types.

The write path is: 1. Create :class:Provenance (if tracker is configured). 2. Validate via :class:MemoryValidator (if configured) — raises :class:MemorySecurityError on rejection. 3. Store into each requested memory type with provenance JSON attached.

Parameters:

Name	Type	Description	Default
`content`	`str`	Text content to store.	required
`session_id`	`str`	Current session identifier (used for episodic records).	required
`memory_types`	`list[str] \| None`	Which stores to write to (`"episodic"`, `"semantic"`). Unknown values are silently ignored. Defaults to `["episodic"]`.	`None`
`source_type`	`SourceType`	Provenance category of the write origin.	`LLM_GENERATED`
`source_id`	`str`	Identifier of the specific source.	`'unknown'`
`**kwargs`	`Any`	Forwarded to the underlying store methods.	`{}`

Raises:

Type	Description
`MemorySecurityError`	When the validator blocks the write.

`recall(query, *, memory_types=None, top_k=5)` `async` ¶

Query memory and return a combined result.

When an AdaptiveRetriever is configured (F3), routes the query through it for optimal structure selection. Falls back to the existing path on any error to guarantee zero behavioral change when router is absent.

Parameters:

Name	Type	Description	Default
`query`	`str`	Free-text query string.	required
`memory_types`	`list[str] \| None`	Which stores to search (`"episodic"`, `"semantic"`). Unknown values are silently ignored. Defaults to `["episodic", "semantic"]`.	`None`
`top_k`	`int`	Maximum records to return from each retriever.	`5`

Returns:

Name	Type	Description
`A`	`MemoryRecallResult`	class:`MemoryRecallResult` with results from each queried store.

`forget(record_id, *, memory_type)` `async` ¶

Delete a record from the specified memory store.

Parameters:

Name	Type	Description	Default
`record_id`	`str`	ID of the record to remove.	required
`memory_type`	`str`	Which store to delete from (`"episodic"` or `"semantic"`).	required

Raises:

Type	Description
`ValueError`	If memory_type is not `"episodic"` or `"semantic"`.

`consolidate()` `async` ¶

Run one consolidation pass: extract semantic facts from episodic records.

Returns:

Name	Type	Description
`A`	`ConsolidationResult`	class:`ConsolidationResult` with extraction statistics.

`add_message(message)` `async` ¶

Add message to the working memory window.

Delegates directly to :meth:WorkingMemory.add.

`get_messages()` `async` ¶

Return the current working memory window.

Delegates directly to :meth:WorkingMemory.get_messages.

Working memory¶

`grampus.memory.working.WorkingMemory` ¶

In-session message buffer with auto-summarization and durable audit log.

Two separate Dapr state keys are maintained: - window — the live, possibly compressed, message list sent to the LLM. - history — append-only full audit log, never compressed or deleted.

Summarization is triggered inside add() when the live window exceeds threshold_fraction * max_tokens. An asyncio.Lock prevents races when the same session receives concurrent messages.

`get_messages()` `async` ¶

Return a copy of the current live window.

`clear()` `async` ¶

Reset the live window without touching the audit log.

Episodic memory¶

`grampus.memory.episodic.EpisodicMemory` ¶

CRUD store for episodic memory records backed by a DaprStateStore.

Key layout (within the agent's namespace): - episodic:{record_id} — individual record - episodic:_index — JSON list of record IDs for this agent

Importance scoring proxy: min(word_count / 200, 1.0) — longer content is treated as more important. Phase 4 consolidation upgrades this with LLM-based extraction.

Parameters:

Name	Type	Description	Default
`state_store`	`Any`	Dapr state store (or duck-typed equivalent).	required
`embedding_service`	`Any`	Service used to generate embedding vectors.	required
`agent_id`	`str`	Scopes all keys to this agent.	required
`vector_store`	`VectorStore \| None`	Optional external vector store adapter. When set, vectors are mirrored there for similarity search. Falls back to pgvector path when `None`.	`None`

`store(content, *, session_id, user_id=None, metadata=None, provenance=None)` `async` ¶

Create and persist a new episodic record.

If the embedding API fails the record is still saved with embedding=None (graceful degradation).

`get(record_id)` `async` ¶

Load a single record by ID. Returns None if not found.

`delete(record_id)` `async` ¶

Remove a record and its ID from the index.

`grampus.memory.retriever.EpisodicRetriever` ¶

Rank episodic records by a weighted combination of recency, semantic similarity, and stored importance score.

Score formula::

score = α·recency + β·similarity + γ·importance
recency = exp(-decay_rate * age_in_days)

Parameters:

Name	Type	Description	Default
`episodic_memory`	`Any`	Source of records to search.	required
`embedding_service`	`Any`	Used to embed the query string.	required
`alpha`	`float`	Recency weight (default 0.4).	`_DEFAULT_ALPHA`
`beta`	`float`	Similarity weight (default 0.4).	`_DEFAULT_BETA`
`gamma`	`float`	Importance weight (default 0.2).	`_DEFAULT_GAMMA`
`decay_rate`	`float`	Exponential decay constant (default 0.01).	`_DEFAULT_DECAY_RATE`

Raises:

Type	Description
`ValueError`	If `alpha + beta + gamma` does not sum to 1.0.

`retrieve(query, *, top_k=5, min_score=0.0)` `async` ¶

Return the top-k records most relevant to query.

Records with no embedding receive similarity_score=0.0 and are still eligible to rank via recency and importance.

Side-effect: update_access is scheduled as a background task for all returned records so it doesn't add latency to the caller.

Semantic memory¶

`grampus.memory.semantic.SemanticMemory` ¶

CRUD store for semantic facts backed by a DaprStateStore.

Key layout (within the agent's namespace): - semantic:{fact_id} — individual fact - semantic:_index — JSON list of fact IDs for this agent

Deduplication: storing a fact whose (subject, predicate) matches an existing fact merges them rather than creating a duplicate. The higher- confidence fact's object_value wins; source_episode_ids are always unioned.

Parameters:

Name	Type	Description	Default
`state_store`	`Any`	A DaprStateStore (or duck-typed equivalent).	required
`agent_id`	`str`	Scopes all keys to this agent.	required
`vector_store`	`VectorStore \| None`	Optional external vector store adapter. When set, fact embeddings are mirrored there for similarity search.	`None`

`grampus.memory.semantic_retriever.SemanticRetriever` ¶

Retrieve semantic facts by subject, predicate, or semantic similarity.

Parameters:

Name	Type	Description	Default
`semantic_memory`	`Any`	Source of SemanticFact records.	required
`embedding_service`	`Any`	Used to embed free-text queries for similarity search.	required

Procedural memory¶

`grampus.memory.procedural.ProceduralMemory` ¶

CRUD store for learned procedures backed by a DaprStateStore.

Key layout (within the agent's namespace): - procedure:{procedure_id} — individual procedure - procedure:_index — JSON list of procedure IDs for this agent

Parameters:

Name	Type	Description	Default
`state_store`	`Any`	A DaprStateStore (or duck-typed equivalent).	required
`agent_id`	`str`	Scopes all keys to this agent.	required

`store(procedure)` `async` ¶

Persist procedure and register it in the index.

Returns the stored procedure unchanged.

`get(procedure_id)` `async` ¶

Load a single procedure by ID. Returns None if not found.

`delete(procedure_id)` `async` ¶

Remove a procedure and its entry from the index.

Consolidation¶

`grampus.memory.consolidation.ConsolidationPipeline` ¶

Scans recent episodic records, extracts facts via LLM, updates semantic memory.

Episodes are processed in batches of batch_size (newest-first). Each processed episode is marked with metadata["consolidated"] = True so subsequent runs skip it.

Parameters:

Name	Type	Description	Default
`episodic_memory`	`Any`	Source of episodic records.	required
`semantic_memory`	`Any`	Destination for extracted facts.	required
`model_client`	`Any`	LLM client for fact extraction.	required
`agent_id`	`str`	Scopes processing to this agent.	required
`batch_size`	`int`	Maximum number of episodes to process per run.	`10`

`run()` `async` ¶

Run one consolidation pass and return a summary.

Memory security¶

`grampus.memory.provenance.ProvenanceTracker` ¶

Creates and verifies :class:Provenance records for memory writes.

Stateless — safe to share across components.

`verify(content, provenance)` ¶

Return True if content matches the hash stored in provenance.

Parameters:

Name	Type	Description	Default
`content`	`str`	Current content of the memory record.	required
`provenance`	`Provenance`	The provenance record to verify against.	required

Returns:

Type	Description
`bool`	True when hashes match (content is unmodified), False otherwise.

`grampus.memory.validator.MemoryValidator` ¶

Pre-write validation pipeline for memory content.

Checks in order: 1. Injection detection — regex match against known prompt-injection patterns. 2. Size check — content byte length vs. max_content_bytes. 3. Rate limit — sliding-window counter per source_id vs. max_writes_per_minute.

All failing checks are collected and returned together so callers see the full picture. A write is blocked if any check fails.

Parameters:

Name	Type	Description	Default
`max_content_bytes`	`int`	Maximum byte length of content (default 10 000).	`10000`
`max_writes_per_minute`	`int`	Maximum write attempts per source_id per 60 s (default 60).	`60`

`validate(content, *, source_id)` ¶

Run all validation checks against content from source_id.

Parameters:

Name	Type	Description	Default
`content`	`str`	Raw text about to be stored.	required
`source_id`	`str`	Identifier of the source requesting the write.	required

Returns:

Name	Type	Description
`A`	`ValidationResult`	class:`ValidationResult` with `allowed=True` when all checks pass.

`grampus.memory.trust.TrustScorer` ¶

Computes a dynamic trust score from provenance, age, and access frequency.

Formula: clamp(base * exp(-decay_rate * age_days) + min(access_count * access_boost, max_boost), 0, 1)

Parameters:

Name	Type	Description	Default
`decay_rate`	`float`	Exponential decay rate per day (higher = faster decay).	`0.01`
`access_boost`	`float`	Per-access increment added to the decayed base.	`0.01`
`max_boost`	`float`	Upper cap on the total access boost term.	`0.2`

`score(provenance, *, access_count, age_days)` ¶

Compute a trust score in [0, 1].

Parameters:

Name	Type	Description	Default
`provenance`	`Provenance`	Source provenance (provides baseline trust level).	required
`access_count`	`int`	Number of times this record has been retrieved.	required
`age_days`	`float`	Age of the record in fractional days.	required

Returns:

Type	Description
`float`	A float in [0.0, 1.0].

`grampus.memory.auditor.MemoryAuditor` ¶

Scans all episodic records and verifies content-hash integrity.

Parameters:

Name	Type	Description	Default
`episodic_memory`	`Any`	Episodic store to audit (must expose `list_all()`).	required
`provenance_tracker`	`ProvenanceTracker`	Used to re-derive expected hashes.	required
`agent_id`	`str`	Agent namespace being audited.	required

`audit()` `async` ¶

Load all episodic records and check each for provenance integrity.

A record is flagged as tampered when its provenance JSON is present but the stored content no longer matches the hash. It is flagged as missing_provenance when the provenance field is None or empty.

Returns:

Name	Type	Description
`An`	`AuditReport`	class:`AuditReport` with counts and the fraction of clean records.

Types¶

`grampus.memory.types.EpisodicRecord` ¶

Bases: BaseModel

A single episodic memory record persisted across sessions.

`grampus.memory.types.SemanticFact` ¶

Bases: BaseModel

A discrete, structured fact extracted from episodic memory.

Stored as a subject-predicate-object triple with a confidence score. Deduplication is performed on (subject, predicate) when storing.

`grampus.memory.types.Procedure` ¶

Bases: BaseModel

A learned, reusable workflow extracted from completed tool-call sequences.

`grampus.memory.types.ProcedureStep` ¶

Bases: BaseModel

A single step within a learned procedure.

SourceType enum¶

The SourceType enum determines the default trust level assigned to a memory write:

Value	Default trust	Description
`SYSTEM`	1.0	Internal framework writes
`USER_INPUT`	0.9	Direct user messages
`LLM_GENERATED`	0.7	Agent's own reasoning output
`TOOL_RESULT`	0.6	Results from tool executions
`EXTERNAL_DATA`	0.3	Data from external APIs, web scraping, etc.

from grampus.memory.provenance import SourceType

await manager.remember(
    "API returned rate limit error.",
    session_id="s1",
    source_type=SourceType.TOOL_RESULT,
    source_id="http_client:call_xyz",
)

MemoryRecallResult¶

Returned by MemoryManager.recall():

@dataclass
class MemoryRecallResult:
    episodic: list[RetrievedRecord]   # scored episodic records
    semantic: list[SemanticFact]      # matching semantic facts
    query: str                        # original query string

RetrievedRecord wraps an EpisodicRecord with its retrieval score:

@dataclass
class RetrievedRecord:
    record: EpisodicRecord
    score: float    # combined recency × similarity × importance score

Memory API Reference¶

MemoryManager¶

grampus.memory.manager.MemoryManager ¶

remember(content, *, session_id, memory_types=None, source_type=SourceType.LLM_GENERATED, source_id='unknown', **kwargs) async ¶

recall(query, *, memory_types=None, top_k=5) async ¶

forget(record_id, *, memory_type) async ¶

consolidate() async ¶

add_message(message) async ¶

get_messages() async ¶

Working memory¶

grampus.memory.working.WorkingMemory ¶

get_messages() async ¶

clear() async ¶

Episodic memory¶

grampus.memory.episodic.EpisodicMemory ¶

store(content, *, session_id, user_id=None, metadata=None, provenance=None) async ¶

get(record_id) async ¶

delete(record_id) async ¶

grampus.memory.retriever.EpisodicRetriever ¶

retrieve(query, *, top_k=5, min_score=0.0) async ¶

Semantic memory¶

grampus.memory.semantic.SemanticMemory ¶

grampus.memory.semantic_retriever.SemanticRetriever ¶

Procedural memory¶

grampus.memory.procedural.ProceduralMemory ¶

store(procedure) async ¶

get(procedure_id) async ¶

delete(procedure_id) async ¶

Consolidation¶

grampus.memory.consolidation.ConsolidationPipeline ¶

run() async ¶

Memory security¶

grampus.memory.provenance.ProvenanceTracker ¶

verify(content, provenance) ¶

grampus.memory.validator.MemoryValidator ¶

validate(content, *, source_id) ¶

grampus.memory.trust.TrustScorer ¶

score(provenance, *, access_count, age_days) ¶

grampus.memory.auditor.MemoryAuditor ¶

audit() async ¶

Types¶

grampus.memory.types.EpisodicRecord ¶

grampus.memory.types.SemanticFact ¶

grampus.memory.types.Procedure ¶

grampus.memory.types.ProcedureStep ¶

SourceType enum¶

MemoryRecallResult¶

`grampus.memory.manager.MemoryManager` ¶

`remember(content, *, session_id, memory_types=None, source_type=SourceType.LLM_GENERATED, source_id='unknown', **kwargs)` `async` ¶

`recall(query, *, memory_types=None, top_k=5)` `async` ¶

`forget(record_id, *, memory_type)` `async` ¶

`consolidate()` `async` ¶

`add_message(message)` `async` ¶

`get_messages()` `async` ¶

`grampus.memory.working.WorkingMemory` ¶

`get_messages()` `async` ¶

`clear()` `async` ¶

`grampus.memory.episodic.EpisodicMemory` ¶

`store(content, *, session_id, user_id=None, metadata=None, provenance=None)` `async` ¶

`get(record_id)` `async` ¶

`delete(record_id)` `async` ¶

`grampus.memory.retriever.EpisodicRetriever` ¶

`retrieve(query, *, top_k=5, min_score=0.0)` `async` ¶

`grampus.memory.semantic.SemanticMemory` ¶

`grampus.memory.semantic_retriever.SemanticRetriever` ¶

`grampus.memory.procedural.ProceduralMemory` ¶

`store(procedure)` `async` ¶

`get(procedure_id)` `async` ¶

`delete(procedure_id)` `async` ¶

`grampus.memory.consolidation.ConsolidationPipeline` ¶

`run()` `async` ¶

`grampus.memory.provenance.ProvenanceTracker` ¶

`verify(content, provenance)` ¶

`grampus.memory.validator.MemoryValidator` ¶

`validate(content, *, source_id)` ¶

`grampus.memory.trust.TrustScorer` ¶

`score(provenance, *, access_count, age_days)` ¶

`grampus.memory.auditor.MemoryAuditor` ¶

`audit()` `async` ¶

`grampus.memory.types.EpisodicRecord` ¶

`grampus.memory.types.SemanticFact` ¶

`grampus.memory.types.Procedure` ¶

`grampus.memory.types.ProcedureStep` ¶