AgenticMind

---

不是“为 Agent 提供的记忆存储”。 AgenticMind 是 Agent 在需要可信答案、需要审计轨迹，以及需要能够不断积累的知识 库时所依托的底层基础。

大多数 Agent 记忆只是带有 save() 和 search() 的向量存储。它能模糊地回忆信息，却无法承担责任：你无法知道答案为何出现、信息是否仍然有效，或来源是否真的支持答案。AgenticMind 将知识视为一等公民、可审计且能自我改进的底层基础，并通过模型上下文协议向任意 Agent 提供服务。

✨ 为什么选择 AgenticMind

• 📌 强制引用来源——答案中的每项陈述都对应一个带编号的来源。没有来源，就没有陈述。
• 🔍 完全可审计——每个答案都有可重放的_推理轨迹_：检索了什么、如何排序，以及用了什么。
• ♻️ 持续自我改进——经过验证的答案会通过由评审器把关的累积循环重新写入知识库，该循环由程序化信号驱动（而非人工点赞）。
• 🧩 分层检索——片段 → 类型化事实卡片 → 知识图谱；结合向量与全文混合检索，并感知信息时效性。
• 🔐 从设计上保障安全——范围受限、遵循最小权限原则的 MCP 令牌，默认拒绝的身份验证，以及针对输入和输出的防护机制。
• 🐘 单一数据存储——Postgres + pgvector 承载向量、全文检索、图谱（递归 CTE）和持久队列。无需 Redis、Neo4j，也无需铺开多个向量数据库。

🔧 工作原理

flowchart TD
  A["🤖 Agent"] -->|"MCP request"| R["Tiered retrieval<br/>pgvector + full-text + graph"]
  R --> Y["Citation-enforced synthesis"]
  Y -->|"grounded answer + [citations]"| A
  Y --> T[("Replayable why-trace")]
  Y -->|"programmatic signals"| L["Judge-gated compounding loop"]
  L -->|"promotes validated knowledge"| R

请求通过 MCP 进入 → 引擎跨三个层级进行检索 → 综合生成每项陈述均引用来源的答案 → 记录可重放的轨迹 → 并将程序化信号送入循环，把经过验证的知识重新写入知识库。

🎬 看看它的实际效果

针对一个以 Agentic Product Standard 为种子内容的语料库，实际调用 kl_ask_global。这个 问题刻意分成两部分——一部分语料库能回答，另一部分不能：

// → kl_ask_global
{ "question": "When should I use a multi-agent architecture instead of a single agent,
                and what must every agent ship with according to the standard?" }

// ← response (trimmed)
{
  "answer": "The provided sources do not specify when to use a multi-agent architecture
             versus a single agent. … According to the Agentic Product Standard, every
             agent must ship with a written Agent Contract [1]. This contract must cover
             ownership, forbidden actions, acceptance criteria, failure modes, escalation
             rules, and logging requirements [1].",
  "citations": [
    { "number": 1, "title": "Agent Contract requirement",
      "materialId": "ba44971b-…", "score": 0.46, "origin": "chunk" }
  ],
  "model": "google/gemini-3.1-flash-lite-preview",
  "retrievalMs": 606, "generationMs": 890,
  "phases": [ {"phase":"embed","ms":552}, {"phase":"retrieve","ms":37},
              {"phase":"synth","ms":890}, {"phase":"output_filter","ms":2} ],
  "telemetryId": "cc942e54-…"
}

看看没有发生什么。 对于语料库无法支持的那一部分，模型拒绝回答——"提供的来源未说明……"——而不是捏造内容。对于它能支持的那一部分，回答附有编号引文，可供打开查看。每个回答还附带可回放的原因追踪（phases、model、telemetryId）。一次调用就能说明全部要点：没有来源，就没有论断；每个回答都有凭据。

🆚 有何不同

	普通 RAG / 记忆 SDK	AgenticMind
有依据的回答	有时	强制提供引文 + 后置检查
每个回答都有原因追踪	✗	完整决策追踪
自我改进的语料库	✗	持续增强循环（经评审门控）
关系验证	✗	图模块
运行于	各不相同	Postgres + pgvector（旗舰方案）

✅ 适用场景 / 🚫 不适用场景

适合使用 AgenticMind 的情况：

• 你的 Agent 必须依据可信来源回答，且每项论断都需要引文。
• 你需要可回放的原因追踪，以及一个可用于对 Agent 进行门控的单一 status（supported / partial / unsupported / conflicted / needs_review）。
• 必须呈现相互矛盾或过时的来源，而不能悄然解决冲突。
• 你希望实现受治理的自我改进，而不是悄然自主修改记忆。
• 你需要自托管（仅需 Postgres）和原生支持 MCP 的访问方式（Claude Code、 Cursor、LangGraph、OpenAI/Claude Agent SDK、自定义 Agent）。

以下情况建议选择其他方案：

• 你只需要简单的个性化聊天记忆（使用记忆 SDK）。
• 你现在就想要托管 API / 无代码 UI——AgenticMind 是可自托管的基础设施。
• 你需要开箱即用的 SSO / SOC2（现有功能请参阅安全模型）。
• 你追求的是最快的原型，而不是可问责的生产环境。

🛠 Agent 接入面（MCP）

一个无头服务（apps/server）通过可流式传输的 HTTP 将引擎作为 MCP 工具提供，并采用失败关闭的逐令牌 Bearer 身份验证（限定范围、遵循最小权限原则）：

工具	范围	用途
kl_search	knowledge:read	语义／关键词段落搜索
kl_ask_global	knowledge:read	综合回答 + 引文 + 可设门控的 status（可选 intent／facts）
kl_get_material	knowledge:read	按 ID 获取资料
kl_graph_neighbors	knowledge:read	通过知识图谱查找相关资料
kl_ingest	knowledge:write	添加文本（分块、嵌入、提炼成卡片、提取图谱）
kl_forget	knowledge:admin	删除一份资料及其所有衍生分块／卡片／图谱（与摄取操作相反）
kl_signal	knowledge:signal	对先前的回答发出程序化复利信号
mem_recall	memory:read	回忆信念（私有 ∪ 共享）；语义检索或按 asOf 回溯时间
mem_write	memory:write	将信念记录到私有记忆中（双时态、支持修订）
mem_forget	memory:write	撤回你自己的某条信念（软删除、双时态）

请参阅 什么算作知识，了解知识单元契约（哪些内容可以成为已存储知识）；参阅 评估与限制，了解我们衡量什么以及我们不做什么声明；参阅 docs/knobs.md，了解可选的回答质量调节项（B 级忠实度、有争议的来源、回答策略、来源可信度）；以及**安全模型**（失败关闭的身份验证、租户 RLS、致命三角分析、供应链）。

没有前端——唯一的使用者是通过 MCP 接入的 Agent。工具逻辑在 packages/shared/src/lib/knowledge/mcp-tools.ts 中，与框架无关；宿主是一个约 60 行的 Web 标准 fetch 处理程序，可由 Node 或 Bun 提供服务。

🚀 快速开始

运行——无需克隆（约 1 分钟）

需要 Docker（Compose v2.23+）和一个兼容 OpenAI 的密钥。一条命令即可拉取已发布的镜像、生成密钥、启动 Postgres + 服务 + worker，并输出可直接粘贴的 MCP 配置——无需克隆仓库，也无需创建令牌：

OPENAI_API_KEY=sk-... sh -c "$(curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/quickstart.sh)"

MCP 端点会在 http://localhost:3000/mcp 启动，并使用单个静态 Bearer 进行身份验证（自动生成的 MCP_API_KEY）。在 Claude Code / Cursor 中配置该端点，并添加 Authorization: Bearer <MCP_API_KEY> 标头。

嵌入默认在本地运行——首次使用时会下载一个无需密钥、可离线运行的多语言模型（bge-m3），因此检索无需云端密钥。只有综合生成步骤需要聊天模型：使用 OpenAI 时设置 OPENAI_API_KEY（默认选项），或将 CHAT_BASE_URL 指向任意兼容 OpenAI 的端点——例如本地 Ollama 或 vLLM。

已发布的 Docker 镜像会读取 OPENAI_API_KEY，并在内部将其映射为服务的 CHAT_API_KEY；下方的源码运行方式会在 .env.local 中直接设置 CHAT_API_KEY—— 两者是同一个密钥，只是针对不同入口使用了不同名称。

想先阅读再运行？步骤相同，但会明确列出（仅需放入 deploy/，无需完整克隆）：

mkdir agenticmind && cd agenticmind
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/.env.example       -o .env.example
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/gen-secrets.sh     -o gen-secrets.sh && chmod +x gen-secrets.sh
./gen-secrets.sh                   # writes DB password + MCP_API_KEY into .env
# set OPENAI_API_KEY in .env, then:
docker compose up -d

从源代码开始（开发与贡献）

需要 Docker 和 Node ≥22.18（或 Bun ≥1.3）——服务端和工作进程可直接运行在 Node 或 Bun 上。

git clone https://github.com/Moai-Team-LLC/AgenticMind.git
cd AgenticMind
cp .env.example .env.local         # set AUTH_SECRET (+ a chat key OR local Ollama)
./setup.sh                         # picks npm or bun, starts Postgres, runs migrations
npm run dev                        # headless MCP server on :3000  (or: bun run dev)

使用 npm run check 验证构建（类型检查 + 测试）——也可以运行 bun run check。

在从源代码搭建的开发环境中，/mcp 路由采用默认拒绝策略，并接受 Bearer typ="mcp" HS256 JWT（而不是静态部署密钥）。无头服务端不附带管理界面——使用签发脚本生成一个令牌（脚本会从你的 .env.local 读取 DATABASE_URL + AUTH_SECRET）：

npm run issue-token -- --label "claude-code" --ttl-days 365   # or: bun run issue-token --label …
# prints the bearer on the last line — capture it, it is not stored in plaintext

然后让 MCP 客户端连接到 http://localhost:3000/mcp，并在 Authorization: Bearer … 标头中提供该令牌。（Lint 还要求 Node ≥22.18——参见 .nvmrc。）

注意。 本地 Docker Postgres 未启用 TLS，因此 .env.example 中设置了 DATABASE_SSL=false，且 DATABASE_URL 使用主机端口 5435。对于需要 SSL 的托管 Postgres （Supabase、RDS、……），请设置 DATABASE_SSL=true。

🧱 目录结构

packages/shared/src/lib/knowledge/        ← the tiered engine (the product)
packages/shared/src/lib/ai/               ← chat + embeddings (provider-agnostic; local embeddings by default)
packages/shared/src/database/             ← Drizzle schema + queries (Postgres + pgvector)
apps/server/src/{index,mcp}.ts            ← headless MCP host, Node or Bun (agent surface)
apps/worker/src/jobs/knowledge-feedback/  ← Postgres-scheduled compounding sweep

架构说明。 以 Agent 为先，且仅使用 Postgres：图谱通过 GraphStore 接口提供（在 Postgres 上使用递归 CTE 遍历，无需额外服务）；复利增长由程序化信号驱动；MCP 令牌遵循最小权限原则；Agent 主体精简；主机是无头 Node/Bun HTTP 服务端。检索默认支持多语言——本地 bge-m3 嵌入模型支持多种语言，无需密钥；全文搜索使用语言无关的 simple 配置（可按部署进行配置）。

🌐 AgenticProduct 生态系统

一个标准和五个可运行的参考实现——它们共同构成生产环境中的 Agent 所需闭环：运行 → 记忆 → 衡量，并将安全作为贯穿各环节的保障层。

	项目	角色
📐	agentic-product-standard	契约——原则、自主性阶梯、Harness 分层和评估规范（另含一套 Claude Code 技能）。
⚙️	AgenticOps	运行时与运维——可部署清单、调度、持久化待办队列、有界运行器和集群健康状况。
🧠	AgenticMind（本仓库）	知识与记忆——可审计、可自我改进、强制要求引用，通过 MCP 提供；仅使用 Postgres。
📈	AgenticPerformance	评估与可观测性——OTel 跟踪、带 CI 门禁的黄金集评估、故障集群和改进闭环。
🌉	AgenticGateway	模型与成本层——统一密钥、经衡量的路由、成本上限、缓存和证据。
🛡️	AgenticAssurance	安全与保障——对任意 Agent 进行红队测试（OWASP Agentic + MITRE ATLAS）、生成有害流程图和 SARIF 输出。

它们如何协同。 AgenticOps 运行整个集群，AgenticMind 为 Agent 提供可审计的知识与记忆，AgenticPerformance 则通过跟踪和评估衡量每次运行——由此构成运行 → 记忆 → 衡量闭环。AgenticGateway 是闭环中每次大模型调用所经过的模型层——统一密钥、由评估衡量的路由和成本上限；AgenticAssurance 则对闭环中的任意 Agent 进行红队测试。整个技术栈均符合 agentic-product-standard。

参见标准中的 AgenticMind 案例研究，了解本仓库如何逐层实现规范。

🤝 贡献与许可证

欢迎贡献——请参阅 CONTRIBUTING.md。本项目采用 Apache-2.0 许可证。