Agent-Memory-OS

<!-- mcp-name: io.github.yamantaka520/agent-memory-os --> <p align="center"> <img src="https://raw.githubusercontent.com/yamantaka520/Agent-Memory-OS/main/assets/agent-memory-os-logo-integrated-v2.png" alt="Agent Memory OS" width="560"> </p> <p align="center"> <a href="https://pypi.org/project/agent-memory-os/"><img src="https://img.shields.io/pypi/v/agent-memory-os?color=4F46E5" alt="PyPI"></a> <a href="https://pypi.org/project/agent-memory-os/"><img src="https://img.shields.io/pypi/pyversions/agent-memory-os" alt="Python"></a> <a href="https://github.com/yamantaka520/Agent-Memory-OS/actions"><img src="https://img.shields.io/github/actions/workflow/status/yamantaka520/Agent-Memory-OS/ci.yml?branch=main&label=CI" alt="CI"></a> <a href="https://hub.docker.com/r/yamantaka520/agent-memory-os"><img src="https://img.shields.io/docker/pulls/yamantaka520/agent-memory-os?color=2496ED&logo=docker&logoColor=white" alt="Docker Pulls"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License"></a> <a href="https://glama.ai/mcp/servers/yamantaka520/Agent-Memory-OS"><img src="https://glama.ai/mcp/servers/yamantaka520/Agent-Memory-OS/badges/score.svg" alt="Glama score"></a> </p> <p align="center"> <b>English</b> · <a href="README.zh-Hant.md">繁體中文</a> </p>

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.

<p align="center"> <a href="#why">Why</a> · <a href="#how-it-compares">Compare</a> · <a href="#install">Install</a> · <a href="#quickstart">Quickstart</a> · <a href="#features">Features</a> · <a href="#federation-multi-host-sync">Federation</a> · <a href="#web-ui">Web&nbsp;UI</a> · <a href="docs/USER_GUIDE.md">User&nbsp;Guide</a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/yamantaka520/Agent-Memory-OS/main/assets/console-demo.gif" alt="AgentMemoryOS web console — dashboard, browse, association graph" width="820"> <br>_{The built-in web console: token-usage by agent/team/project, memory browse, and the ACL-safe association graph.} </p>

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:<id> memory; a project (a subset of the team) sees project:<id> 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:<id> 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:<id> memory reaches the whole team, project:<id> 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.

| | AgentMemoryOS | Mem0 | Zep / Graphiti | |---|---|---|---| | Run it | One SQLite file, pip install | Self-host (configure LLM + vector DB) or hosted | Zep Cloud, or self-host Graphiti on Neo4j/FalkorDB | | Core needs an LLM | No (FTS5 + optional local vectors) | Yes (LLM extraction, e.g. gpt-5-mini) | Yes (LLM builds the temporal graph) | | External services | None required | LLM API + vector store | Graph DB + LLM + embeddings (3+ systems to self-host) | | Scope / ACL model | Private / agent / team / project / global — hard gate before ranking | Per user / agent / session id | Per user / session graph | | Cross-node federation | Yes — memories and org structure converge; revocation propagates | Centralized store | Centralized (Cloud or your graph DB) | | Built-in MCP server | Yes | Via SDK | Via SDK | | License / self-host | Apache-2.0, fully OSS | OSS core; graph & advanced tiers paid | Community Edition deprecated; self-host = raw Graphiti |

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