Skip to main content
Glama

Ebb — 面向智能体的知识图谱

为 AI 智能体构建的长期记忆,以图的形式实现。相关性是基于近期性的加权连接强度:重复使用的知识保持活跃,未使用的知识会衰减并被归档,除非人类确认,否则不会删除任何内容。可嵌入式运行(零基础设施)或运行在 Neo4j 上(生产环境)。

它围绕的两个机制——连接加权相关性和时间衰减——都是原生图操作,并且两者都有深厚的先例(PageRank/中心性;认知科学中的 ACT-R 基级激活和扩散激活;间隔重复遗忘曲线)。这是对该谱系的一个小而诚实的实现,专门针对智能体记忆。


为什么这样构建

1. 引擎和接口是分离的。 图存储位于一个小接口(GraphStore)之后。智能体和评分逻辑从不接触特定数据库,因此你今天可以在嵌入式引擎上运行完全相同的图,以后只需一个环境变量即可切换到 Neo4j。

2. 相关性是基于近期性的,而不是原始连接数。 “连接越多 = 越相关”会永远奖励旧的、被大量引用的数据——这正是系统要消除的过时数据问题。在这里,每条边对相关性的贡献都乘以一个时间衰减因子,该因子取决于连接上次被强化的时间。昨天被强化的边几乎算作满值;六个月前最后接触的边几乎不算。重用连接(recall/reinforce)会重置其时钟——因此相关性跟踪实际活跃的内容,过时的知识会自行沉没。

证明,来自演示种子图(python -m ebb.demo):

node                             raw#   activation
decision:outcome-pricing            3        6.116   <- fresh, few links, ranks #1
decision:seat-pricing              11        3.077   <- MOST links, ranks #3
...
note:analysis-* (x10)               1        0.051   <- decayed -> archived (tier 4)

被取代的按席位决策拥有图中最高的原始连接数,但仍然排名第三,落后于一个链接数只有其三分之一的新决策。原始计数输了;近期性赢了。


Related MCP server: Memory Engine MCP

包含什么

  • 图模型 — 每个笔记、决策、会议、人员、客户、事实都是一个节点;每个引用都是一条带时间戳、类型化、加权的边。

  • 评分引擎(scoring.py)— 基于近期性的激活、指数衰减(可配置半衰期)、一跳扩散激活(PageRank 的可移植替代品)以及层级分配。纯函数,完全单元测试。

  • 四个归档层级 — 1 热(默认召回)· 2 温(更深召回)· 3 冷(已归档,仅按需)· 4 冻结(删除前需人工确认)。固定节点永远不会自动归档。

  • MCP 服务器(mcp_server.py)— 智能体接口:remember、recall、connect、reinforce、forget、neighbors、pin、maintain、review_queue、stats。

  • 两个后端 — KuzuStore(嵌入式,默认)和 Neo4jStore(生产环境),相同的接口,相同的 Cypher 形状。


快速开始(嵌入式 — 零基础设施)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m ebb.demo      # narrated end-to-end walkthrough
pytest -q                 # 11 tests, all green

无需 Docker,无需服务器,无需端口。Kùzu 是一个进程内图数据库,因此 Ebb 只是一个文件夹(./ebb_db)。

将其接入 MCP 客户端(例如 Claude Desktop)

  1. 将 claude_desktop_config.example.json 中的 ebb 块复制到客户端的 MCP 配置中,并修正绝对路径。

  2. 重启客户端。ebb 工具会出现在工具菜单中。

  3. 智能体现在可以跨会话 remember 内容,recall 相关内容,并 reinforce 它持续使用的内容——衰减和归档由系统自动处理。

生产模式(Neo4j)

docker compose up -d      # Neo4j + Graph Data Science + APOC
EBB_BACKEND=neo4j NEO4J_PASSWORD=brainbrain python -m ebb.demo

相同的代码,相同的行为。在 Neo4j 上,你还可以获得 GDS 库,因此当规模需要时,scoring.py 中的扩散激活过程可以升级为真正的 PageRank / 中心性 / 社区检测。(Neo4j 后端的 Cypher 镜像了经过完全测试的 Kùzu 后端;在生产环境中信任它之前,请对实时实例运行 pytest。)


模型简述

节点的激活值 = Σ (edge.weight × decay(age_since_last_reinforced)) + read-recency-bonus,再加上来自其邻居的同一衰减一跳。衰减是半衰期(默认 30 天,可调)。层级根据相对于最活跃的非固定节点归一化的激活值进行划分。recall 将此激活值与查询文本匹配相结合,并返回每个结果出现的原因。所有内容都可以在一个地方调整 — ebb/scoring.py::Config。

编写摄取适配器

Ebb 与来源无关:任何调用 remember/connect 的内容都可以为其提供数据。一个来源(笔记文件夹、wiki、问题跟踪器)通过将文档映射到节点、链接/提及映射到边、编辑时间戳映射到近期性时钟,从而成为图。将适配器及其数据保留在仓库之外。

目录结构

src/ebb/
  model.py        # Node, Edge, tiers
  scoring.py      # decay, activation, spreading, tiering  <- the core
  store.py        # GraphStore interface
  kuzu_store.py   # embedded backend (default)
  neo4j_store.py  # production backend
  engine.py       # Brain: remember/recall/connect/reinforce/maintain/...
  mcp_server.py   # agent-facing MCP tools
  seed.py         # fictional demo graph
  demo.py         # narrated walkthrough
tests/            # 11 tests: scoring + end-to-end
docker-compose.yml

许可证

MIT — 参见 LICENSE。

Available Tools

10 tools
connectA

Create a connection from node src to node dst. If it already exists it is reinforced (its decay clock resets). rel examples: references, about, mentions, decided_in, involves, depends_on, contradicts, supersedes.

NameRequiredDescriptionDefault
dstYes
relNoreferences
srcYes
weightNo

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that an existing connection is reinforced and its decay clock resets, which is a key behavioral trait. It also provides rel examples for context. However, it does not mention prerequisites (e.g., nodes existing) or what happens to weight during reinforcement, which would be useful but not critical.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action. The reinforcement behavior is stated immediately, and rel examples follow. There is no filler or redundancy, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 4-parameter mutation tool with no output schema, the description covers the essential purpose and reinforcement behavior, but leaves weight unexplained and does not mention requirements (e.g., existing nodes) or error conditions. This is adequate for a minimal viable definition but has clear gaps that an agent might need filled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no descriptions (0% coverage), so the description must add meaning. It explains src and dst as nodes, and gives rel examples, but says nothing about weight. This partial coverage leaves weight's purpose ambiguous. The description adds some value but does not fully compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Create a connection from node src to node dst') with a clear verb and resource, and further clarifies the reinforcement behavior on existing connections. This distinctly separates it from siblings like remember (which likely deals with nodes) and reinforce (which may target nodes or other resources).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (to create or reinforce connections), and gives rel examples for typical use cases. However, it does not explicitly compare with siblings such as reinforce or recall, nor does it state when not to use it. The guidance is implicit rather than direct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

forgetA

Permanently delete a node and its connections. Prefer letting decay + the tier-4 review queue handle phase-out; use this only for deliberate deletion.

NameRequiredDescriptionDefault
node_idYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the behavioral burden. It states the operation is permanent and destructive, covering the key side effect (deletion of connections). However, it does not mention any prerequisites, error handling, or authorization needs, which is a minor gap for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences deliver the function and usage guidance without wasted words. The core action is front-loaded, and the additional guidance is placed after, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, no-output-schema tool, the description provides everything needed to invoke it correctly: what it does, when to use it, and when not to. The scope of deletion (node and connections) is explicitly stated, and the permanence is clear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter node_id is left entirely to the schema, which only specifies it as a string. The description does not elaborate on its format or semantics, but the tool's purpose makes the meaning obvious. The baseline for low schema coverage is compensated by the tool's simplicity and the clear function.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with 'Permanently delete a node and its connections,' a clear verb (delete) and resource (node) with a specific scope (connections). This unambiguously differentiates it from all siblings, none of which perform deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence explicitly contrasts this tool with the preferred decay + review queue process, and states the condition for use: 'only for deliberate deletion.' This gives clear when-to-use and when-not-to-use guidance, and implies the alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

maintainA

Run the decay/archival pass: recompute activation, reassign tiers 1-4, and return the changes plus the tier-4 review queue (items awaiting human sign-off before deletion).

NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

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 disclose key aspects: it recomputes activation, reassigns tiers, and explicitly notes that items are placed in a review queue 'awaiting human sign-off before deletion', implying non-destructive immediate action. It does not mention potential side effects like performance impact or irreversibility, but for a zero-parameter trigger, it provides substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action and lists the specific steps and outputs. It is concise with no filler, and every clause adds necessary information: what the pass does, what it returns, and the key detail about human sign-off for deletion.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description must clarify what it returns. It states it returns 'the changes plus the tier-4 review queue', which is adequate, but it does not specify the format of the changes or queue items. However, for a zero-parameter operation with clear high-level behavior, this is reasonably complete. It could mention that the operation is safe to run repeatedly, but that is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the baseline is 4. The input schema is empty and schema coverage is 100% (no parameters to document). The description does not need to explain any parameters, and it does not introduce any confusion. A score of 4 is appropriate as the baseline for no-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Run the decay/archival pass') and explicitly lists the operations performed: recompute activation, reassign tiers, and return changes plus the review queue. This clearly distinguishes it from siblings like 'forget' (immediate deletion) and 'review_queue' (which likely only lists the queue without running the pass).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that this tool is used to trigger the archival pass, but provides no explicit guidance on when to call it (e.g., periodic maintenance) or how it compares to alternatives like 'forget' or 'review_queue'. It does not state when not to use it or mention specific exclusions. The purpose is clear, but the when-to-use context is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

neighborsC

List the direct connections of a node.

NameRequiredDescriptionDefault
node_idYes

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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 merely says 'List the direct connections' without clarifying read-only nature, ordering, depth semantics ('direct' is clear but not elaborated), or any side effects. It doesn't mention what the output looks like (though an output schema exists), so the behavior is under-described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, precise sentence with zero waste. The essential verb and resource are front-loaded. It is appropriately concise for such a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is simple (one parameter, no nested objects) and an output schema exists, the description is minimal but technically sufficient to convey the core action. However, it omits any behavioral context (e.g., whether 'direct' means depth-1, whether it returns node IDs or objects, any performance implications). A slightly richer description would improve completeness, so it's adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% — the description does not mention node_id at all. The parameter is named 'node_id' in the schema, which is self-explanatory to some degree, but the description adds no meaning about format, example, or accepted patterns. Since coverage is 0%, the description should compensate, but it does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('direct connections of a node'). It clearly distinguishes the purpose from siblings like 'connect' (creating connections) and 'stats' (aggregate data). However, it doesn't explicitly name an alternative, so it's clear but not maximally differentiating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It only says what it does, not why an agent might pick it over siblings like 'remember' or 'review_queue'. No context about prerequisites, limitations, or when it would be inappropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pinB

Pin (or unpin) a node so it is never auto-archived — a human 'principal' mark on durable knowledge.

NameRequiredDescriptionDefault
pinnedNo
node_idYes

TDQS

B3/5.0
Behavior3/5

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 disclose the key effect (the node is exempt from auto-archiving), which is the core behavior an agent needs. However, it does not clarify reversible behavior on unpin or any side effects, leaving a partially disclosed profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the core action front-loaded ('Pin (or unpin) a node'). No wasted verbiage; the 'durable knowledge' flourish is short and adds thematic context without excessive length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (2 params, 1 required, no output schema), so the bar is low. Still, the disconnect between the description and schema means an agent must infer which param targets the node and which toggles the state. There's no detail on whether unpinning immediately re-exposes the node to archiving. Barely adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

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 — but it never names node_id or explains the pinned boolean directly. The phrase 'or unpin' only implicitly hints at the pinned toggle, and the node_id target is assumed. The description fails to fill the parameter coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (pin/unpin) applied to a specific resource (node) and gives the outcome: never auto-archived. This distinguishes it from memory-oriented siblings like remember/reinforce since it concerns archive lifecycle, not recall strength. The 'human principal mark' clause adds flavor but doesn't obscure the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to pin versus using siblings like remember, forget, or maintain. There are no exclusions, prerequisites, or mention of when NOT to use the tool. The agent must infer context from the archive-prevention wording alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

recallA

Retrieve the k most relevant nodes for a query. Ranking blends text match with recency-weighted activation. Archived (cold/frozen) nodes are excluded unless include_cold=True. Each result explains why it surfaced.

NameRequiredDescriptionDefault
kNo
queryYes
include_coldNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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 transparently states that ranking blends text match with recency-weighted activation, that archived nodes are excluded by default, and that each result includes an explanation for why it surfaced. These are non-obvious behaviors that an agent needs to know. It does not mention edge cases like empty results or performance characteristics, but for a retrieval tool the disclosed behaviors are significant and adequately cover the essential operational aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loads the primary action, and every clause adds meaningful information: the ranking mechanism, the archive exclusion condition, and the explanation feature. There is no fluff or repetition of schema details. The structure efficiently communicates the tool's behavior without unnecessary length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 params, 1 required) and that an output schema exists, the description covers the essential aspects an agent needs: what the query is, how ranking works, the cold-node handling, and that results include explanations. It does not need to describe return structure since the output schema handles that. The description is complete for the task—there are no critical gaps that would prevent correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 undocumented parameters. It explicitly explains the meaning of 'k' (the number of nodes to retrieve), 'include_cold' (a flag to include archived nodes), and 'query' (the search input). This goes beyond the minimal schema definitions and adds value, particularly clarifying that k controls result count and include_cold toggles archive inclusion. The description effectively fills the gap left by the schema's lack of parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: 'Retrieve the k most relevant nodes for a query.' It immediately distinguishes the tool as a query-based retrieval mechanism, and the mention of ranking blend (text + recency) and exclusion of archived nodes sets it apart from siblings like 'neighbors' (graph traversal) or 'remember' (storage). The description clearly communicates a distinct purpose without relying on the tool name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides contextual usage details: it explains the archiving behavior and the include_cold flag, which tells the agent when to set include_cold=True. However, it does not explicitly compare this tool to alternatives (e.g., when to use 'neighbors' or 'review_queue' instead) nor state any exclusions or prerequisites. The usage context is implied through the retrieval scenario, but there is no explicit 'use this when X, otherwise use Y' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reinforceC

Strengthen and refresh an existing connection you just used again — the spaced-repetition signal that keeps knowledge from decaying.

NameRequiredDescriptionDefault
dstYes
relNoreferences
srcYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavior. It indicates a mutation ('strengthen and refresh') but does not specify what changes occur, whether it is reversible, or any side effects. It also uses metaphorical language that obscures the actual effect on the connection data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, making it concise and front-loaded with the action. However, the metaphorical phrasing ('keeps knowledge from decaying') adds unnecessary abstraction, and the sentence does not efficiently convey the operational details. It is adequately short but could be clearer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, lacks an output schema, and has no annotations, the description is severely incomplete. It does not explain what the parameters do, what the expected outcome is, or any prerequisites. An agent cannot determine how to invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 3 parameters (src, dst, rel) with zero description coverage. The description neither mentions these parameters nor explains their meaning or relationship. Without any compensation, the agent cannot infer how to populate src/dst/rel correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action ('strengthen and refresh an existing connection') and the resource (a connection). However, it does not explicitly differentiate from siblings like 'maintain' or 'connect', and the metaphor ('spaced-repetition signal') adds ambiguity. Still, it identifies the core purpose distinctly enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a context (when you have 'just used' a connection again) but provides no explicit guidance on when to choose this tool over siblings like 'connect' or 'maintain'. It lacks any mention of alternatives or exclusions, leaving the agent to infer usage from the vague context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rememberA

Store a piece of knowledge (note, decision, fact, person, client, ...). Returns its node id. Re-calling with the same node_id updates it. Set pinned=True for durable knowledge that should never be auto-archived.

NameRequiredDescriptionDefault
bodyNo
kindNonote
titleYes
pinnedNo
node_idNo

TDQS

A4.1/5.0
Behavior4/5

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 that re-calling with the same node_id updates the existing node, explains the return value (node id), and clarifies the effect of pinned=True (prevents auto-archiving). This covers update semantics and a durability guarantee, though it does not mention side effects like overwriting on duplicate titles or any destructive actions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero filler. The purpose is front-loaded, and each sentence adds distinct information (purpose+return, update behavior, pinning). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers core behavior but omits essential parameter details (what body and kind do, whether title must be unique) and does not explain interaction with sibling tools like pin. Since there is no output schema and no annotations, the description should have provided richer guidance for correct invocation, especially given the presence of a 'pin' tool that overlaps in functionality.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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. It adds meaning for node_id (used for updates) and pinned (durability control), but it gives no direct explanation for title, body, or kind. The examples (note, decision, fact) imply what title might hold, but they are not tied to parameters. This partial coverage is insufficient for a five-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pairing ('Store a piece of knowledge') and enumerates examples (note, decision, fact, person, client). It distinguishes itself from sibling tools like recall and forget by clearly stating its write/update behavior, and it mentions the return value (node_id).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool (storing knowledge) and a specific condition for setting pinned (durable knowledge that should never be auto-archived). However, it does not explicitly name alternative tools like pin or recall or state when NOT to use this tool, so it stops short of full exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

review_queueC

The tier-4 queue: knowledge that has decayed to the point of proposed deletion and is waiting for a human to confirm or reprieve it.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for disclosing behavioral traits such as whether the tool is read-only, has side effects, or requires specific permissions. The description only states the queue's content and purpose; it says nothing about what happens when the tool is called or whether any data is mutated. This is a significant gap for a tool that could plausibly modify state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, elegantly concise sentence that immediately identifies the queue's tier and its purpose. There is no filler or redundant wording, and the core concept is front-loaded. It is as efficient as possible.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters but an output schema, the description should at least indicate what the tool returns or what invoking it accomplishes. Instead, it only describes the queue's definition, leaving the operational purpose unclear. An agent would not know whether calling this tool returns the queue, allows actions on it, or something else. Given the simplicity of the tool, the description could easily have included a verb or explicit statement of behavior, so the omission makes it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema already fully covers any input requirements. The baseline for zero-parameter tools is 4, and the description does not need to add parameter-specific information. It appropriately omits any mention of parameters, which would be unnecessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the object—a tier-4 queue of decayed knowledge awaiting human review—but it does not state the tool's action. There is no verb like 'list' or 'get', so an agent cannot tell whether the tool returns the queue, updates it, or performs some other operation. This is more of a definition than a purpose statement, though it is specific enough to distinguish it from generic queues.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or conditions for invoking the tool, and it does not reference any sibling tools. An agent is left to infer that it might be used to inspect deletion candidates, but there is no explicit or implicit usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statsB

Graph size, tier distribution, and the most-active nodes right now.

NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility for behavioral disclosure. It does indicate that the data reflects the current state ('right now'), implying a real-time snapshot. However, it doesn't mention whether the operation is read-only or pure, any potential performance costs, or whether it reflects the entire graph or a subset. The description is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that is front-loaded with the core purpose (graph size, tier distribution, most-active nodes). Every word contributes to conveying what the tool does. It is appropriately brief for a stats tool with no parameters, though it could mention output format or examples to slightly improve clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description is the sole source of context. It specifies the three key statistics (size, tier distribution, most-active nodes) and the temporal aspect (right now). This is sufficient for an agent to understand what the tool returns, though it doesn't detail the exact format or structure of the output, which is acceptable for a simple stats endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the input schema covers everything (100% coverage). The description adds no parameter details because none exist. This is the baseline case where no additional semantic information is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it reports graph size, tier distribution, and the most-active nodes. This is specific and distinct from the sibling tools, which focus on operations like remembering, connecting, or recalling. It could be slightly more descriptive about what 'size' means (e.g., node count vs edge count), but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus siblings. It doesn't state that this is the go-to for overview statistics, or mention any prerequisites or ordering (e.g., run after adding nodes). An agent would have to infer from the name that it's for general stats, but no explicit context is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updatesv0.1.0
    • First observedconnect
    • First observedforget
    • First observedmaintain
    • First observedneighbors
    • First observedpin
    • First observedrecall
    • First observedreinforce
    • First observedremember
    • First observedreview_queue
    • First observedstats

TDQS

A3.5/5.0

Scored across 10 tools

Disambiguation5/5

Each tool serves a distinct operation: node creation/update, edge creation, edge reinforcement, query, neighbor listing, deletion, pinning, maintenance pass, review queue access, and statistics. No two tools overlap in purpose.

Naming Consistency4/5

All tool names are single lowercase words, with most being verbs (remember, connect, reinforce, recall, forget, pin, maintain) and a few nouns (neighbors, review_queue, stats). The style is consistent but mixes verb and noun forms, a minor deviation from a pure verb-noun pattern.

Tool Count5/5

With 10 tools, the server is well-scoped for a knowledge graph with memory decay and archival. Each tool earns its place, covering creation, linking, querying, deletion, and maintenance without unnecessary bloat.

Completeness4/5

The surface covers the full node lifecycle (remember/forget), edge operations (connect/reinforce), querying (recall/neighbors), and archival (pin/maintain/review_queue). Minor gaps exist—no explicit edge deletion and no direct node fetch by ID—but recall and forget adequately work around these.

Maintenance

ActivityStale
ResponsivenessNo recent community issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to manage and query a temporally-aware knowledge graph memory, supporting episode tracking, entity relationships, and semantic search via MCP tools.
    1
    -
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to have persistent, self-managing memory with bi-temporal supersession, timely forgetting, and recall under a limited context window, using MCP protocol.
    MIT