Skip to main content
Glama

ctxstore — memory that follows you across models

Search Facts

search_facts
Read-onlyIdempotent

Search your persistent memory for stored facts.

For session bootstrap, prefer load_context() or wake_status() — they pull your identity, conventions, and latest self-note deterministically. Use search_facts when you need semantic discovery across the fact corpus.

Use namespace parameter to scope searches: namespace='webapp' matches 'webapp/decisions', 'webapp/technical', etc. (prefix matching).

Search tips: use the words the fact was stored with. If you stored 'Postgres database', search for 'database' or 'Postgres', not 'data storage solution'.

Each search embeds the query on a shared embedder: at most 4 searches (search_facts, search_context) per account run at once; past that a call waits up to 2 s, then answers {"code": "busy", "retry_after_s": 2}. Fan out with 2-4 readers, not 16.

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": {
      "query": "<query>"
    },
    "name": "search_facts"
  }
}

Input Schema

NameRequiredDescriptionDefault
layerNoContext persistence layer: 0=identity, 1=architecture, 2=state, 3=session.
queryYesWhat to search for
top_kNoNumber of results
categoryNoFilter by category
namespaceNoFilter results to a specific namespace.
recollectNoWhen true (default), appends a RECOLLECTIONS section: facts cross-referenced from the top hits via related_facts and [[wiki]] links, ranked by association strength times outcome-weighted usefulness (reward/salience). Set false for plain semantic results only.
boost_recentNoWhen true (default), appends the 5 most recent facts for recency signal. Set false to get pure semantic results without recent-fact injection.
include_grantedNoWhen true (default), hits from workspaces shared with this account (active grants, under their granted prefixes) follow the own results, each tagged |from:<grantor>'s workspace: <prefix>. Set false to search this account only. A blind session (bind_agent blind=true) defaults to false; pass true to include granted hits there. Ignored inside a workspace session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / include_granted / description
      Previous value: -"When true (default), hits from workspaces shared with this account (active grants, under their granted prefixes) follow the own results, each tagged |from:<grantor>'s workspace: <prefix>. Set false to search this account only. Ignored inside a workspace session."New value: +"When true (default), hits from workspaces shared with this account (active grants, under their granted prefixes) follow the own results, each tagged |from:<grantor>'s workspace: <prefix>. Set false to search this account only. A blind session (bind_agent blind=true) defaults to false; pass true to include granted hits there. Ignored inside a workspace session."
  2. Changed1 schema field changed
    • addedInput schema / properties / include_granted
      Added value: +{
      +  "default": true,
      +  "description": "When true (default), hits from workspaces shared with this account (active grants, under their granted prefixes) follow the own results, each tagged |from:<grantor>'s workspace: <prefix>. Set false to search this account only. Ignored inside a workspace session.",
      +  "type": "boolean"
      +}
  3. Changed4 schema fields changed
    • changedInput schema / properties / layer / description
      Previous value: -"Context persistence layer: 0=identity, 1=architecture, 2=state, 3=session. Pass 0-3 as integer or string."New value: +"Context persistence layer: 0=identity, 1=architecture, 2=state, 3=session."
    • addedInput schema / properties / layer / maximum
      Added value: +3
    • addedInput schema / properties / layer / minimum
      Added value: +0
    • changedInput schema / properties / layer / type
      Previous value: -[
      -  "integer",
      -  "string"
      -]New value: +"integer"
  4. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes further with a real operational constraint: at most 4 concurrent embedder calls, after which a call waits up to 2s and returns a concrete {code: 'busy', retry_after_s: 2} payload. That error shape and throttling behavior are not derivable from annotations or schema. It does not, however, describe result ordering or result-shape details for the base (non-augmented) hits.

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 purpose, then broken into clearly separated paragraphs for routing, namespace semantics, query tips, and concurrency. Slightly dense for one tool description and mixes caller-side orchestration advice with tool semantics, but each sentence carries actionable information with no filler.

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?

With 8 parameters and no output schema, the description carries the return-value burden and does so: it explains the appended RECOLLECTIONS section, the 5-fact recency injection, and the |from:<grantor> tagging on granted-workspace hits. Combined with the busy-error contract, an agent has everything needed to call and interpret results correctly.

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 coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond it: namespace filtering is prefix-based ('webapp' matches 'webapp/decisions'), which is not stated in the schema's one-line param text. It also implicitly clarifies that query should use stored vocabulary. Other parameters (layer, top_k, category, recollect, boost_recent, include_granted) are left to the schema's own thorough 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?

Opens with a specific verb and resource ('Search your persistent memory for stored facts') and immediately differentiates itself from the bootstrap siblings load_context() and wake_status(). The scope ('semantic discovery across the fact corpus') tells an agent exactly what class of retrieval this is.

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?

Explicitly states when NOT to use it (session bootstrap → load_context/wake_status) and when to use it (semantic discovery across the corpus), naming the alternatives. Adds operational guidance on fan-out ('2-4 readers, not 16') and a concrete query-phrasing heuristic for better recall.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.