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><sub>The built-in web console: token-usage by agent/team/project, memory browse, and the ACL-safe association graph.</sub>
</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

```bash
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:

```bash
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](docs/DOCKER.md) (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:

```bash
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`](examples/team_memory.py) shows three agents sharing one store under a hard ACL in ~40 lines — `python examples/team_memory.py`.

```python
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=