bilmem 0.1.0

package/dist/types-Nxq5Gzay.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Core type definitions for bilmem:
+ * A lightweight, language-independent knowledge and learning runtime for AI agents.
+ */
+type Scope = 'global' | 'user' | 'organization' | 'project' | string;
+type KnowledgeType = 'lesson' | 'fact' | 'decision' | 'convention' | 'rule' | 'architecture' | 'question' | 'failure' | 'heuristic';
+type KnowledgeStatus = 'active' | 'candidate' | 'probation' | 'needs_revalidation' | 'stale' | 'contradicted' | 'superseded' | 'invalid' | 'invalidated';
+type KnowledgeStage = 'candidate' | 'probation' | 'active';
+type ConfidenceTier = 'low' | 'medium' | 'high';
+interface Provenance {
+    type: 'code' | 'doc' | 'git' | 'user' | 'agent' | 'test' | 'file';
+    path?: string;
+    line?: number;
+    commit?: string;
+    author?: string;
+    timestamp: string;
+    contentHash?: string;
+    uri?: string;
+}
+/**
+ * An observation made from a source file, commit, agent attempt, or user correction.
+ */
+interface Observation {
+    id: string;
+    source: string;
+    claim: string;
+    provenance: Provenance;
+    confidence: number;
+    positive?: string[];
+    negative?: string[];
+    details?: Record<string, unknown>;
+    recordedAt: string;
+}
+/**
+ * Evidence node supporting or contradicting claims.
+ * Underlying source identity ensures multiple agents reading the same source
+ * do NOT count as independent evidence.
+ */
+interface Evidence {
+    id: string;
+    source: string;
+    sourceHash: string;
+    observationIds: string[];
+    type: 'supports' | 'contradicts' | 'observes';
+    claim: string;
+    provenance: Provenance;
+    weight: number;
+    firstObservedAt: string;
+    lastObservedAt: string;
+}
+type RelationType = 'IMPORTS' | 'DEFINES' | 'REFERENCES' | 'CALLS' | 'TESTS' | 'DOCUMENTS' | 'SUPPORTS' | 'CONTRADICTS' | 'SPECIALIZES' | 'SUPERSEDES' | 'DEPENDS_ON' | 'CO_CHANGED' | 'MOVED';
+interface EvidenceRelation {
+    from: string;
+    to: string;
+    type: RelationType;
+    weight?: number;
+    metadata?: Record<string, unknown>;
+}
+interface TemporalMetadata {
+    revision: number;
+    valid_from?: {
+        commit?: string;
+        timestamp?: string;
+    };
+    valid_until?: {
+        commit?: string;
+        timestamp?: string;
+    };
+    supersedes?: string[];
+}
+interface KnowledgeMetrics {
+    reuse_count: number;
+    last_used?: string;
+    support_count: number;
+    contradiction_count: number;
+    successful_outcomes: number;
+    failed_outcomes: number;
+}
+interface KnowledgeHistoryEntry {
+    timestamp: string;
+    stage?: KnowledgeStage;
+    status: KnowledgeStatus;
+    action?: string;
+    reason?: string;
+    evidenceId?: string;
+    source?: string;
+}
+interface KnowledgeOutcomesSummary {
+    applied: number;
+    successful: number;
+    misleading: number;
+    neutral: number;
+}
+/**
+ * Reusable conclusion supported by evidence.
+ */
+interface Knowledge {
+    id: string;
+    type: KnowledgeType;
+    status: KnowledgeStatus;
+    stage?: KnowledgeStage;
+    statement: string;
+    positive: string[];
+    negative: string[];
+    relations: string[];
+    confidence: number;
+    confidenceTier?: ConfidenceTier;
+    evidence: string[];
+    depends_on?: string[];
+    resolves?: string[];
+    question?: string;
+    scope: Scope;
+    tags?: string[];
+    temporal?: TemporalMetadata;
+    metrics: KnowledgeMetrics;
+    outcomesSummary?: KnowledgeOutcomesSummary;
+    history?: KnowledgeHistoryEntry[];
+    value?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Epistemic Resolution Types.
+ */
+type ResolutionState = 'KNOWN' | 'PARTIALLY_KNOWN' | 'UNKNOWN' | 'CONFLICTED' | 'STALE';
+type ResolutionReason = 'NOT_OBSERVED' | 'INSUFFICIENT_EVIDENCE' | 'CONFLICTING_EVIDENCE' | 'STALE_EVIDENCE' | 'UNRESOLVABLE_LOCALLY' | 'CONTEXT_MISMATCH';
+type ActionType = 'USE_KNOWLEDGE' | 'INSPECT_FILE' | 'INSPECT_SYMBOL' | 'INSPECT_TEST' | 'SEARCH_REPOSITORY' | 'CHECK_GIT' | 'CHECK_DOCUMENTATION' | 'ASK_USER' | 'STOP';
+interface NextEvidenceAction {
+    type: ActionType;
+    target?: string;
+    reason: string;
+    relativeCost?: number;
+    expectedInfoGain?: number;
+}
+interface InvestigationReceipt {
+    id: string;
+    question: string;
+    checked: string[];
+    findings: string[];
+    rejected: Array<{
+        target: string;
+        reason: string;
+    }>;
+    missing: string[];
+    next?: NextEvidenceAction;
+    status: 'resolved' | 'unresolved';
+    timestamp: string;
+    gitCommit?: string;
+    positive?: string[];
+    negative?: string[];
+}
+interface ResolveOptions {
+    question: string;
+    positive?: string[];
+    negative?: string[];
+    scope?: Scope;
+    limit?: number;
+    maxDepth?: number;
+}
+interface ResolutionResult {
+    state: ResolutionState;
+    reason?: ResolutionReason;
+    known: Array<{
+        id: string;
+        statement: string;
+        confidence: number | string;
+        confidenceTier?: ConfidenceTier;
+        stage?: KnowledgeStage;
+    }>;
+    applicable: string[];
+    rejected: Array<{
+        id: string;
+        reason: string;
+    }>;
+    missing: string[];
+    checked: string[];
+    next?: NextEvidenceAction;
+    fallback?: {
+        type: 'ask' | 'inspect';
+        question?: string;
+        target?: string;
+    };
+    receiptId?: string;
+}
+/**
+ * First-class Unknown representation.
+ */
+type UnknownState = 'KNOWN' | 'PARTIALLY_KNOWN' | 'UNKNOWN' | 'STALE' | 'CONFLICTED';
+type UnknownReason = 'NOT_OBSERVED' | 'INSUFFICIENT_EVIDENCE' | 'CONFLICTING_EVIDENCE' | 'STALE' | 'UNRESOLVABLE_LOCALLY';
+interface UnknownNextAction {
+    type: 'ask' | 'inspect' | 'verify' | 'test';
+    question?: string;
+    suggestedAction?: string;
+}
+interface UnknownRecord {
+    id: string;
+    state: UnknownState;
+    reason?: UnknownReason;
+    statement?: string;
+    checked: string[];
+    next?: UnknownNextAction;
+    scope: Scope;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Outcome recording whether knowledge application helped or failed.
+ */
+type OutcomeType = 'success' | 'failure' | 'reverted' | 'neutral';
+interface OutcomeRecord {
+    id: string;
+    knowledgeId?: string;
+    taskId?: string;
+    result: OutcomeType;
+    context?: {
+        positive?: string[];
+        negative?: string[];
+    };
+    feedback?: string;
+    timestamp: string;
+}
+/**
+ * Smart knowledge growth classification actions.
+ */
+type ReconciliationAction = 'NEW' | 'MERGE' | 'UPDATE' | 'SUPPORT' | 'CONTRADICT' | 'SPECIALIZE' | 'GENERALIZE' | 'IGNORE';
+interface ReconciliationResult {
+    action: ReconciliationAction;
+    targetId?: string;
+    knowledge?: Knowledge;
+    reason: string;
+    score?: number;
+}
+/**
+ * Agent task trajectory event.
+ */
+type TrajectoryEventType = 'search' | 'read' | 'hypothesis' | 'attempt' | 'edit' | 'test' | 'failure' | 'revert' | 'success' | 'ask_user' | 'user_correction';
+interface TrajectoryEvent {
+    type: TrajectoryEventType;
+    description: string;
+    path?: string;
+    data?: Record<string, unknown>;
+    timestamp?: string;
+}
+interface TaskTrajectory {
+    taskId: string;
+    goal: string;
+    events: TrajectoryEvent[];
+    startedAt: string;
+    completedAt?: string;
+    finalOutcome?: OutcomeType;
+}
+/**
+ * JEV Matching Result.
+ */
+type JevMatchStatus = 'MATCH' | 'POSSIBLE' | 'REJECT';
+interface JevExplanation {
+    positiveMatches: string[];
+    negativeConflicts: string[];
+    score: number;
+    confidence: number;
+    status: JevMatchStatus;
+    reasons: string[];
+}
+interface JevResult {
+    knowledge: Knowledge;
+    status: JevMatchStatus;
+    score: number;
+    explanation: JevExplanation;
+}
+interface KnowledgeBudgetConfig {
+    active?: number;
+    maxCandidates?: number;
+}
+/**
+ * Global Bilmem Configuration.
+ */
+interface BilmemConfig {
+    schemaVersion: number;
+    projectName: string;
+    defaultScope: Scope;
+    lastScanCommit?: string;
+    lastScanTimestamp?: string;
+    dataDir: string;
+    knowledge?: {
+        budget?: KnowledgeBudgetConfig;
+    };
+}
+/**
+ * Aggregated metrics tracked by bilmem.
+ */
+interface BilmemMetrics {
+    knowledgeHits: number;
+    knowledgeMisses: number;
+    knowledgeReused: number;
+    unknownsResolved: number;
+    repeatedInvestigationsPrevented: number;
+    candidateKnowledgeMerged: number;
+    staleKnowledgeDetected: number;
+    contradictionsDetected: number;
+    knowledgePromoted: number;
+    knowledgeSuperseded: number;
+}
+/**
+ * Conditions evaluated by the rule engine during scanning.
+ */
+interface RuleCondition {
+    has_file?: string | string[];
+    missing_file?: string | string[];
+    any_file?: string[];
+    file_pattern?: string;
+    content_match?: {
+        files?: string;
+        pattern: string;
+    };
+}
+/**
+ * Definition of a single rule in a RuleSet.
+ */
+interface RuleDefinition {
+    id: string;
+    name?: string;
+    statement: string;
+    type?: KnowledgeType;
+    confidence?: number;
+    scope?: Scope;
+    positive?: string[];
+    negative?: string[];
+    when?: RuleCondition;
+    details?: Record<string, unknown>;
+    tags?: string[];
+}
+/**
+ * A bundle of rules defined in a YAML file.
+ */
+interface RuleSet {
+    name?: string;
+    version?: number | string;
+    scope?: Scope;
+    description?: string;
+    rules: RuleDefinition[];
+}
+/**
+ * Result of evaluating a rule against repository context.
+ */
+interface EvaluatedRule {
+    rule: RuleDefinition;
+    matched: boolean;
+    reason?: string;
+    matchedFiles?: string[];
+}
+/**
+ * Summary diff representing incremental learning changes.
+ */
+interface KnowledgeDiff {
+    sinceRef?: string;
+    observationsAdded: number;
+    candidatesAdded: number;
+    strengthenedCount: number;
+    revisedCount: number;
+    contradictionCount: number;
+    unknownsCount?: number;
+    needsRevalidationCount?: number;
+    invalidatedCount: number;
+    details?: {
+        strengthened?: string[];
+        revised?: string[];
+        contradictions?: string[];
+        unknowns?: string[];
+        needsRevalidation?: string[];
+        invalidated?: string[];
+    };
+}
+/**
+ * Point-in-time snapshot of repository knowledge state.
+ */
+interface RevisionSnapshot {
+    id: string;
+    commit?: string;
+    timestamp: string;
+    action: 'scan' | 'learn' | 'compact' | 'init' | string;
+    observationCount: number;
+    evidenceCount: number;
+    knowledgeCount: number;
+    activeCount: number;
+    contradictedCount: number;
+    staleCount: number;
+    changesSummary?: string;
+}
+
+export type { ActionType as A, BilmemConfig as B, ConfidenceTier as C, TrajectoryEvent as D, EvaluatedRule as E, TrajectoryEventType as F, UnknownNextAction as G, UnknownReason as H, InvestigationReceipt as I, JevResult as J, Knowledge as K, UnknownState as L, NextEvidenceAction as N, OutcomeType as O, Provenance as P, ResolveOptions as R, Scope as S, TaskTrajectory as T, UnknownRecord as U, ResolutionResult as a, BilmemMetrics as b, Evidence as c, EvidenceRelation as d, JevExplanation as e, JevMatchStatus as f, KnowledgeBudgetConfig as g, KnowledgeDiff as h, KnowledgeHistoryEntry as i, KnowledgeMetrics as j, KnowledgeOutcomesSummary as k, KnowledgeStage as l, KnowledgeStatus as m, KnowledgeType as n, Observation as o, OutcomeRecord as p, ReconciliationAction as q, ReconciliationResult as r, RelationType as s, ResolutionReason as t, ResolutionState as u, RevisionSnapshot as v, RuleCondition as w, RuleDefinition as x, RuleSet as y, TemporalMetadata as z };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "bilmem",
+  "version": "0.1.0",
+  "description": "Lightweight, language-independent knowledge and learning runtime for AI agents and developer tooling",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "bilmem": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./jev": {
+      "types": "./dist/jev/index.d.ts",
+      "import": "./dist/jev/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./scanner": {
+      "types": "./dist/scanner/index.d.ts",
+      "import": "./dist/scanner/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    },
+    "./install": {
+      "types": "./dist/install/index.d.ts",
+      "import": "./dist/install/index.js"
+    },
+    "./stats": {
+      "types": "./dist/stats/index.d.ts",
+      "import": "./dist/stats/index.js"
+    }
+  },
+  "scripts": {
+    "prebuild": "npm run typecheck",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@orama/orama": "^3.1.18",
+    "commander": "^13.1.0",
+    "mcponce": "^0.2.3",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.22.6",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.19",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  }
+}