Metadata-Version: 2.4
Name: iflow-mcp_dasblueyeddevil-daem0nmcp
Version: 6.6.6
Summary: AI Memory & Decision System - Give AI agents persistent memory and consistent decision-making
Author: Daem0nMCP
License: MIT
Project-URL: Homepage, https://github.com/DasBluEyedDevil/Daem0n-MCP
Project-URL: Repository, https://github.com/DasBluEyedDevil/Daem0n-MCP
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=3.0.0b1
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: greenlet>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: onnxruntime>=1.24.1
Requires-Dist: numpy>=1.24.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: plyer>=2.1.0
Requires-Dist: tree-sitter-language-pack>=0.13.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: networkx>=3.0
Requires-Dist: leidenalg>=0.10.0
Requires-Dist: python-igraph>=0.11.0
Requires-Dist: langgraph>=1.0.7
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.3
Requires-Dist: llmlingua>=0.2.2
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: e2b-code-interpreter>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: tracing
Requires-Dist: opentelemetry-api>=1.20.0; extra == "tracing"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "tracing"
Dynamic: license-file

# Daem0nMCP

```
        ,     ,
       /(     )\
      |  \   /  |      "I am Daem0n, keeper of memories,
       \  \ /  /        guardian of decisions past..."
        \  Y  /
         \ | /
          \|/
           *
```

**AI Memory & Decision System** - Give AI agents persistent memory and consistent decision-making with *actual* semantic understanding.

## What's New in v6.6.6

### ModernBERT Deep Sight (BREAKING)
The daemon's vision has been fundamentally sharpened. The old `all-MiniLM-L6-v2` embedding model is replaced by **ModernBERT** with asymmetric query/document encoding and optional ONNX acceleration.

| Aspect | Old (v5.x) | New (v6.6.6) |
|--------|------------|--------------|
| **Model** | `all-MiniLM-L6-v2` | `nomic-ai/modernbert-embed-base` |
| **Dimensions** | 384 | 256 (Matryoshka truncation) |
| **Encoding** | Single `encode()` | Dual: `encode_query()` / `encode_document()` |
| **Backend** | PyTorch only | ONNX quantized (with torch fallback) |
| **Prefixes** | None | `search_query: ` / `search_document: ` |

**This is a BREAKING CHANGE** — existing embeddings must be re-encoded:
```bash
python -m daem0nmcp.migrations.migrate_embedding_model --project-path /path/to/.daem0nmcp
```

### Background Dreaming
When the user goes idle, the daemon autonomously re-evaluates past failed decisions using current evidence:
- `IdleDreamScheduler` monitors tool call activity
- After configurable idle timeout (default 60s), `FailedDecisionReview` strategy runs
- Classifies decisions as **revised**, **confirmed_failure**, or **needs_more_data**
- Insights persisted as `learning` memories with `dream` tag and full provenance
- Yields immediately when user returns (cooperative scheduling)

### Cognitive Tools (3 new standalone MCP tools)
Meta-reasoning tools for daemon introspection:

| Tool | Purpose |
|------|---------|
| `simulate_decision` | **Temporal Scrying** — replay a past decision with current knowledge, revealing what changed |
| `evolve_rule` | **Rule Entropy Analysis** — examine rules for staleness, code drift, and outcome correlation |
| `debate_internal` | **Adversarial Council** — structured evidence-grounded debate with convergence detection |

### Auto-Zoom Retrieval Routing
Query-aware search dispatch that routes to the optimal retrieval strategy:
- **SIMPLE** queries → Vector-only search (fast path)
- **MEDIUM** queries → Hybrid BM25+vector with RRF fusion
- **COMPLEX** queries → GraphRAG multi-hop traversal + community summaries
- Shadow mode (default) logs classifications without changing behavior
- All strategies fall back to hybrid on failure

### Claude Code Native Hooks
New `daem0nmcp/claude_hooks/` module with 5 lifecycle hooks and automated installation:
```bash
python -m daem0nmcp.cli install-claude-hooks      # Install to ~/.claude/settings.json
python -m daem0nmcp.cli uninstall-claude-hooks     # Remove
```

| Hook | Purpose |
|------|---------|
| `session_start` | Auto-briefing at session dawn |
| `pre_edit` | Preflight enforcement + file memory recall before edits |
| `pre_bash` | Rule enforcement on bash commands |
| `post_edit` | Suggest remembrance for significant changes |
| `stop` | Auto-capture decisions from conversation |

### Stats
- **8 workflow tools** + **3 cognitive tools** (11 MCP tools total, plus legacy)
- **59 workflow actions** across 8 workflows
- **500+ tests** passing

---

## What's New in v5.1.0

### Workflow Consolidation
v5.1 consolidates **67 individual MCP tools into 8 workflow-oriented tools**, dramatically reducing context overhead for AI agents while preserving all capabilities.

#### 8 Workflow Tools

| Workflow | Purpose | Actions |
|----------|---------|---------|
| **`commune`** | Session start & status | `briefing`, `active_context`, `triggers`, `health`, `covenant`, `updates` |
| **`consult`** | Pre-action intelligence | `preflight`, `recall`, `recall_file`, `recall_entity`, `recall_hierarchical`, `search`, `check_rules`, `compress` |
| **`inscribe`** | Memory writing & linking | `remember`, `remember_batch`, `link`, `unlink`, `pin`, `activate`, `deactivate`, `clear_active`, `ingest` |
| **`reflect`** | Outcomes & verification | `outcome`, `verify`, `execute` |
| **`understand`** | Code comprehension | `index`, `find`, `impact`, `todos`, `refactor` |
| **`govern`** | Rules & triggers | `add_rule`, `update_rule`, `list_rules`, `add_trigger`, `list_triggers`, `remove_trigger` |
| **`explore`** | Graph & discovery | `related`, `chain`, `graph`, `stats`, `communities`, `community_detail`, `rebuild_communities`, `entities`, `backfill_entities`, `evolution`, `versions`, `at_time` |
| **`maintain`** | Housekeeping & federation | `prune`, `archive`, `cleanup`, `compact`, `rebuild_index`, `export`, `import_data`, `link_project`, `unlink_project`, `list_projects`, `consolidate` |

#### How It Works
Each workflow tool accepts an `action` parameter that selects the operation:
```python
# Old way (67 separate tools)
mcp__daem0nmcp__get_briefing(project_path="...")
mcp__daem0nmcp__recall(topic="auth", project_path="...")
mcp__daem0nmcp__remember(category="decision", content="...", project_path="...")
mcp__daem0nmcp__record_outcome(memory_id=42, outcome="...", worked=True, project_path="...")

# New way (8 workflow tools)
mcp__daem0nmcp__commune(action="briefing", project_path="...")
mcp__daem0nmcp__consult(action="recall", topic="auth", project_path="...")
mcp__daem0nmcp__inscribe(action="remember", category="decision", content="...", project_path="...")
mcp__daem0nmcp__reflect(action="outcome", memory_id=42, outcome_text="...", worked=True, project_path="...")
```

#### Why Consolidate?
- **88% fewer tool definitions** in context (8 vs 67)
- **Lower token overhead** — AI agents load fewer tool schemas
- **Logical grouping** — related operations live in one tool
- **Backward compatible** — legacy individual tools still registered alongside workflows

---

## What's New in v5.0.0

### Visions of the Void (MCP Apps)
Interactive HTML interfaces via MCP Apps (SEP-1865). Visual mode is now accessed via the `visual=true` parameter on workflow tools:

```python
commune(action="briefing", visual=true, project_path="...")      # Briefing Dashboard
consult(action="recall", topic="auth", visual=true, project_path="...")  # Search Results UI
commune(action="covenant", visual=true, project_path="...")      # Covenant Status
explore(action="communities", visual=true, project_path="...")   # Community Map
explore(action="graph", topic="auth", visual=true, project_path="...")  # Memory Graph Viewer
```

Features: D3.js v7 bundled (105KB, no CDN), restrictive CSP, canvas-based graph (10,000+ nodes at 60fps), graceful text fallback for non-visual hosts.

---

## What's New in v4.0.0

### Cognitive Architecture
Five major capabilities:

- **GraphRAG & Leiden Communities**: Knowledge graph construction with hierarchical community detection, multi-hop queries, global search via community summaries
- **Bi-Temporal Knowledge**: Dual timestamps (`valid_time` vs `transaction_time`), `happened_at` backfilling, `as_of_time` point-in-time queries, contradiction detection
- **Metacognitive Reflexion**: Actor-Evaluator-Reflector loop, `verify` action validates claims against stored knowledge, reflection persistence
- **Context Engineering**: LLMLingua-2 for 3x-6x compression, code entity preservation, adaptive rates, `compress` action for on-demand optimization
- **Dynamic Agency**: `execute` action for sandboxed Python execution via E2B Firecracker microVMs

---

## What's New in v3.1.0

### 2026 AI Memory Research Enhancements
- **BM25 + RRF Hybrid Retrieval**: Okapi BM25 replaces TF-IDF, Reciprocal Rank Fusion combines keyword and vector search
- **TiMem-Style Recall Planner**: Complexity-aware retrieval adapting to query difficulty (simple/medium/complex)
- **Titans-Inspired Surprise Scoring**: Novelty detection with `surprise_score` (0.0-1.0)
- **Importance-Weighted Learning**: EWC-inspired protection for valuable memories via `importance_score`
- **Fact Model**: Verified facts promote to immutable O(1) lookup after threshold successful outcomes

---

## What's New in v3.0.0

### FastMCP 3.0 Upgrade
- **CovenantMiddleware**: Sacred Covenant enforcement via FastMCP 3.0 middleware pattern
- **Component Versioning**: All tools include version metadata
- **OpenTelemetry Tracing** (Optional): `pip install daem0nmcp[tracing]`

---

## Previous Versions

<details>
<summary>v2.16.0 — Sacred Covenant Enforcement</summary>

- Tools block with `COMMUNION_REQUIRED`/`COUNSEL_REQUIRED` until proper rituals observed
- Preflight tokens with 5-minute validity
- MCP Resources for dynamic context injection (`daem0n://warnings/`, `daem0n://failed/`, etc.)
</details>

<details>
<summary>v2.14.0–v2.15.0 — Active Context, Temporal Versioning, Entities</summary>

- Active Working Context (MemGPT-style always-hot memories, max 10)
- Temporal versioning with `versions` and `at_time` queries
- Hierarchical summarization via Leiden communities
- Auto entity extraction from memory content
- Contextual recall triggers (auto-recall on file/tag/entity patterns)
- Configurable hybrid search weight, result diversity, tag inference
- Qualified entity names (`module.Class.method`), incremental indexing
</details>

<details>
<summary>v2.11.0–v2.13.0 — Passive Capture, Linked Projects</summary>

- Passive Capture hooks (auto-remember decisions from conversation)
- Endless Mode (condensed recall with 50-75% token reduction)
- Linked Projects for cross-repo memory awareness
</details>

<details>
<summary>v2.7.0–v2.10.0 — Code Understanding, Enforcement, File Watcher</summary>

- Multi-language AST parsing via tree-sitter (Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Ruby, PHP)
- Qdrant vector backend for persistent vector storage
- Proactive file watcher with desktop/log/editor-poll notifications
- Pre-commit enforcement hooks blocking commits with stale decisions
- CLI tools for status, record-outcome, install-hooks
</details>

<details>
<summary>Core Features (v2.1+)</summary>

- TF-IDF semantic search with real similarity matching
- Memory decay (30-day half-life for decisions/learnings, eternal patterns/warnings)
- Conflict detection and failed decision boosting (1.5x relevance)
- File-level memory associations
- Vector embeddings for enhanced semantic matching
</details>

## Why Daem0nMCP?

AI agents start each session fresh. They don't remember:
- What decisions were made and why
- Patterns that should be followed
- Warnings from past mistakes

**Markdown files don't solve this** - the AI has to know to read them and might ignore them.

**Daem0nMCP provides ACTIVE memory** - it surfaces relevant context when the AI asks about a topic, enforces rules before actions, and learns from outcomes.

### What Makes This Different

- **Semantic matching**: "creating REST endpoint" matches rules about "adding API route"
- **Time decay**: A decision from yesterday matters more than one from 6 months ago
- **Conflict warnings**: "You tried this approach before and it failed"
- **Learning loops**: Record outcomes, and failures get boosted in future recalls
- **Surprise scoring**: Novel information surfaces above routine knowledge
- **Graph reasoning**: Multi-hop traversal across linked memories and communities
- **Background dreaming**: Idle-time re-evaluation of past failed decisions

## Quick Start

### Claude Code (The Easy Way)

1. Copy `Summon_Daem0n.md` to your project
2. Start a Claude Code session in that project
3. Claude will read the file and perform the summoning ritual automatically

### OpenCode

1. Install Daem0n-MCP: `pip install -e ~/Daem0nMCP`
2. Run the installer: `python -m daem0nmcp.cli install-opencode`
3. Launch OpenCode in your project directory
4. Run `/commune` to begin

For the full ritual walkthrough, see `Summon_Daem0n_OpenCode.md`.

### Manual Installation

```bash
# Clone the repository
git clone https://github.com/DasBluEyedDevil/Daem0n-MCP.git ~/Daem0nMCP

# Install
pip install -e ~/Daem0nMCP

# Run the MCP server (Linux/macOS — stdio transport)
python -m daem0nmcp.server

# Run the MCP server (Windows — HTTP transport required)
python ~/Daem0nMCP/start_server.py --port 9876
```

## Installation by Platform

### Linux / macOS (stdio transport)

```bash
# Find your Python path
python3 -c "import sys; print(sys.executable)"

# Register with Claude Code (replace <PYTHON_PATH>)
claude mcp add daem0nmcp --scope user -- <PYTHON_PATH> -m daem0nmcp.server

# Restart Claude Code
```

### Windows (HTTP transport required)

Windows has a known bug where Python MCP servers using stdio transport hang indefinitely. Use HTTP transport instead:

1. **Start the server** (keep this terminal open):
```bash
python ~/Daem0nMCP/start_server.py --port 9876
```
Or use `start_daem0nmcp_server.bat`

2. **Add to `~/.claude.json`**:
```json
{
  "mcpServers": {
    "daem0nmcp": {
      "type": "http",
      "url": "http://localhost:9876/mcp"
    }
  }
}
```

3. **Start Claude Code** (after server is running)

### Transport Modes

| Method | Transport | Default Port | Use Case |
|--------|-----------|-------------|----------|
| `python -m daem0nmcp.server` | `stdio` (default) or `sse` | 8765 (sse) | Unix/macOS direct channel |
| `python start_server.py` | `streamable-http` | 9876 | Windows HTTP, remote access |

For OpenCode setup, see the [OpenCode Integration](#opencode-integration) section below, or run `python -m daem0nmcp.cli install-opencode` for automated setup.

## Workflow Tools (8 Tools, 59 Actions)

All capabilities are accessed through 8 workflow tools. Each tool accepts an `action` parameter to select the operation. Legacy individual tools remain registered for backward compatibility.

### `commune` — Session Start & Status

| Action | Purpose |
|--------|---------|
| `briefing` | Smart session start with git awareness |
| `active_context` | Get all hot memories for current focus |
| `triggers` | Check context triggers for auto-recalled memories |
| `health` | Server health, version, and statistics |
| `covenant` | Sacred Covenant status and phase |
| `updates` | Poll for knowledge changes (real-time notifications) |

### `consult` — Pre-Action Intelligence

| Action | Purpose |
|--------|---------|
| `preflight` | Combined recall + rules check before changes |
| `recall` | Semantic memory retrieval by topic (supports `condensed`, `visual`) |
| `recall_file` | Get memories linked to a specific file |
| `recall_entity` | Get memories mentioning a code entity |
| `recall_hierarchical` | GraphRAG-style layered retrieval with community summaries |
| `search` | Full-text search across all memories (supports `highlight`, `visual`) |
| `check_rules` | Validate action against decision rules |
| `compress` | LLMLingua-2 context compression |

### `inscribe` — Memory Writing & Linking

| Action | Purpose |
|--------|---------|
| `remember` | Store a memory with conflict detection |
| `remember_batch` | Store multiple memories in one transaction |
| `link` | Create causal relationships between memories |
| `unlink` | Remove relationships between memories |
| `pin` | Pin/unpin memories to prevent pruning |
| `activate` | Add memory to always-hot working context |
| `deactivate` | Remove memory from active context |
| `clear_active` | Clear all active context |
| `ingest` | Import external documentation from URL |

### `reflect` — Outcomes & Verification

| Action | Purpose |
|--------|---------|
| `outcome` | Record whether a decision worked or failed |
| `verify` | Validate factual claims against stored knowledge |
| `execute` | Sandboxed Python execution (E2B) |

### `understand` — Code Comprehension

| Action | Purpose |
|--------|---------|
| `index` | Index code entities via tree-sitter |
| `find` | Semantic search across code entities |
| `impact` | Analyze blast radius of code changes |
| `todos` | Scan for TODO/FIXME/HACK/XXX/BUG comments |
| `refactor` | Generate refactor suggestions with causal history |

### `govern` — Rules & Triggers

| Action | Purpose |
|--------|---------|
| `add_rule` | Create decision tree rules |
| `update_rule` | Modify existing rules |
| `list_rules` | Show all configured rules |
| `add_trigger` | Create auto-recall context triggers |
| `list_triggers` | List all context triggers |
| `remove_trigger` | Remove a context trigger |

### `explore` — Graph & Discovery

| Action | Purpose |
|--------|---------|
| `related` | Find related memories via graph traversal |
| `chain` | Find causal paths between memories |
| `graph` | Visualize memory relationships (JSON/Mermaid, supports `visual`) |
| `stats` | Knowledge graph metrics |
| `communities` | List Leiden community clusters (supports `visual`) |
| `community_detail` | Drill down into a community |
| `rebuild_communities` | Detect communities via Leiden algorithm |
| `entities` | List most frequently mentioned entities |
| `backfill_entities` | Extract entities from existing memories |
| `evolution` | Trace knowledge evolution over time |
| `versions` | Get version history for a memory |
| `at_time` | Query memory state at a point in time |

### `maintain` — Housekeeping & Federation

| Action | Purpose |
|--------|---------|
| `prune` | Remove old, low-value memories (with protection) |
| `archive` | Archive/restore memories |
| `cleanup` | Find and merge duplicate memories |
| `compact` | Consolidate episodic memories into summaries |
| `rebuild_index` | Force rebuild TF-IDF and vector indexes |
| `export` | Export all memories and rules as JSON |
| `import_data` | Import memories and rules from JSON |
| `link_project` | Link to another project for cross-repo awareness |
| `unlink_project` | Remove a project link |
| `list_projects` | List all linked projects |
| `consolidate` | Merge memories from linked projects |

### Cognitive Tools (Standalone)

| Tool | Purpose |
|------|---------|
| `simulate_decision` | Temporal Scrying — replay a past decision with current knowledge |
| `evolve_rule` | Rule Entropy — examine rules for staleness and drift |
| `debate_internal` | Adversarial Council — evidence-grounded debate with convergence detection |

### Tool Names by Client

Different MCP clients use different naming conventions for tools. Both formats resolve to the same server-side operations.

**Workflow Tools:**

| MCP Tool | Claude Code | OpenCode |
|----------|-------------|----------|
| commune | `mcp__daem0nmcp__commune` | `daem0nmcp_commune` |
| consult | `mcp__daem0nmcp__consult` | `daem0nmcp_consult` |
| inscribe | `mcp__daem0nmcp__inscribe` | `daem0nmcp_inscribe` |
| reflect | `mcp__daem0nmcp__reflect` | `daem0nmcp_reflect` |
| understand | `mcp__daem0nmcp__understand` | `daem0nmcp_understand` |
| govern | `mcp__daem0nmcp__govern` | `daem0nmcp_govern` |
| explore | `mcp__daem0nmcp__explore` | `daem0nmcp_explore` |
| maintain | `mcp__daem0nmcp__maintain` | `daem0nmcp_maintain` |

**Cognitive Tools:**

| MCP Tool | Claude Code | OpenCode |
|----------|-------------|----------|
| simulate_decision | `mcp__daem0nmcp__simulate_decision` | `daem0nmcp_simulate_decision` |
| evolve_rule | `mcp__daem0nmcp__evolve_rule` | `daem0nmcp_evolve_rule` |
| debate_internal | `mcp__daem0nmcp__debate_internal` | `daem0nmcp_debate_internal` |

**Format pattern:**

| Client | Format | Separator |
|--------|--------|-----------|
| Claude Code | `mcp__servername__toolname` | Double underscore (`__`) |
| OpenCode | `servername_toolname` | Single underscore (`_`) |

## Usage Examples

### Store a Memory
```python
inscribe(
    action="remember",
    category="decision",  # decision, pattern, warning, or learning
    content="Use JWT tokens instead of sessions",
    rationale="Need stateless auth for horizontal scaling",
    tags=["auth", "architecture"],
    file_path="src/auth/jwt.py"  # optional file association
)
```

### Retrieve Memories
```python
consult(action="recall", topic="authentication")
# Returns: decisions, patterns, warnings, learnings about auth
# Sorted by: semantic relevance x recency x importance

consult(action="recall_file", file_path="src/auth/jwt.py")
# Returns: all memories linked to this file

consult(action="recall_entity", entity_name="UserService")
# Returns: all memories mentioning the entity

consult(action="recall", topic="auth", condensed=True)
# Condensed: 50-75% fewer tokens, content truncated to 150 chars
```

### Create Rules
```python
govern(
    action="add_rule",
    trigger="adding new API endpoint",
    must_do=["Add rate limiting", "Write integration test"],
    must_not=["Use synchronous database calls"],
    ask_first=["Is this a breaking change?"]
)
```

### Track Outcomes
```python
reflect(action="outcome", memory_id=42, outcome_text="JWT auth works great", worked=True)
reflect(action="outcome", memory_id=43, outcome_text="Caching caused stale data", worked=False)
# Failed decisions get 1.5x boost in future recalls
```

### Session Start
```python
commune(action="briefing", focus_areas=["authentication", "API"])
# Returns: stats, recent decisions, warnings, failed approaches,
# git changes, plus pre-fetched context for focus areas
```

### Active Context (Working Memory)
```python
inscribe(action="activate", memory_id=42, reason="Working on auth refactor",
         priority=10, expires_in_hours=8)
# Memory stays in always-hot context, auto-injected into briefings
# Max 10 items, auto-expires, duplicate prevention

commune(action="active_context")  # View all hot memories
inscribe(action="deactivate", memory_id=42)  # Remove
inscribe(action="clear_active")  # Clear all
```

### Cognitive Tools
```python
# Temporal Scrying: What would I decide differently today?
simulate_decision(decision_id=42)

# Rule Entropy: Which rules have grown stale?
evolve_rule(rule_id=5)       # Single rule
evolve_rule()                 # Batch: all enabled rules

# Adversarial Council: Evidence-grounded debate
debate_internal(
    topic="Database choice for sessions",
    advocate_position="Use Redis",
    challenger_position="Use PostgreSQL"
)
```

### Import External Docs
```python
inscribe(action="ingest", url="https://stripe.com/docs/api/charges", topic="stripe")
# Later: consult(action="recall", topic="stripe") to retrieve
```

## AI Agent Protocol

The recommended workflow for AI agents:

```
SESSION START
    +-> commune(action="briefing")

BEFORE CHANGES
    +-> consult(action="preflight", description="what you're doing")
    +-> consult(action="recall_file", file_path="path/to/file.py")

AFTER DECISIONS
    +-> inscribe(action="remember", category=..., content=..., rationale=..., file_path=...)

AFTER IMPLEMENTATION
    +-> reflect(action="outcome", memory_id=..., outcome_text=..., worked=...)
```

See `Summon_Daem0n.md` for the complete protocol (with ritual theme for fun).

## Claude Code Integration

### Automated Hook Installation (Recommended)

```bash
python -m daem0nmcp.cli install-claude-hooks
```

This registers 5 hook modules in `~/.claude/settings.json`:

| Event | Hook | Purpose |
|-------|------|---------|
| `SessionStart` | `session_start` | Auto-briefing summary |
| `PreToolUse` (Edit/Write/NotebookEdit) | `pre_edit` | Preflight enforcement + file memory recall |
| `PreToolUse` (Bash) | `pre_bash` | Rule enforcement on commands |
| `PostToolUse` (Edit/Write) | `post_edit` | Suggest remembrance for significant changes |
| `Stop`/`SubagentStop` | `stop` | Auto-capture decisions from conversation |

To remove: `python -m daem0nmcp.cli uninstall-claude-hooks`

### Manual Hooks (Legacy)

Add to `.claude/settings.json`:
```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write|NotebookEdit",
      "hooks": [{
        "type": "command",
        "command": "python3 \"$HOME/Daem0nMCP/hooks/daem0n_pre_edit_hook.py\""
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "python3 \"$HOME/Daem0nMCP/hooks/daem0n_post_edit_hook.py\""
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "python3 \"$HOME/Daem0nMCP/hooks/daem0n_stop_hook.py\""
      }]
    }]
  }
}
```

### Protocol Skill

A Claude Code skill is included at `.claude/skills/daem0nmcp-protocol/SKILL.md` that enforces the memory protocol automatically.

## OpenCode Integration

OpenCode connects to Daem0n-MCP via the same MCP server. No server changes required -- the daemon serves all clients equally.

### Configuration

Create `opencode.json` at your project root:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "daem0nmcp": {
      "type": "local",
      "command": ["python", "-m", "daem0nmcp"],
      "enabled": true,
      "environment": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

For Windows (where HTTP transport is required), use:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "daem0nmcp": {
      "type": "remote",
      "url": "http://localhost:9876/mcp",
      "enabled": true
    }
  }
}
```

### System Instructions

OpenCode reads `AGENTS.md` from the project root for system prompt injection. The Sacred Covenant protocol is included in `AGENTS.md` with OpenCode-compatible tool names.

If both `AGENTS.md` and `CLAUDE.md` exist in a project, OpenCode uses only `AGENTS.md`.

### Tool Names

OpenCode uses a different tool name format than Claude Code:

| Client | Format | Example |
|--------|--------|---------|
| Claude Code | `mcp__servername__toolname` | `mcp__daem0nmcp__commune` |
| OpenCode | `servername_toolname` | `daem0nmcp_commune` |

Both formats resolve to the same MCP server tools. Use the format matching your client. See the [Tool Names by Client](#tool-names-by-client) table in the Workflow Tools section for the complete mapping.

## How It Works

### Hybrid Search (BM25 + Vector + RRF)
- **BM25** for keyword matching with term saturation and length normalization
- **ModernBERT** vector embeddings (256-dim, asymmetric encoding) for deep semantic understanding
- **Reciprocal Rank Fusion** combines both with configurable weights
- "blocking database calls" matches memories about "synchronous queries"

### Auto-Zoom Retrieval Routing
Query-aware dispatch classifies complexity and routes to the optimal strategy:
- Simple queries → vector-only (fast path)
- Medium queries → hybrid BM25+vector
- Complex queries → GraphRAG multi-hop with community summaries

### Memory Decay
```
weight = e^(-lambda*t) where lambda = ln(2)/half_life_days
```
Default half-life is 30 days. Patterns and warnings are permanent (no decay).

### Conflict Detection
When storing a new memory, it's compared against recent memories:
- If similar content failed before → warning about the failure
- If it matches an existing warning → warning surfaced
- If highly similar content exists → potential duplicate flagged

### Failed Decision Boosting
Memories with `worked=False` get a 1.5x relevance boost in recalls.
Warnings get a 1.2x boost. Past mistakes surface prominently.

### Background Dreaming
During idle periods, the daemon re-evaluates failed decisions against current evidence. `FailedDecisionReview` strategy finds `worked=False` decisions, recalls current evidence, and persists actionable insights as `learning` memories. Yields cooperatively when the user returns.

## Data Storage

Each project gets isolated storage at:
```
<project_root>/.daem0nmcp/storage/daem0nmcp.db
```

## Configuration

All settings are configurable via environment variables with `DAEM0NMCP_` prefix.

### Core Settings

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_PROJECT_ROOT` | `.` | Project root path |
| `DAEM0NMCP_STORAGE_PATH` | auto | Override storage location |
| `DAEM0NMCP_LOG_LEVEL` | `INFO` | Logging level |
| `DAEM0NMCP_QDRANT_URL` | `None` | Remote Qdrant URL (overrides local) |

### Embedding Model (v6.6.6+)

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_EMBEDDING_MODEL` | `nomic-ai/modernbert-embed-base` | Model name |
| `DAEM0NMCP_EMBEDDING_DIMENSION` | `256` | Matryoshka truncation dimension |
| `DAEM0NMCP_EMBEDDING_BACKEND` | auto-detected | `onnx` or `torch` |
| `DAEM0NMCP_EMBEDDING_QUERY_PREFIX` | `search_query: ` | Prefix for query encoding |
| `DAEM0NMCP_EMBEDDING_DOCUMENT_PREFIX` | `search_document: ` | Prefix for document encoding |

### Search Tuning

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_HYBRID_VECTOR_WEIGHT` | `0.3` | Vector weight in hybrid search (0.0-1.0) |
| `DAEM0NMCP_BM25_K1` | `1.5` | BM25 term frequency saturation |
| `DAEM0NMCP_BM25_B` | `0.75` | BM25 document length normalization |
| `DAEM0NMCP_RRF_K` | `60` | RRF fusion dampening constant |
| `DAEM0NMCP_SEARCH_DIVERSITY_MAX_PER_FILE` | `3` | Max results from same file |

### Auto-Zoom Routing

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_AUTO_ZOOM_ENABLED` | `false` | Master switch for query-aware routing |
| `DAEM0NMCP_AUTO_ZOOM_SHADOW` | `true` | Log classifications without routing |
| `DAEM0NMCP_AUTO_ZOOM_CONFIDENCE_THRESHOLD` | `0.25` | Below this → hybrid fallback |
| `DAEM0NMCP_AUTO_ZOOM_GRAPH_EXPANSION_DEPTH` | `2` | Multi-hop depth for complex queries |

### Background Dreaming

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_DREAM_ENABLED` | `true` | Master switch for dreaming |
| `DAEM0NMCP_DREAM_IDLE_TIMEOUT` | `60.0` | Seconds of idle before dreaming starts |
| `DAEM0NMCP_DREAM_MAX_DECISIONS_PER_SESSION` | `5` | Max failed decisions to re-evaluate |
| `DAEM0NMCP_DREAM_MIN_DECISION_AGE_HOURS` | `1` | Min age before re-evaluation eligible |

### Cognitive Tools

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_COGNITIVE_DEBATE_MAX_ROUNDS` | `5` | Max rounds for adversarial council |
| `DAEM0NMCP_COGNITIVE_EVOLVE_MAX_RULES` | `10` | Max rules to analyze for staleness |
| `DAEM0NMCP_COGNITIVE_STALENESS_AGE_WEIGHT` | `0.3` | Time-based decay weight |

### Recall Planner

| Variable | Default | Description |
|----------|---------|-------------|
| `DAEM0NMCP_SURPRISE_K_NEAREST` | `5` | Neighbors for surprise calculation |
| `DAEM0NMCP_SURPRISE_BOOST_THRESHOLD` | `0.7` | Boost threshold (0.0-1.0) |
| `DAEM0NMCP_RECALL_SIMPLE_MAX_MEMORIES` | `5` | Max memories for simple queries |
| `DAEM0NMCP_RECALL_MEDIUM_MAX_MEMORIES` | `10` | Max memories for medium queries |
| `DAEM0NMCP_RECALL_COMPLEX_MAX_MEMORIES` | `20` | Max memories for complex queries |
| `DAEM0NMCP_FACT_PROMOTION_THRESHOLD` | `3` | Outcomes to promote to fact |

See `Summon_Daem0n.md` for the complete configuration reference (~50 settings).

## Architecture

```
daem0nmcp/
├── server.py            # MCP server with 8 workflow + 3 cognitive tools (FastMCP)
├── mcp_instance.py      # FastMCP instance creation
├── config.py            # Pydantic settings (~50 configurable options)
├── memory.py            # Memory storage & semantic retrieval
├── rules.py             # Rule engine with BM25 matching
├── similarity.py        # TF-IDF index, decay, conflict detection
├── vectors.py           # ModernBERT embeddings (ONNX/torch, asymmetric encoding)
├── bm25_index.py        # BM25 Okapi keyword retrieval
├── fusion.py            # Reciprocal Rank Fusion for hybrid search
├── surprise.py          # Titans-inspired novelty detection
├── recall_planner.py    # TiMem-style complexity classification
├── retrieval_router.py  # Auto-Zoom query-aware search dispatch
├── query_classifier.py  # Exemplar-based query complexity classification
├── qdrant_store.py      # Qdrant vector database backend
├── active_context.py    # MemGPT-style always-hot working memory
├── entity_extractor.py  # Entity extraction from memory content
├── entity_manager.py    # Entity lifecycle management
├── communities.py       # Leiden community detection & summaries
├── context_triggers.py  # Auto-recall trigger system
├── context_manager.py   # Multi-project context management
├── covenant.py          # Sacred Covenant enforcement & preflight tokens
├── database.py          # SQLite async database
├── models.py            # 10+ tables: memories, rules, relationships, etc.
├── enforcement.py       # Pre-commit enforcement & session tracking
├── hooks.py             # Git hook templates & installation
├── cli.py               # Command-line interface
├── workflows/           # 8 consolidated workflow tools
│   ├── commune.py       # Session start & status
│   ├── consult.py       # Pre-action intelligence
│   ├── inscribe.py      # Memory writing & linking
│   ├── reflect.py       # Outcomes & verification
│   ├── understand.py    # Code comprehension
│   ├── govern.py        # Rules & triggers
│   ├── explore.py       # Graph & discovery
│   └── maintain.py      # Housekeeping & federation
├── tools/               # MCP tool registrations
│   ├── workflows.py     # 8 workflow tool definitions
│   ├── cognitive_tools.py # simulate_decision, evolve_rule, debate_internal
│   ├── memory.py        # Legacy memory tools (deprecated)
│   ├── briefing.py      # Legacy briefing tools (deprecated)
│   ├── code_tools.py    # Legacy code tools (deprecated)
│   ├── context_tools.py # Legacy context tools (deprecated)
│   ├── entity_tools.py  # Legacy entity tools (deprecated)
│   ├── graph_tools.py   # Legacy graph tools (deprecated)
│   ├── rules.py         # Legacy rule tools (deprecated)
│   ├── temporal.py      # Legacy temporal tools (deprecated)
│   ├── verification.py  # Legacy verification tools (deprecated)
│   ├── federation.py    # Legacy federation tools (deprecated)
│   ├── maintenance.py   # Legacy maintenance tools (deprecated)
│   └── agency_tools.py  # Legacy agency tools (deprecated)
├── cognitive/           # Cognitive tool implementations
│   ├── simulate.py      # Temporal scrying (decision replay)
│   ├── evolve.py        # Rule entropy analysis
│   └── debate.py        # Adversarial council
├── dreaming/            # Background dreaming system
│   ├── scheduler.py     # IdleDreamScheduler (idle detection + dispatch)
│   ├── strategies.py    # FailedDecisionReview strategy
│   └── persistence.py   # Dream session/result models & persistence
├── claude_hooks/        # Claude Code native hooks
│   ├── install.py       # install/uninstall-claude-hooks CLI
│   ├── session_start.py # Auto-briefing at session dawn
│   ├── pre_edit.py      # Preflight enforcement + file recall
│   ├── pre_bash.py      # Rule enforcement on commands
│   ├── post_edit.py     # Significance detection
│   ├── stop.py          # Auto-capture decisions
│   └── _client.py       # Hook helper utilities
├── compression/         # LLMLingua-2 context compression
├── graph/               # Knowledge graph (NetworkX + Leiden)
├── reflexion/           # Metacognitive architecture (LangGraph)
├── agency/              # Dynamic agency (E2B sandboxing)
├── transforms/          # FastMCP 3.0 middleware
│   └── covenant.py      # CovenantMiddleware & CovenantTransform
├── ui/                  # MCP Apps visual interfaces (D3.js)
├── channels/            # Notification channels (desktop, log, editor-poll)
├── migrations/          # Database schema & embedding migrations
├── code_indexer.py      # Code understanding via tree-sitter
├── watcher.py           # Proactive file watcher daemon
├── tracing.py           # OpenTelemetry integration (optional)
├── prompt_templates.py  # AutoPDL-inspired modular prompts
└── tool_search.py       # Dynamic tool discovery index

.claude/
└── skills/
    └── daem0nmcp-protocol/
        └── SKILL.md       # Protocol enforcement skill

.opencode/
├── commands/
│   ├── commune.md       # /commune slash command
│   ├── counsel.md       # /counsel slash command
│   ├── inscribe.md      # /inscribe slash command
│   └── recall.md        # /recall slash command
└── plugins/
    └── daem0n.ts        # Covenant enforcement plugin

Summon_Daem0n.md              # Claude Code installation grimoire
Summon_Daem0n_OpenCode.md     # OpenCode installation grimoire
Banish_Daem0n.md              # Uninstallation instructions (both clients)
start_server.py               # HTTP server launcher (streamable-http transport)
```

## CLI Commands

```bash
# Session briefing/statistics
python -m daem0nmcp.cli briefing

# Index code entities
python -m daem0nmcp.cli index [--path PATH] [--patterns **/*.py **/*.ts ...]

# Scan for TODO/FIXME/HACK comments
python -m daem0nmcp.cli scan-todos [--auto-remember] [--path PATH]

# Check a file against memories and rules
python -m daem0nmcp.cli check <filepath>

# Run database migrations (usually automatic)
python -m daem0nmcp.cli migrate [--backfill-vectors]
```

### Hook & Enforcement Commands

```bash
# Install Claude Code hooks (user-level, all projects)
python -m daem0nmcp.cli install-claude-hooks [--dry-run]

# Remove Claude Code hooks
python -m daem0nmcp.cli uninstall-claude-hooks [--dry-run]

# Install OpenCode configuration (project-level)
python -m daem0nmcp.cli install-opencode [--dry-run] [--force]
# Creates: opencode.json, .opencode/ directories, .opencode/plugins/daem0n.ts
# AGENTS.md and command files are not auto-created

# Install git pre-commit hooks
python -m daem0nmcp.cli install-hooks [--force]

# Remove git pre-commit hooks
python -m daem0nmcp.cli uninstall-hooks

# Show pending decisions and blocking issues
python -m daem0nmcp.cli status

# Record outcome for a decision
python -m daem0nmcp.cli record-outcome <id> "<outcome>" --worked|--failed
```

All commands support `--json` for machine-readable output and `--project-path` to specify the project root.

## Upgrading

### 1. Update the Code

```bash
# If installed from source (recommended)
cd ~/Daem0nMCP && git pull && pip install -e .

```

### 2. Re-encode Embeddings (v6.6.6+ — REQUIRED for existing data)

The embedding model changed from `all-MiniLM-L6-v2` (384-dim) to `nomic-ai/modernbert-embed-base` (256-dim). Existing embeddings must be re-encoded:

```bash
python -m daem0nmcp.migrations.migrate_embedding_model --project-path /path/to/.daem0nmcp
```

Qdrant collections are auto-recreated with the correct dimension on first startup.

### 3. Install Claude Code Hooks

```bash
python -m daem0nmcp.cli install-claude-hooks
```

### 4. Restart Claude Code

After updating, restart Claude Code to load the new MCP tools.

### 4b. Update OpenCode Configuration (if using OpenCode)

```bash
python -m daem0nmcp.cli install-opencode --force
```

This regenerates `opencode.json` and the plugin to match the latest version.

### 5. Migrations Run Automatically

Database schema migrations are applied automatically when any MCP tool runs. No manual migration step required.

### 6. Index Your Codebase

```bash
python -m daem0nmcp.cli index
```

Supports Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Ruby, PHP via tree-sitter.

## Troubleshooting

### MCP Tools Not Available in Claude Session

**Symptom:** `claude mcp list` shows daem0nmcp connected, but Claude can't use `mcp__daem0nmcp__*` tools.

**Fixes:**

1. **Start server before Claude Code (Windows):**
   ```bash
   # Terminal 1: Start Daem0n server first
   python ~/Daem0nMCP/start_server.py --port 9876
   # Wait for "Uvicorn running on http://localhost:9876"

   # Terminal 2: Then start Claude Code
   claude
   ```

2. **Re-register the server:**
   ```bash
   claude mcp remove daem0nmcp -s user
   claude mcp add daem0nmcp http://localhost:9876/mcp -s user
   ```

### Hooks Not Firing

1. MCP server running: `curl http://localhost:9876/mcp` should respond
2. Hooks configured: check `~/.claude/settings.json` or `.claude/settings.json`
3. Project has `.daem0nmcp/` directory

### Communion/Counsel Errors

- `COMMUNION_REQUIRED` → Call `commune(action="briefing", project_path="...")` first
- `COUNSEL_REQUIRED` → Call `consult(action="preflight", description="...", project_path="...")` first

### OpenCode: Tools Not Found

**Symptom:** OpenCode reports "tool not found" when using `mcp__daem0nmcp__*` format.

**Fix:** OpenCode uses single-underscore format: `daem0nmcp_commune` (not `mcp__daem0nmcp__commune`). See [Tool Names by Client](#tool-names-by-client) for the full mapping.

### OpenCode: MCP Connection Timeout

**Symptom:** First tool call times out, but subsequent calls work.

**Fix:** The embedding model loads on first call (several seconds). Add `"timeout": 30000` to your opencode.json MCP config.

### OpenCode: Covenant Not Enforced

**Symptom:** No preflight warnings, no post-edit suggestions in OpenCode.

**Fix:**
1. Verify plugin exists: `ls .opencode/plugins/daem0n.ts`
2. Verify AGENTS.md contains the Sacred Covenant section
3. Check OpenCode logs for plugin errors

## Development

```bash
# Install in development mode
pip install -e .[dev]

# Run tests (500+ tests)
pytest tests/ -v --asyncio-mode=auto

# Run server directly (stdio)
python -m daem0nmcp.server

# Run HTTP server (Windows)
python start_server.py --port 9876
```

## Support

If Daem0nMCP has been useful to you, consider supporting its development:

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/vitruvianredux)

## Uninstallation

See `Banish_Daem0n.md` for complete removal instructions (covers both Claude Code and OpenCode), or quick version:

### Claude Code

```bash
python -m daem0nmcp.cli uninstall-claude-hooks
claude mcp remove daem0nmcp --scope user
pip uninstall daem0nmcp
rm -rf ~/Daem0nMCP
rm -rf .daem0nmcp/
```

### OpenCode

```bash
rm opencode.json
rm -rf .opencode/commands/ .opencode/plugins/daem0n.ts
pip uninstall daem0nmcp
rm -rf ~/Daem0nMCP
rm -rf .daem0nmcp/
```

---

```
    "The system learns from YOUR outcomes.
     Record them faithfully..."
                              ~ Daem0n
```

*Daem0nMCP v6.6.6: ModernBERT Deep Sight (256-dim Matryoshka, ONNX quantized, asymmetric encoding). 8 workflow tools with 59 actions + 3 cognitive tools (simulate_decision, evolve_rule, debate_internal). Background Dreaming, Auto-Zoom Retrieval Routing, Active Context, Visual Portals (MCP Apps), GraphRAG, bi-temporal knowledge, LLMLingua-2 compression. Claude Code native hooks + OpenCode integration (plugins, commands, covenant enforcement). 500+ tests. The daemon reaches beyond the veil.*
