Agent-Memory-OS

Agent-Memory-OS is a local-first memory system for AI agent teams. Its goal is not merely to provide memory for a single agent, but to build a shared memory network for multi-agent collaboration: managing private, team, and project-level memories under strict ACLs (access control lists), supporting associative recall, and keeping multiple nodes (and their organizational structures) consistent through federated sync. The entire system is based on a single SQLite file, with a zero-dependency core, and is licensed under Apache-2.0.

1. Purpose and Positioning Real agent work often happens in teams—a project may mix Claude Code, Codex, OpenClaw, and multiple Hermes configurations, across multiple teams and projects, distributed across one or more machines. These agents need to share the right knowledge with the right teammates while keeping what should be private private. Agent-Memory-OS provides:

• Per-agent memory: persisted facts, preferences, procedures, and lessons that survive across sessions.
• Team and project memory: teams see team:<id> memories, projects (subsets of teams) see project:<id> memories, with no leakage across boundaries. Membership is a first-class citizen, manageable, and drives ACLs.
• Federated sync: memories and organizational structures (teams/projects/memberships) converge across nodes, so that project:<id> means the same thing on all nodes.
• Local-first: avoids the latency, cost, and privacy trade-offs of cloud memory platforms—memories are stored in a local SQLite file, and each prompt receives only the relevant, budgeted slice.

1. Main Capabilities

• Local-first, zero-dependency core: a single SQLite file (FTS5), no server required, usable after pip install.
• Teams and projects as first-class citizens: a team is a collection of node members, and project members are a subset of its team. team:<id> memories reach the entire team, while project:<id> memories are restricted to that project; this is a hard ACL, manageable via console/CLI/API. Removing a member immediately rescopes recall; deleting a scope revokes its memories.
• Federated sync and trust model: portable bundles plus peer sync, using last-writer-wins with tombstones, so that memories, links, configs, and organizational structures converge. Each peer policy (shared/full/team:/project:) is a mandatory authorization scope: a peer can only assert memberships within its own scope, can only narrow memory visibility, and can never expand it—Bundles cannot escalate privileges across scopes.
• Propagable revocation: independent ACL clocks propagate post-hoc sharing/revocation along the mesh; peers that have already synced that memory will actually have access revoked, without interfering with the decay clock.
• Requester-aware ACL: each agent has private, agent, team, project, and global memory; visibility is a hard gate enforced before ranking, never a soft score. The candidate index returns only IDs; content is re-read through the gate.
• Dynamic context packs: per-prompt token budgeting, auditable memory selection (context_pack_report() explains every include/exclude decision).
• Truth arbitration: duplicate suppression, contradiction detection (CONFLICT flag), and reserved budget for core memories.
• Associative recall (resonance): the authoritative memory_links graph lets related memories surface even without shared query terms; traversal is ACL-safe (invisible nodes cannot be traversed).
• Hebbian reinforcement: memories recalled together strengthen links (record_recall, or auto_reinforce=True on a context pack); unhelpful recalls weaken links and confidence (helpful=False).
• Per-agent recall configuration: different agent roles weight memory types differently (engineers favor procedure, companions favor preference); configuration is persisted in the database and only reweights ranking, never bypasses ACL.
• Memory lifecycle: exponential/linear decay, fixed, hard expiry, and a write-side consolidate() process that merges duplicates and synthesizes strong co-occurrence clusters into concept memories.
• Optional sidecars: semantic vector candidates (turbovec), MCP server, and FastAPI Web UI, all provided as extras; every candidate is re-fed into SQLite and must pass the hard gate before use.

III. How to Use Install: pip install agent-memory-os (zero dependencies for the core), optional extras such as [api] (Web UI), [mcp] (MCP server), [semantic] (turbovec vector recall). Docker: prebuilt multi-architecture images include the full AgentMemoryOS (Web console + MCP server + CLI); the first argument selects the mode. After docker compose up -d, the console is at http://localhost:8000，记忆持久化在卷中。 Requirements: Python 3.11+, SQLite FTS5 (included in standard CPython builds). After installation, run two commands to start; the token is stored in <home>/web_token (permissions 600), agent-memory-web reads it automatically, and the console prompts for it on first use. It can later be managed with agent-memory token show|rotate|disable. There are two narrower tiers: --readonly (GET only) and --sync (federation routes only, can be handed to a peer instead of an admin token). Runnable script example: examples/team_memory.py shows three agents sharing one store under hard ACL, about 40 lines, run python examples/team_memory.py. Agent integration: Hermes Agent has a native memory provider plugin (pip install agent-memory-os && agent-memory hermes install), select agent-memory-os in the hermes memory settings, recall is injected every turn, amos_* tools carry team/project ACL, no API key or LLM required. Any MCP-capable agent can run python -m agent_memory_os.mcp_server as a stdio MCP server pointed at a shared AGENT_MEMORY_HOME. Claude Code one-line integration (set the agent identity to attribute memories correctly). Tools (12): memory_add (with a share parameter 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. Setting AGENT_MEMORY_AGENT_ID makesEach agent acts as its own identity, and two agents pointing to the same home immediately share team:/project: memory. Web console: supports English, Traditional Chinese, Simplified Chinese, Japanese, and Korean (automatically detected from the browser and switchable in the header). It provides a statistics dashboard, search and recent browsing, an interactive relationship graph view, context package previews and per-memory decisions, as well as add/link/merge tools, all driven by the global "acting as" identity.

1. Applicable scenarios

• Multi-agent collaborative projects: one project mixes Claude Code, Codex, OpenClaw, and multiple Hermes configurations, sharing memory while maintaining boundaries.
• Multi-team, multi-project enterprise environments: requires strict team/project memory isolation and manageable membership.
• Offline or privacy-sensitive scenarios: local-first, with memory stored in local SQLite, able to work offline and sync on your own terms.
• Multi-host federation: converge memory and organizational structure across nodes via portable bundles or peer-to-peer sync.

1. Limitations and known constraints

• Performance has been verified: with 10k memories, add takes 0.17 ms, search <1 ms, and context package 7.8 ms.
• The database must be placed on a local disk; network file systems (NFS/SMB) may cause SQLite FTS5 schema creation to fail with database is locked.
• Requests without a requester run with an unrestricted administrator view—bind to localhost only, or require a bearer token on every API route via --token <secret> (or AGENT_MEMORY_WEB_TOKEN).
• Sync scoped tokens are still sent via the Authorization header; for non-local peers it is recommended to use https://（证书验证）以保护令牌。
• The semantic vector backend (turbovec) is optional, and silently degrades to lexical + resonance recall when not installed.
• 1.x stable release, with 300+ tests covering a 3-OS CI matrix, and the database self-migrates forward.
• Official pricing or fee information is not provided in the materials, and is not yet available.