agentmemory 配置完全指南：环境变量、端口体系与特性开关（agentmemory-config）

agentmemory 配置完全指南：环境变量、端口体系与特性开关（agentmemory-config）

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory

本篇指南以plugin/skills/agentmemory-config技能（含 REFERENCE.md 与 SKILL.md）为骨架，结合 src/config.ts 等源码实现，系统讲解 agentmemory 的配置加载机制、全部 37 个AGENTMEMORY_*环境变量、默认值与特性开关、端口四元组迁移方式以及 REST 认证配置。读完你可以在~/.agentmemory/.env中独立完成从零启动、开启 LLM 压缩、迁移端口、隔离多 Agent 记忆的完整配置，并理解每个开关背后的默认关闭原因与 token 成本影响。

配置从哪来：环境变量 +~/.agentmemory/.env

agentmemory 的配置来源只有两个：进程环境变量与~/.agentmemory/.env文件（Windows 下为%USERPROFILE%\.agentmemory\.env）。文件格式为每行一个KEY=value，不带export前缀，支持#注释、空行、引号包裹与行内注释。

src/config.ts 中的loadEnvFile()是实际解析器，其规则可以精确概括为：

• 空白行与#开头的行直接跳过；
• 按第一个=切分 key 与 value，两侧 trim；
• value 若以"或'开头，则取配对的引号内内容；
• 未加引号时，遇到" #"（空格加井号）视为行内注释并截断；
• 解析结果按进程生命周期记忆化缓存（envFileCache），文件被视为 boot-static——这正是 SKILL 文档要求"修改后重启服务"的原因。测试中可通过__resetEnvFileCache()或模块重载刷新缓存。

配置的合并优先级（见 src/config.ts 的getMergedEnv()）为：

{ ...fileEnv, ...process.env, ...overrides }

即~/.agentmemory/.env是地基，进程环境变量覆盖它，代码内覆盖最优先。hydrateProcessEnvFromFile()（src/config.ts）在启动时把文件变量灌入process.env，但仅在键尚未被真实环境变量占用时写入，保证"真实环境变量胜出"的优先级与getMergedEnv()一致。

快速上手：一份可复制的初始配置

在~/.agentmemory/.env中写入（对应 SKILL.md 的 Quick start 并补充注释）：

# LLM provider（选一个即可；一个都不配 = 零-LLM 模式） ANTHROPIC_API_KEY=sk-ant-... # 或者 GEMINI_API_KEY / OPENROUTER_API_KEY / MINIMAX_API_KEY / OPENAI_API_KEY # 特性开关 AGENTMEMORY_AUTO_COMPRESS=true AGENTMEMORY_INJECT_CONTEXT=true

保存后重启服务即生效。这套配置等价于 README 中演示的"更丰富记忆"形态：自动压缩观察记录、在对话中注入项目上下文。其余所有变量都有安全默认值，不配置也能运行。

默认值背后的设计意图

SKILL.md 明确列出三条"值得知道的默认值"，背后均有源码佐证：

• 无 API Key 也能跑：不配 Key 时detectProvider()（src/config.ts）返回noopprovider，系统以 BM25 关键词检索 + 本地 embedding 的零-LLM 模式运行。detectLlmProviderKind()在无任何 Key 时判定为"noop"，consolidation的默认开关也依赖hasLLMProviderConfigured()动态决定。
• 烧 token 的功能默认关闭：AGENTMEMORY_AUTO_COMPRESS（每次观察调用 LLM 压缩）与AGENTMEMORY_INJECT_CONTEXT（向模型注入上下文）都会按工具调用频率消耗 token，因此默认 OFF，属有意设计。isAutoCompressEnabled()（src/config.ts）仅接受字面量"true"，isContextInjectionEnabled()（src/config.ts）同理。
• 工具可见性可裁剪：AGENTMEMORY_TOOLS=all（默认，54 个工具）或core（8 个精简工具），对应 src/mcp/tools-registry.ts 的getVisibleTools()。

37 个AGENTMEMORY_*变量全参考

REFERENCE.md 中的变量清单由 scripts/skills/generate.ts 扫描src/目录生成：正则匹配AGENTMEMORY_[A-Z0-9_]+，排除以__结尾的内部标记，去重排序后写入<!-- AUTOGEN:env -->块。修改源码中的变量后必须运行npm run skills:gen重新生成（--check模式可在 CI 中做漂移检测）。

当前识别的全部 37 个变量（与 REFERENCE.md 完全一致）如下：

AGENTMEMORY_AGENT_SCOPE、AGENTMEMORY_ALLOW_AGENT_SDK、AGENTMEMORY_AUTO_COMPRESS、AGENTMEMORY_COMMIT_SHA、AGENTMEMORY_CONSOLIDATION_COOLDOWN_MS、AGENTMEMORY_COPILOT_MCP_BLOCK、AGENTMEMORY_CWD、AGENTMEMORY_DATA_DIR、AGENTMEMORY_DEBUG、AGENTMEMORY_DROP_STALE_INDEX、AGENTMEMORY_EXPORT_ROOT、AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS、AGENTMEMORY_FORCE_PROXY、AGENTMEMORY_GRAPH_WEIGHT、AGENTMEMORY_III_CONFIG、AGENTMEMORY_III_VERSION、AGENTMEMORY_IMAGE_EMBEDDINGS、AGENTMEMORY_IMAGE_STORE_MAX_BYTES、AGENTMEMORY_INJECT_CONTEXT、AGENTMEMORY_LLM_NOTHINK、AGENTMEMORY_LLM_TIMEOUT_MS、AGENTMEMORY_MCP_BLOCK、AGENTMEMORY_PROBE_TIMEOUT_MS、AGENTMEMORY_PROJECT_NAME、AGENTMEMORY_PROVIDER、AGENTMEMORY_REFLECT、AGENTMEMORY_SDK_CHILD、AGENTMEMORY_SECRET、AGENTMEMORY_SESSION_ID、AGENTMEMORY_SLOTS、AGENTMEMORY_SUPPRESS_COST_WARNING、AGENTMEMORY_TOOLS、AGENTMEMORY_URL、AGENTMEMORY_USE_DOCKER、AGENTMEMORY_VERBOSE、AGENTMEMORY_VIEWER_HOST、AGENTMEMORY_VIEWER_URL

按功能分组，结合源码逐个展开：

核心服务与地址

Provider 与 LLM 行为

Provider 自动检测有严格的优先级顺序（src/config.ts）：OPENAI_API_KEY（可用OPENAI_API_KEY_FOR_LLM=false排除）→MINIMAX_API_KEY→ANTHROPIC_API_KEY→GEMINI_API_KEY/GOOGLE_API_KEY→OPENROUTER_API_KEY→ 无 Key 时noop（零-LLM）。模型默认值、MAX_TOKENS=4096、baseURL均在该函数内确定。

记忆功能特性开关

认证与多 Agent

Hook 上下文传递

端口四元组：一个锚点迁走整组服务

agentmemory 以REST 为锚点派生其余端口（对应 SKILL.md 的 Ports 小节与 src/config.ts）：

三种整体搬迁方式（src/cli.ts）：

agentmemory --port 3211 # 整组迁到 3211/3212/3213/49234 agentmemory --instance 1 # 等价快捷方式：3111 + 1*100，最大 N=50 III_REST_PORT=3211 npx @agentmemory/agentmemory # 环境变量方式

--instance N是"同机并行多套 daemon"的推荐做法：--instance 0保持标准 3111/3112/3113/49134 四元组，--instance 1得到 3211/3212/3213/49234，互不冲突；已有实例占位时启动第二个实例会被拒绝，提示改用不同--instance或先agentmemory stop。架构背景参见 agentmemory-architecture SKILL。

认证实践：何时必须配AGENTMEMORY_SECRET

• 纯本机回环：REST 绑定127.0.0.1，默认开放，无需认证；
• 远程/容器/多主机：设置AGENTMEMORY_SECRET后，所有受保护端点要求Authorization: Bearer <secret>，MCP shim 与各 hook 会把它透传给请求（各 src/hooks 文件均以REST_URL+SECRET组织请求头）；
• mesh 多实例协作：两端必须同时设置相同的AGENTMEMORY_SECRET；
• viewer 开放绑定：AGENTMEMORY_VIEWER_HOST绑定非回环地址时，强制要求AGENTMEMORY_SECRET并配合VIEWER_ALLOWED_HOSTS白名单校验 Host 头（src/viewer/server.ts），Fly 等云部署场景见 deploy/fly/README.md。

与配置相关的非AGENTMEMORY_*变量

REFERENCE 只统计AGENTMEMORY_前缀，但配置体系还包含以下常用键（README 的完整示例见 README.md）：

• Provider Key 族：ANTHROPIC_API_KEY、GEMINI_API_KEY/GOOGLE_API_KEY、OPENROUTER_API_KEY、MINIMAX_API_KEY、OPENAI_API_KEY（同一 Key 同时激活 LLM 与 embedding，可用OPENAI_API_KEY_FOR_LLM=false只留 embedding）；均可用*_BASE_URL、*_MODEL微调；
• 检索调优：BM25_WEIGHT=0.4、VECTOR_WEIGHT=0.6（src/config.ts 会做范围钳制）、TOKEN_BUDGET=2000、EMBEDDING_PROVIDER=local；
• 流水线开关：CONSOLIDATION_ENABLED（配好 LLM 后默认开，false/0显式关）、GRAPH_EXTRACTION_ENABLED、LESSON_DECAY_ENABLED、OBSIDIAN_AUTO_EXPORT、SNAPSHOT_ENABLED/SNAPSHOT_INTERVAL（下限 1 秒，防止误配置导致满载快照）；
• 团队：TEAM_ID、USER_ID、TEAM_MODE=shared|private（src/config.ts）；
• Claude Code 桥：CLAUDE_MEMORY_BRIDGE=true+CLAUDE_PROJECT_PATH，把记忆同步到~/.claude/projects/<slug>/memory/MEMORY.md（src/config.ts）；
• MCP 独立模式：STANDALONE_MCP=true、STANDALONE_PERSIST_PATH、FALLBACK_PROVIDERS（逗号分隔的故障转移链，agent-sdk 仅在显式开启时被允许加入，见 src/config.ts）。

如何验证配置生效

• agentmemory status/agentmemory doctor：查看健康状态、记忆数与特性开关；
• curl -fsS http://localhost:3111/agentmemory/livez：存活探针；
• 修改~/.agentmemory/.env后必须重启服务（文件缓存为 boot-static）；
• 变量清单漂移检查：npm run skills:gen -- --check，未同步会报DRIFT并给出重生成提示；
• 相关测试覆盖见 test/env-loader.test.ts 与 test/mcp-env-placeholder.test.ts。

配置体系与 REST API 的认证配合详见 agentmemory-rest-api SKILL，端口四元组的设计动机见 agentmemory-architecture SKILL。

【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory