The Knowledge Loop

is the MVP core. Every session captures learnings. Every new session recalls them. Solved problems stay solved.

<2s
Recall Latency
0.85
Cosine Dedup Threshold
100 days
Decay Period

The Full Task Journey

Task enters โ†’ Blueprint Engine sequences deterministic and agent nodes โ†’ review interface โ†’ engineer decides.

flowchart TD
    subgraph INPUT["๐Ÿ“ฅ TASK ENTRY"]
        CLI["jarvis CLI"]
        WEB["Autoboard Web"]
        SLACK["Slack (future)"]
    end

    subgraph ENGINE["โš™๏ธ BLUEPRINT ENGINE"]
        REG["Blueprint Registry<br/>implement-feature ยท fix-bug<br/>code-review ยท knowledge-capture"]
        API["HTTP API<br/>POST /blueprints/:id/run"]
        WF["Mastra Workflow Engine<br/>.then() .branch() .parallel()"]
        REG --> API --> WF
    end

    subgraph EXEC["๐Ÿ”„ BLUEPRINT EXECUTION"]
        KSR["๐Ÿ”ต ksRecall<br/>load past learnings"]
        GOOSE1["๐Ÿ”ด gooseAgent(implement)<br/>Goose HTTP SSE"]
        LINT["๐Ÿ”ต shellStep(lint)"]
        TEST["๐Ÿ”ต shellStep(test)"]
        GOOSE2["๐Ÿ”ด gooseAgent(fix)<br/>conditional"]
        COMMIT["๐Ÿ”ต gitStep(commit)"]
        PR["๐Ÿ”ต shellStep(gh pr create)"]
        KSI["๐Ÿ”ต ksIngest<br/>capture learnings"]

        KSR --> GOOSE1 --> LINT --> TEST
        TEST -->|fail| GOOSE2 --> TEST
        TEST -->|pass| COMMIT --> PR --> KSI
    end

    subgraph REVIEW["๐Ÿ‘๏ธ REVIEW INTERFACE"]
        LEFT["Left Panel<br/>Structured Reasoning"]
        RIGHT["Right Panel<br/>Diff Viewer / Context"]
        ACTIONS["Approve โ†’ PR<br/>Iterate โ†’ feedback<br/>Discard โ†’ cleanup"]
    end

    subgraph OUT["๐Ÿ“ค OUTPUTS"]
        GHPR["GitHub PR"]
        KB["Knowledge Base<br/>learnings ingested"]
        FEED["Iterate Loop<br/>feedback โ†’ new run"]
    end

    CLI & WEB & SLACK --> API
    WF --> KSR
    KSI --> REVIEW
    ACTIONS -->|Approve| GHPR
    ACTIONS -->|Iterate| FEED
    KSI --> KB
    FEED -->|new run| API

Write Path โ€” Knowledge Extraction

The begins when a session ends. OMO hooks intercept the session transcript and extract valuable facts.

flowchart TD
    DEV["๐Ÿ‘จโ€๐Ÿ’ป Developer codes with Claude Code"]
    HOOK["OMO PreCompact hook fires"]
    INGEST["Knowledge Service gRPC: Ingest()"]
    F1["1. Filter\nskip tool-only, short msgs, injected context"]
    F2["2. Extract\nheuristic + async LLM enrichment"]
    F3["3. Embed\nembedding provider, batched"]
    F4["4. Dedup\ncosine โ‰ฅ0.95 against existing"]
    F5["5. Classify\ntype, scope, importance"]
    F6["6. Store\nPostgreSQL: facts + vectors + audit log"]
    
    DEV --> HOOK --> INGEST
    INGEST --> F1 --> F2 --> F3 --> F4 --> F5 --> F6

1. Filter

Removes noise like tool-only executions, short messages, and previously injected context.

2. Extract

Uses heuristics and async LLM enrichment to pull out decisions, learnings, patterns, and gotchas.

3. Embed

Generates vector embeddings for the extracted facts in batches.

4. Dedup

Checks for existing facts using cosine similarity (โ‰ฅ0.95) to prevent duplicates.

5. Classify

Assigns type, scope, and importance to the fact.

6. Store

Saves the fact, vector, and audit log to PostgreSQL.

Read Path โ€” Knowledge Recall

When a new session starts, the system recalls relevant knowledge to provide context.

flowchart TD
    START["Developer starts new session / submits prompt"]
    HOOK["OMO UserPromptSubmit hook fires"]
    RECALL["Knowledge Service gRPC: Recall()"]
    R1["1. Embed query"]
    R2["2. Scope filter\nproject-local first, then global"]
    R3["3. Hybrid search\npgvector cosine + tsvector BM25"]
    R4["4. RRF fusion + scope-aware boost"]
    R5["5. Budget-aware packing\nโ‰ค N tokens"]
    R6["6. Format as markdown"]
    INJECT["OMO injects as prependContext"]
    CLAUDE["Claude Code sees relevant knowledge in context"]
    
    START --> HOOK --> RECALL
    RECALL --> R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> INJECT --> CLAUDE

The recall process uses for vector similarity and to combine vector and keyword search results.

Compaction โ€” Background Maintenance

To keep the knowledge base healthy, background compaction runs periodically.

flowchart TD
    TRIGGER["Scheduled trigger\nperiodic / threshold"]
    COMPACT["Knowledge Service: Compact()"]
    S1["Strategy 1: Semantic Dedup\ncosine โ‰ฅ0.95 โ†’ merge, keep richest version"]
    S2["Strategy 2: Temporal Supersession\nsame entity + newer timestamp โ†’ newer wins"]
    S3["Strategy 3: Relevance Decay\nscore = importance ร— e^(-ฮปร—days) ร— log(1+access)\nbelow threshold โ†’ archive"]
    
    TRIGGER --> COMPACT
    COMPACT --> S1
    COMPACT --> S2
    COMPACT --> S3

The Specialist Pipeline

Jarvis operates on a pipeline paradigm: Intent Router โ†’ Knowledge Service โ†’ Advisory Agent. Each specialist is best at one thing.

There are two types of knowledge:

  • Canonical/Deterministic: "Dijkstra's for shortest path" โ€” textbooks, CS fundamentals, taxonomy exact match.
  • Experiential/Contextual: "Last time our auth service had this race condition..." โ€” session-extracted, vector similarity.
specs/001-core-knowledge-loop/spec.md docs/architecture/diagrams.md