fleet-memory/hindsight-docs/docs/api-reference/mcp.md

sidebar_position
3

MCP API

Model Context Protocol (MCP) tools exposed by the Hindsight MCP server.

Available Tools

hindsight_search

Search memories for an agent.

Parameters:

Parameter	Type	Required	Description
query	string	yes	Search query
agent_id	string	no	Agent ID (uses default if not specified)
top_k	integer	no	Number of results (default: 10)

Example:

{
  "name": "hindsight_search",
  "arguments": {
    "query": "What does Alice do for work?",
    "top_k": 5
  }
}

Response:

{
  "results": [
    {
      "text": "Alice works at Google as a software engineer",
      "weight": 0.95,
      "fact_type": "world"
    }
  ]
}

---

hindsight_think

Generate a personality-aware response using retrieved memories.

Parameters:

Parameter	Type	Required	Description
query	string	yes	Question or prompt
agent_id	string	no	Agent ID (uses default if not specified)
thinking_budget	integer	no	Tokens for reasoning (default: 100)

Example:

{
  "name": "hindsight_think",
  "arguments": {
    "query": "What should I recommend to Alice?"
  }
}

Response:

{
  "text": "Based on Alice's interest in machine learning and her work at Google, I would recommend...",
  "based_on": [
    {"text": "Alice works at Google", "weight": 0.95}
  ],
  "new_opinions": []
}

---

hindsight_store

Store a new memory.

Parameters:

Parameter	Type	Required	Description
content	string	yes	Memory content to store
agent_id	string	no	Agent ID (uses default if not specified)
context	string	no	Context or topic of the memory

Example:

{
  "name": "hindsight_store",
  "arguments": {
    "content": "User prefers Python for data analysis",
    "context": "programming discussion"
  }
}

Response:

{
  "success": true,
  "message": "Memory stored successfully"
}

---

hindsight_agents

List all available agents.

Parameters: None

Example:

{
  "name": "hindsight_agents",
  "arguments": {}
}

Response:

{
  "agents": [
    {"agent_id": "default"},
    {"agent_id": "assistant"},
    {"agent_id": "researcher"}
  ]
}

---

Environment Variables

Variable	Description	Default
HINDSIGHT_API_URL	Hindsight API URL	http://localhost:8888
HINDSIGHT_AGENT_ID	Default agent ID	Required

Error Responses

MCP tools return errors in the standard MCP error format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent 'unknown-agent' not found"
  }
}

Code	Description
INVALID_PARAMS	Missing or invalid parameters
NOT_FOUND	Agent or resource not found
INTERNAL_ERROR	Server error