# Competitive Gap #1: Knowledge Graph — Hindsight Integration Plan > **Verdict: INTEGRATE, DO NOT BUILD.** Hindsight already provides a superset of the capabilities pi-maestro-flow's knowledge graph offers. The gap is integration into the workflow engine, not capability. --- ## Problem pi-maestro-flow ships a SQLite/BM25F knowledge graph with: - Structured taxonomy: `spec` / `knowhow` / `domain` types - Cross-workspace read-only sharing via `maestro workspace link` - Auto-deposit from session artifacts (SessionStart, UserPromptSubmit, PreToolUse hooks) - Lifecycle management: supersede, contested, time-decay per type - Code symbol integration (import/call edges in KG) - BM25F field-weighted full-text search Our pi-dynamic-workflows has **no workflow-integrated knowledge system**. Every run starts cold. The conductor has no memory of past plans, review findings, or architectural decisions beyond what's in the transcript (lost to compaction) or committed files. **However**, this VM runs the Hindsight memory plugin with: - 50+ existing banks on a healthy self-hosted server (`http://10.100.0.100:8888`) - `tooling` bank: 336K facts, `shared-dev`: 611 facts, `gt::pi-dynamic-workflows`: 0 (newly created) - Auto-recall on every prompt, auto-retain on every turn - `memory_gardener` saved workflow (Graphiti-style dedupe/supersede/expire) - `hindsight_reflect` for synthesis - Bank mission and entity label configuration **Question: Can we close this gap natively with Hindsight?** --- ## Hindsight Feature Audit (What It Already Has) ### Cross-session persistence ✓ Banks survive restarts. Each bank is an isolated container of memories, documents, entities, relationships, observations, and directives. `document_id` enables idempotent upserts (replace or append mode). ### Cross-workspace banks ✓ Each project gets its own bank (e.g., `proj-dev-system`, `proj-kneutral-api`). `shared-dev` and `momentum::shared-dev` serve as cross-project banks. Tag-based scoping (`tag_groups` with AND/OR/NOT compounds) enables fine-grained isolation within a single bank. ### Auto-retain ✓ Runs on `agent_end` hook. Uses stable `documentId` + `updateMode: "append"` with a versioned cursor (`retain-cursors.json`) for dedup across overlapping transcripts. Queue-first durability: jobs written to JSONL before sending; survives Hindsight server downtime. ### Graphiti-style staleness resolution ✓ **Observations** are the key feature. After `retain()`, Hindsight's consolidation engine automatically: - Compares new facts against existing observations - Synthesizes new observations or refines existing ones - Tracks supporting evidence with exact quotes and proof counts - Handles contradictory evidence (preserves history, captures evolution) - Marks stale observations for re-verification against raw facts - Near-duplicate reconciliation: automatically merges observations ≥0.97 cosine similarity (configurable, disabled on Oracle) ### Reflect/synthesis ✓ `hindsight_reflect` runs a dedicated agent that: 1. Retrieves observations (highest priority) 2. Checks raw facts (ground truth verification) 3. Considers mental models (curated summaries) 4. Returns synthesized markdown with `based_on` evidence trail ### Multi-strategy recall (surpasses BM25F) ✓ TEMpr pipeline runs four strategies in parallel, fuses with RRF, re-ranks with cross-encoder: | Strategy | What it does | Best for | |----------|-------------|----------| | **Semantic** | Embedding similarity | Conceptual matches, paraphrasing, synonyms | | **Keyword (BM25)** | Pluggable backend (5 options, including `pg_search` for true BM25) | Exact terms, proper nouns, technical identifiers | | **Graph traversal** | Entity relationship hopping | Indirect connections, multi-hop reasoning | | **Temporal** | Natural language time parsing | "What happened last sprint?", time-range queries | ### Entity taxonomy (equivalent to spec/knowhow/domain) ✓ `entity_labels` in bank config defines a controlled vocabulary of `key:value` classifications: - Enum groups (`value`, `multi-values`): predefined list - Free-text groups (`text`): guided by description - Map groups (`map`): structured entities with named fields (e.g., `person:name`, `person:role`, `person:organization`) - Label entities become graph nodes, link memories, and improve retrieval - `tag: true` makes labels filterable via `tags/tags_match` ### Token-budget recall (agent-native) ✓ Hindsight measures in tokens, not result counts. `max_tokens` controls context allocation; `budget` (low/mid/high) controls search depth. Built for AI agents, not humans. --- ## Gap Analysis: What Hindsight Doesn't Provide (That the Workflow Engine Needs) ### (a) Mid-run agent() auto-retain and recall ⚠️ PARTIAL **Current state:** The extension config has `toolsEnabled: ["retain", "reflect"]` — `hindsight_recall` is **disabled** and recall only works via the auto-recall context hook (which fires at prompt composition, not during agent execution). **Can a workflow agent() auto-retain mid-run?** YES. `hindsight_retain` is enabled. An agent can call: ``` hindsight_retain({ content: "Workflow found: authentication uses JWT in src/auth/jwt.ts", context: "workflow-discovery", document_id: "wf-pi-dynamic-workflows-auth-pattern", tags: ["type:discover", "workflow:issue-delivery"], metadata: {"source": "agent", "step": "discovery"} }) ``` **Can a later agent() recall it mid-run?** CURRENTLY NO. `hindsight_recall` is not in `toolsEnabled`. Options: 1. **Enable recall tool** — simplest, add `"recall"` to `toolsEnabled`. Risk: agents spamming recall. 2. **Conductor-mediated recall** — the conductor (medium tier) runs `hindsight_reflect` and injects results into downstream agent prompts via `contextPrefix`/system text. 3. **Auto-recall improvement** — widen auto-recall scope to include workflow-specific tags so the auto-recall context hook picks up workflow memories on every turn. **Recommendation:** Option 1 + 3. Enable `hindsight_recall` with a guardrail in the agent system prompt instructing agents to use targeted queries and respect the budget. Auto-recall already covers the default case. ### (b) Structured taxonomy (spec/knowhow/domain) ⚠️ PARTIAL pi-maestro-flow has a file-based structured taxonomy: - `specs/*.md` — Markdown with `` blocks, frontmatter (sid, status, confidence) - `knowhow/{TYPE}-{timestamp}-{slug}.md` — frontmatter + body, prefixed by type (KNW/TIP/TPL/RCP/REF/DCS/AST/BLP/DOC) - `domain/glossary.json` — protected Data Store Hindsight has **free-text observations** by default. However, it can approximate structured knowledge through: 1. **Entity labels** — Define classification dimensions in bank config: ```json { "entity_labels": [ { "key": "knowledge_type", "type": "value", "description": "Type of workflow knowledge", "values": [ { "value": "plan", "description": "Issue delivery plan/architecture" }, { "value": "finding", "description": "Review or test finding" }, { "value": "convention", "description": "Project convention or spec" }, { "value": "decision", "description": "Architecture decision" }, { "value": "lesson", "description": "Hard-won lesson" } ], "tag": true }, { "key": "artifact_stage", "type": "value", "description": "Pipeline stage where this was produced", "values": [ { "value": "scout" }, { "value": "planner" }, { "value": "worker" }, { "value": "reviewer" }, { "value": "verifier" }, { "value": "finalize" } ], "tag": true } ] } ``` 1. **Tag-based retrieval** — `types: ["observation"]` + `tags: ["knowledge_type:plan"]` + `tags_match: "any_strict"` gives type-filtered recall. 2. **Context field** — Every `retain()` call can set `context` (e.g., `"issue-delivery-plan"`, `"adversarial-review"`), which shapes extraction and is returned with recall results. 3. **Mental models** — For curated "best-of" summaries (equivalent to a `domain/glossary.md`): ``` hindsight_reflect generates a mental model that: - Auto-refreshes on new retains (refresh_after_consolidation: true) - Supports delta mode (surgical edits, preserves unchanged sections) - Can be tagged and filtered ``` **Gap remaining:** Hindsight doesn't have the same explicit lifecycle as maestro's spec (supersede, contested, deprecated, health checks). However, Hindsight's observation system achieves the same goal — new evidence refines existing observations, contradictions are captured with history. A "deprecated" plan becomes an observation noting the superseding decision. ### (c) BM25F vs semantic/keyword ⚠️ REVERSE GAP pi-maestro-flow uses BM25F (field-weighted BM25: title ×5, tags ×3, summary ×1.5, body ×0.5). This is **inferior** to Hindsight's TEMpr: - BM25F is pure keyword with field boosting - TEMpr adds semantic (embeddings), graph (entities), and temporal - Hindsight's keyword backend is pluggable (supports `pg_search` for true BM25 if needed) **No gap here.** Hindsight's recall is superior. ### (d) Auto-deposit from workflow artifacts ⚠️ ACTION NEEDED pi-maestro-flow auto-deposits via three hooks: - `SessionStart` — injects spec + wiki role context - `UserPromptSubmit` — keyword spec injector - `PreToolUse` — context injection Hindsight auto-retain runs on `agent_end` but the current config restricts to conversational text only: ```json "retainContent": { "assistant": ["text"], "user": ["text"] } ``` Tool calls, tool results, CI statuses, git diffs are NOT retained. **This is the biggest actionable gap.** **Fix:** Two complementary approaches: 1. **Widen auto-retain** for workflow banks — include structured tool output: ```json "retainContent": { "assistant": ["text", "toolCall"], "toolResult": ["text"] } ``` With a corresponding `retainMission` focused on workflow knowledge: "Focus on technical decisions, plans, review findings, test results, and architectural decisions. Ignore routine tool invocations, file reads, and search results." 1. **Saved workflow auto-deposit hooks** — After key workflow stages, call `hindsight_retain` explicitly with structured content: - After **Planner**: retain the plan with `context: "issue-plan"`, `document_id: "wf-{issue-id}-plan"` - After **Reviewer**: retain findings with `context: "review-findings"`, `document_id: "wf-{issue-id}-review"` - After **Verifier**: retain test results with `context: "verification"` - After **Finalize**: retain the outcome (ship/decline) with CI status This is more targeted than widening auto-retain and gives full control over what gets deposited. ### (e) Code symbol integration (callers/callees) ⚠️ OUT OF SCOPE pi-maestro-flow indexes code symbols into the KG and traverses import/call edges. Hindsight's graph is entity-based (people, projects, concepts), not AST-level. **This is not a gap for the workflow engine.** The workflow engine already has `codegraph_search`, `codegraph_callers`, `codegraph_callees`, `lsp_navigation`, and `ast_grep_search` for code-aware exploration. Hindsight doesn't need to replicate this — it complements it. ### (f) Cross-workspace sharing (read-only linked workspaces) ⚠️ MINOR pi-maestro-flow: `maestro workspace link ../shared-lib --name shared --share spec,knowhow,domain` Hindsight: Separate banks with `hindsight_recall` targeting a specific bank + tag filter. No "link" command needed — the API already supports multi-bank operations. The `shared-dev` bank already serves as the cross-project knowledge store. **Gap:** If a workflow needs to read another project's knowledge, it needs the other project's bank ID and appropriate tags. This is achievable but requires operator configuration (setting the right bank ID in the workflow's hindsight config). --- ## Proposed Integration ### Phase 1: Enable and Configure 1. **Extension config update** (`~/.pi/agent/extensions/pi-hindsight/config.jsonc`): - Add `"recall"` to `toolsEnabled`: `["retain", "reflect", "recall"]` - Update `retainContent` for workflow banks to include structured tool output - Configure `entity_labels` for `gt::pi-dynamic-workflows` bank 2. **Bank configuration** (Hindsight API or Control Panel): - Set `retain_mission` for `gt::pi-dynamic-workflows`: ``` Focus on workflow knowledge: plans, architecture decisions, review findings, test results, lessons learned, and operational conventions. Extract facts about code patterns discovered, issues resolved, and workflow stage outcomes. Ignore routine file reads, search results, and tool invocation details. ``` - Define `entity_labels` (see above taxonomy) - Set `observations_mission`: ``` Synthesize durable workflow knowledge: recurring patterns in issue delivery, common review findings, test failure patterns, and architectural conventions. Focus on observations that would help future workflow agents avoid repeating mistakes or rediscover proven patterns. ``` 3. **System prompt addition** — Add a workflow-integration section to the agent system prompt instructing agents when to use `hindsight_retain`, `hindsight_recall`, and `hindsight_reflect` during workflow runs. ### Phase 2: Saved Workflow Auto-Deposit Integrate `hindsight_retain` calls into existing saved workflows at key stages: | Workflow | Stage | Retain Content | Context | Document ID | |----------|-------|---------------|---------|-------------| | `issue-delivery` | After Planner | Plan summary, scope, approach | `issue-plan` | `wf-{issueId}-plan-{timestamp}` | | `issue-delivery` | After Worker | Implementation summary, key decisions | `implementation` | `wf-{issueId}-impl-{timestamp}` | | `issue-delivery` | After Verifier | Test results, CI status | `verification` | `wf-{issueId}-verify-{timestamp}` | | `pr_adversarial_review` | After reviewers | Review findings, severity, resolved status | `adversarial-review` | `wf-{prNumber}-review-{timestamp}` | | `surgical_pr_repair` | After repair | Repair scope, what was fixed | `pr-repair` | `wf-{prNumber}-repair-{timestamp}` | Each retain call includes: ```json { "content": "", "context": "", "document_id": "", "tags": ["workflow:", "stage:", "issueId:"], "metadata": { "source": "workflow-auto-deposit", "workflow": "", "issueId": "", "stage": "", "agentTier": "" } } ``` ### Phase 3: Knowledge Injection at Workflow Start Before the Scout/Planner starts, the conductor runs: ```javascript // Pseudocode for workflow integration const recentContext = await agent( "Recall relevant workflow knowledge for this issue", { label: 'knowledge-recall', tier: 'small', tools: ['hindsight_recall', 'hindsight_reflect'], contextPrefix: `Issue: ${issue.title}\nRepo: ${repo.name}\n\nRecall relevant knowledge from past workflows using hindsight_recall. Focus on plans, findings, and lessons related to this area of the codebase.` } ); ``` The recalled knowledge is injected into the Scout/Planner prompt via `contextPrefix`. ### Phase 4: Memory Gardener for Workflow Banks Extend the existing `memory_gardener` saved workflow to cover the `gt::pi-dynamic-workflows` bank: - **Dedupe**: Merge near-identical workflow findings (already handled by Hindsight's auto-consolidation) - **Supersede**: Mark superseded plans/decisions (observations naturally evolve) - **Expire**: Archive old CI statuses, temporary findings (use `updateMemory` with `state: "invalidated"`) - **Reflect**: Periodic synthesis of workflow patterns across all issues The memory_gardener runs on a schedule (e.g., weekly) or on demand via `/hindsight:gardener`. --- ## Scope ### In scope (Phase 1–2, ~1 week) - [ ] Enable `hindsight_recall` in extension config - [ ] Configure `gt::pi-dynamic-workflows` bank with mission + entity_labels - [ ] Add system prompt guidance for workflow-aware memory usage - [ ] Implement auto-deposit in `issue-delivery` saved workflow (plan + verify stages) - [ ] Implement auto-deposit in `pr_adversarial_review` (findings) - [ ] Test: workflow agent retains → later session recalls → knowledge injected ### In scope (Phase 3–4, ~1 week) - [ ] Conductor-mediated knowledge recall at workflow start - [ ] Extend memory_gardener to workflow bank - [ ] Mental models for curated workflow knowledge summaries - [ ] End-to-end test: plan → implement → ship → recall → reuse ### Nice-to-have - [ ] Cross-bank recall: read `shared-dev` knowledge during workflow runs - [ ] Auto-deposit for CI telemetry (test results, performance numbers) - [ ] Workflow-specific mental model: "current-state-of-workflows" auto-refreshing summary - [ ] Bank config `entity_labels` refinement based on actual workflow data patterns --- ## Non-Goals - **DO NOT build a parallel SQLite store.** Hindsight IS the knowledge system. Building a second store (like pi-maestro-flow's `kg/maestro.db`) duplicates effort and splits the knowledge graph. - **DO NOT vendor pi-maestro-flow's schema.** Their `spec/knowhow/domain` taxonomy is a file-based artifact that doesn't translate well to a memory system. Hindsight's entity labels + observations + mental models achieve the same outcome differently. - **DO NOT replicate code symbol integration.** The workflow engine already has `codegraph_*` tools. Hindsight complements, not replaces, code-aware exploration. - **DO NOT replace the memory_gardener.** Extend it, don't rewrite it. It already does Graphiti-style maintenance; add workflow bank coverage. - **DO NOT auto-retain everything.** Wider `retainContent` is a Phase 2 consideration with clear risks (token bloat, noisy facts). Start with targeted auto-deposit first. --- ## File-Touch List | File | Change | Reason | |------|--------|--------| | `~/.pi/agent/extensions/pi-hindsight/config.jsonc` | Edit | Enable `recall` tool, update `retainContent` | | `src/workflow/issue-delivery.ts` | Edit | Add auto-deposit retain calls after planner/verifier stages | | `src/workflow/pr-review.ts` | Edit | Add auto-deposit retain call after review stage | | `src/workflow/conductor.ts` | Edit | Add pre-scout knowledge recall step | | `src/agent/system-prompt.ts` | Edit | Add memory usage guidance section | | `docs/plans/competitive-gap-1-knowledge-graph-hindsight.md` | Create | This document | | *(Hindsight API)* | POST | Configure bank mission + entity_labels via REST API | **Total new code:** ~200 lines (retain call wrappers + recall injection logic) **Total modified:** ~5 files **No new dependencies:** Hindsight is already installed and running --- ## Test Plan ### Unit tests | Test | What it verifies | Method | |------|-----------------|--------| | Retain wraps correctly | Auto-deposit produces valid retain payloads | Mock Hindsight API, verify payload schema | | Recall returns structured results | Recall queries return facts with expected types/tags | Assert on `results[0].type == "observation"` or `"world"` | | Bank config persists | Entity labels and mission are stored on the bank | GET bank config API, assert fields | | Document_id uniqueness | Auto-deposit IDs don't collide | Generate 100 IDs, assert no dups | | Tag filtering works | Recall with tag filter only returns tagged memories | Retain with tag → recall with tag → verify isolation | ### Integration tests | Test | Setup | Verification | |------|-------|-------------| | Plan → Recall | Run issue-delivery workflow → start new session → recall same issue | Recall returns the plan as a fact/observation | | Findings survive compaction | Run workflow with transcript compaction → recall | Knowledge persists (not dependent on transcript) | | Cross-issue knowledge | Complete issue A with finding X → run issue B → recall "X" | Finding from issue A is recalled | | Auto-deposit hooks fire | Run workflow → check Hindsight bank fact count increased | `fact_count` incremented by expected amount | | Observation consolidation | Run two similar workflows → check for consolidated observations | Single observation with multiple source facts | ### Smoke test (manual) 1. Run `/issue-delivery` on a small issue 2. Observe retain calls in the transcript 3. Restart session (new tab, same repo) 4. Ask "what do I know about the workflow for this area?" 5. Verify `hindsight_reflect` returns relevant prior knowledge 6. Verify the knowledge is in the right bank (`gt::pi-dynamic-workflows`) --- ## Conclusion **can_do_natively: true** Hindsight provides a capable, mature memory system that covers and in many ways exceeds pi-maestro-flow's knowledge graph. The gap is **integration**, not capability: 1. Enable the recall tool (1 line config change) 2. Configure the bank for workflow knowledge (REST API call) 3. Wire auto-deposit into saved workflows (~200 lines of code) 4. Add knowledge recall at workflow start (~50 lines) 5. Extend memory_gardener to workflow banks (~30 lines) No parallel store. No vendor-lock-in. No schema translation. Just Hindsight, properly integrated. --- ## JSON Summary ```json { "can_do_natively": true, "hindsight_features_found": [ "TEMpr multi-strategy recall (semantic + BM25 + graph + temporal, RRF fusion)", "Observations with auto-consolidation, evidence grounding, and evolution", "Entity labels for controlled vocabulary taxonomy", "Mental models with auto-refresh (full/delta mode)", "Bank mission and custom retain instructions", "Compound tag_groups filtering (AND/OR/NOT)", "Queue-first durability for retain jobs", "Near-duplicate observation reconciliation", "Freshness awareness with stale re-verification", "Cross-bank isolation and multi-bank operations", "Token-budget recall optimized for AI agents", "Document upserts (replace/append modes)", "Memory curation (invalidate/revert with reason tracking)", "Webhooks for event-driven notifications" ], "hard_gaps_remaining": [ "hindsight_recall tool not enabled by default (config fix needed)", "No pre-configured entity_labels taxonomy for workflow knowledge (needs bank config)", "Auto-deposit hooks not wired into saved workflows (needs integration code)", "Auto-retain excludes tool outputs and CI data (config or targeted retain needed)", "No code-AST knowledge graph (but codegraph_* tools already cover this)", "No explicit spec lifecycle (supersede/contested/health) — observations evolve naturally instead" ], "integration_approach": "Extend Hindsight via: (1) enable recall tool in config, (2) configure bank mission + entity_labels for workflow taxonomy, (3) wire hindsight_retain into saved workflows at key stages (planner, reviewer, verifier, finalizer), (4) conductor runs hindsight_reflect at workflow start to inject prior knowledge, (5) extend memory_gardener to workflow bank for ongoing maintenance", "issue_title": "[Gap #1] Integrate Hindsight as workflow knowledge system (no parallel store)", "issue_body": "Competitive gap: pi-maestro-flow has a SQLite/BM25F knowledge graph that persists workflow knowledge across sessions. Our workflow engine starts cold every run.\n\nResearch found that Hindsight (already running on this VM) provides a superset of capabilities: TEMpr recall (semantic+keyword+graph+temporal), auto-consolidating observations with evidence grounding, entity labels for taxonomy, mental models for curated summaries, and tag-based scoping for isolation.\n\nThe gap is integration, not capability. Required changes:\n1. Enable hindsight_recall in extension config\n2. Configure gt::pi-dynamic-workflows bank with mission + entity_labels\n3. Wire auto-deposit into saved workflows (issue-delivery, pr-review)\n4. Conductor-mediated knowledge recall at workflow start\n5. Extend memory_gardener to workflow bank\n\nFull analysis: docs/plans/competitive-gap-1-knowledge-graph-hindsight.md", "labels": ["gap-1-knowledge-graph", "hindsight-integration", "workflow-engine", "no-new-store", "phase-1-easy-win"] } ```