Hindsight Memory Plugin for Grok Build

Biomimetic long-term memory for Grok Build using Hindsight. The plugin automatically captures your conversations and intelligently recalls the relevant context on every prompt — so Grok remembers across sessions instead of starting cold each time.

Installation

1. Install the plugin

In Grok Build, run /plugin, search for hindsight, and select it to install. This wires up the lifecycle hooks (auto-recall / auto-retain) and the bundled Hindsight MCP server. You can verify the MCP connection any time with /mcp.

2. Choose how memory is extracted

Hindsight needs an LLM to extract durable facts from your conversations. Pick one:

# Option A — OpenAI (auto-detected)
export OPENAI_API_KEY="sk-your-key"

# Option B — Anthropic (auto-detected)
export ANTHROPIC_API_KEY="your-key"

# Option C — Connect to an external/hosted Hindsight server instead of running locally
#           (the server handles extraction; no local key needed)
mkdir -p ~/.hindsight
echo '{"hindsightApiUrl": "https://your-hindsight-server.com", "hindsightApiToken": "your-token"}' > ~/.hindsight/claude-code.json

That's it. Once installed, the plugin activates automatically — it captures conversation content and recalls relevant memories before each prompt, with no further setup.

Features

• Auto-recall — on every prompt, queries Hindsight for relevant memories and injects them as context (visible to Grok, invisible in the chat transcript)
• Auto-retain — after each response (or every N turns), extracts and stores conversation content to Hindsight for long-term memory
• Knowledge tools — an MCP server exposing agent_knowledge_* tools to manage knowledge pages (list, get, create, update, delete), search memories, and ingest documents
• Subagents with memory — scaffold specialized subagents that learn across sessions via the create-agent skill
• Daemon management — auto-starts/stops a local hindsight-embed daemon, or connects to an external Hindsight server
• Dynamic bank IDs — per-agent, per-project, or per-session memory isolation
• Lightweight — hooks are pure Python stdlib; the MCP server only needs the mcp pip package

Knowledge tools (MCP)

When the MCP server is connected, the plugin exposes these tools:

Tool	Description
agent_knowledge_list_pages	List all knowledge pages
agent_knowledge_get_page	Read a specific page
agent_knowledge_create_page	Create a new page with a source query
agent_knowledge_update_page	Update a page's name or source query
agent_knowledge_delete_page	Delete a page
agent_knowledge_recall	Search memories
agent_knowledge_ingest	Ingest text content
agent_knowledge_ingest_file	Ingest a file from disk
agent_knowledge_get_current_bank	Get the current bank ID

The bank ID is resolved automatically from the plugin config — tools never expose a bank_id parameter.

Connection modes

The plugin supports three ways to reach Hindsight:

1. External API (recommended for production) — connect to a running Hindsight server (cloud or self-hosted). No local LLM needed; the server handles fact extraction. Set hindsightApiUrl (and hindsightApiToken).
2. Local daemon (auto-managed) — the plugin starts and stops hindsight-embed for you via uvx, talking to it over http://127.0.0.1:9077. Requires an LLM provider key for local extraction. Leave hindsightApiUrl empty.
3. Existing local server — if you already run hindsight-embed, leave hindsightApiUrl empty and set apiPort to match; the plugin detects it automatically.

Configuration

All settings live in ~/.hindsight/claude-code.json, and every setting can also be overridden by an environment variable. The plugin ships with sensible defaults — you only configure what you want to change.

Loading order (later wins): built-in defaults → plugin settings.json → ~/.hindsight/claude-code.json → environment variables.

Common settings:

Setting	Env Var	Default	Description
hindsightApiUrl	HINDSIGHT_API_URL	""	External Hindsight API server URL. Empty = use the local daemon.
hindsightApiToken	HINDSIGHT_API_TOKEN	null	Auth token for the external API.
apiPort	HINDSIGHT_API_PORT	9077	Port for the local hindsight-embed daemon.
embedVersion	HINDSIGHT_EMBED_VERSION	"latest"	Version of hindsight-embed to install via uvx. Pin for reproducibility.
llmProvider	HINDSIGHT_LLM_PROVIDER	auto-detect	Local-daemon LLM provider: openai, anthropic, gemini, groq, ollama. Auto-detected from API-key env vars when omitted.
llmModel	HINDSIGHT_LLM_MODEL	provider default	Override the default model for the chosen provider.

See the full configuration reference and provider setup at https://vectorize.io/hindsight.

How it works

Component	Trigger	Purpose
session_start.py	SessionStart hook	Health check — verify Hindsight is reachable
recall.py	UserPromptSubmit hook	Auto-recall — query memories, inject as context
retain.py	Stop hook (async)	Auto-retain — extract the transcript, store to Hindsight
session_end.py	SessionEnd hook	Cleanup — stop the auto-managed daemon if started
mcp_server.py	MCP stdio server	Knowledge tools (agent_knowledge_*)
create-agent	Skill	Scaffold a memory-backed subagent

Network & credentials

• The local daemon is reached over loopback only (http://127.0.0.1:9077) — no inbound listener, no external endpoint by default.
• Outbound calls happen only when you configure them: your chosen LLM provider (using your own API key) for fact extraction, or an external Hindsight API URL you set explicitly.
• The MCP launcher creates a per-plugin virtualenv and installs mcp from the bundled requirements.txt — no remote code execution. The memory backend is Hindsight's own hindsight-embed package, fetched via uvx.

Links

• Hindsight: https://vectorize.io/hindsight
• Documentation: https://hindsight.vectorize.io
• Source: https://github.com/vectorize-io/hindsight

License

MIT © Vectorize AI, Inc.