cognitive-core 0.1.0 → 0.1.2

package/dist/memory/knowledge-bank.d.ts

@@ -0,0 +1,220 @@
+import type { KnowledgeNote, KnowledgeMatch, KnowledgeStats, EntityUpdate, Contradiction, ExtractedKnowledge, InboxResult, DefragResult, DecayResult, GraphLayerName, PlaybookLink } from '../types/knowledge.js';
+import type { Trajectory } from '../types/index.js';
+import type { TrajectorySource } from '../types/trajectory-source.js';
+import type { KnowledgeBankConfig } from '../types/config.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+import type { TrajectoryAnalyzer, AnalysisResult } from '../learning/analyzer.js';
+import { KnowledgeGraphManager } from './knowledge-graph.js';
+import type { SearchProvider } from './search-provider.js';
+/**
+ * KnowledgeBank — Semantic memory store for facts, concepts, and relationships.
+ *
+ * Uses the filesystem as the universal primary index (minimem-compatible).
+ * Maintains a multi-layer graph overlay as a derived index for relationship queries.
+ *
+ * Directory structure:
+ *   {memoryDir}/
+ *     knowledge/
+ *       observations/   — atomic facts (k-*.md)
+ *       entities/       — living entity docs ({entity}.md)
+ *       domains/        — domain summaries ({domain}.md)
+ *     inbox/            — unorganized agent-authored notes
+ *     .knowledge/       — derived index files (graph, manifest)
+ */
+export declare class KnowledgeBank {
+    readonly graph: KnowledgeGraphManager;
+    private memoryDir;
+    private readonly bankConfig;
+    private initialized;
+    private searchProvider;
+    private observationsDir;
+    private entitiesDir;
+    private domainsDir;
+    private inboxDir;
+    private indexDir;
+    constructor(memoryDir: string, config: KnowledgeBankConfig);
+    init(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Create a new knowledge note and write it to disk.
+     * Updates the graph overlay in memory.
+     */
+    addObservation(note: KnowledgeNote): Promise<string>;
+    /**
+     * Update an existing entity note by appending a section.
+     */
+    updateEntity(entityId: string, update: EntityUpdate): Promise<void>;
+    /**
+     * Get a note by ID. Scans all directories.
+     */
+    getNote(id: string): Promise<KnowledgeNote | null>;
+    /**
+     * Get an entity note by entity name.
+     */
+    getEntity(entityName: string): Promise<KnowledgeNote | null>;
+    /**
+     * Get a domain summary by domain name.
+     */
+    getDomainSummary(domain: string): Promise<KnowledgeNote | null>;
+    /**
+     * List all known entity names (from entity note filenames).
+     */
+    listEntities(): Promise<string[]>;
+    /**
+     * List all known domain names (from domain summary filenames).
+     */
+    listDomains(): Promise<string[]>;
+    /**
+     * Get all notes across all directories.
+     */
+    getAllNotes(): Promise<KnowledgeNote[]>;
+    /**
+     * Get related notes via multi-layer graph traversal.
+     */
+    getRelated(noteId: string, options?: {
+        depth?: number;
+        layers?: GraphLayerName[];
+        minWeight?: number;
+    }): Promise<KnowledgeMatch[]>;
+    /**
+     * Get cross-system links to playbooks.
+     */
+    getPlaybookLinks(noteId: string): Promise<PlaybookLink[]>;
+    getStats(): Promise<KnowledgeStats>;
+    /**
+     * Search knowledge notes by text similarity.
+     * Scores against note ID + body using Jaccard + n-gram similarity.
+     */
+    search(query: string, options?: {
+        domains?: string[];
+        maxResults?: number;
+    }): Promise<KnowledgeMatch[]>;
+    /**
+     * Get relevant knowledge for a task using 3-tier retrieval:
+     * 1. Domain summary match
+     * 2. Entity name match in task description
+     * 3. Semantic text similarity search
+     */
+    getRelevantKnowledge(task: {
+        description: string;
+        domain?: string;
+    }, options?: {
+        maxNotes?: number;
+        maxTokens?: number;
+        layers?: GraphLayerName[];
+    }): Promise<KnowledgeMatch[]>;
+    /**
+     * Process inbox files: classify, move to correct directory, add to graph.
+     * Files with valid frontmatter are classified by type field.
+     * Files without valid frontmatter get heuristic classification as observations.
+     */
+    processInbox(): Promise<InboxResult>;
+    /**
+     * Run the full 7-step defragmentation cycle via KnowledgeDefragmenter.
+     */
+    defragment(): Promise<DefragResult>;
+    applyExtraction(extraction: ExtractedKnowledge): Promise<void>;
+    /**
+     * Reinforce a knowledge note with new evidence from a trajectory.
+     * Uses EMA to increase confidence: newConf = (1 - alpha) * oldConf + alpha * 1.0
+     */
+    reinforce(noteId: string, trajectoryId: string): Promise<void>;
+    recordContradiction(contradiction: Contradiction): Promise<void>;
+    /**
+     * Apply time-based confidence decay to all knowledge notes.
+     * Skips domain summaries, notes already tagged stale, and notes within the grace period.
+     */
+    applyDecay(): Promise<DecayResult>;
+    /**
+     * Extract knowledge from a trajectory source.
+     * Iterates all trajectories, runs extraction (agent or heuristic), and applies results.
+     */
+    extractFrom(source: TrajectorySource, options?: {
+        taskRunner?: AgenticTaskRunner;
+        analyzer?: TrajectoryAnalyzer;
+    }): Promise<ExtractedKnowledge[]>;
+    /**
+     * Extract knowledge from a single trajectory.
+     * Uses the workspace template if a taskRunner is provided, otherwise falls back to heuristic.
+     * Applies the extraction to the knowledge bank.
+     */
+    extractFromTrajectory(trajectory: Trajectory, analysis?: AnalysisResult, taskRunner?: AgenticTaskRunner): Promise<ExtractedKnowledge>;
+    /**
+     * Format knowledge notes as a markdown section for agent prompt injection.
+     * Groups by type: domain summaries → entities → observations.
+     */
+    formatKnowledgeForPrompt(notes: KnowledgeMatch[], options?: {
+        maxTokens?: number;
+        includeEvidence?: boolean;
+        includeLinks?: boolean;
+    }): string;
+    /**
+     * Get the name of the active search provider.
+     */
+    getSearchProviderName(): string;
+    /**
+     * Replace the active search provider (strategy pattern).
+     */
+    setSearchProvider(provider: SearchProvider): void;
+    /**
+     * Detect whether minimem is available and set up the MinimemSearchProvider.
+     *
+     * Detection checks (in order):
+     * 1. Look for a `.minimem/` directory under memoryDir
+     * 2. Look for a `MEMORY.md` file under memoryDir
+     * 3. Create a Minimem instance and wire MinimemSearchProvider
+     *
+     * Falls back to TextSimilaritySearchProvider on any failure.
+     */
+    private detectMinimem;
+    /**
+     * Get the index directory path (for defragmenter).
+     */
+    getIndexDir(): string;
+    /**
+     * Check if defragmentation should be triggered.
+     */
+    shouldDefragment(): Promise<boolean>;
+    /**
+     * Resolve a note's file path and write it to disk.
+     */
+    private writeNote;
+    /**
+     * Scan a directory for .md files and parse them as KnowledgeNotes.
+     * Skips files with invalid/missing frontmatter.
+     */
+    private scanDirectory;
+    /**
+     * Count .md files in a directory.
+     */
+    private countFiles;
+    /**
+     * Resolve the relative path for a note based on its type and filename.
+     * When minimemAware, paths are nested under memory/knowledge/ instead of knowledge/.
+     */
+    private resolveNotePath;
+    /**
+     * Move an inbox note to the correct directory based on its type.
+     * Updates the note's filePath accordingly.
+     */
+    private moveInboxNote;
+    /**
+     * Create a KnowledgeNote from a raw inbox file with no valid frontmatter.
+     * Applies heuristic: observation type, agent-authored origin, agentAuthoredInitial confidence.
+     */
+    private processRawInboxFile;
+    /**
+     * Convert a KnowledgeNote to a GraphNode.
+     */
+    /**
+     * Enforce a token budget on a list of matches.
+     * Always includes at least one match.
+     */
+    private enforceTokenBudget;
+    /**
+     * Format a single knowledge note for prompt injection.
+     */
+    private formatSingleNote;
+    private noteToGraphNode;
+}
+//# sourceMappingURL=knowledge-bank.d.ts.map

package/dist/memory/knowledge-bank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-bank.d.ts","sourceRoot":"","sources":["../../src/memory/knowledge-bank.ts"],"names":[],"mappings":"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"}