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, search engines, and memory dumps:

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.

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.

Before substantial work, understand constraints, lessons, and blocking unknowns.

The Bilmem Product Loop

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

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:

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).

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:

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:

.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

# 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

# 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]

# Local-first statistics & knowledge health
bilmem stats

# Status summary & metrics
bilmem status

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.

# 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:

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:

$ bilmem resolve "How are sessions renewed?" -p server-session -n stateless-jwt

Structured output:

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

$ 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:

bilmem mcp

Exposed MCP Tools:

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).

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:

# Interactive detection & installation for detected agents
bilmem install

# Target specific agents
bilmem install cursor
bilmem install claude
bilmem install codex
bilmem install antigravity
bilmem install gemini

# Non-interactive / CI automation
bilmem install --detected --yes
bilmem install --all

# Dry-run preview
bilmem install antigravity --dry-run

# Global vs Project scope (defaults to project-local)
bilmem install antigravity --global

# Safe uninstallation (preserves other servers and user rules)
bilmem uninstall antigravity

# Health diagnostics & automated repair
bilmem doctor
bilmem doctor --fix

Safe, Non-Destructive Editing

• 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.

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.

# 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

import { Bilmem } from 'bilmem';

// Initialize bilmem client
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',
  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);

Adaptive Epistemic Core

Bilmem includes a lightweight, deterministic learning layer that allows it to improve how it evaluates knowledge, not merely accumulate more memories:

Epistemic Decision
        ↓
Agent Action
        ↓
Outcome
        ↓
Epistemic Replay
        ↓
Calibration / Policy Learning
        ↓
Candidate Core Improvements
        ↓
Shadow Evaluation
        ↓
Validated Adaptation

Key Principles

1. Epistemic Invariant Hierarchy: DETERMINISTIC INVARIANTS → BOUNDARIES / CONTRADICTIONS → EVIDENCE → JEV → CALIBRATION → LEARNED POLICY → AI SUGGESTIONS. A lower layer may improve ranking or interpretation, but can never override a stronger layer.
2. Deterministic Actionability: Explicitly separates knowledge state from actionability (ACTIONABLE | VERIFY | ABSTAIN).
3. Epistemic Replay & Calibration: Learns empirical reliability of confidence fingerprints across contexts without altering deterministic JEV rules on the critical path.
4. Shadow Evaluation: Candidate meta-rules run alongside active policies (PROPOSED → SHADOW → VALIDATED → ACTIVE). Never directly promoted from AI suggestions.
5. Cross-Project Scope Promotion & Specialization: Project-isolated knowledge can earn global status only across independent project contexts; lessons that fail in specific environments specialize (SPECIALIZE) with explicit boundary conditions.
6. Adaptive Memory Budget & Explainable Forgetting: Bounded active working memory with cold archiving (status: archived) without destroying history or provenance.

Diagnostic CLI Commands

# Inspect current epistemic policy status and parameters
bilmem policy status

# View policy revision history
bilmem policy history

# Diff policy revisions
bilmem policy diff 1..2

# Replay an epistemic decision against real outcomes
bilmem replay dec_123
bilmem replay --recent

# Inspect cross-project transfer status and promotion candidates
bilmem global status
bilmem global candidates

License

MIT