Skip to main content
Glama
Sign In
open-memex

open-memex

by stoneskin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

memory_useful

Mark a stored memory as confirmed useful to update cumulative usefulness counts and reuse rate; call only on explicit evidence it helped, never from passive exposure.

Instructions

Mark an existing memory as useful (D77): record that it demonstrably paid off. Call it ONLY on an explicit signal — the user confirmed it helped ('that was the one', 'saved me again'), or your completed/accepted work clearly relied on that memory and the user saw the result. NEVER call it because a memory appeared in memory_search results, a memory_list inventory, or the session-start block: passive exposure never refreshes usefulness. Exposure is counted automatically under retrieved_count; the useful buckets increment only through this tool, a human approval at review, or a supersede. Useful is split automatically: useful_self for personal memories and unpublished project drafts (the author's own utility), useful_team for approved/published project memories (team knowledge reused) — pass kind only to override. Returns the cumulative counts and reuse_rate (useful / retrieved). The counters live in the local SQLite index, not in the Markdown source of truth, and never leave this machine.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "memory_useful"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesID of the memory being confirmed useful (memory_search / memory_list return ids).
kindNoWhich useful counter. Default: auto — personal memories and unpublished project drafts count useful_self; approved/published project memories count useful_team. Pass only to override the auto split.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.9.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare this is not read-only and not destructive; the description goes far beyond by disclosing the auto-split of counters (useful_self vs useful_team), the exact return payload (cumulative counts and reuse_rate = useful/retrieved), and the storage location (local SQLite index, not the Markdown source of truth, never leaving the machine). It also warns that the effect is cumulative and irreversible-by-omission, which is material for a counter-mutation tool.

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?

Front-loaded with the action and its definition, then the trigger rule, then the anti-trigger warning, then side effects and return value — a sensible order. It is dense and long, but nearly every clause carries decision-relevant content; the only mild redundancy is restating the self/team split that the schema already spells out.

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?

There is no output schema, yet the description states what is returned (cumulative counts plus reuse_rate and its formula) and what the counters even mean. Combined with the trigger rules and storage caveats, an agent has everything needed to decide whether and how to call this among twelve siblings.

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 100%, so both parameters are already documented and the baseline is 3. The description reinforces the override semantics of 'kind' ('pass kind only to override') and frames the auto-split as the default behavior, which clarifies intent slightly beyond the field text, but it largely restates the schema rather than adding new parameter meaning.

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 names a specific verb and resource ('Mark an existing memory as useful') and immediately qualifies it ('record that it demonstrably paid off'), which pins down the semantics of a word ('useful') that would otherwise be ambiguous. It also distinguishes itself concretely from siblings by naming memory_search and memory_list as things that do NOT constitute a trigger.

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?

Explicit when-to-call criteria are given with quoted user signals ('that was the one', 'saved me again') plus the inferential case of completed/accepted work that relied on the memory. Explicit when-NOT-to-call is provided (passive exposure via search results, list inventory, session-start block), and the alternative mechanisms that also increment the counters (automatic retrieved_count, human approval at review, supersede) are named, so the agent can route correctly.

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

Deploy Server

Other Tools