Agent Memory Os

English · 繁體中文

A local-first memory system for AI-agent teams — not just giving one agent a memory, but a shared memory fabric for a *fleet* of agents working together: private, team, and project-scoped memories behind a hard ACL, associative recall, and federated sync that keeps a mesh of nodes (and their org structure) in agreement. One SQLite file, zero required dependencies, Apache-2.0.

Why · Compare · Install · Quickstart · Features · Federation · Web UI · User Guide

The built-in web console: token-usage by agent/team/project, memory browse, and the ACL-safe association graph.

Why

Real work happens in teams of agents — a project might mix Claude Code, Codex, OpenClaw, and several Hermes profiles, across multiple teams and projects, on one machine or many. They need to share the *right* knowledge with the *right* teammates and keep private what should stay private:

• Per-agent memory is the floor, not the ceiling: durable facts, preferences, procedures, and lessons that survive across sessions.
• Team & project memory is the point: a team sees team: memory; a project (a subset of the team) sees project: memory; nothing leaks across the boundary. Membership is first-class and manageable, and drives the ACL.
• Federation keeps a mesh honest: memories *and* the org structure (teams/projects/memberships) converge across nodes, so project: means the same thing everywhere.
• Local-first avoids the latency, cost, and privacy tradeoffs of cloud memory platforms — memories live in a local SQLite file, 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.
• Teams & projects, first-class — teams are sets of node members; a project's members are a subset of its team. team: memory reaches the whole team, project: memory only that project — a hard ACL, managed in the console/CLI/API. Removing a member re-scopes recall instantly; deleting a scope revokes its memory.
• Federated across nodes, with a real trust model — portable bundles + peer sync converge memories, links, profiles, and the org structure (teams/projects/memberships) with last-writer-wins + tombstones. Per-peer policy (shared/full/team:/project:) is an enforced authorization scope: a peer can only assert membership within its own scope and can only *shrink* a memory's visibility, never widen it — no cross-scope escalation from a bundle.
• Revocation that propagates — an independent ACL clock carries a post-hoc share/revoke across the mesh, so revoking access actually retracts it on peers that already synced the memory — without disturbing the decay clock.
• Requester-aware ACL — every agent has private, agent, team, project, and global memories; visibility is a hard gate enforced before ranking, never a soft score. Candidate indexes return IDs only; content is re-read through the gate.
• 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.

How it compares

Most agent-memory systems optimize for LLM-driven extraction at hosted scale. AgentMemoryOS optimizes for a different point: local-first, team-scoped, and federated — memory you run yourself, shared across a fleet under a hard ACL. This is a *positioning* comparison (architecture, not a benchmark); verify each row against the projects' current docs.

Mem0 and Zep are strong at LLM-based extraction and managed-scale retrieval — things AgentMemoryOS deliberately doesn't do. Reach for AgentMemoryOS when you want a dependency-light memory you own, shared correctly across a *team* of agents, that keeps working offline and syncs on your terms.

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).

Docker: the prebuilt multi-arch image is the complete AgentMemoryOS (web console + MCP server + CLI); the first argument picks the mode:

docker run -p 8000:8000 -v amos-data:/data yamantaka520/agent-memory-os        # web console (default)

docker run -i --rm yamantaka520/agent-memory-os mcp # stdio MCP server docker run --rm -v amos-data:/data yamantaka520/agent-memory-os check # any CLI command

Or docker compose up -d. Console at http://localhost:8000, memories persist in a volume. See the Docker guide (Docker Hub image + a two-node sync mesh).

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 /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. Two narrower tiers exist: --readonly (GET-only) and --sync (federation routes only — hand this to a peer instead of the admin token).

Quickstart

Prefer a runnable script? examples/team_memory.py shows three agents sharing one store under a hard ACL in ~40 lines — python examples/team_memory.py.

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 (