Tools / Memory

search_memory()

Key

Hybrid retrieval over everything stored: semantic (pgvector) + keyword (FTS) + entity and type filters, fused with reciprocal-rank fusion. An absolute relevance cutoff means no padding — if nothing relevant exists, the result is honestly empty.

search_memory(query, types, entity, as_of, limit)→ RANKED SUMMARIES + IDS

Callable over MCP as search_memory(query, types, entity, as_of, limit). REST mirror POST /v1/search Planned — alpha is MCP-only

Why your agent calls it

The workhorse read. Before forming any view, the agent searches what the workspace already knows — semantic and keyword retrieval fused, filtered by entity and type, optionally as-of a past moment. The absolute relevance cutoff matters: when nothing relevant exists, the agent learns that, instead of being handed confident padding.

What it returns

search_memory() · Hybrid retrieval with an honest empty result.ILLUSTRATIVE

Call it from an agent

Over MCP, your agent invokes it on its own when the moment calls for it — just describe the situation. A Python SDK for headless runtimes is planned; this is what the call will look like.

agent · python sdkSDK · PLANNED — ALPHA IS MCP-ONLY

from cascadian import Cascadian

cx = Cascadian(api_key=os.environ["CASCADIAN_API_KEY"])

result = cx.search_memory(
    query="discount tier win rate",
    types=["belief", "fact"],
    entity="discount_tier",
    as_of="2026-06-11T17:00:00Z",
    limit=10,
)

Parameters

Param	Type	Description
queryREQUIRED	string	Natural-language or keyword query.
types	string[]	Filter by memory type — fact, belief, lesson, …
entity	string	Restrict to one entity.
as_of	timestamp	Search only what was knowable at this moment.
limit	int	Max results. Default 10.

Example response

search_memory()JSON · ILLUSTRATIVE

{
  "query": "discount tier win rate",
  "results": [
    { "id": "mem_0871", "type": "belief", "score": 0.041,
      "summary": "discount pulls deals forward; net win-rate lift unclear" },
    { "id": "fct_2231", "type": "fact", "score": 0.033,
      "summary": "discount tier live since 2025-09" }
  ],
  "cutoff_applied": true,
  "note": "2 results above the relevance cutoff — no padding"
}

Related — Memory

keybootstrap()The ~200-token session card your agent reads first.keyingest_source()Store a raw source — chunked, embedded, indexed.keyassert_fact()Write a temporal fact with an honest available_at.keypropose_memory()Propose a memory item — contradiction-checked on write.keylink_memories()A typed relationship edge, with rationale.keysupersede_memory()Revise without erasing — new row, old row closed.keyget_facts()What was true, as of any moment.keyget_entity()The versioned dossier for one entity.keyget_memory()The full evidence card, by id.keyget_context_pack()Everything knowable for a decision, stamped and typed.keylist_contradictions()Open conflicts waiting on a human.