memstate_search
Search agent memories by semantic meaning to find relevant information before starting tasks when exact keypaths are unknown.
Instructions
Find memories by meaning (semantic search). Use BEFORE starting tasks when you don't know the exact keypath.
USE THIS WHEN: You want to find relevant memories by topic or meaning, not by exact keypath. NOT FOR: Saving content (use memstate_remember for markdown/summaries, memstate_set for one keypath value).
memstate_search(query="how is authentication configured", project_id="myapp") memstate_search(query="database connection settings", project_id="myapp")
Returns summaries with similarity scores. Use memstate_get(memory_id="...") to fetch full content of a result.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query. Leave empty to explore/list all memories ordered by keypath. | |
| project_id | No | Filter by project | |
| limit | No | Maximum results (default: 20, max: 100) | |
| categories | No | Filter by categories | |
| keypath_prefix | No | Filter by keypath prefix | |
| include_superseded | No | Include old versions |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- skill/scripts/memstate_search.py:11-48 (handler)The actual implementation of the semantic search tool, which performs a POST request to the Memstate API. It is designed to be executable as a script or via the MCP proxy.
def search_memories(query, project_id=None, limit=20): url = f"{BASE_URL}/memories/search" headers = { "X-API-Key": API_KEY, "Content-Type": "application/json", "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" } data = { "query": query, "limit": limit } if project_id: data["project_id"] = project_id req = urllib.request.Request(url, data=json.dumps(data).encode("utf-8"), headers=headers, method="POST") try: with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode("utf-8")) print(json.dumps(result, indent=2)) return 0 except urllib.error.HTTPError as e: print(f"Error: {e.code} - {e.read().decode('utf-8')}", file=sys.stderr) return 1 except Exception as e: print(f"Error: {e}", file=sys.stderr) return 1 if __name__ == "__main__": parser = argparse.ArgumentParser(description="Semantic search by meaning") parser.add_argument("--query", required=True, help="Natural language search query") parser.add_argument("--project", help="Filter by project ID") parser.add_argument("--limit", type=int, default=20, help="Maximum results (default: 20)") args = parser.parse_args() sys.exit(search_memories(args.query, args.project, args.limit)) - src/index.ts:139-144 (handler)In the proxy implementation, `memstate_search` (among other tools) is dynamically forwarded from the remote Memstate MCP server to the client.
server.setRequestHandler(CallToolRequestSchema, async (request) => { return await remote.callTool({ name: request.params.name, arguments: request.params.arguments, }); });