{"uid":"cap_wsfxxFo9utcWWfPe9mLiv","slug":"memory-withzero-xyz-recall-memories-matching-a-query-242a8bfe","name":"Recall Memories Matching a Query","description":"Recall memories matching a query (free).","url":"https://memory.withzero.xyz/api/v1/contexts","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["query"],"properties":{"ns":{"type":"string","maxLength":128,"minLength":1,"description":"Restrict recall to this namespace. Omit to search all of the caller's memories."},"limit":{"type":"integer","maximum":100,"minimum":1,"description":"Max memories to return (default 10)."},"query":{"type":"string","maxLength":4096,"minLength":1,"description":"Natural-language query to recall against."}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["memories"],"properties":{"memories":{"type":"array","items":{"type":"object","required":["id","ns","key","content","distance","pinned","is_summary"],"properties":{"id":{"type":"string"},"ns":{"type":"string"},"key":{"type":"string"},"pinned":{"type":"boolean","description":"A \"standing order\" — always surfaced ahead of distance-ranked rows, exempt from dreaming."},"content":{"type":"string"},"distance":{"type":"number","description":"Cosine distance (0 = identical, smaller = more relevant)."},"is_summary":{"type":"boolean","description":"True if this row is a dreaming summary node. Pass its `id` to POST /api/v1/contexts/expand to read back the original memories it consolidated."}},"additionalProperties":false}}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.50","reviews":0,"stars":null,"state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"metered","summary":"metered — billed by usage","primary":{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_HuRBAYvthj0RnL6hFSYPf","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0","costPer":"request","priority":0,"asset":"0x20C000000000000000000000b9537d11c60E8b50","unit":"request","depositMicros":null,"planRef":"memory.recall:1"}],"brandName":"memory.withzero.xyz","brandSlug":"memory-withzero-xyz-mpp","brandBaseUrl":"https://memory.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Performs a semantic similarity search over durable agent memories and returns the most relevant stored facts or context entries for a given natural-language query.","exampleAgentPrompt":"Search my durable agent memory for anything relevant to 'project deadlines and client deliverables' and return the top 5 most similar memories.","exampleUseCases":[{"title":"Retrieve customer context before support call","prompt":"Before I take this customer call, search my agent memory for anything relevant to their account history and previous issues they've mentioned."},{"title":"Find relevant product info from past research","prompt":"I'm writing a comparison document—search my memories for anything about competitor pricing strategies and market positioning we've discussed before."},{"title":"Look up prior conversation topics with user","prompt":"The user is asking about their fitness goals again. Search my memory for what they've told me before about their exercise habits and health concerns."}],"resultDescription":"An array of memory objects ranked by cosine distance (smaller = more relevant), each containing the memory ID, namespace, key, content text, distance score, a pinned flag (always surfaced ahead of distance-ranked results), and an is_summary flag (if true, the memory is a dreaming-consolidated summary that can be expanded via the /expand endpoint).","failureModes":["query string missing or empty — returns 400 validation error","query exceeds 4096 character limit — returns 400 validation error","namespace specified does not exist or has no memories — returns empty memories array","limit out of range (less than 1 or greater than 100) — returns 400 validation error","caller has no stored memories — returns empty memories array","authentication failure — returns 401 unauthorized"],"whenToPreferThis":"Use this endpoint when an AI agent needs to retrieve previously stored facts, context, or notes that are semantically relevant to the current task or user query. It is free to call, making it ideal for frequent lookups during reasoning loops. Prefer this over a full memory dump when you want ranked, relevant results rather than all stored data. If a returned memory has is_summary=true, follow up with the /expand endpoint to retrieve the underlying consolidated memories.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":5,"lastUsedAt":"2026-07-29T00:21:25.435Z","lastSuccessfullyRanAt":"2026-07-18T00:21:17.600Z","lastHealthCheckAt":"2026-09-14T00:36:53.588Z","isFirstParty":true}