Agent Memory

Remember what changed. Keep the evidence.

Traceable, correctable memory for AI agents.
Start with Python + SQLite. Add PostgreSQL, MCP, and LangGraph when you need them.

简体中文 · Quickstart · Architecture · Examples · Integrations · Docs

Agent Memory gives your agent current facts, evidence, and a history of what changed. It records where a statement came from, when it applies, and whether it can be used in the current scope. Your host receives a bounded MemoryBundle for its next model call.

The basic memory loop runs locally with zero third-party runtime dependencies—no model key, vector database, or background service required. Extraction, integrations, and workers are opt-in.

Alpha · v0.1.0. Try the local examples below. Supported slices and remaining acceptance work are documented in capability status.

Memory changes. The evidence stays connected.

A real memory problem	What your agent can do
“I moved from Hangzhou to Shanghai.”	Record the change and its effective time. Keep the earlier history. If Shanghai's evidence is erased, return unknown after the move while preserving the independent evidence that Hangzhou ended. Run it →
“Use Chinese for Project A, except on holidays.”	Preserve the project condition and the exception. Return a qualified language preference when applicable, or context_unknown when the trusted context is missing. Run it →
“Forget this source—even after restoring a backup.”	Replay an authoritative deletion log over an isolated old database copy. Keep unrelated sources while preventing erased content from returning. Run it →

These examples use explicit host policies and deterministic adapters. They demonstrate inspectable behavior without a model API key. Source identity, time, and permission remain attached as memory is corrected, combined, retrieved, or erased.

Quickstart

Install

Requires Python 3.13+. Install from this repository into a virtual environment. On macOS or Linux:

git clone https://github.com/agent-memory-lab/agent-memory.git
cd agent-memory
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Windows PowerShell

git clone https://github.com/agent-memory-lab/agent-memory.git
cd agent-memory
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe demo.py

Create demo.py from the example below before running the last command. This uses the virtual environment's interpreter directly; activation is optional.

On macOS or Linux, ./setup.sh creates a development environment; ./setup.sh --all also installs the optional packages. Select an interpreter with PYTHON_BIN=/path/to/python3.13 ./setup.sh.

Remember → recall → inspect the source

Save this as demo.py, then run python demo.py:

import asyncio
from agent_memory import AgentMemory, MemoryScope


async def main():
    # Your application supplies identity and scope.
    scope = MemoryScope(tenant_id="demo", user_id="alice", agent_id="assistant")
    async with AgentMemory.local("memory.sqlite3", scope=scope) as memory:
        await memory.remember(
            "I prefer concise answers.",
            event_type="user.message",
            actor="user",
            idempotency_key="alice-answer-style-1",
            claims=({
                "key": "answer.style",
                "value": "concise",
                "text": "Alice prefers concise answers.",
                "scope": "user",
                "confidence": 0.98,
            },),
        )
        bundle = await memory.recall("How should I answer Alice?", token_budget=600)
        for claim in bundle.current_state:
            print(f"{claim.key}: {claim.value}")
            print("source event:", claim.provenance.source_event_ids[0])


asyncio.run(main())

Output on a fresh database:

answer.style: concise
source event: <event-id>

The event ID is generated at runtime. Rerunning the same input with the same idempotency key returns the same source event; changing that input requires a new key.

This example supplies the structured claim from host code. It demonstrates persistence and recall; automatic extraction is a separate, optional path. confidence is an input score, not a guarantee of truth. The returned bundle contains memory context for your host to assemble into a model request; it does not call an LLM.

From source evidence to usable knowledge

The v6.1 design separates the source, the accepted interpretation, and the views built from it:

Component	Responsibility	Available scope
L0 · Source evidence	Preserve captured content, source identity, revisions, and processing requests	Durable receive, deduplication, explicit source revisions, and replay
L1 · Atomic memory	Decide what can be used, with evidence, conditions, and time	Typed admission; accepted, pending, or contested outcomes; supported corrections and dual-time queries
Observation · Derived views	Organize a facet across sources and rebuild when its inputs change	Same-scope language templates, bounded historical reads, current non-conditional parent views, and versioned host permissions
L2 · Scenario	Organize versioned scenario pages and blocks	Current language-scenario/1 pages support full rebuild from fixed same-scope, non-conditional language parents; general scenario templates remain planned
L3 · Core / Persona	Organize explicit long-term preferences and carefully evaluated patterns	Planned under the unified contract; inferred profiles require separate acceptance

Observation is a derived building block that can support L2 or L3. L1 also feeds retrieval directly. A summary's position in this structure never increases the authority of its evidence.

• Two clocks: valid_at asks when a fact applies; known_at asks what the system knew at that point.
• Reliable work: sources, tasks, publication receipts, and index coverage have explicit transaction boundaries and recovery behavior.
• Controlled delivery: the host supplies identity and permissions; retrieval and derived reads enforce their supported scope and current erasure guards.
• Bounded context: MemoryBundle carries relevant memory and citations within item, character, and token estimates configured by the host.

See Atom admission, bitemporal memory, and code architecture for contracts and module boundaries.

Examples

Run these from the repository root. Core means python -m pip install -e .; + SDK adds python -m pip install -e packages/python-sdk. All examples below run locally without a model key.

Try this	What to inspect	Install
Basic memory	A saved preference, current state, and source citations	Core
Contribution correction	A move, independent termination evidence, and safe erasure	Core
Conditional language	Project conditions, exceptions, and qualified Observation output	+ SDK
Host-controlled views	Versioned query definitions, expiring host permissions, and read-only delivery	+ SDK
Batched publication	Partial publication, closure, and complete index coverage	+ SDK
Backup deletion replay	Recover an old backup without restoring erased evidence	Core

python examples/contribution_memory.py

October 2: ['Hangzhou']
October 6: unknown

More examples: capture, recovery, indexes, and plugins

Example	What to inspect	Install
Durable memory	Persist sources and processing requests, then publish L1	+ SDK
Contextual facts	Field evidence, conditions, and supported time ranges	Core
Derived parent views	Fixed current parent versions, transitive access and revocation	+ SDK
Versioned L2 page	Full rebuild, stable block identities and guarded current page readiness	+ SDK
Current Observation	Build and read a current language facet	+ SDK
Offline deletion sync	Clean a participating SDK outbox before new delivery	+ SDK
L1 readiness	Wait for a fixed set of requests; cancel a deleted offline sequence	+ SDK
Reprocessing readiness	Track an explicit interpretation replacement	+ SDK
Local index readiness	Separate publication from candidate locator visibility	+ SDK
Index repair and rollover	Repair a gap and switch to a rebuilt index stream	+ SDK
Resource refresh	Coalesce work while preserving fixed completion targets	Core
Plugin contracts	Implement and validate a plugin lifecycle	Core

The capture integration recipe shows how to connect lifecycle hooks, a host provider, authenticated context, and a queue. It requires the Python SDK and host setup.

Integrations

Start with the core and install the integration packages you need:

Package	Purpose	Local installation
agent-memory	Domain contracts, SQLite runtime, retrieval, plugin loading	python -m pip install -e .
Python SDK · agent-memory-sdk	Embedded/remote facade and durable host outbox	python -m pip install -e packages/python-sdk
MCP server · agent-memory-mcp	stdio and Streamable HTTP transport	python -m pip install -e packages/mcp-server
LangGraph	Lifecycle adapter	python -m pip install -e packages/langgraph
PostgreSQL	PostgreSQL provider and optional vector support	python -m pip install -e packages/postgres
Evolution	Evaluated Procedure candidates and promotion	python -m pip install -e packages/evolution

For a local MCP host, install the MCP package above and start a scope-bound stdio server:

agent-memory-mcp --transport stdio --database memory.sqlite3 \
  --tenant-id demo --user-id alice --agent-id assistant --session-id session-1

For remote HTTP, use the authenticated gateway contract. Identity comes from trusted host configuration or verified authentication.

The public boundary is MemoryProvider. Optional packages use lazy discovery; importing the core does not load database drivers, framework runtimes, or ML libraries. Plugin Protocol v1 adds manifests, capability negotiation, lifecycle health, resource limits, and stable errors. See the plugin example and architecture guide.

Capability status and roadmap

The current documented delivery baseline is stage 15: bounded current language L2 pages of the v6.1 architecture plan. The software package is v0.1.0 / Alpha; architecture, protocol, and package versions are tracked separately.

Capability	Current implementation	Evidence
Reliable L0 → L1	Host outbox, atomic receive/publish, source revisions, explicit reprocessing, same-slot corrections, and dual-time fact reads	Delivery chain · Contribution lifecycle
Recovery and readiness	Fixed processing targets, bounded waiting, batch closure, local candidate indexing, explicit repair, and stream rollover	Index recovery · Batched publication
Erasure and backup replay	Participating outbox deletion sync and controlled offline replay using an independently held authoritative checkpoint	Deletion sync · Backup replay
Current Observation	Same-scope language facets, complete input dependencies, invalidation, full rebuild, and conditional language templates	Lifecycle · Conditions
Historical Observation	Frozen language snapshots/context, independent known/valid time, certified coverage and current permission/erasure checks	History
Derived parent inputs	Fixed current language revisions, complete processing lineage, guarded delivery and transitive physical erasure	Stage 14C
Query and host permissions	Versioned current queries, expiring local authority, source-grant binding, and checks before final delivery	Stage 14A
Current language L2 pages	Typed Scenario/Page/Block versions, stable block identities, atomic full rebuild, fixed readiness targets, guarded delivery, and transitive erasure	Stage 15
Retrieval and feedback foundations	Scoped, bounded recall; optional lexical/hybrid candidates; outcome-linked Episode/Procedure and gated Evolution components	Architecture · Feedback

Observation remains limited to documented language templates. Published-point and certified-interval history preserve frozen policies/context and current access checks; gaps are rejected. Current locale-parents/1 views bind fixed parent revisions and transitive processing permissions. Current language-scenario/1 pages combine 1–4 non-conditional language Observation parents in the same exact scope, with compatible subject, purpose, and authority.

Conditional/historical parents, pages as parents, historical pages, delta updates, general scenario templates, cross-scope composition, remote ACL synchronization, and L3 remain disabled or planned. The bounded page delivery does not complete the full L2/L3 lifecycle. L1's existing bitemporal queries remain independently available; l1_decided means processing completed, not that a fact is true.

Validation records include SQLite and real PostgreSQL contracts, cross-connection races, process-kill recovery, and backup replay. The stage 12 full-suite report is an older baseline; stage 13 and stage 14 A/B.3/C record targeted and affected regression runs. Stage 15 records a full repository/package run and build/install verification, with independent evidence. Each report applies to its recorded code baseline; counts are not cumulative. Production acceptance, real-domain extraction quality, and full M0/M1/M2 milestone acceptance remain open.

Next in the implementation plan:

1. Qualified current parents and pages: the stage 16 plan defines compatible host routing and qualification contracts that preserve conditions and exceptions; it is not yet implemented or accepted.
2. Further composition: historical parents/pages and broader templates need their own frozen-input contracts and acceptance; cross-scope composition remains disabled.
3. Incremental views and L3: delta is deferred pending evidence of benefit and a versioned patch contract; inferred profiles require independent stability, counterexample, and quality acceptance.
4. Real-world validation: domain gold, model input and delivery controls, dispatch budgets, and reproducible quality/cost comparisons.

Advanced retrieval and optional read-only Reflect remain on the task ledger. Remote deployments use the security policy and threat model; external caches, remote ACL systems, and provider-held copies need their own integration contracts.

Documentation

You want to…	Start here
Understand the design	v6.1 architecture · Module boundaries
Admit or extract facts	Atom admission · Automatic extraction
Read facts across time	Bitemporal memory
Build a controlled language view	Observation lifecycle · Conditional view · Query and permissions
Read historical views or compose current pages	Bounded history · Parent inputs · Current L2 pages
Connect feedback and evolution	Feedback contract · Evolution package
Deploy and recover	Single-host deployment · Recovery operations
Inspect evaluation evidence	Evaluation methodology · Resource baseline
Follow or contribute to development	Plan · Tasks · Next steps

Contributing

Useful contributions include a reproducible edge case, an integration adapter, or a well-annotated evaluation scenario. Start with the task ledger and CONTRIBUTING.md.

./setup.sh --all
source .venv/bin/activate
python -m pytest -q

Integration and live PostgreSQL tests have additional setup; see CI. Preserve the small default footprint, host-owned scope, and traceable evidence.

Open an issue with a reproducible example, or report security vulnerabilities privately through SECURITY.md.

License

Apache License 2.0.