conductor-harness 1.0.0 → 1.0.2

package/README.md

@@ -8,7 +8,7 @@ A Claude Code harness for [Conductor](https://conductor.build) projects. Install
 
 - **SessionStart hook** — injects branch, recent commits, last session progress, and `WORKFLOW.md` context before every Claude Code session
 - **Linear integration** — reads attached issues directly from Conductor's `+` button; falls back to Linear MCP for comments and history
-- **Graphiti memory** — searches past decisions before starting work; writes episodes after `/done`
+- **Hindsight memory** — searches past decisions before starting work; writes memories after `/done`
 - **Context7 docs** — fetches up-to-date framework and package documentation before planning or implementing
 - **`/start`, `/done`, `/status`** — task kickoff and closeout rituals that keep progress state and memory in sync
 - **`/setup`** — analyzes your project and auto-generates `WORKFLOW.md`
@@ -16,91 +16,74 @@ A Claude Code harness for [Conductor](https://conductor.build) projects. Install
 
 ---
 
-## Requirements
+## Setup
 
-- [Claude Code](https://claude.ai/code)
-- [Conductor](https://conductor.build)
-- Node.js 18+
-- A git repository
+### 1. Install MCP servers (once per machine)
 
-**Recommended MCP servers** (register once per machine):
+**Hindsight** — persistent cross-session memory for decisions, gotchas, and patterns:
+1. Get an API key at [ui.hindsight.vectorize.io/connect](https://ui.hindsight.vectorize.io/connect)
+2. Add to your `.env`: `HINDSIGHT_API_KEY=your_key_here`
+3. The installer creates `.mcp.json` with the Hindsight config automatically — no CLI command needed.
 
+**Linear** — read and update issues from Claude Code:
 ```bash
-# Graphiti memory (Zep Cloud)
-claude mcp add graphiti-memory \
-  --transport sse \
-  --url https://mcp.getzep.com/sse \
-  --header "Authorization: Api-Key $ZEP_API_KEY"
-
-# Linear
 claude mcp add linear -s user -- npx -y @linear/mcp-server
+```
 
-# Context7 (up-to-date docs)
+**Context7** — fetch up-to-date framework and package docs:
+```bash
 claude mcp add context7 -s user -- npx -y @upstash/context7-mcp
 ```
 
----
-
-## Install
-
-Run from your project root:
+### 2. Install the harness into a project
 
+From your project root (must be a git repo):
 ```bash
 npx conductor-harness
 ```
 
-The installer will:
-
-1. Detect your package manager (pnpm / yarn / bun / npm)
-2. Ask if the project uses Railway
-3. Copy hooks, commands, skills, and agents into `.claude/`
-4. Merge harness hooks and permissions into `.claude/settings.local.json`
-5. Write `CLAUDE.md` with orchestration principles and harness configuration
-6. Write `conductor.json` with setup, run, and archive commands
-7. Create `WORKFLOW.md` for project context
-8. Create `.harness/progress.md` for session state
-
-Re-running is safe — `settings.local.json` is always merged, never overwritten.
-
----
-
-## Railway projects
+The installer will ask two questions:
+- **Package manager** — auto-detected from your lockfile
+- **Railway?** — adds `railway link` to the Conductor setup command
 
-If your project uses Railway, add these to your `.env`:
+### 3. Configure Railway (if applicable)
 
+Add to your `.env`:
 ```env
 RAILWAY_PROJECT_ID=your-project-id
 RAILWAY_ENVIRONMENT_ID=your-environment-id
 RAILWAY_SERVICE_ID=your-service-id
 ```
 
-The generated `conductor.json` setup command will pick them up automatically via `source .env`.
-
----
-
-## After install
-
-**Fill in `WORKFLOW.md`** — or let Claude generate it:
+### 4. Fill in WORKFLOW.md
 
+Either edit it manually or let Claude generate it:
 ```
 /setup
 ```
 
-**Start a task:**
+### 5. Start working
+
+Open the project in Claude Code via Conductor. The SessionStart hook fires automatically and injects your project context.
 
 ```
-/start LIN-123
+/start LIN-123    ← kick off a task
+/done             ← close it out, write memory
+/status           ← check current state
 ```
 
-Or attach a Linear issue via Conductor's `+` button and type `/start` — the harness reads it directly without an MCP fetch.
+---
+
+## Requirements
 
-**End a task:**
+- [Claude Code](https://claude.ai/code)
+- [Conductor](https://conductor.build)
+- Node.js 18+
+- A git repository
 
-```
-/done
-```
+Or attach a Linear issue via Conductor's `+` button and type `/start` — the harness reads it directly without an MCP fetch.
 
-Closes the Linear issue, writes a Graphiti memory episode, and resets progress state.
+`/done` closes the Linear issue, writes a Graphiti memory episode, and resets progress state.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-harness",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Claude Code harness for Conductor projects — hooks, memory, Linear, and workflow context",
   "bin": {
     "conductor-harness": "./bin/conductor-harness.js"

package/runtime/.claude/CLAUDE.md.template

@@ -16,7 +16,7 @@
 
 **Verify before done**: Never mark complete without proving it works. Ask: "Would a staff engineer approve this?" Run tests, check logs, demonstrate correctness.
 
-**Memory over lessons**: After /done, a Graphiti episode is written. Before non-trivial work, search memory for past decisions. This is the self-improvement loop.
+**Memory over lessons**: After /done, a memory is written to Hindsight. Before non-trivial work, recall past decisions. This is the self-improvement loop.
 
 **Docs over assumptions**: AI knowledge has a cutoff. Before using any framework, library, or package API — fetch current docs via Context7 (`mcp__claude_ai_Context7__resolve-library-id` then `mcp__claude_ai_Context7__query-docs`). Never assume an API is current. This applies in plan mode too.
 

package/runtime/.claude/agents/memory-writer.md

@@ -1,19 +1,19 @@
 ---
 name: memory-writer
-description: Writes a structured memory episode to Graphiti for the current session. Called by /done and by the Stop hook when task is marked complete.
-tools: [mcp__graphiti-memory__add_episode]
+description: Writes a structured memory to Hindsight for the current session. Called by /done and by the Stop hook when task is marked complete.
+tools: [mcp__hindsight__retain]
 ---
 
-You are a memory writer. Your only job is to write a structured episode to Graphiti.
+You are a memory writer. Your only job is to write a structured memory to Hindsight.
 
-Write one episode using the add_episode tool. The episode should contain:
+Write one memory using the retain tool. The memory should contain:
 - What was built or changed (concrete, specific)
 - Key decisions made and why
 - Gotchas, edge cases, or surprising discoveries
 - Patterns or utilities that could be reused in other contexts
 
-Group ID: use the project name from the current directory (lowercase, hyphens for spaces).
+Tag with the project name (lowercase, hyphens for spaces) derived from the current directory.
 
-Episode name format: "[DATE] [Branch/Feature]: [One-line summary]"
+Format: "[DATE] [Branch/Feature]: [One-line summary]\n\n[Body]"
 
-Be specific and brief. This episode will be recalled in future sessions — write for your future self.
+Be specific and brief. This memory will be recalled in future sessions — write for your future self.

package/runtime/.claude/commands/done.md

@@ -5,7 +5,7 @@ description: "End-of-task ritual — writes memory, updates Linear, confirms PR-
 Task completion for the current Linear issue:
 
 1. Run the type checker and any available tests. Fix any failures before continuing.
-2. Write a memory episode to Graphiti via the memory skill: include what was built, key decisions made, gotchas discovered, patterns worth reusing.
+2. Write a memory to Hindsight via the memory skill: include what was built, key decisions made, gotchas discovered, patterns worth reusing. Tag with the project name.
 3. Update `.harness/progress.md`: status: done, completed: [date], PR: [branch].
 4. Update the Linear issue status to "In Review" using the Linear MCP tool. Add a comment with a one-sentence summary of what was done.
 5. Confirm: "Ready for PR. Run ⌘⇧P in Conductor to create the PR."

package/runtime/.claude/hooks/session-start.sh

@@ -64,6 +64,6 @@ if workflow:
     lines.append("**Project context (WORKFLOW.md):**")
     lines.append(workflow)
 lines.append("")
-lines.append("**Action:** Search Graphiti memory for context relevant to this branch/task before responding to the user. Use the `memory` skill if needed.")
+lines.append("**Action:** Search Hindsight memory for context relevant to this branch/task before responding to the user. Use the `memory` skill if needed.")
 
 print(json.dumps({"promptText": "\n".join(lines)}))

package/runtime/.claude/skills/memory/SKILL.md

@@ -1,21 +1,17 @@
 ---
 name: memory
-description: "Search and write to Graphiti cross-session memory for this project"
+description: "Search and write to Hindsight cross-session memory for this project"
 ---
 
 # Memory Skill
 
-Uses Graphiti MCP (Zep Cloud) for persistent cross-session memory.
+Uses Hindsight MCP for persistent cross-session memory.
 
 ## MCP tool reference
-- `search_facts(query, group_id)` — semantic search for facts/edges
-- `search_nodes(query, group_id)` — semantic search for entities
-- `add_episode(name, episode_body, group_id, source_description)` — write new memory
-- `get_episodes(group_id, last_n)` — get recent episodes
-
-## group_id convention
-Use the project name: `nerdic-next`, `monomos`, `openfang`, `data-agent`, etc.
-Derive from the git remote URL or project root directory name.
+- `recall(query)` — semantic search across stored memories
+- `retain(content, tags)` — write a new memory (decisions, gotchas, patterns)
+- `reflect(question)` — get an AI answer using your memories as context
+- `create_mental_model(name, description)` — create a living summary document
 
 ## When to search memory
 - At session start (automatically via SessionStart hook)
@@ -28,7 +24,10 @@ Derive from the git remote URL or project root directory name.
 - After discovering a non-obvious gotcha
 - After making an architectural decision with lasting implications
 
+## Tagging convention
+Always tag memories with the project name derived from the git remote URL or project root directory name (e.g. `my-project`, `api-service`).
+
 ## Gotchas
-- If MCP is not connected, instruct: `claude mcp add graphiti-memory --transport sse --url https://mcp.getzep.com/sse --header "Authorization: Api-Key $ZEP_API_KEY"`
-- Keep episodes specific and brief — Graphiti retrieves by semantic similarity, verbose episodes dilute signal
+- If MCP is not connected, add `HINDSIGHT_API_KEY` to `.env` and ensure `.mcp.json` is present
+- Keep memories specific and brief — recall uses semantic search, verbose entries dilute signal
 - Do not write memory for obvious facts, boilerplate decisions, or things already in CLAUDE.md

package/runtime/install.sh

@@ -32,7 +32,7 @@ echo "Detected package manager: $PKG_MANAGER"
 
 # ── 3. Railway prompt ────────────────────────────────────────────────────────
 read -r -p "Does this project use Railway? [y/N] " USE_RAILWAY
-USE_RAILWAY="${USE_RAILWAY,,}"
+USE_RAILWAY="$(echo "$USE_RAILWAY" | tr '[:upper:]' '[:lower:]')"
 
 # ── 4. Create .claude subdirs ────────────────────────────────────────────────
 mkdir -p \
@@ -224,7 +224,41 @@ else
   echo "✓ WORKFLOW.md already exists (skipped)"
 fi
 
-# ── 15. Next steps ────────────────────────────────────────────────────────────
+# ── 15. .mcp.json — create or append Hindsight MCP entry ─────────────────────
+MCP_JSON="$TARGET_DIR/.mcp.json"
+
+python3 - "$MCP_JSON" <<'PYEOF'
+import sys, json, os
+
+mcp_path = sys.argv[1]
+
+hindsight_entry = {
+    "type": "http",
+    "url": "https://api.hindsight.vectorize.io/mcp/Claude/",
+    "headers": {
+        "Authorization": "Bearer ${HINDSIGHT_API_KEY}"
+    }
+}
+
+if os.path.exists(mcp_path):
+    with open(mcp_path) as f:
+        data = json.load(f)
+    if "mcpServers" not in data:
+        data["mcpServers"] = {}
+    if "hindsight" not in data["mcpServers"]:
+        data["mcpServers"]["hindsight"] = hindsight_entry
+        print("✓ Hindsight MCP added to existing .mcp.json")
+    else:
+        print("✓ .mcp.json already has hindsight entry (skipped)")
+else:
+    data = {"mcpServers": {"hindsight": hindsight_entry}}
+    print("✓ .mcp.json created with Hindsight MCP")
+
+with open(mcp_path, "w") as f:
+    json.dump(data, f, indent=2)
+PYEOF
+
+# ── 16. Next steps ────────────────────────────────────────────────────────────
 echo ""
 echo "══════════════════════════════════════════════════"
 echo "  Harness installed successfully!"
@@ -232,12 +266,9 @@ echo "════════════════════════
 echo ""
 echo "Next steps:"
 echo ""
-echo "1. Register Zep Cloud memory MCP (once per machine):"
-echo "   export ZEP_API_KEY=your_zep_api_key_here"
-echo "   claude mcp add graphiti-memory \\"
-echo "     --transport sse \\"
-echo "     --url https://mcp.getzep.com/sse \\"
-echo "     --header \"Authorization: Api-Key \$ZEP_API_KEY\""
+echo "1. Add your Hindsight API key to .env:"
+echo "   HINDSIGHT_API_KEY=your_key_here"
+echo "   Get a key at: https://ui.hindsight.vectorize.io/connect"
 echo ""
 echo "2. Register Linear MCP (once per machine, if not already):"
 echo "   claude mcp add linear -s user -- npx -y @linear/mcp-server"