Context-Sieve 🧠

A background sentinel that captures "Aha!" moments from your AI agent sessions and turns them into permanent architectural rules.

The Problem: Context Rot & Dilution

When building with AI agents, they often repeat the same mistakes. You might fix a race condition in auth.ts, but the next agent that touches the file won't know the history. Documenting everything in a README leads to "Context Rot," and expecting the agent to read the whole repo leads to "Context Dilution."

The Solution: Semantic "Thought-Scraping"

Context-Sieve is a "plug-and-forget" background daemon.

1. Capture: It watches configured agent logs and source files.
2. Sieve: It detects "Success-after-Failure" arcs (e.g., an agent fails a test, realizes the bug, and fixes it).
3. Hydrate: It extracts the "Lesson" and auto-injects it into a high-signal context target such as AGENTS.md, .sieve/context.md, or a legacy .gemini_context file.

Current implementation note: v0.1.0 now defaults to .sieve/logs and .sieve/context.md. Legacy Gemini paths are available through explicit config.

The next agent that wakes up instantly reads:

Rule #1: Always use connectSafe() in Auth to prevent V03 race conditions.

Quick Start

Installation

npm install -g context-sieve

Usage

Run the daemon in the background of your project:

context-sieve

Run the deterministic product harness:

npm run harness

Verify the npm package boundary and built CLI:

npm run smoke:package
npm run smoke:install

Initialize a config profile without hand-editing JSON:

context-sieve init --profile default

Run once with a profile override without writing config:

context-sieve --profile legacy-gemini

Review pending lessons before they become verified invariants:

context-sieve review
context-sieve review edit <id> "Refined rule text"
context-sieve review approve <id>
context-sieve review reject <id>

Check project wiring and health:

context-sieve status

Configuration

By default, Context-Sieve uses provider-neutral paths:

• Logs: .sieve/logs
• Context target: .sieve/context.md
• Ledger: .sieve/memory.jsonl
• Reflection timeout: 300000 ms

To target a compatibility file such as AGENTS.md, add .sieve/config.json:

{
  "contextTargets": [
    { "path": "AGENTS.md", "strategy": "managed-block" }
  ]
}

To use legacy Gemini logs/context explicitly:

context-sieve init --profile legacy-gemini

This writes:

{
  "logSources": [
    { "type": "tail", "path": ".gemini/logs", "legacy": true }
  ],
  "contextTargets": [
    { "path": ".gemini_context", "strategy": "replace", "legacy": true }
  ],
  "reflectionTimeoutMs": 300000
}

Note: The project is currently in the Incubator Phase (v0.1.0). The CLI and daemon logic are actively being hardened.

Architecture

• The Engine: Stream-processes logs to find semantic breakthroughs.
• The Watcher: Uses a portable Node-native file watcher with per-file offsets instead of shell tail.
• The Adapters: Agent log and context targets should be provider-neutral. Gemini support is a legacy adapter, not the product identity.
• The Ledger: Stores versioned JSONL entries in .sieve/memory.jsonl, reports malformed lines, and atomically rewrites reviewed entries.
• The Messenger: Prompts the active agent for SIEVE_RULE: after a failure-to-success arc and records the semantic lesson.
• The Review CLI: Lets humans edit, approve, or reject pending lessons before they become verified invariants.
• The Status CLI: Reports config, log source, ledger, and context target health without mutating project files.
• The Package Smoke Gates: Verify the npm tarball boundary, built CLI, and local tarball install before publish automation.
• The Harness: Runs deterministic product-contract scenarios without real watchers or external agents.

License

MIT