Skip to main content
Glama
cirwel

UNITARES

by cirwel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

search_shared_memory

Search the cross-agent knowledge graph before writing to find prior findings, then store new ones with store_finding.

Instructions

Search shared memory (the knowledge graph) before you write; to add a finding use store_finding.

Searches the cross-agent knowledge graph. Archived and cold rows appear only when you set status or include_archived / include_cold, or when a query finds under 3 other rows; resolved and closed ones always do. Each successful search appends a knowledge_read audit row (the reader and a redacted copy of the query), so this tool is not annotated read-only. It serves unbound callers, so it works before start_session, unlike the writes: use store_finding to add a finding and use_tool(tool_name='update_finding', ...) to revise one.

Input Schema

NameRequiredDescriptionDefault
tagsNoExact any-of tag filter.
limitNoMax results, 1-100 (more is capped).
queryNoSearch text.
statusNoFilter by status: open, resolved, archived, superseded.
sort_byNosearch order: relevance, or created_at (newest matches first).
agent_idNoFilter by author agent; agent_id_filter wins if both are set.
operatorNoBoolean operator for multi-term FTS queries
semanticNoLegacy semantic on/off toggle.
severityNoFilter by severity: low, medium, high, critical.
search_modeNoauto, or force fts/semantic/hybrid.
include_coldNoInclude cold-storage rows.
created_afterNosearch: created after ISO time.
response_modeNoRead-envelope mode. Default lean: one-line digests; compact adds diagnostics, full adds raw_governance.lean
authority_modeNoprefer_governed (default) down-ranks imported memory and omits it from queryless listings; all keeps raw order.
created_beforeNosearch: created before this ISO time.
discovery_typeNoFilter by discovery type, e.g. bug_found.
min_similarityNoSemantic similarity floor.
agent_id_filterNoAuthor agent UUID filter; wins over agent_id.
include_detailsNoInline details need response_mode='full'; else open one via use_tool(tool_name='knowledge', arguments={'action': 'details', ...}).
continuity_tokenNoSame-process rebind proof only; never a cross-process resume.
include_archivedNoInclude archived rows.
client_session_idNoBinding id for calls in this process; not a cross-process proof.
include_provenanceNoAdd provenance fields.
exclude_agent_labelsNoOmit search results whose writer display label matches one of these values
recency_half_life_daysNosearch: score halves per N days.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv3.4.0
    • changedInput schema / properties / authority_mode / description
      Previous value: -"prefer_governed (default) down-ranks imported memory; all keeps raw order."New value: +"prefer_governed (default) down-ranks imported memory and omits it from queryless listings; all keeps raw order."
    • changedInput schema / properties / include_details / description
      Previous value: -"Inline details need response_mode='full'; else open one with knowledge(action='details')."New value: +"Inline details need response_mode='full'; else open one via use_tool(tool_name='knowledge', arguments={'action': 'details', ...})."
  2. Changed3 schema fields changedv3.2.0
    • changedInput schema / properties / agent_id / description
      Previous value: -"Filter by agent (for action=get, search; omit when using discovery_id readback)"New value: +"Filter by author agent; agent_id_filter wins if both are set."
    • changedInput schema / properties / query / description
      Previous value: -"Search query (for action=search)"New value: +"Search text."
    • changedInput schema / properties / status / description
      Previous value: -"Status filter/update value (open, resolved, archived, superseded)"New value: +"Filter by status: open, resolved, archived, superseded."
  3. Changed37 schema fields changedv3.1.0
    • changedInput schema / description
      Previous value: -"Parameters for knowledge"New value: +"Knowledge graph parameters."
    • addedInput schema / properties / agent_id_filter
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Author agent UUID filter; wins over agent_id."
+}
    • addedInput schema / properties / authority_mode
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "prefer_governed",
+        "all"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "prefer_governed (default) down-ranks imported memory; all keeps raw order."
+}
    • changedInput schema / properties / client_session_id / description
      Previous value: -"In-session binding id from start_session()/identity(); pass it on same-process calls. Not a cross-process proof."New value: +"Binding id for calls in this process; not a cross-process proof."
    • removedInput schema / properties / closure_class
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Closing standard for action=update: fix_verified | unobserved | not_reproducible | obsolete | duplicate. 'fix_verified' needs a deployed change whose effect was observed."
-}
    • removedInput schema / properties / closure_evidence
      Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Evidence for closure_class. Required keys: fix_verified needs {deployed, observed}; unobserved needs {window, instrument_check}."
-}
    • removedInput schema / properties / confidence
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "number"
-    },
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Writer-supplied confidence for action=store, validated to 0-1; not independently verified or adjusted by governance metrics"
-}
    • changedInput schema / properties / continuity_token / description
      Previous value: -"Ownership proof from onboard()/identity(), for same-live-process rebinds only. Not a cross-process resume credential."New value: +"Same-process rebind proof only; never a cross-process resume."
    • addedInput schema / properties / created_after
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "search: created after ISO time."
+}
    • addedInput schema / properties / created_before
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "search: created before this ISO time."
+}
    • changedInput schema / properties / discovery_type / description
      Previous value: -"action=store; one of architectural_decision, learning, pattern, bug_fix, refactoring, documentation, experiment, question, note, rule, insight, bug_found, bug, improvement, exploration, observation."New value: +"Filter by discovery type, e.g. bug_found."
    • removedInput schema / properties / dry_run
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "boolean"
-    },
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Dry run mode (for action=cleanup, synthesize)"
-}
    • removedInput schema / properties / epoch_scope
      Removed value: -{
-  "anyOf": [
-    {
-      "enum": [
-        "current",
-        "all"
-      ],
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Stats/list scope: current epoch only or all epochs"
-}
    • changedInput schema / properties / include_archived / description
      Previous value: -"Include archived discoveries in search results (default: excluded)"New value: +"Include archived rows."
    • changedInput schema / properties / include_cold / description
      Previous value: -"Include cold-storage (long-term) discoveries in search results (default: excluded)"New value: +"Include cold-storage rows."
    • changedInput schema / properties / include_details / description
      Previous value: -"Expand results inline only with response_mode='full'; otherwise open one with knowledge(action='details')."New value: +"Inline details need response_mode='full'; else open one with knowledge(action='details')."
    • changedInput schema / properties / include_provenance / description
      Previous value: -"Include provenance and lineage chain fields in search/details results"New value: +"Add provenance fields."
    • removedInput schema / properties / include_response_chain
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "boolean"
-    },
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Include typed response chain for action=details"
-}
    • removedInput schema / properties / including_cold
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "boolean"
-    },
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Include cold-storage discoveries in action=list raw status aggregates"
-}
    • removedInput schema / properties / length
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "integer"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Maximum details characters returned for action=details"
-}
    • changedInput schema / properties / limit / description
      Previous value: -"Max results (for action=search: min 1, values above 100 are capped, 0 or negative is rejected)"New value: +"Max results, 1-100 (more is capped)."
    • removedInput schema / properties / max_chain_depth
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "integer"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Maximum response-chain traversal depth for action=details"
-}
    • removedInput schema / properties / memory_context
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "S22 provenance: memory/KG/transcript surfaces visible to the writer"
-}
    • removedInput schema / properties / min_members
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "integer"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Minimum discoveries a topic needs before it is rolled up (for action=synthesize, default 3)"
-}
    • changedInput schema / properties / min_similarity / description
      Previous value: -"Minimum cosine similarity for semantic retrieval modes"New value: +"Semantic similarity floor."
    • removedInput schema / properties / offset
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "integer"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Character offset for action=details pagination"
-}
    • addedInput schema / properties / recency_half_life_days
      Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "maximum": 36500,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "search: score halves per N days."
+}
    • removedInput schema / properties / scope
      Removed value: -{
-  "anyOf": [
-    {
-      "enum": [
-        "open",
-        "all",
-        "by_agent"
-      ],
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "KG audit scope for action=audit"
-}
    • changedInput schema / properties / search_mode / description
      Previous value: -"Force retrieval mode for action=search. 'semantic' and 'hybrid' fail honestly when unsupported by the active backend."New value: +"auto, or force fts/semantic/hybrid."
    • changedInput schema / properties / semantic / description
      Previous value: -"Legacy action=search toggle to force or skip semantic retrieval when supported"New value: +"Legacy semantic on/off toggle."
    • changedInput schema / properties / severity / description
      Previous value: -"Severity: low, medium, high, critical (for action=store or action=update)"New value: +"Filter by severity: low, medium, high, critical."
    • addedInput schema / properties / sort_by
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "relevance",
+        "created_at"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "search order: relevance, or created_at (newest matches first)."
+}
    • changedInput schema / properties / tags / description
      Previous value: -"Tags (action=store, note); for action=search an exact any-of filter in every search mode."New value: +"Exact any-of tag filter."
    • removedInput schema / properties / top_n
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "integer"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Maximum stale entries returned by action=audit"
-}
    • removedInput schema / properties / topic
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Synthesize just this one tag/topic (for action=synthesize). Omit to sweep the densest topics."
-}
    • removedInput schema / properties / use_llm
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "boolean"
-    },
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Use the local LLM for the rollup narrative (for action=synthesize, default true; falls back to deterministic when unreachable)"
-}
    • removedInput schema / properties / use_model
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "boolean"
-    },
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Use the local model to assess stale entries for action=audit"
-}
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

It discloses the non-obvious side effect that each search appends a knowledge_read audit row with a redacted query copy, and explains why readOnlyHint is false even though the operation reads. It also spells out the visibility rules for archived, cold, resolved and closed rows, including the under-3-results fallback, which annotations cannot express.

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?

Purpose and the sibling pointer come first, then the visibility and audit caveats in three dense sentences with no filler. Every clause carries information an agent would otherwise discover only by trial.

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?

For a 25-parameter, no-output-schema tool it covers the high-risk surprises: audit side effects, unbound-caller support, visibility of archived/cold rows, and where to go for single-record details. The gaps are minor, such as the interaction between limit and the small-result fallback or the default search_mode behavior, which the schema only partially explains.

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 semantics beyond the schema for include_archived, include_cold and status: archived and cold rows surface only when requested or when a query returns fewer than 3 other rows, while resolved and closed always appear. Those filtering knobs are only some of the 25 parameters, so it is not a full 5.

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 shared memory (the knowledge graph)') and immediately names the sibling tool that handles the write path, so an agent can separate this from store_finding without inspecting either schema.

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?

It states the trigger ('before you write'), names the alternatives for adjacent actions (store_finding to add, use_tool/update_finding to revise), and adds a call-order rule: it works before start_session unlike the write tools. That is explicit when, when-not, and what-to-use-instead.

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