opencode-orchestrator 1.2.71 → 1.3.3

package/README.md

@@ -9,7 +9,7 @@
   [![MIT License](https://img.shields.io/badge/license-MIT-red.svg)](LICENSE)
   [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
   <!-- VERSION:START -->
-  **Version:** `1.2.71`
+  **Version:** `1.3.3`
   <!-- VERSION:END -->
 </div>
 
@@ -238,6 +238,42 @@ Maintains focus across thousands of conversation turns using a 4-tier memory str
 - **Diagnostic Intervention**: Forces "Diagnostic Mode" mandating log audits and strategy pivots
 - **Proactive Agency**: Mandates Speculative Planning during background task execution
 
+### 🧬 Knowledge Graph RAG (Second Brain)
+An autonomous **Obsidian-style evolutionary memory system** that gives agents persistent, searchable knowledge across sessions.
+
+Runtime context injection is active for orchestrated sessions through `experimental.chat.system.transform`, indexing `docs/**/*.md` and `.opencode/docs/**/*.md` with BM25/tag/graph fusion before prompt injection.
+
+```
+  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+  │  📝 Ingest   │────▶│  🔍 Search   │────▶│  🧠 Recall   │
+  │  ──────────  │     │  ──────────  │     │  ──────────  │
+  │  YAML Parser │     │  BM25 Lexical│     │  RRF-Ranked  │
+  │  Tag HashMap │     │  Tag Index   │     │  Top-K Notes │
+  │  Wiki-Links  │     │  2-Hop Graph │     │  → Context   │
+  └──────┬───────┘     └──────────────┘     └──────────────┘
+         │
+         ▼
+  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+  │  🔄 Evolve   │────▶│  🛡️ Guard    │────▶│  📦 Archive  │
+  │  ──────────  │     │  ──────────  │     │  ──────────  │
+  │  Fission     │     │  Cycle DFS   │     │  Orphan GC   │
+  │  Fusion      │     │  Write FIFO  │     │  MOC Hubs    │
+  │  (Auto-Split │     │  Keep-Pin    │     │  MD Export   │
+  │   & Merge)   │     │  Shield      │     │              │
+  └──────────────┘     └──────────────┘     └──────────────┘
+```
+
+**Six integrated modules** power the knowledge pipeline:
+
+| Module | Purpose |
+|:-------|:--------|
+| **TagIndexer** | O(1) YAML frontmatter parsing → tag-to-file HashMap |
+| **GraphParser** | `[[wiki-link]]` extraction, bi-directional adjacency graph |
+| **HybridSearch** | BM25 + Tag + 2-Hop Graph → **Reciprocal Rank Fusion** (k=60) |
+| **Scratchpad** | LRU register cache (64 slots, 4KB max) with markdown persistence |
+| **SafetyGuards** | Circular link DFS, async FIFO write queue, keep-pin shield |
+| **MemoryConsolidation** | Fission/Fusion/GC/MOC — pure functional analysis |
+
 ---
 
 ## ⚙️ Performance Benchmarks
@@ -276,6 +312,7 @@ Maintains focus across thousands of conversation turns using a 4-tier memory str
 - **Memory**: Object pooling + string interning + buffer pooling
 - **State Management**: MVCC + Mutex
 - **Safety**: RAII + circuit breaker + resource pressure detection
+- **Knowledge**: In-memory graph RAG with BM25/Tag/Graph search fusion
 
 ---
 
@@ -342,6 +379,7 @@ const task = createParallelTask({ description: "Test" });
 
 - [System Architecture Deep-Dive →](docs/SYSTEM_ARCHITECTURE.md)
 - [Developer Notes →](docs/DEVELOPERS_NOTE.md)
+- [Knowledge RAG Roadmap →](docs/histories/2026/05/31/PLAN_SecondBrainOrchestration_2026-05-31.md)
 
 ---
 

package/dist/core/knowledge/context-provider.d.ts

@@ -0,0 +1,8 @@
+export declare class KnowledgeContextProvider {
+    buildPrompt(directory: string, query: string): string | null;
+    private collectMarkdownFiles;
+    private walkDirectory;
+    private indexKnowledge;
+    private buildSnippet;
+    private formatPrompt;
+}

package/dist/core/knowledge/graph-parser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * GraphParser - Bi-directional Obsidian Wiki-Link & Markdown Link Knowledge Graph Parser
+ */
+export declare class GraphParser {
+    /** Heading marker used for the auto-generated backlinks section */
+    static readonly BACKLINKS_HEADING = "## \uD83D\uDD17 Backlinks";
+    private forwardLinks;
+    private backlinks;
+    private noteToPath;
+    private pathToNote;
+    /**
+     * Resolve file path or relative link to a note name (basename without extension).
+     */
+    getNoteName(filePath: string): string;
+    /**
+     * Parse content and extract all unique referenced target note names.
+     */
+    parseLinks(content: string): string[];
+    /**
+     * Index file and register its bi-directional links.
+     */
+    indexFile(filePath: string, content: string): void;
+    /**
+     * Retrieve backlinks for a note name or file path.
+     */
+    getBacklinks(noteOrPath: string): string[];
+    /**
+     * Retrieve forward links for a note name or file path.
+     */
+    getForwardLinks(noteOrPath: string): string[];
+    /**
+     * Synchronize the ## 🔗 Backlinks section in a file's content.
+     */
+    syncBacklinksSection(content: string, backlinksList: string[]): string;
+    /**
+     * Clear all indexes for a note.
+     */
+    private clearIndexForNote;
+}

package/dist/core/knowledge/hybrid-search.d.ts

@@ -0,0 +1,65 @@
+/**
+ * HybridSearch - Combines lexical (BM25-inspired), tag, and graph search
+ * with Reciprocal Rank Fusion to surface the most relevant notes.
+ */
+import type { TagIndexer } from "./tag-indexer.js";
+import type { GraphParser } from "./graph-parser.js";
+/** Unified search result with provenance tracking. */
+export interface SearchResult {
+    noteName: string;
+    score: number;
+    matchType: "lexical" | "tag" | "graph";
+}
+export declare class HybridSearch {
+    private readonly tagIndexer;
+    private readonly graphParser;
+    /** Stores indexed note content keyed by note name. */
+    private contentMap;
+    constructor(tagIndexer: TagIndexer, graphParser: GraphParser);
+    /**
+     * Register note content for lexical search.
+     * Must be called after TagIndexer.indexFile / GraphParser.indexFile.
+     */
+    indexContent(noteName: string, content: string): void;
+    /**
+     * Fuse lexical, tag, and graph rankings via RRF to produce a single list.
+     */
+    search(query: string, maxResults?: number): SearchResult[];
+    /**
+     * BM25-inspired term-frequency scoring across all indexed documents.
+     * Approximates IDF via corpus size and document frequency.
+     */
+    private lexicalSearch;
+    /**
+     * Match query terms against the tag index to find tagged notes.
+     */
+    private tagSearch;
+    /**
+     * 2-hop graph traversal from tag-matched seed notes to discover related notes.
+     */
+    private graphSearch;
+    /**
+     * Depth-limited BFS from a seed note, scoring neighbors by proximity.
+     */
+    private traverseGraph;
+    /**
+     * Reciprocal Rank Fusion: combine three ranked lists into a single ranking.
+     * Formula: score(d) = Σ 1/(k + rank_i) for each list where d appears.
+     */
+    private fuseResults;
+    /**
+     * Accumulate RRF scores from a single ranked list into the fused map.
+     * The matchType is set to the source with the highest individual contribution.
+     */
+    private addRrfScores;
+    /** Split query into lowercase tokens for matching. */
+    private tokenize;
+    /** Count non-overlapping occurrences of a term in text. */
+    private countOccurrences;
+    /** Average document length across the corpus (character-based). */
+    private computeAverageLength;
+    /** Number of documents containing the given term. */
+    private documentFrequency;
+    /** Sort entries by descending score and return the keys in order. */
+    private sortByScore;
+}

package/dist/core/knowledge/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Knowledge Module - Barrel Export
+ *
+ * Re-exports all knowledge graph modules (Phase 1-7)
+ * for clean module boundary access from the rest of the framework.
+ */
+export { TagIndexer } from "./tag-indexer.js";
+export type { FrontmatterData } from "./tag-indexer.js";
+export { GraphParser } from "./graph-parser.js";
+export { HybridSearch } from "./hybrid-search.js";
+export type { SearchResult } from "./hybrid-search.js";
+export { Scratchpad } from "./scratchpad.js";
+export { SafetyGuards } from "./safety-guards.js";
+export type { WriteQueue } from "./safety-guards.js";
+export { MemoryConsolidation } from "./memory-consolidation.js";

package/dist/core/knowledge/memory-consolidation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MemoryConsolidation - Pure analysis functions for knowledge-graph maintenance.
+ * All methods are side-effect-free: they read from indexes but never mutate state or files.
+ */
+import type { TagIndexer } from "./tag-indexer.js";
+import type { GraphParser } from "./graph-parser.js";
+export declare class MemoryConsolidation {
+    private readonly tagIndexer;
+    private readonly graphParser;
+    constructor(tagIndexer: TagIndexer, graphParser: GraphParser);
+    /**
+     * Find notes whose content exceeds the line-count ceiling.
+     * These are candidates for splitting to improve navigability.
+     */
+    identifyOversizedNotes(contentMap: Map<string, string>, maxLines?: number): string[];
+    /**
+     * Find notes that have zero forward links AND zero backlinks.
+     * Orphan notes are disconnected from the graph and may need linking or removal.
+     */
+    identifyOrphanNotes(allNotes: string[]): string[];
+    /**
+     * Find pairs of notes sharing enough tags to warrant merging.
+     * Uses TagIndexer.getAllTags() and getFilesWithTag() to build the full picture.
+     */
+    suggestMerges(threshold?: number): Array<[string, string]>;
+    /**
+     * Generate a Map of Content markdown listing all notes tagged with the given tag.
+     * MOCs serve as navigational hubs in the knowledge graph.
+     */
+    generateMOC(tag: string): string;
+    /**
+     * Build a lookup from note name to its set of tags by iterating
+     * all known tags in the index and collecting their associated files.
+     */
+    private buildNoteTagMap;
+    /** Count how many tags two sets share. */
+    private countSharedTags;
+}

package/dist/core/knowledge/safety-guards.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SafetyGuards - Graph integrity checks and concurrency primitives.
+ * Protects knowledge-graph mutations from cycles, races, and accidental deletes.
+ */
+import type { GraphParser } from "./graph-parser.js";
+import type { FrontmatterData } from "./tag-indexer.js";
+/**
+ * FIFO async write queue that serializes concurrent write operations
+ * to prevent data corruption from overlapping file mutations.
+ */
+export interface WriteQueue {
+    /** Enqueue a write operation; resolves when the operation completes. */
+    enqueue(fn: () => Promise<void>): Promise<void>;
+    /** Wait for all queued operations to finish. */
+    drain(): Promise<void>;
+}
+export declare class SafetyGuards {
+    /**
+     * Detect circular links from a starting note via depth-limited DFS.
+     * Returns true if the start note is reachable from itself within maxDepth hops.
+     */
+    static checkCircularLinks(graph: GraphParser, startNote: string, maxDepth?: number): boolean;
+    /**
+     * Create a FIFO write queue that ensures only one write runs at a time.
+     * Each enqueued function waits for all prior functions to complete first.
+     */
+    static createWriteQueue(): WriteQueue;
+    /**
+     * Check whether a note's frontmatter marks it as pinned (keep: true).
+     * Pinned notes should be excluded from pruning and consolidation.
+     */
+    static isPinned(metadata: FrontmatterData): boolean;
+    /**
+     * Recursive DFS that returns true when the start note is revisited.
+     * Bounded by maxDepth to prevent runaway traversal in dense graphs.
+     * Always checks direct neighbors for the start note before applying depth limit.
+     */
+    private static dfsDetectCycle;
+}

package/dist/core/knowledge/scratchpad.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Scratchpad - Volatile key-value register cache for agent working memory.
+ * Implements LRU eviction and markdown-based serialization for persistence.
+ */
+export declare class Scratchpad {
+    /**
+     * Ordered map where the most-recently-accessed key moves to the end.
+     * Eviction removes from the beginning (least recently used).
+     */
+    private registers;
+    /**
+     * Store a value, evicting the least-recently-used entry if at capacity.
+     * Values exceeding 4 KB are truncated to enforce size constraints.
+     */
+    set(key: string, value: string): void;
+    /**
+     * Retrieve a register value, refreshing its LRU position on access.
+     */
+    get(key: string): string | undefined;
+    /** Return a snapshot copy of all registers. */
+    getAll(): Map<string, string>;
+    /** Remove a specific register entry. */
+    delete(key: string): boolean;
+    /** Wipe all register entries. */
+    clear(): void;
+    /**
+     * Export all registers as a markdown document for persistence.
+     * Each register becomes a level-2 heading with its value as content.
+     */
+    serialize(): string;
+    /**
+     * Import registers from a previously serialized markdown document.
+     * Clears existing state before importing to ensure idempotent loads.
+     */
+    deserialize(content: string): void;
+    /** Evict the least-recently-used entry (first key in insertion order). */
+    private evictLru;
+}

package/dist/core/knowledge/tag-indexer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Interface representing standard Obsidian-style Frontmatter metadata.
+ */
+export interface FrontmatterData {
+    tags?: string[];
+    title?: string;
+    keep?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Metadata extractor with regular expression fallback when standard parser crashes.
+ */
+export declare class TagIndexer {
+    private tagMap;
+    private fileCache;
+    /**
+     * Parse frontmatter using regular expressions as a primary safe parser.
+     * This avoids library dependencies and provides deterministic error recovery.
+     */
+    parseFrontmatter(content: string): {
+        data: FrontmatterData;
+        body: string;
+    };
+    /**
+     * Parse a single YAML line and update data object in-place.
+     * Returns the currently active key for block list continuation.
+     */
+    private parseYamlLine;
+    /**
+     * Index a single markdown file content dynamically.
+     */
+    indexFile(filePath: string, fileContent: string): void;
+    /**
+     * Index a file directly from the filesystem.
+     */
+    indexFileFromDisk(filePath: string): void;
+    /**
+     * Get all files associated with a specific tag O(1).
+     */
+    getFilesWithTag(tag: string): Set<string>;
+    /**
+     * Get intersection of files containing all specified tags.
+     */
+    getFilesWithAllTags(tags: string[]): Set<string>;
+    /**
+     * Get union of files containing any of the specified tags.
+     */
+    getFilesWithAnyTags(tags: string[]): Set<string>;
+    /**
+     * Get the cached frontmatter metadata of a file.
+     */
+    getMetadata(filePath: string): FrontmatterData | undefined;
+    /**
+     * Return all file paths that have been indexed.
+     */
+    getIndexedFiles(): string[];
+    /**
+     * Return all distinct tags currently present across all indexed files.
+     */
+    getAllTags(): string[];
+    /**
+     * Remove file references cleanly from tag mappings and metadata cache.
+     */
+    private clearIndexForFile;
+    /**
+     * Helper to insert tags atomically.
+     */
+    private addTagEntry;
+    /**
+     * Basic scalar value parser for YAML frontmatter fields.
+     */
+    private parseScalar;
+}