Python SDK API

This page covers the stable, high-value Python surface. Import public types from memorizz unless a guide documents a provider-specific module.

MemAgent

memorizz.memagent.core.MemAgent

MemAgent class that orchestrates manager components.

Attributes

last_tool_outcomes property

Structured outcomes from the most recent turn, in execution order.

Methods:

run(query, memory_id=None, thread_id=None, user_id=None, context=None, tool_context=None, observability_context=None)

Run the agent with the given query using the new manager architecture.

Parameters:

Name	Type	Description	Default
query	str	The user's query	required
memory_id	Optional[str]	Optional memory ID to use (if not provided, uses stored or default)	None
thread_id	Optional[str]	Optional thread ID to use (if not provided, reuses current or creates new)	None
user_id	Optional[str]	Optional end-user identifier for multi-tenant apps. When provided, every memory unit written during this turn is tagged with user_id and every read is restricted to rows matching the same scope. None means anonymous/legacy scope — reads return only rows with no user_id set.	None
context	Optional[Dict[str, Any]]	Optional per-call ephemeral context (M2). When provided, the dict is rendered as a structured system-role message between the main system prompt and conversation history, so the agent sees it for this turn only. It is intentionally NOT persisted to conversation_memory (only the original query is recorded). Recommended shape for SDK consumers:: { "current_page": {"type": "analysis"|"group"|..., "id": "<id>", "title": "<title>"}, "quoted_text": "<optional highlighted snippet>", "highlights": [...], # optional "notes": [...], # optional "internet_search_allowed": True|False, "open_threads": [...], # optional } Callers may pass any JSON-serialisable dict; unknown keys are included verbatim.	None
tool_context	Optional[Dict[str, Any]]	Optional per-call dict made available to tool functions via memorizz.get_tool_context() (M4). Unlike context above, this is NOT sent to the LLM at all — it's stored in a contextvars.ContextVar set before the tool loop and reset when the call returns. Use it for per-request facts the LLM should not see or be required to pass (e.g. {"user_id": "..."} for tenant-scoped tool queries).	None
observability_context	Optional[Dict[str, Any]]	Optional content-free host provenance for the private trace bundle. Only a strict allowlist of routing, ownership, grounding, and fingerprint fields is retained; this dict is never sent to the LLM or conversation history.	None

Returns:

Type	Description
str	The agent's response

run_stream(query, memory_id=None, thread_id=None, user_id=None, context=None, tool_context=None, raise_on_provider_error=False, event_callback=None, observability_context=None)

Run the agent with streaming output, yielding text chunks as they arrive.

This method mirrors run() but yields partial text tokens so callers can display incremental output. It honours the same caching, memory, and tool-calling logic as the synchronous path.

Parameters:

Name	Type	Description	Default
query	str	The user's query	required
memory_id	Optional[str]	Optional memory ID	None
thread_id	Optional[str]	Optional thread ID	None
user_id	Optional[str]	Optional end-user identifier for multi-tenant scoping. See run() for the full semantics.	None
context	Optional[Dict[str, Any]]	Optional per-call ephemeral context (M2). See run() for the full semantics and recommended schema. Not persisted to conversation_memory.	None
tool_context	Optional[Dict[str, Any]]	Optional per-call dict made available to tool functions via memorizz.get_tool_context() (M4). See run() for the full semantics. Not sent to the LLM.	None
raise_on_provider_error	bool	Re-raise LLM/provider API failures after emitting typed terminal events. Defaults to False for compatibility with UI streams that render inline failures.	False
event_callback	Optional[Callable[[Dict[str, Any]], None]]	Optional callback scoped to this stream only. This is concurrency-safe and preferred over mutating a shared agent with set_stream_event_callback immediately before a run.	None
observability_context	Optional[Dict[str, Any]]	Optional content-free host provenance. See run(); the same strict persistence allowlist applies.	None

Yields:

Name	Type	Description
str	str	Partial text chunks of the agent's response

validate_configuration()

Validate configured optional subsystems and return a stable report.

capability_report(*, preflight=False)

Return package and configured-agent feature/provider states.

semantic_cache_stats()

Return real hit/miss/bypass/write/eviction counters and provenance.

inspect_semantic_cache(query, *, thread_id=None, user_id=None, context=None, metadata=None, bypass_reason=None)

Inspect cache provenance/freshness without returning cached content.

invalidate_semantic_cache(*, domains=None, tags=None, data_version=None)

Invalidate semantic cache entries by operational domain or tag.

generate_summaries(days_back=7, max_memories_per_summary=50, *, memory_id=None, user_id=None, thread_id=None)

Generate summaries by compressing memory units from a specified time period.

This method collects memory units from the specified time period, uses an LLM to compress them into emotionally and situationally relevant summaries, and stores them in the summaries collection.

Parameters:

days_back : int, optional Number of days back to include in the summary (default: 7) max_memories_per_summary : int, optional Maximum number of memory units to include in each summary (default: 50) memory_id : str, optional Exact memory scope. When omitted, the configured/current memory IDs are considered for backward compatibility. user_id : str, optional Exact tenant scope. None selects only anonymous/legacy rows; this method never inherits a user from the most recent run. thread_id : str, optional Exact conversation thread. When omitted, all threads in the selected memory/tenant scope may be compacted independently.

Returns:

List[str] List of summary IDs that were created

observability_summary(memory_id, user_id, *, thread_id=None, limit=1000)

Return tenant-scoped operational counts without exposing row bodies.

get_trace_context()

Return identifiers for linking application outcomes to the last turn.

build_personalization_context(query, *, memory_id=None, user_id=None, preferences=None, writing_samples=None, additional_memories=None, policy=None, exclude_thread_id=None)

Build explicit, tenant-scoped personalization without running an LLM.

Cross-thread conversation recall occurs only when the supplied :class:~memorizz.personalization.PersonalizationPolicy enables it and both memory_id and user_id are bound. Host preferences and writing samples are accepted as already-authorized application data.

last_memory_context_evidence()

Return the content-free memory supply snapshot for the latest turn.

record_feedback(rating, *, verified=True, source='user', label=None, comment=None, include_comment=False, trace_context=None, external_id=None)

Join verified application feedback to a concrete agent trace.

record_task_outcome(status, *, verified=True, source='application', score=None, metrics=None, trace_context=None, external_id=None)

Join a business/task outcome to a concrete agent trace.

has_automations()

Return True when automation storage + tools are available for this agent.

create_automation(name, schedule_type, *, query_template, cron_expr=None, interval_seconds=None, timezone=None, memory_id=None, whatsapp_to=None, max_run_seconds=900, retry_max_attempts=1, retry_backoff_seconds=60, misfire_policy='skip')

Create a scheduled automation job for this agent.

Parameters:

Name	Type	Description	Default
name	str	Human-readable job name (e.g. "Daily briefing").	required
schedule_type	str	One of "cron", "interval", or "one_shot".	required
query_template	str	The prompt template to run. Supports placeholders: {today_iso}, {scheduled_for_iso}, {now_utc_iso}, {timezone}.	required
cron_expr	Optional[str]	5-field cron expression (required when schedule_type="cron").	None
interval_seconds	Optional[int]	Seconds between runs (required when schedule_type="interval").	None
timezone	Optional[str]	IANA timezone name. Falls back to agent's default_timezone or MEMORIZZ_DEFAULT_TIMEZONE env var.	None
memory_id	Optional[str]	Memory ID for the automation's conversation thread. Auto-generated if not provided.	None
whatsapp_to	Optional[List[str]]	List of WhatsApp recipient numbers. When provided, results are delivered via WhatsApp/Twilio.	None
max_run_seconds	int	Maximum execution time per run (default 900).	900
retry_max_attempts	int	Number of retry attempts on failure (default 1).	1
retry_backoff_seconds	int	Backoff between retries (default 60).	60
misfire_policy	str	What to do on missed runs: "skip" or "run".	'skip'

Returns:

Type	Description
AutomationJob	The created AutomationJob instance.

Raises:

Type	Description
ValueError	If automations are unavailable, timezone is invalid, or required parameters are missing.

Example::

job = agent.create_automation(
    name="Morning News Digest",
    schedule_type="cron",
    cron_expr="0 8 * * *",
    timezone="America/New_York",
    query_template="Give me today's top 5 tech news for {today_iso}",
)
print(f"Created job {job.job_id}, next run: {job.next_run_at}")

list_automations(*, enabled=None)

List automation jobs belonging to this agent.

Parameters:

Name	Type	Description	Default
enabled	Optional[bool]	Filter by enabled state. None returns all jobs.	None

Returns:

Type	Description
List[AutomationJob]	List of AutomationJob instances.

get_automation(job_id)

Get a single automation job by ID.

Parameters:

Name	Type	Description	Default
job_id	str	The job identifier.	required

Returns:

Type	Description
Optional[AutomationJob]	AutomationJob if found, None otherwise.

pause_automation(job_id)

Pause a running automation job.

Parameters:

Name	Type	Description	Default
job_id	str	The job identifier to pause.	required

Returns:

Type	Description
AutomationJob	The updated AutomationJob with enabled=False.

resume_automation(job_id)

Resume a paused automation job.

Parameters:

Name	Type	Description	Default
job_id	str	The job identifier to resume.	required

Returns:

Type	Description
AutomationJob	The updated AutomationJob with enabled=True.

trigger_automation(job_id)

Trigger an immediate run of an automation job.

Sets next_run_at to now and enables the job so the worker picks it up on its next poll cycle.

Parameters:

Name	Type	Description	Default
job_id	str	The job identifier to trigger.	required

Returns:

Type	Description
AutomationJob	The updated AutomationJob.

list_automation_runs(job_id, *, limit=50)

List execution history for a specific automation job.

Parameters:

Name	Type	Description	Default
job_id	str	The job identifier.	required
limit	int	Maximum number of runs to return (default 50).	50

Returns:

Type	Description
List[AutomationRun]	List of AutomationRun instances, most recent first.

delete_automation(job_id)

Permanently delete an automation job.

Parameters:

Name	Type	Description	Default
job_id	str	The job identifier to delete.	required

Returns:

Type	Description
bool	True if the job was deleted, False if not found.

list_approval_proposals(*, status=None, limit=100)

List durable approval proposals owned by this agent.

approve(proposal_id, *, approver_id, reason=None)

Record a host-side approval decision without executing the tool.

reject(proposal_id, *, approver_id, reason=None)

Record a host-side rejection decision.

cancel_approval(proposal_id, *, approver_id, reason=None)

Cancel a pending proposal (host-friendly alias for rejection).

resume_approval(proposal_id, *, continue_model=True)

Execute an approved checkpoint once and return structured evidence.

Set continue_model=False for deterministic host workflows that need the exact tool result without asking an LLM to comment on it.

close(*, cleanup_scope=None, close_memory_provider=True, close_model_provider=False)

Close agent-owned runtime resources and optionally delete a scope.

cleanup_scope is forwarded to a provider's delete_scope before connections are closed. It must contain an exact memory_id, user_id, and/or agent_ids boundary; providers retain their own fail-closed validation.

lifecycle(*, cleanup_scope=None, close_memory_provider=True, close_model_provider=False)

Manage the agent lifecycle with optional exact-scope cleanup.

Persistence

agent.save() stores the current definition in its configured memory provider. MemAgent.load(agent_id, memory_provider=provider, **overrides) restores it; omit memory_provider only when the definition lives in the default filesystem provider.

Personalization context

PersonalizationContext is the provider-neutral boundary between durable memory and a host application's generation prompt. Cross-thread conversation recall is disabled by default and becomes available only when the host opts in with an exact memory_id and authenticated user_id.

from memorizz import PersonalizationPolicy

personalization = agent.build_personalization_context(
    "Draft a LinkedIn post about memory observability",
    memory_id="workspace-7",
    user_id="user-42",
    exclude_thread_id="current-thread",
    preferences={"preferred_tone": "concise and technical"},
    policy=PersonalizationPolicy(
        conversation_recall=True,
        min_relevance_score=0.70,
        max_conversation_memories=2,
    ),
)

response = agent.run(
    "Draft the post.",
    memory_id="workspace-7",
    user_id="user-42",
    context={"personalization_context": personalization.to_dict()},
)

The rendered prompt tells the model to use memories only when they naturally improve the current answer. personalization.trace_summary() and agent.last_memory_context_evidence() contain counts, scores, attribute names, and hashed references, not the underlying profile values or conversation text.

Canonical user entities and duplicate cleanup

Use a stable application-owned identity_key for profile writes. Name changes then update one deterministic entity instead of creating a second profile. This field is deliberately absent from the model-facing entity_memory_upsert tool: only a trusted host or application may bind a canonical identity. Existing cross-name duplicates are never merged heuristically: preview an exact selection first, inspect conflicts, and only then apply a reversible soft supersession.

from memorizz.long_term.semantic.entity_memory import EntityMemory

entities = EntityMemory(provider)
preview = entities.consolidate_duplicate_entities(
    memory_id="workspace-7",
    user_id="user-42",
    entity_ids=["reviewed-id-1", "reviewed-id-2"],
    canonical_identity_key="authenticated_user",
)

# After operator review of preview["groups"]:
applied = entities.consolidate_duplicate_entities(
    memory_id="workspace-7",
    user_id="user-42",
    entity_ids=["reviewed-id-1", "reviewed-id-2"],
    canonical_identity_key="authenticated_user",
    apply=True,
)

The apply path writes and verifies the merged canonical row before setting metadata.superseded_by on aliases. It does not delete records. Anonymous legacy rows require the separate explicit migrate_legacy_scope operator step; authenticated runtime reads never adopt them automatically.

MemAgentBuilder

memorizz.memagent.builders.agent_builder.MemAgentBuilder

Builder pattern for constructing MemAgent instances.

This provides a fluent interface for complex MemAgent configurations, making them more readable and maintainable.

Methods:

with_name(name)

Set a display name for the agent.

with_instruction(instruction)

Set the agent instruction.

with_model(model)

Set the LLM model.

with_llm_config(config)

Set the LLM configuration.

with_persona(persona=None, name=None, expertise=None)

Set the agent persona.

with_favorite(is_favorite=True)

Mark the built agent as favorite or non-favorite.

with_memory_provider(provider)

Set the memory provider.

with_memory_ids(memory_ids)

Set memory IDs.

with_application_mode(mode)

Set the application mode.

with_tools(tools)

Add tools to the agent.

with_tool(tool)

Add a single tool to the agent.

with_toolbox(toolbox)

Attach a progressively retrieved Toolbox and its callable bindings.

with_mcp_servers(mcp_servers)

Attach MCP server configurations to the agent.

with_internet_access_provider(provider)

Attach an internet access provider.

with_skills_marketplace(provider, config=None)

Configure a skills marketplace without post-build mutation.

with_skill_paths(skill_paths)

Attach skill markdown file paths to the agent.

with_sandbox(provider)

Attach a sandbox provider instance, name, or provider config.

with_sandbox_provider(provider)

Backward-compatible alias for :meth:with_sandbox.

with_browser_control(provider)

Attach a browser-control provider instance, name, or config.

with_browser_control_provider(provider)

Compatibility alias for :meth:with_browser_control.

with_meta_harness(meta_harness=None, *, mode='delegate', default_harness='auto', config=None)

Attach the memory-first external-harness control plane.

delegate exposes bounded harness invocation tools to the native MemAgent loop. runtime makes the selected harness execute the complete turn while MemoRizz retains memory, approval, and trace ownership. Passing None lazily builds the standard Codex, Claude Code, and OpenHands registry from the local configuration.

with_execution_harness(harness, *, meta_harness=None, config=None)

Convenience alias for full-runtime meta-harness execution.

with_semantic_cache(enabled=True, threshold=0.85, scope='session')

Configure semantic caching (isolated to a session by default).

with_embedding_provider(provider, config=None)

Set the embedding provider.

with_retrieval_policy(policy)

Set automatic memory-retrieval scope independently of storage.

with_context_policy(policy)

with_tool_result_policy(policy)

with_approval_store(store)

with_skills(skills, *, persistence='skillbox')

Attach authored procedural skills without enabling continual learning.

with_skill_retrieval(enabled=True, top_k=2, min_similarity=0.7)

Configure progressive Skillbox retrieval independently of learning.

with_skillbox(skillbox)

Attach an authored/learned Skillbox independently of learning.

with_continual_learning(enabled=True, config=None)

Enable/disable the workflow→skill continual learning loop.

config keys follow PromotionConfig (e.g. min_executions, require_shadow, shadow_evaluation_enabled, promotion_every_n_runs).

with_learning_control_plane(enabled=True, config=None, **settings)

Enable bounded evidence, event compilation, and governed forgetting.

with_workflow_outcome_evaluator(evaluator)

Set a runtime business-success rubric for captured workflows.

with_delegation(delegates=None, **config)

Make delegates operational and configure orchestration behavior.

with_delegates(delegates)

Set delegates and enable model-generated orchestration by default.

with_semantic_layer(catalog)

Attach a governed semantic catalog and query planner.

with_completion_policy(policy)

Attach a host-enforced final-response acceptance policy.

with_automations_enabled(enabled=True)

Enable/disable durable automations tooling (when supported by provider).

with_default_timezone(tz)

Set a default IANA timezone used by automation tools when omitted.

with_self_aware(enabled=True, config=None)

Enable/disable self-awareness host codebase tooling.

with_entity_memory(enabled=True)

Explicitly enable or disable entity memory for the agent.

with_tool_access(access)

Set tool access level.

with_max_steps(steps)

Set maximum execution steps.

with_verbose(verbose=True)

Enable verbose logging.

with_oracle_from_env(*, ensure_ready=True, provision_if_missing=None, preflight=True, require_preflight_ok=True, **provider_overrides)

Attach an Oracle provider using the documented environment.

By default the local Docker runtime is started/readied first and a provider preflight is retained on the built agent in environment_reports["oracle"].

with_e2b_from_env(*, validate=True, **provider_config)

Attach a stateful E2B provider using E2B_API_KEY by default.

build(validate=True, persist=False)

Build the MemAgent instance.

Returns:

Type	Description
MemAgent	Configured MemAgent instance.

build_and_save(validate=True)

Build, validate, and persist the configured agent.

Meta-harness

memorizz.metaharness.service.MetaHarness

Route, govern, execute, remember, and evaluate agent harness runs.

Methods:

from_env(*, memory_provider=None, agent=None, run_store=None, approval_store=None, allowed_workspace_roots=None) classmethod

register(adapter)

list_harnesses(*, probe=True)

probe(name)

run(task)

start(task)

stream(run_id, *, after=0, poll_seconds=0.1)

approve(proposal_id, *, approver_id, reason=None)

reject(proposal_id, *, approver_id, reason=None)

resume_approval(proposal_id)

Consume and synchronously execute one approved exact checkpoint.

resume_approval_start(proposal_id)

Consume an approval and resume its checkpoint in a background worker.

cancel(run_id)

retry(run_id)

run_plan(task, plan)

Run a bounded serial planner/implementer/reviewer composition.

compare(task, harnesses)

Run an explicit comparison; callers must provide isolated workspaces for writes.

recover_interrupted_runs()

Mark orphaned queued/running rows interrupted when a worker starts.

close()

memorizz.metaharness.models.HarnessTask dataclass

memorizz.metaharness.base.AgentHarness

Bases: ABC

Methods:

probe() abstractmethod

Return secret-free runtime capability and health information.

run(task, *, workspace, context_pack, emit, cancel_event) abstractmethod

Execute one bounded task and emit normalized events.

See the memory-first meta-harness guide for the adapter security matrix and complete SDK, CLI, UI, and MCP workflows.

Runtime policies

memorizz.tooling.ToolPolicy dataclass

Runtime governance metadata attached to a trusted callable.

memorizz.tooling.ToolResultPolicy dataclass

Control when full tool output is replaced by an auditable pointer.

Methods:

to_dict()

Return a stable JSON representation for agent persistence.

memorizz.tool_outcomes.ToolOutcome dataclass

Content-free evidence about a tool result.

status drives the primary UI label. fallback_used and degraded remain orthogonal because a fallback can itself offer reduced capability.

Attributes

ok property

Whether execution produced a usable result.

Methods:

from_value(value) classmethod

Build an outcome from a status string or outcome mapping.

to_dict()

Return a stable JSON-safe representation.

memorizz.tool_outcomes.ToolOutcomeStatus

Bases: str, Enum

Terminal state for one tool execution.

memorizz.tool_outcomes.ToolResult dataclass

A tool payload with an explicit outcome.

MemAgent unwraps value before model serialization, preserving the tool's established result schema.

memorizz.tooling.ContextPolicy dataclass

Bounded context and progressive-disclosure defaults for an agent.

memorizz.retrieval.RetrievalPolicy dataclass

Configure automatic semantic recall without changing storage.

The defaults preserve the pre-0.5.2 behaviour for compatibility. Safer conversational applications can use RetrievalPolicy.disabled() or select conversation_scope="thread" and explicit KB namespaces.

memorizz.completion.CompletionPolicy dataclass

Bounded, auditable final-response acceptance policy.

validator is deliberately runtime-only: serializing arbitrary code is unsafe. When validator_required is persisted, a reloaded agent rejects completion until the trusted host rebinds a validator.

Methods:

evaluate(candidate)

Evaluate one candidate without mutating agent or host state.

to_dict()

Serialize configuration without serializing executable validator code.

Model providers

memorizz.llms.llm_provider.LLMProvider

Bases: Protocol

A generic protocol that defines the contract for any LLM provider to be compatible with both the OpenAI and AzureOpenAI classes.

Methods:

generate(messages, tools=None, tool_choice='auto')

Generate a response from a list of messages (chat format), optionally with tool calling.

generate_stream(messages, tools=None, tool_choice='auto')

Stream a response from a list of messages (chat format), optionally with tool calling.

Yields dictionaries with one of these shapes

• {"type": "content", "content": "..."} for text chunks
• {"type": "tool_calls", "response": } when tool calls are detected
• {"type": "done", "content": ""} at the end of the stream
• {"type": "usage", "usage": {...}} for known token accounting

Content deltas concatenate exactly to done.content, including whitespace. Exactly one done or completed tool_calls event ends a successful request; an incomplete/refused request raises, it must not invent success at EOF. Reasoning is diagnostic only. Tool response objects are internal and never serialized into public SDK events. Consumers close this generator; adapters must close their raw provider stream and cooperate with the current cancellation token. See llms.streaming.streaming_capabilities for reliable detection (an inherited Protocol stub is not an iterator).

get_config()

Returns a serializable dictionary of the provider's configuration. This is used for saving and reconstructing the agent.

get_last_usage()

Return token usage details (prompt/completion/total) from the most recent call.

get_context_window_tokens()

Return the provider's context window size in tokens, when known.

Memory providers

memorizz.memory_provider.base.MemoryProvider

Bases: ABC

Abstract base class for memory providers.

Methods:

store(data=None, memory_store_type=None, memory_id=None, memory_unit=None) abstractmethod

Store data in the memory provider.

Parameters:

data : Dict[str, Any], optional Data dictionary to store (legacy parameter) memory_store_type : str, optional Type of memory store (legacy parameter) memory_id : str, optional Memory ID to associate with (new parameter) memory_unit : MemoryUnit, optional Memory unit object to store (new parameter)

retrieve_by_query(query, memory_store_type=None, limit=1, memory_id=None, memory_type=None, **kwargs) abstractmethod

Retrieve a document from the memory provider.

Parameters:

query : Dict[str, Any] or str Search query (dict for filter queries, str for semantic search) memory_store_type : str, optional Type of memory store (legacy parameter name) memory_type : str or MemoryType, optional Type of memory store (new parameter name, takes precedence over memory_store_type) memory_id : str, optional Filter results to specific memory_id limit : int Maximum number of results to return **kwargs Additional provider-specific parameters. Includes user_id for multi-tenant scoping. Omitting it is an administrative/unscoped read, explicitly passing None selects anonymous/legacy rows, and a string selects that exact tenant.

retrieve_by_id(id, memory_store_type) abstractmethod

Retrieve a document from the memory provider by id.

When a provider supports multi-tenant scoping via user_id it may accept a user_id keyword argument; callers that need strict isolation should check the returned row's user_id against their expected scope before acting on it.

list_all(memory_store_type, user_id=_UNSET) abstractmethod

List all documents within a memory store type in the memory provider.

user_id follows the shared sentinel contract: omitting it performs an administrative/unscoped read, explicitly passing None selects only anonymous/legacy rows, and a string selects that exact tenant.

retrieve_conversation_history_ordered_by_timestamp(memory_id, memory_type=None, limit=None, user_id=_UNSET, thread_id=None) abstractmethod

Retrieve the conversation history ordered by timestamp.

Parameters:

memory_id : str The memory ID to retrieve history for memory_type : str or MemoryType, optional Type of memory (typically CONVERSATION_MEMORY) limit : int, optional Maximum number of entries to return user_id : str, optional (keyword) Multi-tenant scope. Omitting it is an administrative/unscoped read, explicitly passing None selects anonymous/legacy rows, and a string selects that exact tenant. thread_id : str, optional When provided, return only rows from that exact conversation thread. When omitted, return all threads in the memory scope.

query_observability_records(memory_store_type, *, agent_ids=None, memory_ids=None, thread_id=None, user_id=_UNSET, application_id=None, record_type=None, tool_name=None, success=None, start_time=None, end_time=None, limit=250, cursor=None)

Return one bounded observability page with portable metadata.

First-party database providers should override this with indexed predicates. This compatibility path intentionally remains available to third-party and filesystem providers, but it never returns an unbounded page to the caller.

invalidate_semantic_cache(*, agent_id=None, memory_id=None, domains=None, tags=None, data_version=None)

Delete persistent cache entries matching governance metadata.

This provider-neutral fallback keeps domain/tag/data-version invalidation operational on filesystem, MongoDB, Oracle, and custom providers. Native providers may override it with a bulk predicate.

store_memagent(memagent) abstractmethod

Store a memagent in the memory provider.

delete_memagent(agent_id, cascade=False) abstractmethod

Delete a memagent from the memory provider.

list_memagents() abstractmethod

List all memagents in the memory provider.

close() abstractmethod

Close the connection to the memory provider.

See the custom provider contract before implementing this interface, particularly the three-state user_id filter.

Memory evaluation

The normalized memory-suite SDK keeps diagnostic runs separate from exact paper reproduction. Use get_protocol_manifest() before a run and inspect the returned report's comparison_label, paper_comparable, and comparability_reasons fields before publishing a comparison.

from memorizz.benchmarks.memory_suite import (
    get_protocol_manifest,
    run_memory_suite,
    verify_dataset,
)

readiness = verify_dataset("longmemeval-v2", data_path="./datasets/lme-v2")
protocol = get_protocol_manifest("longmemeval-v2")

report = run_memory_suite(
    "longmemeval-v2",
    "./datasets/lme-v2",
    variant="standard-100",
    profile="smoke",
    workspace="./.memorizz-eval",
    memory_backend="filesystem",  # use "oracle" for Oracle AI Database
    candidate_pool_size=256,
    lexical_ratio=0.35,
    oracle_reader=True,
)

MemorySuiteRunner additionally accepts injected model, judge, embedding, and memory-provider objects for deterministic tests. See the evaluation-suite guide for official-source sync, strict comparability, CLI equivalents, and result interpretation.