AgentMemory class — the primary interface for reading, writing, and managing agent memory.
Installation
Creating an Instance
With Custom Configuration
With a Pre-configured Adapter
With an Embedder
With an Importance Evaluator
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
Read
List
Search
depth — search only high-priority tiers for fast, high-signal results:
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. Userecall, 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: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: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
AMemoryScope 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:Decision Traces
When you callcommit_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)
Userecord_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)
UseMemoryType.EXPERIENCE with a TTL to store tool results so downstream agents can retrieve them:
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:- Adapter-native
briefing()— e.g.HttpAdapterproxies to the server amfs_cortex.BriefingService— full Cortex scoring (ifamfs-cortexis installed)- Inline scoring via adapter
list_digests()— fallback when Cortex is not installed but adapter has digest access
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.Semantic Search
If you configure an embedder, you can search by meaning:Context Manager
UseAgentMemory as a context manager for automatic cleanup:
Connecting to AMFS
Set two env vars and the SDK connects automatically — no adapter setup needed: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.