bilmem 0.1.0

package/README.md

@@ -0,0 +1,439 @@
+# bilmem
+
+> **`bilmem` is a lightweight, language-independent knowledge and learning runtime for AI agents and developer tooling.**
+
+Its purpose is **NOT** to constantly intercept an agent, monitor every prompt, or act as another autonomous agent.
+
+Its purpose is to help an agent:
+
+- **reuse knowledge** it already has,
+- **recognize when existing knowledge does not apply** through negative contextual cues,
+- **explicitly represent uncertainty** and first-class unknowns,
+- **avoid repeating previously useless investigations**,
+- **learn from successful and failed work**,
+- **refine existing knowledge** instead of endlessly accumulating memories,
+- **ask for clarification** when local evidence is insufficient,
+- **share, import, and export knowledge** in a portable format.
+
+### Core Epistemic Philosophy
+
+Bilmem differs fundamentally from repository graphs, vector databases, and memory dumps:
+- Traditional repository tools primarily ask: **"What is related to X?"**
+- Traditional memory systems primarily ask: **"What did we previously store about X?"**
+- **Bilmem asks:**
+
+> **"Do I know enough to act, what do I know does not apply, what am I missing, and what is the cheapest next step to resolve the uncertainty?"**
+
+Bilmem is a lightweight **epistemic runtime**.
+
+### Guiding Principles
+
+> **Memory should grow by refinement, not accumulation.**
+
+> **Bilmem should be cheaper than not knowing.**
+
+> **Prefer the smallest action likely to resolve the uncertainty.**
+
+## Architecture Overview
+
+```text
+Sources (Filesystem, Structured Markdown, Git, Agent Trajectories, User Corrections)
+                     │
+                     ▼
+                Observations
+                     │
+                     ▼
+               Evidence Graph (IMPORTS, REFERENCES, CO_CHANGED, etc.)
+                     │
+                     ▼
+          Candidate Extraction & Smart Reconciliation
+          (NEW, MERGE, UPDATE, SUPPORT, CONTRADICT, SPECIALIZE, IGNORE)
+                     │
+                     ▼
+            Storage (.bilmem/)
+                     │
+         ┌───────────┴───────────┐
+         ▼                       ▼
+     Search Index          Portable YAML
+    (Rebuildable)      (import/export/dump/restore)
+         │
+    Query / Context
+         │
+   Candidate Retrieval (top candidates)
+         │
+    JEV Contextual Reranking (positive & negative proximity)
+         │
+ MATCH / POSSIBLE / REJECT with Explanations
+```
+
+---
+
+## Core Concepts
+
+### 1. Observation & Provenance
+Something observed directly from a source with verifiable provenance (file path, line, git commit/revision, content hash). `author` is optional and non-essential for truth verification; cryptographic content and revision hashes establish deterministic provenance.
+
+### 2. Evidence
+One or more observations supporting or contradicting a claim. Multiple agents reading the same source do **not** count as independent evidence; evidence identity is derived from deterministic source hashing.
+
+### 3. Knowledge & Honest Confidence Model
+A reusable conclusion supported by evidence:
+```yaml
+id: auth.session.refresh-order
+type: lesson
+status: active
+statement: Refresh token validation happens before session renewal.
+positive:
+  - expired-session
+  - refresh-token
+  - server-session
+negative:
+  - stateless-jwt
+confidenceTier: high
+confidence: 0.95
+evidence:
+  - code:src/auth/session.ts
+  - git:81ac23
+```
+To avoid deceptive artificial precision (e.g. `0.91`), `bilmem` uses transparent, explainable confidence tiers backed by deterministic evidence scoring:
+- `high` (0.95): Explicit human correction, accepted ADR, or repeatedly verified outcome.
+- `medium` (0.75): Confirmed test pass, documented code pattern, or supported rule.
+- `low` (0.50): Heuristic observation or candidate lesson awaiting verification.
+
+### 4. First-Class Unknowns
+`bilmem` treats unknown states as first-class citizens (`KNOWN`, `PARTIALLY_KNOWN`, `UNKNOWN`, `STALE`, `CONFLICTED`) with actionable reasons (`NOT_OBSERVED`, `INSUFFICIENT_EVIDENCE`, `CONFLICTING_EVIDENCE`, `STALE`, `UNRESOLVABLE_LOCALLY`).
+```yaml
+id: project.database.migration
+state: unknown
+reason: UNRESOLVABLE_LOCALLY
+checked:
+  - package.json
+  - src/db/**
+  - scripts/**
+next:
+  type: ask
+  question: How are database migrations performed in this project?
+```
+This directly prevents future agents from repeating the same failed investigation.
+
+### 5. JEV Contextual Matching
+Retrieval is not just fuzzy similarity. JEV calculates:
+- Positive cue overlap
+- Hard negative conflicts (immediate rejection when forbidden patterns are present)
+- Scope alignment (exact, parent, global)
+- Effective confidence (dampened by contradiction ratios and outcome history)
+- Inspectable decision explanations (`MATCH`, `POSSIBLE`, `REJECT`)
+
+### 6. Contradiction Precedes Merge & Smart Growth
+Lexical similarity alone **never** justifies merging. Opposing assertions (e.g., `cache enabled in production` vs `cache disabled in production`) have high token overlap but polar opposite meaning. Polarity and negative checks evaluate **strictly before** any merge decision:
+- `CONTRADICT`: Directly conflicts or asserts opposing polarity; flags status or lowers confidence.
+- `SPECIALIZE`: Contextual divergence (e.g. SQLite for dev vs PostgreSQL for prod) creates sub-context branches.
+- `MERGE`: Highly similar non-contradictory statement; consolidates evidence and cues.
+- `NEW`: No related knowledge exists.
+- `UPDATE`: Refines or updates existing knowledge statement.
+- `SUPPORT`: Confirms existing knowledge with new evidence source, increasing confidence.
+- `IGNORE`: Duplicate observation from already-known source with no new information.
+
+### 7. Staged Trajectory Learning Pipeline
+`bilmem learn` adheres to a strict multi-stage lifecycle:
+```text
+trajectory → observations → candidate lessons → reconcile → knowledge
+```
+Raw trajectories are never dumped directly into permanent knowledge. Each trajectory step produces traceable `Observation` and `Evidence` nodes. Reusable candidate lessons are extracted and reconciled with existing knowledge before any persistence occurs.
+
+### 8. Conservative Scanning ("Ederinden Fazlasını Vaat Etmeme")
+A repository scan is not forced to manufacture knowledge out of thin air. The primary, deterministic output of `bilmem scan` is **Observation & Evidence**. Speculative or loose file signals remain observations; only explicit rule sets, accepted ADRs, and verified git reverts become candidate lessons.
+
+---
+
+## Storage Architecture
+
+Inside `.bilmem/`, the source-of-truth is stored in **append-friendly JSONL** files:
+
+```text
+.bilmem/
+├── knowledge.jsonl     # Canonical append-log of knowledge units
+├── evidence.jsonl      # Canonical append-log of evidence nodes
+├── observations.jsonl  # Signal observations with cryptographic hashes
+├── unknowns.jsonl      # First-class unknowns and unresolvable questions
+├── outcomes.jsonl      # Task feedback and outcome records
+├── revisions.jsonl     # Point-in-time snapshot log for diff tracking
+├── rules/              # Declarative YAML rule sets (.bilmem/rules/*.yml)
+├── index/              # Ephemeral, 100% rebuildable search index
+├── config.json         # Project configuration and scan checkpoints
+└── metrics.json        # Reuse, miss, and prevention telemetry
+```
+
+- **JSONL for internal source-of-truth**: Fast streaming, append-friendly writes, and git-diff friendly log lines.
+- **YAML for interchange & rules**: Human-edited rule sets (`.bilmem/rules/*.yml`) and portable sharing (`bilmem export`, `bilmem dump`).
+- **Rebuildable Index**: The search index in `.bilmem/index/` is completely rebuildable from `.bilmem/knowledge.jsonl` at any time.
+
+---
+
+## CLI Commands
+
+```bash
+# Primary Epistemic Operation: Do I know enough to act, what is missing, cheapest next action?
+bilmem resolve "How are sessions renewed?" -p server-session -n stateless-jwt
+
+# Lookup knowledge using candidate retrieval + JEV contextual reranker
+bilmem lookup "refresh session" -p expired-session refresh-token
+
+# Explain why a knowledge unit exists or inspect its full lifecycle history
+bilmem why auth.session.refresh-order
+bilmem why auth.session.refresh-order --history
+
+# Initialize bilmem in current directory
+bilmem init [path]
+
+# Scan filesystem conventions, structured markdown, and git history
+bilmem scan [path] [--incremental] [--dry-run]
+
+# Inspect incremental learning and revision diffs
+bilmem diff [sinceRef]
+
+# Learn from an agent trajectory JSON via the staged pipeline
+bilmem learn trajectory.json [--dry-run]
+
+# List active knowledge items
+bilmem known [--scope <scope>] [--status <status>]
+
+# List first-class unknowns and unresolvable items
+bilmem unknown
+
+# Manage declarative YAML rule sets and guardrails
+bilmem rules list
+bilmem rule add "Use Vitest for testing" --when-file vite.config.ts
+
+# Smart import with reconciliation
+bilmem import knowledge.yml
+bilmem import ./rules/
+
+# Export active knowledge to YAML
+bilmem export [--scope <scope>] [-o output.yml]
+
+# Complete snapshot backup and deterministic restore
+bilmem dump snapshot.yml
+bilmem restore snapshot.yml
+
+# Compact knowledge base (merge duplicates, clean stale observations)
+bilmem compact [--dry-run]
+
+# Status summary & metrics
+bilmem status
+```
+
+### Primary Operation: `bilmem resolve`
+
+Unlike search or lookup, `resolve` executes an epistemic evaluation:
+
+```bash
+$ bilmem resolve "How are sessions renewed?" -p server-session -n stateless-jwt
+```
+
+Structured output:
+```yaml
+state: PARTIALLY_KNOWN
+
+known:
+  - id: auth.refresh-token
+    confidence: high
+
+applicable:
+  - server-session
+
+rejected:
+  - id: auth.jwt-refresh
+    reason: stateless-jwt conflicts with current context
+
+missing:
+  - renewal-order
+
+checked:
+  - src/auth/**
+  - docs/auth.md
+
+next:
+  type: INSPECT_TEST
+  target: tests/session-refresh.test.ts
+  reason: Most direct uninspected evidence for renewal ordering.
+
+fallback:
+  type: ask
+  question: Does session renewal happen before or after refresh-token validation?
+```
+
+### Inspecting Changes with `bilmem diff`
+```text
+$ bilmem diff 8ac12f
+
+Since 8ac12f:
+
++ 14 observations
++ 2 candidates
+↑ 1 knowledge strengthened
+~ 1 knowledge revised
+! 1 contradiction
+? 2 unknowns
+× 1 knowledge needs revalidation
+- 0 invalidated
+```
+
+---
+
+## Model Context Protocol (MCP) via `mcponce`
+
+`bilmem` provides a single-instance MCP server via `mcponce`.
+
+Run directly:
+```bash
+bilmem mcp
+```
+
+### Exposed MCP Tools:
+1. `bilmem_resolve`: Primary epistemic operation. Determines if enough is known to answer or act, what contextually does not apply, what is missing, and the cheapest next step to resolve uncertainty.
+2. `bilmem_lookup`: Query knowledge with positive/negative context cues. Returns compact, highly applicable knowledge units without flooding agent context.
+3. `bilmem_observe`: Record an observation with preserved provenance.
+4. `bilmem_learn`: Learn from task trajectories or explicit user corrections.
+5. `bilmem_explain`: Inspectable explanation of why an item is known (supports `--history`).
+6. `bilmem_unknown`: Query or record first-class unknowns with checked paths.
+7. `bilmem_scan`: Trigger a repository scan.
+8. `bilmem_stats`: Inspect local-first statistics, knowledge health, and effectiveness metrics (read-only).
+
+---
+
+## Agent & Editor Installer (`bilmem install`)
+
+Bilmem features a lightweight, decoupled installer system to configure Bilmem's MCP server and minimal instructions across supported AI coding agents and editors:
+
+```bash
+# Interactive detection & installation for detected agents
+bilmem install
+
+# Target specific agents
+bilmem install cursor
+bilmem install claude
+bilmem install codex
+bilmem install gemini
+
+# Non-interactive / CI automation
+bilmem install --detected --yes
+bilmem install --all
+
+# Dry-run preview
+bilmem install cursor --dry-run
+
+# Global vs Project scope (defaults to project-local)
+bilmem install cursor --global
+
+# Safe uninstallation (preserves other servers and user rules)
+bilmem uninstall cursor
+
+# Health diagnostics & automated repair
+bilmem doctor
+bilmem doctor --fix
+```
+
+### Safe, Non-Destructive Editing
+- **JSON Configuration**: Safely parses existing agent configs (`.cursor/mcp.json`, `.claude/mcp.json`, etc.), injects the `bilmem` MCP server under `mcpServers`, preserves all existing third-party servers and settings, and writes atomically.
+- **Agent Instructions**: Installs a token-efficient instruction block bounded by `<!-- bilmem:start -->` and `<!-- bilmem:end -->` into `.cursorrules`, `CLAUDE.md`, `CODEX.md`, or `GEMINI.md` without overwriting custom user guidelines.
+- **Ownership Tracking**: Maintains metadata in `.bilmem/integrations.json` so `bilmem uninstall` cleanly removes only Bilmem-owned blocks and registrations.
+
+---
+
+## Statistics & Effectiveness Layer (`bilmem stats`)
+
+The purpose of stats is **NOT** to create a vanity dashboard. It provides measurable evidence answering:
+
+> **Is Bilmem actually reducing repeated investigation and improving knowledge reuse?**
+
+Bilmem adheres to the principle: **"Bilmem should be cheaper than not knowing."**
+
+- **Deterministic & Observable**: No fake token, dollar, or time savings. Metrics track directly observable events: repeated checks avoided, broad searches avoided, source reads avoided, and knowledge reused.
+- **State vs Activity Separation**: Current state metrics (active, candidates, unknowns, conflicted, needs revalidation) are computed live from canonical state without drifting counters; historical metrics are aggregated from append-only events (`.bilmem/events.jsonl`).
+- **Local & Private by Default**: No network calls, telemetry, or remote analytics.
+
+```bash
+# Default overview report
+bilmem stats
+
+# Filter activity by timeframe
+bilmem stats --since 24h
+bilmem stats --since 7d
+bilmem stats --since 30d
+
+# Filter activity by Git revision
+bilmem stats --since HEAD~20
+bilmem stats --since 81ac23
+
+# Inspect single-item lifecycle, evidence, JEV diagnostics, and health
+bilmem stats --knowledge auth.session.refresh-order
+
+# Structured JSON output for CI, tooling, or MCP
+bilmem stats --json
+
+# Safe reset of metric events log (historical knowledge/evidence are never deleted)
+bilmem stats --reset
+```
+
+### Knowledge Health Classifications
+Deterministic, observable health classifications for every knowledge item:
+- `HEALTHY`: Active with verified independent sources and clean outcome history.
+- `NEEDS_REVALIDATION`: Underlying source or dependency changed since last validation.
+- `LOW_EVIDENCE`: Less than 2 independent sources and confidence < 0.75.
+- `FREQUENTLY_REJECTED`: Rejected by JEV in ≥70% of evaluations (min 3 attempts).
+- `FREQUENTLY_MISLEADING`: Misleading outcomes exceed or equal successful outcomes.
+- `UNUSED`: No reuse recorded after creation.
+
+---
+
+## Programmatic TypeScript API
+
+```ts
+import { Bilmem } from 'bilmem';
+
+// Initialize bilmem client
+const bilmem = new Bilmem();
+await bilmem.init();
+
+// Lookup knowledge with contextual cues
+const results = await bilmem.lookup({
+  query: 'session renewal',
+  positive: ['server-session']
+});
+
+// Record an observation with provenance
+await bilmem.observe({
+  claim: 'Refresh token validation happens before session renewal',
+  source: 'file:src/auth/session.ts',
+  positive: ['auth', 'session']
+});
+
+// Learn from task trajectory or user corrections
+await bilmem.learn({
+  goal: 'Fix session race condition',
+  outcome: 'success',
+  events: [
+    { type: 'hypothesis', description: 'Investigate token renewal lock' },
+    { type: 'attempt', description: 'Apply mutex to session refresh' },
+    { type: 'success', description: 'Resolved concurrent refresh race' }
+  ]
+});
+
+// Or compose modular building blocks directly:
+import { Storage, SearchIndex, Retriever } from 'bilmem';
+
+const storage = new Storage();
+await storage.init();
+
+const index = new SearchIndex();
+await index.buildIndex(await storage.getAllKnowledge());
+
+const retriever = new Retriever(index, storage);
+```
+
+---
+
+## License
+
+MIT

package/dist/canonical-CglQQ0xc.d.ts

@@ -0,0 +1,262 @@
+import { u as ResolutionState, A as ActionType, O as OutcomeType, m as KnowledgeStatus, l as KnowledgeStage, B as BilmemConfig, K as Knowledge, c as Evidence, o as Observation, U as UnknownRecord, p as OutcomeRecord, I as InvestigationReceipt, d as EvidenceRelation, b as BilmemMetrics, y as RuleSet, x as RuleDefinition, v as RevisionSnapshot, h as KnowledgeDiff } from './types-Nxq5Gzay.js';
+import { KnowledgeStoreProvider } from './search/index.js';
+
+type JevRejectReason = 'HARD_NEGATIVE' | 'SCOPE_MISMATCH' | 'INSUFFICIENT_CONTEXT' | 'STALE_KNOWLEDGE' | 'CONTEXT_MISMATCH';
+type MetricEvent = {
+    type: 'resolve';
+    state: ResolutionState;
+    action?: ActionType;
+    question?: string;
+    timestamp: number;
+} | {
+    type: 'knowledge_reused';
+    knowledgeId: string;
+    timestamp: number;
+} | {
+    type: 'knowledge_created';
+    knowledgeId: string;
+    timestamp: number;
+} | {
+    type: 'knowledge_merged';
+    knowledgeId: string;
+    targetId?: string;
+    timestamp: number;
+} | {
+    type: 'knowledge_strengthened';
+    knowledgeId: string;
+    timestamp: number;
+} | {
+    type: 'knowledge_specialized';
+    knowledgeId: string;
+    timestamp: number;
+} | {
+    type: 'knowledge_superseded';
+    knowledgeId: string;
+    supersededBy?: string;
+    timestamp: number;
+} | {
+    type: 'contradiction_detected';
+    knowledgeId?: string;
+    conflictingId?: string;
+    timestamp: number;
+} | {
+    type: 'duplicate_ignored';
+    timestamp: number;
+} | {
+    type: 'jev_result';
+    knowledgeId: string;
+    result: 'MATCH' | 'POSSIBLE' | 'REJECT';
+    reason?: JevRejectReason | string;
+    timestamp: number;
+} | {
+    type: 'jev_hard_negative';
+    knowledgeId: string;
+    timestamp: number;
+} | {
+    type: 'investigation_reused';
+    investigationId: string;
+    timestamp: number;
+} | {
+    type: 'source_read_avoided';
+    source: string;
+    timestamp: number;
+} | {
+    type: 'broad_search_avoided';
+    targetAction?: ActionType;
+    timestamp: number;
+} | {
+    type: 'question_suggested';
+    questionId?: string;
+    question?: string;
+    timestamp: number;
+} | {
+    type: 'question_resolved';
+    questionId?: string;
+    timestamp: number;
+} | {
+    type: 'outcome';
+    knowledgeId: string;
+    result: OutcomeType;
+    timestamp: number;
+};
+interface EffectivenessRatio {
+    value?: number;
+    formatted: string;
+    formula: string;
+}
+type KnowledgeHealthCategory = 'HEALTHY' | 'NEEDS_REVALIDATION' | 'LOW_EVIDENCE' | 'FREQUENTLY_REJECTED' | 'FREQUENTLY_MISLEADING' | 'UNUSED';
+interface StatsReport {
+    since?: string;
+    sinceTimestamp?: number;
+    knowledge: {
+        active: number;
+        candidates: number;
+        unknown: number;
+        conflicted: number;
+        needsRevalidation: number;
+        stale: number;
+        total: number;
+    };
+    learning: {
+        observations: number;
+        new: number;
+        merged: number;
+        strengthened: number;
+        specialized: number;
+        superseded: number;
+        contradictions: number;
+        ignoredDuplicates: number;
+    };
+    resolution: {
+        resolveCalls: number;
+        known: number;
+        partiallyKnown: number;
+        unknown: number;
+        conflicted: number;
+        stale: number;
+    };
+    investigation: {
+        repeatedChecksAvoided: number;
+        knowledgeReused: number;
+        questionsSuggested: number;
+        questionsResolved: number;
+        broadSearchesAvoided: number;
+        sourceReadsAvoided: number;
+        investigationsReused: number;
+    };
+    jev: {
+        candidates: number;
+        match: number;
+        possible: number;
+        rejected: number;
+        hardNegativeRejects: number;
+        reasons: {
+            hardNegative: number;
+            scopeMismatch: number;
+            insufficientContext: number;
+            staleKnowledge: number;
+        };
+    };
+    actions: Record<string, number>;
+    effectiveness: {
+        knowledgeReuseRate: EffectivenessRatio;
+        resolveSuccessRate: EffectivenessRatio;
+        questionResolutionRate: EffectivenessRatio;
+        jevRejectionRate: EffectivenessRatio;
+    };
+    health: {
+        healthy: number;
+        needsRevalidation: number;
+        lowEvidence: number;
+        frequentlyRejected: number;
+        frequentlyMisleading: number;
+        unused: number;
+    };
+}
+interface KnowledgeStatsReport {
+    id: string;
+    status: KnowledgeStatus;
+    stage?: KnowledgeStage;
+    statement: string;
+    usage: {
+        used: number;
+        successfulOutcomes: number;
+        neutralOutcomes: number;
+        misleadingOutcomes: number;
+        failedOutcomes: number;
+    };
+    jev: {
+        match: number;
+        possible: number;
+        rejected: number;
+        hardNegativeRejects: number;
+    };
+    evidence: {
+        sources: number;
+        independentSources: number;
+        sourcesList: string[];
+    };
+    lifecycle: {
+        revisions: number;
+        strengthened: number;
+        contradictions: number;
+        lastUsed?: string;
+        lastValidated?: string;
+        health: KnowledgeHealthCategory;
+        healthReason: string;
+    };
+}
+
+declare function sanitizeFileName(id: string): string;
+declare function desanitizeFileName(name: string): string;
+declare class Storage implements KnowledgeStoreProvider {
+    private baseDir;
+    private knowledgeDir;
+    private evidenceDir;
+    private observationDir;
+    private unknownDir;
+    private rulesDir;
+    private configFile;
+    private relationsFile;
+    private outcomesFile;
+    private metricsFile;
+    private revisionsFile;
+    private knowledgeJsonlFile;
+    private evidenceJsonlFile;
+    private observationJsonlFile;
+    private unknownsJsonlFile;
+    private receiptsDir;
+    private receiptsJsonlFile;
+    private eventsFile;
+    constructor(rootDir?: string);
+    getBaseDir(): string;
+    isInitialized(): Promise<boolean>;
+    init(options?: {
+        projectName?: string;
+        defaultScope?: string;
+    }): Promise<BilmemConfig>;
+    getConfig(): Promise<BilmemConfig>;
+    saveConfig(config: BilmemConfig): Promise<void>;
+    updateConfig(updates: Partial<BilmemConfig>): Promise<BilmemConfig>;
+    saveKnowledge(knowledge: Knowledge): Promise<void>;
+    getKnowledge(id: string): Promise<Knowledge | undefined>;
+    getAllKnowledge(): Promise<Knowledge[]>;
+    deleteKnowledge(id: string): Promise<boolean>;
+    saveEvidence(evidence: Evidence): Promise<void>;
+    getEvidence(id: string): Promise<Evidence | undefined>;
+    getAllEvidence(): Promise<Evidence[]>;
+    saveObservation(obs: Observation): Promise<void>;
+    getObservation(id: string): Promise<Observation | undefined>;
+    getAllObservations(): Promise<Observation[]>;
+    deleteObservation(id: string): Promise<boolean>;
+    saveUnknown(record: UnknownRecord): Promise<void>;
+    getUnknown(id: string): Promise<UnknownRecord | undefined>;
+    getAllUnknowns(): Promise<UnknownRecord[]>;
+    deleteUnknown(id: string): Promise<boolean>;
+    appendOutcome(outcome: OutcomeRecord): Promise<void>;
+    getAllOutcomes(): Promise<OutcomeRecord[]>;
+    appendMetricEvent(event: MetricEvent): Promise<void>;
+    getMetricEvents(filter?: {
+        sinceTimestamp?: number;
+        knowledgeId?: string;
+    }): Promise<MetricEvent[]>;
+    resetMetricEvents(): Promise<void>;
+    saveReceipt(receipt: InvestigationReceipt): Promise<void>;
+    getReceipt(id: string): Promise<InvestigationReceipt | undefined>;
+    getAllReceipts(): Promise<InvestigationReceipt[]>;
+    getRelations(): Promise<EvidenceRelation[]>;
+    saveRelations(relations: EvidenceRelation[]): Promise<void>;
+    getMetrics(): Promise<BilmemMetrics>;
+    saveMetrics(metrics: BilmemMetrics): Promise<void>;
+    getRulesDir(): string;
+    loadRuleSets(): Promise<RuleSet[]>;
+    saveRuleSet(ruleSet: RuleSet, fileName?: string): Promise<string>;
+    addRule(rule: RuleDefinition, fileName?: string): Promise<string>;
+    appendRevision(snapshot: RevisionSnapshot): Promise<void>;
+    getRevisions(): Promise<RevisionSnapshot[]>;
+    getLatestRevision(): Promise<RevisionSnapshot | undefined>;
+    getDiff(sinceRef?: string): Promise<KnowledgeDiff>;
+}
+declare function formatKnowledgeDiff(diff: KnowledgeDiff): string;
+
+export { type EffectivenessRatio as E, type JevRejectReason as J, type KnowledgeHealthCategory as K, type MetricEvent as M, Storage as S, type KnowledgeStatsReport as a, type StatsReport as b, desanitizeFileName as d, formatKnowledgeDiff as f, sanitizeFileName as s };