Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt

Use this file to discover all available pages before exploring further.

The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools exposed by external servers. Hindsight includes a built-in MCP server, so any MCP-compatible client — Claude Code, Claude Desktop, Cursor, or your own tooling — can store and retrieve memories without writing integration code.

​
Endpoint

The MCP server is enabled by default and mounted at /mcp on the Hindsight API server. Each memory bank has its own scoped endpoint: 
http://localhost:8888/mcp/{bank_id}/
For example, to connect to the bank alice: 
http://localhost:8888/mcp/alice/
To disable the MCP server entirely, set the environment variable before starting the API: 
export HINDSIGHT_API_MCP_ENABLED=false

​
Single-bank vs. multi-bank mode

The MCP server operates in two modes depending on the URL you connect to:
ModeURLbank_id
Single-bank (recommended)/mcp/{bank_id}/Implicit from URL — tools don’t expose a bank_id parameter
Multi-bank/mcp/Explicit parameter on each tool call — also exposes list_banks, create_bank, get_bank_stats
Single-bank mode is recommended for most use cases. It scopes all tool calls to the bank in the URL, which simplifies tool usage and enforces isolation per connection.

​
Bank selection priority

When using the base /mcp/ endpoint, the bank is resolved in this order:
  1. URL path — http://localhost:8888/mcp/my-bank/
  2. X-Bank-Id header — --header "X-Bank-Id: my-bank"
  3. Default — the value of HINDSIGHT_MCP_BANK_ID (defaults to "default")

​
Authentication

By default, the MCP endpoint requires no authentication. To enable API key authentication: 
export HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
export HINDSIGHT_API_TENANT_API_KEY=your-secret-key
When authentication is enabled, requests without a valid key receive a 401 Unauthorized response.

​
Connecting Claude Code

1

Without authentication

claude mcp add --transport http hindsight http://localhost:8888/mcp
2

With authentication and a specific bank

claude mcp add --transport http hindsight http://localhost:8888/mcp \
  --header "Authorization: Bearer your-secret-key" \
  --header "X-Bank-Id: my-bank"

​
Connecting Claude Desktop

Add the following to ~/.claude_desktop_config.json: 
{
  "mcpServers": {
    "hindsight": {
      "url": "http://localhost:8888/mcp/my-bank/"
    }
  }
}

​
Connecting Cursor

In Cursor’s MCP settings, add a new HTTP server entry pointing to the bank-specific URL: 
http://localhost:8888/mcp/my-bank/
If authentication is enabled, add the Authorization header in Cursor’s header configuration.

​
Testing with a raw HTTP request

curl -X POST http://localhost:8888/mcp \
  -H "Authorization: Bearer your-secret-key" \
  -H "X-Bank-Id: my-bank" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

​
Available tools

Single-bank mode exposes 26 tools covering memory, mental models, directives, documents, operations, tags, and bank management. The three core tools are:

​
retain

Store information to long-term memory. Hindsight extracts facts, entities, and relationships from the content automatically.
ParameterTypeRequiredDescription
contentstringYesThe fact or memory to store
contextstringNoCategory label (default: general)
timestampstringNoISO 8601 timestamp for when the event occurred
tagslist[string]NoTags for organizing and filtering this memory
metadataobjectNoKey-value metadata (e.g., {"source": "slack"})
document_idstringNoAssociate this memory with an existing document
{
  "name": "retain",
  "arguments": {
    "content": "User prefers Python over JavaScript for backend development",
    "context": "programming_preferences",
    "tags": ["user:alice", "preferences"]
  }
}

​
recall

Search memories to provide personalized, context-aware responses.
ParameterTypeRequiredDescription
querystringYesNatural language search query
max_tokensintegerNoMaximum tokens to return (default: 4096)
budgetstringNoSearch thoroughness: low, mid, or high (default: high)
typeslist[string]NoFilter by fact type: world, experience, opinion
tagslist[string]NoFilter memories by tags
query_timestampstringNoRecall as if asking at this point in time
{
  "name": "recall",
  "arguments": {
    "query": "What are the user's programming language preferences?",
    "tags": ["preferences"],
    "budget": "high"
  }
}

​
reflect

Generate thoughtful analysis by synthesizing stored memories with the bank’s personality and mission.
ParameterTypeRequiredDescription
querystringYesThe question or topic to reflect on
contextstringNoAdditional context about why this reflection is needed
budgetstringNoSearch budget: low, mid, or high (default: low)
max_tokensintegerNoMaximum tokens in the response (default: 4096)
response_schemaobjectNoJSON Schema for structured output
tagslist[string]NoFilter memories by tags before reflecting
{
  "name": "reflect",
  "arguments": {
    "query": "Based on my past decisions, what architectural style do I prefer?",
    "budget": "mid",
    "tags": ["architecture"]
  }
}
Use recall when you need raw facts (“What did Alice say about deadlines?”). Use reflect when you need reasoned analysis (“What should Alice prioritize this sprint?”).

​
Multi-user setups

Each user can connect to their own memory bank using a bank-specific URL path or the X-Bank-Id header: 
# User alice
claude mcp add --transport http hindsight-alice http://localhost:8888/mcp/alice/

# User bob
claude mcp add --transport http hindsight-bob http://localhost:8888/mcp/bob/
This enforces complete isolation — each MCP connection is scoped to a single bank, and tools cannot cross bank boundaries.

Build docs developers (and LLMs) love

Get started for freeTalk to us