Agentic 配置与内置文档检索

本文是 Agentic 发版后的人类可读配置入口，也会作为 npm 包的 README.md 和 docs/configuration.md 分发。运行中的模型通过独立内置 agentic-config skill 按需读取 Agentic 扩展；现有 customize-agentic 及其上游配置知识保持不变，OpenCode-compatible 字段继续查询官方文档和 schema。

模型如何查询

直接在会话中提问即可，例如：

如何开启或关闭 Agentmemory？
查一下 agentmemory.contextInjection 的默认值。
Agentic 的全局配置文件在哪里？
如何配置 OpenCode Zen、OAuth、MCP 或自定义 provider？
OPENAI_BASE_URL 在 Agentmemory 中有什么作用？

默认模型可见的 skill 列表包含独立 agentic-config。其简短描述只包含 Agentmemory 和 AGENTIC_*，不包含 OAuth、Zen、provider、MCP、LSP、plugin 或 TUI 等上游检索关键词；完整正文只有模型调用现有 skill 工具时才进入上下文，因此：

• 不新增 system prompt、CLI 命令或常驻模型工具；
• Agentmemory 关闭时仍能查询，因为 skill 属于 Agentic 内置配置能力；
• 正常编程任务只承担一条 skill 描述的既有开销，详细说明不进入上下文；
• Agentic 独立配置记录在新 skill 正文；上游问题仍由未修改的 customize-agentic 和官方文档处理。

如果用户显式禁用了 skill 权限，模型不能自动加载正文，此时可直接阅读本文件。不要在项目或用户 skill 目录创建同名 agentic-config，因为同名磁盘 skill 按现有规则会覆盖内置版本。

~/.config/agentic/skills/memory/SKILL.md 这类磁盘文件是用户安装的普通 Markdown skill，不是嵌入式 Agentmemory。它可能指导 .agentic/memory/ 文档工作流，但不代表 agentmemory 已开启，也不提供本页所述的 SQLite、Viewer 或原生 memory_* 工具。模型回答“memory skill”时必须先根据 skill 的 location 说明具体指哪一种机制。

配置文件与兼容边界

推荐配置：

| 作用域 | 推荐路径 | |---|---| | 全局 | ~/.config/agentic/agentic.jsonc | | 项目 | 从工作目录向上查找 agentic.jsonc 或 agentic.json | | 扩展目录 | 项目/用户目录下的 .agentic/ | | TUI | 全局 ~/.config/agentic/tui.jsonc；项目 tui.json(c) 或 .agentic/tui.json(c) | | Agentmemory provider/model/embedding/port | ~/.agentmemory/.env 或启动 agentic 的进程环境 | | 其他 Agentmemory 环境变量 | 启动 agentic 的进程环境 |

Agentic 为迁移和 OpenCode 生态兼容继续读取旧 opencode.json(c)、.opencode/ 和 ~/.config/opencode/。同层级同时存在旧路径与 Agentic 路径时，Agentic 路径后加载并覆盖冲突值。

配置中的 $schema 继续使用：

{ "$schema": "https://opencode.ai/config.json" }

这是兼容边界，不是遗漏品牌化。OAuth、OpenCode Zen/免费模型、provider catalog、MCP 和官方服务仍由 OpenCode 提供，不能替换官方域名或 schema。上游语义可继续参考 OpenCode config。

官方 schema 不包含 Agentic 独有的 agentmemory 字段，因此编辑器可能只对该字段报 unknown；Agentic 运行时仍会按本地类型 schema 校验它。不要为消除上游 schema 提示而删除有效的 Agentmemory 配置。

上游兼容配置总表

Agentic 不复制上游字段总表。模型处理 provider、OAuth、OpenCode Zen/免费模型、MCP、LSP、permission、agent、plugin 或 TUI 配置时，应直接读取：

• OpenCode 配置文档
• OpenCode 主配置 JSON Schema
• OpenCode TUI JSON Schema

现有 customize-agentic skill 继续处理这些上游字段且内容未改；agentic-config 明确把它们路由回原 skill 和官方来源。Agentic 继续使用官方 schema，以保证 OAuth、Zen、免费模型和生态兼容；只有 agentmemory、Agentic 品牌路径/兼容顺序及 AGENTIC_* 扩展由本项目维护。

Agentmemory 开关

Agentmemory 默认关闭。推荐对象形式：

{
  "agentmemory": {
    "enabled": true,
    "viewer": false,
    "capture": true,
    "contextInjection": true,
    "shutdownTimeoutMs": 5000
  }
}

也可以使用简写：

{ "agentmemory": true }

关闭方式：

{ "agentmemory": false }

紧急关闭优先于任何配置文件：

AGENTIC_DISABLE_AGENTMEMORY=1 agentic

| 字段 | 默认值 | 开启/调整后能做什么 | 前置与代价 | |---|---:|---|---| | enabled | false | 启动嵌入式 SQLite/BM25 记忆并注册七个 memory_* 工具；模型可手工保存、召回、搜索、查会话/文件历史和经验 | 总开关；关闭时不启动记忆 runtime、端口、自动捕获/注入和原生记忆工具 | | viewer | false | 默认在 http://localhost:3113 打开 Web 查看器，查看 Dashboard、记忆、时间线、会话回放、图谱、slots 和有效开关状态 | 需要 enabled: true；它只是查看/控制面，不会隐式打开 capture、注入、向量或付费 LLM | | capture | true | 自动记录 prompt、工具调用/结果、会话生命周期和文件活动，后续可检索/回放，无需每次手工 memory_save | 关闭后已有记忆和手工工具仍可用；不代表开启 LLM 压缩 | | contextInjection | true | 在首次 system 上下文和 compaction 时自动注入相关历史记忆，模型不必先手工召回 | 只在 capture hooks 活跃时生效；不需要 LLM key；关闭后仍可手工搜索/召回 | | shutdownTimeoutMs | 5000 | 在 reload/退出时给关键写入和生命周期任务留出排空时间 | 不是功能开关；值大更优先耐久性，值小更优先快速退出；范围 100～30000ms |

修改配置并 reload 后，当前项目实例会被释放；下一实例按新配置加载。环境变量修改需要重启 Agentic。

四个开关彼此独立：

• capture: true 只负责记录会话/工具事件，不会自动打开付费 LLM 压缩；
• contextInjection: true 已直接控制 Agentic 的 system/compaction 注入，不需要再设置 AGENTMEMORY_INJECT_CONTEXT=true；该环境变量属于 Agentmemory standalone/Claude Code hook 路径；
• AGENTMEMORY_AUTO_COMPRESS=true 是单独的高频 LLM 功能，会产生 token 成本；未开启时使用 zero-LLM synthetic compression；
• viewer: true 只启动 Dashboard，不会隐式开启其他三个功能。

Viewer 的配置状态读取上述 Agentic 有效配置；如果多个项目窗口共享 runtime，则显示所有活跃租约的聚合有效状态。

引导用户时必须先说明“打开后能做什么”，再给配置；不得只罗列开关名，也不得默认全开。例如用户只想在 Web 中看记忆，只需说明并开启 viewer；想让模型自动利用旧决策，再说明并开启 contextInjection。

Agentmemory 官方可选功能开关

下表以 Agentmemory 官方中文文档 和当前嵌入源码为准，同时标出 Agentic 嵌入模式与 standalone 的差异。

| 配置 | 开启后能做什么 | 前置、成本与 Agentic 差异 | |---|---|---| | EMBEDDING_PROVIDER=local | 在 BM25 之上增加语义向量召回，提高“意思相同但用词不同”的命中 | 需安装 @xenova/transformers；首次下载 Xenova/all-MiniLM-L6-v2，之后本地推理，不需 embedding key | | AGENTMEMORY_AUTO_COMPRESS=true | 每条 observation 交给 LLM 生成更丰富的结构化压缩 | 需 LLM provider，活跃会话可显著消耗 token；关闭时仍有 zero-LLM synthetic compression + BM25 | | GRAPH_EXTRACTION_ENABLED=true | 在会话结束时从 observation 提取实体/关系，可在图谱搜索和 Viewer Graph 中查看 | 需 LLM provider，会增加 session stop 后台调用 | | CONSOLIDATION_ENABLED=true | 把累积的会话摘要/模式整合为语义事实和流程经验 | 需 LLM provider 并增加调用；未显式设置时，当前 runtime 检测到 LLM 会自动启用；设 false 可明确关闭 | | AGENTMEMORY_SLOTS=true | 启用有容量上限的置顶记忆槽：persona、用户偏好、工具规则、项目上下文、待办和会话模式等 | 存储不需 LLM；Agentic 七个原生工具不含 memory_slot_*，需通过 Viewer/REST 或另行接入的完整 Agentmemory MCP 编辑 | | AGENTMEMORY_REFLECT=true | 会话结束时扫描近期 observation，自动更新 pending items、重复模式和项目触及文件 | 需 AGENTMEMORY_SLOTS=true；异步执行，slot-reflect 本身不要求单独 LLM key | | AUTO_FORGET_ENABLED=true | 允许 auto-forget 清理 TTL 过期/低价值记忆，删除记录进入审计 | 属于破坏性生命周期功能；Agentic 嵌入模式需从 REST 显式触发，不启动 standalone 周期调度器 | | SNAPSHOT_ENABLED=true | 开放 Git-backed 状态快照的创建/列表/恢复能力 | 需本机 git；Agentic 嵌入模式从 REST/MCP 显式创建，不应宣称 SNAPSHOT_INTERVAL 会自动调度 | | RERANK_ENABLED=true | 用本地 cross-encoder 对混合搜索候选结果再排序，改善最终顺序 | 需 @xenova/transformers；首次下载 Xenova/ms-marco-MiniLM-L-6-v2，增加本地 CPU/延迟而非 provider token 费；关闭不影响基础 BM25/向量搜索 | | AGENTMEMORY_IMAGE_EMBEDDINGS=true | 使用跨模态向量存储/搜索图像引用 | 需图像 embedding 运行库/模型和更多磁盘/CPU；普通文本记忆不需它 | | AGENT_ID + AGENTMEMORY_AGENT_SCOPE=isolated | 按智能体标记并过滤召回，严格防止不同智能体互看记忆 | 默认 shared 只标记不过滤；只在确实需要角色隔离时用 isolated | | AGENTMEMORY_ALLOW_AGENT_SDK=true | 允许用 Claude Agent SDK 订阅作为后台 LLM fallback | 高风险 opt-in；会派生子会话，曾触发 Stop-hook 递归；有 API provider 或 zero-LLM 可用时不推荐 | | CLAUDE_MEMORY_BRIDGE=true | 把部分记忆镜像到 Claude 专用 memory 文件/hook | 仅 standalone Claude 集成；普通 Agentic 嵌入运行不开启 |

AGENTMEMORY_INJECT_CONTEXT=true 也是 standalone Claude Code hook 开关。Agentic 嵌入模式只引导用户设置 agentmemory.contextInjection，两者不需重复开启。

Agentmemory 环境变量

Agentmemory 主要变量同时内置在 agentic-config skill 中，主要分组如下。全部变量都可由启动 agentic 的进程环境设置；provider/model/embedding/port 类变量另外支持 ~/.agentmemory/.env。AGENTIC_DISABLE_AGENTMEMORY 等 Agentic 进程开关必须在启动环境中设置。

| 分组 | 变量 | |---|---| | 安全/地址 | AGENTMEMORY_SECRET, AGENTMEMORY_HOST, AGENTMEMORY_VIEWER_HOST, VIEWER_ALLOWED_HOSTS, VIEWER_ALLOWED_ORIGINS, AGENTMEMORY_URL | | 端口 | III_REST_PORT, III_STREAM_PORT, III_STREAMS_PORT, III_ENGINE_PORT, III_ENGINE_URL | | OpenAI-compatible | DEEPSEEK_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL, OPENAI_API_KEY_FOR_LLM, OPENAI_REASONING_EFFORT, OPENAI_API_VERSION, OPENAI_TIMEOUT_MS | | 其他 LLM | ANTHROPIC_*, GEMINI_*, GOOGLE_API_KEY, OPENROUTER_*, MINIMAX_*, FALLBACK_PROVIDERS | | LLM 成本/限额 | MAX_TOKENS, TOKEN_BUDGET, MAX_OBS_PER_SESSION, AGENTMEMORY_LLM_TIMEOUT_MS, AGENTMEMORY_AUTO_COMPRESS, AGENTMEMORY_ALLOW_AGENT_SDK | | Embedding/搜索 | EMBEDDING_PROVIDER, BM25_WEIGHT, VECTOR_WEIGHT, VOYAGE_API_KEY, COHERE_API_KEY, OPENAI_EMBEDDING_*, OPENROUTER_EMBEDDING_MODEL, RERANK_ENABLED | | 图谱/整理 | AGENTMEMORY_GRAPH_WEIGHT, GRAPH_EXTRACTION_*, CONSOLIDATION_*, AGENTMEMORY_SLOTS, AGENTMEMORY_REFLECT, AUTO_FORGET_* | | 快照/桥接 | SNAPSHOT_*, CLAUDE_MEMORY_BRIDGE, CLAUDE_PROJECT_PATH, CLAUDE_MEMORY_LINE_BUDGET | | 多智能体/团队 | AGENT_ID, AGENTMEMORY_AGENT_SCOPE, TEAM_ID, USER_ID, TEAM_MODE |

DeepSeek 可以直接使用厂商 key；默认摘要模型为 deepseek-v4-flash，需要更高质量时显式选择 deepseek-v4-pro：

DEEPSEEK_API_KEY=your-key
# OPENAI_MODEL=deepseek-v4-pro

也可以使用通用 OpenAI-compatible 写法：

OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-v4-flash

新配置不再推荐已弃用的 deepseek-chat 别名。以上变量用于 Agentmemory 后台 LLM 工作，不替代 Agentic 主会话的 provider 配置；DeepSeek Chat API 不提供 embedding，运行时不会再把同一 DeepSeek key 误识别为 OpenAI embedding key。

零 LLM 与本地向量

没有任何 LLM key 时，Agentmemory 仍能运行捕获、SQLite 存储、BM25 检索和 synthetic compression。会跳过的是 LLM 会话摘要、知识图提取及显式开启的 LLM observation compression；因此“启用 Agentmemory”本身不要求 API key。

免费本地向量需要同时安装可选运行库并显式选择 provider：

# agency-agentic 通过 npm 全局安装时
npm install -g @xenova/transformers

# ~/.agentmemory/.env
EMBEDDING_PROVIDER=local

首次向量请求会下载 Xenova/all-MiniLM-L6-v2，之后推理在本机完成，不需要 embedding 厂商 key。没有安装时安全退化为 BM25-only；不能只安装包而漏掉 EMBEDDING_PROVIDER=local。

agency-agentic npm 包已经带 @node-rs/jieba，用于改善中文分词；只有诊断提示缺失时才需执行 npm install -g @node-rs/jieba 修复。tiny-segmenter 是日文分词器，不是中文依赖，仅日文检索需要时执行 npm install -g tiny-segmenter。

如要启用 LLM 摘要压缩，再单独设置：

AGENTMEMORY_AUTO_COMPRESS=true

它会按 observation 消耗 token，不是 capture: true 的必需伴随项。知识图同理，需要 GRAPH_EXTRACTION_ENABLED=true 和可用 LLM；contextInjection 本身不需要 LLM key。

Agentic 独立运行开关

以下是 Agentic 品牌命名的公开进程控制项，必须在启动前设置；上游 JSON 字段仍查官方文档。

| 分类 | 环境变量 | |---|---| | 配置发现 | AGENTIC_CONFIG, AGENTIC_CONFIG_CONTENT, AGENTIC_CONFIG_DIR, AGENTIC_TUI_CONFIG, AGENTIC_DISABLE_PROJECT_CONFIG | | 隔离/插件 | AGENTIC_PURE, AGENTIC_DISABLE_DEFAULT_PLUGINS, AGENTIC_DISABLE_EXTERNAL_SKILLS, AGENTIC_DISABLE_CLAUDE_CODE, AGENTIC_DISABLE_CLAUDE_CODE_PROMPT, AGENTIC_DISABLE_CLAUDE_CODE_SKILLS, AGENTIC_DISABLE_LSP_DOWNLOAD, AGENTIC_DISABLE_EMBEDDED_WEB_UI | | 服务认证 | AGENTIC_SERVER_USERNAME, AGENTIC_SERVER_PASSWORD, AGENTIC_API_KEY | | 行为 | AGENTIC_AUTO_SHARE, AGENTIC_DISABLE_SHARE, AGENTIC_DISABLE_AUTOUPDATE, AGENTIC_ALWAYS_NOTIFY_UPDATE, AGENTIC_DISABLE_AUTOCOMPACT, AGENTIC_DISABLE_PRUNE, AGENTIC_DISABLE_TERMINAL_TITLE, AGENTIC_DISABLE_MOUSE, AGENTIC_DISABLE_MODELS_FETCH, AGENTIC_DISABLE_FFF | | 工具/搜索 | AGENTIC_ENABLE_QUESTION_TOOL, AGENTIC_ENABLE_EXA, AGENTIC_ENABLE_PARALLEL, AGENTIC_WEBSEARCH_PROVIDER | | 诊断/覆盖 | AGENTIC_PRINT_LOGS, AGENTIC_LOG_LEVEL, AGENTIC_SHOW_TTFD, AGENTIC_AUTO_HEAP_SNAPSHOT, AGENTIC_ACP_PROFILE, AGENTIC_DIRECT_TRACE, AGENTIC_MODELS_URL, AGENTIC_MODELS_PATH, AGENTIC_DB, AGENTIC_GIT_BASH_PATH |

布尔开关通常接受 1 或 true。实验开关以 AGENTIC_EXPERIMENTAL / AGENTIC_EXPERIMENTAL_* 命名，属于不稳定接口，只应在用户明确选择时使用；完整当前名称由 agentic-config skill 按需提供。PID、caller、embedded runtime、生成 skill 元数据和测试目录等内部变量不作为用户配置公开。AGENTIC_SYSTEM_PRIMARY_COLOR 是源码常量，不是环境变量。

发布与防漂移

配置说明有三层一致性保障：

1. OpenCode-compatible 主配置和 TUI 字段不在 fork 内复制，统一指向官方文档与 JSON Schema。
2. Agentic 扩展和环境变量由独立内置 packages/core/src/plugin/skill/agentic-config.md 维护，并测试新 skill 可发现且原 customize-agentic 内容未被混入 Agentmemory 知识。
3. npm 构建必须包含 README.md 与 docs/configuration.md；发布 tarball 缺少说明会失败。

增加 Agentic 独立配置时，必须同时更新 schema/实现、agentic-config skill、本文、测试和 PATCHES.md。上游新增字段只由原 skill/官方 schema 承载，升级验收检查隔离边界，不在 Agentic skill 维护字段副本。