agent-memory-os 0.2.4

Local-first, MCP-native memory engine for AI agents with RAM cache and context-budgeted recall.

A local-first memory engine for AI agents — single or multi-agent, with shared and private memories, associative recall, and context-budgeted retrieval. One SQLite file, zero required dependencies, Apache-2.0.

Why

Agents need durable facts, preferences, procedures, and lessons — but prompt-injected memory blocks are small and overflow fast, and cloud memory platforms add latency, cost, and privacy tradeoffs. AgentMemoryOS separates long-term memory from the context window: memories live in a local database, and each prompt receives only the relevant, budgeted slice.

Features

• Local-first, zero-dependency core — one SQLite file (FTS5), no server required. pip install and go.
• Requester-aware ACL — every agent profile has private, team, and global memories; visibility is a hard gate enforced before ranking, never a soft score.
• Dynamic context packs — token-budgeted, auditable memory selection per prompt (context_pack_report() explains every include/exclude decision).
• Truth arbitration — duplicate suppression, contradiction detection (CONFLICT markers), and reserved budget for core memories.
• Associative recall (resonance) — an authoritative memory_links graph lets related memories surface even when they share no query terms; traversal is ACL-safe (invisible nodes are untraversable).
• Hebbian reinforcement — memories recalled together grow stronger links (record_recall, or auto_reinforce=True on context packs); unhelpful recalls weaken links and confidence (helpful=False).
• Per-agent recall profiles — different agent personas weight memory types differently (an engineer leans on procedure, a companion on preference); profiles persist in the database and re-weight ranking only, never bypassing ACL.
• Memory lifecycle — exponential/linear decay, pinning, hard expiry, and a write-side consolidate() pass that merges duplicates and synthesizes strongly co-recalled clusters into concept memories.
• Optional sidecars — semantic vector candidates (turbovec), MCP server, and a FastAPI Web UI, all behind extras; every candidate rejoins SQLite and passes hard gates before use.

Install

pip install 'agent-memory-os[full]'    # recommended: everything (Web UI, MCP, turbovec)

Or pick pieces: agent-memory-os (core, zero dependencies), [api] (Web UI), [mcp] (MCP server), [semantic] (turbovec vector recall).

Requires Python 3.11+ with SQLite FTS5 (included in standard CPython builds).

After installing, run two commands:

agent-memory doctor          # verifies FTS5, turbovec, and the other extras
                             # (add --install to auto-install anything missing)
agent-memory token create    # protects the Web UI API with a bearer token

The token is stored at <home>/web_token (mode 600); agent-memory-web picks it up automatically and the console prompts for it on first use. Manage it later with agent-memory token show|rotate|disable.

Quickstart

from agent_memory_os import MemoryClient, RecallProfile

client = MemoryClient(home="~/.agent-memory")

# Write memories with ownership and visibility
client.add("User prefers dark mode.", owner="mizuki", type="preference",
           visibility=[])                      # private to owner
client.add("Deploy target is port 8000.", owner="neo", type="environment",
           visibility=["global"])              # visible to every agent

# Requester-aware search: each agent sees only what it may see
hits = client.search("deploy port", requester_agent_id="neo")

# Token-budgeted context pack for the prompt, with reinforcement loop closed
pack = client.context_pack("deploy port", requester_agent_id="neo",
                           max_tokens=1200, auto_reinforce=True)

# Associate memories; linked memories resonate into future recalls
a = client.add("Staging deploy failed with database lock.", visibility=["global"])
b = client.add("Always snapshot before schema changes.", visibility=["global"])
client.link(a.id, b.id, relation="caused_by", weight=0.8)

# Persist an agent persona: soft ranking bias per memory type
client.save_profile(RecallProfile(agent_id="neo",
                                  type_weights={"procedure": 1.5, "note": 0.7}))

# Periodic hygiene: merge duplicates, synthesize concept memories
client.consolidate()

Architecture

query
  -> candidate providers (FTS5 | vector sidecar | resonance graph | fallback)
  -> merge/dedupe by stable memory_id
  -> rejoin authoritative rows from SQLite
  -> ACL hard gate -> expires_at hard gate
  -> scoring (relevance x importance x confidence x freshness x reinforcement)
  -> per-agent profile re-weighting (soft)
  -> truth arbitration + context budget allocation

Design invariants:

• The SQLite memories table is the single source of truth; FTS/vector indexes are disposable and rebuildable (rebuild_indexes()).
• Candidate providers return IDs and scores only — content is always re-read through SQLite behind the ACL and expiry hard gates.
• Association edges (memory_links) are authoritative data, survive index rebuilds, decay when unused, and never let an invisible memory bridge two visible ones.

See SPEC.md for the full contract.

Storage engines: SQLite + turbovec

AgentMemoryOS uses two storage layers with strictly different authority:

• SQLite (always on) is the single source of truth: memories, links, profiles, and the FTS5 lexical index all live in one memories.db file.
• turbovec (installed with [full] / [semantic]) is the semantic vector engine: an in-memory quantized index that recalls memories by meaning rather than keywords. It is deliberately disposable — it returns candidate memory_ids and scores only; every candidate rejoins SQLite and passes the ACL/expiry hard gates before its content can be used, and the index can be dropped and rebuilt at any time without touching the truth store.

To activate semantic recall, supply an embedding function and wire the provider in:

from agent_memory_os.providers.turbovec import TurbovecSemanticCandidateProvider

provider = TurbovecSemanticCandidateProvider.from_vectors(
    vectors=embeddings,                      # one row per memory, any embedder
    external_id_by_memory_id=id_mapping,     # stable memory_id -> uint64
    embed_query=embed,                       # str -> vector, same embedder
)
client = MemoryClient(home="~/.agent-memory", candidate_providers=[provider])

agent-memory doctor confirms the turbovec backend is importable.

Backup & restore

agent-memory backup ~/backups/memories-$(date +%F).db   # online, WAL-safe
agent-memory restore ~/backups/memories-2026-07-11.db --force

Backups use SQLite's online backup API, so they are consistent even while agents are writing. Disposable indexes rebuild automatically after a restore.

Agent integrations

Step-by-step guides for wiring AgentMemoryOS into common agents — click a tile:

Any MCP-capable agent can use the same pattern: run python -m agent_memory_os.mcp_server as a stdio MCP server pointing at a shared AGENT_MEMORY_HOME.

MCP server

pip install 'agent-memory-os[mcp]'
python -m agent_memory_os.mcp_server

Tools: memory_add, memory_search, memory_context_pack, memory_link, memory_update, memory_recall_feedback, memory_consolidate.

Web UI

pip install 'agent-memory-os[api]'
agent-memory-web --host 127.0.0.1 --port 8000 --home ~/.agent-memory-web

The console ships with a stats dashboard (scope/type/relation breakdowns, 14-day activity, most-recalled memories), search and recency browsing (memory cards with in-place editing, feedback, links, and delete actions), an interactive association-graph view, a context-pack preview with per-memory decisions, and add/link/consolidate tools — all driven by a global "acting as" identity.

Endpoints: GET /health, GET /api/stats, GET /api/dashboard, GET|POST /api/memories, GET|PATCH|DELETE /api/memories/{id}, GET /api/memories/{id}/links, GET /api/graph, POST /api/links, POST /api/recall, POST /api/consolidate, GET /api/search, GET /api/context-pack.

Search, browse, graph, recall feedback, and context-pack accept requester_agent_id and enforce the same ACL hard gates as the SDK. Requests without a requester run in unrestricted admin view — bind to localhost only, or require a bearer token on every API route with --token <secret> (or AGENT_MEMORY_WEB_TOKEN).

Note: keep the --home database on a local disk. Network filesystems (NFS/SMB) can fail SQLite FTS5 schema creation with database is locked.

Development

pip install -e '.[dev]'
pytest

Status

Alpha (0.2.x). The core contracts above are implemented and covered by the test suite; interfaces may still change before 1.0. See PROJECT_STATUS.md and PROGRESS.md for the evidence-backed state of each feature.

License

Apache License 2.0