muse-hindsight-connector

Native Muse Code plugin for long-term Hindsight memory. One bank per repo (coding-agent::<project>), shared across agents — what you tell Muse is there when you open another Hindsight-wired agent.

Works on macOS, Linux, and Windows. Pure Node.js standard library, zero dependencies, no native modules, no subprocesses.

What you get

All hooks fail open: if the server is unreachable they output {} and the session continues untouched.

Related MCP server: engram

Requirements

• Node.js ≥ 18 on PATH

• A Hindsight server (local default http://localhost:8888, self-hosted, or Cloud)

Install

git clone https://github.com/aminamos/muse-hindsight-connector.git
muse plugins install ./muse-hindsight-connector
muse plugins approve hindsight-muse

Then point it at your server (or skip this if you already use Hindsight with Claude Code / Codex — their endpoint is adopted automatically):

node muse-hindsight-connector/bin/cli.js configure
# or with env vars (sh):
# HINDSIGHT_API_URL=http://localhost:8888 HINDSIGHT_API_KEY=<token>
# PowerShell:
# $env:HINDSIGHT_API_URL='http://localhost:8888'; $env:HINDSIGHT_API_KEY='<token>'

Verify:

node muse-hindsight-connector/bin/cli.js doctor

Configuration

Endpoint precedence:

1. HINDSIGHT_API_URL / HINDSIGHT_API_KEY env vars

2. ~/.hindsight/muse.json ({apiUrl, apiToken, bankIdTemplate})

3. Adopted ~/.hindsight/claude-code.json / codex.json

4. Default: http://localhost:8888, no token

Optional overrides: HINDSIGHT_BANK_TEMPLATE (default coding-agent::{gitProject}), HINDSIGHT_BANK_ID (MCP server only).

Bank naming needs no git binary: the repo name is read from .git/config purely via the filesystem, falling back to the directory name.

One shared bank across all agents

By default every repo gets its own coding-agent::<project> bank. To share one bank with other harnesses (e.g. omp's omp bank), set the template to a fixed name — memories are still tagged per project (project:<name>) and per harness (harness:muse), so recall stays scoped but nothing is siloed:

node bin/cli.js configure   # set bankIdTemplate to: omp

Tests

npm test        # hermetic: stub-server unit + hook + MCP + manifest tests
npm run smoke   # live: needs HINDSIGHT_LIVE=1 + HINDSIGHT_SMOKE_BANK=<bank>

CI runs npm test on ubuntu / windows / macos × node 18 / 20 / 24.

Hook protocol notes

Muse hooks receive JSON on stdin (hook_event_name, session_id, cwd, transcript_path, …) and inject context by printing {"hookSpecificOutput": {"hookEventName": "<event>", "additionalContext": "…"}}. The UserPromptSubmit prompt field is read defensively from several candidate keys. Test one hook directly:

# sh / bash / zsh:
echo '{"hook_event_name":"UserPromptSubmit","cwd":".","prompt":"hi"}' \
  | node hooks/user-prompt-submit.js
# PowerShell:
# '{"hook_event_name":"UserPromptSubmit","cwd":".","prompt":"hi"}' | node hooks/user-prompt-submit.js

License

MIT