bilmem 0.1.0 → 0.2.0

package/README.md

@@ -17,12 +17,17 @@ Its purpose is to help an agent:
 
 ### 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:**
+Bilmem differs fundamentally from repository graphs, search engines, and memory dumps:
 
-> **"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?"**
+```text
+Repository graph:  "What is connected to this code?"
+Search / RAG:      "What information looks relevant?"
+Memory dump:       "What did we store before?"
+
+Bilmem lookup:     "What do we already know?"
+Bilmem resolve:    "Do we know this specific thing well enough to act?"
+Bilmem preflight:  "What must we know before starting this work?"
+```
 
 Bilmem is a lightweight **epistemic runtime**.
 
@@ -34,6 +39,44 @@ Bilmem is a lightweight **epistemic runtime**.
 
 > **Prefer the smallest action likely to resolve the uncertainty.**
 
+> **Before substantial work, understand constraints, lessons, and blocking unknowns.**
+
+### The Bilmem Product Loop
+
+```text
+BEFORE WORK
+  preflight
+      ↓
+  expose constraints
+  surface past lessons
+  identify unknowns
+  identify stale knowledge
+  ask high-value questions
+
+DURING WORK
+  resolve
+      ↓
+  reuse knowledge
+  reject wrong-context knowledge
+  avoid repeated investigation
+  find cheapest next evidence
+
+AFTER WORK
+  learn
+      ↓
+  observations
+  outcomes
+  reconciliation
+  refinement
+
+OVER TIME
+  compact + stats
+      ↓
+  healthier knowledge
+  less duplication
+  measurable reuse
+```
+
 ## Architecture Overview
 
 ```text
@@ -173,6 +216,9 @@ Inside `.bilmem/`, the source-of-truth is stored in **append-friendly JSONL** fi
 ## CLI Commands
 
 ```bash
+# Primary Preflight Operation: What must be known before starting work?
+bilmem preflight "Add OAuth login with Google" [--deep]
+
 # 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
 
@@ -219,11 +265,98 @@ bilmem restore snapshot.yml
 # Compact knowledge base (merge duplicates, clean stale observations)
 bilmem compact [--dry-run]
 
+# Local-first statistics & knowledge health
+bilmem stats
+
 # Status summary & metrics
 bilmem status
 ```
 
-### Primary Operation: `bilmem resolve`
+### Preflight Before Substantial Work: `bilmem preflight`
+
+Before starting substantial implementation work, `bilmem preflight` surfaces existing constraints, applicable past lessons, past failures, stale knowledge, and blocking unknowns.
+
+```bash
+# Analyze existing knowledge relative to a proposed goal
+bilmem preflight "Add OAuth login with Google"
+
+# Pass contextual positive and negative cues
+bilmem preflight "Add OAuth login with Google" -p server-session -n stateless-jwt
+
+# Deep mode: targeted git diff & file staleness verification
+bilmem preflight "Add OAuth login with Google" --deep
+
+# Structured JSON output
+bilmem preflight "Add OAuth login with Google" --json
+```
+
+Structured output:
+```yaml
+goal: Add OAuth login with Google
+readiness: NEEDS_CLARIFICATION
+
+known:
+  - id: auth.session.server
+    statement: Sessions are server-side in Redis.
+    confidence: high
+  - id: auth.user.service
+    statement: User creation goes through UserService.
+    confidence: high
+
+constraints:
+  - id: auth.storage.boundary
+    statement: Auth routes must not access storage directly.
+  - id: auth.token.browser
+    statement: Authentication tokens must not be persisted in browser storage.
+
+lessons:
+  - id: auth.refresh.validation
+    statement: Validate callback credentials before session creation.
+
+past_failures:
+  - id: auth.session.duplicate-write
+    statement: Concurrent session creation previously caused duplicate writes.
+
+unknowns:
+  - id: auth.oauth.account-linking
+    question: Should OAuth identities be linked to existing accounts?
+    blocking: true
+  - id: auth.oauth.scopes
+    question: Which OAuth scopes are required?
+    blocking: false
+
+stale:
+  - id: auth.provider.abstraction
+    reason: Supporting source changed after last validation.
+
+questions:
+  - question: What should happen when the Google email already belongs to an existing account?
+    reason: Existing account-linking semantics are unknown.
+
+likely_domains:
+  - authentication
+  - session
+  - user-identity
+
+next:
+  - type: ASK_USER
+    target: auth.oauth.account-linking
+    reason: Resolve account-linking semantics before implementation.
+  - type: REVALIDATE
+    target: auth.provider.abstraction
+    reason: Supporting source changed after last validation.
+```
+
+### Readiness Model
+
+Readiness is categorical, never a vanity percentage score:
+- **`READY`**: Bilmem found validated knowledge, no unresolved contradictions, no blocking unknowns, and no critical stale dependencies.
+- **`NEEDS_CLARIFICATION`**: One or more important product/behavior decisions or blocking unknowns are unresolved and require human clarification (`ASK_USER`).
+- **`NEEDS_REVALIDATION`**: Critical relevant knowledge exists, but its supporting code or evidence was modified.
+- **`CONFLICTED`**: Multiple applicable credible knowledge units disagree and contextual specialization cannot resolve the conflict.
+- **`INSUFFICIENT_KNOWLEDGE`**: Not enough evidence or knowledge units exist locally to evaluate preflight.
+
+### Primary Epistemic Operation: `bilmem resolve`
 
 Unlike search or lookup, `resolve` executes an epistemic evaluation:
 
@@ -291,14 +424,15 @@ 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).
+1. `bilmem_preflight`: Preflight knowledge analysis before substantial work. Surface constraints, lessons, failures, stale knowledge, and blocking unknowns in compact format.
+2. `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.
+3. `bilmem_lookup`: Query knowledge with positive/negative context cues. Returns compact, highly applicable knowledge units without flooding agent context.
+4. `bilmem_observe`: Record an observation with preserved provenance.
+5. `bilmem_learn`: Learn from task trajectories or explicit user corrections.
+6. `bilmem_explain`: Inspectable explanation of why an item is known (supports `--history`).
+7. `bilmem_unknown`: Query or record first-class unknowns with checked paths.
+8. `bilmem_scan`: Trigger a repository scan.
+9. `bilmem_stats`: Inspect local-first statistics, knowledge health, and effectiveness metrics (read-only).
 
 ---
 
@@ -314,6 +448,7 @@ bilmem install
 bilmem install cursor
 bilmem install claude
 bilmem install codex
+bilmem install antigravity
 bilmem install gemini
 
 # Non-interactive / CI automation
@@ -321,13 +456,13 @@ bilmem install --detected --yes
 bilmem install --all
 
 # Dry-run preview
-bilmem install cursor --dry-run
+bilmem install antigravity --dry-run
 
 # Global vs Project scope (defaults to project-local)
-bilmem install cursor --global
+bilmem install antigravity --global
 
 # Safe uninstallation (preserves other servers and user rules)
-bilmem uninstall cursor
+bilmem uninstall antigravity
 
 # Health diagnostics & automated repair
 bilmem doctor
@@ -335,9 +470,10 @@ 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.
+- **JSON Configuration**: Safely parses existing agent configs (`.agents/mcp_config.json`, `.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.
+- **Antigravity Skills**: For Antigravity, installs a first-class on-demand skill into `.agents/skills/bilmem/SKILL.md` (project) or `~/.gemini/config/skills/bilmem/SKILL.md` (global) with YAML frontmatter for progressive disclosure and tool runbook guidance.
+- **Agent Instructions & Rules**: Installs a token-efficient instruction block bounded by `<!-- bilmem:start -->` and `<!-- bilmem:end -->` into `.agents/rules/bilmem.md`, `.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, skills, and registrations.
 
 ---
 
@@ -396,6 +532,13 @@ import { Bilmem } from 'bilmem';
 const bilmem = new Bilmem();
 await bilmem.init();
 
+// Preflight analysis before starting implementation
+const preflight = await bilmem.preflight({
+  goal: 'Add OAuth login with Google',
+  positive: ['auth', 'server']
+});
+console.log(preflight.readiness); // READY | NEEDS_CLARIFICATION | etc.
+
 // Lookup knowledge with contextual cues
 const results = await bilmem.lookup({
   query: 'session renewal',

package/dist/{canonical-CglQQ0xc.d.ts → canonical-JS6HUWGc.d.ts}

@@ -1,4 +1,4 @@
-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 { Q as ResolutionState, A as ActionType, O as OutcomeType, F as ReadinessStatus, o as KnowledgeStatus, n as KnowledgeStage, B as BilmemConfig, K as Knowledge, e as Evidence, q as Observation, U as UnknownRecord, r as OutcomeRecord, I as InvestigationReceipt, f as EvidenceRelation, d as BilmemMetrics, Y as RuleSet, X as RuleDefinition, V as RevisionSnapshot, j as KnowledgeDiff } from './types-DNlvHsj9.js';
 import { KnowledgeStoreProvider } from './search/index.js';
 
 type JevRejectReason = 'HARD_NEGATIVE' | 'SCOPE_MISMATCH' | 'INSUFFICIENT_CONTEXT' | 'STALE_KNOWLEDGE' | 'CONTEXT_MISMATCH';
@@ -78,6 +78,16 @@ type MetricEvent = {
     knowledgeId: string;
     result: OutcomeType;
     timestamp: number;
+} | {
+    type: 'preflight';
+    goal: string;
+    readiness: ReadinessStatus;
+    blockingUnknownsCount: number;
+    staleKnowledgeCount: number;
+    pastFailuresCount: number;
+    questionsCount: number;
+    repeatedChecksAvoidedCount: number;
+    timestamp: number;
 };
 interface EffectivenessRatio {
     value?: number;
@@ -152,6 +162,19 @@ interface StatsReport {
         frequentlyMisleading: number;
         unused: number;
     };
+    preflight?: {
+        runs: number;
+        ready: number;
+        needsClarification: number;
+        needsRevalidation: number;
+        conflicted: number;
+        insufficientKnowledge: number;
+        blockingUnknownsFound: number;
+        staleKnowledgeFound: number;
+        pastFailuresSurfaced: number;
+        questionsSuggested: number;
+        repeatedChecksAvoided: number;
+    };
 }
 interface KnowledgeStatsReport {
     id: string;