跨 Agent 统一记忆层：一个独立部署的 REST 服务，把记忆存储、混合检索、知识图谱、情绪状态、梦境式记忆巩固、Obsidian 双向同步统一收拢在一个数据库和一套 API 之后，供 Hermes、OpenClaw、Claude Code 等任意 Agent 通过 HTTP 接入。
HCC 不是某个 Agent 框架的内置记忆插件，而是一个独立于任何具体 Agent 运行时的认知操作系统：Agent 只需要会发 HTTP 请求，就能获得持久记忆、语义检索、情绪连续性和夜间自动整理。Works with OpenClaw / Hermes / Claude Code —— 已提供 OpenClaw 官方插件（hcc-memory）与 Claude Code MCP server，其余 Agent 运行时只要能发 HTTP 请求即可接入。
HCC 主体 MIT 开源：核心记忆层、混合检索、知识图谱、梦境巩固、情绪引擎、Obsidian 双向同步全部开源可用，可以直接 fork、自部署、二次开发，没有闭源核心。
hcc-openclaw-plugin/（hcc-memory）是这套记忆层在 OpenClaw 生态里的具体落地：独立插件包、标准 openclaw.plugin.json 清单、声明式 configSchema，定位是能进入 OpenClaw 插件市场/社区插件列表的独立分发单元，装上即用，不需要改 OpenClaw 本体代码。同样的「REST 网关 + 轻客户端」模式也能给 Hermes、Claude Code（MCP）或任意会发 HTTP 请求的 Agent 提供记忆能力——开源核心 + 多端插件分发，是这个项目的长期定位。
Related MCP server: RecallNest
大部分记忆系统只是把对话存进数据库，检索的时候捞一把——HCC 不一样。每天，HCC 会像人一样，把清醒时攒下的记忆做一遍梦：
🌙 Light（浅睡）——短周期聚合当天零散记忆，先做一轮轻量归纳
🌀 REM（快速眼动）——跨天聚类找主题，把散落多日的相关记忆串成线索
🌊 Deep（深睡）——去重、提炼，生成真正沉淀下来的知识，反向写回 Memory
三阶段全部幂等（每天每阶段只跑一次），醒来后 Agent 的知识库比睡前更清晰、更精炼——不是简单的日志归档，而是真正意义上的记忆巩固。更妙的是，每一次梦境都会生成一篇叙事化梦境日记，写进 Obsidian vault：不是干巴巴的处理日志，而是用第一人称讲述"今天梦到了什么、想起了什么"的可读文字，配一份结构化审计报告方便你追溯每一条知识的来源。你的 Agent 不只会记事，还会在无人打扰的夜里，独自消化、成长。
HCC 内置一套 6 维情绪引擎：happiness（愉悦）/ curiosity（好奇）/ fatigue（疲惫）/ worry（担忧）/ closeness（亲近）/ focus（专注），随每一次对话、每一条记忆、每一场梦境持续演化——不是写死的人设开关，而是真正随着交互历史累积漂移的连续状态。多个维度还会组合成具名复合情绪状态（比如"雀跃""低落"），让 Agent 的情绪表达有名字、可辨认、可追溯，而不是一串冷冰冰的数字。
情绪不只是摆设：检索结果会按当前情绪心境一致性加权，梦境 Deep 阶段还能反向调整情绪基线——记忆影响心情，心情也会影响 Agent 想起什么、怎么想。session_end 时情绪状态写回，session_start 时自动 warm-start，跨会话连续不断线，你的 Agent 不会在每次开场都"失忆归零"。专门开放的 /emotion/display 展示模式接口，就是为了配 USB 小屏这类物理外设设计的——把 Agent 此刻的心情，实实在在地摆在桌面上，抬头就能看见。这不是功能堆砌，是想让"陪伴感"这件事，真正有据可依。
┌─────────────────────────────┐
│ Agent 层 │
│ Hermes / OpenClaw / Claude │
│ Code / 任意会发 HTTP 的 Agent │
└───────────────┬───────────────┘
│ REST / SSE
┌───────────────▼───────────────┐
│ Gateway API（FastAPI） │
│ /api/v1/* ，统一入口 + 路由 │
└───┬─────┬─────┬─────┬─────┬────┘
│ │ │ │ │
┌──────────────┘ │ │ │ └──────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌──────────┐ ┌──────┐ ┌────────────┐ ┌───────────┐
│ Memory │ │ Dream │ │Emotion│ │ EventBus │ │ MCP │
│ 混合检索/CRUD │ │三阶段巩固 │ │6维状态机│ │ Redis Pub/Sub│ │ stdio 协议 │
└─────┬─────┘ └────┬─────┘ └──┬───┘ └──────┬─────┘ └───────────┘
│ │ │ │
└──────┬───────┴──────────┴────────────┘
▼
┌───────────────────────┐ ┌─────────────────────┐
│ PostgreSQL 17 │ │ 本地降噪（可选） │
│ + pgvector │◄───────┤ Ollama qwen3.5 异步复核│
└───────────┬───────────┘ └─────────────────────┘
│
▼ Sync Engine（双向）
┌───────────────────────┐
│ Obsidian Vault │
│ QMD 知识文档 / 梦境日记 / │
│ per-agent 导出 / vault API │
└───────────────────────┘Gateway API：FastAPI 单入口，所有模块通过 /api/v1/* 暴露，CORS 开放
Memory：记忆 CRUD + 三种检索模式（关键词 / 向量 / 混合 BM25+向量+RRF）
Dream：夜间三阶段记忆巩固（Light 聚合 → REM 聚类 → Deep 去重生成知识），带 Obsidian 梦境日记
Emotion：6 维度情绪引擎（happiness/curiosity/fatigue/worry/closeness/focus）+ 具名状态机，随对话/记忆/梦境事件演化
EventBus：Redis Pub/Sub（可选，未启用时退化为进程内内存广播），驱动情绪联动、降噪复核、SSE 推送
Sync：PostgreSQL ↔ Markdown 双向同步引擎，定时 + 事件触发
Obsidian：QMD 知识文档生成、per-agent 记忆导出、只读 vault 浏览 API、梦境日记写入
本地降噪：异步订阅记忆写入事件，用本地 Ollama 模型复核低置信度记忆（tool_result/插件写入），软删除噪音，不阻塞主写入路径
MCP：stdio 协议 server，把核心记忆工具暴露给支持 MCP 的客户端（Claude Code 等）
混合检索：BM25（PostgreSQL 全文 + jieba 中文分词）+ pgvector 向量检索，RRF（Reciprocal Rank Fusion）融合排序，可选 Qwen3 交叉编码器重排（HCC_RERANK_ENABLED）
本地模型降噪：低置信度记忆（工具调用结果、第三方插件写入）异步过 Ollama qwen3.5:4b 复核，噪音软删除（status=discarded），从不阻塞写入、从不硬删除
梦境三阶段：Light（短周期聚合）→ REM（跨天标签聚类找主题）→ Deep（去重生成知识 + 写入 Memory + 梦境日记），全部幂等（每天每阶段只跑一次，force 可强制重跑）
情绪 6 维状态机：happiness / curiosity / fatigue / worry / closeness / focus 连续维度 + 具名复合状态（如"雀跃"/"低落"），检索结果按情绪心境一致性加权，梦境 Deep 阶段可反向调整情绪基线
Obsidian 双向导出：知识文档（QMD）自动生成、per-agent 人类可读记忆导出、梦境日记（叙事 + 审计报告双文件）、孤儿文档自动归档
只读 vault API：/vault/list / /vault/read，路径严格限制在 HCC_VAULT_ROOT 内（拒绝 ..、拒绝逃逸的软链、拒绝绝对路径）
SSE 多端感知：/events/stream 推送记忆变更事件（store/update/delete），供旁路监听器、多客户端保持状态同步
Redis EventBus：可选，未配置时优雅降级为进程内内存事件总线，模块间零耦合
以下是作者本人生产环境跑 HCC 的真实 30 天用量数据（DeepSeek API 账单，不是营销基准测试）：
指标 | 数值 |
30 天总成本 | ¥285.67 |
日均成本 | ~¥9.5 |
Prompt 缓存命中率 | 98%（6313.6M tokens 命中 / 126.8M 未命中） |
输出 tokens | 13.6M |
模型成本占比 | flash ¥277.43（97%）+ pro ¥8.24（3%） |
为什么这么便宜：
98% 缓存命中率是结构性的，不是偶然——HCC 把记忆检索结果、系统上下文按稳定结构拼装复用，重复上下文命中缓存价，而不是每轮都按原价 token 重新计费
本地 embedding，0 API 成本——向量化默认走本地 Ollama（qwen3-embedding:0.6b，1024 维，中文语义强于 nomic-embed-text），混合检索/语义检索不产生任何 embedding API 调用费用
无 OCR、无强制云端依赖——PDF/文档索引走本地 pdf-inspector 解析，本地降噪走本地 Ollama 模型复核低置信度记忆；除非你自己接了云端 LLM API，整条记忆链路可以完全离线运行，跑不出账单
BM25 + 向量混合检索（RRF 融合，可选 Qwen3 交叉编码器重排）——大部分召回不需要触发昂贵的语义精排，进一步压低单次调用成本
数据来自 icemaple77 本人真实生产 Agent 的账单快照（2026-08），具体成本因你接入的模型、调用量、上下文结构而异，仅供参考。
Python 3.11+
PostgreSQL 17 + pgvector 扩展
Redis（可选，未启用时事件总线退化为进程内内存广播）
Ollama（可选，本地降噪 / 本地 embedding 需要；不装也能跑，HCC_EMBEDDING_PROVIDER=hash 走零依赖哈希 embedding）
方式一：一键安装脚本（推荐）
git clone https://github.com/icemaple77/hanyan-cognitive-core.git
cd hanyan-cognitive-core
./install.shinstall.sh 会依次检测/安装 Python 3.11+、PostgreSQL 17 + pgvector（有 Docker 优先用 docker compose 一键起 pgvector 容器，没有则走 Homebrew/apt 原生安装）、可选 Redis/Ollama，创建 venv 装依赖，生成 .env，最后建表——幂等，重复运行安全。可选参数：--full（含 rerank + PDF extras）、--skip-db / --skip-redis / --skip-ollama，完整说明见 ./install.sh --help。
方式二：手动安装
git clone https://github.com/icemaple77/hanyan-cognitive-core.git
cd hanyan-cognitive-core
# 用 uv（推荐，仓库自带 uv.lock）
uv sync
# 或用 pip
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"cp .env.example .env
# 至少确认 HCC_DATABASE_URL 指向可用的 PostgreSQL 实例关键环境变量（完整列表见 .env.example，以及 gateway/core/config.py / core/config.py 里每项的详细说明）：
变量 | 说明 |
| PostgreSQL 连接串（必需） |
| Obsidian 知识文档输出目录 |
| Redis EventBus 开关，默认 |
| 本地降噪开关，默认 |
| 混合检索交叉编码器重排开关，默认 |
| Obsidian vault 根目录，供 |
docker compose up -d db redis # 仅启动依赖，不用容器跑 HCC 本体也可以直接用本机已有的 PostgreSQL/Redis，只要在 .env 里指对连接串即可——本地开发无需 Docker。
uv run uvicorn gateway.main:app --reload --host 0.0.0.0 --port 8000
# 或用 Makefile
make dev首次启动会自动建表（SQLAlchemy metadata create_all）并起 3 个梦境后台循环 + 同步循环（受 HCC_DREAM_AUTO_ENABLED / HCC_SYNC_AUTO_ENABLED 控制）。
curl http://localhost:8000/api/v1/health
# → {"status":"ok","version":"0.1.0","service":"hanyan-cognitive-core"}仓库提供 Dockerfile + docker-compose.yml（api + mcp + db + redis 四个服务），适合部署到常驻服务器：
docker compose up -d统一前缀 /api/v1。完整 OpenAPI 交互文档见运行中的 http://localhost:8000/docs。
POST /memory/store — 存入记忆
POST /memory/search — 关键词搜索（ILIKE，支持 user_id/agent_id/shared 过滤）
POST /memory/update — 更新
POST /memory/delete — 删除
POST /memory/touch — 命中强化（access_count+1, last_access=now）
GET /memory/recent — 最近记忆
POST /memory/semantic-search — 纯向量语义搜索
POST /memory/hybrid-search — BM25 + 向量混合检索，RRF 融合（推荐入口）示例：
curl -X POST http://localhost:8000/api/v1/memory/hybrid-search \
-H "Content-Type: application/json" \
-d '{"query":"上次部署踩的坑","limit":10,"user_id":"me","agent_id":"main"}'POST /document/search
POST /document/hybrid-search
GET /document/recentPOST /context — 自动编排 Memory + Knowledge + Emotion，一次调用拿到组装好的上下文POST /graph/entity — 添加实体
POST /graph/relation — 添加关系
POST /graph/query — 查询图谱
GET /graph/entity/{entity_id} — 实体详情GET /emotion/state — 当前情绪（完整维度，供 Agent 内部使用）
GET /emotion/display — 当前情绪（展示模式，供小屏/UI 使用）
POST /emotion/update — 从文本触发情绪更新
GET /emotion/history — 近期触发日志
GET /emotion/snapshots — 每日冷快照（Deep 阶段生成，供心情趋势回顾）POST /dream/light — 触发 Light 阶段（幂等：每天每条记忆一次）
POST /dream/rem — 触发 REM 阶段（幂等：每天一次）
POST /dream/deep — 触发 Deep 阶段，写入 Memory + 日记（幂等：每天一次）
GET /dream/status — 各阶段最近一次运行时间 + 当前阈值配置GET /vault/list?path= — 列出目录（默认 vault 根目录）
GET /vault/read?path= — 读取文件内容（路径越权一律拒绝）POST /sync/qmd — 手动触发 PostgreSQL → Markdown 同步
GET /sync/status — 同步状态
POST /export/agents — 重新生成 per-agent_id 人类可读导出GET /events/stream — 订阅记忆变更事件流（store/update/delete）POST /orchestrator/evaluate — 判断一段内容是否值得存储
GET /forget/scan — 遗忘扫描（只读，不写库）
POST /forget/apply — 执行遗忘（归档，永不物理删除）
GET /personality/summary — 人格画像
POST /personality/process — 处理文本更新人格画像
POST /subconscious/retrieve — 三层检索（意识/前意识/潜意识）
GET /router/summary — 模型调度配置
POST /router/profile — 切换硬件档位
POST /optimizer/scan — 扫描可吸收文件
POST /optimizer/run — 执行完整工作区优化
POST /optimizer/bootstrap — 生成引导文件
POST /indexer/scan — 扫描工作区知识文件
POST /indexer/run — 索引工作区知识
POST /dream/consolidate — 旧版一次性记忆巩固（向后兼容，新代码用上面的三阶段接口）mcp/server.py）store_memory / search_memories / recall / semantic_search /
hybrid_search / get_recent_memories / delete_memory / evaluate在支持 MCP 的客户端（如 Claude Code）里配置 mcp/server.py 为 stdio server 即可直接使用。
hcc-openclaw-plugin/ 目录是一个独立的 OpenClaw 插件（hcc-memory），通过 HTTP 调用 HCC 的 REST API，无需和 HCC 部署在同一台机器，定位是可以直接进 OpenClaw 插件市场/社区插件列表的独立分发单元。详见 hcc-openclaw-plugin/README.md，要点：
工具：memory_search（走 /memory/hybrid-search，BM25+向量+RRF 融合）、memory_get（按 id 或内容匹配）
session_start 自动 recall + 情绪 warm-start：新会话开始时自动从 HCC 拉取相关历史记忆（按 importance 排序取 top-N）和当前情绪状态，在下一次 before_prompt_build 时一次性注入系统上下文——Agent 不用等用户先问才想起上次聊过什么
session_end 情绪回写：会话结束时把摘要文本喂给 /emotion/update，情绪状态跨会话连续演化，下次 session_start 能读到最新情绪
其余钩子：before_compaction（压缩前快照）、tool_result_persist（工具结果低权重存入，配合 HCC 侧本地降噪异步复核）
配置：插件 configSchema 的 baseUrl / userId / agentId，或对应的 HCC_BASE_URL / HCC_USER_ID / HCC_AGENT_ID 环境变量；session_start/情绪相关开关见插件 README
本地开发不需要 Docker：只要有一个可访问的 PostgreSQL（装了 pgvector 扩展）实例，改好 HCC_DATABASE_URL 直接 uvicorn 启动即可；Redis、Ollama 均为可选依赖，未配置时对应功能优雅降级或关闭。
embedding 零依赖跑通：HCC_EMBEDDING_PROVIDER=hash 用确定性哈希代替真实向量模型，适合先把链路跑通再接真实 embedding（ollama 或 sentence-transformers）。
重排模型是可选加分项：HCC_RERANK_ENABLED=false（默认）时，混合检索仍然是完整的 BM25+向量+RRF 融合，只是不做二次交叉编码器重排。
数据库表自动创建：首次启动 uvicorn 会通过 SQLAlchemy create_all 自动建表，无需手动跑 migration 脚本即可开发（生产环境建议接入 Alembic，仓库已列出该依赖）。
容器化部署：docker-compose.yml 提供 api + mcp + db + redis 四服务栈，适合部署到常驻服务器；Dockerfile 仅打包 gateway/core/scanner/mcp，不含开发依赖。
Delete a memory by its id (permanent — use forget/apply via the REST API for reversible archiving instead if you just want it to fade, not vanish).
Args: memory_id: The id of the memory to delete (required).
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the permanent destructive nature of the action ('permanent' and 'vanish'), which is critical transparency. However, it does not mention any side effects, permissions, or confirmation requirements beyond the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise — two sentences with zero waste. The first sentence states the action and permanence, the second provides the alternative, and the args block is clearly structured. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no nested objects), the description is largely complete. It covers the action, permanence, and alternative. The only minor gap is that it doesn't explicitly describe return values or error behavior, but given the minimal complexity and lack of output schema, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the lack of parameter details. It does so by providing a concise explanation of the `memory_id` parameter: 'The id of the memory to delete (required).' This adds a clear, actionable meaning beyond the schema's bare 'Memory Id' title, though it could be slightly more descriptive about how to obtain this id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Delete a memory by its id' — a specific verb and resource. It distinguishes itself from other memory-related tools by mentioning an alternative for non-permanent removal, which helps differentiate from recall/search/store tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides guidance on when to use this tool versus an alternative: 'permanent — use forget/apply via the REST API for reversible archiving instead if you just want it to fade, not vanish.' This clearly communicates the intended use case and offers a specific alternative for a different scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask HCC's orchestrator whether a piece of content is worth remembering, before storing it.
Use this to avoid flooding long-term memory with trivial chatter — only call store_memory for content where should_store comes back true (or when you have an explicit reason to override, e.g. the user said "remember this").
Args: content: The text to evaluate. agent_id: Which agent is asking (for future per-agent tuning). user_id: Whose content this is.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| user_id | No | default | |
| agent_id | No | default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that the tool returns a value indicating whether to store (implied by 'should_store comes back true') and notes that agent_id is for future tuning. However, it does not explicitly state the exact return format or any side effects, though the implied boolean and purpose are reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by a clear usage guideline and parameter list. Every sentence contributes meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no output schema, the description is fairly comprehensive. It explains the tool's role, when to use it, and parameter semantics. The return type is implied but not explicitly stated, and it lacks details on error handling or edge cases, so it's not fully complete for a production tool without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only types and defaults, with zero descriptions. The description's Args section explains each parameter's meaning (content as text to evaluate, agent_id as the asking agent for tuning, user_id as whose content this is), significantly adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to ask HCC's orchestrator whether content is worth remembering before storing it. It uses a specific verb (ask) and resource (orchestrator) and distinguishes itself from siblings by explicitly positioning it as a pre-store gate for store_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool ('only call store_memory for content where should_store comes back true') and when to override, including a concrete example (user says 'remember this'). This provides clear guidance on using it versus the alternative store_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the most recently created memories.
Args: limit: Max number of results (1-100). Defaults to 20. user_id: Restrict to a specific user. agent_id: Restrict to a specific agent's memories.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| user_id | No | ||
| agent_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the primary action and parameters, without revealing whether the operation is read-only, any authorization requirements, result ordering specifics, or error behavior. This is minimal transparency for a retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence purpose statement followed by a formatted Args list. It is front-loading the main functionality and avoids any fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and parameters, but given the absence of annotations, output schema, and usage guidance, it is not fully complete. It lacks details about return format, ordering, edge cases, or interactions with sibling tools, leaving some room for ambiguity in invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for parameters (coverage 0%), but the description thoroughly explains each parameter: limit with range and default, user_id as a restriction, and agent_id as a restriction. This adds meaningful context beyond the schema's type/default definitions, fully compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return the most recently created memories.' This specifies the verb (return), resource (memories), and scope (most recently created), which distinguishes it from sibling tools like search_memories or recall that likely perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving recent memories but provides no explicit guidance on when to choose this tool over alternatives like search_memories or hybrid_search. There are no references to other tools or exclusions, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hybrid search: BM25 full-text + vector similarity, fused with Reciprocal Rank Fusion.
Best default choice for "find memories about X" — combines exact keyword
matches (BM25) with semantic similarity, so it doesn't miss relevant
memories that use different words than the query (e.g. "显卡" vs "GPU").
Passing just query runs both branches — the server embeds the query text
itself (ollama, server-side) for the vector branch, no client-side
embedding model needed. Provide at least one of query/embedding.
Args:
query: Free-text query. Drives the BM25 branch (jieba-segmented
server-side) and, unless embedding is given, is also embedded
server-side for the vector branch. Optional if embedding is given.
embedding: Precomputed query embedding for the vector branch, advanced/
optional — normally you just pass query and let the server embed it.
user_id: Restrict to a specific user.
agent_id: Restrict to a specific agent's memories.
type: Restrict to a specific memory type.
limit: Max number of results (1-100). Defaults to 10.
rerank: Rerank the fused top results with the optional cross-encoder
(Qwen3-Reranker-0.6B). Off by default — adds latency; silently
falls back to RRF order if the reranker isn't enabled/available
server-side (HCC_RERANK_ENABLED).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | ||
| query | No | ||
| rerank | No | ||
| user_id | No | ||
| agent_id | No | ||
| embedding | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden—and it delivers: it discloses server-side embedding via ollama, jieba segmentation for BM25, RRF fusion, rerank latency and silent fallback to RRF order when the reranker is unavailable, and the requirement to provide at least one of query/embedding. These behavioral details go well beyond the schema and give the agent a solid model of the tool's execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized: a two-sentence overview of the algorithm and use case, then a structured Args block. Every sentence conveys essential information—no filler or repetition. The length is justified by the complexity of a hybrid retrieval tool with optional reranking.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (dual retrieval branches, fusion, optional reranking) and the absence of annotations and output schema, the description provides robust coverage: algorithm, default behavior, server-side processing, latency implications, fallback semantics, and parameter constraints. The only omission is the exact return shape, but for a search tool this is acceptable and the description is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining every parameter: the dual role of query, the advanced/optional nature of embedding, the restriction semantics of user_id/agent_id/type, the limit's range and default, and the rerank flag's latency and fallback. This is complete, actionable parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise definition: 'Hybrid search: BM25 full-text + vector similarity, fused with Reciprocal Rank Fusion.' It then identifies the tool as the 'Best default choice for "find memories about X"', clearly distinguishing it from siblings like semantic_search or search_memories by combining exact keyword and semantic matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool is explicitly positioned as the 'best default choice' for memory retrieval, with an example of when hybrid search shines (different wording like '显卡' vs 'GPU'). It explains when to provide query vs embedding and mentions the optional rerank behavior, but does not explicitly name sibling alternatives or state when not to use this tool, making the guidance clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Three-layer memory retrieval (conscious/preconscious/subconscious).
Better than plain keyword search for "what do I remember about X" — merges current-session context with database recall, ranked by relevance.
Args: query: What to recall. user_id: Restrict to a specific user. agent_id: Restrict to a specific agent's memories. limit: Max number of results. Defaults to 5.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| user_id | No | ||
| agent_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral info. It discloses the three-layer approach, context merging, and ranking, but does not explicitly state that it is read-only, describe the output format, or mention any side effects or limitations. This is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro followed by a clear argument list. Every sentence adds value, and it avoids unnecessary verbosity. It front-loads the core purpose and then details parameters efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return value or output structure, which is important for a retrieval tool. It also omits potential edge cases or evaluation criteria. While the tool is not highly complex, the absence of output information leaves a notable gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives meaningful explanations for all four parameters (query, user_id, agent_id, limit), including purpose and default for limit. This fully compensates for the 0% schema description coverage, providing essential context beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Three-layer memory retrieval' and explains its value over plain keyword search. However, it does not explicitly distinguish itself from sibling search tools like search_memories or semantic_search, so it lacks direct differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides guidance on when to use it ('Better than plain keyword search for "what do I remember about X"') and highlights its unique features (merging session context, ranked relevance). Yet it does not mention when not to use it or name alternative tools as options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword-search memories (case-insensitive substring match on content/summary).
Args: query: Substring to search for (required). user_id: Restrict to a specific user. agent_id: Restrict to a specific agent's memories. type: Restrict to a specific memory type. limit: Max number of results (1-100). Defaults to 20.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | ||
| query | Yes | ||
| user_id | No | ||
| agent_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses key behaviors: case-insensitive substring matching, optional filters, and default limit. It does not mention output structure or edge cases, but covers the core behavioral contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line summary followed by a clear Args block. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description handles parameters and behavior well. It omits return value format, but for a search tool the result is implied to be memories; minor gap but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides a full Args section explaining each parameter (query, user_id, agent_id, type, limit) with defaults and constraints, fully compensating for the absence of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs keyword search (case-insensitive substring match) on memories, with a specific verb and resource. It distinguishes itself from semantic/hybrid search siblings by emphasizing substring matching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage for substring-based retrieval and lists filter parameters, but does not explicitly state when to choose this over sibling tools like semantic_search or hybrid_search, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic-similarity search over stored memories (pgvector cosine distance).
Pass free-text query — the server embeds it (ollama, server-side) before
searching. embedding remains available for passing a precomputed vector
directly, but is no longer required.
Args:
query: Free-text query, embedded server-side. Required unless embedding is given.
embedding: Precomputed query embedding vector, advanced/optional.
user_id: Restrict to a specific user.
agent_id: Restrict to a specific agent's memories.
type: Restrict to a specific memory type (e.g. "knowledge" for the Obsidian vault).
limit: Max number of results (1-100). Defaults to 10.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| limit | No | ||
| query | No | ||
| user_id | No | ||
| agent_id | No | ||
| embedding | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no behavioral traits, side effects, or operational details disclosed because the description contains no information about the tool at all. With zero annotations and zero meaningful description, the burden was entirely on the description, and it provides nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While one could argue a single directive is 'concise,' this is not conciseness—it is tragic under-specification. Every word is spent restating the evaluation prompt rather than defining a tool. There is no structure, no front-loading, and no useful information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides zero of the context needed to use the tool. Even for a hypothetical 0-arg operation this would be inadequate, but for an undefined operation it is entirely hopeless. The agent has no way to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined anywhere in the input. The framework itself notes that 0 parameters means a baseline of 4, but in this case the absence of parameters is not the same as a well-understood 0-arg tool—the input is entirely empty of semantic content. There is no schema for the description to supplement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a verbatim copy of the evaluation framework's own instructions—there is no tool name, title, or purpose stated anywhere. It is entirely impossible to determine what tool this describes, let alone distinguish it from siblings. This is a complete failure of communication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever on when to use this tool vs. alternatives. The text is meta-instruction about how to reply to the original prompt, not about the tool itself. No context, no exclusions, nothing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new memory in HCC.
Args: content: The memory text to store (required). user_id: Owner of the memory (e.g. "michael"). agent_id: Which agent this memory belongs to (e.g. "hanyan", "hermes", "openclaw-main"). Memories are scoped by agent_id — different agents don't see each other's memories unless explicitly queried across agents. type: Memory category, e.g. "general", "knowledge", "fact", "preference". summary: Optional short summary of the content. importance: Relevance score in [0, 1]. Defaults to 0.5. tags: Optional list of string tags. embedding: Deprecated, ignored. The server always computes its own embedding (ollama, server-side) so every memory lands in the same vector space — kept only so old callers that still pass one don't break.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| type | No | general | |
| content | Yes | ||
| summary | No | ||
| user_id | No | default | |
| agent_id | No | default | |
| embedding | No | ||
| importance | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does an excellent job: it explains that the embedding parameter is deprecated and ignored, that the server computes its own embedding, and that memories are scoped by agent_id. This goes beyond the schema and provides critical behavioral context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening line and a bulleted parameter list. It is slightly verbose due to the detailed parameter explanations, but every sentence adds value, especially the deprecation note and scoping explanation. It is appropriately sized for an 8-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no annotations, no output schema), the description is remarkably complete. It covers all parameters, explains scoping, deprecation, and defaults, and provides examples. The agent has everything it needs to invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Every parameter is explained with examples and constraints (e.g., importance range, agent_id examples, type categories, embedding deprecation). This adds significant meaning beyond the raw schema, which only provides types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Store a new memory in HCC.' It uses a specific verb ('store') and resource ('memory in HCC'), and the detailed parameter explanations distinguish it from sibling tools like search_memories, recall, and delete_memory, which are all about retrieval or deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to store a new memory) and explains the scoping behavior of agent_id, which is crucial for understanding how memories are isolated. However, it does not explicitly mention when not to use it or name alternative tools for similar operations, though the sibling list makes that implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0delete_memoryevaluateget_recent_memorieshybrid_searchrecallsearch_memoriessemantic_searchstore_memoryScored across 8 tools
Store, delete, and evaluate are clearly distinct, but there are four retrieval-oriented tools (search_memories, semantic_search, hybrid_search, recall) with overlapping purposes. The descriptions help differentiate them, but an agent could easily pick the wrong one when simply trying to find relevant memories.
Several tools follow a verb_noun pattern (store_memory, delete_memory, search_memories, get_recent_memories), but recall is a bare verb and semantic_search/hybrid_search are adjective_noun names. The mixed conventions are readable but not fully consistent.
With 8 tools, the server is well-scoped for a memory system. Each tool serves a meaningful purpose: storing, retrieving via multiple strategies, deleting, and evaluating whether content is worth remembering.
The core memory lifecycle is covered: store, retrieve, search, recall, and delete. One minor gap is the lack of an update/edit operation for existing memories, though this can be worked around by storing a new memory or deleting the old one.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
One memory, every AI: Claude, ChatGPT, Perplexity, Gemini, Cursor, OpenClaw, Hermes, any MCP client.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
