{ "markdown": "\n

\n \"Agent\n

\n\n

\n \"PyPI\"\n \"Python\"\n \"CI\"\n \"Docker\n \"License\"\n \"Glama\n

\n\n

\n English · 繁體中文\n

\n\nA **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.\n\n

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

\n\n

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

\n\n## Why\n\nReal 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:\n\n- **Per-agent memory** is the floor, not the ceiling: durable facts, preferences, procedures, and lessons that survive across sessions.\n- **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.\n- **Federation** keeps a mesh honest: memories *and* the org structure (teams/projects/memberships) converge across nodes, so `project:` means the same thing everywhere.\n- **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.\n\n## Features\n\n- **Local-first, zero-dependency core** — one SQLite file (FTS5), no server required. `pip install` and go.\n- **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.\n- **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.\n- **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.\n- **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.\n- **Dynamic context packs** — token-budgeted, auditable memory selection per prompt (`context_pack_report()` explains every include/exclude decision).\n- **Truth arbitration** — duplicate suppression, contradiction detection (`CONFLICT` markers), and reserved budget for core memories.\n- **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).\n- **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`).\n- **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.\n- **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.\n- **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.\n\n## How it compares\n\nMost agent-memory systems optimize for LLM-driven extraction at hosted scale.\nAgentMemoryOS optimizes for a different point: **local-first, team-scoped, and\nfederated** — memory you run yourself, shared across a fleet under a hard ACL.\nThis is a *positioning* comparison (architecture, not a benchmark); verify each\nrow against the projects' current docs.\n\n| | **AgentMemoryOS** | Mem0 | Zep / Graphiti |\n|---|---|---|---|\n| **Run it** | One SQLite file, `pip install` | Self-host (configure LLM + vector DB) or hosted | Zep Cloud, or self-host Graphiti on Neo4j/FalkorDB |\n| **Core needs an LLM** | **No** (FTS5 + optional local vectors) | Yes (LLM extraction, e.g. gpt-5-mini) | Yes (LLM builds the temporal graph) |\n| **External services** | **None required** | LLM API + vector store | Graph DB + LLM + embeddings (3+ systems to self-host) |\n| **Scope / ACL model** | Private / agent / **team / project** / global — hard gate before ranking | Per user / agent / session id | Per user / session graph |\n| **Cross-node federation** | **Yes** — memories *and* org structure converge; revocation propagates | Centralized store | Centralized (Cloud or your graph DB) |\n| **Built-in MCP server** | **Yes** | Via SDK | Via SDK |\n| **License / self-host** | Apache-2.0, fully OSS | OSS core; graph & advanced tiers paid | Community Edition deprecated; self-host = raw Graphiti |\n\nMem0 and Zep are strong at LLM-based extraction and managed-scale retrieval —\nthings AgentMemoryOS deliberately doesn't do. Reach for AgentMemoryOS when you\nwant a dependency-light memory you own, shared correctly across a *team* of\nagents, that keeps working offline and syncs on your terms.\n\n## Install\n\n```bash\npip install 'agent-memory-os[full]' # recommended: everything (Web UI, MCP, turbovec)\n```\n\nOr pick pieces: `agent-memory-os` (core, zero dependencies), `[api]` (Web UI), `[mcp]` (MCP server), `[semantic]` (turbovec vector recall).\n\n**Docker:** the prebuilt multi-arch image is the complete AgentMemoryOS (web console + MCP server + CLI); the first argument picks the mode:\n\n```bash\ndocker run -p 8000:8000 -v amos-data:/data yamantaka520/agent-memory-os # web console (default)\ndocker run -i --rm yamantaka520/agent-memory-os mcp # stdio MCP server\ndocker run --rm -v amos-data:/data yamantaka520/agent-memory-os check # any CLI command\n```\n\nOr `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).\n\nRequires Python 3.11+ with SQLite FTS5 (included in standard CPython builds).\n\nAfter installing, run two commands:\n\n```bash\nagent-memory doctor # verifies FTS5, turbovec, and the other extras\n # (add --install to auto-install anything missing)\nagent-memory token create # protects the Web UI API with a bearer token\n```\n\nThe token is stored at `/web_token` (mode 600); `agent-memory-web` picks\nit up automatically and the console prompts for it on first use. Manage it\nlater with `agent-memory token show|rotate|disable`. Two narrower tiers exist:\n`--readonly` (GET-only) and `--sync` (federation routes only — hand this to a\npeer instead of the admin token).\n\n## Quickstart\n\n> 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`.\n\n```python\nfrom agent_memory_os import MemoryClient, RecallProfile\n\nclient = MemoryClient(home=\"~/.agent-memory\")\n\n# Write memories with ownership and visibility\nclient.add(\"User prefers dark mode.\", owner=\"mizuki\", type=\"preference\",\n visibility=[]) # private to owner\nclient.add(\"Deploy target is port 8000.\", owner=\"neo\", type=\"environment\",\n visibility=[\"global\"]) # visible to every agent\n\n# Requester-aware search: each agent sees only what it may see\nhits = client.search(\"deploy port\", requester_agent_id=\"neo\")\n\n# Token-budgeted context pack for the prompt, with reinforcement loop closed\npack = client.context_pack(\"deploy port\", requester_agent_id=\"neo\",\n max_tokens=1200, auto_reinforce=True)\n\n# Associate memories; linked memories resonate into future recalls\na = client.add(\"Staging deploy failed with database lock.\", visibility=[\"global\"])\nb = client.add(\"Always snapshot before schema changes.\", visibility=[\"global\"])\nclient.link(a.id, b.id, relation=\"caused_by\", weight=0.8)\n\n# Persist an agent persona: soft ranking bias per memory type\nclient.save_profile(RecallProfile(agent_id=\"neo\",\n type_weights={\"procedure\": 1.5, \"note\": 0.7}))\n\n# Periodic hygiene: merge duplicates, synthesize concept memories\nclient.consolidate()\n```\n\n## Architecture\n\n```text\nquery\n -> candidate providers (FTS5 | vector sidecar | resonance graph | fallback)\n -> merge/dedupe by stable memory_id\n -> rejoin authoritative rows from SQLite\n -> ACL hard gate -> expires_at hard gate\n -> scoring (relevance x importance x confidence x freshness x reinforcement)\n -> per-agent profile re-weighting (soft)\n -> truth arbitration + context budget allocation\n```\n\nDesign invariants:\n\n- The SQLite `memories` table is the single source of truth; FTS/vector indexes are disposable and rebuildable (`rebuild_indexes()`).\n- Candidate providers return IDs and scores only — content is always re-read through SQLite behind the ACL and expiry hard gates.\n- Association edges (`memory_links`) are authoritative data, survive index rebuilds, decay when unused, and never let an invisible memory bridge two visible ones.\n\nSee [SPEC.md](SPEC.md) for the full contract.\n\n## Storage engines: SQLite + turbovec\n\nAgentMemoryOS uses **two storage layers with strictly different authority**:\n\n- **SQLite** (always on) is the single source of truth: memories, links,\n profiles, and the FTS5 lexical index all live in one `memories.db` file.\n- **turbovec** (installed with `[full]` / `[semantic]`) is the semantic vector\n engine: an in-memory quantized index that recalls memories by meaning rather\n than keywords. It is deliberately **disposable** — it returns candidate\n `memory_id`s and scores only; every candidate rejoins SQLite and passes the\n ACL/expiry hard gates before its content can be used, and the index can be\n dropped and rebuilt at any time without touching the truth store.\n\nSemantic recall works out of the box:\n\n```python\nclient = MemoryClient(home=\"~/.agent-memory\", semantic=\"auto\")\n```\n\n`semantic=\"auto\"` wires in a self-syncing turbovec index over a built-in\ndeterministic hashing embedder (no model downloads; typo- and\nmorphology-tolerant lexical vectors). The index rebuilds itself whenever the\nmemories table changes and degrades silently to lexical + resonance recall\nwhen the backend isn't installed. For deeper semantics, plug any embedding\nmodel into `TurbovecSemanticCandidateProvider.from_vectors(...)` with your\nown `embed_query`. `agent-memory doctor` confirms the backend is importable.\n\n## Memory lifecycle & retention\n\n```bash\nagent-memory retention # archive expired + memories idle 4+ half-lives\nagent-memory retention --half-lives 0 # expired only\nagent-memory check # SQLite + FTS + link-graph integrity\n```\n\nArchived memories leave recall entirely but stay restorable (Web UI → Tools →\nRetention & archive, or `POST /api/archive/{id}/restore`). Pinned and\nauthority-track memories are never archived by decay. Databases self-migrate\nthrough a versioned, forward-only migration table (`agent-memory check`\nreports the schema version).\n\n## Backup & restore\n\n```bash\nagent-memory backup ~/backups/memories-$(date +%F).db --keep 14 # rotate, keep 14\nagent-memory restore ~/backups/memories-2026-07-11.db --force\n```\n\nBackups use SQLite's online backup API, so they are consistent even while\nagents are writing. `--keep N` rotates out older backups in the same name\nseries (and can never delete the live database). Disposable indexes rebuild\nautomatically after a restore.\n\n**Upgrades & health.** `agent-memory update` checks PyPI, upgrades, and restarts\nthe running console; `--check` reports only. Point health checks at `GET /healthz`\n(200/503) and a Prometheus scraper at `GET /metrics`.\n\n## Multi-agent projects\n\nOne project can mix **Claude Code, Codex, OpenClaw, and multiple Hermes\nprofiles** against a single store. Register each agent with its teams —\nin the console's **Agents** tab or via API — and team members automatically\nsee `team:` memories with no extra wiring:\n\n```bash\ncurl -X POST localhost:8000/api/agents -H 'content-type: application/json' \\\n -d '{\"id\": \"cc-main\", \"kind\": \"claude-code\", \"teams\": [\"apollo\"]}'\n```\n\nOr declare the whole fleet as code — `/agents.toml` is re-applied\nevery time the store opens (file-listed agents are file-authoritative;\nmanually registered agents are untouched):\n\n```toml\n[agents.cc-main]\nkind = \"claude-code\"\nteams = [\"apollo\", \"shared-infra\"] # multiple teams = multiple projects\n\n[agents.hermes-neo]\nkind = \"hermes\"\nteams = [\"apollo\", \"ops\"]\n```\n\nEach MCP server declares its identity with `AGENT_MEMORY_AGENT_ID`, so\nmemories default to that agent as owner and every recall carries its team\nACL. Ship one project's shared memory to another host with\n`agent-memory sync export apollo.jsonl --team apollo`.\n\n## Federation (multi-host sync)\n\n```bash\n# on the host being joined: mint a sync-scoped token for the peer\nagent-memory token create --sync # prints amos_sync_… (federation routes only)\n\n# one-time, on the joining host\n# easiest: pairing (one command on each side — tokens/mesh key exchanged for you)\n# on the existing node: agent-memory team invite apollo\n# on the joining node: agent-memory join --url http://that-node:8000\n# or wire a peer by hand:\nagent-memory peers add https://other-host:8000 --peer-token \n\n# converge with every registered peer (pull + push, deterministic merges)\nagent-memory sync auto\n```\n\nPeers are stored per-home; `sync auto` (or the console's \"Sync mesh now\")\nconverges bidirectionally with each peer — last-writer-wins on memories and\nprofiles, strongest-wins on links — and unreachable peers fail individually,\nnever fatally. File bundles (`sync export/import`) cover air-gapped moves.\nPair with `agent-memory service install` and a cron/timer entry for\ncontinuous mesh sync.\n\n**Encrypt the wire.** Give every node the same mesh key and sync bundles are\nencrypted app-layer (Fernet), so memory content stays confidential even over\nplain HTTP or through a proxy — the key is a separate secret that never travels\non the wire:\n\n```bash\nagent-memory sync genkey # prints amos_sk_… ; needs the [secure-sync] extra\nexport AGENT_MEMORY_SYNC_KEY=amos_sk_… # set the SAME value on every node\n```\n\nThe sync-scoped token still rides in the `Authorization` header, so prefer\n`https://` peer URLs (certificate-verified) for non-localhost peers to protect\nthe token too. See [SECURITY.md](SECURITY.md) for the exact guarantees.\n\n## Agent integrations\n\nStep-by-step guides for wiring AgentMemoryOS into common agents — click a tile:\n\n

\n \"Claude\n \"Codex\n
\n \"OpenClaw\n \"Hermes\n

\n\nHermes Agent gets a **native memory-provider plugin** (not just MCP):\n`pip install agent-memory-os && agent-memory hermes install`, then pick\n`agent-memory-os` in `hermes memory setup` — recall is injected every turn and\n`amos_*` tools carry the team/project ACL. No API key, no LLM. See the\n[Hermes guide](docs/integrations/hermes-agent.md).\n\nAny MCP-capable agent can use the same pattern: run\n`python -m agent_memory_os.mcp_server` as a stdio MCP server pointing at a\nshared `AGENT_MEMORY_HOME`.\n\n## MCP server\n\n\"AgentMemoryOS\n\n```bash\npip install 'agent-memory-os[mcp]'\npython -m agent_memory_os.mcp_server\n```\n\nWire it into Claude Code in one line (set the agent identity so memories are owned correctly):\n\n```bash\nclaude mcp add agent-memory --env AGENT_MEMORY_AGENT_ID=cc-main -- python -m agent_memory_os.mcp_server\n```\n\nTools (12): `memory_add` (with a `share` arg for team/project/global), `memory_search`, `memory_context_pack`, `memory_orchestrate_context`, `memory_link`, `memory_update`, `memory_share`, `memory_recall_feedback`, `memory_consolidate`, `memory_offload_context`, `memory_reload_context`, `memory_snapshot_diff`. Set `AGENT_MEMORY_AGENT_ID` so each agent acts under its own identity — and two agents pointed at the same home instantly share `team:`/`project:` memories.\n\n## Web UI\n\n```bash\npip install 'agent-memory-os[api]'\nagent-memory-web --host 127.0.0.1 --port 8000 --home ~/.agent-memory-web\n```\n\nThe console speaks **English, 繁體中文, 简体中文, 日本語, and 한국어** — auto-detected from the browser, switchable in the header. It 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.\n\nEndpoints: health/stats/dashboard/integrity · memories CRUD + browse · search / context-pack / orchestrate · links + graph · recall feedback · share / revoke / audit · consolidate / retention / archive+restore · agents registry · peers + mesh sync · bundle export/import · owner list / reassign / purge · fleet status/trigger (Ed25519-signed cross-node ops). Full table in the [User Guide](docs/USER_GUIDE.md).\n\nSearch, 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 ` (or `AGENT_MEMORY_WEB_TOKEN`).\n\nNote: keep the `--home` database on a local disk. Network filesystems (NFS/SMB) can fail SQLite FTS5 schema creation with `database is locked`.\n\n### Run as a login service (macOS / Linux / Windows)\n\n```bash\nagent-memory service install [--host 127.0.0.1] [--port 8000]\nagent-memory service status | start | stop | restart | uninstall\n```\n\n`install` registers the console with the native service manager so it starts\nautomatically at login and restarts on failure — launchd LaunchAgent on\nmacOS, a systemd user unit on Linux, a Task Scheduler logon task on Windows.\nNo admin rights required; the service runs the exact Python environment it\nwas installed from, and logs to `/logs/web.log`. On Linux, run\n`loginctl enable-linger $USER` if it must start at boot without a login.\nAdd `--dry-run` to preview the actions. CI runs the full test suite on\nUbuntu, macOS, and Windows across Python 3.11–3.13.\n\n## Development\n\n```bash\npip install -e '.[dev]'\npytest\n```\n\n## Status\n\n**Stable — `1.x`.** The contracts above are implemented, covered by the test\nsuite (300+ tests across a 3-OS CI matrix, plus a migration upgrade-path job),\nand audited by repeated fan-out code + security reviews (reports under\n[`docs/reviews/`](docs/reviews/)). Performance is verified at 10k memories (add\n0.17 ms, search <1 ms, context-pack 7.8 ms). The database self-migrates forward;\nsee the [CHANGELOG](CHANGELOG.md) for what each release added.\n\n## Documentation\n\n- **[User Guide](docs/USER_GUIDE.md)** — concepts, full CLI / HTTP API / MCP references, multi-agent and federation walkthroughs, ops checklist\n- **[Docker guide](docs/DOCKER.md)** — `docker`/`docker compose` startup, config via env, two-node sync mesh\n- [SPEC](SPEC.md) — contracts and invariants, by milestone\n- **[Security](SECURITY.md)** & **[Threat model](docs/THREAT_MODEL.md)** — disclosure policy, trust boundaries, and honest known limitations\n- **[Embeddings & scale](docs/EMBEDDINGS.md)** — plug in a real embedding model; behaviour from 10k to 1M memories\n- **[Importers](docs/IMPORTERS.md)** — migrate from Mem0 / Zep / ChatGPT · **[Compatibility](COMPATIBILITY.md)** — the 1.x semver promise\n- **[Reviews & reports](docs/reviews/)** — fan-out code + security reviews (through the 1.x line), the performance/security report, and the validation harness (`scripts/validation_run.py`)\n- [CHANGELOG](CHANGELOG.md) · [Roadmap](docs/ROADMAP.md) · [Integration guides](docs/integrations/claude-code.md)\n\n## License\n\n[Apache License 2.0](LICENSE)\n", "bytes": 23311, "sha": "af9eb239fffecce4e241a282690a65be6af848e647fef9d0c63cb3649ea6fe23", "repo_slug": "yamantaka520/agent-memory-os", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_yamantaka520_agent_memory_os_92194feb/readme" }