bettermemory

Overview Schema Source Related Servers Discussions Admin

memory_scope_overview

View per-scope memory counts at session start to know if any stored facts exist. If none, skip memory search until explicitly asked; pending reviews and stale memories are shown for action.

Instructions

Cheap session-start hint: per-scope counts, no bodies / ids / summaries. Call once at the start of a conversation; if total is 0, skip memory_search for the rest of the session unless explicitly asked.

proposals_pending is the count of write-reflex proposals the Stop hook has captured awaiting review via memory_proposals (0 unless the opt-in [proposals] auto_propose is on). pending_writes is this session's staged writes awaiting memory_write_confirm/cancel — a dangling confirmation (silent 1h expiry). curation_pending is an integer-count rollup the model should branch on; the response names its legs. conflicts = contradiction pairs awaiting a memory_conflicts verdict. unaccounted = memories that entered outside every recorded path. curation_unmeasured names legs whose 0 is not a measurement (git or the index did not answer); never read a listed leg's 0 as clean. Non-zero dead or drifted is a cue to suggest a curation pass when there is time; non-zero silent_misses / cold_endorsement_memories is actionable audit backlog. A memory retrieved many times with zero explicit applies is weakly endorsed — worth a look, not a verdict.

Non-zero recently_removed_in_worktree is a 'where did X go?' signal — material was deliberately trimmed here recently; don't blindly re-suggest it.

curation_pending_new_since_last_session is the same shape, filtered to events emitted and memories created since the previous session ended (not memories that aged into a bucket; an older record aging into stale between sessions stays visible only in the absolute curation_pending view — note this is distinct from the separate drifted bucket, which tracks working-tree drift). Branch on it when deciding whether to prompt about curation — non-zero means new rot since the last session, vs. the absolute view which persists until resolved. null on the very first session — fall back to curation_pending.

Default-scoped to the caller's current repository; memories with no origin always pass as global. Set auto_scope=False for the cross-project view. Counts respect session-disabled scopes.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`auto_scope`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv3.34.0Aug 1, 2026

TDQS

A4.5/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 an excellent job: it explains that counts respect session-disabled scopes, that null appears on the first session, that dangling confirmations have a silent 1h expiry, and that certain zero values are not measurements. It also warns against blindly re-suggesting recently removed material. The only minor gap is that it doesn't describe the exact response shape beyond naming fields, but the output schema exists and the description covers the semantics of each field thoroughly.

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 dense and information-rich, but it is quite long and somewhat sprawling. The first sentence is a strong front-loaded summary, but the middle paragraphs read like a field-by-field reference manual. Every sentence earns its place in terms of content, but the structure could be tightened with bullet points or clearer separation between 'what the fields mean' and 'how to act on them.' It is not concise, but it is structured enough to be navigable.

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 complexity — many named fields, subtle semantics, session-scoping behavior, and a branching decision for the model — the description is remarkably complete. It covers the return fields' meanings, the null case, the expiry behavior, the measurement caveats, and the action cues. The output schema exists, so the description doesn't need to explain return structure. An agent has everything it needs to call this tool correctly and interpret its results.

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 the single parameter auto_scope. It does: 'Default-scoped to the caller's current repository; memories with no origin always pass as global. Set auto_scope=False for the cross-project view.' This adds real meaning beyond the bare boolean schema. It doesn't explain the exact default behavior of auto_scope=True in exhaustive detail, but it gives enough for an agent to use it correctly.

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: 'Cheap session-start hint: per-scope counts, no bodies / ids / summaries.' It immediately distinguishes itself from sibling tools like memory_search and memory_list by stating it returns counts only, not content. The name memory_scope_overview is reinforced by the description's focus on per-scope counts and session-start usage.

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 description explicitly says 'Call once at the start of a conversation' and gives a concrete conditional: 'if total is 0, skip memory_search for the rest of the session unless explicitly asked.' It also explains when to use auto_scope=False for the cross-project view and how to branch on curation_pending_new_since_last_session. This is strong when-to-use guidance with clear alternatives.

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

Deploy Server