Frinus

Frinus MCP 服务

φρήν + νοῦς — 通过 Frinus 平台，为你的 Claude Agent 提供长期认知记忆。

frinus-mcp 是一款 MCP（Model Context Protocol）服务。它是你的 MCP 客户端——Claude Code、Cursor 或 Claude Desktop——与托管在 https://frinus.rdxsec.com.br 的 Frinus 平台之间的桥梁。

它无法独立运行。它不会在本地存储任何内容：每次工具调用都会通过 HTTPS 转发到你的 Frinus 账户。因此，在它发挥作用之前，你需要准备好两样东西：

1. 一个 Frinus 账户（免费，无需银行卡），以及
2. 一个 Frinus API 密钥（sk-frinus-...）。

准备好这两样东西后，该服务便会提供 70 个工具，涵盖认知记忆、工作记忆、会话、Agent、L0–L3 知识层级、编排任务和训练流水线。它使用标准输入/输出（stdio），可与任何支持 MCP 的客户端配合使用。

• 版本： 3.8.0
• 工具： 70 个（参见工具参考）
• 平台： https://frinus.rdxsec.com.br（托管式 SaaS——此服务与之通信的后端）
• npm 包： frinus-mcp

工作原理

+-------------------+        +--------------+        +----------------------------+
| Your MCP client   | stdio  | frinus-mcp   | HTTPS  | Frinus platform            |
| (Claude Code,     | <----> | (this server,| <----> | frinus.rdxsec.com.br       |
|  Cursor, Desktop) |        |  via npx)    |        | (your memories live here)  |
+-------------------+        +--------------+        +----------------------------+

该服务会在启动时向平台验证你的 API 密钥，解析你的账户和组织，并将每次工具调用路由到该平台。没有 API 密钥 → 服务会拒绝启动。

规则零——MCP 是强制要求

Frinus MCP 就是 Agent 的长期记忆、身份和智能。没有它，模型在不同会话之间不会保留状态。每个集成 Frinus 的 Claude Agent 都必须：

1. 在对话开始时确认 MCP 工具可访问（例如 session_start、memory_search、search_with_attention）。
2. 如果无法访问，向用户显示警告：“MCP Frinus 尚未连接。长期记忆功能不可用。”
3. 在回答任何非简单问候的问题之前，执行 BOOT 协议（P1）。
4. 在高效会话结束前，通过 memory_store 保存所学内容。

完整的协议集位于全局 CLAUDE.md（Frinus 组织）中，下方的七项协议对此进行了概述。

开始之前——账户和 API 密钥

你需要一个 Frinus 账户和 API 密钥，两者均可免费获取。

1. 创建免费账户

在 https://frinus.rdxsec.com.br 注册。免费计划（R$0） 足以满足入门需求：

• 100 条记忆
• 每天 20 次查询
• 无需信用卡

2. 生成 API 密钥

登录后，打开账户的 设置 → API 密钥，创建一个新密钥。你会得到一个如下格式的值：

sk-frinus-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

现在就复制它——出于安全考虑，它只会显示一次。此值将填入下方的 FRINUS_API_KEY 环境变量。请像对待密码一样妥善保管；切勿将它提交到代码仓库。

快速入门（从零到第一条记忆）

只需五分钟，分四步完成。

步骤 1 — 创建账户

在 https://frinus.rdxsec.com.br 注册（免费计划，无需银行卡）。参见上文。

步骤 2 — 生成 API 密钥

设置 → API 密钥 → 创建。复制 sk-frinus-... 值。参见上文。

第 3 步——将服务添加到客户端

你无需安装任何内容——npx 会按需获取并运行该软件包。你只需提供 API 密钥；平台 URL 已默认为生产环境。

Claude Code（一行命令）：

claude mcp add frinus --env FRINUS_API_KEY=sk-frinus-... -- npx -y frinus-mcp@latest

Cursor / Claude Desktop / 任意客户端（配置 JSON）：

{
  "mcpServers": {
    "frinus": {
      "command": "npx",
      "args": ["-y", "frinus-mcp@latest"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-..."
      }
    }
  }
}

配置文件位置：

• Claude Code： ~/.claude.json，位于 mcpServers 下。
• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）/ ~/.config/claude/claude_desktop_config.json（Linux）。也可以使用一键式 .mcpb 扩展，只需粘贴 API 密钥。
• Cursor： ~/.cursor/mcp.json，位于 mcpServers 下。

重启客户端，使其加载新服务。

将 sk-frinus-... 替换为第 2 步中获取的真实密钥。通常你只需设置 FRINUS_API_KEY——每个后端 URL 都已默认为托管平台。完整列表和自托管覆盖设置请参阅环境变量。

第 4 步——用第一条记忆进行验证

在客户端中，让 Agent 存储并回忆某项内容：

Store this in Frinus memory: "Our staging DB is reset every night at 02:00 UTC."

然后在同一会话或之后的会话中：

What time does our staging DB reset?

在后台，Agent 会调用 memory_store，然后调用 memory_search / search_with_attention。如果成功回忆出内容，说明桥接已正常运行。你可以在 https://frinus.rdxsec.com.br 的 Web 应用中确认同一条记忆是否出现。

环境变量

正常使用时，你只需设置 FRINUS_API_KEY。服务 URL 已指向托管平台——除非你使用自托管，否则请保持不变（参见高级——自托管——本地开发）。

变量	默认值（托管平台）	说明
FRINUS_API_KEY	必填	你的个人 API 密钥（sk-frinus-...）。启动时解析账户和组织。
MEMORY_SERVICE_URL	https://frinus-memory.rdxsec.com.br	Memory Engine 基础 URL
FRINUS_CP_URL	https://frinus-api.rdxsec.com.br	Control Plane 基础 URL（账户、组织、API 密钥、账单）
AGENT_SERVICE_URL	https://frinus-agents.rdxsec.com.br	Agent Service 基础 URL（Agent、调用、技能）
FRINUS_MEMORY_API_KEY	—	FRINUS_API_KEY 的旧版备用项

启动时，服务会向平台验证 API 密钥，并解析你的组织和已登录用户。如果验证失败，服务会以 [FATAL] 中止，以便客户端显示错误——请重新检查“设置”→“API 密钥”中的密钥。

7 项协议

协议	适用时机	工具	用途
P1 — BOOT	每次会话开始时	session_start、working_memory_get、search_with_attention	加载身份信息、近期状态和相关上下文
P2 — CONSULT	执行任何操作前	search_with_attention、session_context、memory_reinforce、memory_weaken	检索、评估并强化相关记忆
P3 — PLAN	规划任务时	memory_store(procedural)、working_memory_add、stream_capture	持久化计划、工作状态和架构决策
P4 — CAPTURE	每 2–3 次交互	heartbeat_tick、working_memory_add、memory_store(episodic)、stream_capture	持续记录进展、错误和模式
P5 — LEARN	获取新知识时	training_teach、training_qa、training_stats、stream_process、sleep_run	教授事实和流程，并运行整合周期
P6 — AUDIT	维护时	consolidation_detect_conflicts、consolidation_resolve_conflict、consolidation_detect_redundant、hierarchy_consolidate	检测冲突和冗余，并整合记忆
P7 — CLOSE	会话结束时	session_summary、stream_process、memory_store、hierarchy_consolidate、session_end	总结内容、提升流项目并持久化所学内容

详细的协议脚本位于 Agent 的 CLAUDE.md 中。请将上表视为每个集成 Frinus 的 Agent 都必须遵守的约定。

工具参考

70 个工具，按领域分组。每个工具都返回文本内容；负载遵循 MCP Tool 规范。完整的 JSON 架构位于 src/tools/definitions.ts。

记忆（7）

认知型长期记忆：情景记忆（发生了什么）、语义记忆（我知道什么）、程序性记忆（如何做事）。

工具	描述
memory_store	创建一条记忆。必需参数：agent_id、content。memory_type ∈ {episodic, semantic, procedural}。scope ∈ {user, agent, universe, organization}。importance 为 0–1。
memory_search	语义相似度搜索。筛选条件：agent_id、memory_types、limit。
memory_get	按 memory_id 获取一条记忆（完整内容、元数据、相关性）。
memory_list	列出某个 agent_id 的记忆，可选按类型筛选。
memory_delete	按 memory_id 永久删除一条记忆。
memory_reinforce	提升有用记忆的相关性（memory_id、boost 0–1，默认值为 0.1）。
memory_weaken	降低过时记忆的权重（memory_id、penalty 0–1，默认值为 0.2）。

工作记忆（3）

短期、受上下文限制的状态。米勒定律：每个上下文最多 7 项，最旧的项目会自动移除。默认 TTL 为 30 min（最长 2 h）。

工具	描述
working_memory_get	加载当前上下文的状态。任务开始时务必调用。
working_memory_add	持久化当前状态。上下文格式：agent:{uuid}、universe:{uuid}、organization:{uuid}。
working_memory_clear	移除某个上下文的所有项目。

会话（5）

会话 = 流、工作记忆和捕获记录的逻辑容器。

工具	描述
session_start	为某个 Agent 开始会话。返回 session_id。支持通过 parent_session_id 继承子 Agent 的上下文。
session_end	终止会话并定稿其摘要。
session_context	结合工作记忆与长期记忆检索，并通过提取的会话主题增强结果。
session_summary	生成结构化回顾（决策、收获、待办事项）。
session_clear	清除会话的工作状态，但不结束会话。

流（4）

持续捕获管道。项目会被批量处理并评分，其中重要项目会提升为永久记忆。

工具	描述
stream_capture	记录与会话关联的输入 / 输出 / 内部备注。
stream_get_session	重放某个 session_id 捕获的每个项目。
stream_get_recent	获取跨会话的近期流项目（可筛选）。
stream_process	将待处理项目提升为长期记忆（手动触发；调度器也会每隔 5 min 运行一次）。

上下文与注意力（2）

工具	描述
memory_get_context	为任务描述构建有令牌数量限制的上下文窗口。
search_with_attention	使用任务类型感知权重的 RAG。task_type ∈ {implementation, debug, deploy, documentation, review}，用于调整各 memory_type 的权重。

用户（2）

工具	描述
user_register	在记忆系统中注册用户（幂等）。
user_get_context	检索用户记忆和租户上下文的组合结果。

维护（2）

工具	描述
heartbeat_tick	为 Agent 执行轻量级时钟周期，驱动相关性衰减和轻量整合。
sleep_run	触发一次休眠周期。phases ⊆ {evaluation, forgetting, consolidation, relevance}。与调度器的常规 / 深度休眠相对应。

整合（3）

工具	描述
consolidation_detect_conflicts	显示相似度高于阈值的候选冲突记忆。
consolidation_resolve_conflict	保留一条记忆，用书面解决说明取代另一条。
consolidation_detect_redundant	查找可合并或移除的近似重复项。

记忆层级（2）

工具	描述
hierarchy_consolidate	将多个相关记忆整合为更高层级的摘要记忆。
hierarchy_get_tree	查看根记忆的整合树。

Agent（6）

Agent 的 CRUD 操作和编排调用。

工具	描述
agent_create	创建 Agent（可选择使用模板），并限定在某个知识域 / 团队内。
agent_list	列出调用方租户中的 Agent。根据 API 密钥自动限定范围。
agent_get	根据 agent_id 获取 Agent。
agent_update	更新角色设定、团队、知识域等。
agent_delete	删除 Agent。
agent_invoke	以编程方式向 Agent 分配任务并调用。返回其工具调用和最终答案。用于委派。

知识域（4）

知识域 = 受租户限定的知识领域。包含 L0–L3 层级。

工具	描述
universe_create	在调用方组织中创建知识域。包括 slug、名称和描述。
universe_list	列出已解析组织中的知识域。
universe_update	更新知识域（名称、描述）。
universe_hierarchy	遍历知识域的完整 L0 → L3 树，并显示状态图标。

知识层级 L0–L3（16）

Universe
  └─ Concept   (L0)  body of knowledge
       └─ Theme  (L1)  thematic split
            └─ Topic   (L2)  unit of work (status: pending / in_progress / completed)
                 └─ Point   (L3)  atomic knowledge unit

每个层级都提供 create、list、update、delete：

• L0 概念：concept_create、concept_list、concept_update、concept_delete
• L1 主题：theme_create、theme_list、theme_update、theme_delete
• L2 话题：topic_create、topic_list、topic_update、topic_delete
• L3 要点：point_create、point_list、point_update、point_delete

topic_update 和 point_update 接受 status 字段，以便 Agent 标记进度。

训练流程（6）

显式地教会系统事实、流程、问答对和完整文档。

工具	描述
training_teach	注入事实或流程。type ∈ {semantic, procedural}。
training_qa	使用 {question, answer} 的 pairs 进行训练。
training_stats	整个语料库的覆盖率统计。
training_gaps	检测到的知识缺口 / 覆盖不足的话题。
training_recent	最近通过训练导入的记忆。

编排 — 任务（4）

Memory Engine 上的任务表驱动多 Agent 编排。

工具	描述
task_create	创建任务（标题、描述、可选的 assigned_agent_id、父任务）。
task_get	获取任务及其完整状态。
task_list	使用筛选条件（状态、Agent、父任务）列出任务。
task_update	更新状态、输出或指派对象。

技能（4）

可分配给 Agent 的可复用行为。

工具	描述
skill_list	列出租户中可用的技能。
skill_assign	为 Agent 添加技能。
skill_remove	从 Agent 移除技能。
skill_agent_list	列出指定 Agent 拥有的技能。

凭据保管库（5）——credential_exec 代理工具

加密凭据存储在控制平面中，并通过 credential_ref 在记忆中引用。

工具	描述
credential_store	将加密凭据存储在某个引用名下（例如 mysql_x）。
credential_get	仅查看非机密元数据（主机/用户/数据库/端口，以及 credential_exec 将注入的环境变量）。绝不会返回凭据值。
credential_exec	**运行命令，并将凭据注入子进程的环境变量中。**仅返回 stdout/stderr/exit_code——机密信息不会到达模型、屏幕或磁盘。
credential_list	列出已存储的凭据引用（不含机密数据）。
credential_delete	删除已存储的凭据。

机密信息处理原则——服务端代理，绝不通过值传递。模型永远不会收到机密值：没有明文、没有临时文件，也没有携带机密信息的 shell 片段。要使用凭据，请调用 credential_exec。MCP 服务（已通过 npx -y frinus-mcp@latest 在本地运行）会从保管库获取凭据，将其字段注入子进程的环境变量中——绝不放入 argv，也绝不放入模型可见的任何文本——然后使用 shell:false（不进行 shell 注入）运行命令，并且只返回输出。

// MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected → standard clients just work
credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
credential_exec(ref="pg_prod",    argv=["psql",  "-c", "SELECT 1"])

// For anything else, read the injected vars inside an explicit shell:
credential_exec(ref="jira_x", argv=["sh","-c",
  "curl -sS -H \"Authorization: Bearer $CRED_TOKEN\" \"$CRED_BASE_URL/whoami\""])

注入的环境变量（凭据中存在相应字段时）：password/secret/token → MYSQL_PWD、PGPASSWORD、CRED_PASSWORD；user/username → CRED_USER、 MYSQL_USER、PGUSER；host → CRED_HOST、MYSQL_HOST、PGHOST；port → CRED_PORT、MYSQL_TCP_PORT、PGPORT；database → CRED_DATABASE、 PGDATABASE；其他任意标量 → CRED_<UPPER_SNAKE>（例如，base_url → CRED_BASE_URL）。argv 必须是字符串数组（不能是 shell 命令字符串； 如果确实需要 shell，请使用 ["sh","-c","..."]）。超时时间为 30s，输出上限为 256 KiB。所有内容都打包在 npm 包中——用户无需安装任何内容，无需编辑 PATH，也无需运行额外命令；只需使用最新的 MCP。

记忆类型

类型	用途	示例
episodic	记录发生的事情	Bug: payment endpoint returned 500. Cause: missing null check on customer.address. Fix: guard + 422 response. File: services/payment.py
semantic	存储事实和知识	`MemoryResponse now includes universe_id (UUID
procedural	记录操作流程	Procedure: rotate-claude-credentials. Steps: 1) aws ecr login, 2) kubectl set image deployment/agent..., 3) verify pod is Ready. Caveat: deployment is named "agent", not "agent-service".

作用域

作用域	可见范围	用途
user	仅存储该记忆的用户	个人偏好和历史记录
agent	仅存储该记忆的 Agent	Agent 私有备注
universe	宇宙（部门）内的所有 Agent	共享领域知识
organization	租户中的所有 Agent	组织范围内的流程和事实

旧版 agent / project / global 作用域已随 project_id 一并弃用。Universe 取代了 project，成为组织内部的隔离边界。

最佳实践

记忆的必需格式——确保未来检索具有确定性：

• Bug： Bug: <description>. Cause: <root cause>. Fix: <solution>. File: <path>
• 模式： Pattern: <description>. When to use: <context>. File: <path>
• 流程： Procedure: <name>. Steps: 1) ... 2) ... 3) .... Caveats: <warnings>

操作指南：

1. 始终先启动。 回答前调用 session_start + working_memory_get + search_with_attention。
2. 使用时强化／弱化。 回忆出的记忆有所帮助时，调用 memory_reinforce。记忆有误时，调用 memory_weaken（并替换它）。
3. 每隔 2–3 轮进行捕获。 使用 working_memory_add 记录状态，使用 stream_capture 记录决策，使用 memory_store 保存提炼后的经验。
4. 选择正确的 task_type。 search_with_attention 会根据任务对记忆类型加权。debug 倾向于情景记忆，documentation 倾向于语义记忆，deploy 倾向于程序性记忆。
5. 完成闭环。 结束会话时调用 session_summary + stream_process + session_end。批次增多时运行 sleep_run，进行更深入的整合。
6. 避免杂乱累积，及时审查。 定期调用 consolidation_detect_conflicts + consolidation_detect_redundant，让回忆保持精准。

架构

+---------------------+       +------------------+       +----------------------+
| Claude Agent /      | <---> | Frinus MCP       | <---> | Memory Engine        |
| Claude Code         | stdio | (this server)    | HTTPS | (memories, sessions, |
+---------------------+       +------------------+       |  hierarchy, tasks)   |
                                |                        +----------------------+
                                |                                  |
                                |                                  v
                                |                        +----------------------+
                                |                        | PostgreSQL+pgvector  |
                                |                        | + Apache AGE (graph) |
                                |                        +----------------------+
                                |
                                +---HTTPS---> Control Plane (universes, orgs)
                                +---HTTPS---> Agent Service (agents, invocation, skills)

• 记忆引擎负责管理记忆、工作记忆、会话、流、L0–L3 层级、训练、睡眠周期、任务和技能。
• 控制平面负责管理组织、宇宙、成员、API 密钥、计费、凭证、白标和 LLM 密钥。
• Agent 服务负责管理 Agent 运行时、工具分发、团队路由、角色设定和调用。

租户隔离采用每个租户独立数据库的方式。MCP 会在启动时根据 API 密钥解析你的租户组织 ID——你无需手动传入 org_id。

高级用法 — 自托管／本地开发

以上内容均面向 https://frinus.rdxsec.com.br 上的托管平台，这也是绝大多数人的选择。如果你运行自己的 Frinus 技术栈（或针对本地后端开发 MCP），请从源代码构建并覆盖这三个 URL：

git clone https://github.com/frinus-ai/frinus-mcp && cd frinus-mcp
npm install
npm run build      # emits dist/index.js

{
  "mcpServers": {
    "frinus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "FRINUS_API_KEY": "sk-frinus-...",
        "MEMORY_SERVICE_URL": "http://localhost:8001",
        "FRINUS_CP_URL": "http://localhost:8000",
        "AGENT_SERVICE_URL": "http://localhost:8002"
      }
    }
  }
}

发布（维护者）

# 1) npm package — powers `npx -y frinus-mcp` everywhere
npm version <patch|minor|major>
npm publish                      # prepublishOnly runs the build

# 2) .mcpb bundle — powers the Claude Desktop one-click install
npm run pack:mcpb                # -> frinus.mcpb
gh release upload v<version> frinus.mcpb --repo frinus-ai/frinus-mcp --clobber
# Frontend points at: releases/latest/download/frinus.mcpb

开发

mcp/
  src/
    index.ts                       Entry: MCP server, dispatch, auth bootstrap
    client/
      memory-client.ts             HTTP client + identity state for Memory Engine
      cp-client.ts                 HTTP client for Control Plane
      agent-client.ts              HTTP client for Agent Service
    tools/
      definitions.ts               Tool schemas (70 tools)
      handlers.ts                  Tool handlers (70 handlers)
    capture/
      interaction-capture.ts       Auto stream capture for every tool call
    types/
      index.ts                     Shared types
  dist/                            Compiled output (npm run build)
  package.json
  tsconfig.json

脚本：

npm run build     # tsc to dist/
npm run dev       # tsx hot reload (src/index.ts)
npm start         # node dist/index.js

类型检查：TypeScript 5.6+、ES 模块、axios。

许可证

许可条款请参阅仓库根目录。