AgentMemory
hsuanshao38 个星标
Self-hosted memory service for AI agents that work in teams, written in Rust: layered L0→L3 memory, async LLM distillation, hybrid BM25 + vector recall, and department/team/member isolation. SQLite or
- 传输方式
- stdio
- 状态
- 本地
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令？ 两种安装方式的区别
English | 繁體中文
Self-hosted, team-aware long-term memory for AI agents. AgentMemory gives Claude Code, Codex, Antigravity, Hermes and any MCP client a memory that persists across sessions. It captures each conversation, distils it into facts, scenes and a persona in the background, and recalls what is relevant before every prompt. It all runs on your own servers.
claude, codex or agy.upgrade.sh that backs up first.amem CLI plugs into Claude Code, Codex, Antigravity and Hermes hooks, and serves recall over MCP. It redacts secrets before anything leaves the machine and queues while the server is unreachable.Written in Rust (memory-core, amem) and TypeScript (Panel), following Clean Architecture: domain ← application ← infrastructure / gateway ← server.
git clone https://github.com/hsuanshao/AgentMemory.git && cd AgentMemory
./install.sh
The installer asks, in order:
127.0.0.1) / other machines over plain HTTP / other machines over HTTPS with Caddy (TLS)[!IMPORTANT] Rootless Docker: memory-core sees every client as one address, so 20 wrong keys from anyone in 15 minutes lock everyone out for 15 minutes. Either set
AGENT_MEMORY_THROTTLE_LOCK_AFTER=0in.env(delays and the audit log stay), or put a reverse proxy on the host that sees the real address and list it inAGENT_MEMORY_TRUSTED_PROXIES(UPGRADE).
It then generates a Gateway API key and database password, writes .env with mode 600 (including COMPOSE_PROFILES), starts the services and waits for the health checks, and finally creates the first admin and shows a one-time login user key.
INSTALL_STORAGE=postgres-docker INSTALL_COORDINATION=redis-docker ./install.sh --non-interactive (see ./install.sh --help for the variables).docker compose up -d; .env carries the same profiles and settings.host.docker.internal instead of localhost.Manual installation (without install.sh):
cp .env.example .env # set at least AGENT_MEMORY_API_KEY
docker compose up -d --build
curl -s -X POST http://localhost:8420/v3/internal/meta/user/init-admin \
-H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
-H "x-memory-department-id: default" -H "content-type: application/json" \
-d '{"username":"admin"}'
Or start each service separately:
docker build -f docker/core.Dockerfile -t memory-core:local .
docker run --rm -p 8420:8420 -e AGENT_MEMORY_API_KEY=change-me \
-e AGENT_MEMORY_LLM_API_KEY=sk-... -v memory-core-data:/data memory-core:local
docker build -t memory-panel:local panel
docker run --rm -p 8125:8125 -e CORE_URL=http://host.docker.internal:8420 memory-panel:local
Sign in to the Panel with the admin user key. Under Metadata, a system admin creates users (each gets a user key, shown once), creates teams, assigns users to teams with a role, and creates agents. Everyone else gets a read-only Panel.
Clients (agents on any machine) authenticate with their user key only; they never need AGENT_MEMORY_API_KEY. Every memory call names a team_id and an agent_id the user belongs to, and members only read and write their own conversations and facts; the scenes and persona of an agent are shared by the people who use it. docs/COLLABORATION.md explains departments, teams, users and agents, from choosing a layout to how isolation is enforced. A department exists once init-admin has run for it; requests that name any other department are refused. See docs/API.md for the exact rules and docs/ARCHITECTURE.md for how it fits together.
Server and agents on different machines? Follow docs/REMOTE-CLIENTS.md. It covers TLS, issuing keys, installing the amem client and the Claude Code, Codex, Antigravity and Hermes integrations, and the client side of an upgrade.
Upgrading from an earlier version? Run ./upgrade.sh in your install directory, after updating the code. docs/UPGRADE.md describes the same steps by hand, plus how to roll back.
Outgrowing SQLite? ./migrate-to-postgres.sh moves an existing install to PostgreSQL: users, keys, memories and skills come along, and clients need no change. docs/MIGRATE-TO-POSTGRES.md covers when to move, the manual steps and how to go back.
Removing it: ./uninstall.sh client removes the client from a machine that runs agents: the Claude Code, Codex, Antigravity and Hermes integrations plus amem. On the server, ./uninstall.sh server removes the containers and images and keeps the data; add --purge-data to delete the data as well. Add --dry-run to either command to see what would be removed first. Details and the manual steps are in docs/UNINSTALL.md.
cargo test --workspace # unit + integration + end-to-end tests (Postgres/Redis tests skipped by default)
# Run integration tests against real Postgres and Redis:
docker run -d --rm --name amem-pg -e POSTGRES_PASSWORD=test -p 25432:5432 pgvector/pgvector:pg17
docker run -d --rm --name amem-redis -p 26379:6379 redis:8.4.0
AGENT_MEMORY_TEST_POSTGRES_URL=postgres://postgres:[email protected]:25432/postgres \
AGENT_MEMORY_TEST_REDIS_URL=redis://127.0.0.1:26379 cargo test --workspace
AGENT_MEMORY_LLM_API_KEY=sk-... cargo run -p memory-server
cd panel && npm install && npm run dev # Panel (Vite + Hono)
/v3/conversation/add ──► L0 conversation (SQLite + FTS5)
│ warm-up 1→2→4→every N turns, or idle 600s
▼
L1 extraction (LLM: context segmentation + persona/episodic/instruction, priority threshold)
└─ dedup: hybrid-recall candidates → LLM decides store / update / merge / skip
│ delay 90s and ≥ 900s since last L2; then a sweep every 3600s
▼
L2 scenes (shared per team+agent; UPDATE > MERGE > CREATE, heat, max 15, META header)
│ cold start / every 50 new memories / when a scene requests an update
▼
L3 Persona (persona.md + auto-appended Scene Navigation)
Recall (/v3/recall): strip previously injected blocks → L1 hybrid retrieval (BM25 + vector + RRF k=60, falls back to BM25 without embeddings) → thresholds, count and character budgets → output <relevant-memories> plus <user-persona> and <scene-navigation>.
Chinese full-text search: text is tokenized into "overlapping CJK bigrams + Latin words" before going to FTS5 — no dictionary needed, and results are predictable.
crates/
├── memory-domain/ Entities, value objects, pure policies (isolation, RRF, ACL, Skill, scene format, trigger rules)
├── memory-application/ Use cases and ports (memory, recall, pipeline, metadata, Skill)
├── memory-infrastructure/ SQLite / filesystem / OpenAI client / background workers
├── memory-gateway/ axum v3 HTTP API, envelopes, validation, CORS
├── memory-server/ Configuration (memory-core.yaml compatible) and wiring (composition root)
└── memory-client/ `amem` client: recall/capture hooks, redaction, offline queue, MCP server
clients/ Claude Code, Codex and Antigravity plugins, Hermes memory provider
panel/ TypeScript Monitor Panel (Hono BFF + React)
docker/core.Dockerfile Core image (bundles the claude and agy CLIs)
install.sh Interactive installer
upgrade.sh Upgrade an existing install
uninstall.sh Remove the client or the server
docs/ARCHITECTURE.md Architecture overview (mermaid diagrams)
docs/API.md API reference and design trade-offs
docs/REMOTE-CLIENTS.md Server/client split deployment guide
docs/UPGRADE.md Upgrading an existing install (upgrade.sh, manual steps, rollback)
docs/UNINSTALL.md Removing the client or the server (uninstall.sh, manual steps)
docs/COLLABORATION.md Departments, teams, users and agents: layouts, setup, isolation internals
docs/MIGRATE-TO-POSTGRES.md Moving an install from SQLite to PostgreSQL (script, manual steps, rollback)
docs/ops/ For maintainers: testing, releases, storage-migration internals
Config file keys (server, data, llm, memory.pipeline, memory.recall, memory.embedding, skill, …); see config/memory-core.example.yaml for an example. Common environment variables:
AGENT_MEMORY_POSTGRES_URL=postgres://user:pass@host:5432/db../migrate-to-postgres.sh, see docs/MIGRATE-TO-POSTGRES.md.agent_memory and am_* schemas). With embeddings enabled, the vector extension must be created: run as superuser, or have a DBA run CREATE EXTENSION vector beforehand.AGENT_MEMORY_REDIS_URL=redis://[:password@]host:6379/0; all keys are prefixed with coordination.redis.keyPrefix (default agent_memory).coordination.redis.queueLeaseMs, default 15 minutes) that is extended automatically while running; if a node crashes, the job is redelivered after the lease expires. In rare cases a job may run twice, which the pipeline is designed to tolerate.SET NX PX and renewed while held (lockTtlMs, default 10 minutes).memory.embedding.provider is not none); stores.vectorIndex in /health reports sqlite-vec, brute-force, pgvector-hnsw, pgvector-exact or none.Besides an OpenAI-compatible API (API key), memory-core can call a local command-line tool to generate memories, with a specified project directory as the tool's working directory (so the tool can read that project's settings and context):
llm:
provider: cli
timeoutMs: 180000
cli:
command: claude # or ollama, or any tool that reads stdin and prints a text answer
args: ["-p"] # ollama example: ["run", "llama3.1"]
promptMode: stdin # use arg for tools that only take arguments, and put {prompt} in args
workingDir: ~/projects/my-app
maxConcurrency: 2
Equivalent environment variables: AGENT_MEMORY_LLM_PROVIDER=cli, AGENT_MEMORY_LLM_CLI_COMMAND, AGENT_MEMORY_LLM_CLI_ARGS (JSON array or whitespace-separated), AGENT_MEMORY_LLM_CLI_PROMPT_MODE, AGENT_MEMORY_LLM_CLI_WORKDIR, AGENT_MEMORY_LLM_CLI_PASS_ENV.
PATH, HOME, locale, certificate and proxy variables, its own settings (ANTHROPIC_*/CLAUDE_* for claude, OPENAI_*/CODEX_* for codex, GEMINI_*/GOOGLE_* for agy), llm.cli.env, and what llm.cli.passEnv names; never AGENT_MEMORY_* (DISTILLATION §6).timeoutMs, and the child process is killed on timeout; a non-zero exit code or empty output is treated as the LLM being unavailable and left to the pipeline to retry.By default docker/core.Dockerfile installs three CLIs with their official native install scripts (no npm; checksums verified), and runs them as a non-root service user:
claude-config → ~/.claude, antigravity-config → ~/.gemini, codex-config → ~/.codex), so it survives container rebuilds.PROJECT_DIR; it is mounted at /workspace in the container and used as the CLI's working directory.Not logged in · Please run /login), and the pipeline retries.agy receives the prompt as an argument, so it is subject to Linux's 128 KiB single-argument limit; prompts beyond that fail with an error.agy requires a CPU with AES-NI (in VMs, set the CPU type to host).--build-arg INSTALL_CLAUDE=false, --build-arg INSTALL_ANTIGRAVITY=false, --build-arg INSTALL_CODEX=false; pin the Claude Code version with --build-arg CLAUDE_VERSION=latest or a specific version number.See docs/API.md for details. Highlights:
/v3/skill/export.Issues and pull requests are welcome. See CONTRIBUTING.md for the development setup, checks and conventions, the Code of Conduct, and SECURITY.md to report a vulnerability privately.
Thanks to everyone who has contributed (emoji key). To credit someone, comment on their issue or pull request: @all-contributors please add <github-user> for code, doc, and the bot opens a pull request that updates this list.
From 0.4.0 the server is licensed under the Business Source License 1.1: free for evaluation, personal and non-profit use, and for an organization with up to 1 department and 10 members; larger production use needs a commercial license. Each version becomes Apache 2.0 four years after release. The amem client and the agent plugins stay MIT, and 0.3.2 and earlier remain MIT. See COMMERCIAL.md.
The layered memory and Skill design draws on ideas from the open-source project TencentDB Agent Memory (MIT); this project is an independent implementation, contains none of its code, and does not connect to any Tencent services.
Self-hosted memory service for AI agents that work in teams, written in Rust: layered L0→L3 memory, async LLM distillation, hybrid BM25 + vector recall, and department/team/member isolation. SQLite or
概览
Self-hosted memory service for AI agents that work in teams, written in Rust: layered L0→L3 memory, async LLM distillation, hybrid BM25 + vector recall, and department/team/member isolation. SQLite or Postgres, any OpenAI-compatible LLM.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
AgentMemory 通过 stdio 在本地运行。
上次检查时间：2026-10-27。 Self-hosted memory service for AI agents that work in teams, written in Rust: layered L0→L3 memory, async LLM distillation, hybrid BM25 + vector recall, and department/team/member isolation. SQLite or Postgres, any OpenAI-compatible LLM.