Skip to main content
Glama

Ebb — エージェントファーストのナレッジグラフ

AIエージェントのための長期記憶を、グラフとして構築。関連性は最近性で重み付けされた接続強度です。知識を再利用すると生き続け、未使用の知識は減衰してアーカイブされ、人間が承認するまで何も削除されません。組み込み(インフラ不要)またはNeo4j(本番)で動作します。

このシステムを支える2つのメカニズム(接続重み付け関連性と時間減衰)は、ネイティブなグラフ操作であり、どちらも深い先行研究があります(PageRank/中心性、認知科学からのACT-Rベースレベル活性化と拡散活性化、間隔反復忘却曲線)。これは、その系譜をエージェントメモリに特化して実装した、小さく誠実な実装です。


このように構築された理由

1. エンジンとインターフェースは分離されています。 グラフストアは小さなインターフェース(GraphStore)の背後にあります。エージェントとスコアリングロジックは特定のデータベースに触れることはないため、今日は組み込みエンジンでまったく同じグラフを実行し、後で1つの環境変数でNeo4jに切り替えることができます。

2. 関連性は最近性で重み付けされており、生の接続数ではありません。 「接続が多いほど関連性が高い」という考え方は、古くて頻繁に参照されるデータを永遠に優遇します。これは、このシステムが排除しようとしているまさに陳腐化データ問題です。ここでは、各エッジの関連性への寄与は、接続が最後に強化された時期に基づく時間減衰係数で乗算されます。昨日強化されたエッジはほぼ全額カウントされ、6か月前に最後に触れたエッジはほぼゼロにカウントされます。接続を再利用する(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)

置き換えられたシート単位の決定は、グラフ内で最も高い生の接続数を持ちながらも、3分の1のリンクしか持たない新しい決定に次いで3位にランクされています。生の数は負け、最近性が勝ちました。


Related MCP server: Memory Engine MCP

含まれるもの

  • グラフモデル — すべてのメモ、決定、会議、人物、クライアント、事実はノードであり、すべての参照はタイムスタンプ付き、型付き、重み付きのエッジです。

  • スコアリングエンジン(scoring.py)— 最近性重み付け活性化、指数減衰(設定可能な半減期)、拡散活性化の1ホップ(PageRankのポータブルな代替)、およびティア割り当て。純粋関数で、完全にユニットテスト済みです。

  • 4つのアーカイブティア — 1 ホット(デフォルトのリコール)・2 ウォーム(より深いリコール)・3 コールド(アーカイブ済み、オンデマンドのみ)・4 フローズン(削除前に人間の承認待ち)。ピン留めされたノードは自動アーカイブされません。

  • MCPサーバー(mcp_server.py)— エージェントインターフェース:remember、recall、connect、reinforce、forget、neighbors、pin、maintain、review_queue、stats。

  • 2つのバックエンド — 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、さらに隣接ノードからの同じ減衰ホップを1回加えます。減衰は半減期(デフォルト30日、調整可能)です。ティアは、最もアクティブな非ピン留めノードに対して正規化された活性化に基づいてカットされます。recallはこの活性化をクエリのテキストマッチとブレンドし、各結果が浮上した理由を返します。すべては1か所で調整可能です — 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 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