Skip to main content
The Python SDK provides the AgentMemory class — the primary interface for reading, writing, and managing agent memory.

Installation

Set the connection env vars and the SDK auto-detects the HTTP adapter:

Creating an Instance

With Custom Configuration

With a Pre-configured Adapter

With an Embedder

With an Importance Evaluator

Every write() call will automatically score the entry and set importance_score and importance_dimensions. If the evaluator raises, the write proceeds without scoring.

Full Constructor Signature


Core Operations

Write

Write with a TTL (time-to-live):

Read

With minimum confidence filter:
Read from a specific branch:

List

Full search options:
Progressive retrieval with depth — search only high-priority tiers for fast, high-signal results:
Composite recall scoring (blends semantic similarity, recency, and confidence):
Semantic scoring requires an embedder. Without one, the semantic component is 0.0.

Stats


Outcomes

Recording Outcomes

Outcome Types


Memory Types

Classify entries to control decay behavior:

Agent-Scoped Memory

The SDK distinguishes between shared memory and agent-scoped memory. Use recall, my_entries, and read_from for explicit agent-level operations.

Recall

Read only entries written by this agent — what this brain knows from direct experience:
Unlike read(), which returns the latest version by any agent, recall() falls back through history to find the most recent version authored by this agent.

My Entries

List everything this agent has written:

Read From Another Agent

Explicitly read from another agent’s memory with tracked knowledge transfer:
This creates a graph edge (learned_from) and logs cross-agent read events on both sides for full traceability.

Cross-Agent Reads

See which other agents’ memory this agent has consumed:

Scopes

A MemoryScope provides a focused view bound to a single entity path, reducing boilerplate:

Scope Utilities


History (Temporal Queries)

Retrieve the full version history of an entry with optional time filtering:

Explainability

Inspect the causal chain — which entries were read during the current session and how they connect to outcomes:
Filter by outcome reference:

Decision Traces

When you call commit_outcome(), AMFS snapshots the full decision trace — every entry that was read, every context that was recorded, and every query that was made. The resulting trace is persisted and can be retrieved later.

Getting the Trace from an Outcome

Browsing Past Traces

Filtering Traces


Tool Context

When agents call external tools or APIs, there are two ways to capture that context in AMFS depending on your needs.

Record in the Causal Chain (Lightweight)

Use record_context() to add external inputs to the causal chain without writing to storage. This makes explain() return a complete decision trace:

Persist for Other Agents (Durable)

Use MemoryType.EXPERIENCE with a TTL to store tool results so downstream agents can retrieve them:
The next agent reads it with mem.read("checkout-service", "tool-result-pagerduty") instead of re-calling the API.

Timeline

View the event log for this agent — every read, write, outcome, and cross-agent interaction:

Watch

Get real-time notifications when entries change:
Watch behavior depends on the adapter. The filesystem adapter supports real-time watches. The HTTP adapter currently logs a warning and returns a no-op handle — use the MCP server’s streaming capabilities for remote real-time updates.

Transactions

Group multiple writes into an atomic commit:

Integrity Verification

Verify content hashes and integrity chains for stored entries:

Commit Log & DAG

Inspect the commit history and navigate the commit DAG:

Diff & Patch

Compute structural diffs between entry versions:

Agent Binding

Profile

Set a profile for this agent (description, defaults, tags):

Capabilities

Declare capabilities so other agents can discover you:

Contracts

Set memory contracts that define expectations for entries:

Discovery

Find other agents by capability or entity path:

Briefing (Memory Cortex)

When the Memory Cortex is running, agents can retrieve pre-compiled knowledge digests ranked by relevance. This is how agents consume the “brain brief” — compiled summaries of entities, other agents, and external sources — without having to search through raw memory entries.

Basic Usage

Parameters

Digest Types

Resolution Order

The briefing method tries multiple backends in order:
  1. Adapter-native briefing() — e.g. HttpAdapter proxies to the server
  2. amfs_cortex.BriefingService — full Cortex scoring (if amfs-cortex is installed)
  3. Inline scoring via adapter list_digests() — fallback when Cortex is not installed but adapter has digest access
If none are available, briefing() returns an empty list — your agent code can safely call it without checking.

Knowledge Graph

The knowledge graph builds automatically as agents write, commit outcomes, and learn from each other. Pattern refs and causal chains create edges. You can traverse it directly:
Multi-hop traversal (depth > 1) requires the Postgres adapter. The Filesystem and S3 adapters return an empty list for graph methods.

If you configure an embedder, you can search by meaning:

Context Manager

Use AgentMemory as a context manager for automatic cleanup:

Connecting to AMFS

Set two env vars and the SDK connects automatically — no adapter setup needed:
See the Connect to AMFS guide for details.

Rooms & Collaboration

The SDK includes room-based collaboration APIs for multi-agent knowledge sharing. These require an HTTP adapter connection.

Negotiation

Rooms support structured negotiation sessions between agents:
Room and negotiation methods require an HTTP adapter that exposes the rooms API. Set AMFS_HTTP_URL to enable these features.

Conflict Handling

Handle concurrent writes to the same key:

Snapshots

Export and import the full state of your memory:

Exports


Properties